pi-subagents 0.52.1 → 0.54.0

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

@@ -15,7 +15,7 @@
 
 import { splitKnownThinkingSuffix } from "../../shared/model-info.ts";
 
-export interface ModelScopeConfig {
+export interface ModelScopeRule {
 	enforce?: boolean;
 	/** Reject inherited and fallback models outside the allowlist instead of warning. */
 	strict?: boolean;
@@ -23,6 +23,19 @@ export interface ModelScopeConfig {
 	allow?: string[];
 }
 
+export interface ModelScopeConfig extends ModelScopeRule {
+	/** Additional restrictions keyed by canonical agent name. */
+	agents?: Record<string, ModelScopeRule>;
+}
+
+export interface ModelScopeCheckRule extends ModelScopeRule {
+	origin?: string;
+}
+
+export interface ResolvedModelScope extends ModelScopeCheckRule {
+	origin: string;
+}
+
 /** Where a resolved model originated, deciding enforcement severity. */
 export type ModelSource = "explicit" | "inherited";
 
@@ -32,6 +45,7 @@ export interface ModelScopeViolation {
 	severity: "warn" | "error";
 	message: string;
 	allowedPatterns: string[];
+	origin: string;
 }
 
 function stripThinkingSuffix(model: string): string {
@@ -61,7 +75,7 @@ export function matchesScopePattern(model: string, pattern: string): boolean {
  */
 export function checkModelScope(
 	model: string | undefined,
-	scope: ModelScopeConfig | undefined,
+	scope: ModelScopeCheckRule | undefined,
 	source: ModelSource,
 ): ModelScopeViolation | undefined {
 	if (!model || !scope?.enforce) return undefined;
@@ -71,16 +85,89 @@ export function checkModelScope(
 
 	const baseModel = stripThinkingSuffix(model);
 	const severity: ModelScopeViolation["severity"] = source === "explicit" || scope.strict === true ? "error" : "warn";
+	const origin = scope.origin ?? "modelScope";
 	return {
 		model: baseModel,
 		severity,
 		allowedPatterns: allow,
+		origin,
 		message:
-			`Model '${baseModel}' is outside the configured subagent model scope. ` +
+			`Model '${baseModel}' is outside the configured subagent model scope (${origin}). ` +
 			`Allowed patterns: ${allow.join(", ")}.`,
 	};
 }
 
+function expandInheritPattern(pattern: string, parentModel: { provider: string; id: string } | undefined): string {
+	return pattern === "inherit" && parentModel ? `${parentModel.provider}/${parentModel.id}` : pattern;
+}
+
+function assertRecord(value: unknown, field: string, meta: { filePath: string }, expected = "an object"): Record<string, unknown> {
+	if (!value || typeof value !== "object" || Array.isArray(value)) {
+		throw new Error(`Subagent settings in '${meta.filePath}' have invalid '${field}'; expected ${expected}.`);
+	}
+	return value as Record<string, unknown>;
+}
+
+function parseAllowList(value: unknown, field: string, meta: { filePath: string }): string[] {
+	if (!Array.isArray(value)) {
+		throw new Error(`Subagent settings in '${meta.filePath}' have invalid '${field}'; expected an array of strings.`);
+	}
+	const allow: string[] = [];
+	for (const entry of value) {
+		if (typeof entry !== "string") {
+			throw new Error(`Subagent settings in '${meta.filePath}' have invalid '${field}'; 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 '${field}'; expected a non-empty array of patterns.`);
+	}
+	return allow;
+}
+
+function parseScopeRule(input: Record<string, unknown>, field: string, meta: { filePath: string }): ModelScopeRule {
+	const rule: ModelScopeRule = {};
+	if ("enforce" in input) {
+		if (typeof input.enforce !== "boolean") throw new Error(`Subagent settings in '${meta.filePath}' have invalid '${field}.enforce'; expected a boolean.`);
+		rule.enforce = input.enforce;
+	}
+	if ("strict" in input) {
+		if (typeof input.strict !== "boolean") throw new Error(`Subagent settings in '${meta.filePath}' have invalid '${field}.strict'; expected a boolean.`);
+		rule.strict = input.strict;
+	}
+	if ("allow" in input) rule.allow = parseAllowList(input.allow, `${field}.allow`, meta);
+	return rule;
+}
+
+/** Resolve the global and matching agent policies into independent launch-time checks. */
+export function resolveModelScopesForAgent(
+	config: ModelScopeConfig | undefined,
+	agentName: string,
+	parentModel: { provider: string; id: string } | undefined,
+): ResolvedModelScope[] {
+	if (!config) return [];
+	const scopes: ResolvedModelScope[] = [];
+	if (config.allow) {
+		scopes.push({
+			...(config.enforce !== undefined ? { enforce: config.enforce } : {}),
+			...(config.strict !== undefined ? { strict: config.strict } : {}),
+			allow: config.allow.map((pattern) => expandInheritPattern(pattern, parentModel)),
+			origin: "modelScope",
+		});
+	}
+	const agentScope = config.agents?.[agentName];
+	if (agentScope?.allow) {
+		scopes.push({
+			enforce: agentScope.enforce ?? config.enforce,
+			strict: agentScope.strict ?? config.strict,
+			allow: agentScope.allow.map((pattern) => expandInheritPattern(pattern, parentModel)),
+			origin: `modelScope.agents.${agentName}`,
+		});
+	}
+	return scopes;
+}
+
 /**
  * Validate and normalize a raw `subagents.modelScope` value from settings.
  * Throws a descriptive error for malformed configs (matching the surrounding
@@ -91,46 +178,26 @@ export function parseModelScopeConfig(
 	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 ("strict" in input) {
-		if (typeof input.strict !== "boolean") {
-			throw new Error(`Subagent settings in '${meta.filePath}' have invalid 'modelScope.strict'; expected a boolean.`);
-		}
-		config.strict = input.strict;
-	}
-
-	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 input = assertRecord(value, "modelScope", meta);
+	const config: ModelScopeConfig = parseScopeRule(input, "modelScope", meta);
+
+	if ("agents" in input) {
+		const agents: Record<string, ModelScopeRule> = {};
+		for (const [rawName, rawScope] of Object.entries(assertRecord(input.agents, "modelScope.agents", meta, "an object keyed by agent name"))) {
+			const name = rawName.trim();
+			const field = `modelScope.agents.${name}`;
+			if (!name) throw new Error(`Subagent settings in '${meta.filePath}' have invalid 'modelScope.agents' key; expected a non-empty agent name.`);
+			const agentInput = assertRecord(rawScope, field, meta);
+			if ("agents" in agentInput) {
+				throw new Error(`Subagent settings in '${meta.filePath}' have invalid '${field}.agents'; nested agent scopes are not supported.`);
 			}
-			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.`);
+			agents[name] = parseScopeRule(agentInput, field, meta);
 		}
-		config.allow = allow;
+		config.agents = agents;
 	}
 
-	if (config.enforce === true && (!config.allow || config.allow.length === 0)) {
+	const hasAnyAllow = Boolean(config.allow?.length) || Object.values(config.agents ?? {}).some((scope) => Boolean(scope.allow?.length));
+	if (config.enforce === true && !hasAnyAllow) {
 		throw new Error(`Subagent settings in '${meta.filePath}' set modelScope.enforce without a non-empty 'allow' list; supply allowed model patterns or disable enforcement.`);
 	}
 

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

@@ -191,6 +191,7 @@ export interface BuildPiArgsInput {
 export interface BuildPiArgsResult {
 	args: string[];
 	env: Record<string, string | undefined>;
+	warnings: string[];
 	tempDir?: string;
 	toolDiagnosticPath?: string;
 	runtimeAcknowledgedExtensionsPath?: string;
@@ -251,6 +252,7 @@ export interface ResolvePiLaunchToolPlanInput {
 	capabilityCeiling?: ResolvedSubagentCapabilityCeiling;
 	inheritedCapabilityCeiling?: ResolvedSubagentCapabilityCeiling;
 	agentName?: string;
+	permissionRules?: PermissionRules;
 }
 
 export interface PiLaunchToolPlan {
@@ -271,6 +273,13 @@ export interface PiLaunchToolPlan {
 	extensionArgs: string[];
 	disableAmbientExtensions: boolean;
 	capabilityAudit?: SubagentCapabilityAudit;
+	/**
+	 * Non-fatal footguns surfaced during plan resolution (currently: an agent
+	 * `extensions: []` override, which disables ALL ambient extensions for the
+	 * child rather than "adding nothing" — see the empty-extensions-override
+	 * warning below). Callers may log these; they never change behavior.
+	 */
+	warnings: string[];
 }
 
 function extensionIdentifier(value: string): string {
@@ -288,6 +297,10 @@ function boundedExtensionIdentifiers(values: string[]): {
 	};
 }
 
+function hasPermissionRules(rules: PermissionRules | undefined): boolean {
+	return rules !== undefined && Object.keys(rules).length > 0;
+}
+
 export function projectLaunchResolvedChildExtensions(
 	toolPlan: Pick<
 		PiLaunchToolPlan,
@@ -451,7 +464,9 @@ export function resolvePiLaunchToolPlan(
 		: [];
 	const permSystemExt = capabilityCeiling?.denyExtensions
 		? undefined
-		: resolvePermissionSystemExtension();
+		: hasPermissionRules(input.permissionRules)
+			? resolvePermissionSystemExtension()
+			: undefined;
 	const runtimeExtensions = [
 		PROMPT_RUNTIME_EXTENSION_PATH,
 		...(fanoutAuthorized ? [FANOUT_CHILD_EXTENSION_PATH] : []),
@@ -460,6 +475,21 @@ export function resolvePiLaunchToolPlan(
 	const disableAmbientExtensions =
 		capabilityCeiling?.denyExtensions === true ||
 		input.extensions !== undefined;
+	const warnings: string[] = [];
+	// An agent override that sets `extensions: []` reads like "add nothing", but
+	// any *defined* extensions list (including an empty one) disables every
+	// ambient extension for this child — not just skips adding extras. That
+	// silently strips load-bearing ambient extensions (e.g. a model provider
+	// extension), so a provider-qualified model pin becomes unresolvable in the
+	// child with no error pointing back at the override that caused it.
+	if (capabilityCeiling?.denyExtensions !== true && Array.isArray(input.extensions) && input.extensions.length === 0) {
+		const agentLabel = input.agentName ? ` for agent '${input.agentName}'` : "";
+		warnings.push(
+			`extensions: [] override${agentLabel} disables ALL ambient extensions for this child (not just "adds nothing"), `
+				+ "including any model-provider extension needed to resolve a provider-qualified model. "
+				+ "List the extensions this child actually needs instead of an empty array.",
+		);
+	}
 	const configuredExtensions = capabilityCeiling?.denyExtensions
 		? []
 		: [
@@ -540,6 +570,7 @@ export function resolvePiLaunchToolPlan(
 		configuredExtensions,
 		extensionArgs,
 		disableAmbientExtensions,
+		warnings,
 		...(capabilityAudit ? { capabilityAudit } : {}),
 	};
 }
@@ -587,6 +618,7 @@ export function buildPiArgs(input: BuildPiArgsInput): BuildPiArgsResult {
 			process.env[SUBAGENT_CAPABILITY_CEILING_ENV],
 		),
 		agentName: input.childAgentName,
+		permissionRules: input.permissionRules,
 	});
 	if (toolPlan.explicitToolAllowlist) {
 		args.push(
@@ -829,6 +861,7 @@ export function buildPiArgs(input: BuildPiArgsInput): BuildPiArgsResult {
 	return {
 		args,
 		env,
+		warnings: toolPlan.warnings,
 		tempDir,
 		toolDiagnosticPath,
 		runtimeAcknowledgedExtensionsPath,

package/src/runs/shared/subagent-control.ts

@@ -17,6 +17,7 @@ const DEFAULT_NOTIFY_ON: ControlEventType[] = ["active_long_running", "needs_att
 export const DEFAULT_CONTROL_CONFIG: ResolvedControlConfig = {
 	enabled: true,
 	needsAttentionAfterMs: 60_000,
+	needsAttentionAfterMsIsExplicit: false,
 	activeNoticeAfterMs: 240_000,
 	failedToolAttemptsBeforeAttention: 3,
 	notifyOn: DEFAULT_NOTIFY_ON,
@@ -42,9 +43,13 @@ export function resolveControlConfig(
 	override?: ControlConfig,
 ): ResolvedControlConfig {
 	const enabled = override?.enabled ?? globalConfig?.enabled ?? DEFAULT_CONTROL_CONFIG.enabled;
-	const needsAttentionAfterMs = parsePositiveInt(override?.needsAttentionAfterMs)
-		?? parsePositiveInt(globalConfig?.needsAttentionAfterMs)
+	const overrideNeedsAttentionAfterMs = parsePositiveInt(override?.needsAttentionAfterMs);
+	const globalNeedsAttentionAfterMs = parsePositiveInt(globalConfig?.needsAttentionAfterMs);
+	const needsAttentionAfterMs = overrideNeedsAttentionAfterMs
+		?? globalNeedsAttentionAfterMs
 		?? DEFAULT_CONTROL_CONFIG.needsAttentionAfterMs;
+	const needsAttentionAfterMsIsExplicit = overrideNeedsAttentionAfterMs !== undefined
+		|| globalNeedsAttentionAfterMs !== undefined;
 	const activeNoticeAfterMs = parsePositiveInt(override?.activeNoticeAfterMs)
 		?? parsePositiveInt(globalConfig?.activeNoticeAfterMs)
 		?? DEFAULT_CONTROL_CONFIG.activeNoticeAfterMs;
@@ -64,6 +69,7 @@ export function resolveControlConfig(
 	return {
 		enabled,
 		needsAttentionAfterMs,
+		needsAttentionAfterMsIsExplicit,
 		activeNoticeAfterMs,
 		activeNoticeAfterTurns,
 		activeNoticeAfterTokens,
@@ -73,18 +79,34 @@ export function resolveControlConfig(
 	};
 }
 
+function scaledNeedsAttentionAfterMs(config: ResolvedControlConfig, thinking?: string | false): number {
+	if (config.needsAttentionAfterMsIsExplicit !== false) return config.needsAttentionAfterMs;
+	switch (thinking) {
+		case "medium":
+			return config.needsAttentionAfterMs * 2;
+		case "high":
+			return config.needsAttentionAfterMs * 5;
+		case "xhigh":
+		case "max":
+			return config.needsAttentionAfterMs * 10;
+		default:
+			return config.needsAttentionAfterMs;
+	}
+}
+
 export function deriveActivityState(input: {
 	config: ResolvedControlConfig;
 	startedAt: number;
 	lastActivityAt?: number;
 	currentTool?: string;
+	thinking?: string | false;
 	now?: number;
 }): ActivityState | undefined {
 	if (!input.config.enabled || input.currentTool) return undefined;
 	const now = input.now ?? Date.now();
 	const lastActivity = input.lastActivityAt ?? input.startedAt;
 	const ageMs = Math.max(0, now - lastActivity);
-	return ageMs > input.config.needsAttentionAfterMs ? "needs_attention" : undefined;
+	return ageMs > scaledNeedsAttentionAfterMs(input.config, input.thinking) ? "needs_attention" : undefined;
 }
 
 export function shouldEmitOpenToolAttention(input: {

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

@@ -21,7 +21,7 @@ import type { JsonSchemaObject, ResolvedToolBudget, SubagentState } from "../../
 import { resolveCurrentSessionId } from "../../shared/session-identity.ts";
 import { resolveWatchPath } from "../../shared/utils.ts";
 import { registerChildWatchdog } from "../../watchdog/register-child.ts";
-import { CHILD_WATCHDOG_CONFIG_ENV } from "../../watchdog/child-status.ts";
+import { CHILD_WATCHDOG_CONFIG_ENV, decodeChildWatchdogConfig } from "../../watchdog/child-status.ts";
 import { requestWatchdogPermission, type WatchdogPermissionRequest, type WatchdogPermissionResult } from "../../watchdog/permission-arbiter.ts";
 import { SUBAGENT_WATCHDOG_WARNING_TYPE } from "../../watchdog/types.ts";
 import { resolveWaitToolConfig } from "../background/wait-config.ts";
@@ -296,14 +296,41 @@ export function registerPermissionGate(
 		const decision = permissionDecision(rules, toolName);
 		if (decision === "allow") return undefined;
 		if (decision === "deny") return { block: true, reason: `Blocked by pi-subagents permission rule: '${toolName}' is denied.` };
-		const result = await requestPermission({
-			ctx,
-			toolName,
-			args: event.input ?? {},
-			rawWatchdogConfig: process.env[CHILD_WATCHDOG_CONFIG_ENV],
-			auditPath: process.env[PERMISSION_AUDIT_PATH_ENV],
-			...(ctx.signal ? { signal: ctx.signal } : {}),
-		});
+		const rawWatchdogConfig = process.env[CHILD_WATCHDOG_CONFIG_ENV];
+		let timeoutMs = 30_000;
+		try {
+			timeoutMs = decodeChildWatchdogConfig(rawWatchdogConfig)?.agentEndTimeoutMs ?? timeoutMs;
+		} catch {
+			// The arbiter reports invalid configuration with the concrete decode error.
+		}
+		if (ctx.signal?.aborted) return { block: true, reason: "Blocked by pi-subagents permission rule: Watchdog permission decision was cancelled." };
+		let timeout: ReturnType<typeof setTimeout> | undefined;
+		let abort: (() => void) | undefined;
+		let result: WatchdogPermissionResult;
+		try {
+			result = await Promise.race([
+				requestPermission({
+					ctx,
+					toolName,
+					args: event.input ?? {},
+					rawWatchdogConfig,
+					auditPath: process.env[PERMISSION_AUDIT_PATH_ENV],
+					...(ctx.signal ? { signal: ctx.signal } : {}),
+				}),
+				new Promise<WatchdogPermissionResult>((resolve) => {
+					if (!ctx.signal) return;
+					abort = () => resolve({ approved: false, reason: "Watchdog permission decision was cancelled.", source: "watchdog" });
+					ctx.signal.addEventListener("abort", abort, { once: true });
+				}),
+				new Promise<never>((_, reject) => { timeout = setTimeout(() => reject(new Error(`Watchdog permission decision timed out after ${timeoutMs}ms.`)), timeoutMs); }),
+			]);
+		} catch (error) {
+			const reason = error instanceof Error ? error.message : String(error);
+			return { block: true, reason: `Blocked by pi-subagents permission rule: Watchdog permission arbiter failed closed: ${reason}` };
+		} finally {
+			if (timeout) clearTimeout(timeout);
+			if (abort) ctx.signal?.removeEventListener("abort", abort);
+		}
 		if (result.approved) return undefined;
 		return { block: true, reason: `Blocked by pi-subagents permission rule: ${result.reason}` };
 	});

package/src/shared/fork-context.ts

@@ -208,7 +208,23 @@ export function createForkContextResolver(
 	const openSession = options.openSession
 		?? sessionManager.openSession
 		?? ((file: string, dir?: string) => SessionManager.open(file, dir));
-	const sessionDir = sessionManager.getSessionDir?.();
+	// Fork files must not land in the parent's top-level session directory.
+	// Pi's recent-session discovery (`pi -c` → findMostRecentSession) is
+	// non-recursive and picks the largest-mtime *.jsonl in that directory, so
+	// a still-running forked subagent — which keeps appending after the parent
+	// went idle — would hijack the next `pi -c` away from the conversation the
+	// user actually left. Nesting fork sessions in a per-parent directory keeps
+	// them invisible to that discovery; the `parentSession` header still
+	// records the tree relationship. The directory mirrors
+	// getSubagentSessionRoot() plus a "forks" level so fork files never sit
+	// loose next to run-N/ result directories. Derived from the file path
+	// rather than getSessionDir() so it also works when the manager cannot
+	// report its directory.
+	const sessionDir = path.join(
+		path.dirname(parentSessionFile),
+		path.basename(parentSessionFile, ".jsonl"),
+		"forks",
+	);
 	const cachedResolutions = new Map<number, ForkContextResolution>();
 
 	const resolveFork = (index = 0): ForkContextResolution => {

package/src/shared/model-info.ts

@@ -1,3 +1,5 @@
+import type { ModelCost } from "@earendil-works/pi-ai";
+
 export const THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh", "max"] as const;
 export type ThinkingLevel = typeof THINKING_LEVELS[number];
 export type ThinkingLevelMap = Partial<Record<ThinkingLevel, string | null>>;
@@ -9,6 +11,14 @@ export interface ModelInfo {
 	api?: string;
 	reasoning?: boolean;
 	thinkingLevelMap?: ThinkingLevelMap;
+	/** Context window in tokens, when the host model registry reports one. */
+	contextWindow?: number;
+	/** Maximum output tokens, when the host model registry reports one. */
+	maxTokens?: number;
+	/** Input modalities reported by the registry, e.g. ["text", "image"]. */
+	input?: string[];
+	/** Per-token pricing from the registry (USD per 1M tokens). */
+	cost?: ModelCost;
 }
 
 interface RegistryModelLike {
@@ -17,6 +27,10 @@ interface RegistryModelLike {
 	api?: string;
 	reasoning?: boolean;
 	thinkingLevelMap?: ThinkingLevelMap;
+	contextWindow?: number;
+	maxTokens?: number;
+	input?: string[];
+	cost?: ModelCost;
 }
 
 export function toModelInfo(model: RegistryModelLike): ModelInfo {
@@ -27,6 +41,12 @@ export function toModelInfo(model: RegistryModelLike): ModelInfo {
 		api: model.api,
 		reasoning: model.reasoning,
 		thinkingLevelMap: model.thinkingLevelMap,
+		...(typeof model.contextWindow === "number" && Number.isFinite(model.contextWindow) && model.contextWindow > 0 ? { contextWindow: model.contextWindow } : {}),
+		...(typeof model.maxTokens === "number" && Number.isFinite(model.maxTokens) && model.maxTokens > 0 ? { maxTokens: model.maxTokens } : {}),
+		...(Array.isArray(model.input) && model.input.length > 0 ? { input: [...model.input] } : {}),
+		...(model.cost && Number.isFinite(model.cost.input) && Number.isFinite(model.cost.output)
+			? { cost: { ...model.cost, ...(model.cost.tiers ? { tiers: model.cost.tiers.map((tier) => ({ ...tier })) } : {}) } }
+			: {}),
 	};
 }
 

package/src/shared/settings.ts

@@ -282,7 +282,7 @@ export function resolveStepBehavior(
 		}
 	}
 
-	const outputMode = stepOverrides.outputMode ?? "inline";
+	const outputMode = stepOverrides.outputMode ?? agentConfig.outputMode ?? "inline";
 	const model = stepOverrides.model ?? agentConfig.model;
 	return { output, outputMode, reads, progress, skills, model };
 }
@@ -465,7 +465,7 @@ export function resolveParallelBehaviors(
 			}
 		}
 
-		const outputMode = task.outputMode ?? "inline";
+		const outputMode = task.outputMode ?? config.outputMode ?? "inline";
 		const model = task.model ?? config.model;
 		return { output, outputMode, reads, progress, skills, model };
 	});

package/src/shared/types.ts

@@ -8,7 +8,7 @@ import type { Message } from "@earendil-works/pi-ai";
 import type { AgentConfig } from "../agents/agents.ts";
 import type { FSWatcher } from "node:fs";
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
-import type { ModelScopeConfig } from "../runs/shared/model-scope.ts";
+import type { ModelScopeRule } from "../runs/shared/model-scope.ts";
 import type { ResolvedSubagentCapabilityCeiling, SubagentCapabilityAudit } from "../runs/shared/capability-ceiling.ts";
 import type { AuthorityPolicyConfig } from "../policy/authority.ts";
 import type { GlobalMissionIndexRecord, MissionRecord, MissionStoreConfig } from "../missions/types.ts";
@@ -71,6 +71,29 @@ export interface WorkflowGraphSnapshot {
 	currentNodeId?: string;
 }
 
+export type WorkflowReceiptState = "complete" | "failed" | "paused" | "stopped";
+
+type WorkflowReceiptEntryResumability =
+	| { latestRunId: string; resumability: { state: "resumable" } }
+	| { latestRunId?: string; resumability: { state: "not-resumable"; reason: string } };
+
+export type WorkflowReceiptEntry = WorkflowReceiptEntryResumability & {
+	key: string;
+	agent?: string;
+	requestedContext?: "fresh" | "fork";
+	resolvedContext?: "fresh" | "fork" | "mixed";
+	outputReference?: string;
+	continuation: { runIds: string[] };
+};
+
+export interface WorkflowReceipt {
+	version: 1;
+	workflowRunId: string;
+	state: WorkflowReceiptState;
+	createdAt: number;
+	entries: Record<string, WorkflowReceiptEntry>;
+}
+
 export interface SavedOutputReference {
 	path: string;
 	bytes: number;
@@ -161,6 +184,7 @@ export interface ControlConfig {
 export interface ResolvedControlConfig {
 	enabled: boolean;
 	needsAttentionAfterMs: number;
+	needsAttentionAfterMsIsExplicit?: boolean;
 	activeNoticeAfterMs: number;
 	activeNoticeAfterTurns?: number;
 	activeNoticeAfterTokens?: number;
@@ -529,6 +553,8 @@ export interface SteeringRecoveryDescriptor {
 	structuredOutputSchema?: JsonSchemaObject;
 	acceptance?: AcceptanceInput;
 	controlConfig?: ResolvedControlConfig;
+	/** Resolved launch context for this async child. */
+	context?: "fresh" | "fork";
 	/** Raw per-run bridge override. Omitted descriptors continue to use global config. */
 	intercomBridge?: IntercomBridgeConfig;
 	absoluteDeadlineAt?: number;
@@ -931,6 +957,13 @@ export interface SingleResult {
 	modelAttempts?: ModelAttempt[];
 	controlEvents?: ControlEvent[];
 	error?: string;
+	/**
+	 * True when the dispatch failed because the input exceeded the model's
+	 * context window. The model fallback loop stops immediately (retrying the
+	 * same input on another model cannot succeed). Callers should treat this as
+	 * a signal to reduce input size or re-decompose the task.
+	 */
+	contextOverflow?: boolean;
 	protocolError?: ProtocolOutputLimit;
 	sessionFile?: string;
 	skills?: string[];
@@ -996,6 +1029,7 @@ export interface WaitCompletionChild {
 	outputState?: SubagentOutputState;
 	error?: string;
 	model?: string;
+	contextOverflow?: boolean;
 	artifactPaths?: Partial<ArtifactPaths>;
 }
 
@@ -1099,6 +1133,8 @@ export interface Details {
 		}>;
 		emits: unknown[];
 		console: Array<{ level: "log" | "info" | "warn" | "error"; text: string }>;
+		/** Terminal keyed child receipt. Async workflows also persist it beside status.json. */
+		receipt?: WorkflowReceipt;
 	};
 	chatProgress?: {
 		mode: "off" | "live-card";
@@ -1468,6 +1504,8 @@ export interface AsyncStatus {
 		thinking?: string;
 		attemptedModels?: string[];
 		modelAttempts?: ModelAttempt[];
+		/** True when the child input exceeded the model context window. */
+		contextOverflow?: boolean;
 		totalCost?: CostSummary;
 		steering?: SteeringStatus;
 		error?: string;
@@ -1862,7 +1900,7 @@ export interface RunSyncOptions {
 	/** Current parent-session provider to prefer for ambiguous bare model ids */
 	preferredModelProvider?: string;
 	/** Optional subagent model-scope enforcement for fallback candidates */
-	modelScope?: ModelScopeConfig;
+	modelScope?: ModelScopeRule | ModelScopeRule[];
 	/** Skills to make available (overrides agent default if provided) */
 	skills?: string[];
 	structuredOutput?: {
@@ -2026,6 +2064,13 @@ export interface ExtensionConfig {
 	/** Artifact cleanup retention. Set cleanupDays to 0 to disable cleanup. */
 	artifactConfig?: Pick<ArtifactConfig, "cleanupDays">;
 	intercomBridge?: IntercomBridgeConfig;
+	/** Control how slow result-index scans are logged. Defaults to \"activity\".
+	 *  - \"all\": log every slow scan, including scans that find nothing.
+	 *  - \"activity\": log only slow scans that found or scheduled work. Silences
+	 *    the periodic healthy rescan that inspects zero files while no async runs
+	 *    are pending, which otherwise spams the session transcript.
+	 *  - \"off\": never log slow result-index scans. */
+	resultScanLogging?: "all" | "activity" | "off";
 	proactiveSkillSubagents?: ProactiveSkillSubagentsConfig | false;
 	scheduledRuns?: ScheduledRunsConfig;
 	/** Durable mission behavior. Missions are automatic by default; set enabled:false to disable auto-create. Explicit mission actions/fields still work. */