70 70
71> [tab] macOS/Linux71> [tab] macOS/Linux
72>72>
73> `matcher` 縮小到 Bash 工具呼叫，`if` 條件進一步縮小到符合 `rm *` 的 Bash 子命令，因此 `block-rm.sh` 僅在兩個篩選器都符合時才生成：73> `matcher` 縮小到 Bash 工具呼叫和 [Monitor 命令](#match-monitor-commands)，`if` 條件進一步縮小到符合 `rm *` 的 Bash 子命令，因此 `block-rm.sh` 僅在兩個篩選器都符合時才生成：
74>74>
75> ```json theme={null}75> ```json theme={null}
76> {76> {
116 116
117> [tab] Windows (PowerShell)117> [tab] Windows (PowerShell)
118>118>
119> 匹配器 `Bash|PowerShell` 涵蓋 [PowerShell 工具](#powershell)以及 Bash。單一 `if` 規則只符合一個工具的呼叫，因此每個工具都有自己的處理程式：第一個縮小到符合 `rm *` 的 Bash 子命令，第二個縮小到符合 `Remove-Item *` 的 PowerShell 命令。兩者都透過 `powershell.exe` 執行相同的指令碼：119> Matcher `Bash|PowerShell` 涵蓋 [PowerShell 工具](#powershell)以及 Bash。單一 `if` 規則只指定一個工具，因此每個工具都有自己的處理程式：第一個縮小到符合 `rm *` 的 Bash 子命令，第二個縮小到符合 `Remove-Item *` 的 PowerShell 命令。兩者都透過 `powershell.exe` 執行相同的指令碼：
120>120>
121> ```json theme={null}121> ```json theme={null}
122> {122> {
225Hook 定義在 JSON 設定檔中。設定有三層巢狀結構：225Hook 定義在 JSON 設定檔中。設定有三層巢狀結構：
226 226
2271. 選擇要回應的 [hook 事件](#hook-events)，例如 `PreToolUse` 或 `Stop`2271. 選擇要回應的 [hook 事件](#hook-events)，例如 `PreToolUse` 或 `Stop`
2282. 新增 [matcher 群組](#matcher-patterns)來篩選觸發時機，例如「僅限 Bash 工具」2282. 新增一個 [matcher 群組](#matcher-patterns)來篩選其觸發時機，例如「針對 Bash 工具」
2293. 定義一個或多個在符合時執行的 [hook 處理常式](#hook-handler-fields)2293. 定義一個或多個在符合時執行的 [hook 處理常式](#hook-handler-fields)
230 230
231請參閱上方的 [Hook 如何解析](#how-a-hook-resolves)，其中有附註解範例的完整逐步說明。231請參閱上方的 [Hook 如何解析](#how-a-hook-resolves)，其中有附註解範例的完整逐步說明。
277| Matcher 值 | 評估方式 | 範例 |277| Matcher 值 | 評估方式 | 範例 |
278| :- | :- | :- |278| :- | :- | :- |
279| `"*"`、`""` 或省略 | 全部符合 | 每次發生該事件時都會觸發 |279| `"*"`、`""` 或省略 | 全部符合 | 每次發生該事件時都會觸發 |
280| 僅包含字母、數字、`_`、`-`、空格、`,` 與 `\|` | 精確字串，或以 `\|` 或 `,` 分隔的精確字串清單，前後可有空白 | `Bash` 僅符合 Bash 工具；`Edit\|Write` 與 `Edit, Write` 皆精確符合這兩個工具中的任一個；`code-reviewer` 僅符合該 agent 類型 |280| 僅包含字母、數字、`_`、`-`、空格、`,` 與 `\|` | 精確字串，或以 `\|` 或 `,` 分隔的精確字串清單，前後可有空白 | `Bash` 符合 Bash 工具，且在 `PreToolUse` 與 `PermissionRequest` 上也符合 [Monitor 命令](#match-monitor-commands)；`Edit\|Write` 與 `Edit, Write` 皆精確符合這兩個工具中的任一個；`code-reviewer` 僅符合該 agent 類型 |
281| 包含任何其他字元 | JavaScript 正規表示式，未錨定 | `^Notebook` 符合名稱以 `Notebook` 開頭的任何工具；`mcp__memory__.*` 符合來自 `memory` 伺服器的所有工具 |281| 包含任何其他字元 | JavaScript 正規表示式，未錨定 | `^Notebook` 符合名稱以 `Notebook` 開頭的任何工具；`mcp__memory__.*` 符合來自 `memory` 伺服器的所有工具 |
282 282
283走正規表示式路徑的 matcher 會以 JavaScript 的 `RegExp.prototype.test` 進行測試，只要值中任何位置有符合即成功。`Edit.*` 同時符合 `Edit` 與 `NotebookEdit`；需要完整字串比對時，請以 `^` 與 `$` 包住模式，例如 `^Edit$`。283走正規表示式路徑的 matcher 會以 JavaScript 的 `RegExp.prototype.test` 進行測試，只要值中任何位置有符合即成功。`Edit.*` 同時符合 `Edit` 與 `NotebookEdit`；需要完整字串比對時，請以 `^` 與 `$` 包住模式，例如 `^Edit$`。
294| `SessionStart` | 工作階段的啟動方式 | `startup`、`resume`、`clear`、`compact`、`fork` |294| `SessionStart` | 工作階段的啟動方式 | `startup`、`resume`、`clear`、`compact`、`fork` |
295| `Setup` | 觸發 setup 的 CLI 旗標 | `init`、`maintenance` |295| `Setup` | 觸發 setup 的 CLI 旗標 | `init`、`maintenance` |
296| `SessionEnd` | 工作階段結束的原因 | `clear`、`resume`、`logout`、`prompt_input_exit`、`other` |296| `SessionEnd` | 工作階段結束的原因 | `clear`、`resume`、`logout`、`prompt_input_exit`、`other` |
297| `Notification` | 通知類型 | `permission_prompt`、`idle_prompt`、`auth_success`、`elicitation_dialog`、`elicitation_url_dialog`、`elicitation_complete`、`elicitation_response`、`agent_needs_input`、`agent_completed`、`quota_auto_resume_fired`、`quota_auto_resume_stale`、`quota_auto_resume_disabled`、`plugin_notification` |297| `Notification` | 通知類型 | `permission_prompt`、`idle_prompt`、`auth_success`、`auth_storage_failure`、`elicitation_dialog`、`elicitation_url_dialog`、`elicitation_complete`、`elicitation_response`、`agent_needs_input`、`agent_completed`、`quota_auto_resume_fired`、`quota_auto_resume_stale`、`quota_auto_resume_disabled`、`plugin_notification` |
298| `SubagentStart` | agent 類型 | `general-purpose`、`Explore`、`Plan`、自訂 agent 名稱，或外掛範圍的名稱，例如 `^my-plugin:reviewer$` |298| `SubagentStart` | agent 類型 | `general-purpose`、`Explore`、`Plan`、自訂 agent 名稱，或外掛範圍的名稱，例如 `^my-plugin:reviewer$` |
299| `PreCompact`、`PostCompact` | 觸發壓縮的原因 | `manual`、`auto` |299| `PreCompact`、`PostCompact` | 觸發壓縮的原因 | `manual`、`auto` |
300| `PreModelSwitch`、`PostModelSwitch` | 工作階段要切換到的模型之標準名稱，如 [PreModelSwitch](#premodelswitch) 中所述 | `claude-opus-5`、`claude-opus-4-6\|claude-opus-5`、`.*opus.*` |300| `PreModelSwitch`、`PostModelSwitch` | 工作階段要切換到的模型之標準名稱，如 [PreModelSwitch](#premodelswitch) 中所述 | `claude-opus-5`、`claude-opus-4-6\|claude-opus-5`、`.*opus.*` |
385}385}
386```386```
387 387
388#### 比對 Monitor 命令
389
390具有 `Bash` matcher 的 [`PreToolUse`](#pretooluse) 或 [`PermissionRequest`](#permissionrequest) hook，也會在 Claude 透過 [Monitor 工具](https://code.claude.com/docs/zh-TW/tools-reference.md#monitor-tool)啟動的 shell 命令上執行，但其 `allow` 與 [`updatedInput`](#pretooluse-decision-control) 對這些命令沒有作用。需要 Claude Code v2.1.314 或更新版本。`Bash|PowerShell`、`^Bash$` 與 `Bash.*` 等 matcher 也屬於 `Bash` matcher。具有 `Bash` matcher 的 hook 不會針對 [WebSocket 監看](https://code.claude.com/docs/zh-TW/tools-reference.md#websocket-source)執行，而具有此類 matcher 的 `PostToolUse` hook 不會針對 Monitor 執行。
391
392針對 Monitor 命令執行的 hook 可以拒絕該命令，或讓 Claude Code 詢問您。若要允許或改寫該命令，請將 `Bash` matcher 改為包含 Monitor 的 matcher：
393
394* **包含 Monitor 的 matcher**：使用 `Bash|Monitor` 或 `.*` 等 matcher，或不設定 matcher 時，hook 會取得 Monitor 呼叫本身的輸入，且 `allow` 與 `updatedInput` 會生效。在 [`if`](#common-fields) 中請指名 Monitor，例如 `Monitor(tail *)`，其比對方式依循 [`Bash(tail *)` 所遵循的規則](#bash-if-matching)。若其 `if` 指名 Bash，hook 仍會取得 Monitor 呼叫的輸入，但 `allow` 與 `updatedInput` 沒有作用
395* **`Bash` matcher**：hook 會取得 Bash 呼叫。在 `if` 中請指名 Bash，例如 `Bash(tail *)`。若其 `if` 指名 Monitor，hook 不會執行
396
388### Hook 處理常式欄位397### Hook 處理常式欄位
389 398
390內層 `hooks` 陣列中的每個物件都是一個 hook 處理常式：即 matcher 符合時執行的 shell 命令、HTTP 端點、MCP 工具、LLM 提示詞或 agent。共有五種類型：399內層 `hooks` 陣列中的每個物件都是一個 hook 處理常式：即 matcher 符合時執行的 shell 命令、HTTP 端點、MCP 工具、LLM 提示詞或 agent。共有五種類型：
811* **兩行或更多行，每行本身都可解析為 JSON，且第一行以 `{` 開頭、最後一行以 `}` 結尾**：若沒有任何一行是設定欄位的 JSON 輸出物件，則為純文字。若有一行是，則輸出為解析失敗，因此請列印該物件，且 stdout 上不要有其他任何內容。820* **兩行或更多行，每行本身都可解析為 JSON，且第一行以 `{` 開頭、最後一行以 `}` 結尾**：若沒有任何一行是設定欄位的 JSON 輸出物件，則為純文字。若有一行是，則輸出為解析失敗，因此請列印該物件，且 stdout 上不要有其他任何內容。
812* **其他任何以 `{` 開頭並以 `}` 結尾但不是有效 JSON 的內容**：解析失敗。821* **其他任何以 `{` 開頭並以 `}` 結尾但不是有效 JSON 的內容**：解析失敗。
813 822
814對於大多數事件，Claude Code 將 stdout 寫入偵錯日誌，不在逐字稿中顯示。例外是 `UserPromptSubmit`、`UserPromptExpansion`、`SessionStart` 和 `PostModelSwitch`，其中 Claude Code 將純文字 stdout 新增為 Claude 可以看到並據以行動的上下文。在這些事件上，Claude Code 不會新增其無法解析的 stdout。823對於大多數事件，Claude Code 將 stdout 寫入偵錯日誌，不在逐字稿中顯示。在以下事件上，您的 stdout 會傳達給 Claude 或壓縮摘要：
824
825* **`UserPromptSubmit`、`UserPromptExpansion`、`SessionStart` 和 `PostModelSwitch`**：Claude Code 將純文字 stdout 新增為 Claude 可以看到並據以行動的上下文。它不會新增其無法解析的 stdout。
826* **`PreCompact`**：您的 stdout 會成為 [壓縮摘要的指示](#precompact-output)
815 827
816Claude 永遠看不到以 0 退出的 hook 的 stderr。要在 `PreToolUse` 等事件上自行讀取它，請啟用 [偵錯日誌](#debug-hooks)。要從 `PostToolUse` 或 `PostToolUseFailure` hook 向 Claude 顯示警告，請改為退出 2，以便 [Claude 看到 stderr](#exit-code-2-behavior-per-event)，儘管工具已執行。828Claude 永遠看不到以 0 退出的 hook 的 stderr。要在 `PreToolUse` 等事件上自行讀取它，請啟用 [偵錯日誌](#debug-hooks)。要從 `PostToolUse` 或 `PostToolUseFailure` hook 向 Claude 顯示警告，請改為退出 2，以便 [Claude 看到 stderr](#exit-code-2-behavior-per-event)，儘管工具已執行。
817 829
1050Hook 的 `additionalContext`、`systemMessage` 和 `initialUserMessage` 字串，以及其純 stdout，上限為 10,000 個字元：1062Hook 的 `additionalContext`、`systemMessage` 和 `initialUserMessage` 字串，以及其純 stdout，上限為 10,000 個字元：
1051 1063
1052* **範圍**：Claude Code 分別測量每個字串，即使多個 hook 為同一事件執行。對於 JSON 輸出，每個欄位分別測量；純 stdout 整體測量。1064* **範圍**：Claude Code 分別測量每個字串，即使多個 hook 為同一事件執行。對於 JSON 輸出，每個欄位分別測量；純 stdout 整體測量。
1053* **超過限制**：Claude Code 將輸出儲存到工作階段目錄中的檔案，並將其替換為檔案路徑和最多前 2,000 個字元的預覽。大型有效 Bash 結果的處理方式相同，如 [輸出限制](https://code.claude.com/docs/zh-TW/tools-reference.md#output-limits) 下所述。與該 Bash 上限不同，此上限沒有可提高它的設定或環境變數。1065* **超過限制**：除了 [PreCompact stdout](#precompact-output) 之外，Claude Code 會將輸出儲存到工作階段目錄中的檔案。它會將輸出替換為檔案路徑和最多前 2,000 個字元的預覽。大型有效 Bash 結果的處理方式相同，如 [輸出限制](https://code.claude.com/docs/zh-TW/tools-reference.md#output-limits) 下所述。與該 Bash 上限不同，此上限沒有可提高它的設定或環境變數。
1054* **讀取檔案**：Claude Code 不要求 Claude 讀取檔案，因此將 Claude 必須始終看到的任何內容保持在上限內。1066* **讀取檔案**：Claude Code 不要求 Claude 讀取檔案，因此將 Claude 必須始終看到的任何內容保持在上限內。
1055 1067
1056JSON 物件支援三種欄位：1068JSON 物件支援三種欄位：
1954 1966
1955#### PreToolUse 決策控制1967#### PreToolUse 決策控制
1956 1968
1957`PreToolUse` hook 可以控制工具呼叫是否繼續。與其他使用頂層 `decision` 欄位的 hook 不同，PreToolUse 會在 `hookSpecificOutput` 物件內回傳其決策。這讓它擁有更豐富的控制：四種結果（允許、拒絕、詢問或延遲），以及在執行前修改工具輸入的能力。1969`PreToolUse` hook 可以控制工具呼叫是否繼續進行。與其他使用頂層 `decision` 欄位的 hook 不同，PreToolUse 會在 `hookSpecificOutput` 物件中傳回其決策。這讓它擁有更豐富的控制：四種結果（允許、拒絕、詢問或延後），以及在執行前修改工具輸入的能力。若要允許或改寫 Monitor 命令，請參閱[比對 Monitor 命令](#match-monitor-commands)。
1958 1970
1959| 欄位 | 說明 |1971| 欄位 | 說明 |
1960| :- | :- |1972| :- | :- |
2051 2063
2052#### 將工具呼叫延遲到稍後2064#### 將工具呼叫延遲到稍後
2053 2065
2054`"defer"` 適用於以子程序方式執行 `claude -p` 並讀取其 JSON 輸出的整合，例如 Agent SDK 應用程式或建構在 Claude Code 之上的自訂 UI。它讓呼叫端程序可以在工具呼叫處暫停 Claude、透過自己的介面收集輸入，然後從中斷處恢復。Claude Code 只在使用 `-p` 旗標的[非互動模式](https://code.claude.com/docs/zh-TW/headless.md)中遵守此值。在互動式工作階段中，它會記錄警告並忽略 hook 結果。2066`"defer"` 適用於以子程序執行 `claude -p` 並讀取其 JSON 輸出的整合，例如 Agent SDK 應用程式或建構於 Claude Code 之上的自訂 UI。它讓呼叫端程序能在工具呼叫處暫停 Claude，透過自己的介面收集輸入，然後從中斷處繼續。
2067
2068Claude Code 僅在使用 `-p` 旗標的[非互動模式](https://code.claude.com/docs/zh-TW/headless.md)下，且僅在 Claude 於該回合中只發出單一工具呼叫時，才會採用 `"defer"`：
2069
2070* **在互動式工作階段中**：會記錄警告並忽略 hook 結果
2071* **同時有多個工具呼叫**：`"defer"` 會被忽略並發出警告，工具將依照一般權限流程繼續進行
2055 2072
2056`AskUserQuestion` 工具是典型的情況：Claude 想詢問使用者某件事，但沒有終端機可供回答。`-p` 執行只有在具有[權限主機](https://code.claude.com/docs/zh-TW/headless.md#turn-off-permission-prompts-in-unattended-runs)時才會提供 `AskUserQuestion`，例如您以 `--permission-prompt-tool` 傳入的 MCP 工具，因此請以此方式啟動執行。來回流程如下：2073`AskUserQuestion` 工具是典型的情況：Claude 想詢問使用者某件事，但沒有終端機可供回答。`-p` 執行只有在具有[權限主機](https://code.claude.com/docs/zh-TW/headless.md#turn-off-permission-prompts-in-unattended-runs)時才會提供 `AskUserQuestion`，例如您以 `--permission-prompt-tool` 傳入的 MCP 工具，因此請以此方式啟動執行。來回流程如下：
2057 2074
20614. 呼叫端程序以相同的權限主機執行 `claude -p --resume <session-id>`。同一個工具呼叫再次觸發 `PreToolUse`。20784. 呼叫端程序以相同的權限主機執行 `claude -p --resume <session-id>`。同一個工具呼叫再次觸發 `PreToolUse`。
20625. hook 回傳 `permissionDecision: "allow"`，並在 `updatedInput` 中附上答案。工具執行，Claude 繼續。20795. hook 回傳 `permissionDecision: "allow"`，並在 `updatedInput` 中附上答案。工具執行，Claude 繼續。
2063 2080
2064`deferred_tool_use` 欄位攜帶工具的 `id`、`name` 和 `input`。`input` 是 Claude 為該工具呼叫產生的參數，在執行前擷取：2081`deferred_tool_use` 欄位包含工具的 `id`、`name` 與 `input`：
2065 2082
2066```json theme={null}2083```json theme={null}
2067{2084{
2077}2094}
2078```2095```
2079 2096
2080沒有逾時或重試次數限制。工作階段會保留在磁碟上直到您繼續它，但受 [`cleanupPeriodDays`](https://code.claude.com/docs/zh-TW/settings-reference#cleanupperioddays) 保留期清理的約束，該清理預設會在 30 天後刪除工作階段檔案，並遵循[保留期清理規則](https://code.claude.com/docs/zh-TW/claude-directory.md#cleaned-up-automatically)。2097沒有逾時或重試次數限制。工作階段會保留在磁碟上，直到 [`cleanupPeriodDays`](https://code.claude.com/docs/zh-TW/settings-reference#cleanupperioddays) [保留期清理](https://code.claude.com/docs/zh-TW/claude-directory.md#cleaned-up-automatically)將其刪除，預設為 30 天後。
2081
2082如果在您繼續時延後的工具已不再可用，繼續後的第一個結果會帶有 `stop_reason: "tool_deferred_unavailable"` 和 `is_error: true`，且 hook 不會觸發。當提供該工具的 MCP 伺服器在繼續的工作階段中未連線時，就會發生這種情況。`deferred_tool_use` payload 仍會包含在內，讓您可以識別遺失的是哪個工具。
2083
2084* **如果您在繼續時或之後未傳送提示詞**，該呼叫仍處於待處理狀態。在工具可用時再次繼續，它會最先執行。
2085* **如果您在繼續時或之後傳送了提示詞**，Claude Code 會在沒有工具結果的情況下回答它，並捨棄延後的呼叫。如果您仍需要呼叫該工具，請在工具可用後傳送新的提示詞。
2086 2098
2087如果在您不帶提示詞繼續時，所等待的答案尚未就緒，hook 可以再次傳回 `"defer"`。如果您傳送了提示詞而 hook 再次延後，Claude Code 會以相同方式處理該提示詞：在沒有工具結果的情況下回答，並捨棄該呼叫。請在不帶提示詞的情況下繼續，直到 hook 傳回 `"allow"` 或 `"deny"`，這就是呼叫端程序跳出迴圈的方式。2099如果恢復時回答尚未備妥，hook 可以再次回傳 `"defer"`。如果您在該次恢復時傳送了提示詞，Claude 會在沒有工具結果的情況下回答它，且不會執行該呼叫。請在不帶提示詞的情況下恢復，直到 hook 回傳 `"allow"` 或 `"deny"`。
2088
2089`"defer"` 只在 Claude 於該回合中進行單一工具呼叫時有效。若 Claude 同時進行多個工具呼叫，`"defer"` 會被忽略並顯示警告，工具則會經由一般的權限流程繼續。此限制的原因在於恢復時只能重新執行一個工具：無法在不讓其他呼叫懸而未決的情況下，延遲一批呼叫中的其中一個。
2090 2100
2091> [!NOTE]2101> [!NOTE]
2092>2102>
2093> 若要在 plan mode 中恢復延遲的工作階段，請將 [`--permission-prompt-tool`](https://code.claude.com/docs/zh-TW/cli-reference#cli-flags) 與 `--resume` 一起傳入，讓 Claude Code 能呈現計畫以供核准。其他條件請參閱[以 `-p` 在 plan mode 中恢復](https://code.claude.com/docs/zh-TW/sessions#resume-in-plan-mode-with-p)。需要 Claude Code v2.1.246 或更新版本。2103> 若要在 plan mode 中恢復延遲的工作階段，請將 [`--permission-prompt-tool`](https://code.claude.com/docs/zh-TW/cli-reference#cli-flags) 與 `--resume` 一起傳入，讓 Claude Code 能呈現計畫以供核准。其他條件請參閱[以 `-p` 在 plan mode 中恢復](https://code.claude.com/docs/zh-TW/sessions#resume-in-plan-mode-with-p)。需要 Claude Code v2.1.246 或更新版本。
2094>2104>
2095> 當您以 `-p` 恢復時，Claude Code 不會還原任何其他已儲存的權限模式。它會以新的 `claude -p` 執行所使用的權限模式啟動，因此若延遲的工作階段使用了 `--permission-mode` 或 `--dangerously-skip-permissions`，請再次傳入。當您不使用 `-p`、以 `claude --resume <session-id>` 恢復時，Claude Code 會還原已儲存的權限模式，例外情況列於[恢復時的權限模式](https://code.claude.com/docs/zh-TW/sessions.md#permission-mode-on-resume)。2105> 當您使用 `-p` 恢復時，Claude Code 不會還原任何其他已儲存的權限模式。它會以新的 `claude -p` 執行所使用的權限模式啟動，因此如果已延後的工作階段使用了 `--permission-mode` 或 `--dangerously-skip-permissions`，請再次傳入。
2106
2107##### 在已延後的工具無法使用時恢復
2108
2109帶有 `stop_reason: "tool_deferred_unavailable"` 的結果表示已延後呼叫的工具在恢復的工作階段中無法使用，例如因為其 MCP 伺服器未連線。您的 `PreToolUse` hook 不會觸發，結果的 `deferred_tool_use` 欄位會指出該工具。
2110
2111在呼叫處於待處理狀態期間，您傳送的任何提示詞都不會送達 Claude，且執行會以退出碼 1 結束。`result` 欄位以 `<tool> isn't available, so its deferred call didn't run.` 開頭。請執行該呼叫，或將其捨棄使其不執行：
2112
2113* **執行該呼叫**：讓工具可用後再次恢復。
2114* **捨棄該呼叫**：帶著提示詞恢復，並將 [`CLAUDE_CODE_DROP_UNAVAILABLE_DEFERRED_TOOL`](https://code.claude.com/docs/zh-TW/env-vars#variables) 設為 `1`。Claude 會收到錯誤作為該呼叫的結果，並回答您的提示詞。之後再恢復時，就不會有待處理的呼叫。
2115
2116當您捨棄呼叫時，執行會先寫入 `result` 欄位為空的 `tool_deferred_unavailable` 結果，然後在第二個結果中寫入 Claude 的回答。除非該回答是錯誤，否則會以退出碼 0 結束。如果您設定了該變數但未傳送提示詞，執行仍會捨棄該呼叫並以退出碼 1 結束。
2117
2118在 v2.1.319 之前，Claude Code 會在沒有工具結果的情況下回答提示詞並捨棄該呼叫。在這些版本中，請在工具可用後傳送新的提示詞。
2096 2119
2097### PermissionRequest2120### PermissionRequest
2098 2121
2148| `message` | 僅適用於 `"deny"`：告訴 Claude 權限被拒絕的原因 |2171| `message` | 僅適用於 `"deny"`：告訴 Claude 權限被拒絕的原因 |
2149| `interrupt` | 僅適用於 `"deny"`：若為 `true`，則停止 Claude |2172| `interrupt` | 僅適用於 `"deny"`：若為 `true`，則停止 Claude |
2150 2173
2174若要允許或改寫 Monitor 命令，請參閱[比對 Monitor 命令](#match-monitor-commands)。
2175
2151以退出碼 2 結束但未提供 `decision` 物件的 hook 不會改變權限流程，且其 stderr 會被捨棄。若要授予或拒絕請求，請回傳 `decision` 物件。2176以退出碼 2 結束但未提供 `decision` 物件的 hook 不會改變權限流程，且其 stderr 會被捨棄。若要授予或拒絕請求，請回傳 `decision` 物件。
2152 2177
2153```json theme={null}2178```json theme={null}
2205* 若要在任何工具成功完成後執行 hook，請省略 `matcher` 或將其設為 `"*"`。接著您的 hook 可以自行找出變更內容，例如執行 `git status --porcelain`，它也會列出 `git diff` 遺漏的未追蹤檔案。對於失敗的工具呼叫，請在 [PostToolUseFailure](#posttoolusefailure) 下加入相同的 hook。2230* 若要在任何工具成功完成後執行 hook，請省略 `matcher` 或將其設為 `"*"`。接著您的 hook 可以自行找出變更內容，例如執行 `git status --porcelain`，它也會列出 `git diff` 遺漏的未追蹤檔案。對於失敗的工具呼叫，請在 [PostToolUseFailure](#posttoolusefailure) 下加入相同的 hook。
2206* 若要在特定檔案於磁碟上變更時執行 hook（不論是由誰寫入），請使用 [FileChanged](#filechanged)。當 `Bash` 命令或 Claude Code 以外的程序重寫同一個檔案時，Claude Code 不會執行比對 `Edit|Write` 的 `PostToolUse` hook。2231* 若要在特定檔案於磁碟上變更時執行 hook（不論是由誰寫入），請使用 [FileChanged](#filechanged)。當 `Bash` 命令或 Claude Code 以外的程序重寫同一個檔案時，Claude Code 不會執行比對 `Edit|Write` 的 `PostToolUse` hook。
2207 2232
2233#### 中斷後的 PostToolUse
2234
2235如果在工具呼叫期間您傳送訊息或中斷後，`PostToolUse` hook 提前停止，請確認您按的是 `Ctrl+Enter`、`Enter` 還是 `Esc`：
2236
2237* **`Ctrl+Enter`**：如果在工具執行期間按下它會[結束回合](https://code.claude.com/docs/zh-TW/interactive-mode.md#when-claude-code-sends-what-you-queued)，且工具完成，您的 `PostToolUse` hook 會針對其結果執行，並有 10 秒可以完成。如果您在訊息之前排入了 `!` 命令，或背景任務已停用（例如透過 [`CLAUDE_CODE_DISABLE_BACKGROUND_TASKS`](https://code.claude.com/docs/zh-TW/env-vars#variables)），此按鍵的作用等同於 `Esc`。
2238* **`Enter`**：以 `Enter` 排入的訊息不會中斷回合，因此 hook 會保有其一般的 `timeout`。
2239* **`Esc`**：會立即取消 hook，因此當 hook 必須執行時，請以 `Enter` 或 `Ctrl+Enter` 傳送訊息。
2240
224110 秒時間一到，Claude Code 會終止仍在執行的命令 hook，不論其 [`timeout`](#common-fields) 為何。若要讓較長的命令 hook 完成，請以 [`async: true`](#run-hooks-in-the-background) 執行它，這表示該 hook 無法阻擋或改寫結果。
2242
2243在 v2.1.319 之前，當您以訊息中斷回合後，hook 不會啟動，而執行中的 hook 會被停止。
2244
2208#### PostToolUse 輸入2245#### PostToolUse 輸入
2209 2246
2210`PostToolUse` hook 會在工具已成功執行後觸發。輸入同時包含 `tool_input`（傳送給工具的引數）與 `tool_response`（工具回傳的結果）。兩者的確切 schema 取決於工具。檔案工具的 `tool_input` 路徑格式與 [PreToolUse](#pretooluse-input) 相同：一律為絕對路徑，並使用平台原生的分隔符號，因此在 Windows 上為反斜線。對於 MCP 工具，輸入也會攜帶 [`mcp_server`](#pretooluse-input) 物件。2247`PostToolUse` hook 會在工具已成功執行後觸發。輸入同時包含 `tool_input`（傳送給工具的引數）與 `tool_response`（工具回傳的結果）。兩者的確切 schema 取決於工具。檔案工具的 `tool_input` 路徑格式與 [PreToolUse](#pretooluse-input) 相同：一律為絕對路徑，並使用平台原生的分隔符號，因此在 Windows 上為反斜線。對於 MCP 工具，輸入也會攜帶 [`mcp_server`](#pretooluse-input) 物件。
2479| `permission_prompt` | Claude 需要您核准工具使用或沙箱化命令的[網路請求](https://code.claude.com/docs/zh-TW/sandboxing.md#network-isolation)，且提示已等待約六秒 |2516| `permission_prompt` | Claude 需要您核准工具使用或沙箱化命令的[網路請求](https://code.claude.com/docs/zh-TW/sandboxing.md#network-isolation)，且提示已等待約六秒 |
2480| `idle_prompt` | Claude 約在 60 秒前完成回應，且您之後未曾輸入 |2517| `idle_prompt` | Claude 約在 60 秒前完成回應，且您之後未曾輸入 |
2481| `auth_success` | 身分驗證完成 |2518| `auth_success` | 身分驗證完成 |
2519| `auth_storage_failure` | 您的登入已完成，但 Claude Code 無法將新憑證儲存至其[憑證儲存區](https://code.claude.com/docs/zh-TW/authentication.md#credential-management)。會取代 `auth_success` 觸發 |
2482| `elicitation_dialog` | MCP 伺服器開啟 elicitation 表單，且您約六秒未輸入 |2520| `elicitation_dialog` | MCP 伺服器開啟 elicitation 表單，且您約六秒未輸入 |
2483| `elicitation_url_dialog` | MCP 伺服器要求您開啟瀏覽器 URL，且您約六秒未輸入 |2521| `elicitation_url_dialog` | MCP 伺服器要求您開啟瀏覽器 URL，且您約六秒未輸入 |
2484| `elicitation_complete` | MCP 伺服器回報 [URL 模式 elicitation](#elicitation-input) 已完成 |2522| `elicitation_complete` | MCP 伺服器回報 [URL 模式 elicitation](#elicitation-input) 已完成 |
2490| `quota_auto_resume_disabled` | Claude Code 結束對 claude.ai 用量上限的等待，且未繼續您的任務：[`autoContinueAtUsageLimit`](https://code.claude.com/docs/zh-TW/settings-reference#autocontinueatusagelimit) 已關閉，或在 Claude Code 自行開始的等待期間重設時間延後超過 24 小時、繼續的任務持續觸及上限，或繼續執行在抵達模型之前遭到封鎖。當您按下 `Esc` 或 `Ctrl+C`，或選擇 **Don't continue automatically** 時不會觸發 |2528| `quota_auto_resume_disabled` | Claude Code 結束對 claude.ai 用量上限的等待，且未繼續您的任務：[`autoContinueAtUsageLimit`](https://code.claude.com/docs/zh-TW/settings-reference#autocontinueatusagelimit) 已關閉，或在 Claude Code 自行開始的等待期間重設時間延後超過 24 小時、繼續的任務持續觸及上限，或繼續執行在抵達模型之前遭到封鎖。當您按下 `Esc` 或 `Ctrl+C`，或選擇 **Don't continue automatically** 時不會觸發 |
2491| `plugin_notification` | [mod](https://code.claude.com/docs/zh-TW/plugins/mods/api.md#show-something-without-starting-a-turn) 以 `$.ui.notify` 發出通知。除非 mod 另行設定，否則 hook 的 `title` 為該 mod 的名稱 |2529| `plugin_notification` | [mod](https://code.claude.com/docs/zh-TW/plugins/mods/api.md#show-something-without-starting-a-turn) 以 `$.ui.notify` 發出通知。除非 mod 另行設定，否則 hook 的 `title` 為該 mod 的名稱 |
2492 2530
2493`quota_auto_resume_fired`、`quota_auto_resume_stale` 與 `quota_auto_resume_disabled` 類型需要 Claude Code v2.1.234 或更新版本。2531`quota_auto_resume_fired`、`quota_auto_resume_stale` 與 `quota_auto_resume_disabled` 類型需要 Claude Code v2.1.234 或更新版本。`auth_storage_failure` 類型需要 v2.1.288 或更新版本。
2494 2532
2495在終端機工作階段中，針對沙箱化命令網路請求的 `permission_prompt` 需要 Claude Code v2.1.246 或更新版本。2533在終端機工作階段中，針對沙箱化命令網路請求的 `permission_prompt` 需要 Claude Code v2.1.246 或更新版本。
2496 2534
3325}3363}
3326```3364```
3327 3365
3366#### PreCompact 輸出
3367
3368當 PreCompact hook 以 0 結束且未阻擋時，Claude Code 會將其 stdout 作為壓縮摘要的指令。請將每個 hook 的 stdout 控制在 10,000 個字元以內。Claude Code 會在上限處截斷較長的輸出並附加標記。
3369
3328### PostCompact3370### PostCompact
3329 3371
3330在 Claude Code 完成壓縮作業後執行。使用此事件對新的壓縮後狀態做出反應，例如記錄產生的摘要或更新外部狀態。Claude Code 會捨棄 PostCompact hook 的 `systemMessage` 與 `continue` 欄位。3372在 Claude Code 完成壓縮作業後執行。使用此事件對新的壓縮後狀態做出反應，例如記錄產生的摘要或更新外部狀態。Claude Code 會捨棄 PostCompact hook 的 `systemMessage` 與 `continue` 欄位。
