Claude Code 要讀取敏感檔案前：用 PreToolUse hook 多加一道阻擋規則

先把敏感資訊和一般設定檔分開#

不要用一條模糊規則，例如「不要讀機密」。先列出目前專案不應交給 agent 的實體目標，再決定是否需要搬離 repository。

最重要的判斷是：hook 只能降低誤觸機率，不能把已經提交到 Git 的 secret 變回安全資料。 若真實憑證已經進入版本控制，先撤銷與輪替它，再處理歷史與存放位置。

PreToolUse hook 能做什麼#

Claude Code 官方文件說明，PreToolUse 會在工具呼叫前觸發；hook 可讀取送到 stdin 的 JSON，並回傳 permissionDecision: "deny" 來拒絕該呼叫。這適合用來處理明確、可比對的禁止條件。

先在專案建立 .claude/hooks/block-sensitive-access.sh：

1
#!/usr/bin/env bash
2
set -euo pipefail
3

4
input="$(cat)"
5
tool_name="$(printf '%s' "$input" | jq -r '.tool_name // ""')"
6

7
# Read、Glob、Grep 的路徑欄位不同；把可取得值集中後再比對。
8
target="$(printf '%s' "$input" | jq -r '
9
  .tool_input.file_path //
10
  .tool_input.path //
11
  .tool_input.pattern //
12
  .tool_input.command // ""
13
')"
14

15
if [[ "$target" =~ (^|/)(\.env|\.env\..+|id_rsa|id_ed25519|.*\.pem|.*\.key)($|/) ]] \
16
  || [[ "$target" =~ (cat|sed|awk|grep)[[:space:]].*(\.env|id_rsa|id_ed25519|\.pem|\.key) ]]; then
17
  jq -n --arg reason "Sensitive file access is blocked by this project hook" '{
18
    hookSpecificOutput: {
19
      hookEventName: "PreToolUse",
20
      permissionDecision: "deny",
21
      permissionDecisionReason: $reason
22
    }
23
  }'
24
  exit 0
25
fi
26

27
# 沒有決策時，Claude Code 會走既有的 permission 流程。
28
exit 0

這個範例刻意不把 .env.example 納入阻擋，也不嘗試猜測所有 secret 格式。先用小而可檢查的名單，避免規則過度寬鬆而讓日常工作完全無法進行。

在專案設定中只匹配需要攔的工具#

接著將 hook 放進 .claude/settings.json。官方文件支援在這個檔案定義 project scope 的 hook，因此團隊可以和程式碼一起 review 規則。

1
{
2
  "hooks": {
3
    "PreToolUse": [
4
      {
5
        "matcher": "Read|Glob|Grep|Bash",
6
        "hooks": [
7
          {
8
            "type": "command",
9
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-sensitive-access.sh"
10
          }
11
        ]
12
      }
13
    ]
14
  }
15
}

matcher 的作用是決定什麼工具會觸發 handler；它不是萬用的存取控制清單。對 Bash 而言，請把 hook 視為額外檢查，並用 Claude Code 的權限規則限制可執行命令，不要把所有安全假設都押在一段正規表示式上。

先用安全的測試案例驗證它真的會拒絕#

設定完成後，請在測試 repository 或不含真實 secret 的檔案上檢查。可先建立假資料：

1
mkdir -p /tmp/claude-hook-check
2
printf 'DEMO_TOKEN=not-a-real-secret\n' > /tmp/claude-hook-check/.env

在該目錄啟動 Claude Code，要求它讀取 .env；預期結果是拒絕原因顯示在工作階段中。再讓它讀取 README.md 或 .env.example，確認正常工具呼叫沒有被誤攔。

如果規則沒有生效，先檢查三件事：hook 檔案能否執行、.claude/settings.json 是否為有效 JSON、Claude Code 是否在該 project root 啟動。不要先把 matcher 擴成 .*；先知道是哪一層沒有載入，才能避免新增大量無關攔截。

hook、權限與 secret store 各自解決不同問題#

實務上我會先把憑證移到正確的存放位置，再在 project settings 放 hook，最後用最小權限執行 agent。順序不能倒過來：一個漂亮的 hook，補不了散落在 Git 歷史和工作目錄裡的 token。

這次要記住的事#

Claude Code 的 hook 最適合把少數明確的禁區自動化，而不是假裝它能辨識所有機密。先列出禁止讀取的檔案與命令、在測試資料上驗證拒絕行為，再配合 secret store 與權限設定，才會形成真正可維護的防線。

常見問題#