pi-subagents 0.21.3 → 0.21.4

package/src/agents/chain-serializer.ts

@@ -1,4 +1,5 @@
 import type { ChainConfig, ChainStepConfig } from "./agents.ts";
+import { buildRuntimeName, frontmatterNameForConfig, parsePackageName } from "./identity.ts";
 import { parseFrontmatter } from "./frontmatter.ts";
 
 function parseStepBody(agent: string, sectionBody: string): ChainStepConfig {
@@ -19,6 +20,10 @@ function parseStepBody(agent: string, sectionBody: string): ChainStepConfig {
 			else if (rawValue) step.output = rawValue;
 			continue;
 		}
+		if (key === "outputmode") {
+			if (rawValue === "inline" || rawValue === "file-only") step.outputMode = rawValue;
+			continue;
+		}
 		if (key === "reads") {
 			if (rawValue === "false") {
 				step.reads = false;
@@ -75,14 +80,20 @@ export function parseChain(content: string, source: "user" | "project", filePath
 		steps.push(parseStepBody(agent, sectionBody));
 	}
 
+	const localName = frontmatter.name;
+	const parsedPackage = parsePackageName(frontmatter.package, `Chain '${localName}' package`);
+	if (parsedPackage.error) throw new Error(parsedPackage.error);
+	const packageName = parsedPackage.packageName;
 	const extraFields: Record<string, string> = {};
 	for (const [key, value] of Object.entries(frontmatter)) {
-		if (key === "name" || key === "description") continue;
+		if (key === "name" || key === "package" || key === "description") continue;
 		extraFields[key] = value;
 	}
 
 	return {
-		name: frontmatter.name,
+		name: buildRuntimeName(localName, packageName),
+		localName,
+		packageName,
 		description: frontmatter.description,
 		source,
 		filePath,
@@ -94,7 +105,8 @@ export function parseChain(content: string, source: "user" | "project", filePath
 export function serializeChain(config: ChainConfig): string {
 	const lines: string[] = [];
 	lines.push("---");
-	lines.push(`name: ${config.name}`);
+	lines.push(`name: ${frontmatterNameForConfig(config)}`);
+	if (config.packageName) lines.push(`package: ${config.packageName}`);
 	lines.push(`description: ${config.description}`);
 	if (config.extraFields) {
 		for (const [key, value] of Object.entries(config.extraFields)) {
@@ -109,6 +121,7 @@ export function serializeChain(config: ChainConfig): string {
 		lines.push(`## ${step.agent}`);
 		if (step.output === false) lines.push("output: false");
 		else if (step.output) lines.push(`output: ${step.output}`);
+		if (step.outputMode) lines.push(`outputMode: ${step.outputMode}`);
 		if (step.reads === false) lines.push("reads: false");
 		else if (Array.isArray(step.reads) && step.reads.length > 0) lines.push(`reads: ${step.reads.join(", ")}`);
 		if (step.model) lines.push(`model: ${step.model}`);

package/src/agents/identity.ts

@@ -0,0 +1,30 @@
+import type { AgentConfig, ChainConfig } from "./agents.ts";
+
+const IDENTIFIER_PATTERN = /^[a-z0-9][a-z0-9-]*(?:\.[a-z0-9][a-z0-9-]*)*$/;
+
+function normalizePackageName(value: string | undefined): string | undefined {
+	const trimmed = value?.trim();
+	if (!trimmed) return undefined;
+	return trimmed.toLowerCase().replace(/\s+/g, "-").replace(/[^a-z0-9.-]/g, "").replace(/-+/g, "-").replace(/\.+/g, ".").replace(/(?:^[-.]+|[-.]+$)/g, "");
+}
+
+export function parsePackageName(value: unknown, label = "package"): { packageName?: string; error?: string } {
+	if (value === undefined || value === false || value === "") return { packageName: undefined };
+	if (typeof value !== "string") return { error: `${label} must be a string or false when provided.` };
+	const packageName = normalizePackageName(value);
+	if (!packageName || !IDENTIFIER_PATTERN.test(packageName)) return { error: `${label} is invalid after sanitization.` };
+	return { packageName };
+}
+
+export function buildRuntimeName(localName: string, packageName?: string): string {
+	const trimmedPackage = packageName?.trim();
+	return trimmedPackage ? `${trimmedPackage}.${localName}` : localName;
+}
+
+export function frontmatterNameForConfig(config: Pick<AgentConfig | ChainConfig, "name" | "localName" | "packageName">): string {
+	if (config.localName) return config.localName;
+	if (config.packageName && config.name.startsWith(`${config.packageName}.`)) {
+		return config.name.slice(config.packageName.length + 1);
+	}
+	return config.name;
+}

package/src/extension/index.ts

@@ -408,11 +408,11 @@ Example: { chain: [{agent:"agent-a", task:"Analyze {task}"}, {agent:"agent-b", t
 
 MANAGEMENT (use action field, omit agent/task/chain/tasks):
 • { action: "list" } - discover executable agents/chains
-• { action: "get", agent: "name" } - full detail
-• { action: "create", config: { name, systemPrompt, systemPromptMode, inheritProjectContext, inheritSkills, defaultContext, ... } }
-• { action: "update", agent: "name", config: { ... } } - merge
-• { action: "delete", agent: "name" }
-• Use chainName for chain operations
+• { action: "get", agent: "name" } - full detail; packaged agents use dotted runtime names like "package.agent"
+• { action: "create", config: { name: "custom-agent", package: "code-analysis", systemPrompt, systemPromptMode, inheritProjectContext, inheritSkills, defaultContext, ... } }
+• { action: "update", agent: "code-analysis.custom-agent", config: { package: "analysis", ... } } - merge
+• { action: "delete", agent: "code-analysis.custom-agent" }
+• Use chainName for chain operations; packaged chains also use dotted runtime names
 
 CONTROL:
 • { action: "status", id: "..." } - inspect an async/background run by id or prefix

package/src/extension/schemas.ts

@@ -22,6 +22,11 @@ const OutputOverride = Type.Unsafe({
 	description: "Output filename/path (string), or false to disable file output",
 });
 
+const OutputModeOverride = Type.String({
+	enum: ["inline", "file-only"],
+	description: "Return saved output inline (default) or only a concise file reference. file-only requires output to be a path.",
+});
+
 const ReadsOverride = Type.Unsafe({
 	anyOf: [
 		{ type: "array", items: { type: "string" } },
@@ -36,6 +41,7 @@ const TaskItem = Type.Object({
 	cwd: Type.Optional(Type.String()),
 	count: Type.Optional(Type.Integer({ minimum: 1, description: "Repeat this parallel task N times with the same settings." })),
 	output: Type.Optional(OutputOverride),
+	outputMode: Type.Optional(OutputModeOverride),
 	reads: Type.Optional(ReadsOverride),
 	progress: Type.Optional(Type.Boolean({ description: "Enable progress.md tracking for this task" })),
 	model: Type.Optional(Type.String({ description: "Override model for this task (e.g. 'google/gemini-3-pro')" })),
@@ -49,6 +55,7 @@ const ParallelTaskSchema = Type.Object({
 	cwd: Type.Optional(Type.String()),
 	count: Type.Optional(Type.Integer({ minimum: 1, description: "Repeat this parallel task N times with the same settings." })),
 	output: Type.Optional(OutputOverride),
+	outputMode: Type.Optional(OutputModeOverride),
 	reads: Type.Optional(ReadsOverride),
 	progress: Type.Optional(Type.Boolean({ description: "Enable progress.md tracking in {chain_dir}" })),
 	skill: Type.Optional(SkillOverride),
@@ -63,6 +70,7 @@ const ChainItem = Type.Object({
 	})),
 	cwd: Type.Optional(Type.String()),
 	output: Type.Optional(OutputOverride),
+	outputMode: Type.Optional(OutputModeOverride),
 	reads: Type.Optional(ReadsOverride),
 	progress: Type.Optional(Type.Boolean({ description: "Enable progress.md tracking in {chain_dir}" })),
 	skill: Type.Optional(SkillOverride),
@@ -119,9 +127,9 @@ export const SubagentParams = Type.Object({
 			{ type: "object", additionalProperties: true },
 			{ type: "string" },
 		],
-		description: "Agent or chain config for create/update. Agent: name, description, scope ('user'|'project', default 'user'), systemPrompt, systemPromptMode, inheritProjectContext, inheritSkills, defaultContext ('fresh'|'fork'), model, tools (comma-separated), extensions (comma-separated), skills (comma-separated), thinking, output, reads, progress, maxSubagentDepth. Chain: name, description, scope, steps (array of {agent, task?, output?, reads?, model?, skill?, progress?}). Presence of 'steps' creates a chain instead of an agent. String values must be valid JSON."
+		description: "Agent or chain config for create/update. Agent: name, package (optional namespace; runtime name becomes package.name), description, scope ('user'|'project', default 'user'), systemPrompt, systemPromptMode, inheritProjectContext, inheritSkills, defaultContext ('fresh'|'fork'), model, tools (comma-separated), extensions (comma-separated), skills (comma-separated), thinking, output, reads, progress, maxSubagentDepth. Chain: name, package, description, scope, steps (array of {agent, task?, output?, outputMode?, reads?, model?, skill?, progress?}). Presence of 'steps' creates a chain instead of an agent. String values must be valid JSON."
 	})),
-	tasks: Type.Optional(Type.Array(TaskItem, { description: "PARALLEL mode: [{agent, task, count?, output?, reads?, progress?}, ...]" })),
+	tasks: Type.Optional(Type.Array(TaskItem, { description: "PARALLEL mode: [{agent, task, count?, output?, outputMode?, reads?, progress?}, ...]" })),
 	concurrency: Type.Optional(Type.Integer({ minimum: 1, description: "Top-level PARALLEL mode only: max concurrent tasks. Defaults to config.parallel.concurrency or 4." })),
 	worktree: Type.Optional(Type.Boolean({
 		description: "Create isolated git worktrees for each parallel task. " +
@@ -154,6 +162,7 @@ export const SubagentParams = Type.Object({
 		],
 		description: "Output file for single agent (string), or false to disable. Relative paths resolve against cwd.",
 	})),
+	outputMode: Type.Optional(OutputModeOverride),
 	skill: Type.Optional(SkillOverride),
 	model: Type.Optional(Type.String({ description: "Override model for single agent (e.g. 'anthropic/claude-sonnet-4')" })),
 });

package/src/manager-ui/agent-manager-chain-detail.ts

@@ -50,6 +50,10 @@ function buildChainDetailLines(chain: ChainConfig, width: number): string[] {
 	const steps = chain.steps as DetailChainStep[];
 	const dependencyMap = buildDependencyMap(steps);
 	lines.push(truncateToWidth(chain.description, contentWidth));
+	if (chain.packageName) {
+		lines.push(truncateToWidth(`Local name: ${chain.localName ?? chain.name}`, contentWidth));
+		lines.push(truncateToWidth(`Package: ${chain.packageName}`, contentWidth));
+	}
 	lines.push("");
 	lines.push(truncateToWidth(`File: ${formatPath(chain.filePath)}`, contentWidth));
 	lines.push("");

package/src/manager-ui/agent-manager-detail.ts

@@ -61,6 +61,10 @@ function buildDetailLines(
 	const defaultContext = agent.defaultContext ?? "auto";
 	const maxSubagentDepth = agent.maxSubagentDepth !== undefined ? String(agent.maxSubagentDepth) : "(default)";
 
+	if (agent.packageName) {
+		lines.push(renderFieldLine("Local name:", agent.localName ?? agent.name, contentWidth, theme));
+		lines.push(renderFieldLine("Package:", agent.packageName, contentWidth, theme));
+	}
 	lines.push(renderFieldLine("Model:", agent.model ?? "default", contentWidth, theme));
 	lines.push(renderFieldLine("Prompt mode:", agent.systemPromptMode, contentWidth, theme));
 	lines.push(renderFieldLine("Project ctx:", agent.inheritProjectContext ? "on" : "off", contentWidth, theme));

package/src/manager-ui/agent-manager-edit.ts

@@ -1,6 +1,6 @@
 import type { Theme } from "@mariozechner/pi-coding-agent";
 import { matchesKey, truncateToWidth } from "@mariozechner/pi-tui";
-import { defaultSystemPromptMode, type AgentConfig, type AgentDefaultContext, type BuiltinAgentOverrideBase } from "../agents/agents.ts";
+import { buildRuntimeName, defaultSystemPromptMode, frontmatterNameForConfig, parsePackageName, type AgentConfig, type AgentDefaultContext, type BuiltinAgentOverrideBase } from "../agents/agents.ts";
 import { createEditorState, ensureCursorVisible, getCursorDisplayPos, handleEditorInput, renderEditor, wrapText } from "../tui/text-editor.ts";
 import type { TextEditorState } from "../tui/text-editor.ts";
 import { pad, row, renderHeader, renderFooter, formatScrollInfo } from "../tui/render-helpers.ts";
@@ -26,7 +26,7 @@ interface CreateEditStateOptions {
 }
 
 const THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh"] as const;
-const FIELD_ORDER = ["name", "description", "model", "fallbackModels", "thinking", "systemPromptMode", "inheritProjectContext", "inheritSkills", "defaultContext", "tools", "extensions", "skills", "output", "reads", "progress", "interactive", "prompt"] as const;
+const FIELD_ORDER = ["name", "package", "description", "model", "fallbackModels", "thinking", "systemPromptMode", "inheritProjectContext", "inheritSkills", "defaultContext", "tools", "extensions", "skills", "output", "reads", "progress", "interactive", "prompt"] as const;
 type ThinkingLevel = typeof THINKING_LEVELS[number];
 const PROMPT_VIEWPORT_HEIGHT = 16;
 const MODEL_SELECTOR_HEIGHT = 10;
@@ -94,12 +94,13 @@ export function createEditState(draft: AgentConfig, isNew: boolean, models: Mode
 function renderFieldValue(field: EditField, state: EditState): string {
 	const draft = state.draft;
 	switch (field) {
-		case "name": return draft.name;
+		case "name": return frontmatterNameForConfig(draft);
+		case "package": return draft.packageName ?? "";
 		case "description": return draft.description;
 		case "model": return draft.model ?? "default";
 		case "fallbackModels": return draft.fallbackModels && draft.fallbackModels.length > 0 ? draft.fallbackModels.join(", ") : "";
 		case "thinking": return draft.thinking ?? "off";
-		case "systemPromptMode": return draft.systemPromptMode ?? defaultSystemPromptMode(draft.name);
+		case "systemPromptMode": return draft.systemPromptMode ?? defaultSystemPromptMode(frontmatterNameForConfig(draft));
 		case "inheritProjectContext": return draft.inheritProjectContext ? "on" : "off";
 		case "inheritSkills": return draft.inheritSkills ? "on" : "off";
 		case "defaultContext": return draft.defaultContext ?? "auto";
@@ -118,14 +119,32 @@ function renderFieldValue(field: EditField, state: EditState): string {
 function applyFieldValue(field: EditField, state: EditState, value: string): void {
 	const draft = state.draft;
 	switch (field) {
-		case "name": draft.name = value.trim(); break;
+		case "name": {
+			const localName = value.trim();
+			draft.localName = localName || undefined;
+			draft.name = localName ? buildRuntimeName(localName, draft.packageName) : "";
+			break;
+		}
+		case "package": {
+			const parsed = parsePackageName(value, "package");
+			if (parsed.error) {
+				state.error = parsed.error;
+				break;
+			}
+			const packageName = parsed.packageName;
+			draft.packageName = packageName;
+			const localName = frontmatterNameForConfig(draft).trim();
+			draft.name = localName ? buildRuntimeName(localName, packageName) : "";
+			state.error = undefined;
+			break;
+		}
 		case "description": draft.description = value.trim(); break;
 		case "model": draft.model = value.trim() || undefined; break;
 		case "fallbackModels": draft.fallbackModels = parseCommaList(value); break;
 		case "systemPromptMode": {
 			const trimmed = value.trim();
 			if (trimmed === "") {
-				draft.systemPromptMode = defaultSystemPromptMode(draft.name);
+				draft.systemPromptMode = defaultSystemPromptMode(frontmatterNameForConfig(draft));
 				break;
 			}
 			if (trimmed === "append" || trimmed === "replace") {

package/src/manager-ui/agent-manager.ts

@@ -8,7 +8,9 @@ import {
 	defaultInheritProjectContext,
 	defaultInheritSkills,
 	defaultSystemPromptMode,
+	buildRuntimeName,
 	discoverAgentsAll,
+	frontmatterNameForConfig,
 	removeBuiltinAgentOverride,
 	saveBuiltinAgentOverride,
 	type AgentConfig,
@@ -238,10 +240,19 @@ export class AgentManagerComponent implements Component {
 		catch (err) { this.statusMessage = { text: err instanceof Error ? err.message : "Failed to load chain file.", type: "error" }; this.screen = "list"; }
 	}
 
+	private runtimeNameExistsInScope(kind: "agent" | "chain", scope: "user" | "project", name: string, excludePath?: string): boolean {
+		const discovered = discoverAgentsAll(this.agentData.cwd);
+		if (kind === "agent") {
+			const agents = scope === "user" ? discovered.user : discovered.project;
+			return agents.some((agent) => agent.name === name && agent.filePath !== excludePath);
+		}
+		return discovered.chains.some((chain) => chain.source === scope && chain.name === name && chain.filePath !== excludePath);
+	}
+
 	private enterNameInput(mode: NameInputState["mode"], sourceId?: string, template?: AgentTemplate): void {
 		const allowProject = Boolean(this.agentData.projectDir); let initial = ""; let scope: "user" | "project" = "user";
-		if (mode === "clone-agent" && sourceId) { const entry = this.getAgentEntry(sourceId); if (entry) { initial = `${entry.config.name}-copy`; scope = entry.config.source === "project" ? "project" : "user"; } }
-		if (mode === "clone-chain" && sourceId) { const entry = this.getChainEntry(sourceId); if (entry) { initial = `${entry.config.name}-copy`; scope = entry.config.source === "project" ? "project" : "user"; } }
+		if (mode === "clone-agent" && sourceId) { const entry = this.getAgentEntry(sourceId); if (entry) { initial = `${frontmatterNameForConfig(entry.config)}-copy`; scope = entry.config.source === "project" ? "project" : "user"; } }
+		if (mode === "clone-chain" && sourceId) { const entry = this.getChainEntry(sourceId); if (entry) { initial = `${frontmatterNameForConfig(entry.config)}-copy`; scope = entry.config.source === "project" ? "project" : "user"; } }
 		if (mode === "new-agent" && template && template.name !== "Blank") initial = slugTemplateName(template.name);
 		this.nameInputState = { mode, editor: createEditorState(initial), scope, allowProject, sourceId, template }; this.screen = "name-input";
 	}
@@ -269,7 +280,16 @@ export class AgentManagerComponent implements Component {
 				return false;
 			}
 		}
-		if (!edit.draft.name || !edit.draft.description) { edit.error = "Name and description are required."; return false; }
+		let localName = frontmatterNameForConfig(edit.draft).trim();
+		if (!edit.draft.packageName && edit.draft.name !== entry.config.name) localName = edit.draft.name.trim();
+		if (!localName || !edit.draft.description) { edit.error = "Name and description are required."; return false; }
+		edit.draft.localName = localName;
+		edit.draft.name = buildRuntimeName(localName, edit.draft.packageName);
+		const draftScope = edit.draft.source === "project" ? "project" : "user";
+		if (this.runtimeNameExistsInScope("agent", draftScope, edit.draft.name, entry.config.filePath)) {
+			edit.error = `An agent named '${edit.draft.name}' already exists in ${draftScope} scope.`;
+			return false;
+		}
 		let filePath = entry.config.filePath;
 		if (entry.isNew) {
 			const dir = edit.draft.source === "project" ? this.agentData.projectDir : this.agentData.userDir;
@@ -404,15 +424,15 @@ export class AgentManagerComponent implements Component {
 			const sourceEntry = this.getChainEntry(state.sourceId); if (!sourceEntry) { this.screen = "list"; this.tui.requestRender(); return; }
 			const dir = state.scope === "project" ? this.agentData.projectDir : this.agentData.userDir;
 			if (!dir) { state.error = "Project agents directory not found."; this.tui.requestRender(); return; }
-			const filePath = path.join(dir, `${name}.chain.md`); if (fs.existsSync(filePath)) { state.error = "A chain with that name already exists."; this.tui.requestRender(); return; }
-			try { const cloned = cloneChainConfig({ ...sourceEntry.config, name, source: state.scope, filePath }); fs.mkdirSync(dir, { recursive: true }); fs.writeFileSync(filePath, serializeChain(cloned), "utf-8"); const added: ChainEntry = { id: `c${this.nextId++}`, kind: "chain", config: cloned }; this.chains.push(added); this.nameInputState = null; this.enterChainDetail(added); this.tui.requestRender(); return; }
+			const filePath = path.join(dir, `${name}.chain.md`); if (fs.existsSync(filePath) || this.runtimeNameExistsInScope("chain", state.scope, name)) { state.error = "A chain with that name already exists."; this.tui.requestRender(); return; }
+			try { const cloned = cloneChainConfig({ ...sourceEntry.config, name, localName: name, packageName: undefined, source: state.scope, filePath }); fs.mkdirSync(dir, { recursive: true }); fs.writeFileSync(filePath, serializeChain(cloned), "utf-8"); const added: ChainEntry = { id: `c${this.nextId++}`, kind: "chain", config: cloned }; this.chains.push(added); this.nameInputState = null; this.enterChainDetail(added); this.tui.requestRender(); return; }
 			catch (err) { state.error = err instanceof Error ? err.message : "Failed to clone chain."; this.tui.requestRender(); return; }
 		}
 		if (state.mode === "new-chain") {
 			const dir = state.scope === "project" ? this.agentData.projectDir : this.agentData.userDir;
 			if (!dir) { state.error = "Directory not found."; this.tui.requestRender(); return; }
-			const filePath = path.join(dir, `${name}.chain.md`); if (fs.existsSync(filePath)) { state.error = "A chain with that name already exists."; this.tui.requestRender(); return; }
-			const config: ChainConfig = { name, description: "Describe this chain", source: state.scope, filePath, steps: [{ agent: "agent-name", task: "{task}" }] };
+			const filePath = path.join(dir, `${name}.chain.md`); if (fs.existsSync(filePath) || this.runtimeNameExistsInScope("chain", state.scope, name)) { state.error = "A chain with that name already exists."; this.tui.requestRender(); return; }
+			const config: ChainConfig = { name, localName: name, description: "Describe this chain", source: state.scope, filePath, steps: [{ agent: "agent-name", task: "{task}" }] };
 			try { fs.mkdirSync(dir, { recursive: true }); fs.writeFileSync(filePath, serializeChain(config), "utf-8"); const entry: ChainEntry = { id: `c${this.nextId++}`, kind: "chain", config }; this.chains.push(entry); this.nameInputState = null; this.enterChainEdit(entry); }
 			catch (err) { state.error = err instanceof Error ? err.message : "Failed to create chain."; }
 			this.tui.requestRender(); return;
@@ -438,7 +458,7 @@ export class AgentManagerComponent implements Component {
 		}
 		const dir = state.scope === "project" ? this.agentData.projectDir : this.agentData.userDir;
 		if (!dir) { state.error = "Project agents directory not found."; this.tui.requestRender(); return; }
-		const filePath = path.join(dir, `${name}.md`); const config: AgentConfig = { ...baseConfig, name, source: state.scope, filePath };
+		const filePath = path.join(dir, `${name}.md`); const config: AgentConfig = { ...baseConfig, name, localName: name, packageName: undefined, source: state.scope, filePath };
 		const entry: AgentEntry = { id: `a${this.nextId++}`, kind: "agent", config, isNew: true };
 		this.agents.push(entry); this.nameInputState = null; this.enterEdit(entry); this.tui.requestRender();
 	}

package/src/runs/background/async-execution.ts

@@ -11,7 +11,7 @@ import { createRequire } from "node:module";
 import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
 import type { AgentConfig } from "../../agents/agents.ts";
 import { applyThinkingSuffix } from "../shared/pi-args.ts";
-import { injectSingleOutputInstruction, resolveSingleOutputPath } from "../shared/single-output.ts";
+import { injectSingleOutputInstruction, resolveSingleOutputPath, validateFileOnlyOutputMode } from "../shared/single-output.ts";
 import { buildChainInstructions, isParallelStep, resolveStepBehavior, writeInitialProgressFile, type ChainStep, type ResolvedStepBehavior, type SequentialStep, type StepOverrides } from "../../shared/settings.ts";
 import type { RunnerStep } from "../shared/parallel-utils.ts";
 import { resolvePiPackageRoot } from "../shared/pi-spawn.ts";
@@ -98,6 +98,7 @@ interface AsyncSingleParams {
 	sessionFile?: string;
 	skills?: string[];
 	output?: string | false;
+	outputMode?: "inline" | "file-only";
 	modelOverride?: string;
 	availableModels?: AvailableModelInfo[];
 	maxSubagentDepth: number;
@@ -170,6 +171,7 @@ function formatAsyncStartError(mode: "single" | "chain", message: string): Async
 const UNAVAILABLE_SUBAGENT_SKILL_ERROR = "Skills not found: pi-subagents";
 
 class UnavailableSubagentSkillError extends Error {}
+class AsyncStartValidationError extends Error {}
 
 /**
  * Execute a chain asynchronously
@@ -232,6 +234,7 @@ export function executeAsyncChain(
 		const stepSkillInput = normalizeSkillInput(s.skill);
 		return {
 			...(s.output !== undefined ? { output: s.output } : {}),
+			...(s.outputMode !== undefined ? { outputMode: s.outputMode } : {}),
 			...(s.reads !== undefined ? { reads: s.reads } : {}),
 			...(s.progress !== undefined ? { progress: s.progress } : {}),
 			...(stepSkillInput !== undefined ? { skills: stepSkillInput } : {}),
@@ -258,6 +261,8 @@ export function executeAsyncChain(
 		if (behavior.progress) progressInstructionCreated = true;
 		const progressInstructions = buildChainInstructions({ ...behavior, output: false, reads: false }, runnerCwd, isFirstProgressAgent);
 		const outputPath = resolveSingleOutputPath(behavior.output, ctx.cwd, instructionCwd);
+		const validationError = validateFileOnlyOutputMode(behavior.outputMode, outputPath, `Async step (${s.agent})`);
+		if (validationError) throw new AsyncStartValidationError(validationError);
 		const task = injectSingleOutputInstruction(`${readInstructions.prefix}${s.task ?? "{previous}"}${progressInstructions.suffix}`, outputPath);
 
 		const primaryModel = resolveModelCandidate(behavior.model ?? a.model, availableModels, ctx.currentModelProvider);
@@ -278,6 +283,7 @@ export function executeAsyncChain(
 			inheritSkills: a.inheritSkills,
 			skills: resolvedSkills.map((r) => r.name),
 			outputPath,
+			outputMode: behavior.outputMode,
 			sessionFile,
 			maxSubagentDepth: resolveChildMaxSubagentDepth(maxSubagentDepth, a.maxSubagentDepth),
 		};
@@ -323,7 +329,7 @@ export function executeAsyncChain(
 			return buildSeqStep(s as SequentialStep, nextSessionFile());
 		});
 	} catch (error) {
-		if (error instanceof UnavailableSubagentSkillError) return formatAsyncStartError("chain", error.message);
+		if (error instanceof UnavailableSubagentSkillError || error instanceof AsyncStartValidationError) return formatAsyncStartError("chain", error.message);
 		throw error;
 	}
 	let childTargetIndex = 0;
@@ -470,6 +476,9 @@ export function executeAsyncSingle(
 	}
 
 	const outputPath = resolveSingleOutputPath(params.output, ctx.cwd, runnerCwd);
+	const outputMode = params.outputMode ?? "inline";
+	const validationError = validateFileOnlyOutputMode(outputMode, outputPath, `Async single run (${agent})`);
+	if (validationError) return formatAsyncStartError("single", validationError);
 	const taskWithOutputInstruction = injectSingleOutputInstruction(task, outputPath);
 	let spawnResult: { pid?: number; error?: string } = {};
 	try {
@@ -494,6 +503,7 @@ export function executeAsyncSingle(
 						inheritSkills: agentConfig.inheritSkills,
 						skills: resolvedSkills.map((r) => r.name),
 						outputPath,
+						outputMode,
 						sessionFile,
 						maxSubagentDepth: resolveChildMaxSubagentDepth(maxSubagentDepth, agentConfig.maxSubagentDepth),
 					},

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, {