@narumitw/pi-subagents 0.43.0 → 0.43.1

package/src/render.ts

@@ -1,4 +1,3 @@
-import * as os from "node:os";
 import type { AgentToolResult } from "@earendil-works/pi-agent-core";
 import type { Message } from "@earendil-works/pi-ai";
 import {
@@ -10,6 +9,7 @@ import {
 import { Container, Markdown, Spacer, Text } from "@earendil-works/pi-tui";
 import type { AgentScope, SubagentThinkingLevel } from "./agents.js";
 import { hasUsableAggregator, type SubagentParams } from "./params.js";
+import { expansionHint, formatToolActivity, safeBlock, safeLine } from "./render-common.js";
 import {
 	getResultFinalOutput,
 	isResultError,
@@ -17,15 +17,15 @@ import {
 	type SubagentDetails,
 } from "./runner.js";
 
-const COLLAPSED_ITEM_COUNT = 10;
+const COLLAPSED_ITEM_COUNT = 5;
 
 function previewTask(task: unknown, maxLength = 40): string {
-	if (typeof task !== "string" || task.length === 0) return "...";
-	return task.length > maxLength ? `${task.slice(0, maxLength)}...` : task;
+	const safe = safeLine(task, "...", 2 * 1024);
+	return safe.length > maxLength ? `${safe.slice(0, maxLength)}...` : safe;
 }
 
 function previewAgent(agent: unknown): string {
-	return typeof agent === "string" && agent.length > 0 ? agent : "...";
+	return safeLine(agent, "...", 256);
 }
 
 export function formatTokens(count: number): string {
@@ -59,12 +59,12 @@ export function formatUsageStats(
 	if (usage.cost) parts.push(`$${usage.cost.toFixed(4)}`);
 	if (usage.contextTokens && usage.contextTokens > 0)
 		parts.push(`ctx:${formatTokens(usage.contextTokens)}`);
+	const safeProvider = actualProvider ? safeLine(actualProvider, "", 256) : undefined;
+	const safeModel = actualModel ? safeLine(actualModel, "", 256) : undefined;
 	const actual =
-		actualProvider && actualModel
-			? `${actualProvider}/${actualModel}`
-			: (actualModel ?? actualProvider);
-	if (actual ?? model) parts.push(actual ?? model ?? "");
-	if (thinkingLevel) parts.push(`requested-thinking:${thinkingLevel}`);
+		safeProvider && safeModel ? `${safeProvider}/${safeModel}` : (safeModel ?? safeProvider);
+	if (actual ?? model) parts.push(actual ?? safeLine(model, "", 256));
+	if (thinkingLevel) parts.push(`requested-thinking:${safeLine(thinkingLevel, "", 128)}`);
 	return parts.join(" ");
 }
 
@@ -83,71 +83,7 @@ function formatToolCall(
 	args: Record<string, unknown>,
 	themeFg: (color: ThemeColor, text: string) => string,
 ): string {
-	const shortenPath = (p: string) => {
-		const home = os.homedir();
-		return p.startsWith(home) ? `~${p.slice(home.length)}` : p;
-	};
-
-	switch (toolName) {
-		case "bash": {
-			const command = (args.command as string) || "...";
-			const preview = command.length > 60 ? `${command.slice(0, 60)}...` : command;
-			return themeFg("muted", "$ ") + themeFg("toolOutput", preview);
-		}
-		case "read": {
-			const rawPath = (args.file_path || args.path || "...") as string;
-			const filePath = shortenPath(rawPath);
-			const offset = args.offset as number | undefined;
-			const limit = args.limit as number | undefined;
-			let text = themeFg("accent", filePath);
-			if (offset !== undefined || limit !== undefined) {
-				const startLine = offset ?? 1;
-				const endLine = limit !== undefined ? startLine + limit - 1 : "";
-				text += themeFg("warning", `:${startLine}${endLine ? `-${endLine}` : ""}`);
-			}
-			return themeFg("muted", "read ") + text;
-		}
-		case "write": {
-			const rawPath = (args.file_path || args.path || "...") as string;
-			const filePath = shortenPath(rawPath);
-			const content = (args.content || "") as string;
-			const lines = content.split("\n").length;
-			let text = themeFg("muted", "write ") + themeFg("accent", filePath);
-			if (lines > 1) text += themeFg("dim", ` (${lines} lines)`);
-			return text;
-		}
-		case "edit": {
-			const rawPath = (args.file_path || args.path || "...") as string;
-			return themeFg("muted", "edit ") + themeFg("accent", shortenPath(rawPath));
-		}
-		case "ls": {
-			const rawPath = (args.path || ".") as string;
-			return themeFg("muted", "ls ") + themeFg("accent", shortenPath(rawPath));
-		}
-		case "find": {
-			const pattern = (args.pattern || "*") as string;
-			const rawPath = (args.path || ".") as string;
-			return (
-				themeFg("muted", "find ") +
-				themeFg("accent", pattern) +
-				themeFg("dim", ` in ${shortenPath(rawPath)}`)
-			);
-		}
-		case "grep": {
-			const pattern = (args.pattern || "") as string;
-			const rawPath = (args.path || ".") as string;
-			return (
-				themeFg("muted", "grep ") +
-				themeFg("accent", `/${pattern}/`) +
-				themeFg("dim", ` in ${shortenPath(rawPath)}`)
-			);
-		}
-		default: {
-			const argsStr = JSON.stringify(args);
-			const preview = argsStr.length > 50 ? `${argsStr.slice(0, 50)}...` : argsStr;
-			return themeFg("accent", toolName) + themeFg("dim", ` ${preview}`);
-		}
-	}
+	return formatToolActivity(toolName, args, themeFg);
 }
 
 type DisplayItem =
@@ -160,10 +96,14 @@ function getDisplayItems(messages: Message[]): DisplayItem[] {
 		if (msg.role === "assistant") {
 			for (const part of msg.content) {
 				if (part.type === "text") {
-					const text = part.text.trim();
+					const text = safeBlock(part.text, "", 8 * 1024).trim();
 					if (text) items.push({ type: "text", text });
 				} else if (part.type === "toolCall") {
-					items.push({ type: "toolCall", name: part.name, args: part.arguments });
+					items.push({
+						type: "toolCall",
+						name: safeLine(part.name, "tool", 256),
+						args: part.arguments,
+					});
 				}
 			}
 		}
@@ -181,6 +121,47 @@ function getCollapsedDisplayItems(result: SingleResult): { items: DisplayItem[];
 	return { items, total: items.length };
 }
 
+function sanitizeSingleResultForRender(result: SingleResult): SingleResult {
+	return {
+		...result,
+		agent: safeLine(result.agent, "subagent", 256),
+		task: safeBlock(result.task, "", 50 * 1024),
+		stderr: safeBlock(result.stderr, "", 8 * 1024),
+		model: result.model ? safeLine(result.model, "", 256) : undefined,
+		actualProvider: result.actualProvider ? safeLine(result.actualProvider, "", 256) : undefined,
+		actualModel: result.actualModel ? safeLine(result.actualModel, "", 256) : undefined,
+		stopReason: result.stopReason ? safeLine(result.stopReason, "", 256) : undefined,
+		errorMessage: result.errorMessage ? safeBlock(result.errorMessage, "", 8 * 1024) : undefined,
+		finalOutput: result.finalOutput ? safeBlock(result.finalOutput, "", 50 * 1024) : undefined,
+	};
+}
+
+function renderResultStatus(result: SingleResult, isPartial: boolean): string {
+	if (isResultError(result)) {
+		return result.stopReason === "aborted" || result.aborted ? "Cancelled" : "Failed";
+	}
+	return isPartial || result.exitCode === -1 ? "Running" : "Completed";
+}
+
+function coloredStatus(theme: Theme, status: string): string {
+	const color: ThemeColor =
+		status === "Failed" ? "error" : status === "Completed" ? "success" : "warning";
+	return theme.fg(color, status);
+}
+
+function coloredResultStatus(theme: Theme, result: SingleResult, isPartial: boolean): string {
+	return coloredStatus(theme, renderResultStatus(result, isPartial));
+}
+
+function formatResultPolicy(result: SingleResult): string {
+	if (!result.policy) return "";
+	return [
+		`inherited: ${result.policy.inherited.map((tool) => safeLine(tool, "", 256)).join(", ") || "none"}`,
+		`overridden: ${result.policy.overridden.map((tool) => safeLine(tool, "", 256)).join(", ") || "none"}`,
+		`unsupported: ${result.policy.unsupported.map((tool) => safeLine(tool, "", 256)).join(", ") || "none"}`,
+	].join("\n");
+}
+
 export function renderSubagentCall(args: SubagentParams, theme: Theme) {
 	const scope: AgentScope = args.agentScope ?? "user";
 	if (args.chain && args.chain.length > 0) {
@@ -239,11 +220,22 @@ export function renderSubagentResult(
 	{ expanded, isPartial }: ToolRenderResultOptions,
 	theme: Theme,
 ) {
-	const details = result.details as SubagentDetails | undefined;
-	if (!details || details.results.length === 0) {
+	const rawDetails = result.details as SubagentDetails | undefined;
+	if (!rawDetails || rawDetails.results.length === 0) {
 		const text = result.content[0];
-		return new Text(text?.type === "text" ? text.text : "(no output)", 0, 0);
+		return new Text(
+			text?.type === "text" ? safeBlock(text.text, "(no output)", 8 * 1024) : "(no output)",
+			0,
+			0,
+		);
 	}
+	const details: SubagentDetails = {
+		...rawDetails,
+		results: rawDetails.results.map(sanitizeSingleResultForRender),
+		aggregator: rawDetails.aggregator
+			? sanitizeSingleResultForRender(rawDetails.aggregator)
+			: undefined,
+	};
 
 	const mdTheme = getMarkdownTheme();
 
@@ -254,7 +246,8 @@ export function renderSubagentResult(
 		if (skipped > 0) text += theme.fg("muted", `... ${skipped} earlier items\n`);
 		for (const item of toShow) {
 			if (item.type === "text") {
-				const preview = expanded ? item.text : item.text.split("\n").slice(0, 3).join("\n");
+				const safeText = safeBlock(item.text, "", 8 * 1024);
+				const preview = expanded ? safeText : safeText.split("\n").slice(0, 3).join("\n");
 				text += `${theme.fg("toolOutput", preview)}\n`;
 			} else {
 				text += `${theme.fg("muted", "→ ") + formatToolCall(item.name, item.args, theme.fg.bind(theme))}\n`;
@@ -276,7 +269,7 @@ export function renderSubagentResult(
 
 		if (expanded) {
 			const container = new Container();
-			let header = `${icon} ${theme.fg("toolTitle", theme.bold(r.agent))}${theme.fg("muted", ` (${r.agentSource})`)}`;
+			let header = `${icon} ${theme.fg("toolTitle", theme.bold(r.agent))}${theme.fg("muted", ` (${safeLine(r.agentSource, "unknown", 128)})`)} · ${coloredResultStatus(theme, r, isPartial)}`;
 			if (isError && r.stopReason) header += ` ${theme.fg("error", `[${r.stopReason}]`)}`;
 			container.addChild(new Text(header, 0, 0));
 			if (isError && r.errorMessage)
@@ -284,6 +277,12 @@ export function renderSubagentResult(
 			container.addChild(new Spacer(1));
 			container.addChild(new Text(theme.fg("muted", "─── Task ───"), 0, 0));
 			container.addChild(new Text(theme.fg("dim", r.task), 0, 0));
+			const policy = formatResultPolicy(r);
+			if (policy) {
+				container.addChild(new Spacer(1));
+				container.addChild(new Text(theme.fg("muted", "─── Policy ───"), 0, 0));
+				container.addChild(new Text(theme.fg("dim", policy), 0, 0));
+			}
 			container.addChild(new Spacer(1));
 			container.addChild(new Text(theme.fg("muted", "─── Output ───"), 0, 0));
 			if (displayItems.length === 0 && !finalOutput) {
@@ -314,15 +313,16 @@ export function renderSubagentResult(
 		}
 
 		const collapsed = getCollapsedDisplayItems(r);
-		let text = `${icon} ${theme.fg("toolTitle", theme.bold(r.agent))}${theme.fg("muted", ` (${r.agentSource})`)}`;
+		let text = `${icon} ${theme.fg("toolTitle", theme.bold(r.agent))}${theme.fg("muted", ` (${safeLine(r.agentSource, "unknown", 128)})`)} · ${coloredResultStatus(theme, r, isPartial)}`;
 		if (isError && r.stopReason) text += ` ${theme.fg("error", `[${r.stopReason}]`)}`;
 		if (isError && r.errorMessage) text += `\n${theme.fg("error", `Error: ${r.errorMessage}`)}`;
 		if (collapsed.items.length > 0) {
 			text += `\n${renderDisplayItems(collapsed.items, COLLAPSED_ITEM_COUNT, collapsed.total)}`;
-			if (collapsed.total > COLLAPSED_ITEM_COUNT)
-				text += `\n${theme.fg("muted", "(Ctrl+O to expand)")}`;
+			if (collapsed.total > COLLAPSED_ITEM_COUNT) text += `\n${expansionHint()}`;
 		} else if (finalOutput.trim()) {
-			text += `\n${theme.fg("toolOutput", finalOutput.trim().split("\n").slice(0, 3).join("\n"))}`;
+			const outputLines = finalOutput.trim().split("\n");
+			text += `\n${theme.fg("toolOutput", outputLines.slice(0, 3).join("\n"))}`;
+			if (outputLines.length > 3) text += `\n${expansionHint()}`;
 		} else if (!isError || !r.errorMessage) {
 			text += `\n${theme.fg("muted", isPartial && !isError ? "(running...)" : "(no output)")}`;
 		}
@@ -356,6 +356,11 @@ export function renderSubagentResult(
 			: successCount === details.results.length
 				? theme.fg("success", "✓")
 				: theme.fg("error", "✗");
+		const overallStatus = currentIsRunning
+			? "Running"
+			: successCount === details.results.length
+				? "Completed"
+				: "Failed";
 
 		if (expanded) {
 			const container = new Container();
@@ -364,7 +369,8 @@ export function renderSubagentResult(
 					icon +
 						" " +
 						theme.fg("toolTitle", theme.bold("chain ")) +
-						theme.fg("accent", `${successCount}/${details.results.length} steps`),
+						theme.fg("accent", `${successCount}/${details.results.length} steps`) +
+						` · ${coloredStatus(theme, overallStatus)}`,
 					0,
 					0,
 				),
@@ -383,12 +389,17 @@ export function renderSubagentResult(
 				container.addChild(new Spacer(1));
 				container.addChild(
 					new Text(
-						`${theme.fg("muted", `─── Step ${r.step}: `) + theme.fg("accent", r.agent)} ${rIcon}`,
+						`${theme.fg("muted", `─── Step ${r.step}: `) + theme.fg("accent", r.agent)} ${rIcon} ${coloredResultStatus(theme, r, currentIsRunning && r === currentResult)}`,
 						0,
 						0,
 					),
 				);
 				container.addChild(new Text(theme.fg("muted", "Task: ") + theme.fg("dim", r.task), 0, 0));
+				const policy = formatResultPolicy(r);
+				if (policy)
+					container.addChild(
+						new Text(theme.fg("muted", "Policy:\n") + theme.fg("dim", policy), 0, 0),
+					);
 				if (rFailed && r.errorMessage)
 					container.addChild(new Text(theme.fg("error", `Error: ${r.errorMessage}`), 0, 0));
 
@@ -429,7 +440,8 @@ export function renderSubagentResult(
 			icon +
 			" " +
 			theme.fg("toolTitle", theme.bold("chain ")) +
-			theme.fg("accent", `${successCount}/${details.results.length} steps`);
+			theme.fg("accent", `${successCount}/${details.results.length} steps`) +
+			` · ${coloredStatus(theme, overallStatus)}`;
 		for (const r of details.results) {
 			const rFailed = isResultError(r);
 			const rIcon = rFailed
@@ -439,7 +451,7 @@ export function renderSubagentResult(
 					: theme.fg("success", "✓");
 			const collapsed = getCollapsedDisplayItems(r);
 			const finalOutput = getResultFinalOutput(r).trim();
-			text += `\n\n${theme.fg("muted", `─── Step ${r.step}: `)}${theme.fg("accent", r.agent)} ${rIcon}`;
+			text += `\n\n${theme.fg("muted", `─── Step ${r.step}: `)}${theme.fg("accent", r.agent)} ${rIcon} ${coloredResultStatus(theme, r, currentIsRunning && r === currentResult)}`;
 			if (rFailed && r.errorMessage) text += `\n${theme.fg("error", `Error: ${r.errorMessage}`)}`;
 			if (collapsed.items.length > 0)
 				text += `\n${renderDisplayItems(collapsed.items, 5, collapsed.total)}`;
@@ -451,7 +463,7 @@ export function renderSubagentResult(
 		}
 		const usageStr = formatUsageStats(aggregateUsage(details.results));
 		if (usageStr) text += `\n\n${theme.fg("dim", `Total: ${usageStr}`)}`;
-		text += `\n${theme.fg("muted", "(Ctrl+O to expand)")}`;
+		text += `\n${expansionHint()}`;
 		return new Text(text, 0, 0);
 	}
 
@@ -485,12 +497,17 @@ export function renderSubagentResult(
 			: aggregator
 				? `${successCount}/${details.results.length} tasks + fan-in`
 				: `${successCount}/${details.results.length} tasks`;
+		const overallStatus = isRunning
+			? "Running"
+			: failCount > 0 || aggregatorFailed
+				? "Failed"
+				: "Completed";
 
 		if (expanded && !isRunning) {
 			const container = new Container();
 			container.addChild(
 				new Text(
-					`${icon} ${theme.fg("toolTitle", theme.bold("parallel "))}${theme.fg("accent", status)}`,
+					`${icon} ${theme.fg("toolTitle", theme.bold("parallel "))}${theme.fg("accent", status)} · ${coloredStatus(theme, overallStatus)}`,
 					0,
 					0,
 				),
@@ -508,9 +525,18 @@ export function renderSubagentResult(
 
 				container.addChild(new Spacer(1));
 				container.addChild(
-					new Text(`${theme.fg("muted", "─── ") + theme.fg("accent", r.agent)} ${rIcon}`, 0, 0),
+					new Text(
+						`${theme.fg("muted", "─── ") + theme.fg("accent", r.agent)} ${rIcon} ${coloredResultStatus(theme, r, resultIsRunning(r))}`,
+						0,
+						0,
+					),
 				);
 				container.addChild(new Text(theme.fg("muted", "Task: ") + theme.fg("dim", r.task), 0, 0));
+				const policy = formatResultPolicy(r);
+				if (policy)
+					container.addChild(
+						new Text(theme.fg("muted", "Policy:\n") + theme.fg("dim", policy), 0, 0),
+					);
 				if (rFailed && r.errorMessage)
 					container.addChild(new Text(theme.fg("error", `Error: ${r.errorMessage}`), 0, 0));
 
@@ -550,7 +576,7 @@ export function renderSubagentResult(
 				container.addChild(new Spacer(1));
 				container.addChild(
 					new Text(
-						`${theme.fg("muted", "─── fan-in → ") + theme.fg("accent", aggregator.agent)} ${rIcon}`,
+						`${theme.fg("muted", "─── fan-in → ") + theme.fg("accent", aggregator.agent)} ${rIcon} ${coloredResultStatus(theme, aggregator, aggregatorRunning)}`,
 						0,
 						0,
 					),
@@ -558,6 +584,11 @@ export function renderSubagentResult(
 				container.addChild(
 					new Text(theme.fg("muted", "Task: ") + theme.fg("dim", aggregator.task), 0, 0),
 				);
+				const aggregatorPolicy = formatResultPolicy(aggregator);
+				if (aggregatorPolicy)
+					container.addChild(
+						new Text(theme.fg("muted", "Policy:\n") + theme.fg("dim", aggregatorPolicy), 0, 0),
+					);
 				if (aggregatorFailed && aggregator.errorMessage)
 					container.addChild(
 						new Text(theme.fg("error", `Error: ${aggregator.errorMessage}`), 0, 0),
@@ -592,7 +623,7 @@ export function renderSubagentResult(
 		}
 
 		// Collapsed view (or still running)
-		let text = `${icon} ${theme.fg("toolTitle", theme.bold("parallel "))}${theme.fg("accent", status)}`;
+		let text = `${icon} ${theme.fg("toolTitle", theme.bold("parallel "))}${theme.fg("accent", status)} · ${coloredStatus(theme, overallStatus)}`;
 		for (const r of details.results) {
 			const rFailed = isResultError(r);
 			const rRunning = resultIsRunning(r);
@@ -603,7 +634,7 @@ export function renderSubagentResult(
 					: theme.fg("success", "✓");
 			const collapsed = getCollapsedDisplayItems(r);
 			const finalOutput = getResultFinalOutput(r).trim();
-			text += `\n\n${theme.fg("muted", "─── ")}${theme.fg("accent", r.agent)} ${rIcon}`;
+			text += `\n\n${theme.fg("muted", "─── ")}${theme.fg("accent", r.agent)} ${rIcon} ${coloredResultStatus(theme, r, rRunning)}`;
 			if (rFailed && r.errorMessage) text += `\n${theme.fg("error", `Error: ${r.errorMessage}`)}`;
 			if (collapsed.items.length > 0)
 				text += `\n${renderDisplayItems(collapsed.items, 5, collapsed.total)}`;
@@ -620,7 +651,7 @@ export function renderSubagentResult(
 					: theme.fg("success", "✓");
 			const collapsed = getCollapsedDisplayItems(aggregator);
 			const finalOutput = getResultFinalOutput(aggregator).trim();
-			text += `\n\n${theme.fg("muted", "─── fan-in → ")}${theme.fg("accent", aggregator.agent)} ${rIcon}`;
+			text += `\n\n${theme.fg("muted", "─── fan-in → ")}${theme.fg("accent", aggregator.agent)} ${rIcon} ${coloredResultStatus(theme, aggregator, aggregatorRunning)}`;
 			if (aggregatorFailed && aggregator.errorMessage)
 				text += `\n${theme.fg("error", `Error: ${aggregator.errorMessage}`)}`;
 			if (collapsed.items.length > 0)
@@ -636,10 +667,14 @@ export function renderSubagentResult(
 			const usageStr = formatUsageStats(aggregateUsage(usageResults));
 			if (usageStr) text += `\n\n${theme.fg("dim", `Total: ${usageStr}`)}`;
 		}
-		if (!expanded) text += `\n${theme.fg("muted", "(Ctrl+O to expand)")}`;
+		if (!expanded) text += `\n${expansionHint()}`;
 		return new Text(text, 0, 0);
 	}
 
 	const text = result.content[0];
-	return new Text(text?.type === "text" ? text.text : "(no output)", 0, 0);
+	return new Text(
+		text?.type === "text" ? safeBlock(text.text, "(no output)", 8 * 1024) : "(no output)",
+		0,
+		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,
@@ -81,6 +82,7 @@ export interface SingleResult {
 	malformedEvents?: number;
 	launchFailed?: boolean;
 	processStarted?: boolean;
+	target?: TargetPolicyAudit;
 	policy?: {
 		inherited: string[];
 		overridden: string[];

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.',
+	];
+}