pi-cohort 7.4.0 → 7.4.2

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## [7.4.2] - 2026-10-19
+
+### Added
+- Children with `outputSchema` get one in-process follow-up after a normal completion without a `structured_output` call; a valid follow-up call succeeds like a first-turn call. (#25)
+
+### Changed
+- Pi >=1.3.0 is required. (#25)
+
+## [7.4.1] - 2026-10-19
+
+### Fixed
+- Non-BLOCKED file-only failures and save errors return an artifact pointer or an explicit not-preserved reason instead of the child reply inline; BLOCKED handoffs and inline mode are unchanged. (#24)
+
 ## [7.4.0] - 2026-10-19
 
 ### Added

package/README.md

@@ -33,6 +33,8 @@ Four independent extensions for the [pi coding agent](https://github.com/earendi
 
 ## Installation
 
+Requires Pi >=1.3.0.
+
 ```bash
 pi install npm:pi-cohort
 ```
@@ -45,7 +47,7 @@ Children and detached coordinators use the originating parent's resolved Node ex
 
 External execution backends are currently unsupported on Windows, for both foreground and background runs. Native execution remains supported.
 
-`pi-cohort/execution-backend` requires Pi >=0.85.0 and is the public API for Pi extensions that add child execution surfaces. Pi's TypeScript-aware runtime loads the API; bare Node is not a supported execution path. Consumers outside Pi must supply a TypeScript-aware loader such as [jiti](https://github.com/unjs/jiti).
+`pi-cohort/execution-backend` requires Pi >=1.3.0 and is the public API for Pi extensions that add child execution surfaces. Pi's TypeScript-aware runtime loads the API; bare Node is not a supported execution path. Consumers outside Pi must supply a TypeScript-aware loader such as [jiti](https://github.com/unjs/jiti).
 
 An adapter registers its backend in extension load order. To make that backend available to background runs, registration also supplies an optional reload descriptor:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-cohort",
-  "version": "7.4.0",
+  "version": "7.4.2",
   "description": "Delegate Pi work to focused child agents: code review, scouting, implementation, parallel audits, saved chains, and background jobs.",
   "author": "Jacek Juraszek",
   "license": "MIT",
@@ -63,7 +63,7 @@
   "peerDependencies": {
     "@earendil-works/pi-agent-core": "*",
     "@earendil-works/pi-ai": "*",
-    "@earendil-works/pi-coding-agent": ">=0.85.0",
+    "@earendil-works/pi-coding-agent": ">=1.3.0",
     "@earendil-works/pi-tui": "*",
     "typebox": "*"
   },
@@ -88,10 +88,10 @@
     "jiti": "^2.7.0"
   },
   "devDependencies": {
-    "@earendil-works/pi-agent-core": "^0.85.0",
-    "@earendil-works/pi-ai": "^0.85.0",
-    "@earendil-works/pi-coding-agent": "^0.85.0",
-    "@earendil-works/pi-tui": "^0.85.0",
+    "@earendil-works/pi-agent-core": "^1.3.0",
+    "@earendil-works/pi-ai": "^1.3.0",
+    "@earendil-works/pi-coding-agent": "^1.3.0",
+    "@earendil-works/pi-tui": "^1.3.0",
     "typebox": "^1.3.11"
   }
 }

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

@@ -7,7 +7,7 @@ import type { Message } from "@earendil-works/pi-ai";
 import { writeAtomicJson } from "../../shared/atomic-json.ts";
 import { appendJsonl, getArtifactPaths } from "../../shared/artifacts.ts";
 import { getPiSpawnCommand, parsePiRuntime, PiRuntimeLaunchError, type PiRuntimeIdentity } from "../shared/pi-spawn.ts";
-import { captureSingleOutputSnapshot, finalizeSingleOutput, formatSavedOutputReference, resolveSingleOutput, type SingleOutputSnapshot } from "../shared/single-output.ts";
+import { captureSingleOutputSnapshot, finalizeSingleOutput, formatFileOnlyFailure, formatSavedOutputReference, resolveSingleOutput, type SingleOutputSnapshot } from "../shared/single-output.ts";
 import {
 	type ActivityState,
 	type ArtifactConfig,
@@ -228,6 +228,7 @@ type ChildMessage = Message & {
 
 interface ChildEvent {
 	type?: string;
+	aborted?: boolean;
 	message?: ChildMessage;
 	toolName?: string;
 	args?: Record<string, unknown>;
@@ -255,6 +256,8 @@ function runPiStreaming(
 	childEventContext?: ChildEventContext,
 	registerInterrupt?: (interrupt: (() => void) | undefined) => void,
 	onChildEvent?: (event: ChildEvent) => void,
+	structuredRun = false,
+	controlConfig: ResolvedControlConfig = DEFAULT_CONTROL_CONFIG,
 ): Promise<RunPiStreamingResult> {
 	return new Promise((resolve, reject) => {
 		const spawnSpec = getPiSpawnCommand(args, runtime);
@@ -321,6 +324,13 @@ function runPiStreaming(
 			appendChildEvent(event);
 			onChildEvent?.(event);
 
+			if (structuredRun && event.type === "agent_settled") {
+				clearSettlementWait();
+				cleanTerminalAssistantStopReceived = !event.aborted && !assistantError && !error && !interrupted;
+				if (event.aborted && !error) error = "Subagent aborted before structured settlement.";
+				startFinalDrain();
+			}
+
 			if (event.type === "tool_execution_start" && event.toolName) {
 				observedMutationAttempt = observedMutationAttempt || isMutatingTool(event.toolName, event.args);
 				const toolArgs = extractToolArgsPreview(event.args ?? {});
@@ -351,7 +361,8 @@ function runPiStreaming(
 				if (stopReason === "stop" && !hasToolCall) {
 					if (!event.message.errorMessage && extractTextFromContent(event.message.content).trim()) assistantError = undefined;
 					cleanTerminalAssistantStopReceived ||= !event.message.errorMessage;
-					startFinalDrain();
+					if (structuredRun) startSettlementWait();
+					else startFinalDrain();
 				}
 			}
 		};
@@ -379,8 +390,31 @@ function runPiStreaming(
 		let finalDrainTimer: NodeJS.Timeout | undefined;
 		let finalHardKillTimer: NodeJS.Timeout | undefined;
 		let settled = false;
+		let lastStreamActivityAt = Date.now();
+		let settlementWaitTimer: NodeJS.Timeout | undefined;
+		function clearSettlementWait(): void {
+			if (settlementWaitTimer) clearInterval(settlementWaitTimer);
+			settlementWaitTimer = undefined;
+		}
+		function startSettlementWait(): void {
+			if (settlementWaitTimer || settled || childExited) return;
+			settlementWaitTimer = setInterval(() => {
+				if (settled || childExited || interrupted) return;
+				const silenceMs = Date.now() - lastStreamActivityAt;
+				if (silenceMs >= controlConfig.inFlightSilenceCeilingMs) {
+					error ??= "Subagent awaiting structured settlement exceeded its silence ceiling. Forcing termination.";
+					cleanTerminalAssistantStopReceived = false;
+					startFinalDrain();
+				}
+				if (silenceMs >= controlConfig.inFlightSilenceKillMs) {
+					forcedTerminationSignal = trySignalChild(child, "SIGKILL") || forcedTerminationSignal;
+				}
+			}, Math.min(1000, controlConfig.inFlightSilenceCeilingMs / 4));
+			settlementWaitTimer.unref?.();
+		}
 		const clearStdioGuard = attachPostExitStdioGuard(child, { idleMs: 2000, hardMs: 8000 });
 		child.stdout.on("data", (chunk: Buffer) => {
+			lastStreamActivityAt = Date.now();
 			const text = chunk.toString();
 			stdoutBuf += text;
 			const lines = stdoutBuf.split("\n");
@@ -389,11 +423,13 @@ function runPiStreaming(
 		});
 
 		child.stderr.on("data", (chunk: Buffer) => {
+			lastStreamActivityAt = Date.now();
 			processStderrText(chunk.toString());
 		});
 		registerInterrupt?.(() => {
 			if (settled) return;
 			interrupted = true;
+			clearSettlementWait();
 			if (!error) error = "Interrupted. Waiting for explicit next action.";
 			trySignalChild(child, "SIGINT");
 			setTimeout(() => {
@@ -401,6 +437,7 @@ function runPiStreaming(
 			}, 1000).unref?.();
 		});
 		const clearDrainTimers = () => {
+			clearSettlementWait();
 			if (finalDrainTimer) {
 				clearTimeout(finalDrainTimer);
 				finalDrainTimer = undefined;
@@ -590,6 +627,7 @@ export interface SingleStepContext {
 	onChildEvent?: (event: ChildEvent) => void;
 	executionBackendCoordinator?: DetachedExecutionBackendCoordinator;
 	executionBackendConfig?: DetachedExecutionBackendConfig;
+	controlConfig?: ResolvedControlConfig;
 }
 
 /** Execute one detached-runner leaf. */
@@ -909,6 +947,8 @@ export async function runSingleStep(
 				{ eventsPath, runId: ctx.id, stepIndex: ctx.flatIndex, agent: step.agent },
 				ctx.registerInterrupt,
 				ctx.onChildEvent,
+				effectiveStructuredOutput !== undefined,
+				ctx.controlConfig ?? DEFAULT_CONTROL_CONFIG,
 			);
 		} catch (error) {
 			if (!(error instanceof PiRuntimeLaunchError)) throw error;
@@ -1007,6 +1047,8 @@ export async function runSingleStep(
 	let acceptanceCanFailRun = false;
 	let effectiveFinalExitCode = resolvedOutput.saveError ? 1 : finalResult?.exitCode ?? 1;
 	let effectiveFinalError = finalResult?.error;
+	let preservedAt: string | undefined;
+	let notPreservedReason = "artifact output disabled";
 	if (resolvedOutput.saveError) {
 		effectiveFinalError = effectiveFinalError
 			? `${effectiveFinalError}\n${resolvedOutput.saveError}`
@@ -1037,7 +1079,14 @@ export async function runSingleStep(
 
 	if (artifactPaths && ctx.artifactConfig?.enabled !== false) {
 		if (ctx.artifactConfig?.includeOutput !== false) {
-			fs.writeFileSync(artifactPaths.outputPath, output, "utf-8");
+			try {
+				fs.writeFileSync(artifactPaths.outputPath, output, "utf-8");
+				preservedAt = artifactPaths.outputPath;
+			} catch (error) {
+				const message = error instanceof Error ? error.message : String(error);
+				notPreservedReason = `artifact write failed: ${message}`;
+				throw error;
+			}
 		}
 		if (ctx.artifactConfig?.includeMetadata !== false) {
 			fs.writeFileSync(
@@ -1063,11 +1112,14 @@ export async function runSingleStep(
 		effectiveFinalError = effectiveFinalError ? `${effectiveFinalError}\n${message}` : message;
 	}
 
+	const outputBeforeExternalFinalization = outputForSummary;
+	let externalOutputPersisted = false;
 	// Native runs have runPiStreaming write outputFile live; external runs persist it
 	// before their surface can be destructively closed as delivered.
 	if (externalOwner) {
 		try {
 			fs.writeFileSync(ctx.outputFile, outputForSummary, "utf-8");
+			externalOutputPersisted = true;
 		} catch (error) {
 			const message = safeExternalFailure("output persistence", error);
 			effectiveFinalExitCode = 1;
@@ -1090,6 +1142,30 @@ export async function runSingleStep(
 		executionSurface = { handle: finishResult.handle, retained: finishResult.retained };
 	}
 
+	if (step.outputMode === "file-only"
+		&& (effectiveFinalExitCode !== 0 || resolvedOutput.saveError)
+		&& !blockedLine(effectiveFinalError ?? "")) {
+		const pointer = formatFileOnlyFailure({
+			outputPath: step.outputPath,
+			saveError: resolvedOutput.saveError,
+			...(preservedAt !== undefined ? { preservedAt } : { notPreservedReason }),
+		});
+		outputForSummary = attemptNotes.length > 0
+			? `${attemptNotes.join("\n")}\n\n${pointer}`
+			: pointer;
+	}
+
+	// finish can turn a saved success into a failure after the pre-close log write.
+	if (externalOutputPersisted && outputForSummary !== outputBeforeExternalFinalization) {
+		try {
+			fs.writeFileSync(ctx.outputFile, outputForSummary, "utf-8");
+		} catch (error) {
+			const message = safeExternalFailure("output persistence", error);
+			effectiveFinalExitCode = 1;
+			effectiveFinalError = effectiveFinalError ? `${effectiveFinalError}\n${message}` : message;
+		}
+	}
+
 	return {
 		agent: step.agent,
 		output: outputForSummary,
@@ -1891,6 +1967,7 @@ async function runSubagent(config: SubagentRunConfig): Promise<void> {
 					flatIndex: fi, flatStepCount: Math.max(statusPayload.steps.length, 1),
 					outputFile: path.join(asyncDir, `output-${fi}.log`),
 					runtime: config.runtime,
+					controlConfig: config.controlConfig,
 					forwardedFlags: config.forwardedFlags,
 					executionBackendCoordinator,
 					executionBackendConfig,
@@ -2147,6 +2224,7 @@ async function runSubagent(config: SubagentRunConfig): Promise<void> {
 							flatIndex: fi, flatStepCount: flatSteps.length,
 							outputFile: path.join(asyncDir, `output-${fi}.log`),
 							runtime: config.runtime,
+							controlConfig: config.controlConfig,
 							forwardedFlags: config.forwardedFlags,
 							executionBackendCoordinator,
 							executionBackendConfig,
@@ -2325,6 +2403,7 @@ async function runSubagent(config: SubagentRunConfig): Promise<void> {
 				flatIndex, flatStepCount: flatSteps.length,
 				outputFile: path.join(asyncDir, `output-${flatIndex}.log`),
 				runtime: config.runtime,
+				controlConfig: config.controlConfig,
 				forwardedFlags: config.forwardedFlags,
 				executionBackendCoordinator,
 				executionBackendConfig,

package/src/runs/foreground/execution.ts

@@ -46,7 +46,7 @@ import { PINNED_AGENT_DIR_OVERRIDE } from "../../shared/agent-dir.ts";
 import { createJsonlWriter } from "../../shared/jsonl-writer.ts";
 import { attachPostExitStdioGuard, trySignalChild } from "../../shared/post-exit-stdio-guard.ts";
 import { buildPiArgs, cleanupTempDir } from "../shared/pi-args.ts";
-import { captureSingleOutputSnapshot, validateFileOnlyOutputMode } from "../shared/single-output.ts";
+import { captureSingleOutputSnapshot, formatFileOnlyFailure, validateFileOnlyOutputMode } from "../shared/single-output.ts";
 import {
 	buildModelCandidates,
 	formatModelAttemptNote,
@@ -192,13 +192,18 @@ async function runSingleAttempt(
 		let activityTimer: NodeJS.Timeout | undefined;
 
 
-		// If the child emits a terminal assistant stop but never exits,
-		// give it a short grace period to flush naturally, then clean it up.
+		// Structured continuations can outlive a prose stop; drain only after settlement.
 		const FINAL_STOP_GRACE_MS = 1000;
 		const HARD_KILL_MS = 3000;
 		let childExited = false;
 		let forcedTerminationSignal = false;
 		let cleanTerminalAssistantStopReceived = false;
+		let structuredSettlementPending = Boolean(options.structuredOutput);
+		let cleanStructuredSettlementReceived = false;
+		let silenceHardKillTimer: NodeJS.Timeout | undefined;
+		const cleanCompletionReceived = () => options.structuredOutput
+			? cleanStructuredSettlementReceived && !options.signal?.aborted && !interruptedByControl && !silenceKillRequested
+			: cleanTerminalAssistantStopReceived;
 		let finalDrainTimer: NodeJS.Timeout | undefined;
 		let finalHardKillTimer: NodeJS.Timeout | undefined;
 		const clearFinalDrainTimers = () => {
@@ -218,7 +223,7 @@ async function runSingleAttempt(
 				const termSent = trySignalChild(proc, "SIGTERM");
 				if (!termSent) return;
 				forcedTerminationSignal = true;
-				if (!cleanTerminalAssistantStopReceived && !assistantError) {
+				if (!cleanCompletionReceived() && !assistantError) {
 					result.error = result.error ?? `Subagent process did not exit within ${FINAL_STOP_GRACE_MS}ms after its final message. Forcing termination.`;
 				}
 				finalHardKillTimer = setTimeout(() => {
@@ -240,17 +245,19 @@ async function runSingleAttempt(
 			result.error = result.error ??
 				`Subagent killed: in-flight turn produced no output for ${Math.round(silenceMs / 1000)}s ` +
 				`(exceeded inFlightSilenceKillMs=${controlConfig.inFlightSilenceKillMs}ms). Likely wedged in a tool call.`;
-			const hardKill = setTimeout(() => {
+			silenceHardKillTimer = setTimeout(() => {
 				if (settled || processClosed) return;
 				forcedTerminationSignal = trySignalChild(proc, "SIGKILL") || forcedTerminationSignal;
 			}, HARD_KILL_MS);
-			hardKill.unref?.();
+			silenceHardKillTimer.unref?.();
 		};
 
 
 		const finish = (code: number) => {
 			if (settled) return;
 			settled = true;
+			structuredSettlementPending = false;
+			if (silenceHardKillTimer) clearTimeout(silenceHardKillTimer);
 			clearFinalDrainTimers();
 			clearStdioGuard();
 			if (activityTimer) {
@@ -326,19 +333,33 @@ async function runSingleAttempt(
 			return true;
 		};
 		const updateActivityState = (now: number): boolean => {
+			if (structuredSettlementPending
+				&& now - (progress.lastProductiveSignalAt ?? startTime) >= controlConfig.inFlightSilenceCeilingMs) {
+				result.error ??= "Subagent awaiting structured settlement exceeded its silence ceiling. Forcing termination.";
+				startFinalDrain();
+			}
+			if (!controlConfig.enabled && structuredSettlementPending && shouldSilenceKill({
+				turnOpen: progress.turnOpen || structuredSettlementPending,
+				lastProductiveSignalAt: progress.lastProductiveSignalAt,
+				startedAt: startTime,
+				now,
+				killMs: controlConfig.inFlightSilenceKillMs,
+			})) {
+				requestSilenceKill(now - (progress.lastProductiveSignalAt ?? startTime));
+			}
 			if (!controlConfig.enabled) return false;
 			const idleState = deriveActivityState({
 				config: controlConfig,
 				startedAt: startTime,
 				lastActivityAt: progress.lastActivityAt,
 				now,
-				inFlightTurn: progress.turnOpen,
+				inFlightTurn: progress.turnOpen || structuredSettlementPending,
 				lastProductiveSignalAt: progress.lastProductiveSignalAt,
 			});
 			if (idleState === "needs_attention") {
 				const notified = progress.activityState === "needs_attention" ? false : emitNeedsAttention(now);
 				if (shouldSilenceKill({
-					turnOpen: progress.turnOpen,
+					turnOpen: progress.turnOpen || structuredSettlementPending,
 					lastProductiveSignalAt: progress.lastProductiveSignalAt,
 					startedAt: startTime,
 					now,
@@ -383,9 +404,9 @@ async function runSingleAttempt(
 		const processLine = (line: string) => {
 			if (!line.trim()) return;
 			jsonlWriter.writeLine(line);
-			let evt: { type?: string; message?: Message; toolName?: string; args?: unknown };
+			let evt: { type?: string; message?: Message; toolName?: string; args?: unknown; aborted?: boolean };
 			try {
-				evt = JSON.parse(line) as { type?: string; message?: Message; toolName?: string; args?: unknown };
+				evt = JSON.parse(line) as typeof evt;
 			} catch {
 				// Non-JSON stdout lines are expected; only structured events are parsed.
 				return;
@@ -407,6 +428,14 @@ async function runSingleAttempt(
 			progress.lastProductiveSignalAt = lifecycle.lastProductiveSignalAt;
 			updateActivityState(now);
 
+			if (options.structuredOutput && evt.type === "agent_settled") {
+				structuredSettlementPending = false;
+				cleanStructuredSettlementReceived = !evt.aborted && !assistantError
+					&& !options.signal?.aborted && !interruptedByControl && !silenceKillRequested;
+				if (evt.aborted) result.error ??= "Subagent settlement aborted.";
+				startFinalDrain();
+			}
+
 			if (evt.type === "tool_execution_start") {
 				const toolArgs = evt.args && typeof evt.args === "object" && !Array.isArray(evt.args)
 					? evt.args as Record<string, unknown>
@@ -455,14 +484,14 @@ async function runSingleAttempt(
 					if (evt.message.errorMessage) assistantError = evt.message.errorMessage;
 					const assistantText = extractTextFromContent(evt.message.content);
 					appendRecentOutput(progress, assistantText.split("\n").slice(-10));
-					// Final assistant message: start the exit drain window.
+					// Unstructured runs still drain on the final assistant message.
 					const stopReason = (evt.message as { stopReason?: string }).stopReason;
 					const hasToolCall = Array.isArray(evt.message.content)
 						&& evt.message.content.some((part) => (part as { type?: string }).type === "toolCall");
 					if (stopReason === "stop" && !hasToolCall) {
 						if (!evt.message.errorMessage && assistantText.trim()) assistantError = undefined;
 						cleanTerminalAssistantStopReceived ||= !evt.message.errorMessage;
-						startFinalDrain();
+						if (!options.structuredOutput) startFinalDrain();
 					}
 				}
 				updateActivityState(now);
@@ -499,7 +528,7 @@ async function runSingleAttempt(
 			}
 		};
 
-		if (controlConfig.enabled) {
+		if (controlConfig.enabled || options.structuredOutput) {
 			activityTimer = setInterval(() => {
 				if (processClosed || settled) return;
 				const now = Date.now();
@@ -514,13 +543,20 @@ async function runSingleAttempt(
 		let stderrBuf = "";
 
 		const clearStdioGuard = attachPostExitStdioGuard(proc, { idleMs: 2000, hardMs: 8000 });
+		const refreshStructuredWait = () => {
+			if (!structuredSettlementPending) return;
+			progress.lastActivityAt = Date.now();
+			progress.lastProductiveSignalAt = progress.lastActivityAt;
+		};
 		proc.stdout.on("data", (d) => {
+			refreshStructuredWait();
 			buf += d.toString();
 			const lines = buf.split("\n");
 			buf = lines.pop() || "";
 			lines.forEach(processLine);
 		});
 		proc.stderr.on("data", (d) => {
+			refreshStructuredWait();
 			stderrBuf += d.toString();
 		});
 		proc.on("exit", () => {
@@ -537,7 +573,7 @@ async function runSingleAttempt(
 			processClosed = true;
 			if (buf.trim()) processLine(buf);
 			if (!result.error && assistantError) result.error = assistantError;
-			const forcedDrainAfterFinalSuccess = forcedTerminationSignal && cleanTerminalAssistantStopReceived && !result.error;
+			const forcedDrainAfterFinalSuccess = forcedTerminationSignal && cleanCompletionReceived() && !result.error;
 			if (code !== 0 && stderrBuf.trim() && !result.error && !forcedDrainAfterFinalSuccess) {
 				result.error = stderrBuf.trim();
 			}
@@ -815,6 +851,8 @@ export async function runSync(
 	} satisfies SingleResult;
 
 	let postLoopError: unknown;
+	let preservedAt: string | undefined;
+	let notPreservedReason = "artifact output disabled";
 	try {
 		result.usage = aggregateUsage;
 		result.attemptedModels = attemptedModels.length > 0 ? attemptedModels : undefined;
@@ -834,7 +872,14 @@ export async function runSync(
 		if (artifactPathsResult && options.artifactConfig?.enabled !== false) {
 			result.artifactPaths = artifactPathsResult;
 			if (options.artifactConfig?.includeOutput !== false) {
-				writeArtifact(artifactPathsResult.outputPath, artifactOutputByResult.get(result) ?? result.finalOutput ?? "");
+				try {
+					writeArtifact(artifactPathsResult.outputPath, artifactOutputByResult.get(result) ?? result.finalOutput ?? "");
+					preservedAt = artifactPathsResult.outputPath;
+				} catch (error) {
+					const message = error instanceof Error ? error.message : String(error);
+					notPreservedReason = `artifact write failed: ${message}`;
+					throw error;
+				}
 			}
 			if (options.artifactConfig?.includeMetadata !== false) {
 				writeMetadata(artifactPathsResult.metadataPath, {
@@ -912,9 +957,19 @@ export async function runSync(
 				: safeMessage;
 			result.executionSurface ??= { handle: externalOwner.surface, retained: true };
 		}
-	} else if (postLoopError) {
-		throw postLoopError;
 	}
 
+	if (options.outputMode === "file-only"
+		&& (result.exitCode !== 0 || result.outputSaveError)
+		&& !blockedLine(result.error ?? "")) {
+		result.finalOutput = formatFileOnlyFailure({
+			outputPath: options.outputPath,
+			saveError: result.outputSaveError,
+			...(preservedAt !== undefined ? { preservedAt } : { notPreservedReason }),
+		});
+		result.truncation = undefined;
+	}
+	if (!externalOwner && postLoopError) throw postLoopError;
+
 	return result;
 }

package/src/runs/foreground/subagent-executor.ts

@@ -39,6 +39,7 @@ import { createForkContextResolver } from "../../shared/fork-context.ts";
 import { resolveCurrentSessionId } from "../../shared/session-identity.ts";
 import { formatControlNoticeMessage, resolveControlConfig, shouldNotifyControlEvent } from "../shared/subagent-control.ts";
 import { finalizeSingleOutput, injectSingleOutputInstruction, normalizeTopLevelOutput, resolveParallelTaskOutputPath, resolveSingleOutputPath, validateFileOnlyOutputMode } from "../shared/single-output.ts";
+import { blockedLine } from "../shared/completion-guard.ts";
 import { compactForegroundDetails, getSingleResultOutput, mapConcurrent, readStatus, resolveChildCwd } from "../../shared/utils.ts";
 import { resolveSubagentResultStatus } from "../shared/result-children.ts";
 import { buildRevivedAsyncTask, resolveAsyncResumeTarget } from "../background/async-resume.ts";
@@ -2064,7 +2065,7 @@ async function runSinglePath(data: ExecutionContextData, deps: ExecutorDeps): Pr
 	if (r.artifactPaths) allArtifactPaths.push(r.artifactPaths);
 
 	const fullOutput = getSingleResultOutput(r);
-	const finalizedOutput = finalizeSingleOutput({
+	const displayOutput = r.outputMode === "file-only" ? r.finalOutput : finalizeSingleOutput({
 		fullOutput,
 		truncatedOutput: r.truncation?.text,
 		outputPath,
@@ -2073,7 +2074,7 @@ async function runSinglePath(data: ExecutionContextData, deps: ExecutorDeps): Pr
 		savedPath: r.savedOutputPath,
 		outputReference: r.outputReference,
 		saveError: r.outputSaveError,
-	});
+	}).displayOutput;
 	const details = compactForegroundDetails({
 		mode: "single",
 		runId,
@@ -2096,14 +2097,14 @@ async function runSinglePath(data: ExecutionContextData, deps: ExecutorDeps): Pr
 		};
 	}
 
-	if (r.exitCode !== 0)
-		return {
-			content: [{ type: "text", text: r.error || "Failed" }],
-			details,
-			isError: true,
-		};
+	if (r.exitCode !== 0) {
+		const text = r.outputMode === "file-only" && !blockedLine(r.error ?? "")
+			? `FAILED (exit code ${r.exitCode})${r.error ? `: ${r.error}` : ""}\n\n${r.finalOutput ?? ""}`
+			: r.error || "Failed";
+		return { content: [{ type: "text", text }], details, isError: true };
+	}
 	return {
-		content: [{ type: "text", text: finalizedOutput.displayOutput || "(no output)" }],
+		content: [{ type: "text", text: displayOutput || "(no output)" }],
 		details,
 	};
 }

package/src/runs/shared/forward-flags.ts

@@ -3,7 +3,7 @@ export interface ForwardFlagsConfig {
 }
 
 // Core pi flag names -> value arity. This is the UNION of recognized core flags
-// across the supported pi range (0.74-0.85), transcribed from
+// across the supported pi range (0.74-1.3), transcribed from
 // @earendil-works/pi-coding-agent dist/cli/args.js. A name present here is never
 // forwarded to children. Direction matters: an entry that is core in a NEWER pi
 // but absent from an OLDER installed pi is safe (worst case we skip forwarding a
@@ -14,7 +14,7 @@ type Arity = "boolean" | "value" | "value-guarded" | "value-guarded-print";
 export const RECOGNIZED_PI_FLAGS: Record<string, Arity> = {
   help: "boolean", version: "boolean", continue: "boolean", resume: "boolean",
   "no-session": "boolean", "no-tools": "boolean", "no-builtin-tools": "boolean",
-  "no-extensions": "boolean", "no-skills": "boolean", "no-prompt-templates": "boolean",
+  "no-extensions": "boolean", "no-mcp": "boolean", "no-skills": "boolean", "no-prompt-templates": "boolean",
   "no-themes": "boolean", "no-context-files": "boolean", verbose: "boolean",
   approve: "boolean", "no-approve": "boolean", offline: "boolean",
   mode: "value", provider: "value", model: "value", "api-key": "value",

package/src/runs/shared/single-output.ts

@@ -106,6 +106,16 @@ export function formatSavedOutputReference(savedPath: string, fullOutput: string
 	};
 }
 
+export function formatFileOnlyFailure(params: {
+	outputPath?: string;
+	saveError?: string;
+} & ({ preservedAt: string; notPreservedReason?: never } | { preservedAt?: never; notPreservedReason: string })): string {
+	const pointer = params.preservedAt !== undefined
+		? `Full reply preserved at ${params.preservedAt}`
+		: `Full reply not preserved (${params.notPreservedReason})`;
+	return params.saveError ? `Output file error: ${params.outputPath}\n${params.saveError}\n\n${pointer}` : pointer;
+}
+
 export function validateFileOnlyOutputMode(outputMode: OutputMode | undefined, outputPath: string | undefined, context: string): string | undefined {
 	if (outputMode === "file-only" && !outputPath) {
 		return `${context} sets outputMode: "file-only" but does not configure an output file. Set output to a path or use outputMode: "inline".`;

package/src/runs/shared/structured-output.ts

@@ -55,13 +55,48 @@ export function validateStructuredOutputValue(schema: JsonSchemaObject, value: u
 	return { status: "invalid", message: errors.join("; ") || "schema validation failed" };
 }
 
+const VALIDATION_PREFIX = "Structured output validation failed:";
+const PARAMETER_VALIDATION_PREFIX = 'Validation failed for tool "structured_output":';
+const PARSE_VALIDATION_PREFIX = 'Invalid arguments for tool "structured_output":';
+const INVALID_ARGUMENTS = "Invalid structured_output arguments";
+
+function normalizeValidationDiagnostic(content: string): string {
+	let diagnostic = content.split("Received arguments:", 1)[0].trim();
+	for (;;) {
+		if (diagnostic.startsWith(PARSE_VALIDATION_PREFIX)) return INVALID_ARGUMENTS;
+		const prefix = [VALIDATION_PREFIX, PARAMETER_VALIDATION_PREFIX].find((prefix) => diagnostic.startsWith(prefix));
+		if (!prefix) break;
+		diagnostic = diagnostic.slice(prefix.length).trim();
+	}
+	return diagnostic || INVALID_ARGUMENTS;
+}
+
+export function getStructuredOutputValidationDiagnostic(content: unknown): string | undefined {
+	if (typeof content !== "string") return undefined;
+	if (![VALIDATION_PREFIX, PARAMETER_VALIDATION_PREFIX, PARSE_VALIDATION_PREFIX].some((prefix) => content.startsWith(prefix))) return undefined;
+	return normalizeValidationDiagnostic(content);
+}
+
 export function readStructuredOutput(runtime: StructuredOutputRuntime): { value?: unknown; error?: string } {
 	if (!fs.existsSync(runtime.outputPath)) {
 		return { error: "Missing structured_output call; this step has outputSchema and must finish by calling structured_output." };
 	}
 	let value: unknown;
 	try {
-		value = JSON.parse(fs.readFileSync(runtime.outputPath, "utf-8"));
+		const envelope: unknown = JSON.parse(fs.readFileSync(runtime.outputPath, "utf-8"));
+		if (!envelope || typeof envelope !== "object" || Array.isArray(envelope)) {
+			throw new Error("Expected a capture envelope object.");
+		}
+		const capture = envelope as Record<string, unknown>;
+		if (capture.status === "error") {
+			if (typeof capture.message !== "string" || !capture.message.trim()) {
+				throw new Error("Error capture requires a nonempty message.");
+			}
+			return { error: `${VALIDATION_PREFIX} ${normalizeValidationDiagnostic(capture.message)}` };
+		}
+		if (capture.status !== "success") throw new Error("Unknown capture status.");
+		if (!Object.hasOwn(capture, "value")) throw new Error("Success capture requires a value.");
+		value = capture.value;
 	} catch (error) {
 		return { error: `Failed to read structured output: ${error instanceof Error ? error.message : String(error)}` };
 	}

package/src/runs/shared/subagent-prompt-runtime.ts

@@ -2,11 +2,30 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { SUBAGENT_FANOUT_CHILD_ENV } from "./pi-args.ts";
-import { STRUCTURED_OUTPUT_CAPTURE_ENV, STRUCTURED_OUTPUT_SCHEMA_ENV, STRUCTURED_OUTPUT_TOOL_NAME, validateStructuredOutputValue } from "./structured-output.ts";
+import { STRUCTURED_OUTPUT_CAPTURE_ENV, STRUCTURED_OUTPUT_SCHEMA_ENV, STRUCTURED_OUTPUT_TOOL_NAME, getStructuredOutputValidationDiagnostic, validateStructuredOutputValue } from "./structured-output.ts";
 import type { JsonSchemaObject } from "../../shared/types.ts";
 
 const SUBAGENT_INHERIT_PROJECT_CONTEXT_ENV = "PI_SUBAGENT_INHERIT_PROJECT_CONTEXT";
 const SUBAGENT_INHERIT_SKILLS_ENV = "PI_SUBAGENT_INHERIT_SKILLS";
+let reasked = false;
+let attempted = false;
+
+function lastAssistantStopReason(messages: unknown[]): string | undefined {
+	for (let i = messages.length - 1; i >= 0; i--) {
+		const message = messages[i] as { role?: string; stopReason?: string };
+		if (message?.role === "assistant") return message.stopReason;
+	}
+	return undefined;
+}
+
+function reaskMessage(schema: JsonSchemaObject) {
+	return {
+		type: "custom_message",
+		customType: "pi-cohort:structured-output-reask",
+		display: true,
+		content: "You finished without calling `structured_output`. Call `structured_output` now with a `value` matching this schema, and send no other text:\n\n" + JSON.stringify(schema, null, 2),
+	};
+}
 
 const STRUCTURED_OUTPUT_INSTRUCTIONS = [
 	"This subagent step has a strict structured output contract.",
@@ -176,6 +195,10 @@ function collectSubagentToolCallIds(entries: readonly unknown[]): Set<string> {
 }
 
 export default function registerSubagentPromptRuntime(pi: ExtensionAPI): void {
+	const onRuntimeEvent = pi.on as unknown as (
+		event: string,
+		handler: (event: unknown, ctx?: { sessionManager?: { getBranch(): unknown[] } }) => unknown,
+	) => void;
 	const structuredOutputPath = process.env[STRUCTURED_OUTPUT_CAPTURE_ENV];
 	const structuredSchemaPath = process.env[STRUCTURED_OUTPUT_SCHEMA_ENV];
 	if (structuredOutputPath && structuredSchemaPath) {
@@ -199,12 +222,13 @@ export default function registerSubagentPromptRuntime(pi: ExtensionAPI): void {
 			description: "Submit the required final structured output for this subagent step. This terminates the step.",
 			parameters: parameters as never,
 			async execute(_id: string, params: { value: unknown }) {
+				attempted = true;
 				const validation = validateStructuredOutputValue(schema, params.value);
 				if (validation.status === "invalid") {
 					throw new Error(`Structured output validation failed: ${validation.message}`);
 				}
 				fs.mkdirSync(path.dirname(structuredOutputPath), { recursive: true });
-				fs.writeFileSync(structuredOutputPath, JSON.stringify(params.value), { mode: 0o600 });
+				fs.writeFileSync(structuredOutputPath, JSON.stringify({ status: "success", value: params.value }), { mode: 0o600 });
 				return {
 					content: [{ type: "text", text: "Structured output captured." }],
 					details: { path: structuredOutputPath },
@@ -212,13 +236,47 @@ export default function registerSubagentPromptRuntime(pi: ExtensionAPI): void {
 				};
 			},
 		});
+		onRuntimeEvent("tool_execution_start", (event) => {
+			const e = event as { toolName: string };
+			if (e.toolName === STRUCTURED_OUTPUT_TOOL_NAME) attempted = true;
+		});
+		onRuntimeEvent("tool_execution_end", (event) => {
+			const e = event as { toolName: string; isError: boolean; result?: { content?: { type: string; text?: string }[] } };
+			if (e.toolName !== STRUCTURED_OUTPUT_TOOL_NAME) return;
+			attempted = true;
+			if (!e.isError) return;
+			const text = e.result?.content?.filter((block) => block.type === "text").map((block) => block.text ?? "").join("\n");
+			const message = getStructuredOutputValidationDiagnostic(text);
+			if (message === undefined) return;
+			try {
+				const capture = JSON.parse(fs.readFileSync(structuredOutputPath, "utf-8"));
+				if (capture?.status === "success") return;
+			} catch (error) {
+				if ((error as NodeJS.ErrnoException).code !== "ENOENT") return;
+			}
+			try {
+				fs.writeFileSync(structuredOutputPath, JSON.stringify({ status: "error", message }), { mode: 0o600 });
+			} catch {
+				// The parent owns capture-read errors when recording the attempt fails.
+			}
+		});
+		onRuntimeEvent("agent_before_settle", (event) => {
+			const e = event as { outcome: string; entries: unknown[]; context: { contextMessages: unknown[] } };
+			if (reasked || attempted) return undefined;
+			if (e.outcome !== "completed") return undefined;
+			if (lastAssistantStopReason(e.context.contextMessages) === "length") return undefined;
+			try {
+				fs.statSync(structuredOutputPath);
+				return undefined;
+			} catch (error) {
+				if ((error as NodeJS.ErrnoException).code !== "ENOENT") return undefined;
+			}
+			reasked = true;
+			return { entries: [...e.entries, reaskMessage(schema)], continue: true };
+		});
 	}
 
 	let inheritedSubagentToolCallIds: ReadonlySet<string> = new Set<string>();
-	const onRuntimeEvent = pi.on as unknown as (
-		event: string,
-		handler: (event: unknown, ctx?: { sessionManager?: { getBranch(): unknown[] } }) => unknown,
-	) => void;
 	onRuntimeEvent("session_start", (_event: unknown, ctx?: { sessionManager?: { getBranch(): unknown[] } }) => {
 		// Establishes the inherited/own boundary once, before the child's own first turn: any
 		// `subagent` call already in the branch at this point came from the (forked) parent.

package/src/shared/utils.ts

@@ -6,6 +6,7 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import type { Message } from "@earendil-works/pi-ai";
+import { getStructuredOutputValidationDiagnostic, STRUCTURED_OUTPUT_TOOL_NAME } from "../runs/shared/structured-output.ts";
 import { formatToolCall } from "./formatters.ts";
 import type { AgentProgress, AsyncStatus, Details, DisplayItem, ErrorInfo, SingleResult, ToolCallSummary } from "./types.ts";
 
@@ -293,6 +294,7 @@ export function detectSubagentError(messages: Message[]): ErrorInfo {
 	}
 
 	const scanStart = lastAssistantTextIndex >= 0 ? lastAssistantTextIndex + 1 : 0;
+	let hasLaterStructuredOutputSuccess = false;
 
 	for (let i = messages.length - 1; i >= scanStart; i--) {
 		const msg = messages[i];
@@ -300,9 +302,15 @@ export function detectSubagentError(messages: Message[]): ErrorInfo {
 		const toolName = "toolName" in msg && typeof msg.toolName === "string" ? msg.toolName : undefined;
 		const isError = "isError" in msg && msg.isError === true;
 
+		if (toolName === STRUCTURED_OUTPUT_TOOL_NAME && !isError) {
+			hasLaterStructuredOutputSuccess = true;
+		}
+
 		if (isError) {
 			const text = msg.content.find((c) => c.type === "text");
 			const details = text && "text" in text ? text.text : undefined;
+			if (toolName === STRUCTURED_OUTPUT_TOOL_NAME && hasLaterStructuredOutputSuccess
+				&& getStructuredOutputValidationDiagnostic(details) !== undefined) continue;
 			const exitMatch = details?.match(/exit(?:ed)?\s*(?:with\s*)?(?:code|status)?\s*[:\s]?\s*(\d+)/i);
 			return {
 				hasError: true,