CLI-244 CLI-245 callback infrastructure

[kirill-knize-sonarsource]

No description provided.

[hashicorp-vault-sonar-prod]

CLI-244
CLI-245

[sonar-review-alpha]

Summary

This PR implements callback infrastructure for the Claude Code integration, specifically adding a PreToolUse secrets scanner that blocks file reads if hardcoded secrets are detected.

The main implementation (CLI-245) adds a sonar hook claude-pre-tool-use command that:

• Receives tool invocations from Claude via stdin (JSON)
• Scans files before they're read by the agent using the existing secrets binary
• Returns a deny decision if secrets are found, allowing the agent to block access
• Gracefully allows access if not authenticated, secrets binary missing, or input unparseable

Infrastructure additions (CLI-244) include:

• New sonar hook command group (hidden, for internal use)
• Stdin JSON payload handling utilities
• Stubs for future handlers (claude-prompt-submit, claude-post-tool-use)
• Documentation and test coverage

No changes to public-facing commands or existing behavior—purely additive infrastructure for AI agent integration.

What reviewers should know

Where to start:

1. src/cli/command-tree.ts — hook command registration (lines ~260-280)
2. src/cli/commands/hook/claude-pre-tool-use.ts — main PreToolUse handler logic
3. src/cli/commands/hook/stdin.ts — JSON payload parsing
4. tests/unit/hook-pre-tool-use.test.ts — unit test coverage of the scanner behavior

Key design decisions:

• Naming: Uses claude- prefix (not agent-) following Claude Code convention, applied consistently across all hook names
• Communication: Stdin/stdout JSON protocol—allows shell hooks to delegate to TypeScript for business logic
• Graceful degradation: Returns silently (no output) if auth unavailable, binary missing, file doesn't exist, or stdin unparseable; only denies access when secrets actually found
• Extensibility: Hook infrastructure is ready for additional handlers (prompt-submit stubs included)

Non-obvious details:

• The hook command group is { hidden: true } — not user-facing, only called by shell hook scripts
• Exit code protocol: secrets scanner uses exit code 99 to indicate findings (not a process failure)
• Test coverage includes unit tests for stdin parsing edge cases and integration tests for end-to-end behavior
• Documentation auto-generated from command-tree.ts (README.md note at end: "do not edit manually")

Watch for:

• Graceful fallback logic in claude-pre-tool-use.ts relies on try-catch; verify no secrets are exposed in error logs
• stdin.ts uses process.stdin directly; ensure it doesn't hang on unexpected input
• Integration with Claude agent's hook system is not shown here—verify the agent actually calls these hooks as documented

---

• Generate Walkthrough
• Generate Diagram

🗣️ Give feedback

[sophio-japharidze-sonarsource]

I love the direction this is going 😍

I left a few comments & suggestions, mainly about duplication of secrets scanning logic. I will test it now.

[sophio-japharidze-sonarsource]

Has this been agreed with PM & UX? I agree it's good not to fail the Claude process completely, but at the same time somehow we need to let the users know that their integration is broken, so that they don't have a false sense of security.

[sophio-japharidze-sonarsource]

Maybe it's possible to put something in Claude status bar at this point?

[sonar-review-alpha]

Conclusion: Clean implementation of the callback infrastructure. One minor logic duplication to fix before the pattern spreads to future handlers.

🗣️ Give feedback

[sonar-review-alpha]

Logic duplication: The Promise.race + setTimeout + finally clearTimeout pattern here is identical in structure to scanFiles in secrets-scan.ts (lines 57–80). Both do:

1. Race an operation against a timeout
2. Optionally trigger a cleanup (kill process / nothing for stdin)
3. Clear the timeout in finally

With more handlers coming, this will be copy-pasted again. Extract a shared utility, e.g.:

export async function withTimeout<T>(
  operation: Promise<T>,
  ms: number,
  onTimeout?: () => void,
): Promise<T> {
  let timeoutId: ReturnType<typeof setTimeout> | undefined;
  try {
    return await Promise.race([
      operation,
      new Promise<never>((_, reject) => {
        timeoutId = setTimeout(() => {
          onTimeout?.();
          reject(new Error(`Operation timed out after ${ms}ms`));
        }, ms);
      }),
    ]);
  } finally {
    clearTimeout(timeoutId);
  }
}

Then readRawStdin and scanFiles each become a single withTimeout(...) call.

• Mark as noise

[sonar-review-alpha]

Conclusion: Solid refactor that cleanly moves hook logic from brittle shell scripts into testable TypeScript. One bug needs fixing before merge — the README was regenerated before this commit's renames took effect, so it documents commands that don't exist or have wrong names.

🗣️ Give feedback

[sonar-review-alpha]

The README was regenerated before this commit's renames were applied, so three entries here are stale:

• sonar hook codex-pre-tool-use (this line) — removed from command-tree.ts in this commit, but still documented here
• sonar hook agent-prompt-submit (~line 413) — renamed to claude-prompt-submit; old name is registered nowhere
• sonar hook agent-post-tool-use (~line 419) — renamed to claude-post-tool-use; same issue

Run gen:docs again after the renames and re-commit before merge.

• Mark as noise

[sophio-japharidze-sonarsource]

Suggested change

	.description('Internal callback handlers for agent and git hooks')
	.description('Internal hook handlers for agent and git hooks')

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues
0 New dependency risks

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

See analysis details on SonarQube Cloud

[sonar-review-alpha]

LGTM! ✅

Two previously flagged issues remain open and unresolved — see the existing review threads for details.

🗣️ Give feedback