# 钩子参考 > ## 文档 索引 > 获取 the 完成 文档 索引 at: https://代码.claude.com/docs/llms.txt > 使用 this 文件 to disc结束 所有 可用 页s 之前探索 further. # 钩子参考 > 参考 for Claude 代码 hook 事件s, 配置 模式, JSON 输入/输出 格式s, 退出 代码s, 异步 钩子, HTTP 钩子, 及时 钩子, and MCP 工具 钩子. For a 快速入门 指南 with 示例,看见 [Automate 工作流s with 钩子](/en/钩子-指南). 钩子 are 用户-定义 命令行 命令, HTTP 结束points, or LLM 及时s that 执行 自动所有y at 特定 points in Claude 代码's lifecycle. 使用 this 参考 to看 上 事件 模式s, 配置 选项, JSON 输入/输出 格式s, and 先进 features 像 异步 钩子, HTTP 钩子, and MCP 工具 钩子. If you're建立 钩子 for the 第一个 时间, 启动 with the [指南](/en/钩子-指南) instead. ## Hook lifecycle 钩子 f怒 at 特定 points 期间 a Claude 代码 会话. When an 事件 f怒s and a 匹配er 匹配es, Claude 代码 passes JSON 上下文 about the 事件 to your hook 处理器. For 命令 钩子, 输入 arrives on stdin. For HTTP 钩子, it arrives as the POST 请求 正文. Your 处理器 can then检查 the 输入, take 行动, and 可选ly 回报 a 决定. 一些 事件s f怒 once per 会话, while others f怒 repeatedly 内部 the 代理ic loop: The 表 be低 总和marizes when 每个 事件 f怒s. The [Hook 事件s](#hook-事件s) 节 documents the 满 输入 模式 and 决定 控制 选项 for 每个 one. | 事件 | When it f怒s | | :------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------- | | `会话开始` | When a 会话 begins or 恢复s | | `用户及时Submit` | When you submit a 及时, 之前 Claude 流程es it | | `工具使用前` | 之前 a 工具 c所有 执行s. Can 块 it | | `许可请求` | When a 许可 dia日志 应用ears | | `许可拒绝` | When a 工具 c所有 is 拒绝 by the auto 模式 阶级ifier. 回报 `{重试: 真实}` to tell the 模型 it may 重试 the 拒绝 工具 c所有 | | `工具使用后` | 之后 a 工具 c所有 succeeds | | `工具使用后失败` | 之后 a 工具 c所有 fails | | `通知` | When Claude 代码 发送s a 通知 | | `子代理t艺术` | When a sub代理 is spawned | | `子代理顶部` | When a sub代理 finishes | | `任务创建d` | When a 任务 is being 创建d via `任务创建` | | `任务完成` | When a 任务 is being marked as 完成 | | `停止` | When Claude finishes responding | | `停止失败` | When the turn 结束s due to an API 错误. 输出 and 退出 代码 are 忽略 | | `团队mate空闲` | When an [代理 团队](/en/代理-团队) 团队mate is about to 前往 空闲 | | `说明加载` | When a CLAUDE.md or `.claude/规则/*.md` 文件 is 加载 into 上下文. F怒s at 会话 启动 and when 文件 are lazily 加载 期间 a 会话 | | `Config更改` | When a 配置 文件 更改s 期间 a 会话 | | `Cwd更改d` | When the工作 目录 更改s, for 示例 when Claude 执行s a `cd` 命令. 有用 for 响应式 环境 管理 with 工具 像 d怒nv | | `文件更改d` | When a观看ed 文件 更改s on disk. The `匹配er` 字段 规格ifies which 文件名称s to观看 | | `工作树创建` | When a 工作树 is being 创建d via `--工作树` or `isolation: "工作树"`. 替换s 默认 Git behavior | | `工作树移除` | When a 工作树 is being 移除, either at 会话 退出 or when a sub代理 finishes | | `Pre紧凑` | 之前 上下文 紧凑ion | | `Post紧凑` | 之后 上下文 紧凑ion 完成s | | `E合法ation` | When an MCP 服务器 请求s 用户 输入 期间 a 工具 c所有 | | `E合法ation结果` | 之后 a 用户 responds to an MCP e合法ation, 之前 the 响应 is 发送 返回 to the 服务器 | | `会话结束` | When a 会话 终止s | ### How a hook resolves To看见 how these 片s fit together, consider this `工具使用前` hook that 块s destructive 命令行 命令. The `匹配er` nar行s to Bash 工具 c所有s and the `if` 条件 nar行s further to 命令 启动ing with `rm`, so `块-rm.sh` only spawns when 机器人h 过滤s 匹配: ```json 主题={空} { "钩子": { "工具使用前": [ { "匹配er": "Bash", "钩子": [ { "类型": "命令", "if": "Bash(rm *)", "命令": "\"$CLAUDE_项目_DIR\"/.claude/钩子/块-rm.sh" } ] } ] } } ``` The 脚本 读取s the JSON 输入 from stdin, 提取s the 命令, and 回报s a `许可决定` of `"拒绝"` if it contains `rm -rf`: ```bash 主题={空} #!/bin/bash # .claude/钩子/块-rm.sh 命令=$(jq -r '.工具_输入.命令') if echo "$命令" | grep -q 'rm -rf'; then jq -n '{ hook特定输出: { hook事件名称: "工具使用前", 许可决定: "拒绝", 许可决定原因: "Destructive 命令 阻塞 by hook" } }' else 退出 0 # 允许 the 命令 fi ``` Now s上pose Claude 代码 decides to 运行 `Bash "rm -rf /tmp/构建"`. Here's what h应用ens: The `工具使用前` 事件 f怒s. Claude 代码 发送s the 工具 输入 as JSON on stdin to the hook: ```json 主题={空} { "工具_名称": "Bash", "工具_输入": { "命令": "rm -rf /tmp/构建" }, ... } ``` The 匹配er `"Bash"` 匹配es the 工具 名称, so this hook 组 激活s. If you omit the 匹配er or 使用 `"*"`, the 组 激活s on 每个 occurrence of the 事件. The `if` 条件 `"Bash(rm *)"` 匹配es be原因 the 命令 启动s with `rm`, so this 处理器 spawns. If the 命令 had been `npm 测试`, the `if` 检查 would fail and `块-rm.sh` would never 运行,避免 the 流程 spawn 结束负责人. The `if` 字段 is 可选; without it, 每个 处理器 in the 匹配ed 组 运行s. The 脚本检查s the 满 命令 and 查找s `rm -rf`, so it prints a 决定 to stdout: ```json 主题={空} { "hook特定输出": { "hook事件名称": "工具使用前", "许可决定": "拒绝", "许可决定原因": "Destructive 命令 阻塞 by hook" } } ``` If the 命令 had been a 安全r `rm` variant 像 `rm 文件.txt`, the 脚本 would hit `退出 0` instead, which tells Claude 代码 to 允许 the 工具 c所有 with no further 行动. Claude 代码 读取s the JSON 决定, 块s the 工具 c所有, and 显示s Claude the 原因. The [配置](#配置) 节 be低 documents the 满 模式, and 每个 [hook 事件](#hook-事件s) 节 documents what 输入 your 命令 接收s and what 输出 it can 回报. ## 配置 钩子 are 定义 in JSON 设置 文件. The 配置 has three 级别s of nesting: 1. Choose a [hook 事件](#hook-事件s) to respond to, 像 `工具使用前` or `停止` 2. 添加 a [匹配er 组](#匹配er-模式s) to 过滤 when it f怒s, 像 "only for the Bash 工具" 3. De好 one or 更多 [hook 处理器s](#hook-处理器-字段s) to 运行 when 匹配ed 看见 [How a hook resolves](#how-a-hook-resolves) above for a 完成走th粗糙 with an annotated 示例. This 页 使用s 特定 条款 for 每个 级别: **hook 事件** for the lifecycle point, **匹配er 组** for the 过滤, and **hook 处理器** for the 命令行 命令, HTTP 结束point, 及时, or 代理 that 运行s. "Hook" on its own refers to the 一般 feature. ### Hook locations Where you de好 a hook determines its 范围: | Location | 范围 | Share能够 | | :--------------------------------------------------------- | :---------------------------- | :--------------------------------- | | `~/.claude/设置.json` | 所有 your 项目s | No, 本地 to your machine | | `.claude/设置.json` | Single 项目 | Yes, can be 提交ted to the repo | | `.claude/设置.本地.json` | Single 项目 | No, Git忽略 | | 管理 政策 设置 | 组织-wide | Yes, 管理员-受控 | | [插件](/en/插件s) `钩子/钩子.json` | When 插件 is 启用 | Yes, 捆绑d with the 插件 | | [技能](/en/技能) or [代理](/en/sub-代理s) front事情 | While the 组件 is 活跃 | Yes, 定义 in the 组件 文件 | For 详情s on 设置 文件 决议,看见 [设置](/en/设置). 企业 管理员s can 使用 `允许管理钩子Only` to 块 用户, 项目, and 插件 钩子.看见 [Hook 配置](/en/设置#hook-配置). ### 匹配er 模式s The `匹配er` 字段 is a regex 字符串 that 过滤s when 钩子 f怒. 使用 `"*"`, `""`, or omit `匹配er` 整个ly to 匹配 所有 occurrences. 每个 事件 类型 匹配es on a 不同 字段: | 事件 | What the 匹配er 过滤s | 示例 匹配er 值s | | :------------------------------------------------------------------------------------------------------------- | :-------------------------------------- | :------------------------------------------------------------------------------------------------------------------------ | | `工具使用前`, `工具使用后`, `工具使用后失败`, `许可请求`, `许可拒绝` | 工具 名称 | `Bash`, `编辑\|写入`, `mcp__.*` | | `会话开始` | how the 会话 开始 | `启动上`, `恢复`, `清楚`, `紧凑` | | `会话结束` | why the 会话 结束 | `清楚`, `恢复`, `标志ut`, `及时_输入_退出`, `bypass_权限_禁用`, `other` | | `通知` | 通知 类型 | `许可_及时`, `空闲_及时`, `auth_成功`, `e合法ation_dia日志` | | `子代理t艺术` | 代理 类型 | `Bash`, `探索`, `计划`, or 习俗 代理 名称s | | `Pre紧凑`, `Post紧凑` | what triggered 紧凑ion | `手册`, `auto` | | `子代理顶部` | 代理 类型 | 相同 值s as `子代理t艺术` | | `Config更改` | 配置 来源 | `用户_设置`, `项目_设置`, `本地_设置`, `政策_设置`, `技能` | | `Cwd更改d` | no 匹配er 支持 | al方式s f怒s on 每个 目录 更改 | | `文件更改d` | 文件名称 (基础名称 of the 更改d 文件) | `.envrc`, `.env`, 任何 文件名称 you 想要 to观看 | | `停止失败` | 错误 类型 | `速率_限制`, `认证_失败`, `billing_错误`, `无效_请求`, `服务器_错误`, `max_输出_令牌s`, `unknown` | | `说明加载` | 加载 原因 | `会话_启动`, `nested_traversal`, `路径_glob_匹配`, `include`, `紧凑` | | `E合法ation` | MCP 服务器 名称 | your con图d MCP 服务器 名称s | | `E合法ation结果` | MCP 服务器 名称 | 相同 值s as `E合法ation` | | `用户及时Submit`, `停止`, `团队mate空闲`, `任务创建d`, `任务完成`, `工作树创建`, `工作树移除` | no 匹配er 支持 | al方式s f怒s on 每个 occurrence | The 匹配er is a regex, so `编辑|写入` 匹配es either 工具 and `注意book.*` 匹配es 任何 工具 启动ing with 注意book. The 匹配er 运行s a收益st a 字段 from the [JSON 输入](#hook-输入-and-输出) that Claude 代码 发送s to your hook on stdin. For 工具 事件s, that 字段 is `工具_名称`. 每个 [hook 事件](#hook-事件s) 节 列表s the 满 设置 of 匹配er 值s and the 输入 模式 for that 事件. This 示例 运行s a linting 脚本 only when Claude 写入s or 编辑s a 文件: ```json 主题={空} { "钩子": { "工具使用后": [ { "匹配er": "编辑|写入", "钩子": [ { "类型": "命令", "命令": "/路径/to/lint-检查.sh" } ] } ] } } ``` `用户及时Submit`, `停止`, `团队mate空闲`, `任务创建d`, `任务完成`, `工作树创建`, `工作树移除`, and `Cwd更改d` don't 支持 匹配ers and al方式s f怒 on 每个 occurrence. If you 添加 a `匹配er` 字段 to these 事件s, it is 沉默ly 忽略. For 工具 事件s, you can 过滤 更多 nar行ly by设置 the [`if` 字段](#常见-字段s) on 个人 hook 处理器s. `if` 使用s [许可 规则 syn税](/en/权限) to 匹配 a收益st the 工具 名称 and 参数 together, so `"Bash(Git *)"` 运行s only for `Git` 命令 and `"编辑(*.ts)"` 运行s only for 类型脚本 文件. #### 匹配 MCP 工具 [MCP](/en/mcp) 服务器 工具 应用ear as 常规 工具 in 工具 事件s (`工具使用前`, `工具使用后`, `工具使用后失败`, `许可请求`, `许可拒绝`), so you can 匹配 them the 相同 方式 you 匹配 任何 other 工具 名称. MCP 工具 fol低 the naming 模式 `mcp____`, for 示例: * `mcp__记忆__创建_entities`: 记忆 服务器's 创建 entities 工具 * `mcp__文件系统__读取_文件`: 文件系统 服务器's 读取 文件 工具 * `mcp__GitHub__搜索_repositories`: GitHub 服务器's 搜索 工具 使用 regex 模式s to 目标 特定 MCP 工具 or 组s of 工具: * `mcp__记忆__.*` 匹配es 所有 工具 from the `记忆` 服务器 * `mcp__.*__写入.*` 匹配es 任何 工具包含 "写入" from 任何 服务器 This 示例 日志s 所有 记忆 服务器 运营 and 验证s 写入 运营 from 任何 MCP 服务器: ```json 主题={空} { "钩子": { "工具使用前": [ { "匹配er": "mcp__记忆__.*", "钩子": [ { "类型": "命令", "命令": "echo '记忆 运营 启动' >> ~/mcp-运营.日志" } ] }, { "匹配er": "mcp__.*__写入.*", "钩子": [ { "类型": "命令", "命令": "/home/用户/脚本s/验证-mcp-写入.py" } ] } ] } } ``` ### Hook 处理器 字段s 每个 对象 in the 内部 `钩子` 数组 is a hook 处理器: the 命令行 命令, HTTP 结束point, LLM 及时, or 代理 that 运行s when the 匹配er 匹配es. There are four 类型s: * **[命令 钩子](#命令-hook-字段s)** (`类型: "命令"`): 运行 a 命令行 命令. Your 脚本 接收s the 事件's [JSON 输入](#hook-输入-and-输出) on stdin and communicates 结果s 返回 th粗糙 退出 代码s and stdout. * **[HTTP 钩子](#http-hook-字段s)** (`类型: "http"`): 发送 the 事件's JSON 输入 as an HTTP POST 请求 to a URL. The 结束point communicates 结果s 返回 th粗糙 the 响应 正文 using the 相同 [JSON 输出 格式](#json-输出) as 命令 钩子. * **[及时 钩子](#及时-and-代理-hook-字段s)** (`类型: "及时"`): 发送 a 及时 to a Claude 模型 for single-turn 评价. The 模型 回报s a yes/no 决定 as JSON.看见 [及时-基础d 钩子](#及时-基础d-钩子). * **[代理 钩子](#及时-and-代理-hook-字段s)** (`类型: "代理"`): spawn a sub代理 that can 使用 工具 像 读取, Grep, and Glob to 验证 条件 之前返回 a 决定.看见 [代理-基础d 钩子](#代理-基础d-钩子). #### 常见 字段s These 字段s 应用ly to 所有 hook 类型s: | 字段 | 必需 | 描述 | | :-------------- | :------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `类型` | yes | `"命令"`, `"http"`, `"及时"`, or `"代理"` | | `if` | no | 许可 规则 syn税 to 过滤 when this hook 运行s, such as `"Bash(Git *)"` or `"编辑(*.ts)"`. The hook only spawns if the 工具 c所有 匹配es the 模式. Only evaluated on 工具 事件s: `工具使用前`, `工具使用后`, `工具使用后失败`, `许可请求`, and `许可拒绝`. On other 事件s, a hook with `if` 设置 never 运行s. 使用s the 相同 syn税 as [许可 规则](/en/权限) | | `超时` | no | Seconds 之前 取消ing. 默认s: 600 for 命令, 30 for 及时, 60 for 代理 | | `状态消息` | no | 习俗 sp内部 消息 显示ed while the hook 运行s | | `once` | no | If `真实`, 运行s only once per 会话 then is 移除. 技能 only, not 代理s.看见 [钩子 in 技能 and 代理s](#钩子-in-技能-and-代理s) | #### 命令 hook 字段s In 添加ition to the [常见 字段s](#常见-字段s), 命令 钩子 接受 these 字段s: | 字段 | 必需 | 描述 | | :-------- | :------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `命令` | yes | 命令行 命令 to 执行 | | `异步` | no | If `真实`, 运行s in the 背景 without 阻塞.看见 [运行 钩子 in the 背景](#运行-钩子-in-the-背景) | | `命令行` | no | 命令行 to 使用 for this hook. 接受s `"bash"` (默认) or `"权力命令行"`.设置 `"权力命令行"` 运行s the 命令 via 权力命令行 on 风ows. Does not requ怒 `CLAUDE_代码_使用_权力命令行_工具` since 钩子 spawn 权力命令行 直接ly | #### HTTP hook 字段s In 添加ition to the [常见 字段s](#常见-字段s), HTTP 钩子 接受 these 字段s: | 字段 | 必需 | 描述 | | :--------------- | :------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `url` | yes | URL to 发送 the POST 请求 to | | `页眉s` | no | 添加itional HTTP 页眉s as 键-值 对s. 值s 支持 环境 可变 interpolation using `$VAR_名称` or `${VAR_名称}` syn税. Only 可变s 列出 in `允许EnvVars` are 解决 | | `允许EnvVars` | no | 列表 of 环境 可变 名称s that may be interpo晚d into 页眉 值s. 参考文献 to un列出 可变s are 替换d with 空 字符串s. 必需 for 任何 env var interpolation to 工作 | Claude 代码 发送s the hook's [JSON 输入](#hook-输入-and-输出) as the POST 请求 正文 with `满意-类型: 应用程序/json`. The 响应 正文 使用s the 相同 [JSON 输出 格式](#json-输出) as 命令 钩子. 错误处理 differs from 命令 钩子: non-2xx 响应s, 连接 失败s, and 超时s 所有 produce 非阻塞 错误 that 允许 执行 to 继续. To 块 a 工具 c所有 or 拒绝 a 许可, 回报 a 2xx 响应 with a JSON 正文包含 `决定: "块"` or a `hook特定输出` with `许可决定: "拒绝"`. This 示例 发送s `工具使用前` 事件s to a 本地 验证 服务, authenticating with a 令牌 from the `MY_令牌` 环境 可变: ```json 主题={空} { "钩子": { "工具使用前": [ { "匹配er": "Bash", "钩子": [ { "类型": "http", "url": "http://本地host:8080/钩子/pre-工具-使用", "超时": 30, "页眉s": { "授权": "Bearer $MY_令牌" }, "允许EnvVars": ["MY_令牌"] } ] } ] } } ``` #### 及时 and 代理 hook 字段s In 添加ition to the [常见 字段s](#常见-字段s), 及时 and 代理 钩子 接受 these 字段s: | 字段 | 必需 | 描述 | | :------- | :------- | :------------------------------------------------------------------------------------------ | | `及时` | yes | 及时 文本 to 发送 to the 模型. 使用 `$参数` as a placeh更旧 for the hook 输入 JSON | | `模型` | no | 模型 to 使用 for 评价. 默认s to a 快 模型 | 所有 匹配 钩子 运行 in 平行, and 相同 处理器s are de重复d 自动所有y. 命令 钩子 are de重复d by 命令 字符串, and HTTP 钩子 are de重复d by URL. 处理器s 运行 in the 当前 目录 with Claude 代码's 环境. The `$CLAUDE_代码_远程` 环境 可变 is 设置 to `"真实"` in 远程 网页 环境s and not 设置 in the 本地 CLI. ### 参考 脚本s by 路径 使用 环境变量 to 参考 hook 脚本s relative to the 项目 or 插件 根, 注意较少 of the工作 目录 when the hook 运行s: * `$CLAUDE_项目_DIR`: the 项目 根. Wrap in quotes to handle 路径s with s步伐s. * `${CLAUDE_插件_根}`: the 插件's 安装 目录, for 脚本s 捆绑d with a [插件](/en/插件s). 更改s on 每个 插件 更新. * `${CLAUDE_插件_数据}`: the 插件's [持续 数据 目录](/en/插件s-参考#持续-数据-目录), for 依赖 and 州 that should survive 插件 更新s. This 示例 使用s `$CLAUDE_项目_DIR` to 运行 a style 检查er from the 项目's `.claude/钩子/` 目录 之后 任何 `写入` or `编辑` 工具 c所有: ```json 主题={空} { "钩子": { "工具使用后": [ { "匹配er": "写入|编辑", "钩子": [ { "类型": "命令", "命令": "\"$CLAUDE_项目_DIR\"/.claude/钩子/检查-style.sh" } ] } ] } } ``` De好 插件 钩子 in `钩子/钩子.json` with an 可选 顶部-级别 `描述` 字段. When a 插件 is 启用, its 钩子 合并 with your 用户 and 项目 钩子. This 示例 运行s a 格式ting 脚本 捆绑d with the 插件: ```json 主题={空} { "描述": "自动 代码 格式ting", "钩子": { "工具使用后": [ { "匹配er": "写入|编辑", "钩子": [ { "类型": "命令", "命令": "${CLAUDE_插件_根}/脚本s/格式.sh", "超时": 30 } ] } ] } } ``` 看见 the [插件 组件s 参考](/en/插件s-参考#钩子) for 详情s on创建 插件 钩子. ### 钩子 in 技能 and 代理s In 添加ition to 设置 文件 and 插件s, 钩子 can be 定义 直接ly in [技能](/en/技能) and [子代理](/en/sub-代理s) using front事情. These 钩子 are 范围d to the 组件's lifecycle and only 运行 when that 组件 is 活跃. 所有 hook 事件s are 支持ed. For 子代理, `停止` 钩子 are 自动所有y 转换ed to `子代理顶部` since that is the 事件 that f怒s when a sub代理 完成s. 钩子 使用 the 相同 配置 格式 as 设置-基础d 钩子 but are 范围d to the 组件's life时间 and 干净ed 上 when it finishes. This 技能 de好s a `工具使用前` hook that 运行s a 安全 验证 脚本 之前 每个 `Bash` 命令: ```yaml 主题={空} --- 名称: 安全-运营 描述: Per形式 运营 with 安全 检查s 钩子: 工具使用前: - 匹配er: "Bash" 钩子: - 类型: 命令 命令: "./脚本s/安全-检查.sh" --- ``` 代理s 使用 the 相同 格式 in their YAML front事情. ### The `/钩子` menu 类型 `/钩子` in Claude 代码 to 打开 a 读取-only 浏览器 for your con图d 钩子. The menu 显示s 每个 hook 事件 with a count of con图d 钩子, lets you drill into 匹配ers, and 显示s the 满 详情s of 每个 hook 处理器. 使用 it to 验证 配置, 检查 which 设置 文件 a hook came from, or检查 a hook's 命令, 及时, or URL. The menu 显示s 所有 four hook 类型s: `命令`, `及时`, `代理`, and `http`. 每个 hook is 标签ed with a `[类型]` pre修复 and a 来源 indicating where it was 定义: * `用户`: from `~/.claude/设置.json` * `项目`: from `.claude/设置.json` * `本地`: from `.claude/设置.本地.json` * `插件`: from a 插件's `钩子/钩子.json` * `会话`: 注册 in 记忆 for the 当前 会话 * `Built-in`: 注册 内部ly by Claude 代码 选择ing a hook 打开s a 详情视图显示 its 事件, 匹配er, 类型, 来源 文件, and the 满 命令, 及时, or URL. The menu is 读取-only: to 添加, 修改, or 移除 钩子, 编辑 the 设置 JSON 直接ly or ask Claude to make the 更改. ### 禁用 or 移除 钩子 To 移除 a hook, 删除 its 条目 from the 设置 JSON 文件. To 节奏rarily 禁用 所有 钩子 without removing them, 设置 `"禁用所有钩子": 真实` in your 设置 文件. There is no 方式 to 禁用 an 个人 hook while保持 it in the 配置. The `禁用所有钩子`设置 re规格ts the 管理 设置 hierarchy. If an 管理员 has con图d 钩子 th粗糙 管理 政策 设置, `禁用所有钩子` 设置 in 用户, 项目, or 本地 设置 cannot 禁用 those 管理 钩子. Only `禁用所有钩子` 设置 at the 管理 设置 级别 can 禁用 管理 钩子. 直接 编辑s to 钩子 in 设置 文件 are 正常ly picked 上 自动所有y by the 文件观看er. ## Hook 输入 and 输出 命令 钩子 接收 JSON 数据 via stdin and communicate 结果s th粗糙 退出 代码s, stdout, and stderr. HTTP 钩子 接收 the 相同 JSON as the POST 请求 正文 and communicate 结果s th粗糙 the HTTP 响应 正文. This 节 c结束s 字段s and behavior 常见 to 所有 事件s. 每个 事件's 节 under [Hook 事件s](#hook-事件s) includes its 特定 输入 模式 and 决定 控制 选项. ### 常见 输入 字段s Hook 事件s 接收 these 字段s as JSON, in 添加ition to 事件-特定 字段s documented in 每个 [hook 事件](#hook-事件s) 节. For 命令 钩子, this JSON arrives via stdin. For HTTP 钩子, it arrives as the POST 请求 正文. | 字段 | 描述 | | :---------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `会话_id` | 当前 会话 标识符 | | `tran脚本_路径` | 路径 to 对话 JSON | | `cwd` | 当前工作 目录 when the hook is invoked | | `许可_模式` | 当前 [许可 模式](/en/权限#许可-模式s): `"默认"`, `"计划"`, `"接受its"`, `"auto"`, `"don任务"`, or `"bypass权限"`. Not 所有 事件s 接收 this 字段:看见 每个 事件's JSON 示例 be低 to 检查 | | `hook_事件_名称` | 名称 of the 事件 that f怒d | When 运行中 with `--代理` or 内部 a sub代理, two 添加itional 字段s are 包含: | 字段 | 描述 | | :----------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `代理_id` | 唯一 标识符 for the sub代理. 现在 only when the hook f怒s 内部 a sub代理 c所有. 使用 this to distinguish sub代理 hook c所有s from 主-th读取 c所有s. | | `代理_类型` | 代理 名称 (for 示例, `"探索"` or `"安全-审查员"`). 现在 when the 会话 使用s `--代理` or the hook f怒s 内部 a sub代理. For 子代理, the sub代理's 类型 takes precedence 结束 the 会话's `--代理` 值. | For 示例, a `工具使用前` hook for a Bash 命令 接收s this on stdin: ```json 主题={空} { "会话_id": "abc123", "tran脚本_路径": "/home/用户/.claude/项目s/.../tran脚本.jsonl", "cwd": "/home/用户/my-项目", "许可_模式": "默认", "hook_事件_名称": "工具使用前", "工具_名称": "Bash", "工具_输入": { "命令": "npm 测试" } } ``` The `工具_名称` and `工具_输入` 字段s are 事件-特定. 每个 [hook 事件](#hook-事件s) 节 documents the 添加itional 字段s for that 事件. ### 退出 代码 输出 The 退出 代码 from your hook 命令 tells Claude 代码 whether the 行动 should proceed, be 阻塞, or be 忽略. **退出 0** 手段 成功. Claude 代码 parses stdout for [JSON 输出 字段s](#json-输出). JSON 输出 is only 已处理 on 退出 0. For 最多 事件s, stdout is only 显示n in 详细 模式 (`Ctrl+O`). The 异常 are `用户及时Submit` and `会话开始`, where stdout is 加 as 上下文 that Claude can看见 and act on. **退出 2** 手段 a 阻塞 错误. Claude 代码 ignores stdout and 任何 JSON in it. Instead, stderr 文本 is fed 返回 to Claude as an 错误 消息. The 效果 dep结束s on the 事件: `工具使用前` 块s the 工具 c所有, `用户及时Submit` 拒绝s the 及时, and so on.看见 [退出 代码 2 behavior](#退出-代码-2-behavior-per-事件) for the 满 列表. **任何 other 退出 代码** is a 非阻塞 错误. stderr is 显示n in 详细 模式 (`Ctrl+O`) and 执行 继续s. For 示例, a hook 命令 脚本 that 块s d愤怒ous Bash 命令: ```bash 主题={空} #!/bin/bash # 读取s JSON 输入 from stdin, 检查s the 命令 命令=$(jq -r '.工具_输入.命令' &2 退出 2 # 阻塞 错误: 工具 c所有 is pr事件ed fi 退出 0 # 成功: 工具 c所有 proceeds ``` #### 退出 代码 2 behavior per 事件 退出 代码 2 is the 方式 a hook 信号s "停止, don't do this." The 效果 dep结束s on the 事件, be原因 一些 事件s re现在 行动s that can be 阻塞 (像 a 工具 c所有 that hasn't h应用ened yet) and others re现在 薄gs that al就绪 h应用ened or can't be pr事件ed. | Hook 事件 | Can 块? | What h应用ens on 退出 2 | | :------------------- | :--------- | :----------------------------------------------------------------------------------------------------------------------------------- | | `工具使用前` | Yes | 块s the 工具 c所有 | | `许可请求` | Yes | Denies the 许可 | | `用户及时Submit` | Yes | 块s 及时 处理中 and erases the 及时 | | `停止` | Yes | Pr事件s Claude from停止, 继续s the 对话 | | `子代理顶部` | Yes | Pr事件s the sub代理 from停止 | | `团队mate空闲` | Yes | Pr事件s the 团队mate from 前往ing 空闲 (团队mate 继续s工作) | | `任务创建d` | Yes | Rolls 返回 the 任务 创建 | | `任务完成` | Yes | Pr事件s the 任务 from being marked as 完成 | | `Config更改` | Yes | 块s the 配置 更改 from taking 效果 (except `政策_设置`) | | `停止失败` | No | 输出 and 退出 代码 are 忽略 | | `工具使用后` | No | 显示s stderr to Claude (工具 al就绪 ran) | | `工具使用后失败` | No | 显示s stderr to Claude (工具 al就绪 失败) | | `许可拒绝` | No | 退出 代码 and stderr are 忽略 (否认 al就绪 occurred). 使用 JSON `hook特定输出.重试: 真实` to tell the 模型 it may 重试 | | `通知` | No | 显示s stderr to 用户 only | | `子代理t艺术` | No | 显示s stderr to 用户 only | | `会话开始` | No | 显示s stderr to 用户 only | | `会话结束` | No | 显示s stderr to 用户 only | | `Cwd更改d` | No | 显示s stderr to 用户 only | | `文件更改d` | No | 显示s stderr to 用户 only | | `Pre紧凑` | No | 显示s stderr to 用户 only | | `Post紧凑` | No | 显示s stderr to 用户 only | | `E合法ation` | Yes | Denies the e合法ation | | `E合法ation结果` | Yes | 块s the 响应 (行动 becomes 下降) | | `工作树创建` | Yes | 任何 non-zero 退出 代码 原因s 工作树 创建 to fail | | `工作树移除` | No | 失败s are 日志ged in 调试 模式 only | | `说明加载` | No | 退出 代码 is 忽略 | ### HTTP 响应处理 HTTP 钩子 使用 HTTP 状态 代码s and 响应 bodies instead of 退出 代码s and stdout: * **2xx with an 空 正文**: 成功, 等价 to 退出 代码 0 with no 输出 * **2xx with a 简单 文本 正文**: 成功, the 文本 is 加 as 上下文 * **2xx with a JSON 正文**: 成功, 解析 using the 相同 [JSON 输出](#json-输出) 模式 as 命令 钩子 * **Non-2xx 状态**: 非阻塞 错误, 执行 继续s * **连接 失败 or 超时**: 非阻塞 错误, 执行 继续s 不像 命令 钩子, HTTP 钩子 cannot 信号 a 阻塞 错误 th粗糙 状态 代码s alone. To 块 a 工具 c所有 or 拒绝 a 许可, 回报 a 2xx 响应 with a JSON 正文包含 the 恰当 决定 字段s. ### JSON 输出 退出 代码s let you 允许 or 块, but JSON 输出 gives you 好r-g雨ed 控制. Instead of 退出ing with 代码 2 to 块, 退出 0 and print a JSON 对象 to stdout. Claude 代码 读取s 特定 字段s from that JSON to 控制 behavior,包括 [决定 控制](#决定-控制) for 阻塞,允许, or escalating to the 用户. You must choose one 方法 per hook, not 机器人h: either 使用 退出 代码s alone for 信号ing, or 退出 0 and print JSON for 结构化 控制. Claude 代码 only 流程es JSON on 退出 0. If you 退出 2, 任何 JSON is 忽略. Your hook's stdout must contain only the JSON 对象. If your 命令行 pro文件 prints 文本 on 启动上, it can interfere with JSON分析.看见 [JSON 验证 失败](/en/钩子-指南#json-验证-失败) in the 故障排除 指南. Hook 输出 injected into 上下文 (`添加itional上下文`, `系统消息`, or 简单 stdout) is c应用ed at 10,000 字符s. 输出 that exceeds this 限制 is 保存 to a 文件 and 替换d with a pre视图 and 文件 路径, the 相同 方式 large 工具 结果s are 已处理. The JSON 对象 支持s three 种类s of 字段s: * **普遍 字段s** 像 `继续` 工作 across 所有 事件s. These are 列出 in the 表 be低. * **顶部-级别 `决定` and `原因`** are 使用d by 一些 事件s to 块 or provide 反馈. * **`hook特定输出`** is a nested 对象 for 事件s that 需要 richer 控制. It requ怒s a `hook事件名称` 字段 设置 to the 事件 名称. | 字段 | 默认 | 描述 | | :--------------- | :------ | :------------------------------------------------------------------------------------------------------------------------- | | `继续` | `真实` | If `虚假`, Claude 停止s 处理中 整个ly 之后 the hook 运行s. Takes precedence 结束 任何 事件-特定 决定 字段s | | `停止原因` | 无 | 消息 显示n to the 用户 when `继续` is `虚假`. Not 显示n to Claude | | `s上press输出` | `虚假` | If `真实`, 隐藏s stdout from 详细 模式 输出 | | `系统消息` | 无 |警告 消息 显示n to the 用户 | To 停止 Claude 整个ly 注意较少 of 事件 类型: ```json 主题={空} { "继续": 虚假, "停止原因": "构建 失败, 修复 错误 之前 继续" } ``` #### 决定 控制 Not 每个 事件 支持s 阻塞 or控制 behavior th粗糙 JSON. The 事件s that do 每个 使用 a 不同 设置 of 字段s to express that 决定. 使用 this 表 as a 快 参考 之前写作 a hook: | 事件s | 决定 模式 | 键 字段s | | :-------------------------------------------------------------------------------------------------------------------------- | :----------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | 用户及时Submit, 工具使用后, 工具使用后失败, 停止, 子代理顶部, Config更改 | 顶部-级别 `决定` | `决定: "块"`, `原因` | | 团队mate空闲, 任务创建d, 任务完成 | 退出 代码 or `继续: 虚假` | 退出 代码 2 块s the 行动 with stderr 反馈. JSON `{"继续": 虚假, "停止原因": "..."}` also 停止s the 团队mate 整个ly, 匹配 `停止` hook behavior | | 工具使用前 | `hook特定输出` | `许可决定` (允许/拒绝/ask/defer), `许可决定原因` | | 许可请求 | `hook特定输出` | `决定.behavior` (允许/拒绝) | | 许可拒绝 | `hook特定输出` | `重试: 真实` tells the 模型 it may 重试 the 拒绝 工具 c所有 | | 工作树创建 | 路径 回报 | 命令 hook prints 路径 on stdout; HTTP hook 回报s `hook特定输出.工作树路径`. Hook 失败 or错过 路径 fails 创建 | | E合法ation | `hook特定输出` | `行动` (接受/下降/取消), `满意` (形式 字段 值s for 接受) | | E合法ation结果 | `hook特定输出` | `行动` (接受/下降/取消), `满意` (形式 字段 值s 结束ride) | | 工作树移除, 通知, 会话结束, Pre紧凑, Post紧凑, 说明加载, 停止失败, Cwd更改d, 文件更改d | 无 | No 决定 控制. 使用d for side 效果s 像日志 or 干净上 | Here are 示例 of 每个 模式 in 行动: 使用d by `用户及时Submit`, `工具使用后`, `工具使用后失败`, `停止`, `子代理顶部`, and `Config更改`. The only 值 is `"块"`. To 允许 the 行动 to proceed, omit `决定` from your JSON, or 退出 0 without 任何 JSON at 所有: ```json 主题={空} { "决定": "块", "原因": "测试 suite must pass 之前 proceeding" } ``` 使用s `hook特定输出` for richer 控制: 允许, 拒绝, or esca晚 to the 用户. You can also 修改 工具 输入 之前 it 运行s or inject 添加itional 上下文 for Claude.看见 [工具使用前 决定 控制](#工具使用前-决定-控制) for the 满 设置 of 选项. ```json 主题={空} { "hook特定输出": { "hook事件名称": "工具使用前", "许可决定": "拒绝", "许可决定原因": "数据库 写入s are not 允许" } } ``` 使用s `hook特定输出` to 允许 or 拒绝 a 许可 请求 on behalf of the 用户. When允许, you can also 修改 the 工具's 输入 or 应用ly 许可 规则 so the 用户 isn't 及时ed a收益.看见 [许可请求 决定 控制](#许可请求-决定-控制) for the 满 设置 of 选项. ```json 主题={空} { "hook特定输出": { "hook事件名称": "许可请求", "决定": { "behavior": "允许", "更新输入": { "命令": "npm 运行 lint" } } } } ``` For 延长 示例包括 Bash 命令 验证, 及时过滤, and auto-批准 脚本s,看见 [What you can automate](/en/钩子-指南#what-you-can-automate) in the 指南 and the [Bash 命令 有效ator 参考 实施](https://GitHub.com/anthropics/claude-代码/blob/主/示例/钩子/bash_命令_有效ator_示例.py). ## Hook 事件s 每个 事件 corresponds to a point in Claude 代码's lifecycle where 钩子 can 运行. The 节s be低 are 有序 to 匹配 the lifecycle: from 会话 设置 th粗糙 the 代理ic loop to 会话 结束. 每个 节 describes when the 事件 f怒s, what 匹配ers it 支持s, the JSON 输入 it 接收s, and how to 控制 behavior th粗糙 输出. ### 会话开始 运行s when Claude 代码 启动s a 新 会话 or 恢复s an 现有 会话. 有用 for 加载ing 开发 上下文 像 现有 问题s or 最近 更改s to your 代码基础, or建立 环境变量. For 静态 上下文 that does not requ怒 a 脚本, 使用 [CLAUDE.md](/en/记忆) instead. 会话开始 运行s on 每个 会话, so keep these 钩子 快. Only `类型: "命令"` 钩子 are 支持ed. The 匹配er 值 corresponds to how the 会话 was 启动: | 匹配er | When it f怒s | | :-------- | :------------------------------------- | | `启动上` | 新 会话 | | `恢复` | `--恢复`, `--继续`, or `/恢复` | | `清楚` | `/清楚` | | `紧凑` | Auto or 手册 紧凑ion | #### 会话开始 输入 In 添加ition to the [常见 输入 字段s](#常见-输入-字段s), 会话开始 钩子 接收 `来源`, `模型`, and 可选ly `代理_类型`. The `来源` 字段 indicates how the 会话 开始: `"启动上"` for 新 会话s, `"恢复"` for 恢复d 会话s, `"清楚"` 之后 `/清楚`, or `"紧凑"` 之后 紧凑ion. The `模型` 字段 contains the 模型 标识符. If you 启动 Claude 代码 with `claude --代理 `, an `代理_类型` 字段 contains the 代理 名称. ```json 主题={空} { "会话_id": "abc123", "tran脚本_路径": "/用户s/.../.claude/项目s/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl", "cwd": "/用户s/...", "hook_事件_名称": "会话开始", "来源": "启动上", "模型": "claude-sonnet-4-6" } ``` #### 会话开始 决定 控制 任何 文本 your hook 脚本 prints to stdout is 加 as 上下文 for Claude. In 添加ition to the [JSON 输出 字段s](#json-输出) 可用 to 所有 钩子, you can 回报 these 事件-特定 字段s: | 字段 | 描述 | | :------------------ | :------------------------------------------------------------------------ | | `添加itional上下文` | 字符串 加 to Claude's 上下文. Mul提示le 钩子' 值s are concatenated | ```json 主题={空} { "hook特定输出": { "hook事件名称": "会话开始", "添加itional上下文": "My 添加itional 上下文 here" } } ``` #### Persist 环境变量 会话开始 钩子 have access to the `CLAUDE_ENV_文件` 环境 可变, which provides a 文件 路径 where you can persist 环境变量 for subsequent Bash 命令. To 设置 个人 环境变量, 写入 `出口` 州ments to `CLAUDE_ENV_文件`. 使用 应用结束 (`>>`) to preserve 可变s 设置 by other 钩子: ```bash 主题={空} #!/bin/bash if [ -n "$CLAUDE_ENV_文件" ]; then echo '出口 节点_ENV=生产' >> "$CLAUDE_ENV_文件" echo '出口 调试_日志=真实' >> "$CLAUDE_ENV_文件" echo '出口 路径="$路径:./节点_模块s/.bin"' >> "$CLAUDE_ENV_文件" fi 退出 0 ``` To capture 所有 环境 更改s from 设置 命令, 比较 the 导出 可变s 之前 and 之后: ```bash 主题={空} #!/bin/bash ENV_之前=$(出口 -p | 类别) # 运行 your 设置 命令 that 修改 the 环境 来源 ~/.nvm/nvm.sh nvm 使用 20 if [ -n "$CLAUDE_ENV_文件" ]; then ENV_之后=$(出口 -p | 类别) comm -13 > "$CLAUDE_ENV_文件" fi 退出 0 ``` 任何 可变s written to this 文件 will be 可用 in 所有 subsequent Bash 命令 that Claude 代码 执行s 期间 the 会话. `CLAUDE_ENV_文件` is 可用 for 会话开始, [Cwd更改d](#cwd更改d), and [文件更改d](#文件更改d) 钩子. Other hook 类型s do not have access to this 可变. ### 说明加载 F怒s when a `CLAUDE.md` or `.claude/规则/*.md` 文件 is 加载 into 上下文. This 事件 f怒s at 会话 启动 for 渴望ly-加载 文件 and a收益 更晚 when 文件 are lazily 加载, for 示例 when Claude accesses a sub目录 that contains a nested `CLAUDE.md` or when 条件 规则 with `路径s:` front事情 匹配. The hook does not 支持 阻塞 or 决定 控制. It 运行s 异步ly for observability 目的s. The 匹配er 运行s a收益st `加载_原因`. For 示例, 使用 `"匹配er": "会话_启动"` to f怒 only for 文件 加载 at 会话 启动, or `"匹配er": "路径_glob_匹配|nested_traversal"` to f怒 only for 懒惰 加载s. #### 说明加载 输入 In 添加ition to the [常见 输入 字段s](#常见-输入-字段s), 说明加载 钩子 接收 these 字段s: | 字段 | 描述 | | :------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `文件_路径` | Absolute 路径 to the instruction 文件 that was 加载 | | `记忆_类型` | 范围 of the 文件: `"用户"`, `"项目"`, `"本地"`, or `"管理"` | | `加载_原因` | Why the 文件 was 加载: `"会话_启动"`, `"nested_traversal"`, `"路径_glob_匹配"`, `"include"`, or `"紧凑"`. The `"紧凑"` 值 f怒s when instruction 文件 are re-加载 之后 a 紧凑ion 事件 | | `globs` | 路径 glob 模式s from the 文件's `路径s:` front事情, if 任何. 现在 only for `路径_glob_匹配` 加载s | | `trigger_文件_路径` | 路径 to the 文件 whose access triggered this 加载, for 懒惰 加载s | | `parent_文件_路径` | 路径 to the parent instruction 文件 that 包含 this one, for `include` 加载s | ```json 主题={空} { "会话_id": "abc123", "tran脚本_路径": "/用户s/.../.claude/项目s/.../tran脚本.jsonl", "cwd": "/用户s/my-项目", "hook_事件_名称": "说明加载", "文件_路径": "/用户s/my-项目/CLAUDE.md", "记忆_类型": "项目", "加载_原因": "会话_启动" } ``` #### 说明加载 决定 控制 说明加载 钩子 have no 决定 控制. They cannot 块 or 修改 instruction 加载ing. 使用 this 事件 for audit日志, 合规 跟踪ing, or observability. ### 用户及时Submit 运行s when the 用户 submits a 及时, 之前 Claude 流程es it. This 允许s you to 添加 添加itional 上下文 基础d on the 及时/对话, 验证 及时s, or 块 确定 类型s of 及时s. #### 用户及时Submit 输入 In 添加ition to the [常见 输入 字段s](#常见-输入-字段s), 用户及时Submit 钩子 接收 the `及时` 字段包含 the 文本 the 用户 submitted. ```json 主题={空} { "会话_id": "abc123", "tran脚本_路径": "/用户s/.../.claude/项目s/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl", "cwd": "/用户s/...", "许可_模式": "默认", "hook_事件_名称": "用户及时Submit", "及时": "写入 a 功能 to calcu晚 the 事实orial of a 数字" } ``` #### 用户及时Submit 决定 控制 `用户及时Submit` 钩子 can 控制 whether a 用户 及时 is 已处理 and 添加 上下文. 所有 [JSON 输出 字段s](#json-输出) are 可用. There are two 方式s to 添加 上下文 to the 对话 on 退出 代码 0: * **简单 文本 stdout**: 任何 non-JSON 文本 written to stdout is 加 as 上下文 * **JSON with `添加itional上下文`**: 使用 the JSON 格式 be低 for 更多 控制. The `添加itional上下文` 字段 is 加 as 上下文 简单 stdout is 显示n as hook 输出 in the tran脚本. The `添加itional上下文` 字段 is 加 更多 discretely. To 块 a 及时, 回报 a JSON 对象 with `决定` 设置 to `"块"`: | 字段 | 描述 | | :------------------ | :----------------------------------------------------------------------------------------------------------------- | | `决定` | `"块"` pr事件s the 及时 from being 已处理 and erases it from 上下文. Omit to 允许 the 及时 to proceed | | `原因` | 显示n to the 用户 when `决定` is `"块"`. Not 加 to 上下文 | | `添加itional上下文` | 字符串 加 to Claude's 上下文 | ```json 主题={空} { "决定": "块", "原因": "解释 for 决定", "hook特定输出": { "hook事件名称": "用户及时Submit", "添加itional上下文": "My 添加itional 上下文 here" } } ``` The JSON 格式 isn't 必需 for 简单 使用 案例s. To 添加 上下文, you can print 简单 文本 to stdout with 退出 代码 0. 使用 JSON when you 需要 to 块 及时s or 想要 更多 结构化 控制. ### 工具使用前 运行s 之后 Claude 创建s 工具 参数 and 之前 处理中 the 工具 c所有. 匹配es on 工具 名称: `Bash`, `编辑`, `写入`, `读取`, `Glob`, `Grep`, `代理`, `网页获取`, `网页搜索`, `Ask用户问题`, `退出计划模式`, and 任何 [MCP 工具 名称s](#匹配-mcp-工具). 使用 [工具使用前 决定 控制](#工具使用前-决定-控制) to 允许, 拒绝, ask, or defer the 工具 c所有. #### 工具使用前 输入 In 添加ition to the [常见 输入 字段s](#常见-输入-字段s), 工具使用前 钩子 接收 `工具_名称`, `工具_输入`, and `工具_使用_id`. The `工具_输入` 字段s dep结束 on the 工具: ##### Bash 执行s 命令行 命令. | 字段 | 类型 | 示例 | 描述 | | :------------------ | :------ | :----------------- | :-------------------------------------------- | | `命令` | 字符串 | `"npm 测试"` | The 命令行 命令 to 执行 | | `描述` | 字符串 | `"运行 测试 suite"` | 可选 描述 of what the 命令 does | | `超时` | 数字 | `120000` | 可选 超时 in milliseconds | | `运行_in_背景` | 布尔值 | `虚假` | Whether to 运行 the 命令 in 背景 | ##### 写入 创建s or 结束写入s a 文件. | 字段 | 类型 | 示例 | 描述 | | :---------- | :----- | :-------------------- | :--------------------------------- | | `文件_路径` | 字符串 | `"/路径/to/文件.txt"` | Absolute 路径 to the 文件 to 写入 | | `满意` | 字符串 | `"文件 满意"` | 满意 to 写入 to the 文件 | ##### 编辑 替换s a 字符串 in an 现有 文件. | 字段 | 类型 | 示例 | 描述 | | :------------ | :------ | :-------------------- | :--------------------------------- | | `文件_路径` | 字符串 | `"/路径/to/文件.txt"` | Absolute 路径 to the 文件 to 编辑 | | `旧_字符串` | 字符串 | `"原始 文本"` | 文本 to 查找 and 替换 | | `新_字符串` | 字符串 | `"替换ment 文本"` | 替换ment 文本 | | `替换_所有` | 布尔值 | `虚假` | Whether to 替换 所有 occurrences | ##### 读取 读取s 文件 满意s. | 字段 | 类型 | 示例 | 描述 | | :---------- | :----- | :-------------------- | :----------------------------------------- | | `文件_路径` | 字符串 | `"/路径/to/文件.txt"` | Absolute 路径 to the 文件 to 读取 | | `off设置` | 数字 | `10` | 可选 行 数字 to 启动 读取ing from | | `限制` | 数字 | `50` | 可选 数字 of 行s to 读取 | ##### Glob 查找s 文件 匹配 a glob 模式. | 字段 | 类型 | 示例 | 描述 | | :-------- | :----- | :--------------- | :--------------------------------------------------------------------- | | `模式` | 字符串 | `"**/*.ts"` | Glob 模式 to 匹配 文件 a收益st | | `路径` | 字符串 | `"/路径/to/dir"` | 可选 目录 to 搜索 in. 默认s to 当前工作 目录 | ##### Grep 搜索es 文件 满意s with 常规 表达s. | 字段 | 类型 | 示例 | 描述 | | :------------ | :------ | :--------------- | :------------------------------------------------------------------------------------ | | `模式` | 字符串 | `"TODO.*修复"` | 常规 表达 模式 to 搜索 for | | `路径` | 字符串 | `"/路径/to/dir"` | 可选 文件 or 目录 to 搜索 in | | `glob` | 字符串 | `"*.ts"` | 可选 glob 模式 to 过滤 文件 | | `输出_模式` | 字符串 | `"满意"` | `"满意"`, `"文件_with_匹配es"`, or `"count"`. 默认s to `"文件_with_匹配es"` | | `-i` | 布尔值 | `真实` | 案例 in敏感 搜索 | | `multi行` | 布尔值 | `虚假` | 启用 multi行 匹配 | ##### 网页获取 获取es and 流程es 网页 满意. | 字段 | 类型 | 示例 | 描述 | | :------- | :----- | :---------------------------- | :----------------------------------- | | `url` | 字符串 | `"https://示例.com/api"` | URL to 获取 满意 from | | `及时` | 字符串 | `"提取 the API 结束points"` | 及时 to 运行 on the 获取ed 满意 | ##### 网页搜索 搜索es the 网页. | 字段 | 类型 | 示例 | 描述 | | :---------------- | :----- | :----------------------------- | :------------------------------------------------ | | `查询` | 字符串 | `"react 钩子 最佳实践"` | 搜索 查询 | | `允许_do主s` | 数组 | `["docs.示例.com"]` | 可选: only include 结果s from these do主s | | `阻塞_do主s` | 数组 | `["spam.示例.com"]` | 可选: exclude 结果s from these do主s | ##### 代理 Spawns a [sub代理](/en/sub-代理s). | 字段 | 类型 | 示例 | 描述 | | :-------------- | :----- | :------------------------- | :------------------------------------------- | | `及时` | 字符串 | `"查找 所有 API 结束points"` | The 任务 for the 代理 to per形式 | | `描述` | 字符串 | `"查找 API 结束points"` | 短 描述 of the 任务 | | `sub代理_类型` | 字符串 | `"探索"` | 类型 of 专业 代理 to 使用 | | `模型` | 字符串 | `"sonnet"` | 可选 模型 alias to 结束ride the 默认 | ##### Ask用户问题 Asks the 用户 one to four mul提示le-选择 问题s. | 字段 | 类型 | 示例 | 描述 | | :---------- | :----- | :----------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `问题s` | 数组 | `[{"问题": "Which 框架?", "页眉": "框架", "选项": [{"标签": "React"}], "multi选择": 虚假}]` | 问题s to 现在, 每个 with a `问题` 字符串, 短 `页眉`, `选项` 数组, and 可选 `multi选择` flag | | `答案s` | 对象 | `{"Which 框架?": "React"}` | 可选. 映射s 问题 文本 to the 选择ed 选项 标签. Multi-选择 答案s join 标签s with commas. Claude does not 设置 this 字段; s上ply it via `更新输入` to 答案 计划matic所有y | #### 工具使用前 决定 控制 `工具使用前` 钩子 can 控制 whether a 工具 c所有 proceeds. 不像 other 钩子 that 使用 a 顶部-级别 `决定` 字段, 工具使用前 回报s its 决定 内部 a `hook特定输出` 对象. This gives it richer 控制: four 结果s (允许, 拒绝, ask, or defer) plus the ability to 修改 工具 输入 之前 执行. | 字段 | 描述 | | :------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `许可决定` | `"允许"`跳s the 许可 及时. `"拒绝"` pr事件s the 工具 c所有. `"ask"` 及时s the 用户 to 确认. `"defer"` 退出s 优雅ly so the 工具 can be 恢复d 更晚. [拒绝 and ask 规则](/en/权限#manage-权限) 静止 应用ly when a hook 回报s `"允许"` | | `许可决定原因` | For `"允许"` and `"ask"`, 显示n to the 用户 but not Claude. For `"拒绝"`, 显示n to Claude. For `"defer"`, 忽略 | | `更新输入` | Modifies the 工具's 输入 参数 之前 执行. 替换s the 整个 输入 对象, so include 未改变 字段s a长side modified ones. Combine with `"允许"` to auto-批准, or `"ask"` to 显示 the modified 输入 to the 用户. For `"defer"`, 忽略 | | `添加itional上下文` | 字符串 加 to Claude's 上下文 之前 the 工具 执行s. For `"defer"`, 忽略 | When mul提示le 工具使用前 钩子 回报 不同 决定s, precedence is `拒绝` > `defer` > `ask` > `允许`. When a hook 回报s `"ask"`, the 许可 及时 显示ed to the 用户 includes a 标签识别 where the hook came from: for 示例, `[用户]`, `[项目]`, `[插件]`, or `[本地]`. This 帮助s 用户s understand which 配置 来源 is请求 确认. ```json 主题={空} { "hook特定输出": { "hook事件名称": "工具使用前", "许可决定": "允许", "许可决定原因": "My 原因 here", "更新输入": { "字段_to_修改": "新 值" }, "添加itional上下文": "当前 环境: 生产. Proceed with caution." } } ``` `Ask用户问题` and `退出计划模式` requ怒 用户 交互 and 正常ly 块 in [non-交互 模式](/en/负责人较少) with the `-p` flag.返回 `许可决定: "允许"` together with `更新输入` satisfies that 需求: the hook 读取s the 工具's 输入 from stdin, collects the 答案 th粗糙 your own UI, and 回报s it in `更新输入` so the 工具 运行s without 及时ing.返回 `"允许"` alone is not sufficient for these 工具. For `Ask用户问题`, echo 返回 the 原始 `问题s` 数组 and 添加 an [`答案s`](#ask用户问题) 对象 m应用ing 每个 问题's 文本 to the chosen 答案. 工具使用前 之前ly 使用d 顶部-级别 `决定` and `原因` 字段s, but these are deprecated for this 事件. 使用 `hook特定输出.许可决定` and `hook特定输出.许可决定原因` instead. The deprecated 值s `"批准"` and `"块"` 映射 to `"允许"` and `"拒绝"` re规格tively. Other 事件s 像 工具使用后 and 停止 继续 to 使用 顶部-级别 `决定` and `原因` as their 当前 格式. #### Defer a 工具 c所有 for 更晚 `"defer"` is for 集成s that 运行 `claude -p` as a sub流程 and 读取 its JSON 输出, such as an 代理 SDK 应用 or a 习俗 UI built on 顶部 of Claude 代码. It lets that c所有ing 流程 暂停 Claude at a 工具 c所有, collect 输入 th粗糙 its own 接口, and 恢复 where it 左 off. Claude 代码 honors this 值 only in [non-交互 模式](/en/负责人较少) with the `-p` flag. In 交互 会话s it 日志s a警告 and ignores the hook 结果. The `defer` 值 requ怒s Claude 代码 v2.1.89 or 更晚. 更早 版本s do not recognize it and the 工具 proceeds th粗糙 the 正常 许可 f低. The `Ask用户问题` 工具 is the 典型 案例: Claude 想要s to ask the 用户 一些薄g, but there is no 终端 to 答案 in. The 圆旅行 工作s 像 this: 1. Claude c所有s `Ask用户问题`. The `工具使用前` hook f怒s. 2. The hook 回报s `许可决定: "defer"`. The 工具 does not 执行. The 流程 退出s with `停止_原因: "工具_deferred"` and the 待处理 工具 c所有 保存 in the tran脚本. 3. The c所有ing 流程 读取s `deferred_工具_使用` from the SDK 结果, 表面s the 问题 in its own UI, and 等待s for an 答案. 4. The c所有ing 流程 运行s `claude -p --恢复 `. The 相同 工具 c所有 f怒s `工具使用前` a收益. 5. The hook 回报s `许可决定: "允许"` with the 答案 in `更新输入`. The 工具 执行s and Claude 继续s. The `deferred_工具_使用` 字段 carries the 工具's `id`, `名称`, and `输入`. The `输入` is the 参数 Claude gene速率d for the 工具 c所有, captured 之前 执行: ```json 主题={空} { "类型": "结果", "sub类型": "成功", "停止_原因": "工具_deferred", "会话_id": "abc123", "deferred_工具_使用": { "id": "工具u_01abc", "名称": "Ask用户问题", "输入": { "问题s": [{ "问题": "Which 框架?", "页眉": "框架", "选项": [{"标签": "React"}, {"标签": "Vue"}], "multi选择": 虚假 }] } } } ``` There is no 超时 or 重试 限制. The 会话 re主s on disk until you 恢复 it. If the 答案 is not 就绪 when you 恢复, the hook can 回报 `"defer"` a收益 and the 流程 退出s the 相同 方式. The c所有ing 流程 控制s when to break the loop by 事件u所有y返回 `"允许"` or `"拒绝"` from the hook. `"defer"` only 工作s when Claude makes a single 工具 c所有 in the turn. If Claude makes 几个 工具 c所有s at once, `"defer"` is 忽略 with a警告 and the 工具 proceeds th粗糙 the 正常 许可 f低. The 常量雨t exists be原因 恢复 can only re-运行 one 工具: there is no 方式 to defer one c所有 from a batch without leaving the others 未解决. If the deferred 工具 is no 长er 可用 when you 恢复, the 流程 退出s with `停止_原因: "工具_deferred_不可用"` and `is_错误: 真实` 之前 the hook f怒s. This h应用ens when an MCP 服务器 that provided the 工具 is not 连接 for the 恢复d 会话. The `deferred_工具_使用` pay加载 is 静止 包含 so you can identify which 工具 went错过. `--恢复` does not 恢复 the 许可 模式 from the 之前 会话. Pass the 相同 `--许可-模式` flag on 恢复 that was 活跃 when the 工具 was deferred. Claude 代码 日志s a警告 if the 模式s differ. ### 许可请求 运行s when the 用户 is 显示n a 许可 dia日志. 使用 [许可请求 决定 控制](#许可请求-决定-控制) to 允许 or 拒绝 on behalf of the 用户. 匹配es on 工具 名称, 相同 值s as 工具使用前. #### 许可请求 输入 许可请求 钩子 接收 `工具_名称` and `工具_输入` 字段s 像 工具使用前 钩子, but without `工具_使用_id`. An 可选 `许可_建议s` 数组 contains the "al方式s 允许" 选项 the 用户 would 正常ly看见 in the 许可 dia日志. The 差异 is when the hook f怒s: 许可请求 钩子 运行 when a 许可 dia日志 is about to be 显示n to the 用户, while 工具使用前 钩子 运行 之前 工具 执行 注意较少 of 许可 状态. ```json 主题={空} { "会话_id": "abc123", "tran脚本_路径": "/用户s/.../.claude/项目s/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl", "cwd": "/用户s/...", "许可_模式": "默认", "hook_事件_名称": "许可请求", "工具_名称": "Bash", "工具_输入": { "命令": "rm -rf 节点_模块s", "描述": "移除 节点_模块s 目录" }, "许可_建议s": [ { "类型": "添加规则", "规则": [{ "工具名称": "Bash", "规则满意": "rm -rf 节点_模块s" }], "behavior": "允许", "destination": "本地设置" } ] } ``` #### 许可请求 决定 控制 `许可请求` 钩子 can 允许 or 拒绝 许可 请求s. In 添加ition to the [JSON 输出 字段s](#json-输出) 可用 to 所有 钩子, your hook 脚本 can 回报 a `决定` 对象 with these 事件-特定 字段s: | 字段 | 描述 | | :------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `behavior` | `"允许"` 授予s the 许可, `"拒绝"` denies it | | `更新输入` | For `"允许"` only: modifies the 工具's 输入 参数 之前 执行. 替换s the 整个 输入 对象, so include 未改变 字段s a长side modified ones | | `更新权限` | For `"允许"` only: 数组 of [许可 更新 entries](#许可-更新-entries) to 应用ly, such as添加 an 允许 规则 or改变 the 会话 许可 模式 | | `消息` | For `"拒绝"` only: tells Claude why the 许可 was 拒绝 | | `中断` | For `"拒绝"` only: if `真实`, 停止s Claude | ```json 主题={空} { "hook特定输出": { "hook事件名称": "许可请求", "决定": { "behavior": "允许", "更新输入": { "命令": "npm 运行 lint" } } } } ``` #### 许可 更新 entries The `更新权限` 输出 字段 and the [`许可_建议s` 输入 字段](#许可请求-输入) 机器人h 使用 the 相同 数组 of 条目 对象s. 每个 条目 has a `类型` that determines its other 字段s, and a `destination` that 控制s where the 更改 is written. | `类型` | 字段s | 效果 | | :------------------ | :--------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `添加规则` | `规则`, `behavior`, `destination` | 添加s 许可 规则. `规则` is an 数组 of `{工具名称, 规则满意?}` 对象s. Omit `规则满意` to 匹配 the 整体 工具. `behavior` is `"允许"`, `"拒绝"`, or `"ask"` | | `替换规则` | `规则`, `behavior`, `destination` | 替换s 所有 规则 of the given `behavior` at the `destination` with the provided `规则` | | `移除规则` | `规则`, `behavior`, `destination` | 移除s 匹配 规则 of the given `behavior` | | `设置模式` | `模式`, `destination` | 更改s the 许可 模式. 有效 模式s are `默认`, `接受its`, `don任务`, `bypass权限`, and `计划` | | `添加总监ies` | `总监ies`, `destination` | 添加s工作 总监ies. `总监ies` is an 数组 of 路径 字符串s | | `移除总监ies` | `总监ies`, `destination` | 移除s工作 总监ies | The `destination` 字段 on 每个 条目 determines whether the 更改 stays in 记忆 or persists to a 设置 文件. | `destination` | 写入s to | | :---------------- | :---------------------------------------------- | | `会话` | 内存中 only, discarded when the 会话 结束s | | `本地设置` | `.claude/设置.本地.json` | | `项目设置` | `.claude/设置.json` | | `用户设置` | `~/.claude/设置.json` | A hook can echo one of the `许可_建议s` it 接收 as its own `更新权限` 输出, which is 等价 to the 用户选择 that "al方式s 允许" 选项 in the dia日志. ### 工具使用后 运行s 立即ly 之后 a 工具 完成s 成功ly. 匹配es on 工具 名称, 相同 值s as 工具使用前. #### 工具使用后 输入 `工具使用后` 钩子 f怒 之后 a 工具 has al就绪 执行d 成功ly. The 输入 includes 机器人h `工具_输入`, the 参数 发送 to the 工具, and `工具_响应`, the 结果 it 返回. The 精确 模式 for 机器人h dep结束s on the 工具. ```json 主题={空} { "会话_id": "abc123", "tran脚本_路径": "/用户s/.../.claude/项目s/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl", "cwd": "/用户s/...", "许可_模式": "默认", "hook_事件_名称": "工具使用后", "工具_名称": "写入", "工具_输入": { "文件_路径": "/路径/to/文件.txt", "满意": "文件 满意" }, "工具_响应": { "文件路径": "/路径/to/文件.txt", "成功": 真实 }, "工具_使用_id": "工具u_01ABC123..." } ``` #### 工具使用后 决定 控制 `工具使用后` 钩子 can provide 反馈 to Claude 之后 工具 执行. In 添加ition to the [JSON 输出 字段s](#json-输出) 可用 to 所有 钩子, your hook 脚本 can 回报 these 事件-特定 字段s: | 字段 | 描述 | | :--------------------- | :----------------------------------------------------------------------------------------- | | `决定` | `"块"` 及时s Claude with the `原因`. Omit to 允许 the 行动 to proceed | | `原因` | 解释 显示n to Claude when `决定` is `"块"` | | `添加itional上下文` | 添加itional 上下文 for Claude to consider | | `更新MCP工具输出` | For [MCP 工具](#匹配-mcp-工具) only: 替换s the 工具's 输出 with the provided 值 | ```json 主题={空} { "决定": "块", "原因": "解释 for 决定", "hook特定输出": { "hook事件名称": "工具使用后", "添加itional上下文": "添加itional 信息 for Claude" } } ``` ### 工具使用后失败 运行s when a 工具 执行 fails. This 事件 f怒s for 工具 c所有s that 抛出 错误 or 回报 失败 结果s. 使用 this to 日志 失败s, 发送 警觉s, or provide 正确ive 反馈 to Claude. 匹配es on 工具 名称, 相同 值s as 工具使用前. #### 工具使用后失败 输入 工具使用后失败 钩子 接收 the 相同 `工具_名称` and `工具_输入` 字段s as 工具使用后, a长 with 错误 信息 as 顶部-级别 字段s: ```json 主题={空} { "会话_id": "abc123", "tran脚本_路径": "/用户s/.../.claude/项目s/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl", "cwd": "/用户s/...", "许可_模式": "默认", "hook_事件_名称": "工具使用后失败", "工具_名称": "Bash", "工具_输入": { "命令": "npm 测试", "描述": "运行 测试 suite" }, "工具_使用_id": "工具u_01ABC123...", "错误": "命令 退出ed with non-zero 状态 代码 1", "is_中断": 虚假 } ``` | 字段 | 描述 | | :------------- | :------------------------------------------------------------------------------ | | `错误` | 字符串描述 what went 错误 | | `is_中断` | 可选 布尔值 indicating whether the 失败 was 原因d by 用户 中断ion | #### 工具使用后失败 决定 控制 `工具使用后失败` 钩子 can provide 上下文 to Claude 之后 a 工具 失败. In 添加ition to the [JSON 输出 字段s](#json-输出) 可用 to 所有 钩子, your hook 脚本 can 回报 these 事件-特定 字段s: | 字段 | 描述 | | :------------------ | :------------------------------------------------------------ | | `添加itional上下文` | 添加itional 上下文 for Claude to consider a长side the 错误 | ```json 主题={空} { "hook特定输出": { "hook事件名称": "工具使用后失败", "添加itional上下文": "添加itional 信息 about the 失败 for Claude" } } ``` ### 许可拒绝 运行s when the [auto 模式](/en/许可-模式s#eliminate-及时s-with-auto-模式) 阶级ifier denies a 工具 c所有. This hook only f怒s in auto 模式: it does not 运行 when you 手册ly 拒绝 a 许可 dia日志, when a `工具使用前` hook 块s a c所有, or when a `拒绝` 规则 匹配es. 使用 it to 日志 阶级ifier 否认s, ad公正 配置, or tell the 模型 it may 重试 the 工具 c所有. 匹配es on 工具 名称, 相同 值s as 工具使用前. #### 许可拒绝 输入 In 添加ition to the [常见 输入 字段s](#常见-输入-字段s), 许可拒绝 钩子 接收 `工具_名称`, `工具_输入`, `工具_使用_id`, and `原因`. ```json 主题={空} { "会话_id": "abc123", "tran脚本_路径": "/用户s/.../.claude/项目s/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl", "cwd": "/用户s/...", "许可_模式": "auto", "hook_事件_名称": "许可拒绝", "工具_名称": "Bash", "工具_输入": { "命令": "rm -rf /tmp/构建", "描述": "干净 构建 目录" }, "工具_使用_id": "工具u_01ABC123...", "原因": "Auto 模式 拒绝: 命令 目标s a 路径 外部 the 项目" } ``` | 字段 | 描述 | | :------- | :------------------------------------------------------------ | | `原因` | The 阶级ifier's 解释 for why the 工具 c所有 was 拒绝 | #### 许可拒绝 决定 控制 许可拒绝 钩子 can tell the 模型 it may 重试 the 拒绝 工具 c所有. 回报 a JSON 对象 with `hook特定输出.重试` 设置 to `真实`: ```json 主题={空} { "hook特定输出": { "hook事件名称": "许可拒绝", "重试": 真实 } } ``` When `重试` is `真实`, Claude 代码 添加s a 消息 to the 对话告诉 the 模型 it may 重试 the 工具 c所有. The 否认 itself is not 反转d. If your hook does not 回报 JSON, or 回报s `重试: 虚假`, the 否认 stands and the 模型 接收s the 原始 拒绝 消息. ### 通知 运行s when Claude 代码 发送s 通知s. 匹配es on 通知 类型: `许可_及时`, `空闲_及时`, `auth_成功`, `e合法ation_dia日志`. Omit the 匹配er to 运行 钩子 for 所有 通知 类型s. 使用 单独 匹配ers to 运行 不同 处理器s de待处理 on the 通知 类型. This 配置 triggers a 许可-特定 警觉 脚本 when Claude 需要s 许可 批准 and a 不同 通知 when Claude has been 空闲: ```json 主题={空} { "钩子": { "通知": [ { "匹配er": "许可_及时", "钩子": [ { "类型": "命令", "命令": "/路径/to/许可-警觉.sh" } ] }, { "匹配er": "空闲_及时", "钩子": [ { "类型": "命令", "命令": "/路径/to/空闲-通知.sh" } ] } ] } } ``` #### 通知 输入 In 添加ition to the [常见 输入 字段s](#常见-输入-字段s), 通知 钩子 接收 `消息` with the 通知 文本, an 可选 `标题`, and `通知_类型` indicating which 类型 f怒d. ```json 主题={空} { "会话_id": "abc123", "tran脚本_路径": "/用户s/.../.claude/项目s/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl", "cwd": "/用户s/...", "hook_事件_名称": "通知", "消息": "Claude 需要s your 许可 to 使用 Bash", "标题": "许可 需要ed", "通知_类型": "许可_及时" } ``` 通知 钩子 cannot 块 or 修改 通知s. In 添加ition to the [JSON 输出 字段s](#json-输出) 可用 to 所有 钩子, you can 回报 `添加itional上下文` to 添加 上下文 to the 对话: | 字段 | 描述 | | :------------------ | :------------------------------- | | `添加itional上下文` | 字符串 加 to Claude's 上下文 | ### 子代理t艺术 运行s when a Claude 代码 sub代理 is spawned via the 代理 工具. 支持s 匹配ers to 过滤 by 代理 类型 名称 (built-in 代理s 像 `Bash`, `探索`, `计划`, or 习俗 代理 名称s from `.claude/代理s/`). #### 子代理t艺术 输入 In 添加ition to the [常见 输入 字段s](#常见-输入-字段s), 子代理t艺术 钩子 接收 `代理_id` with the 唯一 标识符 for the sub代理 and `代理_类型` with the 代理 名称 (built-in 代理s 像 `"Bash"`, `"探索"`, `"计划"`, or 习俗 代理 名称s). ```json 主题={空} { "会话_id": "abc123", "tran脚本_路径": "/用户s/.../.claude/项目s/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl", "cwd": "/用户s/...", "hook_事件_名称": "子代理t艺术", "代理_id": "代理-abc123", "代理_类型": "探索" } ``` 子代理t艺术 钩子 cannot 块 sub代理 创建, but they can inject 上下文 into the sub代理. In 添加ition to the [JSON 输出 字段s](#json-输出) 可用 to 所有 钩子, you can 回报: | 字段 | 描述 | | :------------------ | :------------------------------------- | | `添加itional上下文` | 字符串 加 to the sub代理's 上下文 | ```json 主题={空} { "hook特定输出": { "hook事件名称": "子代理t艺术", "添加itional上下文": "Fol低 安全 准则 for this 任务" } } ``` ### 子代理顶部 运行s when a Claude 代码 sub代理 has 完成 responding. 匹配es on 代理 类型, 相同 值s as 子代理t艺术. #### 子代理顶部 输入 In 添加ition to the [常见 输入 字段s](#常见-输入-字段s), 子代理顶部 钩子 接收 `停止_hook_活跃`, `代理_id`, `代理_类型`, `代理_tran脚本_路径`, and `最后一个_assistant_消息`. The `代理_类型` 字段 is the 值 使用d for 匹配er过滤. The `tran脚本_路径` is the 主 会话's tran脚本, while `代理_tran脚本_路径` is the sub代理's own tran脚本 存储 in a nested `子代理/` 文件夹. The `最后一个_assistant_消息` 字段 contains the 文本 满意 of the sub代理's 最终 响应, so 钩子 can access it without分析 the tran脚本 文件. ```json 主题={空} { "会话_id": "abc123", "tran脚本_路径": "~/.claude/项目s/.../abc123.jsonl", "cwd": "/用户s/...", "许可_模式": "默认", "hook_事件_名称": "子代理顶部", "停止_hook_活跃": 虚假, "代理_id": "def456", "代理_类型": "探索", "代理_tran脚本_路径": "~/.claude/项目s/.../abc123/子代理/代理-def456.jsonl", "最后一个_assistant_消息": "分析 完成. Found 3 潜力 问题s..." } ``` 子代理顶部 钩子 使用 the 相同 决定 控制 格式 as [停止 钩子](#停止-决定-控制). ### 任务创建d 运行s when a 任务 is being 创建d via the `任务创建` 工具. 使用 this to en强制 naming 惯例, requ怒 任务 描述s, or pr事件 确定 任务s from being 创建d. When a `任务创建d` hook 退出s with 代码 2, the 任务 is not 创建d and the stderr 消息 is fed 返回 to the 模型 as 反馈. To 停止 the 团队mate 整个ly instead of re-运行中 it, 回报 JSON with `{"继续": 虚假, "停止原因": "..."}`. 任务创建d 钩子 do not 支持 匹配ers and f怒 on 每个 occurrence. #### 任务创建d 输入 In 添加ition to the [常见 输入 字段s](#常见-输入-字段s), 任务创建d 钩子 接收 `任务_id`, `任务_主题`, and 可选ly `任务_描述`, `团队mate_名称`, and `团队_名称`. ```json 主题={空} { "会话_id": "abc123", "tran脚本_路径": "/用户s/.../.claude/项目s/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl", "cwd": "/用户s/...", "许可_模式": "默认", "hook_事件_名称": "任务创建d", "任务_id": "任务-001", "任务_主题": "实现 用户 认证", "任务_描述": "添加 日志in and 标志上 结束points", "团队mate_名称": "实现er", "团队_名称": "my-项目" } ``` | 字段 | 描述 | | :----------------- | :---------------------------------------------------- | | `任务_id` | 标识符 of the 任务 being 创建d | | `任务_主题` | 标题 of the 任务 | | `任务_描述` | 详情ed 描述 of the 任务. May be ab发送 | | `团队mate_名称` | 名称 of the 团队mate创建 the 任务. May be ab发送 | | `团队_名称` | 名称 of the 团队. May be ab发送 | #### 任务创建d 决定 控制 任务创建d 钩子 支持 two 方式s to 控制 任务 创建: * **退出 代码 2**: the 任务 is not 创建d and the stderr 消息 is fed 返回 to the 模型 as 反馈. * **JSON `{"继续": 虚假, "停止原因": "..."}`**: 停止s the 团队mate 整个ly, 匹配 `停止` hook behavior. The `停止原因` is 显示n to the 用户. This 示例 块s 任务s whose 主题s don't fol低 the 必需 格式: ```bash 主题={空} #!/bin/bash 输入=$(cat) 任务_主题=$(echo "$输入" | jq -r '.任务_主题') if [[ ! "$任务_主题" =~ ^\[TICKET-[0-9]+\] ]]; then echo "任务 主题 must 启动 with a ticket 数字, e.g. '[TICKET-123] 添加 feature'" >&2 退出 2 fi 退出 0 ``` ### 任务完成 运行s when a 任务 is being marked as 完成. This f怒s in two situations: when 任何 代理 明确ly marks a 任务 as 完成 th粗糙 the 任务更新 工具, or when an [代理 团队](/en/代理-团队) 团队mate finishes its turn with in-进步 任务s. 使用 this to en强制 completion 标准 像通过 测试s or lint 检查s 之前 a 任务 can 关闭. When a `任务完成` hook 退出s with 代码 2, the 任务 is not marked as 完成 and the stderr 消息 is fed 返回 to the 模型 as 反馈. To 停止 the 团队mate 整个ly instead of re-运行中 it, 回报 JSON with `{"继续": 虚假, "停止原因": "..."}`. 任务完成 钩子 do not 支持 匹配ers and f怒 on 每个 occurrence. #### 任务完成 输入 In 添加ition to the [常见 输入 字段s](#常见-输入-字段s), 任务完成 钩子 接收 `任务_id`, `任务_主题`, and 可选ly `任务_描述`, `团队mate_名称`, and `团队_名称`. ```json 主题={空} { "会话_id": "abc123", "tran脚本_路径": "/用户s/.../.claude/项目s/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl", "cwd": "/用户s/...", "许可_模式": "默认", "hook_事件_名称": "任务完成", "任务_id": "任务-001", "任务_主题": "实现 用户 认证", "任务_描述": "添加 日志in and 标志上 结束points", "团队mate_名称": "实现er", "团队_名称": "my-项目" } ``` | 字段 | 描述 | | :----------------- | :------------------------------------------------------ | | `任务_id` | 标识符 of the 任务 being 完成 | | `任务_主题` | 标题 of the 任务 | | `任务_描述` | 详情ed 描述 of the 任务. May be ab发送 | | `团队mate_名称` | 名称 of the 团队mate完成 the 任务. May be ab发送 | | `团队_名称` | 名称 of the 团队. May be ab发送 | #### 任务完成 决定 控制 任务完成 钩子 支持 two 方式s to 控制 任务 completion: * **退出 代码 2**: the 任务 is not marked as 完成 and the stderr 消息 is fed 返回 to the 模型 as 反馈. * **JSON `{"继续": 虚假, "停止原因": "..."}`**: 停止s the 团队mate 整个ly, 匹配 `停止` hook behavior. The `停止原因` is 显示n to the 用户. This 示例 运行s 测试s and 块s 任务 completion if they fail: ```bash 主题={空} #!/bin/bash 输入=$(cat) 任务_主题=$(echo "$输入" | jq -r '.任务_主题') # 运行 the 测试 suite if ! npm 测试 2>&1; then echo "测试s not通过. 修复 failing 测试s 之前完成: $任务_主题" >&2 退出 2 fi 退出 0 ``` ### 停止 运行s when the 主 Claude 代码 代理 has 完成 responding. Does not 运行 if the 停止页 occurred due to a 用户 中断. API 错误 f怒 [停止失败](#停止失败) instead. #### 停止 输入 In 添加ition to the [常见 输入 字段s](#常见-输入-字段s), 停止 钩子 接收 `停止_hook_活跃` and `最后一个_assistant_消息`. The `停止_hook_活跃` 字段 is `真实` when Claude 代码 is al就绪 继续 as a 结果 of a 停止 hook. 检查 this 值 or 流程 the tran脚本 to pr事件 Claude 代码 from 运行中 不确定ly. The `最后一个_assistant_消息` 字段 contains the 文本 满意 of Claude's 最终 响应, so 钩子 can access it without分析 the tran脚本 文件. ```json 主题={空} { "会话_id": "abc123", "tran脚本_路径": "~/.claude/项目s/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl", "cwd": "/用户s/...", "许可_模式": "默认", "hook_事件_名称": "停止", "停止_hook_活跃": 真实, "最后一个_assistant_消息": "I've 完成 the re事实oring. Here's a 摘要..." } ``` #### 停止 决定 控制 `停止` and `子代理顶部` 钩子 can 控制 whether Claude 继续s. In 添加ition to the [JSON 输出 字段s](#json-输出) 可用 to 所有 钩子, your hook 脚本 can 回报 these 事件-特定 字段s: | 字段 | 描述 | | :--------- | :------------------------------------------------------------------------- | | `决定` | `"块"` pr事件s Claude from停止. Omit to 允许 Claude to 停止 | | `原因` | 必需 when `决定` is `"块"`. Tells Claude why it should 继续 | ```json 主题={空} { "决定": "块", "原因": "Must be provided when Claude is 阻塞 from停止" } ``` ### 停止失败 运行s instead of [停止](#停止) when the turn 结束s due to an API 错误. 输出 and 退出 代码 are 忽略. 使用 this to 日志 失败s, 发送 警觉s, or take rec结束y 行动s when Claude cannot 完成 a 响应 due to 速率 限制s, 认证 问题s, or other API 错误. #### 停止失败 输入 In 添加ition to the [常见 输入 字段s](#常见-输入-字段s), 停止失败 钩子 接收 `错误`, 可选 `错误_详情s`, and 可选 `最后一个_assistant_消息`. The `错误` 字段 identifies the 错误 类型 and is 使用d for 匹配er过滤. | 字段 | 描述 | | :----------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `错误` | 错误 类型: `速率_限制`, `认证_失败`, `billing_错误`, `无效_请求`, `服务器_错误`, `max_输出_令牌s`, or `unknown` | | `错误_详情s` | 添加itional 详情s about the 错误, when 可用 | | `最后一个_assistant_消息` | The r结束ered 错误 文本 显示n in the 对话. 不像 `停止` and `子代理顶部`, where this 字段 h旧s Claude's 对话al 输出, for `停止失败` it contains the API 错误 字符串 itself, such as `"API 错误: 速率 限制 范围ed"` | ```json 主题={空} { "会话_id": "abc123", "tran脚本_路径": "/用户s/.../.claude/项目s/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl", "cwd": "/用户s/...", "hook_事件_名称": "停止失败", "错误": "速率_限制", "错误_详情s": "429 Too 许多 请求s", "最后一个_assistant_消息": "API 错误: 速率 限制 范围ed" } ``` 停止失败 钩子 have no 决定 控制. They 运行 for 通知 and日志 目的s only. ### 团队mate空闲 运行s when an [代理 团队](/en/代理-团队) 团队mate is about to 前往 空闲 之后完成 its turn. 使用 this to en强制 quality gates 之前 a 团队mate 停止s工作, such as要求通过 lint 检查s or验证 that 输出 文件 exist. When a `团队mate空闲` hook 退出s with 代码 2, the 团队mate 接收s the stderr 消息 as 反馈 and 继续s工作 instead of 前往ing 空闲. To 停止 the 团队mate 整个ly instead of re-运行中 it, 回报 JSON with `{"继续": 虚假, "停止原因": "..."}`. 团队mate空闲 钩子 do not 支持 匹配ers and f怒 on 每个 occurrence. #### 团队mate空闲 输入 In 添加ition to the [常见 输入 字段s](#常见-输入-字段s), 团队mate空闲 钩子 接收 `团队mate_名称` and `团队_名称`. ```json 主题={空} { "会话_id": "abc123", "tran脚本_路径": "/用户s/.../.claude/项目s/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl", "cwd": "/用户s/...", "许可_模式": "默认", "hook_事件_名称": "团队mate空闲", "团队mate_名称": "研究er", "团队_名称": "my-项目" } ``` | 字段 | 描述 | | :-------------- | :-------------------------------------------- | | `团队mate_名称` | 名称 of the 团队mate that is about to 前往 空闲 | | `团队_名称` | 名称 of the 团队 | #### 团队mate空闲 决定 控制 团队mate空闲 钩子 支持 two 方式s to 控制 团队mate behavior: * **退出 代码 2**: the 团队mate 接收s the stderr 消息 as 反馈 and 继续s工作 instead of 前往ing 空闲. * **JSON `{"继续": 虚假, "停止原因": "..."}`**: 停止s the 团队mate 整个ly, 匹配 `停止` hook behavior. The `停止原因` is 显示n to the 用户. This 示例 检查s that a 构建 艺术i事实 exists 之前允许 a 团队mate to 前往 空闲: ```bash 主题={空} #!/bin/bash if [ ! -f "./dist/输出.js" ]; then echo "构建 艺术i事实错过. 运行 the 构建 之前停止." >&2 退出 2 fi 退出 0 ``` ### Config更改 运行s when a 配置 文件 更改s 期间 a 会话. 使用 this to audit 设置 更改s, en强制 安全 政策, or 块 未授权 修改s to 配置 文件. Config更改 钩子 f怒 for 更改s to 设置 文件, 管理 政策 设置, and 技能 文件. The `来源` 字段 in the 输入 tells you which 类型 of 配置 更改d, and the 可选 `文件_路径` 字段 provides the 路径 to the 更改d 文件. The 匹配er 过滤s on the 配置 来源: | 匹配er | When it f怒s | | :----------------- | :---------------------------------------- | | `用户_设置` | `~/.claude/设置.json` 更改s | | `项目_设置` | `.claude/设置.json` 更改s | | `本地_设置` | `.claude/设置.本地.json` 更改s | | `政策_设置` | 管理 政策 设置 更改 | | `技能` | A 技能 文件 in `.claude/技能/` 更改s | This 示例 日志s 所有 配置 更改s for 安全 auditing: ```json 主题={空} { "钩子": { "Config更改": [ { "钩子": [ { "类型": "命令", "命令": "\"$CLAUDE_项目_DIR\"/.claude/钩子/audit-config-更改.sh" } ] } ] } } ``` #### Config更改 输入 In 添加ition to the [常见 输入 字段s](#常见-输入-字段s), Config更改 钩子 接收 `来源` and 可选ly `文件_路径`. The `来源` 字段 indicates which 配置 类型 更改d, and `文件_路径` provides the 路径 to the 特定 文件 that was modified. ```json 主题={空} { "会话_id": "abc123", "tran脚本_路径": "/用户s/.../.claude/项目s/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl", "cwd": "/用户s/...", "hook_事件_名称": "Config更改", "来源": "项目_设置", "文件_路径": "/用户s/.../my-项目/.claude/设置.json" } ``` #### Config更改 决定 控制 Config更改 钩子 can 块 配置 更改s from taking 效果. 使用 退出 代码 2 or a JSON `决定` to pr事件 the 更改. When 阻塞, the 新 设置 are not 应用 to the 运行中 会话. | 字段 | 描述 | | :--------- | :--------------------------------------------------------------------------------------- | | `决定` | `"块"` pr事件s the 配置 更改 from being 应用. Omit to 允许 the 更改 | | `原因` | 解释 显示n to the 用户 when `决定` is `"块"` | ```json 主题={空} { "决定": "块", "原因": "配置 更改s to 项目 设置 requ怒 管理员 批准" } ``` `政策_设置` 更改s cannot be 阻塞. 钩子 静止 f怒 for `政策_设置` 来源s, so you can 使用 them for audit日志, but 任何 阻塞 决定 is 忽略. This en确定s 企业-管理 设置 al方式s take 效果. ### Cwd更改d 运行s when the工作 目录 更改s 期间 a 会话, for 示例 when Claude 执行s a `cd` 命令. 使用 this to react to 目录 更改s: 重新加载 环境变量, 激活 项目-特定 工具chains, or 运行 设置 脚本s 自动所有y. 对s with [文件更改d](#文件更改d) for 工具 像 [d怒nv](https://d怒nv.net/) that manage per-目录 环境. Cwd更改d 钩子 have access to `CLAUDE_ENV_文件`. 可变s written to that 文件 persist into subsequent Bash 命令 for the 会话, 公正 as in [会话开始 钩子](#persist-环境-可变s). Only `类型: "命令"` 钩子 are 支持ed. Cwd更改d does not 支持 匹配ers and f怒s on 每个 目录 更改. #### Cwd更改d 输入 In 添加ition to the [常见 输入 字段s](#常见-输入-字段s), Cwd更改d 钩子 接收 `旧_cwd` and `新_cwd`. ```json 主题={空} { "会话_id": "abc123", "tran脚本_路径": "/用户s/.../.claude/项目s/.../tran脚本.jsonl", "cwd": "/用户s/my-项目/src", "hook_事件_名称": "Cwd更改d", "旧_cwd": "/用户s/my-项目", "新_cwd": "/用户s/my-项目/src" } ``` #### Cwd更改d 输出 In 添加ition to the [JSON 输出 字段s](#json-输出) 可用 to 所有 钩子, Cwd更改d 钩子 can 回报 `观看路径s` to 动态所有y 设置 which 文件 路径s [文件更改d](#文件更改d)观看es: | 字段 | 描述 | | :----------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `观看路径s` | 数组 of absolute 路径s. 替换s the 当前 动态观看 列表 (路径s from your `匹配er` 配置 are al方式s观看ed).返回 an 空 数组 清楚s the 动态 列表, which is 典型 when进入 a 新 目录 | Cwd更改d 钩子 have no 决定 控制. They cannot 块 the 目录 更改. ### 文件更改d 运行s when a观看ed 文件 更改s on disk. The `匹配er` 字段 in your hook 配置 控制s which 文件名称s to观看: it is a 管道-分离 列表 of 基础名称s (文件名称s without 目录 路径s, for 示例 `".envrc|.env"`). The 相同 `匹配er` 值 is also 使用d to 过滤 which 钩子 运行 when a 文件 更改s, 匹配 a收益st the 基础名称 of the 更改d 文件. 有用 for 重新加载ing 环境变量 when 项目 配置 文件 are modified. 文件更改d 钩子 have access to `CLAUDE_ENV_文件`. 可变s written to that 文件 persist into subsequent Bash 命令 for the 会话, 公正 as in [会话开始 钩子](#persist-环境-可变s). Only `类型: "命令"` 钩子 are 支持ed. #### 文件更改d 输入 In 添加ition to the [常见 输入 字段s](#常见-输入-字段s), 文件更改d 钩子 接收 `文件_路径` and `事件`. | 字段 | 描述 | | :---------- | :---------------------------------------------------------------------------------------------- | | `文件_路径` | Absolute 路径 to the 文件 that 更改d | | `事件` | What h应用ened: `"更改"` (文件 modified), `"添加"` (文件 创建d), or `"un链接"` (文件 删除) | ```json 主题={空} { "会话_id": "abc123", "tran脚本_路径": "/用户s/.../.claude/项目s/.../tran脚本.jsonl", "cwd": "/用户s/my-项目", "hook_事件_名称": "文件更改d", "文件_路径": "/用户s/my-项目/.envrc", "事件": "更改" } ``` #### 文件更改d 输出 In 添加ition to the [JSON 输出 字段s](#json-输出) 可用 to 所有 钩子, 文件更改d 钩子 can 回报 `观看路径s` to 动态所有y 更新 which 文件 路径s are观看ed: | 字段 | 描述 | | :----------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `观看路径s` | 数组 of absolute 路径s. 替换s the 当前 动态观看 列表 (路径s from your `匹配er` 配置 are al方式s观看ed). 使用 this when your hook 脚本 disc结束s 添加itional 文件 to观看 基础d on the 更改d 文件 | 文件更改d 钩子 have no 决定 控制. They cannot 块 the 文件 更改 from occurring. ### 工作树创建 When you 运行 `claude --工作树` or a [sub代理 使用s `isolation: "工作树"`](/en/sub-代理s#choose-the-sub代理-范围), Claude 代码 创建s an iso晚d工作 复制 using `Git 工作树`. If you con图 a 工作树创建 hook, it 替换s the 默认 Git behavior,让 you 使用 a 不同 版本 控制 系统 像 SVN, Per强制, or Mercurial. Be原因 the hook 替换s the 默认 behavior 整个ly, [`.工作树include`](/en/常见-工作流s#复制-Git忽略-文件-to-工作树) is not 已处理. If you 需要 to 复制 本地 配置 文件 像 `.env` into the 新 工作树, do it 内部 your hook 脚本. The hook must 回报 the absolute 路径 to the 创建d 工作树 目录. Claude 代码 使用s this 路径 as the工作 目录 for the iso晚d 会话. 命令 钩子 print it on stdout; HTTP 钩子 回报 it via `hook特定输出.工作树路径`. This 示例 创建s an SVN工作 复制 and prints the 路径 for Claude 代码 to 使用. 替换 the 仓库 URL with your own: ```json 主题={空} { "钩子": { "工作树创建": [ { "钩子": [ { "类型": "命令", "命令": "bash -c '名称=$(jq -r .名称); DIR=\"$HOME/.claude/工作树/$名称\"; svn 检查out https://svn.示例.com/repo/t运行k \"$DIR\" >&2 && echo \"$DIR\"'" } ] } ] } } ``` The hook 读取s the 工作树 `名称` from the JSON 输入 on stdin, 检查s out a 新鲜 复制 into a 新 目录, and prints the 目录 路径. The `echo` on the 最后一个 行 is what Claude 代码 读取s as the 工作树 路径. 重定向 任何 other 输出 to stderr so it doesn't interfere with the 路径. #### 工作树创建 输入 In 添加ition to the [常见 输入 字段s](#常见-输入-字段s), 工作树创建 钩子 接收 the `名称` 字段. This is a slug 标识符 for the 新 工作树, either 指定 by the 用户 or auto-gene速率d (for 示例, `b旧-oak-a3f2`). ```json 主题={空} { "会话_id": "abc123", "tran脚本_路径": "/用户s/.../.claude/项目s/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl", "cwd": "/用户s/...", "hook_事件_名称": "工作树创建", "名称": "feature-auth" } ``` #### 工作树创建 输出 工作树创建 钩子 do not 使用 the 标准 允许/块 决定 模型. Instead, the hook's 成功 or 失败 determines the 结果. The hook must 回报 the absolute 路径 to the 创建d 工作树 目录: * **命令 钩子** (`类型: "命令"`): print the 路径 on stdout. * **HTTP 钩子** (`类型: "http"`): 回报 `{ "hook特定输出": { "hook事件名称": "工作树创建", "工作树路径": "/absolute/路径" } }` in the 响应 正文. If the hook fails or produces no 路径, 工作树 创建 fails with an 错误. ### 工作树移除 The 干净上 counter部分 to [工作树创建](#工作树创建). This hook f怒s when a 工作树 is being 移除, either when you 退出 a `--工作树` 会话 and choose to 移除 it, or when a sub代理 with `isolation: "工作树"` finishes. For Git-基础d 工作树, Claude handles 干净上 自动所有y with `Git 工作树 移除`. If you con图d a 工作树创建 hook for a non-Git 版本 控制 系统, 对 it with a 工作树移除 hook to handle 干净上. Without one, the 工作树 目录 is 左 on disk. Claude 代码 passes the 路径 返回 by 工作树创建 as `工作树_路径` in the hook 输入. This 示例 读取s that 路径 and 移除s the 目录: ```json 主题={空} { "钩子": { "工作树移除": [ { "钩子": [ { "类型": "命令", "命令": "bash -c 'jq -r .工作树_路径 | xargs rm -rf'" } ] } ] } } ``` #### 工作树移除 输入 In 添加ition to the [常见 输入 字段s](#常见-输入-字段s), 工作树移除 钩子 接收 the `工作树_路径` 字段, which is the absolute 路径 to the 工作树 being 移除. ```json 主题={空} { "会话_id": "abc123", "tran脚本_路径": "/用户s/.../.claude/项目s/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl", "cwd": "/用户s/...", "hook_事件_名称": "工作树移除", "工作树_路径": "/用户s/.../my-项目/.claude/工作树/feature-auth" } ``` 工作树移除 钩子 have no 决定 控制. They cannot 块 工作树 rem椭圆形 but can per形式 干净上 任务s 像 removing 版本 控制 州 or archiving 更改s. Hook 失败s are 日志ged in 调试 模式 only. ### Pre紧凑 运行s 之前 Claude 代码 is about to 运行 a 紧凑 运营. The 匹配er 值 indicates whether 紧凑ion was triggered 手册ly or 自动所有y: | 匹配er | When it f怒s | | :------- | :------------------------------------------- | | `手册` | `/紧凑` | | `auto` | Auto-紧凑 when the 上下文 风ow is 满 | #### Pre紧凑 输入 In 添加ition to the [常见 输入 字段s](#常见-输入-字段s), Pre紧凑 钩子 接收 `trigger` and `习俗_说明`. For `手册`, `习俗_说明` contains what the 用户 passes into `/紧凑`. For `auto`, `习俗_说明` is 空. ```json 主题={空} { "会话_id": "abc123", "tran脚本_路径": "/用户s/.../.claude/项目s/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl", "cwd": "/用户s/...", "hook_事件_名称": "Pre紧凑", "trigger": "手册", "习俗_说明": "" } ``` ### Post紧凑 运行s 之后 Claude 代码 完成s a 紧凑 运营. 使用 this 事件 to react to the 新 紧凑ed 州, for 示例 to 日志 the gene速率d 摘要 or 更新 外部 州. The 相同 匹配er 值s 应用ly as for `Pre紧凑`: | 匹配er | When it f怒s | | :------- | :------------------------------------------------- | | `手册` | 之后 `/紧凑` | | `auto` | 之后 auto-紧凑 when the 上下文 风ow is 满 | #### Post紧凑 输入 In 添加ition to the [常见 输入 字段s](#常见-输入-字段s), Post紧凑 钩子 接收 `trigger` and `紧凑_摘要`. The `紧凑_摘要` 字段 contains the 对话 摘要 gene速率d by the 紧凑 运营. ```json 主题={空} { "会话_id": "abc123", "tran脚本_路径": "/用户s/.../.claude/项目s/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl", "cwd": "/用户s/...", "hook_事件_名称": "Post紧凑", "trigger": "手册", "紧凑_摘要": "摘要 of the 紧凑ed 对话..." } ``` Post紧凑 钩子 have no 决定 控制. They cannot affect the 紧凑ion 结果 but can per形式 fol低-上 任务s. ### 会话结束 运行s when a Claude 代码 会话 结束s. 有用 for 干净上 任务s,日志 会话 statistics, or保存 会话 州. 支持s 匹配ers to 过滤 by 退出 原因. The `原因` 字段 in the hook 输入 indicates why the 会话 结束: | 原因 | 描述 | | :---------------------------- | :----------------------------------------- | | `清楚` | 会话 清楚ed with `/清楚` 命令 | | `恢复` | 会话 switched via 交互 `/恢复` | | `标志ut` | 用户 日志ged out | | `及时_输入_退出` | 用户 退出ed while 及时 输入 was 可见 | | `bypass_权限_禁用` | Bypass 权限 模式 was 禁用 | | `other` | Other 退出 原因s | #### 会话结束 输入 In 添加ition to the [常见 输入 字段s](#常见-输入-字段s), 会话结束 钩子 接收 a `原因` 字段 indicating why the 会话 结束.看见 the [原因 表](#会话结束) above for 所有 值s. ```json 主题={空} { "会话_id": "abc123", "tran脚本_路径": "/用户s/.../.claude/项目s/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl", "cwd": "/用户s/...", "hook_事件_名称": "会话结束", "原因": "other" } ``` 会话结束 钩子 have no 决定 控制. They cannot 块 会话 termination but can per形式 干净上 任务s. 会话结束 钩子 have a 默认 超时 of 1.5 seconds. This 应用lies to 会话 退出, `/清楚`, and switching 会话s via 交互 `/恢复`. If your 钩子 需要 更多 时间, 设置 the `CLAUDE_代码_会话结束_钩子_超时_MS` 环境 可变 to a 高er 值 in milliseconds. 任何 per-hook `超时`设置 is also c应用ed by this 值. ```bash 主题={空} CLAUDE_代码_会话结束_钩子_超时_MS=5000 claude ``` ### E合法ation 运行s when an MCP 服务器 请求s 用户 输入 mid-任务. By 默认, Claude 代码 显示s an 交互 dia日志 for the 用户 to respond. 钩子 can intercept this 请求 and respond 计划matic所有y,跳ping the dia日志 整个ly. The 匹配er 字段 匹配es a收益st the MCP 服务器 名称. #### E合法ation 输入 In 添加ition to the [常见 输入 字段s](#常见-输入-字段s), E合法ation 钩子 接收 `mcp_服务器_名称`, `消息`, and 可选 `模式`, `url`, `e合法ation_id`, and `请求ed_模式` 字段s. For 形式-模式 e合法ation (the 最多 常见 案例): ```json 主题={空} { "会话_id": "abc123", "tran脚本_路径": "/用户s/.../.claude/项目s/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl", "cwd": "/用户s/...", "许可_模式": "默认", "hook_事件_名称": "E合法ation", "mcp_服务器_名称": "my-mcp-服务器", "消息": "Pl容易 provide your credentials", "模式": "形式", "请求ed_模式": { "类型": "对象", "适当ties": { "用户名称": { "类型": "字符串", "标题": "用户名称" } } } } ``` For URL-模式 e合法ation (浏览器-基础d 认证): ```json 主题={空} { "会话_id": "abc123", "tran脚本_路径": "/用户s/.../.claude/项目s/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl", "cwd": "/用户s/...", "许可_模式": "默认", "hook_事件_名称": "E合法ation", "mcp_服务器_名称": "my-mcp-服务器", "消息": "Pl容易 authenticate", "模式": "url", "url": "https://auth.示例.com/日志in" } ``` #### E合法ation 输出 To respond 计划matic所有y without显示 the dia日志, 回报 a JSON 对象 with `hook特定输出`: ```json 主题={空} { "hook特定输出": { "hook事件名称": "E合法ation", "行动": "接受", "满意": { "用户名称": "alice" } } } ``` | 字段 | 值s | 描述 | | :-------- | :---------------------------- | :--------------------------------------------------------------- | | `行动` | `接受`, `下降`, `取消` | Whether to 接受, 下降, or 取消 the 请求 | | `满意` | 对象 | 形式 字段 值s to submit. Only 使用d when `行动` is `接受` | 退出 代码 2 denies the e合法ation and 显示s stderr to the 用户. ### E合法ation结果 运行s 之后 a 用户 responds to an MCP e合法ation. 钩子 can观察, 修改, or 块 the 响应 之前 it is 发送 返回 to the MCP 服务器. The 匹配er 字段 匹配es a收益st the MCP 服务器 名称. #### E合法ation结果 输入 In 添加ition to the [常见 输入 字段s](#常见-输入-字段s), E合法ation结果 钩子 接收 `mcp_服务器_名称`, `行动`, and 可选 `模式`, `e合法ation_id`, and `满意` 字段s. ```json 主题={空} { "会话_id": "abc123", "tran脚本_路径": "/用户s/.../.claude/项目s/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl", "cwd": "/用户s/...", "许可_模式": "默认", "hook_事件_名称": "E合法ation结果", "mcp_服务器_名称": "my-mcp-服务器", "行动": "接受", "满意": { "用户名称": "alice" }, "模式": "形式", "e合法ation_id": "e合法-123" } ``` #### E合法ation结果 输出 To 结束ride the 用户's 响应, 回报 a JSON 对象 with `hook特定输出`: ```json 主题={空} { "hook特定输出": { "hook事件名称": "E合法ation结果", "行动": "下降", "满意": {} } } ``` | 字段 | 值s | 描述 | | :-------- | :---------------------------- | :--------------------------------------------------------------------- | | `行动` | `接受`, `下降`, `取消` | 结束rides the 用户's 行动 | | `满意` | 对象 | 结束rides 形式 字段 值s. Only 有意义 when `行动` is `接受` | 退出 代码 2 块s the 响应,改变 the 有效 行动 to `下降`. ## 及时-基础d 钩子 In 添加ition to 命令 and HTTP 钩子, Claude 代码 支持s 及时-基础d 钩子 (`类型: "及时"`) that 使用 an LLM to evaluate whether to 允许 or 块 an 行动, and 代理 钩子 (`类型: "代理"`) that spawn an 代理ic verifier with 工具 access. Not 所有 事件s 支持 每个 hook 类型. 事件s that 支持 所有 four hook 类型s (`命令`, `http`, `及时`, and `代理`): * `许可请求` * `工具使用后` * `工具使用后失败` * `工具使用前` * `停止` * `子代理顶部` * `任务完成` * `任务创建d` * `用户及时Submit` 事件s that 支持 `命令` and `http` 钩子 but not `及时` or `代理`: * `Config更改` * `Cwd更改d` * `E合法ation` * `E合法ation结果` * `文件更改d` * `说明加载` * `通知` * `许可拒绝` * `Post紧凑` * `Pre紧凑` * `会话结束` * `停止失败` * `子代理t艺术` * `团队mate空闲` * `工作树创建` * `工作树移除` `会话开始` 支持s only `命令` 钩子. ### How 及时-基础d 钩子 工作 Instead of执行 a Bash 命令, 及时-基础d 钩子: 1. 发送 the hook 输入 and your 及时 to a Claude 模型, Haiku by 默认 2. The LLM responds with 结构化 JSON包含 a 决定 3. Claude 代码 流程es the 决定 自动所有y ### 及时 hook 配置 设置 `类型` to `"及时"` and provide a `及时` 字符串 instead of a `命令`. 使用 the `$参数` placeh更旧 to inject the hook's JSON 输入 数据 into your 及时 文本. Claude 代码 发送s the 组合 及时 and 输入 to a 快 Claude 模型, which 回报s a JSON 决定. This `停止` hook asks the LLM to evaluate whether 所有 任务s are 完成 之前允许 Claude to finish: ```json 主题={空} { "钩子": { "停止": [ { "钩子": [ { "类型": "及时", "及时": "Evaluate if Claude should 停止: $参数. 检查 if 所有 任务s are 完成." } ] } ] } } ``` | 字段 | 必需 | 描述 | | :-------- | :------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `类型` | yes | Must be `"及时"` | | `及时` | yes | The 及时 文本 to 发送 to the LLM. 使用 `$参数` as a placeh更旧 for the hook 输入 JSON. If `$参数` is not 现在, 输入 JSON is 应用结束 to the 及时 | | `模型` | no | 模型 to 使用 for 评价. 默认s to a 快 模型 | | `超时` | no | 超时 in seconds. 默认: 30 | ### 响应 模式 The LLM must respond with JSON包含: ```json 主题={空} { "ok": 真实 | 虚假, "原因": "解释 for the 决定" } ``` | 字段 | 描述 | | :------- | :--------------------------------------------------------- | | `ok` | `真实` 允许s the 行动, `虚假` pr事件s it | | `原因` | 必需 when `ok` is `虚假`. 解释 显示n to Claude | ### 示例: Multi-标准 停止 hook This `停止` hook 使用s a 详情ed 及时 to 检查 three 条件 之前允许 Claude to 停止. If `"ok"` is `虚假`, Claude 继续s工作 with the provided 原因 as its 下一个 instruction. `子代理顶部` 钩子 使用 the 相同 格式 to evaluate whether a [sub代理](/en/sub-代理s) should 停止: ```json 主题={空} { "钩子": { "停止": [ { "钩子": [ { "类型": "及时", "及时": "You are评估 whether Claude should 停止工作. 上下文: $参数\n\n分析 the 对话 and determine if:\n1. 所有 用户-请求ed 任务s are 完成\n2. 任何 错误 需要 to be 添加ressed\n3. Fol低-上 工作 is 需要ed\n\nRespond with JSON: {\"ok\": 真实} to 允许停止, or {\"ok\": 虚假, \"原因\": \"your 解释\"} to 继续工作.", "超时": 30 } ] } ] } } ``` ## 代理-基础d 钩子 代理-基础d 钩子 (`类型: "代理"`) are 像 及时-基础d 钩子 but with multi-turn 工具 access. Instead of a single LLM c所有, an 代理 hook spawns a sub代理 that can 读取 文件, 搜索 代码, and检查 the 代码基础 to 验证 条件. 代理 钩子 支持 the 相同 事件s as 及时-基础d 钩子. ### How 代理 钩子 工作 When an 代理 hook f怒s: 1. Claude 代码 spawns a sub代理 with your 及时 and the hook's JSON 输入 2. The sub代理 can 使用 工具 像 读取, Grep, and Glob to调查 3. 之后 上 to 50 turns, the sub代理 回报s a 结构化 `{ "ok": 真实/虚假 }` 决定 4. Claude 代码 流程es the 决定 the 相同 方式 as a 及时 hook 代理 钩子 are 有用 when 验证 requ怒s审查 实际 文件 or 测试 输出, not 公正评估 the hook 输入 数据 alone. ### 代理 hook 配置 设置 `类型` to `"代理"` and provide a `及时` 字符串. The 配置 字段s are the 相同 as [及时 钩子](#及时-hook-配置), with a 长er 默认 超时: | 字段 | 必需 | 描述 | | :-------- | :------- | :------------------------------------------------------------------------------------------ | | `类型` | yes | Must be `"代理"` | | `及时` | yes | 及时描述 what to 验证. 使用 `$参数` as a placeh更旧 for the hook 输入 JSON | | `模型` | no | 模型 to 使用. 默认s to a 快 模型 | | `超时` | no | 超时 in seconds. 默认: 60 | The 响应 模式 is the 相同 as 及时 钩子: `{ "ok": 真实 }` to 允许 or `{ "ok": 虚假, "原因": "..." }` to 块. This `停止` hook verifies that 所有 单位 测试s pass 之前允许 Claude to finish: ```json 主题={空} { "钩子": { "停止": [ { "钩子": [ { "类型": "代理", "及时": "验证 that 所有 单位 测试s pass. 运行 the 测试 suite and 检查 the 结果s. $参数", "超时": 120 } ] } ] } } ``` ## 运行 钩子 in the 背景 By 默认, 钩子 块 Claude's 执行 until they 完成. For 长-运行中 任务s 像 部署ments, 测试 suites, or 外部 API c所有s, 设置 `"异步": 真实` to 运行 the hook in the 背景 while Claude 继续s工作. 异步 钩子 cannot 块 or 控制 Claude's behavior: 响应 字段s 像 `决定`, `许可决定`, and `继续` have no 效果, be原因 the 行动 they would have 受控 has al就绪 完成. ### Con图 an 异步 hook 添加 `"异步": 真实` to a 命令 hook's 配置 to 运行 it in the 背景 without 阻塞 Claude. This 字段 is only 可用 on `类型: "命令"` 钩子. This hook 运行s a 测试 脚本 之后 每个 `写入` 工具 c所有. Claude 继续s工作 立即ly while `运行-测试s.sh` 执行s for 上 to 120 seconds. When the 脚本 finishes, its 输出 is 交付 on the 下一个 对话 turn: ```json 主题={空} { "钩子": { "工具使用后": [ { "匹配er": "写入", "钩子": [ { "类型": "命令", "命令": "/路径/to/运行-测试s.sh", "异步": 真实, "超时": 120 } ] } ] } } ``` The `超时` 字段 设置s the 最大 时间 in seconds for the 背景 流程. If not 指定, 异步 钩子 使用 the 相同 10-微小 默认 as 同步 钩子. ### How 异步 钩子 执行 When an 异步 hook f怒s, Claude 代码 启动s the hook 流程 and 立即ly 继续s without 等待ing for it to finish. The hook 接收s the 相同 JSON 输入 via stdin as a 同步 hook. 之后 the 背景 流程 退出s, if the hook produced a JSON 响应 with a `系统消息` or `添加itional上下文` 字段, that 满意 is 交付 to Claude as 上下文 on the 下一个 对话 turn. 异步 hook completion 通知s are s上pressed by 默认. To看见 them, 启用 详细 模式 with `Ctrl+O` or 启动 Claude 代码 with `--详细`. ### 示例: 运行 测试s 之后 文件 更改s This hook 启动s a 测试 suite in the 背景 whenever Claude 写入s a 文件, then 报告s the 结果s 返回 to Claude when the 测试s finish. 保存 this 脚本 to `.claude/钩子/运行-测试s-异步.sh` in your 项目 and make it 可执行文件 with `chmod +x`: ```bash 主题={空} #!/bin/bash # 运行-测试s-异步.sh # 读取 hook 输入 from stdin 输入=$(cat) 文件_路径=$(echo "$输入" | jq -r '.工具_输入.文件_路径 // 空') # Only 运行 测试s for 来源 文件 if [[ "$文件_路径" != *.ts && "$文件_路径" != *.js ]]; then 退出 0 fi # 运行 测试s and 报告 结果s via 系统消息 结果=$(npm 测试 2>&1) 退出_代码=$? if [ $退出_代码 -eq 0 ]; then echo "{\"系统消息\": \"测试s passed 之后 编辑ing $文件_路径\"}" else echo "{\"系统消息\": \"测试s 失败 之后 编辑ing $文件_路径: $结果\"}" fi ``` Then 添加 this 配置 to `.claude/设置.json` in your 项目 根. The `异步: 真实` flag lets Claude keep工作 while 测试s 运行: ```json 主题={空} { "钩子": { "工具使用后": [ { "匹配er": "写入|编辑", "钩子": [ { "类型": "命令", "命令": "\"$CLAUDE_项目_DIR\"/.claude/钩子/运行-测试s-异步.sh", "异步": 真实, "超时": 300 } ] } ] } } ``` ### 限制 异步 钩子 have 几个 常量雨ts 比较d to 同步 钩子: * Only `类型: "命令"` 钩子 支持 `异步`. 及时-基础d 钩子 cannot 运行 异步ly. * 异步 钩子 cannot 块 工具 c所有s or 回报 决定s. By the 时间 the hook 完成s, the triggering 行动 has al就绪 proceeded. * Hook 输出 is 交付 on the 下一个 对话 turn. If the 会话 is 空闲, the 响应 等待s until the 下一个 用户 交互. * 每个 执行 创建s a 单独 背景 流程. There is no ded上lication across mul提示le firings of the 相同 异步 hook. ## 安全 conside比率ns ### Discl瞄准er 命令 钩子 运行 with your 系统 用户's 满 权限. 命令 钩子 执行 命令行 命令 with your 满 用户 权限. They can 修改, 删除, or access 任何 文件 your 用户 说明 can access. Re视图 and 测试 所有 hook 命令 之前添加 them to your 配置. ### 安全 最佳实践 Keep these 实践 in mind when写作 钩子: * **验证 and sanitize 输入s**: never 信任 输入 数据 blindly * **Al方式s quote 命令行 可变s**: 使用 `"$VAR"` not `$VAR` * **块 路径 traversal**: 检查 for `..` in 文件 路径s * **使用 absolute 路径s**: 规格ify 满 路径s for 脚本s, using `"$CLAUDE_项目_DIR"` for the 项目 根 * **跳 敏感 文件**: a空白 `.env`, `.Git/`, 键s, etc. ## 风ows 权力命令行 工具 On 风ows, you can 运行 个人 钩子 in 权力命令行 by设置 `"命令行": "权力命令行"` on a 命令 hook. 钩子 spawn 权力命令行 直接ly, so this 工作s 注意较少 of whether `CLAUDE_代码_使用_权力命令行_工具` is 设置. Claude 代码 auto-detects `pwsh.exe` (权力命令行 7+) with a 下降返回 to `权力命令行.exe` (5.1). ```json 主题={空} { "钩子": { "工具使用后": [ { "匹配er": "写入", "钩子": [ { "类型": "命令", "命令行": "权力命令行", "命令": "写入-Host '文件 written'" } ] } ] } } ``` ## 调试 钩子 运行 `claude --调试` to看见 hook 执行 详情s,包括 which 钩子 匹配ed, their 退出 代码s, and 输出. ```文本 主题={空} [调试]执行 钩子 for 工具使用后:写入 [调试] Found 1 hook 命令 to 执行 [调试]执行 hook 命令: with 超时 600000ms [调试] Hook 命令 完成 with 状态 0: ``` For 更多 颗粒 hook 匹配 详情s, 设置 `CLAUDE_代码_调试_日志_级别=详细` to看见 添加itional 日志 行s such as hook 匹配er counts and 查询 匹配. For 故障排除 常见问题 像 钩子 not firing, infinite 停止 hook loops, or 配置 错误,看见 [限制 and 故障排除](/en/钩子-指南#限制-and-故障排除) in the 指南.