本頁譯自英文文件。指令、識別名稱與範例保持原樣。執行環境 7.24.4 · SDK 2.6.7。英文原文

生命週期鉤子

狀態：現行
範圍：現行狀態
上次審閱：2026-08-23 負責人：ax-code runtime

生命週期鉤子讓你在代理程式事件上執行 shell 指令，而不必重建執行環境。它們補足權限規則與隔離沙箱：鉤子是決定性的副作用（「一律格式化」、「絕不強制推送」），提示則仍只是建議。

事件

事件	時機	能否阻擋？
PreToolUse	工具執行之前	能（`blockOnFailure: true`）
PostToolUse	工具完成之後（`args`：工具引數）。有上限的 stdout／結構化回饋會附加到模型看到的工具結果；見下文	否
PostToolUseFailure	工具丟出例外之後（`args`：`{ args, error }`，錯誤文字上限 4,000 個字元）。發出後即結束；錯誤仍原樣送達模型	否
Stop	工作階段回合完成時（套件可透過自動化在停止時執行）	否
UserPromptSubmit	使用者提示送出時，在訊息被保存之前	能（`blockOnFailure: true`）
PreCompact	工作階段壓縮執行之前（`args`：`{ auto, overflow }`）	否
SubagentStop	`task` 子代理程式結束時（`args`：`{ agent, status }`）	否
SessionStart	頂層工作階段建立時（`args`：`{ sessionID, title, time }`）	否
SessionEnd	工作階段被移除或封存時（`args`：`{ sessionID, reason }`，`reason` 為 `"remove"` 或 `"archive"`）	否
PostCompact	工作階段壓縮成功完成之後（`args`：`{ sessionID, reason }`，`reason` 為 `"auto"` 或 `"manual"`；壓縮中止時不會觸發，例如情境溢位）	否
Interrupt	使用者或操作者明確取消進行中的回合時（`args`：`{ sessionID }`；正常回合完成或內部清理時不會觸發）	否

四個工作階段生命週期事件（SessionStart、SessionEnd、PostCompact、Interrupt）與 PostToolUseFailure 只供觀察：它們發出後即結束，從不阻擋生命週期路徑，承載只帶 id／原因／時間戳——從不帶對話文字、摘要或工具輸出。子代理程式工作階段不會觸發 SessionStart（它們已透過 SubagentStop 呈現）。SubagentStop 會針對由 task 與 task_parallel 兩者啟動的子項觸發。

模型會收到 PostToolUse 回饋

PostToolUse 鉤子可以把文字交回模型。它會附加在工具結果裡的 <hook_feedback event="PostToolUse"> 區塊中，位於工具自己的輸出之後；它從不取代輸出，也從不阻擋。

舊有項目（沒有 protocol）：結束代碼為 0 的鉤子，其裁剪後的 stdout。
protocol: "claude-code" 項目：hookSpecificOutput.additionalContext、reason（來自 {"decision": "block", "reason": "..."} 判定），或鉤子以結束代碼 2 離開時的 stderr。其他非零結束代碼不貢獻內容。

每個鉤子的回饋上限為 4,000 個字元，每次工具呼叫上限為 8,000 個字元，因此吵雜的鉤子無法灌滿情境。這使 format-after-edit 套件有用：它的提醒現在會進入模型的下一回合，而不只留在日誌裡。

這些名稱對應 AX Code 內部的外掛觸發（tool.execute.before／tool.execute.after），加上工作階段層級的提示、壓縮、子代理程式與停止鉤子。合成的延續提示（內部 agentRouting: "preserve" 提示）不會觸發 UserPromptSubmit。

啟用套件

專案鉤子與外掛會執行儲存庫控制的程式碼，因此 .ax-code/hooks.json、.ax-code/plugin/ 與專案設定的外掛預設停用。審閱之後，請在儲存庫之外、啟動 AX Code 時選擇啟用：

AX_CODE_TRUST_PROJECT_CONFIG=1 ax-code

然後在專案中建立 .ax-code/hooks.json：

{
  "packs": ["format-after-edit", "block-force-push", "require-tests-on-stop", "protect-env-files", "log-bash-commands"]
}

官方套件（≥5）

套件	事件	說明
`format-after-edit`	PostToolUse	提醒代理程式在編輯後格式化
`block-force-push`	PreToolUse	阻擋 `git push --force`／`-f`
`require-tests-on-stop`	Stop	提醒在變更後驗證
`protect-env-files`	PreToolUse	工具碰觸 `.env` 時提出警告
`log-bash-commands`	PreToolUse	記錄 bash 指令供稽核

自訂鉤子：

{
  "hooks": [
    {
      "event": "PreToolUse",
      "matcher": "bash",
      "command": "echo running bash",
      "blockOnFailure": false
    }
  ]
}

Claude Code 線路協定（須自行啟用）

若你已經有為 Claude Code 撰寫的鉤子，項目可以用 "protocol": "claude-code" 選擇 Claude Code 線路協定：

{
  "hooks": [
    {
      "event": "PreToolUse",
      "matcher": "bash",
      "command": "my-claude-code-hook.sh",
      "protocol": "claude-code"
    }
  ]
}

對於可阻擋的事件（PreToolUse、UserPromptSubmit），已選擇的項目會以 Claude Code 語意解碼，而不是 blockOnFailure 檢查：

結束代碼 2 阻擋該動作；鉤子的 stderr 會作為原因呈現。格式錯誤的 stdout 仍然阻擋（失敗時採取安全側）。
結束代碼 0 且 stdout JSON 為 {"permissionDecision": "allow"|"deny"|"ask", "reason"?}： allow 繼續；deny 以 reason 阻擋；ask 會在互動式 hook 權限提示上暫停工具呼叫，並顯示原因（預設 "hook requested user confirmation"）。此提示僅限互動：沒有 always 規則、萬用字元授予或自主自動核准可以回答它，而無介面執行會拒絕它，模型會把它看成一般的權限拒絕。較晚回答 deny 的鉤子優先於較早的 ask。 UserPromptSubmit 沒有可附加提示的工具呼叫，因此 ask 在那裡仍然阻擋。巢狀的 Claude Code 形狀 {"hookSpecificOutput": {"permissionDecision": "...", "permissionDecisionReason": "..."}} 被接受為別名。
任何其他結束代碼 都是不阻擋的錯誤（記入日誌，動作繼續）。

只供觀察的事件完全略過解碼器——它們永遠不能阻擋。沒有 protocol 欄位的項目行為與先前完全相同。

鉤子指令可用的環境變數：

HOOK_EVENT — PreToolUse、PostToolUse、PostToolUseFailure、Stop、UserPromptSubmit、PreCompact、SubagentStop、SessionStart、SessionEnd、PostCompact、Interrupt
HOOK_TOOL — 工具 id
HOOK_SESSION_ID
HOOK_ARGS_JSON — JSON 工具引數
HOOK_ARGS_STDIN=1 — 完整的 JSON 引數一律可從 stdin 取得；承載大於 32 KiB 時 HOOK_ARGS_JSON 為空
HOOK_PACK — 適用時的套件名稱

鉤子子處理程序繼承已淨化的 AX Code 環境。AX Code 保留一般的平台與工具變數，但會移除類似祕密的名稱、帶有憑證的 URL、例如 SSH_AUTH_SOCK 的憑證輔助程式，以及例如 NODE_OPTIONS 的處理程序注入變數。上面的 HOOK_* 協定變數在淨化之後加入，而且一律可用。

需要環境憑證、且完全受信任的舊有鉤子，可以在儲存庫之外恢復先前的行為：

AX_CODE_HOOKS_FULL_ENV=1 AX_CODE_TRUST_PROJECT_CONFIG=1 ax-code

這個逃生口會把每個環境變數暴露給每個已啟用的鉤子。儲存庫不能透過 .ax-code/hooks.json 要求它；請只在審閱全部鉤子與套件之後使用。

**安全性說明：**環境淨化可降低環境憑證的暴露，但不會把鉤子指令放進沙箱。鉤子仍是任意 shell 程式碼，可以讀取可存取的檔案並使用主機網路。請把它們視為受信任的程式碼，並審閱每一個已啟用的鉤子與套件。

與隔離的關係

鉤子不能取代沙箱。請使用：

應用程式隔離，用於可攜的寫入／網路邊界
作業系統隔離（預設的 "auto" 後端），在可用時提供核心強制的 bash 沙箱
鉤子，用於原則副作用與強制推送這類硬性阻擋

請見沙箱模式與 SECURITY.md。