載入中
載入中

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 執行,也就是呼叫程序暫停工具並在之後恢復執行的情況。您很少會用到它。

其結構大致如下:

json
{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "Don't push to main. Open a pull request instead."
  }
}

除了阻擋呼叫之外,您也可以重寫它。回傳 allow 或 ask,並附上 updatedInput。使用 ask 時,您會看到重寫後的呼叫並加以核准。使用 allow 時,它會不經提示直接執行:

json
{
  "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),這樣您的團隊就能共用它:

json
{
  "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 讓它可執行:

bash
#!/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)的變更:

json
{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "compact",
        "hooks": [{ "type": "command", "command": "git status --short" }]
      }
    ]
  }
}

總結

Hook 把一條 Claude 通常會遵從的規則,變成一條它總是會遵從的規則。把目光放得比自動格式化更遠:用 PreToolUse 來守護工具、用 Stop 來把關回合、並在壓縮過程中保存狀態。這樣的設置需要在一開始付出一點心力,但在它第一次於您根本沒在盯著的執行過程中抓到問題時,就會得到回報。