pi-subagents 0.49.0 → 0.50.0

package/src/agents/agent-serializer.ts

@@ -18,6 +18,7 @@ export const KNOWN_FIELDS = new Set([
 	"defaultContext",
 	"async",
 	"timeoutMs",
+	"toolTimeoutMs",
 	"turnBudget",
 	"acceptance",
 	"acceptanceRole",
@@ -86,6 +87,7 @@ export function serializeAgent(config: AgentConfig, options: SerializeAgentOptio
 	}
 	if (config.defaultAsync !== undefined || preserve("async")) lines.push(`async: ${config.defaultAsync === undefined ? "" : config.defaultAsync ? "true" : "false"}`);
 	if (config.defaultTimeoutMs !== undefined || preserve("timeoutMs")) lines.push(`timeoutMs: ${config.defaultTimeoutMs ?? ""}`);
+	if (config.defaultToolTimeoutMs !== undefined || preserve("toolTimeoutMs")) lines.push(`toolTimeoutMs: ${config.defaultToolTimeoutMs ?? ""}`);
 	if (config.defaultTurnBudget || preserve("turnBudget")) lines.push(`turnBudget: ${config.defaultTurnBudget ? JSON.stringify(config.defaultTurnBudget) : ""}`);
 	if (config.defaultAcceptance !== undefined || preserve("acceptance")) {
 		lines.push(`acceptance: ${config.defaultAcceptance === undefined

package/src/agents/agents.ts

@@ -130,6 +130,7 @@ export interface AgentConfig {
 	defaultContext?: AgentDefaultContext;
 	defaultAsync?: boolean;
 	defaultTimeoutMs?: number;
+	defaultToolTimeoutMs?: number;
 	defaultTurnBudget?: TurnBudgetConfig;
 	defaultAcceptance?: AcceptanceInput;
 	acceptanceRole?: AcceptanceRole;
@@ -1582,6 +1583,14 @@ function loadAgentsFromDir(dir: string, source: AgentSource): AgentConfig[] {
 			}
 			defaultTimeoutMs = parsed;
 		}
+		let defaultToolTimeoutMs: number | undefined;
+		if (frontmatter.toolTimeoutMs !== undefined) {
+			const parsed = Number(frontmatter.toolTimeoutMs);
+			if (!Number.isInteger(parsed) || parsed <= 0 || parsed > 2_147_483_647) {
+				throw new Error(`Agent '${localName}' has invalid toolTimeoutMs frontmatter; expected a positive integer no larger than 2147483647.`);
+			}
+			defaultToolTimeoutMs = parsed;
+		}
 		let defaultTurnBudget: TurnBudgetConfig | undefined;
 		if (frontmatter.turnBudget !== undefined && frontmatter.turnBudget.trim()) {
 			const parsed = JSON.parse(frontmatter.turnBudget) as unknown;
@@ -1648,6 +1657,7 @@ function loadAgentsFromDir(dir: string, source: AgentSource): AgentConfig[] {
 			...(defaultContext !== undefined ? { defaultContext } : {}),
 			...(defaultAsync !== undefined ? { defaultAsync } : {}),
 			...(defaultTimeoutMs !== undefined ? { defaultTimeoutMs } : {}),
+			...(defaultToolTimeoutMs !== undefined ? { defaultToolTimeoutMs } : {}),
 			...(defaultTurnBudget !== undefined ? { defaultTurnBudget } : {}),
 			...(defaultAcceptance !== undefined ? { defaultAcceptance } : {}),
 			...(acceptanceRole !== undefined ? { acceptanceRole } : {}),

package/src/api/external-runs.ts

@@ -1,129 +1,219 @@
-export const EXTERNAL_RUN_REGISTRY_VERSION = 1;
-export const EXTERNAL_RUN_REGISTRY_KEY = "pi-subagents.external-runs.v1";
+import { sanitizeDisplayText, truncateDisplayText } from "../shared/display-text.ts";
 
-const MAX_PROVIDERS = 100;
-const MAX_RUNS_PER_PROVIDER = 10_000;
-const MAX_TEXT_LENGTH = 4_096;
+export const EXTERNAL_RUN_REGISTRY_VERSION = 2;
+export const EXTERNAL_RUN_REGISTRY_KEY = "pi-subagents.external-runs.v2";
 
-export type ExternalRunState = "running" | "completed" | "failed" | "stopped";
-export type ExternalRunCompletionReason = "exit" | "timeout" | "user-kill" | "auto-close-quiet" | "crash" | "unknown";
+export const EXTERNAL_RUN_LIMITS = {
+	maxCachedRuns: 100,
+	maxSnapshotRuns: 20,
+	maxIdentityLength: 160,
+	/**
+	 * A Pi session id is the session file path, which routinely exceeds a short
+	 * identity budget in nested worktrees, so it is bounded like the other paths.
+	 */
+	maxSessionIdLength: 4_096,
+	maxTextLength: 160,
+	maxPreviewLength: 4_096,
+	maxPathLength: 4_096,
+	maxSerializedBytes: 32 * 1_024,
+} as const;
 
-/** An observational record for work owned by another runtime. */
+export type ExternalRunState = "queued" | "running" | "completed" | "failed" | "stopped";
+
+/** A display-only record for work owned by another extension or runtime. */
 export interface ExternalRun {
 	id: string;
 	sessionId: string;
 	source: string;
+	label: string;
 	state: ExternalRunState;
-	command?: string;
-	cwd?: string;
-	isolationPath?: string;
-	owner?: string;
-	completionReason?: ExternalRunCompletionReason;
+	startedAt: number;
+	updatedAt?: number;
+	endedAt?: number;
+	currentAction?: string;
+	preview?: string;
 	reportPath?: string;
-	startedAt?: number;
-	completedAt?: number;
-	exitCode?: number | null;
-	residualRisks?: string[];
+	transcriptPath?: string;
 }
 
-export interface ExternalRunProvider {
-	name: string;
-	listExternalRuns(): readonly ExternalRun[];
-}
+export type ExternalRunUpdate = Partial<Omit<ExternalRun, "id" | "sessionId" | "source">>;
 
-export interface RegisteredExternalRun extends ExternalRun {
-	provider: string;
+export interface ExternalRunSnapshotOptions {
+	onMalformedRecord?: (message: string) => void;
+	ignoreMalformed?: boolean;
 }
 
 interface ExternalRunRegistry {
 	version: typeof EXTERNAL_RUN_REGISTRY_VERSION;
-	providers: Map<string, ExternalRunProvider>;
+	runs: Map<string, ExternalRun>;
 }
 
+const RUN_FIELDS = new Set([
+	"id",
+	"sessionId",
+	"source",
+	"label",
+	"state",
+	"startedAt",
+	"updatedAt",
+	"endedAt",
+	"currentAction",
+	"preview",
+	"reportPath",
+	"transcriptPath",
+]);
+const UPDATE_FIELDS = new Set([...RUN_FIELDS].filter((field) => field !== "id" && field !== "sessionId" && field !== "source"));
+
 function registry(): ExternalRunRegistry {
 	const key = Symbol.for(EXTERNAL_RUN_REGISTRY_KEY);
 	const target = globalThis as Record<PropertyKey, unknown>;
 	const existing = target[key];
 	if (existing === undefined) {
-		const created: ExternalRunRegistry = { version: EXTERNAL_RUN_REGISTRY_VERSION, providers: new Map() };
+		const created: ExternalRunRegistry = { version: EXTERNAL_RUN_REGISTRY_VERSION, runs: new Map() };
 		target[key] = created;
 		return created;
 	}
 	if (!existing || typeof existing !== "object" || Array.isArray(existing)) throw new Error(`Malformed external-run registry at Symbol.for("${EXTERNAL_RUN_REGISTRY_KEY}").`);
 	const candidate = existing as Partial<ExternalRunRegistry>;
-	if (candidate.version !== EXTERNAL_RUN_REGISTRY_VERSION || !(candidate.providers instanceof Map)) throw new Error(`Unsupported external-run registry at Symbol.for("${EXTERNAL_RUN_REGISTRY_KEY}").`);
+	if (candidate.version !== EXTERNAL_RUN_REGISTRY_VERSION || !(candidate.runs instanceof Map)) throw new Error(`Unsupported external-run registry at Symbol.for("${EXTERNAL_RUN_REGISTRY_KEY}").`);
 	return candidate as ExternalRunRegistry;
 }
 
-function text(value: unknown, field: string, required = false): string | undefined {
-	if (value === undefined && !required) return undefined;
+function inputObject(value: unknown, field: string, allowed: Set<string>): Record<string, unknown> {
+	if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(`${field} must be an object.`);
+	const input = value as Record<string, unknown>;
+	const unknown = Object.keys(input).filter((key) => !allowed.has(key));
+	if (unknown.length) throw new Error(`${field} has unknown fields: ${unknown.join(", ")}.`);
+	return input;
+}
+
+function identity(value: unknown, field: string, maxLength: number = EXTERNAL_RUN_LIMITS.maxIdentityLength): string {
 	if (typeof value !== "string" || value.length === 0 || value.trim() !== value || value.includes("\0")) throw new Error(`${field} must be a non-empty trimmed string without NUL characters.`);
-	if (value.length > MAX_TEXT_LENGTH) throw new Error(`${field} must be at most ${MAX_TEXT_LENGTH} characters.`);
+	if (value.length > maxLength) throw new Error(`${field} must be at most ${maxLength} characters.`);
+	const safe = sanitizeDisplayText(value);
+	if (!safe || safe !== value) throw new Error(`${field} must contain only display-safe text.`);
 	return value;
 }
 
-function timestamp(value: unknown, field: string): number | undefined {
-	if (value === undefined) return undefined;
-	if (typeof value !== "number" || !Number.isFinite(value) || value < 0) throw new Error(`${field} must be a non-negative finite number.`);
+function displayText(value: unknown, field: string, maxLength: number): string | undefined;
+function displayText(value: unknown, field: string, maxLength: number, required: true): string;
+function displayText(value: unknown, field: string, maxLength: number, required = false): string | undefined {
+	if (value === undefined && !required) return undefined;
+	if (typeof value !== "string" || value.length === 0) throw new Error(`${field} must be a non-empty string.`);
+	const safe = sanitizeDisplayText(value.slice(0, Math.max(maxLength * 4, maxLength)));
+	if (!safe) throw new Error(`${field} must contain displayable text.`);
+	return truncateDisplayText(safe, maxLength);
+}
+
+function timestamp(value: unknown, field: string): number | undefined;
+function timestamp(value: unknown, field: string, required: true): number;
+function timestamp(value: unknown, field: string, required = false): number | undefined {
+	if (value === undefined && !required) return undefined;
+	if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0 || value > 8_640_000_000_000_000) throw new Error(`${field} must be a non-negative safe timestamp.`);
 	return value;
 }
 
-function validateRun(value: unknown, provider: string, index: number): ExternalRun {
-	if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(`External-run provider '${provider}' item ${index} must be an object.`);
-	const run = value as Record<string, unknown>;
-	const fields = new Set(["id", "sessionId", "source", "state", "command", "cwd", "isolationPath", "owner", "completionReason", "reportPath", "startedAt", "completedAt", "exitCode", "residualRisks"]);
-	const unknown = Object.keys(run).filter((key) => !fields.has(key));
-	if (unknown.length) throw new Error(`External-run provider '${provider}' item ${index} has unknown fields: ${unknown.join(", ")}.`);
-	if (!["running", "completed", "failed", "stopped"].includes(run.state as string)) throw new Error(`External-run provider '${provider}' item ${index} state is invalid.`);
-	if (run.completionReason !== undefined && !["exit", "timeout", "user-kill", "auto-close-quiet", "crash", "unknown"].includes(run.completionReason as string)) throw new Error(`External-run provider '${provider}' item ${index} completionReason is invalid.`);
-	if (run.exitCode !== undefined && run.exitCode !== null && (!Number.isInteger(run.exitCode) || !Number.isFinite(run.exitCode))) throw new Error(`External-run provider '${provider}' item ${index} exitCode must be an integer or null.`);
-	if (run.residualRisks !== undefined && (!Array.isArray(run.residualRisks) || run.residualRisks.some((risk, riskIndex) => text(risk, `External-run provider '${provider}' item ${index} residualRisks[${riskIndex}]`, true) === undefined))) throw new Error(`External-run provider '${provider}' item ${index} residualRisks must be an array of strings.`);
+function state(value: unknown, field: string): ExternalRunState {
+	if (value === "queued" || value === "running" || value === "completed" || value === "failed" || value === "stopped") return value;
+	throw new Error(`${field} is invalid.`);
+}
+
+function validateRun(value: unknown): ExternalRun {
+	const run = inputObject(value, "External run", RUN_FIELDS);
+	const updatedAt = timestamp(run.updatedAt, "External run updatedAt");
+	const endedAt = timestamp(run.endedAt, "External run endedAt");
+	const currentAction = displayText(run.currentAction, "External run currentAction", EXTERNAL_RUN_LIMITS.maxTextLength);
+	const preview = displayText(run.preview, "External run preview", EXTERNAL_RUN_LIMITS.maxPreviewLength);
+	const reportPath = displayText(run.reportPath, "External run reportPath", EXTERNAL_RUN_LIMITS.maxPathLength);
+	const transcriptPath = displayText(run.transcriptPath, "External run transcriptPath", EXTERNAL_RUN_LIMITS.maxPathLength);
 	return {
-		id: text(run.id, `External-run provider '${provider}' item ${index} id`, true)!,
-		sessionId: text(run.sessionId, `External-run provider '${provider}' item ${index} sessionId`, true)!,
-		source: text(run.source, `External-run provider '${provider}' item ${index} source`, true)!,
-		state: run.state as ExternalRunState,
-		...(text(run.command, `External-run provider '${provider}' item ${index} command`) !== undefined ? { command: text(run.command, `External-run provider '${provider}' item ${index} command`) } : {}),
-		...(text(run.cwd, `External-run provider '${provider}' item ${index} cwd`) !== undefined ? { cwd: text(run.cwd, `External-run provider '${provider}' item ${index} cwd`) } : {}),
-		...(text(run.isolationPath, `External-run provider '${provider}' item ${index} isolationPath`) !== undefined ? { isolationPath: text(run.isolationPath, `External-run provider '${provider}' item ${index} isolationPath`) } : {}),
-		...(text(run.owner, `External-run provider '${provider}' item ${index} owner`) !== undefined ? { owner: text(run.owner, `External-run provider '${provider}' item ${index} owner`) } : {}),
-		...(run.completionReason !== undefined ? { completionReason: run.completionReason as ExternalRunCompletionReason } : {}),
-		...(text(run.reportPath, `External-run provider '${provider}' item ${index} reportPath`) !== undefined ? { reportPath: text(run.reportPath, `External-run provider '${provider}' item ${index} reportPath`) } : {}),
-		...(timestamp(run.startedAt, `External-run provider '${provider}' item ${index} startedAt`) !== undefined ? { startedAt: timestamp(run.startedAt, `External-run provider '${provider}' item ${index} startedAt`) } : {}),
-		...(timestamp(run.completedAt, `External-run provider '${provider}' item ${index} completedAt`) !== undefined ? { completedAt: timestamp(run.completedAt, `External-run provider '${provider}' item ${index} completedAt`) } : {}),
-		...(run.exitCode !== undefined ? { exitCode: run.exitCode as number | null } : {}),
-		...(run.residualRisks !== undefined ? { residualRisks: [...run.residualRisks] as string[] } : {}),
+		id: identity(run.id, "External run id"),
+		sessionId: identity(run.sessionId, "External run sessionId", EXTERNAL_RUN_LIMITS.maxSessionIdLength),
+		source: displayText(run.source, "External run source", EXTERNAL_RUN_LIMITS.maxTextLength, true),
+		label: displayText(run.label, "External run label", EXTERNAL_RUN_LIMITS.maxTextLength, true),
+		state: state(run.state, "External run state"),
+		startedAt: timestamp(run.startedAt, "External run startedAt", true),
+		...(updatedAt !== undefined ? { updatedAt } : {}),
+		...(endedAt !== undefined ? { endedAt } : {}),
+		...(currentAction ? { currentAction } : {}),
+		...(preview ? { preview } : {}),
+		...(reportPath ? { reportPath } : {}),
+		...(transcriptPath ? { transcriptPath } : {}),
 	};
 }
 
-/** Register an observational provider. pi-subagents never starts, stops, or steers these processes. */
-export function registerExternalRunProvider(provider: ExternalRunProvider): () => void {
-	if (!provider || typeof provider !== "object" || Array.isArray(provider) || Object.keys(provider).some((key) => key !== "name" && key !== "listExternalRuns")) throw new Error("External-run provider must contain only name and listExternalRuns.");
-	const name = text(provider.name, "External-run provider name", true)!;
-	if (typeof provider.listExternalRuns !== "function") throw new Error(`External-run provider '${name}' must expose listExternalRuns().`);
+function key(sessionId: string, id: string): string {
+	return `${sessionId}\0${id}`;
+}
+
+function clone(run: ExternalRun): ExternalRun {
+	return { ...run };
+}
+
+/** Register one current-session external job. pi-subagents never controls the job. */
+export function registerExternalRun(input: ExternalRun): ExternalRun {
+	const run = validateRun(input);
+	const current = registry();
+	const runKey = key(run.sessionId, run.id);
+	if (current.runs.has(runKey)) throw new Error(`External run '${run.id}' is already registered for session '${run.sessionId}'.`);
+	if (current.runs.size >= EXTERNAL_RUN_LIMITS.maxCachedRuns) throw new Error(`External-run registry supports at most ${EXTERNAL_RUN_LIMITS.maxCachedRuns} cached runs.`);
+	current.runs.set(runKey, run);
+	return clone(run);
+}
+
+/** Update display fields for a registered external job without changing its identity or owner. */
+export function updateExternalRun(sessionId: string, id: string, update: ExternalRunUpdate): ExternalRun {
+	const safeSessionId = identity(sessionId, "External run sessionId", EXTERNAL_RUN_LIMITS.maxSessionIdLength);
+	const safeId = identity(id, "External run id");
+	const patch = inputObject(update, "External run update", UPDATE_FIELDS);
+	const current = registry();
+	const runKey = key(safeSessionId, safeId);
+	const previous = current.runs.get(runKey);
+	if (!previous) throw new Error(`External run '${safeId}' is not registered for session '${safeSessionId}'.`);
+	const next = validateRun({ ...previous, ...patch });
+	current.runs.set(runKey, next);
+	return clone(next);
+}
+
+/** Remove a cached external job. The caller remains responsible for its process and artifacts. */
+export function unregisterExternalRun(sessionId: string, id: string): boolean {
+	return registry().runs.delete(key(identity(sessionId, "External run sessionId", EXTERNAL_RUN_LIMITS.maxSessionIdLength), identity(id, "External run id")));
+}
+
+function snapshotBytes(runs: readonly ExternalRun[]): number {
+	return Buffer.byteLength(JSON.stringify(runs), "utf8");
+}
+
+function getErrorMessage(error: unknown): string {
+	return error instanceof Error ? error.message : String(error);
+}
+
+/** Read a bounded cached snapshot for one Pi session. This never invokes third-party code. */
+export function snapshotExternalRuns(sessionId: string, options: ExternalRunSnapshotOptions = {}): readonly ExternalRun[] {
+	const safeSessionId = identity(sessionId, "External-run snapshot sessionId", EXTERNAL_RUN_LIMITS.maxSessionIdLength);
 	const current = registry();
-	if (!current.providers.has(name) && current.providers.size >= MAX_PROVIDERS) throw new Error(`External-run registry supports at most ${MAX_PROVIDERS} providers.`);
-	current.providers.set(name, provider);
-	return () => { if (current.providers.get(name) === provider) current.providers.delete(name); };
-}
-
-/** Snapshot records for one Pi session. Records are read-only observations of foreign process ownership. */
-export function snapshotExternalRuns(sessionId: string): readonly RegisteredExternalRun[] {
-	text(sessionId, "External-run snapshot sessionId", true);
-	const records: RegisteredExternalRun[] = [];
-	const identities = new Set<string>();
-	for (const [name, provider] of registry().providers) {
-		if (provider.name !== name) throw new Error(`External-run registry key '${name}' does not match provider name '${provider.name}'.`);
-		const runs = provider.listExternalRuns();
-		if (!Array.isArray(runs)) throw new Error(`External-run provider '${name}' listExternalRuns() must return an array.`);
-		if (runs.length > MAX_RUNS_PER_PROVIDER) throw new Error(`External-run provider '${name}' returned more than ${MAX_RUNS_PER_PROVIDER} runs.`);
-		runs.forEach((value, index) => {
-			const run = validateRun(value, name, index);
-			const identity = `${name}\0${run.sessionId}\0${run.id}`;
-			if (identities.has(identity)) throw new Error(`External-run provider '${name}' returned duplicate run '${run.id}' for session '${run.sessionId}'.`);
-			identities.add(identity);
-			if (run.sessionId === sessionId) records.push({ provider: name, ...run });
-		});
+	const runs: ExternalRun[] = [];
+	for (const [cacheKey, value] of current.runs.entries()) {
+		try {
+			const run = validateRun(value);
+			if (run.sessionId === safeSessionId) runs.push(run);
+		} catch (error) {
+			const message = `Malformed cached external run '${cacheKey}': ${getErrorMessage(error)}`;
+			if (!options.ignoreMalformed) throw new Error(message, { cause: error instanceof Error ? error : undefined });
+			current.runs.delete(cacheKey);
+			options.onMalformedRecord?.(message);
+		}
 	}
-	return records;
+	runs.sort((left, right) => {
+		const leftActive = left.state === "queued" || left.state === "running";
+		const rightActive = right.state === "queued" || right.state === "running";
+		if (leftActive !== rightActive) return leftActive ? -1 : 1;
+		return (right.updatedAt ?? right.endedAt ?? right.startedAt) - (left.updatedAt ?? left.endedAt ?? left.startedAt) || left.id.localeCompare(right.id);
+	});
+	const snapshot = runs.slice(0, EXTERNAL_RUN_LIMITS.maxSnapshotRuns).map(clone);
+	while (snapshot.length > 0 && snapshotBytes(snapshot) > EXTERNAL_RUN_LIMITS.maxSerializedBytes) snapshot.pop();
+	return snapshot;
 }
+
+/** Alias for callers that prefer list terminology. */
+export const listExternalRuns = snapshotExternalRuns;

package/src/api/preflight.ts

@@ -20,6 +20,7 @@ import { resolveStepBehavior } from "../shared/settings.ts";
 import { agentDefinitionDigest, AGENT_DEFINITION_PROJECTION_VERSION, launchBindingDigest } from "../shared/launch-contract.ts";
 import { DIRS, TEMP_ROOT_DIR } from "../shared/types.ts";
 import { processTerminalCandidatePath, processTerminalPath } from "../runs/background/process-terminal.ts";
+import { resultFilePath } from "../runs/background/result-files.ts";
 import { nestedResultsPath } from "../runs/shared/nested-events.ts";
 
 export const SUBAGENT_LAUNCH_CONTRACT_VERSION = 2 as const;
@@ -259,13 +260,18 @@ export async function resolveSubagentLaunchContract(input: SubagentLaunchContrac
 	}
 	if (resolvedSkills.missing.length > 0) diagnostics.push({ code: "missing_skill", severity: "error", message: `Missing skills: ${resolvedSkills.missing.join(", ")}` });
 
+	const externalRunner = agent.runner?.type === "external-cli";
 	const availableModels = normalizeAvailableModels(input.availableModels);
 	const preferredProvider = input.preferredProvider ?? input.parentModel?.provider;
-	const primaryModel = resolveEffectiveSubagentModel(input.model, agent.model, input.parentModel, availableModels, preferredProvider, { scope: discovered.modelScope });
+	const primaryModel = externalRunner
+		? undefined
+		: resolveEffectiveSubagentModel(input.model, agent.model, input.parentModel, availableModels, preferredProvider, { scope: discovered.modelScope });
 	const effectiveThinkingConfig = input.thinking !== undefined ? input.thinking : agent.thinking;
-	const model = applyThinkingSuffix(primaryModel, effectiveThinkingConfig, input.thinking !== undefined);
-	const modelCandidates = buildModelCandidates(primaryModel, agent.fallbackModels, availableModels, preferredProvider, { scope: discovered.modelScope })
-		.map((candidate) => applyThinkingSuffix(candidate, effectiveThinkingConfig, input.thinking !== undefined) ?? candidate);
+	const model = externalRunner ? undefined : applyThinkingSuffix(primaryModel, effectiveThinkingConfig, input.thinking !== undefined);
+	const modelCandidates = externalRunner
+		? []
+		: buildModelCandidates(primaryModel, agent.fallbackModels, availableModels, preferredProvider, { scope: discovered.modelScope })
+			.map((candidate) => applyThinkingSuffix(candidate, effectiveThinkingConfig, input.thinking !== undefined) ?? candidate);
 	let toolPlan: PiLaunchToolPlan;
 	try {
 		toolPlan = resolvePiLaunchToolPlan({
@@ -295,9 +301,9 @@ export async function resolveSubagentLaunchContract(input: SubagentLaunchContrac
 		: path.join(DIRS.async, runId);
 	const lifecycleResultPath = input.nestedRootRunId
 		? nestedResultsPath(input.nestedRootRunId, runId)
-		: path.join(DIRS.results, `${runId}.json`);
+		: resultFilePath(DIRS.results, runId);
 	if (!sessionDir) diagnostics.push({ code: "host_required", severity: "host-required", message: "No sessionRoot/sessionDir was supplied; exact child session paths require the Pi host session-root policy." });
-	if (input.availableModels === undefined && (input.model || agent.model || input.parentModel)) {
+	if (!externalRunner && input.availableModels === undefined && (input.model || agent.model || input.parentModel)) {
 		diagnostics.push({ code: "host_required", severity: "host-required", message: "No availableModels snapshot was supplied; model resolution may differ from the active Pi host registry." });
 	}
 	if (resolvedSkills.missing.length > 0) {

package/src/extension/config.ts

@@ -1,6 +1,7 @@
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
+import { Key } from "@earendil-works/pi-tui";
 import { FLEET_KEYBINDING_ACTIONS, type ArtifactDirPreference, type ExtensionConfig } from "../shared/types.ts";
 import { validateMissionStoreConfig } from "../missions/store.ts";
 import { validateAuthorityPolicy } from "../policy/authority.ts";
@@ -9,6 +10,21 @@ import { validatePermissionConfig } from "../runs/shared/permissions.ts";
 
 const ARTIFACT_DIR_PREFERENCES = new Set<ArtifactDirPreference>(["project", "session", "temp"]);
 const FLEET_KEYBINDING_ACTION_SET = new Set<string>(FLEET_KEYBINDING_ACTIONS);
+const KEY_MODIFIERS = new Set(["ctrl", "shift", "alt", "super"]);
+const BASE_KEY_IDS = new Set([
+	..."abcdefghijklmnopqrstuvwxyz0123456789",
+	...Object.values(Key).flatMap((value) => typeof value === "string" ? [value.toLowerCase()] : []),
+]);
+
+function isValidKeyId(value: string): boolean {
+	if (value !== value.trim()) return false;
+	const parts = value.toLowerCase().split("+");
+	const base = parts.pop();
+	if (!base || !BASE_KEY_IDS.has(base)) return false;
+	return parts.length <= KEY_MODIFIERS.size
+		&& new Set(parts).size === parts.length
+		&& parts.every((modifier) => KEY_MODIFIERS.has(modifier));
+}
 
 export function resolveScheduledStoreRoot(value: string): string {
 	const expanded = value.startsWith("~/") ? path.join(os.homedir(), value.slice(2)) : value;
@@ -46,6 +62,18 @@ function validateArtifactConfig(value: unknown): void {
 	}
 }
 
+function validateOrcaProgressTabsConfig(value: unknown): void {
+	if (value === undefined) return;
+	if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("config.orcaProgressTabs must be a JSON object");
+	const config = value as Record<string, unknown>;
+	for (const key of Object.keys(config)) {
+		if (key !== "enabled") throw new Error(`config.orcaProgressTabs.${key} is not supported`);
+	}
+	if (config.enabled !== undefined && typeof config.enabled !== "boolean") {
+		throw new Error("config.orcaProgressTabs.enabled must be a boolean");
+	}
+}
+
 function validateMainWindowRendererConfig(value: unknown): void {
 	if (value === undefined) return;
 	if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("config.mainWindowRenderer must be a JSON object");
@@ -66,6 +94,10 @@ function validateMainWindowRendererConfig(value: unknown): void {
 }
 
 function validateConfig(config: Record<string, unknown>): void {
+	if (config.foregroundDetachShortcut !== undefined
+		&& (typeof config.foregroundDetachShortcut !== "string" || !isValidKeyId(config.foregroundDetachShortcut))) {
+		throw new Error("config.foregroundDetachShortcut must be a valid keybinding string such as \"ctrl+b\"");
+	}
 	if (config.artifactDir !== undefined && !ARTIFACT_DIR_PREFERENCES.has(config.artifactDir as ArtifactDirPreference)) {
 		throw new Error(`config.artifactDir must be "project", "session", or "temp"`);
 	}
@@ -85,6 +117,7 @@ function validateConfig(config: Record<string, unknown>): void {
 	validateFleetKeybindingsConfig(config.fleetKeybindings);
 	validateArtifactConfig(config.artifactConfig);
 	validateMainWindowRendererConfig(config.mainWindowRenderer);
+	validateOrcaProgressTabsConfig(config.orcaProgressTabs);
 }
 
 export function getConfigPath(): string {

package/src/extension/index.ts

@@ -31,6 +31,7 @@ import { createSubagentParamsSchema } from "./schemas.ts";
 import { createSubagentExecutor, type SubagentParamsLike } from "../runs/foreground/subagent-executor.ts";
 import { createAsyncJobTracker } from "../runs/background/async-job-tracker.ts";
 import { getActiveAsyncCapacitySnapshot, resolveMaxActiveAsyncRunsPerSession } from "../runs/background/active-async-capacity.ts";
+import { cleanupResultIndexes } from "../runs/background/result-files.ts";
 import { createResultWatcher } from "../runs/background/result-watcher.ts";
 import { createScheduledRunManager } from "../runs/background/scheduled-runs.ts";
 import { registerSlashCommands } from "../slash/slash-commands.ts";
@@ -82,6 +83,13 @@ import {
 
 export { loadConfig, resolveAsyncByDefault } from "./config.ts";
 
+const SLOW_RELOAD_PHASE_MS = 250;
+
+function logSlowPhase(label: string, startedAt: number): void {
+	const elapsed = Date.now() - startedAt;
+	if (elapsed >= SLOW_RELOAD_PHASE_MS) console.error(`Subagent reload phase '${label}' took ${elapsed}ms.`);
+}
+
 function workflowLaneKeys(script: string): string[] {
 	const keys: string[] = [];
 	const seen = new Set<string>();
@@ -255,12 +263,13 @@ function rebuildSlashResultContainer(
 	options: { expanded: boolean },
 	theme: ExtensionContext["ui"]["theme"],
 	rendererConfig?: MainWindowRendererConfig,
+	foregroundDetachShortcut?: string,
 ): void {
 	container.clear();
 	container.addChild(new Spacer(1));
 	const boxTheme = isSlashResultRunning(result) ? "toolPendingBg" : isSlashResultError(result) ? "toolErrorBg" : "toolSuccessBg";
 	const box = new Box(1, 1, (text: string) => theme.bg(boxTheme, text));
-	box.addChild(renderSubagentResult(result, options, theme, undefined, rendererConfig));
+	box.addChild(renderSubagentResult(result, options, theme, undefined, rendererConfig, foregroundDetachShortcut));
 	container.addChild(box);
 }
 
@@ -269,6 +278,7 @@ function createSlashResultComponent(
 	options: { expanded: boolean },
 	theme: ExtensionContext["ui"]["theme"],
 	rendererConfig?: MainWindowRendererConfig,
+	foregroundDetachShortcut?: string,
 ): Container {
 	const container = new Container();
 	let lastVersion = -1;
@@ -276,7 +286,7 @@ function createSlashResultComponent(
 		const snapshot = getSlashRenderableSnapshot(details);
 		if (snapshot.version !== lastVersion || isSlashResultRunning(snapshot.result)) {
 			lastVersion = snapshot.version;
-			rebuildSlashResultContainer(container, snapshot.result, options, theme, rendererConfig);
+			rebuildSlashResultContainer(container, snapshot.result, options, theme, rendererConfig, foregroundDetachShortcut);
 		}
 		return Container.prototype.render.call(container, width);
 	};
@@ -373,6 +383,14 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 	const tempArtifactsDir = getArtifactsDir(null);
 	const artifactCleanupDays = config.artifactConfig?.cleanupDays ?? DEFAULT_ARTIFACT_CONFIG.cleanupDays;
 	cleanupAllArtifactDirs(artifactCleanupDays);
+	const resultIndexCleanupTimer = setTimeout(() => {
+		try {
+			cleanupResultIndexes(DIRS.results);
+		} catch (error) {
+			console.error("Failed to clean stale subagent result indexes:", error);
+		}
+	}, 30_000);
+	resultIndexCleanupTimer.unref?.();
 
 	const state: SubagentState = {
 		baseCwd: "",
@@ -455,6 +473,7 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 	);
 
 	const runtimeCleanup = () => {
+		clearTimeout(resultIndexCleanupTimer);
 		stopResultWatcher();
 		state.currentSessionId = null;
 		completionNotifier.dispose();
@@ -485,7 +504,7 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 	pi.registerMessageRenderer<SlashMessageDetails>(SLASH_RESULT_TYPE, (message, options, theme) => {
 		const details = resolveSlashMessageDetails(message.details);
 		if (!details) return undefined;
-		return createSlashResultComponent(details, options, theme, config.mainWindowRenderer);
+		return createSlashResultComponent(details, options, theme, config.mainWindowRenderer, config.foregroundDetachShortcut);
 	});
 
 	pi.registerMessageRenderer<undefined>(SLASH_TEXT_RESULT_TYPE, (message, _options, _theme) => {
@@ -613,7 +632,7 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 			const renderedResult = { ...result, isError: context.isError };
 			return summaryInlineToolDisplay
 				? renderSubagentSummary(renderedResult, options, theme)
-				: renderSubagentResult(renderedResult, options, theme, undefined, config.mainWindowRenderer);
+				: renderSubagentResult(renderedResult, options, theme, undefined, config.mainWindowRenderer, config.foregroundDetachShortcut);
 		},
 
 	};
@@ -643,7 +662,10 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 		}
 	});
 
-	registerSlashCommands(pi, state, { fleetKeybindings: config.fleetKeybindings });
+	registerSlashCommands(pi, state, {
+		fleetKeybindings: config.fleetKeybindings,
+		foregroundDetachShortcut: config.foregroundDetachShortcut,
+	});
 
 	const eventUnsubscribeStoreKey = "__piSubagentEventUnsubscribes";
 	const controlNoticeSeenStoreKey = "__piSubagentVisibleControlNotices";
@@ -783,18 +805,38 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 			}
 		}
 		state.lastUiContext = ctx;
+		let phaseStartedAt = Date.now();
 		refreshActiveAsyncCapacity();
+		logSlowPhase("active-capacity", phaseStartedAt);
+		phaseStartedAt = Date.now();
 		cleanupSessionArtifacts(ctx);
+		logSlowPhase("session-artifact-cleanup", phaseStartedAt);
 		state.foregroundControls.clear();
 		state.lastForegroundControlId = null;
+		phaseStartedAt = Date.now();
 		resetJobs(ctx);
+		logSlowPhase("reset-jobs", phaseStartedAt);
+		phaseStartedAt = Date.now();
 		restoreForegroundRunHistory(state, { resultsDir: DIRS.results });
+		logSlowPhase("foreground-history", phaseStartedAt);
+		phaseStartedAt = Date.now();
 		restoreActiveJobs(ctx);
+		logSlowPhase("active-job-restore", phaseStartedAt);
+		phaseStartedAt = Date.now();
 		scheduledRunManager.bindSession(ctx);
+		logSlowPhase("scheduled-runs", phaseStartedAt);
+		phaseStartedAt = Date.now();
 		restoreSlashFinalSnapshots(ctx.sessionManager.getEntries());
+		logSlowPhase("slash-snapshots", phaseStartedAt);
+		phaseStartedAt = Date.now();
 		waitSubscriptionManager.restore();
+		logSlowPhase("wait-subscriptions", phaseStartedAt);
+		phaseStartedAt = Date.now();
 		startResultWatcher();
+		logSlowPhase("result-watcher-start", phaseStartedAt);
+		phaseStartedAt = Date.now();
 		primeExistingResults({ triggerTurn: !recovering });
+		logSlowPhase("result-prime", phaseStartedAt);
 		fleetStatus?.setContext(ctx);
 	};
 
@@ -837,6 +879,7 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 
 	pi.on("session_shutdown", async () => {
 		state.widgetsSuspended = false;
+		clearTimeout(resultIndexCleanupTimer);
 		stopResultWatcher();
 		state.currentSessionId = null;
 		state.parentSessionFile = null;

package/src/extension/public-execution.ts

@@ -9,6 +9,7 @@ export interface PublicSubagentExecutionParams {
 	concurrency?: unknown;
 	chainDir?: unknown;
 	workflowScript?: unknown;
+	output?: unknown;
 	resume?: unknown;
 	clarify?: unknown;
 	runFanoutBudget?: unknown;
@@ -82,10 +83,11 @@ export function normalizePublicSubagentExecution<T extends PublicSubagentExecuti
 		if (params.task !== undefined && typeof params.task !== "string") {
 			return { ok: false, error: "Structured single-child task must be a string when provided.", mode: "workflow" };
 		}
-		const { agent: _agent, task: _task, ...workflowDefaults } = params;
+		const { agent: _agent, task: _task, output, ...workflowDefaults } = params;
 		const child = {
 			agent: params.agent.trim(),
 			...(params.task !== undefined ? { task: params.task } : {}),
+			output: output === undefined ? true : output,
 		};
 		return {
 			ok: true,