pi-subagents 0.63.0 → 0.65.0

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

@@ -1,10 +1,3 @@
-import * as fs from "node:fs";
-import * as path from "node:path";
-
-export const REQUIRED_CHILD_TOOLS_ENV = "PI_SUBAGENT_REQUIRED_TOOLS";
-export const MCP_DIRECT_CHILD_TOOLS_ENV = "PI_SUBAGENT_MCP_DIRECT_TOOLS";
-export const CHILD_TOOL_DIAGNOSTIC_PATH_ENV = "PI_SUBAGENT_TOOL_DIAGNOSTIC_PATH";
-
 export interface ChildToolDiagnostic {
 	agent?: string;
 	required: string[];
@@ -13,53 +6,25 @@ export interface ChildToolDiagnostic {
 	missingMcpDirectTools?: string[];
 }
 
-export function writeChildToolDiagnostic(
-	filePath: string,
-	required: string[],
-	available: string[],
-	agent?: string,
-	mcpDirectTools?: string[],
-): ChildToolDiagnostic | undefined {
-	const availableNames = new Set(available);
-	const missing = required.filter((name) => !availableNames.has(name));
-	if (missing.length === 0) {
-		fs.rmSync(filePath, { force: true });
-		return undefined;
-	}
-
-	const missingMcpDirectTools = mcpDirectTools?.length
-		? missing.filter((name) => mcpDirectTools.includes(name))
-		: [];
-	const diagnostic: ChildToolDiagnostic = {
-		agent,
-		required,
-		available,
-		missing,
-		...(missingMcpDirectTools.length > 0 ? { missingMcpDirectTools } : {}),
-	};
-	fs.mkdirSync(path.dirname(filePath), { recursive: true });
-	fs.writeFileSync(filePath, JSON.stringify(diagnostic), { mode: 0o600 });
-	return diagnostic;
-}
-
-export function readChildToolDiagnostic(filePath: string | undefined): ChildToolDiagnostic | undefined {
-	if (!filePath || !fs.existsSync(filePath)) return undefined;
-	const parsed = JSON.parse(fs.readFileSync(filePath, "utf-8")) as Partial<ChildToolDiagnostic>;
-	const stringArray = (value: unknown): value is string[] => Array.isArray(value) && value.every((entry) => typeof entry === "string" && entry.length > 0);
-	if (!stringArray(parsed.required) || !stringArray(parsed.available) || !stringArray(parsed.missing) || (parsed.agent !== undefined && typeof parsed.agent !== "string") || (parsed.missingMcpDirectTools !== undefined && !stringArray(parsed.missingMcpDirectTools))) {
-		throw new Error(`Malformed child tool diagnostic at '${filePath}'.`);
-	}
-	return {
-		...(parsed.agent ? { agent: parsed.agent } : {}),
-		required: parsed.required,
-		available: parsed.available,
-		missing: parsed.missing,
-		...(parsed.missingMcpDirectTools ? { missingMcpDirectTools: parsed.missingMcpDirectTools } : {}),
-	};
-}
-
-export function formatChildToolDiagnostic(diagnostic: ChildToolDiagnostic): string {
+/**
+ * Explain missing child tools. Foreground children run inside the parent
+ * process and never load the parent's ambient extensions, so tools an ambient
+ * extension registers (MCP tools, provider tools) only exist for background
+ * children; the diagnostic says so instead of reporting a generic gap.
+ */
+export function formatChildToolDiagnostic(diagnostic: ChildToolDiagnostic, options: { host?: "parent" | "runner" } = {}): string {
 	const subject = diagnostic.agent ? `Agent '${diagnostic.agent}'` : "Subagent";
+	if (options.host === "parent") {
+		return [
+			`${subject} ran as a foreground child, which never loads the parent's ambient extensions, and these child tools were unavailable: ${diagnostic.missing.join(", ")}.`,
+			"The `tools` field is a strict allowlist; it does not load extension code.",
+			...(diagnostic.missingMcpDirectTools?.length
+				? [`MCP direct tools missing from the child registry: ${diagnostic.missingMcpDirectTools.join(", ")}.`]
+				: []),
+			"Agents that need MCP tools (`mcpDirectTools`, or MCP tools from an ambient adapter such as pi-mcp-adapter) or models from a provider extension must run as background children (`async: true`), which load the ambient extensions.",
+			"For extension tools a foreground child can load, add the provider path to `subagentOnlyExtensions` (child-only), `extensions`, or as a path-like entry in `tools`, while keeping each registered tool name in `tools`.",
+		].join("\n");
+	}
 	return [
 		`${subject} requested unavailable child tools: ${diagnostic.missing.join(", ")}.`,
 		"The `tools` field is a strict allowlist; it does not load extension code.",
@@ -70,12 +35,3 @@ export function formatChildToolDiagnostic(diagnostic: ChildToolDiagnostic): stri
 		"For MCP tools, verify the MCP adapter configuration and selected tool names. For builtin tools, verify the name against the installed Pi version.",
 	].join("\n");
 }
-
-export function readChildToolDiagnosticError(filePath: string | undefined): string | undefined {
-	try {
-		const diagnostic = readChildToolDiagnostic(filePath);
-		return diagnostic ? formatChildToolDiagnostic(diagnostic) : undefined;
-	} catch (error) {
-		return `Failed to read child tool availability diagnostic: ${error instanceof Error ? error.message : String(error)}`;
-	}
-}

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

@@ -1,8 +1,6 @@
 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 const TOOL_BUDGET_ZERO_AUTH_ENV = "PI_SUBAGENT_TOOL_BUDGET_ZERO_AUTH";
 
 export function normalizeToolBudgetBlock(block: ToolBudgetConfig["block"] | undefined): "*" | string[] {
 	if (block === "*") return "*";
@@ -66,15 +64,3 @@ export function toolBudgetSoftNudge(budget: ResolvedToolBudget, toolCount: numbe
 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, options: { allowZero?: boolean } = {}): ResolvedToolBudget | undefined {
-	if (!value?.trim()) return undefined;
-	const parsed = JSON.parse(value) as unknown;
-	const normalized = validateToolBudgetConfig(parsed, TOOL_BUDGET_ENV, options.allowZero ? { minimumHard: 0 } : undefined);
-	if (normalized.error) throw new Error(normalized.error);
-	return normalized.budget;
-}

package/src/runs/shared/worktree-cleanup-plan.ts

@@ -13,6 +13,7 @@ import type {
 	ParallelHandoffGroup,
 	ParallelHandoffManifest,
 } from "../../shared/types.ts";
+import { getAgentDir } from "../../shared/utils.ts";
 import { isTerminalParallelHandoffChildStatus } from "./parallel-handoff.ts";
 
 export const WORKTREE_CLEANUP_PLAN_VERSION = 1 as const;
@@ -244,11 +245,24 @@ function resolveRepoRoot(repo: string): string {
 }
 
 function resolveCleanupBaseDir(repoRoot: string, configuredBaseDir: string | undefined): string {
-	const raw = configuredBaseDir ?? process.env.PI_SUBAGENTS_WORKTREE_DIR ?? os.tmpdir();
-	const trimmed = raw.trim();
-	if (!trimmed) throw new Error("worktree base directory cannot be empty");
-	const expanded = trimmed.startsWith("~/") ? path.join(os.homedir(), trimmed.slice(2)) : trimmed;
-	return path.resolve(path.isAbsolute(expanded) ? expanded : path.resolve(repoRoot, expanded));
+	const raw = configuredBaseDir ?? process.env.PI_SUBAGENTS_WORKTREE_DIR;
+	let dedicatedRoot: string;
+	if (raw === undefined || (configuredBaseDir === undefined && !raw.trim())) {
+		dedicatedRoot = path.join(path.dirname(repoRoot), "worktrees");
+	} else {
+		const trimmed = raw.trim();
+		if (!trimmed) throw new Error("worktree base directory cannot be empty");
+		const expanded = trimmed.startsWith("~/") ? path.join(os.homedir(), trimmed.slice(2)) : trimmed;
+		dedicatedRoot = path.isAbsolute(expanded) ? expanded : path.resolve(repoRoot, expanded);
+	}
+	return path.resolve(path.join(dedicatedRoot, path.basename(repoRoot)));
+}
+
+function cleanupContainmentInvalid(repoRoot: string, projectDir: string): boolean {
+	const extensionsDir = path.join(getAgentDir(), "extensions");
+	return samePath(projectDir, repoRoot)
+		|| pathInside(repoRoot, projectDir, true)
+		|| pathInside(extensionsDir, projectDir);
 }
 
 export function parseGitWorktreeList(raw: string): GitWorktreeRecord[] {
@@ -579,6 +593,7 @@ function isPatchCaptured(record: ManifestMetadataRecord, worktreePath: string):
 function buildManagedEntry(input: {
 	repoRoot: string;
 	baseDir: string;
+	containmentInvalid: boolean;
 	targetHead: string;
 	rootPath: string;
 	git: GitWorktreeRecord;
@@ -605,7 +620,9 @@ function buildManagedEntry(input: {
 	if (pathInspection.missing) return blockedEntry(entry, "stale", "unknown", "worktree path is missing from disk");
 	if (pathInspection.symlink) return blockedEntry(entry, "unknown", "unknown", "worktree path is a symlink; cleanup requires a real directory");
 	if (!pathInspection.directory || !pathInspection.realpath) return blockedEntry(entry, "unknown", "unknown", "worktree path is not a directory");
-	if (!pathInside(baseDir, pathInspection.realpath, true)) return blockedEntry(entry, "ineligible", "keep", `worktree real path is outside configured base directory '${baseDir}'`);
+	const extensionsDir = path.join(getAgentDir(), "extensions");
+	if (pathInside(extensionsDir, pathInspection.realpath)) return blockedEntry(entry, "ineligible", "keep", `worktree real path is inside Pi extensions directory '${extensionsDir}'`);
+	if (input.containmentInvalid || !pathInside(baseDir, pathInspection.realpath, true)) return blockedEntry(entry, "ineligible", "keep", `worktree real path is outside configured base directory '${baseDir}'`);
 
 	if (rootPath === comparablePath(pathInspection.realpath)) return blockedEntry(entry, "ineligible", "keep", "worktree is the repository root");
 	if (!git.branch) return blockedEntry(entry, "unknown", "unknown", "detached worktrees have no metadata-recorded branch");
@@ -725,6 +742,7 @@ export function buildWorktreeCleanupPlan(input: BuildWorktreeCleanupPlanInput):
 	const now = input.now ?? Date.now();
 	if (!Number.isFinite(now)) throw new Error("worktree cleanup plan timestamp must be finite");
 	const baseDir = resolveCleanupBaseDir(repoRoot, input.worktreeBaseDir);
+	const containmentInvalid = cleanupContainmentInvalid(repoRoot, baseDir);
 	const gitRecords = listGitWorktrees(repoRoot);
 	const targetHead = runGitChecked(repoRoot, ["rev-parse", "HEAD"]);
 	const rootPath = comparablePath(repoRoot);
@@ -749,6 +767,7 @@ export function buildWorktreeCleanupPlan(input: BuildWorktreeCleanupPlanInput):
 		else entries.push(buildManagedEntry({
 			repoRoot,
 			baseDir,
+			containmentInvalid,
 			targetHead,
 			rootPath,
 			git,

package/src/runs/shared/worktree.ts

@@ -9,6 +9,7 @@ import { getAgentDir } from "../../shared/utils.ts";
 import type { ManagedWorktreeProvider, WorktreeNaming, WorktreeProvider } from "../../shared/types.ts";
 
 export const DEFAULT_WORKTREE_PROVIDER: WorktreeProvider = "auto";
+export const DEFAULT_WORKTREE_BASE_REF = "HEAD";
 export const DEFAULT_WORKTREE_BRANCH_PREFIX = "pi-subagents/";
 /** Internal marker used to defer Worktrunk-dependent instruction paths to launch time. */
 export const WORKTREE_AGENT_CWD_PLACEHOLDER = path.join(path.parse(process.cwd()).root, "__pi_subagents_worktree_cwd__");
@@ -121,6 +122,8 @@ export interface CreateWorktreesOptions {
 	tasks?: Array<string | undefined>;
 	/** Worktree allocator selection; auto prefers Worktrunk when available. */
 	provider?: WorktreeProvider;
+	/** Git ref used as the worktree base; defaults to `HEAD`. */
+	baseRef?: string;
 	/** Branch namespace; defaults to `pi-subagents/`. */
 	branchPrefix?: string;
 	setupHook?: WorktreeSetupHookConfig;
@@ -159,6 +162,7 @@ interface GitResult {
 interface RepoState {
 	toplevel: string;
 	cwdRelative: string;
+	sourceCheckout: SourceCheckoutSnapshot;
 	baseCommit: string;
 }
 
@@ -193,7 +197,7 @@ function findGitWorktreePath(cwd: string, branch: string): string | undefined {
 	return undefined;
 }
 
-function resolveRepoState(cwd: string): RepoState {
+function resolveRepoState(cwd: string, requestedBaseRef: string | undefined): RepoState {
 	const cwdRelative = resolveRepoCwdRelative(cwd);
 	const toplevel = runGitChecked(cwd, ["rev-parse", "--show-toplevel"]).trim();
 
@@ -204,8 +208,17 @@ function resolveRepoState(cwd: string): RepoState {
 		throw new Error("worktree isolation requires a clean git working tree. Commit or stash changes first.");
 	}
 
-	const baseCommit = runGitChecked(toplevel, ["rev-parse", "HEAD"]).trim();
-	return { toplevel, cwdRelative, baseCommit };
+	const sourceHead = runGitChecked(toplevel, ["rev-parse", "HEAD"]).trim();
+	const sourceCheckout = snapshotSourceCheckout(toplevel, sourceHead);
+	const baseRef = normalizeWorktreeBaseRef(requestedBaseRef) ?? DEFAULT_WORKTREE_BASE_REF;
+	let baseCommit: string;
+	try {
+		baseCommit = runGitChecked(toplevel, ["rev-parse", "--verify", "--end-of-options", `${baseRef}^{commit}`]).trim();
+	} catch (error) {
+		throw new Error(`baseRef '${baseRef}' could not be resolved to a commit: ${error instanceof Error ? error.message : String(error)}`, { cause: error instanceof Error ? error : undefined });
+	}
+	if (!baseCommit) throw new Error(`baseRef '${baseRef}' could not be resolved to a commit`);
+	return { toplevel, cwdRelative, sourceCheckout, baseCommit };
 }
 
 function normalizeComparableCwd(cwd: string): string {
@@ -214,7 +227,13 @@ function normalizeComparableCwd(cwd: string): string {
 	const missingSegments: string[] = [];
 	while (true) {
 		try {
-			return path.join(fs.realpathSync(existing), ...missingSegments.reverse());
+			let realpath: string;
+			try {
+				realpath = fs.realpathSync.native(existing);
+			} catch {
+				realpath = fs.realpathSync(existing);
+			}
+			return path.join(realpath, ...missingSegments.reverse());
 		} catch {
 			const parent = path.dirname(existing);
 			if (parent === existing) return resolved;
@@ -279,11 +298,19 @@ export function sanitizeWorktreePathComponent(value: string, maxBytes = WORKTREE
 }
 
 function validGitRef(ref: string): boolean {
-	if (!ref || Buffer.byteLength(ref, "utf-8") > 1024 || ref.startsWith("/") || ref.endsWith("/") || ref.includes("//") || ref.includes("..") || ref.includes("@{")) return false;
-	if (/[[\]\\~^:?*\u0000-\u0020]/u.test(ref) || ref.endsWith(".") || ref.endsWith(".lock")) return false;
+	if (!ref || ref === "@" || Buffer.byteLength(ref, "utf-8") > 1024 || ref.startsWith("/") || ref.endsWith("/") || ref.includes("//") || ref.includes("..") || ref.includes("@{")) return false;
+	if (/^(?:[0-9a-f]{40}|[0-9a-f]{64})$/iu.test(ref)) return false;
+	if (/[[\]\\~^:?*\u0000-\u0020\u007f]/u.test(ref) || ref.endsWith(".") || ref.endsWith(".lock")) return false;
 	return ref.split("/").every((component) => component.length > 0 && component !== "." && component !== ".." && !component.startsWith(".") && !component.endsWith(".") && !component.endsWith(".lock"));
 }
 
+/** Normalize and validate a configured worktree base ref without resolving it. */
+export function normalizeWorktreeBaseRef(value: unknown): string | undefined {
+	if (value === undefined) return undefined;
+	if (typeof value !== "string" || !validGitRef(value)) throw new Error("baseRef must be a valid Git ref");
+	return value;
+}
+
 /** Normalize and validate the configured Git branch namespace. */
 export function normalizeWorktreeBranchPrefix(value: string | undefined): string {
 	const raw = value === undefined ? DEFAULT_WORKTREE_BRANCH_PREFIX : value.trim();
@@ -428,31 +455,85 @@ export function shouldDeferWorktreeCwd(requested: WorktreeProvider | undefined,
 	return (requested ?? DEFAULT_WORKTREE_PROVIDER) !== "native" && !hasConfiguredWorktreeBaseDir(baseDir);
 }
 
-function resolveWorktreeBaseDir(configuredBaseDir: string | undefined, repoRoot: string): string {
+/**
+ * Resolves the dedicated worktree root: the configured base directory or
+ * PI_SUBAGENTS_WORKTREE_DIR when set, otherwise a `worktrees` folder sibling
+ * to the repository. Managed leaves always nest one level deeper under the
+ * project folder (`basename(repoRoot)`).
+ */
+function resolveWorktreeDedicatedRoot(configuredBaseDir: string | undefined, repoRoot: string): string {
 	const rawBaseDir = configuredBaseDir ?? process.env.PI_SUBAGENTS_WORKTREE_DIR;
-	if (rawBaseDir === undefined || (configuredBaseDir === undefined && !rawBaseDir.trim())) return os.tmpdir();
-
-	const trimmed = rawBaseDir.trim();
-	if (!trimmed) throw new Error("worktree base directory cannot be empty");
+	let expanded: string;
+	if (rawBaseDir === undefined || (configuredBaseDir === undefined && !rawBaseDir.trim())) {
+		expanded = path.join(path.dirname(repoRoot), "worktrees");
+	} else {
+		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);
+		const candidate = trimmed.startsWith("~/") ? path.join(os.homedir(), trimmed.slice(2)) : trimmed;
+		expanded = path.isAbsolute(candidate) ? candidate : path.resolve(repoRoot, candidate);
+	}
 	const extensionsDir = normalizeComparableCwd(path.join(getAgentDir(), "extensions"));
-	const relativeToExtensions = path.relative(extensionsDir, normalizeComparableCwd(resolved));
-	if (!relativeToExtensions || (!relativeToExtensions.startsWith(`..${path.sep}`) && relativeToExtensions !== ".." && !path.isAbsolute(relativeToExtensions))) {
+	if (isPathInside(extensionsDir, normalizeComparableCwd(expanded))) {
 		throw new Error(`worktree base directory cannot be inside Pi extensions directory: ${extensionsDir}. Choose a directory outside it.`);
 	}
+	return expanded;
+}
+
+function buildNativeProjectPath(dedicatedRoot: string, repoRoot: string): string {
+	return path.join(dedicatedRoot, path.basename(repoRoot));
+}
+
+/**
+ * Creates the project folder (parents included) so `git worktree add` can create
+ * the leaf inside it. Must only run after `assertSafeWorktreeLocation` accepted
+ * the planned leaf — an unsafe base must never be materialized on disk.
+ */
+function ensureProjectWorktreeDir(dedicatedRoot: string, repoRoot: string): void {
 	try {
-		fs.mkdirSync(resolved, { recursive: true });
+		fs.mkdirSync(buildNativeProjectPath(dedicatedRoot, repoRoot), { recursive: true });
 	} catch (error) {
 		const message = error instanceof Error ? error.message : String(error);
-		throw new Error(`failed to create worktree base directory ${resolved}: ${message}`);
+		throw new Error(`failed to create worktree base directory ${dedicatedRoot}: ${message}`);
 	}
-	return resolved;
 }
 
-function buildNativeWorktreePath(baseDir: string, runId: string, index: number): string {
-	return path.join(baseDir, `pi-worktree-${sanitizeWorktreePathComponent(runId, 120)}-${index}`);
+function buildNativeWorktreePath(dedicatedRoot: string, repoRoot: string, runId: string, index: number): string {
+	return path.join(buildNativeProjectPath(dedicatedRoot, repoRoot), `pi-worktree-${sanitizeWorktreePathComponent(runId, 120)}-${index}`);
+}
+
+function isPathInside(parent: string, child: string): boolean {
+	const relative = path.relative(parent, child);
+	if (!relative || relative === ".") return true;
+	return relative !== ".." && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative);
+}
+
+function isStrictChildPath(parent: string, child: string): boolean {
+	const relative = path.relative(parent, child);
+	return Boolean(relative) && relative !== "." && relative !== ".." && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative);
+}
+
+/** Fail closed before `git worktree add`: reject unsafe planned/realpath locations. */
+function assertSafeWorktreeLocation(worktreePath: string, repoRoot: string, dedicatedRoot: string): void {
+	const resolvedLeaf = normalizeComparableCwd(worktreePath);
+	const resolvedRepoRoot = normalizeComparableCwd(repoRoot);
+	const projectDir = normalizeComparableCwd(buildNativeProjectPath(dedicatedRoot, repoRoot));
+	const repoParent = normalizeComparableCwd(path.dirname(resolvedRepoRoot));
+	const leafParent = normalizeComparableCwd(path.dirname(resolvedLeaf));
+	const extensionsDir = normalizeComparableCwd(path.join(getAgentDir(), "extensions"));
+
+	if (isPathInside(extensionsDir, projectDir) || isPathInside(extensionsDir, resolvedLeaf)) {
+		throw new Error(`worktree path cannot be inside Pi extensions directory: ${extensionsDir}. Choose a directory outside it.`);
+	}
+	if (isPathInside(resolvedRepoRoot, resolvedLeaf)) {
+		throw new Error(`worktree path would land inside the repository checkout: ${resolvedLeaf}`);
+	}
+	if (leafParent === repoParent) {
+		throw new Error(`worktree path would be a direct child of the repository parent: ${resolvedLeaf}`);
+	}
+	if (!isStrictChildPath(projectDir, resolvedLeaf)) {
+		throw new Error(`worktree path must be a strict child of the project worktree directory ${projectDir}: ${resolvedLeaf}`);
+	}
 }
 
 function resolveRepoCwdRelative(cwd: string): string {
@@ -470,7 +551,9 @@ function resolveRepoCwdRelative(cwd: string): string {
 export function resolveExpectedWorktreeAgentCwd(cwd: string, runId: string, index: number, baseDir?: string): string {
 	const cwdRelative = resolveRepoCwdRelative(cwd);
 	const repoRoot = runGitChecked(cwd, ["rev-parse", "--show-toplevel"]).trim();
-	const worktreePath = buildNativeWorktreePath(resolveWorktreeBaseDir(baseDir, repoRoot), runId, index);
+	const dedicatedRoot = resolveWorktreeDedicatedRoot(baseDir, repoRoot);
+	const worktreePath = buildNativeWorktreePath(dedicatedRoot, repoRoot, runId, index);
+	assertSafeWorktreeLocation(worktreePath, repoRoot, dedicatedRoot);
 	return cwdRelative ? path.join(worktreePath, cwdRelative) : worktreePath;
 }
 
@@ -660,13 +743,15 @@ function createNativeWorktree(
 	baseCommit: string,
 	setupHook: ResolvedWorktreeSetupHook | undefined,
 	agent: string | undefined,
-	baseDir: string,
+	dedicatedRoot: string,
 	labels: Array<string | undefined> | undefined,
 	tasks: Array<string | undefined> | undefined,
 	branchPrefix: string | undefined,
 ): WorktreeInfo {
 	const naming = buildWorktreeNaming({ runId, index, agent, label: labels?.[index], task: tasks?.[index], branchPrefix });
-	const worktreePath = buildNativeWorktreePath(baseDir, runId, index);
+	const worktreePath = buildNativeWorktreePath(dedicatedRoot, toplevel, runId, index);
+	assertSafeWorktreeLocation(worktreePath, toplevel, dedicatedRoot);
+	ensureProjectWorktreeDir(dedicatedRoot, toplevel);
 	const add = runGit(toplevel, ["worktree", "add", worktreePath, "-b", naming.requestedBranch, baseCommit]);
 	if (add.status !== 0) {
 		const message = add.stderr.trim() || add.stdout.trim() || `failed to create worktree ${worktreePath}`;
@@ -712,13 +797,13 @@ function createWorktrunkWorktree(
 	runId: string,
 	index: number,
 	baseCommit: string,
+	sourceCheckout: SourceCheckoutSnapshot,
 	agents: string[] | undefined,
 	labels: Array<string | undefined> | undefined,
 	tasks: Array<string | undefined> | undefined,
 	branchPrefix: string | undefined,
 ): WorktreeInfo {
 	const naming = buildWorktreeNaming({ runId, index, agent: agents?.[index], label: labels?.[index], task: tasks?.[index], branchPrefix });
-	const sourceCheckout = snapshotSourceCheckout(toplevel, baseCommit);
 	const args = ["-C", toplevel, "switch", "--create", naming.requestedBranch, "--base", baseCommit, "--no-cd", "--no-hooks", "--format", "json"];
 	const result = runWorktrunk(args, toplevel);
 	if (result.status !== 0) {
@@ -1045,11 +1130,11 @@ function hasWorktreeChanges(diff: WorktreeDiff): boolean {
 
 export function createWorktrees(cwd: string, runId: string, count: number, options?: CreateWorktreesOptions): WorktreeSetup {
 	if (!Number.isSafeInteger(count) || count < 0) throw new Error("worktree count must be a non-negative integer");
-	const repo = resolveRepoState(cwd);
+	const repo = resolveRepoState(cwd, options?.baseRef);
 	const setupHook = resolveWorktreeSetupHook(repo.toplevel, options?.setupHook);
-	let provider = resolveWorktreeProvider(options?.provider, options?.baseDir);
+	const provider = resolveWorktreeProvider(options?.provider, options?.baseDir);
 	const branchPrefix = normalizeWorktreeBranchPrefix(options?.branchPrefix);
-	let baseDir = provider === "native" ? resolveWorktreeBaseDir(options?.baseDir, repo.toplevel) : undefined;
+	const dedicatedRoot = provider === "native" ? resolveWorktreeDedicatedRoot(options?.baseDir, repo.toplevel) : undefined;
 	const worktrees: WorktreeInfo[] = [];
 
 	try {
@@ -1059,7 +1144,8 @@ export function createWorktrees(cwd: string, runId: string, count: number, optio
 				baseCommit: repo.baseCommit,
 				worktrees: Array.from({ length: count }, (_, index) => {
 					const naming = buildWorktreeNaming({ runId, index, agent: options?.agents?.[index], label: options?.labels?.[index], task: options?.tasks?.[index], branchPrefix });
-					const worktreePath = buildNativeWorktreePath(baseDir!, runId, index);
+					const worktreePath = buildNativeWorktreePath(dedicatedRoot!, repo.toplevel, runId, index);
+					assertSafeWorktreeLocation(worktreePath, repo.toplevel, dedicatedRoot!);
 					return {
 						path: worktreePath,
 						agentCwd: repo.cwdRelative ? path.join(worktreePath, repo.cwdRelative) : worktreePath,
@@ -1075,14 +1161,14 @@ export function createWorktrees(cwd: string, runId: string, count: number, optio
 			options?.beforeCreate?.(plannedSetup);
 			for (let index = 0; index < count; index++) {
 				worktrees.push(createNativeWorktree(
-						 repo.toplevel,
+					repo.toplevel,
 					repo.cwdRelative,
 					runId,
 					index,
 					repo.baseCommit,
 					setupHook,
 					options?.agents?.[index],
-					baseDir!,
+					dedicatedRoot!,
 					options?.labels,
 					options?.tasks,
 					branchPrefix,
@@ -1096,6 +1182,7 @@ export function createWorktrees(cwd: string, runId: string, count: number, optio
 					runId,
 					index,
 					repo.baseCommit,
+					repo.sourceCheckout,
 					options?.agents,
 					options?.labels,
 					options?.tasks,

package/src/shared/child-session-name.ts

@@ -6,7 +6,7 @@ import { PROMPT_REDACTED } from "./utils.ts";
  * the agent name and its task (or workflow node label). The parent computes it
  * once and threads it two ways:
  *
- *  1. Into the child process via `PI_SUBAGENT_SESSION_NAME`, where the prompt
+ *  1. Into the child's runtime config as `sessionName`, where the prompt
  *     runtime calls `pi.setSessionName(...)` so the child's own session file
  *     is identifiable in `pi --resume` and host session browsers.
  *  2. Into the `sessionName` field of result/progress payloads, so hosts

package/src/shared/jsonl-writer.ts

@@ -8,6 +8,7 @@ export interface DrainableSource {
 export interface JsonlWriteStream {
 	write(chunk: string): boolean;
 	once(event: "drain", listener: () => void): JsonlWriteStream;
+	on?(event: "error", listener: (error: Error) => void): JsonlWriteStream;
 	end(callback?: () => void): void;
 }
 
@@ -50,6 +51,16 @@ export function createJsonlWriter(
 	let closed = false;
 	let bytesWritten = 0;
 	const maxBytes = deps.maxBytes ?? DEFAULT_MAX_JSONL_BYTES;
+	// The mirror is best effort: a stream that cannot open or write (for example
+	// because its directory was removed) must not surface as an uncaught error.
+	stream.on?.("error", () => {
+		closed = true;
+		stream = undefined;
+		if (backpressured) {
+			backpressured = false;
+			source.resume();
+		}
+	});
 
 	return {
 		writeLine(line: string) {

package/src/shared/thinking-ceiling.ts

@@ -1,8 +1,6 @@
 import { resolveEffectiveThinking, THINKING_LEVELS, type ThinkingLevel } from "./model-info.ts";
 export type { ThinkingLevel } from "./model-info.ts";
 
-export const SUBAGENT_THINKING_CEILING_ENV = "PI_SUBAGENT_THINKING_CEILING";
-
 const thinkingLevelRanks = new Map<ThinkingLevel, number>(THINKING_LEVELS.map((level, index) => [level, index]));
 
 export function parseThinkingLevel(value: unknown, field = "thinking level"): ThinkingLevel {
@@ -26,10 +24,6 @@ export function intersectThinkingCeilings(...ceilings: Array<ThinkingLevel | und
 	return active.reduce((lowest, ceiling) => compareThinkingLevels(ceiling, lowest) < 0 ? ceiling : lowest);
 }
 
-export function decodeThinkingCeiling(value: string | undefined): ThinkingLevel | undefined {
-	if (value === undefined || value === "") return undefined;
-	return parseThinkingLevel(value, "inherited thinking ceiling");
-}
 
 export interface ThinkingCeilingCheck {
 	model?: string;