268| [Skill](/docs/zh-TW/skills) frontmatter | 叫用 skill 後的工作階段其餘部分。請參閱 [Skills 和代理中的 Hooks](#hooks-in-skills-and-agents) | 是，在 skill 檔案中定義 |268| [Skill](/docs/zh-TW/skills) frontmatter | 叫用 skill 後的工作階段其餘部分。請參閱 [Skills 和代理中的 Hooks](#hooks-in-skills-and-agents) | 是，在 skill 檔案中定義 |
269| [Subagent](/docs/zh-TW/sub-agents) frontmatter | 該 subagent 執行時 | 是，在 subagent 檔案中定義 |269| [Subagent](/docs/zh-TW/sub-agents) frontmatter | 該 subagent 執行時 | 是，在 subagent 檔案中定義 |
270 270
271[Claude Code on the web](/docs/zh-TW/claude-code-on-the-web) 上的雲端工作階段不會讀取您的本機 `~/.claude/settings.json`；那裡的 hooks 來自儲存庫和您組織的伺服器管理設定。在 [自託管環境](/docs/zh-TW/self-hosted-environments-configuration#permissions-and-tool-approval) 中，Claude Code 也執行操作員從執行器主機的 `~/.claude/` 中植入的 hooks，並在該檔案位於 [Claude Code 應用的受管理來源](/docs/zh-TW/managed-settings#how-claude-code-combines-managed-sources) 中時執行執行器映像的受管理設定檔中的 hooks，預設情況下僅當伺服器管理設定或 MDM 傳遞的 Claude Code 原則都不提供受管理層級時。請參閱 [您的設定中哪些內容會轉移到雲端工作階段](/docs/zh-TW/cloud-environments#what-carries-over-from-your-setup) 以了解哪些檔案到達雲端工作階段。271[Claude Code on the web](/docs/zh-TW/claude-code-on-the-web) 上的雲端工作階段不會讀取您的本機 `~/.claude/settings.json`；那裡的 hooks 來自儲存庫的 `.claude/settings.json`（在具有一個儲存庫的工作階段中）、從您的 claude.ai 帳戶 [同步的外掛程式](/docs/zh-TW/plugins-reference#synced-plugins)，以及您組織的伺服器管理設定。在 [自託管環境](/docs/zh-TW/self-hosted-environments-configuration#permissions-and-tool-approval) 中，Claude Code 也執行操作員從執行器主機的 `~/.claude/` 中植入的 hooks，並在該檔案位於 [Claude Code 應用的受管理來源](/docs/zh-TW/managed-settings#how-claude-code-combines-managed-sources) 中時執行執行器映像的受管理設定檔中的 hooks，預設情況下僅當伺服器管理設定或 MDM 傳遞的 Claude Code 原則都不提供受管理層級時。請參閱 [您的設定中哪些內容會轉移到雲端工作階段](/docs/zh-TW/cloud-environments#what-carries-over-from-your-setup) 以了解哪些檔案到達雲端工作階段。
272 272
273有關設定檔解析的詳細資訊，請參閱 [settings](/docs/zh-TW/settings)。273有關設定檔解析的詳細資訊，請參閱 [settings](/docs/zh-TW/settings)。
274 274
1181 Hook 事件1181 Hook 事件
1182</h2>1182</h2>
1183 1183
1184每個事件對應於 Claude Code 生命週期中的一個點，hooks 可以在該點執行。下面的章節按照生命週期排序：從工作階段設定到代理迴圈再到工作階段結束。每個章節描述事件何時觸發、支援的匹配器、接收的 JSON 輸入，以及如何透過輸出控制行為。1184每個事件對應於 Claude Code 生命週期中的一個點，hooks 可以在該點執行。下面的章節按照生命週期的順序排列：從工作階段設定到代理迴圈再到工作階段結束。每個章節描述事件何時觸發、它支援的匹配器、它接收的 JSON 輸入，以及如何透過輸出控制行為。
1185 1185
1186<h3 id="sessionstart">1186<h3 id="sessionstart">
1187 SessionStart1187 SessionStart
1189 1189
1190在 Claude Code 啟動新工作階段或恢復現有工作階段時執行。適用於載入開發環境背景資訊，例如現有問題或程式碼庫的最近變更，或設定環境變數。對於不需要指令碼的靜態背景資訊，請改用 [CLAUDE.md](/docs/zh-TW/memory)。1190在 Claude Code 啟動新工作階段或恢復現有工作階段時執行。適用於載入開發環境背景資訊，例如現有問題或程式碼庫的最近變更，或設定環境變數。對於不需要指令碼的靜態背景資訊，請改用 [CLAUDE.md](/docs/zh-TW/memory)。
1191 1191
1192SessionStart 在每個工作階段執行，因此請保持這些 hooks 快速。僅支援 `type: "command"` 和 `type: "mcp_tool"` hooks。請參閱 [MCP tool hook 欄位](#mcp-tool-hook-fields)，了解 `mcp_tool` hooks 何時執行。1192SessionStart 在每個工作階段上執行，因此請保持這些 hooks 快速。僅支援 `type: "command"` 和 `type: "mcp_tool"` hooks。請參閱 [MCP tool hook 欄位](#mcp-tool-hook-fields)，了解 `mcp_tool` hooks 何時執行。
1193 1193
1194匹配器值對應於工作階段的啟動方式：1194匹配器值對應於工作階段的啟動方式：
1195 1195
1205 1205
1206當您啟動互動式工作階段、在啟動時使用 `--continue` 或 `--resume` 恢復對話，或執行 `/clear` 時，SessionStart hooks 在背景執行。您可以立即輸入，恢復的對話會立即出現，無需等待 hooks。Claude 的第一個回應仍會等待 hooks 完成，因此它們的背景資訊會到達 Claude。1206當您啟動互動式工作階段、在啟動時使用 `--continue` 或 `--resume` 恢復對話，或執行 `/clear` 時，SessionStart hooks 在背景執行。您可以立即輸入，恢復的對話會立即出現，無需等待 hooks。Claude 的第一個回應仍會等待 hooks 完成，因此它們的背景資訊會到達 Claude。
1207 1207
1208當您在工作階段內使用 `/resume` 切換對話時，切換會等待 hooks 完成。如果您在背景 hooks 仍在執行時執行 `/clear` 或切換到另一個對話，它們返回的任何內容都不會套用到工作階段。1208當您在工作階段內使用 `/resume` 切換對話時，切換會等待 hooks 完成。如果您在背景 hooks 仍在執行時執行 `/clear` 或切換到另一個對話，它們傳回的任何內容都不會套用到工作階段。
1209 1209
1210相同的等待也適用於啟動，包括恢復的工作階段：您在 SessionStart hooks 仍在執行時發送的提示不會到達 Claude，直到它們完成。1210在啟動時也適用相同的等待，包括恢復的工作階段：您在 SessionStart hooks 仍在執行時傳送的提示不會到達 Claude，直到它們完成。
1211 1211
1212在任一等待期間，按 `Esc` 將提示返回到輸入中而不發送。Hooks 會繼續執行。1212在任一等待期間，按 `Esc` 將提示取回輸入框而不傳送。Hooks 會繼續執行。
1213 1213
1214<h4 id="sessionstart-input">1214<h4 id="sessionstart-input">
1215 SessionStart 輸入1215 SessionStart 輸入
1220| 欄位 | 描述 |1220| 欄位 | 描述 |
1221| :-------------- | :---------------------------------------------------------------------------------------------------------------- |1221| :-------------- | :---------------------------------------------------------------------------------------------------------------- |
1222| `source` | 工作階段如何啟動：新工作階段為 `"startup"`、恢復的工作階段為 `"resume"`、`/clear` 後為 `"clear"`、壓縮後為 `"compact"`，或從現有工作階段分支的新工作階段為 `"fork"` |1222| `source` | 工作階段如何啟動：新工作階段為 `"startup"`、恢復的工作階段為 `"resume"`、`/clear` 後為 `"clear"`、壓縮後為 `"compact"`，或從現有工作階段分支的新工作階段為 `"fork"` |
1223| `model` | 作用中的模型識別碼。例如在 `/clear` 後或透過對話恢復恢復工作階段時可能會省略，因此在讀取前檢查欄位 |1223| `model` | 作用中的模型識別碼。例如在 `/clear` 後或透過對話復原恢復工作階段時，可能會省略，因此在讀取前請檢查欄位 |
1224| `agent_type` | 代理名稱，當您使用 `claude --agent <name>` 啟動 Claude Code 時出現 |1224| `agent_type` | 代理名稱，當您使用 `claude --agent <name>` 啟動 Claude Code 時出現 |
1225| `session_title` | 目前工作階段標題（如果已設定），例如透過 `--name` 或 `/rename`。發出 `sessionTitle` 的 hook 可以先檢查 `session_title` 以避免覆寫使用者明確設定的標題 |1225| `session_title` | 目前的工作階段標題（如果已設定），例如透過 `--name` 或 `/rename`。發出 `sessionTitle` 的 hook 可以先檢查 `session_title` 以避免覆寫使用者明確設定的標題 |
1226 1226
1227當 `source` 為 `"resume"` 或 `"fork"` 且文字記錄包含至少一個來自 Claude 的回應時，SessionStart hooks 也會接收下面的四個欄位。您的 hook 可以使用它們在第一個請求之前報告恢復陳舊對話的成本，例如在 [`systemMessage`](#json-output) 中。這些欄位需要 Claude Code v2.1.251 或更新版本。1227當 `source` 為 `"resume"` 或 `"fork"` 且文字記錄包含至少一個來自 Claude 的回應時，SessionStart hooks 也會接收下面的四個欄位。您的 hook 可以使用它們在第一個請求之前報告恢復陳舊對話的成本，例如在 [`systemMessage`](#json-output) 中。這些欄位需要 Claude Code v2.1.251 或更新版本。
1228 1228
1229| 欄位 | 描述 |1229| 欄位 | 描述 |
1230| :---------------------------- | :----------------------------------------------------------------------------------------------- |1230| :---------------------------- | :----------------------------------------------------------------------------------------------- |
1231| `seconds_since_last_response` | 自恢復文字記錄中最後一個回應以來的掛鐘秒數 |1231| `seconds_since_last_response` | 自恢復文字記錄中最後一個回應以來的掛鐘秒數 |
1232| `context_tokens` | 恢復工作階段的第一個請求作為其提示重新發送的令牌 |1232| `context_tokens` | 恢復工作階段的第一個請求作為其提示重新傳送的權杖 |
1233| `prompt_cache_likely_expired` | 當最後一個回應早於工作階段的 [prompt cache 生命週期](/docs/zh-TW/prompt-caching#cache-lifetime) 或更新的壓縮替換了快取的對話時為 `true` |1233| `prompt_cache_likely_expired` | 當最後一個回應早於工作階段的 [prompt cache 生命週期](/docs/zh-TW/prompt-caching#cache-lifetime) 或更新的壓縮替換了快取的對話時為 `true` |
1234| `estimated_cache_write_usd` | 將 `context_tokens` 寫入工作階段模型上的 prompt cache 的估計成本（美元），不包括回應 |1234| `estimated_cache_write_usd` | 在工作階段的模型上將 `context_tokens` 寫入 prompt cache 的估計成本（美元），不包括回應 |
1235 1235
1236此範例顯示在最後一個回應後 90 分鐘恢復的工作階段的輸入：1236此範例顯示在最後一個回應後 90 分鐘恢復的工作階段的輸入：
1237 1237
1254 SessionStart 決策控制1254 SessionStart 決策控制
1255</h4>1255</h4>
1256 1256
1257Claude Code 將其 [視為純文字](#exit-code-0) 的 stdout 新增到 Claude 的背景資訊。除了所有 hooks 可用的 [JSON 輸出欄位](#json-output) 外，您還可以返回這些事件特定欄位：1257Claude Code 將它 [視為純文字](#exit-code-0) 的 stdout 新增到 Claude 的背景資訊。除了 [所有 hooks 可用的 JSON 輸出欄位](#json-output) 外，您還可以傳回這些事件特定的欄位：
1258 1258
1259| 欄位 | 描述 |1259| 欄位 | 描述 |
1260| :------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------- |1260| :------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------- |
1261| `additionalContext` | 在對話開始時、第一個提示之前新增到 Claude 背景資訊的字串。請參閱 [為 Claude 新增背景資訊](#add-context-for-claude)，了解文字如何傳遞以及要放入其中的內容 |1261| `additionalContext` | 在對話開始時、第一個提示之前新增到 Claude 背景資訊的字串。請參閱 [為 Claude 新增背景資訊](#add-context-for-claude)，了解文字如何傳遞以及要放入其中的內容 |
1262| `initialUserMessage` | 用作工作階段第一個使用者訊息的字串。適用於 [非互動模式](/docs/zh-TW/headless)，搭配 `-p` 旗標，即使未提供提示，它也會成為第一個回合。如果提供了提示，它會作為下一個回合跟隨。與附加到現有回合的 `additionalContext` 不同，這會建立回合 |1262| `initialUserMessage` | 用作工作階段第一個使用者訊息的字串。適用於 [非互動模式](/docs/zh-TW/headless)，搭配 `-p` 旗標，即使未提供提示，它也會成為第一個回合。如果提供了提示，它會作為下一個回合跟隨。與 `additionalContext` 不同（它附加到現有回合），這會建立回合 |
1263| `sessionTitle` | 設定工作階段標題，效果與 `/rename` 相同。用於根據啟動資料夾、git 分支或 worktree 名稱自動命名工作階段。當 `source` 為 `"startup"`、`"resume"` 或 `"fork"` 時適用；在 `"clear"` 和 `"compact"` 上忽略 |1263| `sessionTitle` | 設定工作階段標題，效果與 `/rename` 相同。用於從啟動資料夾、git 分支或 worktree 名稱自動命名工作階段。當 `source` 為 `"startup"`、`"resume"` 或 `"fork"` 時適用；在 `"clear"` 和 `"compact"` 上忽略 |
1264| `watchPaths` | 絕對路徑陣列，用於在此工作階段期間監視 [FileChanged](#filechanged) 事件 |1264| `watchPaths` | 絕對路徑陣列，用於在此工作階段期間監視 [FileChanged](#filechanged) 事件 |
1265| `reloadSkills` | 布林值。當為 `true` 時，Claude Code 在 SessionStart hooks 完成後重新掃描 [skill](/docs/zh-TW/skills) 和命令目錄，因此 hook 安裝的 skills 在同一工作階段中可用，從第一個提示開始 |1265| `reloadSkills` | 布林值。當為 `true` 時，Claude Code 在 SessionStart hooks 完成後重新掃描 [skill](/docs/zh-TW/skills) 和命令目錄，因此 hook 安裝的 skills 在同一工作階段中可用，從第一個提示開始 |
1266 1266
1274}1274}
1275```1275```
1276 1276
1277由於此事件的純文字 stdout 已到達 Claude，只載入背景資訊的 hook 可以直接列印到 stdout，而無需建立 JSON。當您需要將背景資訊與其他欄位（例如 `sessionTitle`）結合時，請使用 JSON 形式。1277由於此事件的純 stdout 已到達 Claude，只載入背景資訊的 hook 可以直接列印到 stdout，而無需建立 JSON。當您需要將背景資訊與其他欄位（例如 `sessionTitle`）結合時，請使用 JSON 形式。
1278 1278
1279當 SessionStart hook 安裝或更新 skills 時使用 `reloadSkills`。Skill 探索通常在 SessionStart hooks 完成之前執行，因此 hook 寫入 `~/.claude/skills/` 或 `.claude/skills/` 的檔案否則只會在下一個工作階段中出現。此範例同步共享 skills 儲存庫並請求重新掃描：1279當 SessionStart hook 安裝或更新 skills 時，使用 `reloadSkills`。Skill 探索通常在 SessionStart hooks 完成之前執行，因此 hook 寫入 `~/.claude/skills/` 或 `.claude/skills/` 的檔案否則只會在下一個工作階段中出現。此範例同步共享 skills 儲存庫並要求重新掃描：
1280 1280
1281```bash theme={null}1281```bash theme={null}
1282#!/bin/bash1282#!/bin/bash
1287echo '{"hookSpecificOutput": {"hookEventName": "SessionStart", "reloadSkills": true}}'1287echo '{"hookSpecificOutput": {"hookEventName": "SessionStart", "reloadSkills": true}}'
1288```1288```
1289 1289
1290儲存庫 URL 是佔位符；將其替換為您自己的 skills 儲存庫。使用佔位符時，複製會失敗並列印 `fatal:` 訊息到 stderr。來自以 0 退出的 SessionStart hook 的 stderr 僅供參考，因此 `reloadSkills` 請求仍然適用。1290儲存庫 URL 是佔位符；請將其替換為您自己的 skills 儲存庫。使用佔位符時，複製會失敗並列印 `fatal:` 訊息到 stderr。來自以 0 退出的 SessionStart hook 的 stderr 僅供參考，因此 `reloadSkills` 請求仍然適用。
1291 1291
1292<h4 id="persist-environment-variables">1292<h4 id="persist-environment-variables">
1293 保留環境變數1293 保留環境變數
1294</h4>1294</h4>
1295 1295
1296SessionStart hooks 可以存取 `CLAUDE_ENV_FILE` 環境變數，該變數提供一個檔案路徑，您可以在其中保留後續 Bash 命令的環境變數。1296SessionStart hooks 可以存取 `CLAUDE_ENV_FILE` 環境變數，它提供一個檔案路徑，您可以在其中保留後續 Bash 命令的環境變數。
1297 1297
1298若要設定個別環境變數，請將 `export` 陳述式寫入 `CLAUDE_ENV_FILE`。使用附加 (`>>`) 以保留由其他 hooks 設定的變數：1298若要設定個別環境變數，請將 `export` 陳述式寫入 `CLAUDE_ENV_FILE`。使用附加 (`>>`) 來保留由其他 hooks 設定的變數：
1299 1299
1300```bash theme={null}1300```bash theme={null}
1301#!/bin/bash1301#!/bin/bash
1309exit 01309exit 0
1310```1310```
1311 1311
1312若要捕獲設定命令中的所有環境變更，請比較之前和之後的匯出變數：1312若要擷取設定命令的所有環境變更，請比較之前和之後的匯出變數：
1313 1313
1314```bash theme={null}1314```bash theme={null}
1315#!/bin/bash1315#!/bin/bash
1336 Setup1336 Setup
1337</h3>1337</h3>
1338 1338
1339僅當您使用 `--init-only` 啟動 Claude Code，或在 [非互動模式](/docs/zh-TW/headless) 中使用 `--init` 或 `--maintenance` 搭配 `-p` 旗標時觸發。在正常啟動時不觸發。用於一次性相依性安裝或您從 CI 或指令碼明確觸發的排程清理，與正常工作階段啟動分開。對於每個工作階段的初始化，請改用 [SessionStart](#sessionstart)。1339僅當您使用 `--init-only` 啟動 Claude Code，或在 [非互動模式](/docs/zh-TW/headless) 中使用 `--init` 或 `--maintenance` 搭配 `-p` 旗標時觸發。它不會在正常啟動時觸發。用於一次性相依性安裝或您從 CI 或指令碼明確觸發的排程清理，與正常工作階段啟動分開。對於每個工作階段的初始化，請改用 [SessionStart](#sessionstart)。
1340 1340
1341匹配器值對應於觸發 hook 的 CLI 旗標：1341匹配器值對應於觸發 hook 的 CLI 旗標：
1342 1342
1345| `init` | `claude --init-only` 或 `claude -p --init` |1345| `init` | `claude --init-only` 或 `claude -p --init` |
1346| `maintenance` | `claude -p --maintenance` |1346| `maintenance` | `claude -p --maintenance` |
1347 1347
1348當您執行 `claude --init-only` 時，Claude Code 執行 Setup hooks 和 `startup` 匹配器的 `SessionStart` hooks，然後退出而不啟動對話。1348當您執行 `claude --init-only` 時，Claude Code 執行 Setup hooks 和 `SessionStart` hooks（使用 `startup` 匹配器），然後退出而不啟動對話。
1349 1349
1350當您使用 `-p` 啟動或繼續對話時，您還需要提供提示，作為引數或透過 stdin 管道傳輸。當 `SessionStart` hook 提供 [`initialUserMessage`](#sessionstart-decision-control) 或當您使用 [延遲工具呼叫](#defer-a-tool-call-for-later) 恢復工作階段時，您可以跳過提示。1350當您使用 `-p` 啟動或繼續對話時，您還需要提供提示，作為引數或透過 stdin 管道傳輸。當 `SessionStart` hook 提供 [`initialUserMessage`](#sessionstart-decision-control) 或當您使用 [延遲工具呼叫](#defer-a-tool-call-for-later) 恢復工作階段時，您可以跳過提示。
1351 1351
1352成功時，`--init-only` 不會列印任何內容到終端。若要確認 hooks 已執行，請使用 `claude --debug-file <path> --init-only` 啟動，將 `<path>` 替換為日誌檔案位置，並檢查日誌中的 Setup 和 SessionStart hook 項目。1352成功時，`--init-only` 不會列印任何內容到終端。若要確認 hooks 已執行，請使用 `claude --debug-file <path> --init-only` 啟動，將 `<path>` 替換為日誌檔案位置，並檢查日誌中的 Setup 和 SessionStart hook 項目。
1353 1353
1354由於 Setup 不會在每次啟動時觸發，需要安裝相依性的外掛無法僅依賴 Setup。實用的模式是在首次使用時檢查相依性，如果缺少則安裝，例如測試 `${CLAUDE_PLUGIN_DATA}/node_modules` 的 hook 或 skill，如果不存在則執行 `npm install`。請參閱 [持久資料目錄](/docs/zh-TW/plugins-reference#persistent-data-directory)，了解儲存已安裝相依性的位置。如果您透過市場發佈外掛，您可能不需要此模式：Claude Code [在快取外掛時自動安裝符合條件的 Node.js 套件相依性](/docs/zh-TW/plugins-reference#node-js-package-dependencies)。1354由於 Setup 不會在每次啟動時觸發，需要安裝相依性的外掛無法僅依賴 Setup。實用的模式是在首次使用時檢查相依性，如果缺少則安裝，例如測試 `${CLAUDE_PLUGIN_DATA}/node_modules` 的 hook 或 skill，如果不存在則執行 `npm install`。請參閱 [持久資料目錄](/docs/zh-TW/plugins-reference#persistent-data-directory)，了解在何處儲存已安裝的相依性。如果您透過市場發佈外掛，您可能不需要此模式：Claude Code [在快取外掛時自動安裝符合條件的 Node.js 套件相依性](/docs/zh-TW/plugins-reference#node-js-package-dependencies)。
1355 1355
1356<h4 id="setup-input">1356<h4 id="setup-input">
1357 Setup 輸入1357 Setup 輸入
1358</h4>1358</h4>
1359 1359
1360除了 [常見輸入欄位](#common-input-fields) 外，Setup hooks 還會接收設定為 `"init"` 或 `"maintenance"` 的 `trigger` 欄位：1360除了 [常見輸入欄位](#common-input-fields) 外，Setup hooks 接收設定為 `"init"` 或 `"maintenance"` 的 `trigger` 欄位：
1361 1361
1362```json theme={null}1362```json theme={null}
1363{1363{
1381 InstructionsLoaded1381 InstructionsLoaded
1382</h3>1382</h3>
1383 1383
1384在載入 `CLAUDE.md` 或 `.claude/rules/*.md` 檔案到背景資訊時觸發。此事件在工作階段啟動時對於急切載入的檔案觸發，稍後在檔案被延遲載入時再次觸發，例如當 Claude 存取包含巢狀 `CLAUDE.md` 的子目錄或當具有 `paths:` frontmatter 的條件規則匹配時。Hook 不支援阻止或決策控制。它以非同步方式執行以用於可觀測性目的。1384在載入 `CLAUDE.md` 或 `.claude/rules/*.md` 檔案到背景資訊時觸發。此事件在工作階段啟動時對於急切載入的檔案觸發，稍後在檔案被延遲載入時再次觸發，例如當 Claude 存取包含巢狀 `CLAUDE.md` 的子目錄或當具有 `paths:` frontmatter 的條件規則匹配時。Hook 不支援阻止或決策控制。它以非同步方式執行，用於可觀測性目的。
1385 1385
1386此事件在 Claude [直接透過 **Project instructions** 設定讀取 `AGENTS.md`](/docs/zh-TW/memory#agents-md) 時不觸發。當 `CLAUDE.md` 匯入您的 `AGENTS.md` 時它會觸發，其中 `load_reason` 設定為 `include`（如同任何其他匯入的檔案），以及當 `CLAUDE.md` 是它的符號連結時，作為正常 `CLAUDE.md` 載入。1386當 Claude [直接透過 **Project instructions** 設定讀取 `AGENTS.md`](/docs/zh-TW/memory#agents-md) 時，此事件不會觸發。當 `CLAUDE.md` 匯入您的 `AGENTS.md` 時會觸發，`load_reason` 設定為 `include`（如同任何其他匯入的檔案），以及當 `CLAUDE.md` 是它的符號連結時，作為正常的 `CLAUDE.md` 載入。
1387 1387
1388匹配器針對 `load_reason` 執行。例如，使用 `"matcher": "session_start"` 僅對工作階段啟動時載入的檔案觸發，或使用 `"matcher": "path_glob_match|nested_traversal"` 僅對延遲載入觸發。1388匹配器針對 `load_reason` 執行。例如，使用 `"matcher": "session_start"` 僅對在工作階段啟動時載入的檔案觸發，或 `"matcher": "path_glob_match|nested_traversal"` 僅對延遲載入觸發。
1389 1389
1390<h4 id="instructionsloaded-input">1390<h4 id="instructionsloaded-input">
1391 InstructionsLoaded 輸入1391 InstructionsLoaded 輸入
1392</h4>1392</h4>
1393 1393
1394除了 [常見輸入欄位](#common-input-fields) 外，InstructionsLoaded hooks 還會接收這些欄位：1394除了 [常見輸入欄位](#common-input-fields) 外，InstructionsLoaded hooks 接收這些欄位：
1395 1395
1396| 欄位 | 描述 |1396| 欄位 | 描述 |
1397| :------------------ | :-------------------------------------------------------------------------------------------------------------------------- |1397| :------------------ | :--------------------------------------------------------------------------------------------------------------------------- |
1398| `file_path` | 已載入的指令檔案的絕對路徑 |1398| `file_path` | 已載入的指示檔案的絕對路徑 |
1399| `memory_type` | 檔案的範圍：`"User"`、`"Project"`、`"Local"` 或 `"Managed"` |1399| `memory_type` | 檔案的範圍：`"User"`、`"Project"`、`"Local"` 或 `"Managed"` |
1400| `load_reason` | 檔案載入的原因：`"session_start"`、`"nested_traversal"`、`"path_glob_match"`、`"include"` 或 `"compact"`。`"compact"` 值在壓縮事件後重新載入指令檔案時觸發 |1400| `load_reason` | 檔案被載入的原因：`"session_start"`、`"nested_traversal"`、`"path_glob_match"`、`"include"` 或 `"compact"`。`"compact"` 值在壓縮事件後重新載入指示檔案時觸發 |
1401| `globs` | 檔案 `paths:` frontmatter 中的路徑 glob 模式（如果有）。僅對 `path_glob_match` 載入出現 |1401| `globs` | 檔案 `paths:` frontmatter 中的路徑 glob 模式（如果有）。僅對 `path_glob_match` 載入出現 |
1402| `trigger_file_path` | 觸發此載入的檔案的路徑，用於延遲載入 |1402| `trigger_file_path` | 觸發此載入的檔案的路徑，用於延遲載入 |
1403| `parent_file_path` | 包含此檔案的父指令檔案的路徑，用於 `include` 載入 |1403| `parent_file_path` | 包含此檔案的父指示檔案的路徑，用於 `include` 載入 |
1404 1404
1405```json theme={null}1405```json theme={null}
1406{1406{
1418 InstructionsLoaded 決策控制1418 InstructionsLoaded 決策控制
1419</h4>1419</h4>
1420 1420
1421InstructionsLoaded hooks 沒有決策控制。它們無法阻止或修改指令載入。Claude Code 捨棄它們的 [JSON 輸出欄位](#json-output)，例如 `systemMessage` 和 `continue`。使用此事件進行稽核日誌、合規性追蹤或可觀測性。1421InstructionsLoaded hooks 沒有決策控制。它們無法阻止或修改指示載入。Claude Code 捨棄它們的 [JSON 輸出欄位](#json-output)，例如 `systemMessage` 和 `continue`。使用此事件進行稽核日誌、合規性追蹤或可觀測性。
1422 1422
1423<h3 id="userpromptsubmit">1423<h3 id="userpromptsubmit">
1424 UserPromptSubmit1424 UserPromptSubmit
1425</h3>1425</h3>
1426 1426
1427在使用者提交提示時執行，在 Claude 處理之前。這允許您根據提示/對話新增額外背景資訊、驗證提示或阻止某些類型的提示。1427在使用者提交提示時執行，在 Claude 處理它之前。這允許您根據提示/對話新增額外背景資訊、驗證提示或阻止某些類型的提示。
1428 1428
1429`UserPromptSubmit` hooks 對 `command`、`http` 和 `mcp_tool` 類型的預設逾時為 30 秒，比大多數其他事件上這些類型的 600 秒預設值更短。因為此 hook 在每個提示之前執行並阻止模型處理直到完成，卡住的 hook 會停滯工作階段。如果您的 hook 需要更多時間，請在 hook 項目中設定 `timeout` 欄位。1429`UserPromptSubmit` hooks 對 `command`、`http` 和 `mcp_tool` 類型的預設逾時為 30 秒，比大多數其他事件上這些類型的 600 秒預設值更短。由於此 hook 在每個提示之前執行並阻止模型處理直到完成，卡住的 hook 會停滯工作階段。如果您的 hook 需要更多時間，請在 hook 項目中設定 `timeout` 欄位。
1430 1430
1431除了使用 [`async: true`](#run-hooks-in-the-background) 執行的命令 hook 外，達到其逾時的 `UserPromptSubmit` 命令、HTTP 或 MCP tool hook 會被取消，其輸出（包括任何 `additionalContext`）會被捨棄。提示仍會到達 Claude 而不會有該背景資訊。文字記錄顯示一個通知，命名 hook、觸發的逾時以及輸出已被捨棄。1431除了您使用 [`async: true`](#run-hooks-in-the-background) 執行的命令 hook 外，達到其逾時的 `UserPromptSubmit` 命令、HTTP 或 MCP tool hook 會被取消，其輸出（包括任何 `additionalContext`）會被捨棄。提示仍會到達 Claude，但沒有該背景資訊。文字記錄顯示一個通知，命名 hook、觸發的逾時以及輸出被捨棄。
1432 1432
1433在 `UserPromptSubmit` 上達到其逾時的 [Agent SDK 回呼 hook](/docs/zh-TW/agent-sdk/hooks) 會用命名 hook 和逾時的訊息阻止提示，因為該處的回呼可能充當必須不失敗開放的原則閘道。工作階段繼續。在 v2.1.208 之前，該事件上的回呼逾時以執行錯誤結束回合。1433在 `UserPromptSubmit` 上達到其逾時的 [Agent SDK 回呼 hook](/docs/zh-TW/agent-sdk/hooks) 會用命名 hook 和逾時的訊息阻止提示，因為該處的回呼可能充當必須不失敗開放的原則閘道。工作階段繼續。在 v2.1.208 之前，該事件上的回呼逾時以執行錯誤結束回合。
1434 1434
1436 UserPromptSubmit 輸入1436 UserPromptSubmit 輸入
1437</h4>1437</h4>
1438 1438
1439除了 [常見輸入欄位](#common-input-fields) 外，UserPromptSubmit hooks 還會接收包含使用者提交的文字的 `prompt` 欄位。1439除了 [常見輸入欄位](#common-input-fields) 外，UserPromptSubmit hooks 接收包含使用者提交的文字的 `prompt` 欄位。折疊為 `[Pasted text #N]` 佔位符的貼上內容會在原位展開。在 Claude Code [為 Claude 標記貼上文字](/docs/zh-TW/terminal-config#how-claude-treats-pasted-text) 的工作階段中，該展開內容位於 `<pasted_content id="…">` 行和 `</pasted_content id="…">` 行之間，因此如果您的 hook 解析提示，請考慮這些行。
1440 1440
1441```json theme={null}1441```json theme={null}
1442{1442{
1457 1457
1458有兩種方式可以在退出代碼 0 上新增背景資訊到對話：1458有兩種方式可以在退出代碼 0 上新增背景資訊到對話：
1459 1459
1460* **純文字 stdout**：Claude Code 將其 [視為純文字](#exit-code-0) 的 stdout 新增到 Claude 的背景資訊1460* **純文字 stdout**：Claude Code 將它 [視為純文字](#exit-code-0) 的 stdout 新增到 Claude 的背景資訊
1461* **JSON 搭配 `additionalContext`**：使用下面的 JSON 格式以獲得更多控制。`additionalContext` 欄位作為背景資訊新增1461* **JSON 搭配 `additionalContext`**：使用下面的 JSON 格式以獲得更多控制。`additionalContext` 欄位作為背景資訊新增
1462 1462
1463兩個通道都不會產生可見的文字記錄項目。純文字和 `additionalContext` 值各自作為以 hook 名稱開頭的系統提醒注入；Claude 讀取兩者。若要確認傳遞，請檢查 [偵錯日誌](#debug-hooks)。1463兩個通道都不會產生可見的文字記錄項目。純 stdout 和 `additionalContext` 值各自作為以 hook 名稱開頭的系統提醒注入；Claude 讀取兩者。若要確認傳遞，請檢查 [debug log](#debug-hooks)。
1464 1464
1465若要阻止提示，請返回一個 JSON 物件，其中 `decision` 設定為 `"block"`：1465若要阻止提示，傳回一個 JSON 物件，其 `decision` 設定為 `"block"`：
1466 1466
1467| 欄位 | 描述 |1467| 欄位 | 描述 |
1468| :----------------------- | :------------------------------------------------------------------------ |1468| :----------------------- | :------------------------------------------------------------------------ |
1469| `decision` | `"block"` 防止提示被處理並從背景資訊中清除。省略以允許提示繼續 |1469| `decision` | `"block"` 防止提示被處理並從背景資訊中清除它。省略以允許提示繼續 |
1470| `reason` | 當 `decision` 為 `"block"` 時顯示給使用者。不新增到背景資訊 |1470| `reason` | 當 `decision` 為 `"block"` 時顯示給使用者。不新增到背景資訊 |
1471| `additionalContext` | 與提交的提示一起新增到 Claude 背景資訊的字串。請參閱 [為 Claude 新增背景資訊](#add-context-for-claude) |1471| `additionalContext` | 與提交的提示一起新增到 Claude 背景資訊的字串。請參閱 [為 Claude 新增背景資訊](#add-context-for-claude) |
1472| `sessionTitle` | 設定工作階段標題。用於根據提示內容自動命名工作階段 |1472| `sessionTitle` | 設定工作階段標題。用於根據提示內容自動命名工作階段 |
1473| `suppressOriginalPrompt` | 當 `decision` 為 `"block"` 時，如果為 `true`，則從顯示給使用者的阻止訊息中省略原始提示文字 |1473| `suppressOriginalPrompt` | 當 `decision` 為 `"block"` 時，如果為 `true`，則從顯示給使用者的阻止訊息中省略原始提示文字 |
1474 1474
1475透過退出 2 阻止的 hook 路由方式與 `reason` 相同：阻止訊息向使用者顯示 stderr 文字，且不新增到背景資訊。1475透過退出 2 阻止的 hook 以與 `reason` 相同的方式路由：阻止訊息向使用者顯示 stderr 文字，它不會新增到背景資訊。
1476 1476
1477```json theme={null}1477```json theme={null}
1478{1478{
1490 UserPromptExpansion1490 UserPromptExpansion
1491</h3>1491</h3>
1492 1492
1493在使用者輸入的命令擴展為到達 Claude 之前的提示時執行。使用此來阻止特定命令的直接呼叫、為特定 skill 注入背景資訊，或記錄使用者呼叫的命令。例如，匹配 `deploy` 的 hook 可以阻止 `/deploy`，除非存在核准檔案，或匹配審查 skill 的 hook 可以將團隊的審查檢查清單附加為 `additionalContext`。1493在使用者輸入的命令擴展為提示之前執行，然後到達 Claude。使用此來阻止特定命令的直接呼叫、為特定 skill 注入背景資訊，或記錄使用者呼叫的命令。例如，匹配 `deploy` 的 hook 可以阻止 `/deploy`，除非存在核准檔案，或匹配審查 skill 的 hook 可以將團隊的審查檢查清單附加為 `additionalContext`。
1494 1494
1495此事件涵蓋 `PreToolUse` 不涵蓋的路徑：匹配 `Skill` 工具的 `PreToolUse` hook 僅在 Claude 呼叫工具時觸發，但直接輸入 `/skillname` 會繞過 `PreToolUse`。`UserPromptExpansion` 在該直接路徑上觸發。1495此事件涵蓋 `PreToolUse` 不涵蓋的路徑：匹配 `Skill` 工具的 `PreToolUse` hook 僅在 Claude 呼叫工具時觸發，但直接輸入 `/skillname` 會繞過 `PreToolUse`。`UserPromptExpansion` 在該直接路徑上觸發。
1496 1496
1500 UserPromptExpansion 輸入1500 UserPromptExpansion 輸入
1501</h4>1501</h4>
1502 1502
1503除了 [常見輸入欄位](#common-input-fields) 外，UserPromptExpansion hooks 還會接收 `expansion_type`、`command_name`、`command_args`、`command_source` 和原始 `prompt` 字串。`expansion_type` 欄位對於 skill 和自訂命令為 `slash_command`，或對於 MCP 伺服器提示為 `mcp_prompt`。1503除了 [常見輸入欄位](#common-input-fields) 外，UserPromptExpansion hooks 接收 `expansion_type`、`command_name`、`command_args`、`command_source` 和原始 `prompt` 字串。`expansion_type` 欄位對於 skill 和自訂命令為 `slash_command`，或對於 MCP 伺服器提示為 `mcp_prompt`。
1504 1504
1505```json theme={null}1505```json theme={null}
1506{1506{
1527| :------------------ | :------------------------------------------------------------------------ |1527| :------------------ | :------------------------------------------------------------------------ |
1528| `decision` | `"block"` 防止命令擴展。省略以允許它繼續 |1528| `decision` | `"block"` 防止命令擴展。省略以允許它繼續 |
1529| `reason` | 當 `decision` 為 `"block"` 時顯示給使用者 |1529| `reason` | 當 `decision` 為 `"block"` 時顯示給使用者 |
1530| `additionalContext` | 與擴展的提示一起新增到 Claude 背景資訊的字串。請參閱 [為 Claude 新增背景資訊](#add-context-for-claude) |1530| `additionalContext` | 與展開的提示一起新增到 Claude 背景資訊的字串。請參閱 [為 Claude 新增背景資訊](#add-context-for-claude) |
1531 1531
1532透過退出 2 阻止的 hook 路由方式與 `reason` 相同：阻止訊息向使用者顯示 stderr 文字。1532透過退出 2 阻止的 hook 以與 `reason` 相同的方式路由：阻止訊息向使用者顯示 stderr 文字。
1533 1533
1534```json theme={null}1534```json theme={null}
1535{1535{
1546 MessageDisplay1546 MessageDisplay
1547</h3>1547</h3>
1548 1548
1549在助手訊息流向螢幕時執行。Claude Code 分批顯示訊息：每次一批新完成的行準備好呈現時，hook 執行一次，其中包含這些行，Claude Code 呈現 hook 的替換文字代替它們。長訊息會產生多個呼叫；短訊息可能只產生一個。1549在助手訊息流向螢幕時執行。Claude Code 分批顯示訊息：每次一批新完成的行準備好呈現時，hook 執行一次，該批行，Claude Code 在其位置呈現 hook 的替換文字。長訊息會產生多個呼叫；短訊息可能只產生一個。
1550 1550
1551使用 MessageDisplay 來：1551使用 MessageDisplay 來：
1552 1552
1554* 轉換 Agent SDK 應用程式向其使用者顯示的文字1554* 轉換 Agent SDK 應用程式向其使用者顯示的文字
1555* 從 Claude 的回應中編輯 API 金鑰或內部主機名稱1555* 從 Claude 的回應中編輯 API 金鑰或內部主機名稱
1556 1556
1557Claude Code 保留每個批次直到您的 hook 返回，因此請保持 hook 快速。如果 hook 失敗或逾時，Claude Code 顯示原始文字。此事件的預設逾時為 10 秒；如果您的 hook 需要更多時間，請在 hook 項目中設定 `timeout` 欄位。1557Claude Code 保持每個批次，直到您的 hook 傳回，因此請保持 hook 快速。如果 hook 失敗或逾時，Claude Code 顯示原始文字。此事件的預設逾時為 10 秒；如果您的 hook 需要更多時間，請在 hook 項目中設定 `timeout` 欄位。
1558 1558
1559MessageDisplay 僅用於顯示：替換文字僅更改螢幕上呈現的內容。文字記錄和 Claude 看到的內容保持原始文字，因此 Claude 永遠看不到替換，詳細模式顯示原始文字。Hook 僅接收助手訊息文字，因此工具結果和您輸入的文字呈現不變。1559MessageDisplay 僅用於顯示：替換文字僅更改螢幕上呈現的內容。文字記錄和 Claude 看到的內容保持原始文字，因此 Claude 永遠看不到替換，詳細模式顯示原始文字。Hook 僅接收助手訊息文字，因此工具結果和您輸入的文字呈現不變。
1560 1560
1561MessageDisplay 不支援匹配器，對每個流向文字的助手訊息觸發；沒有文字的訊息（例如僅工具呼叫回應）不觸發它。1561MessageDisplay 不支援匹配器，對每個流向文字的助手訊息觸發；沒有文字的訊息（例如僅工具呼叫回應）不會觸發它。
1562 1562
1563在非互動執行中，包括 Agent SDK 查詢和 `claude -p`，MessageDisplay 每個助手訊息執行一次而不是每批行執行一次。單個呼叫在訊息完成後到達並攜帶完整訊息文字：`index` 為 `0`、`final` 為 `true`，`delta` 保留整個訊息。為每個訊息收集 `delta` 文字的 hook 在兩種模式中接收相同的總文字。1563在非互動執行中，包括 Agent SDK 查詢和 `claude -p`，MessageDisplay 每個助手訊息執行一次，而不是每批行執行一次。單個呼叫在訊息完成後到達，並攜帶完整訊息文字：`index` 為 `0`，`final` 為 `true`，`delta` 保持整個訊息。為每個訊息收集 `delta` 文字的 hook 在兩種模式中接收相同的總文字。
1564 1564
1565<h4 id="messagedisplay-input">1565<h4 id="messagedisplay-input">
1566 MessageDisplay 輸入1566 MessageDisplay 輸入
1567</h4>1567</h4>
1568 1568
1569除了 [常見輸入欄位](#common-input-fields) 外，MessageDisplay hooks 還會接收回合和訊息的識別碼、此呼叫在訊息中的位置，以及 `delta` 中的新文字。批次邊界取決於文字流的方式，因此使用 `index` 和 `final` 追蹤訊息的進度，而不是期望行以特定方式分組。1569除了 [常見輸入欄位](#common-input-fields) 外，MessageDisplay hooks 接收回合和訊息的識別碼、此呼叫在訊息中的位置，以及 `delta` 中的新文字。批次邊界取決於文字流的方式，因此使用 `index` 和 `final` 追蹤訊息的進度，而不是期望行以特定方式分組。
1570 1570
1571| 欄位 | 描述 |1571| 欄位 | 描述 |
1572| :----------- | :---------------------------------------------------------------------------------------------------------------------------------------------------- |1572| :----------- | :---------------------------------------------------------------------------------------------------------------------------------------------------- |
1573| `turn_id` | 目前回合的 UUID |1573| `turn_id` | 目前回合的 UUID |
1574| `message_id` | 正在顯示的助手訊息的 UUID。在同一訊息的每個批次中穩定。這不是 API `msg_…` id，因此無法與文字記錄訊息 id 相關聯 |1574| `message_id` | 正在顯示的助手訊息的 UUID。在同一訊息的每個批次中穩定。這不是 API `msg_…` id，因此無法與文字記錄訊息 ids 相關聯 |
1575| `index` | 訊息內此批次的零基索引 |1575| `index` | 此批次在訊息中的零基索引 |
1576| `final` | 在訊息的最後一個批次上為 `true`。每個訊息恰好有一個最終批次 |1576| `final` | 在訊息的最後一個批次上為 `true`。每個訊息恰好有一個最終批次 |
1577| `delta` | 自上一個批次以來新完成的行，包括終止換行符。始終是完整行，除了最終批次可能在行中結束。在互動執行中，當訊息以換行符結束時，最終批次的 delta 為空，因此將 `final` 而不是非空 delta 視為訊息結束信號。在 Agent SDK 和 `claude -p` 執行中，單個呼叫攜帶整個訊息 |1577| `delta` | 自上一個批次以來新完成的行，包括終止換行符。始終是完整行，除了最終批次可能在行中結束。在互動執行中，當訊息以換行符結束時，最終批次的 delta 為空，因此將 `final` 而不是非空 delta 視為訊息結束信號。在 Agent SDK 和 `claude -p` 執行中，單個呼叫攜帶整個訊息 |
1578 1578
1594 MessageDisplay 輸出1594 MessageDisplay 輸出
1595</h4>1595</h4>
1596 1596
1597除了所有 hooks 可用的 [JSON 輸出欄位](#json-output) 外，MessageDisplay hooks 可以返回 `displayContent` 以替換螢幕上的 delta：1597除了 [所有 hooks 可用的 JSON 輸出欄位](#json-output) 外，MessageDisplay hooks 可以傳回 `displayContent` 以在螢幕上替換 delta：
1598 1598
1599| 欄位 | 描述 |1599| 欄位 | 描述 |
1600| :--------------- | :----------------------- |1600| :--------------- | :------------------------ |
1601| `displayContent` | 顯示代替 delta 的文字。省略以顯示原始文字 |1601| `displayContent` | 顯示以取代 delta 的文字。省略以顯示原始文字 |
1602 1602
1603MessageDisplay hooks 沒有決策控制。它們無法阻止訊息或更改文字記錄中儲存或發送給 Claude 的內容。Claude Code 作用於它們的 JSON 輸出中的 `displayContent` 並捨棄 `systemMessage` 和 `continue`。1603MessageDisplay hooks 沒有決策控制。它們無法阻止訊息或更改文字記錄中儲存或傳送給 Claude 的內容。Claude Code 從其 JSON 輸出作用於 `displayContent` 並捨棄 `systemMessage` 和 `continue`。
1604 1604
1605此範例從 Claude 的回應中去除 markdown 格式以獲得純文字顯示。指令碼從 stdin 讀取每個批次，從 `delta` 中移除粗體標記和內聯代碼反引號，並將結果作為 `displayContent` 返回。1605此範例從 Claude 的回應中去除 markdown 格式以獲得純文字顯示。指令碼從 stdin 讀取每個批次，從 `delta` 移除粗體標記和內聯程式碼反引號，並將結果傳回為 `displayContent`。
1606 1606
1607<Tabs>1607<Tabs>
1608 <Tab title="macOS/Linux">1608 <Tab title="macOS/Linux">
1626 }1626 }
1627 ```1627 ```
1628 1628
1629 將此指令碼儲存到您專案中的 `.claude/hooks/plain-display.sh` 並使用 `chmod +x` 使其可執行：1629 將此指令碼儲存到您的專案中的 `.claude/hooks/plain-display.sh`，並使用 `chmod +x` 使其可執行：
1630 1630
1631 ```bash theme={null}1631 ```bash theme={null}
1632 #!/bin/bash1632 #!/bin/bash
1663 1663
1664 `-NoProfile` 旗標跳過載入您的 PowerShell 設定檔，以便 hook 快速啟動，`-ExecutionPolicy Bypass` 讓 PowerShell 執行本機指令碼檔案。1664 `-NoProfile` 旗標跳過載入您的 PowerShell 設定檔，以便 hook 快速啟動，`-ExecutionPolicy Bypass` 讓 PowerShell 執行本機指令碼檔案。
1665 1665
1666 將此指令碼儲存到您專案中的 `.claude/hooks/plain-display.ps1`：1666 將此指令碼儲存到您的專案中的 `.claude/hooks/plain-display.ps1`：
1667 1667
1668 ```powershell theme={null}1668 ```powershell theme={null}
1669 $batch = [Console]::In.ReadToEnd() | ConvertFrom-Json1669 $batch = [Console]::In.ReadToEnd() | ConvertFrom-Json
1678 </Tab>1678 </Tab>
1679</Tabs>1679</Tabs>
1680 1680
1681沒有 markdown 的批次通過不變。如果指令碼失敗，例如因為 `jq` 缺失，Claude Code 顯示原始文字並僅在 [偵錯輸出](#debug-hooks) 中記錄失敗，而不是在工作階段中。1681沒有 markdown 的批次會通過不變。如果指令碼失敗，例如因為 `jq` 遺失，Claude Code 顯示原始文字，並僅在 [debug output](#debug-hooks) 中註記失敗，而不是在工作階段中。
1682 1682
1683<h3 id="pretooluse">1683<h3 id="pretooluse">
1684 PreToolUse1684 PreToolUse
1686 1686
1687在 Claude 建立工具參數之後、處理工具呼叫之前執行。在除 `EndConversation` 外的任何工具名稱上匹配：內建工具，例如 `Bash`、`PowerShell`、`Edit`、`Write`、`Read`、`Glob`、`Grep`、`Agent`、`Workflow`、`WebFetch`、`WebSearch`、`AskUserQuestion` 和 `ExitPlanMode`，以及任何 [MCP 工具名稱](#match-mcp-tools)。1687在 Claude 建立工具參數之後、處理工具呼叫之前執行。在除 `EndConversation` 外的任何工具名稱上匹配：內建工具，例如 `Bash`、`PowerShell`、`Edit`、`Write`、`Read`、`Glob`、`Grep`、`Agent`、`Workflow`、`WebFetch`、`WebSearch`、`AskUserQuestion` 和 `ExitPlanMode`，以及任何 [MCP 工具名稱](#match-mcp-tools)。
1688 1688
1689若要在磁碟上的特定檔案變更時執行 hook，無論什麼寫入它，請改用 [FileChanged](#filechanged) 而不是按名稱匹配檔案編輯工具。與 PreToolUse 不同，Claude Code 在變更後執行 FileChanged hooks，它們沒有決策控制，因此無法阻止寫入。1689若要在特定檔案在磁碟上變更時執行 hook，無論什麼寫入它，請使用 [FileChanged](#filechanged) 而不是按名稱匹配檔案編輯工具。與 PreToolUse 不同，Claude Code 在變更後執行 FileChanged hooks，它們沒有決策控制，因此無法阻止寫入。
1690 1690
1691<Warning>1691<Warning>
1692 PreToolUse 僅在 Claude 呼叫工具時執行。您在提示中 [使用 `@` 參考的檔案](/docs/zh-TW/common-workflows#reference-files-and-directories) 會被新增而不進行任何工具呼叫：Claude Code 在建立提示時插入其內容，因此沒有 PreToolUse hook 對它們觸發，包括匹配 `Read` 的 hooks。若要阻止特定路徑的 `@` 參考，請改用 [`Read` 拒絕規則](/docs/zh-TW/permissions#read-and-edit)。1692 PreToolUse 僅在 Claude 呼叫工具時執行。您 [在提示中使用 `@` 參考的檔案](/docs/zh-TW/common-workflows#reference-files-and-directories) 會被新增而不進行任何工具呼叫：Claude Code 在建立提示時插入其內容，因此沒有 PreToolUse hook 對它們觸發，包括匹配 `Read` 的 hooks。若要阻止特定路徑的 `@` 參考，請改用 [`Read` 拒絕規則](/docs/zh-TW/permissions#read-and-edit)。
1693 1693
1694 PreToolUse 也不對 [`EndConversation`](/docs/zh-TW/tools-reference#endconversation-tool-behavior) 觸發。1694 PreToolUse 也不會對 [`EndConversation`](/docs/zh-TW/tools-reference#endconversation-tool-behavior) 觸發。
1695</Warning>1695</Warning>
1696 1696
1697使用 [PreToolUse 決策控制](#pretooluse-decision-control) 來允許、拒絕、詢問或延遲工具呼叫。1697使用 [PreToolUse 決策控制](#pretooluse-decision-control) 來允許、拒絕、詢問或延遲工具呼叫。
1698 1698
1699在 `PreToolUse` 上超過其逾時的 [Agent SDK 回呼 hook](/docs/zh-TW/agent-sdk/hooks) 會阻止工具呼叫，Claude 接收命名逾時的錯誤結果。另一個 hook 返回的明確拒絕仍然優先。1699在 `PreToolUse` 上超過其逾時的 [Agent SDK 回呼 hook](/docs/zh-TW/agent-sdk/hooks) 會阻止工具呼叫，Claude 接收命名逾時的錯誤結果。另一個 hook 傳回的明確拒絕仍然優先。
1700 1700
1701<h4 id="pretooluse-input">1701<h4 id="pretooluse-input">
1702 PreToolUse 輸入1702 PreToolUse 輸入
1703</h4>1703</h4>
1704 1704
1705除了 [常見輸入欄位](#common-input-fields) 外，PreToolUse hooks 還會接收 `tool_name`、`tool_input` 和 `tool_use_id`。1705除了 [常見輸入欄位](#common-input-fields) 外，PreToolUse hooks 接收 `tool_name`、`tool_input` 和 `tool_use_id`。
1706 1706
1707對於 [MCP 工具](#match-mcp-tools)，輸入也攜帶 `mcp_server`，一個具有伺服器 `name` 和 `source` 的物件，說明伺服器定義來自何處。`source` 值包括 `plugin`、`sdk` 和設定範圍，例如 `user` 和 `project`。Agent SDK 參考中的 [`McpServerProvenance`](/docs/zh-TW/agent-sdk/typescript#mcpserverprovenance) 列出它們全部並說明如何對待您不認識的。基於 `source` 而不是 `name` 或 `mcp__<server>__` 工具名稱前綴進行信任決策。`mcp_server` 欄位需要 Claude Code v2.1.274 或更新版本。1707對於 [MCP 工具](#match-mcp-tools)，輸入也攜帶 `mcp_server`，一個具有伺服器 `name` 和 `source` 的物件，說明伺服器定義的來源。`source` 值包括 `plugin`、`sdk` 和配置範圍，例如 `user` 和 `project`。[Agent SDK 參考中的 `McpServerProvenance`](/docs/zh-TW/agent-sdk/typescript#mcpserverprovenance) 列出它們全部並說明如何處理您不認識的。基於 `source` 而不是 `name` 或 `mcp__<server>__` 工具名稱前綴做出信任決定。`mcp_server` 欄位需要 Claude Code v2.1.274 或更新版本。
1708 1708
1709對於檔案工具 `Write`、`Edit` 和 `Read`，`tool_input.file_path` 始終是絕對的：1709對於檔案工具 `Write`、`Edit` 和 `Read`，`tool_input.file_path` 始終是絕對的：
1710 1710
1711* Claude Code 在 hooks 執行之前擴展 `~` 和相對路徑，因此匹配路徑的 hook 無法透過 `~` 或相同路徑的相對拼寫繞過1711* Claude Code 在 hooks 執行之前展開 `~` 和相對路徑，因此匹配路徑的 hook 無法透過 `~` 或相同路徑的相對拼寫繞過
1712* 在 Windows 上，路徑到達時使用反斜線分隔符，即使您的 hook 在 Git Bash 下執行，其中 `$PWD` 看起來像 `/c/project`1712* 在 Windows 上，路徑到達時使用反斜線分隔符，即使您的 hook 在 Git Bash 下執行，其中 `$PWD` 看起來像 `/c/project`
1713* 使用正斜線編寫的比較，例如 `/src/` 檢查，永遠不會匹配反斜線路徑，工具呼叫會如同 hook 沒有要阻止的內容一樣進行1713* 使用正斜線編寫的比較，例如 `/src/` 檢查，永遠不會匹配反斜線路徑，工具呼叫會如同 hook 沒有要阻止的東西一樣進行
1714* 在比較前規範化分隔符：Bash 中的 `FILE_PATH="${FILE_PATH//\\//}"`，或 Python 中的 `file_path.replace("\\", "/")`，然後匹配路徑段，例如 `/src/`，而不是使用 `^` 錨定，因為路徑是絕對的1714* 在比較前正規化分隔符：Bash 中的 `FILE_PATH="${FILE_PATH//\\//}"` 或 Python 中的 `file_path.replace("\\", "/")`，然後匹配路徑段，例如 `/src/`，而不是使用 `^` 錨定，因為路徑是絕對的
1715 1715
1716Windows 上的 `Write` 呼叫傳遞：1716Windows 上的 `Write` 呼叫傳遞：
1717 1717
1738執行 shell 命令。1738執行 shell 命令。
1739 1739
1740| 欄位 | 類型 | 範例 | 描述 |1740| 欄位 | 類型 | 範例 | 描述 |
1741| :------------------ | :------ | :----------------- | :--------------------------------------------------------------------------- |1741| :------------------ | :------ | :----------------- | :---------------------------------------------------------------------------- |
1742| `command` | string | `"npm test"` | 要執行的 shell 命令 |1742| `command` | string | `"npm test"` | 要執行的 shell 命令 |
1743| `description` | string | `"Run test suite"` | 命令執行內容的可選描述 |1743| `description` | string | `"Run test suite"` | 命令執行內容的可選描述 |
1744| `timeout` | number | `120000` | 可選逾時（毫秒）。超過 [最大值](/docs/zh-TW/tools-reference#bash-tool-behavior) 的值會減少到最大值而不是被拒絕 |1744| `timeout` | number | `120000` | 可選逾時（毫秒）。高於 [最大值](/docs/zh-TW/tools-reference#bash-tool-behavior) 的值會減少到最大值，而不是被拒絕 |
1745| `run_in_background` | boolean | `false` | 是否在背景執行命令 |1745| `run_in_background` | boolean | `false` | 是否在背景執行命令 |
1746 1746
1747當 Bash 命令更改 Git 儲存庫中的檔案時，Claude Code 可以記錄變更的內容。當 [`bashEditDiffEnabled`](/docs/zh-TW/settings-reference#basheditdiffenabled) 設定打開記錄時，它在每個權限模式中記錄；該設定的項目說明哪些檔案可以設定它。否則它僅在自動模式和 `bypassPermissions` 模式中記錄，並且僅當 Claude Code 指導 Claude 透過 Bash 編輯檔案時。設定 `bashEditDiffEnabled` 為 `false` 以關閉記錄。背景命令和唯讀命令不攜帶 diff。1747當 Bash 命令更改 Git 儲存庫中的檔案時，Claude Code 可以記錄變更。當 [`bashEditDiffEnabled`](/docs/zh-TW/settings-reference#basheditdiffenabled) 設定開啟記錄時，它在每個權限模式中記錄；該設定的項目說明哪些檔案可以設定它。否則它僅在自動模式和 `bypassPermissions` 模式中記錄，並且僅當 Claude Code 指導 Claude 透過 Bash 編輯檔案時。設定 `bashEditDiffEnabled` 為 `false` 以關閉記錄。背景命令和唯讀命令不攜帶 diff。
1748 1748
1749您的 [PostToolUse hook](#posttooluse) 然後在 `tool_response.bashEditDiff` 中接收變更的檔案。該清單涵蓋命令執行時在儲存庫下變更的內容。Git 忽略的檔案和子模組中的檔案不被列出。需要 Claude Code v2.1.269 或更新版本。1749您的 [PostToolUse hook](#posttooluse) 然後在 `tool_response.bashEditDiff` 中接收變更的檔案。清單涵蓋命令執行時在儲存庫下變更的內容。Git 忽略的檔案和子模組中的檔案不會列出。需要 Claude Code v2.1.269 或更新版本。
1750 1750
1751<Note>1751<Note>
1752 該清單是盡力而為的，處於公開測試版。Claude Code 可能會遺漏變更、包含另一個程序同時變更的檔案，或在其大小限制處停止。欄位形狀可能會變更。使用該清單找到要審查的內容，而不是強制執行原則。1752 清單是盡力而為的，處於公開測試版。Claude Code 可能會遺漏變更、包含另一個程序同時變更的檔案，或在其大小限制處停止。欄位形狀可能會變更。使用清單找到要審查的內容，而不是強制執行原則。
1753</Note>1753</Note>
1754 1754
1755`changedFiles` 和 `files` 列出命令變更的內容；其餘欄位說明該清單的完整性和可靠性。1755`changedFiles` 和 `files` 列出命令變更的內容；其餘欄位說明該清單的完整性和可靠性。
1756 1756
1757| 欄位 | 類型 | 範例 | 描述 |1757| 欄位 | 類型 | 範例 | 描述 |
1758| :------------- | :------ | :------------------------------------------------------ | :------------------------------------------------------------------------ |1758| :------------- | :------ | :------------------------------------------------------ | :----------------------------------------------------------------------- |
1759| `changedFiles` | array | `["/path/to/src/app.ts"]` | 命令變更的檔案的絕對路徑，最多 200 個。每當 `files` 保留 diff 或 `moreFiles` 高於零時出現 |1759| `changedFiles` | array | `["/path/to/src/app.ts"]` | 命令變更的檔案的絕對路徑，最多 200 個。每當 `files` 保持 diff 或 `moreFiles` 高於零時出現 |
1760| `files` | array | `[{"filePath": "/path/to/src/app.ts", "hunks": [...]}]` | 最多 5 個變更檔案的 diffs，用於顯示。對於命令新增或移除的檔案，`created` 或 `deleted` 為 `true` |1760| `files` | array | `[{"filePath": "/path/to/src/app.ts", "hunks": [...]}]` | 最多 5 個變更檔案的 diffs，用於顯示。`created` 或 `deleted` 對於命令新增或移除的檔案為 `true` |
1761| `moreFiles` | number | `2` | 在 `files` 中沒有 diff 的變更檔案計數 |1761| `moreFiles` | number | `2` | 在 `files` 中沒有 diff 的變更檔案計數 |
1762| `unavailable` | boolean | `true` | 當 diff 不完整或無法進行時設定 |1762| `unavailable` | boolean | `true` | 當 diff 不完整或無法取得時設定 |
1763| `skipped` | boolean | `true` | 對於移動工作樹的 Git 命令設定，例如 `git checkout` 或 `git stash`，因此 Claude Code 不進行 diff |1763| `skipped` | boolean | `true` | 對於移動工作樹的 Git 命令設定，例如 `git checkout` 或 `git stash`，因此 Claude Code 不取 diff |
1764| `shared` | boolean | `true` | 當另一個 Bash 工具呼叫（例如子代理的）同時在同一儲存庫中執行時設定，因此某些列出的變更可能是該命令的 |1764| `shared` | boolean | `true` | 當另一個 Bash 工具呼叫（例如子代理的）同時在同一儲存庫中執行時設定，因此某些列出的變更可能是該命令的 |
1765 1765
1766<a id="powershell" />1766<a id="powershell" />
1782 1782
1783在檢查 shell 命令的 hooks 中匹配 `Bash|PowerShell`，以便它們涵蓋兩個工具：1783在檢查 shell 命令的 hooks 中匹配 `Bash|PowerShell`，以便它們涵蓋兩個工具：
1784 1784
1785* 在 Windows 上，只要啟用了 PowerShell 工具，Claude 就會將 PowerShell 視為主要 shell 並透過它路由 shell 命令。1785* 在 Windows 上，無論 PowerShell 工具在何處啟用，Claude 都將 PowerShell 視為主要 shell，並透過它路由 shell 命令。
1786* 在沒有 Git Bash 的 Windows 上，工具會自動啟用，Claude Code 根本不會註冊 Bash 工具。1786* 在沒有 Git Bash 的 Windows 上，工具會自動啟用，Claude Code 根本不會註冊 Bash 工具。
1787* 僅匹配 `Bash` 的 hook 永遠不會在那裡觸發。1787* 僅匹配 `Bash` 的 hook 永遠不會在那裡觸發。
1788 1788
1819| 欄位 | 類型 | 範例 | 描述 |1819| 欄位 | 類型 | 範例 | 描述 |
1820| :---------- | :----- | :-------------------- | :---------- |1820| :---------- | :----- | :-------------------- | :---------- |
1821| `file_path` | string | `"/path/to/file.txt"` | 要讀取的檔案的絕對路徑 |1821| `file_path` | string | `"/path/to/file.txt"` | 要讀取的檔案的絕對路徑 |
1822| `offset` | number | `10` | 可選行號以開始讀取 |1822| `offset` | number | `10` | 可選開始讀取的行號 |
1823| `limit` | number | `50` | 可選要讀取的行數 |1823| `limit` | number | `50` | 可選要讀取的行數 |
1824 1824
1825<h5 id="glob">1825<h5 id="glob">
1830 1830
1831| 欄位 | 類型 | 範例 | 描述 |1831| 欄位 | 類型 | 範例 | 描述 |
1832| :-------- | :----- | :--------------- | :----------------- |1832| :-------- | :----- | :--------------- | :----------------- |
1833| `pattern` | string | `"**/*.ts"` | 要匹配檔案的 glob 模式 |1833| `pattern` | string | `"**/*.ts"` | 要匹配檔案的 Glob 模式 |
1834| `path` | string | `"/path/to/dir"` | 可選要搜尋的目錄。預設為目前工作目錄 |1834| `path` | string | `"/path/to/dir"` | 可選要搜尋的目錄。預設為目前工作目錄 |
1835 1835
1836<h5 id="grep">1836<h5 id="grep">
1884| `subagent_type` | string | `"Explore"` | 要使用的專門代理類型 |1884| `subagent_type` | string | `"Explore"` | 要使用的專門代理類型 |
1885| `model` | string | `"sonnet"` | 可選模型別名以覆寫預設值 |1885| `model` | string | `"sonnet"` | 可選模型別名以覆寫預設值 |
1886 1886
1887當前景 Agent 呼叫完成時，您的 [PostToolUse hook](#posttooluse) 在 `tool_response` 中接收子代理的結果和執行遙測。讀取這些欄位以檢查執行；對於跨子代理的令牌和成本匯總，使用 [令牌和成本計數器](/docs/zh-TW/monitoring-usage#token-counter)，篩選為 `query_source` `"subagent"`，因為 `totalTokens` 和 `usage` 僅涵蓋最終請求：1887當前景 Agent 呼叫完成時，您的 [PostToolUse hook](#posttooluse) 在 `tool_response` 中接收子代理的結果和執行遙測。讀取這些欄位以檢查執行；對於跨子代理的權杖和成本匯總，使用 [權杖和成本計數器](/docs/zh-TW/monitoring-usage#token-counter)，篩選為 `query_source` `"subagent"`，因為 `totalTokens` 和 `usage` 僅涵蓋最終請求：
1888 1888
1889| 欄位 | 類型 | 範例 | 描述 |1889| 欄位 | 類型 | 範例 | 描述 |
1890| :------------------ | :----- | :---------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------- |1890| :------------------ | :----- | :---------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------- |
1892| `agentId` | string | `"a4d2c8f1e0b3a297"` | 子代理執行的識別碼 |1892| `agentId` | string | `"a4d2c8f1e0b3a297"` | 子代理執行的識別碼 |
1893| `content` | array | `[{"type": "text", "text": "Found 12 endpoints..."}]` | 子代理的最終文字區塊，或對於其報告透過 `SubagentHandback` 的子代理，關於該交接的簡短說明代替 |1893| `content` | array | `[{"type": "text", "text": "Found 12 endpoints..."}]` | 子代理的最終文字區塊，或對於其報告透過 `SubagentHandback` 的子代理，關於該交接的簡短說明代替 |
1894| `resolvedModel` | string | `"claude-sonnet-4-5"` | 子代理啟動的模型，可能與請求的模型不同 |1894| `resolvedModel` | string | `"claude-sonnet-4-5"` | 子代理啟動的模型，可能與請求的模型不同 |
1895| `modelsUsed` | array | `["claude-sonnet-4-5", "claude-haiku-4-5"]` | 按順序使用的模型，連續重複摺疊；僅在模型在執行中交換時設定。需要 Claude Code v2.1.212 或更新版本 |1895| `modelsUsed` | array | `["claude-sonnet-4-5", "claude-haiku-4-5"]` | 按順序使用的模型，連續重複折疊；僅在模型在執行中交換時設定。需要 Claude Code v2.1.212 或更新版本 |
1896| `totalTokens` | number | `12450` | 子代理最終 API 請求的令牌計數：輸入、輸出和快取令牌結合。這不是整個執行的總計 |1896| `totalTokens` | number | `12450` | 子代理最終 API 請求的權杖計數：輸入、輸出和快取權杖結合。這不是整個執行的總計 |
1897| `totalDurationMs` | number | `48211` | 子代理執行的掛鐘持續時間 |1897| `totalDurationMs` | number | `48211` | 子代理執行的掛鐘持續時間 |
1898| `totalToolUseCount` | number | `7` | 子代理進行的工具呼叫計數 |1898| `totalToolUseCount` | number | `7` | 子代理進行的工具呼叫計數 |
1899| `usage` | object | `{"input_tokens": 8320, ...}` | 最終 API 請求的每類型令牌細目：`input_tokens`、`output_tokens`、`cache_creation_input_tokens`、`cache_read_input_tokens` |1899| `usage` | object | `{"input_tokens": 8320, ...}` | 最終 API 請求的每類型權杖細目：`input_tokens`、`output_tokens`、`cache_creation_input_tokens`、`cache_read_input_tokens` |
1900 1900
1901在 Claude Code v2.1.271 或更新版本上，使用 [`SubagentHandback`](/docs/zh-TW/tools-reference) 工具執行的子代理（Claude Code 在 [自動模式](/docs/zh-TW/permission-modes#eliminate-prompts-with-auto-mode) 中提供）透過該工具傳遞其報告，而不是作為文字返回。其 `completed` 結果的 `content` 欄位然後攜帶關於該交接的簡短說明，而不是報告本身。若要讀取報告，請在 `SubagentHandback` 上匹配 `PreToolUse` 或 `PostToolUse` hook 並讀取 `tool_input.message`。1901在 Claude Code v2.1.271 或更新版本上，使用 [`SubagentHandback`](/docs/zh-TW/tools-reference) 工具執行的子代理（Claude Code 在 [自動模式](/docs/zh-TW/permission-modes#eliminate-prompts-with-auto-mode) 中提供）透過該工具傳遞其報告，而不是將其傳回為文字。其 `completed` 結果的 `content` 欄位然後攜帶關於該交接的簡短說明，而不是報告本身。若要讀取報告，匹配 `PreToolUse` 或 `PostToolUse` hook 在 `SubagentHandback` 上，並讀取 `tool_input.message`。
1902 1902
1903對於背景子代理，工具在任務移到背景時返回，因此 `tool_response` 不攜帶使用欄位：背景啟動立即返回，前景任務在執行中被背景化時返回。它有 `status: "async_launched"`、`agentId`、`description`、`prompt`、`outputFile` 和 `resolvedModel`。1903對於背景子代理，工具在任務移到背景時傳回，因此 `tool_response` 不攜帶使用欄位：背景啟動立即傳回，前景任務在該轉換時由 Claude Code 背景化傳回。它有 `status: "async_launched"`、`agentId`、`description`、`prompt`、`outputFile` 和 `resolvedModel`。
1904 1904
1905在 `completed` 回應上，`resolvedModel` 命名子代理啟動的模型，可能與 `tool_input` 中的 `model` 值不同，例如當 `availableModels` 或其他覆寫適用時。在 `async_launched` 回應上，`resolvedModel` 命名代理移到背景時使用的模型，因此在背景化之前發生的交換會反映在那裡。`modelsUsed` 和背景化時間 `resolvedModel` 行為需要 Claude Code v2.1.212 或更新版本。1905在 `completed` 回應上，`resolvedModel` 命名子代理啟動的模型，可能與 `tool_input` 中的 `model` 值不同，例如當 `availableModels` 或另一個覆寫適用時。在 `async_launched` 回應上，`resolvedModel` 命名代理在移到背景時使用的模型，因此在背景化之前發生的交換會反映在那裡。`modelsUsed` 和背景化時間 `resolvedModel` 行為需要 Claude Code v2.1.212 或更新版本。
1906 1906
1907<a id="askuserquestion" />1907<a id="askuserquestion" />
1908 1908
1913詢問使用者一到四個多選題。1913詢問使用者一到四個多選題。
1914 1914
1915| 欄位 | 類型 | 範例 | 描述 |1915| 欄位 | 類型 | 範例 | 描述 |
1916| :---------- | :----- | :----------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------- |1916| :---------- | :----- | :----------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------- |
1917| `questions` | array | `[{"question": "Which framework?", "header": "Framework", "options": [{"label": "React"}], "multiSelect": false}]` | 要呈現的問題，每個都有 `question` 字串、簡短 `header`、`options` 陣列和可選 `multiSelect` 旗標 |1917| `questions` | array | `[{"question": "Which framework?", "header": "Framework", "options": [{"label": "React"}], "multiSelect": false}]` | 要呈現的問題，每個都有 `question` 字串、簡短 `header`、`options` 陣列和可選 `multiSelect` 旗標 |
1918| `answers` | object | `{"Which framework?": "React"}` | 可選。將問題文字對應到選定的選項標籤。多選答案用逗號連接標籤。Claude 不設定此欄位；透過 `updatedInput` 提供以程式設計方式回答 |1918| `answers` | object | `{"Which framework?": "React"}` | 可選。將問題文字對應到選定的選項標籤。多選答案用逗號連接標籤。Claude 不設定此欄位；透過 `updatedInput` 提供它以以程式設計方式回答 |
1919 1919
1920<h5 id="exitplanmode">1920<h5 id="exitplanmode">
1921 ExitPlanMode1921 ExitPlanMode
1922</h5>1922</h5>
1923 1923
1924呈現計畫並要求使用者在 Claude 離開 [計畫模式](/docs/zh-TW/permission-modes#analyze-before-you-edit-with-plan-mode) 之前核准。Claude 在呼叫工具之前將計畫寫入磁碟上的檔案，因此模型的字面 `tool_input` 通常是空的。Claude Code 在將輸入傳遞給 hooks 之前注入計畫內容和檔案路徑。1924呈現計畫並要求使用者在 Claude 離開 [plan mode](/docs/zh-TW/permission-modes#analyze-before-you-edit-with-plan-mode) 之前核准它。Claude 在呼叫工具之前將計畫寫入磁碟上的檔案，因此來自模型的字面 `tool_input` 通常是空的。Claude Code 在將輸入傳遞給 hooks 之前注入計畫內容和檔案路徑。
1925 1925
1926| 欄位 | 類型 | 範例 | 描述 |1926| 欄位 | 類型 | 範例 | 描述 |
1927| :--------------- | :----- | :------------------------------------------ | :---------------------------------------------------------------- |1927| :--------------- | :----- | :------------------------------------------ | :--------------------------------------------------------------- |
1928| `plan` | string | `"## Refactor auth\n1. Extract..."` | Markdown 中的計畫內容。從磁碟上的計畫檔案注入 |1928| `plan` | string | `"## Refactor auth\n1. Extract..."` | Markdown 中的計畫內容。從磁碟上的計畫檔案注入 |
1929| `planFilePath` | string | `"/Users/.../plans/refactor-auth.md"` | 計畫檔案的路徑。注入 |1929| `planFilePath` | string | `"/Users/.../plans/refactor-auth.md"` | 計畫檔案的路徑。注入 |
1930| `allowedPrompts` | array | `[{"tool": "Bash", "prompt": "run tests"}]` | 已棄用。Claude Code 接受欄位但忽略它。在 v2.1.205 之前，它攜帶 Claude 請求以實施計畫的基於提示的權限 |1930| `allowedPrompts` | array | `[{"tool": "Bash", "prompt": "run tests"}]` | 已棄用。Claude Code 接受欄位但忽略它。在 v2.1.205 之前，它攜帶 Claude 要求實施計畫的基於提示的權限 |
1931 1931
1932在 `PostToolUse` 中，`tool_response` 是一個物件，包含 `plan` 和 `filePath` 欄位保留核准的計畫，加上內部狀態旗標。讀取 `tool_response.plan` 以獲取計畫內容，而不是從磁碟重新讀取檔案。1932在 `PostToolUse` 中，`tool_response` 是一個物件，具有 `plan` 和 `filePath` 欄位，保持核准的計畫，加上內部狀態旗標。讀取 `tool_response.plan` 以獲得計畫內容，而不是從磁碟重新讀取檔案。
1933 1933
1934<h4 id="pretooluse-decision-control">1934<h4 id="pretooluse-decision-control">
1935 PreToolUse 決策控制1935 PreToolUse 決策控制
1936</h4>1936</h4>
1937 1937
1938`PreToolUse` hooks 可以控制工具呼叫是否進行。與使用頂級 `decision` 欄位的其他 hooks 不同，PreToolUse 在 `hookSpecificOutput` 物件內返回其決策。這提供了更豐富的控制：四個結果（允許、拒絕、詢問或延遲）加上在執行前修改工具輸入的能力。1938`PreToolUse` hooks 可以控制工具呼叫是否進行。與使用頂級 `decision` 欄位的其他 hooks 不同，PreToolUse 在 `hookSpecificOutput` 物件內傳回其決策。這給予它更豐富的控制：四個結果（允許、拒絕、詢問或延遲）加上在執行前修改工具輸入的能力。
1939 1939
1940| 欄位 | 描述 |1940| 欄位 | 描述 |
1941| :------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |1941| :------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
1942| `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 返回什麼都會被評估 |1942| `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 傳回什麼都會被評估 |
1943| `permissionDecisionReason` | 對於 `"allow"` 和 `"ask"`，顯示給使用者但不顯示給 Claude。對於 `"deny"`，顯示給 Claude。對於 `"defer"`，忽略 |1943| `permissionDecisionReason` | 對於 `"allow"` 和 `"ask"`，顯示給使用者但不顯示 Claude。對於 `"deny"`，顯示給 Claude。對於 `"defer"`，忽略 |
1944| `updatedInput` | 在執行前修改工具的輸入參數。替換整個輸入物件，因此在修改的欄位旁邊包含未變更的欄位。Claude Code 根據您的 hook 返回的輸入評估權限規則和 Bash 命令的 [自動背景資格](/docs/zh-TW/tools-reference#background-commands)，而不是 Claude 發送的輸入。與 `"allow"` 結合以自動核准，或與 `"ask"` 結合以向使用者顯示修改的輸入。對於 `"defer"`，忽略 |1944| `updatedInput` | 在執行前修改工具的輸入參數。替換整個輸入物件，因此在修改的欄位旁邊包含未變更的欄位。Claude Code 根據您的 hook 傳回的輸入評估權限規則和 Bash 命令的 [自動背景資格](/docs/zh-TW/tools-reference#background-commands)，而不是 Claude 傳送的輸入。與 `"allow"` 結合以自動核准，或與 `"ask"` 結合以向使用者顯示修改的輸入。對於 `"defer"`，忽略 |
1945| `additionalContext` | 與工具結果一起新增到 Claude 背景資訊的字串。當 `permissionDecision` 為 `"defer"` 時忽略。請參閱 [為 Claude 新增背景資訊](#add-context-for-claude) |1945| `additionalContext` | 與工具結果一起新增到 Claude 背景資訊的字串。當 `permissionDecision` 為 `"defer"` 時忽略。請參閱 [為 Claude 新增背景資訊](#add-context-for-claude) |
1946 1946
1947當多個 PreToolUse hooks 返回不同的決策時，優先順序為 `deny` > `defer` > `ask` > `allow`。1947當多個 PreToolUse hooks 傳回不同的決策時，優先順序為 `deny` > `defer` > `ask` > `allow`。
1948 1948
1949透過退出 2 阻止的 hook 路由方式與 `"deny"` 相同：Claude 看到 stderr 訊息作為拒絕原因。1949透過退出 2 阻止的 hook 以與 `"deny"` 相同的方式路由：Claude 看到 stderr 訊息作為拒絕原因。
1950 1950
1951當 hook 返回 `"ask"` 時，顯示給使用者的權限提示包含一個標籤，識別 hook 來自何處：`[settings]` 對於來自任何設定檔或代理 frontmatter 的 hook，`[plugin:<name>]` 對於外掛的 hook，或 `[skill]` 對於來自 skill frontmatter 的 hook。這幫助使用者理解哪個設定來源要求確認。1951當 hook 傳回 `"ask"` 時，顯示給使用者的權限提示包括識別 hook 來源的標籤：`[settings]` 對於來自任何設定檔或代理 frontmatter 的 hook，`[plugin:<name>]` 對於外掛的 hook，或 `[skill]` 對於來自 skill frontmatter 的 hook。這幫助使用者理解哪個配置來源要求確認。
1952 1952
1953Hook 的 `"ask"` 也在 [自動模式](/docs/zh-TW/permission-modes#eliminate-prompts-with-auto-mode) 中強制權限提示：分類器仍然可以拒絕工具呼叫，但無法無聲地核准呼叫。在 v2.1.211 之前，分類器可以核准在 [沙箱](/docs/zh-TW/sandboxing) 外執行的 Bash 命令而不顯示 hook 請求的提示；分類器仍然對該命令應用了自己的安全規則，hook `"deny"` 始終被尊重。1953Hook 的 `"ask"` 也在 [自動模式](/docs/zh-TW/permission-modes#eliminate-prompts-with-auto-mode) 中強制權限提示：分類器仍然可以拒絕工具呼叫，但它無法無聲地核准呼叫。在 v2.1.211 之前，分類器可以核准在 [sandbox](/docs/zh-TW/sandboxing) 外執行的 Bash 命令，而不顯示 hook 要求的提示；分類器仍然對該命令應用了自己的安全規則，hook `"deny"` 始終被尊重。
1954 1954
1955```json theme={null}1955```json theme={null}
1956{1956{
1968 1968
1969<span id="allow-with-updatedinput" />1969<span id="allow-with-updatedinput" />
1970 1970
1971在 [非互動模式](/docs/zh-TW/headless) 中使用 `-p` 旗標，Claude Code 僅在執行有 [權限主機](/docs/zh-TW/headless#turn-off-permission-prompts-in-unattended-runs) 以接收提示時提供 `AskUserQuestion` 和 `ExitPlanMode`，例如 Agent SDK `canUseTool` 回呼。這些工具需要使用者互動。返回 `permissionDecision: "allow"` 與 `updatedInput` 一起滿足該要求：hook 從 stdin 讀取工具的輸入，透過您自己的 UI 收集答案，並在 `updatedInput` 中返回它，以便工具執行而不提示。單獨返回 `"allow"` 對這些工具不足夠。對於 `AskUserQuestion`，回顯原始 `questions` 陣列並新增一個 [`answers`](#askuserquestion) 物件，將每個問題的文字對應到選定的答案。1971在 [非互動模式](/docs/zh-TW/headless) 中使用 `-p` 旗標，Claude Code 僅在執行有 [權限主機](/docs/zh-TW/headless#turn-off-permission-prompts-in-unattended-runs) 以接收提示時提供 `AskUserQuestion` 和 `ExitPlanMode`，例如 Agent SDK `canUseTool` 回呼。這些工具需要使用者互動。傳回 `permissionDecision: "allow"` 與 `updatedInput` 一起滿足該要求：hook 從 stdin 讀取工具的輸入，透過您自己的 UI 收集答案，並在 `updatedInput` 中傳回它，以便工具執行而不提示。單獨傳回 `"allow"` 對這些工具不夠。對於 `AskUserQuestion`，回顯原始 `questions` 陣列並新增一個 [`answers`](#askuserquestion) 物件，將每個問題的文字對應到選定的答案。
1972 1972
1973自 v2.1.199 起，其伺服器使用 [`_meta["anthropic/requiresUserInteraction"]`](/docs/zh-TW/mcp#require-approval-for-a-specific-tool) 標記的 MCP 工具更嚴格：hook 無法使用 `"allow"` 跳過其核准提示，無論是否有 `updatedInput`，因為 Claude Code 無法確認 hook 收集了工具需要的互動。1973自 v2.1.199 起，其伺服器使用 [`_meta["anthropic/requiresUserInteraction"]`](/docs/zh-TW/mcp#require-approval-for-a-specific-tool) 標記的 MCP 工具更嚴格：hook 無法使用 `"allow"` 跳過其核准提示，無論是否有 `updatedInput`，因為 Claude Code 無法確認 hook 收集了工具需要的互動。
1974 1974
1985`AskUserQuestion` 工具是典型情況：Claude 想詢問使用者某事，但沒有終端來回答。`-p` 執行僅在有 [權限主機](/docs/zh-TW/headless#turn-off-permission-prompts-in-unattended-runs) 時提供 `AskUserQuestion`，例如您使用 `--permission-prompt-tool` 傳遞的 MCP 工具，因此使用一個啟動執行。往返工作如下：1985`AskUserQuestion` 工具是典型情況：Claude 想詢問使用者某事，但沒有終端來回答。`-p` 執行僅在有 [權限主機](/docs/zh-TW/headless#turn-off-permission-prompts-in-unattended-runs) 時提供 `AskUserQuestion`，例如您使用 `--permission-prompt-tool` 傳遞的 MCP 工具，因此使用一個啟動執行。往返工作如下：
1986 1986
19871. Claude 呼叫 `AskUserQuestion`。`PreToolUse` hook 觸發。19871. Claude 呼叫 `AskUserQuestion`。`PreToolUse` hook 觸發。
19882. Hook 返回 `permissionDecision: "defer"`。工具不執行。程序以 `stop_reason: "tool_deferred"` 退出，待處理工具呼叫保留在文字記錄中。19882. Hook 傳回 `permissionDecision: "defer"`。工具不執行。程序以 `stop_reason: "tool_deferred"` 退出，待處理工具呼叫保留在文字記錄中。
19893. 呼叫程序從 SDK 結果讀取 `deferred_tool_use`，在其自己的 UI 中呈現問題，並等待答案。19893. 呼叫程序從 SDK 結果讀取 `deferred_tool_use`，在其自己的 UI 中呈現問題，並等待答案。
19904. 呼叫程序執行 `claude -p --resume <session-id>`，使用相同的權限主機。相同的工具呼叫再次觸發 `PreToolUse`。19904. 呼叫程序執行 `claude -p --resume <session-id>`，使用相同的權限主機。相同的工具呼叫再次觸發 `PreToolUse`。
19915. Hook 返回 `permissionDecision: "allow"`，答案在 `updatedInput` 中。工具執行，Claude 繼續。19915. Hook 傳回 `permissionDecision: "allow"`，答案在 `updatedInput` 中。工具執行，Claude 繼續。
1992 1992
1993`deferred_tool_use` 欄位攜帶工具的 `id`、`name` 和 `input`。`input` 是 Claude 為工具呼叫生成的參數，在執行前捕獲：1993`deferred_tool_use` 欄位攜帶工具的 `id`、`name` 和 `input`。`input` 是 Claude 為工具呼叫產生的參數，在執行前擷取：
1994 1994
1995```json theme={null}1995```json theme={null}
1996{1996{
2006}2006}
2007```2007```
2008 2008
2009沒有逾時或重試限制。工作階段保留在磁碟上直到您恢復它，受 [`cleanupPeriodDays`](/docs/zh-TW/settings-reference#cleanupperioddays) 保留掃描約束，預設情況下在 30 天後刪除工作階段檔案，遵循 [保留掃描規則](/docs/zh-TW/claude-directory#cleaned-up-automatically)。如果恢復時答案還未準備好，hook 可以再次返回 `"defer"`，程序以相同方式退出。呼叫程序透過最終從 hook 返回 `"allow"` 或 `"deny"` 來控制何時打破迴圈。2009沒有逾時或重試限制。工作階段保留在磁碟上，直到您恢復它，受 [`cleanupPeriodDays`](/docs/zh-TW/settings-reference#cleanupperioddays) 保留掃描約束，預設情況下在 30 天後刪除工作階段檔案，遵循 [保留掃描規則](/docs/zh-TW/claude-directory#cleaned-up-automatically)。如果恢復時答案還未準備好，hook 可以再次傳回 `"defer"`，程序以相同方式退出。呼叫程序控制何時透過最終傳回 `"allow"` 或 `"deny"` 來打破迴圈。
2010 2010
2011`"defer"` 僅在 Claude 在回合中進行單個工具呼叫時有效。如果 Claude 同時進行多個工具呼叫，`"defer"` 會被忽略並帶有警告，工具透過正常權限流程進行。約束存在是因為恢復只能重新執行一個工具：沒有辦法延遲批次中的一個呼叫而不留下其他未解決。2011`"defer"` 僅在 Claude 在回合中進行單個工具呼叫時有效。如果 Claude 同時進行多個工具呼叫，`"defer"` 會被忽略，並顯示警告，工具透過正常權限流程進行。約束存在是因為恢復只能重新執行一個工具：沒有辦法延遲批次中的一個呼叫而不留下其他未解決的。
2012 2012
2013如果恢復時延遲的工具不再可用，程序以 `stop_reason: "tool_deferred_unavailable"` 和 `is_error: true` 退出，在 hook 觸發之前。這發生在為恢復的工作階段未連接提供工具的 MCP 伺服器時。`deferred_tool_use` 有效負載仍然包含，以便您可以識別哪個工具遺失。2013如果恢復時延遲的工具不再可用，程序以 `stop_reason: "tool_deferred_unavailable"` 和 `is_error: true` 退出，在 hook 觸發之前。這發生在為恢復的工作階段未連接提供工具的 MCP 伺服器時。`deferred_tool_use` 有效負載仍包含在內，以便您可以識別哪個工具遺失。
2014 2014
2015<Note>2015<Note>
2016 若要在計畫模式中恢復延遲工作階段，請在 `--resume` 時傳遞 [`--permission-prompt-tool`](/docs/zh-TW/cli-reference#cli-flags)，以便 Claude Code 可以呈現計畫以供核准。沒有它，Claude Code 不會恢復計畫模式。需要 Claude Code v2.1.246 或更新版本。2016 若要在 plan mode 中恢復延遲工作階段，請在 `--resume` 旁邊傳遞 [`--permission-prompt-tool`](/docs/zh-TW/cli-reference#cli-flags)，以便 Claude Code 可以呈現計畫以供核准。沒有它，Claude Code 不會恢復 plan mode。需要 Claude Code v2.1.246 或更新版本。
2017 2017
2018 當您使用 `-p` 恢復時，Claude Code 不會恢復任何其他儲存的權限模式。它在新 `claude -p` 執行會啟動的權限模式中啟動執行，因此如果延遲工作階段使用了一個，請再次傳遞 `--permission-mode` 或 `--dangerously-skip-permissions`。當您使用 `claude --resume <session-id>` 恢復而不使用 `-p` 時，Claude Code 會恢復儲存的權限模式，但 [恢復時的權限模式](/docs/zh-TW/sessions#permission-mode-on-resume) 中列出的例外除外。2018 當您使用 `-p` 恢復時，Claude Code 不會恢復任何其他儲存的權限模式。它在新 `claude -p` 執行會啟動的權限模式中啟動執行，因此如果延遲工作階段使用了一個，請再次傳遞 `--permission-mode` 或 `--dangerously-skip-permissions`。當您使用 `claude --resume <session-id>` 恢復而不使用 `-p` 時，Claude Code 恢復儲存的權限模式，但 [恢復時的權限模式](/docs/zh-TW/sessions#permission-mode-on-resume) 中列出的例外除外。
2019</Note>2019</Note>
2020 2020
2021<h3 id="permissionrequest">2021<h3 id="permissionrequest">
2022 PermissionRequest2022 PermissionRequest
2023</h3>2023</h3>
2024 2024
2025在 Claude Code 即將要求您許可使用工具時執行。在無法顯示提示的工作階段中，例如 [非互動模式](/docs/zh-TW/headless) 中的背景子代理，Claude Code 仍然執行這些 hooks，如果沒有 hook 返回決策，它會拒絕工具呼叫。2025在 Claude Code 即將要求您許可使用工具時執行。在無法顯示提示的工作階段中，例如 [非互動模式](/docs/zh-TW/headless) 中的背景子代理，Claude Code 仍執行這些 hooks，如果沒有 hook 傳回決策，它會拒絕工具呼叫。
2026使用 [PermissionRequest 決策控制](#permissionrequest-decision-control) 代表使用者允許或拒絕。2026使用 [PermissionRequest 決策控制](#permissionrequest-decision-control) 代表使用者允許或拒絕。
2027 2027
2028當您需要 Claude 要求許可使用工具時的信號時使用此事件。Claude Code 僅在提示等待約六秒後才執行 [Notification](#notification) hook，其中 `permission_prompt` 類型。2028當您需要 Claude 要求許可使用工具時的信號時，使用此事件。Claude Code 僅在提示等待約六秒後才執行 [Notification](#notification) hook，其 `permission_prompt` 類型。
2029 2029
2030Claude Code 不為沙箱命令的 [網路請求](/docs/zh-TW/sandboxing#network-isolation) 執行 PermissionRequest hooks。若要獲得該提示的信號，請使用 `permission_prompt` 通知類型。2030Claude Code 不為沙箱命令的 [網路請求](/docs/zh-TW/sandboxing#network-isolation) 執行 PermissionRequest hooks。若要獲得該提示的信號，請使用 `permission_prompt` 通知類型。
2031 2031
2037 2037
2038PermissionRequest hooks 接收 `tool_name` 和 `tool_input` 欄位，如 PreToolUse hooks，但沒有 `tool_use_id`。對於 MCP 工具，它們也接收 [`mcp_server`](#pretooluse-input) 物件。可選 `permission_suggestions` 陣列包含 Claude Code 為此請求建議的 [權限更新](#permission-update-entries)，例如新增允許規則或更改權限模式。2038PermissionRequest hooks 接收 `tool_name` 和 `tool_input` 欄位，如 PreToolUse hooks，但沒有 `tool_use_id`。對於 MCP 工具，它們也接收 [`mcp_server`](#pretooluse-input) 物件。可選 `permission_suggestions` 陣列包含 Claude Code 為此請求建議的 [權限更新](#permission-update-entries)，例如新增允許規則或更改權限模式。
2039 2039
2040`permission_suggestions` 陣列不是您看到的選項的確切清單，因為每個權限對話建立自己的選項。某些對話（例如檔案編輯的對話）根本不讀取陣列，並從請求本身衍生其選項。讀取它的對話仍然可以保留一個選項，其建議保留在陣列中，例如當 [`allowManagedPermissionRulesOnly`](/docs/zh-TW/settings-reference#allowmanagedpermissionrulesonly) 隱藏規則保存選項時。它也可以提供陣列中沒有建議項目的選項，例如 [**是的，並切換到自動模式**](/docs/zh-TW/permission-modes#switch-permission-modes)，它直接更改權限模式而不是透過權限更新。2040`permission_suggestions` 陣列不是您看到的選項的確切清單，因為每個權限對話都建立自己的選項。某些對話（例如檔案編輯的對話）根本不讀取陣列，並從請求本身衍生其選項。讀取它的對話仍然可以保留陣列中的建議，例如當 [`allowManagedPermissionRulesOnly`](/docs/zh-TW/settings-reference#allowmanagedpermissionrulesonly) 隱藏規則保存選項時。它也可以提供沒有建議項目的選項，例如 [**Yes, and switch to auto mode**](/docs/zh-TW/permission-modes#switch-permission-modes)，它直接更改權限模式，而不是透過權限更新。
2041 2041
2042PreToolUse hooks 在每個工具呼叫之前執行，無論是否需要權限。PermissionRequest hooks 僅在 Claude Code 即將要求您許可時執行，或當它會以其他方式自動拒絕無法提示的呼叫時執行。兩個事件都不對 [`EndConversation`](/docs/zh-TW/tools-reference#endconversation-tool-behavior) 觸發。2042PreToolUse hooks 在每個工具呼叫之前執行，無論它是否需要權限。PermissionRequest hooks 僅在 Claude Code 即將要求您許可時執行，或當它否則會自動拒絕無法提示的呼叫時執行。兩個事件都不會對 [`EndConversation`](/docs/zh-TW/tools-reference#endconversation-tool-behavior) 觸發。
2043 2043
2044```json theme={null}2044```json theme={null}
2045{2045{
2068 PermissionRequest 決策控制2068 PermissionRequest 決策控制
2069</h4>2069</h4>
2070 2070
2071`PermissionRequest` hooks 可以允許或拒絕權限請求。除了所有 hooks 可用的 [JSON 輸出欄位](#json-output) 外，您的 hook 指令碼可以返回具有這些事件特定欄位的 `decision` 物件：2071`PermissionRequest` hooks 可以允許或拒絕權限請求。除了 [所有 hooks 可用的 JSON 輸出欄位](#json-output) 外，您的 hook 指令碼可以傳回具有這些事件特定欄位的 `decision` 物件：
2072 2072
2073| 欄位 | 描述 |2073| 欄位 | 描述 |
2074| :------------------- | :------------------------------------------------------------------------------------------------------------------ |2074| :------------------- | :------------------------------------------------------------------------------------------------------------------- |
2075| `behavior` | `"allow"` 授予權限，`"deny"` 拒絕。[拒絕和詢問規則](/docs/zh-TW/permissions#manage-permissions) 仍然被評估，因此返回 `"allow"` 的 hook 不會覆寫匹配的拒絕規則 |2075| `behavior` | `"allow"` 授予權限，`"deny"` 拒絕它。[拒絕和詢問規則](/docs/zh-TW/permissions#manage-permissions) 仍會被評估，因此傳回 `"allow"` 的 hook 不會覆寫匹配的拒絕規則 |
2076| `updatedInput` | 僅對 `"allow"`：在執行前修改工具的輸入參數。替換整個輸入物件，因此在修改的欄位旁邊包含未變更的欄位。修改的輸入會針對拒絕和詢問規則重新評估 |2076| `updatedInput` | 僅對 `"allow"`：在執行前修改工具的輸入參數。替換整個輸入物件，因此在修改的欄位旁邊包含未變更的欄位。修改的輸入會針對拒絕和詢問規則重新評估 |
2077| `updatedPermissions` | 僅對 `"allow"`：[權限更新項目](#permission-update-entries) 陣列以應用，例如新增允許規則或更改工作階段權限模式 |2077| `updatedPermissions` | 僅對 `"allow"`：[權限更新項目](#permission-update-entries) 陣列以應用，例如新增允許規則或更改工作階段權限模式 |
2078| `message` | 僅對 `"deny"`：告訴 Claude 為什麼權限被拒絕 |2078| `message` | 僅對 `"deny"`：告訴 Claude 為什麼權限被拒絕 |
2098 權限更新項目2098 權限更新項目
2099</h4>2099</h4>
2100 2100
2101`updatedPermissions` 輸出欄位和 [`permission_suggestions` 輸入欄位](#permissionrequest-input) 都使用相同的項目物件陣列。每個項目都有一個 `type` 決定其他欄位，以及一個 `destination` 控制變更寫入位置。2101`updatedPermissions` 輸出欄位和 [`permission_suggestions` 輸入欄位](#permissionrequest-input) 都使用相同的項目物件陣列。每個項目都有一個 `type`，決定其他欄位，以及一個 `destination`，控制變更的寫入位置。
2102 2102
2103| `type` | 欄位 | 效果 |2103| `type` | 欄位 | 效果 |
2104| :------------------ | :------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------- |2104| :------------------ | :------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------- |
2105| `addRules` | `rules`、`behavior`、`destination` | 新增權限規則。`rules` 是 `{toolName, ruleContent?}` 物件的陣列。省略 `ruleContent` 以匹配整個工具。`behavior` 為 `"allow"`、`"deny"` 或 `"ask"` |2105| `addRules` | `rules`、`behavior`、`destination` | 新增權限規則。`rules` 是 `{toolName, ruleContent?}` 物件的陣列。省略 `ruleContent` 以匹配整個工具。`behavior` 為 `"allow"`、`"deny"` 或 `"ask"` |
2106| `replaceRules` | `rules`、`behavior`、`destination` | 將給定 `behavior` 在 `destination` 的所有規則替換為提供的 `rules` |2106| `replaceRules` | `rules`、`behavior`、`destination` | 將 `destination` 處給定 `behavior` 的所有規則替換為提供的 `rules` |
2107| `removeRules` | `rules`、`behavior`、`destination` | 移除給定 `behavior` 的匹配規則 |2107| `removeRules` | `rules`、`behavior`、`destination` | 移除給定 `behavior` 的匹配規則 |
2108| `setMode` | `mode`、`destination` | 更改權限模式。有效模式為 `default`、`auto`、`acceptEdits`、`dontAsk`、`bypassPermissions`、`plan` 和 `manual` 作為 `default` 的別名。`manual` 別名需要 Claude Code v2.1.200 或更新版本 |2108| `setMode` | `mode`、`destination` | 更改權限模式。有效模式為 `default`、`auto`、`acceptEdits`、`dontAsk`、`bypassPermissions`、`plan` 和 `manual` 作為 `default` 的別名。`manual` 別名需要 Claude Code v2.1.200 或更新版本 |
2109| `addDirectories` | `directories`、`destination` | 新增工作目錄。`directories` 是路徑字串的陣列 |2109| `addDirectories` | `directories`、`destination` | 新增工作目錄。`directories` 是路徑字串的陣列 |
2110| `removeDirectories` | `directories`、`destination` | 移除工作目錄 |2110| `removeDirectories` | `directories`、`destination` | 移除工作目錄 |
2111 2111
2112<Note>2112<Note>
2113 `setMode` 搭配 `bypassPermissions` 僅在您已啟動工作階段時生效，且繞過模式已可用：`--dangerously-skip-permissions`、`--permission-mode bypassPermissions`、`--allow-dangerously-skip-permissions` 或 [使用者、`--settings` 或受管設定](/docs/zh-TW/settings-reference#permissions-defaultmode) 中的 `permissions.defaultMode: "bypassPermissions"`。否則更新是無操作。當 [`permissions.disableBypassPermissionsMode`](/docs/zh-TW/permissions#managed-settings) 禁用模式或工作階段在 [受限模式](/docs/zh-TW/cli-reference#cli-flags) 中啟動時，更新也是無操作。2113 `setMode` 搭配 `bypassPermissions` 僅在您已啟動工作階段時生效，且 bypass 模式已可用：`--dangerously-skip-permissions`、`--permission-mode bypassPermissions`、`--allow-dangerously-skip-permissions` 或 [user、`--settings` 或 managed settings](/docs/zh-TW/settings-reference#permissions-defaultmode) 中的 `permissions.defaultMode: "bypassPermissions"`。否則更新是無操作。當 [`permissions.disableBypassPermissionsMode`](/docs/zh-TW/permissions#managed-settings) 停用模式或工作階段在 [受限模式](/docs/zh-TW/cli-reference#cli-flags) 中啟動時，更新也是無操作。
2114 2114
2115 `bypassPermissions` 無論 `destination` 如何都永遠不會作為 `defaultMode` 保留。2115 無論 `destination` 如何，`bypassPermissions` 永遠不會作為 `defaultMode` 保留。
2116</Note>2116</Note>
2117 2117
2118每個項目上的 `destination` 欄位決定變更是保留在記憶體中還是保留到設定檔。2118每個項目上的 `destination` 欄位決定變更是保留在記憶體中還是保留到設定檔。
2134 2134
2135在工具名稱上匹配，與 PreToolUse 相同的值。2135在工具名稱上匹配，與 PreToolUse 相同的值。
2136 2136
2137當工具名稱不是正確的篩選器時更廣泛地匹配：2137當工具名稱不是正確的篩選器時，更廣泛地匹配：
2138 2138
2139* 若要在任何工具成功完成後執行 hook，省略 `matcher` 或將其設定為 `"*"`。您的 hook 然後可以自己探索變更的內容，例如執行 `git status --porcelain`，它也列出 `git diff` 遺漏的未追蹤檔案。對於失敗的工具呼叫，在 [PostToolUseFailure](#posttoolusefailure) 下新增相同的 hook。2139* 若要在任何工具成功完成後執行 hook，省略 `matcher` 或將其設定為 `"*"`。您的 hook 然後可以自己探索變更了什麼，例如執行 `git status --porcelain`，它也列出 `git diff` 遺漏的未追蹤檔案。對於失敗的工具呼叫，在 [PostToolUseFailure](#posttoolusefailure) 下新增相同的 hook。
2140* 若要在特定檔案變更時執行 hook，無論什麼寫入它，請使用 [FileChanged](#filechanged)。當 `Bash` 命令或 Claude Code 外的程序重寫相同檔案時，Claude Code 不執行匹配 `Edit|Write` 的 `PostToolUse` hook。2140* 若要在特定檔案在磁碟上變更時執行 hook，無論什麼寫入它，請使用 [FileChanged](#filechanged)。當 `Bash` 命令或 Claude Code 外的程序重寫相同檔案時，Claude Code 不執行匹配 `Edit|Write` 的 `PostToolUse` hook。
2141 2141
2142<h4 id="posttooluse-input">2142<h4 id="posttooluse-input">
2143 PostToolUse 輸入2143 PostToolUse 輸入
2144</h4>2144</h4>
2145 2145
2146`PostToolUse` hooks 在工具已成功執行後觸發。輸入包括 `tool_input`（發送給工具的引數）和 `tool_response`（它返回的結果）。兩者的確切架構取決於工具。檔案工具 `tool_input` 路徑以與 [PreToolUse](#pretooluse-input) 相同的格式到達：始終絕對，使用平台的原生分隔符，因此 Windows 上為反斜線。對於 MCP 工具，輸入也攜帶 [`mcp_server`](#pretooluse-input) 物件。2146`PostToolUse` hooks 在工具已執行成功後觸發。輸入包括 `tool_input`（傳送給工具的引數）和 `tool_response`（它傳回的結果）。兩者的確切架構取決於工具。檔案工具 `tool_input` 路徑以與 [PreToolUse](#pretooluse-input) 相同的格式到達：始終絕對，具有平台的原生分隔符，因此 Windows 上的反斜線。對於 MCP 工具，輸入也攜帶 [`mcp_server`](#pretooluse-input) 物件。
2147 2147
2148```json theme={null}2148```json theme={null}
2149{2149{
2174 PostToolUse 決策控制2174 PostToolUse 決策控制
2175</h4>2175</h4>
2176 2176
2177`PostToolUse` hooks 可以在工具執行後提供回饋給 Claude。除了所有 hooks 可用的 [JSON 輸出欄位](#json-output) 外，您的 hook 指令碼可以返回這些事件特定欄位：2177`PostToolUse` hooks 可以在工具執行後提供回饋給 Claude。除了 [所有 hooks 可用的 JSON 輸出欄位](#json-output) 外，您的 hook 指令碼可以傳回這些事件特定的欄位：
2178 2178
2179| 欄位 | 描述 |2179| 欄位 | 描述 |
2180| :--------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |2180| :--------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
2181| `decision` | `"block"` 在工具結果旁邊新增 `reason`。Claude 仍然看到原始輸出；若要替換它，請使用 `updatedToolOutput` |2181| `decision` | `"block"` 在工具結果旁邊新增 `reason`。Claude 仍看到原始輸出；若要替換它，請使用 `updatedToolOutput` |
2182| `reason` | 當 `decision` 為 `"block"` 時顯示給 Claude 的解釋 |2182| `reason` | 當 `decision` 為 `"block"` 時顯示給 Claude 的說明 |
2183| `additionalContext` | 與工具結果一起新增到 Claude 背景資訊的字串。請參閱 [為 Claude 新增背景資訊](#add-context-for-claude) |2183| `additionalContext` | 與工具結果一起新增到 Claude 背景資訊的字串。請參閱 [為 Claude 新增背景資訊](#add-context-for-claude) |
2184| `classifierContext` | 關於此呼叫結果的簡短說明，用於 [自動模式](/docs/zh-TW/permission-modes#eliminate-prompts-with-auto-mode) 分類器而不是 Claude。請參閱 [為自動模式分類器註釋結果](#annotate-a-result-for-the-auto-mode-classifier)。需要 Claude Code v2.1.236 或更新版本 |2184| `classifierContext` | 關於此呼叫結果的簡短說明，用於 [自動模式](/docs/zh-TW/permission-modes#eliminate-prompts-with-auto-mode) 分類器，而不是 Claude。請參閱 [為自動模式分類器註釋結果](#annotate-a-result-for-the-auto-mode-classifier)。需要 Claude Code v2.1.236 或更新版本 |
2185| `updatedToolOutput` | 在發送給 Claude 之前用提供的值替換工具的輸出。該值必須符合工具的輸出形狀 |2185| `updatedToolOutput` | 在將工具的輸出傳送給 Claude 之前，用提供的值替換它。該值必須符合工具的輸出形狀 |
2186| `updatedMCPToolOutput` | 僅替換 [MCP 工具](#match-mcp-tools) 的輸出。優先使用 `updatedToolOutput`，它適用於所有工具 |2186| `updatedMCPToolOutput` | 僅替換 [MCP 工具](#match-mcp-tools) 的輸出。優先使用 `updatedToolOutput`，它適用於所有工具 |
2187 2187
2188下面的範例替換 `Bash` 呼叫的輸出。替換值符合 `Bash` 工具的輸出形狀：2188下面的範例替換 `Bash` 呼叫的輸出。替換值符合 `Bash` 工具的輸出形狀：
2203```2203```
2204 2204
2205<Warning>2205<Warning>
2206 `updatedToolOutput` 僅更改 Claude 看到的內容。工具已在 hook 觸發時執行，因此任何寫入的檔案、執行的命令或發送的網路請求已生效。遙測（例如 OpenTelemetry 工具跨度和分析事件）也會在 hook 執行前捕獲原始輸出。若要在執行前防止或修改工具呼叫，請改用 [PreToolUse](#pretooluse) hook。2206 `updatedToolOutput` 僅更改 Claude 看到的內容。工具在 hook 觸發時已執行，因此任何寫入的檔案、執行的命令或傳送的網路請求都已生效。遙測（例如 OpenTelemetry 工具跨度和分析事件）也在 hook 執行前擷取原始輸出。若要在執行前防止或修改工具呼叫，請改用 [PreToolUse](#pretooluse) hook。
2207 2207
2208 替換值必須符合工具的輸出形狀。內建工具返回結構化物件而不是純字串。例如，`Bash` 返回具有 `stdout`、`stderr`、`interrupted` 和 `isImage` 欄位的物件。對於內建工具，不符合工具輸出架構的值會被忽略，使用原始輸出。MCP 工具輸出通過而不進行架構驗證。去除 Claude 需要的錯誤詳細資訊可能導致它在錯誤假設上進行。2208 替換值必須符合工具的輸出形狀。內建工具傳回結構化物件，而不是純字串。例如，`Bash` 傳回具有 `stdout`、`stderr`、`interrupted` 和 `isImage` 欄位的物件。對於內建工具，不符合工具輸出架構的值會被忽略，使用原始輸出。MCP 工具輸出通過而不進行架構驗證。去除 Claude 需要的錯誤詳細資訊可能導致它在錯誤假設上進行。
2209</Warning>2209</Warning>
2210 2210
2211<h4 id="annotate-a-result-for-the-auto-mode-classifier">2211<h4 id="annotate-a-result-for-the-auto-mode-classifier">
2212 為自動模式分類器註釋結果2212 為自動模式分類器註釋結果
2213</h4>2213</h4>
2214 2214
2215返回 `classifierContext` 以向 [自動模式](/docs/zh-TW/permission-modes#eliminate-prompts-with-auto-mode) 分類器發送關於工具呼叫結果的簡短說明，而不是向 Claude。分類器 [永遠不會接收工具結果本身](/docs/zh-TW/permission-modes#how-the-classifier-evaluates-actions)，因此此欄位是支援的方式，在它審查稍後的動作之前告訴它工具呼叫返回的內容。該欄位需要 Claude Code v2.1.236 或更新版本。2215傳回 `classifierContext` 以將關於工具呼叫結果的簡短說明傳送給 [自動模式](/docs/zh-TW/permission-modes#eliminate-prompts-with-auto-mode) 分類器，而不是 Claude。分類器 [永遠不會接收工具結果本身](/docs/zh-TW/permission-modes#how-the-classifier-evaluates-actions)，因此此欄位是在分類器審查稍後動作之前告訴它關於呼叫傳回內容的支援方式。該欄位需要 Claude Code v2.1.236 或更新版本。
2216 2216
2217下面的範例告訴分類器查詢的輸出來自何處：2217下面的範例告訴分類器查詢的輸出來自何處：
2218 2218
2225}2225}
2226```2226```
2227 2227
2228分類器給予說明的權重取決於您設定 hook 的位置：2228分類器給予說明的權重取決於您配置 hook 的位置：
2229 2229
2230* **在 Claude Code 中設定的 Hooks**：對於來自設定檔、外掛、skills 和代理 frontmatter 的 hooks，分類器將說明視為未驗證的應用程式提供的背景資訊。說明永遠不會建立使用者意圖，如果它聲稱您核准或請求了某事，分類器會根據您在對話中的自己訊息檢查該聲明2230* **在 Claude Code 中配置的 Hooks**：對於來自設定檔、外掛、skills 和代理 frontmatter 的 hooks，分類器將說明視為未驗證的應用程式提供的背景資訊。說明永遠不會建立使用者意圖，如果它聲稱您核准或要求了某事，分類器會根據您在對話中的自己訊息檢查該聲明
2231* **進程內 Agent SDK 回呼**：當應用程式嵌入 Claude Code 將 hook 註冊為 [TypeScript SDK 回呼](/docs/zh-TW/agent-sdk/hooks) 並在即時工作階段期間返回說明時，分類器可能會將使用者陳述（在說明中轉達）視為使用者意圖。這樣的陳述可以滿足分類器會接受來自您發送的訊息的同意要求，但它永遠不會解除您自己的訊息也無法解除的阻止。工作階段恢復後，Claude Code 將恢復的說明視為未驗證的背景資訊。當兩個群組的 hooks 註釋相同呼叫時，分類器將組合說明視為未驗證2231* **進程內 Agent SDK 回呼**：當應用程式嵌入 Claude Code 並將 hook 註冊為 [TypeScript SDK 回呼](/docs/zh-TW/agent-sdk/hooks) 並在即時工作階段期間傳回說明時，分類器可能會將使用者陳述（在說明中轉達）視為使用者意圖。這樣的陳述可以滿足分類器會接受來自您傳送的訊息的同意要求，但它永遠不會解除您自己的訊息也無法解除的阻止。工作階段恢復後，Claude Code 將恢復的說明視為未驗證的背景資訊。當來自兩個群組的 hooks 註釋相同呼叫時，分類器將組合說明視為未驗證
2232 2232
2233Claude Code 在傳遞說明時應用這些限制：2233Claude Code 在傳遞說明時應用這些限制：
2234 2234
2235* **長度**：Claude Code 將一個工具呼叫的說明上限設定為 2,000 個字元，並截斷其餘部分。上限在回應該呼叫的每個 hook 中共享2235* **長度**：Claude Code 將一個工具呼叫的說明上限設定為 2,000 個字元，並截斷其餘部分。上限在每個回應該呼叫的 hook 之間共享
2236* **僅同步回應**：Claude Code 忽略 [在背景執行](#run-hooks-in-the-background) 的 hook 回應中的欄位，因為該回應在 Claude Code 記錄工具結果後到達2236* **僅同步回應**：Claude Code 忽略 [在背景執行](#run-hooks-in-the-background) 的 hook 回應中的欄位，因為該回應在 Claude Code 記錄工具結果後到達
2237* **分類器不記錄的呼叫**：分類器的文字記錄省略唯讀查詢，例如檔案讀取和搜尋。Claude Code 捨棄附加到其中一個呼叫的說明2237* **分類器不記錄的呼叫**：分類器的文字記錄省略唯讀查詢，例如檔案讀取和搜尋。Claude Code 捨棄附加到其中一個呼叫的說明
2238* **與重寫的互動**：當說明描述您使用 `updatedToolOutput` 替換的輸出時，在相同的 hook 回應中返回兩個欄位。如果該重寫被拒絕或另一個 hook 的重寫替換它，Claude Code 會捨棄說明。Claude Code 傳遞您返回的說明而不進行重寫，即使另一個 hook 重寫輸出2238* **與重寫的互動**：當說明描述您使用 `updatedToolOutput` 替換的輸出時，在相同的 hook 回應中傳回兩個欄位。如果該重寫被拒絕或另一個 hook 的重寫替換它，Claude Code 會捨棄說明。Claude Code 傳遞您傳回的說明，而不進行重寫，即使另一個 hook 重寫輸出
2239 2239
2240<Warning>2240<Warning>
2241 分類器將您放在 `classifierContext` 中的內容讀取為來自託管工作階段的應用程式的資訊，因此不要將不受信任的工具輸出或第三方文字複製到其中。將說明保持為關於此一個呼叫的簡短聲明，例如關於其來源的事實或使用者關於它的陳述；不要使用欄位傳遞不相關的訊息或事件流。2241 分類器將您放在 `classifierContext` 中的內容讀取為來自託管工作階段的應用程式的資訊，因此不要將不受信任的工具輸出或第三方文字複製到其中。將說明保持為關於此一個呼叫的簡短聲明，例如關於其來源的事實或關於它的使用者陳述；不要使用欄位傳遞不相關的訊息或事件流。
2242</Warning>2242</Warning>
2243 2243
2244<h3 id="posttoolusefailure">2244<h3 id="posttoolusefailure">
2245 PostToolUseFailure2245 PostToolUseFailure
2246</h3>2246</h3>
2247 2247
2248在啟動執行的工具失敗時執行：工具拋出錯誤，或 MCP 工具返回錯誤結果。使用此來記錄失敗、發送警報或向 Claude 提供更正回饋。2248在開始執行的工具失敗時執行：工具拋出錯誤，或 MCP 工具傳回錯誤結果。使用此來記錄失敗、傳送警報或向 Claude 提供更正回饋。
2249 2249
2250在工具名稱上匹配，與 PreToolUse 相同的值。2250在工具名稱上匹配，與 PreToolUse 相同的值。
2251 2251
2252<Note>2252<Note>
2253 此事件不對執行前被拒絕的工具呼叫觸發：未知工具名稱、失敗架構或工具特定驗證的輸入，或權限拒絕。驗證拒絕作為 `tool_use_error` 結果返回，在 hooks 執行前發生，因此它們既不觸發 `PreToolUse` 也不觸發此事件。權限拒絕觸發 `PreToolUse` 但不觸發此事件；請參閱 [PermissionDenied](#permissiondenied)。2253 此事件不會對執行前被拒絕的工具呼叫觸發：未知工具名稱、失敗架構或工具特定驗證的輸入，或權限拒絕。驗證拒絕作為 `tool_use_error` 結果傳回，發生在 hooks 執行之前，因此它們既不觸發 `PreToolUse` 也不觸發此事件。權限拒絕觸發 `PreToolUse` 但不觸發此事件；請參閱 [PermissionDenied](#permissiondenied)。
2254</Note>2254</Note>
2255 2255
2256<h4 id="posttoolusefailure-input">2256<h4 id="posttoolusefailure-input">
2257 PostToolUseFailure 輸入2257 PostToolUseFailure 輸入
2258</h4>2258</h4>
2259 2259
2260PostToolUseFailure hooks 接收與 PostToolUse 相同的 `tool_name` 和 `tool_input` 欄位，以及作為頂級欄位的錯誤資訊。對於 MCP 工具，它們也接收 [`mcp_server`](#pretooluse-input) 物件。例如，失敗的 `npm test` 命令可能傳遞：2260PostToolUseFailure hooks 接收與 PostToolUse 相同的 `tool_name` 和 `tool_input` 欄位，以及錯誤資訊作為頂級欄位。對於 MCP 工具，它們也接收 [`mcp_server`](#pretooluse-input) 物件。例如，失敗的 `npm test` 命令可能傳遞：
2261 2261
2262```json theme={null}2262```json theme={null}
2263{2263{
2279```2279```
2280 2280
2281| 欄位 | 描述 |2281| 欄位 | 描述 |
2282| :------------- | :------------------------------------------------------------------------- |2282| :------------- | :-------------------------------------------------------------------------- |
2283| `error` | 描述出錯內容的字串。格式取決於失敗的工具 |2283| `error` | 描述出錯內容的字串。格式取決於失敗的工具 |
2284| `is_interrupt` | 可選布林值。當失敗作為中止而不是工具報告的錯誤到達 Claude Code 時為 True。取消執行中的工具不觸發此 hook；工具結果攜帶中斷訊息 |2284| `is_interrupt` | 可選布林值。當失敗作為中止而不是工具報告的錯誤到達 Claude Code 時為 True。取消執行中的工具不會觸發此 hook；工具結果攜帶中斷訊息 |
2285| `duration_ms` | 可選。工具執行時間（毫秒）。不包括權限提示和 PreToolUse hooks 中花費的時間 |2285| `duration_ms` | 可選。工具執行時間（毫秒）。不包括權限提示和 PreToolUse hooks 中花費的時間 |
2286 2286
2287`error` 字串通常是 Claude 作為失敗工具結果接收的相同文字。其格式因工具和失敗而異。根據 `tool_name`、`is_interrupt` 和第一行 `Exit code N` 鍵入您的 hook；將字串的其餘部分視為顯示文字，而不是穩定格式。2287`error` 字串通常與 Claude 接收的失敗工具結果相同。其格式因工具和失敗而異。在 `tool_name`、`is_interrupt` 和第一行 `Exit code N` 上鍵入您的 hook；將字串的其餘部分視為顯示文字，而不是穩定格式。
2288 2288
2289* 對於 Bash 和 PowerShell，執行並退出的命令產生第一行 `Exit code N`，然後是命令產生的任何輸出作為一個區塊，其中 stdout 和 stderr 交錯2289* 對於 Bash 和 PowerShell，執行並退出的命令會產生第一行 `Exit code N`，然後是命令產生的任何輸出作為一個區塊，stdout 和 stderr 交錯
2290* 有效負載也可能攜帶裸失敗訊息，沒有退出代碼行，當 Claude Code 無法啟動 shell 程序本身時2290* 有效負載也可能攜帶裸失敗訊息，沒有退出代碼行，當 Claude Code 無法啟動 shell 程序本身時
2291* Claude Code 在 `... [N characters truncated] ...` 標記周圍中間截斷長字串，並可以插入自己的行，例如 `Command timed out after 2m 0s`2291* Claude Code 中間截斷長字串，圍繞 `... [N characters truncated] ...` 標記，並可以插入自己的行，例如 `Command timed out after 2m 0s`
2292 2292
2293<h4 id="posttoolusefailure-decision-control">2293<h4 id="posttoolusefailure-decision-control">
2294 PostToolUseFailure 決策控制2294 PostToolUseFailure 決策控制
2295</h4>2295</h4>
2296 2296
2297`PostToolUseFailure` hooks 可以在工具失敗後向 Claude 提供背景資訊。除了所有 hooks 可用的 [JSON 輸出欄位](#json-output) 外，您的 hook 指令碼可以返回這些事件特定欄位：2297`PostToolUseFailure` hooks 可以在工具失敗後向 Claude 提供背景資訊。除了 [所有 hooks 可用的 JSON 輸出欄位](#json-output) 外，您的 hook 指令碼可以傳回這些事件特定的欄位：
2298 2298
2299| 欄位 | 描述 |2299| 欄位 | 描述 |
2300| :------------------ | :--------------------------------------------------------------------- |2300| :------------------ | :--------------------------------------------------------------------- |
2313 PostToolBatch2313 PostToolBatch
2314</h3>2314</h3>
2315 2315
2316在批次中的每個工具呼叫都已解決後執行一次，在 Claude Code 發送下一個請求給模型之前。`PostToolUse` 每個工具執行一次，這意味著當 Claude 進行平行工具呼叫時它並發執行。`PostToolBatch` 恰好執行一次，包含完整批次，因此它是注入取決於執行的工具集而不是任何單個工具的背景資訊的正確位置。此事件沒有匹配器。2316在批次中的每個工具呼叫都已解決後執行一次，在 Claude Code 傳送下一個請求給模型之前。`PostToolUse` 每個工具執行一次，這意味著當 Claude 進行平行工具呼叫時它並發執行。`PostToolBatch` 恰好執行一次，具有完整批次，因此它是注入取決於執行的工具集而不是任何單個工具的背景資訊的正確位置。此事件沒有匹配器。
2317 2317
2318<h4 id="posttoolbatch-input">2318<h4 id="posttoolbatch-input">
2319 PostToolBatch 輸入2319 PostToolBatch 輸入
2320</h4>2320</h4>
2321 2321
2322除了 [常見輸入欄位](#common-input-fields) 外，PostToolBatch hooks 還會接收 `tool_calls`，一個描述批次中每個工具呼叫的陣列：2322除了 [常見輸入欄位](#common-input-fields) 外，PostToolBatch hooks 接收 `tool_calls`，一個描述批次中每個工具呼叫的陣列：
2323 2323
2324```json theme={null}2324```json theme={null}
2325{2325{
2345}2345}
2346```2346```
2347 2347
2348`tool_response` 包含模型在對應 `tool_result` 區塊中接收的相同內容。該值是序列化字串或內容區塊陣列，完全如工具發出的一樣。對於 `Read`，這意味著行號前綴文字而不是原始檔案內容。回應可能很大，因此僅解析您需要的欄位。2348`tool_response` 包含模型在對應 `tool_result` 區塊中接收的相同內容。該值是序列化字串或內容區塊陣列，完全如工具發出的。對於 `Read`，這意味著行號前綴文字，而不是原始檔案內容。回應可能很大，因此僅解析您需要的欄位。
2349 2349
2350<Note>2350<Note>
2351 `tool_response` 形狀與 `PostToolUse` 的不同。`PostToolUse` 傳遞工具的結構化 `Output` 物件，例如 `Write` 的 `{filePath: "...", type: "create"}`；`PostToolBatch` 傳遞模型看到的序列化 `tool_result` 內容。2351 `tool_response` 形狀與 `PostToolUse` 的不同。`PostToolUse` 傳遞工具的結構化 `Output` 物件，例如 `Write` 的 `{filePath: "...", type: "create"}`；`PostToolBatch` 傳遞序列化 `tool_result` 內容模型看到的。
2352</Note>2352</Note>
2353 2353
2354<h4 id="posttoolbatch-decision-control">2354<h4 id="posttoolbatch-decision-control">
2355 PostToolBatch 決策控制2355 PostToolBatch 決策控制
2356</h4>2356</h4>
2357 2357
2358`PostToolBatch` hooks 可以為 Claude 注入背景資訊。除了所有 hooks 可用的 [JSON 輸出欄位](#json-output) 外，您的 hook 指令碼可以返回這些事件特定欄位：2358`PostToolBatch` hooks 可以為 Claude 注入背景資訊。除了 [所有 hooks 可用的 JSON 輸出欄位](#json-output) 外，您的 hook 指令碼可以傳回這些事件特定的欄位：
2359 2359
2360| 欄位 | 描述 |2360| 欄位 | 描述 |
2361| :------------------ | :------------------------------------------------------------------------------------------------------ |2361| :------------------ | :------------------------------------------------------------------------------------------------------- |
2362| `additionalContext` | 在下一個模型呼叫之前注入一次的背景資訊字串。請參閱 [為 Claude 新增背景資訊](#add-context-for-claude)，了解傳遞詳細資訊、要放入其中的內容以及恢復的工作階段如何處理過去的值 |2362| `additionalContext` | 在下一個模型呼叫之前注入一次的背景資訊字串。請參閱 [為 Claude 新增背景資訊](#add-context-for-claude)，了解傳遞詳細資訊、要放入其中的內容，以及恢復的工作階段如何處理過去的值 |
2363 2363
2364```json theme={null}2364```json theme={null}
2365{2365{
2370}2370}
2371```2371```
2372 2372
2373返回 `decision: "block"` 或 `continue: false` 在下一個模型呼叫之前停止代理迴圈。阻止訊息來自 JSON `reason` 或 `stopReason`，或來自退出 2 時的 stderr。您在文字記錄中看到它作為警告，它保留在對話中，因此 Claude 在對話繼續時看到它。2373傳回 `decision: "block"` 或 `continue: false` 在下一個模型呼叫之前停止代理迴圈。阻止訊息來自 JSON `reason` 或 `stopReason`，或來自退出 2 的 stderr。您在文字記錄中看到它作為警告，它保留在對話中，因此當對話繼續時 Claude 看到它。
2374 2374
2375<h3 id="permissiondenied">2375<h3 id="permissiondenied">
2376 PermissionDenied2376 PermissionDenied
2377</h3>2377</h3>
2378 2378
2379在 [自動模式](/docs/zh-TW/permission-modes#eliminate-prompts-with-auto-mode) 拒絕工具呼叫時執行，包括當它拒絕而沒有分類器判決時，因為 [與自動模式分開的安全檢查拒絕了分類器自己的請求](/docs/zh-TW/errors#auto-mode-cannot-determine-the-safety-of-an-action) 或其回應未解析。此 hook 僅在自動模式中觸發：當您手動拒絕權限對話、`PreToolUse` hook 阻止呼叫或 `deny` 規則匹配時不執行。使用它來記錄拒絕、調整設定或告訴模型它可能重試工具呼叫。2379在 [自動模式](/docs/zh-TW/permission-modes#eliminate-prompts-with-auto-mode) 拒絕工具呼叫時執行，包括當它拒絕而沒有分類器判決時，因為 [與自動模式分開的安全檢查拒絕了分類器自己的請求](/docs/zh-TW/errors#auto-mode-cannot-determine-the-safety-of-an-action) 或其回應沒有解析。此 hook 僅在自動模式中觸發：當您手動拒絕權限對話、`PreToolUse` hook 阻止呼叫或 `deny` 規則匹配時，它不執行。使用它來記錄拒絕、調整配置或告訴模型它可能重試工具呼叫。
2380 2380
2381在工具名稱上匹配，與 PreToolUse 相同的值。2381在工具名稱上匹配，與 PreToolUse 相同的值。
2382 2382
2384 PermissionDenied 輸入2384 PermissionDenied 輸入
2385</h4>2385</h4>
2386 2386
2387除了 [常見輸入欄位](#common-input-fields) 外，PermissionDenied hooks 還會接收 `tool_name`、`tool_input`、`tool_use_id` 和 `reason`。對於 MCP 工具，它們也接收 [`mcp_server`](#pretooluse-input) 物件。2387除了 [常見輸入欄位](#common-input-fields) 外，PermissionDenied hooks 接收 `tool_name`、`tool_input`、`tool_use_id` 和 `reason`。對於 MCP 工具，它們也接收 [`mcp_server`](#pretooluse-input) 物件。
2388 2388
2389```json theme={null}2389```json theme={null}
2390{2390{
2404```2404```
2405 2405
2406| 欄位 | 描述 |2406| 欄位 | 描述 |
2407| :------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |2407| :------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
2408| `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` |2408| `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` |
2409 2409
2410<h4 id="permissiondenied-decision-control">2410<h4 id="permissiondenied-decision-control">
2411 PermissionDenied 決策控制2411 PermissionDenied 決策控制
2412</h4>2412</h4>
2413 2413
2414PermissionDenied hooks 可以告訴模型它可能重試被拒絕的工具呼叫。返回一個 JSON 物件，其中 `hookSpecificOutput.retry` 設定為 `true`：2414PermissionDenied hooks 可以告訴模型它可能重試被拒絕的工具呼叫。傳回一個 JSON 物件，其 `hookSpecificOutput.retry` 設定為 `true`：
2415 2415
2416```json theme={null}2416```json theme={null}
2417{2417{
2422}2422}
2423```2423```
2424 2424
2425當 `retry` 為 `true` 時，Claude Code 向對話新增一條訊息，告訴模型它可能重試工具呼叫。Claude Code 不反轉拒絕本身。如果您的 hook 不返回 JSON 或返回 `retry: false`，拒絕成立，模型接收原始拒絕訊息。2425當 `retry` 為 `true` 時，Claude Code 向對話新增一條訊息，告訴模型它可能重試工具呼叫。Claude Code 不反轉拒絕本身。如果您的 hook 不傳回 JSON，或傳回 `retry: false`，拒絕成立，模型接收原始拒絕訊息。
2426 2426
2427當分類器對動作 [沒有判決](/docs/zh-TW/errors#auto-mode-cannot-determine-the-safety-of-an-action) 時，Claude Code 忽略 `retry: true`：其回應未解析，或與自動模式分開的安全檢查拒絕了分類器自己的請求。對於這些拒絕，Claude Code 已經在拒絕訊息中告訴模型是否稍後重試或繼續。2427當分類器對動作產生 [無判決](/docs/zh-TW/errors#auto-mode-cannot-determine-the-safety-of-an-action) 時，Claude Code 忽略 `retry: true`：其回應沒有解析，或與自動模式分開的安全檢查拒絕了分類器自己的請求。對於這些拒絕，Claude Code 已在拒絕訊息中告訴模型是否稍後重試或繼續。
2428 2428
2429<h3 id="notification">2429<h3 id="notification">
2430 Notification2430 Notification
2431</h3>2431</h3>
2432 2432
2433在 Claude Code 發送通知時執行。在通知類型上匹配。省略匹配器以對所有通知類型執行 hooks。2433在 Claude Code 傳送通知時執行。在通知類型上匹配。省略匹配器以對所有通知類型執行 hooks。
2434 2434
2435即使桌面通知已關閉，您也會接收這些 hook 事件：`preferredNotifChannel` 設定（包括 `notifications_disabled`）僅更改您如何被警報，而不是您的 hook 是否執行。2435即使桌面通知關閉，您也會接收這些 hook 事件：`preferredNotifChannel` 設定（包括 `notifications_disabled`）僅更改您如何被警報，而不是您的 hook 是否執行。
2436 2436
2437| 匹配器 | 何時觸發 |2437| 匹配器 | 何時觸發 |
2438| :--------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |2438| :--------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
2439| `permission_prompt` | Claude 需要您核准工具使用或沙箱命令的 [網路請求](/docs/zh-TW/sandboxing#network-isolation)，提示已等待約六秒 |2439| `permission_prompt` | Claude 需要您核准工具使用或沙箱命令的 [網路請求](/docs/zh-TW/sandboxing#network-isolation)，提示已等待約六秒 |
2440| `idle_prompt` | Claude 約 60 秒前完成回應，您自那以後未輸入 |2440| `idle_prompt` | Claude 約 60 秒前完成回應，您自那以後沒有輸入 |
2441| `auth_success` | 驗證完成 |2441| `auth_success` | 驗證完成 |
2442| `elicitation_dialog` | MCP 伺服器開啟引出表單，您約六秒未輸入 |2442| `elicitation_dialog` | MCP 伺服器開啟引誘表單，您約六秒沒有輸入 |
2443| `elicitation_url_dialog` | MCP 伺服器要求您開啟瀏覽器 URL，您約六秒未輸入 |2443| `elicitation_url_dialog` | MCP 伺服器要求您開啟瀏覽器 URL，您約六秒沒有輸入 |
2444| `elicitation_complete` | MCP 伺服器報告 [URL 模式引出](#elicitation-input) 完成 |2444| `elicitation_complete` | MCP 伺服器報告 [URL 模式引誘](#elicitation-input) 完成 |
2445| `elicitation_response` | MCP 引出回應發送回伺服器 |2445| `elicitation_response` | MCP 引誘回應傳送回伺服器 |
2446| `agent_needs_input` | 背景工作階段在 [代理檢視](/docs/zh-TW/agent-view) 在終端中開啟時開始等待您的輸入，或目前工作階段詢問您 [代理團隊隊友的終端設定問題](/docs/zh-TW/agent-teams#choose-a-display-mode)，您約六秒未輸入 |2446| `agent_needs_input` | 背景工作階段在 [agent view](/docs/zh-TW/agent-view) 在終端中開啟時開始等待您的輸入，或目前工作階段詢問您 [agent team](/docs/zh-TW/agent-teams) 隊友的終端設定問題，您約六秒沒有輸入 |
2447| `agent_completed` | 背景工作階段完成或失敗。僅在 [代理檢視](/docs/zh-TW/agent-view) 在終端中開啟時觸發 |2447| `agent_completed` | 背景工作階段完成或失敗。僅在 [agent view](/docs/zh-TW/agent-view) 在終端中開啟時觸發 |
2448| `quota_auto_resume_fired` | Claude Code 在 claude.ai 使用限制暫停後繼續您的任務：在重設時，或更早當您在 Claude Code 中執行某事時，例如新增使用額度、升級計畫或切換模型，使使用可用，搭配 [模型設定例外](/docs/zh-TW/interactive-mode#wait-for-a-usage-limit-to-reset) |2448| `quota_auto_resume_fired` | Claude Code 在 claude.ai 使用限制暫停後繼續您的任務：在重設時，或更早當您在 Claude Code 中做某事時，例如新增使用額度、升級您的計畫或切換模型，使使用可用，具有 [模型設定例外](/docs/zh-TW/interactive-mode#wait-for-a-usage-limit-to-reset) |
2449| `quota_auto_resume_stale` | claude.ai 使用限制在您的電腦睡眠超過約 30 分鐘時重設。Claude Code 等待您按 `Enter` 而不是繼續。睡眠較短後它繼續並改為觸發 `quota_auto_resume_fired` |2449| `quota_auto_resume_stale` | claude.ai 使用限制在您的電腦睡眠超過約 30 分鐘時重設。Claude Code 等待您按 `Enter` 而不是繼續。在更短的睡眠後它繼續並改為觸發 `quota_auto_resume_fired` |
2450| `quota_auto_resume_disabled` | Claude Code 結束其對 claude.ai 使用限制的等待而不繼續您的任務：[`autoContinueAtUsageLimit`](/docs/zh-TW/settings-reference#autocontinueatusagelimit) 關閉或重設在 Claude Code 啟動的等待期間移動超過 24 小時，繼續的任務持續命中限制，或繼續在到達模型之前被阻止。當您按 `Esc` 或 `Ctrl+C` 或選擇 **不要自動繼續** 時不觸發 |2450| `quota_auto_resume_disabled` | Claude Code 結束其對 claude.ai 使用限制的等待而不繼續您的任務：[`autoContinueAtUsageLimit`](/docs/zh-TW/settings-reference#autocontinueatusagelimit) 關閉或重設在 Claude Code 自己啟動的等待期間移動超過 24 小時，繼續的任務持續命中限制，或繼續在到達模型之前被阻止。當您按 `Esc` 或 `Ctrl+C` 或選擇 **Don't continue automatically** 時不觸發 |
2451 2451
2452`agent_needs_input` 和 `agent_completed` 類型需要 Claude Code v2.1.198 或更新版本。2452`agent_needs_input` 和 `agent_completed` 類型需要 Claude Code v2.1.198 或更新版本。
2453 2453
2460<Note>2460<Note>
2461 `permission_prompt`、`idle_prompt`、`elicitation_dialog` 和 `elicitation_url_dialog` 類型與桌面通知共享其計時，因此在終端工作階段中您僅在您似乎遠離終端時看到它們：2461 `permission_prompt`、`idle_prompt`、`elicitation_dialog` 和 `elicitation_url_dialog` 類型與桌面通知共享其計時，因此在終端工作階段中您僅在您似乎遠離終端時看到它們：
2462 2462
2463 * 期望 `permission_prompt` 一旦您約六秒未輸入。計時器在權限提示出現時啟動，每次按鍵都會延遲它。若要在 Claude 要求許可使用工具時立即執行 hook，請改用 [PermissionRequest](#permissionrequest)。2463 * 期望 `permission_prompt` 一旦您約六秒沒有輸入。計時器在權限提示出現時啟動，每次按鍵都會延遲它。若要在 Claude 要求許可使用工具時立即執行 hook，請改用 [PermissionRequest](#permissionrequest)。
2464 * 期望 `idle_prompt` 約 60 秒後 Claude 完成回應，且僅在您自那以後未輸入時。Claude Code 在等待 claude.ai 使用限制重設時不發送 `idle_prompt`。等待結束時，其中一個 `quota_auto_resume_*` 類型改為觸發。2464 * 期望 `idle_prompt` 約 60 秒後 Claude 完成回應，並且僅當您自那以後沒有輸入時。Claude Code 在等待 claude.ai 使用限制重設時不傳送 `idle_prompt`。當等待自己結束時，其中一個 `quota_auto_resume_*` 類型觸發。
2465 * 期望 `elicitation_dialog` 用於引出表單，或 `elicitation_url_dialog` 用於瀏覽器 URL 請求，一旦您約六秒未輸入。兩者共享與 `permission_prompt` 相同的六秒閘門：計時器在對話出現時啟動，每次按鍵都會延遲它。2465 * 期望 `elicitation_dialog` 對於引誘表單，或 `elicitation_url_dialog` 對於瀏覽器 URL 請求，一旦您約六秒沒有輸入。兩者共享與 `permission_prompt` 相同的六秒閘門：計時器在對話出現時啟動，每次按鍵都會延遲它。
2466 2466
2467 在另一個對話在螢幕上時到達的權限請求或引出保持相同的六秒閘門，從請求到達時計時。其通知可以在請求仍在開啟對話後面等待時到達您。2467 在另一個對話在螢幕上時到達的權限請求或引誘與開啟的請求保持相同的六秒閘門，從請求到達時計時。其通知可以在請求仍在開啟對話後面等待時到達您。
2468</Note>2468</Note>
2469 2469
2470Claude Code 在發送權限請求給 Agent SDK 的 [`canUseTool` 回呼](/docs/zh-TW/agent-sdk/user-input) 的工作階段中以不同方式計時 `permission_prompt`，這是 Claude Desktop 和 VS Code 擴充功能託管 Claude Code 的方式：2470Claude Code 在傳送權限請求給 Agent SDK 的 [`canUseTool` 回呼](/docs/zh-TW/agent-sdk/user-input) 的工作階段中以不同方式計時 `permission_prompt`，這是 Claude Desktop 和 VS Code 擴充功能如何託管 Claude Code 的方式：
2471 2471
2472* 期望 `permission_prompt` 約六秒後 Claude 要求許可。Claude Code 在您輸入時不延遲它。2472* 期望 `permission_prompt` 約六秒後 Claude 要求許可。Claude Code 在您輸入時不延遲它。
2473* 如果您或 [PermissionRequest](#permissionrequest) hook 更早回答，Claude Code 不執行 `permission_prompt`。2473* 如果您或 [PermissionRequest](#permissionrequest) hook 更早回答，Claude Code 不執行 `permission_prompt`。
2475 2475
2476在 v2.1.233 之前，`permission_prompt` 在這些工作階段中不觸發。2476在 v2.1.233 之前，`permission_prompt` 在這些工作階段中不觸發。
2477 2477
2478使用單獨的匹配器根據通知類型執行不同的處理程式。此設定在 Claude 需要權限核准時觸發權限特定警報指令碼，在 Claude 閒置時觸發不同的通知：2478使用單獨的匹配器根據通知類型執行不同的處理程式。此配置在 Claude 需要權限核准時觸發權限特定的警報指令碼，以及在 Claude 閒置時觸發不同的通知：
2479 2479
2480```json theme={null}2480```json theme={null}
2481{2481{
2508 Notification 輸入2508 Notification 輸入
2509</h4>2509</h4>
2510 2510
2511除了 [常見輸入欄位](#common-input-fields) 外，Notification hooks 還會接收 `message` 搭配通知文字、可選 `title` 和 `notification_type` 指示哪個類型觸發。2511除了 [常見輸入欄位](#common-input-fields) 外，Notification hooks 接收 `message` 與通知文字、可選 `title` 和 `notification_type` 指示哪個類型觸發。
2512 2512
2513```json theme={null}2513```json theme={null}
2514{2514{
2522}2522}
2523```2523```
2524 2524
2525Notification hooks 無法阻止或修改通知。Claude Code 捨棄它們的 `systemMessage` 和 `continue` 欄位，但仍然發出 [`terminalSequence`](#emit-terminal-notifications)，這是桌面通知範例所依賴的。Notification hooks 用於副作用，例如將通知轉發到外部服務。2525Notification hooks 無法阻止或修改通知。Claude Code 捨棄它們的 `systemMessage` 和 `continue` 欄位，但仍發出 [`terminalSequence`](#emit-terminal-notifications)，這是桌面通知範例所依賴的。Notification hooks 用於副作用，例如將通知轉發到外部服務。
2526 2526
2527<h3 id="subagentstart">2527<h3 id="subagentstart">
2528 SubagentStart2528 SubagentStart
2529</h3>2529</h3>
2530 2530
2531在 Claude 使用 Agent 工具生成子代理時執行，當 Claude [恢復子代理](/docs/zh-TW/sub-agents#resume-subagents) 時，以及每次進程內 [代理團隊](/docs/zh-TW/agent-teams) 隊友處理新訊息時執行。支援匹配器以按代理類型名稱篩選。對於內建代理，這是代理名稱，例如 `general-purpose`、`Explore` 或 `Plan`。對於 [自訂子代理](/docs/zh-TW/sub-agents)，這是代理 frontmatter 中的 `name` 欄位，而不是檔案名稱。2531在 Claude 使用 Agent 工具生成子代理時執行，當 Claude [恢復子代理](/docs/zh-TW/sub-agents#resume-subagents) 時，以及每次進程內 [agent team](/docs/zh-TW/agent-teams) 隊友處理新訊息時執行。支援匹配器以按代理類型名稱篩選。對於內建代理，這是代理名稱，例如 `general-purpose`、`Explore` 或 `Plan`。對於 [自訂子代理](/docs/zh-TW/sub-agents)，這是代理 frontmatter 中的 `name` 欄位，而不是檔案名稱。
2532 2532
2533對於由 [外掛](/docs/zh-TW/plugins) 提供的子代理，代理類型是外掛範圍識別碼，例如 `my-plugin:reviewer`，而不是裸 frontmatter 名稱。冒號將外掛範圍名稱放在正規表達式路徑上，因此使用 `^` 和 `$` 錨定匹配器以進行精確匹配：`^my-plugin:reviewer$`。2533對於由 [外掛](/docs/zh-TW/plugins) 提供的子代理，代理類型是外掛範圍的識別碼，例如 `my-plugin:reviewer`，而不是裸 frontmatter 名稱。冒號將外掛範圍的名稱放在正規表達式路徑上，因此使用 `^` 和 `$` 錨定匹配器以進行精確匹配：`^my-plugin:reviewer$`。
2534 2534
2535<h4 id="subagentstart-input">2535<h4 id="subagentstart-input">
2536 SubagentStart 輸入2536 SubagentStart 輸入
2537</h4>2537</h4>
2538 2538
2539除了 [常見輸入欄位](#common-input-fields) 外，SubagentStart hooks 還會接收 `agent_id` 搭配子代理的唯一識別碼和 `agent_type` 搭配匹配器篩選的代理名稱。2539除了 [常見輸入欄位](#common-input-fields) 外，SubagentStart hooks 接收 `agent_id` 與子代理的唯一識別碼和 `agent_type` 與匹配器篩選的代理名稱。
2540 2540
2541```json theme={null}2541```json theme={null}
2542{2542{
2549}2549}
2550```2550```
2551 2551
2552SubagentStart hooks 無法阻止子代理建立，但它們可以將背景資訊注入到子代理中。除了所有 hooks 可用的 [JSON 輸出欄位](#json-output) 外，您可以返回：2552SubagentStart hooks 無法阻止子代理建立，但它們可以將背景資訊注入子代理。除了 [所有 hooks 可用的 JSON 輸出欄位](#json-output) 外，您可以傳回：
2553 2553
2554| 欄位 | 描述 |2554| 欄位 | 描述 |
2555| :------------------ | :----------------------------------------------------------------------------- |2555| :------------------ | :----------------------------------------------------------------------------- |
2564}2564}
2565```2565```
2566 2566
2567當 hook 再次為相同子代理執行時，Claude Code 僅在子代理的背景資訊還不包含早期執行副本時注入返回的背景資訊。在啟動時注入的副本保留在位置，保持子代理的 [prompt cache](/docs/zh-TW/prompt-caching#subagents-and-the-cache) 完整。在 [自動壓縮](/docs/zh-TW/sub-agents#auto-compaction) 捨棄該副本後，Claude Code 在下一次執行時再次注入背景資訊。2567當 hook 再次對同一子代理執行時，Claude Code 僅在子代理的背景資訊還不包含來自較早執行的複本時注入傳回的背景資訊。在啟動時注入的複本保留在位置，保持子代理的 [prompt cache](/docs/zh-TW/prompt-caching#subagents-and-the-cache) 完整。在 [自動壓縮](/docs/zh-TW/sub-agents#auto-compaction) 捨棄該複本後，Claude Code 再次注入下一次執行的背景資訊。
2568 2568
2569<h3 id="subagentstop">2569<h3 id="subagentstop">
2570 SubagentStop2570 SubagentStop
2576 SubagentStop 輸入2576 SubagentStop 輸入
2577</h4>2577</h4>
2578 2578
2579除了 [常見輸入欄位](#common-input-fields) 外，SubagentStop hooks 還會接收 `stop_hook_active`、`agent_id`、`agent_type`、`agent_transcript_path` 和 `last_assistant_message`。`agent_type` 欄位是用於匹配器篩選的值。`transcript_path` 是主工作階段的文字記錄，而 `agent_transcript_path` 是子代理自己的文字記錄，儲存在巢狀 `subagents/` 資料夾中。`last_assistant_message` 欄位包含子代理最終回應的文字內容，因此 hooks 可以存取它而不解析文字記錄檔案。2579除了 [常見輸入欄位](#common-input-fields) 外，SubagentStop hooks 接收 `stop_hook_active`、`agent_id`、`agent_type`、`agent_transcript_path` 和 `last_assistant_message`。`agent_type` 欄位是用於匹配器篩選的值。`transcript_path` 是主工作階段的文字記錄，而 `agent_transcript_path` 是子代理自己的文字記錄，儲存在巢狀 `subagents/` 資料夾中。`last_assistant_message` 欄位包含子代理最終回應的文字內容，因此 hooks 可以存取它而不解析文字記錄檔案。
2580 2580
2581在 Claude Code v2.1.271 或更新版本上，使用 [`SubagentHandback`](/docs/zh-TW/tools-reference) 工具執行的子代理在停止之前透過該工具傳遞其報告。`last_assistant_message` 欄位然後保留子代理的結束文字（如果有），這不是傳遞的報告。報告是該呼叫的 `message` 輸入，`PreToolUse` 或 `PostToolUse` hook 在 `SubagentHandback` 上匹配時接收為 `tool_input.message`。2581並非每個 SubagentStop 事件都來自 Claude 生成的子代理。Claude Code 也為其某些自己的功能執行內部代理，例如 [prompt suggestions](/docs/zh-TW/interactive-mode#prompt-suggestions) 和 [`/btw` side questions](/docs/zh-TW/interactive-mode#side-questions-with-%2Fbtw)，SubagentStop 在其中一個完成時觸發。對於這些事件，`agent_type` 是工作階段本身執行的代理名稱，例如使用 [`--agent`](/docs/zh-TW/cli-reference#cli-flags) 或 [`agent` 設定](/docs/zh-TW/settings-reference#agent) 設定的，以及當工作階段執行而不使用一個時的空字串。
2582 2582
2583SubagentStop hooks 也接收 [Stop 輸入](#stop-input) 下描述的 `background_tasks` 和 `session_crons` 陣列。兩個陣列的範圍是父工作階段，而不是子代理。2583不命名代理類型的 `matcher` 不匹配空 `agent_type`。其匹配器為省略、`""`、`"*"` 或是匹配空字串的正規表達式的 hook 也對具有空 `agent_type` 的事件執行。
2584
2585在 Claude Code v2.1.271 或更新版本上，使用 [`SubagentHandback`](/docs/zh-TW/tools-reference) 工具執行的子代理在停止之前透過該工具傳遞其報告。`last_assistant_message` 欄位然後保持子代理的結束文字（如果有），這不是傳遞的報告。報告是該呼叫的 `message` 輸入，`PreToolUse` 或 `PostToolUse` hook 匹配 `SubagentHandback` 在 `tool_input.message` 中接收。
2586
2587SubagentStop hooks 也接收 [Stop input](#stop-input) 下描述的 `background_tasks` 和 `session_crons` 陣列。兩個陣列的範圍是父工作階段，而不是子代理。
2584 2588
2585```json theme={null}2589```json theme={null}
2586{2590{
2599}2603}
2600```2604```
2601 2605
2602SubagentStop hooks 使用與 [Stop hooks](#stop-decision-control) 相同的決策控制格式，包括 `hookSpecificOutput.additionalContext` 搭配 `hookEventName` 設定為 `"SubagentStop"`，用於保持子代理執行的非錯誤回饋。返回 `decision: "block"` 搭配 `reason` 保持子代理執行並將 `reason` 作為其下一個指令傳遞給子代理。透過退出 2 阻止的 hook 以相同方式傳遞其 stderr 訊息。若要在子代理返回後將背景資訊注入到父工作階段，請改用 `Agent` 工具上的 [`PostToolUse`](#posttooluse) hook。2606SubagentStop hooks 使用與 [Stop hooks](#stop-decision-control) 相同的決策控制格式，包括 `hookSpecificOutput.additionalContext`，其 `hookEventName` 設定為 `"SubagentStop"`，用於保持子代理執行的非錯誤回饋。傳回 `decision: "block"` 搭配 `reason` 保持子代理執行並將 `reason` 作為其下一個指示傳遞給子代理。透過退出 2 阻止的 hook 以相同方式傳遞其 stderr 訊息。若要在子代理傳回後將背景資訊注入父工作階段，請改用 [PostToolUse](#posttooluse) hook 在 `Agent` 工具上。
2603 2607
2604<h3 id="taskcreated">2608<h3 id="taskcreated">
2605 TaskCreated2609 TaskCreated
2613 TaskCreated 輸入2617 TaskCreated 輸入
2614</h4>2618</h4>
2615 2619
2616除了 [常見輸入欄位](#common-input-fields) 外，TaskCreated hooks 還會接收 `task_id`、`task_subject` 和可選的 `task_description`、`teammate_name` 和 `team_name`。2620除了 [常見輸入欄位](#common-input-fields) 外，TaskCreated hooks 接收 `task_id`、`task_subject` 和可選的 `task_description`、`teammate_name` 和 `team_name`。
2617 2621
2618```json theme={null}2622```json theme={null}
2619{2623{
2641 TaskCreated 決策控制2645 TaskCreated 決策控制
2642</h4>2646</h4>
2643 2647
2644TaskCreated hook 可以透過兩種方式阻止建立。任一方式，Claude Code 刪除任務並將您的訊息返回給 Claude 作為工具的錯誤。Claude Code 忽略此事件中的 `continue: false`，Claude 繼續工作。2648TaskCreated hook 可以透過兩種方式阻止建立。任一方式，Claude Code 刪除任務並將您的訊息傳回給 Claude 作為工具的錯誤。Claude Code 忽略此事件的 `continue: false`，Claude 繼續工作。
2645 2649
2646* **退出代碼 2**：Claude Code 將 stderr 文字返回作為訊息。2650* **退出代碼 2**：Claude Code 將 stderr 文字傳回為訊息。
2647* **JSON `{"decision": "block", "reason": "..."}`**：Claude Code 將 `reason` 返回作為訊息。2651* **JSON `{"decision": "block", "reason": "..."}`**：Claude Code 將 `reason` 傳回為訊息。
2648 2652
2649此範例阻止主題不遵循所需格式的任務：2653此範例阻止主題不遵循所需格式的任務：
2650 2654
2665 TaskCompleted2669 TaskCompleted
2666</h3>2670</h3>
2667 2671
2668在任務被標記為完成時執行。這在兩種情況下觸發：當任何代理透過 TaskUpdate 工具明確標記任務為完成時，或當 [代理團隊](/docs/zh-TW/agent-teams) 隊友以進行中的任務完成其回合時。使用此來強制完成條件，例如通過測試或 lint 檢查，然後任務才能關閉。2672在任務被標記為完成時執行。這在兩種情況下觸發：當任何代理透過 TaskUpdate 工具明確標記任務為完成時，或當 [agent team](/docs/zh-TW/agent-teams) 隊友以進行中的任務完成其回合時。使用此來強制完成標準，例如通過測試或 lint 檢查，然後任務才能關閉。
2669 2673
2670TaskCompleted hooks 不支援匹配器，對每個出現觸發。2674TaskCompleted hooks 不支援匹配器，對每個出現觸發。
2671 2675
2673 TaskCompleted 輸入2677 TaskCompleted 輸入
2674</h4>2678</h4>
2675 2679
2676除了 [常見輸入欄位](#common-input-fields) 外，TaskCompleted hooks 還會接收 `task_id`、`task_subject` 和可選的 `task_description`、`teammate_name` 和 `team_name`。2680除了 [常見輸入欄位](#common-input-fields) 外，TaskCompleted hooks 接收 `task_id`、`task_subject` 和可選的 `task_description`、`teammate_name` 和 `team_name`。
2677 2681
2678```json theme={null}2682```json theme={null}
2679{2683{
2704 2708
2705TaskCompleted hooks 支援兩種方式來控制任務完成：2709TaskCompleted hooks 支援兩種方式來控制任務完成：
2706 2710
2707* **退出代碼 2**：任務未被標記為完成，stderr 訊息作為回饋反饋給模型。2711* **退出代碼 2**：任務未被標記為完成，stderr 訊息被反饋給模型作為回饋。
2708* **JSON `{"continue": false, "stopReason": "..."}`**：當隊友完成其回合觸發事件時，完全停止隊友，匹配 `Stop` hook 行為。`stopReason` 顯示給使用者。當 `TaskUpdate` 工具觸發事件時，Claude Code 忽略 `continue: false`；退出代碼 2 仍然阻止完成。2712* **JSON `{"continue": false, "stopReason": "..."}`**：當隊友完成其回合觸發事件時，完全停止隊友，匹配 `Stop` hook 行為。`stopReason` 顯示給使用者。當 `TaskUpdate` 工具觸發事件時，Claude Code 忽略 `continue: false`；退出代碼 2 仍然阻止完成。
2709 2713
2710此範例執行測試並在它們失敗時阻止任務完成：2714此範例執行測試並在它們失敗時阻止任務完成：
2730在主 Claude Code 代理完成回應時執行。如果停止發生是由於使用者中斷，則不執行。API 錯誤改為觸發 [StopFailure](#stopfailure)。2734在主 Claude Code 代理完成回應時執行。如果停止發生是由於使用者中斷，則不執行。API 錯誤改為觸發 [StopFailure](#stopfailure)。
2731 2735
2732<Tip>2736<Tip>
2733 [`/goal`](/docs/zh-TW/goal) 命令是工作階段範圍提示型 Stop hook 的內建快捷方式。當您想讓 Claude 在不編寫 hook 設定的情況下朝著條件繼續工作時使用它。2737 [`/goal`](/docs/zh-TW/goal) 命令是工作階段範圍提示型 Stop hook 的內建快捷方式。當您想讓 Claude 在不編寫 hook 配置的情況下朝著條件繼續工作時，使用它。
2734</Tip>2738</Tip>
2735 2739
2736<h4 id="stop-input">2740<h4 id="stop-input">
2737 Stop 輸入2741 Stop 輸入
2738</h4>2742</h4>
2739 2743
2740除了 [常見輸入欄位](#common-input-fields) 外，Stop hooks 還會接收 `stop_hook_active`、`last_assistant_message`、`background_tasks` 和 `session_crons`。`stop_hook_active` 欄位在 Claude Code 已作為 stop hook 的結果繼續時為 `true`。檢查此值或處理文字記錄以避免在永遠不會解決的條件上阻止。Claude Code 在 8 個連續阻止後覆寫 hook 並結束回合。2744除了 [常見輸入欄位](#common-input-fields) 外，Stop hooks 接收 `stop_hook_active`、`last_assistant_message`、`background_tasks` 和 `session_crons`。`stop_hook_active` 欄位在 Claude Code 已作為 stop hook 的結果繼續時為 `true`。檢查此值或處理文字記錄以避免在永遠不會解決的條件上阻止。Claude Code 在 8 個連續阻止後覆寫 hook 並結束回合。
2741 2745
2742`last_assistant_message` 欄位包含 Claude 最終回應的文字內容，因此 hooks 可以存取它而不解析文字記錄檔案。對於作用於剛完成回合的 hooks，例如朗讀或通知 hooks，使用此欄位而不是讀取 `transcript_path`：文字記錄檔案不保證在所有版本上的 Stop 時間包含最終訊息。2746`last_assistant_message` 欄位包含 Claude 最終回應的文字內容，因此 hooks 可以存取它而不解析文字記錄檔案。對於作用於剛完成回合的 hooks，例如朗讀或通知 hooks，使用此欄位而不是讀取 `transcript_path`：文字記錄檔案不保證在所有版本上的 Stop 時間包含最終訊息。
2743 2747
2744`background_tasks` 和 `session_crons` 陣列讓 hooks 區分「工作階段完成」與「工作階段暫停等待背景工作喚醒它」。當任務登錄可到達時兩個陣列都存在，當沒有任何內容在進行中或排程時為空。2748`background_tasks` 和 `session_crons` 陣列讓 hooks 區分「工作階段完成」與「工作階段暫停等待背景工作喚醒它」。當任務登錄可到達時兩個陣列都存在，當沒有任何東西在飛行或排程時為空。
2745 2749
2746`background_tasks` 中的每個項目描述一個進行中的任務並使用這些欄位：2750`background_tasks` 中的每個項目描述一個進行中的任務，並使用這些欄位：
2747 2751
2748| 欄位 | 描述 |2752| 欄位 | 描述 |
2749| :------------ | :----------------------------------------------------------------------------------------------------------------------------------------- |2753| :------------ | :------------------------------------------------------------------------------------------------------------------------------------------- |
2750| `id` | 任務識別碼 |2754| `id` | 任務識別碼 |
2751| `type` | 友善任務類型標籤，例如 `shell`、`subagent`、`monitor`、`workflow`、`teammate`、`cloud session` 或 `MCP task`。每個標籤識別哪個 Claude Code 功能建立了任務。對於無法識別的類型回退到原始判別式 |2755| `type` | 友善的任務類型標籤，例如 `shell`、`subagent`、`monitor`、`workflow`、`teammate`、`cloud session` 或 `MCP task`。每個標籤識別哪個 Claude Code 功能建立了任務。對於無法識別的類型，回退到原始判別式 |
2752| `status` | 目前任務狀態 |2756| `status` | 目前任務狀態 |
2753| `description` | 自由文字描述，上限為 1000 個字元，當剪裁時在字串中帶有 `… [+N chars]` 標記 |2757| `description` | 自由文字描述，上限 1000 個字元，當剪裁時在字串中有 `… [+N chars]` 標記 |
2754| `command` | Shell 命令行，上限為 1000 個字元。僅對 `shell` 任務出現 |2758| `command` | Shell 命令行，上限 1000 個字元。僅對 `shell` 任務出現 |
2755| `agent_type` | 子代理類型名稱。僅對 `subagent` 任務出現 |2759| `agent_type` | 子代理類型名稱。僅對 `subagent` 任務出現 |
2756| `server` | MCP 伺服器名稱。僅對 `monitor` 和 `MCP task` 任務出現 |2760| `server` | MCP 伺服器名稱。僅對 `monitor` 和 `MCP task` 任務出現 |
2757| `tool` | MCP 工具名稱。僅對 `monitor` 和 `MCP task` 任務出現 |2761| `tool` | MCP 工具名稱。僅對 `monitor` 和 `MCP task` 任務出現 |
2758| `name` | 工作流程名稱。僅對 `workflow` 任務出現 |2762| `name` | 工作流程名稱。僅對 `workflow` 任務出現 |
2759 2763
2760`session_crons` 中的每個項目描述一個工作階段範圍排程喚醒，來自 `CronCreate`、`ScheduleWakeup` 和 `/loop`：2764`session_crons` 中的每個項目描述一個工作階段範圍的排程喚醒，來自 `CronCreate`、`ScheduleWakeup` 和 `/loop`：
2761 2765
2762| 欄位 | 描述 |2766| 欄位 | 描述 |
2763| :---------- | :---------------------------------------------------- |2767| :---------- | :--------------------------------------------------- |
2764| `id` | Cron 任務識別碼 |2768| `id` | Cron 任務識別碼 |
2765| `schedule` | Cron 表達式，例如 `0 9 * * 1-5` |2769| `schedule` | Cron 表達式，例如 `0 9 * * 1-5` |
2766| `recurring` | 對於一次性喚醒（其排程編碼單個觸發時間）為 `false`，對於在每個匹配上重新觸發的任務為 `true` |2770| `recurring` | 對於其排程編碼單個觸發時間的一次性喚醒為 `false`，對於在每個匹配上重新觸發的任務為 `true` |
2767| `prompt` | Cron 觸發時提交的提示，上限為 1000 個字元，帶有相同的 `… [+N chars]` 標記 |2771| `prompt` | 當 cron 觸發時提交的提示，上限 1000 個字元，具有相同的 `… [+N chars]` 標記 |
2768 2772
2769此範例顯示一個 Stop 輸入，其中一個進行中的 shell 任務和一個循環 cron：2773此範例顯示一個 Stop 輸入，具有一個進行中的 shell 任務和一個循環 cron：
2770 2774
2771```json theme={null}2775```json theme={null}
2772{2776{
2801 Stop 決策控制2805 Stop 決策控制
2802</h4>2806</h4>
2803 2807
2804`Stop` 和 `SubagentStop` hooks 可以控制 Claude 是否繼續。除了所有 hooks 可用的 [JSON 輸出欄位](#json-output) 外，您的 hook 指令碼可以返回這些事件特定欄位：2808`Stop` 和 `SubagentStop` hooks 可以控制 Claude 是否繼續。除了 [所有 hooks 可用的 JSON 輸出欄位](#json-output) 外，您的 hook 指令碼可以傳回這些事件特定的欄位：
2805 2809
2806| 欄位 | 描述 |2810| 欄位 | 描述 |
2807| :------------------------------------- | :------------------------------------------------------------------------------------------ |2811| :------------------------------------- | :------------------------------------------------------------------------------------------- |
2808| `decision` | `"block"` 防止 Claude 停止。省略以允許 Claude 停止 |2812| `decision` | `"block"` 防止 Claude 停止。省略以允許 Claude 停止 |
2809| `reason` | 當 `decision` 為 `"block"` 時需要。告訴 Claude 為什麼它應該繼續 |2813| `reason` | 當 `decision` 為 `"block"` 時需要。告訴 Claude 為什麼它應該繼續 |
2810| `hookSpecificOutput.additionalContext` | Claude 的非錯誤回饋。對話繼續，以便 Claude 可以作用於它，但與 `decision: "block"` 不同，它在文字記錄中顯示為 hook 回饋而不是 hook 錯誤 |2814| `hookSpecificOutput.additionalContext` | Claude 的非錯誤回饋。對話繼續，以便 Claude 可以作用於它，但與 `decision: "block"` 不同，它在文字記錄中顯示為 hook 回饋，而不是 hook 錯誤 |
2811 2815
2812透過退出 2 阻止的 hook 路由方式與 `reason` 相同：Claude 接收 stderr 訊息作為為什麼它應該繼續的解釋。2816透過退出 2 阻止的 hook 以與 `reason` 相同的方式路由：Claude 接收 stderr 訊息作為為什麼它應該繼續的說明。
2813 2817
2814```json theme={null}2818```json theme={null}
2815{2819{
2818}2822}
2819```2823```
2820 2824
2821當 hook 按設計工作並給予 Claude 指導時使用 `additionalContext`，例如「在完成前執行測試套件」。它透過與 `decision: "block"` 相同的迴圈保護保持對話進行，即 `stop_hook_active` 輸入和 8 個連續繼續上限，但文字記錄將其標籤為 `Stop hook feedback`，不顯示 hook 錯誤通知：2825當 hook 按設計工作並給予 Claude 指導時，使用 `additionalContext`，例如「在完成前執行測試套件」。它透過與 `decision: "block"` 相同的迴圈保護保持對話進行，即 `stop_hook_active` 輸入和 8 個連續繼續上限，但文字記錄將其標籤為 `Stop hook feedback`，不顯示 hook 錯誤通知：
2822 2826
2823```json theme={null}2827```json theme={null}
2824{2828{
2833 StopFailure2837 StopFailure
2834</h3>2838</h3>
2835 2839
2836在回合因 API 錯誤而結束時執行，而不是 [Stop](#stop)。Claude Code 忽略 hook 的輸出和退出代碼，除了 [`terminalSequence`](#emit-terminal-notifications)。使用此來記錄失敗、發送警報或在 Claude 因速率限制、驗證問題或其他 API 錯誤而無法完成回應時採取恢復動作。2840在回合因 API 錯誤結束時執行，而不是 [Stop](#stop)。Claude Code 忽略 hook 的輸出和退出代碼，除了 [`terminalSequence`](#emit-terminal-notifications)。使用此來記錄失敗、傳送警報或在 Claude 因速率限制、驗證問題或其他 API 錯誤無法完成回應時採取復原動作。
2837 2841
2838<h4 id="stopfailure-input">2842<h4 id="stopfailure-input">
2839 StopFailure 輸入2843 StopFailure 輸入
2840</h4>2844</h4>
2841 2845
2842除了 [常見輸入欄位](#common-input-fields) 外，StopFailure hooks 還會接收 `error`、可選 `error_details` 和可選 `last_assistant_message`。`error` 欄位識別錯誤類型並用於匹配器篩選。2846除了 [常見輸入欄位](#common-input-fields) 外，StopFailure hooks 接收 `error`、可選 `error_details` 和可選 `last_assistant_message`。`error` 欄位識別錯誤類型，用於匹配器篩選。
2843 2847
2844| 欄位 | 描述 |2848| 欄位 | 描述 |
2845| :----------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |2849| :----------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
2846| `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` |2850| `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` |
2847| `error_details` | 關於錯誤的其他詳細資訊（如果可用） |2851| `error_details` | 關於錯誤的額外詳細資訊（如果可用） |
2848| `last_assistant_message` | 在對話中顯示的呈現錯誤文字。與 `Stop` 和 `SubagentStop` 不同，其中此欄位保留 Claude 的對話輸出，對於 `StopFailure` 它包含 API 錯誤字串本身，例如 `"API Error: Rate limit reached"` |2852| `last_assistant_message` | 在對話中顯示的呈現錯誤文字。與 `Stop` 和 `SubagentStop` 不同，其中此欄位保持 Claude 的對話輸出，對於 `StopFailure` 它包含 API 錯誤字串本身，例如 `"API Error: Rate limit reached"` |
2849 2853
2850```json theme={null}2854```json theme={null}
2851{2855{
2865 TeammateIdle2869 TeammateIdle
2866</h3>2870</h3>
2867 2871
2868在 [代理團隊](/docs/zh-TW/agent-teams) 隊友在完成其回合後即將閒置時執行。使用此來強制品質閘門，然後隊友停止工作，例如要求通過 lint 檢查或驗證輸出檔案存在。2872在 [agent team](/docs/zh-TW/agent-teams) 隊友在完成其回合後即將閒置時執行。使用此來強制品質閘門，然後隊友停止工作，例如要求通過 lint 檢查或驗證輸出檔案存在。
2869 2873
2870TeammateIdle hooks 不支援匹配器，對每個出現觸發。2874TeammateIdle hooks 不支援匹配器，對每個出現觸發。
2871 2875
2873 TeammateIdle 輸入2877 TeammateIdle 輸入
2874</h4>2878</h4>
2875 2879
2876除了 [常見輸入欄位](#common-input-fields) 外，TeammateIdle hooks 還會接收 `teammate_name` 和 `team_name`。2880除了 [常見輸入欄位](#common-input-fields) 外，TeammateIdle hooks 接收 `teammate_name` 和 `team_name`。
2877 2881
2878```json theme={null}2882```json theme={null}
2879{2883{
2898 2902
2899TeammateIdle hooks 支援兩種方式來控制隊友行為：2903TeammateIdle hooks 支援兩種方式來控制隊友行為：
2900 2904
2901* **退出代碼 2**：隊友接收 stderr 訊息作為回饋並繼續工作而不是閒置。2905* **退出代碼 2**：隊友接收 stderr 訊息作為回饋，並繼續工作而不是閒置。
2902* **JSON `{"continue": false, "stopReason": "..."}`**：完全停止隊友，匹配 `Stop` hook 行為。`stopReason` 顯示給使用者。2906* **JSON `{"continue": false, "stopReason": "..."}`**：完全停止隊友，匹配 `Stop` hook 行為。`stopReason` 顯示給使用者。
2903 2907
2904此範例檢查建置成品存在，然後允許隊友閒置：2908此範例檢查建置成品存在，然後允許隊友閒置：
2918 ConfigChange2922 ConfigChange
2919</h3>2923</h3>
2920 2924
2921在工作階段期間設定檔變更時執行。使用此來稽核設定變更、強制安全原則或阻止對設定檔的未授權修改。2925在工作階段期間配置檔案變更時執行。使用此來稽核設定變更、強制安全原則或阻止對配置檔案的未授權修改。
2922 2926
2923Claude Code 在設定檔、受管原則檔案或 skill 檔案變更時執行 ConfigChange hooks。對於受管原則，它僅在 `managed-settings.json` 或 `managed-settings.d/` 中的檔案變更時執行。它應用 [伺服器受管設定](/docs/zh-TW/server-managed-settings) 和對 macOS 受管偏好設定或 Windows 登錄原則的變更而不執行。在 WSL 上搭配 [`wslInheritsWindowsSettings`](/docs/zh-TW/settings-reference#wslinheritswindowssettings)，它也應用在其原則輪詢上變更的 Windows 端受管設定檔而不執行。2927Claude Code 在設定檔、受管原則檔案或 skill 檔案變更時執行 ConfigChange hooks。對於受管原則，它僅在 `managed-settings.json` 或 `managed-settings.d/` 中的檔案變更時執行。它應用 [伺服器受管設定](/docs/zh-TW/server-managed-settings) 和對 macOS 受管偏好設定或 Windows 登錄原則的變更，而不執行它們。在 WSL 上搭配 [`wslInheritsWindowsSettings`](/docs/zh-TW/settings-reference#wslinheritswindowssettings)，它也在其原則輪詢上應用變更的 Windows 端受管設定檔，而不執行它們。
2924 2928
2925匹配器篩選設定來源：2929匹配器篩選配置來源：
2926 2930
2927| 匹配器 | 何時觸發 |2931| 匹配器 | 何時觸發 |
2928| :----------------- | :----------------------------------------------------- |2932| :----------------- | :----------------------------------------------------- |
2932| `policy_settings` | `managed-settings.json` 或 `managed-settings.d/` 中的檔案變更 |2936| `policy_settings` | `managed-settings.json` 或 `managed-settings.d/` 中的檔案變更 |
2933| `skills` | `.claude/skills/` 中的 skill 檔案變更 |2937| `skills` | `.claude/skills/` 中的 skill 檔案變更 |
2934 2938
2935此範例記錄所有設定變更以進行安全稽核：2939此範例記錄所有配置變更以進行安全稽核：
2936 2940
2937```json theme={null}2941```json theme={null}
2938{2942{
2956 ConfigChange 輸入2960 ConfigChange 輸入
2957</h4>2961</h4>
2958 2962
2959除了 [常見輸入欄位](#common-input-fields) 外，ConfigChange hooks 還會接收 `source` 和可選的 `file_path`。`source` 欄位指示哪個設定類型變更，`file_path` 提供修改的特定檔案的路徑。2963除了 [常見輸入欄位](#common-input-fields) 外，ConfigChange hooks 接收 `source` 和可選的 `file_path`。`source` 欄位指示哪個配置類型變更，`file_path` 提供修改的特定檔案的路徑。
2960 2964
2961```json theme={null}2965```json theme={null}
2962{2966{
2973 ConfigChange 決策控制2977 ConfigChange 決策控制
2974</h4>2978</h4>
2975 2979
2976ConfigChange hooks 可以阻止設定變更生效。使用退出代碼 2 或 JSON `decision` 來防止變更。被阻止時，新設定不會套用到執行中的工作階段。2980ConfigChange hooks 可以阻止配置變更生效。使用退出代碼 2 或 JSON `decision` 來防止變更。當被阻止時，新設定不會套用到執行中的工作階段。
2977 2981
2978| 欄位 | 描述 |2982| 欄位 | 描述 |
2979| :--------- | :-------------------------- |2983| :--------- | :-------------------------- |
2980| `decision` | `"block"` 防止設定變更被套用。省略以允許變更 |2984| `decision` | `"block"` 防止配置變更被應用。省略以允許變更 |
2981| `reason` | 接受但永遠不顯示 |2985| `reason` | 接受但永遠不顯示 |
2982 2986
2983```json theme={null}2987```json theme={null}
2987}2991}
2988```2992```
2989 2993
2990`policy_settings` 變更無法被阻止。當機器上的受管設定檔變更時，Hooks 仍然對 `policy_settings` 來源觸發，因此您可以使用它們來記錄這些編輯，但任何阻止決策都被忽略。這確保企業受管設定始終生效。當 [伺服器受管設定](/docs/zh-TW/server-managed-settings) 到達或重新整理時，Claude Code 不執行 `ConfigChange` hooks。2994`policy_settings` 變更無法被阻止。當機器上的受管設定檔變更時，Hooks 仍對 `policy_settings` 來源觸發，因此您可以使用它們來記錄這些編輯，但任何阻止決策都會被忽略。這確保企業受管設定始終生效。當 [伺服器受管設定](/docs/zh-TW/server-managed-settings) 到達或重新整理時，Claude Code 不執行 `ConfigChange` hooks。
2991 2995
2992Claude Code 作用於 ConfigChange hook 的 JSON 輸出中的阻止決策，並捨棄 `systemMessage` 和 `continue`。被阻止的變更不向您或 Claude 呈現任何訊息，無論您是否使用 `reason` 或退出 2 時的 stderr 阻止。Claude Code 僅將一行寫入偵錯日誌。2996Claude Code 從 ConfigChange hook 的 JSON 輸出作用於阻止決策，並捨棄 `systemMessage` 和 `continue`。被阻止的變更不會向您或 Claude 呈現任何訊息，無論您使用 `reason` 還是退出 2 的 stderr 阻止。Claude Code 僅將一行寫入 debug log。
2993 2997
2994<h3 id="cwdchanged">2998<h3 id="cwdchanged">
2995 CwdChanged2999 CwdChanged
2996</h3>3000</h3>
2997 3001
2998在主對話中的 shell 命令變更工作目錄時執行，例如當 Claude 執行 `cd` 命令時。使用此來對目錄變更做出反應：重新載入環境變數、啟動專案特定工具鏈或自動執行設定指令碼。與 [FileChanged](#filechanged) 配對，用於 [direnv](https://direnv.net/) 等管理每個目錄環境的工具。3002在主對話中的 shell 命令變更工作目錄時執行，例如當 Claude 執行 `cd` 命令時。使用此來對目錄變更做出反應：重新載入環境變數、啟用專案特定的工具鏈，或自動執行設定指令碼。與 [FileChanged](#filechanged) 配對，用於 [direnv](https://direnv.net/) 等管理每個目錄環境的工具。
2999 3003
3000CwdChanged hooks 可以存取 [`CLAUDE_ENV_FILE`](#persist-environment-variables)。寫入該檔案的變數會保留到下一個 CwdChanged 事件，當 Claude Code 清除它們時。3004CwdChanged hooks 可以存取 [`CLAUDE_ENV_FILE`](#persist-environment-variables)。寫入該檔案的變數會保留到後續 Bash 命令，直到下一個 CwdChanged 事件，當 Claude Code 清除它們時。
3001 3005
3002CwdChanged 不支援匹配器，對每個出現觸發。3006CwdChanged 不支援匹配器，對每個出現觸發。
3003 3007
3005 CwdChanged 輸入3009 CwdChanged 輸入
3006</h4>3010</h4>
3007 3011
3008除了 [常見輸入欄位](#common-input-fields) 外，CwdChanged hooks 還會接收 `old_cwd` 和 `new_cwd`。3012除了 [常見輸入欄位](#common-input-fields) 外，CwdChanged hooks 接收 `old_cwd` 和 `new_cwd`。
3009 3013
3010```json theme={null}3014```json theme={null}
3011{3015{
3022 CwdChanged 輸出3026 CwdChanged 輸出
3023</h4>3027</h4>
3024 3028
3025除了所有 hooks 可用的 [JSON 輸出欄位](#json-output) 外，CwdChanged hooks 可以返回 `watchPaths` 以動態設定 [FileChanged](#filechanged) 監視的檔案路徑：3029除了 [所有 hooks 可用的 JSON 輸出欄位](#json-output) 外，CwdChanged hooks 可以傳回 `watchPaths` 以動態設定 [FileChanged](#filechanged) 監視的檔案路徑：
3026 3030
3027| 欄位 | 描述 |3031| 欄位 | 描述 |
3028| :----------- | :--------------------------------------------------------------------- |3032| :----------- | :----------------------------------------------------------- |
3029| `watchPaths` | 絕對路徑的陣列。替換目前的動態監視清單。您的 `matcher` 設定中的路徑始終被監視。返回空陣列以清除動態清單，這在進入新目錄時是典型的 |3033| `watchPaths` | 絕對路徑的陣列。替換目前的動態監視清單。來自您 `matcher` 配置的路徑始終被監視。進入新目錄時傳回空陣列是典型的 |
3030 3034
3031CwdChanged hooks 沒有決策控制。它們無法阻止目錄變更。3035CwdChanged hooks 沒有決策控制。它們無法阻止目錄變更。
3032 3036
3033Claude Code 從其 JSON 輸出讀取 `watchPaths` 和 `systemMessage`，並捨棄 `continue`。在互動式工作階段中，它將 `systemMessage` 顯示為簡短終端通知。訊息不到達 SDK 訊息流。3037Claude Code 從其 JSON 輸出讀取 `watchPaths` 和 `systemMessage`，並捨棄 `continue`。在互動式工作階段中，它將 `systemMessage` 顯示為簡短的終端通知。訊息不到達 SDK 訊息流。
3034 3038
3035<h3 id="directoryadded">3039<h3 id="directoryadded">
3036 DirectoryAdded3040 DirectoryAdded
3037</h3>3041</h3>
3038 3042
3039在您使用 `/add-dir` 命令在工作階段中期新增工作目錄後執行，或在 SDK 用戶端使用 `register_repo_root` 控制請求新增工作目錄後執行。使用此來準備新增的儲存庫，例如安裝其相依性。3043在您使用 `/add-dir` 命令在工作階段中新增工作目錄後執行，或在 SDK 用戶端使用 `register_repo_root` 控制請求新增一個後執行。使用此來準備新增的儲存庫，例如安裝其相依性。
3040 3044
3041Claude Code 在以下情況下不觸發此事件：3045Claude Code 在以下情況下不觸發此事件：
3042 3046
3044* 您在 `/permissions` Workspace 標籤上新增目錄3048* 您在 `/permissions` Workspace 標籤上新增目錄
3045* 您新增已是工作目錄或在其內部的目錄3049* 您新增已是工作目錄或在其內部的目錄
3046 3050
3047Claude Code 在重新整理沙箱和權限狀態後觸發 DirectoryAdded，因此沙箱工具在您的 hook 執行時已看到新目錄。Hook 命令本身執行未沙箱化。3051Claude Code 在重新整理 sandbox 和權限狀態後觸發 DirectoryAdded，因此沙箱工具在您的 hook 執行時已看到新目錄。Hook 命令本身執行未沙箱化。
3048 3052
3049Claude Code 不等待 hook：新增立即完成，hook 在背景執行，使用 600 秒預設逾時。3053Claude Code 不等待 hook：新增立即完成，hook 在背景執行，具有 600 秒的預設逾時。
3050 3054
3051匹配器篩選目錄的新增方式：3055匹配器篩選目錄的新增方式：
3052 3056
3059 DirectoryAdded 輸入3063 DirectoryAdded 輸入
3060</h4>3064</h4>
3061 3065
3062除了 [常見輸入欄位](#common-input-fields) 外，DirectoryAdded hooks 還會接收 `directory` 和 `source`。3066除了 [常見輸入欄位](#common-input-fields) 外，DirectoryAdded hooks 接收 `directory` 和 `source`。
3063 3067
3064| 欄位 | 描述 |3068| 欄位 | 描述 |
3065| :---------- | :------------------------------------------------------------------------ |3069| :---------- | :------------------------------------------------------------------------ |
3066| `directory` | 新增的目錄的絕對路徑 |3070| `directory` | 已新增目錄的絕對路徑 |
3067| `source` | 目錄如何被新增，`/add-dir` 為 `"slash_command"` 或 SDK 控制請求為 `"register_repo_root"` |3071| `source` | 目錄如何被新增，`/add-dir` 為 `"slash_command"` 或 SDK 控制請求為 `"register_repo_root"` |
3068 3072
3069```json theme={null}3073```json theme={null}
3079 3083
3080DirectoryAdded hooks 沒有決策控制。它們無法阻止新增，這在 hook 執行時已完成。Claude Code 從其 JSON 輸出捨棄 `continue` 欄位，並根據來源以不同方式呈現其餘部分：3084DirectoryAdded hooks 沒有決策控制。它們無法阻止新增，這在 hook 執行時已完成。Claude Code 從其 JSON 輸出捨棄 `continue` 欄位，並根據來源以不同方式呈現其餘部分：
3081 3085
3082* `slash_command`：Claude Code 將 hook 的 `systemMessage` 傳遞給 Claude 作為下一個對話回合的背景資訊，而不是向您顯示。失敗 hooks 的計數出現在文字記錄中。完整失敗輸出進入偵錯日誌3086* `slash_command`：Claude Code 將 hook 的 `systemMessage` 作為背景資訊傳遞給 Claude，在下一個對話回合上，而不是向您顯示。失敗 hooks 的計數出現在文字記錄中。完整失敗輸出進入 debug log
3083* `register_repo_root`：Claude Code 僅將 `systemMessage` 輸出和失敗輸出寫入偵錯日誌3087* `register_repo_root`：Claude Code 僅將 `systemMessage` 輸出和失敗輸出寫入 debug log
3084 3088
3085<h3 id="filechanged">3089<h3 id="filechanged">
3086 FileChanged3090 FileChanged
3087</h3>3091</h3>
3088 3092
3089在監視的檔案在磁碟上變更時執行。Claude Code 使用檔案系統監視器偵測變更，而不是檢查工具呼叫，因此無論什麼變更檔案，它都執行 hook：`Edit` 或 `Write` 工具呼叫、Claude 使用 `Bash` 執行的指令碼，或 Claude Code 外的程序。常見用途是在專案設定檔變更時重新載入環境變數。3093在監視的檔案在磁碟上變更時執行。Claude Code 使用檔案系統監視器偵測變更，而不是檢查工具呼叫，因此無論什麼變更檔案，它都執行 hook：`Edit` 或 `Write` 工具呼叫、Claude 使用 `Bash` 執行的指令碼，或 Claude Code 外的程序。常見用途是在專案配置檔案變更時重新載入環境變數。
3090 3094
3091此事件的 `matcher` 有兩個角色：3095此事件的 `matcher` 有兩個角色：
3092 3096
3093* **建立監視清單**：值在 `|` 上分割，每個段落註冊為工作目錄中的字面檔案名稱，因此 `".envrc|.env"` 監視恰好這兩個檔案。正規表達式模式在這裡不有用：`^\.env` 之類的值會監視字面名稱為 `^\.env` 的檔案。3097* **建立監視清單**：值在 `|` 上分割，每個段落註冊為工作目錄中的字面檔案名稱，因此 `".envrc|.env"` 恰好監視這兩個檔案。正規表達式模式在這裡不有用：`^\.env` 之類的值會監視字面名稱為 `^\.env` 的檔案。
3094* **篩選哪些 hooks 執行**：當監視的檔案變更時，相同的值使用標準 [匹配器規則](#matcher-patterns) 針對變更檔案的基名篩選哪些 hook 群組執行。3098* **篩選哪些 hooks 執行**：當監視的檔案變更時，相同的值使用標準 [匹配器規則](#matcher-patterns) 針對變更檔案的基名篩選哪個 hook 群組執行。
3095 3099
3096此範例在任何變更後規範化 `data.csv` 中的行結尾，包括 `Bash` 命令或外部指令碼重寫檔案：3100此範例在任何變更後正規化 `data.csv` 中的行結尾，包括 `Bash` 命令或外部指令碼重寫檔案：
3097 3101
3098```json theme={null}3102```json theme={null}
3099{3103{
3113}3117}
3114```3118```
3115 3119
3116Hook 從 [JSON 輸入](#filechanged-input) 的 `file_path` 欄位讀取變更檔案的絕對路徑，在 stdin 上。其 `grep` 守衛測試 `perl` 移除的相同內容，行尾的 CR，因此規範化後的執行退出而不觸及檔案。較鬆散的守衛迴圈永遠，因為 `perl -i` 重寫檔案即使它替換無內容，Claude Code 在每次重寫後執行 hook。將此指令碼儲存在 `/path/to/normalize-line-endings.sh` 並使其可執行：3120Hook 從 [JSON 輸入](#filechanged-input) 的 `file_path` 欄位讀取變更檔案的絕對路徑，在 stdin 上。其 `grep` 守衛測試與 `perl` 移除的相同，行尾的 CR，因此在正規化後執行退出而不觸及檔案。較鬆散的守衛會無限迴圈，因為 `perl -i` 重寫檔案，即使它替換任何東西，Claude Code 在每次重寫後執行 hook。將此指令碼儲存在 `/path/to/normalize-line-endings.sh` 並使其可執行：
3117 3121
3118```bash theme={null}3122```bash theme={null}
3119#!/bin/bash3123#!/bin/bash
3123fi3127fi
3124```3128```
3125 3129
3126若要確認 hook 有效，要求 Claude 使用 `Bash` 命令將 CRLF 行附加到 `data.csv`。Claude Code 執行 hook，檔案以 LF 結尾。3130若要確認 hook 有效，要求 Claude 使用 Bash 命令將 CRLF 行附加到 `data.csv`。Claude Code 執行 hook，檔案最終使用 LF 結尾。
3127 3131
3128若要監視您無法提前命名的檔案，請從 hook 返回 [`watchPaths`](#filechanged-output) 以動態更新監視清單。Claude Code 僅在某事命名要監視的檔案時啟動監視器，因此使用至少命名一個檔案的 FileChanged 群組播種清單，或使用 [SessionStart](#sessionstart-decision-control) 或 [CwdChanged](#cwdchanged) hook 返回 `watchPaths`。匹配器仍然篩選當監視的檔案變更時哪些 hook 群組執行，因此給處理動態路徑的群組一個省略的匹配器，它匹配每個監視的檔案並不向監視清單新增任何內容。`"*"` 匹配器也匹配每個檔案，但 Claude Code 在監視清單中註冊它，如同任何其他值，作為字面名稱為 `*` 的檔案。3132若要監視您無法提前命名的檔案，從 hook 傳回 [`watchPaths`](#filechanged-output) 以動態更新監視清單。Claude Code 僅在某事命名要監視的檔案時啟動監視器，因此使用命名至少一個檔案的 FileChanged 群組播種清單，或使用 [SessionStart](#sessionstart-decision-control) 或 [CwdChanged](#cwdchanged) hook 傳回 `watchPaths`。匹配器仍篩選當監視的檔案變更時哪個 hook 群組執行，因此給處理動態路徑的群組一個省略的匹配器，它匹配每個監視的檔案，並不向監視清單新增任何東西。`"*"` 匹配器也匹配每個檔案，但 Claude Code 像任何其他值一樣在監視清單中註冊它，作為字面名稱為 `*` 的檔案。
3129 3133
3130FileChanged hooks 可以存取 [`CLAUDE_ENV_FILE`](#persist-environment-variables)。寫入該檔案的變數會保留到下一個 [CwdChanged](#cwdchanged) 事件，當 Claude Code 清除它們時。3134FileChanged hooks 可以存取 [`CLAUDE_ENV_FILE`](#persist-environment-variables)。寫入該檔案的變數會保留到後續 Bash 命令，直到下一個 [CwdChanged](#cwdchanged) 事件，當 Claude Code 清除它們時。
3131 3135
3132<h4 id="filechanged-input">3136<h4 id="filechanged-input">
3133 FileChanged 輸入3137 FileChanged 輸入
3134</h4>3138</h4>
3135 3139
3136除了 [常見輸入欄位](#common-input-fields) 外，FileChanged hooks 還會接收 `file_path` 和 `event`。3140除了 [常見輸入欄位](#common-input-fields) 外，FileChanged hooks 接收 `file_path` 和 `event`。
3137 3141
3138| 欄位 | 描述 |3142| 欄位 | 描述 |
3139| :---------- | :-------------------------------------------------------- |3143| :---------- | :------------------------------------------------------- |
3140| `file_path` | 變更的檔案的絕對路徑 |3144| `file_path` | 變更檔案的絕對路徑 |
3141| `event` | 發生的情況：修改的檔案為 `"change"`、建立的檔案為 `"add"` 或刪除的檔案為 `"unlink"` |3145| `event` | 發生了什麼：修改檔案為 `"change"`、建立的檔案為 `"add"`，或刪除的檔案為 `"unlink"` |
3142 3146
3143```json theme={null}3147```json theme={null}
3144{3148{
3155 FileChanged 輸出3159 FileChanged 輸出
3156</h4>3160</h4>
3157 3161
3158除了所有 hooks 可用的 [JSON 輸出欄位](#json-output) 外，FileChanged hooks 可以返回 `watchPaths` 以動態更新監視的檔案路徑：3162除了 [所有 hooks 可用的 JSON 輸出欄位](#json-output) 外，FileChanged hooks 可以傳回 `watchPaths` 以動態更新監視的檔案路徑：
3159 3163
3160| 欄位 | 描述 |3164| 欄位 | 描述 |
3161| :----------- | :----------------------------------------------------------------------------- |3165| :----------- | :----------------------------------------------------------------------------- |
3162| `watchPaths` | 絕對路徑的陣列。替換目前的動態監視清單。您的 `matcher` 設定中的路徑始終被監視。當您的 hook 指令碼根據變更的檔案探索要監視的其他檔案時使用此 |3166| `watchPaths` | 絕對路徑的陣列。替換目前的動態監視清單。來自您 `matcher` 配置的路徑始終被監視。當您的 hook 指令碼根據變更檔案探索要監視的額外檔案時，使用此 |
3163 3167
3164FileChanged hooks 沒有決策控制。它們無法阻止檔案變更發生。3168FileChanged hooks 沒有決策控制。它們無法阻止檔案變更發生。
3165 3169
3166Claude Code 從其 JSON 輸出讀取 `watchPaths` 和 `systemMessage`，並捨棄 `continue`。在互動式工作階段中，它將 `systemMessage` 顯示為簡短終端通知。訊息不到達 SDK 訊息流。3170Claude Code 從其 JSON 輸出讀取 `watchPaths` 和 `systemMessage`，並捨棄 `continue`。在互動式工作階段中，它將 `systemMessage` 顯示為簡短的終端通知。訊息不到達 SDK 訊息流。
3167 3171
3168<h3 id="worktreecreate">3172<h3 id="worktreecreate">
3169 WorktreeCreate3173 WorktreeCreate
3170</h3>3174</h3>
3171 3175
3172在建立 worktree 時執行，無論是從 `claude --worktree`、從 [使用 `isolation: "worktree"` 的子代理](/docs/zh-TW/sub-agents#choose-the-subagent-scope)，或用於 Claude Code 在其自己的 worktree 中隔離的 [背景工作階段](/docs/zh-TW/agent-view#how-file-edits-are-isolated)。預設情況下 Claude Code 使用 `git worktree` 建立隔離的工作副本。設定 WorktreeCreate hook 完全替換該預設 git 行為，讓您使用不同的版本控制系統，例如 SVN、Perforce 或 Mercurial。3176在建立 worktree 時執行，無論是從 `claude --worktree`、從 [使用 `isolation: "worktree"` 的子代理](/docs/zh-TW/sub-agents#choose-the-subagent-scope)，或對於 Claude Code 在其自己的 worktree 中隔離的 [背景工作階段](/docs/zh-TW/agent-view#how-file-edits-are-isolated)。預設情況下，Claude Code 使用 `git worktree` 建立隔離的工作副本。配置 WorktreeCreate hook 替換該預設 git 行為，讓您使用不同的版本控制系統，如 SVN、Perforce 或 Mercurial。
3173 3177
3174因為 hook 完全替換預設行為，[`.worktreeinclude`](/docs/zh-TW/worktrees#copy-gitignored-files-into-worktrees) 不被處理。如果您需要複製本機設定檔，例如 `.env`，到新 worktree，請在您的 hook 指令碼內執行。3178因為 hook 完全替換預設行為，[`.worktreeinclude`](/docs/zh-TW/worktrees#copy-gitignored-files-into-worktrees) 不被處理。如果您需要將本機配置檔案（如 `.env`）複製到新 worktree，請在您的 hook 指令碼內執行。
3175 3179
3176Hook 必須返回建立的 worktree 目錄的路徑。Claude Code 使用此路徑作為隔離工作階段的工作目錄。請參閱 [WorktreeCreate 輸出](#worktreecreate-output)，了解每個 hook 類型如何返回路徑。3180Hook 必須傳回建立的 worktree 目錄的路徑。Claude Code 使用此路徑作為隔離工作階段的工作目錄。請參閱 [WorktreeCreate 輸出](#worktreecreate-output)，了解每個 hook 類型如何傳回路徑。
3177 3181
3178Claude Code 作用於 hook 的成功和返回的路徑，並捨棄 `systemMessage` 和 `continue`。3182Claude Code 作用於 hook 的成功和傳回的路徑，並捨棄 `systemMessage` 和 `continue`。
3179 3183
3180此範例建立 SVN 工作副本並列印路徑供 Claude Code 使用。將儲存庫 URL 替換為您自己的：3184此範例建立 SVN 工作副本並列印路徑供 Claude Code 使用。將儲存庫 URL 替換為您自己的：
3181 3185
3196}3200}
3197```3201```
3198 3202
3199Hook 從 stdin 上的 JSON 輸入讀取 worktree `name`，將新副本簽出到新目錄，並列印目錄路徑。最後一行的 `echo` 是 Claude Code 讀取為 worktree 路徑的內容。將任何其他輸出重定向到 stderr，以便它不干擾路徑。3203Hook 從 stdin 上的 JSON 輸入讀取 worktree `name`，將新副本簽出到新目錄，並列印目錄路徑。最後一行的 `echo` 是 Claude Code 讀取為 worktree 路徑的內容。將任何其他輸出重新導向到 stderr，以便它不會干擾路徑。
3200 3204
3201<h4 id="worktreecreate-input">3205<h4 id="worktreecreate-input">
3202 WorktreeCreate 輸入3206 WorktreeCreate 輸入
3203</h4>3207</h4>
3204 3208
3205除了 [常見輸入欄位](#common-input-fields) 外，WorktreeCreate hooks 還會接收 `name` 欄位。這是新 worktree 的 slug 識別碼，由使用者指定或自動生成，例如 `bold-oak-a3f2`。3209除了 [常見輸入欄位](#common-input-fields) 外，WorktreeCreate hooks 接收 `name` 欄位。這是新 worktree 的 slug 識別碼，由使用者指定或自動產生，例如 `bold-oak-a3f2`。
3206 3210
3207```json theme={null}3211```json theme={null}
3208{3212{
3218 WorktreeCreate 輸出3222 WorktreeCreate 輸出
3219</h4>3223</h4>
3220 3224
3221WorktreeCreate hooks 不使用標準允許/阻止決策模型。相反，hook 的成功或失敗決定結果。Hook 必須返回建立的 worktree 目錄的路徑：3225WorktreeCreate hooks 不使用標準允許/阻止決策模型。相反，hook 的成功或失敗決定結果。Hook 必須傳回建立的 worktree 目錄的路徑：
3222 3226
3223* **命令 hooks** (`type: "command"`)：將路徑列印為 stdout 的最後一個非空行。Claude Code 在讀取該行之前去除 ANSI 逸出代碼，因此在您的 `echo` 之前列印的 shell 啟動橫幅被忽略。將任何其他 hook 輸出重定向到 stderr。3227* **命令 hooks** (`type: "command"`)：將路徑列印為 stdout 的最後一個非空行。Claude Code 在讀取該行之前去除 ANSI 逸出代碼，因此在您的 `echo` 之前列印的 shell 啟動橫幅會被忽略。將任何其他 hook 輸出重新導向到 stderr。
3224* **HTTP hooks** (`type: "http"`)：在回應主體中返回 `{ "hookSpecificOutput": { "hookEventName": "WorktreeCreate", "worktreePath": "/absolute/path" } }`。3228* **HTTP hooks** (`type: "http"`)：在回應主體中傳回 `{ "hookSpecificOutput": { "hookEventName": "WorktreeCreate", "worktreePath": "/absolute/path" } }`。
3225 3229
3226如果 hook 失敗或不產生路徑，worktree 建立失敗並出現錯誤。3230如果 hook 失敗或不產生路徑，worktree 建立失敗，出現錯誤。
3227 3231
3228Claude Code 根據 hook 執行的目錄解決相對路徑，摺疊其中的任何 `.` 或 `..` 段。如果結果路徑不是 Claude Code 可以進入的目錄，工作階段列印命名路徑的錯誤並以代碼 1 退出。3232Claude Code 根據 hook 執行的目錄解決相對路徑，折疊其中的任何 `.` 或 `..` 段。如果結果路徑不是 Claude Code 可以進入的目錄，工作階段列印命名路徑的錯誤並以代碼 1 退出。
3229 3233
3230Claude Code 拒絕包含 `.` 或 `..` 段的絕對路徑，以及通過儲存庫根下方的符號連結的任何路徑，因為提交到儲存庫的符號連結可能將 worktree 重定向到其外部。錯誤命名被拒絕的元件。返回不通過儲存庫內符號連結的規範化路徑。在 v2.1.216 之前，worktree 建立遵循 hook 的路徑而不進行此篩選。3234Claude Code 拒絕包含 `.` 或 `..` 段的絕對路徑，以及通過儲存庫根下方符號連結的任何路徑，因為提交到儲存庫的符號連結可能會將 worktree 重新導向到其外部。錯誤命名被拒絕的元件。傳回不通過儲存庫內符號連結的正規化路徑。在 v2.1.216 之前，worktree 建立遵循 hook 的路徑，而不進行此篩選。
3231 3235
3232<h3 id="worktreeremove">3236<h3 id="worktreeremove">
3233 WorktreeRemove3237 WorktreeRemove
3237 3241
3238* 您退出 `--worktree` 工作階段並選擇移除它3242* 您退出 `--worktree` 工作階段並選擇移除它
3239* 具有 `isolation: "worktree"` 的子代理完成3243* 具有 `isolation: "worktree"` 的子代理完成
3240* 您刪除 [背景工作階段](/docs/zh-TW/agent-view#what-deleting-a-session-removes)，其 worktree 由 hook 建立3244* 您刪除 [背景工作階段](/docs/zh-TW/agent-view#what-deleting-a-session-removes)，其 worktree hook 建立
3241 3245
3242對於基於 git 的 worktrees，Claude Code 使用 `git worktree remove` 自動處理清理。如果您為非 git 版本控制系統設定了 WorktreeCreate hook，請將其與 WorktreeRemove hook 配對以處理清理。沒有它，worktree 目錄保留在磁碟上。3246對於基於 git 的 worktrees，Claude Code 使用 `git worktree remove` 自動處理清理。如果您為非 git 版本控制系統配置了 WorktreeCreate hook，請將其與 WorktreeRemove hook 配對以處理清理。沒有它，worktree 目錄會保留在磁碟上。
3243 3247
3244Claude Code 捨棄 WorktreeRemove hook 的 [JSON 輸出欄位](#json-output)，例如 `systemMessage` 和 `continue`。3248Claude Code 捨棄 WorktreeRemove hook 的 [JSON 輸出欄位](#json-output)，例如 `systemMessage` 和 `continue`。
3245 3249
3246對於背景工作階段刪除，Claude Code 在執行 hook 之前驗證儲存的 worktree 路徑，並拒絕在儲存庫根下方是符號連結或通過符號連結的路徑。Hook 僅對仍包含檔案的 worktree 執行，當您在 [代理檢視](/docs/zh-TW/agent-view#what-deleting-a-session-removes) 中確認刪除時；對於這樣的 worktree，[`claude rm`](/docs/zh-TW/agent-view#manage-sessions-from-the-shell) 保持工作階段和 worktree。在 v2.1.216 之前，hook 在儲存的路徑上執行而不進行這些檢查。3250對於背景工作階段刪除，Claude Code 在執行 hook 之前驗證儲存的 worktree 路徑，並拒絕儲存庫根下方是符號連結或通過符號連結的路徑。Hook 僅對仍包含檔案的 worktree 執行，當您在 [agent view](/docs/zh-TW/agent-view#what-deleting-a-session-removes) 中確認刪除時；對於這樣的 worktree，[`claude rm`](/docs/zh-TW/agent-view#manage-sessions-from-the-shell) 保持工作階段和 worktree。在 v2.1.216 之前，hook 在儲存的路徑上執行，而不進行這些檢查。
3247 3251
3248Claude Code 將 WorktreeCreate 返回的路徑作為 `worktree_path` 在 hook 輸入中傳遞。此範例讀取該路徑並移除目錄：3252Claude Code 將 WorktreeCreate 傳回的路徑作為 `worktree_path` 在 hook 輸入中傳遞。此範例讀取該路徑並移除目錄：
3249 3253
3250```json theme={null}3254```json theme={null}
3251{3255{
3268 WorktreeRemove 輸入3272 WorktreeRemove 輸入
3269</h4>3273</h4>
3270 3274
3271除了 [常見輸入欄位](#common-input-fields) 外，WorktreeRemove hooks 還會接收 `worktree_path` 欄位，這是正在移除的 worktree 的絕對路徑。3275除了 [常見輸入欄位](#common-input-fields) 外，WorktreeRemove hooks 接收 `worktree_path` 欄位，即被移除的 worktree 的絕對路徑。
3272 3276
3273```json theme={null}3277```json theme={null}
3274{3278{
3280}3284}
3281```3285```
3282 3286
3283WorktreeRemove hook 的退出代碼決定結果。當 hook 以非零退出且 `worktree_path` 的目錄仍然存在時，移除失敗：3287WorktreeRemove hook 的退出代碼決定結果。當 hook 以非零退出且 `worktree_path` 處的目錄仍存在時，移除失敗：
3284 3288
3285* Worktree 保留在磁碟上，hook 的命令和 stderr 進入 [偵錯日誌](#debug-hooks)。3289* Worktree 保留在磁碟上，hook 的命令和 stderr 進入 [debug log](#debug-hooks)。
3286* 如果您刪除背景工作階段，工作階段也保留。[代理檢視](/docs/zh-TW/agent-view#what-deleting-a-session-removes) 中的拒絕訊息報告 hook 如何結束，例如 `exited 1`，引用其 stderr 的開頭，並說明再次刪除工作階段是否移除目錄。3290* 如果您刪除背景工作階段，工作階段也保留。[agent view](/docs/zh-TW/agent-view#what-deleting-a-session-removes) 中的拒絕訊息報告 hook 如何結束，例如 `exited 1`，引用其 stderr 的開頭，並說明再次刪除工作階段是否無論如何移除目錄。
3287 3291
3288<h3 id="precompact">3292<h3 id="precompact">
3289 PreCompact3293 PreCompact
3290</h3>3294</h3>
3291 3295
3292在 Claude Code 即將執行壓縮操作之前執行。3296在 Claude Code 即將執行壓縮操作時執行。
3293 3297
3294匹配器值指示壓縮是手動觸發還是自動觸發：3298匹配器值指示壓縮是手動還是自動觸發：
3295 3299
3296| 匹配器 | 何時觸發 |3300| 匹配器 | 何時觸發 |
3297| :------- | :-------------------------------------------------------------------- |3301| :------- | :-------------------------------------------------------------------- |
3298| `manual` | `/compact` |3302| `manual` | `/compact` |
3299| `auto` | 當對話到達 [自動壓縮視窗](/docs/zh-TW/model-config#set-the-auto-compact-window) 時自動壓縮 |3303| `auto` | 當對話到達 [自動壓縮視窗](/docs/zh-TW/model-config#set-the-auto-compact-window) 時自動壓縮 |
3300 3304
3301以代碼 2 退出以阻止壓縮。對於手動 `/compact`，stderr 訊息顯示給使用者。您也可以透過返回 JSON 搭配 `"decision": "block"` 來阻止。3305以代碼 2 退出以阻止壓縮。對於手動 `/compact`，stderr 訊息顯示給使用者。您也可以透過傳回 JSON 搭配 `"decision": "block"` 來阻止。
3302 3306
3303阻止自動壓縮根據何時觸發有不同的效果。如果壓縮在背景資訊限制之前主動觸發，Claude Code 跳過它，對話繼續未壓縮。如果壓縮被觸發以從 API 已返回的背景資訊限制錯誤恢復，基礎錯誤呈現，目前請求失敗。3307阻止自動壓縮根據何時觸發有不同的效果。如果壓縮在背景限制之前主動觸發，Claude Code 跳過它，對話繼續未壓縮。如果壓縮被觸發以從 API 已傳回的背景限制錯誤復原，基礎錯誤呈現，目前請求失敗。
3304 3308
3305Claude Code 捨棄 PreCompact hook 的 `systemMessage` 和 `continue` 欄位。3309Claude Code 捨棄 PreCompact hook 的 `systemMessage` 和 `continue` 欄位。
3306 3310
3308 PreCompact 輸入3312 PreCompact 輸入
3309</h4>3313</h4>
3310 3314
3311除了 [常見輸入欄位](#common-input-fields) 外，PreCompact hooks 還會接收 `trigger` 和 `custom_instructions`。對於 `manual`，`custom_instructions` 包含使用者傳遞到 `/compact` 的內容，當他們傳遞無內容時為 `null`。對於 `auto`，`custom_instructions` 為 `null`。3315除了 [常見輸入欄位](#common-input-fields) 外，PreCompact hooks 接收 `trigger` 和 `custom_instructions`。對於 `manual`，`custom_instructions` 包含使用者傳遞到 `/compact` 的內容，當他們傳遞任何東西時為 `null`。對於 `auto`，`custom_instructions` 為 `null`。
3312 3316
3313```json theme={null}3317```json theme={null}
3314{3318{
3325 PostCompact3329 PostCompact
3326</h3>3330</h3>
3327 3331
3328在 Claude Code 完成壓縮操作後執行。使用此事件對新壓縮狀態做出反應，例如記錄生成的摘要或更新外部狀態。Claude Code 捨棄 PostCompact hook 的 `systemMessage` 和 `continue` 欄位。3332在 Claude Code 完成壓縮操作後執行。使用此事件對新壓縮狀態做出反應，例如記錄產生的摘要或更新外部狀態。Claude Code 捨棄 PostCompact hook 的 `systemMessage` 和 `continue` 欄位。
3329 3333
3330與 `PreCompact` 相同的匹配器值適用：3334與 `PreCompact` 相同的匹配器值適用：
3331 3335
3338 PostCompact 輸入3342 PostCompact 輸入
3339</h4>3343</h4>
3340 3344
3341除了 [常見輸入欄位](#common-input-fields) 外，PostCompact hooks 還會接收 `trigger` 和 `compact_summary`。`compact_summary` 欄位包含壓縮操作生成的對話摘要。3345除了 [常見輸入欄位](#common-input-fields) 外，PostCompact hooks 接收 `trigger` 和 `compact_summary`。`compact_summary` 欄位包含壓縮操作產生的對話摘要。
3342 3346
3343```json theme={null}3347```json theme={null}
3344{3348{
3357 PreModelSwitch3361 PreModelSwitch
3358</h3>3362</h3>
3359 3363
3360在 Claude Code 應用您或用戶端請求的模型切換之前執行。使用它來阻止切換、要求確認或在切換發生前顯示成本。3364在 Claude Code 應用您或用戶端要求的模型切換之前執行。使用它來阻止切換、要求確認或在切換發生前顯示成本。
3361 3365
3362PreModelSwitch 需要 Claude Code v2.1.251 或更新版本。Claude Code 為這些請求執行它：3366PreModelSwitch 需要 Claude Code v2.1.251 或更新版本。Claude Code 為這些請求執行它：
3363 3367
3364* `/model <name>` 和 `/model` 選擇器3368* `/model <name>` 和 `/model` 選擇器
3365* `Option+P` 或 `Alt+P` 模型選擇器3369* `Option+P` 或 `Alt+P` 模型選擇器
3366* `/config` 中的 Model 設定3370* `/config` 中的 Model 設定
3367* 當那改變工作階段的模型時打開 [快速模式](/docs/zh-TW/fast-mode)3371* 當那改變工作階段的模型時開啟 [fast mode](/docs/zh-TW/fast-mode)
3368* 來自 [Agent SDK](/docs/zh-TW/agent-sdk/typescript#query-object) 主機或 [Remote Control](/docs/zh-TW/remote-control) 的 `set_model` 請求，或 `apply_flag_settings` 請求中的模型變更3372* 來自 [Agent SDK](/docs/zh-TW/agent-sdk/typescript#query-object) 主機或 [Remote Control](/docs/zh-TW/remote-control) 的 `set_model` 請求，或 `apply_flag_settings` 請求中的模型變更
3369 3373
3370Claude Code 不為它自己進行的切換執行 PreModelSwitch hooks，例如 [自動模型回退](/docs/zh-TW/model-config#automatic-model-fallback) 或恢復工作階段時恢復模型。這些變更僅到達 [PostModelSwitch](#postmodelswitch)。3374Claude Code 不為它自己進行的切換執行 PreModelSwitch hooks，例如 [自動模型回退](/docs/zh-TW/model-config#automatic-model-fallback) 或恢復工作階段時恢復模型。這些變更僅到達 [PostModelSwitch](#postmodelswitch)。
3371 3375
3372Claude Code 根據工作階段切換到的模型的規範名稱比較匹配器，忽略任何 `[1m]` 後綴。別名（例如 `opus`）、日期模型 ID 和提供者特定 ID（例如 Amazon Bedrock 模型 ID）都匹配它們解決到的一個規範名稱，因此 `claude-opus-5` 涵蓋 Opus 5 的每個拼寫。3376Claude Code 根據工作階段切換到的模型的規範名稱比較匹配器，忽略任何 `[1m]` 後綴。別名（如 `opus`）、日期模型 ID 和提供者特定 ID（如 Amazon Bedrock 模型 ID）都匹配它們解決到的一個規範名稱，因此 `claude-opus-5` 涵蓋 Opus 5 的每個拼寫。
3373 3377
3374當 Claude Code 無法確定目標的規範名稱時，例如僅您的 [LLM 閘道](/docs/zh-TW/llm-gateway) 知道的自訂模型 ID，它執行每個 PreModelSwitch hook，無論匹配器如何。阻止的 hook 應該檢查其輸入中的 `to_model` 而不是僅依賴匹配器。3378當 Claude Code 無法確定目標的規範名稱時，例如只有您的 [LLM gateway](/docs/zh-TW/llm-gateway) 知道的自訂模型 ID，它執行每個 PreModelSwitch hook，無論匹配器如何。阻止的 hook 應該從其輸入檢查 `to_model` 而不是僅依賴匹配器。
3375 3379
3376將匹配器寫為精確名稱、`|` 分隔清單（例如 `claude-opus-4-6|claude-opus-5`）或正規表達式（例如 `.*opus.*`）。此範例使用精確名稱匹配器並也檢查 hook 輸入中的 `to_model`，因此它拒絕切換到 Opus 4.6，透過以代碼 2 退出，並讓任何其他目標通過：3380將匹配器寫為精確名稱、`|` 分隔清單（如 `claude-opus-4-6|claude-opus-5`）或正規表達式（如 `.*opus.*`）。此範例使用精確名稱匹配器，也從 hook 輸入檢查 `to_model`，因此它拒絕切換到 Opus 4.6，透過以代碼 2 退出，並讓任何其他目標通過：
3377 3381
3378<Tabs>3382<Tabs>
3379 <Tab title="macOS/Linux">3383 <Tab title="macOS/Linux">
3426 }3430 }
3427 ```3431 ```
3428 3432
3429 將此指令碼儲存到您專案中的 `.claude/hooks/block-opus-46.ps1`：3433 將此指令碼儲存到您的專案中的 `.claude/hooks/block-opus-46.ps1`：
3430 3434
3431 ```powershell theme={null}3435 ```powershell theme={null}
3432 $hookInput = [Console]::In.ReadToEnd() | ConvertFrom-Json3436 $hookInput = [Console]::In.ReadToEnd() | ConvertFrom-Json
3439 </Tab>3443 </Tab>
3440</Tabs>3444</Tabs>
3441 3445
3442若要確認 hook 有效，從執行不同模型的工作階段執行 `/model claude-opus-4-6`。Claude Code 保持目前模型並報告 PreModelSwitch hook 阻止了切換，您的訊息作為原因。3446若要確認 hook 有效，從執行不同模型的工作階段執行 `/model claude-opus-4-6`。Claude Code 保持目前模型並報告 PreModelSwitch hook 阻止了切換，以您的訊息作為原因。
3443 3447
3444<h4 id="premodelswitch-input">3448<h4 id="premodelswitch-input">
3445 PreModelSwitch 輸入3449 PreModelSwitch 輸入
3446</h4>3450</h4>
3447 3451
3448除了 [常見輸入欄位](#common-input-fields) 外，PreModelSwitch hooks 還會接收此表中的欄位。最後五個描述重新發送對話到新模型的成本，因此 hook 可以在切換發生前顯示該數字。3452除了 [常見輸入欄位](#common-input-fields) 外，PreModelSwitch hooks 接收此表中的欄位。最後五個描述重新傳送對話到新模型的成本，因此 hook 可以在切換發生前顯示該數字。
3449 3453
3450| 欄位 | 類型 | 描述 |3454| 欄位 | 類型 | 描述 |
3451| :-------------------------- | :--------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |3455| :-------------------------- | :--------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
3452| `from_model` | string | 切換變更的模型 ID |3456| `from_model` | string | 切換變更的模型 ID |
3453| `to_model` | string | 切換變更為的模型 ID。匹配器根據此模型的規範名稱比較 |3457| `to_model` | string | 切換變更為的模型 ID。匹配器根據此模型的規範名稱比較 |
3454| `requested_model` | string or `null` | 請求命名的模型：別名（例如 `opus`）、完整模型 ID 或當請求為預設模型時 `null` |3458| `requested_model` | string or `null` | 請求命名的模型：別名（如 `opus`）、完整模型 ID，或當請求為預設模型時 `null` |
3455| `source` | string | 請求來自何處：`/model <name>`、`/config` 中的 Model 設定或打開快速模式的 `"command"`；模型選擇器的 `"picker"`；來自 Agent SDK 主機或 Remote Control 的 `set_model` 請求或 `apply_flag_settings` 請求中的模型變更的 `"sdk"` |3459| `source` | string | 請求來自何處：`/model <name>`、`/config` 中的 Model 設定或開啟 fast mode 的 `"command"`；模型選擇器的 `"picker"`；來自 Agent SDK 主機或 Remote Control 的 `set_model` 請求或 `apply_flag_settings` 請求中的模型變更的 `"sdk"` |
3456| `context_tokens` | number | 下一個請求重新發送作為其提示的令牌：主對話中最後回應的輸入、快取讀取、快取建立和輸出令牌結合。第一個回應前為 `0` |3460| `context_tokens` | number | 下一個請求重新傳送為其提示的權杖：主對話中最後回應的輸入、快取讀取、快取建立和輸出權杖，結合。第一個回應前為 `0` |
3457| `prompt_cache_warm` | boolean | 目前模型的 prompt cache 是否可能仍然溫暖，意味著切換放棄它 |3461| `prompt_cache_warm` | boolean | 目前模型的 prompt cache 是否可能仍然溫暖，意味著切換放棄它 |
3458| `cache_ttl` | string | [Prompt cache 生命週期](/docs/zh-TW/prompt-caching#cache-lifetime) Claude Code 為此工作階段請求：`"5m"` 或 `"1h"` |3462| `cache_ttl` | string | [Prompt cache 生命週期](/docs/zh-TW/prompt-caching#cache-lifetime) Claude Code 為此工作階段要求：`"5m"` 或 `"1h"` |
3459| `estimated_cache_write_usd` | number | 在 `cache_ttl` 速率下將 `context_tokens` 寫入 `to_model` 上的 prompt cache 的估計成本（美元），不包括下一個回應 |3463| `estimated_cache_write_usd` | number | 在 `to_model` 上以 `cache_ttl` 速率將 `context_tokens` 寫入 prompt cache 的估計成本（美元），不包括下一個回應。伺服器可能不需要重新快取整個背景資訊，因此將其視為估計 |
3460| `pricing` | string | Claude Code 如何定價 `estimated_cache_write_usd`：當您的組織已設定它們時在您的組織自己的速率下為 `"configured"`、在清單價格下為 `"catalog"`，或當 `to_model` 沒有已知價格且 Claude Code 假設預設速率時為 `"default"` |3464| `pricing` | string | Claude Code 如何定價 `estimated_cache_write_usd`：當您的組織配置了它們時以您組織自己的速率為 `"configured"`，以清單價格為 `"catalog"`，或當 `to_model` 沒有已知價格且 Claude Code 假設預設速率時為 `"default"` |
3461 3465
3462此範例顯示在執行 Sonnet 5 的工作階段中 `/model opus` 的輸入：3466此範例顯示在 Sonnet 5 執行的工作階段中 `/model opus` 的輸入：
3463 3467
3464```json theme={null}3468```json theme={null}
3465{3469{
3483 PreModelSwitch 決策控制3487 PreModelSwitch 決策控制
3484</h4>3488</h4>
3485 3489
3486`PreModelSwitch` hooks 可以取消切換、要求使用者確認或讓它進行。退出代碼 2 或頂級 `decision: "block"` 取消切換。3490`PreModelSwitch` hooks 可以取消切換、要求使用者確認它，或讓它進行。退出代碼 2 或頂級 `decision: "block"` 取消切換。
3487 3491
3488為了更精細的控制，在 `hookSpecificOutput` 物件中返回 `permissionDecision` 和 `permissionDecisionReason`，如 [PreToolUse](#pretooluse-decision-control) 上。`PreModelSwitch` 接受 `"allow"`、`"deny"` 和 `"ask"`。它不接受 `"defer"`、`updatedInput` 或 `additionalContext`。下表描述兩個欄位：3492為了更精細的控制，在 `hookSpecificOutput` 物件中傳回 `permissionDecision` 和 `permissionDecisionReason`，如 [PreToolUse](#pretooluse-decision-control)。`PreModelSwitch` 接受 `"allow"`、`"deny"` 和 `"ask"`。它不接受 `"defer"`、`updatedInput` 或 `additionalContext`。下表描述兩個欄位：
3489 3493
3490| 欄位 | 描述 |3494| 欄位 | 描述 |
3491| :------------------------- | :-------------------------------------------------------------------------------------------------------------------------- |3495| :------------------------- | :--------------------------------------------------------------------------------------------------------------------------- |
3492| `permissionDecision` | `"allow"` 進行並跳過 [Claude Code 在 prompt cache 溫暖時顯示的確認](/docs/zh-TW/prompt-caching#switching-models)。`"deny"` 取消切換。`"ask"` 提示使用者確認 |3496| `permissionDecision` | `"allow"` 進行並跳過 [Claude Code 在 prompt cache 溫暖時顯示的確認](/docs/zh-TW/prompt-caching#switching-models)。`"deny"` 取消切換。`"ask"` 提示使用者確認它 |
3493| `permissionDecisionReason` | 對於 `"deny"`，顯示給使用者作為切換被阻止的原因，或作為 `set_model` 請求的錯誤返回。對於 `"ask"`，在確認提示中顯示。對於 `"allow"` 忽略 |3497| `permissionDecisionReason` | 對於 `"deny"`，顯示給使用者作為切換被阻止的原因，或作為 `set_model` 請求的錯誤傳回。對於 `"ask"`，在確認提示中顯示。對於 `"allow"` 忽略 |
3494 3498
3495僅互動式工作階段中的 `/model` 可以顯示 `"ask"` 提示。在每個其他表面上，包括搭配 `-p` 旗標的非互動模式、`/config` 和 `set_model` 請求，Claude Code 將 `"ask"` 視為拒絕。3499僅互動式工作階段中的 `/model` 可以顯示 `"ask"` 提示。在每個其他表面上，包括非互動模式搭配 `-p` 旗標、`/config` 和 `set_model` 請求，Claude Code 將 `"ask"` 視為拒絕。
3496 3500
3497此範例要求使用者確認並引用 `context_tokens` 中的令牌計數：3501此範例要求使用者確認並引用來自 `context_tokens` 的權杖計數：
3498 3502
3499```json theme={null}3503```json theme={null}
3500{3504{
3506}3510}
3507```3511```
3508 3512
3509當多個 PreModelSwitch hooks 返回不同的決策時，優先順序為 `deny` > `ask` > `allow`。3513當多個 PreModelSwitch hooks 傳回不同的決策時，優先順序為 `deny` > `ask` > `allow`。
3510 3514
3511Claude Code 無論決策如何都顯示您的 hook 返回的任何 `systemMessage`，因此成本報告 hook 可以返回 `{"systemMessage": "..."}` 並退出 0。3515Claude Code 無論決策如何都顯示您的 hook 傳回的任何 `systemMessage`，因此成本報告 hook 可以傳回 `{"systemMessage": "..."}` 並退出 0。
3512 3516
3513在其逾時前未回應的 PreModelSwitch hook 會阻止切換。在 [PreToolUse](#timeouts) 上相比，逾時的命令 hook 讓工具呼叫繼續。此事件的預設逾時為 30 秒。`PreModelSwitch` 僅執行 `command`、`http` 和 `mcp_tool` hooks，因此 `prompt` 和 `agent` 預設不適用。3517在其逾時前未回應的 PreModelSwitch hook 會阻止切換。在 [PreToolUse](#timeouts) 上，相比之下，逾時的命令 hook 讓工具呼叫繼續。此事件的預設逾時為 30 秒。`PreModelSwitch` 僅執行 `command`、`http` 和 `mcp_tool` hooks，因此 `prompt` 和 `agent` 預設不適用。
3514 3518
3515以 0 或 2 以外的代碼退出且不列印 JSON 決策的 hook 不阻止：Claude Code 顯示其 stderr 並應用切換，如 [其他退出代碼](#other-exit-codes) 下所述。3519以 0 或 2 以外的代碼退出且不列印 JSON 決策的 hook 不阻止：Claude Code 顯示其 stderr 並應用切換，如 [其他退出代碼](#other-exit-codes) 下所述。
3516 3520
3518 PostModelSwitch3522 PostModelSwitch
3519</h3>3523</h3>
3520 3524
3521在工作階段的模型變更後執行。使用它來給予 Claude 模型特定指導，而不編輯每個 CLAUDE.md，例如僅在某些模型上適用的組織範圍指令。3525在工作階段的模型變更後執行。使用它來給予 Claude 模型特定的指導，而不編輯每個 CLAUDE.md，例如僅在某些模型上適用的組織範圍指示。
3522 3526
3523PostModelSwitch 需要 Claude Code v2.1.251 或更新版本。它無法阻止，因為模型已變更。Claude Code 在這些變更後執行 PostModelSwitch hooks：3527PostModelSwitch 需要 Claude Code v2.1.251 或更新版本。它無法阻止，因為模型已變更。Claude Code 在這些變更後執行 PostModelSwitch hooks：
3524 3528
3525* 您或用戶端請求的切換3529* 您或用戶端要求的切換
3526* [自動模型回退](/docs/zh-TW/model-config#automatic-model-fallback)，改變工作階段的模型3530* [自動模型回退](/docs/zh-TW/model-config#automatic-model-fallback)，改變工作階段的模型
3527* 設定（例如 [`opusplan`](/docs/zh-TW/model-config#opusplan-model-setting)）進入或離開計畫模式3531* 設定（如 [`opusplan`](/docs/zh-TW/model-config#opusplan-model-setting)）進入或離開 plan mode
3528* Claude Code 恢復工作階段時恢復模型3532* Claude Code 在您恢復工作階段時恢復模型
3529 3533
3530當 [回退模型鏈](/docs/zh-TW/model-config#fallback-model-chains) 中的模型服務回合時，Claude Code 不執行 PostModelSwitch hooks，因為該替換持續一個回合並保持工作階段的模型不變。3534當 [回退模型鏈](/docs/zh-TW/model-config#fallback-model-chains) 中的模型服務回合時，Claude Code 不執行 PostModelSwitch hooks，因為該替換持續一個回合，並保持工作階段的模型不變。
3531 3535
3532匹配器遵循與 [PreModelSwitch](#premodelswitch) 相同的規則：Claude Code 根據工作階段切換到的模型的規範名稱比較它。3536匹配器遵循與 [PreModelSwitch](#premodelswitch) 相同的規則：Claude Code 根據工作階段切換到的模型的規範名稱比較它。
3533 3537
3557 PostModelSwitch 輸入3561 PostModelSwitch 輸入
3558</h4>3562</h4>
3559 3563
3560PostModelSwitch hooks 接收與 [PreModelSwitch](#premodelswitch-input) 相同的欄位，其中 `hook_event_name` 設定為 `"PostModelSwitch"` 和兩個更多 `source` 值：`"auto"` 用於自動回退或 Claude Code 自己進行的其他變更，`"resume"` 用於恢復工作階段時恢復的模型。3564PostModelSwitch hooks 接收與 [PreModelSwitch](#premodelswitch-input) 相同的欄位，其 `hook_event_name` 設定為 `"PostModelSwitch"` 和兩個更多 `source` 值：`"auto"` 對於自動回退或 Claude Code 自己進行的其他變更，以及 `"resume"` 對於您恢復工作階段時恢復的模型。
3561 3565
3562當 `source` 為 `"auto"` 時 `requested_model` 為 `null`。當 `source` 為 `"resume"` 時，它是 Claude Code 恢復的儲存模型設定。3566當 `source` 為 `"auto"` 時，`requested_model` 為 `null`。當 `source` 為 `"resume"` 時，它是 Claude Code 恢復的儲存模型設定。
3563 3567
3564<h4 id="postmodelswitch-decision-control">3568<h4 id="postmodelswitch-decision-control">
3565 PostModelSwitch 決策控制3569 PostModelSwitch 決策控制
3566</h4>3570</h4>
3567 3571
3568Claude Code 在下一個切換後的請求中採用您的 hook 的 [純文字 stdout](#exit-code-0) 退出 0，或 JSON 輸出中的 `additionalContext`，並將其傳遞給 Claude。除了所有 hooks 可用的 [JSON 輸出欄位](#json-output) 外，您可以返回：3572Claude Code 採用您的 hook 的 [純文字 stdout](#exit-code-0) 在退出 0 上，或來自 JSON 輸出的 `additionalContext`，並在切換後的下一個請求中將其傳遞給 Claude。除了 [所有 hooks 可用的 JSON 輸出欄位](#json-output) 外，您可以傳回：
3569 3573
3570| 欄位 | 描述 |3574| 欄位 | 描述 |
3571| :------------------ | :------------------------------------------------------------------------ |3575| :------------------ | :------------------------------------------------------------------------ |
3572| `additionalContext` | 與下一個請求一起新增到 Claude 背景資訊的字串。請參閱 [為 Claude 新增背景資訊](#add-context-for-claude) |3576| `additionalContext` | 與下一個請求一起新增到 Claude 背景資訊的字串。請參閱 [為 Claude 新增背景資訊](#add-context-for-claude) |
3573 3577
3574如果 hook 在您發送下一個提示後五秒內未完成，Claude Code 發送該請求而不輸出，並改為將其附加到下一個請求。如果模型在下一個請求之前變更多次，Claude Code 僅傳遞最後切換目標模型的輸出。3578如果 hook 在您傳送下一個提示後五秒內未完成，Claude Code 傳送該請求而不輸出，並將其附加到下一個請求。如果模型在下一個請求之前變更多次，Claude Code 僅傳遞最後一個切換目標模型的輸出。
3575 3579
3576<h3 id="sessionend">3580<h3 id="sessionend">
3577 SessionEnd3581 SessionEnd
3588| `logout` | 使用者登出 |3592| `logout` | 使用者登出 |
3589| `prompt_input_exit` | 使用者在提示輸入可見時退出 |3593| `prompt_input_exit` | 使用者在提示輸入可見時退出 |
3590| `other` | 其他退出原因 |3594| `other` | 其他退出原因 |
3591| `bypass_permissions_disabled` | 在 v2.1.234 中移除；Claude Code 不發送它。從您的 `SessionEnd` 匹配器中刪除它 |3595| `bypass_permissions_disabled` | 在 v2.1.234 中移除；Claude Code 不傳送它。從您的 `SessionEnd` 匹配器中刪除它 |
3592 3596
3593<h4 id="sessionend-input">3597<h4 id="sessionend-input">
3594 SessionEnd 輸入3598 SessionEnd 輸入
3595</h4>3599</h4>
3596 3600
3597除了 [常見輸入欄位](#common-input-fields) 外，SessionEnd hooks 還會接收指示工作階段為什麼結束的 `reason` 欄位。請參閱上面的 [原因表](#sessionend) 以了解所有值。3601除了 [常見輸入欄位](#common-input-fields) 外，SessionEnd hooks 接收 `reason` 欄位，指示工作階段為什麼結束。請參閱上面的 [原因表](#sessionend) 以獲得所有值。
3598 3602
3599```json theme={null}3603```json theme={null}
3600{3604{
3610 3614
3611SessionEnd hooks 的預設逾時為 1.5 秒。它在您退出、執行 `/clear` 或使用互動式 `/resume` 切換工作階段時適用。您可以透過兩種方式給予 hook 更多時間：3615SessionEnd hooks 的預設逾時為 1.5 秒。它在您退出、執行 `/clear` 或使用互動式 `/resume` 切換工作階段時適用。您可以透過兩種方式給予 hook 更多時間：
3612 3616
3613* **每個 hook `timeout`**：在該 hook 的設定中設定 `timeout`。整體預算自動上升以符合您設定檔中最高每個 hook `timeout`，最多 60 秒。如果您以這種方式提高預算，沒有自己 `timeout` 的 hook 仍保持預設。在外掛提供的 hooks 上設定的逾時不提高預算。3617* **每個 hook `timeout`**：在該 hook 的配置中設定 `timeout`。整體預算自動上升以符合您設定檔中最高的每個 hook `timeout`，最多 60 秒。如果您以這種方式提高預算，沒有自己 `timeout` 的 hook 仍保持預設。在外掛提供的 hooks 上設定的逾時不會提高預算。
3614* **`CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS`**：以毫秒設定此環境變數以明確覆寫預算。您設定的值也成為每個沒有自己 `timeout` 的 hook 的逾時。3618* **`CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS`**：將此環境變數設定為毫秒以明確覆寫預算。您設定的值也成為每個沒有自己 `timeout` 的 hook 的逾時。
3615 3619
3616此範例將預算設定為 5 秒：3620此範例將預算設定為 5 秒：
3617 3621
3625 Elicitation3629 Elicitation
3626</h3>3630</h3>
3627 3631
3628在 MCP 伺服器在任務中期請求使用者輸入時執行。預設情況下，Claude Code 為使用者顯示互動式對話以回應。Hooks 可以攔截此請求並以程式設計方式回應，完全跳過對話。3632在 MCP 伺服器要求使用者輸入中期任務時執行。預設情況下，Claude Code 為使用者回應顯示互動式對話。Hooks 可以攔截此請求並以程式設計方式回應，完全跳過對話。
3629 3633
3630匹配器欄位根據 MCP 伺服器名稱匹配。3634匹配器欄位根據 MCP 伺服器名稱匹配。
3631 3635
3633 Elicitation 輸入3637 Elicitation 輸入
3634</h4>3638</h4>
3635 3639
3636除了 [常見輸入欄位](#common-input-fields) 外，Elicitation hooks 還會接收 `mcp_server_name`、`message` 和可選的 `mode`、`url`、`elicitation_id` 和 `requested_schema` 欄位。3640除了 [常見輸入欄位](#common-input-fields) 外，Elicitation hooks 接收 `mcp_server_name`、`message` 和可選的 `mode`、`url`、`elicitation_id` 和 `requested_schema` 欄位。
3637 3641
3638對於表單模式引出，最常見的情況：3642對於表單模式引誘，最常見的情況：
3639 3643
3640```json theme={null}3644```json theme={null}
3641{3645{
3655}3659}
3656```3660```
3657 3661
3658對於 URL 模式引出，用於基於瀏覽器的驗證：3662對於 URL 模式引誘，用於基於瀏覽器的驗證：
3659 3663
3660```json theme={null}3664```json theme={null}
3661{3665{
3674 Elicitation 輸出3678 Elicitation 輸出
3675</h4>3679</h4>
3676 3680
3677若要以程式設計方式回應而不顯示對話，請返回具有 `hookSpecificOutput` 的 JSON 物件：3681若要以程式設計方式回應而不顯示對話，傳回具有 `hookSpecificOutput` 的 JSON 物件：
3678 3682
3679```json theme={null}3683```json theme={null}
3680{3684{
3693| `action` | `accept`、`decline`、`cancel` | 是否接受、拒絕或取消請求 |3697| `action` | `accept`、`decline`、`cancel` | 是否接受、拒絕或取消請求 |
3694| `content` | object | 要提交的表單欄位值。僅在 `action` 為 `accept` 時使用 |3698| `content` | object | 要提交的表單欄位值。僅在 `action` 為 `accept` 時使用 |
3695 3699
3696退出代碼 2 拒絕引出。Claude Code 不在任何地方顯示您的 stderr 訊息。3700退出代碼 2 拒絕引誘。Claude Code 不在任何地方顯示您的 stderr 訊息。
3697 3701
3698Claude Code 作用於 Elicitation hook 的 JSON 輸出中的 `hookSpecificOutput` 並捨棄 `systemMessage` 和 `continue`。3702Claude Code 從 Elicitation hook 的 JSON 輸出作用於 `hookSpecificOutput`，並捨棄 `systemMessage` 和 `continue`。
3699 3703
3700<h3 id="elicitationresult">3704<h3 id="elicitationresult">
3701 ElicitationResult3705 ElicitationResult
3702</h3>3706</h3>
3703 3707
3704在使用者回應 MCP 引出後執行。Hooks 可以觀察、修改或阻止回應，然後將其發送回 MCP 伺服器。3708在使用者回應 MCP 引誘後執行。Hooks 可以觀察、修改或阻止回應，然後將其傳送回 MCP 伺服器。
3705 3709
3706匹配器欄位根據 MCP 伺服器名稱匹配。3710匹配器欄位根據 MCP 伺服器名稱匹配。
3707 3711
3709 ElicitationResult 輸入3713 ElicitationResult 輸入
3710</h4>3714</h4>
3711 3715
3712除了 [常見輸入欄位](#common-input-fields) 外，ElicitationResult hooks 還會接收 `mcp_server_name`、`action` 和可選的 `mode`、`elicitation_id` 和 `content` 欄位。3716除了 [常見輸入欄位](#common-input-fields) 外，ElicitationResult hooks 接收 `mcp_server_name`、`action` 和可選的 `mode`、`elicitation_id` 和 `content` 欄位。
3713 3717
3714```json theme={null}3718```json theme={null}
3715{3719{
3729 ElicitationResult 輸出3733 ElicitationResult 輸出
3730</h4>3734</h4>
3731 3735
3732若要覆寫使用者的回應，請返回具有 `hookSpecificOutput` 的 JSON 物件：3736若要覆寫使用者的回應，傳回具有 `hookSpecificOutput` 的 JSON 物件：
3733 3737
3734```json theme={null}3738```json theme={null}
3735{3739{
3748 3752
3749退出代碼 2 阻止回應，將有效動作變更為 `decline`。Claude Code 不在任何地方顯示您的 stderr 訊息。3753退出代碼 2 阻止回應，將有效動作變更為 `decline`。Claude Code 不在任何地方顯示您的 stderr 訊息。
3750 3754
3751Claude Code 作用於 ElicitationResult hook 的 JSON 輸出中的 `hookSpecificOutput` 並捨棄 `systemMessage` 和 `continue`。3755Claude Code 從 ElicitationResult hook 的 JSON 輸出作用於 `hookSpecificOutput`，並捨棄 `systemMessage` 和 `continue`。
3752 3756
3753<h2 id="prompt-based-hooks">3757<h2 id="prompt-based-hooks">
3754 基於提示的 hooks3758 基於提示的 hooks
3759支援所有五種 hook 類型（`command`、`http`、`mcp_tool`、`prompt` 和 `agent`）的事件：3763支援所有五種 hook 類型（`command`、`http`、`mcp_tool`、`prompt` 和 `agent`）的事件：
3760 3764
3761* `PermissionDenied`3765* `PermissionDenied`
3762* `PermissionRequest`
3763* `PostToolBatch`3766* `PostToolBatch`
3764* `PostToolUse`3767* `PostToolUse`
3765* `PostToolUseFailure`3768* `PostToolUseFailure`
3772* `UserPromptExpansion`3775* `UserPromptExpansion`
3773* `UserPromptSubmit`3776* `UserPromptSubmit`
3774 3777
3778`PermissionRequest` 支援 `command`、`http`、`mcp_tool` 和 `prompt` hooks，但不支援 `agent` hooks。如果您在此事件上配置代理 hook，Claude Code 會跳過它，權限流程保持不變。要從 hook 允許或拒絕，請從命令或 HTTP hook 返回[決定物件](#permissionrequest-decision-control)。
3779
3775支援 `command`、`http` 和 `mcp_tool` hooks 但不支援 `prompt` 或 `agent` 的事件：3780支援 `command`、`http` 和 `mcp_tool` hooks 但不支援 `prompt` 或 `agent` 的事件：
3776 3781
3777* `ConfigChange`3782* `ConfigChange`
3904 代理 hooks 是實驗性的。行為和配置可能在未來版本中變更。對於生產工作流程，建議使用[命令 hooks](#command-hook-fields)。3909 代理 hooks 是實驗性的。行為和配置可能在未來版本中變更。對於生產工作流程，建議使用[命令 hooks](#command-hook-fields)。
3905</Warning>3910</Warning>
3906 3911
3907基於代理的 hooks（`type: "agent"`）類似於基於提示的 hooks，但具有多輪工具存取。代理 hook 不是單一 LLM 呼叫，而是生成一個可以讀取檔案、搜尋程式碼和檢查程式碼庫以驗證條件的 subagent。代理 hooks 支援與基於提示的 hooks 相同的事件。3912基於代理的 hooks（`type: "agent"`）類似於基於提示的 hooks，但具有多輪工具存取。代理 hook 不是單一 LLM 呼叫，而是生成一個可以讀取檔案、搜尋程式碼和檢查程式碼庫以驗證條件的 subagent。代理 hooks 支援與[基於提示的 hooks](#prompt-based-hooks) 相同的事件，除了 `PermissionRequest`。
3908 3913
3909<h3 id="how-agent-hooks-work">3914<h3 id="how-agent-hooks-work">
3910 代理 hooks 如何工作3915 代理 hooks 如何工作
