| name | subagent-orchestration |
| description | 沙箱子代理的编排与调用（sandbox_subagent / _status / _wait / _cancel / _retry）——何时委派、收益门、Context Pack、写集、结构化交付与主代理接管。 |
子代理编排 v2（subagent-orchestration）
When to use
先过收益门，全部满足才开子代理：
- 至少 2 个当前可独立执行的节点；
- 预计关键路径缩短 ≥ 25%；
- 拆分/等待/汇总/复核成本 ≤ 子任务总工作量 20%；
- 每个子任务预计 30~180 秒，有单一可验收交付物；
- 写集互斥或使用独立目录；
- 主代理仍保留预算做验收与收尾。
适合并行：多模块只读调研、独立候选方案、独立目录实现、不同测试面。
适合流水线（有依赖时）：调研 → 主代理冻结设计 → 多模块实现 → 验证 → 主代理收尾。
不应委派：少于约 3~4 次工具调用、需要联网/授权/用户交互、多个步骤频繁改同一文件、结果立等可用。
调用姿势
1. 写自包含 Context Pack
子代理看不到主对话历史，prompt 必须自包含：
目标：<一句话>
为什么：<在父计划中的作用>
输入：<明确路径/文件/快照，用 sandbox_list_files 确认>
约束：<禁止项、兼容性、安全边界>
写集：<允许写的路径前缀；写集外写入会被拒绝 write_not_allowed>
接口契约：<DOM ID / schema / 类型 / 命名>
输出契约：<交付 JSON：summary / artifacts[] / evidence[] / acceptance[] / risks / unresolved>
完成标准：<什么算完成>
失败协议：<预算耗尽时输出当前进度与已写文件，不假成功>
2. 等待优先于轮询
sandbox_subagent_wait(subagent_ids, mode=all|any, timeout_ms, after_event_seq)；- 服务端按片返回，超时给
retry_after_ms，按它再次调用；
- 禁止在一个回合内连续多次
sandbox_subagent_status 轮询；
- 等待期间主代理应继续做不冲突的工作（写文档、冻结接口、准备合并框架）。
3. 状态语义（只有 completed 才是成功）
| 状态 | 含义 |
|---|
| completed | 有非空最终答案且交付契约通过 |
| partial | 轮数/工具数/token/费用预算耗尽，可能有可用文件——检查产物 |
| failed | 异常或空结果（empty_result） |
| timed_out | 墙钟超限 |
| cancelled | 已确认取消（取消中是 running + cancel_requested） |
4. 失败处理
- 瞬时 Provider/容量错误：
sandbox_subagent_retry(scope=same) 一次；
- 范围过大/预算耗尽：
sandbox_subagent_retry(scope=scoped, prompt_override=更窄的prompt) 一次；
- 已有大部分产物、剩余工作量小、写集冲突、权限异常、重复失败：主代理接管，不整任务重跑；
- 结果不满意：在结果上迭代，不无脑重跑。
5. 写集与目录
- 派发时声明
write_set；文件类工具越界写入直接拒绝；
- 未声明时默认只允许
work/subagents/<task_id>/ 车道；
- 每个子代理只写自己的目录，主代理按 manifest 合并，避免并行覆盖。
6. 交付说明（强制）
子代理最终回复必须带 JSON 交付块；partial 时也要输出进度与已写文件路径。主代理合并前用 sandbox_read_file / sandbox_grep 确定性复核，不采信"我说完成了"。
限制
- 子代理不能联网、不能弹用户授权、不能嵌套创建子代理；
- 任务持久化在数据库（sandbox_agent_tasks / sandbox_agent_events），重启不丢；
- 并发受 chat/user/workspace 配额约束；排队中任务自动开始，无需重提。
详细说明
- 工具契约见
references/tool-contract.md
- 执行器与调度说明见
references/runner.md
