会话与 Subagent Hooks

不同生命周期事件的阻塞能力不同。会话初始化和压缩观察不能代替执行前权限事件。

会话与提示

sessionStart 在创建新 composer conversation 时触发，可返回 env 与 additional_context；env 会传给后续 hook 执行。它按 fire-and-forget 运行，调用方不等待或执行阻塞响应。即使 schema 接受 continue:false，也不能阻止会话创建。

sessionEnd 用于日志和清理，响应只记录而不用于后续决策。输入包括 reason、duration_ms、final_status 等。

需要阻止用户提示提交时使用 beforeSubmitPrompt：输入 prompt 和 attachments，返回 continue 布尔值及可选 user_message。

Subagent 生命周期

subagentStart 可检查 subagent_type、task、parent_conversation_id、subagent_model、is_parallel_worker 和可选 git_branch。返回 permission 为 allow 或 deny；ask 不受支持，会被当作 deny。

subagentStop 提供 status、summary、duration_ms、modified_files、loop_count 和独立的 agent_transcript_path。只有 status 为 completed 时才消费 followup_message。

完成后续跑

stop 在 Agent loop 结束时收到 completed、aborted 或 error 状态。非空 followup_message 会作为下一条用户消息自动提交。

{
  "version": 1,
  "hooks": {
    "stop": [
      { "command": ".cursor/hooks/check-completion.sh", "loop_limit": 3 }
    ]
  }
}

脚本应根据状态与完成证据决定是否返回 followup_message，目标已达成时不再返回。loop_count 从 0 起，Cursor hook 默认每脚本最多 5 次自动续跑；示例改为 3。null 表示无上限，兼容 Claude Code hooks 的默认值也是 null，迁移时应专门检查。

压缩与回复观察

preCompact 带 trigger、context_usage_percent、context_tokens、context_window_size、message_count 等字段，可返回 user_message，但不能阻止或修改压缩。

afterAgentResponse 提供完成消息的 text；afterAgentThought 提供完成思考块的 text 与可选 duration_ms，当前没有输出字段。将它们作为观察事件，不应期待其返回权限决定生效。