pi-subagents 0.31.0 → 0.32.0

package/src/runs/shared/acceptance.ts

@@ -710,13 +710,15 @@ export function aggregateAcceptanceReport(input: {
 	};
 }
 
-function runVerifyCommand(command: AcceptanceVerifyCommand, defaultCwd: string): Promise<AcceptanceVerifyResult> {
+function runVerifyCommand(command: AcceptanceVerifyCommand, defaultCwd: string, options: { signal?: AbortSignal; abortMessage?: string } = {}): Promise<AcceptanceVerifyResult> {
 	return new Promise((resolve) => {
 		const startedAt = Date.now();
 		const cwd = command.cwd ? path.resolve(defaultCwd, command.cwd) : defaultCwd;
 		let stdout = "";
 		let stderr = "";
 		let timedOut = false;
+		let settled = false;
+		let hardKill: NodeJS.Timeout | undefined;
 		const child = spawn(command.command, {
 			cwd,
 			env: { ...process.env, ...(command.env ?? {}) },
@@ -724,12 +726,39 @@ function runVerifyCommand(command: AcceptanceVerifyCommand, defaultCwd: string):
 			stdio: ["ignore", "pipe", "pipe"],
 			windowsHide: true,
 		});
-		const timeout = setTimeout(() => {
+		const finish = (result: Omit<AcceptanceVerifyResult, "id" | "command" | "cwd" | "durationMs">) => {
+			if (settled) return;
+			settled = true;
+			clearTimeout(timeout);
+			if (hardKill) clearTimeout(hardKill);
+			options.signal?.removeEventListener("abort", abortVerification);
+			resolve({
+				id: command.id,
+				command: command.command,
+				cwd,
+				durationMs: Date.now() - startedAt,
+				...result,
+			});
+		};
+		const abortVerification = () => {
+			if (settled || timedOut) return;
 			timedOut = true;
 			child.kill("SIGTERM");
-			setTimeout(() => child.kill("SIGKILL"), 1000).unref?.();
-		}, command.timeoutMs ?? 120_000);
+			hardKill = setTimeout(() => {
+				child.kill("SIGKILL");
+				finish({
+					exitCode: null,
+					status: "timed-out",
+					stdout: trimOutput(stdout),
+					stderr: trimOutput(stderr || options.abortMessage || "Acceptance verification timed out."),
+				});
+			}, 1000);
+			hardKill.unref?.();
+		};
+		const timeout = setTimeout(abortVerification, command.timeoutMs ?? 120_000);
 		timeout.unref?.();
+		if (options.signal?.aborted) abortVerification();
+		else options.signal?.addEventListener("abort", abortVerification, { once: true });
 		child.stdout.on("data", (chunk: Buffer) => {
 			stdout += chunk.toString();
 		});
@@ -737,30 +766,19 @@ function runVerifyCommand(command: AcceptanceVerifyCommand, defaultCwd: string):
 			stderr += chunk.toString();
 		});
 		child.on("close", (exitCode) => {
-			clearTimeout(timeout);
-			const durationMs = Date.now() - startedAt;
 			const passed = exitCode === 0 && !timedOut;
-			resolve({
-				id: command.id,
-				command: command.command,
-				cwd,
+			finish({
 				exitCode,
 				status: timedOut ? "timed-out" : passed ? "passed" : command.allowFailure ? "allowed-failure" : "failed",
 				stdout: trimOutput(stdout),
-				stderr: trimOutput(stderr),
-				durationMs,
+				stderr: trimOutput(stderr || (timedOut ? options.abortMessage ?? "" : "")),
 			});
 		});
 		child.on("error", (error) => {
-			clearTimeout(timeout);
-			resolve({
-				id: command.id,
-				command: command.command,
-				cwd,
-				exitCode: 1,
-				status: command.allowFailure ? "allowed-failure" : "failed",
-				stderr: error instanceof Error ? error.message : String(error),
-				durationMs: Date.now() - startedAt,
+			finish({
+				exitCode: timedOut ? null : 1,
+				status: timedOut ? "timed-out" : command.allowFailure ? "allowed-failure" : "failed",
+				stderr: timedOut ? trimOutput(stderr || options.abortMessage || "Acceptance verification timed out.") : error instanceof Error ? error.message : String(error),
 			});
 		});
 	});
@@ -772,6 +790,8 @@ export async function evaluateAcceptance(input: {
 	cwd: string;
 	report?: AcceptanceReport;
 	reviewResult?: AcceptanceReviewResult;
+	signal?: AbortSignal;
+	abortMessage?: string;
 }): Promise<AcceptanceLedger> {
 	const acceptance = input.acceptance;
 	const ledger: AcceptanceLedger = {
@@ -815,7 +835,10 @@ export async function evaluateAcceptance(input: {
 			return ledger;
 		}
 		ledger.verifyRuns = [];
-		for (const command of acceptance.verify) ledger.verifyRuns.push(await runVerifyCommand(command, input.cwd));
+		for (const command of acceptance.verify) {
+			ledger.verifyRuns.push(await runVerifyCommand(command, input.cwd, { signal: input.signal, abortMessage: input.abortMessage }));
+			if (input.signal?.aborted) break;
+		}
 		if (ledger.verifyRuns.some((run) => run.status === "failed" || run.status === "timed-out")) {
 			ledger.status = "rejected";
 			return ledger;

package/src/runs/shared/dynamic-fanout.ts

@@ -42,7 +42,7 @@ const ITEM_NAME_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
 const ITEM_REF_PATTERN = /\{([A-Za-z_][A-Za-z0-9_]*)(?:\.([^{}]+))?\}/g;
 const RESERVED_TEMPLATE_NAMES = new Set(["task", "previous", "chain_dir", "outputs"]);
 const DYNAMIC_STEP_KEYS = new Set(["expand", "parallel", "collect", "concurrency", "failFast", "phase", "label", "acceptance"]);
-const RUNNER_DYNAMIC_STEP_KEYS = new Set([...DYNAMIC_STEP_KEYS, "effectiveAcceptance"]);
+const RUNNER_DYNAMIC_STEP_KEYS = new Set([...DYNAMIC_STEP_KEYS, "effectiveAcceptance", "sessionFiles", "thinkingOverrides"]);
 const DYNAMIC_EXPAND_KEYS = new Set(["from", "item", "key", "maxItems", "onEmpty"]);
 const DYNAMIC_EXPAND_FROM_KEYS = new Set(["output", "path"]);
 const DYNAMIC_PARALLEL_KEYS = new Set(["agent", "task", "phase", "label", "outputSchema", "cwd", "output", "outputMode", "reads", "progress", "skill", "model", "acceptance"]);

package/src/runs/shared/model-fallback.ts

@@ -126,6 +126,10 @@ const RETRYABLE_MODEL_FAILURE_PATTERNS = [
 	/\b502\b/,
 	/\b503\b/,
 	/\b504\b/,
+	/cold.?start/i,
+	/empty response/i,
+	/no output/i,
+	/model.*(?:load|fail|error)/i,
 ];
 
 export function isRetryableModelFailure(error: string | undefined): boolean {

package/src/runs/shared/nested-events.ts

@@ -184,6 +184,17 @@ function sanitizeTokenUsage(value: unknown): NestedRunSummary["totalTokens"] | u
 		: undefined;
 }
 
+function sanitizeCost(value: unknown): NestedRunSummary["totalCost"] | undefined {
+	if (!value || typeof value !== "object") return undefined;
+	const raw = value as Record<string, unknown>;
+	const inputTokens = clampNumber(raw.inputTokens);
+	const outputTokens = clampNumber(raw.outputTokens);
+	const costUsd = clampNumber(raw.costUsd);
+	return inputTokens !== undefined && outputTokens !== undefined && costUsd !== undefined
+		? { inputTokens, outputTokens, costUsd }
+		: undefined;
+}
+
 function sanitizeState(value: unknown, fallback: NestedRunState): NestedRunState {
 	return value === "queued" || value === "running" || value === "complete" || value === "failed" || value === "paused"
 		? value
@@ -212,6 +223,7 @@ function sanitizeStep(input: unknown, depth: number): NestedStepSummary | undefi
 		...(clampNumber(raw.startedAt) !== undefined ? { startedAt: clampNumber(raw.startedAt) } : {}),
 		...(clampNumber(raw.endedAt) !== undefined ? { endedAt: clampNumber(raw.endedAt) } : {}),
 		...(stringValue(raw.error, 1024) ? { error: stringValue(raw.error, 1024) } : {}),
+		...(raw.timedOut === true ? { timedOut: true } : {}),
 		...(depth < MAX_DEPTH && Array.isArray(raw.children) ? { children: raw.children.map((child) => sanitizeSummary(child, depth + 1)).filter((child): child is NestedRunSummary => Boolean(child)).slice(0, MAX_CHILDREN) } : {}),
 	};
 }
@@ -225,6 +237,7 @@ export function sanitizeSummary(input: unknown, depth = 0): NestedRunSummary | u
 		? raw.steps.map((step) => sanitizeStep(step, depth + 1)).filter((step): step is NestedStepSummary => Boolean(step)).slice(0, MAX_STEPS)
 		: undefined;
 	const totalTokens = sanitizeTokenUsage(raw.totalTokens);
+	const totalCost = sanitizeCost(raw.totalCost);
 	return {
 		id: raw.id,
 		parentRunId: raw.parentRunId,
@@ -256,9 +269,13 @@ export function sanitizeSummary(input: unknown, depth = 0): NestedRunSummary | u
 		...(clampNumber(raw.turnCount) !== undefined ? { turnCount: clampNumber(raw.turnCount) } : {}),
 		...(clampNumber(raw.toolCount) !== undefined ? { toolCount: clampNumber(raw.toolCount) } : {}),
 		...(totalTokens ? { totalTokens } : {}),
+		...(totalCost ? { totalCost } : {}),
 		...(clampNumber(raw.startedAt) !== undefined ? { startedAt: clampNumber(raw.startedAt) } : {}),
 		...(clampNumber(raw.endedAt) !== undefined ? { endedAt: clampNumber(raw.endedAt) } : {}),
 		...(clampNumber(raw.lastUpdate) !== undefined ? { lastUpdate: clampNumber(raw.lastUpdate) } : {}),
+		...(clampNumber(raw.timeoutMs) !== undefined ? { timeoutMs: clampNumber(raw.timeoutMs) } : {}),
+		...(clampNumber(raw.deadlineAt) !== undefined ? { deadlineAt: clampNumber(raw.deadlineAt) } : {}),
+		...(raw.timedOut === true ? { timedOut: true } : {}),
 		...(stringValue(raw.error, 1024) ? { error: stringValue(raw.error, 1024) } : {}),
 		...(steps && steps.length > 0 ? { steps } : {}),
 		...(depth < MAX_DEPTH && Array.isArray(raw.children) ? { children: raw.children.map((child) => sanitizeSummary(child, depth + 1)).filter((child): child is NestedRunSummary => Boolean(child)).slice(0, MAX_CHILDREN) } : {}),
@@ -394,6 +411,42 @@ export function findNestedRouteForRootId(rootRunId: string): NestedRoute | undef
 	return undefined;
 }
 
+/**
+ * Scan the nested-events directory once and index every route by its root run
+ * id. Use this when resolving routes for many runs (e.g. listAsyncRuns) so the
+ * cost is O(routes) total instead of O(runs * routes) from calling
+ * findNestedRouteForRootId per run.
+ */
+export function buildNestedRouteIndex(): Map<string, NestedRoute> {
+	let entries: string[];
+	try {
+		entries = fs.readdirSync(NESTED_EVENTS_DIR);
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") return new Map();
+		throw error;
+	}
+	const index = new Map<string, NestedRoute>();
+	for (const entry of entries) {
+		const routeRoot = path.join(NESTED_EVENTS_DIR, entry);
+		try {
+			const metadata = JSON.parse(fs.readFileSync(path.join(routeRoot, ROUTE_FILE), "utf-8")) as { rootRunId?: unknown; capabilityToken?: unknown };
+			if (typeof metadata.rootRunId !== "string" || typeof metadata.capabilityToken !== "string") continue;
+			if (index.has(metadata.rootRunId)) continue;
+			const route: NestedRoute = {
+				rootRunId: metadata.rootRunId,
+				eventSink: path.join(routeRoot, "events"),
+				controlInbox: path.join(routeRoot, "controls"),
+				capabilityToken: metadata.capabilityToken,
+			};
+			validateRouteShape(route);
+			index.set(metadata.rootRunId, route);
+		} catch {
+			continue;
+		}
+	}
+	return index;
+}
+
 export function projectNestedRegistryForRoot(rootRunId: string): NestedRegistry | undefined {
 	const route = findNestedRouteForRootId(rootRunId);
 	return route ? projectNestedEvents(route) : undefined;
@@ -778,6 +831,10 @@ export function nestedSummaryFromAsyncStatus(status: AsyncStatus, asyncDir: stri
 		...(status.turnCount !== undefined ? { turnCount: status.turnCount } : {}),
 		...(status.toolCount !== undefined ? { toolCount: status.toolCount } : {}),
 		...(status.totalTokens ? { totalTokens: status.totalTokens } : {}),
+		...(status.timeoutMs !== undefined ? { timeoutMs: status.timeoutMs } : {}),
+		...(status.deadlineAt !== undefined ? { deadlineAt: status.deadlineAt } : {}),
+		...(status.timedOut !== undefined ? { timedOut: status.timedOut } : {}),
+		...(status.error ? { error: status.error } : {}),
 		...(status.startedAt !== undefined ? { startedAt: status.startedAt } : { startedAt: fallback.ts }),
 		...(status.endedAt !== undefined ? { endedAt: status.endedAt } : {}),
 		lastUpdate: status.lastUpdate ?? fallback.ts,
@@ -796,6 +853,7 @@ export function nestedSummaryFromAsyncStatus(status: AsyncStatus, asyncDir: stri
 			...(step.startedAt !== undefined ? { startedAt: step.startedAt } : {}),
 			...(step.endedAt !== undefined ? { endedAt: step.endedAt } : {}),
 			...(step.error ? { error: step.error } : {}),
+			...(step.timedOut !== undefined ? { timedOut: step.timedOut } : {}),
 		})).slice(0, MAX_STEPS) } : {}),
 	};
 }

package/src/runs/shared/parallel-utils.ts

@@ -55,6 +55,8 @@ export interface DynamicRunnerGroup {
 	failFast?: boolean;
 	phase?: string;
 	label?: string;
+	sessionFiles?: (string | undefined)[];
+	thinkingOverrides?: (string | undefined)[];
 	effectiveAcceptance?: import("../../shared/types.ts").ResolvedAcceptanceConfig;
 }
 
@@ -82,10 +84,47 @@ export function flattenSteps(steps: RunnerStep[]): RunnerSubagentStep[] {
 	return flat;
 }
 
+export const DEFAULT_GLOBAL_CONCURRENCY_LIMIT = 20;
+
+/**
+ * A promise-based semaphore for limiting concurrent access across multiple
+ * mapConcurrent calls within a single run. Enforces a global cap on the total
+ * number of subagent tasks executing simultaneously, regardless of each step's
+ * per-step concurrency limit.
+ */
+export class Semaphore {
+	private available: number;
+	private readonly queue: Array<() => void> = [];
+
+	constructor(limit: number) {
+		this.available = Math.max(1, Math.floor(limit) || 1);
+	}
+
+	acquire(): Promise<void> {
+		if (this.available > 0) {
+			this.available--;
+			return Promise.resolve();
+		}
+		return new Promise<void>((resolve) => {
+			this.queue.push(resolve);
+		});
+	}
+
+	release(): void {
+		const next = this.queue.shift();
+		if (next) {
+			next();
+		} else {
+			this.available++;
+		}
+	}
+}
+
 export async function mapConcurrent<T, R>(
 	items: T[],
 	limit: number,
 	fn: (item: T, i: number) => Promise<R>,
+	globalSemaphore?: Semaphore,
 ): Promise<R[]> {
 	const safeLimit = Math.max(1, Math.floor(limit) || 1);
 	const results: R[] = new Array(items.length);
@@ -94,7 +133,16 @@ export async function mapConcurrent<T, R>(
 	async function worker(_workerIndex: number): Promise<void> {
 		while (next < items.length) {
 			const i = next++;
-			results[i] = await fn(items[i], i);
+			if (globalSemaphore) {
+				await globalSemaphore.acquire();
+				try {
+					results[i] = await fn(items[i], i);
+				} finally {
+					globalSemaphore.release();
+				}
+			} else {
+				results[i] = await fn(items[i], i);
+			}
 		}
 	}
 

package/src/runs/shared/pi-args.ts

@@ -73,10 +73,12 @@ interface BuildPiArgsResult {
 	tempDir?: string;
 }
 
-export function applyThinkingSuffix(model: string | undefined, thinking: string | undefined): string | undefined {
-	if (!model || !thinking || thinking === "off") return model;
+export function applyThinkingSuffix(model: string | undefined, thinking: string | undefined, replaceExisting = false): string | undefined {
+	if (!model || !thinking) return model;
 	const colonIdx = model.lastIndexOf(":");
-	if (colonIdx !== -1 && THINKING_LEVELS.includes(model.substring(colonIdx + 1))) return model;
+	if (colonIdx !== -1 && THINKING_LEVELS.includes(model.substring(colonIdx + 1))) {
+		return replaceExisting ? `${model.slice(0, colonIdx)}:${thinking}` : model;
+	}
 	return `${model}:${thinking}`;
 }
 

package/src/runs/shared/pi-spawn.ts

@@ -3,13 +3,18 @@ import * as path from "node:path";
 import { fileURLToPath } from "node:url";
 
 export const PI_CODING_AGENT_PACKAGE = "@earendil-works/pi-coding-agent";
+export const PI_SUBAGENT_PI_BINARY_ENV = "PI_SUBAGENT_PI_BINARY";
 
-export function findPiPackageRootFromEntry(entryPoint: string): string | undefined {
+export function findPiPackageRootFromEntry(
+	entryPoint: string,
+): string | undefined {
 	let dir = path.dirname(entryPoint);
 	while (dir !== path.dirname(dir)) {
 		const packageJsonPath = path.join(dir, "package.json");
 		if (fs.existsSync(packageJsonPath)) {
-			const pkg = JSON.parse(fs.readFileSync(packageJsonPath, "utf-8")) as { name?: unknown };
+			const pkg = JSON.parse(fs.readFileSync(packageJsonPath, "utf-8")) as {
+				name?: unknown;
+			};
 			if (pkg.name === PI_CODING_AGENT_PACKAGE) return dir;
 		}
 		dir = path.dirname(dir);
@@ -18,13 +23,17 @@ export function findPiPackageRootFromEntry(entryPoint: string): string | undefin
 }
 
 export function resolveInstalledPiPackageRoot(): string | undefined {
-	return findPiPackageRootFromEntry(fileURLToPath(import.meta.resolve(PI_CODING_AGENT_PACKAGE)));
+	return findPiPackageRootFromEntry(
+		fileURLToPath(import.meta.resolve(PI_CODING_AGENT_PACKAGE)),
+	);
 }
 
 export function resolvePiPackageRoot(): string | undefined {
 	try {
 		const entry = process.argv[1];
-		return entry ? findPiPackageRootFromEntry(fs.realpathSync(entry)) : undefined;
+		return entry
+			? findPiPackageRootFromEntry(fs.realpathSync(entry))
+			: undefined;
 	} catch {
 		// process.argv[1] probing is best-effort; callers can fall back to PATH/package resolution.
 		return undefined;
@@ -40,6 +49,7 @@ export interface PiSpawnDeps {
 	resolvePackageJson?: () => string;
 	resolvePackageEntry?: () => string;
 	piPackageRoot?: string;
+	env?: NodeJS.ProcessEnv;
 }
 
 interface PiSpawnCommand {
@@ -47,7 +57,10 @@ interface PiSpawnCommand {
 	args: string[];
 }
 
-function isRunnableNodeScript(filePath: string, existsSync: (filePath: string) => boolean): boolean {
+function isRunnableNodeScript(
+	filePath: string,
+	existsSync: (filePath: string) => boolean,
+): boolean {
 	if (!existsSync(filePath)) return false;
 	return /\.(?:mjs|cjs|js)$/i.test(filePath);
 }
@@ -56,9 +69,13 @@ function normalizePath(filePath: string): string {
 	return path.isAbsolute(filePath) ? filePath : path.resolve(filePath);
 }
 
-export function resolveWindowsPiCliScript(deps: PiSpawnDeps = {}): string | undefined {
+export function resolveWindowsPiCliScript(
+	deps: PiSpawnDeps = {},
+): string | undefined {
 	const existsSync = deps.existsSync ?? fs.existsSync;
-	const readFileSync = deps.readFileSync ?? ((filePath, encoding) => fs.readFileSync(filePath, encoding));
+	const readFileSync =
+		deps.readFileSync ??
+		((filePath, encoding) => fs.readFileSync(filePath, encoding));
 	const argv1 = deps.argv1 ?? process.argv[1];
 
 	if (argv1) {
@@ -69,23 +86,29 @@ export function resolveWindowsPiCliScript(deps: PiSpawnDeps = {}): string | unde
 	}
 
 	try {
-		const resolvePackageJson = deps.resolvePackageJson ?? (() => {
-			const root = deps.piPackageRoot ?? resolvePiPackageRoot();
-			if (root) return path.join(root, "package.json");
-			const packageRoot = deps.resolvePackageEntry
-				? findPiPackageRootFromEntry(deps.resolvePackageEntry())
-				: resolveInstalledPiPackageRoot();
-			if (!packageRoot) throw new Error(`Could not resolve ${PI_CODING_AGENT_PACKAGE} package root`);
-			return path.join(packageRoot, "package.json");
-		});
+		const resolvePackageJson =
+			deps.resolvePackageJson ??
+			(() => {
+				const root = deps.piPackageRoot ?? resolvePiPackageRoot();
+				if (root) return path.join(root, "package.json");
+				const packageRoot = deps.resolvePackageEntry
+					? findPiPackageRootFromEntry(deps.resolvePackageEntry())
+					: resolveInstalledPiPackageRoot();
+				if (!packageRoot)
+					throw new Error(
+						`Could not resolve ${PI_CODING_AGENT_PACKAGE} package root`,
+					);
+				return path.join(packageRoot, "package.json");
+			});
 		const packageJsonPath = resolvePackageJson();
 		const packageJson = JSON.parse(readFileSync(packageJsonPath, "utf-8")) as {
 			bin?: string | Record<string, string>;
 		};
 		const binField = packageJson.bin;
-		const binPath = typeof binField === "string"
-			? binField
-			: binField?.pi ?? Object.values(binField ?? {})[0];
+		const binPath =
+			typeof binField === "string"
+				? binField
+				: (binField?.pi ?? Object.values(binField ?? {})[0]);
 		if (!binPath) return undefined;
 		const candidate = path.resolve(path.dirname(packageJsonPath), binPath);
 		if (isRunnableNodeScript(candidate, existsSync)) {
@@ -99,7 +122,16 @@ export function resolveWindowsPiCliScript(deps: PiSpawnDeps = {}): string | unde
 	return undefined;
 }
 
-export function getPiSpawnCommand(args: string[], deps: PiSpawnDeps = {}): PiSpawnCommand {
+export function getPiSpawnCommand(
+	args: string[],
+	deps: PiSpawnDeps = {},
+): PiSpawnCommand {
+	const env = deps.env ?? process.env;
+	const piBinary = env[PI_SUBAGENT_PI_BINARY_ENV]?.trim();
+	if (piBinary) {
+		return { command: piBinary, args };
+	}
+
 	const platform = deps.platform ?? process.platform;
 	if (platform === "win32") {
 		const piCliPath = resolveWindowsPiCliScript(deps);

package/src/runs/shared/single-output.ts

@@ -22,9 +22,11 @@ export function resolveSingleOutputPath(
 	output: string | boolean | undefined,
 	runtimeCwd: string,
 	requestedCwd?: string,
+	relativeBaseDir?: string,
 ): string | undefined {
 	if (typeof output !== "string" || !output || output === "false" || output === "true") return undefined;
 	if (path.isAbsolute(output)) return output;
+	if (relativeBaseDir) return path.resolve(relativeBaseDir, output);
 	const baseCwd = requestedCwd
 		? (path.isAbsolute(requestedCwd) ? requestedCwd : path.resolve(runtimeCwd, requestedCwd))
 		: runtimeCwd;

package/src/runs/shared/subagent-prompt-runtime.ts

@@ -20,7 +20,7 @@ export const CHILD_SUBAGENT_BOUNDARY_INSTRUCTIONS = [
 	"The parent session owns delegation, orchestration, review fanout, and follow-up worker launches.",
 	"Ignore prior parent-only orchestration instructions in inherited conversation history.",
 	"Do not propose or run subagents. Complete only your assigned role-specific task with the tools available to you.",
-	"If you need to edit files, call the actual edit/write tools. Do not print tool-call syntax, patches, or pseudo-tool calls as text.",
+	"If you need to edit files, use the available editing tools. Do not print tool-call syntax, patches, or pseudo-tool calls as text.",
 ].join("\n");
 
 export const CHILD_FANOUT_BOUNDARY_INSTRUCTIONS = [
@@ -29,12 +29,13 @@ export const CHILD_FANOUT_BOUNDARY_INSTRUCTIONS = [
 	"You may use the `subagent` tool only for the fanout work explicitly requested in this task.",
 	"Do not broaden yourself into general parent orchestration. Do not launch follow-up workers unless the task explicitly asks for that.",
 	"The maxSubagentDepth cap still applies and may block further fanout.",
-	"If you need to edit files, call the actual edit/write tools. Do not print tool-call syntax, patches, or pseudo-tool calls as text.",
+	"If you need to edit files, use the available editing tools. Do not print tool-call syntax, patches, or pseudo-tool calls as text.",
 ].join("\n");
 
 const PARENT_ONLY_CUSTOM_MESSAGE_TYPES = new Set([
 	"subagent-orchestration-instructions",
 	"subagent-slash-result",
+	"subagent-slash-text-result",
 	"subagent-notify",
 	"subagent_control_notice",
 	"subagent-control",

package/src/runs/shared/worktree.ts

@@ -43,6 +43,7 @@ interface WorktreeSetupHookConfig {
 interface CreateWorktreesOptions {
 	agents?: string[];
 	setupHook?: WorktreeSetupHookConfig;
+	baseDir?: string;
 }
 
 interface ResolvedWorktreeSetupHook {
@@ -152,8 +153,26 @@ function buildWorktreeBranch(runId: string, index: number): string {
 	return `pi-parallel-${runId}-${index}`;
 }
 
-function buildWorktreePath(runId: string, index: number): string {
-	return path.join(os.tmpdir(), `pi-worktree-${runId}-${index}`);
+function resolveWorktreeBaseDir(configuredBaseDir: string | undefined, repoRoot: string): string {
+	const rawBaseDir = configuredBaseDir ?? process.env.PI_SUBAGENTS_WORKTREE_DIR;
+	if (rawBaseDir === undefined) return os.tmpdir();
+
+	const trimmed = rawBaseDir.trim();
+	if (!trimmed) throw new Error("worktree base directory cannot be empty");
+
+	const expanded = trimmed.startsWith("~/") ? path.join(os.homedir(), trimmed.slice(2)) : trimmed;
+	const resolved = path.isAbsolute(expanded) ? expanded : path.resolve(repoRoot, expanded);
+	try {
+		fs.mkdirSync(resolved, { recursive: true });
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		throw new Error(`failed to create worktree base directory ${resolved}: ${message}`);
+	}
+	return resolved;
+}
+
+function buildWorktreePath(baseDir: string, runId: string, index: number): string {
+	return path.join(baseDir, `pi-worktree-${runId}-${index}`);
 }
 
 function resolveRepoCwdRelative(cwd: string): string {
@@ -168,9 +187,10 @@ function resolveRepoCwdRelative(cwd: string): string {
 	return normalizedPrefix === "." ? "" : normalizedPrefix;
 }
 
-export function resolveExpectedWorktreeAgentCwd(cwd: string, runId: string, index: number): string {
+export function resolveExpectedWorktreeAgentCwd(cwd: string, runId: string, index: number, baseDir?: string): string {
 	const cwdRelative = resolveRepoCwdRelative(cwd);
-	const worktreePath = buildWorktreePath(runId, index);
+	const repoRoot = runGitChecked(cwd, ["rev-parse", "--show-toplevel"]).trim();
+	const worktreePath = buildWorktreePath(resolveWorktreeBaseDir(baseDir, repoRoot), runId, index);
 	return cwdRelative ? path.join(worktreePath, cwdRelative) : worktreePath;
 }
 
@@ -320,9 +340,10 @@ function createSingleWorktree(
 	baseCommit: string,
 	setupHook: ResolvedWorktreeSetupHook | undefined,
 	agent: string | undefined,
+	baseDir: string,
 ): WorktreeInfo {
 	const branch = buildWorktreeBranch(runId, index);
-	const worktreePath = buildWorktreePath(runId, index);
+	const worktreePath = buildWorktreePath(baseDir, runId, index);
 	const add = runGit(toplevel, ["worktree", "add", worktreePath, "-b", branch, "HEAD"]);
 	if (add.status !== 0) {
 		const message = add.stderr.trim() || add.stdout.trim() || `failed to create worktree ${worktreePath}`;
@@ -492,6 +513,7 @@ function hasWorktreeChanges(diff: WorktreeDiff): boolean {
 export function createWorktrees(cwd: string, runId: string, count: number, options?: CreateWorktreesOptions): WorktreeSetup {
 	const repo = resolveRepoState(cwd);
 	const setupHook = resolveWorktreeSetupHook(repo.toplevel, options?.setupHook);
+	const baseDir = resolveWorktreeBaseDir(options?.baseDir, repo.toplevel);
 	const worktrees: WorktreeInfo[] = [];
 
 	try {
@@ -504,6 +526,7 @@ export function createWorktrees(cwd: string, runId: string, count: number, optio
 				repo.baseCommit,
 				setupHook,
 				options?.agents?.[index],
+				baseDir,
 			));
 		}
 	} catch (error) {

package/src/shared/artifacts.ts

@@ -3,8 +3,22 @@ import * as path from "node:path";
 import { TEMP_ARTIFACTS_DIR, type ArtifactPaths } from "./types.ts";
 import { getAgentDir } from "./utils.ts";
 const CLEANUP_MARKER_FILE = ".last-cleanup";
+const PROJECT_ARTIFACT_ROOT = ".pi-subagents";
 
-export function getArtifactsDir(sessionFile: string | null): string {
+export function getProjectSubagentsDir(cwd: string): string {
+	return path.join(cwd, PROJECT_ARTIFACT_ROOT);
+}
+
+export function getProjectArtifactsDir(cwd: string): string {
+	return path.join(getProjectSubagentsDir(cwd), "artifacts");
+}
+
+export function getProjectChainRunsDir(cwd: string): string {
+	return path.join(getProjectSubagentsDir(cwd), "chain-runs");
+}
+
+export function getArtifactsDir(sessionFile: string | null, projectCwd?: string): string {
+	if (projectCwd) return getProjectArtifactsDir(projectCwd);
 	if (sessionFile) {
 		const sessionDir = path.dirname(sessionFile);
 		return path.join(sessionDir, "subagent-artifacts");