钩子参考

本页面提供了在 Claude Code 中实现钩子的参考文档。 💡 提示：> 有关带示例的快速入门指南，请参阅Claude Code 钩子入门。

配置

Claude Code 钩子在您的设置文件中配置：

~/.claude/settings.json - 用户设置
.claude/settings.json - 项目设置
.claude/settings.local.json - 本地项目设置（不提交）
企业管理策略设置

结构

钩子按匹配器组织，每个匹配器可以有多个钩子： json

{
"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 这样不使用匹配器的事件，您可以省略匹配器字段： json

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

项目特定的钩子脚本

您可以使用环境变量 CLAUDE_PROJECT_DIR（仅在 Claude Code 生成钩子命令时可用）来引用存储在项目中的脚本，确保无论 Claude 的当前目录如何，它们都能正常工作： json

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

钩子事件

PreToolUse

在 Claude 创建工具参数之后、处理工具调用之前运行。 常见匹配器：

Task - 子代理任务（参见子代理文档）
Bash - Shell 命令
Glob - 文件模式匹配
Grep - 内容搜索
Read - 文件读取
Edit、MultiEdit - 文件编辑
Write - 文件写入
WebFetch、WebSearch - Web 操作

PostToolUse

在工具成功完成后立即运行。识别与 PreToolUse 相同的匹配器值。

Notification

当 Claude Code 发送通知时运行。通知在以下情况下发送：

Claude 需要您的权限来使用工具。例如："Claude 需要您的权限来使用 Bash"
提示输入已空闲至少 60 秒。"Claude 正在等待您的输入"

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 调用

钩子输入

钩子通过 stdin 接收包含会话信息和事件特定数据的 JSON 数据： typescript

{
// 公共字段
session_id: string
transcript_path: string  // 对话 JSON 的路径
cwd: string              // 调用钩子时的当前工作目录
// 事件特定字段
hook_event_name: string
...
}

PreToolUse 输入

tool_input 的确切模式取决于工具。 json

{
"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 的确切模式取决于工具。 json

{
"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 输入

json

{
"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 输入

json

{
"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_active 为 true。检查此值或处理记录以防止 Claude Code 无限运行。 json

{
"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 为空。 json

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

SessionStart 输入

json

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

钩子输出

钩子有两种方式将输出返回给 Claude Code。输出传达是否阻止以及应该向 Claude 和用户显示的任何反馈。

简单：退出代码

钩子通过退出代码、stdout 和 stderr 传达状态：

退出代码 0：成功。stdout 在记录模式（CTRL-R）中向用户显示，除了 UserPromptSubmit 和 SessionStart，其中 stdout 被添加到上下文中。
退出代码 2：阻塞错误。stderr 被反馈给 Claude 自动处理。请参阅下面的每个钩子事件行为。
其他退出代码：非阻塞错误。stderr 向用户显示，执行继续。

⚠️ 警告：提醒：如果退出代码为 0，Claude Code 不会看到 stdout，除了 UserPromptSubmit 钩子，其中 stdout 被注入为上下文。

退出代码 2 行为

钩子事件行为 PreToolUse 阻止工具调用，向 Claude 显示 stderr PostToolUse 向 Claude 显示 stderr（工具已运行） Notification 不适用，仅向用户显示 stderr UserPromptSubmit 阻止提示处理，擦除提示，仅向用户显示 stderr Stop 阻止停止，向 Claude 显示 stderr SubagentStop 阻止停止，向 Claude 子代理显示 stderr PreCompact 不适用，仅向用户显示 stderr SessionStart 不适用，仅向用户显示 stderr

高级：JSON 输出

钩子可以在 stdout 中返回结构化 JSON 以获得更复杂的控制：

通用 JSON 字段

所有钩子类型都可以包含这些可选字段： json

{
"continue": true, // Claude 是否应在钩子执行后继续（默认：true）
"stopReason": "string" // 当 continue 为 false 时显示的消息
"suppressOutput": true, // 在记录模式中隐藏 stdout（默认：false）
}

如果 continue 为 false，Claude 在钩子运行后停止处理。

对于 PreToolUse，这与 "permissionDecision": "deny" 不同，后者只阻止特定的工具调用并向 Claude 提供自动反馈。
对于 PostToolUse，这与 "decision": "block" 不同，后者向 Claude 提供自动反馈。
对于 UserPromptSubmit，这防止提示被处理。
对于 Stop 和 SubagentStop，这优先于任何 "decision": "block" 输出。
在所有情况下，"continue" = false 优先于任何 "decision": "block" 输出。 stopReason 伴随 continue 提供向用户显示的原因，不向 Claude 显示。

PreToolUse 决策控制

PreToolUse 钩子可以控制工具调用是否继续。

"allow" 绕过权限系统。permissionDecisionReason 向用户显示但不向 Claude 显示。（已弃用的 "approve" 值 + reason 具有相同行为。）
"deny" 防止工具调用执行。permissionDecisionReason 向 Claude 显示。（"block" 值 + reason 具有相同行为。）
"ask" 要求用户在 UI 中确认工具调用。permissionDecisionReason 向用户显示但不向 Claude 显示。 json

{
"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 钩子可以控制工具调用是否继续。

"block" 自动用 reason 提示 Claude。
undefined 什么都不做。reason 被忽略。 json

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

UserPromptSubmit 决策控制

UserPromptSubmit 钩子可以控制用户提示是否被处理。

"block" 防止提示被处理。提交的提示从上下文中擦除。"reason" 向用户显示但不添加到上下文中。
undefined 允许提示正常进行。"reason" 被忽略。
"hookSpecificOutput.additionalContext" 如果未被阻止，将字符串添加到上下文中。 json

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

Stop/SubagentStop 决策控制

Stop 和 SubagentStop 钩子可以控制 Claude 是否必须继续。

"block" 防止 Claude 停止。您必须填充 reason 让 Claude 知道如何继续。
undefined 允许 Claude 停止。reason 被忽略。 json

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

SessionStart 决策控制

SessionStart 钩子允许您在会话开始时加载上下文。

"hookSpecificOutput.additionalContext" 将字符串添加到上下文中。 json

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

退出代码示例：Bash 命令验证

python

#!/usr/bin/env python3
import json
import re
import sys
# 将验证规则定义为（正则表达式模式，消息）元组列表
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)
# 验证命令
issues = validate_command(command)
if issues:
for message in issues:
print(f"• {message}", file=sys.stderr)
# 退出代码 2 阻止工具调用并向 Claude 显示 stderr
sys.exit(2)

JSON 输出示例：UserPromptSubmit 添加上下文和验证

ℹ️ 注意：对于 UserPromptSubmit 钩子，您可以使用任一方法注入上下文：

退出代码 0 与 stdout：Claude 看到上下文（UserPromptSubmit 的特殊情况）
JSON 输出：提供对行为的更多控制 python

#!/usr/bin/env python3
import json
import sys
import re
import datetime
# 从 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", "")
# 检查敏感模式
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):
# 使用 JSON 输出以特定原因阻止
output = {
"decision": "block",
"reason": f"Security policy violation: {message}. Please rephrase your request without sensitive information."
}
print(json.dumps(output))
sys.exit(0)
# 将当前时间添加到上下文
context = f"Current time: {datetime.datetime.now()}"
print(context)
"""
以下也是等效的：
print(json.dumps({
"hookSpecificOutput": {
"hookEventName": "UserPromptSubmit",
"additionalContext": context,
},
}))
"""
# 允许提示继续进行，带有额外的上下文
sys.exit(0)

JSON 输出示例：PreToolUse 与批准

python

#!/usr/bin/env python3
import json
import sys
# 从 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", {})
# 示例：自动批准文档文件的文件读取
if tool_name == "Read":
file_path = tool_input.get("file_path", "")
if file_path.endswith((".md", ".mdx", ".txt", ".json")):
# 使用 JSON 输出自动批准工具调用
output = {
"decision": "approve",
"reason": "Documentation file auto-approved",
"suppressOutput": True  # 不在记录模式中显示
}
print(json.dumps(output))
sys.exit(0)
# 对于其他情况，让正常的权限流程继续
sys.exit(0)

使用 MCP 工具

Claude Code 钩子与模型上下文协议（MCP）工具无缝协作。当 MCP 服务器提供工具时，它们以特殊的命名模式出现，您可以在钩子中匹配。

MCP 工具命名

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

mcp__memory__create_entities - Memory 服务器的创建实体工具
mcp__filesystem__read_file - Filesystem 服务器的读取文件工具
mcp__github__search_repositories - GitHub 服务器的搜索工具

为 MCP 工具配置钩子

您可以针对特定的 MCP 工具或整个 MCP 服务器： json

{
"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 钩子会在您的系统上自动执行任意 shell 命令。通过使用钩子，您承认：

您对配置的命令负全部责任
钩子可以修改、删除或访问您的用户帐户可以访问的任何文件
恶意或编写不当的钩子可能导致数据丢失或系统损坏
Anthropic 不提供任何保证，并且对因使用钩子而导致的任何损害不承担任何责任
您应该在生产使用之前在安全环境中彻底测试钩子在将任何钩子命令添加到配置之前，请始终审查和理解它们。

安全最佳实践

以下是编写更安全钩子的一些关键实践：

验证和清理输入 - 永远不要盲目信任输入数据
始终引用 shell 变量 - 使用 "$VAR" 而不是 $VAR
阻止路径遍历 - 检查文件路径中的 ..
使用绝对路径 - 为脚本指定完整路径（使用 $CLAUDE_PROJECT_DIR 作为项目路径）
跳过敏感文件 - 避免 .env、.git/、密钥等

配置安全

对设置文件中钩子的直接编辑不会立即生效。Claude Code：

在启动时捕获钩子的快照
在整个会话中使用此快照
如果钩子被外部修改则发出警告
需要在 /hooks 菜单中审查更改才能应用这防止恶意钩子修改影响您当前的会话。

钩子执行详细信息

超时：默认 60 秒执行限制，每个命令可配置。
单个命令的超时不会影响其他命令。
并行化：所有匹配的钩子并行运行
环境：在当前目录中运行，使用 Claude Code 的环境
CLAUDE_PROJECT_DIR 环境变量可用，包含项目根目录的绝对路径
输入：通过 stdin 的 JSON
输出：
PreToolUse/PostToolUse/Stop：在记录中显示进度（Ctrl-R）
Notification：仅记录到调试（--debug）

调试

基本故障排除

如果您的钩子不工作：

检查配置 - 运行 /hooks 查看您的钩子是否已注册
验证语法 - 确保您的 JSON 设置有效
测试命令 - 首先手动运行钩子命令
检查权限 - 确保脚本可执行
查看日志 - 使用 claude --debug 查看钩子执行详细信息常见问题：

引号未转义 - 在 JSON 字符串内使用 \"
错误的匹配器 - 检查工具名称完全匹配（区分大小写）
找不到命令 - 为脚本使用完整路径

高级调试

对于复杂的钩子问题：

检查钩子执行 - 使用 claude --debug 查看详细的钩子执行
验证 JSON 模式 - 使用外部工具测试钩子输入/输出
检查环境变量 - 验证 Claude Code 的环境是否正确
测试边缘情况 - 尝试使用异常文件路径或输入的钩子
监控系统资源 - 检查钩子执行期间的资源耗尽
使用结构化日志记录 - 在钩子脚本中实现日志记录

调试输出示例

使用 claude --debug 查看钩子执行详细信息：

[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）中，显示：

哪个钩子正在运行
正在执行的命令
成功/失败状态
输出或错误消息

钩子参考 ​

配置 ​

结构 ​

项目特定的钩子脚本 ​

钩子事件 ​

PreToolUse ​

PostToolUse ​

Notification ​

UserPromptSubmit ​

Stop ​

SubagentStop ​

PreCompact ​

SessionStart ​

钩子输入 ​

PreToolUse 输入 ​

PostToolUse 输入 ​

Notification 输入 ​

UserPromptSubmit 输入 ​

Stop 和 SubagentStop 输入 ​

PreCompact 输入 ​

SessionStart 输入 ​

钩子输出 ​

简单：退出代码 ​

退出代码 2 行为 ​

高级：JSON 输出 ​

通用 JSON 字段 ​

PreToolUse 决策控制 ​

PostToolUse 决策控制 ​

UserPromptSubmit 决策控制 ​

Stop/SubagentStop 决策控制 ​

SessionStart 决策控制 ​

退出代码示例：Bash 命令验证 ​

JSON 输出示例：UserPromptSubmit 添加上下文和验证 ​

JSON 输出示例：PreToolUse 与批准 ​

使用 MCP 工具 ​

MCP 工具命名 ​

为 MCP 工具配置钩子 ​

示例 ​

安全考虑 ​

免责声明 ​

安全最佳实践 ​

配置安全 ​

钩子执行详细信息 ​

调试 ​

基本故障排除 ​

高级调试 ​

调试输出示例 ​

钩子参考

配置

结构

项目特定的钩子脚本

钩子事件

PreToolUse

PostToolUse

Notification

UserPromptSubmit

Stop

SubagentStop

PreCompact

SessionStart

钩子输入

PreToolUse 输入

PostToolUse 输入

Notification 输入

UserPromptSubmit 输入

Stop 和 SubagentStop 输入

PreCompact 输入

SessionStart 输入

钩子输出

简单：退出代码

退出代码 2 行为

高级：JSON 输出

通用 JSON 字段

PreToolUse 决策控制

PostToolUse 决策控制

UserPromptSubmit 决策控制

Stop/SubagentStop 决策控制

SessionStart 决策控制

退出代码示例：Bash 命令验证

JSON 输出示例：UserPromptSubmit 添加上下文和验证

JSON 输出示例：PreToolUse 与批准

使用 MCP 工具

MCP 工具命名

为 MCP 工具配置钩子

示例

安全考虑

免责声明

安全最佳实践

配置安全

钩子执行详细信息

调试

基本故障排除

高级调试

调试输出示例