Hook 事件与输入
区分成功、失败、会话、subagent 和提示转换事件，按实际 payload 编写处理器。
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 与云端。