Claude Code 使用手册 · 第 7 章 Hooks 钩子

Claude Code 使用手册 · 第 7 章 Hooks 钩子

章节摘要:Hooks 是响应会话事件的自动化脚本——工具调用、会话启停、任务完成时自动执行,实现自动化、校验、权限管理与自定义工作流。共 31 个事件,分四组:Tool 组(工具前后)、Session 组(会话生命周期)、Task 组(任务与子代理)、Lifecycle 组(工作树)。五种 handler 类型:command(Shell 命令)、http(Webhook)、prompt(LLM 评估)、mcp_tool(直接调 MCP 工具)、agent(子代理评估)。协议:JSON 经 stdin 输入,exit 0 放行 / exit 2 阻断(阻断原因写 stderr);结果经 JSON stdout 返回(permissionDecision/block/updatedInput 等)。本章共 3 节。

解剖坐标

一句话主线:认识 31 个事件与四组分类 → 学会配置与 matcher → 掌握五种 handler → 用 exit-code 协议写出安全可靠的钩子。

学习目标

阅读完本章,你应当能够:

1. 说出 31 个事件按四组(Tool/Session/Task/Lifecycle)的归类,以及哪些事件可以阻断。
2. 说出五种 handler 类型各自的适用场景。
3. 写出 hooks 配置(EventName → matcher → handler),包括 if 参数条件过滤。
4. 背出 exit-code 协议(0/2/其他)与 JSON 输入输出结构,会写 PreToolUse 的 permissionDecision。
5. 说出 hooks 的常见踩坑(空白环境变量、stdin 占用、禁用开关)与安全最佳实践。

子章节导航

01 事件与配置结构

31 事件四组分类与可阻断性;配置位置(用户/项目/本地/插件/组件 frontmatter);matcher 模式与 if 参数条件;五种 handler 类型逐一说明。

02 示例脚本精读

命令校验(validate-bash 阻断危险命令)、安全扫描(security-scan 找硬编码密钥)、自动格式化(format-code)、提示词校验(validate-prompt)、智能 Stop 评估、上下文用量追踪(context-tracker 双钩配对)、Auto 模式权限种子脚本、学习进度记录(session-end 交互式日志)。

03 exit-code 协议与踩坑经验

exit 0/2/其他三态行为;JSON 输入输出字段;PreToolUse 权限决策(allow/deny/ask/defer 优先级);PostToolUse 的 block 与 continueOnBlock;调试方法(独立喂 JSON 测试);安全注意事项与常见坑(引号、路径、stderr 静默、Stop 死循环上限)。

前置知识与后续延伸

前置知识:第 2 章斜杠命令、第 6 章 MCP(mcp_tool 钩子直接调 MCP 工具)。

后续延伸:第 8 章插件(hooks/hooks.json 是插件四要素之一)、第 9 章检查点(PreCompact/PostCompact 事件)。