設定
Hooks 透過兩個層級的 JSON 檔案設定：
兩個檔案會疊加合併。相同的處理器（同一事件、比對器和指令）會自動去重。
設定格式
hooks 包裝是可選的——您也可以將事件鍵值直接放在根層級。
每個事件鍵值對應一個規則物件陣列。規則包含：
matcher— 要比對的工具或觸發器（參見 比對器）hooks— 處理器物件陣列，每個包含：type— 固定為"command"command— 要執行的 shell 指令timeout— 每個處理器的逾時秒數（預設 60）
比對器
比對器遵循 Claude Code 語意：事件
執行協定
每個比對到的處理器會透過 shell 執行，cwd 設定為專案路徑。stdin 會傳入一個 JSON 承載，包含：
session_id— 目前的工作階段 IDcwd— 專案路徑hook_event_name— 事件名稱
tool_name、tool_input、tool_response、prompt、trigger、agent_type 和 goal。
以下環境變數會被設定：
結束代碼
逾時同樣視為非阻擋性失敗。
決策輸出
結束代碼為0 時，stdout 可包含一個 JSON 物件：
- 阻擋工具呼叫（PreToolUse）：
{"decision": "block", "reason": "..."} - 拒絕並附原因（PreToolUse）：
{"hookSpecificOutput": {"permissionDecision": "deny", "permissionDecisionReason": "..."}} - 附加回饋（PostToolUse）：
{"additionalContext": "..."}
適用範圍
Hooks 適用於所有代理情境：- 主代理的工具呼叫
- 子代理的工具呼叫（承載中包含
agent_type） - GUI 工具呼叫
- ACP 工具呼叫
UserPromptSubmit 僅攔截使用者輸入的提示——目標延續和內部工作階段訊息不受影響。
Hook 引擎失敗不會傳播至代理迴圈。
外掛也可以提供 hook。它們會在安裝時明確核准，並與您的全域和專案 hook 合併。