| name | session-coordination |
| description | Coordinate inter-session communication — when and why to send messages, how to structure spawned tasks. Message format lives in `send`. Use when a caller must pass a callback session key and full skill prompt to a callee, a callee must promptly report a blocker or material finding, or a task needs inter-session updates before final delivery. |
session-coordination - 会话协调
在 caller 与 callee 之间传递可行动信息。它只定义会话通信协议；领域任务、产出结构、wiki 写入和完成门禁仍由调用它的 skill 负责。
工具边界
| 目标 | 工具 | 规则 |
|---|
| 创建独立工作 | sessions_spawn | caller 创建；self-spawn 省略 agentId。 |
| 回传发现或协调既有会话 | sessions_send | 格式细节见 send；只向 task 中明确给出的目标发送。 |
| 持久化领域产出 | 备好 md 经 ingest 写入 + inline reply | 不用 session key 或文件路径充当产物交接。 |
timeoutSeconds: 0 表示非阻塞投递，适合 callee 的即时回传。caller 需要在当前步骤取得回复时，才设置正的 timeoutSeconds。
Caller：创建可回传的子会话
在 sessions_spawn 前，取得 caller 当前可投递的非 thread-scoped session key，并读取本次调用 skill 的完整 prompt/正文。若当前会话 key 以 :thread:<id> 结尾，改为取得对应的非 thread-scoped 父会话 key；无法取得时不得启用即时回传，改用 completion 交付。每个 callee task 都必须内联以下内容；不得只提供路径、占位符或“读取某文件”的指令：
<caller_session_key>
<caller 当前可路由的 session key>
</caller_session_key>
<invoked_skill_prompt>
<本次调用 skill 的完整 prompt/正文>
</invoked_skill_prompt>
<work_item>
<具体目标、输入、约束、预期最终交付>
</work_item>
<reporting_protocol>
出现 blocker、需要 caller 决策、已验证的关键发现或会改变后续工作的结论时，立刻用 sessions_send 向 caller_session_key 发送一条简短结构化回传（格式见 `send`）。没有可行动的新信息时继续工作，不发送进度噪声。最终仍按 work_item 返回完整交付或具体失败原因。
</reporting_protocol>
caller_session_key 仅是即时回传地址，不是领域产物、授权能力或后续流程的交接接口。- isolated callee 不共享 caller 的会话记忆；完整 skill prompt、工作项和约束必须随 task 传入。
- caller 为每个 task 设置唯一
label。批量 task 全部发出后，调用一次 sessions_yield，通过 completion events 汇总；不轮询 sessions_list 或 sessions_history。
- 子会话不得再 spawn 子会话；当前最大深度为一层。
Callee：及时回传可行动发现
-
从 task 中读取 <caller_session_key> 与 <invoked_skill_prompt>，按该 prompt 和 work item 工作。获取自己当前可路由的非 thread-scoped session key（格式为 agent:main:<id>，不以 :thread:<id> 结尾），作为 <message from="..."> 属性的发送方标识。
-
出现下列任一事件时，立即发送一条短消息，而不是等到最终回复：
- 输入缺失、不可读或任务无法继续；
- caller 必须选择的方案、范围或风险；
- 已验证且会改变后续工作方向的发现；
- 关键阶段完成，且 caller 可以据此安排后续工作。
-
使用 send predicate 定义的消息格式调用 sessions_send。
-
最终 reply 仍返回完整交付或明确失败原因；需要持久化的 predicate 产出仍备好 md 经 ingest 写入 wiki 并内联返回内容本体。
回传门禁
- 只发送可行动的新信息；不发送”仍在处理””继续工作中”等低价值进度。
- 不发送 secrets、无关私人上下文或未经验证的推测。
- 不使用
watch，不枚举会话、不读取会话历史，也不把 session key 复制到最终交付中。
- 不向以
:thread:<id> 结尾的 thread-scoped session key 发送。
- 收到回传的 caller 自己决定后续工作；callee 不因回传而创建递归会话或无限来回通信。
- 若缺少 caller key、
sessions_send 被拒绝或投递失败，继续完成可完成的工作，并在最终 reply 明确说明哪条回传未送达；不得声称已通知 caller。
- 消息格式必须遵循
send predicate 的要求；sessionKey 填 caller key（目标），<message from="..."> 填 callee own key（发送方）。
- 当前 sandbox 关闭。若未来使用
sandbox: "require"，会话可见性被限制到 tree；只有 caller 位于该可见树中时才可依赖此协议。
完成门禁
- 每个 spawned task 都含 caller session key、完整调用 skill prompt、完整工作项和唯一 label。
- 每个可行动 blocker / decision / finding / milestone 都已即时回传，或在最终 reply 中报告未送达原因。
- 最终领域交付遵循调用 skill 的 wiki 与 inline reply 规则，未以 session key 或文件路径替代。
- caller 对每个 task 记录成功、失败或超时的唯一终态。
