Claude Code Hooks：事件、檢查同錯誤處理點接

Hook 係自動執行嘅程式，要同其他程式一樣驗證

你想 Claude 改完檔案後提醒跑檢查，或者喺特定工具執行前檢查輸入，可以用 hooks。佢唔係另一句 prompt，而係掛喺指定事件嘅處理程序。

先分清事件：PreToolUse 喺工具之前，支援阻止操作；PostToolUse 喺工具成功之後，唔能夠取消已完成動作；Stop 係 Claude 完成一輪回覆，唔係離開程式。對話終止係 SessionEnd。輸入同控制方式要對照官方 hooks 參考。

1. 先做唔改檔案嘅練習

以下示範一個 Bash 工具前檢查：只阻止名叫 HOOK_TEST_BLOCK 嘅無害測試字串，用嚟確認接線，唔係完整危險指令過濾器。

喺專案建立 .claude/hooks/check-bash.py：

import json
import sys

try:
    payload = json.load(sys.stdin)
    command = payload["tool_input"]["command"]
    if not isinstance(command, str):
        raise ValueError("command must be a string")
except (ValueError, KeyError, TypeError) as error:
    print(f"Hook input error: {error}", file=sys.stderr)
    sys.exit(2)

if command == "HOOK_TEST_BLOCK":
    print("Test hook blocked this marker.", file=sys.stderr)
    sys.exit(2)

sys.exit(0)

Bash 指令喺 tool_input.command，唔係最外層 .command。阻擋型錯誤用 exit 2；唔可以假設任何非零退出碼都同樣會阻擋。

2. 先單獨測試，再加入設定

喺專案根目錄試兩個輸入，毋須執行任何破壞性指令：

printf '%s' '{"tool_input":{"command":"HOOK_TEST_BLOCK"}}' | python3 .claude/hooks/check-bash.py
printf '%s' '{"tool_input":{"command":"pwd"}}' | python3 .claude/hooks/check-bash.py

第一個應回傳 2，第二個應回傳 0。再測空輸入、缺欄位、錯誤 JSON，確認唔會默默放行。依賴缺失、路徑錯誤同程式崩潰嘅行為亦要實測，唔好只測正常情況。

合併以下設定入專案 .claude/settings.json，唔好覆寫已有設定：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "python3 \"$CLAUDE_PROJECT_DIR/.claude/hooks/check-bash.py\""
          }
        ]
      }
    ]
  }
}

用 /hooks 檢查已載入設定，再喺受控環境確認工具事件真係觸發。依賴同路徑需按你部機調整，唔好以為寫咗 JSON 就已經生效。

3. 排版同測試點安排

如果要喺改檔案之後處理，matcher 要涵蓋實際工具，例如 Write|Edit。路徑由 tool_input.file_path 取得，先確認屬於允許處理嘅專案同檔案類型，再用專案鎖定版本嘅工具。

初次可以只做格式檢查，唔自動改內容；等結果穩定先考慮排版。自動排版會改變 Claude 啱啱寫完嘅文字，下一次編輯前可能需要重讀檔案。

大型測試唔適合每次改一行都全套執行。可以按檔案揀相關測試，完整檢查留喺明確驗收步驟或 CI。保留真實退出碼，唔好將輸出接去 head 再固定 exit 0，令失敗變成成功。

4. Stop 唔好用嚟亂刪檔案

每輪回覆都可能觸發 Stop，所以唔應喺度遞迴刪除所有 *.tmp。副檔名唔代表可以丟棄，入面可能有其他程序或者使用者需要嘅資料。

Stop hook 如果阻止結束，要處理 stop_hook_active 等事件狀態，避免無限要求 Claude 繼續。清理自己建立嘅暫存檔，應由建立佢嘅腳本負責，並記住精確路徑。

5. 安全檢查要知道邊界

靠正則表達式搜尋 rm -rf，會漏掉不同空格、變數展開、巢狀 shell 或另一種工具，亦可能錯擋正常指令。呢類檢查只能減少某些失誤，唔係安全沙箱。

檔案存取、網絡、憑證同系統權限仍要用對應隔離機制處理。提交前掃描亦應用成熟工具並檢查暫存內容；Claude hook 唔會自動攔住你喺另一個 Terminal 執行嘅 Git 指令。

每加一個 hook，都留低目的、輸入樣本、預期退出碼同停用方法。檢查少而準，比掛滿一套自己都未試過嘅自動化更容易維護。