在 非互動模式 中使用 -p 旗標，Claude Code 僅在執行有 權限主機 以接收提示時提供 AskUserQuestion 和 ExitPlanMode，例如 Agent SDK canUseTool 回呼。這些工具需要使用者互動。傳回 permissionDecision: "allow" 與 updatedInput 一起滿足該要求：hook 從 stdin 讀取工具的輸入，透過您自己的 UI 收集答案，並在 updatedInput 中傳回它，以便工具執行而不提示。單獨傳回 "allow" 對這些工具不夠。對於 AskUserQuestion，回顯原始 questions 陣列並新增一個 answers 物件，將每個問題的文字對應到選定的答案。

自 v2.1.199 起，其伺服器使用 _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 工具，因此使用一個啟動執行。往返工作如下：

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"，程序以相同方式退出。呼叫程序控制何時透過最終傳回 "allow" 或 "deny" 來打破迴圈。

"defer" 僅在 Claude 在回合中進行單個工具呼叫時有效。如果 Claude 同時進行多個工具呼叫，"defer" 會被忽略，並顯示警告，工具透過正常權限流程進行。約束存在是因為恢復只能重新執行一個工具：沒有辦法延遲批次中的一個呼叫而不留下其他未解決的。

如果恢復時延遲的工具不再可用，程序以 stop_reason: "tool_deferred_unavailable" 和 is_error: true 退出，在 hook 觸發之前。這發生在為恢復的工作階段未連接提供工具的 MCP 伺服器時。deferred_tool_use 有效負載仍包含在內，以便您可以識別哪個工具遺失。

PermissionRequest

在 Claude Code 即將要求您許可使用工具時執行。在無法顯示提示的工作階段中，例如 非互動模式 中的背景子代理，Claude Code 仍執行這些 hooks，如果沒有 hook 傳回決策，它會拒絕工具呼叫。 使用 PermissionRequest 決策控制 代表使用者允許或拒絕。

當您需要 Claude 要求許可使用工具時的信號時，使用此事件。Claude Code 僅在提示等待約六秒後才執行 Notification hook，其 permission_prompt 類型。

Claude Code 不為沙箱命令的 網路請求 執行 PermissionRequest hooks。若要獲得該提示的信號，請使用 permission_prompt 通知類型。

在工具名稱上匹配，與 PreToolUse 相同的值。

PermissionRequest 輸入

PermissionRequest hooks 接收 tool_name 和 tool_input 欄位，如 PreToolUse hooks，但沒有 tool_use_id。對於 MCP 工具，它們也接收 mcp_server 物件。可選 permission_suggestions 陣列包含 Claude Code 為此請求建議的 權限更新，例如新增允許規則或更改權限模式。

permission_suggestions 陣列不是您看到的選項的確切清單，因為每個權限對話都建立自己的選項。某些對話（例如檔案編輯的對話）根本不讀取陣列，並從請求本身衍生其選項。讀取它的對話仍然可以保留陣列中的建議，例如當 allowManagedPermissionRulesOnly 隱藏規則保存選項時。它也可以提供沒有建議項目的選項，例如 Yes, and switch to auto mode，它直接更改權限模式，而不是透過權限更新。

PreToolUse hooks 在每個工具呼叫之前執行，無論它是否需要權限。PermissionRequest hooks 僅在 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 hooks 可以允許或拒絕權限請求。除了 所有 hooks 可用的 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 hooks 在工具已執行成功後觸發。輸入包括 tool_input（傳送給工具的引數）和 tool_response（它傳回的結果）。兩者的確切架構取決於工具。檔案工具 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 hooks 可以在工具執行後提供回饋給 Claude。除了 所有 hooks 可用的 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 中配置的 Hooks：對於來自設定檔、外掛、skills 和代理 frontmatter 的 hooks，分類器將說明視為未驗證的應用程式提供的背景資訊。說明永遠不會建立使用者意圖，如果它聲稱您核准或要求了某事，分類器會根據您在對話中的自己訊息檢查該聲明
• 進程內 Agent SDK 回呼：當應用程式嵌入 Claude Code 並將 hook 註冊為 TypeScript SDK 回呼 並在即時工作階段期間傳回說明時，分類器可能會將使用者陳述（在說明中轉達）視為使用者意圖。這樣的陳述可以滿足分類器會接受來自您傳送的訊息的同意要求，但它永遠不會解除您自己的訊息也無法解除的阻止。工作階段恢復後，Claude Code 將恢復的說明視為未驗證的背景資訊。當來自兩個群組的 hooks 註釋相同呼叫時，分類器將組合說明視為未驗證

Claude Code 在傳遞說明時應用這些限制：

• 長度：Claude Code 將一個工具呼叫的說明上限設定為 2,000 個字元，並截斷其餘部分。上限在每個回應該呼叫的 hook 之間共享
• 僅同步回應：Claude Code 忽略 在背景執行 的 hook 回應中的欄位，因為該回應在 Claude Code 記錄工具結果後到達
• 分類器不記錄的呼叫：分類器的文字記錄省略唯讀查詢，例如檔案讀取和搜尋。Claude Code 捨棄附加到其中一個呼叫的說明
• 與重寫的互動：當說明描述您使用 updatedToolOutput 替換的輸出時，在相同的 hook 回應中傳回兩個欄位。如果該重寫被拒絕或另一個 hook 的重寫替換它，Claude Code 會捨棄說明。Claude Code 傳遞您傳回的說明，而不進行重寫，即使另一個 hook 重寫輸出

PostToolUseFailure

在開始執行的工具失敗時執行：工具拋出錯誤，或 MCP 工具傳回錯誤結果。使用此來記錄失敗、傳送警報或向 Claude 提供更正回饋。

在工具名稱上匹配，與 PreToolUse 相同的值。

PostToolUseFailure 輸入

PostToolUseFailure hooks 接收與 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 接收的失敗工具結果相同。其格式因工具和失敗而異。在 tool_name、is_interrupt 和第一行 Exit code N 上鍵入您的 hook；將字串的其餘部分視為顯示文字，而不是穩定格式。

• 對於 Bash 和 PowerShell，執行並退出的命令會產生第一行 Exit code N，然後是命令產生的任何輸出作為一個區塊，stdout 和 stderr 交錯
• 有效負載也可能攜帶裸失敗訊息，沒有退出代碼行，當 Claude Code 無法啟動 shell 程序本身時
• Claude Code 中間截斷長字串，圍繞 ... [N characters truncated] ... 標記，並可以插入自己的行，例如 Command timed out after 2m 0s

PostToolUseFailure 決策控制

PostToolUseFailure hooks 可以在工具失敗後向 Claude 提供背景資訊。除了 所有 hooks 可用的 JSON 輸出欄位 外，您的 hook 指令碼可以傳回這些事件特定的欄位：

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

PostToolBatch

在批次中的每個工具呼叫都已解決後執行一次，在 Claude Code 傳送下一個請求給模型之前。PostToolUse 每個工具執行一次，這意味著當 Claude 進行平行工具呼叫時它並發執行。PostToolBatch 恰好執行一次，具有完整批次，因此它是注入取決於執行的工具集而不是任何單個工具的背景資訊的正確位置。此事件沒有匹配器。

PostToolBatch 輸入

除了 常見輸入欄位 外，PostToolBatch hooks 接收 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\n     2\t..."
    },
    {
      "tool_name": "Read",
      "tool_input": {"file_path": "/.../ledger/transactions.py"},
      "tool_use_id": "toolu_02...",
      "tool_response": "     1\tfrom __future__ import annotations\n     2\t..."
    }
  ]
}

tool_response 包含模型在對應 tool_result 區塊中接收的相同內容。該值是序列化字串或內容區塊陣列，完全如工具發出的。對於 Read，這意味著行號前綴文字，而不是原始檔案內容。回應可能很大，因此僅解析您需要的欄位。

PostToolBatch 決策控制

PostToolBatch hooks 可以為 Claude 注入背景資訊。除了 所有 hooks 可用的 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 hooks 接收 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 hooks 可以告訴模型它可能重試被拒絕的工具呼叫。傳回一個 JSON 物件，其 hookSpecificOutput.retry 設定為 true：

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

當 retry 為 true 時，Claude Code 向對話新增一條訊息，告訴模型它可能重試工具呼叫。Claude Code 不反轉拒絕本身。如果您的 hook 不傳回 JSON，或傳回 retry: false，拒絕成立，模型接收原始拒絕訊息。

當分類器對動作產生 無判決 時，Claude Code 忽略 retry: true：其回應沒有解析，或與自動模式分開的安全檢查拒絕了分類器自己的請求。對於這些拒絕，Claude Code 已在拒絕訊息中告訴模型是否稍後重試或繼續。

Notification

在 Claude Code 傳送通知時執行。在通知類型上匹配。省略匹配器以對所有通知類型執行 hooks。

即使桌面通知關閉，您也會接收這些 hook 事件：preferredNotifChannel 設定（包括 notifications_disabled）僅更改您如何被警報，而不是您的 hook 是否執行。

agent_needs_input 和 agent_completed 類型需要 Claude Code v2.1.198 或更新版本。

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 回呼 的工作階段中以不同方式計時 permission_prompt，這是 Claude Desktop 和 VS Code 擴充功能如何託管 Claude Code 的方式：

• 期望 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 在這些工作階段中不觸發。

使用單獨的匹配器根據通知類型執行不同的處理程式。此配置在 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 hooks 接收 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 hooks 無法阻止或修改通知。Claude Code 捨棄它們的 systemMessage 和 continue 欄位，但仍發出 terminalSequence，這是桌面通知範例所依賴的。Notification hooks 用於副作用，例如將通知轉發到外部服務。

SubagentStart

在 Claude 使用 Agent 工具生成子代理時執行，當 Claude 恢復子代理 時，以及每次進程內 agent team 隊友處理新訊息時執行。支援匹配器以按代理類型名稱篩選。對於內建代理，這是代理名稱，例如 general-purpose、Explore 或 Plan。對於 自訂子代理，這是代理 frontmatter 中的 name 欄位，而不是檔案名稱。

對於由 外掛 提供的子代理，代理類型是外掛範圍的識別碼，例如 my-plugin:reviewer，而不是裸 frontmatter 名稱。冒號將外掛範圍的名稱放在正規表達式路徑上，因此使用 ^ 和 $ 錨定匹配器以進行精確匹配：^my-plugin:reviewer$。

SubagentStart 輸入

除了 常見輸入欄位 外，SubagentStart hooks 接收 agent_id 與子代理的唯一識別碼和 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 hooks 無法阻止子代理建立，但它們可以將背景資訊注入子代理。除了 所有 hooks 可用的 JSON 輸出欄位 外，您可以傳回：

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

當 hook 再次對同一子代理執行時，Claude Code 僅在子代理的背景資訊還不包含來自較早執行的複本時注入傳回的背景資訊。在啟動時注入的複本保留在位置，保持子代理的 prompt cache 完整。在 自動壓縮 捨棄該複本後，Claude Code 再次注入下一次執行的背景資訊。

SubagentStop

在 Claude Code 子代理完成回應時執行。在代理類型上匹配，與 SubagentStart 相同的值。

SubagentStop 輸入

除了 常見輸入欄位 外，SubagentStop hooks 接收 stop_hook_active、agent_id、agent_type、agent_transcript_path 和 last_assistant_message。agent_type 欄位是用於匹配器篩選的值。transcript_path 是主工作階段的文字記錄，而 agent_transcript_path 是子代理自己的文字記錄，儲存在巢狀 subagents/ 資料夾中。last_assistant_message 欄位包含子代理最終回應的文字內容，因此 hooks 可以存取它而不解析文字記錄檔案。

並非每個 SubagentStop 事件都來自 Claude 生成的子代理。Claude Code 也為其某些自己的功能執行內部代理，例如 prompt suggestions 和 /btw side questions，SubagentStop 在其中一個完成時觸發。對於這些事件，agent_type 是工作階段本身執行的代理名稱，例如使用 --agent 或 agent 設定 設定的，以及當工作階段執行而不使用一個時的空字串。

不命名代理類型的 matcher 不匹配空 agent_type。其匹配器為省略、""、"*" 或是匹配空字串的正規表達式的 hook 也對具有空 agent_type 的事件執行。

在 Claude Code v2.1.271 或更新版本上，使用 SubagentHandback 工具執行的子代理在停止之前透過該工具傳遞其報告。last_assistant_message 欄位然後保持子代理的結束文字（如果有），這不是傳遞的報告。報告是該呼叫的 message 輸入，PreToolUse 或 PostToolUse hook 匹配 SubagentHandback 在 tool_input.message 中接收。

SubagentStop hooks 也接收 Stop input 下描述的 background_tasks 和 session_crons 陣列。兩個陣列的範圍是父工作階段，而不是子代理。

{
  "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 hooks 使用與 Stop hooks 相同的決策控制格式，包括 hookSpecificOutput.additionalContext，其 hookEventName 設定為 "SubagentStop"，用於保持子代理執行的非錯誤回饋。傳回 decision: "block" 搭配 reason 保持子代理執行並將 reason 作為其下一個指示傳遞給子代理。透過退出 2 阻止的 hook 以相同方式傳遞其 stderr 訊息。若要在子代理傳回後將背景資訊注入父工作階段，請改用 PostToolUse hook 在 Agent 工具上。

TaskCreated

在透過 TaskCreate 工具建立任務時執行。使用此來強制命名慣例、要求任務描述或防止建立某些任務。在 沒有 Task 工具的工作階段 中，此事件不觸發。

TaskCreated hooks 不支援匹配器，對每個出現觸發。

TaskCreated 輸入

除了 常見輸入欄位 外，TaskCreated hooks 接收 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

在任務被標記為完成時執行。這在兩種情況下觸發：當任何代理透過 TaskUpdate 工具明確標記任務為完成時，或當 agent team 隊友以進行中的任務完成其回合時。使用此來強制完成標準，例如通過測試或 lint 檢查，然後任務才能關閉。

TaskCompleted hooks 不支援匹配器，對每個出現觸發。

TaskCompleted 輸入

除了 常見輸入欄位 外，TaskCompleted hooks 接收 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 hooks 支援兩種方式來控制任務完成：

• 退出代碼 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 代理完成回應時執行。如果停止發生是由於使用者中斷，則不執行。API 錯誤改為觸發 StopFailure。

Stop 輸入

除了 常見輸入欄位 外，Stop hooks 接收 stop_hook_active、last_assistant_message、background_tasks 和 session_crons。stop_hook_active 欄位在 Claude Code 已作為 stop hook 的結果繼續時為 true。檢查此值或處理文字記錄以避免在永遠不會解決的條件上阻止。Claude Code 在 8 個連續阻止後覆寫 hook 並結束回合。

last_assistant_message 欄位包含 Claude 最終回應的文字內容，因此 hooks 可以存取它而不解析文字記錄檔案。對於作用於剛完成回合的 hooks，例如朗讀或通知 hooks，使用此欄位而不是讀取 transcript_path：文字記錄檔案不保證在所有版本上的 Stop 時間包含最終訊息。

background_tasks 和 session_crons 陣列讓 hooks 區分「工作階段完成」與「工作階段暫停等待背景工作喚醒它」。當任務登錄可到達時兩個陣列都存在，當沒有任何東西在飛行或排程時為空。

background_tasks 中的每個項目描述一個進行中的任務，並使用這些欄位：

session_crons 中的每個項目描述一個工作階段範圍的排程喚醒，來自 CronCreate、ScheduleWakeup 和 /loop：

此範例顯示一個 Stop 輸入，具有一個進行中的 shell 任務和一個循環 cron：

{
  "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 hooks 可以控制 Claude 是否繼續。除了 所有 hooks 可用的 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。Claude Code 忽略 hook 的輸出和退出代碼，除了 terminalSequence。使用此來記錄失敗、傳送警報或在 Claude 因速率限制、驗證問題或其他 API 錯誤無法完成回應時採取復原動作。

StopFailure 輸入

除了 常見輸入欄位 外，StopFailure hooks 接收 error、可選 error_details 和可選 last_assistant_message。error 欄位識別錯誤類型，用於匹配器篩選。

{
  "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 hooks 沒有決策控制。它們僅用於通知和記錄目的執行。

TeammateIdle

在 agent team 隊友在完成其回合後即將閒置時執行。使用此來強制品質閘門，然後隊友停止工作，例如要求通過 lint 檢查或驗證輸出檔案存在。

TeammateIdle hooks 不支援匹配器，對每個出現觸發。

TeammateIdle 輸入

除了 常見輸入欄位 外，TeammateIdle hooks 接收 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 hooks 支援兩種方式來控制隊友行為：

• 退出代碼 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

在工作階段期間配置檔案變更時執行。使用此來稽核設定變更、強制安全原則或阻止對配置檔案的未授權修改。

Claude Code 在設定檔、受管原則檔案或 skill 檔案變更時執行 ConfigChange hooks。對於受管原則，它僅在 managed-settings.json 或 managed-settings.d/ 中的檔案變更時執行。它應用 伺服器受管設定 和對 macOS 受管偏好設定或 Windows 登錄原則的變更，而不執行它們。在 WSL 上搭配 wslInheritsWindowsSettings，它也在其原則輪詢上應用變更的 Windows 端受管設定檔，而不執行它們。

匹配器篩選配置來源：

此範例記錄所有配置變更以進行安全稽核：

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

ConfigChange 輸入

除了 常見輸入欄位 外，ConfigChange hooks 接收 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 hooks 可以阻止配置變更生效。使用退出代碼 2 或 JSON decision 來防止變更。當被阻止時，新設定不會套用到執行中的工作階段。

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

policy_settings 變更無法被阻止。當機器上的受管設定檔變更時，Hooks 仍對 policy_settings 來源觸發，因此您可以使用它們來記錄這些編輯，但任何阻止決策都會被忽略。這確保企業受管設定始終生效。當 伺服器受管設定 到達或重新整理時，Claude Code 不執行 ConfigChange hooks。

Claude Code 從 ConfigChange hook 的 JSON 輸出作用於阻止決策，並捨棄 systemMessage 和 continue。被阻止的變更不會向您或 Claude 呈現任何訊息，無論您使用 reason 還是退出 2 的 stderr 阻止。Claude Code 僅將一行寫入 debug log。

CwdChanged

在主對話中的 shell 命令變更工作目錄時執行，例如當 Claude 執行 cd 命令時。使用此來對目錄變更做出反應：重新載入環境變數、啟用專案特定的工具鏈，或自動執行設定指令碼。與 FileChanged 配對，用於 direnv 等管理每個目錄環境的工具。

CwdChanged hooks 可以存取 CLAUDE_ENV_FILE。寫入該檔案的變數會保留到後續 Bash 命令，直到下一個 CwdChanged 事件，當 Claude Code 清除它們時。

CwdChanged 不支援匹配器，對每個出現觸發。

CwdChanged 輸入

除了 常見輸入欄位 外，CwdChanged hooks 接收 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 輸出

除了 所有 hooks 可用的 JSON 輸出欄位 外，CwdChanged hooks 可以傳回 watchPaths 以動態設定 FileChanged 監視的檔案路徑：

CwdChanged hooks 沒有決策控制。它們無法阻止目錄變更。

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

DirectoryAdded

在您使用 /add-dir 命令在工作階段中新增工作目錄後執行，或在 SDK 用戶端使用 register_repo_root 控制請求新增一個後執行。使用此來準備新增的儲存庫，例如安裝其相依性。

Claude Code 在以下情況下不觸發此事件：

• 您使用 --add-dir 啟動旗標傳遞目錄；SessionStart 涵蓋這些目錄
• 您在 /permissions Workspace 標籤上新增目錄
• 您新增已是工作目錄或在其內部的目錄

Claude Code 在重新整理 sandbox 和權限狀態後觸發 DirectoryAdded，因此沙箱工具在您的 hook 執行時已看到新目錄。Hook 命令本身執行未沙箱化。

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

匹配器篩選目錄的新增方式：

DirectoryAdded 輸入

除了 常見輸入欄位 外，DirectoryAdded hooks 接收 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 hooks 沒有決策控制。它們無法阻止新增，這在 hook 執行時已完成。Claude Code 從其 JSON 輸出捨棄 continue 欄位，並根據來源以不同方式呈現其餘部分：

• slash_command：Claude Code 將 hook 的 systemMessage 作為背景資訊傳遞給 Claude，在下一個對話回合上，而不是向您顯示。失敗 hooks 的計數出現在文字記錄中。完整失敗輸出進入 debug log
• register_repo_root：Claude Code 僅將 systemMessage 輸出和失敗輸出寫入 debug log

FileChanged

在監視的檔案在磁碟上變更時執行。Claude Code 使用檔案系統監視器偵測變更，而不是檢查工具呼叫，因此無論什麼變更檔案，它都執行 hook：Edit 或 Write 工具呼叫、Claude 使用 Bash 執行的指令碼，或 Claude Code 外的程序。常見用途是在專案配置檔案變更時重新載入環境變數。

此事件的 matcher 有兩個角色：

• 建立監視清單：值在 | 上分割，每個段落註冊為工作目錄中的字面檔案名稱，因此 ".envrc|.env" 恰好監視這兩個檔案。正規表達式模式在這裡不有用：^\.env 之類的值會監視字面名稱為 ^\.env 的檔案。
• 篩選哪些 hooks 執行：當監視的檔案變更時，相同的值使用標準 匹配器規則 針對變更檔案的基名篩選哪個 hook 群組執行。

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

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

Hook 從 JSON 輸入 的 file_path 欄位讀取變更檔案的絕對路徑，在 stdin 上。其 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 命令將 CRLF 行附加到 data.csv。Claude Code 執行 hook，檔案最終使用 LF 結尾。

若要監視您無法提前命名的檔案，從 hook 傳回 watchPaths 以動態更新監視清單。Claude Code 僅在某事命名要監視的檔案時啟動監視器，因此使用命名至少一個檔案的 FileChanged 群組播種清單，或使用 SessionStart 或 CwdChanged hook 傳回 watchPaths。匹配器仍篩選當監視的檔案變更時哪個 hook 群組執行，因此給處理動態路徑的群組一個省略的匹配器，它匹配每個監視的檔案，並不向監視清單新增任何東西。"*" 匹配器也匹配每個檔案，但 Claude Code 像任何其他值一樣在監視清單中註冊它，作為字面名稱為 * 的檔案。

FileChanged hooks 可以存取 CLAUDE_ENV_FILE。寫入該檔案的變數會保留到後續 Bash 命令，直到下一個 CwdChanged 事件，當 Claude Code 清除它們時。

FileChanged 輸入

除了 常見輸入欄位 外，FileChanged hooks 接收 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 輸出

除了 所有 hooks 可用的 JSON 輸出欄位 外，FileChanged hooks 可以傳回 watchPaths 以動態更新監視的檔案路徑：

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

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

WorktreeCreate

在建立 worktree 時執行，無論是從 claude --worktree、從 使用 isolation: "worktree" 的子代理，或對於 Claude Code 在其自己的 worktree 中隔離的 背景工作階段。預設情況下，Claude Code 使用 git worktree 建立隔離的工作副本。配置 WorktreeCreate hook 替換該預設 git 行為，讓您使用不同的版本控制系統，如 SVN、Perforce 或 Mercurial。

因為 hook 完全替換預設行為，.worktreeinclude 不被處理。如果您需要將本機配置檔案（如 .env）複製到新 worktree，請在您的 hook 指令碼內執行。

Hook 必須傳回建立的 worktree 目錄的路徑。Claude Code 使用此路徑作為隔離工作階段的工作目錄。請參閱 WorktreeCreate 輸出，了解每個 hook 類型如何傳回路徑。

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 hooks 接收 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 hooks 不使用標準允許/阻止決策模型。相反，hook 的成功或失敗決定結果。Hook 必須傳回建立的 worktree 目錄的路徑：

• 命令 hooks (type: "command")：將路徑列印為 stdout 的最後一個非空行。Claude Code 在讀取該行之前去除 ANSI 逸出代碼，因此在您的 echo 之前列印的 shell 啟動橫幅會被忽略。將任何其他 hook 輸出重新導向到 stderr。
• HTTP hooks (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" 的子代理完成
• 您刪除 背景工作階段，其 worktree hook 建立

對於基於 git 的 worktrees，Claude Code 使用 git worktree remove 自動處理清理。如果您為非 git 版本控制系統配置了 WorktreeCreate hook，請將其與 WorktreeRemove hook 配對以處理清理。沒有它，worktree 目錄會保留在磁碟上。

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

對於背景工作階段刪除，Claude Code 在執行 hook 之前驗證儲存的 worktree 路徑，並拒絕儲存庫根下方是符號連結或通過符號連結的路徑。Hook 僅對仍包含檔案的 worktree 執行，當您在 agent view 中確認刪除時；對於這樣的 worktree，claude rm 保持工作階段和 worktree。在 v2.1.216 之前，hook 在儲存的路徑上執行，而不進行這些檢查。

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

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

WorktreeRemove 輸入

除了 常見輸入欄位 外，WorktreeRemove hooks 接收 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 進入 debug log。
• 如果您刪除背景工作階段，工作階段也保留。agent view 中的拒絕訊息報告 hook 如何結束，例如 exited 1，引用其 stderr 的開頭，並說明再次刪除工作階段是否無論如何移除目錄。

PreCompact

在 Claude Code 即將執行壓縮操作時執行。

匹配器值指示壓縮是手動還是自動觸發：

以代碼 2 退出以阻止壓縮。對於手動 /compact，stderr 訊息顯示給使用者。您也可以透過傳回 JSON 搭配 "decision": "block" 來阻止。

阻止自動壓縮根據何時觸發有不同的效果。如果壓縮在背景限制之前主動觸發，Claude Code 跳過它，對話繼續未壓縮。如果壓縮被觸發以從 API 已傳回的背景限制錯誤復原，基礎錯誤呈現，目前請求失敗。

Claude Code 捨棄 PreCompact hook 的 systemMessage 和 continue 欄位。

PreCompact 輸入

除了 常見輸入欄位 外，PreCompact hooks 接收 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 相同的匹配器值適用：

PostCompact 輸入

除了 常見輸入欄位 外，PostCompact hooks 接收 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 hooks 沒有決策控制。它們無法影響壓縮結果，但可以執行後續任務。

PreModelSwitch

在 Claude Code 應用您或用戶端要求的模型切換之前執行。使用它來阻止切換、要求確認或在切換發生前顯示成本。

PreModelSwitch 需要 Claude Code v2.1.251 或更新版本。Claude Code 為這些請求執行它：

• /model <name> 和 /model 選擇器
• Option+P 或 Alt+P 模型選擇器
• /config 中的 Model 設定
• 當那改變工作階段的模型時開啟 fast mode
• 來自 Agent SDK 主機或 Remote Control 的 set_model 請求，或 apply_flag_settings 請求中的模型變更

Claude Code 不為它自己進行的切換執行 PreModelSwitch hooks，例如 自動模型回退 或恢復工作階段時恢復模型。這些變更僅到達 PostModelSwitch。

Claude Code 根據工作階段切換到的模型的規範名稱比較匹配器，忽略任何 [1m] 後綴。別名（如 opus）、日期模型 ID 和提供者特定 ID（如 Amazon Bedrock 模型 ID）都匹配它們解決到的一個規範名稱，因此 claude-opus-5 涵蓋 Opus 5 的每個拼寫。

當 Claude Code 無法確定目標的規範名稱時，例如只有您的 LLM gateway 知道的自訂模型 ID，它執行每個 PreModelSwitch hook，無論匹配器如何。阻止的 hook 應該從其輸入檢查 to_model 而不是僅依賴匹配器。

將匹配器寫為精確名稱、| 分隔清單（如 claude-opus-4-6|claude-opus-5）或正規表達式（如 .*opus.*）。此範例使用精確名稱匹配器，也從 hook 輸入檢查 to_model，因此它拒絕切換到 Opus 4.6，透過以代碼 2 退出，並讓任何其他目標通過：

{
"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 hooks 接收此表中的欄位。最後五個描述重新傳送對話到新模型的成本，因此 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 hooks 可以取消切換、要求使用者確認它，或讓它進行。退出代碼 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 的權杖計數：

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

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

Claude Code 無論決策如何都顯示您的 hook 傳回的任何 systemMessage，因此成本報告 hook 可以傳回 {"systemMessage": "..."} 並退出 0。

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

以 0 或 2 以外的代碼退出且不列印 JSON 決策的 hook 不阻止：Claude Code 顯示其 stderr 並應用切換，如 其他退出代碼 下所述。

PostModelSwitch

在工作階段的模型變更後執行。使用它來給予 Claude 模型特定的指導，而不編輯每個 CLAUDE.md，例如僅在某些模型上適用的組織範圍指示。

PostModelSwitch 需要 Claude Code v2.1.251 或更新版本。它無法阻止，因為模型已變更。Claude Code 在這些變更後執行 PostModelSwitch hooks：

• 您或用戶端要求的切換
• 自動模型回退，改變工作階段的模型
• 設定（如 opusplan）進入或離開 plan mode
• Claude Code 在您恢復工作階段時恢復模型

當 回退模型鏈 中的模型服務回合時，Claude Code 不執行 PostModelSwitch hooks，因為該替換持續一個回合，並保持工作階段的模型不變。

匹配器遵循與 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 hooks 接收與 PreModelSwitch 相同的欄位，其 hook_event_name 設定為 "PostModelSwitch" 和兩個更多 source 值："auto" 對於自動回退或 Claude Code 自己進行的其他變更，以及 "resume" 對於您恢復工作階段時恢復的模型。

當 source 為 "auto" 時，requested_model 為 null。當 source 為 "resume" 時，它是 Claude Code 恢復的儲存模型設定。

PostModelSwitch 決策控制

Claude Code 採用您的 hook 的 純文字 stdout 在退出 0 上，或來自 JSON 輸出的 additionalContext，並在切換後的下一個請求中將其傳遞給 Claude。除了 所有 hooks 可用的 JSON 輸出欄位 外，您可以傳回：

如果 hook 在您傳送下一個提示後五秒內未完成，Claude Code 傳送該請求而不輸出，並將其附加到下一個請求。如果模型在下一個請求之前變更多次，Claude Code 僅傳遞最後一個切換目標模型的輸出。

SessionEnd

在 Claude Code 工作階段結束時執行。適用於清理任務、記錄工作階段統計資訊或儲存工作階段狀態。支援匹配器以按退出原因篩選。

reason 欄位在 hook 輸入中指示工作階段為什麼結束：

SessionEnd 輸入

除了 常見輸入欄位 外，SessionEnd hooks 接收 reason 欄位，指示工作階段為什麼結束。請參閱上面的 原因表 以獲得所有值。

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

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

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

• 每個 hook timeout：在該 hook 的配置中設定 timeout。整體預算自動上升以符合您設定檔中最高的每個 hook timeout，最多 60 秒。如果您以這種方式提高預算，沒有自己 timeout 的 hook 仍保持預設。在外掛提供的 hooks 上設定的逾時不會提高預算。
• 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 為使用者回應顯示互動式對話。Hooks 可以攔截此請求並以程式設計方式回應，完全跳過對話。

匹配器欄位根據 MCP 伺服器名稱匹配。

Elicitation 輸入

除了 常見輸入欄位 外，Elicitation hooks 接收 mcp_server_name、message 和可選的 mode、url、elicitation_id 和 requested_schema 欄位。

對於表單模式引誘，最常見的情況：

{
  "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 模式引誘，用於基於瀏覽器的驗證：

{
  "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 拒絕引誘。Claude Code 不在任何地方顯示您的 stderr 訊息。

Claude Code 從 Elicitation hook 的 JSON 輸出作用於 hookSpecificOutput，並捨棄 systemMessage 和 continue。

ElicitationResult

在使用者回應 MCP 引誘後執行。Hooks 可以觀察、修改或阻止回應，然後將其傳送回 MCP 伺服器。

匹配器欄位根據 MCP 伺服器名稱匹配。

ElicitationResult 輸入

除了 常見輸入欄位 外，ElicitationResult hooks 接收 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 模型，預設為 Haiku
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。自 v2.1.198 起，Claude Code 會在 PowerShell shell 形式命令中將 ${CLAUDE_PROJECT_DIR}、${CLAUDE_PLUGIN_ROOT} 和 ${CLAUDE_PLUGIN_DATA} 佔位符重寫為 PowerShell 的 ${env:NAME} 形式，無論 hook 是在 settings.json、plugin 或 skill 中定義。PowerShell 會在解析後從匯出的環境中解析該值，因此佔位符在雙引號字串內有效，但在單引號字串內無效，因為 PowerShell 永遠不會在單引號字串中展開變數。

在 v2.1.198 之前，此重寫僅適用於 plugin hooks。在較早的版本上，settings.json hook 需要 $env: 形式或 exec 形式，其中 ${CLAUDE_PROJECT_DIR} 會在每個 args 元素中被替換，無論 hook 在何處定義。

不要在 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 和設定優先順序的更廣泛診斷逐步解說，請參閱 偵錯您的設定。