PR feedback: rename symbols, remove codex stub, fix hook naming, update tests

- Rename scanFiles → scanFilesForSecrets in secrets-scan.ts
- Rename callbackCommand → hookCommand in command-tree.ts
- Remove codex-pre-tool-use command (out of scope)
- Remove PR-specific comments from command-tree.ts
- Rename agent-prompt-submit → claude-prompt-submit
- Rename agent-post-tool-use → claude-post-tool-use
- Consolidate duplicate hook.test.ts tests, assert description shown
- Update README.md via gen:docs

Author: kirill-knize-sonarsource

README.md

@@ -154,6 +154,7 @@ Revoke a user token
 sonar api post "/api/user_tokens/revoke" --data '{"name":"my-token"}'
 ```
 
+
 ---
 
 ### `sonar integrate`
@@ -180,7 +181,7 @@ Setup SonarQube integration for Claude Code. This will install secrets scanning
 
 | Option              | Type    | Required | Description                                                                 | Default |
 | ------------------- | ------- | -------- | --------------------------------------------------------------------------- | ------- |
-| `--project`, `-p`   | string  | No       | Project key                                                                 | -       |
+| `--project`, `-p`   | string  | No       | SonarCloud project key (overrides auto-detected project)                    | -       |
 | `--non-interactive` | boolean | No       | Non-interactive mode (no prompts)                                           | -       |
 | `--global`, `-g`    | boolean | No       | Install hooks and config globally to ~/.claude instead of project directory | -       |
 
@@ -391,6 +392,40 @@ Update sonar CLI to the latest version
 
 ---
 
+### `sonar hook`
+
+Internal callback handlers for agent and git hooks
+
+#### `sonar hook claude-pre-tool-use`
+
+PreToolUse handler: scan files for secrets before agent reads them
+
+---
+
+#### `sonar hook codex-pre-tool-use`
+
+PreToolUse handler for Codex: scan files for secrets before agent reads them
+
+---
+
+#### `sonar hook agent-prompt-submit`
+
+UserPromptSubmit handler: scan prompts for secrets before sending
+
+---
+
+#### `sonar hook agent-post-tool-use`
+
+PostToolUse handler: run SQAA analysis on modified files
+
+**Options:**
+
+| Option            | Type   | Required | Description            | Default |
+| ----------------- | ------ | -------- | ---------------------- | ------- |
+| `--project`, `-p` | string | No       | SonarCloud project key | -       |
+
+---
+
 ## Option Types
 
 - `string` — text value (e.g. `--server https://sonarcloud.io`)
@@ -425,7 +460,7 @@ Both are enabled by default and share the same opt-out toggle. To disable all da
 sonar config telemetry --disabled
 ```
 
-No personally identifiable information is transmitted. File paths in error reports are anonymized by replacing your home directory with `~`.
+No personally identifiable information is transmitted.
 
 ## Contributing
 

src/cli/command-tree.ts

@@ -232,36 +232,27 @@ COMMAND_TREE.command('self-update')
 
 // Hidden callback command — internal handlers for agent and git hooks.
 // Shell hook scripts call `sonar hook <event>` to delegate all business logic to TypeScript.
-export const callbackCommand = COMMAND_TREE.command('hook', { hidden: true })
-  .description('Internal callback handlers for agent and git hooks')
+export const hookCommand = COMMAND_TREE.command('hook', { hidden: true })
+  .description('Internal hook handlers for agent and git hooks')
   .enablePositionalOptions()
   .anonymousAction(function (this: Command) {
     this.outputHelp();
   });
 
-callbackCommand
+hookCommand
   .command('claude-pre-tool-use')
   .description('PreToolUse handler: scan files for secrets before agent reads them')
   .anonymousAction(() => claudePreToolUse());
 
-// codex-pre-tool-use reuses the same handler (same hook event, different agent name)
-callbackCommand
-  .command('codex-pre-tool-use')
-  .description('PreToolUse handler for Codex: scan files for secrets before agent reads them')
-  .anonymousAction(() => claudePreToolUse());
-
-// agent-prompt-submit and agent-post-tool-use are installed by `sonar integrate claude`.
-// They are implemented in subsequent PRs; stubs here ensure scripts don't fail with
-// "unknown command" on a CLI that only has CLI-244/245.
-callbackCommand
-  .command('agent-prompt-submit')
+hookCommand
+  .command('claude-prompt-submit')
   .description('UserPromptSubmit handler: scan prompts for secrets before sending')
   .anonymousAction(() => {
     return;
   });
 
-callbackCommand
-  .command('agent-post-tool-use')
+hookCommand
+  .command('claude-post-tool-use')
   .option('-p, --project <project>', 'SonarCloud project key')
   .description('PostToolUse handler: run SQAA analysis on modified files')
   .anonymousAction(() => {

src/cli/commands/_common/install/secrets.ts

@@ -217,3 +217,13 @@ function cleanupOldVersionBinaries(binDir: string, currentBinaryName: string): v
 export function buildLocalBinaryName(platformInfo: PlatformInfo): string {
   return `sonar-secrets-${SONAR_SECRETS_VERSION}${buildPlatformSuffix(platformInfo)}`;
 }
+
+/**
+ * Returns the path to the installed sonar-secrets binary, or null if not present.
+ * Never downloads — use this where silent operation is required (e.g. hook handlers).
+ */
+export function resolveSecretsBinaryPath(): string | null {
+  const platform = detectPlatform();
+  const binaryPath = join(BIN_DIR, buildLocalBinaryName(platform));
+  return existsSync(binaryPath) ? binaryPath : null;
+}

src/cli/commands/analyze/secrets.ts

@@ -45,32 +45,57 @@ const BINARY_AUTH_TOKEN_ENV = 'SONAR_SECRETS_TOKEN';
 const SCAN_TIMEOUT_MS = 30000;
 const STDIN_READ_TIMEOUT_MS = 5000;
 
+export const EXIT_CODE_SECRETS_FOUND = 51;
+
+/**
+ * Run sonar-secrets binary on the given files. Returns the full spawn result.
+ * Kills the child process on timeout.
+ */
+export async function runSecretsBinary(
+  binaryPath: string,
+  files: string[],
+  auth: ResolvedAuth,
+): Promise<SpawnResult> {
+  let killChild: (() => void) | undefined;
+  let timeoutId: ReturnType<typeof setTimeout> | undefined;
+  try {
+    return await Promise.race([
+      spawnProcess(binaryPath, ['--non-interactive', ...files], {
+        stdin: 'pipe',
+        stdout: 'pipe',
+        stderr: 'pipe',
+        env: { [BINARY_AUTH_URL_ENV]: auth.serverUrl, [BINARY_AUTH_TOKEN_ENV]: auth.token },
+        onSpawn: (kill) => {
+          killChild = kill;
+        },
+      }),
+      new Promise<never>((_, reject) => {
+        timeoutId = setTimeout(() => {
+          killChild?.();
+          reject(new Error(`Scan timed out after ${SCAN_TIMEOUT_MS}ms`));
+        }, SCAN_TIMEOUT_MS);
+      }),
+    ]);
+  } finally {
+    clearTimeout(timeoutId);
+  }
+}
+
 async function handleCheckCommand(
   options: AnalyzeSecretsOptions,
   auth: ResolvedAuth,
 ): Promise<void> {
   validateScanOptions(options);
   const binaryPath = await installSecretsBinary();
-  const { authUrl, authToken } = setupScanEnvironment(binaryPath, auth);
   const scanStartTime = Date.now();
 
   if (options.stdin) {
-    await performStdinScan(binaryPath, authUrl, authToken, scanStartTime);
+    await performStdinScan(binaryPath, auth, scanStartTime);
   } else {
-    await performPathsScan(binaryPath, options.paths ?? [], authUrl, authToken, scanStartTime);
+    await performPathsScan(binaryPath, options.paths ?? [], auth, scanStartTime);
   }
 }
 
-interface ScanEnvironment {
-  binaryPath: string;
-  authUrl?: string;
-  authToken?: string;
-}
-
-function setupScanEnvironment(binaryPath: string, auth: ResolvedAuth): ScanEnvironment {
-  return { binaryPath, authUrl: auth.serverUrl, authToken: auth.token };
-}
-
 function validateScanOptions(options: { paths?: string[]; stdin?: boolean }): void {
   const hasPaths = (options.paths?.length ?? 0) > 0;
   if (!hasPaths && !options.stdin) {
@@ -84,11 +109,10 @@ function validateScanOptions(options: { paths?: string[]; stdin?: boolean }): vo
 
 async function performStdinScan(
   binaryPath: string,
-  authUrl: string | undefined,
-  authToken: string | undefined,
+  auth: ResolvedAuth,
   scanStartTime: number,
 ): Promise<void> {
-  const result = await runScanFromStdin(binaryPath, authUrl, authToken);
+  const result = await runScanFromStdin(binaryPath, auth);
   const scanDurationMs = Date.now() - scanStartTime;
 
   const exitCode = result.exitCode ?? 1;
@@ -102,8 +126,7 @@ async function performStdinScan(
 async function performPathsScan(
   binaryPath: string,
   paths: string[],
-  authUrl: string | undefined,
-  authToken: string | undefined,
+  auth: ResolvedAuth,
   scanStartTime: number,
 ): Promise<void> {
   if (paths.length === 0) {
@@ -116,7 +139,7 @@ async function performPathsScan(
     }
   }
 
-  const result = await runScan(binaryPath, paths, authUrl, authToken);
+  const result = await runSecretsBinary(binaryPath, paths, auth);
   const scanDurationMs = Date.now() - scanStartTime;
 
   const exitCode = result.exitCode ?? 1;
@@ -127,41 +150,7 @@ async function performPathsScan(
   }
 }
 
-async function runScan(
-  binaryPath: string,
-  paths: string[],
-  authUrl: string | undefined,
-  authToken: string | undefined,
-): Promise<SpawnResult> {
-  let timeoutId: ReturnType<typeof setTimeout> | undefined;
-  try {
-    return await Promise.race([
-      spawnProcess(binaryPath, ['--non-interactive', ...paths], {
-        stdin: 'pipe',
-        stdout: 'pipe',
-        stderr: 'pipe',
-        env: {
-          ...(authUrl && authToken
-            ? { [BINARY_AUTH_URL_ENV]: authUrl, [BINARY_AUTH_TOKEN_ENV]: authToken }
-            : {}),
-        },
-      }),
-      new Promise<never>((_resolve, reject) => {
-        timeoutId = setTimeout(() => {
-          reject(new Error(`Scan timed out after ${SCAN_TIMEOUT_MS}ms`));
-        }, SCAN_TIMEOUT_MS);
-      }),
-    ]);
-  } finally {
-    clearTimeout(timeoutId);
-  }
-}
-
-async function runScanFromStdin(
-  binaryPath: string,
-  authUrl: string | undefined,
-  authToken: string | undefined,
-): Promise<SpawnResult> {
+async function runScanFromStdin(binaryPath: string, auth: ResolvedAuth): Promise<SpawnResult> {
   const { writeFileSync, unlinkSync } = await import('node:fs');
   const { tmpdir } = await import('node:os');
   const pathModule = await import('node:path');
@@ -171,6 +160,7 @@ async function runScanFromStdin(
 
   const tempFile = pathJoin(tmpdir(), `sonar-secrets-scan-${Date.now()}.tmp`);
 
+  let killChild: (() => void) | undefined;
   let timeoutId: ReturnType<typeof setTimeout> | undefined;
   try {
     writeFileSync(tempFile, stdinData);
@@ -179,14 +169,14 @@ async function runScanFromStdin(
       spawnProcess(binaryPath, [tempFile], {
         stdout: 'pipe',
         stderr: 'pipe',
-        env: {
-          ...(authUrl && authToken
-            ? { [BINARY_AUTH_URL_ENV]: authUrl, [BINARY_AUTH_TOKEN_ENV]: authToken }
-            : {}),
+        env: { [BINARY_AUTH_URL_ENV]: auth.serverUrl, [BINARY_AUTH_TOKEN_ENV]: auth.token },
+        onSpawn: (kill) => {
+          killChild = kill;
         },
       }),
       new Promise<never>((_resolve, reject) => {
         timeoutId = setTimeout(() => {
+          killChild?.();
           reject(new Error(`Scan timed out after ${SCAN_TIMEOUT_MS}ms`));
         }, SCAN_TIMEOUT_MS);
       }),
@@ -270,8 +260,6 @@ function displayScanResults(scanResult: {
   });
 }
 
-const EXIT_CODE_SECRETS_FOUND = 51;
-
 function handleScanFailure(
   result: { exitCode: number | null; stderr: string; stdout: string },
   scanDurationMs: number,

src/cli/commands/hook/claude-pre-tool-use.ts

@@ -25,7 +25,8 @@ import { existsSync } from 'node:fs';
 import { resolveAuth } from '../../../lib/auth-resolver';
 import logger from '../../../lib/logger';
 import { readStdinJson } from './stdin';
-import { resolveSecretsBinaryPath, scanFiles, EXIT_CODE_SECRETS_FOUND } from './secrets-scan';
+import { resolveSecretsBinaryPath } from '../_common/install/secrets';
+import { EXIT_CODE_SECRETS_FOUND, runSecretsBinary } from '../analyze/secrets';
 
 interface PreToolUsePayload {
   tool_name?: string;
@@ -52,7 +53,8 @@ export async function claudePreToolUse(): Promise<void> {
   if (!binaryPath) return; // binary not installed — allow gracefully
 
   try {
-    const exitCode = await scanFiles(binaryPath, [filePath], auth);
+    const result = await runSecretsBinary(binaryPath, [filePath], auth);
+    const exitCode = result.exitCode ?? 1;
     if (exitCode === EXIT_CODE_SECRETS_FOUND) {
       process.stdout.write(
         JSON.stringify({