@deepseek-ai/dsh-subagent-acp 0.0.1-rc.1

package/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, DeepSeek
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.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 packages/subagent/subagent-acp/README.md
+README.md: 3bccddbca021bed1f8bf5766b9575f3bd7441669
+README.zh.md: 80afd65e5f4815042f05c22e4597bbb2677fb4fc

package/README.md

@@ -0,0 +1,100 @@
+# @deepseek-ai/dsh-subagent-acp
+
+English | [中文](README.zh.md)
+
+The ACP provider runs each subagent in a fresh subprocess and drives it as an Agent Client Protocol client. It is the out-of-process alternative to spawn and fork: the child has its own runtime, session, model configuration, and tools.
+
+## Start and ownership
+
+`start(request)` resolves the child's working directory, then performs `spawn` → ACP `initialize` → `newSession` before it fulfills. Fulfillment therefore means a remote session is ready and ownership has transferred to the caller. A spawn, initialization, new-session, or pre-publication cancellation failure rejects only after the subprocess has been reaped; a working-directory resolution failure rejects before anything is spawned.
+
+The working directory is the configured `cwd` override when set, else the delegating parent session's cwd — never the server process's own cwd, because one server process serves sessions from many workspaces. The parent-derived value must be an absolute path naming a directory the harness can enter (search permission — what a subprocess cwd needs), and the same resolved path becomes both the subprocess cwd and the ACP `session/new` workspace.
+
+The returned run id is minted in the parent namespace. The child server's session id remains private to ACP wire calls because ACP guarantees it only within that fresh child process; using it as the parent lifecycle id could collide with another remote run or a local agent.
+
+After publication, the provider sends the prompt and collects streamed `agent_message_chunk` text into `SubagentResult.output`. A prompt/transport failure resolves with `stopReason: 'error'`, or `aborted` when the required request signal or disposal requested cancellation.
+
+`dispose()` is idempotent. It removes the signal listener, requests ACP cancellation when possible, then runs this backend's own teardown ladder (`disposeAcpChild`) over the seam's verbs: close stdin and wait `disposeEofGraceMs` for cooperative quiescence, then invoke the handle's `terminate()` escalation (SIGTERM, the spawn grace, SIGKILL — Windows force-terminates directly) and await the subprocess owner's whole-tree exit proof. Every run uses a fresh process; process pooling is not implemented.
+
+## Capabilities and context
+
+ACP advertises no start-time capabilities because this process cannot enforce the remote child's depth, tool filter, persona, or structured-output runtime. It also reports `inheritsParentContext: false`: the remote session starts fresh, and the only parent-derived input is the workspace cwd described above — no conversation context crosses the process boundary.
+
+## Configuration
+
+| Key | Default | Meaning |
+|---|---|---|
+| `providerName` | `acp` | Registry name on `ctx.subagents`. |
+| `command` | required | Executable spawned for each run. |
+| `args` | `[]` | Command arguments. |
+| `cwd` | parent session cwd | Working-directory override for the child process and its ACP session; must be non-empty, a relative value resolves against the harness launch directory at load, and the result must name a directory the harness can enter. |
+| `permission` | `reject` | Auto-answer permission requests by rejecting or choosing the first `allow_once` or `allow_always` option. |
+| `env` | `{}` | Explicit child environment layered over a credential-scrubbed parent environment. |
+| `disposeEofGraceMs` | `6000` | Positive grace after stdin EOF before platform termination; it cannot exceed [`MAX_TIMER_DELAY_MS`](../../util/timeout/README.md). |
+| `disposeGraceMs` | `3000` | Positive POSIX grace after SIGTERM before SIGKILL (Windows force-terminates directly); it cannot exceed [`MAX_TIMER_DELAY_MS`](../../util/timeout/README.md). |
+
+```yaml
+- id: subagent-acp
+  name: '@deepseek-ai/dsh-subagent-acp'
+  config:
+    providerName: acp
+    command: node
+    args: ['--import', 'tsx', './packages/examples/acp-demo/src/bin.ts', '--config', './examples/acp-agent/cordis.yml']
+    permission: reject
+    env:
+      DEEPSEEK_API_KEY: !!js process.env.DEEPSEEK_API_KEY
+```
+
+## Stop-reason mapping
+
+| ACP | Harness |
+|---|---|
+| `end_turn` | `completed` |
+| `max_tokens` | `max-tokens` |
+| `refusal` | `refusal` |
+| `cancelled` | `aborted` |
+| `max_turn_requests` or unknown | `error` |
+
+## Process boundary
+
+The child spawns through the [`dsh-subprocess`](../../subprocess/subprocess/README.md) seam: credential-shaped ambient variables and ambient `DSH_*` names are removed by the shared scrub, then explicit `config.env` values merge after it (an intended `DEEPSEEK_API_KEY` survives, and a `DSH_*` deployment fact such as `DSH_PERMISSION_MODE` reaches the child the same way — the scrub drops only its stale ambient namesake), stderr is inherited to the parent's own stream, and disposal applies this plugin's EOF window before the subprocess-owned SIGTERM→SIGKILL escalation and whole-tree join. The ACP wire is the real serialization boundary; same-process subagent values are not defensively cloned.
+
+The package has no default export. Cordis loader unwrapping would otherwise hide the named `inject` metadata; see [postmortem 0001](../../../docs/postmortem/0001-acp-default-export-drops-inject.md).
+
+## Model Experience
+
+### Child-agent request
+
+#### What the model sees
+
+The remote child receives the standalone task content through ACP plus its own process's configured system prompt, tools, and fresh session. It receives no parent conversation. This provider advertises no optional start-time capabilities, so the local service rejects requests for persona, tool filtering, depth enforcement, or structured output instead of silently omitting them.
+
+#### Token effect
+
+The child pays for an independent full context and its own multi-step history. These tokens never enter the parent's context.
+
+#### KV Cache effect
+
+Independent of the parent request cache. Each ACP child can reuse only prefixes identical under its own provider, model, composition, and history; child steps otherwise grow append-only.
+
+### Parent tool result, indirectly
+
+#### What the model sees
+
+Through `dsh-tool-subagent`, the parent receives only the child's final streamed assistant text or that consumer's exact stop-reason error, not intermediate messages or tool traffic. A request already cancelled before publication becomes exactly `Error: subagent request was aborted before the ACP child started`; other start failures pass through as `Error: <message>`.
+
+#### Token effect
+
+Parent input grows only by the final result or error, which is data-dependent and retained until compaction. This provider adds no parent schema itself.
+
+#### KV Cache effect
+
+Append-only; newly visible content follows the reusable request prefix and does not invalidate existing KV-cache entries.
+
+## Known Limitations and Deferred Work
+
+- **A fresh process per run** — persistent-process pooling is a future optimization ([the seam Agent Note](../../../.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md)).
+- **Local workspaces only** — the resolved cwd is a local path handed to a child on the same machine; workspace mapping for a remote ACP agent would need its own backend capability and is not designed here.
+- **No optional start-time capabilities** — this provider cannot apply the local harness's `outputSchema`, depth cap, tool filter, or persona inside the remote process, so it advertises none and the service rejects requests that require them.
+- **Only committed `agent_message_chunk` text is collected** — the automation server keeps reasoning, tool activity, plans, and other trace data in the child session log rather than emitting them on ACP.
+- **Permission prompts are auto-answered** (`permission: allow | reject`) — no human is surfaced a child's `session/request_permission`.

package/README.zh.md

@@ -0,0 +1,100 @@
+# @deepseek-ai/dsh-subagent-acp
+
+[English](README.md) | 中文
+
+ACP（Agent Client Protocol）提供方会在全新的子进程中运行每个 subagent，并作为 Agent Client Protocol 客户端驱动它。这是 spawn 与 fork 的进程外替代方案：子 agent（智能体）拥有自己的运行时、会话、模型配置和工具。
+
+## 启动与所有权
+
+`start(request)` 先解析子 agent 的工作目录，再依次执行 `spawn` → ACP `initialize` → `newSession`，然后才兑现。因此，兑现表示远程会话已就绪，所有权也已转移给调用方。spawn、初始化、新建会话或发布前取消失败时，只有在子进程已回收后才会拒绝；工作目录解析失败则会在尚未 spawn 任何内容时拒绝。
+
+工作目录优先使用已配置的 `cwd` 覆盖值，否则使用执行委派的父会话 cwd，绝不使用服务器进程自身的 cwd，因为同一个服务器进程会服务来自多个工作区的会话。从父级取得的值必须是绝对路径，指向 harness 可以进入的目录（具备搜索权限，这是子进程 cwd 的要求）；解析后的同一路径同时作为子进程 cwd 和 ACP `session/new` 工作区。
+
+返回的运行 id 在父级命名空间中生成。子服务器的会话 id 只用于 ACP 协议调用，因为 ACP 只保证它在该全新子进程中唯一；若将其用作父级生命周期 id，可能与另一个远程运行或本地 agent 冲突。
+
+发布后，提供方发送提示词，并把流式 `agent_message_chunk` 文本收集到 `SubagentResult.output`。提示词/传输失败会以 `stopReason: 'error'` 兑现；如果必需的请求信号或 dispose（资源释放）请求了取消，则以 `aborted` 兑现。
+
+`dispose()` 是幂等的。它会移除信号监听器，在可行时请求 ACP 取消，然后经由该 seam 的动词运行本后端自有的拆卸阶梯（`disposeAcpChild`）：先关闭 stdin 并等待 `disposeEofGraceMs` 让子进程协作式完全停稳，再触发句柄的 `terminate()` 升级（SIGTERM、spawn 宽限期、SIGKILL——Windows 直接强制终止），并等待子进程责任方给出整棵进程树的退出证明。每次运行都使用全新进程；尚未实现进程池。
+
+## 能力与上下文
+
+ACP 不声明任何启动时能力，因为当前进程无法强制执行远程子 agent 的深度、工具过滤、persona 或结构化输出运行时。它也报告 `inheritsParentContext: false`：远程会话从全新状态开始，唯一源自父级的输入是上述工作区 cwd；对话上下文不会跨越进程边界。
+
+## 配置
+
+| 键 | 默认值 | 含义 |
+|---|---|---|
+| `providerName` | `acp` | `ctx.subagents` 上的注册表名称。 |
+| `command` | 必填 | 每次运行时 spawn 的可执行文件。 |
+| `args` | `[]` | 命令参数。 |
+| `cwd` | 父会话 cwd | 子进程及其 ACP 会话的工作目录覆盖值；不得为空。相对值会在加载时以 harness 启动目录为基准解析，结果必须指向 harness 可以进入的目录。 |
+| `permission` | `reject` | 自动回答权限请求：拒绝，或选择第一个 `allow_once` 或 `allow_always` 选项。 |
+| `env` | `{}` | 显式子进程环境，叠加到已清理凭据的父进程环境之上。 |
+| `disposeEofGraceMs` | `6000` | stdin EOF 之后、平台终止之前的宽限时间须为正值，且不得大于 [`MAX_TIMER_DELAY_MS`](../../util/timeout/README.md)。 |
+| `disposeGraceMs` | `3000` | POSIX 在 SIGTERM 后、SIGKILL 前的宽限时间（Windows 直接强制终止），须为正值且不得大于 [`MAX_TIMER_DELAY_MS`](../../util/timeout/README.md)。 |
+
+```yaml
+- id: subagent-acp
+  name: '@deepseek-ai/dsh-subagent-acp'
+  config:
+    providerName: acp
+    command: node
+    args: ['--import', 'tsx', './packages/examples/acp-demo/src/bin.ts', '--config', './examples/acp-agent/cordis.yml']
+    permission: reject
+    env:
+      DEEPSEEK_API_KEY: !!js process.env.DEEPSEEK_API_KEY
+```
+
+## 结束原因映射
+
+| ACP | Harness |
+|---|---|
+| `end_turn` | `completed` |
+| `max_tokens` | `max-tokens` |
+| `refusal` | `refusal` |
+| `cancelled` | `aborted` |
+| `max_turn_requests` 或未知值 | `error` |
+
+## 进程边界
+
+子进程经由 [`dsh-subprocess`](../../subprocess/subprocess/README.md) seam spawn：共享的凭据清除先移除疑似凭据的环境变量和环境中已有的 `DSH_*` 名称，显式 `config.env` 值在清除之后合并（有意转发的 `DEEPSEEK_API_KEY` 会保留下来，`DSH_PERMISSION_MODE` 这类 `DSH_*` 部署事实也以同样的方式到达子进程——清除只丢弃其陈旧的同名环境值），stderr 会继承到父进程自身的流，dispose 则先应用本插件的 EOF 时间窗，再由子进程责任方执行 SIGTERM→SIGKILL 升级并等待整棵进程树退出。ACP 协议格式（wire format）是真正的序列化边界；同进程 subagent 值不会为防御目的而克隆。
+
+本包没有默认导出。否则 Cordis loader 的解包会隐藏具名 `inject` 元数据；见[事故复盘（postmortem）0001](../../../docs/postmortem/0001-acp-default-export-drops-inject.md)。
+
+## 模型体验
+
+### 子 agent 请求
+
+#### 模型看到的内容
+
+远程子 agent 通过 ACP 接收独立任务内容，并使用其自身进程配置的系统提示词、工具和全新会话。它不接收父级对话。该提供方不声明任何可选启动时能力，因此本地服务会拒绝要求 persona、工具过滤、深度强制或结构化输出的请求，而不是静默省略这些要求。
+
+#### Token 影响
+
+子 agent 为独立的完整上下文及其多步骤历史支付 token 成本。这些 token 绝不会进入父级上下文。
+
+#### KV Cache 影响
+
+与父级请求缓存相互独立。每个 ACP 子 agent 只能在其自身提供方、模型、组合和历史均相同时复用前缀；其余情况下，子 agent 步骤仅追加增长。
+
+### 父级工具结果（间接）
+
+#### 模型看到的内容
+
+通过 `dsh-tool-subagent`，父级只接收子 agent 最终的流式 assistant 文本，或该消费方给出的精确结束原因错误；不接收中间消息或工具流量。发布前已经取消的请求会精确变为 `Error: subagent request was aborted before the ACP child started`；其他启动失败按原样传递为 `Error: <message>`。
+
+#### Token 影响
+
+父级输入只增加最终结果或错误，其内容依赖数据，并保留到压缩（compaction）为止。该提供方自身不会添加父级 schema。
+
+#### KV Cache 影响
+
+仅追加；新增可见内容位于可复用请求前缀之后，不会使现有 KV Cache 条目失效。
+
+## 已知限制与暂缓事项
+
+- **每次运行使用全新进程**：持久进程池属于后续优化（见 [seam Agent Note](../../../.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md)）。
+- **仅支持本地工作区**：解析后的 cwd 是交给同一台机器上子进程的本地路径；远程 ACP agent 的工作区映射需要独立的后端能力，本包尚未设计。
+- **不支持可选启动时能力**：该提供方无法在远程进程内应用本地 harness 的 `outputSchema`、深度上限、工具过滤器或 persona，因此不会声明这些能力；服务会拒绝需要它们的请求。
+- **只收集已提交的 `agent_message_chunk` 文本**：自动化服务器把推理（reasoning）、工具活动、计划和其他 trace 数据保留在子 agent 会话日志中，不通过 ACP 发出。
+- **权限提示自动回答**（`permission: allow | reject`）：不会把子 agent 的 `session/request_permission` 呈现给人。

package/lib/index.js

@@ -0,0 +1,367 @@
+import { accessSync, constants, statSync } from "node:fs";
+import { isAbsolute, resolve } from "node:path";
+import z from "@deepseek-ai/schemastery";
+import { MAX_TIMER_DELAY_MS } from "@deepseek-ai/dsh-timeout";
+import { randomUUID } from "node:crypto";
+import { Readable, Writable } from "node:stream";
+import { ClientSideConnection, PROTOCOL_VERSION, ndJsonStream } from "@agentclientprotocol/sdk";
+import { SessionId } from "@deepseek-ai/dsh-session";
+//#region lib/types/run.js
+/**
+* Fresh-process ACP subagent client. Drives one child session and owns cancellation and
+* quiescent disposal.
+*
+* TODO(acp-subagent-replay): add snapshot-tier coverage with a separate replay fixture and
+* sessions root inside each child process. Current keyless coverage uses a scripted ACP child;
+* with-key coverage drives the real ACP example.
+* @module @deepseek-ai/dsh-subagent-acp/run
+*/
+/** EOF grace for child flush and nested-process teardown; wider than the signal grace below. */
+const DEFAULT_DISPOSE_EOF_GRACE_MS = 6e3;
+/** Default POSIX grace between SIGTERM and SIGKILL on dispose (the `disposeGraceMs` config). */
+const DEFAULT_DISPOSE_GRACE_MS = 3e3;
+/** Bounded whole-tree exit wait: polls the handle's tree liveness until it exits or `ms` elapses. */
+async function treeExitsWithin(child, ms) {
+	const controller = new AbortController();
+	const timer = setTimeout(() => {
+		controller.abort();
+	}, ms);
+	try {
+		return await child.waitForExit(controller.signal);
+	} finally {
+		clearTimeout(timer);
+	}
+}
+/**
+* Cooperative teardown ladder for an out-of-process agent, over the seam's
+* public verbs; resolves only at whole-tree quiescence: stdin EOF (the child's
+* window to flush persistence and reap its own descendants), then the
+* terminate() escalation (SIGTERM → spec grace → SIGKILL) and its
+* whole-tree exit proof.
+* @param child - the spawned ACP child's handle.
+* @param eofGraceMs - tier-1 window after stdin EOF.
+*/
+async function disposeAcpChild(child, eofGraceMs) {
+	if (child.pid <= 0) {
+		await child.done.catch(() => {});
+		return;
+	}
+	child.stdin?.end();
+	if (await treeExitsWithin(child, eofGraceMs)) return;
+	child.terminate();
+	await child.waitForExit();
+}
+/**
+* Map an ACP {@link StopReason} to a harness {@link SubagentStopReason}.
+* @param reason - the terminal reason from the child's `session/prompt` response.
+* @returns the harness equivalent; `max_turn_requests` and any unknown future
+* variant map to `error`, so an unclean stop is never reported as `completed`.
+*/
+function acpStopReason(reason) {
+	switch (reason) {
+		case "end_turn": return "completed";
+		case "max_tokens": return "max-tokens";
+		case "refusal": return "refusal";
+		case "cancelled": return "aborted";
+		case "max_turn_requests": return "error";
+		default: return "error";
+	}
+}
+/**
+* Collect the text of an ACP content block (non-text blocks contribute nothing).
+* @param content - the content block off a streamed `agent_message_chunk`.
+* @returns the block's text, or `''` for a non-text block.
+*/
+function acpContentText(content) {
+	return content.type === "text" ? content.text : "";
+}
+/**
+* Translate the harness prompt blocks into ACP prompt blocks (text only).
+* @param prompt - the harness prompt; non-text blocks are dropped.
+* @returns the ACP text blocks, in order.
+*/
+function toAcpPrompt(prompt) {
+	const blocks = [];
+	for (const block of prompt) if (block.type === "text") blocks.push({
+		type: "text",
+		text: block.text
+	});
+	return blocks;
+}
+/** Normalize an unknown thrown value to an Error (the catch binding is `unknown`). */
+function toError(value) {
+	/* v8 ignore next */
+	return value instanceof Error ? value : new Error(String(value));
+}
+/**
+* Start and publish one ACP child after initialization and session creation.
+* Child failures resolve through the run result; startup failures reject after
+* process reap. Disposal cancels, kills, and reaps the child.
+* @param request - the start request; its signal is the cancellation channel.
+* @param spec - the resolved spawn spec: command/args/cwd, env, permission
+* policy, dispose graces, and the optional error sink.
+* @returns the ready run handle for the child subprocess.
+*/
+async function startAcpRun(request, spec) {
+	if (request.signal.aborted) throw new Error("subagent request was aborted before the ACP child started");
+	const id = SessionId(randomUUID());
+	const child = spec.spawn({
+		argv: [spec.command, ...spec.args],
+		cwd: spec.cwd,
+		stdio: {
+			stdin: "pipe",
+			stdout: "pipe",
+			stderr: "inherit"
+		},
+		graceMs: spec.disposeGraceMs,
+		env: spec.env
+	});
+	/* v8 ignore start -- 'pipe' dispositions expose both streams by the seam contract; defensive. */
+	if (child.stdin === void 0 || child.stdout === void 0) throw new Error("subagent-acp: subprocess implementation dropped a piped protocol stream");
+	/* v8 ignore stop */
+	const spawnFailed = child.done.then(
+		/* v8 ignore next -- the success arm's never-settling executor is intentionally empty. */
+		() => new Promise(() => {}),
+		(err) => Promise.reject(toError(err))
+	);
+	spawnFailed.catch(() => {});
+	let processDisposal;
+	const disposeProcess = () => processDisposal ??= disposeAcpChild(child, spec.disposeEofGraceMs);
+	const output = [];
+	const flags = { cancelled: false };
+	const makeClient = (_agent) => ({
+		sessionUpdate(params) {
+			const update = params.update;
+			if (update.sessionUpdate === "agent_message_chunk") output.push(acpContentText(update.content));
+			return Promise.resolve();
+		},
+		requestPermission(params) {
+			if (spec.permission === "allow") {
+				const allow = params.options.find((o) => o.kind === "allow_once" || o.kind === "allow_always");
+				if (allow !== void 0) return Promise.resolve({ outcome: {
+					outcome: "selected",
+					optionId: allow.optionId
+				} });
+			}
+			return Promise.resolve({ outcome: { outcome: "cancelled" } });
+		}
+	});
+	const conn = new ClientSideConnection(makeClient, ndJsonStream(Writable.toWeb(child.stdin), Readable.toWeb(child.stdout)));
+	let sessionId;
+	let signalCancelSettled;
+	const cancelSettled = new Promise((resolve) => {
+		signalCancelSettled = resolve;
+	});
+	const requestCancel = () => {
+		if (flags.cancelled) return;
+		flags.cancelled = true;
+		signalCancelSettled();
+		/* v8 ignore next */
+		if (sessionId !== void 0) conn.cancel({ sessionId }).catch(() => {});
+	};
+	const onAbort = () => {
+		requestCancel();
+	};
+	request.signal.addEventListener("abort", onAbort, { once: true });
+	const collectOutput = () => {
+		const text = output.join("");
+		return text.length > 0 ? [{
+			type: "text",
+			text
+		}] : [];
+	};
+	try {
+		await Promise.race([
+			(async () => {
+				await conn.initialize({
+					protocolVersion: PROTOCOL_VERSION,
+					clientCapabilities: {}
+				});
+				const session = await conn.newSession({
+					cwd: spec.cwd,
+					mcpServers: []
+				});
+				const returnedSessionId = Reflect.get(session, "sessionId");
+				if (typeof returnedSessionId !== "string") throw new Error("ACP child published without a session id");
+				sessionId = returnedSessionId;
+				if (flags.cancelled) throw new Error("subagent cancelled before the ACP session started");
+			})(),
+			spawnFailed,
+			cancelSettled.then(() => {
+				throw new Error("subagent cancelled before the ACP session started");
+			})
+		]);
+	} catch (error) {
+		request.signal.removeEventListener("abort", onAbort);
+		await disposeProcess();
+		if (flags.cancelled) throw new Error("subagent request was aborted before the ACP child started");
+		throw toError(error);
+	}
+	/* v8 ignore next */
+	if (sessionId === void 0) throw new Error("unreachable: ACP startup fulfilled without a session id");
+	const remoteSessionId = sessionId;
+	const result = (async () => {
+		try {
+			const prompt = async () => {
+				const promptResult = await conn.prompt({
+					sessionId: remoteSessionId,
+					prompt: toAcpPrompt(request.prompt)
+				});
+				return {
+					output: collectOutput(),
+					stopReason: acpStopReason(promptResult.stopReason)
+				};
+			};
+			return await Promise.race([prompt(), cancelSettled.then(() => ({
+				output: collectOutput(),
+				stopReason: "aborted"
+			}))]);
+		} catch (error) {
+			/* v8 ignore next */
+			if (flags.cancelled) return {
+				output: collectOutput(),
+				stopReason: "aborted"
+			};
+			try {
+				spec.onError?.(toError(error), "error");
+			} catch {}
+			return {
+				output: collectOutput(),
+				stopReason: "error"
+			};
+		} finally {
+			request.signal.removeEventListener("abort", onAbort);
+		}
+	})();
+	let disposal;
+	return {
+		id,
+		localAgent: void 0,
+		result,
+		dispose() {
+			if (disposal !== void 0) return disposal;
+			request.signal.removeEventListener("abort", onAbort);
+			requestCancel();
+			disposal = disposeProcess();
+			return disposal;
+		}
+	};
+}
+//#endregion
+//#region lib/types/index.js
+/**
+* Out-of-process ACP subagent backend. Each child has its own process, session, model, and
+* tools, so it shares no Cordis context and advertises no parent-enforced start capabilities;
+* the ONE thing it reads off `request.parent` is the session's workspace cwd (see
+* {@link resolveCwd}). This plugin uses named exports only; a default would hide its
+* loader metadata (see `docs/postmortem/0001-acp-default-export-drops-inject.md`).
+* @module @deepseek-ai/dsh-subagent-acp
+*/
+const name = "subagent-acp";
+const inject = ["subagents", "subprocess"];
+const Config = z.object({
+	providerName: z.string().default("acp"),
+	command: z.string().required(),
+	args: z.array(z.string()).default([]),
+	cwd: z.string(),
+	permission: z.union(["allow", "reject"]).default("reject"),
+	env: z.dict(z.string()).default({}),
+	disposeEofGraceMs: z.number().default(DEFAULT_DISPOSE_EOF_GRACE_MS),
+	disposeGraceMs: z.number().default(DEFAULT_DISPOSE_GRACE_MS)
+});
+/** A dispose grace must fit the single Node timer that owns its teardown tier. */
+function assertPositiveFinite(name, value) {
+	if (!Number.isFinite(value) || value <= 0 || value > MAX_TIMER_DELAY_MS) throw new Error(`subagent-acp: ${name} must be a positive finite number no greater than ${MAX_TIMER_DELAY_MS}`);
+}
+/**
+* Whether `path` names an existing directory the harness can ENTER. The
+* search-permission probe matters: `statSync().isDirectory()` is true for a
+* mode-600 directory, but a subprocess cwd needs `X_OK` or spawn fails EACCES.
+*/
+function isDirectory(path) {
+	try {
+		if (!statSync(path).isDirectory()) return false;
+		accessSync(path, constants.X_OK);
+		return true;
+	} catch {
+		return false;
+	}
+}
+/**
+* Assert `cwd` can actually host the child: absolute (it doubles as the ACP
+* session workspace, and a relative path would be re-anchored to the server
+* process's launch directory) and an existing directory (fail here, before the
+* process boundary, instead of as an ambiguous spawn ENOENT).
+* @param label - which source supplied the value, for the diagnostic.
+* @param cwd - the candidate working directory.
+* @returns `cwd`, validated.
+*/
+function assertUsableCwd(label, cwd) {
+	if (!isAbsolute(cwd)) throw new Error(`subagent-acp: ${label} must be an absolute path: ${cwd}`);
+	if (!isDirectory(cwd)) throw new Error(`subagent-acp: ${label} is not an accessible directory: ${cwd}`);
+	return cwd;
+}
+/**
+* Resolve the child's working directory: the deployment `cwd` override when
+* configured (already validated at load), else the parent session's workspace
+* cwd (validated here, its earliest resolvable point). Fails loud when neither
+* exists — falling back to the harness process cwd would silently bind the
+* child to the server's launch directory instead of the delegating session's
+* workspace (one server process serves many sessions, each with its own cwd).
+*/
+function resolveCwd(configured, request) {
+	if (configured !== void 0) return configured;
+	const parentCwd = request.parent.session.header.cwd;
+	if (parentCwd === void 0) throw new Error("subagent-acp: no working directory for the child — configure `cwd` or delegate from a parent session that has one");
+	return assertUsableCwd("parent session cwd", parentCwd);
+}
+/**
+* The ACP provider. Advertises NO start-time capabilities: an out-of-process
+* child cannot honor `outputSchema`/`maxDepth`/`toolFilter` (the service rejects
+* a request needing any of them before `start` runs).
+*/
+var AcpProvider = class {
+	name;
+	ctx;
+	config;
+	capabilities = {
+		outputSchema: false,
+		depthLimit: false,
+		toolFilter: false,
+		persona: false
+	};
+	inheritsParentContext = false;
+	constructor(name, ctx, config) {
+		this.name = name;
+		this.ctx = ctx;
+		this.config = config;
+	}
+	start(request) {
+		return startAcpRun(request, {
+			command: this.config.command,
+			args: this.config.args,
+			cwd: resolveCwd(this.config.cwd, request),
+			permission: this.config.permission,
+			env: this.config.env,
+			disposeEofGraceMs: this.config.disposeEofGraceMs,
+			disposeGraceMs: this.config.disposeGraceMs,
+			spawn: (spec) => this.ctx.subprocess.spawn(spec),
+			onError: (error, stopReason) => {
+				this.ctx.logger.warn(`subagent-acp "${this.name}": child run failed (${stopReason}): ${error.message}`);
+			}
+		});
+	}
+};
+function apply(ctx, config) {
+	const resolved = config;
+	assertPositiveFinite("disposeEofGraceMs", resolved.disposeEofGraceMs);
+	assertPositiveFinite("disposeGraceMs", resolved.disposeGraceMs);
+	if (resolved.cwd === "") throw new Error("subagent-acp: config cwd must not be empty — omit the key to inherit the parent session cwd");
+	const validated = resolved.cwd === void 0 ? resolved : {
+		...resolved,
+		cwd: assertUsableCwd("config cwd", resolve(resolved.cwd))
+	};
+	ctx.subagents.registerProvider(new AcpProvider(validated.providerName, ctx, validated));
+}
+//#endregion
+export { Config, apply, inject, name };

package/lib/invariant.js

@@ -0,0 +1,23 @@
+//#region lib/types/invariant.js
+/**
+* Package-owned invariant companion for `@deepseek-ai/dsh-subagent-acp`.
+* @module @deepseek-ai/dsh-subagent-acp/invariant
+*/
+const PACKAGE_NAME = "@deepseek-ai/dsh-subagent-acp";
+/** Cordis companion plugin name. */
+const name = "subagent-acp-invariant";
+/** Service required before the companion can reserve package ownership. */
+const inject = ["invariants"];
+/**
+* No runtime invariant: this package exposes no independent event sequence or mutable data relation
+* beyond contracts enforced at its owning seam.
+*/
+const install = () => {};
+/**
+* Register this package's invariant companion.
+* @param ctx - Cordis context carrying the invariant service.
+* @returns the installed registration's disposer after setup succeeds.
+*/
+const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//#endregion
+export { apply, inject, name };

package/lib/types/index.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Out-of-process ACP subagent backend. Each child has its own process, session, model, and
+ * tools, so it shares no Cordis context and advertises no parent-enforced start capabilities;
+ * the ONE thing it reads off `request.parent` is the session's workspace cwd (see
+ * {@link resolveCwd}). This plugin uses named exports only; a default would hide its
+ * loader metadata (see `docs/postmortem/0001-acp-default-export-drops-inject.md`).
+ * @module @deepseek-ai/dsh-subagent-acp
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+import { type PermissionPolicy } from './run.ts';
+export declare const name = "subagent-acp";
+export declare const inject: string[];
+/** Config: how to spawn and drive the child ACP agent process. */
+export interface Config {
+    /** Provider name on `ctx.subagents` (default `acp`). */
+    providerName: string;
+    /** The executable to spawn for each run (the child ACP agent). */
+    command: string;
+    /** Arguments passed to {@link command}. */
+    args: string[];
+    /**
+     * Working directory override for the child process and its ACP session.
+     * Must be non-empty; a relative path resolves against the harness launch
+     * directory at load, and the result must be an existing directory. When
+     * omitted, each child inherits its delegating parent session's cwd — and
+     * starting one from a parent session that has no cwd fails.
+     */
+    cwd?: string;
+    /**
+     * How to auto-answer the child's `session/request_permission` prompts:
+     * `reject` (default — decline every prompt) or `allow` (approve via the first
+     * `allow_once` or `allow_always` option). No prompt is surfaced to a human.
+     */
+    permission: PermissionPolicy;
+    /**
+     * Extra environment variables for the child process — e.g. the child
+     * harness's own `DEEPSEEK_API_KEY`. Forwarded on top of a credential-scrubbed
+     * copy of the parent env, so an explicit key here reaches the child while
+     * ambient secrets do not leak implicitly.
+     */
+    env: Record<string, string>;
+    /**
+     * Grace period (ms) for the child's EOF-driven quiesce on dispose — its
+     * window to flush persistence and tear down its own nested subprocesses
+     * before the parent escalates to a signal. Must not exceed
+     * `MAX_TIMER_DELAY_MS`.
+     */
+    disposeEofGraceMs?: number;
+    /** Termination-escalation grace (ms); must not exceed `MAX_TIMER_DELAY_MS`. */
+    disposeGraceMs?: number;
+}
+export declare const Config: z<Config>;
+export declare function apply(ctx: Context, config: Config): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-subagent-acp`.
+ * @module @deepseek-ai/dsh-subagent-acp/invariant
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "subagent-acp-invariant";
+/** Service required before the companion can reserve package ownership. */
+export declare const inject: string[];
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/lib/types/run.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Fresh-process ACP subagent client. Drives one child session and owns cancellation and
+ * quiescent disposal.
+ *
+ * TODO(acp-subagent-replay): add snapshot-tier coverage with a separate replay fixture and
+ * sessions root inside each child process. Current keyless coverage uses a scripted ACP child;
+ * with-key coverage drives the real ACP example.
+ * @module @deepseek-ai/dsh-subagent-acp/run
+ */
+import { type ContentBlock as AcpContentBlock, type StopReason } from '@agentclientprotocol/sdk';
+import type { ContentBlock } from '@deepseek-ai/dsh-llm';
+import type { SubagentRun, SubagentStartRequest, SubagentStopReason } from '@deepseek-ai/dsh-subagent';
+import type { SubprocessHandle, SubprocessSpawnSpec } from '@deepseek-ai/dsh-subprocess';
+/** Fixed response to child permission requests: reject by default, or select the first allow option. */
+export type PermissionPolicy = 'allow' | 'reject';
+/** Resolved spawn spec for an ACP child process (no defaults — see Config). */
+export interface AcpRunSpec {
+    /** The executable to spawn (the child ACP agent). */
+    command: string;
+    /** Arguments passed to {@link command}. */
+    args: string[];
+    /**
+     * Absolute working directory for the child process AND its ACP session
+     * `cwd`. The provider resolves it before this spec exists: config override,
+     * else the delegating parent session's workspace.
+     */
+    cwd: string;
+    /** How to auto-answer the child's permission prompts. */
+    permission: PermissionPolicy;
+    /**
+     * Extra environment variables to ADD for the child (e.g. the child harness's
+     * `DEEPSEEK_API_KEY`). Merged on top of the subprocess seam's scrubbed
+     * parent env. A value here is forwarded even if its name matches the
+     * credential-scrub pattern (an explicit opt-in for the child's own creds).
+     * Explicit `DSH_*` entries are deployment-owned facts for the child harness
+     * (e.g. `DSH_PERMISSION_MODE`); they simply merge after the scrub that
+     * dropped their stale ambient namesakes.
+     */
+    env: Record<string, string>;
+    /**
+     * Grace period (ms) for the child's EOF-driven quiesce in
+     * {@link SubagentRun.dispose} — the window to flush persistence and tear down
+     * its OWN nested subprocesses before the parent escalates to a signal. The
+     * plugin fills this from its `disposeEofGraceMs` config.
+     */
+    disposeEofGraceMs: number;
+    /**
+     * Termination-escalation grace (ms) in {@link SubagentRun.dispose}; POSIX
+     * waits this long after `SIGTERM` before `SIGKILL`, while Windows
+     * force-terminates directly. The plugin fills it from `disposeGraceMs`.
+     */
+    disposeGraceMs: number;
+    /**
+     * Spawn function from the subprocess seam (`ctx.subprocess.spawn`), so the
+     * child rides the shared scrub, tree-scoped teardown, and service-owned
+     * lifetime instead of a package-local child_process path.
+     */
+    spawn: (spec: SubprocessSpawnSpec) => SubprocessHandle;
+    /**
+     * Sink for a child-level failure that the run flattened into a stop reason
+     * (the seam contract forbids `result` rejecting). The driver calls this with
+     * the original error and the chosen stop reason so the fault is preserved
+     * rather than silently lost; the provider wires it to `ctx.logger.warn`.
+     * A throw from the sink itself is contained — it cannot reject `result`.
+     * Optional — omitted in a unit test that asserts the stop reason directly.
+     */
+    onError?: (error: Error, stopReason: SubagentStopReason) => void;
+}
+/** EOF grace for child flush and nested-process teardown; wider than the signal grace below. */
+export declare const DEFAULT_DISPOSE_EOF_GRACE_MS = 6000;
+/** Default POSIX grace between SIGTERM and SIGKILL on dispose (the `disposeGraceMs` config). */
+export declare const DEFAULT_DISPOSE_GRACE_MS = 3000;
+/**
+ * Cooperative teardown ladder for an out-of-process agent, over the seam's
+ * public verbs; resolves only at whole-tree quiescence: stdin EOF (the child's
+ * window to flush persistence and reap its own descendants), then the
+ * terminate() escalation (SIGTERM → spec grace → SIGKILL) and its
+ * whole-tree exit proof.
+ * @param child - the spawned ACP child's handle.
+ * @param eofGraceMs - tier-1 window after stdin EOF.
+ */
+export declare function disposeAcpChild(child: SubprocessHandle, eofGraceMs: number): Promise<void>;
+/**
+ * Map an ACP {@link StopReason} to a harness {@link SubagentStopReason}.
+ * @param reason - the terminal reason from the child's `session/prompt` response.
+ * @returns the harness equivalent; `max_turn_requests` and any unknown future
+ * variant map to `error`, so an unclean stop is never reported as `completed`.
+ */
+export declare function acpStopReason(reason: StopReason): SubagentStopReason;
+/**
+ * Collect the text of an ACP content block (non-text blocks contribute nothing).
+ * @param content - the content block off a streamed `agent_message_chunk`.
+ * @returns the block's text, or `''` for a non-text block.
+ */
+export declare function acpContentText(content: AcpContentBlock): string;
+/**
+ * Translate the harness prompt blocks into ACP prompt blocks (text only).
+ * @param prompt - the harness prompt; non-text blocks are dropped.
+ * @returns the ACP text blocks, in order.
+ */
+export declare function toAcpPrompt(prompt: ContentBlock[]): AcpContentBlock[];
+/**
+ * Start and publish one ACP child after initialization and session creation.
+ * Child failures resolve through the run result; startup failures reject after
+ * process reap. Disposal cancels, kills, and reaps the child.
+ * @param request - the start request; its signal is the cancellation channel.
+ * @param spec - the resolved spawn spec: command/args/cwd, env, permission
+ * policy, dispose graces, and the optional error sink.
+ * @returns the ready run handle for the child subprocess.
+ */
+export declare function startAcpRun(request: SubagentStartRequest, spec: AcpRunSpec): Promise<SubagentRun>;
+//# sourceMappingURL=run.d.ts.map

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@deepseek-ai/dsh-subagent-acp",
+  "description": "Out-of-process ACP subagent backend: drives a child agent in a spawned subprocess over the Agent Client Protocol",
+  "version": "0.0.1-rc.1",
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
+    "directory": "packages/subagent/subagent-acp"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "BSD-3-Clause",
+  "peerDependencies": {
+    "@deepseek-ai/dsh-agent": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-llm": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-subagent": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-subprocess": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-timeout": "^0.0.1-rc.1",
+    "@deepseek-ai/cordis": "^4.0.1-rc.1",
+    "@deepseek-ai/dsh-session": "^0.0.1-rc.1"
+  },
+  "dependencies": {
+    "@agentclientprotocol/sdk": "0.25.1",
+    "@deepseek-ai/schemastery": "^3.18.1-rc.1"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-agent": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-llm": "^0.0.1-rc.1",
+    "@deepseek-ai/cordis-plugin-loader": "^1.0.1-rc.1",
+    "@deepseek-ai/dsh-loader-smoke": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-session": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-subagent": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-subprocess": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-timeout": "^0.0.1-rc.1",
+    "@deepseek-ai/cordis": "^4.0.1-rc.1",
+    "@deepseek-ai/dsh-subprocess-local": "^0.0.1-rc.1"
+  }
+}