Developer Advocate Deep Dive

Claude Code Hooks
底層機制與防禦實戰

這是一份不妥協的技術指南。我們將徹底解析 queries.zip 專案中，如何撰寫堅不可摧的 Hooks 來阻擋 Claude 讀取機密檔案。拋棄死板的教學，請直接在下方的模擬器中驗證你的邏輯。

防禦標靶：機密檔案 .env

目標環境中存在 SECRET_API_KEY="SUPER SECRET"。我們的唯一任務，就是實作完美無瑕的 Hook 邏輯，在 Claude 觸碰它之前將其攔截。

1

時機決定命運：Pre vs Post

防護檔案的鐵則：必須在操作發生前攔截。 許多開發者誤用 PostToolUse 紀錄日誌並回傳錯誤碼，卻不知道此時檔案早已被 Claude 讀取完畢。

Hook Lifecycle
Claude Engine
PreToolUse
.env
2

鎖定目標工具：隱蔽的 Grep 與動態 MCP

防禦網的第二步是定義要攔截的 tool_name。除了直覺的 Read，開發者極常漏掉 Grep（搜尋內容等同讀取內容）。另外，由於 MCP Servers 會動態注入工具，最佳實踐是直接透過終端機探測。

Target Tools (Watchlist) High Risk
  • "Read"
    直接讀取指定檔案的所有內容。
  • "Grep"
    搜尋檔案內容。邊緣案例： 若 Claude 搜尋 API_KEY，一樣會把機密回傳給 LLM。
  • "Bash", "Glob", "Edit"...
    (根據需求決定是否攔截)
探測動態工具清單
➜ queries git:(dev) ✗ claude
> 點擊此處自動輸入探測指令
3

解析 Standard In (JSON Payload Diff)

Hook 觸發時，Claude 會將 JSON 資料注入到腳本的 Standard In (stdin)。防禦腳本最常犯的錯就是**沒有正確處理屬性差異**。比較下方 Read 與 Grep 的結構差異。

{
"session_id": "2d6a1e4d-6...",
"hook_event_name": "PreToolUse",
}

你的解析器必須擷取 file_path 來檢查是否為敏感檔案。

4

決策與反饋：防禦腳本編譯與測試實驗室

之前的設計確實違反直覺，因為它把「寫腳本」跟「執行測試」混在一起了！
好的開發者體驗應該是：先設定好你的防禦邏輯 (Script Builder)，再丟入不同的檔案來進行測試 (Test Lab)。

1. 腳本邏輯設定 (Script Builder)
hook_script.sh (即時編譯) Bash
# Extract path from stdin
TARGET_PATH=$(cat - | jq -r '.tool_input.file_path')

if [[ "$TARGET_PATH" == *".env"* ]]; then
echo "Access Denied: .env files are restricted." >&2
exit 2
fi

# Default behavior
exit 0
2. 測試實驗室 (Test Lab)
請選擇模擬輸入檔案：
Claude Context Engine Output
等待測試觸發...