05-Hooks系统完整指南

05 Hooks系统完整指南 05 Hooks系统完整指南 Modified May 9 在脚本中检查文件路径： Code block Python Copy if '/articles/' not in file path: sys.exit(0) 不在目标目录，跳过 Q9: 环境变量怎么传递给Hook脚本？ Claude Code自动传递的环境变量： • CLAUDE PROJECT DIR 项目根目录的绝对路径（Claude Code启动目录） ⚠️ 注意：session id不是环境变量，而是通过stdin的JSON输入传递！ 使用方法： Code block Python Copy import os import json import sys 从环境变量获取项目目录 project dir = os.getenv('CLAUDE PROJECT DIR', os.getcwd()) 从stdin的JSON获取session id（不是环境变量！） input data = json.loads(sys.stdin.read()) session id = input data.get('session id', '') Q10: 如何临时禁用Hook？ 方法1：重命名配置文件 Code block Bash Copy mv .claude/settings.json .claude/settings.json.bak 方法2：注释掉Hook配置（JSON不支持注释，需要删除） 脚本问题 Q11: 如何读取Hook的输入？ Code block Python Copy import sys import json stdin读取JSON input data = json.loads(sys.stdin.read()) tool name = input data.get('tool name') Q12: 如何在Hook中向用户输出信息？ 重要：不同Hook类型的输出机制不同！ PostToolUse Hook：无法直接输出给用户 • Claude Code只会显示"Hook执行成功/失败" • 如需调试，写入日志文件： Code block Python Copy from pathlib import Path log file = Path.home() / '.claude' / 'hooks' / 'debug.log' with open(log file, 'a') as f: f.write(f"调试信息\n") UserPromptSubmit Hook：通过stdout JSON的additionalContext字段 Code block Python Copy import json output = { "hookSpecificOutput": { "hookEventName": "UserPromptSubmit", "additionalContext": "要显示给用户的内容" } } print(json.dumps(output)) PreToolUse Hook：通过stdout JSON返回决策 Code block Python Copy import json decision = { "hookSpecificOutput": { "hookEventName": "PreToolUse", "permissionDecision": { "decision": "deny", "message": "拒绝原因（用户可见）" } } } print(json.dumps(decision)) stderr输出：仅用于调试，不会显示在Claude Code界面 Code block Python Copy print("调试信息", file=sys.stderr) 只在终端可见，用户看不到 Q13: 如何返回决策（PreToolUse）？ 使用stdout输出JSON： Code block Python Copy print(json.dumps({"decision": "deny", "message": "原因"})) Q14: 脚本报错会影响Claude Code吗？ 不会！Hook脚本出错不会阻止Claude Code运行，只是该Hook功能失效。 Q15: 如何处理Windows/macOS/Linux兼容性？ Code block Python Copy import platform system = platform.system() if system == 'Windows': Windows特定代码 elif system == 'Darwin': macOS macOS特定代码 else: Linux Linux特定代码 高级问题 Q16: Hook可以修改Claude的输出吗？ 不能直接修改。但可以： • PostToolUse后修改文件内容 • UserPromptSubmit修改用户输入 Q17: 多个Hook的执行顺序是什么？ 按配置文件中的顺序依次执行。 Q18: Hook可以调用Claude API吗？ 可以，但要注意： • 会消耗额外Token • 可能导致无限循环 • 建议设置调用限制 Q19: 如何在团队中共享Hook配置？ 将 .claude/ 目录加入Git版本控制： Code block Bash Copy git add .claude/settings.json git add .claude/hooks/ git commit m "Add Claude Code hooks" Q20: Hook有性能影响吗？ 有一定影响： • 每次工具调用都会触发Hook • 复杂脚本会增加延迟 • 建议优化脚本性能，设置合理timeout 附录A：配置速查表 Hook类型速查 Hook类型 触发时机 输入格式 输出格式 可阻止 重要 UserPromptSubmit 用户输入后 JSON 文本（注入上下文） V PreToolUse 工具调用前 JSON JSON决策 V ⭐ PostToolUse 工具调用后 JSON 无 X ⭐ Notification 通知发送时 JSON 无 X SessionStart 会话开始 无 无 X SessionEnd 会话结束 无 无 X Stop AI停止 JSON 无 X SubagentStart 🆕 子代理启动 JSON 无 X SubagentStop 🆕 子代理停止 JSON 无 X PermissionRequest 🆕 权限请求 JSON JSON决策 V PreCompact 🆕 上下文压缩前 JSON 无 X ConfigChange 🆕 配置变更 JSON 无 X TeammateIdle 🆕 队友空闲 JSON 无 X WorktreeCreate 工作树创建 JSON 无 X WorktreeRemove 工作树删除 JSON 无 X StopFailure 🆕 API异常停止 JSON 无 X PostCompact 🆕 上下文压缩后 JSON 无 X InstructionsLoaded 🆕 指令文件加载 JSON 无 X Elicitation 🆕 MCP请求输入 JSON 无 X ElicitationResult 🆕 MCP输入完成 JSON 无 X 常用工具名速查 工具名 功能 常用Hook 重要 Write 写入文件 PostToolUse格式化 ⭐ Edit 编辑文件 PostToolUse备份 Read 读取文件 PreToolUse权限控制 Bash 执行命令 PreToolUse危险命令拦截 ⭐ Glob 文件搜索 • Grep 内容搜索 • 在脚本中检查文件路径： Q9: 环境变量怎么传递给Hook脚本？ Claude Code自动传递的环境变量： • CLAUDE PROJECT DIR 项目根目录的绝对路径（Claude Code启动目录） ⚠️ 注意：session id不是环境变量，而是通过stdin的JSON输入传递！ 使用方法： Q10: 如何临时禁用Hook？ 方法1：重命名配置文件 方法2：注释掉Hook配置（JSON不支持注释，需要删除） 脚本问题 Q11: 如何读取Hook的输入？ Q12: 如何在Hook中向用户输出信息？ 重要：不同Hook类型的输出机制不同！ PostToolUse Hook：无法直接输出给用户 • Claude Code只会显示"Hook执行成功/失败" • 如需调试，写入日志文件： UserPromptSubmit Hook：通过stdout JSON的additionalContext字段 PreToolUse Hook：通过stdout JSON返回决策 stderr输出：仅用于调试，不会显示在Claude Code界面 Q13: 如何返回决策（PreToolUse）？ 使用stdout输出JSON： Q14: 脚本报错会影响Claude Code吗？ 不会！Hook脚本出错不会阻止Claude Code运行，只是该Hook功能失效。 Q15: 如何处理Windows/macOS/Linux兼容性？ 高级问题 Q16: Hook可以修改Claude的输出吗？ 不能直接修改。但可以： • PostToolUse后修改文件内容 • UserPromptSubmit修改用户输入 Q17: 多个Hook的执行顺序是什么？ 按配置文件中的顺序依次执行。 Q18: Hook可以调用Claude API吗？ 可以，但要注意： • 会消耗额外Token • 可能导致无限循环 • 建议设置调用限制 Q19: 如何在团队中共享Hook配置？ 将 .claude/ 目录加入Git版本控制： Q20: Hook有性能影响吗？ 有一定影响： • 每次工具调用都会触发Hook • 复杂脚本会增加延迟 • 建议优化脚本性能，设置合理timeout 附录A：配置速查表 Hook类型速查 Hook类型 触发时机 输入格式 输出格式 可阻止 重要 UserPromptSubmit 用户输入后 JSON 文本（注入上下文） V PreToolUse 工具调用前 JSON JSON决策 V ⭐ PostToolUse 工具调用后 JSON 无 X ⭐ Notification 通知发送时 JSON 无 X SessionStart 会话开始 无 无 X SessionEnd 会话结束 无 无 X Stop AI停止 JSON 无 X SubagentStart 🆕 子代理启动 JSON 无 X SubagentStop 🆕 子代理停止 JSON 无 X PermissionRequest 🆕 权限请求 JSON JSON决策 V PreCompact 🆕 上下文压缩前 JSON 无 X ConfigChange 🆕 配置变更 JSON 无 X TeammateIdle 🆕 队友空闲 JSON 无 X WorktreeCreate 工作树创建 JSON 无 X WorktreeRemove 工作树删除 JSON 无 X StopFailure 🆕 API异常停止 JSON 无 X PostCompact 🆕 上下文压缩后 JSON 无 X InstructionsLoaded 🆕 指令文件加载 JSON 无 X Elicitation 🆕 MCP请求输入 JSON 无 X ElicitationResult 🆕 MCP输入完成 JSON 无 X Hook类型 Hook类型 触发时机 触发时机 输入格式 输入格式 输出格式 输出格式 可阻止 可阻止 重要 重要 UserPromptSubmit UserPromptSubmit 用户输入后 用户输入后 JSON JSON 文本（注入上下文） 文本（注入上下文） V V PreToolUse PreToolUse 工具调用前 工具调用前 JSON JSON JSON决策 JSON决策 V V ⭐ ⭐ PostToolUse PostToolUse 工具调用后 工具调用后 JSON JSON 无 无 X X ⭐ ⭐ Notification Notification 通知发送时 通知发送时 JSON JSON 无 无 X X SessionStart SessionStart 会话开始 会话开始 无 无 无 无 X X SessionEnd SessionEnd 会话结束 会话结束 无 无 无 无 X X Stop Stop AI停止 AI停止 JSON JSON 无 无 X X SubagentStart 🆕 SubagentStart 🆕 子代理启动 子代理启动 JSON JSON 无 无 X X SubagentStop 🆕 SubagentStop 🆕 子代理停止 子代理停止 JSON JSON 无 无 X X PermissionRequest 🆕 PermissionRequest 🆕 权限请求 权限请求 JSON JSON JSON决策 JSON决策 V V PreCompact 🆕 PreCompact 🆕 上下文压缩前 上下文压缩前 JSON JSON 无 无 X X ConfigChange 🆕 ConfigChange 🆕 配置变更 配置变更 JSON JSON 无 无 X X TeammateIdle 🆕 TeammateIdle 🆕 队友空闲 队友空闲 JSON JSON 无 无 X X WorktreeCreate WorktreeCreate 工作树创建 工作树创建 JSON JSON 无 无 X X WorktreeRemove WorktreeRemove 工作树删除 工作树删除 JSON JSON 无 无 X X StopFailure 🆕 StopFailure 🆕 API异常停止 API异常停止 JSON JSON 无 无 X X PostCompact 🆕 PostCompact 🆕 上下文压缩后 上下文压缩后 JSON JSON 无 无 X X InstructionsLoaded 🆕 InstructionsLoaded 🆕 指令文件加载 指令文件加载 JSON JSON 无 无 X X Elicitation 🆕 Elicitation 🆕 MCP请求输入 MCP请求输入 JSON JSON 无 无 X X ElicitationResult 🆕 ElicitationResult 🆕 MCP输入完成 MCP输入完成 JSON JSON 无 无 X X 常用工具名速查 工具名 功能 常用Hook 重要 Write 写入文件 PostToolUse格式化 ⭐ Edit 编辑文件 PostToolUse备份 Read 读取文件 PreToolUse权限控制 Bash 执行命令 PreToolUse危险命令拦截 ⭐ Glob 文件搜索 • Grep 内容搜索 • 工具名 工具名 功能 功能 常用Hook 常用Hook 重要 重要 Write Write 写入文件 写入文件 PostToolUse格式化 PostToolUse格式化 ⭐ ⭐ Edit Edit 编辑文件 编辑文件 PostToolUse备份 PostToolUse备份 Read Read 读取文件 读取文件 PreToolUse权限控制 PreToolUse权限控制 Bash Bash 执行命令 执行命令 PreToolUse危险命令拦截 PreToolUse危险命令拦截 ⭐ ⭐ Glob Glob 文件搜索 文件搜索 • • Grep Grep 内容搜索 内容搜索 • • WebSearch 网络搜索 • Decision值速查 PreToolUse 新版API（hookSpecificOutput.permissionDecision，推荐）： 值 含义 工具执行 重要 "allow" 允许，绕过权限系统 V ⭐ "deny" 拒绝，原因反馈给Claude X ⭐ "ask" 暂停，询问用户 ? 无输出 默认允许 V 值 值 含义 含义 工具执行 工具执行 重要 重要 "allow" "allow" 允许，绕过权限系统 允许，绕过权限系统 V V ⭐ ⭐ "deny" "deny" 拒绝，原因反馈给Claude 拒绝，原因反馈给Claude X X ⭐ ⭐ "ask" "ask" 暂停，询问用户 暂停，询问用户 ? ? 无输出 无输出 默认允许 默认允许 V V PreToolUse 旧版API（decision，已废弃但仍支持）： 旧版值 等同于新版 "approve" "allow" "block" "deny" 旧版值 旧版值 等同于新版 等同于新版 "approve" "approve" "allow" "allow" "block" "block" "deny" "deny" PostToolUse / UserPromptSubmit： 值 含义 "block" 阻止/提供反馈 无输出 默认允许 值 值 含义 含义 "block" "block" 阻止/提供反馈 阻止/提供反馈 无输出 无输出 默认允许 默认允许 附录B：完整脚本模板 Python脚本模板 Bash脚本模板 附录C：参考资源 官方文档 • Claude Code Hooks官方文档 Claude Code Hooks官方文档 • Claude Code官方指南 Claude Code官方指南 社区资源 • ClaudeLog Hooks教程 ClaudeLog Hooks教程 • GitButler Claude Code Hooks集成 GitButler Claude Code Hooks集成 • Awesome Claude Code Awesome Claude Code 相关课程 • 第3部分：Commands系统 Slash命令开发 • 第4部分：MCP集成 外部工具连接 • 第6部分：Skills定制 技能包开发 学习总结 通过本课学习，你已经掌握： 1. Hooks核心概念：理解Hook是什么、为什么需要、能做什么 2. 15种Hook类型：PreToolUse、PostToolUse、UserPromptSubmit、Notification、Stop、SessionStart、SessionEnd、SubagentStart、SubagentStop、PermissionRequest、PreCompact、ConfigChange、TeammateIdle、WorktreeCreate、WorktreeRemove全部类型 3. 配置方法：settings.json配置格式、Matcher语法、timeout设置 4. 实战场景：Git自动化、代码格式化、文件保护、质量检查 5. 故障排查：常见问题诊断和解决方法 6. 安全意识：Hook安全风险和最佳实践 下一步建议： 1. 从第二部分的简单示例开始实践 2. 根据你的项目需求，选择合适的Hook类型 3. 参考第四部分的实战案例，逐步构建自己的自动化工作流 4. 遇到问题查阅第五部分和第六部分 记住：Hooks是自动化的终极武器，合理使用可以让你的开发效率翻倍！ 文档版本：v1.3（2026 04：v2.1.90 / v2.1.92 release 摘录）最后更新：2026年4月5日作者：老金 v1.2（2026 04 05） • 差量更新：增加 v2.1.90（PostToolUse 与 PreToolUse 相关修复）、v2.1.92（prompt type Stop hooks）官方 release What's changed 英文原文摘录（附链接） v1.1 修正内容（2025 12 23） 修正项 问题 修正后 UserPromptSubmit输入格式 错误描述为"纯文本" 修正为JSON格式 UserPromptSubmit示例脚本 直接读文本导致脚本无法工作 使用json.loads解析 速查表UserPromptSubmit行 输入格式列写"纯文本"与正文矛盾 修正为JSON，输出列修正为"文本（注入上下文）" Notification输入格式 字段不完整 添加完整字段说明 Stop Hook输入格式 错误声称有reason字段 删除不存在的字段 环境变量说明 错误声称有CLAUDE SESSION ID 明确session id在JSON中 Windows通知脚本 NotifyIcon不稳定 改用BurntToast/原生Toast 修正项 修正项 问题 问题 修正后 修正后 UserPromptSubmit输入格式 UserPromptSubmit输入格式 错误描述为"纯文本" 错误描述为"纯文本" 修正为JSON格式 修正为JSON格式 UserPromptSubmit示例脚本 UserPromptSubmit示例脚本 直接读文本导致脚本无法工作 直接读文本导致脚本无法工作 使用json.loads解析 使用json.loads解析 速查表UserPromptSubmit行 速查表UserPromptSubmit行 输入格式列写"纯文本"与正文矛盾 输入格式列写"纯文本"与正文矛盾 修正为JSON，输出列修正为"文本（注入上下文）" 修正为JSON，输出列修正为"文本（注入上下文）" Notification输入格式 Notification输入格式 字段不完整 字段不完整 添加完整字段说明 添加完整字段说明 Stop Hook输入格式 Stop Hook输入格式 错误声称有reason字段 错误声称有reason字段 删除不存在的字段 删除不存在的字段 环境变量说明 环境变量说明 错误声称有CLAUDE SESSION ID 错误声称有CLAUDE SESSION ID 明确session id在JSON中 明确session id在JSON中 Windows通知脚本 Windows通知脚本 NotifyIcon不稳定 NotifyIcon不稳定 改用BurntToast/原生Toast 改用BurntToast/原生Toast Hooks系统完整指南：自动化工作流的终极武器 课程信息 • 作者：老金 • GitHub：https://github.com/KimYx0207 • 公众号：老金带你玩AI • X（Twitter）：老金带你玩AI • 个人博客：https://aiking.dev • 预计学时：4 6小时 • 难度等级：⭐⭐ 入门级（有Claude Code基础即可） • 更新日期：2026年4月 • 适用版本：Claude Code v2.1.133（验证于 2026 05 08） • 前置要求：已完成Claude Code安装和基础使用 https://aiking.dev 课程信息 • 作者：老金 • GitHub：https://github.com/KimYx0207 • 公众号：老金带你玩AI • X（Twitter）：老金带你玩AI • 个人博客：https://aiking.dev https://aiking.dev • 预计学时：4 6小时 • 难度等级：⭐⭐ 入门级（有Claude Code基础即可） • 更新日期：2026年4月 • 适用版本：Claude Code v2.1.133（验证于 2026 05 08） • 前置要求：已完成Claude Code安装和基础使用 本课学习目标 完成本课学习后，你将能够： 1. 理解Hooks的核心价值：掌握Hooks与传统提示词的本质区别 2. 配置第一个Hook：5分钟内完成最简单的Hook配置并看到效果 3. 按事件族理解Hooks：理解工具、会话、任务、失败、文件系统、压缩和 Elicitation 等事件面 4. 实现自动化工作流：Git提交检查、代码格式化、文件保护等实战场景 5. 排查Hook故障：独立解决90%的常见配置和执行问题 6. 安全使用Hooks：理解安全风险并正确配置权限 2026 04 差量更新（先读） 这章旧版最大的问题，是把 Hooks 讲成“固定 20 种类型”。现在这个说法已经不稳了。 • 官方 Hook 事件面仍在扩展，不要再死记一个固定数字。 • 当前主流处理器有 4 类：command、http、prompt、agent。 • 除了常见的 PreToolUse / PostToolUse / UserPromptSubmit，还应注意较新的事件，例如 PostToolUseFailure、PermissionDenied、TaskCreated、TaskCompleted、StopFailure、CwdChanged、FileChanged。 因此，下面正文请用“事件族 + 处理器类型 + 典型场景”来理解，而不是背一个固定数量。 与 Hooks 相关的 v2.1.90 → v2.1.133 变更（GitHub Release 摘录） 下列句子均来自官方 What's changed，英文原文便于逐字核对；教程不展开实现细节。 v2.1.90（release）： release • Fixed Edit/Write failing with "File content has changed" when a PostToolUse format on save hook rewrites the file between consecutive edits • Fixed PreToolUse hooks that emit JSON to stdout and exit with code 2 not correctly blocking the tool call v2.1.92（release）： release • Fixed prompt type Stop hooks incorrectly failing when the small fast model returns ok:false, and restored preventContinuation:true semantics for non Stop prompt type hooks v2.1.121（release）： release • Hook JSON input now includes effort.level field, and $CLAUDE EFFORT environment variable is set for hook subprocesses 这意味着 Hook 脚本现在可以感知当前 effort 等级（low/medium/high/xhigh/max），据此调整行为。例如，xhigh 时跳过某些轻量检查以避免打断深度推理。 v2.1.133（release）： release • PostToolUse hooks can now replace tool output for ALL tools via hookSpecificOutput.updatedToolOutput • Hook output now includes duration ms field 重点变化： 1. PostToolUse 可替换工具输出：以前 PostToolUse 只能做格式化或记录，现在可以通过 hookSpecificOutput.updatedToolOutput 字段替换工具的实际输出内容。适用于所有工具，不再局限于特定工具类型。 2. duration ms：Hook 执行耗时现在以毫秒级精度记录，方便性能监控和超时告警。 3. effort.level：Hook 接收的 JSON input 新增 effort.level 字段，环境变量 $CLAUDE EFFORT 同步可用。 阅读提示：若 Hook 行为与上述条目相关但仍异常，以当前安装的 claude version 及之后新 release 为准。 学习路径导航（先看这里！） 根据你的情况选择学习路径：这是一篇3000+行的长教程，不用全看！根据你的目标选择路径。 路径A：快速上手（30分钟） 适合人群：急着体验Hooks，想快速配一个看效果 只看这些章节（其他跳过）： 30分钟后你能达到：成功配置第一个Hook，Claude Code能自动执行你的脚本 路径B：完整学习（4 6小时） 适合人群：想深入理解Hooks，掌