| 版本 | 内容 | 时间 | | ---- | -------- | ------------------- | | V1 | 新建 | 2026-07-13 14:50:30 | | V2 | 完善文案 | 2026-07-24 11:39:55 | ## 定义 Hook 是 Claude Code 中用于自动触发外部逻辑的机制，可以**在特定事件发生时自动执行预定义操作**。它最大的价值是提供确定性的行为控制：**一些必须执行的规则，不应该依赖模型“记住”或者“主动决定执行”，而应该交给 Hook 强制完成。** 例如： - 修改文件后自动运行格式化； - 执行危险命令前进行拦截； - 代码修改后自动运行测试； - 会话启动时加载项目环境信息。相比 Prompt 里的约束，Hook 属于更可靠的工程控制层，因为它是在 Claude Code 生命周期节点直接触发。简单来说： - Prompt 告诉 Claude “应该怎么做”。 - Hook 保证 Claude “一定会经过这个检查流程”。 **在 Agent 工程中，Hook 的作用就是给模型增加确定性的护栏。** ## quickstart 创建 Claude Code Hook，只需要在配置文件的 `hooks` 字段中添加对应规则即可。下面以桌面通知 Hook 为例。当 Claude Code 需要人工确认时，通过系统通知提醒开发者，避免一直盯着终端。 ### 步骤 1：在配置文件添加钩子在 `~/.claude/settings.json` 中添加： ```json { "hooks": { "Notification": [ { "matcher": "", "hooks": [ { "type": "command", "command": "osascript -e 'display notification \"Claude Code needs your attention\" with title \"Claude Code\"'" } ] } ] } } ``` 其中： - `Notification` 是 Claude Code 提供的生命周期事件； - `matcher` 用于筛选触发条件，空字符串表示匹配全部情况； - `type: command` 表示执行一个 Shell 命令。 ### 步骤 2：校验配置是否加载成功配置完成后，可以在 Claude Code 中输入：`/hooks` 打开 Hook 管理页面，查看当前生效的事件、匹配规则以及配置来源。选中 `Notification`，能查看完整配置详情：触发事件、匹配规则、钩子类型、配置文件路径、执行脚本。 ### 步骤 3：测试钩子功能按 `Esc` 返回交互终端，让 Claude 执行需要权限确认的操作，切走终端窗口，桌面会弹出预设提醒。 > `/hooks` 面板仅用于查看，无法编辑增删钩子；修改、新增、删除钩子只能手动编辑 `settings.json`，或让 AI 帮你修改配置文件。 ## Hook 基本概念 ### Hook 事件 - 完整生命周期覆盖 > 完整的生命周期事件参考 https://code.claude.com/docs/zh-CN/hooks Hook 事件会在 Claude Code 生命周期的固定节点触发。事件触发后，所有匹配的钩子并行执行，重复相同的钩子命令会自动去重。 Claude Code 的 Hook 可以按照它对执行流程的影响方式，分为三类：**控制型 Hook、决策型 Hook、观察型 Hook**。 - **控制型 Hook：负责在关键节点拦截和改变流程。** 这类 Hook 发生在**动作执行前或流程结束前，可以阻止、修改或延迟后续行为**。例如 `PreToolUse` 可以在工具调用前检查参数，阻止危险操作；`UserPromptSubmit` 可以在用户输入进入 Agent 前进行过滤；`Stop` 和 `SubagentStop` 可以控制 Agent 是否允许结束任务。它们的核心价值是把重要规则从“依赖模型自觉遵守”变成“系统强制执行”。 - **决策型 Hook：负责接管原本需要人工判断的节点。** 典型代表是 `PermissionRequest`。当 Claude Code 请求执行某个需要授权的操作时，Hook 可以根据预设规则自动返回允许或拒绝结果。例如在可信目录自动批准读取操作，在敏感目录强制要求人工确认。它解决的是权限流程自动化问题，而不是简单阻止行为。 - **观察型 Hook：负责记录、分析和触发后处理。** 这类 Hook 不改变已经发生的行为，而是**在事件发生后获取上下文，用于日志记录、通知、质量检查和自动化处理**。例如 `SessionStart` 可以初始化环境，`PostToolUse` 可以在文件修改后执行格式化或检查，`PostToolUseFailure` 可以收集失败信息，`Notification` 可以提醒用户关注状态变化。它们类似系统的监控层，帮助开发者了解 Agent 的运行过程。三类 Hook 的核心区别在于：**控制型解决“不要发生什么”，决策型解决“谁来判断是否允许发生”，观察型解决“发生之后如何记录和处理”。** 在工程实践中，通常组合使用三类 Hook：用控制型保证安全边界，用决策型减少人工确认成本，用观察型完善反馈和治理体系。 ### 多 Hook 同时匹配同一事件的合并逻辑 Claude Code 允许同一个生命周期事件配置多个 Hook。当多个 Hook 同时匹配某个事件时，它们会触发执行，所有 Hook 完成后，Claude Code 会综合处理它们返回的结果。需要注意的是：一个 Hook 返回阻止结果，并不会提前终止其他同级 Hook。Hook 之间是相互独立的执行单元，因此不能依赖“第一个拒绝后，后面的 Hook 不会运行”这种行为。例如，一个 `PreToolUse` 事件同时配置两个 Bash 检查 Hook： - 日志 Hook：负责记录 Claude 执行的 Shell 命令； - 安全 Hook：负责检测危险操作，例如 `rm -rf`。 ```json { "hooks": { "PreToolUse": [ { "matcher": "Bash", "hooks": [ { "type": "command", "command": "jq -r .tool_input.command >> ~/.claude/bash.log" }, { "type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/block-rm-rf.sh" } ] } ] } } ``` 当 Claude 尝试执行： ``` rm -rf /tmp/build ``` 两个 Hook 会同时启动： - 日志 Hook 尝试记录这条命令； - 安全 Hook 检测到危险删除操作，并返回拒绝结果。最终 Claude Code 会根据 Hook 返回结果阻止这个工具调用，并把拒绝原因反馈给 Claude。`PreToolUse` 支持通过决策结果控制工具是否继续执行，例如允许、拒绝或请求确认。这里有一个重要工程原则：**Hook 之间不要依赖执行顺序，而应该设计成独立、无副作用冲突的检查单元。** 一个 Hook 负责安全控制，一个 Hook 负责日志记录，一个 Hook 负责质量检查。它们共同组成治理链，而不是互相调用的流水线。 ### Hook如何读写输入输出 Hook 与 Claude Code 的通信主要依靠四个通道：**标准输入 (stdin)、标准输出 (stdout)、标准错误 (stderr)、程序退出码**（exit code）。当某个生命周期事件触发后，Claude Code 会把当前事件相关的 JSON 数据传递给 Hook 脚本，脚本读取这些信息后执行自定义逻辑，再通过输出内容和退出码告诉 Claude Code 后续如何处理。工程上可以这样理解： - stdin：Claude Code 告诉 Hook “发生了什么” - stdout：Hook 返回“结构化结果” - stderr：Hook 说明“为什么失败” - exit code：Hook 决定“是否继续” Hook 本质上就是一个外部控制器：Claude Code 提供事件上下文，Hook 根据规则处理，再通过标准通信协议影响 Agent 后续行为。 #### stdin——接收事件上下文 Claude Code 会把事件对应的数据以 JSON 格式写入 Hook 的 stdin。不同事件包含不同字段，例如工具调用相关事件会包含： ```json { "hook_event_name": "PreToolUse", "tool_name": "Bash", "tool_input": { "command": "npm test" } } ``` 脚本可以解析这些字段，获取当前操作的信息。例如： ```bash jq -r '.tool_input.command' ``` 就是读取 Bash 工具即将执行的命令。 #### stdout——返回结构化结果 stdout 主要用于向 Claude Code 返回结果。最常见的是输出 JSON，用于提供更细粒度的控制，例如允许、拒绝、追加上下文等。需要注意： - 并不是所有 stdout 内容都会进入 Claude 上下文，只有部分事件（例如 `UserPromptSubmit`、`UserPromptExpansion`、`SessionStart`）会把 stdout 内容作为上下文提供给 Claude； - 其他情况下，stdout 更多用于 Hook 返回数据或调试记录。 #### stderr——返回错误和阻断原因 stderr 主要用于告诉 Claude 或用户“为什么失败”。例如安全 Hook 拦截危险命令： ```shell echo "Blocked: rm commands are not allowed" >&2 exit 2 ``` 当 Hook 返回阻断状态时，stderr 内容会反馈给 Claude，帮助它理解为什么操作不能继续。 #### exit code——控制执行结果对于 Command Hook，退出码是最基础的控制方式： - `exit 0`：Hook 执行成功，继续后续流程； - `exit 2`：阻止当前操作，并将 stderr 作为原因反馈； - 其他退出码：表示 Hook 执行异常，但通常不会阻止 Claude 继续执行。例如： ```shell if [[ "$COMMAND" == "rm -rf"* ]]; then echo "Dangerous command blocked" >&2 exit 2 fi exit 0 ``` 这个 Hook 会在危险命令执行前拦截操作。 #### Hook 输入数据说明所有生命周期事件都会携带通用字段（会话 ID、当前工作目录等），同时不同事件会附带专属业务数据。举个例子：当 Claude 要执行 Shell 命令时，`PreToolUse` 前置钩子会通过标准输入传入如下 JSON 数据： ```json { "session_id": "abc123", // 当前会话唯一标识 "cwd": "/Users/sarah/myproject", // 触发钩子时的项目工作目录 "hook_event_name": "PreToolUse", // 触发本次钩子的事件名称 "tool_name": "Bash", // Claude 即将调用的工具名称 "tool_input": { // 传给工具的入参 "command": "npm test" // Bash工具专属：待执行的shell命令 } } ``` 其中： - `tool_name` 表示 Claude 即将调用的工具； - `tool_input` 表示传递给工具的参数； - 对于 Bash 工具，`command` 字段就是即将执行的 Shell 命令。你的脚本可以用 `jq` 等工具解析这份 JSON，读取任意字段做自定义逻辑判断。例如： ```bash jq -r '.tool_input.command' ``` 表示： - 从输入 JSON 中找到 `tool_input` - 继续读取其中的 `command` - 输出对应的 Shell 命令文本 --- 不同事件提供的数据不同： - `UserPromptSubmit` 会包含用户提交的 prompt； - `SessionStart` 会包含会话启动来源，例如新建、恢复等； - `PostToolUse` 会包含工具执行完成后的结果信息。 #### Hook 的输出规则 Hook 通过 **stdin 接收输入，stdout / stderr / exit code 返回结果**，同时支持结构化 JSON 输出，用于向 Claude Code 传递校验结果、控制决策以及补充上下文。下面以一个 `PreToolUse` 安全防护 Hook 为例：当 Claude 尝试执行危险数据库操作时，Hook 检查命令内容，并阻止高风险行为。 ```shell #!/bin/bash INPUT=$(cat) # 从 stdin 读取 Claude Code 传入的 JSON COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command') # 检测危险 SQL 操作 if echo "$COMMAND" | grep -qi "drop table"; then echo "Blocked: dropping tables is not allowed" >&2 exit 2 fi # 没有发现问题 exit 0 ``` Hook 的退出码决定 Claude Code 如何处理结果： - `exit 0`：表示 Hook 执行成功，没有提出阻止意见。对于 `PreToolUse`，它并不代表一定自动执行工具，而只是表示该 Hook 没有拒绝本次调用。最终结果仍可能受到其他 Hook 或权限规则影响。 - `exit 2`：表示 Hook 明确阻止当前行为。但实际效果取决于事件类型： - `PreToolUse`：阻止工具执行； - `UserPromptSubmit`：拒绝该 Prompt； - `Stop`：阻止 Claude 结束当前任务； - `SubagentStop`：阻止子代理停止。而对于已经发生的事件，例如 `PostToolUse`，`exit 2` 无法撤销已经完成的操作，只能把错误反馈给 Claude。 - 其他退出码：表示 Hook 执行异常。 Claude Code 会记录 Hook 错误，并展示 stderr 信息，但通常不会阻止操作继续执行。 --- **stdout 和 stderr 的职责不同**： - **stderr**：用于输出错误信息、阻断原因或提示信息。当 Hook 使用 `exit 2` 阻止操作时，stderr 内容会反馈给 Claude，帮助它理解为什么失败。例如： ```bash echo "Database migration requires approval" >&2 exit 2 ``` Claude 会收到这条原因说明。 - **stdout**：用于返回正常输出。对于高级 Hook 场景，推荐输出 JSON，让 Claude Code 精确理解你的决策。例如 `PreToolUse` 拒绝执行： ``` { "hookSpecificOutput": { "hookEventName": "PreToolUse", "permissionDecision": "deny", "permissionDecisionReason": "Database writes are disabled" } } ``` 这种方式比简单 exit code 更灵活，可以表达允许、拒绝、请求确认等不同决策。 ### 使用 matcher 过滤 Hook 触发条件默认情况下，如果 Hook 没有配置 `matcher`，它会匹配该生命周期事件的所有触发场景。例如，一个 `PostToolUse` Hook 如果不设置 matcher，那么 Claude Code 每次调用工具后都会执行它。实际开发中，通常需要缩小触发范围。例如，我们只希望文件修改完成后自动执行 Prettier，而不是读取文件、执行测试等操作后都运行： ```json { "hooks": { "PostToolUse": [ { "matcher": "Edit|Write", "hooks": [ { "type": "command", "command": "prettier --write ..." } ] } ] } } ``` 这里的 `matcher` 是一个正则表达式，用于匹配工具名称。因此： - `Edit`：匹配 Claude Code 的编辑文件操作； - `Write`：匹配写入文件操作；需要注意，`matcher` 匹配的是**事件对应的字段**，不是任意文本。每一类生命周期事件，`matcher` 过滤的目标字段都不一样，相关对应事件、过滤对象请参考官方文档。 #### 通过 if 字段结合工具名 + 入参双重过滤钩子 > `if` 字段需要 Claude Code v2.1.85 及以上版本，旧版本会直接忽略该字段，匹配 `matcher` 后无条件执行钩子。 `if` 字段用于在 `matcher` 基础上进一步缩小 Hook 的触发范围。它使用 Claude Code 权限规则语法，可以同时匹配工具名称和工具参数，让 Hook 不必在每次工具调用时都启动，而只处理真正相关的操作。 ```json { "hooks": { "PreToolUse": [ { "matcher": "Bash", "hooks": [ { "type": "command", "if": "Bash(git *)", "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/check-git-policy.sh" } ] } ] } } ``` 这里 `matcher: "Bash"` 先筛选 Bash 工具调用，而 `if: "Bash(git *)"` 再进一步判断具体命令内容。只有 Claude 执行 Git 相关命令时，Hook 脚本才会启动。相比 `matcher` 只能根据工具名称过滤，`if` 可以结合工具参数进行更细粒度控制。例如： - `Bash(git *)`：匹配 Git 命令； - `Bash(git push *)`：匹配 Git push 操作； - `Edit(*.ts)`：只匹配 TypeScript 文件编辑。需要注意的是，`if` 并不是完整的 Shell 解析器，而是基于权限规则进行匹配。对于 Bash 命令，Claude Code 会尝试拆分子命令进行判断，例如： ``` npm test && git push ``` 其中 `git push` 会被识别并触发对应 Hook。 --- if 匹配规则执行对照表 | if 匹配模板 | Bash 实际命令 | 是否触发钩子 | 原因说明 | | ------------------ | ---------------------- | ------------ | ------------------------------------------------------------ | | `Bash(git *)` | `git push` | 是 | 主命令匹配 git 前缀 | | `Bash(git *)` | `npm test && git push` | 是 | 会解析管道 / 分号分割的多条子命令，匹配到 git push | | `Bash(git *)` | `echo $(git log)` | 是 | 会解析 `$()`、反引号内嵌套执行的 git 命令 | | `Bash(git *)` | `echo $(date)` | 否 | 无任何 git 相关子命令，不匹配 | | `Bash(git push *)` | `echo $(date)` | 是 | 模板精确指定子命令（git push）时，无论命令内容都会触发钩子（特殊兼容逻辑） | > [!warning] > > 兜底容错逻辑 > > 当脚本无法解析 Bash 命令结构时，过滤规则会**兜底放行**，钩子依然会执行。 > > ⚠️ 重要提醒：`if` 只是过滤触发，属于尽力而为的软过滤；如果需要绝对可靠的拦截 / 放行，优先使用权限系统配置，不要仅依赖该钩子过滤 ### 配置位置决定 Hook 生效范围你把 Hook 写在哪一份配置文件，直接决定它的作用域、是否可以跨项目共享： | 配置文件路径 | 生效范围 | 是否可提交仓库共享 | | ---------------------------------------- | ----------------------------- | ------------------------------------------------------------ | | `~/.claude/settings.json` | 当前电脑**所有项目**全局生效 | 否，仅本机私有，不能同步给别人 | | 项目根目录 `.claude/settings.json` | 仅当前这一个项目 | 是，可以提交 Git，团队所有人拉取后自动生效 | | 项目根目录 `.claude/settings.local.json` | 仅当前项目 | 否，Claude Code 生成该文件时会自动加入 `.gitignore`，不提交仓库，用于个人本地私有配置 | | 企业托管策略配置 | 组织内全部成员全局生效 | 是，由管理员统一管控下发 | | 插件内 `hooks/hooks.json` | 启用对应插件时生效 | 是，打包进插件，跨项目复用 | | SKILL / 子 Agent 文件头部元数据 | 对应技能 / Agent 运行期间生效 | 是，写在组件文件内，随文件共享 | 在 Claude Code 终端输入 `/hooks`，打开钩子管理面板，会按事件分组展示全部已加载的钩子。 > 全局禁用所有钩子：在配置文件顶层添加 `"disableAllHooks": true`，本机所有钩子全部关闭； ## Hook 类型详解 ### Hook 的类型绝大多数钩子使用 `type: "command"` 运行 Shell 脚本，其余 4 种拓展类型： 1. `http`：将事件数据 POST 推送到自定义接口，实现外部系统联动； 2. `mcp_tool`：调用已连接 MCP 服务的工具； 3. `prompt`：单次大模型推理，做简单条件判断； 4. `agent`：多轮带工具权限的智能校验； ### Command 类型执行 Shell 脚本或命令。这是最常用的 Hook 类型，适合明确、固定的工程规则，例如代码格式化、安全检查、文件校验等。Command Hook 不依赖模型推理，而是直接执行用户定义的脚本，因此行为更加可预测。例如检查是否执行 `rm -rf /` 这类危险命令，本质就是规则匹配：满足条件就拦截，不满足就继续执行。典型配置如下： ```json { "type": "command", "command": "./hooks/check-security.sh", "timeout": 30000 } ``` ### 基于大模型判断的 Prompt 型钩子 Prompt 型钩子适用于那些**无法通过固定规则判断，需要借助大模型理解上下文的校验场景**。与 `command` 类型 Hook 执行 Shell 脚本不同，`type: "prompt"` 会把当前 Hook 事件数据和你的提示词发送给大模型，由模型返回结构化判断结果。模型返回固定 JSON 决策格式，模型只能输出包含 `ok` 字段的 JSON，两种结果对应不同行为： - `"ok": true`：校验通过，允许本次操作正常执行。 - `"ok": false`（校验不通过，阻断 / 续跑），不同事件触发不同逻辑： - `Stop` / `SubagentStop`：本轮 AI 停止回复，把 `reason` 内容发给 AI，让它继续完成剩余工作； - `PreToolUse`：直接拒绝本次工具调用，理由作为错误提示返回给 AI，让它调整操作； - `PostToolUse` / `PostToolBatch` / `UserPromptSubmit` / `UserPromptExpansion`：直接终止本轮对话，理由作为警告展示在聊天窗口。例如，可以使用 Stop Hook 检查任务是否真正完成： ```json { "hooks": { "Stop": [ { "hooks": [ { "type": "prompt", "prompt": "Check whether all requested tasks are complete. Context: $ARGUMENTS. If unfinished, return {\"ok\": false, \"reason\": \"remaining work\"}. Otherwise return {\"ok\": true}." } ] } ] } } ``` 这个 Hook 会在 Claude 准备结束响应时触发。如果模型判断任务仍未完成，会阻止停止，并把剩余工作作为下一轮指令反馈给 Claude。 ### 基于子 Agent 的 Hook 启动一个独立子代理进行验证。相比 Prompt Hook，Agent Hook 不只是进行判断，而是可以使用 Claude Code 提供的工具完成调查，例如读取文件、搜索代码、运行测试。它适合复杂验证场景，例如确认所有 API 是否都有文档、检查修改是否影响其他模块、验证测试是否真正通过。优势是分析能力更强，但成本也更高，需要更多 Token 和执行时间。 ```json { "type": "agent", "prompt": "Verify that all unit tests pass. Run the test suite and check the results. $ARGUMENTS", "timeout": 120 } ``` Agent 类型 Hook 适用于需要真实检查项目状态的复杂验证场景。如果校验任务不仅需要理解文本，还需要读取代码、搜索文件、执行测试或运行命令，就应该考虑使用 `type: "agent"`。相比 `type: "prompt"`： - Prompt Hook 更像一个智能判断器，它只能根据 Hook 提供的数据和提示词进行一次模型判断，不具备工具调用能力； - Agent Hook 会启动一个独立 Agent，该 Agent 可以使用 Claude Code 的工具能力，根据任务主动读取文件、执行命令、分析代码仓库，再返回最终判断结果。例如，判断“所有测试是否通过”，Prompt Hook 无法主动运行测试，只能根据已有信息推测；而 Agent Hook 可以实际执行测试命令，查看真实结果后再决定是否允许流程继续。 Agent Hook 同样返回结构化判断结果： ``` { "ok": true, "reason": "All tests passed" } ``` 其中： - `ok: true` 表示验证通过； - `ok: false` 表示验证失败，并通过 `reason` 返回原因。示例：在 Claude 准备结束任务前，启动 Agent 检查测试状态： ```json { "hooks": { "Stop": [ { "hooks": [ { "type": "agent", "prompt": "Verify that all unit tests pass. Run the test suite and check the results. $ARGUMENTS", "timeout": 120 } ] } ] } } ``` 当 Claude 准备停止时，该 Agent 会执行测试检查。如果发现问题，会阻止结束流程，并把失败原因反馈给 Claude，让它继续处理。选择 Prompt 还是 Agent，可以遵循一个简单原则： - 如果答案只依赖已有上下文，例如“这段回复是否符合格式要求”“这个操作是否满足规则”，使用 Prompt Hook。 - 如果判断需要访问真实项目状态，例如“所有测试是否通过”“代码是否满足安全要求”“某个模块是否完成迁移”，使用 Agent Hook。简单来说：**Prompt Hook 负责理解和判断，Agent Hook 负责调查和验证。Agent Hook 的优势是验证能力更强，但代价是执行时间更长、消耗更多 Token，因此应该只用于真正需要深度检查的场景。** ### HTTP 类型钩子将钩子类型设为 `type: "http"`，不再执行本地 Shell 脚本，而是把事件数据通过 POST 请求推送到指定接口地址。接口收到的 JSON 结构和 Command 钩子通过 stdin 传入的数据完全一致；接口需要返回标准 JSON 格式，和 Shell 钩子 stdout 结构化输出规范相同。适用场景：把钩子逻辑交给 Web 服务、云函数、外部中台处理，例如团队共享的审计服务、集中式的安全扫描平台、公司内部的合规检查 API。示例配置：所有工具执行完成后上报本地日志服务 ```json { "hooks": { "PostToolUse": [ { "hooks": [ { "type": "http", "url": "http://localhost:8080/hooks/tool-use", "headers": { "Authorization": "Bearer $MY_TOKEN" }, "allowedEnvVars": ["MY_TOKEN"] } ] } ] } } ``` 关键规则说明 1. **拦截操作的要求** 仅靠 HTTP 响应状态码无法阻断操作；必须返回 `2xx` 成功状态码，同时在响应体输出 `hookSpecificOutput` 结构化 JSON（如 `{"permissionDecision": "deny"}`）才能拦截工具调用。 2. **环境变量插值安全限制** Header 中支持 `$VAR_NAME` / `${VAR_NAME}` 读取系统环境变量，但**只有写在 `allowedEnvVars` 数组内的变量才会被解析替换**，其余变量会保留为空字符串，防止泄露任意环境密钥。 ### mcp_tool 类型用于调用 **MCP工具** 的一种 Action 类型。例如你的团队接入了一个安全扫描 MCP： ``` Claude Code | | Hook | | MCP Tool | | Security Scanner MCP Server ``` 当代码修改完成后，Hook 可以自动调用 MCP 工具： ```json { "type": "mcp_tool", "server": "security-scanner", "tool": "scan_code", "args": { "path": "src/" } } ``` 然后 MCP Server 返回结果： ```json { "issues": [ { "severity": "high", "file": "src/auth.js", "message": "Missing authorization check" } ] } ``` Hook 可以根据返回结果决定后续行为。 ## Hook 工程设计方法论设计 Hook 方案前，先想清楚三个问题：在哪个事件上触发？用哪种类型的钩子执行？配置在哪个作用域？三个维度两两正交——你可以在任何事件上使用任何类型的 Hook，配置在任何位置。但能做不等于应该做。好的工程设计是在这三个维度上找到最恰当的交叉点——用最轻量的类型解决问题，在最小的作用域内生效。 Hook 方案设计决策框架 | 流程步骤 | 可选明细 | | :------------------- | :----------------------------------------------------------- | | **选择触发事件** | ① 操作前拦截：PreToolUse / UserPromptSubmit 等
② 操作后反馈：PostToolUse / PostToolUseFailure 等
③ 完成时检查：Stop / SubagentStop / StopFailure 等
④ 生命周期/特殊事件：SessionStart / SessionEnd / PreCompact / PostCompact / PermissionRequest / Notification 等 | | **选择 Hook 类型** | ① command：规则明确，开销最低
② prompt：单次 LLM 评估
③ agent：子代理多步推理
④ http：对接外部策略引擎
⑤ mcp_tool：复用 MCP 集成能力 | | **确定配置作用域** | ① 用户级：~/.claude/settings.json（所有项目通用）
② 项目共享：.claude/settings.json（团队规范 · 可提交 Git）
③ 项目本地：.claude/settings.local.json（个人覆盖 · 不提交）
④ 子代理专用：Frontmatter 内嵌（仅限代理生命周期） | | **应用设计原则校验** | ① 轻量优先原则：能用 command 不用 prompt，能用 prompt 不用 agent
② 最小作用域原则：能放项目级不放用户级，能放 local 不影响团队规范
③ 单一职责原则：同一工具入参，禁止多个 PreToolUse 同时修改 | ## 案例 ### PreTooluse 阻止危险命令下面是一个典型的 `PreToolUse` Hook 场景：阻止危险 Bash 命令执行。在真实开发环境中，有一些操作一旦执行几乎无法恢复，例如删除整个目录、强制覆盖主分支历史、销毁数据库等。虽然人通常会谨慎确认，但 AI Agent 在自动执行任务时可能因为理解偏差执行过于激进的操作。 `PreToolUse` Hook 可以在工具执行前介入。Claude Code 会把即将执行的 Bash 命令通过 stdin 传递给 Hook 脚本，脚本检查命令内容后决定是否允许继续： - 返回 `exit 0`：允许继续执行； - 返回 `exit 2`：阻止本次工具调用，并把原因反馈给 Claude。示例脚本 `hooks/block-dangerous.sh`： ```shell #!/bin/bash # block-dangerous.sh # 阻止危险的 Bash 命令（Hook for Claude Code / AI Agent） # ---- 1. 安全读取输入，做容错 ---- INPUT=$(cat || echo "") # 如果输入为空，直接放行（避免误杀） if [[ -z "$INPUT" ]]; then echo '{}' exit 0 fi # ---- 2. 提取命令（带容错） ---- COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // ""' 2>/dev/null || echo "") # 如果没提取到命令，也放行（可能不是 Bash 命令调用） if [[ -z "$COMMAND" ]]; then echo '{}' exit 0 fi # 调试日志（写到 stderr，不影响 Hook 响应） echo "DEBUG: Checking command: $COMMAND" >&2 # ---- 3. 标准化命令：去除多余空格、合并换行符 ---- NORMALIZED=$(echo "$COMMAND" | tr '\n' ' ' | sed 's/ */ /g' | sed 's/^ *//;s/ *$//') # ---- 4. 危险模式定义（更全面 + 防绕过） ---- # 注意：所有模式都去掉多余空格，用 [ ]* 匹配任意空格 DANGEROUS_PATTERNS=( "rm[ ]+-rf[ ]+/" "rm[ ]+-rf[ ]+~" "rm[ ]+-rf[ ]+\$HOME" "rm[ ]+-rf[ ]+/\*" "rm[ ]+-rf[ ]+--no-preserve-root" "> /dev/sd" "mkfs\." "dd if=" ":{:\|:&};:" "chmod[ ]+-R[ ]+777[ ]+/" "chmod[ ]+-R[ ]+777[ ]+~" "chown[ ]+-R[ ]+root:root[ ]+/" "git[ ]+push[ ]+--force[ ]+origin[ ]+main" "git[ ]+push[ ]+--force[ ]+origin[ ]+master" "git[ ]+push[ ]+--force-with-lease[ ]+origin[ ]+main" "git[ ]+reset[ ]+--hard[ ]+origin" "git[ ]+clean[ ]+-fdx" "curl[ ]+.*[ ]*\|[ ]*sh" "curl[ ]+.*[ ]*\|[ ]*bash" "wget[ ]+.*[ ]*\|[ ]*sh" "wget[ ]+.*[ ]*\|[ ]*bash" "sudo[ ]+rm[ ]+-rf[ ]+/" "sudo[ ]+dd if=" ":(){ :|:& };:" # Fork bomb 变体 ) # ---- 5. 逐条检查（正则匹配） ---- for pattern in "${DANGEROUS_PATTERNS[@]}"; do if [[ "$NORMALIZED" =~ $pattern ]]; then echo "BLOCKED: Command matches dangerous pattern: $pattern" >&2 cat <&2 cat <&2 exit 2 fi done # 检查证书和私钥文件 case "$FILE_PATH" in *.pem|*.key) echo "BLOCKED: Cannot modify private key file: $FILE_PATH" >&2 exit 2 ;; esac # 非敏感文件，允许继续 exit 0 ``` 配置 ```json { "hooks": { "PreToolUse": [ { "matcher": "Write|Edit", "hooks": [ { "type": "command", "command": "./hooks/protect-files.sh" } ] } ] } } ``` ### PostToolUse 文件修改后自动格式化每次 Claude 写入或修改文件后，自动运行格式化工具。 ```shell #!/bin/bash # auto-format-go.sh # Claude Code Hook: 自动格式化 Go 文件 INPUT=$(cat) # 获取修改文件路径 FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // ""') # 没有文件路径或文件不存在，跳过 if [ -z "$FILE_PATH" ] || [ ! -f "$FILE_PATH" ]; then exit 0 fi # 只处理 Go 文件 case "$FILE_PATH" in *.go) ;; *) exit 0 ;; esac # 检查 gofmt 是否存在 if ! command -v gofmt &> /dev/null; then echo "gofmt not found, skip formatting" >&2 exit 0 fi # 执行格式化 if gofmt -w "$FILE_PATH"; then echo '{"hookSpecificOutput":{"hookEventName":"PostToolUse","additionalContext":"Go file formatted with gofmt"}}' else echo '{"hookSpecificOutput":{"hookEventName":"PostToolUse","additionalContext":"gofmt failed"}}' fi exit 0 ``` 对应 `settings.json`： ```json { "hooks": { "PostToolUse": [ { "matcher": "Edit|Write", "hooks": [ { "type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/auto-format-go.sh" } ] } ] } } ``` ### PostToolUse 自动 Lint 检查格式化解决了“代码长什么样”的问题，Lint 检查解决的是“代码有没有问题”。 ```shell #!/bin/bash # go-lint.sh INPUT=$(cat) FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // ""') if [ -z "$FILE_PATH" ]; then echo '{}' exit 0 fi if [[ "$FILE_PATH" != *.go ]]; then echo '{}' exit 0 fi echo "DEBUG: Running Go lint check: $FILE_PATH" >&2 if ! command -v golangci-lint &> /dev/null; then echo '{"hookSpecificOutput":{"hookEventName":"PostToolUse","additionalContext":"golangci-lint not installed"}}' exit 0 fi LINT_RESULT=$(golangci-lint run "$FILE_PATH" 2>&1 || true) if [ -z "$LINT_RESULT" ]; then echo '{"hookSpecificOutput":{"hookEventName":"PostToolUse","additionalContext":"Go lint passed"}}' else jq -n \ --arg result "$LINT_RESULT" \ '{ hookSpecificOutput:{ decision:"block", reason:$result, hookEventName:"PostToolUse", additionalContext:$result } }' fi exit 0 ``` ### PostToolUse 工具调用审计日志为了事后追溯，谁在什么时间修改了什么文件？执行了什么命令？ ```shell #!/bin/bash # audit-log.sh # 记录所有工具调用到审计日志 # # 作为 PostToolUse hook，记录每次工具调用的详细信息 export PATH="$HOME/bin:/usr/local/bin:$PATH" # 读取 stdin 输入 INPUT=$(cat) # 确定日志目录 if [ -n "$CLAUDE_PROJECT_DIR" ]; then LOG_DIR="$CLAUDE_PROJECT_DIR/.claude/logs" else LOG_DIR="./.claude/logs" fi # 创建日志目录 mkdir -p "$LOG_DIR" # 日志文件（按日期分割） LOG_FILE="$LOG_DIR/audit-$(date +%Y-%m-%d).log" # 提取关键信息 TIMESTAMP=$(date -Iseconds) TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // "unknown"') SESSION_ID=$(echo "$INPUT" | jq -r '.session_id // "unknown"') # 提取工具输入（简化版本） TOOL_INPUT=$(echo "$INPUT" | jq -c '.tool_input // {}') # 提取工具响应状态 TOOL_SUCCESS=$(echo "$INPUT" | jq -r '.tool_response.success // true') # 写入日志 cat >> "$LOG_FILE" << EOF ================================================================================ Timestamp: $TIMESTAMP Session: $SESSION_ID Tool: $TOOL_NAME Success: $TOOL_SUCCESS Input: $TOOL_INPUT ================================================================================ EOF # 输出空 JSON（不阻止后续操作） echo '{}' ``` 对应 `settings.json`： ```json { "hooks": { "PostToolUse": [ { "matcher": "*", "hooks": [ { "type": "command", "command": "./hooks/audit-log.sh" } ] } ] } } ``` ### Stop 任务完成后自动测试 ```shell #!/bin/bash # run-go-tests.sh # Stop hook: Claude 停止前自动运行 Go 测试 export PATH="$HOME/bin:/usr/local/bin:$PATH" echo "DEBUG: Running Go tests before stopping..." >&2 # 进入项目目录 if [ -n "$CLAUDE_PROJECT_DIR" ]; then cd "$CLAUDE_PROJECT_DIR" fi # 不是 Go 项目，直接跳过 if [ ! -f "go.mod" ]; then echo '{}' exit 0 fi echo "DEBUG: Detected Go project" >&2 # 执行测试 TEST_RESULT=$(go test ./... 2>&1) TEST_EXIT_CODE=$? # 测试通过 if [ $TEST_EXIT_CODE -eq 0 ]; then echo '{"decision":"approve","reason":"All Go tests passed."}' exit 0 fi # 测试失败，阻止 Claude 停止 TEST_RESULT_ESCAPED=$(echo "$TEST_RESULT" | head -50 | jq -Rs '.') cat <

18-ClaudeCode-hooks事件驱动.

Dylan Kwok

18-ClaudeCode-hooks事件驱动