pi-subagents 0.30.0 → 0.31.0

package/src/runs/background/async-job-tracker.ts

@@ -26,6 +26,10 @@ interface AsyncJobTrackerOptions {
 	now?: () => number;
 }
 
+const CONTROL_EVENT_READ_CHUNK_BYTES = 64 * 1024;
+const MAX_CONTROL_EVENT_LINE_BYTES = 1024 * 1024;
+const CONTROL_EVENT_SCAN_WINDOW_BYTES = 2 * 1024 * 1024;
+
 export function createAsyncJobTracker(pi: Pick<ExtensionAPI, "events">, state: SubagentState, asyncDirRoot: string, options: AsyncJobTrackerOptions = {}): {
 	ensurePoller: () => void;
 	handleStarted: (data: unknown) => void;
@@ -68,25 +72,24 @@ export function createAsyncJobTracker(pi: Pick<ExtensionAPI, "events">, state: S
 		}
 		try {
 			const stat = fs.fstatSync(fd);
-			const cursor = stat.size < (job.controlEventCursor ?? 0) ? 0 : (job.controlEventCursor ?? 0);
+			const savedCursor = job.controlEventCursor;
+			let cursor = stat.size < (savedCursor ?? 0) ? 0 : (savedCursor ?? 0);
+			const startedFromTail = savedCursor === undefined && stat.size > CONTROL_EVENT_SCAN_WINDOW_BYTES;
+			if (startedFromTail) cursor = stat.size - CONTROL_EVENT_SCAN_WINDOW_BYTES;
 			if (stat.size <= cursor) return;
-			const buffer = Buffer.alloc(stat.size - cursor);
-			fs.readSync(fd, buffer, 0, buffer.length, cursor);
-			const lastNewline = buffer.lastIndexOf(0x0a);
-			if (lastNewline === -1) return;
-			job.controlEventCursor = cursor + lastNewline + 1;
-			for (const line of buffer.subarray(0, lastNewline).toString("utf-8").split("\n")) {
-				if (!line.trim()) continue;
+			const scanEnd = Math.min(stat.size, cursor + CONTROL_EVENT_SCAN_WINDOW_BYTES);
+			const handleLine = (line: string) => {
+				if (!line.trim()) return;
 				let parsed: unknown;
 				try {
 					parsed = JSON.parse(line);
 				} catch (error) {
 					console.error(`Ignoring malformed async control event in '${eventsPath}':`, error);
-					continue;
+					return;
 				}
-				if (!parsed || typeof parsed !== "object" || (parsed as { type?: unknown }).type !== "subagent.control") continue;
+				if (!parsed || typeof parsed !== "object" || (parsed as { type?: unknown }).type !== "subagent.control") return;
 				const record = parsed as { event?: ControlEvent; channels?: string[]; childIntercomTarget?: string; noticeText?: string; intercom?: { to?: string; message?: string } };
-				if (!record.event || !Array.isArray(record.channels)) continue;
+				if (!record.event || !Array.isArray(record.channels)) return;
 				const payload = {
 					event: record.event,
 					source: "async" as const,
@@ -104,7 +107,48 @@ export function createAsyncJobTracker(pi: Pick<ExtensionAPI, "events">, state: S
 						message: record.intercom.message,
 					});
 				}
+			};
+			let readCursor = cursor;
+			let lastCompleteCursor = cursor;
+			let lineParts: Buffer[] = [];
+			let lineBytes = 0;
+			let skippingOversizedLine = startedFromTail;
+			const appendLineSegment = (segment: Buffer) => {
+				if (segment.length === 0 || skippingOversizedLine) return;
+				if (lineBytes + segment.length > MAX_CONTROL_EVENT_LINE_BYTES) {
+					lineParts = [];
+					lineBytes = 0;
+					skippingOversizedLine = true;
+					return;
+				}
+				lineParts.push(segment);
+				lineBytes += segment.length;
+			};
+			while (readCursor < scanEnd) {
+				const toRead = Math.min(CONTROL_EVENT_READ_CHUNK_BYTES, scanEnd - readCursor);
+				const buffer = Buffer.alloc(toRead);
+				const bytesRead = fs.readSync(fd, buffer, 0, toRead, readCursor);
+				if (bytesRead <= 0) break;
+				const chunk = bytesRead === buffer.length ? buffer : buffer.subarray(0, bytesRead);
+				let lineStart = 0;
+				for (let index = 0; index < chunk.length; index++) {
+					if (chunk[index] !== 0x0a) continue;
+					appendLineSegment(chunk.subarray(lineStart, index));
+					if (!skippingOversizedLine && lineBytes > 0) {
+						handleLine(Buffer.concat(lineParts, lineBytes).toString("utf-8"));
+					}
+					lineParts = [];
+					lineBytes = 0;
+					skippingOversizedLine = false;
+					lastCompleteCursor = readCursor + index + 1;
+					lineStart = index + 1;
+				}
+				appendLineSegment(chunk.subarray(lineStart));
+				readCursor += bytesRead;
+				if (skippingOversizedLine) job.controlEventCursor = readCursor;
 			}
+			if (lastCompleteCursor > cursor) job.controlEventCursor = lastCompleteCursor;
+			else if (scanEnd < stat.size || startedFromTail) job.controlEventCursor = scanEnd;
 		} catch (error) {
 			console.error(`Failed to read async control events for '${job.asyncDir}':`, error);
 		} finally {
@@ -261,6 +305,7 @@ export function createAsyncJobTracker(pi: Pick<ExtensionAPI, "events">, state: S
 			activeParallelGroup: Boolean(firstGroupCount && firstGroupCount > 0),
 			startedAt: now,
 			updatedAt: now,
+			controlEventCursor: 0,
 		});
 		ensurePoller();
 		if (state.lastUiContext) {

package/src/runs/background/result-watcher.ts

@@ -21,7 +21,7 @@ import { projectNestedRegistryForRoot, sanitizeSummary } from "../shared/nested-
 const WATCHER_RESTART_DELAY_MS = 3000;
 const POLL_INTERVAL_MS = 3000;
 
-type ResultWatcherFs = Pick<typeof fs, "existsSync" | "readFileSync" | "unlinkSync" | "readdirSync" | "mkdirSync" | "watch">;
+type ResultWatcherFs = Pick<typeof fs, "existsSync" | "readFileSync" | "unlinkSync" | "readdirSync" | "mkdirSync" | "realpathSync" | "watch">;
 
 type ResultWatcherTimers = {
 	setTimeout: typeof setTimeout;
@@ -91,6 +91,14 @@ function shouldFallBackToPolling(error: unknown): boolean {
 	return code === "EMFILE" || code === "ENOSPC";
 }
 
+function resolveNativeWatchDir(fsApi: ResultWatcherFs, resultsDir: string): string {
+	try {
+		return fsApi.realpathSync.native(resultsDir);
+	} catch {
+		return resultsDir;
+	}
+}
+
 export function createResultWatcher(
 	pi: { events: IntercomEventBus },
 	state: SubagentState,
@@ -264,7 +272,8 @@ export function createResultWatcher(
 			state.watcherRestartTimer = null;
 		}
 		try {
-			state.watcher = fsApi.watch(resultsDir, (ev, file) => {
+			const watchDir = resolveNativeWatchDir(fsApi, resultsDir);
+			state.watcher = fsApi.watch(watchDir, (ev, file) => {
 				if (ev !== "rename" || !file) return;
 				const fileName = file.toString();
 				if (!fileName.endsWith(".json")) return;

package/src/runs/background/stale-run-reconciler.ts

@@ -48,9 +48,14 @@ function isNotFoundError(error: unknown): boolean {
 		&& (error as NodeJS.ErrnoException).code === "ENOENT";
 }
 
-function appendJsonl(filePath: string, payload: object): void {
-	fs.mkdirSync(path.dirname(filePath), { recursive: true });
-	fs.appendFileSync(filePath, `${JSON.stringify(payload)}\n`, "utf-8");
+function appendJsonlBestEffort(filePath: string, payload: object): void {
+	try {
+		fs.mkdirSync(path.dirname(filePath), { recursive: true });
+		fs.appendFileSync(filePath, `${JSON.stringify(payload)}\n`, "utf-8");
+	} catch {
+		// Repair status/result writes are the important path. A broken or full
+		// diagnostic event log must not make stale-run reconciliation fail.
+	}
 }
 
 function readStatusFile(asyncDir: string): AsyncStatus | null {
@@ -223,7 +228,7 @@ function writeFailedRepair(asyncDir: string, status: AsyncStatus, resultPath: st
 	const repair = buildFailedRepair(status, asyncDir, now, reason);
 	writeAtomicJson(resultPath, repair.result);
 	writeAtomicJson(path.join(asyncDir, "status.json"), repair.status);
-	appendJsonl(path.join(asyncDir, "events.jsonl"), {
+	appendJsonlBestEffort(path.join(asyncDir, "events.jsonl"), {
 		type: "subagent.run.repaired_stale",
 		ts: now,
 		runId: repair.status.runId,

package/src/runs/background/subagent-runner.ts

@@ -4,7 +4,7 @@ import * as path from "node:path";
 import { pathToFileURL } from "node:url";
 import type { Message } from "@earendil-works/pi-ai";
 import { writeAtomicJson } from "../../shared/atomic-json.ts";
-import { appendJsonl, getArtifactPaths } from "../../shared/artifacts.ts";
+import { appendJsonl as appendRawJsonl, getArtifactPaths } from "../../shared/artifacts.ts";
 import { PI_CODING_AGENT_PACKAGE, getPiSpawnCommand, resolveInstalledPiPackageRoot } from "../shared/pi-spawn.ts";
 import { captureSingleOutputSnapshot, finalizeSingleOutput, formatSavedOutputReference, resolveSingleOutput, type SingleOutputSnapshot } from "../shared/single-output.ts";
 import {
@@ -131,6 +131,79 @@ interface StepResult {
 }
 
 const ASYNC_INTERRUPT_SIGNAL: NodeJS.Signals = process.platform === "win32" ? "SIGBREAK" : "SIGUSR2";
+const DEFAULT_MAX_ASYNC_EVENTS_BYTES = 50 * 1024 * 1024;
+const ASYNC_EVENTS_MAX_BYTES_ENV = "PI_SUBAGENT_ASYNC_EVENTS_MAX_BYTES";
+const TRUNCATED_EVENT_TYPE = "subagent.events.truncated";
+const TRUNCATION_MARKER_RESERVE_BYTES = 512;
+
+interface AsyncEventLogState {
+	bytes: number;
+	diagnosticsTruncated: boolean;
+}
+
+const asyncEventLogStates = new Map<string, AsyncEventLogState>();
+
+function maxAsyncEventsBytes(): number {
+	const raw = process.env[ASYNC_EVENTS_MAX_BYTES_ENV];
+	if (!raw) return DEFAULT_MAX_ASYNC_EVENTS_BYTES;
+	const parsed = Number(raw);
+	if (!Number.isFinite(parsed) || parsed < 0) return DEFAULT_MAX_ASYNC_EVENTS_BYTES;
+	return Math.floor(parsed);
+}
+
+function eventLogState(filePath: string): AsyncEventLogState {
+	let state = asyncEventLogStates.get(filePath);
+	if (state) return state;
+	let bytes = 0;
+	try {
+		bytes = fs.statSync(filePath).size;
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code !== "ENOENT") {
+			// Diagnostic event accounting is best-effort; writes below are also safe.
+		}
+	}
+	state = { bytes, diagnosticsTruncated: false };
+	asyncEventLogStates.set(filePath, state);
+	return state;
+}
+
+function appendJsonl(filePath: string, line: string): void {
+	try {
+		appendRawJsonl(filePath, line);
+		const state = asyncEventLogStates.get(filePath);
+		if (state) state.bytes += Buffer.byteLength(`${line}\n`, "utf-8");
+	} catch {
+		// Async event logging is diagnostic and must not fail the run.
+	}
+}
+
+function appendDiagnosticJsonl(filePath: string, line: string, droppedEventType?: string): void {
+	if (!line.trim()) return;
+	const state = eventLogState(filePath);
+	if (state.diagnosticsTruncated) return;
+	const maxBytes = maxAsyncEventsBytes();
+	const chunkBytes = Buffer.byteLength(`${line}\n`, "utf-8");
+	const diagnosticBudget = Math.max(0, maxBytes - TRUNCATION_MARKER_RESERVE_BYTES);
+	if (state.bytes + chunkBytes <= diagnosticBudget) {
+		appendJsonl(filePath, line);
+		return;
+	}
+
+	const marker = JSON.stringify({
+		type: TRUNCATED_EVENT_TYPE,
+		ts: Date.now(),
+		maxBytes,
+		droppedEventType,
+	});
+	if (state.bytes + Buffer.byteLength(`${marker}\n`, "utf-8") <= maxBytes) {
+		appendJsonl(filePath, marker);
+	}
+	state.diagnosticsTruncated = true;
+}
+
+function shouldPersistChildEvent(event: Record<string, unknown>): boolean {
+	return event.type !== "message_update";
+}
 
 function findLatestSessionFile(sessionDir: string): string | null {
 	try {
@@ -274,14 +347,15 @@ function runPiStreaming(
 
 		const appendChildEvent = (event: Record<string, unknown>) => {
 			if (!childEventContext) return;
-			appendJsonl(childEventContext.eventsPath, JSON.stringify({
+			if (!shouldPersistChildEvent(event)) return;
+			appendDiagnosticJsonl(childEventContext.eventsPath, JSON.stringify({
 				...event,
 				subagentSource: "child",
 				subagentRunId: childEventContext.runId,
 				subagentStepIndex: childEventContext.stepIndex,
 				subagentAgent: childEventContext.agent,
 				observedAt: Date.now(),
-			}));
+			}), typeof event.type === "string" ? event.type : undefined);
 		};
 
 		const appendChildLine = (type: "subagent.child.stdout" | "subagent.child.stderr", line: string) => {
@@ -676,6 +750,7 @@ async function runSingleStep(
 			}
 		}
 		const { args, env, tempDir } = buildPiArgs({
+			parentSessionId: step.parentSessionId,
 			baseArgs: ["--mode", "json", "-p"],
 			task,
 			sessionEnabled,
@@ -684,6 +759,7 @@ async function runSingleStep(
 			model: candidate,
 			inheritProjectContext: step.inheritProjectContext,
 			inheritSkills: step.inheritSkills,
+			requireReadTool: Boolean(step.skills?.length),
 			tools: step.tools,
 			extensions: step.extensions,
 			subagentOnlyExtensions: step.subagentOnlyExtensions,

package/src/runs/foreground/chain-execution.ts

@@ -102,6 +102,7 @@ interface ParallelChainRunInput {
 	globalTaskIndex: number;
 	sessionDirForIndex: (idx?: number) => string | undefined;
 	sessionFileForIndex?: (idx?: number) => string | undefined;
+	sessionFileForTask?: (agentName: string, idx?: number) => string | undefined;
 	shareEnabled: boolean;
 	artifactConfig: ArtifactConfig;
 	artifactsDir: string;
@@ -136,6 +137,8 @@ interface ParallelChainRunInput {
 	worktreeSetup?: WorktreeSetup;
 	maxSubagentDepth: number;
 	nestedRoute?: NestedRouteInfo;
+	timeoutMs?: number;
+	deadlineAt?: number;
 }
 
 function buildChainExecutionDetails(input: ChainExecutionDetailsInput): Details {
@@ -266,6 +269,7 @@ async function runParallelChainTasks(input: ParallelChainRunInput): Promise<Sing
 				? createStructuredOutputRuntime(task.outputSchema, path.join(input.chainDir, "structured-output"))
 				: undefined;
 			const result = await runSync(input.ctx.cwd, input.agents, task.agent, taskStr, {
+				parentSessionId: input.ctx.sessionManager.getSessionId() ?? undefined,
 				cwd: taskCwd,
 				signal: input.signal,
 				interruptSignal: interruptController.signal,
@@ -274,7 +278,8 @@ async function runParallelChainTasks(input: ParallelChainRunInput): Promise<Sing
 				runId: input.runId,
 				index: input.globalTaskIndex + taskIndex,
 				sessionDir: input.sessionDirForIndex(input.globalTaskIndex + taskIndex),
-				sessionFile: input.sessionFileForIndex?.(input.globalTaskIndex + taskIndex),
+				sessionFile: input.sessionFileForTask?.(task.agent, input.globalTaskIndex + taskIndex)
+					?? input.sessionFileForIndex?.(input.globalTaskIndex + taskIndex),
 				share: input.shareEnabled,
 				artifactsDir: input.artifactConfig.enabled ? input.artifactsDir : undefined,
 				artifactConfig: input.artifactConfig,
@@ -293,6 +298,8 @@ async function runParallelChainTasks(input: ParallelChainRunInput): Promise<Sing
 				structuredOutput: structuredRuntime,
 				acceptance: task.acceptance,
 				acceptanceContext: { mode: "chain" },
+				timeoutMs: input.timeoutMs,
+				deadlineAt: input.deadlineAt,
 				onUpdate: input.onUpdate
 					? (progressUpdate) => {
 						const stepResults = progressUpdate.details?.results || [];
@@ -365,6 +372,7 @@ interface ChainExecutionParams {
 	shareEnabled: boolean;
 	sessionDirForIndex: (idx?: number) => string | undefined;
 	sessionFileForIndex?: (idx?: number) => string | undefined;
+	sessionFileForTask?: (agentName: string, idx?: number) => string | undefined;
 	artifactsDir: string;
 	artifactConfig: ArtifactConfig;
 	includeProgress?: boolean;
@@ -395,6 +403,8 @@ interface ChainExecutionParams {
 	nestedRoute?: NestedRouteInfo;
 	worktreeSetupHook?: string;
 	worktreeSetupHookTimeoutMs?: number;
+	timeoutMs?: number;
+	deadlineAt?: number;
 }
 
 interface ChainExecutionResult {
@@ -422,6 +432,7 @@ export async function executeChain(params: ChainExecutionParams): Promise<ChainE
 		shareEnabled,
 		sessionDirForIndex,
 		sessionFileForIndex,
+		sessionFileForTask,
 		artifactsDir,
 		artifactConfig,
 		includeProgress,
@@ -584,6 +595,7 @@ export async function executeChain(params: ChainExecutionParams): Promise<ChainE
 		tuiBehaviorOverrides = result.behaviorOverrides;
 	}
 
+	const deadlineAt = params.deadlineAt ?? (params.timeoutMs !== undefined ? Date.now() + params.timeoutMs : undefined);
 	let prev = "";
 	let globalTaskIndex = 0;
 	let progressCreated = false;
@@ -649,6 +661,7 @@ export async function executeChain(params: ChainExecutionParams): Promise<ChainE
 					globalTaskIndex,
 					sessionDirForIndex,
 					sessionFileForIndex,
+					sessionFileForTask,
 					shareEnabled,
 					artifactConfig,
 					artifactsDir,
@@ -670,6 +683,8 @@ export async function executeChain(params: ChainExecutionParams): Promise<ChainE
 					nestedRoute: params.nestedRoute,
 					worktreeSetup,
 					maxSubagentDepth: params.maxSubagentDepth,
+					timeoutMs: params.timeoutMs,
+					deadlineAt,
 				});
 				globalTaskIndex += step.parallel.length;
 
@@ -739,6 +754,7 @@ export async function executeChain(params: ChainExecutionParams): Promise<ChainE
 						output: getSingleResultOutput(result),
 						exitCode: result.exitCode,
 						error: result.error,
+						timedOut: result.timedOut,
 						outputTargetPath,
 						outputTargetExists: outputTargetPath ? fs.existsSync(outputTargetPath) : undefined,
 					};
@@ -855,6 +871,7 @@ export async function executeChain(params: ChainExecutionParams): Promise<ChainE
 				globalTaskIndex,
 				sessionDirForIndex,
 				sessionFileForIndex,
+				sessionFileForTask,
 				shareEnabled,
 				artifactConfig,
 				artifactsDir,
@@ -875,6 +892,8 @@ export async function executeChain(params: ChainExecutionParams): Promise<ChainE
 				foregroundControl,
 				nestedRoute: params.nestedRoute,
 				maxSubagentDepth: params.maxSubagentDepth,
+				timeoutMs: params.timeoutMs,
+				deadlineAt,
 			});
 			globalTaskIndex += dynamicParallelStep.parallel.length;
 
@@ -970,6 +989,7 @@ export async function executeChain(params: ChainExecutionParams): Promise<ChainE
 				output: getSingleResultOutput(result),
 				exitCode: result.exitCode,
 				error: result.error,
+				timedOut: result.timedOut,
 			}));
 			prev = aggregateParallelOutputs(taskResults, (i, agent) => `=== Dynamic Item ${i + 1} (${agent}, key ${materialized.items[i]?.key ?? i}) ===`);
 		} else {
@@ -1054,6 +1074,7 @@ export async function executeChain(params: ChainExecutionParams): Promise<ChainE
 				? createStructuredOutputRuntime(seqStep.outputSchema, path.join(chainDir, "structured-output"))
 				: undefined;
 			const r = await runSync(ctx.cwd, agents, seqStep.agent, stepTask, {
+				parentSessionId: ctx.sessionManager.getSessionId() ?? undefined,
 				cwd: resolveChildCwd(cwd ?? ctx.cwd, seqStep.cwd),
 				signal,
 				interruptSignal: interruptController.signal,
@@ -1062,7 +1083,8 @@ export async function executeChain(params: ChainExecutionParams): Promise<ChainE
 				runId,
 				index: globalTaskIndex,
 				sessionDir: sessionDirForIndex(globalTaskIndex),
-				sessionFile: sessionFileForIndex?.(globalTaskIndex),
+				sessionFile: sessionFileForTask?.(seqStep.agent, globalTaskIndex)
+					?? sessionFileForIndex?.(globalTaskIndex),
 				share: shareEnabled,
 				artifactsDir: artifactConfig.enabled ? artifactsDir : undefined,
 				artifactConfig,
@@ -1081,6 +1103,8 @@ export async function executeChain(params: ChainExecutionParams): Promise<ChainE
 				structuredOutput: structuredRuntime,
 				acceptance: seqStep.acceptance,
 				acceptanceContext: { mode: "chain" },
+				timeoutMs: params.timeoutMs,
+				deadlineAt,
 				onUpdate: onUpdate
 					? (p) => {
 						const stepResults = p.details?.results || [];

package/src/runs/foreground/execution.ts

@@ -23,6 +23,8 @@ import {
 	DEFAULT_MAX_OUTPUT,
 	INTERCOM_DETACH_REQUEST_EVENT,
 	INTERCOM_DETACH_RESPONSE_EVENT,
+	type AcceptanceLedger,
+	type ResolvedAcceptanceConfig,
 	truncateOutput,
 	getSubagentDepthEnv,
 } from "../../shared/types.ts";
@@ -47,7 +49,7 @@ import { createJsonlWriter } from "../../shared/jsonl-writer.ts";
 import { attachPostExitStdioGuard, trySignalChild } from "../../shared/post-exit-stdio-guard.ts";
 import { applyThinkingSuffix, buildPiArgs, cleanupTempDir } from "../shared/pi-args.ts";
 import { readStructuredOutput } from "../shared/structured-output.ts";
-import { captureSingleOutputSnapshot, formatSavedOutputReference, resolveSingleOutput, validateFileOnlyOutputMode, type SingleOutputSnapshot } from "../shared/single-output.ts";
+import { captureSingleOutputSnapshot, formatSavedOutputReference, injectOutputPathSystemPrompt, resolveSingleOutput, validateFileOnlyOutputMode, type SingleOutputSnapshot } from "../shared/single-output.ts";
 import {
 	buildModelCandidates,
 	formatModelAttemptNote,
@@ -82,6 +84,34 @@ function sumUsage(target: Usage, source: Usage): void {
 	target.turns += source.turns;
 }
 
+function formatTimeoutMessage(timeoutMs: number): string {
+	return `Subagent timed out after ${timeoutMs}ms.`;
+}
+
+function resolveAttemptTimeout(options: RunSyncOptions): { timeoutMs: number; remainingMs: number; message: string } | undefined {
+	if (options.timeoutMs === undefined) return undefined;
+	const deadlineAt = options.deadlineAt ?? Date.now() + options.timeoutMs;
+	return {
+		timeoutMs: options.timeoutMs,
+		remainingMs: Math.max(0, deadlineAt - Date.now()),
+		message: formatTimeoutMessage(options.timeoutMs),
+	};
+}
+
+function buildTimedOutAcceptanceLedger(acceptance: ResolvedAcceptanceConfig): AcceptanceLedger {
+	return {
+		status: acceptance.level === "none" ? "not-required" : "rejected",
+		explicit: acceptance.explicit,
+		effectiveAcceptance: acceptance,
+		inferredReason: acceptance.inferredReason,
+		criteria: acceptance.criteria,
+		runtimeChecks: acceptance.level === "none"
+			? []
+			: [{ id: "timeout", status: "failed", message: "Acceptance was not evaluated because the subagent timed out." }],
+		verifyRuns: [],
+	};
+}
+
 function appendRecentOutput(progress: AgentProgress, lines: string[]): void {
 	if (lines.length === 0) return;
 	progress.recentOutput.push(...lines.filter((line) => line.trim()));
@@ -162,6 +192,7 @@ async function runSingleAttempt(
 		systemPromptMode: agent.systemPromptMode,
 		inheritProjectContext: agent.inheritProjectContext,
 		inheritSkills: agent.inheritSkills,
+		requireReadTool: Boolean(shared.resolvedSkillNames?.length),
 		tools: agent.tools,
 		extensions: agent.extensions,
 		subagentOnlyExtensions: agent.subagentOnlyExtensions,
@@ -178,6 +209,7 @@ async function runSingleAttempt(
 		parentControlInbox: options.nestedRoute?.controlInbox,
 			parentRootRunId: options.nestedRoute?.rootRunId,
 			parentCapabilityToken: options.nestedRoute?.capabilityToken,
+			parentSessionId: options.parentSessionId,
 			structuredOutput: options.structuredOutput,
 		});
 
@@ -227,6 +259,21 @@ async function runSingleAttempt(
 		lastActivityAt: startTime,
 	};
 	result.progress = progress;
+	const attemptTimeout = resolveAttemptTimeout(options);
+	if (attemptTimeout?.remainingMs === 0) {
+		result.exitCode = 1;
+		result.timedOut = true;
+		result.error = attemptTimeout.message;
+		result.finalOutput = attemptTimeout.message;
+		progress.status = "failed";
+		progress.error = attemptTimeout.message;
+		result.progressSummary = {
+			toolCount: progress.toolCount,
+			tokens: progress.tokens,
+			durationMs: progress.durationMs,
+		};
+		return result;
+	}
 	const spawnEnv = { ...process.env, ...sharedEnv, ...getSubagentDepthEnv(options.maxSubagentDepth) };
 	let observedMutationAttempt = false;
 
@@ -248,6 +295,23 @@ async function runSingleAttempt(
 		let removeAbortListener: (() => void) | undefined;
 		let removeInterruptListener: (() => void) | undefined;
 		let activityTimer: NodeJS.Timeout | undefined;
+		let timeoutTimer: NodeJS.Timeout | undefined;
+		let timeoutTerminationTimer: NodeJS.Timeout | undefined;
+		let timeoutHardKillTimer: NodeJS.Timeout | undefined;
+		const clearTimeoutTimers = () => {
+			if (timeoutTimer) {
+				clearTimeout(timeoutTimer);
+				timeoutTimer = undefined;
+			}
+			if (timeoutTerminationTimer) {
+				clearTimeout(timeoutTerminationTimer);
+				timeoutTerminationTimer = undefined;
+			}
+			if (timeoutHardKillTimer) {
+				clearTimeout(timeoutHardKillTimer);
+				timeoutHardKillTimer = undefined;
+			}
+		};
 
 		const detachForIntercom = () => {
 			detached = true;
@@ -316,6 +380,7 @@ async function runSingleAttempt(
 			settled = true;
 			clearFinalDrainTimers();
 			clearStdioGuard();
+			clearTimeoutTimers();
 			if (activityTimer) {
 				clearInterval(activityTimer);
 				activityTimer = undefined;
@@ -429,7 +494,8 @@ async function runSingleAttempt(
 		const fireUpdate = () => {
 			if (!options.onUpdate || processClosed) return;
 			progress.durationMs = Date.now() - startTime;
-			emitUpdateSnapshot(getFinalOutput(result.messages) || "(running...)");
+			const output = result.timedOut && result.finalOutput ? result.finalOutput : getFinalOutput(result.messages);
+			emitUpdateSnapshot(output || "(running...)");
 		};
 
 		const processLine = (line: string) => {
@@ -555,6 +621,31 @@ async function runSingleAttempt(
 			activityTimer.unref?.();
 		}
 
+		if (attemptTimeout) {
+			timeoutTimer = setTimeout(() => {
+				if (processClosed || settled || detached || interruptedByControl) return;
+				result.timedOut = true;
+				result.error = attemptTimeout.message;
+				result.finalOutput = attemptTimeout.message;
+				progress.status = "failed";
+				progress.error = attemptTimeout.message;
+				progress.durationMs = Date.now() - startTime;
+				fireUpdate();
+				trySignalChild(proc, "SIGINT");
+				timeoutTerminationTimer = setTimeout(() => {
+					if (processClosed || settled || detached) return;
+					trySignalChild(proc, "SIGTERM");
+				}, 1000);
+				timeoutTerminationTimer.unref?.();
+				timeoutHardKillTimer = setTimeout(() => {
+					if (processClosed || settled || detached) return;
+					trySignalChild(proc, "SIGKILL");
+				}, 4000);
+				timeoutHardKillTimer.unref?.();
+			}, attemptTimeout.remainingMs);
+			timeoutTimer.unref?.();
+		}
+
 		let stderrBuf = "";
 
 		const clearStdioGuard = attachPostExitStdioGuard(proc, { idleMs: 2000, hardMs: 8000 });
@@ -625,7 +716,9 @@ async function runSingleAttempt(
 		if (options.interruptSignal) {
 			const interrupt = () => {
 				if (processClosed || detached || settled) return;
+				if (result.timedOut) return;
 				interruptedByControl = true;
+				clearTimeoutTimers();
 				progress.status = "running";
 				progress.durationMs = Date.now() - startTime;
 				result.interrupted = true;
@@ -710,8 +803,14 @@ async function runSingleAttempt(
 		durationMs: progress.durationMs,
 	};
 
-		const acceptanceOutput = getFinalOutput(result.messages);
-		let fullOutput = stripAcceptanceReport(acceptanceOutput);
+	const acceptanceOutput = getFinalOutput(result.messages);
+	let fullOutput = stripAcceptanceReport(acceptanceOutput);
+	if (result.timedOut) {
+		const timeoutMessage = formatTimeoutMessage(options.timeoutMs ?? 0);
+		fullOutput = fullOutput.trim()
+			? `${timeoutMessage}\n\nPartial output before timeout:\n${fullOutput}`
+			: timeoutMessage;
+	}
 	const completionGuard = result.exitCode === 0 && !result.error && agent.completionGuard !== false
 		? evaluateCompletionMutationGuard({
 			agent: agent.name,
@@ -835,6 +934,7 @@ export async function runSync(
 		const skillInjection = buildSkillInjection(resolvedSkills);
 		systemPrompt = systemPrompt ? `${systemPrompt}\n\n${skillInjection}` : skillInjection;
 	}
+	systemPrompt = injectOutputPathSystemPrompt(systemPrompt, options.outputPath);
 
 	const candidates = buildModelCandidates(
 		options.modelOverride ?? agent.model,
@@ -892,6 +992,9 @@ export async function runSync(
 			usage: { ...result.usage },
 		};
 		modelAttempts.push(attempt);
+		if (result.timedOut) {
+			break;
+		}
 		if (attemptSucceeded) {
 			break;
 		}
@@ -967,14 +1070,16 @@ export async function runSync(
 		if (sessionFile) result.sessionFile = sessionFile;
 	}
 
-		result.acceptance = await evaluateAcceptance({
+	result.acceptance = result.timedOut
+		? buildTimedOutAcceptanceLedger(effectiveAcceptance)
+		: await evaluateAcceptance({
 			acceptance: effectiveAcceptance,
 			output: acceptanceOutputByResult.get(result) ?? result.finalOutput ?? "",
 			cwd: options.cwd ?? runtimeCwd,
 		});
-		const acceptanceFailure = acceptanceFailureMessage(result.acceptance);
-		stripAcceptanceReportsFromMessages(result.messages);
-		if (acceptanceFailure && result.acceptance.explicit && result.exitCode === 0 && !result.detached && !result.interrupted) {
+	const acceptanceFailure = acceptanceFailureMessage(result.acceptance);
+	stripAcceptanceReportsFromMessages(result.messages);
+	if (acceptanceFailure && result.acceptance.explicit && result.exitCode === 0 && !result.detached && !result.interrupted && !result.timedOut) {
 		result.exitCode = 1;
 		result.error = result.error ? `${result.error}\n${acceptanceFailure}` : acceptanceFailure;
 		if (result.progress) {