云端 Hook 事件与输入

云端仅触发 Hooks 参考所列事件的一部分。不能用 CLI 上某事件正常运行作为它在云端同样有效的依据。

事件表

事件	云端行为
sessionStart	每个 job 一次，作为新会话，可返回 additionalContext
sessionEnd	每个 job 一次，常见 reason 为 complete、error、timeout
userPromptSubmitted	参考描述为初始提示最多一次；配置文件 Hook 的 modifiedPrompt 不处理
userPromptTransformed	可改写模型和历史收到的内容，不改变时间线显示，也不能阻止或接管该轮
preToolUse	工具执行前，可做权限决策；ask 按 deny 处理
postToolUse	仅工具成功后，可替换结果或附加上下文
postToolUseFailure	工具失败后，可提供恢复指导
agentStop	主代理完成一轮时，可要求继续；仍消耗任务时间预算
subagentStart	子代理开始，可追加上下文，不能阻止创建
subagentStop	子代理结束，可要求继续或改写返回给父代理的结果
errorOccurred	发生错误，输出不作为决策处理
preCompact	只有自动压缩，trigger 为 auto
notification	不触发
permissionRequest	不适用于云端权限决策，改用 preToolUse

概念页仍将 postToolUse 概括为含失败；当前参考将失败单列为 postToolUseFailure，本文采用细分规则。

Hooks 参考把云端输入描述为只有初始提示，但会话管理支持 steering。两页未给出所有运行时的事件对应关系，不能据此保证每条 steering 都触发 userPromptSubmitted。

输入格式

命令 Hook 从标准输入读取 JSON。使用 camelCase 事件时字段也是 camelCase，例如 preToolUse 的 sessionId、毫秒时间戳 timestamp、cwd、toolName 和 toolArgs。

使用兼容的 PreToolUse 时，字段变为 session_id、ISO 8601 字符串时间戳、tool_name 和 tool_input，并包含 hook_event_name。应按配置的事件名称解析，不要只改事件大小写却复用原字段访问代码。

兼容事件还会转换工具名，例如原生 bash 在 PreToolUse payload 中是 Bash；相应 matcher 也有兼容语义，详见官方参考。

Matcher

原生 matcher 正则会包成 ^(?:PATTERN)$，要求匹配完整值；无效正则会跳过该条目。

事件	匹配值
preToolUse、postToolUse	工具名 toolName
preCompact	trigger；云端为 auto
subagentStart	agentName

例如 bash|edit 匹配这两个完整工具名，不是任意含该片段的名称。

子代理与结束事件

参考说明内置 general-purpose 不发出 subagentStart / subagentStop，其他所列 YAML 型内置角色和自定义角色会发出；不要把没有收到事件直接解释为子代理没有工作。

subagentStart 的 additionalContext 加到子代理首条用户消息前；多个非空输出按顺序用双换行连接，合计受 10 MiB 限制。

agentStop / subagentStop 可返回 decision: "block" 与非空 reason 继续执行。只有 subagentStop 支持 modifiedResponse；block 优先，多条改写不串联，最后一条改写生效。参考把连续 8 次 block 的保护明确写为 CLI 行为，本文不把它当作云端任务的独立可用预算。