@selesai/code 0.5.29 → 0.6.2

package/dist/extensions/pi-subagents/src/extension/tool-description.ts

@@ -6,13 +6,27 @@ import { getAgentDir, getProjectConfigDir } from "../shared/utils.ts";
 const CUSTOM_TOOL_DESCRIPTION_FILE = "subagent-tool-description.md";
 const CUSTOM_TOOL_DESCRIPTION_MAX_BYTES = 50 * 1024;
 
+/**
+ * Generic parent-only delegation routing contract. Deliberately contains no
+ * bundled agent names: agents are selected from runtime catalog metadata only.
+ * Attached to the parent `subagent` tool as promptGuidelines and embedded in
+ * the mandatory safety guidance so custom descriptions cannot remove it.
+ */
+export const SUBAGENT_PARENT_ROUTING_GUIDANCE = `PARENT-ONLY SUBAGENT ROUTING:
+• Before any execution, call { action: "list" } and select only an executable entry using its current role, context, and tool metadata.
+• Keep tiny targeted reads and simple answers local with the parent.
+• Send broad local investigation, external research, and mutation/implementation work to a capable delegated agent.
+• The parent remains the decision-maker and normally the sole writer.`;
+
 export const SUBAGENT_SAFETY_GUIDANCE = `SAFETY-CRITICAL SUBAGENT GUIDANCE:
 • Use { action: "list" } before execution and only run executable/non-disabled agents or chains.
 • Keep execution and management separate: omit action for SINGLE/PARALLEL/CHAIN execution; use action only for list/get/models/create/update/delete/status/grant-spawn-budget/interrupt/stop/resume/steer/append-step/approve-checkpoint/reject-checkpoint/doctor.
 • Async/background runs: launch with async:true only when work can proceed independently. Do not sleep or poll status just to wait. In an interactive session, normally return control and let Pi wake you; do not call subagent_wait merely to wait. Override that default and call subagent_wait when the current request is run-to-completion — for example, the user asked you to report results back before continuing or a skill must finish in one turn. Headless sessions auto-drain current-session work at agent_end; use subagent_wait when this turn must receive results before it ends.
 • Child-safety boundary: ordinary child subagents are not orchestrators and must not run subagents. Only explicitly configured fanout children may use the child-safe subagent tool, still bounded by depth/session limits.
 • Writing/review safety: keep one writer for the same cwd/worktree. Use fresh-context read-only reviewers/validators for independent review, then have the parent synthesize and apply fixes as the sole writer unless an isolated worktree was intentionally requested.
-• Artifacts/status essentials: chain outputs live under {chain_dir}; async runs expose asyncId/asyncDir with status.json, events.jsonl, output logs, and status via { action: "status", id }. Include output paths and residual risks when reporting results.`;
+• Artifacts/status essentials: chain outputs live under {chain_dir}; async runs expose asyncId/asyncDir with status.json, events.jsonl, output logs, and status via { action: "status", id }. Normal delegated results are reference-first: completion returns saved-output references plus lifecycle/status information, not child prose — inspect full output through the saved output path, async status/transcript, or resume. Include output paths and residual risks when reporting results.
+
+${SUBAGENT_PARENT_ROUTING_GUIDANCE}`;
 
 export const FULL_SUBAGENT_TOOL_DESCRIPTION = `To delegate work, call with { agent, task }, { tasks }, or { chain }; omit action. Use action only for management/control actions listed below.
 
@@ -37,8 +51,9 @@ CHAIN EXAMPLES (quick reference for the nested schema):
 • Parallel fan-out: { chain: [{parallel: [{agent:"agent-a", task:"Check part of {task}", count: 3}]}] }
 • Mixed: { chain: [{agent:"agent-a", task:"Research {task}"}, {checkpoint:"review", message:"Approve implementation?"}, {parallel: [{agent:"agent-b", task:"Review {previous}", count: 2}]}, {agent:"agent-c", task:"Summarize {previous}"}] }
 
-MANAGEMENT (use action field, omit agent/task/chain/tasks):
+MANAGEMENT (use action field; omit agent/chain/tasks — the sole field exception is list's optional advisory task):
 • { action: "list" } - discover executable agents/chains
+• { action: "list", task: "..." } - same, plus optional task-aware advisory routing: recommends one canonical agent (implementation or read-only) for the task, or explains why none is safe. It only recommends and never launches; to proceed, explicitly call subagent with the recommended canonical agent name and the task.
 • { action: "get", agent: "name" } - full detail; packaged agents use dotted runtime names like "package.agent"
 • { action: "models", agent?: "name" } - show the runtime-loaded builtin subagent model mapping, optionally filtered to one builtin
 • { action: "watchdog.status" | "watchdog.check" | "watchdog.recommend-model" } - inspect the opt-in subagent watchdog and its strong complementary model recommendation
@@ -47,10 +62,10 @@ MANAGEMENT (use action field, omit agent/task/chain/tasks):
 • acceptanceRole affects inferred acceptance only, never tool access. Explicit task mutation/no-edit intent wins; omission preserves name heuristics. Update with false or an empty string to clear it.
 • { action: "update", agent: "code-analysis.custom-agent", config: { package: "analysis", ... } } - merge
 • { action: "delete", agent: "code-analysis.custom-agent" }
-• { action: "eject", agent: "commentator", agentScope?: "user" | "project" } - copy a bundled/package agent to user/project scope as an editable custom file that shadows the original (default scope: user)
-• { action: "disable", agent: "commentator", agentScope?: "user" | "project" } - hide any agent from runtime discovery via a reversible settings override (default scope: user)
-• { action: "enable", agent: "commentator", agentScope?: "user" | "project" } - remove a disabled override and restore discovery
-• { action: "reset", agent: "commentator", agentScope?: "user" | "project" } - delete the scope's custom agent file and/or settings override, restoring the bundled default
+• { action: "eject", agent: "agent-name", agentScope?: "user" | "project" } - copy a bundled/package agent to user/project scope as an editable custom file that shadows the original (default scope: user)
+• { action: "disable", agent: "agent-name", agentScope?: "user" | "project" } - hide any agent from runtime discovery via a reversible settings override (default scope: user)
+• { action: "enable", agent: "agent-name", agentScope?: "user" | "project" } - remove a disabled override and restore discovery
+• { action: "reset", agent: "agent-name", agentScope?: "user" | "project" } - delete the scope's custom agent file and/or settings override, restoring the bundled default
 • { action: "grant-spawn-budget", additional: 10 } - add bounded capacity from the root interactive parent after native user confirmation; grants are rejected while children are active and cumulative grants cannot exceed the original configured cap
 • Use chainName for chain operations; packaged chains also use dotted runtime names
 
@@ -88,7 +103,8 @@ EXECUTE:
 • If list shows proactive skill subagent suggestions, use a small fresh-context fanout only when the task is broad enough.
 
 MANAGE / CONTROL:
-• Use action without execution fields: list, get, models, create, update, delete, eject, disable, enable, reset, grant-spawn-budget, doctor, watchdog.status, watchdog.check, watchdog.recommend-model, watchdog.configure.
+• Use action without execution fields (list may add an optional advisory task): list, get, models, create, update, delete, eject, disable, enable, reset, grant-spawn-budget, doctor, watchdog.status, watchdog.check, watchdog.recommend-model, watchdog.configure.
+• { action: "list", task: "..." } optionally appends task-aware advisory routing that recommends a canonical agent but never launches; execute the recommended agent explicitly in a separate call.
 • Agent acceptanceRole (read-only or writer) affects inferred acceptance only, never tools. Explicit task intent wins; omission keeps name heuristics. Update with false or an empty string to clear it.
 • Async control actions: status, interrupt, stop, resume, steer, append-step, approve-checkpoint, reject-checkpoint. Use stop with an id for current-session top-level async runs. Use status view:"fleet" for active-run overview, view:"transcript" to tail child output, steer for acknowledged top-level live async guidance, and resume for paused/completed/failed revival or a routed nested follow-up. Stopped runs are non-resumable. Steering delivery means Pi accepted the correlated user input, not model compliance; use index for a specific child.
 • Opt-in schedule actions: schedule, schedule-list, schedule-status, schedule-cancel. Schedule only explicit delayed runs the user asked for.
@@ -98,6 +114,7 @@ ASYNC / WAIT:
 • Status and artifacts live under asyncId/asyncDir with status.json, events.jsonl, output logs, session files, and { action:"status", id:"..." }.
 
 SAFETY:
+• Parent-only routing: call { action: "list" } before any execution and select only an executable entry using its current role, context, and tool metadata. Keep tiny targeted reads and simple answers local; send broad local investigation, external research, and mutation/implementation work to a capable delegated agent. The parent remains the decision-maker and normally the sole writer.
 • Ordinary child subagents are not orchestrators and must not run subagents. Only explicit fanout children may use child-safe subagent, still bounded by depth/session limits.
 • Keep one writer per cwd/worktree. Use fresh read-only review/validation fanout, then synthesize and apply fixes from the parent unless isolated worktrees were intentionally requested.`;
 

package/dist/extensions/pi-subagents/src/runs/background/async-execution.ts

@@ -686,9 +686,19 @@ export function buildAsyncRunnerSteps(id: string, params: AsyncRunnerStepBuildPa
 		const isFirstProgressAgent = behavior.progress && !progressPrecreated && !progressInstructionCreated;
 		if (behavior.progress) progressInstructionCreated = true;
 		const progressInstructions = buildChainInstructions({ ...behavior, output: false, reads: false }, progressDir, isFirstProgressAgent);
-		const outputPath = resolveSingleOutputPath(behavior.output, ctx.cwd, instructionCwd, outputBaseDir);
+		const explicitOutput = typeof behavior.output === "string" ? behavior.output : undefined;
+		// Omitted output generates a collision-safe per-child durable path
+		// `<asyncDir>/outputs/<flat-index>-<agent>.md`; omitted outputMode resolves
+		// to file-only whenever an output path is active. Explicit paths,
+		// `output: false`, and explicit `outputMode: "inline"` are preserved.
+		const outputPath = explicitOutput
+			? resolveSingleOutputPath(explicitOutput, ctx.cwd, instructionCwd, outputBaseDir)
+			: behavior.output === false && s.output !== false && s.output !== "false" && flatIndex !== undefined
+				? path.join(asyncDir, "outputs", `${flatIndex}-${s.agent}.md`)
+				: undefined;
 		if (!namespaceOutputPath) systemPrompt = injectOutputPathSystemPrompt(systemPrompt, outputPath, a);
-		const validationError = validateFileOnlyOutputMode(behavior.outputMode, outputPath, `Async step (${s.agent})`);
+		const effectiveOutputMode = s.outputMode ?? (outputPath ? "file-only" : "inline");
+		const validationError = validateFileOnlyOutputMode(effectiveOutputMode, outputPath, `Async step (${s.agent})`);
 		if (validationError) throw new AsyncStartValidationError(validationError);
 		let taskTemplate = s.task ?? "{previous}";
 		taskTemplate = taskTemplate.replace(/\{task\}/g, originalTask ?? "");
@@ -751,7 +761,7 @@ export function buildAsyncRunnerSteps(id: string, params: AsyncRunnerStepBuildPa
 			skills: resolvedSkills.map((r) => r.name),
 			outputPath,
 			...(namespaceOutputPath ? { namespaceOutputPath: true } : {}),
-			outputMode: behavior.outputMode,
+			outputMode: effectiveOutputMode,
 			sessionFile,
 			maxSubagentDepth: resolveChildMaxSubagentDepth(maxSubagentDepth, a.maxSubagentDepth),
 			waitToolEnabled: params.waitToolEnabled,
@@ -1228,9 +1238,17 @@ export function executeAsyncSingle(
 	}
 
 	const effectiveOutput = normalizeSingleOutputOverride(params.output, agentConfig.output);
-	const outputPath = resolveSingleOutputPath(effectiveOutput, ctx.cwd, runnerCwd, params.outputBaseDir ?? (artifactsDir ? path.join(artifactsDir, "outputs", id) : undefined));
+	// Omitted output resolves to a generated per-run durable path
+	// `<asyncDir>/outputs/0-<agent>.md`; omitted outputMode resolves to file-only
+	// whenever an output path is active. Explicit paths, `output: false`, and
+	// explicit `outputMode: "inline"` are preserved exactly.
+	const outputPath = typeof effectiveOutput === "string"
+		? resolveSingleOutputPath(effectiveOutput, ctx.cwd, runnerCwd, params.outputBaseDir ?? (artifactsDir ? path.join(artifactsDir, "outputs", id) : undefined))
+		: effectiveOutput === false
+			? undefined
+			: path.join(asyncDir, "outputs", `0-${agent}.md`);
 	systemPrompt = injectOutputPathSystemPrompt(systemPrompt, outputPath, agentConfig);
-	const outputMode = params.outputMode ?? "inline";
+	const outputMode = params.outputMode ?? (outputPath ? "file-only" : "inline");
 	const validationError = validateFileOnlyOutputMode(outputMode, outputPath, `Async single run (${agent})`);
 	if (validationError) return formatAsyncStartError("single", validationError);
 	const taskWithOutputInstruction = injectSingleOutputInstruction(task, outputPath, agentConfig);

package/dist/extensions/pi-subagents/src/runs/background/notify.ts

@@ -192,6 +192,32 @@ function completionBatchKey(result: CompletionNotification): string {
 	return cwd ? `cwd:${cwd}` : "unknown";
 }
 
+/**
+ * Reference-first notification preview: compact child summaries built by the
+ * result watcher from each child's authoritative output path/log. Never uses
+ * `results[].output` or the run-level `summary` as parent-facing text; the run
+ * summary remains only a defensive fallback for legacy payloads without results.
+ */
+function buildReferenceFirstPreview(result: CompletionNotification): string {
+	const children = Array.isArray(result.results) ? result.results : [];
+	if (children.length === 0) {
+		return typeof result.summary === "string" ? result.summary : "";
+	}
+	if (children.length === 1) {
+		const childSummary = typeof children[0]?.summary === "string" && children[0].summary.trim()
+			? children[0].summary
+			: "(no output)";
+		return childSummary;
+	}
+	return children.map((child, index) => {
+		const agentLabel = typeof child?.agent === "string" ? child.agent : `step-${index + 1}`;
+		const childSummary = typeof child?.summary === "string" && child.summary.trim()
+			? child.summary
+			: "(no output)";
+		return `${index + 1}. ${agentLabel}\n${childSummary}`;
+	}).join("\n\n");
+}
+
 export function buildCompletionDetails(result: CompletionNotification): SubagentNotifyDetails {
 	const agent = result.agent ?? "unknown";
 	const summary = typeof result.summary === "string" ? result.summary : "";
@@ -229,7 +255,7 @@ export function buildCompletionDetails(result: CompletionNotification): Subagent
 		status,
 		...(result.source ? { source: result.source } : {}),
 		...(taskInfo ? { taskInfo } : {}),
-		resultPreview: summary,
+		resultPreview: buildReferenceFirstPreview(result),
 		...(typeof result.durationMs === "number" ? { durationMs: result.durationMs } : {}),
 		...(handoffPath ? { handoffPath } : {}),
 		...(session ? { sessionLabel: session.label, sessionValue: session.value } : {}),

package/dist/extensions/pi-subagents/src/runs/background/result-watcher.ts

@@ -20,6 +20,7 @@ import {
 } from "../../intercom/result-intercom.ts";
 import { projectNestedRegistryForRoot, sanitizeSummary } from "../shared/nested-events.ts";
 import { resolveWatchPath } from "../../shared/utils.ts";
+import { formatBoundedPersistenceFallback, formatSavedOutputReference } from "../shared/single-output.ts";
 import type { CompletionNotifier, CompletionNotification } from "./notify.ts";
 
 const WATCHER_RESTART_DELAY_MS = 3000;
@@ -46,10 +47,14 @@ type ResultWatcherDeps = {
 type ResultFileChild = {
 	agent?: string;
 	output?: string;
+	/** Authoritative durable output location: explicit/generated saved path or async output log. */
+	outputPath?: string;
+	savedOutputPath?: string;
 	outputState?: SubagentOutputState;
 	error?: string;
 	success?: boolean;
 	state?: string;
+	exitCode?: number | null;
 	interrupted?: boolean;
 	timedOut?: boolean;
 	stopped?: boolean;
@@ -92,6 +97,57 @@ function isNotFound(error: unknown): boolean {
 	return errorCode(error) === "ENOENT";
 }
 
+/**
+ * Resolve the authoritative output location for one async child: explicit/generated
+ * saved output path first, else the persisted per-child output log
+ * (`asyncDir/output-<flat-index>.log`). Legacy result files without saved-path
+ * fields fall back to the output log when the run directory is known.
+ */
+function childOutputPath(data: ResultFileData, result: ResultFileChild | undefined, index: number): string | undefined {
+	if (typeof result?.outputPath === "string" && result.outputPath.trim()) return result.outputPath;
+	if (typeof result?.savedOutputPath === "string" && result.savedOutputPath.trim()) return result.savedOutputPath;
+	if (typeof data.asyncDir === "string" && data.asyncDir.trim()) return path.join(data.asyncDir, `output-${index}.log`);
+	return undefined;
+}
+
+/**
+ * Reference-only child summary for async delivery: the saved-output reference
+ * (or output-log reference) plus process error/status for failed children. Never
+ * emits `results[].output` or the run `summary` as parent-facing text; when the
+ * output location is absent or unreadable, a bounded fallback is used instead.
+ */
+function buildChildReferenceSummary(fsApi: ResultWatcherFs, input: {
+	outputPath: string | undefined;
+	outputText: string;
+	exitCode: number;
+	error?: string;
+}): string {
+	const statusError = input.exitCode !== 0 && input.error ? input.error : undefined;
+	if (input.outputPath) {
+		try {
+			const content = fsApi.readFileSync(input.outputPath, "utf-8");
+			const ref = formatSavedOutputReference(input.outputPath, content);
+			return statusError ? `${statusError}\n\n${ref.message}` : ref.message;
+		} catch (error) {
+			const fallback = formatBoundedPersistenceFallback({
+				error: `Failed to read saved output: ${error instanceof Error ? error.message : String(error)}`,
+				outputPath: input.outputPath,
+				fullOutput: input.outputText,
+				exitCode: input.exitCode,
+				processError: input.error,
+			});
+			return statusError ? `${statusError}\n\n${fallback}` : fallback;
+		}
+	}
+	const fallback = formatBoundedPersistenceFallback({
+		error: "No saved output path is available for this child.",
+		fullOutput: input.outputText,
+		exitCode: input.exitCode,
+		processError: input.error,
+	});
+	return statusError ? `${statusError}\n\n${fallback}` : fallback;
+}
+
 function shouldPoll(error: unknown): boolean {
 	const code = errorCode(error);
 	return code === "EMFILE" || code === "ENOSPC";
@@ -180,14 +236,16 @@ export function createResultWatcher(
 			const hasResultChildren = Array.isArray(data.results) && data.results.length > 0;
 			const resultChildren: ResultFileChild[] = hasResultChildren
 				? data.results!
-				: [{ agent: data.agent ?? undefined, output: data.summary, outputState: "unknown", success: data.success }];
+				: [{ agent: data.agent ?? undefined, outputPath: childOutputPath(data, undefined, 0), outputState: "unknown", success: data.success }];
 			const normalizedChildren = attachNestedChildrenToResultChildren(runId, resultChildren.map((result = {}, index): SubagentResultIntercomChild => {
 				const baseOutput = hasResultChildren ? result.output : result.output ?? data.summary;
-				const hasRealOutput = typeof baseOutput === "string" && baseOutput.trim().length > 0;
-				const output = hasRealOutput ? baseOutput : "(no output)";
-				const summary = result.success === false && result.error
-					? `${result.error}${hasRealOutput ? `\n\nOutput:\n${baseOutput}` : ""}`
-					: output;
+				const outputText = typeof baseOutput === "string" ? baseOutput : "";
+				const summary = buildChildReferenceSummary(fsApi, {
+					outputPath: childOutputPath(data, result, index),
+					outputText,
+					exitCode: result.success === false ? 1 : result.success === true ? 0 : typeof result.exitCode === "number" ? result.exitCode : data.success === false ? 1 : 0,
+					error: result.error ?? (result.success === false ? (typeof data.error === "string" ? data.error : undefined) : undefined),
+				});
 				const sessionPath = result.sessionFile ?? (resultChildren.length === 1 ? data.sessionFile : undefined);
 				const childNestedChildren = sanitizeNestedResultChildren(result.children, resultPath, `results[${index}].children`);
 				const childState = result.state === "paused" || result.state === "stopped"

package/dist/extensions/pi-subagents/src/runs/background/subagent-runner.ts

@@ -1476,7 +1476,11 @@ async function runSingleStep(
 
 	const rawOutput = finalResult?.finalOutput ?? "";
 	const outputForPersistence = stripAcceptanceReport(rawOutput);
-	const resolvedOutput = step.outputPath && finalResult?.exitCode === 0
+	// Persist whenever an output path is configured and meaningful output exists,
+	// not only for successful runs: failed children keep a readable result file
+	// and a saved-output reference instead of raw inline output. Synthetic
+	// failures without output stay "absent" and are not promoted to a reference.
+	const resolvedOutput = step.outputPath && (outputForPersistence.trim() || (finalResult?.exitCode ?? 1) === 0)
 		? resolveSingleOutput(step.outputPath, outputForPersistence, finalOutputSnapshot)
 		: { fullOutput: outputForPersistence };
 	const output = stripAcceptanceReport(resolvedOutput.fullOutput);
@@ -1515,6 +1519,9 @@ async function runSingleStep(
 		savedPath: resolvedOutput.savedPath,
 		outputReference,
 		saveError: resolvedOutput.saveError,
+		error: finalResult?.error
+			?? (finalResult?.stopped ? ctx.stopMessage ?? "Subagent stopped by user." : undefined)
+			?? (finalResult?.timedOut ? ctx.timeoutMessage ?? "Subagent timed out." : undefined),
 	});
 	outputForSummary = finalizedOutput.displayOutput;
 	const acceptance = step.effectiveAcceptance && !finalResult?.stopped && !finalResult?.turnBudgetExceeded && !ctx.timeoutSignal?.aborted && !ctx.stopSignal?.aborted && !ctx.skipAcceptance?.()
@@ -1596,6 +1603,10 @@ async function runSingleStep(
 		context: step.context,
 		...(step.agentContract ? { agentContract: step.agentContract } : {}),
 		launchContractDigest: actualLaunchContractDigest,
+		// Authoritative durable output location for parent-facing delivery: the
+		// explicit/generated saved output path when present, otherwise the async
+		// per-child output log (`asyncDir/output-<flat-index>.log`).
+		outputPath: step.outputPath ?? ctx.outputFile,
 		output: outputForSummary,
 		outputState,
 		exitCode: effectiveFinalExitCode,
@@ -3388,6 +3399,7 @@ async function runSubagent(
 					launchResolvedExtensions: pr.launchResolvedExtensions,
 					runtimeAcknowledgedExtensions: pr.runtimeAcknowledgedExtensions,
 					output: pr.output,
+					outputPath: pr.outputPath,
 					outputState: pr.outputState,
 					error: pr.error,
 					protocolError: pr.protocolError,
@@ -3797,6 +3809,7 @@ async function runSubagent(
 						launchContractDigest: pr.launchContractDigest,
 						launchResolvedExtensions: pr.launchResolvedExtensions,
 						output: pr.output,
+						outputPath: pr.outputPath,
 						outputState: pr.outputState,
 						error: pr.error,
 						protocolError: pr.protocolError,
@@ -3984,6 +3997,7 @@ async function runSubagent(
 				launchResolvedExtensions: singleResult.launchResolvedExtensions,
 				runtimeAcknowledgedExtensions: singleResult.runtimeAcknowledgedExtensions,
 				output: stopped || childStopped ? stopMessage : timedOut ? (timeoutMessage ?? "Subagent timed out.") : singleResult.output,
+				outputPath: singleResult.outputPath,
 				outputState: singleResult.outputState,
 				error: stopped || childStopped ? stopMessage : timedOut ? (timeoutMessage ?? "Subagent timed out.") : singleResult.error,
 				protocolError: singleResult.protocolError,
@@ -4311,6 +4325,7 @@ async function runSubagent(
 			results: results.map((r) => ({
 				agent: r.agent,
 				context: r.context,
+				outputPath: r.outputPath,
 				output: r.output,
 				outputState: r.outputState,
 				error: r.error,

package/dist/extensions/pi-subagents/src/runs/foreground/chain-execution.ts

@@ -91,6 +91,34 @@ import { usageBudgetExceededMessage, usageBudgetState } from "../shared/usage-bu
 import type { ContextMode } from "../shared/context-mode.ts";
 import type { ResolvedSubagentCapabilityCeiling } from "../shared/capability-ceiling.ts";
 
+/**
+ * Resolve a chain step's output path and effective output mode.
+ *
+ * Explicit `output` paths pass through unchanged (absolute as-is, relative under
+ * the chain dir). Omitted output generates a collision-safe per-child durable
+ * path `<chainDir>/outputs/<flat-index>-<agent>.md` unless the caller explicitly
+ * used `output: false`. Omitted `outputMode` resolves to `file-only` when an
+ * output path is active; explicit `outputMode: "inline"` is preserved exactly.
+ */
+function resolveChainStepOutput(input: {
+	behaviorOutput: string | false;
+	rawOutput: string | false | undefined;
+	rawOutputMode: "inline" | "file-only" | undefined;
+	chainDir: string;
+	flatIndex: number;
+	agent: string;
+}): { outputPath?: string; outputMode: "inline" | "file-only" } {
+	const explicit = typeof input.behaviorOutput === "string" ? input.behaviorOutput : undefined;
+	let outputPath: string | undefined;
+	if (explicit) {
+		outputPath = path.isAbsolute(explicit) ? explicit : path.join(input.chainDir, explicit);
+	} else if (input.behaviorOutput === false && input.rawOutput !== false && input.rawOutput !== "false") {
+		outputPath = path.join(input.chainDir, "outputs", `${input.flatIndex}-${input.agent}.md`);
+	}
+	return { outputPath, outputMode: input.rawOutputMode ?? (outputPath ? "file-only" : "inline") };
+}
+
+
 interface ChainExecutionDetailsInput {
 	results: SingleResult[];
 	includeProgress?: boolean;
@@ -353,9 +381,16 @@ async function runParallelChainTasks(input: ParallelChainRunInput): Promise<Sing
 				? input.worktreeSetup.worktrees[taskIndex]!.agentCwd
 				: resolveChildCwd(input.cwd ?? input.ctx.cwd, task.cwd);
 
-			const outputPath = typeof behavior.output === "string"
-				? (path.isAbsolute(behavior.output) ? behavior.output : path.join(input.chainDir, behavior.output))
-				: undefined;
+			const resolvedTaskOutput = resolveChainStepOutput({
+				behaviorOutput: behavior.output,
+				rawOutput: task.output,
+				rawOutputMode: task.outputMode,
+				chainDir: input.chainDir,
+				flatIndex: childIndex,
+				agent: task.agent,
+			});
+			const outputPath = resolvedTaskOutput.outputPath;
+			const effectiveOutputMode = resolvedTaskOutput.outputMode;
 			taskStr = injectSingleOutputInstruction(taskStr, outputPath, taskAgentConfig);
 			const interruptController = new AbortController();
 			if (input.foregroundControl) {
@@ -399,7 +434,7 @@ async function runParallelChainTasks(input: ParallelChainRunInput): Promise<Sing
 				artifactsDir: input.artifactConfig.enabled ? input.artifactsDir : undefined,
 				artifactConfig: input.artifactConfig,
 				outputPath,
-				outputMode: behavior.outputMode,
+				outputMode: effectiveOutputMode,
 				maxSubagentDepth,
 				controlConfig: input.controlConfig,
 				onControlEvent: input.onControlEvent,
@@ -793,10 +828,16 @@ ${step.message}` : ""}` }],
 					.map((behavior, taskIndex) => suppressProgressForReadOnlyTask(behavior, parallelTemplates[taskIndex] ?? step.parallel[taskIndex]?.task, originalTask));
 				for (let taskIndex = 0; taskIndex < step.parallel.length; taskIndex++) {
 					const behavior = parallelBehaviors[taskIndex]!;
-					const outputPath = typeof behavior.output === "string"
-						? (path.isAbsolute(behavior.output) ? behavior.output : path.join(chainDir, behavior.output))
-						: undefined;
-					const validationError = validateFileOnlyOutputMode(behavior.outputMode, outputPath, `Parallel chain step ${stepIndex + 1} task ${taskIndex + 1} (${step.parallel[taskIndex]!.agent})`);
+					const task = step.parallel[taskIndex]!;
+					const resolvedOutput = resolveChainStepOutput({
+						behaviorOutput: behavior.output,
+						rawOutput: task.output,
+						rawOutputMode: task.outputMode,
+						chainDir,
+						flatIndex: globalTaskIndex + taskIndex,
+						agent: task.agent,
+					});
+					const validationError = validateFileOnlyOutputMode(resolvedOutput.outputMode, resolvedOutput.outputPath, `Parallel chain step ${stepIndex + 1} task ${taskIndex + 1} (${task.agent})`);
 					if (validationError) return buildChainExecutionErrorResult(validationError, makeDetailsInput({ currentStepIndex: stepIndex, currentFlatIndex: globalTaskIndex + taskIndex }));
 				}
 				progressCreated = ensureParallelProgressFile(chainDir, progressCreated, parallelBehaviors);
@@ -1049,10 +1090,16 @@ ${step.message}` : ""}` }],
 
 			for (let taskIndex = 0; taskIndex < dynamicParallelStep.parallel.length; taskIndex++) {
 				const behavior = parallelBehaviors[taskIndex]!;
-				const outputPath = typeof behavior.output === "string"
-					? (path.isAbsolute(behavior.output) ? behavior.output : path.join(chainDir, behavior.output))
-					: undefined;
-				const validationError = validateFileOnlyOutputMode(behavior.outputMode, outputPath, `Dynamic chain step ${stepIndex + 1} item ${taskIndex + 1} (${dynamicParallelStep.parallel[taskIndex]!.agent})`);
+				const task = dynamicParallelStep.parallel[taskIndex]!;
+				const resolvedOutput = resolveChainStepOutput({
+					behaviorOutput: behavior.output,
+					rawOutput: task.output,
+					rawOutputMode: task.outputMode,
+					chainDir,
+					flatIndex: globalTaskIndex + taskIndex,
+					agent: task.agent,
+				});
+				const validationError = validateFileOnlyOutputMode(resolvedOutput.outputMode, resolvedOutput.outputPath, `Dynamic chain step ${stepIndex + 1} item ${taskIndex + 1} (${task.agent})`);
 				if (validationError) {
 					dynamicGroupStatuses[stepIndex] = { status: "failed", error: validationError };
 					return buildChainExecutionErrorResult(validationError, makeDetailsInput({ currentStepIndex: stepIndex, currentFlatIndex: globalTaskIndex + taskIndex }));
@@ -1289,11 +1336,18 @@ ${step.message}` : ""}` }],
 				{ scope: modelScope },
 			);
 
-			const outputPath = typeof behavior.output === "string"
-				? (path.isAbsolute(behavior.output) ? behavior.output : path.join(chainDir, behavior.output))
-				: undefined;
+			const resolvedStepOutput = resolveChainStepOutput({
+				behaviorOutput: behavior.output,
+				rawOutput: stepOverride.output,
+				rawOutputMode: seqStep.outputMode,
+				chainDir,
+				flatIndex: globalTaskIndex,
+				agent: seqStep.agent,
+			});
+			const outputPath = resolvedStepOutput.outputPath;
+			const effectiveOutputMode = resolvedStepOutput.outputMode;
 			stepTask = injectSingleOutputInstruction(stepTask, outputPath, agentConfig);
-			const validationError = validateFileOnlyOutputMode(behavior.outputMode, outputPath, `Chain step ${stepIndex + 1} (${seqStep.agent})`);
+			const validationError = validateFileOnlyOutputMode(effectiveOutputMode, outputPath, `Chain step ${stepIndex + 1} (${seqStep.agent})`);
 			if (validationError) {
 				return buildChainExecutionErrorResult(validationError, makeDetailsInput({ currentStepIndex: stepIndex, currentFlatIndex: globalTaskIndex }));
 			}
@@ -1339,7 +1393,7 @@ ${step.message}` : ""}` }],
 					dynamicChildren,
 					dynamicGroupStatuses,
 				});
-				r = await runSync(ctx.cwd, agents, seqStep.agent, stepTask, {
+			r = await runSync(ctx.cwd, agents, seqStep.agent, stepTask, {
 				parentSessionId: ctx.sessionManager.getSessionId() ?? undefined,
 				capabilityCeiling: params.capabilityCeiling,
 				context: params.contextForAgent?.(seqStep.agent),
@@ -1358,7 +1412,7 @@ ${step.message}` : ""}` }],
 				artifactsDir: artifactConfig.enabled ? artifactsDir : undefined,
 				artifactConfig,
 				outputPath,
-				outputMode: behavior.outputMode,
+				outputMode: effectiveOutputMode,
 				maxSubagentDepth,
 				controlConfig,
 				onControlEvent,

package/dist/extensions/pi-subagents/src/runs/foreground/execution.ts

@@ -62,7 +62,7 @@ import { resolveEffectiveThinking } from "../../shared/model-info.ts";
 import { 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 { captureSingleOutputSnapshot, extractChildWrittenOutput, formatSavedOutputReference, injectOutputPathSystemPrompt, resolveSingleOutput, validateFileOnlyOutputMode, type SingleOutputSnapshot } from "../shared/single-output.ts";
+import { captureSingleOutputSnapshot, extractChildWrittenOutput, formatBoundedPersistenceFallback, formatSavedOutputReference, injectOutputPathSystemPrompt, resolveSingleOutput, validateFileOnlyOutputMode, type SingleOutputSnapshot } from "../shared/single-output.ts";
 import {
 	buildModelCandidates,
 	formatModelAttemptNote,
@@ -1282,7 +1282,12 @@ async function runSingleAttempt(
 			reason: "completion_guard",
 		}));
 	}
-		if (options.outputPath && result.exitCode === 0) {
+		// Persist whenever an output path is configured and meaningful child output
+	// exists, not only for successful runs: failed children with output keep a
+	// readable result file and a saved-output reference instead of raw inline
+	// output. Synthetic failures without output (startup errors, empty responses)
+	// stay outputState "absent" and are not promoted to a bogus saved reference.
+	if (options.outputPath && (fullOutput.trim() || result.exitCode === 0)) {
 			const resolvedOutput = resolveSingleOutput(options.outputPath, fullOutput, shared.outputSnapshot);
 			fullOutput = stripAcceptanceReport(resolvedOutput.fullOutput);
 			result.savedOutputPath = resolvedOutput.savedPath;
@@ -1295,9 +1300,18 @@ async function runSingleAttempt(
 		artifactOutputByResult.set(result, fullOutput);
 		acceptanceOutputByResult.set(result, acceptanceOutput);
 	result.outputMode = options.outputMode ?? "inline";
-	result.finalOutput = options.outputMode === "file-only" && result.savedOutputPath && result.outputReference
-		? result.outputReference.message
-		: fullOutput;
+	const hasSavedReference = result.savedOutputPath && result.outputReference ? true : false;
+	result.finalOutput = hasSavedReference && (options.outputMode === "file-only" || result.exitCode !== 0)
+		? result.outputReference!.message
+		: result.outputSaveError && options.outputPath
+			? formatBoundedPersistenceFallback({
+				error: result.outputSaveError,
+				outputPath: options.outputPath,
+				fullOutput,
+				exitCode: result.exitCode,
+				processError: result.error,
+			})
+			: fullOutput;
 	result.controlEvents = allControlEvents.length ? allControlEvents : undefined;
 	if (options.onUpdate) {
 		const finalText = result.finalOutput || result.error || "(no output)";