@dungle-scrubs/tallow 0.8.26 → 0.8.27

package/extensions/subagent-tool/index.ts

@@ -50,6 +50,7 @@ import {
 	applyBackgroundResultRetention,
 	mapWithConcurrencyLimit,
 	type OnUpdateCallback,
+	resolveRetryPhaseTimeoutMs,
 	runSingleAgent,
 	setPiRef,
 	setTelemetryHandle,
@@ -181,6 +182,25 @@ export default function (pi: ExtensionAPI) {
 		}
 	});
 
+	// Kill all running background subagents on session shutdown (SIGTERM during user input).
+	// Unlike agent_end, this fires when the entire session is exiting — we don't need to
+	// retain results, just ensure orphaned subagent processes are terminated promptly.
+	pi.on("session_shutdown", async () => {
+		let mutated = false;
+		for (const [_id, bg] of backgroundSubagents) {
+			if (bg.status === "running" && bg.process && !bg.process.killed) {
+				bg.process.kill("SIGTERM");
+				bg.completedAt = Date.now();
+				bg.status = "failed";
+				bg.result.stopReason = "shutdown";
+				mutated = true;
+			}
+		}
+		if (mutated) {
+			publishSubagentSnapshot(pi.events);
+		}
+	});
+
 	pi.registerTool({
 		name: "subagent",
 		label: "subagent",
@@ -674,6 +694,7 @@ async function executeParallel(
 	const allResults: SingleResult[] = new Array(tasks.length);
 
 	// Initialize placeholder results
+	const parallelStartTime = Date.now();
 	for (let i = 0; i < tasks.length; i++) {
 		allResults[i] = {
 			agent: tasks[i].agent,
@@ -692,6 +713,7 @@ async function executeParallel(
 				turns: 0,
 				denials: 0,
 			},
+			startTime: parallelStartTime,
 		};
 	}
 
@@ -788,12 +810,34 @@ async function executeParallel(
 		const retrySummaryLines: string[] = [];
 		const totalRetries = initialStalledIndexes.length;
 
+		// Cap the entire retry phase with a wall-clock timeout so N sequential
+		// retries × per-worker watchdog timeouts don't block the parent for 30+ min.
+		const retryPhaseTimeoutMs = resolveRetryPhaseTimeoutMs();
+		const retryAbort = new AbortController();
+		const retryTimer = setTimeout(() => retryAbort.abort(), retryPhaseTimeoutMs);
+		// Propagate parent abort to the retry phase.
+		const parentAbortHandler = signal ? () => retryAbort.abort() : undefined;
+		if (signal && parentAbortHandler) {
+			if (signal.aborted) retryAbort.abort();
+			else signal.addEventListener("abort", parentAbortHandler, { once: true });
+		}
+		const retrySignal = retryAbort.signal;
+
 		try {
 			ctx.ui.setWorkingMessage(
 				`Rerunning ${totalRetries} stalled worker${totalRetries === 1 ? "" : "s"} individually`
 			);
 
 			for (let retryIndex = 0; retryIndex < initialStalledIndexes.length; retryIndex++) {
+				// Bail out if the retry phase deadline has elapsed.
+				if (retrySignal.aborted) {
+					for (let remaining = retryIndex; remaining < initialStalledIndexes.length; remaining++) {
+						const idx = initialStalledIndexes[remaining];
+						retrySummaryLines.push(`- [${tasks[idx].agent}] skipped (retry phase timeout)`);
+					}
+					break;
+				}
+
 				const stalledIndex = initialStalledIndexes[retryIndex];
 				const stalledTask = tasks[stalledIndex];
 				const priorResult = allResults[stalledIndex];
@@ -810,33 +854,49 @@ async function executeParallel(
 					`Retrying stalled worker ${retryIndex + 1}/${totalRetries}: ${stalledTask.agent}`
 				);
 
-				const retryResult = await runSingleAgent(
-					ctx.cwd,
-					agents,
-					stalledTask.agent,
-					retryTask,
-					stalledTask.cwd,
-					undefined,
-					signal,
-					(partial) => {
-						if (partial.details?.results[0]) {
-							const partialResult = {
-								...partial.details.results[0],
-								task: stalledTask.task,
-							};
-							allResults[stalledIndex] = partialResult;
-							emitParallelUpdate();
-						}
-					},
-					makeDetails("parallel"),
-					pi.events,
-					undefined,
-					explicitRetryModel,
-					parentModelId,
-					defaults,
-					retryRoutingHints,
-					stalledTask.isolation
-				);
+				let retryResult: SingleResult;
+				try {
+					retryResult = await runSingleAgent(
+						ctx.cwd,
+						agents,
+						stalledTask.agent,
+						retryTask,
+						stalledTask.cwd,
+						undefined,
+						retrySignal,
+						(partial) => {
+							if (partial.details?.results[0]) {
+								const partialResult = {
+									...partial.details.results[0],
+									task: stalledTask.task,
+								};
+								allResults[stalledIndex] = partialResult;
+								emitParallelUpdate();
+							}
+						},
+						makeDetails("parallel"),
+						pi.events,
+						undefined,
+						explicitRetryModel,
+						parentModelId,
+						defaults,
+						retryRoutingHints,
+						stalledTask.isolation
+					);
+				} catch {
+					// Retry-phase timeout aborted this worker. Mark remaining
+					// workers as skipped and exit the loop.
+					retrySummaryLines.push(`- [${stalledTask.agent}] aborted (retry phase timeout)`);
+					for (
+						let remaining = retryIndex + 1;
+						remaining < initialStalledIndexes.length;
+						remaining++
+					) {
+						const idx = initialStalledIndexes[remaining];
+						retrySummaryLines.push(`- [${tasks[idx].agent}] skipped (retry phase timeout)`);
+					}
+					break;
+				}
 
 				retryResult.task = stalledTask.task;
 				retryResult.stderr = appendStderrNote(
@@ -848,6 +908,10 @@ async function executeParallel(
 				emitParallelUpdate();
 			}
 		} finally {
+			clearTimeout(retryTimer);
+			if (signal && parentAbortHandler) {
+				signal.removeEventListener("abort", parentAbortHandler);
+			}
 			ctx.ui.setWorkingMessage();
 		}
 
@@ -1066,8 +1130,6 @@ interface DisplayRenderOptions {
  * Shared preview budgets for compact subagent presentation lines.
  */
 const SUBAGENT_PREVIEW_LIMITS = {
-	callCentipedeStep: 90,
-	callParallelTask: 90,
 	collapsedParallelResult: 88,
 } as const;
 
@@ -1333,65 +1395,27 @@ function renderSubagentCall(args: Record<string, unknown>, theme: Theme) {
 		args.tasks as { agent: string; model?: string; task: string }[] | string | undefined
 	);
 	const lines: string[] = [];
+	// Only show scope when non-default (user is the default)
+	const scopeEntry = scope !== "user" ? `scope:${scope}` : undefined;
 
 	if (centipedeArr && centipedeArr.length > 0) {
 		appendSection(lines, [formatSubagentHeader(theme, `centipede (${centipedeArr.length} steps)`)]);
-		const metaLine = formatMetaLine(theme, [
-			`scope:${scope}`,
-			model ? `model:${model}` : undefined,
-		]);
+		const metaLine = formatMetaLine(theme, [scopeEntry, model ? `model:${model}` : undefined]);
 		if (metaLine) appendSection(lines, [metaLine]);
-
-		const previewLines = centipedeArr.slice(0, 3).map((step, index) => {
-			const task = step.task.replace(/\{previous\}/g, "").trim();
-			const preview = toCompactPreview(
-				task || "(uses previous output)",
-				SUBAGENT_PREVIEW_LIMITS.callCentipedeStep
-			);
-			const modelTag = formatModelTag(theme, step.model);
-			const identity = modelTag
-				? `${formatSubagentIdentity(step.agent)} ${modelTag}`
-				: formatSubagentIdentity(step.agent);
-			return `${formatPresentationText(theme, "meta", `${index + 1}.`)} ${identity} ${formatPresentationText(theme, "process_output", preview)}`;
-		});
-		if (previewLines.length > 0) appendSection(lines, previewLines, { blankBefore: true });
-		if (centipedeArr.length > 3) {
-			appendSection(lines, [
-				formatPresentationText(theme, "hint", `… +${centipedeArr.length - 3} more steps`),
-			]);
-		}
 		return new Text(lines.join("\n"), 0, 0);
 	}
 
 	if (tasksArr && tasksArr.length > 0) {
 		appendSection(lines, [formatSubagentHeader(theme, `parallel (${tasksArr.length} tasks)`)]);
-		const metaLine = formatMetaLine(theme, [
-			`scope:${scope}`,
-			model ? `model:${model}` : undefined,
-		]);
+		const metaLine = formatMetaLine(theme, [scopeEntry, model ? `model:${model}` : undefined]);
 		if (metaLine) appendSection(lines, [metaLine]);
-
-		const previewLines = tasksArr.slice(0, 2).map((task, index) => {
-			const taskPreview = toCompactPreview(task.task, SUBAGENT_PREVIEW_LIMITS.callParallelTask);
-			const modelTag = formatModelTag(theme, task.model);
-			const identity = modelTag
-				? `${formatSubagentIdentity(task.agent)} ${modelTag}`
-				: formatSubagentIdentity(task.agent);
-			return `${formatPresentationText(theme, "meta", `${index + 1}.`)} ${identity} ${formatPresentationText(theme, "process_output", taskPreview)}`;
-		});
-		if (previewLines.length > 0) appendSection(lines, previewLines, { blankBefore: true });
-		if (tasksArr.length > 2) {
-			appendSection(lines, [
-				formatPresentationText(theme, "hint", `… +${tasksArr.length - 2} more tasks`),
-			]);
-		}
 		return new Text(lines.join("\n"), 0, 0);
 	}
 
 	const agentName = (args.agent as string) || "...";
 	const task = typeof args.task === "string" ? args.task : "...";
 	appendSection(lines, [formatSubagentHeader(theme, "single", agentName)]);
-	const metaLine = formatMetaLine(theme, [`scope:${scope}`, model ? `model:${model}` : undefined]);
+	const metaLine = formatMetaLine(theme, [scopeEntry, model ? `model:${model}` : undefined]);
 	if (metaLine) appendSection(lines, [metaLine]);
 	appendSection(
 		lines,
@@ -1523,7 +1547,14 @@ function renderSingleResult(
 		: isError
 			? theme.fg("error", getIcon("error"))
 			: theme.fg("success", getIcon("success"));
-	const statusLabel = isRunning ? "running" : isError ? "failed" : "completed";
+	const statusLabel =
+		isRunning && r.startTime
+			? `running ${formatDuration(Date.now() - r.startTime)}`
+			: isRunning
+				? "running"
+				: isError
+					? "failed"
+					: "completed";
 	const headerLine = formatSubagentHeader(theme, statusLabel, r.agent, icon);
 	const metaLine = formatMetaLine(theme, [
 		`source:${r.agentSource}`,
@@ -1727,17 +1758,25 @@ function renderCentipedeResult(
 		: failCount > 0
 			? theme.fg("error", getIcon("error"))
 			: theme.fg("success", getIcon("success"));
+	const earliestStart = details.results.reduce(
+		(min, r) => (r.startTime && r.startTime < min ? r.startTime : min),
+		Number.POSITIVE_INFINITY
+	);
+	const elapsed = Number.isFinite(earliestStart)
+		? formatDuration(Date.now() - earliestStart)
+		: undefined;
 	const summaryLine = formatMetaLine(theme, [
 		`${successCount + failCount}/${totalSteps} done`,
 		runningCount > 0 ? `${runningCount} running` : undefined,
 		failCount > 0 ? `${failCount} failed` : undefined,
+		elapsed,
 	]);
 
 	if (expanded) {
 		const container = new Container();
-		const headerLines: string[] = [formatSubagentHeader(theme, "centipede", undefined, icon)];
-		if (summaryLine) appendSection(headerLines, [summaryLine]);
-		container.addChild(new Text(headerLines.join("\n"), 0, 0));
+		const headerLines: string[] = [];
+		if (summaryLine) headerLines.push(`${icon} ${summaryLine}`);
+		if (headerLines.length > 0) container.addChild(new Text(headerLines.join("\n"), 0, 0));
 
 		for (let si = 0; si < totalSteps; si++) {
 			const stepNum = si + 1;
@@ -1746,11 +1785,13 @@ function renderCentipedeResult(
 				stepResult?.agent ?? details.centipedeSteps?.[si]?.agent ?? `step ${stepNum}`;
 			const stepStatus = !stepResult
 				? "pending"
-				: stepResult.exitCode === -1
-					? "running"
-					: isResultError(stepResult)
-						? "failed"
-						: "completed";
+				: stepResult.exitCode === -1 && stepResult.startTime
+					? `running ${formatDuration(Date.now() - stepResult.startTime)}`
+					: stepResult.exitCode === -1
+						? "running"
+						: isResultError(stepResult)
+							? "failed"
+							: "completed";
 			const stepStatusRole = !stepResult
 				? "meta"
 				: stepResult.exitCode === -1
@@ -1839,8 +1880,8 @@ function renderCentipedeResult(
 		return container;
 	}
 
-	const lines: string[] = [formatSubagentHeader(theme, "centipede", undefined, icon)];
-	if (summaryLine) appendSection(lines, [summaryLine]);
+	const lines: string[] = [];
+	if (summaryLine) lines.push(`${icon} ${summaryLine}`);
 
 	for (let si = 0; si < totalSteps; si++) {
 		const stepNum = si + 1;
@@ -1851,11 +1892,13 @@ function renderCentipedeResult(
 		const stem = isLast ? "   " : `${formatPresentationText(theme, "meta", "│")}  `;
 		const stepStatus = !stepResult
 			? "pending"
-			: stepResult.exitCode === -1
-				? "running"
-				: isResultError(stepResult)
-					? "failed"
-					: "done";
+			: stepResult.exitCode === -1 && stepResult.startTime
+				? `running ${formatDuration(Date.now() - stepResult.startTime)}`
+				: stepResult.exitCode === -1
+					? "running"
+					: isResultError(stepResult)
+						? "failed"
+						: "done";
 		const statusRole = !stepResult
 			? "meta"
 			: stepResult.exitCode === -1
@@ -1922,23 +1965,36 @@ function renderParallelResult(
 			: counts.stalled > 0
 				? theme.fg("warning", getIcon("blocked"))
 				: theme.fg("success", getIcon("success"));
+	const earliestStart = details.results.reduce(
+		(min, r) => (r.startTime && r.startTime < min ? r.startTime : min),
+		Number.POSITIVE_INFINITY
+	);
+	const elapsed = Number.isFinite(earliestStart)
+		? formatDuration(Date.now() - earliestStart)
+		: undefined;
 	const summaryLine = formatMetaLine(theme, [
 		`${counts.finished}/${details.results.length} done`,
 		`${counts.completed} completed`,
 		counts.failed > 0 ? `${counts.failed} failed` : undefined,
 		`${counts.stalled} stalled`,
 		counts.running > 0 ? `${counts.running} running` : undefined,
+		elapsed,
 	]);
 
 	if (expanded && !isRunning) {
 		const container = new Container();
-		const headerLines = [formatSubagentHeader(theme, "parallel", undefined, icon)];
-		if (summaryLine) appendSection(headerLines, [summaryLine]);
-		container.addChild(new Text(headerLines.join("\n"), 0, 0));
+		const headerLines: string[] = [];
+		if (summaryLine) headerLines.push(`${icon} ${summaryLine}`);
+		if (headerLines.length > 0) container.addChild(new Text(headerLines.join("\n"), 0, 0));
 
 		for (const result of details.results) {
 			const resultState = getParallelResultState(result);
-			const resultStatus = resultState === "completed" ? "completed" : resultState;
+			const resultStatus =
+				resultState === "completed"
+					? "completed"
+					: resultState === "running" && result.startTime
+						? `running ${formatDuration(Date.now() - result.startTime)}`
+						: resultState;
 			const resultStatusRole =
 				resultState === "failed"
 					? "status_error"
@@ -2028,8 +2084,8 @@ function renderParallelResult(
 		return container;
 	}
 
-	const lines: string[] = [formatSubagentHeader(theme, "parallel", undefined, icon)];
-	if (summaryLine) appendSection(lines, [summaryLine]);
+	const lines: string[] = [];
+	if (summaryLine) lines.push(`${icon} ${summaryLine}`);
 
 	for (let index = 0; index < details.results.length; index++) {
 		const result = details.results[index];
@@ -2037,7 +2093,12 @@ function renderParallelResult(
 		const branch = formatPresentationText(theme, "meta", isLast ? "└─" : "├─");
 		const stem = isLast ? "   " : `${formatPresentationText(theme, "meta", "│")}  `;
 		const resultState = getParallelResultState(result);
-		const resultStatus = resultState === "completed" ? "done" : resultState;
+		const resultStatus =
+			resultState === "completed"
+				? "done"
+				: resultState === "running" && result.startTime
+					? `running ${formatDuration(Date.now() - result.startTime)}`
+					: resultState;
 		const statusRole =
 			resultState === "failed"
 				? "status_error"

package/extensions/subagent-tool/process.ts

@@ -449,6 +449,7 @@ export interface ForegroundWatchdogThresholds {
 	readonly killGraceMs: number;
 	readonly startupTimeoutMs: number;
 	readonly toolExecutionTimeoutMs: number;
+	readonly wallClockTimeoutMs: number;
 }
 
 /** Heartbeat state tracked by the foreground subagent liveness watchdog. */
@@ -464,7 +465,7 @@ export type WatchdogStatus =
 	| {
 			readonly elapsedMs: number;
 			readonly kind: "stalled";
-			readonly phase: "inactivity" | "startup" | "tool_execution";
+			readonly phase: "inactivity" | "startup" | "tool_execution" | "wall_clock";
 			readonly timeoutMs: number;
 	  };
 
@@ -477,17 +478,33 @@ export const SUBAGENT_INACTIVITY_TIMEOUT_MS_ENV = "TALLOW_SUBAGENT_INACTIVITY_TI
 /** Env var overriding the foreground timeout while a tool call is still running. */
 export const SUBAGENT_TOOL_EXECUTION_TIMEOUT_MS_ENV = "TALLOW_SUBAGENT_TOOL_EXECUTION_TIMEOUT_MS";
 
+/** Env var overriding the total wall-clock timeout per foreground subagent. */
+export const SUBAGENT_WALL_CLOCK_TIMEOUT_MS_ENV = "TALLOW_SUBAGENT_WALL_CLOCK_TIMEOUT_MS";
+
 /** Env var overriding the SIGTERM → SIGKILL grace window for stalled workers. */
 export const SUBAGENT_WATCHDOG_KILL_GRACE_MS_ENV = "TALLOW_SUBAGENT_WATCHDOG_KILL_GRACE_MS";
 
+/** Env var overriding the total wall-clock timeout for the stalled-worker retry phase. */
+export const SUBAGENT_RETRY_PHASE_TIMEOUT_MS_ENV = "TALLOW_SUBAGENT_RETRY_PHASE_TIMEOUT_MS";
+
 /** Default watchdog thresholds used by foreground subagents in runSingleAgent. */
 export const FOREGROUND_WATCHDOG_THRESHOLDS: ForegroundWatchdogThresholds = {
-	inactivityTimeoutMs: 180_000,
+	inactivityTimeoutMs: 120_000, // 2 min without any heartbeat event
 	killGraceMs: 5_000,
-	startupTimeoutMs: 60_000,
-	toolExecutionTimeoutMs: 600_000,
+	startupTimeoutMs: 30_000, // 30s to emit first event
+	toolExecutionTimeoutMs: 300_000, // 5 min per tool call (was 10 min)
+	wallClockTimeoutMs: 480_000, // 8 min total (was 15 min)
 };
 
+/**
+ * Default total wall-clock timeout for the entire stalled-worker retry phase.
+ *
+ * Without a cap, N stalled retries × per-worker watchdog timeout can block
+ * the parent for 30+ minutes. This limits the total retry phase so the
+ * parent agent can recover sooner.
+ */
+export const DEFAULT_RETRY_PHASE_TIMEOUT_MS = 180_000; // 3 minutes
+
 /** How often the foreground watchdog checks for stalled subagents. */
 const FOREGROUND_WATCHDOG_CHECK_INTERVAL_MS = 500;
 
@@ -532,9 +549,25 @@ export function resolveForegroundWatchdogThresholds(
 		toolExecutionTimeoutMs:
 			parseTimeoutOverrideMs(env[SUBAGENT_TOOL_EXECUTION_TIMEOUT_MS_ENV]) ??
 			FOREGROUND_WATCHDOG_THRESHOLDS.toolExecutionTimeoutMs,
+		wallClockTimeoutMs:
+			parseTimeoutOverrideMs(env[SUBAGENT_WALL_CLOCK_TIMEOUT_MS_ENV]) ??
+			FOREGROUND_WATCHDOG_THRESHOLDS.wallClockTimeoutMs,
 	};
 }
 
+/**
+ * Resolve the effective retry-phase wall-clock timeout from env overrides.
+ *
+ * @param env - Environment lookup map
+ * @returns Timeout in milliseconds for the entire stalled-worker retry phase
+ */
+export function resolveRetryPhaseTimeoutMs(env: EnvLookup = process.env): number {
+	return (
+		parseTimeoutOverrideMs(env[SUBAGENT_RETRY_PHASE_TIMEOUT_MS_ENV]) ??
+		DEFAULT_RETRY_PHASE_TIMEOUT_MS
+	);
+}
+
 /**
  * Return whether an event type counts as watchdog progress.
  * @param eventType - Raw child-process event type
@@ -619,6 +652,18 @@ export function evaluateWatchdogStatus(
 	nowMs: number,
 	thresholds: ForegroundWatchdogThresholds
 ): WatchdogStatus {
+	// Wall-clock timeout: hard cap on total execution time, regardless of activity.
+	// Catches "slow but active" agents that keep making tool calls without finishing.
+	const totalElapsedMs = nowMs - state.startedAtMs;
+	if (totalElapsedMs >= thresholds.wallClockTimeoutMs) {
+		return {
+			elapsedMs: totalElapsedMs,
+			kind: "stalled",
+			phase: "wall_clock",
+			timeoutMs: thresholds.wallClockTimeoutMs,
+		};
+	}
+
 	if (state.lastHeartbeatAtMs === null) {
 		const startupElapsedMs = nowMs - state.startedAtMs;
 		if (startupElapsedMs >= thresholds.startupTimeoutMs) {
@@ -655,6 +700,15 @@ export function createStalledSubagentErrorMessage(
 	stalledStatus: Extract<WatchdogStatus, { kind: "stalled" }>
 ): string {
 	const timeoutSeconds = Math.max(1, Math.round(stalledStatus.timeoutMs / 1000));
+	const timeoutMinutes = Math.round(timeoutSeconds / 60);
+	if (stalledStatus.phase === "wall_clock") {
+		return (
+			`Subagent terminated after ${timeoutMinutes}m wall-clock timeout. ` +
+			"The agent was still active but exceeded the maximum allowed execution time. " +
+			"Action: break the task into smaller pieces, or increase " +
+			"TALLOW_SUBAGENT_WALL_CLOCK_TIMEOUT_MS for legitimately long work."
+		);
+	}
 	const phaseDescription =
 		stalledStatus.phase === "startup"
 			? "no startup activity was received"
@@ -743,6 +797,54 @@ export function terminateProcessWithGrace(
 /** Callback for streaming partial results during subagent execution. */
 export type OnUpdateCallback = (partial: AgentToolResult<SubagentDetails>) => void;
 
+// ── Subprocess Arg Construction ──────────────────────────────────────────────
+
+/** Options for building subprocess CLI arguments. */
+export interface SubprocessArgsOptions {
+	/** Session file path for persistent teammates (omit for --no-session). */
+	session?: string;
+	/** Provider-qualified model display name (e.g. "anthropic/claude-sonnet-4-6"). */
+	modelDisplayName?: string;
+	/** Effective tool allowlist (already filtered by denylist). */
+	tools?: string[];
+	/** Skill names to pass via --skill flags. */
+	skills?: string[];
+	/** Path to temp file containing the system prompt. */
+	systemPromptPath?: string;
+	/** Task text (will be prefixed with "Task: "). */
+	task: string;
+}
+
+/**
+ * Build the CLI argument array for a subagent child process.
+ *
+ * **Invariant:** `-p <task>` is always the last pair in the array.
+ * Commander consumes the next token after `-p` as its required `<prompt>`
+ * value. Placing `-p` before other flags (e.g. `--no-session`) causes
+ * Commander to swallow the flag as the prompt text, leaving the real
+ * task as a stray positional argument.
+ *
+ * @param opts - Subprocess argument options
+ * @returns CLI argument array safe for child_process.spawn
+ */
+export function buildSubprocessArgs(opts: SubprocessArgsOptions): string[] {
+	const args: string[] = opts.session
+		? ["--mode", "json", "--session", opts.session]
+		: ["--mode", "json", "--no-session"];
+
+	if (opts.modelDisplayName) args.push("--model", opts.modelDisplayName);
+	if (opts.tools && opts.tools.length > 0) args.push("--tools", opts.tools.join(","));
+	if (opts.skills && opts.skills.length > 0) {
+		for (const skill of opts.skills) args.push("--skill", skill);
+	}
+	if (opts.systemPromptPath) args.push("--append-system-prompt", opts.systemPromptPath);
+
+	// CRITICAL: -p must be last — see JSDoc above.
+	args.push("-p", `Task: ${opts.task}`);
+
+	return args;
+}
+
 // ── Background Spawning ──────────────────────────────────────────────────────
 
 /**
@@ -813,18 +915,6 @@ export async function spawnBackgroundSubagent(
 	const agent = { ...resolved.agent, model: routing.model.id };
 	const agentSource = resolved.resolution === "ephemeral" ? ("ephemeral" as const) : agent.source;
 
-	const args: string[] = session
-		? ["--mode", "json", "-p", "--session", session]
-		: ["--mode", "json", "-p", "--no-session"];
-	// Use provider-qualified name (e.g. "openai-codex/gpt-5.1") so the child process
-	// resolves to the exact provider the router selected, not just the first match.
-	if (agent.model) args.push("--model", routing.model.displayName);
-	const effectiveTools = computeEffectiveTools(agent.tools, agent.disallowedTools);
-	if (effectiveTools && effectiveTools.length > 0) args.push("--tools", effectiveTools.join(","));
-	if (agent.skills && agent.skills.length > 0) {
-		for (const skill of agent.skills) args.push("--skill", skill);
-	}
-
 	let tmpPromptDir: string | undefined;
 	let tmpPromptPath: string | undefined;
 
@@ -839,7 +929,6 @@ export async function spawnBackgroundSubagent(
 		const tmp = writePromptToTempFile(agent.name, systemPrompt);
 		tmpPromptDir = tmp.dir;
 		tmpPromptPath = tmp.filePath;
-		args.push("--append-system-prompt", tmpPromptPath);
 	}
 
 	let expandedTask: string;
@@ -850,7 +939,16 @@ export async function spawnBackgroundSubagent(
 		const reason = error instanceof Error ? error.message : String(error);
 		return `Failed to expand task references for ${agentName}: ${reason}`;
 	}
-	args.push(`Task: ${expandedTask}`);
+
+	const effectiveTools = computeEffectiveTools(agent.tools, agent.disallowedTools);
+	const args = buildSubprocessArgs({
+		session,
+		modelDisplayName: agent.model ? routing.model.displayName : undefined,
+		tools: effectiveTools && effectiveTools.length > 0 ? effectiveTools : undefined,
+		skills: agent.skills && agent.skills.length > 0 ? agent.skills : undefined,
+		systemPromptPath: tmpPromptPath,
+		task: expandedTask,
+	});
 
 	const childEnv: Record<string, string> = { ...process.env, PI_IS_SUBAGENT: "1" } as Record<
 		string,
@@ -1236,18 +1334,6 @@ export async function runSingleAgent(
 		background: false,
 	} satisfies SubagentStartEvent);
 
-	const args: string[] = session
-		? ["--mode", "json", "-p", "--session", session]
-		: ["--mode", "json", "-p", "--no-session"];
-	// Use provider-qualified name so the child process resolves to the exact provider.
-	if (agent.model) args.push("--model", routing.model.displayName);
-	const fgEffectiveTools = computeEffectiveTools(agent.tools, agent.disallowedTools);
-	if (fgEffectiveTools && fgEffectiveTools.length > 0)
-		args.push("--tools", fgEffectiveTools.join(","));
-	if (agent.skills && agent.skills.length > 0) {
-		for (const skill of agent.skills) args.push("--skill", skill);
-	}
-
 	let tmpPromptDir: string | null = null;
 	let tmpPromptPath: string | null = null;
 
@@ -1290,6 +1376,7 @@ export async function runSingleAgent(
 		},
 		model: agent.model,
 		step,
+		startTime: Date.now(),
 	};
 
 	/** Timestamp of the last emitted update, used for throttling. */
@@ -1327,11 +1414,18 @@ export async function runSingleAgent(
 			const tmp = writePromptToTempFile(agent.name, fgSystemPrompt);
 			tmpPromptDir = tmp.dir;
 			tmpPromptPath = tmp.filePath;
-			args.push("--append-system-prompt", tmpPromptPath);
 		}
 
 		const expandedTask = await expandFileReferences(task, effectiveCwd);
-		args.push(`Task: ${expandedTask}`);
+		const fgEffectiveTools = computeEffectiveTools(agent.tools, agent.disallowedTools);
+		const args = buildSubprocessArgs({
+			session,
+			modelDisplayName: agent.model ? routing.model.displayName : undefined,
+			tools: fgEffectiveTools && fgEffectiveTools.length > 0 ? fgEffectiveTools : undefined,
+			skills: agent.skills && agent.skills.length > 0 ? agent.skills : undefined,
+			systemPromptPath: tmpPromptPath ?? undefined,
+			task: expandedTask,
+		});
 		let wasAborted = false;
 
 		const fgChildEnv: Record<string, string> = {