CLI-247 Post tool use

[kirill-knize-sonarsource]

No description provided.

[sonar-review-alpha]

Summary

CLI-247: PostToolUse Hook Handler Implementation

This PR implements the claude-post-tool-use hook command, which runs SonarQube Analysis As a Service (SQAA) on files after Claude Agent edits or writes them.

What changed:

• New handler in agent-post-tool-use.ts that receives tool use metadata via stdin (tool name + file path), invokes the SQAA API, and outputs results as structured JSON
• Command registration in command-tree.ts updated from a stub to call the handler; --project is now required
• 14 unit tests covering all code paths (success, auth failures, missing params, unparseable input, etc.)
• 2 integration tests against a fake SonarCloud server

Why: Enables the agent system to report code quality issues immediately after edits, providing real-time feedback to Claude as it modifies files. This is a building block in the callback infrastructure (follows CLI-244/245).

What reviewers should know

Where to start:

• Primary logic: src/cli/commands/hook/agent-post-tool-use.ts — read the handler end-to-end; it's the core of this PR
• Command wiring: src/cli/command-tree.ts lines 271–272 — shows how the CLI invokes the handler
• Test coverage: tests/unit/hook-post-tool-use.test.ts — exhaustive unit tests demonstrating all code paths and edge cases

Non-obvious design choices:

1. Non-blocking failure mode: The handler is designed to fail silently. It returns without output on auth failures, missing params, unparseable input, or SQAA errors. This is intentional — the hook should never block or crash the agent's tool flow.
2. Multiple guards before API call: Auth validation, project key presence, cloud-only check, orgKey presence, and file existence are all checked separately before attempting SQAA analysis. This defensive pattern prevents unnecessary API calls.
3. Output format: Successful analyses output a JSON structure with hookSpecificOutput.hookEventName = "PostToolUse" and additionalContext containing formatted analysis results (issues, errors, and a summary).
4. SonarCloud-only: Explicitly checks connectionType === 'cloud' and requires orgKey — this handler does not support on-premise SonarQube servers.

Gotchas:

• --project is now required (was optional in the stub). Callers must provide it or the hook will silently return.
• Only 'Edit' and 'Write' tools trigger analysis; other tools (Read, etc.) are skipped.
• The handler catches all exceptions from SQAA analysis and logs them at debug level — review integration tests to see how error scenarios are handled.

---

• Generate Walkthrough
• Generate Diagram

🗣️ Give feedback

[hashicorp-vault-sonar-prod]

CLI-247

[sonar-review-alpha]

Conclusion: The hook implementation itself is clean and the unit test suite is thorough. One logic duplication worth fixing, and the quality gate needs addressing before merge.

SonarQube Cloud status: Coverage on new code is at 69.1%, below the required 80% threshold. The integration test added in this PR targets an analyze sqaa edge case (unregistered project with --branch) rather than exercising the new agent-post-tool-use hook — so coverage of agent-post-tool-use.ts comes entirely from unit tests. See the reviewer guide above for details.

🗣️ Give feedback

[sonar-review-alpha]

Logic duplication: formatSqaaResult reimplements the same logic as displaySqaaResults in src/cli/commands/analyze/sqaa.ts (line 162). Both iterate over issues with the same [idx+1] message (line startLine) structure and handle the errors array the same way. They've already diverged: displaySqaaResults puts the rule on a separate Rule: X line, while this version inlines it as [rule].

If the output format needs to change (e.g. adding severity, effort, or a new field), both functions must be updated. Extract shared formatting logic — for example a buildSqaaIssueLines(issues, errors): string[] helper in a shared module — and have each caller apply its own output target on top.

• Mark as noise

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues
0 New dependency risks

Measures
0 Security Hotspots
86.4% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[sonar-review-alpha]

LGTM! ✅

The previously flagged logic duplication between formatSqaaResult (this file) and displaySqaaResults in src/cli/commands/analyze/sqaa.ts is still open — no shared helper has been extracted.

🗣️ Give feedback

[eray-felek-sonarsource]

Tested and LGTM