@astrofoundry/pi-astro 0.14.6 → 0.16.0

package/node_modules/pi-subagents/src/runs/shared/completion-guard.ts

@@ -0,0 +1,125 @@
+import type { Message } from "@earendil-works/pi-ai";
+import { isMutatingBashCommand } from "./long-running-guard.ts";
+
+const REVIEW_ONLY_PATTERNS = [
+	/\breview only\b/i,
+	/\bsuggest fixes only\b/i,
+	/\bonly return findings\b/i,
+	/\breturn findings only\b/i,
+];
+
+const REVIEWER_REQUIRED_EDIT_PATTERNS = [
+	/\bmust\s+(?:edit|modify|change|fix|patch|apply)\b/i,
+	/\brequired\s+to\s+(?:edit|modify|change|fix|patch|apply)\b/i,
+	/\bregardless\s+of\s+findings\b/i,
+	/\balways\s+(?:edit|modify|change|fix|patch|apply)\b/i,
+	/\bapply\s+(?:the\s+)?fix(?:es)?\s+directly\b/i,
+	/\bmake\s+(?:the\s+)?code\s+changes\b/i,
+];
+
+const EXPLICIT_NO_EDIT_PATTERNS = [
+	/\bdo not edit\b/i,
+	/\bdon't edit\b/i,
+	/\bdo not modify\b/i,
+	/\bdo not change files\b/i,
+];
+
+const SCOPED_NO_EDIT_CONSTRAINT_PATTERNS = [
+	/\bdo not edit files?\s+outside\b/i,
+	/\bdo not edit\s+outside\b/i,
+	/\bdo not edit\s+unrelated files?\b/i,
+	/\bdo not change\s+unrelated files?\b/i,
+	/\bdo not modify\s+unrelated files?\b/i,
+];
+
+const RESEARCH_AGENT_PATTERNS = [
+	/\binvestigate\b/i,
+	/\bscout\b/i,
+	/\bresearch(?:er)?\b/i,
+];
+
+const WORKER_IMPLEMENTATION_PATTERNS = [
+	/\b(?:implement|fix|edit|modify|patch|refactor|delete)\b/i,
+	/\b(?:update|add|remove|replace|create)\b(?!\s+(?:(?:a|an|the)\s+)?(?:report|summary|findings?)(?:\b|$))/i,
+	/\bapply\s+(?:the\s+)?(?:changes?|fix(?:es)?|patch)\b/i,
+	/\bmake\s+(?:the\s+)?changes\b/i,
+	/\bdo those fixes\b/i,
+];
+
+const GENERAL_IMPLEMENTATION_PATTERNS = [
+	/\b(?:implement|fix|edit|modify|patch|refactor)\b/i,
+	/\bapply\s+(?:the\s+)?(?:changes?|fix(?:es)?|patch)\b/i,
+	/\bmake\s+(?:the\s+)?changes\b/i,
+	/\bdo those fixes\b/i,
+	/\b(?:update|add|remove|replace|delete|create)\s+(?:the\s+)?(?:file|files|code|source|implementation|test|tests|component|function|module|class|method|logic|import|imports|readme|docs?|changelog|package\.json|config|manifest|extension|prompt|command)\b/i,
+];
+
+
+interface CompletionMutationGuardInput {
+	agent: string;
+	task: string;
+	messages: Message[];
+}
+
+interface CompletionMutationGuardResult {
+	expectedMutation: boolean;
+	attemptedMutation: boolean;
+	triggered: boolean;
+}
+
+function stripFrameworkInstructions(task: string): string {
+	return task
+		.split("\n")
+		.filter((line) => !/^\s*\[(?:Write to|Read from):/i.test(line))
+		.filter((line) => !/^\s*(?:Create and maintain progress at:|Update progress at:|Write your findings to:)/i.test(line))
+		.join("\n");
+}
+
+function stripScopedNoEditConstraints(task: string): string {
+	let stripped = task;
+	for (const pattern of SCOPED_NO_EDIT_CONSTRAINT_PATTERNS) {
+		stripped = stripped.replace(pattern, " ");
+	}
+	return stripped;
+}
+
+export function expectsImplementationMutation(agent: string, task: string): boolean {
+	const taskText = stripFrameworkInstructions(task);
+	const taskTextWithoutScopedConstraints = stripScopedNoEditConstraints(taskText);
+	if (REVIEW_ONLY_PATTERNS.some((pattern) => pattern.test(taskTextWithoutScopedConstraints))) return false;
+	if (EXPLICIT_NO_EDIT_PATTERNS.some((pattern) => pattern.test(taskTextWithoutScopedConstraints))) return false;
+
+	if (RESEARCH_AGENT_PATTERNS.some((pattern) => pattern.test(agent))) return false;
+	if (/\breviewer\b/i.test(agent)) return REVIEWER_REQUIRED_EDIT_PATTERNS.some((pattern) => pattern.test(taskText));
+
+	const workerIntent = agent === "worker" && WORKER_IMPLEMENTATION_PATTERNS.some((pattern) => pattern.test(taskText));
+	if (workerIntent) return true;
+
+	return GENERAL_IMPLEMENTATION_PATTERNS.some((pattern) => pattern.test(taskText));
+}
+
+export function hasMutationToolCall(messages: Message[]): boolean {
+	for (const message of messages) {
+		if (message.role !== "assistant") continue;
+		for (const part of message.content) {
+			if (part.type !== "toolCall") continue;
+			if (part.name === "edit" || part.name === "write") return true;
+			if (part.name !== "bash") continue;
+			const args = typeof part.arguments === "object" && part.arguments !== null && !Array.isArray(part.arguments)
+				? part.arguments as Record<string, unknown>
+				: {};
+			if (typeof args.command === "string" && isMutatingBashCommand(args.command)) return true;
+		}
+	}
+	return false;
+}
+
+export function evaluateCompletionMutationGuard(input: CompletionMutationGuardInput): CompletionMutationGuardResult {
+	const expectedMutation = expectsImplementationMutation(input.agent, input.task);
+	const attemptedMutation = hasMutationToolCall(input.messages);
+	return {
+		expectedMutation,
+		attemptedMutation,
+		triggered: expectedMutation && !attemptedMutation,
+	};
+}

package/node_modules/pi-subagents/src/runs/shared/long-running-guard.ts

@@ -0,0 +1,175 @@
+import type { ResolvedControlConfig } from "../../shared/types.ts";
+
+interface LongRunningNoticeMetrics {
+	startedAt: number;
+	now: number;
+	turns: number;
+	tokens: number;
+}
+
+type LongRunningTriggerReason = "time_threshold" | "turn_threshold" | "token_threshold";
+
+interface FailedMutatingAttempt {
+	tool: string;
+	path?: string;
+	error: string;
+	ts: number;
+}
+
+interface MutatingFailureState {
+	consecutiveFailures: number;
+	lastFailureAt?: number;
+	recentFailures: FailedMutatingAttempt[];
+	lastMutatingPath?: string;
+	repeatedPathFailures: number;
+}
+
+const MUTATING_BASH_PATTERNS = [
+	/(^|[;&|()\s])rm\s+/,
+	/(^|[;&|()\s])mv\s+/,
+	/(^|[;&|()\s])cp\s+/,
+	/(^|[;&|()\s])mkdir\s+/,
+	/(^|[;&|()\s])touch\s+/,
+	/(^|[;&|()\s])git\s+apply\b/,
+	/(^|[;&|()\s])patch\s+/,
+	/(^|[;&|()\s])sed\s+[^\n;&|]*\s-i\b/,
+	/(^|[;&|()\s])perl\s+[^\n;&|]*\s-pi\b/,
+	/(^|[;&|()]|\n)\s*tee\s+[^|&;]+/,
+	/\b(writeFile|writeFileSync|appendFile|appendFileSync)\b/,
+	/\bwrite_text\s*\(/,
+	/\bopen\s*\([^)]*,\s*["'][wa]/,
+];
+
+const MUTATING_FAILURE_HINTS = [
+	"failed",
+	"error",
+	"no exact match",
+	"did not match",
+	"malformed",
+	"rejected",
+	"unable",
+	"cannot",
+	"could not",
+];
+
+export function resolveCurrentPath(toolName: string | undefined, args: Record<string, unknown> | undefined): string | undefined {
+	if (!toolName || !args) return undefined;
+	const direct = ["path", "file", "filename", "target", "cwd"];
+	for (const key of direct) {
+		const value = args[key];
+		if (typeof value === "string" && value.trim()) return value.trim();
+	}
+	if (toolName === "bash") {
+		const command = typeof args.command === "string" ? args.command : undefined;
+		if (!command) return undefined;
+		const redirect = command.match(/(?:>|>>|tee\s+)(\S+)/);
+		if (redirect?.[1]) return redirect[1];
+	}
+	return undefined;
+}
+
+function hasUnquotedFileRedirection(command: string): boolean {
+	let inSingle = false;
+	let inDouble = false;
+	for (let i = 0; i < command.length; i++) {
+		const char = command[i]!;
+		if (char === "'" && !inDouble) {
+			inSingle = !inSingle;
+			continue;
+		}
+		if (char === '"' && !inSingle) {
+			inDouble = !inDouble;
+			continue;
+		}
+		if (inSingle || inDouble) continue;
+		if (char !== ">") continue;
+		if (command[i - 1] === "-") continue;
+		const isDouble = command[i + 1] === ">";
+		let cursor = i + (isDouble ? 2 : 1);
+		while (cursor < command.length && /\s/.test(command[cursor]!)) cursor++;
+		if (cursor >= command.length) continue;
+		const targetStart = command[cursor]!;
+		if (targetStart === "&" || targetStart === "|" || targetStart === ";") continue;
+		if (targetStart === "(" || targetStart === ")") continue;
+		return true;
+	}
+	return false;
+}
+
+export function isMutatingBashCommand(command: string): boolean {
+	return hasUnquotedFileRedirection(command) || MUTATING_BASH_PATTERNS.some((pattern) => pattern.test(command));
+}
+
+export function isMutatingTool(toolName: string | undefined, args: Record<string, unknown> | undefined): boolean {
+	if (!toolName) return false;
+	if (toolName === "edit" || toolName === "write") return true;
+	if (toolName !== "bash") return false;
+	const command = typeof args?.command === "string" ? args.command : "";
+	if (!command.trim()) return false;
+	return isMutatingBashCommand(command);
+}
+
+export function didMutatingToolFail(text: string): boolean {
+	const lowered = text.toLowerCase();
+	return MUTATING_FAILURE_HINTS.some((hint) => lowered.includes(hint));
+}
+
+export function nextLongRunningTrigger(
+	config: ResolvedControlConfig,
+	metrics: LongRunningNoticeMetrics,
+): LongRunningTriggerReason | undefined {
+	if (metrics.now - metrics.startedAt >= config.activeNoticeAfterMs) return "time_threshold";
+	if (config.activeNoticeAfterTurns !== undefined && metrics.turns >= config.activeNoticeAfterTurns) return "turn_threshold";
+	if (config.activeNoticeAfterTokens !== undefined && metrics.tokens >= config.activeNoticeAfterTokens) return "token_threshold";
+	return undefined;
+}
+
+export function resetMutatingFailureState(state: MutatingFailureState): void {
+	state.consecutiveFailures = 0;
+	state.lastFailureAt = undefined;
+	state.recentFailures = [];
+	state.lastMutatingPath = undefined;
+	state.repeatedPathFailures = 0;
+}
+
+export function createMutatingFailureState(): MutatingFailureState {
+	return {
+		consecutiveFailures: 0,
+		recentFailures: [],
+		repeatedPathFailures: 0,
+	};
+}
+
+export function recordMutatingFailure(
+	state: MutatingFailureState,
+	input: FailedMutatingAttempt,
+	windowMs: number,
+): void {
+	if (state.lastFailureAt === undefined || input.ts - state.lastFailureAt > windowMs) {
+		state.consecutiveFailures = 0;
+		state.recentFailures = [];
+		state.repeatedPathFailures = 0;
+		state.lastMutatingPath = undefined;
+	}
+	state.lastFailureAt = input.ts;
+	state.consecutiveFailures += 1;
+	if (input.path && state.lastMutatingPath === input.path) {
+		state.repeatedPathFailures += 1;
+	} else if (input.path) {
+		state.lastMutatingPath = input.path;
+		state.repeatedPathFailures = 1;
+	}
+	state.recentFailures.push(input);
+	if (state.recentFailures.length > 3) state.recentFailures.shift();
+}
+
+export function shouldEscalateMutatingFailures(state: MutatingFailureState, threshold: number): boolean {
+	return state.consecutiveFailures >= threshold || state.repeatedPathFailures >= threshold;
+}
+
+export function summarizeRecentMutatingFailures(state: MutatingFailureState): string | undefined {
+	if (state.recentFailures.length === 0) return undefined;
+	return state.recentFailures
+		.map((entry) => `${entry.tool}${entry.path ? `(${entry.path})` : ""}: ${entry.error}`)
+		.join(" | ");
+}

package/node_modules/pi-subagents/src/runs/shared/model-fallback.ts

@@ -0,0 +1,103 @@
+import type { ModelInfo as AvailableModelInfo } from "../../shared/model-info.ts";
+import type { Usage } from "../../shared/types.ts";
+
+export type { AvailableModelInfo };
+
+interface ModelAttemptSummary {
+	model: string;
+	success: boolean;
+	exitCode?: number | null;
+	error?: string;
+	usage?: Usage;
+}
+
+export function splitThinkingSuffix(model: string): { baseModel: string; thinkingSuffix: string } {
+	const colonIdx = model.lastIndexOf(":");
+	if (colonIdx === -1) return { baseModel: model, thinkingSuffix: "" };
+	return {
+		baseModel: model.substring(0, colonIdx),
+		thinkingSuffix: model.substring(colonIdx),
+	};
+}
+
+export function resolveModelCandidate(
+	model: string | undefined,
+	availableModels: AvailableModelInfo[] | undefined,
+	preferredProvider?: string,
+): string | undefined {
+	if (!model) return undefined;
+	if (model.includes("/")) return model;
+	if (!availableModels || availableModels.length === 0) return model;
+
+	const { baseModel, thinkingSuffix } = splitThinkingSuffix(model);
+	const matches = availableModels.filter((entry) => entry.id === baseModel);
+	if (preferredProvider) {
+		const preferredMatch = matches.find((entry) => entry.provider === preferredProvider);
+		if (preferredMatch) return `${preferredMatch.fullId}${thinkingSuffix}`;
+	}
+	if (matches.length !== 1) return model;
+	return `${matches[0]!.fullId}${thinkingSuffix}`;
+}
+
+export function buildModelCandidates(
+	primaryModel: string | undefined,
+	fallbackModels: string[] | undefined,
+	availableModels: AvailableModelInfo[] | undefined,
+	preferredProvider?: string,
+): string[] {
+	const seen = new Set<string>();
+	const candidates: string[] = [];
+	for (const raw of [primaryModel, ...(fallbackModels ?? [])]) {
+		if (!raw) continue;
+		const normalized = resolveModelCandidate(raw.trim(), availableModels, preferredProvider);
+		if (!normalized || seen.has(normalized)) continue;
+		seen.add(normalized);
+		candidates.push(normalized);
+	}
+	return candidates;
+}
+
+const RETRYABLE_MODEL_FAILURE_PATTERNS = [
+	/rate\s*limit/i,
+	/too many requests/i,
+	/\b429\b/,
+	/quota/i,
+	/billing/i,
+	/credit/i,
+	/auth(?:entication)?/i,
+	/unauthori[sz]ed/i,
+	/forbidden/i,
+	/api key/i,
+	/token expired/i,
+	/invalid key/i,
+	/provider.*unavailable/i,
+	/model.*unavailable/i,
+	/model.*disabled/i,
+	/model.*not found/i,
+	/unknown model/i,
+	/overloaded/i,
+	/service unavailable/i,
+	/temporar(?:ily)? unavailable/i,
+	/connection refused/i,
+	/fetch failed/i,
+	/network error/i,
+	/socket hang up/i,
+	/upstream/i,
+	/timed? out/i,
+	/timeout/i,
+	/\b502\b/,
+	/\b503\b/,
+	/\b504\b/,
+];
+
+export function isRetryableModelFailure(error: string | undefined): boolean {
+	if (!error) return false;
+	return RETRYABLE_MODEL_FAILURE_PATTERNS.some((pattern) => pattern.test(error));
+}
+
+export function formatModelAttemptNote(attempt: ModelAttemptSummary, nextModel?: string): string {
+	const failure = attempt.error?.trim() || `exit ${attempt.exitCode ?? 1}`;
+	return nextModel
+		? `[fallback] ${attempt.model} failed: ${failure}. Retrying with ${nextModel}.`
+		: `[fallback] ${attempt.model} failed: ${failure}.`;
+}

package/node_modules/pi-subagents/src/runs/shared/parallel-utils.ts

@@ -0,0 +1,107 @@
+export interface RunnerSubagentStep {
+	agent: string;
+	task: string;
+	cwd?: string;
+	model?: string;
+	modelCandidates?: string[];
+	tools?: string[];
+	extensions?: string[];
+	mcpDirectTools?: string[];
+	systemPrompt?: string | null;
+	systemPromptMode?: "append" | "replace";
+	inheritProjectContext: boolean;
+	inheritSkills: boolean;
+	skills?: string[];
+	outputPath?: string;
+	outputMode?: "inline" | "file-only";
+	sessionFile?: string;
+	maxSubagentDepth?: number;
+}
+
+export interface ParallelStepGroup {
+	parallel: RunnerSubagentStep[];
+	concurrency?: number;
+	failFast?: boolean;
+	worktree?: boolean;
+}
+
+export type RunnerStep = RunnerSubagentStep | ParallelStepGroup;
+
+export function isParallelGroup(step: RunnerStep): step is ParallelStepGroup {
+	return "parallel" in step && Array.isArray(step.parallel);
+}
+
+export function flattenSteps(steps: RunnerStep[]): RunnerSubagentStep[] {
+	const flat: RunnerSubagentStep[] = [];
+	for (const step of steps) {
+		if (isParallelGroup(step)) {
+			for (const task of step.parallel) flat.push(task);
+		} else {
+			flat.push(step);
+		}
+	}
+	return flat;
+}
+
+export async function mapConcurrent<T, R>(
+	items: T[],
+	limit: number,
+	fn: (item: T, i: number) => Promise<R>,
+): Promise<R[]> {
+	const safeLimit = Math.max(1, Math.floor(limit) || 1);
+	const results: R[] = new Array(items.length);
+	let next = 0;
+
+	async function worker(_workerIndex: number): Promise<void> {
+		while (next < items.length) {
+			const i = next++;
+			results[i] = await fn(items[i], i);
+		}
+	}
+
+	await Promise.all(
+		Array.from({ length: Math.min(safeLimit, items.length) }, (_, wi) => worker(wi)),
+	);
+	return results;
+}
+
+export interface ParallelTaskResult {
+	agent: string;
+	taskIndex?: number;
+	output: string;
+	exitCode: number | null;
+	error?: string;
+	model?: string;
+	attemptedModels?: string[];
+	outputTargetPath?: string;
+	outputTargetExists?: boolean;
+}
+
+export function aggregateParallelOutputs(
+	results: ParallelTaskResult[],
+	headerFormat: (index: number, agent: string) => string = (i, agent) =>
+		`=== Parallel Task ${i + 1} (${agent}) ===`,
+): string {
+	return results
+		.map((r, i) => {
+			const header = headerFormat(r.taskIndex ?? i, r.agent);
+			const hasOutput = Boolean(r.output?.trim());
+			const status =
+				r.exitCode === -1
+					? "SKIPPED"
+					: r.exitCode !== 0 && r.exitCode !== null
+						? `FAILED (exit code ${r.exitCode})${r.error ? `: ${r.error}` : ""}`
+						: r.error
+							? `WARNING: ${r.error}`
+							: !hasOutput && r.outputTargetPath && r.outputTargetExists === false
+								? `EMPTY OUTPUT (expected output file missing: ${r.outputTargetPath})`
+								: !hasOutput && !r.outputTargetPath
+									? "EMPTY OUTPUT (no textual response returned)"
+							: "";
+			const body = status ? (hasOutput ? `${status}\n${r.output}` : status) : r.output;
+			return `${header}\n${body}`;
+		})
+		.join("\n\n");
+}
+
+export const MAX_PARALLEL_CONCURRENCY = 4;

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

@@ -0,0 +1,158 @@
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh"];
+const TASK_ARG_LIMIT = 8000;
+const PROMPT_RUNTIME_EXTENSION_PATH = path.join(path.dirname(fileURLToPath(import.meta.url)), "subagent-prompt-runtime.ts");
+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";
+
+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[];
+	extensions?: string[];
+	systemPrompt?: string | null;
+	mcpDirectTools?: string[];
+	promptFileStem?: string;
+	intercomSessionName?: string;
+	orchestratorIntercomTarget?: string;
+	runId?: string;
+	childAgentName?: string;
+	childIndex?: number;
+}
+
+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 || thinking === "off") return model;
+	const colonIdx = model.lastIndexOf(":");
+	if (colonIdx !== -1 && THINKING_LEVELS.includes(model.substring(colonIdx + 1))) return model;
+	return `${model}:${thinking}`;
+}
+
+export function buildPiArgs(input: BuildPiArgsInput): BuildPiArgsResult {
+	const args = [...input.baseArgs];
+
+	if (input.sessionFile) {
+		fs.mkdirSync(path.dirname(input.sessionFile), { recursive: true });
+		args.push("--session", input.sessionFile);
+	} 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 toolExtensionPaths: string[] = [];
+	if (input.tools?.length) {
+		const builtinTools: string[] = [];
+		for (const tool of input.tools) {
+			if (tool.includes("/") || tool.endsWith(".ts") || tool.endsWith(".js")) {
+				toolExtensionPaths.push(tool);
+			} else {
+				builtinTools.push(tool);
+			}
+		}
+		if (builtinTools.length > 0) {
+			args.push("--tools", builtinTools.join(","));
+		}
+	}
+
+	const runtimeExtensions = [PROMPT_RUNTIME_EXTENSION_PATH];
+	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");
+	}
+
+	let tempDir: string | undefined;
+	if (input.systemPrompt !== undefined && input.systemPrompt !== null) {
+		tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-subagent-"));
+		const stem = (input.promptFileStem ?? "prompt").replace(/[^\w.-]/g, "_");
+		const promptPath = path.join(tempDir, `${stem}.md`);
+		fs.writeFileSync(promptPath, input.systemPrompt, { mode: 0o600 });
+		args.push(input.systemPromptMode === "replace" ? "--system-prompt" : "--append-system-prompt", promptPath);
+	}
+
+	if (input.task.length > TASK_ARG_LIMIT) {
+		if (!tempDir) {
+			tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-subagent-"));
+		}
+		const taskFilePath = path.join(tempDir, "task.md");
+		fs.writeFileSync(taskFilePath, `Task: ${input.task}`, { mode: 0o600 });
+		args.push(`@${taskFilePath}`);
+	} else {
+		args.push(`Task: ${input.task}`);
+	}
+
+	const env: Record<string, string | undefined> = {};
+	env[SUBAGENT_CHILD_ENV] = "1";
+	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(",");
+	} else {
+		env.MCP_DIRECT_TOOLS = "__none__";
+	}
+
+	return { args, env, 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.
+	}
+}