pi-subagents 0.53.0 → 0.54.0

package/src/agents/agents.ts

@@ -110,6 +110,9 @@ export interface AgentConfig {
 	runner?: AgentRunnerConfig;
 	localName?: string;
 	packageName?: string;
+	packageSourceName?: string;
+	packageSourceVersion?: string;
+	packageSourceRoot?: string;
 	description: string;
 	aliases?: string[];
 	tools?: string[];
@@ -255,8 +258,15 @@ function getUserChainDir(): string {
 	return path.join(getAgentDir(), "chains");
 }
 
+interface PackageSubagentPath {
+	dir: string;
+	packageName?: string;
+	packageVersion?: string;
+	packageRoot: string;
+}
+
 interface PackageSubagentPaths {
-	agents: string[];
+	agents: PackageSubagentPath[];
 	chains: string[];
 }
 
@@ -391,18 +401,30 @@ function stringArray(value: unknown): string[] {
 	return value.filter((entry): entry is string => typeof entry === "string" && entry.trim().length > 0);
 }
 
+function packageMetadata(pkg: Record<string, unknown>, packageRoot: string): Omit<PackageSubagentPath, "dir"> {
+	const name = typeof pkg.name === "string" && pkg.name.trim() ? pkg.name.trim() : undefined;
+	const version = typeof pkg.version === "string" && pkg.version.trim() ? pkg.version.trim() : undefined;
+	return {
+		packageRoot,
+		...(name ? { packageName: name } : {}),
+		...(version ? { packageVersion: version } : {}),
+	};
+}
+
 function extractSubagentPathsFromPackageRoot(packageRoot: string): PackageSubagentPaths {
 	const packageJsonPath = path.join(packageRoot, "package.json");
 	const pkg = readJsonFileBestEffort(packageJsonPath);
 	if (!pkg || typeof pkg !== "object" || Array.isArray(pkg)) return { agents: [], chains: [] };
+	const pkgRecord = pkg as Record<string, unknown>;
+	const metadata = packageMetadata(pkgRecord, packageRoot);
 
 	const roots: Record<string, unknown>[] = [];
-	const piSubagents = (pkg as { "pi-subagents"?: unknown })["pi-subagents"];
+	const piSubagents = pkgRecord["pi-subagents"];
 	if (piSubagents && typeof piSubagents === "object" && !Array.isArray(piSubagents)) {
 		roots.push(piSubagents as Record<string, unknown>);
 	}
 
-	const pi = (pkg as { pi?: unknown }).pi;
+	const pi = pkgRecord.pi;
 	if (pi && typeof pi === "object" && !Array.isArray(pi)) {
 		const subagents = (pi as { subagents?: unknown }).subagents;
 		if (subagents && typeof subagents === "object" && !Array.isArray(subagents)) {
@@ -410,10 +432,10 @@ function extractSubagentPathsFromPackageRoot(packageRoot: string): PackageSubage
 		}
 	}
 
-	const agents: string[] = [];
+	const agents: PackageSubagentPath[] = [];
 	const chains: string[] = [];
 	for (const root of roots) {
-		for (const entry of stringArray(root.agents)) agents.push(path.resolve(packageRoot, entry));
+		for (const entry of stringArray(root.agents)) agents.push({ dir: path.resolve(packageRoot, entry), ...metadata });
 		for (const entry of stringArray(root.chains)) chains.push(path.resolve(packageRoot, entry));
 	}
 	return { agents, chains };
@@ -505,17 +527,17 @@ function collectPackageSubagentPaths(cwd: string, options: { includeUser: boolea
 	const seenRoots = new Set<string>();
 	const seenAgents = new Set<string>();
 	const seenChains = new Set<string>();
-	const agents: string[] = [];
+	const agents: PackageSubagentPath[] = [];
 	const chains: string[] = [];
 	for (const packageRoot of packageRoots) {
 		const resolvedRoot = path.resolve(packageRoot);
 		if (seenRoots.has(resolvedRoot)) continue;
 		seenRoots.add(resolvedRoot);
 		const paths = extractSubagentPathsFromPackageRoot(resolvedRoot);
-		for (const agentDir of paths.agents) {
-			if (seenAgents.has(agentDir)) continue;
-			seenAgents.add(agentDir);
-			agents.push(agentDir);
+		for (const agentPath of paths.agents) {
+			if (seenAgents.has(agentPath.dir)) continue;
+			seenAgents.add(agentPath.dir);
+			agents.push(agentPath);
 		}
 		for (const chainDir of paths.chains) {
 			if (seenChains.has(chainDir)) continue;
@@ -1233,7 +1255,18 @@ function applyCustomAgentOverride(
 	if (override.acceptanceRole !== undefined) {
 		fill("acceptanceRole", ["acceptanceRole"], override.acceptanceRole === false ? undefined : override.acceptanceRole);
 	}
-	if (override.disabled !== undefined && agent.disabled === undefined) {
+	if (override.disabled !== undefined) {
+		// Unconditional, matching applyBuiltinOverride: custom agents have no
+		// frontmatter concept of `disabled` to protect (unlike model/thinking/
+		// etc., which use `fill()` + agentHasFrontmatterField to defer to the
+		// agent's own file). A guard here previously read `agent.disabled ===
+		// undefined`, which was a no-op before user+project layering existed
+		// (this function only ever ran once, against the pristine base agent,
+		// whose `.disabled` is always undefined for custom agents) but became a
+		// real bug once a user-scope override could run first: the guard then
+		// silently blocked a later project-scope override from ever changing
+		// `disabled`, breaking this PR's own "project wins" precedence for this
+		// one field.
 		mutable().disabled = override.disabled;
 		anyFilled = true;
 	}
@@ -1275,18 +1308,25 @@ function applyCustomAgentOverrides(
 	userSettingsPath: string,
 	projectSettingsPath: string | null,
 ): AgentConfig[] {
+	// Both scopes are applied, user first then project, so a project override that
+	// only sets a subset of fields (e.g. just `extensions`) layers on top of the
+	// user's override instead of silently discarding it (#1341 / issue writeup:
+	// "agentOverrides project override drops user-only fields for custom agents").
+	// Per-field precedence still favors project over user: applyCustomAgentOverride
+	// only fills fields present in the override it's given, and project is applied
+	// last, so any field set at both scopes ends up with the project's value.
 	return agents.map((agent) => {
+		const userOverride = userSettings.overrides[agent.name];
+		const withUserOverride = userOverride
+			? applyCustomAgentOverride(agent, userOverride, { scope: "user", path: userSettingsPath })
+			: agent;
+
 		const projectOverride = projectSettings.overrides[agent.name];
 		if (projectOverride && projectSettingsPath) {
-			return applyCustomAgentOverride(agent, projectOverride, { scope: "project", path: projectSettingsPath });
-		}
-
-		const userOverride = userSettings.overrides[agent.name];
-		if (userOverride) {
-			return applyCustomAgentOverride(agent, userOverride, { scope: "user", path: userSettingsPath });
+			return applyCustomAgentOverride(withUserOverride, projectOverride, { scope: "project", path: projectSettingsPath });
 		}
 
-		return agent;
+		return withUserOverride;
 	});
 }
 
@@ -1615,7 +1655,7 @@ function resolveAgentRelativeExtensionPaths(paths: string[] | undefined, agentFi
 	});
 }
 
-function loadAgentsFromDefinitionFiles(files: AgentDefinitionFile[], source: AgentSource, discoveryPriority?: number): { agents: AgentConfig[]; diagnostics: AgentDiscoveryDiagnostic[] } {
+function loadAgentsFromDefinitionFiles(files: AgentDefinitionFile[], source: AgentSource, discoveryPriority?: number, packageSource?: Omit<PackageSubagentPath, "dir">): { agents: AgentConfig[]; diagnostics: AgentDiscoveryDiagnostic[] } {
 	const agents: AgentConfig[] = [];
 	const diagnostics: AgentDiscoveryDiagnostic[] = [];
 
@@ -1750,6 +1790,9 @@ function loadAgentsFromDefinitionFiles(files: AgentDefinitionFile[], source: Age
 			...(runner !== undefined ? { runner } : {}),
 			localName,
 			...(packageName !== undefined ? { packageName } : {}),
+			...(packageSource?.packageName ? { packageSourceName: packageSource.packageName } : {}),
+			...(packageSource?.packageVersion ? { packageSourceVersion: packageSource.packageVersion } : {}),
+			...(packageSource?.packageRoot ? { packageSourceRoot: packageSource.packageRoot } : {}),
 			description: frontmatter.description,
 			...(aliases !== undefined ? { aliases } : {}),
 			...(rawTools !== undefined ? { tools } : {}),
@@ -1797,8 +1840,8 @@ function loadAgentsFromDefinitionFiles(files: AgentDefinitionFile[], source: Age
 	return { agents, diagnostics };
 }
 
-function loadAgentsFromDir(dir: string, source: AgentSource, discoveryPriority?: number): { agents: AgentConfig[]; diagnostics: AgentDiscoveryDiagnostic[] } {
-	return loadAgentsFromDefinitionFiles(readAgentDefinitionFiles(dir), source, discoveryPriority);
+function loadAgentsFromDir(dir: string, source: AgentSource, discoveryPriority?: number, packageSource?: Omit<PackageSubagentPath, "dir">): { agents: AgentConfig[]; diagnostics: AgentDiscoveryDiagnostic[] } {
+	return loadAgentsFromDefinitionFiles(readAgentDefinitionFiles(dir), source, discoveryPriority, packageSource);
 }
 
 function loadChainsFromDir(dir: string, source: AgentSource): { chains: ChainConfig[]; diagnostics: ChainDiscoveryDiagnostic[] } {
@@ -1924,7 +1967,7 @@ export function discoverAgents(cwd: string, scope: AgentScope): AgentDiscoveryRe
 		userSettingsPath,
 		projectSettingsPath,
 	);
-	const packageLoaded = packageSubagentPaths.agents.map((dir, index) => loadAgentsFromDir(dir, "package", packageSubagentPaths.agents.length - index));
+	const packageLoaded = packageSubagentPaths.agents.map((entry, index) => loadAgentsFromDir(entry.dir, "package", packageSubagentPaths.agents.length - index, entry));
 	const packageMap = new Map<string, AgentConfig>();
 	for (const loaded of packageLoaded) {
 		for (const agent of loaded.agents) {
@@ -1998,8 +2041,8 @@ export function discoverAgentsAll(cwd: string): {
 	);
 	const packageMap = new Map<string, AgentConfig>();
 	const packageAgentDiagnostics: AgentDiscoveryDiagnostic[] = [];
-	for (const [index, dir] of packageSubagentPaths.agents.entries()) {
-		const loaded = loadAgentsFromDir(dir, "package", packageSubagentPaths.agents.length - index);
+	for (const [index, entry] of packageSubagentPaths.agents.entries()) {
+		const loaded = loadAgentsFromDir(entry.dir, "package", packageSubagentPaths.agents.length - index, entry);
 		packageAgentDiagnostics.push(...loaded.diagnostics);
 		for (const agent of loaded.agents) {
 			if (!packageMap.has(agent.name)) packageMap.set(agent.name, agent);

package/src/api/preflight.ts

@@ -7,6 +7,7 @@ import { resolveExecutionAgentScope } from "../agents/agent-scope.ts";
 import { buildSkillInjection, normalizeSkillInput, resolveSkillsWithFallback } from "../agents/skills.ts";
 import { buildAgentMemoryInjection } from "../agents/agent-memory.ts";
 import { buildModelCandidates, inheritsParentModel, resolveEffectiveSubagentModel, type AvailableModelInfo, type ParentModel } from "../runs/shared/model-fallback.ts";
+import { resolveModelScopesForAgent } from "../runs/shared/model-scope.ts";
 import { applyThinkingSuffix, resolvePiLaunchToolPlan, type PiLaunchToolPlan } from "../runs/shared/pi-args.ts";
 import { injectOutputPathSystemPrompt, normalizeSingleOutputOverride, resolveSingleOutputPath } from "../runs/shared/single-output.ts";
 import { getArtifactPaths, getArtifactsDir } from "../shared/artifacts.ts";
@@ -14,6 +15,7 @@ import { resolveEffectiveThinking } from "../shared/model-info.ts";
 import { SUBAGENT_LIFECYCLE_ARTIFACT_VERSION, type ArtifactDirPreference, type ArtifactPaths, type JsonSchemaObject, type OutputMode } from "../shared/types.ts";
 import { capabilityCeilingAgentRestrictionMessage, intersectSubagentCapabilityCeilings, type ResolvedSubagentCapabilityCeiling, type SubagentCapabilityAudit } from "../runs/shared/capability-ceiling.ts";
 import { appendTurnBudgetSystemPrompt } from "../runs/shared/turn-budget.ts";
+import { resolvePermissionRules } from "../runs/shared/permissions.ts";
 import type { ResolvedTurnBudget } from "../shared/types.ts";
 import type { ResolvedMcpDirectToolSelection } from "../runs/shared/mcp-direct-tool-allowlist.ts";
 import { resolveStepBehavior } from "../shared/settings.ts";
@@ -288,19 +290,21 @@ export async function resolveSubagentLaunchContract(input: SubagentLaunchContrac
 	const externalRunner = agent.runner?.type === "external-cli" || agent.runner?.type === "external-job";
 	const availableModels = normalizeAvailableModels(input.availableModels);
 	const preferredProvider = input.preferredProvider ?? input.parentModel?.provider;
+	const modelScopes = resolveModelScopesForAgent(discovered.modelScope, agent.name, input.parentModel);
 	const primaryModel = externalRunner
 		? undefined
-		: resolveEffectiveSubagentModel(input.model, agent.model, input.parentModel, availableModels, preferredProvider, { scope: discovered.modelScope });
+		: resolveEffectiveSubagentModel(input.model, agent.model, input.parentModel, availableModels, preferredProvider, { scope: modelScopes });
 	const effectiveThinkingConfig = input.thinking !== undefined ? input.thinking : agent.thinking;
 	const model = externalRunner ? undefined : applyThinkingSuffix(primaryModel, effectiveThinkingConfig, input.thinking !== undefined);
 	const modelCandidates = externalRunner
 		? []
 		: buildModelCandidates(primaryModel, agent.fallbackModels, availableModels, preferredProvider, {
-			scope: discovered.modelScope,
+			scope: modelScopes,
 			primaryModelFromParent: inheritsParentModel(input.model, agent.model, input.parentModel),
 		})
 			.map((candidate) => applyThinkingSuffix(candidate, effectiveThinkingConfig, input.thinking !== undefined) ?? candidate);
 	let toolPlan: PiLaunchToolPlan;
+	const permissionRules = resolvePermissionRules(loadConfig().permissions, agent.permissions);
 	try {
 		toolPlan = resolvePiLaunchToolPlan({
 			tools: agent.tools,
@@ -312,6 +316,7 @@ export async function resolveSubagentLaunchContract(input: SubagentLaunchContrac
 			structuredOutput: Boolean(input.outputSchema),
 			capabilityCeiling: effectiveCapabilityCeiling,
 			agentName: agent.name,
+			permissionRules,
 		});
 	} catch (error) {
 		const message = error instanceof Error ? error.message : String(error);

package/src/extension/doctor.ts

@@ -224,6 +224,13 @@ function formatPermissionSystemSection(): string[] {
 	return lines;
 }
 
+function formatWorkflowScriptSection(): string[] {
+	return [
+		"- helpers: runs.run, runs.all, runs.steer, runs.status, runs.ref/refs, emit, console",
+		"- recovery: if runs.all is missing, reload or update pi-subagents; await Promise.all([runs.run(...)]) is also supported",
+	];
+}
+
 export function buildDoctorReport(input: DoctorReportInput): string {
 	const paths = input.paths ?? defaultPaths();
 	const deps = { ...DEFAULT_DEPS, ...input.deps };
@@ -253,6 +260,9 @@ export function buildDoctorReport(input: DoctorReportInput): string {
 		"Active async capacity",
 		...formatActiveAsyncCapacitySection(input),
 		"",
+		"Workflow script",
+		...formatWorkflowScriptSection(),
+		"",
 		"Permission system",
 		...formatPermissionSystemSection(),
 		"",

package/src/extension/fanout-child.ts

@@ -11,6 +11,7 @@ import { readNestedControlRequests, resolveNestedRouteFromEnv, type NestedRoute,
 import { deliverSubagentIntercomMessageEvent } from "../intercom/result-intercom.ts";
 import { resolveSubagentIntercomTarget } from "../intercom/intercom-bridge.ts";
 import { createSubagentParamsSchema } from "./schemas.ts";
+import { finalizeToolResult } from "./tool-result.ts";
 import { loadConfig, resolveAsyncByDefault } from "./config.ts";
 import { type Details, type SubagentState } from "../shared/types.ts";
 
@@ -181,8 +182,8 @@ export default function registerFanoutChildSubagentExtension(pi: ExtensionAPI):
 			"Mutating management actions (create, update, delete, eject, disable, enable, reset, grant-spawn-budget) are blocked in this mode.",
 		].join("\n"),
 		parameters: params,
-		execute(id, params, signal, onUpdate, ctx) {
-			return executor.executePublic(id, params as SubagentParamsLike, signal ?? new AbortController().signal, onUpdate, ctx);
+		async execute(id, params, signal, onUpdate, ctx) {
+			return finalizeToolResult(await executor.executePublic(id, params as SubagentParamsLike, signal ?? new AbortController().signal, onUpdate, ctx));
 		},
 	};
 

package/src/extension/index.ts

@@ -57,6 +57,7 @@ import { resolveCurrentSubagentCapabilityCeiling } from "../runs/shared/capabili
 import { formatDuration, shortenPath } from "../shared/formatters.ts";
 import { loadConfig, resolveAsyncByDefault, resolveScheduledStoreRoot } from "./config.ts";
 import { buildSubagentToolDescription, buildSubagentToolPromptMetadata } from "./tool-description.ts";
+import { finalizeToolResult } from "./tool-result.ts";
 import { collectGoalContinuationNotices } from "../missions/goal-driver.ts";
 import { restoreForegroundRunHistory } from "../runs/foreground/foreground-history.ts";
 import { resolveMissionStoreLocation } from "../missions/store.ts";
@@ -517,7 +518,7 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 			observedCompletionRunIds: () => scheduledRunManager.observedCompletionRunIds(),
 			hasDeliveryDemand: hasResultDeliveryDemand,
 			deliverIntercomResults: config.intercomBridge?.resultDelivery === true,
-			resultScanLogging: config.resultScanLogging ?? "all",
+			resultScanLogging: config.resultScanLogging,
 		},
 	);
 	const { startResultWatcher, primeExistingResults, stopResultWatcher } = resultWatcher;
@@ -658,8 +659,8 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 		...buildSubagentToolPromptMetadata(config),
 		parameters,
 
-		execute(id, params, signal, onUpdate, ctx) {
-			return executeSubagentCollapsed(id, params as SubagentParamsLike, signal ?? new AbortController().signal, onUpdate, ctx);
+		async execute(id, params, signal, onUpdate, ctx) {
+			return finalizeToolResult(await executeSubagentCollapsed(id, params as SubagentParamsLike, signal ?? new AbortController().signal, onUpdate, ctx));
 		},
 
 		renderCall(args, theme) {

package/src/extension/public-execution.ts

@@ -122,7 +122,7 @@ export function normalizePublicSubagentExecution<T extends PublicSubagentExecuti
 			params: {
 				...workflowDefaults,
 				...(params.async === undefined && options.asyncByDefault === false ? { async: false } : {}),
-				workflowScript: `console.info("Converted structured single-child request to workflow runs.run('main', ...)."); return runs.run("main", ${JSON.stringify(child)})`,
+				workflowScript: `return runs.run("main", ${JSON.stringify(child)})`,
 			} as T,
 		};
 	}

package/src/extension/tool-result.ts

@@ -0,0 +1,19 @@
+import type { AgentToolResult } from "@earendil-works/pi-agent-core";
+
+/**
+ * Convert pi-subagents' internal logical-error result into the rejection Pi's
+ * public tool boundary uses to emit a canonical errored ToolResult.
+ *
+ * Keep this at registered tool boundaries. Internal workflows intentionally
+ * retain their return-based error handling.
+ */
+export function finalizeToolResult<T>(result: AgentToolResult<T>): AgentToolResult<T> {
+	if (result.isError !== true) return result;
+
+	const message = result.content
+		.flatMap((item) => item.type === "text" && typeof item.text === "string" ? [item.text] : [])
+		.join("\n")
+		.trim();
+
+	throw new Error(message || "pi-subagents reported a logical tool failure.");
+}

package/src/inspectors/herdr/client.ts

@@ -1,4 +1,4 @@
-import { spawn, type ChildProcess } from "node:child_process";
+import { spawn } from "node:child_process";
 
 export type HerdrErrorCode =
 	| "HERDR_UNAVAILABLE"
@@ -16,7 +16,7 @@ export interface HerdrClient {
 	run<T = unknown>(args: string[], options?: { timeoutMs?: number; signal?: AbortSignal; textOk?: boolean }): Promise<HerdrResult<T>>;
 }
 
-type SpawnHerdr = (command: string, args: readonly string[], options: { shell: false; windowsHide: true; env: NodeJS.ProcessEnv }) => ChildProcess;
+type SpawnHerdr = (command: string, args: readonly string[], options: { shell: false; windowsHide: true; env: NodeJS.ProcessEnv }) => ReturnType<typeof spawn>;
 
 function error(code: HerdrErrorCode, message: string, details?: unknown): HerdrResult<never> {
 	return { ok: false, error: { code, message, ...(details !== undefined ? { details } : {}) } };
@@ -46,7 +46,7 @@ export function createHerdrClient(options: { bin?: string; spawn?: SpawnHerdr }
 	return {
 		run<T>(args: string[], runOptions: { timeoutMs?: number; signal?: AbortSignal; textOk?: boolean } = {}): Promise<HerdrResult<T>> {
 			return new Promise((resolve) => {
-				let child: ChildProcess;
+				let child: ReturnType<typeof spawn>;
 				try {
 					child = spawnImpl(bin, args, { shell: false, windowsHide: true, env: process.env });
 				} catch (cause) {

package/src/runs/background/async-execution.ts

@@ -26,7 +26,7 @@ import { buildAgentMemoryInjection } from "../../agents/agent-memory.ts";
 import { PI_CODING_AGENT_PACKAGE_ROOT_ENV, PROMPT_REDACTED, resolveChildCwd } from "../../shared/utils.ts";
 import { buildModelCandidates, inheritsParentModel, resolveEffectiveSubagentModel, resolveModelCandidate, resolveSubagentModelOverride, type AvailableModelInfo, type ParentModel } from "../shared/model-fallback.ts";
 import { resolveToolTimeoutMs, toolTimeoutFromEnv } from "../shared/tool-timeout.ts";
-import type { ModelScopeConfig } from "../shared/model-scope.ts";
+import { resolveModelScopesForAgent, type ModelScopeConfig } from "../shared/model-scope.ts";
 import { resolveEffectiveThinking } from "../../shared/model-info.ts";
 import { resolveExpectedWorktreeAgentCwd } from "../shared/worktree.ts";
 import { buildWorkflowGraphSnapshot } from "../shared/workflow-graph.ts";
@@ -791,18 +791,20 @@ export function buildAsyncRunnerSteps(id: string, params: AsyncRunnerStepBuildPa
 		const taskText = `${readInstructions.prefix}${taskTemplate}${progressInstructions.suffix}`;
 		const task = namespaceOutputPath ? taskText : injectSingleOutputInstruction(taskText, outputPath, a);
 
+		const modelScopes = resolveModelScopesForAgent(ctx.modelScope, a.name, ctx.currentModel);
 		const primaryModel = externalRunner ? undefined : resolveEffectiveSubagentModel(
 			s.model,
 			a.model,
 			ctx.currentModel,
 			availableModels,
 			ctx.currentModelProvider,
-			{ scope: ctx.modelScope },
+			{ scope: modelScopes },
 		);
 		const thinkingOverride = flatIndex === undefined ? undefined : thinkingOverridesByFlatIndex?.[flatIndex];
 		const effectiveThinking = externalRunner ? undefined : thinkingOverride ?? a.thinking;
 		const model = externalRunner ? undefined : applyThinkingSuffix(primaryModel, effectiveThinking, thinkingOverride !== undefined);
 		const agentContract = s.agentContract ?? params.agentContract;
+		const permissionRules = resolvePermissionRules(ctx.permissions, a.permissions);
 		const toolPlan = resolvePiLaunchToolPlan({
 			tools: a.tools,
 			extensions: a.extensions,
@@ -814,9 +816,9 @@ export function buildAsyncRunnerSteps(id: string, params: AsyncRunnerStepBuildPa
 			capabilityCeiling: params.capabilityCeiling,
 			inheritedCapabilityCeiling: decodeSubagentCapabilityCeiling(process.env[SUBAGENT_CAPABILITY_CEILING_ENV]),
 			agentName: a.name,
+			permissionRules,
 		});
 		const launchResolvedExtensions = externalRunner ? undefined : projectLaunchResolvedChildExtensions(toolPlan);
-		const permissionRules = resolvePermissionRules(ctx.permissions, a.permissions);
 		if (externalRunner && permissionRules) {
 			throw new AsyncStartValidationError(`Agent '${a.name}' uses runner.type='${externalRunnerType}', which cannot enforce native Pi child permission rules.`);
 		}
@@ -839,7 +841,7 @@ export function buildAsyncRunnerSteps(id: string, params: AsyncRunnerStepBuildPa
 			thinking: resolveEffectiveThinking(model, effectiveThinking),
 			launchResolvedExtensions,
 			modelCandidates: externalRunner ? undefined : buildModelCandidates(primaryModel, a.fallbackModels, availableModels, ctx.currentModelProvider, {
-				scope: ctx.modelScope,
+				scope: modelScopes,
 				primaryModelFromParent: inheritsParentModel(s.model, a.model, ctx.currentModel),
 			}).map((candidate) =>
 				applyThinkingSuffix(candidate, effectiveThinking, thinkingOverride !== undefined),
@@ -1418,6 +1420,7 @@ export function executeAsyncSingle(
 		? `[Read from: ${readPaths.join(", ")}]\n\n`
 		: "";
 	const taskText = readsInstruction + taskWithOutputInstruction;
+	const modelScopes = resolveModelScopesForAgent(ctx.modelScope, agentConfig.name, ctx.currentModel);
 	const primaryModel = externalRunner ? undefined : params.modelOverrideFromParent
 		? params.modelOverride
 		: resolveSubagentModelOverride(
@@ -1425,6 +1428,7 @@ export function executeAsyncSingle(
 			ctx.currentModel,
 			availableModels,
 			ctx.currentModelProvider,
+			{ scope: modelScopes },
 		);
 	const effectiveThinking = externalRunner ? undefined : params.thinkingOverride ?? agentConfig.thinking;
 	const model = externalRunner ? undefined : applyThinkingSuffix(primaryModel, effectiveThinking, params.thinkingOverride !== undefined);
@@ -1453,7 +1457,7 @@ export function executeAsyncSingle(
 	const modelCandidates = externalRunner
 		? []
 		: buildModelCandidates(primaryModel, agentConfig.fallbackModels, availableModels, ctx.currentModelProvider, {
-			scope: ctx.modelScope,
+			scope: modelScopes,
 			primaryModelFromParent: params.modelOverrideFromParent,
 		})
 			.flatMap((candidate) => {
@@ -1472,6 +1476,7 @@ export function executeAsyncSingle(
 		capabilityCeiling,
 		inheritedCapabilityCeiling: decodeSubagentCapabilityCeiling(process.env[SUBAGENT_CAPABILITY_CEILING_ENV]),
 		agentName: agentConfig.name,
+		permissionRules: resolvePermissionRules(ctx.permissions, agentConfig.permissions),
 	});
 	const launchResolvedExtensions = externalRunner ? undefined : projectLaunchResolvedChildExtensions(toolPlan);
 	const launchContractDigest = launchBindingDigest({

package/src/runs/background/async-retention.ts

@@ -600,7 +600,7 @@ function runRetentionDiscovery(input: {
 		};
 		const onAbort = (): void => fail(new RetentionCancelledError("Retention discovery was cancelled."));
 		input.signal?.addEventListener("abort", onAbort, { once: true });
-		worker.once("error", (error) => fail(error));
+		worker.once("error", (error) => fail(error instanceof Error ? error : new Error(String(error))));
 		worker.once("exit", (code) => {
 			if (!settled) fail(new Error(`Retention discovery worker exited before replying (${code}).`));
 		});

package/src/runs/background/chain-root-attachment.ts

@@ -21,6 +21,7 @@ export interface ImportedAsyncRootResult {
 	model?: string;
 	attemptedModels?: string[];
 	modelAttempts?: ModelAttempt[];
+	contextOverflow?: boolean;
 	totalCost?: CostSummary;
 	structuredOutput?: unknown;
 	structuredOutputPath?: string;
@@ -49,6 +50,7 @@ interface AsyncResultFile {
 		model?: string;
 		attemptedModels?: string[];
 		modelAttempts?: ModelAttempt[];
+		contextOverflow?: boolean;
 		totalCost?: CostSummary;
 		structuredOutput?: unknown;
 		structuredOutputPath?: string;
@@ -110,6 +112,7 @@ function outputFromTerminalStatus(root: ImportedAsyncRoot, status: AsyncStatus,
 		...(step?.model ? { model: step.model } : {}),
 		...(step?.attemptedModels ? { attemptedModels: step.attemptedModels } : {}),
 		...(step?.modelAttempts ? { modelAttempts: step.modelAttempts } : {}),
+		...(step?.contextOverflow ? { contextOverflow: true } : {}),
 		...(step?.totalCost ? { totalCost: step.totalCost } : {}),
 		...(step?.structuredOutput !== undefined ? { structuredOutput: step.structuredOutput } : {}),
 		...(step?.structuredOutputPath ? { structuredOutputPath: step.structuredOutputPath } : {}),
@@ -131,6 +134,7 @@ function outputFromTimeout(root: ImportedAsyncRoot, status: AsyncStatus | null,
 		...(step?.model ? { model: step.model } : {}),
 		...(step?.attemptedModels ? { attemptedModels: step.attemptedModels } : {}),
 		...(step?.modelAttempts ? { modelAttempts: step.modelAttempts } : {}),
+		...(step?.contextOverflow ? { contextOverflow: true } : {}),
 		...(step?.totalCost ? { totalCost: step.totalCost } : {}),
 	};
 }
@@ -158,6 +162,7 @@ function buildImportedResult(root: ImportedAsyncRoot, status: AsyncStatus | null
 		...(child?.model ?? step?.model ? { model: child?.model ?? step?.model } : {}),
 		...(child?.attemptedModels ?? step?.attemptedModels ? { attemptedModels: child?.attemptedModels ?? step?.attemptedModels } : {}),
 		...(child?.modelAttempts ?? step?.modelAttempts ? { modelAttempts: child?.modelAttempts ?? step?.modelAttempts } : {}),
+		...(child?.contextOverflow || step?.contextOverflow ? { contextOverflow: true } : {}),
 		...(child?.totalCost ?? step?.totalCost ? { totalCost: child?.totalCost ?? step?.totalCost } : {}),
 		...(child?.structuredOutput !== undefined ? { structuredOutput: child.structuredOutput } : step?.structuredOutput !== undefined ? { structuredOutput: step.structuredOutput } : {}),
 		...(child?.structuredOutputPath ?? step?.structuredOutputPath ? { structuredOutputPath: child?.structuredOutputPath ?? step?.structuredOutputPath } : {}),

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

@@ -57,7 +57,7 @@ type ResultWatcherDeps = {
 	coalesceDelayMs?: number;
 	/** Returns true while a durable completion source needs periodic delivery checks. */
 	hasDeliveryDemand?: () => boolean;
-	/** Control how slow result-index scans are logged. Defaults to \"all\". */
+	/** Control how slow result-index scans are logged. Defaults to \"activity\". */
 	resultScanLogging?: "all" | "activity" | "off";
 	platform?: NodeJS.Platform;
 };
@@ -606,12 +606,13 @@ export function createResultWatcher(
 	const logScanStats = (stats: ResultScanStats) => {
 		const elapsed = Date.now() - stats.startedAt;
 		if (elapsed < SLOW_RESULT_SCAN_MS) return;
-		if (deps.resultScanLogging === "off") return;
+		const resultScanLogging = deps.resultScanLogging ?? "activity";
+		if (resultScanLogging === "off") return;
 		// A scan that inspected and scheduled nothing is a quiet no-op (e.g. the
 		// healthy periodic rescan while no async runs are pending). Under
 		// "activity", skip it so empty scans do not burn context tokens in the
 		// session transcript.
-		if (deps.resultScanLogging === "activity" && stats.files === 0 && stats.scheduled === 0) return;
+		if (resultScanLogging === "activity" && stats.files === 0 && stats.scheduled === 0) return;
 		console.error(`Subagent result scan inspected ${stats.files} indexed result file(s), scheduled ${stats.scheduled} in ${elapsed}ms (${resultsDir}).`);
 	};
 	const indexedResultCandidates = (observed: ReadonlySet<string>): string[] => {

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

@@ -97,6 +97,7 @@ interface ResultChildOutcome {
 	thinking?: string;
 	attemptedModels?: string[];
 	modelAttempts?: NonNullable<AsyncStatus["steps"]>[number]["modelAttempts"];
+	contextOverflow?: boolean;
 }
 
 interface ResultRepairData {
@@ -163,6 +164,7 @@ function terminalStatusFromResult(status: AsyncStatus, resultPath: string, now:
 			thinking,
 			attemptedModels: child?.attemptedModels ?? step.attemptedModels,
 			modelAttempts: child?.modelAttempts ?? step.modelAttempts,
+			contextOverflow: child?.contextOverflow ?? step.contextOverflow,
 		};
 	});
 	const terminalStatus: AsyncStatus = {
@@ -258,6 +260,7 @@ function buildFailedRepair(status: AsyncStatus, asyncDir: string, now: number, r
 				model: step.model,
 				attemptedModels: step.attemptedModels,
 				modelAttempts: step.modelAttempts,
+				contextOverflow: step.contextOverflow,
 				sessionFile: step.sessionFile,
 			})),
 			exitCode: 1,