使用 hooks 自動化工作流程

​

設定您的第一個 hook

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Claude Code needs your attention\" with title \"Claude Code\"'"
          }
        ]
      }
    ]
  }
}

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [{ "type": "command", "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write" }]
      }
    ],
    "Notification": [
      {
        "matcher": "",
        "hooks": [{ "type": "command", "command": "osascript -e 'display notification \"Claude Code needs your attention\" with title \"Claude Code\"'" }]
      }
    ]
  }
}

​

您可以自動化的項目

​

在 Claude 需要輸入時收到通知

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Claude Code needs your attention\" with title \"Claude Code\"'"
          }
        ]
      }
    ]
  }
}

osascript -e 'display notification "test"'

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "notify-send 'Claude Code' 'Claude Code needs your attention'"
          }
        ]
      }
    ]
  }
}

notify-send 'Claude Code' 'test'

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "powershell.exe -Command \"[System.Reflection.Assembly]::LoadWithPartialName('System.Windows.Forms'); [System.Windows.Forms.MessageBox]::Show('Claude Code needs your attention', 'Claude Code')\""
          }
        ]
      }
    ]
  }
}

​

在編輯後自動格式化程式碼

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write"
          }
        ]
      }
    ]
  }
}

​

封鎖對受保護檔案的編輯

#!/bin/bash
# protect-files.sh

INPUT=$(cat)
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')

# Normalize Windows backslash separators so the patterns below match
FILE_PATH="${FILE_PATH//\\//}"

PROTECTED_PATTERNS=(".env" "package-lock.json" ".git/")

for pattern in "${PROTECTED_PATTERNS[@]}"; do
  if [[ "$FILE_PATH" == *"$pattern"* ]]; then
    echo "Blocked: $FILE_PATH matches protected pattern '$pattern'" >&2
    exit 2
  fi
done

exit 0

chmod +x .claude/hooks/protect-files.sh

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/protect-files.sh"
          }
        ]
      }
    ]
  }
}

​

在壓縮後重新注入上下文

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "compact",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'Reminder: use Bun, not npm. Run bun test before committing. Current sprint: auth refactor.'"
          }
        ]
      }
    ]
  }
}

​

稽核設定變更

{
  "hooks": {
    "ConfigChange": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "jq -c '{timestamp: now | todate, source: .source, file: .file_path}' >> ~/claude-config-audit.log"
          }
        ]
      }
    ]
  }
}

​

在目錄或檔案變更時重新載入環境

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "direnv export bash > \"$CLAUDE_ENV_FILE\""
          }
        ]
      }
    ],
    "CwdChanged": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "direnv export bash > \"$CLAUDE_ENV_FILE\""
          }
        ]
      }
    ]
  }
}

{
  "hooks": {
    "FileChanged": [
      {
        "matcher": ".envrc|.env",
        "hooks": [
          {
            "type": "command",
            "command": "direnv export bash > \"$CLAUDE_ENV_FILE\""
          }
        ]
      }
    ]
  }
}

​

自動核准特定權限提示

{
  "hooks": {
    "PermissionRequest": [
      {
        "matcher": "ExitPlanMode",
        "hooks": [
          {
            "type": "command",
            "command": "jq -c '{hookSpecificOutput: {hookEventName: \"PermissionRequest\", decision: {behavior: \"allow\", updatedInput: .tool_input}}}'"
          }
        ]
      }
    ]
  }
}

"command": "jq -c '{hookSpecificOutput: {hookEventName: \"PermissionRequest\", decision: {behavior: \"allow\", updatedInput: .tool_input, updatedPermissions: [{type: \"setMode\", mode: \"acceptEdits\", destination: \"session\"}]}}}'"

​

hooks 如何運作

• "type": "http"：將事件資料 POST 到 URL。請參閱 HTTP hooks。
• "type": "mcp_tool"：在已設定的 MCP 伺服器上呼叫工具。請參閱 MCP tool hooks。
• "type": "prompt"：單輪 LLM 評估。請參閱 Prompt-based hooks。
• "type": "agent"：具有工具存取的多輪驗證。Agent hooks 是實驗性的，可能會變更。請參閱 Agent-based hooks。

​

合併來自多個 hooks 的結果

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r .tool_input.command >> ~/.claude/bash.log"
          },
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/block-rm-rf.sh"
          }
        ]
      }
    ]
  }
}

​

讀取輸入並傳回輸出

​

Hook 輸入

• hook_event_name：觸發 hook 的事件
• tool_name：Claude 即將使用的工具
• tool_input：Claude 傳遞給工具的引數。對於 Bash，其 command 欄位保存 shell 命令。

{
  "session_id": "abc123",
  "cwd": "/Users/sarah/myproject",
  "hook_event_name": "PreToolUse",
  "tool_name": "Bash",
  "tool_input": {
    "command": "npm test"
  }
}

​

Hook 輸出

#!/bin/bash
INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command')

if echo "$COMMAND" | grep -q "drop table"; then
  echo "Blocked: dropping tables is not allowed" >&2  # stderr becomes Claude's feedback
  exit 2 # exit 2 = block the action
fi

exit 0  # exit 0 = no decision; the normal permission flow applies

• 結束代碼 0：如果您從 PreToolUse hook 以結束代碼 0 結束，工具呼叫仍會經過正常的 權限流程，因為結束代碼 0 並不會核准它。對於 UserPromptSubmit、UserPromptExpansion、SessionStart 和 PostModelSwitch hooks，Claude Code 會將其 視為純文字 的 stdout 新增到 Claude 的上下文。
• 結束代碼 2：將原因寫入 stderr。視事件而定，Claude 會將其作為回饋接收以便調整、使用者會看到它，或者不顯示任何訊息（如 ConfigChange 和 Elicitation）。某些事件無法被阻止：對於 SessionStart 和其他事件，結束代碼 2 向使用者顯示 stderr 並繼續執行。請參閱 每個事件的結束代碼 2 行為 以取得完整清單。
• 任何其他結束代碼：關於每個事件的例外情況（例如 WorktreeCreate 在任何非零結束代碼上失敗），請參閱 結束代碼輸出。在其他事件上，除非該 hook 屬於其失敗會阻止動作的類型，請依據您的 hook 印出到 stdout 的內容找出您的情況：
  • 通過 schema 驗證的已解析物件：Claude Code 忽略結束代碼，JSON 單獨決定結果，hook 不會報告為錯誤。
  • 未通過 schema 驗證的已解析物件，或 Claude Code 嘗試解析為 JSON 但不是有效 JSON 的 stdout：動作以非阻止性錯誤繼續進行。請查看 <hook name> hook error 通知中的驗證或解析訊息。
  • Claude Code 視為純文字 的 stdout，或空 stdout：動作以非阻止性錯誤繼續進行。逐字稿顯示 <hook name> hook error 通知，然後是 stderr 的第一行，前綴為 Failed with non-blocking status code:。要擷取完整的 stderr，請使用 claude --debug 或在工作階段中執行 /debug 來啟用 偵錯日誌。

​

結構化 JSON 輸出

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "Use rg instead of grep for better performance"
  }
}

• 從 網路路徑 讀取
• 標記為 requiresUserInteraction 的 MCP 工具
• 呼叫 Agent SDK 應用程式標記為 always_ask 的工具，除非 權限模式核准該呼叫
• 在該設定會傳達到 Claude Code 的工作階段中，您的組織設定為 ask 的連接器工具 關於 "allow" 在 plan mode 中的作用，請參閱 plan mode 中的 hook 核准。

{
  "hookSpecificOutput": {
    "hookEventName": "UserPromptSubmit",
    "additionalContext": "Current branch: release-42. Deploy freeze until Friday."
  }
}

​

使用匹配器篩選 hooks

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "prettier --write ..." }
        ]
      }
    ]
  }
}

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.command' >> ~/.claude/command-log.txt"
          }
        ]
      }
    ]
  }
}

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "mcp__github__.*",
        "hooks": [
          {
            "type": "command",
            "command": "echo \"GitHub tool called: $(jq -r '.tool_name')\" >&2"
          }
        ]
      }
    ]
  }
}

{
  "hooks": {
    "SessionEnd": [
      {
        "matcher": "clear",
        "hooks": [
          {
            "type": "command",
            "command": "rm -f /tmp/claude-scratch-*.txt"
          }
        ]
      }
    ]
  }
}

​

使用 if 欄位按工具名稱和引數篩選

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "if": "Bash(git *)",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/check-git-policy.sh"
          }
        ]
      }
    ]
  }
}

​

設定 hook 位置

​

基於提示的 hooks

• "ok": true：操作繼續
• "ok": false：發生的情況取決於事件：
  • Stop 和 SubagentStop：reason 被回饋給 Claude，以便它繼續工作，除非回應也設定 "impossible": true 以標記該條件為永遠無法滿足的條件，在這種情況下 Claude Code 允許停止並結束回合
  • PreToolUse：工具呼叫被拒絕；預設情況下回合結束，拒絕 reason 在聊天中顯示為警告行。在 hook 上設定 continueOnBlock: true 以改為將 reason 傳回給 Claude 作為工具錯誤，以便它可以調整並繼續
  • PostToolUse：預設情況下回合結束，reason 在聊天中顯示為警告行。設定 continueOnBlock: true 以將 reason 回饋給 Claude 並改為繼續回合
  • PostToolBatch、UserPromptSubmit 和 UserPromptExpansion：回合結束，reason 在聊天中顯示為警告行

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "prompt",
            "prompt": "Check if all tasks are complete. If not, respond with {\"ok\": false, \"reason\": \"what remains to be done\"}."
          }
        ]
      }
    ]
  }
}

​

基於代理的 hooks

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "agent",
            "prompt": "Verify that all unit tests pass. Run the test suite and check the results. $ARGUMENTS",
            "timeout": 120
          }
        ]
      }
    ]
  }
}

​

HTTP hooks

{
  "hooks": {
    "PostToolUse": [
      {
        "hooks": [
          {
            "type": "http",
            "url": "http://localhost:8080/hooks/tool-use",
            "headers": {
              "Authorization": "Bearer $MY_TOKEN"
            },
            "allowedEnvVars": ["MY_TOKEN"]
          }
        ]
      }
    ]
  }
}

• 2xx 狀態：若要阻止工具呼叫，請在主體中傳回適當的 hookSpecificOutput 欄位。
• 任何其他狀態，或請求失敗：Claude Code 會回報非阻斷性錯誤並讓該動作繼續進行。若要讓失敗的端點阻止該動作，請在 hook 上設定 onFailure: "block"。

​

限制和故障排除

​

限制

• 命令 hooks 只透過 stdout、stderr 和退出代碼通訊。它們無法觸發 / 命令或工具呼叫。透過 additionalContext 傳回的文字會作為系統提醒注入，Claude 將其讀取為純文字。HTTP hooks 改為透過回應主體通訊。
• Hook 超時因類型而異。透過 timeout 欄位（以秒為單位）按 hook 覆寫。
  • command、http、mcp_tool：10 分鐘。Claude Code 將 UserPromptSubmit、PreModelSwitch 和 PostModelSwitch hooks 的預設值降低至 30 秒，將 MessageDisplay 的預設值降低至 10 秒。
  • prompt：30 秒。
  • agent：60 秒。
  • SessionEnd hooks 的任何類型共享 1.5 秒的預算。如果您的設定為 hook 設定了更長的 timeout，Claude Code 會將預算提高以匹配，最多 60 秒。
• PostToolUse hooks 無法撤銷操作，因為工具已經執行。
• PermissionRequest hook 在 Claude Code 即將要求您授予權限時觸發，或在它原本會自動拒絕無法顯示提示的呼叫時觸發。在使用 -p 旗標的非互動模式中，它們在 dontAsk 模式以外仍會執行，而沒有任何 hook 做出決策、也沒有其他機制能回應的呼叫會被拒絕。
• Stop hooks 在 Claude 完成回應時觸發，而不僅在任務完成時。它們在使用者中斷時不觸發。API 錯誤觸發 StopFailure 代替。
• 當多個 PreToolUse hook 傳回 updatedInput 以重寫工具的輸入時，Claude Code 不會合併這些重寫，也不保證工具會以哪一個重寫執行。避免有多個 hook 重寫同一工具的輸入。

​

Hooks 和權限模式

• 仍優先於 "allow" 的項目：傳回 "allow" 的 hook 不會繞過來自設定的拒絕規則，也無法抑制以下情況的提示：
  • 從網路路徑讀取
  • 標記為 requiresUserInteraction 的 MCP 工具
  • 對 Agent SDK 應用程式標記為 always_ask 之工具的呼叫，除非權限模式核准該呼叫
  • 在該設定會傳達到 Claude Code 的工作階段中，您的組織設定為 ask 的連接器工具

• "deny" 在每個權限模式中都有效：傳回 permissionDecision: "deny" 的 hook 會阻止工具，即使在 bypassPermissions 模式或使用 --dangerously-skip-permissions 時也是如此。PreToolUse hook 在任何權限模式檢查之前觸發，在每個權限模式中皆然，包括 dontAsk。這讓您能強制執行使用者無法透過變更其權限模式來繞過的原則。

​

Hook 未觸發

• 執行 /hooks 並確認 hook 出現在正確的事件下
• 對於 skill frontmatter 中的 hook，請叫用該 skill 或請 Claude 叫用，然後再次執行 /hooks。/hooks 不會列出工作階段中尚未叫用之 skill 的 hook。如果 /hooks 仍未列出該 hook，請檢查其他原因，例如未能解析的 frontmatter 或其中一項 skill hook 的限制
• 檢查匹配器模式是否與工具名稱完全相符。匹配器區分大小寫
• 驗證您觸發的是正確的事件類型：PreToolUse 在工具執行前觸發，PostToolUse 在之後觸發。PermissionRequest hook 在 Claude Code 即將要求您的權限時觸發；請參閱限制以了解非互動模式的情況

​

Hook 輸出中的錯誤

• 您的指令意外以非零代碼退出。透過管道傳輸範例 JSON 來手動測試它：
  echo '{"tool_name":"Bash","tool_input":{"command":"ls"}}' | ./my-hook.sh
  echo $?  # Check the exit code
  
• 如果您看到「command not found」，使用絕對路徑或 ${CLAUDE_PROJECT_DIR} 來參考指令。為了完全避免 shell 引用，添加 "args": [] 以切換到 exec 形式，它直接生成指令而不使用 shell
• 如果您看到「jq: command not found」，安裝 jq 或使用 Python/Node.js 進行 JSON 解析
• 如果訊息包含 blocking because Git Bash wasn't found，表示您在 Windows 上、Claude Code 找不到 Git Bash，且失敗或逾時的 hook 阻止了工具呼叫。請參閱在沒有 Git Bash 的 Windows 上失敗的 hook 以了解修正方法
• 如果通知顯示 JSON 驗證訊息，您的 hook 的 stdout 解析為 JSON 但未通過架構驗證。如果顯示 JSON 解析訊息，stdout 看起來像 JSON 物件但不是有效的 JSON。即使在退出 0 時也會發生這兩種情況。 要修復解析失敗，使用 JSON 編碼器（例如 jq）而不是字串連接來建立有效負載，以便值內的引號和反斜線被轉義。參考的退出代碼輸出部分涵蓋了退出代碼和 JSON 組合
• 如果指令根本沒有執行，使其可執行：chmod +x ./my-hook.sh

​

/hooks 顯示未配置任何 hooks

• 檔案編輯通常會自動選取。如果在幾秒鐘後仍未出現，檔案監視程式可能已錯過變更：重新啟動您的工作階段以強制重新載入。
• 驗證您的 JSON 有效：不允許尾隨逗號和註解
• 確認設定檔在正確的位置：.claude/settings.json 用於專案 hooks，~/.claude/settings.json 用於全域 hooks
• 如果選單顯示 Only hooks from managed settings run here，表示您的組織已設定 allowManagedHooksOnly。您的使用者、專案和本機設定檔中的 hook 不會執行，也不會列出

​

Stop hook 觸發區塊上限

#!/bin/bash
INPUT=$(cat)
if [ "$(echo "$INPUT" | jq -r '.stop_hook_active')" = "true" ]; then
  exit 0  # Allow Claude to stop
fi
# ... rest of your hook logic

​

Hook JSON 沒有效果

• JSON 前的額外輸出：其他東西首先寫入 stdout，通常是您 shell 設定檔中的無條件 echo，所以輸出不再以 { 開頭。請參閱JSON 前的 shell 設定檔輸出。
• 欄位位置錯誤：將每個欄位的位置與 JSON 輸出格式進行比較。例如，permissionDecision 應該在 hookSpecificOutput 內，而不是在頂層。請參閱位於錯誤層級的欄位。

​

JSON 前的 shell 設定檔輸出

Shell ready on arm64
{"decision": "block", "reason": "Not allowed"}

# 在 ~/.zshrc 或 ~/.bashrc 中
if [[ $- == *i* ]]; then
  echo "Shell ready"
fi

​

位於錯誤層級的欄位

​

檢查 hook 做了什麼

• 成功：您看不到任何內容，除非 hook 的 JSON 顯示某些內容，例如 systemMessage 或 Stop hook 回饋。
  • 要確認 hook 已執行，請檢查其效果，例如重新格式化的檔案
• 阻止錯誤：在大多數事件上，您會看到隨阻止一起傳回的訊息，例如 Blocked: rm commands are not allowed。在少數事件上，例如 ConfigChange 和 Elicitation，您不會看到任何訊息。退出碼 2 說明訊息的來源。
• 非阻止錯誤：您會看到 <hook name> hook error 通知，其中包含簡短說明，例如 Failed with non-blocking status code: 之後的 stderr 第一行，或 JSON 驗證或解析訊息。操作仍會繼續進行。

​

深入瞭解

• Hooks 參考：完整的事件架構、JSON 輸出格式、非同步 hooks 和 MCP 工具 hooks
• 安全考量：在共享或生產環境中部署 hooks 之前進行檢查
• Bash 命令驗證器範例：完整的參考實現