pi-subagents 0.27.0 → 0.28.0

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

@@ -19,6 +19,7 @@ import {
 	type ModelAttempt,
 	type NestedRouteInfo,
 	type ResolvedControlConfig,
+	type ResourceLimitExceeded,
 	type SubagentRunMode,
 	type TokenUsage,
 	type Usage,
@@ -53,7 +54,7 @@ import { collectDynamicResults, DynamicFanoutError, materializeDynamicParallelSt
 import { nestedSummaryFromAsyncStatus, writeNestedEvent } from "../shared/nested-events.ts";
 import { formatModelAttemptNote, isRetryableModelFailure } from "../shared/model-fallback.ts";
 import { attachPostExitStdioGuard, trySignalChild } from "../../shared/post-exit-stdio-guard.ts";
-import { detectSubagentError, extractTextFromContent, extractToolArgsPreview, getFinalOutput } from "../../shared/utils.ts";
+import { detectSubagentError, extractTextFromContent, extractToolArgsPreview, formatResourceLimitExceeded, getFinalOutput } from "../../shared/utils.ts";
 import { evaluateCompletionMutationGuard, resolveCompletionPolicy } from "../shared/completion-guard.ts";
 import {
 	createMutatingFailureState,
@@ -140,6 +141,7 @@ interface StepResult {
 	structuredOutputPath?: string;
 	structuredOutputSchemaPath?: string;
 	acceptance?: AcceptanceLedger;
+	resourceLimitExceeded?: ResourceLimitExceeded;
 }
 
 const ASYNC_INTERRUPT_SIGNAL: NodeJS.Signals = process.platform === "win32" ? "SIGBREAK" : "SIGUSR2";
@@ -234,6 +236,7 @@ interface RunPiStreamingResult {
 	finalOutput: string;
 	interrupted?: boolean;
 	observedMutationAttempt?: boolean;
+	resourceLimitExceeded?: ResourceLimitExceeded;
 }
 
 function runPiStreaming(
@@ -247,6 +250,8 @@ function runPiStreaming(
 	childEventContext?: ChildEventContext,
 	registerInterrupt?: (interrupt: (() => void) | undefined) => void,
 	onChildEvent?: (event: ChildEvent) => void,
+	maxExecutionTimeMs?: number,
+	maxTokens?: number,
 ): Promise<RunPiStreamingResult> {
 	return new Promise((resolve) => {
 		const outputStream = fs.createWriteStream(outputFile, { flags: "w" });
@@ -270,7 +275,10 @@ function runPiStreaming(
 		let error: string | undefined;
 		let assistantError: string | undefined;
 		let interrupted = false;
+		let resourceLimitExceeded: ResourceLimitExceeded | undefined;
 		let observedMutationAttempt = false;
+		let resourceLimitTimer: NodeJS.Timeout | undefined;
+		let resourceLimitEscalationTimer: NodeJS.Timeout | undefined;
 		const rawStdoutLines: string[] = [];
 
 		const writeOutputLine = (line: string) => {
@@ -284,6 +292,19 @@ function runPiStreaming(
 			}
 		};
 
+		const triggerResourceLimit = (kind: ResourceLimitExceeded["kind"], limit: number, observed?: number) => {
+			if (settled || resourceLimitExceeded) return;
+			const message = formatResourceLimitExceeded({ agent: childEventContext?.agent ?? "subagent", kind, limit, observed });
+			resourceLimitExceeded = { kind, limit, ...(observed !== undefined ? { observed } : {}), message };
+			error = message;
+			writeOutputLine(message);
+			trySignalChild(child, "SIGINT");
+			resourceLimitEscalationTimer = setTimeout(() => {
+				if (!settled) trySignalChild(child, "SIGTERM");
+			}, 1000);
+			resourceLimitEscalationTimer.unref?.();
+		};
+
 		const appendChildEvent = (event: Record<string, unknown>) => {
 			if (!childEventContext) return;
 			appendJsonl(childEventContext.eventsPath, JSON.stringify({
@@ -338,6 +359,10 @@ function runPiStreaming(
 					usage.cacheRead += eventUsage.cacheRead ?? 0;
 					usage.cacheWrite += eventUsage.cacheWrite ?? 0;
 					usage.cost += eventUsage.cost?.total ?? 0;
+					const observedTokens = usage.input + usage.output;
+					if (maxTokens !== undefined && observedTokens >= maxTokens) {
+						triggerResourceLimit("maxTokens", maxTokens, observedTokens);
+					}
 				}
 				const stopReason = (event.message as { stopReason?: string }).stopReason;
 				const hasToolCall = Array.isArray(event.message.content)
@@ -373,6 +398,12 @@ function runPiStreaming(
 		let finalDrainTimer: NodeJS.Timeout | undefined;
 		let finalHardKillTimer: NodeJS.Timeout | undefined;
 		let settled = false;
+		if (maxExecutionTimeMs !== undefined) {
+			resourceLimitTimer = setTimeout(() => {
+				triggerResourceLimit("maxExecutionTimeMs", maxExecutionTimeMs);
+			}, maxExecutionTimeMs);
+			resourceLimitTimer.unref?.();
+		}
 		const clearStdioGuard = attachPostExitStdioGuard(child, { idleMs: 2000, hardMs: 8000 });
 		child.stdout.on("data", (chunk: Buffer) => {
 			const text = chunk.toString();
@@ -386,7 +417,7 @@ function runPiStreaming(
 			processStderrText(chunk.toString());
 		});
 		registerInterrupt?.(() => {
-			if (settled) return;
+			if (settled || resourceLimitExceeded) return;
 			interrupted = true;
 			if (!error) error = "Interrupted. Waiting for explicit next action.";
 			trySignalChild(child, "SIGINT");
@@ -403,6 +434,14 @@ function runPiStreaming(
 				clearTimeout(finalHardKillTimer);
 				finalHardKillTimer = undefined;
 			}
+			if (resourceLimitTimer) {
+				clearTimeout(resourceLimitTimer);
+				resourceLimitTimer = undefined;
+			}
+			if (resourceLimitEscalationTimer) {
+				clearTimeout(resourceLimitEscalationTimer);
+				resourceLimitEscalationTimer = undefined;
+			}
 		};
 		function startFinalDrain(): void {
 			if (childExited || finalDrainTimer || settled) return;
@@ -434,12 +473,12 @@ function runPiStreaming(
 			if (stdoutBuf.trim()) processStdoutLine(stdoutBuf);
 			if (stderrBuf.trim()) appendChildLine("subagent.child.stderr", stderrBuf);
 			outputStream.end();
-			const finalOutput = getFinalOutput(messages) || rawStdoutLines.join("\n").trim();
-			const finalError = error ?? assistantError;
+			const finalOutput = resourceLimitExceeded?.message ?? (getFinalOutput(messages) || rawStdoutLines.join("\n").trim());
+			const finalError = resourceLimitExceeded?.message ?? error ?? assistantError;
 			const forcedDrainAfterFinalSuccess = forcedTerminationSignal && cleanTerminalAssistantStopReceived && !finalError;
 			resolve({
 				stderr,
-				exitCode: interrupted || forcedDrainAfterFinalSuccess ? 0 : forcedTerminationSignal || signal ? (exitCode ?? 1) : exitCode,
+				exitCode: resourceLimitExceeded ? 1 : interrupted || forcedDrainAfterFinalSuccess ? 0 : forcedTerminationSignal || signal ? (exitCode ?? 1) : exitCode,
 				messages,
 				usage,
 				model,
@@ -447,6 +486,7 @@ function runPiStreaming(
 				finalOutput,
 				interrupted,
 				observedMutationAttempt,
+				resourceLimitExceeded,
 			});
 		});
 
@@ -456,9 +496,9 @@ function runPiStreaming(
 			clearDrainTimers();
 			clearStdioGuard();
 			outputStream.end();
-			const finalOutput = getFinalOutput(messages) || rawStdoutLines.join("\n").trim();
+			const finalOutput = resourceLimitExceeded?.message ?? (getFinalOutput(messages) || rawStdoutLines.join("\n").trim());
 			const spawnErrorMessage = spawnError instanceof Error ? spawnError.message : String(spawnError);
-			resolve({ stderr, exitCode: 1, messages, usage, model, error: error ?? assistantError ?? spawnErrorMessage, finalOutput, observedMutationAttempt });
+			resolve({ stderr, exitCode: 1, messages, usage, model, error: resourceLimitExceeded?.message ?? error ?? assistantError ?? spawnErrorMessage, finalOutput, observedMutationAttempt, resourceLimitExceeded });
 		});
 	});
 }
@@ -614,6 +654,7 @@ async function runSingleStep(
 	structuredOutputPath?: string;
 	structuredOutputSchemaPath?: string;
 	acceptance?: AcceptanceLedger;
+	resourceLimitExceeded?: ResourceLimitExceeded;
 }> {
 	const effectiveStructuredOutput = step.structuredOutput ?? (step.structuredOutputSchema
 		? createStructuredOutputRuntime(step.structuredOutputSchema, path.join(path.dirname(ctx.outputFile), "structured-output"))
@@ -701,6 +742,8 @@ async function runSingleStep(
 			{ eventsPath, runId: ctx.id, stepIndex: ctx.flatIndex, agent: step.agent },
 			ctx.registerInterrupt,
 			ctx.onChildEvent,
+			step.maxExecutionTimeMs,
+			step.maxTokens,
 		);
 		cleanupTempDir(tempDir);
 
@@ -766,7 +809,7 @@ async function runSingleStep(
 		finalOutputSnapshot = outputSnapshot;
 		finalResult = { ...run, exitCode: effectiveExitCode, model: candidate ?? run.model, error, structuredOutput } as RunPiStreamingResult & { structuredOutput?: unknown };
 		if (attempt.success || completionGuardError) break;
-		if (!isRetryableModelFailure(error) || index === candidates.length - 1) break;
+		if (run.resourceLimitExceeded || !isRetryableModelFailure(error) || index === candidates.length - 1) break;
 		attemptNotes.push(formatModelAttemptNote(attempt, candidates[index + 1]));
 	}
 
@@ -861,6 +904,8 @@ async function runSingleStep(
 					{ eventsPath, runId: ctx.id, stepIndex: ctx.flatIndex, agent: step.agent },
 					ctx.registerInterrupt,
 					ctx.onChildEvent,
+					step.maxExecutionTimeMs,
+					step.maxTokens,
 				);
 				cleanupTempDir(tempDir);
 				modelAttempts.push({
@@ -923,6 +968,7 @@ async function runSingleStep(
 					model: finalResult?.model,
 					attemptedModels: attemptedModels.length > 0 ? attemptedModels : undefined,
 					modelAttempts,
+					resourceLimitExceeded: finalResult?.resourceLimitExceeded,
 					skills: step.skills,
 					timestamp: Date.now(),
 				}, null, 2),
@@ -948,6 +994,7 @@ async function runSingleStep(
 		structuredOutputPath: effectiveStructuredOutput?.outputPath,
 		structuredOutputSchemaPath: effectiveStructuredOutput?.schemaPath,
 		acceptance,
+		resourceLimitExceeded: finalResult?.resourceLimitExceeded,
 	};
 }
 
@@ -1712,12 +1759,14 @@ async function runSubagent(config: SubagentRunConfig): Promise<void> {
 				statusPayload.steps[fi].structuredOutputPath = singleResult.structuredOutputPath;
 				statusPayload.steps[fi].structuredOutputSchemaPath = singleResult.structuredOutputSchemaPath;
 				statusPayload.steps[fi].acceptance = singleResult.acceptance;
+				statusPayload.steps[fi].resourceLimitExceeded = singleResult.resourceLimitExceeded;
 				statusPayload.lastUpdate = taskEndTime;
 				writeStatusPayload();
 				appendJsonl(eventsPath, JSON.stringify({
 					type: singleResult.exitCode === 0 ? "subagent.step.completed" : "subagent.step.failed",
 					ts: taskEndTime, runId: id, stepIndex: fi, agent: task.agent,
 					exitCode: singleResult.exitCode, durationMs: taskEndTime - taskStartTime,
+					resourceLimitExceeded: singleResult.resourceLimitExceeded,
 				}));
 				if (singleResult.exitCode !== 0 && failFast) aborted = true;
 				return { ...singleResult, skipped: false };
@@ -1742,6 +1791,7 @@ async function runSubagent(config: SubagentRunConfig): Promise<void> {
 					structuredOutputPath: pr.structuredOutputPath,
 					structuredOutputSchemaPath: pr.structuredOutputSchemaPath,
 					acceptance: pr.acceptance,
+					resourceLimitExceeded: pr.resourceLimitExceeded,
 				});
 			}
 			const collection = collectDynamicResults(step as Parameters<typeof collectDynamicResults>[0], materialized.items, parallelResults);
@@ -1941,6 +1991,7 @@ async function runSubagent(config: SubagentRunConfig): Promise<void> {
 						statusPayload.steps[fi].structuredOutputPath = singleResult.structuredOutputPath;
 						statusPayload.steps[fi].structuredOutputSchemaPath = singleResult.structuredOutputSchemaPath;
 						statusPayload.steps[fi].acceptance = singleResult.acceptance;
+						statusPayload.steps[fi].resourceLimitExceeded = singleResult.resourceLimitExceeded;
 						statusPayload.lastUpdate = taskEndTime;
 						writeStatusPayload();
 
@@ -1948,6 +1999,7 @@ async function runSubagent(config: SubagentRunConfig): Promise<void> {
 							type: singleResult.exitCode === 0 ? "subagent.step.completed" : "subagent.step.failed",
 							ts: taskEndTime, runId: id, stepIndex: fi, agent: task.agent,
 							exitCode: singleResult.exitCode, durationMs: taskDuration,
+							resourceLimitExceeded: singleResult.resourceLimitExceeded,
 						}));
 						if (singleResult.completionGuardTriggered) {
 							const event = buildControlEvent({
@@ -2006,6 +2058,7 @@ async function runSubagent(config: SubagentRunConfig): Promise<void> {
 							structuredOutputPath: pr.structuredOutputPath,
 							structuredOutputSchemaPath: pr.structuredOutputSchemaPath,
 							acceptance: pr.acceptance,
+							resourceLimitExceeded: pr.resourceLimitExceeded,
 						});
 					}
 				for (let t = 0; t < group.parallel.length; t++) {
@@ -2107,6 +2160,7 @@ async function runSubagent(config: SubagentRunConfig): Promise<void> {
 				structuredOutputPath: singleResult.structuredOutputPath,
 				structuredOutputSchemaPath: singleResult.structuredOutputSchemaPath,
 				acceptance: singleResult.acceptance,
+				resourceLimitExceeded: singleResult.resourceLimitExceeded,
 			});
 			if (seqStep.outputName) {
 				outputs[seqStep.outputName] = outputEntryFromAsyncResult({
@@ -2152,6 +2206,7 @@ async function runSubagent(config: SubagentRunConfig): Promise<void> {
 			statusPayload.steps[flatIndex].structuredOutputPath = singleResult.structuredOutputPath;
 			statusPayload.steps[flatIndex].structuredOutputSchemaPath = singleResult.structuredOutputSchemaPath;
 			statusPayload.steps[flatIndex].acceptance = singleResult.acceptance;
+			statusPayload.steps[flatIndex].resourceLimitExceeded = singleResult.resourceLimitExceeded;
 			if (stepTokens) {
 				statusPayload.steps[flatIndex].tokens = stepTokens;
 				statusPayload.totalTokens = { ...previousCumulativeTokens };
@@ -2168,6 +2223,7 @@ async function runSubagent(config: SubagentRunConfig): Promise<void> {
 				exitCode: singleResult.exitCode,
 				durationMs: stepEndTime - stepStartTime,
 				tokens: stepTokens,
+				resourceLimitExceeded: singleResult.resourceLimitExceeded,
 			}));
 			if (singleResult.completionGuardTriggered) {
 				const event = buildControlEvent({
@@ -2314,6 +2370,7 @@ async function runSubagent(config: SubagentRunConfig): Promise<void> {
 				structuredOutputPath: r.structuredOutputPath,
 				structuredOutputSchemaPath: r.structuredOutputSchemaPath,
 				acceptance: r.acceptance,
+				resourceLimitExceeded: r.resourceLimitExceeded,
 			})),
 			outputs,
 			workflowGraph: statusPayload.workflowGraph,

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

@@ -81,7 +81,7 @@ interface ChainExecutionDetailsInput {
 	outputs?: ChainOutputMap;
 	currentFlatIndex?: number;
 	dynamicChildren?: Record<number, Array<{ agent: string; label?: string; flatIndex: number; itemKey: string; outputName?: string; structured?: boolean; error?: string }>>;
-	dynamicGroupStatuses?: Record<number, { status: "pending" | "running" | "completed" | "failed" | "paused" | "detached"; error?: string; acceptance?: SingleResult["acceptance"] }>;
+	dynamicGroupStatuses?: Record<number, { status: "pending" | "running" | "completed" | "failed" | "paused" | "detached" | "timed-out"; error?: string; acceptance?: SingleResult["acceptance"] }>;
 }
 
 interface ParallelChainRunInput {
@@ -103,6 +103,8 @@ interface ParallelChainRunInput {
 	sessionFileForIndex?: (idx?: number) => string | undefined;
 	shareEnabled: boolean;
 	artifactConfig: ArtifactConfig;
+	timeoutMs?: number;
+	timeoutAt?: number;
 	artifactsDir: string;
 	signal?: AbortSignal;
 	onUpdate?: (r: AgentToolResult<Details>) => void;
@@ -265,6 +267,7 @@ async function runParallelChainTasks(input: ParallelChainRunInput): Promise<Sing
 				cwd: taskCwd,
 				signal: input.signal,
 				interruptSignal: interruptController.signal,
+				...(input.timeoutMs !== undefined && input.timeoutAt !== undefined ? { timeoutMs: input.timeoutMs, timeoutAt: input.timeoutAt } : {}),
 				allowIntercomDetach: taskAgentConfig?.systemPrompt?.includes(INTERCOM_BRIDGE_MARKER) === true,
 				intercomEvents: input.intercomEvents,
 				runId: input.runId,
@@ -277,6 +280,8 @@ async function runParallelChainTasks(input: ParallelChainRunInput): Promise<Sing
 				outputPath,
 				outputMode: behavior.outputMode,
 				maxSubagentDepth,
+				maxExecutionTimeMs: taskAgentConfig?.maxExecutionTimeMs,
+				maxTokens: taskAgentConfig?.maxTokens,
 				controlConfig: input.controlConfig,
 				onControlEvent: input.onControlEvent,
 				intercomSessionName: input.childIntercomTarget?.(task.agent, input.globalTaskIndex + taskIndex),
@@ -391,6 +396,7 @@ interface ChainExecutionParams {
 	nestedRoute?: NestedRouteInfo;
 	worktreeSetupHook?: string;
 	worktreeSetupHookTimeoutMs?: number;
+	timeoutMs?: number;
 }
 
 interface ChainExecutionResult {
@@ -580,6 +586,7 @@ export async function executeChain(params: ChainExecutionParams): Promise<ChainE
 		tuiBehaviorOverrides = result.behaviorOverrides;
 	}
 
+	const timeoutAt = params.timeoutMs !== undefined ? Date.now() + params.timeoutMs : undefined;
 	let prev = "";
 	let globalTaskIndex = 0;
 	let progressCreated = false;
@@ -648,6 +655,7 @@ export async function executeChain(params: ChainExecutionParams): Promise<ChainE
 					shareEnabled,
 					artifactConfig,
 					artifactsDir,
+					...(params.timeoutMs !== undefined && timeoutAt !== undefined ? { timeoutMs: params.timeoutMs, timeoutAt } : {}),
 					signal,
 					onUpdate,
 					results,
@@ -674,6 +682,18 @@ export async function executeChain(params: ChainExecutionParams): Promise<ChainE
 					if (result.progress) allProgress.push(result.progress);
 					if (result.artifactPaths) allArtifactPaths.push(result.artifactPaths);
 				}
+				const timedOutIndexInStep = parallelResults.findIndex((result) => result.timedOut);
+				const timedOut = timedOutIndexInStep >= 0 ? parallelResults[timedOutIndexInStep] : undefined;
+				if (timedOut) {
+					return {
+						content: [{ type: "text", text: `Chain timed out at step ${stepIndex + 1} (${timedOut.agent}): ${timedOut.error ?? "timeout expired"}` }],
+						isError: true,
+						details: buildChainExecutionDetails(makeDetailsInput({
+							currentStepIndex: stepIndex,
+							currentFlatIndex: globalTaskIndex - step.parallel.length + timedOutIndexInStep,
+						})),
+					};
+				}
 				const interruptedIndexInStep = parallelResults.findIndex((result) => result.interrupted);
 				const interrupted = interruptedIndexInStep >= 0 ? parallelResults[interruptedIndexInStep] : undefined;
 				if (interrupted) {
@@ -835,6 +855,7 @@ export async function executeChain(params: ChainExecutionParams): Promise<ChainE
 				shareEnabled,
 				artifactConfig,
 				artifactsDir,
+				...(params.timeoutMs !== undefined && timeoutAt !== undefined ? { timeoutMs: params.timeoutMs, timeoutAt } : {}),
 				signal,
 				onUpdate,
 				results,
@@ -861,6 +882,19 @@ export async function executeChain(params: ChainExecutionParams): Promise<ChainE
 				if (result.artifactPaths) allArtifactPaths.push(result.artifactPaths);
 			}
 			const collected = collectDynamicResults(step, materialized.items, parallelResults);
+			const timedOutIndexInStep = parallelResults.findIndex((result) => result.timedOut);
+			const timedOut = timedOutIndexInStep >= 0 ? parallelResults[timedOutIndexInStep] : undefined;
+			if (timedOut) {
+				dynamicGroupStatuses[stepIndex] = { status: "timed-out", error: timedOut.error };
+				return {
+					content: [{ type: "text", text: `Chain timed out at step ${stepIndex + 1} (${timedOut.agent}): ${timedOut.error ?? "timeout expired"}` }],
+					isError: true,
+					details: buildChainExecutionDetails(makeDetailsInput({
+						currentStepIndex: stepIndex,
+						currentFlatIndex: globalTaskIndex - dynamicParallelStep.parallel.length + timedOutIndexInStep,
+					})),
+				};
+			}
 			const interruptedIndexInStep = parallelResults.findIndex((result) => result.interrupted);
 			const interrupted = interruptedIndexInStep >= 0 ? parallelResults[interruptedIndexInStep] : undefined;
 			if (interrupted) {
@@ -1009,6 +1043,7 @@ export async function executeChain(params: ChainExecutionParams): Promise<ChainE
 				cwd: resolveChildCwd(cwd ?? ctx.cwd, seqStep.cwd),
 				signal,
 				interruptSignal: interruptController.signal,
+				...(params.timeoutMs !== undefined && timeoutAt !== undefined ? { timeoutMs: params.timeoutMs, timeoutAt } : {}),
 				allowIntercomDetach: agentConfig.systemPrompt?.includes(INTERCOM_BRIDGE_MARKER) === true,
 				intercomEvents,
 				runId,
@@ -1021,6 +1056,8 @@ export async function executeChain(params: ChainExecutionParams): Promise<ChainE
 				outputPath,
 				outputMode: behavior.outputMode,
 				maxSubagentDepth,
+				maxExecutionTimeMs: agentConfig.maxExecutionTimeMs,
+				maxTokens: agentConfig.maxTokens,
 				controlConfig,
 				onControlEvent,
 				intercomSessionName: childIntercomTarget?.(seqStep.agent, globalTaskIndex),
@@ -1088,6 +1125,13 @@ export async function executeChain(params: ChainExecutionParams): Promise<ChainE
 			if (r.progress) allProgress.push(r.progress);
 			if (r.artifactPaths) allArtifactPaths.push(r.artifactPaths);
 
+			if (r.timedOut) {
+				return {
+					content: [{ type: "text", text: `Chain timed out at step ${stepIndex + 1} (${r.agent}): ${r.error ?? "timeout expired"}` }],
+					isError: true,
+					details: buildChainExecutionDetails(makeDetailsInput({ currentStepIndex: stepIndex, currentFlatIndex: globalTaskIndex - 1 })),
+				};
+			}
 			if (r.interrupted) {
 				return {
 					content: [{ type: "text", text: `Chain paused after interrupt at step ${stepIndex + 1} (${r.agent}). Waiting for explicit next action.` }],

package/src/runs/foreground/execution.ts

@@ -44,6 +44,7 @@ import {
 	detectSubagentError,
 	extractToolArgsPreview,
 	extractTextFromContent,
+	formatResourceLimitExceeded,
 } from "../../shared/utils.ts";
 import { buildSkillInjection, resolveSkillsWithFallback } from "../../agents/skills.ts";
 import { evaluateCompletionMutationGuard, resolveCompletionPolicy, type CompletionPolicy } from "../shared/completion-guard.ts";
@@ -108,6 +109,43 @@ function appendRecentOutput(progress: AgentProgress, lines: string[]): void {
 	}
 }
 
+const FOREGROUND_TIMEOUT_EXIT_CODE = 124;
+
+function formatForegroundTimeoutMessage(timeoutMs: number | undefined): string {
+	return timeoutMs ? `Timed out after ${timeoutMs}ms.` : "Timed out.";
+}
+
+function createTimedOutResult(agent: string, task: string, options: RunSyncOptions): SingleResult {
+	const message = formatForegroundTimeoutMessage(options.timeoutMs);
+	return {
+		agent,
+		task,
+		exitCode: FOREGROUND_TIMEOUT_EXIT_CODE,
+		messages: [],
+		usage: emptyUsage(),
+		error: message,
+		finalOutput: message,
+		timedOut: true,
+		progress: {
+			index: options.index ?? 0,
+			agent,
+			status: "failed",
+			task,
+			recentTools: [],
+			recentOutput: [message],
+			toolCount: 0,
+			tokens: 0,
+			durationMs: 0,
+			lastActivityAt: Date.now(),
+		},
+		progressSummary: {
+			toolCount: 0,
+			tokens: 0,
+			durationMs: 0,
+		},
+	};
+}
+
 function stripAcceptanceReportsFromMessages(messages: Message[] | undefined): void {
 	for (const message of messages ?? []) {
 		if (message.role !== "assistant" || !Array.isArray(message.content)) continue;
@@ -263,6 +301,12 @@ async function runSingleAttempt(
 		let detached = false;
 		let intercomStarted = false;
 		let assistantError: string | undefined;
+		let timedOut = false;
+		let resourceLimited = false;
+		let timeoutTimer: NodeJS.Timeout | undefined;
+		let timeoutEscalationTimer: NodeJS.Timeout | undefined;
+		let resourceLimitTimer: NodeJS.Timeout | undefined;
+		let resourceLimitEscalationTimer: NodeJS.Timeout | undefined;
 		let removeAbortListener: (() => void) | undefined;
 		let removeInterruptListener: (() => void) | undefined;
 		let activityTimer: NodeJS.Timeout | undefined;
@@ -334,6 +378,22 @@ async function runSingleAttempt(
 			settled = true;
 			clearFinalDrainTimers();
 			clearStdioGuard();
+			if (timeoutTimer) {
+				clearTimeout(timeoutTimer);
+				timeoutTimer = undefined;
+			}
+			if (timeoutEscalationTimer) {
+				clearTimeout(timeoutEscalationTimer);
+				timeoutEscalationTimer = undefined;
+			}
+			if (resourceLimitTimer) {
+				clearTimeout(resourceLimitTimer);
+				resourceLimitTimer = undefined;
+			}
+			if (resourceLimitEscalationTimer) {
+				clearTimeout(resourceLimitEscalationTimer);
+				resourceLimitEscalationTimer = undefined;
+			}
 			if (activityTimer) {
 				clearInterval(activityTimer);
 				activityTimer = undefined;
@@ -428,6 +488,26 @@ async function runSingleAttempt(
 		};
 
 
+		const triggerResourceLimit = (kind: "maxExecutionTimeMs" | "maxTokens", limit: number, observed?: number) => {
+			if (processClosed || detached || settled || timedOut || resourceLimited) return;
+			resourceLimited = true;
+			const message = formatResourceLimitExceeded({ agent: agent.name, kind, limit, observed });
+			result.resourceLimitExceeded = { kind, limit, ...(observed !== undefined ? { observed } : {}), message };
+			result.error = message;
+			result.finalOutput = message;
+			progress.status = "failed";
+			progress.durationMs = Date.now() - startTime;
+			appendRecentOutput(progress, [message]);
+			progress.activityState = undefined;
+			fireUpdate();
+			trySignalChild(proc, "SIGINT");
+			resourceLimitEscalationTimer = setTimeout(() => {
+				if (settled || processClosed || detached) return;
+				trySignalChild(proc, "SIGTERM");
+			}, 1000);
+			resourceLimitEscalationTimer.unref?.();
+		};
+
 		const emitUpdateSnapshot = (text: string) => {
 			if (!options.onUpdate || processClosed) return;
 			const progressSnapshot = snapshotProgress(progress);
@@ -512,6 +592,9 @@ async function runSingleAttempt(
 						result.usage.cacheWrite += u.cacheWrite || 0;
 						result.usage.cost += u.cost?.total || 0;
 						progress.tokens = result.usage.input + result.usage.output;
+						if (options.maxTokens !== undefined && progress.tokens >= options.maxTokens) {
+							triggerResourceLimit("maxTokens", options.maxTokens, progress.tokens);
+						}
 					}
 					if (!result.model && evt.message.model) result.model = evt.message.model;
 					if (evt.message.errorMessage) assistantError = evt.message.errorMessage;
@@ -640,9 +723,45 @@ async function runSingleAttempt(
 			}
 		}
 
+		if (options.timeoutAt !== undefined) {
+			const triggerTimeout = () => {
+				if (processClosed || detached || settled || timedOut || resourceLimited) return;
+				timedOut = true;
+				const message = formatForegroundTimeoutMessage(options.timeoutMs);
+				result.timedOut = true;
+				result.error = message;
+				result.finalOutput = message;
+				progress.status = "failed";
+				progress.durationMs = Date.now() - startTime;
+				appendRecentOutput(progress, [message]);
+				progress.activityState = undefined;
+				fireUpdate();
+				trySignalChild(proc, "SIGINT");
+				timeoutEscalationTimer = setTimeout(() => {
+					if (settled || processClosed || detached) return;
+					trySignalChild(proc, "SIGTERM");
+				}, 1000);
+				timeoutEscalationTimer.unref?.();
+			};
+			const delay = options.timeoutAt - Date.now();
+			if (delay <= 0) triggerTimeout();
+			else {
+				timeoutTimer = setTimeout(triggerTimeout, delay);
+				timeoutTimer.unref?.();
+			}
+		}
+
+		if (options.maxExecutionTimeMs !== undefined) {
+			const maxExecutionTimeMs = options.maxExecutionTimeMs;
+			resourceLimitTimer = setTimeout(() => {
+				triggerResourceLimit("maxExecutionTimeMs", maxExecutionTimeMs);
+			}, maxExecutionTimeMs);
+			resourceLimitTimer.unref?.();
+		}
+
 		if (options.interruptSignal) {
 			const interrupt = () => {
-				if (processClosed || detached || settled) return;
+				if (processClosed || detached || settled || timedOut || resourceLimited) return;
 				interruptedByControl = true;
 				progress.status = "running";
 				progress.durationMs = Date.now() - startTime;
@@ -664,6 +783,40 @@ async function runSingleAttempt(
 		}
 	});
 	result.exitCode = exitCode;
+	if (result.resourceLimitExceeded) {
+		result.exitCode = 1;
+		result.error = result.error ?? result.resourceLimitExceeded.message;
+		result.finalOutput = result.finalOutput || result.error;
+		if (result.progress) {
+			result.progress.status = "failed";
+			result.progress.activityState = undefined;
+			result.progress.durationMs = Date.now() - startTime;
+		}
+		result.progressSummary = {
+			toolCount: progress.toolCount,
+			tokens: progress.tokens,
+			durationMs: result.progress?.durationMs ?? Date.now() - startTime,
+		};
+		result.controlEvents = allControlEvents.length ? allControlEvents : undefined;
+		return result;
+	}
+	if (result.timedOut) {
+		result.exitCode = FOREGROUND_TIMEOUT_EXIT_CODE;
+		result.error = result.error ?? formatForegroundTimeoutMessage(options.timeoutMs);
+		result.finalOutput = result.finalOutput || result.error;
+		if (result.progress) {
+			result.progress.status = "failed";
+			result.progress.activityState = undefined;
+			result.progress.durationMs = Date.now() - startTime;
+		}
+		result.progressSummary = {
+			toolCount: progress.toolCount,
+			tokens: progress.tokens,
+			durationMs: result.progress?.durationMs ?? Date.now() - startTime,
+		};
+		result.controlEvents = allControlEvents.length ? allControlEvents : undefined;
+		return result;
+	}
 	if (interruptedByControl) {
 		result.exitCode = 0;
 		result.interrupted = true;
@@ -915,8 +1068,16 @@ export async function runSync(
 			error: outputModeValidationError,
 		};
 	}
+	if (options.timeoutAt !== undefined && Date.now() >= options.timeoutAt) {
+		return createTimedOutResult(agentName, task, options);
+	}
+	const effectiveOptions: RunSyncOptions = {
+		...options,
+		maxExecutionTimeMs: options.maxExecutionTimeMs ?? agent.maxExecutionTimeMs,
+		maxTokens: options.maxTokens ?? agent.maxTokens,
+	};
 
-	const shareEnabled = options.share === true;
+	const shareEnabled = effectiveOptions.share === true;
 	const effectiveAcceptance = resolveEffectiveAcceptance({
 		explicit: options.acceptance,
 		agentName,
@@ -967,13 +1128,13 @@ export async function runSync(
 
 	let artifactPathsResult: ArtifactPaths | undefined;
 	let jsonlPath: string | undefined;
-	if (options.artifactsDir && options.artifactConfig?.enabled !== false) {
-		artifactPathsResult = getArtifactPaths(options.artifactsDir, options.runId, agentName, options.index);
-		ensureArtifactsDir(options.artifactsDir);
-		if (options.artifactConfig?.includeInput !== false) {
+	if (effectiveOptions.artifactsDir && effectiveOptions.artifactConfig?.enabled !== false) {
+		artifactPathsResult = getArtifactPaths(effectiveOptions.artifactsDir, effectiveOptions.runId, agentName, effectiveOptions.index);
+		ensureArtifactsDir(effectiveOptions.artifactsDir);
+		if (effectiveOptions.artifactConfig?.includeInput !== false) {
 				writeArtifact(artifactPathsResult.inputPath, `# Task for ${agentName}\n\n${taskWithAcceptance}`);
 		}
-		if (options.artifactConfig?.includeJsonl !== false) {
+		if (effectiveOptions.artifactConfig?.includeJsonl !== false) {
 			jsonlPath = artifactPathsResult.jsonlPath;
 		}
 	}
@@ -983,8 +1144,8 @@ export async function runSync(
 	for (let i = 0; i < modelsToTry.length; i++) {
 		const candidate = modelsToTry[i];
 		if (candidate) attemptedModels.push(candidate);
-		const outputSnapshot = captureSingleOutputSnapshot(options.outputPath);
-		const result = await runSingleAttempt(runtimeCwd, agent, taskWithAcceptance, candidate, options, {
+		const outputSnapshot = captureSingleOutputSnapshot(effectiveOptions.outputPath);
+		const result = await runSingleAttempt(runtimeCwd, agent, taskWithAcceptance, candidate, effectiveOptions, {
 			sessionEnabled,
 			systemPrompt,
 			resolvedSkillNames: resolvedSkills.length > 0 ? resolvedSkills.map((skill) => skill.name) : undefined,
@@ -1019,7 +1180,7 @@ export async function runSync(
 		if (attemptSucceeded) {
 			break;
 		}
-		if (!isRetryableModelFailure(result.error) || i === modelsToTry.length - 1) {
+		if (result.timedOut || result.resourceLimitExceeded || !isRetryableModelFailure(result.error) || i === modelsToTry.length - 1) {
 			break;
 		}
 		attemptNotes.push(formatModelAttemptNote(attempt, modelsToTry[i + 1]));