Claude Code Hooks 类型与使用指南实践整理

作者：袖梨 2026-08-19

平时做技术实践时，很多问题不是概念不会，而是细节没串起来。拿“Claude Code Hooks 类型与使用指南”来说，它看着像小点，放到项目里常会牵出环境、配置、兼容性和维护成本。下面按实际使用顺序，把思路、关键写法和容易踩坑的地方讲清楚，方便你直接对照操作。

在这个场景下，本文总结 Claude Code / 本仓库恢复版 claude-code 中 hooks 的类型、触发时机、典型采用场景、设置方式与注意事项。

从实现思路看，Hooks 是 Claude Code 在会话、工具调用、权限、压缩、子代理、任务等生命周期节点执行的自定义动作。它们适合做自动校验、权限治理、日志审计、上下文注入、格式化、通知和资源清理。

0. 整体流程图

整体流转可以理解为：会话启动后触发 SessionStart；用户提交 prompt 后、Claude 处理前触发 UserPromptSubmit；Claude 推理中如果要调用工具，先在权限弹窗前触发 PermissionRequest，再在工具真正执行前触发 PreToolUse；工具成功后触发 PostToolUse，失败后触发 PostToolUseFailure，权限被拒绝后触发 PermissionDenied；子代理、上下文压缩、通知和任务事件会在各自生命周期点触发；最后在回复结束前触发 Stop，会话退出时触发 SessionEnd。

1. 设置位置

作用域	设置文件或来源	适用场景	是否建议提交到仓库
用户级	~/.claude/settings.json	个人通用习惯，比如所有项目都禁止危险 Bash 命令	否
项目级	.claude/settings.json	团队共享规则，比如项目统一 formatter、lint、测试钩子	是
项目本地级	.claude/settings.local.json	个人在当前项目的本地设置，比如本机路径、本地通知脚本	否
插件级	~/.claude/plugins/*/hooks/hooks.json	由插件提供的通用 hook 能力	否
会话级	运行时内存注册	临时 hook，随会话结束清除	否

基础设置结构：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash|Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "python3 .claude/hooks/check.py",
            "timeout": 30
          }
        ]
      }
    ]
  }
}

2. Hook 执行类型

理解这一步时，Hook 事件描述“什么时候触发”，hook 执行类型描述“触发后用什么方式执行”。

执行类型	关键字段	什么时候采用	如何采用	注意事项
command	command, shell, timeout, statusMessage, once, async, asyncRewake, if	需执行本地脚本或 shell 命令时；最常用	从实现思路看，写一个脚本从 stdin 读取 JSON，输出文本或 JSON，再在 settings.json 设置 command	hook 可执行任意命令，只运行可信脚本；建议设置合理 timeout
prompt	prompt, model, timeout, statusMessage, once, if	需用模型判断某个事件是否合规，或生成简短建议	落到代码里，设置 prompt，让 Claude Code 把 hook 输入交给模型分析	适合判断和文本分析，不适合强制性安全边界
agent	prompt, model, timeout, statusMessage, once, if	需启动代理做更完整的验证或检查	设置 agent prompt，要求代理审查输入、输出结论	成本和延迟更高；适合较重的检查
http	url, headers, allowedEnvVars, timeout, statusMessage, once, if	需把 hook 事件发送到外部服务，比如审计、通知、策略引擎	结合项目来看，Claude Code 向 url POST hook 输入 JSON，服务得到 JSON	HTTP hook 必须得到 JSON；不要把敏感信息发到不可信服务

callback 和 function 类型属于程序内或会话内注册机制，不适合直接写入持久化 settings.json。

3. Hook 事件类型总表

Hook 类型	触发时机	什么时候采用	如何采用	常用 matcher
PreToolUse	Claude 准备调用工具之前	阻止危险命令、限制文件写入范围、校验工具输入、改写工具输入	在这个场景下，设置在 hooks.PreToolUse 下，按工具名匹配；脚本读取 tool_name 和 tool_input，必要时得到 permissionDecision 或 updatedInput	工具名，比如 Bash, Write, Edit, Read
PostToolUse	工具调用成功之后	自动格式化、运行 lint/test、记录工具结果、补充上下文、处理 MCP 工具输出	结合项目来看，设置在 hooks.PostToolUse 下；脚本读取 tool_response 同时得到普通输出或结构化 JSON	工具名
PostToolUseFailure	工具调用失败之后	收集失败诊断、记录错误、提示修复建议	理解这一步时，设置在 hooks.PostToolUseFailure 下；脚本读取 error 字段	工具名
PermissionRequest	Claude Code 需权限决策时	自动批准低风险命令、拒绝高风险命令、改写工具输入、接入组织策略	在这个场景下，设置在 hooks.PermissionRequest 下，得到 hookSpecificOutput.decision.behavior 为 allow 或 deny，可附带 updatedInput	工具名
PermissionDenied	工具权限被拒绝后	记录拒绝原因、通知用户、决定是否引导换方案	结合项目来看，设置在 hooks.PermissionDenied 下，读取被拒绝的工具和原因	工具名
Notification	Claude Code 发出通知时	转发到桌面、Slack、企业 IM、日志系统	设置在 hooks.Notification 下；按通知类型匹配	notification_type
UserPromptSubmit	用户提交 prompt 后、Claude 处理前	注入项目上下文、审计用户输入、阻止违规请求、补充团队规则	落到代码里，设置在 hooks.UserPromptSubmit 下；得到 additionalContext 可给模型增加上下文	通常不按工具匹配
SessionStart	会话开始、恢复、清空后重新进入等场景	加载项目上下文、设置 watch paths、输出初始化提示	在这个场景下，设置在 hooks.SessionStart 下；可得到 additionalContext, initialUserMessage, watchPaths	source
SessionEnd	会话结束、清空或退出时	清理资源、保存状态、发送结束通知	设置在 hooks.SessionEnd 下；脚本应很快完成	reason
Stop	Claude 完成一次响应、即将停止时	最后质量检查、检查待办未完成项、要求 Claude 继续修复	设置在 hooks.Stop 下；得到阻塞结果可促使继续处理	通常无 matcher
StopFailure	Stop hook 或停止流程失败时	记录停止失败、诊断异常	设置在 hooks.StopFailure 下，读取错误信息	error
SubagentStart	子代理启动时	给子代理注入上下文、记录代理开始执行	设置在 hooks.SubagentStart 下	agent_type
SubagentStop	子代理完成时	校验代理输出、收集报告、阻止不合格结果进入主流程	设置在 hooks.SubagentStop 下	agent_type
PreCompact	上下文压缩前	保存关键状态、导出中间结论、阻止不合适的压缩	设置在 hooks.PreCompact 下	trigger
PostCompact	上下文压缩后	恢复关键上下文、重新注入摘要或提醒	设置在 hooks.PostCompact 下	trigger
Setup	初始化或 setup 流程触发时	初始化环境、准备上下文、执行一次性设置	设置在 hooks.Setup 下	trigger
TeammateIdle	协作 agent 或 teammate 空闲时	自动分派任务、提醒、状态检查	设置在 hooks.TeammateIdle 下	通常无 matcher
TaskCreated	任务新建时	记录任务、同步到外部系统、通知协作方	设置在 hooks.TaskCreated 下	通常无 matcher
TaskCompleted	任务完成时	结果校验、归档、通知、触发后续流程	设置在 hooks.TaskCompleted 下	通常无 matcher
Elicitation	MCP elicitation 请求发起时	自动接受、拒绝或取消 MCP 服务提出的问题	设置在 hooks.Elicitation 下	mcp_server_name
ElicitationResult	MCP elicitation 得到结果时	校验得到内容、审计用户/系统响应	设置在 hooks.ElicitationResult 下	mcp_server_name
ConfigChange	设置发生变化时	刷新缓存、记录设置变更、重新加载策略	设置在 hooks.ConfigChange 下	source
WorktreeCreate	新建 worktree 时	接管或参与 worktree 新建，并在得到路径前完成必要初始化	在这个场景下，设置在 hooks.WorktreeCreate 下；必须借助 stdout 或 hookSpecificOutput.worktreePath 得到非空 worktree 路径	通常无 matcher
WorktreeRemove	删除 worktree 时	清理资源、释放锁、删除临时文件	设置在 hooks.WorktreeRemove 下	通常无 matcher
InstructionsLoaded	指令文件加载完成后	审计或追加说明上下文、提示冲突规则	设置在 hooks.InstructionsLoaded 下	load_reason
CwdChanged	当前工作目录变化时	更新路径相关环境、刷新项目上下文	设置在 hooks.CwdChanged 下	通常无 matcher
FileChanged	被的文件变化时	自动刷新上下文、重新加载设置或规则	在这个场景下，先借助 SessionStart 得到 watchPaths，再设置 FileChanged 处理变更	文件 basename

4. 常用目标与建议 hook

目标	建议 hook	建议 matcher	典型做法
阻止危险 Bash 命令	PreToolUse	Bash	在这个场景下，读取 tool_input.command，命中 rm -rf, git reset --hard, `curl
限制只能改某些目录	PreToolUse	`Write	Edit
编辑后自动格式化	PostToolUse	`Write	Edit
工具失败后自动诊断	PostToolUseFailure	`Bash	Read
自动批准低风险只读命令	PermissionRequest	Bash	对 git status, ls, pwd 等得到 hookSpecificOutput.decision.behavior: "allow"
用户输入后补充上下文	UserPromptSubmit	无	得到 additionalContext，比如项目当前规范或安全边界
会话启动时加载项目信息	SessionStart	source	得到项目说明、默认任务提醒、需的文件路径
响应结束前质量门禁	Stop	无	检查是否运行测试、是否完成待办；不满足则阻塞并说明原因
子代理完成后校验	SubagentStop	agent_type	检查代理输出是否包含必需字段或是否发现高危问题
上下文压缩前保存状态	PreCompact	trigger	把关键任务状态写入文件或外部系统
任务完成后通知	TaskCompleted	无	发桌面通知、Webhook 或企业 IM 消息
接管 worktree 新建	WorktreeCreate	无	新建或初始化 worktree 后，得到最后 worktree 路径

5. Hook 输入协议

实际处理时，Claude Code 会把结构化 JSON 写入 hook 进程的 stdin。

通用字段：

字段	类型	含义
session_id	string	当前会话 ID
transcript_path	string	当前 transcript 文件路径
cwd	string	当前工作目录
permission_mode	string?	当前权限模式，可能不存在
agent_id	string?	子代理 ID，主线程通常不存在
agent_type	string?	agent 类型，可能不存在
hook_event_name	string	当前 hook 事件名

工具相关 hook 额外字段：

字段	出现于	含义
tool_name	PreToolUse, PostToolUse, PostToolUseFailure, PermissionRequest, PermissionDenied	工具名
tool_input	工具相关 hook	工具输入
tool_response	PostToolUse	工具成功输出
error	失败类事件	错误信息

示例脚本读取输入：

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

payload = json.load(sys.stdin)
print(json.dumps({"suppressOutput": True}))

6. Hook 输出协议

command hook 的 stdout 如果去掉空白后以 { 开头，会被当成 JSON 解析；否则按普通文本处理。http hook 必须得到 JSON。

通用输出字段：

字段	类型	作用
continue	boolean	false 表示阻止 Claude 继续
suppressOutput	boolean	是否隐藏 hook stdout
stopReason	string	continue: false 时展示的停止原因
decision	string	常用值为 approve 或 block
reason	string	决策原因
systemMessage	string	展示给用户的系统消息或警告
hookSpecificOutput	object	针对具体 hook 的结构化输出

常用 hookSpecificOutput：

Hook	可用字段	用法
PreToolUse	permissionDecision, permissionDecisionReason, updatedInput	允许、拒绝或改写即将执行的工具输入
PermissionRequest	decision.behavior, decision.updatedInput, decision.message	对权限请求得到允许或拒绝决策
UserPromptSubmit	additionalContext	给 Claude 追加上下文
SessionStart	additionalContext, initialUserMessage, watchPaths	初始化会话上下文和文件
PostToolUse	updatedMCPToolOutput	更新 MCP 工具输出，仅对 MCP 工具有效
WorktreeCreate	worktreePath	理解这一步时，HTTP hook 得到新建好的 worktree 路径；command hook 可直接输出路径

权限请求允许示例：

{
  "hookSpecificOutput": {
    "hookEventName": "PermissionRequest",
    "decision": {
      "behavior": "allow",
      "updatedInput": {}
    }
  }
}

权限请求拒绝示例：

{
  "hookSpecificOutput": {
    "hookEventName": "PermissionRequest",
    "decision": {
      "behavior": "deny",
      "message": "该命令不允许自动执行"
    }
  }
}

阻止危险命令示例：

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "禁止执行破坏性 rm 命令"
  }
}

注入上下文示例：

{
  "hookSpecificOutput": {
    "hookEventName": "UserPromptSubmit",
    "additionalContext": "本项目要求修改代码后运行相关测试。"
  }
}

会话启动示例：

{
  "hookSpecificOutput": {
    "hookEventName": "SessionStart",
    "additionalContext": "已加载项目上下文。",
    "initialUserMessage": "请先阅读 README.md 和 AGENTS.md。",
    "watchPaths": ["/absolute/path/to/AGENTS.md"]
  }
}

7. 退出码语义

退出码	行为	什么时候采用
0	成功	hook 检查借助，或只输出信息
2	阻塞错误，Claude 会收到 hook feedback	需明确阻止当前动作或要求 Claude 修正
其他非零值	非阻塞错误，通常展示给用户但不一定阻止流程	hook 自身失败但不应中断主流程

也可以用 JSON 表达阻塞：

{
  "decision": "block",
  "reason": "该命令不允许执行"
}

8. Matcher 与条件

8.1 matcher

matcher 用来筛选 hook 是否执行。

写法	含义	示例
省略或 *	匹配全部	所有工具调用后都运行日志 hook
精确工具名	只匹配单个工具	Bash
管道分隔	匹配多个工具	`Write
正则表达式	更灵活的匹配	^mcp__.*

8.2 if 条件

if 是更细粒度的工具条件，适用来工具相关事件：

PreToolUse
PostToolUse
PostToolUseFailure
PermissionRequest

示例：

{
  "type": "command",
  "command": "python3 .claude/hooks/check-git.py",
  "if": "Bash(git *)"
}

9. 设置示例

9.1 禁止危险 Bash 命令

.claude/settings.json：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "python3 .claude/hooks/block-dangerous-bash.py",
            "timeout": 10
          }
        ]
      }
    ]
  }
}

.claude/hooks/block-dangerous-bash.py：

从实现思路看，接下来脚本只是最小演示，不能覆盖所有 shell 绕过方式；生产环境更建议 allowlist、命令解析器或组织级策略引擎。

#!/usr/bin/env python3
import json
import re
import sys
payload = json.load(sys.stdin)
command = payload.get("tool_input", {}).get("command", "")
blocked = [r"brms+-rfb", r"bgits+resets+--hardb", r"bgits+pushs+--forceb"]
if any(re.search(pattern, command) for pattern in blocked):
    print(json.dumps({
        "hookSpecificOutput": {
            "hookEventName": "PreToolUse",
            "permissionDecision": "deny",
            "permissionDecisionReason": "检测到高风险命令，请先获得用户明确确认。"
        }
    }))
    sys.exit(0)
print(json.dumps({"suppressOutput": True}))

9.2 编辑后自动格式化

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit|MultiEdit",
        "hooks": [
          {
            "type": "command",
            "command": "python3 .claude/hooks/format-changed-file.py",
            "timeout": 60
          }
        ]
      }
    ]
  }
}

9.3 会话开始时注入项目上下文

settings.json 里只设置 hook 什么时候运行、运行什么命令；hookSpecificOutput 是该命令执行后输出到 stdout 的 JSON，不是直接嵌在 settings.json 里的字段。

.claude/settings.json：

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup|resume|clear|compact",
        "hooks": [
          {
            "type": "command",
            "command": "python3 .claude/hooks/session-context.py",
            "timeout": 10
          }
        ]
      }
    ]
  }
}

matcher 匹配 source 字段，可用值如下所示：

source	含义	适用场景
startup	新会话启动	加载项目上下文、初始化提示
resume	恢复旧会话	恢复会话状态、提醒历史上下文
clear	清空会话后重新开始	重新注入基础规则
compact	压缩上下文后继续	重新注入关键摘要或状态

SessionStart hook 收到的输入 JSON 结构大致如下所示：

{
  "session_id": "session-id",
  "transcript_path": "/absolute/path/to/transcript.jsonl",
  "cwd": "/absolute/path/to/project",
  "permission_mode": "default",
  "hook_event_name": "SessionStart",
  "source": "startup",
  "agent_type": "default",
  "model": "claude-sonnet-4-6"
}

字段说明：

字段	类型	必填	说明
session_id	string	是	当前会话 ID
transcript_path	string	是	当前 transcript 文件路径
cwd	string	是	当前工作目录
permission_mode	string	否	当前权限模式
hook_event_name	"SessionStart"	是	固定为 SessionStart
source	"startup" \| "resume" \| "clear" \| "compact"	是	SessionStart 的触发来源，也是 matcher 匹配字段
agent_type	string	否	当前 agent 类型
model	string	否	当前会话采用的模型

脚本 stdout 得到的完整 hookSpecificOutput JSON 结构：

{
  "hookSpecificOutput": {
    "hookEventName": "SessionStart",
    "additionalContext": "本仓库是 Claude Code 恢复版源码；修改前请优先阅读 README.md。",
    "initialUserMessage": "请先阅读 README.md 和 AGENTS.md，然后再开始任务。",
    "watchPaths": [
      "/absolute/path/to/project/README.md",
      "/absolute/path/to/project/AGENTS.md"
    ]
  }
}

SessionStart.hookSpecificOutput 字段说明：

字段	类型	必填	作用
hookEventName	"SessionStart"	是	必须与当前 hook 事件一致，否则会被视为错误输出
additionalContext	string	否	注入给 Claude 的额外上下文，适合放项目规则、恢复提示、环境说明
initialUserMessage	string	否	作为会话开始时的初始用户消息，适合自动触发启动任务或提醒
watchPaths	string[]	否	要的绝对路径；文件变化后可触发 FileChanged hook

最小脚本示例：

#!/usr/bin/env python3
import json
print(json.dumps({
    "hookSpecificOutput": {
        "hookEventName": "SessionStart",
        "additionalContext": "本项目要求修改代码后运行相关测试。"
    }
}))

9.4 用户提交 prompt 后追加规则

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "python3 .claude/hooks/user-prompt-context.py",
            "timeout": 5
          }
        ]
      }
    ]
  }
}

脚本输出：

{
  "hookSpecificOutput": {
    "hookEventName": "UserPromptSubmit",
    "additionalContext": "如果要修改代码，请先检查现有测试和相关实现。"
  }
}

10. 关键注意事项

注意事项	说明	建议
Hooks 能执行任意命令	.claude/settings.json 中的 hook 是代码执行入口	只信任可信仓库与可信设置；审查外部 PR 中的 hook 变更
交互模式可能需 workspace trust	未信任工作区时，交互模式下 hook 可能被跳过	对安全边界不要只依赖 hook；结合权限模式和人工确认
同一事件的多个 hook 可能并行执行	不应依赖 hook 之间的执行顺序	需顺序时把逻辑放进同一个脚本
默认超时可能较长	工具 hook 默认可能等待较久	为每个 hook 显式设置 timeout
SessionEnd 要更快完成	结束 hook 默认超时很短	只做轻量清理；重任务放到后台或外b队列
stdout JSON 解析敏感	stdout.trim() 以 { 开头会按 JSON 解析	普通文本不要以 { 开头；结构化输出确保合法 JSON
HTTP hook 必须得到 JSON	空响应会按 {} 处理，非 JSON 是错误	外部服务统一得到 JSON envelope
HTTP hook 不适合所有事件	SessionStart / Setup 等场景不适合 HTTP hook	初始化类逻辑优先用 command
PreToolUse 可改写输入	updatedInput 会影响即将执行的工具	只做确定、安全、可审计的改写
PostToolUse 不应假设能改所有输出	updatedMCPToolOutput 只对 MCP 工具有效	普通工具结果用日志或上下文提示处理
async hook 后台运行	可减少等待，但结果不会同步阻塞当前流程	只用来通知、审计、异步归档等非关键路径
asyncRewake 会唤醒模型	后台 hook 退出码为 2 时可注入阻塞反馈	谨慎采用，避免噪音或循环唤醒
once 只运行一次	执行后 hook 会被移除	适合一次性初始化，不适合长期策略
shell 可设置	兼容 bash 和 powershell	跨平台项目要明确 shell 与路径差异

11. 设计建议

设计原则	建议做法
安全优先	从实现思路看，对破坏性操作采用 PreToolUse 或 PermissionRequest，但仍保留人工确认
更快失败	hook 内部校验失败时输出清晰原因，不要静默失败
最小权限	hook 只读取必要字段，只访问必要文件或外部服务
可观察	关键 hook 记录事件、决策和原因，便于排查
不依赖顺序	多个独立 hook 不共享隐式状态
保持轻量	同步 hook 只做更快检查；耗时任务改为异步或外b队列
设置分层	团队规则放项目级，个人偏好放用户级或本地级
明确边界	不把 hook 当作唯一安全机制；配合权限模式、代码审查和测试

12. 速查表

你想做什么	首选 hook	执行类型	得到什么
阻止命令执行	PreToolUse	command	permissionDecision: "deny"
自动批准权限	PermissionRequest	command	hookSpecificOutput.decision.behavior: "allow"
改写工具输入	PreToolUse	command	updatedInput
编辑后格式化	PostToolUse	command	普通输出或 suppressOutput
工具失败后提示	PostToolUseFailure	command / prompt	文本建议或系统消息
增加用户 prompt 上下文	UserPromptSubmit	command	additionalContext
会话开始加载上下文	SessionStart	command	additionalContext, initialUserMessage, watchPaths
响应结束前检查	Stop	command / agent	decision: "block" 或退出码 2
通知外部系统	Notification / TaskCompleted	http / command	{} 或通知结果
压缩前保存状态	PreCompact	command	成功状态或阻塞原因
新建 worktree	WorktreeCreate	command / http	stdout 路径或 hookSpecificOutput.worktreePath