mixdog 1.2.2 → 1.2.4

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

@@ -3,10 +3,11 @@
 // application/selection logic. Pure module (session objects passed in).
 import { clean } from './session-text.mjs';
 import { mergePendingDeferredToolDelta } from './deferred-tool-delta.mjs';
-import { applyInitialDeferredToolManifestToBp2, stripDeferredToolManifestBlock } from '../context/collect.mjs';
+import { applyInitialDeferredToolManifestToBp2 } from '../context/collect.mjs';
 import { getMcpServerInstructionsMap, getMcpTools, getMcpToolGeneration } from '../mcp/client.mjs';
 import { filterMcpToolsForSession } from './extension-scopes.mjs';
-import { isDeferredToolAvailable } from './deferred-tool-availability.mjs';
+import { isDeferredToolAvailable, isToolPermittedBySessionPolicy } from './deferred-tool-availability.mjs';
+import { routeToolExclusionReason } from '../session/loop/provider-tool-exclusions.mjs';
 import { isResponsesFreeformTool, toResponsesCustomTool } from '../providers/custom-tool-wire.mjs';
 import {
   DEFERRED_DEFAULT_FULL_TOOLS,
@@ -28,6 +29,17 @@ import {
   nativeProviderFamily,
 } from './tool-catalog-schema.mjs';
 import { filterModelEditTools } from '../../../shared/edit-tool-dialect.mjs';
+import { describeBridgeTools, formatBridgeResult, isBridgeReadonlySession } from './tool-bridge.mjs';
+import {
+  bridgeSurfaceOutdated,
+  isBridgeToolDefinition,
+  isToolBridgeEnabled,
+  sessionToolExposure,
+  TOOL_EXPOSURE_BRIDGE,
+  TOOL_EXPOSURE_NATIVE,
+  toolExposureModeForProvider,
+} from './tool-exposure.mjs';
+import { TOOL_BRIDGE_TOOLS } from './tool-defs.mjs';
 export {
   toolKind,
   toolSchemaBucket,
@@ -44,9 +56,30 @@ export {
   MEASURED_TOOL_USAGE,
 } from './tool-catalog-data.mjs';
 
-// Provider modes whose whole catalog is the active surface (no deferred pool).
+// Provider modes without native tool search. Their bridge-v1 sessions
+// (tool-exposure.mjs) get the native roster and late delta notices; only a
+// surface not yet migrated to the bridge keeps the fixed full array, with no
+// deferred-pool manifest and no late announcements.
 const FIXED_SURFACE_MODES = new Set(['full', 'manifest', 'canonical']);
 
+function fixedSurfaceSession(session) {
+  return FIXED_SURFACE_MODES.has(session?.deferredProviderMode) && !isToolBridgeEnabled(session);
+}
+
+// Whether a bridge session's roster and delta notices may name `tool`: only
+// what its own policy (allowlist, denied tools, read-only mode) lets it run.
+// Native rosters are unchanged.
+function rosterPermits(session, tool) {
+  if (!isToolBridgeEnabled(session)) return true;
+  if (!isToolPermittedBySessionPolicy(session, clean(tool?.name))) return false;
+  return !(isBridgeReadonlySession(session) && !isReadonlySelectable(tool));
+}
+
+// The bridge definitions every bridge session serializes: one frozen copy, so
+// their bytes never vary across search, describe, call, skill loading or MCP
+// connect/reconnect.
+const BRIDGE_SURFACE_TOOLS = TOOL_BRIDGE_TOOLS.map((tool) => immutableToolForSurface(tool));
+
 function isMcpToolName(name) {
   return typeof name === 'string' && name.startsWith('mcp__');
 }
@@ -73,6 +106,30 @@ export function filterDisallowedTools(tools, disallowed = []) {
   return (tools || []).filter((tool) => !deny.has(clean(tool?.name)));
 }
 
+/**
+ * Discovery's view of `tools` for one session: what its own policy (schema
+ * allowlist + denied tools) lets it execute. Nothing outside it is selected,
+ * registered as discovered, described or named in a result.
+ */
+export function filterSessionToolPolicy(tools, session) {
+  return filterDisallowedTools(tools, session?.disallowedTools).filter((tool) =>
+    isToolPermittedBySessionPolicy(session, clean(tool?.name))
+  );
+}
+
+// Predicate over tool names: false for a tool the session's route leaves out
+// of every request (see routeToolExclusionReason).
+function sentOnRoute(session, catalog) {
+  const byName = new Map();
+  for (const tool of [...(catalog || []), ...(Array.isArray(session?.tools) ? session.tools : [])]) {
+    byName.set(clean(tool?.name), tool);
+  }
+  return (name) => !routeToolExclusionReason(session, byName.get(name));
+}
+
+const permittedNames = (session, names) =>
+  (names || []).filter((name) => isToolPermittedBySessionPolicy(session, name));
+
 export function sortedNamesByMeasuredUsage(names) {
   // Canonical route order first; measured usage orders the unrouted tail.
   return [...(names || [])].sort((a, b) => {
@@ -236,7 +293,7 @@ function setDeferredToolState(session, names) {
 }
 
 function deferredPoolToolNames(session) {
-  if (!session || FIXED_SURFACE_MODES.has(session.deferredProviderMode)) return [];
+  if (!session || fixedSurfaceSession(session)) return [];
   const catalog = Array.isArray(session.deferredToolCatalog) ? session.deferredToolCatalog : [];
   const active = new Set([
     ...(session.tools || []).map((tool) => clean(tool?.name)).filter(Boolean),
@@ -245,7 +302,7 @@ function deferredPoolToolNames(session) {
   const out = [];
   for (const tool of catalog) {
     const name = clean(tool?.name);
-    if (name && !active.has(name)) out.push(name);
+    if (name && !active.has(name) && rosterPermits(session, tool)) out.push(name);
   }
   return sortedNamesByMeasuredUsage(out);
 }
@@ -288,13 +345,37 @@ export function isReadonlySelectable(tool) {
 
 export function applyDeferredToolSurface(session, mode, extraTools = [], options = {}) {
   if (!session || !Array.isArray(session.tools)) return session;
-  const providerMode = deferredProviderMode(options.provider || session.provider);
+  const provider = options.provider || session.provider;
+  // The pinned wire route decides a gateway's mode (it names its own
+  // provider, so a surface built for another provider ignores it).
+  const providerMode = deferredProviderMode(provider, session.wireRoute);
+  const exposure = toolExposureModeForProvider(provider, session.wireRoute);
+  const bridge = exposure === TOOL_EXPOSURE_BRIDGE;
+  // An existing surface built for another exposure is migrated, not merely
+  // re-selected: its fixed prompt guidance changes with it.
+  const previousExposure = sessionToolExposure(session);
+  // A surface an earlier bridge revision built (guidance-only prompt,
+  // search_tools) is rebuilt once, the same rewrite an exposure change makes.
+  const exposureChanged =
+    previousExposure !== null && (previousExposure !== exposure || (bridge && bridgeSurfaceOutdated(session)));
+  // The one native ↔ bridge transition, whoever triggers it (provider switch,
+  // resume, request boundary): leaving native keeps its discoveries aside,
+  // and the way back to native restores them below.
+  if (previousExposure === TOOL_EXPOSURE_NATIVE && bridge) {
+    session.nativeDeferredDiscovery = canonicalDeferredToolNames(
+      deferredCatalogUnion(session),
+      session.deferredDiscoveredTools || []
+    );
+  }
   const byName = new Map();
   // Rebuild from the full catalog, not just its eager projection. Current
-  // definitions still take precedence over retained definitions.
+  // definitions still take precedence over retained definitions. Bridge
+  // definitions belong to the exposure, never to the catalog.
   const candidates = filterDisallowedTools(
     filterModelEditTools(
-      [...session.tools, ...(extraTools || []), ...deferredCatalogUnion(session)],
+      [...session.tools, ...(extraTools || []), ...deferredCatalogUnion(session)].filter(
+        (tool) => !isBridgeToolDefinition(tool)
+      ),
       options.model || session.model
     ),
     [...(session.disallowedTools || []), ...(options.disallowed || [])]
@@ -308,15 +389,12 @@ export function applyDeferredToolSurface(session, mode, extraTools = [], options
   const defaultNames = defaultDeferredToolNames(catalog, mode);
   // Solo keeps `agent` in the deferred pool: loadable on request, never eager.
   if (session.orchestrationMode === 'none') defaultNames.delete('agent');
-  const storedNames = providerMode === 'native' ? [] : storedDeferredToolNames(session);
-  const fixedSurface = FIXED_SURFACE_MODES.has(providerMode);
-  let selectedNames = fixedSurface
-    ? sortedNamesByMeasuredUsage(catalog.map((tool) => clean(tool?.name)).filter(Boolean))
-    : [];
-  if (!fixedSurface) {
-    selectedNames = storedNames.length ? canonicalDeferredToolNames(catalog, storedNames) : [];
-    if (!selectedNames.length || providerMode === 'native') selectedNames = sortedNamesByMeasuredUsage(defaultNames);
-  }
+  // Bridge sessions expose the mode's core only: a stored (legacy all-selected)
+  // selection never widens the wire surface, and load_tool is the bridge's own.
+  const storedNames = providerMode === 'native' || bridge ? [] : storedDeferredToolNames(session);
+  let selectedNames = storedNames.length ? canonicalDeferredToolNames(catalog, storedNames) : [];
+  if (!selectedNames.length || providerMode === 'native') selectedNames = sortedNamesByMeasuredUsage(defaultNames);
+  if (bridge) selectedNames = selectedNames.filter((name) => name !== 'load_tool');
   const selected = new Set(selectedNames);
   session.deferredToolCatalog = catalog;
   session.deferredToolUsage = MEASURED_TOOL_USAGE;
@@ -332,14 +410,29 @@ export function applyDeferredToolSurface(session, mode, extraTools = [], options
     session.tools.push(tool);
     active.push(clean(tool?.name));
   }
+  // Every other definition stays in the scoped catalog, reached through the
+  // bridge. A tool-free session (empty catalog) stays tool-free.
+  if (bridge && catalog.length) session.tools.push(...BRIDGE_SURFACE_TOOLS);
+  if (bridge) session.toolExposureMode = TOOL_EXPOSURE_BRIDGE;
+  else delete session.toolExposureMode;
   session.deferredCallableTools = sortedNamesByMeasuredUsage(active);
   if (providerMode === 'native') {
-    const discovered = canonicalDeferredToolNames(catalog, session.deferredDiscoveredTools || []);
+    const restored = previousExposure === TOOL_EXPOSURE_BRIDGE ? session.nativeDeferredDiscovery || [] : [];
+    delete session.nativeDeferredDiscovery;
+    const discovered = canonicalDeferredToolNames(catalog, [...(session.deferredDiscoveredTools || []), ...restored]);
     session.deferredSelectedTools = active;
     session.deferredDiscoveredTools = discovered.filter((name) => !selected.has(name));
   } else {
     setDeferredToolState(session, active);
   }
+  if (exposureChanged && session.messages?.some((m) => m?.role === 'system')) {
+    // Replace the previous exposure's fixed block once: the native deferred
+    // manifest, or the bridge roster + guidance. History stays as is.
+    session.mcpServerInstructions = getMcpServerInstructionsMap(session.mcpScopeId);
+    applyInitialDeferredToolManifestToBp2(session, deferredPoolToolNames(session), { rebuild: true });
+    const rendered = renderedDeferredManifest(session);
+    session.deferredAnnouncedTools = deferredPoolToolNames(session).filter((name) => rendered.includes(name));
+  }
   if (!session.deferredToolBp2Applied && session.messages?.some((m) => m?.role === 'system')) {
     if (!session.mcpServerInstructions || typeof session.mcpServerInstructions !== 'object') {
       session.mcpServerInstructions = getMcpServerInstructionsMap(session.mcpScopeId);
@@ -358,41 +451,33 @@ export function applyDeferredToolSurface(session, mode, extraTools = [], options
 
 export function rebuildDeferredToolSurfaceForProvider(session, provider) {
   if (!session || !Array.isArray(session.tools)) return session;
-  const previousMode = session.deferredProviderMode;
-  const previousFamily = nativeProviderFamily(session.provider);
-  const nextFamily = nativeProviderFamily(provider);
+  const previousFamily = nativeProviderFamily(session.provider, session.wireRoute);
+  const nextFamily = nativeProviderFamily(provider, session.wireRoute);
   const preserveNativeState = previousFamily && previousFamily === nextFamily;
   const discovered = preserveNativeState
     ? canonicalDeferredToolNames(deferredCatalogUnion(session), session.deferredDiscoveredTools || [])
     : [];
   const catalog = deferredCatalogUnion(session).slice();
-  session.deferredDiscoveredTools = discovered;
+  const fromBridge = isToolBridgeEnabled(session);
+  // Another native family starts without this family's discoveries. Leaving
+  // native for the bridge keeps them: applyDeferredToolSurface sets them aside.
+  if (nextFamily) session.deferredDiscoveredTools = discovered;
+  // applyDeferredToolSurface replaces the fixed guidance when the exposure
+  // (native ↔ bridge) changes.
   applyDeferredToolSurface(session, session.deferredSurfaceMode || 'lead', catalog, { provider });
-  if (session.deferredProviderMode === 'native' && discovered.length) {
-    session.deferredDiscoveredTools = discovered;
+  // Back from the bridge: the discoveries applyDeferredToolSurface restored
+  // become callable again. Otherwise exactly the native family's own.
+  const eager = new Set(session.tools.map((tool) => clean(tool?.name)));
+  const kept = fromBridge
+    ? sortedNamesByMeasuredUsage((session.deferredDiscoveredTools || []).filter((name) => !eager.has(name)))
+    : discovered;
+  if (session.deferredProviderMode === 'native' && kept.length) {
+    session.deferredDiscoveredTools = kept;
     session.deferredCallableTools = sortedNamesByMeasuredUsage(
-      new Set([...(session.deferredCallableTools || []), ...discovered])
+      new Set([...(session.deferredCallableTools || []), ...kept])
     );
     session.deferredSelectedTools = session.deferredCallableTools.slice();
   }
-  if (previousMode && previousMode !== session.deferredProviderMode) {
-    if (session.deferredProviderMode === 'native') {
-      session.mcpServerInstructions = getMcpServerInstructionsMap(session.mcpScopeId);
-      applyInitialDeferredToolManifestToBp2(session, deferredPoolToolNames(session), { rebuild: true });
-      const rendered = renderedDeferredManifest(session);
-      session.deferredAnnouncedTools = deferredPoolToolNames(session).filter((name) => rendered.includes(name));
-    } else if (previousMode === 'native') {
-      for (const system of session.messages?.filter((message) => message?.role === 'system') || []) {
-        if (typeof system.content === 'string') system.content = stripDeferredToolManifestBlock(system.content);
-      }
-      session.messages = session.messages.filter(
-        (message) => message?.role !== 'system' || String(message.content || '').trim()
-      );
-      session.deferredAnnouncedTools = [];
-      session.deferredToolBp2Applied = true;
-      delete session.deferredToolBp1Applied;
-    }
-  }
   return session;
 }
 
@@ -400,9 +485,9 @@ export function rebuildDeferredToolSurfaceForProvider(session, provider) {
 // An MCP server may finish its handshake BETWEEN session-create and the first
 // user send. Fold those LIVE MCP tools into the boot deferred catalog + the
 // provider-visible first-turn surface. Native providers rebuild the initial BP2
-// <available-deferred-tools> manifest IN PLACE and pre-mark names announced.
-// Manifest/canonical providers update their active fixed surface directly; the
-// canonical path never emits a deferred manifest or late reminder. Fully sync
+// <available-deferred-tools> manifest IN PLACE and pre-mark names announced;
+// bridge-v1 sessions do the same (roster + bridge guidance). Only a fixed
+// surface not yet on the bridge updates its scoped catalog alone. Fully sync
 // and idempotent: no genuinely-new MCP name => no-op / no mutation.
 export function refreshInitialDeferredMcpSurface(session, liveMcpTools) {
   if (!session || !Array.isArray(session.messages)) return false;
@@ -422,15 +507,7 @@ export function refreshInitialDeferredMcpSurface(session, liveMcpTools) {
   }
   if (!added) return false;
   session.deferredToolCatalog = sortedCatalogByMeasuredUsage([...byName.values()]);
-  if (session.deferredProviderMode === 'manifest' || session.deferredProviderMode === 'canonical') {
-    const next = session.deferredToolCatalog.filter(
-      (tool) => session.deferredSurfaceMode !== 'readonly' || isReadonlySelectable(tool)
-    );
-    session.tools.splice(0, session.tools.length, ...next);
-    session.deferredCallableTools = next.map((tool) => clean(tool?.name)).filter(Boolean);
-    if (session.deferredProviderMode === 'canonical') {
-      setDeferredToolState(session, session.deferredCallableTools);
-    }
+  if (fixedSurfaceSession(session)) {
     session.updatedAt = Date.now();
     return true;
   }
@@ -497,6 +574,7 @@ function reconcileStateOf(session, liveMcpTools) {
     cwd: clean(session.cwd),
     mode: clean(session.deferredSurfaceMode),
     providerMode: clean(session.deferredProviderMode),
+    exposure: clean(session.toolExposureMode),
     provider: clean(session.provider),
     model: clean(session.model),
     disallowed: JSON.stringify(session.disallowedTools || []),
@@ -525,7 +603,7 @@ function reconcileDeferredMcpToolCatalogUncached(session, liveMcpTools) {
           .filter(isMcpToolName)
   );
   session.deferredMcpToolNames = [...new Set(live.map((tool) => clean(tool?.name)).filter(isMcpToolName))];
-  if (FIXED_SURFACE_MODES.has(session.deferredProviderMode)) {
+  if (fixedSurfaceSession(session)) {
     const byName = new Map();
     for (const tool of Array.isArray(session.deferredToolCatalog) ? session.deferredToolCatalog : []) {
       const name = clean(tool?.name);
@@ -535,17 +613,23 @@ function reconcileDeferredMcpToolCatalogUncached(session, liveMcpTools) {
       const name = clean(tool?.name);
       if (name && isMcpToolName(name)) byName.set(name, liveToolClone(tool));
     }
+    // A fixed surface not yet on the bridge: connect, reconnect and removal
+    // update the scoped catalog only (availability follows
+    // deferredMcpToolNames); nothing is announced.
     const catalog = sortedCatalogByMeasuredUsage([...byName.values()]);
-    const next = catalog.filter((tool) => session.deferredSurfaceMode !== 'readonly' || isReadonlySelectable(tool));
-    const before = JSON.stringify((session.tools || []).map((tool) => activeToolForSurface(tool)));
-    const after = JSON.stringify(next);
+    const previous = Array.isArray(session.deferredToolCatalog) ? session.deferredToolCatalog : [];
     session.deferredToolCatalog = catalog;
-    session.tools.splice(0, session.tools.length, ...next);
-    session.deferredCallableTools = next.map((tool) => clean(tool?.name)).filter(Boolean);
-    if (before !== after) session.updatedAt = Date.now();
-    return before === after ? null : session.deferredCallableTools;
+    if (previous.length !== catalog.length || previous.some((tool, index) => tool !== catalog[index])) {
+      session.updatedAt = Date.now();
+    }
+    return null;
   }
   const lateCatalog = Array.isArray(session.deferredLateToolCatalog) ? session.deferredLateToolCatalog : [];
+  // A bridge session judges a removal by the definition it had before this
+  // reconciliation (a disconnected late tool leaves the late pool below).
+  const knownBefore = isToolBridgeEnabled(session)
+    ? new Map(deferredCatalogUnion(session).map((tool) => [clean(tool?.name), tool]))
+    : null;
   const active = new Set([
     ...(session.tools || []).map((tool) => clean(tool?.name)).filter(Boolean),
     ...parseToolSelection(session.deferredCallableTools),
@@ -594,11 +678,13 @@ function reconcileDeferredMcpToolCatalogUncached(session, liveMcpTools) {
     const name = clean(tool?.name);
     if (!name || !isMcpToolName(name)) continue;
     if (previousNames.has(name) || (!hadSnapshot && (active.has(name) || startupNames.has(name)))) continue;
+    if (!rosterPermits(session, tool)) continue;
     added.push({ name, description: lateAnnouncementDescription(tool?.description) });
   }
   const removed = [];
   for (const name of previousNames) {
     if (nextNames.has(name)) continue;
+    if (knownBefore && !rosterPermits(session, knownBefore.get(name) || { name })) continue;
     removed.push(name);
   }
   if (!added.length && !removed.length) return null;
@@ -625,6 +711,9 @@ export function selectDeferredTools(session, names, mode, { exact = false } = {}
   const active = new Set([...surfaceActive, ...parseToolSelection(session?.deferredCallableTools)]);
   const native = session?.deferredProviderMode === 'native' || session?.deferredNativeTools === true;
   const discovered = new Set(Array.isArray(session?.deferredDiscoveredTools) ? session.deferredDiscoveredTools : []);
+  // Bridge sessions keep a fixed surface: deferred tools are described and
+  // run through the bridge, never appended to session.tools.
+  const bridge = isToolBridgeEnabled(session);
   const activateOnSurface = !native;
   const byName = new Map();
   for (const tool of catalog) {
@@ -645,11 +734,18 @@ export function selectDeferredTools(session, names, mode, { exact = false } = {}
       missing.push(requestedName);
       continue;
     }
+    // A tool this route never sends (schema rejected) is not loaded and not
+    // listed as active; the reason says why.
+    const routeExclusion = bridge ? null : routeToolExclusionReason(session, tool);
+    if (routeExclusion) {
+      blocked.push({ name, reason: routeExclusion });
+      continue;
+    }
     if (mode === 'readonly' && !isReadonlySelectable(tool)) {
       blocked.push({ name, reason: 'readonly mode' });
       continue;
     }
-    if (active.has(name) || (!activateOnSurface && discovered.has(name))) {
+    if (bridge || active.has(name) || (!activateOnSurface && discovered.has(name))) {
       already.push(name);
       continue;
     }
@@ -663,6 +759,7 @@ export function selectDeferredTools(session, names, mode, { exact = false } = {}
     }
     added.push(name);
   }
+  if (bridge) return { added, already, blocked, missing, native };
   if (native) {
     session.deferredCallableTools = sortedNamesByMeasuredUsage(active);
     session.deferredDiscoveredTools = sortedNamesByMeasuredUsage([...discovered]);
@@ -697,11 +794,15 @@ function pendingAndFailedMcpServers(mcpStatus) {
   return { pending: [...new Set(pending)].sort(), failed: [...new Set(failed)].sort() };
 }
 
-/** The deferred catalog union, or the session's own allowed tools when nothing is deferred. */
+/**
+ * The deferred catalog union, or the session's own tools when nothing is
+ * deferred — either way only what the session's policy lets it execute.
+ */
 function resolvableCatalog(session) {
   const union = deferredCatalogUnion(session);
-  if (union.length) return union;
-  return filterDisallowedTools(Array.isArray(session?.tools) ? session.tools : [], session?.disallowedTools);
+  let tools = union;
+  if (!union.length) tools = Array.isArray(session?.tools) ? session.tools : [];
+  return filterSessionToolPolicy(tools, session);
 }
 
 // Pure loader. Input is exact deferred-tool names/aliases; output reports
@@ -709,6 +810,8 @@ function resolvableCatalog(session) {
 // servers. No listing, no ranking, no substring filter. `options.mcpStatus` is
 // the runtime getter for per-server status.
 export function renderToolSearch(args = {}, session, mode = 'full', options = {}) {
+  // Bridge mode: load_tool describes (bounded, paged) and never loads.
+  if (isToolBridgeEnabled(session)) return formatBridgeResult(describeBridgeTools(session, args, { mode }));
   const catalog = resolvableCatalog(session);
   const requestedNames = parseToolSelection(args.names);
   const { pending: pendingMcpServers, failed: failedMcpServers } = pendingAndFailedMcpServers(options?.mcpStatus);
@@ -729,9 +832,11 @@ export function renderToolSearch(args = {}, session, mode = 'full', options = {}
         missing: [],
         ...mcpFields,
         activeTools: sortedNamesByMeasuredUsage(
-          (session?.tools || []).map((tool) => clean(tool?.name)).filter(Boolean)
+          permittedNames(session, (session?.tools || []).map((tool) => clean(tool?.name)).filter(Boolean)).filter(
+            sentOnRoute(session, catalog)
+          )
         ),
-        discoveredTools: sortedNamesByMeasuredUsage(session?.deferredDiscoveredTools || []),
+        discoveredTools: sortedNamesByMeasuredUsage(permittedNames(session, session?.deferredDiscoveredTools)),
       },
       null,
       2
@@ -789,9 +894,11 @@ export function renderToolSearch(args = {}, session, mode = 'full', options = {}
       ...(blocked.length ? { blocked } : {}),
       ...mcpFields,
       activeTools: sortedNamesByMeasuredUsage(
-        [...nextActiveNames].filter((name) => isDeferredToolAvailable(session, name))
+        permittedNames(session, [...nextActiveNames])
+          .filter((name) => isDeferredToolAvailable(session, name))
+          .filter(sentOnRoute(session, catalog))
       ),
-      discoveredTools: sortedNamesByMeasuredUsage(session?.deferredDiscoveredTools || []),
+      discoveredTools: sortedNamesByMeasuredUsage(permittedNames(session, session?.deferredDiscoveredTools)),
       ...(notes.length ? { note: notes.join(' ') } : {}),
     },
     null,

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

@@ -2,6 +2,10 @@
 // Pure, self-contained schemas + the agent-hidden default helper; no runtime
 // closure dependencies.
 
+// One load_tool for every session, native and bridge, byte for byte: native
+// sessions register the named tools; bridge sessions (see tool-bridge.mjs)
+// get their definitions back and run them through call_tool. Native request
+// bytes must never change, so the bridge adds nothing to this definition.
 export const TOOL_SEARCH_TOOL = {
   name: 'load_tool',
   title: 'load_tool',
@@ -27,34 +31,118 @@ export const TOOL_SEARCH_TOOL = {
   },
 };
 
-export const CWD_TOOL = {
-  name: 'cwd',
-  title: 'Project',
+// Fixed tool bridge for non-native providers (see tool-bridge.mjs). The
+// description is static so the definition stays byte-stable: it never carries
+// catalog names, counts or listings.
+export const CALL_TOOL_TOOL = {
+  name: 'call_tool',
+  title: 'call_tool',
   annotations: {
-    title: 'Project',
+    title: 'call_tool',
     readOnlyHint: false,
-    destructiveHint: false,
+    destructiveHint: true,
+    idempotentHint: false,
+    openWorldHint: true,
+    agentHidden: true,
+  },
+  description:
+    'Run one tool that is available in this session but not directly exposed, with the arguments its schema requires. The call has the same permissions, approvals and result as calling that tool directly.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      name: { type: 'string', minLength: 1, maxLength: 256, description: 'Exact tool name.' },
+      arguments: { type: 'object', description: 'Arguments for that tool.' },
+    },
+    required: ['name', 'arguments'],
+    additionalProperties: false,
+  },
+};
+
+// The fixed bridge for non-native providers: the shared load_tool plus call_tool.
+export const TOOL_BRIDGE_TOOLS = Object.freeze([TOOL_SEARCH_TOOL, CALL_TOOL_TOOL]);
+
+export const SESSION_TOOL = {
+  name: 'session',
+  title: 'Session',
+  annotations: {
+    title: 'Session',
+    readOnlyHint: false,
+    destructiveHint: true,
     idempotentHint: false,
     openWorldHint: false,
     agentHidden: true,
   },
-  trigger: 'Show or switch the active Project; not a shell-local cd.',
+  trigger: 'Session lookup/control, title, compact, fork, Project and worktrees.',
   description:
-    'Show or switch the active Project. list returns the registered projects (name, path); a project name instead of a path → list first, then set the matching path, ask only if several match. path must be an existing directory. A shell-local cd does not change the Project. merge-worktree / remove-worktree act on this session’s git worktree only when the user explicitly asks.',
+    'Inspect sessions or control another by exact ID, never a guessed one. send acknowledges queue intake, not completion. Cancel/delete and worktree actions require the user’s request. Other actions affect only the current session.',
   inputSchema: {
     type: 'object',
     properties: {
       action: {
         type: 'string',
-        enum: ['get', 'set', 'list', 'merge-worktree', 'remove-worktree', 'list-worktrees', 'prune-worktrees'],
+        enum: [
+          'status',
+          'list',
+          'read',
+          'send',
+          'cancel',
+          'delete',
+          'rename',
+          'compact',
+          'fork',
+          'set-project',
+          'list-projects',
+          'favorite',
+          'archive',
+          'merge-worktree',
+          'remove-worktree',
+          'list-worktrees',
+          'prune-worktrees',
+        ],
+        description:
+          'status defaults to current; list pages sessions; read returns latest items; send queues prompt; cancel stops the turn; delete removes the session. compact runs after this turn; fork copies it without switching. merge-worktree merges into the Project’s checked-out branch; remove-worktree returns to the Project (repeat on WORKTREE_REMOVAL_INCOMPLETE); list-worktrees includes retaining sessions; prune-worktrees removes only clean, merged, unretained worktrees.',
+      },
+      title: { type: 'string', description: 'rename: new current-session title.' },
+      session_id: {
+        type: 'string',
+        description:
+          'ID from list; required for read/send/cancel/delete, optional for status. send/cancel/delete cannot target the caller.',
+      },
+      prompt: { type: 'string', description: 'send: message to enqueue; loads a cold session.' },
+      limit: {
+        type: 'integer',
+        minimum: 1,
+        maximum: 100,
+        description:
+          'list/read: maximum rows, default 25. Output: 8KiB per page, 12KiB for initial read tail; follow nextOffset/nextTextOffset for more.',
+      },
+      cursor: { type: 'string', description: 'list: returned nextCursor.' },
+      offset: {
+        type: 'integer',
+        minimum: 0,
+        description:
+          'read: newest items to skip, default 0 (tail). Use nextOffset for older pages; appends/rewinds shift positions.',
+      },
+      text_offset: {
+        type: 'integer',
+        minimum: 0,
+        description: 'read: UTF-16 text position from nextTextOffset; requires offset, limit:1, item_id.',
+      },
+      item_id: {
+        type: 'string',
+        description: 'read: returned item id; rejects a shifted position instead of reading another item.',
+      },
+      path: {
+        type: 'string',
         description:
-          'get shows the active Project (default without path), set switches to path, list returns registered projects; merge-worktree merges this session’s worktree into the project folder’s checked-out branch, remove-worktree deletes it (returning to the project folder; call again if it reports WORKTREE_REMOVAL_INCOMPLETE); list-worktrees lists every managed worktree and who retains it; prune-worktrees removes clean, merged ones no session retains.',
+          'Existing directory; implies set-project. Resolve names with list-projects first. Shell cd does not switch Project.',
       },
-      path: { type: 'string', description: 'Existing directory to switch to (implies action=set).' },
+      compact: { type: 'boolean', description: 'fork: compact the copy.' },
       force: {
         type: 'boolean',
-        description: 'remove-worktree: delete even with uncommitted or unmerged work (only when the user says so).',
+        description: 'remove-worktree: allow uncommitted/unmerged work only when explicitly requested.',
       },
+      value: { type: 'boolean', description: 'favorite/archive: on or off.' },
     },
     additionalProperties: false,
   },
@@ -121,6 +209,7 @@ export function collectStandaloneToolDefs({
   tidyToolDefs = [],
   visualizeToolDefs = [],
   setupToolDefs = [],
+  askUserToolDefs = [],
   goalTools = [],
   agentTools = [],
   skillToolEnabled = true,
@@ -129,7 +218,7 @@ export function collectStandaloneToolDefs({
   const standaloneTools = [
     TOOL_SEARCH_TOOL,
     ...(skillToolEnabled ? [SKILL_TOOL] : []),
-    CWD_TOOL,
+    SESSION_TOOL,
     ...webSearchRuntimeTools.filter((tool) => tool?.public !== false),
     ...admitted(memoryToolDefs?.TOOL_DEFS, MEMORY_RUNTIME_TOOLS),
     ...admitted(codeGraphToolDefs?.CODE_GRAPH_TOOL_DEFS, CODE_GRAPH_RUNTIME_TOOLS),
@@ -141,6 +230,7 @@ export function collectStandaloneToolDefs({
     ...admitted(tidyToolDefs, TIDY_RUNTIME_TOOLS),
     ...admitted(visualizeToolDefs, VISUALIZE_RUNTIME_TOOLS),
     ...setupToolDefs,
+    ...askUserToolDefs,
     ...goalTools,
     ...agentTools,
   ];