pi-subagents 0.31.1 → 0.33.0

package/src/agents/agents.ts

@@ -7,14 +7,16 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import { fileURLToPath } from "node:url";
-import type { AcceptanceInput, OutputMode } from "../shared/types.ts";
+import type { AcceptanceInput, OutputMode, ToolBudgetConfig } from "../shared/types.ts";
 import { getAgentDir, getProjectConfigDir } from "../shared/utils.ts";
 import { KNOWN_FIELDS } from "./agent-serializer.ts";
 import { parseChain, parseJsonChain } from "./chain-serializer.ts";
 import { mergeAgentsForScope } from "./agent-selection.ts";
 import { parseFrontmatter } from "./frontmatter.ts";
 import { buildRuntimeName, parsePackageName } from "./identity.ts";
+import { parseModelScopeConfig, type ModelScopeConfig } from "../runs/shared/model-scope.ts";
 export { buildRuntimeName, frontmatterNameForConfig, parsePackageName } from "./identity.ts";
+import { parseMemoryFrontmatter } from "./agent-memory.ts";
 
 export type AgentScope = "user" | "project" | "both";
 
@@ -22,6 +24,13 @@ export type AgentSource = "builtin" | "package" | "user" | "project";
 type SystemPromptMode = "append" | "replace";
 export type AgentDefaultContext = "fresh" | "fork";
 
+export type AgentMemoryScope = "project" | "user";
+
+export interface AgentMemoryConfig {
+	scope: AgentMemoryScope;
+	path: string;
+}
+
 export const BUILTIN_AGENT_NAMES = [
 	"context-builder",
 	"delegate",
@@ -60,6 +69,7 @@ export interface BuiltinAgentOverrideBase {
 	mcpDirectTools?: string[];
 	subagentOnlyExtensions?: string[];
 	completionGuard?: boolean;
+	toolBudget?: ToolBudgetConfig;
 }
 
 interface BuiltinAgentOverrideConfig {
@@ -76,6 +86,7 @@ interface BuiltinAgentOverrideConfig {
 	tools?: string[] | false;
 	subagentOnlyExtensions?: string[] | false;
 	completionGuard?: boolean;
+	toolBudget?: ToolBudgetConfig | false;
 }
 
 interface BuiltinAgentOverrideInfo {
@@ -84,6 +95,13 @@ interface BuiltinAgentOverrideInfo {
 	base: BuiltinAgentOverrideBase;
 }
 
+export interface AgentModelSourceInfo {
+	type: "subagents.defaultModel";
+	scope: "user" | "project";
+	path: string;
+	model: string;
+}
+
 export interface AgentConfig {
 	name: string;
 	localName?: string;
@@ -110,15 +128,20 @@ export interface AgentConfig {
 	interactive?: boolean;
 	maxSubagentDepth?: number;
 	completionGuard?: boolean;
+	toolBudget?: ToolBudgetConfig;
+	memory?: AgentMemoryConfig;
 	disabled?: boolean;
 	extraFields?: Record<string, string>;
 	override?: BuiltinAgentOverrideInfo;
+	modelSource?: AgentModelSourceInfo;
 }
 
 interface SubagentSettings {
 	overrides: Record<string, BuiltinAgentOverrideConfig>;
+	defaultModel?: string;
 	disableBuiltins?: boolean;
 	disableThinking?: boolean;
+	modelScope?: ModelScopeConfig;
 }
 
 const EMPTY_SUBAGENT_SETTINGS: SubagentSettings = { overrides: {} };
@@ -144,6 +167,7 @@ export interface ChainStepConfig {
 	failFast?: boolean;
 	worktree?: boolean;
 	acceptance?: AcceptanceInput;
+	toolBudget?: ToolBudgetConfig;
 }
 
 export interface ChainConfig {
@@ -166,6 +190,7 @@ export interface ChainDiscoveryDiagnostic {
 interface AgentDiscoveryResult {
 	agents: AgentConfig[];
 	projectAgentsDir: string | null;
+	modelScope?: ModelScopeConfig;
 }
 
 function getUserChainDir(): string {
@@ -476,6 +501,7 @@ function cloneOverrideBase(agent: AgentConfig): BuiltinAgentOverrideBase {
 		mcpDirectTools: agent.mcpDirectTools ? [...agent.mcpDirectTools] : undefined,
 		subagentOnlyExtensions: agent.subagentOnlyExtensions ? [...agent.subagentOnlyExtensions] : undefined,
 		completionGuard: agent.completionGuard,
+		toolBudget: agent.toolBudget,
 	};
 }
 
@@ -496,10 +522,11 @@ function cloneOverrideValue(override: BuiltinAgentOverrideConfig): BuiltinAgentO
 		...(override.tools !== undefined ? { tools: override.tools === false ? false : [...override.tools] } : {}),
 		...(override.subagentOnlyExtensions !== undefined ? { subagentOnlyExtensions: override.subagentOnlyExtensions === false ? false : [...override.subagentOnlyExtensions] } : {}),
 		...(override.completionGuard !== undefined ? { completionGuard: override.completionGuard } : {}),
+		...(override.toolBudget !== undefined ? { toolBudget: override.toolBudget === false ? false : { ...override.toolBudget, ...(Array.isArray(override.toolBudget.block) ? { block: [...override.toolBudget.block] } : {}) } } : {}),
 	};
 }
 
-function findNearestProjectRoot(cwd: string): string | null {
+export function findNearestProjectRoot(cwd: string): string | null {
 	let currentDir = cwd;
 	while (true) {
 		if (isDirectory(getProjectConfigDir(currentDir)) || isDirectory(path.join(currentDir, ".agents"))) {
@@ -640,6 +667,16 @@ function parseBuiltinOverrideEntry(
 		}
 	}
 
+	if ("toolBudget" in input) {
+		if (input.toolBudget === false) {
+			override.toolBudget = false;
+		} else if (input.toolBudget && typeof input.toolBudget === "object" && !Array.isArray(input.toolBudget)) {
+			override.toolBudget = input.toolBudget as ToolBudgetConfig;
+		} else {
+			throw new Error(`Builtin override '${name}' in '${filePath}' has invalid 'toolBudget'; expected an object or false.`);
+		}
+	}
+
 	if ("systemPrompt" in input) {
 		if (typeof input.systemPrompt === "string") override.systemPrompt = input.systemPrompt;
 		else throw new Error(`Builtin override '${name}' in '${filePath}' has invalid 'systemPrompt'; expected a string.`);
@@ -683,17 +720,51 @@ function readSubagentSettings(filePath: string | null): SubagentSettings {
 			throw new Error(`Subagent settings in '${filePath}' have invalid 'disableThinking'; expected a boolean.`);
 		}
 	}
+	let defaultModel: string | undefined;
+	if ("defaultModel" in subagentsObject) {
+		if (typeof subagentsObject.defaultModel === "string" && subagentsObject.defaultModel.trim()) {
+			defaultModel = subagentsObject.defaultModel.trim();
+		} else {
+			throw new Error(`Subagent settings in '${filePath}' have invalid 'defaultModel'; expected a non-empty string.`);
+		}
+	}
+	const modelScope = parseModelScopeConfig(subagentsObject.modelScope, { filePath });
 
 	const parsed: Record<string, BuiltinAgentOverrideConfig> = {};
 	const agentOverrides = subagentsObject.agentOverrides;
 	if (!agentOverrides || typeof agentOverrides !== "object" || Array.isArray(agentOverrides)) {
-		return { overrides: parsed, disableBuiltins, disableThinking };
+		return { overrides: parsed, defaultModel, disableBuiltins, disableThinking, modelScope };
 	}
 	for (const [name, value] of Object.entries(agentOverrides)) {
 		const override = parseBuiltinOverrideEntry(name, value, filePath);
 		if (override) parsed[name] = override;
 	}
-	return { overrides: parsed, disableBuiltins, disableThinking };
+	return { overrides: parsed, defaultModel, disableBuiltins, disableThinking, modelScope };
+}
+
+function resolveSubagentDefaultModel(
+	userSettings: SubagentSettings,
+	projectSettings: SubagentSettings,
+	userSettingsPath: string,
+	projectSettingsPath: string | null,
+): AgentModelSourceInfo | undefined {
+	if (projectSettingsPath && projectSettings.defaultModel !== undefined) {
+		return { type: "subagents.defaultModel", scope: "project", path: projectSettingsPath, model: projectSettings.defaultModel };
+	}
+	return userSettings.defaultModel !== undefined
+		? { type: "subagents.defaultModel", scope: "user", path: userSettingsPath, model: userSettings.defaultModel }
+		: undefined;
+}
+
+function applySubagentDefaultModel(agents: AgentConfig[], defaultModel: AgentModelSourceInfo | undefined): AgentConfig[] {
+	if (!defaultModel) return agents;
+	return agents.map((agent) => {
+		if (agent.model !== undefined) return agent;
+		const next = { ...agent, model: defaultModel.model, modelSource: defaultModel };
+		const frontmatterFields = agentFrontmatterFields.get(agent);
+		if (frontmatterFields) agentFrontmatterFields.set(next, frontmatterFields);
+		return next;
+	});
 }
 
 function applyBuiltinOverride(
@@ -727,6 +798,7 @@ function applyBuiltinOverride(
 		next.subagentOnlyExtensions = override.subagentOnlyExtensions === false ? undefined : [...override.subagentOnlyExtensions];
 	}
 	if (override.completionGuard !== undefined) next.completionGuard = override.completionGuard;
+	if (override.toolBudget !== undefined) next.toolBudget = override.toolBudget === false ? undefined : override.toolBudget;
 
 	return next;
 }
@@ -872,6 +944,9 @@ function applyCustomAgentOverride(
 	if (override.completionGuard !== undefined) {
 		fill("completionGuard", ["completionGuard"], override.completionGuard);
 	}
+	if (override.toolBudget !== undefined) {
+		fill("toolBudget", ["toolBudget"], override.toolBudget === false ? undefined : override.toolBudget);
+	}
 
 	if (!anyFilled || !next) return agent;
 	next.override = { ...meta, base: cloneOverrideBase(agent) };
@@ -902,7 +977,7 @@ function applyCustomAgentOverrides(
 
 export function buildBuiltinOverrideConfig(
 	base: BuiltinAgentOverrideBase,
-	draft: Pick<AgentConfig, "model" | "fallbackModels" | "thinking" | "systemPromptMode" | "inheritProjectContext" | "inheritSkills" | "defaultContext" | "disabled" | "systemPrompt" | "skills" | "tools" | "mcpDirectTools" | "subagentOnlyExtensions" | "completionGuard">,
+	draft: Pick<AgentConfig, "model" | "fallbackModels" | "thinking" | "systemPromptMode" | "inheritProjectContext" | "inheritSkills" | "defaultContext" | "disabled" | "systemPrompt" | "skills" | "tools" | "mcpDirectTools" | "subagentOnlyExtensions" | "completionGuard" | "toolBudget">,
 ): BuiltinAgentOverrideConfig | undefined {
 	const override: BuiltinAgentOverrideConfig = {};
 
@@ -926,6 +1001,7 @@ export function buildBuiltinOverrideConfig(
 	if ((draft.completionGuard !== false) !== (base.completionGuard !== false)) {
 		override.completionGuard = draft.completionGuard !== false;
 	}
+	if (JSON.stringify(draft.toolBudget) !== JSON.stringify(base.toolBudget)) override.toolBudget = draft.toolBudget ?? false;
 
 	return Object.keys(override).length > 0 ? override : undefined;
 }
@@ -954,19 +1030,20 @@ export function saveBuiltinAgentOverride(
 	return filePath;
 }
 
-export function removeBuiltinAgentOverride(cwd: string, name: string, scope: "user" | "project"): string {
+export function removeBuiltinAgentOverride(cwd: string, name: string, scope: "user" | "project"): { path: string; removed: boolean } {
 	const filePath = scope === "project" ? getProjectAgentSettingsPath(cwd) : getUserAgentSettingsPath();
 	if (!filePath) throw new Error("Project override is not available here. No project config root was found.");
-	if (!fs.existsSync(filePath)) return filePath;
+	if (!fs.existsSync(filePath)) return { path: filePath, removed: false };
 
 	const settings = readSettingsFileStrict(filePath);
 	const subagents = settings.subagents;
-	if (!subagents || typeof subagents !== "object" || Array.isArray(subagents)) return filePath;
+	if (!subagents || typeof subagents !== "object" || Array.isArray(subagents)) return { path: filePath, removed: false };
 	const nextSubagents = { ...(subagents as Record<string, unknown>) };
 	const agentOverrides = nextSubagents.agentOverrides;
-	if (!agentOverrides || typeof agentOverrides !== "object" || Array.isArray(agentOverrides)) return filePath;
+	if (!agentOverrides || typeof agentOverrides !== "object" || Array.isArray(agentOverrides)) return { path: filePath, removed: false };
 
 	const nextOverrides = { ...(agentOverrides as Record<string, unknown>) };
+	if (!Object.prototype.hasOwnProperty.call(nextOverrides, name)) return { path: filePath, removed: false };
 	delete nextOverrides[name];
 	if (Object.keys(nextOverrides).length > 0) nextSubagents.agentOverrides = nextOverrides;
 	else delete nextSubagents.agentOverrides;
@@ -974,10 +1051,82 @@ export function removeBuiltinAgentOverride(cwd: string, name: string, scope: "us
 	if (Object.keys(nextSubagents).length > 0) settings.subagents = nextSubagents;
 	else delete settings.subagents;
 
+	writeSettingsFile(filePath, settings);
+	return { path: filePath, removed: true };
+}
+
+export function mergeBuiltinAgentOverride(
+	cwd: string,
+	name: string,
+	scope: "user" | "project",
+	fields: BuiltinAgentOverrideConfig,
+): string {
+	const filePath = scope === "project" ? getProjectAgentSettingsPath(cwd) : getUserAgentSettingsPath();
+	if (!filePath) throw new Error("Project override is not available here. No project config root was found.");
+
+	const settings = readSettingsFileStrict(filePath);
+	const subagents = settings.subagents && typeof settings.subagents === "object" && !Array.isArray(settings.subagents)
+		? { ...(settings.subagents as Record<string, unknown>) }
+		: {};
+	const agentOverrides = subagents.agentOverrides && typeof subagents.agentOverrides === "object" && !Array.isArray(subagents.agentOverrides)
+		? { ...(subagents.agentOverrides as Record<string, unknown>) }
+		: {};
+
+	const existing = agentOverrides[name];
+	const base = existing && typeof existing === "object" && !Array.isArray(existing)
+		? existing as Record<string, unknown>
+		: {};
+	agentOverrides[name] = { ...base, ...cloneOverrideValue(fields) };
+	subagents.agentOverrides = agentOverrides;
+	settings.subagents = subagents;
 	writeSettingsFile(filePath, settings);
 	return filePath;
 }
 
+export function removeBuiltinAgentOverrideFields(
+	cwd: string,
+	name: string,
+	scope: "user" | "project",
+	fields: string[],
+): { path: string; removed: boolean } {
+	const filePath = scope === "project" ? getProjectAgentSettingsPath(cwd) : getUserAgentSettingsPath();
+	if (!filePath) throw new Error("Project override is not available here. No project config root was found.");
+	if (!fs.existsSync(filePath)) return { path: filePath, removed: false };
+
+	const settings = readSettingsFileStrict(filePath);
+	const subagents = settings.subagents;
+	if (!subagents || typeof subagents !== "object" || Array.isArray(subagents)) return { path: filePath, removed: false };
+	const agentOverrides = (subagents as Record<string, unknown>).agentOverrides;
+	if (!agentOverrides || typeof agentOverrides !== "object" || Array.isArray(agentOverrides)) return { path: filePath, removed: false };
+
+	const entry = (agentOverrides as Record<string, unknown>)[name];
+	if (!entry || typeof entry !== "object" || Array.isArray(entry)) return { path: filePath, removed: false };
+
+	const nextEntry: Record<string, unknown> = { ...(entry as Record<string, unknown>) };
+	let removed = false;
+	for (const field of fields) {
+		if (Object.prototype.hasOwnProperty.call(nextEntry, field)) {
+			delete nextEntry[field];
+			removed = true;
+		}
+	}
+	if (!removed) return { path: filePath, removed: false };
+
+	const nextSubagents = { ...(subagents as Record<string, unknown>) };
+	if (Object.keys(nextEntry).length > 0) {
+		(nextSubagents.agentOverrides as Record<string, unknown>)[name] = nextEntry;
+	} else {
+		const nextOverrides = { ...(agentOverrides as Record<string, unknown>) };
+		delete nextOverrides[name];
+		if (Object.keys(nextOverrides).length > 0) nextSubagents.agentOverrides = nextOverrides;
+		else delete nextSubagents.agentOverrides;
+	}
+	if (Object.keys(nextSubagents).length > 0) settings.subagents = nextSubagents;
+	else delete settings.subagents;
+	writeSettingsFile(filePath, settings);
+	return { path: filePath, removed: true };
+}
+
 function listFilesRecursive(dir: string, predicate: (fileName: string) => boolean): string[] {
 	const files: string[] = [];
 	if (!fs.existsSync(dir)) return files;
@@ -1111,6 +1260,14 @@ function loadAgentsFromDir(dir: string, source: AgentSource): AgentConfig[] {
 		}
 
 		const parsedMaxSubagentDepth = Number(frontmatter.maxSubagentDepth);
+		let toolBudget: ToolBudgetConfig | undefined;
+		if (frontmatter.toolBudget !== undefined && frontmatter.toolBudget.trim()) {
+			const parsed = JSON.parse(frontmatter.toolBudget) as unknown;
+			if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+				throw new Error(`Agent '${localName}' has invalid toolBudget frontmatter; expected a JSON object.`);
+			}
+			toolBudget = parsed as ToolBudgetConfig;
+		}
 		const completionGuard = frontmatter.completionGuard === "false"
 			? false
 			: frontmatter.completionGuard === "true"
@@ -1146,6 +1303,8 @@ function loadAgentsFromDir(dir: string, source: AgentSource): AgentConfig[] {
 					? parsedMaxSubagentDepth
 					: undefined,
 			completionGuard,
+			toolBudget,
+			memory: parseMemoryFrontmatter(frontmatter.memory),
 			extraFields: Object.keys(extraFields).length > 0 ? extraFields : undefined,
 		};
 		agentFrontmatterFields.set(agent, new Set(Object.keys(frontmatter)));
@@ -1241,13 +1400,15 @@ export function discoverAgents(cwd: string, scope: AgentScope): AgentDiscoveryRe
 	const projectSettingsPath = getProjectAgentSettingsPath(cwd);
 	const userSettings = scope === "project" ? EMPTY_SUBAGENT_SETTINGS : readSubagentSettings(userSettingsPath);
 	const projectSettings = scope === "user" ? EMPTY_SUBAGENT_SETTINGS : readSubagentSettings(projectSettingsPath);
+	const defaultModel = resolveSubagentDefaultModel(userSettings, projectSettings, userSettingsPath, projectSettingsPath);
+	const modelScope = projectSettings.modelScope ?? userSettings.modelScope;
 	const packageSubagentPaths = collectPackageSubagentPaths(cwd, {
 		includeUser: scope !== "project",
 		includeProject: scope !== "user",
 	});
 
 	const builtinAgents = applyBuiltinOverrides(
-		loadAgentsFromDir(BUILTIN_AGENTS_DIR, "builtin"),
+		applySubagentDefaultModel(loadAgentsFromDir(BUILTIN_AGENTS_DIR, "builtin"), defaultModel),
 		userSettings,
 		projectSettings,
 		userSettingsPath,
@@ -1258,7 +1419,7 @@ export function discoverAgents(cwd: string, scope: AgentScope): AgentDiscoveryRe
 	const userAgentsOld = scope === "project" ? [] : loadAgentsFromDir(userDirOld, "user");
 	const userAgentsNew = scope === "project" ? [] : loadAgentsFromDir(userDirNew, "user");
 	const userAgents = applyCustomAgentOverrides(
-		[...userAgentsExtra, ...userAgentsOld, ...userAgentsNew],
+		applySubagentDefaultModel([...userAgentsExtra, ...userAgentsOld, ...userAgentsNew], defaultModel),
 		userSettings,
 		projectSettings,
 		userSettingsPath,
@@ -1266,17 +1427,23 @@ export function discoverAgents(cwd: string, scope: AgentScope): AgentDiscoveryRe
 	);
 
 	const projectAgents = applyCustomAgentOverrides(
-		scope === "user" ? [] : projectAgentDirs.flatMap((dir) => loadAgentsFromDir(dir, "project")),
+		applySubagentDefaultModel(scope === "user" ? [] : projectAgentDirs.flatMap((dir) => loadAgentsFromDir(dir, "project")), defaultModel),
+		userSettings,
+		projectSettings,
+		userSettingsPath,
+		projectSettingsPath,
+	);
+	const packageAgents = applyCustomAgentOverrides(
+		applySubagentDefaultModel(packageSubagentPaths.agents.flatMap((dir) => loadAgentsFromDir(dir, "package")), defaultModel),
 		userSettings,
 		projectSettings,
 		userSettingsPath,
 		projectSettingsPath,
 	);
-	const packageAgents = packageSubagentPaths.agents.flatMap((dir) => loadAgentsFromDir(dir, "package"));
 	const agents = mergeAgentsForScope(scope, userAgents, projectAgents, builtinAgents, packageAgents)
 		.filter((agent) => agent.disabled !== true);
 
-	return { agents, projectAgentsDir };
+	return { agents, projectAgentsDir, modelScope };
 }
 
 export function discoverAgentsAll(cwd: string): {
@@ -1302,21 +1469,22 @@ export function discoverAgentsAll(cwd: string): {
 	const projectSettingsPath = getProjectAgentSettingsPath(cwd);
 	const userSettings = readSubagentSettings(userSettingsPath);
 	const projectSettings = readSubagentSettings(projectSettingsPath);
+	const defaultModel = resolveSubagentDefaultModel(userSettings, projectSettings, userSettingsPath, projectSettingsPath);
 	const packageSubagentPaths = collectPackageSubagentPaths(cwd);
 
 	const builtin = applyBuiltinOverrides(
-		loadAgentsFromDir(BUILTIN_AGENTS_DIR, "builtin"),
+		applySubagentDefaultModel(loadAgentsFromDir(BUILTIN_AGENTS_DIR, "builtin"), defaultModel),
 		userSettings,
 		projectSettings,
 		userSettingsPath,
 		projectSettingsPath,
 	);
 	const user = applyCustomAgentOverrides(
-		[
+		applySubagentDefaultModel([
 			...extraUserAgentDirs().flatMap((dir) => loadAgentsFromDir(dir, "user")),
 			...loadAgentsFromDir(userDirOld, "user"),
 			...loadAgentsFromDir(userDirNew, "user"),
-		],
+		], defaultModel),
 		userSettings,
 		projectSettings,
 		userSettingsPath,
@@ -1328,7 +1496,13 @@ export function discoverAgentsAll(cwd: string): {
 			if (!packageMap.has(agent.name)) packageMap.set(agent.name, agent);
 		}
 	}
-	const packageAgents = Array.from(packageMap.values());
+	const packageAgents = applyCustomAgentOverrides(
+		applySubagentDefaultModel(Array.from(packageMap.values()), defaultModel),
+		userSettings,
+		projectSettings,
+		userSettingsPath,
+		projectSettingsPath,
+	);
 	const projectMap = new Map<string, AgentConfig>();
 	for (const dir of projectDirs) {
 		for (const agent of loadAgentsFromDir(dir, "project")) {
@@ -1336,7 +1510,7 @@ export function discoverAgentsAll(cwd: string): {
 		}
 	}
 	const project = applyCustomAgentOverrides(
-		Array.from(projectMap.values()),
+		applySubagentDefaultModel(Array.from(projectMap.values()), defaultModel),
 		userSettings,
 		projectSettings,
 		userSettingsPath,

package/src/agents/chain-serializer.ts

@@ -3,6 +3,7 @@ import { buildRuntimeName, frontmatterNameForConfig, parsePackageName } from "./
 import { parseFrontmatter } from "./frontmatter.ts";
 import { ChainOutputValidationError, validateChainOutputBindings } from "../runs/shared/chain-outputs.ts";
 import { validateAcceptanceInput } from "../runs/shared/acceptance.ts";
+import { validateToolBudgetConfig } from "../runs/shared/tool-budget.ts";
 import type { ChainStep } from "../shared/settings.ts";
 import type { AgentSource } from "./agents.ts";
 
@@ -78,6 +79,19 @@ function parseStepBody(agent: string, sectionBody: string): ChainStepConfig {
 		if (key === "progress") {
 			if (rawValue === "true") step.progress = true;
 			else if (rawValue === "false") step.progress = false;
+			continue;
+		}
+		if (key === "toolbudget") {
+			let parsed: unknown;
+			try {
+				parsed = JSON.parse(rawValue);
+			} catch (error) {
+				const message = error instanceof Error ? error.message : String(error);
+				throw new Error(`Invalid toolBudget in .chain.md step '${agent}': ${message}`);
+			}
+			const validation = validateToolBudgetConfig(parsed, `toolBudget for step '${agent}'`);
+			if (validation.error) throw new Error(validation.error);
+			step.toolBudget = parsed as ChainStepConfig["toolBudget"];
 		}
 	}
 
@@ -125,6 +139,11 @@ export function parseChain(content: string, source: AgentSource, filePath: strin
 	};
 }
 
+function validateJsonChainToolBudget(value: unknown, label: string): void {
+	const validation = validateToolBudgetConfig(value, label);
+	if (validation.error) throw new Error(validation.error);
+}
+
 export function parseJsonChain(content: string, source: AgentSource, filePath: string): ChainConfig {
 	let parsed: unknown;
 	try {
@@ -152,6 +171,7 @@ export function parseJsonChain(content: string, source: AgentSource, filePath: s
 			throw new Error(`JSON chain '${filePath}' step ${i + 1} must be an object.`);
 		}
 		const stepRecord = step as Record<string, unknown>;
+		if (stepRecord.toolBudget !== undefined) validateJsonChainToolBudget(stepRecord.toolBudget, `step ${i + 1} toolBudget`);
 		const acceptanceErrors = validateAcceptanceInput(stepRecord.acceptance, `step ${i + 1} acceptance`);
 		if (acceptanceErrors.length > 0) {
 			throw new Error(`Invalid JSON chain '${filePath}': ${acceptanceErrors.join(" ")}`);
@@ -161,13 +181,17 @@ export function parseJsonChain(content: string, source: AgentSource, filePath: s
 			for (let taskIndex = 0; taskIndex < parallel.length; taskIndex++) {
 				const task = parallel[taskIndex];
 				if (!task || typeof task !== "object" || Array.isArray(task)) continue;
-				const taskErrors = validateAcceptanceInput((task as Record<string, unknown>).acceptance, `step ${i + 1} parallel task ${taskIndex + 1} acceptance`);
+				const taskRecord = task as Record<string, unknown>;
+				if (taskRecord.toolBudget !== undefined) validateJsonChainToolBudget(taskRecord.toolBudget, `step ${i + 1} parallel task ${taskIndex + 1} toolBudget`);
+				const taskErrors = validateAcceptanceInput(taskRecord.acceptance, `step ${i + 1} parallel task ${taskIndex + 1} acceptance`);
 				if (taskErrors.length > 0) {
 					throw new Error(`Invalid JSON chain '${filePath}': ${taskErrors.join(" ")}`);
 				}
 			}
 		} else if (parallel && typeof parallel === "object") {
-			const templateErrors = validateAcceptanceInput((parallel as Record<string, unknown>).acceptance, `step ${i + 1} dynamic template acceptance`);
+			const parallelRecord = parallel as Record<string, unknown>;
+			if (parallelRecord.toolBudget !== undefined) validateJsonChainToolBudget(parallelRecord.toolBudget, `step ${i + 1} dynamic template toolBudget`);
+			const templateErrors = validateAcceptanceInput(parallelRecord.acceptance, `step ${i + 1} dynamic template acceptance`);
 			if (templateErrors.length > 0) {
 				throw new Error(`Invalid JSON chain '${filePath}': ${templateErrors.join(" ")}`);
 			}
@@ -243,6 +267,7 @@ export function serializeChain(config: ChainConfig): string {
 		if (step.skills === false) lines.push("skills: false");
 		else if (Array.isArray(step.skills) && step.skills.length > 0) lines.push(`skills: ${step.skills.join(", ")}`);
 		if (step.progress !== undefined) lines.push(`progress: ${step.progress ? "true" : "false"}`);
+		if (step.toolBudget !== undefined) lines.push(`toolBudget: ${JSON.stringify(step.toolBudget)}`);
 		lines.push("");
 		lines.push(step.task ?? "");
 		if (i < config.steps.length - 1) lines.push("");

package/src/extension/config.ts

@@ -3,12 +3,35 @@ import * as path from "node:path";
 import type { ExtensionConfig } from "../shared/types.ts";
 import { getAgentDir } from "../shared/utils.ts";
 
+export function getConfigPath(): string {
+	return path.join(getAgentDir(), "extensions", "subagent", "config.json");
+}
+
+function readConfigForUpdate(configPath = getConfigPath()): ExtensionConfig {
+	if (!fs.existsSync(configPath)) return {};
+	const parsed = JSON.parse(fs.readFileSync(configPath, "utf-8")) as unknown;
+	if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+		throw new Error(`Subagent config at '${configPath}' must be a JSON object`);
+	}
+	return parsed as ExtensionConfig;
+}
+
+export function saveConfig(config: ExtensionConfig, configPath = getConfigPath()): void {
+	fs.mkdirSync(path.dirname(configPath), { recursive: true });
+	fs.writeFileSync(configPath, `${JSON.stringify(config, null, "\t")}\n`, "utf-8");
+}
+
+export function updateConfig(updater: (config: ExtensionConfig) => ExtensionConfig): ExtensionConfig {
+	const configPath = getConfigPath();
+	const next = updater(readConfigForUpdate(configPath));
+	saveConfig(next, configPath);
+	return next;
+}
+
 export function loadConfig(): ExtensionConfig {
-	const configPath = path.join(getAgentDir(), "extensions", "subagent", "config.json");
+	const configPath = getConfigPath();
 	try {
-		if (fs.existsSync(configPath)) {
-			return JSON.parse(fs.readFileSync(configPath, "utf-8")) as ExtensionConfig;
-		}
+		return readConfigForUpdate(configPath);
 	} catch (error) {
 		console.error(`Failed to load subagent config from '${configPath}':`, error);
 	}

package/src/extension/doctor.ts

@@ -157,14 +157,8 @@ function formatIntercomDiagnostic(diagnostic: IntercomBridgeDiagnostic, context:
 		`- bridge: ${diagnostic.active ? "active" : "inactive"}${diagnostic.reason ? ` (${diagnostic.reason})` : ""}`,
 		`- mode: ${diagnostic.mode}; context: ${context ?? "unspecified"}`,
 		`- orchestrator target: ${diagnostic.orchestratorTarget ?? "not available"}`,
-		`- pi-intercom: ${diagnostic.piIntercomAvailable ? "available" : "unavailable"} at ${diagnostic.extensionDir}`,
+		`- supervisor channel: ${diagnostic.supervisorChannelAvailable ? "available" : "unavailable"} (${diagnostic.extensionDir})`,
 	];
-	if (diagnostic.configPath && diagnostic.intercomConfigEnabled !== undefined) {
-		lines.push(`- intercom config: ${diagnostic.intercomConfigEnabled === false ? "disabled" : "enabled or absent"} (${diagnostic.configPath})`);
-	}
-	if (diagnostic.intercomConfigError) {
-		lines.push(`- intercom config warning: ${diagnostic.intercomConfigError}; runtime assumes enabled`);
-	}
 	return lines;
 }
 

package/src/extension/fanout-child.ts

@@ -31,6 +31,7 @@ function createChildSafeState(): SubagentState {
 		baseCwd: "",
 		currentSessionId: null,
 		subagentInProgress: false,
+		subagentSpawns: { sessionId: null, count: 0 },
 		asyncJobs: new Map(),
 		foregroundRuns: new Map(),
 		foregroundControls: new Map(),
@@ -157,8 +158,8 @@ export default function registerFanoutChildSubagentExtension(pi: ExtensionAPI):
 		label: "Subagent",
 		description: [
 			"Delegate to subagents from child-safe fanout mode.",
-			"Allowed management/control actions: list, get, status, interrupt, resume, append-step, doctor.",
-			"Agent config mutation actions create, update, and delete are blocked in this mode.",
+			"Allowed management/control actions: list, get, status, interrupt, resume, steer, append-step, doctor.",
+			"Agent config mutation actions (create, update, delete, eject, disable, enable, reset) are blocked in this mode.",
 		].join("\n"),
 		parameters: SubagentParams,
 		execute(id, params, signal, onUpdate, ctx) {