pi-subagents 0.21.2 → 0.21.4

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

@@ -7,7 +7,7 @@ import type { Message } from "@mariozechner/pi-ai";
 import { writeAtomicJson } from "../../shared/atomic-json.ts";
 import { appendJsonl, getArtifactPaths } from "../../shared/artifacts.ts";
 import { getPiSpawnCommand } from "../shared/pi-spawn.ts";
-import { captureSingleOutputSnapshot, resolveSingleOutput } from "../shared/single-output.ts";
+import { captureSingleOutputSnapshot, finalizeSingleOutput, formatSavedOutputReference, resolveSingleOutput } from "../shared/single-output.ts";
 import {
 	type ActivityState,
 	type ArtifactConfig,
@@ -662,19 +662,21 @@ async function runSingleStep(
 		? resolveSingleOutput(step.outputPath, rawOutput, outputSnapshot)
 		: { fullOutput: rawOutput };
 	const output = resolvedOutput.fullOutput;
+	const outputReference = resolvedOutput.savedPath ? formatSavedOutputReference(resolvedOutput.savedPath, output) : undefined;
 	let outputForSummary = output;
 	if (attemptNotes.length > 0) {
 		outputForSummary = `${attemptNotes.join("\n")}\n\n${outputForSummary}`.trim();
 	}
-	if (resolvedOutput.savedPath) {
-		outputForSummary = outputForSummary
-			? `${outputForSummary}\n\nOutput saved to: ${resolvedOutput.savedPath}`
-			: `Output saved to: ${resolvedOutput.savedPath}`;
-	} else if (resolvedOutput.saveError && step.outputPath && finalResult?.exitCode === 0) {
-		outputForSummary = outputForSummary
-			? `${outputForSummary}\n\nFailed to save output to: ${step.outputPath}\n${resolvedOutput.saveError}`
-			: `Failed to save output to: ${step.outputPath}\n${resolvedOutput.saveError}`;
-	}
+	const finalizedOutput = finalizeSingleOutput({
+		fullOutput: outputForSummary,
+		outputPath: step.outputPath,
+		outputMode: step.outputMode,
+		exitCode: finalResult?.exitCode ?? 1,
+		savedPath: resolvedOutput.savedPath,
+		outputReference,
+		saveError: resolvedOutput.saveError,
+	});
+	outputForSummary = finalizedOutput.displayOutput;
 
 	if (artifactPaths && ctx.artifactConfig?.enabled !== false) {
 		if (ctx.artifactConfig?.includeOutput !== false) {

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

@@ -240,6 +240,7 @@ export class ChainClarifyComponent implements Component {
 
 		return {
 			output: override.output !== undefined ? override.output : base.output,
+			outputMode: base.outputMode,
 			reads: override.reads !== undefined ? override.reads : base.reads,
 			progress: override.progress !== undefined ? override.progress : base.progress,
 			skills: override.skills !== undefined ? override.skills : base.skills,
@@ -277,6 +278,7 @@ export class ChainClarifyComponent implements Component {
 			const template = this.templates[i] ?? "";
 			const step: ChainStepConfig = { agent: agent.name, task: template };
 			if (override?.output !== undefined) step.output = behavior.output;
+			if (behavior.outputMode !== "inline") step.outputMode = behavior.outputMode;
 			if (override?.reads !== undefined) step.reads = behavior.reads;
 			if (override?.model !== undefined) step.model = behavior.model;
 			if (override?.skills !== undefined) step.skills = behavior.skills;

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

@@ -55,6 +55,7 @@ import {
 	resolveChildMaxSubagentDepth,
 } from "../../shared/types.ts";
 import { resolveModelCandidate } from "../shared/model-fallback.ts";
+import { validateFileOnlyOutputMode } from "../shared/single-output.ts";
 
 interface ChainExecutionDetailsInput {
 	results: SingleResult[];
@@ -234,6 +235,7 @@ async function runParallelChainTasks(input: ParallelChainRunInput): Promise<Sing
 				artifactsDir: input.artifactConfig.enabled ? input.artifactsDir : undefined,
 				artifactConfig: input.artifactConfig,
 				outputPath,
+				outputMode: behavior.outputMode,
 				maxSubagentDepth,
 				controlConfig: input.controlConfig,
 				onControlEvent: input.onControlEvent,
@@ -412,6 +414,7 @@ export async function executeChain(params: ChainExecutionParams): Promise<ChainE
 
 		const stepOverrides: StepOverrides[] = seqSteps.map((step) => ({
 			output: step.output,
+			outputMode: step.outputMode,
 			reads: step.reads,
 			progress: step.progress,
 			skills: normalizeSkillInput(step.skill),
@@ -462,6 +465,7 @@ export async function executeChain(params: ChainExecutionParams): Promise<ChainE
 					task: result.templates[i]!,
 					...(override?.model ? { model: override.model } : {}),
 					...(override?.output !== undefined ? { output: override.output } : {}),
+					...("outputMode" in step && step.outputMode !== undefined ? { outputMode: step.outputMode } : {}),
 					...(override?.reads !== undefined ? { reads: override.reads } : {}),
 					...(override?.progress !== undefined ? { progress: override.progress } : {}),
 					...(override?.skills !== undefined ? { skill: override.skills } : {}),
@@ -533,6 +537,23 @@ export async function executeChain(params: ChainExecutionParams): Promise<ChainE
 			try {
 				const agentNames = step.parallel.map((task) => task.agent);
 				const parallelBehaviors = resolveParallelBehaviors(step.parallel, agents, stepIndex, chainSkills);
+				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})`);
+					if (validationError) return buildChainExecutionErrorResult(validationError, {
+						results,
+						includeProgress,
+						allProgress,
+						allArtifactPaths,
+						artifactsDir,
+						chainAgents,
+						totalSteps,
+						currentStepIndex: stepIndex,
+					});
+				}
 				progressCreated = ensureParallelProgressFile(chainDir, progressCreated, parallelBehaviors);
 				createParallelDirs(chainDir, stepIndex, step.parallel.length, agentNames);
 
@@ -664,6 +685,7 @@ export async function executeChain(params: ChainExecutionParams): Promise<ChainE
 			const tuiOverride = tuiBehaviorOverrides?.[stepIndex];
 			const stepOverride: StepOverrides = {
 				output: tuiOverride?.output !== undefined ? tuiOverride.output : seqStep.output,
+				outputMode: seqStep.outputMode,
 				reads: tuiOverride?.reads !== undefined ? tuiOverride.reads : seqStep.reads,
 				progress: tuiOverride?.progress !== undefined ? tuiOverride.progress : seqStep.progress,
 				skills:
@@ -701,6 +723,19 @@ export async function executeChain(params: ChainExecutionParams): Promise<ChainE
 			const outputPath = typeof behavior.output === "string"
 				? (path.isAbsolute(behavior.output) ? behavior.output : path.join(chainDir, behavior.output))
 				: undefined;
+			const validationError = validateFileOnlyOutputMode(behavior.outputMode, outputPath, `Chain step ${stepIndex + 1} (${seqStep.agent})`);
+			if (validationError) {
+				return buildChainExecutionErrorResult(validationError, {
+					results,
+					includeProgress,
+					allProgress,
+					allArtifactPaths,
+					artifactsDir,
+					chainAgents,
+					totalSteps,
+					currentStepIndex: stepIndex,
+				});
+			}
 			const maxSubagentDepth = resolveChildMaxSubagentDepth(params.maxSubagentDepth, agentConfig.maxSubagentDepth);
 			const interruptController = new AbortController();
 			if (foregroundControl) {
@@ -731,6 +766,7 @@ export async function executeChain(params: ChainExecutionParams): Promise<ChainE
 				artifactsDir: artifactConfig.enabled ? artifactsDir : undefined,
 				artifactConfig,
 				outputPath,
+				outputMode: behavior.outputMode,
 				maxSubagentDepth,
 				controlConfig,
 				onControlEvent,

package/src/runs/foreground/execution.ts

@@ -46,7 +46,7 @@ import { getPiSpawnCommand } from "../shared/pi-spawn.ts";
 import { createJsonlWriter } from "../../shared/jsonl-writer.ts";
 import { attachPostExitStdioGuard, trySignalChild } from "../../shared/post-exit-stdio-guard.ts";
 import { applyThinkingSuffix, buildPiArgs, cleanupTempDir } from "../shared/pi-args.ts";
-import { captureSingleOutputSnapshot, resolveSingleOutput, type SingleOutputSnapshot } from "../shared/single-output.ts";
+import { captureSingleOutputSnapshot, formatSavedOutputReference, resolveSingleOutput, validateFileOnlyOutputMode, type SingleOutputSnapshot } from "../shared/single-output.ts";
 import {
 	buildModelCandidates,
 	formatModelAttemptNote,
@@ -64,6 +64,8 @@ import {
 	summarizeRecentMutatingFailures,
 } from "../shared/long-running-guard.ts";
 
+const artifactOutputByResult = new WeakMap<SingleResult, string>();
+
 function emptyUsage(): Usage {
 	return { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, turns: 0 };
 }
@@ -97,7 +99,7 @@ function snapshotProgress(progress: AgentProgress): AgentProgress {
 function snapshotResult(result: SingleResult, progress: AgentProgress): SingleResult {
 	return {
 		...result,
-		messages: result.messages ? [...result.messages] : undefined,
+		messages: result.outputMode === "file-only" && result.savedOutputPath ? undefined : result.messages ? [...result.messages] : undefined,
 		usage: { ...result.usage },
 		skills: result.skills ? [...result.skills] : undefined,
 		attemptedModels: result.attemptedModels ? [...result.attemptedModels] : undefined,
@@ -112,6 +114,7 @@ function snapshotResult(result: SingleResult, progress: AgentProgress): SingleRe
 		progressSummary: result.progressSummary ? { ...result.progressSummary } : undefined,
 		artifactPaths: result.artifactPaths ? { ...result.artifactPaths } : undefined,
 		truncation: result.truncation ? { ...result.truncation } : undefined,
+		outputReference: result.outputReference ? { ...result.outputReference } : undefined,
 	};
 }
 
@@ -676,8 +679,15 @@ async function runSingleAttempt(
 		fullOutput = resolvedOutput.fullOutput;
 		result.savedOutputPath = resolvedOutput.savedPath;
 		result.outputSaveError = resolvedOutput.saveError;
+		if (resolvedOutput.savedPath) {
+			result.outputReference = formatSavedOutputReference(resolvedOutput.savedPath, fullOutput);
+		}
 	}
-	result.finalOutput = fullOutput;
+	artifactOutputByResult.set(result, fullOutput);
+	result.outputMode = options.outputMode ?? "inline";
+	result.finalOutput = options.outputMode === "file-only" && result.savedOutputPath && result.outputReference
+		? result.outputReference.message
+		: fullOutput;
 	result.controlEvents = allControlEvents.length ? allControlEvents : undefined;
 	if (options.onUpdate) {
 		const finalText = result.finalOutput || result.error || "(no output)";
@@ -717,6 +727,18 @@ export async function runSync(
 			error: `Unknown agent: ${agentName}`,
 		};
 	}
+	const outputModeValidationError = validateFileOnlyOutputMode(options.outputMode, options.outputPath, `Single run (${agentName})`);
+	if (outputModeValidationError) {
+		return {
+			agent: agentName,
+			task,
+			exitCode: 1,
+			messages: [],
+			usage: emptyUsage(),
+			outputMode: options.outputMode,
+			error: outputModeValidationError,
+		};
+	}
 
 	const shareEnabled = options.share === true;
 	const sessionEnabled = Boolean(options.sessionFile || options.sessionDir) || shareEnabled;
@@ -829,7 +851,7 @@ export async function runSync(
 	if (artifactPathsResult && options.artifactConfig?.enabled !== false) {
 		result.artifactPaths = artifactPathsResult;
 		if (options.artifactConfig?.includeOutput !== false) {
-			writeArtifact(artifactPathsResult.outputPath, result.finalOutput ?? "");
+			writeArtifact(artifactPathsResult.outputPath, artifactOutputByResult.get(result) ?? result.finalOutput ?? "");
 		}
 		if (options.artifactConfig?.includeMetadata !== false) {
 			writeMetadata(artifactPathsResult.metadataPath, {

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

@@ -10,6 +10,7 @@ import { executeChain } from "./chain-execution.ts";
 import { resolveExecutionAgentScope } from "../../agents/agent-scope.ts";
 import { handleManagementAction } from "../../agents/agent-management.ts";
 import { buildDoctorReport } from "../../extension/doctor.ts";
+import { clearPendingForegroundControlNotices } from "../../extension/control-notices.ts";
 import { runSync } from "./execution.ts";
 import { resolveModelCandidate } from "../shared/model-fallback.ts";
 import { aggregateParallelOutputs } from "../shared/parallel-utils.ts";
@@ -30,7 +31,7 @@ import { executeAsyncChain, executeAsyncSingle, isAsyncAvailable } from "../back
 import { createForkContextResolver } from "../../shared/fork-context.ts";
 import { applyIntercomBridgeToAgent, INTERCOM_BRIDGE_MARKER, resolveIntercomBridge, resolveIntercomSessionTarget, resolveSubagentIntercomTarget, type IntercomBridgeState } from "../../intercom/intercom-bridge.ts";
 import { formatControlIntercomMessage, formatControlNoticeMessage, resolveControlConfig, shouldNotifyControlEvent } from "../shared/subagent-control.ts";
-import { finalizeSingleOutput, injectSingleOutputInstruction, resolveSingleOutputPath } from "../shared/single-output.ts";
+import { finalizeSingleOutput, injectSingleOutputInstruction, resolveSingleOutputPath, validateFileOnlyOutputMode } from "../shared/single-output.ts";
 import { compactForegroundDetails, getSingleResultOutput, mapConcurrent, readStatus, resolveChildCwd } from "../../shared/utils.ts";
 import {
 	buildSubagentResultIntercomPayload,
@@ -85,6 +86,7 @@ interface TaskParam {
 	cwd?: string;
 	count?: number;
 	output?: string | boolean;
+	outputMode?: "inline" | "file-only";
 	reads?: string[] | boolean;
 	progress?: boolean;
 	model?: string;
@@ -117,6 +119,7 @@ export interface SubagentParamsLike {
 	model?: string;
 	skill?: string | string[] | boolean;
 	output?: string | boolean;
+	outputMode?: "inline" | "file-only";
 	agentScope?: unknown;
 	chainDir?: string;
 }
@@ -800,6 +803,7 @@ function runAsyncPath(data: ExecutionContextData, deps: ExecutorDeps): AgentTool
 			...(modelOverrides[index] ? { model: modelOverrides[index] } : {}),
 			...(skillOverrides[index] !== undefined ? { skill: skillOverrides[index] } : {}),
 			...(task.output === true ? (agentConfigs[index]?.output ? { output: agentConfigs[index]!.output } : {}) : task.output !== undefined ? { output: task.output } : {}),
+			...(task.outputMode !== undefined ? { outputMode: task.outputMode } : {}),
 			...(task.reads !== undefined && task.reads !== true ? { reads: task.reads } : {}),
 			...(task.progress !== undefined ? { progress: task.progress } : {}),
 		}));
@@ -867,6 +871,7 @@ function runAsyncPath(data: ExecutionContextData, deps: ExecutorDeps): AgentTool
 		}
 		const rawOutput = params.output !== undefined ? params.output : a.output;
 		const effectiveOutput: string | false | undefined = rawOutput === true ? a.output : (rawOutput as string | false | undefined);
+		const effectiveOutputMode = params.outputMode ?? "inline";
 		const normalizedSkills = normalizeSkillInput(params.skill);
 		const skills = normalizedSkills === false ? [] : normalizedSkills;
 		const maxSubagentDepth = resolveChildMaxSubagentDepth(currentMaxSubagentDepth, a.maxSubagentDepth);
@@ -886,6 +891,7 @@ function runAsyncPath(data: ExecutionContextData, deps: ExecutorDeps): AgentTool
 			sessionFile: sessionFileForIndex(0),
 			skills,
 			output: effectiveOutput,
+			outputMode: effectiveOutputMode,
 			modelOverride,
 			maxSubagentDepth,
 			worktreeSetupHook: deps.config.worktreeSetupHook,
@@ -1190,6 +1196,7 @@ async function runForegroundParallelTasks(input: ForegroundParallelRunInput): Pr
 			artifactConfig: input.artifactConfig,
 			maxOutput: input.maxOutput,
 			outputPath,
+			outputMode: behavior?.outputMode,
 			maxSubagentDepth: input.maxSubagentDepths[index],
 			controlConfig: input.controlConfig,
 			onControlEvent: input.onControlEvent,
@@ -1309,6 +1316,7 @@ async function runParallelPath(data: ExecutionContextData, deps: ExecutorDeps):
 	);
 	const behaviorOverrides: StepOverrides[] = tasks.map((task, index) => ({
 		...(task.output !== undefined ? { output: task.output === true ? agentConfigs[index]?.output ?? false : task.output } : {}),
+		...(task.outputMode !== undefined ? { outputMode: task.outputMode } : {}),
 		...(task.reads !== undefined && task.reads !== true ? { reads: task.reads } : {}),
 		...(task.progress !== undefined ? { progress: task.progress } : {}),
 		...(skillOverrides[index] !== undefined ? { skills: skillOverrides[index] } : {}),
@@ -1384,6 +1392,7 @@ async function runParallelPath(data: ExecutionContextData, deps: ExecutorDeps):
 				...(modelOverrides[i] ? { model: modelOverrides[i] } : {}),
 				...(skillOverrides[i] !== undefined ? { skill: skillOverrides[i] } : {}),
 				...(behaviorOverrides[i]?.output !== undefined ? { output: behaviorOverrides[i]!.output } : {}),
+				...(behaviorOverrides[i]?.outputMode !== undefined ? { outputMode: behaviorOverrides[i]!.outputMode } : {}),
 				...(behaviorOverrides[i]?.reads !== undefined ? { reads: behaviorOverrides[i]!.reads } : {}),
 				...(behaviorOverrides[i]?.progress !== undefined ? { progress: behaviorOverrides[i]!.progress } : {}),
 			}));
@@ -1435,6 +1444,12 @@ async function runParallelPath(data: ExecutionContextData, deps: ExecutorDeps):
 			worktreeSetup,
 		});
 		if (duplicateOutputError) return buildParallelModeError(duplicateOutputError);
+		for (let index = 0; index < tasks.length; index++) {
+			const taskCwd = resolveParallelTaskCwd(tasks[index]!, effectiveCwd, worktreeSetup, index);
+			const outputPath = resolveSingleOutputPath(behaviors[index]?.output, ctx.cwd, taskCwd);
+			const validationError = validateFileOnlyOutputMode(behaviors[index]?.outputMode, outputPath, `Parallel task ${index + 1} (${tasks[index]!.agent})`);
+			if (validationError) return buildParallelModeError(validationError);
+		}
 
 		const parallelProgressPrecreated = firstProgressIndex !== -1;
 		if (parallelProgressPrecreated) writeInitialProgressFile(effectiveCwd);
@@ -1585,6 +1600,7 @@ async function runSinglePath(data: ExecutionContextData, deps: ExecutorDeps): Pr
 	let skillOverride: string[] | false | undefined = normalizeSkillInput(params.skill);
 	const rawOutput = params.output !== undefined ? params.output : agentConfig.output;
 	let effectiveOutput: string | false | undefined = rawOutput === true ? agentConfig.output : (rawOutput as string | false | undefined);
+	const effectiveOutputMode = params.outputMode ?? "inline";
 	const currentMaxSubagentDepth = resolveCurrentMaxSubagentDepth(deps.config.maxSubagentDepth);
 	const maxSubagentDepth = resolveChildMaxSubagentDepth(currentMaxSubagentDepth, agentConfig.maxSubagentDepth);
 
@@ -1650,6 +1666,7 @@ async function runSinglePath(data: ExecutionContextData, deps: ExecutorDeps): Pr
 				sessionFile: sessionFileForIndex(0),
 				skills: skillOverride === false ? [] : skillOverride,
 				output: effectiveOutput,
+				outputMode: effectiveOutputMode,
 				modelOverride,
 				maxSubagentDepth,
 				worktreeSetupHook: deps.config.worktreeSetupHook,
@@ -1666,6 +1683,10 @@ async function runSinglePath(data: ExecutionContextData, deps: ExecutorDeps): Pr
 	}
 	const cleanTask = task;
 	const outputPath = resolveSingleOutputPath(effectiveOutput, ctx.cwd, effectiveCwd);
+	const validationError = validateFileOnlyOutputMode(effectiveOutputMode, outputPath, `Single run (${params.agent})`);
+	if (validationError) {
+		return { content: [{ type: "text", text: validationError }], isError: true, details: { mode: "single", results: [] } };
+	}
 	task = injectSingleOutputInstruction(task, outputPath);
 
 	let effectiveSkills: string[] | undefined;
@@ -1724,6 +1745,7 @@ async function runSinglePath(data: ExecutionContextData, deps: ExecutorDeps): Pr
 		artifactConfig,
 		maxOutput: params.maxOutput,
 		outputPath,
+		outputMode: effectiveOutputMode,
 		maxSubagentDepth,
 		onUpdate: forwardSingleUpdate,
 		controlConfig,
@@ -1757,8 +1779,10 @@ async function runSinglePath(data: ExecutionContextData, deps: ExecutorDeps): Pr
 		fullOutput,
 		truncatedOutput: r.truncation?.text,
 		outputPath,
+		outputMode: r.outputMode,
 		exitCode: r.exitCode,
 		savedPath: r.savedOutputPath,
+		outputReference: r.outputReference,
 		saveError: r.outputSaveError,
 	});
 	const details = compactForegroundDetails({
@@ -2067,6 +2091,7 @@ export function createSubagentExecutor(deps: ExecutorDeps): {
 			return toExecutionErrorResult(effectiveParams, error);
 		} finally {
 			if (foregroundControl) {
+				clearPendingForegroundControlNotices(deps.state, runId);
 				deps.state.foregroundControls.delete(runId);
 				if (deps.state.lastForegroundControlId === runId) {
 					deps.state.lastForegroundControlId = null;

package/src/runs/shared/parallel-utils.ts

@@ -13,6 +13,7 @@ export interface RunnerSubagentStep {
 	inheritSkills: boolean;
 	skills?: string[];
 	outputPath?: string;
+	outputMode?: "inline" | "file-only";
 	sessionFile?: string;
 	maxSubagentDepth?: number;
 }

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

@@ -1,5 +1,6 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
+import type { OutputMode, SavedOutputReference } from "../../shared/types.ts";
 
 export interface SingleOutputSnapshot {
 	exists: boolean;
@@ -25,6 +26,43 @@ export function injectSingleOutputInstruction(task: string, outputPath: string |
 	return `${task}\n\n---\n**Output:** Write your findings to: ${outputPath}`;
 }
 
+function countLines(text: string): number {
+	if (!text) return 0;
+	const newlineMatches = text.match(/\r\n|\r|\n/g);
+	return (newlineMatches?.length ?? 0) + (/[\r\n]$/.test(text) ? 0 : 1);
+}
+
+function formatByteSize(bytes: number): string {
+	if (bytes < 1024) return `${bytes} B`;
+	const units = ["KB", "MB", "GB", "TB"];
+	let value = bytes / 1024;
+	let unitIndex = 0;
+	while (value >= 1024 && unitIndex < units.length - 1) {
+		value /= 1024;
+		unitIndex++;
+	}
+	return `${value.toFixed(1)} ${units[unitIndex]}`;
+}
+
+export function formatSavedOutputReference(savedPath: string, fullOutput: string): SavedOutputReference {
+	const absolutePath = path.resolve(savedPath);
+	const bytes = Buffer.byteLength(fullOutput, "utf-8");
+	const lines = countLines(fullOutput);
+	return {
+		path: absolutePath,
+		bytes,
+		lines,
+		message: `Output saved to: ${absolutePath} (${formatByteSize(bytes)}, ${lines} ${lines === 1 ? "line" : "lines"}). Read this file if needed.`,
+	};
+}
+
+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".`;
+	}
+	return undefined;
+}
+
 export function captureSingleOutputSnapshot(outputPath: string | undefined): SingleOutputSnapshot | undefined {
 	if (!outputPath) return undefined;
 	try {
@@ -78,14 +116,20 @@ export function finalizeSingleOutput(params: {
 	fullOutput: string;
 	truncatedOutput?: string;
 	outputPath?: string;
+	outputMode?: OutputMode;
 	exitCode: number;
 	savedPath?: string;
+	outputReference?: SavedOutputReference;
 	saveError?: string;
-}): { displayOutput: string; savedPath?: string; saveError?: string } {
+}): { displayOutput: string; savedPath?: string; outputReference?: SavedOutputReference; saveError?: string } {
 	let displayOutput = params.truncatedOutput || params.fullOutput;
 	if (params.exitCode === 0 && params.savedPath) {
-		displayOutput += `\n\nOutput saved to: ${params.savedPath}`;
-		return { displayOutput, savedPath: params.savedPath };
+		const outputReference = params.outputReference ?? formatSavedOutputReference(params.savedPath, params.fullOutput);
+		if (params.outputMode === "file-only") {
+			return { displayOutput: outputReference.message, savedPath: params.savedPath, outputReference };
+		}
+		displayOutput += `\n\n${outputReference.message}`;
+		return { displayOutput, savedPath: params.savedPath, outputReference };
 	}
 	if (params.exitCode === 0 && params.saveError && params.outputPath) {
 		displayOutput += `\n\nFailed to save output to: ${params.outputPath}\n${params.saveError}`;

package/src/shared/settings.ts

@@ -6,7 +6,7 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import type { AgentConfig } from "../agents/agents.ts";
 import { normalizeSkillInput } from "../agents/skills.ts";
-import { CHAIN_RUNS_DIR } from "./types.ts";
+import { CHAIN_RUNS_DIR, type OutputMode } from "./types.ts";
 const CHAIN_DIR_MAX_AGE_MS = 24 * 60 * 60 * 1000; // 24 hours
 const INITIAL_PROGRESS_CONTENT = "# Progress\n\n## Status\nIn Progress\n\n## Tasks\n\n## Files Changed\n\n## Notes\n";
 
@@ -16,6 +16,7 @@ const INITIAL_PROGRESS_CONTENT = "# Progress\n\n## Status\nIn Progress\n\n## Tas
 
 export interface ResolvedStepBehavior {
 	output: string | false;
+	outputMode: OutputMode;
 	reads: string[] | false;
 	progress: boolean;
 	skills: string[] | false;
@@ -24,6 +25,7 @@ export interface ResolvedStepBehavior {
 
 export interface StepOverrides {
 	output?: string | false;
+	outputMode?: OutputMode;
 	reads?: string[] | false;
 	progress?: boolean;
 	skills?: string[] | false;
@@ -44,6 +46,7 @@ export interface SequentialStep {
 	task?: string;
 	cwd?: string;
 	output?: string | false;
+	outputMode?: OutputMode;
 	reads?: string[] | false;
 	progress?: boolean;
 	skill?: string | string[] | false;
@@ -57,6 +60,7 @@ interface ParallelTaskItem {
 	cwd?: string;
 	count?: number;
 	output?: string | false;
+	outputMode?: OutputMode;
 	reads?: string[] | false;
 	progress?: boolean;
 	skill?: string | string[] | false;
@@ -211,8 +215,9 @@ export function resolveStepBehavior(
 		}
 	}
 
+	const outputMode = stepOverrides.outputMode ?? "inline";
 	const model = stepOverrides.model ?? agentConfig.model;
-	return { output, reads, progress, skills, model };
+	return { output, outputMode, reads, progress, skills, model };
 }
 
 // =============================================================================
@@ -348,8 +353,9 @@ export function resolveParallelBehaviors(
 			}
 		}
 
+		const outputMode = task.outputMode ?? "inline";
 		const model = task.model ?? config.model;
-		return { output, reads, progress, skills, model };
+		return { output, outputMode, reads, progress, skills, model };
 	});
 }
 

package/src/shared/types.ts

@@ -17,6 +17,15 @@ export interface MaxOutputConfig {
 	lines?: number;
 }
 
+export type OutputMode = "inline" | "file-only";
+
+export interface SavedOutputReference {
+	path: string;
+	bytes: number;
+	lines: number;
+	message: string;
+}
+
 interface TruncationResult {
 	text: string;
 	truncated: boolean;
@@ -189,7 +198,9 @@ export interface SingleResult {
 	artifactPaths?: ArtifactPaths;
 	truncation?: TruncationResult;
 	finalOutput?: string;
+	outputMode?: OutputMode;
 	savedOutputPath?: string;
+	outputReference?: SavedOutputReference;
 	outputSaveError?: string;
 }
 
@@ -356,6 +367,7 @@ export interface SubagentState {
 		interrupt?: () => boolean;
 	}>;
 	lastForegroundControlId: string | null;
+	pendingForegroundControlNotices?: Map<string, ReturnType<typeof setTimeout>>;
 	cleanupTimers: Map<string, ReturnType<typeof setTimeout>>;
 	lastUiContext: ExtensionContext | null;
 	poller: NodeJS.Timeout | null;
@@ -424,6 +436,7 @@ export interface RunSyncOptions {
 	sessionFile?: string;
 	share?: boolean;
 	outputPath?: string;
+	outputMode?: OutputMode;
 	maxSubagentDepth?: number;
 	/** Override the agent's default model (format: "provider/id" or just "id") */
 	modelOverride?: string;

package/src/slash/slash-commands.ts

@@ -30,6 +30,7 @@ import {
 
 interface InlineConfig {
 	output?: string | false;
+	outputMode?: "inline" | "file-only";
 	reads?: string[] | false;
 	model?: string;
 	skill?: string[] | false;
@@ -50,6 +51,7 @@ const parseInlineConfig = (raw: string): InlineConfig => {
 		const val = trimmed.slice(eq + 1).trim();
 		switch (key) {
 			case "output": config.output = val === "false" ? false : val; break;
+			case "outputMode": if (val === "inline" || val === "file-only") config.outputMode = val; break;
 			case "reads": config.reads = val === "false" ? false : val.split("+").filter(Boolean); break;
 			case "model": config.model = val || undefined; break;
 			case "skill": case "skills": config.skill = val === "false" ? false : val.split("+").filter(Boolean); break;
@@ -131,6 +133,7 @@ const mapSavedChainSteps = (chain: ChainConfig, worktree = false): ChainStep[] =
 			agent: step.agent,
 			task: step.task || undefined,
 			output: step.output,
+			outputMode: step.outputMode,
 			reads: step.reads,
 			progress: step.progress,
 			skill: step.skill ?? step.skills,
@@ -479,6 +482,7 @@ export function registerSlashCommands(
 			}
 			const params: SubagentParamsLike = { agent: agentName, task: finalTask, clarify: false, agentScope: "both" };
 			if (inline.output !== undefined) params.output = inline.output;
+			if (inline.outputMode !== undefined) params.outputMode = inline.outputMode;
 			if (inline.skill !== undefined) params.skill = inline.skill;
 			if (inline.model) params.model = inline.model;
 			if (bg) params.async = true;
@@ -498,6 +502,7 @@ export function registerSlashCommands(
 				agent: name,
 				...(stepTask ? { task: stepTask } : i === 0 && parsed.task ? { task: parsed.task } : {}),
 				...(config.output !== undefined ? { output: config.output } : {}),
+				...(config.outputMode !== undefined ? { outputMode: config.outputMode } : {}),
 				...(config.reads !== undefined ? { reads: config.reads } : {}),
 				...(config.model ? { model: config.model } : {}),
 				...(config.skill !== undefined ? { skill: config.skill } : {}),
@@ -550,6 +555,7 @@ export function registerSlashCommands(
 				agent: name,
 				task: stepTask ?? parsed.task,
 				...(config.output !== undefined ? { output: config.output } : {}),
+				...(config.outputMode !== undefined ? { outputMode: config.outputMode } : {}),
 				...(config.reads !== undefined ? { reads: config.reads } : {}),
 				...(config.model ? { model: config.model } : {}),
 				...(config.skill !== undefined ? { skill: config.skill } : {}),