@deepseek-ai/dsh-subagent 0.0.1-rc.1 → 0.0.1-rc.2

package/README.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/subagent/subagent/README.md
-README.md: 42a10adeccb8e299e25ff0a5e0a918ef09b79617
-README.zh.md: 34e2ed6c1ca23df9b3158f3caea10cd19bafa841
+README.md: edddb39a2c197eb7c8acb27f5b7f6b8c6016c517
+README.zh.md: e28a8794cfb227dd475ea2b4c42605a90ec7fa1d

package/README.md

@@ -44,7 +44,7 @@ Every in-process child is composed by one call, `applyChildComposition(childCtx,
 
 `childSessionMeta()` records the joined preset id on the child's durable header for the same reason a top-level session records its own: the preset decides the tool schemas and prompt sections the model saw, so a cold read of the child's history has to rebuild that composition rather than the deployment default. It is read from the parent's live scope chain, not from the parent header, because a parent that switched preset while blank runs on the newer composition while its header still names the older one.
 
-Continuable creation is the optional `SubagentProvider.prepareContinuable?()` method: its presence is the capability check, so the service rejects a configured continuable start on a provider without it, while a provider that has it may still serve ordinary one-shot delegations. The method returns only a detached `ContinuableCreateSpec` (`{ seed? }`) — data, never a capability: it carries no Agent, `AgentHandle`, prompt delivery, result, disposal, or resume operation, because the continuation manager owns identity reservation, composition, Agent creation, prompt delivery, cold resume, ownership, and disposal after preparation. A one-shot `SubagentRun` represents one disposable foreground delegation with one result and no cold-resume operation.
+Continuable creation is the optional `SubagentProvider.prepareContinuable?()` method: its presence is the capability check, so the service rejects a configured continuable start on a provider without it, while a provider that has it may still serve ordinary one-shot delegations. The method returns only a detached `ContinuableCreateSpec` (`{ seed? }`) — data, never a capability: it carries no Agent, `AgentHandle`, prompt delivery, result, disposal, or resume operation, because the continuation manager owns identity reservation, composition, Agent creation, prompt delivery, cold resume, ownership, and disposal after preparation. A one-shot `SubagentRun` represents one disposable foreground delegation with one result and no cold-resume operation. The service may invoke one provider concurrently for distinct siblings: each start or preparation owns its mutable state and cancellation path, and one operation's failure, result, or cleanup must not settle or release another. A provider may queue its own capacity internally without changing that independence contract.
 
 ## The durable descriptor
 
@@ -64,7 +64,7 @@ Both in-process delegation paths fix the child's permission scope at the delegat
 
 `provider.start(request): Promise<SubagentRun>` is the ownership-transfer boundary; the delegation tool also uses it inside its one-shot Task-backed background path. Before fulfillment, the provider owns setup and must cancel, roll back, and quiesce unpublished resources on every failure. After fulfillment, the caller owns the run and must call `dispose()` on every path; remaining prompt and turn work belongs to `SubagentRun.result`.
 
-`SubagentRun.result` resolves to `{ output, structured?, stopReason }`. Child-level failures resolve with a non-`completed` reason; only an infrastructure fault that the seam cannot represent may reject. `dispose()` is idempotent, cancels remaining work, and waits for both result settlement and child-resource quiescence. A result rejection remains on `result`; `dispose()` rejects only for an independent resource-release failure.
+`SubagentRun.result` resolves to `{ output, structured?, stopReason }`. Child-level failures resolve with a non-`completed` reason; only an infrastructure fault that the seam cannot represent may reject. `dispose()` is idempotent, cancels remaining work, and waits for both result settlement and child-resource quiescence. A result rejection remains on `result`; `dispose()` rejects only for an independent resource-release failure. `output` and the `subagent/end` event's `lastAssistantMessage` use the exported `AssistantOutputFold`/`finalAssistantOutput` helpers to select the child's last non-empty assistant message, or its accumulated assistant text when no such message exists. `output` is `[]` and the event field is absent when the child produced neither ([`SubagentResult.output`](../../../docs/subsystems/subagent.md#the-terminal-result-subagentresult) owns the result contract).
 
 A local run publishes an ordinary child agent/session before `start()` fulfills, returns that shared session id as `SubagentRun.id`, exposes the exact child as `SubagentRun.localAgent`, records `request.parent.session.id` in the child's `parentSession` header, and appends the resolved descriptor inside its initial turn. Remote providers instead mint a parent-scoped lifecycle id and return `localAgent: undefined`; without a local child session, their one-shot runs are not part of trace-backed enumeration.
 
@@ -76,6 +76,14 @@ The manager derives three internal residency conditions from Agent quiescence an
 
 The manager reserves the child identity, resolves the durable descriptor, calls `ctx.agents.create()` (or `ctx.agents.resume()` for cold resume) through a private activation-owner scope, installs the returned `AgentHandle` in the Activation, establishes any continuable-parent ownership, and then submits the prompt. Cold resume never dispatches through a provider because the persisted Session already holds the initial prefix and the folded descriptor is the whole reconstruction input.
 
+### Settlement delivery
+
+When a resident Activation settles, the manager tells the child's durable direct parent, in the parent's own turn stream, that the child produced everything it is going to. Delivery is unconditional for every child whose id a caller actually received: it does not consider whether the child called `report`, because the endings that most need an account — a token ceiling, a model failure, cancellation, teardown — are exactly the ones where the child never got to choose. A materialization rolled back before its first accepted message stays silent, since that caller was told the child was not established. The message carries the epoch's stop reason, its final assistant content when it produced any, and durable provenance `{ kind: 'subagent-settled', form: 'notice', senderSessionId: <child-id> }` — a different source kind from a child-authored `subagent-report`, so a transcript never credits the child with words the runtime wrote.
+
+Two ordering rules make the delivery reliable rather than lucky, and both are why this belongs to the manager instead of an external `subagent/end` listener. First, the send happens **before** the child's ownership release, while the parent still counts the child and is therefore structurally unable to be judged settled. Second, a parent that is itself a resident Activation receives the message through the same waking-admission accounting as a report, so the window between the synchronous send and the microtask that admits it is not mistaken for quiescence — `Agent.status` folds context maintenance into `idle`, and a waking send behind maintenance only arms a deferred wake. Without either rule the parent can be disposed with the notice still in an inbox that `cancel()` clears, which loses it silently.
+
+An idle parent receives the notice as one ordinary later turn. A busy parent is steered into its nearest step boundary instead, so several children settling together cost one step rather than one turn each; steering rather than injecting also means a driver that retires between the status read and the send still claims the message. A parent whose own lineage is already draining receives the notice by injection, with no wake at all: `Agent.followup()` on a quiescent parent starts a turn and `cancel()` does not arm against a later one, so waking during teardown would spend a model request on an Agent its host is about to dispose — once per tree layer, since each layer's notice then wakes the layer above it. The injected message reaches a parent that is still reading its inbox, and the log records the account either way, but it does not outlive that parent's own disposal: `AgentHandle.dispose()` is a `keepInbox: false` cancel, which durably cancels an unclaimed notice. A resumed parent therefore has no pending notice to read: `list_agents` tells it which children exist and whether each is live or stored, while the outcome itself stays in the child's own Session, which a `send_message` reaches by resuming that child. A parent that has left the registry is not an error: the notice is dropped and the child's own Session remains the durable record. Delivery never blocks or fails teardown — a rejected send is logged, because retaining a child to retry a notice would pin its whole ancestry in `waiting` forever.
+
 A continuation-managed parent Activation records each child Session id in an `ownedChildren` set before the child can run and disposes only after every owned child Activation completes `AgentHandle` disposal (child-first). Teardown propagates Agent cancellation top-down before awaiting slow descendants, while handle release remains child-first. Top-level and other non-continuation Agents have no Activation and stay outside this waiting graph. Final settlement awaits a best-effort `ctx.sessions.flush(child.session)` before handle disposal. A listener rejection is logged without failing the Activation because listener participation does not identify a persistence backend; the persisted state may therefore be missing or stale on resume.
 
 ## Lifecycle events
@@ -94,17 +102,31 @@ When `ctx.sessionProjections` is available, the service registers two projection
 
 ## Collection model
 
-The model-facing tool collects synchronously by default: it awaits the child result and disposes the run before returning. One-shot background delegation registers a plain Task in the tool, whose generic status, collection, and cancellation tools own later interaction, and persists its model-supplied `description` as the optional display label. Continuable background delegation calls `ctx.subagents.startContinuable()` and returns only the durable child id; the child owns its own turns from inbox acceptance, so there is no Task and no result promise — a caller sends later work with the `send_message` follow-up tool, and `interrupt()` stops only the current turn without disposing the child, and the durable child Session remains the source of the child's detailed output. The continuation manager exists only while `ctx.agents` is available, and session persistence is resolved per continuation operation. Independently, `listChildren()` enumerates the live-preferred merge of the live session store and optional session persistence — live-only when persistence is absent, since a cold child cannot be resumed then either — and serves each child's durable mode/label from the registered `subagent` projection unit: the registry's watermark snapshot for a live child; for a cold one, a durable projection-cache row when it serves an own-suffix identity — its `seq` gate proves the value postdates the fork seed, where a child's own descriptor is immutable once appended — else one bounded-concurrency persistence inspection folded through the registry, whose result must still name the enumerated lifecycle (a re-published id degrades to a `corrupt` diagnostic). A throwing cache read renders no verdict — the cache is derived data — and silently falls through to that authoritative re-fold. The projection fold is the single classification authority; listing parses no descriptor itself. A served identity produces a child row; a settled candidate whose fold served no identity is a `corrupt` diagnostic, a failed inspection is a transient `unavailable` retried on the next listing, and a running candidate without an identity yet is omitted (the creation window before its descriptor is appended). It never consults the continuation manager, Agent registrations, Activations, or providers. Each child row derives its read-time `hasChildren` hint from merged headers carrying durable `origin: 'subagent'`; it does not read descendant event logs, and the descriptor-backed child catalog remains authoritative when expanded. Service consumers such as a UI can retain both modes and choose a fallback for an unlabeled one-shot child; the model-facing `list_agents` tool projects only `continuable` entries and refines status through the live Agent registry (`running`/`idle`/`complete`) and walks `listDescendants()` for its `descendants` scope. The listing forwards the caller's signal to every persistence read, checks cancellation around each of those awaits, and reports every observed abort as `SubagentError` code `CANCELLED`; an unmounted projection registry fails loud with `SUBAGENT_CONTROL_PROJECTIONS_UNAVAILABLE`, and a missing session store with `SUBAGENT_CONTROL_SESSION_STORE_UNAVAILABLE`. See the [background subagent tasks Agent Note](../../../.agents/notes/implemented/feature/2026-07-08-background-subagent-tasks.md), the [continuable background subagents Agent Note](../../../.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.md), the [durable catalog Agent Note](../../../.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.md), the [merged-service Agent Note](../../../.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.md), the [capability-seam Agent Note](../../../.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md), and `src/types.ts` for the complete contracts.
+The model-facing tool collects synchronously by default: it awaits the child result and disposes the run before returning. One-shot background delegation registers a plain Task in the tool, whose generic status, collection, and cancellation tools own later interaction, and persists its model-supplied `description` as the optional display label. Continuable background delegation calls `ctx.subagents.startContinuable()` and returns only the durable child id; the child owns its own turns from inbox acceptance, so there is no Task and no result promise — a caller sends later work with the `send_message` follow-up tool, and `interrupt()` stops only the current turn without disposing the child, and the durable child Session remains the source of the child's detailed output. The continuation manager exists only while `ctx.agents` is available, and session persistence is resolved per continuation operation. Independently, `listChildren()` enumerates the live-preferred merge of the live session store and optional session persistence — live-only when persistence is absent, since a cold child cannot be resumed then either — and serves each child's durable mode/label from the registered `subagent` projection unit: the registry's watermark snapshot for a live child; for a cold one, a durable projection-cache row when it serves an own-suffix identity — its `seq` gate proves the value postdates the fork seed, where a child's own descriptor is immutable once appended — else one bounded-concurrency persistence inspection folded through the registry, whose result must still name the enumerated lifecycle (a re-published id degrades to a `corrupt` diagnostic). A throwing cache read renders no verdict — the cache is derived data — and silently falls through to that authoritative re-fold. The projection fold is the single classification authority; listing parses no descriptor itself. A served identity produces a child row; a settled candidate whose fold served no identity is a `corrupt` diagnostic, a failed inspection is a transient `unavailable` retried on the next listing, and a running candidate without an identity yet is omitted (the creation window before its descriptor is appended). It never consults the continuation manager, Agent registrations, Activations, or providers. Each child row derives its read-time `hasChildren` hint from merged headers carrying durable `origin: 'subagent'`; it does not read descendant event logs, and the descriptor-backed child catalog remains authoritative when expanded. Service consumers such as a UI can retain both modes and choose a fallback for an unlabeled one-shot child; the model-facing `list_agents` tool projects only `continuable` entries and refines status through the live Agent registry and maps storage-only to its resumable-not-terminal `ready` (`running`/`idle`/`ready`) and walks `listDescendants()` for its `descendants` scope. The listing forwards the caller's signal to every persistence read, checks cancellation around each of those awaits, and reports every observed abort as `SubagentError` code `CANCELLED`; an unmounted projection registry fails loud with `SUBAGENT_CONTROL_PROJECTIONS_UNAVAILABLE`, and a missing session store with `SUBAGENT_CONTROL_SESSION_STORE_UNAVAILABLE`. See the [background subagent tasks Agent Note](../../../.agents/notes/implemented/feature/2026-07-08-background-subagent-tasks.md), the [continuable background subagents Agent Note](../../../.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.md), the [durable catalog Agent Note](../../../.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.md), the [merged-service Agent Note](../../../.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.md), the [capability-seam Agent Note](../../../.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md), and `src/types.ts` for the complete contracts.
 
 Continuable Activations await a best-effort final session flush without treating listener participation as durability confirmation. One-shot runs retain best-effort session checkpointing, so a completed one-shot child is discoverable after disposal only when its session actually reached persistence; the service does not invent a catalog entry from Task history when that checkpoint is absent.
 
 ## Model Experience
 
+### Settlement notice
+
+#### What the model sees
+
+One user-role parent message opening with the outcome — `Background subagent <child-id> finished and will do no further work unless you send it more.`, or the matching line for a child that was stopped, ran out of room, declined, or failed — followed by `Its closing message:` and the child's final assistant content, or `It left no closing message.` when it produced none. This is the service's only direct parent-side contribution; delegation schemas, parent continuation and discovery, and the child-scoped `report` belong to `dsh-tool-subagent`, `dsh-tool-subagent-control`, and `dsh-tool-subagent-report`.
+
+#### Token effect
+
+One notice per settled Activation in the parent's request, sized by the child's final message. A child that both reports and settles costs the parent both.
+
+#### KV Cache effect
+
+Append-only in the parent: the notice follows its reusable request prefix. Reaching an idle parent starts one independent model request; reaching a busy one does not.
+
 ### Child delegation-scope statement
 
 #### What the model sees
 
-Every in-process child's runtime-context snapshot carries the `subagent:delegation` statement below, after the sandbox-policy and approval-policy sentences; parent-side rendering stays with `dsh-tool-subagent` (delegation schemas), `dsh-tool-subagent-control` (continuation and discovery), and `dsh-tool-subagent-report` (the child-scoped `report`).
+Every in-process child's runtime-context snapshot carries the `subagent:delegation` statement below, after the sandbox-policy and approval-policy sentences.
 
 ##### The delegation-scope statement
 
@@ -129,4 +151,4 @@ Prefix-stable within a child: the statement never changes during the child's lif
 - **Process-local residency** — the Activation inbox and ownership graph do not coordinate two harness processes; concurrent access to one persistence store still requires a durable mailbox and cross-process lease protocol.
 - **No replay of accepted-but-unlogged messages** — only messages written to the child Session log are reconstructable with the source that supplied them. A crash may lose an accepted initial prompt or follow-up that never reached the log; a later authorized message can cold-resume the child, but the lost message is not replayed automatically.
 - **No durable report mailbox** — reports require a live direct parent and provide acceptance identity rather than exactly-once delivery or a read receipt.
-- **Lifecycle events are observe-only** — a run-affecting `subagent/end` continuation or decision surface waits for a concrete consumer.
+- **Lifecycle events are observe-only** — a run-affecting `subagent/end` continuation or decision API waits for a concrete consumer.

package/README.zh.md

@@ -44,7 +44,7 @@ subagent seam 允许一个 agent（智能体）通过具名提供方把工作委
 
 `childSessionMeta()` 把所加入的 preset id 记在子 agent 的持久化 header 上，理由与顶层会话记录自己的那一个相同：preset 决定了模型所见的工具 schema 与提示段，因此冷读子 agent 的历史时必须重建那份组装，而不是部署默认值。该值从父方**活着的** scope 链读取，而不是从父方 header 读取，因为在空白期切换过 preset 的父方运行在更新的那份组装上，而它的 header 仍写着旧的那个。
 
-可继续创建对应可选的 `SubagentProvider.prepareContinuable?()` 方法：方法是否存在就是能力检查，因此服务会在没有该方法的提供方上拒绝已配置的可继续启动，而具备该方法的提供方仍可服务普通一次性委派。该方法只返回分离的 `ContinuableCreateSpec`（`{ seed? }`）——这是数据，绝非能力：它不携带任何 Agent、`AgentHandle`、提示词投递、结果、dispose 或恢复操作，因为准备之后，继续执行管理器拥有身份预留、组合、Agent 创建、提示词投递、冷恢复、所有权和 dispose。一次性 `SubagentRun` 表示一次可 dispose 的前台委派，只有一个结果，且没有冷恢复操作。
+可继续创建对应可选的 `SubagentProvider.prepareContinuable?()` 方法：方法是否存在就是能力检查，因此服务会在没有该方法的提供方上拒绝已配置的可继续启动，而具备该方法的提供方仍可服务普通一次性委派。该方法只返回分离的 `ContinuableCreateSpec`（`{ seed? }`）——这是数据，绝非能力：它不携带任何 Agent、`AgentHandle`、提示词投递、结果、dispose 或恢复操作，因为准备之后，继续执行管理器拥有身份预留、组合、Agent 创建、提示词投递、冷恢复、所有权和 dispose。一次性 `SubagentRun` 表示一次可 dispose 的前台委派，只有一个结果，且没有冷恢复操作。服务可以针对不同的同级子 agent 并发调用同一提供方：每次启动或准备都拥有各自的可变状态和取消路径，一项操作的失败、结果或清理不得使另一项操作结算或释放。提供方可以在内部按自身容量排队，但不得改变这项独立性约定。
 
 ## 持久化描述符
 
@@ -64,7 +64,7 @@ subagent seam 允许一个 agent（智能体）通过具名提供方把工作委
 
 `provider.start(request): Promise<SubagentRun>` 是所有权转移边界；委派工具也会在其由 Task 支撑的一次性后台路径中使用它。兑现前，提供方拥有设置过程，并且每次失败时都必须取消、回滚并使未发布资源完全停稳。兑现后，调用方拥有该运行，并且必须在每条路径上调用 `dispose()`；剩余提示词和轮次工作属于 `SubagentRun.result`。
 
-`SubagentRun.result` 兑现为 `{ output, structured?, stopReason }`。子 agent 级失败会以非 `completed` 原因兑现；只有 seam 无法表示的基础设施故障才可以拒绝。`dispose()` 是幂等的，会取消剩余工作，并等待结果结算以及子 agent 资源完全停稳。`result` 的 rejection 仍归 `result` 通道；只有独立的资源释放失败会使 `dispose()` 拒绝。
+`SubagentRun.result` 兑现为 `{ output, structured?, stopReason }`。子 agent 级失败会以非 `completed` 原因兑现；只有 seam 无法表示的基础设施故障才可以拒绝。`dispose()` 是幂等的，会取消剩余工作，并等待结果结算以及子 agent 资源完全停稳。`result` 的 rejection 仍归 `result` 通道；只有独立的资源释放失败会使 `dispose()` 拒绝。`output` 与 `subagent/end` 事件的 `lastAssistantMessage` 使用导出的 `AssistantOutputFold`／`finalAssistantOutput` 辅助函数选取子 agent 最后一条非空 assistant 消息；若没有这类消息，则选取其累积的 assistant 文本。子 agent 两种输出均未产生时，`output` 为 `[]`，该事件字段缺省（结果约定归 [`SubagentResult.output`](../../../docs/subsystems/subagent.md#the-terminal-result-subagentresult) 所有）。
 
 本地运行会在 `start()` 兑现前发布普通的子 agent／会话，把该共享会话 id 作为 `SubagentRun.id` 返回，以 `SubagentRun.localAgent` 公开准确的子 agent，把 `request.parent.session.id` 记录到子 agent 的 `parentSession` header，并在其初始轮次内追加已解析的描述符。远程提供方则生成 parent 作用域的生命周期 id，并返回 `localAgent: undefined`；由于没有本地 child 会话，其一次性运行不会进入基于追踪的枚举结果。
 
@@ -76,6 +76,14 @@ subagent seam 允许一个 agent（智能体）通过具名提供方把工作委
 
 管理器预留子 agent 身份、解析持久化描述符，通过私有的 activation-owner 作用域调用 `ctx.agents.create()`（冷恢复时为 `ctx.agents.resume()`），把返回的 `AgentHandle` 安装到 Activation 中，建立任何可继续父级所有权，然后提交提示词。冷恢复绝不通过提供方分发，因为持久化 Session 已持有初始前缀，折叠后的描述符即是全部重建输入。
 
+### 结算投递
+
+当一个驻留 Activation 结算时，管理器会在父级自身的轮次流中告知该子级持久化的直接父级：这个子级已经产出它将产出的全部内容。对每个调用方真正拿到过 id 的子级，这条投递都是无条件的：它不考虑该子级是否调用过 `report`，因为最需要这条投递的结束方式——token 上限、模型失败、取消、拆卸——恰恰是子级根本没有机会选择的那些。在第一条消息被接受之前就回滚的物化保持静默，因为那位调用方已被告知该子级未建立。消息会携带该 epoch 的终止原因、它产出过的最终 assistant 内容，以及持久化来源 `{ kind: 'subagent-settled', form: 'notice', senderSessionId: <child-id> }`——与子级自撰的 `subagent-report` 是不同的来源 kind，因此 transcript（文本记录）绝不会把运行时写下的话算到子级头上。
+
+有两条顺序规则让这条投递可靠而非侥幸，它们也正是这件事属于管理器而非外部 `subagent/end` listener 的原因。第一，发送发生在子级所有权释放**之前**，此时父级仍然计入该子级，因此在结构上不可能被判定为已结算。第二，本身就是驻留 Activation 的父级会通过与 report 相同的唤醒准入记账接收该消息，因此同步发送与承认它的那个 microtask 之间的窗口不会被误判为静止——`Agent.status` 会把上下文维护折叠成 `idle`，而维护期间的唤醒发送只会预置一次延后唤醒。缺少其中任一条规则，父级都可能在通知仍留在 inbox 时被 dispose，而 `cancel()` 会清空该 inbox，于是通知被静默丢失。
+
+空闲父级会以一个普通的后续轮次收到该通知。繁忙父级则被 steer 到其最近的 step 边界，因此同时结算的多个子级只消耗一个 step，而不是各自一个轮次；采用 steer 而非 inject 还意味着：即便驱动在状态读取与发送之间退出，该消息仍会被认领。若父级自身所在的谱系已在 draining，则该通知改为 inject 送达，完全不唤醒：对静息父级调用 `Agent.followup()` 会开启一个轮次，而 `cancel()` 不会对之后的轮次设防，因此在拆卸期间唤醒，会在宿主即将 dispose 的 Agent 上白花一次模型请求——而且每层树各一次，因为每层自己的通知又会唤醒它上面那层。被 inject 的消息会送达仍在读取自身 inbox 的父级，而无论如何日志都会记录这份记账；但它不会比该父级自身的 dispose 活得更久：`AgentHandle.dispose()` 是一次 `keepInbox: false` 的 cancel，会持久地取消尚未被认领的通知。因此 resume 后的父级没有待处理通知可读：`list_agents` 只告诉它有哪些子级、各自是在线还是仅存于存储；结局本身留在子级自己的 Session 里，一次 `send_message` 会通过 resume 该子级把它取回。已离开注册表的父级不算错误：通知被丢弃，子级自身的 Session 仍是持久记录。投递绝不会阻塞或使拆卸失败——发送被拒只会记录日志，因为为了重试一条通知而保留子级，会把它的整条祖先链永久钉在 `waiting` 上。
+
 受继续执行管理的父级 Activation 会在子 agent 能够运行之前，把每个子 agent 的 Session id 记录到 `ownedChildren` 集合中，并且只有在每个所拥有的子 agent Activation 完成 `AgentHandle` dispose 之后才会 dispose（子先于父）。拆卸会先自顶向下传播 Agent 取消，再等待缓慢的后代，而 handle 释放仍保持 child-first。顶层及其他非继续执行的 Agent 没有 Activation，处于该等待图之外。最终结算会在 dispose handle 前等待 best-effort 的 `ctx.sessions.flush(child.session)`。listener rejection 会被记录，但不会使 Activation 失败，因为 listener 是否参与无法标识持久化后端；因此，恢复时持久化状态可能缺失或陈旧。
 
 ## 生命周期事件
@@ -94,17 +102,31 @@ subagent seam 允许一个 agent（智能体）通过具名提供方把工作委
 
 ## 收集模型
 
-面向模型的工具默认同步收集：先等待子 agent 结果，再 dispose 运行，然后才返回。一次性后台委派会在工具中注册普通 Task，其通用状态、收集和取消工具负责后续交互，并将模型提供的 `description` 持久化为可选显示标签。可继续后台委派会调用 `ctx.subagents.startContinuable()`，只返回持久化子 agent id；子 agent 自 inbox 接受起就拥有自己的轮次，因此没有 Task、也没有结果 promise——调用方通过 `send_message` 后续操作工具发送后续工作，`interrupt()` 只停止当前轮次而不 dispose 子 agent，而持久化子 agent Session 仍是子 agent 详细输出的来源。只有 `ctx.agents` 可用时，继续执行管理器才会存在，而会话持久化按每项继续执行操作解析。与此独立，`listChildren()` 枚举在线会话存储与可选会话持久化的在线优先合并——持久化缺席时仅枚举在线 child，因为那时冷 child 本就无法恢复——并由已注册的 `subagent` 投影单元供给每个 child 的持久化模式与标签：在线 child 取注册表的水位快照；冷 child 先取可选投影缓存的持久化行，且仅当其 `seq` 门证明该值折叠自 child 自身后缀（fork 种子之后——自有描述符一经追加即不可变）才直接采用，否则经一次有界并发的持久化 inspect 再经注册表折叠，且 inspect 结果必须仍指向枚举时的生命周期（同 id 被重新发布的会话降级为 `corrupt` diagnostic）。缓存读取抛错不产生判决——缓存是派生数据——静默落到该权威重折。投影折叠是唯一的分类权威；列表自身不解析任何描述符。取得身份值即产出 child 行；已定局而折叠未产出身份的候选是 `corrupt` diagnostic，inspect 失败是瞬时的 `unavailable`（下次列表重试），运行中而暂无身份值的候选整行省略（描述符尚未追加的创建窗口）。它不查询继续执行管理器、Agent 注册信息、Activation 或提供方。每个 child 行都会根据合并结果中携带持久化 `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；子 agent 自 inbox 接受起就拥有自己的轮次，因此没有 Task、也没有结果 promise——调用方通过 `send_message` 后续操作工具发送后续工作，`interrupt()` 只停止当前轮次而不 dispose 子 agent，而持久化子 agent Session 仍是子 agent 详细输出的来源。只有 `ctx.agents` 可用时，继续执行管理器才会存在，而会话持久化按每项继续执行操作解析。与此独立，`listChildren()` 枚举在线会话存储与可选会话持久化的在线优先合并——持久化缺席时仅枚举在线 child，因为那时冷 child 本就无法恢复——并由已注册的 `subagent` 投影单元供给每个 child 的持久化模式与标签：在线 child 取注册表的水位快照；冷 child 先取可选投影缓存的持久化行，且仅当其 `seq` 门证明该值折叠自 child 自身后缀（fork 种子之后——自有描述符一经追加即不可变）才直接采用，否则经一次有界并发的持久化 inspect 再经注册表折叠，且 inspect 结果必须仍指向枚举时的生命周期（同 id 被重新发布的会话降级为 `corrupt` diagnostic）。缓存读取抛错不产生判决——缓存是派生数据——静默落到该权威重折。投影折叠是唯一的分类权威；列表自身不解析任何描述符。取得身份值即产出 child 行；已定局而折叠未产出身份的候选是 `corrupt` diagnostic，inspect 失败是瞬时的 `unavailable`（下次列表重试），运行中而暂无身份值的候选整行省略（描述符尚未追加的创建窗口）。它不查询继续执行管理器、Agent 注册信息、Activation 或提供方。每个 child 行都会根据合并结果中携带持久化 `origin: 'subagent'` 的 header 派生读取时的 `hasChildren` 提示；它不会读取后代事件日志，展开后仍以描述符支撑的 child 目录为权威依据。UI 等服务消费方可以保留两种模式，并为无标签的一次性 child 选择回退展示；面向模型的 `list_agents` 工具只投影 `continuable` 条目，通过在线 Agent 注册表细化状态，并把仅存于存储的状态映射为可恢复而非终态的 `ready`（`running`／`idle`／`ready`），并在 `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，但不会把 listener 参与视为持久性确认。一次性运行保留尽力执行的会话检查点，因此已完成的一次性 child 只有在其会话确实进入持久化存储时，才可在 dispose 后继续被发现；如果该检查点缺失，服务不会根据 Task 历史虚构目录条目。
 
 ## 模型体验
 
+### 结算通知
+
+#### 模型看到的内容
+
+一条用户角色的父级消息，开头是结果本身——`Background subagent <child-id> finished and will do no further work unless you send it more.`，或子级被停止、耗尽额度、拒绝任务或失败时的对应句子——随后是 `Its closing message:` 与子级的最终 assistant 内容；若子级没有产出内容，则是 `It left no closing message.`。这是本服务面向父级的唯一直接贡献；委派 schema、父级延续与发现以及子级作用域的 `report` 分别归 `dsh-tool-subagent`、`dsh-tool-subagent-control` 和 `dsh-tool-subagent-report` 所有。
+
+#### Token 影响
+
+父级请求中，每个已结算的 Activation 一条通知，长度取决于子级的最终消息。既上报又结算的子级会让父级同时支付两份。
+
+#### KV Cache 影响
+
+在父级中仅追加：通知位于其可复用请求前缀之后。到达空闲父级会启动一次独立的模型请求，到达繁忙父级则不会。
+
 ### 子级委派范围声明
 
 #### 模型看到的内容
 
-每个进程内子 agent 的运行时上下文快照都携带下方的 `subagent:delegation` 声明，位于沙箱策略与审批策略语句之后；父级侧的渲染仍归 `dsh-tool-subagent`（委派 schema）、`dsh-tool-subagent-control`（延续与发现）和 `dsh-tool-subagent-report`（子级作用域的 `report`）所有。
+每个进程内子 agent 的运行时上下文快照都携带下方的 `subagent:delegation` 声明，位于沙箱策略与审批策略语句之后。
 
 ##### 委派范围声明
 

package/lib/index.js

@@ -1,9 +1,10 @@
 import { Service } from "@deepseek-ai/cordis";
 import { scopeTarget } from "@deepseek-ai/dsh-scope";
 import { assertObjectJsonSchema } from "@deepseek-ai/dsh-tools";
-import { HarnessError, createUserMessage, errorChain } from "@deepseek-ai/dsh-llm";
+import { HarnessError, boundContextSummary, createUserMessage, errorChain } from "@deepseek-ai/dsh-llm";
 import { randomUUID } from "node:crypto";
-import { Session, SessionId, findLastMessageTurnEnd, snapshotJsonValue } from "@deepseek-ai/dsh-session";
+import { foldConsumedWork } from "@deepseek-ai/dsh-agent";
+import { Session, SessionId, snapshotJsonValue } from "@deepseek-ai/dsh-session";
 import { z } from "zod";
 import { accessSync, constants, statSync } from "node:fs";
 import { isAbsolute, resolve } from "node:path";
@@ -52,6 +53,71 @@ function assertSubagentMaxDepth(maxDepth) {
 	if (maxDepth !== void 0 && (typeof maxDepth !== "number" || !Number.isSafeInteger(maxDepth) || maxDepth < 0 || Object.is(maxDepth, -0))) throw new TypeError("subagent maxDepth must be a non-negative safe integer");
 }
 //#endregion
+//#region lib/types/assistant-output.js
+/**
+* Canonical selection of a child's final assistant output. Backend run results
+* and `subagent/end.lastAssistantMessage` apply the same rule: select the last
+* non-empty assistant message. An empty-content message records usage only
+* when the loop appends it after a max-tokens step with no executable blocks,
+* so it does not replace earlier output. If no non-empty message exists,
+* select the accumulated assistant text. Selection is independent of the
+* run's stop reason.
+*
+* @module @deepseek-ai/dsh-subagent/assistant-output
+*/
+/**
+* Incremental fold of the selection rule, for backends that observe a child's
+* output as it streams: session-event backends {@link push} each event, and
+* transports without session events (ACP content chunks) {@link pushText} raw
+* text into the same streamed fallback.
+*/
+var AssistantOutputFold = class {
+	message;
+	partial = [];
+	/**
+	* Fold one session event: a non-empty assistant message becomes the
+	* candidate final answer, and a `text-delta` chunk extends the streamed
+	* fallback; every other event contributes nothing.
+	* @param event - the next observed session event.
+	*/
+	push(event) {
+		if (event.type === "assistant/message") {
+			const content = event.data.message.content;
+			if (content.length > 0) this.message = content;
+		} else if (event.type === "assistant/chunk" && event.data.chunk.type === "text-delta") this.pushText(event.data.chunk.text);
+	}
+	/**
+	* Extend the streamed fallback with text observed outside session events.
+	* @param text - the next streamed text piece (an empty piece is a no-op).
+	*/
+	pushText(text) {
+		if (text.length > 0) this.partial.push(text);
+	}
+	/**
+	* Select the final output folded so far.
+	* @returns the last non-empty assistant message, else the accumulated
+	*   streamed text, or `undefined` when the child produced neither.
+	*/
+	collect() {
+		if (this.message !== void 0) return this.message;
+		const text = this.partial.join("");
+		return text.length > 0 ? [{
+			type: "text",
+			text
+		}] : void 0;
+	}
+};
+/**
+* Apply the selection rule to one complete child-owned event suffix.
+* @param events - the child-owned events (after any seed or epoch boundary).
+* @returns the selected output, or `undefined` when the child produced none.
+*/
+function finalAssistantOutput(events) {
+	const fold = new AssistantOutputFold();
+	for (const event of events) fold.push(event);
+	return fold.collect();
+}
+//#endregion
 //#region lib/types/types.js
 /**
 * The seam's consumer-facing contracts: request, result, and capability types
@@ -133,7 +199,7 @@ function observeRun(emit, provider, parent, run) {
 		emit("subagent/end", {
 			...identity,
 			stopReason: result.stopReason,
-			lastAssistantMessage: result.output
+			...result.output.length === 0 ? {} : { lastAssistantMessage: result.output }
 		}, parent);
 	}, () => {
 		emit("subagent/end", {
@@ -164,6 +230,7 @@ function createActivationObserver(emit, provider, childId, parent) {
 	};
 	let boundary = 0;
 	let captured = { stopReason: "completed" };
+	const terminal = (failure) => failure === void 0 ? captured : { stopReason: "error" };
 	return {
 		start: (child) => {
 			boundary = child.session.events.length;
@@ -171,54 +238,55 @@ function createActivationObserver(emit, provider, childId, parent) {
 		},
 		capture: (child) => {
 			const own = child.session.events.slice(boundary);
-			const output = lastAssistantOutput(own);
+			const output = finalAssistantOutput(own);
 			captured = {
 				stopReason: epochStopReason(own),
 				...output === void 0 ? {} : { output }
 			};
 		},
+		terminal,
 		settle: (failure) => {
-			const output = failure === void 0 ? captured.output : void 0;
+			const { stopReason, output } = terminal(failure);
 			emit("subagent/end", {
 				...identity,
-				stopReason: failure === void 0 ? captured.stopReason : "error",
+				stopReason,
 				...output === void 0 ? {} : { lastAssistantMessage: output }
 			}, parent);
 		}
 	};
 }
 /**
-* Why this child's last ordinary turn ended, for the terminal lifecycle edge.
-* The child's own `turn/end` is authoritative: teardown succeeding says nothing
-* about whether the model errored, hit its token ceiling, or was cancelled, so
-* deriving the reason from disposal would report failed work as completed.
+* Why this child's epoch ended, for the terminal lifecycle edge and the
+* manager's own parent delivery. The child's own log is authoritative:
+* teardown succeeding says nothing about whether the model errored, hit its
+* token ceiling, or was cancelled, so deriving the reason from disposal would
+* report failed work as completed.
+*
+* {@link foldConsumedWork} supplies both halves the raw turn sequence cannot:
+* which turn accounts for the work this epoch consumed, and whether accepted
+* work was cancelled after it without any turn opening over it. A recorded
+* failure still wins over a cancellation — stopping a child that had already
+* failed does not turn its failure into a cancellation.
 * @param events - this epoch's own event suffix.
-* @returns its terminal stop reason; `completed` when no ordinary turn closed.
+* @returns its terminal stop reason; `completed` only for an epoch that both
+*   closed cleanly and had nothing left to run.
 */
 function epochStopReason(events) {
-	const reason = findLastMessageTurnEnd(events)?.data.reason;
-	if (reason === void 0) return "completed";
-	switch (reason.kind) {
+	const { end, droppedUnrun } = foldConsumedWork(events);
+	switch (end?.data.reason.kind) {
 		case "max-tokens": return "max-tokens";
 		case "aborted":
 		case "interrupted": return "aborted";
 		case "error": return "error";
-		case "completed": return "completed";
+		case "blocked": return "refusal";
+		case void 0:
+		case "completed": return droppedUnrun ? "aborted" : "completed";
 		/* v8 ignore next 3 -- `TurnEndReason` is merge-extensible, so this arm needs a
 		* backend that adds a variant; treating an unnameable reason as success would
 		* report failed work as completed. */
 		default: return "error";
 	}
 }
-/**
-* The child's last assistant message content, for one Activation's terminal
-* lifecycle edge. Absent when no assistant message reached the log.
-* @param events - this epoch's own event suffix.
-* @returns its final assistant content, or `undefined` when it produced none.
-*/
-function lastAssistantOutput(events) {
-	return events.findLast((event) => event.type === "assistant/message")?.data.message.content;
-}
 /** Render any listener-thrown value without letting coercion escape containment. */
 function renderThrown(value) {
 	try {
@@ -577,7 +645,8 @@ function seedDescriptorTurn(childId, seed, descriptor) {
 /**
 * Internal continuable-subagent manager: stable child ids, descriptor
 * persistence, activation admission, the live ownership graph, cold resume,
-* and child-first disposal behind `ctx.subagents`.
+* child-first disposal, and settlement delivery to the parent, behind
+* `ctx.subagents`.
 *
 * A continuable child has one durable Session and at most one process-local
 * {@link Activation} — one residency epoch for a reconstructed child Agent. An
@@ -587,6 +656,12 @@ function seedDescriptorTurn(childId, seed, descriptor) {
 * residency while the Agent loop owns all turn ordering and execution. No
 * continuable path creates a Task or an intermediate result-bearing wrapper.
 *
+* Because residency is this manager's alone to end, telling the parent that a
+* child settled is its job too. An external `subagent/end` listener cannot do
+* it correctly: that payload names no parent, the child handle is already
+* disposed by then, and the release that wakes the parent's own settlement
+* watcher has already run. See {@link SubagentContinuationManager.notifySettlement}.
+*
 * @module @deepseek-ai/dsh-subagent
 */
 /**
@@ -599,6 +674,27 @@ function seedDescriptorTurn(childId, seed, descriptor) {
 function disposalOf(activation) {
 	return activation.disposal;
 }
+/**
+* One line telling a parent that a background child is finished and why, in
+* the parent's own task vocabulary.
+* @param childId - the durable child the parent knows by id.
+* @param stopReason - how the child's last ordinary turn ended.
+* @returns the model-facing opening line of the settlement notice.
+*/
+function settlementSummary(childId, stopReason) {
+	const subject = `Background subagent ${childId}`;
+	switch (stopReason) {
+		case "completed": return `${subject} finished and will do no further work unless you send it more.`;
+		case "aborted": return `${subject} was stopped before it finished.`;
+		case "max-tokens": return `${subject} ran out of room before it finished.`;
+		case "refusal": return `${subject} declined the task.`;
+		case "error": return `${subject} failed before it finished.`;
+		/* v8 ignore next 4 -- `SubagentResult['stopReason']` is merge-extensible, so this arm
+		* needs a backend that adds a variant; an unnameable ending is reported as unfinished
+		* rather than silently as success. */
+		default: return `${subject} ended abnormally (${String(stopReason)}) before it finished.`;
+	}
+}
 /** Serialize each durable child's delivery, release, and disposal. */
 var ChildLock = class {
 	tails = /* @__PURE__ */ new Map();
@@ -845,13 +941,26 @@ var SubagentContinuationManager = class {
 				senderSessionId: activation.childId
 			}
 		});
-		const parentActivation = this.activations.get(parent.id);
-		if (delivery === "wakeup" && parentActivation !== void 0 && parentActivation.handle.agent === parent) this.admitWaking(parentActivation, message.id, () => {
+		if (delivery === "wakeup") this.sendWaking(parent, message, () => {
 			this.sendReport(parent, message, delivery);
 		});
 		else this.sendReport(parent, message, delivery);
 		return message.id;
 	}
+	/**
+	* Perform one waking send to a parent, accounted against that parent's own
+	* Activation when it has one. Registering the id before the send is what
+	* keeps a continuation-managed parent from being judged quiescent in the
+	* window between `followup()` and the microtask that admits it.
+	* @param parent - the exact live parent receiving the waking message.
+	* @param message - the message whose id is accounted.
+	* @param send - the synchronous waking send to perform.
+	*/
+	sendWaking(parent, message, send) {
+		const parentActivation = this.activations.get(parent.id);
+		if (parentActivation !== void 0 && parentActivation.handle.agent === parent) this.admitWaking(parentActivation, message.id, send);
+		else send();
+	}
 	/** Send one report while translating only the parent's own rejection. */
 	sendReport(parent, message, delivery) {
 		try {
@@ -956,11 +1065,23 @@ var SubagentContinuationManager = class {
 		}
 		return lineage;
 	}
+	/**
+	* The teardown that closed continuable admission for this agent's lineage.
+	* `'manager'` is the whole manager draining; an Agent is the exact scoped root
+	* whose forest is closing.
+	* @param agent - the agent whose lineage is tested.
+	* @returns the closing teardown, or `undefined` while admission is open.
+	*/
+	closingTeardownFor(agent) {
+		if (this.draining) return "manager";
+		const lineage = this.liveLineage(agent);
+		for (const [root, members] of this.closingScopes) if (members.has(agent) || lineage.includes(root)) return root;
+	}
 	/** Reject new admission once the manager or this exact parent tree began draining. */
 	assertAdmitting(agent) {
-		if (this.draining) throw new SubagentError("continuable subagents are draining; the operation was not admitted", "DRAINING");
-		const lineage = this.liveLineage(agent);
-		for (const [root, members] of this.closingScopes) if (members.has(agent) || lineage.includes(root)) throw new SubagentError(`continuable subagents below parent "${root.id}" are draining; the operation was not admitted`, "DRAINING");
+		const closing = this.closingTeardownFor(agent);
+		if (closing === void 0) return;
+		throw new SubagentError(closing === "manager" ? "continuable subagents are draining; the operation was not admitted" : `continuable subagents below parent "${closing.id}" are draining; the operation was not admitted`, "DRAINING");
 	}
 	/**
 	* Derive residency from Agent quiescence and the owned-child set. `running`
@@ -1088,6 +1209,7 @@ var SubagentContinuationManager = class {
 		});
 		const activation = {
 			childId,
+			parentSession: parent.id,
 			provider,
 			handle,
 			ancestry: new WeakSet([handle.agent, ...parentLineage]),
@@ -1095,6 +1217,7 @@ var SubagentContinuationManager = class {
 			observer,
 			disposal: void 0,
 			accepted: /* @__PURE__ */ new Set(),
+			announced: false,
 			poke: Promise.withResolvers()
 		};
 		this.activations.set(childId, activation);
@@ -1167,9 +1290,11 @@ var SubagentContinuationManager = class {
 			content,
 			source
 		});
-		return this.admitWaking(activation, message.id, () => {
+		const accepted = this.admitWaking(activation, message.id, () => {
 			activation.handle.agent.followup(message);
 		});
+		activation.announced = true;
+		return accepted;
 	}
 	/**
 	* Account one waking send across a resident Activation's settlement window.
@@ -1300,11 +1425,66 @@ var SubagentContinuationManager = class {
 		if (failures.length === 1) failure = failures[0];
 		else if (failures.length > 1) failure = new SubagentError(`subagent "${childId}" activation teardown failed at ${failures.length} boundaries: ` + failures.map((item) => errorChain(item)).join("; "), "ACTIVATION_TEARDOWN_FAILED", { cause: new AggregateError(failures) });
 		this.activations.delete(childId);
+		this.notifySettlement(activation, activation.observer.terminal(failure));
 		this.releaseOwnership(childId);
 		activation.observer.settle(failure);
 		if (failure !== void 0) throw failure;
 	}
 	/**
+	* Tell the durable direct parent that this child produced everything it is
+	* going to. Unconditional for every child the caller received an id for: it
+	* does not consider whether the child reported, because the cases that most
+	* need it — a token ceiling, a model failure, cancellation, teardown — are
+	* exactly the ones where the child never got to choose. A materialization
+	* rolled back before its first acceptance stays silent, since the caller was
+	* told that child was not established. A parent that is no longer live is not
+	* an error; the child's own Session remains the durable record either way.
+	* A parent whose own lineage is already closing receives the notice without a
+	* wake, because teardown is not a reason to start a turn.
+	*
+	* Never blocks disposal. A delivery failure is logged and dropped, because
+	* retaining a child to retry a notice would pin its whole ancestry in
+	* `waiting` forever.
+	* @param activation - the settling Activation, still owned by its parent.
+	* @param terminal - how this epoch ended, as the terminal edge will report it.
+	*/
+	notifySettlement(activation, terminal) {
+		if (!activation.announced) return;
+		try {
+			const parent = this.ctx.agents.get(activation.parentSession);
+			if (parent === void 0) return;
+			const summary = settlementSummary(activation.childId, terminal.stopReason);
+			const message = createUserMessage({
+				content: [{
+					type: "text",
+					text: summary
+				}, ...terminal.output === void 0 ? [{
+					type: "text",
+					text: "It left no closing message."
+				}] : [{
+					type: "text",
+					text: "Its closing message:"
+				}, ...terminal.output]],
+				source: {
+					kind: "subagent-settled",
+					form: "notice",
+					summary: boundContextSummary(summary),
+					senderSessionId: activation.childId
+				}
+			});
+			if (this.closingTeardownFor(parent) !== void 0) {
+				parent.inject(message);
+				return;
+			}
+			this.sendWaking(parent, message, () => {
+				if (parent.status === "idle") parent.followup(message);
+				else parent.steer(message);
+			});
+		} catch (error) {
+			this.ctx.logger.warn(`subagent "${activation.childId}" settlement notice was not delivered to its parent: ` + errorChain(error));
+		}
+	}
+	/**
 	* Request a best-effort final session flush after the child is quiescent.
 	* Listener failure is logged because flush participation cannot identify a
 	* particular persistence backend, and teardown must still release ownership.
@@ -2079,7 +2259,7 @@ async function settleRun(run) {
 //#region lib/types/index.js
 /**
 * Service Definition for the subagent capability seam (`ctx.subagents`): a named-provider registry plus a
-* capability-validating asynchronous start surface. Providers establish a
+* capability-validating asynchronous start API. Providers establish a
 * child before returning its run, so fulfillment is the single publication and
 * ownership-transfer boundary.
 *
@@ -2389,4 +2569,4 @@ var SubagentService = class extends Service {
 	}
 };
 //#endregion
-export { NO_START_CAPABILITIES, SUBAGENT_DESCRIPTOR_VERSION, SubagentDepthError, SubagentError, SubagentRunId, SubagentService, SubagentService as default, appendDelegatedPolicyOverrides, applyChildComposition, assertPositiveFinite, assertSubagentMaxDepth, assertUsableCwd, captureDelegatedPolicyOverrides, childSessionMeta, delegationDepthOf, foldSubagentDescriptor, resolveChildAgentOptions, resolveChildCwd, resolveChildDepth, seedDescriptorTurn, settleRun, settleRunResult, snapshotSubagentDescriptor, subprocessRunHandle, validateConfiguredCwd };
+export { AssistantOutputFold, NO_START_CAPABILITIES, SUBAGENT_DESCRIPTOR_VERSION, SubagentDepthError, SubagentError, SubagentRunId, SubagentService, SubagentService as default, appendDelegatedPolicyOverrides, applyChildComposition, assertPositiveFinite, assertSubagentMaxDepth, assertUsableCwd, captureDelegatedPolicyOverrides, childSessionMeta, delegationDepthOf, finalAssistantOutput, foldSubagentDescriptor, resolveChildAgentOptions, resolveChildCwd, resolveChildDepth, seedDescriptorTurn, settleRun, settleRunResult, snapshotSubagentDescriptor, subprocessRunHandle, validateConfiguredCwd };