diff --git a/.agents/skills/dsh-code-review/SKILL.md b/.agents/skills/dsh-code-review/SKILL.md
index 3502e4454a..2b562cc321 100644
--- a/.agents/skills/dsh-code-review/SKILL.md
+++ b/.agents/skills/dsh-code-review/SKILL.md
@@ -19,19 +19,26 @@ description: Use when reviewing a pull request in the deepseek-harness repo —
## Blocking requirements
-1. **Docs match the code.** Config, defaults, errors, wire fields, events, and public behavior update the package README and JSDoc in the same diff. Comments state non-obvious contracts; flag implementation narration, test walkthroughs, review history, and duplicated rationale for deletion or a link to their one home.
-2. **Core type docs match.** Changes to spine or seam vocabulary update the appropriate [core-data-structures](../../../docs/core-data-structures/core.md) page and any `type-equiv` entry. Internal types need no catalog entry.
-3. **Registrations clean up.** A new registry contribution has a test that disposes its owner and observes removal.
-4. **Required gates pass.** Trust the [current readiness sequence](../../../AGENTS.md#run-the-ci-gates-locally-before-marking-a-pr-ready) and `pnpm run check:pre-push` for their enforced inventory; review the semantic gaps they cannot detect.
+1. **New prose receives semantic review.** Use [dsh-prose-standard](../dsh-prose-standard/SKILL.md) to critically review every added or changed Markdown passage, JSDoc, comment, prompt, description, diagnostic, and visible string. Verify required coverage, accuracy, placement, and editorial quality against the owning code or behavior; automated checks do not establish those properties.
+2. **Docs match the code.** Config, defaults, errors, wire fields, events, and public behavior update the package README and JSDoc in the same diff. Comments state non-obvious contracts; flag implementation narration, test walkthroughs, review history, and duplicated rationale for deletion or a link to their one home.
+3. **Core type docs match.** Changes to spine or seam vocabulary update the appropriate [core-data-structures](../../../docs/core-data-structures/core.md) page and any `type-equiv` entry. Internal types need no catalog entry.
+4. **Registrations clean up.** A new registry contribution has a test that disposes its owner and observes removal.
+5. **Required gates pass.** Trust the [current readiness sequence](../../../AGENTS.md#run-the-ci-gates-locally-before-marking-a-pr-ready) and `pnpm run check:pre-push` for their enforced inventory; review the semantic gaps they cannot detect.
## Manual checks
- **Intent and seam contracts:** trace both sides of every changed interface. Confirm the implementation matches the PR and any RFC, including errors, cancellation, ownership, and disposal.
-- **Lifecycle and concurrency:** for async setup, callbacks, processes, or teardown, apply [defensive-patterns.md](../../../docs/defensive-patterns.md). Check races before publication, cancellation during awaits, independent error reporting, callback containment, and quiescent disposal.
+- **Lifecycle and concurrency:** for async setup, callbacks, processes, or teardown, apply [defensive-patterns.md](../../../docs/defensive-patterns.md). Check races before publication, cancellation during awaits, independent error reporting, callback containment, ownership before reentry, complete detach cleanup, and quiescent disposal.
- **Capability shape:** a swappable capability follows the interface / implementation / consumer split. Consumers depend on the interface, not a backend.
+- **Scope, ownership, and necessity:** tie each abstraction, state machine, option, defensive copy, and compatibility path to a current contract or production consumer. Challenge unrelated features, speculative generality, and behavior placed outside its owning plugin or service.
- **Configuration:** deployment-varying timeouts, caps, models, URLs, paths, and retry counts are validated `Config` fields, not literals or `DEFAULT_*` constants.
+- **Enforcement boundaries:** hidden schema fields, filtered prompts, facades, wrappers, and listener ordering are not authoritative enforcement when direct or alternate callers can bypass them. Exercise denial paths at the boundary that actually executes the operation.
+- **Borrowed and derived state:** determine whether retained caller-owned values are borrowed or snapshotted by contract; do not demand copies at typed same-process seams. Materialize mutable values that cross queues, model/tool JSON, durable logs or files, workers, processes, or wire boundaries. Commit notifications and derived state only at the documented success boundary, and trace caches, prompts, UI echoes, replay, and query views to one authoritative source.
+- **Bounds cover the final operation:** verify byte, token, item, and time limits at the boundary that owns the complete emitted or retained result, including wrappers and metadata. Probe tiny limits, exact thresholds, oversized single chunks, and multibyte text for byte limits.
- **Real entry path:** tests exercise the shipped Loader, bin, worker, ACP bridge, or subprocess where relevant. A hand-mounted plugin does not catch Loader export-shape failures; a function plugin must named-export its namespace and have no default export.
- **Test strength:** assertions fail on the intended regression and verify external state, logs, events, or disposal rather than restating the implementation or trusting an agent's report. Coverage is necessary but not evidence that the scenario is correct.
+- **Changed checks have a negative control:** a new automated check, or a changed acceptance path in one, has a deliberately invalid case that reaches the real top-level runner and fails for the intended rule; a green happy path does not prove the check is wired.
+- **Implemented RFCs match shipped reality:** when a PR implements a proposed RFC, move and rewrite it as present-tense shipped state in the same diff, then verify paths, names, and mechanisms against the implementation.
- **Transcript changes:** editor-visible or model-visible changes update snapshots or explain why no snapshot applies. Review golden diffs as behavior changes, not formatting noise.
- **Bilingual changes:** compare meaning and terminology on both sides; a green pairing hash does not prove translation quality.
diff --git a/.agents/skills/dsh-translate-docs/SKILL.md b/.agents/skills/dsh-translate-docs/SKILL.md
index 553cf6f9d1..d935c5c4b7 100644
--- a/.agents/skills/dsh-translate-docs/SKILL.md
+++ b/.agents/skills/dsh-translate-docs/SKILL.md
@@ -14,7 +14,7 @@ These are authoritative; read them at the source so this skill never drifts out
- **[docs/i18n/README.md](../../../docs/i18n/README.md)** — the pairing contract: the three-file pair (`foo.md`, `foo.zh.md`, `foo.i18n.yaml`), the consistency record's both-side blob hashes, the language-switcher lines, scope/exclusions, and the rollout manifest.
- **[docs/i18n/translation-rules.md](../../../docs/i18n/translation-rules.md)** — how to translate: faithfulness, structure preservation, terminology discipline, typography (MUST/SHOULD levels).
- **[docs/i18n/terminology.md](../../../docs/i18n/terminology.md)** — the terminology table, binding in both directions. Load it BEFORE translating, not when a term feels uncertain; the terms you don't notice are the ones that drift.
-- **[docs/i18n/translation-prompt.md](../../../docs/i18n/translation-prompt.md)** — the automated pipeline's machine-consumed template. Agents using this skill do not render it; keep rules shared with this skill synchronized.
+- **[docs/i18n/translation-prompt.md](../../../docs/i18n/translation-prompt.md)** — the automated pipeline's machine-consumed template. Agents using this skill do not render it; the renderer injects `translation-rules.md` so rules have only one home.
- **[dsh-prose-standard](../dsh-prose-standard/SKILL.md)** — required prose coverage and editorial judgment. Apply it to both sides without adding or dropping source propositions.
## Find the work
@@ -42,8 +42,9 @@ Do not process every file the same way:
- **Pass 1 — write, don't transpose.** Read a semantic unit, then restate it as a native technical author in the nearest [style sample's](../../../docs/i18n/style-samples.md) register. Preserve the required frame without forcing sentence-by-sentence correspondence.
- **Pass 2 — verify against the source, clause by clause.** Fidelity is checked here, not written in: confirm nothing was added or dropped, every term follows the table, and each code span survived verbatim. Fix by rewriting the sentence natively, not by patching words into it.
- Write only the final text to the file, never drafts or notes.
-- Every term in [terminology.md](../../../docs/i18n/terminology.md) renders exactly as specified, in both directions, including first-occurrence annotations. A term the table misses: translate only with a citable precedent from a major Chinese OSS/vendor doc; otherwise keep the English and add it to the PR's 「待定术语」 list with your suggested rendering. Never invent a rendering inline — that decision belongs to a human and then to the table.
+- Every term in [terminology.md](../../../docs/i18n/terminology.md) renders exactly as specified. For a Chinese target, use the Chinese and first-occurrence columns; an unlisted term needs a citable Chinese OSS/vendor precedent or stays English under 「待定术语」. For an English target, use the English column and an established English technical term; preserve an ambiguous source term with a short gloss and list it as pending. Never invent a rendering inline.
- Code blocks are byte-identical across the pair, comments included. Relative links keep their `.md` targets; only the switcher line links `.zh.md`.
+- The pairing gate checks heading depths, fenced blocks, table row and column counts, list kinds, ordered-list starts, list item counts, and link targets. In Pass 2, manually verify list and table order, noncanonical list numbering, inline code, emphasis, meaning, terminology, and tone.
## Finish the pair
@@ -51,9 +52,9 @@ Do not process every file the same way:
2. Record consistency: `pnpm run verify-translation-pairing --write` recomputes and records both sides' full blob hashes in `foo.i18n.yaml`. The yaml diff in your PR is the reviewable statement "I confirmed these two say the same thing" — only run it after you actually have.
3. New batch landed? Add the `.md` paths to `required` in [scripts/translation-pairing.manifest.json](../../../scripts/translation-pairing.manifest.json) so the gate ratchets forward.
-## Verify — the gate, not your eyes
+## Verify the mechanical and human halves
-Run `pnpm run verify-translation-pairing`, then the rest of the Markdown gates (`pnpm run verify-md-wrap && pnpm run verify-md-links`, or full `pnpm run doc-sync` before the PR). Fix what they report; do not hand-check what they cover. What they can NOT check — whether the two sides truly say the same thing, terminology judgment calls, tone — is exactly what the PR reviewer will read for, so keep the PR reviewable: state which pairs are new vs minimally updated, and list 「待定术语」 prominently.
+Run `pnpm run verify-translation-pairing`, then the rest of the Markdown gates (`pnpm run verify-md-wrap && pnpm run verify-md-links`, or full `pnpm run doc-sync` before the PR). Fix what they report and manually verify the obligations listed in Pass 2 that the gates do not encode. Keep the PR reviewable: state which pairs are new versus minimally updated and list 「待定术语」 prominently.
## How to respond to translation review
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 884a0417e3..bac25b07cb 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -160,10 +160,9 @@ jobs:
- name: Run complete keyless Python suite
run: uv run --python 3.10 --group test --project python/sdk pytest
- # Windows build lane: install + `pnpm run build` (tsc -b + tsdown) on native
- # Windows. Windows path/shell support is still partial, so this lane covers
- # the build surface only — tests and gates are not run here yet. Wired into
- # all-checks-passed so a native-Windows build regression cannot land silently.
+ # Blocking Windows build lane: keep the already-green native build protected
+ # while the broader observational gate matrix below exposes the remaining
+ # portability work without blocking mainline merges.
windows-build:
runs-on: windows-2025
name: windows / build
@@ -183,11 +182,89 @@ jobs:
- name: Build (tsc -b + tsdown)
run: pnpm run build
+ # Observational, non-blocking Windows static, lint, and artifact lanes. Coverage
+ # and snapshot stay Linux-only until their platform-specific runtime failures
+ # have dedicated support. Run the gates from native PowerShell: an MSYS parent
+ # would change the environment being measured. This job intentionally stays
+ # out of all-checks-passed.needs.
+ windows-gates:
+ continue-on-error: true
+ runs-on: windows-2025
+ name: windows node 24 / ${{ matrix.lane }}
+ env:
+ DSH_GATE_CONCURRENCY: ${{ matrix.gate_concurrency }}
+ DSH_PUBLINT_CONCURRENCY: ${{ matrix.publint_concurrency }}
+ DSH_ESLINT_CACHE: ${{ matrix.eslint_cache }}
+ strategy:
+ fail-fast: false
+ matrix:
+ include:
+ - lane: static
+ command: pnpm run check:ci:static
+ gate_concurrency: '4'
+ publint_concurrency: '8'
+ eslint_cache: ''
+ - lane: lint
+ command: pnpm run check:ci:lint
+ gate_concurrency: '1'
+ publint_concurrency: '8'
+ eslint_cache: '1'
+ - lane: artifacts
+ command: pnpm run check:ci:artifacts
+ gate_concurrency: '3'
+ publint_concurrency: '8'
+ eslint_cache: ''
+ steps:
+ - uses: actions/checkout@v6
+
+ - name: Enable Developer Mode (symlink support)
+ shell: pwsh
+ run: >-
+ reg add "HKLM\SOFTWARE\Microsoft\Windows\CurrentVersion\AppModelUnlock"
+ /t REG_DWORD /f /v "AllowDevelopmentWithoutDevLicense" /d "1"
+
+ - uses: actions/setup-node@v6
+ with:
+ node-version: ${{ env.PRIMARY_NODE_VERSION }}
+
+ - name: Enable corepack (pnpm)
+ shell: pwsh
+ run: corepack enable
+
+ - name: Resolve pnpm store path
+ id: pnpm-store
+ shell: pwsh
+ run: '"path=$(pnpm store path --silent)" >> $env:GITHUB_OUTPUT'
+
+ - uses: actions/cache@v4
+ with:
+ path: ${{ steps.pnpm-store.outputs.path }}
+ key: ${{ runner.os }}-node-${{ env.PRIMARY_NODE_VERSION }}-pnpm-${{ hashFiles('pnpm-lock.yaml') }}
+ restore-keys: |
+ ${{ runner.os }}-node-${{ env.PRIMARY_NODE_VERSION }}-pnpm-
+
+ - name: Install (immutable)
+ shell: pwsh
+ run: pnpm install --frozen-lockfile
+
+ - uses: actions/cache@v4
+ if: matrix.lane == 'lint'
+ with:
+ path: .cache/eslint
+ key: ${{ runner.os }}-node-${{ env.PRIMARY_NODE_VERSION }}-eslint-${{ hashFiles('pnpm-lock.yaml', 'eslint.config.mjs', 'tsconfig.json', 'packages/*/*/tsconfig.json', 'examples/*/tsconfig.json') }}
+ restore-keys: |
+ ${{ runner.os }}-node-${{ env.PRIMARY_NODE_VERSION }}-eslint-
+
+ - name: Run gates
+ shell: pwsh
+ run: ${{ matrix.command }}
+
# Single stable required check for branch protection: require "all checks
# passed" instead of enumerating matrix legs whose names change as lanes and
- # node versions evolve. Every other job in THIS workflow must be listed in
- # `needs` (`needs` cannot reach across workflow files; e2e.yml stays its own
- # check). `if: always()` is load-bearing: without it a failed dependency
+ # node versions evolve. Every blocking job in THIS workflow must be listed in
+ # `needs`; explicitly observational jobs such as windows-gates stay out
+ # (`needs` cannot reach across workflow files; e2e.yml stays its own check).
+ # `if: always()` is load-bearing: without it a failed dependency
# would SKIP this job, and GitHub counts a skipped required check as passing
# — so this job always runs and fails on any non-success result, including
# 'cancelled' and 'skipped'.
diff --git a/README.i18n.yaml b/README.i18n.yaml
index 37a95ccdac..790812344d 100644
--- a/README.i18n.yaml
+++ b/README.i18n.yaml
@@ -3,4 +3,4 @@
# after editing either side, bring the other along and re-record with:
# pnpm run verify-translation-pairing --write
README.md: 53dd3896eb15800125673e7c44f7de02daca9376
-README.zh.md: 2119dabf0ae2d2e16e274e44fda7cbbaec146dc9
+README.zh.md: ab826f62658248249ec18c57b35c0065c0f909d1
diff --git a/README.zh.md b/README.zh.md
index 2119dabf0a..ab826f6265 100644
--- a/README.zh.md
+++ b/README.zh.md
@@ -2,7 +2,7 @@
[English](README.md) | 中文
-**DeepSeek Harness SDK** 是用于构建 agent harness 的 SDK，采取基于插件的设计。
+**DeepSeek Harness SDK** 是用于构建 agent harness（智能体框架）的 SDK，采取基于插件的设计。
## 开发
diff --git a/docs/architecture.md b/docs/architecture.md
index 2fbea9120b..e4990dec82 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -24,7 +24,7 @@ A harness is one [Cordis](cordis-primer.md) context. Packages add services (`ctx
| ctx key | Package family | Role |
|---|---|---|
| `ctx.llm` | [`llm/`](../packages/llm/README.md) | adapter registry and streaming model calls |
-| `ctx.tokenMeter` | [`llm/token-meter`](../packages/llm/token-meter/README.md) | replay-aware per-model request and surface pressure |
+| `ctx.tokenMeter` | [`llm/token-meter`](../packages/llm/token-meter/README.md) | replay-aware request/surface pressure per model |
| `ctx.bash` | [`bash/`](../packages/bash/README.md) | foreground/background command execution |
| `ctx.sandbox` | [`sandbox/`](../packages/sandbox/README.md) | same-world process confinement (argv wrapping, per-call policy) |
| `ctx.codeRuntime` | [`code-runtime/`](../packages/code-runtime/README.md) | model-written program execution |
@@ -33,6 +33,7 @@ A harness is one [Cordis](cordis-primer.md) context. Packages add services (`ctx
| `ctx.web` | [`web/`](../packages/web/README.md) | search/fetch provider registries |
| `ctx.compact` | [`compact/`](../packages/compact/README.md) | session-log compaction |
| `ctx.subagents` | [`subagent/`](../packages/subagent/README.md) | named delegation providers |
+| `ctx.tasks` | [`tasks/`](../packages/tasks/README.md) | background task registry + generic `task_*` control tools |
| `ctx.workflows` | [`workflow/`](../packages/workflow/README.md) | script-driven multi-agent orchestration |
| `ctx.sessionPersistence` | [`session-persistence/`](../packages/session-persistence/README.md) | durable storage for session logs |
| `ctx.sessionQuery` | [`session-query/`](../packages/session-query/README.md) | live-preferred logical-corpus and exact-event reads |
@@ -86,7 +87,7 @@ forever:
otherwise:
'assistant/chunk'
agent/step-result
- 'assistant/message' (transformed content, or an empty successful-call anchor if step-result rejects)
+ 'assistant/message' (transformed content or empty success anchor after step-result rejection)
each tool call:
'tool/call'
tools/pre-execute -> monotonic guards -> tools/execute -> tools/post-execute -> tools/result
@@ -117,11 +118,11 @@ Every session event is turn-enclosed. Reload preserves a crashed tail and closes
### Agent Handles
-`ctx.agents` owns live agents and returns `AgentHandle { agent, dispose() }`. Plugins use `send()`, `steer()`, `inject()`, `cancel()`, and `whenIdle()`. The caller fiber and factory provider structurally co-own programmatic lifecycles; the consumer handle is the sole non-structural teardown capability, and all owners share one awaited disposer.
+`ctx.agents` owns live agents and returns `AgentHandle { agent, dispose() }`. Plugins drive `Agent` through `send()`, `steer()`, `inject()`, `cancel()`, and `whenIdle()`. The caller fiber and factory provider structurally co-own programmatic lifecycles; the consumer handle is the sole non-structural teardown capability, and all owners share one awaited disposer.
### Agent Scope
-Each agent owns `agent.ctx`; its registrations shadow globals, receive only that agent's dispatches, and unwind on disposal. `CreateAgentOptions.setup(agentCtx)` composes it before publication. Typed resolvers derive carrier checks from merged events and `scopeTarget` ([semantic gates](rfc/implemented/process/2026-07-14-typescript-program-backed-semantic-gates.md), [agent scope](rfc/implemented/architecture/2026-07-08-agent-scope-contexts.md), [subagent controls](rfc/implemented/feature/2026-07-12-subagent-persona-tool-filter-and-depth.md)).
+Each agent owns `agent.ctx`; its registrations shadow globals, receive only that agent's dispatches, and unwind on disposal, including awaited background-task cleanup. `CreateAgentOptions.setup(agentCtx)` composes it before publication. Typed resolvers derive carrier checks from merged events and `scopeTarget` ([semantic gates](rfc/implemented/process/2026-07-14-typescript-program-backed-semantic-gates.md), [agent scope](rfc/implemented/architecture/2026-07-08-agent-scope-contexts.md), [subagent controls](rfc/implemented/feature/2026-07-12-subagent-persona-tool-filter-and-depth.md)).
## State
@@ -135,7 +136,7 @@ Durability is a plugin concern. Persistence backends buffer synchronous `session
### Model Content
-Messages are arrays of typed content blocks (`text`, `reasoning`, `tool-call`, `tool-result`). The union derives from the merge-extensible `ContentBlockMap`; the same pattern types `MessageSource`, `FinishReason`, `TurnTrigger`, and `TurnEndReason`. New block types are coordinated across adapters, UI bridges, token metering, and persistence, so block types remain a repo-wide contract. Replay measurement types are cataloged in [token-meter.md](core-data-structures/token-meter.md).
+Messages are arrays of typed content blocks (`text`, `reasoning`, `tool-call`, `tool-result`). The union derives from the merge-extensible `ContentBlockMap`; the same pattern types `MessageSource`, `FinishReason`, `TurnTrigger`, and `TurnEndReason`. New block types require coordinated adapter, UI, token-meter, and persistence changes; replay measurement types live in [token-meter.md](core-data-structures/token-meter.md).
Streaming is a raw chunk protocol (`block-start` through `finish`) with `BlockAssembler` as the shared chunk-to-block assembler. The loop logs raw chunks while assembling them for dispatch. `LlmAdapter` is the provider seam: subclass, implement `stream()`, and register with `ctx.llm.registerAdapter(models, adapter)`. StreamChunk conventions live in [llm-streaming.md](core-data-structures/llm-streaming.md).
@@ -160,6 +161,7 @@ New behavior should attach to a documented extension point; changing the shipped
| Add a model provider | register an adapter on `ctx.llm` |
| Add a model-facing capability | register a tool on `ctx.tools`; schemas flow into prompt assembly |
| Add command execution | implement and register a `ctx.bash` backend |
+| Add a long-running/background capability | register the work on `ctx.tasks`; the generic `task_*` tools collect/stop it |
| Add filesystem access or policy | implement a `ctx.fs` provider or listen on `fs/*` policy events |
| Confine spawned processes | a `ctx.sandbox` backend; consumers wrap their argv before spawning |
| Intercept prompts, requests, model completion/failure, tool use, or continuation | listen on the relevant `agent/*` or `tools/*` event; use serial `agent/turn-stop` for a monotonic terminal stop |
diff --git a/docs/capability-seams.md b/docs/capability-seams.md
index d20c788df9..0e25b973e6 100644
--- a/docs/capability-seams.md
+++ b/docs/capability-seams.md
@@ -77,6 +77,9 @@ flowchart LR
pkg_subagent_fork["subagent-fork"]
pkg_subagent_acp["subagent-acp"]
pkg_subagent_mock["subagent-mock"]
+ pkg_tasks["tasks"]
+ svc_tasks["ctx.tasks
+ /** Generic background-task control-tool config forwarded through agent-core. */
+ toolTasks?: NonNullable
}
```
@@ -86,13 +90,19 @@ Source: [`packages/core/agent-loop/src/index.ts:322`](../packages/core/agent-loo
```ts config-catalog
/**
- * Bundle config: each field forwarded verbatim to the child that owns it — `agents` to the
- * agent loop (an app that pre-creates no agents, like the ACP bridge, omits it),
- * `persona` and `toolOrder` to the system-prompt plugin (the deployment's persona section and
- * the explicit model-facing tool order), the `tools` object to the tool registry (its
- * presentation `mode`), and `skills` to the skill registry/local provider/tool consumer.
- * The schema intersects the owners' schemas, which supply defaults for every
- * optional input and keep validation from drifting.
+ * Bundle config: each field forwarded verbatim to the child that owns it —
+ * `agents` to the agent loop (an app that pre-creates no agents, like the ACP
+ * bridge, simply omits it), `persona` and `toolOrder` to the system-prompt
+ * plugin (the deployment's persona section and the explicit model-facing tool
+ * order), the `tools` object to the tool registry (its presentation `mode`),
+ * and `toolBash`/`toolTasks` to the two model-facing tool plugins this bundle
+ * owns. Producer opt-in stays producer-local: `toolBash` configures bash only;
+ * future background-capable tools remain independently composed plugins.
+ * Every field is optional INPUT here because each owner's schema
+ * supplies the default (`[]` / `''` / absent — lexicographic / `native`); the
+ * schema is the INTERSECTION of the owners' own schemas (the registry's
+ * nested under its `tools` key), so validation and defaulting can never
+ * drift from them.
*/
export interface Config {
/** The agent-loop `agents` list (see dsh-agent-loop's `Config`). */
@@ -105,6 +115,10 @@ export interface Config {
tools?: ToolsConfig
/** Skill registry, local provider, and model-facing consumer config. */
skills?: SkillConfig
+ /** Model-facing bash tool config, including this producer's background opt-in. */
+ toolBash?: toolBash.Config
+ /** Generic background-task control-tool wait bounds. */
+ toolTasks?: toolTasks.Config
}
/** Skill bundle config forwarded to the registry, local provider, and model-facing consumer. */
@@ -118,9 +132,9 @@ export interface SkillConfig {
}
```
-Depends on: [`AgentLoopConfig`](#deepseek-aidsh-agent-loop) · [`SkillLocal`](../packages/skill/skill-local/src/index.ts) · [`SkillRegistryConfig`](#deepseek-aidsh-skill) · [`SystemPromptConfig`](#deepseek-aidsh-system-prompt) · [`ToolsConfig`](#deepseek-aidsh-tools) · [`toolSkill`](../packages/skill/tool-skill/src/index.ts)
+Depends on: [`AgentLoopConfig`](#deepseek-aidsh-agent-loop) · [`SkillLocal`](../packages/skill/skill-local/src/index.ts) · [`SkillRegistryConfig`](#deepseek-aidsh-skill) · [`SystemPromptConfig`](#deepseek-aidsh-system-prompt) · [`toolBash`](../packages/bash/tool-bash/src/index.ts) · [`ToolsConfig`](#deepseek-aidsh-tools) · [`toolSkill`](../packages/skill/tool-skill/src/index.ts) · [`toolTasks`](../packages/tasks/tool-tasks/src/index.ts)
-Source: [`packages/examples/agent-spine-demo/src/index.ts:46`](../packages/examples/agent-spine-demo/src/index.ts)
+Source: [`packages/examples/agent-spine-demo/src/index.ts:55`](../packages/examples/agent-spine-demo/src/index.ts)
## `@deepseek-ai/dsh-bash-local`
@@ -140,7 +154,7 @@ export interface Config {
}
```
-Source: [`packages/bash/bash-local/src/index.ts:18`](../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`
@@ -151,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 {
@@ -167,7 +181,7 @@ export interface Config extends LocalConfig {
Depends on: [`LocalConfig`](#deepseek-aidsh-bash-local) · [`SandboxMode`](core-data-structures/sandbox.md)
-Source: [`packages/bash/bash-sandbox/src/index.ts:26`](../packages/bash/bash-sandbox/src/index.ts)
+Source: [`packages/bash/bash-sandbox/src/index.ts:27`](../packages/bash/bash-sandbox/src/index.ts)
## `@deepseek-ai/dsh-code-runtime-worker`
@@ -551,7 +565,7 @@ export interface Config {
}
```
-Source: [`packages/sandbox/sandbox-local/src/index.ts:20`](../packages/sandbox/sandbox-local/src/index.ts)
+Source: [`packages/sandbox/sandbox-local/src/index.ts:19`](../packages/sandbox/sandbox-local/src/index.ts)
## `@deepseek-ai/dsh-session-persistence-jsonl`
@@ -694,6 +708,10 @@ export interface Config {
welcome?: string
/** Skill registry, local-provider, and model-facing consumer config forwarded to agent-spine-demo. */
skills?: agentCore.SkillConfig
+ /** Model-facing bash tool config forwarded through agent-core. */
+ toolBash?: NonNullable
+ /** Generic background-task control-tool config forwarded through agent-core. */
+ toolTasks?: NonNullable
/**
* If set, the `main` agent RESUMES this persisted session id instead of
* starting fresh. Sourced from an env var in the leaf `cordis.yml`
@@ -874,6 +892,20 @@ export interface ModelTokenMeterConfig {
Source: [`packages/llm/token-meter/src/types.ts:19`](../packages/llm/token-meter/src/types.ts)
+## `@deepseek-ai/dsh-tool-bash`
+
+Requires: `tools` · `bash` · `systemPrompt`
+
+```ts config-catalog
+/** Configures whether the model may background commands. */
+export interface Config {
+ /** Expose `run_in_background` (default true); disabled calls are also rejected. */
+ enableRunInBackground?: boolean
+}
+```
+
+Source: [`packages/bash/tool-bash/src/index.ts:30`](../packages/bash/tool-bash/src/index.ts)
+
## `@deepseek-ai/dsh-tool-cordis`
Requires: `tools`
@@ -936,34 +968,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
/**
- * Default per-child agent options (model) applied to every spawned child.
- * Omitted fields fall back to the child loop's own defaults.
+ * Expose `run_in_background` (default true). Disabled instances omit the
+ * parameter and reject forced background calls.
+ */
+ enableRunInBackground?: boolean
+ /**
+ * 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. */
@@ -972,12 +999,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
}
@@ -985,7 +1008,23 @@ export interface Config {
Depends on: [`AgentOptions`](../packages/core/agent/src/index.ts)
-Source: [`packages/subagent/tool-subagent/src/index.ts:24`](../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
+/** Configures bounded `task_output` waits. */
+export interface Config {
+ /** Wait duration applied when `task_output` sets `wait` without `timeout_ms` (default 30s). */
+ waitTimeoutMs?: number
+ /** Hard cap on any single wait; a larger model-supplied `timeout_ms` is clamped down to it (default 10min). */
+ maxWaitTimeoutMs?: number
+}
+```
+
+Source: [`packages/tasks/tool-tasks/src/index.ts:21`](../packages/tasks/tool-tasks/src/index.ts)
## `@deepseek-ai/dsh-tool-web`
@@ -1119,7 +1158,7 @@ export interface Config {
}
```
-Source: [`packages/web/web-fetch-local/src/index.ts:36`](../packages/web/web-fetch-local/src/index.ts)
+Source: [`packages/web/web-fetch-local/src/index.ts:34`](../packages/web/web-fetch-local/src/index.ts)
## `@deepseek-ai/dsh-web-search-deepseek`
@@ -1143,7 +1182,7 @@ export interface Config {
}
```
-Source: [`packages/web/web-search-deepseek/src/index.ts:40`](../packages/web/web-search-deepseek/src/index.ts)
+Source: [`packages/web/web-search-deepseek/src/index.ts:38`](../packages/web/web-search-deepseek/src/index.ts)
## `@deepseek-ai/dsh-web-search-exa`
@@ -1165,7 +1204,7 @@ export interface Config {
}
```
-Source: [`packages/web/web-search-exa/src/index.ts:39`](../packages/web/web-search-exa/src/index.ts)
+Source: [`packages/web/web-search-exa/src/index.ts:37`](../packages/web/web-search-exa/src/index.ts)
## `@deepseek-ai/dsh-web-search-perplexity`
@@ -1187,7 +1226,7 @@ export interface Config {
}
```
-Source: [`packages/web/web-search-perplexity/src/index.ts:33`](../packages/web/web-search-perplexity/src/index.ts)
+Source: [`packages/web/web-search-perplexity/src/index.ts:31`](../packages/web/web-search-perplexity/src/index.ts)
## `@deepseek-ai/dsh-workflow-workerthread`
@@ -1227,9 +1266,9 @@ These load from a `cordis.yml` entry with no `config:` block; they declare no co
- `@deepseek-ai/dsh-llm` ([`packages/llm/llm/src/index.ts`](../packages/llm/llm/src/index.ts))
- `@deepseek-ai/dsh-session` ([`packages/core/session/src/index.ts`](../packages/core/session/src/index.ts))
- `@deepseek-ai/dsh-subagent` ([`packages/subagent/subagent/src/index.ts`](../packages/subagent/subagent/src/index.ts))
+- `@deepseek-ai/dsh-tasks` ([`packages/tasks/tasks/src/index.ts`](../packages/tasks/tasks/src/index.ts))
- `@deepseek-ai/dsh-timeout-policy` — requires `tools` ([`packages/timeout/timeout-policy/src/index.ts`](../packages/timeout/timeout-policy/src/index.ts))
- `@deepseek-ai/dsh-tool-ask-user` — requires `tools` · `userInteraction` ([`packages/ui/tool-ask-user/src/index.ts`](../packages/ui/tool-ask-user/src/index.ts))
-- `@deepseek-ai/dsh-tool-bash` — requires `tools` · `bash` · `systemPrompt` ([`packages/bash/tool-bash/src/index.ts`](../packages/bash/tool-bash/src/index.ts))
- `@deepseek-ai/dsh-tool-todo` — requires `tools` ([`packages/todo/tool-todo/src/index.ts`](../packages/todo/tool-todo/src/index.ts))
- `@deepseek-ai/dsh-user-interaction` ([`packages/ui/user-interaction/src/index.ts`](../packages/ui/user-interaction/src/index.ts))
@@ -1249,13 +1288,16 @@ Abstract service classes — a deployment loads a concrete implementation packag
Imported as libraries by other packages; a `cordis.yml` cannot load them.
+- `@deepseek-ai/create-sdk` ([`packages/sdk/create-sdk/src/index.ts`](../packages/sdk/create-sdk/src/index.ts))
- `@deepseek-ai/dsh-acp-snapshot` ([`packages/support/acp-snapshot/src/index.ts`](../packages/support/acp-snapshot/src/index.ts))
- `@deepseek-ai/dsh-app-boot` ([`packages/ui/app-boot/src/index.ts`](../packages/ui/app-boot/src/index.ts))
- `@deepseek-ai/dsh-brand` ([`packages/util/brand/src/index.ts`](../packages/util/brand/src/index.ts))
+- `@deepseek-ai/dsh-helper` ([`packages/sdk/helper/src/index.ts`](../packages/sdk/helper/src/index.ts))
- `@deepseek-ai/dsh-hook-protocol` ([`packages/hooks/hook-protocol/src/index.ts`](../packages/hooks/hook-protocol/src/index.ts))
- `@deepseek-ai/dsh-jsonrpc-demo` ([`packages/examples/jsonrpc-demo/src/index.ts`](../packages/examples/jsonrpc-demo/src/index.ts))
- `@deepseek-ai/dsh-loader-smoke` ([`packages/support/loader-smoke/src/index.ts`](../packages/support/loader-smoke/src/index.ts))
- `@deepseek-ai/dsh-scope` ([`packages/core/scope/src/index.ts`](../packages/core/scope/src/index.ts))
+- `@deepseek-ai/dsh-scripts` ([`packages/sdk/scripts/src/index.ts`](../packages/sdk/scripts/src/index.ts))
- `@deepseek-ai/dsh-subagent-inprocess` ([`packages/subagent/subagent-inprocess/src/index.ts`](../packages/subagent/subagent-inprocess/src/index.ts))
- `@deepseek-ai/dsh-subagent-subprocess` ([`packages/subagent/subagent-subprocess/src/index.ts`](../packages/subagent/subagent-subprocess/src/index.ts))
- `@deepseek-ai/dsh-timeout` ([`packages/util/timeout/src/index.ts`](../packages/util/timeout/src/index.ts))
diff --git a/docs/cookbook/adding-a-tool.i18n.yaml b/docs/cookbook/adding-a-tool.i18n.yaml
index 7ff1ffff7a..6ec964c335 100644
--- a/docs/cookbook/adding-a-tool.i18n.yaml
+++ b/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: 4920c98894326fb8eab3b3d5df298baf1da33c1d
-adding-a-tool.zh.md: 3caf1e62f15f2f15103836b4d3f22be20ba02385
+adding-a-tool.md: da214702939e01fedf3d0d69be7560bbafe0696a
+adding-a-tool.zh.md: b216d18b1593cd7e6074685bd39684f1b9694eac
diff --git a/docs/cookbook/adding-a-tool.md b/docs/cookbook/adding-a-tool.md
index 4920c98894..da21470293 100644
--- a/docs/cookbook/adding-a-tool.md
+++ b/docs/cookbook/adding-a-tool.md
@@ -45,9 +45,9 @@ Registration is effect-based: disposing the plugin fiber unregisters the tool (w
## Long-running work
-Follow tool-bash's background pattern: a `run_in_background` flag returns a task id immediately; companion tools poll incrementally and kill; completion notices arrive via `agent.inject()`. Bound buffers and spill full output to disk so nothing is silently lost.
+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.
-> TODO: each tool reimplements this background pattern by hand today. At some point we need a generic long-running-tool layer that handles task ids, incremental polling, kill, and completion notices uniformly.
+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
diff --git a/docs/cookbook/adding-a-tool.zh.md b/docs/cookbook/adding-a-tool.zh.md
index 3caf1e62f1..b216d18b15 100644
--- a/docs/cookbook/adding-a-tool.zh.md
+++ b/docs/cookbook/adding-a-tool.zh.md
@@ -45,9 +45,9 @@ export function apply(ctx: Context) {
## 长时间运行的工作
-遵循 tool-bash 的后台模式：`run_in_background` 标志立即返回一个 task id；配套工具增量轮询和终止；完成通知通过 `agent.inject()` 到达。限定缓冲区大小，将完整输出溢写到磁盘，避免静默丢失。
+通过 producer 配置控制 `run_in_background`，拒绝已预先中止的调用，然后使用 `ctx.tasks.start({ kind, label, owner: exec.agent, run })` 注册任务。运行时会在 `run()` 启动工作前校验 owner 和控制面是否可用，随后提供 id、会话围栏、通用控制工具、通知和 owner cleanup。
-> TODO: 目前每个工具都手动重新实现这套后台模式。未来需要一个通用的长时间运行工具层，统一处理 task id、增量轮询、终止和完成通知。
+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`。
## 执行策略与观测
diff --git a/docs/cookbook/maintaining-dsh-code-review.md b/docs/cookbook/maintaining-dsh-code-review.md
new file mode 100644
index 0000000000..5a6c2df120
--- /dev/null
+++ b/docs/cookbook/maintaining-dsh-code-review.md
@@ -0,0 +1,62 @@
+# Maintaining the dsh-code-review skill
+
+The [`dsh-code-review`](../../.agents/skills/dsh-code-review/SKILL.md) skill is kept current by a single designated operator running a private periodic maintenance tool. This cookbook is the entry point for that operator — and for anyone taking over the role — and for repo contributors who want to understand why skill updates arrive as small periodic PRs rather than one-off audits. The workflow itself is specified in the [human-review skill-maintenance RFC](../rfc/proposed/process/2026-07-13-human-review-skill-maintenance.md).
+
+## What the maintainer receives
+
+Run the private tool daily with a two-UTC-day overlap; until the proposed scheduler has completed its acceptance run, the operator invokes the wrapper manually at the same cadence. A manual weekly recovery run uses a seven-day window. The workflow:
+
+1. It selects PRs merged in the chosen window (default two UTC days for the daily cadence, seven for weekly) whose merge commit is reachable from `origin/master`. PRs whose merge commit is not reachable (stacked branches whose parent was squashed) or that exceed a 250-commit acquisition cap are logged to `skipped-pulls.json` and skipped rather than aborting the run.
+2. It collects pre-merge human review feedback with commit anchors (inline comments and review submissions), then compares feedback-time and final landed PR patches. It does not acquire PR conversation comments because current GitHub state cannot give them a force-push-safe feedback-time baseline, and it excludes target-branch-only changes from adoption evidence.
+3. Two independently configured reviewer adapters classify provenance and adoption, then classify agreed-adopted items against the current skill.
+4. The primary adapter drafts a complete revised `SKILL.md`; both adapters review the same diff; blocking findings loop until both approve.
+5. `pnpm run doc-sync` and `pnpm run lint` run against the candidate before the tool declares success.
+
+Each run stores its artifacts on the operator's machine. The saved diff, candidate `SKILL.md`, and promotion manifest land under `~/dsh-code-review-outputs/` named by timestamp. The manifest records the source master commit and skill blob, source feedback IDs and URLs, landed evidence ranges, adapter verdicts, and gate results; raw per-adapter I/O stays in a private temp directory whose path is written to the notification and to the daily log under `~/Library/Logs/dsh-code-review-maintainer/`. The maintenance worktree itself is restored clean after every run so the operator is never tempted to edit the maintenance copy in place.
+
+## What the operator does with a candidate diff
+
+When a run produces a candidate, a macOS notification arrives with a `dsh-code-review-promote ` hint.
+
+1. **Read the diff on its own merits.** Do not defer to "the reviewers approved" — the maintainer contract is that the operator is the final judgment. Look for checklist bloat, historical prose, unsupported extrapolation from a single incident, and duplicated coverage with existing skill or authoritative-doc content.
+
+ ```sh
+ ls ~/dsh-code-review-outputs/ # every candidate ever produced
+ less ~/dsh-code-review-outputs/2026-07-16T02-00-00Z.diff
+ less ~/dsh-code-review-outputs/2026-07-16T02-00-00Z.SKILL.md
+ less ~/dsh-code-review-outputs/2026-07-16T02-00-00Z.manifest.json
+ ```
+
+2. **Cross-check against the run artifacts.** The promotion manifest maps each proposed rule to source feedback and landed evidence; detailed per-adapter I/O, consensus, and adopted evidence live under the run's private temp directory (path shown in the log). Spot-check at least one candidate: does the linked human comment actually support the added rule? Does the linked PR actually adopt it?
+
+3. **Decide one of three:**
+ - **Discard.** Delete the saved candidate. The tool re-considers the same feedback on the next run under whatever the current skill then says.
+
+ ```sh
+ rm ~/dsh-code-review-outputs/2026-07-16T02-00-00Z.{diff,SKILL.md,manifest.json}
+ ```
+ - **Batch.** Keep the candidate aside if the update is small and could combine with a future one. The source-skill check still applies; rerun the analysis or manually rebase and re-review the diff if `master` changes first.
+ - **Promote.** From a clean `master` checkout of the repo, run the promote helper. It refreshes `master`, verifies that the current skill matches the recorded source blob, applies the saved diff, and opens a draft PR whose body carries the manifest's provenance summary. It stops on skill drift rather than overwriting newer guidance; the operator still reviews the PR on GitHub and either merges it or closes it.
+
+ ```sh
+ cd ~/path/to/deepseek-harness # clean master
+ dsh-code-review-promote 2026-07-16T02-00-00Z
+ ```
+
+4. **Do not commit adapter output verbatim.** Small edits during promotion — tightening wording, removing an example that only makes sense with the source PR's context, folding a rule into an existing one — are expected and preserve the "reviewer judgment" the workflow depends on. Amend the branch before merging.
+
+## When a run produces no candidate
+
+That is the common case after every nonempty classification stage has produced at least one valid adapter result. The tool records "no candidate" in its daily log, sends no notification (to avoid alert fatigue), and moves on. Days without a skill update are the workflow behaving correctly, not a stall.
+
+## Interruptions and handoff
+
+The mechanism lives on one machine. Interruptions the operator handles as they arise:
+
+- **Daily run missed.** The two-day overlap window catches one skipped day automatically; longer gaps recover by running the wrapper manually with `DSH_CODE_REVIEW_SINCE=`. Overlapping windows are idempotent: guidance already in the current skill is classified `covered` and does not re-enter as a candidate.
+- **Adapter provider outage.** The tool refuses to run when the two reviewer commands resolve to byte-identical executables. A single batch whose adapter response fails schema or id validation is failed closed at the batch level (every item in the batch marked unclear) and the run continues; the raw output is preserved for debugging. If either adapter produces no valid result for any nonempty batch in an operation, the run fails, writes a failure record, and notifies the operator; it never collapses a total-provider outage into "no candidate."
+- **Handoff to another maintainer.** Open a follow-up RFC that supersedes the current one: either move the mechanism into the repository or record the new operator's private setup. Do not silently transfer the tool — the "single-maintainer bus factor" in the RFC's Risks section is the reason the handoff needs a documented decision.
+
+## Where the operator's private setup lives
+
+The tool source, reviewer adapters, provider credentials, and scheduler are the operator's private infrastructure and are outside this repository by design (see the RFC's "Where the mechanism lives" section). This cookbook and the RFC describe **what the workflow guarantees**; **how** those guarantees are implemented is a private-infrastructure concern. If you are the new operator, the RFC's `## Proposal` sections are the specification you build against.
diff --git a/docs/cordis-catalog/events.md b/docs/cordis-catalog/events.md
index 131297b797..a7a2c6c5c4 100644
--- a/docs/cordis-catalog/events.md
+++ b/docs/cordis-catalog/events.md
@@ -313,7 +313,7 @@ A ready child settled. Scope-filtered dispatch uses the same delegating parent c
'subagent/end'(this: Scoped, info: SubagentRunEndInfo): void
```
-Source: [`packages/subagent/subagent/src/index.ts:92`](../../packages/subagent/subagent/src/index.ts)
+Source: [`packages/subagent/subagent/src/index.ts:108`](../../packages/subagent/subagent/src/index.ts)
### `subagent/provider-added` — emit
@@ -323,7 +323,7 @@ A provider became resolvable in the registry.
'subagent/provider-added'(provider: SubagentProvider): void
```
-Source: [`packages/subagent/subagent/src/index.ts:66`](../../packages/subagent/subagent/src/index.ts)
+Source: [`packages/subagent/subagent/src/index.ts:82`](../../packages/subagent/subagent/src/index.ts)
### `subagent/provider-removed` — emit
@@ -333,7 +333,7 @@ A provider left the registry. Accepted runs remain holder-owned.
'subagent/provider-removed'(name: string): void
```
-Source: [`packages/subagent/subagent/src/index.ts:72`](../../packages/subagent/subagent/src/index.ts)
+Source: [`packages/subagent/subagent/src/index.ts:88`](../../packages/subagent/subagent/src/index.ts)
### `subagent/start` — emit
@@ -343,7 +343,7 @@ A provider established a ready child. For in-process providers, `ctx.agents.get(
'subagent/start'(this: Scoped, info: SubagentRunInfo): void
```
-Source: [`packages/subagent/subagent/src/index.ts:83`](../../packages/subagent/subagent/src/index.ts)
+Source: [`packages/subagent/subagent/src/index.ts:99`](../../packages/subagent/subagent/src/index.ts)
## `system-prompt/*`
diff --git a/docs/cordis-catalog/services.md b/docs/cordis-catalog/services.md
index 3d4191d88a..2a48032a98 100644
--- a/docs/cordis-catalog/services.md
+++ b/docs/cordis-catalog/services.md
@@ -54,23 +54,24 @@ Source: [`packages/ui/user-approval/src/index.ts:229`](../../packages/ui/user-ap
## `ctx.bash` — `BashExecutor` (abstract seam)
-Registers one `ctx.bash` implementation. Runtime command failures resolve as BashRunResult; only infrastructure failures reject. Background starts return immediately without a timeout, report completion exactly once while live, and remain cancellable by signal or kill. Output reads are incremental and flag lost buffered data; disposal kills and awaits all tasks.
+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).
+
+Implementations must honor these semantics:
+
+- 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
abstract run(spec: BashExecSpec): Promise
-abstract start(spec: BashExecSpec): BashTask
-abstract get(id: BashTaskId): BashTask | undefined
-abstract ownerOf(id: BashTaskId): OwnerToken | undefined
-abstract list(): BashTask[]
-abstract readOutput(id: BashTaskId): BashTaskRead
-abstract kill(id: BashTaskId): boolean
-onTaskDone(listener: BashTaskListener): () => void
+abstract start(spec: BashExecSpec): BashProcess
```
-Types: [BashExecRequest](../core-data-structures/bash.md) · [BashExecSpec](../core-data-structures/bash.md) · [BashRunResult](../core-data-structures/bash.md) · [BashTask](../core-data-structures/bash.md) · [BashTaskRead](../core-data-structures/bash.md)
+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:38`](../../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)
@@ -224,7 +225,7 @@ list(): string[]
async start(name: string, request: SubagentStartRequest): Promise
```
-Source: [`packages/subagent/subagent/src/index.ts:125`](../../packages/subagent/subagent/src/index.ts)
+Source: [`packages/subagent/subagent/src/index.ts:141`](../../packages/subagent/subagent/src/index.ts)
## `ctx.systemPrompt` — `SystemPrompt`
@@ -239,6 +240,25 @@ async assemble(context: AssembleContext = {}): Promise
Source: [`packages/core/system-prompt/src/index.ts:209`](../../packages/core/system-prompt/src/index.ts)
+## `ctx.tasks` — `TaskService`
+
+The `tasks` service: the runtime-global background task registry. See the module doc for the ownership, isolation, and lifecycle contracts.
+
+```ts cordis-catalog
+start(spec: TaskStart): TaskId
+list(caller?: Agent): TaskSnapshot[]
+get(id: TaskId, caller?: Agent): TaskSnapshot
+read(id: TaskId, caller?: Agent): TaskRead
+kill(id: TaskId, caller?: Agent, reason?: string): 'requested' | 'already-finished'
+async wait(id: TaskId, timeoutMs: number, caller?: Agent, signal?: AbortSignal): Promise
+onTaskDone(listener: TaskDoneListener): () => void
+attachSurface(name: string): () => void
+```
+
+Types: [Agent](../core-data-structures/core.md)
+
+Source: [`packages/tasks/tasks/src/index.ts:76`](../../packages/tasks/tasks/src/index.ts)
+
## `ctx.tokenMeter` — `TokenMeterService`
Concrete registry and replay owner for all configured model meters.
diff --git a/docs/core-data-structures/bash.md b/docs/core-data-structures/bash.md
index a5efe1a504..3f2602e613 100644
--- a/docs/core-data-structures/bash.md
+++ b/docs/core-data-structures/bash.md
@@ -1,6 +1,6 @@
# Bash Executor
-The bash execution seam — the canonical [capability seam](../rfc/implemented/architecture/2026-06-13-capability-seams.md) example, split across three packages: interface ([dsh-bash](../../packages/bash/bash), `ctx.bash`), implementation ([dsh-bash-local](../../packages/bash/bash-local), local subprocesses), and consumer ([dsh-tool-bash](../../packages/bash/tool-bash), the `bash`/`bash_output`/`bash_kill` tool schemas). Bash is **one optional capability**, not part of the agent-loop spine — so its vocabulary lives here, not in [core.md](core.md). A sandboxed, containerized, or remote backend is a sibling package implementing the same interface.
+The bash execution seam is split across interface ([dsh-bash](../../packages/bash/bash), `ctx.bash`), implementations ([dsh-bash-local](../../packages/bash/bash-local) and [dsh-bash-sandbox](../../packages/bash/bash-sandbox)), and consumer ([dsh-tool-bash](../../packages/bash/tool-bash), the `bash` schema). Generic background-task ids, ownership, and controls live in [tasks.md](tasks.md); this seam returns a task-free process handle.
Source: [`packages/bash/bash/src/types.ts`](../../packages/bash/bash/src/types.ts)
@@ -35,15 +35,6 @@ interface BashExecRequest {
* uses shell syntax like `FOO=bar cmd`).
*/
env?: Record | undefined
- /**
- * Opaque OWNER token for a background task — the consumer's isolation key
- * (the tool layer passes the owning agent's `session.header.id`). The
- * executor stores it on the task and exposes it via {@link BashExecutor.ownerOf};
- * the executor itself NEVER interprets it (no access policy lives in the
- * seam — that is the consumer's job). Absent for foreground runs and for an
- * ownerless background start (a non-agent caller).
- */
- owner?: OwnerToken | undefined
/**
* Explicit per-call sandbox-policy input, overriding the executor's
* configured default mode for THIS call. Never a silent default: a
@@ -70,10 +61,8 @@ interface BashExecSpec {
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
- * (unlike `owner`): 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).
+ * verbatim from {@link BashExecRequest.stdin}. It has no config default, so
+ * a missing value means "no stdin" and remains an ordinary optional.
*/
stdin?: string | undefined
/**
@@ -85,19 +74,10 @@ interface BashExecSpec {
*/
env?: Record | undefined
/**
- * Opaque owner token, REQUIRED-but-nullable (mirrors `workdir`/`timeoutMs`
- * being required on the resolved spec): {@link BashExecutor.resolve} carries
- * the request's `owner` through, defaulting a missing one to `undefined`. A
- * required field makes a forgotten owner a VISIBLE `undefined` rather than a
- * silently-absent property that yields an unowned (cross-session-readable)
- * task. `start()` stores it; `run()` (foreground) ignores it.
- */
- owner: OwnerToken | undefined
- /**
- * The sandbox mode this call executes under, REQUIRED-but-nullable for the
- * same visibility reason as `owner`. A sandboxing executor's `resolve()`
- * stamps the effective mode (the request's explicit override, else its
- * configured default) so `run()`/`start()` read the spec, never the config;
+ * The sandbox mode this call executes under, required-but-nullable so every
+ * resolved spec states its policy. A sandboxing executor's `resolve()` stamps
+ * the effective mode (the request's explicit override, else its configured
+ * default) so `run()`/`start()` read the spec, never the config;
* a non-sandboxing executor carries the request value through verbatim and
* ignores it (`undefined` under such an executor means what its README says:
* unconfined execution).
@@ -106,11 +86,7 @@ interface BashExecSpec {
}
```
-The `owner` token is the isolation key: the executor stores it but never interprets it (access policy is the consumer's job), so a background task started by one agent isn't readable cross-session. A required-but-nullable field makes a forgotten owner a visible `undefined` rather than a silently-unowned task.
-
-Trusted in-process plugins use `stdin` and `env` for hook payloads and hook-specific variables. The model-facing bash tool constructs requests from its named schema fields and exposes neither input because shell syntax already provides equivalent power; tests guard against a future `...args` spread. This is request-shape discipline, not a security boundary: `dsh-bash-local` scrubs ambient credentials regardless of these fields, then overlays explicit values already held by the caller. See [the bash stdin/env RFC](../rfc/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.md).
-
-Both ids the seam handles are [branded](core.md) (zero-cost `string` brands, the same machinery as `SessionId`/`AgentId`): `BashTaskId` (a tracked background task, generated `bash-N` by the local executor) and `OwnerToken` (the opaque isolation key). `OwnerToken` is deliberately a DISTINCT brand from `SessionId`, not an alias: the bash seam is a capability seam that must not know what an owner token *means*, so it never imports `dsh-session`'s vocabulary — the `dsh-tool-bash` consumer is the single boundary that casts the owning agent's `SessionId` into an `OwnerToken`. Branding both stops a raw `string` (or a `BashTaskId` where an `OwnerToken` is expected, or vice versa) from slipping through the type checker on the model-facing `task_id` path.
+`stdin` and `env` are trusted in-process plugin inputs and are not exposed by `dsh-tool-bash`. The local executor scrubs ambient credentials before merging explicit caller-supplied env. See [the bash-stdin-env RFC](../rfc/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.md).
## Foreground runs: `BashRunResult`
@@ -154,9 +130,9 @@ interface CollectedOutput {
## File sandbox: `BashSandboxInfo`
-A sandbox-consuming executor (`dsh-bash-sandbox`) exposes its configured fallback through `BashExecutor.sandboxMode`. The tool layer folds each agent session's durable `bash/sandbox-mode` override, stamps the effective mode onto the request, and may replace it for one user-approved strictly wider call. It deliberately neither states the standing mode nor narrates switches; a denial result names the mode that command actually ran under. The mode/enforcement vocabulary is owned and cataloged by the [`@deepseek-ai/dsh-sandbox` seam](sandbox.md), whose provider wraps the executor's argv; modes govern FILE effects only, not network or process visibility.
+A sandbox-consuming executor exposes its configured fallback through `BashExecutor.sandboxMode`. The tool layer folds each session's durable `bash/sandbox-mode` override and may replace it for one user-approved strictly wider call. The mode/enforcement vocabulary is owned by the [`@deepseek-ai/dsh-sandbox` seam](sandbox.md); modes govern file effects only.
-A sandboxed run always reports the facts it executed under on `BashRunResult.sandbox`: `denied` is the executor's conservative classification of a failure as sandbox-caused (a failed exit whose stderr carries a filesystem-permission signature — never a clean exit or a signal kill), read from the collected stderr tail; `enforcement` reports how completely the selected backend governs the mode's file effects (`SandboxEnforcement = 'full' | 'partial'` — `partial` when an older Landlock ABI governs only a subset of the requested accesses; absent under `danger-full-access`, where nothing is confined); `runnerFailed` marks the opposite of a denial — the sandbox RUNNER itself failed and the command never ran (stamped only on settled background tasks; a foreground run surfaces the same condition as the thrown `SANDBOX_UNAVAILABLE` error):
+A sandboxed run reports its mode, conservative denial classification, and enforcement completeness. `runnerFailed` marks a sandbox runner failure before the command ran; foreground execution throws `SANDBOX_UNAVAILABLE`, while a settled background process has only its facts channel.
```ts type-equiv
interface BashSandboxInfo {
@@ -195,38 +171,40 @@ interface BashSandboxInfo {
One more piece completes the vocabulary: the `SANDBOX_UNAVAILABLE` error code (owned by the [sandbox seam](sandbox.md)) is what the `ctx.sandbox` provider throws — and the executor propagates — when a confined mode has no usable backend. A selected runner refusing its profile reaches the same fail-closed foreground error; a settled background task records `runnerFailed`. The model receives denial/runner facts in results, learns the effective mode only when a denial marker names it, and can request a one-shot strictly wider retry through `sandbox_permissions` plus `justification`; `ctx.approval` must grant that exact call before anything executes. The complete policy and switching design is the [sandbox RFC](../rfc/implemented/feature/2026-07-06-sandbox.md).
-## Background tasks: `BashTask`
+## Background processes: `BashProcess`
-A long-running command started with `start()` is tracked as a `BashTask`. `BashTaskStatus` is `'running' | 'completed' | 'killed'`; `done` resolves when the underlying process closes and never rejects. A sandboxing executor stamps `sandbox` once the task settles — classification runs against the settled task's collected stderr — so the field is absent while running and under an unsandboxed executor.
+`start()` returns a handle with no id or owner. `dsh-tool-bash` adapts it into `ctx.tasks.start()` hooks; the generic runtime then owns task identity and lifecycle. `done` resolves when the process closes and never rejects, reads remain valid after settlement, and sandbox facts are stamped before `done` resolves.
```ts type-equiv
-interface BashTask {
- readonly id: BashTaskId
- status: BashTaskStatus
+interface BashProcess {
+ /** Process lifecycle state (settled exactly once). */
+ status: BashProcessStatus
/** Exit code once finished (null = killed by signal / still running). */
exitCode: number | null
/** Terminating signal name, when signal-killed. */
signal: NodeJS.Signals | null
- /** Resolves when the underlying process closes (never rejects). */
+ /** Resolves when the underlying process closes (never rejects — a spawn failure settles as `killed` with the error on stderr). */
readonly done: Promise
- /**
- * Sandbox facts for this task's execution, stamped by a sandboxing executor
- * once the task settles and BEFORE completion listeners are notified — an
- * `onTaskDone` consumer and a `done` awaiter both see it. Denial
- * classification runs against the settled task's collected stderr, so the
- * field cannot exist earlier: absent while the task is running and under an
- * executor that does not sandbox. See {@link BashSandboxInfo} for the
- * `denied` semantics.
- */
+ /** Sandbox facts, stamped once a confined process settles. */
sandbox?: BashSandboxInfo
+ /**
+ * Read output produced since the previous read (consuming — consecutive
+ * reads never re-deliver). Reads that lost data flag `lossy` and point at
+ * full-stream spill files when available.
+ */
+ readOutput(): BashProcessRead
+ /**
+ * Kill the process group. Returns false when it had already finished
+ * (no-op); idempotent.
+ */
+ kill(): boolean
}
```
-`readOutput()` returns an incremental `BashTaskRead` — the output produced since the previous read, with a `lossy` flag when truncation dropped unread bytes:
+`readOutput()` returns the incremental delta and spill recovery facts:
```ts type-equiv
-interface BashTaskRead {
- task: BashTask
+interface BashProcessRead {
/** Output produced since the previous read (stderr in a marked section). */
delta: string
/** True when truncation dropped unread bytes the delta cannot include. */
@@ -240,4 +218,4 @@ interface BashTaskRead {
## The service
-`BashExecutor` (`ctx.bash`, abstract — defined in [`packages/bash/bash/src/index.ts`](../../packages/bash/bash/src/index.ts)) mirrors the `LlmService`/`LlmAdapter` split: `resolve` (request → spec), `run` (foreground), `start` (background), `get`/`ownerOf`/`list`/`readOutput`/`kill`, and `onTaskDone` (a `BashTaskListener` completion callback). Spawned commands get a **scrubbed env** (dropping `*KEY*`/`*SECRET*`/`*TOKEN*`) and spill files use a private 0700 dir with random names and owner-only opens — model output never gets the ambient environment or a predictable path. The implementation that provides all this is `dsh-bash-local`; the model-facing `bash`/`bash_output`/`bash_kill` schemas that call it are in `dsh-tool-bash` (and present as terminals via the [tool-presentation vocabulary](tools.md#tool-presentation-ui-vocabulary)).
+`BashExecutor` owns `resolve`, foreground `run`, background-process `start`, and the `sandboxMode` capability fact. `dsh-bash-local` owns process groups, timeout/abort handling, bounded collectors, spill files, credential scrubbing, and disposal quiescence. `dsh-tool-bash` owns model-facing rendering and adapts background handles into the [generic task runtime](tasks.md).
diff --git a/docs/core-data-structures/core.md b/docs/core-data-structures/core.md
index 1f8dca8abc..858731f688 100644
--- a/docs/core-data-structures/core.md
+++ b/docs/core-data-structures/core.md
@@ -25,7 +25,7 @@ Everything else is documented on a **sub-page**, not here. The rule that draws t
| [tools.md](tools.md) | `ToolDefinition` full fields, the schema DSL, `ToolExecution`/`ToolResult`, tool-presentation UI types, and the guarded execution pipeline |
| [user-interaction.md](user-interaction.md) | the UI-backed human question/answer seam: `AskUserQuestionRequest`, answer/options vocabulary, provider API, error taxonomy |
| [approval.md](approval.md) | the one-shot user-approval seam: `ApprovalRequest`, `ApprovalOutcome`, per-session policy, audit and answerer contracts |
-| [bash.md](bash.md) | the bash executor seam: `BashExecRequest`/`Spec`, `BashRunResult`, background `BashTask`s |
+| [bash.md](bash.md) | the bash executor seam: `BashExecRequest`/`Spec`, `BashRunResult`, background `BashProcess` handles |
| [sandbox.md](sandbox.md) | the process-confinement seam: file-effect modes, `SandboxPolicy`, `ConfinedArgv`, enforcement and fail-closed errors |
| [code-runtime.md](code-runtime.md) | the code-execution seam: `CodeRunRequest`/`Result`, binding namespaces, captured logs, the `CodeRunFailure` taxonomy |
| [filesystem.md](filesystem.md) | the filesystem seam: `FsTarget`, read/write/edit outcomes, observed-file state, `FsErrorCode` |
@@ -77,7 +77,7 @@ Two large discriminated unions are the ones consumers `switch` over most: **`Str
IDs that cross package boundaries are **branded** — structurally strings, but non-interchangeable at the type level (an `AgentId` can't be passed where a `CallId` is expected). Construction goes through a per-type factory; comparison, logging, and JSON behave as ordinary strings.
-The `Branded` primitive lives in its own type-only package, [dsh-brand](../../packages/util/brand) (no runtime code, no harness-package dependency), so any package can brand the ids it owns without depending on an unrelated capability package (e.g. dsh-bash brands `BashTaskId`/`OwnerToken` via dsh-brand alone, never pulling in dsh-llm).
+The `Branded` primitive lives in its own type-only package, [dsh-brand](../../packages/util/brand) (no runtime code, no harness-package dependency), so any package can brand the ids it owns without depending on an unrelated capability package.
Source: [`packages/util/brand/src/index.ts`](../../packages/util/brand/src/index.ts)
@@ -85,7 +85,7 @@ Source: [`packages/util/brand/src/index.ts`](../../packages/util/brand/src/index
type Branded = string & { readonly [BRAND]: B }
```
-The three core IDs: `CallId` (correlates a tool call with its result; dsh-llm), `SessionId` (dsh-session), `AgentId` (dsh-agent). Each is `Branded<'CallId'>` etc. plus a same-named factory function. Capability seams brand their own ids too — see `BashTaskId`/`OwnerToken` in [bash.md](bash.md).
+The three core IDs are `CallId`, `SessionId`, and `AgentId`. Capability packages brand their own ids too, such as `TaskId` in [tasks.md](tasks.md).
## Content blocks and messages
diff --git a/docs/core-data-structures/tasks.md b/docs/core-data-structures/tasks.md
new file mode 100644
index 0000000000..0482912af7
--- /dev/null
+++ b/docs/core-data-structures/tasks.md
@@ -0,0 +1,129 @@
+# Background Task Runtime
+
+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 a [branded id](core.md#branded-ids) generated as `-N`. Access control relies on owner authorization, not id secrecy. `TaskKind` derives from a merge-extensible map; the registry treats kinds as opaque id namespaces.
+
+```ts type-equiv
+interface TaskKindMap {
+ bash: 'bash'
+ subagent: 'subagent'
+}
+```
+
+`TaskStatus` is `'running' | 'stopping' | 'completed' | 'killed' | 'failed'`; producer-specific facts belong in `TaskSnapshot.detail`.
+
+## Producer contract
+
+`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 {
+ /** Producer kind — also the id prefix (`bash`, `subagent`, …). */
+ kind: TaskKind
+ /** One-line model-facing label (the command; the delegation description). */
+ label: string
+ /**
+ * 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. Omitting the owner creates an unowned task,
+ * open to any caller until service disposal.
+ */
+ owner?: Agent
+ /**
+ * 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. Must be synchronous, idempotent, and eventually settle
+ * {@link done}; throws propagate. The optional reason is forwarded verbatim.
+ */
+ cancel(reason?: string): void
+ /**
+ * 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
+ /**
+ * 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
+}
+```
+
+```ts type-equiv
+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 tasks without `readOutput`; stream tasks leave it unset. */
+ output?: string
+}
+```
+
+## Consumer views
+
+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 {
+ /** The registry-issued id (`-N`). */
+ id: TaskId
+ /** The producer kind the task was registered with. */
+ kind: TaskKind
+ /** The producer-supplied one-line label. */
+ label: string
+ /**
+ * 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. */
+ status: TaskStatus
+ /** Kind-specific status detail, present once the producer supplied one (usually terminal). */
+ detail?: string
+ /** Epoch ms when the task was registered. */
+ startedAt: number
+ /** Epoch ms when the task settled; absent while `running`/`stopping`. */
+ finishedAt?: number
+ /**
+ * 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
+}
+```
+
+```ts type-equiv
+interface TaskRead {
+ /**
+ * Stream kinds: the consuming delta since the previous read. Final-output
+ * kinds: empty while live, the terminal {@link TaskOutcome.output} (or
+ * empty) once settled — idempotent, never consumed.
+ */
+ text: string
+ /** The task's state at read time. */
+ snapshot: TaskSnapshot
+}
+```
+
+## Service behavior
+
+[`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.
diff --git a/docs/core-data-structures/tools.md b/docs/core-data-structures/tools.md
index 132d22d521..46f2863f73 100644
--- a/docs/core-data-structures/tools.md
+++ b/docs/core-data-structures/tools.md
@@ -232,4 +232,4 @@ How a tool wants its call shown in a UI (an editor tool-call card, a CLI log lin
`ToolCallKind` (`'read' | 'edit' | 'delete' | 'move' | 'search' | 'execute' | 'fetch' | 'other'`) picks an icon on a generic card. `FileLocation` (`{ path, line? }`) and `FileDiff` (`{ path, oldText, newText }`) are the shared file-card vocabulary. The design is pinned in [the render-intent-union RFC](../rfc/implemented/architecture/2026-07-02-tool-render-intent-union.md); the ACP bridge maps a `diff` card to a `{ type: 'diff' }` content block, a `terminal` card to the `_meta` terminal convention, and relativizes a file card's title against the session cwd.
-The full presentation field docs live in [`packages/core/tools/src/presentation.ts`](../../packages/core/tools/src/presentation.ts). The bash tool's own schemas (`bash`/`bash_output`/`bash_kill`) and the executor they drive are on [bash.md](bash.md).
+The full presentation field docs live in [`packages/core/tools/src/presentation.ts`](../../packages/core/tools/src/presentation.ts). The `bash` schema and executor are on [bash.md](bash.md); generic background controls are on [tasks.md](tasks.md).
diff --git a/docs/development.i18n.yaml b/docs/development.i18n.yaml
index cb4807c048..494eb09922 100644
--- a/docs/development.i18n.yaml
+++ b/docs/development.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
-development.md: 376df72c14b59b8ac8e42b31f19442040d6a47a7
-development.zh.md: 676df50a8a1ab2eff3ec829b5d55904626fa3f5e
+development.md: b3c338f03f548b4de4b676850732731323d611f1
+development.zh.md: 20f5c585dd378a7b0a3bd6b0af8ebf7dc5e0fd3c
diff --git a/docs/development.md b/docs/development.md
index 376df72c14..b3c338f03f 100644
--- a/docs/development.md
+++ b/docs/development.md
@@ -19,7 +19,7 @@ Install dependencies from the repo root:
pnpm install
```
-The install also runs the root `postinstall` script, which installs lefthook from the repo dev dependency through `scripts/install-lefthook.mjs`; the wrapper uses lefthook's reviewed `--force` mode so linked worktrees with an existing `core.hooksPath` do not fail normal `pnpm run …` commands.
+The install also runs the root `postinstall` script, which installs lefthook from the repo dev dependency through `scripts/install-lefthook.mjs`; the wrapper script uses lefthook's reviewed `--force` mode so linked worktrees with an existing `core.hooksPath` do not fail normal `pnpm run …` commands.
If hooks are missing because dependencies were restored from cache or `postinstall` was skipped, install them manually:
@@ -59,7 +59,7 @@ DEEPSEEK_BASE_URL=https://... # optional
lefthook is configured in `lefthook.yml` as an early local checkpoint before review:
- `pre-commit` runs staged-file ESLint fixes, `pnpm run typecheck`, and the vendor manifest guard.
-- `pre-push` runs `pnpm run check:pre-push`, whose scheduler runs unit tests, snapshot tests, build, module-graph freshness, and the member gates of `pnpm run hygiene` and `pnpm run doc-sync` concurrently.
+- `pre-push` runs `pnpm run check:pre-push`, whose scheduler runs runtime-closure verification, unit tests, duplication detection, snapshot tests, build, module-graph freshness, and the member gates of `pnpm run hygiene` and `pnpm run doc-sync` concurrently.
The vendor manifest guard checks that changes under `vendor/*/src` are staged with the matching `vendor/README.md` manifest update. See `vendor/README.md` before editing vendored code.
diff --git a/docs/development.zh.md b/docs/development.zh.md
index 676df50a8a..20f5c585dd 100644
--- a/docs/development.zh.md
+++ b/docs/development.zh.md
@@ -9,7 +9,7 @@
- Node.js 支持 22.19+ 与 24+。CI 覆盖 22.19、24 和 26；见 [Node 引擎下限 RFC](rfc/implemented/process/2026-07-06-node-engine-floor.md)。
- 启用了 Corepack 的 pnpm。仓库在 `package.json` 中固定使用 `pnpm@11.7.0`；如果 `pnpm --version` 无法通过 Corepack 解析，请先运行 `corepack enable`。
- Git。
-- 可选：一个 DeepSeek API key，用于 REPL/ACP agent（智能体）演示和真实 API 的 e2e 测试。
+- 可选：一个 DeepSeek API key，用于 REPL/ACP（Agent Client Protocol） agent（智能体）演示和真实 API 的 e2e 测试。
## 首次搭建
@@ -58,8 +58,8 @@ DEEPSEEK_BASE_URL=https://... # optional
lefthook 在 `lefthook.yml` 中配置，作为评审前的本地早期检查点：
-- `pre-commit` 运行对暂存文件的 ESLint 修复、`pnpm run typecheck` 和 vendor manifest 守卫；
-- `pre-push` 运行 `pnpm run check:pre-push`，其调度器并发运行单元测试、快照测试、构建、module-graph 新鲜度，以及 `pnpm run hygiene` 与 `pnpm run doc-sync` 的各成员门禁。
+- `pre-commit` 运行对暂存文件的 ESLint 修复、`pnpm run typecheck` 和 vendor manifest（元数据清单）守卫；
+- `pre-push` 运行 `pnpm run check:pre-push`，其调度器并发运行 runtime-closure 校验、单元测试、重复代码检查、快照测试、构建、module-graph 新鲜度，以及 `pnpm run hygiene` 与 `pnpm run doc-sync` 的各成员门禁。
vendor manifest 守卫检查 `vendor/*/src` 下的改动是否连同对应的 `vendor/README.md` manifest 更新一起暂存。请在编辑 vendor 代码前先阅读 `vendor/README.md`。
diff --git a/docs/event-producer-consumer.md b/docs/event-producer-consumer.md
index 1f280d74b1..9e64489ac6 100644
--- a/docs/event-producer-consumer.md
+++ b/docs/event-producer-consumer.md
@@ -31,10 +31,10 @@ This matrix shows which packages dispatch each harness-owned event and which pac
| `session/disposed` | `emit` | [`packages/core/session/src/index.ts:56`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | - |
| `session/event` | `emit` | [`packages/core/session/src/index.ts:68`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`acp`](../packages/ui/acp), [`invariants`](../packages/support/invariants), [`jsonrpc`](../packages/ui/jsonrpc), [`session-persistence`](../packages/session-persistence/session-persistence), [`stdio`](../packages/ui/stdio), [`token-meter`](../packages/llm/token-meter) |
| `session/flush` | `parallel` | [`packages/core/session/src/index.ts:78`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`session-persistence`](../packages/session-persistence/session-persistence) |
-| `subagent/end` | `emit` | [`packages/subagent/subagent/src/index.ts:92`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`events.dispatch`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`jsonrpc`](../packages/ui/jsonrpc) |
-| `subagent/provider-added` | `emit` | [`packages/subagent/subagent/src/index.ts:66`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`emit`) | [`tool-subagent`](../packages/subagent/tool-subagent) |
-| `subagent/provider-removed` | `emit` | [`packages/subagent/subagent/src/index.ts:72`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`events.dispatch`) | [`tool-subagent`](../packages/subagent/tool-subagent) |
-| `subagent/start` | `emit` | [`packages/subagent/subagent/src/index.ts:83`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`events.dispatch`) | [`hooks-claude`](../packages/hooks/hooks-claude) |
+| `subagent/end` | `emit` | [`packages/subagent/subagent/src/index.ts:108`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`events.dispatch`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`jsonrpc`](../packages/ui/jsonrpc) |
+| `subagent/provider-added` | `emit` | [`packages/subagent/subagent/src/index.ts:82`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`emit`) | [`tool-subagent`](../packages/subagent/tool-subagent) |
+| `subagent/provider-removed` | `emit` | [`packages/subagent/subagent/src/index.ts:88`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`events.dispatch`) | [`tool-subagent`](../packages/subagent/tool-subagent) |
+| `subagent/start` | `emit` | [`packages/subagent/subagent/src/index.ts:99`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`events.dispatch`) | [`hooks-claude`](../packages/hooks/hooks-claude) |
| `system-prompt/assemble` | `waterfall` | [`packages/core/system-prompt/src/index.ts:27`](../packages/core/system-prompt/src/index.ts) | [`system-prompt`](../packages/core/system-prompt) (`waterfall`) | - |
| `system-prompt/change` | `emit` | [`packages/core/system-prompt/src/index.ts:33`](../packages/core/system-prompt/src/index.ts) | [`system-prompt`](../packages/core/system-prompt) (`emit`) | - |
| `tools/change` | `emit` | [`packages/core/tools/src/index.ts:116`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`emit`) | - |
diff --git a/docs/i18n/README.i18n.yaml b/docs/i18n/README.i18n.yaml
index 43c64ddd90..ab1c9024ad 100644
--- a/docs/i18n/README.i18n.yaml
+++ b/docs/i18n/README.i18n.yaml
@@ -2,5 +2,5 @@
# side as of the last confirmed-consistent state. Both languages carry equal authority;
# after editing either side, bring the other along and re-record with:
# pnpm run verify-translation-pairing --write
-README.md: 3a5965ab60a7bdb6345b6abe6815f7090fa98fe1
-README.zh.md: 8e62b53ffefa25ad0bbf713889a2ec2ecdb7027a
+README.md: 17bb1eeb67b4f5119a698fca23f12490c9378a7f
+README.zh.md: c957a82bf420a942e2249942a2d9afc54ad950cf
diff --git a/docs/i18n/README.md b/docs/i18n/README.md
index 3a5965ab60..17bb1eeb67 100644
--- a/docs/i18n/README.md
+++ b/docs/i18n/README.md
@@ -17,16 +17,16 @@ This repo's documentation is read by people and agents both inside and outside t
Blob hashes, not commit hashes, so the record is computable for files edited in the same PR (`git hash-object foo.md`) and consistency is a pure content comparison. The recorded hash also recovers the exact last-confirmed text of either side (`git cat-file -p `), so an out-of-sync pair is updated by diffing the edited side against its last-confirmed state and patching the counterpart minimally — never by re-translating whole files. After bringing the pair back in line, `pnpm run verify-translation-pairing --write` re-records both hashes; that yaml diff is the reviewable act of confirming consistency.
- **Language switcher.** Both files link to each other immediately after their H1 heading: the English file carries `English | [中文](foo.zh.md)` and the Chinese file carries `[English](foo.md) | 中文`.
-- **Structure mirrors the counterpart.** Heading depths and order, list kinds, table columns, link targets, and verbatim code blocks match one to one across the pair — see [translation-rules.md](translation-rules.md) for the full preservation rules. Existing Markdown gates apply to `.zh.md` files unchanged (`verify-md-wrap`, `verify-md-links`).
+- **Structure mirrors the counterpart.** Heading depths and order, list kinds, ordered-list starts, list item counts, table row and column counts, link targets, and verbatim code blocks match one to one across the pair — see [translation-rules.md](translation-rules.md) for the full preservation rules. Existing Markdown gates apply to `.zh.md` files unchanged (`verify-md-wrap`, `verify-md-links`).
## The gate: verify-translation-pairing
`pnpm run verify-translation-pairing` (part of `doc-sync`, so CI and the pre-push hook run it) enforces the contract mechanically:
1. Every file listed as `required` in [scripts/translation-pairing.manifest.json](../../scripts/translation-pairing.manifest.json) has a complete pair.
-2. Every pair that exists at all — required or not — is complete and consistent: all three files present, each side's current blob hash equals the recorded one (editing either side without re-confirming the pair goes red), both sides carry the language switcher, and the structural signatures match in order — heading depths, verbatim code blocks (info string and content), table column counts, list kinds, and every link target apart from the switcher.
+2. Every pair that exists at all — required or not — is complete and consistent: all three files present, each side's current blob hash equals the recorded one (editing either side without re-confirming the pair goes red), both sides carry the language switcher, and the structural signatures match in order — heading depths, verbatim code blocks (info string and content), table row and column counts, list kinds, ordered-list starts, item counts, and every link target apart from the switcher.
3. Files listed as `excluded` have no `.zh.md` and no `.i18n.yaml` at all.
-4. Every date-named document (`yyyy-mm-dd-*.md`) dated on or after the manifest's `requiredSince` cutoff has a complete pair — new documents merge bilingual from birth.
+4. Every date-named document (`yyyy-mm-dd-*.md`) dated on or after the manifest's `requiredSince` cutoff has a complete pair — new date-named RFCs merge bilingual from birth.
`pnpm run verify-translation-pairing --list` prints the current pairing state of every document in scope — missing, out-of-sync, or ok — and is the work list for translation batches. It never fails; it reports.
@@ -49,4 +49,4 @@ The gate's limit, stated plainly: **a green gate means the pair was confirmed co
## Division of labor
-Counterparts here are produced by an agent running [dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md) and reviewed by a human — inference is cheap here, review attention is the scarce resource. The gate exists so that neither the agent nor the reviewer has to remember the contract: pair completeness, consistency, and structure are checked mechanically, and review attention goes to translation quality and terminology, where human judgment is the whole point.
+Counterparts here are produced by an agent running [dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md) and reviewed by a human — inference is cheap here, review attention is the scarce resource. The gate checks pair completeness, recorded hashes, switchers, and its documented structural signature. Review still owns translation quality, terminology, and structural requirements that the signature does not encode. The prompt contract is executable: [scripts/translation-prompt.ts](../../scripts/translation-prompt.ts) renders the canonical rules into either direction and strictly parses the three-field XML response, while `verify-translation-prompt` exercises both render directions, the checked-in example, and the CDATA split rule in `doc-sync`.
diff --git a/docs/i18n/README.zh.md b/docs/i18n/README.zh.md
index 8e62b53ffe..c957a82bf4 100644
--- a/docs/i18n/README.zh.md
+++ b/docs/i18n/README.zh.md
@@ -2,12 +2,12 @@
[English](README.md) | 中文
-本仓库的文档会被公司内外的人和 agent（智能体）阅读，因此 README 与 docs 目录树以英文和简体中文双语维护。本页定义配对契约、强制门禁与推进策略；[translation-rules.md](translation-rules.md) 定义如何翻译；[terminology.md](terminology.md) 是术语真源。进仓的 agent 工作流见 [.agents/skills/dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md)。
+本仓库的文档会被公司内外的人和 agent（智能体）阅读，因此 README 与 docs 目录树以英文和简体中文双语维护。本页定义配对契约、强制门禁与推进策略；[translation-rules.md](translation-rules.md) 定义如何翻译；[terminology.md](terminology.md) 是术语真源。仓库内置的 agent 工作流见 [.agents/skills/dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md)。
## 配对契约
- **两种语言同权。**一篇文档可以先用任一语言撰写和评审——先写中文的 RFC 与先写英文的一样正当——另一侧由它翻译而来。两个文件谁也不高于谁；约束它们的是二者必须说同样的话。
-- **一对文档是三个同目录文件。**英文 `foo.md`、中文 `foo.zh.md`，加一份一致性记录 `foo.i18n.yaml`，都在同一目录。不用语言目录，不用独立翻译仓库，不用中英混排的单文件。配对整体合入：PR 永远不会只带一种语言而缺其余两个文件。
+- **一对文档是三个同目录文件。**英文 `foo.md`、中文 `foo.zh.md`，加一份一致性记录 `foo.i18n.yaml`，都在同一目录。不用语言目录，不用独立翻译仓库，不用中英混排的单文件。配对整体合入：PR（Pull Request）永远不会只带一种语言而缺其余两个文件。
- **一致性记录。**`foo.i18n.yaml` 保存两侧文件在上一次被确认「说同样的话」时各自的完整 git blob hash：
```yaml
@@ -17,15 +17,16 @@
用 blob hash 而不是 commit hash，这样同一个 PR 里改动的文件也能算出记录（`git hash-object foo.md`），一致性是纯内容比较。记录的 hash 还能还原任一侧上次确认时的确切文本（`git cat-file -p `），所以失去同步的配对是「把被改的一侧与其上次确认状态做 diff、再最小化地修补另一侧」——从不整篇重译。两侧对齐后，`pnpm run verify-translation-pairing --write` 重新记录两个 hash；那份 yaml diff 就是「确认一致」这个动作本身，可以被评审。
- **语言切换行。**两个文件在各自 H1 标题之后立即互链：英文文件带 `English | [中文](foo.zh.md)`，中文文件带 `[English](foo.md) | 中文`。
-- **结构与另一侧一一对应。**标题深度与顺序、列表类型、表格列、链接目标与逐字节一致的代码块在配对两侧一一对应——完整保持规则见 [translation-rules.md](translation-rules.md)。既有 Markdown 门禁对 `.zh.md` 文件原样生效（`verify-md-wrap`、`verify-md-links`）。
+- **结构与另一侧一一对应。**标题深度与顺序、列表类型、有序列表起始编号、列表项数量、表格行列数、链接目标与逐字节一致的代码块在配对两侧一一对应——完整保持规则见 [translation-rules.md](translation-rules.md)。既有 Markdown 门禁对 `.zh.md` 文件原样生效（`verify-md-wrap`、`verify-md-links`）。
## 门禁：verify-translation-pairing
-`pnpm run verify-translation-pairing`（`doc-sync` 的一环，因此 CI 和 pre-push 钩子都会运行）机械地强制执行这份契约：
+`pnpm run verify-translation-pairing`（`doc-sync`（文档同步门禁）的一环，因此 CI 和 pre-push 钩子都会运行）机械地强制执行这份契约：
1. [scripts/translation-pairing.manifest.json](../../scripts/translation-pairing.manifest.json) 中 `required` 列出的每个文件都有完整配对。
-2. 任何已存在的配对——无论是否 required——都完整且一致：三个文件齐全、每一侧的当前 blob hash 等于记录值（改了任一侧而没重新确认配对就变红）、双方都带语言切换行、结构签名按序一致——标题深度、逐字节一致的代码块（信息字符串与内容）、表格列数、列表类型，以及除切换行之外的每个链接目标。
+2. 任何已存在的配对——无论是否 required——都完整且一致：三个文件齐全、每一侧的当前 blob hash 等于记录值（改了任一侧而没重新确认配对就变红）、双方都带语言切换行、结构签名按序一致——标题深度、逐字节一致的代码块（信息字符串与内容）、表格行列数、列表类型、有序列表起始编号、列表项数量，以及除切换行之外的每个链接目标。
3. 列为 `excluded` 的文件完全没有 `.zh.md`，也没有 `.i18n.yaml`。
+4. 凡文件名符合 `yyyy-mm-dd-*.md` 且日期不早于 manifest（元数据清单）中 `requiredSince` 分界日期的文档，都必须有完整配对——新建的日期命名 RFC 从创建起便须配齐中英文。
`pnpm run verify-translation-pairing --list` 打印范围内每篇文档的当前配对状态——missing、out-of-sync 或 ok——是翻译批次的工作清单。它从不失败；它只报告。
@@ -44,8 +45,8 @@
- `docs/i18n/terminology.md` 与 [style-samples.md](style-samples.md)——二者本身即为中英对照文档。
- [translation-prompt.md](translation-prompt.md)——自动翻译流水线的 prompt 模板；正文逐字进入模型请求，配对翻译会改变流水线行为。
-**推进**：以日期命名的文档（`yyyy-mm-dd-*.md`，即 RFC），只要标注日期等于或晚于 manifest 的 `requiredSince` 分界日期，合入时就必须配齐双语文件。更早日期的文件属于待翻清单（backlog），包括分界前夜创建的文件。RFC 文件名记录首次提出日期，因此倒填日期绕过分界属于评审可见的违规。manifest 中的 `required` 列表是当前执行红线，并非全量覆盖这一最终目标。翻译批次将路径加入 `required`，使门禁只向前收紧。未列入的文档仍可通过 `--list` 查看，而任何已存在的配对都受完整契约约束。后续修改必须同步更新两侧，因此 `required` 的扩展速度不能超过翻译评审的承载能力。
+**推进**：以日期命名的文档（`yyyy-mm-dd-*.md`，即 RFC），只要标注日期等于或晚于 manifest 的 `requiredSince` 分界日期，合入时就必须配齐双语文件。更早日期的文件属于 backlog（待翻清单），包括分界前夜创建的文件。RFC 文件名记录首次提出日期，因此倒填日期绕过分界属于评审可见的违规。manifest 中的 `required` 列表是当前执行红线，并非全量覆盖这一最终目标。翻译批次将路径加入 `required`，使门禁只向前收紧。未列入的文档仍可通过 `--list` 查看，而任何已存在的配对都受完整契约约束。后续修改必须同步更新两侧，因此 `required` 的扩展速度不能超过翻译评审的承载能力。
## 分工
-这里的对侧译文由运行 [dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md) 的 agent 产出、由人评审——在这里推理（inference）很便宜，评审注意力才是稀缺资源。门禁的存在让 agent 和评审者都不必记住契约：配对完整性、一致性和结构由机械检查兜底，评审注意力投向翻译质量与术语——这正是人的判断的用武之地。
+对侧译文由运行 [dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md) 的 agent 生成，再由人评审：在这里推理（inference）很便宜，评审注意力才是稀缺资源。门禁负责检查配对是否完整、记录的 hash、语言切换行以及本文列出的结构签名；翻译质量、术语和签名未涵盖的结构要求仍由评审把关。prompt 契约也有可执行实现：[scripts/translation-prompt.ts](../../scripts/translation-prompt.ts) 会把权威规则渲染到英译中或中译英的 prompt 中，并严格解析包含三个字段的 XML 响应；`doc-sync` 中的 `verify-translation-prompt` 会检查两个渲染方向、仓库内示例与 CDATA 拆分规则。
diff --git a/docs/i18n/style-samples.md b/docs/i18n/style-samples.md
index 6d9e82d184..786ebea0df 100644
--- a/docs/i18n/style-samples.md
+++ b/docs/i18n/style-samples.md
@@ -1,8 +1,8 @@
# 翻译语体样例（style samples）
-本文件是翻译语体的校准锚点：每组样例是一段英文原文与一段人工定稿的中文译文，覆盖本仓库文档的主要文体。**译文的语体以这些样例为准**——它们的效力高于任何对语气的文字描述。翻译或评审时对照最接近的文体样例；样例与规则冲突时，样例胜出。本文件中英对照、自成双语，不参与配对（见 [README.md](README.md) 排除清单）。
+本文件是翻译语体的校准锚点：每组样例是一段英文原文与一段人工定稿的中文译文，覆盖本仓库文档的主要文体。**译文的语体以这些样例为准**——文体样例的效力高于对语气的文字描述，但术语表、忠实性与结构规则仍然优先。翻译或评审时对照最接近的文体样例。本文件中英对照、自成双语，不参与配对（见 [README.md](README.md) 排除清单）。
-维护方式：人工评审校准出新的金标段落后追加到对应文体；样例只增不改，改动需评审人签字（PR 评审即签字）。
+维护方式：人工评审校准出新的金标段落后追加到对应文体；发现语义、结构或术语错误时直接修正。新增或修正样例都需经过 PR 评审。
## ① 架构叙述
@@ -16,7 +16,7 @@
> This document covers **behavior**; type shapes live in [core-data-structures/](../core-data-structures/core.md), the per-event/service reference in the [generated catalog](../cordis-catalog/events.md), per-package contracts in the package READMEs ([map](../../packages/README.md)).
-本文档描述整体行为逻辑；类型定义存放于 [core-data-structures/](../core-data-structures/core.md)；各类事件、服务的详细参考见[生成目录](../cordis-catalog/events.md)；各 package 对外约束协议写在对应包的 README（[索引](../../packages/README.md)）。
+本文档描述整体行为逻辑；类型定义存放于 [core-data-structures/](../core-data-structures/core.md)；各类事件、服务的详细参考见[生成目录](../cordis-catalog/events.md)；各包（package）的对外契约写在相应的 README 中（[索引](../../packages/README.md)）。
## ② 防御模式规则
@@ -26,11 +26,11 @@
> **Dispose must reach quiescence, not just request it** — A teardown that issues kills/aborts but returns before the work stops leaves orphans. Make cleanup async and await the children's exit (kill → await `done`), and close listener/notification registries BEFORE killing so late completions stay silent. Tests prove disposal waited (pid gone right after `await fiber.dispose()`), not merely that the process eventually dies.
-**销毁操作必须等待所有任务完全停稳，不能仅下发终止指令就返回**——若销毁逻辑仅发送终止、中断信号，但不等任务停止就直接退出，会产生孤儿进程。清理逻辑需设为异步，等待所有子任务彻底退出（先下发终止信号，再等待执行完成）；在执行终止操作前先关闭监听器与通知注册表，让延迟到达的完成事件不再触发任何通知。测试要验证销毁流程确实完成等待：执行完 `await fiber.dispose()` 后进程 PID 立即消失，不能仅校验进程最终会自行消亡。
+**dispose（资源释放）必须等待所有任务完全停稳，不能仅下发终止指令就返回**：如果清理过程只发出终止或中断信号，却不等任务停止就返回，就会留下孤儿进程。清理应采用异步方式，等待所有子任务彻底退出（先发出终止信号，再等待退出）；发出信号前应先关闭监听器与通知注册表，使延迟到达的完成事件不再触发通知。测试要证明 dispose 的确等到清理完成：执行完 `await fiber.dispose()` 后进程 PID 立即消失，不能只检查进程最终会自行消亡。
> **Async state is not synchronous state** — `agent.send()` does not flip status before returning; a background task's completion races turn boundaries; `reader.close()` fires for both EOF and disposal. Never gate control flow on a status you only just requested — drive lifecycle off the events/promises that actually fire (`agent/status`, `task.done`), and observe the transition (saw `running` THEN `idle`) rather than counting actions you assume map 1:1 to turns.
-**异步状态不等同于同步瞬时状态**——调用 `agent.send()` 不会在返回前同步更新状态；后台任务完成时机与轮次边界存在竞态；调用 `reader.close()` 既可能是读到文件末尾，也可能是资源销毁触发。切勿仅凭刚查询到的状态来阻断流程；生命周期逻辑应基于真实触发的事件与 promise 驱动（`agent/status`、`task.done`），观测完整状态切换（先 `running`、再 `idle`），而非主观认定操作和执行轮次一一对应（主循环会批量处理排队消息）。
+**异步状态不等同于同步瞬时状态**：调用 `agent.send()` 不会在返回前同步更新状态；后台任务的完成时间与轮次边界存在竞态；`reader.close()` 既会在读到文件末尾时触发，也会在资源释放时触发。切勿把刚刚发起的状态变更当成已经生效，据此控制流程；生命周期逻辑应以实际触发的事件和已完成的 promise（`agent/status`、`task.done`）为准，并观察完整的状态变化（先 `running`，再 `idle`），不要根据操作次数推断操作与轮次一一对应。
## ③ 测试政策清单
@@ -40,15 +40,15 @@
> We are DeepSeek — do not ration real-API tests. A no-key test proves the plumbing; only a with-key run proves the agent works against a real model. Write many: real prompts that write files, multi-turn conversations, tool use, cancellation mid-stream. Cheapest and highest-value are **smoke tests** that boot the real example, send one real prompt, and check the world — they catch the "green unit tests, broken product" class that mocks structurally cannot. The self-skip exists only so secretless CI and keyless contributors aren't blocked; it is not a cost signal.
-我们是 DeepSeek：真实接口相关测试不得刻意缩减用例数量。无密钥测试仅能验证底层通路；只有携带有效密钥执行的用例，才能确认 agent 可正常对接真实模型。请大量编写此类测试：包含文件写入类真实提示词、多轮对话、工具调用、流式中途取消等场景。
+我们是 DeepSeek：真实接口相关测试不得刻意缩减用例数量。无密钥测试仅能验证底层通路；只有携带有效密钥执行的用例，才能确认 agent（智能体）可正常对接真实模型。请大量编写此类测试：包含文件写入类真实提示词、多轮对话、工具调用、流式中途取消等场景。
-成本最低、收益最高的是**冒烟测试**：拉起完整真实示例，发送一条真实提示并校验整体运行状态。这类用例能捕获一类问题——单元测试全部绿灯，但产品实际运行故障，单靠 mock 完全无法发现这类缺陷。
+成本最低、收益最高的是**冒烟测试**：拉起完整真实示例，发送一条真实提示，并检查文件、进程等外部可观察结果。这类用例能捕获一类问题——单元测试全部绿灯，但产品实际运行故障，单靠 mock 完全无法发现这类缺陷。
自带自动跳过逻辑，仅用于保障无密钥 CI 环境、无权限贡献者不会被流程拦截，不代表可以以此为由削减真实接口测试投入。
> **Prefer the real implementation over a mock** — Mock only the genuinely expensive or non-deterministic boundary (the LLM adapter, the network, the clock); keep everything downstream real. A hand-rolled stand-in proves the bridge moves bytes, not that the shipping tool behaves as asserted — the two drift while the test stays green.
-**优先使用真实实现，而非 mock 替身**——仅对开销极大、结果不确定的边界模块做 mock（LLM 适配器、网络、时钟），其余下游组件全部使用真实实现。手写的 mock 替身只能验证数据通路能传输字节，无法保证线上工具符合预期逻辑；长期下来业务逻辑与 mock 实现会出现偏差，但测试仍会显示通过。
+**优先使用真实实现，而非 mock 替身**——仅对开销极大、结果不确定的边界模块做 mock（LLM（大语言模型）适配器、网络、时钟），其余下游组件全部使用真实实现。手写的 mock 替身只能验证数据通路能传输字节，无法保证线上工具符合预期逻辑；长期下来业务逻辑与 mock 实现会出现偏差，但测试仍会显示通过。
## ④ 机制描述
@@ -60,7 +60,7 @@
> The gate's limit, stated plainly: a green gate means the pair was confirmed consistent at these exact contents, not that the confirmation was sound. It checks hashes and shape; it cannot judge whether the two sides actually say the same thing — that is the reviewer's half of the contract. A re-recorded pair with a sloppy counterpart passes the gate; it must not pass review.
-明确门禁校验边界：门禁校验通过，仅代表两份文档哈希与结构完全匹配，不代表译文内容准确无误。门禁仅校验哈希与结构，无法判断双语表意是否统一——译文质量把关是评审人的责任。即便译文粗糙、表意偏差，只要哈希匹配，门禁就会放行，但这类 PR 绝不能通过人工评审。
+门禁的边界很明确：通过门禁只说明两侧文件当前的 blob hash 与伴随记录吻合，并且结构签名一致，也就是说，这组内容曾被确认一致；它不代表这次确认可靠。门禁无法判断两种语言是否真正表达了相同的意思；这部分契约要由评审人把关。即使译文粗糙、表意有误，重新记录配对后仍能通过门禁，但绝不能通过人工评审。
## ⑥ RFC 论证
@@ -70,9 +70,9 @@
## ⑦ 推进策略（长段拆分示范）
-> **Rollout**: new documents don't wait for a batch — a date-named document dated on or after the manifest's `requiredSince` cutoff must merge with its pair, so everything new is bilingual from birth. For the back-catalog, the `required` list in the manifest is the enforcement frontier, not the goal. […] Pairing a document is a commitment: every later edit to either side must carry the counterpart along, so grow the frontier at the pace translation review is actually resourced, not ahead of it.
+> **Rollout**: date-named RFCs don't wait for a batch — one dated on or after the manifest's `requiredSince` cutoff must merge with its pair, so each new date-named RFC is bilingual from birth. For the back-catalog, the `required` list in the manifest is the enforcement frontier, not the goal. […] Pairing a document is a commitment: every later edit to either side must carry the counterpart along, so grow the frontier at the pace translation review is actually resourced, not ahead of it.
-**推进**：新增文档不再走批量分批翻译流程。以日期命名的文档，若其标注日期等于或晚于 manifest 里 `requiredSince` 分界时间，提交合入时必须配套对应的双语译文文件——所有新文档从创建起就要求中英双语齐备。针对存量旧文档：manifest 内的强制翻译列表只是当下执行红线，并非最终目标。（……）文档完成双语配对等同于一份长期约束承诺：后续只要修改任一版本，就必须同步更新对应另一语种文件。因此强制翻译范围的推进节奏，要匹配翻译评审实际可投入人力，切勿超前铺开。
+**推进**：日期命名的 RFC 无需等待批量翻译。只要文件名中的日期不早于 manifest（元数据清单）的 `requiredSince` 分界日期，合入时就必须配齐中英文，因此此类 RFC 从创建起就要求双语齐备。对于存量文档，manifest 中的 `required` 列表只是当前的执行红线，并非最终目标。（……）一旦文档完成配对，后续修改任一侧都必须同步更新另一侧。因此，应根据实际可投入的翻译评审能力逐步扩展执行红线，不能超前。
## 从样例提炼的要点
diff --git a/docs/i18n/terminology.md b/docs/i18n/terminology.md
index d14d0f2fd8..120121e452 100644
--- a/docs/i18n/terminology.md
+++ b/docs/i18n/terminology.md
@@ -33,7 +33,7 @@
| English | 中文 | 首次出现 | 不要译作 | 备注 |
|---|---|---|---|---|
| agent | agent | agent（智能体） | | |
-| agent harness | agent harness | | | agent 组合词（agent harness/workflow/loop/skill 等）整体保留英文；未括注过 agent 时首现按 agent 行处理 |
+| agent harness | agent harness | agent harness（智能体框架） | | agent 组合词（agent harness/workflow/loop/skill 等）整体保留英文；未括注过 agent 时首现按对应组合词或 agent 行处理 |
| agent loop | agent loop | agent loop（智能体循环） | | |
| backlog | backlog | backlog（待翻清单） | | 仅在双语翻译语境里括注`待翻清单` |
| blob hash | blob hash | | | `git hash-object` 的结果 |
@@ -76,13 +76,16 @@
| backend | 后端 | | | |
| background task | 后台任务 | | | |
| block | 块 | | | |
+| build target | 构建目标 | | | |
| cancel | 取消 | | | |
-| capability | 能力 | | | |
+| feature | 功能 | | 能力 | SDK 产品与工程模型中的可管理产品单元 |
+| feature option | 功能选项 | | variant | 一项 SDK 功能内有限、可选择的实现或配置 |
| checkpoint | 检查点 | | | |
| chunk | 分片 | | | |
| compaction | 压缩 | 压缩（compaction） | | |
| companion tool | 配套工具 | | | |
-| config | 配置 | | | |
+| Cordis plugin config | Cordis 插件配置 | | | Cordis 插件公开的 `Config` 对象或配置结构 |
+| config key | 配置键 | | | Cordis 插件配置中的单个字段 |
| consumer | 消费方 | | | |
| content block | 内容块 | | | |
| Cookbook | 实操手册 | | | 文档标题用语 |
@@ -90,10 +93,13 @@
| counterpart | 对侧文件 | | 对应物、配对物 | 双语配对语境；泛指"另一侧"时可写「另一侧」 |
| context compaction | 上下文压缩 | 上下文压缩（context compaction） | | |
| contract | 契约 | | | 如：`pairing contract` →`配对契约` |
+| Cordis config entry | Cordis 配置项 | | | 指 `cordis.yml` 插件列表中的一项；插件实现本身写`Cordis 插件` |
+| Cordis plugin | Cordis 插件 | | | Cordis 加载的插件实现，不指 `cordis.yml` 中的一项配置 |
| coverage | 覆盖率 | | | |
| crash recovery | 崩溃恢复 | | | |
| deploy root | 部署根目录 | | | |
| durability | 持久性 | | | |
+| feature requirement | 功能依赖 | | | 功能或功能选项通过 `requires` 声明的关系 |
| enforcement frontier | 执行红线 | | 强制边界 | i18n 配对机制用语：manifest `required` 清单所划的门禁生效范围；与金标样例（style-samples ⑦）一致 |
| event | 事件 | | | |
| event log | 事件日志 | | | |
@@ -104,7 +110,7 @@
| extension point | 扩展点 | | | 注意与 `seam` 区分 |
| fail-fast | 快速失败 | | | |
| fenced code block | 围栏代码块 | | | 沿用 MDN 中文翻译 |
-| fingerprint | 指纹 | | | i18n 配对机制用语：`.zh.md` 首行记录英文源 blob hash 的注释 |
+| fingerprint | 指纹 | | | 通用内容指纹；双语配对机制使用 sidecar record 记录两侧 blob hash |
| finish reason | 结束原因 | | | |
| foreground run | 前台运行 | | | |
| freshness | 新鲜度 | | | 沿用 MDN 中文翻译；在本项目中指译文相对源文的同步状态 |
@@ -122,6 +128,7 @@
| mod | 模组 | | | |
| model provider | 模型提供方 | | | |
| module | 模块 | | | |
+| npm dependency | NPM 依赖 | | | `package.json` 中的包关系；`dependencies`、`devDependencies` 等字段保持原样 |
| orphan | 遗留 | | 孤儿、孤立 | 指英文源已不存在的 `.zh.md`（如「遗留译文」）；进程语境按 OS 惯用语译「孤儿进程」 |
| orphan branch | 孤立分支 | | 孤儿分支 | 沿用 git 官方中文翻译 |
| package | 包 | 包（package） | | 指 npm 包（`@deepseek-ai/dsh-*`）；`package.json` 等代码标识保持原样 |
@@ -171,3 +178,5 @@
| vocabulary | 词汇 | | | |
| wire format | 协议格式 | 协议格式（wire format） | | |
| workflow | 工作流 | | | |
+| wrapper | 包装层 | | | 软件层或 SDK 包装层 |
+| wrapper script | 包装脚本 | | | 可执行脚本包装层 |
diff --git a/docs/i18n/translation-prompt.md b/docs/i18n/translation-prompt.md
index 60a023979a..8bc15d6e8e 100644
--- a/docs/i18n/translation-prompt.md
+++ b/docs/i18n/translation-prompt.md
@@ -1,24 +1,27 @@
# Translation prompt (pipeline asset)
-本文件是自动翻译流水线的 prompt 模板；自 `# Translation Prompt` 起的正文逐字进入模型请求，因此不参与双语配对（见 [README.md](README.md) 排除清单）。渲染时，[terminology.md](terminology.md) 整表填入 `{{terminology}}`。[style-samples.md](style-samples.md) 定义文体，模板内嵌的 Examples 仅抽样问题类型；两者冲突时以文体样例为准。修改本文件即修改翻译行为，需按正常 PR 评审。
+本文件是自动翻译流水线使用的 prompt 模板；从 `# Translation Prompt` 开始的正文会逐字进入模型请求，因此本文件不参与双语配对（见 [README.md](README.md) 排除清单）。渲染时会把 [translation-rules.md](translation-rules.md) 全文填入 `{{translation_rules}}`，把 [terminology.md](terminology.md) 整表填入 `{{terminology}}`，以免模板另存一份规则而日后失去同步。[style-samples.md](style-samples.md) 定义文体，模板中的 Examples 只用于说明典型问题；术语表、忠实性和结构规则优先于样例，样例只在这些硬性约束内决定文体。修改本文件会改变翻译行为，需正常经过 PR 评审。
## 占位符契约
-流水线渲染模板时替换以下占位符，除此之外不做任何文本处理：
+流水线渲染模板时替换以下占位符，除此之外不改写系统消息：
| 占位符 | 填入内容 | 来源 |
|---|---|---|
| `{{source_lang}}` | 源语言名（`English` / `Chinese`） | 由改动侧文件推断：`.zh.md` 被改则为 `Chinese` |
| `{{target_lang}}` | 目标语言名（`Chinese` / `English`） | 与 `{{source_lang}}` 相对 |
+| `{{translation_rules}}` | [translation-rules.md](translation-rules.md) 全文（Markdown 原文） | 渲染时读取仓库当前版本，不缓存 |
| `{{terminology}}` | [terminology.md](terminology.md) 的完整表格（Markdown 原文） | 渲染时读取仓库当前版本，不缓存 |
-| `{{source_filename}}` | 源文档的 basename（如 `foo.md`） | 由流水线从待译文件路径取得 |
-| `{{source_filename_zh}}` | 中文侧 basename（如 `foo.zh.md`） | 由 `{{source_filename}}` 派生 |
+| `{{source_filename}}` | 源文档的 basename（如 `foo.md` 或 `foo.zh.md`） | 由流水线从待译文件路径取得 |
+| `{{source_filename_zh}}` | 中文侧 basename（如 `foo.zh.md`） | 英文源追加 `.zh`；中文源使用自身 basename |
-流水线仅支持上表占位符，并按整篇文档翻译。它不支持 `{{to}}`、`{{title_prompt}}`、`{{summary_prompt}}`、`{{terms_prompt}}`、`{{imt_style_guide}}` 或 `%%` 分段协议；输出采用下方三段 XML。
+例如，英译中时若源文件是 `foo.md`，`{{source_filename}}` 填 `foo.md`，`{{source_filename_zh}}` 填 `foo.zh.md`；中译英时若源文件是 `foo.zh.md`，两个占位符都填 `foo.zh.md`。
+
+流水线只识别上表中的占位符，并且一次翻译整篇文档。它不支持 `{{to}}`、`{{title_prompt}}`、`{{summary_prompt}}`、`{{terms_prompt}}`、`{{imt_style_guide}}` 或 `%%` 分段协议。输出必须是一个以 `` 为根元素的 XML 文档；三个子元素中的 Markdown 内容都放在 CDATA 中。内容出现 `]]>` 时写成 `]]]]>`，XML 解析后仍会还原为原文。
## Few-shot 金标
-流水线的 few-shot 是**整文档级**的中英对照，不是模板内嵌的句子级正误例（那是最小抽样）。few-shot 集取自以下 5 组人工定稿的配对文档，以仓库当前版本为准、随仓库更新：
+流水线使用**整篇文档**的中英对照作为 few-shot，不是模板内嵌的句子级正误例。以下 5 组配对文档均经过人工评审，并以仓库当前版本为准，随仓库一同更新：
- `README.md` ↔ `README.zh.md`
- `docs/development.md` ↔ `docs/development.zh.md`
@@ -26,136 +29,58 @@
- `docs/i18n/translation-rules.md` ↔ `docs/i18n/translation-rules.zh.md`
- `docs/rfc/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.md` ↔ 对应 `.zh.md`
-注入方式：在系统消息（本模板）之后、待译文档之前，每组作为一轮示例对话——user 消息为源文档全文，assistant 消息为定稿译文全文（不带三段 XML 包装；只有真实请求要求三段输出）。上下文紧张时按上列顺序从后往前裁剪组数。这 5 组也是评审校准锚点（见 [style-samples.md](style-samples.md)），改动任何一组即改变流水线行为。
+注入时按当前翻译方向选择每组的源侧与目标侧：user 消息包含源文档全文，assistant 消息采用模板正文规定的 XML 协议；`translation` 与 `final` 都放入目标文档全文，`review` 填 `- [None] No corrections.`。CDATA 遵循上文的 `]]>` 拆分规则。上下文不足时，按上列顺序从后往前删减示例组数。这 5 组也是评审校准锚点；改动任何一组都会改变流水线行为。
## 模板正文
````text
# Translation Prompt
-You are a senior technical translator specializing in LLM and agent development documentation. Your task is to translate the given source document from {{source_lang}} to {{target_lang}}, producing natural, professional technical prose.
+You are a senior technical translator specializing in LLM and agent development documentation. Translate the complete source document from {{source_lang}} to {{target_lang}} as natural, professional technical prose.
-## Quality Requirements
+## Binding Translation Rules
-### Structure and Format Preservation
-- Output a complete translated document that maintains exactly the same structure as the source: heading hierarchy, list shape, table columns, link targets, and code blocks.
-- Fenced code blocks must be byte-identical to the source, including ALL comments inside them. Do NOT translate comments inside code blocks. This is a hard rule with no exceptions.
-- Inline code spans (commands, flags, paths, API names, version numbers) must be kept verbatim. Never translate or reformat them.
-- Every relative link must point to the same target as in the source. Link text is translated; link targets are not.
-- Language switcher line: the source document's filename is `{{source_filename}}`. When translating into Chinese, write `[English]({{source_filename}}) | 中文` immediately after the H1 heading. When translating into English, write `English | [中文]({{source_filename_zh}})` immediately after the H1. Emit this line even when the source file has no switcher yet (a brand-new pair); when the source does have one, flip the link direction — never copy it unchanged.
-- After a closing bold marker `**`, insert a space before the next character when that character is a Latin letter or digit. Never insert a space before full-width (Chinese) punctuation.
+The canonical repository rules below are injected verbatim. Apply every direction-appropriate requirement. In those rules, the authored document is the source for this request and the generated document is its counterpart.
-### Tone and Style
-- The translation must read as if originally written in the target language by a native speaker. If an expression sounds like a word-for-word rendering from the source language, rephrase it.
-- Write in a professional, formal tone appropriate for developer documentation. Never use colloquial or casual expressions.
-- Use polite imperative forms where the text instructs the reader to do something.
-- Keep the author's register: concise stays concise, detailed stays detailed.
+{{translation_rules}}
-### Sentence Structure
-- Break long sentences with commas or semicolons. Avoid run-on sentences.
-- Prefer active voice. Convert passive constructions to active if it reads more naturally.
-- Translate meaning, not words. Restructure sentences where the target language grammar requires it.
-- Do not invent words or expressions that do not exist in natural technical writing of the target language.
+## Request-Specific Structure
-### Word Choice
-- Prefer precise, formal vocabulary over casual or colloquial alternatives.
-- When multiple synonyms exist, choose the one most commonly used in professional technical documentation of the target language.
-- Avoid slang, internal jargon, or overly literal translations that would not be recognized by the general developer audience.
-- Do not use the same word to translate two different source-language terms that carry distinct meanings.
-- Avoid repeating the same verb in close proximity; vary word choice for readability.
+- The source basename is `{{source_filename}}`. When translating into Chinese, write `[English]({{source_filename}}) | 中文` immediately after the H1. When translating into English, write `English | [中文]({{source_filename_zh}})` immediately after the H1.
+- Emit the switcher for a new pair and flip an existing switcher; never copy it unchanged.
-#### When translating into Chinese
-- When a number modifies a noun, always include a Chinese classifier or measure word (量词). For example: "three-package seam" → "由三个 package 构成的 seam", not "三 package seam".
+## Binding Terminology
-### Punctuation
-
-#### When translating into Chinese
-- Use full-width Chinese punctuation in prose: `，。：；？！（）「」`.
-- Strongly prefer replacing all em-dashes (——) with colons, periods, commas, or parentheses. Keep an em-dash only if no other punctuation works at all.
-- Use enumeration commas (、) between parallel items, not regular commas.
-- List item endings: use semicolons or no punctuation. Do not end list items with commas.
-- Put one half-width space between Chinese text and Latin words/numbers.
-- For RFC 2119 keywords (MUST, MUST NOT, SHOULD, MAY), render the corresponding Chinese term in italics: *必须*、*禁止*、*应当*、*可以*.
-
-#### When translating into English
-- Use half-width English punctuation and standard English spacing. Preserve full-width punctuation only in verbatim Chinese text.
-- Convert enumeration commas (、) to English commas; convert 「」 quotes to English double quotes.
-- Render the terminology table's English column the same way the Chinese column binds the other direction: listed terms use exactly the table's English form; first-occurrence glosses do not carry over (English prose never glosses an English term with Chinese).
-- Chinese topic-comment sentences and dropped subjects become explicit English subjects; prefer concise declaratives over nominalizations.
-- Do not transliterate Chinese engineering idioms literally: render the underlying concept (误报 → false positive, 执行红线 → enforcement frontier), consulting the terminology table first.
-- Keep the register of institutional developer documentation: contractions are acceptable, marketing language and hedging (very, quite, simply) are not.
-
-## Terminology
-
-A terminology table is provided below. Follow it strictly:
-- Render every listed term exactly as specified.
-- First occurrence: write as shown in the "首次出现" column (with parenthetical gloss). Subsequent occurrences: write only the part before the parentheses.
-- If a term has already been glossed as part of a compound term, do not gloss it again when it appears alone later.
-- NEVER use translations listed in the "不要译作" column.
-- For technical terms not in the table: keep them in the source language. Do not invent a translation. This rule applies to terminology only; for general prose, freely restructure and paraphrase for natural expression.
+Apply the current table below exactly as required by the injected translation rules.
{{terminology}}
## Output Format
-Produce your output in three XML sections:
+Return exactly one well-formed XML document with this root and these three child elements. Do not wrap it in a Markdown code fence. Put all Markdown and review text inside CDATA. If any content contains the CDATA terminator, split it as `]]]]>` so XML parsing reconstructs the original `]]>` sequence.
```xml
-
-(Complete translation of the source document)
-
-
-
-(Self-review notes, one correction per line with category tag, e.g.)
-- [Tone] "旁挂记录" → "伴随记录"（生造词）
-- [Sentence] 第 3 段补充逗号断句
-- [Punctuation] 两处破折号替换为冒号
-- 无修正
-
-
-
-(Final translation after corrections)
-
+
+
```
## Self-Review Instructions
-After writing ``, re-read it in the target language only, without looking at the source. Check by category:
-
-**Structure**
-- Is the heading hierarchy, list shape, and code block content identical to the source?
-- Are ALL comments inside code blocks left untranslated (byte-identical to source)?
-- Is the language switcher line correctly flipped (not copied from source)?
-- Are link targets preserved and bold markers followed by a space?
-
-**Tone & Style**
-- Does every sentence read as if originally written by a native speaker?
-- Is there any colloquial, casual, or overly informal phrasing?
-
-**Sentence Structure**
-- Are there run-on sentences that need breaking?
-- Are there stiff passive constructions that should be converted to active voice?
-
-**Word Choice**
-- Are there overly literal translations that sound unnatural?
-- Is the same target-language word used to translate two distinct source concepts?
-- Is any slang or internal jargon present?
-
-**Terminology**
-- Are first-occurrence glosses correctly applied (not missing, not repeated)?
-- Are any "不要译作" forbidden translations present?
-- Are unlisted terms correctly kept in the source language?
-
-**Punctuation** (when target is Chinese)
-- Are there em-dashes that should be replaced with colons, periods, or commas?
-- Are list items ending with commas instead of semicolons?
-- Are RFC 2119 keywords rendered in italics?
-
-Record corrections in `` with category tags. Then output the corrected version in ``. If no corrections are needed, write "无修正" in `` and copy the translation unchanged into ``.
+After writing ``, re-read it in the target language without looking at the source. Then apply the injected translation rules as a clause-by-clause comparison against the source and record actual corrections in English inside ``. Apply every recorded correction in ``. If no correction is needed, write only `- [None] No corrections.` in `` and copy `` unchanged into ``.
## Examples
-Below are representative examples of common problems and their corrections. Follow the "Good" versions.
+Follow the Good versions; these sentence-level examples illustrate error categories, not the assistant-message wire format.
### Colloquial verb → Professional verb
- Source: `The repo pins pnpm@11.7.0 in package.json`
@@ -177,40 +102,40 @@ Below are representative examples of common problems and their corrections. Foll
- Bad: `旁挂记录两侧 blob hash，使一致性可检查`
- Good: `伴随记录保存两侧 blob hash，使一致性可检查`
-### Em-dash → Colon/period
-- Source: `FIXME — an issue that should block a new release. A release should not ship with an open FIXME unless reviewers explicitly agree the change can be merged anyway.`
-- Bad: `FIXME——应当阻塞新版本发布的问题。除非评审者明确同意可以照常合入，发布不应带着未解决的 FIXME 出门。`
-- Good: `FIXME：应当阻塞新版本发布的问题。除非评审者明确同意该更改可以合并，否则发布版本不应包含未解决的 FIXME。`
-
### Overly literal → Meaningful rendering
- Source: `awkward phrasing is easier to hear without the source anchoring you`
- Bad: `没有源文锚着，别扭的表述更容易被听出来`
- Good: `不对照原文时，更容易察觉别扭的表达`
-### Terminology — do not translate what should be kept in English
+### Terminology — keep the binding English form
- Source: `typed service seams, and explicit extension points`
- Bad: `类型化的服务 seam（扩展点）与显式扩展点`
- Good: `类型化的服务 seam 与显式扩展点`
-### Slang/jargon → Professional phrasing
+### Slang → Professional phrasing
- Source: `The committed agent workflow lives in .agents/skills/dsh-translate-docs`
- Bad: `进仓的 agent 工作流见 .agents/skills/dsh-translate-docs`
- Good: `仓库内置的 agent 工作流见 .agents/skills/dsh-translate-docs`
-### "For humans" — translate the intent, not the word
-- Source: `For humans, start with the development guide`
-- Bad: `对于人工读者，请先从开发指南开始`（"人工读者"生硬）
-- Good: `面向开发者：请先阅读开发指南`（"开发者"自然，且中文里冒号在此处更自然）
+### Chinese → English — idiomatic subject and predicate
+- Source: `门禁绿并不代表译文内容正确。`
+- Bad: `The gate green does not represent that the translation content is correct.`
+- Good: `A green gate does not mean the translation is correct.`
-### Code block comments — NEVER translate
+### Code block comments — never translate
- Source code block contains: `# REPL agent demo (needs DEEPSEEK_API_KEY)`
- Bad: `# REPL agent 演示（需要 DEEPSEEK_API_KEY）`
-- Good: `# REPL agent demo (needs DEEPSEEK_API_KEY)` (keep exactly as-is, byte-for-byte)
+- Good: `# REPL agent demo (needs DEEPSEEK_API_KEY)` (byte-identical)
-### Language switcher — flip direction
-- Source file (English) has: `English | [中文](README.zh.md)`
-- Bad (copying source unchanged): `English | [中文](README.zh.md)`
-- Good (flipped for Chinese file): `[English](README.md) | 中文`
+### Language switcher — English to Chinese
+- Source: `English | [中文](README.zh.md)`
+- Bad: `English | [中文](README.zh.md)`
+- Good: `[English](README.md) | 中文`
+
+### Language switcher — Chinese to English
+- Source: `[English](README.md) | 中文`
+- Bad: `[English](README.md) | 中文`
+- Good: `English | [中文](README.zh.md)`
---
diff --git a/docs/i18n/translation-rules.i18n.yaml b/docs/i18n/translation-rules.i18n.yaml
index 048ce5eef7..dea0883a4b 100644
--- a/docs/i18n/translation-rules.i18n.yaml
+++ b/docs/i18n/translation-rules.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
-translation-rules.md: 3e99aa5432ccd904f702238e9b802a9ed9bf6832
-translation-rules.zh.md: 1d8dcb04f1015af2db46c2e25b44f5cd147b6ecc
+translation-rules.md: fb6aa9ac05bebe68ff9213af99f64457bdb1ad6f
+translation-rules.zh.md: 04dd0a704e19502c676ea0966437870c5af0624f
diff --git a/docs/i18n/translation-rules.md b/docs/i18n/translation-rules.md
index 3e99aa5432..fb6aa9ac05 100644
--- a/docs/i18n/translation-rules.md
+++ b/docs/i18n/translation-rules.md
@@ -6,27 +6,27 @@ How to translate between the two sides of a documentation pair in this repo. Bot
## Faithfulness
-- The counterpart MUST say what the authored side says — no added behavior, prerequisites, warnings, version claims, or examples, and no dropped ones. If the pair disagrees on substance, neither language wins by default: fix the side that is wrong, then bring the other along in the same change.
-- The counterpart SHOULD read as natural technical writing in its own language, not word-by-word gloss. Translate meaning, restructure sentences where the target grammar wants it, and keep the author's register — terse stays terse.
+- The counterpart *MUST* say what the authored side says — no added behavior, prerequisites, warnings, version claims, or examples, and no dropped ones. If the pair disagrees on substance, neither language wins by default: fix the side that is wrong, then bring the other along in the same change.
+- The counterpart *SHOULD* read as natural technical writing in its own language, not word-by-word gloss. Translate meaning, restructure sentences where the target grammar wants it, and keep the author's register — terse stays terse.
- Do not translate the untranslatable: if a sentence resists natural rendering because it leans on an idiom of the source language, translate the idea, not the idiom.
## Voice
-- The register is calibrated by [style-samples.md](style-samples.md) — human-approved gold pairs, one per document genre. The counterpart MUST match the register of the nearest sample; where a sample and a prose rule here disagree, the sample wins. The target is institutional technical Chinese: complete sentences, declarative, neither chatty nor academic.
+- The register is calibrated by [style-samples.md](style-samples.md) — human-approved gold pairs, one per document genre. The counterpart MUST match the target-language side of the nearest sample; where its voice and a prose voice rule disagree, the sample wins. Chinese targets use institutional technical Chinese; English targets use concise professional developer prose.
- Write as a native technical author restating the content, not as a translator transposing sentences. Then verify against the source clause by clause: nothing added, nothing dropped — fluency never justifies losing a clause.
-- Give sentences an explicit agent: where the English uses a passive or an abstract subject, name the actor (系统、门禁、评审人).
-- Prefer established Chinese engineering idiom over calques (误报／漏检 for false positive/negative, 执行红线 for enforcement frontier); localize metaphors instead of transplanting them, and unpack English noun chains into verb clauses.
+- Give sentences an explicit actor when the target language would otherwise obscure it; for Chinese, replace vague passives or abstract subjects with the actual actor (系统、门禁、评审人).
+- Prefer established target-language engineering idiom over calques (误报／漏检 for false positive/negative, 执行红线 for enforcement frontier); localize metaphors instead of transplanting them, and unpack noun chains where the target language requires it.
- Split long paragraphs by semantic unit — one idea per paragraph. Paragraph boundaries MAY differ from the source; the structural signature does not count paragraphs.
-- Category nouns render in Chinese with a first-mention English annotation (实操手册（cookbook）); literal directory or file references stay code-formatted English.
+- When translating into Chinese, category nouns use Chinese with a first-mention English annotation (实操手册（cookbook）); when translating into English, use the conventional English category name. Literal directory or file references stay code-formatted English.
## Structure preservation
-Shape is enforced by the pairing gate, so the writer never trades fluency against it — write naturally inside the frame. The paired files MUST match one to one in:
+The pairing gate checks heading depths, fenced code blocks, table row and column counts, list kinds, ordered-list starts, list item counts, and link targets. Preserve the rest of the frame manually; the paired files MUST match one to one in:
- heading hierarchy (same levels, same order — heading TEXT is translated),
- list shape and numbering,
- tables (same columns, same row order; header cells translated per terminology),
-- fenced code blocks — **byte-identical, including comments**; code is part of the verified surface (` ```ts ` blocks compile under `doc-typecheck`), and an edited comment is drift the fence-count gate cannot see,
+- fenced code blocks — **byte-identical, including comments**; the pairing signature compares their info strings and contents, and ` ```ts ` blocks compile under `doc-typecheck`,
- inline code spans (commands, flags, config keys, file paths, event names, API names, version numbers) — verbatim, never translated or reformatted,
- links and anchors: every relative link MUST point at the same target in both files — by convention the `.md` path, not the `.zh.md` sibling — so links never dangle when one pair lands before its neighbors. The ONLY zh-specific link is the language switcher. Link TEXT is translated; the target is not.
@@ -34,9 +34,9 @@ The repo's Markdown conventions apply to `.zh.md` files unchanged: one physical
## Terminology
-- [terminology.md](terminology.md) is the source of truth in both directions. Before translating, load it; while translating, every term it lists MUST be rendered exactly as it specifies, including its first-occurrence annotations (e.g. `agent（智能体）` on first mention, plain `agent` after) and its "不要译作" prohibitions. When the Chinese side is authored first, the English counterpart uses the table's English column the same way.
-- A technical term NOT in the table MAY be translated only when a major Chinese-language OSS or vendor doc has an established rendering for it (K8s/Vue/MDN Chinese docs, 微软简中风格指南, big-tech project docs). Cite the precedent in the PR.
-- A term with NO established precedent MUST stay in English in the translation and MUST be listed in the PR description under 「待定术语」(pending terms) with a suggested rendering for the reviewer to decide. MUST NOT invent a Chinese rendering inline — an unprecedented translation creates exactly the ambiguity the terminology table exists to prevent. Decided terms then land in [terminology.md](terminology.md) in the same PR or a follow-up.
+- [terminology.md](terminology.md) is the source of truth in both directions. Before translating, load it; every listed term MUST follow its row and its "不要译作" prohibitions. A Chinese target uses the "中文" column and its "首次出现" annotation; an English target uses the "English" column without adding a Chinese gloss.
+- For a Chinese target, an unlisted technical term MAY use an established rendering from a major Chinese-language OSS or vendor source (K8s/Vue/MDN Chinese docs, 微软简中风格指南, big-tech project docs), cited in the PR. Without such precedent it MUST stay in English and be listed under 「待定术语」(pending terms) with a suggested rendering.
+- For an English target, use the established English technical term. If the source term has no unambiguous established equivalent, preserve it with a short explanatory gloss and list it under pending terms. Neither direction may invent a rendering inline; a decided term enters [terminology.md](terminology.md) in the same PR or a follow-up.
## Typography
@@ -44,6 +44,7 @@ These rules govern the Chinese side; the English side follows the repo's normal
- MUST put one half-width space between Chinese text and Latin words, and between Chinese text and numerals: `每个 plugin 注册 3 个 tool`。No space between a full-width punctuation mark and anything.
- MUST use full-width (Chinese) punctuation in Chinese prose: `，。：；？！（）「」`. Half-width punctuation stays inside code spans, inside complete English sentences quoted as-is, and in numbers (`3.5`, `1,024`).
+- Chinese prose *SHOULD* prefer colons, periods, commas, or parentheses over em dashes. Keep an em dash only when no other punctuation preserves the sentence naturally.
- Enumeration commas: a Chinese list of parallel items uses 顿号（、）, not commas.
- MUST NOT use full-width digits or full-width Latin letters — `１２３` never, `123` always.
- Proper nouns keep their canonical casing: GitHub, TypeScript, DeepSeek — never `github`/`Github` unless quoting code.
@@ -54,7 +55,7 @@ These rules govern the Chinese side; the English side follows the repo's normal
- A pair is done when a bilingual engineer reading either file alone gets everything a reader of the other gets — same facts, same caveats, same tone — and nothing extra.
- Before handing off, self-check the result against this file and re-read the counterpart ALONE, without the source side by side; awkward phrasing is easier to hear without the source anchoring you.
-- The mechanical contract (consistency record, switcher, structure, wrap, links) is checked by `pnpm run verify-translation-pairing` and the rest of `doc-sync` — run them; do not hand-verify what a gate covers.
+- Run `pnpm run verify-translation-pairing` and the rest of `doc-sync` for records, switchers, heading depths, code blocks, table row and column counts, list kinds, ordered-list starts, list item counts, links, and repository Markdown rules. Manually verify list and table order, noncanonical list numbering, inline code, emphasis, meaning, terminology, and tone.
## References
diff --git a/docs/i18n/translation-rules.zh.md b/docs/i18n/translation-rules.zh.md
index 1d8dcb04f1..04dd0a704e 100644
--- a/docs/i18n/translation-rules.zh.md
+++ b/docs/i18n/translation-rules.zh.md
@@ -12,21 +12,21 @@
## 行文
-- 语体以 [style-samples.md](style-samples.md) 为校准锚点——人工定稿的金标样例按文体各一组，译文必须对齐最接近的样例语体；样例与本文条款冲突时，以样例为准。目标语体是规范的技术制度文：完整主谓、确定语气，不口语化也不学术腔。
+- 语体以 [style-samples.md](style-samples.md) 为校准锚点。人工定稿的金标样例按文体各一组，译文必须参照文体最接近的样例，采用其中目标语言一侧的语体；如果样例与本文的行文规则冲突，以样例为准。译成中文时，采用规范的技术制度文；译成英文时，采用简洁、专业的开发者文档语体。
- 以母语技术作者的身份重述内容，而不是逐句转写的译者。写完后逐句对照原文核验：不添加、不遗漏——流畅永远不是丢掉语义成分的理由。
-- 给句子补显式执行主体：英文的被动句和抽象主语，中文写成「系统、门禁、评审人」等实际执行者做主语。
-- 优先使用中文工程惯用语而非直译（false positive/negative→误报／漏检、enforcement frontier→执行红线）；隐喻做本地化替换而不是移植，英文名词链展开为动词句。
+- 如果直译会让执行主体含糊，请明确写出实际执行者；译成中文时，应由「系统、门禁、评审人」等实际执行者作主语，避免含糊的被动句或抽象主语。
+- 优先采用目标语言中通行的工程表达，避免生硬直译（false positive/negative→误报／漏检、enforcement frontier→执行红线）；隐喻应自然改写，名词链则按目标语言的习惯拆开。
- 长段按语义单元拆分，一段一件事。段落边界可以与原文不同；结构签名不比对段落数。
-- 类别名词说中文并在首现括注英文（实操手册（cookbook））；指目录或文件本身时保留代码体英文。
+- 翻译为中文时，类别名词使用中文并在首现括注英文（实操手册（cookbook））；翻译为英文时，使用通行的英文类别名。指目录或文件本身时保留代码体英文。
## 结构保持
-结构一致性由配对门禁负责校验，译者无需为保持结构而牺牲行文的流畅：在既定框架内自然书写即可。配对的两个文件必须在以下方面一一对应：
+配对门禁会检查标题深度、围栏代码块、表格行列数、列表类型、有序列表起始编号、列表项数量与链接目标；门禁未覆盖的结构仍需人工核对。两个配对文件必须在以下方面一一对应：
- 标题层级（相同级别、相同顺序；标题的**文字**要翻译）；
- 列表形态与编号；
- 表格（相同的列、相同的行序；表头单元格按术语表翻译）；
-- 围栏代码块：**逐字节一致，包括注释**。代码属于受验证的范围（` ```ts ` 块要通过 `doc-typecheck` 编译），而被改动的注释是代码块计数门禁看不见的漂移；
+- 围栏代码块：**逐字节一致，包括注释**。配对签名比对信息字符串与内容，` ```ts ` 块还要通过 `doc-typecheck` 编译；
- 行内代码（命令、flag、配置键、文件路径、事件名、API 名、版本号）：原样保留，从不翻译或重排；
- 链接与锚点：每个相对链接在两个文件中必须指向相同的目标（按约定是 `.md` 路径而非 `.zh.md` 兄弟文件），这样即使某对文档先于相邻文件落地，链接也不会悬空。唯一的 zh 特有链接是语言切换行。链接**文字**翻译；链接目标不翻。
@@ -34,18 +34,19 @@
## 术语
-- [terminology.md](terminology.md) 是双向的术语真源。翻译前请先加载它；翻译过程中，表内的每个术语都*必须*严格按表中规定的译法呈现，包括首次出现的括注（如首现写 `agent（智能体）`，之后写 `agent`）与「不要译作」的禁项。中文先行撰写时，英文对侧同样按表中英文列使用术语。
-- 表中**没有**的技术术语，只有当某个主要中文 OSS 或厂商文档已有成型译法时（K8s／Vue／MDN 中文文档、微软简中风格指南、大厂项目文档）才*可以*翻译。请在 PR 中注明先例出处。
-- **没有**成型先例的术语，译文中*必须*保留英文，并且*必须*在 PR 描述的「待定术语」下列出，附上建议译法交评审者定夺。*禁止*就地发明中文译法，因为无先例的翻译恰恰会制造术语表要防止的歧义。确定下来的术语随后在同一个 PR 或后续 PR 中进入 [terminology.md](terminology.md)。
+- [terminology.md](terminology.md) 是双向的术语真源。翻译前请先加载它；表内术语必须遵守对应行与「不要译作」禁项。译成中文时，采用「中文」列，并按「首次出现」列括注；译成英文时，采用「English」列，不加中文括注。
+- 译成中文时，术语表未收录的技术术语只有在主流中文 OSS 文档或厂商资料中已有通行译法时才可以翻译（K8s／Vue／MDN 中文文档、微软简中风格指南、大厂项目文档），并须在 PR 中注明出处；否则必须保留英文，并在 PR 描述的「待定术语」中给出建议译法。
+- 译成英文时，采用通行的英文技术术语。如果源术语没有明确的通行对应词，则保留原词、附上简短说明，并列入「待定术语」。两个方向都不得自行创造译法；确定后的术语须在同一个 PR 或后续 PR 中加入 [terminology.md](terminology.md)。
## 排版
本节规则约束中文一侧；英文一侧遵循仓库常规的 Markdown 约定（根 `AGENTS.md`）。以下中西文混排规则遵循 [MDN 简体中文翻译指南](https://github.com/mdn/translated-content/blob/main/docs/zh-cn/translation-guide.md)、[Kubernetes 中文本地化指南](https://kubernetes.io/zh-cn/docs/contribute/localization_zh/)、[Vue.js 中文翻译须知](https://github.com/vuejs-translations/docs-zh-cn/wiki/%E7%BF%BB%E8%AF%91%E9%A1%BB%E7%9F%A5) 与[中文文案排版指北](https://github.com/sparanoid/chinese-copywriting-guidelines)的跨项目共识，其根据是 [W3C clreq](https://www.w3.org/TR/clreq/) 与 GB/T 15834—2011：
-- *必须*在中文与拉丁词之间、中文与数字之间各留一个半角空格：`每个 plugin 注册 3 个 tool`。全角标点与任何字符之间不加空格。
-- 中文行文*必须*使用全角（中文）标点：`，。：；？！（）「」`。半角标点保留在代码内、按原样引用的完整英文句子内、以及数字内（`3.5`、`1,024`）。
+- 必须在中文与拉丁词之间、中文与数字之间各留一个半角空格：`每个 plugin 注册 3 个 tool`。全角标点与任何字符之间不加空格。
+- 中文行文必须使用全角（中文）标点：`，。：；？！（）「」`。半角标点保留在代码内、按原样引用的完整英文句子内、以及数字内（`3.5`、`1,024`）。
+- 中文行文*应当*优先使用冒号、句号、逗号或括号，尽量不用破折号；只有其他标点都无法自然表达时才保留破折号。
- 顿号：中文的并列项之间使用顿号（、），而非逗号。
-- *禁止*使用全角数字或全角拉丁字母：永远不写 `１２３`，永远写 `123`。
+- 禁止使用全角数字或全角拉丁字母：永远不写 `１２３`，永远写 `123`。
- 专有名词保持规范大小写：GitHub、TypeScript、DeepSeek。除非引用代码，否则绝不写 `github`／`Github`。
- 第二人称用「你」，不用「您」（与 Vue、Kubernetes 中文约定及本仓库的直接语气一致）。
- 强调标记（`**加粗**`、`*斜体*`）落在与对侧相同的文字段上。中文没有斜体，渲染效果可能看不出差别，不要用引号或其他装饰替代。
@@ -54,7 +55,7 @@
- 一对文档的完成标准：一位双语工程师只读其中任一文件，能获得与另一文件读者完全相同的信息（相同的事实、相同的告诫、相同的语气），并且没有任何多余的内容。
- 交付前，请对照本文自查一遍，并**单独通读对侧文件**，不与源侧对照；不对照原文时，更容易察觉别扭的表达。
-- 机械契约（一致性记录、切换行、结构、折行、链接）由 `pnpm run verify-translation-pairing` 和 `doc-sync` 的其余门禁检查。请运行门禁；门禁已覆盖的内容无需手工核对。
+- 请运行 `pnpm run verify-translation-pairing` 与 `doc-sync` 的其余门禁。这些门禁会检查一致性记录、切换行、标题深度、代码块、表格行列数、列表类型、有序列表起始编号、列表项数量、链接及仓库 Markdown 规则；列表与表格的顺序、非常规列表编号、行内代码、强调标记、语义、术语和语体仍需人工核对。
## 参考资料
diff --git a/docs/module-graph.md b/docs/module-graph.md
index 0becb3bc4c..990692b6e5 100644
--- a/docs/module-graph.md
+++ b/docs/module-graph.md
@@ -125,6 +125,14 @@ flowchart TD
pkg_sandbox["sandbox"]
pkg_sandbox_local["sandbox-local"]
end
+ subgraph group_sdk["packages/sdk"]
+ pkg_helper["helper"]
+ pkg_scripts["scripts"]
+ end
+ subgraph group_tasks["packages/tasks"]
+ pkg_tasks["tasks"]
+ pkg_tool_tasks["tool-tasks"]
+ end
subgraph group_workflow["packages/workflow"]
pkg_tool_workflow["tool-workflow"]
pkg_workflow["workflow"]
@@ -132,6 +140,8 @@ flowchart TD
end
pkg_llm --> pkg_brand
pkg_code_runtime_worker --> pkg_code_runtime
+ pkg_helper --> pkg_brand
+ pkg_scripts --> pkg_app_boot
pkg_llm_deepseek --> pkg_llm
pkg_llm_pi_ai --> pkg_llm
pkg_session --> pkg_brand
@@ -150,7 +160,6 @@ flowchart TD
pkg_agent --> pkg_scope
pkg_agent --> pkg_session
pkg_agent --> pkg_system_prompt
- pkg_bash --> pkg_brand
pkg_bash --> pkg_sandbox
pkg_bash --> pkg_session
pkg_fs_local --> pkg_fs
@@ -199,6 +208,10 @@ flowchart TD
pkg_user_interaction --> pkg_llm
pkg_time_context --> pkg_agent
pkg_time_context --> pkg_system_prompt
+ pkg_tasks --> pkg_agent
+ pkg_tasks --> pkg_brand
+ pkg_tasks --> pkg_session
+ pkg_tasks --> pkg_timeout
pkg_workflow --> pkg_agent
pkg_workflow --> pkg_brand
pkg_workflow --> pkg_llm
@@ -232,6 +245,7 @@ flowchart TD
pkg_tool_bash --> pkg_llm
pkg_tool_bash --> pkg_sandbox
pkg_tool_bash --> pkg_system_prompt
+ pkg_tool_bash --> pkg_tasks
pkg_tool_bash --> pkg_tools
pkg_tool_bash --> pkg_user_approval
pkg_tool_fs --> pkg_fs
@@ -281,6 +295,10 @@ flowchart TD
pkg_repeat_tool_guard --> pkg_tools
pkg_mcp_client --> pkg_llm
pkg_mcp_client --> pkg_tools
+ pkg_tool_tasks --> pkg_agent
+ pkg_tool_tasks --> pkg_system_prompt
+ pkg_tool_tasks --> pkg_tasks
+ pkg_tool_tasks --> pkg_tools
pkg_tool_workflow --> pkg_agent
pkg_tool_workflow --> pkg_llm
pkg_tool_workflow --> pkg_system_prompt
@@ -299,6 +317,7 @@ flowchart TD
pkg_tool_subagent --> pkg_agent
pkg_tool_subagent --> pkg_llm
pkg_tool_subagent --> pkg_subagent
+ pkg_tool_subagent --> pkg_tasks
pkg_tool_subagent --> pkg_tools
pkg_hooks_claude --> pkg_agent
pkg_hooks_claude --> pkg_hook_protocol
@@ -322,8 +341,10 @@ flowchart TD
pkg_agent_spine_demo --> pkg_skill
pkg_agent_spine_demo --> pkg_skill_local
pkg_agent_spine_demo --> pkg_system_prompt
+ pkg_agent_spine_demo --> pkg_tasks
pkg_agent_spine_demo --> pkg_tool_bash
pkg_agent_spine_demo --> pkg_tool_skill
+ pkg_agent_spine_demo --> pkg_tool_tasks
pkg_agent_spine_demo --> pkg_tools
pkg_workflow_workerthread --> pkg_agent
pkg_workflow_workerthread --> pkg_brand
@@ -370,6 +391,8 @@ flowchart TD
| [`jsonrpc-demo`](../packages/examples/jsonrpc-demo) | `examples` | — |
| [`llm`](../packages/llm/llm) | `llm` | [`brand`](../packages/util/brand) |
| [`code-runtime-worker`](../packages/code-runtime/code-runtime-worker) | `code-runtime` | [`code-runtime`](../packages/code-runtime/code-runtime) |
+| [`helper`](../packages/sdk/helper) | `sdk` | [`brand`](../packages/util/brand) |
+| [`scripts`](../packages/sdk/scripts) | `sdk` | [`app-boot`](../packages/ui/app-boot) |
| [`llm-deepseek`](../packages/llm/llm-deepseek) | `llm` | [`llm`](../packages/llm/llm) |
| [`llm-pi-ai`](../packages/llm/llm-pi-ai) | `llm` | [`llm`](../packages/llm/llm) |
| [`session`](../packages/core/session) | `core` | [`brand`](../packages/util/brand), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope) |
@@ -379,7 +402,7 @@ flowchart TD
| [`sandbox`](../packages/sandbox/sandbox) | `sandbox` | [`llm`](../packages/llm/llm) |
| [`token-meter`](../packages/llm/token-meter) | `llm` | [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
| [`agent`](../packages/core/agent) | `core` | [`brand`](../packages/util/brand), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt) |
-| [`bash`](../packages/bash/bash) | `bash` | [`brand`](../packages/util/brand), [`sandbox`](../packages/sandbox/sandbox), [`session`](../packages/core/session) |
+| [`bash`](../packages/bash/bash) | `bash` | [`sandbox`](../packages/sandbox/sandbox), [`session`](../packages/core/session) |
| [`fs-local`](../packages/fs/fs-local) | `fs` | [`fs`](../packages/fs/fs) |
| [`fs-policy`](../packages/fs/fs-policy) | `fs` | [`fs`](../packages/fs/fs) |
| [`skill-local`](../packages/skill/skill-local) | `skill` | [`fs`](../packages/fs/fs), [`skill`](../packages/skill/skill) |
@@ -401,13 +424,14 @@ flowchart TD
| [`user-approval`](../packages/ui/user-approval) | `ui` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt) |
| [`user-interaction`](../packages/ui/user-interaction) | `ui` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm) |
| [`time-context`](../packages/context/time-context) | `context` | [`agent`](../packages/core/agent), [`system-prompt`](../packages/core/system-prompt) |
+| [`tasks`](../packages/tasks/tasks) | `tasks` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`session`](../packages/core/session), [`timeout`](../packages/util/timeout) |
| [`workflow`](../packages/workflow/workflow) | `workflow` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`llm`](../packages/llm/llm) |
| [`tools`](../packages/core/tools) | `core` | [`agent`](../packages/core/agent), [`code-runtime`](../packages/code-runtime/code-runtime), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt), [`user-approval`](../packages/ui/user-approval) |
| [`bash-sandbox`](../packages/bash/bash-sandbox) | `bash` | [`bash`](../packages/bash/bash), [`bash-local`](../packages/bash/bash-local), [`sandbox`](../packages/sandbox/sandbox) |
| [`permission`](../packages/ui/permission) | `ui` | [`bash`](../packages/bash/bash), [`sandbox`](../packages/sandbox/sandbox), [`session`](../packages/core/session), [`user-approval`](../packages/ui/user-approval) |
| [`stdio`](../packages/ui/stdio) | `ui` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`user-interaction`](../packages/ui/user-interaction) |
| [`agent-loop`](../packages/core/agent-loop) | `core` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) |
-| [`tool-bash`](../packages/bash/tool-bash) | `bash` | [`agent`](../packages/core/agent), [`bash`](../packages/bash/bash), [`llm`](../packages/llm/llm), [`sandbox`](../packages/sandbox/sandbox), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`user-approval`](../packages/ui/user-approval) |
+| [`tool-bash`](../packages/bash/tool-bash) | `bash` | [`agent`](../packages/core/agent), [`bash`](../packages/bash/bash), [`llm`](../packages/llm/llm), [`sandbox`](../packages/sandbox/sandbox), [`system-prompt`](../packages/core/system-prompt), [`tasks`](../packages/tasks/tasks), [`tools`](../packages/core/tools), [`user-approval`](../packages/ui/user-approval) |
| [`tool-fs`](../packages/fs/tool-fs) | `fs` | [`fs`](../packages/fs/fs), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) |
| [`tool-skill`](../packages/skill/tool-skill) | `skill` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`skill`](../packages/skill/skill), [`tools`](../packages/core/tools) |
| [`subagent`](../packages/subagent/subagent) | `subagent` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`tools`](../packages/core/tools) |
@@ -420,14 +444,15 @@ flowchart TD
| [`tool-ask-user`](../packages/ui/tool-ask-user) | `ui` | [`agent`](../packages/core/agent), [`tools`](../packages/core/tools), [`user-interaction`](../packages/ui/user-interaction) |
| [`repeat-tool-guard`](../packages/guard/repeat-tool-guard) | `guard` | [`agent`](../packages/core/agent), [`tools`](../packages/core/tools) |
| [`mcp-client`](../packages/mcp/mcp-client) | `mcp` | [`llm`](../packages/llm/llm), [`tools`](../packages/core/tools) |
+| [`tool-tasks`](../packages/tasks/tool-tasks) | `tasks` | [`agent`](../packages/core/agent), [`system-prompt`](../packages/core/system-prompt), [`tasks`](../packages/tasks/tasks), [`tools`](../packages/core/tools) |
| [`tool-workflow`](../packages/workflow/tool-workflow) | `workflow` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`workflow`](../packages/workflow/workflow) |
| [`subagent-acp`](../packages/subagent/subagent-acp) | `subagent` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`subagent`](../packages/subagent/subagent), [`subagent-subprocess`](../packages/subagent/subagent-subprocess) |
| [`subagent-inprocess`](../packages/subagent/subagent-inprocess) | `subagent` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) |
-| [`tool-subagent`](../packages/subagent/tool-subagent) | `subagent` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`subagent`](../packages/subagent/subagent), [`tools`](../packages/core/tools) |
+| [`tool-subagent`](../packages/subagent/tool-subagent) | `subagent` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`subagent`](../packages/subagent/subagent), [`tasks`](../packages/tasks/tasks), [`tools`](../packages/core/tools) |
| [`hooks-claude`](../packages/hooks/hooks-claude) | `hooks` | [`agent`](../packages/core/agent), [`hook-protocol`](../packages/hooks/hook-protocol), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`tools`](../packages/core/tools) |
| [`subagent-mock`](../packages/support/subagent-mock) | `support` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`subagent`](../packages/subagent/subagent) |
| [`jsonrpc`](../packages/ui/jsonrpc) | `ui` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`llm-deepseek`](../packages/llm/llm-deepseek), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent) |
-| [`agent-spine-demo`](../packages/examples/agent-spine-demo) | `examples` | [`agent`](../packages/core/agent), [`agent-loop`](../packages/core/agent-loop), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`skill`](../packages/skill/skill), [`skill-local`](../packages/skill/skill-local), [`system-prompt`](../packages/core/system-prompt), [`tool-bash`](../packages/bash/tool-bash), [`tool-skill`](../packages/skill/tool-skill), [`tools`](../packages/core/tools) |
+| [`agent-spine-demo`](../packages/examples/agent-spine-demo) | `examples` | [`agent`](../packages/core/agent), [`agent-loop`](../packages/core/agent-loop), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`skill`](../packages/skill/skill), [`skill-local`](../packages/skill/skill-local), [`system-prompt`](../packages/core/system-prompt), [`tasks`](../packages/tasks/tasks), [`tool-bash`](../packages/bash/tool-bash), [`tool-skill`](../packages/skill/tool-skill), [`tool-tasks`](../packages/tasks/tool-tasks), [`tools`](../packages/core/tools) |
| [`workflow-workerthread`](../packages/workflow/workflow-workerthread) | `workflow` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`tools`](../packages/core/tools), [`workflow`](../packages/workflow/workflow) |
| [`subagent-fork`](../packages/subagent/subagent-fork) | `subagent` | [`agent`](../packages/core/agent), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`subagent-inprocess`](../packages/subagent/subagent-inprocess) |
| [`subagent-spawn`](../packages/subagent/subagent-spawn) | `subagent` | [`subagent`](../packages/subagent/subagent), [`subagent-inprocess`](../packages/subagent/subagent-inprocess) |
diff --git a/docs/rfc/INDEX.md b/docs/rfc/INDEX.md
index 926c62676c..b9408ed06a 100644
--- a/docs/rfc/INDEX.md
+++ b/docs/rfc/INDEX.md
@@ -13,6 +13,7 @@ Generated by `pnpm run gen-rfc-index` from the RFC tree — never edit by hand;
| [Interactive side sessions and merge-back](proposed/feature/2026-07-08-interactive-side-sessions.md) | 2026-07-08 |
| [SQLite FTS5 session search](proposed/feature/2026-07-10-sqlite-session-query-provider.md) | 2026-07-10 |
| [Stream workflow progress through tool calls](proposed/feature/2026-07-13-stream-workflow-progress-through-tool-calls.md) | 2026-07-13 |
+| [Developer-owned SDK projects](proposed/feature/2026-07-14-sdk-developer-projects.md) | 2026-07-14 |
### Simplification
@@ -27,7 +28,7 @@ Generated by `pnpm run gen-rfc-index` from the RFC tree — never edit by hand;
| Title | First proposed |
|---|---|
| [Runtime schemas for the event vocabulary (Zod vs the merge-extensible-map pattern)](proposed/architecture/2026-06-16-typed-event-schemas.md) | 2026-06-16 |
-| [Extract a generic long-running tool runtime](proposed/architecture/2026-06-20-generic-long-running-tool-runtime.md) | 2026-06-20 |
+| [SDK project editing architecture](proposed/architecture/2026-07-15-sdk-project-editing-architecture.md) | 2026-07-15 |
### Process
@@ -37,6 +38,7 @@ Generated by `pnpm run gen-rfc-index` from the RFC tree — never edit by hand;
| [Architectural conformance — dependency rules and the adapter kit](proposed/process/2026-06-11-architectural-conformance.md) | 2026-06-11 |
| [Supply chain checks and vendor drift verification](proposed/process/2026-06-11-supply-chain-and-vendor-drift.md) | 2026-06-11 |
| [Discover package inventories instead of maintaining static lists](proposed/process/2026-06-20-discover-package-inventory.md) | 2026-06-20 |
+| [Periodic human-review maintenance for dsh-code-review](proposed/process/2026-07-13-human-review-skill-maintenance.md) | 2026-07-13 |
### Testing
@@ -73,6 +75,7 @@ Generated by `pnpm run gen-rfc-index` from the RFC tree — never edit by hand;
| [The subprocess sandbox — confinement seam, native runners, escalation, and per-session modes](implemented/feature/2026-07-06-sandbox.md) | 2026-07-06 |
| [MCP client plugin — connect to external MCP servers and bridge their tools](implemented/feature/2026-07-07-mcp-client-plugin.md) | 2026-07-07 |
| [The session prefix — request-only messages in front of the derived history](implemented/feature/2026-07-07-session-prefix.md) | 2026-07-07 |
+| [Background subagent tasks](implemented/feature/2026-07-08-background-subagent-tasks.md) | 2026-07-08 |
| [Repeat-tool-call guard plugin](implemented/feature/2026-07-08-repeat-tool-guard.md) | 2026-07-08 |
| [The self-referential cordis toolset](implemented/feature/2026-07-08-self-referential-cordis-toolset.md) | 2026-07-08 |
| [Exact session query service](implemented/feature/2026-07-10-session-query-service.md) | 2026-07-10 |
@@ -127,6 +130,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 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 |
diff --git a/docs/rfc/implemented/architecture/2026-06-13-capability-seams.md b/docs/rfc/implemented/architecture/2026-06-13-capability-seams.md
index 907e4cd86b..6887660de0 100644
--- a/docs/rfc/implemented/architecture/2026-06-13-capability-seams.md
+++ b/docs/rfc/implemented/architecture/2026-06-13-capability-seams.md
@@ -12,9 +12,9 @@ This is distinct from "who provides vs. needs a capability at runtime", which Co
A swappable capability is **three packages**:
-1. **Interface** — an abstract service + the vocabulary types, owning the `ctx.` and depending only on cordis (e.g. `dsh-bash`: `BashExecutor`, `BashRunResult`, `BashTask`).
+1. **Interface** — an abstract service + the vocabulary types, owning the `ctx.` and depending only on its vocabulary dependencies (e.g. `dsh-bash`: `BashExecutor`, `BashRunResult`, `BashProcess`).
2. **Implementation** — a concrete subclass loaded as a plugin (e.g. `dsh-bash-local`: subprocesses, process-group kills, spill-file truncation). Sandboxed/remote backends are sibling packages implementing the same interface.
-3. **Consumer** — what the model and plugins see (e.g. `dsh-tool-bash`: the `bash`/`bash_output`/`bash_kill` tool schemas). Consumers `inject` the interface key and never import implementation types.
+3. **Consumer** — what the model and plugins see (e.g. `dsh-tool-bash`: the `bash` schema, with background handles registered into the generic task runtime). Consumers `inject` the interface key and never import implementation types.
Implementation and consumer then evolve independently: a sandboxed executor replaces `dsh-bash-local` without touching a tool schema.
diff --git a/docs/rfc/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md b/docs/rfc/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md
new file mode 100644
index 0000000000..c99eb9f0fe
--- /dev/null
+++ b/docs/rfc/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md
@@ -0,0 +1,128 @@
+# RFC: The background task runtime (`ctx.tasks`) and generic task control tools
+
+Status: implemented
+
+## Problem
+
+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 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:
+
+- `@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.
+
+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.
+
+`TaskService` is a concrete, process-local service. TODO(task-service-backend): separate its public contract from the implementation when a second backend defines the required lifecycle; a systemd-backed runtime is one plausible driver, but this PR does not speculate about its durability, reconnect, ownership, or observation semantics.
+
+## Runtime contract
+
+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.
+
+The producer hooks define three responsibilities:
+
+- `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`.
+
+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 kinds form a merge-extensible string union, and task ids are branded and generated as `-N`, with a counter per kind.
+
+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.
+
+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.
+
+## Authorization and owner lifecycle
+
+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.
+
+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.
+
+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.
+
+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.
+
+## Service surface
+
+`TaskService` provides:
+
+- `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.
+
+`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.
+
+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.
+
+## Model-facing control surface
+
+`dsh-tool-tasks` registers three kind-independent tools with generic ACP cards:
+
+- `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 ` [] — `, 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.
+
+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.
+
+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.
+
+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.
+
+## Producer opt-in
+
+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.
+
+`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.
+
+## Producer integrations
+
+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.
+
+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.
+
+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
+
+### Per-capability control tools
+
+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.
+
+### An immediate abstract task-runtime backend
+
+The current `TaskStart.run()` contract passes in-process callbacks and exact `Agent` objects. A durable backend changes identity, restart, ownership, and observation semantics, so extracting an interface before a second implementation exists would freeze the wrong boundary.
+
+### Consumer-owned authorization or cleanup events
+
+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.
+
+### Blocking output or a separate wait tool
+
+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.
+
+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.
+
+### Runtime-owned output sinks
+
+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.
+
+### Random ids, promotion, or lifecycle session events
+
+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 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
+
+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.
+
+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.
diff --git a/docs/rfc/implemented/architecture/2026-07-02-tool-render-intent-union.md b/docs/rfc/implemented/architecture/2026-07-02-tool-render-intent-union.md
index cdaf152d73..37507c0c55 100644
--- a/docs/rfc/implemented/architecture/2026-07-02-tool-render-intent-union.md
+++ b/docs/rfc/implemented/architecture/2026-07-02-tool-render-intent-union.md
@@ -43,7 +43,7 @@ interface TerminalResultView { card: 'terminal'; title?: string; output?: string
### Producer mapping
- `dsh-tool-fs` read → `generic` (`kind:'read'`, a follow-along `location`); write → `diff` (`oldText:null`); edit → `diff` (`oldText:old_string || null`, `newText:new_string ?? ''`). This mirrors `claude-agent-acp`'s `toolInfoFromToolUse` Read/Write/Edit arms field-for-field.
-- `dsh-tool-bash` foreground → `terminal` call + `terminal` result; `run_in_background` and `bash_output`/`bash_kill` → `generic`.
+- `dsh-tool-bash` foreground → `terminal` call + `terminal` result; `run_in_background` → `generic`. The generic `task_*` controls own their own generic cards.
- `dsh-tool-todo` → `generic`.
### Terminal fallback ownership
diff --git a/docs/rfc/implemented/architecture/2026-07-07-tool-call-timeout-policy.md b/docs/rfc/implemented/architecture/2026-07-07-tool-call-timeout-policy.md
index 7bd4e2462d..1e516a9aa0 100644
--- a/docs/rfc/implemented/architecture/2026-07-07-tool-call-timeout-policy.md
+++ b/docs/rfc/implemented/architecture/2026-07-07-tool-call-timeout-policy.md
@@ -78,7 +78,7 @@ No new session event is needed for reconstructability: `TOOL_TIMEOUT` is the fin
`bash` stays on the current backend timeout path. `dsh-tool-bash` continues to expose `timeoutMs` and `run_in_background`; `dsh-bash-local` continues to use `@deepseek-ai/dsh-timeout` for `BASH_TIMEOUT`; hook bridges continue to call `runHook()` and pass `timeoutMs` through `ctx.bash`. This keeps foreground/background/hook behavior stable.
-`read`, `write`, `edit`, `todo_write`, `bash_output`, and `bash_kill` do not opt into tool-call timeout: they are local filesystem or short registry/session operations where a deadline would be best-effort only or unnecessary.
+`read`, `write`, `edit`, `todo_write`, `task_list`, and `task_kill` do not opt into tool-call timeout. `task_output` owns its bounded wait because a wait timeout is a successful live-status result, not a tool failure.
A future model-facing grep/glob tool can be implemented on top of `ctx.bash` without importing `@deepseek-ai/dsh-timeout`: it forwards `exec.signal` to `ctx.bash`, and declares its own `timeoutMs` (from its plugin's config) for the enforcer to apply. If bash-local's backend timeout becomes a problem for such a tool, the bash seam can later add a caller-owned-deadline mode; that is outside this cut.
diff --git a/docs/rfc/implemented/feature/2026-06-21-subagent-capability-seam.md b/docs/rfc/implemented/feature/2026-06-21-subagent-capability-seam.md
index e2871532c8..83c7beb440 100644
--- a/docs/rfc/implemented/feature/2026-06-21-subagent-capability-seam.md
+++ b/docs/rfc/implemented/feature/2026-06-21-subagent-capability-seam.md
@@ -67,6 +67,6 @@ The seam is tested through the real Cordis Loader/export path, which catches the
## Consequences
- **Recursion.** Without a bound, an in-process child can see the delegation tool and recurse. The in-process backends implement the optional absolute depth limit and scoped live-global `toolFilter`; ACP advertises both capabilities off and rejects such a request. The [subagent composition-controls RFC](2026-07-12-subagent-persona-tool-filter-and-depth.md) owns their exact semantics and security limits.
-- **Blocking the parent turn.** Synchronous collect holds the parent's `runStep` open for the child's full duration. This is acceptable for the first cut; **background / poll / spill semantics are deferred to a future redesign that unifies long-running-tool handling across subagents AND bash** (a sub-agent and a long `bash` background task pose the same "the model started something slow, how does it collect later" problem, and should share one mechanism rather than each inventing its own).
+- **Blocking the parent turn.** Foreground collection holds the parent's step open for the child's full duration. Background delegation uses the shared `ctx.tasks` runtime and generic `task_*` tools, the same collection mechanism as background bash; the subagent seam itself remains task-agnostic.
- **Live progress.** This cut surfaces only lifecycle + final result; a per-chunk child→parent update stream is deferred with the background redesign.
- **ACP client surface.** Proxying `fs`/`terminal` from the ACP child back to the parent (a shared-workspace mode) is future work; the first cut advertises neither, so the child self-serves in its own process.
diff --git a/docs/rfc/implemented/feature/2026-07-06-sandbox.md b/docs/rfc/implemented/feature/2026-07-06-sandbox.md
index 28f2066ee9..68208b1d66 100644
--- a/docs/rfc/implemented/feature/2026-07-06-sandbox.md
+++ b/docs/rfc/implemented/feature/2026-07-06-sandbox.md
@@ -70,7 +70,7 @@ Backend profiles share the mode contract but differ in necessary host grants. La
#### The bash consumer
-`dsh-bash-sandbox` reuses local process execution and asks `ctx.sandbox` to wrap the exact bash argv. A kernel denial is a result fact independent of exit status and is inferred only from the selected wrap's stderr dialect. Runner failure outranks denial because it means the command never ran: foreground calls throw `SANDBOX_UNAVAILABLE`, while settled background tasks set `sandbox.runnerFailed` for `bash_output`. This keeps broken confinement distinct from both task failure and an enforced denial.
+`dsh-bash-sandbox` extends `LocalBashExecutor` and hands `ctx.sandbox` the exact `['bash', '-c', command]` argv it is about to spawn. A denial is an orthogonal result fact, conservatively classified from the active runner's stderr dialect. A runner failure outranks denial: foreground execution throws `SANDBOX_UNAVAILABLE`; a settled `BashProcess` stamps `sandbox.runnerFailed`, and the bash producer renders it through generic `task_output`.
The model's view is result facts only: the static tool description explains the denial marker (`[sandbox: file access denied under mode]`), encourages attempting commands that may be denied, and forbids retrying around a denial; when the escalation fields are advertised, a denied result additionally carries the escalation hint itself, so the sanctioned same-turn retry is prompted at the decision point rather than depending on the model recalling the description (§ Escalation). No prompt section states the sandbox mode (§ Per-session modes).
@@ -78,13 +78,13 @@ The model's view is result facts only: the static tool description explains the
`BashExecRequest.sandboxMode` is an optional per-call input; resolved specs make the field explicit. `BashExecutor.sandboxMode` advertises whether the mounted executor can honor it, so only a confining composition exposes escalation. The seam accepts any explicit mode; the tool owns the wider-only escalation rule. Non-sandboxing executors remain honestly unconfined.
-`SandboxBashExecutor.resolve()` stamps the effective mode — escalation grant > session override > configured default — so `run()`/`start()` read the spec, never the config. The `danger-full-access` branch, the confine call, and the result facts all key off the spec's mode, and the per-task facts map carries each task's mode alongside its wrap facts (`notifyTaskDone()` stamps from the map entry): one escalated call — foreground or background — reports the mode it ACTUALLY ran under while every neighbor keeps its own.
+`SandboxBashExecutor.resolve()` stamps the effective mode — escalation grant > session override > configured default — so `run()`/`start()` read the spec, never the config. Per-process wrap facts are keyed by the returned `BashProcess`; `onProcessDone()` classifies stderr and stamps that handle before `done` resolves, so overlapping processes retain their own modes and runner dialects.
When a confining executor is mounted, `bash` advertises paired `sandbox_permissions` and `justification` fields. The schema exposes the full closed escalation vocabulary because effective mode is per-session; execution rejects any target that is not strictly wider than that call's effective mode. Approval resolves before execution. `allowed-once` stamps the granted mode onto only that request, while `rejected`, `cancelled`, `unavailable`, a missing approval service, or a missing agent all fail closed with distinct results. No grant is persisted.
Escalation is a same-turn retry of the denied command with the narrowest sufficient `sandbox_permissions` and a `justification`; the approval prompt is the consent step. It must be grounded in an actual denial, except when the session already observed the same denied access, and a disabled or rejected approval ends that command. The retry, approval decision, and result use existing tool and approval events. `dsh-tool-bash` owns the ask because the executor seam has neither the agent nor call id required for user interaction.
-Left open, recorded for the phase that picks them up: what a grant's scope identity is beyond the sandbox mode — the exact call, a path, a command prefix, the session, a time window — the question `allow_always` grant storage must answer before that option can be advertised; and how escalation is defined for `run_in_background` denials that arrive via `bash_output`.
+Left open: what a durable grant's scope identity is beyond the sandbox mode — exact call, path, command prefix, session, or time window — before an `allow_always` option can be advertised.
#### Per-session modes: the session log as the store
@@ -194,8 +194,8 @@ Costs and accepted limits:
- **`bwrap` is installed on my host but unusable (disabled unprivileged userns, an LSM denying `mount`) — what happens?** The chain probe is functional — it builds and enforces a real profile rather than checking `--version` — so a present-but-unusable `bwrap` fails its probe, selection falls to the registry-installed Landlock launcher, and the verdict is cached for the provider's lifetime.
- **Does the sandbox restrict network or process visibility?** No — `SandboxMode` claims FILE effects only; the bwrap profile deliberately does not unshare pid, and no backend claims network. Whether network restriction becomes its own knob is left open in § The seam.
- **Which tools actually run confined?** OS subprocesses through `ctx.bash` — the bash tools, and hook commands transitively. fs/web/todo execute in-process, where an `execve` wrapper is mechanically meaningless; their `read-only` semantics arrive with the cross-family deferred phase, and until then the contract says bash-only honestly.
-- **Does a granted escalation persist, or cover background tasks?** Neither: the grant is consumed by the very call that asked (foreground or background), that one call reports the mode it actually ran under, and every neighbor keeps its own. How escalation should be DEFINED for a background denial that only surfaces later via `bash_output` is left open in § Escalation.
-- **When does an editor's mode switch take effect?** Mid-turn: appended immediately, honored by the very next call's stamp. Idle: held on the bridge's session record, anchored at the next `agent/prompt-submit` inside its open turn, with N flips coalescing to at most one event (none if net-zero); a crash before anchoring reverts it and `session/load` reports the truth. The model is not told — its next command simply behaves under the new mode.
+- **Does a granted escalation persist?** No. The grant is consumed by the exact foreground or background call that asked; every neighboring call keeps its own effective mode. A later background denial surfaces through `task_output` and may ground a new exact-command retry.
+- **When does an editor's mode switch take effect?** Mid-turn: appended immediately, honored by the very next call's stamp. Idle: held on the bridge's session record, anchored at the next turn's `agent/prompt-submit`, with N flips coalescing to at most one event (none if net-zero); a crash before anchoring reverts it and `session/load` reports the truth. The model is not told — its next command simply behaves under the new mode.
- **What survives a restart — and what if the operator changed the config default while the process was down?** Overrides replay from the session log (`effective = fold ?? config`), so a resumed session keeps its modes with zero catch-up machinery; a default that drifted offline changes behavior the same way a switch does (the approval policy, being stated, is additionally narrated with operator/config attribution).
- **What does `enforcement: 'partial'` on a result mean?** The selected backend enforces the subset its kernel ABI governs — e.g. Landlock before ABI v3 does not govern path truncate — and says so structurally instead of refusing the host; the probe's report line distinguishes the cases. The bwrap and Seatbelt profiles govern every promised file effect by construction, so they always report `full`.
@@ -204,7 +204,7 @@ Costs and accepted limits:
In-repo precedents this design copies or contrasts with:
- [The capability-seams RFC](../architecture/2026-06-13-capability-seams.md) — the interface/implementation/consumer split and the "don't split preemptively" timing rule the second consumer satisfied.
-- The `dsh-bash` request/spec split and its `owner` field ([the bash vocabulary catalog](../../../core-data-structures/bash.md)) — the per-call carrier template `sandboxMode` rides, and the explicit-`resolve()` defaulting convention.
+- The `dsh-bash` request/spec split ([the bash vocabulary catalog](../../../core-data-structures/bash.md)) — the per-call carrier template `sandboxMode` rides, and the explicit-`resolve()` defaulting convention.
- [The approval seam RFC](2026-07-06-approval-seam.md) — the channel escalation asks through; its answerer waterfall, audit pair, and one-package rationale are recorded there.
- [Event-sourced sessions](../architecture/2026-06-11-event-sourced-sessions.md) and [the turn-enclosure invariant](../architecture/2026-06-15-turn-enclosure-invariant.md) — the log-as-store foundation the per-session modes fold over, and the commit boundary the anchoring design obeys.
- [The interception-seams RFC](2026-06-30-interception-seams.md) — the `tools/pre-execute` vocabulary the escalation gate deliberately does not reuse (an escalating call has no pre-execute moment of its own).
diff --git a/docs/rfc/implemented/feature/2026-07-08-background-subagent-tasks.md b/docs/rfc/implemented/feature/2026-07-08-background-subagent-tasks.md
new file mode 100644
index 0000000000..830d93577b
--- /dev/null
+++ b/docs/rfc/implemented/feature/2026-07-08-background-subagent-tasks.md
@@ -0,0 +1,62 @@
+# RFC: Background subagent tasks
+
+Status: implemented
+
+## Problem
+
+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.
+
+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`, 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.
+
+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.
+
+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 task registration maps the subagent seam as follows:
+
+- `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
+
+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 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
+
+### Subagent-specific wait, output, and stop tools
+
+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.
+
+### Survival after owner closure
+
+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.
+
+### No owner checks for isolated clients
+
+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.
+
+### Incremental child transcript output
+
+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 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
+
+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.
diff --git a/docs/rfc/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.i18n.yaml b/docs/rfc/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.i18n.yaml
index f20250c3ba..5f83acc3aa 100644
--- a/docs/rfc/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.i18n.yaml
+++ b/docs/rfc/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.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
-2026-07-02-bilingual-docs-and-pairing-gate.md: 1e96622e7fb5694ab61772d68744394ef1aeb53a
-2026-07-02-bilingual-docs-and-pairing-gate.zh.md: c752d76f12f556ce190bf80c4f3a531c0821be8e
+2026-07-02-bilingual-docs-and-pairing-gate.md: 68c0f3bbc0472b0c96f9d64fc6b1b24ac7008795
+2026-07-02-bilingual-docs-and-pairing-gate.zh.md: 2cf8f9b9c17d8a521d8674833e909b34f315cfe0
diff --git a/docs/rfc/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.md b/docs/rfc/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.md
index 1e96622e7f..68c0f3bbc0 100644
--- a/docs/rfc/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.md
+++ b/docs/rfc/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.md
@@ -12,7 +12,7 @@ This repo's README and docs tree are read by people and agents inside and outsid
- **Paired sibling files with equal authority.** A documentation pair is three sibling files: English `foo.md`, Chinese `foo.zh.md`, and a consistency record `foo.i18n.yaml`. Neither language is canonical — a document may be authored and reviewed Chinese-first and translated to English afterwards, or the reverse; what binds the pair is that both sides must say the same thing, and pairs merge whole (both languages plus the record, never one alone). Policy: [docs/i18n/README.md](../../../i18n/README.md); translation rules: [docs/i18n/translation-rules.md](../../../i18n/translation-rules.md); terminology source of truth: [docs/i18n/terminology.md](../../../i18n/terminology.md).
- **A sidecar record of both blob hashes makes consistency checkable.** `foo.i18n.yaml` holds the full git blob hash of each side as of the last confirmed-consistent state. An edit to either side without re-confirming the pair is then mechanically detectable as a pure content comparison — no history lookup — and the hashes are computable for files edited in the same PR, which a commit-hash record is not. Re-recording (`verify-translation-pairing --write`) produces a reviewable yaml diff: confirming consistency is an explicit, visible act in the PR.
-- **`verify-translation-pairing` joins `doc-sync`.** The gate ([scripts/verify-translation-pairing.ts](../../../../scripts/verify-translation-pairing.ts)) enforces: required pairs exist, every existing pair is complete (all three files) and consistent (both hashes match, switcher links both ways, structural signatures identical), and excluded (generated or bilingual-by-construction) files stay unpaired. The `required` list in [scripts/translation-pairing.manifest.json](../../../../scripts/translation-pairing.manifest.json) is a ratchet: each merged translation batch adds its files, so coverage only grows.
+- **`verify-translation-pairing` joins `doc-sync`.** The gate ([scripts/verify-translation-pairing.ts](../../../../scripts/verify-translation-pairing.ts)) enforces: required pairs exist, every existing pair is complete (all three files) and consistent (both hashes match, switcher links both ways, structural signatures identical), excluded (generated or bilingual-by-construction) files stay unpaired, and date-named documents on or after the manifest's `requiredSince` cutoff have complete pairs. The `required` list in [scripts/translation-pairing.manifest.json](../../../../scripts/translation-pairing.manifest.json) is a ratchet: each merged translation batch adds its files, so coverage only grows.
- **Translation is agent work with human review.** The committed workflow is [.agents/skills/dsh-translate-docs](../../../../.agents/skills/dsh-translate-docs/SKILL.md), following the same pattern as [dsh-code-review](../../../../.agents/skills/dsh-code-review/SKILL.md): the skill carries the workflow and defers to the docs as sources of truth.
## Alternatives considered
@@ -34,5 +34,5 @@ Paired sibling files with locale suffixes are the dominant Chinese big-tech conv
- Every pair adds a third file to the tree. The record is machine-written (`--write`), so the cost is directory noise, not maintenance effort; in exchange, "who confirmed these consistent, and when" is answerable from git blame on the yaml.
- When the two sides disagree, no mechanical rule picks a winner — the PR review does. That is the price of equal authority, accepted deliberately: the alternative (a canonical language) forbids Chinese-first authoring.
- Generated docs (`cordis-catalog/`, `tool-catalog/`, `module-graph.md`) are excluded for now; the planned follow-up is to teach their generators to emit Chinese alongside English, at which point they leave the exclusion list.
-- Rollout is incremental by design: documents outside `required` are visible backlog (`--list`), not red CI, so pairs land in reviewable batches without a big-bang PR. New documents are the exception — a date-named document dated on/after the manifest's `requiredSince` cutoff merges bilingual or not at all, so the backlog only ever shrinks.
+- Rollout is incremental by design: documents outside `required` are visible backlog (`--list`), not red CI, so pairs land in reviewable batches without a big-bang PR. A date-named document dated on or after the manifest's `requiredSince` cutoff merges bilingual or not at all, so new date-named RFCs do not enlarge that backlog.
- The recorded hashes double as the update tool (`git cat-file -p ` recovers either side's last-confirmed text for a minimal diff-based update), so re-translation of whole files is never forced by the mechanism.
diff --git a/docs/rfc/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.zh.md b/docs/rfc/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.zh.md
index c752d76f12..2cf8f9b9c1 100644
--- a/docs/rfc/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.zh.md
+++ b/docs/rfc/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.zh.md
@@ -11,9 +11,9 @@ Status: implemented
## 决策
- **配对兄弟文件，两种语言同权。** 一对文档由三个兄弟文件组成：英文 `foo.md`、中文 `foo.zh.md`，以及一份一致性记录 `foo.i18n.yaml`。没有哪种语言是正典：一篇文档可以先用中文撰写和评审、之后再译成英文，反之亦可；约束配对的是：两侧必须表达相同的内容，且配对整体合并（两种语言加记录，绝不单独落一侧）。政策见 [docs/i18n/README.md](../../../i18n/README.md)；翻译规则见 [docs/i18n/translation-rules.md](../../../i18n/translation-rules.md)；术语真源见 [docs/i18n/terminology.md](../../../i18n/terminology.md)。
-- **伴随记录保存两侧 blob hash，使一致性可检查。** `foo.i18n.yaml` 保存两侧文件在上一次确认一致时各自的完整 git blob hash。此后修改了任一侧而未重新确认配对，都能被机械检测出来（纯内容比较，无需查询历史），而且同一个 PR 内改动的文件也能计算出 hash，commit hash 式的记录做不到这一点。重新记录（`verify-translation-pairing --write`）会产生一份可评审的 yaml diff：确认一致在 PR 中是一个显式、可见的动作。
-- **`verify-translation-pairing` 加入 `doc-sync`。** 门禁（[scripts/verify-translation-pairing.ts](../../../../scripts/verify-translation-pairing.ts)）强制执行以下规则：required 的配对必须存在；任何已存在的配对必须完整（三个文件齐全）且一致（两个 hash 匹配、切换行双向互链、结构签名一致）；被排除的文件（生成物或本身即双语的）保持不配对。[scripts/translation-pairing.manifest.json](../../../../scripts/translation-pairing.manifest.json) 中的 `required` 清单只进不退：每个合并的翻译批次将自己的文件加入其中，覆盖面只增不减。
-- **翻译是 agent 的工作，由人评审。** 仓库内置的工作流是 [.agents/skills/dsh-translate-docs](../../../../.agents/skills/dsh-translate-docs/SKILL.md)，与 [dsh-code-review](../../../../.agents/skills/dsh-code-review/SKILL.md) 模式相同：skill 承载工作流，并将文档作为真源。
+- **伴随记录保存两侧 blob hash，使一致性可检查。** `foo.i18n.yaml` 保存两侧文件在上一次确认一致时各自的完整 git blob hash。此后修改了任一侧而未重新确认配对，都能被机械检测出来（纯内容比较，无需查询历史），而且同一个 PR（Pull Request）内改动的文件也能计算出 hash，commit hash 式的记录做不到这一点。重新记录（`verify-translation-pairing --write`）会产生一份可评审的 yaml diff：确认一致在 PR 中是一个显式、可见的动作。
+- **`verify-translation-pairing` 加入 `doc-sync`。** 门禁（[scripts/verify-translation-pairing.ts](../../../../scripts/verify-translation-pairing.ts)）强制执行以下规则：required 的配对必须存在；任何已存在的配对必须完整（三个文件齐全）且一致（两个 hash 匹配、切换行双向互链、结构签名一致）；被排除的文件（生成物或本身即双语的）不得配对；凡文件名以日期开头且日期不早于 manifest（元数据清单）中 `requiredSince` 分界日期的文档，也必须有完整配对。[scripts/translation-pairing.manifest.json](../../../../scripts/translation-pairing.manifest.json) 中的 `required` 清单只进不退：每个合并的翻译批次将自己的文件加入其中，覆盖面只增不减。
+- **翻译是 agent 的工作，由人评审。** 仓库内置的工作流是 [.agents/skills/dsh-translate-docs](../../../../.agents/skills/dsh-translate-docs/SKILL.md)，与 [dsh-code-review](../../../../.agents/skills/dsh-code-review/SKILL.md) 模式相同：skill（技能）承载工作流，并将文档作为真源。
## 曾考虑的替代方案
@@ -34,5 +34,5 @@ Status: implemented
- 每个配对给目录树多添一个文件。记录由机器写入（`--write`），代价是目录噪音而非维护负担；换来的是「谁在何时确认过这对文档一致」可以从 yaml 的 git blame 直接回答。
- 两侧说法冲突时，没有机械规则裁决谁赢，由 PR 评审裁决。这是同权的代价，且是有意接受的：另一个选项（正典语言）会禁止中文先行撰写。
- 生成文档（`cordis-catalog/`、`tool-catalog/`、`module-graph.md`）暂被排除；计划中的后续工作是让生成器在输出英文的同时输出中文，届时将这些文件移出排除清单。
-- 推进天然是渐进的：`required` 之外的文档是可见的 backlog（`--list`），而非红色的 CI；因此配对按可评审的批次落地，无需一个巨型 PR。
+- 推进天然是渐进的：`required` 之外的文档是可见的 backlog（待翻清单，`--list`），而非红色的 CI；因此配对按可评审的批次落地，无需一个巨型 PR。凡文件名以日期开头且日期不早于 manifest 中 `requiredSince` 分界日期的文档，都必须配齐双语文件，因此新建的日期命名 RFC 不会增加这份 backlog。
- 记录的 hash 兼作更新工具（`git cat-file -p ` 能还原任一侧上次确认的文本，用于基于 diff 的最小更新），因此这套机制从不强迫整篇重译。
diff --git a/docs/rfc/implemented/process/2026-07-02-tool-schema-catalog.md b/docs/rfc/implemented/process/2026-07-02-tool-schema-catalog.md
index 7d79f73583..7da1a05a3a 100644
--- a/docs/rfc/implemented/process/2026-07-02-tool-schema-catalog.md
+++ b/docs/rfc/implemented/process/2026-07-02-tool-schema-catalog.md
@@ -31,7 +31,7 @@ The filesystem discovers the tool-package inventory and the completeness guard r
### Scope
-Shipped product tool PACKAGES under `packages/*/tool-*`, each booted with its default config: `dsh-tool-bash` (`bash`, `bash_output`, `bash_kill`), `dsh-tool-todo` (`todo_write`), `dsh-tool-subagent` (`subagent`). The `examples/` demo tools (`echo`) are excluded, matching the cordis catalog's packages-only scope — a demo tool is not part of the product surface a reader is cataloguing.
+Shipped product tool packages under `packages/*/tool-*`, each booted with its default config, including `dsh-tool-bash` (`bash`), `dsh-tool-tasks` (`task_output`, `task_list`, `task_kill`), and `dsh-tool-subagent` (`subagent`). Example-only tools are excluded.
The catalog unit is a package, not every configured tool instance. Each package boots once with default config; load-time aliases such as `subagent_fork` are noted without enumerating every deployment permutation. A deployment inventory is a separate, unbounded surface.
diff --git a/docs/rfc/proposed/architecture/2026-06-20-generic-long-running-tool-runtime.md b/docs/rfc/proposed/architecture/2026-06-20-generic-long-running-tool-runtime.md
deleted file mode 100644
index 5ed9c6354e..0000000000
--- a/docs/rfc/proposed/architecture/2026-06-20-generic-long-running-tool-runtime.md
+++ /dev/null
@@ -1,41 +0,0 @@
-# RFC: Extract a generic long-running tool runtime
-
-Status: proposed
-
-## Problem
-
-The bash capability seam supports both foreground commands and long-running background tasks. Background support is large: the abstract executor exposes `start`, `get`, `ownerOf`, `list`, `readOutput`, `kill`, and `onTaskDone`; the local executor tracks tasks, incremental reads, owner tokens, process cleanup, and completion listeners; the model sees three tools (`bash`, `bash_output`, `bash_kill`); the tool plugin injects completion notices back into the owning agent's session. The local executor fences task access behind owner tokens because predictable global task ids are a cross-session read/kill hazard.
-
-The [tool cookbook](../../../cookbook/adding-a-tool.md) already points at the real design smell: background bash is really generic long-running-tool infrastructure living inside one tool. If future tools need background execution, polling, kill, ownership, and completion notices, those semantics should not be hidden in `dsh-bash`.
-
-## Proposal
-
-Move long-running task semantics above bash into a tool-agnostic runtime. Bash remains able to run background commands, but it stops owning the general concepts of task ids, ownership tokens, polling, cancellation, completion notifications, and model-facing "read/kill this task" commands.
-
-The runtime should own:
-
-- Stable task ids and owner tokens keyed to the calling session/agent.
-- Registration of a long-running task with a producer for incremental output and a completion promise.
-- Generic read/cancel/list operations with the same cross-session authorization rule for every tool.
-- Completion notification injection into the owning session.
-- Presentation hooks for pending/running/completed task state, with bash supplying only command-specific labels and output formatting.
-
-`dsh-bash` then keeps the bash-specific execution contract: resolve a request into a command spec, run a foreground command, or start a process and hand its streams/process handle to the generic runtime. `dsh-tool-bash` keeps the model-facing command tool, but the follow-up operations become generic long-running-tool operations or a shared utility that bash registers with, rather than bespoke `bash_output`/`bash_kill` plumbing.
-
-## Current seam consumption
-
-Current consumers split cleanly: `dsh-tool-bash` uses the full foreground/background seam, while hook bridges use only foreground `resolve` and `run` with trusted `stdin` and `env`. `get` and `list` are test-only; `BashTask.done` is implementation-only for disposal, while production completion uses `onTaskDone`. An extracted runtime should expose one public completion mechanism, preserve the simple foreground path for hooks, and decide whether background `timeoutMs` belongs on `start`. If it owns process spawning, it should also centralize the duplicated credential scrub.
-
-## Acceptance criteria
-
-- The bash-specific packages no longer define the generic task registry, owner-token authorization, polling, cancellation, or completion-notification machinery.
-- A shared long-running-task service or tool layer owns those semantics and is documented as the path for any future background-capable tool.
-- Bash background behavior remains available through the shared layer, with tests proving cross-session isolation still holds.
-- ACP and snapshot fixtures render background bash through the shared task vocabulary, not through bash-only lifecycle semantics.
-- The [tool cookbook](../../../cookbook/adding-a-tool.md) points long-running tools at the shared runtime instead of telling each tool to invent its own task protocol.
-
-## Risks
-
-The bash package loses local ownership of an already-working background-task implementation, and the implementing PR may temporarily churn model-facing tool names or transcript presentation. That churn is worthwhile if it leaves one background-task contract instead of making every future long-running tool clone bash's private protocol.
-
-
diff --git a/docs/rfc/proposed/architecture/2026-07-15-sdk-project-editing-architecture.i18n.yaml b/docs/rfc/proposed/architecture/2026-07-15-sdk-project-editing-architecture.i18n.yaml
new file mode 100644
index 0000000000..6e301ee06a
--- /dev/null
+++ b/docs/rfc/proposed/architecture/2026-07-15-sdk-project-editing-architecture.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# 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
+2026-07-15-sdk-project-editing-architecture.md: 985cc22c159c68801b78262aa96c7422bdfa1318
+2026-07-15-sdk-project-editing-architecture.zh.md: 6a194e8e5f193e62bfc283fd93a5fde0367fe196
diff --git a/docs/rfc/proposed/architecture/2026-07-15-sdk-project-editing-architecture.md b/docs/rfc/proposed/architecture/2026-07-15-sdk-project-editing-architecture.md
new file mode 100644
index 0000000000..985cc22c15
--- /dev/null
+++ b/docs/rfc/proposed/architecture/2026-07-15-sdk-project-editing-architecture.md
@@ -0,0 +1,129 @@
+# RFC: SDK project editing architecture
+
+Status: proposed
+
+English | [中文](2026-07-15-sdk-project-editing-architecture.zh.md)
+
+## Problem
+
+[Developer-owned SDK projects](../feature/2026-07-14-sdk-developer-projects.md) are created through create, adjusted through config, and built and run through commands such as start. Initial creation, configuration changes, and build and runtime commands all need to understand features, feature options, npm dependencies, Cordis config entries, environment variables, package managers, local plugins, and several project files. If each project-reading and project-writing workflow uses a separate interpretation protocol, the SDK developer workflows become difficult to maintain.
+
+## Proposal
+
+The SDK uses one shared object-oriented project model. `SdkProject` is a read-only snapshot, and `ProjectEditSession` is the only mutation and commit boundary. Feature objects own their feature options, relationships, resource contributions, and current-state inspection. Create and config orchestrate only their respective user workflows and modify projects through the same domain operations.
+
+Structured files are modified through document objects, while one-shot text artifacts are generated from complete templates. Questions are typed objects presented through clack. Diff calculation may remain an edit-session implementation detail, but it is not a public execution protocol that callers must assemble.
+
+## Terminology
+
+| Term | Usage in this RFC | Meaning |
+|---|---|---|
+| Feature | feature | A product unit curated and managed by the SDK; one feature may contain several feature options and contribute several Cordis config entries, npm dependencies, environment placeholders, and owned files |
+| Feature option | feature option | A finite selectable implementation or configuration shape within one feature; feature rules may make options fixed, exclusive, or additive |
+| Cordis plugin | Cordis plugin | A plugin implementation loaded by Cordis, usually exported by an npm package; it is not an item in `cordis.yml` |
+| Cordis config entry | Cordis config entry | One item in the `cordis.yml` plugin list, identified as an instance by `id` and referring to a Cordis plugin through `name` |
+| Cordis plugin config | Cordis plugin config | The configuration object or shape exposed by a Cordis plugin; an individual field owned and updated by a feature is a config key |
+| config key | config key | One field in Cordis plugin config; a feature updates only the config keys it declares as owned and preserves unknown config keys |
+| npm dependency | npm dependency | A package relationship in `package.json`; literal fields such as `dependencies` and `devDependencies` keep their names |
+| Feature requirement | feature requirement | A relationship declared through `requires` by a feature or feature option |
+
+## Package boundaries
+
+| Package | Responsibility | Does not own |
+|---|---|---|
+| `@deepseek-ai/dsh-helper` | Edit sessions, feature configuration, project-template rendering, package-manager adaptation, and prompt interaction adaptation | Booting Cordis applications or deciding create/config terminal workflows |
+| `@deepseek-ai/dsh-scripts` | `dsh-sdk start/dev/build/config`, process lifecycle, project entry loading, the config workflow, and its terminal-copy templates | Interpreting feature definitions directly or modifying YAML/JSON ASTs |
+| `@deepseek-ai/create-sdk` | Arguments, question order, initial project creation, installation finish, and terminal-copy templates for `npm create @deepseek-ai/sdk` | Becoming a generated project's runtime npm dependency or providing a library API |
+
+`@deepseek-ai/create-sdk` is the only exception to the repository's `@deepseek-ai/dsh-*` naming rule. npm's scoped-initializer convention requires that package name for `npm create @deepseek-ai/sdk`. The exception is a repository architecture fact and does not add a third developer product entrypoint.
+
+The three packages export only the narrow entrypoints consumed by adjacent layers and provide no `src/*` deep imports. The scripts library entrypoint and build-config subpath serve generated code and project build configuration, while the developer product contract remains the `dsh-sdk` commands.
+
+## Project aggregate and edit session
+
+`SdkProject.create(root, request)` constructs a new project snapshot that has not been written, while `SdkProject.open(root)` loads an existing project. Open requires only readable root `package.json` and `cordis.yml` files; every other file is an optional resource. Both paths return the same read-only aggregate and distinguish their source through explicit origin state.
+
+`project.edit()` clones project documents into a working copy. Domain commands such as install, configure, enable, disable, and addPlugin modify only the working copy. Each command immediately re-inspects its owning feature, and the final commit checks all relationships and files again.
+
+```text
+validate feature requirements and resource ownership
+ -> validate every affected document
+ -> compute changed and removed paths
+ -> compare existing files with the session's original text
+ -> write through one commit boundary
+ -> return a new SdkProject snapshot and ChangeSet
+```
+
+Validation failure or an external edit causes zero writes. “One commit” means only zero pre-write side effects and one write entrypoint. `ChangeSet` describes final feature, plugin, and file changes for Review & Apply and create completion.
+
+## Features and resource ownership
+
+A feature is a first-class behavior object. Shallow base classes implement install, configure, enable, disable, required/requires validation, and common state inspection. Features with fixed, exclusive, or additive feature options share these lifecycles. Only features whose resource contributions depend on project context or require custom round-tripping use dedicated behavior classes; other features declare their actual differences through standardized data.
+
+Each feature contributes stable-keyed Cordis config entries, npm dependencies, environment placeholders, and owned files. The registry rejects two features that declare the same resource key during initialization. Different feature options within one feature may share resources, which that feature resolves from the final option set.
+
+A Cordis config entry anchors feature installation. The npm package name assigns the entry to a feature, and the entry ID distinguishes several instances of one plugin package. An npm dependency without a feature-owned Cordis config entry leaves the feature uninstalled. Once a Cordis config entry exists, a missing npm dependency, unreadable Cordis plugin config, or resource conflict puts the feature into an inconsistent state; the config command shows diagnostics and refuses speculative modification.
+
+Configuring the same feature option updates only its owned config keys and preserves unknown keys. Replacing a feature option removes old resources that are exclusive and still confirmable. If an old resource cannot be confirmed or an owned file was modified by the developer, the whole operation fails.
+
+## Questions and workflows
+
+TypeScript `Question` objects keep defaults, validation, applicability, and types together. `PromptPort` is the only interface between the domain layer and the terminal library, and helper provides one thin `ClackPromptPort`. Create and config inject their own command-line input and output streams and retain ownership of cancellation, return, and completion semantics in their workflows.
+
+Create keeps its stateful question order in one wizard, while config keeps final-state selection in one workflow. Both use the same feature configurator for feature options and dedicated inputs, so adding an ordinary feature, feature option, or parameter does not require changes to both entrypoints.
+
+## Project documents and templates
+
+Only structured files that helper reads or modifies have concrete document objects: `package.json`, `cordis.yml`, `.env`, `.env.example`, the root `tsconfig.json`, and the pnpm workspace file. Document objects own parsing, cloning, validation, and serialization. Concrete classes and modules use `*File` and `*-file.ts` names respectively. Business code does not manipulate YAML/JSON ASTs directly, and malformed shapes fail loudly at the owning document boundary.
+
+README, entrypoint code, build configuration, `.gitignore`, and other one-shot text artifacts use one complete template per real file. Complete product copy such as CLI usage, creation and recovery messages, installation and retry guidance, and the default persona also comes from package-local templates owned by the package that presents it.
+
+Helper provides the generic typed `TextTemplate` renderer, and caller packages load their own templates through package-local asset URLs.
+
+Templates use Handlebars strict mode and `noEscape` without custom processing. File owners encode typed values for the target language. Template source escapes interpolation as `\{{model}}` when it must emit the downstream literal unchanged.
+
+## Command and runtime boundary
+
+Scripts supports `dsh-sdk start/dev/build/config`. Start dynamically loads a module target and calls its named entrypoint. Dev adds TypeScript and local-workspace source resolution before following the same path. Build invokes the project's installed tsdown. Config opens one edit session and commits after Review & Apply. Generated projects run `tsc -b` directly for typechecking.
+
+HMR is an explicit Cordis config entry loaded by dev and start. Its required `node-addon-require-builtin` package is supplied transitively by the scripts package and is absent from the generated project's `package.json`.
+
+Dev and start execute the developer entrypoint, where developer code handles command-line arguments and cwd. Developers pass `--model=` and `--resume=` to start the standard flow.
+
+## Repository live-link mode
+
+Create-sdk retains a hidden `--link-workspace` option for Harness repository development and e2e. The parser accepts it, but help, public flag lists, and ordinary user documentation omit it. It accepts no repository-path parameter; the repository root is derived upward from the executing create-sdk module.
+
+Link mode preserves the ordinary project file shape. `@deepseek-ai/*` points into `packages/`, Cordis-related npm dependencies point into `vendor/`, and shared lower-level packages resolve to the same physical copy used by the repository so Cordis type merging cannot produce multiple module type definitions. npm uses `file:`, pnpm uses `link:` with automatic peer installation disabled, and Yarn uses `portal:` plus resolutions. Repository packages must be built first.
+
+## Future work
+
+- **Replaceable required spine roles.** The current `spine` owns the full implementation set, including SystemPrompt and LLMService, through one fixed feature option. Developers cannot replace or switch these roles and must edit Cordis config entries manually.
+- **Service contracts and package declarations.** When replacing a builtin service, a Cordis plugin currently cannot declare the services it provides through `provides` metadata, so the SDK cannot assist configuration during development or check compatibility at runtime. A corresponding protocol remains to be designed.
+- **Feature parameter descriptions.** Feature-specific inputs currently require handwritten declarations. The SDK cannot derive interactive parameters automatically from arbitrary Cordis plugin config or npm package.json information. Future declarative metadata may expose a limited parameter set without turning arbitrary Cordis plugin config into a generic form.
+- **SDK application-level configuration.** The current project resource model describes Cordis config entries and config keys owned by individual Cordis plugins, so every SDK-managed setting must belong to one plugin. Cross-plugin or whole-application settings have no independent persistence location. Future work must define an application-level configuration document and its ownership, read, and mutation boundaries.
+
+## Alternatives considered
+
+**Keep the static Catalog and central engine.** This minimizes the initial rewrite, but feature parameters, round-tripping, owned files, and create/config reuse continue to accumulate in one coordinator. Splitting files shortens the file without consolidating responsibility.
+
+**Use `wizard.json` and a generic Questionnaire.** Static forms cannot directly express feature requirements, option switches, existing-value refill, and project-resource changes. Types, gates, and dynamic options still connect through string registries and a procedural `run()`, creating another internal DSL.
+
+**Expose the live-link flag.** The mode depends on Harness monorepo layout and unpublished packages and serves repository development only. Making it public would create a project-creation contract that the SDK cannot support outside the repository.
+
+## Acceptance criteria
+
+- Create and config modify projects only through `SdkProject` and `ProjectEditSession`; any business, document, or concurrency validation failure before writing leaves the filesystem unchanged
+- Adding an ordinary feature, feature option, or parameter extends only its typed spec or owning behavior object, without adding a central switch to create or config workflows
+- Helper owns the feature model, npm dependency and other resource configuration, and inconsistent-state detection
+- Structured files change through `*File` document objects; one-shot files and complete product copy come from package-owned Handlebars templates, and business decisions do not enter a template DSL
+- `dsh-sdk start/dev/build/config` is the runtime product surface, typecheck uses `tsc -b` directly, HMR is not injected by command mode, and only the scripts package transitively supplies `node-addon-require-builtin`
+- `--link-workspace` exists only as a hidden repository-development option and preserves one module identity under npm, pnpm, and Yarn
+
+## Risks
+
+- Behavior objects and typed specs create two extension shapes. Dedicated classes must remain limited to features that truly depend on project context or custom behavior, or the design will grow a meaningless type hierarchy
+- Optimistic concurrency checks and pre-write validation cannot recover from an I/O failure during writing; callers must still report a possible partial commit to the developer
+- Hidden link mode depends on repository layout and package-manager link semantics and must change with either one
+- The Cordis loader resolves `node-addon-require-builtin` from its own module path, so the scripts package must continue to satisfy that optional peer under npm, pnpm, and Yarn npm dependency layouts
+- Handlebars `noEscape` makes typed model construction responsible for target-language encoding; new template fields must be escaped correctly at the owning boundary, and downstream Handlebars placeholders must be escaped explicitly in template source
diff --git a/docs/rfc/proposed/architecture/2026-07-15-sdk-project-editing-architecture.zh.md b/docs/rfc/proposed/architecture/2026-07-15-sdk-project-editing-architecture.zh.md
new file mode 100644
index 0000000000..6a194e8e5f
--- /dev/null
+++ b/docs/rfc/proposed/architecture/2026-07-15-sdk-project-editing-architecture.zh.md
@@ -0,0 +1,129 @@
+# RFC: SDK 工程编辑架构
+
+Status: proposed
+
+[English](2026-07-15-sdk-project-editing-architecture.md) | 中文
+
+## 问题
+
+[开发者拥有的 SDK 工程](../feature/2026-07-14-sdk-developer-projects.md) 由 create 创建，可以通过 config 调整，并由 start 等命令构建和运行。初始创建、配置调整和编译运行都需要理解功能、功能选项、NPM 依赖、Cordis 配置项、环境变量、包管理器、本地插件和多个项目文件。如果读写项目的各个流程分别使用不同的解析协议，SDK 开发者流程会变得难以维护。
+
+## 提案
+
+SDK 使用一个共享的面向对象工程模型。`SdkProject` 是只读快照，`ProjectEditSession` 是唯一修改与提交边界；功能对象负责自身的功能选项、关系、资源贡献和现状识别；create 与 config 只编排各自的用户流程，并通过同一组领域操作修改工程。
+
+结构化文件通过文档对象修改，一次性文本产物通过完整模板生成。问题由类型化对象表达，并使用 clack 交互。差异计算可以作为编辑会话的内部实现，但不成为要求调用方组装的公共执行协议。
+
+## 术语
+
+| 名词 | 本文用词 | 含义 |
+|---|---|---|
+| Feature | 功能 | SDK 人工策划和管理的产品单元；一项功能可以包含多个功能选项，并贡献多个 Cordis 配置项、NPM 依赖、环境变量占位和独占文件 |
+| Feature option | 功能选项 | 一项功能内有限、可选择的实现或配置形状；根据功能规则可以固定、互斥或多选 |
+| Cordis plugin | Cordis 插件 | Cordis 加载的插件实现，通常由一个 NPM 包导出；它不是 `cordis.yml` 中的一项配置 |
+| Cordis config entry | Cordis 配置项 | `cordis.yml` 插件列表中的一项，通过 `id` 标识实例并通过 `name` 指向 Cordis 插件 |
+| Cordis plugin config | Cordis 插件配置 | Cordis 插件公开的配置对象或配置结构；其中由功能拥有并更新的单个字段称为“配置键” |
+| config key | 配置键 | Cordis 插件配置中的单个字段；功能只更新自己声明拥有的配置键，并保留未知配置键 |
+| npm dependency | NPM 依赖 | `package.json` 中的包关系；`dependencies`、`devDependencies` 等字段保持原样 |
+| Feature requirement | 功能依赖 | 功能或功能选项通过 `requires` 声明的关系 |
+
+## Package 边界
+
+| Package | 责任 | 不负责 |
+|---|---|---|
+| `@deepseek-ai/dsh-helper` | 编辑会话、功能配置、工程模板渲染、包管理适配和 prompt 交互适配 | 启动 Cordis 应用或决定 create/config 的终端流程 |
+| `@deepseek-ai/dsh-scripts` | `dsh-sdk start/dev/build/config`、进程生命周期、项目入口加载、config 流程和所属终端文案模板 | 直接解释功能定义或修改 YAML/JSON AST |
+| `@deepseek-ai/create-sdk` | `npm create @deepseek-ai/sdk` 的参数、问题顺序、首次工程创建、安装收尾和所属终端文案模板 | 成为生成工程的运行时 NPM 依赖或提供库 API |
+
+`@deepseek-ai/create-sdk` 是仓库 `@deepseek-ai/dsh-*` 命名规则的唯一例外；npm scoped initializer 约定要求 `npm create @deepseek-ai/sdk` 对应这个 package 名。该例外是仓库架构事实，不增加第三个开发者产品入口。
+
+三个 package 只导出相邻层实际使用的最小入口，不提供 `src/*` 深路径。scripts 的库入口与构建配置子路径服务生成代码和项目构建配置，但开发者产品合同仍由 `dsh-sdk` 命令承担。
+
+## 工程聚合与编辑会话
+
+`SdkProject.create(root, request)` 构造尚未写盘的新工程快照，`SdkProject.open(root)` 加载已有工程。open 只要求根 `package.json` 与 `cordis.yml` 可读，其余文件是按需存在的资源；两条路径返回同一种只读聚合，并通过显式 origin 区分来源。
+
+`project.edit()` 克隆项目文档形成 working copy。install、configure、enable、disable 和 addPlugin 等领域命令只修改 working copy；命令完成后立即重新检查所属功能，最终 commit 再检查全部关系和文件。
+
+```text
+validate feature requirements and resource ownership
+ -> validate every affected document
+ -> compute changed and removed paths
+ -> compare existing files with the session's original text
+ -> write through one commit boundary
+ -> return a new SdkProject snapshot and ChangeSet
+```
+
+校验失败或检测到会话外修改时不写盘。“一次 commit”只表示写入前零副作用和单一写入口。`ChangeSet` 只描述功能、插件和文件的最终变化，用于 Review & Apply 与 create 收尾。
+
+## 功能与资源所有权
+
+功能是一等行为对象。浅层基类实现 install、configure、enable、disable、required/requires 校验和共同状态识别；固定功能选项、互斥功能选项与可多选功能选项共享这些生命周期。只有资源贡献依赖项目上下文或需要自定义 round-trip 的功能才使用专用行为类，其余功能通过标准化数据声明真正不同的部分。
+
+每项功能贡献带稳定 key 的 Cordis 配置项、NPM 依赖、环境变量占位和独占文件。注册表初始化时拒绝不同功能声明同一个资源 key；同一功能的不同功能选项可以共享资源，并由该功能根据最终选项集合处理。
+
+Cordis 配置项是功能安装锚点。NPM 包名判断配置项所属的功能，配置项 ID 区分同一插件包的多个实例；只有 NPM 依赖而没有功能拥有的 Cordis 配置项时，该功能仍视为未安装。Cordis 配置项存在后，缺失 NPM 依赖、无法读取的 Cordis 插件配置或资源冲突会使功能进入不一致状态，config 命令显示诊断并拒绝猜测式修改。
+
+同一功能选项只更新其声明拥有的配置键，保留未知键。替换功能选项会删除旧功能选项独占且仍可确认的资源；无法确认旧资源或发现独占文件被用户修改时，整个操作失败。
+
+## 问题与 workflow
+
+问题由 TypeScript `Question` 对象表达，默认值、校验、适用条件和类型留在同一个对象中。`PromptPort` 是领域层与终端库之间的唯一接口，helper 提供一份薄 `ClackPromptPort`；create 和 config 注入各自的命令行输入输出流，并在各自流程中决定取消、返回和收尾语义。
+
+create 的有状态问题顺序留在一个向导中，config 的最终状态选择留在一个流程中。两者通过同一个功能配置器收集功能选项与专用输入，因此增加一项普通功能、功能选项或参数不要求同时修改两个入口。
+
+## 项目文档与模板
+
+只有需要读取或修改的结构化文件拥有具体文档对象，包括 `package.json`、`cordis.yml`、`.env`、`.env.example`、根 `tsconfig.json` 和 pnpm workspace 文件。文档对象拥有解析、克隆、校验和序列化行为；具体类与模块分别使用 `*File` 和 `*-file.ts` 命名，业务层不直接操作 YAML/JSON AST，异常形状在所属文档边界 fail loud。
+
+README、入口代码、构建配置、`.gitignore` 和其他一次性文本产物使用与真实文件一一对应的完整模板。CLI usage、创建结果与恢复提示、安装与重试指导以及默认 persona 等完整产品文案也由所属 package 的本地模板提供。
+
+helper 提供通用的数据类型化 `TextTemplate` 模板渲染器，调用 package 通过本地 asset URL 加载自己的模板。
+
+模板使用 Handlebars strict mode 与 `noEscape`，不进行自定义处理。文件对象负责把类型化数据值编码成目标语言文本；如果不希望插值，则源码以 `\{{model}}` 等转义形式输出下游。
+
+## 命令与运行边界
+
+scripts 支持 `dsh-sdk start/dev/build/config`。start 动态加载模块 target 并调用其命名入口；dev 在同一路径前增加 TypeScript 与本地 workspace 源码解析；build 调用工程安装的 tsdown；config 打开一个编辑会话并在 Review & Apply 后提交。typecheck 由生成工程直接执行 `tsc -b`。
+
+HMR 作为显式 Cordis 配置项由 dev 和 start 加载；它所需的 `node-addon-require-builtin` 由 scripts package 传递提供，不写入开发者工程的 `package.json`。
+
+dev/start 会执行开发者入口，在开发者代码中处理命令行参数、cwd，由开发者自行传入 `--model=` 与 `--resume=` 启动标准流程。
+
+## 仓库本地链接模式
+
+create-sdk 保留隐藏的 `--link-workspace` 选项供 Harness 仓库开发和 e2e 使用。该选项可以被解析，但不出现在 help、公开 flag 清单或普通用户文档中，也不接收仓库路径参数；仓库根从正在执行的 create-sdk 模块位置向上确定。
+
+链接模式保持普通工程的文件形状。`@deepseek-ai/*` 指向 `packages/`，Cordis 相关 NPM 依赖指向 `vendor/`，共享底层 package 锚定到仓库实际使用的同一物理拷贝，避免 Cordis 类型合并产生多个模块类型定义。npm 使用 `file:`，pnpm 使用 `link:` 并关闭自动 peer 安装，Yarn 使用 `portal:` 与 resolutions；仓库 package 需要先构建。
+
+## 后续工作
+
+- **可替换的 required 主干角色。** 当前 `spine` 以一个固定功能选项拥有整组实现，包含 SystemPrompt、LLMService 等。无法让开发者对其进行替换和切换，只能手工修改 Cordis 配置项。
+- **Service contract 与 package 声明。** 替换特定内建服务时，Cordis 插件目前无法通过 `provides` 元数据声明其提供的服务，因此 SDK 无法在开发阶段辅助配置，也无法在运行时检查兼容性。后续需要设计相应协议。
+- **功能参数描述。** 当前功能的专用输入必须手工声明；SDK 无法从任意 Cordis 插件配置或 NPM package.json 信息中自动推导可交互参数。后续可以定义有限的声明式参数元数据，但不把任意 Cordis 插件配置转换成通用表单。
+- **SDK 应用级配置。** 当前项目资源模型只描述 Cordis 配置项及单个 Cordis 插件拥有的配置键，因此所有受 SDK 管理的配置都必须归属某个插件。跨插件或面向整个 SDK 应用的设置没有独立持久化位置；后续需要定义应用级配置文档及其所有权、读取和修改边界。
+
+## 曾考虑的替代方案
+
+**保留静态 Catalog 与中心 engine。** 该方案改动最小，但功能参数、round-trip、独占文件和 create/config 复用都会继续进入同一个协调中心；拆文件只能缩短单文件，不能收拢职责。
+
+**使用 `wizard.json` 与通用 Questionnaire。** 静态表单无法直接表达功能依赖、选项切换、已有值回填和项目资源变化；类型、gate 和动态 option 最终仍要通过字符串 registry 与过程式 `run()` 连接，形成新的内部 DSL。
+
+**公开本地链接 flag。** 该模式依赖 Harness monorepo 布局和未发布 package，只服务仓库开发；公开后会形成无法对外兑现的项目创建合同，因此保持隐藏。
+
+## 验收标准
+
+- create 与 config 只通过 `SdkProject` 和 `ProjectEditSession` 修改工程，写入前的任何业务、文件或并发校验失败都不产生磁盘变化
+- 新增普通功能、功能选项或参数只扩展类型化 spec 或所属行为对象，create/config 流程不增加中央 switch
+- 功能模型、NPM 依赖与其他资源配置、不一致检测由 helper 统一实现
+- 结构化文件通过 `*File` 文档对象修改；一次性文件和完整产品文案通过所属 package 的 Handlebars 模板生成，业务决策不进入模板 DSL
+- `dsh-sdk start/dev/build/config` 是运行产品面，typecheck 直接使用 `tsc -b`，HMR 不通过命令隐式注入，`node-addon-require-builtin` 只由 scripts package 传递提供
+- `--link-workspace` 只作为隐藏的仓库开发选项存在，并对 npm、pnpm 和 Yarn 保持单一模块身份
+
+## 风险
+
+- 行为对象与类型化 spec 并存会形成两种扩展形状；专用类必须只用于确实依赖项目上下文或自定义的功能，否则会重新产生无意义的类型层次
+- 乐观并发检查与写前校验不能解决写入中途的 I/O 故障，调用方仍需向开发者报告可能的部分提交
+- 隐藏链接模式依赖仓库目录与 package manager 链接语义，仓库布局或工具行为变化时必须与实现一起更新
+- Cordis loader 从自身模块路径加载 `node-addon-require-builtin`；npm、pnpm 或 Yarn 的 NPM 依赖布局变化时，scripts package 必须继续满足该可选对等依赖（optional peer dependency）
+- Handlebars 的 `noEscape` 把目标语言编码责任交给 typed model 构造方；新增模板字段时必须在 owner 处完成正确转义，下游 Handlebars 占位符必须在模板源码中显式转义
diff --git a/docs/rfc/proposed/feature/2026-07-14-sdk-developer-projects.i18n.yaml b/docs/rfc/proposed/feature/2026-07-14-sdk-developer-projects.i18n.yaml
new file mode 100644
index 0000000000..36bb26161f
--- /dev/null
+++ b/docs/rfc/proposed/feature/2026-07-14-sdk-developer-projects.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# 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
+2026-07-14-sdk-developer-projects.md: 0b5fe876f92153e1ccf5bd8fe383464f5087f4b1
+2026-07-14-sdk-developer-projects.zh.md: ec08f323acba1b9dc049182937fda34bfb50d4ee
diff --git a/docs/rfc/proposed/feature/2026-07-14-sdk-developer-projects.md b/docs/rfc/proposed/feature/2026-07-14-sdk-developer-projects.md
new file mode 100644
index 0000000000..0b5fe876f9
--- /dev/null
+++ b/docs/rfc/proposed/feature/2026-07-14-sdk-developer-projects.md
@@ -0,0 +1,167 @@
+# RFC: Developer-owned SDK projects
+
+Status: proposed
+
+English | [中文](2026-07-14-sdk-developer-projects.zh.md)
+
+## Problem
+
+DeepSeek Harness composes features through Cordis plugins, but building a runnable project from an empty directory still requires a developer to understand npm dependencies, the `cordis.yml` plugin set, environment variables, TypeScript builds, local-plugin workspaces, and runtime entrypoints together. These manual steps constrain one another: omitting any one can produce a project that installs but cannot be developed, develops but cannot be built, or builds but cannot start.
+
+A one-shot generator reduces only the initial creation cost. If the generated result is hidden inside a preset or an uneditable CLI, advanced developers cannot reshape the plugin tree, change Cordis plugin config, or add project-specific behavior. If a generated project immediately leaves tool management altogether, developers must again maintain consistency across all npm dependencies and Cordis plugin config themselves.
+
+Initial creation and later configuration address the same builtin feature set. When those workflows maintain separate feature lists, feature options, and npm dependencies, new Cordis plugins, npm packages, and Cordis plugin config changes make them diverge. Projects also need an ordinary local-plugin development path that participates in development, build, and start flows.
+
+## Proposal
+
+The SDK creates an ordinary, explicit TypeScript/Cordis project owned by its developer. `cordis.yml` is the only runtime plugin tree; development and production read the same file. The generated `package.json`, `cordis.yml`, TypeScript entrypoint, build configuration, and `plugins/*` remain directly editable instead of being hidden behind a preset.
+
+The only developer product entrypoints are `npm create @deepseek-ai/sdk` and the `dsh-sdk` commands. The initializer performs initial creation, `dsh-sdk config` manages SDK-recognized builtin features afterward, and `dsh-sdk dev`, `dsh-sdk build`, and `dsh-sdk start` own development, build, and startup; this phase provides no `dsh-sdk create`. Create and config consume one manually authored feature definition, so each feature has one source for its feature options, npm dependencies, Cordis config entries, related files, and inspection rules. The [SDK project editing architecture](../architecture/2026-07-15-sdk-project-editing-architecture.md) defines terms such as feature and feature option.
+
+The SDK offers interaction for feature selection and finite feature options only; it does not turn arbitrary Cordis plugin config into a generic form. A feature collects the small number of dedicated inputs required by its feature options. All other Cordis plugin config remains in `cordis.yml`, with comments documenting common edits, for direct developer control.
+
+## Developer workflow
+
+Initial creation collects information in an order where earlier answers determine later questions: target directory and package identity, model provider and credentials, run interface, builtin features and feature options, an optional local plugin, package manager, and whether to install npm dependencies and build. Command-line arguments suppress questions they already answer. Create and config require an interactive TTY in this phase, and cancelling creation writes nothing to the target directory.
+
+```sh
+npm create @deepseek-ai/sdk my-agent
+cd my-agent
+npm exec dsh-sdk dev index.ts
+npm exec dsh-sdk config
+npm exec dsh-sdk build
+npm exec dsh-sdk start index.js
+```
+
+Create rejects every target path that already exists. After committing the project files, the CLI asks whether to install npm dependencies and build. An install or build failure preserves the generated project and prints commands that can retry the failed work.
+
+Create also offers one `none / plugin / tool` choice. `plugin` creates a fixed `plugins/plugin` Cordis plugin, while `tool` creates a fixed `plugins/tool` model-facing tool; one project creation includes at most one local plugin. The operation updates the workspace, root npm dependency, TypeScript reference, build configuration, and `cordis.yml` together, and any pre-write validation failure leaves the project absent.
+
+## Features supported during creation
+
+The table is the developer-visible support set for this phase. A `required` feature is always present but may still offer finite feature options; a `default` feature is preselected in the feature tree; an `optional` feature is selected explicitly. The table describes the product support set, while the runtime registry remains the implementation source of truth.
+
+| Feature | Create state | Feature options | Constraints and relationships |
+|---|---|---|---|
+| `provider` | required | `deepseek` (default) / `custom` | DeepSeek collects an API key; custom also collects a base URL, and a CLI option may override the model name |
+| `app` | required | `stdio` (default) / `acp` / `embed` | Selects the run interface |
+| `spine` | required | `default` | Timer, the LLM seam, session storage, system prompt, the tool registry, the agent registry, and the agent loop |
+| `bash` | required | `local` (default) / `sandbox` | The two feature options are exclusive and independent of the run interface, and both install the model-facing bash tool; sandbox installs the local sandbox provider and sandboxed bash backend |
+| `persistence` | required | `jsonl` (default) / `sqlite` | Every project selects exactly one persistence backend |
+| `hmr` | default | `default` | Loads `@cordisjs/plugin-hmr`; dev and start both enable it with the plugin defaults |
+| `fs` | default | `local` | Installs the local filesystem, policy, and model-facing tools; the process sandbox does not confine in-process fs tools |
+| `todo` | default | `default` | Provides the `todo_write` tool |
+| `skill` | default | `default` | Installs the skill registry, the local skill provider, and the model-facing skill tool |
+| `web` | optional | `deepseek` (default) / `exa` / `perplexity` / `fetch-only` | Search feature options are exclusive; Exa and Perplexity collect their API keys; timeout policy is recommended |
+| `subagent` | optional | `spawn` (default) / `fork`, multiple | This phase provides only in-process backends |
+| `workflow` | optional | `workerthread` | Requires the subagent `spawn` feature option |
+| `compact` | optional | `basic` | Uses SDK-provided context-compaction parameters |
+| `hooks` | optional | `claude` (default) / `codex`, multiple | Each feature option creates a separate editable configuration file |
+| `guard` | optional | `repeat-tool` | Provides repeated-tool-call reminders |
+| `timeout-policy` | optional | `default` | Applies a uniform policy to tools that declare timeout budgets |
+| `ask-user` | optional | `default` | Provides the `ask_user_question` tool; only `acp` and `stdio` can select it because those two feature options provide the injected user-interaction service |
+
+Both `bash` feature options apply to ACP, stdio, and embed and are not selected by the run interface. The sandbox feature option writes no active config key and therefore keeps `dsh-bash-sandbox`'s `read-only` default. Generated `cordis.yml` includes a commented example that developers can change explicitly to `workspace-write`:
+
+```yaml
+- id: bash
+ name: '@deepseek-ai/dsh-bash-sandbox'
+ # Uncomment to allow writes under the project workspace.
+ # config:
+ # mode: workspace-write
+ # workspaceRoot: !!js process.cwd()
+```
+
+Feature contributions reference only single-plugin npm packages and never bundle packages such as `agent-spine-demo`, `stdio-demo`, or `acp-demo`. Plugins outside the table are not managed by create in this phase; advanced developers may still compose them by editing the ordinary project files directly.
+
+## Generated project
+
+With default answers, an npm project uses the DeepSeek provider, the stdio interface, local bash, JSONL persistence, and the preselected hmr, fs, todo, and skill features. Its initial tree is:
+
+```text
+my-agent/
+├── .env
+├── .env.example
+├── .gitignore
+├── README.md
+├── cordis.yml
+├── index.ts
+├── package.json
+├── tsconfig.base.json
+├── tsconfig.json
+└── tsdown.config.ts
+```
+
+`.env.example` always exists, and the SDK keeps its placeholders aligned with the current feature set. A gitignored `.env` is also created when a secret is captured or the developer confirms an empty credential to fill later. The SDK only appends differently named variables that are not already present in `.env` and never updates or removes existing contents. Feature-option changes may remove obsolete `.env.example` placeholders, while old credentials remain in `.env` for the developer to manage. pnpm and Yarn projects add their required workspace files, but do not fork the runtime plugin tree or TypeScript entrypoint.
+
+Generated `package.json` provides the following scripts. `dev`, `build`, `start`, and `config` invoke `dsh-sdk`, while `typecheck` invokes TypeScript directly:
+
+| Script | Behavior |
+|---|---|
+| `dev` | Run `dsh-sdk dev index.ts`, registering development-time resolution for TypeScript and local workspace plugins |
+| `build` | Run `dsh-sdk build`, invoking the project's installed tsdown for the root entrypoint and `plugins/*` packages |
+| `typecheck` | Run `tsc -b` directly |
+| `start` | Run `dsh-sdk start index.js`, starting the built entrypoint without an implicit build |
+| `config` | Run `dsh-sdk config` to edit the current project's feature tree |
+
+`dsh-sdk start` and `dsh-sdk dev` accept a module target and forward arguments after `--` unchanged to the project entrypoint. Generic argument parsing uses Node `parseArgs()` with zero schema: valued flags use `--key=value`, bare flags become `true`, and `--no-*` becomes `false`.
+
+- Stdio projects pass the selected model through `--model=` and create or resume an agent according to optional `--resume=`;
+- ACP uses protocol `session/load`
+- Embed uses the model written into the generated code.
+
+Each feature-owned Cordis config entry keeps its developer-editable Cordis plugin config and explanatory comments in `cordis.yml`. When `dsh-sdk config` changes other features, it preserves unknown fields, formatting on untouched nodes, and comments. HMR is an ordinary leaf config entry: when the feature is selected, dev and start load the same watcher, and the command does not change the plugin tree implicitly.
+
+## Post-creation configuration
+
+`dsh-sdk config` requires only readable root `package.json` and `cordis.yml` files in the current directory. It inspects standard features and their current feature options, expresses the final desired state through one feature tree, and shows feature changes and affected files before Review & Apply.
+
+`dsh-sdk config` can install missing features, enable or disable installed features, and switch finite feature options. Required features cannot be removed. An npm dependency change runs the project package manager's install once after the file commit; installation failure does not roll back committed project files.
+
+The SDK modifies only Cordis config entries, config keys, npm dependencies, `.env.example` placeholders, and owned files explicitly owned by a feature. Updating the same feature option preserves unknown config keys in its Cordis config entries. Handwritten and third-party plugins support enable and disable by stable ID only. When a known feature has been edited into an incomplete, ambiguous, or otherwise unreadable shape, `dsh-sdk config` displays diagnostics and refuses automatic changes until the developer repairs it manually.
+
+One config session accumulates every change in an in-memory working copy. Before Apply, it validates feature relationships, resource conflicts, and document shapes, then compares each affected existing file with the text read when the session opened. Validation failure or an external edit causes zero writes. Once physical writes begin, the SDK does not provide cross-file transactional rollback.
+
+## Maintenance model
+
+The SDK curates its builtin support set instead of exposing npm packages automatically by npm dependency name or directory convention. One feature may compose several Cordis config entries, feature options may share resources, and a feature option may declare a feature requirement on another feature or a specific feature option. Adding an ordinary feature or feature option does not require changes to both create and config command workflows.
+
+## Future work
+
+- `dsh-sdk add [package-spec]` unifies local-plugin creation with external Cordis plugin installation: without a package or repository source it creates a local plugin/tool, while a supplied source adds the npm dependency and `cordis.yml` config entry; the source model leaves room for GitHub repositories and other extensions
+- Non-interactive create/config: both workflows require a TTY in this phase and provide no complete input contract for automation
+- More feature-specific inputs: this product surface exposes only finite feature options, secrets, and a few dedicated values in this phase rather than a generic parameter interface for Cordis plugin config
+
+## Alternatives considered
+
+**An opaque preset or generator-owned project.** This shortens initial creation but hides the real plugin tree and build boundaries, prevents advanced developers from composing Cordis plugins directly, and makes project behavior depend on the CLI version rather than committed project files.
+
+**A one-shot generator only.** Leaving all later maintenance manual redistributes feature requirements, feature-option switches, and multi-file updates. A config workflow over the shared registry retains continuing management for generated projects.
+
+**Separate `cordis.yml` files for development and production.** Two plugin trees mean a successful development run does not demonstrate that production loads the same features. Dev adds only TypeScript and local-workspace resolution; runtime configuration remains singular.
+
+**A generic form for arbitrary Cordis plugin config.** Cordis plugin config contains nested structures, expressions, and plugin-specific semantics. A generic form would become a second incomplete schema. The SDK manages finite feature options and dedicated secrets, while developers continue to edit complex config directly.
+
+**A private local-plugin discovery protocol.** Ordinary package-manager workspaces, root npm dependencies, TypeScript references, and Cordis config entries already express the complete relationship. Another discovery protocol would create hidden state understood only by the SDK.
+
+**A `dsh-sdk create` command for existing projects.** Create already provides one editable local-plugin skeleton, and later plugins can use ordinary workspace and Cordis mechanisms manually. A parallel command would add a second scaffolding product surface without adding composition functionality.
+
+**Automatically expose every new Cordis plugin as a builtin.** An npm package cannot say how several plugins compose into one product feature, nor can it derive exclusivity, feature requirements, secrets, interface applicability, or security constraints. The support set requires human curation; automation is suitable only for checking whether candidates have been classified.
+
+## Acceptance criteria
+
+- `npm create @deepseek-ai/sdk` collects project identity, provider, interface, features, an optional local plugin, package manager, and installation choice in the documented order, and cancellation leaves the target path absent
+- A default npm project has the documented tree and `dev`, `build`, `typecheck`, `start`, and `config` scripts, with dev and start sharing one `cordis.yml`
+- Create offers the documented features and feature options; local and sandbox bash are exclusive with local as the default, the sandbox Cordis config entry retains the editable commented config example, and HMR is selected by default and loaded by both dev and start
+- Create's `plugin` or `tool` choice creates at most one fixed-name local plugin and atomically updates its files and root-project relationships; this phase provides no `dsh-sdk create`
+- `dsh-sdk config` reads the same support set from an existing project, installs, enables, disables, and switches supported feature options, preserves unknown config and comments, and refuses to modify inconsistent config
+- `.env.example` reflects variables required by the current features; `.env` only appends missing differently named variables and never updates or removes existing contents
+- npm, pnpm, and Yarn workspaces install, build, and start; local plugins resolve from source under dev and from built output under start
+
+## Risks
+
+- Developers can edit a builtin into a shape the registry cannot recognize; the SDK stops automating that feature instead of guessing and overwriting config
+- Pre-write validation and external-edit detection do not provide transactional rollback once multi-file writes begin; an I/O failure can leave a partial commit requiring manual repair
+- The sandbox feature option depends on an available local sandbox backend for the target platform; an unavailable backend must fail closed instead of falling back to unsandboxed execution
+- HMR retains its filesystem watcher and hot-reload behavior under production start; this is the result of an explicit plugin choice, not an implicit development-only service
+- The append-only `.env` policy retains credentials that are no longer used; the SDK does not decide when user-owned secret data is safe to delete
diff --git a/docs/rfc/proposed/feature/2026-07-14-sdk-developer-projects.zh.md b/docs/rfc/proposed/feature/2026-07-14-sdk-developer-projects.zh.md
new file mode 100644
index 0000000000..ec08f323ac
--- /dev/null
+++ b/docs/rfc/proposed/feature/2026-07-14-sdk-developer-projects.zh.md
@@ -0,0 +1,167 @@
+# RFC: 开发者拥有的 SDK 工程
+
+Status: proposed
+
+[English](2026-07-14-sdk-developer-projects.md) | 中文
+
+## 问题
+
+DeepSeek Harness 通过 Cordis 插件对功能进行组合，但从空目录开始搭建一个可运行工程仍要求开发者同时理解 NPM 依赖、`cordis.yml` 插件组、环境变量、TypeScript 构建、本地插件 workspace 和运行入口。手工步骤之间存在约束，漏掉任意一处都会得到能够安装却无法开发、能够开发却无法构建，或能够构建却无法启动的工程。
+
+一次性生成器只能降低首次创建成本。若生成结果隐藏在 preset 或不可编辑的 CLI（命令行界面）内部，高级开发者无法调整插件树、修改 Cordis 插件配置或增加项目特有行为；若创建后的工程完全脱离工具管理，开发者又必须重新承担所有 NPM 依赖和 Cordis 插件配置的一致性工作。
+
+初始创建和后续配置面对同一组内置功能。两条流程各自维护功能列表、功能选项和 NPM 依赖时，新增 Cordis 插件、NPM 包或调整配置会使二者逐渐分叉。工程还需要一条普通的本地插件开发路径，参与开发、构建和启动流程。
+
+## 提案
+
+SDK 创建一个普通、显式且归开发者所有的 TypeScript/Cordis 工程。`cordis.yml` 是唯一的运行时插件树；开发和生产读取同一份文件。工程中的 `package.json`、`cordis.yml`、TypeScript 入口、构建配置和 `plugins/*` 均可直接编辑，SDK 不把它们封装成不可见的 preset。
+
+开发者产品入口只有 `npm create @deepseek-ai/sdk` 和 `dsh-sdk` 命令。前者负责首次创建，`dsh-sdk config` 在创建后管理 SDK 能识别的内置功能，`dsh-sdk dev`、`dsh-sdk build` 与 `dsh-sdk start` 负责开发、构建和启动；本期不提供 `dsh-sdk create`。create 与 config 使用同一份人工编写的功能定义，因此一项功能的功能选项、NPM 依赖、Cordis 配置项、相关文件和识别规则只有一个来源。功能、功能选项等名词由 [SDK 工程编辑架构](../architecture/2026-07-15-sdk-project-editing-architecture.md) 的术语表定义。
+
+SDK 只为功能选择和有限功能选项提供交互，不尝试把任意 Cordis 插件配置变成通用表单。功能选项所需的少量专用输入由所属功能收集；其余 Cordis 插件配置留在 `cordis.yml` 中，并通过注释指明常用改法，由开发者直接修改。
+
+## 开发者流程
+
+首次创建按会影响后续问题集合的顺序收集信息：目标目录与 package 身份、模型提供方与凭据、运行接口、内置功能与功能选项、可选本地插件、包管理器，以及是否安装 NPM 依赖并构建。命令参数已提供的答案不重复询问；本期 create 和 config 都要求交互式 TTY，取消创建时不写入目标目录。
+
+```sh
+npm create @deepseek-ai/sdk my-agent
+cd my-agent
+npm exec dsh-sdk dev index.ts
+npm exec dsh-sdk config
+npm exec dsh-sdk build
+npm exec dsh-sdk start index.js
+```
+
+create 拒绝任何已经存在的目标路径。工程文件提交成功后，CLI 询问是否安装 NPM 依赖并构建；安装或构建失败时保留生成结果，并打印可以重新执行的命令。
+
+create 还提供一次 `none / plugin / tool` 选择。`plugin` 固定生成 `plugins/plugin` 的 Cordis 插件，`tool` 固定生成 `plugins/tool` 的模型工具；一次创建至多包含一个本地插件。生成操作同时更新 workspace、根 NPM 依赖、TypeScript reference、构建配置和 `cordis.yml`，任何写入前校验失败都不创建工程。
+
+## 创建时支持的功能
+
+下表是本期 create 面向开发者展示的支持集。`required` 始终存在但仍可切换有限功能选项；`default` 在选择树中预选；`optional` 由开发者主动选择。表格说明产品支持集，运行时注册表是实现的事实源。
+
+| 功能 | create 状态 | 功能选项 | 限制与关系 |
+|---|---|---|---|
+| `provider` | required | `deepseek`（默认）/ `custom` | DeepSeek 收集 API key；custom 另收集 base URL，模型名可由 CLI 参数覆盖 |
+| `app` | required | `stdio`（默认）/ `acp` / `embed` | 选择运行接口 |
+| `spine` | required | `default` | timer、LLM seam、会话存储、系统提示词、工具注册表、agent 注册表，以及 agent loop |
+| `bash` | required | `local`（默认）/ `sandbox` | 两个功能选项互斥、与运行接口正交，且都安装面向模型的 bash 工具；sandbox 安装本地沙箱提供方和沙箱 bash 后端 |
+| `persistence` | required | `jsonl`（默认）/ `sqlite` | 每个工程恰好选择一个持久化后端 |
+| `hmr` | default | `default` | 加载 `@cordisjs/plugin-hmr`；dev 和 start 都启用，使用插件默认配置 |
+| `fs` | default | `local` | 安装本地文件系统、策略和模型工具；进程沙箱不约束进程内 fs 工具 |
+| `todo` | default | `default` | 提供 `todo_write` 工具 |
+| `skill` | default | `default` | 安装 skill（技能）注册表、本地 skill 提供方和面向模型的 skill 工具 |
+| `web` | optional | `deepseek`（默认）/ `exa` / `perplexity` / `fetch-only` | 搜索功能选项互斥；Exa/Perplexity 收集各自 API key；建议同时启用 timeout policy |
+| `subagent` | optional | `spawn`（默认）/ `fork`，可多选 | 本期只提供进程内后端 |
+| `workflow` | optional | `workerthread` | 要求 subagent 的 `spawn` 功能选项 |
+| `compact` | optional | `basic` | 使用 SDK 提供的上下文压缩参数 |
+| `hooks` | optional | `claude`（默认）/ `codex`，可多选 | 各功能选项生成独立的可编辑配置文件 |
+| `guard` | optional | `repeat-tool` | 提供重复工具调用提醒 |
+| `timeout-policy` | optional | `default` | 对声明超时预算的工具执行统一策略 |
+| `ask-user` | optional | `default` | 提供 `ask_user_question` 工具；注入的 user-interaction 服务由 acp/stdio 两个功能选项提供，因此仅这两个接口可选 |
+
+`bash` 的两个功能选项都适用于 ACP、stdio 和 embed，不由运行接口决定。sandbox 功能选项不写任何生效的配置键，因而沿用 `dsh-bash-sandbox` 的 `read-only` 默认值；生成的 `cordis.yml` 保留注释示例，开发者可以显式改为 `workspace-write`：
+
+```yaml
+- id: bash
+ name: '@deepseek-ai/dsh-bash-sandbox'
+ # Uncomment to allow writes under the project workspace.
+ # config:
+ # mode: workspace-write
+ # workspaceRoot: !!js process.cwd()
+```
+
+功能贡献只引用单插件 NPM 包，绝不引用 `agent-spine-demo`、`stdio-demo`、`acp-demo` 这类组合 NPM 包。表格之外的插件不由本期 create 管理；开发者仍可直接编辑普通工程文件进行高级组合。
+
+## 生成工程
+
+使用默认答案创建 npm 工程时，provider 为 DeepSeek，运行接口为 stdio，bash 为 local，持久化为 JSONL，hmr、fs、todo 与 skill 处于选中状态。初始目录树为：
+
+```text
+my-agent/
+├── .env
+├── .env.example
+├── .gitignore
+├── README.md
+├── cordis.yml
+├── index.ts
+├── package.json
+├── tsconfig.base.json
+├── tsconfig.json
+└── tsdown.config.ts
+```
+
+`.env.example` 始终存在，并由 SDK 根据当前功能维护占位。收集到 secret 或开发者确认稍后填写空凭据时，同时生成 gitignored `.env`。SDK 只向 `.env` 追加尚不存在的不同名变量，绝不覆盖或删除已有内容；切换功能选项可以清理 `.env.example` 中不再需要的占位，但旧凭据仍留在 `.env` 中供开发者自行处理。pnpm 和 Yarn 工程增加各自所需的 workspace 配置文件，但运行时插件树和 TypeScript 入口不分叉。
+
+生成的 `package.json` 提供以下 scripts；其中 `dev`、`build`、`start` 与 `config` 调用 `dsh-sdk`，`typecheck` 直接调用 TypeScript：
+
+| script | 行为 |
+|---|---|
+| `dev` | 运行 `dsh-sdk dev index.ts`，为 TypeScript 和本地 workspace 插件注册开发期解析 |
+| `build` | 运行 `dsh-sdk build`，调用工程安装的 tsdown 构建根入口和 `plugins/*` package |
+| `typecheck` | 直接运行 `tsc -b` |
+| `start` | 运行 `dsh-sdk start index.js`，启动已构建入口且不隐式构建 |
+| `config` | 运行 `dsh-sdk config`，修改当前工程功能树 |
+
+`dsh-sdk start` 与 `dsh-sdk dev` 可以接收模块 target，并把 `--` 后的参数原样转发给工程入口。通用参数解析使用 Node `parseArgs()` 的零 schema 模式：带值 flag 采用 `--key=value`，bare flag 转换为 `true`，`--no-*` 转换为 `false`。
+
+- stdio 工程通过 `--model=` 传入所选 model，并根据可选的 `--resume=` 创建或恢复 agent；
+- acp 使用协议 `session/load`
+- embed 使用生成代码中的 model。
+
+每个功能拥有的 Cordis 配置项在 `cordis.yml` 中保留自己的可编辑 Cordis 插件配置和说明注释；`dsh-sdk config` 修改其他功能时必须保留未知字段、未修改节点的格式和注释。HMR（热模块替换）是普通叶子配置项：选择该功能后，dev 和 start 加载同一个 watcher，命令不隐式改变插件树。
+
+## 创建后的配置
+
+`dsh-sdk config` 只要求当前目录具有可读的根 `package.json` 与 `cordis.yml`。它检查标准功能及其当前功能选项，以一棵功能树表达最终目标状态，并在 Review & Apply 前展示功能变化和受影响文件。
+
+`dsh-sdk config` 可以安装缺失功能、启停已安装功能和切换有限功能选项。required 功能不能取消。改变 NPM 依赖后只运行一次项目包管理器安装；安装失败不回滚已经提交的工程文件。
+
+SDK 只修改功能明确拥有的 Cordis 配置项、配置键、NPM 依赖、`.env.example` 占位和独占文件。同一功能选项的更新保留 Cordis 配置项中的未知配置键；手写或第三方插件只支持按稳定 ID 启停。已知功能被手改成不完整、歧义或无法读取的形状时，`dsh-sdk config` 显示诊断并拒绝自动修改，直到开发者手工修复。
+
+一次 config 会话在内存工作区上累计全部修改。Apply 前完成功能关系、资源冲突和文件形状校验，并比较受影响文件与会话打开时的原文；校验失败或检测到外部修改时不写盘。实际写盘开始后不提供跨文件事务回滚。
+
+## 维护模型
+
+Builtin 支持集由 SDK 人工策划，不根据 NPM 依赖名称或目录约定自动暴露。一个功能可以组合多个 Cordis 配置项，功能选项可以共享资源，并声明对其他功能或特定功能选项的功能依赖；新增普通功能或功能选项不应要求同时修改 create 和 config 两个命令流程。
+
+## 后续工作
+
+- `dsh-sdk add [package-spec]`：统一本地插件创建与外部 Cordis 插件接入；未指定 package 或仓库来源时创建本地 plugin/tool，指定来源时增加 NPM 依赖和 `cordis.yml` 配置项，来源模型为 GitHub 仓库等扩展保留空间
+- 非交互 create/config：本期两个流程都要求 TTY，不提供供自动化调用的完整输入合同
+- 更多功能专用参数输入：本期产品只展示有限功能选项、secret 和少量专用值，不为 Cordis 插件配置提供通用参数界面
+
+## 曾考虑的替代方案
+
+**不可编辑的 preset 或生成器托管工程。** 该方案可以缩短初次创建路径，但会隐藏真实插件树和构建边界，使高级开发者无法直接组合 Cordis 插件，也让项目行为依赖 CLI 版本而不是检入的工程文件。
+
+**只提供一次性生成器。** 创建后完全依赖手工维护，会让功能依赖、功能选项切换和多文件更新再次分散；共享 registry 的 config 流程为生成工程保留持续管理机制。
+
+**为开发和生产维护两份 `cordis.yml`。** 两份插件树会使开发成功无法证明生产加载相同功能；dev 只增加 TypeScript 与本地 workspace 解析，运行配置保持唯一。
+
+**为任意 Cordis 插件配置生成通用表单。** Cordis 插件配置包含嵌套结构、表达式和插件特有语义，通用表单会形成第二套不完整 schema。SDK 只管理有限功能选项和专用 secret，复杂配置继续由开发者直接编辑。
+
+**使用私有协议发现本地插件。** 普通 package manager workspace、根 NPM 依赖、TypeScript references 和 Cordis 配置项已能表达完整关系；额外发现协议会创造只能由 SDK 理解的隐藏状态。
+
+**在现有工程中提供 `dsh-sdk create`。** create 已能生成一种可编辑的本地插件骨架，后续插件可以沿用普通 workspace 和 Cordis 机制手工添加；再提供同构命令会增加第二条脚手架产品面，却不增加新的组合功能。
+
+**把每个新 Cordis 插件自动暴露为 builtin。** package 无法说明多个插件如何组合成一项产品功能，也无法推导互斥关系、功能依赖、secret、接口适用性和安全限制；支持集需要人工策划，自动化只适合检查候选是否完成分类。
+
+## 验收标准
+
+- `npm create @deepseek-ai/sdk` 按本文顺序收集项目身份、provider、interface、功能、可选本地插件、包管理器和安装选择，并在取消时保持目标路径不存在
+- 默认 npm 工程具有本文目录树和 `dev`、`build`、`typecheck`、`start`、`config` scripts，且 dev/start 使用同一份 `cordis.yml`
+- create 展示本文功能及功能选项；`bash` 的 local/sandbox 二选一且默认 local，sandbox Cordis 配置项保留可编辑的注释配置示例；HMR 默认选中并同时由 dev/start 加载
+- create 的 `plugin` 或 `tool` 选择至多生成一个固定名称的本地插件，并原子更新插件文件与根工程关系；本期不提供 `dsh-sdk create`
+- `dsh-sdk config` 从现有工程读取同一支持集，能够安装、启停和切换支持的功能选项，保留未知配置与注释，并拒绝修改不一致配置
+- `.env.example` 反映当前功能所需变量；`.env` 只追加缺失的不同名变量，从不覆盖或清理已有内容
+- npm、pnpm 和 Yarn 生成的 workspace 能安装、构建和启动；本地插件在 dev 中使用源码，在 start 中使用构建产物
+
+## 风险
+
+- 开发者可以把 builtin 手改成 registry 无法识别的形状；SDK 选择停止自动化而不是猜测并覆盖配置
+- 多文件写入前的校验和外部修改检测不能提供写入阶段的事务回滚；I/O 中途失败可能留下需要人工修复的部分提交
+- sandbox 功能选项依赖目标平台存在可用的本地沙箱后端；后端不可用时必须 fail closed，不能退回无沙箱执行
+- HMR 在生产启动中也保持文件 watcher 和热重载行为；这是显式插件选择的结果，不是仅限开发环境的隐式服务
+- `.env` 的仅追加策略会保留已经不用的凭据，SDK 不判断这些用户数据何时可以安全删除
diff --git a/docs/rfc/proposed/process/2026-07-13-human-review-skill-maintenance.md b/docs/rfc/proposed/process/2026-07-13-human-review-skill-maintenance.md
new file mode 100644
index 0000000000..8098247fdf
--- /dev/null
+++ b/docs/rfc/proposed/process/2026-07-13-human-review-skill-maintenance.md
@@ -0,0 +1,83 @@
+# RFC: Periodic human-review maintenance for dsh-code-review
+
+Status: proposed
+
+## Problem
+
+The `dsh-code-review` skill records failure modes that require reviewer judgment, but one-off audits are expensive to repeat and easy to scope inconsistently. Treating every comment as a lesson produces checklist bloat; treating merge, thread resolution, or an author's “fixed” reply as proof of adoption promotes feedback that the final code may not implement. The maintenance process needs enough evidence and independent review to fail closed without requiring a webhook service, durable event state, or automatic repository promotion before the workflow has proven useful.
+
+## Proposal
+
+Periodic out-of-repo maintenance. A private tool, kept on the skill maintainer's machine rather than committed to this repository, runs against a clean full-history checkout at refreshed `origin/master`. The intended scheduler runs daily with a two-UTC-day overlap; manual runs accept another `--since` duration or repeated `--pr` arguments for an explicit set. The scan is idempotent against the current skill and stores no repository cursor. The only repository file changed by promotion is [.agents/skills/dsh-code-review/SKILL.md](../../../../.agents/skills/dsh-code-review/SKILL.md); the draft PR carries a provenance summary so reviewers can audit the source feedback and adoption evidence without the private adapter logs.
+
+```mermaid
+flowchart TD
+ A["Maintainer or scheduler runs the tool on origin/master"] --> B["List PRs merged in the overlap window"]
+ B --> C["Collect pre-merge User feedback and final PR evidence"]
+ C --> D["Two reviewers verify provenance and adoption"]
+ D --> E{"Both confirm human-authored and adopted?"}
+ E -- "No" --> F["Exclude or retain as unresolved"]
+ E -- "Yes" --> G["Two reviewers classify against the current skill"]
+ G --> H["Draft a complete candidate from agreed guidance"]
+ H --> I["Two reviewers inspect the same skill diff"]
+ I -- "Blocking finding" --> J["Bounded revision loop"]
+ J --> I
+ I -- "Both approve" --> K["Run documentation and lint checks"]
+ K --> L["Leave a reviewed local working-tree diff"]
+```
+
+### Acquisition contract
+
+Each selected PR is filtered before any feedback is retrieved: its merge commit must be an ancestor of `origin/master`. Merge-commit reachability is the sole eligibility check — a stacked PR whose direct base is a feature branch is admitted whenever the base has since reached master, because the code the reviewer commented on is now on master regardless of the intermediate stack. The tool also resolves the landing merge's target parent; a landing shape it cannot reconstruct is logged to `skipped-pulls.json` and skipped. A single PR that fails preflight, acquisition, or evidence collection is skipped rather than aborting the whole run. The search stage fails loud when the window would exceed GitHub's 1,000-result search cap so no merged PR is silently omitted. The acquisition stage reads complete paginated connections for inline review comments, review submissions, and PR commits. PR conversation comments are not acquired because current GitHub state cannot prove which surviving commit preceded them after a force-push, so the adoption contract would exclude them unconditionally. The workflow admits acquired feedback only when GitHub reports the actor `type` as `User`, and only when both creation and last-edit timestamps strictly predate the PR merge (an equal-timestamp edit is treated as post-merge); review submissions use GraphQL `lastEditedAt` because the REST representation omits edit time.
+
+### Adoption evidence
+
+Each feedback item carries a stable source ID and bounded change evidence. When the reviewer's `commit_id` still belongs to the PR (force-push fail-closed), the tool selects the latest PR commit whose committer timestamp strictly predates the feedback as the baseline — not the reviewer's clicked commit, which may be an older commit. It never compares that baseline directly with the landing merge: such a diff includes unrelated changes from an advancing target branch. Instead, it gives the adoption reviewers two PR-specific patch snapshots. Let `B` be the feedback baseline, `T` the landing merge's target parent, and `M` the landing merge. The feedback-time snapshot is the tree diff from `merge-base(B, T)` to `B`; the final snapshot is the tree diff from `T` to `M`. A target-only change therefore appears in neither PR patch, while a change added to the PR after feedback appears only in the final snapshot. Force-pushed reviews, feedback that predates every surviving PR commit, and landing shapes whose target parent cannot be reconstructed are deterministically classified `unclear` before any reviewer sees them. Merge status, a resolved thread, an author's “fixed” reply, or a same-file edit is context rather than adoption proof; the PR author's own comments never reach the adapter as they cannot be adoption of themselves.
+
+### Dual-reviewer classification and drafting
+
+Two independently configured reviewer adapters classify every eligible item by provenance (`human-authored`, `forwarded-automation`, or `unclear`) and adoption (`adopted`, `rejected`, or `unclear`). Only matching `human-authored` plus `adopted` verdicts proceed. The adopted set then receives a second independent classification against the current skill: candidate, already covered, implementation-specific, or not feedback. A singleton may qualify; recurrence is not required. Disagreement receives one bounded re-evaluation and remains visible in run artifacts if unresolved. A single batch whose adapter output fails schema or id validation is failed closed at the batch level — every feedback item in it is marked unclear and routed to `excluded` — rather than aborting the whole run; the offending raw output is preserved under the run's private artifacts for debugging. If either adapter returns no valid result for any nonempty batch in an operation, the run exits non-zero and emits a failure record instead of reporting “no candidate.”
+
+The primary adapter drafts from structured agreed guidance, never raw review text. It remains tool-free and read-only by adapter-author contract: it returns complete candidate file content, which the tool validates before writing the sole target. Both adapters then review the same complete skill diff; blocking findings return to a bounded revision loop, and both must approve the same revision. The tool rejects staged changes and edits outside the target skill both before running the documentation and lint gates and again before reporting success, so a gate or concurrent process that adds another path cannot slip through. It restores its own write on failure using best-effort compare-and-swap so a concurrent maintainer edit is not overwritten. On success it saves a candidate bundle containing the source `origin/master` commit, source skill blob ID, reviewed diff, complete candidate, source feedback IDs and URLs, landed evidence ranges, adapter verdicts, and gate results; it never commits, pushes, opens, or merges a PR.
+
+### Reviewer adapter protocol
+
+Each private executable receives a byte-bounded, versioned JSON request on stdin and returns byte-bounded, schema-conforming JSON on stdout. The tool refuses to run when the two reviewer commands resolve to byte-identical executables — a minimum-bar mechanical check; guaranteeing that primary and secondary are backed by independent providers or models is the deployment operator's responsibility. The `access` and `tools` fields are contract markers on the adapter author, not an OS sandbox: reviewer subprocesses spawn with a scrubbed environment, `cwd` set to a private run directory rather than the repository root, and feedback wrapped in a nonce-tagged `` block that every prompt instructs the model to treat as data; the 128-bit nonce prevents an untrusted body from forging the closing tag. Every subprocess uses bounded, abort-aware process-tree cleanup. Adapter authors implement each operation as pure read-only inference — even the `edit` operation returns complete candidate content in JSON, which the tool validates and writes to the sole target. Every production `git`/`gh`/gate spawn also uses the scrubbed environment so a pre-push hook's routing variables cannot silently redirect the maintainer. Candidate writes and the failure rollback use best-effort compare-and-swap against the last written content; the rollback also unstages the target so an adapter- or gate-staged candidate cannot survive a failed run into a later commit.
+
+### Promotion contract
+
+The promote helper starts from a clean checkout at refreshed `origin/master` and refuses to apply a candidate when the current skill blob differs from the bundle's recorded source blob. The operator then reruns the maintenance analysis or manually rebases the diff and repeats the candidate review; the helper never replaces a newer `SKILL.md` with stale complete-file output. After applying a current candidate, it opens a draft PR whose body lists the source feedback URLs or IDs, the landed commit range used as adoption evidence, the originating run, gate results, and any operator edits. Raw adapter prompts and responses remain private, but repository reviewers receive enough provenance to judge whether each proposed rule follows from adopted human feedback.
+
+### Where the mechanism lives
+
+The tool source, adapter binaries, provider credentials, and intended daily scheduler are kept private to the maintainer's machine rather than committed to this repository. This document specifies the protocol; the reference implementation is private infrastructure. The mechanism serves a single skill maintained by a single operator, so the ongoing cost of vetting mechanism edits through repository review outweighs any provenance benefit. If the mechanism is ever handed off to a second maintainer, that handoff is a follow-up RFC that revises this decision — the operator doc at [docs/cookbook/maintaining-dsh-code-review.md](../../../cookbook/maintaining-dsh-code-review.md) is the entry point for anyone taking over.
+
+## Alternatives considered
+
+- **Ship the tool inside this repository.** Rejected for a single-maintainer scope: repository maintenance overhead (typecheck, lint, coverage, cross-cutting refactors) would exceed the value of committed provenance. Retained option for a later handoff.
+- **Record every feedback-time PR head** — rejected: it improves causal isolation but requires a continuously running observer, durable event state, retries, and force-push reconciliation. Periodic maintenance uses reviewed-commit evidence where available and fails closed on broader whole-PR evidence.
+- **Persist a processed-PR cursor** — rejected: an overlapping time-window scan is cheap and naturally idempotent against the current skill, while cursor state creates recovery and missed-event problems.
+- **Run on every new comment** — rejected: review waves produce many related comments and lack the final artifact needed to judge adoption.
+- **Treat merge or thread resolution as adoption** — rejected: a PR can merge with rejected, superseded, or intentionally unresolved feedback.
+- **Create or merge repository changes automatically** — rejected: the tool first needs a track record of useful periodic output. The maintainer inspects and promotes the local diff through normal repository review.
+- **Learn from bot findings that were fixed** — rejected: the source contract is human review feedback. Actor type is filtered before analysis, and human accounts forwarding automated findings are excluded by provenance review.
+- **Use one reviewer as author and final judge** — rejected: independent verdicts expose unsupported generalization before it reaches the skill.
+
+## Acceptance criteria
+
+Promotion from `proposed/` to `implemented/` requires all of the following to be observed in a real end-to-end run against this repository:
+
+- The private tool runs from a clean detached checkout at refreshed `origin/master` and either reports "no candidate" or produces a working-tree diff limited to `.agents/skills/dsh-code-review/SKILL.md`. **Observed on 2026-07-15:** 62 merged PRs scanned, 5 skipped (unreachable merge commit or >250-commit acquisition cap), 426 human feedback items considered, 0 candidates surfaced.
+- Both reviewer adapters are independently configured (distinct providers or models) and complete an analyze / adopt / review pass without user intervention. **Observed on 2026-07-15:** distinct primary/secondary adapters completed adoption + analysis in ~8 minutes; batch fail-closed handled one adapter id-hallucination without aborting the run.
+- A scheduler triggers the tool without an interactive terminal, and a candidate diff (or a "no candidate" record) reaches the operator through a durable notification channel.
+- A controlled acquisition case advances the target branch with a feedback-matching change after the feedback baseline; the reviewer evidence excludes that target-only change while retaining a later PR-owned change.
+- The promote helper rejects a candidate after the source skill changes, and a current candidate opens a draft PR with the provenance summary defined above.
+- At least one candidate diff produced by this workflow is inspected by the operator and promoted to `master` through a normal repository PR review. That PR is the evidence that the workflow can turn adopted feedback into shipped skill guidance.
+
+## Risks
+
+- **Causality inferred from committer timestamps.** The feedback-commit baseline is selected by comparing GitHub commit timestamps with feedback creation timestamps; committer clock skew and rewrites still leave a residual false-adoption window. Cross-referencing GitHub's PR event stream would tighten this but requires event acquisition beyond the scope of the periodic tool.
+- **Two-non-candidate classifications routed to `excluded` without a dispute round.** When both classifiers say "not a candidate" but disagree on which non-candidate reason applies (for example `covered` vs `specific`), the item is excluded rather than re-evaluated. Both classifiers agree the item does not become new reviewer behavior, so a dispute round would not change the outcome.
+- **Dual-reviewer independence beyond byte-hash distinctness is a deployment contract.** The tool refuses to run when the two commands resolve to byte-identical executables, but cannot verify that two distinct wrappers back different providers or models. Operators must configure independent primary and secondary adapters.
+- **Best-effort compare-and-swap for candidate writes and rollback.** File-based CAS on POSIX is not truly atomic; the window is one event-loop tick. The tool targets single-user periodic maintenance and a truly concurrent editor is out of scope.
+- **Single-maintainer bus factor.** Because the mechanism lives on one machine, its interruption stops skill maintenance entirely until the operator restores service or hands off to a new maintainer through a follow-up RFC.
diff --git a/docs/rfc/rejected/simplification/2026-06-20-drop-bash-output-spill-files.md b/docs/rfc/rejected/simplification/2026-06-20-drop-bash-output-spill-files.md
index 0a13d90f1b..859bd6f23d 100644
--- a/docs/rfc/rejected/simplification/2026-06-20-drop-bash-output-spill-files.md
+++ b/docs/rfc/rejected/simplification/2026-06-20-drop-bash-output-spill-files.md
@@ -12,7 +12,7 @@ This solves a real problem, but in a narrow and leaky way. A spill path is a pro
Keep tail truncation, drop full-output spill files. A bash result contains the bounded tail plus a clear truncation marker; no path is emitted. If users need full-output recovery, add a generic artifact/blob service with explicit ownership, cleanup, and UI rendering, then let bash attach large outputs to that service.
-This proposal can land independently of [a generic long-running tool runtime](../../proposed/architecture/2026-06-20-generic-long-running-tool-runtime.md). If background tasks stay, `bash_output` should still report that output was dropped, but without advertising a spill path.
+This proposal can land independently of [a generic long-running tool runtime](../../implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md). If background tasks stay, `bash_output` should still report that output was dropped, but without advertising a spill path.
## Acceptance criteria
diff --git a/docs/tool-catalog.md b/docs/tool-catalog.md
index 9ea71d3005..121bfd09f7 100644
--- a/docs/tool-catalog.md
+++ b/docs/tool-catalog.md
@@ -17,11 +17,12 @@ This table connects model-visible tool names to the plugin package and service s
| --- | --- | --- | --- | --- | --- |
| `@deepseek-ai/dsh-tool-ask-user` | `ask_user_question` | `ctx.tools`, `ctx.userInteraction` | `tool/call`, `tool/result after a UI/provider answers the question` | - | ask_user_question pauses the tool call until the active UI provider returns a human answer. |
| `@deepseek-ai/dsh-tools` | `run_code` | `ctx.tools`, `ctx.codeRuntime (execution time)`, `ctx.systemPrompt` | `tool/call`, `one tool/code-dispatch per bridged sub-call`, `tool/result` | - | Owned by the tool registry as a reserved transport outside filterable capability layers under `mode: code` / `mode: both` (see the Code Mode RFC). Under `code` it is the registry's only wire contribution; the other visible capabilities are declared in a generated TypeScript SDK section, and a program calls them through serialized bindings that re-enter the complete guarded tool pipeline and link each nested execution to this outer result. |
-| `@deepseek-ai/dsh-tool-bash` | `bash`, `bash_kill`, `bash_output` | `ctx.tools`, `ctx.bash` | `tool/call`, `tool/result`, `context/message via agent.inject() for background completion notices` | - | The bash/bash_output/bash_kill tools are model-facing consumers of the bash executor seam. |
+| `@deepseek-ai/dsh-tool-bash` | `bash` | `ctx.tools`, `ctx.bash`, `ctx.tasks at call time for run_in_background` | `tool/call`, `tool/result` | - | The bash tool is the model-facing consumer of the bash executor seam. A `run_in_background` run registers with the generic `ctx.tasks` runtime and is collected/stopped through the `task_*` tools from `@deepseek-ai/dsh-tool-tasks`; the `enableRunInBackground` config (default true) removes the parameter entirely when disabled. |
| `@deepseek-ai/dsh-tool-cordis` | `cordis_inspect`, `cordis_mount`, `cordis_unmount` | `ctx.tools` | `tool/call`, `tool/result`, `live plugin-tree mutations (mount/unmount)` | - | Ships in examples/cordis-agent only (a deliberate opt-in — mounted code gets the real ctx, see docs/rfc/implemented/feature/2026-07-08-self-referential-cordis-toolset.md). Plugins the model mounts may register ADDITIONAL model-visible tools at runtime; the request-header ToolsDelta logs those tool-set changes. |
| `@deepseek-ai/dsh-tool-fs` | `edit`, `read`, `write` | `ctx.tools`, `ctx.fs`, `ctx.systemPrompt` | `tool/call`, `fs/write-intent or fs/edit-intent for mutations`, `fs/observed after successful file operations`, `tool/result` | - | The read-before-write/edit policy is added by `@deepseek-ai/dsh-fs-policy` (an `fs/*` event-gate plugin, no schema change); a deployment that loads these tools is expected to also load it. The tool schemas above are identical with or without the policy plugin. |
| `@deepseek-ai/dsh-tool-skill` | `skill` | `ctx.tools`, `ctx.skills` | `tool/call`, `tool/result` | - | - |
| `@deepseek-ai/dsh-tool-subagent` | `subagent` | `ctx.tools`, `ctx.subagents` | `tool/call`, `tool/result`, `child session events through the chosen provider` | `subagent`, `subagent_fork` | The registered tool name is the load-time `toolName` config (default `subagent`); the schema above is that default. The shipped example agents load this package once per subagent backend, so the model additionally sees `subagent_fork` (bound to the fork backend) with an identical schema — see `examples/coding-agent/cordis.yml` and `examples/acp-agent/cordis.yml`. |
+| `@deepseek-ai/dsh-tool-tasks` | `task_kill`, `task_list`, `task_output` | `ctx.tools`, `ctx.tasks`, `ctx.systemPrompt` | `tool/call`, `tool/result`, `context/message via agent.inject() for background completion notices` | - | The kind-agnostic background-task control surface: a background bash command and a background subagent are read, listed, and killed through the same three tools. Loading the plugin attaches the control surface that arms producers' `ctx.tasks.start()`. |
| `@deepseek-ai/dsh-tool-todo` | `todo_write` | `ctx.tools`, `owning Agent session` | `tool/call`, `todo/write`, `tool/result` | - | todo_write is session-owned state; UIs render the latest todo/write event as a checklist or ACP plan. |
| `@deepseek-ai/dsh-tool-workflow` | `workflow` | `ctx.tools`, `ctx.workflows`, `ctx.systemPrompt`, `a calling Agent (exec.agent parents the script children)` | `tool/call`, `tool/result` | - | - |
| `@deepseek-ai/dsh-tool-web` | `web_fetch`, `web_search` | `ctx.tools`, `ctx.web`, `ctx.systemPrompt` | `tool/call`, `tool/result` | - | web_search and web_fetch keep provider selection behind ctx.web so model-visible schemas stay stable across backend swaps. |
@@ -125,7 +126,7 @@ Owned by the tool registry as a reserved transport outside filterable capability
### `bash`
-Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Commands may run under a file sandbox; a blocked file operation is reported as `[sandbox: file access denied under mode]` — a policy denial, not a bug in the command; do not retry another way (a background task reports the same marker via bash_output once it has finished). Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.
+Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Commands may run under a file sandbox; a blocked file operation is reported as `[sandbox: file access denied under mode]` — a policy denial, not a bug in the command; do not retry another way. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; read its output with `task_output` and stop it with `task_kill`.
```json
{
@@ -149,7 +150,7 @@ Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs
},
"run_in_background": {
"type": "boolean",
- "description": "Run in the background and return a task id immediately. No timeout applies."
+ "description": "Run in the background and return a task id immediately (collect with task_output, stop with task_kill). No timeout applies."
}
},
"required": [
@@ -161,49 +162,7 @@ Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs
Source: [`packages/bash/tool-bash/src/index.ts`](../packages/bash/tool-bash/src/index.ts)
-### `bash_kill`
-
-Ask the executor to kill a running background bash task by task id.
-
-```json
-{
- "type": "object",
- "properties": {
- "task_id": {
- "type": "string",
- "description": "Task id returned by the bash tool."
- }
- },
- "required": [
- "task_id"
- ]
-}
-```
-
-Source: [`packages/bash/tool-bash/src/index.ts`](../packages/bash/tool-bash/src/index.ts)
-
-### `bash_output`
-
-Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.
-
-```json
-{
- "type": "object",
- "properties": {
- "task_id": {
- "type": "string",
- "description": "Task id returned by the bash tool."
- }
- },
- "required": [
- "task_id"
- ]
-}
-```
-
-Source: [`packages/bash/tool-bash/src/index.ts`](../packages/bash/tool-bash/src/index.ts)
-
-The bash/bash_output/bash_kill tools are model-facing consumers of the bash executor seam.
+The bash tool is the model-facing consumer of the bash executor seam. A `run_in_background` run registers with the generic `ctx.tasks` runtime and is collected/stopped through the `task_*` tools from `@deepseek-ai/dsh-tool-tasks`; the `enableRunInBackground` config (default true) removes the parameter entirely when disabled.
## `@deepseek-ai/dsh-tool-cordis`
@@ -398,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.
+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
{
@@ -411,6 +370,10 @@ Delegate a self-contained task to a subagent (a separate agent that works in its
"prompt": {
"type": "string",
"description": "The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."
+ },
+ "run_in_background": {
+ "type": "boolean",
+ "description": "Run as a background task and return its id; collect with task_output or stop with task_kill."
}
},
"required": [
@@ -424,6 +387,77 @@ Source: [`packages/subagent/tool-subagent/src/index.ts`](../packages/subagent/to
The registered tool name is the load-time `toolName` config (default `subagent`); the schema above is that default. The shipped example agents load this package once per subagent backend, so the model additionally sees `subagent_fork` (bound to the fork backend) with an identical schema — see `examples/coding-agent/cordis.yml` and `examples/acp-agent/cordis.yml`.
+## `@deepseek-ai/dsh-tool-tasks`
+
+### `task_kill`
+
+Request cancellation of a running background task by task id. Returns immediately; the task settles as killed once its work actually stops.
+
+```json
+{
+ "type": "object",
+ "properties": {
+ "task_id": {
+ "type": "string",
+ "description": "Task id returned by the tool that started the background work."
+ },
+ "reason": {
+ "type": "string",
+ "description": "Optional short reason, recorded in the log and forwarded to the task."
+ }
+ },
+ "required": [
+ "task_id"
+ ]
+}
+```
+
+Source: [`packages/tasks/tool-tasks/src/index.ts`](../packages/tasks/tool-tasks/src/index.ts)
+
+### `task_list`
+
+List your background tasks (running and finished) with their ids, kinds, and statuses.
+
+```json
+{
+ "type": "object",
+ "properties": {}
+}
+```
+
+Source: [`packages/tasks/tool-tasks/src/index.ts`](../packages/tasks/tool-tasks/src/index.ts)
+
+### `task_output`
+
+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
+{
+ "type": "object",
+ "properties": {
+ "task_id": {
+ "type": "string",
+ "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."
+ },
+ "timeout_ms": {
+ "type": "number",
+ "description": "Max wait in milliseconds (only meaningful with wait: true). Defaults to the configured wait timeout; capped by the configured maximum."
+ }
+ },
+ "required": [
+ "task_id"
+ ]
+}
+```
+
+Source: [`packages/tasks/tool-tasks/src/index.ts`](../packages/tasks/tool-tasks/src/index.ts)
+
+The kind-agnostic background-task control surface: a background bash command and a background subagent are read, listed, and killed through the same three tools. Loading the plugin attaches the control surface that arms producers' `ctx.tasks.start()`.
+
## `@deepseek-ai/dsh-tool-todo`
### `todo_write`
diff --git a/eslint.config.mjs b/eslint.config.mjs
index 3f0e8ce820..189b762185 100644
--- a/eslint.config.mjs
+++ b/eslint.config.mjs
@@ -74,7 +74,7 @@ export default tseslint.config(
// --- tests: same rules, minus the friction that fights test ergonomics --
{
- files: ['packages/*/*/tests/**/*.ts', 'examples/*/tests/**/*.ts'],
+ files: ['packages/*/*/tests/**/*.ts', 'examples/*/tests/**/*.ts', 'scripts/**/*.spec.ts'],
extends: [
...tseslint.configs.strictTypeChecked,
],
diff --git a/examples/AGENTS.md b/examples/AGENTS.md
index f74dda4687..df330de838 100644
--- a/examples/AGENTS.md
+++ b/examples/AGENTS.md
@@ -1,8 +1,8 @@
# AGENTS.md — Examples
-Runnable harness compositions. **Examples are not workspaces:** private package stubs are not built. App bins load each `cordis.yml` through `tsx`; package names resolve through root `tsconfig.json` paths, not `node_modules`.
+Runnable harness compositions. **Examples are NOT workspaces**: their private `package.json` files are dependency-free stubs, and the cordis Loader boots each `cordis.yml` unbuilt through `tsx` plus the root tsconfig paths.
-Keep wiring, demo fixtures, and e2e/snapshot scenarios here. Move reusable logic into `packages/`, with coverage and a README. App bins own bootstrapping; examples have no `start.ts`.
+Extract reusable logic into `packages/`, where per-file coverage and README gates apply. Examples keep only `cordis.yml` wiring, demo artifacts, and e2e/snapshot scenarios; app package bins own boot glue.
## E2E smokes
diff --git a/examples/acp-agent/tests/snapshots/advanced-toolchain/system-prompt.golden.md b/examples/acp-agent/tests/snapshots/advanced-toolchain/system-prompt.golden.md
index 5ad12cddff..33bfa25590 100644
--- a/examples/acp-agent/tests/snapshots/advanced-toolchain/system-prompt.golden.md
+++ b/examples/acp-agent/tests/snapshots/advanced-toolchain/system-prompt.golden.md
@@ -7,6 +7,8 @@ Verify your work by running the code or tests. Keep answers brief and factual.
Check the [exit code: N] marker on every bash result; investigate failures before moving on.
+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.
+
Approval prompts are disabled in this session: actions that require approval are rejected automatically — do not request sandbox escalation (do not set `sandbox_permissions`).
@@ -25,7 +27,7 @@ The available tools:
```ts
declare const tools: {
- /** Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Commands may run under a file sandbox; a blocked file operation is reported as `[sandbox: file access denied under mode]` — a policy denial, not a bug in the command; do not retry another way (a background task reports the same marker via bash_output once it has finished). Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`. Attempting a command the sandbox may deny is safe and expected: run it and read the marker rather than assuming the denial. When a command is denied and a wider mode would let it succeed, escalate immediately in the same turn — the one sanctioned exception to a denial: retry the exact same command once with `sandbox_permissions` (the narrowest wider mode that suffices) plus a one-sentence `justification`. Do not detour through chat to ask permission first — the approval prompt raised by that retry is how the user consents. If the session states approval prompts are disabled, there is no exception: a denial is final — do not set `sandbox_permissions`. Never escalate speculatively: ground the request in a real denial — normally the one this command just hit; escalating up front is fine only when this session already denied the same access. A rejected escalation is final for that command — stop and explain, never work around it — but it does not forbid attempting or escalating other commands later. */
+ /** Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Commands may run under a file sandbox; a blocked file operation is reported as `[sandbox: file access denied under mode]` — a policy denial, not a bug in the command; do not retry another way. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; read its output with `task_output` and stop it with `task_kill`. Attempting a command the sandbox may deny is safe and expected: run it and read the marker rather than assuming the denial. When a command is denied and a wider mode would let it succeed, escalate immediately in the same turn — the one sanctioned exception to a denial: retry the exact same command once with `sandbox_permissions` (the narrowest wider mode that suffices) plus a one-sentence `justification`. Do not detour through chat to ask permission first — the approval prompt raised by that retry is how the user consents. If the session states approval prompts are disabled, there is no exception: a denial is final — do not set `sandbox_permissions`. Never escalate speculatively: ground the request in a real denial — normally the one this command just hit; escalating up front is fine only when this session already denied the same access. A rejected escalation is final for that command — stop and explain, never work around it — but it does not forbid attempting or escalating other commands later. */
bash(args: {
/** The bash command to execute. */
command: string;
@@ -35,23 +37,13 @@ declare const tools: {
timeoutMs?: number;
/** Working directory for this command. Defaults to the session workspace; a relative path is resolved against it. */
workdir?: string;
- /** Run in the background and return a task id immediately. No timeout applies. */
+ /** Run in the background and return a task id immediately (collect with task_output, stop with task_kill). No timeout applies. */
run_in_background?: boolean;
/** The wider sandbox mode this command needs. Only valid as a one-shot retry of a command the sandbox just denied; requires justification and user approval. */
sandbox_permissions?: "workspace-write" | "danger-full-access";
/** Required with sandbox_permissions: one sentence for the user explaining why this exact command needs the wider access. */
justification?: string;
}): Promise;
- /** Ask the executor to kill a running background bash task by task id. */
- bash_kill(args: {
- /** Task id returned by the bash tool. */
- task_id: string;
- }): Promise;
- /** Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output. */
- bash_output(args: {
- /** Task id returned by the bash tool. */
- task_id: string;
- }): Promise;
/** Inspect the live cordis runtime that is running THIS agent. Read-only. Sections: `services` (every provided ctx service and the plugin fiber that owns it), `plugins` (a flat list of the loaded plugins with their lifecycle states), `tools` (the model-facing tools currently registered, i.e. what you can call), `dynamic` (plugins you mounted via cordis_mount: id, name, state, provided services, awaited services), `api` (method signatures AND argument/return type shapes for every LIVE service — read this before writing plugin code that calls a service), `events` (every harness event with its dispatch mode and exact signature — pick listener targets here). Omit `what` to get all six sections. */
cordis_inspect(args: {
/** Limit the report to one section. Omit for all sections. */
@@ -72,19 +64,41 @@ declare const tools: {
/** The exact skill name from the available skills list. */
name: string;
}): Promise;
- /** 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. */
+ /** 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 as a background task and return its id; collect with task_output or stop with task_kill. */
+ run_in_background?: boolean;
}): Promise;
- /** 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. */
+ /** 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 as a background task and return its id; collect with task_output or stop with task_kill. */
+ run_in_background?: boolean;
+ }): Promise;
+ /** Request cancellation of a running background task by task id. Returns immediately; the task settles as killed once its work actually stops. */
+ task_kill(args: {
+ /** Task id returned by the tool that started the background work. */
+ task_id: string;
+ /** Optional short reason, recorded in the log and forwarded to the task. */
+ reason?: string;
+ }): Promise;
+ /** List your background tasks (running and finished) with their ids, kinds, and statuses. */
+ task_list(args: Record): Promise;
+ /** 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;
+ /** Block until the task reaches a terminal status or the timeout expires. A timed-out wait returns [status: running] and leaves the task alive. */
+ wait?: boolean;
+ /** Max wait in milliseconds (only meaningful with wait: true). Defaults to the configured wait timeout; capped by the configured maximum. */
+ timeout_ms?: number;
}): Promise;
/** Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished). */
todo_write(args: {
diff --git a/examples/acp-agent/tests/snapshots/advanced-toolchain/tool-schemas.golden.json b/examples/acp-agent/tests/snapshots/advanced-toolchain/tool-schemas.golden.json
index e5b5593267..daf4e93ee8 100644
--- a/examples/acp-agent/tests/snapshots/advanced-toolchain/tool-schemas.golden.json
+++ b/examples/acp-agent/tests/snapshots/advanced-toolchain/tool-schemas.golden.json
@@ -2,7 +2,7 @@
"initial": [
{
"name": "bash",
- "description": "Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Commands may run under a file sandbox; a blocked file operation is reported as `[sandbox: file access denied under mode]` — a policy denial, not a bug in the command; do not retry another way (a background task reports the same marker via bash_output once it has finished). Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`. Attempting a command the sandbox may deny is safe and expected: run it and read the marker rather than assuming the denial. When a command is denied and a wider mode would let it succeed, escalate immediately in the same turn — the one sanctioned exception to a denial: retry the exact same command once with `sandbox_permissions` (the narrowest wider mode that suffices) plus a one-sentence `justification`. Do not detour through chat to ask permission first — the approval prompt raised by that retry is how the user consents. If the session states approval prompts are disabled, there is no exception: a denial is final — do not set `sandbox_permissions`. Never escalate speculatively: ground the request in a real denial — normally the one this command just hit; escalating up front is fine only when this session already denied the same access. A rejected escalation is final for that command — stop and explain, never work around it — but it does not forbid attempting or escalating other commands later.",
+ "description": "Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Commands may run under a file sandbox; a blocked file operation is reported as `[sandbox: file access denied under mode]` — a policy denial, not a bug in the command; do not retry another way. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; read its output with `task_output` and stop it with `task_kill`. Attempting a command the sandbox may deny is safe and expected: run it and read the marker rather than assuming the denial. When a command is denied and a wider mode would let it succeed, escalate immediately in the same turn — the one sanctioned exception to a denial: retry the exact same command once with `sandbox_permissions` (the narrowest wider mode that suffices) plus a one-sentence `justification`. Do not detour through chat to ask permission first — the approval prompt raised by that retry is how the user consents. If the session states approval prompts are disabled, there is no exception: a denial is final — do not set `sandbox_permissions`. Never escalate speculatively: ground the request in a real denial — normally the one this command just hit; escalating up front is fine only when this session already denied the same access. A rejected escalation is final for that command — stop and explain, never work around it — but it does not forbid attempting or escalating other commands later.",
"parameters": {
"type": "object",
"properties": {
@@ -24,7 +24,7 @@
},
"run_in_background": {
"type": "boolean",
- "description": "Run in the background and return a task id immediately. No timeout applies."
+ "description": "Run in the background and return a task id immediately (collect with task_output, stop with task_kill). No timeout applies."
},
"sandbox_permissions": {
"type": "string",
@@ -45,38 +45,6 @@
]
}
},
- {
- "name": "bash_kill",
- "description": "Ask the executor to kill a running background bash task by task id.",
- "parameters": {
- "type": "object",
- "properties": {
- "task_id": {
- "type": "string",
- "description": "Task id returned by the bash tool."
- }
- },
- "required": [
- "task_id"
- ]
- }
- },
- {
- "name": "bash_output",
- "description": "Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.",
- "parameters": {
- "type": "object",
- "properties": {
- "task_id": {
- "type": "string",
- "description": "Task id returned by the bash tool."
- }
- },
- "required": [
- "task_id"
- ]
- }
- },
{
"name": "cordis_inspect",
"description": "Inspect the live cordis runtime that is running THIS agent. Read-only. Sections: `services` (every provided ctx service and the plugin fiber that owns it), `plugins` (a flat list of the loaded plugins with their lifecycle states), `tools` (the model-facing tools currently registered, i.e. what you can call), `dynamic` (plugins you mounted via cordis_mount: id, name, state, provided services, awaited services), `api` (method signatures AND argument/return type shapes for every LIVE service — read this before writing plugin code that calls a service), `events` (every harness event with its dispatch mode and exact signature — pick listener targets here). Omit `what` to get all six sections.",
@@ -164,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.",
+ "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": {
@@ -175,6 +143,10 @@
"prompt": {
"type": "string",
"description": "The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."
+ },
+ "run_in_background": {
+ "type": "boolean",
+ "description": "Run as a background task and return its id; collect with task_output or stop with task_kill."
}
},
"required": [
@@ -185,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.",
+ "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": {
@@ -196,6 +168,10 @@
"prompt": {
"type": "string",
"description": "The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."
+ },
+ "run_in_background": {
+ "type": "boolean",
+ "description": "Run as a background task and return its id; collect with task_output or stop with task_kill."
}
},
"required": [
@@ -204,6 +180,58 @@
]
}
},
+ {
+ "name": "task_kill",
+ "description": "Request cancellation of a running background task by task id. Returns immediately; the task settles as killed once its work actually stops.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "task_id": {
+ "type": "string",
+ "description": "Task id returned by the tool that started the background work."
+ },
+ "reason": {
+ "type": "string",
+ "description": "Optional short reason, recorded in the log and forwarded to the task."
+ }
+ },
+ "required": [
+ "task_id"
+ ]
+ }
+ },
+ {
+ "name": "task_list",
+ "description": "List your background tasks (running and finished) with their ids, kinds, and statuses.",
+ "parameters": {
+ "type": "object",
+ "properties": {}
+ }
+ },
+ {
+ "name": "task_output",
+ "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": {
+ "task_id": {
+ "type": "string",
+ "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."
+ },
+ "timeout_ms": {
+ "type": "number",
+ "description": "Max wait in milliseconds (only meaningful with wait: true). Defaults to the configured wait timeout; capped by the configured maximum."
+ }
+ },
+ "required": [
+ "task_id"
+ ]
+ }
+ },
{
"name": "todo_write",
"description": "Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).",
diff --git a/examples/acp-agent/tests/snapshots/both-mode-turn/system-prompt.golden.md b/examples/acp-agent/tests/snapshots/both-mode-turn/system-prompt.golden.md
index ed60d52258..36aa94c53c 100644
--- a/examples/acp-agent/tests/snapshots/both-mode-turn/system-prompt.golden.md
+++ b/examples/acp-agent/tests/snapshots/both-mode-turn/system-prompt.golden.md
@@ -7,6 +7,8 @@ Verify your work by running the code or tests. Keep answers brief and factual.
Check the [exit code: N] marker on every bash result; investigate failures before moving on.
+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.
+
Approval prompts are disabled in this session: actions that require approval are rejected automatically — do not request sandbox escalation (do not set `sandbox_permissions`).
@@ -25,7 +27,7 @@ The available tools:
```ts
declare const tools: {
- /** Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Commands may run under a file sandbox; a blocked file operation is reported as `[sandbox: file access denied under mode]` — a policy denial, not a bug in the command; do not retry another way (a background task reports the same marker via bash_output once it has finished). Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`. Attempting a command the sandbox may deny is safe and expected: run it and read the marker rather than assuming the denial. When a command is denied and a wider mode would let it succeed, escalate immediately in the same turn — the one sanctioned exception to a denial: retry the exact same command once with `sandbox_permissions` (the narrowest wider mode that suffices) plus a one-sentence `justification`. Do not detour through chat to ask permission first — the approval prompt raised by that retry is how the user consents. If the session states approval prompts are disabled, there is no exception: a denial is final — do not set `sandbox_permissions`. Never escalate speculatively: ground the request in a real denial — normally the one this command just hit; escalating up front is fine only when this session already denied the same access. A rejected escalation is final for that command — stop and explain, never work around it — but it does not forbid attempting or escalating other commands later. */
+ /** Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Commands may run under a file sandbox; a blocked file operation is reported as `[sandbox: file access denied under mode]` — a policy denial, not a bug in the command; do not retry another way. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; read its output with `task_output` and stop it with `task_kill`. Attempting a command the sandbox may deny is safe and expected: run it and read the marker rather than assuming the denial. When a command is denied and a wider mode would let it succeed, escalate immediately in the same turn — the one sanctioned exception to a denial: retry the exact same command once with `sandbox_permissions` (the narrowest wider mode that suffices) plus a one-sentence `justification`. Do not detour through chat to ask permission first — the approval prompt raised by that retry is how the user consents. If the session states approval prompts are disabled, there is no exception: a denial is final — do not set `sandbox_permissions`. Never escalate speculatively: ground the request in a real denial — normally the one this command just hit; escalating up front is fine only when this session already denied the same access. A rejected escalation is final for that command — stop and explain, never work around it — but it does not forbid attempting or escalating other commands later. */
bash(args: {
/** The bash command to execute. */
command: string;
@@ -35,41 +37,53 @@ declare const tools: {
timeoutMs?: number;
/** Working directory for this command. Defaults to the session workspace; a relative path is resolved against it. */
workdir?: string;
- /** Run in the background and return a task id immediately. No timeout applies. */
+ /** Run in the background and return a task id immediately (collect with task_output, stop with task_kill). No timeout applies. */
run_in_background?: boolean;
/** The wider sandbox mode this command needs. Only valid as a one-shot retry of a command the sandbox just denied; requires justification and user approval. */
sandbox_permissions?: "workspace-write" | "danger-full-access";
/** Required with sandbox_permissions: one sentence for the user explaining why this exact command needs the wider access. */
justification?: string;
}): Promise;
- /** Ask the executor to kill a running background bash task by task id. */
- bash_kill(args: {
- /** Task id returned by the bash tool. */
- task_id: string;
- }): Promise;
- /** Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output. */
- bash_output(args: {
- /** Task id returned by the bash tool. */
- task_id: string;
- }): Promise;
/** Load the full instructions for an available skill. Call this with the exact skill name from the session skill catalog before acting on a task that names or clearly matches that skill. */
skill(args: {
/** The exact skill name from the available skills list. */
name: string;
}): Promise;
- /** 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. */
+ /** 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 as a background task and return its id; collect with task_output or stop with task_kill. */
+ run_in_background?: boolean;
}): Promise;
- /** 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. */
+ /** 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 as a background task and return its id; collect with task_output or stop with task_kill. */
+ run_in_background?: boolean;
+ }): Promise;
+ /** Request cancellation of a running background task by task id. Returns immediately; the task settles as killed once its work actually stops. */
+ task_kill(args: {
+ /** Task id returned by the tool that started the background work. */
+ task_id: string;
+ /** Optional short reason, recorded in the log and forwarded to the task. */
+ reason?: string;
+ }): Promise;
+ /** List your background tasks (running and finished) with their ids, kinds, and statuses. */
+ task_list(args: Record): Promise;
+ /** 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;
+ /** Block until the task reaches a terminal status or the timeout expires. A timed-out wait returns [status: running] and leaves the task alive. */
+ wait?: boolean;
+ /** Max wait in milliseconds (only meaningful with wait: true). Defaults to the configured wait timeout; capped by the configured maximum. */
+ timeout_ms?: number;
}): Promise;
/** Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished). */
todo_write(args: {
diff --git a/examples/acp-agent/tests/snapshots/both-mode-turn/tool-schemas.golden.json b/examples/acp-agent/tests/snapshots/both-mode-turn/tool-schemas.golden.json
index 3c3e5bb0b2..52e7974409 100644
--- a/examples/acp-agent/tests/snapshots/both-mode-turn/tool-schemas.golden.json
+++ b/examples/acp-agent/tests/snapshots/both-mode-turn/tool-schemas.golden.json
@@ -2,7 +2,7 @@
"initial": [
{
"name": "bash",
- "description": "Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Commands may run under a file sandbox; a blocked file operation is reported as `[sandbox: file access denied under mode]` — a policy denial, not a bug in the command; do not retry another way (a background task reports the same marker via bash_output once it has finished). Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`. Attempting a command the sandbox may deny is safe and expected: run it and read the marker rather than assuming the denial. When a command is denied and a wider mode would let it succeed, escalate immediately in the same turn — the one sanctioned exception to a denial: retry the exact same command once with `sandbox_permissions` (the narrowest wider mode that suffices) plus a one-sentence `justification`. Do not detour through chat to ask permission first — the approval prompt raised by that retry is how the user consents. If the session states approval prompts are disabled, there is no exception: a denial is final — do not set `sandbox_permissions`. Never escalate speculatively: ground the request in a real denial — normally the one this command just hit; escalating up front is fine only when this session already denied the same access. A rejected escalation is final for that command — stop and explain, never work around it — but it does not forbid attempting or escalating other commands later.",
+ "description": "Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Commands may run under a file sandbox; a blocked file operation is reported as `[sandbox: file access denied under mode]` — a policy denial, not a bug in the command; do not retry another way. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; read its output with `task_output` and stop it with `task_kill`. Attempting a command the sandbox may deny is safe and expected: run it and read the marker rather than assuming the denial. When a command is denied and a wider mode would let it succeed, escalate immediately in the same turn — the one sanctioned exception to a denial: retry the exact same command once with `sandbox_permissions` (the narrowest wider mode that suffices) plus a one-sentence `justification`. Do not detour through chat to ask permission first — the approval prompt raised by that retry is how the user consents. If the session states approval prompts are disabled, there is no exception: a denial is final — do not set `sandbox_permissions`. Never escalate speculatively: ground the request in a real denial — normally the one this command just hit; escalating up front is fine only when this session already denied the same access. A rejected escalation is final for that command — stop and explain, never work around it — but it does not forbid attempting or escalating other commands later.",
"parameters": {
"type": "object",
"properties": {
@@ -24,7 +24,7 @@
},
"run_in_background": {
"type": "boolean",
- "description": "Run in the background and return a task id immediately. No timeout applies."
+ "description": "Run in the background and return a task id immediately (collect with task_output, stop with task_kill). No timeout applies."
},
"sandbox_permissions": {
"type": "string",
@@ -45,38 +45,6 @@
]
}
},
- {
- "name": "bash_kill",
- "description": "Ask the executor to kill a running background bash task by task id.",
- "parameters": {
- "type": "object",
- "properties": {
- "task_id": {
- "type": "string",
- "description": "Task id returned by the bash tool."
- }
- },
- "required": [
- "task_id"
- ]
- }
- },
- {
- "name": "bash_output",
- "description": "Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.",
- "parameters": {
- "type": "object",
- "properties": {
- "task_id": {
- "type": "string",
- "description": "Task id returned by the bash tool."
- }
- },
- "required": [
- "task_id"
- ]
- }
- },
{
"name": "run_code",
"description": "Execute a TypeScript program against the available tools. Write the BODY of an async function (erasable syntax only; top-level `await` and `return` work) and call tools as `await tools.name(args)` per the declarations in the system prompt. Only what you print or return comes back — curate it.",
@@ -111,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.",
+ "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": {
@@ -122,6 +90,10 @@
"prompt": {
"type": "string",
"description": "The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."
+ },
+ "run_in_background": {
+ "type": "boolean",
+ "description": "Run as a background task and return its id; collect with task_output or stop with task_kill."
}
},
"required": [
@@ -132,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.",
+ "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": {
@@ -143,6 +115,10 @@
"prompt": {
"type": "string",
"description": "The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."
+ },
+ "run_in_background": {
+ "type": "boolean",
+ "description": "Run as a background task and return its id; collect with task_output or stop with task_kill."
}
},
"required": [
@@ -151,6 +127,58 @@
]
}
},
+ {
+ "name": "task_kill",
+ "description": "Request cancellation of a running background task by task id. Returns immediately; the task settles as killed once its work actually stops.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "task_id": {
+ "type": "string",
+ "description": "Task id returned by the tool that started the background work."
+ },
+ "reason": {
+ "type": "string",
+ "description": "Optional short reason, recorded in the log and forwarded to the task."
+ }
+ },
+ "required": [
+ "task_id"
+ ]
+ }
+ },
+ {
+ "name": "task_list",
+ "description": "List your background tasks (running and finished) with their ids, kinds, and statuses.",
+ "parameters": {
+ "type": "object",
+ "properties": {}
+ }
+ },
+ {
+ "name": "task_output",
+ "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": {
+ "task_id": {
+ "type": "string",
+ "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."
+ },
+ "timeout_ms": {
+ "type": "number",
+ "description": "Max wait in milliseconds (only meaningful with wait: true). Defaults to the configured wait timeout; capped by the configured maximum."
+ }
+ },
+ "required": [
+ "task_id"
+ ]
+ }
+ },
{
"name": "todo_write",
"description": "Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).",
diff --git a/examples/acp-agent/tests/snapshots/code-mode-turn/system-prompt.golden.md b/examples/acp-agent/tests/snapshots/code-mode-turn/system-prompt.golden.md
index ed60d52258..36aa94c53c 100644
--- a/examples/acp-agent/tests/snapshots/code-mode-turn/system-prompt.golden.md
+++ b/examples/acp-agent/tests/snapshots/code-mode-turn/system-prompt.golden.md
@@ -7,6 +7,8 @@ Verify your work by running the code or tests. Keep answers brief and factual.
Check the [exit code: N] marker on every bash result; investigate failures before moving on.
+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.
+
Approval prompts are disabled in this session: actions that require approval are rejected automatically — do not request sandbox escalation (do not set `sandbox_permissions`).
@@ -25,7 +27,7 @@ The available tools:
```ts
declare const tools: {
- /** Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Commands may run under a file sandbox; a blocked file operation is reported as `[sandbox: file access denied under mode]` — a policy denial, not a bug in the command; do not retry another way (a background task reports the same marker via bash_output once it has finished). Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`. Attempting a command the sandbox may deny is safe and expected: run it and read the marker rather than assuming the denial. When a command is denied and a wider mode would let it succeed, escalate immediately in the same turn — the one sanctioned exception to a denial: retry the exact same command once with `sandbox_permissions` (the narrowest wider mode that suffices) plus a one-sentence `justification`. Do not detour through chat to ask permission first — the approval prompt raised by that retry is how the user consents. If the session states approval prompts are disabled, there is no exception: a denial is final — do not set `sandbox_permissions`. Never escalate speculatively: ground the request in a real denial — normally the one this command just hit; escalating up front is fine only when this session already denied the same access. A rejected escalation is final for that command — stop and explain, never work around it — but it does not forbid attempting or escalating other commands later. */
+ /** Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Commands may run under a file sandbox; a blocked file operation is reported as `[sandbox: file access denied under mode]` — a policy denial, not a bug in the command; do not retry another way. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; read its output with `task_output` and stop it with `task_kill`. Attempting a command the sandbox may deny is safe and expected: run it and read the marker rather than assuming the denial. When a command is denied and a wider mode would let it succeed, escalate immediately in the same turn — the one sanctioned exception to a denial: retry the exact same command once with `sandbox_permissions` (the narrowest wider mode that suffices) plus a one-sentence `justification`. Do not detour through chat to ask permission first — the approval prompt raised by that retry is how the user consents. If the session states approval prompts are disabled, there is no exception: a denial is final — do not set `sandbox_permissions`. Never escalate speculatively: ground the request in a real denial — normally the one this command just hit; escalating up front is fine only when this session already denied the same access. A rejected escalation is final for that command — stop and explain, never work around it — but it does not forbid attempting or escalating other commands later. */
bash(args: {
/** The bash command to execute. */
command: string;
@@ -35,41 +37,53 @@ declare const tools: {
timeoutMs?: number;
/** Working directory for this command. Defaults to the session workspace; a relative path is resolved against it. */
workdir?: string;
- /** Run in the background and return a task id immediately. No timeout applies. */
+ /** Run in the background and return a task id immediately (collect with task_output, stop with task_kill). No timeout applies. */
run_in_background?: boolean;
/** The wider sandbox mode this command needs. Only valid as a one-shot retry of a command the sandbox just denied; requires justification and user approval. */
sandbox_permissions?: "workspace-write" | "danger-full-access";
/** Required with sandbox_permissions: one sentence for the user explaining why this exact command needs the wider access. */
justification?: string;
}): Promise;
- /** Ask the executor to kill a running background bash task by task id. */
- bash_kill(args: {
- /** Task id returned by the bash tool. */
- task_id: string;
- }): Promise;
- /** Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output. */
- bash_output(args: {
- /** Task id returned by the bash tool. */
- task_id: string;
- }): Promise;
/** Load the full instructions for an available skill. Call this with the exact skill name from the session skill catalog before acting on a task that names or clearly matches that skill. */
skill(args: {
/** The exact skill name from the available skills list. */
name: string;
}): Promise;
- /** 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. */
+ /** 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 as a background task and return its id; collect with task_output or stop with task_kill. */
+ run_in_background?: boolean;
}): Promise;
- /** 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. */
+ /** 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 as a background task and return its id; collect with task_output or stop with task_kill. */
+ run_in_background?: boolean;
+ }): Promise;
+ /** Request cancellation of a running background task by task id. Returns immediately; the task settles as killed once its work actually stops. */
+ task_kill(args: {
+ /** Task id returned by the tool that started the background work. */
+ task_id: string;
+ /** Optional short reason, recorded in the log and forwarded to the task. */
+ reason?: string;
+ }): Promise;
+ /** List your background tasks (running and finished) with their ids, kinds, and statuses. */
+ task_list(args: Record): Promise;
+ /** 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;
+ /** Block until the task reaches a terminal status or the timeout expires. A timed-out wait returns [status: running] and leaves the task alive. */
+ wait?: boolean;
+ /** Max wait in milliseconds (only meaningful with wait: true). Defaults to the configured wait timeout; capped by the configured maximum. */
+ timeout_ms?: number;
}): Promise;
/** Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished). */
todo_write(args: {
diff --git a/examples/acp-agent/tests/snapshots/escalation-approved/session.jsonl b/examples/acp-agent/tests/snapshots/escalation-approved/session.jsonl
index 7dff360513..070f269bcd 100644
--- a/examples/acp-agent/tests/snapshots/escalation-approved/session.jsonl
+++ b/examples/acp-agent/tests/snapshots/escalation-approved/session.jsonl
@@ -131,8 +131,8 @@
{"type":"assistant/chunk","seq":129,"time":1783962245385,"data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}}
{"type":"assistant/message","seq":130,"time":1783962245385,"data":{"turn":1,"step":1,"content":[{"type":"reasoning","text":"The user wants me to run a command with sandbox_permissions set to danger-full-access, no prior run needed, justified as instructed."},{"type":"tool-call","id":"call_00_d0sAHpJ9mYOJi0z7KNy30441","name":"bash","arguments":"{\"command\": \"printf 'escalated\\\\n' > /tmp/dsh-escalated.txt && cat /tmp/dsh-escalated.txt && rm /tmp/dsh-escalated.txt\", \"description\": \"Write file outside workspace and verify\", \"sandbox_permissions\": \"danger-full-access\", \"justification\": \"the user asked to write a file outside the workspace\"}"}],"usage":{"inputTokens":1501,"outputTokens":174,"cacheReadTokens":0,"reasoningTokens":28}},"sourceEventSeqs":[7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,41,42,43,44,45,46,47,48,49,50,51,52,53,54,55,56,57,58,59,60,61,62,63,64,65,66,67,68,69,70,71,72,73,74,75,76,77,78,79,80,81,82,83,84,85,86,87,88,89,90,91,92,93,94,95,96,97,98,99,100,101,102,103,104,105,106,107,108,109,110,111,112,113,114,115,116,117,118,119,120,121,122,123,124,125,126,127,128,129],"surfaceOp":"append"}
{"type":"tool/call","seq":131,"time":1783962245385,"data":{"turn":1,"step":1,"callId":"call_00_d0sAHpJ9mYOJi0z7KNy30441","name":"bash","arguments":"{\"command\": \"printf 'escalated\\\\n' > /tmp/dsh-escalated.txt && cat /tmp/dsh-escalated.txt && rm /tmp/dsh-escalated.txt\", \"description\": \"Write file outside workspace and verify\", \"sandbox_permissions\": \"danger-full-access\", \"justification\": \"the user asked to write a file outside the workspace\"}"}}
-{"type":"approval/asked","seq":132,"time":1783962245386,"data":{"id":"d409f075-74f1-4637-9e13-6e80d7b6f6ff","toolName":"bash","callId":"call_00_d0sAHpJ9mYOJi0z7KNy30441","reason":"escalate sandbox to danger-full-access: the user asked to write a file outside the workspace"}}
-{"type":"approval/decided","seq":133,"time":1783962245387,"data":{"id":"d409f075-74f1-4637-9e13-6e80d7b6f6ff","outcome":"allowed-once"}}
+{"type":"approval/asked","seq":132,"time":1783962245386,"data":{"id":"b76bc320-c954-4f8a-b7d6-30821793dae8","toolName":"bash","callId":"call_00_d0sAHpJ9mYOJi0z7KNy30441","reason":"escalate sandbox to danger-full-access: the user asked to write a file outside the workspace"}}
+{"type":"approval/decided","seq":133,"time":1783962245387,"data":{"id":"b76bc320-c954-4f8a-b7d6-30821793dae8","outcome":"allowed-once"}}
{"type":"tool/result","seq":134,"time":1783962245399,"data":{"turn":1,"step":1,"callId":"call_00_d0sAHpJ9mYOJi0z7KNy30441","content":[{"type":"text","text":"escalated\n"}],"isError":false},"sourceEventSeqs":[131],"surfaceOp":"append"}
{"type":"step/end","seq":135,"time":1783962245400,"data":{"turn":1,"step":1}}
{"type":"step/start","seq":136,"time":1783962245400,"data":{"turn":1,"step":2}}
diff --git a/examples/acp-agent/tests/snapshots/escalation-rejected/session.jsonl b/examples/acp-agent/tests/snapshots/escalation-rejected/session.jsonl
index 55cad3689d..c0315ac54a 100644
--- a/examples/acp-agent/tests/snapshots/escalation-rejected/session.jsonl
+++ b/examples/acp-agent/tests/snapshots/escalation-rejected/session.jsonl
@@ -155,8 +155,8 @@
{"type":"assistant/chunk","seq":153,"time":1783962246274,"data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}}
{"type":"assistant/message","seq":154,"time":1783962246274,"data":{"turn":1,"step":1,"content":[{"type":"reasoning","text":"The user wants me to run a specific command with `sandbox_permissions` set to `danger-full-access` and a specific justification. They explicitly said NOT to run it without sandbox_permissions first. Let me do exactly that."},{"type":"tool-call","id":"call_00_WB1vnPomi8yr6MlcFKTj7912","name":"bash","arguments":"{\"command\": \"printf 'escalated\\\\n' > /tmp/dsh-escalated.txt && cat /tmp/dsh-escalated.txt && rm /tmp/dsh-escalated.txt\", \"description\": \"Write to /tmp and verify, then clean up\", \"sandbox_permissions\": \"danger-full-access\", \"justification\": \"the user asked to write a file outside the workspace\"}"}],"usage":{"inputTokens":1509,"outputTokens":198,"cacheReadTokens":0,"reasoningTokens":48}},"sourceEventSeqs":[7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,41,42,43,44,45,46,47,48,49,50,51,52,53,54,55,56,57,58,59,60,61,62,63,64,65,66,67,68,69,70,71,72,73,74,75,76,77,78,79,80,81,82,83,84,85,86,87,88,89,90,91,92,93,94,95,96,97,98,99,100,101,102,103,104,105,106,107,108,109,110,111,112,113,114,115,116,117,118,119,120,121,122,123,124,125,126,127,128,129,130,131,132,133,134,135,136,137,138,139,140,141,142,143,144,145,146,147,148,149,150,151,152,153],"surfaceOp":"append"}
{"type":"tool/call","seq":155,"time":1783962246274,"data":{"turn":1,"step":1,"callId":"call_00_WB1vnPomi8yr6MlcFKTj7912","name":"bash","arguments":"{\"command\": \"printf 'escalated\\\\n' > /tmp/dsh-escalated.txt && cat /tmp/dsh-escalated.txt && rm /tmp/dsh-escalated.txt\", \"description\": \"Write to /tmp and verify, then clean up\", \"sandbox_permissions\": \"danger-full-access\", \"justification\": \"the user asked to write a file outside the workspace\"}"}}
-{"type":"approval/asked","seq":156,"time":1783962246275,"data":{"id":"e592115c-e915-4010-9bf5-cc5e7bb6f8bc","toolName":"bash","callId":"call_00_WB1vnPomi8yr6MlcFKTj7912","reason":"escalate sandbox to danger-full-access: the user asked to write a file outside the workspace"}}
-{"type":"approval/decided","seq":157,"time":1783962246275,"data":{"id":"e592115c-e915-4010-9bf5-cc5e7bb6f8bc","outcome":"rejected"}}
+{"type":"approval/asked","seq":156,"time":1783962246275,"data":{"id":"66efb593-279a-472b-b647-c50d34045bc0","toolName":"bash","callId":"call_00_WB1vnPomi8yr6MlcFKTj7912","reason":"escalate sandbox to danger-full-access: the user asked to write a file outside the workspace"}}
+{"type":"approval/decided","seq":157,"time":1783962246275,"data":{"id":"66efb593-279a-472b-b647-c50d34045bc0","outcome":"rejected"}}
{"type":"tool/result","seq":158,"time":1783962246275,"data":{"turn":1,"step":1,"callId":"call_00_WB1vnPomi8yr6MlcFKTj7912","content":[{"type":"text","text":"Error: the user rejected escalating this command to \"danger-full-access\""}],"isError":true},"sourceEventSeqs":[155],"surfaceOp":"append"}
{"type":"step/end","seq":159,"time":1783962246276,"data":{"turn":1,"step":1}}
{"type":"step/start","seq":160,"time":1783962246276,"data":{"turn":1,"step":2}}
diff --git a/examples/acp-agent/tests/snapshots/hook-cc-pretool-ask/session.jsonl b/examples/acp-agent/tests/snapshots/hook-cc-pretool-ask/session.jsonl
index 3933a939ba..f67bf420ab 100644
--- a/examples/acp-agent/tests/snapshots/hook-cc-pretool-ask/session.jsonl
+++ b/examples/acp-agent/tests/snapshots/hook-cc-pretool-ask/session.jsonl
@@ -55,8 +55,8 @@
{"type":"tool/call","seq":53,"time":1783352172557,"data":{"turn":1,"step":1,"callId":"call_00_6k0oGSliVHxGSgqBmMEO4311","name":"bash","arguments":"{\"command\": \"echo HELLO\", \"description\": \"Echo HELLO\"}"}}
{"type":"hook/invoked","seq":54,"time":1783352172558,"data":{"turn":1,"point":"PreToolUse","dialect":"claude","handlerId":"claude:PreToolUse:1","matcher":"bash"}}
{"type":"hook/result","seq":55,"time":1783352172573,"data":{"turn":1,"point":"PreToolUse","handlerId":"claude:PreToolUse:1","decision":"ask","exitCode":0,"durationMs":14.113374999999905}}
-{"type":"approval/asked","seq":56,"time":1783962235813,"data":{"id":"cdd11a3a-c721-4d08-8255-732218775c33","toolName":"bash","callId":"call_00_6k0oGSliVHxGSgqBmMEO4311","reason":"bash requires manual approval in this session"}}
-{"type":"approval/decided","seq":57,"time":1783962235813,"data":{"id":"cdd11a3a-c721-4d08-8255-732218775c33","outcome":"rejected"}}
+{"type":"approval/asked","seq":56,"time":1783962235813,"data":{"id":"af257151-c371-4be2-a9ab-fbf4b6d18eb1","toolName":"bash","callId":"call_00_6k0oGSliVHxGSgqBmMEO4311","reason":"bash requires manual approval in this session"}}
+{"type":"approval/decided","seq":57,"time":1783962235813,"data":{"id":"af257151-c371-4be2-a9ab-fbf4b6d18eb1","outcome":"rejected"}}
{"type":"tool/result","seq":58,"time":1783962235814,"data":{"turn":1,"step":1,"callId":"call_00_6k0oGSliVHxGSgqBmMEO4311","content":[{"type":"text","text":"Error: the user rejected tool \"bash\""}],"isError":true},"sourceEventSeqs":[53],"surfaceOp":"append"}
{"type":"step/end","seq":59,"time":1783962235814,"data":{"turn":1,"step":1}}
{"type":"step/start","seq":60,"time":1783962235814,"data":{"turn":1,"step":2}}
diff --git a/examples/acp-agent/tests/snapshots/permission-switching/session.jsonl b/examples/acp-agent/tests/snapshots/permission-switching/session.jsonl
index eefadc2be4..71cd200931 100644
--- a/examples/acp-agent/tests/snapshots/permission-switching/session.jsonl
+++ b/examples/acp-agent/tests/snapshots/permission-switching/session.jsonl
@@ -107,7 +107,7 @@
{"type":"user/message","seq":105,"time":1783962244624,"data":{"content":[{"type":"text","text":"Use the bash tool to run exactly: cat out.txt. Then reply with the single word DONE and stop."}],"source":{"kind":"user"}},"surfaceOp":"append"}
{"type":"context/message","seq":106,"time":1783962244624,"data":{"content":[{"type":"text","text":"The approval policy changed from \"ask\" to \"never\" (changed by the user)."}],"source":{"kind":"plugin","plugin":"user-approval"}},"surfaceOp":"append"}
{"type":"step/start","seq":107,"time":1783962244624,"data":{"turn":2,"step":1}}
-{"type":"request/header-delta","seq":108,"time":1783962244624,"data":{"system":{"keepStart":9,"keepEnd":2,"insert":["{{system}}","{{system}}"]}}}
+{"type":"request/header-delta","seq":108,"time":1783962244624,"data":{"system":{"keepStart":11,"keepEnd":2,"insert":["{{system}}","{{system}}"]}}}
{"type":"assistant/chunk","seq":109,"time":1783860671025,"data":{"turn":2,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}}
{"type":"assistant/chunk","seq":110,"time":1783860671026,"data":{"turn":2,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"The"}}}
{"type":"assistant/chunk","seq":111,"time":1783860671026,"data":{"turn":2,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" user"}}}
diff --git a/examples/acp-agent/tests/snapshots/permission-switching/system-prompt.golden.md b/examples/acp-agent/tests/snapshots/permission-switching/system-prompt.golden.md
index 3da863d3b8..95f9bdb600 100644
--- a/examples/acp-agent/tests/snapshots/permission-switching/system-prompt.golden.md
+++ b/examples/acp-agent/tests/snapshots/permission-switching/system-prompt.golden.md
@@ -7,11 +7,13 @@ Verify your work by running the code or tests. Keep answers brief and factual.
Check the [exit code: N] marker on every bash result; investigate failures before moving on.
+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.
+
Use the workflow tool ONLY when the user explicitly asks for a workflow or for large multi-agent orchestration: you write a JavaScript script (the tool description documents the exact format) that fans work out across many subagents with phases and structured results. For one or two delegations, prefer plain subagent calls.
-
+
Approval prompts are disabled in this session: actions that require approval are rejected automatically — do not request sandbox escalation (do not set `sandbox_permissions`).
diff --git a/examples/acp-agent/tests/snapshots/permission-switching/tool-schemas.golden.json b/examples/acp-agent/tests/snapshots/permission-switching/tool-schemas.golden.json
index 68d4b037d7..4b07d8edef 100644
--- a/examples/acp-agent/tests/snapshots/permission-switching/tool-schemas.golden.json
+++ b/examples/acp-agent/tests/snapshots/permission-switching/tool-schemas.golden.json
@@ -2,7 +2,7 @@
"initial": [
{
"name": "bash",
- "description": "Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Commands may run under a file sandbox; a blocked file operation is reported as `[sandbox: file access denied under mode]` — a policy denial, not a bug in the command; do not retry another way (a background task reports the same marker via bash_output once it has finished). Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`. Attempting a command the sandbox may deny is safe and expected: run it and read the marker rather than assuming the denial. When a command is denied and a wider mode would let it succeed, escalate immediately in the same turn — the one sanctioned exception to a denial: retry the exact same command once with `sandbox_permissions` (the narrowest wider mode that suffices) plus a one-sentence `justification`. Do not detour through chat to ask permission first — the approval prompt raised by that retry is how the user consents. If the session states approval prompts are disabled, there is no exception: a denial is final — do not set `sandbox_permissions`. Never escalate speculatively: ground the request in a real denial — normally the one this command just hit; escalating up front is fine only when this session already denied the same access. A rejected escalation is final for that command — stop and explain, never work around it — but it does not forbid attempting or escalating other commands later.",
+ "description": "Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Commands may run under a file sandbox; a blocked file operation is reported as `[sandbox: file access denied under mode]` — a policy denial, not a bug in the command; do not retry another way. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; read its output with `task_output` and stop it with `task_kill`. Attempting a command the sandbox may deny is safe and expected: run it and read the marker rather than assuming the denial. When a command is denied and a wider mode would let it succeed, escalate immediately in the same turn — the one sanctioned exception to a denial: retry the exact same command once with `sandbox_permissions` (the narrowest wider mode that suffices) plus a one-sentence `justification`. Do not detour through chat to ask permission first — the approval prompt raised by that retry is how the user consents. If the session states approval prompts are disabled, there is no exception: a denial is final — do not set `sandbox_permissions`. Never escalate speculatively: ground the request in a real denial — normally the one this command just hit; escalating up front is fine only when this session already denied the same access. A rejected escalation is final for that command — stop and explain, never work around it — but it does not forbid attempting or escalating other commands later.",
"parameters": {
"type": "object",
"properties": {
@@ -24,7 +24,7 @@
},
"run_in_background": {
"type": "boolean",
- "description": "Run in the background and return a task id immediately. No timeout applies."
+ "description": "Run in the background and return a task id immediately (collect with task_output, stop with task_kill). No timeout applies."
},
"sandbox_permissions": {
"type": "string",
@@ -45,38 +45,6 @@
]
}
},
- {
- "name": "bash_kill",
- "description": "Ask the executor to kill a running background bash task by task id.",
- "parameters": {
- "type": "object",
- "properties": {
- "task_id": {
- "type": "string",
- "description": "Task id returned by the bash tool."
- }
- },
- "required": [
- "task_id"
- ]
- }
- },
- {
- "name": "bash_output",
- "description": "Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.",
- "parameters": {
- "type": "object",
- "properties": {
- "task_id": {
- "type": "string",
- "description": "Task id returned by the bash tool."
- }
- },
- "required": [
- "task_id"
- ]
- }
- },
{
"name": "skill",
"description": "Load the full instructions for an available skill. Call this with the exact skill name from the session skill catalog before acting on a task that names or clearly matches that skill.",
@@ -95,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.",
+ "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": {
@@ -106,6 +74,10 @@
"prompt": {
"type": "string",
"description": "The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."
+ },
+ "run_in_background": {
+ "type": "boolean",
+ "description": "Run as a background task and return its id; collect with task_output or stop with task_kill."
}
},
"required": [
@@ -116,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.",
+ "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": {
@@ -127,6 +99,10 @@
"prompt": {
"type": "string",
"description": "The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."
+ },
+ "run_in_background": {
+ "type": "boolean",
+ "description": "Run as a background task and return its id; collect with task_output or stop with task_kill."
}
},
"required": [
@@ -135,6 +111,58 @@
]
}
},
+ {
+ "name": "task_kill",
+ "description": "Request cancellation of a running background task by task id. Returns immediately; the task settles as killed once its work actually stops.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "task_id": {
+ "type": "string",
+ "description": "Task id returned by the tool that started the background work."
+ },
+ "reason": {
+ "type": "string",
+ "description": "Optional short reason, recorded in the log and forwarded to the task."
+ }
+ },
+ "required": [
+ "task_id"
+ ]
+ }
+ },
+ {
+ "name": "task_list",
+ "description": "List your background tasks (running and finished) with their ids, kinds, and statuses.",
+ "parameters": {
+ "type": "object",
+ "properties": {}
+ }
+ },
+ {
+ "name": "task_output",
+ "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": {
+ "task_id": {
+ "type": "string",
+ "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."
+ },
+ "timeout_ms": {
+ "type": "number",
+ "description": "Max wait in milliseconds (only meaningful with wait: true). Defaults to the configured wait timeout; capped by the configured maximum."
+ }
+ },
+ "required": [
+ "task_id"
+ ]
+ }
+ },
{
"name": "todo_write",
"description": "Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).",
diff --git a/examples/acp-agent/tests/snapshots/skill-load/system-prompt.golden.md b/examples/acp-agent/tests/snapshots/skill-load/system-prompt.golden.md
index d0ce1272d0..43ecb9746f 100644
--- a/examples/acp-agent/tests/snapshots/skill-load/system-prompt.golden.md
+++ b/examples/acp-agent/tests/snapshots/skill-load/system-prompt.golden.md
@@ -7,6 +7,8 @@ Verify your work by running the code or tests. Keep answers brief and factual.
Check the [exit code: N] marker on every bash result; investigate failures before moving on.
+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.
+
Approval prompts are disabled in this session: actions that require approval are rejected automatically — do not request sandbox escalation (do not set `sandbox_permissions`).
diff --git a/examples/acp-agent/tests/snapshots/skill-load/tool-schemas.golden.json b/examples/acp-agent/tests/snapshots/skill-load/tool-schemas.golden.json
index 68d4b037d7..4b07d8edef 100644
--- a/examples/acp-agent/tests/snapshots/skill-load/tool-schemas.golden.json
+++ b/examples/acp-agent/tests/snapshots/skill-load/tool-schemas.golden.json
@@ -2,7 +2,7 @@
"initial": [
{
"name": "bash",
- "description": "Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Commands may run under a file sandbox; a blocked file operation is reported as `[sandbox: file access denied under mode]` — a policy denial, not a bug in the command; do not retry another way (a background task reports the same marker via bash_output once it has finished). Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`. Attempting a command the sandbox may deny is safe and expected: run it and read the marker rather than assuming the denial. When a command is denied and a wider mode would let it succeed, escalate immediately in the same turn — the one sanctioned exception to a denial: retry the exact same command once with `sandbox_permissions` (the narrowest wider mode that suffices) plus a one-sentence `justification`. Do not detour through chat to ask permission first — the approval prompt raised by that retry is how the user consents. If the session states approval prompts are disabled, there is no exception: a denial is final — do not set `sandbox_permissions`. Never escalate speculatively: ground the request in a real denial — normally the one this command just hit; escalating up front is fine only when this session already denied the same access. A rejected escalation is final for that command — stop and explain, never work around it — but it does not forbid attempting or escalating other commands later.",
+ "description": "Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Commands may run under a file sandbox; a blocked file operation is reported as `[sandbox: file access denied under mode]` — a policy denial, not a bug in the command; do not retry another way. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; read its output with `task_output` and stop it with `task_kill`. Attempting a command the sandbox may deny is safe and expected: run it and read the marker rather than assuming the denial. When a command is denied and a wider mode would let it succeed, escalate immediately in the same turn — the one sanctioned exception to a denial: retry the exact same command once with `sandbox_permissions` (the narrowest wider mode that suffices) plus a one-sentence `justification`. Do not detour through chat to ask permission first — the approval prompt raised by that retry is how the user consents. If the session states approval prompts are disabled, there is no exception: a denial is final — do not set `sandbox_permissions`. Never escalate speculatively: ground the request in a real denial — normally the one this command just hit; escalating up front is fine only when this session already denied the same access. A rejected escalation is final for that command — stop and explain, never work around it — but it does not forbid attempting or escalating other commands later.",
"parameters": {
"type": "object",
"properties": {
@@ -24,7 +24,7 @@
},
"run_in_background": {
"type": "boolean",
- "description": "Run in the background and return a task id immediately. No timeout applies."
+ "description": "Run in the background and return a task id immediately (collect with task_output, stop with task_kill). No timeout applies."
},
"sandbox_permissions": {
"type": "string",
@@ -45,38 +45,6 @@
]
}
},
- {
- "name": "bash_kill",
- "description": "Ask the executor to kill a running background bash task by task id.",
- "parameters": {
- "type": "object",
- "properties": {
- "task_id": {
- "type": "string",
- "description": "Task id returned by the bash tool."
- }
- },
- "required": [
- "task_id"
- ]
- }
- },
- {
- "name": "bash_output",
- "description": "Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.",
- "parameters": {
- "type": "object",
- "properties": {
- "task_id": {
- "type": "string",
- "description": "Task id returned by the bash tool."
- }
- },
- "required": [
- "task_id"
- ]
- }
- },
{
"name": "skill",
"description": "Load the full instructions for an available skill. Call this with the exact skill name from the session skill catalog before acting on a task that names or clearly matches that skill.",
@@ -95,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.",
+ "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": {
@@ -106,6 +74,10 @@
"prompt": {
"type": "string",
"description": "The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."
+ },
+ "run_in_background": {
+ "type": "boolean",
+ "description": "Run as a background task and return its id; collect with task_output or stop with task_kill."
}
},
"required": [
@@ -116,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.",
+ "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": {
@@ -127,6 +99,10 @@
"prompt": {
"type": "string",
"description": "The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."
+ },
+ "run_in_background": {
+ "type": "boolean",
+ "description": "Run as a background task and return its id; collect with task_output or stop with task_kill."
}
},
"required": [
@@ -135,6 +111,58 @@
]
}
},
+ {
+ "name": "task_kill",
+ "description": "Request cancellation of a running background task by task id. Returns immediately; the task settles as killed once its work actually stops.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "task_id": {
+ "type": "string",
+ "description": "Task id returned by the tool that started the background work."
+ },
+ "reason": {
+ "type": "string",
+ "description": "Optional short reason, recorded in the log and forwarded to the task."
+ }
+ },
+ "required": [
+ "task_id"
+ ]
+ }
+ },
+ {
+ "name": "task_list",
+ "description": "List your background tasks (running and finished) with their ids, kinds, and statuses.",
+ "parameters": {
+ "type": "object",
+ "properties": {}
+ }
+ },
+ {
+ "name": "task_output",
+ "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": {
+ "task_id": {
+ "type": "string",
+ "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."
+ },
+ "timeout_ms": {
+ "type": "number",
+ "description": "Max wait in milliseconds (only meaningful with wait: true). Defaults to the configured wait timeout; capped by the configured maximum."
+ }
+ },
+ "required": [
+ "task_id"
+ ]
+ }
+ },
{
"name": "todo_write",
"description": "Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).",
diff --git a/examples/acp-agent/tests/snapshots/text-turn/system-prompt.golden.md b/examples/acp-agent/tests/snapshots/text-turn/system-prompt.golden.md
index d0ce1272d0..43ecb9746f 100644
--- a/examples/acp-agent/tests/snapshots/text-turn/system-prompt.golden.md
+++ b/examples/acp-agent/tests/snapshots/text-turn/system-prompt.golden.md
@@ -7,6 +7,8 @@ Verify your work by running the code or tests. Keep answers brief and factual.
Check the [exit code: N] marker on every bash result; investigate failures before moving on.
+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.
+
Approval prompts are disabled in this session: actions that require approval are rejected automatically — do not request sandbox escalation (do not set `sandbox_permissions`).
diff --git a/examples/acp-agent/tests/snapshots/text-turn/tool-schemas.golden.json b/examples/acp-agent/tests/snapshots/text-turn/tool-schemas.golden.json
index 68d4b037d7..4b07d8edef 100644
--- a/examples/acp-agent/tests/snapshots/text-turn/tool-schemas.golden.json
+++ b/examples/acp-agent/tests/snapshots/text-turn/tool-schemas.golden.json
@@ -2,7 +2,7 @@
"initial": [
{
"name": "bash",
- "description": "Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Commands may run under a file sandbox; a blocked file operation is reported as `[sandbox: file access denied under mode]` — a policy denial, not a bug in the command; do not retry another way (a background task reports the same marker via bash_output once it has finished). Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`. Attempting a command the sandbox may deny is safe and expected: run it and read the marker rather than assuming the denial. When a command is denied and a wider mode would let it succeed, escalate immediately in the same turn — the one sanctioned exception to a denial: retry the exact same command once with `sandbox_permissions` (the narrowest wider mode that suffices) plus a one-sentence `justification`. Do not detour through chat to ask permission first — the approval prompt raised by that retry is how the user consents. If the session states approval prompts are disabled, there is no exception: a denial is final — do not set `sandbox_permissions`. Never escalate speculatively: ground the request in a real denial — normally the one this command just hit; escalating up front is fine only when this session already denied the same access. A rejected escalation is final for that command — stop and explain, never work around it — but it does not forbid attempting or escalating other commands later.",
+ "description": "Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Commands may run under a file sandbox; a blocked file operation is reported as `[sandbox: file access denied under mode]` — a policy denial, not a bug in the command; do not retry another way. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; read its output with `task_output` and stop it with `task_kill`. Attempting a command the sandbox may deny is safe and expected: run it and read the marker rather than assuming the denial. When a command is denied and a wider mode would let it succeed, escalate immediately in the same turn — the one sanctioned exception to a denial: retry the exact same command once with `sandbox_permissions` (the narrowest wider mode that suffices) plus a one-sentence `justification`. Do not detour through chat to ask permission first — the approval prompt raised by that retry is how the user consents. If the session states approval prompts are disabled, there is no exception: a denial is final — do not set `sandbox_permissions`. Never escalate speculatively: ground the request in a real denial — normally the one this command just hit; escalating up front is fine only when this session already denied the same access. A rejected escalation is final for that command — stop and explain, never work around it — but it does not forbid attempting or escalating other commands later.",
"parameters": {
"type": "object",
"properties": {
@@ -24,7 +24,7 @@
},
"run_in_background": {
"type": "boolean",
- "description": "Run in the background and return a task id immediately. No timeout applies."
+ "description": "Run in the background and return a task id immediately (collect with task_output, stop with task_kill). No timeout applies."
},
"sandbox_permissions": {
"type": "string",
@@ -45,38 +45,6 @@
]
}
},
- {
- "name": "bash_kill",
- "description": "Ask the executor to kill a running background bash task by task id.",
- "parameters": {
- "type": "object",
- "properties": {
- "task_id": {
- "type": "string",
- "description": "Task id returned by the bash tool."
- }
- },
- "required": [
- "task_id"
- ]
- }
- },
- {
- "name": "bash_output",
- "description": "Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.",
- "parameters": {
- "type": "object",
- "properties": {
- "task_id": {
- "type": "string",
- "description": "Task id returned by the bash tool."
- }
- },
- "required": [
- "task_id"
- ]
- }
- },
{
"name": "skill",
"description": "Load the full instructions for an available skill. Call this with the exact skill name from the session skill catalog before acting on a task that names or clearly matches that skill.",
@@ -95,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.",
+ "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": {
@@ -106,6 +74,10 @@
"prompt": {
"type": "string",
"description": "The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."
+ },
+ "run_in_background": {
+ "type": "boolean",
+ "description": "Run as a background task and return its id; collect with task_output or stop with task_kill."
}
},
"required": [
@@ -116,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.",
+ "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": {
@@ -127,6 +99,10 @@
"prompt": {
"type": "string",
"description": "The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."
+ },
+ "run_in_background": {
+ "type": "boolean",
+ "description": "Run as a background task and return its id; collect with task_output or stop with task_kill."
}
},
"required": [
@@ -135,6 +111,58 @@
]
}
},
+ {
+ "name": "task_kill",
+ "description": "Request cancellation of a running background task by task id. Returns immediately; the task settles as killed once its work actually stops.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "task_id": {
+ "type": "string",
+ "description": "Task id returned by the tool that started the background work."
+ },
+ "reason": {
+ "type": "string",
+ "description": "Optional short reason, recorded in the log and forwarded to the task."
+ }
+ },
+ "required": [
+ "task_id"
+ ]
+ }
+ },
+ {
+ "name": "task_list",
+ "description": "List your background tasks (running and finished) with their ids, kinds, and statuses.",
+ "parameters": {
+ "type": "object",
+ "properties": {}
+ }
+ },
+ {
+ "name": "task_output",
+ "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": {
+ "task_id": {
+ "type": "string",
+ "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."
+ },
+ "timeout_ms": {
+ "type": "number",
+ "description": "Max wait in milliseconds (only meaningful with wait: true). Defaults to the configured wait timeout; capped by the configured maximum."
+ }
+ },
+ "required": [
+ "task_id"
+ ]
+ }
+ },
{
"name": "todo_write",
"description": "Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).",
diff --git a/examples/acp-agent/tests/snapshots/workspace-edit/system-prompt.golden.md b/examples/acp-agent/tests/snapshots/workspace-edit/system-prompt.golden.md
index 6bb634b339..ddf502a773 100644
--- a/examples/acp-agent/tests/snapshots/workspace-edit/system-prompt.golden.md
+++ b/examples/acp-agent/tests/snapshots/workspace-edit/system-prompt.golden.md
@@ -13,6 +13,8 @@ Use the edit tool for targeted changes to existing UTF-8 text files. It replaces
Check the [exit code: N] marker on every bash result; investigate failures before moving on.
+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.
+
Approval prompts are disabled in this session: actions that require approval are rejected automatically — do not request sandbox escalation (do not set `sandbox_permissions`).
diff --git a/examples/acp-agent/tests/snapshots/workspace-edit/tool-schemas.golden.json b/examples/acp-agent/tests/snapshots/workspace-edit/tool-schemas.golden.json
index 18e285888b..da5e23216c 100644
--- a/examples/acp-agent/tests/snapshots/workspace-edit/tool-schemas.golden.json
+++ b/examples/acp-agent/tests/snapshots/workspace-edit/tool-schemas.golden.json
@@ -2,7 +2,7 @@
"initial": [
{
"name": "bash",
- "description": "Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Commands may run under a file sandbox; a blocked file operation is reported as `[sandbox: file access denied under mode]` — a policy denial, not a bug in the command; do not retry another way (a background task reports the same marker via bash_output once it has finished). Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`. Attempting a command the sandbox may deny is safe and expected: run it and read the marker rather than assuming the denial. When a command is denied and a wider mode would let it succeed, escalate immediately in the same turn — the one sanctioned exception to a denial: retry the exact same command once with `sandbox_permissions` (the narrowest wider mode that suffices) plus a one-sentence `justification`. Do not detour through chat to ask permission first — the approval prompt raised by that retry is how the user consents. If the session states approval prompts are disabled, there is no exception: a denial is final — do not set `sandbox_permissions`. Never escalate speculatively: ground the request in a real denial — normally the one this command just hit; escalating up front is fine only when this session already denied the same access. A rejected escalation is final for that command — stop and explain, never work around it — but it does not forbid attempting or escalating other commands later.",
+ "description": "Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Commands may run under a file sandbox; a blocked file operation is reported as `[sandbox: file access denied under mode]` — a policy denial, not a bug in the command; do not retry another way. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; read its output with `task_output` and stop it with `task_kill`. Attempting a command the sandbox may deny is safe and expected: run it and read the marker rather than assuming the denial. When a command is denied and a wider mode would let it succeed, escalate immediately in the same turn — the one sanctioned exception to a denial: retry the exact same command once with `sandbox_permissions` (the narrowest wider mode that suffices) plus a one-sentence `justification`. Do not detour through chat to ask permission first — the approval prompt raised by that retry is how the user consents. If the session states approval prompts are disabled, there is no exception: a denial is final — do not set `sandbox_permissions`. Never escalate speculatively: ground the request in a real denial — normally the one this command just hit; escalating up front is fine only when this session already denied the same access. A rejected escalation is final for that command — stop and explain, never work around it — but it does not forbid attempting or escalating other commands later.",
"parameters": {
"type": "object",
"properties": {
@@ -24,7 +24,7 @@
},
"run_in_background": {
"type": "boolean",
- "description": "Run in the background and return a task id immediately. No timeout applies."
+ "description": "Run in the background and return a task id immediately (collect with task_output, stop with task_kill). No timeout applies."
},
"sandbox_permissions": {
"type": "string",
@@ -45,38 +45,6 @@
]
}
},
- {
- "name": "bash_kill",
- "description": "Ask the executor to kill a running background bash task by task id.",
- "parameters": {
- "type": "object",
- "properties": {
- "task_id": {
- "type": "string",
- "description": "Task id returned by the bash tool."
- }
- },
- "required": [
- "task_id"
- ]
- }
- },
- {
- "name": "bash_output",
- "description": "Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.",
- "parameters": {
- "type": "object",
- "properties": {
- "task_id": {
- "type": "string",
- "description": "Task id returned by the bash tool."
- }
- },
- "required": [
- "task_id"
- ]
- }
- },
{
"name": "edit",
"description": "Edit an existing UTF-8 text file by replacing literal text.",
@@ -149,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.",
+ "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": {
@@ -160,6 +128,10 @@
"prompt": {
"type": "string",
"description": "The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."
+ },
+ "run_in_background": {
+ "type": "boolean",
+ "description": "Run as a background task and return its id; collect with task_output or stop with task_kill."
}
},
"required": [
@@ -170,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.",
+ "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": {
@@ -181,6 +153,10 @@
"prompt": {
"type": "string",
"description": "The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."
+ },
+ "run_in_background": {
+ "type": "boolean",
+ "description": "Run as a background task and return its id; collect with task_output or stop with task_kill."
}
},
"required": [
@@ -189,6 +165,58 @@
]
}
},
+ {
+ "name": "task_kill",
+ "description": "Request cancellation of a running background task by task id. Returns immediately; the task settles as killed once its work actually stops.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "task_id": {
+ "type": "string",
+ "description": "Task id returned by the tool that started the background work."
+ },
+ "reason": {
+ "type": "string",
+ "description": "Optional short reason, recorded in the log and forwarded to the task."
+ }
+ },
+ "required": [
+ "task_id"
+ ]
+ }
+ },
+ {
+ "name": "task_list",
+ "description": "List your background tasks (running and finished) with their ids, kinds, and statuses.",
+ "parameters": {
+ "type": "object",
+ "properties": {}
+ }
+ },
+ {
+ "name": "task_output",
+ "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": {
+ "task_id": {
+ "type": "string",
+ "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."
+ },
+ "timeout_ms": {
+ "type": "number",
+ "description": "Max wait in milliseconds (only meaningful with wait: true). Defaults to the configured wait timeout; capped by the configured maximum."
+ }
+ },
+ "required": [
+ "task_id"
+ ]
+ }
+ },
{
"name": "todo_write",
"description": "Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).",
diff --git a/examples/coding-agent/README.md b/examples/coding-agent/README.md
index 380ab8134f..9e627324d4 100644
--- a/examples/coding-agent/README.md
+++ b/examples/coding-agent/README.md
@@ -11,7 +11,7 @@ The REPL agent demo wiring: DeepSeek V4 + the `read`/`write`/`edit` filesystem t
pnpm run demo:repl
```
-Type a coding task. The agent works through the `read`/`write`/`edit` filesystem tools for ordinary file operations and `bash` (+ `bash_output` / `bash_kill` for background tasks) for shell commands, searches, and test runs, each in a fresh `bash -c` (the system prompt tells the model to pass `workdir` instead of `cd`). Both the fs tools and bash resolve relative paths against the session workspace. It can also delegate with `subagent`/`subagent_fork` and track multi-step work with `todo_write` (a whole-list task tracker rendered as a checklist). Reasoning streams dimmed; tool calls/results render inline.
+Type a coding task. The agent works through the `read`/`write`/`edit` filesystem tools for ordinary file operations and `bash` (+ the generic `task_output` / `task_list` / `task_kill` for background tasks) for shell commands, searches, and test runs, each in a fresh `bash -c` (the system prompt tells the model to pass `workdir` instead of `cd`). Both the fs tools and bash resolve relative paths against the session workspace. It can also delegate with `subagent`/`subagent_fork` and track multi-step work with `todo_write` (a whole-list task tracker rendered as a checklist). Reasoning streams dimmed; tool calls/results render inline.
```
> fix the failing test in /path/to/project
@@ -54,8 +54,8 @@ This example is a thin leaf `cordis.yml`: it picks the swappable backends, loads
|---|---|
| `hmr` (`@cordisjs/plugin-hmr`) | the dev/demo edit-reload loop — a **leaf** entry (not baked into the app) because it is Loader-only and needs `node --expose-internals`, which `demo:repl` passes |
| `llm-deepseek` | real `LlmAdapter` via config (`!!js process.env.…` secrets); swap one line to `@deepseek-ai/dsh-llm-pi-ai` for the library-backed twin |
-| `bash` (`dsh-bash-local`) | the executor implementation — the swappable half of the bash seam. The model-facing `bash`/`bash_output`/`bash_kill` tool schemas (`tool-bash`) come from `agent-core`, so only the executor is a leaf choice |
-| `stdio-agent` (`@deepseek-ai/dsh-stdio-demo`) | the app bundle: the agent-core spine + console logger + JSONL persistence + readline UI + a pre-created `main` agent. Its config carries the model, system prompt, `persistenceRoot` (`./.sessions`), and `resumeSessionId` — so persistence and the agent are configured here, not wired as separate leaf plugins |
+| `bash` (`dsh-bash-local`) | the executor implementation — the swappable half of the bash seam. The model-facing `bash` schema (`tool-bash`) and generic `task_*` controls (`tool-tasks`) come from `dsh-agent-spine-demo`, so only the executor is a leaf choice |
+| `stdio-agent` (`@deepseek-ai/dsh-stdio-demo`) | the app bundle: the agent-spine demo + console logger + JSONL persistence + readline UI + a pre-created `main` agent. Its config carries the model, system prompt, `persistenceRoot` (`./.sessions`), and `resumeSessionId` — so persistence and the agent are configured here, not wired as separate leaf plugins |
| `subagent`, `subagent-spawn`, `subagent-fork` | the subagent provider registry plus the two in-process backends: a fresh child and a child seeded with the parent's completed-turn prefix |
| `tool-subagent`, `tool-subagent-fork` | two model-facing `dsh-tool-subagent` loads, each bound to a different provider and exposed under a distinct tool name (`subagent`, `subagent_fork`) |
| `tool-todo` | the model-facing `todo_write` tool; writes the whole task list to the session log and renders as a checklist in stdio |
diff --git a/examples/coding-agent/cordis.yml b/examples/coding-agent/cordis.yml
index 9400528c2b..7b40a64789 100644
--- a/examples/coding-agent/cordis.yml
+++ b/examples/coding-agent/cordis.yml
@@ -1,5 +1,6 @@
# REPL agent with swappable DeepSeek and local-bash backends. `dsh-stdio-demo`
-# supplies the agent-core spine, logging, JSONL persistence, readline UI, and `main` agent.
+# supplies the agent spine, generic task controls, logging, JSONL persistence,
+# readline UI, and `main` agent.
# HMR remains a leaf because it requires Loader internals; `demo:repl` passes
# `--expose-internals`. The app bin loads the gitignored root `.env`; this file
# reads `DEEPSEEK_API_KEY` and optional `DEEPSEEK_BASE_URL` through `!!js`.
diff --git a/knip.json b/knip.json
index 71c9d1e01d..b978da3a76 100644
--- a/knip.json
+++ b/knip.json
@@ -97,6 +97,15 @@
"packages/examples/jsonrpc-demo": {
"project": ["src/**/*.ts"]
},
+ "packages/sdk/create-sdk": {
+ "entry": ["src/bin.ts", "tests/**/*.spec.ts", "tests/**/*.e2e.ts", "tests/**/*.snapshot.ts"],
+ "project": ["src/**/*.ts", "tests/**/*.ts"]
+ },
+ "packages/sdk/scripts": {
+ "entry": ["src/bin.ts", "tests/**/*.spec.ts", "tests/**/*.snapshot.ts"],
+ "project": ["src/**/*.ts", "tests/**/*.ts"],
+ "ignoreDependencies": ["node-addon-require-builtin"]
+ },
"packages/subagent/subagent-spawn": {
"entry": ["tests/**/*.spec.ts", "tests/**/*.e2e.ts"],
"project": ["src/**/*.ts", "tests/**/*.ts"]
diff --git a/package.json b/package.json
index 081c2eb51e..aaec1e62c4 100644
--- a/package.json
+++ b/package.json
@@ -44,6 +44,7 @@
"verify-rfc-classification": "tsx scripts/verify-rfc-classification.ts",
"verify-rfc-format": "tsx scripts/verify-rfc-format.ts",
"verify-type-equiv": "tsx scripts/verify-type-equiv.ts",
+ "verify-translation-prompt": "tsx scripts/verify-translation-prompt.ts",
"verify-translation-pairing": "tsx scripts/verify-translation-pairing.ts",
"verify-doc-budgets": "tsx scripts/verify-doc-budgets.ts",
"verify-package-readme-limitations": "tsx scripts/verify-package-readme-limitations.ts",
@@ -69,7 +70,7 @@
"verify-scoped-events": "tsx scripts/gen-scoped-events.ts --check",
"verify-module-graph": "tsx scripts/gen-module-graph.ts --check",
"constraints": "tsx scripts/check-workspace-constraints.ts",
- "doc-sync": "pnpm run doc-typecheck && pnpm run verify-cordis-catalog && pnpm run verify-cordis-api && pnpm run verify-export-jsdoc && pnpm run verify-tool-catalog && pnpm run verify-config-catalog && pnpm run verify-persistence-catalog && pnpm run verify-doc-graphs && pnpm run verify-scoped-events && pnpm run verify-md-wrap && pnpm run verify-md-links && pnpm run verify-doc-refs && pnpm run verify-package-paths && pnpm run verify-package-readme-model-experience && pnpm run verify-mermaid && pnpm run verify-rfc-classification && pnpm run verify-rfc-format && pnpm run verify-type-equiv && pnpm run verify-translation-pairing && pnpm run verify-doc-budgets && pnpm run verify-package-readme-limitations",
+ "doc-sync": "pnpm run doc-typecheck && pnpm run verify-cordis-catalog && pnpm run verify-cordis-api && pnpm run verify-export-jsdoc && pnpm run verify-tool-catalog && pnpm run verify-config-catalog && pnpm run verify-persistence-catalog && pnpm run verify-doc-graphs && pnpm run verify-scoped-events && pnpm run verify-md-wrap && pnpm run verify-md-links && pnpm run verify-doc-refs && pnpm run verify-package-paths && pnpm run verify-package-readme-model-experience && pnpm run verify-mermaid && pnpm run verify-rfc-classification && pnpm run verify-rfc-format && pnpm run verify-type-equiv && pnpm run verify-translation-prompt && pnpm run verify-translation-pairing && pnpm run verify-doc-budgets && pnpm run verify-package-readme-limitations",
"hygiene": "pnpm run knip && pnpm run publint && pnpm run constraints && pnpm run verify-cordis-config && pnpm run verify-node-next-types && pnpm run verify-runtime-closure",
"demo:echo": "node --expose-internals --import tsx packages/examples/stdio-demo/src/bin.ts examples/echo-agent/cordis.yml",
"demo:repl": "node --expose-internals --import tsx packages/examples/stdio-demo/src/bin.ts examples/coding-agent/cordis.yml",
@@ -99,6 +100,7 @@
"mermaid": "11.16.0",
"micromark-extension-gfm": "^3.0.0",
"publint": "^0.3.21",
+ "saxes": "^6.0.0",
"tsdown": "^0.22.2",
"tsx": "^4.22.4",
"typescript": "^6.0.3",
diff --git a/packages/README.md b/packages/README.md
index db364421b1..8f1bf3dde2 100644
--- a/packages/README.md
+++ b/packages/README.md
@@ -4,7 +4,7 @@ Packages use the `@deepseek-ai/dsh-*` scope. Each is a Cordis `Service` subclass
## Hierarchy
-Packages are grouped by modular role at `packages///`. The group directory is a pure container (no `package.json`); the package name stays `@deepseek-ai/dsh-` regardless of group. **Each group README is the canonical per-package map** — package roles, ctx keys, and the product-vs-support split live there, next to the code.
+Packages live at `packages///`; groups are containers, while names remain `@deepseek-ai/dsh-`. **Each group README is the canonical package/ctx-key map.**
| Group | Role | Release expectation |
|---|---|---|
@@ -18,6 +18,7 @@ Packages are grouped by modular role at `packages///`. The group dir
| [`compact/`](compact/README.md) | Compaction capability family: the abstract seam + a basic backend (tool deferred) | Product — stable surface |
| [`context/`](context/README.md) | Opt-in request-context enrichment | Product — stable surface |
| [`subagent/`](subagent/README.md) | Subagent capability family: the provider-registry seam and the model-facing delegation tool | Product — stable surface |
+| [`tasks/`](tasks/README.md) | Generic background-task runtime and model-facing `task_*` control tools | Product — stable surface |
| [`workflow/`](workflow/README.md) | Workflow capability family: the script-engine seam, the worker-thread engine, and the model-facing `workflow` tool | Product — stable surface |
| [`web/`](web/README.md) | Web capability family: the abstract seam, search/fetch provider impls, and the model-facing web tools | Product — stable surface |
| [`timeout/`](timeout/README.md) | Tool-call timeout policy: the `tools/execute` deadline enforcer | Product — stable surface |
@@ -27,12 +28,13 @@ Packages are grouped by modular role at `packages///`. The group dir
| [`hooks/`](hooks/README.md) | Hook bridges + the shared Claude Code / Codex wire-protocol library | Product — stable surface |
| [`session-persistence/`](session-persistence/README.md) | Persistence capability family: the seam + JSONL/SQLite backends | Product — stable surface |
| [`session-query/`](session-query/README.md) | Session retrieval family: logical corpus, surface records, and bounded exact reads | Product — stable surface |
+| [`sdk/`](sdk/README.md) | Project SDK tooling | Product — stable surface |
| [`ui/`](ui/README.md) | Editor/client integration surfaces: ACP bridge, JSON-RPC SDK server, user-approval/user-interaction seams, ask-user tool | Product — stable surface |
| [`examples/`](examples/README.md) | Demo bundles (agent-spine + stdio/ACP/JSON-RPC bins) the leaves load | Support — example infra |
| [`support/`](support/README.md) | Support infrastructure (invariants, replay, Loader smokes) | Support — lower compatibility expectations |
| [`util/`](util/README.md) | Low-level zero-dependency utilities shared across groups (the `Branded` primitive) | Support — small, stable, harness-dep-free |
-The split is the point: a package's group says whether it is part of the product API or support/test/example infrastructure, so release and removal decisions do not treat every package as an equal public contract. New packages join an existing group; adding a new top-level group is a deliberate act (extend the group READMEs and this table).
+Groups distinguish product API from support infrastructure. New packages join an existing group; a new group updates its README and this table.
## Dependencies
diff --git a/packages/bash/README.md b/packages/bash/README.md
index c850ce2c15..20c11c5dff 100644
--- a/packages/bash/README.md
+++ b/packages/bash/README.md
@@ -7,6 +7,6 @@ The canonical three-package capability seam (see [capability seams](../../docs/r
| `bash/` | Abstract bash executor seam (interface + vocabulary; sandbox result facts carry the [`sandbox/`](../sandbox/README.md) seam's mode/enforcement vocabulary) | `ctx.bash` |
| `bash-local/` | Local-subprocess `BashExecutor` implementation | (registers `ctx.bash`) |
| `bash-sandbox/` | Sandbox-consuming `BashExecutor` (wraps every command argv via `ctx.sandbox`, stamps denial/enforcement facts; extends `bash-local`'s mechanics) | (registers `ctx.bash`) |
-| `tool-bash/` | Model-facing `bash`/`bash_output`/`bash_kill` tool schemas | (registers on `ctx.tools`) |
+| `tool-bash/` | Model-facing `bash` schema; background processes register with the generic [`tasks/`](../tasks/README.md) runtime | (registers on `ctx.tools`) |
The interface lives at `bash/bash/`. `bash-sandbox` replacing `bash-local` without touching the interface or the tool is the split doing exactly what it exists for — a leaf `cordis.yml` picks one executor entry, plus a `ctx.sandbox` provider entry for the confined one (see [the acp-agent example's default composition](../../examples/acp-agent/)).
diff --git a/packages/bash/bash-local/README.md b/packages/bash/bash-local/README.md
index cf919ab836..6048f886a3 100644
--- a/packages/bash/bash-local/README.md
+++ b/packages/bash/bash-local/README.md
@@ -24,12 +24,12 @@ Design surveyed against the bash tools of Claude Code, OpenCode, Codex, and pi;
- **Spawn per call, no shell state** — every call is a fresh non-login `bash -c` (deterministic; no rc files). All four surveyed tools spawn per call. `XXX(stateful-shell)` in `src/run.ts` records the two proven stateful designs (Claude Code's cwd-only persistence; Codex's PTY exec sessions) for when real workflows demand them.
- **Process-group kills with escalation** — children are spawned `detached` (own process group); kills send SIGTERM to the group, then SIGKILL after the `graceMs` grace (default 3s — OpenCode's escalation; pipelines and subshells die with the parent). ESRCH is tolerated; daemons that re-parent away from the group can still survive — same caveat as the surveyed tools.
- **Tail-keep truncation + spill files** — output beyond `maxOutputBytes` keeps the in-memory TAIL (errors/results cluster at the end — pi/OpenCode rationale) while the FULL stream is appended to a temp file whose path is reported when available. If the final spill close reports a delayed writeback failure, the executor still returns the tail but withholds the path rather than advertising a possibly incomplete file.
-- **Model-friendly environment** — ambient credential-shaped variables are removed before noninteractive terminal defaults and explicit caller entries are applied. Supplied stdin is written and closed; otherwise fd 0 is `/dev/null`. Trusted plugins use `env` and `stdin`, but the model-facing tool does not expose them. See the [bash stdin/env RFC](../../../docs/rfc/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.md).
-- **Background tasks** — `start()` returns immediately, no timeout applies (Claude Code detaches timeouts when backgrounding), `readOutput()` is incremental with whole-stream byte offsets, and disposal kills everything. The spec's opaque `owner` token is stored on the tracked task and returned by `ownerOf(id)` — the executor never interprets it (the consumer's access policy does), and because it lives with the task here it survives a `tool-bash` HMR reload.
+- **Model-friendly env + credential scrub** — `process.env` minus credential-shaped vars (`*KEY*`/`*SECRET*`/`*TOKEN*`), then `NO_COLOR=1 TERM=dumb PAGER=cat GIT_PAGER=cat` (Codex's hardcoded set) so pagers and ANSI color don't garble results. This scrub is the security control that keeps the harness's *ambient* credentials out of a spawned command. A spec's `env` is merged LAST (after the scrub), so a caller's explicit entry — a value it already holds — wins even on a credential-shaped name. The spec's `stdin`, when supplied, is written to the child and closed; with none supplied, fd 0 is `/dev/null` — the exact pre-seam default, so a command that probes stdin's file type is unaffected. Both `env`/`stdin` are set by in-process plugins (the hooks bridges); the model-facing tool doesn't expose them. See [the bash-stdin-env RFC](../../../docs/rfc/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.md).
+- **Background processes** — `start()` returns a live `BashProcess` handle immediately, no timeout applies (Claude Code detaches timeouts when backgrounding), the handle's `readOutput()` is incremental with whole-stream byte offsets, and disposal kills every running process and awaits its exit. Everything task-shaped (ids, ownership, polling, notices) lives in the generic [`ctx.tasks` runtime](../../tasks/tasks/README.md), which the tool layer registers the handle with — this executor never sees a session or a registry.
## Model Experience
-Indirectly, through `dsh-tool-bash`, which renders this executor's bounded stdout/stderr tails, background-task deltas and state, spill-file path, exact `Error: unknown bash task ""` and `Error: aborted before spawn: ` failures, and retains each resulting tool message until compaction.
+Indirectly, through `dsh-tool-bash`, which renders this executor's bounded stdout/stderr tails, background-process deltas, spill-file paths, and infrastructure failures.
## Known Limitations and Deferred Work
@@ -38,6 +38,5 @@ Indirectly, through `dsh-tool-bash`, which renders this executor's bounded stdou
- **POSIX-only** — the `bash` binary, detached process groups, group kills, and SIGTERM→SIGKILL escalation are hardcoded; Windows is unsupported.
- **The credential scrub is a name heuristic** — `*KEY*`/`*SECRET*`/`*TOKEN*` only; differently-named secrets (e.g. `*PASSWORD*`) pass through, and a whitelist for over-scrubbed vars is noted future work.
- **Spill files are never deleted** — full-output recovery files (and the private per-process spill dir) accumulate under the OS tmpdir until something external cleans them.
-- **Finished background tasks are never evicted** — they stay in the task map, retaining their in-memory output tails, until executor disposal.
The raw process handling lives in `src/run.ts`; `src/index.ts` is the service wiring.
diff --git a/packages/bash/bash-local/src/index.ts b/packages/bash/bash-local/src/index.ts
index f6dfcea636..9c2b0b4511 100644
--- a/packages/bash/bash-local/src/index.ts
+++ b/packages/bash/bash-local/src/index.ts
@@ -1,15 +1,14 @@
/**
- * Local-subprocess implementation of the bash seam. Each call runs in its own
- * process group, background tasks are tracked, and disposal kills and awaits
- * them. Execution policy belongs in `tools/pre-execute` or a sandboxing
- * executor, not this local process layer.
+ * 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
*/
import { Context } from 'cordis'
import z from 'schemastery'
-import { BashExecutor, BashTaskId } from '@deepseek-ai/dsh-bash'
-import type { BashExecRequest, BashExecSpec, BashRunResult, BashTask, BashTaskRead, OwnerToken } from '@deepseek-ai/dsh-bash'
+import { BashExecutor } from '@deepseek-ai/dsh-bash'
+import type { BashExecRequest, BashExecSpec, BashProcess, BashProcessRead, BashRunResult } from '@deepseek-ai/dsh-bash'
import { clampTimeout, deadline, timeoutOf } from '@deepseek-ai/dsh-timeout'
import { DEFAULT_GRACE_MS, runBash } from './run.ts'
import type { RunInternals, RunningBash } from './run.ts'
@@ -37,20 +36,9 @@ function assertPositiveFinite(name: string, value: number): void {
}
}
-interface TrackedTask extends BashTask {
- running: RunningBash
- /** Whole-stream byte offsets already delivered via {@link LocalBashExecutor.readOutput}. */
- stdoutOffset: number
- stderrOffset: number
- /** Opaque owner token from the {@link BashExecSpec} (the consumer's isolation key). */
- owner: OwnerToken | undefined
-}
-
/**
- * 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 = z.object({
@@ -61,8 +49,8 @@ export class LocalBashExecutor extends BashExecutor {
graceMs: z.number().default(DEFAULT_GRACE_MS),
})
- private tasks = new Map()
- private nextTaskId = 1
+ /** Live processes retained only so disposal can kill and join them. */
+ private live = new Map()
/** Test seam: spill knobs forwarded to runBash. */
internals: RunInternals = {}
@@ -71,26 +59,21 @@ 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[] = []
- for (const task of this.tasks.values()) {
- if (task.status === 'running') {
- task.status = 'killed'
- task.running.kill()
- pending.push(task.done)
- }
+ for (const [proc, running] of this.live) {
+ proc.status = 'killed'
+ running.kill()
+ pending.push(proc.done)
}
- this.tasks.clear()
+ this.live.clear()
await Promise.all(pending)
}, 'local bash teardown')
}
@@ -114,24 +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 } : {},
- // Carry the owner through verbatim (required-but-nullable on the spec):
- // the executor never interprets it — the consumer's access policy does.
- owner: request.owner,
- // Carry a sandbox-mode override through verbatim: this executor never
- // confines, so the field is inert here (the seam contract) — a
- // sandboxing subclass overrides resolve() to stamp its default instead.
+ // Local execution carries this override for sandboxing subclasses.
sandboxMode: request.sandboxMode,
}
}
async run(spec: BashExecSpec): Promise {
- // 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,
@@ -142,18 +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): BashTask {
- // No timeout for background tasks (matches Claude Code, which detaches the timeout when
- // backgrounding); callers stop tasks via kill() — or via spec.signal, which the seam
- // contract honors for background runs too (runBash wires it to the group kill).
+ start(spec: BashExecSpec): BashProcess {
+ // Background runs ignore timeoutMs; callers stop them through kill() or spec.signal.
const running = runBash({
command: spec.command,
cwd: spec.workdir,
@@ -164,93 +135,66 @@ export class LocalBashExecutor extends BashExecutor {
env: spec.env,
}, this.internals)
- const id = BashTaskId(`bash-${this.nextTaskId++}`)
- const task: TrackedTask = {
- id,
+ let stdoutOffset = 0
+ let stderrOffset = 0
+ const proc: BashProcess = {
status: 'running',
exitCode: null,
signal: null,
- owner: spec.owner,
- running,
- stdoutOffset: 0,
- stderrOffset: 0,
done: running.done.then((outcome) => {
- // Abort-killed tasks report as killed, not completed. Background runs
- // forward only the upstream signal (no timeout), so its aborted state
- // is the authoritative "was this cancelled" signal.
- if (task.status === 'running') task.status = spec.signal?.aborted === true ? 'killed' : 'completed'
- task.exitCode = outcome.exitCode
- task.signal = outcome.signal
- this.notifyTaskDone(task)
+ // 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'
+ }
+ proc.exitCode = outcome.exitCode
+ proc.signal = outcome.signal
+ this.onProcessDone(proc, running.stderr.readFrom(0).text)
+ this.live.delete(proc)
}, (error: unknown) => {
- // Spawn-level failure (bad workdir, …): the task never ran. String()
- // suffices — runBash only rejects with Error instances.
- task.status = 'killed'
- task.running.stderr.push(Buffer.from(`spawn failed: ${String(error)}`))
- this.notifyTaskDone(task)
+ // 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)
+ this.live.delete(proc)
}),
- }
- this.tasks.set(id, task)
- return task
- }
+ readOutput: (): BashProcessRead => {
+ const out = running.stdout.readFrom(stdoutOffset)
+ const err = running.stderr.readFrom(stderrOffset)
+ stdoutOffset = out.nextOffset
+ stderrOffset = err.nextOffset
- get(id: BashTaskId): BashTask | undefined {
- return this.tasks.get(id)
+ // Single newline between sections: stdout chunks usually end with one
+ // already; add it only when missing.
+ const separator = out.text.length > 0 && !out.text.endsWith('\n') ? '\n' : ''
+ const delta = out.text
+ + (err.text.length > 0 ? `${separator}[stderr]\n${err.text}` : '')
+ return {
+ delta,
+ lossy: out.lossy || err.lossy,
+ ...out.spillPath !== undefined ? { stdoutSpillPath: out.spillPath } : {},
+ ...err.spillPath !== undefined ? { stderrSpillPath: err.spillPath } : {},
+ }
+ },
+ kill: (): boolean => {
+ if (proc.status !== 'running') return false
+ proc.status = 'killed'
+ running.kill()
+ return true
+ },
+ }
+ this.live.set(proc, running)
+ return proc
}
/**
- * Full collected stderr of a tracked task from stream start (bounded by the
- * in-memory cap; bytes only in the spill file are not re-read). A protected
- * seam for subclasses that classify a settled task's outcome — reading here
- * does NOT advance the consumer's {@link readOutput} cursor. An unknown id
- * (a task already dropped by disposal) reads as empty.
+ * Settlement hook for subclasses that attach execution facts to a process.
+ * Called after exit facts or spawn-failure output are stamped and before
+ * {@link BashProcess.done} resolves. The base implementation is intentionally
+ * empty.
+ * @param _proc - the settled process handle.
+ * @param _stderr - the process's retained stderr tail used by subclasses for settlement classification.
*/
- protected collectedStderr(id: BashTaskId): string {
- const task = this.tasks.get(id)
- return task === undefined ? '' : task.running.stderr.readFrom(0).text
- }
-
- ownerOf(id: BashTaskId): OwnerToken | undefined {
- // Unknown id and known-but-ownerless both read as undefined — the consumer
- // treats undefined as "open" and a truly unknown id fails at readOutput/kill.
- return this.tasks.get(id)?.owner
- }
-
- list(): BashTask[] {
- return [...this.tasks.values()]
- }
-
- readOutput(id: BashTaskId): BashTaskRead {
- const task = this.tasks.get(id)
- if (!task) throw new Error(`unknown bash task "${id}"`)
-
- const out = task.running.stdout.readFrom(task.stdoutOffset)
- const err = task.running.stderr.readFrom(task.stderrOffset)
- task.stdoutOffset = out.nextOffset
- task.stderrOffset = err.nextOffset
-
- // Single newline between sections: stdout chunks usually end with one
- // already; add it only when missing.
- const separator = out.text.length > 0 && !out.text.endsWith('\n') ? '\n' : ''
- const delta = out.text
- + (err.text.length > 0 ? `${separator}[stderr]\n${err.text}` : '')
- return {
- task,
- delta,
- lossy: out.lossy || err.lossy,
- ...out.spillPath !== undefined ? { stdoutSpillPath: out.spillPath } : {},
- ...err.spillPath !== undefined ? { stderrSpillPath: err.spillPath } : {},
- }
- }
-
- kill(id: BashTaskId): boolean {
- const task = this.tasks.get(id)
- if (!task) throw new Error(`unknown bash task "${id}"`)
- if (task.status !== 'running') return false
- task.status = 'killed'
- task.running.kill()
- return true
- }
+ protected onProcessDone(_proc: BashProcess, _stderr: string): void {}
}
export default LocalBashExecutor
diff --git a/packages/bash/bash-local/tests/executor.spec.ts b/packages/bash/bash-local/tests/executor.spec.ts
index 8f24b4b017..b176cbaf86 100644
--- a/packages/bash/bash-local/tests/executor.spec.ts
+++ b/packages/bash/bash-local/tests/executor.spec.ts
@@ -1,11 +1,10 @@
import { mkdtempSync } from 'node:fs'
import { tmpdir } from 'node:os'
import { join } from 'node:path'
-import { describe, expect, it, vi } from 'vitest'
+import { describe, expect, it } from 'vitest'
import { Context } from 'cordis'
import { LocalBashExecutor } from '@deepseek-ai/dsh-bash-local'
-import { BashTaskId } from '@deepseek-ai/dsh-bash'
-import type { BashTaskRead } from '@deepseek-ai/dsh-bash'
+import type { BashProcess } from '@deepseek-ai/dsh-bash'
const spillDir = mkdtempSync(join(tmpdir(), 'dsh-bash-exec-spec-'))
@@ -18,36 +17,20 @@ async function setup(config: ConstructorParameters[1]
return { ctx, bash }
}
-/** Poll until a pid no longer exists. */
-async function waitGone(pid: number, timeoutMs = 5_000): Promise {
+/**
+ * Poll a handle's consuming readOutput until the ACCUMULATED delta contains
+ * `expected`; returns the accumulation (reads never re-deliver, so the caller
+ * gets everything produced up to the match).
+ */
+async function readUntil(proc: BashProcess, expected: string, timeoutMs = 5_000): Promise {
const deadline = Date.now() + timeoutMs
+ let all = ''
while (Date.now() < deadline) {
- try {
- process.kill(pid, 0)
- } catch {
- return
- }
+ all += proc.readOutput().delta
+ if (all.includes(expected)) return all
await new Promise(resolve => setTimeout(resolve, 20))
}
- throw new Error(`pid ${pid} still alive after ${timeoutMs}ms`)
-}
-
-async function readUntil(
- bash: LocalBashExecutor,
- id: BashTaskId,
- expected: string,
- timeoutMs = 5_000,
-): Promise {
- const deadline = Date.now() + timeoutMs
- let last: BashTaskRead | undefined
- let delta = ''
- while (Date.now() < deadline) {
- last = bash.readOutput(id)
- delta += last.delta
- if (delta.includes(expected)) return { ...last, delta }
- await new Promise(resolve => setTimeout(resolve, 20))
- }
- throw new Error(`task ${id} output did not include ${JSON.stringify(expected)}; output was ${JSON.stringify(delta)}, last delta was ${JSON.stringify(last?.delta ?? '')}`)
+ throw new Error(`process output did not include ${JSON.stringify(expected)}; accumulated ${JSON.stringify(all)}`)
}
describe('LocalBashExecutor.run', () => {
@@ -90,15 +73,6 @@ describe('LocalBashExecutor.run', () => {
expect(() => bash.resolve({ command: 'true', timeoutMs: -1 })).toThrow(/request\.timeoutMs/)
})
- it('kill escalation uses the configured graceMs (a TERM-trapping task dies by SIGKILL)', async () => {
- const { bash } = await setup() // setup pins graceMs: 200 via config
- const task = bash.start(bash.resolve({ command: 'trap \'\' TERM; echo ready; while :; do sleep 60 & wait $!; done' }))
- await readUntil(bash, task.id, 'ready\n')
- bash.kill(task.id)
- await task.done
- expect(task.signal).toBe('SIGKILL')
- })
-
it('per-call timeout takes precedence under the cap and kills on expiry', async () => {
const { bash } = await setup({ timeoutMs: 60_000 })
const result = await bash.run(bash.resolve({ command: 'sleep 60', timeoutMs: 100 }))
@@ -154,229 +128,183 @@ describe('LocalBashExecutor.run', () => {
})
})
-describe('LocalBashExecutor background tasks', () => {
- it('start returns immediately with a registered running task', async () => {
+describe('LocalBashExecutor.start (background process handles)', () => {
+ it('start returns immediately with a running handle that settles as completed', async () => {
const { bash } = await setup()
const before = Date.now()
- const task = bash.start(bash.resolve({ command: 'sleep 0.2; echo done' }))
+ const proc = bash.start(bash.resolve({ command: 'sleep 0.2; echo done' }))
expect(Date.now() - before).toBeLessThan(150)
- expect(task.status).toBe('running')
- expect(bash.get(task.id)).toBe(task)
- expect(bash.list()).toContain(task)
- await task.done
- expect(task.status).toBe('completed')
- expect(task.exitCode).toBe(0)
+ expect(proc.status).toBe('running')
+ await proc.done
+ expect(proc.status).toBe('completed')
+ expect(proc.exitCode).toBe(0)
})
- it('assigns sequential ids', async () => {
+ it('threads stdin and extra env into a background process', async () => {
const { bash } = await setup()
- const first = bash.start(bash.resolve({ command: 'true' }))
- const second = bash.start(bash.resolve({ command: 'true' }))
- expect(first.id).toBe('bash-1')
- expect(second.id).toBe('bash-2')
- await Promise.all([first.done, second.done])
- })
-
- it('threads stdin and extra env into a background task', async () => {
- const { bash } = await setup()
- const task = bash.start(bash.resolve({
+ const proc = bash.start(bash.resolve({
command: 'cat; echo "[$DSH_BG_VAR]"',
stdin: 'bg-stdin\n',
env: { DSH_BG_VAR: 'bg-env' },
}))
- const read = await readUntil(bash, task.id, '[bg-env]')
- expect(read.delta).toContain('bg-stdin')
- await task.done
- expect(task.exitCode).toBe(0)
+ const output = await readUntil(proc, '[bg-env]')
+ expect(output).toContain('bg-stdin')
+ await proc.done
+ expect(proc.exitCode).toBe(0)
})
- it('readOutput returns increments without re-delivery', async () => {
+ it('readOutput is consuming: increments are never re-delivered, and reads stay valid after exit', async () => {
const { bash } = await setup()
- const task = bash.start(bash.resolve({ command: 'echo first; sleep 1; echo second' }))
- const first = await readUntil(bash, task.id, 'first\n')
- expect(first.delta).toBe('first\n')
- expect(first.lossy).toBe(false)
- await task.done
- const second = bash.readOutput(task.id)
+ const proc = bash.start(bash.resolve({ command: 'echo first; sleep 1; echo second' }))
+ const first = await readUntil(proc, 'first\n')
+ expect(first).toBe('first\n')
+ await proc.done
+ // Read-after-exit returns the remaining buffered output — once.
+ const second = proc.readOutput()
expect(second.delta).toBe('second\n')
- const third = bash.readOutput(task.id)
- expect(third.delta).toBe('')
+ expect(second.lossy).toBe(false)
+ expect(proc.readOutput().delta).toBe('')
})
it('readOutput marks stderr sections', async () => {
const { bash } = await setup()
- const task = bash.start(bash.resolve({ command: 'echo out; echo err >&2' }))
- await task.done
- const read = bash.readOutput(task.id)
- expect(read.delta).toBe('out\n[stderr]\nerr\n')
+ const proc = bash.start(bash.resolve({ command: 'echo out; echo err >&2' }))
+ await proc.done
+ expect(proc.readOutput().delta).toBe('out\n[stderr]\nerr\n')
})
it('readOutput reports stderr-only deltas without a leading newline', async () => {
const { bash } = await setup()
- const task = bash.start(bash.resolve({ command: 'echo err >&2' }))
- await task.done
- expect(bash.readOutput(task.id).delta).toBe('[stderr]\nerr\n')
+ const proc = bash.start(bash.resolve({ command: 'echo err >&2' }))
+ await proc.done
+ expect(proc.readOutput().delta).toBe('[stderr]\nerr\n')
})
- it('readOutput flags lossy reads and reports spill paths', async () => {
+ it('readOutput adds a separator only when stdout lacks a trailing newline', async () => {
+ const { bash } = await setup()
+ const proc = bash.start(bash.resolve({ command: 'printf out; echo err >&2' }))
+ await proc.done
+ expect(proc.readOutput().delta).toBe('out\n[stderr]\nerr\n')
+ })
+
+ it('readOutput flags lossy reads and reports stdout spill paths', async () => {
const { bash } = await setup({ maxOutputBytes: 100 })
- const task = bash.start(bash.resolve({ command: 'for i in $(seq 1 100); do printf "line-%04d\\n" $i; done' }))
- await task.done
- const read = bash.readOutput(task.id)
+ const proc = bash.start(bash.resolve({ command: 'for i in $(seq 1 100); do printf "line-%04d\\n" $i; done' }))
+ await proc.done
+ const read = proc.readOutput()
// Window slid past offset 0 → lossy, spill path points at the full stream.
expect(read.lossy).toBe(true)
expect(read.stdoutSpillPath).toBeDefined()
})
- it('readOutput throws for unknown ids', async () => {
- const { bash } = await setup()
- expect(() => bash.readOutput(BashTaskId('nope'))).toThrow(/unknown bash task "nope"/)
- })
-
- it('kill terminates the process group and reports status killed', async () => {
- const { bash } = await setup()
- const task = bash.start(bash.resolve({ command: 'sleep 60' }))
- expect(bash.kill(task.id)).toBe(true)
- await task.done
- expect(task.status).toBe('killed')
- expect(task.signal).toBe('SIGTERM')
- })
-
- it('kill returns false for finished tasks and throws for unknown ids', async () => {
- const { bash } = await setup()
- const task = bash.start(bash.resolve({ command: 'true' }))
- await task.done
- expect(bash.kill(task.id)).toBe(false)
- expect(() => bash.kill(BashTaskId('nope'))).toThrow(/unknown bash task "nope"/)
- })
-
- it('notifies onTaskDone listeners on completion', async () => {
- const { bash } = await setup()
- const seen: [string, string][] = []
- bash.onTaskDone(task => void seen.push([task.id, task.status]))
- const task = bash.start(bash.resolve({ command: 'true' }))
- await task.done
- expect(seen).toEqual([[task.id, 'completed']])
- })
-
- it('notifies onTaskDone for killed tasks too', async () => {
- const { bash } = await setup()
- const listener = vi.fn()
- bash.onTaskDone(listener)
- const task = bash.start(bash.resolve({ command: 'sleep 60' }))
- bash.kill(task.id)
- await task.done
- expect(listener).toHaveBeenCalledWith(task)
- expect(task.status).toBe('killed')
- })
-
- it('marks tasks killed when the background spawn itself fails', async () => {
- const { bash } = await setup()
- const listener = vi.fn()
- bash.onTaskDone(listener)
- const task = bash.start(bash.resolve({ command: 'true', workdir: '/nonexistent-dsh' }))
- await task.done
- expect(task.status).toBe('killed')
- expect(listener).toHaveBeenCalledWith(task)
- expect(bash.readOutput(task.id).delta).toContain('spawn failed')
- })
-
- it('readOutput adds a separator only when stdout lacks a trailing newline', async () => {
- const { bash } = await setup()
- const task = bash.start(bash.resolve({ command: 'printf out; echo err >&2' }))
- await task.done
- expect(bash.readOutput(task.id).delta).toBe('out\n[stderr]\nerr\n')
- })
-
it('readOutput reports stderr spill paths', async () => {
const { bash } = await setup({ maxOutputBytes: 100 })
- const task = bash.start(bash.resolve({ command: 'for i in $(seq 1 100); do printf "line-%04d\\n" $i >&2; done' }))
- await task.done
- const read = bash.readOutput(task.id)
+ const proc = bash.start(bash.resolve({ command: 'for i in $(seq 1 100); do printf "line-%04d\\n" $i >&2; done' }))
+ await proc.done
+ const read = proc.readOutput()
expect(read.lossy).toBe(true)
expect(read.stderrSpillPath).toBeDefined()
expect(read.delta).toContain('[stderr]')
})
- it('disposing with already-finished tasks only kills the running ones', async () => {
+ it('kill() terminates the process group: true once, false after settlement', async () => {
+ const { bash } = await setup()
+ const proc = bash.start(bash.resolve({ command: 'sleep 60' }))
+ expect(proc.kill()).toBe(true)
+ await proc.done
+ expect(proc.status).toBe('killed')
+ expect(proc.signal).toBe('SIGTERM')
+ expect(proc.kill()).toBe(false)
+ })
+
+ it('kill() returns false for a naturally completed process', async () => {
+ const { bash } = await setup()
+ const proc = bash.start(bash.resolve({ command: 'true' }))
+ await proc.done
+ expect(proc.status).toBe('completed')
+ expect(proc.kill()).toBe(false)
+ })
+
+ it('kill escalation uses the configured graceMs (a TERM-trapping process dies by SIGKILL)', async () => {
+ const { bash } = await setup() // setup pins graceMs: 200 via config
+ // The child echoes AFTER arming the trap, so waiting for the marker
+ // guarantees SIGTERM is already ignored when the kill lands (a fixed sleep
+ // is load-flaky: a slow spawn would take the SIGTERM before the trap).
+ const proc = bash.start(bash.resolve({ command: 'trap \'\' TERM; echo armed; sleep 60' }))
+ await readUntil(proc, 'armed')
+ proc.kill()
+ await proc.done
+ expect(proc.status).toBe('killed')
+ expect(proc.signal).toBe('SIGKILL')
+ })
+
+ it('a spec.signal abort settles the handle as killed, not completed', async () => {
+ const { bash } = await setup()
+ const controller = new AbortController()
+ const proc = bash.start(bash.resolve({ command: 'sleep 60', signal: controller.signal }))
+ controller.abort()
+ await proc.done
+ expect(proc.status).toBe('killed')
+ expect(proc.signal).toBe('SIGTERM')
+ })
+
+ it('a self-signal exit settles the handle as killed, not completed', async () => {
+ const { bash } = await setup()
+ const proc = bash.start(bash.resolve({ command: 'kill -TERM $$' }))
+ await proc.done
+ expect(proc.status).toBe('killed')
+ expect(proc.exitCode).toBeNull()
+ expect(proc.signal).toBe('SIGTERM')
+ })
+
+ it('a background spawn failure settles as killed with the error readable on stderr', async () => {
+ const { bash } = await setup()
+ const proc = bash.start(bash.resolve({ command: 'true', workdir: '/nonexistent-dsh' }))
+ // done resolves (never rejects) even though the process never ran.
+ await expect(proc.done).resolves.toBeUndefined()
+ expect(proc.status).toBe('killed')
+ expect(proc.readOutput().delta).toContain('spawn failed:')
+ })
+})
+
+describe('LocalBashExecutor disposal', () => {
+ it('disposing the fiber kills running processes and AWAITS their exit (no orphans, SIGKILL escalation included)', async () => {
const ctx = new Context()
const fiber = await ctx.plugin(LocalBashExecutor, { graceMs: 200 })
const bash = ctx.bash as LocalBashExecutor
bash.internals = { spillDir }
- const finished = bash.start(bash.resolve({ command: 'true' }))
+ // The child prints its own pid ($$ = the detached bash group leader) so
+ // the test can probe liveness through the public read surface alone.
+ const proc = bash.start(bash.resolve({ command: 'trap \'\' TERM; echo $$; sleep 60' }))
+ const pid = Number((await readUntil(proc, '\n')).trim())
+ expect(Number.isInteger(pid) && pid > 0).toBe(true)
+
+ await fiber.dispose()
+ // Disposal itself waited: the pid must already be gone, no grace left —
+ // even for a TERM-trapping child held until the SIGKILL escalation landed.
+ expect(() => process.kill(pid, 0)).toThrow()
+ expect(proc.status).toBe('killed')
+ await proc.done
+ })
+
+ it('settled processes already left the live map: dispose does not touch them', async () => {
+ const ctx = new Context()
+ const fiber = await ctx.plugin(LocalBashExecutor, { graceMs: 200 })
+ const bash = ctx.bash as LocalBashExecutor
+ bash.internals = { spillDir }
+
+ const finished = bash.start(bash.resolve({ command: 'echo done' }))
await finished.done
+ expect(finished.status).toBe('completed')
const running = bash.start(bash.resolve({ command: 'sleep 60' }))
await fiber.dispose()
- await running.done
+ // The teardown marks every LIVE entry killed; a settled process had
+ // already left the map, so its status stays completed.
expect(finished.status).toBe('completed')
+ expect(running.status).toBe('killed')
+ await running.done
expect(running.signal).toBe('SIGTERM')
- expect(bash.list()).toEqual([])
- })
-
- it('disposing the executor fiber kills running tasks (no orphans)', async () => {
- const ctx = new Context()
- const fiber = await ctx.plugin(LocalBashExecutor, { graceMs: 200 })
- const bash = ctx.bash as LocalBashExecutor
- bash.internals = { spillDir }
- const listener = vi.fn()
- bash.onTaskDone(listener)
-
- const task = bash.start(bash.resolve({ command: 'sleep 60' }))
- const running = bash.get(task.id)!
- await new Promise(resolve => setTimeout(resolve, 50))
-
- // Grab the pid before dispose clears the registry.
- const pid = (running as unknown as { running: { pid: number } }).running.pid
- await fiber.dispose()
- await waitGone(pid)
- expect(bash.list()).toEqual([])
- // Listener silenced by base-class teardown — no late notifications.
- expect(listener).not.toHaveBeenCalled()
- })
-})
-
-describe('executor cancellation, callback, and disposal contracts', () => {
- it('start honors a pre-aborted or later-aborted AbortSignal', async () => {
- const { bash } = await setup()
- const controller = new AbortController()
- const task = bash.start(bash.resolve({ command: 'sleep 60', signal: controller.signal }))
- controller.abort()
- await task.done
- expect(task.status).toBe('killed')
- expect(task.signal).toBe('SIGTERM')
- })
-
- it('a throwing onTaskDone listener does not reject task.done or starve later listeners', async () => {
- const { bash } = await setup()
- const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => undefined)
- const second = vi.fn()
- try {
- bash.onTaskDone(() => { throw new Error('listener bug') })
- bash.onTaskDone(second)
- const task = bash.start(bash.resolve({ command: 'true' }))
- await expect(task.done).resolves.toBeUndefined()
- expect(second).toHaveBeenCalledWith(task)
- expect(errorSpy).toHaveBeenCalled()
- } finally {
- errorSpy.mockRestore()
- }
- })
-
- it('dispose AWAITS a TERM-trapping process (SIGKILL escalation included)', async () => {
- const ctx = new Context()
- const fiber = await ctx.plugin(LocalBashExecutor, { graceMs: 200 })
- const bash = ctx.bash as LocalBashExecutor
- bash.internals = { spillDir }
-
- const task = bash.start(bash.resolve({ command: 'trap \'\' TERM; sleep 60' }))
- await new Promise(resolve => setTimeout(resolve, 100))
- const pid = (task as unknown as { running: { pid: number } }).running.pid
-
- await fiber.dispose()
- // Disposal itself waited: the pid must already be gone, no grace left.
- expect(() => process.kill(pid, 0)).toThrow()
- expect(task.status).toBe('killed')
})
})
diff --git a/packages/bash/bash-sandbox/README.md b/packages/bash/bash-sandbox/README.md
index 0d0ebca439..347aefb679 100644
--- a/packages/bash/bash-sandbox/README.md
+++ b/packages/bash/bash-sandbox/README.md
@@ -2,21 +2,23 @@
Sandbox-consuming implementation of the [`@deepseek-ai/dsh-bash`](../bash/) executor seam. Load it **instead of** `@deepseek-ai/dsh-bash-local`, together with a [`ctx.sandbox`](../../sandbox/sandbox/) provider (e.g. [`@deepseek-ai/dsh-sandbox-local`](../../sandbox/sandbox-local/)) — no alternate tool plugin is needed; `dsh-tool-bash` detects the executor's `sandboxMode` capability and adds the escalation fields.
+The package root exports the default and named `SandboxBashExecutor` plugin plus its `Config`; quoting and result-classification helpers stay internal.
+
Every command is confined by handing the provider the exact `['bash', '-c', command]` argv this executor is about to spawn and spawning the returned (wrapped) argv instead. WHICH platform runner confines it — and whether one is usable at all (fail closed with a structured `SANDBOX_UNAVAILABLE` error, never a silent unconfined run) — is the provider's concern; this package owns the bash side only.
| Mode | File effects |
|---|---|
| `read-only` (default) | No writes anywhere (of `/dev`, only the `/dev/null` node is writable, so `>/dev/null` keeps working) |
| `workspace-write` | Writes only under `workspaceRoot` + `/tmp` (ephemeral under bwrap, the host `/tmp` under Landlock, `/private/tmp` plus the per-user temp dir under Seatbelt) |
-| `danger-full-access` | No confinement; the provider is never consulted. Execution is `dsh-bash-local`'s verbatim — foreground results still carry `sandbox: { mode, denied: false }` (no `enforcement`: nothing was confined), background tasks carry no sandbox facts |
+| `danger-full-access` | No confinement; the provider is never consulted. Foreground results carry `sandbox: { mode, denied: false }`; background process handles carry no sandbox facts. |
Semantics:
- **Denials are result facts.** A failed run whose stderr carries the selected backend's own denial dialect — the signatures the provider stamps on every wrap (EROFS text under bwrap, EACCES under Landlock, EPERM under Seatbelt) — is reported as `BashRunResult.sandbox.denied: true` (conservative classification, read from the collected stderr tail); every CONFINED run also carries the mode it executed under (`result.sandbox.mode`) and the provider's enforcement completeness (`result.sandbox.enforcement`: `full`, or `partial` on an older Landlock ABI).
-- **Runner failures are sandbox failures, never task failures.** A failed run matching the wrap's `runnerFailureSignatures` (the runner's own error prefix — also what the shell prints for a missing runner) means the sandbox itself broke and the command NEVER RAN; the check outranks denial classification because a runner's error text can contain denial words. The foreground path re-throws it as the structured fail-closed `SANDBOX_UNAVAILABLE` error, with the runner's first stderr line as the cause; a settled background task stamps `task.sandbox.runnerFailed` instead (no error channel remains after settle), which `bash_output` renders as its own marker.
-- **Config default, per-call override.** `resolve()` stamps the configured sandbox mode onto each spec unless an approved request supplies a wider mode. That override affects only its call or background task. `ctx.bash.sandboxMode` reports the default so the tool advertises escalation only when supported; results report the effective mode. The model learns standing mode only from tool/result facts, not a system-prompt announcement.
+- **Runner failures are sandbox failures, never command failures.** Foreground execution throws `SANDBOX_UNAVAILABLE`; a settled background process stamps `process.sandbox.runnerFailed`, which the bash producer renders through generic `task_output`. Spawn failures also pass through settlement, so confined background handles retain their mode/enforcement facts and release per-process accounting.
+- **Config-time default, per-call policy.** The DEFAULT mode is fixed by this entry's config for the executor's lifetime; `resolve()` stamps it onto every spec, and an explicit request-level `sandboxMode` override — set by the tool layer only for a call whose wider mode a human granted through `ctx.approval` ([the sandbox RFC § Escalation](../../../docs/rfc/implemented/feature/2026-07-06-sandbox.md)) — makes THAT call run, classify, and report under its own mode while every neighbor keeps the default (background facts are stamped per task at settle). The capability fact `ctx.bash.sandboxMode` reports the configured default so the tool layer advertises escalation only when this executor is mounted. The model learns of the sandbox only through result facts — the static bash tool description explains the denial marker; there is no current-mode statement in the system prompt.
- **File effects only.** Network and process visibility are deliberately not restricted — the mode vocabulary does not pretend to cover what the backend does not enforce.
-- Process mechanics (spawn, process-group kills, output collection/spill, background tasks, credential scrub) are inherited verbatim from [`dsh-bash-local`](../bash-local/); the runner ladder, probes, and the per-platform Landlock launcher packages live with [`dsh-sandbox-local`](../../sandbox/sandbox-local/).
+- Process mechanics (spawn, process-group kills, output collection/spill, background handles, credential scrub) are inherited from [`dsh-bash-local`](../bash-local/); runner selection lives in [`dsh-sandbox-local`](../../sandbox/sandbox-local/).
Deny-only at the seam: a denial is a reported fact, and this executor never negotiates permissions itself — the approval question lives in the tool layer (`dsh-tool-bash`), which drives the override this package honors.
@@ -56,5 +58,5 @@ The keyless consumer-integration proofs are `tests/bwrap.e2e.ts`, `tests/landloc
- **Confinement covers file effects only** — network access and process visibility are unchanged, so the modes are not a general-purpose security sandbox.
- **Denials are inferred from failed-command stderr** — backend signatures make the inference portable, but a matching application error can be classified as a denial and a denial omitted from the retained tail can be missed.
-- **A background runner failure has no immediate error channel** — it is recorded on the settled task and surfaces when the caller polls with `bash_output`.
+- **A background runner failure has no immediate error channel** — it is recorded on the settled process and surfaces when the caller reads the generic task with `task_output`.
- **`danger-full-access` deliberately bypasses `ctx.sandbox`** — it is an explicit unconfined mode, not a wider sandbox profile.
diff --git a/packages/bash/bash-sandbox/src/helpers.ts b/packages/bash/bash-sandbox/src/helpers.ts
new file mode 100644
index 0000000000..a98f47216e
--- /dev/null
+++ b/packages/bash/bash-sandbox/src/helpers.ts
@@ -0,0 +1,49 @@
+/**
+ * Internal shell-quoting and sandbox-result classification helpers.
+ *
+ * @module @deepseek-ai/dsh-bash-sandbox/helpers
+ */
+
+import type { BashRunResult } from '@deepseek-ai/dsh-bash'
+
+/**
+ * Quote one string as a single-quoted POSIX shell word.
+ * @param text - raw argv element to preserve through the outer shell parse.
+ * @returns the quoted shell word.
+ */
+export function shellQuote(text: string): string {
+ return `'${text.replaceAll("'", String.raw`'\''`)}'`
+}
+
+/**
+ * Classify a failed run against the selected backend's denial dialect.
+ * @param result - settled foreground run.
+ * @param signatures - case-insensitive denial substrings from the active wrap.
+ * @returns whether the failed run matches that denial dialect.
+ */
+export function classifyDenial(result: BashRunResult, signatures: readonly string[]): boolean {
+ return matchesSignature(result.exitCode, result.stderr.text, signatures)
+}
+
+/**
+ * Classify a failed run against the selected backend's runner-failure dialect.
+ * @param result - settled foreground run.
+ * @param signatures - case-insensitive runner-failure substrings from the active wrap.
+ * @returns whether the failed run matches that runner-failure dialect.
+ */
+export function classifyRunnerFailure(result: BashRunResult, signatures: readonly string[]): boolean {
+ return matchesSignature(result.exitCode, result.stderr.text, signatures)
+}
+
+/**
+ * Match a non-zero exit against case-insensitive stderr signatures.
+ * @param exitCode - process exit code; null means signal termination.
+ * @param stderr - collected stderr text.
+ * @param signatures - substrings identifying the selected backend's dialect.
+ * @returns whether this is a non-zero exit whose stderr matches a signature.
+ */
+export function matchesSignature(exitCode: number | null, stderr: string, signatures: readonly string[]): boolean {
+ if (exitCode === null || exitCode === 0) return false
+ const lowered = stderr.toLowerCase()
+ return signatures.some(signature => lowered.includes(signature.toLowerCase()))
+}
diff --git a/packages/bash/bash-sandbox/src/index.ts b/packages/bash/bash-sandbox/src/index.ts
index 3b8837a7b6..124f6b6a9f 100644
--- a/packages/bash/bash-sandbox/src/index.ts
+++ b/packages/bash/bash-sandbox/src/index.ts
@@ -3,24 +3,25 @@
* `ctx.sandbox`, inherits local process mechanics, and reports the selected
* mode, enforcement, and denial facts. Runner failure means the command never
* ran: foreground calls throw `SANDBOX_UNAVAILABLE`, while settled background
- * tasks carry `runnerFailed`. The tool owns approval and passes per-call modes.
+ * processes carry `runnerFailed`. The tool owns approval and passes per-call modes.
* @module @deepseek-ai/dsh-bash-sandbox
*/
import { resolve } from 'node:path'
import { Context } from 'cordis'
import z from 'schemastery'
-import type { BashExecRequest, BashExecSpec, BashRunResult, BashTask, BashTaskId } from '@deepseek-ai/dsh-bash'
+import type { BashExecRequest, BashExecSpec, BashProcess, BashRunResult } from '@deepseek-ai/dsh-bash'
import { SandboxUnavailableError } from '@deepseek-ai/dsh-sandbox'
import type { ConfinedSandboxMode, SandboxEnforcement, SandboxMode } from '@deepseek-ai/dsh-sandbox'
import { LocalBashExecutor } from '@deepseek-ai/dsh-bash-local'
import type { Config as LocalConfig } from '@deepseek-ai/dsh-bash-local'
+import { classifyDenial, classifyRunnerFailure, matchesSignature, shellQuote } from './helpers.ts'
/**
* 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 {
@@ -33,54 +34,6 @@ export interface Config extends LocalConfig {
workspaceRoot?: string
}
-/**
- * Quote one string as a single-quoted POSIX shell word (embedded single
- * quotes become `'\''`), so a wrapped argv element survives the outer
- * `bash -c` re-parse byte-for-byte.
- * @param text - the raw argv element to quote.
- * @returns the single-quoted shell word.
- */
-export function shellQuote(text: string): string {
- return `'${text.replaceAll("'", String.raw`'\''`)}'`
-}
-
-/**
- * Conservatively classify a nonzero, non-signal run using only the selected
- * backend's denial signatures. Text inference may miss a denial or match
- * unrelated stderr in that dialect; it never uses another backend's terms.
- * @param result - the settled foreground run to classify.
- * @param signatures - the active wrap's denial dialect, case-insensitive stderr substrings.
- * @returns whether the run's failure reads as a sandbox denial.
- */
-export function classifyDenial(result: BashRunResult, signatures: readonly string[]): boolean {
- return matchesSignature(result.exitCode, result.stderr.text, signatures)
-}
-
-/**
- * Classify a nonzero run using the selected backend's runner-failure
- * signatures. Callers check this before denial because runner diagnostics may
- * contain denial words; the command did not run.
- * @param result - the settled foreground run to classify.
- * @param signatures - the active wrap's runner-failure signatures,
- * case-insensitive stderr substrings.
- * @returns whether the run's failure reads as the runner itself failing.
- */
-export function classifyRunnerFailure(result: BashRunResult, signatures: readonly string[]): boolean {
- return matchesSignature(result.exitCode, result.stderr.text, signatures)
-}
-
-/**
- * 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`).
- */
-function matchesSignature(exitCode: number | null, stderr: string, signatures: readonly string[]): boolean {
- if (exitCode === null || exitCode === 0) return false
- const lowered = stderr.toLowerCase()
- return signatures.some(signature => lowered.includes(signature.toLowerCase()))
-}
-
/**
* Registers as `ctx.bash` in place of the local executor and requires a
* `ctx.sandbox` provider; the tool layer is unchanged. The configured mode is
@@ -104,11 +57,12 @@ export class SandboxBashExecutor extends LocalBashExecutor {
private readonly mode: SandboxMode
private readonly workspaceRoot: string
/**
- * Per-task mode and wrap facts retained until settlement. Overlapping tasks
- * may use different modes or provider facts, so one latest-wrap field would
- * misclassify earlier completions.
+ * 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 taskFacts = new Map {
const task = bash.start(bash.resolve({ command: 'echo free-bg' }))
await task.done
expect(task.sandbox).toBeUndefined()
- expect(bash.readOutput(task.id).delta).toContain('free-bg')
+ expect(task.readOutput().delta).toContain('free-bg')
expect(calls).toHaveLength(0)
})
})
@@ -184,7 +185,7 @@ describe('per-call sandboxMode override (the escalation mechanism)', () => {
const task = bash.start(bash.resolve({ command: 'echo bg-free', sandboxMode: 'danger-full-access' }))
await task.done
expect(task.sandbox).toBeUndefined()
- expect(bash.readOutput(task.id).delta).toContain('bg-free')
+ expect(task.readOutput().delta).toContain('bg-free')
expect(calls).toHaveLength(0)
})
})
@@ -243,6 +244,20 @@ describe('result facts', () => {
})
describe('background sandbox facts', () => {
+ it('stamps facts and releases accounting when background spawn fails', async () => {
+ const { bash } = await setup()
+ const missingWorkdir = join(mkdtempSync(join(tmpdir(), 'dsh-sandbox-missing-cwd-')), 'missing')
+ const task = bash.start(bash.resolve({ command: 'true', workdir: missingWorkdir }))
+
+ await task.done
+
+ expect(task.status).toBe('killed')
+ expect(task.readOutput().delta).toContain('spawn failed:')
+ expect(task.sandbox).toEqual({ mode: 'read-only', denied: false, enforcement: 'full' })
+ const accounting = (bash as unknown as { processFacts: Map }).processFacts
+ expect(accounting.size).toBe(0)
+ })
+
it('stamps a settled denial: nonzero exit + permission stderr under a confined mode', async () => {
const { bash } = await setup()
const task = bash.start(bash.resolve({ command: 'echo "x: Permission denied" >&2; exit 1' }))
@@ -273,15 +288,6 @@ describe('background sandbox facts', () => {
expect(task.sandbox).toEqual({ mode: 'read-only', denied: false, enforcement: 'full', runnerFailed: true })
})
- it('completion listeners already see the stamped facts (stamp precedes notify)', async () => {
- const { ctx, bash } = await setup({}, argv => ({ argv: [...argv], enforcement: 'partial', denialSignatures: UNIX_SIGNATURES, runnerFailureSignatures: RUNNER_FAILURE }))
- const seen: unknown[] = []
- ctx.bash.onTaskDone((task) => { seen.push(task.sandbox) })
- const task = bash.start(bash.resolve({ command: 'echo "x: Permission denied" >&2; exit 1' }))
- await task.done
- expect(seen).toEqual([{ mode: 'read-only', denied: true, enforcement: 'partial' }])
- })
-
it('overlapping background tasks keep their OWN wrap facts (per-task, not latest-wrap)', async () => {
// Facts belong to each wrap and may vary between calls. The slow task settles after the
// quick task starts; a shared latest-wrap field would classify and stamp it with the wrong
@@ -308,8 +314,8 @@ describe('background sandbox facts', () => {
const task = bash.start(bash.resolve({ command: 'echo "Permission denied" >&2; sleep 30' }))
// Let the stderr land before the kill so the classifier sees the
// signature and must still refuse it on the null exit code alone.
- await vi.waitFor(() => { expect(bash.readOutput(task.id).delta).toContain('Permission denied') })
- bash.kill(task.id)
+ await vi.waitFor(() => { expect(task.readOutput().delta).toContain('Permission denied') })
+ task.kill()
await task.done
expect(task.sandbox).toEqual({ mode: 'read-only', denied: false, enforcement: 'full' })
})
diff --git a/packages/bash/bash-sandbox/tests/seatbelt.e2e.ts b/packages/bash/bash-sandbox/tests/seatbelt.e2e.ts
index 7cc58202fc..cc3703d742 100644
--- a/packages/bash/bash-sandbox/tests/seatbelt.e2e.ts
+++ b/packages/bash/bash-sandbox/tests/seatbelt.e2e.ts
@@ -5,7 +5,8 @@ import { homedir } from 'node:os'
import { join } from 'node:path'
import { afterEach, describe, expect, it } from 'vitest'
import { Context } from 'cordis'
-import { LocalSandboxProvider, seatbeltProfileArgs } from '@deepseek-ai/dsh-sandbox-local'
+import { LocalSandboxProvider } from '@deepseek-ai/dsh-sandbox-local'
+import { seatbeltProfileArgs } from '@deepseek-ai/dsh-sandbox-local/src/profiles.ts'
import { SandboxBashExecutor } from '@deepseek-ai/dsh-bash-sandbox'
/**
diff --git a/packages/bash/bash/README.md b/packages/bash/bash/README.md
index 540eef700c..ba0915c929 100644
--- a/packages/bash/bash/README.md
+++ b/packages/bash/bash/README.md
@@ -1,6 +1,6 @@
# @deepseek-ai/dsh-bash
-The **bash executor seam**: an abstract `BashExecutor` service (`ctx.bash`) defining WHAT a bash backend does — run commands, manage background tasks — without saying HOW.
+The **bash executor seam**: an abstract `BashExecutor` service (`ctx.bash`) defining WHAT a bash backend does — run foreground commands and start background processes — without saying HOW. Task ids, ownership, collection, cancellation, and notices belong to the generic `ctx.tasks` runtime.
This package is the interface quarter of the bash capability, split so each concern can evolve (and be swapped) independently:
@@ -18,23 +18,20 @@ The split mirrors the LLM seam (`LlmService`/`LlmAdapter`) and the agent-tool su
| Member | Semantics |
|---|---|
| `run(spec)` | Foreground execution. Resolves when the command finishes. **Rejects only for infrastructure failures** (unusable workdir, missing shell, pre-aborted signal); nonzero exits, timeout kills, and abort kills resolve with a descriptive `BashRunResult`. |
-| `start(spec)` | Background execution. Returns a `BashTask` handle immediately; **no timeout applies** (stop tasks via `kill`). |
-| `get(id)` / `list()` | Task lookup. |
+| `start(spec)` | Background execution. Returns a task-free `BashProcess` handle immediately; **no timeout applies**. The caller may adapt it into `ctx.tasks`. |
| `sandboxMode` | The capability fact for the tool layer: the default mode a SANDBOXING executor confines under (`undefined` in the base class — "this executor does not sandbox"). `dsh-tool-bash` reads it at registration to advertise the escalation fields only when the composition honors them. |
-| `ownerOf(id)` | The opaque OWNER token recorded for a background task at `start` (from the spec's `owner`), or `undefined` for an unknown id OR a known-but-ownerless task. The executor stores/returns it verbatim and NEVER interprets it — the access POLICY lives in the consumer (`dsh-tool-bash`), which compares `ownerOf(id)` to the caller's token. Storing ownership here (disposed with the executor's fiber) is what makes it survive a consumer HMR reload. |
-| `readOutput(id)` | **Incremental** output read — consecutive reads never re-deliver. Reads that lost data to buffer bounds flag `lossy` and point at full-stream spill files. Throws for unknown ids. |
-| `kill(id)` | Kill a running task. Returns `false` when it already finished; throws for unknown ids. |
-| `onTaskDone(listener)` | Completion listener (effect-based, disposer returned). Fires exactly once per task; never after the service is disposed. |
+| `BashProcess.readOutput()` | **Incremental** output read — consecutive reads never re-deliver. Reads that lost data to buffer bounds flag `lossy` and point at full-stream spill files. |
+| `BashProcess.kill()` | Kill the process group. Returns `false` when it already finished. |
-Implementations subclass `BashExecutor`, implement the abstract methods, and call `notifyTaskDone(task)` on background completion. Disposal must kill every running task (no orphan processes) — see the HMR-safety tests.
+Implementations subclass `BashExecutor` and implement the abstract methods. Disposal must kill every running process and await its exit — see the HMR-safety tests.
## Vocabulary
-`BashExecRequest` (command, workdir?, timeoutMs?, signal?, stdin?, env?, owner?, sandboxMode?) resolves to `BashExecSpec` (command, workdir, timeoutMs, signal?, stdin?, env?, owner, sandboxMode) before execution; `owner` and `sandboxMode` are optional on the request and **required-but-nullable** on the resolved spec, so a forgotten one is a visible `undefined` rather than a silently-absent property. `sandboxMode` is the explicit per-call sandbox-policy input: an escalation grant a human just issued ([the sandbox RFC § Escalation](../../../docs/rfc/implemented/feature/2026-07-06-sandbox.md), which outranks) or the session's standing override ([the sandbox RFC § Per-session mode switching](../../../docs/rfc/implemented/feature/2026-07-06-sandbox.md)); a sandboxing executor's `resolve()` stamps its configured default when the request carries none, and a non-sandboxing executor carries the field verbatim and confines nothing.
+`BashExecRequest` (command, workdir?, timeoutMs?, signal?, stdin?, env?, sandboxMode?) resolves to `BashExecSpec` (command, workdir, timeoutMs, signal?, stdin?, env?, sandboxMode) before execution. `sandboxMode` is optional on the request and required-but-nullable on the resolved spec: it carries an approved one-shot escalation or the session's standing override; a sandboxing executor stamps its configured default when absent, while a non-sandboxing executor carries the field and confines nothing.
-The seam owns per-session sandbox overrides through the log-only `bash/sandbox-mode` event, `effectiveSandboxMode`, and `setSandboxMode`; writers preserve turn enclosure, and replay restores the last override. `BashTaskId` and `OwnerToken` are distinct brands. Foreground `run` returns exit, timeout, cancellation, output, and optional sandbox facts; background `start` and `readOutput` use task records. A sandboxing executor reports the executed mode, conservative denial classification, and enforcement completeness. See [core-data-structures/bash.md](../../../docs/core-data-structures/bash.md) for full shapes.
+The seam also owns the per-session mode override vocabulary: the log-only `'bash/sandbox-mode'` session event, the pure `effectiveSandboxMode(events)` fold, and the `setSandboxMode(session, mode)` write path. `run()` returns `BashRunResult`; `start()` returns `BashProcess`, whose incremental read and kill methods are adapted by `dsh-tool-bash` into a generic task registration. A sandboxing executor stamps `BashSandboxInfo` on foreground results and settled process handles. See `src/types.ts` and [core-data-structures/bash.md](../../../docs/core-data-structures/bash.md).
-`stdin` and `env` are set by in-process plugins (the hooks bridges, native plugins) to feed a hook command its JSON payload on stdin and its `CLAUDE_PROJECT_DIR`/`CLAUDE_PLUGIN_ROOT` env. The model-facing `dsh-tool-bash` tool does not expose them as parameters — a model already has equivalent power through shell syntax (`FOO=bar cmd`, a heredoc), so they would be redundant tool params. This is not a security boundary: the implementation's credential scrub (not these fields) is what keeps the harness's ambient secrets out of a spawned command. They are plain optionals on the resolved spec (unlike `owner`'s required-but-nullable): a missing one means "none", the safe default. See [the bash-stdin-env RFC](../../../docs/rfc/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.md).
+`stdin` and `env` are set by in-process plugins (the hooks bridges, native plugins) to feed a hook command its JSON payload on stdin and its `CLAUDE_PROJECT_DIR`/`CLAUDE_PLUGIN_ROOT` env. The model-facing `dsh-tool-bash` tool does not expose them as parameters — a model already has equivalent power through shell syntax (`FOO=bar cmd`, a heredoc), so they would be redundant tool params. This is not a security boundary: the implementation's credential scrub (not these fields) is what keeps the harness's ambient secrets out of a spawned command. They are plain optionals on the resolved spec; a missing value means "none". See [the bash-stdin-env RFC](../../../docs/rfc/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.md).
## Model Experience
diff --git a/packages/bash/bash/package.json b/packages/bash/bash/package.json
index 2ae0566142..0783995161 100644
--- a/packages/bash/bash/package.json
+++ b/packages/bash/bash/package.json
@@ -22,13 +22,11 @@
],
"license": "BSD-3-Clause",
"peerDependencies": {
- "@deepseek-ai/dsh-brand": "^0.0.1",
"@deepseek-ai/dsh-sandbox": "^0.0.1",
"@deepseek-ai/dsh-session": "^0.0.1",
"cordis": "^4.0.0-rc.7"
},
"devDependencies": {
- "@deepseek-ai/dsh-brand": "workspace:^",
"@deepseek-ai/dsh-sandbox": "workspace:^",
"@deepseek-ai/dsh-session": "workspace:^",
"cordis": "^4.0.0-rc.7"
diff --git a/packages/bash/bash/src/index.ts b/packages/bash/bash/src/index.ts
index 67e36385f0..7563224000 100644
--- a/packages/bash/bash/src/index.ts
+++ b/packages/bash/bash/src/index.ts
@@ -1,24 +1,23 @@
/**
- * The bash executor seam (`ctx.bash`): an abstract service defining what a bash backend does —
- * run commands, manage background tasks — without saying how.
+ * 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
*/
import { Context, Service } from 'cordis'
import type { SandboxMode } from '@deepseek-ai/dsh-sandbox'
-import type { BashExecRequest, BashExecSpec, BashRunResult, BashTask, BashTaskId, BashTaskListener, BashTaskRead, OwnerToken } from './types.ts'
+import type { BashExecRequest, BashExecSpec, BashProcess, BashRunResult } from './types.ts'
-export { BashTaskId, OwnerToken } from './types.ts'
export { SANDBOX_MODES, effectiveSandboxMode, setSandboxMode } from './session-mode.ts'
export type {
BashExecRequest,
BashExecSpec,
+ BashProcess,
+ BashProcessRead,
+ BashProcessStatus,
BashRunResult,
BashSandboxInfo,
- BashTask,
- BashTaskListener,
- BashTaskRead,
- BashTaskStatus,
CollectedOutput,
} from './types.ts'
@@ -29,34 +28,30 @@ declare module 'cordis' {
}
/**
- * Registers one `ctx.bash` implementation. Runtime command failures resolve as
- * {@link BashRunResult}; only infrastructure failures reject. Background starts
- * return immediately without a timeout, report completion exactly once while
- * live, and remain cancellable by signal or {@link kill}. Output reads are
- * incremental and flag lost buffered data; disposal kills and awaits all tasks.
+ * 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).
+ *
+ * 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. `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
+ * 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 {
- private listeners = new Set()
- private listenersClosed = false
-
constructor(ctx: Context) {
super(ctx, 'bash')
- ctx.effect(() => () => {
- // Close the listener registry before subclass teardown so late task
- // completions (e.g. from kills issued during dispose) stay silent.
- this.listenersClosed = true
- this.listeners.clear()
- }, 'bash listener teardown')
}
/**
- * The sandbox mode this executor confines commands under BY DEFAULT, or `undefined` when it
- * does not sandbox at all — the capability fact the tool and ACP layers read to advertise
- * sandbox controls honestly.
- * A session or call may override this default, so widening is evaluated per
- * execution rather than encoded in this getter.
- * @returns the configured default mode of a sandboxing executor;
- * `undefined` for an executor that never confines.
+ * The sandbox mode this executor applies by default, or `undefined` when it
+ * does not sandbox commands.
+ * @returns the configured default sandbox mode, when supported.
*/
get sandboxMode(): SandboxMode | undefined {
return undefined
@@ -79,79 +74,11 @@ export abstract class BashExecutor extends Service {
abstract run(spec: BashExecSpec): Promise
/**
- * Start a background task and return its handle immediately.
+ * Start a background process and return its handle immediately.
* @param spec - a resolved spec from {@link resolve}, never a raw request.
- * @returns the live task handle; completion fires {@link onTaskDone}.
+ * @returns the live process handle (reads, kill, quiescence promise).
*/
- abstract start(spec: BashExecSpec): BashTask
-
- /**
- * Look up a background task by id.
- * @param id - the task id to look up.
- * @returns the tracked task, or undefined for an id this executor never issued.
- */
- abstract get(id: BashTaskId): BashTask | undefined
-
- /**
- * The opaque OWNER token recorded for a background task at {@link start} (from the {@link
- * BashExecSpec}'s `owner`), or `undefined` for an unknown id OR a known-but-ownerless task.
- * The executor stores the token without interpreting policy; keeping it here
- * lets ownership survive a consumer-plugin reload.
- * @param id - the background task id to look up ownership for.
- * @returns the token recorded at start, verbatim; undefined for an unknown
- * id or a known-but-ownerless task.
- */
- abstract ownerOf(id: BashTaskId): OwnerToken | undefined
-
- /**
- * All tracked background tasks (insertion order).
- * @returns every task this executor started, running or finished.
- */
- abstract list(): BashTask[]
-
- /**
- * Read output produced since the previous read. Throws for unknown ids.
- * @param id - the task to read from.
- * @returns the incremental read; consecutive reads never re-deliver output.
- */
- abstract readOutput(id: BashTaskId): BashTaskRead
-
- /**
- * Kill a running background task. Returns false when it had already
- * finished (no-op). Throws for unknown ids.
- * @param id - the task to kill.
- * @returns true when this call killed it, false when it had already finished.
- */
- abstract kill(id: BashTaskId): boolean
-
- /**
- * Register a background-task completion listener (disposed with the
- * calling fiber). Listeners never fire after this service is disposed.
- * @param listener - called exactly once per task completion.
- * @returns the disposer that unregisters the listener.
- */
- onTaskDone(listener: BashTaskListener): () => void {
- const dispose = this.ctx.effect(() => {
- this.listeners.add(listener)
- return () => this.listeners.delete(listener)
- }, 'bash.onTaskDone()')
- return () => void dispose()
- }
-
- /** For implementations: notify listeners that `task` completed. Listener
- * exceptions are contained (logged) — one bad listener must not reject
- * `BashTask.done` or starve the listeners after it. */
- protected notifyTaskDone(task: BashTask): void {
- if (this.listenersClosed) return
- for (const listener of this.listeners) {
- try {
- listener(task)
- } catch (error: unknown) {
- // Listener bugs are reported, never propagated into task.done.
- console.error('bash onTaskDone listener threw:', error)
- }
- }
- }
+ abstract start(spec: BashExecSpec): BashProcess
}
export default BashExecutor
diff --git a/packages/bash/bash/src/types.ts b/packages/bash/bash/src/types.ts
index 9fe9c2efed..d9ad6eda6d 100644
--- a/packages/bash/bash/src/types.ts
+++ b/packages/bash/bash/src/types.ts
@@ -1,79 +1,24 @@
/**
- * 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).
- *
+ * 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
*/
-import type { Branded } from '@deepseek-ai/dsh-brand'
import type { SandboxEnforcement, SandboxMode } from '@deepseek-ai/dsh-sandbox'
-/** Identifies one background task within an executor (generated `bash-N`). */
-export type BashTaskId = Branded<'BashTaskId'>
-
/**
- * Brand a string as a {@link BashTaskId}.
- * @param id - the raw task-id string (the executor generates `bash-N`).
- * @returns the same string, branded; no validation is performed.
- */
-export function BashTaskId(id: string): BashTaskId {
- return id as BashTaskId
-}
-
-/**
- * A background task's opaque isolation key — the CONSUMER's owner identity, not
- * the bash seam's. The executor stores and returns it verbatim and never
- * interprets it; the access policy lives in the consumer (`dsh-tool-bash`),
- * which is the single boundary that casts its own id vocabulary into one. A
- * DISTINCT brand (not a `SessionId` alias) keeps the seam decoupled — a
- * sandboxed/remote executor inherits no session dependency.
- */
-export type OwnerToken = Branded<'OwnerToken'>
-
-/**
- * Brand a string as an {@link OwnerToken}. Only the consuming boundary
- * (`dsh-tool-bash`) should cast its own id vocabulary in — see the type's doc.
- * @param id - the consumer's raw owner identity (the tool layer passes the owning agent's session id).
- * @returns the same string, branded; no validation is performed.
- */
-export function OwnerToken(id: string): OwnerToken {
- return id as OwnerToken
-}
-
-/**
- * Sandbox facts for one foreground run — present on {@link BashRunResult} iff
- * a sandboxing executor ran the command (an unsandboxed executor reports no
- * `sandbox` field at all). Reported independently of `exitCode`/`signal`
- * (orthogonal outcomes), so a caller can tell "the command failed on its own"
- * from "the sandbox blocked a file operation". The mode/enforcement
- * vocabulary lives on the `@deepseek-ai/dsh-sandbox` seam; this shape is the
- * bash seam's result-fact carrier for it.
+ * Sandbox facts for one run, present iff a sandboxing executor handled it.
+ * Facts are reported independently of process exit status so callers can
+ * distinguish command failures from policy denials and runner failures.
*/
export interface BashSandboxInfo {
/** The mode the command actually ran under. */
mode: SandboxMode
- /**
- * True when the executor classifies this run's failure as the sandbox
- * denying a file operation. The classification is CONSERVATIVE (a failed
- * exit whose stderr carries a filesystem-permission signature) and reads
- * the COLLECTED stderr — the bounded in-memory tail per
- * {@link CollectedOutput} semantics, so a signature that survives only in a
- * spill file is missed toward `denied: false`. A plain command failure
- * keeps `denied: false` even under a sandboxed mode.
- */
+ /** Whether the sandbox denied a file operation. */
denied: boolean
- /**
- * How completely the runner enforced `mode`'s file effects — see
- * {@link SandboxEnforcement}. Absent exactly when `mode` is
- * `danger-full-access`: nothing is confined, so there is no enforcement to
- * report.
- */
+ /** How completely the selected runner enforced the requested mode. */
enforcement?: SandboxEnforcement
- /**
- * The sandbox runner failed before executing the command. Set only on settled
- * background tasks; foreground runs throw `SANDBOX_UNAVAILABLE` instead.
- */
+ /** Whether the sandbox runner failed before the command could run. */
runnerFailed?: boolean
}
@@ -109,30 +54,14 @@ export interface BashExecRequest {
* uses shell syntax like `FOO=bar cmd`).
*/
env?: Record | undefined
- /**
- * Opaque OWNER token for a background task — the consumer's isolation key
- * (the tool layer passes the owning agent's `session.header.id`). The
- * executor stores it on the task and exposes it via {@link BashExecutor.ownerOf};
- * the executor itself NEVER interprets it (no access policy lives in the
- * seam — that is the consumer's job). Absent for foreground runs and for an
- * ownerless background start (a non-agent caller).
- */
- owner?: OwnerToken | undefined
- /**
- * Explicit per-call sandbox policy. The tool stamps a session override or a
- * one-shot approved escalation, with the grant taking precedence. Sandboxing
- * executors honor it for this call; non-sandboxing executors do not confine.
- */
+ /** Explicit per-call sandbox mode override. */
sandboxMode?: SandboxMode | undefined
}
/**
- * 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 tasks, `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
@@ -140,40 +69,14 @@ 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
- * (unlike `owner`): 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 | undefined
- /**
- * Opaque owner token, REQUIRED-but-nullable (mirrors `workdir`/`timeoutMs`
- * being required on the resolved spec): {@link BashExecutor.resolve} carries
- * the request's `owner` through, defaulting a missing one to `undefined`. A
- * required field makes a forgotten owner a VISIBLE `undefined` rather than a
- * silently-absent property that yields an unowned (cross-session-readable)
- * task. `start()` stores it; `run()` (foreground) ignores it.
- */
- owner: OwnerToken | undefined
- /**
- * The sandbox mode this call executes under, REQUIRED-but-nullable for the
- * same visibility reason as `owner`. A sandboxing executor's `resolve()`
- * stamps the effective mode (the request's explicit override, else its
- * configured default) so `run()`/`start()` read the spec, never the config;
- * a non-sandboxing executor carries the request value through verbatim and
- * ignores it (`undefined` under such an executor means what its README says:
- * unconfined execution).
- */
+ /** Resolved sandbox mode; ignored by executors that do not confine. */
sandboxMode: SandboxMode | undefined
}
@@ -201,42 +104,15 @@ export interface BashRunResult {
timeoutMs: number
stdout: CollectedOutput
stderr: CollectedOutput
- /**
- * Sandbox facts, present iff a sandboxing executor ran the command — an
- * unsandboxed executor (e.g. `dsh-bash-local`) never sets it. See
- * {@link BashSandboxInfo} for the `denied` classification semantics.
- */
+ /** Sandbox execution facts, absent for an unsandboxed executor. */
sandbox?: BashSandboxInfo
}
-/** Lifecycle of a background task. */
-export type BashTaskStatus = 'running' | 'completed' | 'killed'
+/** Lifecycle of a background process. */
+export type BashProcessStatus = 'running' | 'completed' | 'killed'
-/** A tracked background task handle. */
-export interface BashTask {
- readonly id: BashTaskId
- status: BashTaskStatus
- /** Exit code once finished (null = killed by signal / still running). */
- exitCode: number | null
- /** Terminating signal name, when signal-killed. */
- signal: NodeJS.Signals | null
- /** Resolves when the underlying process closes (never rejects). */
- readonly done: Promise
- /**
- * Sandbox facts for this task's execution, stamped by a sandboxing executor
- * once the task settles and BEFORE completion listeners are notified — an
- * `onTaskDone` consumer and a `done` awaiter both see it. Denial
- * classification runs against the settled task's collected stderr, so the
- * field cannot exist earlier: absent while the task is running and under an
- * executor that does not sandbox. See {@link BashSandboxInfo} for the
- * `denied` semantics.
- */
- sandbox?: BashSandboxInfo
-}
-
-/** One incremental {@link BashExecutor.readOutput} read. */
-export interface BashTaskRead {
- task: BashTask
+/** One incremental {@link BashProcess.readOutput} read. */
+export interface BashProcessRead {
/** Output produced since the previous read (stderr in a marked section). */
delta: string
/** True when truncation dropped unread bytes the delta cannot include. */
@@ -247,5 +123,31 @@ export interface BashTaskRead {
stderrSpillPath?: string
}
-/** Completion callback for background tasks. */
-export type BashTaskListener = (task: BashTask) => void
+/**
+ * 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). */
+ status: BashProcessStatus
+ /** Exit code once finished (null = killed by signal / still running). */
+ exitCode: number | null
+ /** Terminating signal name, when signal-killed. */
+ signal: NodeJS.Signals | null
+ /** Resolves when the underlying process closes (never rejects — a spawn failure settles as `killed` with the error on stderr). */
+ readonly done: Promise
+ /** Sandbox facts, stamped once a confined process settles. */
+ sandbox?: BashSandboxInfo
+ /**
+ * Read output produced since the previous read (consuming — consecutive
+ * reads never re-deliver). Reads that lost data flag `lossy` and point at
+ * full-stream spill files when available.
+ */
+ readOutput(): BashProcessRead
+ /**
+ * Kill the process group. Returns false when it had already finished
+ * (no-op); idempotent.
+ */
+ kill(): boolean
+}
diff --git a/packages/bash/bash/tests/service.spec.ts b/packages/bash/bash/tests/service.spec.ts
index bdee15aedd..a869f4834c 100644
--- a/packages/bash/bash/tests/service.spec.ts
+++ b/packages/bash/bash/tests/service.spec.ts
@@ -1,150 +1,83 @@
-import { describe, expect, it, vi } from 'vitest'
+import { describe, expect, it } from 'vitest'
import { Context } from 'cordis'
-import { BashExecutor, BashTaskId, OwnerToken } from '@deepseek-ai/dsh-bash'
-import type { BashExecRequest, BashExecSpec, BashRunResult, BashTask, BashTaskRead } from '@deepseek-ai/dsh-bash'
+import { BashExecutor } from '@deepseek-ai/dsh-bash'
+import type { BashExecRequest, BashExecSpec, BashProcess, BashProcessRead, BashRunResult } from '@deepseek-ai/dsh-bash'
-/** Minimal concrete executor: records calls, lets tests drive completions. */
+/**
+ * Minimal concrete executor: canned foreground results, a hand-built process
+ * handle. The seam is TASK-FREE (start returns a {@link BashProcess} handle;
+ * task semantics live in `ctx.tasks`), so this stub is all an implementation
+ * owes the abstract class.
+ */
class StubExecutor extends BashExecutor {
- tasks = new Map()
- private owners = new Map()
-
resolve(request: BashExecRequest): BashExecSpec {
return {
command: request.command,
workdir: request.workdir ?? '/stub',
timeoutMs: request.timeoutMs ?? 1000,
...request.signal ? { signal: request.signal } : {},
- owner: request.owner,
sandboxMode: request.sandboxMode,
}
}
- async run(_spec: BashExecSpec): Promise {
+ async run(spec: BashExecSpec): Promise {
return {
exitCode: 0,
signal: null,
timedOut: false,
aborted: false,
- timeoutMs: 1000,
+ timeoutMs: spec.timeoutMs,
stdout: { text: 'ok', truncated: false },
stderr: { text: '', truncated: false },
}
}
- start(spec: BashExecSpec): BashTask {
- const task: BashTask = {
- id: BashTaskId(`stub-${this.tasks.size + 1}`),
+ start(): BashProcess {
+ const proc: BashProcess = {
status: 'running',
exitCode: null,
signal: null,
done: Promise.resolve(),
+ readOutput: (): BashProcessRead => ({ delta: '', lossy: false }),
+ kill: (): boolean => {
+ if (proc.status !== 'running') return false
+ proc.status = 'killed'
+ return true
+ },
}
- this.tasks.set(task.id, task)
- this.owners.set(task.id, spec.owner)
- return task
+ return proc
}
-
- get(id: BashTaskId): BashTask | undefined {
- return this.tasks.get(id)
- }
-
- ownerOf(id: BashTaskId): OwnerToken | undefined {
- return this.owners.get(id)
- }
-
- list(): BashTask[] {
- return [...this.tasks.values()]
- }
-
- readOutput(id: BashTaskId): BashTaskRead {
- const task = this.tasks.get(id)
- if (!task) throw new Error(`unknown bash task "${id}"`)
- return { task, delta: '', lossy: false }
- }
-
- kill(id: BashTaskId): boolean {
- const task = this.tasks.get(id)
- if (!task) throw new Error(`unknown bash task "${id}"`)
- if (task.status !== 'running') return false
- task.status = 'killed'
- return true
- }
-
- /** Expose the protected notifier for tests. */
- fire(task: BashTask): void {
- this.notifyTaskDone(task)
- }
-}
-
-async function setup() {
- const ctx = new Context()
- await ctx.plugin(StubExecutor)
- // ctx.bash resolves to the registered implementation.
- const bash = ctx.bash as StubExecutor
- return { ctx, bash }
}
describe('BashExecutor service seam', () => {
- it('registers as ctx.bash and serves the abstract API', async () => {
- const { bash } = await setup()
- const task = bash.start(bash.resolve({ command: 'sleep 1' }))
- expect(bash.get(task.id)).toBe(task)
- expect(bash.list()).toEqual([task])
- expect(bash.kill(task.id)).toBe(true)
- expect(bash.kill(task.id)).toBe(false)
- const result = await bash.run(bash.resolve({ command: 'true' }))
- expect(result.exitCode).toBe(0)
- })
-
- it('reports no default sandbox mode (composition truth: the base never confines)', async () => {
- const { bash } = await setup()
- expect(bash.sandboxMode).toBeUndefined()
- })
-
- it('onTaskDone delivers completions to registered listeners', async () => {
- const { bash } = await setup()
- const seen: string[] = []
- bash.onTaskDone(task => void seen.push(task.id))
- const task = bash.start(bash.resolve({ command: 'x' }))
- bash.fire(task)
- expect(seen).toEqual([task.id])
- })
-
- it('onTaskDone disposer unsubscribes the listener', async () => {
- const { bash } = await setup()
- const listener = vi.fn()
- const dispose = bash.onTaskDone(listener)
- dispose()
- bash.fire(bash.start(bash.resolve({ command: 'x' })))
- expect(listener).not.toHaveBeenCalled()
- })
-
- it('listeners registered from a fiber are removed on dispose (HMR safety)', async () => {
- const { ctx, bash } = await setup()
- const listener = vi.fn()
- const fiber = await ctx.plugin(Object.assign((inner: Context) => {
- inner.bash.onTaskDone(listener)
- }, { inject: ['bash'] }))
- bash.fire(bash.start(bash.resolve({ command: 'one' })))
- expect(listener).toHaveBeenCalledTimes(1)
-
- await fiber.dispose()
- bash.fire(bash.start(bash.resolve({ command: 'two' })))
- expect(listener).toHaveBeenCalledTimes(1)
- })
-
- it('silences listeners once the service fiber is disposed', async () => {
+ it('a concrete subclass registers as ctx.bash and serves the abstract API', async () => {
const ctx = new Context()
- const fiber = await ctx.plugin(Object.assign(async (inner: Context) => {
- await inner.plugin(StubExecutor)
- }, {}))
- const bash = ctx.bash as StubExecutor
- const listener = vi.fn()
- bash.onTaskDone(listener)
- const task = bash.start(bash.resolve({ command: 'x' }))
+ await ctx.plugin(StubExecutor)
+ const spec = ctx.bash.resolve({ command: 'echo hi' })
+ expect(spec).toEqual({ command: 'echo hi', workdir: '/stub', timeoutMs: 1000, sandboxMode: undefined })
- await fiber.dispose()
- bash.fire(task)
- expect(listener).not.toHaveBeenCalled()
+ const result = await ctx.bash.run(spec)
+ expect(result.exitCode).toBe(0)
+ expect(result.stdout.text).toBe('ok')
+
+ const proc = ctx.bash.start(spec)
+ expect(proc.status).toBe('running')
+ expect(proc.readOutput()).toEqual({ delta: '', lossy: false })
+ expect(proc.kill()).toBe(true)
+ expect(proc.kill()).toBe(false) // already settled → no-op
+ await proc.done
+ })
+
+ it('reports no default sandbox mode from the task-free base seam', async () => {
+ const ctx = new Context()
+ await ctx.plugin(StubExecutor)
+ expect(ctx.bash.sandboxMode).toBeUndefined()
+ })
+
+ it('loading a second implementation throws (one bash service per context — cordis standard)', async () => {
+ const ctx = new Context()
+ await ctx.plugin(StubExecutor)
+ class SecondExecutor extends StubExecutor {}
+ await expect(ctx.plugin(SecondExecutor)).rejects.toThrow(/service "bash" has been registered/)
})
})
diff --git a/packages/bash/bash/tsconfig.json b/packages/bash/bash/tsconfig.json
index 13d297a292..b9ab094edb 100644
--- a/packages/bash/bash/tsconfig.json
+++ b/packages/bash/bash/tsconfig.json
@@ -14,9 +14,6 @@
{
"path": "../../../vendor/cordis"
},
- {
- "path": "../../util/brand"
- },
{
"path": "../../sandbox/sandbox"
},
diff --git a/packages/bash/tool-bash/README.md b/packages/bash/tool-bash/README.md
index 2c7fe345ad..f2a68e4bd9 100644
--- a/packages/bash/tool-bash/README.md
+++ b/packages/bash/tool-bash/README.md
@@ -1,12 +1,12 @@
# @deepseek-ai/dsh-tool-bash
-The model-facing bash tools — `bash`, `bash_output`, `bash_kill` — registered over the `ctx.bash` executor seam (`@deepseek-ai/dsh-bash`). This package owns schema and text shaping while process concerns stay behind the seam. Executor facts can change rendered results, and a sandboxing executor activates the escalation fields, without moving those presentation rules into the backend.
+The model-facing `bash` tool registered over the `ctx.bash` executor seam. Foreground execution stays behind that seam; a background process handle is registered with the generic `ctx.tasks` runtime and controlled through `task_output`, `task_list`, and `task_kill` from `@deepseek-ai/dsh-tool-tasks`.
Requires a loaded executor implementation (e.g. `@deepseek-ai/dsh-bash-local`); the plugin stays pending until `ctx.bash` exists (`inject: ['tools', 'bash', 'systemPrompt']`).
-The package root exposes only the Cordis plugin contract (`name`, `inject`, `apply`); result rendering remains an implementation detail covered by same-package tests.
+The package root exposes only the Cordis plugin contract (`name`, `inject`, `Config`, `apply`); result rendering and background-process adaptation remain implementation details covered by same-package tests.
-The plugin also contributes the `tool:bash` prompt section (order 105) — the cross-call habit the per-tool descriptions cannot carry: check the `[exit code: N]` marker on every result and investigate failures before moving on. A sandboxing executor changes the `bash` schema and result markers but adds no mode statement or switch notice; see [Per-session mode](#per-session-mode-switching).
+The plugin also contributes the `tool:bash` prompt section (order 105): check the `[exit code: N]` marker on every result and investigate failures before moving on.
## Tools
@@ -26,29 +26,15 @@ The plugin also contributes the `tool:bash` prompt section (order 105) — the c
Result text contains stdout, an optional `[stderr]` section, then applicable sandbox-denial, timeout, signal, exit-code, and truncation markers. Timeout is reported independently of final exit status; nonzero exit remains a model-interpreted result rather than `isError`. Truncation links a safe complete spill file or reports it unavailable. Only infrastructure failures such as spawn errors and aborts produce `isError`.
-### `bash_output`
-
-`task_id` → output produced **since the previous `bash_output` call** plus a status line (`running` / `completed, exit code: N` / `killed`). A settled task classified as a sandbox denial carries the same `[sandbox: file access denied under mode]` marker on every read that sees it (denials are only classifiable once the whole stderr has been collected). Reads that lost data to buffer bounds say so and point at the full-output spill file when one is safely available, otherwise `(unavailable)`.
-
-### `bash_kill`
-
-`task_id` → ask the executor to kill the background task. The concrete executor decides how to signal or stop the process; killing an already-finished task is a reported no-op, and unknown ids are errors.
-
-### Task ownership (cross-session isolation)
-
-The executor stores the spawning session id as the task's owner. `bash_output` and `bash_kill` reject a caller with a different session id; agent-less tasks remain unowned, while agent-less calls cannot access owned tasks. Storing ownership on the task prevents predictable global ids from crossing ACP sessions and preserves the fence across tool-plugin reloads. Completion notices remain effect-scoped and may be missed during a reload gap.
+When `run_in_background` is true, this plugin preflights `ctx.tasks.start()` before spawning, registers the calling agent as owner, and adapts the returned `BashProcess` handle into generic cancel/done/incremental-output hooks. The task runtime owns ids, cross-session isolation, completion notices, waiting, and disposal cleanup; this plugin only maps bash exit/sandbox facts into task output and outcome detail. `enableRunInBackground: false` removes the parameter and rejects a forced background call at execution time.
## UI presentation
-UI presentation is tool-owned through `presentCall` and `presentResult`. Foreground `bash` uses a terminal card whose title is the exact command and whose optional description is separate; cwd follows an explicit `workdir`—resolved by the bridge against the session when relative—or the session cwd. Its result carries raw output plus exit or signal data, and clients without terminal support receive a bridge-derived fenced console fallback. Background runs, spawn failures, `bash_output`, and `bash_kill` use generic cards. Presenters are pure and replay-safe; malformed older arguments fall back to generic rendering. See [`dsh-tools`](../../core/tools/) and [`dsh-acp`](../../ui/acp/) for card semantics.
-
-## Background completion notices
-
-When a task finishes, the plugin resolves its owner token to a live agent and injects a durable completion notice. If the owner no longer exists, the notice is dropped. Injection affects the next request but does not wake an idle agent, so the model must poll with `bash_output` when it needs completion promptly.
+The tool owns its `presentCall`/`presentResult` render intent. A foreground call is a terminal card carrying command, description, cwd, raw output, and parsed exit status. A background start is a generic execute card because it returns only a task id; the generic `task_*` tools own their own cards. These presenters are pure and replay-safe.
## The tool builds its request from named args only
-The seam supports trusted-plugin `stdin` and `env`, but the model-facing tool does not. It builds requests only from its declared arguments, signal, and owner; extra model keys are ignored. Shell syntax already provides equivalent command-level behavior, while the local executor's credential scrub protects ambient secrets. See the [stdin/env RFC](../../../docs/rfc/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.md).
+The `BashExecRequest` seam carries optional `stdin` and `env`, used by trusted in-process plugins. This tool does **not** expose or forward them: it builds requests from named command/workdir/timeout/signal/sandbox fields only. This is not a trust boundary; the local executor's ambient credential scrub is the security control.
## Permissions and escalation
@@ -76,7 +62,7 @@ Check the [exit code: N] marker on every bash result; investigate failures befor
### Tool schemas
-**What the model sees**: The model sees the generated [`bash`, `bash_output`, and `bash_kill` schemas](../../../docs/tool-catalog.md#deepseek-aidsh-tool-bash). `sandbox_permissions` and `justification` augment `bash` only when the mounted executor advertises sandboxing. Agent-scoped tool restrictions can remove the definitions for that agent.
+**What the model sees**: The model sees the generated [`bash` schema](../../../docs/tool-catalog.md#deepseek-aidsh-tool-bash). `run_in_background` appears only when this producer enables it; `sandbox_permissions` and `justification` appear only when the mounted executor advertises sandboxing. Agent-scoped tool restrictions can remove the definition for that agent.
**Token effect**: Fixed schema cost on every request where the tools are visible; sandbox support adds the escalation fields and its conditional description paragraph.
@@ -88,19 +74,18 @@ Check the [exit code: N] marker on every bash result; investigate failures befor
### Background task context and results
-**What the model sees**: Start returns exactly `started background task `. Completion injects exactly `background bash task finished . Read its output with bash_output.` Reads return only the data-dependent delta or `(no new output)`, optionally `[some output was dropped from memory; full output: ]`, then exactly one of `[status: running]`, `[status: killed]`, `[status: killed by ]`, or `[status: completed, exit code: ]`. Kill returns `killed background task ` or `task had already finished`.
+**What the model sees**: Start returns exactly `started background task `. This producer supplies incremental process output, optional `[some output was dropped from memory; full output: ]`, sandbox facts, and terminal detail such as `exit code: ` or `signal: ` to the generic task runtime. [`dsh-tool-tasks`](../../tasks/tool-tasks/README.md) owns the visible status line, completion notice, listing, and cancellation response.
-**Token effect**: Start and status text is small; deltas are data-dependent. The completion notice and every tool result are retained until compaction, but polling does not repeat already-delivered output.
+**Token effect**: The start acknowledgement is small and retained; collected output is data-dependent and bounded by the executor's stream buffers. Consuming reads do not repeat prior output.
### Tool errors
-**What the model sees**: Validation and policy failures are normalized as `Error: `. This package's stable messages are `invalid command: expected a non-empty string`, `invalid description: expected a non-empty string`, `invalid timeoutMs: expected a positive number, got `, `invalid escalation: sandbox_permissions requires a justification`, `invalid escalation: justification is only valid together with sandbox_permissions`, `invalid justification: expected a non-empty sentence`, `invalid task_id: expected a string, got `, `task belongs to another session`, `sandbox_permissions is not available in this composition (no sandboxing executor to escalate)`, `sandbox escalation to "" is not strictly wider than this call's current "" mode`, the approval-availability/rejection/cancellation variants, and `command aborted`.
+**What the model sees**: Validation and policy failures are normalized as `Error: `. This package's stable messages are `invalid command: expected a non-empty string`, `invalid description: expected a non-empty string`, `invalid timeoutMs: expected a positive number, got `, `invalid escalation: sandbox_permissions requires a justification`, `invalid escalation: justification is only valid together with sandbox_permissions`, `invalid justification: expected a non-empty sentence`, `background execution is disabled for this bash tool`, `background tasks unavailable: load @deepseek-ai/dsh-tasks and @deepseek-ai/dsh-tool-tasks`, `sandbox_permissions is not available in this composition (no sandboxing executor to escalate)`, `sandbox escalation to "" is not strictly wider than this call's current "" mode`, the approval-availability/rejection/cancellation variants, and `command aborted`.
**Token effect**: Only the failing call adds these retained tokens; a rejected escalation does not add command output because the command does not run.
## Known Limitations and Deferred Work
- **Replay exit pills parse from result text** — output whose final line happens to be exactly `[exit code: N]` / `[killed by signal: …]` shows a wrong pill on session replay; a display-only known residual.
-- **The bash tools opt out of `timeout-policy` budgets** — `bash` keeps the executor-owned `BASH_TIMEOUT` path and `bash_output`/`bash_kill` declare no budget, per [the tool-call timeout-policy RFC](../../../docs/rfc/implemented/architecture/2026-07-07-tool-call-timeout-policy.md).
-- **Completion notices do not wake an idle agent** — they become durable context for the next request; a caller needing progress now must poll `bash_output` or send another message.
-- **Tasks started outside an agent have no ownership fence** — their predictable ids are readable and killable by any caller; only agent-started tasks carry a session owner token.
+- **The `bash` tool opts out of `timeout-policy` budgets** — it keeps the executor-owned `BASH_TIMEOUT` path, per [the tool-call timeout-policy RFC](../../../docs/rfc/implemented/architecture/2026-07-07-tool-call-timeout-policy.md).
+- **Background processes have no executor timeout** — callers must use `task_kill`, or rely on owner/service disposal, when work no longer matters.
diff --git a/packages/bash/tool-bash/package.json b/packages/bash/tool-bash/package.json
index 4e23a928a7..035b16aeec 100644
--- a/packages/bash/tool-bash/package.json
+++ b/packages/bash/tool-bash/package.json
@@ -1,6 +1,6 @@
{
"name": "@deepseek-ai/dsh-tool-bash",
- "description": "Model-facing bash tools (bash, bash_output, bash_kill) over the DeepSeek Harness bash executor seam",
+ "description": "Model-facing bash tool with optional generic background-task and sandbox-escalation support",
"version": "0.0.1",
"private": true,
"type": "module",
@@ -28,21 +28,25 @@
"@deepseek-ai/dsh-llm": "^0.0.1",
"@deepseek-ai/dsh-sandbox": "^0.0.1",
"@deepseek-ai/dsh-system-prompt": "^0.0.1",
+ "@deepseek-ai/dsh-tasks": "^0.0.1",
"@deepseek-ai/dsh-tools": "^0.0.1",
"cordis": "^4.0.0-rc.7"
},
+ "dependencies": {
+ "schemastery": "^3.18.0"
+ },
"devDependencies": {
"@deepseek-ai/dsh-agent": "workspace:^",
"@deepseek-ai/dsh-agent-loop": "workspace:^",
"@deepseek-ai/dsh-user-approval": "workspace:^",
"@deepseek-ai/dsh-bash": "workspace:^",
"@deepseek-ai/dsh-bash-local": "workspace:^",
- "@deepseek-ai/dsh-bash-sandbox": "workspace:^",
"@deepseek-ai/dsh-llm": "workspace:^",
"@deepseek-ai/dsh-sandbox": "workspace:^",
- "@deepseek-ai/dsh-sandbox-local": "workspace:^",
"@deepseek-ai/dsh-session": "workspace:^",
"@deepseek-ai/dsh-system-prompt": "workspace:^",
+ "@deepseek-ai/dsh-tasks": "workspace:^",
+ "@deepseek-ai/dsh-tool-tasks": "workspace:^",
"@deepseek-ai/dsh-tools": "workspace:^",
"cordis": "^4.0.0-rc.7"
}
diff --git a/packages/bash/tool-bash/src/background.ts b/packages/bash/tool-bash/src/background.ts
new file mode 100644
index 0000000000..6ba67cdfde
--- /dev/null
+++ b/packages/bash/tool-bash/src/background.ts
@@ -0,0 +1,27 @@
+/**
+ * Generic-task adaptation for background bash process handles.
+ *
+ * @module @deepseek-ai/dsh-tool-bash/background
+ */
+
+import type { BashProcess } from '@deepseek-ai/dsh-bash'
+
+/**
+ * Map a settled background process onto the generic task-outcome vocabulary:
+ * `killed` stays `killed` (detail: the signal when one is known), everything
+ * else is `completed` with the exit code as detail. A nonzero command exit is
+ * reported, not failed, exactly like the foreground rendering.
+ * @param proc - the settled process handle.
+ * @returns the outcome for the `ctx.tasks` registration.
+ */
+export function processOutcome(proc: BashProcess): { status: 'completed' | 'killed'; detail: string } {
+ // TODO(background-infrastructure-outcome): widen BashProcess with an explicit
+ // infrastructure-failure outcome, then map spawn failures and
+ // sandbox.runnerFailed to task `failed`. The current seam aliases a spawn
+ // failure with a signal-less kill and a runner failure with an ordinary
+ // wrapper exit; real nonzero command exits must remain `completed`.
+ if (proc.status === 'killed') {
+ return { status: 'killed', detail: proc.signal !== null ? `signal: ${proc.signal}` : 'killed before exit' }
+ }
+ return { status: 'completed', detail: `exit code: ${proc.exitCode ?? 0}` }
+}
diff --git a/packages/bash/tool-bash/src/index.ts b/packages/bash/tool-bash/src/index.ts
index ac4716b43f..476cd1a176 100644
--- a/packages/bash/tool-bash/src/index.ts
+++ b/packages/bash/tool-bash/src/index.ts
@@ -1,36 +1,52 @@
/**
- * Model-facing `bash`, `bash_output`, and `bash_kill` tools over the executor
- * seam. Background tasks are fenced by owning session, completion injects a
- * durable notice, and confining executors add one-shot approval-based escalation.
- * Notices do not wake idle agents. Ownership is stored with the executor task so
- * it survives this plugin's reload; per-call authority is escalation grant,
- * session override, then executor default. See the package README for the tool contract.
+ * 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
*/
import type { Context } from 'cordis'
+import z from 'schemastery'
import { isAbsolute, resolve as resolvePath } from 'node:path'
import { defineTool } from '@deepseek-ai/dsh-tools'
import type { GenericCallView, TerminalCallView, ToolExecution, ToolResult, ToolResultView } from '@deepseek-ai/dsh-tools'
import type { Agent } from '@deepseek-ai/dsh-agent'
import { assertNever } from '@deepseek-ai/dsh-llm'
import type {} from '@deepseek-ai/dsh-system-prompt'
-// Side-effect type import: declaration-merges `ctx.approval`, consumed
-// opportunistically by the escalation gate (`ctx.get('approval')` — the seam
-// stays optional at runtime, same pattern as dsh-tools' ask routing).
+import type {} from '@deepseek-ai/dsh-tasks'
import type {} from '@deepseek-ai/dsh-user-approval'
import type { SandboxMode } from '@deepseek-ai/dsh-sandbox'
-import { BashTaskId, OwnerToken, effectiveSandboxMode } from '@deepseek-ai/dsh-bash'
-import type { BashTask } from '@deepseek-ai/dsh-bash'
-import { parseExitStatus, renderResult } from './render.ts'
+import { effectiveSandboxMode } from '@deepseek-ai/dsh-bash'
+import { processOutcome } from './background.ts'
+import { parseExitStatus, renderProcessRead, renderResult } from './render.ts'
export const name = 'tool-bash'
export const inject = ['tools', 'bash', 'systemPrompt']
-/**
- * Validate value constraints absent from SchemaSpec: non-empty strings, a
- * positive finite timeout, and paired escalation mode and justification.
- */
+/** Configures whether the model may background commands. */
+export interface Config {
+ /** Expose `run_in_background` (default true); disabled calls are also rejected. */
+ enableRunInBackground?: boolean
+}
+
+export const Config: z = z.object({
+ enableRunInBackground: z.boolean().default(true),
+})
+
+/** Parsed tool args; execute validates value constraints absent from SchemaSpec. */
+interface BashToolArgs {
+ command: string
+ description: string
+ timeoutMs?: number
+ workdir?: string
+ run_in_background?: boolean
+ sandbox_permissions?: string
+ justification?: string
+}
+
function validateBashArgs(args: BashToolArgs): void {
if (args.command.trim().length === 0) {
throw new Error('invalid command: expected a non-empty string')
@@ -52,59 +68,23 @@ function validateBashArgs(args: BashToolArgs): void {
}
}
-/**
- * Reject an empty `task_id`; SchemaSpec already validates type and presence.
- */
-function validateTaskId(value: string): BashTaskId {
- if (value.length === 0) {
- throw new Error(`invalid task_id: expected a string, got ${JSON.stringify(value)}`)
- }
- return BashTaskId(value)
-}
-
-/**
- * Validated bash arguments. Escalation fields are advertised only when the
- * mounted executor reports a confining mode.
- */
-interface BashToolArgs {
- command: string
- description: string
- timeoutMs?: number
- workdir?: string
- run_in_background?: boolean
- sandbox_permissions?: string
- justification?: string
-}
-
-/**
- * Strictly wider modes for each effective mode. Execution checks this table
- * because the schema is global while the effective mode is per call.
- */
const WIDER_MODES: Record = {
'read-only': ['workspace-write', 'danger-full-access'],
'workspace-write': ['danger-full-access'],
}
-/**
- * All possible escalation targets. Advertise the global set because a session
- * override may be narrower than the executor default; execution rejects a
- * target that is not wider for that call.
- */
const ESCALATION_TARGETS: readonly SandboxMode[] = ['workspace-write', 'danger-full-access']
-/**
- * The bash tool's byte-stable base description. Escalation guidance is added
- * only when the mounted executor can honor it, as the one exception to the
- * ordinary no-retry guidance.
- */
-function bashDescription(escalationModes: readonly SandboxMode[]): string {
+function bashDescription(backgroundEnabled: boolean, escalationModes: readonly SandboxMode[]): string {
+ const background = backgroundEnabled
+ ? 'Set `run_in_background: true` for long-running commands: the call returns a task id immediately; read its output with `task_output` and stop it with `task_kill`.'
+ : 'Background execution is not available; long-running commands must finish within the timeout.'
const base = 'Execute a bash command (`bash -c`) and return its stdout/stderr. '
+ 'Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — '
+ 'pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. '
- + 'Commands may run under a file sandbox; a blocked file operation is reported as `[sandbox: file access denied under mode]` — a policy denial, not a bug in the command; do not retry another way (a background task reports the same marker via bash_output once it has finished). '
+ + 'Commands may run under a file sandbox; a blocked file operation is reported as `[sandbox: file access denied under mode]` — a policy denial, not a bug in the command; do not retry another way. '
+ 'Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. '
- + 'Set `run_in_background: true` for long-running commands: the call returns a task id immediately; '
- + 'poll it with `bash_output` and stop it with `bash_kill`.'
+ + background
if (escalationModes.length === 0) return base
return base + ' Attempting a command the sandbox may deny is safe and expected: run it and read the '
+ 'marker rather than assuming the denial. When a command is denied and a wider mode would let it '
@@ -119,16 +99,14 @@ function bashDescription(escalationModes: readonly SandboxMode[]): string {
+ 'it — but it does not forbid attempting or escalating other commands later.'
}
-// Pure tool-owned presentation used for both live events and replay.
-
/**
* 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',
@@ -138,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,
@@ -156,21 +133,13 @@ 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) }
}
-/** Pending-state presentation for `bash_output`/`bash_kill` (background-task tools). */
-function presentTaskCall(verb: string, args: { task_id: string }): GenericCallView {
- return { card: 'generic', title: `${verb} background task ${args.task_id}`, kind: 'execute', rawInput: args.task_id }
-}
-
/**
* Resolve an explicit workdir first, making a relative one session-cwd-relative;
* otherwise use the session cwd and leave executor defaulting as the fallback.
@@ -184,86 +153,18 @@ function resolveWorkdir(modelWorkdir: string | undefined, exec: { agent?: Agent
return modelWorkdir
}
-/** Status line for background task reads. */
-function statusLine(task: BashTask): string {
- switch (task.status) {
- case 'running': return '[status: running]'
- case 'killed': return `[status: killed${task.signal !== null ? ` by ${task.signal}` : ''}]`
- case 'completed': return `[status: completed, exit code: ${task.exitCode ?? 0}]`
- }
-}
-
-export function apply(ctx: Context): void {
- // Cross-call guidance belongs in the prompt rather than one tool description.
- ctx.systemPrompt.section({
- name: 'tool:bash',
- order: 105,
- text: 'Check the [exit code: N] marker on every bash result; investigate failures before moving on.',
- })
-
- /**
- * Return the canonical session-header id used by ACP and persistence as the
- * task owner, or undefined for a non-agent caller.
- */
- const callerToken = (exec: { agent?: Agent }): OwnerToken | undefined =>
- exec.agent ? OwnerToken(exec.agent.session.header.id) : undefined
-
- /**
- * Reject access when a task has a different session owner. Unowned tasks are
- * allowed; unknown ids still fail in the subsequent read or kill.
- */
- const assertTaskAccess = (taskId: BashTaskId, exec: { agent?: Agent }): void => {
- const owner = ctx.bash.ownerOf(taskId)
- if (owner !== undefined && owner !== callerToken(exec)) {
- throw new Error(`task ${taskId} belongs to another session`)
- }
- }
-
- // Completion runs on the bash fiber, so use topology-independent lookup and
- // match the executor's stored session-owner token to a live agent.
- ctx.bash.onTaskDone((task) => {
- const ownerToken = ctx.bash.ownerOf(task.id)
- if (ownerToken === undefined) return
- const agent = ctx.get('agents')?.list().find(a => OwnerToken(a.session.header.id) === ownerToken)
- if (!agent) return
- try {
- agent.inject(
- [{ type: 'text', text: `background bash task ${task.id} finished ${statusLine(task)}. Read its output with bash_output.` }],
- { source: { kind: 'plugin', plugin: 'tool-bash' } },
- )
- } catch (error: unknown) {
- // The one expected failure: the agent was disposed between task completion and this
- // injection (ReactLoopAgent.inject throws `agent "" is disposed`).
- if (error instanceof Error && error.message.includes('is disposed')) return
- throw error
- }
- })
-
- // The escalation surface exists whenever the mounted executor confines.
- // Advertise the closed target vocabulary globally, then enforce strict
- // widening against each call's effective session mode.
+export function apply(ctx: Context, config: Config): void {
+ const backgroundEnabled = config.enableRunInBackground ?? true
const defaultMode = ctx.bash.sandboxMode
const escalationModes: readonly SandboxMode[] = defaultMode === undefined ? [] : ESCALATION_TARGETS
- /**
- * Return the calling session's folded standing mode. Approval outranks this
- * value and the executor default applies when it is absent; non-sandboxing
- * and agent-less calls have no override.
- */
const sessionOverride = (exec: ToolExecution): SandboxMode | undefined =>
defaultMode === undefined || exec.agent === undefined ? undefined : effectiveSandboxMode(exec.agent.session.events)
- /**
- * Request one-shot escalation before execution. Missing approval context,
- * rejection, cancellation, and unavailable answers throw without running the
- * command; the optional seam is resolved per call through `ctx.get`.
- */
const approveEscalation = async (mode: string, justification: string, exec: ToolExecution): Promise => {
- // Reject an unadvertised escalation before prompting for a nonexistent sandbox.
if (escalationModes.length === 0) {
throw new Error('sandbox_permissions is not available in this composition (no sandboxing executor to escalate)')
}
- // Reject sandbox widening against the call's effective mode before requesting approval.
const effectiveMode = (sessionOverride(exec) ?? defaultMode) as SandboxMode
if (!(WIDER_MODES[effectiveMode] ?? []).includes(mode as SandboxMode)) {
throw new Error(`sandbox escalation to "${mode}" is not strictly wider than this call's current "${effectiveMode}" mode`)
@@ -279,13 +180,10 @@ export function apply(ctx: Context): void {
agent: exec.agent,
toolName: 'bash',
callId: exec.callId,
- // Self-contained for the audit trail: approval/asked stores this
- // reason, and the target mode is part of the grant's identity.
reason: `escalate sandbox to ${mode}: ${justification}`,
...exec.signal ? { signal: exec.signal } : {},
})
switch (outcome) {
- // Schema validation pins the vocabulary; the per-call check proves widening.
case 'allowed-once': return mode as SandboxMode
case 'rejected': throw new Error(`the user rejected escalating this command to "${mode}"`)
case 'cancelled': throw new Error(`approval for escalating to "${mode}" was cancelled`)
@@ -294,9 +192,16 @@ export function apply(ctx: Context): void {
}
}
+ // Cross-call guidance belongs in the prompt rather than one-call schema prose.
+ ctx.systemPrompt.section({
+ name: 'tool:bash',
+ order: 105,
+ text: 'Check the [exit code: N] marker on every bash result; investigate failures before moving on.',
+ })
+
ctx.tools.register(defineTool({
name: 'bash',
- description: bashDescription(escalationModes),
+ description: bashDescription(backgroundEnabled, escalationModes),
parameters: {
command: { type: 'string', required: true, description: 'The bash command to execute.' },
description: {
@@ -308,104 +213,69 @@ export function apply(ctx: Context): void {
},
timeoutMs: { type: 'number', description: 'Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry.' },
workdir: { type: 'string', description: 'Working directory for this command. Defaults to the session workspace; a relative path is resolved against it.' },
- run_in_background: { type: 'boolean', description: 'Run in the background and return a task id immediately. No timeout applies.' },
+ ...backgroundEnabled ? {
+ run_in_background: { type: 'boolean' as const, description: 'Run in the background and return a task id immediately (collect with task_output, stop with task_kill). No timeout applies.' },
+ } : {},
...escalationModes.length > 0 ? {
sandbox_permissions: {
type: 'string' as const,
enum: [...escalationModes],
- description: 'The wider sandbox mode this command needs. Only valid as a one-shot retry '
- + 'of a command the sandbox just denied; requires justification and user approval.',
+ description: 'The wider sandbox mode this command needs. Only valid as a one-shot retry of a command the sandbox just denied; requires justification and user approval.',
},
justification: {
type: 'string' as const,
- description: 'Required with sandbox_permissions: one sentence for the user explaining '
- + 'why this exact command needs the wider access.',
+ description: 'Required with sandbox_permissions: one sentence for the user explaining why this exact command needs the wider access.',
},
} : {},
},
async execute(args: BashToolArgs, exec) {
validateBashArgs(args)
- // `description` is display/logging metadata only. Escalation approval
- // completes before execution; grant > session override > executor default.
+ // 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)
- // 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.
const workdir = resolveWorkdir(args.workdir, exec)
const request = {
command: args.command,
...workdir !== undefined ? { workdir } : {},
...args.timeoutMs !== undefined ? { timeoutMs: args.timeoutMs } : {},
- ...exec.signal ? { signal: exec.signal } : {},
...sandboxMode !== undefined ? { sandboxMode } : {},
}
if (args.run_in_background === true) {
- // Store the session owner on the task for bash_output/bash_kill isolation.
- const task = ctx.bash.start(ctx.bash.resolve({ ...request, owner: callerToken(exec) }))
- return [{ type: 'text', text: `started background task ${task.id}` }]
+ // 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)')
+ }
+ 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')
+ }
+ // Reject pre-start cancellation; returned tasks use their own lifecycle.
+ if (exec.signal?.aborted) throw new Error('command aborted')
+ // Task preflight finishes before the starter can spawn a process.
+ const id = tasks.start({
+ kind: 'bash',
+ label: args.command,
+ ...exec.agent ? { owner: exec.agent } : {},
+ run: () => {
+ const proc = ctx.bash.start(ctx.bash.resolve(request))
+ return {
+ cancel: () => void proc.kill(),
+ done: proc.done.then(() => processOutcome(proc)),
+ readOutput: () => renderProcessRead(proc.readOutput(), proc.sandbox, escalationModes),
+ }
+ },
+ })
+ return [{ type: 'text', text: `started background task ${id}` }]
}
- const result = await ctx.bash.run(ctx.bash.resolve(request))
+ const result = await ctx.bash.run(ctx.bash.resolve({
+ ...request,
+ ...exec.signal ? { signal: exec.signal } : {},
+ }))
if (result.aborted) throw new Error('command aborted')
return [{ type: 'text', text: renderResult(result, escalationModes) }]
},
presentCall: presentBashCall,
presentResult: presentBashResult,
}))
-
- ctx.tools.register(defineTool({
- name: 'bash_output',
- description: 'Read new output from a background bash task started with `bash` + `run_in_background`. '
- + 'Returns only output produced since the previous bash_output call, plus the task status. '
- + 'Tasks keep running while you do other work; poll again later for more output.',
- parameters: {
- task_id: { type: 'string', required: true, description: 'Task id returned by the bash tool.' },
- },
- // execute is synchronous (registry reads + string shaping) but the
- // ToolDefinition contract wants a Promise — hence resolve(), not async.
- execute(args, exec) {
- const id = validateTaskId(args.task_id)
- assertTaskAccess(id, exec)
- const read = ctx.bash.readOutput(id)
- let text = read.delta.length > 0 ? read.delta : '(no new output)'
- if (read.lossy) {
- const paths = [read.stdoutSpillPath, read.stderrSpillPath].filter((p): p is string => p !== undefined)
- const fullOutput = paths.length > 0 ? paths.join(', ') : '(unavailable)'
- text += `\n[some output was dropped from memory; full output: ${fullOutput}]`
- }
- text += `\n${statusLine(read.task)}`
- if (read.task.sandbox?.runnerFailed) {
- // Background settlement carries the runner-failure fact that a
- // foreground call exposes as SANDBOX_UNAVAILABLE.
- text += `\n[sandbox: the sandbox runner itself failed under ${read.task.sandbox.mode} mode — the command did not run; this is a sandbox problem, not a command failure]`
- } else if (read.task.sandbox?.denied) {
- // Mirrors the foreground result marker (and its same-turn escalation hint).
- text += `\n[sandbox: file access denied under ${read.task.sandbox.mode} mode]`
- if (escalationModes.length > 0) {
- text += '\n[sandbox: escalation available — retry this exact command once with sandbox_permissions (the narrowest wider mode that suffices) + justification; the approval prompt asks the user]'
- }
- }
- return Promise.resolve([{ type: 'text', text }])
- },
- presentCall: args => presentTaskCall('Read output from', args),
- }))
-
- ctx.tools.register(defineTool({
- name: 'bash_kill',
- description: 'Ask the executor to kill a running background bash task by task id.',
- parameters: {
- task_id: { type: 'string', required: true, description: 'Task id returned by the bash tool.' },
- },
- execute(args, exec) {
- const id = validateTaskId(args.task_id)
- assertTaskAccess(id, exec)
- const killed = ctx.bash.kill(id)
- return Promise.resolve([{
- type: 'text',
- text: killed ? `killed background task ${id}` : `task ${id} had already finished`,
- }])
- },
- presentCall: args => presentTaskCall('Kill', args),
- }))
}
diff --git a/packages/bash/tool-bash/src/render.ts b/packages/bash/tool-bash/src/render.ts
index 924861bb1e..2ce36af593 100644
--- a/packages/bash/tool-bash/src/render.ts
+++ b/packages/bash/tool-bash/src/render.ts
@@ -4,7 +4,7 @@
* @module @deepseek-ai/dsh-tool-bash/render
*/
-import type { BashRunResult, CollectedOutput } from '@deepseek-ai/dsh-bash'
+import type { BashProcessRead, BashRunResult, BashSandboxInfo, CollectedOutput } from '@deepseek-ai/dsh-bash'
import type { SandboxMode } from '@deepseek-ai/dsh-sandbox'
/** Append the truncation notice (with the full-output spill path) to a stream's text. */
@@ -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}]`)
@@ -69,6 +61,38 @@ export function renderResult(
return body + markers.join('\n')
}
+/**
+ * Shape one background-process read into the `task_output` delta the model
+ * sees: the incremental delta, plus the lossy-read notice (with full-stream
+ * spill paths) when in-memory truncation dropped unread bytes. Empty-delta
+ * rendering (`(no new output)`) is the generic control surface's job.
+ * @param read - one incremental read from the process handle.
+ * @param sandbox - settled sandbox facts, when this was a confined process.
+ * @param escalationModes - escalation targets advertised by this composition.
+ * @returns the delta text with any loss or sandbox notice appended.
+ */
+export function renderProcessRead(
+ read: BashProcessRead,
+ sandbox?: BashSandboxInfo,
+ escalationModes: readonly SandboxMode[] = [],
+): string {
+ const notices: string[] = []
+ if (read.lossy) {
+ const paths = [read.stdoutSpillPath, read.stderrSpillPath].filter((path): path is string => path !== undefined)
+ notices.push(`[some output was dropped from memory; full output: ${paths.length > 0 ? paths.join(', ') : '(unavailable)'}]`)
+ }
+ if (sandbox?.runnerFailed) {
+ notices.push(`[sandbox: the sandbox runner itself failed under ${sandbox.mode} mode — the command did not run; this is a sandbox problem, not a command failure]`)
+ } else if (sandbox?.denied) {
+ notices.push(`[sandbox: file access denied under ${sandbox.mode} mode]`)
+ if (escalationModes.length > 0) {
+ notices.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]')
+ }
+ }
+ if (notices.length === 0) return read.delta
+ return `${read.delta}${read.delta.length > 0 && !read.delta.endsWith('\n') ? '\n' : ''}${notices.join('\n')}`
+}
+
/**
* Recover the structured exit status from a rendered {@link renderResult}
* string — the inverse of the status markers it appends. A killed marker
diff --git a/packages/bash/tool-bash/tests/integration.spec.ts b/packages/bash/tool-bash/tests/integration.spec.ts
index a22e86bd99..238176b8a6 100644
--- a/packages/bash/tool-bash/tests/integration.spec.ts
+++ b/packages/bash/tool-bash/tests/integration.spec.ts
@@ -7,15 +7,17 @@ import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
import ToolRegistry from '@deepseek-ai/dsh-tools'
import AgentRegistry, { AgentId } from '@deepseek-ai/dsh-agent'
import AgentLoop, { ReactLoopAgent } from '@deepseek-ai/dsh-agent-loop'
+import TaskService from '@deepseek-ai/dsh-tasks'
+import * as ToolTasks from '@deepseek-ai/dsh-tool-tasks'
import { LocalBashExecutor } from '@deepseek-ai/dsh-bash-local'
-import { BashTaskId } from '@deepseek-ai/dsh-bash'
import * as ToolBash from '@deepseek-ai/dsh-tool-bash'
import { MockAdapter, textResponse, toolCallResponse } from '../../../core/agent-loop/tests/mock-adapter.ts'
/**
* Full-loop integration: a scripted mock model drives the REAL bash tool
* through the agent loop, exercising the same seams a live model would
- * (tool/call + tool/result session events, agent.inject notifications).
+ * (tool/call + tool/result session events, the generic `ctx.tasks` runtime,
+ * agent.inject completion notices).
*/
async function harness(adapter: MockAdapter) {
const ctx = new Context()
@@ -25,6 +27,8 @@ async function harness(adapter: MockAdapter) {
await ctx.plugin(ToolRegistry)
await ctx.plugin(AgentRegistry)
await ctx.plugin(AgentLoop, { agents: [] })
+ await ctx.plugin(TaskService)
+ await ctx.plugin(ToolTasks)
await ctx.plugin(LocalBashExecutor, { timeoutMs: 10_000 })
await ctx.plugin(ToolBash)
ctx.llm.registerAdapter(['mock'], adapter)
@@ -67,6 +71,16 @@ function resultText(event: SessionEvent): string {
.join('')
}
+/** Poll until `predicate` holds (background settlement races turn end). */
+async function pollUntil(predicate: () => boolean, timeoutMs = 5_000): Promise {
+ const deadline = Date.now() + timeoutMs
+ while (Date.now() < deadline) {
+ if (predicate()) return
+ await new Promise(resolve => setTimeout(resolve, 20))
+ }
+ throw new Error(`condition not met within ${timeoutMs}ms`)
+}
+
describe('bash tool through the agent loop', () => {
it('foreground: model calls bash, sees the result, replies', async () => {
const adapter = new MockAdapter([
@@ -116,46 +130,41 @@ describe('bash tool through the agent loop', () => {
expect(resultText(toolResult)).toContain('[exit code: 9]')
})
- it('background: start → poll → completion notice lands as context/message', async () => {
+ it('background: start ack → completion notice as context/message → task_output collects it', async () => {
+ // The task id is deterministic (a fresh TaskService counts per kind from 1),
+ // so the script can name `bash-1` without threading a generated id.
const adapter = new MockAdapter([
toolCallResponse('call-1', 'bash', { command: 'echo bg-ok', description: 'test command', run_in_background: true }),
- // Each harness owns a fresh BashLocal service, whose first task id is
- // deterministically bash-1. Keep the scripted call faithful to what the
- // model sent; tool arguments are immutable once execution policy begins.
- toolCallResponse('call-2', 'bash_output', { task_id: 'bash-1' }, undefined),
+ textResponse('Started it in the background.'),
+ toolCallResponse('call-2', 'task_output', { task_id: 'bash-1' }),
textResponse('Background task finished.'),
])
- let taskId = ''
-
const ctx = await harness(adapter)
const agent = ctx.agentLoop.create(AgentId('it-bg'), { model: 'mock' })
- // Capture the generated id so the deterministic fixture is checked against
- // the real executor instead of silently assuming it.
- ctx.on('session/event', (_session, event) => {
- if (event.type === 'tool/result' && taskId === '') {
- const match = /task (bash-\d+)/.exec(resultText(event))
- if (match) taskId = match[1]!
- }
- })
agent.send([{ type: 'text', text: 'run echo bg-ok in the background' }])
await waitForIdle(ctx, agent)
- expect(taskId).toBe('bash-1')
+ const firstResult = findEvent(events(agent), 'tool/result')
+ expect(firstResult.data.isError).toBe(false)
+ expect(resultText(firstResult)).toBe('started background task bash-1')
- // Wait for the background task itself (completion may race turn end).
- const task = ctx.bash.get(BashTaskId(taskId))
- if (!task) throw new Error(`task ${taskId} not registered`)
- await task.done
-
- const log = events(agent)
- const firstResult = findEvent(log, 'tool/result')
- expect(resultText(firstResult)).toBe(`started background task ${taskId}`)
-
- const notice = findEvent(log, 'context/message')
+ // The task settles on its own; the tool-tasks notice listener injects a
+ // durable context/message into the owning agent's session (settlement may
+ // race turn end, so poll for it).
+ await pollUntil(() => events(agent).some(event => event.type === 'context/message'))
+ const notice = findEvent(events(agent), 'context/message')
expect(notice.data.content.some(
- block => block.type === 'text' && block.text.includes(`background bash task ${taskId} finished`),
+ block => block.type === 'text' && block.text.includes('background task bash-1 (bash: echo bg-ok) finished'),
)).toBe(true)
- expect(notice.data.source).toEqual({ kind: 'plugin', plugin: 'tool-bash' })
+ expect(notice.data.source).toEqual({ kind: 'plugin', plugin: 'tool-tasks' })
+
+ // The next turn collects the output through the generic task tool.
+ agent.send([{ type: 'text', text: 'collect it' }])
+ await waitForIdle(ctx, agent)
+ const readResult = findEvent(events(agent), 'tool/result', 'last')
+ expect(readResult.data.isError).toBe(false)
+ expect(resultText(readResult)).toContain('bg-ok')
+ expect(resultText(readResult)).toContain('[status: completed, exit code: 0]')
})
})
diff --git a/packages/bash/tool-bash/tests/tools.spec.ts b/packages/bash/tool-bash/tests/tools.spec.ts
index d2cbc643a4..c09c14c459 100644
--- a/packages/bash/tool-bash/tests/tools.spec.ts
+++ b/packages/bash/tool-bash/tests/tools.spec.ts
@@ -1,40 +1,27 @@
-import { chmodSync, mkdirSync, mkdtempSync } from 'node:fs'
+import { mkdtempSync } from 'node:fs'
import { tmpdir } from 'node:os'
import { join } from 'node:path'
import { describe, expect, it, vi } from 'vitest'
import { Context } from 'cordis'
import { CallId } from '@deepseek-ai/dsh-llm'
-import { BashExecutor, BashTaskId, setSandboxMode } from '@deepseek-ai/dsh-bash'
-import type { BashExecRequest, BashExecSpec, BashRunResult, BashTask, BashTaskRead, OwnerToken } from '@deepseek-ai/dsh-bash'
-import { Session, SessionId } from '@deepseek-ai/dsh-session'
+import { BashExecutor } from '@deepseek-ai/dsh-bash'
+import type { BashExecRequest, BashExecSpec, BashProcess, BashProcessRead, BashRunResult } from '@deepseek-ai/dsh-bash'
import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
import ToolRegistry from '@deepseek-ai/dsh-tools'
import AgentRegistry from '@deepseek-ai/dsh-agent'
import type { Agent } from '@deepseek-ai/dsh-agent'
-import { LocalBashExecutor } from '@deepseek-ai/dsh-bash-local'
-import { SandboxBashExecutor } from '@deepseek-ai/dsh-bash-sandbox'
-import { SandboxProvider } from '@deepseek-ai/dsh-sandbox'
-import type { ConfinedArgv } from '@deepseek-ai/dsh-sandbox'
-import { LocalSandboxProvider } from '@deepseek-ai/dsh-sandbox-local'
+import TaskService from '@deepseek-ai/dsh-tasks'
+import * as ToolTasks from '@deepseek-ai/dsh-tool-tasks'
import ApprovalService from '@deepseek-ai/dsh-user-approval'
import type { ApprovalOutcome } from '@deepseek-ai/dsh-user-approval'
+import { LocalBashExecutor } from '@deepseek-ai/dsh-bash-local'
import * as ToolBash from '@deepseek-ai/dsh-tool-bash'
-import { renderResult } from '../src/render.ts'
+import { processOutcome } from '../src/background.ts'
+import { renderProcessRead, renderResult } from '../src/render.ts'
const spillDir = mkdtempSync(join(tmpdir(), 'dsh-tool-bash-spec-'))
-// Pure-config passthrough runner (same knob the snapshot tier uses): skips the
-// profile args up to `--` and execs the command unconfined — deterministic
-// without a host bwrap.
-const PASSTHROUGH_RUNNER = ['bash', '-c', 'while [ "$1" != "--" ]; do shift; done; shift; exec "$@"', 'passthrough-runner']
-const PASSTHROUGH_RUNNER_CONFIG = {
- runnerCommand: PASSTHROUGH_RUNNER,
- // The script has no pre-exec failure path; the provider still requires an
- // explicit dialect so a future script change cannot silently turn runner
- // failure into an ordinary command result.
- runnerFailureSignatures: ['passthrough-runner: profile rejected'],
-}
-
+/** Foreground-only harness: no task runtime (backgrounding fails loud here). */
async function setup() {
const ctx = new Context()
await ctx.plugin(SystemPrompt)
@@ -46,35 +33,40 @@ async function setup() {
return ctx
}
+/** Full harness: the generic task runtime + its control surface, then the bash tool. */
+async function setupWithTasks() {
+ const ctx = new Context()
+ await ctx.plugin(SystemPrompt)
+ await ctx.plugin(ToolRegistry)
+ await ctx.plugin(AgentRegistry)
+ await ctx.plugin(TaskService)
+ await ctx.plugin(ToolTasks)
+ await ctx.plugin(LocalBashExecutor, { timeoutMs: 10_000, graceMs: 200 })
+ ;(ctx.bash as LocalBashExecutor).internals = { spillDir }
+ await ctx.plugin(ToolBash)
+ return ctx
+}
+
/**
- * Build a fake {@link Agent} whose session token is `sessionId`, REGISTER it in
- * `ctx.agents` (the completion-notice path finds the owning agent by scanning
- * the registry for a matching `session.header.id`), and return it. The returned
- * agent is also passed to `execute` as `exec.agent` so it owns the spawned task.
- * The registration disposer is tracked so {@link unregisterFakeAgents} can drop
- * it (simulating the owning session disconnecting before a task completes).
+ * Build a fake {@link Agent} whose session token is `sessionId`, give it a
+ * dedicated lifecycle fiber for `Agent.ctx`, and register it in `ctx.agents`.
+ * The agent id is deliberately different from the session token so a
+ * wrong-field ownership match fails the test.
*/
-const fakeAgentDisposers = new Map Promise | void)[]>()
-function registerFakeAgent(ctx: Context, sessionId: string, inject: (...args: unknown[]) => void): Agent {
- // A config agent has distinct registry (`agent.id`) and owner (`session.header.id`) tokens.
- // Keeping them unequal makes notice lookup by the wrong field fail instead of passing by chance.
- const agent = { id: `agent-${sessionId}`, inject, session: { header: { version: 0, id: sessionId, createdAt: 0 } } } as unknown as Agent
- const dispose = ctx.agents.register(agent)
- const list = fakeAgentDisposers.get(ctx) ?? []
- list.push(dispose)
- fakeAgentDisposers.set(ctx, list)
+function registerFakeAgent(ctx: Context, sessionId: string, inject: (...args: unknown[]) => void = () => {}): Agent {
+ const scopeFiber = ctx.plugin(() => {})
+ const agent = {
+ id: `agent-${sessionId}`,
+ ctx: scopeFiber.ctx,
+ inject,
+ session: { header: { version: 0, id: sessionId, createdAt: 0 } },
+ } as unknown as Agent
+ ctx.agents.register(agent)
return agent
}
-
-/** Unregister every fake agent in this ctx (simulate the owning session disconnecting). */
-function unregisterFakeAgents(ctx: Context): void {
- for (const dispose of fakeAgentDisposers.get(ctx) ?? []) void dispose()
- fakeAgentDisposers.delete(ctx)
-}
-
let callCounter = 0
-function call(ctx: Context, name: string, args: unknown) {
- return ctx.tools.execute({ callId: CallId(`call-${++callCounter}`), name, arguments: args })
+function call(ctx: Context, name: string, args: unknown, agent?: Agent) {
+ return ctx.tools.execute({ callId: CallId(`call-${++callCounter}`), name, arguments: args, ...agent ? { agent } : {} })
}
function text(result: { content: { type: string; text?: string }[] }): string {
@@ -98,56 +90,103 @@ async function callUntilText(
throw new Error(`${name} output did not include ${JSON.stringify(expected)}; last text was ${JSON.stringify(last !== undefined ? text(last) : '')}`)
}
-abstract class TestBashExecutor extends BashExecutor {
+class RecordingSandboxExecutor extends BashExecutor {
+ readonly modes: Array = []
+
+ override get sandboxMode() {
+ return 'read-only' as const
+ }
+
resolve(request: BashExecRequest): BashExecSpec {
return {
command: request.command,
workdir: request.workdir ?? process.cwd(),
- timeoutMs: request.timeoutMs ?? 0,
+ timeoutMs: request.timeoutMs ?? 1000,
...request.signal ? { signal: request.signal } : {},
- owner: request.owner,
- sandboxMode: request.sandboxMode,
+ sandboxMode: request.sandboxMode ?? 'read-only',
+ }
+ }
+
+ run(spec: BashExecSpec): Promise {
+ this.modes.push(spec.sandboxMode)
+ return Promise.resolve({
+ exitCode: 0,
+ signal: null,
+ timedOut: false,
+ aborted: false,
+ timeoutMs: spec.timeoutMs,
+ stdout: { text: 'ok', truncated: false },
+ stderr: { text: '', truncated: false },
+ sandbox: { mode: spec.sandboxMode ?? 'read-only', denied: false },
+ })
+ }
+
+ start(spec: BashExecSpec): BashProcess {
+ this.modes.push(spec.sandboxMode)
+ return {
+ status: 'completed',
+ exitCode: 0,
+ signal: null,
+ done: Promise.resolve(),
+ sandbox: { mode: spec.sandboxMode ?? 'read-only', denied: false },
+ readOutput: () => ({ delta: '', lossy: false }),
+ kill: () => false,
}
}
}
-class LossyReadBashExecutor extends TestBashExecutor {
- private readonly task: BashTask = {
- id: BashTaskId('bash-lossy'),
- status: 'running',
- exitCode: null,
- signal: null,
- done: Promise.resolve(),
+/** Test executor that records whether the background start boundary was crossed. */
+class CountingStartExecutor extends BashExecutor {
+ starts = 0
+
+ resolve(request: BashExecRequest): BashExecSpec {
+ return { command: request.command, workdir: request.workdir ?? '/x', timeoutMs: request.timeoutMs ?? 0, sandboxMode: request.sandboxMode }
}
- run(): Promise {
- return Promise.reject(new Error('not used'))
- }
+ run(): Promise { return Promise.reject(new Error('unused')) }
- start(): BashTask {
- return this.task
+ start(): BashProcess {
+ this.starts += 1
+ return {
+ status: 'completed',
+ exitCode: 0,
+ signal: null,
+ done: Promise.resolve(),
+ readOutput: () => ({ delta: '', lossy: false }),
+ kill: () => false,
+ }
}
+}
- get(id: BashTaskId): BashTask | undefined {
- return id === this.task.id ? this.task : undefined
- }
+async function setupSandboxed(withApproval = false) {
+ const ctx = new Context()
+ await ctx.plugin(SystemPrompt)
+ await ctx.plugin(ToolRegistry)
+ await ctx.plugin(AgentRegistry)
+ await ctx.plugin(TaskService)
+ await ctx.plugin(ToolTasks)
+ await ctx.plugin(RecordingSandboxExecutor)
+ if (withApproval) await ctx.plugin(ApprovalService)
+ await ctx.plugin(ToolBash)
+ return { ctx, bash: ctx.bash as RecordingSandboxExecutor }
+}
- ownerOf(): OwnerToken | undefined {
- return undefined
- }
-
- list(): BashTask[] {
- return [this.task]
- }
-
- readOutput(id: BashTaskId): BashTaskRead {
- if (id !== this.task.id) throw new Error(`unknown bash task "${id}"`)
- return { task: this.task, delta: 'tail', lossy: true }
- }
-
- kill(): boolean {
- return false
- }
+function sandboxAgent(mode?: 'read-only' | 'workspace-write' | 'danger-full-access', ctx?: Context): Agent {
+ const events: Array<{ type: string; data?: Record }> = [{ type: 'turn/start' }]
+ if (mode !== undefined) events.push({ type: 'bash/sandbox-mode', data: { mode } })
+ return {
+ id: 'sandbox-agent',
+ ...ctx === undefined ? {} : { ctx: ctx.plugin(() => {}).ctx },
+ session: {
+ header: { version: 0, id: 'sandbox-session', createdAt: 0 },
+ events,
+ append: (type: string, data: Record) => {
+ const event = { type, data }
+ events.push(event)
+ return event
+ },
+ },
+ } as unknown as Agent
}
describe('bash tool', () => {
@@ -222,7 +261,7 @@ describe('bash tool', () => {
expect(text(result)).toMatch(/ENOENT/)
})
- it('surfaces aborts as isError', async () => {
+ it('surfaces foreground aborts as isError', async () => {
const ctx = await setup()
const controller = new AbortController()
const pending = ctx.tools.execute({
@@ -237,7 +276,7 @@ describe('bash tool', () => {
expect(text(result)).toMatch(/aborted/)
})
- // Type and required-key violations are now rejected by the harness
+ // Type and required-key violations are rejected by the harness
// (defineTool validates against the SchemaSpec — the arg-validation RFC) before execute.
it.each([
[{}, /missing required property "command"/],
@@ -275,15 +314,18 @@ describe('bash tool', () => {
expect(text(result)).toContain('tool execution arguments must be losslessly JSON-serializable')
})
- it('registers all three schemas in the system prompt assembly', async () => {
+ it('registers the bash schema with run_in_background exposed by default', async () => {
const ctx = await setup()
- const names = ctx.tools.schemas().map(schema => schema.name)
- expect(names).toEqual(['bash', 'bash_output', 'bash_kill'])
- const bashSchema = ctx.tools.schemas()[0]!
+ const schemas = ctx.tools.schemas()
+ expect(schemas.map(schema => schema.name)).toEqual(['bash'])
+ const bashSchema = schemas[0]!
expect(bashSchema.parameters).toMatchObject({
type: 'object',
required: ['command', 'description'],
})
+ expect(Object.keys(bashSchema.parameters.properties as Record))
+ .toContain('run_in_background')
+ expect(bashSchema.description).toContain('task_output')
})
it('contributes the exit-code habit as its prompt section (guidance the descriptions cannot carry)', async () => {
@@ -308,7 +350,7 @@ describe('bash tool', () => {
await ctx.plugin(ToolRegistry)
await ctx.plugin(LocalBashExecutor, {})
const fiber = await ctx.plugin(ToolBash)
- expect(ctx.tools.schemas()).toHaveLength(3)
+ expect(ctx.tools.schemas()).toHaveLength(1)
expect((await ctx.systemPrompt.assemble()).sections.map(s => s.name)).toEqual(['harness:identity', 'deployment:persona', 'tool:bash'])
await fiber.dispose()
expect(ctx.tools.schemas()).toHaveLength(0)
@@ -325,338 +367,352 @@ describe('bash tool', () => {
expect(ctx.tools.schemas()).toHaveLength(0)
await ctx.plugin(LocalBashExecutor, {})
await new Promise(resolve => setTimeout(resolve, 0))
- expect(ctx.tools.schemas()).toHaveLength(3)
+ expect(ctx.tools.schemas()).toHaveLength(1)
+ })
+
+ it('applies the built-in background default when apply() receives a bare config', async () => {
+ // Bypasses the schemastery defaults on purpose: apply() must stand on its
+ // own `?? true` fallback when embedded programmatically without the schema.
+ const ctx = new Context()
+ await ctx.plugin(SystemPrompt)
+ await ctx.plugin(ToolRegistry)
+ await ctx.plugin(LocalBashExecutor, {})
+ ToolBash.apply(ctx, {})
+ const schema = ctx.tools.schemas()[0]!
+ expect(Object.keys(schema.parameters.properties as Record))
+ .toContain('run_in_background')
})
})
-describe('background tools', () => {
- it('bash with run_in_background returns a task id immediately', async () => {
- const ctx = await setup()
- const result = await call(ctx, 'bash', { command: 'sleep 0.2; echo bg-done', description: 'test command', run_in_background: true })
- expect(result.isError).toBe(false)
- expect(text(result)).toMatch(/^started background task bash-\d+$/)
+describe('background execution through the task runtime', () => {
+ it('run_in_background acks with the task id, readable through the REAL task_output tool', async () => {
+ const ctx = await setupWithTasks()
+ const started = await call(ctx, 'bash', { command: 'echo bg-ok', description: 'test command', run_in_background: true })
+ expect(started.isError).toBe(false)
+ expect(text(started)).toBe('started background task bash-1')
+
+ const read = await callUntilText(ctx, 'task_output', { task_id: 'bash-1' }, 'bg-ok')
+ expect(text(read)).toContain('bg-ok')
+ // A later read reports the terminal outcome in the generic status line.
+ const final = await callUntilText(ctx, 'task_output', { task_id: 'bash-1' }, '[status: completed, exit code: 0]')
+ expect(final.isError).toBe(false)
})
- it('bash_output polls incrementally and reports status', async () => {
- const ctx = await setup()
- const started = await call(ctx, 'bash', { command: 'echo first; sleep 1; echo second', description: 'test command', run_in_background: true })
- const id = BashTaskId(/task (bash-\d+)/.exec(text(started))![1]!)
+ it('a running background task is killable through the REAL task_kill tool', async () => {
+ const ctx = await setupWithTasks()
+ await call(ctx, 'bash', { command: 'sleep 60', description: 'test command', run_in_background: true })
- const first = await callUntilText(ctx, 'bash_output', { task_id: id }, 'first')
- expect(text(first)).toContain('first')
- expect(text(first)).toContain('[status: running]')
-
- await ctx.bash.get(id)!.done
- const second = await call(ctx, 'bash_output', { task_id: id })
- expect(text(second)).toContain('second')
- expect(text(second)).not.toContain('first')
- expect(text(second)).toContain('[status: completed, exit code: 0]')
-
- const third = await call(ctx, 'bash_output', { task_id: id })
- expect(text(third)).toContain('(no new output)')
+ const killed = await call(ctx, 'task_kill', { task_id: 'bash-1' })
+ expect(text(killed)).toBe('requested cancellation of task bash-1')
+ // The cancel reached the process handle; the task settles as killed with
+ // the signal detail mapped by processOutcome.
+ const final = await call(ctx, 'task_output', { task_id: 'bash-1', wait: true })
+ expect(text(final)).toContain('[status: killed, signal: SIGTERM]')
})
- it('bash_output flags lossy reads with spill paths', async () => {
- const ctx = new Context()
- await ctx.plugin(SystemPrompt)
- await ctx.plugin(ToolRegistry)
- await ctx.plugin(LocalBashExecutor, { maxOutputBytes: 100, graceMs: 200 })
- ;(ctx.bash as LocalBashExecutor).internals = { spillDir }
- await ctx.plugin(ToolBash)
+ it('a self-signal background exit is reported as killed through the REAL task_output tool', async () => {
+ const ctx = await setupWithTasks()
+ await call(ctx, 'bash', { command: 'kill -TERM $$', description: 'test command', run_in_background: true })
- const started = await call(ctx, 'bash', { command: 'for i in $(seq 1 200); do printf "line-%04d\\n" $i; done', description: 'test command', run_in_background: true })
- const id = BashTaskId(/task (bash-\d+)/.exec(text(started))![1]!)
- await ctx.bash.get(id)!.done
- const read = await call(ctx, 'bash_output', { task_id: id })
- expect(text(read)).toContain('[some output was dropped from memory; full output: ')
+ const final = await call(ctx, 'task_output', { task_id: 'bash-1', wait: true })
+ expect(text(final)).toContain('[status: killed, signal: SIGTERM]')
})
- it('bash_output reports unavailable when a lossy read has no safe spill path', async () => {
- const ctx = new Context()
- await ctx.plugin(SystemPrompt)
- await ctx.plugin(ToolRegistry)
- await ctx.plugin(LossyReadBashExecutor)
- await ctx.plugin(ToolBash)
+ it('a background task started by an agent is registered with that agent as owner', async () => {
+ // 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)
+ expect(text(started)).toBe('started background task bash-1')
- const read = await call(ctx, 'bash_output', { task_id: 'bash-lossy' })
- expect(text(read)).toBe('tail\n[some output was dropped from memory; full output: (unavailable)]\n[status: running]')
+ const anon = await call(ctx, 'task_output', { task_id: 'bash-1' })
+ expect(anon.isError).toBe(true)
+ expect(text(anon)).toMatch(/belongs to another session/)
+
+ const killed = await call(ctx, 'task_kill', { task_id: 'bash-1' }, agent)
+ expect(killed.isError).toBe(false)
+ await call(ctx, 'task_output', { task_id: 'bash-1', wait: true }, agent) // await settlement — no orphan
})
- it('bash_kill stops a running task; repeat reports already-finished', async () => {
- const ctx = await setup()
- const started = await call(ctx, 'bash', { command: 'sleep 60', description: 'test command', run_in_background: true })
- const id = BashTaskId(/task (bash-\d+)/.exec(text(started))![1]!)
-
- const killed = await call(ctx, 'bash_kill', { task_id: id })
- expect(text(killed)).toBe(`killed background task ${id}`)
- await ctx.bash.get(id)!.done
-
- const again = await call(ctx, 'bash_kill', { task_id: id })
- expect(text(again)).toBe(`task ${id} had already finished`)
-
- const status = await call(ctx, 'bash_output', { task_id: id })
- expect(text(status)).toContain('[status: killed by SIGTERM]')
- })
-
- it('unknown task ids are isError for both tools', async () => {
- const ctx = await setup()
- const read = await call(ctx, 'bash_output', { task_id: 'bash-999' })
- expect(read.isError).toBe(true)
- expect(text(read)).toMatch(/unknown bash task/)
- const kill = await call(ctx, 'bash_kill', { task_id: 'bash-999' })
- expect(kill.isError).toBe(true)
- })
-
- it.each([
- ['bash_output', {}, /missing required property "task_id"/],
- ['bash_output', { task_id: 9 }, /"task_id" must be a string/],
- ['bash_kill', { task_id: '' }, /invalid task_id/],
- ])('%s rejects invalid task_id %j', async (tool, args, pattern) => {
- const ctx = await setup()
- const result = await call(ctx, tool, args)
+ it('fails loud when the task runtime is not loaded', async () => {
+ const ctx = await setup() // no TaskService / ToolTasks
+ const result = await call(ctx, 'bash', { command: 'sleep 60', description: 'test command', run_in_background: true })
expect(result.isError).toBe(true)
- expect(text(result)).toMatch(pattern)
+ expect(text(result)).toContain('background tasks unavailable: load @deepseek-ai/dsh-tasks and @deepseek-ai/dsh-tool-tasks')
})
- it('injects a completion notice into the owning agent (found via the registry by session token)', async () => {
- const ctx = await setup()
- const inject = vi.fn()
- // Notices look up the agent in ctx.agents by session token, so passing it to execute is not
- // enough: the fake must be registered with a matching `session.header.id`.
- const agent = registerFakeAgent(ctx, 'bg', inject)
+ it('a pre-aborted call refuses to start: isError, no process spawned', async () => {
+ const ctx = new Context()
+ await ctx.plugin(SystemPrompt)
+ await ctx.plugin(ToolRegistry)
+ await ctx.plugin(AgentRegistry)
+ await ctx.plugin(TaskService)
+ await ctx.plugin(ToolTasks)
+ await ctx.plugin(CountingStartExecutor)
+ await ctx.plugin(ToolBash)
- const started = await ctx.tools.execute({
- callId: CallId('call-bg'),
+ const controller = new AbortController()
+ controller.abort()
+ const result = await ctx.tools.execute({
+ callId: CallId('call-pre-aborted'),
name: 'bash',
- arguments: { command: 'true', description: 'test command', run_in_background: true },
- agent,
+ arguments: { command: 'sleep 60', description: 'test command', run_in_background: true },
+ signal: controller.signal,
})
- const id = BashTaskId(/task (bash-\d+)/.exec(text(started))![1]!)
- await ctx.bash.get(id)!.done
-
- expect(inject).toHaveBeenCalledTimes(1)
- const [content, options] = inject.mock.calls[0] as [
- { type: string; text: string }[],
- { source: { kind: string; plugin: string } },
- ]
- expect(content[0]!.text).toContain(`background bash task ${id} finished`)
- expect(content[0]!.text).toContain('bash_output')
- expect(options.source).toEqual({ kind: 'plugin', plugin: 'tool-bash' })
+ expect(result.isError).toBe(true)
+ expect(text(result)).toContain('command aborted')
+ expect((ctx.bash as CountingStartExecutor).starts).toBe(0)
})
- it('swallows ONLY the disposed-agent inject error', async () => {
- const ctx = await setup()
- const agent = registerFakeAgent(ctx, 'bg', () => { throw new Error('agent "x" is disposed') })
+ it('never spawns the process when tasks.start preflight throws (no orphan, by construction)', async () => {
+ // With no control surface, task preflight fails before the executor can spawn.
+ const ctx = new Context()
+ await ctx.plugin(SystemPrompt)
+ await ctx.plugin(ToolRegistry)
+ await ctx.plugin(AgentRegistry)
+ await ctx.plugin(TaskService)
+ await ctx.plugin(CountingStartExecutor)
+ await ctx.plugin(ToolBash)
- const started = await ctx.tools.execute({
- callId: CallId('call-bg2'),
- name: 'bash',
- arguments: { command: 'true', description: 'test command', run_in_background: true },
- agent,
- })
- const id = BashTaskId(/task (bash-\d+)/.exec(text(started))![1]!)
- await expect(ctx.bash.get(id)!.done).resolves.toBeUndefined()
+ const result = await call(ctx, 'bash', { command: 'sleep 60', description: 'test command', run_in_background: true })
+ expect(result.isError).toBe(true)
+ expect(text(result)).toContain('no control surface is attached')
+ // Declare-then-execute: the failed preflight means no process ever ran.
+ expect((ctx.bash as CountingStartExecutor).starts).toBe(0)
})
- it('rethrows a non-disposed inject failure (not blindly swallowed)', async () => {
- const ctx = await setup()
- // A real bug in inject (not the benign disposed race) must surface — the
- // base-class notifier contains it (logs, does not reject task.done), but
- // the listener itself must have thrown rather than silently eaten it.
- const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => undefined)
- try {
- const agent = registerFakeAgent(ctx, 'bg', () => { throw new Error('unexpected inject bug') })
+ it('enableRunInBackground: false removes the parameter and flips the description', async () => {
+ const ctx = new Context()
+ await ctx.plugin(SystemPrompt)
+ await ctx.plugin(ToolRegistry)
+ await ctx.plugin(LocalBashExecutor, {})
+ await ctx.plugin(ToolBash, { enableRunInBackground: false })
- const started = await ctx.tools.execute({
- callId: CallId('call-bg3'),
- name: 'bash',
- arguments: { command: 'true', description: 'test command', run_in_background: true },
- agent,
- })
- const id = BashTaskId(/task (bash-\d+)/.exec(text(started))![1]!)
- await ctx.bash.get(id)!.done
- // notifyTaskDone caught and logged the rethrown error.
- expect(errorSpy).toHaveBeenCalled()
- const logged = errorSpy.mock.calls.flat().some(arg => arg instanceof Error && arg.message === 'unexpected inject bug')
- expect(logged).toBe(true)
- } finally {
- errorSpy.mockRestore()
+ const schema = ctx.tools.schemas().find(s => s.name === 'bash')!
+ expect(Object.keys(schema.parameters.properties as Record))
+ .toEqual(['command', 'description', 'timeoutMs', 'workdir'])
+ expect(schema.description).toContain('Background execution is not available')
+ expect(schema.description).not.toContain('run_in_background')
+ // The registry-held definition agrees (schema and capability never disagree).
+ const parameters = ctx.tools.get('bash')!.parameters as { properties: Record }
+ expect('run_in_background' in parameters.properties).toBe(false)
+
+ // 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')
+ const foreground = await call(ctx, 'bash', { command: 'echo hi', description: 'test command' })
+ expect(foreground.isError).toBe(false)
+ })
+})
+
+describe('sandbox escalation through the generic task producer', () => {
+ const escalate = {
+ command: 'true',
+ description: 'test escalation',
+ sandbox_permissions: 'workspace-write',
+ justification: 'the command needs workspace writes',
+ }
+
+ it('advertises the sandbox fields and validates their pairing', async () => {
+ const { ctx } = await setupSandboxed()
+ const schema = ctx.tools.schemas().find(item => item.name === 'bash')!
+ const properties = schema.parameters.properties as Record
+ expect(properties['sandbox_permissions']?.enum).toEqual(['workspace-write', 'danger-full-access'])
+ expect(schema.description).toContain('approval prompt')
+
+ for (const args of [
+ { command: 'true', description: 'd', sandbox_permissions: 'workspace-write' },
+ { command: 'true', description: 'd', justification: 'why' },
+ { command: 'true', description: 'd', sandbox_permissions: 'workspace-write', justification: ' ' },
+ ]) {
+ expect((await call(ctx, 'bash', args)).isError).toBe(true)
}
})
- it('drops the notice cleanly when the owning agent is gone from the registry by completion', async () => {
- // Host-scoped bash tasks can outlive a per-session agent after an ACP disconnect. The task
- // retains its owner token, but with no matching live agent the notice is dropped without error.
- const ctx = await setup()
- const inject = vi.fn()
- const agent = registerFakeAgent(ctx, 'bg', inject)
- const started = await ctx.tools.execute({
- callId: CallId('call-bg4'),
- name: 'bash',
- arguments: { command: 'true', description: 'test command', run_in_background: true },
- agent,
+ it('rejects injected escalation without a sandbox and non-widening escalation without prompting', async () => {
+ const plain = await setup()
+ expect(text(await call(plain, 'bash', escalate))).toContain('not available in this composition')
+
+ const { ctx } = await setupSandboxed(true)
+ const prompted = vi.fn()
+ ctx.on('approval/request', () => { prompted(); return Promise.resolve('allowed-once') })
+ const result = await call(ctx, 'bash', { ...escalate, sandbox_permissions: 'workspace-write' }, sandboxAgent('workspace-write'))
+ expect(text(result)).toContain('not strictly wider')
+ expect(prompted).not.toHaveBeenCalled()
+
+ const malformed = sandboxAgent()
+ ;(malformed.session.events as unknown as Array<{ type: string; data: { mode: string } }>).push({
+ type: 'bash/sandbox-mode',
+ data: { mode: 'unknown-mode' },
})
- const id = BashTaskId(/task (bash-\d+)/.exec(text(started))![1]!)
- // Unregister the agent BEFORE the task completes (simulate disconnect).
- unregisterFakeAgents(ctx)
- await expect(ctx.bash.get(id)!.done).resolves.toBeUndefined()
- expect(inject).not.toHaveBeenCalled()
+ expect(text(await call(ctx, 'bash', escalate, malformed))).toContain('not strictly wider')
})
- it('does not notify when no agent owned the task', async () => {
- const ctx = await setup()
- const started = await call(ctx, 'bash', { command: 'true', description: 'test command', run_in_background: true })
- const id = BashTaskId(/task (bash-\d+)/.exec(text(started))![1]!)
- await expect(ctx.bash.get(id)!.done).resolves.toBeUndefined()
+ it('fails closed when approval cannot be routed', async () => {
+ const withoutService = await setupSandboxed()
+ expect(text(await call(withoutService.ctx, 'bash', escalate, sandboxAgent()))).toContain('no approval service')
+
+ const withService = await setupSandboxed(true)
+ expect(text(await call(withService.ctx, 'bash', escalate))).toContain('no agent to route')
+ expect(text(await call(withService.ctx, 'bash', escalate, sandboxAgent()))).toContain('no approval channel')
+ })
+
+ it.each([
+ ['rejected', 'user rejected'],
+ ['cancelled', 'was cancelled'],
+ ] as const)('maps an approval %s to its distinct failure', async (outcome, message) => {
+ const { ctx, bash } = await setupSandboxed(true)
+ ctx.on('approval/request', () => Promise.resolve(outcome))
+ const result = await call(ctx, 'bash', escalate, sandboxAgent())
+ expect(text(result)).toContain(message)
+ expect(bash.modes).toEqual([])
+ })
+
+ it('runs a granted foreground or background call under the approved mode', async () => {
+ const { ctx, bash } = await setupSandboxed(true)
+ ctx.on('approval/request', () => Promise.resolve('allowed-once'))
+ const agent = sandboxAgent(undefined, ctx)
+ ctx.agents.register(agent)
+ const foreground = await ctx.tools.execute({
+ callId: CallId('sandbox-signal'),
+ name: 'bash',
+ arguments: escalate,
+ agent,
+ signal: new AbortController().signal,
+ })
+ expect(foreground.isError).toBe(false)
+ const background = await call(ctx, 'bash', { ...escalate, run_in_background: true }, agent)
+ expect(text(background)).toBe('started background task bash-1')
+ expect(bash.modes).toEqual(['workspace-write', 'workspace-write'])
+ })
+
+ it('uses the session override for ordinary calls and evaluates widening against it', async () => {
+ const { ctx, bash } = await setupSandboxed(true)
+ const agent = sandboxAgent('workspace-write')
+ await call(ctx, 'bash', { command: 'true', description: 'ordinary' }, agent)
+ ctx.on('approval/request', () => Promise.resolve('allowed-once'))
+ await call(ctx, 'bash', { ...escalate, sandbox_permissions: 'danger-full-access' }, agent)
+ expect(bash.modes).toEqual(['workspace-write', 'danger-full-access'])
+ })
+
+ it('keeps the exhaustiveness backstop for a rogue approval implementation', async () => {
+ const { ctx } = await setupSandboxed(true)
+ ctx.approval.request = () => Promise.resolve('rogue' as ApprovalOutcome)
+ const result = await call(ctx, 'bash', escalate, sandboxAgent())
+ expect(text(result)).toContain('unreachable variant in ApprovalOutcome')
})
})
-describe('background task ownership (cross-session isolation)', () => {
- /** Run a tool on behalf of a specific agent (sets exec.agent). */
- function callAs(ctx: Context, agent: import('@deepseek-ai/dsh-agent').Agent | undefined, name: string, args: unknown) {
- return ctx.tools.execute({ callId: CallId(`own-${++callCounter}`), name, arguments: args, ...agent ? { agent } : {} })
+describe('renderProcessRead', () => {
+ const base: BashProcessRead = { delta: 'out\n', lossy: false }
+
+ it('returns the delta verbatim for a lossless read', () => {
+ expect(renderProcessRead(base)).toBe('out\n')
+ expect(renderProcessRead({ delta: '', lossy: false })).toBe('')
+ })
+
+ it('appends the loss notice with the available spill paths', () => {
+ expect(renderProcessRead({ ...base, lossy: true, stdoutSpillPath: '/spill/out.log' }))
+ .toBe('out\n[some output was dropped from memory; full output: /spill/out.log]')
+ expect(renderProcessRead({ ...base, lossy: true, stdoutSpillPath: '/spill/out.log', stderrSpillPath: '/spill/err.log' }))
+ .toBe('out\n[some output was dropped from memory; full output: /spill/out.log, /spill/err.log]')
+ })
+
+ it('reports (unavailable) when a lossy read has no safe spill path', () => {
+ expect(renderProcessRead({ ...base, lossy: true }))
+ .toBe('out\n[some output was dropped from memory; full output: (unavailable)]')
+ })
+
+ it('an empty lossy delta is the notice alone', () => {
+ expect(renderProcessRead({ delta: '', lossy: true, stderrSpillPath: '/spill/err.log' }))
+ .toBe('[some output was dropped from memory; full output: /spill/err.log]')
+ })
+
+ it('inserts the separating newline only when the delta lacks one', () => {
+ expect(renderProcessRead({ delta: 'tail', lossy: true }))
+ .toBe('tail\n[some output was dropped from memory; full output: (unavailable)]')
+ expect(renderProcessRead({ delta: 'tail\n', lossy: true }))
+ .toBe('tail\n[some output was dropped from memory; full output: (unavailable)]')
+ })
+
+ it('appends settled sandbox denial and runner-failure facts', () => {
+ expect(renderProcessRead(base, { mode: 'read-only', denied: true }, ['workspace-write']))
+ .toContain('[sandbox: escalation available')
+ expect(renderProcessRead({ delta: 'tail', lossy: false }, { mode: 'read-only', denied: true }))
+ .toBe('tail\n[sandbox: file access denied under read-only mode]')
+ const runner = renderProcessRead(
+ { delta: '', lossy: false },
+ { mode: 'workspace-write', denied: true, runnerFailed: true },
+ ['danger-full-access'],
+ )
+ expect(runner).toContain('sandbox runner itself failed under workspace-write mode')
+ expect(runner).not.toContain('file access denied')
+ })
+})
+
+describe('processOutcome', () => {
+ function settled(over: Partial): BashProcess {
+ return {
+ status: 'completed',
+ exitCode: 0,
+ signal: null,
+ done: Promise.resolve(),
+ readOutput: () => ({ delta: '', lossy: false }),
+ kill: () => false,
+ ...over,
+ }
}
- // Ownership uses `session.header.id`, not object identity. Distinct ids keep the isolation tests
- // from passing accidentally because every fake produced the same owner token.
- const fakeAgent = (sessionId: string) =>
- ({ inject: () => undefined, session: { header: { version: 0, id: sessionId, createdAt: 0 } } }) as unknown as import('@deepseek-ai/dsh-agent').Agent
- it('rejects bash_output/bash_kill for a task owned by a DIFFERENT session token', async () => {
- const ctx = await setup()
- const a = fakeAgent('sess-a')
- const b = fakeAgent('sess-b')
- // Agent A starts a long-running background task.
- const started = await callAs(ctx, a, 'bash', { command: 'sleep 60', description: 'bg', run_in_background: true })
- const id = BashTaskId(/task (bash-\d+)/.exec(text(started))![1]!)
-
- // Agent B (a different session token) cannot read or kill A's task.
- const readByB = await callAs(ctx, b, 'bash_output', { task_id: id })
- expect(readByB.isError).toBe(true)
- expect(text(readByB)).toMatch(/belongs to another session/)
- const killByB = await callAs(ctx, b, 'bash_kill', { task_id: id })
- expect(killByB.isError).toBe(true)
- expect(text(killByB)).toMatch(/belongs to another session/)
-
- // The task is still running (B's kill did nothing) — A can still kill it.
- const killByA = await callAs(ctx, a, 'bash_kill', { task_id: id })
- expect(killByA.isError).toBe(false)
- expect(text(killByA)).toBe(`killed background task ${id}`)
+ it('maps a signal-killed process to killed with the signal detail', () => {
+ expect(processOutcome(settled({ status: 'killed', signal: 'SIGTERM' })))
+ .toEqual({ status: 'killed', detail: 'signal: SIGTERM' })
})
- it('a DIFFERENT Agent object with the SAME session token may access the task (ownership is by token, not object identity)', async () => {
- // Ownership fences by session.header.id, NOT Agent object identity. Two
- // distinct Agent objects sharing one session token (e.g. an agent re-created
- // on the same session) are the SAME owner.
- const ctx = await setup()
- const a1 = fakeAgent('sess-shared')
- const a2 = fakeAgent('sess-shared') // distinct object, same token
- const started = await callAs(ctx, a1, 'bash', { command: 'sleep 60', description: 'bg', run_in_background: true })
- const id = BashTaskId(/task (bash-\d+)/.exec(text(started))![1]!)
- const readByA2 = await callAs(ctx, a2, 'bash_output', { task_id: id })
- expect(readByA2.isError).toBe(false)
- await callAs(ctx, a1, 'bash_kill', { task_id: id }) // cleanup
+ it('maps a killed process without a recorded signal (kill raced exit / spawn failure)', () => {
+ expect(processOutcome(settled({ status: 'killed', exitCode: null })))
+ .toEqual({ status: 'killed', detail: 'killed before exit' })
})
- it('the no-agent (non-loop) caller cannot access an owned task', async () => {
- const ctx = await setup()
- const a = fakeAgent('sess-a')
- const started = await callAs(ctx, a, 'bash', { command: 'sleep 60', description: 'bg', run_in_background: true })
- const id = BashTaskId(/task (bash-\d+)/.exec(text(started))![1]!)
- // A call with no exec.agent has no token → cannot prove ownership of an owned task.
- const read = await callAs(ctx, undefined, 'bash_output', { task_id: id })
- expect(read.isError).toBe(true)
- expect(text(read)).toMatch(/belongs to another session/)
- await callAs(ctx, a, 'bash_kill', { task_id: id }) // cleanup
+ it('maps a completed process to its exit code', () => {
+ expect(processOutcome(settled({ exitCode: 3 })))
+ .toEqual({ status: 'completed', detail: 'exit code: 3' })
})
- it('an UNOWNED task (started with no agent) is accessible to anyone', async () => {
- const ctx = await setup()
- // Started by a non-loop caller (no exec.agent) → no owner token recorded.
- const started = await callAs(ctx, undefined, 'bash', { command: 'sleep 60', description: 'bg', run_in_background: true })
- const id = BashTaskId(/task (bash-\d+)/.exec(text(started))![1]!)
- // Any agent (and the no-agent caller) may read/kill it.
- const read = await callAs(ctx, fakeAgent('sess-x'), 'bash_output', { task_id: id })
- expect(read.isError).toBe(false)
- const killed = await callAs(ctx, undefined, 'bash_kill', { task_id: id })
- expect(killed.isError).toBe(false)
- })
-
- it('the owner can still access its task AFTER it completes (owner token persists on the task)', async () => {
- const ctx = await setup()
- const a = fakeAgent('sess-a')
- const b = fakeAgent('sess-b')
- const started = await callAs(ctx, a, 'bash', { command: 'echo done', description: 'bg', run_in_background: true })
- const id = BashTaskId(/task (bash-\d+)/.exec(text(started))![1]!)
- await ctx.bash.get(id)!.done
- // Completion does NOT clear ownership: B is still rejected, A still allowed.
- const readByB = await callAs(ctx, b, 'bash_output', { task_id: id })
- expect(readByB.isError).toBe(true)
- expect(text(readByB)).toMatch(/belongs to another session/)
- const readByA = await callAs(ctx, a, 'bash_output', { task_id: id })
- expect(readByA.isError).toBe(false)
- })
-
- it('ownership SURVIVES an independent tool-bash HMR reload (token lives on the executor)', async () => {
- // The executor task owns the token, so reloading only tool-bash preserves ownership. A
- // plugin-local map would lose it and incorrectly expose the task to agent B.
- const ctx = new Context()
- await ctx.plugin(SystemPrompt)
- await ctx.plugin(ToolRegistry)
- await ctx.plugin(LocalBashExecutor, { timeoutMs: 10_000, graceMs: 200 })
- ;(ctx.bash as LocalBashExecutor).internals = { spillDir }
- const fiber = await ctx.plugin(ToolBash)
-
- const a = fakeAgent('sess-a')
- const b = fakeAgent('sess-b')
- const started = await callAs(ctx, a, 'bash', { command: 'sleep 60', description: 'bg', run_in_background: true })
- const id = BashTaskId(/task (bash-\d+)/.exec(text(started))![1]!)
- // Before reload: B is rejected (A owns it).
- expect((await callAs(ctx, b, 'bash_output', { task_id: id })).isError).toBe(true)
-
- // Reload ONLY tool-bash; the executor and its running task (with its owner
- // token) survive.
- await fiber.dispose()
- await ctx.plugin(ToolBash)
- expect(ctx.bash.get(id)?.status).toBe('running')
- expect(ctx.bash.ownerOf(id)).toBe('sess-a')
-
- // After reload, ownership is INTACT → B is STILL rejected.
- expect((await callAs(ctx, b, 'bash_output', { task_id: id })).isError).toBe(true)
- await callAs(ctx, a, 'bash_kill', { task_id: id }) // cleanup
+ it('defensively reads a null exit code as 0 (handle shapes from other executors)', () => {
+ expect(processOutcome(settled({ exitCode: null })))
+ .toEqual({ status: 'completed', detail: 'exit code: 0' })
})
})
describe('session-cwd routing (per-session workdir)', () => {
- function callAs(ctx: Context, agent: import('@deepseek-ai/dsh-agent').Agent | undefined, args: unknown) {
- return ctx.tools.execute({ callId: CallId(`cwd-${++callCounter}`), name: 'bash', arguments: args, ...agent ? { agent } : {} })
- }
// An agent whose session header carries a cwd (what session/new records).
const agentInCwd = (cwd: string) =>
- ({ inject: () => undefined, session: { header: { version: 0, id: 'c', createdAt: 0, cwd } } }) as unknown as import('@deepseek-ai/dsh-agent').Agent
+ ({ inject: () => undefined, session: { header: { version: 0, id: 'c', createdAt: 0, cwd } } }) as unknown as Agent
it('defaults bash to the agent\'s session cwd (not the server launch dir)', async () => {
const ctx = await setup()
- const result = await callAs(ctx, agentInCwd('/tmp'), { command: 'pwd', description: 'pwd' })
+ const result = await call(ctx, 'bash', { command: 'pwd', description: 'pwd' }, agentInCwd('/tmp'))
expect(text(result).trim()).toMatch(/\/tmp$/)
})
it('an explicit absolute workdir overrides the session cwd', async () => {
const ctx = await setup()
- const result = await callAs(ctx, agentInCwd('/'), { command: 'pwd', description: 'pwd', workdir: '/tmp' })
+ const result = await call(ctx, 'bash', { command: 'pwd', description: 'pwd', workdir: '/tmp' }, agentInCwd('/'))
expect(text(result).trim()).toMatch(/\/tmp$/)
})
it('a relative workdir is resolved against the session cwd', async () => {
const ctx = await setup()
// session cwd /usr + relative 'bin' → /usr/bin
- const result = await callAs(ctx, agentInCwd('/usr'), { command: 'pwd', description: 'pwd', workdir: 'bin' })
+ const result = await call(ctx, 'bash', { command: 'pwd', description: 'pwd', workdir: 'bin' }, agentInCwd('/usr'))
expect(text(result).trim()).toMatch(/\/usr\/bin$/)
})
it('two sessions with different cwds each run bash in their own dir', async () => {
const ctx = await setup()
- const inUsr = await callAs(ctx, agentInCwd('/usr'), { command: 'pwd', description: 'pwd' })
- const inTmp = await callAs(ctx, agentInCwd('/tmp'), { command: 'pwd', description: 'pwd' })
+ const inUsr = await call(ctx, 'bash', { command: 'pwd', description: 'pwd' }, agentInCwd('/usr'))
+ const inTmp = await call(ctx, 'bash', { command: 'pwd', description: 'pwd' }, agentInCwd('/tmp'))
expect(text(inUsr).trim()).toMatch(/\/usr$/)
expect(text(inTmp).trim()).toMatch(/\/tmp$/)
})
@@ -718,34 +774,22 @@ describe('renderResult', () => {
expect(renderResult({ ...base, stdout: { text: 'tail', truncated: true } }))
.toBe('tail\n[output truncated; full output: (unavailable)]')
})
-})
-describe('status lines', () => {
- it('reports kills without a recorded signal (executor raced process exit)', async () => {
- const ctx = await setup()
- const started = await call(ctx, 'bash', { command: 'sleep 60', description: 'test command', run_in_background: true })
- const id = BashTaskId(/task (bash-\d+)/.exec(text(started))![1]!)
- const task = ctx.bash.get(id)!
-
- await call(ctx, 'bash_kill', { task_id: id })
- await task.done
- // Simulate the variant where the close event carried no signal.
- task.signal = null
- const read = await call(ctx, 'bash_output', { task_id: id })
- expect(text(read)).toContain('[status: killed]')
- })
-
- it('reports completed tasks with a null exit code as exit 0', async () => {
- const ctx = await setup()
- const started = await call(ctx, 'bash', { command: 'true', description: 'test command', run_in_background: true })
- const id = BashTaskId(/task (bash-\d+)/.exec(text(started))![1]!)
- const task = ctx.bash.get(id)!
- await task.done
- // Defensive: completed tasks always carry an exit code in practice; the
- // ?? 0 fallback covers task shapes from other executor implementations.
- task.exitCode = null
- const read = await call(ctx, 'bash_output', { task_id: id })
- expect(text(read)).toContain('[status: completed, exit code: 0]')
+ it('reports sandbox denials before exit status and hints only when escalation is advertised', () => {
+ const result: BashRunResult = {
+ exitCode: 1,
+ signal: null,
+ timedOut: false,
+ aborted: false,
+ timeoutMs: 1000,
+ stdout: { text: '', truncated: false },
+ stderr: { text: 'denied', truncated: false },
+ sandbox: { mode: 'read-only', denied: true },
+ }
+ expect(renderResult(result)).toMatch(/denied under read-only mode\]\n\[exit code: 1\]$/)
+ expect(renderResult(result, ['workspace-write'])).toContain('[sandbox: escalation available')
+ expect(renderResult({ ...result, sandbox: { mode: 'read-only', denied: false } }, ['workspace-write']))
+ .not.toContain('[sandbox:')
})
})
@@ -871,14 +915,6 @@ describe('tool-owned UI presentation (presentCall / presentResult)', () => {
})).toBeUndefined()
})
- it('bash_output / bash_kill presentCall: a readable task-scoped title, task id as rawInput', async () => {
- const ctx = await setup()
- expect(ctx.tools.get('bash_output')!.presentCall!({ task_id: 'bash-3' }))
- .toEqual({ card: 'generic', title: 'Read output from background task bash-3', kind: 'execute', rawInput: 'bash-3' })
- expect(ctx.tools.get('bash_kill')!.presentCall!({ task_id: 'bash-3' }))
- .toEqual({ card: 'generic', title: 'Kill background task bash-3', kind: 'execute', rawInput: 'bash-3' })
- })
-
it('presentCall validates softly: malformed args (missing required description) return undefined, never throw', async () => {
const ctx = await setup()
// `defineTool` soft-validates replayed logged args before presentation. Invalid shapes return
@@ -889,10 +925,16 @@ describe('tool-owned UI presentation (presentCall / presentResult)', () => {
describe('the model-facing bash tool builds its request from named args only (no {...args} forward)', () => {
/**
- * Records requests passed to `resolve()` so tests can prove the model-facing tool forwards only
- * named arguments. It intentionally exposes neither `stdin` nor `env`; this catches a future
- * `...args` spread into the post-scrub env merge. The credential scrub remains the security
- * boundary; see the bash stdin/env RFC. Foreground `run()` is canned and `start()` is unused.
+ * Records every {@link BashExecRequest} the consumer hands to `resolve()`, so a
+ * test can assert what the model-facing tool DID and DID NOT forward. The `bash`
+ * tool does not expose `stdin`/`env` as parameters (bash syntax already gives a
+ * model that power), so it must build its request from named args only and
+ * never spread unknown tool-call keys into it. This guard's job is to catch a
+ * future refactor that blindly forwards `...args` — which would silently thread
+ * model input into the post-scrub `env` merge — NOT to defend a trust boundary
+ * (the credential scrub in dsh-bash-local is the security control; see the
+ * bash-stdin-env RFC). Foreground `run()` returns a canned result; `start()`
+ * hands back an already-settled fake handle so the task registration completes.
*/
class RecordingBashExecutor extends BashExecutor {
readonly requests: BashExecRequest[] = []
@@ -905,7 +947,6 @@ describe('the model-facing bash tool builds its request from named args only (no
...request.signal ? { signal: request.signal } : {},
...request.stdin !== undefined ? { stdin: request.stdin } : {},
...request.env !== undefined ? { env: request.env } : {},
- owner: request.owner,
sandboxMode: request.sandboxMode,
}
}
@@ -915,12 +956,16 @@ describe('the model-facing bash tool builds its request from named args only (no
stdout: { text: 'ok', truncated: false }, stderr: { text: '', truncated: false },
})
}
- start(): BashTask { throw new Error('unused') }
- get(): BashTask | undefined { return undefined }
- ownerOf(): OwnerToken | undefined { return undefined }
- list(): BashTask[] { return [] }
- readOutput(): BashTaskRead { throw new Error('unused') }
- kill(): boolean { return false }
+ start(): BashProcess {
+ return {
+ status: 'completed',
+ exitCode: 0,
+ signal: null,
+ done: Promise.resolve(),
+ readOutput: () => ({ delta: '', lossy: false }),
+ kill: () => false,
+ }
+ }
}
async function setupRecording() {
@@ -928,6 +973,8 @@ describe('the model-facing bash tool builds its request from named args only (no
await ctx.plugin(SystemPrompt)
await ctx.plugin(ToolRegistry)
await ctx.plugin(AgentRegistry)
+ await ctx.plugin(TaskService)
+ await ctx.plugin(ToolTasks)
await ctx.plugin(RecordingBashExecutor)
await ctx.plugin(ToolBash)
return { ctx, bash: ctx.bash as RecordingBashExecutor }
@@ -957,9 +1004,7 @@ describe('the model-facing bash tool builds its request from named args only (no
it('a background bash call likewise carries no env/stdin', async () => {
const { ctx, bash } = await setupRecording()
- // start() throws in this recorder, but resolve() runs first and records the
- // request — which is all this no-forward assertion needs.
- await ctx.tools.execute({
+ const result = await ctx.tools.execute({
callId: CallId('no-forward-2'),
name: 'bash',
arguments: {
@@ -970,508 +1015,14 @@ describe('the model-facing bash tool builds its request from named args only (no
stdin: 'x',
},
})
+ // The call really went down the background path (the recorder sees the real
+ // request the consumer built, so the absent env/stdin below is a real
+ // negative, not a recorder that drops everything).
+ expect(text(result)).toBe('started background task bash-1')
expect(bash.requests).toHaveLength(1)
const request = bash.requests[0]!
+ expect(request.command).toBe('sleep 1')
expect('env' in request).toBe(false)
expect('stdin' in request).toBe(false)
- // The owner token IS set on a background call (the isolation fence) — proving
- // the recorder sees the real request the consumer built, so the absent
- // env/stdin above is a real negative, not a recorder that drops everything.
- expect('owner' in request).toBe(true)
})
})
-
-describe('sandbox rendering', () => {
- const sandboxResult = (denied: boolean, exitCode: number): BashRunResult => ({
- exitCode,
- signal: null,
- timedOut: false,
- aborted: false,
- timeoutMs: 1000,
- stdout: { text: '', truncated: false },
- stderr: { text: denied ? 'bash: /x: Read-only file system' : 'boom', truncated: false },
- sandbox: { mode: 'read-only', denied },
- })
-
- it('renders a denial marker BEFORE the exit-code marker (the $-anchored parse survives)', () => {
- const text = renderResult(sandboxResult(true, 1))
- expect(text).toMatch(/\[sandbox: file access denied under read-only mode\]\n\[exit code: 1\]$/)
- })
-
- it('appends the same-turn escalation hint to a denial exactly when the fields are advertised', () => {
- const hinted = renderResult(sandboxResult(true, 1), ['workspace-write', 'danger-full-access'])
- expect(hinted).toMatch(
- /denied under read-only mode\]\n\[sandbox: escalation available — retry this exact command once with sandbox_permissions [^\n]+\]\n\[exit code: 1\]$/, // eslint-disable-line @stylistic/max-len -- the hint sentence is pinned verbatim
- )
- // Default (no advertisement): no hint — a lever the schema does not offer is never suggested.
- expect(renderResult(sandboxResult(true, 1))).not.toContain('escalation available')
- // A non-denied result never hints, advertised or not.
- expect(renderResult(sandboxResult(false, 2), ['danger-full-access'])).not.toContain('escalation available')
- })
-
- it('renders no sandbox marker for a plain failure under a sandboxed mode', () => {
- expect(renderResult(sandboxResult(false, 2))).not.toContain('[sandbox:')
- })
-
- it('bash_output reports a settled background denial with the same marker', async () => {
- const ctx = new Context()
- await ctx.plugin(SystemPrompt)
- await ctx.plugin(ToolRegistry)
- await ctx.plugin(AgentRegistry)
- await ctx.plugin(LocalSandboxProvider, PASSTHROUGH_RUNNER_CONFIG)
- await ctx.plugin(SandboxBashExecutor, { graceMs: 200 })
- const bash = ctx.bash as SandboxBashExecutor
- bash.internals = { spillDir }
- await ctx.plugin(ToolBash)
- const started = await call(ctx, 'bash', { command: 'echo "x: Permission denied" >&2; exit 1', description: 'test command', run_in_background: true })
- const id = text(started).match(/started background task (bash-\d+)/)![1]
- await bash.list().find(task => task.id === id)!.done
- const read = await call(ctx, 'bash_output', { task_id: id })
- expect(text(read)).toMatch(
- /\[status: completed, exit code: 1\]\n\[sandbox: file access denied under read-only mode\]\n\[sandbox: escalation available[^\n]+\]$/,
- )
- })
-
- it('a settled background denial renders no escalation hint without a confining executor (defensive arm)', async () => {
- // Structurally near-unreachable through the real stack — every confining
- // default advertises the static target set — but the read path guards
- // it anyway: an executor that reports no sandboxMode (fields never
- // advertised) whose task nonetheless carries denial facts must render
- // the marker without suggesting a lever the schema does not offer.
- class FactsOnlyExecutor extends TestBashExecutor {
- private readonly task: BashTask = {
- id: BashTaskId('bash-facts'),
- status: 'completed',
- exitCode: 1,
- signal: null,
- done: Promise.resolve(),
- sandbox: { mode: 'read-only', denied: true },
- }
-
- run(): Promise { return Promise.reject(new Error('not used')) }
- start(): BashTask { return this.task }
- get(id: string): BashTask | undefined { return id === this.task.id ? this.task : undefined }
- list(): BashTask[] { return [this.task] }
- kill(): boolean { return false }
- ownerOf(): OwnerToken | undefined { return undefined }
- readOutput(): BashTaskRead {
- return { task: this.task, delta: '', lossy: false }
- }
- }
- const ctx = new Context()
- await ctx.plugin(SystemPrompt)
- await ctx.plugin(ToolRegistry)
- await ctx.plugin(AgentRegistry)
- await ctx.plugin(FactsOnlyExecutor)
- await ctx.plugin(ToolBash)
- const read = await call(ctx, 'bash_output', { task_id: 'bash-facts' })
- expect(text(read)).toMatch(/\[sandbox: file access denied under read-only mode\]$/)
- expect(text(read)).not.toContain('escalation available')
- })
-
- it('bash_output reports a settled background RUNNER failure as a sandbox problem, outranking the denial marker', async () => {
- // A provider whose wrap carries a runner-failure signature: the settled
- // task's stderr matching it means the sandbox itself broke and the
- // command never ran — even though the same stderr also carries denial
- // words (a runner's error text may contain them).
- class FakeProvider extends SandboxProvider {
- confine(argv: readonly string[]): ConfinedArgv {
- return { argv: [...argv], enforcement: 'full', denialSignatures: ['permission denied'], runnerFailureSignatures: ['fake-runner: '] }
- }
- }
- const ctx = new Context()
- await ctx.plugin(SystemPrompt)
- await ctx.plugin(ToolRegistry)
- await ctx.plugin(AgentRegistry)
- await ctx.plugin(FakeProvider)
- await ctx.plugin(SandboxBashExecutor, { graceMs: 200 })
- const bash = ctx.bash as SandboxBashExecutor
- bash.internals = { spillDir }
- await ctx.plugin(ToolBash)
- const started = await call(ctx, 'bash', { command: 'echo "fake-runner: cannot open rule path: /x: Permission denied" >&2; exit 125', description: 'test command', run_in_background: true })
- const id = text(started).match(/started background task (bash-\d+)/)![1]
- await bash.list().find(task => task.id === id)!.done
- const read = await call(ctx, 'bash_output', { task_id: id })
- expect(text(read)).toMatch(/\[sandbox: the sandbox runner itself failed under read-only mode — the command did not run; /)
- expect(text(read)).toMatch(/this is a sandbox problem, not a command failure\]$/)
- expect(text(read)).not.toContain('file access denied')
- })
-
- it('classifies an executable configured runner that refuses its profile before the command runs', async () => {
- const signature = 'custom-runner-rejected'
- const ctx = new Context()
- await ctx.plugin(LocalSandboxProvider, {
- runnerCommand: ['bash', '-c', `printf '${signature}\\n' >&2; exit 125`, 'custom-runner'],
- runnerFailureSignatures: [signature],
- })
- await ctx.plugin(SandboxBashExecutor, { graceMs: 200 })
- const bash = ctx.bash as SandboxBashExecutor
- bash.internals = { spillDir }
-
- await expect(bash.run(bash.resolve({ command: 'echo command-must-not-run' })))
- .rejects.toMatchObject({ code: 'SANDBOX_UNAVAILABLE' })
-
- const task = bash.start(bash.resolve({ command: 'echo command-must-not-run' }))
- await task.done
- expect(task.sandbox).toEqual({ mode: 'read-only', denied: false, enforcement: 'full', runnerFailed: true })
- })
-
- it('reports a real denial end-to-end through the shipping sandbox executor', async () => {
- const ctx = new Context()
- await ctx.plugin(SystemPrompt)
- await ctx.plugin(ToolRegistry)
- await ctx.plugin(AgentRegistry)
- await ctx.plugin(LocalSandboxProvider, PASSTHROUGH_RUNNER_CONFIG)
- await ctx.plugin(SandboxBashExecutor, { graceMs: 200 })
- const bash = ctx.bash as SandboxBashExecutor
- bash.internals = { spillDir }
- await ctx.plugin(ToolBash)
- const lockedDir = join(mkdtempSync(join(tmpdir(), 'dsh-tool-bash-denied-')), 'locked')
- mkdirSync(lockedDir)
- chmodSync(lockedDir, 0o555)
- const result = await call(ctx, 'bash', { command: `echo x > ${lockedDir}/f`, description: 'Write into a locked directory' })
- expect(result.isError).toBe(false)
- expect(text(result)).toMatch(
- /denied under read-only mode\]\n\[sandbox: escalation available[^\n]+\]\n\[exit code: \d+\]$/,
- )
- })
-})
-
-describe('sandbox escalation (sandbox_permissions / justification)', () => {
- /** Compose the real sandbox stack (passthrough runner) at a given default mode. */
- async function setupSandboxed(mode?: 'read-only' | 'workspace-write' | 'danger-full-access', opts: { approval?: boolean; policy?: 'ask' | 'never' } = {}) {
- const ctx = new Context()
- await ctx.plugin(SystemPrompt)
- await ctx.plugin(ToolRegistry)
- await ctx.plugin(AgentRegistry)
- await ctx.plugin(LocalSandboxProvider, PASSTHROUGH_RUNNER_CONFIG)
- await ctx.plugin(SandboxBashExecutor, { graceMs: 200, ...mode !== undefined ? { mode } : {} })
- const bash = ctx.bash as SandboxBashExecutor
- bash.internals = { spillDir }
- if (opts.approval === true) await ctx.plugin(ApprovalService, opts.policy !== undefined ? { policy: opts.policy } : {})
- await ctx.plugin(ToolBash)
- return { ctx, bash }
- }
-
- /** The registered bash tool's wire schema (what the model actually sees). */
- function bashSchema(ctx: Context) {
- const schema = ctx.tools.schemas().find(s => s.name === 'bash')
- if (!schema) throw new Error('bash tool not registered')
- return schema as unknown as { description: string; parameters: { properties: Record } }
- }
-
- /**
- * A fake agent whose session records appends — the approval audit surface.
- * Seeded mid-turn: an escalating call always runs inside one, and request()
- * enforces the enclosure.
- */
- function escalationAgent(events: Array<{ type: string; data: Record }>): Agent {
- return {
- id: 'agent-esc',
- session: {
- header: { version: 0, id: 'sess-esc', createdAt: 0 },
- events: [{ type: 'turn/start' }],
- append: (type: string, data: Record) => { events.push({ type, data }) },
- },
- } as unknown as Agent
- }
-
- let escCall = 0
- function callAs(ctx: Context, agent: Agent | undefined, args: unknown) {
- return ctx.tools.execute({ callId: CallId(`call-esc-${++escCall}`), name: 'bash', arguments: args, ...agent ? { agent } : {} })
- }
-
- const ESCALATE = { command: 'true', description: 'test escalation', sandbox_permissions: 'workspace-write', justification: 'the test needs it' }
-
- it('advertises no escalation surface under a non-sandboxing executor', async () => {
- const ctx = await setup()
- expect(ctx.bash.sandboxMode).toBeUndefined()
- const schema = bashSchema(ctx)
- expect(schema.parameters.properties['sandbox_permissions']).toBeUndefined()
- expect(schema.parameters.properties['justification']).toBeUndefined()
- expect(schema.description).not.toContain('sanctioned exception')
- })
-
- it('advertises the full closed target vocabulary under any confining default', async () => {
- // The enum is deliberately NOT default-relative: a session's effective
- // mode is per-session and switchable, so every confining composition
- // advertises every possible target — strict widening is checked at
- // execution against the call's effective mode instead.
- for (const mode of [undefined, 'workspace-write', 'danger-full-access'] as const) {
- const { ctx } = await setupSandboxed(mode)
- const schema = bashSchema(ctx)
- expect(schema.parameters.properties['sandbox_permissions']?.enum).toEqual(['workspace-write', 'danger-full-access'])
- expect(schema.parameters.properties['justification']).toBeDefined()
- expect(schema.description).toContain('sanctioned exception')
- }
- })
-
- it('a non-widening request fails at execution with its own text and prompts no one', async () => {
- const { ctx } = await setupSandboxed('danger-full-access', { approval: true })
- const consulted = vi.fn()
- ctx.on('approval/request', (_req, next) => { consulted(); return next() })
- const result = await callAs(ctx, escalationAgent([]), { command: 'true', description: 'd', sandbox_permissions: 'workspace-write', justification: 'already wider' })
- expect(result.isError).toBe(true)
- expect(text(result)).toContain('not strictly wider than this call\'s current "danger-full-access" mode')
- expect(consulted).not.toHaveBeenCalled()
- })
-
- it('rejects sandbox_permissions without a justification, and vice versa, and a blank justification', async () => {
- const { ctx } = await setupSandboxed()
- const missing = await callAs(ctx, undefined, { command: 'true', description: 'd', sandbox_permissions: 'workspace-write' })
- expect(missing.isError).toBe(true)
- expect(text(missing)).toContain('sandbox_permissions requires a justification')
- const orphan = await callAs(ctx, undefined, { command: 'true', description: 'd', justification: 'why not' })
- expect(orphan.isError).toBe(true)
- expect(text(orphan)).toContain('only valid together with sandbox_permissions')
- const blank = await callAs(ctx, undefined, { command: 'true', description: 'd', sandbox_permissions: 'workspace-write', justification: ' ' })
- expect(blank.isError).toBe(true)
- expect(text(blank)).toContain('expected a non-empty sentence')
- })
-
- it('the schema enum rejects a mode outside the target vocabulary before execute (registry-level, any caller)', async () => {
- const { ctx } = await setupSandboxed()
- const result = await callAs(ctx, undefined, { command: 'true', description: 'd', sandbox_permissions: 'read-only', justification: 'narrow' })
- expect(result.isError).toBe(true)
- expect(text(result)).toContain('must be one of')
- })
-
- it('rejects an unadvertised sandbox_permissions injection under a non-sandboxing executor', async () => {
- const ctx = await setup()
- const result = await callAs(ctx, undefined, { command: 'true', description: 'd', sandbox_permissions: 'workspace-write', justification: 'sneaky' })
- expect(result.isError).toBe(true)
- expect(text(result)).toContain('not available in this composition')
- })
-
- it('fails closed with its own text when no approval service is composed', async () => {
- const { ctx } = await setupSandboxed()
- const result = await callAs(ctx, escalationAgent([]), ESCALATE)
- expect(result.isError).toBe(true)
- expect(text(result)).toContain('no approval service is composed')
- })
-
- it('fails closed with its own text for an agent-less escalating call', async () => {
- const { ctx } = await setupSandboxed('read-only', { approval: true })
- const result = await callAs(ctx, undefined, ESCALATE)
- expect(result.isError).toBe(true)
- expect(text(result)).toContain('no agent to route it through')
- })
-
- it('fails closed with its own text when the service has no answerer', async () => {
- const { ctx } = await setupSandboxed('read-only', { approval: true })
- const result = await callAs(ctx, escalationAgent([]), ESCALATE)
- expect(result.isError).toBe(true)
- expect(text(result)).toContain('no approval channel is available')
- })
-
- it('a grant runs THAT call under the wider mode — the denial marker names it — and lands the audit pair', async () => {
- const { ctx } = await setupSandboxed('read-only', { approval: true })
- ctx.on('approval/request', () => Promise.resolve('allowed-once'))
- const events: Array<{ type: string; data: Record }> = []
- // A real unix denial under the passthrough runner: the marker's mode can
- // only say workspace-write if the override actually rode the spec.
- const lockedDir = join(mkdtempSync(join(tmpdir(), 'dsh-esc-denied-')), 'locked')
- mkdirSync(lockedDir)
- chmodSync(lockedDir, 0o555)
- const result = await callAs(ctx, escalationAgent(events), {
- command: `echo x > ${lockedDir}/f`,
- description: 'write into a locked directory',
- sandbox_permissions: 'workspace-write',
- justification: 'must write outside the workspace',
- })
- expect(result.isError).toBe(false)
- expect(text(result)).toMatch(/\[sandbox: file access denied under workspace-write mode\]/)
- expect(events.map(e => e.type)).toEqual(['approval/asked', 'approval/decided'])
- expect(events[0]?.data['toolName']).toBe('bash')
- expect(events[0]?.data['reason']).toBe('escalate sandbox to workspace-write: must write outside the workspace')
- expect(events[1]?.data['outcome']).toBe('allowed-once')
- })
-
- it('a granted background start settles with the wider mode\'s facts', async () => {
- const { ctx, bash } = await setupSandboxed('read-only', { approval: true })
- ctx.on('approval/request', () => Promise.resolve('allowed-once'))
- const started = await callAs(ctx, escalationAgent([]), { ...ESCALATE, run_in_background: true })
- expect(started.isError).toBe(false)
- const id = text(started).match(/started background task (bash-\d+)/)?.[1]
- const task = bash.list().find(t => t.id === id)
- if (!task) throw new Error('escalated task not tracked')
- await task.done
- expect(task.sandbox).toMatchObject({ mode: 'workspace-write', denied: false })
- })
-
- it('a rejection denies with the user-said-no text and runs nothing', async () => {
- const { ctx } = await setupSandboxed('read-only', { approval: true })
- ctx.on('approval/request', () => Promise.resolve('rejected'))
- // A live (non-aborted) signal rides the execution: the gate threads it
- // into the approval request so a turn cancellation can withdraw the ask.
- const result = await ctx.tools.execute({
- callId: CallId(`call-esc-${++escCall}`),
- name: 'bash',
- arguments: ESCALATE,
- agent: escalationAgent([]),
- signal: new AbortController().signal,
- })
- expect(result.isError).toBe(true)
- expect(text(result)).toContain('the user rejected escalating this command to "workspace-write"')
- })
-
- it('a cancellation denies with the cancelled text', async () => {
- const { ctx } = await setupSandboxed('read-only', { approval: true })
- ctx.on('approval/request', () => Promise.resolve('cancelled'))
- const result = await callAs(ctx, escalationAgent([]), ESCALATE)
- expect(result.isError).toBe(true)
- expect(text(result)).toContain('approval for escalating to "workspace-write" was cancelled')
- })
-
- it('a rogue approval stand-in returning a non-vocabulary outcome hits the exhaustiveness backstop', async () => {
- const { ctx } = await setupSandboxed()
- ctx.provide('approval', { request: () => Promise.resolve('yolo') } as unknown as InstanceType)
- const result = await callAs(ctx, escalationAgent([]), ESCALATE)
- expect(result.isError).toBe(true)
- expect(text(result)).toContain('unreachable')
- })
-
- it('a never policy rejects an escalation deterministically without consulting any answerer', async () => {
- // The live-session e.md case: the model requests escalation against a
- // 'never' session — the prepend gate answers rejected before any
- // interactive answerer, the fail-closed text is the ordinary rejection
- // wording, and the audit pair still lands.
- const { ctx } = await setupSandboxed('read-only', { approval: true, policy: 'never' })
- const consulted = vi.fn()
- ctx.on('approval/request', (_req, next) => { consulted(); return next() })
- const events: Array<{ type: string; data: Record }> = []
- const result = await callAs(ctx, escalationAgent(events), ESCALATE)
- expect(result.isError).toBe(true)
- expect(text(result)).toContain('the user rejected escalating this command to "workspace-write"')
- expect(consulted).not.toHaveBeenCalled()
- expect(events.map(e => e.type)).toEqual(['approval/asked', 'approval/decided'])
- expect(events[1]?.data).toMatchObject({ outcome: 'rejected' })
- })
-
- it('a plain call under a sandboxing executor never consults approval', async () => {
- const { ctx } = await setupSandboxed('read-only', { approval: true })
- const asked = vi.fn()
- ctx.on('approval/request', (_req, next) => { asked(); return next() })
- const result = await callAs(ctx, escalationAgent([]), { command: 'echo plain', description: 'plain run' })
- expect(result.isError).toBe(false)
- expect(text(result)).toContain('plain')
- expect(asked).not.toHaveBeenCalled()
- })
-})
-
-describe('per-session sandbox mode (the bash/sandbox-mode fold)', () => {
- /** Compose the real sandbox stack (passthrough runner) at a given default mode. */
- async function setupModal(mode: 'read-only' | 'workspace-write' | 'danger-full-access' = 'read-only', opts: { approval?: boolean } = {}) {
- const ctx = new Context()
- await ctx.plugin(SystemPrompt)
- await ctx.plugin(ToolRegistry)
- await ctx.plugin(AgentRegistry)
- await ctx.plugin(LocalSandboxProvider, PASSTHROUGH_RUNNER_CONFIG)
- await ctx.plugin(SandboxBashExecutor, { graceMs: 200, mode })
- ;(ctx.bash as SandboxBashExecutor).internals = { spillDir }
- if (opts.approval === true) await ctx.plugin(ApprovalService)
- await ctx.plugin(ToolBash)
- return ctx
- }
-
- /**
- * An agent stand-in over a REAL Session — the stamping folds real events;
- * the opened turn satisfies approval's enclosure precondition on escalating
- * calls.
- */
- function sessionAgent(id: string): { agent: Agent; session: Session; injected: string[] } {
- const session = new Session(SessionId(id))
- session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
- const injected: string[] = []
- const agent = {
- id,
- session,
- inject: (content: { type: string; text: string }[]) => { injected.push(content[0]?.text ?? '') },
- } as unknown as Agent
- return { agent, session, injected }
- }
-
- let modeCall = 0
- const callAs = (ctx: Context, agent: Agent | undefined, args: unknown) =>
- ctx.tools.execute({ callId: CallId(`call-mode-${++modeCall}`), name: 'bash', arguments: args, ...agent ? { agent } : {} })
-
-
- it('stamps calls with grant > session override > nothing (executor default)', async () => {
- const ctx = await setupModal('read-only', { approval: true })
- ctx.on('approval/request', () => Promise.resolve('allowed-once'))
- const seen: (string | undefined)[] = []
- const original = ctx.bash.resolve.bind(ctx.bash)
- vi.spyOn(ctx.bash, 'resolve').mockImplementation((req) => {
- seen.push(req.sandboxMode)
- return original(req)
- })
- const { agent, session } = sessionAgent('sess-stamp-1')
- const run = { command: 'true', description: 'stamp probe' }
- await callAs(ctx, agent, run) // no override yet
- setSandboxMode(session, 'workspace-write')
- await callAs(ctx, agent, run) // standing override
- await callAs(ctx, undefined, run) // agent-less caller: no session to fold
- await callAs(ctx, agent, { ...run, sandbox_permissions: 'danger-full-access', justification: 'grant outranks override' })
- expect(seen).toEqual([undefined, 'workspace-write', undefined, 'danger-full-access'])
- })
-
- it('escalates relative to the session effective mode, not the executor default (narrower override)', async () => {
- // With a workspace-write default and read-only override, escalation must return to
- // workspace-write. The static target vocabulary exposes it, and validation compares it with
- // the call's effective override rather than a default-relative ladder.
- const ctx = await setupModal('workspace-write', { approval: true })
- ctx.on('approval/request', () => Promise.resolve('allowed-once'))
- const seen: (string | undefined)[] = []
- const original = ctx.bash.resolve.bind(ctx.bash)
- vi.spyOn(ctx.bash, 'resolve').mockImplementation((req) => {
- seen.push(req.sandboxMode)
- return original(req)
- })
- const { agent, session } = sessionAgent('sess-esc-narrow')
- setSandboxMode(session, 'read-only')
- const result = await callAs(ctx, agent, { command: 'true', description: 'd', sandbox_permissions: 'workspace-write', justification: 'the override is narrower than the default' })
- expect(result.isError).toBe(false)
- expect(seen).toEqual(['workspace-write'])
- })
-
- it('a danger-full-access default still offers the lever to a narrower-switched session', async () => {
- // Under the default-relative ladder these fields VANISHED (nothing is
- // wider than the default), stranding a read-only-overridden session
- // with no escalation path at all.
- const ctx = await setupModal('danger-full-access', { approval: true })
- ctx.on('approval/request', () => Promise.resolve('allowed-once'))
- const schema = ctx.tools.schemas().find(t => t.name === 'bash') as unknown as { parameters: { properties: Record } }
- expect(schema.parameters.properties['sandbox_permissions']?.enum).toEqual(['workspace-write', 'danger-full-access'])
- const { agent, session } = sessionAgent('sess-esc-dfa')
- setSandboxMode(session, 'read-only')
- const result = await callAs(ctx, agent, { command: 'true', description: 'd', sandbox_permissions: 'workspace-write', justification: 'confined by override under a wide default' })
- expect(result.isError).toBe(false)
- })
-
- it('rejects a non-widening request against the OVERRIDDEN effective mode without prompting', async () => {
- const ctx = await setupModal('read-only', { approval: true })
- const consulted = vi.fn()
- ctx.on('approval/request', (_req, next) => { consulted(); return next() })
- const { agent, session } = sessionAgent('sess-esc-nonwide')
- setSandboxMode(session, 'danger-full-access')
- const result = await callAs(ctx, agent, { command: 'true', description: 'd', sandbox_permissions: 'workspace-write', justification: 'already wider via override' })
- expect(result.isError).toBe(true)
- expect(text(result)).toContain('not strictly wider than this call\'s current "danger-full-access" mode')
- expect(consulted).not.toHaveBeenCalled()
- })
-
- it('never stamps an override under a non-sandboxing executor (nothing honors it)', async () => {
- const ctx = await setup()
- const seen: (string | undefined)[] = []
- const original = ctx.bash.resolve.bind(ctx.bash)
- vi.spyOn(ctx.bash, 'resolve').mockImplementation((req) => {
- seen.push(req.sandboxMode)
- return original(req)
- })
- const { agent, session } = sessionAgent('sess-stamp-2')
- setSandboxMode(session, 'danger-full-access')
- await callAs(ctx, agent, { command: 'true', description: 'plain probe' })
- expect(seen).toEqual([undefined])
- })
-
-})
diff --git a/packages/bash/tool-bash/tsconfig.json b/packages/bash/tool-bash/tsconfig.json
index c4d738c7dd..6957c10fdf 100644
--- a/packages/bash/tool-bash/tsconfig.json
+++ b/packages/bash/tool-bash/tsconfig.json
@@ -14,6 +14,9 @@
{
"path": "../../../vendor/cordis"
},
+ {
+ "path": "../../../vendor/schemastery"
+ },
{
"path": "../../llm/llm"
},
@@ -26,6 +29,9 @@
{
"path": "../../bash/bash"
},
+ {
+ "path": "../../tasks/tasks"
+ },
{
"path": "../../core/system-prompt"
},
diff --git a/packages/cordis/tool-cordis/src/api-catalog.ts b/packages/cordis/tool-cordis/src/api-catalog.ts
index 2e9ace7c50..1d4362b35f 100644
--- a/packages/cordis/tool-cordis/src/api-catalog.ts
+++ b/packages/cordis/tool-cordis/src/api-catalog.ts
@@ -84,17 +84,11 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
},
{
key: 'bash',
- summary: 'Registers one `ctx.bash` implementation.',
+ summary: 'Abstract bash execution service.',
methods: [
'abstract resolve(request: BashExecRequest): BashExecSpec',
'abstract run(spec: BashExecSpec): Promise',
- 'abstract start(spec: BashExecSpec): BashTask',
- 'abstract get(id: BashTaskId): BashTask | undefined',
- 'abstract ownerOf(id: BashTaskId): OwnerToken | undefined',
- 'abstract list(): BashTask[]',
- 'abstract readOutput(id: BashTaskId): BashTaskRead',
- 'abstract kill(id: BashTaskId): boolean',
- 'onTaskDone(listener: BashTaskListener): () => void',
+ 'abstract start(spec: BashExecSpec): BashProcess',
],
},
{
@@ -214,6 +208,20 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
'async assemble(context: AssembleContext = {}): Promise',
],
},
+ {
+ key: 'tasks',
+ summary: 'The `tasks` service: the runtime-global background task registry.',
+ methods: [
+ 'start(spec: TaskStart): TaskId',
+ 'list(caller?: Agent): TaskSnapshot[]',
+ 'get(id: TaskId, caller?: Agent): TaskSnapshot',
+ 'read(id: TaskId, caller?: Agent): TaskRead',
+ 'kill(id: TaskId, caller?: Agent, reason?: string): \'requested\' | \'already-finished\'',
+ 'async wait(id: TaskId, timeoutMs: number, caller?: Agent, signal?: AbortSignal): Promise',
+ 'onTaskDone(listener: TaskDoneListener): () => void',
+ 'attachSurface(name: string): () => void',
+ ],
+ },
{
key: 'tokenMeter',
summary: 'Concrete registry and replay owner for all configured model meters.',
@@ -578,11 +586,23 @@ export const TYPE_API: readonly TypeApiEntry[] = [
},
{
name: 'BashExecRequest',
- declaration: 'export interface BashExecRequest {\n command: string;\n workdir?: string | undefined;\n timeoutMs?: number | undefined;\n signal?: AbortSignal | undefined;\n stdin?: string | undefined;\n env?: Record | undefined;\n owner?: OwnerToken | undefined;\n sandboxMode?: SandboxMode | undefined;\n}',
+ declaration: 'export interface BashExecRequest {\n command: string;\n workdir?: string | undefined;\n timeoutMs?: number | undefined;\n signal?: AbortSignal | undefined;\n stdin?: string | undefined;\n env?: Record | undefined;\n sandboxMode?: SandboxMode | undefined;\n}',
},
{
name: 'BashExecSpec',
- declaration: 'export interface BashExecSpec {\n command: string;\n workdir: string;\n timeoutMs: number;\n signal?: AbortSignal | undefined;\n stdin?: string | undefined;\n env?: Record | undefined;\n owner: OwnerToken | undefined;\n sandboxMode: SandboxMode | undefined;\n}',
+ declaration: 'export interface BashExecSpec {\n command: string;\n workdir: string;\n timeoutMs: number;\n signal?: AbortSignal | undefined;\n stdin?: string | undefined;\n env?: Record | undefined;\n sandboxMode: SandboxMode | undefined;\n}',
+ },
+ {
+ name: 'BashProcess',
+ declaration: 'export interface BashProcess {\n status: BashProcessStatus;\n exitCode: number | null;\n signal: NodeJS.Signals | null;\n readonly done: Promise;\n sandbox?: BashSandboxInfo;\n readOutput(): BashProcessRead;\n kill(): boolean;\n}',
+ },
+ {
+ name: 'BashProcessRead',
+ declaration: 'export interface BashProcessRead {\n delta: string;\n lossy: boolean;\n stdoutSpillPath?: string;\n stderrSpillPath?: string;\n}',
+ },
+ {
+ name: 'BashProcessStatus',
+ declaration: 'export type BashProcessStatus = \'running\' | \'completed\' | \'killed\';',
},
{
name: 'BashRunResult',
@@ -592,26 +612,6 @@ export const TYPE_API: readonly TypeApiEntry[] = [
name: 'BashSandboxInfo',
declaration: 'export interface BashSandboxInfo {\n mode: SandboxMode;\n denied: boolean;\n enforcement?: SandboxEnforcement;\n runnerFailed?: boolean;\n}',
},
- {
- name: 'BashTask',
- declaration: 'export interface BashTask {\n readonly id: BashTaskId;\n status: BashTaskStatus;\n exitCode: number | null;\n signal: NodeJS.Signals | null;\n readonly done: Promise;\n sandbox?: BashSandboxInfo;\n}',
- },
- {
- name: 'BashTaskId',
- declaration: 'export type BashTaskId = Branded<\'BashTaskId\'>;',
- },
- {
- name: 'BashTaskListener',
- declaration: 'export type BashTaskListener = (task: BashTask) => void;',
- },
- {
- name: 'BashTaskRead',
- declaration: 'export interface BashTaskRead {\n task: BashTask;\n delta: string;\n lossy: boolean;\n stdoutSpillPath?: string;\n stderrSpillPath?: string;\n}',
- },
- {
- name: 'BashTaskStatus',
- declaration: 'export type BashTaskStatus = \'running\' | \'completed\' | \'killed\';',
- },
{
name: 'Branded',
declaration: 'export type Branded = string & {\n readonly [BRAND]: B;\n};',
@@ -780,10 +780,6 @@ export const TYPE_API: readonly TypeApiEntry[] = [
name: 'ModelTokenMeter',
declaration: 'export interface ModelTokenMeter {\n readonly model: string;\n readonly contextWindow: number;\n readonly charsPerToken: number;\n measure(session: Session, requestHeader?: EpochHeader): TokenMeasurement;\n measureSurface(session: Session): TokenSurfaceMeasurement;\n estimateMessage(message: Message): number;\n}',
},
- {
- name: 'OwnerToken',
- declaration: 'export type OwnerToken = Branded<\'OwnerToken\'>;',
- },
{
name: 'PresetOption',
declaration: 'export interface PresetOption {\n value: string;\n name: string;\n description?: string;\n}',
@@ -960,6 +956,46 @@ export const TYPE_API: readonly TypeApiEntry[] = [
name: 'SurfaceOp',
declaration: 'export type SurfaceOp = \'append\' | {\n op: \'replace\';\n start: number;\n end: number;\n};',
},
+ {
+ name: 'TaskDoneListener',
+ declaration: 'export type TaskDoneListener = (snapshot: TaskSnapshot, owner: Agent | undefined) => void | PromiseLike;',
+ },
+ {
+ name: 'TaskHooks',
+ declaration: 'export interface TaskHooks {\n cancel(reason?: string): void;\n done: Promise;\n readOutput?(): string;\n}',
+ },
+ {
+ name: 'TaskId',
+ declaration: 'export type TaskId = Branded<\'TaskId\'>;',
+ },
+ {
+ name: 'TaskKind',
+ declaration: 'export type TaskKind = TaskKindMap[keyof TaskKindMap];',
+ },
+ {
+ name: 'TaskKindMap',
+ declaration: 'export interface TaskKindMap {\n bash: \'bash\';\n subagent: \'subagent\';\n}',
+ },
+ {
+ name: 'TaskOutcome',
+ declaration: 'export interface TaskOutcome {\n status: \'completed\' | \'killed\' | \'failed\';\n detail?: string;\n output?: string;\n}',
+ },
+ {
+ name: 'TaskRead',
+ declaration: 'export interface TaskRead {\n text: string;\n snapshot: TaskSnapshot;\n}',
+ },
+ {
+ name: 'TaskSnapshot',
+ declaration: 'export interface TaskSnapshot {\n id: TaskId;\n kind: TaskKind;\n label: string;\n ownerSession?: SessionId;\n status: TaskStatus;\n detail?: string;\n startedAt: number;\n finishedAt?: number;\n reported: boolean;\n}',
+ },
+ {
+ name: 'TaskStart',
+ declaration: 'export interface TaskStart {\n kind: TaskKind;\n label: string;\n owner?: Agent;\n run(): TaskHooks;\n}',
+ },
+ {
+ name: 'TaskStatus',
+ declaration: 'export type TaskStatus = \'running\' | \'stopping\' | \'completed\' | \'killed\' | \'failed\';',
+ },
{
name: 'TerminalCallView',
declaration: 'export interface TerminalCallView {\n card: \'terminal\';\n title: string;\n description?: string;\n cwd?: string;\n}',
diff --git a/packages/core/agent-loop/README.md b/packages/core/agent-loop/README.md
index 70d7c16cf0..886c44c67b 100644
--- a/packages/core/agent-loop/README.md
+++ b/packages/core/agent-loop/README.md
@@ -60,7 +60,7 @@ Everything that goes beyond "call the model, run the tools, repeat" belongs to p
- Hooks and policy: the relevant `agent/*` checkpoints plus the guarded `tools/pre-execute` → `tools/execute` → `tools/post-execute` → `tools/result` pipeline; exact signatures and modes live in the [generated event catalog](../../../docs/cordis-catalog/events.md)
- Compaction: pressure on `agent/post-step`; canonical context overflow on `agent/request-error`
- Sandbox, permission, plan mode: `tools/pre-execute` for extensible deny/ask, `tools.guard()` for monotonic owner policy, `tools/post-execute` for result decisions, and `tools/result` for final observation
-- Sub-agents: implemented outside the loop as `ctx.subagents` providers; in-process providers use `ctx.agents.create()` and owned `AgentHandle` teardown, while child streaming/progress and background/poll collection remain deferred.
+- Sub-agents: implemented outside the loop as `ctx.subagents` providers; in-process providers use `ctx.agents.create()` and owned `AgentHandle` teardown, while generic [`ctx.tasks`](../../tasks/tasks/) plus [`dsh-tool-subagent`](../../subagent/tool-subagent/) own background collection.
- Persistence: `session/event` + `session/flush`
- UI: `session/event` (assistant token stream, boundaries, tool activity) + `agent/*` control events (`agent/status`, `agent/created`/`agent/disposed`)
diff --git a/packages/core/agent/tests/verify-export-jsdoc.spec.ts b/packages/core/agent/tests/verify-export-jsdoc.spec.ts
index 2761351d10..cc361a956e 100644
--- a/packages/core/agent/tests/verify-export-jsdoc.spec.ts
+++ b/packages/core/agent/tests/verify-export-jsdoc.spec.ts
@@ -30,6 +30,22 @@ function fixture(files: Record): string {
const make = (content: string): string => fixture({ 'index.ts': content })
describe('verify-export-jsdoc functions and consts', () => {
+ it('limits packages without src/* exports to declarations reachable from package entrypoints', () => {
+ const root = fixture({
+ 'index.ts': "export { publicFn } from './internal.ts'\n",
+ 'internal.ts': `
+export function publicFn(value: string): string { return value }
+export function hiddenFn(value: string): string { return value }
+`,
+ })
+ writeFileSync(join(root, 'packages/group/fix/package.json'), JSON.stringify({
+ exports: { '.': { types: './lib/types/index.d.ts', default: './lib/index.js' } },
+ }))
+ const violations = collectExportJsdocViolations(root)
+ expect(violations).toHaveLength(1)
+ expect(violations.every(violation => violation.includes('publicFn'))).toBe(true)
+ })
+
it('accepts a fully documented surface', () => {
expect(collectExportJsdocViolations(make(`
/**
diff --git a/packages/core/tools/tests/gen-tool-catalog.spec.ts b/packages/core/tools/tests/gen-tool-catalog.spec.ts
index ad739173c9..1ba64f6326 100644
--- a/packages/core/tools/tests/gen-tool-catalog.spec.ts
+++ b/packages/core/tools/tests/gen-tool-catalog.spec.ts
@@ -23,7 +23,7 @@ describe('gen-tool-catalog collectToolCatalog', () => {
it('boots every shipped tool package and harvests its model-facing schemas', async () => {
const catalog = await collectToolCatalog()
const names = catalog.flatMap(entry => entry.schemas.map(s => s.name)).sort()
- expect(names).toEqual(['ask_user_question', 'bash', 'bash_kill', 'bash_output', 'cordis_inspect', 'cordis_mount', 'cordis_unmount', 'edit', 'read', 'run_code', 'skill', 'subagent', 'todo_write', 'web_fetch', 'web_search', 'workflow', 'write'])
+ expect(names).toEqual(['ask_user_question', 'bash', 'cordis_inspect', 'cordis_mount', 'cordis_unmount', 'edit', 'read', 'run_code', 'skill', 'subagent', 'task_kill', 'task_list', 'task_output', 'todo_write', 'web_fetch', 'web_search', 'workflow', 'write'])
// Every tool carries a JSON-Schema `parameters` object (what the model sees).
for (const entry of catalog) {
for (const schema of entry.schemas) {
diff --git a/packages/examples/acp-demo/README.md b/packages/examples/acp-demo/README.md
index 17e3da78f3..c778ab6c2e 100644
--- a/packages/examples/acp-demo/README.md
+++ b/packages/examples/acp-demo/README.md
@@ -30,6 +30,8 @@ Because the package wires no logger entry, an ACP leaf has **nothing to get wron
| `toolOrder` | — | explicit model-facing tool order (a name list with one `''` rest entry; absent — lexicographic; an unregistered name fails each turn at prompt assembly), routed to `dsh-system-prompt` |
| `tools` | `{ mode: 'native' }` | tool-registry presentation config (`native` / `code` / `both`), routed through `dsh-agent-spine-demo` |
| `skills` | owner defaults | registry-cache, local-provider, and model-facing skill-tool config, routed through `dsh-agent-spine-demo` |
+| `toolBash` | owner defaults | model-facing bash config routed through `dsh-agent-spine-demo`, including bash's producer-local `enableRunInBackground` |
+| `toolTasks` | owner defaults | generic `task_output` wait bounds routed through `dsh-agent-spine-demo` |
| `persistenceRoot` | `./.sessions` | the JSONL backend's root directory |
The leaf supplies the swappable backends: an LLM adapter (`llm-deepseek` for the real model, `llm-replay` for keyless snapshot replay) and a bash executor.
diff --git a/packages/examples/acp-demo/src/index.ts b/packages/examples/acp-demo/src/index.ts
index 0439363301..917cb128a6 100644
--- a/packages/examples/acp-demo/src/index.ts
+++ b/packages/examples/acp-demo/src/index.ts
@@ -41,6 +41,10 @@ export interface Config {
persistenceRoot?: string
/** Skill registry, local-provider, and model-facing consumer config forwarded to agent-spine-demo. */
skills?: agentCore.SkillConfig
+ /** Model-facing bash tool config forwarded through agent-core. */
+ toolBash?: NonNullable
+ /** Generic background-task control-tool config forwarded through agent-core. */
+ toolTasks?: NonNullable
}
// Each front door owns a complete, directly readable config schema; extracting
@@ -58,6 +62,8 @@ export const Config: z = z.object({
// apply() fallback through one named constant while retaining both boundaries.
persistenceRoot: z.string().default('./.sessions'),
skills: agentCore.SkillConfigSchema,
+ toolBash: agentCore.ToolBashConfigSchema,
+ toolTasks: agentCore.ToolTasksConfigSchema,
})
/* jscpd:ignore-end */
@@ -74,6 +80,8 @@ export function apply(ctx: Context, config: Config): void {
...config.toolOrder !== undefined ? { toolOrder: config.toolOrder } : {},
...config.tools !== undefined ? { tools: config.tools } : {},
...config.skills !== undefined ? { skills: config.skills } : {},
+ ...config.toolBash !== undefined ? { toolBash: config.toolBash } : {},
+ ...config.toolTasks !== undefined ? { toolTasks: config.toolTasks } : {},
})
ctx.plugin(UserInteractionService)
ctx.plugin(SessionPersistenceJsonl, { root: config.persistenceRoot ?? './.sessions' })
diff --git a/packages/examples/acp-demo/tests/acp-agent.spec.ts b/packages/examples/acp-demo/tests/acp-agent.spec.ts
index f3495c827c..285e4756d0 100644
--- a/packages/examples/acp-demo/tests/acp-agent.spec.ts
+++ b/packages/examples/acp-demo/tests/acp-agent.spec.ts
@@ -19,8 +19,9 @@ import * as acpAgent from '../src/index.ts'
* ACP operations end-to-end) is the keyless bin smoke in `load-path.e2e.ts`;
* this spec asserts the composition and the persistenceRoot default branch.
*/
-async function mount(config: acpAgent.Config): Promise {
+async function mount(config: acpAgent.Config, withBash = false): Promise {
const ctx = new Context()
+ if (withBash) ctx.provide('bash', { sandboxMode: undefined })
await ctx.plugin(acpAgent, config)
// The bundle mounts its children inside apply() (not awaited there); let their
// fibers settle so the spine services are ready.
@@ -112,6 +113,19 @@ describe('dsh-acp-demo composition', () => {
await ctx.fiber.dispose()
})
+ it('forwards bundled tool config into agent-core', async () => {
+ const ctx = await mount({
+ model: 'mock',
+ toolBash: { enableRunInBackground: false },
+ toolTasks: { waitTimeoutMs: 7, maxWaitTimeoutMs: 11 },
+ skills: await isolatedSkillsConfig(),
+ }, true)
+ const bash = ctx.tools.schemas().find(tool => tool.name === 'bash')
+ expect(Object.keys((bash!.parameters as { properties: Record }).properties))
+ .not.toContain('run_in_background')
+ await ctx.fiber.dispose()
+ })
+
it('exposes its plugin shape', () => {
expect(acpAgent.name).toBe('acp-demo')
expect(acpAgent.Config).toBeDefined()
@@ -134,7 +148,7 @@ describe('dsh-acp-demo composition', () => {
})
}
const assembly = await ctx.get('systemPrompt')!.assemble()
- expect(assembly.tools.map(tool => tool.name)).toEqual(['zulu', 'alpha', 'skill'])
+ expect(assembly.tools.map(tool => tool.name)).toEqual(['zulu', 'alpha', 'skill', 'task_kill', 'task_list', 'task_output'])
await ctx.fiber.dispose()
})
diff --git a/packages/examples/acp-demo/tests/built-bin.e2e.ts b/packages/examples/acp-demo/tests/built-bin.e2e.ts
index 7b5749fee5..9e799b29db 100644
--- a/packages/examples/acp-demo/tests/built-bin.e2e.ts
+++ b/packages/examples/acp-demo/tests/built-bin.e2e.ts
@@ -95,8 +95,19 @@ let consumer: string | undefined
let child: ReturnType | undefined
afterEach(async () => {
- if (child !== undefined) { child.kill('SIGKILL'); child = undefined }
- if (consumer !== undefined) await rm(consumer, { recursive: true, force: true })
+ if (child !== undefined) {
+ const proc = child
+ child = undefined
+ // Windows retains the child's cwd and session-log handles until process
+ // teardown completes, so await exit before removing the temp directory.
+ if (proc.exitCode === null && proc.signalCode === null) {
+ const exited = new Promise((resolve) => { proc.once('exit', () => { resolve() }) })
+ proc.kill('SIGKILL')
+ await exited
+ }
+ }
+ // Windows can briefly retain released handles after exit; retry removal.
+ if (consumer !== undefined) await rm(consumer, { recursive: true, force: true, maxRetries: 10, retryDelay: 100 })
consumer = undefined
})
diff --git a/packages/examples/agent-spine-demo/README.md b/packages/examples/agent-spine-demo/README.md
index a85f3e0889..eb56f9515c 100644
--- a/packages/examples/agent-spine-demo/README.md
+++ b/packages/examples/agent-spine-demo/README.md
@@ -17,9 +17,11 @@ Read this package for the whole plugin tree and its composition order.
@deepseek-ai/dsh-skill skill provider registry
@deepseek-ai/dsh-skill-local local filesystem skill provider
@deepseek-ai/dsh-agent agent registry + agent/* event vocabulary
-@deepseek-ai/dsh-invariants runtime event-contract assertions
-@deepseek-ai/dsh-tool-bash the model-facing bash/bash_output/bash_kill schemas
+@deepseek-ai/dsh-tasks generic background-task registry
+@deepseek-ai/dsh-invariants dev-mode event-contract assertions
+@deepseek-ai/dsh-tool-bash the model-facing bash schema
@deepseek-ai/dsh-tool-skill session-prefix skill catalog + model-facing loader schema
+@deepseek-ai/dsh-tool-tasks task_output/task_list/task_kill schemas + completion notices
@deepseek-ai/dsh-agent-loop THE concrete loop (gets the forwarded `agents`)
(dsh-system-prompt gets the forwarded `persona`)
```
@@ -39,11 +41,12 @@ This is the [interface/implementation/consumer seam](../../../docs/rfc/implement
```ts
import type { Config } from '@deepseek-ai/dsh-agent-spine-demo'
-// { agents?, persona?, toolOrder?, tools?, skills? } — the schema intersects the owner schemas,
+// { agents?, persona?, toolOrder?, tools?, skills?, toolBash?, toolTasks? }
+// The schema intersects the owner schemas,
// so validation and defaulting can never drift from the owners.
```
-The bundle FORWARDS each field to the child that owns it: `agents` to `agent-loop` (default `[]`), so each app supplies its own pre-created agents — a stdio app pre-creates a `main`; the ACP app pre-creates none (it creates agents on demand at `session/new`) — `persona` and `toolOrder` to `dsh-system-prompt`; `tools` to the tool registry for its presentation mode; and `skills.registry`, `skills.local`, and `skills.tool` to the skill registry, local provider, and model-facing consumer. Forwarding is exactly why the owners can live in the shared spine even though the apps disagree on what to configure.
+The bundle FORWARDS each field to the child that owns it: `agents` to `agent-loop` (default `[]`), so each app supplies its own pre-created agents — a stdio app pre-creates a `main`; the ACP app pre-creates none (it creates agents on demand at `session/new`) — `persona` and `toolOrder` to `dsh-system-prompt`; `tools` to the tool registry for its presentation mode; `skills.registry`, `skills.local`, and `skills.tool` to the skill registry, local provider, and model-facing consumer; and `toolBash`/`toolTasks` to the two model-facing tool plugins the bundle owns. `toolBash.enableRunInBackground` controls only the bash producer, while `toolTasks` controls generic `task_output` wait bounds; independently loaded producers keep their own config. Forwarding is exactly why the owners can live in the shared spine even though the apps disagree on what to configure.
## Why a code bundle, not a shared YAML include
diff --git a/packages/examples/agent-spine-demo/package.json b/packages/examples/agent-spine-demo/package.json
index 049530872a..d328043507 100644
--- a/packages/examples/agent-spine-demo/package.json
+++ b/packages/examples/agent-spine-demo/package.json
@@ -1,6 +1,6 @@
{
"name": "@deepseek-ai/dsh-agent-spine-demo",
- "description": "The default executor-less/UI-less agent spine as one Cordis bundle plugin (timer + llm + sessions + system-prompt + tools + skills + agents + invariants + tool-bash + tool-skill + agent-loop)",
+ "description": "The default executor-less/UI-less agent spine as one Cordis bundle plugin (timer + llm + sessions + system-prompt + tools + skills + agents + tasks + invariants + tool-bash + tool-skill + tool-tasks + agent-loop)",
"version": "0.0.1",
"private": true,
"type": "module",
@@ -31,8 +31,10 @@
"@deepseek-ai/dsh-skill": "^0.0.1",
"@deepseek-ai/dsh-skill-local": "^0.0.1",
"@deepseek-ai/dsh-system-prompt": "^0.0.1",
+ "@deepseek-ai/dsh-tasks": "^0.0.1",
"@deepseek-ai/dsh-tool-bash": "^0.0.1",
"@deepseek-ai/dsh-tool-skill": "^0.0.1",
+ "@deepseek-ai/dsh-tool-tasks": "^0.0.1",
"@deepseek-ai/dsh-tools": "^0.0.1",
"cordis": "^4.0.0-rc.7"
},
@@ -46,8 +48,10 @@
"@deepseek-ai/dsh-skill": "workspace:^",
"@deepseek-ai/dsh-skill-local": "workspace:^",
"@deepseek-ai/dsh-system-prompt": "workspace:^",
+ "@deepseek-ai/dsh-tasks": "workspace:^",
"@deepseek-ai/dsh-tool-bash": "workspace:^",
"@deepseek-ai/dsh-tool-skill": "workspace:^",
+ "@deepseek-ai/dsh-tool-tasks": "workspace:^",
"@deepseek-ai/dsh-tools": "workspace:^",
"cordis": "^4.0.0-rc.7"
},
diff --git a/packages/examples/agent-spine-demo/src/index.ts b/packages/examples/agent-spine-demo/src/index.ts
index d1aecaa4c0..b3d6ca22bc 100644
--- a/packages/examples/agent-spine-demo/src/index.ts
+++ b/packages/examples/agent-spine-demo/src/index.ts
@@ -1,7 +1,8 @@
/**
* Default executor-less, UI-less agent spine. It bundles the common services,
- * concrete loop, local skill provider, and model-facing bash/skill consumers;
- * deployments still choose the LLM adapter, bash executor, and presentation.
+ * background-task registry and controls, concrete loop, local skill provider,
+ * and model-facing bash/skill consumers; deployments still choose the LLM
+ * adapter, bash executor, and presentation.
* The plugin intentionally exposes named exports only because Loader default
* unwrapping would discard its `Config` schema (see docs/postmortem/0001).
* @module @deepseek-ai/dsh-agent-spine-demo
@@ -17,9 +18,11 @@ import ToolRegistry, { type Config as ToolsConfig } from '@deepseek-ai/dsh-tools
import SkillService, { type Config as SkillRegistryConfig } from '@deepseek-ai/dsh-skill'
import * as SkillLocal from '@deepseek-ai/dsh-skill-local'
import AgentRegistry from '@deepseek-ai/dsh-agent'
+import TaskService from '@deepseek-ai/dsh-tasks'
import * as invariants from '@deepseek-ai/dsh-invariants'
import * as toolBash from '@deepseek-ai/dsh-tool-bash'
import * as toolSkill from '@deepseek-ai/dsh-tool-skill'
+import * as toolTasks from '@deepseek-ai/dsh-tool-tasks'
import AgentLoop, { type Config as AgentLoopConfig } from '@deepseek-ai/dsh-agent-loop'
export const name = 'agent-spine-demo'
@@ -35,13 +38,19 @@ export interface SkillConfig {
}
/**
- * Bundle config: each field forwarded verbatim to the child that owns it — `agents` to the
- * agent loop (an app that pre-creates no agents, like the ACP bridge, omits it),
- * `persona` and `toolOrder` to the system-prompt plugin (the deployment's persona section and
- * the explicit model-facing tool order), the `tools` object to the tool registry (its
- * presentation `mode`), and `skills` to the skill registry/local provider/tool consumer.
- * The schema intersects the owners' schemas, which supply defaults for every
- * optional input and keep validation from drifting.
+ * Bundle config: each field forwarded verbatim to the child that owns it —
+ * `agents` to the agent loop (an app that pre-creates no agents, like the ACP
+ * bridge, simply omits it), `persona` and `toolOrder` to the system-prompt
+ * plugin (the deployment's persona section and the explicit model-facing tool
+ * order), the `tools` object to the tool registry (its presentation `mode`),
+ * and `toolBash`/`toolTasks` to the two model-facing tool plugins this bundle
+ * owns. Producer opt-in stays producer-local: `toolBash` configures bash only;
+ * future background-capable tools remain independently composed plugins.
+ * Every field is optional INPUT here because each owner's schema
+ * supplies the default (`[]` / `''` / absent — lexicographic / `native`); the
+ * schema is the INTERSECTION of the owners' own schemas (the registry's
+ * nested under its `tools` key), so validation and defaulting can never
+ * drift from them.
*/
export interface Config {
/** The agent-loop `agents` list (see dsh-agent-loop's `Config`). */
@@ -54,6 +63,10 @@ export interface Config {
tools?: ToolsConfig
/** Skill registry, local provider, and model-facing consumer config. */
skills?: SkillConfig
+ /** Model-facing bash tool config, including this producer's background opt-in. */
+ toolBash?: toolBash.Config
+ /** Generic background-task control-tool wait bounds. */
+ toolTasks?: toolTasks.Config
}
/** The skill config schema exported for app packages that forward `skills`. */
@@ -63,11 +76,22 @@ export const SkillConfigSchema: z = z.object({
tool: toolSkill.Config,
})
+/** The bash-tool config schema exported for app packages that forward `toolBash`. */
+export const ToolBashConfigSchema: z = toolBash.Config
+
+/** The task-control-tool config schema exported for app packages that forward `toolTasks`. */
+export const ToolTasksConfigSchema: z = toolTasks.Config
+
/** Intersect the owners' schemas so validation + defaulting stay identical. */
export const Config = z.intersect([
AgentLoop.Config,
SystemPrompt.Config,
- z.object({ tools: ToolRegistry.Config, skills: SkillConfigSchema }),
+ z.object({
+ tools: ToolRegistry.Config,
+ skills: SkillConfigSchema,
+ toolBash: ToolBashConfigSchema,
+ toolTasks: ToolTasksConfigSchema,
+ }),
]) as unknown as z
/**
@@ -92,8 +116,10 @@ export function apply(ctx: Context, config: Config): void {
ctx.plugin(SkillService, config.skills?.registry ?? {})
ctx.plugin(SkillLocal, config.skills?.local ?? {})
ctx.plugin(AgentRegistry)
+ ctx.plugin(TaskService)
ctx.plugin(invariants)
- ctx.plugin(toolBash)
+ ctx.plugin(toolBash, config.toolBash ?? {})
ctx.plugin(toolSkill, config.skills?.tool ?? {})
+ ctx.plugin(toolTasks, config.toolTasks ?? {})
ctx.plugin(AgentLoop, { agents: config.agents ?? [] })
}
diff --git a/packages/examples/agent-spine-demo/tests/agent-core.spec.ts b/packages/examples/agent-spine-demo/tests/agent-core.spec.ts
index ecf997f3cd..74dbfe5484 100644
--- a/packages/examples/agent-spine-demo/tests/agent-core.spec.ts
+++ b/packages/examples/agent-spine-demo/tests/agent-core.spec.ts
@@ -1,4 +1,4 @@
-import { describe, expect, it } from 'vitest'
+import { describe, expect, it, vi } from 'vitest'
import { mkdir, mkdtemp, writeFile } from 'node:fs/promises'
import { join } from 'node:path'
import { tmpdir } from 'node:os'
@@ -7,7 +7,13 @@ import Loader from '@cordisjs/plugin-loader'
import { TOOL_ORDER_REST } from '@deepseek-ai/dsh-system-prompt'
import * as agentCore from '../src/index.ts'
import { AgentId, agentEvents, type Agent } from '@deepseek-ai/dsh-agent'
-import type { Message } from '@deepseek-ai/dsh-llm'
+import { CallId, type Message } from '@deepseek-ai/dsh-llm'
+
+declare module '@deepseek-ai/dsh-tasks' {
+ interface TaskKindMap {
+ probe: 'probe'
+ }
+}
async function composePrefix(ctx: Context, cwd: string): Promise {
const agent = { session: { header: { cwd } } } as unknown as Agent
@@ -28,12 +34,13 @@ async function composePrefix(ctx: Context, cwd: string): Promise {
* Loader-path guard (export shape, `unwrapExports`) is the app packages' keyless
* bin smokes; here we assert the composition + config forwarding.
*/
-async function mount(config?: agentCore.Config): Promise {
+async function mount(config?: agentCore.Config, withBash = false): Promise {
const oldDshHome = process.env.DSH_HOME
const oldAgentsHome = process.env.DSH_AGENTS_HOME
process.env.DSH_HOME = await mkdtemp(join(tmpdir(), 'dsh-agent-spine-demo-home-'))
process.env.DSH_AGENTS_HOME = await mkdtemp(join(tmpdir(), 'dsh-agent-spine-demo-agents-'))
const ctx = new Context()
+ if (withBash) ctx.provide('bash', { sandboxMode: undefined })
try {
await ctx.plugin(agentCore, config)
// The bundle mounts its children inside apply() (not awaited there); let their
@@ -86,6 +93,7 @@ describe('dsh-agent-spine-demo bundle', () => {
expect(ctx.get('tools')).toBeDefined()
expect(ctx.get('skills')).toBeDefined()
expect(ctx.get('agents')).toBeDefined()
+ expect(ctx.get('tasks')).toBeDefined()
expect(ctx.get('agentLoop')).toBeDefined()
await ctx.fiber.dispose()
})
@@ -153,6 +161,33 @@ describe('dsh-agent-spine-demo bundle', () => {
await ctx.fiber.dispose()
})
+ it('forwards its bundled tool configs to tool-bash and tool-tasks', async () => {
+ const ctx = await mount({
+ toolBash: { enableRunInBackground: false },
+ toolTasks: { waitTimeoutMs: 7, maxWaitTimeoutMs: 11 },
+ }, true)
+
+ const bash = ctx.tools.schemas().find(tool => tool.name === 'bash')
+ expect(bash).toBeDefined()
+ expect(Object.keys((bash!.parameters as { properties: Record }).properties))
+ .not.toContain('run_in_background')
+
+ const id = ctx.tasks.start({
+ kind: 'probe',
+ label: 'config forwarding probe',
+ run: () => ({ cancel: () => {}, done: Promise.resolve({ status: 'completed' }) }),
+ })
+ const wait = vi.spyOn(ctx.tasks, 'wait')
+ await ctx.tools.execute({
+ callId: CallId('task-config-forwarding'),
+ name: 'task_output',
+ arguments: { task_id: id, wait: true },
+ })
+ expect(wait).toHaveBeenCalledWith(id, 7, undefined, undefined)
+
+ await ctx.fiber.dispose()
+ })
+
it('uses the default skill config when apply is called directly without skills', async () => {
await withIsolatedSkillHomes(async () => {
const ctx = new Context()
@@ -177,7 +212,7 @@ describe('dsh-agent-spine-demo bundle', () => {
})
}
const assembly = await ctx.get('systemPrompt')!.assemble()
- expect(assembly.tools.map(tool => tool.name)).toEqual(['zulu', 'alpha', 'skill'])
+ expect(assembly.tools.map(tool => tool.name)).toEqual(['zulu', 'alpha', 'skill', 'task_kill', 'task_list', 'task_output'])
await ctx.fiber.dispose()
})
diff --git a/packages/examples/agent-spine-demo/tsconfig.json b/packages/examples/agent-spine-demo/tsconfig.json
index 4fd0a81e97..faea4b949f 100644
--- a/packages/examples/agent-spine-demo/tsconfig.json
+++ b/packages/examples/agent-spine-demo/tsconfig.json
@@ -11,9 +11,6 @@
{
"path": "../../../vendor/cordis"
},
- {
- "path": "../../../vendor/schemastery"
- },
{
"path": "../../../vendor/timer"
},
@@ -52,6 +49,12 @@
},
{
"path": "../../bash/tool-bash"
+ },
+ {
+ "path": "../../tasks/tasks"
+ },
+ {
+ "path": "../../tasks/tool-tasks"
}
]
}
diff --git a/packages/examples/stdio-demo/README.md b/packages/examples/stdio-demo/README.md
index 5087a2fca0..98f639491e 100644
--- a/packages/examples/stdio-demo/README.md
+++ b/packages/examples/stdio-demo/README.md
@@ -30,6 +30,8 @@ The leaf `cordis.yml` supplies only the **swappable backends** — an LLM adapte
| `toolOrder` | — | explicit model-facing tool order (a name list with one `''` rest entry; absent — lexicographic; an unregistered name fails each turn at prompt assembly), routed to `dsh-system-prompt` |
| `tools` | `{ mode: 'native' }` | tool-registry presentation config (`native` / `code` / `both`), routed through `dsh-agent-spine-demo` |
| `skills` | owner defaults | registry-cache, local-provider, and model-facing skill-tool config, routed through `dsh-agent-spine-demo` |
+| `toolBash` | owner defaults | model-facing bash config routed through `dsh-agent-spine-demo`, including bash's producer-local `enableRunInBackground` |
+| `toolTasks` | owner defaults | generic `task_output` wait bounds routed through `dsh-agent-spine-demo` |
| `persistenceRoot` | `./.sessions` | the JSONL backend's root directory |
| `welcome` | `ready.` | the stdin-chat banner |
| `resumeSessionId` | — | resume a persisted session id instead of starting fresh (sourced from an env var in the leaf) |
diff --git a/packages/examples/stdio-demo/src/index.ts b/packages/examples/stdio-demo/src/index.ts
index 89f4142af6..73f163d7f4 100644
--- a/packages/examples/stdio-demo/src/index.ts
+++ b/packages/examples/stdio-demo/src/index.ts
@@ -48,6 +48,10 @@ export interface Config {
welcome?: string
/** Skill registry, local-provider, and model-facing consumer config forwarded to agent-spine-demo. */
skills?: agentCore.SkillConfig
+ /** Model-facing bash tool config forwarded through agent-core. */
+ toolBash?: NonNullable
+ /** Generic background-task control-tool config forwarded through agent-core. */
+ toolTasks?: NonNullable
/**
* If set, the `main` agent RESUMES this persisted session id instead of
* starting fresh. Sourced from an env var in the leaf `cordis.yml`
@@ -69,6 +73,8 @@ export const Config: z = z.object({
persistenceRoot: z.string().default('./.sessions'),
welcome: z.string().default('ready.'),
skills: agentCore.SkillConfigSchema,
+ toolBash: agentCore.ToolBashConfigSchema,
+ toolTasks: agentCore.ToolTasksConfigSchema,
resumeSessionId: z.string(),
})
@@ -92,6 +98,8 @@ export function apply(ctx: Context, config: Config): void {
...config.resumeSessionId !== undefined ? { resumeSessionId: SessionId(config.resumeSessionId) } : {},
}],
...config.skills !== undefined ? { skills: config.skills } : {},
+ ...config.toolBash !== undefined ? { toolBash: config.toolBash } : {},
+ ...config.toolTasks !== undefined ? { toolTasks: config.toolTasks } : {},
})
ctx.plugin(SessionPersistenceJsonl, { root: config.persistenceRoot ?? './.sessions' })
ctx.plugin(UserInteractionService)
diff --git a/packages/examples/stdio-demo/tests/built-bin.e2e.ts b/packages/examples/stdio-demo/tests/built-bin.e2e.ts
index fdbeb2b8e4..ec14440b18 100644
--- a/packages/examples/stdio-demo/tests/built-bin.e2e.ts
+++ b/packages/examples/stdio-demo/tests/built-bin.e2e.ts
@@ -116,7 +116,8 @@ function runBuiltBin(cwd: string, configArg: string, line: string): Promise<{ st
let consumer: string | undefined
afterEach(async () => {
- if (consumer !== undefined) await rm(consumer, { recursive: true, force: true })
+ // Windows can briefly retain released handles after exit; retry removal.
+ if (consumer !== undefined) await rm(consumer, { recursive: true, force: true, maxRetries: 10, retryDelay: 100 })
consumer = undefined
})
diff --git a/packages/examples/stdio-demo/tests/stdio-agent.spec.ts b/packages/examples/stdio-demo/tests/stdio-agent.spec.ts
index 20bcaa5704..b5fb0e0207 100644
--- a/packages/examples/stdio-demo/tests/stdio-agent.spec.ts
+++ b/packages/examples/stdio-demo/tests/stdio-agent.spec.ts
@@ -15,8 +15,9 @@ import * as stdioAgent from '../src/index.ts'
* keyless echo smoke; this tier pins the export shape because an inject-less app could otherwise
* survive namespace collapse while silently losing its schema.
*/
-async function mount(config: stdioAgent.Config): Promise {
+async function mount(config: stdioAgent.Config, withBash = false): Promise {
const ctx = new Context()
+ if (withBash) ctx.provide('bash', { sandboxMode: undefined })
await ctx.plugin(stdioAgent, config)
// The app mounts its children inside apply() (not awaited there); let their
// fibers settle so the spine services + the pre-created agent are ready.
@@ -126,6 +127,19 @@ describe('dsh-stdio-demo app', () => {
await ctx.fiber.dispose()
})
+ it('forwards bundled tool config into agent-core', async () => {
+ const ctx = await mount({
+ model: 'mock',
+ toolBash: { enableRunInBackground: false },
+ toolTasks: { waitTimeoutMs: 7, maxWaitTimeoutMs: 11 },
+ skills: await isolatedSkillsConfig(),
+ }, true)
+ const bash = ctx.tools.schemas().find(tool => tool.name === 'bash')
+ expect(Object.keys((bash!.parameters as { properties: Record }).properties))
+ .not.toContain('run_in_background')
+ await ctx.fiber.dispose()
+ })
+
it('exposes its name and Config schema', () => {
expect(stdioAgent.name).toBe('stdio-demo')
expect(stdioAgent.Config).toBeDefined()
@@ -148,7 +162,7 @@ describe('dsh-stdio-demo app', () => {
})
}
const assembly = await ctx.get('systemPrompt')!.assemble()
- expect(assembly.tools.map(tool => tool.name)).toEqual(['zulu', 'alpha', 'ask_user_question', 'skill'])
+ expect(assembly.tools.map(tool => tool.name)).toEqual(['zulu', 'alpha', 'ask_user_question', 'skill', 'task_kill', 'task_list', 'task_output'])
await ctx.fiber.dispose()
})
diff --git a/packages/hooks/hook-protocol/tests/runner.spec.ts b/packages/hooks/hook-protocol/tests/runner.spec.ts
index 6f52198a93..5d3f7147f2 100644
--- a/packages/hooks/hook-protocol/tests/runner.spec.ts
+++ b/packages/hooks/hook-protocol/tests/runner.spec.ts
@@ -25,7 +25,6 @@ function recordingBash(run: (spec: BashExecSpec) => Promise): {
...request.signal ? { signal: request.signal } : {},
...request.stdin !== undefined ? { stdin: request.stdin } : {},
...request.env !== undefined ? { env: request.env } : {},
- owner: request.owner,
sandboxMode: request.sandboxMode,
}
},
diff --git a/packages/sandbox/sandbox-local/README.md b/packages/sandbox/sandbox-local/README.md
index fa0ff7257f..cbd765bbf9 100644
--- a/packages/sandbox/sandbox-local/README.md
+++ b/packages/sandbox/sandbox-local/README.md
@@ -2,6 +2,8 @@
Local implementation of the [`dsh-sandbox`](../sandbox/) seam. It selects and caches one platform runner: Linux prefers a working `bwrap` then Landlock; macOS uses Seatbelt. Multiple candidates are probed in order, while a sole candidate is selected directly.
+The package root exports the default and named `LocalSandboxProvider` plugin, `Config`, and its public test-injection seam; platform profile builders stay internal.
+
Unsupported platforms and unusable runners fail closed with `SANDBOX_UNAVAILABLE`; execution never silently falls through unconfined. Each wrap carries runner-failure signatures so consumers can distinguish a broken sandbox from a command failure. The [sandbox RFC](../../../docs/rfc/implemented/feature/2026-07-06-sandbox.md) owns selection rationale and profile differences.
Policy is per call; the provider stores only the mechanism and cached runner verdict. Each wrap reports enforcement completeness plus backend-specific denial and runner-failure signatures. `runnerCommand` is an operator assertion of a bwrap-shaped runner and skips probes, but missing or unexecutable commands still fail closed at execution. Because its mechanism is unknown, it carries both Linux denial dialects. `probeTimeoutMs` bounds functional probes. The [sandbox RFC](../../../docs/rfc/implemented/feature/2026-07-06-sandbox.md) owns selection and failure semantics.
diff --git a/packages/sandbox/sandbox-local/src/index.ts b/packages/sandbox/sandbox-local/src/index.ts
index cc464eb5c4..98dc86d23e 100644
--- a/packages/sandbox/sandbox-local/src/index.ts
+++ b/packages/sandbox/sandbox-local/src/index.ts
@@ -7,14 +7,13 @@
*/
import { spawnSync } from 'node:child_process'
-import { realpathSync } from 'node:fs'
-import { tmpdir } from 'node:os'
-import { grantArgs as landlockGrantArgs, LAUNCHER_BIN, launcherPath as landlockLauncherPath, probe as defaultProbeLandlock } from 'node-addon-landlock-run'
+import { LAUNCHER_BIN, launcherPath as landlockLauncherPath, probe as defaultProbeLandlock } from 'node-addon-landlock-run'
import { Context } from 'cordis'
import z from 'schemastery'
import { assertNever } from '@deepseek-ai/dsh-llm'
import { SandboxProvider, SandboxUnavailableError } from '@deepseek-ai/dsh-sandbox'
import type { ConfinedArgv, ConfinedSandboxMode, SandboxEnforcement, SandboxPolicy } from '@deepseek-ai/dsh-sandbox'
+import { bwrapProfileArgs, landlockProfileArgs, seatbeltProfileArgs } from './profiles.ts'
/** Plugin config. All optional — `static Config` supplies the defaults. */
export interface Config {
@@ -38,77 +37,6 @@ export interface Config {
probeTimeoutMs?: number
}
-/**
- * Build a bwrap profile: the host is read-only with fresh `/dev` and `/proc`;
- * workspace-write overlays writable temp and workspace mounts. PID and network
- * isolation are intentionally outside the file-effect policy.
- *
- * @param policy - the file-effect policy to express as bwrap arguments.
- * @returns the bwrap profile arguments (before the trailing `--` + argv).
- */
-export function bwrapProfileArgs(policy: SandboxPolicy): string[] {
- const args = ['--ro-bind', '/', '/', '--dev', '/dev', '--proc', '/proc', '--die-with-parent']
- if (policy.mode === 'workspace-write') {
- args.push('--tmpfs', '/tmp')
- args.push('--bind', policy.workspaceRoot, policy.workspaceRoot)
- }
- return args
-}
-
-/**
- * Build Landlock grants for the same file policy without synthetic mounts.
- * Read-only grants only `/dev/null` for writes; workspace-write also grants the
- * host temp root and workspace.
- *
- * @param policy - the file-effect policy to express as launcher grants.
- * @returns the launcher grant arguments (before `--` + argv).
- */
-export function landlockProfileArgs(policy: SandboxPolicy): string[] {
- const readWrite = ['/dev/null']
- if (policy.mode === 'workspace-write') {
- readWrite.push('/tmp', policy.workspaceRoot)
- }
- return landlockGrantArgs({ readOnly: ['/'], readWrite })
-}
-
-/**
- * Resolve a granted root to the path the kernel actually sees. Seatbelt path
- * filters match the CANONICAL path (symlinks resolved), and the roots this
- * profile grants are symlinked on every macOS: `/tmp` is `/private/tmp` and
- * the user temp dir lives under `/var` → `/private/var` — an as-spelled
- * grant would match nothing.
- */
-function canonicalPath(path: string): string {
- try {
- return realpathSync(path)
- } catch {
- // An unresolved grant matches nothing until the named path exists; keep its spelling.
- return path
- }
-}
-
-/** Quote one path as an SBPL string literal (backslashes and double quotes escaped). */
-function sbplString(path: string): string {
- return `"${path.replaceAll('\\', String.raw`\\`).replaceAll('"', String.raw`\"`)}"`
-}
-
-/**
- * Build a Seatbelt profile that denies file writes then allows `/dev/null` and,
- * for workspace-write, the canonical workspace, host temp, and per-user macOS
- * temp roots. Network and process visibility remain unrestricted.
- *
- * @param policy - the file-effect policy to express as an SBPL profile.
- * @returns the `sandbox-exec` arguments (`-p` + profile, before `--` + argv).
- */
-export function seatbeltProfileArgs(policy: SandboxPolicy): string[] {
- const forms = ['(version 1)', '(allow default)', '(deny file-write*)', `(allow file-write* (literal ${sbplString('/dev/null')}))`]
- if (policy.mode === 'workspace-write') {
- const roots = [...new Set([policy.workspaceRoot, '/tmp', tmpdir()].map(canonicalPath))]
- forms.push(`(allow file-write* ${roots.map(root => `(subpath ${sbplString(root)})`).join(' ')})`)
- }
- return ['-p', forms.join(' ')]
-}
-
/** Probe whether `bwrap` can create the profile; the provider caches the bounded result. */
function defaultProbeBwrap(timeoutMs: number): boolean {
const probe = spawnSync('bwrap', ['--ro-bind', '/', '/', '--dev', '/dev', '--proc', '/proc', '--die-with-parent', '--', 'true'], {
diff --git a/packages/sandbox/sandbox-local/src/profiles.ts b/packages/sandbox/sandbox-local/src/profiles.ts
new file mode 100644
index 0000000000..9303583cbb
--- /dev/null
+++ b/packages/sandbox/sandbox-local/src/profiles.ts
@@ -0,0 +1,67 @@
+/**
+ * Internal platform-profile builders for the local sandbox provider.
+ *
+ * @module @deepseek-ai/dsh-sandbox-local/profiles
+ */
+
+import { realpathSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { grantArgs as landlockGrantArgs } from 'node-addon-landlock-run'
+import type { SandboxPolicy } from '@deepseek-ai/dsh-sandbox'
+
+/**
+ * Build the bwrap profile arguments for one file-effect policy.
+ * @param policy - file-effect policy to express as bwrap mounts.
+ * @returns profile arguments before the trailing separator and command argv.
+ */
+export function bwrapProfileArgs(policy: SandboxPolicy): string[] {
+ const args = ['--ro-bind', '/', '/', '--dev', '/dev', '--proc', '/proc', '--die-with-parent']
+ if (policy.mode === 'workspace-write') {
+ args.push('--tmpfs', '/tmp')
+ args.push('--bind', policy.workspaceRoot, policy.workspaceRoot)
+ }
+ return args
+}
+
+/**
+ * Build the Landlock launcher grants for one file-effect policy.
+ * @param policy - file-effect policy to express as Landlock allow-list grants.
+ * @returns launcher grant arguments before the trailing separator and command argv.
+ */
+export function landlockProfileArgs(policy: SandboxPolicy): string[] {
+ const readWrite = ['/dev/null']
+ if (policy.mode === 'workspace-write') {
+ readWrite.push('/tmp', policy.workspaceRoot)
+ }
+ return landlockGrantArgs({ readOnly: ['/'], readWrite })
+}
+
+/** Resolve a granted root to the canonical path the Seatbelt kernel sees. */
+function canonicalPath(path: string): string {
+ try {
+ return realpathSync(path)
+ } catch {
+ // Missing or unreadable roots stay as spelled; an unresolved root grants
+ // nothing until it exists, which is the conservative outcome.
+ return path
+ }
+}
+
+/** Quote one path as an SBPL string literal. */
+function sbplString(path: string): string {
+ return `"${path.replaceAll('\\', String.raw`\\`).replaceAll('"', String.raw`\"`)}"`
+}
+
+/**
+ * Build the sandbox-exec arguments and SBPL profile for one policy.
+ * @param policy - file-effect policy to express as an SBPL profile.
+ * @returns sandbox-exec arguments before the trailing separator and command argv.
+ */
+export function seatbeltProfileArgs(policy: SandboxPolicy): string[] {
+ const forms = ['(version 1)', '(allow default)', '(deny file-write*)', `(allow file-write* (literal ${sbplString('/dev/null')}))`]
+ if (policy.mode === 'workspace-write') {
+ const roots = [...new Set([policy.workspaceRoot, '/tmp', tmpdir()].map(canonicalPath))]
+ forms.push(`(allow file-write* ${roots.map(root => `(subpath ${sbplString(root)})`).join(' ')})`)
+ }
+ return ['-p', forms.join(' ')]
+}
diff --git a/packages/sandbox/sandbox-local/tests/bwrap.e2e.ts b/packages/sandbox/sandbox-local/tests/bwrap.e2e.ts
index 1e818e1bdf..9a093e4632 100644
--- a/packages/sandbox/sandbox-local/tests/bwrap.e2e.ts
+++ b/packages/sandbox/sandbox-local/tests/bwrap.e2e.ts
@@ -6,7 +6,8 @@ import { join } from 'node:path'
import { afterEach, describe, expect, it } from 'vitest'
import { Context } from 'cordis'
import type { SandboxPolicy } from '@deepseek-ai/dsh-sandbox'
-import { bwrapProfileArgs, LocalSandboxProvider } from '@deepseek-ai/dsh-sandbox-local'
+import { LocalSandboxProvider } from '@deepseek-ai/dsh-sandbox-local'
+import { bwrapProfileArgs } from '../src/profiles.ts'
/**
* Keyless backend integration through `confine()` and a real bwrap process. With no rung forced,
diff --git a/packages/sandbox/sandbox-local/tests/local.spec.ts b/packages/sandbox/sandbox-local/tests/local.spec.ts
index c221544861..f9efbf992c 100644
--- a/packages/sandbox/sandbox-local/tests/local.spec.ts
+++ b/packages/sandbox/sandbox-local/tests/local.spec.ts
@@ -15,12 +15,10 @@ import { Context } from 'cordis'
import { SANDBOX_UNAVAILABLE, SandboxUnavailableError } from '@deepseek-ai/dsh-sandbox'
import type { SandboxPolicy } from '@deepseek-ai/dsh-sandbox'
import {
- bwrapProfileArgs,
- landlockProfileArgs,
LocalSandboxProvider,
- seatbeltProfileArgs,
} from '@deepseek-ai/dsh-sandbox-local'
import type { Config } from '@deepseek-ai/dsh-sandbox-local'
+import { bwrapProfileArgs, landlockProfileArgs, seatbeltProfileArgs } from '../src/profiles.ts'
const RO: SandboxPolicy = { mode: 'read-only', workspaceRoot: '/ws' }
const WW: SandboxPolicy = { mode: 'workspace-write', workspaceRoot: '/ws' }
diff --git a/packages/sandbox/sandbox-local/tests/seatbelt.e2e.ts b/packages/sandbox/sandbox-local/tests/seatbelt.e2e.ts
index 2c5a026ddb..6d645b1a3b 100644
--- a/packages/sandbox/sandbox-local/tests/seatbelt.e2e.ts
+++ b/packages/sandbox/sandbox-local/tests/seatbelt.e2e.ts
@@ -6,7 +6,8 @@ import { join } from 'node:path'
import { afterEach, describe, expect, it } from 'vitest'
import { Context } from 'cordis'
import type { SandboxPolicy } from '@deepseek-ai/dsh-sandbox'
-import { LocalSandboxProvider, seatbeltProfileArgs } from '@deepseek-ai/dsh-sandbox-local'
+import { LocalSandboxProvider } from '@deepseek-ai/dsh-sandbox-local'
+import { seatbeltProfileArgs } from '../src/profiles.ts'
/**
* Keyless backend integration through `confine()` and a real macOS Seatbelt process, with Linux
diff --git a/packages/sdk/README.md b/packages/sdk/README.md
new file mode 100644
index 0000000000..953d52ea76
--- /dev/null
+++ b/packages/sdk/README.md
@@ -0,0 +1,15 @@
+# SDK packages
+
+Developer tooling for creating, editing, building, and running DeepSeek Harness projects.
+
+The [feature RFC](../../docs/rfc/proposed/feature/2026-07-14-sdk-developer-projects.md) owns the developer workflow; the [architecture RFC](../../docs/rfc/proposed/architecture/2026-07-15-sdk-project-editing-architecture.md) owns the package and project-editing boundaries.
+
+| Package | Role |
+|---|---|
+| [`helper`](helper/README.md) | Project aggregate, edit session, builtin features, project documents, templates, package managers, and prompt abstraction |
+| [`scripts`](scripts/README.md) | The `dsh-sdk` launcher: `start`, `dev`, `build`, and interactive `config` |
+| [`create-sdk`](create-sdk/README.md) | The `npm create @deepseek-ai/sdk` initializer |
+
+`@deepseek-ai/create-sdk` is the one package-name exception to the repository's `@deepseek-ai/dsh-*` rule: npm's scoped initializer convention requires that name for `npm create @deepseek-ai/sdk`.
+
+Generated projects keep `cordis.yml` as the only runtime plugin tree. `dsh-sdk dev` adds TypeScript and local-workspace resolution around that same file; it does not create a development-only config.
diff --git a/packages/sdk/create-sdk/README.md b/packages/sdk/create-sdk/README.md
new file mode 100644
index 0000000000..66cddc030a
--- /dev/null
+++ b/packages/sdk/create-sdk/README.md
@@ -0,0 +1,19 @@
+# `@deepseek-ai/create-sdk`
+
+Interactive initializer for `npm create @deepseek-ai/sdk [directory]`. Directory/name/description have visible editable defaults. A tree picker selects features and configures finite options with Right/Left navigation; secret text follows only for selected options. Local plugin creation is one none/plugin/tool choice.
+
+The supported package surface is the `create-sdk` bin. The package root exports no symbols, and workflow, bin, source, and package-manifest subpaths are not exported.
+
+The initializer rejects every existing target path, creates one `SdkProject` edit session, validates and commits it, then asks whether to install NPM dependencies and build. Install or build failures keep the generated project and print a retry command.
+
+Public flags are `[directory]`, `--description`, `--provider`, `--base-url`, `--api-key`, `--model`, `--interface`, `--pm`, and `--install`/`--no-install`. Flags prefill matching questions, but creation always requires a TTY.
+
+The provider choice is DeepSeek or a custom endpoint backed by `llm-pi-ai`. DeepSeek asks only for an API key and uses the public endpoint plus `deepseek-v4-flash`; custom also asks for a base URL. An empty key requires confirmation and creates a commented empty `.env` variable so provider startup fails clearly until it is filled. Existing plugin defaults are omitted; required SDK presets remain typed against the owning package's Config.
+
+## Model Experience
+
+Indirectly, through the generated project composition and its selected runtime plugins.
+
+## Known Limitations and Deferred Work
+
+- **TTY-only creation** — flags prefill questions, but the wizard still requires an interactive terminal before it writes a project.
diff --git a/packages/sdk/create-sdk/package.json b/packages/sdk/create-sdk/package.json
new file mode 100644
index 0000000000..e23415f8dc
--- /dev/null
+++ b/packages/sdk/create-sdk/package.json
@@ -0,0 +1,37 @@
+{
+ "name": "@deepseek-ai/create-sdk",
+ "description": "Create a DeepSeek Harness SDK project with npm create @deepseek-ai/sdk",
+ "version": "0.0.1",
+ "private": true,
+ "type": "module",
+ "main": "lib/index.js",
+ "types": "lib/types/index.d.ts",
+ "bin": {
+ "create-sdk": "lib/bin.js"
+ },
+ "exports": {
+ ".": {
+ "types": "./lib/types/index.d.ts",
+ "default": "./lib/index.js"
+ }
+ },
+ "files": [
+ "lib/index.js",
+ "lib/bin.js",
+ "lib/assets",
+ "lib/types/**/*.d.ts",
+ "lib/types/**/*.d.ts.map",
+ "src"
+ ],
+ "license": "BSD-3-Clause",
+ "dependencies": {
+ "@deepseek-ai/dsh-helper": "workspace:^",
+ "commander": "^15.0.0"
+ },
+ "peerDependencies": {
+ "cordis": "^4.0.0-rc.7"
+ },
+ "devDependencies": {
+ "cordis": "^4.0.0-rc.7"
+ }
+}
diff --git a/packages/sdk/create-sdk/src/args.ts b/packages/sdk/create-sdk/src/args.ts
new file mode 100644
index 0000000000..521132caa9
--- /dev/null
+++ b/packages/sdk/create-sdk/src/args.ts
@@ -0,0 +1,84 @@
+/**
+ * Commander adapter for the create-sdk command surface.
+ *
+ * @module @deepseek-ai/create-sdk/args
+ */
+
+import { Command, Option } from 'commander'
+import type { PackageManagerName, RunInterface } from '@deepseek-ai/dsh-helper'
+
+/** Parsed create command flags before interactive resolution. */
+export interface CreateArgs {
+ directory?: string
+ description?: string
+ provider?: 'deepseek' | 'custom'
+ baseURL?: string
+ apiKey?: string
+ model?: string
+ runInterface?: RunInterface
+ packageManager?: PackageManagerName
+ install?: boolean
+ linkWorkspace?: boolean
+ help: boolean
+}
+
+interface CommanderCreateOptions {
+ description?: string
+ provider?: 'deepseek' | 'custom'
+ baseUrl?: string
+ apiKey?: string
+ model?: string
+ interface?: RunInterface
+ pm?: PackageManagerName
+ install?: boolean
+ linkWorkspace?: boolean
+ help?: boolean
+}
+
+function createProgram(): Command {
+ return new Command()
+ .name('create-sdk')
+ .description('Create a DeepSeek Harness SDK project')
+ .helpOption(false)
+ .showHelpAfterError(false)
+ .exitOverride()
+ .configureOutput({
+ /* v8 ignore next -- the command wrapper renders the package-owned usage template */
+ writeOut: () => {},
+ /* v8 ignore next -- Commander output is deliberately suppressed; errors are returned to the bin wrapper */
+ writeErr: () => {},
+ })
+ .argument('[directory]')
+ .option('-h, --help')
+ .option('--description ')
+ .addOption(new Option('--provider ').choices(['deepseek', 'custom']))
+ .option('--base-url ')
+ .option('--api-key ')
+ .option('--model ')
+ .addOption(new Option('--interface ').choices(['acp', 'stdio', 'embed']))
+ .addOption(new Option('--pm ').choices(['npm', 'pnpm', 'yarn']))
+ .addOption(new Option('--install').default(undefined))
+ .addOption(new Option('--no-install').default(undefined))
+ .option('--link-workspace')
+}
+
+/** Parse create-sdk positionals/options through Commander into a domain-neutral value. */
+export function parseCreateArgs(argv: readonly string[]): CreateArgs {
+ const program = createProgram()
+ program.parse([...argv], { from: 'user' })
+ const options = program.opts()
+ const directory = program.processedArgs[0] as string | undefined
+ return {
+ ...directory === undefined ? {} : { directory },
+ ...options.description === undefined ? {} : { description: options.description },
+ ...options.provider === undefined ? {} : { provider: options.provider },
+ ...options.baseUrl === undefined ? {} : { baseURL: options.baseUrl },
+ ...options.apiKey === undefined ? {} : { apiKey: options.apiKey },
+ ...options.model === undefined ? {} : { model: options.model },
+ ...options.interface === undefined ? {} : { runInterface: options.interface },
+ ...options.pm === undefined ? {} : { packageManager: options.pm },
+ ...options.install === undefined ? {} : { install: options.install },
+ ...options.linkWorkspace ? { linkWorkspace: true } : {},
+ help: options.help ?? false,
+ }
+}
diff --git a/packages/sdk/create-sdk/src/bin.ts b/packages/sdk/create-sdk/src/bin.ts
new file mode 100644
index 0000000000..7a04af8b84
--- /dev/null
+++ b/packages/sdk/create-sdk/src/bin.ts
@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+/**
+ * Self-executing create-sdk command.
+ *
+ * @module @deepseek-ai/create-sdk/bin
+ */
+
+import { runCreateCommand } from './command.ts'
+
+process.exitCode = await runCreateCommand()
diff --git a/packages/sdk/create-sdk/src/command.ts b/packages/sdk/create-sdk/src/command.ts
new file mode 100644
index 0000000000..0c7076c90b
--- /dev/null
+++ b/packages/sdk/create-sdk/src/command.ts
@@ -0,0 +1,111 @@
+/**
+ * Internal create-sdk command composition used by the package bin.
+ *
+ * @module @deepseek-ai/create-sdk/command
+ */
+
+import { readFile } from 'node:fs/promises'
+import {
+ ClackPromptPort,
+ PromptCancelledError,
+ type PackageManagerVersionProbe,
+ type PromptPort,
+} from '@deepseek-ai/dsh-helper'
+import { parseCreateArgs } from './args.ts'
+import { CreateWizard, type ResolvedCreateRequest } from './create-wizard.ts'
+import { scaffoldProject, type ScaffoldResult } from './project-scaffolder.ts'
+import { CREATE_TEMPLATES, packageManagerTemplateModel } from './templates/create-templates.ts'
+
+/** Process and terminal slice used by the initializer. */
+export interface CreateCommandContext {
+ cwd: string
+ stdin: NodeJS.ReadStream
+ stdout: NodeJS.WriteStream
+ stderr: NodeJS.WriteStream
+ releaseVersion?: string
+ versionProbe?: PackageManagerVersionProbe
+ port?: PromptPort
+ setup?: (request: ResolvedCreateRequest) => Promise
+}
+
+/** Read this initializer package's release version in source and built layouts. */
+export async function readCreateSdkVersion(): Promise {
+ const manifest = JSON.parse(await readFile(new URL('../package.json', import.meta.url), 'utf8')) as { version?: unknown }
+ /* v8 ignore next -- this package's checked-in manifest always carries its version */
+ if (typeof manifest.version !== 'string') throw new Error('create-sdk package version is missing')
+ return manifest.version
+}
+
+/** Resolve, write, optionally install, and build one new project. */
+export async function createProject(
+ argv: readonly string[],
+ context: CreateCommandContext,
+): Promise {
+ const args = parseCreateArgs(argv)
+ if (args.help) {
+ context.stdout.write(CREATE_TEMPLATES.usage.render({}))
+ return undefined
+ }
+ if (!context.port && (!context.stdin.isTTY || !context.stdout.isTTY)) {
+ throw new Error('create-sdk requires an interactive TTY')
+ }
+ const wizard = new CreateWizard({
+ args,
+ /* v8 ignore next -- production TTY wiring is exercised by the built-bin smoke */
+ port: context.port ?? new ClackPromptPort(context.stdin, context.stdout),
+ cwd: context.cwd,
+ releaseVersion: context.releaseVersion ?? await readCreateSdkVersion(),
+ ...context.versionProbe ? { versionProbe: context.versionProbe } : {},
+ })
+ const resolved = await wizard.run()
+ const result = await scaffoldProject(resolved.directory, resolved.request)
+ context.stdout.write(CREATE_TEMPLATES.created.render({
+ name: resolved.request.name,
+ directory: resolved.directory,
+ }))
+ if (resolved.install) {
+ try {
+ if (context.setup) await context.setup(resolved)
+ else {
+ await resolved.request.packageManager.install(resolved.directory)
+ await resolved.request.packageManager.build(resolved.directory)
+ }
+ } catch (error) {
+ context.stderr.write(CREATE_TEMPLATES.setupFailure.render({
+ directory: resolved.directory,
+ error: String(error),
+ ...packageManagerTemplateModel(resolved.request.packageManager),
+ }))
+ throw error
+ }
+ }
+ context.stdout.write(CREATE_TEMPLATES.nextSteps.render({
+ directory: resolved.directory,
+ setupRequired: !resolved.install,
+ ...packageManagerTemplateModel(resolved.request.packageManager),
+ }))
+ return result
+}
+
+/** Run the create command with process defaults and convert cancellation to a clean exit. */
+export async function runCreateCommand(
+ argv: readonly string[] = process.argv.slice(2),
+ context: CreateCommandContext = {
+ cwd: process.cwd(),
+ stdin: process.stdin,
+ stdout: process.stdout,
+ stderr: process.stderr,
+ },
+): Promise