@fitchmultz/pi-subagents 0.44.6 → 0.45.0

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

@@ -2,349 +2,279 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 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 {
+  childRouteEnv,
+  SUBAGENT_EAGER_TOOL_ENV,
+  SUBAGENT_INHERITED_EXTENSIONS_JSON_ENV,
+} from "./child-route-env.ts";
+export * from "./child-route-env.ts";
+import type { BuildPiArgsInput, BuildPiArgsResult } from "./pi-launch-input.ts";
+import { isUnknownArray, isRecord as isObject } from "../../shared/unknown.ts";
+import { nonempty } from "./child-presence.ts";
 import { splitKnownThinkingSuffix } from "../../shared/model-info.ts";
-import { prepareChildExecutionCwd } from "./child-execution-cwd.ts";
-import type { ChildProjectTrustPolicy, JsonSchemaObject } from "../../shared/types.ts";
+import { piSessionLaunch } from "./pi-session-launch.ts";
+import type { ChildProjectTrustPolicy, ReadonlyInput } from "../../shared/types.ts";
 import { loadConfig } from "../../extension/config.ts";
 // Managed macOS environments can SIGKILL Node when one argv entry reaches ~930 UTF-8 bytes.
 // Measure the full entry (including the `Task: ` prefix), not just the task body.
 const TASK_ARG_LIMIT_BYTES = 900;
 // Resolve sibling extensions in both layouts: TypeScript sources (tests, jiti) and compiled dist output.
 const MODULE_EXTENSION = import.meta.url.endsWith(".ts") ? ".ts" : ".js";
-const SESSION_CWD_PRELOAD_URL = new URL(`session-cwd-preload${MODULE_EXTENSION}`, import.meta.url).href;
-const PROMPT_RUNTIME_EXTENSION_PATH = path.join(path.dirname(fileURLToPath(import.meta.url)), `subagent-prompt-runtime${MODULE_EXTENSION}`);
-const FANOUT_CHILD_EXTENSION_PATH = path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "..", "extension", `fanout-child${MODULE_EXTENSION}`);
-export const SUBAGENT_CHILD_ENV = "PI_SUBAGENT_CHILD";
-export const SUBAGENT_ORCHESTRATOR_TARGET_ENV = "PI_SUBAGENT_ORCHESTRATOR_TARGET";
-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";
-export const SUBAGENT_FANOUT_CHILD_ENV = "PI_SUBAGENT_FANOUT_CHILD";
-export const SUBAGENT_EAGER_TOOL_ENV = "PI_SUBAGENT_EAGER_TOOL";
-export const SUBAGENT_PARENT_EVENT_SINK_ENV = "PI_SUBAGENT_PARENT_EVENT_SINK";
-export const SUBAGENT_PARENT_CONTROL_INBOX_ENV = "PI_SUBAGENT_PARENT_CONTROL_INBOX";
-export const SUBAGENT_PARENT_ROOT_RUN_ID_ENV = "PI_SUBAGENT_PARENT_ROOT_RUN_ID";
-export const SUBAGENT_PARENT_RUN_ID_ENV = "PI_SUBAGENT_PARENT_RUN_ID";
-export const SUBAGENT_PARENT_CHILD_INDEX_ENV = "PI_SUBAGENT_PARENT_CHILD_INDEX";
-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_INHERITED_EXTENSIONS_JSON_ENV = "PI_SUBAGENT_INHERITED_EXTENSIONS_JSON";
+const PROMPT_RUNTIME_EXTENSION_PATH = path.join(
+  path.dirname(fileURLToPath(import.meta.url)),
+  `subagent-prompt-runtime${MODULE_EXTENSION}`,
+);
+const FANOUT_CHILD_EXTENSION_PATH = path.join(
+  path.dirname(fileURLToPath(import.meta.url)),
+  "..",
+  "..",
+  "extension",
+  `fanout-child${MODULE_EXTENSION}`,
+);
 
-interface BuildPiArgsInput {
-	baseArgs: string[];
-	task: string;
-	sessionEnabled: boolean;
-	sessionDir?: string;
-	sessionFile?: string;
-	model?: string;
-	thinking?: string;
-	systemPromptMode?: "append" | "replace";
-	inheritProjectContext: boolean;
-	inheritSkills: boolean;
-	tools?: string[];
-	allowSubagents?: boolean;
-	extensions?: string[];
-	systemPrompt?: string | null;
-	mcpDirectTools?: string[];
-	/** Actual child spawn cwd; a new --session file inherits this directory natively. */
-	cwd?: string;
-	intercomSessionName?: string;
-	orchestratorIntercomTarget?: string;
-	rootSessionId?: string;
-	runId?: string;
-	childAgentName?: string;
-	childIndex?: number;
-	parentEventSink?: string;
-	parentControlInbox?: string;
-	parentRootRunId?: string;
-	parentRunId?: string;
-	parentChildIndex?: number;
-	parentDepth?: number;
-	parentPath?: NestedPathEntry[];
-	parentCapabilityToken?: string;
-	structuredOutput?: {
-		schema: JsonSchemaObject;
-		schemaPath: string;
-		outputPath: string;
-	};
-	projectTrust?: ChildProjectTrustPolicy;
-}
-
-interface BuildPiArgsResult {
-	args: string[];
-	env: Record<string, string | undefined>;
-	tempDir?: string;
-}
-
-export function applyThinkingSuffix(model: string | undefined, thinking: string | undefined): string | undefined {
-	if (!model || !thinking) return model;
-	if (splitKnownThinkingSuffix(model).thinkingSuffix) return model;
-	return `${model}:${thinking}`;
+export function applyThinkingSuffix(
+  model: string | undefined,
+  thinking: string | undefined,
+): string | undefined {
+  if (!nonempty(model) || !nonempty(thinking)) {
+    return model;
+  }
+  if (nonempty(splitKnownThinkingSuffix(model).thinkingSuffix)) {
+    return model;
+  }
+  return `${model}:${thinking}`;
 }
 
 export function normalizeChildProjectTrustPolicy(input: unknown): ChildProjectTrustPolicy {
-	if (input === "approve" || input === "no-approve" || input === "inherit") return input;
-	if (typeof input === "object" && input !== null && "childRuns" in input) {
-		return normalizeChildProjectTrustPolicy((input as { childRuns?: unknown }).childRuns);
-	}
-	return input === undefined ? "inherit" : "no-approve";
+  if (input === "approve" || input === "no-approve" || input === "inherit") {
+    return input;
+  }
+  if (isObject(input) && "childRuns" in input) {
+    return normalizeChildProjectTrustPolicy(input.childRuns);
+  }
+  return input === undefined ? "inherit" : "no-approve";
 }
 
-export function resolveConfiguredChildProjectTrustPolicy(input: unknown, argv: string[] = process.argv): ChildProjectTrustPolicy {
-	const inherited = findInheritedProjectTrustFlag(argv);
-	const explicitInherit = input === "inherit" || (typeof input === "object" && input !== null && (input as { childRuns?: unknown }).childRuns === "inherit");
-	if (explicitInherit) return inherited ?? "inherit";
-	if (inherited === "no-approve") return "no-approve";
-	if (input === undefined || (typeof input === "object" && input !== null && !("childRuns" in input))) return "approve";
-	const normalized = normalizeChildProjectTrustPolicy(input);
-	return normalized === "inherit" ? "approve" : normalized;
+export function resolveConfiguredChildProjectTrustPolicy(
+  input: unknown,
+  argv: readonly string[] = process.argv,
+): ChildProjectTrustPolicy {
+  const inherited = findInheritedProjectTrustFlag(argv);
+  const configured = isObject(input) ? input.childRuns : input;
+  const explicitInherit = configured === "inherit";
+  if (explicitInherit) {
+    return inherited ?? "inherit";
+  }
+  if (inherited === "no-approve") {
+    return "no-approve";
+  }
+  if (input === undefined || (isObject(input) && !("childRuns" in input))) {
+    return "approve";
+  }
+  const normalized = normalizeChildProjectTrustPolicy(input);
+  return normalized === "inherit" ? "approve" : normalized;
 }
 
-function findInheritedProjectTrustFlag(argv: string[]): "approve" | "no-approve" | undefined {
-	let inherited: "approve" | "no-approve" | undefined;
-	for (const arg of argv) {
-		if (arg === "--approve" || arg === "-a") inherited = "approve";
-		if (arg === "--no-approve" || arg === "-na") inherited = "no-approve";
-	}
-	return inherited;
+function findInheritedProjectTrustFlag(
+  argv: readonly string[],
+): "approve" | "no-approve" | undefined {
+  let inherited: "approve" | "no-approve" | undefined;
+  for (const arg of argv) {
+    if (arg === "--approve" || arg === "-a") {
+      inherited = "approve";
+    }
+    if (arg === "--no-approve" || arg === "-na") {
+      inherited = "no-approve";
+    }
+  }
+  return inherited;
 }
 
-export function resolveChildProjectTrustArgs(policy: ChildProjectTrustPolicy = "inherit", argv: string[] = process.argv): string[] {
-	const inherited = findInheritedProjectTrustFlag(argv);
-	if (policy === "approve") return inherited === "no-approve" ? ["--no-approve"] : ["--approve"];
-	if (policy === "no-approve") return ["--no-approve"];
+export function resolveChildProjectTrustArgs(
+  policy: ChildProjectTrustPolicy = "inherit",
+  argv: readonly string[] = process.argv,
+): string[] {
+  const inherited = findInheritedProjectTrustFlag(argv);
+  if (policy === "approve") {
+    return inherited === "no-approve" ? ["--no-approve"] : ["--approve"];
+  }
+  if (policy === "no-approve") {
+    return ["--no-approve"];
+  }
 
-	return inherited === "approve" ? ["--approve"] : inherited === "no-approve" ? ["--no-approve"] : [];
+  if (inherited === undefined) {
+    return [];
+  }
+  return [`--${inherited}`];
 }
 
-function inheritedRuntimeExtensionPaths(env: NodeJS.ProcessEnv = process.env): string[] {
-	const raw = env[SUBAGENT_INHERITED_EXTENSIONS_JSON_ENV]?.trim();
-	if (!raw) return [];
-	try {
-		const parsed = JSON.parse(raw) as unknown;
-		if (!Array.isArray(parsed)) return [];
-		return parsed.filter((entry): entry is string => typeof entry === "string" && entry.trim().length > 0);
-	} catch {
-		return [];
-	}
+function inheritedRuntimeExtensionPaths(env: Readonly<NodeJS.ProcessEnv> = process.env): string[] {
+  const raw = env[SUBAGENT_INHERITED_EXTENSIONS_JSON_ENV]?.trim();
+  if (!nonempty(raw)) {
+    return [];
+  }
+  try {
+    const parsed: unknown = JSON.parse(raw);
+    if (!isUnknownArray(parsed)) {
+      return [];
+    }
+    return parsed.filter(
+      (entry): entry is string => typeof entry === "string" && entry.trim().length > 0,
+    );
+  } catch {
+    return [];
+  }
 }
 
-// Read only through the header, not the potentially large transcript. Decode after
-// joining chunks so a UTF-8 character split across reads is preserved.
-function readSessionHeaderLine(file: string): string | undefined {
-	let fd: number;
-	try {
-		fd = fs.openSync(file, "r");
-	} catch (error) {
-		if ((error as NodeJS.ErrnoException).code === "ENOENT" && !fs.lstatSync(file, { throwIfNoEntry: false })) return undefined;
-		throw error;
-	}
-	try {
-		const chunks: Buffer[] = [];
-		const buffer = Buffer.alloc(4096);
-		while (true) {
-			const length = fs.readSync(fd, buffer, 0, buffer.length, null);
-			if (!length) break;
-			const chunk = buffer.subarray(0, length);
-			const newline = chunk.indexOf(10);
-			chunks.push(Buffer.from(newline < 0 ? chunk : chunk.subarray(0, newline)));
-			if (newline >= 0) break;
-		}
-		return Buffer.concat(chunks).toString("utf8");
-	} finally {
-		fs.closeSync(fd);
-	}
+function isExtensionTool(tool: string): boolean {
+  return tool.includes("/") || tool.endsWith(".ts") || tool.endsWith(".js");
+}
+function builtinLoadout(
+  input: ReadonlyInput<BuildPiArgsInput>,
+  declared: readonly string[],
+  fanoutAuthorized: boolean,
+  compact: boolean,
+): string[] {
+  const builtin = [...declared];
+  if (builtin.length === 0) {
+    return builtin;
+  }
+  if (fanoutAuthorized) {
+    const additions = compact
+      ? ["subagent", "delegate", "agent_runs", "load_subagent"]
+      : ["subagent"];
+    builtin.push(...additions.filter((tool) => !builtin.includes(tool)));
+  }
+  if (input.structuredOutput && !builtin.includes("structured_output")) {
+    builtin.push("structured_output");
+  }
+  if (input.mcpDirectTools !== undefined && input.mcpDirectTools.length > 0) {
+    builtin.push(...resolveMcpDirectToolNames(input.mcpDirectTools, input.cwd));
+  }
+  return builtin;
+}
+function buildToolLoadout(input: ReadonlyInput<BuildPiArgsInput>): {
+  args: string[];
+  toolExtensionPaths: string[];
+  fanoutAuthorized: boolean;
+  eager: boolean;
+} {
+  const declared = input.tools?.filter((tool) => !isExtensionTool(tool)) ?? [];
+  const fanoutAuthorized = input.allowSubagents === true || declared.includes("subagent");
+  const compact = fanoutAuthorized && loadConfig().compactChildTools !== false;
+  const tools = builtinLoadout(input, declared, fanoutAuthorized, compact);
+  return {
+    args: tools.length > 0 ? ["--tools", tools.join(",")] : [],
+    toolExtensionPaths: input.tools?.filter(isExtensionTool) ?? [],
+    fanoutAuthorized,
+    // Preserve explicit advanced tools, never inherit them into another profile.
+    eager: declared.includes("subagent"),
+  };
 }
 
-export function buildPiArgs(input: BuildPiArgsInput): BuildPiArgsResult {
-	const args = [...input.baseArgs];
-	const env: Record<string, string | undefined> = {};
-	args.push(...resolveChildProjectTrustArgs(input.projectTrust));
-
-	if (input.sessionFile) {
-		prepareChildExecutionCwd(input.sessionFile, input.cwd);
-		fs.mkdirSync(path.dirname(input.sessionFile), { recursive: true });
-		args.push("--session", input.sessionFile);
-		if (input.cwd) {
-			let needsOverride = true;
-			try {
-				const line = readSessionHeaderLine(input.sessionFile);
-				if (line === undefined) {
-					// Preassigned new sessions (including acceptance) inherit the actual spawn cwd.
-					needsOverride = false;
-				} else {
-					const header: unknown = JSON.parse(line);
-					if (header && typeof header === "object" && "type" in header && header.type === "session"
-						&& "cwd" in header && typeof header.cwd === "string" && path.isAbsolute(header.cwd)) {
-						needsOverride = fs.realpathSync.native(header.cwd) !== fs.realpathSync.native(input.cwd);
-					}
-				}
-			} catch { /* Unknown headers or unavailable directories still need the native override. */ }
-			// Pi's SDK supports cwdOverride; its CLI has no --session-cwd flag.
-			// Keep normal resumes untouched and supply only a needed override before startup.
-			if (needsOverride) {
-				env.PI_SUBAGENT_SESSION_CWD = JSON.stringify({
-					sessionFile: path.resolve(input.cwd, input.sessionFile), cwd: input.cwd, nodeOptions: process.env.NODE_OPTIONS,
-				});
-				env.NODE_OPTIONS = `${process.env.NODE_OPTIONS ?? ""} --import=${SESSION_CWD_PRELOAD_URL}`.trim();
-			}
-		}
-	} else {
-		if (!input.sessionEnabled) {
-			args.push("--no-session");
-		}
-		if (input.sessionDir) {
-			fs.mkdirSync(input.sessionDir, { recursive: true });
-			args.push("--session-dir", input.sessionDir);
-		}
-	}
-
-	const modelArg = applyThinkingSuffix(input.model, input.thinking);
-	if (modelArg) {
-		args.push("--model", modelArg);
-	}
-
-	const declaredBuiltinTools = input.tools?.filter((tool) => !(tool.includes("/") || tool.endsWith(".ts") || tool.endsWith(".js"))) ?? [];
-	const fanoutAuthorized = input.allowSubagents === true || declaredBuiltinTools.includes("subagent");
-	const compactChildTools = fanoutAuthorized && loadConfig().compactChildTools !== false;
-	// Preserve an explicit advanced-tool policy, but never inherit it into another profile.
-	env[SUBAGENT_EAGER_TOOL_ENV] = declaredBuiltinTools.includes("subagent") ? "1" : undefined;
-	const toolExtensionPaths: string[] = [];
-	if (input.tools?.length) {
-		const builtinTools = [...declaredBuiltinTools];
-		if (fanoutAuthorized && declaredBuiltinTools.length > 0) {
-			for (const tool of compactChildTools ? ["subagent", "delegate", "agent_runs", "load_subagent"] : ["subagent"]) {
-				if (!builtinTools.includes(tool)) builtinTools.push(tool);
-			}
-		}
-		if (input.structuredOutput && builtinTools.length > 0 && !builtinTools.includes("structured_output")) builtinTools.push("structured_output");
-		for (const tool of input.tools) {
-			if (!declaredBuiltinTools.includes(tool) && (tool.includes("/") || tool.endsWith(".ts") || tool.endsWith(".js"))) {
-				toolExtensionPaths.push(tool);
-			}
-		}
-		if (builtinTools.length > 0) {
-			if (input.mcpDirectTools?.length) {
-				builtinTools.push(...resolveMcpDirectToolNames(input.mcpDirectTools, input.cwd));
-			}
-			args.push("--tools", builtinTools.join(","));
-		}
-	}
-
-	const runtimeExtensions = fanoutAuthorized
-		? [PROMPT_RUNTIME_EXTENSION_PATH, FANOUT_CHILD_EXTENSION_PATH, ...inheritedRuntimeExtensionPaths()]
-		: [PROMPT_RUNTIME_EXTENSION_PATH, ...inheritedRuntimeExtensionPaths()];
-	if (input.extensions !== undefined) {
-		args.push("--no-extensions");
-		for (const extPath of [...new Set([...runtimeExtensions, ...toolExtensionPaths, ...input.extensions])]) {
-			args.push("--extension", extPath);
-		}
-	} else {
-		for (const extPath of [...new Set([...runtimeExtensions, ...toolExtensionPaths])]) {
-			args.push("--extension", extPath);
-		}
-	}
+function buildExtensionArgs(
+  input: ReadonlyInput<BuildPiArgsInput>,
+  fanoutAuthorized: boolean,
+  toolExtensionPaths: readonly string[],
+): string[] {
+  const args: string[] = [];
+  const runtimeExtensions = fanoutAuthorized
+    ? [
+        PROMPT_RUNTIME_EXTENSION_PATH,
+        FANOUT_CHILD_EXTENSION_PATH,
+        ...inheritedRuntimeExtensionPaths(),
+      ]
+    : [PROMPT_RUNTIME_EXTENSION_PATH, ...inheritedRuntimeExtensionPaths()];
+  if (input.extensions !== undefined) {
+    args.push("--no-extensions");
+    for (const extPath of new Set([
+      ...runtimeExtensions,
+      ...toolExtensionPaths,
+      ...input.extensions,
+    ])) {
+      args.push("--extension", extPath);
+    }
+  } else {
+    for (const extPath of new Set([...runtimeExtensions, ...toolExtensionPaths])) {
+      args.push("--extension", extPath);
+    }
+  }
 
-	if (!input.inheritSkills) {
-		args.push("--no-skills");
-	}
-	if (!input.inheritProjectContext) {
-		args.push("--no-context-files");
-	}
+  return args;
+}
 
-	let tempDir: string | undefined;
-	if (input.systemPrompt !== undefined && input.systemPrompt !== null) {
-		tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-subagent-"));
-		const promptPath = path.join(tempDir, "system.md");
-		fs.writeFileSync(promptPath, input.systemPrompt, { mode: 0o600 });
-		args.push(input.systemPromptMode === "replace" ? "--system-prompt" : "--append-system-prompt", promptPath);
-	}
+function buildPromptArgs(input: ReadonlyInput<BuildPiArgsInput>): {
+  args: string[];
+  tempDir?: string;
+} {
+  const args: string[] = [];
+  if (!input.inheritSkills) {
+    args.push("--no-skills");
+  }
+  if (!input.inheritProjectContext) {
+    args.push("--no-context-files");
+  }
 
-	const taskArg = `Task: ${input.task}`;
-	if (Buffer.byteLength(taskArg) > TASK_ARG_LIMIT_BYTES) {
-		if (!tempDir) {
-			tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-subagent-"));
-		}
-		const taskFilePath = path.join(tempDir, "task.md");
-		fs.writeFileSync(taskFilePath, taskArg, { mode: 0o600 });
-		args.push(`@${taskFilePath}`);
-	} else {
-		args.push(taskArg);
-	}
+  let tempDir: string | undefined;
+  if (input.systemPrompt !== undefined && input.systemPrompt !== null) {
+    tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-subagent-"));
+    const promptPath = path.join(tempDir, "system.md");
+    fs.writeFileSync(promptPath, input.systemPrompt, { mode: 0o600 });
+    args.push(
+      input.systemPromptMode === "replace" ? "--system-prompt" : "--append-system-prompt",
+      promptPath,
+    );
+  }
 
-	env[SUBAGENT_CHILD_ENV] = "1";
-	env.PI_SUBAGENT_ROOT_SESSION_ID = input.rootSessionId ?? (process.env[SUBAGENT_CHILD_ENV] === "1" ? process.env.PI_SUBAGENT_ROOT_SESSION_ID : undefined);
-	env[SUBAGENT_FANOUT_CHILD_ENV] = fanoutAuthorized ? "1" : "0";
-	const inheritedNestedRoute = Boolean(process.env[SUBAGENT_PARENT_EVENT_SINK_ENV] && process.env[SUBAGENT_PARENT_ROOT_RUN_ID_ENV] && process.env[SUBAGENT_PARENT_CAPABILITY_TOKEN_ENV]);
-	const parentRunId = input.parentRunId ?? input.runId ?? (inheritedNestedRoute ? process.env[SUBAGENT_RUN_ID_ENV] : undefined) ?? process.env[SUBAGENT_PARENT_RUN_ID_ENV] ?? "";
-	const parentChildIndex = input.parentChildIndex !== undefined
-		? String(input.parentChildIndex)
-		: input.childIndex !== undefined
-			? String(input.childIndex)
-			: process.env[SUBAGENT_PARENT_CHILD_INDEX_ENV] ?? "";
-	const inheritedDepth = Number(process.env[SUBAGENT_PARENT_DEPTH_ENV]);
-	const parentDepth = input.parentDepth ?? (inheritedNestedRoute && Number.isFinite(inheritedDepth) ? inheritedDepth + 1 : 1);
-	const parentPath = input.parentPath ?? [
-		...parseNestedPathEnv(process.env[SUBAGENT_PARENT_PATH_ENV]),
-		...(parentRunId ? [{
-			runId: parentRunId,
-			...(parentChildIndex && /^\d+$/.test(parentChildIndex) ? { stepIndex: Number(parentChildIndex) } : {}),
-			...(input.childAgentName ? { agent: input.childAgentName } : {}),
-		}] : []),
-	];
-	env[SUBAGENT_PARENT_EVENT_SINK_ENV] = fanoutAuthorized
-		? input.parentEventSink ?? process.env[SUBAGENT_PARENT_EVENT_SINK_ENV] ?? ""
-		: "";
-	env[SUBAGENT_PARENT_CONTROL_INBOX_ENV] = fanoutAuthorized
-		? input.parentControlInbox ?? process.env[SUBAGENT_PARENT_CONTROL_INBOX_ENV] ?? ""
-		: "";
-	env[SUBAGENT_PARENT_ROOT_RUN_ID_ENV] = fanoutAuthorized
-		? input.parentRootRunId ?? process.env[SUBAGENT_PARENT_ROOT_RUN_ID_ENV] ?? input.runId ?? ""
-		: "";
-	env[SUBAGENT_PARENT_RUN_ID_ENV] = fanoutAuthorized ? parentRunId : "";
-	env[SUBAGENT_PARENT_CHILD_INDEX_ENV] = fanoutAuthorized ? parentChildIndex : "";
-	env[SUBAGENT_PARENT_DEPTH_ENV] = fanoutAuthorized ? String(parentDepth) : "";
-	env[SUBAGENT_PARENT_PATH_ENV] = fanoutAuthorized ? encodeNestedPathEnv(parentPath) : "";
-	env[SUBAGENT_PARENT_CAPABILITY_TOKEN_ENV] = fanoutAuthorized
-		? input.parentCapabilityToken ?? process.env[SUBAGENT_PARENT_CAPABILITY_TOKEN_ENV] ?? ""
-		: "";
-	env.PI_SUBAGENT_INHERIT_PROJECT_CONTEXT = input.inheritProjectContext ? "1" : "0";
-	env.PI_SUBAGENT_INHERIT_SKILLS = input.inheritSkills ? "1" : "0";
-	if (input.intercomSessionName) {
-		env.PI_SUBAGENT_INTERCOM_SESSION_NAME = input.intercomSessionName;
-	}
-	if (input.orchestratorIntercomTarget) {
-		env[SUBAGENT_ORCHESTRATOR_TARGET_ENV] = input.orchestratorIntercomTarget;
-	}
-	if (input.runId) {
-		env[SUBAGENT_RUN_ID_ENV] = input.runId;
-	}
-	if (input.childAgentName) {
-		env[SUBAGENT_CHILD_AGENT_ENV] = input.childAgentName;
-	}
-	if (input.childIndex !== undefined) {
-		env[SUBAGENT_CHILD_INDEX_ENV] = String(input.childIndex);
-	}
-	if (input.mcpDirectTools?.length) {
-		env.MCP_DIRECT_TOOLS = input.mcpDirectTools.join(",");
-	}
-	// A nested helper must never submit into its parent's capture.
-	env[STRUCTURED_OUTPUT_CAPTURE_ENV] = input.structuredOutput?.outputPath ?? "";
-	env[STRUCTURED_OUTPUT_SCHEMA_ENV] = input.structuredOutput?.schemaPath ?? "";
+  const taskArg = `Task: ${input.task}`;
+  if (Buffer.byteLength(taskArg) > TASK_ARG_LIMIT_BYTES) {
+    if (!nonempty(tempDir)) {
+      tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-subagent-"));
+    }
+    const taskFilePath = path.join(tempDir, "task.md");
+    fs.writeFileSync(taskFilePath, taskArg, { mode: 0o600 });
+    args.push(`@${taskFilePath}`);
+  } else {
+    args.push(taskArg);
+  }
 
-	return { args, env, tempDir };
+  return { args, tempDir };
 }
 
+export function buildPiArgs(input: ReadonlyInput<BuildPiArgsInput>): BuildPiArgsResult {
+  const args = [...input.baseArgs, ...resolveChildProjectTrustArgs(input.projectTrust)];
+  const session = piSessionLaunch(input);
+  args.push(...session.args);
+  const modelArg = applyThinkingSuffix(input.model, input.thinking);
+  if (nonempty(modelArg)) {
+    args.push("--model", modelArg);
+  }
+  const tools = buildToolLoadout(input);
+  args.push(
+    ...tools.args,
+    ...buildExtensionArgs(input, tools.fanoutAuthorized, tools.toolExtensionPaths),
+  );
+  const prompt = buildPromptArgs(input);
+  args.push(...prompt.args);
+  return {
+    args,
+    env: {
+      ...session.env,
+      [SUBAGENT_EAGER_TOOL_ENV]: tools.eager ? "1" : undefined,
+      ...childRouteEnv(input, tools.fanoutAuthorized),
+    },
+    tempDir: prompt.tempDir,
+  };
+}
 
 export function cleanupTempDir(tempDir: string | null | undefined): void {
-	if (!tempDir) return;
-	try {
-		fs.rmSync(tempDir, { recursive: true, force: true });
-	} catch {
-		// Temp cleanup is best effort.
-	}
+  if (!nonempty(tempDir)) {
+    return;
+  }
+  try {
+    fs.rmSync(tempDir, { recursive: true, force: true });
+  } catch {
+    // Temp cleanup is best effort.
+  }
 }

package/src/runs/shared/pi-launch-input.ts

@@ -0,0 +1,48 @@
+import type { ChildProjectTrustPolicy, JsonSchemaObject } from "../../shared/types.ts";
+import type { NestedPathEntry } from "./nested-path.ts";
+
+export interface BuildPiArgsInput {
+  readonly baseArgs: readonly string[];
+  readonly task: string;
+  readonly sessionEnabled: boolean;
+  readonly sessionDir?: string;
+  readonly sessionFile?: string;
+  readonly model?: string;
+  readonly thinking?: string;
+  readonly systemPromptMode?: "append" | "replace";
+  readonly inheritProjectContext: boolean;
+  readonly inheritSkills: boolean;
+  readonly tools?: readonly string[];
+  readonly allowSubagents?: boolean;
+  readonly extensions?: readonly string[];
+  readonly systemPrompt?: string | null;
+  readonly mcpDirectTools?: readonly string[];
+  /** Actual child spawn cwd; a new --session file inherits this directory natively. */
+  readonly cwd?: string;
+  readonly intercomSessionName?: string;
+  readonly orchestratorIntercomTarget?: string;
+  readonly rootSessionId?: string;
+  readonly runId?: string;
+  readonly childAgentName?: string;
+  readonly childIndex?: number;
+  readonly parentEventSink?: string;
+  readonly parentControlInbox?: string;
+  readonly parentRootRunId?: string;
+  readonly parentRunId?: string;
+  readonly parentChildIndex?: number;
+  readonly parentDepth?: number;
+  readonly parentPath?: readonly NestedPathEntry[];
+  readonly parentCapabilityToken?: string;
+  readonly structuredOutput?: {
+    readonly schema: JsonSchemaObject;
+    readonly schemaPath: string;
+    readonly outputPath: string;
+  };
+  readonly projectTrust?: ChildProjectTrustPolicy;
+}
+
+export interface BuildPiArgsResult {
+  args: string[];
+  env: Record<string, string | undefined>;
+  tempDir?: string;
+}