Claude Code 扩展点：Hooks

本文讲清 hooks 机制 + 配置写法 + 典型场景，需要时按模板落地即可。

1. Hooks 是什么

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

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

一句话：hook 是"无论 Claude 想不想，都会跑"的自动化。想做安全拦截、格式强制、操作审计，用 hook 而不是 skill。

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

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

2.1.163 起 Stop / SubagentStop hook 可返回 additionalContext 反馈给 Claude 并继续 turn------hook 不再只是"旁路脚本"，能真正参与对话循环。

3. 配置写法

在 settings.json 里配 hooks 段：

json 复制代码

{
  "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`	停止/特殊	不同事件语义不同，参考官方文档

PreToolUse 返回非 0 = 工具被拦截 。这就是 hook 能做"安全护栏"的原因------git push、rm -rf 这类危险操作，可以写 hook 在触发前拦下来。

4. 典型场景

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

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

bash 复制代码

#!/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 后自动跑格式化。

json 复制代码

{
  "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 通知。

json 复制代码

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

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

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

⚠️ 如果你设了 bypassPermissions，跑不可信的项目时建议至少加一条 PreToolUse 安全 hook，否则 CC 可以执行任何命令而无人过问。

6. 如何调试

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