15 | Claude Code Hooks 事件驱动自动化：防微杜渐的安全防线

15 | Claude Code Hooks 事件驱动自动化：防微杜渐的安全防线声明：📝 作者：甜城瑞庄的核桃（ZMJ）原创学习笔记，欢迎分享，但请保留作者信息及原文链接哦～本文深入解析 Claude Code 的 Hooks 机制,揭示如何在 AI 执行工具前后插入自定义检查,阻止危险命令、保护敏感文件、自动格式化代码——在小问题萌芽时就防止它演变成灾难。目录一、为什么需要 Hooks二、Hooks 的本质三、17种Hook事件全景四、Hook 配置详解五、四种 Hook 执行类型六、PreToolUse 实战七、PostToolUse 实战八、总结一、为什么需要 Hooks1.1 AI 辅助开发的隐患场景: 咖哥用 Claude Code 快速写完了代码写代码 → 测试通过 → git push → 关机睡觉潜在问题:❌ 安全漏洞未检查❌ 敏感信息可能泄露❌ 代码格式混乱❌ 测试没跑就上线共同特点: 这些问题本可以被自动阻止1.2 需要一道看不见的防线如果有一道防线: ├─ 在代码提交前 → 自动检查敏感文件 ├─ 在文件保存后 → 自动格式化 └─ 在任务完成时 → 自动运行测试 那些"忘记"就不再是问题这道防线,就是 Hooks1.3 三大扩展机制对比机制作用能否拦截类比Commands告诉 Claude"做什么"❌任务指令Skills告诉 Claude"怎么做"❌领域知识Hooks控制 Claude"能不能做"✅安全制度关键区别: Hooks 是唯一能拦截和修改 Claude 行为的机制二、Hooks 的本质2.1 AI 时代的中间件Web 开发中的中间件:请求 → 中间件1→ 中间件2→ 中间件3→ 处理函数 ↓ 认证、日志、限流横切关注点 (Cross-cutting Concerns):不属于任何一个业务功能但必须贯穿所有请求认证要每个接口都检查日志要每个操作都记录Claude Code 的 Hooks:用户请求 → Claude决策 → [PreToolUse Hook] → 工具执行 → [PostToolUse Hook] → 响应 ↓ ↓ 权限检查、拦截 格式化、验证、日志2.2 核心价值业务代码不应该操心安全和日志 ↓ Claude 不应该操心格式化和权限检查 ↓ 安全防线、质量守卫、审计日志 全部由 Hooks 在"幕后"自动完成2.3 三大机制完整控制谱系┌─────────────────────────────────────────────────┐ │ 控制谱系 │ ├─────────────────────────────────────────────────┤ │ Commands → 任务指令 │ │ "做什么" (给 Claude 下达任务) │ ├─────────────────────────────────────────────────┤ │ Skills → 领域知识 │ │ "怎么做" (Claude 掌握的专业能力) │ ├─────────────────────────────────────────────────┤ │ Hooks → 安全制度 │ │ "能不能做" (公司的规范和防线) │ └─────────────────────────────────────────────────┘类比: 如果把 Claude 比作工程师Commands: 你给他下达的任务Skills: 他掌握的领域知识Hooks: 公司的安全制度和质量规范三、17种Hook事件全景3.1 完整事件列表截至 2026年3月,Claude Code 支持17种 Hook 事件:事件名称时机能否阻止典型用途SessionStart会话启动时❌初始化、欢迎消息UserPromptSubmit用户提交输入前✅输入过滤、内容审查PreToolUse工具执行前✅权限检查、危险拦截PostToolUse工具执行成功后❌格式化、Lint、日志PostToolUseFailure工具执行失败后❌错误处理、告警PermissionRequest权限请求时✅(接管)自动批准/拒绝Stop任务完成时✅质量验收、强制继续SubagentStart子代理启动前❌上下文注入SubagentStop子代理完成时✅输出验证Notification通知触发时❌自定义通知PreCompact上下文压缩前❌数据备份SessionEnd会话结束时❌清理、统计3.2 三大阵营分类阵营 1: 控制点 (能阻止的事件)PreToolUse → 拦截危险操作 UserPromptSubmit → 拒绝不合理输入 Stop → 强制 Claude 继续修复 SubagentStop → 拒绝不合格的子代理输出特点: 可以改变 Claude 的执行路径类比: Hooks 系统的肌肉阵营 2: 接管点 (替代默认行为)PermissionRequest → 自动批准或拒绝权限请求特点: 接管原本由用户手动处理的权限弹窗类比: Hooks 系统的自动驾驶阵营 3: 观察点 (不能阻止的事件)SessionStart → 记录会话开始 PostToolUse → 记录、反馈、后处理 PostToolUseFailure → 记录失败 Notification → 自定义通知 SubagentStart → 记录子代理启动 PreCompact → 备份压缩前数据 SessionEnd → 记录会话结束特点: 只能记录、反馈、后处理,不能改变已发生的事类比: Hooks 系统的眼睛3.3 不对称设计的原因工具执行前 → 可以拦截 理由: 操作还没发生,拦截不会造成不一致状态 工具执行后 → 不能拦截 理由: 操作已经完成,不能"取消"已写入磁盘的文件 但可以: 观察它、记录它、反馈它四、Hook 配置详解4.1 配置位置与作用域位置文件路径作用域版本控制适用场景用户级~/.claude/settings.json所有项目❌ 不提交个人习惯项目级.claude/settings.json当前项目✅ 提交到 git团队约定本地覆盖.claude/settings.local.json当前项目❌ 不提交临时调试子代理级Agent frontmatter特定子代理✅ 提交到 git子代理专属4.2 配置位置选择流程决策流程: │ ├─ 只影响我自己? (日志格式、通知方式) │ └─ 是 → 用户级 (~/.claude/settings.json) │ ├─ 需要团队共享? (代码格式化、敏感文件保护) │ └─ 是 → 项目级 (.claude/settings.json) │ ├─ 临时调试用? (关闭某个 Hook) │ └─ 是 → 本地覆盖 (.claude/settings.local.json) │ └─ 只和特定子代理相关? (SQL注入检查) └─ 是 → 子代理 frontmatter4.3 典型配置结构{"hooks":{"PreToolUse":[{"matcher":"Bash","hooks":[{"type":"command","command":"./hooks/block-dangerous.sh"}]}],"PostToolUse":[{"matcher":"Write","hooks":[{"type":"command","command":"prettier --write $CLAUDE_FILE_PATH"}]}]}}4.4 三层嵌套结构解析hooks ← 第一层: 顶层容器 ├── PreToolUse ← 第二层: 事件类型(什么时候触发) │ └── [第一组规则] │ ├── matcher: "Bash" ← 第三层: 匹配器(针对哪个工具) │ └── hooks: [...] ← 第三层: Hook 列表(执行什么) │ ├── type: "command" │ └── command: "..." └── PostToolUse └── [第二组规则] ├── matcher: "Write" └── hooks: [...]决策路径:第一层 → "什么时候" (工具执行前 or 后?) 第二层 → "针对谁" (所有工具 or 特定工具?) 第三层 → "做什么" (执行脚本 or 调用LLM?)4.5 Matcher 匹配模式四种匹配方式// 1. 精确匹配单个工具"matcher":"Write"// 2. 匹配多个工具(用竖线分隔)"matcher":"Edit|Write|MultiEdit"// 3. 匹配所有工具"matcher":"*"// 4. 空匹配(用于生命周期事件)"matcher":""使用建议模式适用场景示例精确匹配最常用,针对特定工具"Write"竖线分隔同类工具组"Edit|Write|MultiEdit"通配符*审计日志(无差别记录)谨慎使用空匹配生命周期事件SessionStart,SessionEnd五、四种 Hook 执行类型5.1 类型概览类型能力代价适用场景command确定性规则最低模式匹配、文件检查promptLLM 单次评估中等需要语义理解agent子代理多轮验证最高需要翻代码确认http远程服务对接网络延迟团队审计、集中管控5.2 类型 1: Command (Shell 脚本)定义: 执行 Shell 命令或脚本{"type":"command","command":"./hooks/check-security.sh","timeout":30000}优势:✅ 确定性: 同样输入永远产生同样输出✅ 可靠性: 无 LLM 随机性✅ 速度快: 纯本地执行示例: 正则匹配rm -rf /要么匹配到 → 拦截要么没匹配到 → 放行没有"可能""大概"的中间地带5.3 类型 2: Prompt (LLM 评估)定义: 用小型 LLM (通常 Haiku) 评估{"type":"prompt","prompt":"Evaluate if this task was completed correctly. Check for any errors or incomplete work."}适用场景: 规则无法用确定性脚本表达时示例: “这段代码是否有安全隐患”需要理解代码语义,不是简单模式匹配限制: 只能"看一眼就判断",无法主动读取更多文件5.4 类型 3: Agent (子代理评估)定义: 启动子代理,可以使用工具验证{"type":"agent","prompt":"Verify that all unit tests pass. Run the test suite and check the resul