@tt-a1i/openpi 0.5.0 → 0.6.1

package/extensions/subagents/src/agent-types.ts

@@ -92,6 +92,8 @@ export interface AgentType {
   readonly description: string;
   /** Omitted = the child keeps the normal tool set. Present = allowlist. */
   readonly tools?: readonly string[];
+  /** Only built-in investigator definitions carry this planning compatibility. */
+  readonly planningCompatible?: boolean;
   /** "provider/model-id" or a bare id; resolved by the pi backend. */
   readonly model?: string;
   readonly reasoningEffort?: ReasoningEffort;
@@ -121,9 +123,9 @@ export const READ_ONLY_AGENT_TOOLS = [
 export const BUILT_IN_AGENT_TYPES: readonly AgentType[] = [
   {
     name: "explorer",
+    planningCompatible: true,
     description:
       "Read-only codebase exploration. Usually use moderate reasoning, increasing it for harder tasks.",
-    tools: READ_ONLY_AGENT_TOOLS,
     body: "Explore the codebase read-only. Trace the real flow, inspect related callers, and report concise evidence with file paths and line references.",
     source: "built-in:explorer",
   },
@@ -131,36 +133,22 @@ export const BUILT_IN_AGENT_TYPES: readonly AgentType[] = [
     name: "implementer",
     description:
       "Focused implementation with repository checks. Usually use medium-high reasoning, adjusted for scope, risk, and task difficulty.",
-    tools: [
-      "read",
-      "bash",
-      "edit",
-      "write",
-      "grep",
-      "find",
-      "ls",
-      "fd",
-      "rg",
-      "git_show",
-      "git_diff",
-      "git_log",
-    ],
     body: "Implement the requested change carefully. Trace the affected flow first, make the smallest correct edit, and run relevant checks before reporting results.",
     source: "built-in:implementer",
   },
   {
     name: "reviewer",
+    planningCompatible: true,
     description:
       "Read-only review for correctness, safety, and regressions. Usually use high reasoning, adjusted for task difficulty.",
-    tools: READ_ONLY_AGENT_TOOLS,
     body: "Review the requested code or change read-only. Identify concrete correctness, security, and regression risks with evidence; do not modify files.",
     source: "built-in:reviewer",
   },
   {
     name: "advisor",
+    planningCompatible: true,
     description:
       "Deep read-only analysis and technical advice. Usually use high reasoning, adjusted for task difficulty.",
-    tools: READ_ONLY_AGENT_TOOLS,
     body: "Analyze the problem deeply without modifying files. Explain the relevant tradeoffs, risks, and recommended next step using repository evidence.",
     source: "built-in:advisor",
   },

package/extensions/subagents/src/backends/pi.ts

@@ -19,11 +19,13 @@ import type {
 } from "@earendil-works/pi-coding-agent";
 import {
   createAgentSession,
+  getAgentDir,
   SessionManager,
 } from "@earendil-works/pi-coding-agent";
 import type { Cause, Scope } from "effect";
 import { Effect, Queue, Stream } from "effect";
 import { resolveAgentModel } from "../agent-types.ts";
+import { toolPreview } from "./tool-preview.ts";
 import type {
   SubagentBackend,
   SubagentCleanupReceipt,
@@ -49,6 +51,14 @@ import {
   reclaimWorktree,
 } from "../../../shared/worktree.ts";
 import { AgentToolRenderLedger } from "../../../shared/agent-tool-renderer.ts";
+import {
+  childToolsWithStructuredOutput,
+  createStructuredOutputTool,
+  encodeStructuredResult,
+  type EncodedStructuredResult,
+  STRUCTURED_OUTPUT_SYSTEM_INSTRUCTION,
+} from "../../../shared/structured-output.ts";
+import { persistStructuredResultArtifact } from "../result-artifact.ts";
 
 const DIRECT_WORKTREE_CLEANUP_TIMEOUT_MS = 4_000;
 const PARTIAL_TEXT_MAX_LENGTH = 128 * 1_024;
@@ -109,27 +119,6 @@ function safeJson(value: unknown): string | undefined {
   }
 }
 
-/** First non-empty line of a tool result-ish value (v1 liveToolPreview). */
-function toolPreview(value: unknown): string | undefined {
-  if (typeof value === "string") {
-    return value
-      .split("\n")
-      .find((line) => line.trim())
-      ?.trim();
-  }
-  if (!value || typeof value !== "object") return undefined;
-  const content = (value as { content?: unknown }).content;
-  if (!Array.isArray(content)) return undefined;
-  for (const part of content) {
-    if (!part || typeof part !== "object") continue;
-    const record = part as { type?: unknown; text?: unknown };
-    if (record.type !== "text" || typeof record.text !== "string") continue;
-    const firstLine = record.text.split("\n").find((line) => line.trim());
-    if (firstLine) return firstLine.trim();
-  }
-  return undefined;
-}
-
 function assistantParts(msg: AssistantMessage): TranscriptPart[] {
   const parts: TranscriptPart[] = [];
   for (const part of msg.content) {
@@ -198,38 +187,93 @@ const makePiSession = (
     const thinkingLevel = (task.reasoningEffort ??
       task.parent.inheritedThinkingLevel) as ThinkingLevel | undefined;
 
+    let capturedStructured: EncodedStructuredResult | undefined;
+    const structuredOutputTool =
+      task.outputSchema === undefined
+        ? undefined
+        : createStructuredOutputTool(task.outputSchema, (value) => {
+            capturedStructured = encodeStructuredResult(value);
+          });
+
+    // Own the session before asynchronous startup. Interruption can happen
+    // before the normal backend finalizer has been installed.
+    let acquiringSession: AgentSession | undefined;
+    let startupOwned = true;
+    const cleanupStartup = () =>
+      acquiringSession
+        ? shutdownAndDisposeChildSession(acquiringSession, {
+            abort: true,
+            timeoutMs: options.shutdownTimeoutMs,
+          })
+        : Promise.resolve();
+    yield* Effect.addFinalizer(() =>
+      Effect.promise(async () => {
+        if (startupOwned) await cleanupStartup();
+      }),
+    );
+
     const session = yield* Effect.tryPromise({
-      try: async () => {
-        const { loader, settingsManager } = await createChildResources({
-          cwd: task.cwd,
-          projectTrusted: task.parent.projectTrusted,
-          ...(task.appendSystemPrompt
-            ? { appendSystemPrompt: [...task.appendSystemPrompt] }
-            : {}),
-        });
-        const { session } = await (
-          options.sessionFactory ?? createAgentSession
-        )({
-          cwd: task.cwd,
-          sessionManager: SessionManager.create(task.cwd),
-          settingsManager,
-          resourceLoader: loader,
-          model,
-          thinkingLevel,
-          ...childToolPolicy(task.tools),
-        });
-        // Start child extension session hooks/resources in headless mode.
-        // A rejection here would otherwise leak the freshly created session:
-        // the scope finalizer that owns cleanup is only registered later.
+      try: async (signal) => {
+        const checkCancelled = () => {
+          if (signal.aborted)
+            throw signal.reason ?? new Error("Subagent startup cancelled");
+        };
+        const onCancelled = () => {
+          void cleanupStartup().catch(() => {});
+        };
+        signal.addEventListener("abort", onCancelled, { once: true });
         try {
-          await bindChildSessionExtensions(session, task.tools);
-        } catch (error) {
-          await shutdownAndDisposeChildSession(session, {
-            timeoutMs: options.shutdownTimeoutMs,
+          checkCancelled();
+          const appendSystemPrompt = [
+            ...(task.appendSystemPrompt ?? []),
+            ...(structuredOutputTool
+              ? [STRUCTURED_OUTPUT_SYSTEM_INSTRUCTION]
+              : []),
+          ];
+          const { loader, settingsManager } = await createChildResources({
+            cwd: task.cwd,
+            projectTrusted: task.parent.projectTrusted,
+            ...(appendSystemPrompt.length > 0 ? { appendSystemPrompt } : {}),
+          });
+          checkCancelled();
+          const { session } = await (
+            options.sessionFactory ?? createAgentSession
+          )({
+            cwd: task.cwd,
+            sessionManager: SessionManager.create(task.cwd),
+            settingsManager,
+            resourceLoader: loader,
+            model,
+            thinkingLevel,
+            ...(structuredOutputTool
+              ? { customTools: [structuredOutputTool] }
+              : {}),
+            ...childToolPolicy(
+              childToolsWithStructuredOutput(
+                task.tools,
+                structuredOutputTool !== undefined,
+              ),
+            ),
           });
+          acquiringSession = session;
+          checkCancelled();
+          // Never start extension binding for a factory that completed after
+          // cancellation. Already-running hooks retain bounded cleanup ownership.
+          await bindChildSessionExtensions(
+            session,
+            childToolsWithStructuredOutput(
+              task.tools,
+              structuredOutputTool !== undefined,
+            ),
+          );
+          checkCancelled();
+          return session;
+        } catch (error) {
+          await cleanupStartup();
           throw error;
+        } finally {
+          signal.removeEventListener("abort", onCancelled);
         }
-        return session;
       },
       catch: (error) => new SpawnError({ message: boundedError(error) }),
     });
@@ -338,11 +382,46 @@ const makePiSession = (
         });
         return;
       }
+      if (task.outputSchema !== undefined && capturedStructured === undefined) {
+        emit({
+          _tag: "RunSettled",
+          outcome: {
+            _tag: "Failed",
+            errorText:
+              "Agent finished without calling structured_output; no structured result matching output_schema was produced.",
+            partialText,
+          },
+        });
+        return;
+      }
+      let structuredResult;
+      if (capturedStructured) {
+        try {
+          structuredResult = {
+            ...capturedStructured,
+            artifactPath: persistStructuredResultArtifact(
+              getAgentDir(),
+              capturedStructured.json,
+            ),
+          };
+        } catch (error) {
+          emit({
+            _tag: "RunSettled",
+            outcome: {
+              _tag: "Failed",
+              errorText: `Structured result artifact could not be persisted: ${boundedError(error)}`,
+              partialText,
+            },
+          });
+          return;
+        }
+      }
       emit({
         _tag: "RunSettled",
         outcome: {
           _tag: "Completed",
           finalText: prompt.finalText,
+          ...(structuredResult ? { structuredResult } : {}),
         },
       });
     };
@@ -580,6 +659,8 @@ const makePiSession = (
       }),
     );
 
+    startupOwned = false;
+
     /** Start a fresh run (v1 manager.run): fire-and-forget, errors -> events. */
     const startRun = (text: string) => {
       if (state.activePrompt) {
@@ -597,6 +678,7 @@ const makePiSession = (
         promise: Promise.resolve(),
       };
       state.activePrompt = activePrompt;
+      capturedStructured = undefined;
       state.settled = false;
       emit({ _tag: "RunStarted" });
       let prompt: Promise<void>;

package/extensions/subagents/src/backends/tool-preview.ts

@@ -0,0 +1,29 @@
+// Match the manager's existing transcript text limit; canonical Pi tool results
+// remain intact. Only the normalized event's single-line preview is bounded.
+const TOOL_PREVIEW_MAX_LENGTH = 64 * 1_024;
+
+function firstMeaningfulLine(text: string) {
+  // Search only until the first non-whitespace character. Unlike splitting the
+  // entire log, this preserves blank-line behavior without visiting its tail.
+  const start = text.search(/\S/);
+  if (start < 0) return undefined;
+  const prefix = text.slice(start, start + TOOL_PREVIEW_MAX_LENGTH);
+  const newline = prefix.indexOf("\n");
+  return (newline < 0 ? prefix : prefix.slice(0, newline)).trimEnd();
+}
+
+/** First meaningful line of a tool result, without splitting accumulated logs. */
+export function toolPreview(value: unknown) {
+  if (typeof value === "string") return firstMeaningfulLine(value);
+  if (!value || typeof value !== "object") return undefined;
+  const content = (value as { content?: unknown }).content;
+  if (!Array.isArray(content)) return undefined;
+  for (const part of content) {
+    if (!part || typeof part !== "object") continue;
+    const record = part as { type?: unknown; text?: unknown };
+    if (record.type !== "text" || typeof record.text !== "string") continue;
+    const firstLine = firstMeaningfulLine(record.text);
+    if (firstLine) return firstLine;
+  }
+  return undefined;
+}

package/extensions/subagents/src/domain.ts

@@ -69,6 +69,8 @@ export interface SpawnTask {
   readonly tools?: readonly string[];
   /** Agent type that supplied the above, for the session label. */
   readonly agentTypeName?: string;
+  /** Optional JSON Schema for one terminating, validated child result. */
+  readonly outputSchema?: unknown;
   /**
    * Isolated git worktree this child runs in, created by the tool layer. The
    * backend only reclaims it when the session scope closes; it does not know
@@ -142,7 +144,11 @@ export interface QueuedMessage {
 // --- Events ------------------------------------------------------------------
 
 export type RunOutcome =
-  | { readonly _tag: "Completed"; readonly finalText: string }
+  | {
+      readonly _tag: "Completed";
+      readonly finalText: string;
+      readonly structuredResult?: StructuredSubagentResult;
+    }
   | {
       readonly _tag: "Failed";
       readonly errorText: string;
@@ -232,10 +238,19 @@ export interface SubagentSnapshot {
   readonly queued: ReadonlyArray<QueuedMessage>;
   /** Final text of the most recent completed run (v1 `finalOutput`). */
   readonly finalText: string;
+  /** Present only when this run supplied and satisfied output_schema. */
+  readonly structuredResult?: StructuredSubagentResult;
   /** Count of finalized assistant messages (for subagent_check). */
   readonly turns: number;
 }
 
+export interface StructuredSubagentResult {
+  readonly value: unknown;
+  readonly json: string;
+  readonly byteLength: number;
+  readonly artifactPath: string;
+}
+
 /** Final text, or the live streaming buffer while a run is active (v1 `latestOutput`). */
 export function latestText(snap: SubagentSnapshot) {
   const live = snap.liveAssistant?.text.trim();

package/extensions/subagents/src/manager.ts

@@ -10,10 +10,8 @@
  * imperative TUI components (which render synchronously) can read snapshots
  * and issue fire-and-forget commands without touching the Effect runtime.
  *
- * Every run is guarded by a first-response watchdog: a provider that accepts
- * the request but never emits its first assistant event is settled as a
- * failure (releasing its concurrency slot) instead of hanging forever,
- * mirroring the workflow runner's watchdog.
+ * Pi owns provider transport timeouts and retries. This manager owns explicit
+ * cancellation, settlement, and bounded cleanup, not model-output deadlines.
  */
 
 import {
@@ -60,13 +58,6 @@ export const MAX_TRACKED = 64;
 const STOP_TIMEOUT_MS = 5_000;
 /** Session abort/shutdown (5s) plus bounded direct-worktree cleanup (4s). */
 const ENTRY_CLOSE_TIMEOUT_MS = 10_000;
-/**
- * First-response watchdog: a run whose provider accepts the request but
- * never emits an assistant event is settled as a failure so it cannot
- * occupy a concurrency slot forever. Matches the workflow runner's
- * MODEL_PROGRESS_TIMEOUT_MS (extensions/workflows/runner.ts).
- */
-export const FIRST_RESPONSE_TIMEOUT_MS = 45_000;
 const ERROR_TEXT_MAX_LENGTH = 4_096;
 const TRANSCRIPT_TEXT_MAX_LENGTH = 64 * 1_024;
 const LIVE_ASSISTANT_MAX_LENGTH = 128 * 1_024;
@@ -77,10 +68,6 @@ function bounded(text: string) {
   return text.slice(0, ERROR_TEXT_MAX_LENGTH);
 }
 
-function formatWatchdogTimeout(ms: number) {
-  return ms % 1_000 === 0 ? `${ms / 1_000} seconds` : `${ms} ms`;
-}
-
 function boundedTranscriptText(text: string) {
   return text.slice(0, TRANSCRIPT_TEXT_MAX_LENGTH);
 }
@@ -123,6 +110,7 @@ interface MutableSnapshot {
   liveTools: LiveToolState[];
   queued: SubagentSnapshot["queued"];
   finalText: string;
+  structuredResult?: SubagentSnapshot["structuredResult"];
   turns: number;
 }
 
@@ -132,8 +120,6 @@ interface Entry {
   scope: Scope.Closeable;
   pump?: Fiber.Fiber<void>;
   liveToolMap: Map<string, LiveToolState>;
-  /** First-response watchdog timer for the active (or just-armed) run. */
-  watchdogTimer?: ReturnType<typeof setTimeout>;
   /** Idle restart dispatched but RunStarted not folded yet; counts as running
    * so concurrent restarts cannot race past the cap. */
   restarting?: boolean;
@@ -213,8 +199,6 @@ export class SubagentManager extends Context.Service<
 
 const makeManager = (config: SubagentManagerConfig = {}) =>
   Effect.gen(function* () {
-    const firstResponseTimeoutMs =
-      config.firstResponseTimeoutMs ?? FIRST_RESPONSE_TIMEOUT_MS;
     const registry = yield* BackendRegistry;
     // Detached forker for sync contexts (read-model commands, pruning) that
     // preserves the manager's services instead of using the global runtime.
@@ -343,7 +327,6 @@ const makeManager = (config: SubagentManagerConfig = {}) =>
     };
 
     const settle = (entry: Entry, outcome: RunOutcome) => {
-      clearWatchdog(entry);
       const s = entry.snapshot;
       const wasRestarting = entry.restarting === true;
       entry.restarting = false;
@@ -363,6 +346,7 @@ const makeManager = (config: SubagentManagerConfig = {}) =>
           s.outcome = "completed";
           s.errorText = undefined;
           s.finalText = outcome.finalText.slice(0, FINAL_TEXT_MAX_LENGTH);
+          s.structuredResult = outcome.structuredResult;
           break;
         case "Failed":
           s.status = "error";
@@ -373,6 +357,7 @@ const makeManager = (config: SubagentManagerConfig = {}) =>
             0,
             FINAL_TEXT_MAX_LENGTH,
           );
+          s.structuredResult = undefined;
           break;
         case "Interrupted":
           s.status = "error";
@@ -382,6 +367,7 @@ const makeManager = (config: SubagentManagerConfig = {}) =>
             0,
             FINAL_TEXT_MAX_LENGTH,
           );
+          s.structuredResult = undefined;
           break;
       }
       s.liveAssistant = undefined;
@@ -399,44 +385,6 @@ const makeManager = (config: SubagentManagerConfig = {}) =>
       pruneSettled();
     };
 
-    /** Stop the first-response watchdog (first response arrived / run settled). */
-    const clearWatchdog = (entry: Entry) => {
-      if (entry.watchdogTimer !== undefined) {
-        clearTimeout(entry.watchdogTimer);
-        entry.watchdogTimer = undefined;
-      }
-    };
-
-    /** Settle a run whose provider never emitted a first assistant response. */
-    const watchdogExpired = (entry: Entry) => {
-      entry.watchdogTimer = undefined;
-      if (!isBusy(entry)) return;
-      const model = entry.snapshot.meta.modelLabel;
-      settle(entry, {
-        _tag: "Failed",
-        errorText: `Agent received no assistant response event${model ? ` for ${model}` : ""} within ${formatWatchdogTimeout(firstResponseTimeoutMs)}; the provider request may be stalled. Retry the subagent.`,
-      });
-      // The stalled session cannot be trusted to abort cooperatively; dispose
-      // it like the abort-deadline path so it cannot revive into a zombie run.
-      const fiber = runDetached(
-        closeEntryScope(entry).pipe(
-          Effect.timeout(ENTRY_CLOSE_TIMEOUT_MS),
-          Effect.ignore,
-        ),
-      );
-      cleanups.add(fiber);
-      fiber.addObserver(() => cleanups.delete(fiber));
-    };
-
-    /** Arm the first-response watchdog for the entry's current run. */
-    const armWatchdog = (entry: Entry) => {
-      clearWatchdog(entry);
-      entry.watchdogTimer = setTimeout(
-        () => watchdogExpired(entry),
-        firstResponseTimeoutMs,
-      );
-    };
-
     const foldEvent = (entry: Entry, event: SubagentEvent) => {
       const s = entry.snapshot;
       switch (event._tag) {
@@ -446,7 +394,7 @@ const makeManager = (config: SubagentManagerConfig = {}) =>
           s.outcome = undefined;
           s.settledAt = undefined;
           s.errorText = undefined;
-          armWatchdog(entry);
+          s.structuredResult = undefined;
           break;
         case "RunSettled":
           settle(entry, event.outcome);
@@ -458,7 +406,6 @@ const makeManager = (config: SubagentManagerConfig = {}) =>
           });
           break;
         case "AssistantDelta": {
-          clearWatchdog(entry);
           const live = s.liveAssistant ?? { text: "", thinking: "" };
           s.liveAssistant =
             event.kind === "text"
@@ -477,7 +424,6 @@ const makeManager = (config: SubagentManagerConfig = {}) =>
           break;
         }
         case "AssistantMessage":
-          clearWatchdog(entry);
           appendTranscript(s, {
             kind: "assistant",
             parts: event.parts.map((part) =>
@@ -623,9 +569,6 @@ const makeManager = (config: SubagentManagerConfig = {}) =>
             liveToolMap: new Map(),
           };
           entries.set(id, entry);
-          // The run is live from the caller's perspective before RunStarted
-          // reaches the pump; guard that window too.
-          armWatchdog(entry);
 
           // Pump: fold the event stream into the snapshot. Tied to the entry
           // scope, so closing the scope stops it. If the stream ends while the
@@ -776,10 +719,6 @@ const makeManager = (config: SubagentManagerConfig = {}) =>
           // both pass the check in that window. Cleared by RunStarted/settle,
           // or here when the backend rejects the send.
           entry.restarting = true;
-          // A backend that accepts the send but never starts the run would
-          // hold the slot forever; guard the restart window the same way the
-          // spawn path guards its pre-RunStarted window.
-          armWatchdog(entry);
           return entry.session.send(text).pipe(
             Effect.onError(() =>
               Effect.sync(() => {
@@ -795,7 +734,6 @@ const makeManager = (config: SubagentManagerConfig = {}) =>
     const disposeAll = Effect.gen(function* () {
       disposed = true;
       const all = [...entries.values()];
-      for (const entry of all) clearWatchdog(entry);
       entries.clear();
       yield* Effect.forEach(
         all,
@@ -873,8 +811,6 @@ const makeManager = (config: SubagentManagerConfig = {}) =>
   });
 
 export interface SubagentManagerConfig {
-  /** Test-only override for the first-response watchdog timeout. */
-  firstResponseTimeoutMs?: number;
   /** Session-branch high-water marks restored by the extension host. */
   initialModelCounter?: number;
   initialBtwCounter?: number;

package/extensions/subagents/src/prompt.ts

@@ -17,8 +17,8 @@ export const SUBAGENT_SCHEMA_BUDGETS = Object.freeze({
 
 /** Describes subagent_spawn, including the fixed concurrency cap. */
 export const SUBAGENT_SPAWN_TOOL_DESCRIPTION =
-  "Spawn a background in-process Pi subagent with its own context, child-safe tools, and normal host permissions. Returns immediately; its final result is delivered automatically. The child cannot see this conversation, ask the user, or orchestrate agents/workflows. Use only trusted working directories. " +
-  `Max ${MAX_RUNNING} subagents can be running at once.`;
+  "Spawn a background Pi subagent with isolated context and child-safe tools. Returns immediately; its result arrives automatically. It cannot see this chat, ask the user, or orchestrate. Use trusted directories. " +
+  `Max ${MAX_RUNNING} subagents can run at once.`;
 
 /** UTF-8 bounded, whitespace-normalized text for the parent-facing roster. */
 function boundedPurpose(description: string) {
@@ -141,17 +141,18 @@ export const SUBAGENT_SPAWN_PROMPT_GUIDELINES = [
 /** Model-facing schema descriptions for subagent_spawn task and execution options. */
 export const SUBAGENT_SPAWN_PARAMETER_DESCRIPTIONS = {
   prompt:
-    "Task prompt for the subagent. Must be self-contained: include all needed context, file paths, and what to report back.",
+    "Self-contained task: include needed context, file paths, and expected report.",
   name: "Short human-readable name shown in listings and the UI",
   harness: 'Optional; "pi" is the only harness and the default.',
   workingDir:
-    "Trusted child working directory; defaults to the current directory",
+    "Child cwd, absolute or relative to parent. Target project trust is checked separately.",
   isolation:
     'Use "worktree" for concurrent writers and tell the child to commit. See the Subagents Skill for lifecycle details.',
   model:
     'Optional "provider/model-id" or current-provider model override. Omit to use the preset, configured role, or parent default. Never guess a model name.',
   reasoningEffort:
     "Optional child thinking level. Honor the user's requested level. Otherwise choose a level supported by the resolved child model based on the selected role and task difficulty. An explicit value overrides a role default.",
+  outputSchema: "Optional result JSON Schema.",
 };
 
 /** The exact name/description/wire-schema source used by registration/tests. */
@@ -193,6 +194,15 @@ export function createSubagentSpawnToolSurface(
           description: SUBAGENT_SPAWN_PARAMETER_DESCRIPTIONS.reasoningEffort,
         }),
       ),
+      output_schema: Type.Optional(
+        Type.Object(
+          {},
+          {
+            additionalProperties: true,
+            description: SUBAGENT_SPAWN_PARAMETER_DESCRIPTIONS.outputSchema,
+          },
+        ),
+      ),
     }),
   };
 }
@@ -207,6 +217,7 @@ export function buildSubagentSpawnResult(options: {
   agentTypeName?: string;
   tools?: readonly string[];
   worktreeBranch?: string;
+  structured?: boolean;
 }) {
   const typeNote = options.agentTypeName
     ? ` Agent type "${options.agentTypeName}" applied.`
@@ -226,8 +237,11 @@ export function buildSubagentSpawnResult(options: {
   const worktreeNote = options.worktreeBranch
     ? ` Isolated in its own worktree on branch "${options.worktreeBranch}" — its edits are invisible here until you merge that branch. The checkout stays available for later send/review and is reclaimed on Session retirement only when bounded inspection proves it empty.`
     : "";
+  const structuredNote = options.structured
+    ? " This run must finish with the requested validated structured result."
+    : "";
   return (
-    `Spawned subagent ${options.id} "${options.title}" (${options.harness}: ${options.modelLabel}, ${options.cwd}).${typeNote}${toolNote}${worktreeNote}\n` +
+    `Spawned subagent ${options.id} "${options.title}" (${options.harness}: ${options.modelLabel}, ${options.cwd}).${typeNote}${toolNote}${worktreeNote}${structuredNote}\n` +
     `It runs in the background — keep working on independent work. If none remains in an interactive session, briefly tell the user it is still running and end your turn; its result is delivered automatically and you are automatically re-invoked when it finishes. Do not poll or call subagent_wait merely because a later step depends on it. ` +
     `Use subagent_wait(ids: ["${options.id}"]) only if the user explicitly asked you to keep the current response open for this result, or a non-interactive automation must return it in the same invocation; subagent_cancel stops it, subagent_check peeks at a running one, subagent_list shows all.`
   );

package/extensions/subagents/src/result-artifact.ts

@@ -77,6 +77,38 @@ export function persistResultArtifact(agentDir: string, content: string) {
   return artifactPath;
 }
 
+/** Persist one complete validated structured value under a JSON identity. */
+export function persistStructuredResultArtifact(
+  agentDir: string,
+  content: string,
+) {
+  let directory = path.resolve(agentDir);
+  for (const segment of RESULT_ARTIFACT_DIR) {
+    directory = ensureDirectory(directory, segment);
+  }
+
+  const digest = createHash("sha256").update(content).digest("hex");
+  const artifactPath = path.join(directory, `${digest}.json`);
+  try {
+    writeFileSync(artifactPath, content, {
+      encoding: "utf8",
+      flag: "wx",
+      mode: 0o600,
+    });
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+    const stat = lstatSync(artifactPath);
+    if (
+      !stat.isFile() ||
+      stat.isSymbolicLink() ||
+      readFileSync(artifactPath, "utf8") !== content
+    ) {
+      throw new Error(`Structured result artifact collision: ${artifactPath}`);
+    }
+  }
+  return artifactPath;
+}
+
 /**
  * Build the single model-visible projection used by automatic delivery and
  * explicit waits. Short answers pass through byte-for-byte. Long answers keep