mixdog 0.9.22 → 0.9.24

package/src/runtime/agent/orchestrator/mcp/client.mjs

@@ -4,6 +4,7 @@ import { join } from 'path';
 import { tmpdir } from 'os';
 import { randomUUID } from 'crypto';
 import { smartReadTruncate } from '../tools/builtin/read-formatting.mjs';
+import { shutdownStdioChild, killStdioChildTreeFast } from './child-tree.mjs';
 // --- Types ---
 /** Known auto-detect targets: port file path relative to tmpdir.
  *  Note: `mixdog` used to self-loopback via active-instance.json's
@@ -15,6 +16,8 @@ const AUTO_DETECT_PORTS = {
     'mixdog-memory': { dir: 'mixdog', file: 'active-instance.json', portField: 'memory_port', endpoint: '/mcp' },
 };
 const DEFAULT_MCP_CALL_TIMEOUT_MS = 0;
+// Per-server STARTUP handshake budget (connect + listTools). Codex parity: 10s.
+export const DEFAULT_MCP_STARTUP_TIMEOUT_MS = 10000;
 // --- State ---
 const servers = new Map();
 let mcpSdkPromise = null;
@@ -96,21 +99,31 @@ export function resolveMcpTransportKind(cfg) {
  * Supports stdio (child process) and http (Streamable HTTP) transports.
  */
 export async function connectMcpServers(config) {
+    // Capture the abort generation SYNCHRONOUSLY at entry: the boot path fires
+    // this un-awaited, so a runtime close can land while connectServer is still
+    // loading the SDK. A capture taken any later would already see the bumped
+    // generation and register the server anyway (leaking its stdio child).
+    const genAtStart = _connectAbortGeneration;
     const failures = [];
-    for (const [name, cfg] of Object.entries(config)) {
+    const entries = Object.entries(config).filter(([name, cfg]) => {
         if (cfg?.enabled === false) {
             mcpLog(`[mcp-client] Skipping disabled server "${name}"\n`);
-            continue;
+            return false;
         }
-        try {
-            await connectServer(name, cfg);
-        }
-        catch (err) {
-            const msg = err instanceof Error ? err.message : String(err);
-            mcpLog(`[mcp-client] Failed to connect "${name}": ${msg}\n`);
-            failures.push({ name, msg });
-        }
-    }
+        return true;
+    });
+    // Connect all servers in PARALLEL: a slow/hung server (bounded by its
+    // per-server startup timeout) must never delay the others' handshakes.
+    const settled = await Promise.allSettled(
+        entries.map(([name, cfg]) => connectServer(name, cfg, genAtStart)),
+    );
+    settled.forEach((res, i) => {
+        if (res.status !== 'rejected') return;
+        const [name] = entries[i];
+        const msg = res.reason instanceof Error ? res.reason.message : String(res.reason);
+        mcpLog(`[mcp-client] Failed to connect "${name}": ${msg}\n`);
+        failures.push({ name, msg });
+    });
     if (failures.length > 0) {
         const detail = failures.map(f => `${f.name}: ${f.msg}`).join('; ');
         const err = new Error(`[mcp-client] ${failures.length} MCP server(s) failed to connect — ${detail}`);
@@ -182,7 +195,7 @@ export async function executeMcpTool(name, args) {
         mcpLog(`[mcp-client] Tool call failed, attempting reconnect...\n`);
         await new Promise(r => setTimeout(r, 500));
         try {
-            await server.client.close();
+            await _closeServer(server);
         } catch { /* ignore close error */ }
         try {
             await connectServer(serverName, server.cfg);
@@ -233,6 +246,26 @@ export function isMcpToolCallTimeoutError(err) {
     return err?.code === 'EMCPTOOLTIMEOUT';
 }
 
+// MCP per-server STARTUP timeout: bounds the connect + listTools handshake so a
+// slow or hung server can't stall boot or the first turn. Default 10s (codex
+// parity). Per-server override: startupTimeoutMs / startupTimeoutSec. Global
+// env: MIXDOG_MCP_STARTUP_TIMEOUT_MS. A value of 0/off/none/false disables it.
+export function resolveMcpStartupTimeoutMs(cfg = {}, env = process.env) {
+    const rawMs = cfg?.startupTimeoutMs ?? cfg?.startup_timeout_ms;
+    const rawSec = cfg?.startupTimeoutSec ?? cfg?.startup_timeout_sec;
+    const rawEnv = env?.MIXDOG_MCP_STARTUP_TIMEOUT_MS;
+    let raw;
+    let scale = 1;
+    if (rawMs != null && rawMs !== '') raw = rawMs;
+    else if (rawSec != null && rawSec !== '') { raw = rawSec; scale = 1000; }
+    else if (rawEnv != null && rawEnv !== '') raw = rawEnv;
+    else return DEFAULT_MCP_STARTUP_TIMEOUT_MS;
+    if (raw === 0 || (typeof raw === 'string' && /^(0|off|none|false)$/i.test(raw.trim()))) return 0;
+    const parsed = Number(raw) * scale;
+    if (!Number.isFinite(parsed) || parsed <= 0) return DEFAULT_MCP_STARTUP_TIMEOUT_MS;
+    return Math.round(parsed);
+}
+
 async function _callToolWithTimeout(server, toolName, args) {
     let timer;
     const timeoutMs = resolveMcpCallTimeoutMs(server?.cfg);
@@ -241,7 +274,9 @@ async function _callToolWithTimeout(server, toolName, args) {
     }
     const timeout = new Promise((_, rej) => {
         timer = setTimeout(() => {
-            try { server.client.close().catch(() => {}); } catch { /* ignore */ }
+            // Route through the full tree-shutdown path so a timed-out stdio
+            // server never orphans grandchildren. Fire-and-forget.
+            try { _closeServer(server).catch(() => {}); } catch { /* ignore */ }
             const err = new Error(`MCP tool call timed out after ${timeoutMs}ms (server="${server.name}", tool="${toolName}")`);
             err.code = 'EMCPTOOLTIMEOUT';
             err.serverName = server.name;
@@ -336,16 +371,72 @@ export function mcpToolHasField(name, field) {
  * Disconnect all MCP servers.
  */
 export async function disconnectAll() {
+    // Abort handshakes still in flight: bump the generation so a connect that
+    // completes after this point tears itself down instead of registering, and
+    // reap any already-spawned stdio child now so its ref'd ChildProcess handle
+    // can't keep the event loop alive (close-during-connect previously leaked
+    // the uvx/npx wrapper tree and hung process exit).
+    _connectAbortGeneration++;
+    for (const entry of [..._pendingConnects]) {
+        _pendingConnects.delete(entry);
+        // Mid-handshake child: nothing to shut down gracefully — hard-kill the
+        // tree without holding the event loop (this path runs during process
+        // exit; the spec-order grace dance would delay exit by seconds).
+        try { killStdioChildTreeFast(entry.transport); }
+        catch { /* ignore */ }
+        try { void entry.client.close().catch(() => { /* ignore */ }); }
+        catch { /* ignore */ }
+    }
     for (const [name, server] of servers) {
         try {
-            await server.client.close();
+            await _closeServer(server);
         }
         catch { /* ignore */ }
         servers.delete(name);
     }
     _invalidateMcpToolFieldMemo();
 }
-async function connectServer(name, cfg) {
+/**
+ * Disconnect a single MCP server by name. No-op (returns false) when the
+ * server is not in the live registry; otherwise closes its transport, removes
+ * it, and invalidates the tool-field memo. Lets callers toggle one server
+ * without a full disconnectAll()/reconnect cycle.
+ */
+export async function disconnectMcpServer(name) {
+    const server = servers.get(name);
+    if (!server) return false;
+    try {
+        await _closeServer(server);
+    }
+    catch { /* ignore */ }
+    servers.delete(name);
+    _invalidateMcpToolFieldMemo();
+    return true;
+}
+/**
+ * Close a single server: for stdio transports first shut down the full child
+ * process tree (close stdin -> grace -> tree kill) so wrapper chains such as
+ * uvx/npx/uv never orphan grandchildren, then release the SDK client. The
+ * tree teardown runs before client.close() because the SDK's own close()
+ * only kills the direct child and discards the pid we need to walk the tree.
+ */
+async function _closeServer(server) {
+    const transport = server?.transport;
+    // Live stdio transports expose the spawned ChildProcess on _process.
+    if (transport && transport._process) {
+        try { await shutdownStdioChild(transport); }
+        catch { /* ignore */ }
+    }
+    try { await server.client.close(); }
+    catch { /* ignore */ }
+}
+// Connects whose handshake has not finished yet: disconnectAll() must be able
+// to see (and tear down) their transports, because `servers` only lists fully
+// handshaken entries. Generation token aborts a connect that outlives a
+// disconnectAll() issued mid-handshake (runtime close during boot connect).
+let _connectAbortGeneration = 0;
+const _pendingConnects = new Set();
+async function connectServer(name, cfg, genAtStart = _connectAbortGeneration) {
     const {
         Client,
         StdioClientTransport,
@@ -353,6 +444,11 @@ async function connectServer(name, cfg) {
         SSEClientTransport,
         WebSocketClientTransport,
     } = await loadMcpSdk();
+    if (genAtStart !== _connectAbortGeneration) {
+        // disconnectAll() ran while the SDK was loading: nothing spawned yet —
+        // abort before creating a transport/child at all.
+        throw new Error(`MCP server "${name}" connect aborted by shutdown`);
+    }
     const client = new Client({ name: `mixdog-agent/${name}`, version: '1.0.0' });
     let transport;
     const kind = resolveMcpTransportKind(cfg);
@@ -435,23 +531,78 @@ async function connectServer(name, cfg) {
     else {
         throw new Error(`Invalid config for "${name}": need autoDetect, type (stdio/http/sse/ws), url (http), or command (stdio)`);
     }
-    await client.connect(transport);
-    const instructionsRaw = typeof client.getInstructions === 'function'
-        ? client.getInstructions()
-        : undefined;
-    const instructions = typeof instructionsRaw === 'string' ? instructionsRaw.trim() : '';
-    const toolsResult = await client.listTools();
-    if (!toolsResult || !Array.isArray(toolsResult.tools)) {
-        throw new Error(`[mcp-client] ListTools returned invalid shape for "${name}": missing or non-array tools field`);
+    const pending = { name, client, transport };
+    _pendingConnects.add(pending);
+    try {
+        // Bound the connect + listTools handshake so a slow/hung server can't
+        // stall boot or the first turn. On expiry we tear down the pending
+        // transport/child (nothing leaks) and fail this server like any other
+        // connect failure — the parallel Promise.allSettled means other servers
+        // are unaffected.
+        const startupTimeoutMs = resolveMcpStartupTimeoutMs(cfg);
+        let startupTimer = null;
+        let startupTimedOut = false;
+        const handshake = (async () => {
+            await client.connect(transport);
+            const instructionsRaw = typeof client.getInstructions === 'function'
+                ? client.getInstructions()
+                : undefined;
+            const instr = typeof instructionsRaw === 'string' ? instructionsRaw.trim() : '';
+            const result = await client.listTools();
+            return { instructions: instr, toolsResult: result };
+        })();
+        let instructions;
+        let toolsResult;
+        try {
+            if (startupTimeoutMs > 0) {
+                const guard = new Promise((_, rej) => {
+                    startupTimer = setTimeout(() => {
+                        startupTimedOut = true;
+                        const err = new Error(`MCP server "${name}" startup exceeded ${startupTimeoutMs}ms budget — raise per-server "startupTimeoutSec"/"startupTimeoutMs" or env MIXDOG_MCP_STARTUP_TIMEOUT_MS`);
+                        err.code = 'EMCPSTARTUPTIMEOUT';
+                        rej(err);
+                    }, startupTimeoutMs);
+                });
+                ({ instructions, toolsResult } = await Promise.race([handshake, guard]));
+            } else {
+                ({ instructions, toolsResult } = await handshake);
+            }
+        } catch (err) {
+            if (startupTimedOut) {
+                // Tear down the pending transport/child so a hung handshake never
+                // leaks a stdio process or socket — fire-and-forget (like the
+                // tool-call timeout path) so a slow tree-kill never delays this
+                // server's failure or the parallel batch's resolution.
+                try { _closeServer({ client, transport }).catch(() => {}); }
+                catch { /* ignore */ }
+                // Never let the late handshake settle into an unhandled rejection.
+                handshake.catch(() => {});
+            }
+            throw err;
+        } finally {
+            if (startupTimer) clearTimeout(startupTimer);
+        }
+        if (!toolsResult || !Array.isArray(toolsResult.tools)) {
+            throw new Error(`[mcp-client] ListTools returned invalid shape for "${name}": missing or non-array tools field`);
+        }
+        if (genAtStart !== _connectAbortGeneration) {
+            // disconnectAll() ran mid-handshake: never register — tear down.
+            try { await _closeServer({ client, transport }); }
+            catch { /* ignore */ }
+            throw new Error(`MCP server "${name}" connect aborted by shutdown`);
+        }
+        const tools = toolsResult.tools.map((t) => ({
+            name: `mcp__${name}__${t.name}`,
+            description: t.description || '',
+            inputSchema: (t.inputSchema || { type: 'object', properties: {} }),
+            ...(t.annotations && typeof t.annotations === 'object' ? { annotations: t.annotations } : {}),
+        }));
+        const toolNames = tools.map(t => t.name);
+        servers.set(name, { name, client, transport, tools, cfg, instructions });
+        _invalidateMcpToolFieldMemo();
+        mcpLog(`[mcp] connected: ${tools.length} tools — ${toolNames.join(', ')}\n`);
+    }
+    finally {
+        _pendingConnects.delete(pending);
     }
-    const tools = toolsResult.tools.map((t) => ({
-        name: `mcp__${name}__${t.name}`,
-        description: t.description || '',
-        inputSchema: (t.inputSchema || { type: 'object', properties: {} }),
-        ...(t.annotations && typeof t.annotations === 'object' ? { annotations: t.annotations } : {}),
-    }));
-    const toolNames = tools.map(t => t.name);
-    servers.set(name, { name, client, transport, tools, cfg, instructions });
-    _invalidateMcpToolFieldMemo();
-    mcpLog(`[mcp] connected: ${tools.length} tools — ${toolNames.join(', ')}\n`);
 }

package/src/runtime/agent/orchestrator/providers/anthropic-oauth.mjs

@@ -301,6 +301,21 @@ function nativeAnthropicTools(opts) {
         ? opts.nativeTools.filter(t => t && typeof t === 'object')
         : [];
 }
+// Map the orchestrator-level opts.toolChoice into Anthropic's tool_choice.
+// Only 'none' is activated: it lets the hard-cap final turn keep the tool
+// DEFINITIONS in-request (so the tools->system->messages prefix — and its
+// prompt-cache prefix — stay byte-identical to prior turns) while forbidding
+// tool USE, so the model can only emit text. Forced values
+// ('required'->{type:'any'}, {name}->{type:'tool'}) are deliberately NOT
+// mapped: Anthropic returns a 400 for any forced tool_choice while
+// extended/adaptive thinking is enabled, and the only caller that sets
+// opts.toolChoice='required' (the forced-first-tool turn) runs with
+// effort/thinking active on reasoning models — activating it would convert a
+// previously-harmless no-op into a hard 400 on exactly that turn. Attached
+// only when the request actually carries tools (see buildRequestBody).
+function toAnthropicToolChoice(toolChoice) {
+    return toolChoice === 'none' ? { type: 'none' } : undefined;
+}
 function deferredAnthropicTools(activeTools, opts) {
     if (opts?.session?.deferredNativeTools !== true) return [];
     // A request whose ONLY tools are deferred is rejected by the API with
@@ -464,10 +479,25 @@ function applyAnthropicCacheMarkers(sanitizedMessages, { messageTtl = CACHE_TTL_
         return -1;
     };
 
+    const firstRequestUserPromptIdx = () => {
+        // Iteration-1 fallback: on the very first request a session has only the
+        // current user prompt — no tool_result tail and no earlier user turn, so
+        // both anchors above return -1 and NO message breakpoint is placed. That
+        // left the whole tools+system prefix (~4.2k) uncached on iter1: nothing
+        // was written, so iter2 re-sent it as a fresh full write instead of a
+        // read hit. Anchor the current prompt's tail so the stable prefix is
+        // cache-written on the first ask and read back on the next. Only used
+        // when neither real anchor exists, so later turns still prefer the
+        // tool_result / previous-user-text anchors (never the volatile new
+        // prompt). Synthetic <system-reminder> turns are excluded by hasUserText.
+        if (latestToolResultTailIdx() !== -1 || previousUserTextAnchorIdx() !== -1) return -1;
+        const tailIdx = sanitizedMessages.length - 1;
+        return hasUserText(sanitizedMessages[tailIdx]) ? tailIdx : -1;
+    };
     if (messageTtl !== null) {
         const slots = Math.max(0, Math.min(4, Number(messageSlots) || 0));
         const marked = new Set();
-        const candidates = [latestToolResultTailIdx(), previousUserTextAnchorIdx()];
+        const candidates = [latestToolResultTailIdx(), previousUserTextAnchorIdx(), firstRequestUserPromptIdx()];
         for (const idx of candidates) {
             if (slots <= 0) break;
             if (idx < 0 || marked.has(idx) || !canMarkMessageIdx(idx)) continue;
@@ -597,6 +627,13 @@ function buildRequestBody(messages, model, tools, sendOpts) {
         // a slot that's better spent on messages tail.
         body.tools = [...nativeTools, ...toAnthropicTools([...(tools || []), ...deferredTools])];
     }
+    // tool_choice only when tools are actually present (Anthropic rejects
+    // tool_choice without tools). 'none' rides the hard-cap final turn to
+    // forbid tool USE while keeping the tools prefix stable for cache reuse.
+    if (body.tools) {
+        const toolChoice = toAnthropicToolChoice(opts.toolChoice);
+        if (toolChoice) body.tool_choice = toolChoice;
+    }
 
     applyAnthropicEffortToBody(body, {
         model,

package/src/runtime/agent/orchestrator/providers/anthropic.mjs

@@ -308,6 +308,22 @@ function nativeAnthropicTools(opts) {
         ? opts.nativeTools.filter(t => t && typeof t === 'object')
         : [];
 }
+// Map the orchestrator-level opts.toolChoice into Anthropic's tool_choice.
+// Only 'none' is activated: it lets the hard-cap final turn keep the tool
+// DEFINITIONS in-request (so the tools->system->messages prefix — and its
+// prompt-cache prefix — stay byte-identical to prior turns) while forbidding
+// tool USE, so the model can only emit text. Forced values
+// ('required'->{type:'any'}, {name}->{type:'tool'}) are deliberately NOT
+// mapped: Anthropic returns a 400 for any forced tool_choice while
+// extended/adaptive thinking is enabled, and the only caller that sets
+// opts.toolChoice='required' (the forced-first-tool turn) runs with
+// effort/thinking active on reasoning models — activating it would convert a
+// previously-harmless no-op into a hard 400 on exactly that turn. Attached
+// only when the request actually carries tools (see _doSend). Mirrors
+// anthropic-oauth.mjs.
+function toAnthropicToolChoice(toolChoice) {
+    return toolChoice === 'none' ? { type: 'none' } : undefined;
+}
 function deferredAnthropicTools(activeTools, opts) {
     if (opts?.session?.deferredNativeTools !== true) return [];
     // Guard against an all-deferred tools array — the API rejects it with
@@ -458,10 +474,25 @@ function applyAnthropicCacheMarkers(sanitizedMessages, { messageTtl = CACHE_TTL_
         return -1;
     };
 
+    const firstRequestUserPromptIdx = () => {
+        // Iteration-1 fallback: on the very first request a session has only the
+        // current user prompt — no tool_result tail and no earlier user turn, so
+        // both anchors above return -1 and NO message breakpoint is placed. That
+        // left the whole tools+system prefix (~4.2k) uncached on iter1: nothing
+        // was written, so iter2 re-sent it as a fresh full write instead of a
+        // read hit. Anchor the current prompt's tail so the stable prefix is
+        // cache-written on the first ask and read back on the next. Only used
+        // when neither real anchor exists, so later turns still prefer the
+        // tool_result / previous-user-text anchors (never the volatile new
+        // prompt). Synthetic <system-reminder> turns are excluded by hasUserText.
+        if (latestToolResultTailIdx() !== -1 || previousUserTextAnchorIdx() !== -1) return -1;
+        const tailIdx = sanitizedMessages.length - 1;
+        return hasUserText(sanitizedMessages[tailIdx]) ? tailIdx : -1;
+    };
     if (messageTtl !== null) {
         const slots = Math.max(0, Math.min(4, Number(messageSlots) || 0));
         const marked = new Set();
-        const candidates = [latestToolResultTailIdx(), previousUserTextAnchorIdx()];
+        const candidates = [latestToolResultTailIdx(), previousUserTextAnchorIdx(), firstRequestUserPromptIdx()];
         for (const idx of candidates) {
             if (slots <= 0) break;
             if (idx < 0 || marked.has(idx) || !canMarkMessageIdx(idx)) continue;
@@ -578,6 +609,13 @@ export class AnthropicProvider {
             // Anthropic prefix semantics (order: tools → system → messages).
             params.tools = [...nativeTools, ...toAnthropicTools([...(tools || []), ...deferredAnthropicTools(tools || [], opts)])];
         }
+        // tool_choice only when tools are actually present (Anthropic rejects
+        // tool_choice without tools). 'none' rides the hard-cap final turn to
+        // forbid tool USE while keeping the tools prefix stable for cache reuse.
+        if (params.tools) {
+            const toolChoice = toAnthropicToolChoice(opts.toolChoice);
+            if (toolChoice) params.tool_choice = toolChoice;
+        }
         // Known tool names for the shared parseSSEStream leaked-tool-call guard
         // (same guard fixes both Anthropic providers). Recovered leaked calls
         // are only synthesized when they name a tool actually offered here.

package/src/runtime/agent/orchestrator/providers/openai-compat-stream.mjs

@@ -514,7 +514,7 @@ function handleCompatResponsesStreamEvent(event, state, { label, parseResponsesT
             : parseCompletedToolCallArgumentsJson(item.arguments || '{}', label, { id: callId, name: 'tool_search', finishReason: 'done' });
         const call = {
             id: callId,
-            name: 'tool_search',
+            name: 'load_tool',
             // Schema is a plain object ({query,select,limit}); an array must
             // never pass through as args.
             arguments: (_tsArgs && typeof _tsArgs === 'object' && !Array.isArray(_tsArgs)) ? _tsArgs : {},

package/src/runtime/agent/orchestrator/providers/openai-compat-wire.mjs

@@ -107,7 +107,9 @@ export function toOpenAITools(tools) {
 
 export function toResponsesTools(tools) {
     return tools.map((t) => {
-        if (t?.name === 'tool_search') {
+        // load_tool advertises as the OpenAI-native `tool_search` wire type
+        // (legacy 'tool_search' name still accepted for back-compat).
+        if (t?.name === 'load_tool' || t?.name === 'tool_search') {
             return {
                 type: 'tool_search',
                 execution: 'client',
@@ -193,7 +195,7 @@ export function parseResponsesToolCalls(response, label) {
                 : parseCompletedToolCallArgumentsJson(item.arguments || '{}', label, { id: item.call_id || item.id, name: 'tool_search', finishReason });
             out.push({
                 id: item.call_id || item.id,
-                name: 'tool_search',
+                name: 'load_tool',
                 // Schema is a plain object ({query,select,limit}); an array
                 // (parsed JSON or passthrough) must never pass through as args.
                 arguments: (_tsArgs && typeof _tsArgs === 'object' && !Array.isArray(_tsArgs)) ? _tsArgs : {},
@@ -294,7 +296,7 @@ export function toResponsesInputMessage(m, pendingToolMedia = null, customToolCa
         const items = [];
         if (m.content) items.push({ role: 'assistant', content: normalizeContentForOpenAIResponses(m.content, { role: 'assistant' }) });
         for (const tc of m.toolCalls) {
-            if (tc.nativeType === 'tool_search_call' || tc.name === 'tool_search') {
+            if (tc.nativeType === 'tool_search_call' || tc.name === 'load_tool' || tc.name === 'tool_search') {
                 items.push({
                     type: 'tool_search_call',
                     call_id: tc.id,

package/src/runtime/agent/orchestrator/providers/openai-oauth-http-sse.mjs

@@ -451,7 +451,7 @@ export async function sendViaHttpSse({
         }
         const call = {
             id: callId,
-            name: 'tool_search',
+            name: 'load_tool',
             arguments: args,
             nativeType: 'tool_search_call',
         };
@@ -501,7 +501,7 @@ export async function sendViaHttpSse({
                     // mistakes it for a function call by id collision/empty id.
                     if (event.item.id) {
                         pendingCalls.set(event.item.id, {
-                            name: 'tool_search',
+                            name: 'load_tool',
                             callId: event.item.call_id || '',
                             kind: 'tool_search',
                         });

package/src/runtime/agent/orchestrator/providers/openai-oauth.mjs

@@ -444,7 +444,7 @@ function convertMessagesToResponsesInput(messages, opts = {}) {
             // reasoning in `input` triggers "Duplicate item".
             if (m.content) out.push({ role: 'assistant', content: normalizeContentForOpenAIResponses(m.content, { role: 'assistant' }) });
             for (const tc of m.toolCalls) {
-                if (tc.nativeType === 'tool_search_call' || tc.name === 'tool_search') {
+                if (tc.nativeType === 'tool_search_call' || tc.name === 'load_tool' || tc.name === 'tool_search') {
                     out.push({
                         type: 'tool_search_call',
                         call_id: tc.id,
@@ -480,7 +480,7 @@ function convertMessagesToResponsesInput(messages, opts = {}) {
 }
 
 function toOpenAIResponsesTool(t) {
-    if (t?.name === 'tool_search') {
+    if (t?.name === 'load_tool' || t?.name === 'tool_search') {
         return {
             type: 'tool_search',
             execution: 'client',

package/src/runtime/agent/orchestrator/providers/openai-ws-stream.mjs

@@ -355,7 +355,7 @@ export async function _streamResponse({
         if (!callId || toolCalls.some((call) => call.id === callId)) return;
         const call = {
             id: callId,
-            name: 'tool_search',
+            name: 'load_tool',
             arguments: parseToolSearchArgs(item.arguments),
             nativeType: 'tool_search_call',
         };

package/src/runtime/agent/orchestrator/session/agent-loop.mjs

@@ -291,8 +291,10 @@ export async function agentLoop(provider, messages, model, tools, onToolCall, cw
         if (iterations >= maxLoopIterations) {
             // Final-answer turn: instead of breaking mid-transcript (which
             // yields an empty final for locator-style agents that never got to
-            // answer), give the model ONE tool-less text turn to wrap up, then
-            // stop (empty sendTools + refusal stubs if tools are requested).
+            // answer), give the model ONE text-only turn to wrap up, then stop.
+            // Tool DEFINITIONS stay in-request (stable cache prefix) but tool
+            // USE is forbidden via tool_choice:'none'; any tool call a
+            // toolChoice-ignoring provider still emits gets a refusal stub.
             if (_capFinalTurnUsed) {
                 process.stderr.write(`[loop] hard iteration cap ${maxLoopIterations} reached (sess=${sessionId || 'unknown'}); stopping loop.\n`);
                 terminatedByCap = true;
@@ -362,15 +364,22 @@ export async function agentLoop(provider, messages, model, tools, onToolCall, cw
         const nextIteration = iterations + 1;
         opts.iteration = nextIteration;
         opts.providerState = providerState;
-        if (forcedFirstTool && toolCallsTotal === 0) {
+        if (_capFinalToolsDisabled) {
+            // Hard-cap final turn: forbid tool USE (tool_choice:'none') instead
+            // of stripping tool DEFINITIONS. Sending tools:[] changed the
+            // tools→system→messages prefix chain, so Anthropic could no longer
+            // prefix-match and re-prefilled the whole prompt (~10k, cache
+            // read=0) on the final capped turn. Keeping the tools in-request
+            // holds the prefix byte-stable; 'none' makes the model emit text
+            // only. Overrides the forced-first-tool path below.
+            opts.toolChoice = 'none';
+        } else if (forcedFirstTool && toolCallsTotal === 0) {
             opts.toolChoice = 'required';
         } else {
             delete opts.toolChoice;
         }
-        // Hard-cap final turn: send NO tool definitions so the provider can
-        // only emit text. Overrides the forced-first-tool path.
         const sendTools = _capFinalToolsDisabled
-            ? []
+            ? tools
             : (forcedFirstToolDef && toolCallsTotal === 0 ? [forcedFirstToolDef] : tools);
         // Eager-dispatch queue: when the provider streams a tool-call event,
         // start read-only tools immediately so execution overlaps with the
@@ -387,7 +396,15 @@ export async function agentLoop(provider, messages, model, tools, onToolCall, cw
             getNextIteration: () => nextIteration,
             repeatFailLimit: REPEAT_FAIL_LIMIT,
         });
-        opts.onToolCall = eager.onToolCall;
+        // Hard-cap final turn: forbid eager dispatch. Tools are still sent (to
+        // hold the cache prefix) but tool_choice:'none' means Anthropic emits
+        // no calls; a toolChoice-IGNORING provider could still stream calls,
+        // and an attached onToolCall would eager-run read-only tools mid-stream
+        // (real cost/UI/network side effects) whose results are then discarded
+        // by the refusal-stub path. Leave it unset so nothing dispatches; opts
+        // is reused across iterations but onToolCall is cleared to undefined
+        // after send() below, so non-cap iterations are unaffected.
+        opts.onToolCall = _capFinalToolsDisabled ? undefined : eager.onToolCall;
         // Reattach separated tool results, then drop only truly dangling
         // assistant/orphan pairs before the provider sees the transcript.
         repairTranscriptBeforeProviderSend(messages, sessionId);

package/src/runtime/agent/orchestrator/session/loop/completion-guards.mjs

@@ -24,8 +24,9 @@ export function crossTurnSignature(name, args) {
 
 // Tool names that are non-eager (no readOnlyHint) but are NOT edits/progress —
 // they must not reset the escalation ladder's "zero edit" condition. Skill /
-// recall / agent / task / cwd / tool_search are exploration/meta plumbing.
-const NON_PROGRESS_TOOLS = new Set(['Skill', 'recall', 'agent', 'task', 'cwd', 'tool_search']);
+// recall / agent / task / cwd / load_tool are exploration/meta plumbing.
+// (tool_search kept as legacy alias for old transcripts.)
+const NON_PROGRESS_TOOLS = new Set(['Skill', 'recall', 'agent', 'task', 'cwd', 'load_tool', 'tool_search']);
 
 // True when a successfully-executed tool represents real edit/progress. A tool
 // counts as progress only if its def lacks readOnlyHint (not eager) AND it is

package/src/runtime/agent/orchestrator/session/loop/deferred-call-through.mjs

@@ -1,7 +1,7 @@
 // Deferred catalog call-through: inactive catalog tool_use → discovery bookkeeping
 // then normal executeTool routing (runtime errors only; no pre-dispatch schema).
 import { clean } from '../../../../../session-runtime/session-text.mjs';
-import { isReadonlySelectable, selectDeferredTools } from '../../../../../session-runtime/tool-catalog.mjs';
+import { deferredCatalogUnion, isReadonlySelectable, selectDeferredTools } from '../../../../../session-runtime/tool-catalog.mjs';
 
 /** Skill-list plumbing only; mutation/MCP/builtins must use the catalog+mode gate. */
 const INACTIVE_INFRA_BYPASS = new Set(['skills_list', 'skill_view']);
@@ -13,7 +13,10 @@ function isActiveSessionTool(session, name) {
 }
 
 function lookupDeferredCatalogTool(session, name) {
-    const catalog = Array.isArray(session?.deferredToolCatalog) ? session.deferredToolCatalog : [];
+    // Union of the boot-frozen catalog and the late-connected MCP catalog so a
+    // direct call to a tool whose server connected after boot resolves and
+    // auto-loads (selectDeferredTools promotes it onto session.tools).
+    const catalog = deferredCatalogUnion(session);
     const key = clean(name);
     if (!key) return null;
     for (const tool of catalog) {
@@ -66,7 +69,7 @@ export function prepareDeferredToolCallThrough(sessionRef, name, _args) {
     if (resolvedMode === null) {
         if (!isReadonlySelectable(tool)) {
             return denyDeferredCallThrough(
-                `Error: tool "${toolLabel}" is deferred and cannot be auto-loaded without a resolved tool mode; use tool_search or load it explicitly.`,
+                `Error: tool "${toolLabel}" is deferred and cannot be auto-loaded without a resolved tool mode; load it with load_tool names:["${toolLabel}"].`,
             );
         }
     } else if (resolvedMode === 'readonly' && !isReadonlySelectable(tool)) {

package/src/runtime/agent/orchestrator/session/loop/tool-helpers.mjs

@@ -81,7 +81,7 @@ export function resolveToolResultAfterHook(originalResult, hookResult) {
 }
 
 export function parseNativeToolSearchPayload(toolName, result) {
-    if (toolName !== 'tool_search' || typeof result !== 'string') return null;
+    if ((toolName !== 'load_tool' && toolName !== 'tool_search') || typeof result !== 'string') return null;
     try {
         const parsed = JSON.parse(result);
         const native = parsed?.nativeToolSearch;