@ferris1225/pi-subagents 0.4.0 → 0.5.0

package/src/prompt.ts

@@ -1,57 +1,58 @@
-/**
- * Builds the delegation directive injected into the parent model's system prompt
- * via the `before_agent_start` hook. This is the lever that makes the main model
- * actually USE the subagent tool proactively (pi never shows it the per-agent
- * descriptions otherwise).
- *
- * The directive is a self-contained replacement for the "Sub-agent Dispatch" and
- * "Review, Verification & Commit" sections users otherwise keep in a global
- * AGENTS.md — so installing this extension lets them delete those sections without
- * losing the behavior. (Other AGENTS.md sections — Behavior, Git & Security,
- * platform/language rules — are unrelated and stay put.)
- */
-
-import type { AgentConfig } from "./agents.ts";
-import { formatCatalogEntry } from "./agents.ts";
-
-/** Compact role routing hints, emitted only for roles that are enabled. */
-const ROLE_ROUTING: Record<string, string> = {
-	explore: "explore — broad/open-ended code search, \"where is X\", multi-file lookups (read-only, cheap).",
-	plan: "plan — a separate, human-reviewable implementation plan before any code (read-only).",
-	worker: "worker — implement/fix/refactor/test a well-scoped task (full tools; plans internally).",
-	reviewer: "reviewer — adversarial pre-commit review of a diff (read-only; independent context).",
-};
-
-export function buildDelegationDirective(agents: AgentConfig[]): string {
-	if (agents.length === 0) return "";
-
-	const catalog = agents.map(formatCatalogEntry).join("\n");
-	const routing = agents
-		.map((a) => ROLE_ROUTING[a.name])
-		.filter((line): line is string => Boolean(line))
-		.map((line) => `- ${line}`)
-		.join("\n");
-	const hasReviewer = agents.some((a) => a.name === "reviewer");
-	const hasMultiple = agents.length > 1;
-
-	return `
-## Sub-agent delegation (pi-subagents)
-
-You have a \`subagent\` tool that runs specialized agents in ISOLATED context windows.
-Delegate discrete, self-contained tasks to it instead of doing everything inline, so the
-main window stays focused on orchestration, synthesis, and verification.
-
-Available agents:
-${catalog}
-
-${routing ? `Routing:\n${routing}\n` : ""}Dispatch discipline:
-- Default to delegating every discrete task to a sub-agent; do the orchestration and verification yourself in the main window.
-- Only handle inline: pure Q&A, a single trivial edit/lookup, or when the user explicitly says to do it directly. When in doubt, delegate.
-- For an already-known or trivial target, use a direct search/read tool (e.g. grep/find/read) — do not over-delegate a one-line lookup.
-${hasMultiple ? "- Run INDEPENDENT tasks in parallel: one subagent call with a `tasks` array, and track them with your todo list. Keep dependent work sequential (e.g. explore, then worker, then reviewer).\n" : ""}- Brief each sub-agent as self-contained: goal, exact paths, constraints, expected output. It has NO memory of this conversation.
-- Trust but verify: a sub-agent's summary describes intent, not outcome. Check the actual changes/results before reporting work done.
-
-Review & verification:
-- Never report an unrun check as passed; report it as unavailable or as a pre-existing failure.
-${hasReviewer ? "- For non-trivial diffs, run one fresh read-only `reviewer` sub-agent before reporting done. Fix only concrete blockers and re-review at most once.\n- Use multi-model cross-review only when explicitly requested or for genuinely high-risk changes (security, unsafe/FFI, persistence-migration, concurrency). Reviewers are read-only; only the main agent edits.\n" : ""}- Commit or push only when explicitly requested, applicable checks pass, and no accepted blockers remain.`;
-}
+/**
+ * Builds the delegation directive injected into the parent model's system prompt
+ * via the `before_agent_start` hook. This is the lever that makes the main model
+ * actually USE the subagent tool proactively (pi never shows it the per-agent
+ * descriptions otherwise).
+ *
+ * The directive is a self-contained replacement for the "Sub-agent Dispatch" and
+ * "Review, Verification & Commit" sections users otherwise keep in a global
+ * AGENTS.md — so installing this extension lets them delete those sections without
+ * losing the behavior. (Other AGENTS.md sections — Behavior, Git & Security,
+ * platform/language rules — are unrelated and stay put.)
+ */
+
+import type { AgentConfig } from "./agents.ts";
+import { formatCatalogEntry } from "./agents.ts";
+
+/** Compact role routing hints, emitted only for roles that are enabled. */
+const ROLE_ROUTING: Record<string, string> = {
+	explore: "explore — broad/open-ended code search, \"where is X\", multi-file lookups (read-only, cheap).",
+	plan: "plan — a separate, human-reviewable implementation plan before any code (read-only).",
+	worker: "worker — implement/fix/refactor/test a well-scoped task (full tools; plans internally).",
+	reviewer: "reviewer — adversarial pre-commit review of a diff (read-only; independent context).",
+};
+
+export function buildDelegationDirective(agents: AgentConfig[]): string {
+	if (agents.length === 0) return "";
+
+	const catalog = agents.map(formatCatalogEntry).join("\n");
+	const routing = agents
+		.map((a) => ROLE_ROUTING[a.name])
+		.filter((line): line is string => Boolean(line))
+		.map((line) => `- ${line}`)
+		.join("\n");
+	const hasReviewer = agents.some((a) => a.name === "reviewer");
+	const hasMultiple = agents.length > 1;
+
+	return `
+## Sub-agent delegation (pi-subagents)
+
+You have a \`subagent\` tool that runs specialized agents in ISOLATED context windows.
+Delegate discrete, self-contained tasks to it instead of doing everything inline, so the
+main window stays focused on orchestration, synthesis, and verification.
+
+Available agents:
+${catalog}
+
+${routing ? `Routing:\n${routing}\n` : ""}Dispatch discipline:
+- Default to delegating every discrete task to a sub-agent; do the orchestration and verification yourself in the main window.
+- Only handle inline: pure Q&A, a single trivial edit/lookup, or when the user explicitly says to do it directly. When in doubt, delegate.
+- For an already-known or trivial target, use a direct search/read tool (e.g. grep/find/read) — do not over-delegate a one-line lookup.
+${hasMultiple ? "- Run INDEPENDENT tasks in parallel: one subagent call with a `tasks` array, and track them with your todo list. Keep dependent work sequential (e.g. explore, then worker, then reviewer).\n" : ""}- Brief each sub-agent as self-contained: goal, exact paths, constraints, expected output. It has NO memory of this conversation.
+- Treat delegated agents as leaf workers: do not ask a sub-agent to dispatch another sub-agent; child processes do not have this tool.
+- Trust but verify: a sub-agent's summary describes intent, not outcome. Check the actual changes/results before reporting work done.
+
+Review & verification:
+- Never report an unrun check as passed; report it as unavailable or as a pre-existing failure.
+${hasReviewer ? "- For non-trivial diffs, run one fresh read-only `reviewer` sub-agent before reporting done. Fix only concrete blockers and re-review at most once.\n- Use multi-model cross-review only when explicitly requested or for genuinely high-risk changes (security, unsafe/FFI, persistence-migration, concurrency). Reviewers are read-only; only the main agent edits.\n" : ""}- Commit or push only when explicitly requested, applicable checks pass, and no accepted blockers remain.`;
+}

package/src/setup.ts

@@ -1,222 +1,264 @@
-/**
- * Interactive configuration wizard for /subagents-setup.
- *
- * Everything is selection-driven (no free-text answers): a multi-select for which
- * agents to enable, a per-agent single-select for model overrides (fuzzy filter +
- * paging), and simple menus for the injection toggle and agent scope. Config is
- * written to <agentDir>/pi-subagents.json.
- */
-
-import { stat } from "node:fs/promises";
-import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
-import {
-	AGENT_SCOPE_VALUES,
-	BUILTIN_AGENT_NAMES,
-	DEFAULT_CONFIG,
-	DEFAULT_ENABLED_AGENTS,
-	type AgentScope,
-	type SubagentsConfig,
-	errorMessage,
-	getConfigPath,
-	loadConfig,
-	saveConfig,
-} from "./config.ts";
-import { promptSelectMany, promptSelectOne } from "./ui.ts";
-
-const INHERIT = "__inherit__";
-
-/** Short, selection-friendly descriptions for the built-in agents. */
-const MODULE_HINTS: Record<string, string> = {
-	explore: "read-only codebase recon (fast model)",
-	plan: "implementation plan before code (opt-in)",
-	worker: "implement / fix / refactor / test (full tools)",
-	reviewer: "adversarial pre-commit review (read-only)",
-};
-
-function moduleLabel(name: string): string {
-	const hint = MODULE_HINTS[name];
-	return hint ? `${name} — ${hint}` : name;
-}
-
-async function configExists(configPath: string): Promise<boolean> {
-	try {
-		await stat(configPath);
-		return true;
-	} catch {
-		return false;
-	}
-}
-
-/** Ordered "provider/model-id" references, with the active model first. */
-function availableModelRefs(ctx: ExtensionCommandContext): string[] {
-	const refs = new Set<string>();
-	if (ctx.model) refs.add(`${ctx.model.provider}/${ctx.model.id}`);
-	const models =
-		ctx.scopedModels.length > 0 ? ctx.scopedModels.map((entry) => entry.model) : ctx.modelRegistry.getAvailable();
-	for (const model of models) refs.add(`${model.provider}/${model.id}`);
-	return [...refs];
-}
-
-async function pickEnabledAgents(
-	ctx: ExtensionCommandContext,
-	current: readonly string[],
-): Promise<string[] | undefined> {
-	const items = BUILTIN_AGENT_NAMES.map((name) => ({ value: name, label: moduleLabel(name) }));
-	return promptSelectMany(
-		ctx,
-		"Enable which sub-agents?",
-		"Space toggles • Enter confirms • Esc cancels",
-		items,
-		current,
-	);
-}
-
-async function pickAgentModels(
-	ctx: ExtensionCommandContext,
-	enabledAgents: readonly string[],
-	current: Record<string, string>,
-): Promise<Record<string, string> | undefined> {
-	const refs = availableModelRefs(ctx);
-	if (refs.length === 0) {
-		ctx.ui.notify("No Pi models are currently available; model overrides left unchanged.", "warning");
-		return { ...current };
-	}
-
-	const result: Record<string, string> = {};
-	for (const name of enabledAgents) {
-		const currentRef = current[name];
-		const items = [
-			{
-				value: INHERIT,
-				label: currentRef
-					? `(use main session's model — drop override "${currentRef}")`
-					: "(use main session's current model — no override)",
-			},
-			...refs.map((ref) => ({ value: ref, label: ref === currentRef ? `${ref} (current)` : ref })),
-		];
-		const choice = await promptSelectOne(
-			ctx,
-			`Model for "${name}"`,
-			"Type to filter • ↑/↓ • PgUp/PgDn • Enter selects • Esc cancels setup",
-			items,
-		);
-		if (choice === undefined) return undefined; // Esc aborts the whole wizard
-		if (choice !== INHERIT) result[name] = choice;
-	}
-	return result;
-}
-
-async function pickInjection(ctx: ExtensionCommandContext, current: boolean): Promise<boolean | undefined> {
-	const on = "On — inject the delegation directive into the system prompt (recommended)";
-	const off = "Off — do not inject (rely on the tool description alone)";
-	const choice = await ctx.ui.select("Proactive dispatch injection?", [current ? `${on} (current)` : on, current ? off : `${off} (current)`]);
-	if (choice === undefined) return undefined;
-	return choice.startsWith("On");
-}
-
-async function pickScope(ctx: ExtensionCommandContext, current: AgentScope): Promise<AgentScope | undefined> {
-	const labels: Record<AgentScope, string> = {
-		user: "user — built-in + ~/.pi/agent/agents (default)",
-		project: "project — built-in + nearest .pi/agents only",
-		both: "both — user agents, overridden by project agents",
-	};
-	const options = AGENT_SCOPE_VALUES.map((scope) =>
-		scope === current ? `${labels[scope]} (current)` : labels[scope],
-	);
-	const choice = await ctx.ui.select("Which agent directories to discover from?", options);
-	if (choice === undefined) return undefined;
-	const scope = AGENT_SCOPE_VALUES.find((s) => choice.startsWith(s));
-	return scope;
-}
-
-/** Validate that every configured model override still resolves; drop stale ones. */
-function pruneStaleModels(ctx: ExtensionCommandContext, agentModels: Record<string, string>): Record<string, string> {
-	const clean: Record<string, string> = {};
-	for (const [name, ref] of Object.entries(agentModels)) {
-		const slash = ref.indexOf("/");
-		if (slash <= 0) continue;
-		const model = ctx.modelRegistry.find(ref.slice(0, slash), ref.slice(slash + 1));
-		if (model) clean[name] = ref;
-		else ctx.ui.notify(`Dropped stale model override for "${name}": ${ref}`, "warning");
-	}
-	return clean;
-}
-
-async function runFullSetup(ctx: ExtensionCommandContext, configPath: string, base: SubagentsConfig): Promise<void> {
-	const enabled = await pickEnabledAgents(ctx, base.enabledAgents);
-	if (enabled === undefined) return notifyCancelled(ctx);
-
-	const models = await pickAgentModels(ctx, enabled, base.agentModels);
-	if (models === undefined) return notifyCancelled(ctx);
-
-	const injection = await pickInjection(ctx, base.proactiveInjection);
-	if (injection === undefined) return notifyCancelled(ctx);
-
-	const scope = await pickScope(ctx, base.agentScope);
-	if (scope === undefined) return notifyCancelled(ctx);
-
-	const next: SubagentsConfig = {
-		enabledAgents: enabled,
-		agentModels: pruneStaleModels(ctx, models),
-		proactiveInjection: injection,
-		agentScope: scope,
-	};
-	await saveConfig(next, configPath);
-	ctx.ui.notify(`pi-subagents configured. Saved to ${configPath}`, "info");
-}
-
-async function runMenu(ctx: ExtensionCommandContext, configPath: string, config: SubagentsConfig): Promise<void> {
-	const choice = await ctx.ui.select("pi-subagents is already configured. What would you like to change?", [
-		"Enable/disable agents",
-		"Change agent models",
-		"Toggle proactive injection",
-		"Change agent scope",
-		"Full re-setup",
-	]);
-	if (choice === undefined) return notifyCancelled(ctx);
-
-	if (choice.startsWith("Full")) return runFullSetup(ctx, configPath, config);
-
-	let next: SubagentsConfig = { ...config, agentModels: { ...config.agentModels } };
-
-	if (choice.startsWith("Enable")) {
-		const enabled = await pickEnabledAgents(ctx, config.enabledAgents);
-		if (enabled === undefined) return notifyCancelled(ctx);
-		next.enabledAgents = enabled;
-	} else if (choice.startsWith("Change agent models")) {
-		const models = await pickAgentModels(ctx, config.enabledAgents, config.agentModels);
-		if (models === undefined) return notifyCancelled(ctx);
-		next.agentModels = pruneStaleModels(ctx, models);
-	} else if (choice.startsWith("Toggle")) {
-		const injection = await pickInjection(ctx, config.proactiveInjection);
-		if (injection === undefined) return notifyCancelled(ctx);
-		next.proactiveInjection = injection;
-	} else if (choice.startsWith("Change agent scope")) {
-		const scope = await pickScope(ctx, config.agentScope);
-		if (scope === undefined) return notifyCancelled(ctx);
-		next.agentScope = scope;
-	}
-
-	await saveConfig(next, configPath);
-	ctx.ui.notify(`pi-subagents updated. Saved to ${configPath}`, "info");
-}
-
-function notifyCancelled(ctx: ExtensionCommandContext): void {
-	ctx.ui.notify("pi-subagents setup cancelled.", "info");
-}
-
-/** Entry point for the /subagents-setup command. */
-export async function runSetup(ctx: ExtensionCommandContext, configPath: string = getConfigPath()): Promise<void> {
-	if (ctx.mode !== "tui") {
-		ctx.ui.notify("/subagents-setup requires Pi's interactive TUI.", "error");
-		return;
-	}
-	try {
-		const exists = await configExists(configPath);
-		const config = await loadConfig(configPath);
-		if (exists) await runMenu(ctx, configPath, config);
-		else await runFullSetup(ctx, configPath, { ...DEFAULT_CONFIG, enabledAgents: [...DEFAULT_ENABLED_AGENTS] });
-	} catch (error) {
-		ctx.ui.notify(`pi-subagents setup failed: ${errorMessage(error)}`, "error");
-	}
-}
+/**
+ * Interactive configuration wizard for /subagents-setup.
+ *
+ * Everything is selection-driven (no free-text answers): a multi-select for which
+ * agents to enable, a per-agent single-select for model overrides (fuzzy filter +
+ * paging), and simple menus for the injection toggle and agent scope. Config is
+ * written to <agentDir>/pi-subagents.json.
+ */
+
+import { stat } from "node:fs/promises";
+import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import {
+	AGENT_SCOPE_VALUES,
+	BUILTIN_AGENT_NAMES,
+	DEFAULT_CONFIG,
+	DEFAULT_ENABLED_AGENTS,
+	THINKING_LEVEL_VALUES,
+	type AgentScope,
+	type SubagentsConfig,
+	type ThinkingLevel,
+	errorMessage,
+	getConfigPath,
+	loadConfig,
+	saveConfig,
+} from "./config.ts";
+import { availableModelRefs, repairUnavailableModelOverrides } from "./models.ts";
+import { promptSelectMany, promptSelectOne } from "./ui.ts";
+
+const INHERIT = "__inherit__";
+
+/** Short, selection-friendly descriptions for the built-in agents. */
+const MODULE_HINTS: Record<string, string> = {
+	explore: "read-only codebase recon (fast model)",
+	plan: "implementation plan before code (opt-in)",
+	worker: "implement / fix / refactor / test (full tools)",
+	reviewer: "adversarial pre-commit review (read-only)",
+};
+
+function moduleLabel(name: string): string {
+	const hint = MODULE_HINTS[name];
+	return hint ? `${name} — ${hint}` : name;
+}
+
+async function configExists(configPath: string): Promise<boolean> {
+	try {
+		await stat(configPath);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+async function pickEnabledAgents(
+	ctx: ExtensionCommandContext,
+	current: readonly string[],
+): Promise<string[] | undefined> {
+	const items = BUILTIN_AGENT_NAMES.map((name) => ({ value: name, label: moduleLabel(name) }));
+	return promptSelectMany(
+		ctx,
+		"Enable which sub-agents?",
+		"Space toggles • Enter confirms • Esc cancels",
+		items,
+		current,
+	);
+}
+
+async function pickAgentModels(
+	ctx: ExtensionCommandContext,
+	enabledAgents: readonly string[],
+	current: Record<string, string>,
+): Promise<Record<string, string> | undefined> {
+	const refs = availableModelRefs(ctx);
+	if (refs.length === 0) {
+		ctx.ui.notify("No Pi models are currently available; model overrides left unchanged.", "warning");
+		return { ...current };
+	}
+
+	const result: Record<string, string> = {};
+	for (const name of enabledAgents) {
+		const currentRef = current[name];
+		const items = [
+			{
+				value: INHERIT,
+				label: currentRef
+					? `(use main session's model — drop override "${currentRef}")`
+					: "(use main session's current model — no override)",
+			},
+			...refs.map((ref) => ({ value: ref, label: ref === currentRef ? `${ref} (current)` : ref })),
+		];
+		const choice = await promptSelectOne(
+			ctx,
+			`Model for "${name}"`,
+			"Type to filter • ↑/↓ • PgUp/PgDn • Enter selects • Esc cancels setup",
+			items,
+		);
+		if (choice === undefined) return undefined; // Esc aborts the whole wizard
+		if (choice !== INHERIT) result[name] = choice;
+	}
+	return result;
+}
+
+const THINKING_LEVEL_HINTS: Record<ThinkingLevel, string> = {
+	off: "no reasoning tokens (fastest)",
+	minimal: "minimal reasoning",
+	low: "light reasoning",
+	medium: "balanced reasoning",
+	high: "deep reasoning",
+	xhigh: "extra-deep reasoning",
+	max: "strongest reasoning (default)",
+};
+
+async function pickThinkingLevel(
+	ctx: ExtensionCommandContext,
+	current: ThinkingLevel,
+): Promise<ThinkingLevel | undefined> {
+	const options = THINKING_LEVEL_VALUES.map((level) =>
+		level === current ? `${level} — ${THINKING_LEVEL_HINTS[level]} (current)` : `${level} — ${THINKING_LEVEL_HINTS[level]}`,
+	);
+	const choice = await ctx.ui.select("Sub-agent thinking strength?", options);
+	if (choice === undefined) return undefined;
+	return THINKING_LEVEL_VALUES.find((level) => choice.startsWith(`${level} —`));
+}
+
+async function pickInjection(ctx: ExtensionCommandContext, current: boolean): Promise<boolean | undefined> {
+	const on = "On — inject the delegation directive into the system prompt (recommended)";
+	const off = "Off — do not inject (rely on the tool description alone)";
+	const choice = await ctx.ui.select("Proactive dispatch injection?", [current ? `${on} (current)` : on, current ? off : `${off} (current)`]);
+	if (choice === undefined) return undefined;
+	return choice.startsWith("On");
+}
+
+async function pickScope(ctx: ExtensionCommandContext, current: AgentScope): Promise<AgentScope | undefined> {
+	const labels: Record<AgentScope, string> = {
+		user: "user — built-in + ~/.pi/agent/agents (default)",
+		project: "project — built-in + nearest .pi/agents only",
+		both: "both — user agents, overridden by project agents",
+	};
+	const options = AGENT_SCOPE_VALUES.map((scope) =>
+		scope === current ? `${labels[scope]} (current)` : labels[scope],
+	);
+	const choice = await ctx.ui.select("Which agent directories to discover from?", options);
+	if (choice === undefined) return undefined;
+	const scope = AGENT_SCOPE_VALUES.find((s) => choice.startsWith(s));
+	return scope;
+}
+
+/** Replace unavailable overrides with a model usable by the current main window. */
+function repairStaleModels(ctx: ExtensionCommandContext, agentModels: Record<string, string>): Record<string, string> {
+	const repair = repairUnavailableModelOverrides(ctx, agentModels);
+	if (repair.changed) {
+		const detail = repair.fallbackRef
+			? `Switched ${repair.replaced} unavailable model override(s) to ${repair.fallbackRef}.`
+			: `Removed ${repair.removed} unavailable model override(s); no model is currently available.`;
+		ctx.ui.notify(detail, "warning");
+	}
+	return repair.agentModels;
+}
+
+async function repairConfigModels(
+	ctx: ExtensionCommandContext,
+	configPath: string,
+	config: SubagentsConfig,
+): Promise<SubagentsConfig> {
+	const repairedModels = repairUnavailableModelOverrides(ctx, config.agentModels);
+	if (!repairedModels.changed) return config;
+
+	const repaired = { ...config, agentModels: repairedModels.agentModels };
+	try {
+		await saveConfig(repaired, configPath);
+		ctx.ui.notify(`Repaired unavailable model overrides in ${configPath}.`, "warning");
+	} catch (error) {
+		ctx.ui.notify(`Could not persist repaired model overrides: ${errorMessage(error)}`, "warning");
+	}
+	return repaired;
+}
+
+async function runFullSetup(ctx: ExtensionCommandContext, configPath: string, base: SubagentsConfig): Promise<void> {
+	const enabled = await pickEnabledAgents(ctx, base.enabledAgents);
+	if (enabled === undefined) return notifyCancelled(ctx);
+
+	const models = await pickAgentModels(ctx, enabled, base.agentModels);
+	if (models === undefined) return notifyCancelled(ctx);
+
+	const thinkingLevel = await pickThinkingLevel(ctx, base.thinkingLevel);
+	if (thinkingLevel === undefined) return notifyCancelled(ctx);
+
+	const injection = await pickInjection(ctx, base.proactiveInjection);
+	if (injection === undefined) return notifyCancelled(ctx);
+
+	const scope = await pickScope(ctx, base.agentScope);
+	if (scope === undefined) return notifyCancelled(ctx);
+
+	const next: SubagentsConfig = {
+		enabledAgents: enabled,
+		agentModels: repairStaleModels(ctx, models),
+		thinkingLevel,
+		proactiveInjection: injection,
+		agentScope: scope,
+	};
+	await saveConfig(next, configPath);
+	ctx.ui.notify(`pi-subagents configured. Saved to ${configPath}`, "info");
+}
+
+async function runMenu(ctx: ExtensionCommandContext, configPath: string, config: SubagentsConfig): Promise<void> {
+	const choice = await ctx.ui.select("pi-subagents is already configured. What would you like to change?", [
+		"Enable/disable agents",
+		"Change agent models",
+		"Change thinking strength",
+		"Toggle proactive injection",
+		"Change agent scope",
+		"Full re-setup",
+	]);
+	if (choice === undefined) return notifyCancelled(ctx);
+
+	if (choice.startsWith("Full")) return runFullSetup(ctx, configPath, config);
+
+	let next: SubagentsConfig = { ...config, agentModels: { ...config.agentModels } };
+
+	if (choice.startsWith("Enable")) {
+		const enabled = await pickEnabledAgents(ctx, config.enabledAgents);
+		if (enabled === undefined) return notifyCancelled(ctx);
+		next.enabledAgents = enabled;
+	} else if (choice.startsWith("Change agent models")) {
+		const models = await pickAgentModels(ctx, config.enabledAgents, config.agentModels);
+		if (models === undefined) return notifyCancelled(ctx);
+		next.agentModels = repairStaleModels(ctx, models);
+	} else if (choice.startsWith("Change thinking")) {
+		const thinkingLevel = await pickThinkingLevel(ctx, config.thinkingLevel);
+		if (thinkingLevel === undefined) return notifyCancelled(ctx);
+		next.thinkingLevel = thinkingLevel;
+	} else if (choice.startsWith("Toggle")) {
+		const injection = await pickInjection(ctx, config.proactiveInjection);
+		if (injection === undefined) return notifyCancelled(ctx);
+		next.proactiveInjection = injection;
+	} else if (choice.startsWith("Change agent scope")) {
+		const scope = await pickScope(ctx, config.agentScope);
+		if (scope === undefined) return notifyCancelled(ctx);
+		next.agentScope = scope;
+	}
+
+	await saveConfig(next, configPath);
+	ctx.ui.notify(`pi-subagents updated. Saved to ${configPath}`, "info");
+}
+
+function notifyCancelled(ctx: ExtensionCommandContext): void {
+	ctx.ui.notify("pi-subagents setup cancelled.", "info");
+}
+
+/** Entry point for the /subagents-setup command. */
+export async function runSetup(ctx: ExtensionCommandContext, configPath: string = getConfigPath()): Promise<void> {
+	if (ctx.mode !== "tui") {
+		ctx.ui.notify("/subagents-setup requires Pi's interactive TUI.", "error");
+		return;
+	}
+	try {
+		const exists = await configExists(configPath);
+		const loaded = await loadConfig(configPath);
+		const config = await repairConfigModels(ctx, configPath, loaded);
+		if (exists) await runMenu(ctx, configPath, config);
+		else await runFullSetup(ctx, configPath, { ...DEFAULT_CONFIG, enabledAgents: [...DEFAULT_ENABLED_AGENTS] });
+	} catch (error) {
+		ctx.ui.notify(`pi-subagents setup failed: ${errorMessage(error)}`, "error");
+	}
+}