@bastani/atomic 0.9.11-alpha.1 → 0.9.11-alpha.11

package/dist/builtin/subagents/src/agents/agent-management.ts

@@ -1,23 +1,43 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { CONFIG_DIR_NAME } from "@bastani/atomic";
 import type { ExtensionContext } from "@bastani/atomic";
+import { CONFIG_DIR_NAME } from "@bastani/atomic";
+import type { SubagentToolResult } from "../shared/types.ts";
+import {
+	allAgents,
+	applyAgentConfig,
+	asDisambiguationScope,
+	availableNames,
+	chainStepWarnings,
+	configObject,
+	fallbackModelsWarning,
+	findAgents,
+	findChains,
+	hasKey,
+	modelWarning,
+	nameExistsInScope,
+	normalizeListScope,
+	parsePackageConfig,
+	parseStepList,
+	result,
+	sanitizeName,
+	skillsWarning,
+	unknownChainAgents,
+} from "./agent-management-helpers.ts";
+import { serializeAgent } from "./agent-serializer.ts";
 import {
 	type AgentConfig,
 	type AgentSource,
+	buildRuntimeName,
 	type ChainConfig,
 	type ChainStepConfig,
 	defaultInheritProjectContext,
 	defaultInheritSkills,
 	defaultSystemPromptMode,
 	discoverAgentsAll,
-	buildRuntimeName,
 	frontmatterNameForConfig,
 } from "./agents.ts";
-import { serializeAgent } from "./agent-serializer.ts";
 import { serializeChain, serializeJsonChain } from "./chain-serializer.ts";
-import { allAgents, applyAgentConfig, asDisambiguationScope, availableNames, chainStepWarnings, configObject, fallbackModelsWarning, findAgents, findChains, hasKey, modelWarning, nameExistsInScope, normalizeListScope, parsePackageConfig, parseStepList, result, sanitizeName, skillsWarning, unknownChainAgents } from "./agent-management-helpers.ts";
-import type { SubagentToolResult } from "../shared/types.ts";
 
 type ManagementAction = "list" | "get" | "create" | "update" | "delete";
 export type ManagementScope = "user" | "project";
@@ -47,20 +67,34 @@ function resolveTarget<T extends { source: AgentSource; filePath: string }>(
 	const mutable = matches.filter(isMutableDefinition);
 	if (mutable.length === 0) {
 		if (matches.length > 0) {
-			return result(`${kind === "agent" ? "Agent" : "Chain"} '${name}' is builtin and cannot be modified. Create a same-named ${kind} in user or project scope to override it.`, true);
+			return result(
+				`${kind === "agent" ? "Agent" : "Chain"} '${name}' is builtin and cannot be modified. Create a same-named ${kind} in user or project scope to override it.`,
+				true,
+			);
 		}
 		const available = availableNames(cwd, kind);
-		return result(`${kind === "agent" ? "Agent" : "Chain"} '${name}' not found. Available: ${available.join(", ") || "none"}.`, true);
+		return result(
+			`${kind === "agent" ? "Agent" : "Chain"} '${name}' not found. Available: ${available.join(", ") || "none"}.`,
+			true,
+		);
 	}
 	if (mutable.length === 1) return mutable[0]!;
 	const scope = asDisambiguationScope(scopeHint);
 	if (!scope) {
 		const paths = mutable.map((m) => `${m.source}: ${m.filePath}`).join("\n");
-		return result(`${kind === "agent" ? "Agent" : "Chain"} '${name}' exists in both scopes. Specify agentScope: 'user' or 'project'.\n${paths}`, true);
+		return result(
+			`${kind === "agent" ? "Agent" : "Chain"} '${name}' exists in both scopes. Specify agentScope: 'user' or 'project'.\n${paths}`,
+			true,
+		);
 	}
 	const scoped = mutable.filter((m) => m.source === scope);
-	if (scoped.length === 0) return result(`${kind === "agent" ? "Agent" : "Chain"} '${name}' not found in scope '${scope}'.`, true);
-	if (scoped.length > 1) return result(`Multiple ${kind}s named '${name}' found in scope '${scope}': ${scoped.map((m) => m.filePath).join(", ")}`, true);
+	if (scoped.length === 0)
+		return result(`${kind === "agent" ? "Agent" : "Chain"} '${name}' not found in scope '${scope}'.`, true);
+	if (scoped.length > 1)
+		return result(
+			`Multiple ${kind}s named '${name}' found in scope '${scope}': ${scoped.map((m) => m.filePath).join(", ")}`,
+			true,
+		);
 	return scoped[0]!;
 }
 
@@ -71,11 +105,14 @@ function renamePath(
 	scope: ManagementScope,
 	cwd: string,
 ): { filePath?: string; error?: string } {
-	if (nameExistsInScope(cwd, scope, newName, currentPath)) return { error: `Name '${newName}' already exists in ${scope} scope.` };
+	if (nameExistsInScope(cwd, scope, newName, currentPath))
+		return { error: `Name '${newName}' already exists in ${scope} scope.` };
 	const ext = kind === "agent" ? ".md" : currentPath.endsWith(".chain.json") ? ".chain.json" : ".chain.md";
 	const filePath = path.join(path.dirname(currentPath), `${newName}${ext}`);
 	if (fs.existsSync(filePath) && filePath !== currentPath) {
-		return { error: `File already exists at ${filePath} but is not a valid ${kind} definition. Remove or rename it first.` };
+		return {
+			error: `File already exists at ${filePath} but is not a valid ${kind} definition. Remove or rename it first.`,
+		};
 	}
 	fs.renameSync(currentPath, filePath);
 	return { filePath };
@@ -83,7 +120,11 @@ function renamePath(
 
 function formatAgentDetail(agent: AgentConfig): string {
 	const tools = [...(agent.tools ?? []), ...(agent.mcpDirectTools ?? []).map((t) => `mcp:${t}`)];
-	const lines: string[] = [`Agent: ${agent.name} (${agent.source})`, `Path: ${agent.filePath}`, `Description: ${agent.description}`];
+	const lines: string[] = [
+		`Agent: ${agent.name} (${agent.source})`,
+		`Path: ${agent.filePath}`,
+		`Description: ${agent.description}`,
+	];
 	if (agent.packageName) {
 		lines.push(`Local name: ${frontmatterNameForConfig(agent)}`);
 		lines.push(`Package: ${agent.packageName}`);
@@ -97,7 +138,8 @@ function formatAgentDetail(agent: AgentConfig): string {
 	lines.push(`Inherit skills: ${agent.inheritSkills ? "true" : "false"}`);
 	if (agent.defaultContext) lines.push(`Default context: ${agent.defaultContext}`);
 	if (agent.source === "builtin") lines.push(`Disabled: ${agent.disabled ? "true" : "false"}`);
-	if (agent.extensions !== undefined) lines.push(`Extensions: ${agent.extensions.length ? agent.extensions.join(", ") : "(none)"}`);
+	if (agent.extensions !== undefined)
+		lines.push(`Extensions: ${agent.extensions.length ? agent.extensions.join(", ") : "(none)"}`);
 	if (agent.thinking) lines.push(`Thinking: ${agent.thinking}`);
 	if (agent.output) lines.push(`Output: ${agent.output}`);
 	if (agent.defaultReads?.length) lines.push(`Reads: ${agent.defaultReads.join(", ")}`);
@@ -110,9 +152,24 @@ function formatAgentDetail(agent: AgentConfig): string {
 function formatChainStepDetail(step: ChainStepConfig, index: number): string[] {
 	const lines: string[] = [];
 	if (step.expand || step.collect) {
-		const parallel = step.parallel && !Array.isArray(step.parallel) && typeof step.parallel === "object" ? step.parallel as { agent?: unknown; task?: unknown; label?: unknown; outputSchema?: unknown } : undefined;
-		const expand = step.expand && typeof step.expand === "object" ? step.expand as { from?: { output?: unknown; path?: unknown }; item?: unknown; key?: unknown; maxItems?: unknown; onEmpty?: unknown } : undefined;
-		const collect = step.collect && typeof step.collect === "object" ? step.collect as { as?: unknown; outputSchema?: unknown } : undefined;
+		const parallel =
+			step.parallel && !Array.isArray(step.parallel) && typeof step.parallel === "object"
+				? (step.parallel as { agent?: unknown; task?: unknown; label?: unknown; outputSchema?: unknown })
+				: undefined;
+		const expand =
+			step.expand && typeof step.expand === "object"
+				? (step.expand as {
+						from?: { output?: unknown; path?: unknown };
+						item?: unknown;
+						key?: unknown;
+						maxItems?: unknown;
+						onEmpty?: unknown;
+					})
+				: undefined;
+		const collect =
+			step.collect && typeof step.collect === "object"
+				? (step.collect as { as?: unknown; outputSchema?: unknown })
+				: undefined;
 		lines.push(`${index + 1}. Dynamic fanout${typeof collect?.as === "string" ? ` -> ${collect.as}` : ""}`);
 		if (expand?.from) lines.push(`   Expand: ${String(expand.from.output ?? "?")}${String(expand.from.path ?? "")}`);
 		if (typeof expand?.item === "string") lines.push(`   Item variable: ${expand.item}`);
@@ -143,7 +200,11 @@ function formatChainStepDetail(step: ChainStepConfig, index: number): string[] {
 }
 
 function formatChainDetail(chain: ChainConfig): string {
-	const lines: string[] = [`Chain: ${chain.name} (${chain.source})`, `Path: ${chain.filePath}`, `Description: ${chain.description}`];
+	const lines: string[] = [
+		`Chain: ${chain.name} (${chain.source})`,
+		`Path: ${chain.filePath}`,
+		`Description: ${chain.description}`,
+	];
 	if (chain.packageName) {
 		lines.push(`Local name: ${frontmatterNameForConfig(chain)}`);
 		lines.push(`Package: ${chain.packageName}`);
@@ -158,19 +219,28 @@ function formatChainDetail(chain: ChainConfig): string {
 export function handleList(params: ManagementParams, ctx: ManagementContext): SubagentToolResult {
 	const scope = normalizeListScope(params.agentScope) ?? "both";
 	const d = discoverAgentsAll(ctx.cwd);
-	const scopedAgents = allAgents(d).filter((a) => scope === "both" || a.source === "builtin" || a.source === scope).sort((a, b) => a.name.localeCompare(b.name));
+	const scopedAgents = allAgents(d)
+		.filter((a) => scope === "both" || a.source === "builtin" || a.source === scope)
+		.sort((a, b) => a.name.localeCompare(b.name));
 	const agents = scopedAgents.filter((a) => !a.disabled);
-	const chains = d.chains.filter((c) => scope === "both" || c.source === scope).sort((a, b) => a.name.localeCompare(b.name));
+	const chains = d.chains
+		.filter((c) => scope === "both" || c.source === scope)
+		.sort((a, b) => a.name.localeCompare(b.name));
 	const diagnostics = d.chainDiagnostics.filter((entry) => scope === "both" || entry.source === scope);
 	const lines = [
 		"Executable agents:",
 		...(agents.length
-			? agents.map((a) => `- ${a.name} (${a.source}${a.defaultContext ? `, context: ${a.defaultContext}` : ""}): ${a.description}`)
+			? agents.map(
+					(a) =>
+						`- ${a.name} (${a.source}${a.defaultContext ? `, context: ${a.defaultContext}` : ""}): ${a.description}`,
+				)
 			: ["- (none)"]),
 		"",
 		"Chains:",
 		...(chains.length ? chains.map((c) => `- ${c.name} (${c.source}): ${c.description}`) : ["- (none)"]),
-		...(diagnostics.length ? ["", "Chain diagnostics:", ...diagnostics.map((entry) => `- ${entry.filePath}: ${entry.error}`)] : []),
+		...(diagnostics.length
+			? ["", "Chain diagnostics:", ...diagnostics.map((entry) => `- ${entry.filePath}: ${entry.error}`)]
+			: []),
 	];
 	return result(lines.join("\n"));
 }
@@ -210,10 +280,13 @@ export function handleCreate(params: ManagementParams, ctx: ManagementContext):
 	if (parsedConfig.error) return result(parsedConfig.error, true);
 	const cfg = parsedConfig.value;
 	if (!cfg) return result("config required for create.", true);
-	if (typeof cfg.name !== "string" || !cfg.name.trim()) return result("config.name is required and must be a non-empty string.", true);
-	if (typeof cfg.description !== "string" || !cfg.description.trim()) return result("config.description is required and must be a non-empty string.", true);
+	if (typeof cfg.name !== "string" || !cfg.name.trim())
+		return result("config.name is required and must be a non-empty string.", true);
+	if (typeof cfg.description !== "string" || !cfg.description.trim())
+		return result("config.description is required and must be a non-empty string.", true);
 	const name = sanitizeName(cfg.name);
-	if (!name) return result("config.name is invalid after sanitization. Use letters, numbers, spaces, or hyphens.", true);
+	if (!name)
+		return result("config.name is invalid after sanitization. Use letters, numbers, spaces, or hyphens.", true);
 	const parsedPackage = parsePackageConfig(cfg.package);
 	if (parsedPackage.error) return result(parsedPackage.error, true);
 	const runtimeName = buildRuntimeName(name, parsedPackage.packageName);
@@ -223,18 +296,36 @@ export function handleCreate(params: ManagementParams, ctx: ManagementContext):
 	const isChain = hasKey(cfg, "steps");
 	const d = discoverAgentsAll(ctx.cwd);
 	const targetDir = isChain
-		? scope === "user" ? d.userChainDir : d.projectChainDir ?? path.join(ctx.cwd, CONFIG_DIR_NAME, "chains")
-		: scope === "user" ? d.userDir : d.projectDir ?? path.join(ctx.cwd, CONFIG_DIR_NAME, "agents");
+		? scope === "user"
+			? d.userChainDir
+			: (d.projectChainDir ?? path.join(ctx.cwd, CONFIG_DIR_NAME, "chains"))
+		: scope === "user"
+			? d.userDir
+			: (d.projectDir ?? path.join(ctx.cwd, CONFIG_DIR_NAME, "agents"));
 	fs.mkdirSync(targetDir, { recursive: true });
-	if (nameExistsInScope(ctx.cwd, scope, runtimeName)) return result(`Name '${runtimeName}' already exists in ${scope} scope. Use update instead.`, true);
+	if (nameExistsInScope(ctx.cwd, scope, runtimeName))
+		return result(`Name '${runtimeName}' already exists in ${scope} scope. Use update instead.`, true);
 	const targetPath = path.join(targetDir, isChain ? `${runtimeName}.chain.md` : `${runtimeName}.md`);
-	if (fs.existsSync(targetPath)) return result(`File already exists at ${targetPath} but is not a valid ${isChain ? "chain" : "agent"} definition. Remove or rename it first.`, true);
+	if (fs.existsSync(targetPath))
+		return result(
+			`File already exists at ${targetPath} but is not a valid ${isChain ? "chain" : "agent"} definition. Remove or rename it first.`,
+			true,
+		);
 	const warnings: string[] = [];
-	if (!isChain && d.builtin.some((a) => a.name === runtimeName)) warnings.push(`Note: this shadows the builtin agent '${runtimeName}'.`);
+	if (!isChain && d.builtin.some((a) => a.name === runtimeName))
+		warnings.push(`Note: this shadows the builtin agent '${runtimeName}'.`);
 	if (isChain) {
 		const parsed = parseStepList(cfg.steps);
 		if (parsed.error) return result(parsed.error, true);
-		const chain: ChainConfig = { name: runtimeName, localName: name, packageName: parsedPackage.packageName, description: cfg.description.trim(), source: scope, filePath: targetPath, steps: parsed.steps! };
+		const chain: ChainConfig = {
+			name: runtimeName,
+			localName: name,
+			packageName: parsedPackage.packageName,
+			description: cfg.description.trim(),
+			source: scope,
+			filePath: targetPath,
+			steps: parsed.steps!,
+		};
 		fs.writeFileSync(targetPath, serializeChain(chain), "utf-8");
 		const missing = unknownChainAgents(ctx.cwd, chain.steps);
 		if (missing.length) warnings.push(`Warning: chain steps reference unknown agents: ${missing.join(", ")}.`);
@@ -275,13 +366,21 @@ export function handleUpdate(params: ManagementParams, ctx: ManagementContext):
 	const warnings: string[] = [];
 	if (params.agent) {
 		const scopeHint = asDisambiguationScope(params.agentScope);
-		const targetOrError = resolveTarget("agent", params.agent, findAgents(params.agent, ctx.cwd, scopeHint ?? "both"), ctx.cwd, params.agentScope);
+		const targetOrError = resolveTarget(
+			"agent",
+			params.agent,
+			findAgents(params.agent, ctx.cwd, scopeHint ?? "both"),
+			ctx.cwd,
+			params.agentScope,
+		);
 		if ("content" in targetOrError) return targetOrError;
 		const target = targetOrError;
 		const updated: AgentConfig = { ...target };
 		const oldName = target.name;
-		if (hasKey(cfg, "name") && (typeof cfg.name !== "string" || !cfg.name.trim())) return result("config.name must be a non-empty string when provided.", true);
-		if (hasKey(cfg, "description") && (typeof cfg.description !== "string" || !cfg.description.trim())) return result("config.description must be a non-empty string when provided.", true);
+		if (hasKey(cfg, "name") && (typeof cfg.name !== "string" || !cfg.name.trim()))
+			return result("config.name must be a non-empty string when provided.", true);
+		if (hasKey(cfg, "description") && (typeof cfg.description !== "string" || !cfg.description.trim()))
+			return result("config.description must be a non-empty string when provided.", true);
 		let newLocalName = target.localName ?? frontmatterNameForConfig(target);
 		if (hasKey(cfg, "name")) {
 			newLocalName = sanitizeName(cfg.name as string);
@@ -318,22 +417,33 @@ export function handleUpdate(params: ManagementParams, ctx: ManagementContext):
 		}
 		fs.writeFileSync(updated.filePath, serializeAgent(updated), "utf-8");
 		if (updated.name !== oldName) {
-			const refs = discoverAgentsAll(ctx.cwd).chains.filter((c) => c.steps.some((s) => s.agent === oldName)).map((c) => `${c.name} (${c.source})`);
+			const refs = discoverAgentsAll(ctx.cwd)
+				.chains.filter((c) => c.steps.some((s) => s.agent === oldName))
+				.map((c) => `${c.name} (${c.source})`);
 			if (refs.length) warnings.push(`Warning: chains still reference '${oldName}': ${refs.join(", ")}.`);
 		}
-		const headline = updated.name === oldName
-			? `Updated agent '${updated.name}' at ${updated.filePath}.`
-			: `Updated agent '${oldName}' to '${updated.name}' at ${updated.filePath}.`;
+		const headline =
+			updated.name === oldName
+				? `Updated agent '${updated.name}' at ${updated.filePath}.`
+				: `Updated agent '${oldName}' to '${updated.name}' at ${updated.filePath}.`;
 		return result([headline, ...warnings].join("\n"));
 	}
 	const scopeHint = asDisambiguationScope(params.agentScope);
-	const targetOrError = resolveTarget("chain", params.chainName!, findChains(params.chainName!, ctx.cwd, scopeHint ?? "both"), ctx.cwd, params.agentScope);
+	const targetOrError = resolveTarget(
+		"chain",
+		params.chainName!,
+		findChains(params.chainName!, ctx.cwd, scopeHint ?? "both"),
+		ctx.cwd,
+		params.agentScope,
+	);
 	if ("content" in targetOrError) return targetOrError;
 	const target = targetOrError;
 	const updated: ChainConfig = { ...target, steps: [...target.steps] };
 	const oldName = target.name;
-	if (hasKey(cfg, "name") && (typeof cfg.name !== "string" || !cfg.name.trim())) return result("config.name must be a non-empty string when provided.", true);
-	if (hasKey(cfg, "description") && (typeof cfg.description !== "string" || !cfg.description.trim())) return result("config.description must be a non-empty string when provided.", true);
+	if (hasKey(cfg, "name") && (typeof cfg.name !== "string" || !cfg.name.trim()))
+		return result("config.name must be a non-empty string when provided.", true);
+	if (hasKey(cfg, "description") && (typeof cfg.description !== "string" || !cfg.description.trim()))
+		return result("config.description must be a non-empty string when provided.", true);
 	let newLocalName = target.localName ?? frontmatterNameForConfig(target);
 	if (hasKey(cfg, "name")) {
 		newLocalName = sanitizeName(cfg.name as string);
@@ -366,10 +476,15 @@ export function handleUpdate(params: ManagementParams, ctx: ManagementContext):
 		if (renamed.error) return result(renamed.error, true);
 		updated.filePath = renamed.filePath!;
 	}
-	fs.writeFileSync(updated.filePath, updated.filePath.endsWith(".chain.json") ? serializeJsonChain(updated) : serializeChain(updated), "utf-8");
-	const headline = updated.name === oldName
-		? `Updated chain '${updated.name}' at ${updated.filePath}.`
-		: `Updated chain '${oldName}' to '${updated.name}' at ${updated.filePath}.`;
+	fs.writeFileSync(
+		updated.filePath,
+		updated.filePath.endsWith(".chain.json") ? serializeJsonChain(updated) : serializeChain(updated),
+		"utf-8",
+	);
+	const headline =
+		updated.name === oldName
+			? `Updated chain '${updated.name}' at ${updated.filePath}.`
+			: `Updated chain '${oldName}' to '${updated.name}' at ${updated.filePath}.`;
 	return result([headline, ...warnings].join("\n"));
 }
 
@@ -378,29 +493,53 @@ function handleDelete(params: ManagementParams, ctx: ManagementContext): Subagen
 	if (params.agent && params.chainName) return result("Specify either 'agent' or 'chainName', not both.", true);
 	const scopeHint = asDisambiguationScope(params.agentScope);
 	if (params.agent) {
-		const targetOrError = resolveTarget("agent", params.agent, findAgents(params.agent, ctx.cwd, scopeHint ?? "both"), ctx.cwd, params.agentScope);
+		const targetOrError = resolveTarget(
+			"agent",
+			params.agent,
+			findAgents(params.agent, ctx.cwd, scopeHint ?? "both"),
+			ctx.cwd,
+			params.agentScope,
+		);
 		if ("content" in targetOrError) return targetOrError;
 		const target = targetOrError;
 		fs.unlinkSync(target.filePath);
-		const refs = discoverAgentsAll(ctx.cwd).chains.filter((c) => c.steps.some((s) => s.agent === target.name)).map((c) => `${c.name} (${c.source})`);
+		const refs = discoverAgentsAll(ctx.cwd)
+			.chains.filter((c) => c.steps.some((s) => s.agent === target.name))
+			.map((c) => `${c.name} (${c.source})`);
 		const lines = [`Deleted agent '${target.name}' at ${target.filePath}.`];
 		if (refs.length) lines.push(`Warning: chains reference deleted agent '${target.name}': ${refs.join(", ")}.`);
 		return result(lines.join("\n"));
 	}
-	const targetOrError = resolveTarget("chain", params.chainName!, findChains(params.chainName!, ctx.cwd, scopeHint ?? "both"), ctx.cwd, params.agentScope);
+	const targetOrError = resolveTarget(
+		"chain",
+		params.chainName!,
+		findChains(params.chainName!, ctx.cwd, scopeHint ?? "both"),
+		ctx.cwd,
+		params.agentScope,
+	);
 	if ("content" in targetOrError) return targetOrError;
 	const target = targetOrError;
 	fs.unlinkSync(target.filePath);
 	return result(`Deleted chain '${target.name}' at ${target.filePath}.`);
 }
 
-export function handleManagementAction(action: string, params: ManagementParams, ctx: ManagementContext): SubagentToolResult {
+export function handleManagementAction(
+	action: string,
+	params: ManagementParams,
+	ctx: ManagementContext,
+): SubagentToolResult {
 	switch (action as ManagementAction) {
-		case "list": return handleList(params, ctx);
-		case "get": return handleGet(params, ctx);
-		case "create": return handleCreate(params, ctx);
-		case "update": return handleUpdate(params, ctx);
-		case "delete": return handleDelete(params, ctx);
-		default: return result(`Unknown action: ${action}`, true);
+		case "list":
+			return handleList(params, ctx);
+		case "get":
+			return handleGet(params, ctx);
+		case "create":
+			return handleCreate(params, ctx);
+		case "update":
+			return handleUpdate(params, ctx);
+		case "delete":
+			return handleDelete(params, ctx);
+		default:
+			return result(`Unknown action: ${action}`, true);
 	}
 }

package/dist/builtin/subagents/src/agents/agent-overrides.ts

@@ -1,13 +1,13 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
+import { getProjectAgentSettingsPath, getUserAgentSettingsPath } from "./agent-paths.ts";
 import {
-	EMPTY_SUBAGENT_SETTINGS,
 	type AgentConfig,
 	type BuiltinAgentOverrideBase,
 	type BuiltinAgentOverrideConfig,
+	EMPTY_SUBAGENT_SETTINGS,
 	type SubagentSettings,
 } from "./agent-types.ts";
-import { getProjectAgentSettingsPath, getUserAgentSettingsPath } from "./agent-paths.ts";
 
 export function splitToolList(rawTools: string[] | undefined): { tools?: string[]; mcpDirectTools?: string[] } {
 	const mcpDirectTools: string[] = [];
@@ -26,10 +26,7 @@ export function splitToolList(rawTools: string[] | undefined): { tools?: string[
 }
 
 function joinToolList(config: Pick<AgentConfig, "tools" | "mcpDirectTools">): string[] | undefined {
-	const joined = [
-		...(config.tools ?? []),
-		...(config.mcpDirectTools ?? []).map((tool) => `mcp:${tool}`),
-	];
+	const joined = [...(config.tools ?? []), ...(config.mcpDirectTools ?? []).map((tool) => `mcp:${tool}`)];
 	return joined.length > 0 ? joined : undefined;
 }
 
@@ -68,11 +65,16 @@ function cloneOverrideValue(override: BuiltinAgentOverrideConfig): BuiltinAgentO
 			? { fallbackModels: override.fallbackModels === false ? false : [...override.fallbackModels] }
 			: {}),
 		...(override.fallbackThinkingLevels !== undefined
-			? { fallbackThinkingLevels: override.fallbackThinkingLevels === false ? false : [...override.fallbackThinkingLevels] }
+			? {
+					fallbackThinkingLevels:
+						override.fallbackThinkingLevels === false ? false : [...override.fallbackThinkingLevels],
+				}
 			: {}),
 		...(override.thinking !== undefined ? { thinking: override.thinking } : {}),
 		...(override.systemPromptMode !== undefined ? { systemPromptMode: override.systemPromptMode } : {}),
-		...(override.inheritProjectContext !== undefined ? { inheritProjectContext: override.inheritProjectContext } : {}),
+		...(override.inheritProjectContext !== undefined
+			? { inheritProjectContext: override.inheritProjectContext }
+			: {}),
 		...(override.inheritSkills !== undefined ? { inheritSkills: override.inheritSkills } : {}),
 		...(override.defaultContext !== undefined ? { defaultContext: override.defaultContext } : {}),
 		...(override.disabled !== undefined ? { disabled: override.disabled } : {}),
@@ -107,7 +109,7 @@ function readSettingsFileStrict(filePath: string): Record<string, unknown> {
 
 function writeSettingsFile(filePath: string, settings: Record<string, unknown>): void {
 	fs.mkdirSync(path.dirname(filePath), { recursive: true });
-	fs.writeFileSync(filePath, JSON.stringify(settings, null, 2) + "\n", "utf-8");
+	fs.writeFileSync(filePath, `${JSON.stringify(settings, null, 2)}\n`, "utf-8");
 }
 
 function parseOverrideStringArrayOrFalse(
@@ -117,13 +119,17 @@ function parseOverrideStringArrayOrFalse(
 	if (value === undefined) return undefined;
 	if (value === false) return false;
 	if (!Array.isArray(value)) {
-		throw new Error(`Builtin override '${meta.name}' in '${meta.filePath}' has invalid '${meta.field}'; expected an array of strings or false.`);
+		throw new Error(
+			`Builtin override '${meta.name}' in '${meta.filePath}' has invalid '${meta.field}'; expected an array of strings or false.`,
+		);
 	}
 
 	const items: string[] = [];
 	for (const item of value) {
 		if (typeof item !== "string") {
-			throw new Error(`Builtin override '${meta.name}' in '${meta.filePath}' has invalid '${meta.field}'; expected an array of strings or false.`);
+			throw new Error(
+				`Builtin override '${meta.name}' in '${meta.filePath}' has invalid '${meta.field}'; expected an array of strings or false.`,
+			);
 		}
 		const trimmed = item.trim();
 		if (trimmed) items.push(trimmed);
@@ -145,19 +151,27 @@ function parseBuiltinOverrideEntry(
 
 	if ("model" in input) {
 		if (typeof input.model === "string" || input.model === false) override.model = input.model;
-		else throw new Error(`Builtin override '${name}' in '${filePath}' has invalid 'model'; expected a string or false.`);
+		else
+			throw new Error(
+				`Builtin override '${name}' in '${filePath}' has invalid 'model'; expected a string or false.`,
+			);
 	}
 
 	if ("thinking" in input) {
 		if (typeof input.thinking === "string" || input.thinking === false) override.thinking = input.thinking;
-		else throw new Error(`Builtin override '${name}' in '${filePath}' has invalid 'thinking'; expected a string or false.`);
+		else
+			throw new Error(
+				`Builtin override '${name}' in '${filePath}' has invalid 'thinking'; expected a string or false.`,
+			);
 	}
 
 	if ("systemPromptMode" in input) {
 		if (input.systemPromptMode === "append" || input.systemPromptMode === "replace") {
 			override.systemPromptMode = input.systemPromptMode;
 		} else {
-			throw new Error(`Builtin override '${name}' in '${filePath}' has invalid 'systemPromptMode'; expected 'append' or 'replace'.`);
+			throw new Error(
+				`Builtin override '${name}' in '${filePath}' has invalid 'systemPromptMode'; expected 'append' or 'replace'.`,
+			);
 		}
 	}
 
@@ -165,7 +179,9 @@ function parseBuiltinOverrideEntry(
 		if (typeof input.inheritProjectContext === "boolean") {
 			override.inheritProjectContext = input.inheritProjectContext;
 		} else {
-			throw new Error(`Builtin override '${name}' in '${filePath}' has invalid 'inheritProjectContext'; expected a boolean.`);
+			throw new Error(
+				`Builtin override '${name}' in '${filePath}' has invalid 'inheritProjectContext'; expected a boolean.`,
+			);
 		}
 	}
 
@@ -173,7 +189,9 @@ function parseBuiltinOverrideEntry(
 		if (typeof input.inheritSkills === "boolean") {
 			override.inheritSkills = input.inheritSkills;
 		} else {
-			throw new Error(`Builtin override '${name}' in '${filePath}' has invalid 'inheritSkills'; expected a boolean.`);
+			throw new Error(
+				`Builtin override '${name}' in '${filePath}' has invalid 'inheritSkills'; expected a boolean.`,
+			);
 		}
 	}
 
@@ -181,7 +199,9 @@ function parseBuiltinOverrideEntry(
 		if (input.defaultContext === "fresh" || input.defaultContext === "fork" || input.defaultContext === false) {
 			override.defaultContext = input.defaultContext;
 		} else {
-			throw new Error(`Builtin override '${name}' in '${filePath}' has invalid 'defaultContext'; expected 'fresh', 'fork', or false.`);
+			throw new Error(
+				`Builtin override '${name}' in '${filePath}' has invalid 'defaultContext'; expected 'fresh', 'fork', or false.`,
+			);
 		}
 	}
 
@@ -195,13 +215,22 @@ function parseBuiltinOverrideEntry(
 
 	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.`);
+		else
+			throw new Error(`Builtin override '${name}' in '${filePath}' has invalid 'systemPrompt'; expected a string.`);
 	}
 
-	const fallbackModels = parseOverrideStringArrayOrFalse(input.fallbackModels, { filePath, name, field: "fallbackModels" });
+	const fallbackModels = parseOverrideStringArrayOrFalse(input.fallbackModels, {
+		filePath,
+		name,
+		field: "fallbackModels",
+	});
 	if (fallbackModels !== undefined) override.fallbackModels = fallbackModels;
 
-	const fallbackThinkingLevels = parseOverrideStringArrayOrFalse(input.fallbackThinkingLevels, { filePath, name, field: "fallbackThinkingLevels" });
+	const fallbackThinkingLevels = parseOverrideStringArrayOrFalse(input.fallbackThinkingLevels, {
+		filePath,
+		name,
+		field: "fallbackThinkingLevels",
+	});
 	if (fallbackThinkingLevels !== undefined) override.fallbackThinkingLevels = fallbackThinkingLevels;
 
 	const skills = parseOverrideStringArrayOrFalse(input.skills, { filePath, name, field: "skills" });
@@ -272,13 +301,15 @@ function applyBuiltinOverride(
 		next.fallbackModels = override.fallbackModels === false ? undefined : [...override.fallbackModels];
 	}
 	if (override.fallbackThinkingLevels !== undefined) {
-		next.fallbackThinkingLevels = override.fallbackThinkingLevels === false ? undefined : [...override.fallbackThinkingLevels];
+		next.fallbackThinkingLevels =
+			override.fallbackThinkingLevels === false ? undefined : [...override.fallbackThinkingLevels];
 	}
 	if (override.thinking !== undefined) next.thinking = override.thinking === false ? undefined : override.thinking;
 	if (override.systemPromptMode !== undefined) next.systemPromptMode = override.systemPromptMode;
 	if (override.inheritProjectContext !== undefined) next.inheritProjectContext = override.inheritProjectContext;
 	if (override.inheritSkills !== undefined) next.inheritSkills = override.inheritSkills;
-	if (override.defaultContext !== undefined) next.defaultContext = override.defaultContext === false ? undefined : override.defaultContext;
+	if (override.defaultContext !== undefined)
+		next.defaultContext = override.defaultContext === false ? undefined : override.defaultContext;
 	if (override.disabled !== undefined) next.disabled = override.disabled;
 	if (override.systemPrompt !== undefined) next.systemPrompt = override.systemPrompt;
 	if (override.skills !== undefined) next.skills = override.skills === false ? undefined : [...override.skills];
@@ -326,16 +357,34 @@ export function applyBuiltinOverrides(
 
 export function buildBuiltinOverrideConfig(
 	base: BuiltinAgentOverrideBase,
-	draft: Pick<AgentConfig, "model" | "fallbackModels" | "fallbackThinkingLevels" | "thinking" | "systemPromptMode" | "inheritProjectContext" | "inheritSkills" | "defaultContext" | "disabled" | "systemPrompt" | "skills" | "tools" | "mcpDirectTools">,
+	draft: Pick<
+		AgentConfig,
+		| "model"
+		| "fallbackModels"
+		| "fallbackThinkingLevels"
+		| "thinking"
+		| "systemPromptMode"
+		| "inheritProjectContext"
+		| "inheritSkills"
+		| "defaultContext"
+		| "disabled"
+		| "systemPrompt"
+		| "skills"
+		| "tools"
+		| "mcpDirectTools"
+	>,
 ): BuiltinAgentOverrideConfig | undefined {
 	const override: BuiltinAgentOverrideConfig = {};
 
 	if (draft.model !== base.model) override.model = draft.model ?? false;
-	if (!arraysEqual(draft.fallbackModels, base.fallbackModels)) override.fallbackModels = draft.fallbackModels ? [...draft.fallbackModels] : false;
-	if (!arraysEqual(draft.fallbackThinkingLevels, base.fallbackThinkingLevels)) override.fallbackThinkingLevels = draft.fallbackThinkingLevels ? [...draft.fallbackThinkingLevels] : false;
+	if (!arraysEqual(draft.fallbackModels, base.fallbackModels))
+		override.fallbackModels = draft.fallbackModels ? [...draft.fallbackModels] : false;
+	if (!arraysEqual(draft.fallbackThinkingLevels, base.fallbackThinkingLevels))
+		override.fallbackThinkingLevels = draft.fallbackThinkingLevels ? [...draft.fallbackThinkingLevels] : false;
 	if (draft.thinking !== base.thinking) override.thinking = draft.thinking ?? false;
 	if (draft.systemPromptMode !== base.systemPromptMode) override.systemPromptMode = draft.systemPromptMode;
-	if (draft.inheritProjectContext !== base.inheritProjectContext) override.inheritProjectContext = draft.inheritProjectContext;
+	if (draft.inheritProjectContext !== base.inheritProjectContext)
+		override.inheritProjectContext = draft.inheritProjectContext;
 	if (draft.inheritSkills !== base.inheritSkills) override.inheritSkills = draft.inheritSkills;
 	if (draft.defaultContext !== base.defaultContext) override.defaultContext = draft.defaultContext ?? false;
 	if (draft.disabled !== base.disabled) override.disabled = draft.disabled ?? false;
@@ -358,12 +407,16 @@ export function saveBuiltinAgentOverride(
 	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 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>) }
+			: {};
 
 	agentOverrides[name] = cloneOverrideValue(override);
 	subagents.agentOverrides = agentOverrides;