@ferris1225/pi-subagents 4.3.0 → 4.3.2

package/src/agents.ts

@@ -39,7 +39,17 @@ const SHELL_TOOL_NAMES = new Set(["bash", "powershell"]);
  * Only used to break a tie when the parent has both enabled — a parent running a
  * single shell is followed as configured, whatever it is. */
 const NATIVE_SHELL_TOOL = process.platform === "win32" ? "powershell" : "bash";
-const PI_BUILTIN_TOOL_NAMES = new Set(["read", "bash", "powershell", "edit", "write", "grep", "find", "ls"]);
+const READ_ONLY_TOOL_NAMES = new Set([
+	"read",
+	"grep",
+	"find",
+	"ls",
+	"anchor_grep",
+	"web_search",
+	"fetch_content",
+	"resolve-library-id",
+	"query-docs",
+]);
 export const SUBAGENT_TOOL_NAMES = [
 	"subagent",
 	"subagent_control",
@@ -48,21 +58,26 @@ export const SUBAGENT_TOOL_NAMES = [
 const SUBAGENT_TOOL_NAME_SET = new Set<string>(SUBAGENT_TOOL_NAMES);
 
 /** Resolve every child against the parent's live tool selection. Roles without
- * an allowlist inherit the complete active set. Explicit lists keep only their
- * declared Pi built-ins, adapt an existing shell slot, and gain active extension/
- * SDK tools. pi-subagents controls are always removed so children stay leaves.
+ * an allowlist inherit the complete active set. Explicit lists are strict: they
+ * keep only declared tools that are active in the parent, with shell adaptation.
+ * Active extension/SDK tools are never added implicitly. pi-subagents controls
+ * are always removed so children stay leaves.
  *
  * A declared shell is one slot, so it resolves to one shell: the parent's, and
  * the host-native one when the parent runs both. A child never inherits a shell
- * the parent does not have — Pi's `--tools` allowlist overrides the child's own
- * `defaultTools` setting, so naming a shell the user disabled would hand it a
- * terminal they deliberately turned off. */
+ * the parent does not have. */
 export function resolveAgentTools(
 	agent: AgentConfig,
 	activeToolNames: readonly string[],
 ): AgentConfig {
 	const active = [...new Set(activeToolNames)].filter((tool) => !SUBAGENT_TOOL_NAME_SET.has(tool));
-	if (!agent.tools) return { ...agent, tools: active };
+	if (!agent.tools) {
+		return { ...agent, tools: agent.name === "scout" ? active.filter((tool) => READ_ONLY_TOOL_NAMES.has(tool)) : active };
+	}
+	const declaredTools = agent.name === "scout"
+		? agent.tools.filter((tool) => READ_ONLY_TOOL_NAMES.has(tool))
+		: agent.tools;
+	const activeSet = new Set(active);
 
 	const parentShellTools = active.filter((tool) => SHELL_TOOL_NAMES.has(tool));
 	const activeShellTools = parentShellTools.length > 1 && parentShellTools.includes(NATIVE_SHELL_TOOL)
@@ -70,32 +85,30 @@ export function resolveAgentTools(
 		: parentShellTools;
 	const tools: string[] = [];
 	let shellAdapted = false;
-	for (const tool of agent.tools) {
+	for (const tool of declaredTools) {
+		if (SUBAGENT_TOOL_NAME_SET.has(tool)) continue;
 		if (SHELL_TOOL_NAMES.has(tool)) {
 			if (!shellAdapted) tools.push(...activeShellTools);
 			shellAdapted = true;
-		} else if (PI_BUILTIN_TOOL_NAMES.has(tool) && !tools.includes(tool)) {
+		} else if (activeSet.has(tool) && !tools.includes(tool)) {
 			tools.push(tool);
 		}
 	}
-	for (const tool of active) {
-		if (PI_BUILTIN_TOOL_NAMES.has(tool) || tools.includes(tool)) continue;
-		tools.push(tool);
-	}
 	return { ...agent, tools };
 }
 
 /** Filesystem-write capability used by worktree admission and repository-lane
- * safety. Built-in read-only role names remain read-only even when overridden;
- * an omitted tool list inherits the parent's active set, so it counts as
- * write-capable unless the parent itself is read-only. */
+ * safety. Scout is a hard read-only boundary even with a project override.
+ * Omitted allowlists inherit arbitrary active tools and are therefore mutable.
+ * For explicit allowlists, only the canonical retrieval tools are proven
+ * read-only; shells and unknown custom tools are conservatively mutable. */
 export function isWriteCapableAgent(
 	agent: Pick<AgentConfig, "name" | "tools">,
 ): boolean {
 	if (agent.name === "scout") return false;
 	if (agent.name === "artisan" || agent.name === "steward") return true;
 	if (!agent.tools) return true;
-	return agent.tools.includes("edit") || agent.tools.includes("write");
+	return agent.tools.some((tool) => !READ_ONLY_TOOL_NAMES.has(tool));
 }
 
 const here = dirname(fileURLToPath(import.meta.url));

package/src/announcements.ts

@@ -1,21 +1,16 @@
-/** Session-start recovery, stale-config migration, and progress-surface installation. */
+/** Session-start recovery, stale-model cleanup, and progress-surface installation. */
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { existsSync } from "node:fs";
 import { FIRST_RUN_SETUP_HINT, loadConfig, saveConfig } from "./config.ts";
 import { availableModelsInScope, filterUnavailableModelOverrides } from "./models.ts";
-import { announceRecoveryRecords } from "./recovery.ts";
+import { announceRecoveryRecords, relocateRecoveryManifest } from "./recovery.ts";
 import type { SubagentRuntime } from "./runtime.ts";
 import { installActiveRunsStatus } from "./status.ts";
 import { installActiveRunsWidget } from "./widget.ts";
 
-/**
- * One-time-per-stale-override migration: keep agent model selections Pi still
- * reports as available, drop the rest back to dynamic main-model routing, and
- * tell the user what was removed. Saving the cleaned config is what makes it
- * one-time — the dropped refs no longer exist to re-trigger the notice.
- */
-async function migrateUnavailableAgentModels(
+/** Drop unavailable model overrides back to dynamic main-model routing. */
+async function removeUnavailableAgentModels(
 	ctx: { ui: { notify: (message: string, kind: "info" | "warning" | "error") => void } } & Parameters<typeof availableModelsInScope>[0],
 	runtime: SubagentRuntime,
 ): Promise<void> {
@@ -32,7 +27,7 @@ async function migrateUnavailableAgentModels(
 			"warning",
 		);
 	} catch {
-		/* migration failures are non-fatal */
+		/* stale-model cleanup is non-fatal */
 	}
 }
 
@@ -41,20 +36,11 @@ export function registerAnnouncements(pi: ExtensionAPI, runtime: SubagentRuntime
 		if (!existsSync(runtime.configPath)) {
 			ctx.ui.notify(`pi-subagents: ${FIRST_RUN_SETUP_HINT}`, "info");
 		}
+		await relocateRecoveryManifest(runtime.configPath);
 		await announceRecoveryRecords(runtime.configPath, ctx);
-		await migrateUnavailableAgentModels(ctx, runtime);
-		try {
-			const config = await loadConfig(runtime.configPath);
-			if (config.pendingSetupNotice) {
-				ctx.ui.notify(`pi-subagents: ${config.pendingSetupNotice}`, "info");
-				const { pendingSetupNotice: _cleared, ...rest } = config;
-				await saveConfig(rest, runtime.configPath);
-			}
-		} catch {
-			/* notice is non-fatal */
-		}
-		// Restore starts at extension load and session_start fires right behind
-		// it, so without this the notice reports whatever the race left behind.
+		await removeUnavailableAgentModels(ctx, runtime);
+		// Bootstrap also runs on session_start; wait so this notice sees restored
+		// threads instead of racing an empty list.
 		await runtime.durableRestore;
 		if (!runtime.restoredNotified && runtime.restoredRunIds.length > 0) {
 			runtime.restoredNotified = true;

package/src/background.ts

@@ -14,6 +14,7 @@ import { cpus } from "node:os";
 export type BackgroundTask = (signal: AbortSignal, controller: AbortController) => Promise<void>;
 
 interface PendingTask {
+	kind: "task";
 	task: BackgroundTask;
 	controller: AbortController;
 	complete: () => void;
@@ -29,6 +30,14 @@ interface PendingTask {
 	onError?: (error: unknown) => void | Promise<void>;
 }
 
+interface PendingAcquire {
+	kind: "acquire";
+	controller: AbortController;
+	resolve: (acquired: boolean) => void;
+}
+
+type PendingEntry = PendingTask | PendingAcquire;
+
 /** How many sub-agent processes may run at once, derived from the host instead
  * of being fixed: children wait on model I/O far more than on CPU, so the pool
  * scales with cores while the bounds keep tiny machines usable and huge ones
@@ -40,7 +49,7 @@ export function resolveSubagentConcurrency(cpuCount: number = cpus().length): nu
 
 export class BackgroundTaskQueue {
 	private concurrency: number;
-	private readonly pending: PendingTask[] = [];
+	private readonly pending: PendingEntry[] = [];
 	private readonly active = new Set<AbortController>();
 	/** Active tasks that no longer count toward the concurrency limit. They keep
 	 * every other guarantee: abortable, awaited by waitForTask/waitForIdle. */
@@ -67,7 +76,7 @@ export class BackgroundTaskQueue {
 			return controller;
 		}
 
-		this.pending.push({ task, controller, complete, onCancelled, onError });
+		this.pending.push({ kind: "task", task, controller, complete, onCancelled, onError });
 		this.drain();
 		return controller;
 	}
@@ -88,7 +97,7 @@ export class BackgroundTaskQueue {
 
 	/** Tasks still waiting for a free slot (never started). */
 	get pendingCount(): number {
-		return this.pending.length;
+		return this.pending.filter((entry) => entry.kind === "task").length;
 	}
 
 	/** Tasks currently holding a slot. Suspended tasks (lane waits, managed
@@ -114,6 +123,19 @@ export class BackgroundTaskQueue {
 		this.drain();
 	}
 
+	/** Reacquire a released process slot before a suspended task starts another
+	 * child process. Reacquisitions share FIFO order with not-yet-started tasks,
+	 * so lane waiters cannot bypass work already queued for the pool. */
+	acquire(controller: AbortController | undefined): Promise<boolean> {
+		if (!controller || this.stopped || controller.signal.aborted) return Promise.resolve(false);
+		if (this.active.has(controller)) return Promise.resolve(true);
+		if (!this.suspended.has(controller)) return Promise.resolve(false);
+		return new Promise<boolean>((resolve) => {
+			this.pending.push({ kind: "acquire", controller, resolve });
+			this.drain();
+		});
+	}
+
 	/** Cancel one queued/running task. Queued entries are removed immediately;
 	 * active entries resolve waitForTask only after their body and error handler
 	 * have quiesced and the concurrency slot has been released. */
@@ -123,8 +145,13 @@ export class BackgroundTaskQueue {
 		const index = this.pending.findIndex((entry) => entry.controller === controller);
 		if (index !== -1) {
 			const [entry] = this.pending.splice(index, 1);
-			this.runCancelled(entry.onCancelled);
-			entry.complete();
+			if (entry.kind === "task") {
+				this.runCancelled(entry.onCancelled);
+				entry.complete();
+			} else {
+				this.suspended.delete(controller);
+				entry.resolve(false);
+			}
 			this.drain();
 			this.resolveIdleWaiters();
 		}
@@ -143,8 +170,13 @@ export class BackgroundTaskQueue {
 
 		for (const entry of this.pending.splice(0)) {
 			entry.controller.abort();
-			this.runCancelled(entry.onCancelled);
-			entry.complete();
+			if (entry.kind === "task") {
+				this.runCancelled(entry.onCancelled);
+				entry.complete();
+			} else {
+				this.suspended.delete(entry.controller);
+				entry.resolve(false);
+			}
 		}
 		for (const controller of this.active) controller.abort();
 		for (const controller of this.suspended) controller.abort();
@@ -170,8 +202,23 @@ export class BackgroundTaskQueue {
 				return;
 			}
 			if (entry.controller.signal.aborted) {
-				this.runCancelled(entry.onCancelled);
-				entry.complete();
+				if (entry.kind === "task") {
+					this.runCancelled(entry.onCancelled);
+					entry.complete();
+				} else {
+					this.suspended.delete(entry.controller);
+					entry.resolve(false);
+				}
+				continue;
+			}
+
+			if (entry.kind === "acquire") {
+				if (!this.suspended.delete(entry.controller)) {
+					entry.resolve(false);
+					continue;
+				}
+				this.active.add(entry.controller);
+				entry.resolve(true);
 				continue;
 			}
 

package/src/completion.ts

@@ -98,7 +98,6 @@ export function createCompletionBatcher<T>(options: CompletionBatcherOptions<T>)
 export interface CompletionMessageItem {
 	agent: string;
 	block: string;
-	triggerTurn: boolean;
 	/** Final usage of the underlying run (or chain); aggregated into the group totals. */
 	usage?: UsageStats;
 }
@@ -115,11 +114,6 @@ export function formatCompletionMessage(items: readonly CompletionMessageItem[])
 	return `### Subagents completed (${items.length}): ${agents}\n\n${items.map((item) => item.block).join("\n\n")}${footer}`;
 }
 
-/** A grouped completion wakes the main agent when any member requires a turn. */
-export function completionGroupTriggersTurn(items: readonly CompletionMessageItem[]): boolean {
-	return items.some((item) => item.triggerTurn);
-}
-
 /** Minimal shape of an active run, for the "others still running" footer. Kept
  * decoupled from the monitor's RunView so this stays a pure, easily tested
  * formatter; the caller maps its live runs into this shape. */

package/src/config.ts

@@ -15,26 +15,6 @@ import { getAgentDir, withFileMutationQueue } from "@earendil-works/pi-coding-ag
 /** Full catalog of agents shipped with the package (selectable in /subagents-setup). */
 export const BUILTIN_AGENT_NAMES = ["scout", "artisan", "steward"] as const;
 
-/** Every shipped role stays enabled. The setup wizard and load-time adopt both
- * force the full team on so a stale allow-list cannot hide scout, artisan, or
- * steward. */
-export const REQUIRED_ENABLED_AGENTS = [...BUILTIN_AGENT_NAMES] as const;
-
-/** Built-in agent names this package no longer ships. Loading an older config
- * prunes them from every record so the setup wizard, dispatch catalog, and
- * model-routing table never surface dead roles. Custom names stay untouched —
- * except one that reuses a removed built-in name, which this cleanup cannot
- * distinguish and deliberately treats as retired. */
-export const REMOVED_BUILTIN_AGENT_NAMES = [
-	"worker",
-	"cleaner",
-	"documenter",
-	"synthesizer",
-	"reviewer",
-	"explorer",
-	"executor",
-] as const;
-
 /** Agents enabled out of the box on a fresh install. */
 export const DEFAULT_ENABLED_AGENTS: readonly string[] = [...BUILTIN_AGENT_NAMES];
 
@@ -72,15 +52,15 @@ export interface AgentProfile {
 export const AGENT_PROFILES: Record<(typeof BUILTIN_AGENT_NAMES)[number], AgentProfile> = {
 	scout: {
 		summary: "read-only recon",
-		remark: "Maps unfamiliar code. Returns exact paths and leads — never proof. Broad search, symbols, dependencies.",
+		remark: "Broad or unknown reconnaissance. Returns decisive citations as leads, never proof.",
 	},
 	artisan: {
 		summary: "implement / fix",
-		remark: "Writes the change. One deliverable: implement, fix, refactor, or test. Confirms a named defect before editing.",
+		remark: "Owns implementation, code refactors, and directly affected tests/docs; a disproved defect means zero edits.",
 	},
 	steward: {
-		summary: "tidy when needed",
-		remark: "Use only when that work exists: evidence-first cleanup, docs/comment sync, or merging fan-out results.",
+		summary: "pre-commit finish",
+		remark: "Cleans a completed broad or multi-writer diff and synchronizes cross-cutting docs/comments without changing behavior.",
 	},
 };
 
@@ -109,11 +89,6 @@ export const IDLE_TIMEOUT_SEC_LIMIT = 600;
 export interface SubagentsConfig {
 	/** Agent names that are discoverable and injected. Fresh-install default: every built-in agent. */
 	enabledAgents: string[];
-	/** Built-in names this config has already surfaced. A shipped agent outside
-	 * this set is new in an upgrade: loadConfig enables it instead of leaving it
-	 * dark behind a stale allow-list. Bookkeeping only — maintained automatically,
-	 * and it is what keeps an explicit disable from being undone. */
-	knownAgents: string[];
 	/** Per-agent model override, keyed by agent name, as "provider/model-id". */
 	agentModels: Record<string, string>;
 	/** Optional per-agent thinking override from `/subagents-setup`. Missing =
@@ -133,13 +108,10 @@ export interface SubagentsConfig {
 	 * off to the current main model. 0 disables the idle watchdog. Default: 90.
 	 */
 	idleTimeoutSec: number;
-	/** One-shot session notice after a catalog migration; announcements clears it. */
-	pendingSetupNotice?: string;
 }
 
 export const DEFAULT_CONFIG: SubagentsConfig = {
 	enabledAgents: [...DEFAULT_ENABLED_AGENTS],
-	knownAgents: [...BUILTIN_AGENT_NAMES],
 	agentModels: {},
 	agentThinkingLevels: {},
 	maxResultLines: DEFAULT_MAX_RESULT_LINES,
@@ -148,13 +120,10 @@ export const DEFAULT_CONFIG: SubagentsConfig = {
 };
 
 export const FIRST_RUN_SETUP_HINT =
-	"Run /subagents-setup: pick a model for scout, artisan, and steward. " +
-	"scout maps code (leads, not proof). artisan implements, fixes, refactors, or tests. " +
-	"steward tidies or merges only when that work exists. All three stay on. " +
-	"Each role has a thinking default you can change in setup.";
-
-export const TEAM_SETUP_NOTICE =
-	"The team is now scout, artisan, and steward. Run /subagents-setup to pick a model for each; thinking has a role default you can change there.";
+	"Run /subagents-setup to choose enabled roles and pick their models. " +
+	"Keep orchestration on the strongest main model; prefer an efficient model for scout and steward. " +
+	"Scout handles clustered broad reconnaissance, artisan implements with affected tests/docs, " +
+	"and steward finishes completed broad or multi-writer changes before commit.";
 
 export function getConfigPath(agentDir: string = getAgentDir()): string {
 	return join(agentDir, CONFIG_FILE_NAME);
@@ -197,20 +166,6 @@ export function normalizeConfig(raw: unknown): SubagentsConfig {
 		config.enabledAgents = [...new Set(names.map((name) => name.trim()))];
 	}
 
-	// Known-agent bookkeeping starts empty for a parsed record (not the fresh
-	// default) so loadConfig can still tell which shipped agents this config
-	// has never seen. Every enabled name was necessarily surfaced.
-	config.knownAgents = [];
-	if (Array.isArray(raw.knownAgents)) {
-		const names = raw.knownAgents.filter(
-			(name): name is string => typeof name === "string" && name.trim().length > 0,
-		);
-		config.knownAgents = [...new Set(names.map((name) => name.trim()))];
-	}
-	for (const name of config.enabledAgents) {
-		if (!config.knownAgents.includes(name)) config.knownAgents.push(name);
-	}
-
 	if (isRecord(raw.agentModels)) {
 		for (const [rawKey, value] of Object.entries(raw.agentModels)) {
 			const key = rawKey.trim();
@@ -245,10 +200,6 @@ export function normalizeConfig(raw: unknown): SubagentsConfig {
 		config.idleTimeoutSec = Math.max(0, Math.min(IDLE_TIMEOUT_SEC_LIMIT, Math.round(raw.idleTimeoutSec)));
 	}
 
-	if (typeof raw.pendingSetupNotice === "string" && raw.pendingSetupNotice.trim()) {
-		config.pendingSetupNotice = raw.pendingSetupNotice.trim();
-	}
-
 	return config;
 }
 
@@ -261,124 +212,10 @@ function defaultConfig(): SubagentsConfig {
 	};
 }
 
-export function withRequiredAgents(enabled: readonly string[]): string[] {
-	const next = [...enabled];
-	for (const name of REQUIRED_ENABLED_AGENTS) {
-		if (!next.includes(name)) next.push(name);
-	}
-	return next;
-}
-
-function forceRequiredAgents(config: SubagentsConfig): SubagentsConfig {
-	const enabledAgents = withRequiredAgents(config.enabledAgents);
-	const knownAgents = [...config.knownAgents];
-	for (const name of REQUIRED_ENABLED_AGENTS) {
-		if (!knownAgents.includes(name)) knownAgents.push(name);
-	}
-	return { ...config, enabledAgents, knownAgents };
-}
-
-/**
- * Drop every removed built-in role from an already-normalized config: enabled
- * and known lists, plus per-agent model and thinking routes. The schema-upgrade
- * persistence in loadConfig writes the pruned shape back to disk.
- */
-function pruneRemovedBuiltins(config: SubagentsConfig): SubagentsConfig {
-	const removed = new Set<string>(REMOVED_BUILTIN_AGENT_NAMES);
-	const filter = (names: readonly string[]): string[] => names.filter((name) => !removed.has(name));
-	const agentModels = { ...config.agentModels };
-	const agentThinkingLevels = { ...config.agentThinkingLevels };
-	for (const name of REMOVED_BUILTIN_AGENT_NAMES) {
-		delete agentModels[name];
-		delete agentThinkingLevels[name];
-	}
-	return {
-		...config,
-		enabledAgents: filter(config.enabledAgents),
-		knownAgents: filter(config.knownAgents),
-		agentModels,
-		agentThinkingLevels,
-	};
-}
-
-/**
- * A shipped agent the config has never recorded is new in this release; the
- * stale allow-list must not keep it dark. Enable it. Model and thinking stay
- * unset so the role default and current main model apply until setup.
- */
-function adoptNewBuiltins(config: SubagentsConfig): { config: SubagentsConfig; fresh: string[] } {
-	const known = new Set(config.knownAgents);
-	const fresh = BUILTIN_AGENT_NAMES.filter((name) => !known.has(name));
-	if (fresh.length === 0) return { config, fresh };
-	return {
-		config: {
-			...config,
-			enabledAgents: [...config.enabledAgents, ...fresh],
-			knownAgents: [...known, ...fresh],
-		},
-		fresh,
-	};
-}
-
-// --- v4 → current catalog migration. Delete this block in the next major. ---
-
-const RENAMED_BUILTIN_AGENTS: Record<string, string> = {
-	explorer: "scout",
-	executor: "artisan",
-};
-
-function renameNameList(names: readonly string[]): { names: string[]; changed: boolean } {
-	let changed = false;
-	const out: string[] = [];
-	for (const name of names) {
-		const mapped = RENAMED_BUILTIN_AGENTS[name] ?? name;
-		if (mapped !== name) changed = true;
-		if (!out.includes(mapped)) out.push(mapped);
-	}
-	return { names: out, changed };
-}
-
-function renameKeyedRecord<T>(record: Record<string, T>): { record: Record<string, T>; changed: boolean } {
-	let changed = false;
-	const out: Record<string, T> = {};
-	for (const [key, value] of Object.entries(record)) {
-		const mapped = RENAMED_BUILTIN_AGENTS[key] ?? key;
-		if (mapped !== key) changed = true;
-		if (!(mapped in out)) out[mapped] = value;
-	}
-	return { record: out, changed };
-}
-
-/** Map retired built-in names onto the current catalog and keep their models
- * and thinking overrides. Isolated so the next major can delete it. */
-function migrateRetiredBuiltinNames(config: SubagentsConfig): { config: SubagentsConfig; changed: boolean } {
-	const enabled = renameNameList(config.enabledAgents);
-	const known = renameNameList(config.knownAgents);
-	const models = renameKeyedRecord(config.agentModels);
-	const thinking = renameKeyedRecord(config.agentThinkingLevels);
-	const changed = enabled.changed || known.changed || models.changed || thinking.changed;
-	if (!changed) return { config, changed: false };
-	return {
-		changed: true,
-		config: {
-			...config,
-			enabledAgents: enabled.names,
-			knownAgents: known.names,
-			agentModels: models.record,
-			agentThinkingLevels: thinking.record,
-		},
-	};
-}
-
-// --- end v4 catalog migration ---
-
 /**
  * Load config. A missing file is a normal state and yields the defaults (not an error).
  * A corrupt file also falls back to defaults rather than throwing, so startup never breaks.
- * A file from an older version (missing newer keys or holding extra keys) is
- * normalized and persisted back, so the on-disk config stays current. Built-in
- * agents the file has never seen are adopted. Retired built-in names are
- * renamed or pruned. Artisan and steward stay enabled.
+ * Valid fields are normalized and unknown fields are omitted when the config is saved.
  */
 export async function loadConfig(configPath: string = getConfigPath()): Promise<SubagentsConfig> {
 	let text: string;
@@ -396,15 +233,9 @@ export async function loadConfig(configPath: string = getConfigPath()): Promise<
 		return defaultConfig();
 	}
 
-	const renamed = migrateRetiredBuiltinNames(normalizeConfig(parsed));
-	const adopted = adoptNewBuiltins(renamed.config);
-	let config = forceRequiredAgents(pruneRemovedBuiltins(adopted.config));
-	if ((renamed.changed || adopted.fresh.length > 0) && !config.pendingSetupNotice) {
-		config = { ...config, pendingSetupNotice: TEAM_SETUP_NOTICE };
-	}
+	const config = normalizeConfig(parsed);
 
-	// Schema upgrade: persist the normalized shape when the file gained fields
-	// (new version) or dropped invalid ones.
+	// Persist the canonical shape when invalid or unknown fields were omitted.
 	if (JSON.stringify(config) !== JSON.stringify(parsed)) {
 		try {
 			await saveConfig(config, configPath);