pi-bro 0.13.1 → 0.14.0

package/bro.ts

@@ -9,14 +9,15 @@ import { homedir, tmpdir } from "node:os";
 import { extname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { createInterface } from "node:readline";
 import { stripVTControlCharacters } from "node:util";
-import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
-import { copyToClipboard, getMarkdownTheme } from "@earendil-works/pi-coding-agent";
-import { Input, Markdown, matchesKey, truncateToWidth, visibleWidth, type Focusable } from "@earendil-works/pi-tui";
+import type { ExtensionAPI, ExtensionCommandContext, ExtensionContext, SessionEntry } from "@earendil-works/pi-coding-agent";
+import { Container, Editor, Input, Markdown, SettingsList, SelectList, Text, matchesKey, truncateToWidth, visibleWidth, type Component, type EditorTheme, type Focusable, type SelectItem, type SettingItem, type TUI } from "@earendil-works/pi-tui";
+import { convertToLlm, copyToClipboard, getMarkdownTheme, getSelectListTheme, getSettingsListTheme } from "@earendil-works/pi-coding-agent";
 import { Defuddle } from "defuddle/node";
 import { parseHTML } from "linkedom";
 import mammoth from "mammoth";
+import { Type } from "typebox";
 import { extractText } from "unpdf";
-import { BRO_MODES, DEFAULT_BRO_MODE, buildBtwPrompt, buildDefaultPrompt, buildShowPrompt, parseBroMode, type BroMode } from "./prompt.ts";
+import { BRO_MODES, DEFAULT_BRO_MODE, buildAdvisorPrompt, buildBtwPrompt, buildDefaultPrompt, buildShowPrompt, parseBroMode, type BroMode } from "./prompt.ts";
 
 const AGENT_DIR = process.env.PI_CODING_AGENT_DIR ?? join(homedir(), ".pi", "agent");
 const ENV_MODEL = process.env.PI_BRO_MODEL?.trim();
@@ -52,7 +53,20 @@ type BtwThread = { turns: BtwTurn[]; conversationId?: string; full: boolean };
 const EFFORTS = ["default", "low", "medium", "high"] as const;
 type BroEffort = (typeof EFFORTS)[number];
 type AgyEffort = Exclude<BroEffort, "default">;
-type BroSettings = { model: string; effort: BroEffort; mode: BroMode; showTurns: number };
+// "advisor" is a real capability (command, Agy invocation, Doctor check) like the other three;
+// see docs/plans/2026-09-19-bro-advisor-design.md. All four share one model/effort resolution,
+// override, and Doctor-check path via this single list -- there is no configuration-only tier.
+const CAPABILITIES = ["explain", "show", "btw", "advisor"] as const;
+type Capability = (typeof CAPABILITIES)[number];
+const CAPABILITY_LABELS: Record<Capability, string> = { explain: "Explain", show: "Show", btw: "Btw", advisor: "Advisor" };
+type ModelEffortPair = { model: string; effort: BroEffort };
+type BroSettings = {
+	model: string;
+	effort: BroEffort;
+	mode: BroMode;
+	showTurns: number;
+	overrides: Partial<Record<Capability, ModelEffortPair>>;
+};
 type AgyModelFamily = {
 	id: string;
 	label: string;
@@ -91,12 +105,15 @@ const COMMANDS = [
 	{ value: "show", label: "show", description: "Draw what happened in recent session turns as shapes" },
 	{ value: "mode", label: "mode", description: "Choose brief, balanced, or faithful explanations" },
 	{ value: "btw", label: "btw", description: "Open a side conversation (sandboxed by default; --full edits files)" },
+	{ value: "config", label: "config", description: "Configure shared defaults and per-capability model/effort overrides" },
+	{ value: "advisor", label: "advisor", description: "Check whether the executor's advisor tool is available right now" },
+	{ value: "advisor-steer", label: "advisor-steer", description: "View, edit, save, or clear the advisor's persistent steering brief" },
 	{ value: "help", label: "help", description: "Learn what Bro does and what it can access" },
 ];
 const KNOWN_ACTIONS = new Set(COMMANDS.map((command) => command.value));
 
 function isRecord(value: unknown): value is Record<string, unknown> {
-	return typeof value === "object" && value !== null;
+	return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 
 function errorMessage(error: unknown): string {
@@ -477,6 +494,24 @@ export function agyFailureMessage(
 	return `Agy could not ${action}. Make sure Agy is installed and signed in, then run \`/bro doctor\`.`;
 }
 
+function parseModelEffortPair(value: unknown, context: string): ModelEffortPair {
+	if (!isRecord(value) || typeof value.model !== "string" || !value.model.trim() || !EFFORTS.some((effort) => effort === value.effort)) {
+		throw new Error(`${context} must contain a model and effort set to "default", "low", "medium", or "high".`);
+	}
+	return { model: value.model.trim(), effort: value.effort as BroEffort };
+}
+
+function parseOverrides(value: unknown): Partial<Record<Capability, ModelEffortPair>> {
+	if (value === undefined) return {};
+	if (!isRecord(value)) throw new Error("Settings overrides must be an object.");
+	const overrides: Partial<Record<Capability, ModelEffortPair>> = {};
+	for (const capability of CAPABILITIES) {
+		if (value[capability] === undefined) continue;
+		overrides[capability] = parseModelEffortPair(value[capability], `Settings overrides.${capability}`);
+	}
+	return overrides;
+}
+
 export function parseBroSettings(value: unknown): BroSettings {
 	if (
 		!isRecord(value) ||
@@ -492,7 +527,87 @@ export function parseBroSettings(value: unknown): BroSettings {
 	if (typeof showTurns !== "number" || !Number.isInteger(showTurns) || showTurns < 1) {
 		throw new Error("Settings showTurns must be a positive whole number of turns.");
 	}
-	return { model: value.model.trim(), effort: value.effort as BroSettings["effort"], mode, showTurns };
+	const overrides = parseOverrides(value.overrides);
+	return { model: value.model.trim(), effort: value.effort as BroSettings["effort"], mode, showTurns, overrides };
+}
+
+function capabilityOverride(settings: BroSettings, capability: Capability): ModelEffortPair | undefined {
+	return settings.overrides[capability];
+}
+
+function capabilityPair(settings: BroSettings, capability: Capability): ModelEffortPair {
+	return capabilityOverride(settings, capability) ?? { model: settings.model, effort: settings.effort };
+}
+
+// An override always pins both model and effort together (never just one), so a capability's
+// setting is either fully inherited or fully its own — no partial-inheritance edge cases.
+//
+// An override is cleared ONLY by an explicit "Default" selection (pair === undefined), never
+// automatically because it happens to match the shared default: a user who deliberately pins a
+// capability to the model that currently IS the shared default must keep that pin — unchanged —
+// if the shared default is later changed to something else. Silently dropping an override that
+// merely coincides with the default would make that pin impossible to express.
+export function withCapabilityOverride(
+	settings: BroSettings,
+	capability: Capability,
+	pair: ModelEffortPair | undefined,
+): BroSettings {
+	const overrides = { ...settings.overrides };
+	if (!pair) delete overrides[capability];
+	else overrides[capability] = pair;
+	return { ...settings, overrides };
+}
+
+export function resolveModelEffort(
+	pair: ModelEffortPair,
+	families: AgyModelFamily[],
+): { pair: ModelEffortPair; family?: AgyModelFamily } {
+	const family = families.find((item) => item.id === pair.model || item.variants.some((variant) => variant.id === pair.model));
+	if (!family) return { pair };
+	const variant = family.variants.find((item) => item.id === pair.model);
+	return {
+		family,
+		pair: { model: family.id, effort: pair.effort === "default" && variant?.effort ? variant.effort : pair.effort },
+	};
+}
+
+function resolveCapabilitySettings(
+	settings: BroSettings,
+	capability: Capability,
+	families: AgyModelFamily[],
+): { pair: ModelEffortPair; family?: AgyModelFamily } {
+	return resolveModelEffort(capabilityPair(settings, capability), families);
+}
+
+// The steering brief is stored as a session `custom` entry — extension state that never
+// participates in LLM context (see docs/plans/2026-09-19-bro-advisor-design.md). Writes go
+// through pi.appendEntry(); ctx.sessionManager is read-only and has no append methods.
+//
+// bro_advisor has no on/off activation state: it is registered once at extension load like any
+// other tool and never gated via pi.setActiveTools(). Whether the executor can call it is purely a
+// function of this host's own tool restrictions (pi.getAllTools() / pi.getActiveTools()), which
+// this code only ever reads, never overrides. A session may still carry historical
+// "bro-advisor-active" entries from before this simplification; they are silently ignored.
+const ADVISOR_STEERING_ENTRY = "bro-advisor-steering";
+export const ADVISOR_TOOL_NAME = "bro_advisor";
+// setStatus() key for mirroring live advisor progress to the footer/status bar -- see the execute()
+// handler below for why this fallback surface exists alongside onUpdate's tool-card renderResult.
+const ADVISOR_STATUS_BAR_KEY = "bro-advisor";
+const ADVISOR_COMPATIBILITY = "Pi >=0.84.2; Agy >=1.1.15";
+
+export type AdvisorState = { steering: string };
+
+// getBranch() walks root-to-leaf (see latestAssistant above for the same convention), so a forward
+// scan taking the last match of ADVISOR_STEERING_ENTRY resolves "latest wins". Forking clones the
+// branch's entries into a new session file, so this same resolution gives fork inheritance and
+// independent post-fork edits for free, with no special-case fork logic.
+export function resolveAdvisorState(branch: readonly SessionEntry[]): AdvisorState {
+	let steering = "";
+	for (const entry of branch) {
+		if (entry.type !== "custom" || entry.customType !== ADVISOR_STEERING_ENTRY) continue;
+		if (isRecord(entry.data) && typeof entry.data.text === "string") steering = entry.data.text;
+	}
+	return { steering };
 }
 
 async function ensureSettingsFile(): Promise<void> {
@@ -519,9 +634,18 @@ async function readSettings(): Promise<BroSettings> {
 	}
 }
 
+// Exported so persistence stays testable without touching the filesystem. This only ever omits
+// the `overrides` key itself when there are no overrides at all — it does NOT deduplicate or drop
+// any individual override that happens to match the shared default; see withCapabilityOverride
+// for why an explicit override is always kept until the user clears it back to "Default".
+export function settingsPayload(settings: BroSettings): Record<string, unknown> {
+	const { overrides, ...rest } = settings;
+	return Object.keys(overrides).length ? { ...rest, overrides } : rest;
+}
+
 async function writeSettings(settings: BroSettings): Promise<void> {
 	// ponytail: last writer wins across concurrent Pi processes; add locking only if that becomes a common workflow.
-	await writeFile(SETTINGS_FILE, `${JSON.stringify(settings, null, 2)}\n`, "utf8");
+	await writeFile(SETTINGS_FILE, `${JSON.stringify(settingsPayload(settings), null, 2)}\n`, "utf8");
 }
 
 export function formatAgyUsage(value: unknown): string {
@@ -604,35 +728,36 @@ async function checkAgyVersion(pi: ExtensionAPI, signal: AbortSignal): Promise<s
 	}
 }
 
+export function advisorAgyCompatible(version: string): boolean | undefined {
+	const match = /(?:^|\D)(\d+)\.(\d+)\.(\d+)(?:\D|$)/.exec(version);
+	if (!match) return undefined;
+	const installed = match.slice(1, 4).map(Number);
+	const minimum = [1, 1, 15];
+	for (let index = 0; index < minimum.length; index++) {
+		if (installed[index]! !== minimum[index]!) return installed[index]! > minimum[index]!;
+	}
+	return true;
+}
+
 function resolveCatalogSettings(
 	settings: BroSettings,
 	families: AgyModelFamily[],
 ): { settings: BroSettings; family?: AgyModelFamily } {
-	const family = families.find(
-		(item) => item.id === settings.model || item.variants.some((variant) => variant.id === settings.model),
-	);
-	if (!family) return { settings };
-	const variant = family.variants.find((item) => item.id === settings.model);
-	return {
-		family,
-		settings: {
-			...settings,
-			model: family.id,
-			effort: settings.effort === "default" && variant?.effort ? variant.effort : settings.effort,
-		},
-	};
+	const resolved = resolveModelEffort({ model: settings.model, effort: settings.effort }, families);
+	if (!resolved.family) return { settings };
+	return { family: resolved.family, settings: { ...settings, ...resolved.pair } };
 }
 
 function preferredEffort(family: AgyModelFamily): BroEffort {
 	return family.efforts.includes("low") ? "low" : (family.efforts[0] ?? "default");
 }
 
-export function agySelection(settings: BroSettings): { model: string; effort?: AgyEffort } {
-	if (settings.effort === "default") return { model: settings.model };
-	const suffix = (["low", "medium", "high"] as const).find((effort) => settings.model.endsWith(`-${effort}`));
+export function agySelection(pair: ModelEffortPair): { model: string; effort?: AgyEffort } {
+	if (pair.effort === "default") return { model: pair.model };
+	const suffix = (["low", "medium", "high"] as const).find((effort) => pair.model.endsWith(`-${effort}`));
 	return {
-		model: suffix ? settings.model.slice(0, -suffix.length - 1) : settings.model,
-		effort: settings.effort,
+		model: suffix ? pair.model.slice(0, -suffix.length - 1) : pair.model,
+		effort: pair.effort,
 	};
 }
 
@@ -656,11 +781,12 @@ async function checkAgyUsage(pi: ExtensionAPI, signal: AbortSignal): Promise<str
 	}
 }
 
-async function doctorReport(pi: ExtensionAPI, signal: AbortSignal): Promise<string> {
+async function doctorReport(pi: ExtensionAPI, ctx: ExtensionCommandContext, signal: AbortSignal): Promise<string> {
 	const lines: string[] = [];
 	let failed = false;
 	let settings: BroSettings | undefined;
 	let models: AgyModelFamily[] | undefined;
+	let agyVersion: string | undefined;
 	const pass = (name: string, detail: string) => lines.push(`- ✓ **${name}:** ${detail}`);
 	const fail = (name: string, error: unknown) => {
 		failed = true;
@@ -683,7 +809,8 @@ async function doctorReport(pi: ExtensionAPI, signal: AbortSignal): Promise<stri
 
 	let agyStarted = false;
 	try {
-		pass("Agy", await checkAgyVersion(pi, signal));
+		agyVersion = await checkAgyVersion(pi, signal);
+		pass("Agy", agyVersion);
 		agyStarted = true;
 	} catch (error) {
 		if (signal.aborted) throw error;
@@ -723,8 +850,42 @@ async function doctorReport(pi: ExtensionAPI, signal: AbortSignal): Promise<stri
 				fail("Reasoning effort", `\`${effort}\` is unsupported. Run \`/bro effort\` to choose another.`);
 			}
 		}
+
+		for (const capability of CAPABILITIES) {
+			const label = CAPABILITY_LABELS[capability];
+			const override = capabilityOverride(settings, capability);
+			const resolved = resolveCapabilitySettings(settings, capability, models);
+			if (!resolved.family) {
+				fail(label, `\`${resolved.pair.model}\` is unavailable. Run \`/bro config\` to fix this override.`);
+				continue;
+			}
+			const effortOk = !resolved.family.efforts.length
+				? resolved.pair.effort === "default"
+				: resolved.pair.effort !== "default" && resolved.family.efforts.includes(resolved.pair.effort);
+			if (!effortOk) {
+				fail(label, `\`${resolved.pair.effort}\` is unsupported for \`${resolved.family.id}\`. Run \`/bro config\` to fix this.`);
+				continue;
+			}
+			pass(
+				label,
+				override
+					? `override \`${resolved.family.id}\`${resolved.pair.effort === "default" ? "" : ` (${resolved.pair.effort})`}`
+					: "using the shared default",
+			);
+		}
 	}
 
+	// bro_advisor has no on/off preference to compare against -- it is only ever gated by this
+	// host's own tool restrictions, which this reads via pi.getAllTools()/pi.getActiveTools() and
+	// never overrides. Exposed-but-inactive is the one genuine anomaly worth failing on.
+	const advisorExposed = pi.getAllTools().some((tool) => tool.name === ADVISOR_TOOL_NAME);
+	const advisorActive = pi.getActiveTools().includes(ADVISOR_TOOL_NAME);
+	if (advisorExposed && !advisorActive) fail("Advisor tool", "bro_advisor is exposed but not active in this session. Run /reload.");
+	else pass("Advisor tool", advisorExposed ? "bro_advisor is exposed and active" : "bro_advisor is not exposed by this host (tool restriction, or the extension has not finished loading)");
+	pass("Advisor steering", resolveAdvisorState(ctx.sessionManager.getBranch()).steering.trim() ? "present" : "none");
+	if (agyVersion && advisorAgyCompatible(agyVersion)) pass("Advisor compatibility", ADVISOR_COMPATIBILITY);
+	else if (agyVersion) fail("Advisor compatibility", `installed \`${agyVersion}\`; requires Agy >=1.1.15. Run \`agy update\`.`);
+
 	return `# Bro doctor\n\n${lines.join("\n")}\n\n**${failed ? "Bro needs attention." : "Bro is ready."}**\n\n${
 		failed ? "Fix the failed items, then press **R** to check again." : "No assistant response was sent and no model turn was run."
 	}`;
@@ -946,7 +1107,7 @@ async function simplify(
 	settings: BroSettings,
 	onProgress?: (text: string) => void,
 ): Promise<string> {
-	return runAgyText((await promptFor(response, settings.mode)).text, agySelection(settings), signal, onProgress);
+	return runAgyText((await promptFor(response, settings.mode)).text, agySelection(capabilityPair(settings, "explain")), signal, onProgress);
 }
 
 async function runShowExplanation(
@@ -956,7 +1117,7 @@ async function runShowExplanation(
 	settings: BroSettings,
 	onProgress?: (text: string) => void,
 ): Promise<string> {
-	return runAgyText(buildShowPrompt(transcript, steering), agySelection(settings), signal, onProgress);
+	return runAgyText(buildShowPrompt(transcript, steering), agySelection(capabilityPair(settings, "show")), signal, onProgress);
 }
 
 async function runAgyText(
@@ -1067,9 +1228,917 @@ async function runAgyText(
 	}
 }
 
-function helpText(settings?: BroSettings, settingsError?: string): string {
+// Harness-neutral advisor context snapshot: plain role/text/tool-name+args/tool-result-text, not
+// Pi's internal message objects serialized as-is, so the shape isn't a Pi-specific contract. Every
+// piece of free-text message content is JSON-quoted (the same "quote the source as data" convention
+// SOURCE_GUARD/buildShowPrompt/buildBtwPrompt already use in prompt.ts) rather than pasted in raw
+// after a bare "## role" heading: unquoted text under a heading would let pasted text or tool output
+// forge a fake "## user"/"## assistant" section that looks like a real turn boundary. See
+// docs/plans/2026-09-19-bro-advisor-design.md, "Context snapshot".
+type AdvisorMessageLike = { role?: unknown; content?: unknown; toolName?: unknown; toolCallId?: unknown; isError?: unknown };
+
+// Parameter element type of Pi's own AgentMessage → LLM converter (core/messages.ts), reused below
+// instead of redeclaring BashExecutionMessage's shape (it isn't exported from the package root).
+type AdvisorAgentMessage = Parameters<typeof convertToLlm>[0][number];
+
+function advisorQuoted(text: string): string {
+	return JSON.stringify(text);
+}
+
+// `resolvedToolCallIds` lets a still-pending bro_advisor call (the one currently in flight for this
+// very consultation, which by definition has no result yet) be dropped instead of rendered as an
+// orphaned, unresolved call — a past, completed bro_advisor call is unaffected and renders normally.
+function advisorContentText(content: unknown, resolvedToolCallIds: ReadonlySet<string>): string {
+	if (typeof content === "string") {
+		const text = content.trim();
+		return text ? advisorQuoted(text) : "";
+	}
+	if (!Array.isArray(content)) return "";
+	const parts: string[] = [];
+	for (const part of content) {
+		if (!part || typeof part !== "object") continue;
+		const type = (part as { type?: string }).type;
+		if (type === "text" && typeof (part as { text?: unknown }).text === "string") {
+			const text = (part as { text: string }).text.trim();
+			if (text) parts.push(advisorQuoted(text));
+		} else if (type === "image") {
+			parts.push("[image omitted]");
+		} else if (type === "thinking") {
+			parts.push("[reasoning omitted]");
+		} else if (type === "toolCall") {
+			const call = part as { id?: unknown; name?: unknown; arguments?: unknown };
+			const id = typeof call.id === "string" ? call.id : undefined;
+			const name = typeof call.name === "string" ? call.name : "(unknown)";
+			if (name === ADVISOR_TOOL_NAME && (!id || !resolvedToolCallIds.has(id))) continue;
+			parts.push(`[tool call${id ? ` #${id}` : ""}] ${name}(${JSON.stringify(call.arguments ?? {})})`);
+		}
+	}
+	return parts.join("\n").trim();
+}
+
+function renderAdvisorMessage(message: AdvisorMessageLike, resolvedToolCallIds: ReadonlySet<string>): string {
+	if (message.role === "user") {
+		const text = advisorContentText(message.content, resolvedToolCallIds);
+		return text ? `## user\n${text}` : "";
+	}
+	if (message.role === "assistant") {
+		const text = advisorContentText(message.content, resolvedToolCallIds);
+		return text ? `## assistant\n${text}` : "";
+	}
+	if (message.role === "toolResult") {
+		const name = typeof message.toolName === "string" ? message.toolName : "(unknown)";
+		const id = typeof message.toolCallId === "string" ? message.toolCallId : undefined;
+		const header = `## tool result${id ? ` [#${id}]` : ""}: ${name}${message.isError ? " · error" : ""}`;
+		const text = advisorContentText(message.content, resolvedToolCallIds);
+		return text ? `${header}\n${text}` : header;
+	}
+	if (message.role === "bashExecution") {
+		// Reuse Pi's own AgentMessage -> LLM conversion instead of hand-rolling one: it already
+		// drops a command run with the `!!` prefix (excludeFromContext) and formats the rest exactly
+		// as Pi's own context builder would, so a `!`-run command an executor can see is not silently
+		// missing from what the advisor sees.
+		const [converted] = convertToLlm([message as AdvisorAgentMessage]);
+		if (!converted) return "";
+		const text = advisorContentText(converted.content, resolvedToolCallIds);
+		return text ? `## bash execution\n${text}` : "";
+	}
+	return "";
+}
+
+export function buildAdvisorSnapshot(ctx: ExtensionContext, pi: ExtensionAPI): { text: string; hadCompaction: boolean } {
+	const systemPrompt = ctx.getSystemPrompt().trim();
+
+	const activeToolNames = new Set(pi.getActiveTools().filter((name) => name !== ADVISOR_TOOL_NAME));
+	const tools = pi.getAllTools().filter((tool) => activeToolNames.has(tool.name)).sort((a, b) => a.name.localeCompare(b.name));
+	// No truncation of tool descriptions: Bro imposes no size cap on the snapshot (see the design
+	// doc) and an arbitrary slice would silently drop part of a tool's actual behavior contract.
+	const toolsSection = tools.length
+		? tools.map((tool) => `- ${tool.name}: ${tool.description.replace(/\s+/g, " ").trim()}`).join("\n")
+		: "(none)";
+
+	const entries = ctx.sessionManager.buildContextEntries();
+	const resolvedToolCallIds = new Set<string>();
+	for (const entry of entries) {
+		if (entry.type !== "message") continue;
+		const message = entry.message as AdvisorMessageLike;
+		if (message.role === "toolResult" && typeof message.toolCallId === "string") resolvedToolCallIds.add(message.toolCallId);
+	}
+
+	const lines: string[] = [];
+	// Tracked from the actual entry type, not a substring search over the rendered snapshot text --
+	// free-text content (a file the executor read, a pasted paragraph) is JSON-quoted but not
+	// stripped of "#", so a substring check could be forged by source data that happens to contain
+	// the literal heading text. Only a real `compaction` entry may set this.
+	let hadCompaction = false;
+	for (const entry of entries) {
+		if (entry.type === "message") {
+			const rendered = renderAdvisorMessage(entry.message as AdvisorMessageLike, resolvedToolCallIds);
+			if (rendered) lines.push(rendered);
+		} else if (entry.type === "compaction") {
+			// buildContextEntries() already includes every real entry after the compaction point;
+			// the summary is all there is to represent for what it replaced.
+			hadCompaction = true;
+			lines.push(`## compacted earlier context\n${advisorQuoted(entry.summary)}`);
+		} else if (entry.type === "branch_summary") {
+			lines.push(`## abandoned branch summary\n${advisorQuoted(entry.summary)}`);
+		} else if (entry.type === "custom_message") {
+			const text = advisorContentText(entry.content, resolvedToolCallIds);
+			if (text) lines.push(`## extension message: ${entry.customType}\n${text}`);
+		}
+		// "custom" entries (including our own advisor activation/steering state) are intentionally
+		// skipped — they never participate in LLM context and must not leak into the snapshot either.
+	}
+	const conversationSection = lines.length ? lines.join("\n\n") : "(no conversation content captured)";
+
+	const text = `## Executor's system instructions\n\n${systemPrompt ? advisorQuoted(systemPrompt) : "(none)"}\n\n## Executor's active tools\n\n${toolsSection}\n\n## Conversation so far (message text is quoted as JSON strings; includes tool calls and results, correlated by call id; image and reasoning content is noted but omitted; the still-pending advisor call for this very consultation is omitted)\n\n${conversationSection}`;
+	return { text, hadCompaction };
+}
+
+// Advisor stdin/stream-json transport, confirmed against pi-flow-external's tested agy backend
+// (src/core/agy.ts, test/agy-backend.test.ts): --input-format stream-json reads one NDJSON
+// "user" message from stdin instead of a --print argv value (unbounded snapshot size would
+// otherwise risk ARG_MAX), and --dangerously-skip-permissions gives the advisor real, unprompted
+// tool access. See docs/plans/2026-09-19-bro-advisor-design.md, "Transport".
+type AdvisorAgyEvent = {
+	event?: string;
+	step_update?: { tool_name?: unknown; step_type?: unknown; text_delta?: unknown };
+	result?: { status?: unknown; response?: unknown; error?: unknown };
+};
+
+// Guards only against a single runaway line with no newline (a protocol break, not a real
+// response size) — agy's real NDJSON lines are far smaller than this.
+const ADVISOR_MAX_STDOUT_LINE_CHARS = 2_000_000;
+
+function parseAdvisorLine(line: string): AdvisorAgyEvent {
+	try {
+		return JSON.parse(line) as AdvisorAgyEvent;
+	} catch {
+		throw new Error("Agy emitted invalid stream-json output.");
+	}
+}
+
+// Only a tool_name or a user-facing agent_response/assistant text_delta becomes an activity label
+// -- hidden reasoning/thinking step_types and any other shape stay unreported, never leaked into
+// progress.
+function advisorActivityFromEvent(event: AdvisorAgyEvent): string | undefined {
+	if (event.event !== "step_update" || !event.step_update || typeof event.step_update !== "object") return undefined;
+	const update = event.step_update;
+	if (typeof update.tool_name === "string" && update.tool_name.trim()) return update.tool_name.trim();
+	const isUserFacingText = update.step_type === "agent_response" || update.step_type === "assistant";
+	if (isUserFacingText && typeof update.text_delta === "string" && update.text_delta.trim()) {
+		return update.text_delta.split("\n").find((line) => line.trim())?.trim();
+	}
+	return undefined;
+}
+
+const MAX_ADVISOR_ACTIVITY_LINES = 4;
+const ADVISOR_ACTIVITY_PREVIEW_CHARS = 100;
+
+function advisorActivityPreview(label: string): string {
+	return label.length > ADVISOR_ACTIVITY_PREVIEW_CHARS ? `${label.slice(0, ADVISOR_ACTIVITY_PREVIEW_CHARS).trimEnd()}…` : label;
+}
+
+// Older agy CLIs reject --input-format with Go's flag-package usage dump and exit before running
+// the agent at all (no terminal result event). Turn that into an actionable version hint instead
+// of a bare "no terminal result" error.
+export function advisorFlagErrorHint(stderr: string): string | undefined {
+	const match = /flags? provided but not defined: -([a-z0-9-]+)/i.exec(stderr);
+	if (!match) return undefined;
+	return `flag provided but not defined: -${match[1]} (installed Agy CLI is too old; the advisor needs Agy 1.1.15+ for --input-format stream-json — run \`agy update\`, then \`/bro doctor\`)`;
+}
+
+export type AdvisorActivityCallback = (label: string, timestamp: number) => void;
+
+export async function runAdvisorConsultation(
+	prompt: string,
+	selection: ReturnType<typeof agySelection>,
+	cwd: string,
+	signal: AbortSignal,
+	killEscalationMs = 5_000,
+	onActivity?: AdvisorActivityCallback,
+): Promise<string> {
+	const child = spawn(
+		"agy",
+		[
+			"--dangerously-skip-permissions",
+			"--disable-slash-commands",
+			"--output-format", "stream-json",
+			"--input-format", "stream-json",
+			"--model", selection.model,
+			...(selection.effort ? ["--effort", selection.effort] : []),
+			"--print-timeout", "10m",
+		],
+		// detached: true (POSIX only) makes the child its own process-group leader, so a signal to
+		// -child.pid below reaches it AND every grandchild it spawned -- not just the immediate
+		// process. Without this, killing only the immediate child can leave a grandchild holding the
+		// inherited stdio pipes open, and the "close" event this function waits on never fires until
+		// that orphan exits on its own.
+		{ cwd, timeout: 610_000, stdio: ["pipe", "pipe", "pipe"], windowsHide: true, detached: process.platform !== "win32" },
+	);
+
+	let processError: Error | undefined;
+	let stderr = "";
+	let final: string | undefined;
+	let terminalError: string | undefined;
+	let protocolError: string | undefined;
+	let sawTerminal = false;
+	let stdoutBuffer = "";
+
+	// Signal the whole process group when possible so a misbehaving grandchild dies too, not just
+	// the immediate agy process; child.kill() alone only ever reaches the immediate child.
+	const killAdvisorChild = (signalName: NodeJS.Signals) => {
+		if (process.platform !== "win32" && typeof child.pid === "number") {
+			try {
+				process.kill(-child.pid, signalName);
+				return;
+			} catch {
+				// Group may already be gone (e.g. the child already exited) -- fall through.
+			}
+		}
+		child.kill(signalName);
+	};
+
+	// Relying on spawn({signal}) alone only ever sends one SIGTERM and gives up if the child (or a
+	// misbehaving grandchild it spawned) ignores it, hanging this promise forever. Escalate to
+	// SIGKILL -- which cannot be ignored -- if the child hasn't exited shortly after.
+	let killEscalationTimer: ReturnType<typeof setTimeout> | undefined;
+	const onAbort = () => {
+		killAdvisorChild("SIGTERM");
+		killEscalationTimer = setTimeout(() => {
+			killAdvisorChild("SIGKILL");
+		}, killEscalationMs);
+	};
+	signal.addEventListener("abort", onAbort, { once: true });
+	if (signal.aborted) onAbort();
+
+	child.stderr.setEncoding("utf8");
+	child.stderr.on("data", (chunk: string) => {
+		stderr += chunk;
+	});
+	child.once("error", (error) => {
+		processError = error;
+	});
+	child.stdin.on("error", () => {
+		// agy exiting before it reads stdin is reported through the close/error path below.
+	});
+	child.stdin.end(`${JSON.stringify({ event: "user", message: { content: prompt } })}\n`);
+
+	const handleLine = (line: string) => {
+		if (!line.trim() || sawTerminal) return;
+		const event = parseAdvisorLine(line);
+		const activity = advisorActivityFromEvent(event);
+		if (activity) onActivity?.(activity, Date.now());
+		if (event.event !== "result") return;
+		sawTerminal = true;
+		const result = event.result;
+		const status = typeof result?.status === "string" ? result.status.trim().toUpperCase() : undefined;
+		if (status === "SUCCESS" && typeof result?.response === "string") {
+			final = result.response;
+		} else {
+			const detail = typeof result?.error === "string" && result.error.trim() ? `: ${result.error.trim()}` : "";
+			terminalError = `Agy failed with status ${status ?? "(missing)"}${detail}`;
+		}
+	};
+
+	child.stdout.setEncoding("utf8");
+	child.stdout.on("data", (chunk: string) => {
+		stdoutBuffer += chunk;
+		const parts = stdoutBuffer.split(/\r?\n/);
+		stdoutBuffer = parts.pop() ?? "";
+		if (stdoutBuffer.length > ADVISOR_MAX_STDOUT_LINE_CHARS || parts.some((line) => line.length > ADVISOR_MAX_STDOUT_LINE_CHARS)) {
+			protocolError ??= `Agy emitted a stdout line over ${ADVISOR_MAX_STDOUT_LINE_CHARS} characters; the stream is unparseable.`;
+			stdoutBuffer = "";
+			killAdvisorChild("SIGTERM");
+			return;
+		}
+		for (const line of parts) {
+			try {
+				handleLine(line);
+			} catch (error) {
+				protocolError ??= errorMessage(error);
+				killAdvisorChild("SIGTERM");
+				return;
+			}
+		}
+	});
+
+	const { code, exitSignal } = await new Promise<{ code: number | null; exitSignal: NodeJS.Signals | null }>((resolve) => {
+		child.once("close", (code, exitSignal) => {
+			if (stdoutBuffer.trim() && !sawTerminal) {
+				try {
+					handleLine(stdoutBuffer);
+				} catch (error) {
+					protocolError ??= errorMessage(error);
+				}
+			}
+			resolve({ code, exitSignal });
+		});
+	});
+	signal.removeEventListener("abort", onAbort);
+	if (killEscalationTimer) clearTimeout(killEscalationTimer);
+
+	if (signal.aborted) throw new Error("Canceled.");
+	if (protocolError) throw new Error(withDoctor(protocolError));
+	if (processError) {
+		const missing = (processError as NodeJS.ErrnoException).code === "ENOENT";
+		throw new Error(
+			missing
+				? "Agy could not start. Make sure Agy is installed and on PATH, then run `/bro doctor`."
+				: `Agy could not start: ${processError.message}\n\nRun \`/bro doctor\` for setup help.`,
+		);
+	}
+	if (exitSignal || code === null) {
+		throw new Error("Agy timed out during the advisor consultation. Run `/bro doctor` for setup help.");
+	}
+	if (!sawTerminal) {
+		const hint = advisorFlagErrorHint(stderr);
+		throw new Error(withDoctor(hint ?? (stderr.trim() ? `Agy exited without a terminal result event: ${stderr.trim()}` : "Agy exited without a terminal result event.")));
+	}
+	if (terminalError) throw new Error(withDoctor(terminalError));
+	if (code !== 0) throw new Error(agyFailureMessage("complete the advisor consultation", { code, killed: false, stderr }));
+
+	const text = final?.trim();
+	if (!text) throw new Error(withDoctor(stderr.trim() || "Agy returned no advice."));
+	return text;
+}
+
+function advisorDelay(ms: number, signal: AbortSignal, onTick?: (remainingMs: number) => void): Promise<void> {
+	return new Promise((resolve, reject) => {
+		if (signal.aborted) {
+			reject(new Error("Canceled."));
+			return;
+		}
+		const startedAt = Date.now();
+		const interval = onTick ? setInterval(() => onTick(Math.max(0, ms - (Date.now() - startedAt))), 1_000) : undefined;
+		interval?.unref();
+		const cleanup = () => {
+			clearTimeout(timer);
+			if (interval) clearInterval(interval);
+			signal.removeEventListener("abort", onAbort);
+		};
+		const onAbort = () => {
+			cleanup();
+			reject(new Error("Canceled."));
+		};
+		const timer = setTimeout(() => {
+			cleanup();
+			resolve();
+		}, ms);
+		signal.addEventListener("abort", onAbort, { once: true });
+	});
+}
+
+export type AdvisorConsult = (
+	prompt: string,
+	selection: ReturnType<typeof agySelection>,
+	cwd: string,
+	signal: AbortSignal,
+	killEscalationMs?: number,
+	onActivity?: AdvisorActivityCallback,
+) => Promise<string>;
+export type AdvisorDelayFn = (ms: number, signal: AbortSignal, onTick?: (remainingMs: number) => void) => Promise<void>;
+export type AdvisorToolDetails = {
+	status: "investigating" | "retrying" | "done";
+	attempt: number;
+	of: number;
+	elapsedMs: number;
+	error?: string;
+	retryInMs?: number;
+	model?: string;
+	effort?: string;
+	durationMs?: number;
+	cwd?: string;
+	steeringIncluded?: boolean;
+	snapshotChars?: number;
+	broTruncated?: false;
+	omissions?: string;
+	// Real Agy-reported activity for the current attempt only -- reset to empty whenever a new
+	// attempt (including a retry) starts, never carried over from a prior failed attempt.
+	activity?: string[];
+	lastActivityAt?: number;
+	// Total count of accepted activity events (tool calls AND user-facing text deltas -- "activity"
+	// is the honest label, not "tool calls") observed across the whole consultation, including every
+	// retry attempt. Unlike `activity` above, this never resets on a retry; the final "done" details
+	// carry the same running total.
+	activityCount?: number;
+};
+export type AdvisorProgressCallback = (details: AdvisorToolDetails) => void;
+export type AdvisorRunResult = { advice: string; attempts: number; durationMs: number; activityCount: number };
+
+// Bursts of chunked NDJSON activity events are coalesced to this cadence so a fast stream of tool
+// calls/text deltas doesn't flood onProgress; the 1s elapsed-time heartbeat below is unaffected and
+// keeps ticking independently.
+const ADVISOR_ACTIVITY_THROTTLE_MS = 250;
+
+// `consult`/`delayFn` are injectable so tests can swap in a fake agy spawn and a fake clock
+// instead of spawning real processes and waiting 15 real seconds. Every attempt sends the
+// identical prompt/selection/cwd to a fresh, standalone Agy process — never resumed via
+// --conversation, even across retries.
+export async function runAdvisorWithRetries(
+	prompt: string,
+	selection: ReturnType<typeof agySelection>,
+	cwd: string,
+	signal: AbortSignal,
+	consult: AdvisorConsult = runAdvisorConsultation,
+	delayFn: AdvisorDelayFn = advisorDelay,
+	onProgress?: AdvisorProgressCallback,
+	progressIntervalMs = 1_000,
+	activityThrottleMs = ADVISOR_ACTIVITY_THROTTLE_MS,
+): Promise<AdvisorRunResult> {
+	const delays = [5_000, 10_000];
+	const totalAttempts = delays.length + 1;
+	const startedAt = Date.now();
+	let lastError: unknown;
+	// Cumulative across every attempt in this consultation, including retries -- unlike `activity`
+	// below, a retry must never reset this back to zero.
+	let totalActivityCount = 0;
+	for (let attempt = 0; attempt <= delays.length; attempt++) {
+		if (signal.aborted) throw new Error("Canceled.");
+		// Fresh per attempt: a retry must never show the previous attempt's activity trail.
+		const activity: string[] = [];
+		let lastActivityAt: number | undefined;
+		let lastActivityEmitAt = 0;
+		let pendingActivityTimer: ReturnType<typeof setTimeout> | undefined;
+
+		const running = (): AdvisorToolDetails => ({
+			status: "investigating",
+			attempt: attempt + 1,
+			of: totalAttempts,
+			elapsedMs: Date.now() - startedAt,
+			activity: [...activity],
+			lastActivityAt,
+			activityCount: totalActivityCount,
+		});
+		const emitRunning = () => onProgress?.(running());
+		emitRunning();
+		const progressTimer = onProgress ? setInterval(emitRunning, progressIntervalMs) : undefined;
+		progressTimer?.unref();
+
+		const stopActivityThrottle = () => {
+			if (pendingActivityTimer) {
+				clearTimeout(pendingActivityTimer);
+				pendingActivityTimer = undefined;
+			}
+		};
+		const onActivity: AdvisorActivityCallback = (label, timestamp) => {
+			const normalized = label.replace(/\s+/g, " ").trim();
+			if (!normalized) return;
+			activity.push(normalized);
+			if (activity.length > MAX_ADVISOR_ACTIVITY_LINES) activity.splice(0, activity.length - MAX_ADVISOR_ACTIVITY_LINES);
+			totalActivityCount += 1;
+			lastActivityAt = timestamp;
+			if (!onProgress) return;
+			const elapsed = Date.now() - lastActivityEmitAt;
+			if (elapsed >= activityThrottleMs) {
+				lastActivityEmitAt = Date.now();
+				emitRunning();
+				return;
+			}
+			if (!pendingActivityTimer) {
+				pendingActivityTimer = setTimeout(() => {
+					pendingActivityTimer = undefined;
+					lastActivityEmitAt = Date.now();
+					emitRunning();
+				}, activityThrottleMs - elapsed);
+				pendingActivityTimer.unref?.();
+			}
+		};
+
+		try {
+			const advice = await consult(prompt, selection, cwd, signal, undefined, onActivity);
+			// `totalActivityCount` is read directly here rather than from the last onProgress snapshot,
+			// which may lag behind by up to `activityThrottleMs` -- the final count must be exact.
+			return { advice, attempts: attempt + 1, durationMs: Date.now() - startedAt, activityCount: totalActivityCount };
+		} catch (error) {
+			if (progressTimer) clearInterval(progressTimer);
+			stopActivityThrottle();
+			if (signal.aborted || errorMessage(error) === "Canceled.") throw error;
+			lastError = error;
+			if (attempt === delays.length) break;
+			const delay = delays[attempt]!;
+			const retrying = (remainingMs: number): AdvisorToolDetails => ({
+				status: "retrying",
+				attempt: attempt + 2,
+				of: totalAttempts,
+				elapsedMs: Date.now() - startedAt,
+				error: errorMessage(error),
+				retryInMs: remainingMs,
+				activityCount: totalActivityCount,
+			});
+			onProgress?.(retrying(delay));
+			await delayFn(delay, signal, (remainingMs) => onProgress?.(retrying(remainingMs)));
+		} finally {
+			if (progressTimer) clearInterval(progressTimer);
+			stopActivityThrottle();
+		}
+	}
+	throw lastError;
+}
+
+export function advisorAttemptLabel(details: AdvisorToolDetails): string {
+	if (details.status === "retrying") {
+		return `Bro advisor · retrying in ${Math.ceil((details.retryInMs ?? 0) / 1_000)}s · attempt ${details.attempt}/${details.of}${details.error ? ` — ${details.error}` : ""}`;
+	}
+	if (details.status === "done") {
+		return `Bro advisor · ${details.model ?? "unknown model"} · ${details.attempt} attempt${details.attempt === 1 ? "" : "s"} · ${Math.ceil((details.durationMs ?? details.elapsedMs) / 1_000)}s`;
+	}
+	const latest = details.activity?.at(-1);
+	// "last reported" + freshness, never a claim about what Agy is doing right now and never
+	// "stalled" -- silence since lastActivityAt is not itself evidence of a stuck run.
+	const activityLabel = latest
+		? `last reported: ${advisorActivityPreview(latest)} (${Math.max(0, Math.floor((Date.now() - (details.lastActivityAt ?? Date.now())) / 1_000))}s ago)`
+		: "awaiting first activity from Agy";
+	return `Bro advisor · running · ${Math.floor(details.elapsedMs / 1_000)}s · attempt ${details.attempt}/${details.of} · ${activityLabel}`;
+}
+
+const SHOW_TURNS_PRESETS = [1, 2, 3, 5, 8];
+
+function showTurnsValues(current: number): string[] {
+	return [...new Set([...SHOW_TURNS_PRESETS, current])].sort((a, b) => a - b).map(String);
+}
+
+// A resolved pair's display string: distinguishes a model that is genuinely fixed-effort from
+// one that simply isn't in the current catalog (both used to render as "fixed", which read as
+// falsely healthy for an unavailable model), and flags a stored effort that isn't one of the
+// resolved family's supported efforts instead of silently showing it as if it were valid.
+function effortDisplay(resolved: { pair: ModelEffortPair; family?: AgyModelFamily }): string {
+	if (!resolved.family) return "unavailable";
+	const fixed = !resolved.family.efforts.length;
+	const valid = fixed ? resolved.pair.effort === "default" : resolved.family.efforts.includes(resolved.pair.effort as AgyEffort);
+	if (!valid) return `${resolved.pair.effort} (unsupported)`;
+	return fixed ? "fixed" : resolved.pair.effort;
+}
+
+// Testable core: takes settings/catalog/persist as plain arguments so smoke tests can drive
+// the exact interaction (submenus, cancel, cycling, save failure) without a real Agy process
+// or settings file. showBroConfigModal below wires this to the real ctx/pi/filesystem.
+export function createConfigModal(
+	initialSettings: BroSettings,
+	families: AgyModelFamily[],
+	persistSettings: (settings: BroSettings) => Promise<void>,
+): (tui: TuiLike, theme: Theme, keybindings: unknown, done: (value?: void) => void) => Component & { dispose?(): void } {
+	return (tui, theme, _keybindings, done) => {
+		let settings = initialSettings;
+		// The last settings actually confirmed on disk. A failed save reverts `settings` (and the
+		// whole displayed row set) back to this, so the screen never shows state that doesn't exist.
+		let savedSettings = initialSettings;
+		// Only one persistSettings call is ever in flight. A change that arrives while one is
+		// already running is coalesced into `queued` (overwriting any earlier queued change) rather
+		// than firing a second concurrent write — this is what keeps writes serialized and makes
+		// sure the on-disk file always converges on the latest intent instead of a stale one that
+		// happened to finish last.
+		let saving = false;
+		let queued: BroSettings | undefined;
+		// Esc while a save is in flight must not close past an unshown result: it requests a close
+		// that only actually happens once the in-flight (and any coalesced) save has settled, and
+		// only if it succeeded — a failure cancels the pending close so its notice stays visible.
+		let closeRequested = false;
+
+		const findFamily = (modelId: string) =>
+			families.find((item) => item.id === modelId || item.variants.some((variant) => variant.id === modelId));
+
+		const modelPicker = (current: string, pickerDone: (value?: string) => void, capability?: Capability) => {
+			const defaultResolved = resolveModelEffort({ model: settings.model, effort: settings.effort }, families);
+			const options: SelectItem[] = [
+				...(capability ? [{ value: "__default__", label: `Default (${defaultResolved.family?.label ?? settings.model})` }] : []),
+				...families.map((family) => ({
+					value: family.id,
+					label: `${family.label}${family.efforts.length ? "" : " · fixed effort"}`,
+				})),
+			];
+			const picker = new SelectList(options, Math.min(options.length, 8), getSelectListTheme());
+			const selectedIndex = capability && current === "Default" ? 0 : options.findIndex((option) => option.value === current);
+			picker.setSelectedIndex(Math.max(0, selectedIndex));
+			picker.onSelect = (item) => pickerDone(item.value);
+			picker.onCancel = () => pickerDone();
+			return picker;
+		};
+
+		const modelItem: SettingItem = { id: "model", label: "Default model", currentValue: settings.model, submenu: modelPicker };
+		const effortItem: SettingItem = { id: "effort", label: "Default effort", currentValue: "" };
+		const modeItem: SettingItem = { id: "mode", label: "Explain mode", currentValue: settings.mode, values: [...BRO_MODES] };
+		const showTurnsItem: SettingItem = {
+			id: "showTurns",
+			label: "Show turns",
+			currentValue: String(settings.showTurns),
+			values: showTurnsValues(settings.showTurns),
+		};
+		const capabilityItems = Object.fromEntries(
+			CAPABILITIES.map((capability) => [
+				capability,
+				{
+					model: {
+						id: `${capability}Model`,
+						label: `${CAPABILITY_LABELS[capability]} model`,
+						currentValue: "Default",
+						submenu: (current: string, pickerDone: (value?: string) => void) => modelPicker(current, pickerDone, capability),
+					} as SettingItem,
+					effort: {
+						id: `${capability}Effort`,
+						label: `${CAPABILITY_LABELS[capability]} effort`,
+						currentValue: "",
+					} as SettingItem,
+				},
+			]),
+		) as Record<Capability, { model: SettingItem; effort: SettingItem }>;
+
+		function refresh(): void {
+			const def = resolveModelEffort({ model: settings.model, effort: settings.effort }, families);
+			modelItem.currentValue = def.family?.id ?? settings.model;
+			effortItem.currentValue = effortDisplay(def);
+			effortItem.values = def.family?.efforts.length ? [...def.family.efforts] : undefined;
+			modeItem.currentValue = settings.mode;
+			showTurnsItem.currentValue = String(settings.showTurns);
+			showTurnsItem.values = showTurnsValues(settings.showTurns);
+
+			for (const capability of CAPABILITIES) {
+				const override = capabilityOverride(settings, capability);
+				const resolved = resolveModelEffort(capabilityPair(settings, capability), families);
+				const rows = capabilityItems[capability];
+				rows.model.currentValue = override ? (resolved.family?.id ?? override.model) : "Default";
+				rows.effort.currentValue = effortDisplay(resolved);
+				rows.effort.values = resolved.family?.efforts.length ? [...resolved.family.efforts] : undefined;
+			}
+		}
+		refresh();
+
+		const items: SettingItem[] = [
+			modelItem,
+			effortItem,
+			modeItem,
+			showTurnsItem,
+			...CAPABILITIES.flatMap((capability) => [capabilityItems[capability].model, capabilityItems[capability].effort]),
+		];
+
+		const noticeText = new Text("");
+
+		function runSave(toSave: BroSettings): void {
+			saving = true;
+			void persistSettings(toSave)
+				.then(() => {
+					savedSettings = toSave;
+					noticeText.setText("");
+				})
+				.catch((error: unknown) => {
+					// Restore the last state that is actually on disk: showing the failed, unsaved
+					// value would let the screen claim a setting that doesn't really exist.
+					settings = savedSettings;
+					queued = undefined;
+					closeRequested = false;
+					refresh();
+					noticeText.setText(theme.fg("warning", `Could not save settings: ${errorMessage(error)}. Reverted to the last saved settings.`));
+				})
+				.finally(() => {
+					saving = false;
+					tui.requestRender();
+					if (queued !== undefined) {
+						const next = queued;
+						queued = undefined;
+						runSave(next);
+					} else if (closeRequested) {
+						closeRequested = false;
+						done(undefined);
+					}
+				});
+		}
+
+		function persist(toSave: BroSettings): void {
+			if (saving) {
+				queued = toSave;
+				return;
+			}
+			runSave(toSave);
+		}
+
+		const onChange = (id: string, newValue: string) => {
+			if (id === "model") {
+				const family = findFamily(newValue);
+				if (!family) return;
+				const keepCurrent = settings.effort === "default" ? !family.efforts.length : family.efforts.includes(settings.effort as AgyEffort);
+				settings = { ...settings, model: family.id, effort: keepCurrent ? settings.effort : preferredEffort(family) };
+			} else if (id === "effort") {
+				// Effort-only edit: pin the resolved family's canonical id, same reasoning as the
+				// capability-override effort-only edit below -- otherwise a shared default created
+				// from a suffixed variant id (e.g. "gemini-x-low") would end up paired with an
+				// unrelated effort instead of its actual family id.
+				const resolved = resolveModelEffort({ model: settings.model, effort: settings.effort }, families);
+				settings = { ...settings, model: resolved.family?.id ?? settings.model, effort: newValue as BroEffort };
+			} else if (id === "mode") {
+				const mode = parseBroMode(newValue);
+				if (!mode) return;
+				settings = { ...settings, mode };
+			} else if (id === "showTurns") {
+				const turns = Number(newValue);
+				if (!Number.isInteger(turns) || turns < 1) return;
+				settings = { ...settings, showTurns: turns };
+			} else {
+				const capability = CAPABILITIES.find((item) => id === `${item}Model` || id === `${item}Effort`);
+				if (!capability) return;
+				if (id === `${capability}Model`) {
+					if (newValue === "__default__") {
+						settings = withCapabilityOverride(settings, capability, undefined);
+					} else {
+						const family = findFamily(newValue);
+						if (!family) return;
+						const currentEffort = capabilityPair(settings, capability).effort;
+						const keepCurrent = currentEffort === "default" ? !family.efforts.length : family.efforts.includes(currentEffort as AgyEffort);
+						settings = withCapabilityOverride(settings, capability, {
+							model: family.id,
+							effort: keepCurrent ? currentEffort : preferredEffort(family),
+						});
+					}
+				} else {
+					// Effort-only edit: pin the resolved family's canonical id, never whatever raw
+					// string happens to sit in settings.model/override.model (which — for a shared
+					// default created from a suffixed variant id such as "gemini-x-low" with
+					// effort "default" — is not the family id). Storing the raw string here would
+					// pair a mismatched model/effort (e.g. a "-low"-suffixed id with effort "high").
+					const resolved = resolveModelEffort(capabilityPair(settings, capability), families);
+					const existing = capabilityOverride(settings, capability);
+					const model = resolved.family?.id ?? existing?.model ?? settings.model;
+					settings = withCapabilityOverride(settings, capability, { model, effort: newValue as BroEffort });
+				}
+			}
+			refresh();
+			tui.requestRender();
+			persist(settings);
+		};
+
+		const requestClose = () => {
+			if (saving) {
+				closeRequested = true;
+				return;
+			}
+			done(undefined);
+		};
+
+		const settingsList = new SettingsList(items, Math.min(items.length + 2, 18), getSettingsListTheme(), onChange, requestClose);
+		const container = new Container();
+		container.addChild(new Text(theme.fg("accent", theme.bold("Bro · config"))));
+		container.addChild(new Text(theme.fg("dim", "Shared defaults, with optional overrides per capability")));
+		container.addChild(settingsList);
+		container.addChild(noticeText);
+		container.addChild(new Text(theme.fg("dim", "↑/↓ navigate · Enter select/change · Esc back/close")));
+
+		return {
+			render: (w: number) => {
+				const inner = Math.max(1, w - 4);
+				const border = (left: string, right: string) => theme.fg("border", left + "─".repeat(inner + 2) + right);
+				return [border("┌", "┐"), ...container.render(inner).map(line => {
+					const text = truncateToWidth(line, inner, "");
+					return theme.fg("border", "│") + " " + text + " ".repeat(Math.max(0, inner - visibleWidth(text))) + " " + theme.fg("border", "│");
+				}), border("└", "┘")];
+			},
+			invalidate: () => container.invalidate(),
+			handleInput: (data: string) => {
+				settingsList.handleInput?.(data);
+				tui.requestRender();
+			},
+		};
+	};
+}
+
+export async function showBroConfigModal(ctx: ExtensionCommandContext, pi: ExtensionAPI): Promise<void> {
+	if (ctx.mode !== "tui") {
+		ctx.ui.notify("Use /bro config in Pi's interactive UI.", "warning");
+		return;
+	}
+	let settings: BroSettings;
+	let families: AgyModelFamily[];
+	try {
+		settings = await readSettings();
+		families = await listAgyModels(pi);
+	} catch (error) {
+		ctx.ui.notify(withDoctor(error), "error");
+		return;
+	}
+	await ctx.ui.custom<void>(createConfigModal(settings, families, writeSettings), {
+		overlay: true,
+		overlayOptions: {
+			width: "78%",
+			minWidth: 48,
+			maxHeight: "78%",
+			anchor: "top-center",
+			margin: { top: 1, left: 2, right: 2 },
+		},
+	});
+}
+
+// Testable core for /bro advisor-steer: persistence only happens on Ctrl+S/Ctrl+K.
+// Esc leaves the stored brief untouched; only the in-memory draft is discarded.
+export function createAdvisorSteerModal(
+	initialText: string,
+	onSave: (text: string) => void,
+	onClear: () => void,
+	copy: (text: string) => Promise<void> = copyToClipboard,
+): (tui: TUI, theme: Theme, keybindings: unknown, done: (value?: void) => void) => Component & { dispose?(): void } {
+	return (tui, theme, _keybindings, done) => {
+		const editorTheme: EditorTheme = { borderColor: (s: string) => theme.fg("border", s), selectList: getSelectListTheme() };
+		const editor = new Editor(tui, editorTheme);
+		editor.focused = true;
+		editor.setText(initialText);
+		let disposed = false;
+		const notice = new Text("");
+		const showNotice = (message: string, color: "success" | "error") => {
+			if (disposed) return;
+			notice.setText(theme.fg(color, message));
+			tui.requestRender();
+		};
+		editor.onChange = () => notice.setText("");
+
+		const container = new Container();
+		container.addChild(new Text(theme.fg("accent", theme.bold("Bro · advisor steer"))));
+		container.addChild(new Text(theme.fg("dim", "One persistent steering brief the advisor always sees — never sent to the main model.")));
+		container.addChild(editor);
+		container.addChild(notice);
+		container.addChild(new Text(theme.fg("dim", "Ctrl+S save · Enter newline · Ctrl+K clear · Ctrl+C copy · Esc close")));
+
+		return {
+			render: (w: number) => {
+				const inner = Math.max(1, w - 4);
+				const border = (left: string, right: string) => theme.fg("border", left + "─".repeat(inner + 2) + right);
+				return [border("┌", "┐"), ...container.render(inner).map((line) => {
+					const text = truncateToWidth(line, inner, "");
+					return theme.fg("border", "│") + " " + text + " ".repeat(Math.max(0, inner - visibleWidth(text))) + " " + theme.fg("border", "│");
+				}), border("└", "┘")];
+			},
+			invalidate: () => container.invalidate(),
+			handleInput: (data: string) => {
+				if (matchesKey(data, "escape")) {
+					disposed = true;
+					done(undefined);
+					return;
+				}
+				if (matchesKey(data, "ctrl+s")) {
+					try {
+						onSave(editor.getExpandedText());
+						showNotice("Saved", "success");
+					} catch (error) {
+						showNotice(`Save failed: ${errorMessage(error)}`, "error");
+					}
+					return;
+				}
+				if (matchesKey(data, "ctrl+k")) {
+					try {
+						onClear();
+						editor.setText("");
+						showNotice("Cleared", "success");
+					} catch (error) {
+						showNotice(`Clear failed: ${errorMessage(error)}`, "error");
+					}
+					return;
+				}
+				if (matchesKey(data, "ctrl+c")) {
+					const text = editor.getExpandedText();
+					void Promise.resolve()
+						.then(() => copy(text))
+						.then(() => showNotice("Copied", "success"))
+						.catch((error) => showNotice(`Copy failed: ${errorMessage(error)}`, "error"));
+					return;
+				}
+				if (matchesKey(data, "enter")) {
+					editor.insertTextAtCursor("\n");
+					tui.requestRender();
+					return;
+				}
+				editor.handleInput(data);
+				tui.requestRender();
+			},
+			dispose: () => { disposed = true; },
+		};
+	};
+}
+
+export async function showAdvisorSteerModal(ctx: ExtensionCommandContext, pi: ExtensionAPI): Promise<void> {
+	if (ctx.mode !== "tui") {
+		ctx.ui.notify("Use /bro advisor-steer in Pi's interactive UI.", "warning");
+		return;
+	}
+	const { steering } = resolveAdvisorState(ctx.sessionManager.getBranch());
+	await ctx.ui.custom<void>(
+		createAdvisorSteerModal(
+			steering,
+			(text) => pi.appendEntry(ADVISOR_STEERING_ENTRY, { text }),
+			() => pi.appendEntry(ADVISOR_STEERING_ENTRY, { text: "" }),
+		),
+		{
+			overlay: true,
+			overlayOptions: { width: "78%", minWidth: 48, maxHeight: "60%", anchor: "top-center", margin: { top: 1, left: 2, right: 2 } },
+		},
+	);
+}
+
+export function helpText(settings?: BroSettings, settingsError?: string): string {
+	const overrideLines = settings
+		? CAPABILITIES.map((capability) => {
+				const override = capabilityOverride(settings, capability);
+				return override
+					? `- **${CAPABILITY_LABELS[capability]} override:** \`${override.model}\`${override.effort === "default" ? "" : ` (${override.effort})`}`
+					: undefined;
+			}).filter((line): line is string => line !== undefined)
+		: [];
 	const settingsSummary = settings
-		? `- **Model:** \`${settings.model}\`\n- **Reasoning effort:** ${settings.effort === "default" ? "built into the selected model" : settings.effort}\n- **Mode:** ${settings.mode}\n- **Show turns:** ${settings.showTurns}`
+		? `- **Model:** \`${settings.model}\`\n- **Reasoning effort:** ${settings.effort === "default" ? "built into the selected model" : settings.effort}\n- **Mode:** ${settings.mode}\n- **Show turns:** ${settings.showTurns}${overrideLines.length ? `\n${overrideLines.join("\n")}` : ""}`
 		: `Bro could not read its settings: ${settingsError}\n\nRun \`/bro doctor\` for setup help.`;
 	return `# Bro
 
@@ -1092,14 +2161,26 @@ Press **R** to simplify the captured source again. Run a new \`/bro text\`, \`/b
 
 - \`/bro doctor\` — check settings, Agy, account, model, effort, and mode
 - \`/bro usage [--provider agy]\` — show current Agy limits
-- \`/bro model [id]\` — view or choose the Agy model
-- \`/bro effort [low|medium|high]\` — view or choose reasoning effort
+- \`/bro model [id]\` — view or choose the shared default Agy model
+- \`/bro effort [low|medium|high]\` — view or choose the shared default reasoning effort
 - \`/bro mode [brief|balanced|faithful]\` — view or choose explanation mode
+- \`/bro config\` — open an interactive settings screen for the shared default model/effort, explain mode, show turns, and per-capability (explain/show/btw/advisor) model and effort overrides. Changes save immediately; Esc on a picker cancels without changing anything, Esc on the screen closes it and keeps whatever was already saved.
+
+\`/bro model\` and \`/bro effort\` always change the shared default that explain, show, btw, and advisor fall back to when they have no override. Use \`/bro config\` to give one of them its own model or effort.
 
 ## Side conversation
 
 - \`/bro btw [--fresh] [--full] [question]\` — open a side conversation. Sandboxed (read-only) by default; add \`--full\` to let it read and edit the workspace, and \`--fresh\` to start without main-session context. Inside the side thread, type questions and press Enter (empty Enter re-asks); \`/copy\` copies the latest answer to the main editor without submitting (use \`/copy!\` to replace an existing draft), \`/copy-all\` the full thread, \`/retry\` re-asks the last question, and \`/clear\` resets the thread. Esc closes.
 
+## Advisor
+
+- \`bro_advisor\` — a tool the executor agent can voluntarily call mid-task for a second opinion from a fresh Agy process before or after a non-trivial decision. It is registered like any other tool and has no on/off switch of its own; whether the executor can actually call it depends entirely on this host's own tool restrictions
+- \`/bro advisor\` — a quick notice of whether \`bro_advisor\` is available right now, pointing at \`/bro config\`, \`/bro advisor-steer\`, and \`/bro doctor\`
+- \`/bro advisor-steer\` — open an editor for one persistent steering brief the advisor always sees. **Ctrl+S** saves, **Enter**/**Shift+Enter** insert newlines, **Ctrl+K** clears the saved brief and draft, **Ctrl+C** copies the full draft, and **Esc** closes without saving unsaved edits
+- \`/bro doctor\` — the full advisor diagnostic: whether this host exposes and activates \`bro_advisor\`, its resolved model/effort, steering presence, and the Agy compatibility floor
+
+Each consultation is a fresh, standalone Agy process — never resumed, never looping, never automatically triggered. Bro captures the context snapshot (system instructions, active tools, and the conversation so far) automatically; the executor never has to assemble one. The advisor has real tool access in the workspace, running with permissions auto-approved, so it can verify claims itself — it only ever returns advice, and the executor stays responsible for any actual change. The steering brief persists in the session (not sent to the model) and is restored on resume or reload; forking a session inherits it, and edits after the fork are independent of the original branch.
+
 ## Current settings
 
 ${settingsSummary}
@@ -1132,6 +2213,7 @@ Bro temporarily captures mouse input while the modal is open. Native mouse selec
 - Show draws only what already happened in this session — the conversation text of the last few turns, with tool calls, tool results, reasoning, and images always omitted — and cannot read the repository or other files on its own. On a remote or headless session with no display, pressing **O** reports a failure instead of opening the diagram.
 - Show reflects what was reported in the conversation, not independent verification against the actual code or system state.
 - Btw threads are memory-only and do not survive reloads or restarts. A turn is capped at 2 minutes in sandbox mode and 10 minutes in full mode; the side conversation resumes through Agy's \`--conversation\` support.
+- Advisor consultations run with real tool access and auto-approved permissions (\`--dangerously-skip-permissions\`) — there is no enforced read-only isolation, only the advisor's own instructions to advise rather than implement. On invocation failure (not a completed answer), Bro retries with the identical snapshot, steering, and question: once after 5 seconds, once more after 10 seconds, then returns Agy's own diagnostic as the failure.
 
 ## Privacy and safety
 
@@ -1144,6 +2226,8 @@ For webpages, it connects directly to the site without browser cookies; the site
 
 Usage and Doctor checks contact Agy but do not send source text or run a model turn. Pressing **C** sends the explanation to your system clipboard.
 
+Each advisor consultation sends the executor's system instructions, active tool list, ordered conversation (including tool calls and results, since the advisor needs to verify claims), your steering brief, and the executor's optional question to Agy and your model provider; the advisor process itself can read and edit the workspace with no permission prompts. The steering brief and activation state are stored as session-only extension data — never added to the main conversation Pi or the model sees.
+
 ## Custom prompt
 
 Create or edit \`${PROMPT_FILE}\` and include \`{{response}}\` exactly once. Bro reads it on the next explanation and never modifies it. Existing valid custom prompts continue working unchanged.
@@ -1475,6 +2559,18 @@ export function resolveBtwThread(existing: BtwThread | undefined, parsed: { fres
 	return !existing || startFresh ? { turns: [], full: targetFull } : existing;
 }
 
+export function formatBtwTranscript(turns: readonly BtwTurn[]): string {
+	return turns
+		.map((turn) => {
+			const question = turn.question.split(/\r?\n/).map((line) => (line ? `> ${line}` : ">")).join("\n");
+			// A turn aborted mid-stream can end inside an unclosed code fence, which would swallow the
+			// separator and every later turn; close it so each turn renders as its own block.
+			const answer = (turn.answer.match(/^```/gm)?.length ?? 0) % 2 === 1 ? `${turn.answer}\n\`\`\`` : turn.answer;
+			return `> **You**\n>\n${question}\n\n**Bro**\n\n${answer}`;
+		})
+		.join("\n\n---\n\n");
+}
+
 export function parseBtwAgyLine(line: string): { delta?: string; result?: string; conversationId?: string; error?: string } {
 	let event: AgyEvent;
 	try {
@@ -1791,7 +2887,7 @@ async function openBtwModal(
 			let closed = false;
 			let controller: AbortController | undefined;
 
-			const transcript = () => thread.turns.map((turn) => `## you\n${turn.question}\n\n${turn.answer}`).join("\n\n");
+			const transcript = () => formatBtwTranscript(thread.turns);
 
 			const close = () => {
 				if (closed) return;
@@ -1829,7 +2925,7 @@ async function openBtwModal(
 					const settings = await readSettings();
 					const result = await runBtwTurn(
 						buildBtwPrompt(context, question),
-						agySelection(settings),
+						agySelection(capabilityPair(settings, "btw")),
 						{ full: thread.full, cwd: ctx.cwd, conversationId: thread.conversationId },
 						turnController.signal,
 						(partial) => {
@@ -1934,11 +3030,112 @@ export default async function bro(pi: ExtensionAPI) {
 		if (result.source) lastResult = { source: result.source, text: result.text };
 	};
 
-	pi.on("session_start", async () => {
+	pi.on("session_start", async (_event, _ctx) => {
 		lastResult = undefined;
 		btwThread = undefined;
 	});
 
+	pi.registerTool({
+		name: ADVISOR_TOOL_NAME,
+		label: "Bro advisor",
+		description:
+			"Consult a fresh, independent Agy process for a second opinion mid-task. It has real, unsandboxed tool access in the current workspace (read files, search, run commands) with permissions auto-approved, and is instructed to investigate before advising and to leave edits to you — that is a behavioral instruction to the advisor, not an enforced restriction, so treat its findings as advice rather than a delegated implementation. You never need to prepare a summary or evidence first: Bro automatically captures your system instructions, active tools, and the conversation so far, plus any human-set steering priorities, and sends them to the advisor.",
+		promptSnippet: "bro_advisor({question?}): consult a fresh Agy process for a second opinion; it investigates the workspace itself and returns advice",
+		promptGuidelines: [
+			"Call bro_advisor before or after a non-trivial design or scope decision, or when genuinely uncertain, for a second opinion from a fresh, independent Agy process.",
+			"question is optional — never delay a call to first prepare a summary or evidence; Bro captures your context automatically.",
+			"Any human-set steering priorities are applied automatically by the advisor; you don't need to relay or repeat them.",
+			"The advisor is instructed to only return advice and leave edits to you — that instruction is not enforced, so verify its findings yourself rather than treating them as a completed implementation.",
+		],
+		parameters: Type.Object({
+			question: Type.Optional(
+				Type.String({ description: "Optional question to focus the consultation on. Leave unset to ask for general advice on the current state." }),
+			),
+		}),
+		async execute(_toolCallId, params, signal, onUpdate, ctx) {
+			const state = resolveAdvisorState(ctx.sessionManager.getBranch());
+			const settings = await readSettings();
+			const selection = agySelection(capabilityPair(settings, "advisor"));
+			const snapshot = buildAdvisorSnapshot(ctx, pi);
+			const prompt = buildAdvisorPrompt(state.steering, snapshot.text, params.question);
+			let lastAttempt: AdvisorToolDetails = { status: "investigating", attempt: 1, of: 3, elapsedMs: 0 };
+			try {
+				const run = await runAdvisorWithRetries(
+					prompt,
+					selection,
+					ctx.cwd,
+					signal ?? new AbortController().signal,
+					undefined,
+					undefined,
+					(details) => {
+						lastAttempt = details;
+						const label = advisorAttemptLabel(lastAttempt);
+						onUpdate?.({
+							content: [{ type: "text", text: label }],
+							details: lastAttempt,
+						});
+						// A host's tool-card renderer may replace onUpdate's partial renderResult with its
+						// own generic placeholder for the whole run (observed with pi-cc-extensions' default
+						// mode, which hardcodes "Pending…" for every isPartial tool result unless the tool
+						// is opted into its excludeRenderers list). The footer/status bar is a separate,
+						// host-owned surface that no such tool-card override touches, so mirror progress
+						// there too as a fallback the user can see regardless of that renderer choice.
+						ctx.ui.setStatus(ADVISOR_STATUS_BAR_KEY, label);
+					},
+				);
+				const effort = selection.effort ?? "model default";
+				const omissions = `image/reasoning bodies omitted when present; ${snapshot.hadCompaction ? "Pi compaction summaries replace earlier turns" : "no Pi compaction summary present"}`;
+				const details: AdvisorToolDetails = {
+					...lastAttempt,
+					status: "done",
+					attempt: run.attempts,
+					model: selection.model,
+					effort,
+					durationMs: run.durationMs,
+					cwd: ctx.cwd,
+					steeringIncluded: Boolean(state.steering.trim()),
+					snapshotChars: snapshot.text.length,
+					broTruncated: false,
+					omissions,
+					// run.activityCount is the exact final total; lastAttempt's may lag behind by up to
+					// the activity throttle window.
+					activityCount: run.activityCount,
+				};
+				const header = `Bro advisor · model: ${selection.model} · effort: ${effort} · ${run.attempts} attempt${run.attempts === 1 ? "" : "s"} · ${Math.ceil(run.durationMs / 1_000)}s`;
+				const context = `Context · cwd: ${JSON.stringify(ctx.cwd)} · steering: ${details.steeringIncluded ? "included" : "none"} · snapshot: ${snapshot.text.length} chars · Bro truncation: none · omissions: ${omissions}`;
+				return { content: [{ type: "text", text: `${header}\n${context}\n\n${run.advice}` }], details };
+			} finally {
+				ctx.ui.setStatus(ADVISOR_STATUS_BAR_KEY, undefined);
+			}
+		},
+		renderCall(args, theme) {
+			const question = args.question?.trim();
+			return new Text(theme.fg("dim", question ? `Bro advisor · ${question}` : "Bro advisor · consulting…"));
+		},
+		renderResult(result, options, theme) {
+			const details = result.details as AdvisorToolDetails | undefined;
+			if (options.isPartial) {
+				const label = new Text(theme.fg("dim", details ? advisorAttemptLabel(details) : "Bro advisor · investigating…"));
+				// Expanded + running: the simplest native tail -- one dim line per bounded recent
+				// activity label, nothing fancier than the compact renderer above.
+				if (!options.expanded || !details?.activity?.length) return label;
+				const container = new Container();
+				container.addChild(label);
+				for (const line of details.activity) {
+					container.addChild(new Text(theme.fg("dim", `  ${advisorActivityPreview(line)}`)));
+				}
+				return container;
+			}
+			if (!options.expanded && details?.status === "done") return new Text(theme.fg("accent", advisorAttemptLabel(details)));
+			const text = result.content[0]?.type === "text" ? result.content[0].text : "";
+			if (!options.expanded) {
+				const firstLine = text.split("\n").find((line) => line.trim()) ?? "(no advice)";
+				return new Text(`${theme.fg("accent", "Bro advisor")}${theme.fg("dim", ` · ${firstLine}`)}`);
+			}
+			return new Markdown(text, 0, 0, getMarkdownTheme());
+		},
+	});
+
 	pi.registerCommand("bro", {
 		description: "Explain replies, pasted text, documents, and webpages, draw recent session turns, or open a sandboxed side conversation with /bro btw",
 		getArgumentCompletions: (prefix) => {
@@ -2049,7 +3246,7 @@ export default async function bro(pi: ExtensionAPI) {
 						loadingText: "Checking Bro setup…",
 						retryable: true,
 						retryLabel: "check again",
-						run: async (signal) => ({ text: await doctorReport(pi, signal) }),
+						run: async (signal) => ({ text: await doctorReport(pi, ctx, signal) }),
 					});
 				} catch (error) {
 					ctx.ui.notify(errorMessage(error), "error");
@@ -2235,6 +3432,45 @@ export default async function bro(pi: ExtensionAPI) {
 				return;
 			}
 
+			if (action === "config") {
+				if (parts.length !== 1) {
+					ctx.ui.notify("Use /bro config.", "warning");
+					return;
+				}
+				await showBroConfigModal(ctx, pi);
+				return;
+			}
+
+			if (action === "advisor") {
+				// bro_advisor has no on/off/status controls of its own anymore -- it is always registered
+				// and gated only by this host's own tool restrictions. An old on/off/status argument gets
+				// an actionable notice pointing at the commands that replaced it, not a silent no-op.
+				if (parts.length > 1) {
+					ctx.ui.notify(
+						"/bro advisor no longer has on/off/status controls -- bro_advisor is always registered and available whenever this host exposes and activates it. Use /bro config for its model/effort, /bro advisor-steer for its steering brief, or /bro doctor for full diagnostics.",
+						"warning",
+					);
+					return;
+				}
+				const active = pi.getActiveTools().includes(ADVISOR_TOOL_NAME);
+				ctx.ui.notify(
+					active
+						? "Bro advisor is available -- the executor agent can call bro_advisor. Use /bro config for its model/effort, /bro advisor-steer for its steering brief, or /bro doctor for full diagnostics."
+						: "Bro advisor is unavailable in this runtime. Use /bro doctor for full diagnostics, /bro config for its model/effort, or /bro advisor-steer for its steering brief.",
+					active ? "info" : "warning",
+				);
+				return;
+			}
+
+			if (action === "advisor-steer") {
+				if (parts.length !== 1) {
+					ctx.ui.notify("Use /bro advisor-steer.", "warning");
+					return;
+				}
+				await showAdvisorSteerModal(ctx, pi);
+				return;
+			}
+
 			if (action === "help") {
 				if (parts.length !== 1) {
 					ctx.ui.notify("Use /bro help.", "warning");