mixdog 1.2.2 → 1.2.4

package/src/runtime/agent/orchestrator/providers/xai-tool-search.fixtures.mjs

@@ -0,0 +1,195 @@
+// Shared by xai-tool-search.test.mjs and the one-off generator that produced
+// xai-tool-search-head-parity.json by running these same captures against the
+// pre-change xAI send path. The WebSocket transport is driven through the real
+// sendViaWebSocket with a scripted socket, so the real stream collector and
+// delta framing run; only the connection is replaced.
+import { mock } from 'node:test';
+import { EventEmitter } from 'node:events';
+import * as realWs from './openai-oauth-ws.mjs';
+
+export const ws = { bodies: [], frames: [], scripts: [] };
+
+function scriptedEntry() {
+  const socket = new EventEmitter();
+  socket.readyState = 1;
+  socket.close = () => {
+    socket.readyState = 3;
+  };
+  socket.terminate = socket.close;
+  return { socket, ephemeral: true };
+}
+
+mock.module(new URL('./openai-oauth-ws.mjs', import.meta.url).href, {
+  namedExports: {
+    ...realWs,
+    sendViaWebSocket: (args) => {
+      ws.bodies.push(structuredClone(args.body));
+      return realWs.sendViaWebSocket({
+        ...args,
+        _acquireWithRetryFn: async () => ({ entry: scriptedEntry(), reused: false }),
+        _sendFrameFn: async (entry, frame) => {
+          ws.frames.push(structuredClone(frame));
+          const events = ws.scripts.shift() || [COMPLETED_REPLY];
+          setImmediate(() => {
+            for (const event of events) entry.socket.emit('message', Buffer.from(JSON.stringify(event)));
+          });
+        },
+      });
+    },
+  },
+});
+
+const { sendXaiResponses, sendXaiResponsesWebSocket } = await import('./openai-compat-xai-send.mjs');
+const { nativeHistory, oauthHistory } = await import('./openai-compat-responses-parity.fixtures.mjs');
+export { sendXaiResponses, sendXaiResponsesWebSocket, nativeHistory, oauthHistory };
+
+export const REPLY = { type: 'message', role: 'assistant', content: [{ type: 'output_text', text: 'ok' }] };
+export const COMPLETED_REPLY = {
+  type: 'response.completed',
+  response: { id: 'resp-1', model: 'grok-4', status: 'completed', output: [REPLY] },
+};
+
+// A recorded xAI server-side tool-search turn (shapes per xAI's OpenAPI schema
+// ToolSearchCall / ToolSearchOutput: execution always "server", call_id null).
+export const ENCRYPTED_REASONING = { type: 'reasoning', id: 'rs_1', encrypted_content: 'ENC', summary: [] };
+export const TS_CALL = {
+  type: 'tool_search_call',
+  id: 'tsc_1',
+  call_id: null,
+  execution: 'server',
+  status: 'completed',
+  arguments: { query: 'mcp__weather__forecast', limit: 1 },
+};
+export const TS_OUTPUT = {
+  type: 'tool_search_output',
+  id: 'tso_1',
+  call_id: null,
+  execution: 'server',
+  status: 'completed',
+  tools: [
+    {
+      type: 'function',
+      name: 'mcp__weather__forecast',
+      description: 'Forecast',
+      parameters: { type: 'object', properties: { city: { type: 'string' } } },
+      defer_loading: true,
+    },
+  ],
+};
+export const FN_CALL = {
+  type: 'function_call',
+  id: 'fc_1',
+  call_id: 'call_w',
+  name: 'mcp__weather__forecast',
+  arguments: '{"city":"Seoul"}',
+  status: 'completed',
+};
+export const TURN_OUTPUT = [ENCRYPTED_REASONING, TS_CALL, TS_OUTPUT, FN_CALL];
+
+/** The stream events one server tool-search turn emits, in wire order. */
+export function serverSearchEvents(model = 'grok-4') {
+  return [
+    { type: 'response.created', response: { id: 'resp_ts', model } },
+    { type: 'response.output_item.done', item: ENCRYPTED_REASONING },
+    { type: 'response.output_item.added', item: { ...TS_CALL, status: 'in_progress' } },
+    { type: 'response.output_item.done', item: TS_CALL },
+    { type: 'response.output_item.added', item: TS_OUTPUT },
+    { type: 'response.output_item.done', item: TS_OUTPUT },
+    { type: 'response.output_item.added', item: { ...FN_CALL, arguments: '', status: 'in_progress' } },
+    { type: 'response.function_call_arguments.done', item_id: 'fc_1', arguments: FN_CALL.arguments },
+    { type: 'response.output_item.done', item: FN_CALL },
+    {
+      type: 'response.completed',
+      response: { id: 'resp_ts', model, status: 'completed', output: TURN_OUTPUT },
+    },
+  ];
+}
+
+export const SESSION_TOOLS = [
+  {
+    name: 'Read',
+    description: 'Read a file',
+    inputSchema: { type: 'object', properties: { path: { type: 'string' } } },
+  },
+  {
+    name: 'load_tool',
+    description: 'Load tools',
+    inputSchema: { type: 'object', properties: { names: { type: 'array' } } },
+  },
+];
+export const DEFERRED_TOOLS = [
+  ...SESSION_TOOLS,
+  {
+    name: 'mcp__weather__forecast',
+    description: 'Forecast',
+    inputSchema: { type: 'object', properties: { city: { type: 'string' } } },
+    deferLoading: true,
+  },
+];
+
+export function xaiProvider(config = {}, events = null) {
+  const requests = [];
+  const provider = {
+    name: 'xai',
+    config: { apiKey: 'test-key', preconnect: false, ...config },
+    nativePdf: true,
+    client: {
+      responses: {
+        create: async (params) => {
+          requests.push(structuredClone(params));
+          return (async function* () {
+            for (const event of events || [COMPLETED_REPLY]) yield event;
+          })();
+        },
+      },
+    },
+  };
+  return { provider, requests };
+}
+
+/** The history left by a recorded server tool-search turn (replay owner xai-responses). */
+export function serverSearchHistory() {
+  return [
+    { role: 'user', content: 'weather in Seoul?' },
+    {
+      role: 'assistant',
+      content: '',
+      toolCalls: [{ id: 'call_w', name: 'mcp__weather__forecast', arguments: { city: 'Seoul' } }],
+      providerReplay: { version: 1, provider: 'xai-responses', items: structuredClone(TURN_OUTPUT) },
+    },
+    { role: 'tool', toolCallId: 'call_w', content: 'sunny' },
+    { role: 'user', content: 'and Busan?' },
+  ];
+}
+
+export const CASES = [
+  ['native/plain-tools', () => nativeHistory(), SESSION_TOOLS],
+  ['oauth/plain-tools', () => oauthHistory(), SESSION_TOOLS],
+  ['server-replay/plain-tools', () => serverSearchHistory(), SESSION_TOOLS],
+  ['server-replay/deferred-tools', () => serverSearchHistory(), DEFERRED_TOOLS],
+  ['native/deferred-tools', () => nativeHistory(), DEFERRED_TOOLS],
+];
+
+/** The request body each transport sends for `history`, plus any option overrides. */
+export async function captureBodies(history, tools, { config = {}, opts = {} } = {}) {
+  const http = xaiProvider(config);
+  await sendXaiResponses(http.provider, history, 'grok-4', tools, { sessionId: 'sess-1', ...opts });
+  const before = ws.bodies.length;
+  const socket = xaiProvider(config);
+  await sendXaiResponsesWebSocket(socket.provider, history, 'grok-4', tools, {
+    sessionId: 'sess-1',
+    iteration: 1,
+    ...opts,
+  });
+  return { http: http.requests[0], ws: ws.bodies[before] };
+}
+
+export async function captureAll() {
+  const out = {};
+  for (const [label, build, tools] of CASES) {
+    const { http, ws: socketBody } = await captureBodies(build(), tools);
+    out[`http/${label}`] = http;
+    out[`ws/${label}`] = socketBody;
+  }
+  return out;
+}

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

@@ -0,0 +1,104 @@
+export const ASK_USER_MAX_QUESTIONS = 4;
+export const ASK_USER_MAX_TEXT = 4000;
+export const ASK_USER_MAX_LABEL = 80;
+
+export const ASK_USER_TOOL_DEFS = Object.freeze([
+  {
+    name: 'ask_user',
+    title: 'Ask User',
+    trigger:
+      'Ask the user 1–4 multiple-choice questions and wait; when a plan needs the user to pick between clear options, instead of listing them in chat.',
+    description:
+      'Ask the user multiple-choice questions and wait. Only while planning, for a decision only the user can make with clear options; open questions, minor choices and plan approval go in chat. Do not repeat the options in your message.',
+    annotations: {
+      title: 'Ask User',
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: false,
+      openWorldHint: false,
+      agentHidden: true,
+    },
+    inputSchema: {
+      type: 'object',
+      properties: {
+        questions: {
+          type: 'array',
+          minItems: 1,
+          maxItems: ASK_USER_MAX_QUESTIONS,
+          items: {
+            type: 'object',
+            properties: {
+              question: { type: 'string', description: 'Full question, without the options.' },
+              header: { type: 'string', maxLength: 12, description: 'Chip label.' },
+              options: {
+                type: 'array',
+                minItems: 2,
+                maxItems: 4,
+                description: 'Distinct; free text is added, never "Other".',
+                items: {
+                  type: 'object',
+                  properties: {
+                    label: { type: 'string', maxLength: 80, description: '1-5 words.' },
+                    description: { type: 'string', description: 'One-sentence tradeoff.' },
+                  },
+                  required: ['label', 'description'],
+                  additionalProperties: false,
+                },
+              },
+              multi_select: { type: 'boolean' },
+              recommended: { type: 'integer', minimum: 0, description: 'Recommended option index.' },
+            },
+            required: ['question', 'header', 'options'],
+          },
+        },
+      },
+      required: ['questions'],
+      additionalProperties: false,
+    },
+  },
+]);
+
+/** Throws a clear error when the questions are malformed; returns the list. */
+export function validateAskUserQuestions(args) {
+  const questions = args?.questions;
+  if (!Array.isArray(questions) || questions.length < 1 || questions.length > ASK_USER_MAX_QUESTIONS) {
+    throw new Error(`ask_user requires 1-${ASK_USER_MAX_QUESTIONS} questions`);
+  }
+  const seenQuestions = new Set();
+  questions.forEach((q, i) => {
+    const at = `ask_user question ${i + 1}`;
+    if (!q || typeof q !== 'object') throw new Error(`${at} must be an object`);
+    if (typeof q.question !== 'string' || !q.question.trim()) throw new Error(`${at} needs question text`);
+    if (typeof q.header !== 'string' || !q.header.trim() || q.header.length > 12) {
+      throw new Error(`${at} needs a header of at most 12 characters`);
+    }
+    if (seenQuestions.has(q.question)) throw new Error(`${at} duplicates another question text`);
+    seenQuestions.add(q.question);
+    if (!Array.isArray(q.options) || q.options.length < 2 || q.options.length > 4) {
+      throw new Error(`${at} needs 2-4 options`);
+    }
+    const labels = new Set();
+    for (const option of q.options) {
+      if (!option || typeof option.label !== 'string' || !option.label.trim()) {
+        throw new Error(`${at} has an option without a label`);
+      }
+      if (option.label.length > 80) throw new Error(`${at} has an option label over 80 characters`);
+      if (typeof option.description !== 'string' || !option.description.trim()) {
+        throw new Error(`${at} option "${option.label}" needs a one-sentence description`);
+      }
+      if (option.description.length > 200) throw new Error(`${at} has an option description over 200 characters`);
+      if (Object.keys(option).some((key) => key !== 'label' && key !== 'description')) {
+        throw new Error(`${at}: options take only a label and a description`);
+      }
+      if (labels.has(option.label)) throw new Error(`${at} has duplicate option label "${option.label}"`);
+      labels.add(option.label);
+    }
+    if (
+      q.recommended != null &&
+      (!Number.isInteger(q.recommended) || q.recommended < 0 || q.recommended >= q.options.length)
+    ) {
+      throw new Error(`${at} recommended must be an index below ${q.options.length}`);
+    }
+  });
+  return questions;
+}

package/src/runtime/agent/orchestrator/runtime-core/config-helpers.mjs

@@ -189,18 +189,20 @@ const AUTO_CLEAR_DEFAULT_IDLE_MS = 60 * 60 * 1000;
 // rewrite the accumulated tail. Anthropic agent tails are 5m and compact once
 // expired; their terminal reap keeps this 1h window so a completed agent stays
 // reusable. Gemini, xAI and Mistral
-// caches run ~1h, Groq's implicit cache persists ~2h, OpenAI/DeepSeek
-// key-prefix/implicit caches persist far longer (~24h), and OpenAI OAuth
-// (Codex backend) guarantees a 30-minute minimum prompt-cache TTL on
-// GPT-5.6+ models (prompt_cache_options.ttl=30m, refreshed on use), so the
-// sweep matches that window to avoid clearing a still-warm cache.
+// caches run ~1h, Groq's implicit cache persists ~2h, and DeepSeek's
+// implicit cache is evicted after "a few hours to a few days" (kept at 24h).
+// OpenAI (direct and OAuth/Codex) guarantees a 30-minute minimum prompt-cache
+// TTL on GPT-5.6+ (refreshed on use; no 24h retention there), so the sweep
+// matches that window. Older OpenAI models that still take
+// prompt_cache_retention='24h' are not distinguished: these call sites only
+// know the provider, not the model, so 30m applies to the whole provider.
 // Unknown/unrecognized providers fall back to the 'default' 1h entry.
 const AUTO_CLEAR_PROVIDER_IDLE_MS = Object.freeze({
   anthropic: 60 * 60 * 1000,
   'anthropic-oauth': 60 * 60 * 1000,
   gemini: 60 * 60 * 1000,
   groq: 2 * 60 * 60 * 1000,
-  openai: 24 * 60 * 60 * 1000,
+  openai: 30 * 60 * 1000,
   deepseek: 24 * 60 * 60 * 1000,
   xai: 60 * 60 * 1000,
   'openai-oauth': 30 * 60 * 1000,

package/src/runtime/agent/orchestrator/runtime-core/deferred-tool-availability.mjs

@@ -1,3 +1,27 @@
+const lowerName = (name) => String(name || '').toLowerCase();
+
+/** The persisted schema allowlist (also the execution allowlist) leaves `name` out. */
+export function sessionAllowlistExcludes(session, name) {
+  if (!Array.isArray(session?.schemaAllowedTools)) return false;
+  return !session.schemaAllowedTools.some((allowed) => lowerName(allowed) === lowerName(name));
+}
+
+/** The session's denied tools name `name`. */
+export function sessionDisallows(session, name) {
+  return (
+    Array.isArray(session?.disallowedTools) &&
+    session.disallowedTools.some((denied) => lowerName(denied) === lowerName(name))
+  );
+}
+
+/**
+ * The session's own tool policy permits `name`: discovery (load_tool by name
+ * or query) shows, selects and describes only what execution would run.
+ */
+export function isToolPermittedBySessionPolicy(session, name) {
+  return !sessionAllowlistExcludes(session, name) && !sessionDisallows(session, name);
+}
+
 // Discovery history retains definitions; only the latest scoped MCP snapshot
 // grants availability. An absent snapshot preserves pre-initialization behavior.
 export function isDeferredToolAvailable(session, name) {

package/src/runtime/agent/orchestrator/runtime-core/effort.mjs

@@ -114,6 +114,21 @@ function catalogEffortOptions(provider, model) {
   return providerAllowed ? [...providerAllowed] : [];
 }
 
+const warnedEmptyLadders = new Set();
+
+/**
+ * Auto effort skipped a judgment because the base is off the model's ladder.
+ * A user-chosen max/ultra is expected to skip; any other base means the route
+ * has no usable ladder, so say so once per provider/model per process.
+ */
+export function warnEmptyAutoEffortLadder(provider, model, base) {
+  if (base === 'max' || base === 'ultra') return;
+  const key = `${provider}/${model}`;
+  if (warnedEmptyLadders.has(key)) return;
+  warnedEmptyLadders.add(key);
+  process.stderr.write(`[auto-effort] no effort ladder for ${key}; judge skipped\n`);
+}
+
 export function coerceEffortFor(provider, model, effort) {
   if (!effort) return null;
   if (model?.customReasoning) return snapCustomEffort(customEffortLevels(model), effort);

package/src/runtime/agent/orchestrator/runtime-core/goal-store.mjs

@@ -86,7 +86,7 @@ export function createGoalStore(ctx) {
     }
   };
 
-  const commit = async (sessionId, goal) => {
+  const commit = async (sessionId, goal, { isCurrent, accept } = {}) => {
     const id = assertSessionId(sessionId);
     const previous = goal ? readRecord(id).goal : null;
     let committedGoal = null;
@@ -101,7 +101,35 @@ export function createGoalStore(ctx) {
           ? previous.revision + Number(revisionStateKey(previous) !== revisionStateKey(committedGoal))
           : 1;
     }
-    await storage.write(id, { version: GOAL_FILE_VERSION, goal: committedGoal });
+    const rollback = async () => {
+      try {
+        await storage.write(id, { version: GOAL_FILE_VERSION, goal: previous });
+      } catch (error) {
+        error.quotaResumeRollbackFailed = true;
+        throw error;
+      }
+      ctx.deadlines.armDeadline(id);
+    };
+    try {
+      await storage.write(id, { version: GOAL_FILE_VERSION, goal: committedGoal });
+    } catch (error) {
+      if (isCurrent || accept) await rollback();
+      throw error;
+    }
+    if (isCurrent || accept) {
+      let accepted = false;
+      let admissionError = null;
+      try {
+        accepted = (!isCurrent || isCurrent()) && (!accept || accept() === true);
+      } catch (error) {
+        admissionError = error;
+      }
+      if (!accepted) {
+        await rollback();
+        if (admissionError) throw admissionError;
+        return null;
+      }
+    }
     ctx.deadlines.armDeadline(id);
     emit(id);
     return publicGoal(committedGoal, now());

package/src/runtime/agent/orchestrator/runtime-core/goal-turns.mjs

@@ -171,8 +171,9 @@ export function createGoalTurnLifecycle(ctx) {
     // A quota resume revives exactly the Goal its failure suspended, and only
     // while that Goal is still waiting on the limit: a Goal the user paused,
     // stopped, replaced or completed meanwhile stays as it is.
-    reactivateUsageLimited(sessionId, goalId) {
+    reactivateUsageLimited(sessionId, goalId, options = {}) {
       return withMutation(sessionId, async (id) => {
+        if (options.isCurrent && !options.isCurrent()) return null;
         const goal = readRecord(id).goal;
         if (!goal || goal.archivedAt || goal.id !== clean(goalId) || goal.status !== 'usage_limited') return null;
         try {
@@ -180,7 +181,7 @@ export function createGoalTurnLifecycle(ctx) {
         } catch {
           return null;
         }
-        return commit(id, goal);
+        return commit(id, goal, options);
       });
     },
     continuation(sessionId, { agentStatus = null } = {}) {

package/src/runtime/agent/orchestrator/runtime-core/orchestration.mjs

@@ -5,9 +5,10 @@ const BATCHING = {
 self-contained supporting work, one agent per role; batch related tasks
 rather than splitting them for parallelism.`,
   balanced: `Delegate independent work by coherent feature or module, one agent per
-scope. Batch related tasks within the same change scope rather than
-splitting every file or step.`,
-  swarm: `Delegate every independent scope to its own agent. Treat disjoint file or
+scope; a scope is one verifiable deliverable. Batch related tasks within the
+same change scope rather than splitting every file or step.`,
+  swarm: `Delegate every independent scope to its own agent; a scope is one
+verifiable deliverable, not a bundle of steps. Treat disjoint file or
 module sets as independent and merge scopes only on a true output
 dependency. Prefer parallel scopes over sequential slices in one agent.`,
 };
@@ -38,6 +39,10 @@ scopes does not change this.
 
 Dispatch all ready independent scopes in one turn. Only a scope that requires
 another's output waits. Brief each agent as the Lead rules describe.
+A running agent receives only changes within its own scope; a new independent
+need goes to a new agent. When scopes touch the same file, name one owner for
+that file in each brief. Agents run only the checks covering their own change;
+Lead runs the full suite once after integration.
 Use only available agents; when none fits a role, Lead does that work itself
 and never changes settings to enable one. If the reviewer is disabled or
 unavailable, Lead alone reviews the result against the approved scope and

package/src/runtime/agent/orchestrator/runtime-core/provider-request-snapshot.mjs

@@ -3,7 +3,7 @@ import { types } from 'node:util';
 import { clean } from './session-text.mjs';
 import { isDeferredToolAvailable } from './deferred-tool-availability.mjs';
 import { finalizeProviderRequestTools } from './provider-request-tools.mjs';
-import { parseToolSelection, ANTHROPIC_NATIVE_PROVIDERS } from './tool-catalog-schema.mjs';
+import { parseToolSelection, nativeProviderFamily, ANTHROPIC_NATIVE_PROVIDERS } from './tool-catalog-schema.mjs';
 
 const OMIT_REQUEST_TOOL_VALUE = Symbol('omit-request-tool-value');
 const MAX_PROVIDER_SNAPSHOT_ARRAY_LENGTH = 1_000_000;
@@ -378,9 +378,13 @@ const requestToolSnapshotMemo = new WeakMap();
 export function snapshotProviderRequestTools(options = {}) {
   const { provider, tools, nativeTools, messages, session } = options;
   const normalizedProvider = clean(provider || session?.provider).toLowerCase();
-  const anthropic = ANTHROPIC_NATIVE_PROVIDERS.has(normalizedProvider);
+  // Server-hosted definitions stay first-party Anthropic only; defer_loading
+  // expansion follows the session's native family, which a gateway gets from
+  // its pinned Messages route with verified support.
+  const firstPartyAnthropic = ANTHROPIC_NATIVE_PROVIDERS.has(normalizedProvider);
+  const anthropic = nativeProviderFamily(normalizedProvider, session?.wireRoute) === 'anthropic';
   const activeTools = entriesOf(tools);
-  const nativeList = anthropic ? entriesOf(nativeTools) : NO_ENTRIES;
+  const nativeList = firstPartyAnthropic ? entriesOf(nativeTools) : NO_ENTRIES;
   const mcpNames = Array.isArray(session?.deferredMcpToolNames) ? session.deferredMcpToolNames : null;
   let base = Array.isArray(tools) ? requestToolSnapshotMemo.get(tools) : null;
   if (

package/src/runtime/agent/orchestrator/runtime-core/session-title.mjs

@@ -15,6 +15,26 @@ function hasMeaningfulTitleText(value) {
   return /[\p{L}\p{N}]/u.test(String(value || ''));
 }
 
+const graphemeSegmenter =
+  typeof Intl !== 'undefined' && typeof Intl.Segmenter === 'function'
+    ? new Intl.Segmenter(undefined, { granularity: 'grapheme' })
+    : null;
+
+/** The longest prefix of `text` within `limit` UTF-16 units that ends on a
+ *  grapheme (else code point) boundary, so a surrogate pair or emoji sequence
+ *  is never split. */
+function prefixWithinLimit(text, limit) {
+  const pieces = graphemeSegmenter
+    ? Array.from(graphemeSegmenter.segment(text), (part) => part.segment)
+    : Array.from(text);
+  let head = '';
+  for (const piece of pieces) {
+    if (head.length + piece.length > limit) break;
+    head += piece;
+  }
+  return head;
+}
+
 export function compactSessionTitle(value, maximum = 32) {
   const line =
     String(value || '')
@@ -25,7 +45,7 @@ export function compactSessionTitle(value, maximum = 32) {
   const text = cleanSessionPreview(line, Math.max(maximum * 4, 128));
   if (!hasMeaningfulTitleText(text)) return '';
   if (text.length <= maximum) return text;
-  const clipped = text.slice(0, maximum - 1);
+  const clipped = prefixWithinLimit(text, maximum - 1);
   const boundary = clipped.lastIndexOf(' ');
   const head = boundary >= Math.floor(maximum * 0.6) ? clipped.slice(0, boundary) : clipped;
   return `${head.trimEnd()}…`;

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

@@ -3,6 +3,7 @@
 import { deferredCatalogUnion, selectDeferredTools, toolSearchNativePayload } from './tool-catalog.mjs';
 import { preDispatchDenyForSession } from '../session/loop/pre-dispatch-deny.mjs';
 import { parseMcpToolName } from '../../../shared/tool-primitives.mjs';
+import { isToolBridgeEnabled } from './tool-exposure.mjs';
 
 export function loadSkillToolDependencies(envelope, session, mode) {
   if (!envelope?.__toolEnvelope) return envelope;
@@ -46,11 +47,24 @@ export function loadSkillToolDependencies(envelope, session, mode) {
   if (loaded.length) {
     session.skillLoadedTools = [...new Set([...(session.skillLoadedTools || []), ...loaded])];
   }
+  const eager = new Set((session?.tools || []).map((tool) => tool.name));
+  // Bridge exposure never promotes a schema: deferred dependencies stay
+  // reachable through call_tool while the eager surface keeps its bytes.
+  const bridged = isToolBridgeEnabled(session) ? loaded.filter((name) => !eager.has(name)) : [];
+  const direct = loaded.filter((name) => !bridged.includes(name));
   const summary = [
     envelope.result,
-    ...(loaded.length
+    ...(direct.length && !isToolBridgeEnabled(session)
+      ? [
+          `Required tools loaded: ${direct.join(', ')}. Their full definitions are available on your next request; use them directly without load_tool.`,
+        ]
+      : []),
+    ...(direct.length && isToolBridgeEnabled(session)
+      ? [`Required tools available directly: ${direct.join(', ')}.`]
+      : []),
+    ...(bridged.length
       ? [
-          `Required tools loaded: ${loaded.join(', ')}. Their full definitions are available on your next request; use them directly without load_tool.`,
+          `Required tools available through call_tool: ${bridged.join(', ')}. Read a definition with load_tool, then run it with call_tool {name, arguments}.`,
         ]
       : []),
     ...(unavailable.length
@@ -60,7 +74,6 @@ export function loadSkillToolDependencies(envelope, session, mode) {
         ]
       : []),
   ].join('\n');
-  const eager = new Set((session?.tools || []).map((tool) => tool.name));
   const native = selection?.native
     ? toolSearchNativePayload(
         [...catalog.values()],

package/src/runtime/agent/orchestrator/runtime-core/tool-bridge-contract.mjs

@@ -0,0 +1,6 @@
+export const BRIDGE_NAME_MAX_CHARS = 256;
+const META_NAMES = new Set(['load_tool', 'call_tool', 'tool_search']);
+
+export function isBridgeMetaTool(name) {
+  return typeof name === 'string' && META_NAMES.has(name.toLowerCase());
+}