Claude Code 的 hook 預設是 fail-open：腳本不存在、逾時、exit 1，守門員都會放行——v2.1.295 的 onFailure: "block" 怎麼用

很多人把 hook 當成「保證會擋」的安全閘門，但官方 hooks 文件寫得很清楚：只有 exit code 2 能單靠退出碼阻擋動作。其他非零退出碼不會阻擋，只會在 transcript 顯示一行 hook error。這代表守門的腳本一旦壞掉，預設結果是放行。2026 年 10 月 8 日的 v2.1.295 新增了 onFailure: "block"，專門補這個洞。

預設是 fail-open：哪些情況會放行

根據官方 hooks 文件，以下情況對 PreToolUse 都不會阻擋：

• 腳本不存在或不可執行：退出碼像 127，被當成非阻擋錯誤。文件自己警告，settings.json 裡打錯路徑會讓閘門悄悄失效。
• 逾時：command、http、mcp_tool 類 hook 逾時後，工具呼叫照常進入一般權限流程。這幾類的預設 timeout 是 600 秒，prompt hook 是 30 秒，agent hook 是 60 秒。
• 退出碼 1 或其他非零值：一般 Unix 習慣的失敗碼在這裡只是警告，文件要求「要執行規範就用 exit 2」。
• HTTP hook 出問題：非 2xx 狀態、連線失敗、2xx 但內容不是 JSON，全部都是非阻擋錯誤。HTTP hook 光靠狀態碼無法阻擋，必須回傳含決策欄位的 2xx JSON。

v2.1.295 的 onFailure: "block"

更新說明的描述是：command 與 HTTP hook 可以設定成，當 hook 無法啟動、逾時或以非預期的退出碼結束時，改為阻擋動作，而不是放行。Developers Digest 在 10 月 9 日發表的實測用 v2.1.295 的 claude -p 跑了六組設定，只改 PreToolUse hook：沒設定時，腳本不存在和逾時兩種情況都讓指令照樣執行；設成 "onFailure": "block" 後兩者都被擋下，而正常運作的守門腳本仍然放行安全指令。

該文也指出範圍：它只對可以阻擋的事件有意義，例如 PreToolUse、UserPromptSubmit、Stop；prompt、agent 與 MCP tool hook 不在涵蓋範圍內。以下的設定寫法來自該文的範例（我讀到的官方 hooks 文件頁面沒有出現這個鍵，採用前請用官方文件或 claude Plugin validate 再確認）：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/guard.sh",
            "timeout": 5,
            "onFailure": "block"
          }
        ]
      }
    ]
  }
}

守門腳本自己也要 fail-closed

只加 onFailure 不夠。如果腳本是「跑完了，但因為某個指令失敗而以 0 結束」，Claude Code 看到的就是一次成功的放行。Developers Digest 的作者發現，一個沒做錯誤處理的守門腳本，在沒有安裝 jq 的機器上會以 0 結束，等於讓 rm -rf 通過。比較穩的寫法是讓任何非預期的錯誤都以 2 結束。下面是依這個原則寫的示意（比對規則很粗糙，只是為了示範流程）：

#!/usr/bin/env bash
set -euo pipefail
trap 'echo "guard crashed" >&2; exit 2' ERR
cmd=$(jq -r '.tool_input.command')
if printf '%s' "$cmd" | grep -Eq 'rm +-rf +/'; then
  echo "blocked: destructive rm" >&2
  exit 2
fi

這裡的 trap ... ERR 讓 jq 不存在這類失敗直接變成 exit 2；而 if 條件裡的 grep 沒比對到時回傳 1，不會觸發 trap。

不要全部都設成 block

fail-closed 有代價：如果守門用的 HTTP 端點掛了，所有 Bash 呼叫都會被擋；格式化或通知這類方便性 hook 壞掉，也沒有必要卡住整個 session。以下是我的建議，屬於推論，不是官方規範：

• 只對不可逆或可能被惡意利用的動作（刪除、推送、外洩憑證）設 onFailure: "block"。
• 同時設一個短的 timeout。官方預設是 600 秒，一個卡住的守門腳本最多會讓動作等十分鐘。
• regex 守門只是一層，應搭配 sandbox 或 deny 規則。

同一週的相關修正

v2.1.294（10 月 8 日）修正了寫成指示語句的 prompt 與 agent hook（例如「Block commands that…」）會放行本該阻擋的動作；Stop 與 SubagentStop 上的 prompt hook 判斷也改善，Claude 比較不容易提早停下。更早的 v2.1.288 更新說明摘要也提到，PreToolUse hook 因比對失敗而被略過的情形，現在改為阻擋該次呼叫（細節請看原始更新說明）。同一個月內連續出現好幾個「守門沒守住」的修正，值得把自己的 hook 重新驗一次。