mixdog 0.9.51 → 0.9.53

package/src/session-runtime/tool-catalog.mjs

@@ -3,34 +3,41 @@
 // application/selection logic. Pure module (session objects passed in).
 import { clean, LATE_TOOL_ANNOUNCEMENT_SENTINEL } from './session-text.mjs';
 import { estimateToolSchemaTokens, toolSchemaSignature } from '../runtime/agent/orchestrator/session/context-utils.mjs';
-import { applyInitialDeferredToolManifestToBp1, buildDeferredToolManifest } from '../runtime/agent/orchestrator/context/collect.mjs';
+import {
+  applyInitialDeferredToolManifestToBp1,
+  buildDeferredToolManifest,
+  stripDeferredToolManifestBlock,
+} from '../runtime/agent/orchestrator/context/collect.mjs';
 import { getMcpServerInstructionsMap } from '../runtime/agent/orchestrator/mcp/client.mjs';
 import {
   isResponsesFreeformTool,
   toResponsesCustomTool,
 } from '../runtime/agent/orchestrator/providers/custom-tool-wire.mjs';
+import {
+  finalizeProviderRequestTools,
+  providerNativeToolPrefixCount,
+} from './provider-request-tools.mjs';
+import {
+  DEFERRED_DEFAULT_FULL_TOOLS,
+  DEFERRED_DEFAULT_LEAD_TOOLS,
+  DEFERRED_DEFAULT_READONLY_TOOLS,
+  DEFERRED_SELECT_ALIASES,
+  MEASURED_TOOL_ORDER,
+  MEASURED_TOOL_USAGE,
+  READONLY_TOOL_NAMES,
+} from './tool-catalog-data.mjs';
+export {
+  DEFERRED_DEFAULT_FULL_TOOLS,
+  DEFERRED_DEFAULT_LEAD_TOOLS,
+  DEFERRED_DEFAULT_READONLY_TOOLS,
+  MEASURED_TOOL_USAGE,
+} from './tool-catalog-data.mjs';
 
-export const MEASURED_TOOL_USAGE = Object.freeze({
-  read: 710,
-  code_graph: 520,
-  grep: 500,
-  find: 480,
-  glob: 460,
-  list: 430,
-  apply_patch: 400,
-  explore: 360,
-  agent: 330,
-  shell: 81,
-  cwd: 2,
-  recall: 2,
-  search: 2,
-  web_fetch: 2,
-});
-const MEASURED_TOOL_ORDER = Object.freeze(Object.keys(MEASURED_TOOL_USAGE));
 const toolSchemaBreakdownMemo = new WeakMap();
 
 function sameToolSchemaEntries(cached, tools) {
   if (!cached || cached.entries.length !== tools.length) return false;
+  const nativePrefixCount = providerNativeToolPrefixCount(tools);
   for (let index = 0; index < tools.length; index += 1) {
     const entry = cached.entries[index];
     const tool = tools[index];
@@ -45,12 +52,17 @@ function sameToolSchemaEntries(cached, tools) {
       || entry.defer_loading !== tool?.defer_loading
       || entry.annotationsMixdogKind !== tool?.annotations?.mixdogKind
       || entry.annotationsAgentHidden !== tool?.annotations?.agentHidden
-      || entry.wireSignature !== toolSchemaSignature([tool])) return false;
+      || entry.native !== (index < nativePrefixCount)
+      || entry.wireSignature !== toolSchemaSignature(toolMeteringList(tool, index < nativePrefixCount))) return false;
   }
   return true;
 }
 
-function toolSchemaEntry(tool) {
+function toolMeteringList(tool, native) {
+  return native ? finalizeProviderRequestTools([tool], 1) : [tool];
+}
+
+function toolSchemaEntry(tool, native = false) {
   return {
     tool,
     name: tool?.name,
@@ -63,81 +75,10 @@ function toolSchemaEntry(tool) {
     defer_loading: tool?.defer_loading,
     annotationsMixdogKind: tool?.annotations?.mixdogKind,
     annotationsAgentHidden: tool?.annotations?.agentHidden,
-    wireSignature: toolSchemaSignature([tool]),
+    native,
+    wireSignature: toolSchemaSignature(toolMeteringList(tool, native)),
   };
 }
-export const DEFERRED_DEFAULT_FULL_TOOLS = Object.freeze([
-  'read',
-  'code_graph',
-  'grep',
-  'find',
-  'glob',
-  'list',
-  'explore',
-  'apply_patch',
-  'Skill',
-  'load_tool',
-]);
-export const DEFERRED_DEFAULT_READONLY_TOOLS = Object.freeze([
-  'read',
-  'code_graph',
-  'grep',
-  'find',
-  'glob',
-  'list',
-  'explore',
-  'Skill',
-  'load_tool',
-]);
-export const DEFERRED_DEFAULT_LEAD_TOOLS = Object.freeze([
-  'read',
-  'code_graph',
-  'grep',
-  'find',
-  'glob',
-  'list',
-  'shell',
-  'task',
-  'explore',
-  'apply_patch',
-  'agent',
-  'recall',
-  'search',
-  'web_fetch',
-  'cwd',
-    'session_manage',
-  'Skill',
-  'load_tool',
-]);
-const READONLY_TOOL_NAMES = new Set([
-  'read',
-  'list',
-  'grep',
-  'find',
-  'glob',
-  'code_graph',
-  'search',
-  'web_fetch',
-  'recall',
-  'memory',
-  'fetch',
-  'Skill',
-]);
-const DEFERRED_SELECT_ALIASES = {
-  filesystem: ['read', 'list', 'grep', 'find', 'glob'],
-  search: ['search', 'web_fetch'],
-  web: ['web_fetch', 'search'],
-  memory: ['memory', 'recall'],
-  channels: ['reply', 'fetch'],
-  discord: ['reply', 'fetch'],
-  explore: ['explore'],
-  discovery: ['explore'],
-  agent: ['agent'],
-  graph: ['code_graph'],
-  code: ['code_graph'],
-  shell: ['shell', 'task'],
-};
-
 export function toolKind(tool) {
   const name = clean(tool?.name);
   if (name.startsWith('mcp__')) return 'mcp';
@@ -170,14 +111,22 @@ export function estimateToolSchemaBreakdown(tools) {
     if (sameToolSchemaEntries(cached, tools)) return cached.value;
   }
   const out = {};
-  for (const tool of Array.isArray(tools) ? tools : []) {
+  const list = Array.isArray(tools) ? tools : [];
+  const nativePrefixCount = providerNativeToolPrefixCount(list);
+  for (let index = 0; index < list.length; index += 1) {
+    const tool = list[index];
     const bucket = toolSchemaBucket(tool);
     const row = out[bucket] || { count: 0, tokens: 0 };
     row.count += 1;
-    row.tokens += estimateToolSchemaTokens([tool]);
+    row.tokens += estimateToolSchemaTokens(toolMeteringList(tool, index < nativePrefixCount));
     out[bucket] = row;
   }
-  if (Array.isArray(tools)) toolSchemaBreakdownMemo.set(tools, { entries: tools.map(toolSchemaEntry), value: out });
+  if (Array.isArray(tools)) {
+    toolSchemaBreakdownMemo.set(tools, {
+      entries: tools.map((tool, index) => toolSchemaEntry(tool, index < nativePrefixCount)),
+      value: out,
+    });
+  }
   return out;
 }
 
@@ -246,6 +195,324 @@ function nativeProviderFamily(provider) {
   return '';
 }
 
+const ANTHROPIC_NATIVE_PROVIDERS = new Set(['anthropic', 'anthropic-oauth']);
+
+// Pure projection of the tool definitions that the next provider request will
+// serialize. Anthropic's native deferred surface sends the base active tools
+// plus only definitions that have actually been discovered through the
+// session/native tool-search history. Every other provider already receives
+// its canonical/native surface in `tools`, so preserve that array verbatim.
+export function resolveProviderRequestTools({
+  provider,
+  tools,
+  messages,
+  session,
+} = {}) {
+  const activeTools = Array.isArray(tools) ? tools : [];
+  const normalizedProvider = clean(provider || session?.provider).toLowerCase();
+  if (!ANTHROPIC_NATIVE_PROVIDERS.has(normalizedProvider)
+    || session?.deferredNativeTools !== true
+    || activeTools.length === 0) {
+    return activeTools;
+  }
+  const discovered = new Set(
+    parseToolSelection(session?.deferredDiscoveredTools),
+  );
+  for (const message of Array.isArray(messages) ? messages : []) {
+    const native = message?.nativeToolSearch;
+    const source = clean(native?.provider).toLowerCase();
+    if (source && source !== normalizedProvider
+      && !(ANTHROPIC_NATIVE_PROVIDERS.has(source)
+        && ANTHROPIC_NATIVE_PROVIDERS.has(normalizedProvider))) continue;
+    for (const name of parseToolSelection(native?.toolReferences)) discovered.add(name);
+  }
+  if (discovered.size === 0) return activeTools;
+  const activeNames = new Set(activeTools.map((tool) => clean(tool?.name)).filter(Boolean));
+  const catalog = Array.isArray(session?.deferredToolCatalog) ? session.deferredToolCatalog : [];
+  const deferredTools = catalog
+    .filter((tool) => {
+      const name = clean(tool?.name);
+      return name && discovered.has(name) && !activeNames.has(name);
+    })
+    .map((tool) => ({ ...tool, deferLoading: true }));
+  return deferredTools.length ? [...activeTools, ...deferredTools] : activeTools;
+}
+
+const OMIT_REQUEST_TOOL_VALUE = Symbol('omit-request-tool-value');
+const MAX_PROVIDER_SNAPSHOT_ARRAY_LENGTH = 1_000_000;
+
+function defineEnumerableDataProperty(target, key, value) {
+  Object.defineProperty(target, key, {
+    value,
+    enumerable: true,
+    configurable: false,
+    writable: false,
+  });
+}
+
+function boxedJsonPrimitive(value) {
+  try { return { matched: true, value: Number.prototype.valueOf.call(value) }; } catch {}
+  try { return { matched: true, value: String.prototype.valueOf.call(value) }; } catch {}
+  try { return { matched: true, value: Boolean.prototype.valueOf.call(value) }; } catch {}
+  try { return { matched: true, value: BigInt.prototype.valueOf.call(value) }; } catch {}
+  return { matched: false, value: null };
+}
+
+function providerSnapshotLengthPrimitive(value) {
+  if ((typeof value !== 'object' || value === null) && typeof value !== 'function') return value;
+  const exotic = value[Symbol.toPrimitive];
+  if (exotic !== undefined && exotic !== null) {
+    if (typeof exotic !== 'function') throw new TypeError('invalid length primitive');
+    const primitive = exotic.call(value, 'number');
+    if ((typeof primitive === 'object' && primitive !== null) || typeof primitive === 'function') {
+      throw new TypeError('invalid length primitive');
+    }
+    return primitive;
+  }
+  for (const methodName of ['valueOf', 'toString']) {
+    const method = value[methodName];
+    if (typeof method !== 'function') continue;
+    const primitive = method.call(value);
+    if ((typeof primitive !== 'object' || primitive === null) && typeof primitive !== 'function') {
+      return primitive;
+    }
+  }
+  throw new TypeError('invalid length primitive');
+}
+
+function providerSnapshotArrayLength(rawLength) {
+  let primitive;
+  let numeric;
+  try {
+    primitive = providerSnapshotLengthPrimitive(rawLength);
+    if (typeof primitive === 'bigint' || typeof primitive === 'symbol') {
+      throw new TypeError('invalid length primitive');
+    }
+    numeric = Number(primitive);
+  } catch {
+    throw new TypeError('provider tool snapshot: invalid array length');
+  }
+  if (Number.isNaN(numeric) || numeric <= 0) return 0;
+  if (!Number.isFinite(numeric)) {
+    throw new RangeError(
+      `provider tool snapshot: array length exceeds safe limit ${MAX_PROVIDER_SNAPSHOT_ARRAY_LENGTH}`,
+    );
+  }
+  const effectiveLength = Math.floor(numeric);
+  if (effectiveLength > MAX_PROVIDER_SNAPSHOT_ARRAY_LENGTH) {
+    throw new RangeError(
+      `provider tool snapshot: array length exceeds safe limit ${MAX_PROVIDER_SNAPSHOT_ARRAY_LENGTH}`,
+    );
+  }
+  return effectiveLength;
+}
+
+function normalizeRequestToolJson(value, state, {
+  arrayEntry = false,
+  key = '',
+  applyToJSON = true,
+  seededProperties = null,
+} = {}) {
+  if (value === null || typeof value === 'string' || typeof value === 'boolean') return value;
+  if (typeof value === 'number') return Number.isFinite(value) ? value : null;
+  if (typeof value === 'bigint') {
+    throw new TypeError('provider tool snapshot: BigInt is not JSON-serializable');
+  }
+  if (value === undefined || typeof value === 'function' || typeof value === 'symbol') {
+    return arrayEntry ? null : OMIT_REQUEST_TOOL_VALUE;
+  }
+  if (typeof value !== 'object') {
+    throw new TypeError(`provider tool snapshot: unsupported JSON value type ${typeof value}`);
+  }
+  if (state.active.has(value)) {
+    throw new TypeError('provider tool snapshot: cyclic value is not JSON-serializable');
+  }
+  if (state.memo.has(value)) return state.memo.get(value);
+
+  let capturedProperties = seededProperties;
+  if (applyToJSON) {
+    // JSON reads `toJSON` once before serializing an object. Preserve that
+    // single observation for an own-enumerable non-function (and for a
+    // callable that returns `this`) so property traversal cannot invoke a
+    // stateful accessor a second time.
+    const toJSONDescriptor = Object.getOwnPropertyDescriptor(value, 'toJSON');
+    const toJSON = value.toJSON;
+    if (typeof toJSON === 'function') {
+      // Keep the source guarded through both hook execution and replacement
+      // normalization. A hook returning itself, or any replacement graph that
+      // points back to its source, is a JSON cycle rather than another hook
+      // invocation.
+      state.active.add(value);
+      try {
+        const replacement = toJSON.call(value, key);
+        const normalized = normalizeRequestToolJson(replacement, state, {
+          arrayEntry,
+          key,
+          applyToJSON: false,
+          seededProperties: null,
+        });
+        state.memo.set(value, normalized);
+        return normalized;
+      } finally {
+        state.active.delete(value);
+      }
+    }
+    if (toJSONDescriptor?.enumerable) {
+      capturedProperties = { ...(seededProperties || {}), toJSON };
+    }
+  }
+  const boxed = boxedJsonPrimitive(value);
+  if (boxed.matched) {
+    return normalizeRequestToolJson(boxed.value, state, { arrayEntry, key });
+  }
+
+  const isArray = Array.isArray(value);
+  const normalized = isArray ? [] : {};
+  state.active.add(value);
+  try {
+    if (isArray) {
+      // JSON.stringify captures array length once. Accessors may mutate the
+      // source array, but they cannot extend or shorten this iteration bound.
+      const rawLength = value.length;
+      const length = providerSnapshotArrayLength(rawLength);
+      for (let index = 0; index < length; index += 1) {
+        const entry = value[index];
+        normalized.push(normalizeRequestToolJson(entry, state, {
+          arrayEntry: true,
+          key: String(index),
+        }));
+      }
+    } else {
+      // JSON-compatible request schemas are own-enumerable data. Normalize class
+      // instances/accessors to a plain record, ignore inherited mutable fields,
+      // and define keys explicitly so an own "__proto__" remains ordinary data.
+      for (const key of Reflect.ownKeys(value)) {
+        if (typeof key !== 'string') continue;
+        const descriptor = Object.getOwnPropertyDescriptor(value, key);
+        if (!descriptor?.enumerable) continue;
+        // Deferred catalog selection captures `name` once before touching the
+        // candidate schema. Seed that captured value here so a stateful/throwing
+        // getter is never observed a second time during JSON normalization.
+        const entry = capturedProperties && Object.hasOwn(capturedProperties, key)
+          ? capturedProperties[key]
+          : value[key];
+        const child = normalizeRequestToolJson(entry, state, { key });
+        if (child !== OMIT_REQUEST_TOOL_VALUE) defineEnumerableDataProperty(normalized, key, child);
+      }
+    }
+  } finally {
+    state.active.delete(value);
+  }
+  Object.freeze(normalized);
+  state.memo.set(value, normalized);
+  return normalized;
+}
+
+// Establish one immutable request-attempt snapshot. Nested schema records are
+// cloned before freezing, so a catalog refresh or in-place schema mutation
+// after this boundary cannot change either provider bytes or their signature.
+export function snapshotProviderRequestTools(options = {}) {
+  const {
+    provider,
+    tools,
+    nativeTools,
+    messages,
+    session,
+  } = options;
+  const activeTools = Array.isArray(tools) ? tools : [];
+  const state = { active: new WeakSet(), memo: new WeakMap() };
+  const snapshots = [];
+  const names = new Set();
+  const activeCandidateRefs = new WeakSet();
+  // Anthropic native definitions are already provider-wire objects. Preserve
+  // their prior prepend order and duplicate behavior, but freeze the exact
+  // bytes into the same request snapshot used for accounting and retries.
+  if (ANTHROPIC_NATIVE_PROVIDERS.has(clean(provider || session?.provider).toLowerCase())) {
+    for (const nativeTool of Array.isArray(nativeTools) ? nativeTools : []) {
+      if (!nativeTool || typeof nativeTool !== 'object') continue;
+      const normalized = normalizeRequestToolJson(nativeTool, state);
+      if (normalized && typeof normalized === 'object' && !Array.isArray(normalized)) {
+        snapshots.push(normalized);
+      }
+    }
+  }
+  const nativePrefixCount = snapshots.length;
+  const finish = () => finalizeProviderRequestTools(snapshots, nativePrefixCount);
+  const appendSnapshot = (candidate, selectedName = null, deferred = false) => {
+    const normalized = normalizeRequestToolJson(candidate, state, {
+      seededProperties: selectedName === null ? null : { name: selectedName },
+    });
+    if (deferred && (
+      !normalized
+      || typeof normalized !== 'object'
+      || Array.isArray(normalized)
+      || typeof normalized.name !== 'string'
+      || !clean(normalized.name)
+      || normalized.name !== selectedName
+    )) {
+      throw new TypeError(`provider tool snapshot: selected tool identity mismatch for ${JSON.stringify(selectedName)}`);
+    }
+    if (!normalized || typeof normalized !== 'object' || Array.isArray(normalized)) return;
+    const name = clean(normalized.name);
+    if (!name || names.has(name)) return;
+    names.add(name);
+    if (!deferred) {
+      snapshots.push(normalized);
+      return;
+    }
+    const deferredSnapshot = {};
+    for (const key of Object.keys(normalized)) {
+      if (key === 'deferLoading' || key === 'defer_loading') continue;
+      defineEnumerableDataProperty(deferredSnapshot, key, normalized[key]);
+    }
+    defineEnumerableDataProperty(deferredSnapshot, 'deferLoading', true);
+    snapshots.push(Object.freeze(deferredSnapshot));
+  };
+
+  // Active candidates are provider-visible by definition: normalize each once,
+  // then perform all validation/dedupe from the plain snapshot only.
+  for (const tool of activeTools) {
+    if (tool && typeof tool === 'object') activeCandidateRefs.add(tool);
+    appendSnapshot(tool);
+  }
+
+  const normalizedProvider = clean(provider || session?.provider).toLowerCase();
+  if (!ANTHROPIC_NATIVE_PROVIDERS.has(normalizedProvider)
+    || session?.deferredNativeTools !== true
+    // Native definitions preserve their historical prepend behavior, but they
+    // do not make an otherwise all-deferred catalog eligible for expansion.
+    || names.size === 0) {
+    return finish();
+  }
+  const discovered = new Set(parseToolSelection(session?.deferredDiscoveredTools));
+  for (const message of Array.isArray(messages) ? messages : []) {
+    const native = message?.nativeToolSearch;
+    const source = clean(native?.provider).toLowerCase();
+    if (source && source !== normalizedProvider
+      && !(ANTHROPIC_NATIVE_PROVIDERS.has(source)
+        && ANTHROPIC_NATIVE_PROVIDERS.has(normalizedProvider))) continue;
+    for (const name of parseToolSelection(native?.toolReferences)) discovered.add(name);
+  }
+  if (discovered.size === 0) return finish();
+
+  // Catalog arrays have no separate key map, so `name` is their explicit
+  // selection key contract: capture it once, skip undiscovered/duplicate
+  // entries without touching schemas, and seed selected normalization with the
+  // captured value to avoid a second getter evaluation.
+  const seenCatalogRefs = new WeakSet();
+  for (const tool of Array.isArray(session?.deferredToolCatalog) ? session.deferredToolCatalog : []) {
+    if (tool && typeof tool === 'object') {
+      if (activeCandidateRefs.has(tool) || seenCatalogRefs.has(tool)) continue;
+      seenCatalogRefs.add(tool);
+    }
+    const capturedName = tool?.name;
+    const selectionName = typeof capturedName === 'string' ? clean(capturedName) : '';
+    if (!selectionName || !discovered.has(selectionName) || names.has(selectionName)) continue;
+    appendSnapshot(tool, capturedName, true);
+  }
+  return finish();
+}
+
 export function filterDisallowedTools(tools, disallowed = []) {
   if (!Array.isArray(disallowed) || disallowed.length === 0) return tools;
   const deny = new Set(disallowed.map((name) => clean(name)).filter(Boolean));
@@ -510,6 +777,7 @@ 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 preserveNativeState = previousFamily && previousFamily === nextFamily;
@@ -532,21 +800,36 @@ export function rebuildDeferredToolSurfaceForProvider(session, provider) {
     ]));
     session.deferredSelectedTools = session.deferredCallableTools.slice();
   }
+  if (previousMode && previousMode !== session.deferredProviderMode) {
+    if (session.deferredProviderMode === 'native') {
+      session.mcpServerInstructions = getMcpServerInstructionsMap();
+      applyInitialDeferredToolManifestToBp1(session, deferredPoolToolNames(session), { rebuild: true });
+      const rendered = session.messages?.find((message) => message?.role === 'system')?.content;
+      session.deferredAnnouncedTools = deferredPoolToolNames(session)
+        .filter((name) => typeof rendered === 'string' && rendered.includes(name));
+    } else if (previousMode === 'native') {
+      const system = session.messages?.find((message) => message?.role === 'system');
+      if (system && typeof system.content === 'string') {
+        system.content = stripDeferredToolManifestBlock(system.content);
+      }
+      session.deferredAnnouncedTools = [];
+      session.deferredToolBp1Applied = true;
+    }
+  }
   return session;
 }
 
 // FIRST-TURN deferred-surface refresh (claude-code turn-time deferred manifest).
 // 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
-// initial BP1 <available-deferred-tools> manifest (rebuilt IN PLACE — strip +
-// reappend, never duplicated) and pre-mark them announced, so they appear in the
-// INITIAL manifest instead of arriving as a late-tool <system-reminder>. Fully
-// sync (registry read is sync, no await) and idempotent: no genuinely-new MCP
-// name => no-op / no mutation. Skipped in 'full' provider mode (all tools ship
-// active — there is no deferred manifest to refresh).
+// provider-visible first-turn surface. Native providers rebuild the initial BP1
+// <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
+// and idempotent: no genuinely-new MCP name => no-op / no mutation.
 export function refreshInitialDeferredMcpSurface(session, liveMcpTools) {
   if (!session || !Array.isArray(session.messages)) return false;
-  if (session.deferredProviderMode === 'full' || session.deferredProviderMode === 'canonical') return false;
+  if (session.deferredProviderMode === 'full') return false;
   const isMcp = (name) => typeof name === 'string' && name.startsWith('mcp__');
   const byName = new Map();
   for (const tool of Array.isArray(session.deferredToolCatalog) ? session.deferredToolCatalog : []) {
@@ -562,12 +845,15 @@ export function refreshInitialDeferredMcpSurface(session, liveMcpTools) {
   }
   if (!added) return false;
   session.deferredToolCatalog = sortedCatalogByMeasuredUsage([...byName.values()]);
-  if (session.deferredProviderMode === 'manifest') {
+  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);
+    }
     session.updatedAt = Date.now();
     return true;
   }

package/src/standalone/agent-tool/spawn-preset.mjs

@@ -0,0 +1,73 @@
+import { isKnownProvider } from '../provider-admin.mjs';
+import {
+  DEFAULT_AGENT_PRESETS,
+  DEFAULT_PROVIDER,
+} from './tool-def.mjs';
+import {
+  agentPresetName,
+  clean,
+  findPreset,
+  normalizeAgentName,
+  normalizeAgentRoute,
+  synthesizePreset,
+} from './helpers.mjs';
+
+export function resolveAgentSpawnPreset(config, args = {}) {
+  if (args.provider && args.model) {
+    return {
+      presetName: args.preset || '__direct__',
+      preset: {
+        id: '__direct__',
+        name: '__DIRECT__',
+        type: 'agent',
+        provider: clean(args.provider),
+        model: clean(args.model),
+        effort: clean(args.effort) || undefined,
+        fast: args.fast === true,
+        tools: 'full',
+      },
+    };
+  }
+
+  const agentName = normalizeAgentName(args.agent);
+  const configuredDefault = clean(config?.defaultProvider);
+  const fallbackProvider = configuredDefault && isKnownProvider(configuredDefault)
+    ? configuredDefault
+    : DEFAULT_PROVIDER;
+  const workflowSlot = agentName === 'explore' ? 'explorer'
+    : (agentName === 'maintainer' ? 'memory' : '');
+  const maintenanceSlot = agentName === 'explore' ? 'explore'
+    : (agentName === 'maintainer' ? 'memory' : '');
+  const agentRoute = !clean(args.preset)
+    ? (normalizeAgentRoute(config?.agents?.[agentName], fallbackProvider)
+      || (agentName === 'maintainer' ? normalizeAgentRoute(config?.agents?.maintenance, fallbackProvider) : null)
+      || normalizeAgentRoute(config?.workflowRoutes?.[workflowSlot], fallbackProvider)
+      || normalizeAgentRoute(config?.maintenance?.[maintenanceSlot], fallbackProvider))
+    : null;
+  if (agentRoute) {
+    return {
+      presetName: agentPresetName(agentName),
+      preset: {
+        id: `agent-${agentName}`,
+        name: agentPresetName(agentName),
+        type: 'agent',
+        provider: agentRoute.provider,
+        model: agentRoute.model,
+        effort: agentRoute.effort,
+        fast: agentRoute.fast === true,
+        tools: 'full',
+      },
+    };
+  }
+
+  const mainPreset = !clean(args.preset) && (agentName === 'explore' || agentName === 'maintainer')
+    ? findPreset(config, config?.default)
+    : null;
+  if (mainPreset) return { presetName: mainPreset.id || mainPreset.name, preset: mainPreset };
+
+  const presetName = clean(args.preset) || DEFAULT_AGENT_PRESETS[agentName];
+  if (!presetName) throw new Error(`agent: agent "${agentName}" has no model assignment`);
+  const preset = findPreset(config, presetName) || synthesizePreset(config, presetName);
+  if (!preset) throw new Error(`agent: preset "${presetName}" not found`);
+  return { presetName, preset };
+}