Claude Code Hooks System 深度解析：让 AI 编码工具真正“听话“

AI工程化落地的前端/全栈工程师具备丰富的工具链集成与自动化流程设计经验。请基于 Claude Code Hooks System 的真实源码实现事件类型、配置格式、stdin/stdout 通信协议、exit code 语义、asyncRewake 等高级特性撰写一篇面向中高级工程师的深度技术博客。要求结构清晰背景动机 → 核心概念 → 生命周期架构图 → 配置格式详解 → 实战案例 → 高级特性 → 最佳实践图文并茂用 Mermaid 流程图展示 Hook 执行链路与生命周期代码驱动提供可直接运行的 Python/Shell 示例覆盖基础到进阶工程视角从用 Hooks 解决真实工程问题出发而非文档翻译深度适中基础用法exit code→ 中级matcher/if 过滤→ 高级asyncRewake/continueOnBlockClaude Code Hooks System 深度解析让 AI 编码工具真正听话一、为什么需要 HooksClaude Code 是一个强大的 AI 编码 Agent但在企业级工程实践中我们往往需要在 AI 行为的关键节点插入自定义逻辑安全合规在 AI 写文件前检查是否引入了硬编码密钥或 SQL 注入漏洞工程规范强制 AI 使用rg而非grep使用项目内的 lint 工具流程集成AI 完成一轮任务后自动触发测试、通知 Slack、更新 JIRA上下文注入每次会话开始时自动注入团队规范文档这正是Hooks System的设计初衷——在 Claude Code 执行生命周期的关键节点注入可编程的自定义行为。Hooks 于 v1.0.38 正式发布源于社区 issue #712 的大量需求反馈。二、核心概念速览概念说明Hook Event生命周期中的触发点如PreToolUse、StopHook Type实现方式command脚本或promptLLM 驱动Matcher过滤器指定 Hook 只对特定工具生效如BashExit Code脚本返回值决定 Claude Code 的后续行为additionalContextHook 向 Claude 注入的额外上下文信息asyncRewake异步执行后唤醒 Claude 继续处理结果三、Hook 生命周期全景图四、完整事件类型表Hook 事件触发时机典型用途SessionStart会话开始用户交互前注入团队规范、初始化环境UserPromptSubmit用户提交 Prompt 时捕获 git 基线、Prompt 安全检查PreToolUse工具执行前命令验证、安全拦截、参数改写PostToolUse工具执行后安全扫描、日志记录、结果增强Stop主 Agent 准备停止时运行测试、最终安全审查SubagentStart子 Agent 启动时子任务初始化SubagentStop子 Agent 停止时子任务结果收集PreCompact上下文压缩前保留关键信息到摘要SessionEnd会话结束时清理、状态持久化NotificationClaude 发送通知时转发到 Slack/钉钉WorktreeCreate创建 git worktree 时环境初始化WorktreeRemove删除 git worktree 时清理资源TeammateIdle团队 Agent 空闲时任务调度EnterWorktree切换 worktree 时上下文切换PermissionRequest工具权限请求时自动审批/拒绝PermissionDenied权限被拒绝后通知模型可重试TaskCreated任务通过 TaskCreate 创建时任务追踪ConfigChange配置文件变更时热重载响应五、配置格式详解Hooks 在settings.json中配置全局~/.claude/settings.json项目级.claude/settings.json{hooks:{PreToolUse:[{matcher:Bash,hooks:[{type:command,command:python3 /path/to/my_hook.py,timeout:30}]}],PostToolUse:[{matcher:Edit|Write|MultiEdit,hooks:[{type:command,command:python3 /path/to/security_check.py,if:Bash(git commit:*),asyncRewake:true,rewakeMessage:安全扫描完成请处理以下发现,rewakeSummary:发现安全问题}]}]}}关键配置字段字段类型说明matcherstring正则匹配工具名如Bash或Edit|Writeifstring权限规则语法过滤如Bash(git commit:*)timeoutnumber超时秒数asyncRewakeboolean异步执行后唤醒 ClauderewakeMessagestring唤醒时注入给 Claude 的消息continueOnBlockbooleanexit 2 时继续执行而非中断PostToolUse 专用onceboolean整个会话只执行一次argsstring[]exec 形式启动避免 shell 注入六、通信协议stdin / stdout / exit codeHook 脚本通过标准 I/O 与 Claude Code 通信Claude Code ──stdin(JSON)──▶ Hook 脚本 Claude Code ◀──stdout(JSON)── Hook 脚本 Claude Code ◀──stderr(text)── Hook 脚本错误信息 Claude Code ◀──exit code──── Hook 脚本控制流Exit Code 语义012Hook 脚本执行完毕exit code?✅ 继续执行stdout 作为 additionalContext⚠️ 错误stderr 显示给用户不传给 Claude 阻止stderr 作为工具结果反馈给 ClaudePreToolUse工具不执行Stop强制 Claude 继续stdin 输入结构以 PreToolUse 为例{session_id:abc123,hook_event_name:PreToolUse,tool_name:Bash,tool_use_id:toolu_xyz,tool_input:{command:grep -r password .},cwd:/home/user/myproject}stdout 输出结构{hookSpecificOutput:{hookEventName:PreToolUse,permissionDecision:allow,updatedInput:{command:rg password .}}}七、实战案例一Bash 命令规范检查器PreToolUse这是官方提供的参考实现强制 AI 使用rg替代grep#!/usr/bin/env python3PreToolUse HookBash 命令规范检查器importjson,re,sys _VALIDATION_RULES[(r^grep\b(?!.*\|),请使用 rgripgrep替代 grep性能更好),(r^find\s\S\s-name\b,请使用 rg --files -g pattern 替代 find -name),]defmain():input_datajson.load(sys.stdin)ifinput_data.get(tool_name)!Bash:sys.exit(0)# 非 Bash 工具直接放行commandinput_data.get(tool_input,{}).get(command,)issues[msgforpattern,msgin_VALIDATION_RULESifre.search(pattern,command)]ifissues:formsginissues:print(f•{msg},filesys.stderr)sys.exit(2)# 阻止执行stderr 反馈给 Claudeif__name____main__:main()配置方式{hooks:{PreToolUse:[{matcher:Bash,hooks:[{type:command,command:python3 /path/to/validator.py}]}]}}八、实战案例二安全审查插件多事件联动官方security-guidance插件展示了多事件协同的完整架构捕获 git stash SHA 作为基线正则扫描新写入代码asyncRewake分析 commit diffasyncRewakegit diff 基线 → LLM 审查UserPromptSubmit状态文件PostToolUse(Edit/Write)additionalContext 警告PostToolUse(Bash: git commit)唤醒 Claude 处理发现Stopexit 2 强制 Claude 修复hooks.json配置{hooks:{UserPromptSubmit:[{hooks:[{type:command,command:python3 security_hook.py}]}],PostToolUse:[{matcher:Edit|Write|MultiEdit|NotebookEdit,hooks:[{type:command,command:python3 security_hook.py}]},{matcher:Bash,hooks:[{type:command,command:python3 security_hook.py,if:Bash(git commit:*),asyncRewake:true,rewakeMessage:后台安全审查完成请处理以下发现,rewakeSummary:Commit 安全审查发现问题}]}],Stop:[{hooks:[{type:command,command:python3 security_hook.py,asyncRewake:true,rewakeMessage:最终安全审查反馈请处理后继续,rewakeSummary:后台安全审查发现问题}]}]}}九、高级特性详解9.1asyncRewake异步后台执行普通 Hook 是同步阻塞的——Claude 等待 Hook 完成才继续。asyncRewake: true让 Hook 在后台运行Claude 先返回响应Hook 完成后再唤醒 Claude 处理结果。适用场景耗时的 LLM 安全审查、CI 触发、慢速外部 API 调用。Claude 响应用户 ──▶ [用户看到结果] ↓ (后台) Hook 执行可能需要数秒 ↓ asyncRewake 唤醒 Claude ↓ Claude 处理 Hook 发现并继续 [13](#0-12) ### 9.2 continueOnBlock软性拦截 PostToolUse 默认情况下 exit 2 会中断当前 turn。设置 continueOnBlock: true 后拒绝原因会作为上下文反馈给 Claude但 turn 继续执行。 json { type: command, command: python3 lint_check.py, continueOnBlock: true }9.3if条件过滤精准触发使用权限规则语法过滤避免不必要的进程启动{if:Bash(git commit:*)}支持复合命令匹配ls git push和环境变量前缀FOObar git push。9.4argsexec 形式安全启动{type:command,command:/path/to/my_hook,args:[--mode,strict]}直接 exec 而非通过 shell路径中的特殊字符无需转义防止 shell 注入。9.5 Plugin 中的 HooksHooks 可以在 Plugin 的hooks.json中声明随插件自动加载支持${CLAUDE_PLUGIN_ROOT}变量引用插件目录{hooks:{SessionStart:[{hooks:[{type:command,command:bash \${CLAUDE_PLUGIN_ROOT}/setup.sh\,timeout:180}]}]}}十、Hook 输出向 Claude 注入上下文Hook 可以通过 stdout 输出 JSON 来影响 Claude 的行为importjson,sys# PostToolUse注入额外上下文output{hookSpecificOutput:{hookEventName:PostToolUse,additionalContext:⚠️ 检测到潜在的 SQL 注入风险请使用参数化查询}}print(json.dumps(output))sys.exit(0)# PostToolUse替换工具输出v2.1.121output{hookSpecificOutput:{hookEventName:PostToolUse,updatedToolOutput:已过滤敏感信息的工具输出...}}print(json.dumps(output))# SessionStart注入团队规范output{hookSpecificOutput:{hookEventName:SessionStart,additionalContext:团队规范所有 API 调用必须有错误处理禁止使用 any 类型}}print(json.dumps(output))十一、最佳实践性能原则用matcher和if精准过滤避免每次工具调用都启动进程耗时操作用asyncRewakeLLM 审查、网络请求不要阻塞主流程once: true用于初始化SessionStart 的环境检查只需执行一次可靠性原则exit code 要明确不要依赖默认行为显式sys.exit(0/1/2)JSON 解析要容错stdin 解析失败时 exit 0 而非崩溃设置合理 timeout防止 Hook 挂起阻塞整个会话安全原则用args替代 shell 拼接避免路径中特殊字符导致的注入Hook 不能访问终端v2.1.139不要依赖 TTY 交互大输出自动落盘超过 50K 字符的 Hook 输出会保存到磁盘并以文件引用形式注入 19 20十二、企业级应用场景速查场景Hook 事件实现思路禁止写入特定目录PreToolUse(Write)检查file_pathexit 2 阻止自动运行 lintPostToolUse(Edit/Write)调用 eslint/prettier结果注入 additionalContextgit commit 安全审查PostToolUse(Bash)asyncRewake分析 diff发现问题唤醒 Claude注入团队 CLAUDE.mdSessionStart读取团队规范文件输出 additionalContext任务完成通知Stop调用 Slack/钉钉 Webhook自动审批低风险操作PermissionRequest检查工具参数返回allow决策子 Agent 结果汇总SubagentStop收集agent_transcript_path中的结果总结Claude Code Hooks System 是一套设计精良的生命周期扩展机制核心设计哲学是简单协议stdin/stdout/exit code任何语言都能实现精准触发matcher if 条件最小化性能开销双向通信不仅能拦截还能注入上下文、改写输入、替换输出异步友好asyncRewake 让耗时操作不阻塞用户体验对于 AI 工程化落地而言Hooks 是将 Claude Code 从通用 AI 助手变成符合团队规范的工程伙伴的关键抓手。从一个简单的命令验证脚本开始逐步构建你的 Hook 生态让 AI 真正融入你的工程流程。