35下表总结了每个事件何时触发。[Hook 事件](#hook-events)部分记录了每个事件的完整输入架构和决定控制选项。35下表总结了每个事件何时触发。[Hook 事件](#hook-events)部分记录了每个事件的完整输入架构和决定控制选项。
36 36
37| 事件 | 触发时机 |37| 事件 | 触发时机 |
38| :-------------------- | :--------------------------------------------------------------------------------------------------------------------- |38| :- | :- |
39| `SessionStart` | 当会话开始或恢复时 |39| `SessionStart` | 当会话开始或恢复时 |
40| `Setup` | 当你使用 `--init-only` 启动 Claude Code，或在 `-p` 模式下使用 `--init` 或 `--maintenance` 时。用于 CI 或脚本中的一次性准备 |40| `Setup` | 当你使用 `--init-only` 启动 Claude Code，或在 `-p` 模式下使用 `--init` 或 `--maintenance` 时。用于 CI 或脚本中的一次性准备 |
41| `UserPromptSubmit` | 当你提交提示词时，在 Claude 处理之前 |41| `UserPromptSubmit` | 当你提交提示词时，在 Claude 处理之前 |
259定义 hook 的位置决定了其范围：259定义 hook 的位置决定了其范围：
260 260
261| 位置 | 范围 | 可共享 |261| 位置 | 范围 | 可共享 |
262| :--------------------------------------------------- | :------------------------------------------------------------------------- | :-------------------------------- |262| :- | :- | :- |
263| `~/.claude/settings.json` | 所有项目 | 否，仅限本地计算机 |263| `~/.claude/settings.json` | 所有项目 | 否，仅限本地计算机 |
264| `.claude/settings.json` | 单个项目 | 是，可以提交到仓库 |264| `.claude/settings.json` | 单个项目 | 是，可以提交到仓库 |
265| `.claude/settings.local.json` | 单个项目 | 否，当 Claude Code 保存设置时被 gitignored |265| `.claude/settings.local.json` | 单个项目 | 否，当 Claude Code 保存设置时被 gitignored |
297`matcher` 字段过滤何时触发 hooks。匹配器的评估方式取决于它包含的字符：297`matcher` 字段过滤何时触发 hooks。匹配器的评估方式取决于它包含的字符：
298 298
299| 匹配器值 | 评估为 | 示例 |299| 匹配器值 | 评估为 | 示例 |
300| :--------------------------- | :----------------------------------- | :-------------------------------------------------------------------------------- |300| :- | :- | :- |
301| `"*"`、`""` 或省略 | 匹配所有 | 在事件的每次出现时触发 |301| `"*"`、`""` 或省略 | 匹配所有 | 在事件的每次出现时触发 |
302| 仅字母、数字、`_`、`-`、空格、`,` 和 `\|` | 精确字符串或由 `\|` 或 `,` 分隔的精确字符串列表，可选周围空格 | `Bash` 仅匹配 Bash 工具；`Edit\|Write` 和 `Edit, Write` 各匹配任一工具；`code-reviewer` 仅匹配该代理类型 |302| 仅字母、数字、`_`、`-`、空格、`,` 和 `\|` | 精确字符串或由 `\|` 或 `,` 分隔的精确字符串列表，可选周围空格 | `Bash` 仅匹配 Bash 工具；`Edit\|Write` 和 `Edit, Write` 各匹配任一工具；`code-reviewer` 仅匹配该代理类型 |
303| 包含任何其他字符 | JavaScript 正则表达式，未锚定 | `^Notebook` 匹配任何名称以 `Notebook` 开头的工具；`mcp__memory__.*` 匹配来自 `memory` 服务器的每个工具 |303| 包含任何其他字符 | JavaScript 正则表达式，未锚定 | `^Notebook` 匹配任何名称以 `Notebook` 开头的工具；`mcp__memory__.*` 匹配来自 `memory` 服务器的每个工具 |
313每个事件类型在不同的字段上匹配：313每个事件类型在不同的字段上匹配：
314 314
315| 事件 | 匹配器过滤的内容 | 示例匹配器值 |315| 事件 | 匹配器过滤的内容 | 示例匹配器值 |
316| :---------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |316| :- | :- | :- |
317| `PreToolUse`、`PostToolUse`、`PostToolUseFailure`、`PermissionRequest`、`PermissionDenied` | 工具名称 | `Bash`、`Edit\|Write`、`mcp__.*` |317| `PreToolUse`、`PostToolUse`、`PostToolUseFailure`、`PermissionRequest`、`PermissionDenied` | 工具名称 | `Bash`、`Edit\|Write`、`mcp__.*` |
318| `SessionStart` | 会话如何启动 | `startup`、`resume`、`clear`、`compact`、`fork` |318| `SessionStart` | 会话如何启动 | `startup`、`resume`、`clear`、`compact`、`fork` |
319| `Setup` | 哪个 CLI 标志触发了设置 | `init`、`maintenance` |319| `Setup` | 哪个 CLI 标志触发了设置 | `init`、`maintenance` |
438这些字段适用于所有 hook 类型：438这些字段适用于所有 hook 类型：
439 439
440| 字段 | 必需 | 描述 |440| 字段 | 必需 | 描述 |
441| :-------------- | :- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |441| :- | :- | :- |
442| `type` | 是 | `"command"`、`"http"`、`"mcp_tool"`、`"prompt"` 或 `"agent"` |442| `type` | 是 | `"command"`、`"http"`、`"mcp_tool"`、`"prompt"` 或 `"agent"` |
443| `if` | 否 | 权限规则语法来过滤此 hook 何时运行，如 `"Bash(git *)"` 或 `"Edit(*.ts)"`。hook 命令仅在工具调用与模式匹配时运行。有关 Bash 模式如何针对子命令、`$()` 和反引号评估的信息，请参阅下面的 [Bash 匹配表](#bash-if-matching)。仅在工具事件上评估：`PreToolUse`、`PostToolUse`、`PostToolUseFailure`、`PermissionRequest` 和 `PermissionDenied`。在其他事件上，设置了 `if` 的 hook 永远不会运行。使用与 [权限规则](/docs/zh-CN/permissions) 相同的语法 |443| `if` | 否 | 权限规则语法来过滤此 hook 何时运行，如 `"Bash(git *)"` 或 `"Edit(*.ts)"`。hook 命令仅在工具调用与模式匹配时运行。有关 Bash 模式如何针对子命令、`$()` 和反引号评估的信息，请参阅下面的 [Bash 匹配表](#bash-if-matching)。仅在工具事件上评估：`PreToolUse`、`PostToolUse`、`PostToolUseFailure`、`PermissionRequest` 和 `PermissionDenied`。在其他事件上，设置了 `if` 的 hook 永远不会运行。使用与 [权限规则](/docs/zh-CN/permissions) 相同的语法 |
444| `timeout` | 否 | 取消前的秒数。Claude Code 不在使用 [`async: true`](#run-hooks-in-the-background) 运行的命令 hook 上强制执行。默认值：`command`、`http` 和 `mcp_tool` 为 600；`prompt` 为 30；`agent` 为 60。Claude Code 在 [`UserPromptSubmit`](#userpromptsubmit)、[`PreModelSwitch`](#premodelswitch) 和 [`PostModelSwitch`](#postmodelswitch) 上将 `command`、`http` 和 `mcp_tool` 默认值降低到 30，在 [`MessageDisplay`](#messagedisplay) 上降低到 10。[`SessionEnd`](#sessionend) hooks 共享 1.5 秒的预算；如果设置设置了更长的每个 hook `timeout`，Claude Code 将预算提高到匹配，最多 60 秒 |444| `timeout` | 否 | 取消前的秒数。Claude Code 不在使用 [`async: true`](#run-hooks-in-the-background) 运行的命令 hook 上强制执行。默认值：`command`、`http` 和 `mcp_tool` 为 600；`prompt` 为 30；`agent` 为 60。Claude Code 在 [`UserPromptSubmit`](#userpromptsubmit)、[`PreModelSwitch`](#premodelswitch) 和 [`PostModelSwitch`](#postmodelswitch) 上将 `command`、`http` 和 `mcp_tool` 默认值降低到 30，在 [`MessageDisplay`](#messagedisplay) 上降低到 10。[`SessionEnd`](#sessionend) hooks 共享 1.5 秒的预算；如果设置设置了更长的每个 hook `timeout`，Claude Code 将预算提高到匹配，最多 60 秒 |
452<span id="bash-if-matching" />对于 Bash 模式，hook 命令是否运行取决于模式的形状和 Claude 调用的 Bash 命令。在匹配前剥离前导 `VAR=value` 赋值。452<span id="bash-if-matching" />对于 Bash 模式，hook 命令是否运行取决于模式的形状和 Claude 调用的 Bash 命令。在匹配前剥离前导 `VAR=value` 赋值。
453 453
454| `if` 模式 | Bash 命令 | Hook 运行？ | 为什么 |454| `if` 模式 | Bash 命令 | Hook 运行？ | 为什么 |
455| :----------------- | :-------------------------- | :------- | :------------------------------------------- |455| :- | :- | :- | :- |
456| `Bash(git *)` | `FOO=bar git push` | 是 | 前导赋值被剥离；`git push` 匹配 |456| `Bash(git *)` | `FOO=bar git push` | 是 | 前导赋值被剥离；`git push` 匹配 |
457| `Bash(git *)` | `npm test && git push` | 是 | 每个子命令被检查；`git push` 匹配 |457| `Bash(git *)` | `npm test && git push` | 是 | 每个子命令被检查；`git push` 匹配 |
458| `Bash(rm *)` | `echo $(rm -rf /)` | 是 | `$()` 和反引号内的命令被检查；`rm -rf /` 匹配 |458| `Bash(rm *)` | `echo $(rm -rf /)` | 是 | `$()` 和反引号内的命令被检查；`rm -rf /` 匹配 |
470除了 [通用字段](#common-fields)，命令 hooks 接受这些字段：470除了 [通用字段](#common-fields)，命令 hooks 接受这些字段：
471 471
472| 字段 | 必需 | 描述 |472| 字段 | 必需 | 描述 |
473| :------------ | :- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |473| :- | :- | :- |
474| `command` | 是 | 要执行的 shell 命令。使用 `args` 时，直接生成的可执行文件。请参阅 [Exec 形式和 shell 形式](#exec-form-and-shell-form) |474| `command` | 是 | 要执行的 shell 命令。使用 `args` 时，直接生成的可执行文件。请参阅 [Exec 形式和 shell 形式](#exec-form-and-shell-form) |
475| `args` | 否 | 参数列表。存在时，`command` 被解析为可执行文件并直接使用 `args` 作为参数向量生成，不涉及 shell。请参阅 [Exec 形式和 shell 形式](#exec-form-and-shell-form) |475| `args` | 否 | 参数列表。存在时，`command` 被解析为可执行文件并直接使用 `args` 作为参数向量生成，不涉及 shell。请参阅 [Exec 形式和 shell 形式](#exec-form-and-shell-form) |
476| `async` | 否 | 如果为 `true`，在后台运行而不阻止。请参阅 [在后台运行 hooks](#run-hooks-in-the-background) |476| `async` | 否 | 如果为 `true`，在后台运行而不阻止。请参阅 [在后台运行 hooks](#run-hooks-in-the-background) |
529除了 [通用字段](#common-fields)，HTTP hooks 接受这些字段：529除了 [通用字段](#common-fields)，HTTP hooks 接受这些字段：
530 530
531| 字段 | 必需 | 描述 |531| 字段 | 必需 | 描述 |
532| :--------------- | :- | :-------------------------------------------------------------------------------------- |532| :- | :- | :- |
533| `url` | 是 | 发送 POST 请求的 URL |533| `url` | 是 | 发送 POST 请求的 URL |
534| `headers` | 否 | 其他 HTTP 标头作为键值对。值支持使用 `$VAR_NAME` 或 `${VAR_NAME}` 语法的环境变量插值。仅解析 `allowedEnvVars` 中列出的变量 |534| `headers` | 否 | 其他 HTTP 标头作为键值对。值支持使用 `$VAR_NAME` 或 `${VAR_NAME}` 语法的环境变量插值。仅解析 `allowedEnvVars` 中列出的变量 |
535| `allowedEnvVars` | 否 | 可能被插值到标头值中的环境变量名称列表。对未列出变量的引用被替换为空字符串。任何环境变量插值都需要 |535| `allowedEnvVars` | 否 | 可能被插值到标头值中的环境变量名称列表。对未列出变量的引用被替换为空字符串。任何环境变量插值都需要 |
570除了 [通用字段](#common-fields)，MCP 工具 hooks 接受这些字段：570除了 [通用字段](#common-fields)，MCP 工具 hooks 接受这些字段：
571 571
572| 字段 | 必需 | 描述 |572| 字段 | 必需 | 描述 |
573| :------- | :- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |573| :- | :- | :- |
574| `server` | 是 | 配置的 MCP 服务器的名称。对于 [插件捆绑的服务器](/docs/zh-CN/mcp#plugin-provided-mcp-servers)，这是范围名称 `plugin:<plugin-name>:<server-name>`，如 `plugin:my-plugin:db`，不是裸服务器密钥。服务器必须已连接；hook 永远不会触发 OAuth 或连接流 |574| `server` | 是 | 配置的 MCP 服务器的名称。对于 [插件捆绑的服务器](/docs/zh-CN/mcp#plugin-provided-mcp-servers)，这是范围名称 `plugin:<plugin-name>:<server-name>`，如 `plugin:my-plugin:db`，不是裸服务器密钥。服务器必须已连接；hook 永远不会触发 OAuth 或连接流 |
575| `tool` | 是 | 在该服务器上调用的工具的名称 |575| `tool` | 是 | 在该服务器上调用的工具的名称 |
576| `input` | 否 | 传递给工具的参数。字符串值支持来自 hook 的 [JSON 输入](#hook-input-and-output) 的 `${path}` 替换，如 `"${tool_input.file_path}"` |576| `input` | 否 | 传递给工具的参数。字符串值支持来自 hook 的 [JSON 输入](#hook-input-and-output) 的 `${path}` 替换，如 `"${tool_input.file_path}"` |
634除了 [通用字段](#common-fields)，提示和代理 hooks 接受这些字段：634除了 [通用字段](#common-fields)，提示和代理 hooks 接受这些字段：
635 635
636| 字段 | 必需 | 描述 |636| 字段 | 必需 | 描述 |
637| :------- | :- | :--------------------------------------------------------------------------------- |637| :- | :- | :- |
638| `prompt` | 是 | 发送给模型的提示文本。使用 `$ARGUMENTS` 作为 hook 输入 JSON 的占位符。用反斜杠转义以包含文字文本：`\$1.00` 呈现为 `$1.00` |638| `prompt` | 是 | 发送给模型的提示文本。使用 `$ARGUMENTS` 作为 hook 输入 JSON 的占位符。用反斜杠转义以包含文字文本：`\$1.00` 呈现为 `$1.00` |
639| `model` | 否 | 用于评估的模型。默认为快速模型 |639| `model` | 否 | 用于评估的模型。默认为快速模型 |
640 640
786Hook 事件接收这些字段作为 JSON，除了每个 [hook 事件](#hook-events)部分中记录的事件特定字段。对于命令 hook，此 JSON 通过 stdin 到达。对于 HTTP hook，它作为 POST 请求体到达。786Hook 事件接收这些字段作为 JSON，除了每个 [hook 事件](#hook-events)部分中记录的事件特定字段。对于命令 hook，此 JSON 通过 stdin 到达。对于 HTTP hook，它作为 POST 请求体到达。
787 787
788| 字段 | 描述 |788| 字段 | 描述 |
789| :---------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |789| :- | :- |
790| `session_id` | 当前会话标识符 |790| `session_id` | 当前会话标识符 |
791| `prompt_id` | 标识当前正在处理的用户提示的 UUID。与 [OpenTelemetry 事件上的 `prompt.id` 属性](/docs/zh-CN/monitoring-usage#event-correlation-attributes)匹配，因此您可以将 hook 输出与单个提示的遥测关联起来。在第一个用户输入之前不存在。需要 Claude Code v2.1.196 或更高版本 |791| `prompt_id` | 标识当前正在处理的用户提示的 UUID。与 [OpenTelemetry 事件上的 `prompt.id` 属性](/docs/zh-CN/monitoring-usage#event-correlation-attributes)匹配，因此您可以将 hook 输出与单个提示的遥测关联起来。在第一个用户输入之前不存在。需要 Claude Code v2.1.196 或更高版本 |
792| `transcript_path` | 对话 JSON 的路径。转录文件异步写入，可能滞后于内存中的对话，因此当 hook 触发时，它可能还不包括当前轮次的最新消息。需要当前轮次最终助手文本的 hook 应在 [Stop](#stop) 和 [SubagentStop](#subagentstop) 上使用 `last_assistant_message`，而不是读取转录 |792| `transcript_path` | 对话 JSON 的路径。转录文件异步写入，可能滞后于内存中的对话，因此当 hook 触发时，它可能还不包括当前轮次的最新消息。需要当前轮次最终助手文本的 hook 应在 [Stop](#stop) 和 [SubagentStop](#subagentstop) 上使用 `last_assistant_message`，而不是读取转录 |
799使用 `--agent` 运行或在 subagent 内部时，包括两个额外字段：799使用 `--agent` 运行或在 subagent 内部时，包括两个额外字段：
800 800
801| 字段 | 描述 |801| 字段 | 描述 |
802| :----------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |802| :- | :- |
803| `agent_id` | subagent 的唯一标识符。仅当 hook 在 subagent 调用内触发时存在。使用此来区分 subagent hook 调用和主线程调用。 |803| `agent_id` | subagent 的唯一标识符。仅当 hook 在 subagent 调用内触发时存在。使用此来区分 subagent hook 调用和主线程调用。 |
804| `agent_type` | Agent 名称（例如，`"Explore"` 或 `"security-reviewer"`）。当会话使用 `--agent` 或 hook 在 subagent 内触发时存在。对于 subagent，subagent 的类型优先于会话的 `--agent` 值。请参阅 [SubagentStart](#subagentstart) 了解自定义和插件 subagent 报告的值以及如何针对插件范围的名称编写匹配器。 |804| `agent_type` | Agent 名称（例如，`"Explore"` 或 `"security-reviewer"`）。当会话使用 `--agent` 或 hook 在 subagent 内触发时存在。对于 subagent，subagent 的类型优先于会话的 `--agent` 值。请参阅 [SubagentStart](#subagentstart) 了解自定义和插件 subagent 报告的值以及如何针对插件范围的名称编写匹配器。 |
805 805
926退出代码 2 是 hook 发出"停止，不要这样做"信号的方式。效果取决于事件，因为某些事件代表可以被阻止的操作（如尚未发生的工具调用），而其他事件代表已经发生或无法防止的事情。926退出代码 2 是 hook 发出"停止，不要这样做"信号的方式。效果取决于事件，因为某些事件代表可以被阻止的操作（如尚未发生的工具调用），而其他事件代表已经发生或无法防止的事情。
927 927
928| Hook 事件 | 可以阻止？ | 退出 2 时发生什么 |928| Hook 事件 | 可以阻止？ | 退出 2 时发生什么 |
929| :-------------------- | :---- | :---------------------------------------------------------------------------------------------------------------------------------------------------- |929| :- | :- | :- |
930| `PreToolUse` | 是 | 阻止工具调用 |930| `PreToolUse` | 是 | 阻止工具调用 |
931| `PermissionRequest` | 否 | 此事件不接受退出代码 2，权限流程保持不变。改为通过 [`decision` 对象](#permissionrequest-decision-control)拒绝 |931| `PermissionRequest` | 否 | 此事件不接受退出代码 2，权限流程保持不变。改为通过 [`decision` 对象](#permissionrequest-decision-control)拒绝 |
932| `UserPromptSubmit` | 是 | 阻止提示处理并删除提示 |932| `UserPromptSubmit` | 是 | 阻止提示处理并删除提示 |
1003* **`hookSpecificOutput`** 是需要更丰富控制的事件的嵌套对象。它需要一个 `hookEventName` 字段设置为事件名称。1003* **`hookSpecificOutput`** 是需要更丰富控制的事件的嵌套对象。它需要一个 `hookEventName` 字段设置为事件名称。
1004 1004
1005| 字段 | 默认 | 描述 |1005| 字段 | 默认 | 描述 |
1006| :----------------- | :------ | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |1006| :- | :- | :- |
1007| `continue` | `true` | 如果 `false`，Claude 在 hook 运行后完全停止处理。优先于任何事件特定的决策字段 |1007| `continue` | `true` | 如果 `false`，Claude 在 hook 运行后完全停止处理。优先于任何事件特定的决策字段 |
1008| `stopReason` | 无 | 当 `continue` 为 `false` 时向用户显示的消息。它保留在对话中，因此如果对话继续，Claude 会看到它 |1008| `stopReason` | 无 | 当 `continue` 为 `false` 时向用户显示的消息。它保留在对话中，因此如果对话继续，Claude 会看到它 |
1009| `suppressOutput` | `false` | 无效果：Claude Code 接受字段但不作用。成功的 hook 的 stdout 从不在转录中显示，并在调试日志中记录 |1009| `suppressOutput` | `false` | 无效果：Claude Code 接受字段但不作用。成功的 hook 的 stdout 从不在转录中显示，并在调试日志中记录 |
1101并非每个事件都支持通过 JSON 阻止或控制行为。支持的事件各自使用不同的字段集来表达该决策。在编写 hook 之前，使用此表作为快速参考：1101并非每个事件都支持通过 JSON 阻止或控制行为。支持的事件各自使用不同的字段集来表达该决策。在编写 hook 之前，使用此表作为快速参考：
1102 1102
1103| 事件 | 决策模式 | 关键字段 |1103| 事件 | 决策模式 | 关键字段 |
1104| :-------------------------------------------------------------------------------------------------------------------------- | :---------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |1104| :- | :- | :- |
1105| UserPromptSubmit、UserPromptExpansion、PostToolUse、PostToolUseFailure、PostToolBatch、Stop、SubagentStop、ConfigChange、PreCompact | 顶级 `decision` | `decision: "block"`、`reason`。Stop 和 SubagentStop 也接受 `hookSpecificOutput.additionalContext` 用于[继续对话的非错误反馈](#stop-decision-control) |1105| UserPromptSubmit、UserPromptExpansion、PostToolUse、PostToolUseFailure、PostToolBatch、Stop、SubagentStop、ConfigChange、PreCompact | 顶级 `decision` | `decision: "block"`、`reason`。Stop 和 SubagentStop 也接受 `hookSpecificOutput.additionalContext` 用于[继续对话的非错误反馈](#stop-decision-control) |
1106| TeammateIdle、TaskCompleted | 退出代码或 `continue: false` | 退出代码 2 用 stderr 反馈阻止操作。JSON `{"continue": false, "stopReason": "..."}` 也完全停止队友，匹配 `Stop` hook 行为；[TaskCompleted 在 `TaskUpdate` 工具触发事件时忽略它](#taskcompleted-decision-control) |1106| TeammateIdle、TaskCompleted | 退出代码或 `continue: false` | 退出代码 2 用 stderr 反馈阻止操作。JSON `{"continue": false, "stopReason": "..."}` 也完全停止队友，匹配 `Stop` hook 行为；[TaskCompleted 在 `TaskUpdate` 工具触发事件时忽略它](#taskcompleted-decision-control) |
1107| TaskCreated | 退出代码或顶级 `decision` | 退出代码 2 或 `decision: "block"` [取消任务](#taskcreated-decision-control)并将消息返回给 Claude。`continue: false` 被忽略 |1107| TaskCreated | 退出代码或顶级 `decision` | 退出代码 2 或 `decision: "block"` [取消任务](#taskcreated-decision-control)并将消息返回给 Claude。`continue: false` 被忽略 |
1192匹配器值对应于会话的启动方式：1192匹配器值对应于会话的启动方式：
1193 1193
1194| 匹配器 | 何时触发 |1194| 匹配器 | 何时触发 |
1195| :-------- | :------------------------------------------------------------------------------- |1195| :- | :- |
1196| `startup` | 新会话 |1196| `startup` | 新会话 |
1197| `resume` | `--resume`、`--continue` 或 `/resume` |1197| `resume` | `--resume`、`--continue` 或 `/resume` |
1198| `clear` | `/clear` |1198| `clear` | `/clear` |
1216除了 [常见输入字段](#common-input-fields) 外，SessionStart hooks 还接收 `source` 和可选的 `model`、`agent_type` 和 `session_title`：1216除了 [常见输入字段](#common-input-fields) 外，SessionStart hooks 还接收 `source` 和可选的 `model`、`agent_type` 和 `session_title`：
1217 1217
1218| 字段 | 描述 |1218| 字段 | 描述 |
1219| :-------------- | :------------------------------------------------------------------------------------------------------ |1219| :- | :- |
1220| `source` | 会话如何启动：新会话为 `"startup"`、恢复的会话为 `"resume"`、`/clear` 后为 `"clear"`、压缩后为 `"compact"`，或从现有会话分叉的新会话为 `"fork"` |1220| `source` | 会话如何启动：新会话为 `"startup"`、恢复的会话为 `"resume"`、`/clear` 后为 `"clear"`、压缩后为 `"compact"`，或从现有会话分叉的新会话为 `"fork"` |
1221| `model` | 活跃的模型标识符。它可以被省略，例如在 `/clear` 后或通过对话恢复恢复会话时，因此在读取它之前检查该字段 |1221| `model` | 活跃的模型标识符。它可以被省略，例如在 `/clear` 后或通过对话恢复恢复会话时，因此在读取它之前检查该字段 |
1222| `agent_type` | agent 名称，当您使用 `claude --agent <name>` 启动 Claude Code 时出现 |1222| `agent_type` | agent 名称，当您使用 `claude --agent <name>` 启动 Claude Code 时出现 |
1225当 `source` 为 `"resume"` 或 `"fork"` 且成绩单包含至少一个来自 Claude 的响应时，SessionStart hooks 还接收下面的四个字段。您的 hook 可以使用它们在第一个请求之前报告恢复陈旧对话的成本，例如在 [`systemMessage`](#json-output) 中。这些字段需要 Claude Code v2.1.251 或更高版本。1225当 `source` 为 `"resume"` 或 `"fork"` 且成绩单包含至少一个来自 Claude 的响应时，SessionStart hooks 还接收下面的四个字段。您的 hook 可以使用它们在第一个请求之前报告恢复陈旧对话的成本，例如在 [`systemMessage`](#json-output) 中。这些字段需要 Claude Code v2.1.251 或更高版本。
1226 1226
1227| 字段 | 描述 |1227| 字段 | 描述 |
1228| :---------------------------- | :--------------------------------------------------------------------------------------------- |1228| :- | :- |
1229| `seconds_since_last_response` | 自恢复成绩单中最后一个响应以来的挂钟秒数 |1229| `seconds_since_last_response` | 自恢复成绩单中最后一个响应以来的挂钟秒数 |
1230| `context_tokens` | 恢复会话的第一个请求作为其提示重新发送的令牌 |1230| `context_tokens` | 恢复会话的第一个请求作为其提示重新发送的令牌 |
1231| `prompt_cache_likely_expired` | 当最后一个响应早于会话的 [prompt cache 生命周期](/docs/zh-CN/prompt-caching#cache-lifetime) 或更晚的压缩替换了缓存的对话时为 `true` |1231| `prompt_cache_likely_expired` | 当最后一个响应早于会话的 [prompt cache 生命周期](/docs/zh-CN/prompt-caching#cache-lifetime) 或更晚的压缩替换了缓存的对话时为 `true` |
1255Claude Code 将它 [视为纯文本](#exit-code-0) 的 stdout 添加到 Claude 的上下文中。除了所有 hooks 可用的 [JSON 输出字段](#json-output) 外，您还可以返回这些事件特定的字段：1255Claude Code 将它 [视为纯文本](#exit-code-0) 的 stdout 添加到 Claude 的上下文中。除了所有 hooks 可用的 [JSON 输出字段](#json-output) 外，您还可以返回这些事件特定的字段：
1256 1256
1257| 字段 | 描述 |1257| 字段 | 描述 |
1258| :------------------- | :------------------------------------------------------------------------------------------------------------------------------------------- |1258| :- | :- |
1259| `additionalContext` | 在对话开始时添加到 Claude 上下文的字符串，在第一个提示之前。有关文本如何传递以及放入其中的内容，请参阅 [为 Claude 添加上下文](#add-context-for-claude) |1259| `additionalContext` | 在对话开始时添加到 Claude 上下文的字符串，在第一个提示之前。有关文本如何传递以及放入其中的内容，请参阅 [为 Claude 添加上下文](#add-context-for-claude) |
1260| `initialUserMessage` | 用作会话第一个用户消息的字符串。适用于 [非交互模式](/docs/zh-CN/headless)，带有 `-p` 标志，即使未提供提示，它也成为第一个回合。如果提供了提示，它作为下一个回合跟随。与 `additionalContext` 不同，后者附加到现有回合，这会创建回合 |1260| `initialUserMessage` | 用作会话第一个用户消息的字符串。适用于 [非交互模式](/docs/zh-CN/headless)，带有 `-p` 标志，即使未提供提示，它也成为第一个回合。如果提供了提示，它作为下一个回合跟随。与 `additionalContext` 不同，后者附加到现有回合，这会创建回合 |
1261| `sessionTitle` | 设置会话标题，与 `/rename` 效果相同。用于从启动文件夹、git 分支或 worktree 名称自动命名会话。当 `source` 为 `"startup"`、`"resume"` 或 `"fork"` 时适用；在 `"clear"` 和 `"compact"` 上被忽略 |1261| `sessionTitle` | 设置会话标题，与 `/rename` 效果相同。用于从启动文件夹、git 分支或 worktree 名称自动命名会话。当 `source` 为 `"startup"`、`"resume"` 或 `"fork"` 时适用；在 `"clear"` 和 `"compact"` 上被忽略 |
1339匹配器值对应于触发 hook 的 CLI 标志：1339匹配器值对应于触发 hook 的 CLI 标志：
1340 1340
1341| 匹配器 | 何时触发 |1341| 匹配器 | 何时触发 |
1342| :------------ | :---------------------------------------- |1342| :- | :- |
1343| `init` | `claude --init-only` 或 `claude -p --init` |1343| `init` | `claude --init-only` 或 `claude -p --init` |
1344| `maintenance` | `claude -p --maintenance` |1344| `maintenance` | `claude -p --maintenance` |
1345 1345
1392除了 [常见输入字段](#common-input-fields) 外，InstructionsLoaded hooks 接收这些字段：1392除了 [常见输入字段](#common-input-fields) 外，InstructionsLoaded hooks 接收这些字段：
1393 1393
1394| 字段 | 描述 |1394| 字段 | 描述 |
1395| :------------------ | :-------------------------------------------------------------------------------------------------------------------------- |1395| :- | :- |
1396| `file_path` | 加载的指令文件的绝对路径 |1396| `file_path` | 加载的指令文件的绝对路径 |
1397| `memory_type` | 文件的范围：`"User"`、`"Project"`、`"Local"` 或 `"Managed"` |1397| `memory_type` | 文件的范围：`"User"`、`"Project"`、`"Local"` 或 `"Managed"` |
1398| `load_reason` | 文件加载的原因：`"session_start"`、`"nested_traversal"`、`"path_glob_match"`、`"include"` 或 `"compact"`。`"compact"` 值在压缩事件后重新加载指令文件时触发 |1398| `load_reason` | 文件加载的原因：`"session_start"`、`"nested_traversal"`、`"path_glob_match"`、`"include"` 或 `"compact"`。`"compact"` 值在压缩事件后重新加载指令文件时触发 |
1463要阻止提示，返回一个 `decision` 设置为 `"block"` 的 JSON 对象：1463要阻止提示，返回一个 `decision` 设置为 `"block"` 的 JSON 对象：
1464 1464
1465| 字段 | 描述 |1465| 字段 | 描述 |
1466| :----------------------- | :------------------------------------------------------------------------------ |1466| :- | :- |
1467| `decision` | `"block"` 防止提示被处理并从上下文中删除它。省略以允许提示继续 |1467| `decision` | `"block"` 防止提示被处理并从上下文中删除它。省略以允许提示继续 |
1468| `reason` | 当 `decision` 为 `"block"` 时显示给用户。不添加到上下文 |1468| `reason` | 当 `decision` 为 `"block"` 时显示给用户。不添加到上下文 |
1469| `additionalContext` | 与提交的提示一起添加到 Claude 上下文的字符串。有关详细信息，请参阅 [为 Claude 添加上下文](#add-context-for-claude) |1469| `additionalContext` | 与提交的提示一起添加到 Claude 上下文的字符串。有关详细信息，请参阅 [为 Claude 添加上下文](#add-context-for-claude) |
1522`UserPromptExpansion` hooks 可以阻止扩展或添加上下文。所有 [JSON 输出字段](#json-output) 都可用。1522`UserPromptExpansion` hooks 可以阻止扩展或添加上下文。所有 [JSON 输出字段](#json-output) 都可用。
1523 1523
1524| 字段 | 描述 |1524| 字段 | 描述 |
1525| :------------------ | :------------------------------------------------------------------------------ |1525| :- | :- |
1526| `decision` | `"block"` 防止命令扩展。省略以允许它继续 |1526| `decision` | `"block"` 防止命令扩展。省略以允许它继续 |
1527| `reason` | 当 `decision` 为 `"block"` 时显示给用户 |1527| `reason` | 当 `decision` 为 `"block"` 时显示给用户 |
1528| `additionalContext` | 与扩展的提示一起添加到 Claude 上下文的字符串。有关详细信息，请参阅 [为 Claude 添加上下文](#add-context-for-claude) |1528| `additionalContext` | 与扩展的提示一起添加到 Claude 上下文的字符串。有关详细信息，请参阅 [为 Claude 添加上下文](#add-context-for-claude) |
1567除了 [常见输入字段](#common-input-fields) 外，MessageDisplay hooks 接收回合和消息的标识符、此调用在消息中的位置以及 `delta` 中的新文本。批次边界取决于文本如何流式传输，因此使用 `index` 和 `final` 来跟踪通过消息的进度，而不是期望行以特定方式分组。1567除了 [常见输入字段](#common-input-fields) 外，MessageDisplay hooks 接收回合和消息的标识符、此调用在消息中的位置以及 `delta` 中的新文本。批次边界取决于文本如何流式传输，因此使用 `index` 和 `final` 来跟踪通过消息的进度，而不是期望行以特定方式分组。
1568 1568
1569| 字段 | 描述 |1569| 字段 | 描述 |
1570| :----------- | :------------------------------------------------------------------------------------------------------------------------------------------------------ |1570| :- | :- |
1571| `turn_id` | 当前回合的 UUID |1571| `turn_id` | 当前回合的 UUID |
1572| `message_id` | 正在显示的助手消息的 UUID。在同一消息的每个批次中稳定。这不是 API `msg_…` id，因此无法与成绩单消息 id 关联 |1572| `message_id` | 正在显示的助手消息的 UUID。在同一消息的每个批次中稳定。这不是 API `msg_…` id，因此无法与成绩单消息 id 关联 |
1573| `index` | 此批次在消息中的零基索引 |1573| `index` | 此批次在消息中的零基索引 |
1595除了所有 hooks 可用的 [JSON 输出字段](#json-output) 外，MessageDisplay hooks 可以返回 `displayContent` 来替换屏幕上的 delta：1595除了所有 hooks 可用的 [JSON 输出字段](#json-output) 外，MessageDisplay hooks 可以返回 `displayContent` 来替换屏幕上的 delta：
1596 1596
1597| 字段 | 描述 |1597| 字段 | 描述 |
1598| :--------------- | :----------------------- |1598| :- | :- |
1599| `displayContent` | 显示代替 delta 的文本。省略以显示原始文本 |1599| `displayContent` | 显示代替 delta 的文本。省略以显示原始文本 |
1600 1600
1601MessageDisplay hooks 没有决策控制。它们无法阻止消息或更改成绩单中存储或发送给 Claude 的内容。Claude Code 从其 JSON 输出中作用于 `displayContent` 并丢弃 `systemMessage` 和 `continue`。1601MessageDisplay hooks 没有决策控制。它们无法阻止消息或更改成绩单中存储或发送给 Claude 的内容。Claude Code 从其 JSON 输出中作用于 `displayContent` 并丢弃 `systemMessage` 和 `continue`。
1736执行 shell 命令。1736执行 shell 命令。
1737 1737
1738| 字段 | 类型 | 示例 | 描述 |1738| 字段 | 类型 | 示例 | 描述 |
1739| :------------------ | :------ | :----------------- | :--------------------------------------------------------------------------- |1739| :- | :- | :- | :- |
1740| `command` | string | `"npm test"` | 要执行的 shell 命令 |1740| `command` | string | `"npm test"` | 要执行的 shell 命令 |
1741| `description` | string | `"Run test suite"` | 命令执行操作的可选描述 |1741| `description` | string | `"Run test suite"` | 命令执行操作的可选描述 |
1742| `timeout` | number | `120000` | 可选超时（毫秒）。超过 [最大值](/docs/zh-CN/tools-reference#bash-tool-behavior) 的值被减少到最大值而不是被拒绝 |1742| `timeout` | number | `120000` | 可选超时（毫秒）。超过 [最大值](/docs/zh-CN/tools-reference#bash-tool-behavior) 的值被减少到最大值而不是被拒绝 |
1753`changedFiles` 和 `files` 列出命令更改的内容；其余字段说明该列表的完整性和可靠性。1753`changedFiles` 和 `files` 列出命令更改的内容；其余字段说明该列表的完整性和可靠性。
1754 1754
1755| 字段 | 类型 | 示例 | 描述 |1755| 字段 | 类型 | 示例 | 描述 |
1756| :------------- | :------ | :------------------------------------------------------ | :---------------------------------------------------------------------- |1756| :- | :- | :- | :- |
1757| `changedFiles` | array | `["/path/to/src/app.ts"]` | 命令更改的文件的绝对路径，最多 200 个。每当 `files` 保持 diff 或 `moreFiles` 高于零时出现 |1757| `changedFiles` | array | `["/path/to/src/app.ts"]` | 命令更改的文件的绝对路径，最多 200 个。每当 `files` 保持 diff 或 `moreFiles` 高于零时出现 |
1758| `files` | array | `[{"filePath": "/path/to/src/app.ts", "hunks": [...]}]` | 最多 5 个更改文件的 diffs，用于显示。对于命令添加或删除的文件，`created` 或 `deleted` 为 `true` |1758| `files` | array | `[{"filePath": "/path/to/src/app.ts", "hunks": [...]}]` | 最多 5 个更改文件的 diffs，用于显示。对于命令添加或删除的文件，`created` 或 `deleted` 为 `true` |
1759| `moreFiles` | number | `2` | 在 `files` 中没有 diff 的更改文件的计数 |1759| `moreFiles` | number | `2` | 在 `files` 中没有 diff 的更改文件的计数 |
1772字段与 Bash 工具匹配，命令字符串在 `command` 中：1772字段与 Bash 工具匹配，命令字符串在 `command` 中：
1773 1773
1774| 字段 | 类型 | 示例 | 描述 |1774| 字段 | 类型 | 示例 | 描述 |
1775| :------------------ | :------ | :------------------------- | :----------------- |1775| :- | :- | :- | :- |
1776| `command` | string | `"Get-ChildItem -Recurse"` | 要执行的 PowerShell 命令 |1776| `command` | string | `"Get-ChildItem -Recurse"` | 要执行的 PowerShell 命令 |
1777| `description` | string | `"List files recursively"` | 命令执行操作的可选描述 |1777| `description` | string | `"List files recursively"` | 命令执行操作的可选描述 |
1778| `timeout` | number | `120000` | 可选超时（毫秒） |1778| `timeout` | number | `120000` | 可选超时（毫秒） |
1791创建或覆盖文件。1791创建或覆盖文件。
1792 1792
1793| 字段 | 类型 | 示例 | 描述 |1793| 字段 | 类型 | 示例 | 描述 |
1794| :---------- | :----- | :-------------------- | :---------- |1794| :- | :- | :- | :- |
1795| `file_path` | string | `"/path/to/file.txt"` | 要写入的文件的绝对路径 |1795| `file_path` | string | `"/path/to/file.txt"` | 要写入的文件的绝对路径 |
1796| `content` | string | `"file content"` | 要写入文件的内容 |1796| `content` | string | `"file content"` | 要写入文件的内容 |
1797 1797
1802替换现有文件中的字符串。1802替换现有文件中的字符串。
1803 1803
1804| 字段 | 类型 | 示例 | 描述 |1804| 字段 | 类型 | 示例 | 描述 |
1805| :------------ | :------ | :-------------------- | :---------- |1805| :- | :- | :- | :- |
1806| `file_path` | string | `"/path/to/file.txt"` | 要编辑的文件的绝对路径 |1806| `file_path` | string | `"/path/to/file.txt"` | 要编辑的文件的绝对路径 |
1807| `old_string` | string | `"original text"` | 要查找和替换的文本 |1807| `old_string` | string | `"original text"` | 要查找和替换的文本 |
1808| `new_string` | string | `"replacement text"` | 替换文本 |1808| `new_string` | string | `"replacement text"` | 替换文本 |
1815读取文件内容。1815读取文件内容。
1816 1816
1817| 字段 | 类型 | 示例 | 描述 |1817| 字段 | 类型 | 示例 | 描述 |
1818| :---------- | :----- | :-------------------- | :---------- |1818| :- | :- | :- | :- |
1819| `file_path` | string | `"/path/to/file.txt"` | 要读取的文件的绝对路径 |1819| `file_path` | string | `"/path/to/file.txt"` | 要读取的文件的绝对路径 |
1820| `offset` | number | `10` | 可选行号以开始读取 |1820| `offset` | number | `10` | 可选行号以开始读取 |
1821| `limit` | number | `50` | 可选要读取的行数 |1821| `limit` | number | `50` | 可选要读取的行数 |
1827查找与 glob 模式匹配的文件。1827查找与 glob 模式匹配的文件。
1828 1828
1829| 字段 | 类型 | 示例 | 描述 |1829| 字段 | 类型 | 示例 | 描述 |
1830| :-------- | :----- | :--------------- | :----------------- |1830| :- | :- | :- | :- |
1831| `pattern` | string | `"**/*.ts"` | 要匹配文件的 glob 模式 |1831| `pattern` | string | `"**/*.ts"` | 要匹配文件的 glob 模式 |
1832| `path` | string | `"/path/to/dir"` | 可选要搜索的目录。默认为当前工作目录 |1832| `path` | string | `"/path/to/dir"` | 可选要搜索的目录。默认为当前工作目录 |
1833 1833
1838使用正则表达式搜索文件内容。1838使用正则表达式搜索文件内容。
1839 1839
1840| 字段 | 类型 | 示例 | 描述 |1840| 字段 | 类型 | 示例 | 描述 |
1841| :------------ | :------ | :--------------- | :------------------------------------------------------------------------ |1841| :- | :- | :- | :- |
1842| `pattern` | string | `"TODO.*fix"` | 要搜索的正则表达式模式 |1842| `pattern` | string | `"TODO.*fix"` | 要搜索的正则表达式模式 |
1843| `path` | string | `"/path/to/dir"` | 可选要搜索的文件或目录 |1843| `path` | string | `"/path/to/dir"` | 可选要搜索的文件或目录 |
1844| `glob` | string | `"*.ts"` | 可选 glob 模式以过滤文件 |1844| `glob` | string | `"*.ts"` | 可选 glob 模式以过滤文件 |
1853获取和处理网络内容。1853获取和处理网络内容。
1854 1854
1855| 字段 | 类型 | 示例 | 描述 |1855| 字段 | 类型 | 示例 | 描述 |
1856| :------- | :----- | :---------------------------- | :----------- |1856| :- | :- | :- | :- |
1857| `url` | string | `"https://example.com/api"` | 要从中获取内容的 URL |1857| `url` | string | `"https://example.com/api"` | 要从中获取内容的 URL |
1858| `prompt` | string | `"Extract the API endpoints"` | 在获取的内容上运行的提示 |1858| `prompt` | string | `"Extract the API endpoints"` | 在获取的内容上运行的提示 |
1859 1859
1864搜索网络。1864搜索网络。
1865 1865
1866| 字段 | 类型 | 示例 | 描述 |1866| 字段 | 类型 | 示例 | 描述 |
1867| :---------------- | :----- | :----------------------------- | :------------- |1867| :- | :- | :- | :- |
1868| `query` | string | `"react hooks best practices"` | 搜索查询 |1868| `query` | string | `"react hooks best practices"` | 搜索查询 |
1869| `allowed_domains` | array | `["docs.example.com"]` | 可选：仅包含来自这些域的结果 |1869| `allowed_domains` | array | `["docs.example.com"]` | 可选：仅包含来自这些域的结果 |
1870| `blocked_domains` | array | `["spam.example.com"]` | 可选：排除来自这些域的结果 |1870| `blocked_domains` | array | `["spam.example.com"]` | 可选：排除来自这些域的结果 |
1876生成 [子代理](/docs/zh-CN/sub-agents)。1876生成 [子代理](/docs/zh-CN/sub-agents)。
1877 1877
1878| 字段 | 类型 | 示例 | 描述 |1878| 字段 | 类型 | 示例 | 描述 |
1879| :-------------- | :----- | :------------------------- | :-------------- |1879| :- | :- | :- | :- |
1880| `prompt` | string | `"Find all API endpoints"` | agent 要执行的任务 |1880| `prompt` | string | `"Find all API endpoints"` | agent 要执行的任务 |
1881| `description` | string | `"Find API endpoints"` | 任务的简短描述 |1881| `description` | string | `"Find API endpoints"` | 任务的简短描述 |
1882| `subagent_type` | string | `"Explore"` | 要使用的专门 agent 类型 |1882| `subagent_type` | string | `"Explore"` | 要使用的专门 agent 类型 |
1885当前台 Agent 调用完成时，您的 [PostToolUse hook](#posttooluse) 在 `tool_response` 中接收子代理的结果和运行遥测。读取这些字段以检查运行；对于跨子代理的令牌和成本汇总，使用 [令牌和成本计数器](/docs/zh-CN/monitoring-usage#token-counter) 过滤到 `query_source` `"subagent"`，因为 `totalTokens` 和 `usage` 仅涵盖最终请求：1885当前台 Agent 调用完成时，您的 [PostToolUse hook](#posttooluse) 在 `tool_response` 中接收子代理的结果和运行遥测。读取这些字段以检查运行；对于跨子代理的令牌和成本汇总，使用 [令牌和成本计数器](/docs/zh-CN/monitoring-usage#token-counter) 过滤到 `query_source` `"subagent"`，因为 `totalTokens` 和 `usage` 仅涵盖最终请求：
1886 1886
1887| 字段 | 类型 | 示例 | 描述 |1887| 字段 | 类型 | 示例 | 描述 |
1888| :------------------ | :----- | :---------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------- |1888| :- | :- | :- | :- |
1889| `status` | string | `"completed"` | 前台子代理为 `"completed"`，后台子代理为 `"async_launched"`。从 v2.1.198 起，子代理默认在后台运行，因此省略的 `run_in_background` 也产生 `"async_launched"` |1889| `status` | string | `"completed"` | 前台子代理为 `"completed"`，后台子代理为 `"async_launched"`。从 v2.1.198 起，子代理默认在后台运行，因此省略的 `run_in_background` 也产生 `"async_launched"` |
1890| `agentId` | string | `"a4d2c8f1e0b3a297"` | 子代理运行的标识符 |1890| `agentId` | string | `"a4d2c8f1e0b3a297"` | 子代理运行的标识符 |
1891| `content` | array | `[{"type": "text", "text": "Found 12 endpoints..."}]` | 子代理的最终文本块，或对于其报告通过 `SubagentHandback` 的子代理，关于该交接的简短说明代替 |1891| `content` | array | `[{"type": "text", "text": "Found 12 endpoints..."}]` | 子代理的最终文本块，或对于其报告通过 `SubagentHandback` 的子代理，关于该交接的简短说明代替 |
1911向用户提出一到四个多选题。1911向用户提出一到四个多选题。
1912 1912
1913| 字段 | 类型 | 示例 | 描述 |1913| 字段 | 类型 | 示例 | 描述 |
1914| :---------- | :----- | :----------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------- |1914| :- | :- | :- | :- |
1915| `questions` | array | `[{"question": "Which framework?", "header": "Framework", "options": [{"label": "React"}], "multiSelect": false}]` | 要呈现的问题，每个都有 `question` 字符串、简短 `header`、`options` 数组和可选 `multiSelect` 标志 |1915| `questions` | array | `[{"question": "Which framework?", "header": "Framework", "options": [{"label": "React"}], "multiSelect": false}]` | 要呈现的问题，每个都有 `question` 字符串、简短 `header`、`options` 数组和可选 `multiSelect` 标志 |
1916| `answers` | object | `{"Which framework?": "React"}` | 可选。将问题文本映射到选定的选项标签。多选答案用逗号连接标签。Claude 不设置此字段；通过 `updatedInput` 提供它以以编程方式回答 |1916| `answers` | object | `{"Which framework?": "React"}` | 可选。将问题文本映射到选定的选项标签。多选答案用逗号连接标签。Claude 不设置此字段；通过 `updatedInput` 提供它以以编程方式回答 |
1917 1917
1922呈现计划并要求用户在 Claude 离开 [plan mode](/docs/zh-CN/permission-modes#analyze-before-you-edit-with-plan-mode) 之前批准它。Claude 在调用工具之前将计划写入磁盘上的文件，因此来自模型的文字 `tool_input` 通常为空。Claude Code 在将输入传递给 hooks 之前注入计划内容和文件路径。1922呈现计划并要求用户在 Claude 离开 [plan mode](/docs/zh-CN/permission-modes#analyze-before-you-edit-with-plan-mode) 之前批准它。Claude 在调用工具之前将计划写入磁盘上的文件，因此来自模型的文字 `tool_input` 通常为空。Claude Code 在将输入传递给 hooks 之前注入计划内容和文件路径。
1923 1923
1924| 字段 | 类型 | 示例 | 描述 |1924| 字段 | 类型 | 示例 | 描述 |
1925| :--------------- | :----- | :------------------------------------------ | :---------------------------------------------------------------- |1925| :- | :- | :- | :- |
1926| `plan` | string | `"## Refactor auth\n1. Extract..."` | Markdown 中的计划内容。从磁盘上的计划文件注入 |1926| `plan` | string | `"## Refactor auth\n1. Extract..."` | Markdown 中的计划内容。从磁盘上的计划文件注入 |
1927| `planFilePath` | string | `"/Users/.../plans/refactor-auth.md"` | 计划文件的路径。注入 |1927| `planFilePath` | string | `"/Users/.../plans/refactor-auth.md"` | 计划文件的路径。注入 |
1928| `allowedPrompts` | array | `[{"tool": "Bash", "prompt": "run tests"}]` | 已弃用。Claude Code 接受该字段但忽略它。在 v2.1.205 之前，它携带 Claude 请求实现计划的基于提示的权限 |1928| `allowedPrompts` | array | `[{"tool": "Bash", "prompt": "run tests"}]` | 已弃用。Claude Code 接受该字段但忽略它。在 v2.1.205 之前，它携带 Claude 请求实现计划的基于提示的权限 |
1936`PreToolUse` hooks 可以控制工具调用是否继续。与使用顶级 `decision` 字段的其他 hooks 不同，PreToolUse 在 `hookSpecificOutput` 对象内返回其决策。这给了它更丰富的控制：四个结果（允许、拒绝、询问或延迟）加上在执行前修改工具输入的能力。1936`PreToolUse` hooks 可以控制工具调用是否继续。与使用顶级 `decision` 字段的其他 hooks 不同，PreToolUse 在 `hookSpecificOutput` 对象内返回其决策。这给了它更丰富的控制：四个结果（允许、拒绝、询问或延迟）加上在执行前修改工具输入的能力。
1937 1937
1938| 字段 | 描述 |1938| 字段 | 描述 |
1939| :------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |1939| :- | :- |
1940| `permissionDecision` | `"allow"` 跳过权限提示，除了 [任何模式自动批准的操作](/docs/zh-CN/permission-modes#actions-no-mode-auto-approves) 和对于 `AskUserQuestion` 和 `ExitPlanMode`，它们需要 [`updatedInput` 与其配对](#allow-with-updatedinput)。`"deny"` 防止工具调用。`"ask"` 提示用户确认。`"defer"` 优雅地退出，以便稍后可以恢复工具。[拒绝和询问规则](/docs/zh-CN/permissions#manage-permissions) 仍然被评估，无论 hook 返回什么 |1940| `permissionDecision` | `"allow"` 跳过权限提示，除了 [任何模式自动批准的操作](/docs/zh-CN/permission-modes#actions-no-mode-auto-approves) 和对于 `AskUserQuestion` 和 `ExitPlanMode`，它们需要 [`updatedInput` 与其配对](#allow-with-updatedinput)。`"deny"` 防止工具调用。`"ask"` 提示用户确认。`"defer"` 优雅地退出，以便稍后可以恢复工具。[拒绝和询问规则](/docs/zh-CN/permissions#manage-permissions) 仍然被评估，无论 hook 返回什么 |
1941| `permissionDecisionReason` | 对于 `"allow"` 和 `"ask"`，显示给用户但不显示给 Claude。对于 `"deny"`，显示给 Claude。对于 `"defer"`，被忽略 |1941| `permissionDecisionReason` | 对于 `"allow"` 和 `"ask"`，显示给用户但不显示给 Claude。对于 `"deny"`，显示给 Claude。对于 `"defer"`，被忽略 |
1942| `updatedInput` | 在执行前修改工具的输入参数。替换整个输入对象，因此在修改的字段旁边包含未更改的字段。Claude Code 根据您的 hook 返回的输入而不是 Claude 发送的输入评估权限规则和 Bash 命令的 [自动后台资格](/docs/zh-CN/tools-reference#background-commands)。与 `"allow"` 结合以自动批准，或与 `"ask"` 结合以向用户显示修改的输入。对于 `"defer"`，被忽略 |1942| `updatedInput` | 在执行前修改工具的输入参数。替换整个输入对象，因此在修改的字段旁边包含未更改的字段。Claude Code 根据您的 hook 返回的输入而不是 Claude 发送的输入评估权限规则和 Bash 命令的 [自动后台资格](/docs/zh-CN/tools-reference#background-commands)。与 `"allow"` 结合以自动批准，或与 `"ask"` 结合以向用户显示修改的输入。对于 `"defer"`，被忽略 |
2069`PermissionRequest` hooks 可以允许或拒绝权限请求。除了所有 hooks 可用的 [JSON 输出字段](#json-output) 外，您的 hook 脚本可以返回一个带有这些事件特定字段的 `decision` 对象：2069`PermissionRequest` hooks 可以允许或拒绝权限请求。除了所有 hooks 可用的 [JSON 输出字段](#json-output) 外，您的 hook 脚本可以返回一个带有这些事件特定字段的 `decision` 对象：
2070 2070
2071| 字段 | 描述 |2071| 字段 | 描述 |
2072| :------------------- | :------------------------------------------------------------------------------------------------------------------- |2072| :- | :- |
2073| `behavior` | `"allow"` 授予权限，`"deny"` 拒绝它。[拒绝和询问规则](/docs/zh-CN/permissions#manage-permissions) 仍然被评估，因此返回 `"allow"` 的 hook 不会覆盖匹配的拒绝规则 |2073| `behavior` | `"allow"` 授予权限，`"deny"` 拒绝它。[拒绝和询问规则](/docs/zh-CN/permissions#manage-permissions) 仍然被评估，因此返回 `"allow"` 的 hook 不会覆盖匹配的拒绝规则 |
2074| `updatedInput` | 仅对 `"allow"`：在执行前修改工具的输入参数。替换整个输入对象，因此在修改的字段旁边包含未更改的字段。修改的输入针对拒绝和询问规则重新评估 |2074| `updatedInput` | 仅对 `"allow"`：在执行前修改工具的输入参数。替换整个输入对象，因此在修改的字段旁边包含未更改的字段。修改的输入针对拒绝和询问规则重新评估 |
2075| `updatedPermissions` | 仅对 `"allow"`：要应用的 [权限更新条目](#permission-update-entries) 数组，例如添加允许规则或更改会话权限模式 |2075| `updatedPermissions` | 仅对 `"allow"`：要应用的 [权限更新条目](#permission-update-entries) 数组，例如添加允许规则或更改会话权限模式 |
2099`updatedPermissions` 输出字段和 [`permission_suggestions` 输入字段](#permissionrequest-input) 都使用相同的条目对象数组。每个条目有一个 `type` 来确定其他字段，以及一个 `destination` 来控制更改的写入位置。2099`updatedPermissions` 输出字段和 [`permission_suggestions` 输入字段](#permissionrequest-input) 都使用相同的条目对象数组。每个条目有一个 `type` 来确定其他字段，以及一个 `destination` 来控制更改的写入位置。
2100 2100
2101| `type` | 字段 | 效果 |2101| `type` | 字段 | 效果 |
2102| :------------------ | :------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------- |2102| :- | :- | :- |
2103| `addRules` | `rules`、`behavior`、`destination` | 添加权限规则。`rules` 是 `{toolName, ruleContent?}` 对象的数组。省略 `ruleContent` 以匹配整个工具。`behavior` 是 `"allow"`、`"deny"` 或 `"ask"` |2103| `addRules` | `rules`、`behavior`、`destination` | 添加权限规则。`rules` 是 `{toolName, ruleContent?}` 对象的数组。省略 `ruleContent` 以匹配整个工具。`behavior` 是 `"allow"`、`"deny"` 或 `"ask"` |
2104| `replaceRules` | `rules`、`behavior`、`destination` | 用提供的 `rules` 替换 `destination` 处给定 `behavior` 的所有规则 |2104| `replaceRules` | `rules`、`behavior`、`destination` | 用提供的 `rules` 替换 `destination` 处给定 `behavior` 的所有规则 |
2105| `removeRules` | `rules`、`behavior`、`destination` | 删除给定 `behavior` 的匹配规则 |2105| `removeRules` | `rules`、`behavior`、`destination` | 删除给定 `behavior` 的匹配规则 |
2116每个条目上的 `destination` 字段确定更改是保留在内存中还是持久化到设置文件。2116每个条目上的 `destination` 字段确定更改是保留在内存中还是持久化到设置文件。
2117 2117
2118| `destination` | 写入 |2118| `destination` | 写入 |
2119| :---------------- | :---------------------------- |2119| :- | :- |
2120| `session` | 仅在内存中，会话结束时丢弃 |2120| `session` | 仅在内存中，会话结束时丢弃 |
2121| `localSettings` | `.claude/settings.local.json` |2121| `localSettings` | `.claude/settings.local.json` |
2122| `projectSettings` | `.claude/settings.json` |2122| `projectSettings` | `.claude/settings.json` |
2165```2165```
2166 2166
2167| 字段 | 描述 |2167| 字段 | 描述 |
2168| :------------ | :--------------------------------------------- |2168| :- | :- |
2169| `duration_ms` | 可选。工具执行时间（毫秒）。不包括权限提示和 PreToolUse hooks 中花费的时间 |2169| `duration_ms` | 可选。工具执行时间（毫秒）。不包括权限提示和 PreToolUse hooks 中花费的时间 |
2170 2170
2171<h4 id="posttooluse-decision-control">2171<h4 id="posttooluse-decision-control">
2175`PostToolUse` hooks 可以在工具执行后提供反馈给 Claude。除了所有 hooks 可用的 [JSON 输出字段](#json-output) 外，您的 hook 脚本可以返回这些事件特定的字段：2175`PostToolUse` hooks 可以在工具执行后提供反馈给 Claude。除了所有 hooks 可用的 [JSON 输出字段](#json-output) 外，您的 hook 脚本可以返回这些事件特定的字段：
2176 2176
2177| 字段 | 描述 |2177| 字段 | 描述 |
2178| :--------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |2178| :- | :- |
2179| `decision` | `"block"` 在工具结果旁边添加 `reason`。Claude 仍然看到原始输出；要替换它，请使用 `updatedToolOutput` |2179| `decision` | `"block"` 在工具结果旁边添加 `reason`。Claude 仍然看到原始输出；要替换它，请使用 `updatedToolOutput` |
2180| `reason` | 当 `decision` 为 `"block"` 时显示给 Claude 的解释 |2180| `reason` | 当 `decision` 为 `"block"` 时显示给 Claude 的解释 |
2181| `additionalContext` | 与工具结果一起添加到 Claude 上下文的字符串。有关详细信息，请参阅 [为 Claude 添加上下文](#add-context-for-claude) |2181| `additionalContext` | 与工具结果一起添加到 Claude 上下文的字符串。有关详细信息，请参阅 [为 Claude 添加上下文](#add-context-for-claude) |
2277```2277```
2278 2278
2279| 字段 | 描述 |2279| 字段 | 描述 |
2280| :------------- | :------------------------------------------------------------------------ |2280| :- | :- |
2281| `error` | 描述出错的字符串。格式取决于失败的工具 |2281| `error` | 描述出错的字符串。格式取决于失败的工具 |
2282| `is_interrupt` | 可选布尔值。当失败作为中止而不是工具报告的错误到达 Claude Code 时为 True。取消运行的工具不触发此 hook；工具结果携带中断消息 |2282| `is_interrupt` | 可选布尔值。当失败作为中止而不是工具报告的错误到达 Claude Code 时为 True。取消运行的工具不触发此 hook；工具结果携带中断消息 |
2283| `duration_ms` | 可选。工具执行时间（毫秒）。不包括权限提示和 PreToolUse hooks 中花费的时间 |2283| `duration_ms` | 可选。工具执行时间（毫秒）。不包括权限提示和 PreToolUse hooks 中花费的时间 |
2295`PostToolUseFailure` hooks 可以在工具失败后向 Claude 提供上下文。除了所有 hooks 可用的 [JSON 输出字段](#json-output) 外，您的 hook 脚本可以返回这些事件特定的字段：2295`PostToolUseFailure` hooks 可以在工具失败后向 Claude 提供上下文。除了所有 hooks 可用的 [JSON 输出字段](#json-output) 外，您的 hook 脚本可以返回这些事件特定的字段：
2296 2296
2297| 字段 | 描述 |2297| 字段 | 描述 |
2298| :------------------ | :--------------------------------------------------------------------------- |2298| :- | :- |
2299| `additionalContext` | 与错误一起添加到 Claude 上下文的字符串。有关详细信息，请参阅 [为 Claude 添加上下文](#add-context-for-claude) |2299| `additionalContext` | 与错误一起添加到 Claude 上下文的字符串。有关详细信息，请参阅 [为 Claude 添加上下文](#add-context-for-claude) |
2300 2300
2301```json theme={null}2301```json theme={null}
2356`PostToolBatch` hooks 可以为 Claude 注入上下文。除了所有 hooks 可用的 [JSON 输出字段](#json-output) 外，您的 hook 脚本可以返回这些事件特定的字段：2356`PostToolBatch` hooks 可以为 Claude 注入上下文。除了所有 hooks 可用的 [JSON 输出字段](#json-output) 外，您的 hook 脚本可以返回这些事件特定的字段：
2357 2357
2358| 字段 | 描述 |2358| 字段 | 描述 |
2359| :------------------ | :-------------------------------------------------------------------------------------------------- |2359| :- | :- |
2360| `additionalContext` | 在下一个模型调用之前注入一次的上下文字符串。有关传递详细信息、放入其中的内容以及恢复的会话如何处理过去的值，请参阅 [为 Claude 添加上下文](#add-context-for-claude) |2360| `additionalContext` | 在下一个模型调用之前注入一次的上下文字符串。有关传递详细信息、放入其中的内容以及恢复的会话如何处理过去的值，请参阅 [为 Claude 添加上下文](#add-context-for-claude) |
2361 2361
2362```json theme={null}2362```json theme={null}
2402```2402```
2403 2403
2404| 字段 | 描述 |2404| 字段 | 描述 |
2405| :------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |2405| :- | :- |
2406| `reason` | 拒绝原因。对于分类器判决，在大多数会话中它命名方括号中的匹配规则，例如 `[Data Exfiltration]`；有关其他形式，请参阅 [审查拒绝](/docs/zh-CN/auto-mode-config#review-denials)。对于 [无判决拒绝](#permissiondenied-decision-control)，它以 `Auto mode could not evaluate this action and is blocking it for safety` 开头。对于拒绝因为分类器模型不可用，它是固定文本 `Classifier unavailable` |2406| `reason` | 拒绝原因。对于分类器判决，在大多数会话中它命名方括号中的匹配规则，例如 `[Data Exfiltration]`；有关其他形式，请参阅 [审查拒绝](/docs/zh-CN/auto-mode-config#review-denials)。对于 [无判决拒绝](#permissiondenied-decision-control)，它以 `Auto mode could not evaluate this action and is blocking it for safety` 开头。对于拒绝因为分类器模型不可用，它是固定文本 `Classifier unavailable` |
2407 2407
2408<h4 id="permissiondenied-decision-control">2408<h4 id="permissiondenied-decision-control">
2433即使关闭了桌面通知，您也会接收这些 hook 事件：`preferredNotifChannel` 设置（包括 `notifications_disabled`）仅更改您如何被警告，而不是您的 hook 是否运行。2433即使关闭了桌面通知，您也会接收这些 hook 事件：`preferredNotifChannel` 设置（包括 `notifications_disabled`）仅更改您如何被警告，而不是您的 hook 是否运行。
2434 2434
2435| 匹配器 | 何时触发 |2435| 匹配器 | 何时触发 |
2436| :--------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |2436| :- | :- |
2437| `permission_prompt` | Claude 需要您批准工具使用或沙箱命令的 [网络请求](/docs/zh-CN/sandboxing#network-isolation)，提示已等待约六秒 |2437| `permission_prompt` | Claude 需要您批准工具使用或沙箱命令的 [网络请求](/docs/zh-CN/sandboxing#network-isolation)，提示已等待约六秒 |
2438| `idle_prompt` | Claude 约 60 秒前完成响应，您自那以后没有输入 |2438| `idle_prompt` | Claude 约 60 秒前完成响应，您自那以后没有输入 |
2439| `auth_success` | 身份验证完成 |2439| `auth_success` | 身份验证完成 |
2550SubagentStart hooks 无法阻止子代理创建，但它们可以向子代理注入上下文。除了所有 hooks 可用的 [JSON 输出字段](#json-output) 外，您可以返回：2550SubagentStart hooks 无法阻止子代理创建，但它们可以向子代理注入上下文。除了所有 hooks 可用的 [JSON 输出字段](#json-output) 外，您可以返回：
2551 2551
2552| 字段 | 描述 |2552| 字段 | 描述 |
2553| :------------------ | :------------------------------------------------------------------------------------ |2553| :- | :- |
2554| `additionalContext` | 在子代理对话开始时添加到子代理上下文的字符串，在其第一个提示之前。有关详细信息，请参阅 [为 Claude 添加上下文](#add-context-for-claude) |2554| `additionalContext` | 在子代理对话开始时添加到子代理上下文的字符串，在其第一个提示之前。有关详细信息，请参阅 [为 Claude 添加上下文](#add-context-for-claude) |
2555 2555
2556```json theme={null}2556```json theme={null}
2632```2632```
2633 2633
2634| 字段 | 描述 |2634| 字段 | 描述 |
2635| :----------------- | :---------------------- |2635| :- | :- |
2636| `task_id` | 正在创建的任务的标识符 |2636| `task_id` | 正在创建的任务的标识符 |
2637| `task_subject` | 任务的标题 |2637| `task_subject` | 任务的标题 |
2638| `task_description` | 任务的详细描述。可能不存在 |2638| `task_description` | 任务的详细描述。可能不存在 |
2693```2693```
2694 2694
2695| 字段 | 描述 |2695| 字段 | 描述 |
2696| :----------------- | :---------------------- |2696| :- | :- |
2697| `task_id` | 正在完成的任务的标识符 |2697| `task_id` | 正在完成的任务的标识符 |
2698| `task_subject` | 任务的标题 |2698| `task_subject` | 任务的标题 |
2699| `task_description` | 任务的详细描述。可能不存在 |2699| `task_description` | 任务的详细描述。可能不存在 |
2748`background_tasks` 中的每个条目描述一个进行中的任务，并使用这些字段：2748`background_tasks` 中的每个条目描述一个进行中的任务，并使用这些字段：
2749 2749
2750| 字段 | 描述 |2750| 字段 | 描述 |
2751| :------------ | :------------------------------------------------------------------------------------------------------------------------------------------ |2751| :- | :- |
2752| `id` | 任务标识符 |2752| `id` | 任务标识符 |
2753| `type` | 友好的任务类型标签，例如 `shell`、`subagent`、`monitor`、`workflow`、`teammate`、`cloud session` 或 `MCP task`。每个标签标识哪个 Claude Code 功能创建了任务。对于无法识别的类型回退到原始判别式 |2753| `type` | 友好的任务类型标签，例如 `shell`、`subagent`、`monitor`、`workflow`、`teammate`、`cloud session` 或 `MCP task`。每个标签标识哪个 Claude Code 功能创建了任务。对于无法识别的类型回退到原始判别式 |
2754| `status` | 当前任务状态 |2754| `status` | 当前任务状态 |
2762`session_crons` 中的每个条目描述一个会话范围的计划唤醒，来自 `CronCreate`、`ScheduleWakeup` 和 `/loop`：2762`session_crons` 中的每个条目描述一个会话范围的计划唤醒，来自 `CronCreate`、`ScheduleWakeup` 和 `/loop`：
2763 2763
2764| 字段 | 描述 |2764| 字段 | 描述 |
2765| :---------- | :---------------------------------------------------- |2765| :- | :- |
2766| `id` | Cron 任务标识符 |2766| `id` | Cron 任务标识符 |
2767| `schedule` | Cron 表达式，例如 `0 9 * * 1-5` |2767| `schedule` | Cron 表达式，例如 `0 9 * * 1-5` |
2768| `recurring` | 对于一次性唤醒（其计划编码单个触发时间）为 `false`，对于在每个匹配上重新触发的任务为 `true` |2768| `recurring` | 对于一次性唤醒（其计划编码单个触发时间）为 `false`，对于在每个匹配上重新触发的任务为 `true` |
2806`Stop` 和 `SubagentStop` hooks 可以控制 Claude 是否继续。除了所有 hooks 可用的 [JSON 输出字段](#json-output) 外，您的 hook 脚本可以返回这些事件特定的字段：2806`Stop` 和 `SubagentStop` hooks 可以控制 Claude 是否继续。除了所有 hooks 可用的 [JSON 输出字段](#json-output) 外，您的 hook 脚本可以返回这些事件特定的字段：
2807 2807
2808| 字段 | 描述 |2808| 字段 | 描述 |
2809| :------------------------------------- | :--------------------------------------------------------------------------------------------- |2809| :- | :- |
2810| `decision` | `"block"` 防止 Claude 停止。省略以允许 Claude 停止 |2810| `decision` | `"block"` 防止 Claude 停止。省略以允许 Claude 停止 |
2811| `reason` | 当 `decision` 为 `"block"` 时需要。告诉 Claude 为什么它应该继续 |2811| `reason` | 当 `decision` 为 `"block"` 时需要。告诉 Claude 为什么它应该继续 |
2812| `hookSpecificOutput.additionalContext` | 对 Claude 的非错误反馈。对话继续，以便 Claude 可以对其采取行动，但与 `decision: "block"` 不同，它在成绩单中显示为 hook 反馈而不是 hook 错误 |2812| `hookSpecificOutput.additionalContext` | 对 Claude 的非错误反馈。对话继续，以便 Claude 可以对其采取行动，但与 `decision: "block"` 不同，它在成绩单中显示为 hook 反馈而不是 hook 错误 |
2844除了 [常见输入字段](#common-input-fields) 外，StopFailure hooks 接收 `error`、可选的 `error_details` 和可选的 `last_assistant_message`。`error` 字段标识错误类型，用于匹配器过滤。2844除了 [常见输入字段](#common-input-fields) 外，StopFailure hooks 接收 `error`、可选的 `error_details` 和可选的 `last_assistant_message`。`error` 字段标识错误类型，用于匹配器过滤。
2845 2845
2846| 字段 | 描述 |2846| 字段 | 描述 |
2847| :----------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |2847| :- | :- |
2848| `error` | 错误类型：`rate_limit`、`overloaded`、`authentication_failed`、`oauth_org_not_allowed`、`account_on_hold`、`billing_error`、`invalid_request`、`model_not_found`、`server_error`、`max_output_tokens`、`cloud_credential_error` 或 `unknown` |2848| `error` | 错误类型：`rate_limit`、`overloaded`、`authentication_failed`、`oauth_org_not_allowed`、`account_on_hold`、`billing_error`、`invalid_request`、`model_not_found`、`server_error`、`max_output_tokens`、`cloud_credential_error` 或 `unknown` |
2849| `error_details` | 关于错误的其他详细信息（如果可用） |2849| `error_details` | 关于错误的其他详细信息（如果可用） |
2850| `last_assistant_message` | 在对话中显示的呈现错误文本。与 `Stop` 和 `SubagentStop` 不同，其中此字段保持 Claude 的对话输出，对于 `StopFailure` 它包含 API 错误字符串本身，例如 `"API Error: Rate limit reached"` |2850| `last_assistant_message` | 在对话中显示的呈现错误文本。与 `Stop` 和 `SubagentStop` 不同，其中此字段保持 Claude 的对话输出，对于 `StopFailure` 它包含 API 错误字符串本身，例如 `"API Error: Rate limit reached"` |
2890```2890```
2891 2891
2892| 字段 | 描述 |2892| 字段 | 描述 |
2893| :-------------- | :---------------------- |2893| :- | :- |
2894| `teammate_name` | 即将空闲的队友的名称 |2894| `teammate_name` | 即将空闲的队友的名称 |
2895| `team_name` | 已弃用。会话派生的团队名称；将在未来版本中删除 |2895| `team_name` | 已弃用。会话派生的团队名称；将在未来版本中删除 |
2896 2896
2927匹配器过滤配置源：2927匹配器过滤配置源：
2928 2928
2929| 匹配器 | 何时触发 |2929| 匹配器 | 何时触发 |
2930| :----------------- | :----------------------------------------------------- |2930| :- | :- |
2931| `user_settings` | `~/.claude/settings.json` 更改 |2931| `user_settings` | `~/.claude/settings.json` 更改 |
2932| `project_settings` | `.claude/settings.json` 更改 |2932| `project_settings` | `.claude/settings.json` 更改 |
2933| `local_settings` | `.claude/settings.local.json` 更改 |2933| `local_settings` | `.claude/settings.local.json` 更改 |
2978ConfigChange hooks 可以阻止配置更改生效。使用退出代码 2 或 JSON `decision` 来防止更改。当被阻止时，新设置不应用于运行的会话。2978ConfigChange hooks 可以阻止配置更改生效。使用退出代码 2 或 JSON `decision` 来防止更改。当被阻止时，新设置不应用于运行的会话。
2979 2979
2980| 字段 | 描述 |2980| 字段 | 描述 |
2981| :--------- | :-------------------------- |2981| :- | :- |
2982| `decision` | `"block"` 防止配置更改被应用。省略以允许更改 |2982| `decision` | `"block"` 防止配置更改被应用。省略以允许更改 |
2983| `reason` | 接受但永远不显示 |2983| `reason` | 接受但永远不显示 |
2984 2984
3027除了所有 hooks 可用的 [JSON 输出字段](#json-output) 外，CwdChanged hooks 可以返回 `watchPaths` 来动态设置哪些文件路径 [FileChanged](#filechanged) 监视：3027除了所有 hooks 可用的 [JSON 输出字段](#json-output) 外，CwdChanged hooks 可以返回 `watchPaths` 来动态设置哪些文件路径 [FileChanged](#filechanged) 监视：
3028 3028
3029| 字段 | 描述 |3029| 字段 | 描述 |
3030| :----------- | :------------------------------------------------------------------- |3030| :- | :- |
3031| `watchPaths` | 绝对路径的数组。替换当前动态监视列表。来自您 `matcher` 配置的路径始终被监视。返回空数组清除动态列表，这在进入新目录时是典型的 |3031| `watchPaths` | 绝对路径的数组。替换当前动态监视列表。来自您 `matcher` 配置的路径始终被监视。返回空数组清除动态列表，这在进入新目录时是典型的 |
3032 3032
3033CwdChanged hooks 没有决策控制。它们无法阻止目录更改。3033CwdChanged hooks 没有决策控制。它们无法阻止目录更改。
3053匹配器过滤目录的添加方式：3053匹配器过滤目录的添加方式：
3054 3054
3055| 匹配器 | 何时触发 |3055| 匹配器 | 何时触发 |
3056| :------------------- | :-------------------------------------- |3056| :- | :- |
3057| `slash_command` | 您使用 `/add-dir` 添加目录 |3057| `slash_command` | 您使用 `/add-dir` 添加目录 |
3058| `register_repo_root` | SDK 客户端使用 `register_repo_root` 控制请求添加目录 |3058| `register_repo_root` | SDK 客户端使用 `register_repo_root` 控制请求添加目录 |
3059 3059
3064除了 [常见输入字段](#common-input-fields) 外，DirectoryAdded hooks 接收 `directory` 和 `source`。3064除了 [常见输入字段](#common-input-fields) 外，DirectoryAdded hooks 接收 `directory` 和 `source`。
3065 3065
3066| 字段 | 描述 |3066| 字段 | 描述 |
3067| :---------- | :------------------------------------------------------------------------ |3067| :- | :- |
3068| `directory` | 添加的目录的绝对路径 |3068| `directory` | 添加的目录的绝对路径 |
3069| `source` | 目录如何被添加，`/add-dir` 为 `"slash_command"` 或 SDK 控制请求为 `"register_repo_root"` |3069| `source` | 目录如何被添加，`/add-dir` 为 `"slash_command"` 或 SDK 控制请求为 `"register_repo_root"` |
3070 3070
3138除了 [常见输入字段](#common-input-fields) 外，FileChanged hooks 接收 `file_path` 和 `event`。3138除了 [常见输入字段](#common-input-fields) 外，FileChanged hooks 接收 `file_path` 和 `event`。
3139 3139
3140| 字段 | 描述 |3140| 字段 | 描述 |
3141| :---------- | :------------------------------------------------------- |3141| :- | :- |
3142| `file_path` | 更改的文件的绝对路径 |3142| `file_path` | 更改的文件的绝对路径 |
3143| `event` | 发生了什么：修改文件为 `"change"`、创建的文件为 `"add"` 或删除的文件为 `"unlink"` |3143| `event` | 发生了什么：修改文件为 `"change"`、创建的文件为 `"add"` 或删除的文件为 `"unlink"` |
3144 3144
3160除了所有 hooks 可用的 [JSON 输出字段](#json-output) 外，FileChanged hooks 可以返回 `watchPaths` 来动态更新哪些文件路径被监视：3160除了所有 hooks 可用的 [JSON 输出字段](#json-output) 外，FileChanged hooks 可以返回 `watchPaths` 来动态更新哪些文件路径被监视：
3161 3161
3162| 字段 | 描述 |3162| 字段 | 描述 |
3163| :----------- | :--------------------------------------------------------------------------- |3163| :- | :- |
3164| `watchPaths` | 绝对路径的数组。替换当前动态监视列表。来自您 `matcher` 配置的路径始终被监视。当您的 hook 脚本根据更改的文件发现要监视的其他文件时使用此 |3164| `watchPaths` | 绝对路径的数组。替换当前动态监视列表。来自您 `matcher` 配置的路径始终被监视。当您的 hook 脚本根据更改的文件发现要监视的其他文件时使用此 |
3165 3165
3166FileChanged hooks 没有决策控制。它们无法阻止文件更改发生。3166FileChanged hooks 没有决策控制。它们无法阻止文件更改发生。
3294匹配器值指示压缩是手动还是自动触发：3294匹配器值指示压缩是手动还是自动触发：
3295 3295
3296| 匹配器 | 何时触发 |3296| 匹配器 | 何时触发 |
3297| :------- | :-------------------------------------------------------------------- |3297| :- | :- |
3298| `manual` | `/compact` |3298| `manual` | `/compact` |
3299| `auto` | 当对话达到 [自动压缩窗口](/docs/zh-CN/model-config#set-the-auto-compact-window) 时自动压缩 |3299| `auto` | 当对话达到 [自动压缩窗口](/docs/zh-CN/model-config#set-the-auto-compact-window) 时自动压缩 |
3300 3300
3330与 `PreCompact` 相同的匹配器值适用：3330与 `PreCompact` 相同的匹配器值适用：
3331 3331
3332| 匹配器 | 何时触发 |3332| 匹配器 | 何时触发 |
3333| :------- | :--------------------------------------------------------------------- |3333| :- | :- |
3334| `manual` | 在 `/compact` 后 |3334| `manual` | 在 `/compact` 后 |
3335| `auto` | 当对话达到 [自动压缩窗口](/docs/zh-CN/model-config#set-the-auto-compact-window) 时自动压缩后 |3335| `auto` | 当对话达到 [自动压缩窗口](/docs/zh-CN/model-config#set-the-auto-compact-window) 时自动压缩后 |
3336 3336
3448除了 [常见输入字段](#common-input-fields) 外，PreModelSwitch hooks 接收此表中的字段。最后五个描述重新发送对话到新模型的成本，因此 hook 可以在切换发生之前显示该数字。3448除了 [常见输入字段](#common-input-fields) 外，PreModelSwitch hooks 接收此表中的字段。最后五个描述重新发送对话到新模型的成本，因此 hook 可以在切换发生之前显示该数字。
3449 3449
3450| 字段 | 类型 | 描述 |3450| 字段 | 类型 | 描述 |
3451| :-------------------------- | :--------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |3451| :- | :- | :- |
3452| `from_model` | string | 切换更改的模型 ID |3452| `from_model` | string | 切换更改的模型 ID |
3453| `to_model` | string | 切换更改为的模型 ID。匹配器与此模型的规范名称进行比较 |3453| `to_model` | string | 切换更改为的模型 ID。匹配器与此模型的规范名称进行比较 |
3454| `requested_model` | string or `null` | 请求命名的模型：别名（如 `opus`）、完整模型 ID 或当请求为默认模型时 `null` |3454| `requested_model` | string or `null` | 请求命名的模型：别名（如 `opus`）、完整模型 ID 或当请求为默认模型时 `null` |
3488为了更精细的控制，在 `hookSpecificOutput` 对象中返回 `permissionDecision` 和 `permissionDecisionReason`，如 [PreToolUse](#pretooluse-decision-control) 上。`PreModelSwitch` 接受 `"allow"`、`"deny"` 和 `"ask"`。它不接受 `"defer"`、`updatedInput` 或 `additionalContext`。下表描述两个字段：3488为了更精细的控制，在 `hookSpecificOutput` 对象中返回 `permissionDecision` 和 `permissionDecisionReason`，如 [PreToolUse](#pretooluse-decision-control) 上。`PreModelSwitch` 接受 `"allow"`、`"deny"` 和 `"ask"`。它不接受 `"defer"`、`updatedInput` 或 `additionalContext`。下表描述两个字段：
3489 3489
3490| 字段 | 描述 |3490| 字段 | 描述 |
3491| :------------------------- | :-------------------------------------------------------------------------------------------------------------------------- |3491| :- | :- |
3492| `permissionDecision` | `"allow"` 继续并跳过 [Claude Code 在 prompt cache 温暖时显示的确认](/docs/zh-CN/prompt-caching#switching-models)。`"deny"` 取消切换。`"ask"` 提示用户确认它 |3492| `permissionDecision` | `"allow"` 继续并跳过 [Claude Code 在 prompt cache 温暖时显示的确认](/docs/zh-CN/prompt-caching#switching-models)。`"deny"` 取消切换。`"ask"` 提示用户确认它 |
3493| `permissionDecisionReason` | 对于 `"deny"`，显示给用户作为切换被阻止的原因，或为 `set_model` 请求返回为错误。对于 `"ask"`，显示在确认提示中。对于 `"allow"` 被忽略 |3493| `permissionDecisionReason` | 对于 `"deny"`，显示给用户作为切换被阻止的原因，或为 `set_model` 请求返回为错误。对于 `"ask"`，显示在确认提示中。对于 `"allow"` 被忽略 |
3494 3494
3568Claude Code 在切换后的下一个请求中获取您的 hook 的 [纯文本 stdout](#exit-code-0) 退出 0，或 JSON 输出中的 `additionalContext`，并将其传递给 Claude。除了所有 hooks 可用的 [JSON 输出字段](#json-output) 外，您可以返回：3568Claude Code 在切换后的下一个请求中获取您的 hook 的 [纯文本 stdout](#exit-code-0) 退出 0，或 JSON 输出中的 `additionalContext`，并将其传递给 Claude。除了所有 hooks 可用的 [JSON 输出字段](#json-output) 外，您可以返回：
3569 3569
3570| 字段 | 描述 |3570| 字段 | 描述 |
3571| :------------------ | :------------------------------------------------------------------------------ |3571| :- | :- |
3572| `additionalContext` | 与下一个请求一起添加到 Claude 上下文的字符串。有关详细信息，请参阅 [为 Claude 添加上下文](#add-context-for-claude) |3572| `additionalContext` | 与下一个请求一起添加到 Claude 上下文的字符串。有关详细信息，请参阅 [为 Claude 添加上下文](#add-context-for-claude) |
3573 3573
3574如果 hook 在您发送下一个提示后五秒内未完成，Claude Code 发送该请求而不输出，并将其附加到以下请求。如果模型在下一个请求之前更改多次，Claude Code 仅传递最后一个切换目标模型的输出。3574如果 hook 在您发送下一个提示后五秒内未完成，Claude Code 发送该请求而不输出，并将其附加到以下请求。如果模型在下一个请求之前更改多次，Claude Code 仅传递最后一个切换目标模型的输出。
3582`reason` 字段在 hook 输入中指示会话为什么结束：3582`reason` 字段在 hook 输入中指示会话为什么结束：
3583 3583
3584| 原因 | 描述 |3584| 原因 | 描述 |
3585| :---------------------------- | :------------------------------------------------------- |3585| :- | :- |
3586| `clear` | 会话使用 `/clear` 命令清除 |3586| `clear` | 会话使用 `/clear` 命令清除 |
3587| `resume` | 会话通过交互式 `/resume` 切换 |3587| `resume` | 会话通过交互式 `/resume` 切换 |
3588| `logout` | 用户登出 |3588| `logout` | 用户登出 |
3689```3689```
3690 3690
3691| 字段 | 值 | 描述 |3691| 字段 | 值 | 描述 |
3692| :-------- | :-------------------------- | :----------------------------------- |3692| :- | :- | :- |
3693| `action` | `accept`、`decline`、`cancel` | 是否接受、拒绝或取消请求 |3693| `action` | `accept`、`decline`、`cancel` | 是否接受、拒绝或取消请求 |
3694| `content` | object | 要提交的表单字段值。仅在 `action` 为 `accept` 时使用 |3694| `content` | object | 要提交的表单字段值。仅在 `action` 为 `accept` 时使用 |
3695 3695
3742```3742```
3743 3743
3744| 字段 | 值 | 描述 |3744| 字段 | 值 | 描述 |
3745| :-------- | :-------------------------- | :---------------------------------- |3745| :- | :- | :- |
3746| `action` | `accept`、`decline`、`cancel` | 覆盖用户的操作 |3746| `action` | `accept`、`decline`、`cancel` | 覆盖用户的操作 |
3747| `content` | object | 覆盖表单字段值。仅在 `action` 为 `accept` 时有意义 |3747| `content` | object | 覆盖表单字段值。仅在 `action` 为 `accept` 时有意义 |
3748 3748
3832```3832```
3833 3833
3834| 字段 | 必需 | 描述 |3834| 字段 | 必需 | 描述 |
3835| :---------------- | :- | :----------------------------------------------------------------------------------------------------- |3835| :- | :- | :- |
3836| `type` | 是 | 必须是 `"prompt"` |3836| `type` | 是 | 必须是 `"prompt"` |
3837| `prompt` | 是 | 要发送给 LLM 的提示文本。使用 `$ARGUMENTS` 作为 hook 输入 JSON 的占位符。如果 `$ARGUMENTS` 不存在，输入 JSON 被追加到提示 |3837| `prompt` | 是 | 要发送给 LLM 的提示文本。使用 `$ARGUMENTS` 作为 hook 输入 JSON 的占位符。如果 `$ARGUMENTS` 不存在，输入 JSON 被追加到提示 |
3838| `model` | 否 | 用于评估的模型。默认为快速模型 |3838| `model` | 否 | 用于评估的模型。默认为快速模型 |
3854```3854```
3855 3855
3856| 字段 | 描述 |3856| 字段 | 描述 |
3857| :----------- | :-------------------------------------------------------------------------------------------------------------- |3857| :- | :- |
3858| `ok` | `true` 允许。对于 `false`，请参阅下面的每个事件行为 |3858| `ok` | `true` 允许。对于 `false`，请参阅下面的每个事件行为 |
3859| `reason` | 当 `ok` 为 `false` 时必需 |3859| `reason` | 当 `ok` 为 `false` 时必需 |
3860| `impossible` | 可选。当模型判断条件永远无法满足时，模型使用 `ok: false` 返回它。在 `Stop` 和 `SubagentStop` 上，Claude Code 随后让转轮结束而不是反馈原因。代理 hooks 和其他事件忽略它 |3860| `impossible` | 可选。当模型判断条件永远无法满足时，模型使用 `ok: false` 返回它。在 `Stop` 和 `SubagentStop` 上，Claude Code 随后让转轮结束而不是反馈原因。代理 hooks 和其他事件忽略它 |
