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` | 單一專案 | 否，gitignored（當 Claude Code 將設定儲存到其中時） |265| `.claude/settings.local.json` | 單一專案 | 否，gitignored（當 Claude Code 將設定儲存到其中時） |
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-if-matching) 以了解 Bash 模式如何針對子命令、`$()` 和反引號進行評估。僅在工具事件上評估：`PreToolUse`、`PostToolUse`、`PostToolUseFailure`、`PermissionRequest` 和 `PermissionDenied`。在其他事件上，設定 `if` 的 hook 永遠不會執行。使用與 [權限規則](/docs/zh-TW/permissions) 相同的語法 |443| `if` | 否 | 權限規則語法以篩選此 hook 何時執行，例如 `"Bash(git *)"` 或 `"Edit(*.ts)"`。Hook 命令僅在工具呼叫匹配模式時執行。請參閱下面的 [Bash 匹配表](#bash-if-matching) 以了解 Bash 模式如何針對子命令、`$()` 和反引號進行評估。僅在工具事件上評估：`PreToolUse`、`PostToolUse`、`PostToolUseFailure`、`PermissionRequest` 和 `PermissionDenied`。在其他事件上，設定 `if` 的 hook 永遠不會執行。使用與 [權限規則](/docs/zh-TW/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 伺服器的名稱。對於 [plugin-bundled server](/docs/zh-TW/mcp#plugin-provided-mcp-servers)，這是範圍名稱 `plugin:<plugin-name>:<server-name>`，例如 `plugin:my-plugin:db`，而不是裸伺服器金鑰。伺服器必須已連接；hook 永遠不會觸發 OAuth 或連接流程 |574| `server` | 是 | 已配置的 MCP 伺服器的名稱。對於 [plugin-bundled server](/docs/zh-TW/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) 部分中記錄的事件特定欄位。對於命令 hooks，此 JSON 通過 stdin 到達。對於 HTTP hooks，它作為 POST 請求正文到達。786Hook 事件接收這些欄位作為 JSON，除了每個 [hook 事件](#hook-events) 部分中記錄的事件特定欄位。對於命令 hooks，此 JSON 通過 stdin 到達。對於 HTTP hooks，它作為 POST 請求正文到達。
787 787
788| 欄位 | 描述 |788| 欄位 | 描述 |
789| :---------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |789| :- | :- |
790| `session_id` | 目前工作階段識別碼 |790| `session_id` | 目前工作階段識別碼 |
791| `prompt_id` | UUID 識別目前正在處理的使用者提示。與 [OpenTelemetry 事件上的 `prompt.id` 屬性](/docs/zh-TW/monitoring-usage#event-correlation-attributes) 相符，因此您可以將 hook 輸出與單一提示的遙測相關聯。在第一個使用者輸入之前不存在。需要 Claude Code v2.1.196 或更新版本 |791| `prompt_id` | UUID 識別目前正在處理的使用者提示。與 [OpenTelemetry 事件上的 `prompt.id` 屬性](/docs/zh-TW/monitoring-usage#event-correlation-attributes) 相符，因此您可以將 hook 輸出與單一提示的遙測相關聯。在第一個使用者輸入之前不存在。需要 Claude Code v2.1.196 或更新版本 |
792| `transcript_path` | 對話 JSON 的路徑。成績單檔案以非同步方式寫入，可能滯後於記憶體中的對話，因此當 hook 觸發時，它可能尚未包含目前回合的最新訊息。需要目前回合最後助手文字的 Hooks 應在 [Stop](#stop) 和 [SubagentStop](#subagentstop) 上使用 `last_assistant_message`，而不是讀取成績單 |792| `transcript_path` | 對話 JSON 的路徑。成績單檔案以非同步方式寫入，可能滯後於記憶體中的對話，因此當 hook 觸發時，它可能尚未包含目前回合的最新訊息。需要目前回合最後助手文字的 Hooks 應在 [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` | 代理名稱（例如 `"Explore"` 或 `"security-reviewer"`）。當工作階段使用 `--agent` 或 hook 在 subagent 內觸發時出現。對於 subagents，subagent 的類型優先於工作階段的 `--agent` 值。請參閱 [SubagentStart](#subagentstart) 以了解自訂和 plugin subagents 報告的值，以及如何針對 plugin 範圍名稱編寫匹配器。 |804| `agent_type` | 代理名稱（例如 `"Explore"` 或 `"security-reviewer"`）。當工作階段使用 `--agent` 或 hook 在 subagent 內觸發時出現。對於 subagents，subagent 的類型優先於工作階段的 `--agent` 值。請參閱 [SubagentStart](#subagentstart) 以了解自訂和 plugin subagents 報告的值，以及如何針對 plugin 範圍名稱編寫匹配器。 |
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` | 代理名稱，當您使用 `claude --agent <name>` 啟動 Claude Code 時出現 |1222| `agent_type` | 代理名稱，當您使用 `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-TW/prompt-caching#cache-lifetime) 或更新的壓縮替換了快取的對話時為 `true` |1231| `prompt_cache_likely_expired` | 當最後一個回應早於工作階段的 [prompt cache 生命週期](/docs/zh-TW/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-TW/headless)，搭配 `-p` 旗標，即使未提供提示，它也會成為第一個回合。如果提供了提示，它會作為下一個回合跟隨。與 `additionalContext` 不同（它附加到現有回合），這會建立回合 |1260| `initialUserMessage` | 用作工作階段第一個使用者訊息的字串。適用於 [非互動模式](/docs/zh-TW/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若要阻止提示，傳回一個 JSON 物件，其 `decision` 設定為 `"block"`：1463若要阻止提示，傳回一個 JSON 物件，其 `decision` 設定為 `"block"`：
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，因此無法與文字記錄訊息 ids 相關聯 |1572| `message_id` | 正在顯示的助手訊息的 UUID。在同一訊息的每個批次中穩定。這不是 API `msg_…` id，因此無法與文字記錄訊息 ids 相關聯 |
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-TW/tools-reference#bash-tool-behavior) 的值會減少到最大值，而不是被拒絕 |1742| `timeout` | number | `120000` | 可選逾時（毫秒）。高於 [最大值](/docs/zh-TW/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-TW/sub-agents)。1876生成 [子代理](/docs/zh-TW/sub-agents)。
1877 1877
1878| 欄位 | 類型 | 範例 | 描述 |1878| 欄位 | 類型 | 範例 | 描述 |
1879| :-------------- | :----- | :------------------------- | :----------- |1879| :- | :- | :- | :- |
1880| `prompt` | string | `"Find all API endpoints"` | 代理要執行的任務 |1880| `prompt` | string | `"Find all API endpoints"` | 代理要執行的任務 |
1881| `description` | string | `"Find API endpoints"` | 任務的簡短描述 |1881| `description` | string | `"Find API endpoints"` | 任務的簡短描述 |
1882| `subagent_type` | string | `"Explore"` | 要使用的專門代理類型 |1882| `subagent_type` | string | `"Explore"` | 要使用的專門代理類型 |
1885當前景 Agent 呼叫完成時，您的 [PostToolUse hook](#posttooluse) 在 `tool_response` 中接收子代理的結果和執行遙測。讀取這些欄位以檢查執行；對於跨子代理的權杖和成本匯總，使用 [權杖和成本計數器](/docs/zh-TW/monitoring-usage#token-counter)，篩選為 `query_source` `"subagent"`，因為 `totalTokens` 和 `usage` 僅涵蓋最終請求：1885當前景 Agent 呼叫完成時，您的 [PostToolUse hook](#posttooluse) 在 `tool_response` 中接收子代理的結果和執行遙測。讀取這些欄位以檢查執行；對於跨子代理的權杖和成本匯總，使用 [權杖和成本計數器](/docs/zh-TW/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-TW/permission-modes#analyze-before-you-edit-with-plan-mode) 之前核准它。Claude 在呼叫工具之前將計畫寫入磁碟上的檔案，因此來自模型的字面 `tool_input` 通常是空的。Claude Code 在將輸入傳遞給 hooks 之前注入計畫內容和檔案路徑。1922呈現計畫並要求使用者在 Claude 離開 [plan mode](/docs/zh-TW/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-TW/permission-modes#actions-no-mode-auto-approves) 和 `AskUserQuestion` 和 `ExitPlanMode`，需要 [`updatedInput` 與其配對](#allow-with-updatedinput)。`"deny"` 防止工具呼叫。`"ask"` 提示使用者確認。`"defer"` 優雅地退出，以便稍後可以恢復工具。[拒絕和詢問規則](/docs/zh-TW/permissions#manage-permissions) 無論 hook 傳回什麼都會被評估 |1940| `permissionDecision` | `"allow"` 跳過權限提示，除了 [任何模式自動核准的動作](/docs/zh-TW/permission-modes#actions-no-mode-auto-approves) 和 `AskUserQuestion` 和 `ExitPlanMode`，需要 [`updatedInput` 與其配對](#allow-with-updatedinput)。`"deny"` 防止工具呼叫。`"ask"` 提示使用者確認。`"defer"` 優雅地退出，以便稍後可以恢復工具。[拒絕和詢問規則](/docs/zh-TW/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 傳回的輸入評估權限規則和 Bash 命令的 [自動背景資格](/docs/zh-TW/tools-reference#background-commands)，而不是 Claude 傳送的輸入。與 `"allow"` 結合以自動核准，或與 `"ask"` 結合以向使用者顯示修改的輸入。對於 `"defer"`，忽略 |1942| `updatedInput` | 在執行前修改工具的輸入參數。替換整個輸入物件，因此在修改的欄位旁邊包含未變更的欄位。Claude Code 根據您的 hook 傳回的輸入評估權限規則和 Bash 命令的 [自動背景資格](/docs/zh-TW/tools-reference#background-commands)，而不是 Claude 傳送的輸入。與 `"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-TW/permissions#manage-permissions) 仍會被評估，因此傳回 `"allow"` 的 hook 不會覆寫匹配的拒絕規則 |2073| `behavior` | `"allow"` 授予權限，`"deny"` 拒絕它。[拒絕和詢問規則](/docs/zh-TW/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` | 將 `destination` 處給定 `behavior` 的所有規則替換為提供的 `rules` |2104| `replaceRules` | `rules`、`behavior`、`destination` | 將 `destination` 處給定 `behavior` 的所有規則替換為提供的 `rules` |
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-TW/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-TW/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-TW/sandboxing#network-isolation)，提示已等待約六秒 |2437| `permission_prompt` | Claude 需要您核准工具使用或沙箱命令的 [網路請求](/docs/zh-TW/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 沒有決策控制。它們無法阻止檔案變更發生。
3296匹配器值指示壓縮是手動還是自動觸發：3296匹配器值指示壓縮是手動還是自動觸發：
3297 3297
3298| 匹配器 | 何時觸發 |3298| 匹配器 | 何時觸發 |
3299| :------- | :-------------------------------------------------------------------- |3299| :- | :- |
3300| `manual` | `/compact` |3300| `manual` | `/compact` |
3301| `auto` | 當對話到達 [自動壓縮視窗](/docs/zh-TW/model-config#set-the-auto-compact-window) 時自動壓縮 |3301| `auto` | 當對話到達 [自動壓縮視窗](/docs/zh-TW/model-config#set-the-auto-compact-window) 時自動壓縮 |
3302 3302
3332與 `PreCompact` 相同的匹配器值適用：3332與 `PreCompact` 相同的匹配器值適用：
3333 3333
3334| 匹配器 | 何時觸發 |3334| 匹配器 | 何時觸發 |
3335| :------- | :--------------------------------------------------------------------- |3335| :- | :- |
3336| `manual` | 在 `/compact` 後 |3336| `manual` | 在 `/compact` 後 |
3337| `auto` | 當對話到達 [自動壓縮視窗](/docs/zh-TW/model-config#set-the-auto-compact-window) 時自動壓縮後 |3337| `auto` | 當對話到達 [自動壓縮視窗](/docs/zh-TW/model-config#set-the-auto-compact-window) 時自動壓縮後 |
3338 3338
3450除了 [常見輸入欄位](#common-input-fields) 外，PreModelSwitch hooks 接收此表中的欄位。最後五個描述重新傳送對話到新模型的成本，因此 hook 可以在切換發生前顯示該數字。3450除了 [常見輸入欄位](#common-input-fields) 外，PreModelSwitch hooks 接收此表中的欄位。最後五個描述重新傳送對話到新模型的成本，因此 hook 可以在切換發生前顯示該數字。
3451 3451
3452| 欄位 | 類型 | 描述 |3452| 欄位 | 類型 | 描述 |
3453| :-------------------------- | :--------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |3453| :- | :- | :- |
3454| `from_model` | string | 切換變更的模型 ID |3454| `from_model` | string | 切換變更的模型 ID |
3455| `to_model` | string | 切換變更為的模型 ID。匹配器根據此模型的規範名稱比較 |3455| `to_model` | string | 切換變更為的模型 ID。匹配器根據此模型的規範名稱比較 |
3456| `requested_model` | string or `null` | 請求命名的模型：別名（如 `opus`）、完整模型 ID，或當請求為預設模型時 `null` |3456| `requested_model` | string or `null` | 請求命名的模型：別名（如 `opus`）、完整模型 ID，或當請求為預設模型時 `null` |
3490為了更精細的控制，在 `hookSpecificOutput` 物件中傳回 `permissionDecision` 和 `permissionDecisionReason`，如 [PreToolUse](#pretooluse-decision-control)。`PreModelSwitch` 接受 `"allow"`、`"deny"` 和 `"ask"`。它不接受 `"defer"`、`updatedInput` 或 `additionalContext`。下表描述兩個欄位：3490為了更精細的控制，在 `hookSpecificOutput` 物件中傳回 `permissionDecision` 和 `permissionDecisionReason`，如 [PreToolUse](#pretooluse-decision-control)。`PreModelSwitch` 接受 `"allow"`、`"deny"` 和 `"ask"`。它不接受 `"defer"`、`updatedInput` 或 `additionalContext`。下表描述兩個欄位：
3491 3491
3492| 欄位 | 描述 |3492| 欄位 | 描述 |
3493| :------------------------- | :--------------------------------------------------------------------------------------------------------------------------- |3493| :- | :- |
3494| `permissionDecision` | `"allow"` 進行並跳過 [Claude Code 在 prompt cache 溫暖時顯示的確認](/docs/zh-TW/prompt-caching#switching-models)。`"deny"` 取消切換。`"ask"` 提示使用者確認它 |3494| `permissionDecision` | `"allow"` 進行並跳過 [Claude Code 在 prompt cache 溫暖時顯示的確認](/docs/zh-TW/prompt-caching#switching-models)。`"deny"` 取消切換。`"ask"` 提示使用者確認它 |
3495| `permissionDecisionReason` | 對於 `"deny"`，顯示給使用者作為切換被阻止的原因，或作為 `set_model` 請求的錯誤傳回。對於 `"ask"`，在確認提示中顯示。對於 `"allow"` 忽略 |3495| `permissionDecisionReason` | 對於 `"deny"`，顯示給使用者作為切換被阻止的原因，或作為 `set_model` 請求的錯誤傳回。對於 `"ask"`，在確認提示中顯示。對於 `"allow"` 忽略 |
3496 3496
3570Claude Code 採用您的 hook 的 [純文字 stdout](#exit-code-0) 在退出 0 上，或來自 JSON 輸出的 `additionalContext`，並在切換後的下一個請求中將其傳遞給 Claude。除了 [所有 hooks 可用的 JSON 輸出欄位](#json-output) 外，您可以傳回：3570Claude Code 採用您的 hook 的 [純文字 stdout](#exit-code-0) 在退出 0 上，或來自 JSON 輸出的 `additionalContext`，並在切換後的下一個請求中將其傳遞給 Claude。除了 [所有 hooks 可用的 JSON 輸出欄位](#json-output) 外，您可以傳回：
3571 3571
3572| 欄位 | 描述 |3572| 欄位 | 描述 |
3573| :------------------ | :------------------------------------------------------------------------ |3573| :- | :- |
3574| `additionalContext` | 與下一個請求一起新增到 Claude 背景資訊的字串。請參閱 [為 Claude 新增背景資訊](#add-context-for-claude) |3574| `additionalContext` | 與下一個請求一起新增到 Claude 背景資訊的字串。請參閱 [為 Claude 新增背景資訊](#add-context-for-claude) |
3575 3575
3576如果 hook 在您傳送下一個提示後五秒內未完成，Claude Code 傳送該請求而不輸出，並將其附加到下一個請求。如果模型在下一個請求之前變更多次，Claude Code 僅傳遞最後一個切換目標模型的輸出。3576如果 hook 在您傳送下一個提示後五秒內未完成，Claude Code 傳送該請求而不輸出，並將其附加到下一個請求。如果模型在下一個請求之前變更多次，Claude Code 僅傳遞最後一個切換目標模型的輸出。
3584`reason` 欄位在 hook 輸入中指示工作階段為什麼結束：3584`reason` 欄位在 hook 輸入中指示工作階段為什麼結束：
3585 3585
3586| 原因 | 描述 |3586| 原因 | 描述 |
3587| :---------------------------- | :------------------------------------------------------- |3587| :- | :- |
3588| `clear` | 使用 `/clear` 命令清除工作階段 |3588| `clear` | 使用 `/clear` 命令清除工作階段 |
3589| `resume` | 透過互動式 `/resume` 切換工作階段 |3589| `resume` | 透過互動式 `/resume` 切換工作階段 |
3590| `logout` | 使用者登出 |3590| `logout` | 使用者登出 |
3691```3691```
3692 3692
3693| 欄位 | 值 | 描述 |3693| 欄位 | 值 | 描述 |
3694| :-------- | :-------------------------- | :----------------------------------- |3694| :- | :- | :- |
3695| `action` | `accept`、`decline`、`cancel` | 是否接受、拒絕或取消請求 |3695| `action` | `accept`、`decline`、`cancel` | 是否接受、拒絕或取消請求 |
3696| `content` | object | 要提交的表單欄位值。僅在 `action` 為 `accept` 時使用 |3696| `content` | object | 要提交的表單欄位值。僅在 `action` 為 `accept` 時使用 |
3697 3697
3744```3744```
3745 3745
3746| 欄位 | 值 | 描述 |3746| 欄位 | 值 | 描述 |
3747| :-------- | :-------------------------- | :---------------------------------- |3747| :- | :- | :- |
3748| `action` | `accept`、`decline`、`cancel` | 覆寫使用者的動作 |3748| `action` | `accept`、`decline`、`cancel` | 覆寫使用者的動作 |
3749| `content` | object | 覆寫表單欄位值。僅在 `action` 為 `accept` 時有意義 |3749| `content` | object | 覆寫表單欄位值。僅在 `action` 為 `accept` 時有意義 |
3750 3750
3834```3834```
3835 3835
3836| 欄位 | 必需 | 描述 |3836| 欄位 | 必需 | 描述 |
3837| :---------------- | :- | :----------------------------------------------------------------------------------------------------- |3837| :- | :- | :- |
3838| `type` | 是 | 必須為 `"prompt"` |3838| `type` | 是 | 必須為 `"prompt"` |
3839| `prompt` | 是 | 要發送到 LLM 的提示文字。使用 `$ARGUMENTS` 作為 hook 輸入 JSON 的佔位符。如果 `$ARGUMENTS` 不存在，輸入 JSON 會附加到提示 |3839| `prompt` | 是 | 要發送到 LLM 的提示文字。使用 `$ARGUMENTS` 作為 hook 輸入 JSON 的佔位符。如果 `$ARGUMENTS` 不存在，輸入 JSON 會附加到提示 |
3840| `model` | 否 | 用於評估的模型。預設為快速模型 |3840| `model` | 否 | 用於評估的模型。預設為快速模型 |
3856```3856```
3857 3857
3858| 欄位 | 描述 |3858| 欄位 | 描述 |
3859| :----------- | :-------------------------------------------------------------------------------------------------------------- |3859| :- | :- |
3860| `ok` | `true` 允許操作。`false` 時，請參閱下面的每個事件行為 |3860| `ok` | `true` 允許操作。`false` 時，請參閱下面的每個事件行為 |
3861| `reason` | 當 `ok` 為 `false` 時必需 |3861| `reason` | 當 `ok` 為 `false` 時必需 |
3862| `impossible` | 選用。當模型判斷條件永遠無法滿足時，模型會以 `ok: false` 返回它。在 `Stop` 和 `SubagentStop` 上，Claude Code 會讓轉換結束而不是反饋原因。代理 hooks 和其他事件會忽略它 |3862| `impossible` | 選用。當模型判斷條件永遠無法滿足時，模型會以 `ok: false` 返回它。在 `Stop` 和 `SubagentStop` 上，Claude Code 會讓轉換結束而不是反饋原因。代理 hooks 和其他事件會忽略它 |
