mixdog 1.2.0 → 1.2.2

package/src/runtime/agent/orchestrator/runtime-core/plugin-mcp.mjs

@@ -1,21 +1,13 @@
 // Plugin/project MCP server discovery + normalization, and skill-file counting.
-import {
-  chmodSync,
-  closeSync,
-  existsSync,
-  fsyncSync,
-  openSync,
-  readFileSync,
-  readdirSync,
-  renameSync,
-  statSync,
-  unlinkSync,
-  writeFileSync,
-} from 'node:fs';
-import { isAbsolute, join } from 'node:path';
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { join, relative, sep } from 'node:path';
 import { clean } from './session-text.mjs';
-import { readJsonSafe } from './fs-utils.mjs';
-import { pluginManifest, pluginSkillsRoots, resolveContainedPluginPath } from '../../../shared/plugin-manifest.mjs';
+import {
+  PLUGIN_MANIFEST_FILES,
+  pluginManifest,
+  pluginSkillsRoots,
+  resolveContainedPluginPath,
+} from '../../../shared/plugin-manifest.mjs';
 import { isPlainObject } from '../../../shared/object.mjs';
 
 const MCP_TRANSPORT_FIELDS = new Set([
@@ -50,105 +42,19 @@ export function mergeMcpServerConfig(existing, next) {
   return { ...merged, ...next };
 }
 
-function readProjectMcpDocument(cwd, allowMissing = false) {
-  const path = join(cwd || '.', '.mcp.json');
-  if (!existsSync(path)) {
-    if (allowMissing) return { path, raw: { mcpServers: {} }, usesWrapper: true };
-    throw new Error(`MCP config file not found: ${path}`);
-  }
-  let raw;
-  try {
-    raw = JSON.parse(readFileSync(path, 'utf8'));
-  } catch (error) {
-    throw new Error(`cannot read ${path}: ${error?.message || String(error)}`);
-  }
-  if (!isPlainObject(raw)) throw new Error(`unexpected .mcp.json shape at ${path}`);
-  if (Object.hasOwn(raw, 'mcpServers') && !isPlainObject(raw.mcpServers)) {
-    throw new Error(`unexpected .mcp.json shape at ${path}`);
-  }
-  const usesWrapper = isPlainObject(raw.mcpServers);
-  return { path, raw, usesWrapper };
-}
-
-function writeProjectMcpDocument(path, raw) {
-  let mode = 0o644;
-  try {
-    mode = statSync(path).mode;
-  } catch {
-    /* new file */
-  }
-  const tempPath = `${path}.tmp-${process.pid}-${Date.now()}`;
-  let fd = null;
-  try {
-    fd = openSync(tempPath, 'w', mode);
-    writeFileSync(fd, `${JSON.stringify(raw, null, 2)}\n`, 'utf8');
-    fsyncSync(fd);
-    closeSync(fd);
-    fd = null;
-    chmodSync(tempPath, mode);
-    renameSync(tempPath, path);
-  } catch (error) {
-    if (fd !== null) {
-      try {
-        closeSync(fd);
-      } catch {
-        /* best effort */
-      }
-    }
-    try {
-      unlinkSync(tempPath);
-    } catch {
-      /* best effort */
-    }
-    throw error;
-  }
-}
-
-// The stored key for `key`: an exact own key first, else one that trims to it.
-function mcpEntryKey(map, key) {
-  return Object.hasOwn(map, key) ? key : Object.keys(map).find((candidate) => String(candidate || '').trim() === key);
-}
-
-export function readProjectMcpServerConfig(cwd, name) {
-  const { raw, usesWrapper } = readProjectMcpDocument(cwd);
-  const map = usesWrapper ? raw.mcpServers : raw;
-  const entryKey = mcpEntryKey(map, String(name || '').trim());
-  return entryKey && isPlainObject(map[entryKey]) ? { name: entryKey, config: { ...map[entryKey] } } : null;
-}
-
-export function saveProjectMcpServer(cwd, { originalName = '', name, config }) {
-  const { path, raw, usesWrapper } = readProjectMcpDocument(cwd, !originalName);
-  const map = usesWrapper ? raw.mcpServers : raw;
-  const target = String(name || '').trim();
-  const original = String(originalName || '').trim();
-  if (!target) throw new Error('MCP server name is required');
-  const entryKey = original ? mcpEntryKey(map, original) : null;
-  if (original && !entryKey) throw new Error(`MCP server not defined in ${path}: ${original}`);
-  if (target !== entryKey && Object.hasOwn(map, target)) {
-    throw new Error(`MCP server already exists in ${path}: ${target}`);
-  }
-  const existing = entryKey ? map[entryKey] : {};
-  if (entryKey && entryKey !== target) delete map[entryKey];
-  map[target] = mergeMcpServerConfig(existing, config);
-  writeProjectMcpDocument(path, raw);
-  return { name: target, source: 'project', path, config: { ...map[target] } };
-}
-
 // Manifest + contained-path resolution live in the shared module so skill
 // discovery and this status surface read the same roots.
 export { pluginManifest, resolveContainedPluginPath };
 
-function mcpServersMapFromJson(raw) {
-  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return null;
-  if (isPlainObject(raw.mcpServers)) return raw.mcpServers;
-  return raw;
-}
-
 function isSkillMdFile(name) {
   return /^(SKILL|skill)\.md$/i.test(name);
 }
 
-const PLUGIN_INLINE_MCP_SCRIPT = 'plugin.json';
+const PLUGIN_MANIFEST_FORMATS = {
+  '.codex-plugin/plugin.json': 'codex',
+  'plugin.json': 'mixdog',
+  '.claude-plugin/plugin.json': 'claude',
+};
 
 export function countSkillFiles(root) {
   let count = 0;
@@ -177,102 +83,283 @@ export function countSkillFiles(root) {
   return count;
 }
 
-export function discoverPluginMcp(root) {
-  const manifest = pluginManifest(root);
-  const mcp = manifest.mcpServers;
-  if (typeof mcp === 'string' && mcp.trim()) {
-    const rel = mcp.trim();
-    const abs = resolveContainedPluginPath(root, rel);
-    if (abs && existsSync(abs)) return { mcpScript: rel, mcpInline: false };
-  } else if (isPlainObject(mcp)) {
-    const keys = Object.keys(mcp).filter((k) => isPlainObject(mcp[k]));
-    if (keys.length) return { mcpScript: null, mcpInline: true };
+const MCP_STDIO_TYPES = new Set(['stdio']);
+const MCP_URL_TYPES = new Set(['http', 'streamable-http', 'sse', 'ws']);
+
+function manifestFormat(root) {
+  for (const rel of PLUGIN_MANIFEST_FILES) {
+    const path = join(root, ...rel.split('/'));
+    if (existsSync(path)) return { path, format: PLUGIN_MANIFEST_FORMATS[rel] };
   }
-  const candidates = ['.mcp.json', 'scripts/run-mcp.mjs', 'mcp/server.mjs', 'server.mjs'];
-  for (const rel of candidates) {
-    const abs = resolveContainedPluginPath(root, rel);
-    if (abs && existsSync(abs)) return { mcpScript: rel, mcpInline: false };
+  return null;
+}
+
+/** Transport a declared server asks for, inferred the way the MCP client does
+ *  when `type` is absent: `transport: "http"` or a `url` -> http, else stdio.
+ *  Null for an unrecognized explicit type. */
+export function declaredMcpTransport(config) {
+  if (config?.type !== undefined && config?.type !== null && config?.type !== '') {
+    if (typeof config.type !== 'string') return null;
+    const type = config.type.toLowerCase();
+    if (type === 'streamablehttp') return 'streamable-http';
+    return MCP_STDIO_TYPES.has(type) || MCP_URL_TYPES.has(type) ? type : null;
   }
-  return { mcpScript: null, mcpInline: false };
+  if (config?.transport === 'http') return 'http';
+  if (config?.command !== undefined) return 'stdio';
+  if (config?.url !== undefined) return 'http';
+  return 'stdio';
 }
 
-export function mcpScriptForPlugin(root) {
-  return discoverPluginMcp(root).mcpScript;
+// One server entry -> a message when it cannot be launched, else null. Messages
+// name fields and expected types only, never a configured value.
+function mcpServerProblem(config) {
+  if (!isPlainObject(config)) return 'server entry must be an object';
+  const type = declaredMcpTransport(config);
+  if (!type) return '"type" must be one of stdio, http, streamable-http, sse, ws';
+  if (MCP_STDIO_TYPES.has(type)) {
+    return typeof config.command === 'string' && config.command.trim() ? null : 'stdio server requires "command"';
+  }
+  return typeof config.url === 'string' && config.url.trim() ? null : `${type} server requires "url"`;
 }
 
-export function pluginMcpEnableScript(root, plugin = {}) {
-  if (plugin.mcpInline) return PLUGIN_INLINE_MCP_SCRIPT;
-  const fromPlugin = clean(plugin.mcpScript);
-  if (fromPlugin) return fromPlugin;
-  const discovered = discoverPluginMcp(root);
-  if (discovered.mcpInline) return PLUGIN_INLINE_MCP_SCRIPT;
-  return discovered.mcpScript || null;
+// A JSON parse failure as a location only: engines may quote the offending
+// source text, which can hold credentials.
+function jsonErrorMessage(error) {
+  const text = String(error?.message || '');
+  const lineColumn = /line (\d+) column (\d+)/.exec(text);
+  if (lineColumn) return `invalid JSON at line ${lineColumn[1]} column ${lineColumn[2]}`;
+  const position = /position (\d+)/.exec(text);
+  if (position) return `invalid JSON at position ${position[1]}`;
+  return /end of (JSON|data) input/i.test(text) ? 'invalid JSON: unexpected end of input' : 'invalid JSON';
 }
 
-function substitutePluginRootTokens(value, root) {
-  if (typeof value !== 'string') return value;
-  return value.replace(/\$\{CLAUDE_PLUGIN_ROOT\}/g, root).replace(/\$\{CODEX_PLUGIN_ROOT\}/g, root);
+function readJsonFile(path, errors) {
+  let text;
+  try {
+    text = readFileSync(path, 'utf8');
+  } catch (error) {
+    errors.push({ source: path, message: `cannot read file${error?.code ? ` (${error.code})` : ''}` });
+    return { ok: false };
+  }
+  try {
+    return { ok: true, value: JSON.parse(text) };
+  } catch (error) {
+    errors.push({ source: path, message: jsonErrorMessage(error) });
+    return { ok: false };
+  }
 }
 
-function substitutePluginRootTokensDeep(value, root) {
-  if (typeof value === 'string') return substitutePluginRootTokens(value, root);
-  if (Array.isArray(value)) return value.map((v) => substitutePluginRootTokensDeep(v, root));
-  if (value && typeof value === 'object') {
-    const out = {};
-    for (const [k, v] of Object.entries(value)) out[k] = substitutePluginRootTokensDeep(v, root);
-    return out;
+// A `{ mcpServers: {...} }` wrapper or a bare server map -> the server map.
+function mcpServerMap(doc, source, errors, where = '') {
+  if (!isPlainObject(doc)) {
+    errors.push({ source, message: `${where}MCP declaration must be an object` });
+    return null;
   }
-  return value;
+  if (!Object.hasOwn(doc, 'mcpServers')) return doc;
+  if (!isPlainObject(doc.mcpServers)) {
+    errors.push({ source, message: `${where}"mcpServers" must be an object` });
+    return null;
+  }
+  return doc.mcpServers;
 }
 
-export function normalizePluginMcpServerConfig(cfg, root) {
-  const substituted = substitutePluginRootTokensDeep(cfg, root) || {};
-  const out = { ...substituted };
-  if (typeof out.cwd === 'string' && out.cwd) {
-    out.cwd = isAbsolute(out.cwd) ? out.cwd : join(root, out.cwd);
-  } else {
-    out.cwd = root;
+function collectMcpServers(map, source, into, errors) {
+  for (const [key, config] of Object.entries(map)) {
+    const problem = mcpServerProblem(config);
+    if (problem) errors.push({ source, key, message: problem });
+    else into.set(key, { key, config, source });
   }
-  return out;
 }
 
-export function pluginRawMcpServers(root, script) {
-  const rel = clean(script);
-  if (!rel) return null;
-  if (rel === PLUGIN_INLINE_MCP_SCRIPT) {
-    const manifest = pluginManifest(root);
-    const rawServers = manifest.mcpServers;
-    if (!isPlainObject(rawServers)) {
-      throw new Error('plugin.json missing inline mcpServers object');
+function loadMcpJsonFile(path, into, errors) {
+  const read = readJsonFile(path, errors);
+  if (!read.ok) return;
+  const map = mcpServerMap(read.value, path, errors);
+  if (map) collectMcpServers(map, path, into, errors);
+}
+
+// `where` locates the manifest field (e.g. `mcpServers[1]: `); the declared
+// path itself is never echoed.
+function loadDeclaredPath(root, rel, manifestPath, into, errors, touched, where) {
+  if (typeof rel !== 'string' || !rel.trim()) {
+    errors.push({ source: manifestPath, message: `${where}MCP path must be a non-empty string` });
+    return;
+  }
+  const abs = resolveContainedPluginPath(root, rel);
+  if (!abs || rel.split(/[\\/]/).includes('..')) {
+    errors.push({ source: manifestPath, message: `${where}MCP path must be relative and stay inside the plugin root` });
+    return;
+  }
+  touched.add(abs);
+  if (!existsSync(abs)) {
+    errors.push({ source: manifestPath, message: `${where}MCP file not found` });
+    return;
+  }
+  loadMcpJsonFile(abs, into, errors);
+}
+
+function readPluginMcpDeclarations(root, touched) {
+  const errors = [];
+  const into = new Map();
+  for (const rel of PLUGIN_MANIFEST_FILES) touched.add(join(root, ...rel.split('/')));
+  const found = manifestFormat(root);
+  const mcpJson = join(root, '.mcp.json');
+  touched.add(mcpJson);
+  const hasMcpJson = existsSync(mcpJson);
+  let format = 'none';
+  if (found) format = found.format;
+  else if (hasMcpJson) format = 'claude';
+
+  if (hasMcpJson) loadMcpJsonFile(mcpJson, into, errors);
+
+  let declaredRef;
+  if (found) {
+    const read = readJsonFile(found.path, errors);
+    const declared = read.ok && isPlainObject(read.value) ? read.value.mcpServers : undefined;
+    declaredRef = declared;
+    if (declared === undefined) {
+      /* nothing declared */
+    } else if (typeof declared === 'string') {
+      loadDeclaredPath(root, declared, found.path, into, errors, touched, '"mcpServers": ');
+    } else if (Array.isArray(declared)) {
+      // Members merge in order: a path to a JSON file, or an inline server
+      // map (bare or `{ mcpServers }`-wrapped).
+      declared.forEach((entry, index) => {
+        const where = `"mcpServers"[${index}]: `;
+        if (isPlainObject(entry)) {
+          const map = mcpServerMap(entry, found.path, errors, where);
+          if (map) collectMcpServers(map, found.path, into, errors);
+        } else {
+          loadDeclaredPath(root, entry, found.path, into, errors, touched, where);
+        }
+      });
+    } else if (isPlainObject(declared)) {
+      const map = mcpServerMap(declared, found.path, errors);
+      if (map) collectMcpServers(map, found.path, into, errors);
+    } else {
+      errors.push({ source: found.path, message: '"mcpServers" must be a path, a list, or an object' });
     }
-    const keys = Object.keys(rawServers).filter((k) => isPlainObject(rawServers[k]));
-    if (!keys.length) throw new Error('plugin.json has no mcpServers');
-    return { rawServers, mcpRoot: root };
   }
-  if (!/\.json$/i.test(rel)) return null;
-  const mcpJsonPath = resolveContainedPluginPath(root, rel);
-  if (!mcpJsonPath || !existsSync(mcpJsonPath)) {
-    throw new Error(`plugin MCP manifest not found: ${join(root, rel)}`);
+  const declaredPath = typeof declaredRef === 'string' ? declaredRef : null;
+  return { format, servers: [...into.values()], errors, declaredPath };
+}
+
+// Parsed declarations per plugin root, valid while every file the parse looked
+// at (present or absent) still has the same identity, size and timestamps.
+const DECLARATION_CACHE_MAX = 256;
+const declarationCache = new Map();
+const declarationCacheStats = { hits: 0, misses: 0 };
+
+function fileStamp(path) {
+  try {
+    const st = statSync(path, { bigint: true });
+    return `${st.ino}:${st.size}:${st.mtimeNs}:${st.ctimeNs}`;
+  } catch {
+    return '-';
   }
-  const rawServers = mcpServersMapFromJson(readJsonSafe(mcpJsonPath) || {});
-  if (!isPlainObject(rawServers)) {
-    throw new Error(`plugin MCP manifest missing mcpServers object: ${mcpJsonPath}`);
+}
+
+function copyDeclarations(result) {
+  return {
+    format: result.format,
+    servers: result.servers.map((server) => ({ ...server, config: structuredClone(server.config) })),
+    errors: result.errors.map((error) => ({ ...error })),
+  };
+}
+
+/** What a plugin declares for MCP, read raw: `<root>/.mcp.json` first, then the
+ *  manifest `mcpServers` (a path, an inline object, or a list mixing both).
+ *  Later sources override earlier ones by key. Never throws for plugin
+ *  content; errors carry locations and field names, never values. Unchanged
+ *  declaration files are not parsed again. */
+export function loadPluginMcpDeclarations(root) {
+  return copyDeclarations(cachedDeclarations(root));
+}
+
+function cachedDeclarations(root) {
+  const key = String(root || '');
+  const cached = declarationCache.get(key);
+  if (cached?.signature.every(([path, stamp]) => fileStamp(path) === stamp)) {
+    declarationCacheStats.hits += 1;
+    return cached.result;
+  }
+  declarationCacheStats.misses += 1;
+  // Stamps are taken before reading, so a write racing the parse invalidates.
+  const before = new Map();
+  const result = readPluginMcpDeclarations(root, {
+    add(path) {
+      if (!before.has(path)) before.set(path, fileStamp(path));
+    },
+  });
+  declarationCache.delete(key);
+  declarationCache.set(key, { signature: [...before], result });
+  if (declarationCache.size > DECLARATION_CACHE_MAX) declarationCache.delete(declarationCache.keys().next().value);
+  return result;
+}
+
+/** Test seam: cache hit/miss counters. */
+export function pluginMcpDeclarationCacheStats() {
+  return { ...declarationCacheStats };
+}
+
+// Adapter: where the declarations live, in the shape older callers expect.
+export function discoverPluginMcp(root) {
+  const { servers, declaredPath } = cachedDeclarations(root);
+  if (!servers.length) return { mcpScript: null, mcpInline: false };
+  const inline = servers.some((s) => PLUGIN_MANIFEST_FILES.some((rel) => s.source === join(root, ...rel.split('/'))));
+  if (inline) return { mcpScript: null, mcpInline: true };
+  if (declaredPath?.trim()) {
+    const abs = resolveContainedPluginPath(root, declaredPath);
+    if (servers.some((s) => s.source === abs)) return { mcpScript: declaredPath.trim(), mcpInline: false };
   }
-  const keys = Object.keys(rawServers).filter((k) => isPlainObject(rawServers[k]));
-  if (!keys.length) throw new Error(`plugin MCP manifest has no mcpServers: ${mcpJsonPath}`);
-  return { rawServers, mcpRoot: root };
+  const mcpJson = join(root, '.mcp.json');
+  const declaredFile = servers.find((s) => s.source !== mcpJson) || servers[0];
+  return { mcpScript: relative(root, declaredFile.source).split(sep).join('/'), mcpInline: false };
 }
 
-/** Every MCP entry a plugin owns: `<serverName>` and `<serverName>--<key>`. */
-export function pluginServerMatcher(serverName) {
-  const prefix = `${serverName}--`;
-  return (name) => name === serverName || name.startsWith(prefix);
+// User intent for plugin-declared servers, stored apart from the declarations
+// as `pluginMcp[pluginId][declaredKey]`: `enabled: false`, a kept `alias`
+// name, and connection overrides layered over the declaration.
+export const PLUGIN_MCP_OVERRIDE_MAP_FIELDS = Object.freeze(['env', 'headers', 'env_http_headers']);
+export const PLUGIN_MCP_OVERRIDE_VALUE_FIELDS = Object.freeze([
+  'command',
+  'args',
+  'url',
+  'bearer_token_env_var',
+  'env_vars',
+  ...MCP_TIMEOUT_FIELD_GROUPS.flat(),
+]);
+
+function normalizePluginMcpIntent(value) {
+  if (!isPlainObject(value)) return null;
+  const out = {};
+  // `enabled: true` is kept too: it turns on a server declared `enabled: false`.
+  if (typeof value.enabled === 'boolean') out.enabled = value.enabled;
+  if (typeof value.alias === 'string' && value.alias.trim()) out.alias = value.alias.trim();
+  for (const field of PLUGIN_MCP_OVERRIDE_MAP_FIELDS) {
+    if (!isPlainObject(value[field])) continue;
+    const map = Object.fromEntries(Object.entries(value[field]).filter(([, v]) => v !== null && v !== undefined));
+    if (Object.keys(map).length) out[field] = map;
+  }
+  for (const field of PLUGIN_MCP_OVERRIDE_VALUE_FIELDS) {
+    if (value[field] !== undefined && value[field] !== null) out[field] = value[field];
+  }
+  return Object.keys(out).length ? out : null;
 }
 
-export function pluginMcpServerName(plugin = {}) {
-  const base = clean(plugin.name || plugin.title || 'plugin')
-    .toLowerCase()
-    .replace(/[^a-z0-9_.-]+/g, '-')
-    .replace(/^-+|-+$/g, '');
-  return base ? `plugin-${base}` : 'plugin-mcp';
+/** `{ [pluginId]: { [declaredKey]: intent } }` with empty records dropped. */
+export function normalizePluginMcpIntents(value) {
+  const out = {};
+  if (!isPlainObject(value)) return out;
+  for (const [pluginId, servers] of Object.entries(value)) {
+    const id = clean(pluginId);
+    if (!id || !isPlainObject(servers)) continue;
+    const kept = {};
+    for (const [key, intent] of Object.entries(servers)) {
+      const normalized = normalizePluginMcpIntent(intent);
+      if (key && normalized) kept[key] = normalized;
+    }
+    if (Object.keys(kept).length) out[id] = kept;
+  }
+  return out;
 }

package/src/runtime/agent/orchestrator/runtime-core/skill-tool-loading.mjs

@@ -2,6 +2,7 @@
 // definitions out of the eager prefix; selection never changes permission policy.
 import { deferredCatalogUnion, selectDeferredTools, toolSearchNativePayload } from './tool-catalog.mjs';
 import { preDispatchDenyForSession } from '../session/loop/pre-dispatch-deny.mjs';
+import { parseMcpToolName } from '../../../shared/tool-primitives.mjs';
 
 export function loadSkillToolDependencies(envelope, session, mode) {
   if (!envelope?.__toolEnvelope) return envelope;
@@ -15,7 +16,9 @@ export function loadSkillToolDependencies(envelope, session, mode) {
   for (const { type, value } of dependencies) {
     if (type === 'tool') names.add(value);
     else if (type === 'mcp') {
-      const matches = [...catalog.keys()].filter((name) => name.startsWith(`mcp__${value}__`));
+      const matches = [...catalog.values()]
+        .filter((tool) => parseMcpToolName(tool)?.server === value)
+        .map((tool) => tool.name);
       if (matches.length)
         matches.forEach((name) => {
           names.add(name);

package/src/runtime/agent/orchestrator/runtime-core/tool-catalog-schema.mjs

@@ -145,11 +145,32 @@ export function sortedCatalogByMeasuredUsage(catalog) {
     .map((entry) => entry.tool);
 }
 
+const IMMUTABLE_SURFACE_TOOLS = new WeakSet();
+
+function deepFreeze(value) {
+  if (value && typeof value === 'object' && !Object.isFrozen(value)) {
+    Object.freeze(value);
+    for (const key of Object.keys(value)) deepFreeze(value[key]);
+  }
+  return value;
+}
+
 export function activeToolForSurface(tool) {
   if (!tool || typeof tool !== 'object') return tool;
+  if (IMMUTABLE_SURFACE_TOOLS.has(tool)) return tool;
   return JSON.parse(JSON.stringify(tool));
 }
 
+// Clone once into a deep-frozen definition that activeToolForSurface passes
+// through without re-cloning. Safe to share: it can never be mutated in place.
+export function immutableToolForSurface(tool) {
+  if (!tool || typeof tool !== 'object') return tool;
+  if (IMMUTABLE_SURFACE_TOOLS.has(tool)) return tool;
+  const frozen = deepFreeze(JSON.parse(JSON.stringify(tool)));
+  IMMUTABLE_SURFACE_TOOLS.add(frozen);
+  return frozen;
+}
+
 export function deferredProviderMode(provider) {
   const p = clean(provider).toLowerCase();
   if (p === 'gemini') return 'manifest';

package/src/runtime/agent/orchestrator/runtime-core/tool-catalog.mjs

@@ -4,7 +4,7 @@
 import { clean } from './session-text.mjs';
 import { mergePendingDeferredToolDelta } from './deferred-tool-delta.mjs';
 import { applyInitialDeferredToolManifestToBp2, stripDeferredToolManifestBlock } from '../context/collect.mjs';
-import { getMcpServerInstructionsMap, getMcpTools } from '../mcp/client.mjs';
+import { getMcpServerInstructionsMap, getMcpTools, getMcpToolGeneration } from '../mcp/client.mjs';
 import { filterMcpToolsForSession } from './extension-scopes.mjs';
 import { isDeferredToolAvailable } from './deferred-tool-availability.mjs';
 import { isResponsesFreeformTool, toResponsesCustomTool } from '../providers/custom-tool-wire.mjs';
@@ -23,6 +23,7 @@ import {
   routeToolRank,
   sortedCatalogByMeasuredUsage,
   activeToolForSurface,
+  immutableToolForSurface,
   deferredProviderMode,
   nativeProviderFamily,
 } from './tool-catalog-schema.mjs';
@@ -464,6 +465,56 @@ export function refreshInitialDeferredMcpSurface(session, liveMcpTools) {
  */
 export function reconcileDeferredMcpToolCatalog(session, liveMcpTools) {
   if (!session || !Array.isArray(session.tools)) return null;
+  const cached = RECONCILE_STATE.get(session);
+  if (cached && reconcileStateMatches(cached, reconcileStateOf(session, liveMcpTools))) return null;
+  const result = reconcileDeferredMcpToolCatalogUncached(session, liveMcpTools);
+  RECONCILE_STATE.set(session, reconcileStateOf(session, liveMcpTools));
+  return result;
+}
+
+// Last reconciled inputs per session. A matching state means the surface that
+// reconciliation would rebuild is identical, so it is skipped outright.
+const RECONCILE_STATE = new WeakMap();
+const LIVE_CLONES = new WeakMap();
+
+function liveToolClone(tool) {
+  if (!tool || typeof tool !== 'object') return tool;
+  const generation = getMcpToolGeneration();
+  const hit = LIVE_CLONES.get(tool);
+  if (hit && hit.generation === generation) return hit.clone;
+  const clone = immutableToolForSurface(tool);
+  LIVE_CLONES.set(tool, { generation, clone });
+  return clone;
+}
+
+function reconcileStateOf(session, liveMcpTools) {
+  return {
+    generation: getMcpToolGeneration(),
+    live: Array.isArray(liveMcpTools) ? liveMcpTools.slice() : [],
+    tools: session.tools.slice(),
+    lateCatalog: session.deferredLateToolCatalog,
+    scope: clean(session.mcpScopeId),
+    cwd: clean(session.cwd),
+    mode: clean(session.deferredSurfaceMode),
+    providerMode: clean(session.deferredProviderMode),
+    provider: clean(session.provider),
+    model: clean(session.model),
+    disallowed: JSON.stringify(session.disallowedTools || []),
+    callable: JSON.stringify(parseToolSelection(session.deferredCallableTools)),
+    discovered: JSON.stringify(parseToolSelection(session.deferredDiscoveredTools)),
+  };
+}
+
+function reconcileStateMatches(a, b) {
+  for (const key of Object.keys(a)) {
+    if (key === 'live' || key === 'tools') {
+      if (a[key].length !== b[key].length || a[key].some((tool, i) => tool !== b[key][i])) return false;
+    } else if (a[key] !== b[key]) return false;
+  }
+  return true;
+}
+
+function reconcileDeferredMcpToolCatalogUncached(session, liveMcpTools) {
   const live = filterDisallowedTools(Array.isArray(liveMcpTools) ? liveMcpTools : [], session.disallowedTools);
   const hadSnapshot = Array.isArray(session.deferredMcpToolNames);
   const previousNames = new Set(
@@ -482,7 +533,7 @@ export function reconcileDeferredMcpToolCatalog(session, liveMcpTools) {
     }
     for (const tool of live) {
       const name = clean(tool?.name);
-      if (name && isMcpToolName(name)) byName.set(name, activeToolForSurface(tool));
+      if (name && isMcpToolName(name)) byName.set(name, liveToolClone(tool));
     }
     const catalog = sortedCatalogByMeasuredUsage([...byName.values()]);
     const next = catalog.filter((tool) => session.deferredSurfaceMode !== 'readonly' || isReadonlySelectable(tool));
@@ -505,7 +556,7 @@ export function reconcileDeferredMcpToolCatalog(session, liveMcpTools) {
   for (const tool of live) {
     const name = clean(tool?.name);
     if (!name || !isMcpToolName(name) || liveMcpByName.has(name)) continue;
-    liveMcpByName.set(name, activeToolForSurface(tool));
+    liveMcpByName.set(name, liveToolClone(tool));
   }
 
   // Rebuild the LATE pool only (boot catalog stays frozen). It holds live MCP