@narumitw/pi-subagents 0.43.0 → 0.46.0

package/src/runner.ts

@@ -6,6 +6,7 @@ import type { AgentToolResult } from "@earendil-works/pi-agent-core";
 import type { Message } from "@earendil-works/pi-ai";
 import { withFileMutationQueue } from "@earendil-works/pi-coding-agent";
 import type { AgentConfig, AgentScope, AgentSource, SubagentThinkingLevel } from "./agents.js";
+import type { TargetPolicyAudit } from "./cwd-policy.js";
 import {
 	appendBounded,
 	DEFAULT_MAX_CONTEXT_BYTES,
@@ -15,6 +16,7 @@ import {
 	MAX_SUBAGENT_TIMEOUT_MS,
 	truncateUtf8,
 } from "./limits.js";
+import { resolvePiInvocation } from "./pi-invocation.js";
 import { JsonLineDecoder } from "./protocol.js";
 
 export const KILL_GRACE_MS = 5000;
@@ -81,6 +83,7 @@ export interface SingleResult {
 	malformedEvents?: number;
 	launchFailed?: boolean;
 	processStarted?: boolean;
+	target?: TargetPolicyAudit;
 	policy?: {
 		inherited: string[];
 		overridden: string[];
@@ -351,22 +354,6 @@ export function buildPiArgs(options: PiArgsOptions): string[] {
 	return args;
 }
 
-function getPiInvocation(args: string[]): { command: string; args: string[] } {
-	const currentScript = process.argv[1];
-	const isBunVirtualScript = currentScript?.startsWith("/$bunfs/root/");
-	if (currentScript && !isBunVirtualScript && fs.existsSync(currentScript)) {
-		return { command: process.execPath, args: [currentScript, ...args] };
-	}
-
-	const execName = path.basename(process.execPath).toLowerCase();
-	const isGenericRuntime = /^(node|bun)(\.exe)?$/.test(execName);
-	if (!isGenericRuntime) {
-		return { command: process.execPath, args };
-	}
-
-	return { command: "pi", args };
-}
-
 function signalProcess(proc: ReturnType<typeof spawn>, signal: NodeJS.Signals): void {
 	if (process.platform !== "win32" && proc.pid) {
 		try {
@@ -574,16 +561,26 @@ export async function runSingleAgent(
 			systemPromptPath: tmpPromptPath ?? undefined,
 			task,
 		});
-		let wasAborted = false;
-		let timedOut = false;
-
-		const exitCode = await new Promise<number>((resolve) => {
-			const invocation = invocationOverride
+		let invocation: { command: string; args: string[] };
+		try {
+			invocation = invocationOverride
 				? {
 						command: invocationOverride.command,
 						args: [...(invocationOverride.argsPrefix ?? []), ...args],
 					}
-				: getPiInvocation(args);
+				: resolvePiInvocation(args);
+		} catch (error) {
+			currentResult.launchFailed = true;
+			currentResult.exitCode = 1;
+			currentResult.stderr = setErrorMessage(
+				error instanceof Error ? error.message : String(error),
+			);
+			return currentResult;
+		}
+		let wasAborted = false;
+		let timedOut = false;
+
+		const exitCode = await new Promise<number>((resolve) => {
 			let settled = false;
 			let cleanupTermination: (() => void) | undefined;
 			let timeout: NodeJS.Timeout | undefined;

package/src/settings.ts

@@ -6,8 +6,12 @@ import lockfile from "proper-lockfile";
 import {
 	type AgentConfig,
 	CONSULT_RESOURCE_POLICIES,
+	CONSULTATION_CWD_POLICIES,
 	type CompletionDelivery,
+	type ConsultationCwdPolicy,
 	type ConsultResourcePolicy,
+	DELEGATION_CWD_POLICIES,
+	type DelegationCwdPolicy,
 	isThinkingLevel,
 	type SubagentAgentConfig,
 	type SubagentSettings,
@@ -158,6 +162,29 @@ export function normalizeSubagentSettings(value: unknown): SubagentSettings | un
 		}
 		settings.consult = consult;
 	}
+	if (hasOwn(value, "cwdPolicy")) {
+		if (!isPlainObject(value.cwdPolicy)) return undefined;
+		const cwdPolicy: NonNullable<SubagentSettings["cwdPolicy"]> = {};
+		if (hasOwn(value.cwdPolicy, "consultation")) {
+			if (
+				typeof value.cwdPolicy.consultation !== "string" ||
+				!CONSULTATION_CWD_POLICIES.includes(value.cwdPolicy.consultation as ConsultationCwdPolicy)
+			) {
+				return undefined;
+			}
+			cwdPolicy.consultation = value.cwdPolicy.consultation as ConsultationCwdPolicy;
+		}
+		if (hasOwn(value.cwdPolicy, "delegation")) {
+			if (
+				typeof value.cwdPolicy.delegation !== "string" ||
+				!DELEGATION_CWD_POLICIES.includes(value.cwdPolicy.delegation as DelegationCwdPolicy)
+			) {
+				return undefined;
+			}
+			cwdPolicy.delegation = value.cwdPolicy.delegation as DelegationCwdPolicy;
+		}
+		settings.cwdPolicy = cwdPolicy;
+	}
 	return settings;
 }
 
@@ -165,6 +192,8 @@ const SETTINGS_FILE = "pi-subagents.json";
 const LEGACY_SETTINGS_FILE = "pi-subagents-config.json";
 const DEFAULT_COMPLETION_DELIVERY: CompletionDelivery = "next-turn";
 export const DEFAULT_CONSULT_RESOURCE_POLICY: ConsultResourcePolicy = "project-context";
+export const DEFAULT_CONSULTATION_CWD_POLICY: ConsultationCwdPolicy = "anywhere";
+export const DEFAULT_DELEGATION_CWD_POLICY: DelegationCwdPolicy = "trusted-targets";
 const SETTINGS_LOCK_FS_ADAPTER = {
 	mkdir: fs.mkdir,
 	mkdirSync: fs.mkdirSync,
@@ -261,6 +290,18 @@ export interface ConsultResourceSettingsSnapshot {
 	error?: string;
 }
 
+export interface CwdPolicyFieldSnapshot<T> {
+	value: T;
+	source: "default" | "user settings";
+}
+
+export interface CwdPolicySettingsSnapshot {
+	path: string;
+	consultation: CwdPolicyFieldSnapshot<ConsultationCwdPolicy>;
+	delegation: CwdPolicyFieldSnapshot<DelegationCwdPolicy>;
+	error?: string;
+}
+
 export interface SubagentSettingsSnapshot {
 	path: string;
 	settings?: SubagentSettings;
@@ -302,16 +343,28 @@ function inspectSubagentSettingsPath(configPath: string): {
 	settings?: SubagentSettings;
 	error?: string;
 } {
+	const fileName = path.basename(configPath);
+	let contents: string;
 	try {
-		const raw: unknown = JSON.parse(fs.readFileSync(configPath, "utf8"));
-		const settings = normalizeSubagentSettings(raw);
-		if (!isPlainObject(raw) || !settings) {
-			throw new Error(`${path.basename(configPath)} is not a valid settings object`);
-		}
-		return { path: configPath, raw, settings };
+		contents = fs.readFileSync(configPath, "utf8");
 	} catch (error) {
-		return { path: configPath, error: formatError(error) };
+		const code = (error as NodeJS.ErrnoException).code;
+		return {
+			path: configPath,
+			error: `${fileName} could not be read${code ? ` (${safeErrorCode(code)})` : ""}`,
+		};
 	}
+	let raw: unknown;
+	try {
+		raw = JSON.parse(contents);
+	} catch {
+		return { path: configPath, error: `${fileName} contains malformed JSON` };
+	}
+	const settings = normalizeSubagentSettings(raw);
+	if (!isPlainObject(raw) || !settings) {
+		return { path: configPath, error: `${fileName} is not a valid settings object` };
+	}
+	return { path: configPath, raw, settings };
 }
 
 export function inspectSubagentSettings(): SubagentSettingsSnapshot {
@@ -343,6 +396,30 @@ export function inspectConsultResourceSettings(): ConsultResourceSettingsSnapsho
 	};
 }
 
+export function inspectCwdPolicySettings(): CwdPolicySettingsSnapshot {
+	const inspected = inspectSubagentSettingsDocument();
+	if (!inspected.raw || !inspected.settings) {
+		return {
+			path: inspected.path,
+			consultation: { value: DEFAULT_CONSULTATION_CWD_POLICY, source: "default" },
+			delegation: { value: DEFAULT_DELEGATION_CWD_POLICY, source: "default" },
+			...(inspected.error ? { error: inspected.error } : {}),
+		};
+	}
+	const rawPolicy = isPlainObject(inspected.raw.cwdPolicy) ? inspected.raw.cwdPolicy : undefined;
+	return {
+		path: inspected.path,
+		consultation: {
+			value: inspected.settings.cwdPolicy?.consultation ?? DEFAULT_CONSULTATION_CWD_POLICY,
+			source: rawPolicy && hasOwn(rawPolicy, "consultation") ? "user settings" : "default",
+		},
+		delegation: {
+			value: inspected.settings.cwdPolicy?.delegation ?? DEFAULT_DELEGATION_CWD_POLICY,
+			source: rawPolicy && hasOwn(rawPolicy, "delegation") ? "user settings" : "default",
+		},
+	};
+}
+
 export function inspectDelegationWorkflowSettings(): DelegationWorkflowSettingsSnapshot {
 	const inspected = inspectSubagentSettingsDocument();
 	if (!inspected.raw || !inspected.settings) {
@@ -458,6 +535,29 @@ export function updateConsultResourceSetting(value: ConsultResourcePolicy): void
 	});
 }
 
+export function updateCwdPolicySetting(field: "consultation", value: ConsultationCwdPolicy): void;
+export function updateCwdPolicySetting(field: "delegation", value: DelegationCwdPolicy): void;
+export function updateCwdPolicySetting(
+	field: "consultation" | "delegation",
+	value: ConsultationCwdPolicy | DelegationCwdPolicy,
+): void {
+	withSettingsMutationLock(() => {
+		const update = readSettingsObjectForUpdate();
+		const raw = update.document;
+		const cwdPolicy = raw.cwdPolicy;
+		if (cwdPolicy !== undefined && !isPlainObject(cwdPolicy)) {
+			throw new Error(`Cannot update invalid ${SETTINGS_FILE} cwdPolicy settings`);
+		}
+		writeSettingsObjectUnlocked(
+			{
+				...raw,
+				cwdPolicy: { ...(cwdPolicy ?? {}), [field]: value },
+			},
+			update.replaceCanonical,
+		);
+	});
+}
+
 export function updateAgentToolsSetting(name: string, tools: string[] | undefined): void {
 	withSettingsMutationLock(() => {
 		const update = readSettingsObjectForUpdate();
@@ -504,8 +604,8 @@ function readSettingsObjectForUpdate(): SettingsObjectForUpdate {
 	let parsed: unknown;
 	try {
 		parsed = JSON.parse(fs.readFileSync(activePath, "utf8"));
-	} catch (error) {
-		throw new Error(`Cannot update malformed ${activeFile}: ${formatError(error)}`);
+	} catch {
+		throw new Error(`Cannot update malformed ${activeFile}`);
 	}
 	if (!isPlainObject(parsed) || !normalizeSubagentSettings(parsed)) {
 		throw new Error(`Cannot update invalid ${activeFile}`);
@@ -585,8 +685,8 @@ function readSettingsSnapshot(configPath: string): {
 	}
 }
 
-function formatError(error: unknown) {
-	return error instanceof Error ? error.message : String(error);
+function safeErrorCode(value: string): string {
+	return value.replace(/[^A-Z0-9_-]/giu, "?").slice(0, 64);
 }
 
 export function uniqueToolNames(tools: string[]): string[] {

package/src/stateful-guidance.ts

@@ -0,0 +1,35 @@
+import type { CompletionDelivery } from "./agents.js";
+
+export function createSpawnPromptGuidelines(
+	completionDelivery: CompletionDelivery,
+	blockingEnabled = true,
+): string[] {
+	const deliveryGuidance =
+		completionDelivery === "auto-resume"
+			? blockingEnabled
+				? "With subagent_spawn completion delivery set to auto-resume, prefer one subagent_spawn for broad asynchronous research or review that covers related branches even when the final answer depends on its result; do not choose blocking parallel fan-out merely to keep delegation in the same turn."
+				: "With subagent_spawn completion delivery set to auto-resume, prefer one subagent_spawn for broad asynchronous research or review that covers related branches even when the final answer depends on its result."
+			: blockingEnabled
+				? "With subagent_spawn completion delivery set to next-turn (the default), prefer one subagent_spawn for broad asynchronous research or review only when the current response does not depend on its result; use the blocking subagent when the final answer depends on the detached result."
+				: "With subagent_spawn completion delivery set to next-turn (the default), use subagent_spawn only when the current response does not depend on its result; complete final-answer-dependent work directly because an idle root is not awakened.";
+	const noLocalWorkGuidance =
+		completionDelivery === "auto-resume"
+			? "After subagent_spawn returns, do useful non-overlapping local work immediately. If none remains, briefly tell the user what subagent_spawn launched and end the response; auto-resume will request a synthesis turn after completion."
+			: "After subagent_spawn returns, do useful non-overlapping local work immediately. If none remains, briefly tell the user what subagent_spawn launched and end the response only when the current response does not depend on its result; next-turn delivery will not wake an idle root.";
+	return [
+		"Do not use subagent_spawn for simple or critical-path work that the main agent can perform directly.",
+		"Set subagent_spawn thinkingLevel to the lowest sufficient thinking level for the delegated task: use off or minimal for extraction, formatting, or mechanical work; low for straightforward bounded work; medium for ordinary multi-step research or implementation; high for complex debugging, design, review, or cross-file analysis; xhigh for highly ambiguous, cross-system, or high-risk analysis; and max only for the hardest tasks when quality clearly outweighs latency and cost. Omit subagent_spawn thinkingLevel only to preserve the agent or child default.",
+		deliveryGuidance,
+		"Use a single subagent_spawn only for a concrete bounded subtask that can run independently and has an isolation or specialization benefit such as independent review, bounded context/output, a distinct model/tool profile, or workspace isolation.",
+		...(blockingEnabled
+			? [
+					"Use the blocking subagent instead of subagent_spawn when synchronous output is required before the main agent can continue and waiting is intentional; queued steering cannot be processed until that blocking call returns.",
+					"When subagent_spawn fits the completion-delivery policy, do not choose a blocking parallel subagent merely to keep delegation in the same turn.",
+				]
+			: []),
+		"Add another subagent_spawn only for truly independent work with safe workspace concurrency.",
+		noLocalWorkGuidance,
+		'Consume and synthesize available subagent_spawn completion messages; use subagent_manage with action "interrupt" or "close" for agents that are no longer needed.',
+		'Completion from subagent_spawn is delivered automatically. Do not poll with subagent_manage action "list" or subagent_mailbox action "read", repeatedly check progress, or duplicate the delegated work.',
+	];
+}

package/src/stateful-lifecycle.ts

@@ -0,0 +1,31 @@
+import type { AgentRegistry } from "./registry.js";
+import type { WorkspaceManager } from "./workspace.js";
+
+export async function disposeStatefulRuntime(
+	registry: AgentRegistry | undefined,
+	workspaceManager: WorkspaceManager,
+): Promise<unknown[]> {
+	const errors: unknown[] = [];
+	try {
+		await registry?.shutdown();
+	} catch (error) {
+		errors.push(error);
+	}
+	try {
+		await workspaceManager.cleanupAll();
+	} catch (error) {
+		errors.push(error);
+	}
+	return errors;
+}
+
+export function assertCurrentSpawn(
+	signal: AbortSignal | undefined,
+	generation: number,
+	currentGeneration: number,
+): void {
+	if (!signal?.aborted && generation === currentGeneration) return;
+	const error = new Error("Subagent spawn owner was replaced or aborted");
+	error.name = "AbortError";
+	throw error;
+}

package/src/stateful-render.ts

@@ -0,0 +1,249 @@
+import type { AgentToolResult } from "@earendil-works/pi-agent-core";
+import type { Theme, ToolRenderResultOptions } from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+import {
+	COLLAPSED_LIST_LIMIT,
+	expansionHint,
+	type RenderStatus,
+	recordList,
+	recordValue,
+	renderFallbackResult,
+	safeBlock,
+	safeLine,
+	statusBadge,
+	stringValue,
+	type ToolRendererContext,
+	textResult,
+	toolHeader,
+} from "./render-common.js";
+
+export type StatefulRenderTool = "spawn" | "send" | "manage" | "mailbox";
+
+export function createStatefulToolRenderer(tool: StatefulRenderTool) {
+	return {
+		renderCall(args: unknown, theme: Theme) {
+			return renderStatefulCall(tool, recordValue(args) ?? {}, theme);
+		},
+		renderResult(
+			result: AgentToolResult<unknown>,
+			options: ToolRenderResultOptions,
+			theme: Theme,
+			context: ToolRendererContext<unknown>,
+		) {
+			return renderStatefulResult(tool, result, options, theme, context);
+		},
+	};
+}
+
+function renderStatefulCall(tool: StatefulRenderTool, args: Record<string, unknown>, theme: Theme) {
+	if (tool === "spawn") {
+		const metadata = [
+			`[${safeLine(args.agentScope, "user", 64)}]`,
+			"detached",
+			safeLine(args.workspaceMode, "shared", 64),
+		];
+		if (typeof args.thinkingLevel === "string") metadata.push(`thinking:${args.thinkingLevel}`);
+		return new Text(
+			[
+				toolHeader(theme, "subagent_spawn", args.agent, metadata),
+				`  ${theme.fg("dim", safeLine(args.task, "...", 2 * 1024))}`,
+			].join("\n"),
+			0,
+			0,
+		);
+	}
+	if (tool === "send") {
+		return new Text(
+			[
+				toolHeader(theme, "subagent_send", args.agentId, ["follow-up"]),
+				`  ${theme.fg("dim", safeLine(args.task, "...", 2 * 1024))}`,
+			].join("\n"),
+			0,
+			0,
+		);
+	}
+	if (tool === "manage") {
+		const metadata: string[] = [];
+		if (typeof args.agentId === "string") metadata.push(`id:${safeLine(args.agentId, "", 256)}`);
+		if (args.subtree === true) metadata.push("subtree");
+		if (args.includeClosed === true) metadata.push("include closed");
+		return new Text(toolHeader(theme, "subagent_manage", args.action, metadata), 0, 0);
+	}
+	const metadata = [`id:${safeLine(args.agentId, "...", 256)}`];
+	if (args.action === "read") {
+		metadata.push(args.acknowledge === false ? "leave unread" : "acknowledge");
+	}
+	const lines = [toolHeader(theme, "subagent_mailbox", args.action, metadata)];
+	if (args.action === "send") {
+		lines.push(`  ${theme.fg("dim", safeLine(args.message, "...", 2 * 1024))}`);
+	}
+	return new Text(lines.join("\n"), 0, 0);
+}
+
+function renderStatefulResult(
+	tool: StatefulRenderTool,
+	result: AgentToolResult<unknown>,
+	options: ToolRenderResultOptions,
+	theme: Theme,
+	context: ToolRendererContext<unknown>,
+) {
+	const details = recordValue(result.details);
+	const args = recordValue(context.args) ?? {};
+	if (!details) return renderFallbackResult(result, options, theme, context.isError);
+	if (tool === "spawn" || tool === "send") {
+		const agent = recordValue(details.agent);
+		if (!agent) return renderFallbackResult(result, options, theme, context.isError);
+		return new Text(renderAgentResult(agent, result, options.expanded, theme), 0, 0);
+	}
+	if (tool === "manage") {
+		return new Text(renderManageResult(args, details, result, options.expanded, theme), 0, 0);
+	}
+	return new Text(renderMailboxResult(args, details, options.expanded, theme), 0, 0);
+}
+
+function renderAgentResult(
+	agent: Record<string, unknown>,
+	result: AgentToolResult<unknown>,
+	expanded: boolean,
+	theme: Theme,
+): string {
+	const state = safeLine(agent.state, "unknown", 128);
+	const lines = [
+		`${statusBadge(theme, lifecycleStatus(state))} · ${theme.fg("accent", safeLine(agent.id, "agent", 256))} · ${theme.fg("toolOutput", safeLine(agent.agent, "subagent", 256))} · ${theme.fg("muted", state)}`,
+	];
+	const thinking = stringValue(agent.thinkingLevel);
+	const unread = typeof agent.unreadMessages === "number" ? agent.unreadMessages : 0;
+	if (thinking || unread > 0) {
+		lines.push(
+			theme.fg(
+				"dim",
+				[thinking && `thinking:${safeLine(thinking, "", 128)}`, unread > 0 && `unread:${unread}`]
+					.filter(Boolean)
+					.join(" · "),
+			),
+		);
+	}
+	if (expanded) {
+		const task = safeBlock(agent.currentTask, "", 2 * 1024).trim();
+		const error = safeBlock(agent.error, "", 2 * 1024).trim();
+		if (task) lines.push(theme.fg("dim", `task: ${task}`));
+		if (error) lines.push(theme.fg("error", `error: ${error}`));
+		const content = safeBlock(textResult(result), "", 8 * 1024).trim();
+		if (content) lines.push(theme.fg("toolOutput", content));
+	} else lines.push(expansionHint());
+	return lines.join("\n");
+}
+
+function renderManageResult(
+	args: Record<string, unknown>,
+	details: Record<string, unknown>,
+	result: AgentToolResult<unknown>,
+	expanded: boolean,
+	theme: Theme,
+): string {
+	const action = safeLine(args.action, "action", 128);
+	const agents = recordList(details.agents);
+	const primary = recordValue(details.agent);
+	if (action === "list") {
+		const lines = [
+			`${statusBadge(theme, "completed")} · list · ${agents.length} agent${agents.length === 1 ? "" : "s"}`,
+		];
+		const selected = expanded ? agents : agents.slice(0, COLLAPSED_LIST_LIMIT);
+		for (const agent of selected) lines.push(formatAgentLine(agent, theme, expanded));
+		if (agents.length === 0) lines.push(theme.fg("muted", "(no retained agents)"));
+		if (agents.length > selected.length)
+			lines.push(theme.fg("muted", `… ${agents.length - selected.length} omitted`));
+		if (!expanded && agents.length > 0) lines.push(expansionHint());
+		return lines.join("\n");
+	}
+
+	const subtree = args.subtree === true;
+	const affected = subtree ? agents.length : agents.length > 0 ? agents.length : primary ? 1 : 0;
+	const status: RenderStatus = action === "interrupt" ? "interrupted" : "closed";
+	const lines = [
+		`${statusBadge(theme, status)} · ${affected} agent${affected === 1 ? "" : "s"}${subtree ? theme.fg("muted", " · subtree") : ""}`,
+	];
+	const selected = agents.length > 0 ? agents : !subtree && primary ? [primary] : [];
+	for (const agent of expanded ? selected : selected.slice(0, COLLAPSED_LIST_LIMIT)) {
+		lines.push(formatAgentLine(agent, theme, expanded));
+	}
+	if (selected.length === 0) {
+		const content = safeBlock(textResult(result), "(no output)", 8 * 1024);
+		lines.push(theme.fg("toolOutput", content));
+	}
+	if (!expanded && selected.length > 0) lines.push(expansionHint());
+	return lines.join("\n");
+}
+
+function renderMailboxResult(
+	args: Record<string, unknown>,
+	details: Record<string, unknown>,
+	expanded: boolean,
+	theme: Theme,
+): string {
+	const action = safeLine(args.action, "action", 64);
+	if (action === "send") {
+		const message = recordValue(details.message);
+		if (!message) return `${statusBadge(theme, "completed")} · Queued message`;
+		const lines = [
+			`${theme.fg("success", "✓")} ${theme.fg("success", "Queued")} · ${theme.fg("accent", safeLine(message.id, "message", 256))} · ${theme.fg("muted", `to ${safeLine(message.recipientId, safeLine(args.agentId), 256)}`)}`,
+		];
+		if (expanded) {
+			lines.push(theme.fg("toolOutput", safeBlock(message.content, "(empty message)", 2 * 1024)));
+		} else lines.push(expansionHint());
+		return lines.join("\n");
+	}
+
+	const messages = recordList(details.messages);
+	const acknowledged = args.acknowledge === false ? "left unread" : "acknowledged";
+	const lines = [
+		`${statusBadge(theme, "completed")} · ${messages.length} message${messages.length === 1 ? "" : "s"} · ${acknowledged}`,
+	];
+	const selected = expanded ? messages : messages.slice(0, COLLAPSED_LIST_LIMIT);
+	for (const message of selected) {
+		const content = expanded
+			? safeBlock(message.content, "(empty message)", 2 * 1024)
+			: safeLine(message.content, "(empty message)", 512);
+		lines.push(
+			`${theme.fg("muted", "• ")}${theme.fg("accent", safeLine(message.id, "message", 256))} ${theme.fg("muted", `from ${safeLine(message.senderId, "unknown", 256)}: `)}${theme.fg("toolOutput", content)}`,
+		);
+	}
+	if (messages.length === 0) lines.push(theme.fg("muted", "(no unread messages)"));
+	if (messages.length > selected.length)
+		lines.push(theme.fg("muted", `… ${messages.length - selected.length} omitted`));
+	if (!expanded && messages.length > 0) lines.push(expansionHint());
+	return lines.join("\n");
+}
+
+function formatAgentLine(agent: Record<string, unknown>, theme: Theme, expanded: boolean): string {
+	const unread = typeof agent.unreadMessages === "number" ? agent.unreadMessages : 0;
+	const lines = [
+		`${theme.fg("muted", "• ")}${theme.fg("accent", safeLine(agent.id, "agent", 256))} ${theme.fg("toolOutput", safeLine(agent.agent, "subagent", 256))} ${theme.fg("muted", safeLine(agent.state, "unknown", 128))}${unread > 0 ? theme.fg("warning", ` · unread:${unread}`) : ""}`,
+	];
+	if (expanded) {
+		const task = safeBlock(agent.currentTask, "", 2 * 1024).trim();
+		const error = safeBlock(agent.error, "", 2 * 1024).trim();
+		if (task) lines.push(`  ${theme.fg("dim", `task: ${task}`)}`);
+		if (error) lines.push(`  ${theme.fg("error", `error: ${error}`)}`);
+	}
+	return lines.join("\n");
+}
+
+function lifecycleStatus(state: string): RenderStatus {
+	switch (state) {
+		case "starting":
+			return "starting";
+		case "running":
+			return "running";
+		case "idle":
+			return "idle";
+		case "failed":
+			return "failed";
+		case "interrupted":
+			return "interrupted";
+		case "closed":
+			return "closed";
+		default:
+			return "completed";
+	}
+}

package/src/stateful-safety.ts

@@ -0,0 +1,91 @@
+import { realpathSync } from "node:fs";
+import * as path from "node:path";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { type AgentScope, discoverAgents, type SubagentSettings } from "./agents.js";
+import type { AgentRegistry, ManagedAgent } from "./registry.js";
+import { safeTerminalLine } from "./safe-text.js";
+import { readSubagentSettings } from "./settings.js";
+
+export function assertNoSharedWriteConflict(
+	registry: AgentRegistry,
+	agentName: string,
+	cwd: string,
+	scope: AgentScope,
+	settings?: SubagentSettings,
+): void {
+	const agents = discoverAgents(cwd, scope, settings ?? readSubagentSettings()).agents;
+	const requested = agents.find((agent) => agent.name === agentName);
+	if (!isWriteCapable(requested?.tools)) return;
+	for (const active of registry.list()) {
+		if (
+			!isSameCwd(active.cwd, cwd) ||
+			(active.state !== "running" && active.state !== "starting")
+		) {
+			continue;
+		}
+		const activeConfig = agents.find((agent) => agent.name === active.agent);
+		if (isWriteCapable(activeConfig?.tools)) {
+			throw new Error(
+				`Write-capable subagent ${active.id} is already active in shared workspace ${cwd}. ` +
+					"Prefer one subagent_spawn covering combined asynchronous work. Use the blocking subagent parallel mode only when concurrent synchronous outputs justify making the main agent unavailable. Otherwise let the active agent finish or close it; set allowConcurrentWrites only when overlapping writes are knowingly safe, or use workspaceMode worktree when repository isolation is needed.",
+			);
+		}
+	}
+}
+
+export function assertFollowUpWriteAllowed(
+	registry: AgentRegistry,
+	agent: ManagedAgent,
+	allowConcurrentWrites: boolean,
+	isolatedWorkspace: boolean,
+	settings?: SubagentSettings,
+): void {
+	if (allowConcurrentWrites || isolatedWorkspace) return;
+	assertNoSharedWriteConflict(
+		registry,
+		agent.agent,
+		agent.cwd,
+		agent.agentScope ?? "user",
+		settings,
+	);
+}
+
+export function isWriteCapable(tools: string[] | undefined): boolean {
+	if (!tools) return true;
+	return tools.some((tool) => ["bash", "write", "edit"].includes(tool));
+}
+
+export async function confirmProjectAgent(
+	name: string,
+	scope: AgentScope,
+	confirm: boolean,
+	ctx: ExtensionContext,
+	cwd: string,
+	settings?: SubagentSettings,
+): Promise<void> {
+	if (scope !== "project" && scope !== "both") return;
+	if (!isSameCwd(cwd, ctx.cwd)) {
+		throw new Error("Project-local subagent definitions cannot run with an overridden cwd");
+	}
+	if (!ctx.isProjectTrusted()) {
+		throw new Error("Project-local subagent definitions require a trusted project");
+	}
+	const discovery = discoverAgents(cwd, scope, settings ?? readSubagentSettings());
+	const agent = discovery.agents.find((candidate) => candidate.name === name);
+	if (agent?.source !== "project") return;
+	if (confirm && ctx.hasUI) {
+		const approved = await ctx.ui.confirm(
+			"Run project-local agent?",
+			`Agent: ${safeTerminalLine(name, 256)}\nSource: ${safeTerminalLine(agent.filePath)}`,
+		);
+		if (!approved) throw new Error("Project-local subagent was not approved");
+	}
+}
+
+function isSameCwd(left: string, right: string): boolean {
+	try {
+		return realpathSync(left) === realpathSync(right);
+	} catch {
+		return path.resolve(left) === path.resolve(right);
+	}
+}