@@ -4,7 +4,7 @@
subagent seam 允许一个 agent（ ） （ `ctx.subagents` ）；提供方决定子 agent 在当前进程、另一进程还是未来的传输之上运行。
[subagent 家族概述 ](../README.md )列出了实现和面向模型的消费方。本包负责提供方注册表、共享请求和 结果契 约、持久描述符以及可继续子级编排。多个具名提供方可以在该契 约背后共存。
[subagent 家族概述 ](../README.md )列出了实现和面向模型的消费方。本包负责提供方注册表、共享的 请求与 结果约定 、持久描述符以及可继续子级编排。多个具名提供方可以在该约定 背后共存。
## 服务 API
@@ -23,7 +23,7 @@ subagent seam 允许一个 agent（ ）
| `registerContinuableSetup(contribution)` | 把一项可选部署能力组合到每个可继续 child 尚未发布的作用域中，并支持从驻留 child 立即撤销。 |
| `drainContinuableDescendants(parents)` | 在由 host 确切拥有的在线 parent Agent 之下关闭准入，只停止其可见的可继续后代，等待在这些根之下已获准的物化过程完成发布或回滚，再按 child-first 顺序释放所选森林。该截止状态会持续到每个确切 parent 离开注册表；无关的 parent 森林和管理器全局准入保持在线。 |
| `listChildren(parentSessionId, signal?)` | 按 `createdAt` 再按 id 的顺序列出由会话支撑的直接 subagent， `one-shot` ／ `continuable` 模式、`running` ／ `inactive` 活动状态、基于 origin 分类的一层 `hasChildren` 提示与逐 child diagnostic， （ ） ， `sessionProjections` 注册表；不要求 `ctx.agents` 、继续执行管理器或任何查询服务。 |
| `listDescendants(rootSessionId, signal?)` | 从同一份实时 优先语料按稳定 pre-order 展平根的完整会话树，并为每个 subagent 条目附加持久 `parentId` 与相对根的 `depth` 。普通会话与一次性 child 仍作为遍历节点， 契 约均沿用 `listChildren()` 。 |
| `listDescendants(rootSessionId, signal?)` | 从同一份在线 优先语料按稳定 pre-order 展平根的完整会话树，并为每个 subagent 条目附加持久 `parentId` 与相对根的 `depth` 。普通会话与一次性 child 仍作为遍历节点， 定 均沿用 `listChildren()` 。 |
`SubagentStartRequest.label` 是由会话支撑的一次性 child 所使用的可选简短持久化显示标签。面向模型的委派会提供其已有的 `description` ；底层调用方无需凭空构造展示元数据。可继续启动始终携带自身的必填标签。`signal` 是必填项，也是一次性 `start` 的规范取消通道。发布前中止会使 `start()` 在回滚后拒绝；发布后中止会取消已返回 run 的剩余轮次工作，但不会隐藏其 id。请求还可以选择模型、要求结构化输出、限制委派深度、约束子 agent 工具或设置子 agent persona。对于可继续启动或后续操作， ， ， （ ）
@@ -80,13 +80,13 @@ subagent seam 允许一个 agent（ ）
可继续子级不会创建 `SubagentRun` 或 Task。继续执行管理器为每个驻留子 Session 直接拥有一个仅存在于当前进程的 Activation 和一个留存的 `AgentHandle` ，使用 Agent inbox 作为唯一 FIFO， ； `parentSession` 推导接收方，`MessageSource` 仍只表示来源，不表示权限。中断权限被刻意设计得比投递权限更宽：人类出示持久化直接 parent 地址，因此即使 parent Agent 离线，在线 child 仍可被停止；
当 `ctx.sessionProjections` 可用时，服务会注册两个投影单元。`subagentTiming` 会在每个描述符处重置，使 fork 种子中的祖先工作不会计入 child 总量，随后累加 `turn/start` → `turn/end` 活跃时间，并为未结束的轮次保留同一切面的 `active.since` 和 `active.through` 边界；在该轮次保持未结束期间，`active.through` 会跟随最近折叠的事件，从而为 inactive 消费方提供保守的崩溃上界，又不会混入更新的会话元数据。`subagent` 以同样的 last-wins 重置纪律 从 `subagent/descriptor` 事件折叠持久化身份——模式与创建标签——因此 fork 种子中的祖先描述符只在 child 自身的描述符覆盖之前有效；畸形或版本不识别的载荷折叠为可序列化的 `null` 哨兵——与没有描述符的日志不可区分，且能完好通过每个 JSON 推送帧，让 消费方以之替换掉手中过时的身份而非永久滞 留——绝不抛错。
当 `ctx.sessionProjections` 可用时，服务会注册两个投影单元。`subagentTiming` 会在每个描述符处重置，使 fork 种子中的祖先工作不会计入 child 总量，随后累加 `turn/start` → `turn/end` 活跃时间，并为未结束的轮次保留同一切面的 `active.since` 和 `active.through` 边界；在该轮次保持未结束期间，`active.through` 会跟随最近折叠的事件，从而为 inactive 消费方提供保守的崩溃上界，又不会混入更新的会话元数据。`subagent` 以同样的 last-wins 重置规则 从 `subagent/descriptor` 事件折叠持久化身份——模式与创建标签——因此 fork 种子中的祖先描述符只在 child 自身的描述符覆盖之前有效；畸形或版本不识别的载荷折叠为可序列化的 `null` 哨兵——与没有描述符的日志不可区分，且能完好通过每个 JSON 推送帧，使 消费方替换陈旧身份而不是将其保 留——绝不抛错。
`registerContinuableSetup()` 允许可选包添加子级作用域能力，而无需让继续执行管理器知道这些能力的名称。贡献会在 Activation 发布前同步安装，在设置失败时一并回滚，并随子级作用域释放。新授权须等到下一个 Activation，
## 收集模型
面向模型的工具默认同步收集：先等待子 agent 结果，再 dispose 运行，然后才返回。一次性后台委派会在工具中注册普通 Task， ， `description` 持久化为可选显示标签。可继续后台委派会调用 `ctx.subagents.startContinuable()` ，只返回持久化子 agent id； `send_message` 后续操作工具发送后续工作，`interrupt()` 只停止当前轮次而不 dispose 子 agent， `ctx.agents` 可用时，继续执行管理器才会存在，而会话持久化按每项继续执行操作解析。与此独立，`listChildren()` 枚举在线会话存储与可选会话持久化的在线优先合并——持久化缺席时仅枚举在线 child， `subagent` 投影单元供给每个 child 的持久化模式与标签：在线 child 取注册表的水位快照；冷 child 先取可选投影缓存的持久化行，且仅当其 `seq` 门证明该值折叠自 child 自身后缀（ `corrupt` diagnostic） ； `corrupt` diagnostic， `unavailable` （ ） ， （ ） `origin: 'subagent'` 的 header 派生读取时的 `hasChildren` 提示；它不会读取后代事件日志，展开后仍以描述符支撑的 child 目录为权威依据。UI 等服务消费方可以保留两种模式，并为无标签的一次性 child 选择回退展示；面向模型的 `list_agents` 工具只投影 `continuable` 条目，通过在线 Agent 注册表细化状态（`running` ／ `idle` ／ `complete` ），并在 `descendants` scope 下遍历 `listDescendants()` 。列表操作会把调用方的取消信号转发到每次持久化读取，在这些 await 前后检查取消，并将每次检测到的中止报告为 `SubagentError` 错误码 `CANCELLED` ；投影注册表未挂载则以 `SUBAGENT_CONTROL_PROJECTIONS_UNAVAILABLE` 响亮失败 ，会话存储缺失则以 `SUBAGENT_CONTROL_SESSION_STORE_UNAVAILABLE` 响亮失败 。完整契 约见[后台 subagent 任务 Agent Note ](../../../.agents/notes/implemented/feature/2026-07-08-background-subagent-tasks.md )、[可继续后台 subagent Agent Note ](../../../.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.md )、[持久化目录 Agent Note ](../../../.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.md )、[服务合并 Agent Note ](../../../.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.md )、[能力 seam Agent Note ](../../../.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md )和 `src/types.ts` 。
面向模型的工具默认同步收集：先等待子 agent 结果，再 dispose 运行，然后才返回。一次性后台委派会在工具中注册普通 Task， ， `description` 持久化为可选显示标签。可继续后台委派会调用 `ctx.subagents.startContinuable()` ，只返回持久化子 agent id； `send_message` 后续操作工具发送后续工作，`interrupt()` 只停止当前轮次而不 dispose 子 agent， `ctx.agents` 可用时，继续执行管理器才会存在，而会话持久化按每项继续执行操作解析。与此独立，`listChildren()` 枚举在线会话存储与可选会话持久化的在线优先合并——持久化缺席时仅枚举在线 child， `subagent` 投影单元供给每个 child 的持久化模式与标签：在线 child 取注册表的水位快照；冷 child 先取可选投影缓存的持久化行，且仅当其 `seq` 门证明该值折叠自 child 自身后缀（ `corrupt` diagnostic） ； `corrupt` diagnostic， `unavailable` （ ） ， （ ） `origin: 'subagent'` 的 header 派生读取时的 `hasChildren` 提示；它不会读取后代事件日志，展开后仍以描述符支撑的 child 目录为权威依据。UI 等服务消费方可以保留两种模式，并为无标签的一次性 child 选择回退展示；面向模型的 `list_agents` 工具只投影 `continuable` 条目，通过在线 Agent 注册表细化状态（`running` ／ `idle` ／ `complete` ），并在 `descendants` scope 下遍历 `listDescendants()` 。列表操作会把调用方的取消信号转发到每次持久化读取，在这些 await 前后检查取消，并将每次检测到的中止报告为 `SubagentError` 错误码 `CANCELLED` ；投影注册表未挂载则以 `SUBAGENT_CONTROL_PROJECTIONS_UNAVAILABLE` 明确报错 ，会话存储缺失则以 `SUBAGENT_CONTROL_SESSION_STORE_UNAVAILABLE` 明确报错 。完整约定 见[后台 subagent 任务 Agent Note ](../../../.agents/notes/implemented/feature/2026-07-08-background-subagent-tasks.md )、[可继续后台 subagent Agent Note ](../../../.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.md )、[持久化目录 Agent Note ](../../../.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.md )、[服务合并 Agent Note ](../../../.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.md )、[能力 seam Agent Note ](../../../.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md )和 `src/types.ts` 。
可继续 Activation 会等待 best-effort 的最终会话 flush，
xjt