feat: add canonical typed tool outputs

packages/subagent/tool-subagent/README.md

@@ -6,9 +6,9 @@ The model-facing delegation tool over one configured `ctx.subagents` provider. C
 
 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 final text; abort, refusal, token limit, and other failures become errored tool results without partial output.
+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.
 
-With `run_in_background: true`, the tool registers the parent-owned task before starting the provider. A task-owned signal covers pending startup and the child after the starting call returns. `task_kill` and owner disposal abort it. Settlement awaits startup rollback or child disposal, then maps completed final text, abort to `killed`, and other failures to `failed`. The task has no incremental read; generic task tools own later status, collection, cancellation, and notices. See the [background subagent Agent Note](../../../.agents/notes/implemented/feature/2026-07-08-background-subagent-tasks.md).
+With `run_in_background: true`, the tool registers the parent-owned task before starting the provider and returns canonical `{ kind: 'background', taskId }`, rendered as `started background subagent task <id>`. A task-owned signal covers pending startup and the child after the starting call returns. `task_kill` and owner disposal abort it. Settlement awaits startup rollback or child disposal, then maps completed final text, abort to `killed`, and other failures to `failed`. The task has no incremental read; generic task tools own later status, collection, cancellation, and notices. See the [background subagent Agent Note](../../../.agents/notes/implemented/feature/2026-07-08-background-subagent-tasks.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).
 

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

@@ -12,6 +12,7 @@ import z from 'schemastery'
 import { defineTool } from '@deepseek-ai/dsh-tools'
 import type { Agent, AgentOptions } from '@deepseek-ai/dsh-agent'
 import type { ContentBlock } from '@deepseek-ai/dsh-llm'
+import type { JsonValue } from '@deepseek-ai/dsh-session'
 import { assertSubagentMaxDepth } from '@deepseek-ai/dsh-subagent'
 import type { SubagentProvider, SubagentResult, SubagentRun, SubagentStartRequest } from '@deepseek-ai/dsh-subagent'
 import type { TaskOutcome } from '@deepseek-ai/dsh-tasks'
@@ -95,6 +96,16 @@ function outputText(blocks: ContentBlock[]): string {
     .join('')
 }
 
+/** Render text blocks from the canonical JSON block array without trusting arbitrary values. */
+function outputValueText(values: JsonValue[]): string {
+  return values
+    .filter((value): value is { type: 'text'; text: string } =>
+      typeof value === 'object' && value !== null && !Array.isArray(value)
+      && value.type === 'text' && typeof value.text === 'string')
+    .map(value => value.text)
+    .join('')
+}
+
 /** A non-`completed` stop reason means the child did not finish cleanly. */
 function stopReasonError(result: SubagentResult): string | undefined {
   switch (result.stopReason) {
@@ -268,7 +279,36 @@ export function apply(ctx: Context, config: Config): void {
           },
         } : {},
       },
-      async execute(args, exec): Promise<ContentBlock[]> {
+      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: '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}`
+            : outputValueText(value.output),
+        }],
+      },
+      async execute(args, exec) {
         const parent = exec.agent
         if (!parent) {
           // Non-agent callers provide no parent for delegation ownership.
@@ -308,7 +348,7 @@ export function apply(ctx: Context, config: Config): void {
               }
             },
           })
-          return [{ type: 'text', text: `started background subagent task ${id}` }]
+          return { kind: 'background' as const, taskId: id }
         }
 
         const request = startRequest(
@@ -327,7 +367,13 @@ export function apply(ctx: Context, config: Config): void {
             // The registry converts this throw to isError; partial output is not success.
             throw new Error(error)
           }
-          return [{ type: 'text', text: outputText(result.output) }]
+          return {
+            kind: 'foreground' as const,
+            runId: run.id,
+            // Content blocks already cross durable JSON boundaries elsewhere;
+            // the registry performs the authoritative lossless snapshot here.
+            output: result.output as unknown as JsonValue[],
+          }
         } finally {
           // Dispose before returning so no child session outlives the call.
           await run.dispose()

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

@@ -62,6 +62,12 @@ describe('dsh-tool-subagent', () => {
     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)
+    if (result.isError) throw new Error('expected subagent success')
+    expect(result.value).toEqual({
+      kind: 'foreground',
+      runId: 'scripted-subagent:mock:parent-1',
+      output: [{ type: 'text', text: 'child says hi' }],
+    })
     expect(text(result)).toBe('child says hi')
   })
 
@@ -637,6 +643,8 @@ describe('dsh-tool-subagent background mode', () => {
 
     const start = await callSubagent(ctx, { description: 'deep research', prompt: 'dig in', run_in_background: true }, { agent: parent })
     expect(start.isError).toBe(false)
+    if (start.isError) throw new Error('expected background subagent success')
+    expect(start.value).toEqual({ kind: 'background', taskId: 'subagent-1' })
     expect(text(start)).toBe('started background subagent task subagent-1')
 
     const collected = await ctx.tools.execute({