@narumitw/pi-subagents 0.41.0 → 0.43.0

package/src/runner.ts

@@ -12,6 +12,7 @@ import {
 	DEFAULT_MAX_MESSAGES,
 	DEFAULT_MAX_OUTPUT_BYTES,
 	DEFAULT_MAX_STDERR_BYTES,
+	MAX_SUBAGENT_TIMEOUT_MS,
 	truncateUtf8,
 } from "./limits.js";
 import { JsonLineDecoder } from "./protocol.js";
@@ -24,6 +25,11 @@ export interface UsageStats {
 	cacheRead: number;
 	cacheWrite: number;
 	cost: number;
+	costInput?: number;
+	costOutput?: number;
+	costCacheRead?: number;
+	costCacheWrite?: number;
+	totalTokens?: number;
 	contextTokens: number;
 	turns: number;
 }
@@ -34,6 +40,21 @@ export type RecentActivityItem =
 const MAX_RECENT_ACTIVITY_ITEMS = 10;
 const MAX_RECENT_ACTIVITY_BYTES = 8 * 1024;
 const MAX_RECENT_ACTIVITY_ARGUMENT_BYTES = 1024;
+const MAX_USAGE_VALUE = Number.MAX_SAFE_INTEGER;
+
+function protocolUsageCount(value: unknown): number {
+	return typeof value === "number" && Number.isSafeInteger(value) && value >= 0 ? value : 0;
+}
+
+function protocolUsageCost(value: unknown): number {
+	return typeof value === "number" && Number.isFinite(value) && value >= 0
+		? Math.min(value, MAX_USAGE_VALUE)
+		: 0;
+}
+
+function addUsageValue(current: number, addition: number): number {
+	return Math.min(MAX_USAGE_VALUE, current + addition);
+}
 
 export interface SingleResult {
 	agent: string;
@@ -58,6 +79,8 @@ export interface SingleResult {
 	aborted?: boolean;
 	truncated?: boolean;
 	malformedEvents?: number;
+	launchFailed?: boolean;
+	processStarted?: boolean;
 	policy?: {
 		inherited: string[];
 		overridden: string[];
@@ -288,20 +311,41 @@ async function writePromptToTempFile(
 	return { dir: tmpDir, filePath };
 }
 
-export function buildPiArgs(options: {
+export interface PiArgsOptions {
 	model?: string;
 	thinkingLevel?: SubagentThinkingLevel;
 	tools?: string[];
+	disableExtensions?: boolean;
+	disableSkills?: boolean;
+	disablePromptTemplates?: boolean;
+	disableContextFiles?: boolean;
+	projectTrust?: boolean;
+	baseSystemPromptPath?: string;
+	appendSystemPromptPaths?: string[];
+	/** Existing single append prompt path retained for compatibility. */
 	systemPromptPath?: string;
 	task: string;
-}): string[] {
+}
+
+export function buildPiArgs(options: PiArgsOptions): string[] {
 	const args: string[] = ["--mode", "json", "-p", "--no-session"];
 	if (options.model) args.push("--model", options.model);
 	if (options.thinkingLevel) args.push("--thinking", options.thinkingLevel);
+	if (options.disableExtensions) args.push("--no-extensions");
+	if (options.disableSkills) args.push("--no-skills");
+	if (options.disablePromptTemplates) args.push("--no-prompt-templates");
+	if (options.disableContextFiles) args.push("--no-context-files");
+	if (options.projectTrust !== undefined) {
+		args.push(options.projectTrust ? "--approve" : "--no-approve");
+	}
 	if (Array.isArray(options.tools)) {
 		if (options.tools.length > 0) args.push("--tools", options.tools.join(","));
 		else args.push("--no-tools");
 	}
+	if (options.baseSystemPromptPath) args.push("--system-prompt", options.baseSystemPromptPath);
+	for (const promptPath of options.appendSystemPromptPaths ?? []) {
+		args.push("--append-system-prompt", promptPath);
+	}
 	if (options.systemPromptPath) args.push("--append-system-prompt", options.systemPromptPath);
 	args.push(`Task: ${options.task}`);
 	return args;
@@ -365,6 +409,17 @@ export function terminateProcess(
 
 export type OnUpdateCallback = (partial: AgentToolResult<SubagentDetails>) => void;
 
+export interface ChildLaunchPolicy {
+	tools?: string[];
+	disableExtensions?: boolean;
+	disableSkills?: boolean;
+	disablePromptTemplates?: boolean;
+	disableContextFiles?: boolean;
+	projectTrust?: boolean;
+	baseSystemPrompt?: string;
+	appendSystemPromptPaths?: string[];
+}
+
 export async function runSingleAgent(
 	defaultCwd: string,
 	agents: AgentConfig[],
@@ -378,6 +433,7 @@ export async function runSingleAgent(
 	onUpdate: OnUpdateCallback | undefined,
 	makeDetails: (results: SingleResult[]) => SubagentDetails,
 	invocationOverride?: { command: string; argsPrefix?: string[] },
+	launchPolicy?: ChildLaunchPolicy,
 ): Promise<SingleResult> {
 	const agent = agents.find((a) => a.name === agentName);
 
@@ -405,8 +461,9 @@ export async function runSingleAgent(
 		};
 	}
 
-	let tmpPromptDir: string | null = null;
+	const temporaryPrompts: Array<{ dir: string; filePath: string }> = [];
 	let tmpPromptPath: string | null = null;
+	let baseSystemPromptPath: string | null = null;
 
 	let latestAssistantOutput = "";
 	let terminalAssistantOutput: string | undefined;
@@ -474,17 +531,46 @@ export async function runSingleAgent(
 			setErrorMessage("Subagent was aborted before start");
 			return currentResult;
 		}
+		if (!Number.isFinite(timeoutMs) || timeoutMs < 1 || timeoutMs > MAX_SUBAGENT_TIMEOUT_MS) {
+			currentResult.exitCode = 1;
+			currentResult.stopReason = "error";
+			setErrorMessage(
+				`Invalid subagent timeout: expected 1-${MAX_SUBAGENT_TIMEOUT_MS}ms, received ${timeoutMs}`,
+			);
+			return currentResult;
+		}
 
+		if (launchPolicy?.baseSystemPrompt?.trim()) {
+			const tmp = await writePromptToTempFile(`${agent.name}-base`, launchPolicy.baseSystemPrompt);
+			temporaryPrompts.push(tmp);
+			baseSystemPromptPath = tmp.filePath;
+		}
 		if (agent.systemPrompt.trim()) {
 			const tmp = await writePromptToTempFile(agent.name, agent.systemPrompt);
-			tmpPromptDir = tmp.dir;
+			temporaryPrompts.push(tmp);
 			tmpPromptPath = tmp.filePath;
 		}
+		if (signal?.aborted) {
+			currentResult.exitCode = 130;
+			currentResult.aborted = true;
+			currentResult.stopReason = "aborted";
+			setErrorMessage("Subagent was aborted before launch");
+			return currentResult;
+		}
 
+		const effectiveTools =
+			launchPolicy && Object.hasOwn(launchPolicy, "tools") ? launchPolicy.tools : agent.tools;
 		const args = buildPiArgs({
 			model: agent.model,
 			thinkingLevel,
-			tools: agent.tools,
+			tools: effectiveTools,
+			disableExtensions: launchPolicy?.disableExtensions,
+			disableSkills: launchPolicy?.disableSkills,
+			disablePromptTemplates: launchPolicy?.disablePromptTemplates,
+			disableContextFiles: launchPolicy?.disableContextFiles,
+			projectTrust: launchPolicy?.projectTrust,
+			baseSystemPromptPath: baseSystemPromptPath ?? undefined,
+			appendSystemPromptPaths: launchPolicy?.appendSystemPromptPaths,
 			systemPromptPath: tmpPromptPath ?? undefined,
 			task,
 		});
@@ -525,6 +611,7 @@ export async function runSingleAgent(
 					},
 				});
 			} catch (error) {
+				currentResult.launchFailed = true;
 				currentResult.stderr = setErrorMessage(
 					error instanceof Error ? error.message : String(error),
 				);
@@ -576,19 +663,62 @@ export async function runSingleAgent(
 					if (msg.role === "assistant") {
 						currentResult.usage.turns++;
 						const usage = msg.usage;
-						if (usage) {
-							currentResult.usage.input += usage.input || 0;
-							currentResult.usage.output += usage.output || 0;
-							currentResult.usage.cacheRead += usage.cacheRead || 0;
-							currentResult.usage.cacheWrite += usage.cacheWrite || 0;
-							currentResult.usage.cost += usage.cost?.total || 0;
-							currentResult.usage.contextTokens = usage.totalTokens || 0;
+						if (usage && typeof usage === "object") {
+							const input = protocolUsageCount(usage.input);
+							const output = protocolUsageCount(usage.output);
+							const cacheRead = protocolUsageCount(usage.cacheRead);
+							const cacheWrite = protocolUsageCount(usage.cacheWrite);
+							const reportedTotal = protocolUsageCount(usage.totalTokens);
+							const turnTotal =
+								reportedTotal ||
+								addUsageValue(addUsageValue(input, output), addUsageValue(cacheRead, cacheWrite));
+							const cost = usage.cost && typeof usage.cost === "object" ? usage.cost : undefined;
+							currentResult.usage.input = addUsageValue(currentResult.usage.input, input);
+							currentResult.usage.output = addUsageValue(currentResult.usage.output, output);
+							currentResult.usage.cacheRead = addUsageValue(
+								currentResult.usage.cacheRead,
+								cacheRead,
+							);
+							currentResult.usage.cacheWrite = addUsageValue(
+								currentResult.usage.cacheWrite,
+								cacheWrite,
+							);
+							currentResult.usage.cost = addUsageValue(
+								currentResult.usage.cost,
+								protocolUsageCost(cost?.total),
+							);
+							currentResult.usage.costInput = addUsageValue(
+								currentResult.usage.costInput ?? 0,
+								protocolUsageCost(cost?.input),
+							);
+							currentResult.usage.costOutput = addUsageValue(
+								currentResult.usage.costOutput ?? 0,
+								protocolUsageCost(cost?.output),
+							);
+							currentResult.usage.costCacheRead = addUsageValue(
+								currentResult.usage.costCacheRead ?? 0,
+								protocolUsageCost(cost?.cacheRead),
+							);
+							currentResult.usage.costCacheWrite = addUsageValue(
+								currentResult.usage.costCacheWrite ?? 0,
+								protocolUsageCost(cost?.cacheWrite),
+							);
+							currentResult.usage.totalTokens = addUsageValue(
+								currentResult.usage.totalTokens ?? 0,
+								turnTotal,
+							);
+							currentResult.usage.contextTokens = turnTotal;
 						}
-						if (msg.provider) currentResult.actualProvider = msg.provider;
-						if (msg.responseModel ?? msg.model)
-							currentResult.actualModel = msg.responseModel ?? msg.model;
-						if (msg.stopReason) currentResult.stopReason = msg.stopReason;
-						if (msg.errorMessage) setErrorMessage(msg.errorMessage);
+						if (typeof msg.provider === "string") currentResult.actualProvider = msg.provider;
+						const actualModel =
+							typeof msg.responseModel === "string"
+								? msg.responseModel
+								: typeof msg.model === "string"
+									? msg.model
+									: undefined;
+						if (actualModel) currentResult.actualModel = actualModel;
+						if (typeof msg.stopReason === "string") currentResult.stopReason = msg.stopReason;
+						if (typeof msg.errorMessage === "string") setErrorMessage(msg.errorMessage);
 					}
 					emitUpdate();
 				} else if (event.type === "tool_result_end" && event.message) {
@@ -623,6 +753,9 @@ export async function runSingleAgent(
 			}, timeoutMs);
 			timeout.unref();
 
+			proc.once("spawn", () => {
+				currentResult.processStarted = true;
+			});
 			proc.stdout?.on("data", (data) => decoder.push(data));
 			proc.stderr?.on("data", (data) => {
 				const bounded = appendBounded(
@@ -638,6 +771,7 @@ export async function runSingleAgent(
 				finish(timedOut ? 124 : wasAborted ? 130 : (code ?? 0));
 			});
 			proc.on("error", (error) => {
+				currentResult.launchFailed = true;
 				const message = setErrorMessage(error.message);
 				const bounded = appendBounded(
 					currentResult.stderr,
@@ -682,23 +816,27 @@ export async function runSingleAgent(
 				"cwd",
 				...(agent.model ? ["model"] : []),
 				...(thinkingLevel ? ["thinkingLevel"] : []),
-				...(agent.tools ? ["tools"] : []),
+				...(effectiveTools !== undefined ? ["tools"] : []),
+				...(launchPolicy?.disableExtensions ? ["extensions"] : []),
+				...(launchPolicy?.disableSkills ? ["skills"] : []),
+				...(launchPolicy?.disablePromptTemplates ? ["promptTemplates"] : []),
+				...(launchPolicy?.disableContextFiles ? ["contextFiles"] : []),
 			],
 			unsupported: ["approvalPolicy", "sandboxProfile", "providerHeaders"],
 		};
 		return currentResult;
 	} finally {
-		if (tmpPromptPath)
+		for (const temporary of temporaryPrompts.reverse()) {
 			try {
-				fs.unlinkSync(tmpPromptPath);
+				fs.unlinkSync(temporary.filePath);
 			} catch {
 				/* ignore */
 			}
-		if (tmpPromptDir)
 			try {
-				fs.rmdirSync(tmpPromptDir);
+				fs.rmdirSync(temporary.dir);
 			} catch {
 				/* ignore */
 			}
+		}
 	}
 }

package/src/safe-text.ts

@@ -0,0 +1,67 @@
+import * as os from "node:os";
+import * as path from "node:path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import { redactPrivateText } from "./context.js";
+import { DEFAULT_MAX_OUTPUT_BYTES, TRUNCATION_MARKER, truncateUtf8 } from "./limits.js";
+
+export const DEFAULT_MAX_OUTPUT_LINES = 2_000;
+
+export function safeTerminalText(value: string): string {
+	return (
+		value
+			// biome-ignore lint/suspicious/noControlCharactersInRegex: Escape untrusted terminal controls while preserving newlines.
+			.replace(/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f-\u009f]/gu, "?")
+			.replace(/\r/gu, "")
+	);
+}
+
+export function safeTerminalLine(value: string, maxBytes = 2 * 1024): string {
+	const singleLine = safeTerminalText(redactPrivateText(value)).replace(/\s+/gu, " ").trim();
+	return truncateUtf8(singleLine, maxBytes).text.replace(/\s+/gu, " ").trim();
+}
+
+export function boundText(
+	value: string,
+	maxBytes = DEFAULT_MAX_OUTPUT_BYTES,
+	maxLines = DEFAULT_MAX_OUTPUT_LINES,
+): { text: string; truncated: boolean } {
+	const safe = safeTerminalText(value);
+	const lines = safe.split("\n");
+	const lineBounded =
+		lines.length > maxLines
+			? `${lines.slice(0, Math.max(0, maxLines - 1)).join("\n")}${TRUNCATION_MARKER}`
+			: safe;
+	const bounded = truncateUtf8(lineBounded, maxBytes);
+	return { text: bounded.text, truncated: lines.length > maxLines || bounded.truncated };
+}
+
+export function boundedPrivateText(value: string, maxBytes: number): string {
+	return boundText(redactPrivateText(value), maxBytes).text;
+}
+
+export function safeDisplayPath(value: string, workspace: string): string {
+	if (value.startsWith("built-in:")) return safeTerminalLine(value);
+	const resolved = path.resolve(value);
+	const agentDir = path.resolve(getAgentDir());
+	const relativeAgent = path.relative(agentDir, resolved);
+	if (
+		relativeAgent === "" ||
+		(!relativeAgent.startsWith("..") && !path.isAbsolute(relativeAgent))
+	) {
+		return relativeAgent ? `~/${safeTerminalLine(relativeAgent)}` : "~";
+	}
+	const resolvedWorkspace = path.resolve(workspace);
+	const relativeWorkspace = path.relative(resolvedWorkspace, resolved);
+	if (
+		relativeWorkspace === "" ||
+		(!relativeWorkspace.startsWith("..") && !path.isAbsolute(relativeWorkspace))
+	) {
+		return relativeWorkspace ? safeTerminalLine(relativeWorkspace) : ".";
+	}
+	const home = path.resolve(os.homedir());
+	const relativeHome = path.relative(home, resolved);
+	if (relativeHome === "" || (!relativeHome.startsWith("..") && !path.isAbsolute(relativeHome))) {
+		return relativeHome ? `~/${safeTerminalLine(relativeHome)}` : "~";
+	}
+	return safeTerminalLine(resolved);
+}

package/src/settings.ts

@@ -5,12 +5,15 @@ import { getAgentDir } from "@earendil-works/pi-coding-agent";
 import lockfile from "proper-lockfile";
 import {
 	type AgentConfig,
+	CONSULT_RESOURCE_POLICIES,
 	type CompletionDelivery,
+	type ConsultResourcePolicy,
 	isThinkingLevel,
 	type SubagentAgentConfig,
 	type SubagentSettings,
 	type SubagentThinkingLevel,
 } from "./agents.js";
+import { MAX_SUBAGENT_TIMEOUT_MS } from "./limits.js";
 
 export function hasOwn(obj: object, key: PropertyKey): boolean {
 	return Object.hasOwn(obj, key);
@@ -61,7 +64,12 @@ export function normalizeAgentSettings(value: unknown): SubagentAgentConfig | un
 	}
 
 	if (hasOwn(value, "timeoutMs")) {
-		if (value.timeoutMs !== null && !isPositiveNumber(value.timeoutMs)) return undefined;
+		if (
+			value.timeoutMs !== null &&
+			(!isPositiveNumber(value.timeoutMs) || value.timeoutMs > MAX_SUBAGENT_TIMEOUT_MS)
+		) {
+			return undefined;
+		}
 		config.timeoutMs = value.timeoutMs;
 		hasKnownField = true;
 	}
@@ -136,12 +144,27 @@ export function normalizeSubagentSettings(value: unknown): SubagentSettings | un
 		}
 		settings.stateful = runtime;
 	}
+	if (hasOwn(value, "consult")) {
+		if (!isPlainObject(value.consult)) return undefined;
+		const consult: NonNullable<SubagentSettings["consult"]> = {};
+		if (hasOwn(value.consult, "resources")) {
+			if (
+				typeof value.consult.resources !== "string" ||
+				!CONSULT_RESOURCE_POLICIES.includes(value.consult.resources as ConsultResourcePolicy)
+			) {
+				return undefined;
+			}
+			consult.resources = value.consult.resources as ConsultResourcePolicy;
+		}
+		settings.consult = consult;
+	}
 	return settings;
 }
 
 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";
 const SETTINGS_LOCK_FS_ADAPTER = {
 	mkdir: fs.mkdir,
 	mkdirSync: fs.mkdirSync,
@@ -231,6 +254,20 @@ export interface CompletionDeliverySettingsSnapshot {
 	error?: string;
 }
 
+export interface ConsultResourceSettingsSnapshot {
+	path: string;
+	value: ConsultResourcePolicy;
+	source: "default" | "user settings";
+	error?: string;
+}
+
+export interface SubagentSettingsSnapshot {
+	path: string;
+	settings?: SubagentSettings;
+	source: "default" | "user settings";
+	error?: string;
+}
+
 export function subagentSettingsFilePath(): string {
 	return path.join(getAgentDir(), SETTINGS_FILE);
 }
@@ -277,6 +314,35 @@ function inspectSubagentSettingsPath(configPath: string): {
 	}
 }
 
+export function inspectSubagentSettings(): SubagentSettingsSnapshot {
+	const inspected = inspectSubagentSettingsDocument();
+	return {
+		path: inspected.path,
+		settings: inspected.settings,
+		source: inspected.settings ? "user settings" : "default",
+		...(inspected.error ? { error: inspected.error } : {}),
+	};
+}
+
+export function inspectConsultResourceSettings(): ConsultResourceSettingsSnapshot {
+	const inspected = inspectSubagentSettingsDocument();
+	if (!inspected.raw || !inspected.settings) {
+		return {
+			path: inspected.path,
+			value: DEFAULT_CONSULT_RESOURCE_POLICY,
+			source: "default",
+			...(inspected.error ? { error: inspected.error } : {}),
+		};
+	}
+	const explicit =
+		isPlainObject(inspected.raw.consult) && hasOwn(inspected.raw.consult, "resources");
+	return {
+		path: inspected.path,
+		value: inspected.settings.consult?.resources ?? DEFAULT_CONSULT_RESOURCE_POLICY,
+		source: explicit ? "user settings" : "default",
+	};
+}
+
 export function inspectDelegationWorkflowSettings(): DelegationWorkflowSettingsSnapshot {
 	const inspected = inspectSubagentSettingsDocument();
 	if (!inspected.raw || !inspected.settings) {
@@ -371,6 +437,27 @@ export function updateCompletionDeliverySetting(value: CompletionDelivery): void
 	});
 }
 
+export function updateConsultResourceSetting(value: ConsultResourcePolicy): void {
+	withSettingsMutationLock(() => {
+		const update = readSettingsObjectForUpdate();
+		const raw = update.document;
+		const consult = raw.consult;
+		if (consult !== undefined && !isPlainObject(consult)) {
+			throw new Error(`Cannot update invalid ${SETTINGS_FILE} consult settings`);
+		}
+		writeSettingsObjectUnlocked(
+			{
+				...raw,
+				consult: {
+					...(consult ?? {}),
+					resources: value,
+				},
+			},
+			update.replaceCanonical,
+		);
+	});
+}
+
 export function updateAgentToolsSetting(name: string, tools: string[] | undefined): void {
 	withSettingsMutationLock(() => {
 		const update = readSettingsObjectForUpdate();

package/src/stateful.ts

@@ -24,7 +24,14 @@ import {
 } from "./in-process-transport.js";
 import { DEFAULT_MAX_CONTEXT_BYTES, truncateUtf8 } from "./limits.js";
 import { AgentPersistence } from "./persistence.js";
-import { AgentRegistry, type AgentTurnCompletion, type ManagedAgent } from "./registry.js";
+import {
+	AgentRegistry,
+	type AgentRunInspectionDetail,
+	type AgentRunInspectionSummary,
+	type AgentTurnCompletion,
+	type ManagedAgent,
+} from "./registry.js";
+import { safeTerminalLine } from "./safe-text.js";
 import { readSubagentSettings } from "./settings.js";
 import {
 	MailboxParamsSchema,
@@ -109,6 +116,8 @@ export interface StatefulSubagentController {
 	setAgentCatalog(value: string): void;
 	getRuntimeStatus(): StatefulSubagentRuntimeStatus;
 	listAgents(includeClosed?: boolean): ManagedAgent[];
+	listRunInspection(includeClosed?: boolean): AgentRunInspectionSummary[];
+	getRunInspection(agentId: string): AgentRunInspectionDetail | undefined;
 	clearAgents(): Promise<number>;
 }
 
@@ -168,21 +177,24 @@ export function registerStatefulSubagents(
 			refreshSpawnToolRegistration?.();
 		},
 		getRuntimeStatus() {
-			const agents = registry?.list(true) ?? [];
+			const counts = registry?.inspectionCounts() ?? { activeAgents: 0, retainedAgents: 0 };
 			return {
 				enabled,
 				initialized: registry !== undefined,
 				transport: transportKind,
 				completionDelivery,
-				activeAgents: agents.filter(
-					(agent) => agent.state === "starting" || agent.state === "running",
-				).length,
-				retainedAgents: agents.filter((agent) => agent.state !== "closed").length,
+				...counts,
 			};
 		},
 		listAgents(includeClosed = false) {
 			return registry?.list(includeClosed) ?? [];
 		},
+		listRunInspection(includeClosed = false) {
+			return registry?.listInspection(includeClosed) ?? [];
+		},
+		getRunInspection(agentId) {
+			return registry?.getInspection(agentId);
+		},
 		clearAgents,
 	};
 	if (!enabled) return controller;
@@ -450,7 +462,7 @@ export function registerStatefulSubagents(
 		name: "subagent_manage",
 		label: "Manage Subagents",
 		description:
-			"List retained subagents, interrupt active work while keeping an agent reusable, or close agents and release their resources.",
+			"List retained subagents through the compatibility route, interrupt active work while keeping an agent reusable, or close agents and release their resources. Prefer subagent_inspect when the whole activated capability must be read-only.",
 		promptSnippet: "List or control retained detached subagents",
 		parameters: ManageParamsSchema,
 		async execute(_id, params): Promise<StatefulActionToolResult> {
@@ -518,7 +530,7 @@ export function registerStatefulSubagents(
 		name: "subagent_mailbox",
 		label: "Subagent Mailbox",
 		description:
-			"Queue a bounded message without starting a turn, or read unread mailbox messages and optionally acknowledge them.",
+			"Queue a bounded message without starting a turn, or read unread mailbox messages. Read acknowledges returned messages by default; use subagent_inspect for metadata-only unread counts.",
 		promptSnippet: "Send or read queue-only detached-subagent mailbox messages",
 		parameters: MailboxParamsSchema,
 		async execute(_id, params): Promise<StatefulActionToolResult> {
@@ -608,19 +620,19 @@ async function confirmProjectAgent(
 	cwd: string,
 ): Promise<void> {
 	if (scope !== "project" && scope !== "both") return;
-	const discovery = discoverAgents(cwd, scope, readSubagentSettings());
-	const agent = discovery.agents.find((candidate) => candidate.name === name);
-	if (agent?.source !== "project") 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, 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: ${name}\nSource: ${agent.filePath}`,
+			`Agent: ${safeTerminalLine(name, 256)}\nSource: ${safeTerminalLine(agent.filePath)}`,
 		);
 		if (!approved) throw new Error("Project-local subagent was not approved");
 	}