在使用 -p 旗標的非互動模式中，只有當執行具有接收提示的權限主機（例如 Agent SDK 的 canUseTool 回呼）時，Claude Code 才會提供 AskUserQuestion 與 ExitPlanMode。這些工具需要使用者互動。回傳 permissionDecision: "allow" 並搭配 updatedInput 即可滿足此需求：hook 從 stdin 讀取工具的輸入，透過您自己的 UI 收集答案，並在 updatedInput 中回傳，讓工具在不提示的情況下執行。對於這些工具，只回傳 "allow" 是不夠的。對於 AskUserQuestion，請回傳原始的 questions 陣列，並加入一個 answers 物件，將每個問題的文字對應到所選的答案。

伺服器以 _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 執行只有在具有權限主機（例如您以 --permission-prompt-tool 傳入的 MCP 工具）時才會提供 AskUserQuestion，因此請以權限主機啟動執行。往返流程如下：

1. Claude 呼叫 AskUserQuestion。PreToolUse hook 觸發。
2. hook 回傳 permissionDecision: "defer"。工具不會執行。程序以 stop_reason: "tool_deferred" 結束，待處理的工具呼叫會保留在逐字稿中。
3. 呼叫端程序從 SDK 結果讀取 deferred_tool_use，在自己的 UI 中呈現問題，並等待答案。
4. 呼叫端程序以相同的權限主機執行 claude -p --resume <session-id>。同一個工具呼叫會再次觸發 PreToolUse。
5. hook 回傳 permissionDecision: "allow"，並在 updatedInput 中附上答案。工具執行，Claude 繼續。

deferred_tool_use 欄位攜帶工具的 id、name 與 input。input 是 Claude 為該工具呼叫產生的參數，在執行前擷取：

{
  "type": "result",
  "subtype": "success",
  "stop_reason": "tool_deferred",
  "session_id": "abc123",
  "deferred_tool_use": {
    "id": "toolu_01abc",
    "name": "AskUserQuestion",
    "input": { "questions": [{ "question": "Which framework?", "header": "Framework", "options": [{"label": "React"}, {"label": "Vue"}], "multiSelect": false }] }
  }
}

沒有逾時或重試次數限制。工作階段會保留在磁碟上直到您繼續它，但受 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 仍會包含在內，讓您能識別遺失的是哪個工具。

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 會像 PreToolUse hook 一樣接收 tool_name 與 tool_input 欄位，但不含 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 觸發。

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "permission_mode": "default",
  "hook_event_name": "PermissionRequest",
  "tool_name": "Bash",
  "tool_input": {
    "command": "rm -rf node_modules",
    "description": "Remove node_modules directory"
  },
  "permission_suggestions": [
    {
      "type": "addRules",
      "rules": [{ "toolName": "Bash", "ruleContent": "rm -rf node_modules" }],
      "behavior": "allow",
      "destination": "localSettings"
    }
  ]
}

PermissionRequest 決策控制

PermissionRequest hook 可以允許或拒絕權限請求。除了所有 hook 都可使用的 JSON 輸出欄位之外，您的 hook 指令碼還可以回傳包含下列事件專屬欄位的 decision 物件：

以退出碼 2 結束但沒有 decision 物件的 hook 不會改變權限流程，其 stderr 會被捨棄。只有 decision 物件能授予或拒絕請求。

{
  "hookSpecificOutput": {
    "hookEventName": "PermissionRequest",
    "decision": {
      "behavior": "allow",
      "updatedInput": {
        "command": "npm run lint"
      }
    }
  }
}

權限更新項目

updatedPermissions 輸出欄位與 permission_suggestions 輸入欄位都使用相同的項目物件陣列。每個項目都有一個決定其他欄位的 type，以及一個控制變更寫入位置的 destination。

每個項目上的 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 的 PostToolUse hook。

PostToolUse 輸入

PostToolUse hook 會在工具已成功執行後觸發。輸入同時包含 tool_input（傳送給工具的引數）與 tool_response（工具傳回的結果）。兩者的確切 schema 取決於工具。檔案工具的 tool_input 路徑格式與 PreToolUse 相同：一律為絕對路徑，並使用平台原生的分隔符號，因此在 Windows 上為反斜線。對於 MCP 工具，輸入也會帶有 mcp_server 物件。

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "permission_mode": "default",
  "hook_event_name": "PostToolUse",
  "tool_name": "Write",
  "tool_input": {
    "file_path": "/path/to/file.txt",
    "content": "file content"
  },
  "tool_response": {
    "filePath": "/path/to/file.txt",
    "type": "create"
  },
  "tool_use_id": "toolu_01ABC123...",
  "duration_ms": 12
}

PostToolUse 決策控制

PostToolUse hook 可以在工具執行後向 Claude 提供回饋。除了所有 hook 皆可使用的 JSON 輸出欄位之外，您的 hook 指令碼還可以傳回以下事件專屬欄位：

以下範例取代 Bash 呼叫的輸出。取代值符合 Bash 工具的輸出結構：

{
  "hookSpecificOutput": {
    "hookEventName": "PostToolUse",
    "additionalContext": "Additional information for Claude",
    "updatedToolOutput": {
      "stdout": "[redacted]",
      "stderr": "",
      "interrupted": false,
      "isImage": false
    }
  }
}

為自動模式分類器註記結果

傳回 classifierContext，即可將關於工具呼叫結果的簡短註記傳送給自動模式分類器，而非傳送給 Claude。分類器永遠不會收到工具結果本身，因此在它審查後續動作之前，此欄位是告知它某次呼叫傳回內容的官方支援方式。此欄位需要 Claude Code v2.1.236 或更新版本。

以下範例告訴分類器某個查詢的輸出來源：

{
  "hookSpecificOutput": {
    "hookEventName": "PostToolUse",
    "classifierContext": "This query ran against the staging database, not production."
  }
}

分類器對註記的重視程度，取決於您在何處設定該 hook：

• 在 Claude Code 中設定的 hook：對於來自設定檔、外掛、skill 與 agent frontmatter 的 hook，分類器會將註記視為未經驗證、由應用程式提供的上下文。註記永遠無法確立使用者意圖；若註記聲稱您核准或要求了某件事，分類器會以您在對話中的訊息查核該聲明
• 行程內 Agent SDK 回呼：當嵌入 Claude Code 的應用程式將 hook 註冊為 TypeScript SDK 回呼，並在即時工作階段中傳回註記時，分類器可能會將註記中轉述的使用者陳述視為使用者意圖。此類陳述可以滿足分類器原本會接受您傳送訊息來滿足的同意要求，但永遠無法解除您自己的訊息也無法解除的封鎖。工作階段恢復後，Claude Code 會將還原的註記視為未經驗證的上下文。當兩組來源的 hook 都為同一次呼叫加上註記時，分類器會將合併後的註記視為未經驗證

Claude Code 在傳遞註記時會套用以下限制：

• 長度：Claude Code 將單次工具呼叫的註記上限設為 2,000 個字元，超出部分會被截斷。此上限由回應該次呼叫的所有 hook 共用
• 僅限同步回應：對於在背景執行的 hook，Claude Code 會忽略其回應中的此欄位，因為該回應會在 Claude Code 記錄工具結果之後才抵達
• 分類器未記錄的呼叫：分類器的逐字稿會省略唯讀查詢，例如檔案讀取與搜尋。附加在這類呼叫上的註記會被 Claude Code 捨棄
• 與改寫的互動：當註記描述的是您正以 updatedToolOutput 取代的輸出時，請在同一個 hook 回應中同時傳回這兩個欄位。若該改寫遭到拒絕，或被另一個 hook 的改寫取代，Claude Code 會捨棄該註記。若您傳回註記但未改寫，即使另一個 hook 改寫了輸出，Claude Code 仍會傳遞您的註記

PostToolUseFailure

當已開始執行的工具失敗時執行：工具擲出錯誤，或 MCP 工具傳回錯誤結果。可用來記錄失敗、傳送警示，或向 Claude 提供修正回饋。

依工具名稱比對，可用值與 PreToolUse 相同。

PostToolUseFailure 輸入

PostToolUseFailure hook 會收到與 PostToolUse 相同的 tool_name 與 tool_input 欄位，以及作為頂層欄位的錯誤資訊。對於 MCP 工具，它們也會收到 mcp_server 物件。例如，失敗的 npm test 命令可能會傳遞：

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "permission_mode": "default",
  "hook_event_name": "PostToolUseFailure",
  "tool_name": "Bash",
  "tool_input": {
    "command": "npm test",
    "description": "Run test suite"
  },
  "tool_use_id": "toolu_01ABC123...",
  "error": "Exit code 1\nError: Cannot find module 'express'",
  "is_interrupt": false,
  "duration_ms": 4187
}

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 指令碼還可以傳回以下事件專屬欄位：

{
  "hookSpecificOutput": {
    "hookEventName": "PostToolUseFailure",
    "additionalContext": "Additional information about the failure for Claude"
  }
}

PostToolBatch

在批次中的每個工具呼叫都已解決後執行一次，時間點在 Claude Code 將下一個請求傳送給模型之前。PostToolUse 會針對每個工具觸發一次，這表示當 Claude 進行平行工具呼叫時，它會同時觸發。PostToolBatch 則會帶著完整批次恰好觸發一次，因此適合用來注入取決於已執行工具集合、而非任何單一工具的上下文。此事件沒有 matcher。

PostToolBatch 輸入

除了通用輸入欄位之外，PostToolBatch hook 還會收到 tool_calls，這是描述批次中每個工具呼叫的陣列：

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "permission_mode": "default",
  "hook_event_name": "PostToolBatch",
  "tool_calls": [
    {
      "tool_name": "Read",
      "tool_input": {"file_path": "/.../ledger/accounts.py"},
      "tool_use_id": "toolu_01...",
      "tool_response": "1\tfrom __future__ import annotations\n2\t..."
    },
    {
      "tool_name": "Read",
      "tool_input": {"file_path": "/.../ledger/transactions.py"},
      "tool_use_id": "toolu_02...",
      "tool_response": "1\tfrom __future__ import annotations\n2\t..."
    }
  ]
}

tool_response 包含與模型在對應 tool_result 區塊中收到的相同內容。其值為序列化字串或內容區塊陣列，與工具輸出時完全相同。對於 Read，這表示是帶有行號前綴的文字，而非原始檔案內容。回應可能很大，因此請只解析您需要的欄位。

PostToolBatch 決策控制

PostToolBatch hook 可以為 Claude 注入上下文。除了所有 hook 皆可使用的 JSON 輸出欄位之外，您的 hook 指令碼還可以傳回以下事件專屬欄位：

{
  "hookSpecificOutput": {
    "hookEventName": "PostToolBatch",
    "additionalContext": "These files are part of the ledger module. Run pytest before marking the task complete."
  }
}

傳回 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 物件。

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "permission_mode": "auto",
  "hook_event_name": "PermissionDenied",
  "tool_name": "Bash",
  "tool_input": {
    "command": "rm -rf /tmp/build",
    "description": "Clean build directory"
  },
  "tool_use_id": "toolu_01ABC123...",
  "reason": "[Irreversible Local Destruction]"
}

PermissionDenied 決策控制

PermissionDenied hook 可以告知模型它可以重試遭拒的工具呼叫。傳回將 hookSpecificOutput.retry 設為 true 的 JSON 物件：

{
  "hookSpecificOutput": {
    "hookEventName": "PermissionDenied",
    "retry": true
  }
}

當 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 或更新版本。

在 Claude Code 將權限請求傳送給 Agent SDK 的 canUseTool 回呼的工作階段中（Claude Desktop 與 VS Code 擴充功能即以此方式託管 Claude Code），Claude Code 對 permission_prompt 的計時方式有所不同：

• 預期 permission_prompt 會在 Claude 要求權限約六秒後出現。Claude Code 不會因您輸入而延後它。
• 如果您或 PermissionRequest hook 較早回應，Claude Code 不會執行 permission_prompt。
• 將 CLAUDE_CODE_DISABLE_PERMISSION_PROMPT_NOTIFY_HOOKS 設為 1，即可在這些工作階段中關閉 permission_prompt。

在 v2.1.233 之前，permission_prompt 不會在這些工作階段中觸發。

使用不同的 matcher，即可依通知類型執行不同的處理常式。此設定會在 Claude 需要權限核准時觸發權限專用的警示指令碼，並在 Claude 閒置時觸發另一個通知：

{
  "hooks": {
    "Notification": [
      {
        "matcher": "permission_prompt",
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/permission-alert.sh"
          }
        ]
      },
      {
        "matcher": "idle_prompt",
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/idle-notification.sh"
          }
        ]
      }
    ]
  }
}

Notification 輸入

除了通用輸入欄位之外，Notification hook 還會收到含有通知文字的 message、選用的 title，以及指出觸發類型的 notification_type。

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "Notification",
  "message": "Claude needs your permission",
  "title": "Permission needed",
  "notification_type": "permission_prompt"
}

Notification hook 無法封鎖或修改通知。Claude Code 會捨棄其 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。

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "SubagentStart",
  "agent_id": "agent-abc123",
  "agent_type": "Explore"
}

SubagentStart hook 無法封鎖 subagent 的建立，但可以將上下文注入 subagent。除了所有 hook 皆可使用的 JSON 輸出欄位之外，您還可以傳回：

{
  "hookSpecificOutput": {
    "hookEventName": "SubagentStart",
    "additionalContext": "Follow security guidelines for this task"
  }
}

當 hook 針對同一個 subagent 再次執行時，Claude Code 只會在 subagent 的上下文中尚未保有先前執行所注入的副本時，才注入傳回的上下文。啟動時注入的副本會保留在原處，使 subagent 的提示快取維持完整。在自動壓縮捨棄該副本後，Claude Code 會再次注入下一次執行的上下文。

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 則是 subagent 自己的逐字稿，儲存在巢狀的 subagents/ 資料夾中。last_assistant_message 欄位包含 subagent 最終回應的文字內容，因此 hook 無需解析逐字稿檔案即可存取它。

並非每個 SubagentStop 事件都來自 Claude 產生的 subagent。Claude Code 也會為其部分功能執行內部 agent，例如提示詞建議與 /btw 旁支問題，這些 agent 完成時同樣會觸發 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。

{
  "session_id": "abc123",
  "transcript_path": "~/.claude/projects/.../abc123.jsonl",
  "cwd": "/Users/...",
  "permission_mode": "default",
  "hook_event_name": "SubagentStop",
  "stop_hook_active": false,
  "agent_id": "def456",
  "agent_type": "Explore",
  "agent_transcript_path": "~/.claude/projects/.../abc123/subagents/agent-def456.jsonl",
  "last_assistant_message": "Analysis complete. Found 3 potential issues...",
  "background_tasks": [],
  "session_crons": []
}

SubagentStop hook 使用與 Stop hook 相同的決策控制格式，包括將 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。

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "TaskCreated",
  "task_id": "task-001",
  "task_subject": "Implement user authentication",
  "task_description": "Add login and signup endpoints",
  "teammate_name": "implementer",
  "team_name": "session-a1b2c3d4"
}

TaskCreated 決策控制

TaskCreated hook 可以透過兩種方式封鎖建立。無論哪種方式，Claude Code 都會刪除該任務，並將您的訊息作為工具錯誤傳回給 Claude。Claude Code 會忽略此事件的 continue: false，Claude 會繼續工作。

• 退出碼 2：Claude Code 將 stderr 文字作為訊息傳回。
• JSON {"decision": "block", "reason": "..."}：Claude Code 將 reason 作為訊息傳回。

此範例會封鎖主旨不符合所需格式的任務：

#!/bin/bash
INPUT=$(cat)
TASK_SUBJECT=$(echo "$INPUT" | jq -r '.task_subject')

if [[ ! "$TASK_SUBJECT" =~ ^\[TICKET-[0-9]+\] ]]; then
  echo "Task subject must start with a ticket number, e.g. '[TICKET-123] Add feature'" >&2
  exit 2
fi

exit 0

TaskCompleted

在任務即將被標記為已完成時執行。這會在兩種情況下觸發：任何 agent 透過 TaskUpdate 工具明確將任務標記為已完成時，或 agent team 隊員在仍有進行中任務的情況下結束其回合時。可用來在任務關閉前強制執行完成條件，例如通過測試或 lint 檢查。

TaskCompleted hook 不支援 matcher，每次發生時都會觸發。

TaskCompleted 輸入

除了通用輸入欄位之外，TaskCompleted hook 還會收到 task_id、task_subject，以及選用的 task_description、teammate_name 與 team_name。

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "permission_mode": "default",
  "hook_event_name": "TaskCompleted",
  "task_id": "task-001",
  "task_subject": "Implement user authentication",
  "task_description": "Add login and signup endpoints",
  "teammate_name": "implementer",
  "team_name": "session-a1b2c3d4"
}

TaskCompleted 決策控制

TaskCompleted hook 支援兩種控制任務完成的方式：

• 退出碼 2：任務不會被標記為已完成，stderr 訊息會作為回饋傳回給模型。
• JSON {"continue": false, "stopReason": "..."}：當事件是由隊員結束其回合所觸發時，會完全停止該隊員，與 Stop hook 的行為一致。stopReason 會顯示給使用者。當事件是由 TaskUpdate 工具觸發時，Claude Code 會忽略 continue: false；退出碼 2 仍會封鎖完成。

此範例會執行測試，並在測試失敗時封鎖任務完成：

#!/bin/bash
INPUT=$(cat)
TASK_SUBJECT=$(echo "$INPUT" | jq -r '.task_subject')

# Run the test suite
if ! npm test 2>&1; then
  echo "Tests not passing. Fix failing tests before completing: $TASK_SUBJECT" >&2
  exit 2
fi

exit 0

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_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 輸入：

{
  "session_id": "abc123",
  "transcript_path": "~/.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "permission_mode": "default",
  "hook_event_name": "Stop",
  "stop_hook_active": true,
  "last_assistant_message": "I've completed the refactoring. Here's a summary...",
  "background_tasks": [
    {
      "id": "task-001",
      "type": "shell",
      "status": "running",
      "description": "tail logs",
      "command": "tail -f /var/log/syslog"
    }
  ],
  "session_crons": [
    {
      "id": "cron-001",
      "schedule": "0 9 * * 1-5",
      "recurring": true,
      "prompt": "check the build"
    }
  ]
}

Stop 決策控制

Stop 與 SubagentStop hook 可以控制 Claude 是否繼續。除了所有 hook 皆可使用的 JSON 輸出欄位之外，您的 hook 指令碼還可以傳回以下事件專屬欄位：

以退出碼 2 封鎖的 hook，其處理方式與 reason 相同：Claude 會收到 stderr 訊息，作為它應繼續的原因說明。

{
  "decision": "block",
  "reason": "Must be provided when Claude is blocked from stopping"
}

當 hook 依設計運作並為 Claude 提供指引時（例如「完成前請執行測試套件」），請使用 additionalContext。它會透過與 decision: "block" 相同的迴圈保護機制讓對話繼續，即 stop_hook_active 輸入與連續 8 次繼續的上限，但逐字稿會將其標示為 Stop hook feedback，且不會顯示 hook 錯誤通知：

{
  "hookSpecificOutput": {
    "hookEventName": "Stop",
    "additionalContext": "Please run the test suite before finishing"
  }
}

StopFailure

當回合因 API 錯誤而結束時，取代 Stop 執行。除了 terminalSequence 之外，Claude Code 會忽略此 hook 的輸出與退出碼。當 Claude 因速率限制、身分驗證問題或其他 API 錯誤而無法完成回應時，可用來記錄失敗、傳送警示或採取復原動作。

StopFailure 輸入

除了通用輸入欄位之外，StopFailure hook 還會收到 error、選用的 error_details 與選用的 last_assistant_message。error 欄位識別錯誤類型，並用於 matcher 篩選。

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "StopFailure",
  "error": "rate_limit",
  "error_details": "429 Too Many Requests",
  "last_assistant_message": "API Error: Rate limit reached"
}

StopFailure hook 沒有決策控制。它們僅用於通知與記錄日誌。

TeammateIdle

當 agent team 隊員在結束其回合後即將進入閒置狀態時執行。可用來在隊員停止工作前強制執行品質關卡，例如要求通過 lint 檢查或確認輸出檔案存在。

TeammateIdle hook 不支援 matcher，每次發生時都會觸發。

TeammateIdle 輸入

除了通用輸入欄位之外，TeammateIdle hook 還會收到 teammate_name 與 team_name。

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "permission_mode": "default",
  "hook_event_name": "TeammateIdle",
  "teammate_name": "researcher",
  "team_name": "session-a1b2c3d4"
}

TeammateIdle 決策控制

TeammateIdle hook 支援兩種控制隊員行為的方式：

• 退出碼 2：隊員會收到 stderr 訊息作為回饋，並繼續工作而不進入閒置狀態。
• JSON {"continue": false, "stopReason": "..."}：完全停止該隊員，與 Stop hook 的行為一致。stopReason 會顯示給使用者。

此範例會在允許隊員進入閒置狀態前，檢查建置產物是否存在：

#!/bin/bash

if [ ! -f "./dist/output.js" ]; then
  echo "Build artifact missing. Run the build before stopping." >&2
  exit 2
fi

exit 0

ConfigChange

在工作階段期間設定檔變更時執行。可用來稽核設定變更、強制執行安全政策，或封鎖對設定檔未經授權的修改。

當設定檔、受管政策檔案或 skill 檔案變更時，Claude Code 會執行 ConfigChange hook。對於受管政策，只有在 managed-settings.json 或 managed-settings.d/ 中的檔案變更時才會執行。套用伺服器管理設定以及 macOS 受管偏好設定或 Windows 登錄政策的變更時，不會執行這些 hook。在啟用 wslInheritsWindowsSettings 的 WSL 上，它在政策輪詢時套用已變更的 Windows 端受管設定檔，同樣不會執行這些 hook。

matcher 依設定來源篩選：

此範例會記錄所有設定變更以供安全稽核：

{
  "hooks": {
    "ConfigChange": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/audit-config-change.sh",
            "args": []
          }
        ]
      }
    ]
  }
}

ConfigChange 輸入

除了通用輸入欄位之外，ConfigChange hook 還會收到 source 與選用的 file_path。source 欄位指出哪種設定類型發生變更，file_path 則提供被修改之特定檔案的路徑。

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "ConfigChange",
  "source": "project_settings",
  "file_path": "/Users/.../my-project/.claude/settings.json"
}

ConfigChange 決策控制

ConfigChange hook 可以封鎖設定變更使其不生效。使用退出碼 2 或 JSON decision 即可阻止變更。遭封鎖時，新設定不會套用至正在執行的工作階段。

{
  "decision": "block",
  "reason": "Configuration changes to project settings require admin approval"
}

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。

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../transcript.jsonl",
  "cwd": "/Users/my-project/src",
  "hook_event_name": "CwdChanged",
  "old_cwd": "/Users/my-project",
  "new_cwd": "/Users/my-project/src"
}

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 分頁中新增目錄
• 您新增的目錄已是工作目錄或位於某個工作目錄內

Claude Code 會在重新整理沙箱與權限狀態後觸發 DirectoryAdded，因此當您的 hook 執行時，沙箱化的工具已能看到新目錄。hook 命令本身則在沙箱外執行。

Claude Code 不會等待 hook：新增會立即完成，hook 則在背景執行，使用 600 秒的預設逾時。

matcher 依目錄的新增方式篩選：

DirectoryAdded 輸入

除了通用輸入欄位之外，DirectoryAdded hook 還會收到 directory 與 source。

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../transcript.jsonl",
  "cwd": "/Users/my-project",
  "hook_event_name": "DirectoryAdded",
  "directory": "/Users/my-other-repo",
  "source": "slash_command"
}

DirectoryAdded hook 沒有決策控制。它們無法封鎖新增，因為 hook 執行時新增已經完成。Claude Code 會捨棄其 JSON 輸出中的 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 群組。

此範例會在任何變更後正規化 data.csv 的行尾，包括 Bash 命令或外部指令碼改寫該檔案的情況：

{
  "hooks": {
    "FileChanged": [
      {
        "matcher": "data.csv",
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/normalize-line-endings.sh"
          }
        ]
      }
    ]
  }
}

hook 會從 stdin 上 JSON 輸入的 file_path 欄位讀取變更檔案的絕對路徑。其 grep 防護條件檢查的正是 perl 要移除的內容，也就是行尾的 CR，因此正規化之後的那次執行會直接結束而不動到檔案。較寬鬆的防護條件會造成無限迴圈，因為即使沒有替換任何內容，perl -i 仍會改寫檔案，而 Claude Code 會在每次改寫後再次執行 hook。請將此指令碼儲存於 /path/to/normalize-line-endings.sh 並設為可執行：

#!/bin/bash
FILE=$(jq -r .file_path)
if grep -q $'\r$' "$FILE"; then
  perl -pi -e 's/\r$//' "$FILE"
fi

若要確認 hook 正常運作，請要求 Claude 以 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。

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../transcript.jsonl",
  "cwd": "/Users/my-project",
  "hook_event_name": "FileChanged",
  "file_path": "/Users/my-project/.envrc",
  "event": "change"
}

FileChanged 輸出

除了所有 hook 皆可使用的 JSON 輸出欄位之外，FileChanged hook 還可以傳回 watchPaths，以動態更新要監看的檔案路徑：

FileChanged hook 沒有決策控制。它們無法阻止檔案變更發生。

Claude Code 會從其 JSON 輸出讀取 watchPaths 與 systemMessage，並捨棄 continue。在互動式工作階段中，它會將 systemMessage 顯示為簡短的終端機通知。該訊息不會傳到 SDK 訊息串流。

WorktreeCreate

在建立 worktree 時執行，無論是來自 claude --worktree、來自使用 isolation: "worktree" 的 subagent，或是為 Claude Code 隔離在其自身 worktree 中的背景工作階段。依預設，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 替換為您自己的：

{
  "hooks": {
    "WorktreeCreate": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'NAME=$(jq -r .name); DIR=\"$HOME/.claude/worktrees/$NAME\"; svn checkout https://svn.example.com/repo/trunk \"$DIR\" >&2 && echo \"$DIR\"'"
          }
        ]
      }
    ]
  }
}

hook 會從 stdin 上的 JSON 輸入讀取 worktree 的 name，將全新副本簽出到新目錄，並印出目錄路徑。最後一行的 echo 就是 Claude Code 讀取為 worktree 路徑的內容。請將其他任何輸出重新導向至 stderr，以免干擾路徑。

WorktreeCreate 輸入

除了通用輸入欄位之外，WorktreeCreate hook 還會收到 name 欄位。這是新 worktree 的 slug 識別碼，由使用者指定或自動產生，例如 bold-oak-a3f2。

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "WorktreeCreate",
  "name": "feature-auth"
}

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" } }。

如果 hook 失敗或未產生路徑，worktree 建立將失敗並顯示錯誤。

Claude Code 會以 hook 執行時所在的目錄解析相對路徑，並摺疊其中的任何 . 或 .. 區段。如果產生的路徑不是 Claude Code 可以進入的目錄，工作階段會印出指明該路徑的錯誤，並以代碼 1 結束。

Claude Code 會拒絕包含 . 或 .. 區段的絕對路徑，以及任何經過儲存庫根目錄下方符號連結的路徑，因為提交至儲存庫的符號連結可能會將 worktree 重新導向至儲存庫之外。錯誤會指明被拒絕的元件。請回傳不經過儲存庫內符號連結的正規化路徑。在 v2.1.216 之前，worktree 建立會直接採用 hook 的路徑，不進行此項檢查。

WorktreeRemove

在移除 worktree 時執行。這是 WorktreeCreate 對應的清理事件。此事件會在以下情況觸發：

• 您結束 --worktree 工作階段並選擇移除它
• 具有 isolation: "worktree" 的 subagent 完成
• 您刪除一個其 worktree 由 hook 建立的背景工作階段

對於基於 git 的 worktree，Claude Code 會透過 git worktree remove 自動處理清理。如果您設定了 WorktreeCreate hook，請搭配 WorktreeRemove hook 來控制其所建立 worktree 的清理：

• 沒有 WorktreeRemove hook：當您結束 --worktree 工作階段並選擇移除時，Claude Code 會改用 git worktree remove --force 處理您的 WorktreeCreate hook 回傳的路徑，因此 git 能識別的 worktree 會被移除。git 無法識別的 worktree，例如您的 hook 以非 git 版本控制系統建立的 worktree，會保留在磁碟上。關於刪除背景工作階段時如何處理 hook 建立的 worktree，請參閱 agent view 的刪除規則。
• Hook 以 0 結束：該 worktree 視為已移除。Claude Code 不會從 hook 讀取其他任何內容，因此請確保您的 hook 已刪除該目錄。
• Hook 以非零結束：如果 worktree_path 處的目錄在之後仍然存在，移除即失敗，且 worktree 會保留在磁碟上，不會改用 git。在以非零結束之前已刪除目錄的 hook 視為已移除。關於失敗的回報方式，請參閱 WorktreeRemove 輸入。

Claude Code 絕不會刪除屬於 hook 建立之 worktree 的分支，因為它只知道您的 WorktreeCreate hook 回傳的路徑。如果您的 WorktreeCreate hook 建立了分支，請在 WorktreeRemove hook 中將其刪除。

Claude Code 會捨棄 WorktreeRemove hook 的 JSON 輸出欄位，例如 systemMessage 和 continue。

對於背景工作階段的刪除，Claude Code 會在執行 hook 之前驗證所儲存的 worktree 路徑，並拒絕本身為符號連結或經過儲存庫根目錄下方符號連結的路徑。只有當您在 agent view 中確認刪除時，hook 才會針對仍含有檔案的 worktree 執行；對於這類 worktree，claude rm 則會保留工作階段和 worktree。在 v2.1.216 之前，hook 會在未經這些檢查的情況下針對儲存的路徑執行。

Claude Code 會將 WorktreeCreate 回傳的路徑作為 hook 輸入中的 worktree_path 傳入。以下範例讀取該路徑並移除目錄：

{
  "hooks": {
    "WorktreeRemove": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'jq -r .worktree_path | xargs rm -rf'"
          }
        ]
      }
    ]
  }
}

WorktreeRemove 輸入

除了通用輸入欄位之外，WorktreeRemove hook 還會收到 worktree_path 欄位，即要移除之 worktree 的絕對路徑。

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "WorktreeRemove",
  "worktree_path": "/Users/.../my-project/.claude/worktrees/feature-auth"
}

WorktreeRemove hook 的退出碼決定結果。當 hook 以非零結束，且 worktree_path 處的目錄在之後仍然存在時，移除即失敗：

• worktree 會保留在磁碟上，hook 的命令和 stderr 會寫入偵錯日誌。
• 如果您正在刪除背景工作階段，該工作階段也會保留。agent view 中的拒絕訊息會回報 hook 的結束方式（例如 exited 1）、引用其 stderr 的開頭，並說明再次刪除該工作階段是否仍會移除該目錄。

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。

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "PreCompact",
  "trigger": "manual",
  "custom_instructions": null
}

PostCompact

在 Claude Code 完成壓縮操作之後執行。使用此事件來回應新的壓縮狀態，例如記錄產生的摘要或更新外部狀態。Claude Code 會捨棄 PostCompact hook 的 systemMessage 和 continue 欄位。

適用與 PreCompact 相同的 matcher 值：

PostCompact 輸入

除了通用輸入欄位之外，PostCompact hook 還會收到 trigger 和 compact_summary。compact_summary 欄位包含壓縮操作所產生的對話摘要。

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "PostCompact",
  "trigger": "manual",
  "compact_summary": "Summary of the compacted conversation..."
}

PostCompact hook 沒有決策控制。它們無法影響壓縮結果，但可以執行後續工作。

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 請求中的模型變更

對於 Claude Code 自行進行的切換，例如自動模型備援或在您恢復工作階段時還原模型，Claude Code 不會執行 PreModelSwitch hook。這些變更只會觸發 PostModelSwitch。

Claude Code 會將 matcher 與工作階段要切換到的模型的正式名稱進行比對，並忽略任何 [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，並允許任何其他目標通過：

{
"hooks": {
"PreModelSwitch": [
{
"matcher": "claude-opus-4-6",
"hooks": [
{
"type": "command",
"command": "jq -e '.to_model | test(\"opus-4-6\")' > /dev/null && { echo 'Opus 4.6 is retired for this project. Use a newer model.' >&2; exit 2; }; exit 0"
}
]
}
]
}
}

{
"hooks": {
"PreModelSwitch": [
{
"matcher": "claude-opus-4-6",
"hooks": [
{
"type": "command",
"command": "powershell.exe",
"args": [
"-NoProfile",
"-ExecutionPolicy",
"Bypass",
"-File",
"${CLAUDE_PROJECT_DIR}/.claude/hooks/block-opus-46.ps1"
]
}
]
}
]
}
}

$hookInput = [Console]::In.ReadToEnd() | ConvertFrom-Json
if ($hookInput.to_model -match 'opus-4-6') {
[Console]::Error.WriteLine('Opus 4.6 is retired for this project. Use a newer model.')
exit 2
}
exit 0

若要確認 hook 正常運作，請在執行其他模型的工作階段中執行 /model claude-opus-4-6。Claude Code 會保留目前的模型，並回報 PreModelSwitch hook 封鎖了切換，並以您的訊息作為原因。

PreModelSwitch 輸入

除了通用輸入欄位之外，PreModelSwitch hook 還會收到下表中的欄位。最後五個欄位描述將對話重新傳送至新模型的成本，讓 hook 能在切換發生之前顯示該數字。

以下範例顯示在執行 Sonnet 5 的工作階段中執行 /model opus 時的輸入：

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "PreModelSwitch",
  "from_model": "claude-sonnet-5",
  "to_model": "claude-opus-5",
  "requested_model": "opus",
  "source": "command",
  "context_tokens": 182340,
  "prompt_cache_warm": true,
  "cache_ttl": "5m",
  "estimated_cache_write_usd": 1.1396,
  "pricing": "catalog"
}

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 數：

{
  "hookSpecificOutput": {
    "hookEventName": "PreModelSwitch",
    "permissionDecision": "ask",
    "permissionDecisionReason": "Switching now re-sends about 180k tokens to the new model. Continue?"
  }
}

當多個 PreModelSwitch hook 回傳不同的決策時，優先順序為 deny > ask > allow。

無論決策為何，Claude Code 都會向使用者顯示您的 hook 回傳的任何 systemMessage，因此成本回報 hook 可以回傳 {"systemMessage": "..."} 並以 0 結束。

在逾時前未回應的 PreModelSwitch hook 會封鎖切換。相較之下，在 PreToolUse 上，逾時的命令 hook 會讓工具呼叫繼續進行。此事件的預設逾時為 30 秒。PreModelSwitch 只執行 command、http 和 mcp_tool hook，因此 prompt 和 agent 的預設值不適用。

以 0 或 2 以外的代碼結束且未印出 JSON 決策的 hook 不會封鎖：Claude Code 會顯示其 stderr 並套用切換，如其他退出碼中所述。

PostModelSwitch

在工作階段的模型變更之後執行。使用它來為 Claude 提供特定於模型的指引，而無需編輯每個 CLAUDE.md，例如適用於特定模型的全組織指令。

PostModelSwitch 需要 Claude Code v2.1.251 或更新版本。它無法封鎖，因為模型已經變更。Claude Code 會在以下任何變更之後執行 PostModelSwitch hook：

• 您或用戶端所請求的切換
• 自動模型備援，會變更工作階段的模型
• 諸如 opusplan 之類的設定進入或離開 plan mode
• Claude Code 在您恢復工作階段時還原模型

當備援模型鏈中的模型服務某個回合時，Claude Code 不會執行 PostModelSwitch hook，因為該替換只持續一個回合，且不會變更工作階段的模型。

matcher 遵循與 PreModelSwitch 相同的規則：Claude Code 會將其與工作階段所切換到的模型的正式名稱進行比對。

以下範例會在工作階段的模型變更為任何 Opus 模型時新增指引：

{
  "hooks": {
    "PostModelSwitch": [
      {
        "matcher": ".*opus.*",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'On Opus, delegate implementation work to subagents and keep this conversation for planning and review.'"
          }
        ]
      }
    ]
  }
}

若要確認 hook 正常運作，請從執行其他模型的工作階段切換到 Opus 模型，例如在 Sonnet 工作階段中執行 /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 欄位。所有值請參閱上方的原因表格。

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "SessionEnd",
  "reason": "other"
}

SessionEnd hook 沒有決策控制。它們無法封鎖工作階段終止，但可以執行清理工作。Claude Code 會捨棄它們的 JSON 輸出欄位，例如 systemMessage。

SessionEnd hook 的預設逾時為 1.5 秒。此逾時適用於您結束、執行 /clear 或透過互動式 /resume 切換工作階段時。您可以透過兩種方式給予 hook 更多時間：

• 個別 hook 的 timeout：在該 hook 的設定中設定 timeout。整體預算會自動提高，以符合您設定檔中最高的個別 hook timeout，上限為 60 秒。如果您以這種方式提高預算，沒有自己 timeout 的 hook 仍會保留預設值。在外掛程式提供的 hook 上設定的逾時不會提高預算。
• CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS：以毫秒為單位設定此環境變數，以明確覆寫預算。您設定的值也會成為每個沒有自己 timeout 之 hook 的逾時。

以下範例將預算設定為 5 秒：

CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS=5000 claude

在 v2.1.268 之前，CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS 只會提高整體預算，沒有自己 timeout 的 hook 仍會在 1.5 秒後被取消。

Elicitation

在 MCP 伺服器於工作進行中請求使用者輸入時執行。根據預設，Claude Code 會顯示互動式對話方塊供使用者回應。hook 可以攔截此請求並以程式化方式回應，完全略過對話方塊。

matcher 欄位會與 MCP 伺服器名稱進行比對。

Elicitation 輸入

除了通用輸入欄位之外，Elicitation hook 還會收到 mcp_server_name、message，以及選用的 mode、url、elicitation_id 和 requested_schema 欄位。

對於表單模式的 elicitation（最常見的情況）：

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "Elicitation",
  "mcp_server_name": "my-mcp-server",
  "message": "Please provide your credentials",
  "mode": "form",
  "requested_schema": {
    "type": "object",
    "properties": {
      "username": { "type": "string", "title": "Username" }
    }
  }
}

對於 URL 模式的 elicitation，用於基於瀏覽器的身分驗證：

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "Elicitation",
  "mcp_server_name": "my-mcp-server",
  "message": "Please authenticate",
  "mode": "url",
  "url": "https://auth.example.com/login"
}

Elicitation 輸出

若要在不顯示對話方塊的情況下以程式化方式回應，請回傳含有 hookSpecificOutput 的 JSON 物件：

{
  "hookSpecificOutput": {
    "hookEventName": "Elicitation",
    "action": "accept",
    "content": {
      "username": "alice"
    }
  }
}

退出碼 2 會拒絕 elicitation。Claude Code 不會在任何地方顯示您的 stderr 訊息。

Claude Code 會依據 Elicitation hook JSON 輸出中的 hookSpecificOutput 採取行動，並捨棄 systemMessage 和 continue。

ElicitationResult

在使用者回應 MCP elicitation 之後執行。hook 可以在回應傳回 MCP 伺服器之前觀察、修改或封鎖該回應。

matcher 欄位會與 MCP 伺服器名稱進行比對。

ElicitationResult 輸入

除了通用輸入欄位之外，ElicitationResult hook 還會收到 mcp_server_name、action，以及選用的 mode、elicitation_id 和 content 欄位。

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "ElicitationResult",
  "mcp_server_name": "my-mcp-server",
  "action": "accept",
  "content": { "username": "alice" },
  "mode": "form",
  "elicitation_id": "elicit-123"
}

ElicitationResult 輸出

若要覆寫使用者的回應，請回傳含有 hookSpecificOutput 的 JSON 物件：

{
  "hookSpecificOutput": {
    "hookEventName": "ElicitationResult",
    "action": "decline",
    "content": {}
  }
}

退出碼 2 會封鎖回應，將實際動作變更為 decline。Claude Code 不會在任何地方顯示您的 stderr 訊息。

Claude Code 會依據 ElicitationResult hook JSON 輸出中的 hookSpecificOutput 採取行動，並捨棄 systemMessage 和 continue。

基於提示的 hooks

除了命令、HTTP 和 MCP tool hooks 外，Claude Code 還支援基於提示的 hooks（type: "prompt"），使用 LLM 評估是否允許或阻止操作，以及代理 hooks（type: "agent"），生成具有工具存取權限的代理驗證器。並非所有事件都支援每種 hook 類型。

支援所有五種 hook 類型（command、http、mcp_tool、prompt 和 agent）的事件：

• PermissionDenied
• PostToolBatch
• PostToolUse
• PostToolUseFailure
• PreToolUse
• Stop
• SubagentStop
• TaskCompleted
• TaskCreated
• TeammateIdle
• UserPromptExpansion
• UserPromptSubmit

PermissionRequest 支援 command、http、mcp_tool 和 prompt hooks，但不支援 agent hooks。如果您在此事件上配置代理 hook，Claude Code 會跳過它，權限流程保持不變。要從 hook 允許或拒絕，請從命令或 HTTP hook 返回決定物件。

支援 command、http 和 mcp_tool hooks 但不支援 prompt 或 agent 的事件：

• ConfigChange
• CwdChanged
• DirectoryAdded
• Elicitation
• ElicitationResult
• FileChanged
• InstructionsLoaded
• MessageDisplay
• Notification
• PostCompact
• PostModelSwitch
• PreCompact
• PreModelSwitch
• SessionEnd
• StopFailure
• SubagentStart
• WorktreeCreate
• WorktreeRemove

SessionStart 和 Setup 支援 command 和 mcp_tool hooks，而 MCP tool hook 欄位描述了它們的 mcp_tool hooks 何時執行。它們不支援 http、prompt 或 agent hooks。

基於提示的 hooks 如何工作

基於提示的 hooks 不執行 Bash 命令，而是：

1. 將 hook 輸入和您的提示發送到 Claude 模型，預設為 Claude Code 用於背景功能的模型
2. LLM 以包含決定的結構化 JSON 回應
3. Claude Code 自動處理決定

提示 hook 配置

將 type 設定為 "prompt" 並提供 prompt 字串而不是 command。使用 $ARGUMENTS 佔位符將 hook 的 JSON 輸入資料注入到您的提示文字中。

此 Stop hook 詢問 LLM 在允許 Claude 完成之前是否應該評估所有任務是否完成：

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "prompt",
            "prompt": "Evaluate if Claude should stop: $ARGUMENTS. Check if all tasks are complete."
          }
        ]
      }
    ]
  }
}

回應架構

LLM 必須以包含以下內容的 JSON 回應：

{
  "ok": true | false,
  "reason": "Explanation for the decision",
  "impossible": true | false
}

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

如果您需要對任何事件進行更精細的控制，請使用命令 hook，其中包含決定控制中描述的每個事件欄位。

在停止前檢查多個條件

此 Stop hook 使用詳細提示在允許 Claude 停止之前檢查三個條件。SubagentStop hooks 使用相同的格式來評估 subagent 是否應該停止。如果模型因為條件尚未滿足而返回 "ok": false，Claude 繼續工作，提供的原因作為其下一個指令：

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "prompt",
            "prompt": "You are evaluating whether Claude should stop working. Context: $ARGUMENTS\n\nAnalyze the conversation and determine if:\n1. All user-requested tasks are complete\n2. Any errors need to be addressed\n3. Follow-up work is needed\n\nRespond with JSON: {\"ok\": true} to allow stopping, or {\"ok\": false, \"reason\": \"your explanation\"} to continue working.",
            "timeout": 30
          }
        ]
      }
    ]
  }
}

基於代理的 hooks

基於代理的 hooks（type: "agent"）類似於基於提示的 hooks，但具有多輪工具存取。代理 hook 不是單一 LLM 呼叫，而是生成一個可以讀取檔案、搜尋程式碼和檢查程式碼庫以驗證條件的 subagent。代理 hooks 支援與基於提示的 hooks 相同的事件，除了 PermissionRequest。

代理 hooks 如何工作

當代理 hook 觸發時：

1. Claude Code 生成一個 subagent，使用您的提示和 hook 的 JSON 輸入
2. Subagent 可以使用 Read、Grep 和 Glob 等工具進行調查
3. 在最多 50 輪後，subagent 返回結構化的 { "ok": true/false } 決定
4. Claude Code 允許該動作（如果 ok 是 true）。如果 ok 是 false，Claude Code 會以與提示 hook 相同的方式處理阻止，該提示 hook 在該事件上具有 continueOnBlock: true，如回應架構下所列

代理 hooks 在驗證需要檢查實際檔案或測試輸出時很有用，而不僅僅是評估 hook 輸入資料。

代理 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": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "agent",
            "prompt": "Verify that all unit tests pass. Run the test suite and check the results. $ARGUMENTS",
            "timeout": 120
          }
        ]
      }
    ]
  }
}

在背景執行 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 執行。當指令碼完成時，其輸出在下一個對話輪次上傳遞：

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/run-tests.sh",
            "async": true
          }
        ]
      }
    ]
  }
}

一旦非同步 hook 在背景執行，Claude Code 不會對其強制執行 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 不同，這兩個欄位都不會顯示給你。

Claude Code 驗證該 JSON 回應是否符合與同步 hooks 相同的輸出結構，並捨棄任何值類型錯誤的欄位，例如不是字串的 systemMessage，而不是傳遞它。使用 --debug 執行以查看命名每個捨棄欄位的警告。在 v2.1.202 之前，來自非同步 hook 的格式不正確的 JSON 輸出可能會導致工作階段崩潰，每次恢復工作階段時都會重複發生崩潰。

非同步 hook 完成通知預設被抑制。要查看它們，請使用 Ctrl+O 啟用詳細模式或使用 --verbose 啟動 Claude Code。

檔案變更後執行測試

此 hook 在 Claude 寫入檔案時在背景啟動測試套件，然後在測試完成時將結果報告回 Claude。將此指令碼儲存到專案中的 .claude/hooks/run-tests-async.sh 並使用 chmod +x 使其可執行：

#!/bin/bash
# run-tests-async.sh

# 從 stdin 讀取 hook 輸入
INPUT=$(cat)
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')

# 僅針對原始檔案執行測試
if [[ "$FILE_PATH" != *.ts && "$FILE_PATH" != *.js ]]; then
  exit 0
fi

# 執行測試並通過 additionalContext 報告結果給 Claude
RESULT=$(npm test 2>&1)
EXIT_CODE=$?

if [ $EXIT_CODE -eq 0 ]; then
  MSG="Tests passed after editing $FILE_PATH"
else
  MSG="Tests failed after editing $FILE_PATH: $RESULT"
fi
jq -nc --arg msg "$MSG" '{hookSpecificOutput: {hookEventName: "PostToolUse", additionalContext: $msg}}'

然後將此配置新增到專案根目錄中的 .claude/settings.json。async: true 旗標讓 Claude 在測試執行時繼續工作：

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/run-tests-async.sh",
            "args": [],
            "async": true
          }
        ]
      }
    ]
  }
}

限制

非同步 hooks 與同步 hooks 相比有額外的限制：

• Hook 輸出在下一個對話輪次上傳遞。如果工作階段閒置，回應會等待直到下一個使用者互動。例外：退出代碼為 2 的 asyncRewake hook 即使在工作階段閒置時也會立即喚醒 Claude。
• 每次執行都會建立一個單獨的背景程序。同一非同步 hook 的多次觸發之間沒有去重。

安全考慮

免責聲明

工作區信任

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）。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "shell": "powershell",
            "command": "Write-Host 'File written'"
          }
        ]
      }
    ]
  }
}

若要從 PowerShell shell 形式命令參考專案根目錄，請寫入 ${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: 形式執行專案指令碼：

{
  "type": "command",
  "shell": "powershell",
  "command": "& \"$env:CLAUDE_PROJECT_DIR\\.claude\\hooks\\check.ps1\""
}

偵錯 hooks

Hook 執行詳細資訊被寫入偵錯日誌檔案。使用 claude --debug-file <path> 啟動 Claude Code 以將日誌寫入已知位置，或執行 claude --debug 並在 ~/.claude/debug/<session-id>.txt 讀取日誌。--debug 標誌不列印到終端。

例如，在 Write 上的 PostToolUse hook，其命令列印 hook-ran 會產生如下項目：

2026-07-19T02:03:24.382Z [DEBUG] Hook output does not start with {, treating as plain text
2026-07-19T02:03:24.382Z [DEBUG] "Hook PostToolUse:Write (PostToolUse) success:\nhook-ran"

有關更細粒度的 hook 匹配詳細資訊，設定 CLAUDE_CODE_DEBUG_LOG_LEVEL=verbose 以查看額外的日誌行，例如 hook 匹配器計數和查詢匹配。

有關故障排除常見問題，如 hooks 不觸發、Stop hooks 持續阻擋或配置錯誤，請參閱指南中的 限制和故障排除。有關涵蓋 /context、/doctor 和設定優先順序的更廣泛診斷逐步解說，請參閱 偵錯您的設定。