pi-subagents 0.31.1 → 0.33.0

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

@@ -38,6 +38,7 @@ export interface RunnerSubagentStep {
 	};
 	structuredOutputSchema?: import("../../shared/types.ts").JsonSchemaObject;
 	effectiveAcceptance?: import("../../shared/types.ts").ResolvedAcceptanceConfig;
+	toolBudget?: import("../../shared/types.ts").ResolvedToolBudget;
 }
 
 export interface ParallelStepGroup {
@@ -55,6 +56,8 @@ export interface DynamicRunnerGroup {
 	failFast?: boolean;
 	phase?: string;
 	label?: string;
+	sessionFiles?: (string | undefined)[];
+	thinkingOverrides?: (string | undefined)[];
 	effectiveAcceptance?: import("../../shared/types.ts").ResolvedAcceptanceConfig;
 }
 
@@ -82,10 +85,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 +134,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

@@ -5,7 +5,8 @@ import { fileURLToPath } from "node:url";
 import { encodeNestedPathEnv, parseNestedPathEnv, type NestedPathEntry } from "./nested-path.ts";
 import { resolveMcpDirectToolNames } from "./mcp-direct-tool-allowlist.ts";
 import { STRUCTURED_OUTPUT_CAPTURE_ENV, STRUCTURED_OUTPUT_SCHEMA_ENV } from "./structured-output.ts";
-import type { JsonSchemaObject } from "../../shared/types.ts";
+import { TEMP_ROOT_DIR, type JsonSchemaObject, type ResolvedToolBudget } from "../../shared/types.ts";
+import { TOOL_BUDGET_ENV, encodeToolBudgetEnv } from "./tool-budget.ts";
 
 const THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh"];
 const TASK_ARG_LIMIT = 8000;
@@ -13,6 +14,8 @@ const PROMPT_RUNTIME_EXTENSION_PATH = path.join(path.dirname(fileURLToPath(impor
 const FANOUT_CHILD_EXTENSION_PATH = path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "..", "extension", "fanout-child.ts");
 export const SUBAGENT_CHILD_ENV = "PI_SUBAGENT_CHILD";
 export const SUBAGENT_ORCHESTRATOR_TARGET_ENV = "PI_SUBAGENT_ORCHESTRATOR_TARGET";
+export const SUBAGENT_ORCHESTRATOR_SESSION_ID_ENV = "PI_SUBAGENT_ORCHESTRATOR_SESSION_ID";
+export const SUBAGENT_SUPERVISOR_CHANNEL_DIR_ENV = "PI_SUBAGENT_SUPERVISOR_CHANNEL_DIR";
 export const SUBAGENT_RUN_ID_ENV = "PI_SUBAGENT_RUN_ID";
 export const SUBAGENT_CHILD_AGENT_ENV = "PI_SUBAGENT_CHILD_AGENT";
 export const SUBAGENT_CHILD_INDEX_ENV = "PI_SUBAGENT_CHILD_INDEX";
@@ -26,6 +29,7 @@ export const SUBAGENT_PARENT_DEPTH_ENV = "PI_SUBAGENT_PARENT_DEPTH";
 export const SUBAGENT_PARENT_PATH_ENV = "PI_SUBAGENT_PARENT_PATH";
 export const SUBAGENT_PARENT_CAPABILITY_TOKEN_ENV = "PI_SUBAGENT_PARENT_CAPABILITY_TOKEN";
 export const SUBAGENT_PARENT_SESSION_ENV = "PI_SUBAGENT_PARENT_SESSION";
+export const SUBAGENT_STEER_INBOX_ENV = "PI_SUBAGENT_STEER_INBOX";
 
 interface BuildPiArgsInput {
 	parentSessionId?: string;
@@ -60,11 +64,13 @@ interface BuildPiArgsInput {
 	parentDepth?: number;
 	parentPath?: NestedPathEntry[];
 	parentCapabilityToken?: string;
+	steerInboxDir?: string;
 	structuredOutput?: {
 		schema: JsonSchemaObject;
 		schemaPath: string;
 		outputPath: string;
 	};
+	toolBudget?: ResolvedToolBudget;
 }
 
 interface BuildPiArgsResult {
@@ -73,10 +79,20 @@ interface BuildPiArgsResult {
 	tempDir?: string;
 }
 
-export function applyThinkingSuffix(model: string | undefined, thinking: string | undefined): string | undefined {
-	if (!model || !thinking || thinking === "off") return model;
+function sanitizeSupervisorChannelSegment(value: string): string {
+	return value.trim().replace(/[^A-Za-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "") || "unknown";
+}
+
+function supervisorChannelDir(runId: string, agent: string, childIndex: number): string {
+	return path.join(TEMP_ROOT_DIR, "supervisor-channels", `${sanitizeSupervisorChannelSegment(runId)}-${sanitizeSupervisorChannelSegment(agent)}-${childIndex}`);
+}
+
+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}`;
 }
 
@@ -204,6 +220,16 @@ export function buildPiArgs(input: BuildPiArgsInput): BuildPiArgsResult {
 	if (input.orchestratorIntercomTarget) {
 		env[SUBAGENT_ORCHESTRATOR_TARGET_ENV] = input.orchestratorIntercomTarget;
 	}
+	if (input.parentSessionId) {
+		env[SUBAGENT_ORCHESTRATOR_SESSION_ID_ENV] = input.parentSessionId;
+	}
+	if (input.orchestratorIntercomTarget && input.parentSessionId && input.runId && input.childAgentName) {
+		const childIndex = input.childIndex ?? 0;
+		const channelDir = supervisorChannelDir(input.runId, input.childAgentName, childIndex);
+		fs.mkdirSync(path.join(channelDir, "requests"), { recursive: true });
+		fs.mkdirSync(path.join(channelDir, "replies"), { recursive: true });
+		env[SUBAGENT_SUPERVISOR_CHANNEL_DIR_ENV] = channelDir;
+	}
 	if (input.runId) {
 		env[SUBAGENT_RUN_ID_ENV] = input.runId;
 	}
@@ -222,6 +248,11 @@ export function buildPiArgs(input: BuildPiArgsInput): BuildPiArgsResult {
 		env[STRUCTURED_OUTPUT_CAPTURE_ENV] = input.structuredOutput.outputPath;
 		env[STRUCTURED_OUTPUT_SCHEMA_ENV] = input.structuredOutput.schemaPath;
 	}
+	if (input.steerInboxDir) {
+		env[SUBAGENT_STEER_INBOX_ENV] = input.steerInboxDir;
+	}
+	const encodedToolBudget = encodeToolBudgetEnv(input.toolBudget);
+	if (encodedToolBudget) env[TOOL_BUDGET_ENV] = encodedToolBudget;
 
 	env[SUBAGENT_PARENT_SESSION_ENV] = input.parentSessionId ?? process.env[SUBAGENT_PARENT_SESSION_ENV] ?? "";
 

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

@@ -1,9 +1,12 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { SUBAGENT_FANOUT_CHILD_ENV } from "./pi-args.ts";
+import { registerNativeSupervisorClient } from "../../intercom/native-supervisor-channel.ts";
+import { consumeSteerRequestsFromDir, writeSteerRequestToDir, type SteerRequest } from "../background/control-channel.ts";
+import { SUBAGENT_FANOUT_CHILD_ENV, SUBAGENT_STEER_INBOX_ENV } from "./pi-args.ts";
 import { STRUCTURED_OUTPUT_CAPTURE_ENV, STRUCTURED_OUTPUT_SCHEMA_ENV, validateStructuredOutputValue } from "./structured-output.ts";
-import type { JsonSchemaObject } from "../../shared/types.ts";
+import { TOOL_BUDGET_ENV, decodeToolBudgetEnv, shouldBlockToolForBudget, toolBudgetBlockedMessage, toolBudgetSoftNudge } from "./tool-budget.ts";
+import type { JsonSchemaObject, ResolvedToolBudget } from "../../shared/types.ts";
 
 const SUBAGENT_INHERIT_PROJECT_CONTEXT_ENV = "PI_SUBAGENT_INHERIT_PROJECT_CONTEXT";
 const SUBAGENT_INHERIT_SKILLS_ENV = "PI_SUBAGENT_INHERIT_SKILLS";
@@ -20,7 +23,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,7 +32,7 @@ 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([
@@ -155,7 +158,110 @@ export function stripParentOnlySubagentMessages(messages: unknown[]): unknown[]
 	return changed ? filtered : messages;
 }
 
+export function formatSteerMessage(request: SteerRequest): string {
+	return [
+		"Mid-run steering from the parent orchestrator:",
+		"",
+		request.message,
+		"",
+		"Incorporate this guidance at the next safe point. Do not restart the task unless the guidance explicitly asks you to.",
+	].join("\n");
+}
+
+function registerToolBudget(pi: ExtensionAPI, budget: ResolvedToolBudget | undefined): void {
+	if (!budget) return;
+	let toolCount = 0;
+	let softNudged = false;
+	const sendUserMessage = (pi as { sendUserMessage?: (content: string, options: { deliverAs: "steer" }) => unknown }).sendUserMessage;
+	const onRuntimeEvent = pi.on as unknown as (event: string, handler: (event: { toolName?: string }) => unknown) => void;
+	onRuntimeEvent("tool_call", (event) => {
+		const toolName = typeof event.toolName === "string" ? event.toolName : "tool";
+		toolCount++;
+		if (budget.soft !== undefined && toolCount >= budget.soft && !softNudged) {
+			softNudged = true;
+			try {
+				sendUserMessage?.(toolBudgetSoftNudge(budget, toolCount), { deliverAs: "steer" });
+			} catch {
+				// Budget nudges are advisory; blocking below remains authoritative.
+			}
+		}
+		if (!shouldBlockToolForBudget(budget, toolName, toolCount)) return undefined;
+		return { block: true, reason: toolBudgetBlockedMessage(budget, toolName, toolCount) };
+	});
+}
+
+function registerSteeringInbox(pi: ExtensionAPI): void {
+	const steerInbox = process.env[SUBAGENT_STEER_INBOX_ENV]?.trim();
+	if (!steerInbox) return;
+	const sendUserMessage = (pi as { sendUserMessage?: (content: string, options: { deliverAs: "steer" }) => unknown }).sendUserMessage;
+	if (typeof sendUserMessage !== "function") return;
+
+	let canSteer = false;
+	let disposed = false;
+	let flushing = false;
+	let started = false;
+	let watcher: fs.FSWatcher | undefined;
+	let interval: NodeJS.Timeout | undefined;
+	const flush = (): void => {
+		if (disposed || flushing || !canSteer) return;
+		flushing = true;
+		try {
+			const requests = consumeSteerRequestsFromDir(steerInbox);
+			for (let index = 0; index < requests.length; index++) {
+				const request = requests[index]!;
+				try {
+					sendUserMessage(formatSteerMessage(request), { deliverAs: "steer" });
+				} catch {
+					for (const pending of requests.slice(index)) writeSteerRequestToDir(steerInbox, pending);
+					break;
+				}
+			}
+		} finally {
+			flushing = false;
+		}
+	};
+	const start = (): void => {
+		if (started || disposed) return;
+		try {
+			fs.mkdirSync(steerInbox, { recursive: true });
+		} catch {
+			return;
+		}
+		started = true;
+		try {
+			watcher = fs.watch(steerInbox, () => flush());
+			watcher.on("error", () => {});
+		} catch {
+			watcher = undefined;
+		}
+		interval = setInterval(flush, 250);
+		interval.unref?.();
+	};
+	const activate = (): undefined => {
+		start();
+		canSteer = true;
+		flush();
+		return undefined;
+	};
+
+	const onRuntimeEvent = pi.on as unknown as (event: string, handler: (event: unknown) => unknown) => void;
+	onRuntimeEvent("session_start", () => start());
+	for (const eventName of ["message_start", "message_update", "message_end", "tool_execution_start", "tool_execution_end", "turn_end"] as const) {
+		onRuntimeEvent(eventName, activate);
+	}
+	onRuntimeEvent("session_shutdown", () => {
+		disposed = true;
+		try {
+			watcher?.close();
+		} catch {}
+		if (interval) clearInterval(interval);
+	});
+}
+
 export default function registerSubagentPromptRuntime(pi: ExtensionAPI): void {
+	registerSteeringInbox(pi);
+	registerToolBudget(pi, decodeToolBudgetEnv(process.env[TOOL_BUDGET_ENV]));
+	registerNativeSupervisorClient(pi);
 	const structuredOutputPath = process.env[STRUCTURED_OUTPUT_CAPTURE_ENV];
 	const structuredSchemaPath = process.env[STRUCTURED_OUTPUT_SCHEMA_ENV];
 	if (structuredOutputPath && structuredSchemaPath) {

package/src/runs/shared/tool-budget.ts

@@ -0,0 +1,74 @@
+import type { ResolvedToolBudget, ToolBudgetConfig, ToolBudgetState } from "../../shared/types.ts";
+
+export const DEFAULT_TOOL_BUDGET_BLOCK = ["read", "grep", "find", "ls"] as const;
+export const TOOL_BUDGET_ENV = "PI_SUBAGENT_TOOL_BUDGET";
+
+export function normalizeToolBudgetBlock(block: ToolBudgetConfig["block"] | undefined): "*" | string[] {
+	if (block === "*") return "*";
+	if (block === undefined) return [...DEFAULT_TOOL_BUDGET_BLOCK];
+	return [...new Set(block.map((tool) => tool.trim()).filter(Boolean))];
+}
+
+export function validateToolBudgetConfig(raw: unknown, label = "toolBudget"): { budget?: ResolvedToolBudget; error?: string } {
+	if (raw === undefined) return {};
+	if (!raw || typeof raw !== "object" || Array.isArray(raw)) return { error: `${label} must be an object with hard and optional soft/block.` };
+	const value = raw as ToolBudgetConfig;
+	if (typeof value.hard !== "number" || !Number.isInteger(value.hard) || value.hard < 1) {
+		return { error: `${label}.hard must be an integer >= 1.` };
+	}
+	if (value.soft !== undefined && (typeof value.soft !== "number" || !Number.isInteger(value.soft) || value.soft < 1)) {
+		return { error: `${label}.soft must be an integer >= 1 when provided.` };
+	}
+	if (value.soft !== undefined && value.soft > value.hard) {
+		return { error: `${label}.soft must be <= ${label}.hard.` };
+	}
+	if (value.block !== undefined && value.block !== "*") {
+		if (!Array.isArray(value.block)) return { error: `${label}.block must be "*" or an array of tool names.` };
+		if (value.block.length === 0) return { error: `${label}.block must contain at least one tool name.` };
+		for (const item of value.block) {
+			if (typeof item !== "string" || !item.trim()) return { error: `${label}.block must contain non-empty tool names.` };
+		}
+	}
+	return { budget: { hard: value.hard, ...(value.soft !== undefined ? { soft: value.soft } : {}), block: normalizeToolBudgetBlock(value.block) } };
+}
+
+export function initialToolBudgetState(budget: ResolvedToolBudget): ToolBudgetState {
+	return { ...budget, toolCount: 0, outcome: "within-budget" };
+}
+
+export function toolBudgetState(budget: ResolvedToolBudget, toolCount: number, blockedTool?: string): ToolBudgetState {
+	const overHard = toolCount > budget.hard;
+	const overSoft = budget.soft !== undefined && toolCount >= budget.soft;
+	return {
+		...budget,
+		toolCount,
+		outcome: overHard ? "hard-blocked" : overSoft ? "soft-reached" : "within-budget",
+		...(overSoft ? { softReachedAt: budget.soft } : {}),
+		...(overHard ? { hardReachedAt: budget.hard, blockedTool } : {}),
+	};
+}
+
+export function shouldBlockToolForBudget(budget: ResolvedToolBudget, toolName: string, nextToolCount: number): boolean {
+	if (nextToolCount <= budget.hard) return false;
+	return budget.block === "*" || budget.block.includes(toolName);
+}
+
+export function toolBudgetSoftNudge(budget: ResolvedToolBudget, toolCount: number): string {
+	return `Tool budget soft limit reached after ${toolCount} tool call${toolCount === 1 ? "" : "s"} (soft ${budget.soft}, hard ${budget.hard}). Stop starting new browsing/search work and finalize from the context you already have.`;
+}
+
+export function toolBudgetBlockedMessage(budget: ResolvedToolBudget, toolName: string, toolCount: number): string {
+	return `Tool budget hard limit reached after ${toolCount} tool call${toolCount === 1 ? "" : "s"} (hard ${budget.hard}). The '${toolName}' tool is blocked so you can finalize from the context you already have.`;
+}
+
+export function encodeToolBudgetEnv(budget: ResolvedToolBudget | undefined): string | undefined {
+	return budget ? JSON.stringify(budget) : undefined;
+}
+
+export function decodeToolBudgetEnv(value: string | undefined): ResolvedToolBudget | undefined {
+	if (!value?.trim()) return undefined;
+	const parsed = JSON.parse(value) as unknown;
+	const normalized = validateToolBudgetConfig(parsed, TOOL_BUDGET_ENV);
+	if (normalized.error) throw new Error(normalized.error);
+	return normalized.budget;
+}

package/src/runs/shared/turn-budget.ts

@@ -0,0 +1,52 @@
+import type { ResolvedTurnBudget, TurnBudgetState } from "../../shared/types.ts";
+
+export const DEFAULT_TURN_BUDGET_GRACE_TURNS = 1;
+
+export function appendTurnBudgetSystemPrompt(systemPrompt: string, budget: ResolvedTurnBudget | undefined): string {
+	if (!budget) return systemPrompt;
+	const grace = budget.graceTurns === 1 ? "1 additional assistant turn" : `${budget.graceTurns} additional assistant turns`;
+	const block = [
+		"## Turn budget",
+		`This child run has a soft budget of ${budget.maxTurns} assistant turn${budget.maxTurns === 1 ? "" : "s"}.`,
+		`After that, ${grace} may be allowed only for a final wrap-up.`,
+		"When you approach or reach the soft budget, stop starting new tool work and return the final answer immediately.",
+		"This runner uses process-mode execution, so live steering after launch may be unavailable; treat this instruction as the wrap-up request.",
+		"If you continue past the soft budget plus grace turns, the supervisor may abort the process and return only partial output.",
+	].join("\n");
+	return systemPrompt.trim() ? `${systemPrompt.trim()}\n\n${block}` : block;
+}
+
+export function turnBudgetSoftNote(budget: ResolvedTurnBudget, turnCount: number): string {
+	return `Turn budget wrap-up was requested after ${turnCount} assistant turn${turnCount === 1 ? "" : "s"} (soft limit ${budget.maxTurns}, grace ${budget.graceTurns}). Process-mode live steering is unavailable, so the child was warned at launch to wrap up by this budget. Output may be partial.`;
+}
+
+export function turnBudgetExceededMessage(budget: ResolvedTurnBudget, turnCount: number): string {
+	return `Subagent exceeded turn budget after ${turnCount} assistant turn${turnCount === 1 ? "" : "s"} (soft limit ${budget.maxTurns} + grace ${budget.graceTurns}).`;
+}
+
+export function formatTurnBudgetOutput(message: string, output: string): string {
+	return output.trim()
+		? `${message}\n\nPartial output before turn-budget abort:\n${output}`
+		: message;
+}
+
+export function initialTurnBudgetState(budget: ResolvedTurnBudget): TurnBudgetState {
+	return { ...budget, outcome: "within-budget", turnCount: 0 };
+}
+
+export function turnBudgetState(budget: ResolvedTurnBudget, turnCount: number, exceeded: boolean): TurnBudgetState {
+	return {
+		...budget,
+		turnCount,
+		outcome: exceeded ? "exceeded" : "wrap-up-requested",
+		wrapUpRequestedAtTurn: budget.maxTurns,
+		...(exceeded ? { exceededAtTurn: turnCount } : {}),
+	};
+}
+
+export function shouldAbortForTurnBudget(budget: ResolvedTurnBudget, turnCount: number, terminalAssistantStop: boolean): boolean {
+	const hardLimit = budget.maxTurns + budget.graceTurns;
+	if (turnCount < hardLimit) return false;
+	if (turnCount > hardLimit) return true;
+	return !terminalAssistantStop;
+}

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) {