Claude Code 扩展点：Hooks

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

1. Hooks 是什么

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

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

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 '会话已启动'"}]}]}}

字段说明

退出码语义

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 还是环境问题