pi-profile-switch 0.13.2 → 0.14.0

package/README.md

@@ -60,6 +60,21 @@ A profile that uses every field:
 
 How the fields behave:
 
+- `skills`, `extensions`, `mcps`, `tools` take names or globs (e.g. `"internal-*"`) referencing resources you already installed or configured — profiles never copy them. Installed packages and files in standard locations are discovered automatically; no registration needed.
+- `tools` expands strictly against Pi's non-MCP tool registry — built-ins and extension-contributed tools, attributed by registration ownership (`sourceInfo`). Available MCP tools remain usable independently of `tools`. When a profile declares `tools` and at least one MCP server is enabled, Pi's native MCP discovery entry points (`codemode` and `tool_search`) stay active even if you did not list them; unrelated non-MCP tools excluded by `tools` stay excluded.
+- `mcp_tools` defines per-server MCP tool filtering: keys are literal configured server names and values are literal MCP tool names as exposed by Pi's built-in MCP extension. Globs are not accepted. An omitted server keeps native access to all its tools; a nonempty array allows only matched tools; an empty array (`[]`) denies all tools for that server while leaving it enabled. Unmatched selectors remain restrictive and are not diagnosed, so confirm selectors with the server before writing them.
+- **Migration notes:**
+  - Former MCP references in `tools` (e.g. `mcp__*`, `<server>_*`) no longer govern MCP access. Move desired MCP tool restrictions to `mcp_tools`.
+  - Prefixed selectors (e.g. `<server>_<tool>` forms used by previous MCP integrations) no longer apply; replace them with the literal tool names from Pi's built-in MCP extension.
+- `mcps` references servers from your Pi user-level MCP configuration (`~/.config/mcp/mcp.json`, `~/.agents/mcp.json`, `~/.agents/mcp/mcp.json`, and `<agentDir>/mcp.json`); connection details stay in those files.
+  - **Omitting `mcps`** leaves all discovered user-level servers at their normal availability.
+  - **`mcps: []`** disables every discovered user-level server, including agentDir-only servers; every unselected user-level server keeps its full definition and is explicitly marked `enabled: false` in the generated instance `mcp.json`. Project-level servers are never narrowed.
+  - Trusted project-level MCP servers are always kept enabled and are never narrowed by `mcps`.
+  - Servers using `type: "sse"` cannot be selected; migrate them to streamable HTTP before referencing them in a profile.
+  - A later user-level source replaces a same-named server from an earlier source in full (no field-wise merging), so connection and credential fields are never inherited across files.
+  - A profile that declares neither `mcps` nor `mcp_tools` treats a malformed user-level MCP source as a non-fatal diagnostic (printed on stderr with the file path) and starts with the remaining valid sources. Declaring `mcps` or a nonempty `mcp_tools` makes the same malformed source fail activation, because the allowlist cannot be trusted.
+- The instance `mcp.json` is always a generated snapshot of the merged user-level configuration. In-session `pi mcp add` edits the instance copy, and the next `/profile use` or `/profile reload` overwrites it with the profile's snapshot.
+- Any field you omit keeps plain Pi behavior.
 - `label` and `description` are display metadata. `defaultProvider` and `defaultModel` (declared together) set the startup model; `defaultThinkingLevel` sets its thinking level; `instructions` is appended to the system prompt.
 - `skills`, `extensions`, `mcps`, and `tools` reference installed resources by name or glob; profiles never copy resources. `tools` covers non-MCP tools only (built-ins and extension tools).
 - `mcp_tools` selects tools inside MCP servers by literal server and tool name — globs are rejected. Omit a server to leave it unchanged, use `[]` to deny all of its tools while keeping the server enabled, or list names to allow only those. A literal selector that matches nothing stays restrictive without warning; a server that is unknown, disabled, or project-only fails activation with candidates.
@@ -82,6 +97,7 @@ The instance's `mcp.json` is generated by the launcher. Running `pi mcp add` ins
 | `/profile overlay disable\|enable skill\|extension\|mcp\|tool <name-or-glob>` | Narrow or restore resources for this session only. |
 | `/profile overlay clear` | Drop the overlay and use the profile as written. |
 
+All forms work in every mode, including non-interactive ones (`--mode rpc|text|json`); the bare selector degrades to the profile list where no interactive UI exists. The overlay is a runtime-only narrowing: it is never written to a catalog file and never survives a restart. Tools follow the same disable/enable model as the other resource kinds: a tool `disable` entry narrows the profile's resolved tool references — or the runtime's full available tool set when the profile declares no `tools`.
 All of these work in every mode, including non-interactive ones (`--mode text`, `--mode json`, `--mode rpc`). An overlay lives only in the current runtime: it is never written to your profile files and is gone after a restart. Disabling MCP servers with an overlay is not possible on the built-in `default` profile — it has no server list to narrow.
 
 ## Docs

package/bin/pi-profile.ts

@@ -67,6 +67,9 @@ try {
 		console.error(`pi-profile: warning: ${warning}`);
 	}
 	const generated = await generateRuntimeDir(plan, { agentDir, discovery, projectDir });
+	for (const warning of generated.warnings) {
+		console.error(`pi-profile: warning: ${warning}`);
+	}
 	process.exitCode = await spawnPi({
 		generated,
 		piArgs: args.piArgs,

package/extensions/pi-profile/index.ts

@@ -224,7 +224,17 @@ export default function piProfileExtension(pi: ExtensionAPI): void {
 					const mcpDiscovery = await loadMergedMcpServers(
 						plan.agentDir,
 						projectTrusted ? ctx.cwd : undefined,
+						{
+							invalidSource:
+								plan.mcps !== undefined ||
+								(plan.mcpTools !== undefined && Object.keys(plan.mcpTools).length > 0)
+									? "throw"
+									: "diagnose",
+						},
 					);
+					for (const diagnostic of mcpDiscovery.diagnostics ?? []) {
+						notify(diagnostic, "warning");
+					}
 					const discoveredMcpServers = Object.keys(mcpDiscovery.servers).sort();
 					const disabledMcpServers = discoveredMcpServers.filter(
 						(server) => mcpDiscovery.servers[server]?.enabled === false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-profile-switch",
-  "version": "0.13.2",
+  "version": "0.14.0",
   "description": "Named profiles for Pi: reference skills, extensions, MCP servers, and tools per workflow, switched without restarting. Install: npm install -g pi-profile-switch (not pi install).",
   "type": "module",
   "keywords": [

package/src/launcher/initial-profile.ts

@@ -169,7 +169,7 @@ export async function resolveInitialProfile(
 		(options?.overlay?.disabledMcps?.length ?? 0) > 0,
 	);
 	const mcpDiscovery = needsMcp
-		? await loadMergedMcpServers(context.agentDir, projectDir)
+		? await loadMergedMcpServers(context.agentDir, projectDir, { invalidSource: "throw" })
 		: undefined;
 
 	const plan = await resolveProfile({

package/src/launcher/spawn.ts

@@ -3,8 +3,8 @@
  *
  * The spawned pi gets: the pi-profile extension via `-e` and the user's
  * arguments verbatim. stdio is inherited so interactive
- * TUI, RPC, and print modes all behave natively; exit codes and signals
- * propagate.
+ * TUI, text, JSON, and RPC modes all behave natively; exit codes and
+ * signals propagate.
  */
 
 import { spawn } from "node:child_process";

package/src/mcp-config.ts

@@ -13,8 +13,10 @@
  * (read for ownership classification only — Pi reads the file itself).
  * The legacy project-root `.mcp.json` source is not read.
  *
- * Malformed config files fail loudly — a broken mcp.json must not silently
- * read as "no servers" and reject every reference.
+ * Malformed config files follow the discovery tier: strict mode throws
+ * `McpConfigError` (a broken mcp.json must not silently read as "no servers"
+ * under an explicit MCP policy); diagnostic mode skips the malformed source
+ * with a path-bearing diagnostic so valid sources still merge.
  */
 
 import { homedir } from "node:os";
@@ -34,6 +36,10 @@ export class McpConfigError extends Error {
 
 export interface McpDiscoveryOptions {
 	homeDir?: string;
+	/** How an unreadable or malformed source is handled. "throw" (default)
+	 *  fails discovery with `McpConfigError`; "diagnose" skips the source and
+	 *  records a path-bearing diagnostic so valid sources still merge. */
+	invalidSource?: "throw" | "diagnose";
 }
 
 export interface MergedMcpResult {
@@ -48,6 +54,10 @@ export interface MergedMcpResult {
 	/** The merged user-level configuration object, with later sources
 	 *  overriding earlier ones per server name. */
 	baseConfig?: Record<string, unknown>;
+	/** Path-bearing diagnostics for sources skipped in "diagnose" mode.
+	 *  Always populated by `loadMergedMcpServers`; absent from hand-built
+	 *  discovery fixtures. */
+	diagnostics?: string[];
 }
 
 function setOwnRecordValue<T>(record: Record<string, T>, key: string, value: T): void {
@@ -98,14 +108,19 @@ export async function loadMergedMcpServers(
 	projectDir?: string,
 	options?: McpDiscoveryOptions,
 ): Promise<MergedMcpResult> {
+	const invalidSource = options?.invalidSource ?? "throw";
 	const sources = getStandardMcpConfigSources(agentDir, projectDir, options);
 	const seenPaths = new Set<string>();
 	const servers: Record<string, Record<string, unknown>> = {};
 	const sharedServers = new Set<string>();
 	const projectServers = new Set<string>();
 	const serverOwners: Record<string, "user" | "project"> = {};
+	const diagnostics: string[] = [];
 	let baseConfig: Record<string, unknown> | undefined;
 
+	/** Strict mode fails discovery; diagnostic mode records the path and
+	 *  skips only that source, leaving valid sources available. */
+
 	for (const source of sources) {
 		const resolvedPath = path.resolve(source.path);
 		if (seenPaths.has(resolvedPath)) continue;
@@ -114,11 +129,26 @@ export async function loadMergedMcpServers(
 		const result = await readJsonFile(resolvedPath);
 		if (!result.ok) {
 			if (result.reason === "missing") continue;
+			if (invalidSource === "diagnose") {
+				diagnostics.push(`MCP config is not valid JSON: ${resolvedPath}`);
+				continue;
+			}
 			throw new McpConfigError(`MCP config is not valid JSON: ${resolvedPath}`, resolvedPath);
 		}
 		if (!isRecord(result.value)) {
+			if (invalidSource === "diagnose") {
+				diagnostics.push(`MCP config must be a JSON object: ${resolvedPath}`);
+				continue;
+			}
 			throw new McpConfigError(`MCP config must be a JSON object: ${resolvedPath}`, resolvedPath);
 		}
+		if (result.value.mcpServers !== undefined && !isRecord(result.value.mcpServers)) {
+			if (invalidSource === "diagnose") {
+				diagnostics.push(`"mcpServers" must be a JSON object: ${resolvedPath}`);
+				continue;
+			}
+			throw new McpConfigError(`"mcpServers" must be a JSON object: ${resolvedPath}`, resolvedPath);
+		}
 
 		if (!source.isProject) {
 			// Merge user-level base configuration: later sources override
@@ -128,9 +158,6 @@ export async function loadMergedMcpServers(
 		}
 
 		if (result.value.mcpServers === undefined) continue;
-		if (!isRecord(result.value.mcpServers)) {
-			throw new McpConfigError(`"mcpServers" must be a JSON object: ${resolvedPath}`, resolvedPath);
-		}
 		for (const [name, def] of Object.entries(result.value.mcpServers)) {
 			// Align discovery with JSON semantics: inherited prototype keys are
 			// never treated as discoverable server names.
@@ -140,11 +167,13 @@ export async function loadMergedMcpServers(
 			}
 			if (source.isProject === true) projectServers.add(name);
 			setOwnRecordValue(serverOwners, name, source.isProject === true ? "project" : "user");
-			const previous = Object.hasOwn(servers, name) ? servers[name] : undefined;
-			const merged = isRecord(def) ? { ...(previous ?? {}), ...def } : { ...(previous ?? {}) };
-			setOwnRecordValue(servers, name, merged);
+			// Whole-definition precedence: a later definition replaces the same-named
+			// server entirely. Connection, credential, and exposure fields are never
+			// inherited from an earlier source, so a later URL cannot pick up an
+			// earlier authorization header (D1).
+			setOwnRecordValue(servers, name, isRecord(def) ? { ...def } : {});
 		}
 	}
 
-	return { servers, sharedServers, projectServers, serverOwners, baseConfig };
+	return { servers, sharedServers, projectServers, serverOwners, baseConfig, diagnostics };
 }

package/src/profile-resolver.ts

@@ -48,11 +48,27 @@ export class ActivationError extends Error {
 	}
 }
 
-/** Pi's built-in tool names (pi 0.85.1 `allToolNames`; not exported by the
+/** Pi's built-in tool names (pi 0.99.2 `allToolNames`; not exported by the
  *  SDK). The integration suite guards drift. Literal tool names pass through
  *  regardless — extension-provided tools are unknowable before spawn. */
 export const BUILTIN_TOOL_NAMES = ["read", "bash", "powershell", "edit", "write", "grep", "find", "ls"] as const;
 
+/** User-level, enabled MCP server names, sorted — the set a profile can
+ *  actually select via `mcps` or narrow via `mcp_tools`. Project-owned and
+ *  source-disabled servers are not usable candidates. */
+function userLevelMcpCandidates(mcpDiscovery: MergedMcpResult): string[] {
+	return Object.keys(mcpDiscovery.servers)
+		.filter((s) => {
+			const isUser =
+				Object.hasOwn(mcpDiscovery.serverOwners, s) &&
+				mcpDiscovery.serverOwners[s] === "user" &&
+				!mcpDiscovery.projectServers.has(s);
+			const isEnabled = mcpDiscovery.servers[s]?.enabled !== false;
+			return isUser && isEnabled;
+		})
+		.sort();
+}
+
 const VALID_THINKING_LEVELS = new Set(["off", "minimal", "low", "medium", "high", "xhigh", "max"]);
 
 /** Immutable, fully resolved activation set. */
@@ -182,7 +198,12 @@ function expandReferences<T>(
 	universe: readonly T[],
 	nameOf: (item: T) => string,
 	kind: string,
-	options?: { literalMustExist?: boolean; onZeroMatch?: (reference: string) => void },
+	options?: {
+		literalMustExist?: boolean;
+		onZeroMatch?: (reference: string) => void;
+		/** Custom literal-miss failure (e.g. with near-miss candidates). Throws. */
+		literalMissError?: (reference: string) => never;
+	},
 ): T[] {
 	const selected = new Map<string, T>();
 	for (const reference of references) {
@@ -204,6 +225,10 @@ function expandReferences<T>(
 				selected.set(reference, reference as T);
 				continue;
 			}
+			const missError = options?.literalMissError;
+			if (missError !== undefined) {
+				missError(reference);
+			}
 			throw new ActivationError(`unknown ${kind}: "${reference}" does not match any discovered ${kind}`);
 		}
 		selected.set(reference, item);
@@ -250,6 +275,17 @@ export async function resolveProfile(input: ResolveInput): Promise<ActivationPla
 			}
 			mcps = expandReferences(definition.mcps, input.discoveredMcpServers, (name) => name, "MCP server", {
 				onZeroMatch: (reference) => unmatched.push(`mcp:${reference}`),
+				literalMissError: (reference) => {
+					const candidates =
+						input.mcpDiscovery !== undefined
+							? userLevelMcpCandidates(input.mcpDiscovery)
+							: [...(input.discoveredMcpServers ?? [])].sort();
+					const suffix =
+						candidates.length > 0
+							? ` (usable candidates: ${candidates.join(", ")})`
+							: " (no user-level servers are discovered)";
+					throw new ActivationError(`unknown MCP server: "${reference}"${suffix}`);
+				},
 			});
 			if (input.mcpDiscovery !== undefined) {
 				const discovery = input.mcpDiscovery;
@@ -327,17 +363,9 @@ export async function resolveProfile(input: ResolveInput): Promise<ActivationPla
 		}
 
 		const mcpDiscovery = input.mcpDiscovery;
-		const usableCandidates = Object.keys(mcpDiscovery.servers)
-			.filter((s) => {
-				const isUser =
-					Object.hasOwn(mcpDiscovery.serverOwners, s) &&
-					mcpDiscovery.serverOwners[s] === "user" &&
-					!mcpDiscovery.projectServers.has(s);
-				const isEnabled = mcpDiscovery.servers[s]?.enabled !== false;
-				const isAllowedByMcps = mcps === undefined || mcps.includes(s);
-				return isUser && isEnabled && isAllowedByMcps;
-			})
-			.sort();
+		const usableCandidates = userLevelMcpCandidates(mcpDiscovery).filter(
+			(s) => mcps === undefined || mcps.includes(s),
+		);
 		const candidateMsg = usableCandidates.length > 0 ? ` (usable candidates: ${usableCandidates.join(", ")})` : "";
 
 		for (const serverKey of mcpToolKeys) {
@@ -479,6 +507,14 @@ export function buildInstanceMcpConfig(
 			mcpDiscovery.serverOwners[serverName] === "project" || mcpDiscovery.projectServers.has(serverName);
 		if (isProjectOwned) continue;
 
+		// A selected server the winning source explicitly disables fails with a
+		// fix, never a silent enablement override (D1).
+		if (mcps?.includes(serverName) === true && originalDef.enabled === false) {
+			throw new ActivationError(
+				`profile "${profileName}": selected MCP server "${serverName}" is disabled in its source configuration; enable it there or remove it from "mcps"`,
+			);
+		}
+
 		// A server explicitly selected by mcps whose definition uses a
 		// transport Pi's built-in MCP extension cannot use fails activation.
 		if (mcps?.includes(serverName) === true && originalDef.type === "sse") {
@@ -502,11 +538,14 @@ export function buildInstanceMcpConfig(
 		setOwnRecordValue(filteredServers, serverName, def);
 	}
 
-	// Unselected user-level servers are explicitly disabled.
+	// Unselected user-level servers keep their complete winning definition and
+	// are explicitly disabled. Pi validates the transport before `enabled`, so
+	// a transport-less placeholder would warn on every valid disabled server.
 	if (mcps !== undefined) {
 		for (const userName of userServers) {
 			if (mcps.includes(userName)) continue;
-			setOwnRecordValue(filteredServers, userName, { enabled: false });
+			const unselectedDef = mcpDiscovery.servers[userName] ?? {};
+			setOwnRecordValue(filteredServers, userName, { ...unselectedDef, enabled: false });
 		}
 	}
 

package/src/settings-generator.ts

@@ -48,7 +48,7 @@ import path from "node:path";
 import { buildInstanceMcpConfig, type ActivationPlan } from "./profile-resolver.ts";
 import { getInstancesRootDir } from "./workspace.ts";
 import { isRecord } from "./json-file.ts";
-import { loadMergedMcpServers } from "./mcp-config.ts";
+import { loadMergedMcpServers, type MergedMcpResult } from "./mcp-config.ts";
 import type { SkillEntry } from "./skill-registry.ts";
 
 /** A configured global package and its resolved install/local root. */
@@ -83,6 +83,9 @@ export interface GeneratedRuntime {
 	runtimeDir: string;
 	/** Environment variables for the spawned pi process. */
 	env: Record<string, string>;
+	/** Non-fatal diagnostics (e.g. malformed MCP sources skipped under an
+	 *  undeclared MCP policy). The launcher prints them on stderr. */
+	warnings: string[];
 }
 
 /** Files managed explicitly by pi-profile in runtimeDir; excluded from auto-symlinking. */
@@ -193,6 +196,32 @@ function userSkillExclusions(userSkills: unknown, agentDir: string, runtimeDir:
 	return exclusions;
 }
 
+/** Pi's built-in MCP discovery entry points (see installed Pi
+ *  `dist/extensions/mcp/index.js`, `codemode/tool.js`, `tool-search/tool.js`).
+ *  These are the tools a narrowed `tools` profile must keep reachable when an
+ *  MCP server is enabled; their identities are Pi's, not a profile field. */
+const MCP_GATEWAY_TOOL_NAMES = ["codemode", "tool_search"] as const;
+
+/** Whether the prepared effective MCP set contains at least one enabled
+ *  server (user-level snapshot entries with `enabled !== false`, plus any
+ *  enabled trusted-project server Pi reads itself). */
+function hasEnabledMcpServer(
+	instanceMcpConfig: Record<string, unknown>,
+	discovery: MergedMcpResult,
+): boolean {
+	const snapshotServers = instanceMcpConfig.mcpServers;
+	if (isRecord(snapshotServers)) {
+		for (const def of Object.values(snapshotServers)) {
+			if (isRecord(def) && def.enabled !== false) return true;
+		}
+	}
+	for (const name of discovery.projectServers) {
+		const def = discovery.servers[name];
+		if (def !== undefined && def.enabled !== false) return true;
+	}
+	return false;
+}
+
 function buildSelectionSettings(
 	plan: ActivationPlan,
 	userSettings: Record<string, unknown>,
@@ -405,14 +434,47 @@ export interface ResolvedNames {
 /** Writes settings.json + pi-profile.json into an existing runtime dir and
  *  keeps the trust.json link in place for every profile: Pi reads its
  *  project-scope decision from that path, and project-level resources belong
- *  to Pi's trust gate rather than to the profile. */
+ *  to Pi's trust gate rather than to the profile.
+ *
+ *  All generated content (settings, launch plan, MCP snapshot, diagnostics)
+ *  is prepared in memory before any runtime file is touched, so a discovery
+ *  failure can never leave a half-written runtime dir (D3). */
 export async function writeRuntimeFiles(
 	runtimeDir: string,
 	plan: ActivationPlan,
 	options: RuntimeFileOptions,
-): Promise<void> {
+): Promise<{ warnings: string[] }> {
+	const warnings: string[] = [];
 	const settings = await computeSettings(plan, options, runtimeDir);
-	await writeFile(path.join(runtimeDir, "settings.json"), `${JSON.stringify(settings, null, 2)}\n`);
+
+	// Prepare the MCP snapshot and diagnostics before the write stage. A
+	// declared mcps or nonempty mcp_tools policy is strict; an undeclared
+	// policy diagnoses malformed sources by path and keeps valid ones (D2).
+	const hasMcpPolicy =
+		plan.mcps !== undefined || (plan.mcpTools !== undefined && Object.keys(plan.mcpTools).length > 0);
+	const discovery = await loadMergedMcpServers(
+		options.agentDir,
+		options.projectDir,
+		{
+			...(options.homeDir !== undefined ? { homeDir: options.homeDir } : {}),
+			invalidSource: hasMcpPolicy ? "throw" : "diagnose",
+		},
+	);
+	warnings.push(...(discovery.diagnostics ?? []));
+	const instanceMcpConfig = buildInstanceMcpConfig(plan.profile, discovery, plan.mcps, plan.mcpTools);
+
+	// When a profile narrows `tools` and the effective MCP set still has an
+	// enabled server, keep Pi's native MCP discovery entry points reachable
+	// (D4). The marker drives the session-start preservation; the
+	// defaultTools baseline covers the boot window before session_start.
+	const mcpGateways = plan.tools !== undefined && hasEnabledMcpServer(instanceMcpConfig, discovery);
+	if (mcpGateways) {
+		const current = Array.isArray(settings.defaultTools) ? (settings.defaultTools as string[]) : [];
+		settings.defaultTools = [
+			...current,
+			...MCP_GATEWAY_TOOL_NAMES.filter((name) => !current.includes(name)),
+		];
+	}
 
 	// The launch plan feeds the in-pi extension: tool re-application after
 	// reload (the tools strict allowlist), in-session switching, status
@@ -420,33 +482,31 @@ export async function writeRuntimeFiles(
 	// agentDir is the REAL agent dir — the extension needs it for trust
 	// checks, state files, and catalog reads (its own
 	// PI_CODING_AGENT_DIR points at this runtime dir).
-	await writeFile(
-		path.join(runtimeDir, "pi-profile.json"),
-		`${JSON.stringify(
-			{
-				profile: plan.profile,
-				source: plan.source,
-				agentDir: options.agentDir,
-				...(plan.tools !== undefined ? { tools: plan.tools } : {}),
-				...(plan.toolReferences !== undefined ? { toolReferences: plan.toolReferences } : {}),
-				...(plan.disabledTools !== undefined ? { disabledTools: plan.disabledTools } : {}),
-				...(plan.mcps !== undefined ? { mcps: plan.mcps } : {}),
-				...(plan.mcpTools !== undefined ? { mcpTools: plan.mcpTools } : {}),
-				// The resolved sets feed /profile status (absolute paths) and the
-				// glob-delta diff against the previous activation.
-				resolved: {
-					skills: plan.skills.map((skill) => ({ name: skill.name, filePath: skill.filePath })),
-					extensions: plan.extensions,
-				},
-				// Zero-match glob references (ADR-0009) — surfaced by /profile status
-				// so a typo'd glob is visible instead of silently selecting nothing.
-				...(plan.unmatched !== undefined ? { unmatched: plan.unmatched } : {}),
-				...options.planExtras,
-			},
-			null,
-			2,
-		)}\n`,
-	);
+	const launchPlan = {
+		profile: plan.profile,
+		source: plan.source,
+		agentDir: options.agentDir,
+		...(plan.tools !== undefined ? { tools: plan.tools } : {}),
+		...(plan.toolReferences !== undefined ? { toolReferences: plan.toolReferences } : {}),
+		...(plan.disabledTools !== undefined ? { disabledTools: plan.disabledTools } : {}),
+		...(plan.mcps !== undefined ? { mcps: plan.mcps } : {}),
+		...(plan.mcpTools !== undefined ? { mcpTools: plan.mcpTools } : {}),
+		...(mcpGateways ? { mcpGateways: true } : {}),
+		// The resolved sets feed /profile status (absolute paths) and the
+		// glob-delta diff against the previous activation.
+		resolved: {
+			skills: plan.skills.map((skill) => ({ name: skill.name, filePath: skill.filePath })),
+			extensions: plan.extensions,
+		},
+		// Zero-match glob references (ADR-0009) — surfaced by /profile status
+		// so a typo'd glob is visible instead of silently selecting nothing.
+		...(plan.unmatched !== undefined ? { unmatched: plan.unmatched } : {}),
+		...options.planExtras,
+	};
+
+	// --- write stage: all content is ready; no reads re-run here. ---
+	await writeFile(path.join(runtimeDir, "settings.json"), `${JSON.stringify(settings, null, 2)}\n`);
+	await writeFile(path.join(runtimeDir, "pi-profile.json"), `${JSON.stringify(launchPlan, null, 2)}\n`);
 
 	// Every profile gets the link, dangling allowed: Pi's stored trust decision
 	// is what makes a trusted project's resources visible, and a decision Pi
@@ -460,20 +520,11 @@ export async function writeRuntimeFiles(
 
 	// MCP Servers generation: the instance mcp.json is always a generated
 	// snapshot of the merged user-level configuration; it is never a symlink
-	// or a copy of the real agentDir file (ADR-0016).
+	// or a copy of the real agentDir file (ADR-0016). The replacement content
+	// was prepared above, so the old file is removed only once its successor
+	// is ready to write.
 	const mcpInstancePath = path.join(runtimeDir, "mcp.json");
 	try { await rm(mcpInstancePath); } catch {}
-	const discovery = await loadMergedMcpServers(
-		options.agentDir,
-		options.projectDir,
-		options.homeDir !== undefined ? { homeDir: options.homeDir } : undefined,
-	);
-	const instanceMcpConfig = buildInstanceMcpConfig(
-		plan.profile,
-		discovery,
-		plan.mcps,
-		plan.mcpTools,
-	);
 	await writeFile(mcpInstancePath, JSON.stringify(instanceMcpConfig, null, 2));
 
 	// Instructions generation (Ticket 04)
@@ -486,6 +537,8 @@ export async function writeRuntimeFiles(
 
 	// Full-fidelity symlink mirroring and dangling link cleanup (Ticket 02).
 	await syncAgentSymlinks(options.agentDir, runtimeDir);
+
+	return { warnings };
 }
 
 /**
@@ -595,12 +648,13 @@ export async function generateRuntimeDir(
 	// their switches) rewrite each other's files (ADR-0010).
 	const runtimeDir = await mkdtemp(path.join(runtimeRoot, "launch-"));
 
-	await writeRuntimeFiles(runtimeDir, plan, options);
+	const { warnings } = await writeRuntimeFiles(runtimeDir, plan, options);
 
 	return {
 		runtimeDir,
 		env: {
 			PI_CODING_AGENT_DIR: runtimeDir,
 		},
+		warnings,
 	};
 }

package/src/switching/apply-plan.ts

@@ -49,6 +49,11 @@ export interface LaunchPlanFile {
 	disabledTools?: string[];
 	mcps?: string[];
 	mcpTools?: Record<string, string[]>;
+	/** Marks a narrowed `tools` profile whose effective MCP set still has an
+	 *  enabled server; session start must retain Pi's native MCP discovery
+	 *  entry points (codemode / tool_search) if they were natively
+	 *  registered (D4). */
+	mcpGateways?: boolean;
 	switchedFrom?: string;
 	persistSelection?: boolean;
 	clearOverlay?: boolean;
@@ -99,6 +104,14 @@ export function isMcpOwnedTool(tool: {
 	return info.path === "builtin:mcp";
 }
 
+/** Pi's native MCP discovery entry points and their built-in source paths
+ *  (see installed Pi `dist/extensions/index.js`). A same-named tool from any
+ *  other source is never treated as an MCP gateway. */
+const MCP_GATEWAYS = [
+	{ name: "codemode", sourcePath: "builtin:codemode" },
+	{ name: "tool_search", sourcePath: "builtin:tool-search" },
+] as const;
+
 /** Applies the plan carried by the runtime dir's pi-profile.json. */
 export async function applyLaunchPlan(input: {
 	runtimeDir: string;
@@ -116,7 +129,7 @@ export async function applyLaunchPlan(input: {
 
 	// --- tools ---
 	const hasOverlayDisables = plan.disabledTools !== undefined && plan.disabledTools.length > 0;
-	if (plan.toolReferences !== undefined || hasOverlayDisables) {
+	if (plan.toolReferences !== undefined || hasOverlayDisables || plan.mcpGateways === true) {
 		const allTools = surface.getAllTools();
 		const mcpToolNames: string[] = [];
 		const nonMcpToolNames: string[] = [];
@@ -155,6 +168,7 @@ export async function applyLaunchPlan(input: {
 			active = allTools.map((tool) => tool.name);
 		}
 
+		const disabledSet = new Set<string>();
 		if (hasOverlayDisables) {
 			const allLiveNames = allTools.map((tool) => tool.name);
 			const { expanded: disabled, droppedLiterals: vanishedEntries } = expandToolReferences(
@@ -167,9 +181,33 @@ export async function applyLaunchPlan(input: {
 					`profile "${plan.profile}": overlay tool entries ${vanishedEntries.map((name) => JSON.stringify(name)).join(", ")} match nothing in Pi's live registry`,
 				);
 			}
-			const disabledSet = new Set(disabled);
+			for (const name of disabled) disabledSet.add(name);
 			active = active.filter((name) => !disabledSet.has(name));
 		}
+
+		// Native MCP discovery entry points stay reachable for narrowed `tools`
+		// profiles when the plan marked them (D4). Only the built-in
+		// registration counts; an explicit overlay disable still wins.
+		if (plan.mcpGateways === true) {
+			for (const gateway of MCP_GATEWAYS) {
+				if (disabledSet.has(gateway.name)) continue;
+				const registered = allTools.find((tool) => tool.name === gateway.name);
+				if (registered === undefined) {
+					warnings.push(
+						`profile "${plan.profile}": MCP entry point ${JSON.stringify(gateway.name)} is unavailable because its built-in extension did not register it`,
+					);
+					continue;
+				}
+				if (registered.sourceInfo?.path === gateway.sourcePath) {
+					if (!active.includes(gateway.name)) active.push(gateway.name);
+				} else {
+					warnings.push(
+						`profile "${plan.profile}": MCP entry point ${JSON.stringify(gateway.name)} is registered by ${registered.sourceInfo?.path ?? "an unknown source"}, not the built-in extension; it was not used as an MCP gateway`,
+					);
+				}
+			}
+		}
+
 		surface.setActiveTools(active);
 	}
 

package/src/switching/switch-profile.ts

@@ -204,22 +204,7 @@ export async function switchProfile(
 					...(previousPlan.mcps !== undefined ? { mcps: previousPlan.mcps } : {}),
 				}
 			: undefined;
-	await writeRuntimeFiles(deps.runtimeDir, resolved.plan, {
-		agentDir: deps.realAgentDir,
-		projectDir: resolved.projectDir,
-		discovery: resolved.discovery,
-		planExtras: {
-			...(isSwitch && current.profile !== undefined ? { switchedFrom: current.profile } : {}),
-			// `/profile use` persists; `/profile reload` keeps the current
-			// profile's existing persistence (launch selections stay transient).
-			persistSelection: options?.reloadCurrent === true ? current.persistSelection : true,
-			// A switch discards the previous profile's overlay; the post-reload
-			// instance drops it from the state file. Customize/reset manage the
-			// overlay directly and never set this.
-			...(options?.clearOverlay === true ? { clearOverlay: true } : {}),
-			...(previousResolved !== undefined ? { previousResolved } : {}),
-		},
-	});
+	const warnings = [...resolved.warnings];
 
 	const rollback = async (cause: string): Promise<never> => {
 		// Restore the verified snapshot and reload again — the runtime must
@@ -236,7 +221,26 @@ export async function switchProfile(
 		);
 	};
 
+	// The write-and-reload interval is one rollback boundary: a failure in any
+	// write after the first, or in reload, restores every managed file (D3).
 	try {
+		const written = await writeRuntimeFiles(deps.runtimeDir, resolved.plan, {
+			agentDir: deps.realAgentDir,
+			projectDir: resolved.projectDir,
+			discovery: resolved.discovery,
+			planExtras: {
+				...(isSwitch && current.profile !== undefined ? { switchedFrom: current.profile } : {}),
+				// `/profile use` persists; `/profile reload` keeps the current
+				// profile's existing persistence (launch selections stay transient).
+				persistSelection: options?.reloadCurrent === true ? current.persistSelection : true,
+				// A switch discards the previous profile's overlay; the post-reload
+				// instance drops it from the state file. Customize/reset manage the
+				// overlay directly and never set this.
+				...(options?.clearOverlay === true ? { clearOverlay: true } : {}),
+				...(previousResolved !== undefined ? { previousResolved } : {}),
+			},
+		});
+		warnings.push(...written.warnings);
 		await deps.reload();
 	} catch (error) {
 		await rollback(error instanceof Error ? error.message : String(error));
@@ -257,5 +261,5 @@ export async function switchProfile(
 		}
 	}
 
-	return { profile: resolved.plan.profile, warnings: resolved.warnings };
+	return { profile: resolved.plan.profile, warnings };
 }