feat: add canonical typed tool outputs

packages/core/tools/src/code-mode.ts

@@ -10,7 +10,7 @@ import { inspect } from 'node:util'
 import { CallId, HarnessError } from '@deepseek-ai/dsh-llm'
 import type { ContentBlock } from '@deepseek-ai/dsh-llm'
 import type { CodeBindingFunction, CodeRunResult, CodeRuntime } from '@deepseek-ai/dsh-code-runtime'
-import type {} from '@deepseek-ai/dsh-session'
+import type { JsonValue } from '@deepseek-ai/dsh-session'
 import { defineTool } from './schema.ts'
 import type { ToolDefinition, ToolRegistry } from './index.ts'
 
@@ -111,9 +111,8 @@ function jsonNormalizeArgs(value: unknown): { dispatched: unknown; logged: unkno
   return { dispatched: JSON.parse(text) as unknown, logged: JSON.parse(text) as unknown }
 }
 
-/** Render the program's completion value for the model-facing result text (`''` when the program returned nothing). */
-function renderValue(value: unknown): string {
-  if (value === undefined) return ''
+/** Render one present program completion value for the model-facing result text. */
+function renderValue(value: JsonValue): string {
   return typeof value === 'string' ? value : inspect(value, INSPECT_OPTIONS)
 }
 
@@ -122,6 +121,9 @@ interface RunCodeMeta {
   logs: CodeRunResult['logs']
 }
 
+/** Canonical value returned by the outer Code Mode transport. */
+type RunCodeOutput = { logs: string[]; result?: JsonValue }
+
 /** Soft-narrow a result `meta` back to {@link RunCodeMeta} (replay may carry older shapes; presentation must not throw). */
 function asRunCodeMeta(meta: unknown): RunCodeMeta | undefined {
   if (typeof meta !== 'object' || meta === null) return undefined
@@ -152,7 +154,23 @@ export function createRunCodeTool(registry: ToolRegistry, requireRuntime: () =>
     parameters: {
       code: { type: 'string', required: true, description: 'The program: the body of an async TypeScript function.' },
     },
-    async execute(args, exec) {
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          logs: { type: 'array', required: true, items: { type: 'string' } },
+          result: { type: 'json' },
+        },
+      },
+      render: (_args, value) => {
+        const rendered = value.result === undefined ? '' : renderValue(value.result)
+        const parts = [value.logs.join('\n'), rendered].filter(part => part.length > 0)
+        return [{ type: 'text', text: parts.length > 0 ? parts.join('\n') : '(run_code completed with no output)' }]
+      },
+      presentationMeta: (_args, value) => ({ logs: value.logs }),
+    },
+    async execute(args, exec): Promise<RunCodeOutput> {
       const runtime = requireRuntime()
 
       // The run-scoped abort: follows the outer signal in, and fires when the
@@ -265,12 +283,12 @@ export function createRunCodeTool(registry: ToolRegistry, requireRuntime: () =>
           const logsText = result.logs.length > 0 ? `\nCaptured output:\n${result.logs.join('\n')}` : ''
           throw new CodeRunFailedError(`code run failed (${result.error.kind}): ${result.error.message}${logsText}`)
         }
-        const rendered = renderValue(result.value)
-        const parts = [result.logs.join('\n'), rendered].filter(part => part.length > 0)
-        const meta: RunCodeMeta = { logs: result.logs }
+        // The runtime seam is wider than JSON until PR 3 makes this boundary
+        // lossless. The registry immediately snapshots and rejects any value
+        // that does not satisfy the declared JSON output.
         return {
-          content: [{ type: 'text', text: parts.length > 0 ? parts.join('\n') : '(run_code completed with no output)' }],
-          meta,
+          logs: result.logs,
+          ...result.value !== undefined ? { result: result.value as JsonValue } : {},
         }
       } finally {
         exec.signal?.removeEventListener('abort', onOuterAbort)

packages/core/tools/src/index.ts

@@ -12,12 +12,15 @@ import type { CallId, ContentBlock, ToolSchema } from '@deepseek-ai/dsh-llm'
 import { assertNever, deepFreeze, HarnessError } from '@deepseek-ai/dsh-llm'
 import type { Agent, HookContext } from '@deepseek-ai/dsh-agent'
 import { snapshotJsonValue } from '@deepseek-ai/dsh-session'
+import type { JsonValue } from '@deepseek-ai/dsh-session'
 import type { ToolProviderResult } from '@deepseek-ai/dsh-system-prompt'
 import type { CodeRuntime } from '@deepseek-ai/dsh-code-runtime'
 // Type-only: makes `ctx.get('approval')` resolve to the ApprovalService
 // augmentation. The seam stays optional at runtime — see `serviceAsk`.
 import type {} from '@deepseek-ai/dsh-user-approval'
 import type { ToolCallView, ToolResultView } from './presentation.ts'
+import { assertSupportedJsonSchema, validateJsonSchemaValue } from './json-schema.ts'
+import type { JsonSchemaNode } from './json-schema.ts'
 import { createRunCodeTool, RUN_CODE_NAME, SDK_SECTION_ORDER } from './code-mode.ts'
 import { renderToolsSdk } from './ts-types.ts'
 
@@ -61,6 +64,7 @@ export type { JsonValue } from '@deepseek-ai/dsh-session'
 
 export { CodeRunFailedError, RUN_CODE_NAME } from './code-mode.ts'
 export { jsonSchemaToTs, renderToolsSdk } from './ts-types.ts'
+export { defineContentToolFixture, type ContentToolFixtureOptions } from './testing.ts'
 
 // The render-intent vocabulary a tool declares via `presentCall`/`presentResult`
 // lives in its own UI-facing module; re-export it so `@deepseek-ai/dsh-tools`
@@ -132,12 +136,22 @@ declare module 'cordis' {
   }
 }
 
-/** Tool output, optionally with lossless-JSON presentation metadata persisted for replay. */
-export type ToolExecuteReturn = ContentBlock[] | { content: ContentBlock[]; meta?: unknown }
+/** Tool-owned canonical output contract used after the body returns a JSON value. */
+export interface ToolOutputDefinition {
+  /** Raw supported JSON Schema enforced against every successful canonical value. */
+  readonly schema: JsonSchemaNode
+  /** Pure projection from validated arguments and value to Native/model content. */
+  render(args: unknown, value: JsonValue): ContentBlock[]
+  /** Pure replayable presentation projection, computed only for surface calls. */
+  presentationMeta?(args: unknown, value: JsonValue): JsonValue
+}
 
 /** A registered tool: its schema plus the execution function. */
 export interface ToolDefinition extends ToolSchema {
-  execute(args: unknown, exec: ToolRunContext): Promise<ToolExecuteReturn>
+  /** Mandatory canonical output declaration. */
+  readonly output: ToolOutputDefinition
+  /** Execute the tool and return only its canonical lossless-JSON value. */
+  execute(args: unknown, exec: ToolRunContext): Promise<unknown>
   /**
    * Cooperative tool-call timeout budget in milliseconds. Omit for no deadline.
    * Enforced by `@deepseek-ai/dsh-timeout-policy` (a `tools/execute` wrapper); it
@@ -172,7 +186,7 @@ export interface ToolDefinition extends ToolSchema {
   presentCall?(args: unknown): ToolCallView | undefined
   /**
    * Optional: how to present the COMPLETED state, given the same `args` and the
-   * `result` (`execute`'s content + whether it errored). Returns a
+   * durable result projection (`content`, failure state, and optional `meta`). Returns a
    * {@link ToolResultView}, or `undefined` (or omit the method) to keep the
    * pending title and render the raw result content. Pure and side-effect-free
    * for the same replay reason.
@@ -182,17 +196,16 @@ export interface ToolDefinition extends ToolSchema {
 
 /** The completed outcome handed to {@link ToolDefinition.presentResult}. */
 export interface ToolResult {
-  /** The model-facing content `execute` returned (or the error text on failure). */
+  /** The final model-facing content (or the rendered error text on failure). */
   content: ContentBlock[]
   /** Whether the call failed. */
   isError: boolean
   /**
-   * The tool-private presentation payload the tool attached from `execute` (via
-   * the object return form), threaded verbatim from the `tool/result` event.
-   * Opaque (`unknown`); the tool narrows it back to its own shape. Absent when
-   * the tool attached none.
+   * The tool-private presentation payload projected by its output declaration
+   * and threaded verbatim from the `tool/result` event. Absent when the tool
+   * declared no projector or the call was nested under a composite transport.
    */
-  meta?: unknown
+  meta?: JsonValue
 }
 
 declare const toolExecutionTokenBrand: unique symbol
@@ -303,6 +316,14 @@ export interface ToolErrorInfo {
   code: string
 }
 
+/** Canonical failure detail; internal routing information remains optional. */
+export interface ToolFailure {
+  /** Human-readable failure message without the Native `Error: ` envelope. */
+  message: string
+  /** Internal error class/code used by policy and durable diagnostics. */
+  info?: ToolErrorInfo
+}
+
 /**
  * Thrown (internally) when the model requests a tool that isn't registered.
  * Extends {@link HarnessError} (`code: 'UNKNOWN_TOOL'`) so an unknown-tool
@@ -316,30 +337,42 @@ export class ToolNotFoundError extends HarnessError {
   }
 }
 
-/** The outcome of one tool call. */
-export interface ToolExecutionResult {
-  content: ContentBlock[]
-  isError: boolean
-  /**
-   * Set when the call failed with a {@link HarnessError}: machine-routable
-   * `{ name, code }` for retry/sandbox plugins and replay. The model-facing
-   * text in `content` is always present; this is extra structure for code.
-   */
-  error?: ToolErrorInfo
-  /**
-   * Model-facing context for the next request, separate from this tool result. The loop
-   * accepts it into the active-batch FIFO, then appends after recorded results even if interrupted.
-   */
-  additionalContexts?: HookContext[]
-  /**
-   * The tool-private presentation payload from a successful `execute` (the object
-   * return form). Threaded onto the `tool/result` session event and back into
-   * {@link ToolResult} for `presentResult`. Opaque (`unknown`); absent when the
-   * tool attached none or the call failed.
-   */
-  meta?: unknown
+/** Thrown when a tool body or post-policy value violates its declared output. */
+export class ToolOutputError extends HarnessError {
+  /** Schema/value violations in validation order. */
+  readonly violations: string[]
+
+  constructor(toolName: string, violations: string[]) {
+    super(`tool "${toolName}" returned invalid output: ${violations.join('; ')}`, 'INVALID_TOOL_OUTPUT')
+    this.name = 'ToolOutputError'
+    this.violations = violations
+  }
 }
 
+/** Successful canonical tool execution, including its Native/model projection. */
+export interface ToolExecutionSuccess {
+  readonly isError: false
+  /** Execution-local canonical value; deliberately omitted from durable events. */
+  readonly value: JsonValue
+  readonly content: ContentBlock[]
+  readonly error?: never
+  readonly meta?: JsonValue
+  readonly additionalContexts?: HookContext[]
+}
+
+/** Failed canonical tool execution; failures never carry a successful value. */
+export interface ToolExecutionFailure {
+  readonly isError: true
+  readonly error: ToolFailure
+  readonly value?: never
+  readonly content: ContentBlock[]
+  readonly meta?: JsonValue
+  readonly additionalContexts?: HookContext[]
+}
+
+/** The discriminated, execution-local outcome of one tool call. */
+export type ToolExecutionResult = ToolExecutionSuccess | ToolExecutionFailure
+
 /**
  * Pre-dispatch decision. `allow` runs the call; `deny` materializes an error;
  * `ask` runs only after an approval service returns `allowed-once` and otherwise
@@ -352,11 +385,12 @@ export type PreToolDecision =
   | { kind: 'ask'; reason?: string }
 
 /**
- * Post-dispatch decision: accept or replace content, attach context for the next
- * request, or block by turning corrective feedback into an error result.
+ * Post-dispatch decision: accept, replace one projection, attach context for the
+ * next request, or block by turning corrective feedback into an error result.
  */
 export type PostToolDecision =
-  | { kind: 'accept'; content?: ContentBlock[]; additionalContexts?: HookContext[] }
+  | { kind: 'accept'; content?: ContentBlock[]; value?: never; additionalContexts?: HookContext[] }
+  | { kind: 'accept'; value: JsonValue; content?: never; additionalContexts?: HookContext[] }
   | { kind: 'block'; feedback: ContentBlock[]; additionalContexts?: HookContext[] }
 
 /**
@@ -381,6 +415,23 @@ function errorMessage(error: unknown): string {
   }
 }
 
+/** Derive one failure message from policy feedback without changing its rendered blocks. */
+function failureMessageFromContent(content: ContentBlock[]): string {
+  const text = content
+    .map(block => block.type === 'text' ? block.text : `[${block.type} content]`)
+    .join('\n')
+  return text.length > 0 ? text : 'tool result blocked by post-execute policy'
+}
+
+/** Snapshot and freeze one durable tool-result projection or reject lossy data. */
+function materializePresentation<T>(candidate: T): T {
+  const detached = snapshotJsonValue(candidate)
+  if (detached === undefined) {
+    throw new TypeError('tool result must be losslessly JSON-serializable')
+  }
+  return deepFreeze(detached)
+}
+
 /** Structured `{ name, code }` for a thrown HarnessError, else undefined. */
 function errorInfo(error: unknown): ToolErrorInfo | undefined {
   try {
@@ -553,6 +604,13 @@ export class ToolRegistry extends Service {
   register(definition: ToolDefinition): () => void {
     const scope = scopeOf(this.ctx)
     const name = definition.name
+    const output = (definition as Partial<ToolDefinition>).output
+    if (output === undefined || typeof output !== 'object'
+      || typeof output.render !== 'function'
+      || (output.presentationMeta !== undefined && typeof output.presentationMeta !== 'function')) {
+      throw new TypeError(`tool "${name}" must declare output { schema, render, presentationMeta? }`)
+    }
+    assertSupportedJsonSchema(output.schema)
     const timeoutMs = definition.timeoutMs
     if (timeoutMs !== undefined
       && (!Number.isFinite(timeoutMs) || timeoutMs <= 0)) {
@@ -880,10 +938,11 @@ export class ToolRegistry extends Service {
         return await next({
           kind: 'post-result',
           exec,
-          result: {
+          result: this.materializeFinalResult({
             content: [{ type: 'text', text: `Error: ${denialReason}` }],
             isError: true,
-          },
+            error: { message: denialReason },
+          }),
         })
       }
       return await next({ kind: 'dispatch', exec })
@@ -909,27 +968,26 @@ export class ToolRegistry extends Service {
             const tool = this.get(exec.name, exec.agent)
             if (!tool) throw new ToolNotFoundError(exec.name)
             const returned = await tool.execute(exec.arguments, exec)
-            const content = Array.isArray(returned) ? returned : returned.content
-            const meta = Array.isArray(returned) ? undefined : returned.meta
-            return { content, isError: false, ...meta !== undefined ? { meta } : {} }
+            return this.createSuccessResult(exec, tool, returned)
           } catch (error: unknown) {
-            return toolErrorResult(error)
+            return this.materializeFinalResult(toolErrorResult(error))
           }
         },
       )
+      const normalized = this.normalizeDispatchResult(exec, result)
       const deferredContexts = this.deferredContexts.get(exec)
       /* v8 ignore next -- dispatch only receives executions minted by this registry's prepare stage */
       if (deferredContexts === undefined) throw new Error('tool registry scheduler invariant violated: unprepared execution')
       const resultWithDeferredContexts: ToolExecutionResult = deferredContexts.length === 0
-        ? result
-        : {
-          ...result,
+        ? normalized
+        : this.markCanonical({
+          ...normalized,
           additionalContexts: [
             ...deferredContexts,
-            ...result.additionalContexts ?? [],
+            ...normalized.additionalContexts ?? [],
           ],
-        }
-      return { kind: 'post-result', result: resultWithDeferredContexts }
+        })
+      return { kind: 'post-result', result: this.materializeFinalResult(resultWithDeferredContexts) }
     } catch (error: unknown) {
       return { kind: 'final-result', result: toolErrorResult(error) }
     }
@@ -1046,32 +1104,103 @@ export class ToolRegistry extends Service {
     )
     const decisionContexts = decision.additionalContexts ?? []
     if (decision.kind === 'block') {
-      return {
+      const message = failureMessageFromContent(decision.feedback)
+      return this.markCanonical({
         content: decision.feedback,
         isError: true,
+        error: { message },
         ...decisionContexts.length > 0 ? { additionalContexts: decisionContexts } : {},
-      }
+      })
+    }
+    if (Object.hasOwn(decision, 'content') && Object.hasOwn(decision, 'value')) {
+      throw new TypeError('tools/post-execute accept decision cannot replace both value and content')
     }
-    // Accept: replace content if supplied, preserve the dispatched outcome, and
-    // append decision contexts after contexts deferred by the tool body.
     const additionalContexts = [
       ...result.additionalContexts ?? [],
       ...decisionContexts,
     ]
-    return {
-      ...result,
-      ...decision.content ? { content: decision.content } : {},
-      ...additionalContexts.length > 0 ? { additionalContexts } : {},
+    if (Object.hasOwn(decision, 'value')) {
+      if (result.isError) {
+        throw new TypeError('tools/post-execute cannot replace the value of a failed result')
+      }
+      const tool = this.get(exec.name, exec.agent)
+      if (tool === undefined) throw new ToolNotFoundError(exec.name)
+      const replaced = this.createSuccessResult(exec, tool, decision.value)
+      return this.markCanonical({
+        ...replaced,
+        ...additionalContexts.length > 0 ? { additionalContexts } : {},
+      })
     }
+    return this.markCanonical({
+      ...result,
+      ...decision.content !== undefined ? { content: decision.content } : {},
+      ...additionalContexts.length > 0 ? { additionalContexts } : {},
+    })
+  }
+
+  /** Results created by the registry already own a validated, frozen canonical value. */
+  private readonly canonicalResults = new WeakSet<object>()
+
+  /** Mark a registry-normalized result without freezing presentation fields prematurely. */
+  private markCanonical<T extends ToolExecutionResult>(result: T): T {
+    this.canonicalResults.add(result)
+    return result
+  }
+
+  /** Snapshot, validate, render, and optionally project one successful body value. */
+  private createSuccessResult(exec: ToolExecution, tool: ToolDefinition, candidate: unknown): ToolExecutionSuccess {
+    const detached = snapshotJsonValue(candidate)
+    if (detached === undefined) {
+      throw new ToolOutputError(tool.name, ['value is not lossless JSON'])
+    }
+    const violations = validateJsonSchemaValue(tool.output.schema, detached, 'value')
+    if (violations.length > 0) throw new ToolOutputError(tool.name, violations)
+    const value = deepFreeze(detached as JsonValue)
+    const content = tool.output.render(exec.arguments, value)
+    const meta = exec.parent === undefined && tool.output.presentationMeta !== undefined
+      ? tool.output.presentationMeta(exec.arguments, value)
+      : undefined
+    return this.markCanonical(this.materializeFinalResult({
+      isError: false,
+      value,
+      content,
+      ...meta !== undefined ? { meta } : {},
+    }) as ToolExecutionSuccess)
+  }
+
+  /** Normalize an around-dispatch wrapper's authored result through the owning output contract. */
+  private normalizeDispatchResult(exec: ToolExecution, result: ToolExecutionResult): ToolExecutionResult {
+    if (this.canonicalResults.has(result)) return result
+    if (result.isError) {
+      return this.markCanonical({
+        isError: true,
+        error: result.error,
+        content: result.content,
+        ...result.meta !== undefined ? { meta: result.meta } : {},
+        ...result.additionalContexts !== undefined ? { additionalContexts: result.additionalContexts } : {},
+      })
+    }
+    const tool = this.get(exec.name, exec.agent)
+    if (tool === undefined) throw new ToolNotFoundError(exec.name)
+    const normalized = this.createSuccessResult(exec, tool, result.value)
+    return this.markCanonical({
+      ...normalized,
+      ...result.additionalContexts !== undefined ? { additionalContexts: result.additionalContexts } : {},
+    })
   }
 
   /** Materialize the authoritative commit outcome once, immediately before `tools/result`. */
   private materializeFinalResult(result: ToolExecutionResult): ToolExecutionResult {
-    const detached = snapshotJsonValue(result)
-    if (detached === undefined) {
-      throw new TypeError('tool result must be losslessly JSON-serializable')
+    const presentation = {
+      content: result.content,
+      ...result.meta !== undefined ? { meta: result.meta } : {},
+      ...result.additionalContexts !== undefined ? { additionalContexts: result.additionalContexts } : {},
     }
-    return deepFreeze(detached)
+    if (result.isError) {
+      return materializePresentation({ isError: true as const, error: result.error, ...presentation })
+    }
+    const detached = materializePresentation({ isError: false as const, ...presentation })
+    return deepFreeze({ ...detached, value: result.value })
   }
 }
 
@@ -1082,10 +1211,11 @@ function createExecutionToken(): ToolExecutionToken {
 
 function toolErrorResult(error: unknown): ToolExecutionResult {
   const info = errorInfo(error)
+  const message = errorMessage(error)
   return {
-    content: [{ type: 'text', text: `Error: ${errorMessage(error)}` }],
+    content: [{ type: 'text', text: `Error: ${message}` }],
     isError: true,
-    ...info ? { error: info } : {},
+    error: { message, ...info ? { info } : {} },
   }
 }
 

packages/core/tools/src/schema.ts

@@ -1,8 +1,9 @@
 /** Unified JSON-value schema DSL, inference, compilation, and typed tool helper. @module dsh-tools/schema */
 
 import { HarnessError } from '@deepseek-ai/dsh-llm'
+import type { ContentBlock } from '@deepseek-ai/dsh-llm'
 import type { JsonValue } from '@deepseek-ai/dsh-session'
-import type { ToolDefinition, ToolExecuteReturn, ToolRunContext, ToolResult } from './index.ts'
+import type { ToolDefinition, ToolRunContext, ToolResult } from './index.ts'
 import { assertSupportedJsonSchema, isPlainJsonRecord, JsonSchemaError, validateJsonSchemaValue } from './json-schema.ts'
 import type { JsonSchemaNode, JsonSchemaScalar, ObjectJsonSchema } from './json-schema.ts'
 import type { ToolCallView, ToolResultView } from './presentation.ts'
@@ -114,21 +115,25 @@ type RequiredKeys<S extends ParameterSchemaSpec> = {
   [K in keyof S]: S[K] extends { required: true } ? K : never
 }[keyof S]
 
+/** Advance the bounded inference walk through one nested schema node. */
+type NextDepth<D extends readonly unknown[]> = readonly [...D, unknown]
+
 /** Infer the declared value of one parameter property without key optionality. */
-type InferProperty<P extends ParameterPropertySpec> = P extends ValueSchemaSpec ? InferValue<P> : never
+type InferProperty<P extends ParameterPropertySpec, D extends readonly unknown[]> =
+  P extends ValueSchemaSpec ? InferValue<P, D> : never
 
 /** Infer an implicit property map into required and optional object keys. */
-type InferProperties<S extends ParameterSchemaSpec> = Simplify<
-  & { [K in RequiredKeys<S>]: InferProperty<S[K]> }
-  & { [K in Exclude<keyof S, RequiredKeys<S>>]?: InferProperty<S[K]> }
+type InferProperties<S extends ParameterSchemaSpec, D extends readonly unknown[]> = Simplify<
+  & { [K in RequiredKeys<S>]: InferProperty<S[K], D> }
+  & { [K in Exclude<keyof S, RequiredKeys<S>>]?: InferProperty<S[K], D> }
 >
 
 /** Infer an explicit object node, including its declared openness. */
-type InferObject<S extends ObjectValueSchemaSpec> =
+type InferObject<S extends ObjectValueSchemaSpec, D extends readonly unknown[]> =
   S extends { properties: infer P extends ParameterSchemaSpec }
     ? S['additionalProperties'] extends true
-      ? InferProperties<P> & Record<string, JsonValue>
-      : InferProperties<P>
+      ? InferProperties<P, D> & Record<string, JsonValue>
+      : InferProperties<P, D>
     : S['additionalProperties'] extends true
       ? Record<string, JsonValue>
       : Record<string, never>
@@ -143,20 +148,21 @@ type InferScalar<S, Fallback> =
  * Infer the TypeScript value accepted by an author-facing value schema.
  * Output schemas may therefore infer object, array, scalar, or null roots.
  */
-export type InferValue<S extends ValueSchemaSpec> =
-  S extends StringValueSchemaSpec ? InferScalar<S, string> :
-    S extends NumberValueSchemaSpec | IntegerValueSchemaSpec ? InferScalar<S, number> :
-      S extends BooleanValueSchemaSpec ? InferScalar<S, boolean> :
-        S extends NullValueSchemaSpec ? null :
-          S extends ArrayValueSchemaSpec
-            ? S extends { items: infer I extends ValueSchemaSpec } ? InferValue<I>[] : JsonValue[]
-            : S extends ObjectValueSchemaSpec ? InferObject<S> :
-              S extends JsonValueSchemaSpec ? JsonValue :
-                S extends OneOfValueSchemaSpec ? InferValue<S['oneOf'][number]> :
-                  never
+export type InferValue<S extends ValueSchemaSpec, D extends readonly unknown[] = readonly []> =
+  D['length'] extends 12 ? JsonValue :
+    S extends StringValueSchemaSpec ? InferScalar<S, string> :
+      S extends NumberValueSchemaSpec | IntegerValueSchemaSpec ? InferScalar<S, number> :
+        S extends BooleanValueSchemaSpec ? InferScalar<S, boolean> :
+          S extends NullValueSchemaSpec ? null :
+            S extends ArrayValueSchemaSpec
+              ? S extends { items: infer I extends ValueSchemaSpec } ? InferValue<I, NextDepth<D>>[] : JsonValue[]
+              : S extends ObjectValueSchemaSpec ? InferObject<S, NextDepth<D>> :
+                S extends JsonValueSchemaSpec ? JsonValue :
+                  S extends OneOfValueSchemaSpec ? InferValue<S['oneOf'][number], NextDepth<D>> :
+                    never
 
 /** Infer the TypeScript argument object for an implicit parameter schema. */
-export type InferArgs<S extends ParameterSchemaSpec> = InferProperties<S>
+export type InferArgs<S extends ParameterSchemaSpec> = InferProperties<S, readonly []>
 
 const ANNOTATION_KEYS = ['description', 'title', 'default', 'examples'] as const
 
@@ -329,13 +335,22 @@ export function validateArgs(spec: ParameterSchemaSpec, args: unknown): string[]
 }
 
 /** Options for {@link defineTool}. */
-export interface DefineToolOptions<S extends ParameterSchemaSpec> {
+export interface DefineToolOptions<S extends ParameterSchemaSpec, O extends ValueSchemaSpec> {
   /** Tool name (must be unique). */
   readonly name: string
   /** Human-readable description sent to the model. */
   readonly description: string
   /** Per-property parameter schema compiled to an implicit open object root. */
   readonly parameters: S
+  /** Canonical output schema plus pure Native and presentation projections. */
+  readonly output: {
+    /** Schema enforced against every successful body or policy-replaced value. */
+    readonly schema: O
+    /** Pure Native/model rendering of one validated canonical value. */
+    render(args: InferArgs<S>, value: InferValue<NoInfer<O>>): ContentBlock[]
+    /** Pure replayable presentation metadata for direct surface calls. */
+    presentationMeta?(args: InferArgs<S>, value: InferValue<NoInfer<O>>): JsonValue
+  }
   /** Optional positive cooperative timeout budget in milliseconds. */
   readonly timeoutMs?: number
   /**
@@ -348,9 +363,9 @@ export interface DefineToolOptions<S extends ParameterSchemaSpec> {
    * Execute the tool after argument validation.
    * @param args - typed validated arguments.
    * @param exec - execution identity, caller, cancellation, and nesting data.
-   * @returns Model-facing content and optional presentation metadata.
+   * @returns The canonical value declared by `output.schema`.
    */
-  execute(args: InferArgs<S>, exec: ToolRunContext): Promise<ToolExecuteReturn>
+  execute(args: InferArgs<S>, exec: ToolRunContext): Promise<InferValue<NoInfer<O>>>
   /**
    * Pure pending-state presenter.
    * @param args - typed validated arguments.
@@ -373,11 +388,17 @@ export interface DefineToolOptions<S extends ParameterSchemaSpec> {
  * @param options - typed definition and optional presenters.
  * @returns A registry-ready definition.
  */
-export function defineTool<S extends ParameterSchemaSpec>(options: DefineToolOptions<S>): ToolDefinition {
+export function defineTool<const S extends ParameterSchemaSpec, const O extends ValueSchemaSpec>(
+  options: DefineToolOptions<S, O>,
+): ToolDefinition {
   // Object-literal methods do not use `this`; retaining references is safe.
   // eslint-disable-next-line @typescript-eslint/unbound-method
   const userExecute = options.execute
   // eslint-disable-next-line @typescript-eslint/unbound-method
+  const userRender = options.output.render
+  // eslint-disable-next-line @typescript-eslint/unbound-method
+  const userPresentationMeta = options.output.presentationMeta
+  // eslint-disable-next-line @typescript-eslint/unbound-method
   const userPresentCall = options.presentCall
   // eslint-disable-next-line @typescript-eslint/unbound-method
   const userPresentResult = options.presentResult
@@ -387,16 +408,28 @@ export function defineTool<S extends ParameterSchemaSpec>(options: DefineToolOpt
     throw new Error(`defineTool(${options.name}): timeoutMs must be a positive finite number`)
   }
   const parameters = parameterSchemaSpecToJsonSchema(options.parameters)
+  const outputSchema = valueSchemaSpecToJsonSchema(options.output.schema)
   const validate = (args: unknown): string[] => validateJsonSchemaValue(parameters, args, '')
   const tool: ToolDefinition = {
     name: options.name,
     description: options.description,
     parameters: parameters as unknown as Record<string, unknown>,
+    output: {
+      schema: outputSchema,
+      render(args: unknown, value: JsonValue): ContentBlock[] {
+        return userRender(args as InferArgs<S>, value as unknown as InferValue<NoInfer<O>>)
+      },
+      ...userPresentationMeta !== undefined ? {
+        presentationMeta(args: unknown, value: JsonValue): JsonValue {
+          return userPresentationMeta(args as InferArgs<S>, value as unknown as InferValue<NoInfer<O>>)
+        },
+      } : {},
+    },
     ...(options.timeoutMs !== undefined ? { timeoutMs: options.timeoutMs } : {}),
-    async execute(args: unknown, exec: ToolRunContext): Promise<ToolExecuteReturn> {
+    async execute(args: unknown, exec: ToolRunContext): Promise<JsonValue> {
       const violations = validate(args)
       if (violations.length > 0) throw new ToolArgsError(violations)
-      return userExecute(args as InferArgs<S>, exec)
+      return userExecute(args as InferArgs<S>, exec) as Promise<JsonValue>
     },
   }
   if (userPresentCall) {

packages/core/tools/src/testing.ts

@@ -0,0 +1,42 @@
+/** Canonical tool-definition fixtures for repository tests. @module dsh-tools/testing */
+
+import type { ContentBlock } from '@deepseek-ai/dsh-llm'
+import type { JsonValue } from '@deepseek-ai/dsh-session'
+import { defineTool } from './schema.ts'
+import type { DefineToolOptions, ParameterSchemaSpec } from './schema.ts'
+import type { ToolDefinition, ToolRunContext } from './index.ts'
+
+const CONTENT_VALUE_SCHEMA = { type: 'array', items: { type: 'json' } } as const
+
+/** Options for a fixture whose canonical value is its rendered content array. */
+export type ContentToolFixtureOptions<S extends ParameterSchemaSpec> = Omit<
+  DefineToolOptions<S, typeof CONTENT_VALUE_SCHEMA>,
+  'output' | 'execute'
+> & {
+  /** Produce the fixture's content blocks as its canonical test value. */
+  execute(args: import('./schema.ts').InferArgs<S>, exec: ToolRunContext): Promise<ContentBlock[]>
+}
+
+/**
+ * Define a test fixture that deliberately uses its content blocks as the
+ * canonical JSON value. Product tools must declare domain-owned DTOs instead.
+ * @param options - ordinary fixture fields plus a content-producing body.
+ * @returns a registry-ready tool with an explicit JSON-array output contract.
+ * @internal
+ */
+export function defineContentToolFixture<const S extends ParameterSchemaSpec>(
+  options: ContentToolFixtureOptions<S>,
+): ToolDefinition {
+  // eslint-disable-next-line @typescript-eslint/unbound-method
+  const execute = options.execute
+  return defineTool({
+    ...options,
+    output: {
+      schema: CONTENT_VALUE_SCHEMA,
+      render: (_args, value) => value as unknown as ContentBlock[],
+    },
+    async execute(args, exec) {
+      return await execute(args, exec) as unknown as JsonValue[]
+    },
+  })
+}