pi-subagents 0.32.0 → 0.33.0

package/src/runs/background/wait.ts

@@ -0,0 +1,353 @@
+/**
+ * `wait` tool: block the current turn until outstanding async subagent runs
+ * finish (or another completion notification arrives).
+ *
+ * Background subagent runs are detached. In an interactive session the parent
+ * can end its turn and Pi will wake it with a completion notification. That
+ * does not work when the parent is a skill that must run to completion, and it
+ * cannot work at all non-interactively (`pi -p ...`), where the run is a single
+ * turn: once the turn ends there is nothing left to receive the notification.
+ *
+ * `wait` closes that gap. It keeps the turn alive until a tracked async run for
+ * this session reaches a terminal state (complete / failed / paused), the
+ * caller-supplied timeout elapses, or the turn is aborted. Because it awaits
+ * inside the turn, the completion the model was told to wait for is actually
+ * observed before the tool returns.
+ *
+ * By default `wait` returns as soon as ONE run finishes, so a fleet manager can
+ * use it in a rolling-replacement loop: launch N workers, wait for the next one
+ * to finish, spawn its replacement, wait again — keeping N in flight instead of
+ * draining to zero between batches. Pass `all: true` to block until every
+ * tracked run is terminal, or `id` to block on one specific run.
+ *
+ * `wait` also returns when a run needs attention — not just on completion. A
+ * child that goes idle or blocks for a decision surfaces `needs_attention`
+ * (the same signal Pi shows as a control notice and, interactively, wakes the
+ * parent with). Since `wait` is used exactly where there is no next turn to
+ * receive that notice, it must break on it too, or a stuck child would stall
+ * the loop until the timeout. Attention runs are reported so the caller can
+ * inspect / nudge / resume / interrupt them.
+ *
+ * Wake mechanism: when given Pi's event bus (`deps.events`), `wait` subscribes
+ * to the subagent completion/control channels and wakes the instant any fires,
+ * rather than waiting out a fixed poll interval. A poll still runs on the
+ * interval as a reconciliation fallback (crashed runners, missed events), and
+ * the poll is the source of truth for what actually changed — the event only
+ * ends the sleep early. With no bus, `wait` degrades to pure polling.
+ */
+
+import type { AgentToolResult } from "@earendil-works/pi-agent-core";
+import { listAsyncRuns, type AsyncRunSummary } from "./async-status.ts";
+import {
+	ASYNC_DIR,
+	RESULTS_DIR,
+	SUBAGENT_ASYNC_COMPLETE_EVENT,
+	SUBAGENT_CONTROL_EVENT,
+	SUBAGENT_CONTROL_INTERCOM_EVENT,
+	SUBAGENT_RESULT_INTERCOM_EVENT,
+	type Details,
+	type SubagentState,
+} from "../../shared/types.ts";
+import { formatDuration } from "../../shared/formatters.ts";
+
+/** States that mean a run is still in flight (not yet resolved). */
+const ACTIVE_STATES: ReadonlyArray<AsyncRunSummary["state"]> = ["queued", "running"];
+
+const DEFAULT_TIMEOUT_MS = 30 * 60 * 1000; // 30 minutes
+const MIN_POLL_INTERVAL_MS = 250;
+const DEFAULT_POLL_INTERVAL_MS = 1000;
+
+export interface WaitParams {
+	/** Optional run id/prefix to wait for. When omitted, waits across every active run in this session. */
+	id?: string;
+	/**
+	 * When true, block until EVERY active run in this session (or matching `id`)
+	 * is terminal. Default false: return as soon as the first run finishes, so a
+	 * fleet manager can spawn a replacement and wait again. Ignored when `id`
+	 * targets a single run.
+	 */
+	all?: boolean;
+	/** Give up after this many milliseconds. Defaults to 30 minutes. */
+	timeoutMs?: number;
+}
+
+/** Minimal event-bus surface wait subscribes to (matches pi.events). */
+export interface WaitEventBus {
+	on(channel: string, handler: (data: unknown) => void): () => void;
+}
+
+export interface WaitDeps {
+	state: SubagentState;
+	asyncDirRoot?: string;
+	resultsDir?: string;
+	kill?: (pid: number, signal?: NodeJS.Signals | 0) => boolean;
+	now?: () => number;
+	pollIntervalMs?: number;
+	/** Injectable sleep for tests. */
+	sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
+	/**
+	 * Optional event bus (pi.events). When provided, wait wakes immediately on a
+	 * subagent completion/control event instead of waiting out the poll interval;
+	 * the poll then remains as a reconciliation fallback (crashed runners, missed
+	 * events). Omit in tests that want pure poll behavior.
+	 */
+	events?: WaitEventBus;
+}
+
+/** Bus channels that indicate a run changed state or needs attention. */
+const WAKE_CHANNELS = [
+	SUBAGENT_ASYNC_COMPLETE_EVENT,
+	SUBAGENT_CONTROL_EVENT,
+	SUBAGENT_CONTROL_INTERCOM_EVENT,
+	SUBAGENT_RESULT_INTERCOM_EVENT,
+];
+
+function defaultSleep(ms: number, signal?: AbortSignal): Promise<void> {
+	return new Promise((resolve) => {
+		if (signal?.aborted) {
+			resolve();
+			return;
+		}
+		const timer = setTimeout(() => {
+			signal?.removeEventListener("abort", onAbort);
+			resolve();
+		}, ms);
+		const onAbort = () => {
+			clearTimeout(timer);
+			resolve();
+		};
+		signal?.addEventListener("abort", onAbort, { once: true });
+	});
+}
+
+/**
+ * Sleep up to `ms`, but wake early if a subagent event fires on the bus (or the
+ * turn aborts). Returns when the first of those happens. With no bus this is a
+ * plain sleep, so the poll interval alone drives progress.
+ */
+function waitForWake(ms: number, signal: AbortSignal | undefined, deps: WaitDeps): Promise<void> {
+	const sleep = deps.sleep ?? defaultSleep;
+	const events = deps.events;
+	if (!events) return sleep(ms, signal);
+	return new Promise((resolve) => {
+		let settled = false;
+		const unsubs: Array<() => void> = [];
+		const wakeController = new AbortController();
+		const done = () => {
+			if (settled) return;
+			settled = true;
+			wakeController.abort();
+			signal?.removeEventListener("abort", done);
+			for (const u of unsubs) {
+				try { u(); } catch { /* best effort */ }
+			}
+			resolve();
+		};
+		if (signal?.aborted) {
+			done();
+			return;
+		}
+		signal?.addEventListener("abort", done, { once: true });
+		for (const channel of WAKE_CHANNELS) {
+			try { unsubs.push(events.on(channel, done)); } catch { /* ignore bad channel */ }
+		}
+		// Poll-interval fallback so we still reconcile even if no event arrives.
+		// The local signal cancels that fallback timer when an event wakes us first.
+		void sleep(ms, wakeController.signal).then(done);
+	});
+}
+
+function matchesId(run: AsyncRunSummary, id: string): boolean {
+	return run.id === id || run.id.startsWith(id);
+}
+
+/** A running run that has flagged it needs the parent's attention. */
+function needsAttention(run: AsyncRunSummary): boolean {
+	return run.activityState === "needs_attention";
+}
+
+/** Queued/running runs from this session, including runs that need attention. */
+function activeRunsForSession(params: WaitParams, deps: WaitDeps): AsyncRunSummary[] {
+	const asyncDirRoot = deps.asyncDirRoot ?? ASYNC_DIR;
+	const resultsDir = deps.resultsDir ?? RESULTS_DIR;
+	const runs = listAsyncRuns(asyncDirRoot, {
+		states: [...ACTIVE_STATES],
+		sessionId: deps.state.currentSessionId ?? undefined,
+		resultsDir,
+		kill: deps.kill,
+		now: deps.now,
+	});
+	return params.id ? runs.filter((run) => matchesId(run, params.id!)) : runs;
+}
+
+/** Runs (from the initial set) currently flagged needs_attention, for reporting. */
+function attentionRunsForSession(params: WaitParams, deps: WaitDeps, initialIds: Set<string>): AsyncRunSummary[] {
+	return activeRunsForSession(params, deps).filter((run) => needsAttention(run) && initialIds.has(run.id));
+}
+
+/** All runs (any state) for this session, for the final summary. */
+function allRunsForSession(params: WaitParams, deps: WaitDeps): AsyncRunSummary[] {
+	const asyncDirRoot = deps.asyncDirRoot ?? ASYNC_DIR;
+	const resultsDir = deps.resultsDir ?? RESULTS_DIR;
+	const runs = listAsyncRuns(asyncDirRoot, {
+		sessionId: deps.state.currentSessionId ?? undefined,
+		resultsDir,
+		kill: deps.kill,
+		now: deps.now,
+	});
+	return params.id ? runs.filter((run) => matchesId(run, params.id!)) : runs;
+}
+
+function summarizeTerminalRuns(runs: AsyncRunSummary[]): string {
+	if (runs.length === 0) return "";
+	const counts = { complete: 0, failed: 0, paused: 0 } as Record<string, number>;
+	for (const run of runs) {
+		if (run.state in counts) counts[run.state] += 1;
+	}
+	const parts: string[] = [];
+	if (counts.complete) parts.push(`${counts.complete} complete`);
+	if (counts.failed) parts.push(`${counts.failed} failed`);
+	if (counts.paused) parts.push(`${counts.paused} paused`);
+	return parts.join(", ");
+}
+
+function result(text: string, isError = false): AgentToolResult<Details> {
+	return {
+		content: [{ type: "text", text }],
+		...(isError ? { isError: true } : {}),
+		details: { mode: "management", results: [] },
+	};
+}
+
+/**
+ * Block until the targeted async runs finish, the timeout elapses, or the turn
+ * is aborted. Resolves with a short human-readable summary either way.
+ */
+export async function waitForSubagents(
+	params: WaitParams,
+	signal: AbortSignal | undefined,
+	deps: WaitDeps,
+): Promise<AgentToolResult<Details>> {
+	const now = deps.now ?? Date.now;
+	const pollIntervalMs = Math.max(MIN_POLL_INTERVAL_MS, deps.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS);
+	const timeoutMs = params.timeoutMs !== undefined && params.timeoutMs > 0 ? params.timeoutMs : DEFAULT_TIMEOUT_MS;
+	const startedAt = now();
+
+	// A single named run always means "wait until that one is done", regardless
+	// of `all`. Otherwise `all` decides: true → every run terminal; false → the
+	// first run to finish.
+	const waitForAll = params.id ? true : params.all === true;
+
+	let active: AsyncRunSummary[];
+	try {
+		active = activeRunsForSession(params, deps);
+	} catch (error) {
+		return result(error instanceof Error ? error.message : String(error), true);
+	}
+
+	if (active.length === 0) {
+		const finished = params.id
+			? `No active run matched "${params.id}". Nothing to wait for.`
+			: "No active async runs in this session. Nothing to wait for.";
+		return result(finished);
+	}
+	if (params.id) {
+		const exact = active.filter((run) => run.id === params.id);
+		if (exact.length === 1) active = exact;
+		else if (active.length > 1) {
+			return result(`Ambiguous async run id prefix "${params.id}" matched ${active.length} active runs: ${active.map((run) => run.id).join(", ")}. Pass a longer id.`, true);
+		}
+	}
+	const waitParams = params.id ? { ...params, id: active[0]!.id } : params;
+
+	// The set of runs in flight when the wait began. In first-completion mode we
+	// return as soon as any of THESE leaves the active set — a run spawned by a
+	// concurrent turn shouldn't satisfy this wait.
+	const initialIds = new Set(active.map((run) => run.id));
+	const initialCount = initialIds.size;
+	let pending = active.filter((run) => !needsAttention(run));
+
+	const done = (active: AsyncRunSummary[], attention: AsyncRunSummary[]): boolean => {
+		// A run needing attention always breaks the wait, in either mode: the
+		// caller has to act on it (nudge/resume/interrupt) and blocking longer
+		// helps nothing.
+		if (attention.length > 0) return true;
+		if (waitForAll) return active.every((run) => !initialIds.has(run.id));
+		// First-completion: satisfied once any initially-pending run is gone.
+		const stillActiveInitial = active.filter((run) => initialIds.has(run.id));
+		return stillActiveInitial.length < initialCount;
+	};
+
+	let attention = active.filter((run) => needsAttention(run));
+
+	while (!done(pending, attention)) {
+		if (signal?.aborted) {
+			const stillActive = pending.map((run) => `${run.id} (${run.state})`).join(", ");
+			return result(`Wait aborted after ${formatDuration(now() - startedAt)}. Still active: ${stillActive}.`, true);
+		}
+		if (now() - startedAt >= timeoutMs) {
+			const stillActive = pending.map((run) => `${run.id} (${run.state})`).join(", ");
+			return result(
+				`Wait timed out after ${formatDuration(timeoutMs)} with ${pending.length} run(s) still active: ${stillActive}. `
+					+ `The runs are detached and keep going; call wait again or inspect with subagent({ action: "status" }).`,
+				true,
+			);
+		}
+		await waitForWake(pollIntervalMs, signal, deps);
+		try {
+			active = activeRunsForSession(waitParams, deps);
+			pending = active.filter((run) => !needsAttention(run));
+			attention = attentionRunsForSession(waitParams, deps, initialIds);
+		} catch (error) {
+			return result(error instanceof Error ? error.message : String(error), true);
+		}
+	}
+
+	// Report how the finished run(s) came out. In first-completion mode, name the
+	// runs from the initial set that are now terminal.
+	let terminalSummary = "";
+	let finishedCount = 0;
+	try {
+		const allNow = allRunsForSession(waitParams, deps);
+		const terminal = allNow.filter((run) => !ACTIVE_STATES.includes(run.state) && initialIds.has(run.id));
+		finishedCount = terminal.length;
+		terminalSummary = summarizeTerminalRuns(terminal);
+	} catch {
+		// Summary is best-effort; the important part is that the wait resolved.
+	}
+
+	const attentionNote = attention.length > 0
+		? ` ${attention.length} run(s) need attention: ${attention.map((r) => r.id).join(", ")} — inspect with subagent({ action: "status" }) then nudge/resume/interrupt.`
+		: "";
+
+	const stillRunning = pending.filter((run) => initialIds.has(run.id)).length;
+	const elapsed = formatDuration(now() - startedAt);
+	const outcome = terminalSummary ? ` Outcome: ${terminalSummary}.` : "";
+
+	if (waitForAll) {
+		const scope = params.id ? `run "${params.id}"` : `${initialCount} async run(s)`;
+		const status = attention.length > 0 ? "attention required" : "done";
+		const notificationText = attention.length > 0
+			? "Relevant completion/control events have been observed; inspect status if the notification is not visible yet."
+			: "Completion events have been observed; inspect status if the notification is not visible yet.";
+		return result(
+			`Waited ${elapsed} for ${scope}; ${status}.${outcome}${attentionNote} ${notificationText}`,
+		);
+	}
+
+	// First-completion mode.
+	const remainder = stillRunning > 0
+		? ` ${stillRunning} run(s) still in flight — call wait again to catch the next one.`
+		: attention.length > 0
+			? " No other runs are waitable until attention is handled."
+			: " No runs remain in flight.";
+	const progress = attention.length > 0 && finishedCount === 0
+		? `${attention.length} of ${initialCount} run(s) need attention`
+		: `${finishedCount} of ${initialCount} run(s) finished`;
+	const notificationText = finishedCount > 0
+		? " Completion events for the finished run(s) have been observed; inspect status if the notification is not visible yet."
+		: " Relevant control events have been observed; inspect status if the notification is not visible yet.";
+	return result(
+		`Waited ${elapsed}; ${progress}.${outcome}${attentionNote}${remainder}${notificationText}`,
+	);
+}

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

@@ -56,11 +56,15 @@ import {
 	type IntercomEventBus,
 	type NestedRouteInfo,
 	type ResolvedControlConfig,
+	type ResolvedTurnBudget,
+	type ResolvedToolBudget,
 	type SingleResult,
+	type ToolBudgetConfig,
 	MAX_CONCURRENCY,
 	resolveChildMaxSubagentDepth,
 } from "../../shared/types.ts";
 import { resolveSubagentModelOverride } from "../shared/model-fallback.ts";
+import type { ModelScopeConfig } from "../shared/model-scope.ts";
 import { validateFileOnlyOutputMode } from "../shared/single-output.ts";
 import { buildWorkflowGraphSnapshot } from "../shared/workflow-graph.ts";
 import { ChainOutputValidationError, outputEntryFromResult, resolveOutputReferences, validateChainOutputBindings } from "../shared/chain-outputs.ts";
@@ -68,6 +72,7 @@ import { createStructuredOutputRuntime } from "../shared/structured-output.ts";
 import { collectDynamicResults, DynamicFanoutError, materializeDynamicParallelStep, validateDynamicCollection, type DynamicCollectedResult } from "../shared/dynamic-fanout.ts";
 import { acceptanceFailureMessage, aggregateAcceptanceReport, evaluateAcceptance, resolveEffectiveAcceptance } from "../shared/acceptance.ts";
 import type { ChainOutputMap } from "../../shared/types.ts";
+import { validateToolBudgetConfig } from "../shared/tool-budget.ts";
 
 interface ChainExecutionDetailsInput {
 	results: SingleResult[];
@@ -93,6 +98,7 @@ interface ParallelChainRunInput {
 	agents: AgentConfig[];
 	stepIndex: number;
 	availableModels: ModelInfo[];
+	modelScope?: ModelScopeConfig;
 	chainDir: string;
 	prev: string;
 	originalTask: string;
@@ -141,6 +147,10 @@ interface ParallelChainRunInput {
 	nestedRoute?: NestedRouteInfo;
 	timeoutMs?: number;
 	deadlineAt?: number;
+	turnBudget?: ResolvedTurnBudget;
+	onDetachedExit?: (index: number, result: SingleResult) => void;
+	toolBudget?: ResolvedToolBudget;
+	configToolBudget?: ToolBudgetConfig;
 	globalSemaphore?: Semaphore;
 }
 
@@ -202,6 +212,20 @@ function appendParallelWorktreeSummary(
 	return `${output}\n\n${diffSummary}`;
 }
 
+function resolveChainToolBudget(input: { stepBudget?: ToolBudgetConfig; runBudget?: ResolvedToolBudget; agentBudget?: ToolBudgetConfig; configBudget?: ToolBudgetConfig }): { toolBudget?: ResolvedToolBudget; error?: string } {
+	if (input.stepBudget !== undefined) {
+		const resolved = validateToolBudgetConfig(input.stepBudget, "toolBudget");
+		return { toolBudget: resolved.budget, error: resolved.error };
+	}
+	if (input.runBudget !== undefined) return { toolBudget: input.runBudget };
+	if (input.agentBudget !== undefined) {
+		const resolved = validateToolBudgetConfig(input.agentBudget, "agent.toolBudget");
+		return { toolBudget: resolved.budget, error: resolved.error };
+	}
+	const resolved = validateToolBudgetConfig(input.configBudget, "config.toolBudget");
+	return { toolBudget: resolved.budget, error: resolved.error };
+}
+
 async function runParallelChainTasks(input: ParallelChainRunInput): Promise<SingleResult[]> {
 	const concurrency = input.step.concurrency ?? MAX_CONCURRENCY;
 	const failFast = input.step.failFast ?? false;
@@ -245,8 +269,11 @@ async function runParallelChainTasks(input: ParallelChainRunInput): Promise<Sing
 				input.ctx.model,
 				input.availableModels,
 				input.ctx.model?.provider,
+				{ scope: input.modelScope, source: task.model ? "explicit" : "inherited" },
 			);
 			const maxSubagentDepth = resolveChildMaxSubagentDepth(input.maxSubagentDepth, taskAgentConfig?.maxSubagentDepth);
+			const toolBudget = resolveChainToolBudget({ stepBudget: task.toolBudget, runBudget: input.toolBudget, agentBudget: taskAgentConfig?.toolBudget, configBudget: input.configToolBudget });
+			if (toolBudget.error) throw new Error(toolBudget.error);
 
 			const taskCwd = input.worktreeSetup
 				? input.worktreeSetup.worktrees[taskIndex]!.agentCwd
@@ -300,12 +327,18 @@ async function runParallelChainTasks(input: ParallelChainRunInput): Promise<Sing
 				modelOverride: effectiveModel,
 				availableModels: input.availableModels,
 				preferredModelProvider: input.ctx.model?.provider,
+				modelScope: input.modelScope,
 				skills: behavior.skills === false ? [] : behavior.skills,
 				structuredOutput: structuredRuntime,
 				acceptance: task.acceptance,
 				acceptanceContext: { mode: "chain" },
 				timeoutMs: input.timeoutMs,
 				deadlineAt: input.deadlineAt,
+				turnBudget: input.turnBudget,
+				onDetachedExit: input.onDetachedExit
+					? (result) => input.onDetachedExit?.(input.globalTaskIndex + taskIndex, result)
+					: undefined,
+				toolBudget: toolBudget.toolBudget,
 				onUpdate: input.onUpdate
 					? (progressUpdate) => {
 						const stepResults = progressUpdate.details?.results || [];
@@ -414,6 +447,10 @@ interface ChainExecutionParams {
 	worktreeBaseDir?: string;
 	timeoutMs?: number;
 	deadlineAt?: number;
+	turnBudget?: ResolvedTurnBudget;
+	onDetachedExit?: (index: number, result: SingleResult) => void;
+	toolBudget?: ResolvedToolBudget;
+	configToolBudget?: ToolBudgetConfig;
 	/** Global cap on simultaneously-running tasks within this chain. Defaults to DEFAULT_GLOBAL_CONCURRENCY_LIMIT. */
 	globalConcurrencyLimit?: number;
 }
@@ -452,12 +489,14 @@ export async function executeChain(params: ChainExecutionParams): Promise<ChainE
 		onUpdate,
 		onControlEvent,
 		controlConfig,
+		onDetachedExit,
 		childIntercomTarget,
 		orchestratorIntercomTarget,
 		foregroundControl,
 		intercomEvents,
 		chainSkills: chainSkillsParam,
 		chainDir: chainDirBase,
+		modelScope,
 	} = params;
 	const chainSkills = chainSkillsParam ?? [];
 
@@ -516,7 +555,7 @@ export async function executeChain(params: ChainExecutionParams): Promise<ChainE
 	const chainDir = createChainDir(runId, chainDirBase);
 	const hasParallelSteps = chainSteps.some((step) => isParallelStep(step) || isDynamicParallelStep(step));
 	let templates: ResolvedTemplates = resolveChainTemplates(chainSteps);
-	const shouldClarify = clarify !== false && ctx.hasUI && !hasParallelSteps;
+	const shouldClarify = clarify === true && ctx.hasUI && !hasParallelSteps;
 	let tuiBehaviorOverrides: (BehaviorOverride | undefined)[] | undefined;
 	const availableModels: ModelInfo[] = ctx.modelRegistry.getAvailable().map(toModelInfo);
 	const availableSkills = discoverAvailableSkills(cwd ?? ctx.cwd);
@@ -665,6 +704,7 @@ export async function executeChain(params: ChainExecutionParams): Promise<ChainE
 					agents,
 					stepIndex,
 					availableModels,
+					modelScope,
 					chainDir,
 					prev,
 					originalTask,
@@ -700,6 +740,10 @@ export async function executeChain(params: ChainExecutionParams): Promise<ChainE
 					maxSubagentDepth: params.maxSubagentDepth,
 					timeoutMs: params.timeoutMs,
 					deadlineAt,
+					turnBudget: params.turnBudget,
+					onDetachedExit,
+					toolBudget: params.toolBudget,
+					configToolBudget: params.configToolBudget,
 					globalSemaphore,
 				});
 				globalTaskIndex += step.parallel.length;
@@ -880,6 +924,7 @@ export async function executeChain(params: ChainExecutionParams): Promise<ChainE
 				agents,
 				stepIndex,
 				availableModels,
+				modelScope,
 				chainDir,
 				prev,
 				originalTask,
@@ -914,6 +959,10 @@ export async function executeChain(params: ChainExecutionParams): Promise<ChainE
 				maxSubagentDepth: params.maxSubagentDepth,
 				timeoutMs: params.timeoutMs,
 				deadlineAt,
+				turnBudget: params.turnBudget,
+				onDetachedExit,
+				toolBudget: params.toolBudget,
+				configToolBudget: params.configToolBudget,
 				globalSemaphore,
 			});
 			globalTaskIndex = dynamicStartIndex + reservedDynamicItems;
@@ -1060,13 +1109,14 @@ export async function executeChain(params: ChainExecutionParams): Promise<ChainE
 			const cleanTask = stepTask;
 			stepTask = prefix + stepTask + suffix;
 
-			const effectiveModel = tuiOverride?.model
-				?? resolveSubagentModelOverride(
-					seqStep.model ?? agentConfig.model,
-					ctx.model,
-					availableModels,
-					ctx.model?.provider,
-				);
+			const explicitStepModel = tuiOverride?.model ?? seqStep.model;
+			const effectiveModel = resolveSubagentModelOverride(
+				explicitStepModel ?? agentConfig.model,
+				ctx.model,
+				availableModels,
+				ctx.model?.provider,
+				{ scope: modelScope, source: explicitStepModel ? "explicit" : "inherited" },
+			);
 
 			const outputPath = typeof behavior.output === "string"
 				? (path.isAbsolute(behavior.output) ? behavior.output : path.join(chainDir, behavior.output))
@@ -1076,10 +1126,11 @@ export async function executeChain(params: ChainExecutionParams): Promise<ChainE
 				return buildChainExecutionErrorResult(validationError, makeDetailsInput({ currentStepIndex: stepIndex, currentFlatIndex: globalTaskIndex }));
 			}
 			const maxSubagentDepth = resolveChildMaxSubagentDepth(params.maxSubagentDepth, agentConfig.maxSubagentDepth);
+			const childIndex = globalTaskIndex;
 			const interruptController = new AbortController();
 			if (foregroundControl) {
 				foregroundControl.currentAgent = seqStep.agent;
-				foregroundControl.currentIndex = globalTaskIndex;
+				foregroundControl.currentIndex = childIndex;
 				foregroundControl.currentActivityState = undefined;
 				foregroundControl.updatedAt = Date.now();
 				foregroundControl.interrupt = () => {
@@ -1094,6 +1145,23 @@ export async function executeChain(params: ChainExecutionParams): Promise<ChainE
 			const structuredRuntime = seqStep.outputSchema
 				? createStructuredOutputRuntime(seqStep.outputSchema, path.join(chainDir, "structured-output"))
 				: undefined;
+			const toolBudget = resolveChainToolBudget({ stepBudget: seqStep.toolBudget, runBudget: params.toolBudget, agentBudget: agentConfig?.toolBudget, configBudget: params.configToolBudget });
+			if (toolBudget.error) return buildChainExecutionErrorResult(toolBudget.error, {
+				results,
+				includeProgress,
+				allProgress,
+				allArtifactPaths,
+				artifactsDir: params.artifactsDir,
+				chainAgents,
+				chainSteps,
+				totalSteps,
+				currentStepIndex: stepIndex,
+				runId: params.runId,
+				outputs,
+				currentFlatIndex: globalTaskIndex,
+				dynamicChildren,
+				dynamicGroupStatuses,
+			});
 			const r = await runSync(ctx.cwd, agents, seqStep.agent, stepTask, {
 				parentSessionId: ctx.sessionManager.getSessionId() ?? undefined,
 				cwd: resolveChildCwd(cwd ?? ctx.cwd, seqStep.cwd),
@@ -1102,11 +1170,11 @@ export async function executeChain(params: ChainExecutionParams): Promise<ChainE
 				allowIntercomDetach: agentConfig.systemPrompt?.includes(INTERCOM_BRIDGE_MARKER) === true,
 				intercomEvents,
 				runId,
-				index: globalTaskIndex,
-				sessionDir: sessionDirForIndex(globalTaskIndex),
-				sessionFile: sessionFileForTask?.(seqStep.agent, globalTaskIndex)
-					?? sessionFileForIndex?.(globalTaskIndex),
-				thinkingOverride: thinkingOverrideForTask?.(seqStep.agent, globalTaskIndex),
+				index: childIndex,
+				sessionDir: sessionDirForIndex(childIndex),
+				sessionFile: sessionFileForTask?.(seqStep.agent, childIndex)
+					?? sessionFileForIndex?.(childIndex),
+				thinkingOverride: thinkingOverrideForTask?.(seqStep.agent, childIndex),
 				share: shareEnabled,
 				artifactsDir: artifactConfig.enabled ? artifactsDir : undefined,
 				artifactConfig,
@@ -1115,18 +1183,24 @@ export async function executeChain(params: ChainExecutionParams): Promise<ChainE
 				maxSubagentDepth,
 				controlConfig,
 				onControlEvent,
-				intercomSessionName: childIntercomTarget?.(seqStep.agent, globalTaskIndex),
+				intercomSessionName: childIntercomTarget?.(seqStep.agent, childIndex),
 				orchestratorIntercomTarget,
 				nestedRoute: params.nestedRoute,
 				modelOverride: effectiveModel,
 				availableModels,
 				preferredModelProvider: ctx.model?.provider,
+				modelScope,
 				skills: behavior.skills === false ? [] : behavior.skills,
 				structuredOutput: structuredRuntime,
 				acceptance: seqStep.acceptance,
 				acceptanceContext: { mode: "chain" },
 				timeoutMs: params.timeoutMs,
 				deadlineAt,
+				turnBudget: params.turnBudget,
+				onDetachedExit: onDetachedExit
+					? (result) => onDetachedExit(childIndex, result)
+					: undefined,
+				toolBudget: toolBudget.toolBudget,
 				onUpdate: onUpdate
 					? (p) => {
 						const stepResults = p.details?.results || [];
@@ -1134,7 +1208,7 @@ export async function executeChain(params: ChainExecutionParams): Promise<ChainE
 						if (foregroundControl && stepProgress.length > 0) {
 							const current = stepProgress[0];
 							foregroundControl.currentAgent = seqStep.agent;
-							foregroundControl.currentIndex = globalTaskIndex;
+							foregroundControl.currentIndex = childIndex;
 							foregroundControl.currentActivityState = current?.activityState;
 							foregroundControl.lastActivityAt = current?.lastActivityAt;
 							foregroundControl.currentTool = current?.currentTool;
@@ -1162,7 +1236,7 @@ export async function executeChain(params: ChainExecutionParams): Promise<ChainE
 									steps: chainSteps,
 									results: results.concat(stepResults),
 									currentStepIndex: stepIndex,
-									currentFlatIndex: globalTaskIndex,
+									currentFlatIndex: childIndex,
 									dynamicChildren,
 									dynamicGroupStatuses,
 								}),
@@ -1171,7 +1245,7 @@ export async function executeChain(params: ChainExecutionParams): Promise<ChainE
 					}
 					: undefined,
 			});
-			if (foregroundControl?.currentIndex === globalTaskIndex) {
+			if (foregroundControl?.currentIndex === childIndex) {
 				foregroundControl.interrupt = undefined;
 				foregroundControl.updatedAt = Date.now();
 			}
@@ -1185,13 +1259,13 @@ export async function executeChain(params: ChainExecutionParams): Promise<ChainE
 			if (r.interrupted) {
 				return {
 					content: [{ type: "text", text: `Chain paused after interrupt at step ${stepIndex + 1} (${r.agent}). Waiting for explicit next action.` }],
-					details: buildChainExecutionDetails(makeDetailsInput({ currentStepIndex: stepIndex, currentFlatIndex: globalTaskIndex - 1 })),
+					details: buildChainExecutionDetails(makeDetailsInput({ currentStepIndex: stepIndex, currentFlatIndex: childIndex })),
 				};
 			}
 			if (r.detached) {
 				return {
 					content: [{ type: "text", text: `Chain detached for intercom coordination at step ${stepIndex + 1} (${r.agent}). Reply to the supervisor request first. After the child exits, start a fresh follow-up if needed.` }],
-					details: buildChainExecutionDetails(makeDetailsInput({ currentStepIndex: stepIndex, currentFlatIndex: globalTaskIndex - 1 })),
+					details: buildChainExecutionDetails(makeDetailsInput({ currentStepIndex: stepIndex, currentFlatIndex: childIndex })),
 				};
 			}
 
@@ -1202,7 +1276,7 @@ export async function executeChain(params: ChainExecutionParams): Promise<ChainE
 				});
 				return {
 					content: [{ type: "text", text: summary }],
-					details: buildChainExecutionDetails(makeDetailsInput({ currentStepIndex: stepIndex, currentFlatIndex: globalTaskIndex - 1 })),
+					details: buildChainExecutionDetails(makeDetailsInput({ currentStepIndex: stepIndex, currentFlatIndex: childIndex })),
 					isError: true,
 				};
 			}