Add subagent capability seam: interface, mock backend, model-facing tool

Introduce the `packages/subagent/` group and the abstract subagent seam — an
agent delegating to a child agent — as a named-provider registry (`ctx.subagents`),
unlike the single-implementation bash seam, so multiple transports (in-process,
ACP, future A2A) coexist. This first PR lands the interface, a scripted test
backend, and the model-facing tool, validated through the real cordis load path.

- dsh-subagent: SubagentService registry + SubagentProvider/SubagentRun
  vocabulary + subagent/start|end events. Start-time capabilities (outputSchema,
  depthLimit, toolFilter) are checked pre-start and rejected loud; runtime
  capabilities (sendMessage, resume) are optional methods on SubagentRun.
- dsh-subagent-mock (support): scripted provider for keyless, deterministic
  tests through the real Loader/export path.
- dsh-tool-subagent: the model-facing `subagent` tool, config-bound to one
  provider; synchronous collect with try/finally dispose, signal->cancel
  bridging, and non-completed-stop-reason -> isError mapping.
- Proposed RFC documenting the seam, the fork-vs-spawn-as-separate-backends
  decision, own-session isolation, synchronous-collect scope, and the deferral
  of background/poll/spill to a future unification with bash.
- Wire the new group into tsconfigs, build refs, package hierarchy docs, the
  module graph, and the cordis catalog.

RFC: docs/rfc/proposed/feature/2026-06-21-subagent-capability-seam.md

packages/subagent/tool-subagent/README.md

@@ -0,0 +1,18 @@
+# @deepseek-ai/dsh-tool-subagent
+
+The model-facing `subagent` tool: delegate a self-contained task to a child agent and return its final output. Pure schema + lifecycle shaping over the [`ctx.subagents`](../subagent/README.md) provider registry — an in-process, ACP, or future A2A backend swaps in without changing what the model sees.
+
+## Provider selection is config, not model-facing
+
+This plugin binds to **exactly one** provider (`Config.provider`). The model sees only `{ description, prompt }` — there is no provider/type parameter in the schema. To expose more than one transport, load the plugin more than once, each bound to a different provider. Keeping selection in config (not the schema) is the deliberate split: the *service* holds a multi-provider registry; the *tool* picks one.
+
+| Config key | Meaning |
+|---|---|
+| `provider` (required) | The `ctx.subagents` provider name to start runs on (`spawn`, `fork`, `acp`, …). |
+| `agentOptions` | Default per-child `{ model?, systemPrompt? }` applied to every spawned child. |
+
+## Lifecycle (synchronous collect)
+
+`execute` starts a run on the configured provider and **awaits `run.result` inside a `try/finally` that always `dispose()`s the run** — the owned child agent/session is torn down on every path (success, error, abort), never leaked. The tool's abort signal (`exec.signal`) is bridged to `run.cancel()`. A non-`completed` stop reason (aborted/error/max-tokens/refusal) maps to an `isError` tool result rather than returning partial output as success.
+
+Background / poll collection is deferred (see the [RFC](../../../docs/rfc/proposed/feature/2026-06-21-subagent-capability-seam.md)); this cut blocks the parent turn until the child finishes.

packages/subagent/tool-subagent/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@deepseek-ai/dsh-tool-subagent",
+  "description": "Model-facing subagent delegation tool over the ctx.subagents seam",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "src"
+  ],
+  "license": "BSD-3-Clause",
+  "peerDependencies": {
+    "@deepseek-ai/dsh-agent": "^0.0.1",
+    "@deepseek-ai/dsh-llm": "^0.0.1",
+    "@deepseek-ai/dsh-subagent": "^0.0.1",
+    "@deepseek-ai/dsh-tools": "^0.0.1",
+    "cordis": "^4.0.0-rc.6"
+  },
+  "dependencies": {
+    "schemastery": "^3.18.0"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-agent": "workspace:^",
+    "@deepseek-ai/dsh-llm": "workspace:^",
+    "@deepseek-ai/dsh-subagent": "workspace:^",
+    "@deepseek-ai/dsh-subagent-mock": "workspace:^",
+    "@deepseek-ai/dsh-system-prompt": "workspace:^",
+    "@deepseek-ai/dsh-tools": "workspace:^",
+    "@cordisjs/plugin-loader": "^1.0.0-rc.4",
+    "cordis": "^4.0.0-rc.6"
+  }
+}

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

@@ -0,0 +1,147 @@
+/**
+ * The model-facing `subagent` tool: delegate a task to a child agent and return
+ * its final output. Pure schema + lifecycle shaping — every transport concern
+ * lives behind the `ctx.subagents` provider registry
+ * (`@deepseek-ai/dsh-subagent`), so an in-process, ACP, or future A2A backend
+ * swaps in without touching what the model sees.
+ *
+ * Provider selection is config, not model-facing: this plugin is bound to
+ * EXACTLY ONE provider name (`Config.provider`). To expose more than one
+ * transport, load the plugin more than once, each bound to a different provider
+ * — there is no provider/type parameter in the model-facing schema. The model
+ * sees only `{ description, prompt }`.
+ *
+ * Collection is SYNCHRONOUS this cut: `execute` starts a run and awaits
+ * `run.result` inside a `try/finally` that always disposes the run, so the
+ * owned child agent/session is torn down on every path (success, error, abort)
+ * and never leaks as a live idle child. A non-`completed` stop reason maps to an
+ * `isError` tool result (by throwing) rather than returning partial output as
+ * success.
+ *
+ * @module @deepseek-ai/dsh-tool-subagent
+ */
+
+import type { Context } from 'cordis'
+import z from 'schemastery'
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import type { AgentOptions } from '@deepseek-ai/dsh-agent'
+import type { ContentBlock } from '@deepseek-ai/dsh-llm'
+import type { SubagentResult, SubagentRun, SubagentStartRequest } from '@deepseek-ai/dsh-subagent'
+
+export const name = 'tool-subagent'
+export const inject = ['tools', 'subagents']
+
+/** 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
+  /**
+   * Default per-child agent options (model, system prompt) applied to every
+   * spawned child. Omitted fields fall back to the child loop's own defaults.
+   */
+  agentOptions?: AgentOptions
+}
+
+export const Config: z<Config> = z.object({
+  provider: z.string().required(),
+  agentOptions: z.object({
+    model: z.string(),
+    systemPrompt: z.string(),
+  }),
+})
+
+/**
+ * Flatten a child's final output blocks to text for the tool result. The child
+ * may return non-text blocks; this cut surfaces the text content (the common
+ * case) and drops the rest, which is acceptable for a synchronous summary —
+ * the structured path (`outputSchema`) is the channel for non-text results.
+ */
+function outputText(blocks: ContentBlock[]): string {
+  return blocks
+    .filter((b): b is Extract<ContentBlock, { type: 'text' }> => b.type === 'text')
+    .map(b => b.text)
+    .join('')
+}
+
+/** A non-`completed` stop reason means the child did not finish cleanly. */
+function stopReasonError(result: SubagentResult): string | undefined {
+  switch (result.stopReason) {
+    case 'completed':
+      return undefined
+    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'
+    // Merge-extensible union: a backend may add stop reasons. Treat an unknown
+    // terminal reason as a failure rather than reporting partial output as success.
+    default:
+      return `subagent run ended abnormally (${String(result.stopReason)})`
+  }
+}
+
+export function apply(ctx: Context, config: Config): void {
+  ctx.tools.register(defineTool({
+    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.',
+    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: 'The complete, self-contained task for the subagent. It does not share this '
+          + 'conversation\'s context, so include everything it needs.',
+      },
+    },
+    async execute(args, exec): Promise<ContentBlock[]> {
+      const parent = exec.agent
+      if (!parent) {
+        // The loop sets `exec.agent` for every model-driven call; its absence
+        // means a non-agent caller invoked the tool directly, which has no
+        // parent to attribute the child to. Fail loud rather than guess.
+        throw new Error('subagent tool requires a calling agent (exec.agent was undefined)')
+      }
+
+      const request: SubagentStartRequest = {
+        prompt: [{ type: 'text', text: args.prompt }],
+        parent,
+        ...exec.signal ? { signal: exec.signal } : {},
+        ...config.agentOptions ? { agentOptions: config.agentOptions } : {},
+      }
+
+      const run: SubagentRun = ctx.subagents.start(config.provider, request)
+
+      // Bridge the tool's abort signal to the run: if the parent step is
+      // aborted while the child is in flight, cancel the child too.
+      const onAbort = (): void => { run.cancel('parent step aborted') }
+      exec.signal?.addEventListener('abort', onAbort, { once: true })
+
+      try {
+        const result = await run.result
+        const error = stopReasonError(result)
+        if (error !== undefined) {
+          // Map a non-clean finish to an isError result (the registry turns a
+          // throw into an isError). Report the reason, not partial output.
+          throw new Error(error)
+        }
+        return [{ type: 'text', text: outputText(result.output) }]
+      } finally {
+        exec.signal?.removeEventListener('abort', onAbort)
+        // Always reach child quiescence — never leak a live idle child/session.
+        await run.dispose()
+      }
+    },
+  }))
+}

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

@@ -0,0 +1,210 @@
+import { describe, expect, it, vi } from 'vitest'
+import { Context } from 'cordis'
+import Loader from '@cordisjs/plugin-loader'
+import { CallId } from '@deepseek-ai/dsh-llm'
+import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
+import ToolRegistry from '@deepseek-ai/dsh-tools'
+import { AgentId, type Agent } from '@deepseek-ai/dsh-agent'
+import SubagentService from '@deepseek-ai/dsh-subagent'
+import * as mock from '@deepseek-ai/dsh-subagent-mock'
+import * as tool from '../src/index.ts'
+
+/**
+ * Drives the REAL plugin body: mounts `dsh-tool-subagent` on a real
+ * `ToolRegistry` + `SubagentService`, with the real `dsh-subagent-mock` as the
+ * backend, and invokes the registered `subagent` tool through
+ * `ctx.tools.execute`. The mock is the genuine collaborator (we mock only the
+ * "child agent", the expensive/non-deterministic boundary) — everything
+ * downstream of the tool is the shipping code path.
+ */
+
+/** A minimal parent Agent — the tool reads `agent.id` for `parent`. */
+function fakeAgent(id = 'parent-1'): Agent {
+  return { id: AgentId(id) } as unknown as Agent
+}
+
+async function setup(toolConfig: tool.Config, mockConfig: Partial<mock.Config> = {}) {
+  const ctx = new Context()
+  await ctx.plugin(SystemPrompt)
+  await ctx.plugin(ToolRegistry)
+  await ctx.plugin(SubagentService)
+  await ctx.plugin(mock, { name: 'mock', ...mockConfig })
+  await ctx.plugin(tool, toolConfig)
+  return ctx
+}
+
+let callCounter = 0
+function callSubagent(ctx: Context, args: unknown, over: { agent?: Agent | undefined; signal?: AbortSignal } = {}) {
+  // Distinguish "no override" (use a default agent) from an explicit
+  // `{ agent: undefined }` (test the no-agent path). Under
+  // exactOptionalPropertyTypes the key is omitted rather than set to undefined.
+  const agent = 'agent' in over ? over.agent : fakeAgent()
+  return ctx.tools.execute({
+    callId: CallId(`call-${++callCounter}`),
+    name: 'subagent',
+    arguments: args,
+    ...agent ? { agent } : {},
+    ...over.signal ? { signal: over.signal } : {},
+  })
+}
+
+function text(result: { content: { type: string; text?: string }[] }): string {
+  return result.content.filter(b => b.type === 'text').map(b => b.text).join('')
+}
+
+describe('dsh-tool-subagent', () => {
+  it('registers a `subagent` tool that delegates to the configured provider and returns its output', async () => {
+    const ctx = await setup({ provider: 'mock' }, { reply: 'child says hi' })
+    const result = await callSubagent(ctx, { description: 'do a thing', prompt: 'go research X' })
+    expect(result.isError).toBe(false)
+    expect(text(result)).toBe('child says hi')
+  })
+
+  it('exposes only description + prompt to the model (no provider/type parameter)', async () => {
+    const ctx = await setup({ provider: 'mock' })
+    const schema = ctx.tools.schemas().find(s => s.name === 'subagent')
+    expect(schema).toBeDefined()
+    const props = (schema!.parameters as { properties?: Record<string, unknown> }).properties ?? {}
+    expect(Object.keys(props).sort()).toEqual(['description', 'prompt'])
+  })
+
+  it('maps a non-completed stop reason to an isError result (not partial success)', async () => {
+    const ctx = await setup({ provider: 'mock' }, { stopReason: 'refusal' })
+    const result = await callSubagent(ctx, { description: 'd', prompt: 'p' })
+    expect(result.isError).toBe(true)
+    expect(text(result)).toContain('declined')
+  })
+
+  it('fails loud when invoked without a calling agent', async () => {
+    const ctx = await setup({ provider: 'mock' })
+    const result = await callSubagent(ctx, { description: 'd', prompt: 'p' }, { agent: undefined })
+    expect(result.isError).toBe(true)
+    expect(text(result)).toContain('requires a calling agent')
+  })
+
+  it('surfaces an UNSUPPORTED_CAPABILITY rejection as an isError result is NOT applicable here '
+    + '(the tool requests no capabilities) — a missing provider IS surfaced', async () => {
+    // Bind the tool to a provider name that is not registered: the service throws
+    // NO_PROVIDER, the registry turns it into an isError result.
+    const ctx = await setup({ provider: 'does-not-exist' })
+    const result = await callSubagent(ctx, { description: 'd', prompt: 'p' })
+    expect(result.isError).toBe(true)
+    expect(text(result)).toContain('no subagent provider')
+  })
+
+  it('disposes the run on the success path (no leaked child)', async () => {
+    // Spy on the provider's run.dispose via a wrapping provider registered
+    // directly on the service, then point the tool at it.
+    const disposed = vi.fn()
+    const ctx = new Context()
+    await ctx.plugin(SystemPrompt)
+    await ctx.plugin(ToolRegistry)
+    await ctx.plugin(SubagentService)
+    ctx.subagents.registerProvider({
+      name: 'spy',
+      capabilities: { outputSchema: false, depthLimit: false, toolFilter: false },
+      start: () => ({
+        id: AgentId('spy-child'),
+        result: Promise.resolve({ output: [{ type: 'text', text: 'ok' }], stopReason: 'completed' as const }),
+        cancel() {},
+        dispose: async () => void disposed(),
+      }),
+    })
+    await ctx.plugin(tool, { provider: 'spy' })
+
+    await callSubagent(ctx, { description: 'd', prompt: 'p' })
+    expect(disposed).toHaveBeenCalledTimes(1)
+  })
+
+  it('disposes the run on the error path too', async () => {
+    const disposed = vi.fn()
+    const ctx = new Context()
+    await ctx.plugin(SystemPrompt)
+    await ctx.plugin(ToolRegistry)
+    await ctx.plugin(SubagentService)
+    ctx.subagents.registerProvider({
+      name: 'spy',
+      capabilities: { outputSchema: false, depthLimit: false, toolFilter: false },
+      start: () => ({
+        id: AgentId('spy-child'),
+        result: Promise.resolve({ output: [], stopReason: 'error' as const }),
+        cancel() {},
+        dispose: async () => void disposed(),
+      }),
+    })
+    await ctx.plugin(tool, { provider: 'spy' })
+
+    const result = await callSubagent(ctx, { description: 'd', prompt: 'p' })
+    expect(result.isError).toBe(true)
+    expect(disposed).toHaveBeenCalledTimes(1)
+  })
+
+  it('bridges the tool abort signal to run.cancel()', async () => {
+    const cancelled = vi.fn()
+    const ctx = new Context()
+    await ctx.plugin(SystemPrompt)
+    await ctx.plugin(ToolRegistry)
+    await ctx.plugin(SubagentService)
+    ctx.subagents.registerProvider({
+      name: 'spy',
+      capabilities: { outputSchema: false, depthLimit: false, toolFilter: false },
+      start: () => {
+        let resolveResult: (r: { output: never[]; stopReason: 'aborted' }) => void
+        const result = new Promise<{ output: never[]; stopReason: 'aborted' }>((res) => { resolveResult = res })
+        return {
+          id: AgentId('spy-child'),
+          result,
+          cancel: () => {
+            cancelled()
+            resolveResult({ output: [], stopReason: 'aborted' })
+          },
+          dispose: async () => {},
+        }
+      },
+    })
+    await ctx.plugin(tool, { provider: 'spy' })
+
+    const controller = new AbortController()
+    const pending = callSubagent(ctx, { description: 'd', prompt: 'p' }, { signal: controller.signal })
+    controller.abort()
+    const result = await pending
+    expect(cancelled).toHaveBeenCalledTimes(1)
+    expect(result.isError).toBe(true)
+  })
+
+  it('tools depend on the service: no `subagent` tool without ctx.subagents', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SystemPrompt)
+    await ctx.plugin(ToolRegistry)
+    // No SubagentService mounted. The tool injects ['tools','subagents'] so its
+    // apply never runs; the tool is absent rather than half-registered.
+    let booted = true
+    try {
+      await ctx.plugin(tool, { provider: 'mock' })
+      await new Promise(r => setTimeout(r, 20))
+    } catch {
+      booted = false
+    }
+    // Either it never booted, or it booted but registered no tool.
+    const present = ctx.get('tools')?.schemas().some(s => s.name === 'subagent') ?? false
+    expect(booted && present).toBe(false)
+  })
+
+  it('has the namespace-plugin export shape (no stray default) so the Loader keeps name/inject/Config/apply', () => {
+    // Postmortem 0001 guard: this plugin HAS `inject = ['tools','subagents']`, so
+    // a stray `export default apply` would collapse the module via
+    // `unwrapExports` (`exports.default ?? exports`), DROP `inject`, and crash at
+    // load with "cannot get property … without inject". Guard the shape directly.
+    expect('default' in tool).toBe(false)
+    expect(tool.name).toBe('tool-subagent')
+    expect(tool.inject).toEqual(['tools', 'subagents'])
+
+    const loader = Object.create(Loader.prototype) as Loader
+    const unwrapped = loader.unwrapExports(tool) as Record<string, unknown>
+    expect(unwrapped).toBe(tool)
+    expect(unwrapped.name).toBe('tool-subagent')
+    expect(unwrapped.inject).toEqual(['tools', 'subagents'])
+    expect(typeof unwrapped.apply).toBe('function')
+    expect(unwrapped.Config).toBeDefined()
+  })
+})

packages/subagent/tool-subagent/tsconfig.json

@@ -0,0 +1,33 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib"
+  },
+  "include": [
+    "src"
+  ],
+  "references": [
+    {
+      "path": "../../../vendor/cosmokit"
+    },
+    {
+      "path": "../../../vendor/cordis"
+    },
+    {
+      "path": "../../../vendor/schemastery"
+    },
+    {
+      "path": "../../core/agent"
+    },
+    {
+      "path": "../../llm/llm"
+    },
+    {
+      "path": "../../core/tools"
+    },
+    {
+      "path": "../subagent"
+    }
+  ]
+}