pi-subagents 0.64.0 → 0.65.1

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,7 +13,9 @@ import type {
 	ParallelHandoffGroup,
 	ParallelHandoffManifest,
 } from "../../shared/types.ts";
+import { getAgentDir } from "../../shared/utils.ts";
 import { isTerminalParallelHandoffChildStatus } from "./parallel-handoff.ts";
+import { MACHINE_DIFF_OPTIONS, validateWorktreePatchRepresentsCurrentWorktree } from "./worktree.ts";
 
 export const WORKTREE_CLEANUP_PLAN_VERSION = 1 as const;
 export const WORKTREE_CLEANUP_PLAN_TTL_MS = 30 * 60 * 1000;
@@ -244,11 +246,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[] {
@@ -558,7 +573,7 @@ function resolveBranchTip(repoRoot: string, branch: string): { value?: string; e
 	return { value: result.stdout.trim() };
 }
 
-function isPatchCaptured(record: ManifestMetadataRecord, worktreePath: string): { path?: string; error?: string } {
+function isPatchCaptured(record: ManifestMetadataRecord, worktreePath: string, baseCommit: string): { path?: string; error?: string } {
 	const patchPath = metadataPatchPath(record);
 	if (!patchPath || record.child.patch?.error !== undefined || record.child.patch?.changed !== true) return {};
 	const inspection = inspectPath(patchPath);
@@ -573,12 +588,15 @@ function isPatchCaptured(record: ManifestMetadataRecord, worktreePath: string):
 	if (!patchStat.isFile()) return { error: "captured handoff patch is not a file" };
 	if (pathInside(worktreePath, inspection.realpath)) return { error: "durable handoff patch lives inside the worktree" };
 	if (patchStat.size <= 0) return { error: "captured handoff patch is empty" };
+	const validationError = validateWorktreePatchRepresentsCurrentWorktree(worktreePath, baseCommit, patchPath);
+	if (validationError) return { error: `captured handoff patch failed validation: ${validationError}` };
 	return { path: patchPath };
 }
 
 function buildManagedEntry(input: {
 	repoRoot: string;
 	baseDir: string;
+	containmentInvalid: boolean;
 	targetHead: string;
 	rootPath: string;
 	git: GitWorktreeRecord;
@@ -605,7 +623,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");
@@ -648,14 +668,14 @@ function buildManagedEntry(input: {
 	entry.preconditions.statusDigest = status.digest;
 	if (status.output && status.output.trim()) return blockedEntry(entry, "dirty", "keep", "worktree has uncommitted or untracked changes");
 
-	const diff = runGit(worktreePath, ["diff", "--quiet", resolvedBase.value, "--"]);
+	const diff = runGit(worktreePath, ["diff", "--quiet", ...MACHINE_DIFF_OPTIONS, resolvedBase.value, "--"]);
 	if (diff.status !== 0 && diff.status !== 1) return blockedEntry(entry, "unknown", "unknown", `git diff safety check failed: ${gitFailure(diff, "git diff")}`);
 	const ancestor = runGit(repoRoot, ["merge-base", "--is-ancestor", git.head, targetHead]);
 	if (ancestor.status !== 0 && ancestor.status !== 1) return blockedEntry(entry, "unknown", "unknown", `local merge safety check failed: ${gitFailure(ancestor, "git merge-base --is-ancestor")}`);
 	const branchTipIsAncestor = ancestor.status === 0;
 	let divergenceSafe = diff.status === 0;
 	if (!divergenceSafe) {
-		const captured = isPatchCaptured(record, worktreePath);
+		const captured = isPatchCaptured(record, worktreePath, resolvedBase.value);
 		if (captured.error) return blockedEntry(entry, "ineligible", "keep", captured.error);
 		if (captured.path) {
 			entry.patchPath = captured.path;
@@ -725,6 +745,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 +770,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__");
@@ -16,6 +17,9 @@ const WORKTREE_NAMING_COMPONENT_MAX_BYTES = 96;
 const WORKTREE_NAMING_LABEL_MAX_BYTES = 256;
 const WORKTREE_NAMING_BRANCH_MAX_BYTES = 256;
 const WORKTREE_COMMAND_OUTPUT_MAX_BYTES = 128 * 1024;
+export const MACHINE_DIFF_OPTIONS = ["--no-color", "--no-ext-diff", "--no-textconv", "--default-prefix", "--line-prefix=", "--no-relative"] as const;
+const MACHINE_PATCH_OPTIONS = [...MACHINE_DIFF_OPTIONS, "--binary"] as const;
+const PATCH_VALIDATION_OPTIONS = ["apply", "--check", "--cached", "--reverse", "--binary", "--whitespace=nowarn"] as const;
 
 export interface WorktreeNamingInput {
 	runId: string;
@@ -121,6 +125,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,13 +165,14 @@ interface GitResult {
 interface RepoState {
 	toplevel: string;
 	cwdRelative: string;
+	sourceCheckout: SourceCheckoutSnapshot;
 	baseCommit: string;
 }
 
 const DEFAULT_WORKTREE_SETUP_HOOK_TIMEOUT_MS = 30000;
 
-function runGit(cwd: string, args: string[]): GitResult {
-	const result = spawnSync("git", ["-C", cwd, ...args], { encoding: "utf-8", windowsHide: true, shell: false });
+function runGit(cwd: string, args: string[], env?: NodeJS.ProcessEnv): GitResult {
+	const result = spawnSync("git", ["-C", cwd, ...args], { encoding: "utf-8", windowsHide: true, shell: false, ...(env ? { env: { ...process.env, ...env } } : {}) });
 	return {
 		stdout: result.stdout ?? "",
 		stderr: result.stderr ?? "",
@@ -183,6 +190,53 @@ function runGitChecked(cwd: string, args: string[]): string {
 	return result.stdout;
 }
 
+/** Validate a captured patch against the worktree index without changing either. */
+export function validateWorktreePatch(worktreePath: string, patchPath: string): string | undefined {
+	const result = runGit(worktreePath, [...PATCH_VALIDATION_OPTIONS, patchPath]);
+	if (result.status === 0) return undefined;
+	return result.stderr.trim() || result.stdout.trim() || `git -C ${worktreePath} apply --check failed`;
+}
+
+function currentWorktreePatch(worktreePath: string, baseCommit: string): { patch: string } | { error: string } {
+	let tempDir: string;
+	try {
+		tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-worktree-index-"));
+	} catch (error) {
+		return { error: error instanceof Error ? error.message : String(error) };
+	}
+	const env = { GIT_INDEX_FILE: path.join(tempDir, "index") };
+	try {
+		const readTree = runGit(worktreePath, ["read-tree", "HEAD"], env);
+		if (readTree.status !== 0) return { error: readTree.stderr.trim() || readTree.stdout.trim() || "git read-tree failed" };
+		const add = runGit(worktreePath, ["add", "-A"], env);
+		if (add.status !== 0) return { error: add.stderr.trim() || add.stdout.trim() || "git add failed" };
+		const diff = runGit(worktreePath, ["diff", "--cached", ...MACHINE_PATCH_OPTIONS, baseCommit], env);
+		if (diff.status !== 0) return { error: diff.stderr.trim() || diff.stdout.trim() || "git diff failed" };
+		return { patch: diff.stdout };
+	} finally {
+		try {
+			fs.rmSync(tempDir, { recursive: true, force: true });
+		} catch {
+			// Cleanup safety depends on preserving the worktree, not on best-effort temp-index deletion.
+		}
+	}
+}
+
+export function validateWorktreePatchRepresentsCurrentWorktree(worktreePath: string, baseCommit: string, patchPath: string): string | undefined {
+	const validationError = validateWorktreePatch(worktreePath, patchPath);
+	if (validationError) return validationError;
+	let capturedPatch: string;
+	try {
+		capturedPatch = fs.readFileSync(patchPath, "utf-8");
+	} catch (error) {
+		return error instanceof Error ? error.message : String(error);
+	}
+	const current = currentWorktreePatch(worktreePath, baseCommit);
+	if ("error" in current) return current.error || "failed to capture current worktree patch";
+	if (capturedPatch !== current.patch) return "captured handoff patch does not match current worktree changes";
+	return undefined;
+}
+
 function findGitWorktreePath(cwd: string, branch: string): string | undefined {
 	const targetBranch = `branch refs/heads/${branch}`;
 	let currentPath: string | undefined;
@@ -193,7 +247,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 +258,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 +277,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 +348,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 +505,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 +601,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 +793,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 +847,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) {
@@ -872,15 +1007,18 @@ function captureWorktreeDiff(
 ): WorktreeDiff {
 	removeSyntheticPathsBeforeDiff(worktree);
 	runGitChecked(worktree.path, ["add", "-A"]);
-	const diffStat = runGitChecked(worktree.path, ["diff", "--cached", "--stat", setup.baseCommit]).trim();
-	const patch = runGitChecked(worktree.path, ["diff", "--cached", setup.baseCommit]);
-	const numstat = runGitChecked(worktree.path, ["diff", "--cached", "--numstat", setup.baseCommit]);
+	const diffStat = runGitChecked(worktree.path, ["diff", "--cached", ...MACHINE_DIFF_OPTIONS, "--stat", setup.baseCommit]).trim();
+	const patch = runGitChecked(worktree.path, ["diff", "--cached", ...MACHINE_PATCH_OPTIONS, setup.baseCommit]);
+	const numstat = runGitChecked(worktree.path, ["diff", "--cached", ...MACHINE_DIFF_OPTIONS, "--numstat", setup.baseCommit]);
 	fs.writeFileSync(patchPath, patch, "utf-8");
 
 	if (!patch.trim()) {
 		return emptyDiff(worktree.index, agent, worktree.branch, patchPath);
 	}
 
+	const validationError = validateWorktreePatch(worktree.path, patchPath);
+	if (validationError) throw new Error(`captured worktree patch is not machine-applyable: ${validationError}`);
+
 	const parsed = parseNumstat(numstat);
 	return {
 		index: worktree.index,
@@ -949,7 +1087,7 @@ function cleanupSingleWorktree(
 			errors.push(`synthetic path cleanup failed: ${error instanceof Error ? error.message : String(error)}`);
 		}
 		const status = runGit(worktree.path, ["status", "--porcelain"]);
-		const baseDiff = runGit(worktree.path, ["diff", "--quiet", setup.baseCommit, "--"]);
+		const baseDiff = runGit(worktree.path, ["diff", "--quiet", ...MACHINE_DIFF_OPTIONS, setup.baseCommit, "--"]);
 		if (status.status !== 0 || (baseDiff.status !== 0 && baseDiff.status !== 1)) {
 			const reason = status.status !== 0
 				? status.stderr.trim() || status.stdout.trim() || "git status failed"
@@ -970,13 +1108,25 @@ function cleanupSingleWorktree(
 		const hasWork = status.stdout.trim().length > 0 || baseDiff.status === 1;
 		if (hasWork && intent.kind === "preserve") {
 			const captured = (intent.capturedDiffs ?? setup.capturedDiffs)?.find((diff) => diff.index === worktree.index);
-			const patchCaptured = captured !== undefined
+			let patchValidationError: string | undefined;
+			let patchCaptured = false;
+			if (captured !== undefined
 				&& captured.error === undefined
 				&& fs.existsSync(captured.patchPath)
-				&& fs.statSync(captured.patchPath).size > 0
-				&& handoffRecordsPatch(intent.handoffManifestPath, captured.patchPath);
+				&& handoffRecordsPatch(intent.handoffManifestPath, captured.patchPath)) {
+				try {
+					if (fs.statSync(captured.patchPath).size > 0) {
+						patchValidationError = validateWorktreePatchRepresentsCurrentWorktree(worktree.path, setup.baseCommit, captured.patchPath);
+						patchCaptured = patchValidationError === undefined;
+					}
+				} catch (error) {
+					patchValidationError = error instanceof Error ? error.message : String(error);
+				}
+			}
 			if (!patchCaptured) {
-				const reason = "worktree contains changes that are not represented by a captured handoff patch";
+				const reason = patchValidationError
+					? `captured handoff patch failed validation: ${patchValidationError}`
+					: "worktree contains changes that are not represented by a captured handoff patch";
 				return {
 					index: worktree.index,
 					path: worktree.path,
@@ -1045,11 +1195,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 +1209,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 +1226,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 +1247,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