@oh-my-pi/pi-coding-agent 17.0.2 → 17.0.3

package/src/eval/agent-bridge.ts

@@ -1,32 +1,15 @@
 /**
  * Host-side handler for the eval `agent()` helper.
  */
-import * as fs from "node:fs/promises";
-import * as os from "node:os";
-import * as path from "node:path";
-import { prompt, Snowflake } from "@oh-my-pi/pi-utils";
 import { type } from "arktype";
-import { resolveAgentModelPatterns } from "../config/model-resolver";
-import type { LocalProtocolOptions } from "../internal-urls";
-import { registerArtifactsDir } from "../internal-urls/registry-helpers";
-import { MCPManager } from "../mcp/manager";
-import subagentUserPromptTemplate from "../prompts/system/subagent-user-prompt.md" with { type: "text" };
-import { MAIN_AGENT_ID } from "../registry/agent-registry";
-import * as taskDiscovery from "../task/discovery";
-import type { ExecutorOptions } from "../task/executor";
-import * as taskExecutor from "../task/executor";
 import {
-	applyEligibleNestedPatches,
-	type IsolationContext,
-	makeIsolationCommitMessage,
-	mergeIsolatedChanges,
-	prepareIsolationContext,
-	runIsolatedSubprocess,
-} from "../task/isolation-runner";
-import { AgentOutputManager } from "../task/output-manager";
-import { resolveSpawnPolicy } from "../task/spawn-policy";
-import { type AgentDefinition, type AgentProgress, canSpawnAtDepth, type SingleResult } from "../task/types";
-import { type NestedRepoPatch, parseIsolationMode } from "../task/worktree";
+	buildStructuredSubagentRecoveryHint,
+	runStructuredSubagent,
+	StructuredSubagentError,
+	type StructuredSubagentSchemaMode,
+} from "../task/structured-subagent";
+import type { AgentProgress, SingleResult } from "../task/types";
+import type { NestedRepoPatch } from "../task/worktree";
 import type { ToolSession } from "../tools";
 import { ToolError } from "../tools/tool-errors";
 import { withBridgeTimeoutPause } from "./bridge-timeout";
@@ -37,21 +20,13 @@ import "../tools/review";
 /** Synthetic bridge name reserved for the `agent()` helper across both runtimes. */
 export const EVAL_AGENT_BRIDGE_NAME = "__agent__";
 
-/**
- * Hard recursion ceiling for eval-driven subagents. The user setting
- * `task.maxRecursionDepth` is honored on top of this — whichever is tighter
- * wins, so a maintainer-friendly cap can't get raised by a user setting.
- */
-export const EVAL_AGENT_MAX_DEPTH = 3;
-
-const DEFAULT_AGENT_LABEL = "EvalAgent";
-
 const agentArgsSchema = type({
 	prompt: "string>0",
 	"agent?": "string>0",
 	"model?": "string>0|string>0[]",
 	"label?": "string",
 	"schema?": "unknown",
+	"schemaMode?": "'permissive' | 'strict'",
 	"isolated?": "boolean",
 	"apply?": "boolean",
 	"merge?": "boolean",
@@ -64,30 +39,10 @@ interface EvalAgentArgs {
 	model?: string | string[];
 	label?: string;
 	schema?: unknown;
-	/**
-	 * Run this subagent inside an isolation worktree (copy-on-write of the
-	 * parent repo). Strict opt-in: defaults to `false` regardless of the
-	 * session's `task.isolation.mode`, mirroring the `task` tool. Passing
-	 * `true` while `task.isolation.mode === "none"` errors out instead of
-	 * silently downgrading.
-	 */
+	schemaMode?: StructuredSubagentSchemaMode;
 	isolated?: boolean;
-	/**
-	 * When isolated, apply the captured patch / merge the captured branch back
-	 * to the parent repo (default `true`). Pass `false` to keep changes in the
-	 * isolation worktree only — the patch artifact path / branch name lands in
-	 * the result so the caller can inspect or apply manually.
-	 */
 	apply?: boolean;
-	/**
-	 * When isolated, allow branch-merge mode (cherry-pick onto HEAD). Defaults
-	 * to `true`, in which case the active `task.isolation.merge` setting picks
-	 * patch vs branch. Pass `false` to force patch mode even when the setting
-	 * is `"branch"` — useful when a fan-out cannot tolerate the per-call git
-	 * lock + repo mutation that branch mode performs.
-	 */
 	merge?: boolean;
-	/** True when a runtime helper will return an `agent://` handle backed by the output artifacts. */
 	handle?: boolean;
 }
 
@@ -99,28 +54,21 @@ export interface EvalAgentBridgeOptions {
 
 export interface EvalAgentResult {
 	text: string;
+	/** Parsed structured data returned by the child executor. */
+	data?: unknown;
 	details: {
 		agent: string;
 		id: string;
 		model?: string | string[];
 		structured: boolean;
-		/** True iff this run executed inside an isolation worktree. */
+		schemaSource?: "caller" | "agent" | "session";
+		schemaMode?: StructuredSubagentSchemaMode;
+		schemaStatus?: "valid" | "invalid";
 		isolated?: boolean;
-		/** Captured patch artifact (patch mode) — surfaced regardless of `apply`. */
 		patchPath?: string;
-		/** Captured branch (branch mode) — surfaced regardless of `apply`. */
 		branchName?: string;
-		/** Captured nested repository patches — surfaced for isolated `apply=false` manual application. */
 		nestedPatches?: NestedRepoPatch[];
-		/**
-		 * Tri-state apply outcome for isolated runs:
-		 * - `true`  — apply ran (or had nothing to do) and left the repo clean.
-		 * - `false` — apply attempted and failed; artifacts preserved.
-		 * - `null`  — caller opted out via `apply=false`.
-		 * Omitted for non-isolated runs.
-		 */
 		changesApplied?: boolean | null;
-		/** Human-readable isolation apply/merge summary; kept out of schema-backed `text`. */
 		isolationSummary?: string;
 	};
 }
@@ -133,136 +81,11 @@ function parseAgentArgs(args: unknown): EvalAgentArgs {
 	return result;
 }
 
-function assertDepthAllowed(session: ToolSession): void {
-	const taskDepth = session.taskDepth ?? 0;
-	// Honor the user's `task.maxRecursionDepth` (mirroring the task tool's gate
-	// in tools/index.ts) but never above the hard ceiling. `< 0` means
-	// "Unlimited" in the same schema `canSpawnAtDepth` reads, so it falls back
-	// to the hard ceiling instead of going past it.
-	const settingMax = session.settings.get("task.maxRecursionDepth") ?? 2;
-	const effectiveMax = settingMax < 0 ? EVAL_AGENT_MAX_DEPTH : Math.min(settingMax, EVAL_AGENT_MAX_DEPTH);
-	if (!canSpawnAtDepth(effectiveMax, taskDepth)) {
-		throw new ToolError(
-			`agent() cannot spawn another agent at task depth ${taskDepth}; maximum depth is ${effectiveMax} (task.maxRecursionDepth=${settingMax}, hard ceiling=${EVAL_AGENT_MAX_DEPTH}).`,
-		);
-	}
-}
-
-function assertSpawnAllowed(session: ToolSession, agentName: string): void {
-	const spawnPolicy = resolveSpawnPolicy(session.getSessionSpawns());
-	if (!spawnPolicy.enabled) {
-		throw new ToolError(`Cannot spawn '${agentName}'. Allowed: ${spawnPolicy.allowedErrorText}`);
-	}
-	if (spawnPolicy.allowedAgents !== null && !spawnPolicy.allowedAgents.includes(agentName)) {
-		throw new ToolError(`Cannot spawn '${agentName}'. Allowed: ${spawnPolicy.allowedErrorText}`);
-	}
-}
-
-function assertAgentEnabled(session: ToolSession, agentName: string, agents: AgentDefinition[]): void {
-	const disabledAgents = session.settings.get("task.disabledAgents") as string[];
-	if (!disabledAgents.includes(agentName)) return;
-	const enabled = agents.filter(agent => !disabledAgents.includes(agent.name)).map(agent => agent.name);
-	throw new ToolError(
-		`Agent "${agentName}" is disabled in settings. Enable it via /agents, or use a different agent type.${enabled.length > 0 ? ` Available: ${enabled.join(", ")}` : ""}`,
-	);
-}
-
-function assertNotPlanMode(session: ToolSession): void {
-	if (session.getPlanModeState?.()?.enabled) {
-		throw new ToolError("agent() is unavailable in plan mode.");
-	}
-}
-
-function renderSubagentPrompt(assignment: string): string {
-	return prompt.render(subagentUserPromptTemplate, { assignment: assignment.trim() });
-}
-
 function trimToUndefined(value: string | undefined): string | undefined {
 	const trimmed = value?.trim();
 	return trimmed ? trimmed : undefined;
 }
 
-function outputIdBase(label: string | undefined, agentName: string): string {
-	const source = trimToUndefined(label) ?? agentName ?? DEFAULT_AGENT_LABEL;
-	const sanitized = source.replace(/[^A-Za-z0-9_-]+/g, "").slice(0, 48);
-	return sanitized || DEFAULT_AGENT_LABEL;
-}
-
-function getOutputManager(session: ToolSession): AgentOutputManager {
-	if (session.agentOutputManager) return session.agentOutputManager;
-	const manager = new AgentOutputManager(session.getArtifactsDir ?? (() => null));
-	session.agentOutputManager = manager;
-	return manager;
-}
-
-interface ArtifactPaths {
-	sessionFile: string | null;
-	artifactsDir: string;
-	unregisterArtifactsDir?: () => void;
-	/**
-	 * True when `artifactsDir` was created off the session path (no session
-	 * file). Caller is then free to `rm -rf` it once all isolated patch
-	 * artifacts have been consumed or applied.
-	 */
-	tempArtifactsDir: boolean;
-}
-
-async function getArtifacts(session: ToolSession): Promise<ArtifactPaths> {
-	const sessionFile = session.getSessionFile();
-	const sessionArtifactsDir = sessionFile ? sessionFile.slice(0, -6) : null;
-	const tempArtifactsDir = sessionArtifactsDir === null;
-	const artifactsDir = sessionArtifactsDir ?? path.join(os.tmpdir(), `omp-eval-agent-${Snowflake.next()}`);
-	await fs.mkdir(artifactsDir, { recursive: true });
-	const unregisterArtifactsDir = tempArtifactsDir ? registerArtifactsDir(artifactsDir) : undefined;
-	return { sessionFile, artifactsDir, unregisterArtifactsDir, tempArtifactsDir };
-}
-
-/**
- * Persist nested-repo patches to the per-call artifacts dir so an isolated
- * apply failure can surface their paths in the thrown ToolError. The
- * isolation worktree is already gone by the time we run, so without this the
- * captured nested patches would be unrecoverable.
- */
-async function persistNestedPatches(
-	artifactsDir: string,
-	agentId: string,
-	nestedPatches: NestedRepoPatch[],
-): Promise<string[]> {
-	const written: string[] = [];
-	for (let index = 0; index < nestedPatches.length; index++) {
-		const patch = nestedPatches[index];
-		if (!patch) continue;
-		const slug = patch.relativePath.replace(/[^A-Za-z0-9._-]+/g, "_") || `nested-${index}`;
-		const out = path.join(artifactsDir, `${agentId}.nested-${index}-${slug}.patch`);
-		await Bun.write(out, patch.patch);
-		written.push(out);
-	}
-	return written;
-}
-
-/**
- * Assemble the "captured X preserved at Y" recovery hint appended to
- * isolated-run failure messages. Persists nested-repo patches to
- * `artifactsDir` when present so their paths can be surfaced. Returns an
- * empty string when the result carries no salvageable artifacts.
- */
-async function buildIsolationRecoveryHint(result: SingleResult, artifactsDir: string): Promise<string> {
-	const parts: string[] = [];
-	if (result.patchPath) parts.push(`Captured patch preserved at ${result.patchPath}.`);
-	if (result.branchName) parts.push(`Captured branch preserved as ${result.branchName}.`);
-	if (result.nestedPatches?.length) {
-		const nestedPaths = await persistNestedPatches(artifactsDir, result.id, result.nestedPatches);
-		parts.push(
-			`Captured nested repository patches (${result.nestedPatches.length}) preserved at: ${nestedPaths.join(", ")}.`,
-		);
-	}
-	return parts.length > 0 ? ` ${parts.join(" ")}` : "";
-}
-
-function plainIsolationSummary(summary: string): string {
-	return summary.replace(/<\/?system-notification>/g, "").trim();
-}
-
 function emitProgressStatus(emitStatus: ((event: JsStatusEvent) => void) | undefined, progress: AgentProgress): void {
 	if (!emitStatus) return;
 	const preview = (progress.assignment ?? progress.task ?? "").split("\n")[0]?.slice(0, 120);
@@ -285,15 +108,6 @@ function emitProgressStatus(emitStatus: ((event: JsStatusEvent) => void) | undef
 	});
 }
 
-/**
- * Coalesce a subagent failure into a non-empty, human-meaningful error message.
- *
- * When the executor aborts a subagent (runtime limit, parent cancellation, …)
- * the actionable explanation lives on `abortReason`, while `error`/`stderr`
- * are routinely empty strings. Plain `??` coalescing stops at the empty string
- * and ships an empty error through the bridge — Python then surfaces only the
- * generic `bridge call '__agent__' failed`. See #2006.
- */
 function buildSubagentFailureMessage(agentName: string, result: SingleResult): string {
 	const abortReason = trimToUndefined(result.abortReason);
 	if (result.aborted && abortReason) return abortReason;
@@ -310,288 +124,101 @@ function buildSubagentFailureMessage(agentName: string, result: SingleResult): s
  */
 export async function runEvalAgent(args: unknown, options: EvalAgentBridgeOptions): Promise<EvalAgentResult> {
 	const parsed = parseAgentArgs(args);
-	const agentName = parsed.agent ?? resolveSpawnPolicy(options.session.getSessionSpawns()).defaultAgent;
-	const structured = Object.hasOwn(parsed, "schema");
-
-	assertNotPlanMode(options.session);
-	assertDepthAllowed(options.session);
-	assertSpawnAllowed(options.session, agentName);
-
 	const turnBudget = options.session.getTurnBudget?.();
 	if (turnBudget?.hard && turnBudget.total !== null && turnBudget.spent >= turnBudget.total) {
 		throw new ToolError(
 			`agent() blocked: turn token budget exhausted (${turnBudget.spent}/${turnBudget.total} output tokens). Raise or drop the +Nk! ceiling to continue.`,
 		);
 	}
-
-	const { agents } = await taskDiscovery.discoverAgents(options.session.cwd);
-	const agent = taskDiscovery.getAgent(agents, agentName);
-	if (!agent) {
-		const available = agents.map(candidate => candidate.name).join(", ") || "none";
-		throw new ToolError(`Unknown agent "${agentName}". Available: ${available}`);
-	}
-	assertAgentEnabled(options.session, agentName, agents);
-
-	const effectiveAgent = agent;
-	const parentActiveModelPattern = options.session.getActiveModelString?.();
-	const agentModelOverrides = options.session.settings.get("task.agentModelOverrides");
-	const modelOverride = resolveAgentModelPatterns({
-		settingsOverride: parsed.model ?? agentModelOverrides[agentName],
-		agentModel: effectiveAgent.model,
-		settings: options.session.settings,
-		activeModelPattern: parentActiveModelPattern,
-		fallbackModelPattern: options.session.getModelString?.(),
-	});
-	const availableSkills = [...(options.session.skills ?? [])];
-	const resolvedAutoloadSkills =
-		effectiveAgent.autoloadSkills?.length && availableSkills.length > 0
-			? effectiveAgent.autoloadSkills
-					.map(name => availableSkills.find(skill => skill.name === name))
-					.filter((skill): skill is NonNullable<typeof skill> => skill !== undefined)
-			: [];
-	const contextFiles = options.session.contextFiles?.filter(
-		file => path.basename(file.path).toLowerCase() !== "agents.md",
-	);
-	const localProtocolOptions: LocalProtocolOptions = options.session.localProtocolOptions ?? {
-		getArtifactsDir: options.session.getArtifactsDir ?? (() => null),
-		getSessionId: options.session.getSessionId ?? (() => null),
-	};
-	const parentArtifactManager = options.session.getArtifactManager?.() ?? undefined;
-	const mcpManager = options.session.mcpManager ?? MCPManager.instance();
-	const { sessionFile, artifactsDir, unregisterArtifactsDir, tempArtifactsDir } = await getArtifacts(options.session);
-	const outputManager = getOutputManager(options.session);
-	const id = await outputManager.allocate(outputIdBase(parsed.label, agentName));
-	const assignment = parsed.prompt.trim();
-
-	// Isolation gating. Strict opt-in: only the explicit `isolated=true`
-	// argument turns it on; `task.isolation.mode` no longer drives the
-	// default. Mirrors the `task` tool so eval `agent()` and `task` callers
-	// see the same semantic. `isolated=true` while the mode is `"none"`
-	// surfaces a clear error instead of silently downgrading.
-	const isolationMode = options.session.settings.get("task.isolation.mode");
-	const isolationEnabledInSettings = isolationMode !== "none";
-	if (parsed.isolated === true && !isolationEnabledInSettings) {
-		throw new ToolError(`agent(isolated=True) requires task.isolation.mode to be set; current mode is "none".`);
-	}
-	const isIsolated = parsed.isolated === true;
-	const settingsMergeMode = options.session.settings.get("task.isolation.merge");
-	const mergeMode: "patch" | "branch" = parsed.merge === false ? "patch" : settingsMergeMode;
-	const applyChanges = parsed.apply !== false;
-
-	// Isolation context capture (prepareIsolationContext → captureBaseline)
-	// happens inside the timeout-pause closure below; on dirty/large repos the
-	// baseline walk can run long and must stay covered by the eval idle
-	// suspension.
-
-	const buildCommitMessage = makeIsolationCommitMessage(options.session);
-
-	const baseRunOptions: ExecutorOptions = {
-		cwd: options.session.cwd,
-		agent: effectiveAgent,
-		task: renderSubagentPrompt(assignment),
-		assignment,
-		description: trimToUndefined(parsed.label),
-		index: 0,
-		id,
-		taskDepth: options.session.taskDepth ?? 0,
-		modelOverride,
-		parentActiveModelPattern,
-		thinkingLevel: effectiveAgent.thinkingLevel,
-		...(structured ? { outputSchema: parsed.schema, outputSchemaOverridesAgent: true } : {}),
-		sessionFile,
-		persistArtifacts: Boolean(sessionFile),
-		artifactsDir,
-		// Eval `agent()` subagents are short-lived programmatic helpers (data
-		// collection, structured output, parallel() fan-out). LSP server
-		// cold-start costs tens of seconds and is pure overhead here, so it is
-		// forced off regardless of the `task.enableLsp` setting — that knob only
-		// governs LSP-aware delegation through the `task` tool.
-		enableLsp: false,
-		signal: options.signal,
-		eventBus: options.session.eventBus,
-		onProgress: progress => emitProgressStatus(options.emitStatus, progress),
-		authStorage: options.session.authStorage,
-		modelRegistry: options.session.modelRegistry,
-		settings: options.session.settings,
-		// Eval `agent()` subagents are never wall-clock capped: the parent
-		// cell's idle watchdog is suspended for the whole bridge call
-		// (withBridgeTimeoutPause), so a long-running phase/recovery workflow
-		// must not be killed by `task.maxRuntimeMs`. Force the limit off
-		// regardless of the inherited session setting.
-		maxRuntimeMs: 0,
-		keepAlive: false,
-		mcpManager,
-		contextFiles,
-		skills: availableSkills,
-		autoloadSkills: resolvedAutoloadSkills,
-		workspaceTree: options.session.workspaceTree,
-		promptTemplates: options.session.promptTemplates,
-		localProtocolOptions,
-		parentArtifactManager,
-		parentHindsightSessionState: options.session.getHindsightSessionState?.(),
-		parentMnemopiSessionState: options.session.getMnemopiSessionState?.(),
-		parentTelemetry: options.session.getTelemetry?.(),
-		parentAgentId: options.session.getAgentId?.() ?? MAIN_AGENT_ID,
-		// Live source of truth for `tier.subagent: inherit` (null = explicit none).
-		parentServiceTier: options.session.getServiceTierByFamily
-			? (options.session.getServiceTierByFamily() ?? null)
-			: undefined,
-		// Deliberately omit parentEvalSessionId: the parent's Python kernel is
-		// blocked on this bridge call, so sharing the eval session would deadlock
-		// (subagent queues behind the parent's in-flight execution, parent waits
-		// for subagent → circular). Each bridge-spawned subagent gets its own
-		// eval session with an independent kernel.
-	};
-
-	// Suspend eval timeout accounting through the WHOLE bridge call: the
-	// subagent subprocess plus any isolation post-processing (merge,
-	// nested-patch apply, cleanup). All of that is host-side work while the
-	// runtime is parked waiting for the result, and the cell timeout must
-	// not abort us mid-cherry-pick or mid-nested-commit. The clock restarts
-	// only after we hand control back to the runtime.
-	const { result, mergeSummary, changesApplied } = await withBridgeTimeoutPause(
-		options.emitStatus,
-		async () => {
-			let isolationContext: IsolationContext | null = null;
-			if (isIsolated) {
-				try {
-					isolationContext = await prepareIsolationContext(options.session.cwd);
-				} catch (err) {
-					const message = err instanceof Error ? err.message : String(err);
-					throw new ToolError(`Isolated agent() execution requires a git repository. ${message}`);
-				}
-			}
-			const preferredBackend = isIsolated ? parseIsolationMode(isolationMode) : undefined;
-
-			const result = await (async () => {
-				if (!isolationContext) {
-					return taskExecutor.runSubprocess(baseRunOptions);
-				}
-				const taskStart = Date.now();
-				return runIsolatedSubprocess({
-					baseOptions: baseRunOptions,
-					context: isolationContext,
-					preferredBackend,
-					agentId: id,
-					mergeMode,
-					artifactsDir,
-					description: trimToUndefined(parsed.label),
-					buildCommitMessage,
-					buildFailureResult: err => {
-						const message = err instanceof Error ? err.message : String(err);
-						return {
-							index: 0,
-							id,
-							agent: effectiveAgent.name,
-							agentSource: effectiveAgent.source,
-							task: renderSubagentPrompt(assignment),
-							assignment,
-							description: trimToUndefined(parsed.label),
-							exitCode: 1,
-							output: "",
-							stderr: message,
-							truncated: false,
-							durationMs: Date.now() - taskStart,
-							tokens: 0,
-							requests: 0,
-							modelOverride,
-							error: message,
-						};
-					},
-				});
-			})();
-
-			if (result.exitCode !== 0 || result.error || result.aborted) {
-				const failureMessage = buildSubagentFailureMessage(agentName, result);
-				const recoveryHint = isIsolated ? await buildIsolationRecoveryHint(result, artifactsDir) : "";
-				throw new ToolError(`${failureMessage}${recoveryHint}`);
-			}
-
-			let mergeSummary = "";
-			let changesApplied: boolean | null = null;
-			if (isIsolated && isolationContext) {
-				if (applyChanges) {
-					const outcome = await mergeIsolatedChanges({
-						result,
-						repoRoot: isolationContext.repoRoot,
-						mergeMode,
-					});
-					mergeSummary = outcome.summary;
-					changesApplied = outcome.changesApplied;
-					if (outcome.changesApplied === false) {
-						const summaryText = outcome.summary.trim();
-						const recoveryHint = await buildIsolationRecoveryHint(result, artifactsDir);
-						throw new ToolError(
-							`agent() isolated apply failed for ${result.id}${summaryText ? `: ${summaryText}` : ""}${recoveryHint}`,
-						);
-					}
-
-					const nestedSummary = await applyEligibleNestedPatches({
-						result,
-						repoRoot: isolationContext.repoRoot,
-						mergeMode,
-						changesApplied: outcome.changesApplied,
-						mergedBranchForNestedPatches: outcome.mergedBranchForNestedPatches,
-						commitMessage: buildCommitMessage(),
-					});
-					mergeSummary += nestedSummary;
-					if (structured && nestedSummary.trim()) {
-						const recoveryHint = await buildIsolationRecoveryHint(
-							{ ...result, patchPath: undefined, branchName: undefined },
-							artifactsDir,
-						);
-						throw new ToolError(
-							`agent() isolated nested patch apply failed for ${result.id}: ${plainIsolationSummary(nestedSummary)}${recoveryHint}`,
-						);
-					}
-				} else if (result.branchName) {
-					mergeSummary = `\n\nIsolation: changes captured on branch \`${result.branchName}\` (apply=false). Not merged.`;
-				} else if (result.patchPath) {
-					mergeSummary = `\n\nIsolation: changes captured at \`${result.patchPath}\` (apply=false). Not applied.`;
-				} else {
-					const nestedPatches = result.nestedPatches ?? [];
-					if (nestedPatches.length > 0) {
-						mergeSummary = `\n\nIsolation: changes captured for ${nestedPatches.length} nested repositor${nestedPatches.length === 1 ? "y" : "ies"} (apply=false). Not applied.`;
-					} else {
-						mergeSummary = "\n\nIsolation: no changes captured.";
-					}
+	const isolation =
+		Object.hasOwn(parsed, "isolated") || Object.hasOwn(parsed, "apply") || Object.hasOwn(parsed, "merge")
+			? {
+					...(parsed.isolated !== undefined ? { requested: parsed.isolated } : {}),
+					...(parsed.merge === false ? { merge: "patch" as const } : {}),
+					...(parsed.apply !== undefined ? { apply: parsed.apply } : {}),
 				}
-			}
-
-			// Clean up the temp artifacts dir we created for this call only when the
-			// caller will not need files from it later. Keep it when the runtime helper
-			// will return an `agent://` handle (the `.md`/`.jsonl` backing files live
-			// here) and on `apply=false` (`changesApplied === null`) where the caller
-			// consumes `details.patchPath` / `details.branchName` /
-			// `details.nestedPatches` out of band. Failed isolated applies throw
-			// earlier with a recovery hint, so they never reach this gate.
-			const shouldCleanupTempArtifacts =
-				tempArtifactsDir && !parsed.handle && (!isIsolated || changesApplied === true);
-			if (shouldCleanupTempArtifacts) {
-				await fs.rm(artifactsDir, { recursive: true, force: true });
-				unregisterArtifactsDir?.();
-			}
-
-			options.session.recordEvalSubagentUsage?.(result.usage?.output ?? 0);
-
-			return { result, mergeSummary, changesApplied };
-		},
-		{ deferExternalAbort: true },
-	);
-
-	return {
-		text: structured ? result.output : result.output + mergeSummary,
-		details: {
-			agent: result.agent,
-			id: result.id,
-			model: result.resolvedModel ?? modelOverride,
-			structured,
-			isolated: isIsolated || undefined,
-			patchPath: result.patchPath,
-			branchName: result.branchName,
-			nestedPatches: result.nestedPatches?.length ? result.nestedPatches : undefined,
-			changesApplied: isIsolated ? changesApplied : undefined,
-			isolationSummary: mergeSummary ? mergeSummary.trim() : undefined,
-		},
-	};
+			: undefined;
+
+	try {
+		const execution = await withBridgeTimeoutPause(
+			options.emitStatus,
+			() =>
+				runStructuredSubagent({
+					session: options.session,
+					invocationKind: "eval",
+					assignment: parsed.prompt,
+					...(parsed.agent !== undefined ? { agent: parsed.agent } : {}),
+					...(parsed.model !== undefined ? { model: parsed.model } : {}),
+					...(Object.hasOwn(parsed, "schema") ? { outputSchema: parsed.schema } : {}),
+					...(parsed.schemaMode !== undefined ? { schemaMode: parsed.schemaMode } : {}),
+					...(parsed.label !== undefined ? { identity: { label: parsed.label } } : {}),
+					...(isolation ? { isolation } : {}),
+					...(parsed.handle ? { retainArtifacts: true } : {}),
+					keepAlive: false,
+					maxRuntimeMs: 0,
+					shareEvalSession: false,
+					...(options.signal !== undefined ? { signal: options.signal } : {}),
+					...(options.emitStatus
+						? { onProgress: (progress: AgentProgress) => emitProgressStatus(options.emitStatus, progress) }
+						: {}),
+				}),
+			{ deferExternalAbort: true },
+		);
+		const { result, policy, mergeSummary, changesApplied, artifactsDir } = execution;
+		if (result.exitCode !== 0 || result.error || result.aborted) {
+			const failureMessage = buildSubagentFailureMessage(policy.agentName, result)
+				.replace(/<\/?system-notification>/g, "")
+				.trim();
+			const recoveryHint = policy.isIsolated ? await buildStructuredSubagentRecoveryHint(result, artifactsDir) : "";
+			throw new ToolError(`${failureMessage}${recoveryHint}`);
+		}
+		if (policy.isIsolated && changesApplied === false) {
+			const summary = mergeSummary.replace(/<\/?system-notification>/g, "").trim();
+			const recoveryHint = await buildStructuredSubagentRecoveryHint(result, artifactsDir);
+			throw new ToolError(
+				`agent() isolated apply failed for ${result.id}${summary ? `: ${summary}` : ""}${recoveryHint}`,
+			);
+		}
+
+		const structuredOutput = result.structuredOutput;
+		const structured = structuredOutput?.source !== undefined && structuredOutput.source !== "none";
+		if (structured && mergeSummary.includes("<system-notification>")) {
+			const recoveryHint = await buildStructuredSubagentRecoveryHint(result, artifactsDir);
+			throw new ToolError(
+				`agent() isolated nested patch apply failed for ${result.id}: ${mergeSummary.replace(/<\/?system-notification>/g, "").trim()}${recoveryHint}`,
+			);
+		}
+
+		const hasData = structured && structuredOutput !== undefined && Object.hasOwn(structuredOutput, "data");
+		const data = structuredOutput?.data;
+		const text = structured ? result.output : result.output + mergeSummary;
+		const schemaSource = structuredOutput?.source === "none" ? undefined : structuredOutput?.source;
+		const schemaMode = structured ? structuredOutput?.mode : undefined;
+		const schemaStatus = structuredOutput?.status === "unavailable" ? undefined : structuredOutput?.status;
+
+		const model = result.resolvedModel ?? policy.modelOverride;
+		const nestedPatches = result.nestedPatches?.length ? result.nestedPatches : undefined;
+		const isolationSummary = mergeSummary ? mergeSummary.trim() : undefined;
+		return {
+			text,
+			...(hasData ? { data } : {}),
+			details: {
+				agent: result.agent,
+				id: result.id,
+				...(model !== undefined ? { model } : {}),
+				structured,
+				...(schemaSource !== undefined ? { schemaSource } : {}),
+				...(schemaMode !== undefined ? { schemaMode } : {}),
+				...(schemaStatus !== undefined ? { schemaStatus } : {}),
+				...(policy.isIsolated ? { isolated: true, changesApplied } : {}),
+				...(result.patchPath !== undefined ? { patchPath: result.patchPath } : {}),
+				...(result.branchName !== undefined ? { branchName: result.branchName } : {}),
+				...(nestedPatches !== undefined ? { nestedPatches } : {}),
+				...(isolationSummary !== undefined ? { isolationSummary } : {}),
+			},
+		};
+	} catch (error) {
+		if (error instanceof StructuredSubagentError) throw new ToolError(error.message);
+		throw error;
+	}
 }