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 })
+export const hookCommand = COMMAND_TREE.command('hook', { hidden: true })
   .description('Internal callback 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/hook/claude-pre-tool-use.ts

@@ -25,7 +25,7 @@ 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, scanFilesForSecrets, EXIT_CODE_SECRETS_FOUND } from './secrets-scan';
 
 interface PreToolUsePayload {
   tool_name?: string;
@@ -52,7 +52,7 @@ export async function claudePreToolUse(): Promise<void> {
   if (!binaryPath) return; // binary not installed — allow gracefully
 
   try {
-    const exitCode = await scanFiles(binaryPath, [filePath], auth);
+    const exitCode = await scanFilesForSecrets(binaryPath, [filePath], auth);
     if (exitCode === EXIT_CODE_SECRETS_FOUND) {
       process.stdout.write(
         JSON.stringify({

src/cli/commands/hook/secrets-scan.ts

@@ -49,7 +49,7 @@ export function resolveSecretsBinaryPath(): string | null {
  * Run secrets scan on the given files. Returns the binary exit code.
  * May throw on timeout; other errors are surfaced as non-zero exit codes.
  */
-export async function scanFiles(
+export async function scanFilesForSecrets(
   binaryPath: string,
   files: string[],
   auth: ResolvedAuth,

src/cli/commands/integrate/claude/hook-templates.ts

@@ -45,17 +45,17 @@ export function getSecretPreToolTemplateWindows(): string {
 }
 
 export function getSecretPromptTemplateUnix(): string {
-  return unixTemplate('sonar hook agent-prompt-submit');
+  return unixTemplate('sonar hook claude-prompt-submit');
 }
 
 export function getSecretPromptTemplateWindows(): string {
-  return windowsTemplate('sonar hook agent-prompt-submit');
+  return windowsTemplate('sonar hook claude-prompt-submit');
 }
 
 export function getSqaaPostToolTemplateUnix(projectKey: string): string {
-  return unixTemplate(`sonar hook agent-post-tool-use --project ${projectKey}`);
+  return unixTemplate(`sonar hook claude-post-tool-use --project ${projectKey}`);
 }
 
 export function getSqaaPostToolTemplateWindows(projectKey: string): string {
-  return windowsTemplate(`sonar hook agent-post-tool-use --project ${projectKey}`);
+  return windowsTemplate(`sonar hook claude-post-tool-use --project ${projectKey}`);
 }

tests/integration/specs/hook/hook.test.ts

@@ -45,20 +45,11 @@ describe('sonar hook', () => {
   );
 
   it(
-    'sonar hook --help exits 0 and shows usage',
-    async () => {
-      const result = await harness.run('hook --help');
-      expect(result.exitCode).toBe(0);
-      expect(result.stdout).toContain('hook');
-    },
-    { timeout: 15000 },
-  );
-
-  it(
-    'sonar hook exits 0 (shows help)',
+    'sonar hook exits 0 and shows command description',
     async () => {
       const result = await harness.run('hook');
       expect(result.exitCode).toBe(0);
+      expect(result.stdout).toContain('Internal callback handlers for agent and git hooks');
     },
     { timeout: 15000 },
   );

tests/integration/specs/integrate/claude.test.ts

@@ -426,7 +426,7 @@ describe('integrate claude', () => {
     { timeout: 30000 },
   );
   it(
-    'prompt-secrets.sh uses correct subcommand (sonar hook agent-prompt-submit) after integration',
+    'prompt-secrets.sh uses correct subcommand (sonar hook claude-prompt-submit) after integration',
     async () => {
       const server = await harness
         .newFakeServer()
@@ -445,7 +445,7 @@ describe('integrate claude', () => {
       const promptScriptContent = harness.cwd
         .file('.claude', 'hooks', 'sonar-secrets', 'build-scripts', 'prompt-secrets.sh')
         .asText();
-      expect(promptScriptContent).toContain('sonar hook agent-prompt-submit');
+      expect(promptScriptContent).toContain('sonar hook claude-prompt-submit');
       expect(promptScriptContent).not.toContain('sonar analyze --file');
     },
     { timeout: 30000 },

tests/unit/hook-pre-tool-use.test.ts

@@ -51,7 +51,7 @@ describe('claudePreToolUse', () => {
     resolveSecretsBinaryPathSpy = spyOn(secretsScan, 'resolveSecretsBinaryPath').mockReturnValue(
       '/usr/bin/sonar-secrets',
     );
-    scanFilesSpy = spyOn(secretsScan, 'scanFiles').mockResolvedValue(0);
+    scanFilesSpy = spyOn(secretsScan, 'scanFilesForSecrets').mockResolvedValue(0);
     existsSyncSpy = spyOn(fs, 'existsSync').mockReturnValue(true);
   });
 

tests/unit/hook-templates.test.ts

@@ -60,7 +60,7 @@ describe('Secret Scanning Hook Templates', () => {
     const template = getSecretPromptTemplateUnix();
 
     expect(template.startsWith('#!/bin/bash')).toBe(true);
-    expect(template.includes('sonar hook agent-prompt-submit')).toBe(true);
+    expect(template.includes('sonar hook claude-prompt-submit')).toBe(true);
     expect(template.includes(UNIX_SONAR_COMMAND_GUARD)).toBe(true);
   });
 
@@ -74,7 +74,7 @@ describe('Secret Scanning Hook Templates', () => {
   it('UserPromptSubmit Windows hook: delegates to sonar hook', () => {
     const template = getSecretPromptTemplateWindows();
 
-    expect(template.includes('sonar hook agent-prompt-submit')).toBe(true);
+    expect(template.includes('sonar hook claude-prompt-submit')).toBe(true);
     expect(template.includes(WINDOWS_SONAR_COMMAND_GUARD)).toBe(true);
   });
 });
@@ -84,7 +84,7 @@ describe('SQAA PostToolUse Hook Templates', () => {
     const template = getSqaaPostToolTemplateUnix('my-project');
 
     expect(template.startsWith('#!/bin/bash')).toBe(true);
-    expect(template.includes('sonar hook agent-post-tool-use')).toBe(true);
+    expect(template.includes('sonar hook claude-post-tool-use')).toBe(true);
     expect(template.includes('--project my-project')).toBe(true);
     expect(template.includes(UNIX_SONAR_COMMAND_GUARD)).toBe(true);
   });
@@ -100,7 +100,7 @@ describe('SQAA PostToolUse Hook Templates', () => {
   it('PostTool Windows hook: delegates to sonar hook with project key', () => {
     const template = getSqaaPostToolTemplateWindows('my-project');
 
-    expect(template.includes('sonar hook agent-post-tool-use')).toBe(true);
+    expect(template.includes('sonar hook claude-post-tool-use')).toBe(true);
     expect(template.includes('--project my-project')).toBe(true);
     expect(template.includes(WINDOWS_SONAR_COMMAND_GUARD)).toBe(true);
   });
@@ -150,11 +150,11 @@ describe('Template Integrity', () => {
     });
   });
 
-  it('SQAA template routes to agent-post-tool-use, secrets templates route to other events', () => {
-    expect(getSqaaPostToolTemplateUnix('proj').includes('agent-post-tool-use')).toBe(true);
-    expect(getSqaaPostToolTemplateWindows('proj').includes('agent-post-tool-use')).toBe(true);
+  it('SQAA template routes to claude-post-tool-use, secrets templates route to other events', () => {
+    expect(getSqaaPostToolTemplateUnix('proj').includes('claude-post-tool-use')).toBe(true);
+    expect(getSqaaPostToolTemplateWindows('proj').includes('claude-post-tool-use')).toBe(true);
 
-    expect(getSecretPreToolTemplateUnix().includes('agent-post-tool-use')).toBe(false);
-    expect(getSecretPromptTemplateUnix().includes('agent-post-tool-use')).toBe(false);
+    expect(getSecretPreToolTemplateUnix().includes('claude-post-tool-use')).toBe(false);
+    expect(getSecretPromptTemplateUnix().includes('claude-post-tool-use')).toBe(false);
   });
 });

tests/unit/pgp-verification.test.ts

@@ -32,12 +32,12 @@ import type { PlatformInfo } from '../../src/lib/install-types.js';
 
 const PLATFORM: PlatformInfo = { os: 'linux', arch: 'x86-64', extension: '' };
 
-async function generateKeyPair() {
+async function generateKeyPair(): Promise<{ privateKey: string; publicKey: string }> {
   return openpgp.generateKey({
     type: 'rsa',
     rsaBits: 2048,
     userIDs: [{ name: 'Test', email: 'test@example.com' }],
-  });
+  }) as Promise<{ privateKey: string; publicKey: string }>;
 }
 
 async function sign(content: Buffer, armoredPrivateKey: string): Promise<string> {