Hook 事件与输入

区分成功、失败、会话、subagent 和提示转换事件，按实际 payload 编写处理器。

This page has not been translated into English yet. The original Chinese version is shown below.

Hook 处理器接收 JSON 输入。事件名决定触发时机，也决定输入格式；不要根据其他客户端的示例直接猜测字段名称或时间格式。

事件选择

事件	触发时机	输出能力
sessionStart	新建或恢复会话	添加上下文
sessionEnd	会话结束	不处理输出
userPromptSubmitted	用户提交提示	modifiedPrompt 仅 SDK programmatic hooks 生效
userPromptTransformed	提示转为模型输入后、写入历史前	改写模型收到的内容
preToolUse	执行工具前	允许、拒绝、询问或改写参数
postToolUse	工具成功后	改写结果或添加上下文
postToolUseFailure	工具失败后	提供恢复建议
permissionRequest	常规权限服务运行前	程序化允许或拒绝
preCompact	手动或自动压缩前	仅通知
subagentStart	subagent 开始前	给首条提示添加上下文，不能阻止创建
subagentStop	subagent 正常结束、返回父级前	继续执行或改写返回内容
agentStop	主智能体完成一轮	可要求继续执行
notification	CLI 系统通知	异步运行，可添加上下文
errorOccurred	执行错误	不处理输出

内置 general-purpose 不发出 subagentStart / subagentStop，其余官方列出的 YAML 内置角色和自定义 agents 会发出。不要用 subagent Hooks 推断一定覆盖所有委派方式。

输入命名格式

camelCase 事件名，例如 sessionStart，使用 sessionId 和毫秒 Unix timestamp。VS Code 兼容的 PascalCase 名称，例如 SessionStart，使用 session_id、hook_event_name 和 ISO 8601 字符串时间戳。

部分事件别名不是简单改变首字母：agentStop 对应 Stop，userPromptSubmitted 对应 UserPromptSubmit。应按官方对应表选择。

工具前置事件的 camelCase 输入结构：

{
  sessionId: string;
  timestamp: number;
  cwd: string;
  toolName: string;
  toolArgs: unknown;
}

toolArgs 是 unknown，不应假设永远是已经解析的对象或永远是 JSON 字符串。编写处理器时先校验类型，再解析所需参数。成功事件增加 toolResult，失败事件增加 error 字符串。

会话与提示细节

sessionStart 的 source 为 startup、resume 或 new；sessionEnd 的 reason 包括 complete、error、abort、timeout、user_exit。CLI 的 /clear 会结束旧会话并触发 user_exit，但进程继续运行，旧会话结束 Hook 在后台执行，不阻塞新提示；之后退出 CLI 会终止尚未结束的后台 Hook。

配置文件中的 userPromptSubmitted 命令或 HTTP Hook 不支持用 modifiedPrompt 改写提示。需要改变模型侧内容时核对 userPromptTransformed 的 modifiedTransformedPrompt；它改变模型内容和会话历史，不改时间线显示的用户提示，恢复会话会重放修改后的内容。

Matcher

native matcher 是完整匹配的正则表达式，相当于 ^(?:PATTERN)$；无效正则会跳过该 Hook。notification 匹配 notification_type，preCompact 匹配 manual / auto，subagentStart 匹配 agentName，工具相关事件匹配 toolName。

PascalCase PreToolUse / PermissionRequest 采用 Claude 兼容匹配：*、** 或空值匹配所有；Bash、Edit|Write 等名称按兼容工具名称匹配。此时 payload 中可能是 Bash / Read / Write / Edit，而不是 bash / view / create / edit。迁移时同时检查 matcher 和处理器字段。

云端不会触发全部事件，差异见HTTP Hooks 与云端。