pi-subagents 0.43.0 → 0.45.0

package/src/runs/background/run-id-resolver.ts

@@ -1,6 +1,7 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { DIRS, type SubagentState } from "../../shared/types.ts";
+import { readStatus } from "../../shared/utils.ts";
 import { findAsyncRunPrefixMatches, type AsyncRunLocation } from "./async-resume.ts";
 import { assertSafeNestedId, findNestedRunMatchesById, type NestedRoute, type NestedRunMatch, type NestedRunResolutionScope } from "../shared/nested-events.ts";
 
@@ -27,6 +28,70 @@ function exactAsyncLocation(id: string, asyncDirRoot: string, resultsDir: string
 	};
 }
 
+type AsyncRunMatch = { id: string; location: AsyncRunLocation };
+
+type WorkflowResultIdentity = {
+	id?: string;
+	runId?: string;
+	toolCallId?: string;
+};
+
+function readWorkflowResultIdentity(resultPath: string): WorkflowResultIdentity | undefined {
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(fs.readFileSync(resultPath, "utf-8")) as unknown;
+	} catch {
+		return undefined;
+	}
+	if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return undefined;
+	const record = parsed as Record<string, unknown>;
+	return {
+		...(typeof record.id === "string" ? { id: record.id } : {}),
+		...(typeof record.runId === "string" ? { runId: record.runId } : {}),
+		...(typeof record.toolCallId === "string" ? { toolCallId: record.toolCallId } : {}),
+	};
+}
+
+function directoryEntries(root: string): string[] {
+	try {
+		return fs.readdirSync(root);
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") return [];
+		throw error;
+	}
+}
+
+function resultPathFor(resultsDir: string, runId: string): string | null {
+	const resultPath = path.join(resultsDir, `${runId}.json`);
+	return fs.existsSync(resultPath) ? resultPath : null;
+}
+
+function toolCallIdMatches(value: string | undefined, query: string, options: { prefix?: boolean }): boolean {
+	if (value === undefined) return false;
+	return options.prefix === true ? value.startsWith(query) : value === query;
+}
+
+function toolCallIdAsyncLocations(toolCallId: string, asyncDirRoot: string, resultsDir: string, options: { prefix?: boolean } = {}): AsyncRunMatch[] {
+	const byId = new Map<string, AsyncRunLocation>();
+	for (const entry of directoryEntries(asyncDirRoot)) {
+		const asyncDir = path.join(asyncDirRoot, entry);
+		const status = readStatus(asyncDir);
+		if (!status || !toolCallIdMatches(status.toolCallId, toolCallId, options)) continue;
+		const runId = status.runId || entry;
+		byId.set(runId, { asyncDir, resultPath: resultPathFor(resultsDir, runId), resolvedId: runId });
+	}
+	for (const entry of directoryEntries(resultsDir)) {
+		if (!entry.endsWith(".json")) continue;
+		const resultPath = path.join(resultsDir, entry);
+		const identity = readWorkflowResultIdentity(resultPath);
+		if (!identity || !toolCallIdMatches(identity.toolCallId, toolCallId, options)) continue;
+		const runId = identity.runId ?? identity.id ?? entry.slice(0, -".json".length);
+		const asyncDir = path.join(asyncDirRoot, runId);
+		byId.set(runId, { asyncDir: fs.existsSync(asyncDir) ? asyncDir : null, resultPath, resolvedId: runId });
+	}
+	return [...byId.entries()].map(([id, location]) => ({ id, location }));
+}
+
 function foregroundIds(state: SubagentState | undefined): string[] {
 	if (!state) return [];
 	const remembered = state.currentSessionId
@@ -73,6 +138,9 @@ export function resolveSubagentRunId(id: string, deps: ResolveSubagentRunIdDeps
 	if (hasExactForegroundId(deps.state, id)) return { kind: "foreground", id };
 	const exactAsync = exactAsyncLocation(id, asyncDirRoot, resultsDir);
 	if (exactAsync) return { kind: "async", id, location: exactAsync };
+	const exactToolCallIdMatches = toolCallIdAsyncLocations(id, asyncDirRoot, resultsDir);
+	if (exactToolCallIdMatches.length > 1) throw new Error(`Subagent tool-call id '${id}' is ambiguous across async runs. Use the returned asyncId instead.`);
+	if (exactToolCallIdMatches[0]) return { kind: "async", id: exactToolCallIdMatches[0].id, location: exactToolCallIdMatches[0].location };
 	const exactNested = findNestedRunMatchesById(id, nestedScope ? { scope: nestedScope } : {});
 	if (exactNested.length > 1) throw new Error(`Nested run id '${id}' is ambiguous across authorized registries. Provide the full id after stale registries are cleaned up.`);
 	if (exactNested[0]) return { kind: "nested", id, match: exactNested[0] };
@@ -84,6 +152,9 @@ export function resolveSubagentRunId(id: string, deps: ResolveSubagentRunIdDeps
 	for (const match of asyncPrefixMatches(id, asyncDirRoot, resultsDir)) {
 		matches.push({ kind: "async", id: match.id, location: match.location });
 	}
+	for (const match of toolCallIdAsyncLocations(id, asyncDirRoot, resultsDir, { prefix: true })) {
+		matches.push({ kind: "async", id: match.id, location: match.location });
+	}
 	for (const match of findNestedRunMatchesById(id, nestedScope ? { prefix: true, scope: nestedScope } : { prefix: true })) {
 		matches.push({ kind: "nested", id: match.run.id, match });
 	}

package/src/runs/background/run-status.ts

@@ -382,6 +382,7 @@ export function inspectSubagentStatus(params: RunStatusParams, deps: RunStatusDe
 			const workflowEmitPreview = status.workflow?.emits.length ? formatWorkflowJsonPreview(status.workflow.emits.at(-1), 240) : undefined;
 			const lines = [
 				`Run: ${status.runId}`,
+				status.toolCallId ? `Tool call: ${status.toolCallId}` : undefined,
 				missionId ? `Mission: ${missionId}` : undefined,
 				`State: ${status.state}`,
 				processTerminal ? `Process terminal: ${processTerminal.state}${processTerminal.reason ? ` (${processTerminal.reason})` : ""}` : undefined,
@@ -454,7 +455,7 @@ export function inspectSubagentStatus(params: RunStatusParams, deps: RunStatusDe
 	if (resultPath) {
 		try {
 			const raw = fs.readFileSync(resultPath, "utf-8");
-			const data = JSON.parse(raw) as { id?: string; runId?: string; agent?: string; success?: boolean; summary?: string; output?: string; exitCode?: number; state?: string; stopped?: boolean; timedOut?: boolean; turnBudgetExceeded?: boolean; processSignal?: string | null; sessionFile?: string; parallelHandoff?: { path?: string }; results?: Array<{ agent?: string; output?: string; summary?: string; sessionFile?: string; state?: string; success?: boolean; exitCode?: number | null; stopped?: boolean; timedOut?: boolean; turnBudgetExceeded?: boolean; interrupted?: boolean; processSignal?: string | null }> };
+			const data = JSON.parse(raw) as { id?: string; runId?: string; toolCallId?: string; agent?: string; success?: boolean; summary?: string; output?: string; exitCode?: number; state?: string; stopped?: boolean; timedOut?: boolean; turnBudgetExceeded?: boolean; processSignal?: string | null; sessionFile?: string; parallelHandoff?: { path?: string }; results?: Array<{ agent?: string; output?: string; summary?: string; sessionFile?: string; state?: string; success?: boolean; exitCode?: number | null; stopped?: boolean; timedOut?: boolean; turnBudgetExceeded?: boolean; interrupted?: boolean; processSignal?: string | null }> };
 			if (params.view === "transcript") {
 				try {
 					return { content: [{ type: "text", text: formatAsyncResultTranscript(data, resultPath, { index: params.index, lines: params.lines }) }], details: { mode: "single", results: [] } };
@@ -479,7 +480,7 @@ export function inspectSubagentStatus(params: RunStatusParams, deps: RunStatusDe
 				? "stopped"
 				: data.success ? "complete" : data.state === "paused" || data.exitCode === 0 ? "paused" : "failed";
 			const runId = data.runId ?? data.id ?? resolvedId;
-			const lines = [`Run: ${runId}`, `State: ${status}`, `Result: ${resultPath}`];
+			const lines = [`Run: ${runId}`, data.toolCallId ? `Tool call: ${data.toolCallId}` : undefined, `State: ${status}`, `Result: ${resultPath}`].filter((line): line is string => Boolean(line));
 			if (data.parallelHandoff?.path) lines.push(`Parallel handoff: ${data.parallelHandoff.path}`);
 			const children = Array.isArray(data.results) ? data.results : data.agent ? [{ agent: data.agent, sessionFile: data.sessionFile }] : [];
 			lines.push(formatResumeGuidance(runId, children, data.sessionFile, { stopped: status === "stopped" }));

package/src/runs/background/subagent-runner.ts

@@ -69,7 +69,7 @@ import {
 import { applyThinkingSuffix, buildPiArgs, cleanupTempDir, projectLaunchResolvedChildExtensions, resolvePiLaunchToolPlan } from "../shared/pi-args.ts";
 import { readRuntimeAcknowledgedExtensions } from "../shared/runtime-acknowledged-extensions.ts";
 import { outputEntryFromAsyncResult, resolveOutputReferences } from "../shared/chain-outputs.ts";
-import { createStructuredOutputRuntime, readStructuredOutput } from "../shared/structured-output.ts";
+import { createStructuredOutputRuntime, MISSING_STRUCTURED_OUTPUT_CALL_ERROR, readStructuredOutput } from "../shared/structured-output.ts";
 import { formatProcessSignalError, isUnexplainedProcessSignal } from "../shared/process-signal.ts";
 import { readChildToolDiagnosticError } from "../shared/tool-availability.ts";
 import { collectDynamicResults, DynamicFanoutError, materializeDynamicParallelStep, validateDynamicCollection } from "../shared/dynamic-fanout.ts";
@@ -503,6 +503,8 @@ interface RunPiStreamingResult {
 	toolBudget?: ToolBudgetState;
 	toolBudgetBlocked?: boolean;
 	observedMutationAttempt?: boolean;
+	structuredOutputToolInvoked?: boolean;
+	structuredOutputMessageStartIndex?: number;
 	watchdog?: ChildWatchdogStateSnapshot;
 	runtimeAcknowledgedExtensions?: RuntimeAcknowledgedChildExtensionsV1;
 	processInstanceId: string;
@@ -568,6 +570,8 @@ function runPiStreaming(
 		let turnBudgetMessage: string | undefined;
 		let turnBudget: TurnBudgetState | undefined;
 		let observedMutationAttempt = false;
+		let structuredOutputToolInvoked = false;
+		let structuredOutputMessageStartIndex: number | undefined;
 		let toolCount = 0;
 		const childWatchdogConfig = decodeChildWatchdogConfig(env?.[CHILD_WATCHDOG_CONFIG_ENV]);
 		let childWatchdogState: ChildWatchdogStateSnapshot | undefined;
@@ -658,6 +662,10 @@ function runPiStreaming(
 
 			if (event.type === "tool_execution_start" && event.toolName) {
 				toolCount += 1;
+				if (event.toolName === "structured_output") {
+					structuredOutputToolInvoked = true;
+					structuredOutputMessageStartIndex = messages.length;
+				}
 				observedMutationAttempt = observedMutationAttempt || isMutatingTool(event.toolName, event.args);
 				const toolArgs = extractToolArgsPreview(event.args ?? {});
 				writeOutputLine(toolArgs ? `${event.toolName}: ${toolArgs}` : event.toolName);
@@ -923,6 +931,8 @@ function runPiStreaming(
 				turnBudgetExceeded,
 				wrapUpRequested: turnBudget?.outcome === "wrap-up-requested" || turnBudget?.outcome === "termination-deferred" || turnBudgetExceeded || undefined,
 				observedMutationAttempt,
+				structuredOutputToolInvoked,
+				structuredOutputMessageStartIndex,
 				watchdog: childWatchdogState,
 				processInstanceId,
 				processCloseObservedAt,
@@ -949,7 +959,7 @@ function runPiStreaming(
 			const stderr = stderrTail.text();
 			const finalOutput = getFinalOutput(messages) || rawStdoutTail.text().trim();
 			const spawnErrorMessage = spawnError instanceof Error ? spawnError.message : String(spawnError);
-			resolve(omitUndefinedProperties({ stderr, exitCode: 1, messages, usage, toolCount, durationMs: Date.now() - startedAt, model, error: stopped ? (stopMessage ?? "Subagent stopped by user.") : timedOut ? (timeoutMessage ?? "Subagent timed out.") : turnBudgetExceeded ? turnBudgetMessage : error ?? assistantError ?? spawnErrorMessage, protocolError, finalOutput: (timedOut || stopped) && !finalOutput.trim() ? (stopped ? stopMessage ?? "Subagent stopped by user." : timeoutMessage ?? "Subagent timed out.") : finalOutput, outputState: finalOutput.trim() ? "present" : "absent", timedOut, stopped, turnBudget, turnBudgetExceeded, wrapUpRequested: turnBudget?.outcome === "wrap-up-requested" || turnBudget?.outcome === "termination-deferred" || turnBudgetExceeded || undefined, observedMutationAttempt, watchdog: childWatchdogState, processInstanceId }));
+			resolve(omitUndefinedProperties({ stderr, exitCode: 1, messages, usage, toolCount, durationMs: Date.now() - startedAt, model, error: stopped ? (stopMessage ?? "Subagent stopped by user.") : timedOut ? (timeoutMessage ?? "Subagent timed out.") : turnBudgetExceeded ? turnBudgetMessage : error ?? assistantError ?? spawnErrorMessage, protocolError, finalOutput: (timedOut || stopped) && !finalOutput.trim() ? (stopped ? stopMessage ?? "Subagent stopped by user." : timeoutMessage ?? "Subagent timed out.") : finalOutput, outputState: finalOutput.trim() ? "present" : "absent", timedOut, stopped, turnBudget, turnBudgetExceeded, wrapUpRequested: turnBudget?.outcome === "wrap-up-requested" || turnBudget?.outcome === "termination-deferred" || turnBudgetExceeded || undefined, observedMutationAttempt, structuredOutputToolInvoked, structuredOutputMessageStartIndex, watchdog: childWatchdogState, processInstanceId }));
 		});
 	});
 }
@@ -1444,31 +1454,42 @@ async function runSingleStep(
 		const runtimeAcknowledgedExtensions = readRuntimeAcknowledgedExtensions(runtimeAcknowledgedExtensionsPath);
 		cleanupTempDir(tempDir);
 
-		const hiddenError = run.exitCode === 0 && !run.error && !toolAvailabilityError ? detectSubagentError(run.messages) : null;
-		const missingStructuredOutput = effectiveStructuredOutput
-			? !fs.existsSync(effectiveStructuredOutput.outputPath)
-			: false;
+		let structuredOutput: unknown;
+		let structuredError: string | undefined;
+		let validatedStructuredOutput = false;
+		if (effectiveStructuredOutput && run.exitCode === 0 && !run.error && !toolAvailabilityError) {
+			if (!run.structuredOutputToolInvoked) {
+				structuredError = MISSING_STRUCTURED_OUTPUT_CALL_ERROR;
+			} else {
+				const structured = await readStructuredOutput({
+					schema: effectiveStructuredOutput.schema,
+					schemaPath: effectiveStructuredOutput.schemaPath,
+					outputPath: effectiveStructuredOutput.outputPath,
+				});
+				if (structured.error) structuredError = structured.error;
+				else {
+					structuredOutput = structured.value;
+					validatedStructuredOutput = true;
+				}
+			}
+		}
+		const errorMessages = validatedStructuredOutput
+			? run.messages.slice(run.structuredOutputMessageStartIndex ?? run.messages.length)
+			: run.messages;
+		const hiddenError = run.exitCode === 0 && !run.error && !toolAvailabilityError && !structuredError
+			? detectSubagentError(errorMessages)
+			: null;
 		const emptyOutputError = run.exitCode === 0
 			&& !run.error
 			&& !toolAvailabilityError
+			&& !structuredError
 			&& !run.finalOutput.trim()
-			&& (!effectiveStructuredOutput || missingStructuredOutput)
+			&& !validatedStructuredOutput
 			&& (!hiddenError?.hasError || hasEmptyTerminalAssistantResponse(run.messages))
 			? "Subagent produced no output (possible model cold-start or empty response)."
 			: undefined;
-		let structuredOutput: unknown;
-		let structuredError: string | undefined;
-		if (effectiveStructuredOutput && run.exitCode === 0 && !run.error && !toolAvailabilityError && !hiddenError?.hasError && !emptyOutputError) {
-			const structured = await readStructuredOutput({
-				schema: effectiveStructuredOutput.schema,
-				schemaPath: effectiveStructuredOutput.schemaPath,
-				outputPath: effectiveStructuredOutput.outputPath,
-			});
-			if (structured.error) structuredError = structured.error;
-			else structuredOutput = structured.value;
-		}
 		const completionGuardEnabled = isAgentContractV1(step.agentContract) ? step.completionGuard === true : step.completionGuard !== false;
-		const completionGuard = run.exitCode === 0 && !run.error && !toolAvailabilityError && !hiddenError?.hasError && !emptyOutputError && completionGuardEnabled
+		const completionGuard = run.exitCode === 0 && !run.error && !toolAvailabilityError && !structuredError && !hiddenError?.hasError && !emptyOutputError && completionGuardEnabled
 			? evaluateCompletionMutationGuard(omitUndefinedProperties({
 				agent: step.agent,
 				task: taskForCompletionGuard,
@@ -4418,40 +4439,6 @@ async function runSubagent(
 			statusPayload.error = `Step failed: ${failedStep.agent}`;
 		}
 	}
-	writeStatusPayload();
-	appendJsonl(
-		eventsPath,
-		JSON.stringify({
-			type: "subagent.run.completed",
-			lifecycleArtifactVersion: SUBAGENT_LIFECYCLE_ARTIFACT_VERSION,
-			ts: runEndedAt,
-			runId: id,
-			status: statusPayload.state,
-			durationMs: runEndedAt - overallStartTime,
-			totalTokens: statusPayload.totalTokens,
-			totalCost: finalTotalCost,
-			usageBudget: statusPayload.usageBudget,
-		}),
-	);
-	writeRunLog(logPath, omitUndefinedProperties({
-		id,
-		mode: statusPayload.mode,
-		cwd,
-		startedAt: overallStartTime,
-		endedAt: runEndedAt,
-		steps: statusPayload.steps.map((step) => omitUndefinedProperties({
-			agent: step.agent,
-			status: step.status,
-			durationMs: step.durationMs,
-		})),
-		summary,
-		truncated,
-		artifactsDir,
-		sessionFile: effectiveSessionFile,
-		shareUrl,
-		shareError,
-	}));
-
 	try {
 		writeAtomicJson(resultPath, {
 			lifecycleArtifactVersion: SUBAGENT_LIFECYCLE_ARTIFACT_VERSION,
@@ -4551,6 +4538,38 @@ async function runSubagent(
 	} catch (err) {
 		console.error(`Failed to write result file ${resultPath}:`, err);
 	}
+	appendJsonl(
+		eventsPath,
+		JSON.stringify({
+			type: "subagent.run.completed",
+			lifecycleArtifactVersion: SUBAGENT_LIFECYCLE_ARTIFACT_VERSION,
+			ts: runEndedAt,
+			runId: id,
+			status: statusPayload.state,
+			durationMs: runEndedAt - overallStartTime,
+			totalTokens: statusPayload.totalTokens,
+			totalCost: finalTotalCost,
+			usageBudget: statusPayload.usageBudget,
+		}),
+	);
+	writeRunLog(logPath, omitUndefinedProperties({
+		id,
+		mode: statusPayload.mode,
+		cwd,
+		startedAt: overallStartTime,
+		endedAt: runEndedAt,
+		steps: statusPayload.steps.map((step) => omitUndefinedProperties({
+			agent: step.agent,
+			status: step.status,
+			durationMs: step.durationMs,
+		})),
+		summary,
+		truncated,
+		artifactsDir,
+		sessionFile: effectiveSessionFile,
+		shareUrl,
+		shareError,
+	}));
 	if (config.runnerProcessInstanceId) {
 		const writers: Record<string, Array<{ processInstanceId: string; kind: "pi-writer"; attempt: number; closeObservedAt: number; exitCode: number | null; signal: string | null }>> = {};
 		const expectedWriters: Record<string, number> = {};
@@ -4573,6 +4592,7 @@ async function runSubagent(
 			console.error(`Failed to write process-terminal candidate for '${id}':`, error);
 		}
 	}
+	writeStatusPayload();
 }
 
 async function waitForStartupControl(

package/src/runs/background/subagent-wait.ts

@@ -58,8 +58,10 @@ import {
 	type Details,
 	type ForegroundResumeRun,
 	type SubagentState,
+	type WaitCompletion,
 } from "../../shared/types.ts";
 import { formatDuration, shortenPath } from "../../shared/formatters.ts";
+import { collectWaitCompletions } from "./wait-completions.ts";
 export { WAIT_TOOL_ENABLED_ENV, resolveWaitToolConfig, type ResolvedWaitToolConfig } from "./wait-config.ts";
 
 /** States that mean a run is still in flight (not yet resolved). */
@@ -303,11 +305,15 @@ function summarizeTerminalRuns(runs: AsyncRunSummary[], providerFinishedCount =
 	return parts.join(", ");
 }
 
-function result(text: string, isError = false): AgentToolResult<Details> {
+function result(text: string, isError = false, completions?: WaitCompletion[]): AgentToolResult<Details> {
 	return {
 		content: [{ type: "text", text }],
 		...(isError ? { isError: true } : {}),
-		details: { mode: "management", results: [] },
+		details: {
+			mode: "management",
+			results: [],
+			...(completions && completions.length > 0 ? { completions } : {}),
+		},
 	};
 }
 
@@ -597,6 +603,7 @@ export async function waitForSubagents(
 	let terminalSummary: string;
 	let finishedAsyncCount: number;
 	let failedAsyncCount: number;
+	let completions: WaitCompletion[] | undefined;
 	const activeProviderIds = new Set(providerActive.map(backgroundWorkIdentity));
 	const providerFinishedCount = [...initialProviderIds].filter((id) => !activeProviderIds.has(id)).length;
 	try {
@@ -605,6 +612,7 @@ export async function waitForSubagents(
 		finishedAsyncCount = terminal.length;
 		failedAsyncCount = terminal.filter((run) => run.state === "failed").length;
 		terminalSummary = summarizeTerminalRuns(terminal, providerFinishedCount);
+		completions = collectWaitCompletions(terminal, deps.state, deps.resultsDir ?? DIRS.results);
 	} catch (error) {
 		return result(error instanceof Error ? error.message : String(error), true);
 	}
@@ -631,6 +639,7 @@ export async function waitForSubagents(
 		return result(
 			`Waited ${elapsed} for ${scope}; ${status}.${outcome}${attentionNote} Completion/control events have been observed; inspect status if a notification is not visible yet.`,
 			deps.failOnFailedRuns === true && failedAsyncCount > 0,
+			completions,
 		);
 	}
 
@@ -647,5 +656,6 @@ export async function waitForSubagents(
 	return result(
 		`Waited ${elapsed}; ${progress}.${outcome}${attentionNote}${remainder} Relevant completion/control events have been observed; inspect status if a notification is not visible yet.`,
 		deps.failOnFailedRuns === true && failedAsyncCount > 0,
+		completions,
 	);
 }

package/src/runs/background/wait-completions.ts

@@ -0,0 +1,112 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { ArtifactPaths, SubagentState, WaitCompletion, WaitCompletionChild } from "../../shared/types.ts";
+import type { AsyncRunSummary } from "./async-status.ts";
+
+function asNonEmptyString(value: unknown): string | undefined {
+	return typeof value === "string" && value ? value : undefined;
+}
+
+function errorCode(error: unknown): string | undefined {
+	return typeof error === "object" && error !== null && "code" in error
+		? (error as NodeJS.ErrnoException).code
+		: undefined;
+}
+
+function errorMessage(error: unknown): string {
+	return error instanceof Error ? error.message : String(error);
+}
+
+/**
+ * Project a terminal result payload into the slim shape that is safe to surface in
+ * tool_result details: run identity, per-child outcome, and the artifact trail.
+ * Output text is deliberately excluded — it already travels in the tool result
+ * content, and duplicating it in details would double the payload for every wait.
+ */
+export function toWaitCompletion(data: Record<string, unknown>, runId: string): WaitCompletion {
+	const results = Array.isArray(data.results)
+		? data.results.flatMap((entry): WaitCompletionChild[] => {
+			if (entry === null || typeof entry !== "object") return [];
+			const child = entry as Record<string, unknown>;
+			const outputState = child.outputState === "present" || child.outputState === "absent" || child.outputState === "unknown"
+				? child.outputState
+				: undefined;
+			const artifactPaths = child.artifactPaths !== null && typeof child.artifactPaths === "object"
+				? (child.artifactPaths as Partial<ArtifactPaths>)
+				: undefined;
+			const agent = asNonEmptyString(child.agent);
+			const childRunId = asNonEmptyString(child.runId);
+			const error = asNonEmptyString(child.error);
+			const model = asNonEmptyString(child.model);
+			return [{
+				...(agent ? { agent } : {}),
+				...(childRunId ? { runId: childRunId } : {}),
+				...(typeof child.success === "boolean" ? { success: child.success } : {}),
+				...(outputState ? { outputState } : {}),
+				...(error ? { error } : {}),
+				...(model ? { model } : {}),
+				...(artifactPaths ? { artifactPaths } : {}),
+			}];
+		})
+		: undefined;
+	const agent = asNonEmptyString(data.agent);
+	const mode = asNonEmptyString(data.mode);
+	const state = asNonEmptyString(data.state);
+	return {
+		runId,
+		...(agent ? { agent } : {}),
+		...(mode ? { mode } : {}),
+		...(state ? { state } : {}),
+		...(typeof data.success === "boolean" ? { success: data.success } : {}),
+		...(results && results.length > 0 ? { results } : {}),
+	};
+}
+
+/**
+ * Record a consumed terminal payload for later surfacing by subagent_wait, pruning
+ * stale entries with the same TTL that dedupes completion notifications. The result
+ * file is deleted after delivery, so this record is the only in-process source once
+ * the watcher has consumed it.
+ */
+export function recordWaitCompletion(state: SubagentState, runId: string, data: Record<string, unknown>, now: number, ttlMs: number): void {
+	const store = state.completedResults ??= new Map();
+	for (const [key, entry] of store) {
+		if (now - entry.seenAt > ttlMs) store.delete(key);
+	}
+	store.set(runId, { seenAt: now, completion: toWaitCompletion(data, runId) });
+}
+
+/**
+ * Terminal payloads for the runs a wait covered: the watcher's in-memory record
+ * first, then the not-yet-consumed result file. Result files are written atomically,
+ * so a direct read never observes a torn write; the read is deliberately read-only —
+ * the watcher owns notification and cleanup.
+ */
+export function collectWaitCompletions(terminal: AsyncRunSummary[], state: SubagentState, resultsDir: string): WaitCompletion[] | undefined {
+	if (terminal.length === 0) return undefined;
+	const completions: WaitCompletion[] = [];
+	for (const run of terminal) {
+		const recorded = state.completedResults?.get(run.id);
+		if (recorded) {
+			completions.push(recorded.completion);
+			continue;
+		}
+		const resultPath = path.join(resultsDir, `${run.id}.json`);
+		try {
+			const raw = JSON.parse(fs.readFileSync(resultPath, "utf-8")) as Record<string, unknown>;
+			completions.push(toWaitCompletion(raw, run.id));
+		} catch (error) {
+			if (errorCode(error) !== "ENOENT") {
+				throw new Error(`Failed to read subagent result '${resultPath}': ${errorMessage(error)}`, {
+					cause: error instanceof Error ? error : undefined,
+				});
+			}
+			// The watcher may have consumed the file between the store check and the
+			// read; its record is authoritative when present, otherwise the payload
+			// is gone and the text summary remains the only surface for this run.
+			const late = state.completedResults?.get(run.id);
+			if (late) completions.push(late.completion);
+		}
+	}
+	return completions.length > 0 ? completions : undefined;
+}

package/src/runs/foreground/chain-clarify.ts

@@ -532,7 +532,7 @@ export class ChainClarifyComponent implements Component {
 			buffer = template.split("\n")[0] ?? "";
 		} else if (mode === "output") {
 			const behavior = this.getEffectiveBehavior(this.selectedStep);
-			buffer = behavior.output === false ? "" : (behavior.output || "");
+			buffer = typeof behavior.output === "string" ? behavior.output : "";
 		} else if (mode === "reads") {
 			const behavior = this.getEffectiveBehavior(this.selectedStep);
 			buffer = behavior.reads === false ? "" : (behavior.reads?.join(", ") || "");
@@ -1165,7 +1165,9 @@ export class ChainClarifyComponent implements Component {
 
 		const writesValue = behavior.output === false
 			? th.fg("dim", "(disabled)")
-			: (behavior.output || th.fg("dim", "(none)"));
+			: (typeof behavior.output === "string" && behavior.output
+				? behavior.output
+				: th.fg("dim", "(none)"));
 		const writesLabel = th.fg("dim", "writes: ");
 		lines.push(this.row(`     ${writesLabel}${truncateToWidth(writesValue, innerW - 14)}`));
 
@@ -1296,7 +1298,9 @@ export class ChainClarifyComponent implements Component {
 
 			const writesValue = behavior.output === false
 				? th.fg("dim", "(disabled)")
-				: (behavior.output || th.fg("dim", "(none)"));
+				: (typeof behavior.output === "string" && behavior.output
+					? behavior.output
+					: th.fg("dim", "(none)"));
 			const writesLabel = th.fg("dim", "writes: ");
 			lines.push(this.row(`     ${writesLabel}${truncateToWidth(writesValue, innerW - 14)}`));
 

package/src/runs/foreground/execution.ts

@@ -459,6 +459,7 @@ async function runSingleAttempt(
 	const spawnEnv = { ...process.env, ...sharedEnv, ...getSubagentDepthEnv(options.maxSubagentDepth) };
 	let observedMutationAttempt = false;
 	let structuredOutputToolInvoked = false;
+	let structuredOutputMessageStartIndex: number | undefined;
 
 	const exitCode = await new Promise<number>((resolve) => {
 		const spawnSpec = getPiSpawnCommand(args);
@@ -874,7 +875,10 @@ async function runSingleAttempt(
 				const toolArgs = evt.args && typeof evt.args === "object" && !Array.isArray(evt.args)
 					? evt.args as Record<string, unknown>
 					: {};
-				if (options.structuredOutput && evt.toolName === "structured_output") structuredOutputToolInvoked = true;
+				if (options.structuredOutput && evt.toolName === "structured_output") {
+					structuredOutputToolInvoked = true;
+					structuredOutputMessageStartIndex = result.messages?.length ?? 0;
+				}
 				if (options.allowIntercomDetach && (evt.toolName === "intercom" || evt.toolName === "contact_supervisor")) {
 					intercomStarted = true;
 				}
@@ -1183,24 +1187,7 @@ async function runSingleAttempt(
 	if (result.error && result.exitCode === 0) {
 		result.exitCode = 1;
 	}
-	if (result.exitCode === 0 && !result.error) {
-		const messages = result.messages ?? [];
-		const finalText = getFinalOutput(messages);
-		const missingStructuredOutput = options.structuredOutput
-			? !existsSync(options.structuredOutput.outputPath)
-			: false;
-		const errInfo = detectSubagentError(messages);
-		const missingOutput = !finalText?.trim() && (!options.structuredOutput || missingStructuredOutput);
-		if (missingOutput && (!errInfo.hasError || hasEmptyTerminalAssistantResponse(messages))) {
-			result.exitCode = 1;
-			result.error = "Subagent produced no output (possible model cold-start or empty response).";
-		} else if (errInfo.hasError) {
-			result.exitCode = errInfo.exitCode ?? 1;
-			result.error = errInfo.details
-				? `${errInfo.errorType} failed (exit ${errInfo.exitCode}): ${errInfo.details}`
-				: `${errInfo.errorType} failed with exit code ${errInfo.exitCode}`;
-		}
-	}
+	let validatedStructuredOutput = false;
 	if (options.structuredOutput && result.exitCode === 0 && !result.error) {
 		result.structuredOutputSchemaPath = options.structuredOutput.schemaPath;
 		result.structuredOutputPath = options.structuredOutput.outputPath;
@@ -1220,9 +1207,28 @@ async function runSingleAttempt(
 				result.structuredOutputFailed = true;
 			} else {
 				result.structuredOutput = structured.value;
+				validatedStructuredOutput = true;
 			}
 		}
 	}
+	if (result.exitCode === 0 && !result.error) {
+		const messages = result.messages ?? [];
+		const finalText = getFinalOutput(messages);
+		const errorMessages = validatedStructuredOutput
+			? messages.slice(structuredOutputMessageStartIndex ?? messages.length)
+			: messages;
+		const errInfo = detectSubagentError(errorMessages);
+		const missingOutput = !finalText?.trim() && !validatedStructuredOutput;
+		if (missingOutput && (!errInfo.hasError || hasEmptyTerminalAssistantResponse(messages))) {
+			result.exitCode = 1;
+			result.error = "Subagent produced no output (possible model cold-start or empty response).";
+		} else if (errInfo.hasError) {
+			result.exitCode = errInfo.exitCode ?? 1;
+			result.error = errInfo.details
+				? `${errInfo.errorType} failed (exit ${errInfo.exitCode}): ${errInfo.details}`
+				: `${errInfo.errorType} failed with exit code ${errInfo.exitCode}`;
+		}
+	}
 
 	progress.status = result.exitCode === 0 ? "completed" : "failed";
 	progress.durationMs = Date.now() - startTime;