Claude Code 扩展点：Hooks需要先看清适用场景和关键步骤，避免只记结论却忽略实际限制。

1. Hooks 是什么

Hook = 在 CC 生命周期事件发生时，自动执行的一段脚本。它由 CC 的 harness（运行框架）执行，不是由 Claude 模型执行——这是 hooks 和 skill/MCP 的本质区别：

机制	谁来执行	特性
Skill	Claude 模型读指令后执行	灵活，但依赖模型判断
MCP	Claude 模型调用工具	灵活，模型驱动
Hook	harness 硬性执行脚本	确定性，不依赖模型，适合做安全护栏/强制规范

2. 事件点（什么时候触发）

事件	触发时机	典型用途
PreToolUse	任何工具调用前	拦截危险命令、校验参数、记录审计
PostToolUse	工具调用完成后	校验结果、触发后续处理
SessionStart	每次会话启动时	注入上下文/提示、加载环境
Stop	Claude 输出结束时	收尾、汇总、触发下一步
Notification	后台任务完成等通知时	发提醒、更新状态
SubagentStart / SubagentStop	子 Agent 启动/结束时	子任务管理、上下文注入

3. 配置写法

在 settings.json 里配 hooks 段：

{"hooks":{"PreToolUse":[{"matcher":"Bash","hooks":[{"type":"command","command":"bash ~/.claude/hooks/guard_bash.sh","timeout":10}]}],"SessionStart":[{"hooks":[{"type":"command","command":"echo '会话已启动'"}]}]}}

字段说明

字段	含义
matcher	匹配的工具/事件，如 Bash、Read、Edit、Write；支持 glob（Edit(src/**)）
type	command（执行 shell 命令）或 python（执行脚本）
command	要执行的命令/脚本
timeout	超时（秒），超时按失败处理
事件键	事件名对应上面的表格（PreToolUse / SessionStart / ...）

退出码语义

退出码	含义	结果
0	成功	放行
1	失败	阻止（PreToolUse 会拦截该工具调用）
2	停止/特殊	不同事件语义不同，参考官方文档

4. 典型场景

4.1 安全护栏：拦截危险命令

场景：防止 CC 误执行 git push 或清空文件的命令。

#!/bin/bash# ~/.claude/hooks/guard_bash.sh# 从 stdin 读取工具调用 JSON，检查 command 字段input=$(cat)echo"$input" | grep -q '"command": "git push"' && {  echo" 拦截：不允许直接 git push，请走 PR 流程" >&2  exit 1}exit 0

4.2 强制代码规范：PostToolUse 检查格式

场景：每次 Edit 后自动跑格式化。

{"hooks":{"PostToolUse":[{"matcher":"Edit|Write","hooks":[{"type":"command","command":"npx prettier --check"}]}]}}

4.3 SessionStart 注入工作区上下文

场景：在知识库 vault 里启动 CC 时，自动加载 MOC 结构提示。superpowers 的 SessionStart hook 就是这种模式——插件启用时自动挂上，每次会话注入"你有 superpowers"的上下文。

4.4 通知：后台任务完成提醒

场景：子 Agent 跑完长任务，发个 macOS 通知。

{"hooks":{"Notification":[{"hooks":[{"type":"command","command":"osascript -e 'display notification "后台任务完成" with title "Claude Code"'"}]}]}}

5. 与 skill / MCP / 权限的关系

1. hook 做"确定性拦截"，skill 做"灵活性指导"——安全类需求优先 hook（模型无法绕过），流程类需求用 skill
2. hook 可以调用 MCP 工具的结果（通过读 PostToolUse 输出），但 hook 本身是 harness 执行的，不是模型驱动的工具调用
3. 权限模式 + hooks 双保险：权限管"询问不询问"，hook 管"必然拦截"；bypassPermissions 下 hook 依然生效——所以 hook 是 bypass 模式的唯一安全网

6. 如何调试

1. hook 的 stdout/stderr 会回显到 CC 会话，先加 echo 观察输入输出
2. PreToolUse 钩子从 stdin 收到的是工具调用 JSON，可以用 cat 存下来分析字段结构
3. 临时禁用一个 hook：从 settings.json 注释掉对应条目，重开会话生效
4. 2.1.169 起 --safe-mode 启动会禁用所有定制（含 hooks），排障时可用它区分是 hook 还是环境问题