Hooks
在 CLAUDE.md 檔案中告訴 Claude 該做什麼,問題就在這裡:那只是一個請求,而不是保證。您可以寫下「編輯後務必進行格式化」,而 Claude 通常會遵從。通常。但在一個您無法全程盯著的長時間執行過程中,「通常」並不夠好。Hook 就是用來解決這個問題的。Hook 是一段確定性的程式碼,會在迴圈中的固定時間點執行,因此它能夠保證行為的發生,而不是只能寄望於它。它把一條規則從「Claude 通常會遵從」變成了「Claude 不能跳過它」。
這就是整套說法的核心。現在讓我們來看看它實際上是如何運作的。
Hook 事件
Claude Code 在一個工作階段的過程中會觸發大約 30 個 hook 事件。您不需要全部都知道,hooks 參考文件(在新分頁中開啟)列出了每一個事件。其中有一小部分您會一再用到,它們恰好對應代理迴圈(agentic loop)中您會想要介入的時間點。
以下是它們在迴圈中的位置。一個工作階段開始,提示(prompt)進來,工具被呼叫,回合最終結束。每一個時刻都有一個您可以掛上程式碼的 hook。
值得認識的有:
- PreToolUse 在工具呼叫之前觸發。這是您的強制執行原語(enforcement primitive)。它是那個能夠在事情發生之前就阻止它的 hook。
- PostToolUse 在工具呼叫成功之後觸發。這通常是自動格式化或自動 lint 所在的位置。
- Stop 在 Claude 想要結束其回合時觸發。如果某個條件未被滿足,您可以拒絕並說「不,你還沒完成」。還有一個對應的 SubagentStop,用於子代理(sub-agent)完成時的情況。
- PreCompact 和 PostCompact 分別在壓縮(compaction)之前與之後觸發。
- InstructionsLoaded 在載入 CLAUDE.md 或規則檔案時觸發。對於稽核實際進入上下文的內容來說很方便。
- SessionStart 在開始時觸發,並為環境做好準備。如果您只想在全新啟動時觸發,請使用
startup來源。
有一件事會讓人困惑:若要在壓縮後重新注入上下文,不要使用 PostCompact。請使用帶有 compact 比對器(matcher)的 SessionStart。那才是真正能把其輸出送回對話中的那一個。
PreToolUse:以 JSON 形式回傳決策
PreToolUse 是真正具有威力的地方,因為它能在工具呼叫執行之前就將其阻擋下來。您與 Claude 溝通的方式,是印出 JSON 並以零值結束程序(exit zero)。關鍵欄位是 permissionDecision,它可以是以下三個值之一:
allow— 讓呼叫通過deny— 阻止呼叫ask— 交還給使用者來決定
技術上還有第四個值 defer,但它只適用於非互動式的 -p 執行,也就是呼叫程序暫停工具並在之後恢復執行的情況。您很少會用到它。
其結構大致如下:
{
"hookSpecificOutput": {
"hookEventName": "PreToolUse",
"permissionDecision": "deny",
"permissionDecisionReason": "Don't push to main. Open a pull request instead."
}
}除了阻擋呼叫之外,您也可以重寫它。回傳 allow 或 ask,並附上 updatedInput。使用 ask 時,您會看到重寫後的呼叫並加以核准。使用 allow 時,它會不經提示直接執行:
{
"hookSpecificOutput": {
"hookEventName": "PreToolUse",
"permissionDecision": "ask",
"updatedInput": {
"command": "..."
}
}
}這就是您如何把機密資訊從一個 bash 指令中編修掉,同時仍然讓它執行的方法。有一個需要注意的地方:updatedInput 會取代整個輸入物件,所以您必須把沒有變更的欄位原樣回傳,否則就會遺失它們。
結束代碼:用於不回傳 JSON 的 hook
並非每個 hook 都需要以 JSON 溝通。對於較簡單的 hook,結束代碼(exit code)就能完成任務。有三個重要的數字。
- 0 代表成功。 如果標準輸出是 JSON,Claude 會解析它。在大多數事件中,純文字會被忽略,但在 SessionStart、UserPromptSubmit 和 UserPromptExpansion 這幾個事件中,純文字會被加入上下文。這正是讓狀態保存(state-preserver)hook 得以運作的原因。
- 2 代表阻擋性錯誤。 標準錯誤會被回饋給 Claude 作為上下文。在幾乎所有地方,這都是用來阻擋的結束代碼。
- 其他任何值都是非阻擋性的。標準錯誤會被記錄下來,而 Claude 會繼續進行。
讓人中招的是結束代碼 1。它感覺像是一個錯誤,但它其實並不會阻擋。Claude 仍然會執行該指令。所以如果您的用意是要阻止某件事,請使用 exit 2,而不是 1。
還有幾個細節要注意。Exit 2 甚至可以阻擋 Stop,這就是您告訴 Claude 它還沒完成的方式。但 PostToolUse 是在工具已經執行之後才觸發,所以在那裡阻擋已經太遲,無法阻止呼叫本身,不過它仍然可以把文字回饋給 Claude。還有少數事件完全忽略阻擋行為,例如 Notification 和 SessionStart。SessionStart 只會把您的標準錯誤顯示給您自己看,Notification 則會忽略它,而這兩者都會不受影響地繼續進行。
一個實際的防護機制:編修而非阻擋
讓我們用一個實際的例子把這一切串起來。假設您想在 Bash 工具上設置一個 PreToolUse 防護機制。您會在設定檔中註冊一個 hook。把它放進 .claude/settings.json 並提交(commit),這樣您的團隊就能共用它:
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/redact-secrets.sh",
"args": []
}
]
}
]
}
}matcher 用來選定要監看的工具,而 hook 上可選的 if 欄位可以把範圍縮小到特定指令,例如 "if": "Bash(curl *)"。執行 /hooks 來確認該 hook 已經註冊完成。
顯而易見的做法是回傳 deny 並阻止一個危險的呼叫。這樣做很好。但較少人知道、也更有意思的做法,是回傳 updatedInput 來重寫該呼叫。這就是您如何從指令中剝除機密資訊、同時仍然讓它執行的方式,而不是單純地拒絕它。
以下是它在實務上的樣子。Claude 被要求執行一個包含看似真實機密資訊的指令。該 hook 攔截了它,偵測到 sk_live_ 這個模式,並在該指令真正執行之前,把它換成一個佔位符。
這是腳本 .claude/hooks/redact-secrets.sh。它需要用到 jq,而且您要用 chmod +x 讓它可執行:
#!/bin/bash
# 在指令執行前替換看起來像真實金鑰的內容。
jq 'if (.tool_input.command // "" | test("sk_live_\\w+")) then {
hookSpecificOutput: {
hookEventName: "PreToolUse",
permissionDecision: "ask",
permissionDecisionReason: "Replaced a live key with a placeholder",
updatedInput: (.tool_input | .command |= gsub("sk_live_\\w+"; "REDACTED"))
}
} else empty end'它回傳 ask,所以您會核准重寫後的指令。若回傳 allow,則會跳過對每一個符合該模式的指令所做的提示。一旦您核准了它,該指令就會在不含機密資訊的情況下執行。這就是阻擋與編修之間的差異,而這正是 hook 每一次都能強制執行的那種事情。
在壓縮過程中保存狀態
還有一個值得建立的模式。當 Claude 壓縮一段長對話時,它會捨棄大量細節。一個帶有 compact 比對器的 SessionStart hook 會在壓縮完成之後立即執行。讓它印出您一直在處理的檔案的簡短摘要。這份摘要會被送回上下文中,所以 Claude 會從原本停下的地方接續下去,而不是從頭開始。這個範例會列出您尚未提交(commit)的變更:
{
"hooks": {
"SessionStart": [
{
"matcher": "compact",
"hooks": [{ "type": "command", "command": "git status --short" }]
}
]
}
}總結
Hook 把一條 Claude 通常會遵從的規則,變成一條它總是會遵從的規則。把目光放得比自動格式化更遠:用 PreToolUse 來守護工具、用 Stop 來把關回合、並在壓縮過程中保存狀態。這樣的設置需要在一開始付出一點心力,但在它第一次於您根本沒在盯著的執行過程中抓到問題時,就會得到回報。