docs(tasks): condense background task prose

The background-task change repeated its lifecycle design across implemented RFCs, package READMEs, JSDoc, test commentary, and model-visible schemas. That repetition obscured the contracts that maintainers must preserve and added avoidable prompt tokens.

Rewrite the implemented RFCs around the current design, keep authorization, exact-owner cleanup, wait/abort ordering, producer quiescence, and teardown-failure guarantees at their owning surfaces, and remove peer surveys, review history, control-flow narration, and emphatic restatement.

Shorten the task and subagent schema wording, synchronize the bilingual tool cookbook, and regenerate the config, service, RFC, tool, and replay snapshot derivatives. Runtime behavior is unchanged; test edits update prose-only assertions and descriptions.

docs/config-catalog.md

@@ -154,7 +154,7 @@ export interface Config {
 }
 ```
 
-Source: [`packages/bash/bash-local/src/index.ts:27`](../packages/bash/bash-local/src/index.ts)
+Source: [`packages/bash/bash-local/src/index.ts:17`](../packages/bash/bash-local/src/index.ts)
 
 ## `@deepseek-ai/dsh-bash-sandbox`
 
@@ -165,7 +165,7 @@ Requires: `sandbox`
  * Plugin config: the local executor's knobs plus the sandbox policy. All
  * optional — `static Config` supplies the defaults (`mode: 'read-only'` is the
  * fail-safe default; an example that wants a workspace-writable agent opts in
- * explicitly). The runner choice is NOT configured here: which platform
+ * explicitly). The runner choice is not configured here: which platform
  * backend confines the command is the `ctx.sandbox` provider's config.
  */
 export interface Config extends LocalConfig {
@@ -886,19 +886,14 @@ Source: [`packages/context/time-context/src/index.ts:22`](../packages/context/ti
 Requires: `tools` · `bash` · `systemPrompt`
 
 ```ts config-catalog
-/** Config: whether the model may background commands (the producer-opt-in flag). */
+/** Configures whether the model may background commands. */
 export interface Config {
-  /**
-   * Expose `run_in_background` in the bash schema (default true). Disabled,
-   * the parameter is absent entirely — schema and capability never disagree.
-   * Backgrounding also needs the `ctx.tasks` runtime at call time; a missing
-   * one fails the call loud with the load-these-packages message.
-   */
+  /** Expose `run_in_background` (default true); disabled calls are also rejected. */
   enableRunInBackground?: boolean
 }
 ```
 
-Source: [`packages/bash/tool-bash/src/index.ts:48`](../packages/bash/tool-bash/src/index.ts)
+Source: [`packages/bash/tool-bash/src/index.ts:30`](../packages/bash/tool-bash/src/index.ts)
 
 ## `@deepseek-ai/dsh-tool-cordis`
 
@@ -962,42 +957,29 @@ export interface Config {
   /** The `ctx.subagents` provider name to start runs on (e.g. `spawn`, `acp`). */
   provider: string
   /**
-   * The model-facing tool name to register (default `subagent`). To expose more
-   * than one transport, load this plugin once per provider — each load MUST set
-   * a distinct `toolName` (the tool registry rejects a duplicate name), e.g.
-   * `{ provider: 'spawn', toolName: 'subagent' }` and
-   * `{ provider: 'acp', toolName: 'subagent_acp' }`.
+   * Model-facing tool name (default `subagent`). Each loaded instance must use
+   * a distinct name.
    */
   toolName?: string
   /**
-   * Expose `run_in_background` in this instance's schema (default true).
-   * Disabled, the parameter is absent entirely — schema and capability never
-   * disagree; delegation through this instance stays strictly synchronous.
-   * Backgrounding also needs the `ctx.tasks` runtime at call time; a missing
-   * one fails the call loud with the load-these-packages message.
+   * Expose `run_in_background` (default true). Disabled instances omit the
+   * parameter and reject forced background calls.
    */
   enableRunInBackground?: boolean
   /**
-   * Default per-child agent options (model) applied to every spawned child.
-   * Omitted fields fall back to the child loop's own defaults.
+   * Agent options applied to every child; omitted fields use child-loop defaults.
    */
   agentOptions?: AgentOptions
   /**
-   * Per-child persona applied to every child this tool spawns: a scoped
-   * `deployment:persona` section shadowing the deployment's persona for the
-   * child alone. Requires the bound provider's `persona` capability
-   * (in-process backends support it; a request against one that doesn't is
-   * rejected at start). Omitted ⇒ the child renders the deployment persona.
+   * Per-child persona that shadows `deployment:persona`. Requires the
+   * provider's `persona` capability; omission preserves the deployment persona.
    */
   persona?: string
   /**
-   * Tool scoping applied to every child this tool spawns (see
-   * `SubagentStartRequest.toolFilter`): the named global tools vanish from
-   * the child's prompt AND refuse to execute. Requires the provider's
-   * `toolFilter` capability. Unknown names fail the spawn loudly. Note the
-   * child otherwise sees every global tool — including this delegation tool
-   * itself; `deny`-listing it (or setting `maxDepth`) is how a deployment
-   * bounds recursion.
+   * Tool filter applied to every child. Filtered tools disappear from its
+   * prompt and reject execution. Requires the provider's `toolFilter`
+   * capability; unknown names fail startup. Children otherwise see this tool,
+   * so deny it or set `maxDepth` to bound recursion.
    */
   toolFilter?: {
     /** Global tool names the child keeps; everything else is removed. */
@@ -1006,12 +988,8 @@ export interface Config {
     deny?: string[]
   }
   /**
-   * Recursion cap applied to every child this tool spawns (see
-   * `SubagentStartRequest.maxDepth`): a spawn whose child would sit deeper
-   * than this in the delegation tree is rejected. Requires the provider's
-   * `depthLimit` capability. Must be a non-negative safe integer and is
-   * validated when the plugin loads. Omitted ⇒ unbounded (bound it in
-   * deployments that expose this tool to children).
+   * Maximum child depth. Requires the provider's `depthLimit` capability and a
+   * non-negative safe integer. Omission is unbounded.
    */
   maxDepth?: number
 }
@@ -1019,14 +997,14 @@ export interface Config {
 
 Depends on: [`AgentOptions`](../packages/core/agent/src/index.ts)
 
-Source: [`packages/subagent/tool-subagent/src/index.ts:59`](../packages/subagent/tool-subagent/src/index.ts)
+Source: [`packages/subagent/tool-subagent/src/index.ts:23`](../packages/subagent/tool-subagent/src/index.ts)
 
 ## `@deepseek-ai/dsh-tool-tasks`
 
 Requires: `tools` · `tasks` · `systemPrompt`
 
 ```ts config-catalog
-/** Config: the `task_output` wait bounds (defaulted, capped — never hardcoded). */
+/** Configures bounded `task_output` waits. */
 export interface Config {
   /** Wait duration applied when `task_output` sets `wait` without `timeout_ms` (default 30s). */
   waitTimeoutMs?: number
@@ -1035,7 +1013,7 @@ export interface Config {
 }
 ```
 
-Source: [`packages/tasks/tool-tasks/src/index.ts:34`](../packages/tasks/tool-tasks/src/index.ts)
+Source: [`packages/tasks/tool-tasks/src/index.ts:21`](../packages/tasks/tool-tasks/src/index.ts)
 
 ## `@deepseek-ai/dsh-tool-web`
 

docs/cookbook/adding-a-tool.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
-adding-a-tool.md: c98b6901e1a58db1872a0abf12930a9b4bcce9c1
-adding-a-tool.zh.md: 69cb9fe2b63296e21409d9c4ea375a51c95a2648
+adding-a-tool.md: da214702939e01fedf3d0d69be7560bbafe0696a
+adding-a-tool.zh.md: b216d18b1593cd7e6074685bd39684f1b9694eac

docs/cookbook/adding-a-tool.md

@@ -45,7 +45,9 @@ Registration is effect-based: disposing the plugin fiber unregisters the tool (w
 
 ## Long-running work
 
-Hand long-running work to the shared task runtime instead of inventing a task protocol: gate a `run_in_background` parameter behind your plugin's own defaulted `enableRunInBackground`-style config, then call `ctx.tasks.start({ kind, label, owner: exec.agent, run: () => ({ cancel, done, readOutput? }) })` (`@deepseek-ai/dsh-tasks`) — the runtime preflights everything that can fail (the control-surface fence, validation, owner-cleanup attach) BEFORE invoking your `run()` starter, so work that started without a collectable id is structurally impossible (no try/catch rollback in your tool). The runtime issues the `<kind>-N` id, fences access to the owning session, cancels-and-awaits your task when the owner disposes, and the generic `task_output`/`task_list`/`task_kill` tools plus the completion notice come from `@deepseek-ai/dsh-tool-tasks` — your tool returns `started background task <id>` and is done. Your producer keeps its execution concerns: `done` must settle at quiescence (resources released), and a stream-kind `readOutput` owns its own truncation/spill formatting (bound buffers, spill full output to disk so nothing is silently lost — see tool-bash's `renderProcessRead`). Do NOT wire `exec.signal` to the background work after the id is returned; check `exec.signal?.aborted` once before calling `start`, then leave cancellation to `task_kill` and owner cleanup.
+Gate `run_in_background` with producer config, reject a pre-aborted call, then register through `ctx.tasks.start({ kind, label, owner: exec.agent, run })`. The runtime validates ownership and control-surface availability before `run()` starts work, then supplies the id, session fence, generic control tools, notices, and owner cleanup.
+
+The producer supplies synchronous `cancel`, non-rejecting `done` that settles after resource cleanup, and optional consuming `readOutput` with bounded-output formatting. Once the id is returned, use a task-owned cancellation signal rather than `exec.signal`. See the [background task runtime RFC](../rfc/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md) and `dsh-tool-bash` for a stream producer.
 
 ## Execution policy and observation
 

docs/cookbook/adding-a-tool.zh.md

@@ -45,7 +45,9 @@ export function apply(ctx: Context) {
 
 ## 长时间运行的工作
 
-不要为长时间运行的工作另造任务协议，而应将其交给共享 task 运行时：通过插件自身带默认值的 `enableRunInBackground` 类配置控制是否暴露 `run_in_background` 参数，然后调用 `ctx.tasks.start({ kind, label, owner: exec.agent, run: () => ({ cancel, done, readOutput? }) })`（`@deepseek-ai/dsh-tasks`）。运行时会在调用你的 `run()` 启动器之前，预检所有可能失败的条件（控制面围栏、校验和 owner cleanup 挂接），从结构上杜绝工作已经启动却没有可收集 id 的情况（你的工具无需通过 try/catch 回滚）。运行时签发 `<kind>-N` id，将访问限制在 owner 会话，并在 owner dispose 时取消并等待任务；通用的 `task_output`、`task_list`、`task_kill` 工具和完成通知由 `@deepseek-ai/dsh-tool-tasks` 提供，你的工具返回 `started background task <id>` 后即完成。producer 保留自身的执行职责：`done` 必须在达到静止状态（资源已释放）后 settle；流类型的 `readOutput` 自行负责截断和溢写格式（限定缓冲区大小，将完整输出溢写到磁盘，避免静默丢失——参见 tool-bash 的 `renderProcessRead`）。返回 id 后，不要再把 `exec.signal` 连接到后台工作；调用 `start` 前只检查一次 `exec.signal?.aborted`，此后由 `task_kill` 和 owner cleanup 负责取消。
+通过 producer 配置控制 `run_in_background`，拒绝已预先中止的调用，然后使用 `ctx.tasks.start({ kind, label, owner: exec.agent, run })` 注册任务。运行时会在 `run()` 启动工作前校验 owner 和控制面是否可用，随后提供 id、会话围栏、通用控制工具、通知和 owner cleanup。
+
+producer 提供同步的 `cancel`、在资源清理后 settle 且不 reject 的 `done`，以及可选的消费式 `readOutput`（负责有界输出的格式化）。返回 id 后，应使用 task 自有的取消信号，而不是 `exec.signal`。流式 producer 的示例和完整契约见[后台 task 运行时 RFC](../rfc/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md)与 `dsh-tool-bash`。
 
 ## 执行策略与观测
 

docs/cordis-catalog/services.md

@@ -56,12 +56,12 @@ Source: [`packages/ui/user-approval/src/index.ts:229`](../../packages/ui/user-ap
 
 Abstract bash execution service. Subclass, implement the abstract methods, and load the subclass as a plugin — it registers as `ctx.bash` (one implementation per context; loading a second throws, which is cordis' standard duplicate-service behavior).
 
-Semantics every implementation must honor:
+Implementations must honor these semantics:
 
-- run REJECTS only for infrastructure failures (unusable workdir, missing shell, pre-aborted signal). Nonzero exits, timeout kills, and abort kills RESOLVE with a descriptive BashRunResult — reporting a failed command is the tool layer's job, not an exception.
-- start returns immediately; no timeout applies to background processes (callers stop them via BashProcess.kill or the spec's AbortSignal). The handle's `done` settles at process close and never rejects (a spawn failure settles as `killed` with the error readable on stderr).
-- BashProcess.readOutput is incremental: consecutive reads never re-deliver output. Implementations bound their buffers; reads that lost data flag `lossy` and point at full-stream spill files when available.
-- Disposal kills every running background process and awaits their exit (no orphan processes survive `fiber.dispose()`).
+- run rejects only for infrastructure failures. Nonzero exits, timeout kills, and abort kills resolve with a BashRunResult.
+- start returns immediately; no timeout applies to background processes. `done` settles at process close and never rejects; spawn failures settle as `killed` with the error on stderr.
+- BashProcess.readOutput is incremental: consecutive reads never repeat output. Lossy reads report truncation and available spill files.
+- Disposal kills all running background processes and awaits their exit.
 
 ```ts cordis-catalog
 abstract resolve(request: BashExecRequest): BashExecSpec
@@ -71,7 +71,7 @@ abstract start(spec: BashExecSpec): BashProcess
 
 Types: [BashExecRequest](../core-data-structures/bash.md) · [BashExecSpec](../core-data-structures/bash.md) · [BashRunResult](../core-data-structures/bash.md)
 
-Source: [`packages/bash/bash/src/index.ts:68`](../../packages/bash/bash/src/index.ts)
+Source: [`packages/bash/bash/src/index.ts:46`](../../packages/bash/bash/src/index.ts)
 
 ## `ctx.codeRuntime` — `CodeRuntime` (abstract seam)
 
@@ -259,7 +259,7 @@ attachSurface(name: string): () => void
 
 Types: [Agent](../core-data-structures/core.md)
 
-Source: [`packages/tasks/tasks/src/index.ts:98`](../../packages/tasks/tasks/src/index.ts)
+Source: [`packages/tasks/tasks/src/index.ts:72`](../../packages/tasks/tasks/src/index.ts)
 
 ## `ctx.tools` — `ToolRegistry`
 

docs/core-data-structures/tasks.md

@@ -1,16 +1,14 @@
 # Background Task Runtime
 
-The shared background-task vocabulary — what a producer (`dsh-tool-bash`, `dsh-tool-subagent`, any future long-running tool) hands to `ctx.tasks.start()` and what consumers (the `task_output`/`task_list`/`task_kill` tools, completion-notice injection) get back. The runtime is ONE concrete service ([dsh-tasks](../../packages/tasks/tasks), `ctx.tasks`), not an interface/implementation seam pair — see [the runtime RFC](../rfc/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md) for the decision and [the tasks group README](../../packages/tasks/README.md) for the package split.
-
-Source: [`packages/tasks/tasks/src/types.ts`](../../packages/tasks/tasks/src/types.ts)
+Types shared by long-running producers, `ctx.tasks`, and task control surfaces. The [runtime RFC](../rfc/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md) owns the design; this page records the literal shapes from [`packages/tasks/tasks/src/types.ts`](../../packages/tasks/tasks/src/types.ts).
 
 ## Ids and status
 
-`TaskId` is [branded](core.md#branded-ids) (`Branded<'TaskId'>` + a same-named factory), generated by the registry as `<kind>-N` with a per-kind counter (`bash-1`, `subagent-1`) — kind-prefixed so transcripts stay self-describing, sequential because the owner fence (not id secrecy) is the isolation boundary. `TaskStatus` is generic and CLOSED: `'running' | 'stopping' | 'completed' | 'killed' | 'failed'` — kind-specific meaning (exit codes, stop reasons) rides in `TaskSnapshot.detail`, so the registry never learns process or agent semantics.
+`TaskId` is a [branded id](core.md#branded-ids) generated as `<kind>-N`. Access control relies on owner authorization, not id secrecy. `TaskStatus` is `'running' | 'stopping' | 'completed' | 'killed' | 'failed'`; producer-specific facts belong in `TaskSnapshot.detail`.
 
-## The producer contract: `TaskStart` and `TaskHooks`
+## Producer contract
 
-Declare-then-execute: the producer hands its task's identity plus a `run()` starter to `ctx.tasks.start()`, which preflights everything that can fail (the control-surface fence, validation, the owner-cleanup attach) BEFORE invoking `run()`, and commits atomically after — work that started without a collectable id is structurally impossible. The producer stays the owner of its execution concerns (process streams, child agents); the runtime owns ids, isolation, status, and completion fan-out. The optional `readOutput` hook marks a STREAM kind — the method presence is the capability, mirroring `SubagentRun.sendMessage`.
+`TaskStart` declares identity and a starter. The runtime finishes preflight before calling `run()` and commits without a later failable step. Producers own execution resources; the runtime owns identity, access, and lifecycle state.
 
 ```ts type-equiv
 interface TaskStart {
@@ -19,53 +17,41 @@ interface TaskStart {
   /** One-line model-facing label (the command; the delegation description). */
   label: string
   /**
-   * The spawning agent. Its `session.header.id` becomes the task's owner
-   * identity (read/kill/wait/list are fenced to that session), and its `ctx` scope
-   * owns an async cleanup that cancels and awaits the task during disposal. It
-   * must be the exact live instance currently registered under its agent id;
-   * a stale object whose id has been reused is rejected before work starts.
-   * `undefined` starts an UNOWNED task: open to any caller, alive until the
-   * tasks service disposes.
+   * Owning live agent. Access is fenced by its session id, and agent disposal
+   * cancels and awaits the task. The instance must be the one currently
+   * registered under its agent id. `undefined` creates an unowned task, open to
+   * any caller until service disposal.
    */
   owner?: Agent | undefined
   /**
-   * Start the actual work and return its {@link TaskHooks}. Called EXACTLY
-   * once, synchronously, after every preflight check (control-surface fence,
-   * validation, owner-cleanup attach) has passed — nothing in the runtime can
-   * fail after it returns, so the started work is always registered. A throw
-   * here propagates with nothing registered; the producer owns any partial
-   * cleanup of its own failed start.
+   * Start the work after preflight and synchronously return its hooks. Called
+   * once; a throw leaves nothing registered, and the producer must clean up any
+   * partially started resources.
    */
   run(): TaskHooks
 }
 ```
 
+`TaskHooks.done` is the quiescence boundary. Optional `readOutput` distinguishes consuming stream tasks from final-output-only tasks.
+
 ```ts type-equiv
 interface TaskHooks {
   /**
-   * Request termination. Idempotent, synchronous, and must lead to
-   * {@link done} settling; a throw propagates to the killer (fail loud — a
-   * cancel that cannot even be requested is a producer bug). The optional
-   * reason is `task_kill`'s logged reason, forwarded verbatim.
+   * Request termination. Must be synchronous, idempotent, and eventually settle
+   * {@link done}; throws propagate. The optional reason is forwarded verbatim.
    */
   cancel(reason?: string): void
   /**
-   * Settles with the terminal outcome at QUIESCENCE — after the producer has
-   * released the task's resources (process exited, child agent disposed) —
-   * not merely when the work finished. Must never reject; a rejection is
-   * contained as a `failed` outcome and logged as a producer contract
-   * violation. If `cancel` throws during teardown, the runtime may force-fail
-   * only its registry record to avoid deadlock because this promise may never
-   * settle; that fallback explicitly does not claim work quiescence.
+   * Resolves after the producer releases its resources, not merely when work
+   * finishes. Must not reject; the runtime converts a rejection to `failed`.
+   * If teardown cancellation throws, the runtime may force-fail only the
+   * registry record without claiming that the work stopped.
    */
   done: Promise<TaskOutcome>
   /**
-   * OPTIONAL incremental read (stream kinds): everything produced since the
-   * previous call, formatted by the producer (truncation/spill notices
-   * included). Consecutive calls never re-deliver output; the registry keeps
-   * ONE consuming cursor per task, so v1's single intended reader is the
-   * owning model. Absence marks a final-output-only kind (the method presence
-   * IS the capability).
+   * Consume output produced since the previous call. The producer formats
+   * truncation and spill notices. Absence marks a final-output-only task; each
+   * task has one consuming cursor.
    */
   readOutput?(): string
 }
@@ -77,18 +63,14 @@ interface TaskOutcome {
   status: 'completed' | 'killed' | 'failed'
   /** Kind-specific detail rendered into status lines ('exit code: 3', 'max-tokens'). */
   detail?: string
-  /**
-   * Final output for FINAL-OUTPUT-ONLY kinds (no {@link TaskHooks.readOutput}),
-   * read idempotently after the task settles. Stream kinds leave it unset —
-   * their output is consumed incrementally through `readOutput`.
-   */
+  /** Final output for tasks without `readOutput`; stream tasks leave it unset. */
   output?: string
 }
 ```
 
-## What consumers see: `TaskSnapshot` and `TaskRead`
+## Consumer views
 
-Snapshots are fresh projections, never live registry state. `ownerSession` retains the shared branded `SessionId` type across the package boundary. `reported` is the notice-suppression flag: the completion-notice injector (`dsh-tool-tasks`) skips a task whose terminal state the model already saw.
+Snapshots are fresh read-only projections. `ownerSession` carries the shared `SessionId` used for authorization; completion listeners separately receive the exact owner object used for lifecycle cleanup. `reported` suppresses a completion notice after another surface has delivered or committed to deliver the terminal state.
 
 ```ts type-equiv
 interface TaskSnapshot {
@@ -99,12 +81,9 @@ interface TaskSnapshot {
   /** The producer-supplied one-line label. */
   label: string
   /**
-   * The owner's session id (`session.header.id`), for authorization and
-   * correlation; absent for unowned tasks. A listener that must reach the
-   * lifecycle owner receives the exact Agent separately through
-   * {@link TaskDoneListener}. Session ids are runtime-shared identifiers, not
-   * secrets — the read/kill/wait/list FENCE is what isolation rests on. The
-   * shared {@link SessionId} brand is preserved across this package boundary.
+   * Owner session id used for authorization and correlation; absent for
+   * unowned tasks. Completion listeners receive the exact {@link Agent}
+   * separately through {@link TaskDoneListener}.
    */
   ownerSession?: SessionId
   /** Current lifecycle state. */
@@ -116,11 +95,8 @@ interface TaskSnapshot {
   /** Epoch ms when the task settled; absent while `running`/`stopping`. */
   finishedAt?: number
   /**
-   * True once the terminal state has been (or is being) reported to the owner
-   * through an explicit surface response — a `kill` call, or a `read`/`wait`
-   * that returned the terminal state (including a wait pending at settlement).
-   * Completion-notice surfaces suppress their notice when set, so the model
-   * never gets a redundant "finished" for a task it just collected or killed.
+   * True when a kill, read, or wait has reported or committed to report the
+   * terminal state. Completion surfaces suppress redundant notices when set.
    */
   reported: boolean
 }
@@ -139,6 +115,6 @@ interface TaskRead {
 }
 ```
 
-## The service
+## Service behavior
 
-`TaskService` (`ctx.tasks` — [`packages/tasks/tasks/src/index.ts`](../../packages/tasks/tasks/src/index.ts)): `start` (preflight → producer `run()` → atomic commit, fenced by `attachSurface`), non-consuming `get`/`list` (caller-scoped — owned-by-caller plus unowned only), `read` (consuming for stream kinds), `kill` (producer `cancel` first; a throw leaves the task untouched), `wait` (bounded, abort cancels the wait only), and `onTaskDone` (a `TaskDoneListener` per terminal record, given the exact lifecycle owner and effect-scoped). Listener calls contain synchronous throws and returned promise rejections independently; returned promises are not awaited and therefore do not delay task settlement. Start retains the exact live Agent instance validated under its id; owner-scope cleanup selects by that identity, so a reused agent/session id cannot make an old scope cancel replacement work. Read/kill/wait/get authorization remains session-based and rejects a foreign session. A teardown cancel that throws force-fails only the registry record and reports that the underlying work may be orphaned, preventing disposal deadlock without claiming quiescence. The model-facing surface over all of this is [dsh-tool-tasks](../../packages/tasks/tool-tasks/README.md).
+[`TaskService`](../../packages/tasks/tasks/src/index.ts) provides atomic `start`, caller-scoped `get` and `list`, `read`, `kill`, bounded `wait`, contained `onTaskDone` listeners, and the `attachSurface` availability fence. Authorization compares owner sessions; owner cleanup selects the exact registered `Agent` instance. See [`dsh-tasks`](../../packages/tasks/tasks/README.md) for the package contract and [`dsh-tool-tasks`](../../packages/tasks/tool-tasks/README.md) for the model-facing surface.

docs/rfc/INDEX.md

@@ -127,7 +127,7 @@ Generated by `pnpm run gen-rfc-index` from the RFC tree — never edit by hand;
 | [Shared persistence write coordinator](implemented/architecture/2026-06-18-shared-persistence-write-coordinator.md) | 2026-06-18 |
 | [Branded IDs everywhere they belong](implemented/architecture/2026-06-20-branded-ids.md) | 2026-06-20 |
 | [Extract example apps into packages](implemented/architecture/2026-06-20-extract-example-app-packages.md) | 2026-06-20 |
-| [The background task runtime (`ctx.tasks`) and the generic task control tools](implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md) | 2026-06-20 |
+| [The background task runtime (`ctx.tasks`) and generic task control tools](implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md) | 2026-06-20 |
 | [Reorganize packages into a modular hierarchy](implemented/architecture/2026-06-20-package-hierarchy.md) | 2026-06-20 |
 | [Mandatory `User-Agent` attribution for provider requests](implemented/architecture/2026-06-21-mandatory-app-attribution-headers.md) | 2026-06-21 |
 | [Web capability seam - stable tools over multiple providers](implemented/architecture/2026-06-24-web-capability-seam.md) | 2026-06-24 |

docs/rfc/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md

@@ -1,185 +1,128 @@
-# RFC: The background task runtime (`ctx.tasks`) and the generic task control tools
+# RFC: The background task runtime (`ctx.tasks`) and generic task control tools
 
 Status: implemented
 
 ## Problem
 
-The bash capability seam supports both foreground commands and long-running background tasks. Background support was large: the abstract executor exposed `start`, `get`, `ownerOf`, `list`, `readOutput`, `kill`, and `onTaskDone`; the local executor tracked tasks, incremental reads, owner tokens, process cleanup, and completion listeners; the model saw three tools (`bash`, `bash_output`, `bash_kill`); the tool plugin injected completion notices back into the owning agent's session. The local executor fenced task access behind owner tokens because predictable global task ids are a cross-session read/kill hazard.
+Background bash originally combined two responsibilities: the bash executor ran processes and also managed task ids, ownership, incremental reads, cancellation, completion listeners, and model-facing control tools. Adding background subagents required the same lifecycle and interaction contract. Implementing that contract independently for every long-running capability would duplicate isolation, cleanup, notification, and prompt behavior while teaching the model a different collect-and-stop protocol for each producer.
 
-The [tool cookbook](../../../cookbook/adding-a-tool.md) already pointed at the real design smell: background bash is really generic long-running-tool infrastructure living inside one tool. The pressure stopped being hypothetical with [background subagent tasks](../feature/2026-07-08-background-subagent-tasks.md), which needs the same task ids, owner isolation, polling, stop, completion notices, and prompt guidance, and whose first draft answered by cloning the protocol under new names (`subagent_wait`, `subagent_output`, `subagent_stop`) and reshaping `dsh-tool-subagent` into a multi-tool plugin solely so the cloned companion tools would not collide across instances. Every future long-running capability (dev servers, watchers, remote jobs) would clone it again, and the model would learn a new collect/stop habit per capability.
-
-The surveyed peer products converged on the opposite shape. Claude Code exposes one `TaskOutput`/`TaskStop` pair spanning seven task kinds (background shells, subagents, remote sessions, …), with its earlier per-capability `BashOutput`/`KillShell` names kept only as aliases; Kimi Code's `BackgroundManager` runs process, agent, and pending-question kinds behind the same two tools and a ~5-method producer interface; DeepSeek-Reasonix serves bash and delegation from one session-scoped jobs manager; OpenCode's `BackgroundJob` registry is kind-agnostic by construction. The lesson is that the task registry, the control tools, and the notification path are one capability, and the producers (bash, subagents) are plugins into it.
+The task registry, control tools, and completion notices form one harness capability. Bash and subagents should supply execution-specific hooks without owning generic task behavior.
 
 ## Decision
 
-The `tasks/` package group owns background-task semantics once, and bash and subagents are producers:
-
-- `@deepseek-ai/dsh-tasks` — the task registry service (`ctx.tasks`): branded task ids, owner-scoped authorization, status snapshots, incremental/final output reads, cancellation, wait-for-terminal, completion listeners, and the awaited owner-cleanup path.
-- `@deepseek-ai/dsh-tool-tasks` — the model-facing control surface: `task_output`, `task_list`, `task_kill`, the completion-notice injection into the owning session, and the system-prompt section that teaches the background-task habit.
+The `tasks/` package group owns background-task semantics:
 
-Producers register running work into `ctx.tasks` and stay owners of their execution concerns: `dsh-tool-bash`'s `run_in_background` path registers the process it started (incremental stdout, spill formatting, kill), and `dsh-tool-subagent`'s background mode ([the feature RFC](../feature/2026-07-08-background-subagent-tasks.md)) registers the child run (final output only, cancel + dispose). The bash seam carries no registry: `bash_output`/`bash_kill` no longer exist (the generic tools replaced them), and the subagent companion tools were never created. The `dsh-agent-core` bundle loads the pair, so every shipped deployment has the control surface.
+- `@deepseek-ai/dsh-tasks` registers running work as `ctx.tasks` and owns task ids, authorization, snapshots, reads, cancellation, waiting, completion listeners, and cleanup.
+- `@deepseek-ai/dsh-tool-tasks` exposes `task_output`, `task_list`, and `task_kill`, injects completion notices, and supplies the background-task system-prompt guidance.
 
-The registry is a CONCRETE service, not an interface/implementation seam pair: there is exactly one sensible in-process implementation today, and the capability-seam convention says not to split preemptively. The pre-release stance lets a later durable/remote job system extract an interface when a second backend actually exists.
+Long-running tools are producers. `dsh-tool-bash` adapts a `BashProcess` into incremental output and process cancellation; `dsh-tool-subagent` adapts a child run into final output and child disposal. The execution seams remain independent of sessions and the task registry.
 
-## Task model
+`TaskService` is a concrete service. There is one in-process implementation, so an interface/backend package split would be speculative. A durable or remote implementation can introduce that seam when its lifecycle requirements are known.
 
-`dsh-tasks` owns the vocabulary ([data-structure catalog](../../../core-data-structures/tasks.md)). `TaskId` is branded, generated by the registry as `<kind>-N` with a per-kind counter (`bash-1`, `subagent-1`) — the kind prefix keeps ids self-describing in transcripts and preserves the pre-runtime `bash-N` shape. Ids are runtime-global and predictable, so every access is authorized (below).
+## Runtime contract
 
-A producer hands its work to `ctx.tasks.start()` in a declare-then-execute shape (the pattern the timeout-policy plugin set: the capability declares, the shared layer executes): identity first, then a `run()` starter the runtime invokes only once nothing can fail anymore.
+The literal types live in the [task data-structure catalog](../../../core-data-structures/tasks.md). A producer calls `ctx.tasks.start()` with a kind, label, optional owning `Agent`, and a `run()` function. The runtime completes all failable preflight work before calling `run()` and invokes it once. After `run()` returns hooks, registration commits without another failable step; a producer cannot start work that lacks a collectable task id.
 
-```ts ignore-check
-interface TaskStart {
-  /** Producer kind — also the id prefix ('bash', 'subagent', …). */
-  kind: string
-  /** One-line model-facing label (the command; the delegation description). */
-  label: string
-  /** The spawning agent; undefined = unowned (open access, dies with the service). */
-  owner?: Agent
-  /** Start the actual work; called exactly once, after preflight passed. */
-  run(): TaskHooks
-}
+The producer hooks define three responsibilities:
 
-interface TaskHooks {
-  /** Request termination; idempotent; must lead to `done` settling. The optional reason is `task_kill`'s logged reason, forwarded. */
-  cancel(reason?: string): void
-  /** Settles at QUIESCENCE — after the producer has released the task's resources. Never rejects. */
-  done: Promise<TaskOutcome>
-  /** OPTIONAL incremental read (stream kinds). Consecutive calls never re-deliver output; the producer owns truncation/spill formatting. Absence = final-output-only kind. */
-  readOutput?(): string
-}
+- `cancel(reason?)` synchronously requests termination, is idempotent, and must cause `done` to settle.
+- `done` never rejects and settles only after the producer has released the task's resources.
+- Optional `readOutput()` returns the next consuming output delta. Omitting it declares a final-output task whose terminal result comes from `TaskOutcome.output`.
 
-interface TaskOutcome {
-  status: 'completed' | 'killed' | 'failed'
-  /** Kind-specific detail rendered into the status line ('exit code: 3', 'max-tokens'). */
-  detail?: string
-  /** Final output for final-only kinds; read idempotently after the task settles. */
-  output?: string
-}
-```
+Statuses are `running`, `stopping`, `completed`, `killed`, and `failed`. Producer-specific information such as an exit code or stop reason belongs in `detail`; the registry does not interpret it. Task ids are branded and generated as `<kind>-N`, with a counter per kind.
 
-The task status vocabulary is generic and closed: `running`, `stopping` (cancel requested, not yet settled), and the three terminal values above. Kind-specific meaning rides in `detail`, so the registry never learns process or agent semantics — the method presence (`readOutput`) is the capability, mirroring `SubagentRun.sendMessage`.
+The runtime attaches one continuation to `done`, records the first terminal outcome, resolves waiters, and invokes completion listeners with per-listener error containment. First-wins settlement matters during teardown: if `cancel` throws, the runtime force-fails the record and warns that work may be orphaned rather than waiting forever for a promise that may never settle. A later producer outcome cannot overwrite that diagnosis or notify twice. A `cancel` that returns without eventually settling `done` still blocks teardown because the runtime cannot distinguish it from a slow, valid stop.
 
-The registry attaches ONE continuation to `done`: record the terminal snapshot, then notify task-done listeners with per-listener containment (the guarantee the bash seam's `notifyTaskDone` used to give its own listener set). `done` settling at quiescence — not merely at completion — makes ordinary owner cleanup and service disposal awaitable without a second completion surface. Settlement is first-wins because teardown has one explicit failure fallback: if producer `cancel` throws before the request is delivered, `done` may never settle, so the registry force-fails the record with a possible-orphan detail instead of deadlocking disposal; a late producer outcome cannot overwrite that diagnosis or notify twice. This fallback terminates bookkeeping, not necessarily the underlying work.
+Task registrations are not effects of the producer tool fiber. Reloading a tool or control-surface plugin therefore does not kill work owned by an agent and backend. The task service's own disposal cancels all live tasks and awaits contract-compliant producers.
 
-Registrations are NOT effect-scoped to the registering fiber: a task belongs to its owning agent and its producing backend, not to the tool plugin whose call started it, so an HMR reload of `dsh-tool-bash` or `dsh-tool-tasks` never orphans or kills a running task (the same argument that used to keep bash ownership in the executor). The registry's own disposal cancels every live task and awaits contract-compliant producers to quiescence. A teardown cancel that throws force-fails the terminal record and logs that work may be orphaned; this prevents a broken producer from deadlocking the fiber without pretending the work stopped.
+## Authorization and owner lifecycle
 
-## Authorization and the service surface
+Task ids are runtime-global and predictable, so every access is authorized by the registry. `get`, `read`, `wait`, and `kill` accept the calling `Agent`; `list` returns only tasks visible to that caller. An owned task is accessible only to the exact owning session. Unowned tasks are open to non-agent callers and die with the task service.
 
-Cross-session isolation lives IN the runtime so every consumer gets the same rule for free: read/kill/wait/get take the caller (`Agent | undefined`), and a task whose owner session differs from the caller's session is rejected (`!== undefined` comparison — an unowned task is open, a no-agent caller cannot match an owned one). `list(caller)` returns only the caller-visible tasks (owned-by-caller or unowned) — a global listing would leak other sessions' labels. The snapshot carries that authorization identity as the canonical branded `SessionId`, not a package-local token or bare string. Lifecycle ownership is independent: start retains the exact live `Agent` instance, owner cleanup selects by object identity, and completion listeners receive that exact owner, so id reuse cannot redirect cleanup or notices to a replacement.
+The snapshot stores the owner's branded `SessionId` for authorization, while lifecycle operations retain the exact live `Agent` instance. These identities serve different purposes: session equality grants access, but exact object identity selects cleanup and completion delivery. Reusing an agent or session id cannot redirect an old scope's cleanup or notices to a replacement.
 
-```ts ignore-check
-class TaskService extends Service {           // ctx.tasks
-  start(spec: TaskStart): TaskId              // preflight (throws) → spec.run() starts the work → atomic commit (cannot fail)
-  get(id: TaskId, caller?: Agent): TaskSnapshot            // non-consuming; throws: unknown id, foreign owner
-  list(caller?: Agent): TaskSnapshot[]                     // caller-visible only
-  read(id: TaskId, caller?: Agent): TaskRead               // delta (stream kinds, consuming) or final output (final kinds, idempotent) + snapshot
-  kill(id: TaskId, caller?: Agent, reason?: string): 'requested' | 'already-terminal'
-  wait(id: TaskId, timeoutMs: number, caller?: Agent, signal?: AbortSignal): Promise<TaskSnapshot>
-  onTaskDone(listener: (snapshot: TaskSnapshot, owner: Agent | undefined) => void | PromiseLike<void>): () => void   // exact owner; effect-scoped, contained
-  attachSurface(name: string): () => void     // the misconfiguration fence, below
-}
-```
+The first task for an owner attaches one asynchronous effect to `owner.ctx`. Agent-scope disposal cancels that owner's live tasks, awaits their terminal records, and removes their snapshots. This effect survives producer reloads and joins the agent's existing quiescence boundary. The task service retains the effect disposer so service reload can detach callbacks from still-live agent scopes after global teardown.
 
-`TaskSnapshot` is the read-only projection: id, kind, label, branded owner `SessionId`, status, detail, started/finished timestamps, and the `reported` notice-suppression flag (below). `wait` resolves with the terminal snapshot, or with the still-`running` snapshot on timeout; aborting the wait cancels only the wait — unless the task already settled, in which case the wait still delivers the terminal snapshot (settlement suppressed the completion notice on this live waiter's behalf, and an aborted waiter un-counts itself synchronously so a same-tick settlement never suppresses a notice nobody will deliver).
+For contract-compliant producers, `AgentHandle.dispose()` resolves only after owned background work has stopped. Work intended to outlive an agent must be started unowned; survival across runtime restarts requires a separate durable-job design.
 
-**Misconfiguration fails loud**: a deployment that loads a background-capable producer without any control surface would let the model start tasks it can never read or stop — the half-loaded failure mode the subagent RFC's first draft reshaped a whole plugin to avoid. The fence is `attachSurface()`: `dsh-tool-tasks` attaches (effect-scoped) on load, and `start()` throws `background tasks unavailable: no control surface is attached (load @deepseek-ai/dsh-tool-tasks)` when none is attached — the earliest self-contained moment, since concurrent plugin start makes a load-time check racy. The registry stays ignorant of tool names; a deployment with a custom (non-model) surface attaches its own.
+## Service surface
 
-## The model-facing control tools
+`TaskService` provides:
 
-`dsh-tool-tasks` registers three kind-agnostic tools (ACP render intent: `generic` cards, `kind: 'execute'` for kill and `'read'` for output/list, no `locations`):
+- `start(spec)` for preflighted, atomic registration.
+- `get(id, caller?)` and `list(caller?)` for non-consuming snapshots.
+- `read(id, caller?)` for a consuming stream delta or an idempotent final result.
+- `kill(id, caller?, reason?)` for cancellation.
+- `wait(id, timeoutMs, caller?, signal?)` for bounded terminal waiting.
+- `onTaskDone(listener)` for effect-scoped observation with exact-owner delivery and listener containment.
+- `attachSurface(name)` for the control-surface availability fence.
 
-- `task_output(task_id, wait?, timeout_ms?)` — non-blocking by default: stream kinds return output produced since the previous read, final kinds return only a status line while running and the final output once terminal; every response ends with the status line (`[status: running]`, `[status: completed, exit code: 0]`, `[status: failed, max-tokens]` — generic status + producer detail). `wait: true` blocks until the task settles or the timeout expires (config: defaulted `waitTimeoutMs`, capped `maxWaitTimeoutMs`); a timed-out wait returns `[status: running]` and leaves the task alive. Polling-by-default preserves the established bash habit; `wait` is what a parent uses when it is genuinely blocked on a subagent's answer.
-- `task_list()` — the caller's tasks, one line each: `<id> [<kind>] <status> — <label>`; `(no background tasks)` when empty. Most peers make listing a human-only surface (`/tasks` panels) and only Gemini CLI ships a model-facing list; DSH keeps it model-facing because the harness is an SDK with no guaranteed user UI — a deployment may have no `/tasks` equivalent — and a caller-scoped list is one cheap registry read.
-- `task_kill(task_id, reason?)` — requests cancellation and returns immediately (`requested cancellation of task <id>`); the optional `reason` lands in the logged tool args and is forwarded to the producer's `cancel` hook (the subagent producer aborts its task-owned signal with that reason). Killing an already-terminal task reports its terminal status rather than failing; a producer `cancel` that throws fails the call loud and leaves the task untouched (still `running`, notice not suppressed).
+`wait` returns the terminal snapshot when the task settles or the live snapshot when its timeout expires. Aborting a wait cancels only that wait. If settlement has already assigned terminal delivery to the waiter, the terminal snapshot still wins. Waiters unregister synchronously on abort so a same-tick settlement cannot suppress a completion notice on behalf of a reader that receives nothing.
 
-`task_output`'s read cursor is task-scoped and CONSUMING for stream kinds: the registry keeps one cursor per task, and a read returns everything produced since the previous read, exactly like the old `bash_output`. v1's intended reader is the owning model — the owner fence already makes it the only model-facing one — so a non-consuming observation surface (a UI tailing a task, multiple concurrent readers) is deliberately out of scope; when one is needed, it extends the registry with a cursor/snapshot read API rather than changing `task_output`, because two consumers sharing the consuming cursor would silently eat each other's output.
+A producer loaded without any control surface would let callers start work they cannot collect or stop. `dsh-tool-tasks` therefore calls `attachSurface()` for its lifetime, and `start()` fails before producer execution when no surface is attached. This check occurs at start rather than plugin load because sibling plugins may activate concurrently. Custom non-model surfaces can attach themselves without teaching the registry tool names.
 
-One system-prompt section (order 106, next to `tool:bash`) teaches the cross-call habit the per-tool descriptions cannot: track every returned task id; you are notified in-session when a task finishes, so do not busy-poll or sleep on one — keep working on independent steps and do not duplicate a running task's work; do not produce a final answer while a relevant task still runs — call `task_output` (with `wait` when blocked) to collect it first; `task_kill` tasks that stopped mattering. The do-not-poll and do-not-duplicate sentences are near-verbatim convergent across Claude Code, Kimi Code, and OpenCode — they are the two failure modes every peer engineered against.
+## Model-facing control surface
 
-Completion notices stay durable context, not a wake-up (`agent.inject()` appends a logged `context/message` the next model request sees; it does not run the model): on `onTaskDone`, `dsh-tool-tasks` injects `background task <id> (<kind>: <label>) finished [status: …]. Read its output with task_output.` through the exact owner captured at start, never a replacement found through a reused agent/session id, with the disposed-race contained. Notices are deduplicated the way Claude Code and Kimi Code both learned to: a task the model explicitly killed, or whose terminal state a read/wait already returned (including a wait pending at the moment of settlement), is marked `reported` and its notice suppressed — never a redundant "finished" for work the model just collected or ended. The model-visible ⟺ logged invariant holds with no new session event type.
+`dsh-tool-tasks` registers three kind-independent tools with generic ACP cards:
 
-Completion listeners are observation-only: each synchronous throw and returned promise rejection is logged independently, later listeners still run, and listener promises are not awaited before waiters or task teardown continue.
+- `task_output(task_id, wait?, timeout_ms?)` reads output and always appends `[status: ...]`. Stream tasks return only output since the previous read; final-output tasks return their result after settlement. Reads are non-blocking unless `wait: true`, whose timeout is defaulted and capped by plugin config. A wait timeout reports the still-running status and does not stop the task.
+- `task_list()` returns caller-visible tasks as `<id> [<kind>] <status> — <label>`, or `(no background tasks)`.
+- `task_kill(task_id, reason?)` requests cancellation immediately. The optional logged reason is forwarded to the producer. Terminal tasks report their existing status; a throwing producer cancel fails the call and leaves the task running.
 
-## Producer opt-in and schema exposure
+Stream reads share one task-scoped consuming cursor because the owning model is the intended reader. A UI or multiple independent readers need a separate non-consuming observation API; sharing this cursor would let readers consume one another's output.
 
-Whether a producer tool offers `run_in_background` is that producer's own defaulted config: `enableRunInBackground?: boolean` on `dsh-tool-bash` and on each `dsh-tool-subagent` instance (both default `true` — bash keeps its always-exposed behavior, and a deployment disables either per instance from cordis.yml, no code edit). A bundle forwards the configs of the child plugins it owns: `dsh-agent-core` exposes `toolBash` for its built-in producer and `toolTasks` for the generic control surface, while independently composed producers such as subagent instances receive config directly. This forwarding is config reachability, not producer registration: future background-capable tools do not become `agent-core` fields unless that bundle also chooses to own them. A disabled producer omits the parameter from its schema entirely — and, because the arg validator deliberately allows undeclared keys, its `execute` ALSO refuses a forced `run_in_background: true` loud (the omission is advertising; the execution-time check is the enforcement). `ctx.tasks` plays no part in schema shaping — it never rewrites or decorates a producer's tool schema (Kimi Code regex-rewrites its bash description when background is disabled; config-owns-the-schema makes that trick unnecessary) — it only provides runtime registration. The two halves compose fail-loud: the producer's config decides what the model sees, and a background call that still reaches `start()` without a control surface throws the load-this-package error. `start()` preflights every failable check (the fence, validation, exact live owner instance, and owner-cleanup attach) BEFORE invoking the producer's `run()` and commits atomically after — background work started without a collectable id is structurally impossible, not a producer rollback obligation.
+The system prompt tells the model to retain task ids, continue independent work instead of busy-polling or duplicating a running task, collect relevant tasks before its final answer, and kill work that no longer matters. Completion injects a logged `context/message` into the exact owner's session; it becomes durable context for the next request but does not wake an idle agent.
 
-## Agent-scope owner cleanup
+The runtime marks a terminal task `reported` when a read or wait delivers it, when a live waiter has claimed delivery at settlement, or when the model explicitly kills it. Reported tasks do not inject redundant completion notices. Listener failures are logged independently, do not stop later listeners, and are not awaited by waiters or teardown.
 
-A contract-compliant background task must not outlive its owner: the subagent case leaks live child agents/sessions otherwise, and `agent/disposed` is an observe-only notification rather than a quiescence seam. Every live agent already owns an awaited structural registration scope ([agent-scope contract](2026-07-08-agent-scope-contexts.md)), so the task runtime uses that single lifecycle mechanism:
+## Producer opt-in
 
-- After validating and retaining the exact registered owner instance, the first task for that owner registers an async effect through `owner.ctx`. The effect belongs to the agent scope, survives producer reloads, selects tasks by exact owner identity, cancels them, awaits each terminal record, and drops the snapshots; a replacement reusing the same ids is outside that set.
-- `AgentHandle.dispose()` stops and drains the driver, detaches the agent and session, then awaits scope disposal. The task cleanup therefore participates in the same memoized quiescence boundary as every other agent-owned registration; no task-specific link exists in `AgentRegistry` or the loop.
-- The tasks service retains each exact owner-effect disposer so service reload can detach callbacks from still-live scopes after global task teardown, rather than leaving a dead service retained until every agent exits.
+Each producer owns whether its schema exposes `run_in_background` through defaulted config. `dsh-tool-bash` and each `dsh-tool-subagent` instance use `enableRunInBackground`, defaulting to true. A disabled instance omits the parameter and also rejects a forced background argument at execution because the generic argument validator permits undeclared keys. Schema omission advertises the capability; the execution check enforces it.
 
-For contract-compliant producers, `AgentHandle.dispose()` resolves only after the owner's background children are gone. A producer whose teardown cancel throws is the explicit degradation: its record settles `failed` with a possible-orphan detail and cleanup continues. An ownerless task is the sanctioned way for healthy work to outlive an agent, and a future durable-job RFC is the way to outlive the runtime.
+`ctx.tasks` does not rewrite producer schemas. A bundle forwards configuration only for producers it owns. If a background call reaches `start()` without an attached surface, the runtime fence fails before execution.
 
-## Bash migration
+## Producer integrations
 
-`dsh-bash` keeps the execution contract and carries no registry. The seam is `resolve`, `run`, and `start`, where `start(spec)` returns a process handle — `BashProcess`: `{ command, status, exitCode, signal, done, readOutput(), kill() }` — instead of a registry entry: `get`/`ownerOf`/`list`/`onTaskDone`, the listener machinery, `BashTaskId`, `OwnerToken`, and the spec's `owner` field are gone (a consumer census found `get`/`list` reached only by test harnesses and `onTaskDone` single-consumer — `dsh-tool-bash`; the hook bridges consume `resolve`+`run` only). The local executor keeps an internal table of LIVE processes solely for its own disposal quiescence (entries leave on settlement). The foreground trusted-plugin path (`resolve` + `run` with `stdin`/`env`, used by the hook bridges) is untouched and never routes through the runtime; `BashExecSpec.timeoutMs` stays required-but-ignored by `start()` (shared-spec status quo, documented in the seam JSDoc); the credential-scrub duplication between the bash and ACP spawn sites is explicitly NOT this runtime's work — the registry never touches process spawning.
+The bash seam exposes `resolve`, `run`, and `start`. `start(spec)` returns a `BashProcess` with incremental reads, cancellation, exit facts, and a non-rejecting quiescence promise. The local executor retains live handles only so its own disposal can kill and join processes. Foreground callers continue to use `resolve` and `run` directly.
 
-`dsh-tool-bash` keeps the `bash` tool; the `run_in_background` path is `ctx.tasks.start({ kind: 'bash', label: command, owner: exec.agent, run })` whose `run()` spawns through `ctx.bash.start(...)` and returns the hooks, where `done` maps the process exit to a `TaskOutcome` (`processOutcome`: `completed`/`killed` + exit-code/signal detail) and `readOutput` wraps the handle's incremental read with the spill/lossy formatting (`renderProcessRead`). The completion-notice listener left `dsh-tool-bash` entirely.
+For background bash, `dsh-tool-bash` registers the calling agent as owner. Its hooks map `kill()` to cancellation, `done` to a completed or killed `TaskOutcome`, and `readOutput()` to the process's bounded incremental output plus spill and sandbox notices. Generic task tools own ids, status lines, listing, waiting, and completion notices.
 
-## Subagent integration
-
-[Background subagent tasks](../feature/2026-07-08-background-subagent-tasks.md) rides this runtime while `dsh-tool-subagent` keeps its one-instance-per-provider shape. The task starter creates an independent `AbortController`, immediately begins async `ctx.subagents.start()` with that signal, and synchronously returns hooks: `cancel(reason)` aborts the controller, while `done` awaits startup rollback or the ready run's result and disposal. This covers cancellation before and after readiness through the subagent seam's one signal channel. Terminal mapping remains `completed` with final text, `aborted` as `killed`, and other reasons as `failed`; there is no `readOutput` because the child session remains the detailed trace.
+For background subagents, `dsh-tool-subagent` creates a task-owned `AbortController` and begins provider startup inside the task starter. Cancellation aborts the same signal before or after provider readiness. `done` awaits both the child result and child disposal, maps completed output to a final result, maps abort to `killed`, and maps other stop reasons or infrastructure failures to `failed`. Intermediate child history remains in the child session and is not exposed through `readOutput()`.
 
 ## Alternatives considered
 
-### Why not per-capability companion tools (`bash_output`/`bash_kill` + `subagent_wait`/`subagent_output`/`subagent_stop`)?
-
-That is the trajectory this RFC interrupted. Each capability re-implements ids, ownership, polling, stop, notices, and guidance; the model learns N collect/stop habits and the prompt carries N near-identical tool descriptions; `dsh-tool-subagent` needed a structural reshape purely to de-duplicate its clones. Claude Code walked this exact path — per-capability `BashOutput`/`KillShell` first, then a generalized `TaskOutput`/`TaskStop` spanning shells, agents, and remote sessions with the old names kept as deprecated aliases — and the pre-release stance let this repo land directly on the unified shape with no alias burden.
-
-### Why not an abstract `TaskRuntime` seam with swappable backends?
-
-There is one in-process implementation and no concrete second backend; the capability-seam rule is to split when the consumer and backend can actually evolve independently, not before. A durable/persistent job system is the plausible second backend, and it changes the lifecycle contract (survival across owner disposal) enough that its RFC should own the interface extraction.
-
-### Why not keep authorization in the consumers, as bash did?
+### Per-capability control tools
 
-The bash split put policy in `dsh-tool-bash` so the executor seam stayed session-free — right for a seam that may be implemented remotely. The registry is harness-local infrastructure whose entire purpose includes the isolation fence; leaving the fence to each consumer means every future surface (model tools, a UI bridge, hook bridges) re-implements it or forgets it. Centralizing it is most of the reason the runtime exists.
+Separate bash and subagent output/stop tools duplicate ids, isolation, cleanup, notification, and guidance while increasing the model's schema and protocol burden. One runtime keeps execution-specific behavior in producers without cloning the task lifecycle.
 
-### Why not a `parallel`-mode `agent/cleanup` event instead of the keyed registry?
+### An abstract task-runtime backend
 
-An event fires for every agent at every disposal and every listener must filter; `Promise.all` rejection semantics need extra containment; and there is no disposer to make registrations effects. A keyed registry is targeted, contained, and disposable — and the loop already drains an ordered chain, so one more awaited link was the smaller change.
+No second backend exists. Durable work also changes owner and restart semantics, so its design should extract an interface from concrete requirements rather than preserve this implementation speculatively.
 
-### Why not blocking-by-default `task_output` (Claude Code's `block: true`)?
+### Consumer-owned authorization or cleanup events
 
-The established bash habit is poll-between-work, and the guidance tells the model to keep doing independent work while tasks run; defaulting to block would silently serialize the parent on its slowest child. The explicit `wait: true` keeps blocking a deliberate act, and the wait/read/kill trio still lands within the three-tool surface.
+Consumer-owned checks invite inconsistent or missing isolation on each new surface. A broadcast cleanup event makes every listener filter every agent and provides no registration disposer. Central authorization plus one owner-scoped effect gives every consumer the same fence and an awaited, removable lifecycle hook.
 
-### Why not a separate `task_wait` tool?
+### Blocking output or a separate wait tool
 
-Waiting is never useful without reading the result afterwards; a separate tool doubles the calls and the schema surface for zero information. Folding it into `task_output` matches the only real usage pattern.
+Blocking by default would serialize the parent while background work runs. Waiting without reading would add another model call and schema without returning useful information. `task_output(wait: true)` makes blocking explicit and combines it with result delivery.
 
-### Why not `ToolDefinition.timeoutMs` (the timeout-policy plugin) for `task_output`'s wait?
+The wait uses the shared deadline primitives but not the generic tool-timeout policy. A wait timeout is a successful observation that returns `[status: running]`; the generic policy would replace it with a timeout error. No tool-call timeout controls task lifetime after a task id has been returned.
 
-The [timeout library](2026-07-06-timeout-deadline-library.md) gives `wait()` its timing internals — `ctx.tasks.wait` arms a `deadline()` and classifies wait-timeout vs caller-abort with `timeoutOf` scoped to `TASK_WAIT_TIMEOUT` — but the tool-call-level policy is deliberately NOT adopted: timeout-policy replaces a timed-out call with a structured `TOOL_TIMEOUT` failure, whereas a timed-out `task_output(wait: true)` is a SUCCESS that must still report `[status: running]` (the model needs the task's state either way, and the task keeps running). The wait therefore bounds its own deadline through the tool's `waitTimeoutMs`/`maxWaitTimeoutMs` config. For the same reason, no timeout policy manages a background task's LIFETIME: once the id is returned the work is off the tool-call deadline entirely — cancellation belongs to `task_kill` and owner cleanup.
+### Runtime-owned output sinks
 
-### Why not a push-sink producer contract (`appendOutput`/`settle`), as Kimi Code's manager uses?
+A push sink would centralize buffering, but bash already owns bounded buffers, truncation, and spill files behind its executor seam. Pulling formatted deltas preserves that ownership. A durable backend that owns storage may justify revisiting the producer interface.
 
-A sink centralizes output buffering, truncation, and spill in the runtime, which is elegant when the runtime owns output storage. In this codebase those concerns already live — bounded, tested, spill-file-aware — inside `dsh-bash-local`, and keeping process concerns in the executor is the point of the bash seam. The pull contract (`readOutput()` returning a formatted delta) reuses that machinery as-is; a sink would relocate it for no v1 gain. If a durable backend later makes the runtime own output storage, the producer contract is the one seam to revisit.
+### Random ids, promotion, or lifecycle session events
 
-### Why not random task ids (Claude Code's per-kind `36^8` suffixes)?
-
-Peers with shared registries use unguessable ids as defense-in-depth against cross-session access and predictable-path attacks. Here the owner fence is the boundary — exactly as `dsh-tool-bash` documented for the old predictable `bash-N` — and the registry hands no filesystem paths derived from the id, so sequential per-kind counters keep transcripts readable and tests deterministic. Nothing prevents switching the generator later; the id is branded and opaque to consumers.
-
-### Why not foreground→background promotion?
-
-Claude Code, Kimi Code, and OpenCode all let a running foreground call be promoted to a background task (user action or an over-budget auto-detach). It is deliberately out of v1: promotion needs a UI/user channel the SDK does not prescribe, and it changes the foreground tools' result contracts. The registration-based design leaves the door open — a foreground execution is promotable by registering its already-running work mid-flight — and a follow-up RFC can add it without touching the model-facing control tools.
-
-### Why not new session events for task lifecycle?
-
-Everything model-visible already lands in the log: starts and reads are tool calls/results, notices are injected `context/message` events. A `task/*` session event would duplicate facts the log carries, and live registry state (`task_list`) is intentionally runtime state, exactly as bash's task table was.
+Authorization, not unguessability, is the access boundary, and ids do not derive filesystem paths; sequential branded ids keep transcripts readable. Foreground-to-background promotion requires a user interaction contract the SDK does not prescribe. Starts, reads, and notices are already logged as tool and context events, so dedicated task session events would duplicate model-visible facts.
 
 ## Testing
 
-Unit coverage pins the registry lifecycle (register/read/kill/wait/list, owner isolation including no-agent callers and stale owner objects after id reuse, stream-vs-final read semantics, listener containment, notice suppression after an explicit kill or terminal read/wait, the `attachSurface` fence, start atomicity, model-facing and teardown cancel failures, ordinary disposal quiescence, and per-kind counters), the branded `SessionId` boundary, owner-effect placement and service-detach behavior, both producers' start mapping including async subagent readiness cancellation, and the structural no-uncollectable-work guarantee. Snapshot coverage pins the task tool schemas and prompt section.
+Unit coverage pins preflight atomicity, per-kind ids, stream and final reads, wait timeout and abort races, cancellation, first-wins settlement, listener containment, notice suppression, owner isolation, stale owner instances, owner cleanup, service teardown, and the no-surface fence. Producer tests cover bash process mapping, subagent startup cancellation, terminal mapping, and disposal. Snapshot coverage pins the control-tool schemas and prompt guidance.
 
 ## Consequences
 
-One background-task contract exists instead of a per-capability clone family: a background subagent and a background bash command coexist in one session under one id namespace, one listing, one notice format, and one guidance section, and the [tool cookbook](../../../cookbook/adding-a-tool.md) points long-running tools at `ctx.tasks`. The cost was a wide landing change — the bash seam lost its registry surface and every test tier moved with it, model-facing tool names churned (`bash_output`/`bash_kill` deleted), and the ACP snapshot pinned header was refreshed for the new schemas — sanctioned by the pre-release stance.
-
-Owner-scoped cleanup changed bash semantics: a task that previously outlived its agent now dies with it. Deployments that relied on fire-and-forget background commands start them unowned (a non-agent caller) or accept the new lifecycle; the uniformity was judged worth the change, and the durable-job direction remains open for real survival requirements.
-
-Teardown trusts the producer contract that a successful `cancel` leads to `done` settling at quiescence. An explicit cancel throw is detectable and force-fails the record with a possible-orphan warning so disposal cannot deadlock; a cancel that returns but silently fails is indistinguishable from a slow stop and can still stall teardown. Covering that residual requires a bounded lifetime or a separate forced-disposal contract, both outside this runtime shape.
+Bash commands and subagents share one id vocabulary, listing, notice format, prompt habit, and set of control tools. New long-running producers implement execution hooks instead of another registry and tool family. The [tool cookbook](../../../cookbook/adding-a-tool.md) points producers to this contract.
 
-`wait` is the first blocking tool call whose duration is model-controlled; the config cap bounds it, but a model that serializes on `wait` loses the parallelism the feature exists for — prompt guidance mitigates, and a future continuation-policy guard can enforce. Recording live background-flow snapshot scenarios (a polled and killed background command, a completion-notice turn) and a with-key e2e background lifecycle require a `DEEPSEEK_API_KEY` re-record and remain named follow-up work. The runtime deliberately defers durable/cross-restart tasks, non-consuming observation cursors, and foreground→background promotion (see Alternatives).
+Owned background bash now stops with its agent instead of surviving it. Background processes have no executor timeout; callers must kill irrelevant work or rely on owner/service disposal. Stream reads support one consuming reader, completion notices do not wake idle agents, and a producer that returns from `cancel` without settling `done` can still stall teardown. Durable jobs, independent observation cursors, and foreground promotion remain separate designs.

docs/rfc/implemented/feature/2026-07-08-background-subagent-tasks.md

@@ -4,59 +4,59 @@ Status: implemented
 
 ## Problem
 
-The subagent seam ([the seam RFC](2026-06-21-subagent-capability-seam.md)) exposes `start() -> SubagentRun`, and the model-facing `dsh-tool-subagent` consumer collected that run synchronously only: the parent turn blocked until the child returned one final result. That shape is simple and transport-neutral, but it makes slow delegation expensive for the parent. A model that wants two independent investigations must either run them serially or hold the parent step open for the entire child duration.
+The [subagent seam](2026-06-21-subagent-capability-seam.md) returns a `SubagentRun`, but the model-facing tool originally collected every run synchronously. Independent, slow delegations therefore held the parent call open or ran serially.
 
-The harness already had one background-task precedent in bash: task ids, owner checks, output polling, stop, completion notifications, and prompt guidance. Subagents need the same user-facing habit, but not by copying bash's process-output semantics: a subagent does not expose an incremental stdout stream, and its child session remains the home for internal steps. The parent needs to start a child, keep working, later wait for or read the final answer, and stop the task when it is no longer relevant. An earlier draft of this RFC answered by cloning the bash protocol under subagent names (`subagent_wait`, `subagent_output`, `subagent_stop`) and reshaping `dsh-tool-subagent` into a multi-tool plugin so the clones would not collide across instances; [the background task runtime RFC](../architecture/2026-06-20-generic-long-running-tool-runtime.md) dissolved that duplication by extracting the registry and the control tools once, and this feature rides it.
-
-The design also has two lifecycle constraints that the synchronous path does not face. First, a background subagent can outlive the tool call that started it, so the tool-call abort signal must not stay wired to the child after the id is returned. Second, a completion notice can only be injected into a live owner agent: once an ACP session closes or an agent handle is disposed, `agent.inject()` cannot append to that session. The feature must therefore define whether background subagents survive owner disposal.
+Subagents need the same start, collect, list, stop, ownership, notification, and cleanup behavior as other long-running tools without adopting process-stream semantics. The child session remains the detailed trace; the parent needs the final answer and task status. A background child also outlives its starting tool call, so its cancellation and owner-disposal contracts must be explicit.
 
 ## Decision
 
-Each `dsh-tool-subagent` instance may expose `run_in_background?: boolean`, gated per instance by its defaulted `enableRunInBackground` config flag (default `true`; a disabled instance omits the parameter from its schema — the producer-opt-in shape [the runtime RFC](../architecture/2026-06-20-generic-long-running-tool-runtime.md) pins: the producer's config owns the schema, `ctx.tasks` only provides runtime registration). The plugin keeps its one-instance-per-provider shape — provider selection stays deployment config (`subagent` on `spawn`, `subagent_fork` on `fork`, …), and there are no subagent-specific companion tools to collide: collection, listing, and cancellation are the generic `task_output`/`task_list`/`task_kill` tools from `@deepseek-ai/dsh-tool-tasks`.
+Each `dsh-tool-subagent` instance may expose `run_in_background`, controlled by `enableRunInBackground` and enabled by default. A disabled instance omits the parameter and rejects a forced background argument at execution. Provider selection remains deployment configuration, so one instance still registers one distinctly named tool for one provider.
+
+Background subagents use the [generic background task runtime](../architecture/2026-06-20-generic-long-running-tool-runtime.md). Collection, listing, cancellation, completion notices, and prompt guidance come from `task_output`, `task_list`, and `task_kill`; there are no subagent-specific companion tools.
 
-A foreground call keeps the synchronous semantics: it waits for `run.result`, returns final text on `completed`, maps non-clean terminal stop reasons to an errored tool result, and disposes the run in `finally`.
+Foreground calls retain their synchronous contract: await provider startup and `run.result`, return final text only for `completed`, map other terminal reasons to an errored tool result, and always dispose the run before returning.
 
-A background call validates that a parent agent exists, checks an already-aborted tool signal, and hands the delegation to `ctx.tasks.start()`. The runtime preflights the control-surface fence and owner-scope cleanup before its synchronous `run()` starter creates an independent `AbortController` and begins async `ctx.subagents.start()`; commit after that starter cannot fail, so provider work cannot become uncollectable. The task-owned signal, not the tool-call signal, then covers pending readiness and the live child. `ctx.tasks.start()` supplies kind-prefixed branded ids, owner-scoped access, loud no-control-surface failure, completion notices, and generic prompt guidance.
+For a background call, the tool validates the parent and refuses an already-aborted execution signal before calling `ctx.tasks.start()`. The task runtime preflights the control surface and owner cleanup before invoking the producer starter. That starter creates an independent `AbortController` and begins `ctx.subagents.start()`; after the id is returned, the tool-call signal no longer owns the child.
 
-The registration maps the seam vocabulary onto the runtime's:
+The task registration maps the subagent seam as follows:
 
-- `kind: 'subagent'`, `label`: the model's `description` argument, `owner`: the parent agent.
-- `cancel`: abort the task-owned controller with `task_kill`'s optional logged reason; the same signal cancels provider-owned partial startup or a published child, and the task shows as `stopping` until settlement.
-- `done`: await `ctx.subagents.start()`. A cancellation rejection after startup rollback maps to `killed`; another startup rejection maps to `failed`. A ready run flows through `settleRun`, which awaits `run.result`, then `run.dispose()` (child quiescence), and maps `completed` to final `output`, `aborted` to `killed`, and other stop reasons to `failed`. Infrastructure and disposal failures settle `failed` rather than rejecting the task contract.
-- No `readOutput`: a subagent task is final-output-only. While it runs, `task_output` returns only the status line; once terminal it returns the final text (or failure detail) idempotently. The child session remains the detailed trace; v1 deliberately exposes no incremental transcript cursor.
+- `kind` is `subagent`, `label` is the model-supplied description, and `owner` is the parent agent.
+- `cancel(reason?)` aborts the task-owned controller. The same signal covers pending provider startup and the ready child.
+- `done` awaits provider startup, the child result, and `run.dispose()`. Completed runs return final text, aborted runs become `killed`, and other stop reasons become `failed`. Startup, result, and disposal failures become failed outcomes rather than rejected task promises.
+- `readOutput` is absent. While live, `task_output` returns status only; after settlement, it returns final output idempotently. Intermediate child activity remains in the child session.
 
 ## Lifecycle
 
-The background task is scoped to the owner session, not durable across session closure. The runtime registers one async cleanup through the exact owner's `agent.ctx`; agent-scope disposal cancels running tasks and awaits each `done` before `AgentHandle.dispose()` resolves. Since subagent `done` settles only after startup rollback or `run.dispose()`, owner disposal reaches child quiescence without leaking child agents or sessions. Completion notices are best-effort: a live owner gets the injection, while teardown that already detached or disposed the owner drops it.
+A background subagent belongs to its parent agent and is not durable across owner closure. The task runtime attaches cleanup to the exact owner's scope. Agent disposal cancels the task and awaits startup rollback or child disposal before `AgentHandle.dispose()` resolves, preventing leaked child agents and sessions.
+
+Completion notices target the exact owner captured at start. If owner teardown has already disposed the injection target, the notice is dropped; cleanup, not notification, is the lifecycle guarantee.
 
 ## Model guidance
 
-The background-task habit (track ids, do not finish while a relevant task runs, collect with `task_output`, kill what stopped mattering) is the generic `dsh-tool-tasks` prompt section — one habit for bash and subagents alike, which is the point of the shared runtime. `dsh-tool-subagent` adds only the wording on its own tool: the description and the `run_in_background` parameter say the call returns a task id immediately and the final answer is collected with `task_output` (with `wait: true` when genuinely blocked on it). Runtime enforcement remains owner authorization and the awaited owner-cleanup path, not the prompt.
+The generic task prompt teaches the shared habit: retain ids, continue independent work instead of busy-polling, collect relevant tasks before answering, and kill irrelevant work. The subagent schema adds only that background mode returns a task id and that `task_output` collects the result. Authorization and owner cleanup enforce the runtime boundary independently of prompt compliance.
 
 ## Alternatives considered
 
-### Why not subagent-specific `subagent_wait`/`subagent_output`/`subagent_stop` tools?
+### Subagent-specific wait, output, and stop tools
 
-The earlier draft of this RFC. The clones duplicate the bash protocol, teach the model a second collect/stop habit, and force a structural reshape of `dsh-tool-subagent` (one multi-tool instance instead of one instance per provider) purely so the companion tools register once. The generic runtime provides the same operations kind-agnostically, keeps this plugin's shape untouched, and its `attachSurface` fence covers the half-loaded deployment failure the reshape was defending against. The reshape was dropped with the clones.
+Capability-specific tools would duplicate the task protocol, teach another collect-and-stop habit, and complicate multiple provider instances. The generic runtime provides the required behavior without changing the tool's one-provider-per-instance shape.
 
-### Why not let background subagents survive owner session closure?
+### Survival after owner closure
 
-Survival after owner closure requires durable task state, child-session recovery, a way to surface late results into a reopened session, and policy for tasks whose owning client never returns. The agent runtime unregisters disposed agents, and `agent.inject()` intentionally rejects disposed targets. Scoping tasks to the owner and cleaning up through the awaited path makes the v1 lifecycle explicit and avoids orphaned child agents; a durable job system is the runtime RFC's named future direction, not this feature.
+Survival requires persistent task state, child-session recovery, a late-result delivery channel, and policy for abandoned owners. Owner-scoped cleanup gives process-local work a clear lifetime. Durable jobs require a separate design.
 
-### Why not skip owner checks because ACP sessions are isolated?
+### No owner checks for isolated clients
 
-ACP sessions isolate their logs and agents, but services such as `ctx.agents`, `ctx.tools`, and `ctx.tasks` are shared within the runtime, and task ids are global, predictable resource handles. The runtime enforces the owner fence for every task kind; this RFC merely notes that subagent tasks inherit it.
+Agents and logs may be session-scoped, but the task registry and predictable ids are runtime-global. The generic owner fence therefore applies to subagents like every other producer.
 
-### Why not expose incremental subagent transcript output?
+### Incremental child transcript output
 
-The child session is already the trace for internal reasoning, tool calls, and intermediate messages. Streaming that transcript into the parent would blur the parent/child log boundary that makes in-process and ACP providers equivalent. The first background surface returns status and final output only; richer observation belongs to UI/session tooling or a separate observation RFC.
+Streaming child history into the parent would blur the log boundary and make provider behavior diverge. This surface exposes final output only; richer observation belongs to session or UI tooling.
 
 ## Testing
 
-Unit coverage pins the stop-reason → outcome mapping (`runOutcome`, including unknown merge-extensible reasons), `settleRun`'s dispose-before-report on both result paths, the detached-signal contract (a pre-aborted signal refuses to start; a returned id is never wired to the tool signal), background settlement collected through the real `task_output`/`task_kill` tools, the structural no-orphan guarantee (a failed `tasks.start` preflight never invokes the provider), per-instance schema gating (`enableRunInBackground: false` omits the parameter and the background wording), and the loud failure when the tasks runtime is absent. Snapshot coverage pins the changed `subagent`/`subagent_fork` schemas through the pinned-header fixture; recording a live background-delegation transcript requires a `DEEPSEEK_API_KEY` re-record and remains named follow-up work.
+Unit coverage pins stop-reason mapping, dispose-before-report behavior, startup and result failures, pre-aborted refusal, detachment from the starting call's signal, cancellation before and after provider readiness, collection through the real task tools, the no-surface preflight fence, missing-runtime failure, and per-instance schema gating. Snapshot coverage pins the model-facing schemas.
 
 ## Consequences
 
-Slow delegation no longer holds the parent step open: the model fans out background children, keeps working, and collects with the same three control tools it already uses for bash — no new habit, no schema clones, and `dsh-tool-subagent`'s per-provider shape survived unchanged. The feature's usability depends on the tasks pair being loaded; the runtime's `start()` preflight fence turns a missing control surface into a loud, actionable error (raised before any child exists) rather than a silent dead end, and the `dsh-agent-core` bundle ships the pair so every stock deployment has it.
-
-The prompt guidance reduces abandoned tasks but cannot force a model to collect every background result. Runtime cleanup through the awaited owner-disposal path is the hard stop; a future planner or guard could enforce "no final answer with relevant running tasks" more strongly if the prompt proves insufficient. A background child outliving its starting tool call means a misbehaving child consumes tokens until collected, killed, or owner-disposed; `task_list` keeps it visible, and setting `enableRunInBackground: false` per instance keeps a deployment's delegation strictly synchronous.
+The parent can fan out slow delegations and collect them through the same task controls used by bash. Child work no longer occupies the starting tool call, but it can consume resources until collected, killed, or owner-disposed. Prompt guidance encourages collection; owner cleanup provides the hard lifetime boundary. Deployments that require synchronous delegation can disable background mode per tool instance.

docs/tool-catalog.md

@@ -357,7 +357,7 @@ Source: [`packages/skill/tool-skill/src/index.ts`](../packages/skill/tool-skill/
 
 ### `subagent`
 
-Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation. Set `run_in_background: true` to get a task id immediately and keep working; collect the final answer with `task_output` (wait: true when you are blocked on it) and stop it with `task_kill`.
+Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation. Set `run_in_background: true` to return a task id; collect with `task_output` and stop with `task_kill`.
 
 ```json
 {
@@ -373,7 +373,7 @@ Delegate a self-contained task to a subagent (a separate agent that works in its
     },
     "run_in_background": {
       "type": "boolean",
-      "description": "Run the subagent as a background task and return a task id immediately (collect with task_output, stop with task_kill)."
+      "description": "Run as a background task and return its id; collect with task_output or stop with task_kill."
     }
   },
   "required": [
@@ -429,7 +429,7 @@ Source: [`packages/tasks/tool-tasks/src/index.ts`](../packages/tasks/tool-tasks/
 
 ### `task_output`
 
-Read output/status from a background task (started by a tool with `run_in_background`). Stream tasks (bash) return only output produced since your previous task_output call; final-output tasks (subagent) return the final answer once the task finishes. Every response ends with a [status: ...] line. Non-blocking by default; set `wait: true` to block until the task finishes (bounded by a capped timeout) when you are genuinely blocked on its result.
+Read a background task. Stream tasks return only output since the previous read; final-output tasks return their result after settlement. Every response ends with `[status: ...]`. Reads are non-blocking unless `wait: true`, which waits up to the configured cap.
 
 ```json
 {

examples/acp-agent/tests/snapshots/advanced-toolchain/system-prompt.golden.md

@@ -64,22 +64,22 @@ declare const tools: {
     /** The exact skill name from the available skills list. */
     name: string;
   }): Promise<string>;
-  /** Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation. Set `run_in_background: true` to get a task id immediately and keep working; collect the final answer with `task_output` (wait: true when you are blocked on it) and stop it with `task_kill`. */
+  /** Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation. Set `run_in_background: true` to return a task id; collect with `task_output` and stop with `task_kill`. */
   subagent(args: {
     /** A short (3-5 word) description of the delegated task, for display. */
     description: string;
     /** The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs. */
     prompt: string;
-    /** Run the subagent as a background task and return a task id immediately (collect with task_output, stop with task_kill). */
+    /** Run as a background task and return its id; collect with task_output or stop with task_kill. */
     run_in_background?: boolean;
   }): Promise<string>;
-  /** Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps. Set `run_in_background: true` to get a task id immediately and keep working; collect the final answer with `task_output` (wait: true when you are blocked on it) and stop it with `task_kill`. */
+  /** Delegate a task to a subagent that inherits this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps. Set `run_in_background: true` to return a task id; collect with `task_output` and stop with `task_kill`. */
   subagent_fork(args: {
     /** A short (3-5 word) description of the delegated task, for display. */
     description: string;
     /** The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new. */
     prompt: string;
-    /** Run the subagent as a background task and return a task id immediately (collect with task_output, stop with task_kill). */
+    /** Run as a background task and return its id; collect with task_output or stop with task_kill. */
     run_in_background?: boolean;
   }): Promise<string>;
   /** Request cancellation of a running background task by task id. Returns immediately; the task settles as killed once its work actually stops. */
@@ -91,7 +91,7 @@ declare const tools: {
   }): Promise<string>;
   /** List your background tasks (running and finished) with their ids, kinds, and statuses. */
   task_list(args: Record<string, unknown>): Promise<string>;
-  /** Read output/status from a background task (started by a tool with `run_in_background`). Stream tasks (bash) return only output produced since your previous task_output call; final-output tasks (subagent) return the final answer once the task finishes. Every response ends with a [status: ...] line. Non-blocking by default; set `wait: true` to block until the task finishes (bounded by a capped timeout) when you are genuinely blocked on its result. */
+  /** Read a background task. Stream tasks return only output since the previous read; final-output tasks return their result after settlement. Every response ends with `[status: ...]`. Reads are non-blocking unless `wait: true`, which waits up to the configured cap. */
   task_output(args: {
     /** Task id returned by the tool that started the background work. */
     task_id: string;

examples/acp-agent/tests/snapshots/advanced-toolchain/tool-schemas.golden.json

@@ -132,7 +132,7 @@
     },
     {
       "name": "subagent",
-      "description": "Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation. Set `run_in_background: true` to get a task id immediately and keep working; collect the final answer with `task_output` (wait: true when you are blocked on it) and stop it with `task_kill`.",
+      "description": "Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation. Set `run_in_background: true` to return a task id; collect with `task_output` and stop with `task_kill`.",
       "parameters": {
         "type": "object",
         "properties": {
@@ -146,7 +146,7 @@
           },
           "run_in_background": {
             "type": "boolean",
-            "description": "Run the subagent as a background task and return a task id immediately (collect with task_output, stop with task_kill)."
+            "description": "Run as a background task and return its id; collect with task_output or stop with task_kill."
           }
         },
         "required": [
@@ -157,7 +157,7 @@
     },
     {
       "name": "subagent_fork",
-      "description": "Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps. Set `run_in_background: true` to get a task id immediately and keep working; collect the final answer with `task_output` (wait: true when you are blocked on it) and stop it with `task_kill`.",
+      "description": "Delegate a task to a subagent that inherits this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps. Set `run_in_background: true` to return a task id; collect with `task_output` and stop with `task_kill`.",
       "parameters": {
         "type": "object",
         "properties": {
@@ -171,7 +171,7 @@
           },
           "run_in_background": {
             "type": "boolean",
-            "description": "Run the subagent as a background task and return a task id immediately (collect with task_output, stop with task_kill)."
+            "description": "Run as a background task and return its id; collect with task_output or stop with task_kill."
           }
         },
         "required": [
@@ -210,7 +210,7 @@
     },
     {
       "name": "task_output",
-      "description": "Read output/status from a background task (started by a tool with `run_in_background`). Stream tasks (bash) return only output produced since your previous task_output call; final-output tasks (subagent) return the final answer once the task finishes. Every response ends with a [status: ...] line. Non-blocking by default; set `wait: true` to block until the task finishes (bounded by a capped timeout) when you are genuinely blocked on its result.",
+      "description": "Read a background task. Stream tasks return only output since the previous read; final-output tasks return their result after settlement. Every response ends with `[status: ...]`. Reads are non-blocking unless `wait: true`, which waits up to the configured cap.",
       "parameters": {
         "type": "object",
         "properties": {

examples/acp-agent/tests/snapshots/both-mode-turn/system-prompt.golden.md

@@ -49,22 +49,22 @@ declare const tools: {
     /** The exact skill name from the available skills list. */
     name: string;
   }): Promise<string>;
-  /** Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation. Set `run_in_background: true` to get a task id immediately and keep working; collect the final answer with `task_output` (wait: true when you are blocked on it) and stop it with `task_kill`. */
+  /** Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation. Set `run_in_background: true` to return a task id; collect with `task_output` and stop with `task_kill`. */
   subagent(args: {
     /** A short (3-5 word) description of the delegated task, for display. */
     description: string;
     /** The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs. */
     prompt: string;
-    /** Run the subagent as a background task and return a task id immediately (collect with task_output, stop with task_kill). */
+    /** Run as a background task and return its id; collect with task_output or stop with task_kill. */
     run_in_background?: boolean;
   }): Promise<string>;
-  /** Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps. Set `run_in_background: true` to get a task id immediately and keep working; collect the final answer with `task_output` (wait: true when you are blocked on it) and stop it with `task_kill`. */
+  /** Delegate a task to a subagent that inherits this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps. Set `run_in_background: true` to return a task id; collect with `task_output` and stop with `task_kill`. */
   subagent_fork(args: {
     /** A short (3-5 word) description of the delegated task, for display. */
     description: string;
     /** The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new. */
     prompt: string;
-    /** Run the subagent as a background task and return a task id immediately (collect with task_output, stop with task_kill). */
+    /** Run as a background task and return its id; collect with task_output or stop with task_kill. */
     run_in_background?: boolean;
   }): Promise<string>;
   /** Request cancellation of a running background task by task id. Returns immediately; the task settles as killed once its work actually stops. */
@@ -76,7 +76,7 @@ declare const tools: {
   }): Promise<string>;
   /** List your background tasks (running and finished) with their ids, kinds, and statuses. */
   task_list(args: Record<string, unknown>): Promise<string>;
-  /** Read output/status from a background task (started by a tool with `run_in_background`). Stream tasks (bash) return only output produced since your previous task_output call; final-output tasks (subagent) return the final answer once the task finishes. Every response ends with a [status: ...] line. Non-blocking by default; set `wait: true` to block until the task finishes (bounded by a capped timeout) when you are genuinely blocked on its result. */
+  /** Read a background task. Stream tasks return only output since the previous read; final-output tasks return their result after settlement. Every response ends with `[status: ...]`. Reads are non-blocking unless `wait: true`, which waits up to the configured cap. */
   task_output(args: {
     /** Task id returned by the tool that started the background work. */
     task_id: string;

examples/acp-agent/tests/snapshots/both-mode-turn/tool-schemas.golden.json

@@ -79,7 +79,7 @@
     },
     {
       "name": "subagent",
-      "description": "Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation. Set `run_in_background: true` to get a task id immediately and keep working; collect the final answer with `task_output` (wait: true when you are blocked on it) and stop it with `task_kill`.",
+      "description": "Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation. Set `run_in_background: true` to return a task id; collect with `task_output` and stop with `task_kill`.",
       "parameters": {
         "type": "object",
         "properties": {
@@ -93,7 +93,7 @@
           },
           "run_in_background": {
             "type": "boolean",
-            "description": "Run the subagent as a background task and return a task id immediately (collect with task_output, stop with task_kill)."
+            "description": "Run as a background task and return its id; collect with task_output or stop with task_kill."
           }
         },
         "required": [
@@ -104,7 +104,7 @@
     },
     {
       "name": "subagent_fork",
-      "description": "Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps. Set `run_in_background: true` to get a task id immediately and keep working; collect the final answer with `task_output` (wait: true when you are blocked on it) and stop it with `task_kill`.",
+      "description": "Delegate a task to a subagent that inherits this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps. Set `run_in_background: true` to return a task id; collect with `task_output` and stop with `task_kill`.",
       "parameters": {
         "type": "object",
         "properties": {
@@ -118,7 +118,7 @@
           },
           "run_in_background": {
             "type": "boolean",
-            "description": "Run the subagent as a background task and return a task id immediately (collect with task_output, stop with task_kill)."
+            "description": "Run as a background task and return its id; collect with task_output or stop with task_kill."
           }
         },
         "required": [
@@ -157,7 +157,7 @@
     },
     {
       "name": "task_output",
-      "description": "Read output/status from a background task (started by a tool with `run_in_background`). Stream tasks (bash) return only output produced since your previous task_output call; final-output tasks (subagent) return the final answer once the task finishes. Every response ends with a [status: ...] line. Non-blocking by default; set `wait: true` to block until the task finishes (bounded by a capped timeout) when you are genuinely blocked on its result.",
+      "description": "Read a background task. Stream tasks return only output since the previous read; final-output tasks return their result after settlement. Every response ends with `[status: ...]`. Reads are non-blocking unless `wait: true`, which waits up to the configured cap.",
       "parameters": {
         "type": "object",
         "properties": {

examples/acp-agent/tests/snapshots/code-mode-turn/system-prompt.golden.md

@@ -49,22 +49,22 @@ declare const tools: {
     /** The exact skill name from the available skills list. */
     name: string;
   }): Promise<string>;
-  /** Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation. Set `run_in_background: true` to get a task id immediately and keep working; collect the final answer with `task_output` (wait: true when you are blocked on it) and stop it with `task_kill`. */
+  /** Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation. Set `run_in_background: true` to return a task id; collect with `task_output` and stop with `task_kill`. */
   subagent(args: {
     /** A short (3-5 word) description of the delegated task, for display. */
     description: string;
     /** The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs. */
     prompt: string;
-    /** Run the subagent as a background task and return a task id immediately (collect with task_output, stop with task_kill). */
+    /** Run as a background task and return its id; collect with task_output or stop with task_kill. */
     run_in_background?: boolean;
   }): Promise<string>;
-  /** Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps. Set `run_in_background: true` to get a task id immediately and keep working; collect the final answer with `task_output` (wait: true when you are blocked on it) and stop it with `task_kill`. */
+  /** Delegate a task to a subagent that inherits this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps. Set `run_in_background: true` to return a task id; collect with `task_output` and stop with `task_kill`. */
   subagent_fork(args: {
     /** A short (3-5 word) description of the delegated task, for display. */
     description: string;
     /** The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new. */
     prompt: string;
-    /** Run the subagent as a background task and return a task id immediately (collect with task_output, stop with task_kill). */
+    /** Run as a background task and return its id; collect with task_output or stop with task_kill. */
     run_in_background?: boolean;
   }): Promise<string>;
   /** Request cancellation of a running background task by task id. Returns immediately; the task settles as killed once its work actually stops. */
@@ -76,7 +76,7 @@ declare const tools: {
   }): Promise<string>;
   /** List your background tasks (running and finished) with their ids, kinds, and statuses. */
   task_list(args: Record<string, unknown>): Promise<string>;
-  /** Read output/status from a background task (started by a tool with `run_in_background`). Stream tasks (bash) return only output produced since your previous task_output call; final-output tasks (subagent) return the final answer once the task finishes. Every response ends with a [status: ...] line. Non-blocking by default; set `wait: true` to block until the task finishes (bounded by a capped timeout) when you are genuinely blocked on its result. */
+  /** Read a background task. Stream tasks return only output since the previous read; final-output tasks return their result after settlement. Every response ends with `[status: ...]`. Reads are non-blocking unless `wait: true`, which waits up to the configured cap. */
   task_output(args: {
     /** Task id returned by the tool that started the background work. */
     task_id: string;

examples/acp-agent/tests/snapshots/permission-switching/tool-schemas.golden.json

@@ -63,7 +63,7 @@
     },
     {
       "name": "subagent",
-      "description": "Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation. Set `run_in_background: true` to get a task id immediately and keep working; collect the final answer with `task_output` (wait: true when you are blocked on it) and stop it with `task_kill`.",
+      "description": "Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation. Set `run_in_background: true` to return a task id; collect with `task_output` and stop with `task_kill`.",
       "parameters": {
         "type": "object",
         "properties": {
@@ -77,7 +77,7 @@
           },
           "run_in_background": {
             "type": "boolean",
-            "description": "Run the subagent as a background task and return a task id immediately (collect with task_output, stop with task_kill)."
+            "description": "Run as a background task and return its id; collect with task_output or stop with task_kill."
           }
         },
         "required": [
@@ -88,7 +88,7 @@
     },
     {
       "name": "subagent_fork",
-      "description": "Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps. Set `run_in_background: true` to get a task id immediately and keep working; collect the final answer with `task_output` (wait: true when you are blocked on it) and stop it with `task_kill`.",
+      "description": "Delegate a task to a subagent that inherits this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps. Set `run_in_background: true` to return a task id; collect with `task_output` and stop with `task_kill`.",
       "parameters": {
         "type": "object",
         "properties": {
@@ -102,7 +102,7 @@
           },
           "run_in_background": {
             "type": "boolean",
-            "description": "Run the subagent as a background task and return a task id immediately (collect with task_output, stop with task_kill)."
+            "description": "Run as a background task and return its id; collect with task_output or stop with task_kill."
           }
         },
         "required": [
@@ -141,7 +141,7 @@
     },
     {
       "name": "task_output",
-      "description": "Read output/status from a background task (started by a tool with `run_in_background`). Stream tasks (bash) return only output produced since your previous task_output call; final-output tasks (subagent) return the final answer once the task finishes. Every response ends with a [status: ...] line. Non-blocking by default; set `wait: true` to block until the task finishes (bounded by a capped timeout) when you are genuinely blocked on its result.",
+      "description": "Read a background task. Stream tasks return only output since the previous read; final-output tasks return their result after settlement. Every response ends with `[status: ...]`. Reads are non-blocking unless `wait: true`, which waits up to the configured cap.",
       "parameters": {
         "type": "object",
         "properties": {

examples/acp-agent/tests/snapshots/skill-load/tool-schemas.golden.json

@@ -63,7 +63,7 @@
     },
     {
       "name": "subagent",
-      "description": "Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation. Set `run_in_background: true` to get a task id immediately and keep working; collect the final answer with `task_output` (wait: true when you are blocked on it) and stop it with `task_kill`.",
+      "description": "Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation. Set `run_in_background: true` to return a task id; collect with `task_output` and stop with `task_kill`.",
       "parameters": {
         "type": "object",
         "properties": {
@@ -77,7 +77,7 @@
           },
           "run_in_background": {
             "type": "boolean",
-            "description": "Run the subagent as a background task and return a task id immediately (collect with task_output, stop with task_kill)."
+            "description": "Run as a background task and return its id; collect with task_output or stop with task_kill."
           }
         },
         "required": [
@@ -88,7 +88,7 @@
     },
     {
       "name": "subagent_fork",
-      "description": "Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps. Set `run_in_background: true` to get a task id immediately and keep working; collect the final answer with `task_output` (wait: true when you are blocked on it) and stop it with `task_kill`.",
+      "description": "Delegate a task to a subagent that inherits this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps. Set `run_in_background: true` to return a task id; collect with `task_output` and stop with `task_kill`.",
       "parameters": {
         "type": "object",
         "properties": {
@@ -102,7 +102,7 @@
           },
           "run_in_background": {
             "type": "boolean",
-            "description": "Run the subagent as a background task and return a task id immediately (collect with task_output, stop with task_kill)."
+            "description": "Run as a background task and return its id; collect with task_output or stop with task_kill."
           }
         },
         "required": [
@@ -141,7 +141,7 @@
     },
     {
       "name": "task_output",
-      "description": "Read output/status from a background task (started by a tool with `run_in_background`). Stream tasks (bash) return only output produced since your previous task_output call; final-output tasks (subagent) return the final answer once the task finishes. Every response ends with a [status: ...] line. Non-blocking by default; set `wait: true` to block until the task finishes (bounded by a capped timeout) when you are genuinely blocked on its result.",
+      "description": "Read a background task. Stream tasks return only output since the previous read; final-output tasks return their result after settlement. Every response ends with `[status: ...]`. Reads are non-blocking unless `wait: true`, which waits up to the configured cap.",
       "parameters": {
         "type": "object",
         "properties": {

examples/acp-agent/tests/snapshots/text-turn/tool-schemas.golden.json

@@ -63,7 +63,7 @@
     },
     {
       "name": "subagent",
-      "description": "Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation. Set `run_in_background: true` to get a task id immediately and keep working; collect the final answer with `task_output` (wait: true when you are blocked on it) and stop it with `task_kill`.",
+      "description": "Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation. Set `run_in_background: true` to return a task id; collect with `task_output` and stop with `task_kill`.",
       "parameters": {
         "type": "object",
         "properties": {
@@ -77,7 +77,7 @@
           },
           "run_in_background": {
             "type": "boolean",
-            "description": "Run the subagent as a background task and return a task id immediately (collect with task_output, stop with task_kill)."
+            "description": "Run as a background task and return its id; collect with task_output or stop with task_kill."
           }
         },
         "required": [
@@ -88,7 +88,7 @@
     },
     {
       "name": "subagent_fork",
-      "description": "Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps. Set `run_in_background: true` to get a task id immediately and keep working; collect the final answer with `task_output` (wait: true when you are blocked on it) and stop it with `task_kill`.",
+      "description": "Delegate a task to a subagent that inherits this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps. Set `run_in_background: true` to return a task id; collect with `task_output` and stop with `task_kill`.",
       "parameters": {
         "type": "object",
         "properties": {
@@ -102,7 +102,7 @@
           },
           "run_in_background": {
             "type": "boolean",
-            "description": "Run the subagent as a background task and return a task id immediately (collect with task_output, stop with task_kill)."
+            "description": "Run as a background task and return its id; collect with task_output or stop with task_kill."
           }
         },
         "required": [
@@ -141,7 +141,7 @@
     },
     {
       "name": "task_output",
-      "description": "Read output/status from a background task (started by a tool with `run_in_background`). Stream tasks (bash) return only output produced since your previous task_output call; final-output tasks (subagent) return the final answer once the task finishes. Every response ends with a [status: ...] line. Non-blocking by default; set `wait: true` to block until the task finishes (bounded by a capped timeout) when you are genuinely blocked on its result.",
+      "description": "Read a background task. Stream tasks return only output since the previous read; final-output tasks return their result after settlement. Every response ends with `[status: ...]`. Reads are non-blocking unless `wait: true`, which waits up to the configured cap.",
       "parameters": {
         "type": "object",
         "properties": {

examples/acp-agent/tests/snapshots/workspace-edit/tool-schemas.golden.json

@@ -117,7 +117,7 @@
     },
     {
       "name": "subagent",
-      "description": "Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation. Set `run_in_background: true` to get a task id immediately and keep working; collect the final answer with `task_output` (wait: true when you are blocked on it) and stop it with `task_kill`.",
+      "description": "Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation. Set `run_in_background: true` to return a task id; collect with `task_output` and stop with `task_kill`.",
       "parameters": {
         "type": "object",
         "properties": {
@@ -131,7 +131,7 @@
           },
           "run_in_background": {
             "type": "boolean",
-            "description": "Run the subagent as a background task and return a task id immediately (collect with task_output, stop with task_kill)."
+            "description": "Run as a background task and return its id; collect with task_output or stop with task_kill."
           }
         },
         "required": [
@@ -142,7 +142,7 @@
     },
     {
       "name": "subagent_fork",
-      "description": "Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps. Set `run_in_background: true` to get a task id immediately and keep working; collect the final answer with `task_output` (wait: true when you are blocked on it) and stop it with `task_kill`.",
+      "description": "Delegate a task to a subagent that inherits this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps. Set `run_in_background: true` to return a task id; collect with `task_output` and stop with `task_kill`.",
       "parameters": {
         "type": "object",
         "properties": {
@@ -156,7 +156,7 @@
           },
           "run_in_background": {
             "type": "boolean",
-            "description": "Run the subagent as a background task and return a task id immediately (collect with task_output, stop with task_kill)."
+            "description": "Run as a background task and return its id; collect with task_output or stop with task_kill."
           }
         },
         "required": [
@@ -195,7 +195,7 @@
     },
     {
       "name": "task_output",
-      "description": "Read output/status from a background task (started by a tool with `run_in_background`). Stream tasks (bash) return only output produced since your previous task_output call; final-output tasks (subagent) return the final answer once the task finishes. Every response ends with a [status: ...] line. Non-blocking by default; set `wait: true` to block until the task finishes (bounded by a capped timeout) when you are genuinely blocked on its result.",
+      "description": "Read a background task. Stream tasks return only output since the previous read; final-output tasks return their result after settlement. Every response ends with `[status: ...]`. Reads are non-blocking unless `wait: true`, which waits up to the configured cap.",
       "parameters": {
         "type": "object",
         "properties": {

packages/bash/bash-local/src/index.ts

@@ -1,17 +1,7 @@
 /**
- * `LocalBashExecutor`: the local-subprocess implementation of the
- * `@deepseek-ai/dsh-bash` executor seam. Spawns `bash -c` per call in its
- * own process group (see `./run.ts` for the plumbing and the agent-tool
- * survey notes), tracks live background processes for disposal quiescence
- * ONLY (task semantics live in `ctx.tasks`), and kills everything on dispose.
- *
- * TODO(permissions/sandbox): execution policy does NOT belong here — use
- * the `tools/pre-execute` deny/ask gate (see docs/architecture.md
- * § Extending The Harness) or implement a sandboxing `BashExecutor`.
- * Reference points:
- * Claude Code wraps commands in sandbox-exec/bubblewrap; Codex applies
- * seatbelt/landlock plus an execpolicy prefix-rule engine.
- *
+ * Local-subprocess implementation of the bash executor seam. Each command runs
+ * as `bash -c` in its own process group; disposal kills and joins live groups.
+ * Execution policy belongs in `tools/pre-execute` or a sandboxing executor.
  * @module @deepseek-ai/dsh-bash-local
  */
 
@@ -47,10 +37,8 @@ function assertPositiveFinite(name: string, value: number): void {
 }
 
 /**
- * Local-subprocess bash executor. Defaults follow the agent-tool survey
- * consensus: 120s default / 600s max timeout (Claude Code, OpenCode), 64KB
- * in-memory output with full-stream spill files (pi, OpenCode),
- * process-group SIGTERM→SIGKILL kills with a 3s grace (OpenCode).
+ * Local bash executor with bounded output, spill files, and process-group
+ * `SIGTERM` to `SIGKILL` escalation.
  */
 export class LocalBashExecutor extends BashExecutor {
   static Config: z<Config> = z.object({
@@ -61,11 +49,7 @@ export class LocalBashExecutor extends BashExecutor {
     graceMs: z.number().default(DEFAULT_GRACE_MS),
   })
 
-  /**
-   * Live background processes, tracked for DISPOSAL only: an entry leaves
-   * the map the moment its process settles (callers keep reading through
-   * their own {@link BashProcess} handle — the buffers live on it).
-   */
+  /** Live processes retained only so disposal can kill and join them. */
   private live = new Map<BashProcess, RunningBash>()
   /** Test seam: spill knobs forwarded to runBash. */
   internals: RunInternals = {}
@@ -75,17 +59,14 @@ export class LocalBashExecutor extends BashExecutor {
 
   constructor(ctx: Context, config: Config) {
     super(ctx)
-    // schemastery (static Config) has already filled the defaulted fields;
-    // the cast records that runtime fact for exactOptionalPropertyTypes.
+    // Schemastery fills these fields before construction; the type does not encode that step.
     this.config = config as ResolvedConfig
     assertPositiveFinite('timeoutMs', this.config.timeoutMs)
     assertPositiveFinite('maxTimeoutMs', this.config.maxTimeoutMs)
     assertPositiveFinite('maxOutputBytes', this.config.maxOutputBytes)
     assertPositiveFinite('graceMs', this.config.graceMs)
     ctx.effect(() => async () => {
-      // Kill every live process group and WAIT for the processes to close so
-      // nothing outlives the fiber (HMR safety) — a TERM-trapping child is
-      // held until the SIGKILL escalation lands.
+      // Await closure so even a TERM-trapping child cannot outlive the fiber.
       const pending: Promise<void>[] = []
       for (const [proc, running] of this.live) {
         proc.status = 'killed'
@@ -116,20 +97,16 @@ export class LocalBashExecutor extends BashExecutor {
       workdir: request.workdir ?? this.config.cwd ?? process.cwd(),
       timeoutMs,
       ...request.signal ? { signal: request.signal } : {},
-      // Carry stdin/env through verbatim — optional, no config default (absent
-      // means none). env merges AFTER the scrub in run.ts.
+      // Explicit environment values are merged after credential scrubbing in run.ts.
       ...request.stdin !== undefined ? { stdin: request.stdin } : {},
       ...request.env !== undefined ? { env: request.env } : {},
-      // A local executor carries the override as an explicit inert fact; a
-      // sandboxing subclass resolves it to its configured fallback.
+      // Local execution carries this override for sandboxing subclasses.
       sandboxMode: request.sandboxMode,
     }
   }
 
   async run(spec: BashExecSpec): Promise<BashRunResult> {
-    // One fused deadline drives both the timeout and upstream cancellation;
-    // runBash listens on d.signal and runs the SIGTERM→grace→SIGKILL kill.
-    // `using` clears the timer across the awaited process lifetime.
+    // One deadline combines timeout and upstream cancellation; disposal clears its timer.
     using d = deadline(spec.signal, spec.timeoutMs, 'BASH_TIMEOUT')
     const outcome = await runBash({
       command: spec.command,
@@ -140,21 +117,14 @@ export class LocalBashExecutor extends BashExecutor {
       stdin: spec.stdin,
       env: spec.env,
     }, this.internals).done
-    // Classify the FIRST abort reason: a BASH_TIMEOUT TimeoutReason means our timeout cut the
-    // command short; any other abort — an upstream cancel, or a foreign (outer) deadline's
-    // timeout under nesting — is aborted.
+    // Only this executor's timeout reason counts as timedOut; outer deadlines count as aborts.
     const timedOut = timeoutOf(d.signal, 'BASH_TIMEOUT') !== undefined
     const aborted = d.signal.aborted && !timedOut
     return { ...outcome, timedOut, aborted, timeoutMs: spec.timeoutMs }
   }
 
   start(spec: BashExecSpec): BashProcess {
-    // No timeout for background processes (matches Claude Code, which
-    // detaches the timeout when backgrounding); callers stop them via the
-    // handle's kill() — or via spec.signal, which the seam contract honors
-    // for background runs too (runBash wires it to the group kill). No
-    // deadline is created here, so spec.timeoutMs is ignored by design —
-    // background processes stay timeout-free (see the timeout-library RFC).
+    // Background runs ignore timeoutMs; callers stop them through kill() or spec.signal.
     const running = runBash({
       command: spec.command,
       cwd: spec.workdir,
@@ -172,9 +142,7 @@ export class LocalBashExecutor extends BashExecutor {
       exitCode: null,
       signal: null,
       done: running.done.then((outcome) => {
-        // Caller-aborted and signal-terminated processes report as killed, not
-        // completed. The signal check also covers commands that terminate
-        // themselves without aborting the upstream signal.
+        // Any signal termination is killed, including a command signaling itself.
         if (proc.status === 'running') {
           proc.status = spec.signal?.aborted === true || outcome.signal !== null ? 'killed' : 'completed'
         }
@@ -183,9 +151,7 @@ export class LocalBashExecutor extends BashExecutor {
         this.onProcessDone(proc, running.stderr.readFrom(0).text)
         this.live.delete(proc)
       }, (error: unknown) => {
-        // Spawn-level failure (bad workdir, …): the process never ran. The
-        // error is surfaced through the read path, not a rejection. String()
-        // suffices — runBash only rejects with Error instances.
+        // Background spawn failures settle as killed and surface through the read path.
         proc.status = 'killed'
         running.stderr.push(Buffer.from(`spawn failed: ${String(error)}`))
         this.onProcessDone(proc, running.stderr.readFrom(0).text)

packages/bash/bash-sandbox/src/index.ts

@@ -20,7 +20,7 @@ import type { Config as LocalConfig } from '@deepseek-ai/dsh-bash-local'
  * Plugin config: the local executor's knobs plus the sandbox policy. All
  * optional — `static Config` supplies the defaults (`mode: 'read-only'` is the
  * fail-safe default; an example that wants a workspace-writable agent opts in
- * explicitly). The runner choice is NOT configured here: which platform
+ * explicitly). The runner choice is not configured here: which platform
  * backend confines the command is the `ctx.sandbox` provider's config.
  */
 export interface Config extends LocalConfig {
@@ -70,10 +70,8 @@ export function classifyRunnerFailure(result: BashRunResult, signatures: readonl
 }
 
 /**
- * The classifier core shared by foreground results and settled background
- * tasks: failed AND signature present. Lowercases BOTH sides — the seam
- * declares its signatures case-insensitive, and producers compose them from
- * runtime data of any case (an `argv0` path, `No such file or directory`).
+ * Shared classifier for failed runs. Signatures are case-insensitive and may
+ * include runtime values such as an executable path.
  */
 function matchesSignature(exitCode: number | null, stderr: string, signatures: readonly string[]): boolean {
   if (exitCode === null || exitCode === 0) return false
@@ -104,15 +102,10 @@ export class SandboxBashExecutor extends LocalBashExecutor {
   private readonly mode: SandboxMode
   private readonly workspaceRoot: string
   /**
-   * Per-process facts, keyed by handle from `start()` until the settle stamp
-   * consumes them: the mode the process runs under (per-call — an escalated process
-   * differs from its neighbors) plus its wrap facts. The seam returns facts
-   * PER WRAP — a provider may legally vary enforcement or dialect between
-   * calls — so overlapping background processes must each classify against their
-   * OWN wrap; a single latest-wrap field would let a later `start()` clobber
-   * an earlier process's facts before it settles. A `danger-full-access` process
-   * has NO entry (nothing confined it), which is what the settle stamp keys
-   * off.
+   * Per-process confinement facts retained until settlement. Providers may
+   * vary enforcement and diagnostic dialect between overlapping calls, so a
+   * shared latest-wrap value would classify a process against the wrong facts.
+   * Unconfined processes have no entry.
    */
   private readonly processFacts = new Map<BashProcess, {
     mode: ConfinedSandboxMode
@@ -123,10 +116,7 @@ export class SandboxBashExecutor extends LocalBashExecutor {
 
   constructor(ctx: Context, config: Config) {
     super(ctx, config)
-    // schemastery (static Config) already filled the defaulted fields — the
-    // cast records that runtime fact (mirrors LocalBashExecutor's config
-    // cast). `workspaceRoot` and `cwd` have NO schema default, so their
-    // fallback chain is real branching.
+    // Schemastery fills mode before construction; workspaceRoot and cwd retain runtime fallbacks.
     this.mode = config.mode as SandboxMode
     this.workspaceRoot = resolve(config.workspaceRoot ?? config.cwd ?? process.cwd())
   }
@@ -168,11 +158,7 @@ export class SandboxBashExecutor extends LocalBashExecutor {
     // Same stamped-by-resolve invariant as run().
     const mode = spec.sandboxMode as SandboxMode
     if (mode === 'danger-full-access') return super.start(spec)
-    // Sandbox facts are stamped at settle time by onProcessDone()
-    // (denial classification runs against the settled task's collected
-    // stderr). The map entry lands synchronously after spawn, strictly
-    // before the earliest possible settle (including a spawn rejection, whose
-    // promise reaction cannot run until this synchronous start call returns).
+    // Install facts synchronously; promise settlement cannot run before start() returns.
     const confined = this.confine(spec.command, mode)
     const proc = super.start({ ...spec, command: confined.command })
     const { enforcement, denialSignatures, runnerFailureSignatures } = confined
@@ -188,10 +174,7 @@ export class SandboxBashExecutor extends LocalBashExecutor {
     const facts = this.processFacts.get(proc)
     if (facts !== undefined) {
       this.processFacts.delete(proc)
-      // Runner failure outranks denial (the command never ran; the runner's
-      // own error text can contain denial words). A settled task has no
-      // error channel left, so the fact IS the surface here — the foreground
-      // path throws instead.
+      // Runner failure outranks denial because its diagnostics may contain denial terms.
       const runnerFailed = matchesSignature(proc.exitCode, stderr, facts.runnerFailureSignatures)
       proc.sandbox = {
         mode: facts.mode,

packages/bash/bash/src/index.ts

@@ -1,23 +1,7 @@
 /**
- * The bash executor seam (`ctx.bash`): an abstract service defining WHAT a
- * bash backend does — run foreground commands, start background processes —
- * without saying HOW. Implementations subclass {@link BashExecutor} and
- * register themselves as the `bash` service; `@deepseek-ai/dsh-bash-local`
- * (local subprocesses) is the first. Future implementations swap in
- * sandboxes, containers, or remote exec servers without touching the tool
- * schemas that consume them (`@deepseek-ai/dsh-tool-bash`).
- *
- * The split mirrors the LLM seam (`LlmService`/`LlmAdapter`) and the
- * surveyed agents: pi hides execution behind a `BashOperations` interface
- * (local shell / SSH / VM backends), Codex behind an exec-server protocol.
- *
- * The seam is deliberately TASK-FREE: `start()` hands back a
- * {@link BashProcess} handle (incremental reads, kill, a quiescence promise)
- * and nothing else. Task ids, owner isolation, polling tools, and completion
- * notices are the generic `ctx.tasks` runtime's job (`@deepseek-ai/dsh-tasks`)
- * — the tool layer adapts the handle into a task registration. This keeps a
- * remote/sandbox executor free of any session or registry dependency.
- *
+ * The `ctx.bash` executor seam for foreground commands and background process
+ * handles. Task ids, ownership, polling, and notices belong to
+ * `@deepseek-ai/dsh-tasks`, keeping executors independent of sessions.
  * @module @deepseek-ai/dsh-bash
  */
 
@@ -49,21 +33,15 @@ declare module 'cordis' {
  * implementation per context; loading a second throws, which is cordis'
  * standard duplicate-service behavior).
  *
- * Semantics every implementation must honor:
- * - {@link run} REJECTS only for infrastructure failures (unusable workdir,
- *   missing shell, pre-aborted signal). Nonzero exits, timeout kills, and
- *   abort kills RESOLVE with a descriptive {@link BashRunResult} — reporting
- *   a failed command is the tool layer's job, not an exception.
+ * Implementations must honor these semantics:
+ * - {@link run} rejects only for infrastructure failures. Nonzero exits,
+ *   timeout kills, and abort kills resolve with a {@link BashRunResult}.
  * - {@link start} returns immediately; no timeout applies to background
- *   processes (callers stop them via {@link BashProcess.kill} or the spec's
- *   AbortSignal). The handle's `done` settles at process close and never
- *   rejects (a spawn failure settles as `killed` with the error readable on
- *   stderr).
+ *   processes. `done` settles at process close and never rejects; spawn
+ *   failures settle as `killed` with the error on stderr.
  * - {@link BashProcess.readOutput} is incremental: consecutive reads never
- *   re-deliver output. Implementations bound their buffers; reads that lost
- *   data flag `lossy` and point at full-stream spill files when available.
- * - Disposal kills every running background process and awaits their exit
- *   (no orphan processes survive `fiber.dispose()`).
+ *   repeat output. Lossy reads report truncation and available spill files.
+ * - Disposal kills all running background processes and awaits their exit.
  */
 export abstract class BashExecutor extends Service {
   constructor(ctx: Context) {

packages/bash/bash/src/types.ts

@@ -1,14 +1,6 @@
 /**
- * Execution vocabulary for the bash executor seam. Types only — the abstract
- * service lives in `./index.ts`, implementations in sibling packages
- * (`@deepseek-ai/dsh-bash-local` first).
- *
- * Background TASK semantics (ids, ownership, polling protocol, completion
- * listeners) deliberately do NOT live here: the seam starts a background
- * PROCESS and returns a {@link BashProcess} handle; the caller (the tool
- * layer) registers that handle with the generic `ctx.tasks` runtime
- * (`@deepseek-ai/dsh-tasks`), which owns everything task-shaped.
- *
+ * Execution types for the bash executor seam. Background task semantics belong
+ * to `@deepseek-ai/dsh-tasks`; this seam exposes only process handles.
  * @module dsh-bash/types
  */
 
@@ -67,12 +59,9 @@ export interface BashExecRequest {
 }
 
 /**
- * A fully-resolved execution SPEC — exactly what {@link BashExecutor.run} /
- * {@link BashExecutor.start} act on. `workdir` and `timeoutMs` are REQUIRED:
- * defaulting and capping already happened in {@link BashExecutor.resolve}, so
- * the executor never hides a `?? config` fallback (explicit > implicit). For
- * background processes, `start()` ignores `timeoutMs` (background runs have no
- * timeout) — the field is still required because the type is shared.
+ * A resolved execution spec. {@link BashExecutor.resolve} fills and caps the
+ * required fields; {@link BashExecutor.start} ignores `timeoutMs` because
+ * background processes have no executor timeout.
  */
 export interface BashExecSpec {
   command: string
@@ -80,20 +69,11 @@ export interface BashExecSpec {
   timeoutMs: number
   /** Abort signal — implementations kill the command when it fires. */
   signal?: AbortSignal | undefined
-  /**
-   * Bytes to write to the command's stdin (then close it), carried through
-   * verbatim from {@link BashExecRequest.stdin}. OPTIONAL on the resolved spec:
-   * it has no config default, so a missing one means "no stdin" — the safe,
-   * ordinary case — not a silent footgun, so it stays a plain optional rather
-   * than required-but-nullable (see the request field).
-   */
+  /** Bytes to write to stdin before closing it; absent means no stdin. */
   stdin?: string | undefined
   /**
-   * Extra environment entries, carried through verbatim from
-   * {@link BashExecRequest.env} and merged by the implementation AFTER its
-   * credential scrub (an explicit entry wins even when its name matches the
-   * scrub pattern). OPTIONAL on the spec for the same reason as `stdin` — no
-   * config default, absent means "no extra env".
+   * Extra environment entries, merged after credential scrubbing so explicit
+   * values win; absent means no extra entries.
    */
   env?: Record<string, string> | undefined
   /** Resolved sandbox mode; ignored by executors that do not confine. */
@@ -144,12 +124,9 @@ export interface BashProcessRead {
 }
 
 /**
- * A live background process handle, returned by {@link BashExecutor.start}.
- * The HANDLE is the only access path (no executor-level id lookup): the
- * caller holds it, adapts it into a `ctx.tasks` registration, or drops it.
- * Reads stay valid after the process exits (the remaining buffered output is
- * still consumable); the executor's own disposal kills every running process
- * and awaits {@link done}.
+ * A background process handle returned by {@link BashExecutor.start}. It is the
+ * only access path; buffered output remains readable after exit. Executor
+ * disposal kills running processes and awaits {@link done}.
  */
 export interface BashProcess {
   /** Process lifecycle state (settled exactly once). */

packages/bash/tool-bash/src/index.ts

@@ -1,28 +1,10 @@
 /**
- * The model-facing `bash` tool. Pure schema + text shaping — every process
- * concern lives behind the `ctx.bash` executor seam (`@deepseek-ai/dsh-bash`),
- * so sandbox/permission/remote executor implementations swap in without
- * touching what the model sees.
- *
- * Background runs are TASKS, not bash-private state: `run_in_background`
- * starts a process through the seam and registers its handle with the generic
- * `ctx.tasks` runtime (`@deepseek-ai/dsh-tasks`), which owns the id, the
- * owner fence, the completion notice, and the model-facing collect/stop
- * tools (`task_output`/`task_list`/`task_kill` from
- * `@deepseek-ai/dsh-tool-tasks`). Whether the parameter is exposed at all is
- * THIS plugin's `enableRunInBackground` config (default on) — the registry
- * never rewrites a producer's schema.
- *
- * The tool-call abort signal is deliberately NOT wired to a background
- * process: after the task id is returned the parent step may end while the
- * work continues; cancellation belongs to `task_kill` and the owner-disposal
- * cleanup. A signal already aborted before the call refuses to start.
- *
- * TODO(permissions): commands run with the executor's full authority. The
- * permission/sandbox seam is the `tools/pre-execute` waterfall (deny/ask) plus
- * sandboxing `BashExecutor` implementations — see docs/architecture.md
- * § Extending The Harness.
+ * Model-facing `bash` tool over the `ctx.bash` executor seam. Background calls
+ * register process handles with `ctx.tasks`; their work uses task cancellation
+ * rather than the tool-call signal after an id is returned.
  *
+ * TODO(permissions): deployment policy belongs in `tools/pre-execute` and
+ * sandboxing executors; see docs/architecture.md § Extending The Harness.
  * @module @deepseek-ai/dsh-tool-bash
  */
 
@@ -44,14 +26,9 @@ import { parseExitStatus, renderProcessRead, renderResult } from './render.ts'
 export const name = 'tool-bash'
 export const inject = ['tools', 'bash', 'systemPrompt']
 
-/** Config: whether the model may background commands (the producer-opt-in flag). */
+/** Configures whether the model may background commands. */
 export interface Config {
-  /**
-   * Expose `run_in_background` in the bash schema (default true). Disabled,
-   * the parameter is absent entirely — schema and capability never disagree.
-   * Backgrounding also needs the `ctx.tasks` runtime at call time; a missing
-   * one fails the call loud with the load-these-packages message.
-   */
+  /** Expose `run_in_background` (default true); disabled calls are also rejected. */
   enableRunInBackground?: boolean
 }
 
@@ -59,14 +36,7 @@ export const Config: z<Config> = z.object({
   enableRunInBackground: z.boolean().default(true),
 })
 
-/**
- * Validate the constraints the SchemaSpec can't express. `defineTool` now
- * validates parsed args against the SchemaSpec before `execute` runs (the
- * arg-validation RFC), so type/required/enum checks are already done and `args`
- * is the validated `InferArgs` shape here. What remains are value constraints
- * the DSL has no vocabulary for: non-empty strings and a positive, finite
- * timeout.
- */
+/** Parsed tool args; execute validates value constraints absent from SchemaSpec. */
 interface BashToolArgs {
   command: string
   description: string
@@ -129,39 +99,14 @@ function bashDescription(backgroundEnabled: boolean, escalationModes: readonly S
     + 'it — but it does not forbid attempting or escalating other commands later.'
 }
 
-// ---------------------------------------------------------------------------
-// UI presentation (tool-owned). These shape how a UI (e.g. the ACP bridge)
-// renders a bash call's pending and completed states. They are display-only and
-// pure — a UI may call them during live streaming AND a session-log replay.
-// ---------------------------------------------------------------------------
-
 /**
- * Pending-state presentation for a `bash` call. The TITLE is the exact `command`
- * — a `kind: 'execute'` card is rendered as a terminal whose header label IS the
- * title, and an execute-kind card HIDES `rawInput` (Zed: `should_show_raw_input
- * = !is_terminal_tool`), so the command must BE the title to be seen. This
- * mirrors the reference ACP adapters (claude-agent-acp, codex-acp), which both
- * use the bare command as an execute tool's title. The model-written
- * `description` (a readable summary) rides as a `content` text block shown ABOVE
- * the card. (Note: claude-agent-acp DROPS the description in terminal mode and
- * shows only the card; surfacing it as a content block is a deliberate
- * divergence here — we keep the human summary visible alongside the card.)
- * `rawInput` still carries the bare command for non-execute UIs that DO render it.
- *
- * `terminal` marks the call so a capable UI renders a TERMINAL card — but ONLY a
- * FOREGROUND run is a terminal: a `run_in_background` call returns a task id
- * immediately (it never streams a terminal; its output is polled via
- * `task_output`), so it is NOT marked terminal and renders as an ordinary
- * execute card. For a foreground run the `terminal.cwd` (header) is the model
- * `workdir` when given — ABSOLUTE as-is, RELATIVE for the UI bridge to resolve
- * against the session cwd; when omitted the bridge fills the session workspace
- * cwd (this PURE presenter, args only, can't see it).
+ * Present foreground calls as terminals and background starts as generic cards.
+ * The command remains the title on both paths; foreground cwd is passed through
+ * for the bridge to resolve, while background descriptions remain card content.
  */
 type BashCallArgs = { command: string; description: string; workdir?: string; run_in_background?: boolean }
 
 function presentBashCall(args: BashCallArgs): GenericCallView | TerminalCallView {
-  // A background start is not an interactive terminal — a generic execute card
-  // with the command as rawInput and the description as a content block.
   if (args.run_in_background === true) {
     return {
       card: 'generic',
@@ -171,7 +116,6 @@ function presentBashCall(args: BashCallArgs): GenericCallView | TerminalCallView
       content: [{ type: 'text', text: args.description }],
     }
   }
-  // A foreground run is a terminal; an explicit workdir supplies its cwd.
   return {
     card: 'terminal',
     title: args.command,
@@ -189,13 +133,10 @@ function presentBashResult(args: unknown, result: ToolResult): ToolResultView |
   if (block === undefined || block.type !== 'text') return undefined
   const raw = block.text
   const isBackground = typeof args === 'object' && args !== null && (args as { run_in_background?: unknown }).run_in_background === true
-  // A background ack or an errored run is not a real terminal exit: render the
-  // fenced ```console fallback as generic content (no exit pill).
+  // Background acknowledgements and errors have no terminal exit status.
   if (isBackground || result.isError) {
     return { card: 'generic', content: [{ type: 'text', text: `\`\`\`console\n${raw.replace(/\n+$/, '')}\n\`\`\`` }] }
   }
-  // A finished foreground run supplies raw output and parsed exit status.
-  // The bridge derives the no-capability fenced fallback from `output`.
   return { card: 'terminal', output: raw, ...parseExitStatus(raw) }
 }
 
@@ -251,9 +192,7 @@ export function apply(ctx: Context, config: Config): void {
     }
   }
 
-  // The bash tool's cross-call HABIT, which the per-tool description cannot
-  // carry (it describes one call): the exit-code marker is only useful
-  // if the model actually checks it every time.
+  // Cross-call guidance belongs in the prompt rather than one-call schema prose.
   ctx.systemPrompt.section({
     name: 'tool:bash',
     order: 105,
@@ -291,12 +230,7 @@ export function apply(ctx: Context, config: Config): void {
     },
     async execute(args: BashToolArgs, exec) {
       validateBashArgs(args)
-      // `description` is display/logging metadata only (surfaced to UIs via
-      // the tool/call session event); it is intentionally NOT forwarded to
-      // ctx.bash and has no effect on execution.
-      // Default the workdir to the calling agent's session cwd so each ACP
-      // session runs in its own workspace (see resolveWorkdir); an explicit
-      // model workdir still wins.
+      // Description is display metadata; workdir defaults to the caller's session.
       const sandboxMode = args.sandbox_permissions !== undefined && args.justification !== undefined
         ? await approveEscalation(args.sandbox_permissions, args.justification, exec)
         : sessionOverride(exec)
@@ -308,27 +242,17 @@ export function apply(ctx: Context, config: Config): void {
         ...sandboxMode !== undefined ? { sandboxMode } : {},
       }
       if (args.run_in_background === true) {
-        // The schema omission is advertising, not enforcement — the arg
-        // validator deliberately allows undeclared keys, so a caller (or a
-        // model that has seen the parameter elsewhere) can still send it.
-        // A disabled deployment must refuse at execution time, loud.
+        // Undeclared keys are allowed, so schema omission also needs enforcement.
         if (!backgroundEnabled) {
           throw new Error('run_in_background is disabled for this deployment (enableRunInBackground: false)')
         }
-        // The generic runtime owns everything task-shaped; without it a task
-        // id would be uncollectable — fail loud with the fix, not a dangle.
         const tasks = ctx.get('tasks')
         if (tasks === undefined) {
           throw new Error('background tasks unavailable: load @deepseek-ai/dsh-tasks and @deepseek-ai/dsh-tool-tasks')
         }
-        // A step already cancelled must not spawn; after the id is returned
-        // the tool-call signal is deliberately NOT wired to the process
-        // (cancellation belongs to task_kill / owner cleanup), so the check
-        // happens here, once, instead of passing the signal to start().
+        // Reject pre-start cancellation; returned tasks use their own lifecycle.
         if (exec.signal?.aborted) throw new Error('command aborted')
-        // tasks.start preflights (surface fence, owner cleanup) BEFORE run()
-        // spawns anything, and cannot fail after — the process can never
-        // start without a collectable id.
+        // Task preflight finishes before the starter can spawn a process.
         const id = tasks.start({
           kind: 'bash',
           label: args.command,

packages/bash/tool-bash/src/render.ts

@@ -15,7 +15,7 @@ function streamText(output: CollectedOutput): string {
 
 /**
  * Shape one finished run into the text the model sees: stdout, then a marked
- * stderr section, then exit-status markers. Non-zero exits are REPORTED, not
+ * stderr section, then exit-status markers. Non-zero exits are reported, not
  * errored — the model decides how to react; only infrastructure failures
  * (spawn errors, aborts) surface as isError results.
  * @param result - the completed foreground run from the executor.
@@ -40,23 +40,15 @@ export function renderResult(
   if (body.length === 0) body = '(no output)'
 
   const markers: string[] = []
-  // The sandbox marker precedes the exit-status markers so `[exit code: N]`
-  // stays the LAST line (exitStatus() anchors its parse there). Denial is a
-  // reported fact like timeout: the model decides how to react.
+  // Keep the exit marker last because parseExitStatus anchors there.
   if (result.sandbox?.denied) {
     markers.push(`[sandbox: file access denied under ${result.sandbox.mode} mode]`)
-    // The same-turn nudge lives at the decision point: only when this
-    // composition advertises the fields (a lever is never hinted that the
-    // schema does not offer), and inside the sandbox marker family so the
-    // exit-code marker stays the last line.
+    // Hint only when the composition exposes escalation, before the final exit marker.
     if (escalationModes.length > 0) {
       markers.push('[sandbox: escalation available — retry this exact command once with sandbox_permissions (the narrowest wider mode that suffices) + justification; the approval prompt asks the user]')
     }
   }
-  // Timeout is reported independently of how the process actually ended: a
-  // command can trap SIGTERM and exit 0 after our timer fired (e.g.
-  // `trap "exit 0" TERM; sleep 60`), giving timedOut:true / exitCode:0 /
-  // signal:null — the model must still see that the command was cut short.
+  // A command may trap SIGTERM and exit 0 after timeout; still report interruption.
   if (result.timedOut) markers.push(`[timed out after ${result.timeoutMs}ms]`)
   if (result.signal !== null) {
     markers.push(`[killed by signal: ${result.signal}]`)

packages/bash/tool-bash/tests/tools.spec.ts

@@ -419,8 +419,7 @@ describe('background execution through the task runtime', () => {
   })
 
   it('a background task started by an agent is registered with that agent as owner', async () => {
-    // The fence SEMANTICS are pinned in dsh-tasks; this only pins that
-    // tool-bash forwards exec.agent as the registration's owner.
+    // The producer must forward exec.agent as the task owner.
     const ctx = await setupWithTasks()
     const agent = registerFakeAgent(ctx, 'sess-owner')
     const started = await call(ctx, 'bash', { command: 'sleep 60', description: 'test command', run_in_background: true }, agent)
@@ -466,9 +465,7 @@ describe('background execution through the task runtime', () => {
   })
 
   it('never spawns the process when tasks.start preflight throws (no orphan, by construction)', async () => {
-    // TaskService WITHOUT any control surface: tasks.start preflights that
-    // fence BEFORE invoking the producer's run(), so the executor is never
-    // asked to spawn — there is no orphan to roll back.
+    // With no control surface, task preflight fails before the executor can spawn.
     const ctx = new Context()
     await ctx.plugin(SystemPrompt)
     await ctx.plugin(ToolRegistry)
@@ -500,9 +497,7 @@ describe('background execution through the task runtime', () => {
     const parameters = ctx.tools.get('bash')!.parameters as { properties: Record<string, unknown> }
     expect('run_in_background' in parameters.properties).toBe(false)
 
-    // Schema omission is advertising, not enforcement: the arg validator
-    // allows undeclared keys, so a forced run_in_background must be REFUSED
-    // at execution time (review finding) — while foreground still works.
+    // Schema omission is advertising; execution must also enforce the opt-out.
     const forced = await call(ctx, 'bash', { command: 'echo hi', description: 'test command', run_in_background: true })
     expect(forced.isError).toBe(true)
     expect(text(forced)).toContain('run_in_background is disabled for this deployment')

packages/subagent/tool-subagent/README.md

@@ -1,63 +1,51 @@
 # @deepseek-ai/dsh-tool-subagent
 
-The `subagent` tool lets the model delegate one self-contained task and collect the child's final output. It is a thin consumer of `ctx.subagents`; changing the configured provider changes the transport without changing the model-facing execution contract.
+The model-facing delegation tool over one configured `ctx.subagents` provider. Changing the provider changes transport without changing the execution contract.
 
-## Provider selection
+## Provider selection and lifecycle
 
-This plugin binds to **exactly one** provider (`Config.provider`). The model sees only `{ description, prompt, run_in_background? }` — there is no provider/type parameter in the schema. To expose more than one transport, load the plugin more than once, each bound to a different provider **and a distinct `toolName`** (the tool registry rejects a duplicate name, so a second load that kept the default `subagent` name would throw). Keeping selection in config (not the schema) is the deliberate split: the *service* holds a multi-provider registry; the *tool* picks one.
+Each plugin instance binds one `provider` to one `toolName`; the model receives no provider selector. Load another distinctly named instance to expose another transport. The tool registers only while its provider exists, avoiding sibling load-order and provider-reload dependencies. Its description follows `provider.inheritsParentContext`: fresh children require standalone prompts, while forked children already see completed parent turns.
 
-The description is derived from `provider.inheritsParentContext`: spawn and ACP tell the model to provide a standalone prompt, while fork says the child already sees completed conversation turns. The plugin follows `subagent/provider-added` and `subagent/provider-removed`, so concurrent Cordis plugin loading does not create a registration-order dependency.
+A foreground call passes the execution signal through startup and execution, awaits `run.result`, and always awaits `run.dispose()` before returning. Only `completed` returns final text; abort, refusal, token limit, and other failures become errored tool results without partial output.
 
-## Lifecycle
+With `run_in_background: true`, the tool registers the parent-owned task before starting the provider. A task-owned signal covers pending startup and the child after the starting call returns. `task_kill` and owner disposal abort it. Settlement awaits startup rollback or child disposal, then maps completed final text, abort to `killed`, and other failures to `failed`. The task has no incremental read; generic task tools own later status, collection, cancellation, and notices. See the [background subagent RFC](../../../docs/rfc/implemented/feature/2026-07-08-background-subagent-tasks.md).
 
-Foreground `execute` passes the tool execution's abort signal when present, otherwise supplies an inert signal to satisfy the required `SubagentStartRequest.signal`. It awaits `ctx.subagents.start(...)`, then awaits `run.result` inside a `try/finally` that always calls `run.dispose()`. The selected signal therefore covers startup and live execution, while disposal guarantees quiescence on success, failure, and abort.
-
-A non-`completed` stop reason becomes an `isError` tool result; partial child output is never reported as success. With `run_in_background`, an independent task-owned signal covers both asynchronous startup and the ready child, while collection moves to the generic task tools.
+`toolFilter` changes the child's global tool layer but is not a parent-derived authority ceiling. See the [agent-scope security non-goal](../../../docs/rfc/implemented/architecture/2026-07-08-agent-scope-contexts.md#security-and-authority-are-non-goals).
 
 ## Config
 
 | Key | Meaning |
 |---|---|
-| `provider` (required) | The `ctx.subagents` provider name to start runs on (`spawn`, `fork`, `acp`, …). |
-| `toolName` | The model-facing tool name to register (default `subagent`). Set a distinct value per load when exposing multiple providers, e.g. `subagent` + `subagent_acp`. |
-| `enableRunInBackground` | Expose `run_in_background` in this instance's schema (default `true`). Disabled, the parameter is absent entirely AND a caller that forces the key anyway is refused at execution time (the arg validator allows undeclared keys) — delegation through this instance stays strictly synchronous. |
-| `agentOptions` | Default child agent options, currently including `model`. |
+| `provider` (required) | Provider name (`spawn`, `fork`, `acp`, ...). |
+| `toolName` | Model-facing name, default `subagent`; distinct for every loaded instance. |
+| `enableRunInBackground` | Exposes background mode, default `true`; disabling also rejects forced background calls. |
+| `agentOptions` | Default child options, currently including `model`. |
 | `persona` | Per-child persona; requires provider `persona` capability. |
-| `toolFilter` | Per-child global-tool restriction; requires provider `toolFilter` capability. |
-| `maxDepth` | Absolute delegation-depth cap; requires provider `depthLimit` capability. |
-
-## Foreground lifecycle (synchronous collect)
-
-`execute` awaits a ready run from the configured provider and then **awaits `run.result` inside a `try/finally` that always `dispose()`s the run** — the owned child agent/session is torn down on every path (success, error, abort), never leaked. The required request signal is the canonical cancellation path across startup and live execution. A non-`completed` stop reason (aborted/error/max-tokens/refusal) maps to an `isError` tool result rather than returning partial output as success.
-
-## Background delegation (a generic task)
-
-`run_in_background: true` refuses an already-aborted `exec.signal`, synchronously registers `{ kind: 'subagent', label: description, owner: parent, cancel, done }` with `ctx.tasks`, and returns `started background subagent task <id>`. The starter immediately calls async `ctx.subagents.start()` with an independent `AbortController`; `task_kill` and owner-scope teardown abort that signal whether startup is still pending or the child is ready. The task is final-output-only, and `done` settles only after startup rollback or `run.dispose()` reaches quiescence. Mapping: `runOutcome` turns `completed` into final output, `aborted` into `killed`, and other terminal reasons into `failed`; `settleRun` contains infrastructure and disposal failures. A missing task runtime fails loud. See the [background subagent tasks RFC](../../../docs/rfc/implemented/feature/2026-07-08-background-subagent-tasks.md).
-
-`toolFilter` changes the child's visible global tool layer; it is not a parent-derived authority ceiling. See the [agent-scope security non-goal](../../../docs/rfc/implemented/architecture/2026-07-08-agent-scope-contexts.md#security-and-authority-are-non-goals).
+| `toolFilter` | Per-child global-tool restriction; requires `toolFilter` capability. |
+| `maxDepth` | Absolute delegation-depth cap; requires `depthLimit` capability. |
 
 ## Model Experience
 
-### Tool schemas
+### Tool schema
 
-**What the model sees**: While the configured provider exists, the model sees the generated default [`subagent` schema](../../../docs/tool-catalog.md#deepseek-aidsh-tool-subagent) under this instance's configured `toolName`. Fresh-context and inherited-context providers change the tool and `prompt` descriptions; `enableRunInBackground: true` adds `run_in_background` and its generic-task guidance.
+**What the model sees**: The generated default [`subagent` schema](../../../docs/tool-catalog.md#deepseek-aidsh-tool-subagent) under this instance's configured name while its provider exists. Provider context inheritance changes the tool and prompt descriptions; enabled background mode adds `run_in_background`.
 
-**Token effect**: Fixed schema cost per parent request while mounted; each additional provider instance contributes one independently named schema.
+**Token effect**: Fixed schema cost per parent request; each provider instance adds one schema.
 
 ### Foreground result
 
-**What the model sees**: The parent tool call retains the task description and prompt. Success contains only the child's data-dependent final text; non-completed stop reasons and infrastructure failures become `Error: <message>`. Intermediate child steps never enter the parent.
+**What the model sees**: The call retains the description and prompt. Success contains only the child's final text; other outcomes become `Error: <message>`. Intermediate child steps stay out of the parent.
 
-**Token effect**: The prompt and final result remain in parent history until compaction; child working context is paid only in the child.
+**Token effect**: The prompt and result remain in parent history until compaction; child working context remains in the child.
 
 ### Background task result
 
-**What the model sees**: Start returns exactly `started background subagent task <id>`. The generic task control surface owns later status, final output, cancellation responses, and completion notices; the child still contributes only its final text on successful collection.
+**What the model sees**: Start returns exactly `started background subagent task <id>`. The generic task surface provides later status, final output, cancellation responses, and notices.
 
-**Token effect**: The start acknowledgement is small and retained. Final output and generic task status enter parent history only when collected or injected by `dsh-tool-tasks`.
+**Token effect**: The acknowledgement is retained; final output enters parent history only when collected or injected.
 
 ## Known Limitations and Deferred Work
 
-- **Background runs expose final output only** — intermediate child steps remain in the child session and cannot be streamed through `task_output`.
-- **Duplicate `toolName` across waiting loads is detected late** (`TODO(subagent-dup-toolname)`) — two instances waiting on providers collide only when a provider arrives; config-time detection needs a cross-fiber registry of intended names.
-- **Child policy is fixed per tool registration** — model, persona, tool filter, and depth cap come from plugin config; another policy requires another distinctly named tool.
+- **Background runs expose final output only** — intermediate child steps stay in the child session.
+- **Duplicate names across waiting instances are detected late** (`TODO(subagent-dup-toolname)`) — preventing provider-registration rollback requires a registry of intended names.
+- **Child policy is fixed per instance** — another model, persona, tool filter, or depth cap requires another distinctly named tool.

packages/subagent/tool-subagent/src/index.ts

@@ -1,45 +1,9 @@
 /**
- * The model-facing `subagent` tool: delegate a task to a child agent and return
- * its final output. Pure schema + lifecycle shaping — every transport concern
- * lives behind the `ctx.subagents` provider registry
- * (`@deepseek-ai/dsh-subagent`), so an in-process, ACP, or future A2A backend
- * swaps in without touching what the model sees.
- *
- * Provider selection is config, not model-facing: this plugin is bound to
- * EXACTLY ONE provider name (`Config.provider`). To expose more than one
- * transport, load the plugin more than once, each bound to a different provider
- * — there is no provider/type parameter in the model-facing schema. The model
- * sees only `{ description, prompt }` (plus `run_in_background` when enabled).
- *
- * The tool DESCRIPTION is derived from the bound provider's conversation-history
- * descriptor ({@link providerWording}): a fresh-conversation provider (spawn,
- * ACP) gets the standalone-prompt wording, while a seeded-conversation provider
- * (fork) tells the model the child already sees the conversation's completed
- * turns. This descriptor says nothing about Cordis scope, services, tools, or
- * authority. The tool MIRRORS the
- * provider's lifecycle via `subagent/provider-added`/`-removed` — it registers
- * when the provider is (or becomes) available and unregisters when the
- * provider goes away — so no load-order requirement exists and an HMR reload
- * of the backend re-derives the wording from the fresh provider.
- *
- * FOREGROUND collection is synchronous: `execute` starts a run and awaits
- * `run.result` inside a `try/finally` that always disposes the run, so the
- * owned child agent/session is torn down on every path (success, error, abort)
- * and never leaks as a live idle child. A non-`completed` stop reason maps to an
- * `isError` tool result (by throwing) rather than returning partial output as
- * success.
- *
- * BACKGROUND delegation (`run_in_background: true`, exposed only when this
- * instance's `enableRunInBackground` config allows) is a generic background
- * TASK: the run is registered with `ctx.tasks` (kind `subagent`, final-output
- * only — the child session remains the detailed trace) and collected/stopped
- * through the generic `task_output`/`task_list`/`task_kill` tools. The
- * tool-call abort signal is deliberately NOT wired to a background child:
- * after the id is returned the parent step may end while the child works —
- * cancellation belongs to `task_kill` and the owner-disposal cleanup. The
- * task's `done` settles only after `run.dispose()` (child quiescence), which
- * is what makes owner-disposal cleanup an actual no-leak guarantee.
- *
+ * Model-facing delegation through one configured `ctx.subagents` provider.
+ * Provider lifecycle controls tool registration and context-sensitive schema
+ * wording. Foreground calls always dispose the run after collection; background
+ * calls use an independent cancellation signal and settle a final-output task
+ * only after child disposal.
  * @module @deepseek-ai/dsh-tool-subagent
  */
 
@@ -60,42 +24,29 @@ export interface Config {
   /** The `ctx.subagents` provider name to start runs on (e.g. `spawn`, `acp`). */
   provider: string
   /**
-   * The model-facing tool name to register (default `subagent`). To expose more
-   * than one transport, load this plugin once per provider — each load MUST set
-   * a distinct `toolName` (the tool registry rejects a duplicate name), e.g.
-   * `{ provider: 'spawn', toolName: 'subagent' }` and
-   * `{ provider: 'acp', toolName: 'subagent_acp' }`.
+   * Model-facing tool name (default `subagent`). Each loaded instance must use
+   * a distinct name.
    */
   toolName?: string
   /**
-   * Expose `run_in_background` in this instance's schema (default true).
-   * Disabled, the parameter is absent entirely — schema and capability never
-   * disagree; delegation through this instance stays strictly synchronous.
-   * Backgrounding also needs the `ctx.tasks` runtime at call time; a missing
-   * one fails the call loud with the load-these-packages message.
+   * Expose `run_in_background` (default true). Disabled instances omit the
+   * parameter and reject forced background calls.
    */
   enableRunInBackground?: boolean
   /**
-   * Default per-child agent options (model) applied to every spawned child.
-   * Omitted fields fall back to the child loop's own defaults.
+   * Agent options applied to every child; omitted fields use child-loop defaults.
    */
   agentOptions?: AgentOptions
   /**
-   * Per-child persona applied to every child this tool spawns: a scoped
-   * `deployment:persona` section shadowing the deployment's persona for the
-   * child alone. Requires the bound provider's `persona` capability
-   * (in-process backends support it; a request against one that doesn't is
-   * rejected at start). Omitted ⇒ the child renders the deployment persona.
+   * Per-child persona that shadows `deployment:persona`. Requires the
+   * provider's `persona` capability; omission preserves the deployment persona.
    */
   persona?: string
   /**
-   * Tool scoping applied to every child this tool spawns (see
-   * `SubagentStartRequest.toolFilter`): the named global tools vanish from
-   * the child's prompt AND refuse to execute. Requires the provider's
-   * `toolFilter` capability. Unknown names fail the spawn loudly. Note the
-   * child otherwise sees every global tool — including this delegation tool
-   * itself; `deny`-listing it (or setting `maxDepth`) is how a deployment
-   * bounds recursion.
+   * Tool filter applied to every child. Filtered tools disappear from its
+   * prompt and reject execution. Requires the provider's `toolFilter`
+   * capability; unknown names fail startup. Children otherwise see this tool,
+   * so deny it or set `maxDepth` to bound recursion.
    */
   toolFilter?: {
     /** Global tool names the child keeps; everything else is removed. */
@@ -104,12 +55,8 @@ export interface Config {
     deny?: string[]
   }
   /**
-   * Recursion cap applied to every child this tool spawns (see
-   * `SubagentStartRequest.maxDepth`): a spawn whose child would sit deeper
-   * than this in the delegation tree is rejected. Requires the provider's
-   * `depthLimit` capability. Must be a non-negative safe integer and is
-   * validated when the plugin loads. Omitted ⇒ unbounded (bound it in
-   * deployments that expose this tool to children).
+   * Maximum child depth. Requires the provider's `depthLimit` capability and a
+   * non-negative safe integer. Omission is unbounded.
    */
   maxDepth?: number
 }
@@ -118,16 +65,12 @@ export const Config: z<Config> = z.object({
   provider: z.string().required(),
   toolName: z.string().default('subagent'),
   enableRunInBackground: z.boolean().default(true),
-  // Omitted-object discipline (see the toolFilter note below): without the
-  // forced default an omitted `agentOptions` materializes `{}`, which reads as
-  // present — the request would carry `agentOptions: {}` and the presence
-  // check in execute() could never be false through config.
+  // Prevent Schemastery from materializing omitted agentOptions as `{}`.
   agentOptions: z.object({
     model: z.string(),
   }).default(undefined as unknown as { model: string }),
   persona: z.string(),
-  // Schemastery otherwise materializes omitted objects and nested arrays as `{ allow: [] }`, which
-  // silently means deny all. Preserve omission while retaining an explicit empty allow-list.
+  // Preserve omission; Schemastery's `{ allow: [] }` default would deny every tool.
   toolFilter: z.object({
     allow: z.array(z.string()).default(undefined as unknown as string[]),
     deny: z.array(z.string()).default(undefined as unknown as string[]),
@@ -137,9 +80,8 @@ export const Config: z<Config> = z.object({
 
 /**
  * Flatten a child's final output blocks to text for the tool result. The child
- * may return non-text blocks; this cut surfaces the text content (the common
- * case) and drops the rest, which is acceptable for a synchronous summary —
- * the structured path (`outputSchema`) is the channel for non-text results.
+ * may return non-text blocks; this path returns only text. Structured results
+ * use `outputSchema`.
  */
 function outputText(blocks: ContentBlock[]): string {
   return blocks
@@ -169,15 +111,10 @@ function stopReasonError(result: SubagentResult): string | undefined {
 }
 
 /**
- * Map a settled subagent result onto the generic task-outcome vocabulary:
- * `completed` carries the final text as the task's idempotent output;
- * `aborted` is the task-level `killed`; everything else — `error`,
- * `max-tokens`, `refusal`, and unknown merge-extensible reasons — is `failed`
- * with the reason as the status-line detail (partial output is NOT reported
- * as output, mirroring the synchronous path's report-the-reason rule).
- * Exported for tests.
- * @param result - the child's terminal result.
- * @returns the outcome for the `ctx.tasks` registration.
+ * Map a child result to the task outcome: completed carries final text,
+ * aborted is killed, and every other reason is failed without partial output.
+ * @param result - child terminal result.
+ * @returns outcome for the `ctx.tasks` registration.
  */
 export function runOutcome(result: SubagentResult): TaskOutcome {
   switch (result.stopReason) {
@@ -189,23 +126,17 @@ export function runOutcome(result: SubagentResult): TaskOutcome {
     case 'max-tokens':
     case 'refusal':
       return { status: 'failed', detail: result.stopReason }
-    // Merge-extensible union: an unknown terminal reason is a failure with
-    // the raw reason as detail, never partial output as success.
+    // Merge-extensible reasons remain failures with their raw detail.
     default:
       return { status: 'failed', detail: String(result.stopReason) }
   }
 }
 
 /**
- * Settle a background run at QUIESCENCE: await the child's result, ALWAYS
- * dispose the run (the owned child agent/session is released on every path),
- * and only then report the mapped outcome — so the task registry's `done`,
- * and therefore owner-disposal cleanup, cannot resolve before the child is
- * actually gone. A rejected `run.result` or `run.dispose()` reports `failed`
- * with the error as detail rather than rejecting the producer contract; when
- * both fail, both independent failures are preserved. Exported for tests.
- * @param run - the live background run to settle and release.
- * @returns the task outcome, after the run's resources are released.
+ * Await the child result, dispose the run, then return its task outcome. Result
+ * and disposal failures become `failed`; when both fail, both details survive.
+ * @param run - live run to settle and release.
+ * @returns outcome after child resources are released.
  */
 export async function settleRun(run: SubagentRun): Promise<TaskOutcome> {
   let outcome: TaskOutcome
@@ -239,7 +170,7 @@ export function providerWording(inheritsConversation: boolean): { description: s
   if (inheritsConversation) {
     return {
       description:
-        'Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all '
+        'Delegate a task to a subagent that inherits this conversation: a child agent seeded with all '
         + 'completed turns so far (it does not see the current in-flight turn), returning only its final '
         + 'result. Use this when the subtask builds on this conversation\'s context — a follow-up analysis, '
         + 'a review, a continuation — without consuming this conversation\'s context for the work itself. '
@@ -262,7 +193,6 @@ export function providerWording(inheritsConversation: boolean): { description: s
   }
 }
 
-/** Build the provider request shared by foreground and background execution. */
 function startRequest(config: Config, prompt: string, parent: Agent, signal: AbortSignal): SubagentStartRequest {
   return {
     prompt: [{ type: 'text', text: prompt }],
@@ -275,7 +205,7 @@ function startRequest(config: Config, prompt: string, parent: Agent, signal: Abo
   }
 }
 
-/** Settle a possibly-pending provider start through the task outcome contract. */
+/** Settle pending startup without rejecting the task producer contract. */
 async function settleStart(start: Promise<SubagentRun>, signal: AbortSignal): Promise<TaskOutcome> {
   try {
     return await settleRun(await start)
@@ -287,23 +217,14 @@ async function settleStart(start: Promise<SubagentRun>, signal: AbortSignal): Pr
 }
 
 export function apply(ctx: Context, config: Config): void {
-  // Keep misconfiguration at plugin load even when a caller invokes apply()
-  // directly and bypasses Schemastery's natural/max metadata.
+  // Direct apply() bypasses Schemastery's numeric constraints.
   assertSubagentMaxDepth(config.maxDepth)
-  // Misconfiguration fails loud AT LOAD (the check is self-contained): an
-  // explicit `toolFilter: {}` would otherwise pass the capability gate and
-  // kill every delegation later, in the child-setup `restrict({})` throw.
+  // Reject an empty explicit filter at load instead of failing every delegation.
   if (config.toolFilter !== undefined && config.toolFilter.allow === undefined && config.toolFilter.deny === undefined) {
     throw new Error('tool-subagent: `toolFilter` is configured but names neither `allow` nor `deny` — remove the key or fill the filter')
   }
-  // The tool MIRRORS its provider's lifecycle instead of assuming load order:
-  // the cordis Loader starts sibling entries concurrently, so "backend listed
-  // first in cordis.yml" does not guarantee "provider registered first", and
-  // an HMR reload of the backend replaces the provider while this fiber stays
-  // loaded. Register the tool when the bound provider is (or becomes)
-  // available — deriving the wording from THAT provider — and unregister it
-  // when the provider goes away, so the description can never outlive or
-  // predate the provider it describes.
+  // Mirror provider lifecycle because sibling load order and HMR replacement
+  // can change provider availability while this fiber remains active.
   let disposeTool: (() => void) | undefined
   const mount = (provider: SubagentProvider): void => {
     const wording = providerWording(provider.inheritsParentContext)
@@ -311,7 +232,7 @@ export function apply(ctx: Context, config: Config): void {
     disposeTool = ctx.tools.register(defineTool({
       name: config.toolName ?? 'subagent',
       description: wording.description + (backgroundEnabled
-        ? ' Set `run_in_background: true` to get a task id immediately and keep working; collect the final answer with `task_output` (wait: true when you are blocked on it) and stop it with `task_kill`.'
+        ? ' Set `run_in_background: true` to return a task id; collect with `task_output` and stop with `task_kill`.'
         : ''),
       parameters: {
         description: {
@@ -327,42 +248,31 @@ export function apply(ctx: Context, config: Config): void {
         ...backgroundEnabled ? {
           run_in_background: {
             type: 'boolean' as const,
-            description: 'Run the subagent as a background task and return a task id immediately (collect with task_output, stop with task_kill).',
+            description: 'Run as a background task and return its id; collect with task_output or stop with task_kill.',
           },
         } : {},
       },
       async execute(args, exec): Promise<ContentBlock[]> {
         const parent = exec.agent
         if (!parent) {
-          // The loop sets `exec.agent` for every model-driven call; its absence
-          // means a non-agent caller invoked the tool directly, which has no
-          // parent to attribute the child to. Fail loud rather than guess.
+          // Non-agent callers provide no parent for delegation ownership.
           throw new Error('subagent tool requires a calling agent (exec.agent was undefined)')
         }
 
         if (args.run_in_background === true) {
-          // The schema omission is advertising, not enforcement — the arg
-          // validator deliberately allows undeclared keys, so a caller (or a
-          // model that has seen the parameter elsewhere) can still send it.
-          // A disabled instance must refuse at execution time, loud.
+          // The validator permits undeclared keys, so schema omission also needs
+          // execution-time enforcement.
           if (!backgroundEnabled) {
             throw new Error('run_in_background is disabled for this tool instance (enableRunInBackground: false)')
           }
-          // The generic runtime owns everything task-shaped; without it a task
-          // id would be uncollectable — fail loud with the fix, not a dangle.
           const tasks = ctx.get('tasks')
           if (tasks === undefined) {
             throw new Error('background tasks unavailable: load @deepseek-ai/dsh-tasks and @deepseek-ai/dsh-tool-tasks')
           }
-          // A step already cancelled must not spawn a child. After the id is
-          // returned the tool-call signal is deliberately NOT wired to the run;
-          // an independent controller lets task_kill/owner disposal cancel both
-          // a pending async start and a ready child through the seam's one
-          // canonical cancellation channel.
+          // Reject cancellation before spawning; after return, the task-owned
+          // signal covers both pending startup and the ready child.
           if (exec.signal?.aborted) throw new Error('subagent delegation aborted')
-          // tasks.start preflights (surface fence, owner cleanup) BEFORE run()
-          // spawns the child, and cannot fail after — a child can never start
-          // without a collectable id.
+          // Task preflight finishes before the starter can spawn a child.
           const id = tasks.start({
             kind: 'subagent',
             label: args.description,
@@ -378,8 +288,7 @@ export function apply(ctx: Context, config: Config): void {
                   controller.abort(reason ?? 'background subagent task killed')
                 },
                 done: settleStart(start, controller.signal),
-                // No readOutput: a subagent task is final-output-only — the
-                // child session remains the detailed trace.
+                // No readOutput: the child session owns intermediate detail.
               }
             },
           })
@@ -399,29 +308,22 @@ export function apply(ctx: Context, config: Config): void {
           const result = await run.result
           const error = stopReasonError(result)
           if (error !== undefined) {
-            // Map a non-clean finish to an isError result (the registry turns a
-            // throw into an isError). Report the reason, not partial output.
+            // The registry converts this throw to isError; partial output is not success.
             throw new Error(error)
           }
           return [{ type: 'text', text: outputText(result.output) }]
         } finally {
-          // Always reach child quiescence — never leak a live idle child/session.
+          // Dispose before returning so no child session outlives the call.
           await run.dispose()
         }
       },
     }))
   }
 
-  // Listeners first, then the presence check: both run synchronously, so no
-  // registration can slip between them; the `disposeTool === undefined` guard
-  // makes a same-tick added-event after a successful mount a no-op.
+  // Register listeners before checking presence so no synchronous change is missed.
   // TODO(subagent-dup-toolname): two WAITING fibers configured with the same
-  // toolName collide only when their provider finally arrives — the duplicate
-  // tool-name throw then propagates through `subagent/provider-added` and
-  // rolls back the PROVIDER registration, so an invalid config blasts the
-  // backend's fiber instead of the misconfigured tool's. Config-time detection
-  // would need a cross-fiber registry of intended tool names; revisit if a
-  // real deployment ever hits it.
+  // toolName collide when their provider appears, and the duplicate-name throw
+  // rolls back the provider registration. Add an intent registry if this occurs.
   ctx.on('subagent/provider-added', (provider) => {
     if (provider.name === config.provider && disposeTool === undefined) mount(provider)
   })
@@ -434,9 +336,7 @@ export function apply(ctx: Context, config: Config): void {
   if (present !== undefined) {
     mount(present)
   } else {
-    // Not an error: the backend's fiber may activate after this one.
-    // The tool appears the moment the provider registers; a typo'd provider
-    // name shows up as this note plus a tool that never materializes.
+    // A backend fiber may activate later; a misspelled provider remains visible in this log.
     ctx.logger.info(`subagent provider "${config.provider}" not registered yet; the "${config.toolName ?? 'subagent'}" tool will register when it appears`)
   }
 }

packages/subagent/tool-subagent/tests/tool-subagent.spec.ts

@@ -81,7 +81,7 @@ describe('dsh-tool-subagent', () => {
     expect(schema!.description).not.toContain('task_output')
   })
 
-  it('refuses a forced run_in_background at execution time when the instance disables it (review finding)', async () => {
+  it('refuses a forced run_in_background at execution time when the instance disables it', async () => {
     // Schema omission is advertising, not enforcement: the arg validator
     // allows undeclared keys, so the opt-out must also hold in execute().
     const ctx = await setup({ provider: 'mock', enableRunInBackground: false })
@@ -253,7 +253,7 @@ describe('dsh-tool-subagent', () => {
     // Backend reloads with a DIFFERENT conversation-history descriptor: the wording is re-derived
     // from the fresh provider, not served stale from the first mount.
     await ctx.plugin(mock, { name: 'mock', inheritsParentContext: true })
-    expect(ctx.tools.schemas().find(s => s.name === 'subagent')!.description).toContain('INHERITS this conversation')
+    expect(ctx.tools.schemas().find(s => s.name === 'subagent')!.description).toContain('inherits this conversation')
   })
 
   it('the tool PLUGIN fiber owns its lifecycle listeners: disposal unmounts, and a disposed fiber never zombie-mounts', async () => {
@@ -303,10 +303,10 @@ describe('dsh-tool-subagent', () => {
     expect(props['prompt']!.description).toContain('include everything it needs')
   })
 
-  it('derives fork-shaped wording from a seeded-conversation provider (the description stops lying)', async () => {
+  it('derives inherited-context wording from a seeded-conversation provider', async () => {
     const ctx = await setup({ provider: 'mock', toolName: 'subagent' }, { inheritsParentContext: true })
     const schema = ctx.tools.schemas().find(s => s.name === 'subagent')!
-    expect(schema.description).toContain('INHERITS this conversation')
+    expect(schema.description).toContain('inherits this conversation')
     expect(schema.description).not.toContain('does not see this conversation')
     const props = (schema.parameters as { properties: Record<string, { description: string }> }).properties
     expect(props['prompt']!.description).toContain('completed turns')
@@ -711,8 +711,7 @@ describe('dsh-tool-subagent background mode', () => {
   })
 
   it('forwards task_kill reasons through the run signal (and defaults one when absent)', async () => {
-    // A provider whose runs settle only on signal abort — the mock settles on a
-    // microtask, too fast to observe a LIVE kill through the real tools.
+    // Use a provider that remains live until its signal is aborted.
     const ctx = await backgroundSetup({ provider: 'mock', agentOptions: { model: 'child-model' } })
     const parent = ownerAgent(ctx, 'sess-parent')
     const cancels: (string | undefined)[] = []
@@ -736,9 +735,7 @@ describe('dsh-tool-subagent background mode', () => {
         }
       },
     })
-    // Direct apply (schema bypass): schemastery would default agentOptions to
-    // an (truthy) empty object — the raw config exercises the omitted branch
-    // on the background start request.
+    // Direct apply preserves omitted agentOptions instead of applying schema defaults.
     tool.apply(ctx, { provider: 'hanging', toolName: 'subagent_hang' })
 
     const startOne = await ctx.tools.execute({ callId: CallId('h1'), name: 'subagent_hang', arguments: { description: 'one', prompt: 'p', run_in_background: true }, agent: parent })
@@ -810,9 +807,7 @@ describe('dsh-tool-subagent background mode', () => {
 
 describe('background preflight failure (no orphaned child, by construction)', () => {
   it('never starts the child when tasks.start preflight throws', async () => {
-    // TaskService is loaded but NO control surface is attached: tasks.start
-    // preflights that fence BEFORE invoking the producer's run(), so the
-    // provider is never asked to spawn — there is no orphan to roll back.
+    // With no control surface, task preflight fails before the provider can spawn.
     const ctx = await setup({ provider: 'mock' })
     await ctx.plugin(AgentRegistry)
     await ctx.plugin(TaskService)

packages/tasks/README.md

@@ -1,10 +1,10 @@
 # tasks/ — background task capability family
 
-The shared background-task runtime: ONE home for task ids, owner isolation, polling, cancellation, wait, and completion notification, so bash, subagents, and every future long-running tool expose the same model-facing habit instead of cloning a private task protocol each. Rationale and the full design: [the background-task-runtime RFC](../../docs/rfc/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md).
+The shared home for background-task ids, owner isolation, reads, cancellation, waiting, and completion notices. Bash, subagents, and future long-running tools use one model-facing protocol. See the [background-task runtime RFC](../../docs/rfc/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md).
 
 | Package | ctx key | Role |
 |---|---|---|
 | [`tasks`](tasks/README.md) (`@deepseek-ai/dsh-tasks`) | `ctx.tasks` | The registry service: branded `<kind>-N` ids, owner-fenced read/kill/wait/list, settlement bookkeeping, the awaited owner-cleanup path, and the `attachSurface` misconfiguration fence |
 | [`tool-tasks`](tool-tasks/README.md) (`@deepseek-ai/dsh-tool-tasks`) | — | The model-facing control surface: `task_output`, `task_list`, `task_kill`, the completion-notice injection, and the background-habit prompt section |
 
-The split is the state/surface boundary: the registry holds task state (an HMR reload of any tool plugin never orphans or kills a running task), while the tool surface is stateless presentation. Producers (`dsh-tool-bash`, `dsh-tool-subagent`) hand their work to `ctx.tasks.start` (preflight, then the producer's starter, then an atomic commit) and keep their own execution concerns; whether a producer exposes `run_in_background` is that producer's own `enableRunInBackground` config, never rewritten by this family.
+The registry owns state across producer or surface reloads; the tool package owns presentation. Producers register execution hooks through `ctx.tasks.start` and own whether their config exposes `run_in_background`.

packages/tasks/tasks/README.md

@@ -1,35 +1,34 @@
 # @deepseek-ai/dsh-tasks
 
-The background task registry (`ctx.tasks`): a runtime-global, CONCRETE service (no interface/implementation split — one sensible in-process implementation exists; a durable job backend would own that extraction) that gives every long-running tool the same ids, isolation, and lifecycle.
+The process-local background task registry (`ctx.tasks`). It gives long-running producers shared ids, owner isolation, reads, cancellation, waiting, notices, and cleanup. The service is concrete; a durable backend can introduce an interface when its different lifecycle is specified.
 
 ## Service API
 
-- `start(spec): TaskId` — declare-then-execute: the producer hands identity (`kind` — also the id prefix — `label`, optional `owner: Agent`) plus `run()`, the starter that returns the work's `TaskHooks` (`cancel(reason?)`, `done: Promise<TaskOutcome>` settling at QUIESCENCE and never rejecting, optional `readOutput()` for stream kinds; absence = final-output-only). Every check that can fail — the control-surface fence (the loud guard against a deployment exposing `run_in_background` with no way to collect or stop the work), validation, the owner-cleanup attach — runs BEFORE `run()` starts the actual work, and nothing can fail after it returns: work started without a collectable id is structurally impossible, not a producer rollback obligation.
-- `get(id, caller?)` / `list(caller?)` — non-consuming snapshots; `list` returns only caller-owned plus unowned tasks (a global listing would leak foreign labels).
-- `read(id, caller?): TaskRead` — stream kinds consume the per-task cursor (v1's single intended reader is the owning model — a non-consuming multi-reader surface would be a cursor/snapshot API extension, not a `read` change); final kinds read the terminal output idempotently.
-- `kill(id, caller?, reason?)` — `'requested'` (live task: producer `cancel` runs first — a throw fails the kill loud and leaves the task untouched — then `stopping`) or `'already-terminal'`. Every successful kill marks the task `reported` (the killer saw the end → completion notice suppressed).
-- `wait(id, timeoutMs, caller?, signal?)` — resolves with the terminal snapshot (marked `reported`), or the live snapshot at timeout; an aborted signal rejects the WAIT only — unless the task already settled, in which case the wait still resolves and delivers the terminal snapshot (settlement suppressed the completion notice on this waiter's behalf, so rejecting would leave the finish both unreported and un-noticed). Timing is a [`dsh-timeout`](../../util/timeout/README.md) `deadline()` scoped to the `TASK_WAIT_TIMEOUT` code, so a nested foreign deadline never misreads as a wait timeout; timeout and abort detach their settlement resolver immediately, keeping retention bounded while the task remains live.
-- `onTaskDone(listener)` — exactly once per terminal task record, with the snapshot plus its exact lifecycle owner (or `undefined`); effect-scoped, contains synchronous throws and returned promise rejections without awaiting listener work, silent after service disposal.
-- `attachSurface(name)` — declares a control surface exists (the model tools, or a deployment's custom surface); effect-scoped.
+- `start(spec): TaskId` validates the control surface, spec, and exact live owner before calling the producer's `run()` once. A starter throw leaves nothing registered; successful return commits without another failable step.
+- `get(id, caller?)` and `list(caller?)` return non-consuming snapshots. Listing includes only caller-owned and unowned tasks.
+- `read(id, caller?)` consumes the single cursor for stream tasks and reads terminal output idempotently for final-output tasks.
+- `kill(id, caller?, reason?)` invokes producer cancellation before changing status. A cancellation throw leaves the task running; success changes it to `stopping` and marks terminal delivery reported.
+- `wait(id, timeoutMs, caller?, signal?)` returns a terminal snapshot or the live snapshot at timeout. Aborting stops only the wait; settlement wins once it has committed terminal delivery to that waiter.
+- `onTaskDone(listener)` observes each terminal record with the exact owner. Listener throws and rejections are contained; listener work is not awaited.
+- `attachSurface(name)` declares a control surface for its effect lifetime. `start()` fails before producer execution when none is attached.
 
-Every read/kill/wait/get compares the task's owner session (`owner.session.header.id`) with the caller's and rejects a foreign one — ids are predictable (`bash-1`), so the fence, not id secrecy, is the isolation boundary.
+Owned access compares the task's `SessionId` with the caller's. Ids such as `bash-1` are predictable, so this fence is the boundary. Unowned tasks are open to callers and last until service disposal.
 
 ## Lifecycle
 
-- Registrations are NOT effect-scoped to the registering fiber: tasks belong to their owning agent + producing backend, so producer/surface HMR reloads never touch them.
-- An owned task retains the exact live `Agent` instance validated at start and attaches one awaited cleanup through `owner.ctx`: agent-scope disposal selects only that instance's tasks, cancels them, awaits contract-compliant producers to quiescence, and drops their snapshots. Reused agent/session ids cannot make an old cleanup sweep replacement work. If a teardown cancel throws, it force-fails the record and logs that the underlying work may be orphaned rather than deadlocking `AgentHandle.dispose()`.
-- Service disposal closes the listener registry first, applies the same cancellation rule to every live task, awaits terminal records, then detaches its effects from still-live agent scopes so a reloaded tasks service is not retained until those agents exit.
-- A producer whose `cancel` returns but never causes `done` to settle remains indistinguishable from a slow stop and can stall teardown; solving that residual requires an explicit bounded-lifetime or forced-disposal design.
+Tasks belong to their owner and backend, not the producer tool fiber, so producer and surface reloads do not stop them. The first task for an owner attaches one awaited effect to the exact `Agent` scope. Owner disposal cancels that object's tasks, awaits producer quiescence, and removes their snapshots; reused agent or session ids cannot redirect an old cleanup.
+
+Service disposal closes listeners, cancels all live tasks, awaits their records, and detaches effects from surviving owner scopes. If teardown cancellation throws, the service force-fails the record and warns that work may be orphaned instead of deadlocking. A cancellation that returns but never settles `done` remains indistinguishable from a slow stop and can stall teardown.
+
+See the [task type catalog](../../../docs/core-data-structures/tasks.md) and [runtime RFC](../../../docs/rfc/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md).
 
 ## Model Experience
 
-Indirectly, through `dsh-tool-tasks` and producer plugins, which render task ids, output, status, and completion notices.
+Indirectly, through producer plugins and [`dsh-tool-tasks`](../tool-tasks/README.md), which render task ids, output, status, cancellation, and completion notices.
 
 ## Known Limitations and Deferred Work
 
-- **Tasks are process-local** — durable or cross-restart execution is deferred.
-- **Stream output has one consuming cursor** — non-consuming observation and multiple independent readers require a separate cursor/snapshot API.
-- **Foreground work cannot be promoted** — producers must choose foreground or background before execution starts.
-- **A silently ineffective producer cancel can stall teardown** — the runtime can force-settle an explicit cancel throw, but cannot distinguish a slow stop from a cancel that returned without stopping work.
-
-See the [runtime RFC](../../../docs/rfc/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md) § Alternatives for the deferred designs.
+- **Tasks are process-local** — durable or cross-restart execution needs a separate lifecycle.
+- **Stream output has one consuming cursor** — independent observers need a cursor or snapshot API.
+- **Foreground work cannot be promoted** — producers choose foreground or background before starting.
+- **A silently ineffective cancel can stall teardown** — only an explicit throw can be force-failed safely.

packages/tasks/tasks/src/index.ts

@@ -1,32 +1,11 @@
 /**
- * The background task registry (`ctx.tasks`): ONE home for the semantics every
- * long-running tool needs — branded task ids, owner-scoped isolation, status
- * snapshots, incremental/final output reads, cancellation, wait-for-terminal,
- * completion listeners, and the awaited owner-cleanup path. Producers
- * (`dsh-tool-bash` background commands, `dsh-tool-subagent` background
- * delegations, future long-running tools) hand their work to
- * {@link TaskService.start} — preflight, then the producer's starter, then an
- * atomic commit — and keep their own execution concerns; the
- * model-facing control surface (`@deepseek-ai/dsh-tool-tasks`) drives the
- * generic read/list/kill/wait operations.
- *
- * A CONCRETE service, not an interface/implementation seam pair: there is one
- * sensible in-process implementation today, and the capability-seam convention
- * says not to split preemptively (see the background-task-runtime RFC).
- *
- * Cross-session isolation lives IN the registry: task ids are runtime-global
- * and predictable (`bash-1`, `subagent-1`), so every read/kill/wait compares
- * the task's owner session against the caller and rejects a foreign one —
- * every surface gets the fence for free instead of re-implementing it.
- *
- * Task registrations are NOT effect-scoped to the registering fiber: a task
- * belongs to its owning agent and producing backend, not to the tool plugin
- * whose call started it, so an HMR reload of a producer or of the control
- * surface never orphans or kills a running task. The registry's own disposal
- * cancels every live task and awaits contract-compliant producers to
- * quiescence. If a teardown cancel throws, the registry force-fails its record
- * to avoid deadlock and logs that the underlying work may be orphaned.
+ * The in-process background task registry (`ctx.tasks`). It owns task ids,
+ * session-scoped access, lifecycle state, completion listeners, and owner
+ * cleanup while producers retain their execution resources.
  *
+ * Registrations outlive producer and control-surface fibers. Agent or service
+ * disposal cancels live work and awaits compliant producers; a throwing
+ * teardown cancel force-fails only the record and reports a possible orphan.
  * @module @deepseek-ai/dsh-tasks
  */
 
@@ -53,12 +32,7 @@ declare module 'cordis' {
   }
 }
 
-/**
- * The `dsh-timeout` code stamped on a {@link TaskService.wait} deadline's
- * `TimeoutReason`. A wait timeout only ends the WAIT (the task keeps running
- * and the live snapshot is returned) — scoping `timeoutOf` to this code keeps
- * a foreign (outer, nested) deadline's timeout from being misread as ours.
- */
+/** Timeout code that distinguishes a bounded wait from caller cancellation. */
 export const TASK_WAIT_TIMEOUT = 'TASK_WAIT_TIMEOUT'
 
 /** The registry's mutable per-task record (never handed out — see {@link TaskService.snapshot}). */
@@ -78,9 +52,9 @@ interface TrackedTask {
   reported: boolean
   /** Resolves once the terminal snapshot is recorded and listeners notified. */
   settled: Promise<void>
-  /** Resolver for {@link settled} (called by the first effective {@link TaskService.settle}). */
+  /** Resolver for {@link settled}, called by the first effective settlement. */
   markSettled: () => void
-  /** Live {@link TaskService.wait} calls — a settlement with waiters marks the task reported. */
+  /** Live waits; settlement with a waiter marks the task reported. */
   waiters: number
   /** Removable resolvers for live waits; timeout/abort unregister before the task settles. */
   waitResolvers: Set<() => void>
@@ -101,15 +75,9 @@ export class TaskService extends Service {
   private surfaces = new Set<symbol>()
   private listeners = new Set<TaskDoneListener>()
   private listenersClosed = false
-  /** Owner agents whose scope cleanup is attached, mapped to its exact disposer. */
+  /** Owner agents with attached scope cleanup, mapped to the exact disposer. */
   private ownerCleanups = new Map<Agent, () => Promise<void> | void>()
-  /**
-   * The service's OWN construction-time context, for work that outlives the
-   * calling fiber: detached settlement continuations (logging), and the
-   * service teardown. Owner cleanup itself is registered through the owning
-   * agent's scope so it survives producer-plugin reloads and participates in
-   * the agent's structural quiescence boundary.
-   */
+  /** Service context used by detached settlement continuations and teardown. */
   private readonly selfCtx: Context
 
   constructor(ctx: Context) {
@@ -119,24 +87,14 @@ export class TaskService extends Service {
   }
 
   /**
-   * PREFLIGHT, start, then atomically register background work; returns its
-   * task id (`<kind>-N`, per-kind counter). Every check that can fail — the
-   * control-surface fence ({@link attachSurface}; a task the model could
-   * never read or stop must fail loud before it exists), kind/label
-   * validation, exact live owner-instance identity, and the owner's awaited
-   * disposal-cleanup attach (once per owner agent, through `owner.ctx`) — runs BEFORE
-   * `spec.run()` starts the actual work, and nothing in the runtime can fail
-   * after it returns: "work started but never got a collectable id" is
-   * structurally impossible, not a producer rollback obligation. The runtime
-   * attaches ONE continuation to the returned `done` that records the
-   * terminal snapshot, notifies {@link onTaskDone} listeners, and releases
-   * waiters. A throwing `run()` propagates with nothing registered (the
-   * producer owns any partial cleanup of its own failed start).
-   * @param spec - the task's identity/owner plus the `run()` starter (see {@link TaskStart}).
-   * @returns the registry-issued task id.
+   * Preflight access, validation, and owner cleanup before starting and
+   * atomically registering work. A throwing starter leaves nothing registered;
+   * after it returns, registration cannot fail. Settlement records the outcome,
+   * notifies listeners, and releases waiters.
+   * @param spec - task identity, owner, and synchronous starter.
+   * @returns the registry-issued `<kind>-N` id.
    */
   start(spec: TaskStart): TaskId {
-    // -- Preflight: everything that can throw, before any work or mutation. --
     if (this.surfaces.size === 0) {
       throw new Error('background tasks unavailable: no control surface is attached (load @deepseek-ai/dsh-tool-tasks)')
     }
@@ -144,10 +102,7 @@ export class TaskService extends Service {
     if (spec.label.length === 0) throw new Error('invalid task label: expected a non-empty string')
     if (spec.owner !== undefined) this.ensureOwnerCleanup(spec.owner)
 
-    // -- Start: the producer's work begins only now, preflight-clean. --
     const hooks = spec.run()
-
-    // -- Commit: pure mutations; nothing below can throw. --
     const count = (this.counters.get(spec.kind) ?? 0) + 1
     this.counters.set(spec.kind, count)
     const id = TaskId(`${spec.kind}-${count}`)
@@ -177,8 +132,7 @@ export class TaskService extends Service {
     void hooks.done.then(
       (outcome) => { this.settle(task, outcome) },
       (error: unknown) => {
-        // Producer contract violation (`done` must never reject) — contained
-        // as a failed outcome so waiters, cleanup, and disposal never hang.
+        // Contain a producer contract violation so cleanup and waiters cannot hang.
         this.selfCtx.logger.warn(`tasks: task ${task.id} 'done' rejected (producer contract violation): ${String(error)}`)
         this.settle(task, { status: 'failed', detail: String(error) })
       },
@@ -187,11 +141,10 @@ export class TaskService extends Service {
   }
 
   /**
-   * The caller-VISIBLE tasks (owned by the caller's session, or unowned), in
-   * registration order. Never lists another session's tasks — a global
-   * listing would leak their labels across the isolation fence.
-   * @param caller - the reading agent; undefined (a non-agent caller) sees only unowned tasks.
-   * @returns fresh snapshots; mutating them does not affect the registry.
+   * List caller-owned and unowned tasks in registration order without exposing
+   * another session's labels.
+   * @param caller - reading agent; a non-agent caller sees only unowned tasks.
+   * @returns fresh snapshots.
    */
   list(caller?: Agent): TaskSnapshot[] {
     const session = caller?.session.header.id
@@ -201,12 +154,10 @@ export class TaskService extends Service {
   }
 
   /**
-   * A non-consuming snapshot of one task — unlike {@link read}, never touches
-   * the stream cursor or the reported flag (the kill surface uses it to
-   * describe an already-terminal task WITHOUT eating a pending delta).
-   * Throws for an unknown id or a task owned by another session.
-   * @param id - the task to look up.
-   * @param caller - the reading agent, checked against the task's owner.
+   * Return a non-consuming snapshot without changing its read cursor or notice
+   * state. Throws for an unknown or foreign task.
+   * @param id - task to look up.
+   * @param caller - reading agent checked against the owner.
    * @returns a fresh snapshot.
    */
   get(id: TaskId, caller?: Agent): TaskSnapshot {
@@ -216,15 +167,12 @@ export class TaskService extends Service {
   }
 
   /**
-   * Read a task's output. Stream kinds (registered with `readOutput`) yield
-   * the CONSUMING delta since the previous read — one cursor per task, the
-   * owning model is v1's single intended reader; final-output kinds yield
-   * empty text while live and the terminal output idempotently once settled.
-   * A read that returns the terminal state marks the task {@link TaskSnapshot.reported}.
-   * Throws for an unknown id or a task owned by another session.
-   * @param id - the task to read.
-   * @param caller - the reading agent, checked against the task's owner.
-   * @returns the read text plus the post-read snapshot.
+   * Read the next stream delta, or the idempotent final output after settlement.
+   * A terminal read marks the task reported. Throws for an unknown or foreign
+   * task.
+   * @param id - task to read.
+   * @param caller - reading agent checked against the owner.
+   * @returns output text and the post-read snapshot.
    */
   read(id: TaskId, caller?: Agent): TaskRead {
     const task = this.expect(id)
@@ -237,18 +185,13 @@ export class TaskService extends Service {
   }
 
   /**
-   * Request cancellation of a task. A live task has its producer
-   * `cancel(reason)` invoked FIRST — a throw propagates (fail loud) and
-   * leaves the task untouched (still `running`, notice not suppressed) —
-   * then moves to `stopping` and settles through the normal `done` path; an
-   * already-terminal task is reported, not failed. Every SUCCESSFUL kill
-   * marks the task {@link TaskSnapshot.reported}: the killer has seen (or
-   * asked for) the end, so the completion notice is suppressed. Throws for
-   * an unknown id or a task owned by another session.
-   * @param id - the task to cancel.
-   * @param caller - the killing agent, checked against the task's owner.
-   * @param reason - the surface's logged reason, forwarded to the producer.
-   * @returns 'requested' when cancellation was asked of a live task, 'already-terminal' otherwise.
+   * Request cancellation, then mark the task stopping and reported. A producer
+   * throw propagates without changing task state. Throws for an unknown or
+   * foreign task.
+   * @param id - task to cancel.
+   * @param caller - killing agent checked against the owner.
+   * @param reason - logged reason forwarded to the producer.
+   * @returns `requested` for live work, otherwise `already-terminal`.
    */
   kill(id: TaskId, caller?: Agent, reason?: string): 'requested' | 'already-terminal' {
     const task = this.expect(id)
@@ -257,12 +200,7 @@ export class TaskService extends Service {
       task.reported = true
       return 'already-terminal'
     }
-    // Producer cancel FIRST: a throw must leave the task untouched (still
-    // `running`, notice not suppressed) — the killer's tool call fails loud,
-    // but task_list and the eventual completion notice keep telling the
-    // truth about a cancellation that never happened. Cancel is synchronous
-    // and settlement lands on a later microtask, so the mutations below
-    // cannot race the settle path.
+    // Cancel first so a throw leaves both lifecycle and notice state unchanged.
     task.cancel(reason)
     task.status = 'stopping'
     task.reported = true
@@ -270,23 +208,16 @@ export class TaskService extends Service {
   }
 
   /**
-   * Wait for a task to settle, bounded by a timeout. Resolves with the
-   * terminal snapshot (marked {@link TaskSnapshot.reported} — the wait
-   * response reports the end, so the completion notice is suppressed), or
-   * with the still-live snapshot when the timeout expires first. An abort of
-   * `signal` rejects the WAIT only (the task keeps running) — UNLESS the task
-   * has already settled: settlement saw this live waiter and suppressed the
-   * completion notice on its behalf, so the wait still resolves and delivers
-   * the terminal snapshot it owes (an abort must never leave a finished task
-   * both unreported and notice-suppressed). Each live wait uses a removable
-   * resolver that timeout/abort detaches, so a long-running task does not
-   * retain expired waits. Throws for an unknown id, a task owned by another
-   * session, or a non-positive timeout.
-   * @param id - the task to wait for.
-   * @param timeoutMs - max wait in milliseconds (positive, finite; the surface caps it).
-   * @param caller - the waiting agent, checked against the task's owner.
-   * @param signal - optional abort for the wait itself.
-   * @returns the snapshot at settlement, or at timeout when the task outlives the wait.
+   * Wait for settlement or timeout without cancelling the task. Caller abort
+   * rejects only while the task is live; after settlement it returns the
+   * terminal snapshot so a notice suppressed for this waiter is still delivered.
+   * Timed-out and aborted waits detach their resolvers. Throws for invalid,
+   * unknown, or foreign input.
+   * @param id - task to wait for.
+   * @param timeoutMs - positive finite wait bound in milliseconds.
+   * @param caller - waiting agent checked against the owner.
+   * @param signal - optional cancellation of the wait itself.
+   * @returns snapshot at settlement or timeout.
    */
   async wait(id: TaskId, timeoutMs: number, caller?: Agent, signal?: AbortSignal): Promise<TaskSnapshot> {
     const task = this.expect(id)
@@ -296,12 +227,8 @@ export class TaskService extends Service {
     }
     if (!isTerminal(task.status)) {
       if (signal?.aborted) throw new Error('wait aborted')
-      // `waiters` is the settle-path heuristic "someone WILL deliver the
-      // terminal snapshot, suppress the notice". An abort breaks that promise,
-      // so the un-count must happen SYNCHRONOUSLY inside onAbort — the
-      // `finally` decrement alone runs a microtask later, after a same-tick
-      // settlement could already have read the stale count and suppressed the
-      // notice for a waiter that then rejects and delivers nothing.
+      // Abort removes the waiter synchronously so same-tick settlement cannot
+      // suppress a notice for a wait that will reject.
       task.waiters += 1
       let counted = true
       const uncount = (): void => {
@@ -310,11 +237,8 @@ export class TaskService extends Service {
         task.waiters -= 1
       }
       try {
-        // The dsh-timeout deadline fits wait() exactly because both only
-        // NOTIFY: a wait timeout returns the live snapshot (the task keeps
-        // running — nothing is terminated), and timeoutOf scoped to our own
-        // code tells that timeout apart from a caller abort, which rejects
-        // the wait. `using` clears the timer on every exit path.
+        // The scoped deadline distinguishes a successful wait timeout from
+        // caller cancellation and clears its timer on every exit.
         using d = deadline(signal, timeoutMs, TASK_WAIT_TIMEOUT)
         await new Promise<void>((resolve, reject) => {
           const onSettled = (): void => {
@@ -327,8 +251,7 @@ export class TaskService extends Service {
             if (timeoutOf(d.signal, TASK_WAIT_TIMEOUT) !== undefined) {
               resolve()
             } else if (isTerminal(task.status)) {
-              // Settlement already ran and suppressed the notice for this
-              // waiter — deliver the terminal snapshot instead of rejecting.
+              // Settlement suppressed the notice for this waiter; deliver it.
               resolve()
             } else {
               uncount()
@@ -347,14 +270,11 @@ export class TaskService extends Service {
   }
 
   /**
-   * Register a completion listener, called exactly once per terminal task
-   * record with its snapshot and exact lifecycle owner (or `undefined` for an
-   * unowned task). Effect-scoped (disposed with the calling fiber); per-listener
-   * containment (one throwing or rejecting listener is logged, never starves
-   * the rest); returned promises are observed but not awaited; never fires
-   * after this service is disposed.
-   * @param listener - called with each terminal snapshot and its exact owner.
-   * @returns the disposer that unregisters the listener.
+   * Register an effect-scoped completion listener. Each listener is contained;
+   * returned promises are observed but not awaited. No listener runs after
+   * service disposal.
+   * @param listener - receives each terminal snapshot and its exact owner.
+   * @returns disposer that unregisters the listener.
    */
   onTaskDone(listener: TaskDoneListener): () => void {
     const dispose = this.ctx.effect(() => {
@@ -365,19 +285,13 @@ export class TaskService extends Service {
   }
 
   /**
-   * Declare that a control surface capable of reading/stopping tasks is
-   * loaded. {@link start} refuses to start a background task while NO
-   * surface is attached — the loud fence against a deployment exposing
-   * `run_in_background` without any way to collect or stop the work. The
-   * model-facing `@deepseek-ai/dsh-tool-tasks` attaches on load; a deployment
-   * with a custom (non-model) surface attaches its own. Effect-scoped:
-   * detached with the calling fiber.
-   * @param name - a diagnostic label for the surface (duplicate names count independently).
-   * @returns the disposer that detaches the surface.
+   * Attach an effect-scoped surface that can read and stop tasks. {@link start}
+   * refuses work while none is attached.
+   * @param name - diagnostic label; duplicate names remain independent.
+   * @returns disposer that detaches this surface.
    */
   attachSurface(name: string): () => void {
-    // One token per attach call: duplicate names stay independent, and the
-    // single-shot effect disposer removes exactly its own attachment.
+    // One token per call keeps duplicate labels independently disposable.
     const token = Symbol(name)
     const dispose = this.ctx.effect(() => {
       this.surfaces.add(token)
@@ -421,14 +335,9 @@ export class TaskService extends Service {
   }
 
   /**
-   * Record the first terminal outcome, notify listeners with containment, then
-   * release waiters. Normally the producer's single `done` continuation calls
-   * this; teardown also force-fails the record when `cancel` throws and `done`
-   * may never settle. First-wins makes a producer outcome arriving after that
-   * fallback a no-op, so listeners fire once and the diagnosed terminal state
-   * is never overwritten. A settlement observed by a pending {@link wait}
-   * marks the task reported BEFORE listeners run, so the notice surface can
-   * suppress its redundant "finished".
+   * Record the first terminal outcome, notify contained listeners, and release
+   * waiters. First-wins preserves a teardown force-failure against late producer
+   * settlement. Pending waits mark the task reported before listeners run.
    */
   private settle(task: TrackedTask, outcome: TaskOutcome): void {
     if (isTerminal(task.status)) return
@@ -457,17 +366,10 @@ export class TaskService extends Service {
   }
 
   /**
-   * Attach the awaited owner-disposal cleanup for an owner agent, once. The
-   * effect is registered through `owner.ctx`, so it belongs to the agent scope
-   * rather than the producer or long-lived tasks fiber: it survives producer
-   * reloads, runs at the structural agent quiescence boundary, and removes its
-   * wrapper automatically when that scope unwinds. The tasks service retains
-   * the exact disposer only so service teardown can detach cross-fiber effects
-   * instead of leaving a dead service captured by still-live agents.
-   * Fails loud when no agent registry is mounted or when `owner` is not the
-   * exact live instance currently registered under its id — accepting a stale
-   * object after id reuse would attach its session's task to another agent's
-   * lifecycle.
+   * Attach one awaited cleanup through the exact owner's scope. This survives
+   * producer reloads and joins agent quiescence; the retained disposer lets
+   * service teardown detach the cross-fiber effect. Fails when the registry is
+   * absent or the owner is not its currently registered instance.
    */
   private ensureOwnerCleanup(owner: Agent): void {
     const ownerId = owner.id
@@ -479,8 +381,7 @@ export class TaskService extends Service {
       throw new Error(`agent "${ownerId}" is not the registered agent instance (background task owner must be live)`)
     }
     if (this.ownerCleanups.has(owner)) return
-    // Attach FIRST, record after: an already-disposing scope rejects effects,
-    // and marking the owner as covered before that would poison later starts.
+    // Record only after attach succeeds; a disposing scope rejects new effects.
     const detach = owner.ctx.effect(() => async () => {
       this.ownerCleanups.delete(owner)
       await this.disposeOwned(owner)
@@ -497,11 +398,8 @@ export class TaskService extends Service {
   }
 
   /**
-   * Service teardown: close the listener registry FIRST (late completions
-   * from teardown kills stay silent), cancel every live task, and await each
-   * terminal record. Contract-compliant producers settle at quiescence; a
-   * producer whose cancel throws is force-failed so disposal cannot deadlock,
-   * with the possible underlying orphan logged explicitly.
+   * Close listeners, cancel live tasks, await settlement, and detach owner
+   * effects. Throwing cancels are force-failed to avoid teardown deadlock.
    */
   private async disposeAll(): Promise<void> {
     this.listenersClosed = true
@@ -510,24 +408,16 @@ export class TaskService extends Service {
     this.cancelForTeardown(all, 'tasks service disposed')
     await Promise.all(all.map(task => task.settled))
     this.store.clear()
-    // These effects belong to agent scopes, not this service's fiber. Detach
-    // them after the shared store is quiescent so a tasks-service reload cannot
-    // leave old callbacks retaining the dead service until each agent exits.
+    // Detach cross-fiber owner effects after the shared store is quiescent.
     const ownerCleanups = [...this.ownerCleanups.values()]
     this.ownerCleanups.clear()
     await Promise.all(ownerCleanups.map(cleanup => Promise.resolve(cleanup())))
   }
 
   /**
-   * Teardown-path cancellation with per-task containment: unlike the
-   * model-facing {@link kill} (where a throwing producer `cancel` fails the tool
-   * call and leaves the record live), teardown force-fails a record whose cancel
-   * throws because its `done` may depend on a request that never arrived. This
-   * prevents disposal deadlock but cannot prove the underlying work stopped, so
-   * the potential orphan is carried in the detail and warning. A cancel that
-   * returns but never leads to `done` remains indistinguishable from a slow stop
-   * and can still stall teardown; fixing that requires a separate bounded-lifetime
-   * or forced-disposal design.
+   * Cancel tasks during teardown with per-task containment. A throwing cancel
+   * force-fails the record and reports a possible orphan; a cancel that returns
+   * without settling remains indistinguishable from a slow stop and may stall.
    */
   private cancelForTeardown(tasks: TrackedTask[], reason: string): void {
     for (const task of tasks) {

packages/tasks/tasks/src/types.ts

@@ -1,9 +1,6 @@
 /**
- * Task-runtime vocabulary: the {@link TaskStart} a producer hands to
- * {@link TaskService.start} (identity + the `run()` starter), the
- * {@link TaskHooks} its work is driven through, and the snapshots/reads
- * consumers get back. Types only — the service lives in `./index.ts`.
- *
+ * Types shared by task producers, the registry, and control surfaces. The
+ * service implementation lives in `./index.ts`.
  * @module @deepseek-ai/dsh-tasks/types
  */
 
@@ -12,10 +9,8 @@ import type { Agent } from '@deepseek-ai/dsh-agent'
 import type { SessionId } from '@deepseek-ai/dsh-session'
 
 /**
- * Identifies one background task in the runtime-global registry. Generated by
- * {@link TaskService.start} as `<kind>-N` (per-kind counter) — kind-prefixed
- * so transcripts stay self-describing, sequential because the owner fence (not
- * id secrecy) is the isolation boundary.
+ * Identifies a background task. The registry generates `<kind>-N`; predictable
+ * ids rely on owner authorization rather than secrecy.
  */
 export type TaskId = Branded<'TaskId'>
 
@@ -29,40 +24,25 @@ export function TaskId(id: string): TaskId {
 }
 
 /**
- * Task lifecycle. `running` → (`stopping` when cancellation was requested) →
- * exactly one terminal {@link TaskOutcome.status} (`completed`, `killed`,
- * `failed`). The vocabulary is generic and CLOSED — kind-specific meaning
- * (exit codes, stop reasons) rides in {@link TaskSnapshot.detail}, so the
- * registry never learns process or agent semantics.
+ * Task lifecycle: `running`, optionally `stopping`, then exactly one terminal
+ * status. Producer-specific facts belong in {@link TaskSnapshot.detail}.
  */
 export type TaskStatus = 'running' | 'stopping' | 'completed' | 'killed' | 'failed'
 
-/**
- * The terminal result a producer's {@link TaskHooks.done} resolves
- * with, mapped from the producer's own vocabulary (a process exit, a subagent
- * stop reason) into the registry's closed status set.
- */
+/** Terminal result supplied by a producer through {@link TaskHooks.done}. */
 export interface TaskOutcome {
   /** How the task ended: finished (`completed`), cancelled (`killed`), or broke (`failed`). */
   status: 'completed' | 'killed' | 'failed'
   /** Kind-specific detail rendered into status lines ('exit code: 3', 'max-tokens'). */
   detail?: string
-  /**
-   * Final output for FINAL-OUTPUT-ONLY kinds (no {@link TaskHooks.readOutput}),
-   * read idempotently after the task settles. Stream kinds leave it unset —
-   * their output is consumed incrementally through `readOutput`.
-   */
+  /** Final output for tasks without `readOutput`; stream tasks leave it unset. */
   output?: string
 }
 
 /**
- * What a producer hands to {@link TaskService.start}: the task's identity and
- * owner (preflighted BEFORE any work starts), plus {@link run} — the starter
- * the runtime invokes only once preflight cannot fail anymore. The producer
- * stays the owner of its execution concerns (process streams, child agents);
- * the runtime owns ids, isolation, status, and completion fan-out. This
- * declare-then-execute split is what makes "work started but never got a
- * collectable id" structurally impossible.
+ * Producer declaration passed to {@link TaskService.start}. The runtime
+ * preflights access and cleanup before invoking {@link run}; the producer owns
+ * execution resources while the runtime owns identity and lifecycle state.
  */
 export interface TaskStart {
   /** Producer kind — also the id prefix (`bash`, `subagent`, …). Non-empty. */
@@ -70,56 +50,38 @@ export interface TaskStart {
   /** One-line model-facing label (the command; the delegation description). */
   label: string
   /**
-   * The spawning agent. Its `session.header.id` becomes the task's owner
-   * identity (read/kill/wait/list are fenced to that session), and its `ctx` scope
-   * owns an async cleanup that cancels and awaits the task during disposal. It
-   * must be the exact live instance currently registered under its agent id;
-   * a stale object whose id has been reused is rejected before work starts.
-   * `undefined` starts an UNOWNED task: open to any caller, alive until the
-   * tasks service disposes.
+   * Owning live agent. Access is fenced by its session id, and agent disposal
+   * cancels and awaits the task. The instance must be the one currently
+   * registered under its agent id. `undefined` creates an unowned task, open to
+   * any caller until service disposal.
    */
   owner?: Agent | undefined
   /**
-   * Start the actual work and return its {@link TaskHooks}. Called EXACTLY
-   * once, synchronously, after every preflight check (control-surface fence,
-   * validation, owner-cleanup attach) has passed — nothing in the runtime can
-   * fail after it returns, so the started work is always registered. A throw
-   * here propagates with nothing registered; the producer owns any partial
-   * cleanup of its own failed start.
+   * Start the work after preflight and synchronously return its hooks. Called
+   * once; a throw leaves nothing registered, and the producer must clean up any
+   * partially started resources.
    */
   run(): TaskHooks
 }
 
-/**
- * The live-work hooks a {@link TaskStart.run} returns: how the runtime
- * cancels the work, observes its settlement, and (for stream kinds) reads
- * its incremental output.
- */
+/** Hooks through which the runtime controls and observes producer work. */
 export interface TaskHooks {
   /**
-   * Request termination. Idempotent, synchronous, and must lead to
-   * {@link done} settling; a throw propagates to the killer (fail loud — a
-   * cancel that cannot even be requested is a producer bug). The optional
-   * reason is `task_kill`'s logged reason, forwarded verbatim.
+   * Request termination. Must be synchronous, idempotent, and eventually settle
+   * {@link done}; throws propagate. The optional reason is forwarded verbatim.
    */
   cancel(reason?: string): void
   /**
-   * Settles with the terminal outcome at QUIESCENCE — after the producer has
-   * released the task's resources (process exited, child agent disposed) —
-   * not merely when the work finished. Must never reject; a rejection is
-   * contained as a `failed` outcome and logged as a producer contract
-   * violation. If `cancel` throws during teardown, the runtime may force-fail
-   * only its registry record to avoid deadlock because this promise may never
-   * settle; that fallback explicitly does not claim work quiescence.
+   * Resolves after the producer releases its resources, not merely when work
+   * finishes. Must not reject; the runtime converts a rejection to `failed`.
+   * If teardown cancellation throws, the runtime may force-fail only the
+   * registry record without claiming that the work stopped.
    */
   done: Promise<TaskOutcome>
   /**
-   * OPTIONAL incremental read (stream kinds): everything produced since the
-   * previous call, formatted by the producer (truncation/spill notices
-   * included). Consecutive calls never re-deliver output; the registry keeps
-   * ONE consuming cursor per task, so v1's single intended reader is the
-   * owning model. Absence marks a final-output-only kind (the method presence
-   * IS the capability).
+   * Consume output produced since the previous call. The producer formats
+   * truncation and spill notices. Absence marks a final-output-only task; each
+   * task has one consuming cursor.
    */
   readOutput?(): string
 }
@@ -136,12 +98,9 @@ export interface TaskSnapshot {
   /** The producer-supplied one-line label. */
   label: string
   /**
-   * The owner's session id (`session.header.id`), for authorization and
-   * correlation; absent for unowned tasks. A listener that must reach the
-   * lifecycle owner receives the exact Agent separately through
-   * {@link TaskDoneListener}. Session ids are runtime-shared identifiers, not
-   * secrets — the read/kill/wait/list FENCE is what isolation rests on. The
-   * shared {@link SessionId} brand is preserved across this package boundary.
+   * Owner session id used for authorization and correlation; absent for
+   * unowned tasks. Completion listeners receive the exact {@link Agent}
+   * separately through {@link TaskDoneListener}.
    */
   ownerSession?: SessionId
   /** Current lifecycle state. */
@@ -153,20 +112,13 @@ export interface TaskSnapshot {
   /** Epoch ms when the task settled; absent while `running`/`stopping`. */
   finishedAt?: number
   /**
-   * True once the terminal state has been (or is being) reported to the owner
-   * through an explicit surface response — a `kill` call, or a `read`/`wait`
-   * that returned the terminal state (including a wait pending at settlement).
-   * Completion-notice surfaces suppress their notice when set, so the model
-   * never gets a redundant "finished" for a task it just collected or killed.
+   * True when a kill, read, or wait has reported or committed to report the
+   * terminal state. Completion surfaces suppress redundant notices when set.
    */
   reported: boolean
 }
 
-/**
- * One {@link TaskService.read}: the output text this read yields (may be
- * empty — the surface decides how to render "nothing new") plus the snapshot
- * taken after the read.
- */
+/** Output and post-read state returned by {@link TaskService.read}. */
 export interface TaskRead {
   /**
    * Stream kinds: the consuming delta since the previous read. Final-output
@@ -179,10 +131,8 @@ export interface TaskRead {
 }
 
 /**
- * Completion callback registered via {@link TaskService.onTaskDone}.
- * `owner` is the exact lifecycle instance supplied at start, not a registry
- * lookup by reusable agent or session id; it is absent for unowned tasks. A
- * returned promise is observed for rejection but does not delay settlement.
+ * Completion callback with the exact owner supplied at start, or `undefined`
+ * for an unowned task. Returned promises are observed but not awaited.
  */
 export type TaskDoneListener = (
   snapshot: TaskSnapshot,

packages/tasks/tasks/tests/tasks.spec.ts

@@ -269,7 +269,7 @@ describe('TaskService.wait', () => {
     const wait = ctx.tasks.wait(id, 5_000)
     p.settle({ status: 'completed', detail: 'exit code: 0' })
     expect(await wait).toMatchObject({ status: 'completed', reported: true })
-    // The pending wait marked the task reported BEFORE listeners ran.
+    // A waiting reader claims delivery before completion listeners inspect the snapshot.
     expect(seen[0]).toMatchObject({ id, reported: true })
   })
 
@@ -330,7 +330,7 @@ describe('TaskService.wait', () => {
     await expect(ctx.tasks.wait(id, 5_000, undefined, preAborted.signal)).rejects.toThrow('wait aborted')
   })
 
-  it('an abort racing settlement in the same tick does not swallow the notice (review finding)', async () => {
+  it('an abort racing settlement in the same tick does not swallow the notice', async () => {
     const ctx = await harness()
     const seen: TaskSnapshot[] = []
     ctx.tasks.onTaskDone(snapshot => void seen.push(snapshot))
@@ -339,11 +339,8 @@ describe('TaskService.wait', () => {
 
     const controller = new AbortController()
     const wait = ctx.tasks.wait(id, 5_000, undefined, controller.signal)
-    // Same synchronous tick, settlement QUEUED first: the settle continuation
-    // will run before the rejected wait's `finally`, so only the SYNCHRONOUS
-    // un-count inside onAbort keeps it from reading a stale waiter count,
-    // marking the task reported, and suppressing the completion notice for a
-    // wait that then delivers nothing.
+    // Settlement is queued first, so abort must remove the waiter synchronously;
+    // otherwise settlement suppresses the notice for a reader that receives nothing.
     p.settle({ status: 'completed', detail: 'exit code: 0' })
     controller.abort()
     await expect(wait).rejects.toThrow('wait aborted')
@@ -351,15 +348,12 @@ describe('TaskService.wait', () => {
     expect(seen[0]).toMatchObject({ id, status: 'completed', reported: false })
   })
 
-  it('an abort landing AFTER settlement still delivers the terminal snapshot it owes', async () => {
+  it('an abort landing after settlement still delivers the terminal snapshot it owes', async () => {
     const ctx = await harness()
     const controller = new AbortController()
     const seen: TaskSnapshot[] = []
-    // The listener runs synchronously inside settle — aborting HERE lands the
-    // abort after settlement marked this waiter reported (notice suppressed)
-    // but before the wait's own resolve microtask. Rejecting now would leave
-    // the finished task both unreported and notice-suppressed, so the wait
-    // must resolve and deliver instead.
+    // The listener aborts after settlement has assigned delivery to this waiter
+    // but before its resolve microtask; the waiter must still receive the result.
     ctx.tasks.onTaskDone((snapshot) => {
       seen.push(snapshot)
       controller.abort()
@@ -426,14 +420,12 @@ describe('TaskService owner isolation', () => {
     const ctx = await harness()
     const ghost = stubAgent(ctx, 'ghost') // never registered in ctx.agents
 
-    // Exact-instance preflight rejects the unregistered agent BEFORE any
-    // registry mutation or owner-cleanup attachment.
+    // Exact-instance validation precedes registry mutation and cleanup attachment.
     expect(() => ctx.tasks.start(producer({ owner: ghost }).spec))
       .toThrow('is not the registered agent instance')
     expect(ctx.tasks.list(ghost)).toEqual([])
 
-    // Once the agent actually exists, the same owner gets a WORKING cleanup —
-    // the failed attempt must not have marked it as already covered.
+    // A later valid registration must still attach cleanup for the same object.
     ctx.agents.register(ghost)
     const cancels: (string | undefined)[] = []
     let settle!: (outcome: TaskOutcome) => void
@@ -607,13 +599,11 @@ describe('TaskService owner cleanup', () => {
     await tick()
     const drainedWithoutProducerDone = drained
     if (!drainedWithoutProducerDone) {
-      // Failure-path cleanup for the pre-fix implementation: let its pending
-      // drain finish without weakening the assertion captured above.
+      // Release the producer if the assertion fails so the test can finish.
       settle({ status: 'completed' })
       await drain
     } else {
-      // A late producer completion must not replace the forced failed record or
-      // notify listeners a second time.
+      // A late producer completion must not replace the failure or notify twice.
       settle({ status: 'completed' })
       await tick()
     }
@@ -681,7 +671,7 @@ describe('TaskService disposal', () => {
     await tick()
     const disposedWithoutProducerDone = disposed
     if (!disposedWithoutProducerDone) {
-      // Failure-path cleanup for the pre-fix implementation.
+      // Release the producer if the assertion fails so the test can finish.
       settle({ status: 'completed' })
       await disposal
     } else {

packages/tasks/tool-tasks/README.md

@@ -1,35 +1,35 @@
 # @deepseek-ai/dsh-tool-tasks
 
-The model-facing background task control surface over `ctx.tasks`: three kind-agnostic tools, the completion-notice injection, and the prompt section that teaches the background habit. Loading this plugin calls `ctx.tasks.attachSurface('tool-tasks')`, which is what arms producers' `ctx.tasks.start()`.
+The model-facing control surface for `ctx.tasks`: three kind-independent tools, completion notices, and one background-work prompt section. Loading the plugin attaches the surface required by `ctx.tasks.start()`.
 
 ## Tools
 
-- `task_output(task_id, wait?, timeout_ms?)` — non-blocking read by default (stream kinds: the consuming delta since the previous read; final kinds: the final answer once terminal); every response ends with a `[status: …]` line (generic status + producer detail, e.g. `[status: completed, exit code: 0]`). `wait: true` blocks until settlement, bounded by `waitTimeoutMs`/`maxWaitTimeoutMs` config; a timed-out wait returns `[status: running]` and leaves the task alive.
-- `task_list()` — the caller's tasks, `<id> [<kind>] <status> — <label>` per line.
-- `task_kill(task_id, reason?)` — requests cancellation and returns immediately; the logged `reason` is forwarded to the producer. An already-terminal task is described via a non-consuming snapshot (never eats a pending delta).
+- `task_output(task_id, wait?, timeout_ms?)` reads without blocking by default. Stream tasks return only the next delta; final-output tasks return their result after settlement. Every response ends with `[status: ...]`. `wait: true` waits up to the configured cap and leaves a still-running task alive on timeout.
+- `task_list()` returns caller-visible tasks as `<id> [<kind>] <status> — <label>`.
+- `task_kill(task_id, reason?)` requests cancellation immediately and forwards the logged reason. Terminal tasks return a non-consuming snapshot.
 
-ACP render intent: all three are `generic` cards (`read`/`read`/`execute`) — a task read is not a terminal.
+All three use generic ACP cards: `read` for output and list, `execute` for kill.
 
 ## Completion notices
 
-On `onTaskDone`, injects `background task <id> (<kind>: <label>) finished [status: …]. Read its output with task_output.` through the exact owner `Agent` captured at task start (`agent.inject()` — durable context for the next request, not a wake-up). It never re-resolves a reusable agent/session id to a replacement. Suppressed when the snapshot is `reported` (the model already killed it, or a read/wait returned the end) — never a redundant "finished"; the disposed-owner race is contained.
+An unreported completion injects `background task <id> (<kind>: <label>) finished [status: ...]. Read its output with task_output.` into the exact owner's session. Injection is durable context for the next request, not a wake-up. A kill or terminal read/wait marks delivery reported and suppresses the redundant notice; owner-disposal races are contained.
 
 ## Config
 
 | key | default | meaning |
 |---|---|---|
-| `waitTimeoutMs` | `30000` | wait duration when `task_output` sets `wait` without `timeout_ms` |
-| `maxWaitTimeoutMs` | `600000` | hard cap; larger model-supplied `timeout_ms` values are clamped |
+| `waitTimeoutMs` | `30000` | wait used when `wait: true` omits `timeout_ms` |
+| `maxWaitTimeoutMs` | `600000` | cap for model-supplied waits |
 
-A config whose default exceeds the cap fails loud at load.
+A default above the cap fails at load.
 
 ## Model Experience
 
 ### System prompt
 
-**What the model sees**: Every request in this plugin's registration scope contains the background-task guidance below. Agent-scoped tool filtering can hide the control schemas without removing this independently registered section.
+**What the model sees**: Every request in this plugin's registration scope contains this guidance. Agent-scoped tool filtering may hide the tools without removing the independently registered prompt section.
 
-**Token effect**: Small fixed input cost per request while the plugin is active.
+**Token effect**: Small fixed input cost per request while active.
 
 #### Background-task guidance
 
@@ -39,18 +39,18 @@ Track every background task id you start. You are notified in-session when a tas
 
 ### Tool schemas
 
-**What the model sees**: The model sees the generated [`task_output`, `task_list`, and `task_kill` schemas](../../../docs/tool-catalog.md#deepseek-aidsh-tool-tasks) while this control surface is visible.
+**What the model sees**: The generated [`task_output`, `task_list`, and `task_kill` schemas](../../../docs/tool-catalog.md#deepseek-aidsh-tool-tasks) while this surface is visible.
 
 **Token effect**: Fixed schema cost on each request where the tools are visible.
 
-### Task results and notices
+### Results and notices
 
-**What the model sees**: Reads return a producer-owned output delta or `(no new output)`, followed by `[status: <status>]` with optional producer detail. Listing returns `(no background tasks)` or one `<id> [<kind>] <status> — <label>` line per visible task. Kill returns `requested cancellation of task <id>` or `task <id> had already finished [status: ...]`. An unreported owned completion injects exactly `background task <id> (<kind>: <label>) finished [status: ...]. Read its output with task_output.`
+**What the model sees**: Reads return output or `(no new output)` followed by `[status: <status>]` and optional detail. An empty list returns `(no background tasks)`. Kill returns `requested cancellation of task <id>` or the existing terminal status. Unreported owned completion uses the notice above.
 
-**Token effect**: Results and completion notices are retained in the parent session until compaction; stream reads consume their cursor and do not repeat prior output.
+**Token effect**: Results and notices remain in parent history until compaction. Stream reads do not repeat consumed output.
 
 ## Known Limitations and Deferred Work
 
-- **Completion notices do not wake idle agents** — they become durable context for the next request; callers needing an immediate result must use `task_output`.
-- **Stream reads are single-consumer** — this control surface exposes the task runtime's one consuming cursor rather than independent observers.
-- **Unowned tasks have no session fence** — deployments exposing background starts outside an agent must provide their own caller policy or avoid ownerless tasks.
+- **Completion notices do not wake idle agents** — callers needing an immediate result must use `task_output`.
+- **Stream reads are single-consumer** — independent observers need another runtime API.
+- **Unowned tasks have no session fence** — external surfaces must supply caller policy or avoid them.

packages/tasks/tool-tasks/src/index.ts

@@ -1,21 +1,8 @@
 /**
- * The model-facing background task control tools: `task_output`, `task_list`,
- * `task_kill`. Kind-agnostic — a background bash command and a background
- * subagent read, list, and die through the same three schemas — with every
- * task concern (ids, isolation, cursors, settlement) behind the `ctx.tasks`
- * registry (`@deepseek-ai/dsh-tasks`).
- *
- * This plugin IS the control surface: it calls `ctx.tasks.attachSurface()` on
- * load, which is what arms producers' `ctx.tasks.start()` (the runtime's
- * preflight refuses background work while no surface could collect or stop it).
- *
- * Completion notices: when a task settles, a short notice is injected into
- * the owning agent's session (`agent.inject()` — durable context for the NEXT
- * model request, not a wake-up). A task whose terminal state the model
- * already saw (`snapshot.reported` — an explicit kill, or a read/wait that
- * returned the end) is suppressed, so the model never gets a redundant
- * "finished" for work it just collected.
- *
+ * Model-facing `task_output`, `task_list`, and `task_kill` tools over
+ * `ctx.tasks`. Loading the plugin attaches the control surface required by
+ * producers. It also injects unreported completions as durable context for the
+ * owner's next request; notices do not wake idle agents.
  * @module @deepseek-ai/dsh-tool-tasks
  */
 
@@ -30,7 +17,7 @@ import type {} from '@deepseek-ai/dsh-system-prompt'
 export const name = 'tool-tasks'
 export const inject = ['tools', 'tasks', 'systemPrompt']
 
-/** Config: the `task_output` wait bounds (defaulted, capped — never hardcoded). */
+/** Configures bounded `task_output` waits. */
 export interface Config {
   /** Wait duration applied when `task_output` sets `wait` without `timeout_ms` (default 30s). */
   waitTimeoutMs?: number
@@ -44,12 +31,9 @@ export const Config: z<Config> = z.object({
 })
 
 /**
- * Render a snapshot's status line — generic status plus the producer's
- * kind-specific detail: `[status: completed, exit code: 0]`,
- * `[status: failed, max-tokens]`, `[status: running]`. Exported for tests
- * and for producers that want a consistent line in their own results.
- * @param snapshot - the task state to render.
- * @returns the bracketed status line.
+ * Render generic status with optional producer detail.
+ * @param snapshot - task state to render.
+ * @returns a bracketed status line.
  */
 export function statusLine(snapshot: TaskSnapshot): string {
   return snapshot.detail !== undefined
@@ -57,11 +41,7 @@ export function statusLine(snapshot: TaskSnapshot): string {
     : `[status: ${snapshot.status}]`
 }
 
-/**
- * Reject an empty `task_id`. Type/presence come from the SchemaSpec
- * validation; only the non-empty constraint, which the DSL cannot express,
- * is checked here.
- */
+/** Validate the non-empty constraint that SchemaSpec cannot express. */
 function validateTaskId(value: string): TaskId {
   if (value.length === 0) {
     throw new Error(`invalid task_id: expected a non-empty string, got ${JSON.stringify(value)}`)
@@ -69,7 +49,7 @@ function validateTaskId(value: string): TaskId {
   return TaskId(value)
 }
 
-/** Pending-state presentation shared by the three control tools (generic cards by design — a task read/kill is not a terminal). */
+/** Pending presentation shared by the three generic task controls. */
 function presentTaskCall(title: string, kind: 'read' | 'execute', rawInput?: string): GenericCallView {
   return { card: 'generic', title, kind, ...rawInput !== undefined ? { rawInput } : {} }
 }
@@ -81,24 +61,18 @@ export function apply(ctx: Context, config: Config): void {
     throw new Error(`tool-tasks: waitTimeoutMs (${waitDefault}) exceeds maxWaitTimeoutMs (${waitCap})`)
   }
 
-  // The registry's misconfiguration fence: producers can register background
-  // work only while a surface capable of collecting/stopping it is attached.
+  // Producers may start work only while a control surface is attached.
   ctx.tasks.attachSurface('tool-tasks')
 
-  // The cross-call HABIT the per-tool descriptions cannot carry. Order 106:
-  // right after tool:bash (105), before deployment product sections.
+  // Cross-call guidance follows the bash section and precedes product sections.
   ctx.systemPrompt.section({
     name: 'tool:tasks',
     order: 106,
     text: 'Track every background task id you start. You are notified in-session when a task finishes — do not busy-poll or sleep on one; keep working on independent steps and do not duplicate a running task\'s work. Before giving a final answer, collect every still-relevant task with task_output (set wait: true only when you are genuinely blocked on it), and task_kill tasks that stopped mattering.',
   })
 
-  // Background completion → inject a notice through the exact lifecycle owner.
-  // Re-resolving by a reusable agent/session id could target a replacement
-  // while the old owner's scope is still unwinding.
+  // Use the exact lifecycle owner; reusable ids could resolve to a replacement.
   ctx.tasks.onTaskDone((snapshot, owner) => {
-    // A reported terminal state was already surfaced by an explicit
-    // read/wait/kill response — a notice would be a redundant "finished".
     if (snapshot.reported || owner === undefined) return
     try {
       owner.inject(
@@ -106,9 +80,7 @@ export function apply(ctx: Context, config: Config): void {
         { source: { kind: 'plugin', plugin: 'tool-tasks' } },
       )
     } catch (error: unknown) {
-      // The ONE expected failure: the agent was disposed between settlement
-      // and this injection (inject throws `agent "<id>" is disposed`). That
-      // race is benign — drop the notice. Anything else must surface.
+      // Disposal may win the race after settlement; other injection failures surface.
       if (error instanceof Error && error.message.includes('is disposed')) return
       throw error
     }
@@ -116,16 +88,11 @@ export function apply(ctx: Context, config: Config): void {
 
   ctx.tools.register(defineTool({
     name: 'task_output',
-    description: 'Read output/status from a background task (started by a tool with `run_in_background`). '
-      + 'Stream tasks (bash) return only output produced since your previous task_output call; '
-      + 'final-output tasks (subagent) return the final answer once the task finishes. '
-      + 'Every response ends with a [status: ...] line. Non-blocking by default; '
-      + 'set `wait: true` to block until the task finishes (bounded by a capped timeout) when you are genuinely blocked on its result.',
-    // Deliberately NO ToolDefinition.timeoutMs: the timeout-policy plugin
-    // replaces a timed-out call with a structured TOOL_TIMEOUT failure, but a
-    // timed-out wait here is a SUCCESS that reports [status: running] — the
-    // task's state must reach the model either way, so the wait bounds its
-    // own deadline (waitTimeoutMs/maxWaitTimeoutMs) via ctx.tasks.wait.
+    description: 'Read a background task. Stream tasks return only output since the previous read; '
+      + 'final-output tasks return their result after settlement. Every response ends with '
+      + '`[status: ...]`. Reads are non-blocking unless `wait: true`, which waits up to the configured cap.',
+    // A timed-out wait returns task state rather than a TOOL_TIMEOUT error, so
+    // this tool owns its deadline instead of using ToolDefinition.timeoutMs.
     parameters: {
       task_id: { type: 'string', required: true, description: 'Task id returned by the tool that started the background work.' },
       wait: { type: 'boolean', description: 'Block until the task reaches a terminal status or the timeout expires. A timed-out wait returns [status: running] and leaves the task alive.' },
@@ -149,8 +116,6 @@ export function apply(ctx: Context, config: Config): void {
     name: 'task_list',
     description: 'List your background tasks (running and finished) with their ids, kinds, and statuses.',
     parameters: {},
-    // execute is synchronous (registry reads + string shaping) but the
-    // ToolDefinition contract wants a Promise — hence resolve(), not async.
     execute(_args, exec) {
       const tasks = ctx.tasks.list(exec.agent)
       const text = tasks.length === 0
@@ -172,8 +137,7 @@ export function apply(ctx: Context, config: Config): void {
       const id = validateTaskId(args.task_id)
       const result = ctx.tasks.kill(id, exec.agent, args.reason)
       if (result === 'already-terminal') {
-        // ctx.tasks.get, NOT .read: a read would consume a stream task's
-        // pending delta just to describe the terminal state.
+        // A snapshot describes terminal state without consuming pending output.
         const snapshot = ctx.tasks.get(id, exec.agent)
         return Promise.resolve([{ type: 'text', text: `task ${id} had already finished ${statusLine(snapshot)}` }])
       }

packages/ui/acp/README.md

@@ -42,7 +42,7 @@ Forward and reverse indexes route every event, prompt, cancel, and approval to o
 
 When `ctx.permission` is composed, the bridge advertises one `permission` select in `session/new` and `session/load`. Options come from the deployment's preset table; the current value comes from the session fold, with switch-away-only `custom` for unmatched knobs. `session/set_config_option` accepts advertised presets and writes both sandbox-mode and approval-policy events through `PermissionService.set()`. Open-turn switches append immediately; idle switches overlay responses and anchor at the next `agent/prompt-submit`, before request assembly. A crash before anchoring restores the durable fold. See the [sandbox RFC](../../../docs/rfc/implemented/feature/2026-07-06-sandbox.md), [`dsh-permission`](../permission/README.md), and [protocol matrix](acp-feature-support.md#6-session-config-options).
 
-Background-task isolation rides on the `ctx.tasks` runtime (`dsh-tasks`): task ids are global and predictable, so every read/kill/wait/list is fenced to the owning agent's session (`session.header.id`), and one session's agent can't read or kill another's task through `task_output`/`task_kill`. Ownership is by session token, not `Agent` object identity — a different `Agent` object on the same session may access the task — and because the registration lives in the tasks service it survives a producer-plugin HMR reload.
+The shared [`ctx.tasks` runtime](../../tasks/tasks/) fences access to predictable task ids by the owning session; ACP sessions therefore cannot read or stop one another's background work.
 
 ## Per-session cwd
 

packages/util/brand/README.md

@@ -17,10 +17,10 @@ export function SessionId(id: string): SessionId {
 }
 ```
 
-Construction goes through the per-id factory in the OWNING package (a plain cast inside — zero runtime cost). Comparison, logging, JSON serialization, and the wire format all behave exactly as for an ordinary string; the brand is erased at compile time.
+Construction goes through the per-id factory in the owning package. Comparison, logging, JSON serialization, and the wire format behave as for an ordinary string; the brand is erased at compile time.
 
 ## Policy: brand ids that cross package boundaries
 
-A package brands the ids it OWNS — `CallId` in `dsh-llm` (tool-call correlation), `SessionId` in `dsh-session`, `AgentId` in `dsh-agent`, `TaskId` in `dsh-tasks`. Branding is for ids that cross package boundaries and could plausibly be confused; **not every string needs a brand.**
+A package brands the ids it owns — `CallId` in `dsh-llm`, `SessionId` in `dsh-session`, `AgentId` in `dsh-agent`, and `TaskId` in `dsh-tasks`. Brand cross-package ids that could plausibly be confused; not every string needs one.
 
-This package owns ONLY the primitive — no concrete id, no runtime code beyond the (erased) type. Keeping the primitive dependency-free is the point: a capability package can brand its ids without depending on an unrelated package. `dsh-tasks`, for example, brands `TaskId` by depending on `dsh-brand` alone — it never pulls in `dsh-llm` (or `dsh-session`) just to reach `Branded`.
+This package owns only the primitive. Keeping it dependency-free lets `dsh-tasks`, for example, brand `TaskId` without importing an unrelated capability package merely to reach `Branded`.