mixdog 0.9.23 → 0.9.25

package/src/runtime/agent/orchestrator/mcp/child-tree.mjs

@@ -86,6 +86,45 @@ export async function collectDescendants(rootPid) {
     return descendantsOf(childrenOf, rootPid);
 }
 
+/**
+ * Immediate, non-blocking tree kill for a transport whose MCP handshake never
+ * completed (shutdown-during-connect). Unlike shutdownStdioChild there is no
+ * grace wait and no identity-checked enumeration on Windows — the ChildProcess
+ * handle is live, so the pid is current, and taskkill /T reaps the still-
+ * parented tree. Everything is unref'd/fire-and-forget so the kill can never
+ * hold the caller's event loop open (the caller is a process about to exit).
+ */
+export function killStdioChildTreeFast(transport) {
+    const proc = transport?._process;
+    const pid = (typeof transport?.pid === 'number' ? transport.pid : null) ?? proc?.pid ?? null;
+    if (!pid) return false;
+    if (proc && (proc.exitCode !== null || proc.signalCode !== null)) return false;
+    try { proc?.unref?.(); } catch { /* ignore */ }
+    for (const s of [proc?.stdin, proc?.stdout, proc?.stderr]) {
+        try { s?.unref?.(); } catch { /* ignore */ }
+        try { s?.destroy?.(); } catch { /* ignore */ }
+    }
+    if (isWin) {
+        try {
+            const cp = spawn('taskkill', ['/PID', String(pid), '/T', '/F'], {
+                windowsHide: true,
+                detached: true,
+                stdio: 'ignore',
+            });
+            cp.unref();
+        } catch { /* ignore */ }
+        return true;
+    }
+    // POSIX: cheap ps enumerate, then SIGKILL descendants + root. Best-effort
+    // and un-awaited; a straggler orphan is reparented to init, not leaked by us.
+    void collectDescendants(pid).then((pids) => {
+        for (const p of [...pids, pid]) {
+            try { process.kill(p, 'SIGKILL'); } catch { /* ignore */ }
+        }
+    }).catch(() => { /* ignore */ });
+    return true;
+}
+
 function isAlive(pid) {
     try {
         process.kill(pid, 0);

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

@@ -4,7 +4,7 @@ import { join } from 'path';
 import { tmpdir } from 'os';
 import { randomUUID } from 'crypto';
 import { smartReadTruncate } from '../tools/builtin/read-formatting.mjs';
-import { shutdownStdioChild } from './child-tree.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
@@ -16,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;
@@ -97,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}`);
@@ -234,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);
@@ -339,6 +371,22 @@ 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 _closeServer(server);
@@ -382,7 +430,13 @@ async function _closeServer(server) {
     try { await server.client.close(); }
     catch { /* ignore */ }
 }
-async function connectServer(name, cfg) {
+// 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,
@@ -390,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);
@@ -472,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/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/manager/runtime-liveness.mjs

@@ -108,6 +108,7 @@ export function markSessionAskStart(id) {
     entry.lastStreamDeltaAt = null;
     entry.lastToolCall = null;
     entry.toolStartedAt = null;
+    entry.toolSelfDeadlineMs = null;
     entry.lastError = null;
     // A new ask starts a fresh turn lifecycle — clear any stale empty-final
     // classification from the prior turn so inspectBridgeEntry doesn't keep
@@ -166,11 +167,18 @@ export async function markSessionStreamDelta(id) {
     }
     entry.updatedAt = now;
 }
-export function markSessionToolCall(id, toolName) {
+export function markSessionToolCall(id, toolName, selfDeadlineMs) {
     if (!id) return;
     const entry = _touchRuntime(id);
     entry.stage = 'tool_running';
     entry.lastToolCall = toolName || null;
+    // Self-enforced deadline (ms) for tools that kill themselves at a known
+    // budget (shell timeout / task wait). The watchdog raises the tool-running
+    // ceiling to this + grace instead of aborting at toolRunningMs. Null/<=0
+    // means unknown -> plain toolRunningMs behavior.
+    entry.toolSelfDeadlineMs = (typeof selfDeadlineMs === 'number' && selfDeadlineMs > 0)
+        ? selfDeadlineMs
+        : null;
     entry.toolStartedAt = Date.now();
     entry.lastProgressAt = entry.toolStartedAt;
     entry.updatedAt = entry.toolStartedAt;
@@ -289,6 +297,8 @@ export function getSessionProgressSnapshot(sessionId) {
         firstActivityAt,
         lastStreamDeltaAt: entry.lastStreamDeltaAt || 0,
         toolStartedAt: entry.toolStartedAt || 0,
+        currentTool: entry.lastToolCall || null,
+        toolSelfDeadlineMs: entry.toolSelfDeadlineMs || 0,
         lastProgressAt: entry.lastProgressAt || 0,
         updatedAt: entry.updatedAt || 0,
         hasFirstActivity: Boolean(firstActivityAt && (!askStartedAt || firstActivityAt >= askStartedAt)),

package/src/runtime/agent/orchestrator/session/manager/session-lifecycle.mjs

@@ -167,8 +167,9 @@ export function createSession(opts) {
     //   - read-only roles (reviewer / debugger / hidden retrieval, i.e. any
     //     session resolving to permission 'read') -> 'readonly' bundle:
     //     read builtins (code_graph/find/glob/list/grep/read) + retrieval
-    //     (explore/search/web_fetch/Skill), no apply_patch/shell/task, no
-    //     MCP-write. applyToolPermissionNarrowing('read') below trims the
+    //     (explore/search/web_fetch/Skill) + shell/task for self-verification
+    //     (agent-owned readonly bundle only), no apply_patch, no MCP-write.
+    //     applyToolPermissionNarrowing('read') below trims the
     //     bundle to AGENT_STRING_PERMISSION_READ_ALLOW so the final surface is
     //     bit-identical across these roles regardless of MCP registry state.
     //   - write roles (worker / heavy-worker / maintainer / …) -> 'full'
@@ -188,7 +189,10 @@ export function createSession(opts) {
     // fail closed (zero tools) rather than silently falling back to the full
     // preset, which would grant the role more surface than declared.
     if (ownerIsAgent) {
-        toolsForRouting = applyToolPermissionNarrowing(toolsForRouting, toolPermission, opts.agent || null);
+        // Pass the RESOLVED agent (opts.agent || opts.role): narrowing keys
+        // retrieval/locator roles (explore etc.) off this name to strip
+        // shell/task; verifying read roles (reviewer/debugger) keep them.
+        toolsForRouting = applyToolPermissionNarrowing(toolsForRouting, toolPermission, resolvedAgent);
     }
 
     const { baseRules, stableSystemContext, sessionMarker, volatileTail } = composeSystemPrompt({

package/src/runtime/agent/orchestrator/session/manager/tool-resolution.mjs

@@ -74,14 +74,39 @@ const AGENT_STRING_PERMISSION_READ_ALLOW = Object.freeze([
     'list',
     'grep',
     'read',
+    // shell/task: read-role agents (reviewer/debugger) must run their own
+    // verification (tests/repro). task is required because shell's
+    // auto-background transition settles with a bare jobId — agent sessions
+    // get no completion notification, so `task wait/read` is the only way to
+    // collect a long-running result. apply_patch stays excluded: read roles
+    // keep the no-edit contract.
+    'shell',
+    'task',
     'explore',
     'search',
     'web_fetch',
     'Skill',
 ]);
 
-function stringToolPermissionAllowList(toolPermission) {
-    if (toolPermission === 'read') return AGENT_STRING_PERMISSION_READ_ALLOW;
+// Retrieval/locator roles never self-verify, so they keep the historical
+// no-shell read surface. Covers hidden retrieval agents (kind 'retrieval')
+// AND public wrapper roles (explore + any invokedBy wrapper) — the same set
+// pre-dispatch-deny treats as recursive wrappers. Only verifying read roles
+// (reviewer/debugger) get shell/task.
+const AGENT_STRING_PERMISSION_READ_RETRIEVAL_ALLOW = Object.freeze(
+    AGENT_STRING_PERMISSION_READ_ALLOW.filter((n) => n !== 'shell' && n !== 'task'),
+);
+
+function isRetrievalToolRole(agent) {
+    if (!agent) return false;
+    if (getHiddenAgent(agent)?.kind === 'retrieval') return true;
+    return Boolean(recursiveWrapperToolNameForPublicAgent(agent));
+}
+
+function stringToolPermissionAllowList(toolPermission, { retrieval = false } = {}) {
+    if (toolPermission === 'read') {
+        return retrieval ? AGENT_STRING_PERMISSION_READ_RETRIEVAL_ALLOW : AGENT_STRING_PERMISSION_READ_ALLOW;
+    }
     if (toolPermission === 'read-write') return AGENT_STRING_PERMISSION_READ_WRITE_ALLOW;
     if (toolPermission === 'none') return [];
     return null;
@@ -109,7 +134,7 @@ const AGENT_STRING_PERMISSION_READ_WRITE_ALLOW = Object.freeze([
 
 export function applyToolPermissionNarrowing(tools, toolPermission, warnRole = null) {
     if (toolPermission === 'none') return [];
-    const allowList = stringToolPermissionAllowList(toolPermission);
+    const allowList = stringToolPermissionAllowList(toolPermission, { retrieval: isRetrievalToolRole(warnRole) });
     if (allowList) {
         const allowSet = new Set(allowList.map((n) => String(n).toLowerCase()));
         return tools.filter((t) => allowSet.has(String(t?.name || '').toLowerCase()));
@@ -203,7 +228,7 @@ export function resolveSessionTools(toolSpec, skills, { ownerIsAgentSession = fa
     // time (loop.mjs), so the schema bytes stay bit-identical across roles /
     // cwds and the provider cache shard does not fragment.
     const skillTools = buildSkillToolDefs(skills, { ownerIsAgentSession });
-    return _computeBaseTools(toolSpec, mcp, skillTools);
+    return _computeBaseTools(toolSpec, mcp, skillTools, { ownerIsAgentSession });
 }
 
 export function previewSessionTools(toolSpec, skills = [], options = {}) {
@@ -230,7 +255,7 @@ function _dedupByName(tools) {
 // Tools with agentHidden:true are stripped from agent sessions at schema
 // build time (see deny filtering below). No code-level name list needed.
 
-function _computeBaseTools(toolSpec, mcp, skillTools) {
+function _computeBaseTools(toolSpec, mcp, skillTools, { ownerIsAgentSession = false } = {}) {
     if (Array.isArray(toolSpec)) {
         if (toolSpec.length === 0) {
             // Explicit "no tools" — skill meta tools still travel so the model
@@ -285,7 +310,16 @@ function _computeBaseTools(toolSpec, mcp, skillTools) {
             return _dedupByName([...mcp, ...skillTools]);
         case 'readonly': {
             const readTools = ALL_BUILTIN_SESSION_TOOLS.filter(t => READONLY_TOOL_NAMES.has(t.name));
-            return _dedupByName([...readTools, ...mcp, ...skillTools]);
+            // Read-ROLE agent sessions (reviewer/debugger) must self-verify, so
+            // their base bundle carries shell/task defs. The 'read' permission
+            // allowlist (AGENT_STRING_PERMISSION_READ_ALLOW) is a pure FILTER —
+            // it can only keep tools already assembled here, so without this the
+            // allowlist's shell/task entries were dead letters. Non-agent
+            // 'readonly' profiles stay strictly read-only.
+            const verifyTools = ownerIsAgentSession
+                ? ALL_BUILTIN_SESSION_TOOLS.filter(t => t.name === 'shell' || t.name === 'task')
+                : [];
+            return _dedupByName([...readTools, ...verifyTools, ...mcp, ...skillTools]);
         }
         case 'full':
         default:

package/src/runtime/agent/orchestrator/session/tool-batch.mjs

@@ -11,6 +11,7 @@ import { takeApplyPatchUiDiff } from '../tools/patch.mjs';
 import { compressToolResult } from '../tools/result-compression.mjs';
 import { appendAgentTrace, traceAgentTool, traceAgentToolFailure } from '../agent-trace.mjs';
 import { markSessionToolCall, updateSessionStage } from './manager.mjs';
+import { resolveToolSelfDeadlineMs } from '../agent-runtime/agent-progress-watchdog.mjs';
 import { classifyResultKind } from './result-classification.mjs';
 import { normalizeToolEnvelope } from './tool-envelope.mjs';
 import { maybeOffloadToolResult } from './tool-result-offload.mjs';
@@ -150,7 +151,7 @@ export async function processToolBatch(ctx) {
                     continue;
                 }
             }
-            if (sessionId) markSessionToolCall(sessionId, call.name);
+            if (sessionId) markSessionToolCall(sessionId, call.name, resolveToolSelfDeadlineMs(call.name, call.arguments));
             let result;
             let toolStartedAt;
             let toolEndedAt;