pi-subagents 0.21.2 → 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/control-notices.ts

@@ -0,0 +1,92 @@
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { controlNotificationKey, formatControlNoticeMessage } from "../runs/shared/subagent-control.ts";
+import type { ControlEvent, SubagentState } from "../shared/types.ts";
+
+export const SUBAGENT_CONTROL_MESSAGE_TYPE = "subagent_control_notice";
+
+export interface SubagentControlMessageDetails {
+	event: ControlEvent;
+	source?: "foreground" | "async";
+	asyncDir?: string;
+	childIntercomTarget?: string;
+	noticeText?: string;
+}
+
+export function controlNoticeTarget(details: SubagentControlMessageDetails): string | undefined {
+	return details.childIntercomTarget;
+}
+
+export function formatSubagentControlNotice(details: SubagentControlMessageDetails, content?: string): string {
+	return details.noticeText ?? content ?? formatControlNoticeMessage(details.event, controlNoticeTarget(details));
+}
+
+function noticeTimerKey(details: SubagentControlMessageDetails): string {
+	const childIntercomTarget = controlNoticeTarget(details);
+	return `${details.event.runId}:${controlNotificationKey(details.event, childIntercomTarget)}`;
+}
+
+export function clearPendingForegroundControlNotices(state: SubagentState, runId?: string): void {
+	const pending = state.pendingForegroundControlNotices;
+	if (!pending) return;
+	for (const [key, timer] of pending) {
+		if (runId !== undefined && !key.startsWith(`${runId}:`)) continue;
+		clearTimeout(timer);
+		pending.delete(key);
+	}
+}
+
+function deliverControlNotice(input: {
+	pi: Pick<ExtensionAPI, "sendMessage">;
+	visibleControlNotices: Set<string>;
+	details: SubagentControlMessageDetails;
+}): void {
+	const childIntercomTarget = controlNoticeTarget(input.details);
+	const key = controlNotificationKey(input.details.event, childIntercomTarget);
+	if (input.visibleControlNotices.has(key)) return;
+	input.visibleControlNotices.add(key);
+	const noticeText = input.details.noticeText ?? formatControlNoticeMessage(input.details.event, childIntercomTarget);
+	input.pi.sendMessage(
+		{
+			customType: SUBAGENT_CONTROL_MESSAGE_TYPE,
+			content: noticeText,
+			display: true,
+			details: { ...input.details, childIntercomTarget, noticeText },
+		},
+		{ triggerTurn: input.details.source !== "foreground" },
+	);
+}
+
+function isForegroundNoticeStillActionable(state: SubagentState, details: SubagentControlMessageDetails): boolean {
+	const control = state.foregroundControls.get(details.event.runId);
+	if (!control) return false;
+	if (control.currentAgent && control.currentAgent !== details.event.agent) return false;
+	if (details.event.index !== undefined && control.currentIndex !== details.event.index) return false;
+	return control.currentActivityState === "needs_attention";
+}
+
+export function handleSubagentControlNotice(input: {
+	pi: Pick<ExtensionAPI, "sendMessage">;
+	state: SubagentState;
+	visibleControlNotices: Set<string>;
+	details: SubagentControlMessageDetails;
+	foregroundDelayMs?: number;
+}): void {
+	if (!input.details?.event || input.details.event.type === "active_long_running") return;
+	if (input.details.source !== "foreground") {
+		deliverControlNotice(input);
+		return;
+	}
+
+	const pending = input.state.pendingForegroundControlNotices ?? new Map<string, ReturnType<typeof setTimeout>>();
+	input.state.pendingForegroundControlNotices = pending;
+	const timerKey = noticeTimerKey(input.details);
+	const existing = pending.get(timerKey);
+	if (existing) clearTimeout(existing);
+	const timer = setTimeout(() => {
+		pending.delete(timerKey);
+		if (!isForegroundNoticeStillActionable(input.state, input.details)) return;
+		deliverControlNotice(input);
+	}, input.foregroundDelayMs ?? 1000);
+	timer.unref?.();
+	pending.set(timerKey, timer);
+}

package/src/extension/index.ts

@@ -25,7 +25,6 @@ import { renderWidget, renderSubagentResult, stopResultAnimations, stopWidgetAni
 import { SubagentParams } from "./schemas.ts";
 import { createSubagentExecutor } from "../runs/foreground/subagent-executor.ts";
 import { createAsyncJobTracker } from "../runs/background/async-job-tracker.ts";
-import { controlNotificationKey, formatControlNoticeMessage } from "../runs/shared/subagent-control.ts";
 import { createResultWatcher } from "../runs/background/result-watcher.ts";
 import { registerSlashCommands } from "../slash/slash-commands.ts";
 import { registerPromptTemplateDelegationBridge } from "../slash/prompt-template-bridge.ts";
@@ -36,7 +35,6 @@ import registerSubagentNotify, { type SubagentNotifyDetails } from "../runs/back
 import { SUBAGENT_CHILD_ENV } from "../runs/shared/pi-args.ts";
 import { formatDuration, shortenPath } from "../shared/formatters.ts";
 import {
-	type ControlEvent,
 	type Details,
 	type ExtensionConfig,
 	type SubagentState,
@@ -49,6 +47,13 @@ import {
 	SUBAGENT_CONTROL_EVENT,
 	WIDGET_KEY,
 } from "../shared/types.ts";
+import {
+	clearPendingForegroundControlNotices,
+	formatSubagentControlNotice,
+	handleSubagentControlNotice,
+	SUBAGENT_CONTROL_MESSAGE_TYPE,
+	type SubagentControlMessageDetails,
+} from "./control-notices.ts";
 
 /**
  * Derive subagent session base directory from parent session file.
@@ -153,24 +158,6 @@ function createSlashResultComponent(
 	return container;
 }
 
-const SUBAGENT_CONTROL_MESSAGE_TYPE = "subagent_control_notice";
-
-interface SubagentControlMessageDetails {
-	event: ControlEvent;
-	source?: "foreground" | "async";
-	asyncDir?: string;
-	childIntercomTarget?: string;
-	noticeText?: string;
-}
-
-function controlNoticeTarget(details: SubagentControlMessageDetails): string | undefined {
-	return details.childIntercomTarget;
-}
-
-function formatSubagentControlNotice(details: SubagentControlMessageDetails, content?: string): string {
-	return details.noticeText ?? content ?? formatControlNoticeMessage(details.event, controlNoticeTarget(details));
-}
-
 function parseSubagentNotifyContent(content: string): SubagentNotifyDetails | undefined {
 	const lines = content.split("\n");
 	const header = lines[0] ?? "";
@@ -259,6 +246,7 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 		asyncJobs: new Map(),
 		foregroundControls: new Map(),
 		lastForegroundControlId: null,
+		pendingForegroundControlNotices: new Map(),
 		cleanupTimers: new Map(),
 		lastUiContext: null,
 		poller: null,
@@ -283,6 +271,7 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 	const runtimeCleanup = () => {
 		stopWidgetAnimation();
 		stopResultAnimations();
+		clearPendingForegroundControlNotices(state);
 		if (state.poller) {
 			clearInterval(state.poller);
 			state.poller = null;
@@ -419,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
@@ -497,22 +486,12 @@ DIAGNOSTICS:
 	const visibleControlNotices = existingVisibleControlNotices instanceof Set ? existingVisibleControlNotices as Set<string> : new Set<string>();
 	globalStore[controlNoticeSeenStoreKey] = visibleControlNotices;
 	const controlEventHandler = (payload: unknown) => {
-		const details = payload as SubagentControlMessageDetails;
-		if (!details?.event || details.event.type === "active_long_running") return;
-		const childIntercomTarget = controlNoticeTarget(details);
-		const key = controlNotificationKey(details.event, childIntercomTarget);
-		if (visibleControlNotices.has(key)) return;
-		visibleControlNotices.add(key);
-		const noticeText = details.noticeText ?? formatControlNoticeMessage(details.event, childIntercomTarget);
-		pi.sendMessage(
-			{
-				customType: SUBAGENT_CONTROL_MESSAGE_TYPE,
-				content: noticeText,
-				display: true,
-				details: { ...details, childIntercomTarget, noticeText },
-			},
-			{ triggerTurn: true },
-		);
+		handleSubagentControlNotice({
+			pi,
+			state,
+			visibleControlNotices,
+			details: payload as SubagentControlMessageDetails,
+		});
 	};
 	const eventUnsubscribes = [
 		pi.events.on(SUBAGENT_ASYNC_STARTED_EVENT, handleStarted),
@@ -547,6 +526,7 @@ DIAGNOSTICS:
 		state.currentSessionId = ctx.sessionManager.getSessionFile() ?? `session-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
 		state.lastUiContext = ctx;
 		cleanupSessionArtifacts(ctx);
+		clearPendingForegroundControlNotices(state);
 		resetJobs(ctx);
 		restoreSlashFinalSnapshots(ctx.sessionManager.getEntries());
 	};
@@ -569,6 +549,7 @@ DIAGNOSTICS:
 		stopResultWatcher();
 		if (state.poller) clearInterval(state.poller);
 		state.poller = null;
+		clearPendingForegroundControlNotices(state);
 		for (const timer of state.cleanupTimers.values()) {
 			clearTimeout(timer);
 		}

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),
 					},