Hook 生命週期
Claude Code 在工作階段期間的特定時間點執行 hooks。當事件觸發且匹配器符合時，Claude Code 會將有關該事件的 JSON 上下文傳遞給您的 hook 處理程式。對於命令 hooks，輸入會到達 stdin。對於 HTTP hooks，它會作為 POST 請求正文到達。您的處理程式可以檢查輸入、採取行動，並可選擇性地返回決定。 事件分為三種節奏：- 每個工作階段一次：
SessionStart和SessionEnd - 每個轉向一次：
UserPromptSubmit、Stop和StopFailure - 在代理迴圈內每個工具呼叫上：
PreToolUse和PostToolUse，除了EndConversation呼叫外，兩者都會跳過
Hook 如何解析
為了了解事件、匹配器和處理程式如何組合在一起，請考慮此PreToolUse hook，它會阻止破壞性 shell 命令。
- macOS/Linux
- Windows (PowerShell)
matcher 縮小到 Bash 工具呼叫，if 條件進一步縮小到符合 rm * 的 Bash 子命令，因此 block-rm.sh 僅在兩個篩選器都符合時才生成：rm -rf，則返回 permissionDecision 為 "deny"。將其儲存到您的專案中的 .claude/hooks/block-rm.sh，並使用 chmod +x .claude/hooks/block-rm.sh 使其可執行，以便 Claude Code 可以執行它：jq，因此在嘗試之前請安裝 jq 並確保它在您的 PATH 上。Bash "rm -rf /tmp/build"。以下是發生的情況：
1
事件觸發
PreToolUse 事件觸發。Claude Code 將工具輸入作為 JSON 在 stdin 上發送到 hook：2
匹配器檢查
匹配器
"Bash" 符合工具名稱，因此此 hook 群組啟動。如果您省略匹配器或使用 "*"，群組在事件的每次出現時啟動。3
If 條件檢查
if 條件 "Bash(rm *)" 符合，因為 rm -rf /tmp/build 是符合 rm * 的子命令，因此此處理程式生成。如果命令是 npm test，if 檢查會失敗，block-rm.sh 永遠不會執行，避免程序生成開銷。if 欄位是可選的；沒有它，符合群組中的每個處理程式都執行。4
Hook 處理程式執行
該指令碼檢查完整命令並找到 如果命令是更安全的
rm -rf，因此它將決定列印到 stdout：rm 變體，如 rm file.txt，指令碼會改為執行 exit 0。Exit code 0 且沒有輸出表示 hook 沒有決定要報告，因此工具呼叫會繼續通過正常的權限流程。Hook 可以拒絕呼叫，但保持沉默不會批准它。5
Claude Code 根據結果採取行動
Claude Code 讀取 JSON 決定，阻止工具呼叫，並向 Claude 顯示原因。
設定
Hook 定義在 JSON 設定檔中。設定有三層巢狀結構：- 選擇要回應的 hook 事件，例如
PreToolUse或Stop - 新增 matcher 群組來篩選觸發時機，例如「僅限 Bash 工具」
- 定義一個或多個在符合時執行的 hook 處理常式
本頁針對每個層級使用特定術語：hook 事件指生命週期中的時間點，matcher 群組指篩選條件，hook 處理常式指實際執行的 shell 命令、HTTP 端點、MCP 工具、提示詞或 agent。單獨使用「hook」時指的是整體功能。
Hook 位置
定義 hook 的位置決定其範圍：
雲端工作階段不會讀取您本機的
~/.claude/settings.json。在自行託管環境中，Claude Code 也會執行操作者從 runner 主機的 ~/.claude/ 預先植入的 hook；當 runner 映像檔的受管設定檔屬於 Claude Code 套用的受管來源之一時，Claude Code 也會執行該檔案中的 hook，而依預設，這僅在伺服器受管設定與透過 MDM 傳遞的 Claude Code 政策都未提供受管層級時才會發生。請參閱從您的設定中沿用的項目，了解哪些設定檔與外掛（以及因此哪些 hook）會進入雲端工作階段。
如需設定檔解析的詳細資訊，請參閱設定。
來自設定檔、受管政策設定與外掛的 hook 也會在 subagent 內執行。當 subagent 呼叫工具時，PreToolUse 與 PostToolUse 等工具事件會觸發與主對話中相同的已設定 hook，且輸入會帶有用於識別 subagent 的 agent_id 與 agent_type 通用輸入欄位。
管理員可以在受管設定中使用 allowManagedHooksOnly 來限制可執行的 hook：
- 您的使用者、專案、本機及外掛 hook 會被封鎖。在受管設定
enabledPlugins中強制啟用的外掛所提供的 hook 不受此限 - Claude Code 也會將您的
statusLine、fileSuggestion與subagentStatusLine設定限縮為僅採用受管設定 - 除非
disableCommandPluginSources明確設為false，否則 Claude Code 也會停用具有command來源的外掛，包括在受管設定enabledPlugins中強制啟用的外掛。command來源需要 Claude Code v2.1.229 或更新版本 - 除非
disableCommandPluginSources明確設為false，否則 Claude Code 也會封鎖市集的headersHelper命令，但受管設定本身宣告的市集除外
allowManagedHooksOnly 下會執行的項目。
Hook 項目會在各設定層級之間合併，而不是互相取代：使用者、專案與本機設定會加入各自的 hook，而不會移除受管 hook；且在受管設定以外設定的 disableAllHooks 無法停用受管 hook。
HTTP hook 允許清單適用於所有來源的 hook，包括受管政策設定：
allowedHttpHookUrls：只要在任一設定層級中定義，Claude Code 僅會在 HTTP hook 處理常式的 URL 符合合併後的允許清單時執行它httpHookAllowedEnvVars：定義後，Claude Code 只會將清單上的環境變數插入 hook 標頭中
Matcher 模式
matcher 欄位用於篩選 hook 的觸發時機。Matcher 的評估方式取決於其包含的字元：
走正規表示式路徑的 matcher 會以 JavaScript 的
RegExp.prototype.test 進行測試，只要值中任何位置有符合即成功。Edit.* 同時符合 Edit 與 NotebookEdit；需要完整字串比對時，請以 ^ 與 $ 包住模式，例如 ^Edit$。
FileChanged 與 StopFailure 使用較窄的精確比對字元集，僅限字母、數字、_ 與 |。這兩個事件的 matcher 中若含有連字號、空格或逗號，就會走正規表示式路徑，且只有 | 能分隔替代項目。下表中其他支援 matcher 的事件皆接受 | 或 ,。
FileChanged 事件在建立監看清單時不遵循這些規則。請參閱 FileChanged。
每種事件類型比對的欄位不同：
以
cloud_credential_error 比對 StopFailure 需要 Claude Code v2.1.267 或更新版本，這是第一個以該值回報憑證載入失敗，而非以 server_error 或 unknown 回報的版本。
對於大多數事件，Claude Code 會以它透過 stdin 傳送給您的 hook 的 JSON 輸入中的某個欄位來評估 matcher。對於工具事件，該欄位為 tool_name。對於 PreModelSwitch 與 PostModelSwitch，Claude Code 會以從 to_model 推導出的標準名稱來評估 matcher，如 PreModelSwitch 中所述。每個 hook 事件章節都列出了該事件完整的 matcher 值與輸入 schema。
此範例僅在 Claude 寫入或編輯檔案時執行 lint 指令碼：
matcher 欄位，該欄位會被靜默忽略。
對於工具事件，您可以在個別 hook 處理常式上設定 if 欄位以進一步縮小篩選範圍。if 使用權限規則語法同時比對工具名稱與引數，因此 "Bash(git *)" 會在 Bash 輸入的任何子命令符合 git * 時執行，而 "Edit(*.ts)" 僅對 TypeScript 檔案執行。
比對 MCP 工具
MCP 伺服器的工具在工具事件（PreToolUse、PostToolUse、PostToolUseFailure、PermissionRequest、PermissionDenied）中會以一般工具的形式出現，因此您可以用比對其他工具名稱的相同方式來比對它們。
MCP 工具遵循 mcp__<server>__<tool> 命名模式，例如：
mcp__memory__create_entities：Memory 伺服器的建立實體工具mcp__filesystem__read_file：Filesystem 伺服器的讀取檔案工具mcp__github__search_repositories：GitHub 伺服器的搜尋工具
.*。.* 是必要的：像 mcp__memory 或 mcp__brave-search 這樣的 matcher 只包含精確比對字元，因此會被當作精確字串比較，不會符合任何工具。
mcp__memory__.*符合memory伺服器的所有工具mcp__brave-search__.*符合名稱含有連字號的伺服器的所有工具mcp__.*__write.*符合任何伺服器中名稱以write開頭的任何工具
mcp__plugin_<plugin-name>_<server-name>__<tool>。針對單純伺服器鍵撰寫的 matcher 永遠不會對這些工具觸發。例如名為 my-plugin 的外掛以鍵 db 綁定了一個伺服器，則 query 工具會顯示為 mcp__plugin_my-plugin_db__query，因此比對該伺服器所有工具的 matcher 為 mcp__plugin_my-plugin_db__.*。在處理常式的 if 欄位中也請使用相同的範圍化工具名稱。請參閱外掛提供的 MCP 伺服器，了解範圍化名稱的組成方式。
此範例會記錄所有 memory 伺服器的操作，並驗證來自任何 MCP 伺服器的寫入操作：
Hook 處理常式欄位
內層hooks 陣列中的每個物件都是一個 hook 處理常式：即 matcher 符合時執行的 shell 命令、HTTP 端點、MCP 工具、LLM 提示詞或 agent。共有五種類型：
- 命令 hook（
type: "command"）：執行 shell 命令。您的指令碼會透過 stdin 接收事件的 JSON 輸入，並透過退出碼與 stdout 回傳結果。 - HTTP hook（
type: "http"）：將事件的 JSON 輸入以 HTTP POST 請求傳送至某個 URL。端點會透過回應主體，以與命令 hook 相同的 JSON 輸出格式回傳結果。 - MCP 工具 hook（
type: "mcp_tool"）：呼叫已設定的 MCP 伺服器上的工具。工具的文字輸出會比照命令 hook 的 stdout 處理。 - 提示詞 hook（
type: "prompt"）：將提示詞傳送給 Claude 模型進行單回合評估。模型會以 JSON 回傳其決定。請參閱以提示詞為基礎的 hook。 - Agent hook（
type: "agent"）：產生一個 subagent，可使用 Read、Grep 與 Glob 等工具驗證條件後再回傳決定。Agent hook 屬實驗性功能，可能會變更。請參閱以 agent 為基礎的 hook。
$CLAUDE_CODE_REMOTE 環境變數在遠端 Web 環境中為 "true"，在本機 CLI 中則未設定。Claude Code v2.1.199 及更新版本會在本機工作階段具有作用中的 Remote Control 連線時，將 $CLAUDE_CODE_BRIDGE_SESSION_ID 設為 Remote Control 工作階段 ID。
通用欄位
這些欄位適用於所有 hook 類型：if 欄位只能容納一條權限規則。沒有 &&、|| 或清單語法可用來組合規則；若要套用多個條件，請為每個條件分別定義 hook 處理常式。
在檔案工具的 if 條件中，像 "Edit(src/**)" 這樣的單一區段目錄模式只會符合工作目錄中的 src 目錄及其下的檔案。若要符合任意深度中名為 src 的目錄，請寫成 "Edit(**/src/**)"。在 v2.1.214 之前，"Edit(src/**)" 會符合工作目錄下任意深度中名為 src 的目錄。
if 模式如何比對 Bash 命令
對於 if 欄位中的 Bash 模式，您的 hook 命令是否執行取決於模式的形式以及 Claude 所叫用的 Bash 命令。比對前會先移除開頭的 VAR=value 指派。
當 Claude Code 無法判斷 Bash 輸入會執行哪些命令時，無論模式為何都會執行您的 hook。由於
if 篩選僅為盡力而為，若要強制實施嚴格的允許或拒絕，請使用權限系統而非 hook。
命令 hook 欄位
除了通用欄位之外，命令 hook 還接受下列欄位：
設定了
args 時，命令 hook 會以 exec 形式執行；省略 args 時則以 shell 形式執行。只要 hook 參照了路徑預留位置，就請設定 args，因為每個元素都會作為單一引數傳遞，無需加引號。當您需要管線或 && 等 shell 功能，或上述兩種情況都不適用時，請省略 args。
Exec 形式在有 args 時執行。Claude Code 會將 command 解析為 PATH 上的可執行檔，並以 args 作為引數向量直接產生它。由於沒有 shell，每個 args 元素都會完全依照所寫的內容成為一個引數，而 ${CLAUDE_PLUGIN_ROOT} 等路徑預留位置會以純字串形式代入 command 與每個 args 元素。撇號、$ 與反引號等特殊字元會原封不動地傳遞，因為沒有 shell 會解譯它們。在任何平台上都不會進行 shell 斷詞。
Shell 形式在沒有 args 時執行。command 字串會傳給 shell：macOS 與 Linux 上為 sh -c，Windows 上為 Git Bash，未安裝 Git Bash 時則為 PowerShell。設定 shell 欄位可明確選擇。Shell 會對字串進行斷詞、展開變數，並解譯管線、&&、重新導向與萬用字元。
在 Windows 上，exec 形式要求
command 解析為真正的可執行檔，例如 .exe。npm、npx、eslint 與其他工具安裝在 node_modules/.bin 中的 .cmd 與 .bat shim 並非可執行檔，無法在沒有 shell 的情況下產生。若要以 exec 形式執行它們，請直接以 node 叫用底層指令碼，例如 "command": "node", "args": ["${CLAUDE_PLUGIN_ROOT}/node_modules/eslint/bin/eslint.js"]。node 加上指令碼路徑的模式在所有平台上都可運作，因為 node.exe 是真正的二進位檔。若要依名稱執行 .cmd 或 .bat shim，請使用 shell 形式。CLAUDE_PROJECT_DIR、CLAUDE_PLUGIN_ROOT 與 CLAUDE_PLUGIN_DATA，因此無論指令碼是如何啟動的，都能讀取 process.env.CLAUDE_PLUGIN_ROOT。
外掛 hook 另外還會代入 ${user_config.*} 值，但僅限 exec 形式：該值會以純字串形式代入 command 與每個 args 元素，因此不會被 shell 重新剖析。
command 參照 ${user_config.*} 的 shell 形式外掛 hook 會以錯誤失敗，而不會執行。若要在 shell 形式的 hook 中使用選項值，請讀取 $CLAUDE_PLUGIN_OPTION_<KEY> 環境變數，例如 webhook_url 選項對應的 $CLAUDE_PLUGIN_OPTION_WEBHOOK_URL，或設定 args 將 hook 切換為 exec 形式。在 v2.1.207 之前，shell 形式的外掛 hook 命令也會代入 ${user_config.*}。
在 exec 形式中，
command 只能是可執行檔名稱或路徑。若 command 是不含路徑分隔符號的單純名稱，且在有 args 的情況下包含空白，Claude Code 會記錄警告，因為產生程序將會失敗：不存在名為 node script.js 的可執行檔。請將多餘的 token 移至 args。含有空格的絕對路徑，例如 C:\Program Files\nodejs\node.exe，是單一有效的可執行檔，不會觸發警告。HTTP hook 欄位
除了通用欄位之外，HTTP hook 還接受下列欄位：
Claude Code 會將 hook 的 JSON 輸入作為 POST 請求主體傳送，並帶有
Content-Type: application/json。回應主體使用與命令 hook 相同的 JSON 輸出格式。
錯誤處理方式與命令 hook 不同；請參閱 HTTP 回應處理。
此範例將 PreToolUse 事件傳送至本機驗證服務，並使用 MY_TOKEN 環境變數中的 token 進行驗證：
MCP 工具 hook 欄位
除了通用欄位之外，MCP 工具 hook 還接受下列欄位：
此範例會在每次
Write 或 Edit 後，呼叫 my_server MCP 伺服器上的 security_scan 工具，並傳入被編輯檔案的路徑：
isError: true，hook 會產生非封鎖性錯誤，並繼續執行。
在 hook 可以封鎖或變更結果的事件上，例如 PreToolUse 或 Stop，Claude Code 會在呼叫工具前等待正在連線的伺服器，最多等待 MCP_TIMEOUT，且不超過 hook 本身的 timeout。在觀察性事件上，例如 Notification 或 SessionEnd，則不會等待。
顯示 cached 狀態的伺服器會在 hook 呼叫其工具時進行連線。若此時伺服器未連線，hook 會產生非封鎖性錯誤，並繼續執行。Hook 永遠不會啟動 OAuth 流程，因此請先從 /mcp 驗證伺服器。
啟動時的 SessionStart（包括使用 --continue 或 --resume 時）以及每個 Setup 事件，都會在工作階段的 MCP 伺服器可供 hook 使用之前觸發。Claude Code 會略過這些事件的 mcp_tool hook 而不呼叫工具，且偵錯日誌會記錄 mcp_tool hooks are not available for the 'SessionStart' hook event (no MCP client context)，或指名 Setup 的相同訊息。當 SessionStart 在工作階段稍後（/clear 或壓縮之後）再次觸發時，其 mcp_tool hook 會執行。對於工作階段啟動時所需的任何內容，請改在 SessionStart 上使用 type: "command" hook。
提示詞與 agent hook 欄位
除了通用欄位之外，提示詞與 agent hook 還接受下列欄位：以路徑參照指令碼
使用這些預留位置，以相對於專案或外掛根目錄的方式參照 hook 指令碼，不受 hook 執行時的工作目錄影響：${CLAUDE_PROJECT_DIR}：工作階段啟動時的專案根目錄。Claude Code 也會在 stdio MCP 伺服器與外掛 LSP 伺服器的環境中設定此變數。${CLAUDE_PLUGIN_ROOT}：外掛的安裝目錄，用於與外掛綁定的指令碼。請參閱外掛環境變數，了解此路徑在更新時的行為。${CLAUDE_PLUGIN_DATA}：外掛的持久資料目錄，用於應在外掛更新後保留的相依性與狀態。
Worktree 的情況不同。 若 Claude 在工作階段期間進入 worktree，Claude Code 會讓
${CLAUDE_PROJECT_DIR} 維持原樣，並以另一種方式將 worktree 路徑傳給您的 hook：${CLAUDE_PROJECT_DIR}保持不變：它仍指向工作階段啟動時的專案根目錄，因此像${CLAUDE_PROJECT_DIR}/.claude/hooks/check-style.sh這樣的命令仍會在主要 checkout 中執行指令碼。cwd跟隨 Claude：Claude 進入 worktree 後，hook 輸入 JSON 中的cwd欄位為 worktree 根目錄；Claude 執行cd後則為新的目錄。當 hook 需要知道 Claude 正在哪個目錄中工作時，請讀取此欄位。
${CLAUDE_PROJECT_DIR} 指向何處。- 專案指令碼
- 外掛指令碼
此範例使用
${CLAUDE_PROJECT_DIR}，在任何 Write 或 Edit 工具呼叫後，從專案的 .claude/hooks/ 目錄執行樣式檢查器：Skill 與 agent 中的 hook
除了設定檔與外掛之外，hook 也可以使用 frontmatter 直接定義在 skill 與 subagent 中，其設定格式與以設定為基礎的 hook 相同。Claude Code 保留其註冊的時間長短取決於元件：- Subagent hook：Claude Code 只會在該 subagent 執行期間執行它們，並在其完成時移除。Claude Code 會將此處的
Stophook 轉換為SubagentStop，也就是 subagent 完成時觸發的事件。 - Skill hook：Claude Code 會在您或 Claude 叫用 skill 時註冊它們，並在工作階段剩餘期間持續執行，包括 skill 本身所在回合之後的回合。若要讓 Claude Code 改為在 hook 第一次成功執行後將其移除，請在其上設定
once: true。
PreToolUse hook，會在每個 Bash 命令之前執行安全驗證指令碼：
-p 時。
專案 subagent 中的 frontmatter hook，只有在您為 agent 檔案所在的資料夾接受工作區信任對話方塊後才會執行。-p 工作階段不算作接受。信任資料夾前會執行的項目將此與設定檔規則進行比較，而 subagent 頁面列出了哪些範圍不受此限。在 v2.1.218 之前，這些 hook 可能會從您尚未信任的資料夾執行。
/hooks 選單
在 Claude Code 中輸入 /hooks，即可開啟已設定 hook 的唯讀瀏覽器。清單會標示每個 hook 的來源，例如使用者設定、專案設定、本機設定、外掛或目前的工作階段。
選取某個 hook 即可查看其執行內容的完整文字以及定義位置，例如其設定檔的路徑或其外掛的名稱。
若要瀏覽所有 hook 事件，包括未設定任何 hook 的事件，請在清單末端選取 All events。
停用或移除 hook
若要移除定義在設定檔中的 hook，請從該檔案中刪除其項目。 若要暫時停用所有 hook 而不移除它們，請在您的設定檔中設定"disableAllHooks": true。Claude Code 會讀取套用設定優先順序後剩下的值，因此專案 .claude/settings.json 中的 "disableAllHooks": false 會覆寫您使用者設定中的 true。若要不論專案設定為何都在單次執行中關閉 hook，請傳入 --settings '{"disableAllHooks": true}'，它會優先於專案與本機設定。無法在保留於設定中的同時停用個別 hook。
disableAllHooks 設定會遵循受管設定的階層。若管理員已透過受管政策設定來設定 hook，則在使用者、專案或本機設定中設定的 disableAllHooks 無法停用這些受管 hook。只有在受管設定層級設定的 disableAllHooks 才能停用受管 hook。如需各層級的完整作用範圍，請參閱 disableAllHooks。
直接編輯設定檔中的 hook，通常會由檔案監看程式自動偵測並套用。
Hook 輸入和輸出
命令 hook 透過 stdin 接收 JSON 資料，並透過退出碼、stdout 和 stderr 傳回結果。HTTP hook 接收相同的 JSON 作為 POST 請求正文，並透過 HTTP 回應正文傳回結果。本部分涵蓋所有事件通用的欄位和行為。每個事件在 Hook 事件 下的部分包括其特定的輸入 schema 和決定控制選項。 在 macOS 和 Linux 上，命令 hook 在沒有控制終端機的自己的工作階段中執行。Hook 程序和任何子程序無法開啟/dev/tty 或直接向 Claude Code 介面發送逃逸序列。Windows 沒有 /dev/tty。
要在任何平台上向使用者顯示訊息，請在 JSON 輸出中返回 systemMessage。某些事件會捨棄它或將其傳遞到其他地方，每個 事件的部分 都會說明。要觸發桌面通知、設定視窗標題或響鈴，請改為返回 terminalSequence。
通用輸入欄位
Hook 事件接收這些欄位作為 JSON，除了每個 hook 事件 部分中記錄的事件特定欄位。對於命令 hook，此 JSON 透過 stdin 到達。對於 HTTP hook，它作為 POST 請求正文到達。agent_id 和 agent_type 會告訴您的指令碼 hook 是在哪個 agent 中觸發的，例如 subagent、同一程序內的隊友，或您透過 --agent 選擇的 agent：
只有
SessionStart hook 可以接收 model 欄位，且 Claude Code 不一定包含它。PreModelSwitch 和 PostModelSwitch hook 改為接收 from_model 和 to_model，因此使用 PostModelSwitch hook 來追蹤模型在工作階段期間的變化。
沒有 $CLAUDE_MODEL 環境變數。如果您在 shell 中設定了 $ANTHROPIC_MODEL，hook 可以讀取它，但當您在工作階段期間使用 /model 切換模型時，該值不會改變。
Hook 程序繼承父環境，但不包括 Claude Code 從它產生的每個子程序中移除 的 OTEL_* 匯出器變數，以及當 CLAUDE_CODE_SUBPROCESS_ENV_SCRUB 設定為 1 時它剝離的變數。在套用 HIPAA 設定的工作階段中，Claude Code 也會從 hook 的環境中移除 Anthropic 憑證。
例如，Bash 命令的 PreToolUse hook 在 stdin 上接收此內容：
tool_name、tool_input 和 tool_use_id 欄位是事件特定的。每個 hook 事件 部分記錄了該事件的額外欄位。
退出碼輸出
您的 hook 的退出碼會告訴 Claude Code 是否繼續執行觸發該 hook 的操作，例如工具呼叫或提示詞。完成的執行有以下三種結果之一：- 成功：您的 hook 以 0 退出。Claude Code 套用您的 hook 列印的任何 JSON 輸出 欄位，除非這些欄位阻止或拒絕該操作，否則操作會繼續進行。啟動背景程序的 hook 說明了例外情況。
- 阻止性錯誤：您的 hook 以 2 退出。在 可以阻止的事件 上，Claude Code 會停止該操作。
- 非阻止性錯誤：您的 hook 以任何其他代碼退出，或以其他方式失敗，例如無法啟動或列印無效的 JSON。操作會繼續進行，但 失敗時會阻止操作的 hook 除外，例如將
onFailure設定為"block"的 hook。在PreToolUse等事件上，您會在逐字稿中看到<hook name> hook error通知。
PreToolUse hook 以 1 退出，但列印了通過驗證的 JSON 時，該 JSON 仍可決定接下來發生的情況。要找出您的 hook 在 PreToolUse 等事件上的結果，請將第一欄中它列印到 stdout 的內容與頂端的退出碼對應：
某些事件有自己的規則：
WorktreeCreate：任何非零退出碼都會使 worktree 建立失敗，無論您的 JSON 說什麼。WorktreeRemove：任何非零退出碼會在目錄之後仍然存在時使 worktree 移除失敗。Stop、SubagentStop、TaskCompleted和外掛的UserPromptSubmithook：當您的 hook 以 2 退出、stdout 沒有任何內容，且其 stderr 表示找不到檔案（例如No such file or directory）時，Claude Code 將該次執行視為非阻止性錯誤。Elicitation和ElicitationResult：當您的 hook 以 0 退出時，Claude Code 套用您的hookSpecificOutput，在任何其他退出碼上則忽略它。- 捨棄 hook 輸出的事件，例如
StopFailure：Claude Code 在任何退出碼上都會忽略您的 JSON，但terminalSequence等副作用欄位仍會觸發。
退出碼 0
退出 0 表示成功，是當您列印 JSON 進行結構化控制時的預期退出碼。 對於大多數事件，Claude Code 將 stdout 寫入偵錯日誌，不在逐字稿中顯示。例外是UserPromptSubmit、UserPromptExpansion、SessionStart 和 PostModelSwitch，其中 Claude Code 將純文字 stdout 新增為 Claude 可以看到並據以行動的上下文。
對於非 async 的 hook，當整個輸出是單一 JSON 物件且周圍只有空白時，Claude Code 會將您的 stdout 解析為 JSON 輸出，否則視為純文字或解析失敗：
- 單一 JSON 物件，位於一行或多行：解析為 JSON 輸出。
- 不以
{開頭的輸出，或以{開頭但不以}結尾的輸出：純文字。依此規則，JSON 陣列和帶引號的 JSON 字串都是純文字。 - 兩行或更多行，每行本身都可解析為 JSON，且第一行以
{開頭、最後一行以}結尾：若沒有任何一行是設定欄位的 JSON 輸出物件，則為純文字；若有，則為解析失敗。 - 其他任何以
{開頭並以}結尾但不是有效 JSON 的內容：解析失敗。
<hook name> hook error 通知帶有解析或驗證訊息。在將純文字 stdout 新增為上下文的事件上，Claude Code 不會新增其無法解析的 stdout。
Claude 永遠看不到以 0 退出的 hook 的 stderr。要在 PreToolUse 等事件上自行讀取它，請啟用 偵錯日誌。要從 PostToolUse 或 PostToolUseFailure hook 向 Claude 顯示警告，請改為退出 2，以便 Claude 看到 stderr，儘管工具已執行。
退出碼 2
以代碼 2 退出以阻止操作。在 可以阻止的事件 上，Claude Code 會停止該操作：例如，PreToolUse hook 會阻止工具呼叫，UserPromptSubmit hook 會拒絕提示詞。
隨阻止一起傳回的訊息是您的 hook 的 stderr。如果您的 hook 也列印了做出阻止決定的 JSON，Claude Code 會改用該決定的原因。
即使您的 hook 列印 JSON，退出 2 仍會阻止：
- 通過 schema 驗證的 JSON：Claude Code 仍會讀取 JSON 輸出 欄位，但它們無法覆寫阻止。即使
permissionDecision為"allow"也無法讓操作通過。在Elicitation和ElicitationResult上，exit-2 hook 的hookSpecificOutput會被忽略。 - 未通過 schema 驗證的 JSON：hook 仍會阻止。Claude Code 使用您的 stderr 作為阻止原因，並在偵錯日誌中記錄驗證失敗。
rm 命令，並將每個其他命令留給正常權限流程：
Bash 上的 PreToolUse hook 後，以 rm 開頭的命令會被阻止，Claude 會收到 hook 的 stderr 作為工具的錯誤，前綴為事件名稱、工具名稱和 hook 的命令：
其他退出碼
除非該 hook 是 失敗時會阻止操作的 hook，否則以 0 或 2 以外的退出碼退出，並在 stdout 列印純文字或不列印任何內容，即為 非阻止性錯誤。如果操作繼續進行，您會在逐字稿中看到<hook name> hook error 通知，帶有 Failed with non-blocking status code: 和您的 hook 的 stderr 第一行。
例如，當 Bash 上的 PreToolUse hook 將 something broke 列印到 stderr 並以 1 退出時，PreToolUse:Bash hook error 通知帶有這一行：
settings.json 中拼寫錯誤的路徑代表該 hook 永遠不會執行。要在 hook 無法啟動時阻止操作，請設定 onFailure: "block"。
逾時
除了您使用async: true 執行的命令 hook，Claude Code 會取消達到其 timeout 的 command、http 或 mcp_tool hook，並捨棄 hook 的輸出，因此在大多數事件上，逾時的 hook 不會做出決定。
在 PreModelSwitch 上，在其逾時時被取消的 hook 會阻止模型切換。在 PreToolUse 上，兩個 hook 系列不同：
- 逾時的
command、http或mcp_toolhook 不阻止工具呼叫，但 失敗時會阻止操作的 hook 除外。呼叫透過正常 權限流程 繼續，因此不要指望停滯的 hook 充當閘門。要在command或httphook 逾時時阻止呼叫，請設定onFailure: "block"。 - 超過其逾時的 Agent SDK 回呼 hook 阻止工具呼叫。
啟動背景程序的 hook
如果您的命令 hook 在背景程序中做出決定後就退出，該程序在 Claude Code 停止讀取之後才列印的拒絕不會阻止工具呼叫。對於非 async 的 hook，Claude Code 會在 hook 本身的程序退出後不久完成讀取 hook 的輸出。 請在啟動背景程序之前列印決定，並重新導向該程序的 stdout 和 stderr。如果您的指令碼列印允許決定，然後啟動背景程序而未重新導向該程序的 stdout 和 stderr，Claude Code 會阻止工具呼叫。hook 錯誤包含refusing to honor the suspect capture。
此 PreToolUse hook 指令碼使用 policy-check.sh 列印決定，然後在背景上傳指標：
|| exit $?：讓檢查的退出碼成為 hook 本身的退出碼，因此以 2 退出以拒絕的檢查仍會阻止。否則 hook 會以最後一行的代碼退出，也就是 0。>/dev/null 2>&1 &：在背景執行upload-metrics.sh並重新導向其輸出，使其不會讓 hook 的輸出保持開啟。
policy-check.sh 以 2 退出，然後觸發該 hook 所匹配的工具呼叫。工具呼叫會被阻止。
在 hook 失敗時阻止操作
在大多數事件上，當 hook 失敗或逾時時，Claude Code 仍會執行該操作。如此一來，路徑錯誤或指令碼當機的原則 hook 會讓所有操作通過。若要改為阻止操作，請在command 或 http hook 上設定 "onFailure": "block"。需要 Claude Code v2.1.295 或更新版本。
在沒有 Git Bash 的 Windows 上，未設定
onFailure 的 shell 形式 PreToolUse 或 PermissionRequest 命令 hook 失敗時，可能改為阻止工具呼叫。.claude/settings.json 中的這個 PreToolUse hook 會在每個 Bash 命令之前執行專案指令碼，並在指令碼失敗時阻止該命令：
check-command.js 保持不存在，並要求 Claude 執行 ls 之類的 Bash 命令。Claude Code 會阻止該呼叫，錯誤包含 failed; blocking because onFailure is "block"，後接 node 本身的錯誤輸出（此處截短為一行）：
timed out 而不是 failed。未設定 onFailure 時，同樣缺少的指令碼是非阻止性錯誤，ls 會執行。
以下各項都計為失敗：
- 無法啟動：命令 hook 無法啟動，例如因為指令碼或可執行檔不存在
- 0 或 2 以外的退出碼：對命令 hook 而言，即使它列印了允許操作的 JSON（例如
permissionDecision: "allow"）也會計入。要傳回 JSON 決定，請以 0 退出 - HTTP 錯誤：HTTP hook 的連線失敗，或回應狀態不是 2xx
- 逾時：hook 達到其
timeout - 無效輸出：JSON 輸出 無法解析 或未通過 schema 驗證。對於 HTTP hook，既非空白也非 JSON 物件的 2xx 正文也會計入。命令 hook 的純文字 stdout 不算失敗
"block" 後，失敗會執行 退出碼 2 在該事件上的作用，但 PermissionRequest 除外，在該事件上它會拒絕請求。例如，PreToolUse 失敗會阻止工具呼叫，UserPromptSubmit 失敗會阻止提示詞。
該欄位對以下 hook 沒有作用：
Stop、SubagentStop、TaskCompleted和TeammateIdlehook：在這些事件上，退出碼 2 會讓 Claude 回去繼續工作，而 Claude 無法修復無法執行的 hook- 背景命令 hook：設定
async或asyncRewake的命令 hook
Windows 上沒有 Git Bash 時失敗的 hook
如果被阻止的工具呼叫的錯誤包含以下文字，表示某個PreToolUse 或 PermissionRequest 命令 hook 失敗或逾時，並阻止了該呼叫：
shell 的 shell 形式 hook 在未安裝 Git Bash 時會在 PowerShell 中執行，而為 Bash 撰寫的指令碼在那裡可能無法照原樣執行。請選擇符合您 hook 的修正方式：
- hook 是為 Bash 撰寫的：安裝 Git for Windows，或者如果 Git Bash 安裝在 Claude Code 找不到的位置，請設定
CLAUDE_CODE_GIT_BASH_PATH，然後啟動新的工作階段 - hook 執行單一
.exe，而非.cmd或.bat檔案：將程式放在command中、將其引數放在args中以使用 exec 形式，並新增"onFailure": "block"。Claude Code 接著會在沒有 shell 的情況下啟動該程式。若沒有"onFailure": "block"，當程式失敗、不存在或逾時時，呼叫可能會繼續進行 - hook 是為 PowerShell 撰寫的：在 hook 中新增
"shell": "powershell"和"onFailure": "block"。若沒有"onFailure": "block"，當 hook 仍然失敗或逾時時，呼叫可能會繼續進行。要找出 hook 失敗的原因，請查看 偵錯日誌 - hook 失敗時操作應繼續進行：在 hook 中新增
"onFailure": "continue"
每個事件的退出碼 2 行為
退出碼 2 是 hook 發出「停止，不要這樣做」的方式。效果取決於事件，因為某些事件代表可以被阻止的操作（例如尚未發生的工具呼叫），而其他事件代表已經發生或無法防止的事情。
對於
SessionStart、SubagentStart 和 PostModelSwitch，Claude Code 在逐字稿中將退出碼 2 的 stderr 呈現為 <hook name> hook error 通知，與 非阻止性錯誤 相同的方式。Claude 看不到它，工作階段或 subagent 繼續進行。對於 SubagentStart，通知出現在 subagent 自己的逐字稿中，而不是在父對話中。
HTTP 回應處理
HTTP hook 使用 HTTP 狀態碼和回應正文，而不是退出碼和 stdout。下面的結果適用於大多數事件；在 每個事件表 中有自己的失敗約定的事件（如WorktreeCreate）也會將該約定套用於失敗的 HTTP hook：
- 2xx 且正文為空：成功，等同於退出碼 0 且無輸出
- 2xx 且 JSON 物件正文：使用與命令 hook 相同的 JSON 輸出 schema 進行解析。未通過 schema 驗證的正文是非阻止性錯誤
- 2xx 且任何其他正文，如純文字：非阻止性錯誤，處理方式與非 2xx 狀態相同。Claude Code 不將文字新增到 Claude 的上下文
- 非 2xx 狀態：非阻止性錯誤
- 連線失敗：非阻止性錯誤
- 逾時：hook 被取消，如 逾時 下所述
onFailure: "block"。
JSON 輸出
退出碼只讓您阻止或保持沉默，但 JSON 輸出提供更細緻的控制。與其以代碼 2 退出來阻止，不如退出 0 並將 JSON 物件列印到 stdout。Claude Code 從該 JSON 讀取特定欄位以控制行為，包括用於阻止、允許或升級給使用者的 決定控制。為每個 hook 選擇一種方法：要麼單獨使用退出碼進行信號傳遞，要麼退出 0 並列印 JSON 進行結構化控制。如果您混合它們，退出 2 保持其 阻止效果，Claude Code 仍然讀取 JSON 欄位，但 Exit code 2 下記錄的一個 elicitation 例外除外。
additionalContext、systemMessage 和 initialUserMessage 字串，以及其純 stdout，上限為 10,000 個字元：
- 範圍：Claude Code 分別測量每個字串，即使多個 hook 為同一事件執行。對於 JSON 輸出，每個欄位分別測量；純 stdout 整體測量。
- 超過限制：Claude Code 將輸出儲存到工作階段目錄中的檔案，並將其替換為檔案路徑和最多前 2,000 個字元的預覽。大型有效 Bash 結果的處理方式相同，如 輸出限制 下所述。與該 Bash 上限不同，此上限沒有可提高它的設定或環境變數。
- 讀取檔案：Claude Code 不要求 Claude 讀取檔案，因此將 Claude 必須始終看到的任何內容保持在上限內。
- 通用欄位，如
continue，列在下表中。每個事件都接受它們，但某些事件捨棄它們或將systemMessage傳遞到逐字稿以外的地方。每個事件的部分都會說明。terminalSequence在這些事件上也有效，但 發出終端機通知 下列出的例外除外。 - 頂層
decision和reason由某些事件用來阻止或提供回饋。 hookSpecificOutput是一個巢狀物件，用於需要更豐富控制的事件。它需要一個設定為事件名稱的hookEventName欄位。
要完全停止 Claude：
PreToolUse 和 PostToolUse hook，即使工具呼叫在 Claude 仍在串流回應時失敗或完成，停止仍然適用。
發出終端機通知
Hook 在沒有控制終端機的情況下執行，因此直接將逃逸序列寫入/dev/tty 會失敗。相反，在 terminalSequence 欄位中返回逃逸序列，Claude Code 會透過其自己的終端機寫入路徑為您發出它。這不會產生競爭狀況，在 tmux 和 GNU screen 內有效，並在沒有 /dev/tty 的 Windows 上有效。
該欄位接受由一個或多個允許清單中逃逸序列組成的字串：
- OSC
0、1、2：視窗和圖示標題 - OSC
9：iTerm2、ConEmu、Windows Terminal 和 WezTerm 通知，包括9;4工作列進度 - OSC
99：Kitty 通知 - OSC
777：urxvt、Ghostty 和 Warp 通知 - 單獨的 BEL
systemMessage 和 continue 的事件上也有效，例如 Notification 和 StopFailure。它有兩個限制：
- Claude Code 僅在互動式工作階段中寫入序列，且僅在其介面顯示於螢幕上時。在使用
-p旗標的非互動模式和 Agent SDK 中，它忽略該欄位。 WorktreeCreate命令 hook 無法返回 JSON，因為 Claude Code 將其 stdout 讀取為 worktree 路徑。HTTPWorktreeCreatehook 返回 JSON 並可以包含該欄位。
Notification hook 觸發桌面通知。逃逸序列使用 printf 八進位逃逸建立，因此控制位元組永遠不會出現在 shell 命令列上，並以 jq -n --arg 建立 JSON 輸出，因此通知訊息中的引號、反斜線和換行符號會被正確逃逸：
{ "terminalSequence": "..." } 形式在任何 shell 或語言中都相同。
為 Claude 新增上下文
additionalContext 欄位將字串從您的 hook 傳遞到 Claude 的上下文視窗。Claude Code 將字串包裝在 系統提醒 中，並將其插入到 hook 觸發時的對話位置。Claude 在下一個模型請求時讀取提醒，但它不會在介面中顯示為聊天訊息。
在 hookSpecificOutput 中將 additionalContext 與事件名稱一起返回：
- SessionStart 和 SubagentStart：在對話開始時，在第一個提示詞之前
- UserPromptSubmit 和 UserPromptExpansion：與提交的提示詞一起
- PreToolUse、PostToolUse、PostToolUseFailure 和 PostToolBatch：在工具結果旁邊
- Stop 和 SubagentStop：在回合結束時。對話繼續，以便 Claude 可以對回饋採取行動。請參閱 Stop 決定控制
- PostModelSwitch：與切換後的下一個請求一起。請參閱 PostModelSwitch 決定控制 以了解時機
additionalContext 時，Claude 接收所有值。
如果您的字串包含 <system-reminder> 或 </system-reminder> 標籤，Claude 收到的字串中該標籤的 < 會被替換為 <。
如果值超過 10,000 個字元，Claude Code 會將文字寫入工作階段目錄中的檔案，並改為將檔案路徑與最多前 2,000 個字元的預覽傳遞給 Claude。Claude 可以讀取檔案，但 Claude Code 不要求它這樣做。
使用 additionalContext 來提供 Claude 應該知道的有關您環境目前狀態或剛剛執行的操作的資訊：
- 環境狀態：目前分支、部署目標或啟用中的功能旗標
- 條件式專案規則：哪個測試命令適用於剛編輯的檔案，此 worktree 中哪些目錄是唯讀的
- 外部資料：指派給您的未解決問題、最近的 CI 結果、從內部服務擷取的內容
bun test」之類的措辭讀起來像專案資訊。以帶外系統命令形式呈現的文字可能會觸發 Claude 的提示詞注入防禦，這會導致 Claude 將文字呈現給您，而不是將其視為上下文。
Claude Code 在工作階段逐字稿中儲存注入的文字。對於 PostToolUse 或 UserPromptSubmit 等工作階段中途的事件，當您使用 --continue 或 --resume 繼續時，Claude Code 會重播儲存的文字，而不是為過去的回合重新執行 hook，因此時間戳記或提交 SHA 等值會變得過時。SessionStart hook 會在繼續時再次執行，其 source 設定為 "resume"，或在您新增了 --fork-session 時設定為 "fork"，因此它們可以重新整理其上下文。
決定控制
並非每個事件都支援透過 JSON 阻止或控制行為。支援的事件各自使用不同的欄位集來表達該決定。在編寫 hook 之前，使用此表作為快速參考：
一些事件也可以重寫內容，而不僅僅是允許或阻止它：
PreToolUse：直接位於hookSpecificOutput下的updatedInput會在工具執行前替換其引數。請參閱 PreToolUse 決定控制PermissionRequest：decision物件內的updatedInput。請參閱 PermissionRequest 決定控制PostToolUse：updatedToolOutput替換工具的結果。請參閱 PostToolUse 決定控制UserPromptSubmit：無法替換提示詞；僅在其旁邊注入additionalContext
PreToolUse 攔截外送的工具輸入，在 PostToolUse 攔截傳入的工具結果。
以下是每種模式的實際範例：
- 頂層決定
- PreToolUse
- PermissionRequest
decision 的唯一值是 "block"。要允許操作進行，請從 JSON 中省略 decision，或以 0 退出而不帶任何 JSON：Hook 事件
每個事件都對應 Claude Code 生命週期中可執行 hook 的一個時間點。以下各節依照生命週期的順序排列：從工作階段設定、經過代理式迴圈，到工作階段結束。每一節說明事件何時觸發、支援哪些 matcher、接收的 JSON 輸入，以及如何透過輸出控制行為。SessionStart
在 Claude Code 開始新工作階段或恢復現有工作階段時執行。適合用來載入開發情境，例如現有的 issue 或程式碼庫的近期變更，或是設定環境變數。若是不需要指令碼的靜態情境，請改用 CLAUDE.md。 SessionStart 會在每個工作階段執行，因此請讓這些 hook 保持快速。僅支援type: "command" 和 type: "mcp_tool" hook。關於 mcp_tool hook 何時執行，請參閱 MCP tool hook 欄位。
matcher 值對應工作階段的啟動方式：
在 v2.1.214 之前，分岔出的工作階段回報的 source 為
"resume"。
當您啟動互動式工作階段、在啟動時以 --continue 或 --resume 恢復對話，或執行 /clear 時，SessionStart hook 會在背景執行。您可以立即開始輸入，恢復的對話也會直接顯示，無需等待 hook。Claude 的第一個回應仍會等待 hook 完成，以便其情境能傳達給 Claude。
當您在工作階段內以 /resume 切換對話時，切換會改為等待 hook 完成。若您在背景 hook 仍在執行時執行 /clear 或切換到另一個對話，它們回傳的任何內容都不會套用到工作階段。
啟動時也有相同的等待，包括恢復的工作階段：在 SessionStart hook 仍在執行時送出的提示詞，要等到 hook 完成後才會傳達給 Claude。
在任一種等待期間，按下 Esc 可將提示詞取回輸入框而不送出。hook 會繼續執行。
SessionStart 輸入
除了通用輸入欄位之外，SessionStart hook 還會接收source，以及選擇性的 model、agent_type 和 session_title：
您尚未命名的工作階段仍可能有自動產生的標題。該標題不是自訂標題，也不會出現在
session_title 中。
當 source 為 "resume" 或 "fork"，且逐字稿中至少包含一則 Claude 的回應時，SessionStart hook 還會接收下列四個欄位。您的 hook 可以用它們在第一個請求之前回報恢復一段閒置已久的對話所需的成本，例如透過 systemMessage。這些欄位需要 Claude Code v2.1.251 或更新版本。
此範例顯示一個在最後一則回應 90 分鐘後恢復的工作階段的輸入：
SessionStart 決策控制
SessionStart hook 可以為 Claude 新增情境、提供第一則使用者訊息、設定工作階段標題、監看檔案，以及重新載入 skill。除了所有 hook 都可使用的 JSON 輸出欄位之外，請為每一項回傳對應的欄位：
此輸出會新增情境並為工作階段命名：
initialUserMessage 或 sessionTitle，請在工作階段開始前安裝該外掛。對於在 SessionStart hook 執行完畢後才完成安裝的外掛，Claude Code 會忽略這兩個欄位。
重新載入 hook 安裝的 skill
若要讓 SessionStart hook 安裝的 skill 在同一個工作階段中可用，請回傳reloadSkills。skill 探索通常在 SessionStart hook 完成之前就會執行，因此若沒有此欄位，hook 寫入 ~/.claude/skills/ 或 .claude/skills/ 的檔案可能在第一個提示詞執行時尚未被載入。
此範例會同步共用的 skill 儲存庫並要求重新掃描：
保存環境變數
SessionStart hook 可以存取CLAUDE_ENV_FILE 環境變數，它提供一個檔案路徑，讓您可以為 Claude 在工作階段稍後執行的 shell 命令保存環境變數。
若要設定個別的環境變數，請將 export 陳述式寫入 CLAUDE_ENV_FILE。請使用附加（>>）以保留其他 hook 設定的變數：
export PATH="$PATH:./node_modules/.bin" 中的 $PATH 參照。
在 Claude Code v2.1.296 或更新版本中，PowerShell 命令也會接收 CLAUDE_ENV_FILE 中的變數，但 PowerShell 從不執行該檔案。Claude Code 會從中讀出賦值，並改為複製到 PowerShell 命令的環境中。只有當本工作階段中每個 hook 所寫入的內容，以及您在啟動前將 CLAUDE_ENV_FILE 設為的任何指令碼中，每一行都屬於下列其中一種時，才會這麼做：
- 空白行或
#註解 - 位於行首的單一賦值，寫法為
export NAME=value、declare -x NAME=value或NAME=value，且其值是 Bash 會按原樣使用的值，可由下列部分任意組合而成：僅使用字母、數字及字元_ @ % + = : , . / -的未加引號文字、單引號內的文字，以及其中任何$、反引號或"都已用反斜線跳脫的雙引號內文字
$PATH 的 export PATH="$PATH:./node_modules/.bin"、source 命令，或 direnv export bash 輸出的 $'...' 字串，PowerShell 命令將不會接收任何變數，且 claude --debug 會記錄 Session environment is not all plain assignments。Bash 命令仍會接收所有變數。在 Windows 上，PowerShell 命令也不會接收值中包含 / 或 \ 的變數，因為 Git Bash 和 Windows 的路徑寫法不同。沙箱化的 PowerShell 命令不會接收任何變數。
CLAUDE_ENV_FILE 可供 SessionStart、Setup、CwdChanged 和 FileChanged hook 使用。其他 hook 事件無法存取此變數，在 PowerShell 中執行的 hook 也無法存取，無論是透過 "shell": "powershell"，還是在沒有 Git Bash 的 Windows 上預設執行。Setup
僅在您以--init-only 啟動 Claude Code，或在使用 -p 旗標的非互動模式中搭配 --init 或 --maintenance 啟動時觸發。一般啟動時不會觸發。適合用於您從 CI 或指令碼明確觸發的一次性相依套件安裝或排程清理，與一般的工作階段啟動分開。若要進行每個工作階段的初始化，請改用 SessionStart。
matcher 值對應觸發 hook 的 CLI 旗標：
當您執行
claude --init-only 時，Claude Code 會執行 Setup hook 以及帶有 startup matcher 的 SessionStart hook，然後在不開始對話的情況下結束。
當您以 -p 開始或繼續對話時，也需要提供提示詞，可作為引數或透過 stdin 管道傳入。當 SessionStart hook 提供 initialUserMessage，或您恢復含有延遲工具呼叫的工作階段時，可以省略提示詞。
成功時，--init-only 不會在終端機印出任何內容。若要確認 hook 已執行，請以 claude --debug-file <path> --init-only 啟動，將 <path> 替換為日誌檔案位置，然後檢查日誌中的 Setup 和 SessionStart hook 項目。
由於 Setup 不會在每次啟動時觸發，需要安裝相依套件的外掛不能只依賴 Setup。實務上的做法是在首次使用時檢查相依套件，缺少時再安裝，例如使用一個 hook 或 skill 檢查 ${CLAUDE_PLUGIN_DATA}/node_modules，若不存在則執行 npm install。關於已安裝相依套件的存放位置，請參閱持久資料目錄。若您透過市集發布外掛，可能不需要此做法：Claude Code 在快取外掛時會自動安裝符合條件的 Node.js 套件相依套件。
Setup 輸入
除了通用輸入欄位之外，Setup hook 還會接收trigger 欄位，其值為 "init" 或 "maintenance"：
Setup 決策控制
Setup hook 無法阻擋；無論退出碼為何，執行都會繼續。無論退出碼為何，Claude Code 都會捨棄 Setup hook 的 JSON 輸出欄位，例如systemMessage、continue 和 hookSpecificOutput.additionalContext。使用 -p 時，只有在您以 --output-format stream-json --verbose 啟動的情況下，Setup hook 的 stdout、stderr 和退出碼才會以 hook_response 事件的形式出現在執行輸出中。
Setup hook 可以存取 CLAUDE_ENV_FILE。寫入該檔案的變數會保存到工作階段後續的 Bash 命令中，與 SessionStart hook 相同。Setup 上只會執行 type: "command" hook。Setup 上的 type: "mcp_tool" hook 一律會被略過，如 MCP tool hook 欄位中所述。
InstructionsLoaded
當CLAUDE.md 或 .claude/rules/*.md 檔案被載入情境時觸發。此事件會在工作階段開始時針對預先載入的檔案觸發，並在稍後檔案延遲載入時再次觸發，例如當 Claude 存取包含巢狀 CLAUDE.md 的子目錄，或帶有 paths: frontmatter 的條件式規則相符時。此 hook 不支援阻擋或決策控制。它以非同步方式執行，用於可觀察性目的。
當 Claude 透過 Project instructions 設定直接讀取 AGENTS.md 時，此事件不會觸發。當 CLAUDE.md 匯入您的 AGENTS.md 時會觸發，此時 load_reason 與其他任何匯入的檔案一樣設為 include；當 CLAUDE.md 是指向它的符號連結時也會觸發，視為一般的 CLAUDE.md 載入。
matcher 會比對 load_reason。例如，使用 "matcher": "session_start" 僅針對工作階段開始時載入的檔案觸發，或使用 "matcher": "path_glob_match|nested_traversal" 僅針對延遲載入觸發。
InstructionsLoaded 輸入
除了通用輸入欄位之外，InstructionsLoaded hook 還會接收下列欄位：InstructionsLoaded 決策控制
InstructionsLoaded hook 沒有決策控制。它們無法阻擋或修改指令載入。Claude Code 會捨棄它們的 JSON 輸出欄位，例如systemMessage 和 continue。請將此事件用於稽核日誌、合規追蹤或可觀察性。
UserPromptSubmit
在提示詞送出時、Claude 處理之前執行。這可讓您 根據提示詞或對話新增額外情境、驗證提示詞，或 阻擋特定類型的提示詞。UserPromptSubmit hook 不僅會針對您輸入的提示詞觸發。Claude Code 也會在下列情況執行它們：
- 排程任務觸發時，包括
/loop的每次迭代 - 背景 subagent 向啟動它的工作階段回報時
- 另一個工作階段傳送訊息到您的主要對話時
UserPromptSubmit hook 對於 command、http 和 mcp_tool 類型的預設逾時為 30 秒，短於這些類型在大多數其他事件上的 600 秒預設值。由於此 hook 在每個提示詞之前執行，並會阻擋模型處理直到完成，卡住的 hook 會使工作階段停滯。若您的 hook 需要更多時間，請在 hook 項目中設定 timeout 欄位。
除了以 async: true 執行的 command hook 之外，達到逾時的 UserPromptSubmit command、HTTP 或 MCP tool hook 會被取消，其輸出（包括任何 additionalContext）會被捨棄。提示詞仍會在沒有該情境的情況下傳達給 Claude。若要改為阻擋提示詞，請在 command 或 HTTP hook 上設定 onFailure: "block"。逐字稿會顯示一則通知，指出該 hook、觸發的逾時，以及輸出已被捨棄。
UserPromptSubmit 上的 Agent SDK 回呼 hook 若達到逾時，會阻擋提示詞並顯示指出該 hook 和逾時的訊息，因為該處的回呼可能扮演不得在失敗時放行的政策閘門。工作階段會繼續。在 v2.1.208 之前，該事件上的回呼逾時會以執行錯誤結束該回合。
UserPromptSubmit 輸入
除了通用輸入欄位之外，UserPromptSubmit hook 還會接收包含所送出文字的prompt 欄位。被收合為 [Pasted text #N] 預留位置的貼上內容會在原處展開後送達。在 Claude Code 為 Claude 標記貼上文字的工作階段中，該展開內容位於 <pasted_content id="…"> 行和 </pasted_content id="…"> 行之間，因此若您的 hook 會解析提示詞，請將這些行納入考量。
當工作階段有自訂標題時，UserPromptSubmit hook 也會接收 session_title，其意義與 SessionStart session_title 欄位相同。
/deploy staging）時，hook 接收的是您輸入的那一行原文，而非展開後的 skill 內容。如果 hook 阻擋了該提示詞，命令就不會執行，因此 skill 以 !`<command>` 注入的 shell 命令也不會執行。若要改為比對命令的名稱或引數，請使用 UserPromptExpansion。
UserPromptSubmit 決策控制
UserPromptSubmit hook 可以控制是否處理所送出的提示詞，並新增情境。所有 JSON 輸出欄位皆可使用。
在退出碼為 0 時，有兩種方式可以將情境加入對話：
- 純文字 stdout：Claude Code 會將其視為純文字的 stdout 加入 Claude 的情境
- 帶有
additionalContext的 JSON：使用下方的 JSON 格式以獲得更多控制。additionalContext欄位會作為情境加入
additionalContext 值各自以 hook 名稱開頭的系統提醒形式注入；Claude 會讀取兩者。若要確認已傳遞，請查看除錯日誌。
若要阻擋提示詞，請回傳 decision 設為 "block" 的 JSON 物件：
以退出碼 2 阻擋的 hook，其處理方式與
reason 相同：阻擋訊息會向使用者顯示 stderr 文字，且不會加入情境。
被阻擋的提示詞會留下什麼
被阻擋的提示詞永遠不會傳達給 Claude，但其文字並不會從所有地方移除。預設情況下，向使用者顯示的阻擋訊息結尾為Original prompt:，後接所送出的文字，而 Claude Code 會將該訊息寫入磁碟上的工作階段逐字稿檔案。若要在訊息中省略該文字，請在 hookSpecificOutput 內印出帶有 "suppressOriginalPrompt": true 的 JSON。無論 hook 是以 decision: "block" 還是以退出碼 2 阻擋，此設定皆有效。
suppressOriginalPrompt 只會變更阻擋訊息。所送出的文字仍可能出現在本機檔案中，例如工作階段逐字稿和您的提示詞歷程記錄，因此阻擋 hook 並不是讓機密不落入磁碟的方法。若要限制或移除這些檔案，請參閱純文字儲存和清除本機資料。
UserPromptExpansion
在使用者輸入的命令展開為提示詞、傳達給 Claude 之前執行。可用於阻擋特定命令被直接呼叫、為特定 skill 注入情境，或記錄使用者呼叫了哪些命令。例如，比對deploy 的 hook 可以在沒有核准檔案時阻擋 /deploy，或比對某個審查 skill 的 hook 可以將團隊的審查檢查清單作為 additionalContext 附加。
此事件涵蓋了 PreToolUse 未涵蓋的路徑：比對 Skill 工具的 PreToolUse hook 只會在 Claude 呼叫該工具時觸發，但直接輸入 /skillname 會繞過 PreToolUse。UserPromptExpansion 會在該直接路徑上觸發。
比對 command_name。將 matcher 留空可針對每個提示詞類型的命令觸發。
UserPromptExpansion 輸入
除了通用輸入欄位之外，UserPromptExpansion hook 還會接收expansion_type、command_name、command_args、command_source，以及原始的 prompt 字串。expansion_type 欄位對於 skill 和自訂命令為 slash_command，對於 MCP 伺服器提示詞則為 mcp_prompt。
UserPromptExpansion 決策控制
UserPromptExpansion hook 可以阻擋展開或新增情境。所有 JSON 輸出欄位皆可使用。
以退出碼 2 阻擋的 hook，其處理方式與
reason 相同：阻擋訊息會向使用者顯示 stderr 文字。
MessageDisplay
在助理訊息串流顯示到螢幕上時執行。Claude Code 會分段顯示訊息：每當有一批新完成的行準備好呈現時，hook 會以這些行執行一次，Claude Code 則在其位置呈現 hook 的替換文字。長訊息會產生多次呼叫；短訊息可能只產生一次。 使用 MessageDisplay 來：- 移除 markdown 以呈現精簡的顯示
- 轉換 Agent SDK 應用程式向其使用者顯示的文字
- 從 Claude 的回應中遮蔽 API 金鑰或內部主機名稱
timeout 欄位。
MessageDisplay 僅影響顯示：替換文字只會變更螢幕上呈現的內容。逐字稿和 Claude 所見的內容會保留原始文字，因此 Claude 永遠看不到替換內容，詳細模式也會顯示原始文字。hook 只接收助理訊息的文字，因此工具結果和您輸入的文字會原封不動地呈現。
MessageDisplay 不支援 matcher，並會針對每則串流文字的助理訊息觸發；沒有文字的訊息（例如僅包含工具呼叫的回應）不會觸發它。
在非互動式執行中，包括 Agent SDK 查詢和 claude -p，MessageDisplay 會對每則助理訊息執行一次，而不是每批行執行一次。這單次呼叫會在訊息完成後到達，並攜帶完整的訊息文字：index 為 0、final 為 true，delta 則包含整則訊息。收集每則訊息 delta 文字的 hook，在兩種模式下接收到的總文字相同。
MessageDisplay 輸入
除了通用輸入欄位之外，MessageDisplay hook 還會接收回合和訊息的識別碼、此次呼叫在訊息中的位置，以及delta 中的新文字。批次邊界取決於文字的串流方式，因此請使用 index 和 final 追蹤訊息的進度，而不要預期行會以特定方式分組。
MessageDisplay 輸出
除了所有 hook 都可使用的 JSON 輸出欄位之外，MessageDisplay hook 還可以回傳displayContent，以在螢幕上取代 delta：
MessageDisplay hook 沒有決策控制。它們無法阻擋訊息，也無法變更儲存在逐字稿中或傳送給 Claude 的內容。Claude Code 會依據其 JSON 輸出中的
displayContent 採取動作，並捨棄 systemMessage 和 continue。
此範例會從 Claude 的回應中移除 markdown 格式，以純文字方式顯示。指令碼會從 stdin 讀取每一批，從 delta 中移除粗體標記和行內程式碼反引號，並將結果作為 displayContent 回傳。
- macOS/Linux
- Windows (PowerShell)
在您的設定檔中為此事件註冊一個 command hook：將此指令碼儲存至專案中的
.claude/hooks/plain-display.sh，並以 chmod +x 使其可執行：jq，Claude Code 會顯示原始文字，並只在除錯輸出中記錄該失敗，而不會在工作階段中顯示。
PreToolUse
在 Claude 建立工具參數之後、處理工具呼叫之前執行。比對EndConversation 以外的任何工具名稱：內建工具如 Bash、PowerShell、Edit、Write、Read、Glob、Grep、Agent、Workflow、WebFetch、WebSearch、AskUserQuestion 和 ExitPlanMode，以及任何 MCP 工具名稱。
若要在特定檔案於磁碟上變更時執行 hook（無論是誰寫入的），請使用 FileChanged，而不要依名稱比對檔案編輯工具。與 PreToolUse 不同，Claude Code 會在變更之後執行 FileChanged hook，且它們沒有決策控制，因此無法阻擋寫入。
使用 PreToolUse 決策控制來允許、拒絕、詢問或延遲工具呼叫。
PreToolUse 上超過逾時的 Agent SDK 回呼 hook 會封鎖工具呼叫，而 Claude 會收到一個指出逾時的錯誤結果。
PreToolUse 輸入
除了通用輸入欄位之外，PreToolUse hook 還會接收tool_name、tool_input 和 tool_use_id。
對於 MCP 工具，輸入還會攜帶 mcp_server，這是一個包含伺服器 name 以及說明伺服器定義來源之 source 的物件。source 的值包括 plugin、sdk，以及 user 和 project 等設定範圍。Agent SDK 參考文件中的 McpServerProvenance 列出了所有值，並說明如何處理您無法辨識的值。請根據 source 而非 name 或 mcp__<server>__ 工具名稱前綴來做信任決策。mcp_server 欄位需要 Claude Code v2.1.274 或更新版本。
對於檔案工具 Write、Edit 和 Read，tool_input.file_path 一律為絕對路徑：
- Claude Code 會在 hook 執行前展開
~和相對路徑，因此比對路徑的 hook 無法透過~或同一路徑的相對寫法被繞過 - 在 Windows 上，路徑會以反斜線分隔符號送達，即使您的 hook 在 Git Bash 下執行、
$PWD看起來像/c/project也是如此 - 以正斜線撰寫的比較（例如
/src/檢查）永遠不會比對到反斜線路徑，工具呼叫會如同 hook 沒有要阻擋的內容般繼續進行 - 比較前請先正規化分隔符號：在 Bash 中使用
FILE_PATH="${FILE_PATH//\\//}"，或在 Python 中使用file_path.replace("\\", "/")，然後比對/src/之類的路徑片段，而不要以^錨定，因為路徑是絕對路徑
Write 呼叫會傳遞：
tool_input 欄位取決於工具：
執行 shell 命令。
當 Bash 命令變更 Git 儲存庫中的檔案時，Claude Code 可以記錄變更內容。當
bashEditDiffEnabled 設定開啟記錄時，它會在每種權限模式下記錄變更；該設定的項目說明了哪些檔案可以設定它。否則，它只會在自動模式和 bypassPermissions 模式下記錄，且僅在 Claude Code 指示 Claude 透過 Bash 編輯檔案時才記錄。將 bashEditDiffEnabled 設為 false 可關閉記錄。背景命令和唯讀命令不會附帶差異。
接著，您的 PostToolUse hook 會在 tool_response.bashEditDiff 中接收變更的檔案。此清單涵蓋命令執行期間儲存庫中發生的變更。Git 忽略的檔案和子模組中的檔案不會列出。需要 Claude Code v2.1.269 或更新版本。
此清單為盡力而為，且處於公開測試版。Claude Code 可能遺漏某項變更、納入另一個程序同時變更的檔案，或在達到大小限制時停止。欄位結構可能會變更。請使用此清單來找出需要審查的內容，而不要用來強制執行政策。
changedFiles 和 files 列出命令變更的內容；其餘欄位說明該清單的完整程度和可靠程度。
執行 PowerShell 命令。關於各平台的可用性，請參閱 PowerShell 工具。
欄位與 Bash 工具相同，命令字串位於
command：
在檢查 shell 命令的 hook 中比對
Bash|PowerShell，以涵蓋兩種工具：
- 在 Windows 上，只要啟用了 PowerShell 工具，Claude 就會將 PowerShell 視為主要 shell，並透過它傳送 shell 命令。
- 在沒有 Git Bash 的 Windows 上，該工具會自動啟用，且 Claude Code 完全不會註冊 Bash 工具。
- 只比對
Bash的 hook 在那裡永遠不會觸發。
取代現有檔案中的字串。
讀取檔案內容。
尋找符合 glob 模式的檔案。
使用正規表示式搜尋檔案內容。
擷取並處理網頁內容。
搜尋網路。
產生一個 subagent。
當前景 Agent 呼叫完成時，您的 PostToolUse hook 會在
tool_response 中接收 subagent 的結果和執行遙測。讀取這些欄位以檢視執行情況；若要彙總各 subagent 的 token 和成本，請使用以 query_source "subagent" 篩選的 token 和成本計數器，因為 totalTokens 和 usage 只涵蓋最後一個請求：
在 Claude Code v2.1.271 或更新版本中，以
SubagentHandback 工具執行的 subagent（Claude Code 在自動模式中提供此工具）會透過該工具提交報告，而不是以文字回傳。此時其 completed 結果的 content 欄位會攜帶一則關於該交回的簡短說明，而非報告本身。若要讀取報告，請讓 PreToolUse 或 PostToolUse hook 比對 SubagentHandback，並讀取 tool_input.message。
對於背景 subagent，工具會在任務移至背景時回傳，因此 tool_response 不攜帶任何用量欄位：背景啟動會立即回傳，而被 Claude Code 在執行中途移至背景的前景任務則會在該轉換時回傳。它包含 status: "async_launched"、agentId、description、prompt、outputFile 和 resolvedModel。
在 completed 回應中，resolvedModel 指的是 subagent 起始使用的模型，可能與 tool_input 中的 model 值不同，例如套用了 availableModels 或其他覆寫時。在 async_launched 回應中，resolvedModel 指的是 agent 移至背景時所使用的模型，因此在移至背景之前發生的切換會反映在其中。modelsUsed 以及移至背景時的 resolvedModel 行為需要 Claude Code v2.1.212 或更新版本。
向使用者詢問一到四個多選題。
呈現計畫，並在 Claude 離開 plan mode 之前請使用者核准。Claude 會在呼叫工具之前將計畫寫入磁碟上的檔案，因此模型傳來的原始
tool_input 通常是空的。Claude Code 會在將輸入傳給 hook 之前注入計畫內容和檔案路徑。
在
PostToolUse 中，tool_response 是一個物件，其中的 plan 和 filePath 欄位包含已核准的計畫，另外還有內部狀態旗標。請讀取 tool_response.plan 取得計畫內容，而不要從磁碟重新讀取檔案。
PreToolUse 決策控制
PreToolUse hook 可以控制工具呼叫是否繼續。與其他使用頂層 decision 欄位的 hook 不同，PreToolUse 會在 hookSpecificOutput 物件內回傳其決策。這讓它擁有更豐富的控制：四種結果（允許、拒絕、詢問或延遲），以及在執行前修改工具輸入的能力。
當多個 PreToolUse hook 回傳不同的決策時，優先順序為
deny > defer > ask > allow。
以退出碼 2 阻擋的 hook，其處理方式與 "deny" 相同：Claude 會將 stderr 訊息視為拒絕原因。
當 hook 回傳 "ask" 時，向使用者顯示的權限提示會包含一個標籤，指出該 hook 的來源：來自任何設定檔或 agent frontmatter 的 hook 為 [settings]，外掛的 hook 為 [plugin:<name>]，來自 skill frontmatter 的 hook 則為 [skill]。這有助於使用者了解是哪個設定來源在要求確認。
hook 的 "ask" 也會在自動模式中強制顯示權限提示：分類器仍可拒絕工具呼叫，但無法在不提示的情況下核准該呼叫。在 v2.1.211 之前，分類器可以在不顯示 hook 所要求之提示的情況下，核准在沙箱外執行的 Bash 命令；分類器仍會對該命令套用其自身的安全規則，而 hook 的 "deny" 一律會被遵守。
PreToolUse 先前使用頂層的
decision 和 reason 欄位，但這些欄位在此事件中已棄用。請改用 hookSpecificOutput.permissionDecision 和 hookSpecificOutput.permissionDecisionReason。已棄用的值 "approve" 和 "block" 分別對應到 "allow" 和 "deny"。PostToolUse 和 Stop 等其他事件則繼續以頂層 decision 和 reason 作為其目前的格式。需要使用者互動的工具
AskUserQuestion 和 ExitPlanMode 需要使用者互動。在使用 -p 旗標的非互動模式中，只有當執行具有可接收提示的權限主機（例如 Agent SDK 的 canUseTool 回呼）時，Claude Code 才會提供這些工具。
PreToolUse hook 在執行下列動作時即可滿足該需求：
- 從 stdin 讀取工具的輸入
- 透過您自己的 UI 收集答案
- 回傳
permissionDecision: "allow"，並搭配包含答案的updatedInput，讓工具在不提示的情況下執行
"allow" 是不夠的。
對於 AskUserQuestion，請回傳原始的 questions 陣列，並新增一個 answers 物件，將每個問題的文字對應到所選答案。此輸出以 React 回答一個問題：
_meta["anthropic/requiresUserInteraction"] 標記的 MCP 工具則更為嚴格：hook 無法以 "allow" 略過其核准提示，無論是否搭配 updatedInput，因為 Claude Code 無法確認 hook 已收集到該工具所需的互動。
將工具呼叫延遲到稍後
"defer" 適用於以子程序方式執行 claude -p 並讀取其 JSON 輸出的整合，例如 Agent SDK 應用程式或建構在 Claude Code 之上的自訂 UI。它讓呼叫端程序可以在工具呼叫處暫停 Claude、透過自己的介面收集輸入，然後從中斷處恢復。Claude Code 只在使用 -p 旗標的非互動模式中遵守此值。在互動式工作階段中，它會記錄警告並忽略 hook 結果。
AskUserQuestion 工具是典型的情況：Claude 想詢問使用者某件事，但沒有終端機可供回答。-p 執行只有在具有權限主機時才會提供 AskUserQuestion，例如您以 --permission-prompt-tool 傳入的 MCP 工具，因此請以此方式啟動執行。來回流程如下：
- Claude 呼叫
AskUserQuestion。PreToolUsehook 觸發。 - hook 回傳
permissionDecision: "defer"。工具不會執行。程序以stop_reason: "tool_deferred"結束，待處理的工具呼叫保留在逐字稿中。 - 呼叫端程序從 SDK 結果讀取
deferred_tool_use，在自己的 UI 中呈現問題，並等待答案。 - 呼叫端程序以相同的權限主機執行
claude -p --resume <session-id>。同一個工具呼叫再次觸發PreToolUse。 - hook 回傳
permissionDecision: "allow"，並在updatedInput中附上答案。工具執行，Claude 繼續。
deferred_tool_use 欄位攜帶工具的 id、name 和 input。input 是 Claude 為該工具呼叫產生的參數，在執行前擷取：
cleanupPeriodDays 保留期清理的約束，該清理預設會在 30 天後依照保留期清理規則刪除工作階段檔案。若恢復時答案尚未準備好，hook 可以再次回傳 "defer"，程序會以相同方式結束。呼叫端程序最終從 hook 回傳 "allow" 或 "deny"，藉此控制何時跳出迴圈。
"defer" 只在 Claude 於該回合中進行單一工具呼叫時有效。若 Claude 同時進行多個工具呼叫，"defer" 會被忽略並顯示警告，工具則會經由一般的權限流程繼續。此限制的原因在於恢復時只能重新執行一個工具：無法在不讓其他呼叫懸而未決的情況下，延遲一批呼叫中的其中一個。
若恢復時延遲的工具已不可用，程序會在 hook 觸發前以 stop_reason: "tool_deferred_unavailable" 和 is_error: true 結束。當提供該工具的 MCP 伺服器在恢復的工作階段中未連線時，就會發生這種情況。deferred_tool_use payload 仍會包含在內，讓您能辨識是哪個工具遺失了。
若要在 plan mode 中恢復延遲的工作階段，請將
--permission-prompt-tool 與 --resume 一起傳入，讓 Claude Code 能呈現計畫以供核准。其他條件請參閱以 -p 在 plan mode 中恢復。需要 Claude Code v2.1.246 或更新版本。當您以 -p 恢復時，Claude Code 不會還原任何其他已儲存的權限模式。它會以新的 claude -p 執行所使用的權限模式啟動，因此若延遲的工作階段使用了 --permission-mode 或 --dangerously-skip-permissions，請再次傳入。當您不使用 -p、以 claude --resume <session-id> 恢復時，Claude Code 會還原已儲存的權限模式，例外情況列於恢復時的權限模式。PermissionRequest
在 Claude Code 即將向您要求使用工具的權限時執行。在無法顯示提示的工作階段中，例如非互動模式中的背景 subagent，Claude Code 仍會執行這些 hook，若沒有 hook 回傳決策，它會拒絕該工具呼叫。對於傳達到--permission-prompt-tool 或 Agent SDK 的 canUseTool 回呼的呼叫，hook 會與您的主機並行執行，並以先做出決定者為準。
使用 PermissionRequest 決策控制代表使用者允許或拒絕。
當您需要在 Claude 要求使用工具權限的當下取得訊號時，請使用此事件。Claude Code 只會在提示已等待約六秒後，才執行 permission_prompt 類型的 Notification hook。
Claude Code 不會針對沙箱化命令的網路請求執行 PermissionRequest hook。若要取得該提示的訊號，請使用 permission_prompt 通知類型。
比對工具名稱，值與 PreToolUse 相同。
PermissionRequest 輸入
PermissionRequest hook 會接收tool_name 與 tool_input 欄位，與 PreToolUse hook 相同，但不含 tool_use_id。對於 MCP 工具，它們也會接收 mcp_server 物件。選用的 permission_suggestions 陣列包含 Claude Code 針對此請求建議的權限更新，例如新增允許規則或變更權限模式。
permission_suggestions 陣列並非您所看到選項的精確清單，因為每個權限對話框會自行建構其選項。有些對話框（例如用於檔案編輯的對話框）完全不讀取此陣列，而是從請求本身推導出選項。會讀取此陣列的對話框，仍可能隱藏某個建議仍保留在陣列中的選項，例如當 allowManagedPermissionRulesOnly 隱藏儲存規則的選項時。它也可能提供沒有對應建議項目的選項，例如 Yes, and switch to auto mode，此選項會直接變更權限模式，而非透過權限更新。
PreToolUse hook 會在每次工具呼叫之前執行，無論是否需要權限。PermissionRequest hook 只會在 Claude Code 即將向您請求權限時執行，或在它原本會自動拒絕某個無法提示的呼叫時執行。這兩個事件都不會針對 EndConversation 觸發。
PermissionRequest 決策控制
PermissionRequest hook 可以允許或拒絕權限請求。除了所有 hook 都可使用的 JSON 輸出欄位之外，您的 hook 指令碼還可以回傳包含以下事件專屬欄位的 decision 物件：
以退出碼 2 結束但未提供
decision 物件的 hook 不會改變權限流程，且其 stderr 會被捨棄。若要授予或拒絕請求，請回傳 decision 物件。
權限更新項目
updatedPermissions 輸出欄位與 permission_suggestions 輸入欄位都使用相同的項目物件陣列。每個項目都有一個決定其他欄位的 type，以及一個控制變更寫入位置的 destination。
帶有
bypassPermissions 的 setMode 只有在您啟動工作階段時已可使用略過模式的情況下才會生效：--dangerously-skip-permissions、--permission-mode bypassPermissions、--allow-dangerously-skip-permissions，或在使用者、--settings 或受管設定中設定 permissions.defaultMode: "bypassPermissions"。否則此更新不會產生任何作用。當 permissions.disableBypassPermissionsMode 停用此模式，或工作階段以受限模式啟動時，此更新同樣不會產生任何作用。無論 destination 為何，bypassPermissions 都不會被保存為 defaultMode。destination 欄位決定變更是僅保留在記憶體中，還是保存到設定檔。
hook 可以將其接收到的其中一個
permission_suggestions 作為自己的 updatedPermissions 輸出回傳。
PostToolUse
在工具成功完成後立即執行。 依工具名稱比對，值與 PreToolUse 相同。 當工具名稱不是合適的篩選條件時，可使用更廣泛的比對方式：- 若要在任何工具成功完成後執行 hook，請省略
matcher或將其設為"*"。接著您的 hook 可以自行找出變更內容，例如執行git status --porcelain，它也會列出git diff遺漏的未追蹤檔案。對於失敗的工具呼叫，請在 PostToolUseFailure 下加入相同的 hook。 - 若要在特定檔案於磁碟上變更時執行 hook（不論是由誰寫入），請使用 FileChanged。當
Bash命令或 Claude Code 以外的程序重寫同一個檔案時，Claude Code 不會執行比對Edit|Write的PostToolUsehook。
PostToolUse 輸入
PostToolUse hook 會在工具已成功執行後觸發。輸入同時包含 tool_input（傳送給工具的引數）與 tool_response（工具回傳的結果）。兩者的確切 schema 取決於工具。檔案工具的 tool_input 路徑格式與 PreToolUse 相同：一律為絕對路徑，並使用平台原生的分隔符號，因此在 Windows 上為反斜線。對於 MCP 工具，輸入也會攜帶 mcp_server 物件。
PostToolUse 決策控制
PostToolUse hook 可以在工具執行後向 Claude 提供回饋。除了所有 hook 都可使用的 JSON 輸出欄位之外，您的 hook 指令碼還可以回傳以下事件專屬欄位：
以下範例取代了
Bash 呼叫的輸出。取代值符合 Bash 工具的輸出結構：
為自動模式分類器註記結果
回傳classifierContext，即可將關於工具呼叫結果的簡短註記傳送給自動模式分類器，而非傳送給 Claude。分類器永遠不會接收工具結果本身，因此此欄位是在分類器審查後續動作之前，告知它呼叫回傳內容的受支援方式。此欄位需要 Claude Code v2.1.236 或更新版本。
以下範例告訴分類器查詢輸出的來源：
- 在 Claude Code 中設定的 hook：對於來自設定檔、外掛、skill 與 agent frontmatter 的 hook，分類器會將註記視為未經驗證、由應用程式提供的上下文。註記永遠無法確立使用者意圖；若註記聲稱您核准或要求了某件事，分類器會將該聲明與您在對話中的訊息進行比對
- 程序內的 Agent SDK 回呼：當嵌入 Claude Code 的應用程式將 hook 註冊為 TypeScript SDK 回呼，並在即時工作階段期間回傳註記時，分類器可能會將註記中轉述的使用者陳述視為使用者意圖。此類陳述可以滿足分類器原本會接受您所傳送訊息作為依據的同意要求，但永遠無法解除您自己的訊息也無法解除的封鎖。工作階段恢復後，Claude Code 會將還原的註記視為未經驗證的上下文。當兩類 hook 都對同一個呼叫進行註記時，分類器會將合併後的註記視為未經驗證
- 長度：Claude Code 將單一工具呼叫的註記上限設為 2,000 個字元，並截斷其餘部分。此上限由回應該呼叫的所有 hook 共用
- 僅限同步回應：Claude Code 會忽略在背景執行之 hook 回應中的此欄位，因為該回應會在 Claude Code 記錄工具結果之後才抵達
- 分類器不記錄的呼叫：分類器的逐字稿會省略唯讀查詢，例如檔案讀取與搜尋。附加在這些呼叫上的註記會被 Claude Code 捨棄
- 與重寫的互動：當註記描述的是您以
updatedToolOutput取代的輸出時，請在同一個 hook 回應中同時回傳這兩個欄位。若該重寫遭拒或被其他 hook 的重寫取代，Claude Code 會捨棄該註記。若您回傳註記時未進行重寫，即使有其他 hook 重寫了輸出，Claude Code 仍會傳遞該註記
PostToolUseFailure
在已開始執行的工具失敗時執行：工具擲出錯誤，或 MCP 工具回傳錯誤結果。可用於記錄失敗、傳送警示，或向 Claude 提供修正回饋。 依工具名稱比對，值與 PreToolUse 相同。此事件不會針對執行前就被拒絕的工具呼叫觸發：未知的工具名稱、未通過 schema 或工具專屬驗證的輸入，或權限拒絕。驗證拒絕會以
tool_use_error 結果回傳，且發生在 hook 執行之前，因此既不會觸發 PreToolUse，也不會觸發 PostToolUseFailure。權限拒絕會觸發 PreToolUse，但不會觸發此事件；請參閱 PermissionDenied。PostToolUseFailure 輸入
PostToolUseFailure hook 會接收與 PostToolUse 相同的tool_name 與 tool_input 欄位，並以頂層欄位提供錯誤資訊。對於 MCP 工具，它們也會接收 mcp_server 物件。例如，失敗的 npm test 命令可能會傳遞：
error 字串通常與 Claude 收到的失敗工具結果文字相同。其格式因工具與失敗情況而異。請讓您的 hook 以 tool_name、is_interrupt 以及 Exit code N 第一行為判斷依據；將字串的其餘部分視為顯示文字，而非穩定的格式。
- 對於 Bash 與 PowerShell，已執行並結束的命令會產生第一行
Exit code N，接著是命令所產生的任何輸出，以單一區塊呈現，stdout 與 stderr 交錯 - 當 Claude Code 無法啟動 shell 程序本身時，payload 也可能只攜帶沒有退出碼行的單純失敗訊息
- Claude Code 會以
... [N characters truncated] ...標記為中心截斷長字串的中間部分，也可能插入自己的行，例如Command timed out after 2m 0s
PostToolUseFailure 決策控制
PostToolUseFailure hook 可以在工具失敗後向 Claude 提供上下文。除了所有 hook 都可使用的 JSON 輸出欄位之外，您的 hook 指令碼還可以回傳以下事件專屬欄位：
PostToolBatch
在批次中的每個工具呼叫都已完成後執行一次，於 Claude Code 向模型傳送下一個請求之前。PostToolUse 會針對每個工具各觸發一次，這表示當 Claude 進行平行工具呼叫時，它會同時觸發。PostToolBatch 則會以完整批次精確觸發一次，因此適合用來注入取決於所執行工具集合、而非任何單一工具的上下文。此事件沒有 matcher。
PostToolBatch 輸入
除了通用輸入欄位之外，PostToolBatch hook 還會接收tool_calls，這是一個描述批次中每個工具呼叫的陣列：
tool_response 包含模型在對應 tool_result 區塊中收到的相同內容。該值是序列化後的字串或內容區塊陣列，與工具輸出的內容完全一致。對於 Read，這表示是帶有行號前綴的文字，而非原始檔案內容。回應可能很大，因此請只解析您需要的欄位。
tool_response 的結構與 PostToolUse 不同。PostToolUse 傳遞的是工具的結構化 Output 物件，例如 Write 的 {filePath: "...", type: "create"}；PostToolBatch 傳遞的則是模型所看到的序列化 tool_result 內容。PostToolBatch 決策控制
PostToolBatch hook 可以為 Claude 注入上下文。除了所有 hook 都可使用的 JSON 輸出欄位之外，您的 hook 指令碼還可以回傳以下事件專屬欄位：
decision: "block" 或 continue: false 會在下一次模型呼叫前停止代理式迴圈。封鎖訊息來自 JSON 的 reason 或 stopReason，或在退出碼 2 時來自 stderr。您會在逐字稿中看到它以警告形式呈現，且它會保留在對話中，因此 Claude 會在對話繼續時看到它。
PermissionDenied
在自動模式拒絕工具呼叫時執行，包括在沒有分類器判定的情況下拒絕，原因是獨立於自動模式之外的安全檢查拒絕了分類器本身的請求，或其回應無法解析。此 hook 只會在自動模式下觸發：當您手動拒絕權限對話框、PreToolUse hook 封鎖呼叫，或 deny 規則相符時，都不會執行。可用於記錄拒絕、調整設定，或告知模型它可以重試該工具呼叫。
依工具名稱比對，值與 PreToolUse 相同。
PermissionDenied 輸入
除了通用輸入欄位之外，PermissionDenied hook 還會接收tool_name、tool_input、tool_use_id 與 reason。對於 MCP 工具，它們也會接收 mcp_server 物件。
PermissionDenied 決策控制
PermissionDenied hook 可以告知模型它可以重試被拒絕的工具呼叫。回傳一個hookSpecificOutput.retry 設為 true 的 JSON 物件：
retry 為 true 時，Claude Code 會在對話中加入一則訊息，告知模型它可以重試該工具呼叫。Claude Code 本身不會撤銷拒絕。若您的 hook 未回傳 JSON，或回傳 retry: false，拒絕維持有效，模型會收到原始的拒絕訊息。
當分類器未對該動作產生判定時，Claude Code 會忽略 retry: true：其回應無法解析，或獨立於自動模式之外的安全檢查拒絕了分類器本身的請求。對於這些拒絕，Claude Code 已在拒絕訊息中告知模型應稍後重試或繼續其他工作。
Notification
在 Claude Code 傳送通知時執行。依通知類型比對。省略 matcher 即可針對所有通知類型執行 hook。 即使關閉了桌面通知，您仍會收到這些 hook 事件：preferredNotifChannel 設定（包括 notifications_disabled）只會改變您接收提醒的方式，而不會影響您的 hook 是否執行。
quota_auto_resume_fired、quota_auto_resume_stale 與 quota_auto_resume_disabled 類型需要 Claude Code v2.1.234 或更新版本。
在終端機工作階段中，針對沙箱化命令網路請求的 permission_prompt 需要 Claude Code v2.1.246 或更新版本。
針對隊員終端機設定問題的 agent_needs_input 需要 Claude Code v2.1.248 或更新版本。
permission_prompt、idle_prompt、elicitation_dialog 與 elicitation_url_dialog 類型與桌面通知共用相同的時機，因此在終端機工作階段中，只有當您看起來不在終端機前時才會看到它們：- 當您約六秒未輸入時，預期會出現
permission_prompt。計時器從權限提示出現時開始，每次按鍵都會使其延後。若要在 Claude 請求使用工具的權限時立即執行 hook，請改用 PermissionRequest。 - 在 Claude 完成回應約 60 秒後，預期會出現
idle_prompt，但前提是您之後未曾輸入，且沒有背景 agent（例如背景 subagent）仍在執行。Claude Code 在等待 claude.ai 用量上限重設期間不會傳送idle_prompt。當等待自行結束時，會改為觸發其中一個quota_auto_resume_*類型。 - 當您約六秒未輸入時，預期會針對 elicitation 表單出現
elicitation_dialog，或針對瀏覽器 URL 請求出現elicitation_url_dialog。兩者與permission_prompt共用相同的六秒門檻：計時器從對話框出現時開始，每次按鍵都會使其延後。
canUseTool 回呼的工作階段中（也就是 Claude Desktop 與 VS Code 擴充功能承載 Claude Code 的方式），Claude Code 對 permission_prompt 的計時方式不同：
- 預期會在 Claude 請求權限約六秒後出現
permission_prompt。Claude Code 不會因為您輸入而延後它。 - 若您或 PermissionRequest hook 較早回應，Claude Code 不會執行
permission_prompt。 - 將
CLAUDE_CODE_DISABLE_PERMISSION_PROMPT_NOTIFY_HOOKS設為1，即可在這些工作階段中關閉permission_prompt。
permission_prompt 不會在這些工作階段中觸發。
使用不同的 matcher，即可依通知類型執行不同的處理常式。以下設定會在 Claude 需要權限核准時觸發權限專屬的警示指令碼，並在 Claude 閒置時觸發另一個通知：
Notification 輸入
除了通用輸入欄位之外，Notification hook 還會接收包含通知文字的message、選用的 title，以及指出觸發類型的 notification_type。
systemMessage 與 continue 欄位，但仍會輸出 terminalSequence，桌面通知範例正是仰賴此欄位。Notification hook 的用途是產生副作用，例如將通知轉送至外部服務。
SubagentStart
在 Claude 使用 Agent 工具產生 subagent 時、在 Claude 恢復 subagent 時，以及每次程序內 agent team 隊員處理新訊息時執行。支援使用 matcher 依 agent 類型名稱篩選。對於內建 agent，這是 agent 名稱，例如general-purpose、Explore 或 Plan。對於自訂 subagent，這是 agent frontmatter 中的 name 欄位，而非檔案名稱。
對於由外掛提供的 subagent，agent 類型是外掛範圍的識別碼，例如 my-plugin:reviewer，而非單純的 frontmatter 名稱。冒號會使外掛範圍的名稱走正規表示式路徑，因此請以 ^ 與 $ 錨定 matcher 以進行精確比對：^my-plugin:reviewer$。
SubagentStart 輸入
除了通用輸入欄位之外，SubagentStart hook 還會接收包含 subagent 唯一識別碼的agent_id，以及包含 matcher 篩選依據之 agent 名稱的 agent_type。
SubagentStop
在 Claude Code subagent 完成回應時執行。依 agent 類型比對，值與 SubagentStart 相同。SubagentStop 輸入
除了通用輸入欄位之外，SubagentStop hook 還會接收stop_hook_active、agent_id、agent_type、agent_transcript_path 與 last_assistant_message。agent_type 欄位是用於 matcher 篩選的值。transcript_path 是主工作階段的逐字稿，而 agent_transcript_path 則是儲存在巢狀 subagents/ 資料夾中的 subagent 自身逐字稿。last_assistant_message 欄位包含 subagent 最終回應的文字內容，因此 hook 無需解析逐字稿檔案即可存取。
並非每個 SubagentStop 事件都來自 Claude 所產生的 subagent。Claude Code 也會為其自身的某些功能執行內部 agent，例如提示詞建議與 /btw 旁支問題，當其中之一完成時，SubagentStop 也會觸發。對於這些事件，agent_type 是工作階段本身執行時所使用的 agent 名稱，例如以 --agent 或 agent 設定所設定者；若工作階段未使用任何 agent 執行，則為空字串。
指定 agent 類型的 matcher 不會比對空的 agent_type。matcher 被省略、為 "" 或 "*"，或是可比對空字串之正規表示式的 hook，也會針對 agent_type 為空的事件執行。
在 Claude Code v2.1.271 或更新版本中，使用 SubagentHandback 工具執行的 subagent 會在停止之前透過該工具傳遞其報告。此時 last_assistant_message 欄位保存的是 subagent 的結尾文字（若有），而非所傳遞的報告。報告是該呼叫的 message 輸入，比對 SubagentHandback 的 PreToolUse 或 PostToolUse hook 會以 tool_input.message 接收它。
SubagentStop hook 也會接收 Stop 輸入中所述的 background_tasks 與 session_crons 陣列。這兩個陣列的範圍都是父工作階段，而非 subagent。
hookEventName 設為 "SubagentStop" 的 hookSpecificOutput.additionalContext，用於提供讓 subagent 繼續執行的非錯誤回饋。回傳帶有 reason 的 decision: "block" 會讓 subagent 繼續執行，並將 reason 作為下一個指令傳遞給 subagent。以退出碼 2 封鎖的 hook 也會以相同方式傳遞其 stderr 訊息。若要在 subagent 回傳後將上下文注入父工作階段，請改為在 Agent 工具上使用 PostToolUse hook。
TaskCreated
在透過TaskCreate 工具建立任務時執行。可用於強制執行命名慣例、要求任務說明，或防止建立特定任務。在沒有 Task 工具的工作階段中，此事件不會觸發。
TaskCreated hook 不支援 matcher，每次發生時都會觸發。
TaskCreated 輸入
除了通用輸入欄位之外，TaskCreated hook 還會接收task_id、task_subject，以及選用的 task_description、teammate_name 與 team_name。
TaskCreated 決策控制
TaskCreated hook 可以使用退出碼 2 或 JSON 決策封鎖建立。無論哪種方式，Claude Code 都會刪除該任務，並將您的訊息作為工具錯誤回傳給 Claude。Claude Code 會忽略此事件的continue: false，Claude 會繼續工作。
- 退出碼 2：Claude Code 會將 stderr 文字作為訊息回傳。
- JSON
{"decision": "block", "reason": "..."}：Claude Code 會將reason作為訊息回傳。
TaskCompleted
在任務被標記為已完成時執行。此事件會在兩種情況下觸發：任何 agent 透過 TaskUpdate 工具明確將任務標記為已完成時，或 agent team 隊員在仍有進行中任務的情況下結束其回合時。可用於在任務關閉前強制執行完成條件，例如通過測試或 lint 檢查。 TaskCompleted hook 不支援 matcher，每次發生時都會觸發。TaskCompleted 輸入
除了通用輸入欄位之外，TaskCompleted hook 還會接收task_id、task_subject，以及選用的 task_description、teammate_name 與 team_name。
TaskCompleted 決策控制
TaskCompleted hook 支援兩種控制任務完成的方式：- 退出碼 2：任務不會被標記為已完成，且 stderr 訊息會作為回饋傳回給模型。
- JSON
{"continue": false, "stopReason": "..."}：當事件是由隊員結束其回合所觸發時，會完全停止該隊員，與Stophook 的行為一致。stopReason會顯示給使用者。當事件是由TaskUpdate工具觸發時，Claude Code 會忽略continue: false；退出碼 2 仍會封鎖完成。
Stop
在主要 Claude Code agent 完成回應時執行。若停止是由使用者中斷所造成，則不會執行。API 錯誤會改為觸發 StopFailure。Stop 輸入
除了通用輸入欄位之外，Stop hook 還會接收stop_hook_active、last_assistant_message、background_tasks 與 session_crons。當 Claude Code 已因 stop hook 而繼續執行時，stop_hook_active 欄位為 true。請檢查此值或處理逐字稿，以避免因永遠無法解決的條件而持續封鎖。
Claude Code 套用 8 次連續繼續的上限：在 stop hook 連續讓回合繼續八次之後，Claude Code 會覆寫下一次封鎖並結束回合。每當 Claude 呼叫工具時，連續繼續的次數就會重設。若要提高上限，請設定 CLAUDE_CODE_STOP_HOOK_BLOCK_CAP。
last_assistant_message 欄位包含 Claude 最終回應的文字內容，因此 hook 無需解析逐字稿檔案即可存取。對於針對剛完成之回合採取動作的 hook（例如朗讀或通知 hook），請使用此欄位，而非讀取 transcript_path：在所有版本中，逐字稿檔案並不保證在 Stop 時已包含最終訊息。
background_tasks 與 session_crons 陣列讓 hook 能夠區分「工作階段已完成」與「工作階段已暫停，等待背景工作將其喚醒」。當任務登錄可存取時，這兩個陣列都會存在；當沒有任何進行中或已排程的項目時，它們為空。
background_tasks 中的每個項目描述一個進行中的任務，並使用以下欄位：
session_crons 中的每個項目描述一個工作階段範圍的排程喚醒，來源為 CronCreate、ScheduleWakeup 與 /loop：
以下範例顯示一個包含一個進行中 shell 任務與一個週期性 cron 的 Stop 輸入：
Stop 決策控制
Stop 與 SubagentStop hook 可以控制 Claude 是否繼續。除了所有 hook 都可使用的 JSON 輸出欄位之外，您的 hook 指令碼還可以回傳以下事件專屬欄位：
以退出碼 2 封鎖的 hook 與
reason 的路由方式相同：Claude 會將 stderr 訊息作為其應繼續的原因說明。
additionalContext。它會透過與 decision: "block" 相同的迴圈保護機制讓對話繼續，也就是 stop_hook_active 輸入與 8 次連續繼續的上限，但逐字稿會將其標記為 Stop hook feedback，且不會顯示 hook 錯誤通知：
StopFailure
當回合因 API 錯誤而結束時，取代 Stop 執行。除了terminalSequence 之外，Claude Code 會忽略此 hook 的輸出與退出碼。當 Claude 因速率限制、身分驗證問題或其他 API 錯誤而無法完成回應時，可用於記錄失敗、傳送警示或採取復原動作。
StopFailure 輸入
除了通用輸入欄位之外，StopFailure hook 還會接收error、選用的 error_details，以及選用的 last_assistant_message。error 欄位識別錯誤類型，並用於 matcher 篩選。
TeammateIdle
在 agent team 隊員結束其回合、即將進入閒置時執行。可用於在隊員停止工作前強制執行品質關卡，例如要求通過 lint 檢查或確認輸出檔案存在。 TeammateIdle hook 不支援 matcher，每次發生時都會觸發。TeammateIdle 輸入
除了通用輸入欄位之外，TeammateIdle hook 還會接收teammate_name 與 team_name。
TeammateIdle 決策控制
TeammateIdle hook 支援兩種控制隊員行為的方式：- 退出碼 2：隊員會接收 stderr 訊息作為回饋，並繼續工作而非進入閒置。
- JSON
{"continue": false, "stopReason": "..."}：完全停止該隊員，與Stophook 的行為一致。stopReason會顯示給使用者。
ConfigChange
在工作階段期間設定檔變更時執行。可用於稽核設定變更、強制執行安全政策，或封鎖對設定檔的未經授權修改。 當設定檔、受管政策檔案或 skill 檔案變更時，Claude Code 會執行 ConfigChange hook。對於受管政策，只有在managed-settings.json 或 managed-settings.d/ 中的檔案變更時才會執行。它會套用伺服器受管設定以及 macOS 受管偏好設定或 Windows 登錄政策的變更，但不會執行這些 hook。在啟用 wslInheritsWindowsSettings 的 WSL 上，它也會在政策輪詢時套用已變更的 Windows 端受管設定檔，而不執行這些 hook。
matcher 依設定來源進行篩選：
以下範例會記錄所有設定變更以進行安全稽核：
ConfigChange 輸入
除了通用輸入欄位之外，ConfigChange hook 還會接收source 以及選用的 file_path。source 欄位指出變更的設定類型，而 file_path 提供被修改之特定檔案的路徑。
ConfigChange 決策控制
ConfigChange hook 可以封鎖設定變更使其不生效。使用退出碼 2 或 JSONdecision 即可阻止變更。遭封鎖時，新設定不會套用至正在執行的工作階段。
policy_settings 變更無法被封鎖。當機器上的受管設定檔變更時，hook 仍會針對 policy_settings 來源觸發，因此您可以用它們記錄這些編輯，但任何封鎖決策都會被忽略。這可確保企業受管設定一律生效。當伺服器受管設定抵達或重新整理時，Claude Code 不會執行 ConfigChange hook。
Claude Code 會依據 ConfigChange hook JSON 輸出中的封鎖決策採取行動，並捨棄 systemMessage 與 continue。無論您是以 reason 封鎖，還是以退出碼 2 搭配 stderr 封鎖，被封鎖的變更都不會向您或 Claude 顯示任何訊息。Claude Code 只會在除錯日誌中寫入一行。
CwdChanged
當主對話中的 shell 命令變更工作目錄時執行，例如 Claude 執行cd 命令時。可用於對目錄變更做出反應：重新載入環境變數、啟用專案專屬的工具鏈，或自動執行設定指令碼。可與 FileChanged 搭配，用於 direnv 等管理各目錄環境的工具。
CwdChanged hook 可以存取 CLAUDE_ENV_FILE。寫入該檔案的變數會保留至後續的 Bash 命令中，直到下一個 CwdChanged 事件時由 Claude Code 清除。
CwdChanged 不支援 matcher，每次發生時都會觸發。
CwdChanged 輸入
除了通用輸入欄位之外，CwdChanged hook 還會接收old_cwd 與 new_cwd。
CwdChanged 輸出
除了所有 hook 都可使用的 JSON 輸出欄位之外，CwdChanged hook 還可以回傳watchPaths，以動態設定 FileChanged 要監看的檔案路徑：
CwdChanged hook 沒有決策控制。它們無法封鎖目錄變更。
Claude Code 會從其 JSON 輸出中讀取
watchPaths 與 systemMessage，並捨棄 continue。在互動式工作階段中，它會將 systemMessage 顯示為簡短的終端機通知。該訊息不會進入 SDK 訊息串流。
DirectoryAdded
在您於工作階段中途使用/add-dir 命令新增工作目錄後，或在 SDK 用戶端以 register_repo_root 控制請求新增工作目錄後執行。可用於準備新加入的儲存庫，例如安裝其相依套件。
在以下情況下，Claude Code 不會觸發此事件：
- 您透過
--add-dir啟動旗標傳入目錄；SessionStart 涵蓋這些目錄 - 您在
/permissions的 Workspace 分頁上新增目錄 - 您新增的目錄已經是工作目錄或位於工作目錄之內
DirectoryAdded 輸入
除了通用輸入欄位之外，DirectoryAdded hook 還會接收directory 與 source。
continue 欄位，並依來源以不同方式呈現其餘部分：
slash_command：Claude Code 會在下一個對話回合將 hook 的systemMessage作為上下文傳遞給 Claude，而不是顯示給您。失敗 hook 的數量會顯示在逐字稿中。完整的失敗輸出會寫入除錯日誌register_repo_root：Claude Code 只會將systemMessage輸出與失敗輸出寫入除錯日誌
FileChanged
在受監看的檔案於磁碟上發生變更時執行。Claude Code 透過檔案系統監看器偵測變更，而非檢查工具呼叫，因此無論是什麼變更了該檔案，它都會執行 hook：Edit 或 Write 工具呼叫、Claude 以 Bash 執行的指令碼，或完全在 Claude Code 之外的程序。常見的用途是在專案設定檔變更時重新載入環境變數。
此事件的 matcher 具有兩種作用：
- 建立監看清單：該值會以
|分割，每個片段都會被註冊為工作目錄中的字面檔名，因此".envrc|.env"會精確監看這兩個檔案。正規表示式在此沒有用處：像^\.env這樣的值會監看一個字面名稱為^\.env的檔案。 - 篩選要執行的 hook：當受監看的檔案變更時，同一個值會依據標準的 matcher 規則，針對變更檔案的基本名稱篩選要執行哪些 hook 群組。
Bash 命令或外部指令碼改寫該檔案）正規化 data.csv 中的行尾字元：
file_path 欄位讀取變更檔案的絕對路徑。它的 grep 防護條件所檢查的，正是 perl 所移除的內容，也就是行尾的 CR，因此正規化之後的那次執行會直接結束而不觸碰該檔案。較寬鬆的防護條件會造成無限迴圈，因為即使 perl -i 沒有取代任何內容也會改寫檔案，而 Claude Code 會在每次改寫後再次執行此 hook。請將此指令碼儲存於 /path/to/normalize-line-endings.sh 並設為可執行：
Bash 命令在 data.csv 附加一行 CRLF。Claude Code 會執行此 hook，檔案最終會使用 LF 行尾。
若要監看無法事先指名的檔案，請從 hook 傳回 watchPaths 以動態更新監看清單。Claude Code 只有在有東西指名要監看的檔案時才會啟動監看器，因此請以一個 matcher 至少指名一個檔案的 FileChanged 群組，或以傳回 watchPaths 的 SessionStart 或 CwdChanged hook 來初始化清單。當受監看的檔案變更時，matcher 仍會篩選要執行哪些 hook 群組，因此請讓處理動態路徑的群組省略 matcher，這樣它會符合每個受監看的檔案，且不會在監看清單中新增任何項目。"*" matcher 同樣會符合每個檔案，但 Claude Code 會像處理其他值一樣將其註冊到監看清單中，成為一個字面名稱為 * 的檔案。
FileChanged hook 可以存取 CLAUDE_ENV_FILE。寫入該檔案的變數會持續套用到後續的 Bash 命令，直到下一次 CwdChanged 事件發生時由 Claude Code 清除為止。
FileChanged 輸入
除了通用輸入欄位之外，FileChanged hook 還會收到file_path 與 event。
FileChanged 輸出
除了所有 hook 皆可使用的 JSON 輸出欄位之外，FileChanged hook 還可以傳回watchPaths，以動態更新要監看的檔案路徑：
FileChanged hook 沒有決策控制。它們無法阻止檔案變更發生。
Claude Code 會從其 JSON 輸出讀取
watchPaths 與 systemMessage，並捨棄 continue。在互動式工作階段中，它會將 systemMessage 顯示為簡短的終端機通知。該訊息不會傳送到 SDK 訊息串流。
WorktreeCreate
在 Claude Code 建立 worktree 時執行，例如以下情況：- 您以
claude --worktree啟動工作階段 - Claude 在工作階段期間建立 worktree，並以
EnterWorktree工具切換進入 - subagent 使用
isolation: "worktree" - 工作流程在自己的 worktree 中執行 agent
- Claude Code 將背景工作階段隔離在其自己的 worktree 中
worktree模式下的claude remote-control在自己的 worktree 中啟動工作階段
git worktree add，而非呼叫 EnterWorktree 時，您的 WorktreeCreate hook 不會執行。若要檢查或封鎖該命令，請新增一個使用 Bash matcher 的 PreToolUse hook。
根據預設，Claude Code 會使用 git worktree 建立隔離的工作副本。設定 WorktreeCreate hook 會取代該預設的 git 行為，讓您可以使用其他版本控制系統，例如 SVN、Perforce 或 Mercurial。
由於此 hook 會完全取代預設行為，因此不會處理 .worktreeinclude。如果您需要將 .env 等本機設定檔複製到新的 worktree，請在 hook 指令碼中完成。
此 hook 必須傳回所建立之 worktree 目錄的路徑。Claude Code 會將此路徑用作隔離工作階段的工作目錄。關於各 hook 類型如何傳回路徑，請參閱 WorktreeCreate 輸出。
Claude Code 會依據 hook 是否成功以及傳回的路徑採取動作，並捨棄 systemMessage 與 continue。
此範例會建立 SVN 工作副本，並印出路徑供 Claude Code 使用。請將儲存庫 URL 替換為您自己的：
name，將全新副本簽出到新目錄，並印出該目錄路徑。最後一行的 echo 就是 Claude Code 讀取為 worktree 路徑的內容。請將其他任何輸出重新導向至 stderr，以免干擾該路徑。
WorktreeCreate 輸入
除了通用輸入欄位之外，WorktreeCreate hook 還會收到name 欄位。這是新 worktree 的 slug 識別碼，可能由使用者指定或自動產生，例如 bold-oak-a3f2。
WorktreeCreate 輸出
WorktreeCreate hook 不使用標準的允許/封鎖決策模型。取而代之的是，由 hook 的成功或失敗決定結果。此 hook 必須傳回所建立之 worktree 目錄的路徑：- 命令 hook（
type: "command"）：將路徑印為 stdout 的最後一個非空白行。Claude Code 會在讀取該行之前移除 ANSI 跳脫碼，因此在您的echo之前印出的 shell 啟動橫幅會被忽略。請將其他任何 hook 輸出重新導向至 stderr。 - HTTP hook（
type: "http"）：在回應主體中傳回{ "hookSpecificOutput": { "hookEventName": "WorktreeCreate", "worktreePath": "/absolute/path" } }。
. 或 .. 片段。如果所得路徑不是 Claude Code 可以進入的目錄，工作階段會印出指名該路徑的錯誤，並以代碼 1 結束。
Claude Code 會拒絕包含 . 或 .. 片段的絕對路徑，以及任何經過儲存庫根目錄之下符號連結的路徑，因為提交到儲存庫的符號連結可能會將 worktree 重新導向到儲存庫之外。錯誤會指名被拒絕的路徑元件。請傳回一個不經過儲存庫內部符號連結的正規化路徑。在 v2.1.216 之前，worktree 建立會直接沿用 hook 的路徑，而不進行此項檢查。
WorktreeRemove
在 Claude Code 清理由您的WorktreeCreate hook 所建立的 worktree 時執行。此事件會在以下情況觸發：
- 您結束互動式 worktree 工作階段，並在 Claude Code 提示時選擇移除 worktree
- 您結束一個尚未命名的互動式 worktree 工作階段，Claude Code 沒有找到已變更或未追蹤的檔案，並在不提示您的情況下移除 worktree
- 您刪除在該 worktree 中執行的背景工作階段
- 您在工作階段期間要求 Claude 結束並移除 worktree，而 Claude 以
ExitWorktree工具將其移除 - 由
claude remote-control以worktree模式啟動的工作階段在未當機的情況下結束，且 Claude Code 在其 worktree 中沒有找到已變更或未追蹤的檔案，也沒有新的提交 - 您在
claude remote-control以worktree模式啟動的工作階段仍在執行時停止它，且 Claude Code 在這些工作階段的 worktree 中沒有找到已變更或未追蹤的檔案，也沒有新的提交
ExitWorktree 呼叫或 claude remote-control 清理，Claude Code 在您的 hook 執行前不會提示您。除非呼叫傳入 discard_changes: true，否則 ExitWorktree 會拒絕移除由 hook 建立的 worktree，這使得您的 hook 成為該途徑上的最後一道檢查。
Claude Code 使用 git 尋找已變更或未追蹤的檔案，因此在不是 git 簽出（或不位於 git 簽出內）的 worktree 中，即使目錄中含有未提交的工作，它也找不到任何檔案。請在您的 WorktreeRemove hook 刪除任何內容之前檢查這類工作。
對於以 git 為基礎的 worktree，Claude Code 會以 git worktree remove 自動處理清理。如果您設定了 WorktreeCreate hook，請搭配 WorktreeRemove hook 來控制清理：
- 沒有 WorktreeRemove hook：對於結束時或透過
ExitWorktree進行的移除，Claude Code 會改用 git；而在claude remote-control進行清理時則會保留 worktree：- 您結束 worktree 工作階段，或 Claude 呼叫
ExitWorktree：Claude Code 會以如同git worktree remove --force的方式移除您的 WorktreeCreate hook 所傳回的路徑，因此 git 能識別的 worktree 會被移除。git 無法識別的 worktree（例如您的 hook 以非 git 版本控制系統建立的 worktree）則會保留在磁碟上。 claude remote-control清理工作階段的 worktree：worktree 會保留在磁碟上，且執行claude remote-control的終端機會顯示worktree removal failed, kept: <path>。- 您刪除背景工作階段：請參閱刪除工作階段會移除哪些內容。
- 您結束 worktree 工作階段，或 Claude 呼叫
- Hook 以 0 結束：worktree 會被視為已移除。Claude Code 不會從 hook 讀取其他任何內容，因此請確保您的 hook 已刪除該目錄。
- Hook 以非零值結束：如果
worktree_path處的目錄之後仍然存在，移除即告失敗，worktree 會保留在磁碟上，且不會改用 git。在以非零值結束前已刪除目錄的 hook 會被視為已移除。關於失敗如何回報，請參閱 WorktreeRemove 輸入。
systemMessage 與 continue。
對於背景工作階段的刪除，Claude Code 會在執行 hook 前驗證所儲存的 worktree 路徑，並拒絕本身為符號連結或經過儲存庫根目錄之下符號連結的路徑。在該途徑上，只有當您在 agent view 中確認刪除時，hook 才會針對仍包含檔案的 worktree 執行；對於此類 worktree，claude rm 則會保留工作階段與 worktree。在 v2.1.216 之前，hook 會在未經這些檢查的情況下針對所儲存的路徑執行。
Claude Code 會將 WorktreeCreate 傳回的路徑作為 hook 輸入中的 worktree_path 傳入。此範例會讀取該路徑並移除目錄：
WorktreeRemove 輸入
除了通用輸入欄位之外，WorktreeRemove hook 還會收到worktree_path 欄位，也就是要移除之 worktree 的絕對路徑。
worktree_path 處的目錄之後仍然存在時，移除即告失敗：
- worktree 會保留在磁碟上，hook 的命令與 stderr 會寫入偵錯日誌。
- 如果您當時正在刪除背景工作階段，該工作階段也會保留。agent view 中的拒絕訊息會回報 hook 的結束方式（例如
exited 1）、引用其 stderr 的開頭，並說明再次刪除工作階段是否仍會移除該目錄。 - 如果
claude remote-control當時正在清理工作階段的 worktree，執行它的終端機會顯示worktree removal failed, kept: <path>。
PreCompact
在 Claude Code 即將執行壓縮作業之前執行。 matcher 值表示壓縮是手動或自動觸發的：
以代碼 2 結束可封鎖壓縮。對於手動的
/compact，stderr 訊息會顯示給使用者。您也可以傳回包含 "decision": "block" 的 JSON 來封鎖。
封鎖自動壓縮會依觸發時機而產生不同效果。如果壓縮是在達到上下文上限之前主動觸發的，Claude Code 會略過它，對話會在未壓縮的情況下繼續。如果壓縮是為了從 API 已傳回的上下文上限錯誤中復原而觸發的，底層錯誤會浮現，且目前的請求會失敗。
Claude Code 會捨棄 PreCompact hook 的 systemMessage 與 continue 欄位。
PreCompact 輸入
除了通用輸入欄位之外，PreCompact hook 還會收到trigger 與 custom_instructions。對於 manual，custom_instructions 包含使用者傳入 /compact 的內容，未傳入任何內容時則為 null。對於 auto，custom_instructions 為 null。
PostCompact
在 Claude Code 完成壓縮作業後執行。使用此事件對新的壓縮後狀態做出反應，例如記錄產生的摘要或更新外部狀態。Claude Code 會捨棄 PostCompact hook 的systemMessage 與 continue 欄位。
適用與 PreCompact 相同的 matcher 值：
PostCompact 輸入
除了通用輸入欄位之外，PostCompact hook 還會收到trigger 與 compact_summary。compact_summary 欄位包含壓縮作業所產生的對話摘要。
PreModelSwitch
在 Claude Code 套用您或用戶端所請求的模型切換之前執行。可用來封鎖切換、要求確認，或在切換發生前顯示切換的成本。 PreModelSwitch 需要 Claude Code v2.1.251 或更新版本。Claude Code 會針對以下請求執行它：/model <name>與/model選擇器Option+P或Alt+P模型選擇器/config中的 Model 設定- 開啟快速模式且因此變更工作階段的模型時
- 來自 Agent SDK 主機或 Remote Control 的
set_model請求，或apply_flag_settings請求中的模型變更
[1m] 後綴。像 opus 這樣的別名、帶日期的模型 ID，以及供應商特定的 ID（例如 Amazon Bedrock 模型 ID）都會符合它們所解析到的同一個標準名稱，因此 claude-opus-5 涵蓋了 Opus 5 的所有寫法。
當 Claude Code 無法判斷目標的標準名稱時（例如只有您的 LLM 閘道知道的自訂模型 ID），它會不論 matcher 為何而執行每個 PreModelSwitch hook。因此，進行封鎖的 hook 應檢查其輸入中的 to_model，而非僅依賴 matcher。
請將 matcher 寫成精確名稱、以 | 分隔的清單（例如 claude-opus-4-6|claude-opus-5），或正規表示式（例如 .*opus.*）。此範例使用精確名稱 matcher，並同時檢查 hook 輸入中的 to_model，因此會以代碼 2 結束來拒絕切換到 Opus 4.6，並放行其他任何目標：
- macOS/Linux
- Windows (PowerShell)
此命令以
jq 檢查 to_model：/model claude-opus-4-6。Claude Code 會保留目前的模型，並回報 PreModelSwitch hook 封鎖了切換，並以您的訊息作為原因。
PreModelSwitch 輸入
除了通用輸入欄位之外，PreModelSwitch hook 還會收到此表中的欄位。最後五個欄位描述將對話重新傳送給新模型的成本，讓 hook 可以在切換發生前顯示該數字。
此範例顯示在執行 Sonnet 5 的工作階段中執行
/model opus 時的輸入：
PreModelSwitch 決策控制
PreModelSwitch hook 可以取消切換、要求使用者確認，或讓切換繼續進行。退出碼 2 或頂層的 decision: "block" 會取消切換。
若要進行更精細的控制，請在 hookSpecificOutput 物件中傳回 permissionDecision 與 permissionDecisionReason，如同 PreToolUse。PreModelSwitch 接受 "allow"、"deny" 與 "ask"。它不接受 "defer"、updatedInput 或 additionalContext。下表說明這兩個欄位：
只有互動式工作階段中的
/model 能顯示 "ask" 提示。在其他所有使用介面上，包括使用 -p 旗標的非互動模式、/config 以及 set_model 請求，Claude Code 都會將 "ask" 視為拒絕。
此範例會要求使用者確認，並引用 context_tokens 中的 token 數：
deny > ask > allow。
無論決策為何，Claude Code 都會向使用者顯示您的 hook 所傳回的任何 systemMessage，因此回報成本的 hook 可以傳回 {"systemMessage": "..."} 並以 0 結束。
PreModelSwitch 逾時及其他退出碼
在逾時之前未回應的 PreModelSwitch hook 會阻擋切換。此事件的預設逾時為 30 秒。 關於 0 或 2 以外的退出碼會產生什麼效果，請參閱其他退出碼。PostModelSwitch
在工作階段的模型變更後執行。可用來為 Claude 提供特定模型的指引，而無需編輯每個 CLAUDE.md，例如適用於特定模型的組織層級指令。 PostModelSwitch 需要 Claude Code v2.1.251 或更新版本。由於模型已經變更，它無法進行封鎖。Claude Code 會在以下任何變更後執行 PostModelSwitch hook： 當備援模型鏈中的模型負責某個回合時，Claude Code 不會執行 PostModelSwitch hook，因為該替代只持續一個回合，且不會變更工作階段的模型。 matcher 遵循與 PreModelSwitch 相同的規則：Claude Code 會將其與工作階段切換到的模型之標準名稱進行比對。 此範例會在工作階段的模型變更為任何 Opus 模型時加入指引：/model opus，然後詢問 Claude 它對目前模型有什麼指引。
PostModelSwitch 輸入
PostModelSwitch hook 會收到與 PreModelSwitch 相同的欄位，其中hook_event_name 設為 "PostModelSwitch"，並多了兩個 source 值："auto" 表示自動備援或 Claude Code 自行進行的其他變更，"resume" 表示您繼續工作階段時所還原的模型。
當 source 為 "auto" 時，requested_model 為 null。當 source 為 "resume" 時，它是 Claude Code 所還原的已儲存模型設定。
PostModelSwitch 決策控制
Claude Code 會在以 0 結束時取得您 hook 的純文字 stdout，或取得 JSON 輸出中的additionalContext，並在切換後隨下一個請求傳遞給 Claude。除了所有 hook 皆可使用的 JSON 輸出欄位之外，您還可以傳回：
如果在您傳送下一個提示詞後五秒內 hook 尚未完成，Claude Code 會在不含該輸出的情況下傳送該請求，並改為將其附加到再下一個請求。如果模型在下一個請求之前變更了數次，Claude Code 只會傳遞最後一次切換之目標模型的輸出。
SessionEnd
在 Claude Code 工作階段結束時執行。適用於清理工作、記錄工作階段 統計資料或儲存工作階段狀態。支援以 matcher 依結束原因進行篩選。 hook 輸入中的reason 欄位表示工作階段結束的原因：
SessionEnd 輸入
除了通用輸入欄位之外，SessionEnd hook 還會收到表示工作階段結束原因的reason 欄位。所有值請參閱上方的原因表。
systemMessage。
SessionEnd hook 的預設逾時為 1.5 秒。它適用於您結束、執行 /clear，或以互動式 /resume 切換工作階段時。您可以透過兩種方式給予 hook 更多時間：
- 個別 hook 的
timeout：在該 hook 的設定中設定timeout。整體預算會自動提高，以符合您設定檔中最高的個別 hooktimeout，最多 60 秒。如果您以此方式提高預算，沒有自己timeout的 hook 仍會保留預設值。在外掛程式提供的 hook 上設定的逾時不會提高預算。 CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS：以毫秒為單位設定此環境變數，以明確覆寫預算。您設定的值也會成為每個沒有自己timeout之 hook 的逾時。
CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS 只會提高整體預算，沒有自己 timeout 的 hook 仍會在 1.5 秒後被取消。
Elicitation
在 MCP 伺服器於工作進行中請求使用者輸入時執行。根據預設，Claude Code 會顯示互動式對話方塊讓使用者回應。hook 可以攔截此請求並以程式方式回應，完全略過對話方塊。 關於包含設定項目與指令碼的完整 hook，請參閱從指令碼回答表單請求。 matcher 欄位會與 MCP 伺服器名稱進行比對。Elicitation 輸入
除了通用輸入欄位之外，Elicitation hook 還會收到mcp_server_name、message，以及選用的 mode、url、elicitation_id 與 requested_schema 欄位。
表單模式的 elicitation，也就是最常見的情況：
Elicitation 輸出
Elicitation hook 可以代替使用者回答請求、拒絕或取消請求，或將其留給對話方塊處理。若要回答、拒絕或取消，請以 0 結束並印出含有action 的 hookSpecificOutput 物件。伺服器會收到您的答覆，且不會出現對話方塊。此表的每一列都顯示針對某個結果應傳回的內容，以及 MCP 伺服器會收到的內容：
此輸出會回答 Elicitation 輸入中所示的表單模式請求。
content 中的鍵是該請求之 requested_schema 中的屬性名稱：
decline，按下 Esc 則會傳送 cancel，因此請傳回您希望伺服器看到的那一個。
對於 URL 模式的請求，傳回 accept 的 hook 會略過對話方塊，因此 URL 永遠不會開啟。
無論您傳回哪個 action，Claude Code 都會捨棄 Elicitation hook JSON 輸出中的 reason、systemMessage 與 continue。
拒絕 elicitation 的其他方式
您的 hook 也可以透過以下方式拒絕。伺服器會收到與"action": "decline" 相同的 decline：
- 以代碼 2 結束：Claude Code 會忽略同一個 hook 所印出的
hookSpecificOutput - 印出頂層的
"decision": "block"：封鎖會覆寫同一輸出中的action
accept 或 cancel。
此指令碼會拒絕 URL 模式的請求，並將表單請求留給對話方塊處理：
reason。
從 v2.1.105 起直到 v2.1.284 修正為止，Claude Code 會忽略 Elicitation 與 ElicitationResult hook 的頂層 decision。
從指令碼回答表單請求
此範例會代替使用者回答一個反覆出現的問題。名為issue-tracker 的 MCP 伺服器會在表單中要求專案鍵，而 hook 會填入 DOCS。當 project_key 是表單唯一的欄位時，指令碼會接受。對於其他任何請求，它不會印出任何內容，因此會出現對話方塊。
- macOS/Linux
- Windows (PowerShell)
在您的設定檔中為此事件註冊命令 hook，並以伺服器名稱作為 matcher：將此指令碼儲存至專案中的
.claude/hooks/answer-project-key.sh，並以 chmod +x 設為可執行：claude --debug 啟動 Claude Code，並給 Claude 一項會讓伺服器要求專案鍵的工作。不會出現對話方塊，且偵錯日誌中會有一行以 Elicitation resolved by hook: {"action":"accept","content":{"project_key":"DOCS"}} 結尾。
ElicitationResult
在使用者回應 MCP elicitation 後執行。hook 可以在回應傳回 MCP 伺服器之前觀察、修改或封鎖該回應。 當 Elicitation hook 回答了請求時，Claude Code 會將該答覆傳送給伺服器，而不執行 ElicitationResult hook。 matcher 欄位會與 MCP 伺服器名稱進行比對。ElicitationResult 輸入
除了通用輸入欄位之外，ElicitationResult hook 還會收到mcp_server_name、action，以及選用的 mode、elicitation_id 與 content 欄位。
ElicitationResult 輸出
ElicitationResult hook 可以讓使用者的回應通過、變更其值，或封鎖它。若要變更或封鎖回應，請以 0 結束並印出含有action 的 hookSpecificOutput 物件。此表的每一列都顯示針對某個結果應傳回的內容，以及 MCP 伺服器會收到的內容：
此輸出會變更 ElicitationResult 輸入中所示的回應，使伺服器在使用者提交
alice 之處收到 alice@example.com：
content 會取代使用者的整個 content 物件，因此請包含您未變更的欄位。請一併傳回 action，因為 Claude Code 會忽略沒有 action 的 hookSpecificOutput。
ElicitationResult hook 在使用者拒絕或取消時也會執行，且您的 action 會取代使用者的。請在傳回 accept 之前，先確認輸入的 action 是 accept，否則您的 hook 會將被拒絕的請求變成已接受的請求。此指令碼會在使用者接受時進行相同的變更、保留其他欄位，否則不列印任何內容：
"decision": "block" 也會封鎖回應。拒絕 elicitation 的其他方式說明了當 hook 同時使用多種方式時哪一種會生效、使用者會看到什麼，以及哪些版本會忽略 decision。
無論您傳回哪個 action，Claude Code 都會捨棄 ElicitationResult hook JSON 輸出中的 reason、systemMessage 與 continue。
基於提示的 hooks
除了命令、HTTP 和 MCP tool hooks 外，Claude Code 還支援基於提示的 hooks（type: "prompt"），使用 LLM 評估是否允許或阻止操作，以及代理 hooks（type: "agent"），生成具有工具存取權限的代理驗證器。並非所有事件都支援每種 hook 類型。
支援所有五種 hook 類型（command、http、mcp_tool、prompt 和 agent）的事件：
PermissionDeniedPostToolBatchPostToolUsePostToolUseFailurePreToolUseStopSubagentStopTaskCompletedTaskCreatedTeammateIdleUserPromptExpansionUserPromptSubmit
PermissionRequest 支援 command、http、mcp_tool 和 prompt hooks，但不支援 agent hooks。如果您在此事件上配置代理 hook，Claude Code 會跳過它，權限流程保持不變。要從 hook 允許或拒絕，請從命令或 HTTP hook 返回決定物件。
支援 command、http 和 mcp_tool hooks 但不支援 prompt 或 agent 的事件：
ConfigChangeCwdChangedDirectoryAddedElicitationElicitationResultFileChangedInstructionsLoadedMessageDisplayNotificationPostCompactPostModelSwitchPreCompactPreModelSwitchSessionEndStopFailureSubagentStartWorktreeCreateWorktreeRemove
SessionStart 和 Setup 支援 command 和 mcp_tool hooks，而 MCP tool hook 欄位描述了它們的 mcp_tool hooks 何時執行。它們不支援 http、prompt 或 agent hooks。
基於提示的 hooks 如何工作
基於提示的 hooks 不執行 Bash 命令，而是：- 將 hook 輸入和您的提示發送到 Claude 模型，預設為 Claude Code 用於背景功能的模型
- LLM 以包含決定的結構化 JSON 回應
- Claude Code 自動處理決定
提示 hook 配置
將type 設定為 "prompt" 並提供 prompt 字串而不是 command。使用 $ARGUMENTS 佔位符將 hook 的 JSON 輸入資料注入到您的提示文字中。
在提示詞 hook 或 agent hook 中，您可以將 prompt 寫成關於要阻止或允許什麼的規則，例如「Block any Bash command that reads .env files」，或寫成必須成立的條件，例如「All unit tests pass」。
此 Stop hook 詢問 LLM 在允許 Claude 完成之前是否應該評估所有任務是否完成：
回應架構
LLM 必須以包含以下內容的 JSON 回應：ok: false 時發生的情況取決於事件：
Stop和SubagentStop：原因被反饋給 Claude 作為其下一個指令，轉換繼續，除非回應也設定impossible: true，在這種情況下 Claude Code 允許停止，轉換結束PreToolUse：工具呼叫被拒絕；預設情況下轉換結束，拒絕原因在聊天中顯示為警告行。設定continueOnBlock: true以改為將原因作為工具錯誤返回給 Claude，使其可以調整並繼續，相當於命令 hook 的permissionDecision: "deny"。在 v2.1.210 之前，拒絕原因被作為工具錯誤返回給 Claude，轉換繼續PostToolUse：預設情況下轉換結束，原因在聊天中顯示為警告行。設定continueOnBlock: true以將原因反饋給 Claude 並繼續轉換PostToolBatch、UserPromptSubmit和UserPromptExpansion：轉換結束，原因顯示為警告行。這些事件在decision: "block"上結束轉換，無論continue如何PostToolUseFailure和TaskCreated：原因作為工具錯誤返回給 Claude，轉換繼續，無論continueOnBlock如何TaskCompleted：當它因為任務在轉換期間被標記為完成而觸發時，原因作為工具錯誤返回給 Claude，轉換繼續，無論continueOnBlock如何。當它因為隊友停止而觸發時，它的行為類似TeammateIdle並預設停止隊友TeammateIdle：預設情況下隊友停止，原因顯示為警告行。設定continueOnBlock: true以將原因反饋給隊友並保持其工作狀態PermissionRequest：ok: false沒有效果。要從 hook 拒絕批准，請使用命令 hook返回hookSpecificOutput.decision.behavior: "deny"PermissionDenied：ok: false沒有效果，因為拒絕已經發生。此事件讀取的唯一輸出是hookSpecificOutput.retry，提示和代理 hooks 無法設定。它們在此事件上執行，但其輸出被丟棄。使用命令 hook返回retry
在停止前檢查多個條件
此Stop hook 使用詳細提示在允許 Claude 停止之前檢查三個條件。SubagentStop hooks 使用相同的格式來評估 subagent 是否應該停止。如果模型因為條件尚未滿足而返回 "ok": false，Claude 繼續工作，提供的原因作為其下一個指令：
基於代理的 hooks
基於代理的 hooks（type: "agent"）類似於基於提示的 hooks，但具有多輪工具存取。代理 hook 不是單一 LLM 呼叫，而是生成一個可以讀取檔案、搜尋程式碼和檢查程式碼庫以驗證條件的 subagent。代理 hooks 支援與基於提示的 hooks 相同的事件，除了 PermissionRequest。
代理 hooks 如何工作
當代理 hook 觸發時：- Claude Code 生成一個 subagent，使用您的提示和 hook 的 JSON 輸入
- Subagent 可以使用 Read、Grep 和 Glob 等工具進行調查
- 在最多 50 輪後，subagent 返回結構化的
{ "ok": true/false }決定 - Claude Code 允許該動作（如果
ok是true）。如果ok是false，Claude Code 會以與提示 hook 相同的方式處理阻止，該提示 hook 在該事件上具有continueOnBlock: true，如回應架構下所列
代理 hook 配置
將type 設定為 "agent" 並提供 prompt 字串，使用 $ARGUMENTS 作為 hook 輸入 JSON 的佔位符。配置欄位與提示 hooks 相同，除了代理 hooks 具有更長的預設逾時 60 秒，且沒有 continueOnBlock 欄位。
回應架構是 { "ok": true } 允許或 { "ok": false, "reason": "..." } 阻止。在 ok: false 時，Claude Code 會以處理提示 hook 且具有 continueOnBlock: true 的相同方式處理代理 hook；代理 hooks 沒有 continueOnBlock 欄位，且不支援提示 hook 的 impossible 欄位。
此 Stop hook 驗證所有單元測試通過，然後允許 Claude 完成：
在背景執行 hooks
預設情況下，hooks 會阻止 Claude 的執行，直到它們完成。對於長時間執行的任務，如部署、測試套件或外部 API 呼叫，設定"async": true 以在背景執行 hook，同時 Claude 繼續工作。非同步 hooks 無法阻止或控制 Claude 的行為：回應欄位，如 decision、permissionDecision 和 continue 沒有效果，因為它們會控制的操作已經完成。
配置非同步 hook
將"async": true 新增到命令 hook 的配置以在背景執行它而不阻止 Claude。此欄位僅在 type: "command" hooks 上可用。
此 hook 在每個 Write 工具呼叫後執行測試指令碼。Claude 立即繼續工作，同時 run-tests.sh 執行。當指令碼完成時，其輸出在下一個對話輪次上傳遞：
timeout。Claude Code 仍然會對使用 asyncRewake 執行的 hook 強制執行 timeout。
Claude Code 只在工作階段執行時傳遞非同步 hook 的結果：
- 在非互動模式中使用
-p旗標，Claude Code 會在清理時終止任何仍在執行的非同步 hook，並以cancelled結果完成它 - 如果你的 hook 工作必須超越
claude -p工作階段，請從它啟動一個完全分離的程序
非同步 hooks 如何執行
當非同步 hook 觸發時，Claude Code 啟動 hook 程序並立即繼續，而不等待它完成。Hook 在 stdin 上接收與同步 hook 相同的 JSON 輸入。 背景程序退出後，Claude Code 會在下一個對話輪次將 hook 的 JSON 回應中的additionalContext 和 systemMessage 欄位傳遞給 Claude。與同步 hook 的 systemMessage 不同，這兩個欄位都不會顯示給你。
將 JSON 回應單獨輸出至 stdout，或單獨列印在其自己的一行上：
- 單獨輸出至 stdout：當回應是 stdout 上唯一的文字時，它可以跨越多行，例如經過美化排版的
jq輸出。跨越多行需要 Claude Code v2.1.295 或更新版本。 - 單獨佔一行：當回應本身可容納於一行時，非同步 hook 可以將其他文字列印到 stdout，例如使用
jq -c。
systemMessage，而不是傳遞它。使用 --debug 執行以查看命名每個捨棄欄位的警告。
非同步 hook 完成通知預設被抑制。要查看它們，請使用 Ctrl+O 啟用詳細模式或使用 --verbose 啟動 Claude Code。
檔案變更後執行測試
此 hook 在 Claude 寫入檔案時在背景啟動測試套件，然後在測試完成時將結果報告回 Claude。將此指令碼儲存到專案中的.claude/hooks/run-tests-async.sh 並使用 chmod +x 使其可執行：
.claude/settings.json。async: true 旗標讓 Claude 在測試執行時繼續工作：
限制
非同步 hooks 與同步 hooks 相比有額外的限制：- Hook 輸出在下一個對話輪次上傳遞。如果工作階段閒置，回應會等待直到下一個使用者互動。例外：退出代碼為 2 的
asyncRewakehook 即使在工作階段閒置時也會立即喚醒 Claude。 - 每次執行都會建立一個單獨的背景程序。
安全考慮
免責聲明
工作區信任
Claude Code 在執行任何來自設定檔的 hook 之前會檢查工作區信任。什麼算作受信任取決於工作階段類型：- 互動式工作階段：Claude Code 會保留來自每個設定檔的 hooks，包括您自己的
~/.claude/settings.json，直到您接受該資料夾的工作區信任對話框，或接受其信任延伸到該資料夾的父目錄 -p或 SDK 工作階段：Claude Code 不會顯示對話框，並將該資料夾視為受信任，因此儲存庫.claude/settings.json中提交的 hooks 會在您從未信任過的資料夾中執行
claude -p 之前，如果您沒有編寫該儲存庫，請審查其 .claude/ 設定檔，使用 --bare 開始，或為該執行關閉 hooks，使用 --settings '{"disableAllHooks": true}'。專案子代理中的 Frontmatter hooks 遵循比設定檔 hooks 更嚴格的規則。在您信任資料夾之前執行的內容按工作階段類型列出每種儲存庫內容。
安全最佳實踐
編寫 hooks 時，請記住這些實踐：- 驗證和清理輸入：永遠不要盲目信任輸入資料
- 始終引用 shell 變數：使用
"$VAR"而不是$VAR - 阻止路徑遍歷：檢查檔案路徑中的
.. - 使用絕對路徑：為指令碼指定完整路徑。在 exec 形式中，使用
${CLAUDE_PROJECT_DIR}且路徑不需要引用。在 shell 形式中，將其包裝在雙引號中 - 跳過敏感檔案：避免
.env、.git/、金鑰等
Windows PowerShell 工具
在 Windows 上，您可以通過在命令 hook 上設定"shell": "powershell" 在 PowerShell 中執行個別 hooks。Claude Code 自動偵測 pwsh.exe（PowerShell 7 及更新版本的可執行檔），並回退到 powershell.exe（Windows PowerShell 5.1）。
${CLAUDE_PROJECT_DIR} 或 $env:CLAUDE_PROJECT_DIR。Claude Code 會在 PowerShell shell 形式命令中將 ${CLAUDE_PROJECT_DIR}、${CLAUDE_PLUGIN_ROOT} 和 ${CLAUDE_PLUGIN_DATA} 佔位符重寫為 PowerShell 的 ${env:NAME} 形式，無論 hook 是在 settings.json、外掛或 skill 中定義。PowerShell 會在解析後從匯出的環境中解析該值，因此佔位符在雙引號字串內有效，但在單引號字串內無效，因為 PowerShell 永遠不會在單引號字串中展開變數。
不要在 PowerShell hook 中寫入裸露的 $CLAUDE_PROJECT_DIR 拼寫。PowerShell 會將其解析為未定義的本機變數，並將其解析為 $null，這會導致指令碼路徑沒有其專案根目錄前綴。Claude Code 不會重寫該形式；它會在 debug log 中記錄警告。
下面的範例顯示了一個 settings.json hook，它使用 $env: 形式執行專案指令碼：
偵錯 hooks
Hook 執行詳細資訊被寫入偵錯日誌檔案。使用claude --debug-file <path> 啟動 Claude Code 以將日誌寫入已知位置，或執行 claude --debug 並在 ~/.claude/debug/<session-id>.txt 讀取日誌。--debug 標誌不列印到終端。
例如，在 Write 上的 PostToolUse hook，其命令列印 hook-ran 會產生如下項目：
Hooks: 行。在 Claude Code v2.1.296 或更新版本中，工具事件、UserPromptSubmit、SessionStart、Stop 及其他數個事件上的每個命令 hook 在完成時都會留下這樣一行，無論其輸出了什麼。該行會列出事件名稱，並以冒號連接 hook 所匹配的工具名稱或其他值，接著是以方括號括住的 hook 命令、其來源外掛（如有）、執行的結束方式以及所花費的時間，例如 Hooks: PostToolUse:Write [.claude/hooks/log-write.sh] finished with status 0 (31ms)。執行也可能以 timed out after <N>ms、cancelled、moved to the background 或 failed to start 結束。在某些事件上，例如 Notification、SessionEnd 和 PreCompact，命令 hook 會改為留下不含持續時間的 completed with status 行。
有關更細粒度的 hook 匹配詳細資訊，設定 CLAUDE_CODE_DEBUG_LOG_LEVEL=verbose 以查看額外的日誌行，例如 hook 匹配器計數和查詢匹配。
有關故障排除常見問題，如 hooks 不觸發、Stop hooks 持續阻擋或配置錯誤，請參閱指南中的 限制和故障排除。有關涵蓋 /context、/doctor 和設定優先順序的更廣泛診斷逐步解說，請參閱 偵錯您的設定。