one-code-extension 0.4.0 → 0.5.0

package/extensions/mcp/index.ts

@@ -16,11 +16,13 @@
  */
 
 import os from "node:os";
-import { getAgentDir, type ExtensionAPI, type ExtensionContext, type ToolDefinition } from "@earendil-works/pi-coding-agent";
+import { isDeepStrictEqual } from "node:util";
+import { CONFIG_DIR_NAME, getAgentDir, type ExtensionAPI, type ExtensionContext, type ToolDefinition } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 import { DEFER_CHANNEL } from "../lib/deferred.ts";
 import { MCP_TOOLS_CHANNEL } from "../lib/mcp-share.ts";
 import { persistIfLarge, sessionResultsDir } from "../lib/persisted-output.ts";
+import { emptyToolResultContent } from "../lib/empty-tool-result.ts";
 import { ccToolRenderers } from "../lib/tui-render.ts";
 import {
 	callTool,
@@ -47,14 +49,15 @@ import { readDisabledMcpServers, setMcpServerDisabled } from "../lib/mcp-overrid
 import { boundedDockHeight, safeThemeBold, safeThemePaint, truncateLine } from "../lib/tui-render.ts";
 import { authenticate as runOAuthFlow, silentProvider } from "./oauth/flow.ts";
 import { hasStoredTokens } from "./oauth/store.ts";
-import { announcedFrom, applyMcpDelta, emptyAnnounced, mcpChangeNotices, mcpDelta, type McpSnapshot } from "./announce.ts";
+import { announcedFrom, applyMcpDelta, emptyAnnounced, mcpAnnouncedBaseline, mcpAnnouncedFromReminders, mcpChangeNotices, mcpDelta, serializeMcpAnnounced, type McpAnnounced, type McpSnapshot, mcpStartupNotices } from "./announce.ts";
+import { CONTEXT_BASELINE_CHANNEL, restoredContext } from "../lib/context-stack.ts";
 import { decodeMcpKey } from "./panel/keys.ts";
 import { type McpEntry, type McpEntryStatus } from "./panel/model.ts";
 import { renderMcpPanel, type McpPaint } from "./panel/render.ts";
 import { applyMcpKey, initialMcpState, type McpEffect } from "./panel/state.ts";
 import { sessionAlive } from "../lib/session-lifecycle.ts";
-import { loadServers, type McpServer } from "./config.ts";
-import { approveMcpServers, persistApproval, projectRootOf } from "./trust.ts";
+import { loadServers, type McpServer, noMcpServersMessage, piMcpConfigPaths, registeredMcpServers } from "./config.ts";
+import { approveMcpServers, type McpTrustDeps, persistApproval, projectRootOf, reconnectRefusal } from "./trust.ts";
 import {
 	capDescription,
 	describeContent,
@@ -65,6 +68,11 @@ import {
 	namespacedToolName,
 } from "./schema.ts";
 import { registerLocalCommand } from "../lib/local-command.ts";
+import { canShowCustomUi, notifyRpcReadOnly } from "../lib/headless-output.ts";
+import { claudeSourcesOn } from "../lib/config-mode.ts";
+import { claudeJsonPath } from "../lib/paths.ts";
+import { consentDialog, startupConsentReady } from "../lib/consent-dialogs.ts";
+import { panelUi } from "../lib/panel-focus.ts";
 
 /** Anthropic's hard limit on a tool name; a longer one fails the whole request. */
 const MAX_TOOL_NAME_LENGTH = 128;
@@ -78,10 +86,13 @@ function unknownServerError(name: string) {
 	};
 }
 
+/** pi's own `mcp.json` files, read because our `/mcp` replaces pi 0.99's built-in MCP (config.ts). */
+const piMcpConfigs = (cwd: string) => piMcpConfigPaths(getAgentDir(), cwd, CONFIG_DIR_NAME);
+
 export default function mcpExtension(pi: ExtensionAPI) {
 	const connections = new Map<string, Connection>();
 	let failures: FailedConnection[] = [];
-	const registered = new Set<string>();
+	const registered = new Map<string, { server: string; tool: string }>();
 	let servers: McpServer[] = [];
 	// http servers that returned a 401 with no stored tokens — authNeeded via OAuth,
 	// distinct from a missing-env authNeeded (which Authenticate cannot fix).
@@ -93,6 +104,13 @@ export default function mcpExtension(pi: ExtensionAPI) {
 	const withheldNames = new Map<string, string>();
 	// Config file paths contributed by plugins, so the panel can group them.
 	let pluginConfigPaths = new Set<string>();
+	// pi 0.99's registry of servers other extensions register; absent on older pi.
+	// Registered after the session started: our servers are read once per session.
+	pi.on("mcp_servers_change", (_event, ctx) => {
+		const text = "An extension changed its MCP servers; run /reload to connect the change.";
+		if (ctx.hasUI) ctx.ui.notify(text, "info");
+		else process.stderr.write(`${text}\n`);
+	});
 	const home = os.homedir();
 	// Live tool definitions, shared with in-process subagents so they reach MCP
 	// through these same open connections instead of connecting their own.
@@ -102,6 +120,8 @@ export default function mcpExtension(pi: ExtensionAPI) {
 	// those blocks are frozen and later changes ride one-shot notices (./announce.ts).
 	let requestSent = false;
 	let announced = emptyAnnounced();
+	/** A resumed snapshot from before structured baselines: its MCP blocks, until the server names are known. */
+	let legacyBlocks: { instructions?: string; failures?: string } | undefined;
 	pi.on("context", () => {
 		requestSent = true;
 	});
@@ -114,6 +134,8 @@ export default function mcpExtension(pi: ExtensionAPI) {
 	const resultsDir = (ctx: ExtensionContext | undefined): string => sessionResultsDir(ctx);
 
 	const registerToolsFor = (connection: Connection) => {
+		// Names other extensions own, read once per batch (getAllTools builds every definition).
+		let taken: Set<string> | undefined;
 		for (const tool of connection.tools) {
 			const name = namespacedToolName(connection.server.name, tool.name);
 			// Anthropic caps a tool name at 128 characters and rejects the whole
@@ -128,8 +150,12 @@ export default function mcpExtension(pi: ExtensionAPI) {
 				});
 				continue;
 			}
-			if (registered.has(name)) {
-				// Two tools sanitise to one name (`a-b` and `a_b`, or a server
+			const owner = registered.get(name);
+			// An unchanged tool on reconnect keeps its exact definition and loaded
+			// state. Only a different raw server/tool pair is a name collision.
+			if (owner?.server === connection.server.name && owner.tool === tool.name) continue;
+			if (owner || (taken ??= new Set(pi.getAllTools().map((existing) => existing.name))).has(name)) {
+				// Two tools sanitise to one name (`a.b` and `a_b`, or a server
 				// reconnecting under a stale registration). Skipping silently would
 				// make the second tool unreachable with no trace; record it where
 				// the connection summary reports it.
@@ -139,7 +165,7 @@ export default function mcpExtension(pi: ExtensionAPI) {
 				});
 				continue;
 			}
-			registered.add(name);
+			registered.set(name, { server: connection.server.name, tool: tool.name });
 
 			const def: ToolDefinition = {
 				name,
@@ -147,7 +173,7 @@ export default function mcpExtension(pi: ExtensionAPI) {
 				...ccToolRenderers(`${connection.server.name}: ${tool.name}`),
 				description: capDescription(tool.description) ?? `MCP tool "${tool.name}" from server "${connection.server.name}".`,
 				parameters: jsonSchemaToTypeBox(tool.inputSchema),
-				async execute(toolCallId, params, _signal, _onUpdate, ctx) {
+				async execute(toolCallId, params, signal, _onUpdate, ctx) {
 					const live = connections.get(connection.server.name);
 					if (!live) {
 						return {
@@ -156,17 +182,27 @@ export default function mcpExtension(pi: ExtensionAPI) {
 							isError: true,
 						};
 					}
+					const current = live.tools.find((candidate) => candidate.name === tool.name);
+					if (!current || !isDeepStrictEqual(current.inputSchema, tool.inputSchema)) {
+						return {
+							content: [{ type: "text", text: !current
+								? `MCP server "${connection.server.name}" no longer exposes tool "${tool.name}".`
+								: `MCP tool "${name}" changed its input schema. Run /reload to load the new definition; this call was not sent.` }],
+							details: {} as Record<string, unknown>,
+							isError: true,
+						};
+					}
 					try {
-						const result = await callTool(live, tool.name, (params ?? {}) as Record<string, unknown>);
-						const { text, images } = describeContent(result.content as McpContentBlock[] | undefined, connection.server.name);
+						const result = await callTool(live, tool.name, (params ?? {}) as Record<string, unknown>, signal);
+						const { text: contentText, images } = describeContent(result.content as McpContentBlock[] | undefined, connection.server.name);
+						const structuredText = result.structuredContent !== undefined ? JSON.stringify(result.structuredContent, null, 2) : "";
+						const text = [contentText, structuredText].filter(Boolean).join("\n");
+						const content = [
+							...(text ? [{ type: "text" as const, text: persistIfLarge(text, { dir: resultsDir(ctx), id: toolCallId }) }] : []),
+							...images.map((image) => ({ type: "image" as const, data: image.data, mimeType: image.mimeType })),
+						];
 						return {
-							content: [
-								{
-									type: "text",
-									text: text ? persistIfLarge(text, { dir: resultsDir(ctx), id: toolCallId }) : "(no output)",
-								},
-								...images.map((image) => ({ type: "image" as const, data: image.data, mimeType: image.mimeType })),
-							],
+							content: emptyToolResultContent(content, name) ?? content,
 							details: { server: connection.server.name, tool: tool.name } as Record<string, unknown>,
 							isError: result.isError === true,
 						};
@@ -232,15 +268,35 @@ export default function mcpExtension(pi: ExtensionAPI) {
 			});
 			emitInstructions();
 		};
+		let previousTools = connection.tools;
+		connection.onToolsChanged = (error) => {
+			if (!alive() || connection.closing || connections.get(server.name) !== connection) return;
+			if (error) {
+				failures.push({ server, error: error.message });
+				pi.events.emit(REMINDER_CHANNEL, { text: `MCP server "${server.name}" could not refresh its tool list: ${error.message}` });
+				return;
+			}
+			const unavailable = previousTools.filter((old) => {
+				const current = connection.tools.find((tool) => tool.name === old.name);
+				return !current || !isDeepStrictEqual(current.inputSchema, old.inputSchema);
+			});
+			previousTools = connection.tools;
+			registerToolsFor(connection);
+			if (unavailable.length > 0) {
+				pi.events.emit(REMINDER_CHANNEL, {
+					text: `MCP server "${server.name}" removed or changed these tools: ${unavailable.map((tool) => namespacedToolName(server.name, tool.name)).join(", ")}. Their old definitions cannot be used. Run /reload to refresh changed schemas.`,
+				});
+			}
+		};
 		registerToolsFor(connection);
 		for (const warning of connection.warnings) failures.push({ server, error: warning });
-		if (connection.resources.length > 0) registerResourceTools();
+		if (connection.resources.length > 0 || connection.resourceTemplates?.length) registerResourceTools();
 	};
 
 	const connectOne = async (server: McpServer): Promise<void> => {
 		failures = failures.filter((f) => f.server.name !== server.name);
 		oauthNeeded.delete(server.name);
-		const provider = server.kind === "http" && hasStoredTokens(server.name) ? silentProvider(server.name) : undefined;
+		const provider = server.kind === "http" && hasStoredTokens(server) ? silentProvider(server) : undefined;
 		try {
 			const connection = await connect(server, provider);
 			if (!alive()) {
@@ -265,6 +321,9 @@ export default function mcpExtension(pi: ExtensionAPI) {
 	 * message 1 are (re)written; after it they are frozen and only the changes are
 	 * announced (./announce.ts).
 	 */
+	const publishBaseline = (value: McpAnnounced) => {
+		pi.events.emit(CONTEXT_BASELINE_CHANNEL, { key: "mcp", value: serializeMcpAnnounced(value) });
+	};
 	const emitInstructions = () => {
 		const live = [...connections.values()];
 		const snapshot: McpSnapshot = {
@@ -274,6 +333,8 @@ export default function mcpExtension(pi: ExtensionAPI) {
 
 		if (!requestSent) {
 			// Nothing is cached yet: (re)write the standing message-1 blocks.
+			const nextAnnounced = announcedFrom(snapshot);
+			publishBaseline(nextAnnounced);
 			if (snapshot.failed.length === 0) {
 				pi.events.emit(REMINDER_CHANNEL, { scope: "every-turn", key: "mcp-failures", text: "", remove: true });
 			} else {
@@ -300,35 +361,75 @@ export default function mcpExtension(pi: ExtensionAPI) {
 				// being told to use tools that are gone.
 				pi.events.emit(REMINDER_CHANNEL, { scope: "every-turn", key: "mcp-instructions", text: "", remove: true });
 			}
-			announced = announcedFrom(snapshot);
+			announced = nextAnnounced;
 			return;
 		}
 
 		// Message 1 is frozen (rewriting it would re-cache the whole conversation):
 		// tell the model only what changed, as one-shots where it reads next.
 		const delta = mcpDelta(announced, snapshot);
-		for (const text of mcpChangeNotices(delta)) pi.events.emit(REMINDER_CHANNEL, { text });
+		const notices = mcpChangeNotices(delta);
+		if (notices.length > 0) {
+			const nextAnnounced = { instructed: new Map(announced.instructed), failed: new Map(announced.failed) };
+			applyMcpDelta(nextAnnounced, delta);
+			publishBaseline(nextAnnounced);
+		}
+		for (const text of notices) pi.events.emit(REMINDER_CHANNEL, { text });
 		applyMcpDelta(announced, delta);
 	};
 
 	/** Config files that exist but failed to parse (review M11) — shown at startup and in /mcp. */
 	let configErrors: string[] = [];
 
+	/** How the consent check asks, tells and records a "No", for startup and for Reconnect alike. */
+	const consentDeps = (ctx: ExtensionContext): McpTrustDeps => ({
+		hasUI: ctx.hasUI,
+		select: (title, options) => consentDialog(pi.events, (signal) => ctx.ui.select(title, options, { signal })),
+		notify: (message) => {
+			if (ctx.hasUI) ctx.ui.notify(message, "warning");
+			else process.stderr.write(`${message}\n`);
+		},
+		disable: (server) => {
+			setMcpServerDisabled(server.name, true, "project", ctx.cwd, home);
+			disabledNames.add(server.name);
+		},
+	});
+
 	const connectAll = async (ctx: ExtensionContext) => {
 		const plugins = discoverPlugins(defaultDiscoverRoots(getAgentDir(), ctx.cwd));
 		pluginConfigPaths = new Set(plugins.mcpConfigs);
 		configErrors = [];
+		const configNotes: string[] = [];
 		servers = loadServers(ctx.cwd, home, process.env, [...pluginConfigPaths], {
 			pluginNames: plugins.mcpConfigPlugins,
 			onError: (path, message) => configErrors.push(`${path}: ${message}`),
+			piConfigs: piMcpConfigs(ctx.cwd),
+			onNote: (message) => configNotes.push(message),
+			registered: registeredMcpServers(pi),
 		});
-		if (configErrors.length > 0) {
-			const text = `MCP config could not be parsed (ignored): ${configErrors.join("; ")}`;
+		// An older snapshot stored only the rendered blocks: read them again by the
+		// configured names, before any delta is taken against them.
+		if (legacyBlocks) {
+			announced = mcpAnnouncedFromReminders(legacyBlocks.instructions, legacyBlocks.failures, servers.map((server) => server.name));
+			legacyBlocks = undefined;
+		}
+		const configWarnings = [
+			...(configErrors.length > 0 ? [`MCP config could not be parsed (ignored): ${configErrors.join("; ")}`] : []),
+			...configNotes,
+		];
+		for (const text of configWarnings) {
 			if (ctx.hasUI) ctx.ui.notify(text, "warning");
 			else process.stderr.write(`${text}\n`);
 		}
 		disabledNames = readDisabledMcpServers(ctx.cwd, home);
-		if (servers.length === 0) return;
+		// A resumed first-prepend may describe a server whose configuration was
+		// removed entirely. There is no connection attempt in that case, so make
+		// the frozen-prefix delta explicit rather than leaving the stale capability
+		// silently standing. Fresh empty sessions keep their byte-identical no-op.
+		if (servers.length === 0) {
+			if (requestSent) emitInstructions();
+			return;
+		}
 
 		// Disabled servers are listed but never connected; a server with an unset
 		// credential env var stays "needs authentication" and is not attempted
@@ -336,19 +437,13 @@ export default function mcpExtension(pi: ExtensionAPI) {
 		// server needs the user's consent first (trust.ts — a cloned repo must not
 		// run commands at startup). Everything else connects.
 		const candidates = servers.filter((server) => !disabledNames.has(server.name) && !server.missingEnv?.length);
-		const consent = await approveMcpServers(candidates, pluginConfigPaths, ctx.cwd, home, {
-			hasUI: ctx.hasUI,
-			select: (title, options) => ctx.ui.select(title, options),
-			notify: (message) => {
-				if (ctx.hasUI) ctx.ui.notify(message, "warning");
-				else process.stderr.write(`${message}\n`);
-			},
-			disable: (server) => {
-				setMcpServerDisabled(server.name, true, "project", ctx.cwd, home);
-				disabledNames.add(server.name);
-			},
-		});
-		if (!alive()) return;
+		// Reserve the modal position before the asynchronous policy read, so the
+		// external-includes dialog cannot jump ahead of MCP's startup consent.
+		const consent = await consentDialog(pi.events, (signal) => approveMcpServers(candidates, pluginConfigPaths, ctx.cwd, home, {
+			...consentDeps(ctx),
+			select: (title, options) => ctx.ui.select(title, options, { signal }),
+		}));
+		if (!consent || !alive()) return;
 		withheldNames.clear();
 		for (const { server, reason } of consent.withheld) {
 			withheldNames.set(
@@ -364,16 +459,15 @@ export default function mcpExtension(pi: ExtensionAPI) {
 
 		if (!alive()) return;
 
-		if (failures.length > 0) {
-			const text = failures.map((f) => `MCP server "${f.server.name}" failed: ${f.error}`).join("\n") + " (/mcp for status)";
-			if (ctx.hasUI) ctx.ui.notify(text, "warning");
-			else process.stderr.write(`${text}\n`);
-		}
-		if (oauthNeeded.size > 0 && ctx.hasUI) {
-			ctx.ui.notify(
-				`${oauthNeeded.size} MCP server${oauthNeeded.size === 1 ? "" : "s"} need authentication — run /mcp to authenticate.`,
-				"warning",
-			);
+		// Warnings from servers that did connect are shown in /mcp, not as failures.
+		const failed = failures.filter((f) => !connections.has(f.server.name));
+		if (ctx.hasUI) {
+			// Needs auth: an OAuth sign-in, or a credential variable that is not set (never attempted).
+			const needsAuth = new Set([...oauthNeeded, ...servers.filter((server) => !disabledNames.has(server.name) && server.missingEnv?.length).map((server) => server.name)]).size;
+			for (const text of mcpStartupNotices(new Set(failed.map((f) => f.server.name)).size, needsAuth)) ctx.ui.notify(text, "warning");
+		} else if (failed.length > 0) {
+			// Headless runs have no /mcp, so they keep each server's error on stderr.
+			process.stderr.write(`${failed.map((f) => `MCP server "${f.server.name}" failed: ${f.error}`).join("\n")}\n`);
 		}
 
 		emitInstructions();
@@ -384,12 +478,17 @@ export default function mcpExtension(pi: ExtensionAPI) {
 		if (resourceToolsRegistered) return;
 		resourceToolsRegistered = true;
 
-		pi.registerTool({
+		const registerResourceTool: ExtensionAPI["registerTool"] = (definition) => {
+			pi.registerTool(definition);
+			sharedTools.push(definition as ToolDefinition);
+		};
+
+		registerResourceTool({
 			name: "list_mcp_resources",
 			label: "MCP Resources",
 			...ccToolRenderers("MCP Resources"),
 			description:
-				"List resources exposed by connected MCP servers. Resources are readable documents or data the server offers, addressed by uri.",
+				"List resources and URI templates exposed by connected MCP servers. Resources are readable documents or data the server offers, addressed by uri. Substitute template variables to construct a resource uri.",
 			parameters: Type.Object({
 				server: Type.Optional(Type.String({ description: "Limit to one server by name" })),
 			}),
@@ -417,12 +516,15 @@ export default function mcpExtension(pi: ExtensionAPI) {
 							`${connection.server.name} ${resource.uri}${resource.name ? ` — ${resource.name}` : ""}${resource.description ? `: ${resource.description}` : ""}`,
 						);
 					}
+					for (const template of connection.resourceTemplates ?? []) {
+						lines.push(`${connection.server.name} ${template.uriTemplate} (URI template)${template.name ? ` — ${template.name}` : ""}${template.description ? `: ${template.description}` : ""}`);
+					}
 				}
 				return {
 					content: [
 						{
 							type: "text",
-							text: lines.length ? persistIfLarge(lines.join("\n"), { dir: resultsDir(ctx), id: toolCallId }) : "No MCP resources available.",
+							text: lines.length ? persistIfLarge(lines.join("\n"), { dir: resultsDir(ctx), id: toolCallId }) : "No resources found. MCP servers may still provide tools even if they have no resources.",
 						},
 					],
 					details: { count: lines.length },
@@ -430,7 +532,7 @@ export default function mcpExtension(pi: ExtensionAPI) {
 			},
 		});
 
-		pi.registerTool({
+		registerResourceTool({
 			name: "read_mcp_resource",
 			label: "Read MCP Resource",
 			...ccToolRenderers("Read MCP Resource"),
@@ -439,17 +541,17 @@ export default function mcpExtension(pi: ExtensionAPI) {
 				server: Type.String({ description: "Server name that owns the resource" }),
 				uri: Type.String({ description: "Resource uri" }),
 			}),
-			async execute(toolCallId, params, _signal, _onUpdate, ctx) {
+			async execute(toolCallId, params, signal, _onUpdate, ctx) {
 				const connection = connections.get(params.server);
 				if (!connection) return unknownServerError(params.server);
 				try {
-					const result = await readResource(connection, params.uri);
-					const text = describeResourceContents(result.contents as McpResourceContents[] | undefined);
+					const result = await readResource(connection, params.uri, signal);
+					const text = describeResourceContents(result.contents as McpResourceContents[] | undefined) || JSON.stringify({ contents: result.contents ?? [] });
 					return {
 						content: [
 							{
 								type: "text",
-								text: text ? persistIfLarge(text, { dir: resultsDir(ctx), id: toolCallId }) : "(empty resource)",
+								text: persistIfLarge(text, { dir: resultsDir(ctx), id: toolCallId }),
 							},
 						],
 						details: { server: params.server, uri: params.uri },
@@ -464,7 +566,7 @@ export default function mcpExtension(pi: ExtensionAPI) {
 			},
 		});
 
-		pi.registerTool({
+		registerResourceTool({
 			name: "read_mcp_resource_dir",
 			label: "List MCP Resource Directory",
 			...ccToolRenderers("List MCP Resource Directory"),
@@ -474,18 +576,18 @@ export default function mcpExtension(pi: ExtensionAPI) {
 				server: Type.String({ description: "Server name that owns the directory" }),
 				uri: Type.String({ description: "The directory resource uri to list" }),
 			}),
-			async execute(toolCallId, params, _signal, _onUpdate, ctx) {
+			async execute(toolCallId, params, signal, _onUpdate, ctx) {
 				const connection = connections.get(params.server);
 				if (!connection) return unknownServerError(params.server);
 				try {
-					const result = await readResourceDir(connection, params.uri);
+					const result = await readResourceDir(connection, params.uri, signal);
 					const entries = (result.resources ?? result.entries ?? []) as Array<{ uri?: string; name?: string; mimeType?: string }>;
 					const lines = entries.map((e) => `${e.uri ?? "(no uri)"}${e.name ? ` — ${e.name}` : ""}${e.mimeType ? ` (${e.mimeType})` : ""}`);
 					return {
 						content: [
 							{
 								type: "text",
-								text: lines.length ? persistIfLarge(lines.join("\n"), { dir: resultsDir(ctx), id: toolCallId }) : "(empty directory)",
+								text: lines.length ? persistIfLarge(lines.join("\n"), { dir: resultsDir(ctx), id: toolCallId }) : 'Directory is empty.\n{"resources":[]}',
 							},
 						],
 						details: { server: params.server, uri: params.uri },
@@ -503,13 +605,19 @@ export default function mcpExtension(pi: ExtensionAPI) {
 		for (const name of ["list_mcp_resources", "read_mcp_resource", "read_mcp_resource_dir"]) {
 			pi.events.emit(DEFER_CHANNEL, { name, keywords: ["mcp", "resource", "document", "uri", "directory"] });
 		}
+		pi.events.emit(MCP_TOOLS_CHANNEL, { tools: [...sharedTools] });
 	};
 
 	pi.on("session_start", async (_event, ctx) => {
-		// A new session (/clear, resume in a new process) has no cached prefix yet:
-		// its message-1 blocks are written fresh (same reset as tool-search).
-		requestSent = false;
-		announced = emptyAnnounced();
+		const restored = restoredContext(pi.events);
+		// The restored stack owns message 1. Its structured state records the exact
+		// arbitrary server text that was shown; a fresh session keeps prior behavior.
+		requestSent = restored !== undefined;
+		const stackText = (key: string) => restored?.stack.find((entry) => (entry as { key?: string }).key === key)?.text;
+		const structured = mcpAnnouncedBaseline(restored?.baselines.mcp);
+		legacyBlocks = structured ? undefined : { instructions: stackText("mcp-instructions"), failures: stackText("mcp-failures") };
+		announced = structured ?? mcpAnnouncedFromReminders(legacyBlocks?.instructions, legacyBlocks?.failures);
+		if (!restored) publishBaseline(announced);
 		// pi awaits session_start handlers serially before the prompt opens, and
 		// remote servers take seconds to answer — awaiting here was the entire
 		// "slow startup" (4.9s → 0.24s measured, findings §15). In the interactive
@@ -524,6 +632,9 @@ export default function mcpExtension(pi: ExtensionAPI) {
 			// `failures`, so this only catches setup bugs — surface them loud.
 			if (ctx.hasUI) ctx.ui.notify(`MCP startup failed: ${(error as Error).message}`, "error");
 		});
+		// The external-includes question follows the startup hooks/MCP consent,
+		// but does not wait for slow server connections.
+		startupConsentReady(pi.events);
 		connecting.finally(() => {
 			connectSettled = true;
 			// The session may be gone by now (/clear while a remote server was still
@@ -600,12 +711,18 @@ export default function mcpExtension(pi: ExtensionAPI) {
 		if (pluginConfigPaths.has(server.source)) {
 			return { rank: 3, group: "Plugin MCPs", configLocation: "Plugin configuration", scope: "project" };
 		}
-		if (server.source === join(home, ".claude.json")) {
+		if (server.source === claudeJsonPath(home) || server.piOrigin === "user") {
 			return { rank: 0, group: `User MCPs (${shorten(server.source)})`, configLocation: shorten(server.source), scope: "user" };
 		}
 		if (server.source.endsWith(join(".claude", "settings.local.json"))) {
 			return { rank: 2, group: "Project MCPs (.claude/settings.local.json)", configLocation: shorten(server.source), scope: "project" };
 		}
+		if (server.piOrigin === "extension") {
+			return { rank: 3, group: "Extension MCPs", configLocation: shorten(server.source), scope: "user" };
+		}
+		if (server.piOrigin === "project") {
+			return { rank: 1, group: `Project MCPs (${join(CONFIG_DIR_NAME, "mcp.json")})`, configLocation: shorten(server.source), scope: "project" };
+		}
 		return { rank: 1, group: `Project MCPs (${shorten(server.source)})`, configLocation: shorten(server.source), scope: "project" };
 	};
 
@@ -626,7 +743,7 @@ export default function mcpExtension(pi: ExtensionAPI) {
 				// honestly from whether tokens are stored — not just "failed http".
 				const authState =
 					status === "failed" && server.kind === "http"
-						? hasStoredTokens(server.name)
+						? hasStoredTokens(server)
 							? ("authenticated" as const)
 							: ("notAuthenticated" as const)
 						: undefined;
@@ -656,7 +773,7 @@ export default function mcpExtension(pi: ExtensionAPI) {
 	const MCP_PANEL_MAX_HEIGHT = 22;
 
 	const openMcpPanel = async (ctx: ExtensionContext): Promise<void> => {
-		await ctx.ui.custom<null>((tui, theme, _keybindings, done) => {
+		await panelUi(pi.events, ctx.ui).custom<null>((tui, theme, _keybindings, done) => {
 			const paint: McpPaint = { fg: safeThemePaint(theme), bold: safeThemeBold(theme) };
 			const state = initialMcpState();
 			let notices: string[] = [];
@@ -692,7 +809,24 @@ export default function mcpExtension(pi: ExtensionAPI) {
 			const runReconnect = async (entry: McpEntry) => {
 				const server = servers.find((s) => s.name === entry.name);
 				if (!server || busy.has(entry.name)) return;
+				const refusal = reconnectRefusal(server);
+				if (refusal) {
+					notices = [refusal];
+					syncRepaint();
+					return;
+				}
 				busy.add(entry.name);
+				// Reconnect spawns the command again, so a project server needs the
+				// same consent startup asked for (a stored or session approval
+				// passes without a prompt).
+				const consent = await approveMcpServers([server], pluginConfigPaths, ctx.cwd, home, consentDeps(ctx));
+				if (consent.approved.length === 0) {
+					busy.delete(entry.name);
+					if (!alive()) return;
+					notices = [`"${entry.name}" was not approved, so it was not reconnected.`];
+					syncRepaint();
+					return;
+				}
 				notices = [`Reconnecting to "${entry.name}"…`];
 				syncRepaint();
 				const existing = connections.get(entry.name);
@@ -844,16 +978,19 @@ export default function mcpExtension(pi: ExtensionAPI) {
 	};
 
 	registerLocalCommand(pi, "mcp", {
+		reportsResult: true,
 		description: "Manage MCP servers (status, reconnect, authenticate, enable/disable)",
 		handler: async (args, ctx) => {
 			if (servers.length === 0) {
-				ctx.ui.notify("No MCP servers configured. Add them to .mcp.json or ~/.claude.json.", "info");
-				return;
+				const stdout = noMcpServersMessage(claudeSourcesOn());
+				ctx.ui.notify(stdout, "info");
+				return stdout;
 			}
-			if (ctx.hasUI) {
+			if (canShowCustomUi(ctx)) {
 				await openMcpPanel(ctx);
-				return;
+				return "MCP dialog dismissed";
 			}
+			const readOnly = notifyRpcReadOnly(ctx, "/mcp", "reconnect, authenticate, enable or disable servers");
 			// Non-interactive fallback: a flat status listing, with tool/resource
 			// counts and any warning for connected servers.
 			const lines = servers.map((server) => {
@@ -869,6 +1006,7 @@ export default function mcpExtension(pi: ExtensionAPI) {
 				return `${status.padEnd(12)} ${server.name}${suffix} (${server.source})`;
 			});
 			ctx.ui.notify(lines.join("\n"), "info");
+			return [readOnly, ...lines].filter(Boolean).join("\n");
 		},
 	});
 }

package/extensions/mcp/oauth/browser.ts

@@ -1,26 +1,47 @@
 /**
- * Open a URL in the user's default browser (no dependency — platform command).
+ * Open a sign-in URL in the user's default browser (`lib/open-browser.ts`),
+ * falling back to printing the URL for manual paste when no browser starts.
  *
- * Detached and unref'd so the auth flow never blocks on the browser process,
- * and errors are swallowed to a boolean: a headless box has no browser, in which
- * case the caller falls back to printing the URL for manual paste.
+ * The authorization URL is the server's choice (its metadata names the
+ * endpoint, the SDK appends `&`-joined parameters), so only `https:`, or
+ * `http:` on a loopback host, is opened: `open` and `xdg-open` hand any other
+ * scheme (`file:`, a custom handler) to whatever the desktop registered for it.
  */
 
-import { spawn } from "node:child_process";
+import { launchOpener, type OpenerPlan, openerPlan } from "../../lib/open-browser.ts";
 
-export function openBrowser(url: string): boolean {
-	const [command, args] =
-		process.platform === "darwin"
-			? (["open", [url]] as const)
-			: process.platform === "win32"
-				? (["cmd", ["/c", "start", "", url]] as const)
-				: (["xdg-open", [url]] as const);
+export type BrowserPlan = OpenerPlan | { refused: string };
+
+const LOOPBACK_HOSTS = new Set(["localhost", "127.0.0.1", "[::1]"]);
+
+/** Why a URL must not be opened, or undefined when it may. */
+export function refuseAuthorizationUrl(url: string): string | undefined {
+	let parsed: URL;
 	try {
-		const child = spawn(command, [...args], { stdio: "ignore", detached: true });
-		child.on("error", () => {});
-		child.unref();
-		return true;
+		parsed = new URL(url);
 	} catch {
-		return false;
+		return "it is not a valid URL";
 	}
+	if (parsed.protocol === "https:") return undefined;
+	if (parsed.protocol === "http:" && LOOPBACK_HOSTS.has(parsed.hostname)) return undefined;
+	return `its scheme is ${parsed.protocol} on ${parsed.hostname || "no host"}; a sign-in URL must be https (or http on a loopback host)`;
+}
+
+/** The command and argv that open `url` on `platform`, or why it is refused. Pure. */
+export function browserOpenPlan(url: string, platform: NodeJS.Platform = process.platform, env: Record<string, string | undefined> = process.env): BrowserPlan {
+	const refused = refuseAuthorizationUrl(url);
+	if (refused) return { refused };
+	return openerPlan(url, platform, env);
+}
+
+/**
+ * Open `url`, or throw (synchronously) when it is refused: a sign-in the
+ * server pointed at a non-web scheme is a hostile or broken server, and the
+ * error names why. Resolves false when the opener could not start (no browser
+ * on the box).
+ */
+export function openBrowser(url: string): Promise<boolean> {
+	const plan = browserOpenPlan(url);
+	if ("refused" in plan) throw new Error(`refusing to open the authorization URL: ${plan.refused}`);
+	return launchOpener(plan);
 }