@deepseek-ai/dsh-tool-subagent 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/tool-subagent/README.md
+README.md: 6ec313b3b97f0ffa7488025d4314b1c6231a6f6a
+README.zh.md: 1fd88363b3ade9d57c194580f81295eed139ac50

package/README.md

@@ -0,0 +1,82 @@
+# @deepseek-ai/dsh-tool-subagent
+
+English | [中文](README.zh.md)
+
+The model-facing delegation tool over one configured `ctx.subagents` provider. Changing the provider changes transport without changing the execution contract.
+
+## Provider selection and lifecycle
+
+Each plugin instance binds one `provider` to one `toolName`; the model receives no provider selector. Load another distinctly named instance to expose another transport. The tool registers only while its provider exists, avoiding sibling load-order and provider-reload dependencies. Its description follows `provider.inheritsParentContext`: fresh children require standalone prompts, while forked children already see completed parent turns.
+
+A foreground call passes the execution signal through startup and execution, awaits `run.result`, and always awaits `run.dispose()` before returning. Only `completed` returns the canonical `{ kind: 'foreground', runId, output: JsonValue[] }`, rendered as the same final text; abort, refusal, token limit, and other failures become errored tool results without partial output. If result collection and disposal both reject, the errored result preserves both diagnostics.
+
+With `run_in_background: true`, `backgroundMode` selects the route. `one-shot` registers a plain parent-owned Task and returns canonical `{ kind: 'background', taskId }`, rendered as `started background subagent task <id>`, even when the provider supports continuable children; generic task tools own its later status, collection, cancellation, and notices. `continuable` requires a provider with the `prepareContinuable` capability, calls `ctx.subagents.startContinuable()`, and returns `{ kind: 'continuable', subagentId }`, rendered as `started subagent <childId>`. The continuable route resolves at inbox acceptance: the child owns its own turns from there, so this call neither waits for nor collects a result, and the child does not report back — its transcript by that id is the source of its output, and the optional global `send_message` tool sends it more work. Starting continuable work does not require `send_message` to be loaded. See the [background subagent Agent Note](../../../.agents/notes/implemented/feature/2026-07-08-background-subagent-tasks.md), the [continuable subagents Agent Note](../../../.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.md), and the [merged-service Agent Note](../../../.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.md).
+
+`toolFilter` changes the child's global tool layer but is not a parent-derived authority ceiling. See the [agent-scope security non-goal](../../../.agents/notes/implemented/architecture/2026-07-08-agent-scope-contexts.md#security-and-authority-are-non-goals).
+
+## Config
+
+| Key | Meaning |
+|---|---|
+| `provider` (required) | Provider name (`spawn`, `fork`, `acp`, ...). |
+| `toolName` | Model-facing name, default `subagent`; distinct for every loaded instance. |
+| `enableRunInBackground` | Exposes background mode, default `true`; disabling also rejects forced background calls. |
+| `backgroundMode` | Background lifecycle policy, default `one-shot`. `continuable` requires the provider's `prepareContinuable` capability and returns a durable child id; it does not require the follow-up tool. |
+| `agentOptions` | Provider-specific child `provider`, `model`, and positive `maxTokens`; the in-process provider treats explicit values as overrides of inherited parent options. |
+| `persona` | Per-child persona; requires provider `persona` capability. |
+| `toolFilter` | Per-child global-tool restriction; requires `toolFilter` capability. |
+| `maxDepth` | Absolute delegation-depth cap, default `3` (`0` forbids delegation); a numeric cap requires the `depthLimit` capability and fails the mount without it. `'provider-managed'` sends no cap for an out-of-process provider whose budget belongs to the child harness. The tool stays visible at the cap; each attempted start checks the calling agent's current depth and returns an errored tool result when rejected. |
+
+## Concurrency
+
+Foreground and background calls are exclusive. Children may share the parent's workspace or external resources, and a unary classifier cannot prove that sibling delegations have disjoint effects. See the [parallel tool-call Agent Note](../../../.agents/notes/implemented/feature/2026-07-10-parallel-tool-call-execution.md).
+
+## Model Experience
+
+### Tool schema
+
+#### What the model sees
+
+The generated default [`subagent` schema](../../../docs/tool-catalog.md#deepseek-aidsh-tool-subagent) under this instance's configured name while its provider exists. Provider context inheritance changes the tool and prompt descriptions; enabled background mode adds `run_in_background`, and continuable mode describes starting a background subagent that keeps its conversation and returns its subagent id, while one-shot mode describes a background task id collected with `task_output` and stopped with `task_kill`.
+
+#### Token effect
+
+Fixed schema cost per parent request; each provider instance adds one schema.
+
+#### KV Cache effect
+
+Prefix-stable while provider instances, names, descriptions, and schemas are unchanged. Provider registration lifecycle may invalidate parent reuse from the first changed tool definition.
+
+### Foreground result
+
+#### What the model sees
+
+The call retains the description and prompt. Success contains only the child's final text; other outcomes become `Error: <message>`. Intermediate child steps stay out of the parent.
+
+#### Token effect
+
+The prompt and result remain in parent history until compaction; child working context remains in the child.
+
+#### KV Cache effect
+
+Append-only; newly visible content follows the reusable request prefix and does not invalidate existing KV-cache entries.
+
+### Background result
+
+#### What the model sees
+
+Start returns exactly `started subagent <childId>` in configured continuable mode, or `started background subagent task <id>` in configured one-shot mode. In one-shot mode the generic task surface provides later status, final output, cancellation responses, and notices. In continuable mode the child does not report back; an independently loaded `send_message` tool delivers follow-ups, and the child's transcript by its id is the source of its output.
+
+#### Token effect
+
+The acknowledgement is retained; a one-shot final output enters parent history only when collected or injected, while a continuable child's output never returns through this tool.
+
+#### 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
+
+- **Background runs expose no result through this tool** — a one-shot task's final output is collected through the generic task surface, and a continuable child's output stays in its own session, read by its subagent id.
+- **Duplicate names across waiting instances are detected late** (`TODO(subagent-dup-toolname)`) — preventing provider-registration rollback requires a registry of intended names.
+- **Child policy is fixed per instance** — another model, persona, tool filter, or depth cap requires another distinctly named tool.

package/README.zh.md

@@ -0,0 +1,82 @@
+# @deepseek-ai/dsh-tool-subagent
+
+[English](README.md) | 中文
+
+基于一个已配置 `ctx.subagents` 提供方、面向模型的委派工具。更换提供方只会改变传输，不会改变执行约定。
+
+## 提供方选择与生命周期
+
+每个插件实例把一个 `provider` 绑定到一个 `toolName`；模型不会收到提供方选择器。如需公开另一种传输，请加载另一个名称不同的实例。工具只在其提供方存在时注册，从而避免对同级加载顺序和提供方重新加载的依赖。工具描述遵循 `provider.inheritsParentContext`：新建子 agent（智能体）需要独立提示词，而 fork 子 agent 已能看到父级已完成轮次。
+
+前台调用会让执行信号贯穿启动和执行，等待 `run.result`，并且在返回前总会等待 `run.dispose()`。只有 `completed` 会返回规范值 `{ kind: 'foreground', runId, output: JsonValue[] }`，并渲染为相同的最终文本；中止、拒绝、token 上限和其他失败都会变成出错的工具结果，不包含局部输出。如果结果收集与 dispose（资源释放）都 reject，出错的结果会保留两项诊断信息。
+
+设置 `run_in_background: true` 后，`backgroundMode` 会选择路由。`one-shot` 会注册一个归父级所有的普通 Task，并返回规范值 `{ kind: 'background', taskId }`，渲染为 `started background subagent task <id>`，即使提供方支持可继续子 agent 也不例外；通用 Task 工具负责其后续状态、收集、取消和通知。`continuable` 要求提供方具备 `prepareContinuable` 能力，调用 `ctx.subagents.startContinuable()`，并返回 `{ kind: 'continuable', subagentId }`，渲染为 `started subagent <childId>`。可继续路由在 inbox 接受时结算：子 agent 自此拥有自己的轮次，因此该调用既不等待也不收集结果，而且子 agent 不会回报——通过该 id 查看其 transcript（文本记录）即是其输出来源，可选的全局 `send_message` 工具则向其发送更多工作。启动可继续工作不要求加载 `send_message`。见 [后台 subagent Agent Note](../../../.agents/notes/implemented/feature/2026-07-08-background-subagent-tasks.md)、[可继续的 subagent Agent Note](../../../.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.md)和[服务合并 Agent Note](../../../.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.md)。
+
+`toolFilter` 会改变子 agent 的全局工具层，但不是从父级派生的权限上限。见 [agent 作用域的安全非目标](../../../.agents/notes/implemented/architecture/2026-07-08-agent-scope-contexts.md#security-and-authority-are-non-goals)。
+
+## 配置
+
+| 键 | 含义 |
+|---|---|
+| `provider`（必填） | 提供方名称（`spawn`、`fork`、`acp` 等）。 |
+| `toolName` | 面向模型的名称，默认 `subagent`；每个已加载实例必须不同。 |
+| `enableRunInBackground` | 公开后台模式，默认 `true`；禁用时也会拒绝强制后台调用。 |
+| `backgroundMode` | 后台生命周期策略，默认 `one-shot`。`continuable` 要求提供方具备 `prepareContinuable` 能力并返回持久化子 agent ID；它不要求加载后续消息工具。 |
+| `agentOptions` | 传给具体提供方的子 agent `provider`、`model` 和正整数 `maxTokens`；进程内提供方会用显式值覆盖继承的父级选项。 |
+| `persona` | 每个子 agent 独立的 persona；要求提供方具备 `persona` 能力。 |
+| `toolFilter` | 每个子 agent 独立的全局工具限制；要求提供方具备 `toolFilter` 能力。 |
+| `maxDepth` | 绝对委派深度上限，默认 `3`（`0` 禁止委派）；数值上限要求 `depthLimit` 能力，缺失时挂载失败。对于预算由子 harness 拥有的进程外提供方，`'provider-managed'` 不发送上限。工具在达到上限时仍然可见；每次尝试启动都会检查调用 agent 的当前深度，被拒绝时返回出错的工具结果。 |
+
+## 并发
+
+前台调用和后台调用均互斥。子 agent 可能共享父级工作区或外部资源，一元分类器无法证明同级委派的效果彼此不相交。见 [并行工具调用 Agent Note](../../../.agents/notes/implemented/feature/2026-07-10-parallel-tool-call-execution.md)。
+
+## 模型体验
+
+### 工具 schema
+
+#### 模型看到的内容
+
+当提供方存在时，以当前实例配置的名称公开已生成的默认 [`subagent` schema](../../../docs/tool-catalog.md#deepseek-aidsh-tool-subagent)。提供方是否继承上下文会改变工具描述和提示词描述；启用后台模式会添加 `run_in_background`，可继续模式描述为启动一个保留其对话并返回子 agent id 的后台子 agent，而一次性模式描述为返回一个用 `task_output` 收集、用 `task_kill` 停止的后台任务 id。
+
+#### Token 影响
+
+每个父级请求都会产生固定的 schema token 开销；每个提供方实例增加一个 schema。
+
+#### KV Cache 影响
+
+只要提供方实例、名称、描述和 schema 不变，前缀就保持稳定。提供方注册生命周期可能从首个变化的工具定义开始，使父级复用失效。
+
+### 前台结果
+
+#### 模型看到的内容
+
+调用会保留描述和提示词。成功时只包含子 agent 的最终文本；其他结果变为 `Error: <message>`。子 agent 中间步骤不会进入父级。
+
+#### Token 影响
+
+提示词和结果会留在父级历史中，直到上下文压缩（context compaction）；子 agent 工作上下文留在子 agent 中。
+
+#### KV Cache 影响
+
+仅追加；新增可见内容位于可复用请求前缀之后，不会使现有 KV Cache 条目失效。
+
+### 后台结果
+
+#### 模型看到的内容
+
+在配置的可继续模式下，启动时返回内容恰为 `started subagent <childId>`；在配置的一次性模式下，则返回 `started background subagent task <id>`。一次性模式下，通用 Task 接口提供后续状态、最终输出、取消响应和通知。可继续模式下，子 agent 不会回报；独立加载的 `send_message` 工具会投递后续消息，而通过其 id 查看子 agent 的 transcript 即是其输出来源。
+
+#### Token 影响
+
+确认消息会被保留；一次性最终输出只在收集或注入时进入父级历史，而可继续子 agent 的输出绝不会通过本工具返回。
+
+#### KV Cache 影响
+
+仅追加；新增可见内容位于可复用请求前缀之后，不会使现有 KV Cache 条目失效。
+
+## 已知限制与暂缓事项
+
+- **后台运行不通过本工具公开结果**：一次性任务的最终输出通过通用 Task 接口收集，可继续子 agent 的输出留在其自身会话中，按其 subagent id 读取。
+- **等待中实例的重复名称发现较晚**（`TODO(subagent-dup-toolname)`）：若要阻止提供方注册回滚，需要一份预期名称注册表。
+- **每个实例的子 agent 策略固定**：其他模型、persona、工具过滤器或深度上限都需要另一个名称不同的工具。

package/lib/index.js

@@ -0,0 +1,260 @@
+import z from "@deepseek-ai/schemastery";
+import { defineTool } from "@deepseek-ai/dsh-tools";
+import { assertSubagentMaxDepth, settleRun } from "@deepseek-ai/dsh-subagent";
+//#region lib/types/index.js
+/**
+* Model-facing delegation through one configured `ctx.subagents` provider.
+* Provider lifecycle controls tool registration and context-sensitive schema
+* wording. Foreground calls always dispose the run after collection.
+* Background policy is selected by this plugin's configuration: one-shot
+* calls own a plain Task, while continuable calls use
+* `ctx.subagents.startContinuable()`.
+* @module @deepseek-ai/dsh-tool-subagent
+*/
+const name = "tool-subagent";
+const inject = ["tools", "subagents"];
+const Config = z.object({
+	provider: z.string().required(),
+	toolName: z.string().default("subagent"),
+	enableRunInBackground: z.boolean().default(true),
+	backgroundMode: z.union(["one-shot", "continuable"]).default("one-shot"),
+	agentOptions: z.object({
+		provider: z.string(),
+		model: z.string(),
+		maxTokens: z.number().step(1).min(1).max(Number.MAX_SAFE_INTEGER)
+	}).default(void 0),
+	persona: z.string(),
+	toolFilter: z.object({
+		allow: z.array(z.string()).default(void 0),
+		deny: z.array(z.string()).default(void 0)
+	}).default(void 0),
+	maxDepth: z.union([z.natural().max(Number.MAX_SAFE_INTEGER), z.const("provider-managed")]).default(3)
+});
+/** Render text blocks from the canonical JSON block array without trusting arbitrary values. */
+function outputValueText(values) {
+	return values.filter((value) => typeof value === "object" && value !== null && !Array.isArray(value) && value.type === "text" && typeof value.text === "string").map((value) => value.text).join("");
+}
+/** Settle pending startup without rejecting the task producer contract. */
+async function settleStart(start, signal) {
+	try {
+		return await settleRun(await start);
+	} catch (error) {
+		return signal.aborted ? { status: "killed" } : {
+			status: "failed",
+			detail: String(error)
+		};
+	}
+}
+/** A non-`completed` stop reason means the child did not finish cleanly. */
+function stopReasonError(result) {
+	switch (result.stopReason) {
+		case "completed": return;
+		case "aborted": return "subagent run was cancelled";
+		case "error": return "subagent run failed";
+		case "max-tokens": return "subagent run hit its token limit before finishing";
+		case "refusal": return "subagent declined the task";
+		default: return `subagent run ended abnormally (${String(result.stopReason)})`;
+	}
+}
+/**
+* Collect and release one foreground run without letting disposal replace an
+* independent result failure.
+*/
+async function settleForegroundRun(run) {
+	const [execution] = await Promise.allSettled([run.result.then((result) => {
+		const error = stopReasonError(result);
+		if (error !== void 0) throw new Error(error);
+		return {
+			kind: "foreground",
+			runId: run.id,
+			output: result.output
+		};
+	})]);
+	const [disposal] = await Promise.allSettled([Promise.resolve().then(() => run.dispose())]);
+	if (execution.status === "rejected") {
+		if (disposal.status === "rejected") throw new AggregateError([execution.reason, disposal.reason], `subagent run failed: ${String(execution.reason)}; dispose failed: ${String(disposal.reason)}`);
+		throw execution.reason;
+	}
+	if (disposal.status === "rejected") throw disposal.reason;
+	return execution.value;
+}
+/**
+* Model-facing wording from the provider's conversation-history descriptor
+* ({@link SubagentProvider.inheritsParentContext}).
+* A fresh child needs a standalone prompt; a forked child already sees the
+* conversation's completed turns — telling the model to restate everything
+* (or, worse, that the child "does not see this conversation") would be false
+* for a fork.
+* @param inheritsConversation - whether the child's conversation is seeded
+*   with the parent's completed turns; this says nothing about tool, service,
+*   scope, or authority inheritance.
+* @returns the tool `description` and the `prompt` parameter description.
+*/
+function providerWording(inheritsConversation) {
+	if (inheritsConversation) return {
+		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.",
+		promptDescription: "The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."
+	};
+	return {
+		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.",
+		promptDescription: "The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."
+	};
+}
+function apply(ctx, config) {
+	if (config.maxDepth !== "provider-managed") assertSubagentMaxDepth(config.maxDepth);
+	if (config.toolFilter !== void 0 && config.toolFilter.allow === void 0 && config.toolFilter.deny === void 0) throw new Error("tool-subagent: `toolFilter` is configured but names neither `allow` nor `deny` — remove the key or fill the filter");
+	let disposeTool;
+	const mount = (provider) => {
+		if (typeof config.maxDepth === "number" && !provider.capabilities.depthLimit) throw new Error(`tool-subagent: provider "${provider.name}" cannot enforce maxDepth (no depthLimit capability) — set maxDepth: 'provider-managed' to leave the recursion budget to the provider`);
+		const wording = providerWording(provider.inheritsParentContext);
+		const backgroundEnabled = config.enableRunInBackground !== false;
+		const continuable = (config.backgroundMode ?? "one-shot") === "continuable";
+		if (continuable && provider.prepareContinuable === void 0) throw new Error(`tool-subagent: provider "${provider.name}" does not support \`backgroundMode: continuable\``);
+		disposeTool = ctx.tools.register(defineTool({
+			name: config.toolName ?? "subagent",
+			description: wording.description + (backgroundEnabled ? continuable ? " Set `run_in_background: true` to start a background subagent that keeps its conversation: you receive only its subagent id, never its result, and it works on its own. Use this for work whose result you do not need returned by this call; `send_message` sends it more work." : " Set `run_in_background: true` to return a task id; collect with `task_output` and stop with `task_kill`." : ""),
+			parameters: {
+				description: {
+					type: "string",
+					required: true,
+					description: "A short (3-5 word) description of the delegated task, for display."
+				},
+				prompt: {
+					type: "string",
+					required: true,
+					description: wording.promptDescription
+				},
+				...backgroundEnabled ? { run_in_background: {
+					type: "boolean",
+					description: continuable ? "Run as a background subagent that keeps its conversation and return only its subagent id. This call never returns its result; send it more work with send_message." : "Run as a background task and return its id; collect with task_output or stop with task_kill."
+				} } : {}
+			},
+			output: {
+				schema: { oneOf: [
+					{
+						type: "object",
+						additionalProperties: false,
+						properties: {
+							kind: {
+								type: "string",
+								required: true,
+								const: "background"
+							},
+							taskId: {
+								type: "string",
+								required: true
+							}
+						}
+					},
+					{
+						type: "object",
+						additionalProperties: false,
+						properties: {
+							kind: {
+								type: "string",
+								required: true,
+								const: "continuable"
+							},
+							subagentId: {
+								type: "string",
+								required: true
+							}
+						}
+					},
+					{
+						type: "object",
+						additionalProperties: false,
+						properties: {
+							kind: {
+								type: "string",
+								required: true,
+								const: "foreground"
+							},
+							runId: {
+								type: "string",
+								required: true
+							},
+							output: {
+								type: "array",
+								required: true,
+								items: { type: "json" }
+							}
+						}
+					}
+				] },
+				render: (_args, value) => [{
+					type: "text",
+					text: value.kind === "background" ? `started background subagent task ${value.taskId}` : value.kind === "continuable" ? `started subagent ${value.subagentId}` : outputValueText(value.output)
+				}]
+			},
+			async execute(args, exec) {
+				const parent = exec.agent;
+				if (!parent) throw new Error("subagent tool requires a calling agent (exec.agent was undefined)");
+				const maxDepth = typeof config.maxDepth === "number" ? config.maxDepth : void 0;
+				const request = {
+					label: args.description,
+					prompt: [{
+						type: "text",
+						text: args.prompt
+					}],
+					parent,
+					...config.agentOptions !== void 0 ? { agentOptions: config.agentOptions } : {},
+					...config.persona !== void 0 ? { persona: config.persona } : {},
+					...config.toolFilter !== void 0 ? { toolFilter: config.toolFilter } : {},
+					...maxDepth !== void 0 ? { maxDepth } : {}
+				};
+				if (args.run_in_background === true) {
+					if (!backgroundEnabled) throw new Error("run_in_background is disabled for this tool instance (enableRunInBackground: false)");
+					if (continuable) return {
+						kind: "continuable",
+						subagentId: (await ctx.subagents.startContinuable({
+							provider: config.provider,
+							label: args.description,
+							request,
+							signal: exec.signal
+						})).childId
+					};
+					const tasks = ctx.get("tasks");
+					if (tasks === void 0) throw new Error("background tasks unavailable: load @deepseek-ai/dsh-tasks and @deepseek-ai/dsh-tool-tasks");
+					return {
+						kind: "background",
+						taskId: tasks.start({
+							kind: "subagent",
+							label: args.description,
+							owner: parent,
+							run: () => {
+								const controller = new AbortController();
+								return {
+									cancel: (reason) => {
+										controller.abort(reason ?? "background subagent task killed");
+									},
+									done: settleStart(ctx.subagents.start(config.provider, {
+										...request,
+										signal: controller.signal
+									}), controller.signal)
+								};
+							}
+						})
+					};
+				}
+				return settleForegroundRun(await ctx.subagents.start(config.provider, {
+					...request,
+					signal: exec.signal
+				}));
+			}
+		}));
+	};
+	ctx.on("subagent/provider-added", (provider) => {
+		if (provider.name === config.provider && disposeTool === void 0) mount(provider);
+	});
+	ctx.on("subagent/provider-removed", (name) => {
+		if (name !== config.provider || disposeTool === void 0) return;
+		disposeTool();
+		disposeTool = void 0;
+	});
+	const present = ctx.subagents.getProvider(config.provider);
+	if (present !== void 0) mount(present);
+	else ctx.logger.info(`subagent provider "${config.provider}" not registered yet; the "${config.toolName ?? "subagent"}" tool will register when it appears`);
+}
+//#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-tool-subagent`.
+* @module @deepseek-ai/dsh-tool-subagent/invariant
+*/
+const PACKAGE_NAME = "@deepseek-ai/dsh-tool-subagent";
+/** Cordis companion plugin name. */
+const name = "tool-subagent-invariant";
+/** Service required before the companion can reserve package ownership. */
+const inject = ["invariants"];
+/**
+* No runtime invariant: this model-facing adapter has no independent lifecycle stream; execution
+* relations are owned by the capability seam it calls.
+*/
+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,68 @@
+/**
+ * Model-facing delegation through one configured `ctx.subagents` provider.
+ * Provider lifecycle controls tool registration and context-sensitive schema
+ * wording. Foreground calls always dispose the run after collection.
+ * Background policy is selected by this plugin's configuration: one-shot
+ * calls own a plain Task, while continuable calls use
+ * `ctx.subagents.startContinuable()`.
+ * @module @deepseek-ai/dsh-tool-subagent
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+import type { AgentOptions } from '@deepseek-ai/dsh-agent';
+export declare const name = "tool-subagent";
+export declare const inject: string[];
+/** Config: which registered provider this tool delegates to, plus child defaults. */
+export interface Config {
+    /** The `ctx.subagents` provider name to start runs on (e.g. `spawn`, `acp`). */
+    provider: string;
+    /**
+     * Model-facing tool name (default `subagent`). Each loaded instance must use
+     * a distinct name.
+     */
+    toolName?: string;
+    /**
+     * Expose `run_in_background` (default true). Disabled instances omit the
+     * parameter and reject forced background calls.
+     */
+    enableRunInBackground?: boolean;
+    /**
+     * Background execution policy (default `one-shot`). `continuable` requires a
+     * provider with the `prepareContinuable` capability and returns the durable
+     * child id; follow-up adapters remain independently optional.
+     */
+    backgroundMode?: 'one-shot' | 'continuable';
+    /**
+     * Agent options applied to every child; omitted fields use child-loop defaults.
+     */
+    agentOptions?: AgentOptions;
+    /**
+     * Per-child persona that shadows `deployment:persona`. Requires the
+     * provider's `persona` capability; omission preserves the deployment persona.
+     */
+    persona?: string;
+    /**
+     * 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.
+     */
+    toolFilter?: {
+        /** Global tool names the child keeps; everything else is removed. */
+        allow?: string[];
+        /** Global tool names removed from the child. */
+        deny?: string[];
+    };
+    /**
+     * Maximum child depth: a non-negative safe integer (default `3`; `0` forbids
+     * delegation entirely), or `'provider-managed'` to send no cap. A numeric cap
+     * requires the provider's `depthLimit` capability (mount fails loud
+     * otherwise). The provider checks the calling agent's current depth at every
+     * start; the tool remains model-visible so runtime policy owns rejection.
+     * `'provider-managed'` is for an out-of-process provider whose recursion
+     * budget belongs to the child runtime or its own deployment.
+     */
+    maxDepth?: number | 'provider-managed';
+}
+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-tool-subagent`.
+ * @module @deepseek-ai/dsh-tool-subagent/invariant
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "tool-subagent-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/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@deepseek-ai/dsh-tool-subagent",
+  "description": "Model-facing subagent delegation tool over the ctx.subagents seam",
+  "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/tool-subagent"
+  },
+  "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-tasks": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-tools": "^0.0.1-rc.1",
+    "@deepseek-ai/cordis": "^4.0.1-rc.1"
+  },
+  "dependencies": {
+    "@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-session": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-session-persistence": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-session-persistence-jsonl": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-subagent": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-tasks": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-tasks-local": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-subagent-spawn": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-tool-tasks": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-system-prompt": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-tools": "^0.0.1-rc.1",
+    "@deepseek-ai/cordis": "^4.0.1-rc.1"
+  }
+}