Hooks 參考文件

如需包含範例的快速入門指南，請參閱開始使用 Claude Code hooks。

配置

Claude Code hooks 在您的設定檔案中配置：

~/.claude/settings.json - 使用者設定
.claude/settings.json - 專案設定
.claude/settings.local.json - 本地專案設定（不提交）
企業管理政策設定

結構

Hooks 按匹配器組織，每個匹配器可以有多個 hooks：

{
  "hooks": {
    "EventName": [
      {
        "matcher": "ToolPattern",
        "hooks": [
          {
            "type": "command",
            "command": "your-command-here"
          }
        ]
      }
    ]
  }
}

matcher：匹配工具名稱的模式，區分大小寫（僅適用於 PreToolUse 和 PostToolUse）
- 簡單字串精確匹配：Write 僅匹配 Write 工具
- 支援正規表示式：Edit|Write 或 Notebook.*
- 使用 * 匹配所有工具。您也可以使用空字串（""）或將 matcher 留空。
hooks：當模式匹配時要執行的命令陣列
- type：目前僅支援 "command"
- command：要執行的 bash 命令（可以使用 $CLAUDE_PROJECT_DIR 環境變數）
- timeout：（可選）命令應該執行多長時間（以秒為單位），然後取消該特定命令。

對於像 UserPromptSubmit、Notification、Stop 和 SubagentStop 這樣不使用匹配器的事件，您可以省略匹配器欄位：

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/prompt-validator.py"
          }
        ]
      }
    ]
  }
}

專案特定的 Hook 腳本

您可以使用環境變數 CLAUDE_PROJECT_DIR（僅在 Claude Code 生成 hook 命令時可用）來引用儲存在專案中的腳本，確保無論 Claude 的當前目錄如何，它們都能正常工作：

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/check-style.sh"
          }
        ]
      }
    ]
  }
}

Hook 事件

PreToolUse

在 Claude 建立工具參數之後、處理工具呼叫之前執行。

常見匹配器：

Task - 子代理任務（參見子代理文件）
Bash - Shell 命令
Glob - 檔案模式匹配
Grep - 內容搜尋
Read - 檔案讀取
Edit、MultiEdit - 檔案編輯
Write - 檔案寫入
WebFetch、WebSearch - 網路操作

PostToolUse

在工具成功完成後立即執行。

識別與 PreToolUse 相同的匹配器值。

Notification

當 Claude Code 發送通知時執行。通知在以下情況下發送：

Claude 需要您的許可才能使用工具。例如：“Claude needs your permission to use Bash”
提示輸入已閒置至少 60 秒。“Claude is waiting for your input”

UserPromptSubmit

當使用者提交提示時、Claude 處理之前執行。這允許您根據提示/對話添加額外的上下文、驗證提示或阻止某些類型的提示。

Stop

當主要的 Claude Code 代理完成回應時執行。如果停止是由於使用者中斷而發生的，則不會執行。

SubagentStop

當 Claude Code 子代理（Task 工具呼叫）完成回應時執行。

PreCompact

在 Claude Code 即將執行壓縮操作之前執行。

匹配器：

manual - 從 /compact 呼叫
auto - 從自動壓縮呼叫（由於上下文視窗已滿）

SessionStart

當 Claude Code 開始新會話或恢復現有會話時執行（目前確實會在後台開始新會話）。對於載入開發上下文（如現有問題或程式碼庫的最近變更）很有用。

匹配器：

startup - 從啟動呼叫
resume - 從 --resume、--continue 或 /resume 呼叫
clear - 從 /clear 呼叫

Hook 輸入

Hooks 透過 stdin 接收包含會話資訊和事件特定資料的 JSON 資料：

{
  // 通用欄位
  session_id: string
  transcript_path: string  // 對話 JSON 的路徑
  cwd: string              // 呼叫 hook 時的當前工作目錄

  // 事件特定欄位
  hook_event_name: string
  ...
}

PreToolUse 輸入

tool_input 的確切架構取決於工具。

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "PreToolUse",
  "tool_name": "Write",
  "tool_input": {
    "file_path": "/path/to/file.txt",
    "content": "file content"
  }
}

PostToolUse 輸入

tool_input 和 tool_response 的確切架構取決於工具。

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "PostToolUse",
  "tool_name": "Write",
  "tool_input": {
    "file_path": "/path/to/file.txt",
    "content": "file content"
  },
  "tool_response": {
    "filePath": "/path/to/file.txt",
    "success": true
  }
}

Notification 輸入

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "Notification",
  "message": "Task completed successfully"
}

UserPromptSubmit 輸入

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "UserPromptSubmit",
  "prompt": "Write a function to calculate the factorial of a number"
}

Stop 和 SubagentStop 輸入

當 Claude Code 已經因為 stop hook 而繼續時，stop_hook_active 為 true。檢查此值或處理記錄以防止 Claude Code 無限期執行。

{
  "session_id": "abc123",
  "transcript_path": "~/.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "hook_event_name": "Stop",
  "stop_hook_active": true
}

PreCompact 輸入

對於 manual，custom_instructions 來自使用者傳遞給 /compact 的內容。對於 auto，custom_instructions 為空。

{
  "session_id": "abc123",
  "transcript_path": "~/.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "hook_event_name": "PreCompact",
  "trigger": "manual",
  "custom_instructions": ""
}

SessionStart 輸入

{
  "session_id": "abc123",
  "transcript_path": "~/.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "hook_event_name": "SessionStart",
  "source": "startup"
}

Hook 輸出

有兩種方式讓 hooks 將輸出返回給 Claude Code。輸出傳達是否阻止以及應該向 Claude 和使用者顯示的任何回饋。

簡單：退出代碼

Hooks 透過退出代碼、stdout 和 stderr 傳達狀態：

退出代碼 0：成功。stdout 在記錄模式（CTRL-R）中向使用者顯示，除了 UserPromptSubmit 和 SessionStart，其中 stdout 被添加到上下文中。
退出代碼 2：阻止錯誤。stderr 被回饋給 Claude 自動處理。請參閱下面的每個 hook 事件行為。
其他退出代碼：非阻止錯誤。stderr 向使用者顯示，執行繼續。

提醒：如果退出代碼為 0，Claude Code 不會看到 stdout，除了 UserPromptSubmit hook，其中 stdout 被注入為上下文。

退出代碼 2 行為

Hook 事件	行為
`PreToolUse`	阻止工具呼叫，向 Claude 顯示 stderr
`PostToolUse`	向 Claude 顯示 stderr（工具已經執行）
`Notification`	N/A，僅向使用者顯示 stderr
`UserPromptSubmit`	阻止提示處理，清除提示，僅向使用者顯示 stderr
`Stop`	阻止停止，向 Claude 顯示 stderr
`SubagentStop`	阻止停止，向 Claude 子代理顯示 stderr
`PreCompact`	N/A，僅向使用者顯示 stderr
`SessionStart`	N/A，僅向使用者顯示 stderr

進階：JSON 輸出

Hooks 可以在 stdout 中返回結構化 JSON 以獲得更複雜的控制：

通用 JSON 欄位

所有 hook 類型都可以包含這些可選欄位：

{
  "continue": true, // Claude 是否應該在 hook 執行後繼續（預設：true）
  "stopReason": "string" // 當 continue 為 false 時顯示的訊息
  "suppressOutput": true, // 在記錄模式中隱藏 stdout（預設：false）
}

如果 continue 為 false，Claude 在 hooks 執行後停止處理。

對於 PreToolUse，這與 "permissionDecision": "deny" 不同，後者只阻止特定的工具呼叫並向 Claude 提供自動回饋。
對於 PostToolUse，這與 "decision": "block" 不同，後者向 Claude 提供自動回饋。
對於 UserPromptSubmit，這防止提示被處理。
對於 Stop 和 SubagentStop，這優先於任何 "decision": "block" 輸出。
在所有情況下，"continue" = false 優先於任何 "decision": "block" 輸出。

stopReason 伴隨 continue 提供向使用者顯示的原因，不向 Claude 顯示。

`PreToolUse` 決策控制

PreToolUse hooks 可以控制工具呼叫是否繼續。

"allow" 繞過許可系統。permissionDecisionReason 向使用者顯示但不向 Claude 顯示。（已棄用的 "approve" 值 + reason 具有相同行為。）
"deny" 防止工具呼叫執行。permissionDecisionReason 向 Claude 顯示。（"block" 值 + reason 具有相同行為。）
"ask" 要求使用者在 UI 中確認工具呼叫。permissionDecisionReason 向使用者顯示但不向 Claude 顯示。

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "allow" | "deny" | "ask",
    "permissionDecisionReason": "My reason here (shown to user)"
  },
  "decision": "approve" | "block" | undefined, // 對 PreToolUse 已棄用但仍支援
  "reason": "Explanation for decision" // 對 PreToolUse 已棄用但仍支援
}

`PostToolUse` 決策控制

PostToolUse hooks 可以控制工具呼叫是否繼續。

"block" 自動提示 Claude 使用 reason。
undefined 什麼都不做。reason 被忽略。

{
  "decision": "block" | undefined,
  "reason": "Explanation for decision"
}

`UserPromptSubmit` 決策控制

UserPromptSubmit hooks 可以控制使用者提示是否被處理。

"block" 防止提示被處理。提交的提示從上下文中清除。"reason" 向使用者顯示但不添加到上下文中。
undefined 允許提示正常進行。"reason" 被忽略。
"hookSpecificOutput.additionalContext" 如果未被阻止，將字串添加到上下文中。

{
  "decision": "block" | undefined,
  "reason": "Explanation for decision",
  "hookSpecificOutput": {
    "hookEventName": "UserPromptSubmit",
    "additionalContext": "My additional context here"
  }
}

`Stop`/`SubagentStop` 決策控制

Stop 和 SubagentStop hooks 可以控制 Claude 是否必須繼續。

"block" 防止 Claude 停止。您必須填充 reason 讓 Claude 知道如何繼續。
undefined 允許 Claude 停止。reason 被忽略。

{
  "decision": "block" | undefined,
  "reason": "Must be provided when Claude is blocked from stopping"
}

`SessionStart` 決策控制

SessionStart hooks 允許您在會話開始時載入上下文。

"hookSpecificOutput.additionalContext" 將字串添加到上下文中。

{
  "hookSpecificOutput": {
    "hookEventName": "SessionStart",
    "additionalContext": "My additional context here"
  }
}

退出代碼範例：Bash 命令驗證

#!/usr/bin/env python3
import json
import re
import sys

# Define validation rules as a list of (regex pattern, message) tuples
VALIDATION_RULES = [
    (
        r"\bgrep\b(?!.*\|)",
        "Use 'rg' (ripgrep) instead of 'grep' for better performance and features",
    ),
    (
        r"\bfind\s+\S+\s+-name\b",
        "Use 'rg --files | rg pattern' or 'rg --files -g pattern' instead of 'find -name' for better performance",
    ),
]


def validate_command(command: str) -> list[str]:
    issues = []
    for pattern, message in VALIDATION_RULES:
        if re.search(pattern, command):
            issues.append(message)
    return issues


try:
    input_data = json.load(sys.stdin)
except json.JSONDecodeError as e:
    print(f"Error: Invalid JSON input: {e}", file=sys.stderr)
    sys.exit(1)

tool_name = input_data.get("tool_name", "")
tool_input = input_data.get("tool_input", {})
command = tool_input.get("command", "")

if tool_name != "Bash" or not command:
    sys.exit(1)

# Validate the command
issues = validate_command(command)

if issues:
    for message in issues:
        print(f"• {message}", file=sys.stderr)
    # Exit code 2 blocks tool call and shows stderr to Claude
    sys.exit(2)

JSON 輸出範例：UserPromptSubmit 添加上下文和驗證

對於 UserPromptSubmit hooks，您可以使用任一方法注入上下文：

退出代碼 0 與 stdout：Claude 看到上下文（UserPromptSubmit 的特殊情況）
JSON 輸出：提供對行為的更多控制

#!/usr/bin/env python3
import json
import sys
import re
import datetime

# Load input from stdin
try:
    input_data = json.load(sys.stdin)
except json.JSONDecodeError as e:
    print(f"Error: Invalid JSON input: {e}", file=sys.stderr)
    sys.exit(1)

prompt = input_data.get("prompt", "")

# Check for sensitive patterns
sensitive_patterns = [
    (r"(?i)\b(password|secret|key|token)\s*[:=]", "Prompt contains potential secrets"),
]

for pattern, message in sensitive_patterns:
    if re.search(pattern, prompt):
        # Use JSON output to block with a specific reason
        output = {
            "decision": "block",
            "reason": f"Security policy violation: {message}. Please rephrase your request without sensitive information."
        }
        print(json.dumps(output))
        sys.exit(0)

# Add current time to context
context = f"Current time: {datetime.datetime.now()}"
print(context)

"""
The following is also equivalent:
print(json.dumps({
  "hookSpecificOutput": {
    "hookEventName": "UserPromptSubmit",
    "additionalContext": context,
  },
}))
"""

# Allow the prompt to proceed with the additional context
sys.exit(0)

JSON 輸出範例：PreToolUse 與批准

#!/usr/bin/env python3
import json
import sys

# Load input from stdin
try:
    input_data = json.load(sys.stdin)
except json.JSONDecodeError as e:
    print(f"Error: Invalid JSON input: {e}", file=sys.stderr)
    sys.exit(1)

tool_name = input_data.get("tool_name", "")
tool_input = input_data.get("tool_input", {})

# Example: Auto-approve file reads for documentation files
if tool_name == "Read":
    file_path = tool_input.get("file_path", "")
    if file_path.endswith((".md", ".mdx", ".txt", ".json")):
        # Use JSON output to auto-approve the tool call
        output = {
            "decision": "approve",
            "reason": "Documentation file auto-approved",
            "suppressOutput": True  # Don't show in transcript mode
        }
        print(json.dumps(output))
        sys.exit(0)

# For other cases, let the normal permission flow proceed
sys.exit(0)

使用 MCP 工具

Claude Code hooks 與模型上下文協定（MCP）工具無縫協作。當 MCP 伺服器提供工具時，它們會以特殊的命名模式出現，您可以在 hooks 中匹配。

MCP 工具命名

MCP 工具遵循模式 mcp__<server>__<tool>，例如：

mcp__memory__create_entities - Memory 伺服器的建立實體工具
mcp__filesystem__read_file - Filesystem 伺服器的讀取檔案工具
mcp__github__search_repositories - GitHub 伺服器的搜尋工具

為 MCP 工具配置 Hooks

您可以針對特定的 MCP 工具或整個 MCP 伺服器：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "mcp__memory__.*",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'Memory operation initiated' >> ~/mcp-operations.log"
          }
        ]
      },
      {
        "matcher": "mcp__.*__write.*",
        "hooks": [
          {
            "type": "command",
            "command": "/home/user/scripts/validate-mcp-write.py"
          }
        ]
      }
    ]
  }
}

範例

如需包括程式碼格式化、通知和檔案保護的實用範例，請參閱入門指南中的更多範例。

安全考量

免責聲明

使用風險自負：Claude Code hooks 會在您的系統上自動執行任意 shell 命令。透過使用 hooks，您承認：

您對配置的命令負全責
Hooks 可以修改、刪除或存取您的使用者帳戶可以存取的任何檔案
惡意或編寫不當的 hooks 可能導致資料遺失或系統損壞
Anthropic 不提供保證，對於因使用 hook 而導致的任何損害不承擔責任
您應該在生產使用之前在安全環境中徹底測試 hooks

在將任何 hook 命令添加到您的配置之前，請務必檢查並理解它們。

安全最佳實踐

以下是編寫更安全 hooks 的一些關鍵實踐：

驗證和清理輸入 - 永遠不要盲目信任輸入資料
總是引用 shell 變數 - 使用 "$VAR" 而不是 $VAR
阻止路徑遍歷 - 檢查檔案路徑中的 ..
使用絕對路徑 - 為腳本指定完整路徑（使用 $CLAUDE_PROJECT_DIR 作為專案路徑）
跳過敏感檔案 - 避免 .env、.git/、金鑰等

配置安全

對設定檔案中 hooks 的直接編輯不會立即生效。Claude Code：

在啟動時擷取 hooks 的快照
在整個會話中使用此快照
如果 hooks 被外部修改則發出警告
需要在 /hooks 選單中檢查才能應用變更

這防止惡意的 hook 修改影響您當前的會話。

Hook 執行詳細資訊

超時：預設 60 秒執行限制，每個命令可配置。
- 個別命令的超時不會影響其他命令。
並行化：所有匹配的 hooks 並行執行
環境：在當前目錄中使用 Claude Code 的環境執行
- CLAUDE_PROJECT_DIR 環境變數可用，包含專案根目錄的絕對路徑
輸入：透過 stdin 的 JSON
輸出：
- PreToolUse/PostToolUse/Stop：在記錄中顯示進度（Ctrl-R）
- Notification：僅記錄到除錯（--debug）

除錯

基本故障排除

如果您的 hooks 不工作：

檢查配置 - 執行 /hooks 查看您的 hook 是否已註冊
驗證語法 - 確保您的 JSON 設定有效
測試命令 - 首先手動執行 hook 命令
檢查權限 - 確保腳本可執行
檢查日誌 - 使用 claude --debug 查看 hook 執行詳細資訊

常見問題：

引號未轉義 - 在 JSON 字串內使用 \"
錯誤的匹配器 - 檢查工具名稱完全匹配（區分大小寫）
找不到命令 - 為腳本使用完整路徑

進階除錯

對於複雜的 hook 問題：

檢查 hook 執行 - 使用 claude --debug 查看詳細的 hook 執行
驗證 JSON 架構 - 使用外部工具測試 hook 輸入/輸出
檢查環境變數 - 驗證 Claude Code 的環境是否正確
測試邊緣情況 - 嘗試使用不尋常的檔案路徑或輸入的 hooks
監控系統資源 - 檢查 hook 執行期間的資源耗盡
使用結構化日誌 - 在您的 hook 腳本中實作日誌記錄

除錯輸出範例

使用 claude --debug 查看 hook 執行詳細資訊：

[DEBUG] Executing hooks for PostToolUse:Write
[DEBUG] Getting matching hook commands for PostToolUse with query: Write
[DEBUG] Found 1 hook matchers in settings
[DEBUG] Matched 1 hooks for query "Write"
[DEBUG] Found 1 hook commands to execute
[DEBUG] Executing hook command: <Your command> with timeout 60000ms
[DEBUG] Hook command completed with status 0: <Your stdout>

進度訊息出現在記錄模式（Ctrl-R）中，顯示：

正在執行哪個 hook
正在執行的命令
成功/失敗狀態
輸出或錯誤訊息

開始使用

使用 Claude Code 建構

部署

管理

配置

參考

資源

​配置

​結構

​專案特定的 Hook 腳本

​Hook 事件

​PreToolUse

​PostToolUse

​Notification

​UserPromptSubmit

​Stop

​SubagentStop

​PreCompact

​SessionStart

​Hook 輸入

​PreToolUse 輸入

​PostToolUse 輸入

​Notification 輸入

​UserPromptSubmit 輸入

​Stop 和 SubagentStop 輸入

​PreCompact 輸入

​SessionStart 輸入

​Hook 輸出

​簡單：退出代碼

​退出代碼 2 行為

​進階：JSON 輸出

​通用 JSON 欄位

​PreToolUse 決策控制

​PostToolUse 決策控制

​UserPromptSubmit 決策控制

​Stop/SubagentStop 決策控制

​SessionStart 決策控制

​退出代碼範例：Bash 命令驗證

​JSON 輸出範例：UserPromptSubmit 添加上下文和驗證

​JSON 輸出範例：PreToolUse 與批准

​使用 MCP 工具

​MCP 工具命名

​為 MCP 工具配置 Hooks

​範例

​安全考量

​免責聲明

​安全最佳實踐

​配置安全

​Hook 執行詳細資訊

​除錯

​基本故障排除

​進階除錯

​除錯輸出範例

配置

結構

專案特定的 Hook 腳本

Hook 事件

PreToolUse

PostToolUse

Notification

UserPromptSubmit

Stop

SubagentStop

PreCompact

SessionStart

Hook 輸入

PreToolUse 輸入

PostToolUse 輸入

Notification 輸入

UserPromptSubmit 輸入

Stop 和 SubagentStop 輸入

PreCompact 輸入

SessionStart 輸入

Hook 輸出

簡單：退出代碼

退出代碼 2 行為

進階：JSON 輸出

通用 JSON 欄位

`PreToolUse` 決策控制

`PostToolUse` 決策控制

`UserPromptSubmit` 決策控制

`Stop`/`SubagentStop` 決策控制

`SessionStart` 決策控制

退出代碼範例：Bash 命令驗證

JSON 輸出範例：UserPromptSubmit 添加上下文和驗證

JSON 輸出範例：PreToolUse 與批准

使用 MCP 工具

MCP 工具命名

為 MCP 工具配置 Hooks

範例

安全考量

免責聲明

安全最佳實踐

配置安全

Hook 執行詳細資訊

除錯

基本故障排除

進階除錯

除錯輸出範例