第 20 章Hooks 系统用 Shell 命令扩展 AI 行为

// entrypoints/sdk/coreSchemas.ts:355-383
export const HOOK_EVENTS = [
  'PreToolUse',         // 工具执行前
  'PostToolUse',        // 工具执行后
  'PostToolUseFailure', // 工具执行失败后
  'Notification',       // 通知发送时
  'UserPromptSubmit',   // 用户提交 prompt 时
  'SessionStart',       // 会话开始
  'SessionEnd',         // 会话结束
  'Stop',               // 模型即将结束回答
  'StopFailure',        // 因 API 错误结束 turn
  'SubagentStart',      // 子 Agent 启动
  'SubagentStop',       // 子 Agent 结束
  'PreCompact',         // 对话压缩前
  'PostCompact',        // 对话压缩后
  'PermissionRequest',  // 权限对话框显示时
  'PermissionDenied',   // auto mode 拒绝工具调用后
  'Setup',              // 仓库 setup（init/maintenance）
  'TeammateIdle',       // Teammate 即将空闲
  'TaskCreated',        // 任务创建时
  'TaskCompleted',      // 任务完成时
  'Elicitation',        // MCP 请求用户输入时
  'ElicitationResult',  // 用户响应 MCP elicitation 后
  'ConfigChange',       // 配置文件变更时
  'WorktreeCreate',     // 创建 worktree 时
  'WorktreeRemove',     // 删除 worktree 时
  'InstructionsLoaded', // 指令文件加载时
  'CwdChanged',         // 工作目录变更后
  'FileChanged',        // 被监视文件变更时
] as const

// schemas/hooks.ts:194-213
export const HookMatcherSchema = lazySchema(() =>
  z.object({
    matcher: z.string().optional()
      .describe('String pattern to match (e.g. tool names like "Write")'),
    hooks: z.array(HookCommandSchema())
      .describe('List of hooks to execute when the matcher matches'),
  }),
)

export const HooksSchema = lazySchema(() =>
  z.partialRecord(z.enum(HOOK_EVENTS), z.array(HookMatcherSchema())),
)

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'About to write file' | tee -a /tmp/audit.log"
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "npm test 2>&1 | tail -20"
          }
        ]
      }
    ]
  }
}

// schemas/hooks.ts:176-189
export const HookCommandSchema = lazySchema(() => {
  return z.discriminatedUnion('type', [
    BashCommandHookSchema,   // type: 'command' — Shell 命令
    PromptHookSchema,        // type: 'prompt'  — LLM 评估
    AgentHookSchema,         // type: 'agent'   — 多轮 Agent 验证
    HttpHookSchema,          // type: 'http'    — HTTP POST
  ])
})

// utils/hooks.ts:1346-1381
function matchesPattern(matchQuery: string, matcher: string): boolean {
  if (!matcher || matcher === '*') {
    return true  // 空或 * 匹配一切
  }
  // 纯字母数字 + 管道符 → 精确匹配或多值匹配
  if (/^[a-zA-Z0-9_|]+$/.test(matcher)) {
    if (matcher.includes('|')) {
      const patterns = matcher.split('|').map(p => normalizeLegacyToolName(p.trim()))
      return patterns.includes(matchQuery)
    }
    return matchQuery === normalizeLegacyToolName(matcher)
  }
  // 否则作为正则表达式
  try {
    const regex = new RegExp(matcher)
    if (regex.test(matchQuery)) return true
    // 兼容旧工具名
    for (const legacyName of getLegacyToolNames(matchQuery)) {
      if (regex.test(legacyName)) return true
    }
    return false
  } catch { return false }
}

// utils/hooks.ts:286-296
export function shouldSkipHookDueToTrust(): boolean {
  // 非交互模式（SDK）中，信任是隐式的
  const isInteractive = !getIsNonInteractiveSession()
  if (!isInteractive) {
    return false
  }
  // 交互模式下，所有 Hook 都需要 workspace trust
  const hasTrust = checkHasTrustDialogAccepted()
  return !hasTrust
}

// utils/hooks.ts:1492-1566（简化）
function getHooksConfig(appState, sessionId, hookEvent) {
  // 来源 1：Settings 快照（startup 时捕获）
  const hooks = [...(getHooksConfigFromSnapshot()?.[hookEvent] ?? [])]

  // 来源 2：注册的 Hook（SDK callback + Plugin native hooks）
  const registeredHooks = getRegisteredHooks()?.[hookEvent]
  if (registeredHooks) {
    for (const matcher of registeredHooks) {
      if (managedOnly && 'pluginRoot' in matcher) continue  // 受管模式跳过插件
      hooks.push(matcher)
    }
  }

  // 来源 3：Session 级 Hook（Agent/Skill frontmatter 注册的临时 Hook）
  if (!managedOnly && appState !== undefined) {
    const sessionHooks = getSessionHooks(appState, sessionId, hookEvent)
    // ... 合并 session hooks 和 function hooks
  }

  return hooks
}

// utils/hooks.ts:1453-1455
function hookDedupKey(m: MatchedHook, payload: string): string {
  return `${m.pluginRoot ?? m.skillRoot ?? ''}\0${payload}`
}

// query/stopHooks.ts:136-156（节选）
if (!isBareMode()) {
  if (!isEnvDefinedFalsy(process.env.CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION)) {
    void executePromptSuggestion(stopHookContext)
  }
  if (feature('EXTRACT_MEMORIES') && !toolUseContext.agentId && isExtractModeActive()) {
    void extractMemoriesModule!.executeExtractMemories(stopHookContext, ...)
  }
  if (!toolUseContext.agentId) {
    void executeAutoDream(stopHookContext, toolUseContext.appendSystemMessage)
  }
}

// query/stopHooks.ts:180-189（节选）
const generator = executeStopHooks(
  permissionMode,
  toolUseContext.abortController.signal,
  undefined,
  stopHookActive ?? false,
  toolUseContext.agentId,           // ← 有 agentId 就是 SubagentStop
  toolUseContext,
  [...messagesForQuery, ...assistantMessages],
  toolUseContext.agentType,
)

// hooks/notifs/useStartupNotification.ts:19-30（节选）
export function useStartupNotification(
  compute: () => Result | Promise<Result>,
): void {
  const { addNotification } = useNotifications()
  const hasRunRef = useRef(false)
  // ...
  useEffect(() => {
    if (getIsRemoteMode() || hasRunRef.current) return  // ← 两道守卫
    hasRunRef.current = true
    void Promise.resolve()
      .then(() => computeRef.current())
      .then(result => { /* 派发通知 */ })
      .catch(logError)
  }, [addNotification])
}

// utils/hooks.ts:790-791
const shellType = hook.shell ?? DEFAULT_HOOK_SHELL  // 默认 'bash'
const isPowerShell = shellType === 'powershell'

// utils/hooks.ts:958-984
if (shellType === 'powershell') {
  // PowerShell：显式 argv，不使用 shell option
  child = spawn(pwshPath, buildPowerShellArgs(finalCommand), {
    env: envVars, cwd: safeCwd, windowsHide: true,
  })
} else {
  // Bash：shell option 让 Node 用 shell 解析整个命令字符串
  // 注意：Windows 上显式使用 Git Bash，非 Windows 上 shell: true 实际使用 /bin/sh
  const shell = isWindows ? findGitBashPath() : true
  child = spawn(finalCommand, [], {
    env: envVars, cwd: safeCwd, shell, windowsHide: true,
  })
}

// utils/hooks.ts:882-926（简化）
const envVars: NodeJS.ProcessEnv = {
  ...subprocessEnv(),                      // 继承进程环境
  CLAUDE_PROJECT_DIR: toHookPath(projectDir), // 项目根目录
}

// Plugin/Skill Hook 额外变量
if (pluginRoot) {
  envVars.CLAUDE_PLUGIN_ROOT = toHookPath(pluginRoot)
  envVars.CLAUDE_PLUGIN_DATA = toHookPath(getPluginDataDir(pluginId))
}
// Plugin 配置项作为 env var 暴露
if (pluginOpts) {
  for (const [key, value] of Object.entries(pluginOpts)) {
    const envKey = key.replace(/[^A-Za-z0-9_]/g, '_').toUpperCase()
    envVars[`CLAUDE_PLUGIN_OPTION_${envKey}`] = String(value)
  }
}

// SessionStart/Setup/CwdChanged/FileChanged Hook 获得 CLAUDE_ENV_FILE
if (!isPowerShell && (hookEvent === 'SessionStart' || ...)) {
  envVars.CLAUDE_ENV_FILE = await getHookEnvFilePath(hookEvent, hookIndex)
}

┌──────────┐    stdin (JSON)     ┌──────────┐    stdout (JSON/text)    ┌──────────┐
│ Claude   │ ──────────────────> │   Hook   │ ───────────────────────> │ Claude   │
│ Code     │                    │  Process │                          │ Code     │
└──────────┘                    └──────────┘                          └──────────┘

// utils/hooks.ts:399-451（简化）
function parseHookOutput(stdout: string) {
  const trimmed = stdout.trim()
  if (!trimmed.startsWith('{')) {
    return { plainText: stdout }  // 不以 { 开头 → 纯文本
  }
  // 尝试解析为 JSON 并通过 Zod 验证
  const result = validateHookJson(trimmed)
  if ('json' in result) return result
  return { plainText: stdout, validationError: result.validationError }
}

// utils/hooks.ts:2648-2668
if (result.status === 2) {
  yield {
    blockingError: {
      blockingError: `[${hook.command}]: ${result.stderr || 'No stderr output'}`,
      command: hook.command,
    },
    outcome: 'blocking' as const,
    hook,
  }
  return
}

// types/hooks.ts:50-66（简化）
export const syncHookResponseSchema = lazySchema(() =>
  z.object({
    continue: z.boolean().optional(),       // 是否继续
    suppressOutput: z.boolean().optional(),  // 隐藏 stdout
    stopReason: z.string().optional(),       // continue=false 时的原因
    decision: z.enum(['approve', 'block']).optional(),  // 权限决策
    reason: z.string().optional(),           // 决策原因
    systemMessage: z.string().optional(),    // 警告消息
    hookSpecificOutput: z.union([            // 事件特定输出
      // PreToolUse: permissionDecision, updatedInput, additionalContext
      // PostToolUse: additionalContext, updatedMCPToolOutput
      // SessionStart: additionalContext, initialUserMessage, watchPaths
      // PermissionRequest: decision (allow/deny + updatedInput)
      // ...
    ]).optional(),
  }),
)

// utils/hooks.ts:995-1030（简化）
if ((hook.async || hook.asyncRewake) && !forceSyncExecution) {
  // 先写入 stdin
  child.stdin.write(jsonInput + '\n', 'utf8')
  child.stdin.end()
  // 后台化
  const backgrounded = executeInBackground({
    processId, hookId, shellCommand,
    asyncResponse: { async: true, asyncTimeout: hookTimeoutMs },
    hookEvent, hookName, command: hook.command,
    asyncRewake: hook.asyncRewake,
  })
  if (backgrounded) {
    return { stdout: '', stderr: '', output: '', status: 0, backgrounded: true }
  }
}

// utils/hooks.ts:1117-1143（简化）
if (!initialResponseChecked) {
  const firstLine = firstLineOf(stdout).trim()
  if (!firstLine.includes('}')) return  // 等待完整 JSON
  initialResponseChecked = true
  const parsed = jsonParse(firstLine)
  if (isAsyncHookJSONOutput(parsed) && !forceSyncExecution) {
    const backgrounded = executeInBackground({...})
    if (backgrounded) {
      shellCommandTransferred = true
      asyncResolve?.({ stdout, stderr, output, status: 0 })
    }
  }
}

// utils/hooks.ts:218-243（简化）
void shellCommand.result.then(async result => {
  await new Promise(resolve => setImmediate(resolve))  // 等 I/O 排空
  const stdout = await shellCommand.taskOutput.getStdout()
  const stderr = shellCommand.taskOutput.getStderr()
  shellCommand.cleanup()
  if (result.code === 2) {
    enqueuePendingNotification({
      value: wrapInSystemReminder(
        `Stop hook blocking error from command "${hookName}": ${stderr || stdout}`,
      ),
      mode: 'task-notification',
    })
  }
})

// utils/hooks/AsyncHookRegistry.ts:28
const pendingHooks = new Map<string, PendingAsyncHook>()

// utils/hooks/execPromptHook.ts:62-100（简化）
const response = await queryModelWithoutStreaming({
  messages: messagesToQuery,
  systemPrompt: asSystemPrompt([
    `You are evaluating a hook in Claude Code.
Your response must be a JSON object matching one of the following schemas:
1. If the condition is met, return: {"ok": true}
2. If the condition is not met, return: {"ok": false, "reason": "..."}`,
  ]),
  thinkingConfig: { type: 'disabled' as const },
  options: {
    model: hook.model ?? getSmallFastModel(),
    outputFormat: {
      type: 'json_schema',
      schema: {
        type: 'object',
        properties: { ok: { type: 'boolean' }, reason: { type: 'string' } },
        required: ['ok'],
        additionalProperties: false,
      },
    },
  },
})

// utils/hooks.ts:2826-2847
switch (result.permissionBehavior) {
  case 'deny':
    // deny 始终优先
    permissionBehavior = 'deny'
    break
  case 'ask':
    // ask 优先于 allow，但不优先于 deny
    if (permissionBehavior !== 'deny') {
      permissionBehavior = 'ask'
    }
    break
  case 'allow':
    // allow 只在无其他决策时生效
    if (!permissionBehavior) {
      permissionBehavior = 'allow'
    }
    break
  case 'passthrough':
    // passthrough 不设置权限行为
    break
}

// utils/hooks/hooksConfigSnapshot.ts:62-88

// 1. shouldAllowManagedHooksOnly()：只允许管理策略中的 Hook
export function shouldAllowManagedHooksOnly(): boolean {
  const policySettings = getSettingsForSource('policySettings')
  if (policySettings?.allowManagedHooksOnly === true) return true
  // 非管理设置的 disableAllHooks 被解读为"只保留管理 Hook"
  if (getSettings_DEPRECATED().disableAllHooks === true &&
      policySettings?.disableAllHooks !== true) {
    return true
  }
  return false
}

// 2. shouldDisableAllHooksIncludingManaged()：完全禁用所有 Hook
export function shouldDisableAllHooksIncludingManaged(): boolean {
  return getSettingsForSource('policySettings')?.disableAllHooks === true
}

// utils/hooks/hooksConfigSnapshot.ts:95-97
export function captureHooksConfigSnapshot(): void {
  initialHooksConfig = getHooksFromAllowedSources()
}

// utils/hooks/hooksConfigSnapshot.ts:104-112
export function updateHooksConfigSnapshot(): void {
  resetSettingsCache()  // 确保从磁盘读取最新设置
  initialHooksConfig = getHooksFromAllowedSources()
}

// hooks/toolPermission/handlers/interactiveHandler.ts:70（节选）
const { resolve: resolveOnce, isResolved, claim } = createResolveOnce(resolve)

// hooks/toolPermission/handlers/coordinatorHandler.ts:31-46（节选）
// 1. Try permission hooks first (fast, local)
const hookResult = await ctx.runHooks(permissionMode, suggestions, updatedInput)
if (hookResult) return hookResult

// 2. Try classifier (slow, inference -- bash only)
const classifierResult = feature('BASH_CLASSIFIER')
  ? await ctx.tryClassifier?.(params.pendingClassifierCheck, updatedInput)
  : null
if (classifierResult) return classifierResult

// 3. Neither resolved -- fall through to dialog below.

// hooks/toolPermission/handlers/swarmWorkerHandler.ts:49-57（节选）
// 先试 classifier 快路径 —— 能本地放行就不必跨进程
const classifierResult = feature('BASH_CLASSIFIER')
  ? await ctx.tryClassifier?.(params.pendingClassifierCheck, updatedInput)
  : null
if (classifierResult) return classifierResult
// 否则 createPermissionRequest + sendPermissionRequestViaMailbox + 等 leader 回信

// utils/hooks/registerFrontmatterHooks.ts:18-67（简化）
export function registerFrontmatterHooks(
  setAppState, sessionId, hooks, sourceName, isAgent = false,
): void {
  for (const event of HOOK_EVENTS) {
    const matchers = hooks[event]
    if (!matchers) continue

    // 关键：Agent 的 Stop hook 自动转换为 SubagentStop
    let targetEvent = event
    if (isAgent && event === 'Stop') {
      targetEvent = 'SubagentStop'
    }

    for (const matcherConfig of matchers) {
      for (const hook of matcherConfig.hooks) {
        addSessionHook(setAppState, sessionId, targetEvent, matcher, hook)
      }
    }
  }
}

// utils/hooks.ts:2036-2067
// Fast-path: all hooks are internal callbacks (sessionFileAccessHooks,
// attributionHooks). Measured: 6.01µs → ~1.8µs per PostToolUse hit (-70%).
if (matchingHooks.every(m => m.hook.type === 'callback' && m.hook.internal)) {
  for (const [i, { hook }] of matchingHooks.entries()) {
    if (hook.type === 'callback') {
      await hook.callback(hookInput, toolUseID, signal, i, context)
    }
  }
  return  // 跳过 telemetry、span、progress 等开销
}

// utils/hooks.ts:2124-2140
let jsonInputResult: { ok: true; value: string } | { ok: false; error: unknown } | undefined
function getJsonInput() {
  if (jsonInputResult !== undefined) return jsonInputResult
  try {
    return (jsonInputResult = { ok: true, value: jsonStringify(hookInput) })
  } catch (error) {
    return (jsonInputResult = { ok: false, error })
  }
}

// utils/hooks.ts:1582-1593
function hasHookForEvent(hookEvent, appState, sessionId): boolean {
  const snap = getHooksConfigFromSnapshot()?.[hookEvent]
  if (snap && snap.length > 0) return true
  const reg = getRegisteredHooks()?.[hookEvent]
  if (reg && reg.length > 0) return true
  if (appState?.sessionHooks.get(sessionId)?.hooks[hookEvent]) return true
  return false
}

// types/hooks.ts:28-40
export const promptRequestSchema = lazySchema(() =>
  z.object({
    prompt: z.string(),          // 请求 ID
    message: z.string(),         // 显示给用户的问题
    options: z.array(z.object({  // 选项列表
      key: z.string(),
      label: z.string(),
      description: z.string().optional(),
    })),
  }),
)