Hooks reference
- 分组：一、官方文档
- 原始链接：https://code.claude.com/docs/en/hooks
- 抓取来源：http://code.claude.com/docs/en/hooks
- 原始文件：/Users/yuanruiqin/Desktop/知识库/ClaudeCode-系统化知识库/01-官方文档/10-hooks-reference.md
- 精读版生成时间：2026-04-05 13:50:44
中文精读版（去噪）
挂钩是用户定义的 shell 命令、HTTP 端点或 LLM 提示，它们在 Claude Code 生命周期的特定点自动执行。使用此参考来查找事件架构、配置选项、JSON 输入/输出格式以及异步挂钩、HTTP 挂钩和 MCP 工具挂钩等高级功能。如果您是第一次设置 Hooks，请从指南开始。
钩子生命周期
Hooks 在 Claude Code 会话期间的特定点触发。当事件触发并且匹配器匹配时，Claude Code 会将有关该事件的 JSON 上下文传递给您的挂钩处理程序。对于命令挂钩，输入到达标准输入。对于 HTTP 挂钩，它作为 POST 请求正文到达。然后，您的处理程序可以检查输入、采取操作，并可选择返回决策。有些事件每个会话触发一次，而其他事件则在代理循环内重复触发：
下表总结了每个事件触发的时间。 Hook 事件 部分记录了每个事件的完整输入模式和决策控制选项。
| 活动 | 当它发生时 |
|---|---|
会话开始 | 当会话开始或恢复时 |
用户提示提交 | 当您提交提示时，在 Claude 处理它之前 |
PreToolUse | 在执行工具调用之前。可以屏蔽吗 |
权限请求 | 当出现权限对话框时 |
权限被拒绝 | 当自动模式分类器拒绝工具调用时。返回“{retry: true}”以告诉模型它可以重试被拒绝的工具调用 |
PostToolUse | 工具调用成功后 |
PostToolUseFailure | 工具调用失败后 |
通知 | 当 Claude Code 发送通知时 |
子代理启动 | 当子代理产生时 |
SubagentStop | 当子代理完成时 |
任务已创建 | 当通过 TaskCreate 创建任务时 |
任务已完成 | 当任务被标记为已完成时 |
停止 | 当克劳德回复完毕时 |
停止失败 | 当回合因 API 错误而结束时。输出和退出代码被忽略 |
队友空闲 | 当代理团队队友即将闲置时 |
说明已加载 | 当 CLAUDE.md 或 .claude/rules/*.md 文件加载到上下文中时。会话开始时触发 |
以及在会话期间延迟加载文件时 |
| 配置更改 |当配置文件在会话期间发生更改时 |
| CwdChanged |当工作目录更改时，例如当 Claude 执行“cd”命令时。对于使用 direnv 等工具进行反应式环境管理很有用 |
| 文件已更改 |当监视的文件在磁盘上发生更改时。 matcher 字段指定要观看的文件名 |
| 工作树创建 |当通过 --worktree 或 isolation: "worktree" 创建工作树时。替换默认的 git 行为 |
| 工作树删除 |当工作树被删除时，无论是在会话退出时还是在子代理完成时 |
| 预压缩 |上下文压缩之前 |
| 后压缩 |上下文压缩完成后 |
| 启发 |当 MCP 服务器在工具调用期间请求用户输入时 |
| 启发结果 |在用户响应 MCP 引发之后，在响应被发送回服务器之前 |
| 会话结束 |当会话终止时 |
钩子如何解析
要了解这些部分如何组合在一起，请考虑这个阻止破坏性 shell 命令的“PreToolUse”钩子。 matcher 缩小为 Bash 工具调用，而 if 条件进一步缩小为以 rm 开头的命令，因此仅当两个过滤器匹配时才会生成 block-rm.sh：
“钩子”：{ “预工具使用”：[ “匹配器”：“重击”， “钩子”：[ “类型”：“命令”， “如果”：“重击（rm *）”， “命令”：“\”$CLAUDE_PROJECT_DIR\“/.claude/hooks/block-rm.sh”
该脚本从 stdin 读取 JSON 输入，提取命令，如果包含“rm -rf”，则返回“permissionDecision”为“deny”：
#!/bin/bash
.claude/hooks/block-rm.sh
命令=$(jq -r '.tool_input.command')
如果回显“$COMMAND” | grep -q 'rm -rf';然后 jq -n '{ 钩子特定输出：{ hookEventName: "PreToolUse", 权限决定：“拒绝”， PermissionDecisionReason：“破坏性命令被钩子阻止” }' 否则 exit 0 # 允许该命令
现在假设 Claude Code 决定运行 Bash "rm -rf /tmp/build"。发生的情况如下：
下面的 Configuration 部分记录了完整的架构，每个 hook event 部分记录了您的命令接收的输入以及它可以返回的输出。
配置
挂钩在 JSON 设置文件中定义。该配置具有三层嵌套：
- 选择要响应的钩子事件，例如
PreToolUse或Stop2.添加匹配器组以在触发时进行过滤，例如“仅适用于Bash工具” - 定义一个或多个hook handlers以在匹配时运行
请参阅上面的挂钩如何解析，了解带有注释示例的完整演练。
挂钩位置
定义钩子的位置决定了它的范围：
| 地点 | 范围 | 可分享 |
|---|---|---|
~/.claude/settings.json | 您的所有项目 | 不，在您的机器本地 |
.claude/settings.json | 单个项目 | 是的，可以提交给 repo |
.claude/settings.local.json | 单个项目 | 不，gitignored |
| 托管策略设置 | 组织范围 | 是的，由管理员控制 |
插件hooks/hooks.json | 当插件启用时 | 是的，与插件捆绑在一起 |
| 技能 或 代理当组件处于活动状态时 | 是的，在组件文件中定义 |
有关设置文件分辨率的详细信息，请参阅设置。企业管理员可以使用“allowManagedHooksOnly”来阻止用户、项目和插件挂钩。请参阅Hook 配置。
匹配器模式
“matcher”字段是一个正则表达式字符串，用于在钩子触发时进行过滤。使用 "*"、"" 或完全省略 matcher 来匹配所有匹配项。每个事件类型在不同的字段上匹配：
| 活动 | 匹配器过滤什么 | 匹配器值示例 |
|---|---|---|
PreToolUse、PostToolUse、PostToolUseFailure、PermissionRequest、PermissionDenied | 工具名称 | Bash、`编辑 |
会话开始 | 会议如何开始 | 启动、恢复、清除、紧凑 |
会话结束 | 会议为何结束 | clear、resume、logout、prompt_input_exit、bypass_permissions_disabled、其他 |
通知 | 通知类型 | permission_prompt、idle_prompt、auth_success、eliitation_dialog |
子代理启动 | 代理类型 | Bash、Explore、Plan 或自定义代理名称 |
PreCompact、PostCompact | 是什么触发了压缩 | 手动、自动 |
SubagentStop | 代理类型 | 与“SubagentStart”相同的值 |
配置更改 | 配置源码 | user_settings、project_settings、local_settings、policy_settings、skills |
CwdChanged | 没有匹配器支持 | 总是在每次目录更改时触发 |
文件已更改 | 文件名（已更改文件的基本名称） | .envrc、.env，任何您想要观看的文件名 |
停止失败 | 错误类型 | rate_limit、authentication_failed、billing_error、`invalid_req |
uest、server_error、max_output_tokens、未知| |说明已加载|负载原因 |session_start、nested_traversal、path_glob_match、include、compact| |启发| MCP 服务器名称 |您配置的 MCP 服务器名称 | |启发结果| MCP 服务器名称 |与“启发”相同的值 | |UserPromptSubmit、Stop、TeammateIdle、TaskCreated、TaskCompleted、WorktreeCreate、WorktreeRemove` |没有匹配器支持 |总是在每次发生时触发 |
匹配器是正则表达式，因此“Edit|Write”匹配任一工具，“Notebook.*”匹配任何以 Notebook 开头的工具。匹配器针对 Claude Code 发送到标准输入上的钩子的 JSON 输入 中的字段运行。对于工具事件，该字段是“tool_name”。每个 hook event 部分列出了该事件的完整匹配器值集和输入架构。此示例仅在 Claude 写入或编辑文件时运行 linting 脚本：
“钩子”：{ “后工具使用”：[ "matcher": "编辑|写入", “钩子”：[ “类型”：“命令”， “命令”：“/path/to/lint-check.sh”
UserPromptSubmit、Stop、TeammateIdle、TaskCreated、TaskCompleted、WorktreeCreate、WorktreeRemove 和 CwdChanged 不支持匹配器，并且每次出现时都会触发。如果您向这些事件添加“matcher”字段，它将被静默忽略。对于工具事件，您可以通过在各个钩子处理程序上设置 if 字段 来更严格地过滤。 if 使用权限规则语法 来匹配工具名称和参数，因此 "Bash(git *)" 仅对 git 命令运行，而 "Edit(*.ts)" 仅对 TypeScript 文件运行。
匹配 MCP 工具
MCP 服务器工具在工具事件中显示为常规工具（PreToolUse、PostToolUse、PostToolUseFailure、PermissionRequest、PermissionDenied），因此您可以像匹配任何其他工具名称一样来匹配它们。MCP 工具遵循命名模式 mcp__<server>__<tool>，例如：
mcp__memory__create_entities: 内存服务器的创建实体工具
mcp__filesystem__read_file: 文件系统服务器的读文件工具
使用正则表达式模式来定位特定的 MCP 工具或工具组：
mcp__memory__.* 匹配 memory 服务器中的所有工具
mcp__.*__write.* 匹配来自任何服务器的包含“write”的任何工具
此示例记录所有内存服务器操作并验证来自任何 MCP 服务器的写入操作：
“钩子”：{ “预工具使用”：[ "matcher": "mcp__memory__.", “钩子”：[ “类型”：“命令”， "command": "echo '内存操作启动'>> ~/mcp-operations.log" }, "matcher": "mcp__.__write.*", “钩子”：[ “类型”：“命令”， “命令”：“/home/user/scripts/validate-mcp-write.py”
钩子处理程序字段
内部 hooks 数组中的每个对象都是一个钩子处理程序：shell 命令、HTTP 端点、LLM 提示符或匹配器匹配时运行的代理。有四种类型：
命令挂钩 (type: "command")：运行 shell 命令。您的脚本在标准输入上接收事件的 JSON 输入，并通过退出代码和标准输出传回结果。
HTTP hooks (type: "http")：将事件的 JSON 输入作为 HTTP POST 请求发送到 URL。端点使用与命令挂钩相同的 JSON 输出格式 通过响应正文传回结果。
Prompt hooks (type: "prompt")：向 Claude 模型发送提示以进行单轮评估。该模型以 JSON 形式返回是/否决策。请参阅基于提示的挂钩。
Agent hooks (type: "agent")：生成一个子代理，可以使用 Read、Grep 和 Glob 等工具来验证条件