pi-subagents 0.32.0 → 0.33.0

package/src/runs/shared/dynamic-fanout.ts

@@ -45,7 +45,7 @@ const DYNAMIC_STEP_KEYS = new Set(["expand", "parallel", "collect", "concurrency
 const RUNNER_DYNAMIC_STEP_KEYS = new Set([...DYNAMIC_STEP_KEYS, "effectiveAcceptance", "sessionFiles", "thinkingOverrides"]);
 const DYNAMIC_EXPAND_KEYS = new Set(["from", "item", "key", "maxItems", "onEmpty"]);
 const DYNAMIC_EXPAND_FROM_KEYS = new Set(["output", "path"]);
-const DYNAMIC_PARALLEL_KEYS = new Set(["agent", "task", "phase", "label", "outputSchema", "cwd", "output", "outputMode", "reads", "progress", "skill", "model", "acceptance"]);
+const DYNAMIC_PARALLEL_KEYS = new Set(["agent", "task", "phase", "label", "outputSchema", "cwd", "output", "outputMode", "reads", "progress", "skill", "model", "toolBudget", "acceptance"]);
 const RUNNER_DYNAMIC_PARALLEL_KEYS = new Set([
 	...DYNAMIC_PARALLEL_KEYS,
 	"outputName", "structured", "inheritProjectContext", "inheritSkills", "skills", "outputPath", "maxSubagentDepth",

package/src/runs/shared/model-fallback.ts

@@ -1,5 +1,6 @@
 import type { ModelInfo as AvailableModelInfo } from "../../shared/model-info.ts";
 import type { Usage } from "../../shared/types.ts";
+import { checkModelScope, type ModelScopeConfig, type ModelScopeViolation, type ModelSource } from "./model-scope.ts";
 
 export type { AvailableModelInfo };
 
@@ -29,6 +30,144 @@ export interface ParentModel {
 	id: string;
 }
 
+/**
+ * Normalize a model id or provider segment for fuzzy comparison: case-fold,
+ * treat dots/underscores as dashes (so `4.5` matches `4-5`), and collapse
+ * repeated separators. Pure.
+ */
+export function normalizeModelSegment(segment: string): string {
+	return segment
+		.toLowerCase()
+		.replace(/[._]+/g, "-")
+		.replace(/-+/g, "-")
+		.replace(/^-|-$/g, "");
+}
+
+function isPlausibleDateStamp(year: string, month: string, day: string): boolean {
+	const yyyy = Number(year);
+	const mm = Number(month);
+	const dd = Number(day);
+	return yyyy >= 1900 && yyyy <= 2099 && mm >= 1 && mm <= 12 && dd >= 1 && dd <= 31;
+}
+
+/** Drop a trailing date stamp (`-20251001` or `-2025-10-01`) so dated and undated ids match. Pure. */
+function stripTrailingDateStamp(segment: string): string {
+	const dashed = /^(.*)-(\d{4})-(\d{2})-(\d{2})$/.exec(segment);
+	if (dashed && isPlausibleDateStamp(dashed[2]!, dashed[3]!, dashed[4]!)) return dashed[1]!;
+	const compact = /^(.*)-(\d{4})(\d{2})(\d{2})$/.exec(segment);
+	if (compact && isPlausibleDateStamp(compact[2]!, compact[3]!, compact[4]!)) return compact[1]!;
+	return segment;
+}
+
+function resolveBaseModelCandidate(
+	baseModel: string,
+	availableModels: AvailableModelInfo[],
+	preferredProvider?: string,
+): string | undefined {
+	if (baseModel.includes("/")) {
+		const exact = availableModels.find((entry) => entry.fullId === baseModel);
+		if (exact) return exact.fullId;
+	} else {
+		const exactMatches = availableModels.filter((entry) => entry.id === baseModel);
+		if (preferredProvider) {
+			const preferredMatch = exactMatches.find((entry) => entry.provider === preferredProvider);
+			if (preferredMatch) return preferredMatch.fullId;
+		}
+		if (exactMatches.length === 1) return exactMatches[0]!.fullId;
+	}
+
+	return fuzzyResolveModel(baseModel, availableModels, preferredProvider);
+}
+
+/**
+ * Fuzzy-resolve a base model id (thinking suffix already stripped) against the
+ * registry, tolerating separator, case, and optional date-stamp differences so
+ * users do not have to spell provider/model exactly. A qualified `provider/id`
+ * query only matches within the named provider — this never silently switches
+ * providers for security/cost-sensitive configs. Returns the matched `fullId`,
+ * or `undefined` when there is no match or the match is ambiguous across
+ * providers (and no `preferredProvider` disambiguates). Pure.
+ */
+export function fuzzyResolveModel(
+	baseModel: string,
+	availableModels: AvailableModelInfo[],
+	preferredProvider?: string,
+): string | undefined {
+	let queryProvider: string | undefined;
+	let queryIdRaw = baseModel;
+	const slashIdx = baseModel.indexOf("/");
+	if (slashIdx !== -1) {
+		queryProvider = normalizeModelSegment(baseModel.slice(0, slashIdx));
+		queryIdRaw = baseModel.slice(slashIdx + 1);
+	} else {
+		const providerSeparators = [":", "."];
+		for (const separator of providerSeparators) {
+			const separatorIdx = baseModel.indexOf(separator);
+			if (separatorIdx <= 0) continue;
+			const providerPart = normalizeModelSegment(baseModel.slice(0, separatorIdx));
+			if (!availableModels.some((entry) => normalizeModelSegment(entry.provider) === providerPart)) continue;
+			queryProvider = providerPart;
+			queryIdRaw = baseModel.slice(separatorIdx + 1);
+			break;
+		}
+	}
+	const queryId = normalizeModelSegment(queryIdRaw);
+	const queryIdNoDate = stripTrailingDateStamp(queryId);
+
+	const candidates = availableModels.filter((entry) => {
+		const entryId = normalizeModelSegment(entry.id);
+		if (entryId !== queryId && stripTrailingDateStamp(entryId) !== queryIdNoDate) return false;
+		if (queryProvider !== undefined && normalizeModelSegment(entry.provider) !== queryProvider) return false;
+		return true;
+	});
+	if (candidates.length === 0) return undefined;
+	if (preferredProvider) {
+		const preferredProviderNorm = normalizeModelSegment(preferredProvider);
+		const preferred = candidates.find((entry) => normalizeModelSegment(entry.provider) === preferredProviderNorm);
+		if (preferred) return preferred.fullId;
+	}
+	if (candidates.length === 1) return candidates[0]!.fullId;
+	return undefined;
+}
+
+/**
+ * Resolve a possibly-loose model id to a canonical `provider/id` (plus any
+ * thinking suffix). Exact registry matches win; fuzzy normalization
+ * (separator/case/date-stamp via {@link fuzzyResolveModel}) is a fallback so
+ * spelling differences still resolve. Never switches providers for a qualified
+ * query. Pure.
+ */
+export function resolveModelCandidate(
+	model: string | undefined,
+	availableModels: AvailableModelInfo[] | undefined,
+	preferredProvider?: string,
+): string | undefined {
+	if (!model) return undefined;
+	if (!availableModels || availableModels.length === 0) return model;
+
+	const resolvedWhole = resolveBaseModelCandidate(model, availableModels, preferredProvider);
+	if (resolvedWhole) return resolvedWhole;
+
+	const { baseModel, thinkingSuffix } = splitThinkingSuffix(model);
+	if (!thinkingSuffix) return model;
+	const resolvedBase = resolveBaseModelCandidate(baseModel, availableModels, preferredProvider);
+	if (resolvedBase) return `${resolvedBase}${thinkingSuffix}`;
+	return model;
+}
+
+export interface ResolveSubagentModelOverrideOptions {
+	/** When set with `enforce: true`, out-of-scope models are rejected. */
+	scope?: ModelScopeConfig;
+	/** Origin of the requested model: explicit caller-supplied (hard error) vs inherited (warn). Defaults to `"inherited"`. */
+	source?: ModelSource;
+	/** Called for warn-severity violations instead of `console.warn`. */
+	onWarn?: (violation: ModelScopeViolation) => void;
+}
+
+function defaultScopeWarn(violation: ModelScopeViolation): void {
+	console.warn(`[pi-subagents] ${violation.message}`);
+}
+
 /**
  * Resolve the `--model` override passed to a spawned subagent.
  *
@@ -43,38 +182,39 @@ export interface ParentModel {
  * session's model.
  *
  * An explicitly requested model string is resolved via {@link resolveModelCandidate}.
+ * When `options.scope.enforce` is on, an out-of-scope resolved model throws for
+ * an explicit (`source: "explicit"`) request and warns for an inherited one.
  */
 export function resolveSubagentModelOverride(
 	requestedModel: string | boolean | undefined,
 	parentModel: ParentModel | undefined,
 	availableModels: AvailableModelInfo[] | undefined,
 	preferredProvider?: string,
+	options?: ResolveSubagentModelOverrideOptions,
 ): string | undefined {
 	const trimmed = typeof requestedModel === "string" ? requestedModel.trim() : "";
 	const explicit = trimmed && trimmed !== INHERIT_MODEL ? trimmed : undefined;
+	let resolved: string | undefined;
 	if (explicit === undefined) {
-		return parentModel ? `${parentModel.provider}/${parentModel.id}` : undefined;
+		resolved = parentModel ? `${parentModel.provider}/${parentModel.id}` : undefined;
+	} else {
+		resolved = resolveModelCandidate(explicit, availableModels, preferredProvider);
+	}
+	if (resolved && options?.scope?.enforce) {
+		const source: ModelSource = explicit === undefined ? "inherited" : (options.source ?? "inherited");
+		const violation = checkModelScope(resolved, options.scope, source);
+		if (violation) {
+			if (violation.severity === "error") throw new Error(violation.message);
+			(options.onWarn ?? defaultScopeWarn)(violation);
+		}
 	}
-	return resolveModelCandidate(explicit, availableModels, preferredProvider);
+	return resolved;
 }
 
-export function resolveModelCandidate(
-	model: string | undefined,
-	availableModels: AvailableModelInfo[] | undefined,
-	preferredProvider?: string,
-): string | undefined {
-	if (!model) return undefined;
-	if (model.includes("/")) return model;
-	if (!availableModels || availableModels.length === 0) return model;
-
-	const { baseModel, thinkingSuffix } = splitThinkingSuffix(model);
-	const matches = availableModels.filter((entry) => entry.id === baseModel);
-	if (preferredProvider) {
-		const preferredMatch = matches.find((entry) => entry.provider === preferredProvider);
-		if (preferredMatch) return `${preferredMatch.fullId}${thinkingSuffix}`;
-	}
-	if (matches.length !== 1) return model;
-	return `${matches[0]!.fullId}${thinkingSuffix}`;
+export interface BuildModelCandidatesOptions {
+	/** Fallback models are inherited agent config and warn, rather than error, when out of scope. */
+	scope?: ModelScopeConfig;
+	onWarn?: (violation: ModelScopeViolation) => void;
 }
 
 export function buildModelCandidates(
@@ -82,13 +222,20 @@ export function buildModelCandidates(
 	fallbackModels: string[] | undefined,
 	availableModels: AvailableModelInfo[] | undefined,
 	preferredProvider?: string,
+	options?: BuildModelCandidatesOptions,
 ): string[] {
 	const seen = new Set<string>();
 	const candidates: string[] = [];
-	for (const raw of [primaryModel, ...(fallbackModels ?? [])]) {
+	const rawCandidates = [primaryModel, ...(fallbackModels ?? [])];
+	for (let index = 0; index < rawCandidates.length; index++) {
+		const raw = rawCandidates[index];
 		if (!raw) continue;
 		const normalized = resolveModelCandidate(raw.trim(), availableModels, preferredProvider);
 		if (!normalized || seen.has(normalized)) continue;
+		if (index > 0 && options?.scope?.enforce) {
+			const violation = checkModelScope(normalized, options.scope, "inherited");
+			if (violation) (options.onWarn ?? defaultScopeWarn)(violation);
+		}
 		seen.add(normalized);
 		candidates.push(normalized);
 	}

package/src/runs/shared/model-scope.ts

@@ -0,0 +1,128 @@
+/**
+ * Optional model-scope enforcement for subagent model resolution.
+ *
+ * When `subagents.modelScope.enforce` is enabled in settings, a resolved model
+ * that does not match any `allow` pattern is rejected. The severity depends on
+ * where the model came from: an explicit caller-supplied model (`--model`,
+ * tool-call `model`, or a TUI clarify pick) is a hard error, while a model
+ * inherited from agent frontmatter / `defaultModel` / the parent session only
+ * emits a warning so existing configurations keep working.
+ *
+ * The decision logic ({@link checkModelScope}) is a pure function of its
+ * inputs so it can be unit-tested without touching the filesystem or config.
+ */
+
+import { splitKnownThinkingSuffix } from "../../shared/model-info.ts";
+
+export interface ModelScopeConfig {
+	enforce?: boolean;
+	/** Glob-style allow patterns (only `*` is special), matched against `provider/id`. */
+	allow?: string[];
+}
+
+/** Where a resolved model originated, deciding enforcement severity. */
+export type ModelSource = "explicit" | "inherited";
+
+export interface ModelScopeViolation {
+	/** Resolved model id (without thinking suffix) that fell outside the scope. */
+	model: string;
+	severity: "warn" | "error";
+	message: string;
+	allowedPatterns: string[];
+}
+
+function stripThinkingSuffix(model: string): string {
+	return splitKnownThinkingSuffix(model).baseModel;
+}
+
+/** Escape RegExp specials except `*`, then turn `*` into `.*`. */
+function globToRegExp(pattern: string): RegExp {
+	const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*");
+	return new RegExp(`^${escaped}$`, "i");
+}
+
+/**
+ * Test whether a resolved model matches a single allow pattern. Both sides are
+ * compared case-insensitively against the full `provider/id` (thinking suffix
+ * stripped from the model).
+ */
+export function matchesScopePattern(model: string, pattern: string): boolean {
+	return globToRegExp(pattern).test(stripThinkingSuffix(model));
+}
+
+/**
+ * Pure scope decision. Returns a {@link ModelScopeViolation} when the model is
+ * out of scope and enforcement is on, otherwise `undefined`. Enforcement with
+ * no `allow` list is a no-op (the settings parser rejects that combination, but
+ * this stays defensive for callers that build configs programmatically).
+ */
+export function checkModelScope(
+	model: string | undefined,
+	scope: ModelScopeConfig | undefined,
+	source: ModelSource,
+): ModelScopeViolation | undefined {
+	if (!model || !scope?.enforce) return undefined;
+	const allow = scope.allow;
+	if (!allow || allow.length === 0) return undefined;
+	if (allow.some((pattern) => matchesScopePattern(model, pattern))) return undefined;
+
+	const baseModel = stripThinkingSuffix(model);
+	const severity: ModelScopeViolation["severity"] = source === "explicit" ? "error" : "warn";
+	return {
+		model: baseModel,
+		severity,
+		allowedPatterns: allow,
+		message:
+			`Model '${baseModel}' is outside the configured subagent model scope. ` +
+			`Allowed patterns: ${allow.join(", ")}.`,
+	};
+}
+
+/**
+ * Validate and normalize a raw `subagents.modelScope` value from settings.
+ * Throws a descriptive error for malformed configs (matching the surrounding
+ * settings-parsing style). Returns `undefined` when the field is absent.
+ */
+export function parseModelScopeConfig(
+	value: unknown,
+	meta: { filePath: string },
+): ModelScopeConfig | undefined {
+	if (value === undefined) return undefined;
+	if (!value || typeof value !== "object" || Array.isArray(value)) {
+		throw new Error(`Subagent settings in '${meta.filePath}' have invalid 'modelScope'; expected an object.`);
+	}
+
+	const input = value as Record<string, unknown>;
+	const config: ModelScopeConfig = {};
+
+	if ("enforce" in input) {
+		if (typeof input.enforce !== "boolean") {
+			throw new Error(`Subagent settings in '${meta.filePath}' have invalid 'modelScope.enforce'; expected a boolean.`);
+		}
+		config.enforce = input.enforce;
+	}
+
+	if ("allow" in input) {
+		if (!Array.isArray(input.allow)) {
+			throw new Error(`Subagent settings in '${meta.filePath}' have invalid 'modelScope.allow'; expected an array of strings.`);
+		}
+		const allow: string[] = [];
+		for (const entry of input.allow) {
+			if (typeof entry !== "string") {
+				throw new Error(`Subagent settings in '${meta.filePath}' have invalid 'modelScope.allow'; expected an array of strings.`);
+			}
+			const trimmed = entry.trim();
+			if (trimmed) allow.push(trimmed);
+		}
+		if (allow.length === 0) {
+			throw new Error(`Subagent settings in '${meta.filePath}' have invalid 'modelScope.allow'; expected a non-empty array of patterns.`);
+		}
+		config.allow = allow;
+	}
+
+	if (config.enforce === true && (!config.allow || config.allow.length === 0)) {
+		throw new Error(`Subagent settings in '${meta.filePath}' set modelScope.enforce without a non-empty 'allow' list; supply allowed model patterns or disable enforcement.`);
+	}
+
+	return Object.keys(config).length > 0 ? config : undefined;
+}

package/src/runs/shared/nested-events.ts

@@ -8,6 +8,7 @@ import {
 	type AsyncJobState,
 	type AsyncStatus,
 	type NestedRouteInfo,
+	type TurnBudgetState,
 	type NestedRunSummary,
 	type NestedRunState,
 	type NestedStepSummary,
@@ -195,6 +196,24 @@ function sanitizeCost(value: unknown): NestedRunSummary["totalCost"] | undefined
 		: undefined;
 }
 
+function sanitizeTurnBudget(value: unknown): TurnBudgetState | undefined {
+	if (!value || typeof value !== "object") return undefined;
+	const raw = value as Record<string, unknown>;
+	const maxTurns = clampNumber(raw.maxTurns);
+	const graceTurns = clampNumber(raw.graceTurns);
+	const turnCount = clampNumber(raw.turnCount);
+	const outcome = raw.outcome === "within-budget" || raw.outcome === "wrap-up-requested" || raw.outcome === "exceeded" ? raw.outcome : undefined;
+	if (maxTurns === undefined || graceTurns === undefined || turnCount === undefined || !outcome) return undefined;
+	return {
+		maxTurns,
+		graceTurns,
+		turnCount,
+		outcome,
+		...(clampNumber(raw.wrapUpRequestedAtTurn) !== undefined ? { wrapUpRequestedAtTurn: clampNumber(raw.wrapUpRequestedAtTurn) } : {}),
+		...(clampNumber(raw.exceededAtTurn) !== undefined ? { exceededAtTurn: clampNumber(raw.exceededAtTurn) } : {}),
+	};
+}
+
 function sanitizeState(value: unknown, fallback: NestedRunState): NestedRunState {
 	return value === "queued" || value === "running" || value === "complete" || value === "failed" || value === "paused"
 		? value
@@ -224,6 +243,9 @@ function sanitizeStep(input: unknown, depth: number): NestedStepSummary | undefi
 		...(clampNumber(raw.endedAt) !== undefined ? { endedAt: clampNumber(raw.endedAt) } : {}),
 		...(stringValue(raw.error, 1024) ? { error: stringValue(raw.error, 1024) } : {}),
 		...(raw.timedOut === true ? { timedOut: true } : {}),
+		...(sanitizeTurnBudget(raw.turnBudget) ? { turnBudget: sanitizeTurnBudget(raw.turnBudget) } : {}),
+		...(raw.turnBudgetExceeded === true ? { turnBudgetExceeded: true } : {}),
+		...(raw.wrapUpRequested === true ? { wrapUpRequested: true } : {}),
 		...(depth < MAX_DEPTH && Array.isArray(raw.children) ? { children: raw.children.map((child) => sanitizeSummary(child, depth + 1)).filter((child): child is NestedRunSummary => Boolean(child)).slice(0, MAX_CHILDREN) } : {}),
 	};
 }
@@ -276,6 +298,9 @@ export function sanitizeSummary(input: unknown, depth = 0): NestedRunSummary | u
 		...(clampNumber(raw.timeoutMs) !== undefined ? { timeoutMs: clampNumber(raw.timeoutMs) } : {}),
 		...(clampNumber(raw.deadlineAt) !== undefined ? { deadlineAt: clampNumber(raw.deadlineAt) } : {}),
 		...(raw.timedOut === true ? { timedOut: true } : {}),
+		...(sanitizeTurnBudget(raw.turnBudget) ? { turnBudget: sanitizeTurnBudget(raw.turnBudget) } : {}),
+		...(raw.turnBudgetExceeded === true ? { turnBudgetExceeded: true } : {}),
+		...(raw.wrapUpRequested === true ? { wrapUpRequested: true } : {}),
 		...(stringValue(raw.error, 1024) ? { error: stringValue(raw.error, 1024) } : {}),
 		...(steps && steps.length > 0 ? { steps } : {}),
 		...(depth < MAX_DEPTH && Array.isArray(raw.children) ? { children: raw.children.map((child) => sanitizeSummary(child, depth + 1)).filter((child): child is NestedRunSummary => Boolean(child)).slice(0, MAX_CHILDREN) } : {}),
@@ -834,6 +859,9 @@ export function nestedSummaryFromAsyncStatus(status: AsyncStatus, asyncDir: stri
 		...(status.timeoutMs !== undefined ? { timeoutMs: status.timeoutMs } : {}),
 		...(status.deadlineAt !== undefined ? { deadlineAt: status.deadlineAt } : {}),
 		...(status.timedOut !== undefined ? { timedOut: status.timedOut } : {}),
+		...(status.turnBudget ? { turnBudget: status.turnBudget } : {}),
+		...(status.turnBudgetExceeded !== undefined ? { turnBudgetExceeded: status.turnBudgetExceeded } : {}),
+		...(status.wrapUpRequested !== undefined ? { wrapUpRequested: status.wrapUpRequested } : {}),
 		...(status.error ? { error: status.error } : {}),
 		...(status.startedAt !== undefined ? { startedAt: status.startedAt } : { startedAt: fallback.ts }),
 		...(status.endedAt !== undefined ? { endedAt: status.endedAt } : {}),
@@ -854,6 +882,9 @@ export function nestedSummaryFromAsyncStatus(status: AsyncStatus, asyncDir: stri
 			...(step.endedAt !== undefined ? { endedAt: step.endedAt } : {}),
 			...(step.error ? { error: step.error } : {}),
 			...(step.timedOut !== undefined ? { timedOut: step.timedOut } : {}),
+			...(step.turnBudget ? { turnBudget: step.turnBudget } : {}),
+			...(step.turnBudgetExceeded !== undefined ? { turnBudgetExceeded: step.turnBudgetExceeded } : {}),
+			...(step.wrapUpRequested !== undefined ? { wrapUpRequested: step.wrapUpRequested } : {}),
 		})).slice(0, MAX_STEPS) } : {}),
 	};
 }

package/src/runs/shared/parallel-utils.ts

@@ -38,6 +38,7 @@ export interface RunnerSubagentStep {
 	};
 	structuredOutputSchema?: import("../../shared/types.ts").JsonSchemaObject;
 	effectiveAcceptance?: import("../../shared/types.ts").ResolvedAcceptanceConfig;
+	toolBudget?: import("../../shared/types.ts").ResolvedToolBudget;
 }
 
 export interface ParallelStepGroup {

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

@@ -5,7 +5,8 @@ import { fileURLToPath } from "node:url";
 import { encodeNestedPathEnv, parseNestedPathEnv, type NestedPathEntry } from "./nested-path.ts";
 import { resolveMcpDirectToolNames } from "./mcp-direct-tool-allowlist.ts";
 import { STRUCTURED_OUTPUT_CAPTURE_ENV, STRUCTURED_OUTPUT_SCHEMA_ENV } from "./structured-output.ts";
-import type { JsonSchemaObject } from "../../shared/types.ts";
+import { TEMP_ROOT_DIR, type JsonSchemaObject, type ResolvedToolBudget } from "../../shared/types.ts";
+import { TOOL_BUDGET_ENV, encodeToolBudgetEnv } from "./tool-budget.ts";
 
 const THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh"];
 const TASK_ARG_LIMIT = 8000;
@@ -13,6 +14,8 @@ const PROMPT_RUNTIME_EXTENSION_PATH = path.join(path.dirname(fileURLToPath(impor
 const FANOUT_CHILD_EXTENSION_PATH = path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "..", "extension", "fanout-child.ts");
 export const SUBAGENT_CHILD_ENV = "PI_SUBAGENT_CHILD";
 export const SUBAGENT_ORCHESTRATOR_TARGET_ENV = "PI_SUBAGENT_ORCHESTRATOR_TARGET";
+export const SUBAGENT_ORCHESTRATOR_SESSION_ID_ENV = "PI_SUBAGENT_ORCHESTRATOR_SESSION_ID";
+export const SUBAGENT_SUPERVISOR_CHANNEL_DIR_ENV = "PI_SUBAGENT_SUPERVISOR_CHANNEL_DIR";
 export const SUBAGENT_RUN_ID_ENV = "PI_SUBAGENT_RUN_ID";
 export const SUBAGENT_CHILD_AGENT_ENV = "PI_SUBAGENT_CHILD_AGENT";
 export const SUBAGENT_CHILD_INDEX_ENV = "PI_SUBAGENT_CHILD_INDEX";
@@ -26,6 +29,7 @@ export const SUBAGENT_PARENT_DEPTH_ENV = "PI_SUBAGENT_PARENT_DEPTH";
 export const SUBAGENT_PARENT_PATH_ENV = "PI_SUBAGENT_PARENT_PATH";
 export const SUBAGENT_PARENT_CAPABILITY_TOKEN_ENV = "PI_SUBAGENT_PARENT_CAPABILITY_TOKEN";
 export const SUBAGENT_PARENT_SESSION_ENV = "PI_SUBAGENT_PARENT_SESSION";
+export const SUBAGENT_STEER_INBOX_ENV = "PI_SUBAGENT_STEER_INBOX";
 
 interface BuildPiArgsInput {
 	parentSessionId?: string;
@@ -60,11 +64,13 @@ interface BuildPiArgsInput {
 	parentDepth?: number;
 	parentPath?: NestedPathEntry[];
 	parentCapabilityToken?: string;
+	steerInboxDir?: string;
 	structuredOutput?: {
 		schema: JsonSchemaObject;
 		schemaPath: string;
 		outputPath: string;
 	};
+	toolBudget?: ResolvedToolBudget;
 }
 
 interface BuildPiArgsResult {
@@ -73,6 +79,14 @@ interface BuildPiArgsResult {
 	tempDir?: string;
 }
 
+function sanitizeSupervisorChannelSegment(value: string): string {
+	return value.trim().replace(/[^A-Za-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "") || "unknown";
+}
+
+function supervisorChannelDir(runId: string, agent: string, childIndex: number): string {
+	return path.join(TEMP_ROOT_DIR, "supervisor-channels", `${sanitizeSupervisorChannelSegment(runId)}-${sanitizeSupervisorChannelSegment(agent)}-${childIndex}`);
+}
+
 export function applyThinkingSuffix(model: string | undefined, thinking: string | undefined, replaceExisting = false): string | undefined {
 	if (!model || !thinking) return model;
 	const colonIdx = model.lastIndexOf(":");
@@ -206,6 +220,16 @@ export function buildPiArgs(input: BuildPiArgsInput): BuildPiArgsResult {
 	if (input.orchestratorIntercomTarget) {
 		env[SUBAGENT_ORCHESTRATOR_TARGET_ENV] = input.orchestratorIntercomTarget;
 	}
+	if (input.parentSessionId) {
+		env[SUBAGENT_ORCHESTRATOR_SESSION_ID_ENV] = input.parentSessionId;
+	}
+	if (input.orchestratorIntercomTarget && input.parentSessionId && input.runId && input.childAgentName) {
+		const childIndex = input.childIndex ?? 0;
+		const channelDir = supervisorChannelDir(input.runId, input.childAgentName, childIndex);
+		fs.mkdirSync(path.join(channelDir, "requests"), { recursive: true });
+		fs.mkdirSync(path.join(channelDir, "replies"), { recursive: true });
+		env[SUBAGENT_SUPERVISOR_CHANNEL_DIR_ENV] = channelDir;
+	}
 	if (input.runId) {
 		env[SUBAGENT_RUN_ID_ENV] = input.runId;
 	}
@@ -224,6 +248,11 @@ export function buildPiArgs(input: BuildPiArgsInput): BuildPiArgsResult {
 		env[STRUCTURED_OUTPUT_CAPTURE_ENV] = input.structuredOutput.outputPath;
 		env[STRUCTURED_OUTPUT_SCHEMA_ENV] = input.structuredOutput.schemaPath;
 	}
+	if (input.steerInboxDir) {
+		env[SUBAGENT_STEER_INBOX_ENV] = input.steerInboxDir;
+	}
+	const encodedToolBudget = encodeToolBudgetEnv(input.toolBudget);
+	if (encodedToolBudget) env[TOOL_BUDGET_ENV] = encodedToolBudget;
 
 	env[SUBAGENT_PARENT_SESSION_ENV] = input.parentSessionId ?? process.env[SUBAGENT_PARENT_SESSION_ENV] ?? "";
 

package/src/runs/shared/subagent-prompt-runtime.ts

@@ -1,9 +1,12 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { SUBAGENT_FANOUT_CHILD_ENV } from "./pi-args.ts";
+import { registerNativeSupervisorClient } from "../../intercom/native-supervisor-channel.ts";
+import { consumeSteerRequestsFromDir, writeSteerRequestToDir, type SteerRequest } from "../background/control-channel.ts";
+import { SUBAGENT_FANOUT_CHILD_ENV, SUBAGENT_STEER_INBOX_ENV } from "./pi-args.ts";
 import { STRUCTURED_OUTPUT_CAPTURE_ENV, STRUCTURED_OUTPUT_SCHEMA_ENV, validateStructuredOutputValue } from "./structured-output.ts";
-import type { JsonSchemaObject } from "../../shared/types.ts";
+import { TOOL_BUDGET_ENV, decodeToolBudgetEnv, shouldBlockToolForBudget, toolBudgetBlockedMessage, toolBudgetSoftNudge } from "./tool-budget.ts";
+import type { JsonSchemaObject, ResolvedToolBudget } from "../../shared/types.ts";
 
 const SUBAGENT_INHERIT_PROJECT_CONTEXT_ENV = "PI_SUBAGENT_INHERIT_PROJECT_CONTEXT";
 const SUBAGENT_INHERIT_SKILLS_ENV = "PI_SUBAGENT_INHERIT_SKILLS";
@@ -155,7 +158,110 @@ export function stripParentOnlySubagentMessages(messages: unknown[]): unknown[]
 	return changed ? filtered : messages;
 }
 
+export function formatSteerMessage(request: SteerRequest): string {
+	return [
+		"Mid-run steering from the parent orchestrator:",
+		"",
+		request.message,
+		"",
+		"Incorporate this guidance at the next safe point. Do not restart the task unless the guidance explicitly asks you to.",
+	].join("\n");
+}
+
+function registerToolBudget(pi: ExtensionAPI, budget: ResolvedToolBudget | undefined): void {
+	if (!budget) return;
+	let toolCount = 0;
+	let softNudged = false;
+	const sendUserMessage = (pi as { sendUserMessage?: (content: string, options: { deliverAs: "steer" }) => unknown }).sendUserMessage;
+	const onRuntimeEvent = pi.on as unknown as (event: string, handler: (event: { toolName?: string }) => unknown) => void;
+	onRuntimeEvent("tool_call", (event) => {
+		const toolName = typeof event.toolName === "string" ? event.toolName : "tool";
+		toolCount++;
+		if (budget.soft !== undefined && toolCount >= budget.soft && !softNudged) {
+			softNudged = true;
+			try {
+				sendUserMessage?.(toolBudgetSoftNudge(budget, toolCount), { deliverAs: "steer" });
+			} catch {
+				// Budget nudges are advisory; blocking below remains authoritative.
+			}
+		}
+		if (!shouldBlockToolForBudget(budget, toolName, toolCount)) return undefined;
+		return { block: true, reason: toolBudgetBlockedMessage(budget, toolName, toolCount) };
+	});
+}
+
+function registerSteeringInbox(pi: ExtensionAPI): void {
+	const steerInbox = process.env[SUBAGENT_STEER_INBOX_ENV]?.trim();
+	if (!steerInbox) return;
+	const sendUserMessage = (pi as { sendUserMessage?: (content: string, options: { deliverAs: "steer" }) => unknown }).sendUserMessage;
+	if (typeof sendUserMessage !== "function") return;
+
+	let canSteer = false;
+	let disposed = false;
+	let flushing = false;
+	let started = false;
+	let watcher: fs.FSWatcher | undefined;
+	let interval: NodeJS.Timeout | undefined;
+	const flush = (): void => {
+		if (disposed || flushing || !canSteer) return;
+		flushing = true;
+		try {
+			const requests = consumeSteerRequestsFromDir(steerInbox);
+			for (let index = 0; index < requests.length; index++) {
+				const request = requests[index]!;
+				try {
+					sendUserMessage(formatSteerMessage(request), { deliverAs: "steer" });
+				} catch {
+					for (const pending of requests.slice(index)) writeSteerRequestToDir(steerInbox, pending);
+					break;
+				}
+			}
+		} finally {
+			flushing = false;
+		}
+	};
+	const start = (): void => {
+		if (started || disposed) return;
+		try {
+			fs.mkdirSync(steerInbox, { recursive: true });
+		} catch {
+			return;
+		}
+		started = true;
+		try {
+			watcher = fs.watch(steerInbox, () => flush());
+			watcher.on("error", () => {});
+		} catch {
+			watcher = undefined;
+		}
+		interval = setInterval(flush, 250);
+		interval.unref?.();
+	};
+	const activate = (): undefined => {
+		start();
+		canSteer = true;
+		flush();
+		return undefined;
+	};
+
+	const onRuntimeEvent = pi.on as unknown as (event: string, handler: (event: unknown) => unknown) => void;
+	onRuntimeEvent("session_start", () => start());
+	for (const eventName of ["message_start", "message_update", "message_end", "tool_execution_start", "tool_execution_end", "turn_end"] as const) {
+		onRuntimeEvent(eventName, activate);
+	}
+	onRuntimeEvent("session_shutdown", () => {
+		disposed = true;
+		try {
+			watcher?.close();
+		} catch {}
+		if (interval) clearInterval(interval);
+	});
+}
+
 export default function registerSubagentPromptRuntime(pi: ExtensionAPI): void {
+	registerSteeringInbox(pi);
+	registerToolBudget(pi, decodeToolBudgetEnv(process.env[TOOL_BUDGET_ENV]));
+	registerNativeSupervisorClient(pi);
 	const structuredOutputPath = process.env[STRUCTURED_OUTPUT_CAPTURE_ENV];
 	const structuredSchemaPath = process.env[STRUCTURED_OUTPUT_SCHEMA_ENV];
 	if (structuredOutputPath && structuredSchemaPath) {