@ferris1225/pi-subagents 4.0.1 → 4.1.1

package/src/config.ts

@@ -27,6 +27,20 @@ export type AgentScope = (typeof AGENT_SCOPE_VALUES)[number];
 
 const LEGACY_EXPLORER_NAME = "explore";
 const EXPLORER_NAME = "explorer";
+const CLEANER_NAME = "cleaner";
+const REVIEWER_NAME = "reviewer";
+
+/**
+ * Stamps recorded in `announcedFeatures` by the one-time upgrade that defaults
+ * cleaner on for configs written before it shipped. The first marks a config as
+ * processed, so a later deliberate disable is not undone; the second records
+ * that cleaner was actually injected, so session start can tell the user once;
+ * the third records that reviewer model/thinking settings were actually copied,
+ * so that notice never claims an inheritance that did not happen.
+ */
+export const CLEANER_DEFAULTED_FEATURE = "cleanerDefaulted";
+export const CLEANER_AUTO_ENABLED_FEATURE = "cleanerAutoEnabled";
+export const CLEANER_INHERITED_FEATURE = "cleanerInheritedReviewer";
 
 function migrateAgentName(name: string): string {
 	return name === LEGACY_EXPLORER_NAME ? EXPLORER_NAME : name;
@@ -106,8 +120,9 @@ export interface SubagentsConfig {
 	 */
 	idleTimeoutSec: number;
 	/**
-	 * One-time feature announcements already shown to the user. Persisted so
-	 * the notice never nags again.
+	 * One-time feature announcements already shown to the user, plus schema
+	 * upgrade stamps (e.g. the cleaner default-enable upgrade). Persisted so
+	 * notices and migrations never repeat.
 	 */
 	announcedFeatures: string[];
 }
@@ -241,6 +256,32 @@ export function normalizeConfig(raw: unknown): SubagentsConfig {
 		);
 	}
 
+	// One-time upgrade for configs written before cleaner shipped: a non-empty
+	// explicit enabledAgents list gets cleaner defaulted on (inserted before
+	// reviewer, matching the fresh-install order) and inherits the reviewer's
+	// configured model and thinking level — its closest peer. The stamps make
+	// the upgrade idempotent and keep a later deliberate disable from being undone.
+	if (!config.announcedFeatures.includes(CLEANER_DEFAULTED_FEATURE)) {
+		config.announcedFeatures.push(CLEANER_DEFAULTED_FEATURE);
+		if (config.enabledAgents.length > 0 && !config.enabledAgents.includes(CLEANER_NAME)) {
+			const reviewerIndex = config.enabledAgents.indexOf(REVIEWER_NAME);
+			config.enabledAgents.splice(reviewerIndex === -1 ? config.enabledAgents.length : reviewerIndex, 0, CLEANER_NAME);
+			config.announcedFeatures.push(CLEANER_AUTO_ENABLED_FEATURE);
+			let inherited = false;
+			if (!config.agentModels[CLEANER_NAME] && config.agentModels[REVIEWER_NAME]) {
+				config.agentModels[CLEANER_NAME] = config.agentModels[REVIEWER_NAME];
+				inherited = true;
+			}
+			if (!config.agentThinkingLevels[CLEANER_NAME] && config.agentThinkingLevels[REVIEWER_NAME]) {
+				config.agentThinkingLevels[CLEANER_NAME] = config.agentThinkingLevels[REVIEWER_NAME];
+				inherited = true;
+			}
+			// An old explicit list may have no reviewer overrides to copy; only the
+			// copied case is stamped so the one-time notice stays accurate.
+			if (inherited) config.announcedFeatures.push(CLEANER_INHERITED_FEATURE);
+		}
+	}
+
 	return config;
 }
 

package/src/index.ts

@@ -1,93 +1,93 @@
-/**
- * pi-subagents — focused sub-agent delegation for pi.
- *
- * Assembly point: builds the shared runtime and registers everything.
- * The heavy lifting lives in focused modules:
- *   - dispatch.ts         — the `subagent` tool contract and auto-fix chain
- *   - thread-lifecycle.ts — queued generations, resume/fork, isolation settlement
- *   - tools.ts            — subagent_control / subagent_wait / status / stop
- *   - announcements.ts — session-start recovery, notices, and widget install
- *   - widget.ts        — active-only TUI run status
- *   - runtime.ts       — shared per-session state
- *
- * Also registers the `/subagents-setup` command and a `before_agent_start` hook
- * that injects a delegation directive into the parent system prompt so the main
- * model uses the tool proactively.
- *
- * The tool is not registered inside child sub-agent processes, which prevents
- * runaway recursion and keeps child context windows clean.
- */
-
-import { getAgentDir, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { Text } from "@earendil-works/pi-tui";
-import { discoverAgents } from "./agents.ts";
-import { registerAnnouncements } from "./announcements.ts";
-import { getConfigPath, loadConfig } from "./config.ts";
-import { registerSubagentTool } from "./dispatch.ts";
-import { matchRunIds } from "./format.ts";
-import { buildDelegationDirective } from "./prompt.ts";
-import { createRuntime } from "./runtime.ts";
-import { runSetup } from "./setup.ts";
-import { currentSubagentDepth } from "./spawn.ts";
-import { registerLookupTools } from "./tools.ts";
-import { clearActiveRunsWidget } from "./widget.ts";
-
-export { matchRunIds };
-
-export default function (pi: ExtensionAPI): void {
-	const configPath = getConfigPath(getAgentDir());
-	const runtime = createRuntime(pi, configPath);
-
-	// Recursion guard: sub-agent children are leaf processes. The `subagent` tool is
-	// excluded from their toolset at spawn (--exclude-tools); this check is defense
-	// in depth so a child can never expose the tool back to its model, even if
-	// another extension ignores the depth marker.
-	if (currentSubagentDepth() >= 1) {
-		pi.registerCommand("subagents-setup", {
-			description: "Configure pi-subagents (unavailable in nested sub-agent processes)",
-			handler: async (_args, ctx) => {
-				ctx.ui.notify("pi-subagents setup is unavailable in nested sub-agent processes.", "warning");
-			},
-		});
-		return;
-	}
-
-	pi.registerMessageRenderer("subagent-result", (message, _options, theme) =>
-		new Text(
-			`${theme.fg("toolTitle", theme.bold("subagent result"))}\n${message.content}`,
-			0,
-			0,
-		),
-	);
-
-	pi.on("session_shutdown", async (_event, ctx) => {
-		clearActiveRunsWidget(ctx);
-		await runtime.shutdown();
-	});
-
-	registerSubagentTool(pi, runtime);
-	registerLookupTools(pi, runtime);
-
-	pi.registerCommand("subagents-setup", {
-		description: "Configure pi-subagents: agents, selected models, capability-aware thinking, and runtime settings",
-		handler: async (_args, ctx) => {
-			await runSetup(ctx, configPath);
-		},
-	});
-
-	registerAnnouncements(pi, runtime);
-
-	// Proactive dispatch: inject the delegation directive into the parent system prompt.
-	pi.on("before_agent_start", async (event, ctx) => {
-		const config = await loadConfig(configPath);
-		if (!config.proactiveInjection) return undefined;
-		const { agents } = discoverAgents(ctx.cwd, {
-			scope: config.agentScope,
-			enabledNames: config.enabledAgents,
-			projectTrusted: ctx.isProjectTrusted?.() === true,
-		});
-		const directive = buildDelegationDirective(agents);
-		if (!directive) return undefined;
-		return { systemPrompt: `${event.systemPrompt}\n${directive}` };
-	});
-}
+/**
+ * pi-subagents — focused sub-agent delegation for pi.
+ *
+ * Assembly point: builds the shared runtime and registers everything.
+ * The heavy lifting lives in focused modules:
+ *   - dispatch.ts         — the `subagent` tool contract and auto-fix chain
+ *   - thread-lifecycle.ts — queued generations, resume/fork, isolation settlement
+ *   - tools.ts            — subagent_control / subagent_wait / status / stop
+ *   - announcements.ts — session-start recovery, notices, and widget install
+ *   - widget.ts        — active-only TUI run status
+ *   - runtime.ts       — shared per-session state
+ *
+ * Also registers the `/subagents-setup` command and a `before_agent_start` hook
+ * that injects a delegation directive into the parent system prompt so the main
+ * model uses the tool proactively.
+ *
+ * The tool is not registered inside child sub-agent processes, which prevents
+ * runaway recursion and keeps child context windows clean.
+ */
+
+import { getAgentDir, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+import { discoverAgents } from "./agents.ts";
+import { registerAnnouncements } from "./announcements.ts";
+import { getConfigPath, loadConfig } from "./config.ts";
+import { registerSubagentTool } from "./dispatch.ts";
+import { matchRunIds } from "./format.ts";
+import { buildDelegationDirective } from "./prompt.ts";
+import { createRuntime } from "./runtime.ts";
+import { runSetup } from "./setup.ts";
+import { currentSubagentDepth } from "./spawn.ts";
+import { registerLookupTools } from "./tools.ts";
+import { clearActiveRunsWidget } from "./widget.ts";
+
+export { matchRunIds };
+
+export default function (pi: ExtensionAPI): void {
+	const configPath = getConfigPath(getAgentDir());
+	const runtime = createRuntime(pi, configPath);
+
+	// Recursion guard: sub-agent children are leaf processes. The `subagent` tool is
+	// excluded from their toolset at spawn (--exclude-tools); this check is defense
+	// in depth so a child can never expose the tool back to its model, even if
+	// another extension ignores the depth marker.
+	if (currentSubagentDepth() >= 1) {
+		pi.registerCommand("subagents-setup", {
+			description: "Configure pi-subagents (unavailable in nested sub-agent processes)",
+			handler: async (_args, ctx) => {
+				ctx.ui.notify("pi-subagents setup is unavailable in nested sub-agent processes.", "warning");
+			},
+		});
+		return;
+	}
+
+	pi.registerMessageRenderer("subagent-result", (message, _options, theme) =>
+		new Text(
+			`${theme.fg("toolTitle", theme.bold("subagent result"))}\n${message.content}`,
+			0,
+			0,
+		),
+	);
+
+	pi.on("session_shutdown", async (_event, ctx) => {
+		clearActiveRunsWidget(ctx);
+		await runtime.shutdown();
+	});
+
+	registerSubagentTool(pi, runtime);
+	registerLookupTools(pi, runtime);
+
+	pi.registerCommand("subagents-setup", {
+		description: "Configure pi-subagents: agents, selected models, capability-aware thinking, and runtime settings",
+		handler: async (_args, ctx) => {
+			await runSetup(ctx, configPath);
+		},
+	});
+
+	registerAnnouncements(pi, runtime);
+
+	// Proactive dispatch: inject the delegation directive into the parent system prompt.
+	pi.on("before_agent_start", async (event, ctx) => {
+		const config = await loadConfig(configPath);
+		if (!config.proactiveInjection) return undefined;
+		const { agents } = discoverAgents(ctx.cwd, {
+			scope: config.agentScope,
+			enabledNames: config.enabledAgents,
+			projectTrusted: ctx.isProjectTrusted?.() === true,
+		});
+		const directive = buildDelegationDirective(agents);
+		if (!directive) return undefined;
+		return { systemPrompt: `${event.systemPrompt}\n${directive}` };
+	});
+}

package/src/models.ts

@@ -1,189 +1,189 @@
-/*
- * Model routing, capability-aware thinking, and setup-picker helpers.
- *
- * Runtime has one explicit fallback only: a configured agent model hands
- * off directly to the current main-window model. Setup lists only currently
- * available models and derives thinking choices from Pi's model metadata.
- */
-
-import {
-	clampThinkingLevel,
-	getSupportedThinkingLevels,
-	type Api,
-	type Model,
-} from "@earendil-works/pi-ai";
-import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { DEFAULT_THINKING_LEVEL, type ThinkingLevel } from "./config.ts";
-
-export type ModelContext = Pick<ExtensionContext, "model" | "modelRegistry"> &
-	Partial<Pick<ExtensionContext, "scopedModels">>;
-
-export const CURRENT_MAIN_MODEL = "__current_main_model__";
-
-export interface ModelPickerItem {
-	value: string;
-	label: string;
-	description?: string;
-}
-
-export type ModelListEntry = Pick<
-	Model<Api>,
-	"provider" | "id" | "name" | "input" | "reasoning" | "thinkingLevelMap"
->;
-
-export interface ResolvedAgentModelRoute {
-	/** Effective first candidate. Undefined means let Pi use its normal default. */
-	primaryRef?: string;
-	/** Current main-window model when it differs from the selection. */
-	mainFallbackRef?: string;
-	/** Runtime order, useful for status/tests. */
-	candidateRefs: string[];
-	/** Configured ref skipped because Pi does not currently report it available. */
-	unavailableSelectedRef?: string;
-}
-
-export interface AgentModelRouteInput {
-	selectedRef?: string;
-	mainRef?: string;
-	declaredDefaultRef?: string;
-	/** When supplied, a configured selection outside this live set is skipped. */
-	availableRefs?: readonly string[];
-}
-
-function cleanModelRef(ref: string | undefined): string | undefined {
-	const trimmed = ref?.trim();
-	return trimmed || undefined;
-}
-
-export function modelRef(model: { provider: string; id: string }): string {
-	return `${model.provider}/${model.id}`;
-}
-
-export function currentModelRef(ctx: Pick<ModelContext, "model">): string | undefined {
-	return ctx.model ? modelRef(ctx.model) : undefined;
-}
-
-/**
- * Current authenticated registry models narrowed by the session scope. Scope
- * entries are a session snapshot, so they act only as a whitelist; the live
- * registry remains the source of truth for availability and model metadata.
- */
-export function availableModelsInScope(ctx: ModelContext): readonly Model<Api>[] {
-	const models = ctx.modelRegistry.getAvailable();
-	// scopedModels was added after the original Pi minimum. Treat a missing field
-	// exactly like an empty scope and use the full live registry.
-	const scopedModels = ctx.scopedModels ?? [];
-	if (scopedModels.length === 0) return models;
-	const scopedRefs = new Set(scopedModels.map((entry) => modelRef(entry.model)));
-	return models.filter((model) => scopedRefs.has(modelRef(model)));
-}
-
-export function findModelByRef(
-	models: readonly Model<Api>[],
-	ref: string | undefined,
-): Model<Api> | undefined {
-	const normalized = cleanModelRef(ref);
-	return normalized ? models.find((model) => modelRef(model) === normalized) : undefined;
-}
-
-/**
- * Resolve one agent's runtime route:
- *
- * configured selection -> current main-window model
- *
- * Without an override, current main is primary; the agent-declared default is
- * used only when no main model exists. A configured selection that Pi no longer
- * reports as available is skipped immediately instead of spawning a doomed child.
- */
-export function resolveAgentModelRoute(input: AgentModelRouteInput): ResolvedAgentModelRoute {
-	const selectedRef = cleanModelRef(input.selectedRef);
-	const mainRef = cleanModelRef(input.mainRef);
-	const declaredDefaultRef = cleanModelRef(input.declaredDefaultRef);
-	const available = input.availableRefs
-		? new Set(input.availableRefs.map((ref) => ref.trim()).filter(Boolean))
-		: undefined;
-	const selectedAvailable = !selectedRef || !available || available.has(selectedRef);
-	const usableSelectedRef = selectedAvailable ? selectedRef : undefined;
-	const primaryRef = usableSelectedRef ?? mainRef ?? declaredDefaultRef;
-	const ordered = [primaryRef, usableSelectedRef && usableSelectedRef !== mainRef ? mainRef : undefined];
-	const candidateRefs = [...new Set(ordered.filter((ref): ref is string => Boolean(ref)))];
-	return {
-		primaryRef,
-		...(candidateRefs[1] ? { mainFallbackRef: candidateRefs[1] } : {}),
-		candidateRefs,
-		...(!selectedAvailable && selectedRef ? { unavailableSelectedRef: selectedRef } : {}),
-	};
-}
-
-/** The exact levels Pi exposes for this model, including `off` when supported. */
-export function supportedThinkingLevels(model: Model<Api> | undefined): ThinkingLevel[] {
-	return model ? (getSupportedThinkingLevels(model) as ThinkingLevel[]) : [];
-}
-
-/** Clamp an agent preference to the effective model's actual capability map. */
-export function resolveThinkingLevel(
-	model: Model<Api> | undefined,
-	preferred: ThinkingLevel = DEFAULT_THINKING_LEVEL,
-): ThinkingLevel {
-	return model ? (clampThinkingLevel(model, preferred) as ThinkingLevel) : preferred;
-}
-
-function modelCapabilities(model: ModelListEntry): string {
-	const input = model.input.includes("image") ? "vision" : "text-only";
-	const thinking = getSupportedThinkingLevels(model as Model<Api>).join("/");
-	return `${input} · thinking: ${thinking}`;
-}
-
-/** Build one searchable list for agent model selection. Only models Pi
- * currently reports as available are supplied by setup. */
-export function buildModelPickerItems(options: {
-	models: readonly ModelListEntry[];
-	configuredRef?: string;
-	mainRef?: string;
-}): ModelPickerItem[] {
-	const configuredRef = cleanModelRef(options.configuredRef);
-	const mainRef = cleanModelRef(options.mainRef);
-	const byRef = new Map<string, ModelListEntry>();
-	for (const model of options.models) {
-		const ref = modelRef(model);
-		if (!byRef.has(ref)) byRef.set(ref, model);
-	}
-
-	const refs = [...byRef.keys()]
-		.sort((left, right) => {
-			const leftRank = left === configuredRef ? 0 : left === mainRef ? 1 : 2;
-			const rightRank = right === configuredRef ? 0 : right === mainRef ? 1 : 2;
-			return leftRank - rightRank || left.localeCompare(right);
-		});
-
-	const dynamic: ModelPickerItem = {
-		value: CURRENT_MAIN_MODEL,
-		label: "Current main model (dynamic)",
-		description: "Clear agent override; use the current main model dynamically",
-	};
-	const items: ModelPickerItem[] = [dynamic];
-	for (const ref of refs) {
-		const model = byRef.get(ref)!;
-		const tags = [ref === configuredRef ? "configured" : "", ref === mainRef ? "current main" : ""]
-			.filter(Boolean);
-		const name = model.name.trim() && model.name !== model.id ? model.name.trim() : undefined;
-		items.push({
-			value: ref,
-			label: ref,
-			description: [name, modelCapabilities(model), ...tags].filter(Boolean).join(" · "),
-		});
-	}
-	return items;
-}
-
-/** The dynamic choice removes the persisted per-agent override. */
-export function applyAgentModelChoice(
-	current: Record<string, string>,
-	agentName: string,
-	choice: string,
-): Record<string, string> {
-	const next = { ...current };
-	if (choice === CURRENT_MAIN_MODEL) delete next[agentName];
-	else next[agentName] = choice.trim();
-	return next;
-}
+/*
+ * Model routing, capability-aware thinking, and setup-picker helpers.
+ *
+ * Runtime has one explicit fallback only: a configured agent model hands
+ * off directly to the current main-window model. Setup lists only currently
+ * available models and derives thinking choices from Pi's model metadata.
+ */
+
+import {
+	clampThinkingLevel,
+	getSupportedThinkingLevels,
+	type Api,
+	type Model,
+} from "@earendil-works/pi-ai";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { DEFAULT_THINKING_LEVEL, type ThinkingLevel } from "./config.ts";
+
+export type ModelContext = Pick<ExtensionContext, "model" | "modelRegistry"> &
+	Partial<Pick<ExtensionContext, "scopedModels">>;
+
+export const CURRENT_MAIN_MODEL = "__current_main_model__";
+
+export interface ModelPickerItem {
+	value: string;
+	label: string;
+	description?: string;
+}
+
+export type ModelListEntry = Pick<
+	Model<Api>,
+	"provider" | "id" | "name" | "input" | "reasoning" | "thinkingLevelMap"
+>;
+
+export interface ResolvedAgentModelRoute {
+	/** Effective first candidate. Undefined means let Pi use its normal default. */
+	primaryRef?: string;
+	/** Current main-window model when it differs from the selection. */
+	mainFallbackRef?: string;
+	/** Runtime order, useful for status/tests. */
+	candidateRefs: string[];
+	/** Configured ref skipped because Pi does not currently report it available. */
+	unavailableSelectedRef?: string;
+}
+
+export interface AgentModelRouteInput {
+	selectedRef?: string;
+	mainRef?: string;
+	declaredDefaultRef?: string;
+	/** When supplied, a configured selection outside this live set is skipped. */
+	availableRefs?: readonly string[];
+}
+
+function cleanModelRef(ref: string | undefined): string | undefined {
+	const trimmed = ref?.trim();
+	return trimmed || undefined;
+}
+
+export function modelRef(model: { provider: string; id: string }): string {
+	return `${model.provider}/${model.id}`;
+}
+
+export function currentModelRef(ctx: Pick<ModelContext, "model">): string | undefined {
+	return ctx.model ? modelRef(ctx.model) : undefined;
+}
+
+/**
+ * Current authenticated registry models narrowed by the session scope. Scope
+ * entries are a session snapshot, so they act only as a whitelist; the live
+ * registry remains the source of truth for availability and model metadata.
+ */
+export function availableModelsInScope(ctx: ModelContext): readonly Model<Api>[] {
+	const models = ctx.modelRegistry.getAvailable();
+	// scopedModels was added after the original Pi minimum. Treat a missing field
+	// exactly like an empty scope and use the full live registry.
+	const scopedModels = ctx.scopedModels ?? [];
+	if (scopedModels.length === 0) return models;
+	const scopedRefs = new Set(scopedModels.map((entry) => modelRef(entry.model)));
+	return models.filter((model) => scopedRefs.has(modelRef(model)));
+}
+
+export function findModelByRef(
+	models: readonly Model<Api>[],
+	ref: string | undefined,
+): Model<Api> | undefined {
+	const normalized = cleanModelRef(ref);
+	return normalized ? models.find((model) => modelRef(model) === normalized) : undefined;
+}
+
+/**
+ * Resolve one agent's runtime route:
+ *
+ * configured selection -> current main-window model
+ *
+ * Without an override, current main is primary; the agent-declared default is
+ * used only when no main model exists. A configured selection that Pi no longer
+ * reports as available is skipped immediately instead of spawning a doomed child.
+ */
+export function resolveAgentModelRoute(input: AgentModelRouteInput): ResolvedAgentModelRoute {
+	const selectedRef = cleanModelRef(input.selectedRef);
+	const mainRef = cleanModelRef(input.mainRef);
+	const declaredDefaultRef = cleanModelRef(input.declaredDefaultRef);
+	const available = input.availableRefs
+		? new Set(input.availableRefs.map((ref) => ref.trim()).filter(Boolean))
+		: undefined;
+	const selectedAvailable = !selectedRef || !available || available.has(selectedRef);
+	const usableSelectedRef = selectedAvailable ? selectedRef : undefined;
+	const primaryRef = usableSelectedRef ?? mainRef ?? declaredDefaultRef;
+	const ordered = [primaryRef, usableSelectedRef && usableSelectedRef !== mainRef ? mainRef : undefined];
+	const candidateRefs = [...new Set(ordered.filter((ref): ref is string => Boolean(ref)))];
+	return {
+		primaryRef,
+		...(candidateRefs[1] ? { mainFallbackRef: candidateRefs[1] } : {}),
+		candidateRefs,
+		...(!selectedAvailable && selectedRef ? { unavailableSelectedRef: selectedRef } : {}),
+	};
+}
+
+/** The exact levels Pi exposes for this model, including `off` when supported. */
+export function supportedThinkingLevels(model: Model<Api> | undefined): ThinkingLevel[] {
+	return model ? (getSupportedThinkingLevels(model) as ThinkingLevel[]) : [];
+}
+
+/** Clamp an agent preference to the effective model's actual capability map. */
+export function resolveThinkingLevel(
+	model: Model<Api> | undefined,
+	preferred: ThinkingLevel = DEFAULT_THINKING_LEVEL,
+): ThinkingLevel {
+	return model ? (clampThinkingLevel(model, preferred) as ThinkingLevel) : preferred;
+}
+
+function modelCapabilities(model: ModelListEntry): string {
+	const input = model.input.includes("image") ? "vision" : "text-only";
+	const thinking = getSupportedThinkingLevels(model as Model<Api>).join("/");
+	return `${input} · thinking: ${thinking}`;
+}
+
+/** Build one searchable list for agent model selection. Only models Pi
+ * currently reports as available are supplied by setup. */
+export function buildModelPickerItems(options: {
+	models: readonly ModelListEntry[];
+	configuredRef?: string;
+	mainRef?: string;
+}): ModelPickerItem[] {
+	const configuredRef = cleanModelRef(options.configuredRef);
+	const mainRef = cleanModelRef(options.mainRef);
+	const byRef = new Map<string, ModelListEntry>();
+	for (const model of options.models) {
+		const ref = modelRef(model);
+		if (!byRef.has(ref)) byRef.set(ref, model);
+	}
+
+	const refs = [...byRef.keys()]
+		.sort((left, right) => {
+			const leftRank = left === configuredRef ? 0 : left === mainRef ? 1 : 2;
+			const rightRank = right === configuredRef ? 0 : right === mainRef ? 1 : 2;
+			return leftRank - rightRank || left.localeCompare(right);
+		});
+
+	const dynamic: ModelPickerItem = {
+		value: CURRENT_MAIN_MODEL,
+		label: "Current main model (dynamic)",
+		description: "Clear agent override; use the current main model dynamically",
+	};
+	const items: ModelPickerItem[] = [dynamic];
+	for (const ref of refs) {
+		const model = byRef.get(ref)!;
+		const tags = [ref === configuredRef ? "configured" : "", ref === mainRef ? "current main" : ""]
+			.filter(Boolean);
+		const name = model.name.trim() && model.name !== model.id ? model.name.trim() : undefined;
+		items.push({
+			value: ref,
+			label: ref,
+			description: [name, modelCapabilities(model), ...tags].filter(Boolean).join(" · "),
+		});
+	}
+	return items;
+}
+
+/** The dynamic choice removes the persisted per-agent override. */
+export function applyAgentModelChoice(
+	current: Record<string, string>,
+	agentName: string,
+	choice: string,
+): Record<string, string> {
+	const next = { ...current };
+	if (choice === CURRENT_MAIN_MODEL) delete next[agentName];
+	else next[agentName] = choice.trim();
+	return next;
+}