mixdog 0.7.1

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

@@ -0,0 +1,1478 @@
+import { classifyResultKind } from './result-classification.mjs';
+import { executeMcpTool, isMcpTool, mcpToolHasField } from '../mcp/client.mjs';
+import { canonicalizeBuiltinToolName, executeBuiltinTool, formatUnknownBuiltinToolMessage, isBuiltinTool } from '../tools/builtin.mjs';
+import { executeBashSessionTool } from '../tools/bash-session.mjs';
+import { executePatchTool } from '../tools/patch.mjs';
+import { executeCodeGraphTool, isCodeGraphTool } from '../tools/code-graph.mjs';
+import { executeInternalTool, isInternalTool } from '../internal-tools.mjs';
+import { collectSkillsCached, loadSkillContent } from '../context/collect.mjs';
+import { traceBridgeLoop, traceBridgeTool, traceBridgeTrim, estimateProviderPayloadBytes, messagePrefixHash } from '../bridge-trace.mjs';
+import { markSessionToolCall, updateSessionStage, SessionClosedError, getSessionAbortSignal } from './manager.mjs';
+import { trimMessages, estimateRequestReserveTokens } from './trim.mjs';
+import { isContextOverflowError } from '../providers/retry-classifier.mjs';
+import { classifyBashFileLookupCommand, stripSoftWarns } from '../tool-loop-guard.mjs';
+import { maybeOffloadToolResult } from './tool-result-offload.mjs';
+import { tryReadCached, setReadCached, invalidatePathForSession, markPostEdit, consumePostEditMark, clearReadDedupSession, extractTouchedPathsFromPatch, tryScopedToolCached, setScopedToolCached, clearScopedToolsForSession, clearScopedToolsForSessionPaths, invalidatePrefetchCache } from './read-dedup.mjs';
+import { createScopedCacheOutcome } from './cache/scoped-cache-outcome.mjs';
+import { createHash } from 'crypto';
+
+// Tool-name classification for cross-turn read dedup.
+// Strips the MCP prefix so direct calls and MCP-wrapped calls share the
+// same cache.
+function _stripMcpPrefix(name) {
+    return typeof name === 'string' && name.startsWith(MCP_TOOL_PREFIX)
+        ? name.slice(MCP_TOOL_PREFIX.length) : name;
+}
+function _isReadTool(name) {
+    return _stripMcpPrefix(name) === 'read';
+}
+function _isScalarWriteEditTool(name) {
+    const n = _stripMcpPrefix(name);
+    return n === 'write' || n === 'edit';
+}
+function _isMutationTool(name) {
+    const n = _stripMcpPrefix(name);
+    return n === 'apply_patch' || n === 'write' || n === 'edit';
+}
+const SCOPED_CACHEABLE_TOOLS = new Set([
+    'code_graph',
+    'grep',
+    'list',
+    'glob',
+]);
+function _isScopedCacheableTool(name) {
+    const n = _stripMcpPrefix(name);
+    return SCOPED_CACHEABLE_TOOLS.has(n);
+}
+function _isBashTool(name) {
+    const n = _stripMcpPrefix(name);
+    return n === 'bash' || n === 'bash_session';
+}
+
+// classifyResultKind is imported from result-classification.mjs at the top of
+// this file; import it from there directly rather than via this module.
+
+// Canonical signature for intra-turn duplicate detection. Sorting keys
+// produces a stable hash regardless of arg-object key order. Anything
+// non-serializable falls back to String(args) — still deterministic for
+// the model's typical structured-arg shape.
+function _canonicalArgs(args) {
+    if (args == null || typeof args !== 'object') {
+        try { return JSON.stringify(args); } catch { return String(args); }
+    }
+    try {
+        const keys = Object.keys(args).sort();
+        const sorted = {};
+        for (const k of keys) sorted[k] = args[k];
+        return JSON.stringify(sorted);
+    } catch { return String(args); }
+}
+function _intraTurnSig(name, args) {
+    return createHash('sha256').update(`${name}:${_canonicalArgs(args)}`).digest('hex').slice(0, 16);
+}
+
+// Shared pre-dispatch deny — single source of truth for role/scope/permission
+// rejects. Called by BOTH the eager dispatch path (startEagerTool) and the
+// serial dispatch path (executeTool body). Returns null when the call is
+// allowed to proceed; otherwise returns the Error string the serial path
+// would emit. The eager caller ignores the message body and just treats
+// non-null as "do not start eager".
+//
+// Predicates are kept in the same order as the legacy serial branch so a
+// bridge-owned control-plane tool fails on _bridgeOwned+_controlPlaneTool
+// FIRST (not on permission/wrapper checks) — matches the prior wording.
+// Bridge workers are sandboxed to code/research tools. They must never reach
+// owner/host control surfaces: session management, the ENTIRE channels module
+// (Discord messaging, schedules, webhook/config, channel-bridge toggle,
+// command injection), or host input injection. Explicit name list (no imports)
+// keeps this hot-path gate dependency-free; add new owner/channel tools here.
+const WORKER_DENIED_TOOLS = new Set([
+    // session control-plane — unified into the single `bridge` tool
+    // (type=spawn|send|close|list). Denying the one name blocks all worker
+    // session control. Legacy names kept for defense-in-depth against any
+    // stale catalog entry that still advertises them.
+    'bridge', 'close_session', 'list_sessions', 'create_session',
+    // channels module (owner/Discord-facing)
+    'reply', 'react', 'edit_message', 'download_attachment', 'fetch',
+    'schedule_status', 'trigger_schedule', 'schedule_control',
+    'activate_channel_bridge', 'reload_config', 'inject_command',
+    // host input injection
+    'inject_input',
+]);
+function _preDispatchDeny(call, toolKind, sessionRef) {
+    const name = call?.name;
+    if (typeof name !== 'string' || !name) return null;
+    const _bridgeOwned = sessionRef?.scope?.startsWith?.('bridge:') || sessionRef?.owner === 'bridge';
+    const _controlPlaneTool = WORKER_DENIED_TOOLS.has(name);
+    if (_bridgeOwned && _controlPlaneTool) {
+        return `Error: control-plane tool "${name}" is Lead-only and not available to bridge workers.`;
+    }
+    const noToolRole = sessionRef?.role === 'cycle1-agent' || sessionRef?.role === 'cycle2-agent';
+    if (noToolRole) {
+        return `Error: tool "${name}" is not available in role "${sessionRef.role}". Re-emit the answer as pipe-separated text per the role's output format (first character a digit, NO tool_use blocks, NO JSON, NO prose, NO apology).`;
+    }
+    if (isBlockedHiddenWrapperCall(name, sessionRef)) {
+        return `Error: tool "${name}" is the wrapper your role (${sessionRef?.role || 'hidden'}) backs. Calling it would spawn another hidden agent of the same kind — use direct read/grep/glob/code_graph instead.`;
+    }
+    const effectivePermission = effectiveToolPermission(sessionRef);
+    const permissionBlocked = isBlockedByPermission(name, toolKind, effectivePermission);
+    if (permissionBlocked && effectivePermission === 'mcp') {
+        return `Error: tool "${name}" is not available on this session (permission=mcp). Use MCP/internal retrieval tools only.`;
+    }
+    if (permissionBlocked && effectivePermission === 'read') {
+        return `Error: tool "${name}" is not available on this session (permission=read). Use Mixdog MCP read/grep/glob/recall/search/explore instead.`;
+    }
+    if (permissionBlocked && effectivePermission && typeof effectivePermission === 'object') {
+        return `Error: tool "${name}" is not permitted on this session by the role's allow/deny permission policy.`;
+    }
+    return null;
+}
+/** Exported for smoke tests — same runtime deny as the agent loop. */
+export function preDispatchDenyForSession(sessionRef, call, toolKind = 'builtin') {
+    return _preDispatchDeny(call, toolKind, sessionRef);
+}
+import { compressToolResult, recordToolBatch } from '../tools/result-compression.mjs';
+
+
+import { isHiddenRole } from '../internal-roles.mjs';
+import { createRequire } from 'module';
+import { readFileSync as _readFileSync } from 'fs';
+import { fileURLToPath } from 'url';
+import { dirname, resolve as resolvePath, isAbsolute } from 'path';
+// Load the CJS permission evaluator. The hooks/ directory lives two levels
+// above src/agent/orchestrator/session/, so we walk up from __dirname.
+const _require = createRequire(import.meta.url);
+const _hooksLib = resolvePath(dirname(fileURLToPath(import.meta.url)), '../../../../hooks/lib/permission-evaluator.cjs');
+const { evaluatePermission: _evaluatePermission } = _require(_hooksLib);
+const MCP_TOOL_PREFIX = 'mcp__plugin_mixdog_mixdog__';
+const SAFETY_TRIM_PERCENT = 0.90;
+// Stricter budget used for the one-shot retry after a provider rejects a send
+// with a context-window-exceeded error. 0.60×contextWindow forces older
+// non-system / non-latest turns to drop hard so the retry fits even when the
+// pre-send estimate under-counted provider-side bytes (tool schemas, framing,
+// provider-internal token accounting). Used exactly once per send; see the
+// retry block around provider.send below.
+const OVERFLOW_RETRY_TRIM_PERCENT = 0.60;
+
+// Cache-hit results always inline the cached body. The earlier size-gated
+// `[cache-hit-ref]` branch confused bridge workers whose context did not
+// contain the referenced prior tool_result, triggering shell-cat detours.
+// Hard iteration ceiling for every agent loop. Reset to 0 whenever the
+// transcript is compacted (see the trim block below): a long task that keeps
+// compacting can proceed past this count, while a tight NON-compacting loop
+// still stops here and returns the accumulated transcript.
+const MAX_LOOP_ITERATIONS = 200;
+// Consecutive identical-AND-failing tool calls (same name+args, error result)
+// tolerated across iterations before the loop refuses to re-execute and steers
+// the model to change approach. Distinct from the hard iteration cap above:
+// this catches tight deterministic-failure loops (e.g. a command that errors
+// the same way every time) far earlier than 100 iterations.
+const REPEAT_FAIL_LIMIT = 3;
+const _HIDDEN_ROLES_JSON = resolvePath(dirname(fileURLToPath(import.meta.url)), '../../../../defaults/hidden-roles.json');
+let _hiddenRolesCache = null;
+function _getHiddenRoles() {
+    if (_hiddenRolesCache) return _hiddenRolesCache;
+    try {
+        _hiddenRolesCache = JSON.parse(_readFileSync(_HIDDEN_ROLES_JSON, 'utf8'));
+    } catch { _hiddenRolesCache = { roles: [] }; }
+    return _hiddenRolesCache;
+}
+// Transcript pairing guard. Anthropic 400-rejects when an assistant message
+// ends with tool_use blocks and the next message isn't tool results for
+// those exact ids. abort/timeout/error race in the loop body can leave a
+// dangling assistant tool_use at the tail (e.g. the structure_probe loop
+// running 12 deep then aborting between push-assistant and push-tool).
+// Strip any trailing assistant tool_use that has no matching tool result
+// so provider.send sees a valid transcript instead of leaking the 400 to
+// the user. Repair runs every iteration but is a no-op on healthy paths.
+function _ensureTranscriptPairing(msgs, sessionId) {
+    // Walk backwards to find the last assistant message that emitted
+    // tool_use, then validate that every id has a matching tool result
+    // inside the CONTIGUOUS tool-message block immediately following it.
+    // Earlier guard splice'd the entire tail — which silently deleted any
+    // user prompt appended after the dangling assistant by manager.mjs:
+    // when the guard fired with shape
+    //     [..., assistant{a,b}, tool{a}, user{new prompt}]
+    // the splice removed user{new prompt} along with the orphan suffix.
+    // Fix: remove only assistant + the contiguous tool block; preserve
+    // anything past it (user / system / next assistant) untouched.
+    let popped = 0;
+    while (msgs.length > 0) {
+        let lastAssistantIdx = -1;
+        for (let i = msgs.length - 1; i >= 0; i--) {
+            const m = msgs[i];
+            if (m?.role === 'assistant' && Array.isArray(m.toolCalls) && m.toolCalls.length > 0) {
+                lastAssistantIdx = i;
+                break;
+            }
+        }
+        if (lastAssistantIdx === -1) break;
+        // Collect the contiguous tool messages directly after this assistant.
+        // Anything past that block is unrelated (next user prompt, system
+        // marker, etc.) and must survive the repair.
+        let toolBlockEnd = lastAssistantIdx + 1;
+        while (toolBlockEnd < msgs.length && msgs[toolBlockEnd]?.role === 'tool') {
+            toolBlockEnd += 1;
+        }
+        const toolBlock = msgs.slice(lastAssistantIdx + 1, toolBlockEnd);
+        const ids = msgs[lastAssistantIdx].toolCalls.map(c => c.id);
+        const matched = ids.every(id => toolBlock.some(m => m.toolCallId === id));
+        if (matched) break;
+        const removed = toolBlockEnd - lastAssistantIdx;
+        msgs.splice(lastAssistantIdx, removed);
+        popped += removed;
+    }
+    // Second sweep — catch dangling tool results that survived the
+    // contiguous-block splice. Anthropic strict spec requires every
+    // tool result to sit in a contiguous block right after the
+    // assistant whose toolCalls produced it; a `[..., assistant{a,b},
+    // tool{a}, user, tool{b}]` shape leaves tool{b} orphaned even
+    // after assistant + tool{a} are repaired by the loop above.
+    // Walk back from each tool message to the nearest non-tool
+    // ancestor; if it is not an assistant whose toolCalls include
+    // this id, drop the orphan.
+    for (let i = msgs.length - 1; i >= 0; i--) {
+        const m = msgs[i];
+        if (m?.role !== 'tool') continue;
+        if (!m.toolCallId) {
+            msgs.splice(i, 1);
+            popped += 1;
+            continue;
+        }
+        let prevIdx = i - 1;
+        while (prevIdx >= 0 && msgs[prevIdx]?.role === 'tool') prevIdx--;
+        const anchor = prevIdx >= 0 ? msgs[prevIdx] : null;
+        const anchorOk = anchor?.role === 'assistant'
+            && Array.isArray(anchor.toolCalls)
+            && anchor.toolCalls.some(c => c.id === m.toolCallId);
+        if (!anchorOk) {
+            msgs.splice(i, 1);
+            popped += 1;
+        }
+    }
+    if (popped > 0 && sessionId) {
+        try { process.stderr.write(`[transcript-repair] sess=${sessionId} popped=${popped} dangling assistant tool_use\n`); } catch {}
+    }
+}
+
+// Write-class tools that a permission=read session must not execute. The
+// schema still advertises them to keep one unified shard; this runtime set
+// is the fail-safe reject at call time.
+const READ_BLOCKED_TOOLS = new Set([
+    'bash', 'bash_session',
+    'write',
+    'edit',
+    'apply_patch',
+]);
+const MCP_ONLY_ALLOWED_KINDS = new Set(['mcp', 'internal', 'skill']);
+// Wrappers that hidden retrieval roles back. Hidden roles MUST NOT call
+// these or they spawn another hidden agent of the same kind — nested chain
+// + token burn. Block at call time; the role's rule prompt also says so.
+const RETRIEVAL_WRAPPERS = new Set(['recall', 'search', 'explore']);
+// Hidden roles that may call specific retrieval wrappers. Default policy
+// blocks all hidden→wrapper calls; roles listed here have a documented
+// need:
+//   - scheduler-task / webhook-handler: state-changing agents whose
+//     tasks routinely require both reach-back into past context
+//     (`recall`) and fresh external info (`search`).
+const HIDDEN_ROLE_WRAPPER_ALLOWLIST = {
+    'scheduler-task': new Set(['recall', 'search']),
+    'webhook-handler': new Set(['recall', 'search']),
+};
+// Eager-dispatch: tools with readOnlyHint:true in their declaration are safe
+// to execute during SSE parsing so tool work overlaps with the rest of the
+// stream. Writes, bash, MCP and skills stay serial after send() returns.
+function isEagerDispatchable(name, tools) {
+    if (!Array.isArray(tools)) return false;
+    const def = tools.find(t => t?.name === name);
+    return def?.annotations?.readOnlyHint === true;
+}
+// ── Bridge-worker permission enforcement ──────────────────────────────────────
+// Mirrors the PreToolUse hook evaluation for tool calls that originate inside a
+// bridge worker session. Worker dispatch previously bypassed the hook pipeline
+// entirely; this guard closes that gap by running the same evaluator inline.
+//
+// `ask` is treated as deny here — forwarding `ask` decisions to the channel
+// UI approval flow needs bidirectional prompt plumbing that does not exist.
+function _checkWorkerPermission(toolName, toolInput, sessionRef) {
+    const bareToolName = _stripMcpPrefix(toolName);
+    if (sessionRef?.owner === 'bridge' && bareToolName === 'bash') {
+        const cmdClass = classifyBashFileLookupCommand(toolInput?.command);
+        if (cmdClass) {
+            return `Error: bridge worker bash file lookup blocked (${cmdClass}). Use Mixdog MCP read/grep/glob/list directly; bash is only for build/test/run/git-style commands.`;
+        }
+    }
+    // Even when no explicit permissionMode is propagated to the worker, run
+    // the evaluator under the most restrictive baseline ('default') so the
+    // bypass-proof hard-deny patterns (UNC paths, /etc, C:/Windows, etc.)
+    // and the user's settings.json deny rules still apply. Previously a
+    // missing permissionMode short-circuited to null and the worker
+    // ran ungated — a model could dispatch a bridge to read or write
+    // protected paths even when the same call would have been denied for
+    // the parent. Callers that genuinely need bypassPermissions can still
+    // forward it explicitly via session-builder; this only closes the
+    // silent default-to-bypass path.
+    const permissionMode = sessionRef?.permissionMode || 'default';
+    // Prefix bare mixdog tool names so the evaluator path-logic handles them correctly.
+    const fullName = toolName.startsWith(MCP_TOOL_PREFIX) || toolName.startsWith('mcp__')
+        ? toolName
+        : `${MCP_TOOL_PREFIX}${toolName}`;
+    const projectDir = sessionRef?.cwd || undefined;
+    const userCwd = sessionRef?.cwd || undefined;
+    try {
+        const { decision, reason } = _evaluatePermission({
+            toolName: fullName,
+            toolInput: toolInput || {},
+            permissionMode,
+            projectDir,
+            userCwd,
+        });
+        if (decision === 'deny' || decision === 'ask') {
+            return `Error: tool "${toolName}" blocked by permission evaluator (decision=${decision}): ${reason}`;
+        }
+    } catch (err) {
+        // Evaluator errors must not crash the loop — log and allow.
+        try { process.stderr.write(`[permission-evaluator] error: ${err?.message}\n`); } catch {}
+    }
+    return null;
+}
+function effectiveToolPermission(sessionRef) {
+    return sessionRef?.toolPermission || sessionRef?.permission || null;
+}
+function isBlockedByPermission(toolName, toolKind, permission) {
+    if (permission === 'mcp') return !MCP_ONLY_ALLOWED_KINDS.has(toolKind);
+    if (permission === 'read') return READ_BLOCKED_TOOLS.has(toolName);
+    // Object-form {allow,deny} permission (role template / profile). The
+    // schema-level intersection in createSession only narrows the ADVERTISED
+    // tool list; it is not a runtime execution boundary. Enforce the same
+    // allow/deny here as the fail-safe so a tool call for a non-advertised
+    // (denied / out-of-allow) tool is rejected at dispatch time, matching
+    // the string-form ('read'/'mcp') guards. Names are compared bare +
+    // lowercased to mirror createSession's allow/deny set construction.
+    if (permission && typeof permission === 'object') {
+        const name = String(_stripMcpPrefix(toolName) || '').toLowerCase();
+        const deny = Array.isArray(permission.deny) && permission.deny.length > 0
+            ? permission.deny.map(n => String(n).toLowerCase())
+            : null;
+        if (deny && deny.includes(name)) return true;
+        const allow = Array.isArray(permission.allow) && permission.allow.length > 0
+            ? permission.allow.map(n => String(n).toLowerCase())
+            : null;
+        if (allow && !allow.includes(name)) return true;
+        return false;
+    }
+    return false;
+}
+function isBlockedHiddenWrapperCall(toolName, sessionRef) {
+    if (!RETRIEVAL_WRAPPERS.has(toolName)) return false;
+    if (sessionRef?.owner !== 'bridge') return false;
+    if (!isHiddenRole(sessionRef?.role)) return false;
+    const allow = HIDDEN_ROLE_WRAPPER_ALLOWLIST[sessionRef.role];
+    if (allow && allow.has(toolName)) return false;
+    return true;
+}
+function messagesArrayChanged(before, after) {
+    if (!Array.isArray(before) || !Array.isArray(after)) return before !== after;
+    if (before.length !== after.length) return true;
+    for (let i = 0; i < before.length; i += 1) {
+        if (before[i] !== after[i]) return true;
+    }
+    return false;
+}
+const SKILL_TOOL_NAMES = new Set(['skills_list', 'skill_view', 'skill_execute']);
+const SPECIAL_TOOL_NAMES = new Set(['bash_session', 'apply_patch', 'code_graph']);
+const BASH_SESSION_HEADER_RE = /\[session: ([^\]\r\n]+)\]/;
+const STORED_TOOL_ARG_BODY_KEY_RE = /^(?:content|old_string|new_string|patch|rewrite)$/i;
+const STORED_TOOL_ARG_LONG_KEY_RE = /^(?:command|script)$/i;
+const STORED_TOOL_ARG_BODY_LIMIT = 2_000;
+const STORED_TOOL_ARG_LONG_LIMIT = 8_000;
+const STORED_TOOL_ARG_PREVIEW_HEAD = 360;
+const STORED_TOOL_ARG_PREVIEW_TAIL = 160;
+
+function compactStoredToolArgString(value, key = '') {
+    if (typeof value !== 'string') return value;
+    const isBody = STORED_TOOL_ARG_BODY_KEY_RE.test(key);
+    const isLong = isBody || STORED_TOOL_ARG_LONG_KEY_RE.test(key);
+    const limit = isBody ? STORED_TOOL_ARG_BODY_LIMIT : (isLong ? STORED_TOOL_ARG_LONG_LIMIT : Infinity);
+    if (value.length <= limit) return value;
+    const hash = createHash('sha256').update(value).digest('hex').slice(0, 16);
+    const head = value.slice(0, STORED_TOOL_ARG_PREVIEW_HEAD).replace(/\r\n/g, '\n');
+    const tail = value.slice(-STORED_TOOL_ARG_PREVIEW_TAIL).replace(/\r\n/g, '\n');
+    return `[mixdog compacted ${key || 'string'}: ${value.length} chars, sha256:${hash}]\n${head}\n... [middle omitted from stored tool-call args] ...\n${tail}`;
+}
+
+function compactStoredToolArgValue(value, key = '', depth = 0) {
+    if (value === null || value === undefined) return value;
+    if (typeof value === 'string') return compactStoredToolArgString(value, key);
+    if (typeof value !== 'object') return value;
+    if (depth >= 6) return Array.isArray(value) ? `[${value.length} items]` : '{...}';
+    if (Array.isArray(value)) {
+        return value.map((item) => compactStoredToolArgValue(item, key, depth + 1));
+    }
+    const out = {};
+    for (const [k, v] of Object.entries(value)) {
+        out[k] = compactStoredToolArgValue(v, k, depth + 1);
+    }
+    return out;
+}
+
+function compactToolCallsForHistory(calls) {
+    if (!Array.isArray(calls)) return calls;
+    return calls.map((call) => {
+        if (!call || typeof call !== 'object') return call;
+        return {
+            ...call,
+            arguments: compactStoredToolArgValue(call.arguments),
+        };
+    });
+}
+
+// Restore the FULL body of ONE tool call inside a history assistant message
+// whose toolCalls were compacted at push time. Used for a failed edit call so
+// the model sees the original patch/old_string on retry instead of a
+// `[mixdog compacted …]` placeholder it cannot act on. Must run BEFORE the
+// message is first transmitted so it never mutates an already-cached prefix
+// (the prompt cache is content-prefix matched).
+//
+// Only the compactable body/long keys (patch, old_string, new_string, content,
+// rewrite, command, script) are restored, and at ANY depth — compaction is
+// recursive (compactStoredToolArgValue), so batch shapes like edits[].old_string
+// or writes[].content carry nested compacted bodies too. Every other field
+// (e.g. `path`, which a tool may mutate in place during execution) is taken from
+// the compacted snapshot captured at push time, before any mutation. The
+// compacted args tree is built fresh by compactToolCallsForHistory and is not
+// shared with originalCalls, so rebuilding it here is safe.
+function restoreToolCallBodyForId(assistantMsg, originalCalls, callId) {
+    if (!assistantMsg || !Array.isArray(assistantMsg.toolCalls) || !callId) return;
+    if (!Array.isArray(originalCalls)) return;
+    const tc = assistantMsg.toolCalls.find((t) => t && t.id === callId);
+    const orig = originalCalls.find((c) => c && c.id === callId);
+    if (!tc || !orig) return;
+    if (!tc.arguments || typeof tc.arguments !== 'object'
+        || !orig.arguments || typeof orig.arguments !== 'object') return;
+    tc.arguments = _restoreCompactedBodies(tc.arguments, orig.arguments, '');
+}
+
+// Recursively rebuild a compacted args tree: replace ONLY compactable body/long
+// string fields (matched by key at any depth) with their full originals, and
+// keep every other field from the compacted snapshot. tcVal and origVal share
+// the same structure (compaction only shortens body strings), so the walk
+// descends them in parallel; a missing or non-object origVal falls back to the
+// compacted value rather than throwing.
+function _restoreCompactedBodies(tcVal, origVal, key) {
+    if ((STORED_TOOL_ARG_BODY_KEY_RE.test(key) || STORED_TOOL_ARG_LONG_KEY_RE.test(key))
+        && typeof origVal === 'string') {
+        return origVal;
+    }
+    if (Array.isArray(tcVal) && Array.isArray(origVal)) {
+        return tcVal.map((item, i) => _restoreCompactedBodies(item, origVal[i], key));
+    }
+    if (tcVal && typeof tcVal === 'object' && origVal && typeof origVal === 'object') {
+        const out = {};
+        for (const k of Object.keys(tcVal)) {
+            out[k] = (k in origVal) ? _restoreCompactedBodies(tcVal[k], origVal[k], k) : tcVal[k];
+        }
+        return out;
+    }
+    return tcVal;
+}
+/**
+ * Execute a single tool call — routes to MCP or builtin.
+ */
+function getToolKind(name) {
+    if (SKILL_TOOL_NAMES.has(name)) return 'skill';
+    if (SPECIAL_TOOL_NAMES.has(name)) return 'builtin';
+    if (isMcpTool(name)) return 'mcp';
+    if (isInternalTool(name)) return 'internal';
+    if (isBuiltinTool(name)) return 'builtin';
+    return 'builtin';
+}
+function buildSkillsListResponse(cwd) {
+    const skills = collectSkillsCached(cwd);
+    const entries = skills.map(s => ({ name: s.name, description: s.description || '' }));
+    return JSON.stringify({ skills: entries });
+}
+function viewSkill(cwd, name) {
+    if (!name) return 'Error: skill name is required';
+    const content = loadSkillContent(name, cwd);
+    return content || `Error: skill "${name}" not found`;
+}
+function executeSkill(cwd, name, _args) {
+    if (!name) return 'Error: skill name is required';
+    const content = loadSkillContent(name, cwd);
+    return content || `Error: skill "${name}" not found`;
+}
+function extractBashSessionId(result) {
+    if (typeof result !== 'string') return null;
+    const match = BASH_SESSION_HEADER_RE.exec(result);
+    return match ? match[1] : null;
+}
+
+export function buildBridgeBashSessionArgs(args, sessionRef) {
+    if (sessionRef?.owner !== 'bridge') return null;
+    // run_in_background is a detached one-shot job, incompatible with the
+    // persistent bash session. Fall through to the background-job path
+    // (executeBuiltinTool -> startBackgroundShellJob) so the worker gets a
+    // [job: ...] id that job_wait can resolve — otherwise the persistent
+    // session returns a [session: ...] header and job_wait reports "job not found".
+    if (args?.run_in_background === true) return null;
+    const routedArgs = { ...(args || {}) };
+    const explicitSessionId = typeof routedArgs.session_id === 'string' && routedArgs.session_id.trim()
+        ? routedArgs.session_id.trim()
+        : null;
+    const wantsPersistent = routedArgs.persistent === true || !!explicitSessionId;
+    if (!wantsPersistent) return null;
+    if (!explicitSessionId && sessionRef?.implicitBashSessionId) {
+        routedArgs.session_id = sessionRef.implicitBashSessionId;
+    } else if (explicitSessionId) {
+        routedArgs.session_id = explicitSessionId;
+    }
+    delete routedArgs.persistent;
+    return routedArgs;
+}
+
+function _scopedCacheOutcomeForCall(sessionRef, toolCallId, toolName, callerSessionId, executeOpts = {}) {
+    if (executeOpts.scopedCacheOutcome) {
+        if (sessionRef && toolCallId) {
+            if (!sessionRef._scopedCacheOutcomeByCallId) sessionRef._scopedCacheOutcomeByCallId = new Map();
+            sessionRef._scopedCacheOutcomeByCallId.set(toolCallId, executeOpts.scopedCacheOutcome);
+        }
+        return executeOpts.scopedCacheOutcome;
+    }
+    if (!callerSessionId || !toolCallId || !_isScopedCacheableTool(toolName)) return null;
+    const outcome = createScopedCacheOutcome();
+    if (sessionRef) {
+        if (!sessionRef._scopedCacheOutcomeByCallId) sessionRef._scopedCacheOutcomeByCallId = new Map();
+        sessionRef._scopedCacheOutcomeByCallId.set(toolCallId, outcome);
+    }
+    return outcome;
+}
+
+async function executeTool(name, args, cwd, callerSessionId, sessionRef, executeOpts = {}) {
+    const scopedCacheOutcome = _scopedCacheOutcomeForCall(
+        sessionRef,
+        executeOpts.toolCallId,
+        name,
+        callerSessionId,
+        executeOpts,
+    );
+    const toolOpts = scopedCacheOutcome
+        ? { ...executeOpts, scopedCacheOutcome }
+        : executeOpts;
+    if (name === 'skills_list') {
+        return buildSkillsListResponse(cwd);
+    }
+    if (name === 'skill_view') {
+        return viewSkill(cwd, args?.name);
+    }
+    if (name === 'skill_execute') {
+        return executeSkill(cwd, args?.name, args?.args);
+    }
+    if (isMcpTool(name)) {
+        // 24h trace data shows ~24% of external MCP calls are cwd-sensitive
+        // (bash / grep / read / list / glob etc.) but the worker session's
+        // cwd was previously dropped here. Inject cwd only when the tool's
+        // inputSchema declares the field — schemas without it would reject
+        // an unknown argument.
+        const needsCwdInjection = cwd
+            && mcpToolHasField(name, 'cwd')
+            && (args == null || args.cwd == null);
+        const finalArgs = needsCwdInjection ? { ...(args || {}), cwd } : args;
+        return executeMcpTool(name, finalArgs);
+    }
+    if (isCodeGraphTool(name)) {
+        // cwd chain: args.cwd (caller-explicit) → session cwd → undefined (handler throws)
+        const graphCwd = (typeof args?.cwd === 'string' && args.cwd.trim()) ? args.cwd.trim() : cwd;
+        return executeCodeGraphTool(name, args, graphCwd, null, toolOpts);
+    }
+    if (isInternalTool(name)) {
+        // callerSessionId propagates into server.mjs dispatchTool so that
+        // dispatchAiWrapped can detect and reject recursive calls from a
+        // hidden-role session (recall/search/explore → self).
+        return executeInternalTool(name, args, { callerSessionId, callerCwd: cwd });
+    }
+    if (name === 'bash') {
+        const routedArgs = buildBridgeBashSessionArgs(args, sessionRef);
+        if (!routedArgs) {
+            // clientHostPid scopes background shell-jobs to the dispatching
+            // terminal's claude.exe pid (bridge sessions store it on sessionRef);
+            // without it resolveJobOwnerHostPid falls back to the daemon-global env.
+            return executeBuiltinTool(name, args, cwd, { sessionId: callerSessionId, clientHostPid: sessionRef?.clientHostPid, ...toolOpts });
+        }
+        // Thread the session's AbortSignal so bridge type=close can interrupt the
+        // persistent child process. getSessionAbortSignal is imported at top of
+        // loop.mjs from manager.mjs; callerSessionId identifies the controller.
+        let _bashAbortSignal = null;
+        try { _bashAbortSignal = getSessionAbortSignal(callerSessionId); } catch { /* ignore */ }
+        const result = await executeBashSessionTool('bash_session', routedArgs, cwd, {
+            sessionId: callerSessionId,
+            abortSignal: _bashAbortSignal,
+        });
+        const bashSid = extractBashSessionId(result);
+        if (bashSid) {
+            sessionRef.implicitBashSessionId = bashSid;
+            // Track all persistent bash sessions for bulk teardown on close.
+            if (sessionRef.allBashSessionIds) {
+                if (!sessionRef.allBashSessionIds.includes(bashSid)) {
+                    sessionRef.allBashSessionIds.push(bashSid);
+                }
+            } else {
+                sessionRef.allBashSessionIds = [bashSid];
+            }
+        }
+        return result;
+    }
+    if (name === 'apply_patch') {
+        return executePatchTool(name, args, cwd, { sessionId: callerSessionId });
+    }
+    if (isBuiltinTool(name)) {
+        // clientHostPid threaded for the same per-terminal job-scope reason as
+        // the bash branch above (see resolveJobOwnerHostPid).
+        return executeBuiltinTool(name, args, cwd, { sessionId: callerSessionId, clientHostPid: sessionRef?.clientHostPid, ...toolOpts });
+    }
+    return formatUnknownBuiltinToolMessage(name, args, 'tool');
+}
+/**
+ * Agent loop: send → tool_call → execute → re-send → repeat until text.
+ * sendOpts may include:
+ *   - `effort` (provider-specific)
+ *   - `fast` (boolean)
+ *   - `sessionId` — enables runtime liveness markers (optional)
+ *   - `signal` — AbortSignal; checked at each iteration boundary and after each
+ *                tool. When aborted, throws SessionClosedError so the ask
+ *                wrapper can propagate a clean cancellation.
+ *   - `onStageChange(stage)` / `onStreamDelta()` — forwarded to provider.send for heartbeats
+ */
+// Source of truth: defaults/hidden-roles.json (loaded via _getHiddenRoles
+// above). Build the name Set eagerly at module load so HIDDEN_ROLE_NAMES
+// stays in sync with the declarative registry — no hardcoded duplicate.
+const HIDDEN_ROLE_NAMES = new Set(
+    (_getHiddenRoles().roles || []).map((r) => r && r.name).filter((n) => typeof n === 'string' && n.length > 0)
+);
+
+// Stop reasons that signal the turn was cut short mid-synthesis (token cap,
+// provider pause). Empty content + one of these reasons means the worker
+// was not done — re-prompt instead of accepting empty as final.
+// Covers Anthropic (pause_turn, max_tokens), OpenAI (length), Gemini
+// (MAX_TOKENS, OTHER), and case variants.
+const INCOMPLETE_STOP_REASONS = new Set([
+    'pause_turn', 'max_tokens', 'length', 'MAX_TOKENS', 'OTHER',
+]);
+
+export async function agentLoop(provider, messages, model, tools, onToolCall, cwd, sendOpts) {
+    let iterations = 0;
+    let toolCallsTotal = 0;
+    let lastUsage;
+    let firstTurnUsage;
+    let response;
+    let contractNudges = 0;
+    const opts = sendOpts || {};
+    const sessionId = opts.sessionId || null;
+    const signal = opts.signal || null;
+    const sessionRole = opts.session?.role;
+    const forcedFirstTool = opts.forcedFirstTool ?? null;
+    const forcedFirstToolDef = forcedFirstTool
+        ? tools.find(tool => tool?.name === forcedFirstTool)
+        : null;
+    // Opaque providerState passthrough. The loop never inspects it; only the
+    // originating provider does. Seed from sendOpts.providerState if the
+    // manager restored one. No provider currently emits state (Codex OAuth is
+    // stateless per contract); field remains undefined end-to-end for now.
+    let providerState = opts.providerState ?? undefined;
+    const throwIfAborted = () => {
+        if (signal?.aborted) {
+            const reason = signal.reason instanceof Error ? signal.reason : null;
+            // Preserve any structured abort reason (SessionClosedError,
+            // StreamStalledAbortError, etc.). Fallback to SessionClosedError
+            // when the reason is not an Error instance.
+            if (reason) throw reason;
+            throw new SessionClosedError(sessionId || 'unknown', 'agent loop aborted');
+        }
+    };
+    const sessionRef = opts.session || null;
+    const maxLoopIterations = Number.isFinite(sessionRef?.maxLoopIterations)
+        ? sessionRef.maxLoopIterations
+        : MAX_LOOP_ITERATIONS;
+    // Tool execution must use the session cwd even when the caller omitted the
+    // legacy positional cwd argument. Bridge workers always carry their cwd on
+    // sessionRef; falling through to pwd()/process.cwd() resolves relatives
+    // against the host/plugin root instead of the worker workspace.
+    cwd = cwd || sessionRef?.cwd || undefined;
+    while (true) {
+        throwIfAborted();
+        if (iterations >= maxLoopIterations) {
+            process.stderr.write(`[loop] hard iteration cap ${maxLoopIterations} reached (sess=${sessionId || 'unknown'}); stopping loop.\n`);
+            break;
+        }
+        if (sessionRef && typeof sessionRef.contextWindow === 'number') {
+            const safetyBudget = Math.floor(sessionRef.contextWindow * SAFETY_TRIM_PERCENT);
+            // Reserve headroom for the tool schemas + provider request framing
+            // that ride alongside `messages` but are invisible to the chars/4
+            // message estimate. Without this the budget is optimistic: a
+            // transcript that "fits" by message tokens can still overflow once
+            // the provider serializes N tool definitions into the same request.
+            const reserveTokens = estimateRequestReserveTokens(tools);
+            // Snapshot pre-trim shape so trim_meta can record the actual
+            // mutation (or no-op) for prefix-mutation forensics. Bytes are
+            // a best-effort JSON.stringify length — close enough to the
+            // payload we hand the provider for prefix-cache analysis.
+            const beforeCount = messages.length;
+            let beforeBytes = null;
+            try { beforeBytes = Buffer.byteLength(JSON.stringify(messages), 'utf8'); } catch { beforeBytes = null; }
+            const trimmed = trimMessages(messages, safetyBudget, { reserveTokens });
+            const trimChanged = messagesArrayChanged(messages, trimmed);
+            const pruneCount = Math.max(beforeCount - trimmed.length, 0);
+            if (trimChanged) {
+                messages.length = 0;
+                messages.push(...trimmed);
+                // Trimming the transcript invalidates the server-side
+                // conversation anchor (xAI Responses / Codex WS rely on
+                // previous_response_id which points at a now-mutated prefix).
+                // Drop providerState so the next send starts a fresh chain
+                // instead of triggering silent cache miss or hard mismatch.
+                providerState = undefined;
+                // Compaction shrank the transcript, so prior turns no longer
+                // pressure the window — reset the iteration counter so a
+                // steadily-compacting long task isn't killed by the cap,
+                // while a non-compacting tight loop still hits it.
+                iterations = 0;
+            }
+            let afterBytes = null;
+            try { afterBytes = Buffer.byteLength(JSON.stringify(messages), 'utf8'); } catch { afterBytes = null; }
+            traceBridgeTrim({
+                sessionId,
+                iteration: iterations + 1,
+                prune_count: pruneCount,
+                trim_changed: trimChanged,
+                input_prefix_hash: messagePrefixHash(messages),
+                before_count: beforeCount,
+                after_count: messages.length,
+                before_bytes: beforeBytes,
+                after_bytes: afterBytes,
+            });
+        }
+        const nextIteration = iterations + 1;
+        opts.iteration = nextIteration;
+        opts.providerState = providerState;
+        if (forcedFirstTool && toolCallsTotal === 0) {
+            opts.toolChoice = 'required';
+        } else {
+            delete opts.toolChoice;
+        }
+        const sendTools = 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
+        // remaining SSE parse. Writes and unknown tools wait until send()
+        // returns and run serially in the call-order loop below.
+        const pending = new Map();
+        // Streaming-time intra-turn dedup. When the LLM emits two
+        // tool_use blocks with identical (name, args) signatures in
+        // sequence, the provider's onToolCall fires for both BEFORE
+        // the iter for-body runs, so the batch-level pre-pass would be
+        // too late to prevent the eager dispatch of the second one.
+        // Track signatures of in-flight eager calls and skip starting a
+        // second one for the same sig. The duplicate's executeTool is
+        // never invoked; the for-body's pre-pass marks it as a duplicate
+        // and emits a stub tool_result. The sig is NOT cleared when the
+        // eager promise settles (see finally below): a streaming onToolCall
+        // can deliver a same-turn identical call AFTER the first promise
+        // settles but BEFORE the deferred cache set (:1256), and the static
+        // pre-pass (:909) only runs after send() returns — so clearing the
+        // sig on settle would let that second streaming eager call
+        // re-execute. A fresh Map() is created per turn, so the sig set
+        // resets at the turn boundary without leaking across iterations.
+        const _eagerInFlightSigs = new Map();
+        let _mutationEpoch = 0;
+        const startEagerTool = (call) => {
+            if (!call?.id || pending.has(call.id) || !isEagerDispatchable(call.name, tools)) return null;
+            const _sig = _intraTurnSig(call.name, call.arguments);
+            if (_eagerInFlightSigs.has(_sig)) return null;
+            // Repeat-failure guard also gates eager dispatch (reviewer-flagged):
+            // streaming onToolCall / startEagerRun would otherwise re-run an
+            // identical read-only call that already failed REPEAT_FAIL_LIMIT
+            // times before the serial for-body guard runs. Returning null here
+            // lets the serial body push the [repeat-failure-guard] stub.
+            {
+                const _rfg = sessionRef?._repeatFailGuard;
+                if (_rfg && _rfg.sig === _sig && _rfg.count >= REPEAT_FAIL_LIMIT) return null;
+            }
+            const toolKind = getToolKind(call.name);
+            // Shared pre-dispatch deny: identical predicate runs in the
+            // serial path below. If any role/permission guard would reject
+            // this call there, never start it eagerly here.
+            if (_preDispatchDeny(call, toolKind, sessionRef) !== null) return null;
+            const entry = { startedAt: Date.now(), endedAt: null, mutationEpoch: _mutationEpoch };
+            _eagerInFlightSigs.set(_sig, call.id);
+            entry.promise = (async () => {
+                try {
+                    const permBlocked = _checkWorkerPermission(call.name, call.arguments, sessionRef);
+                    if (permBlocked !== null) return { ok: true, value: permBlocked };
+                    return { ok: true, value: await executeTool(call.name, call.arguments, cwd, sessionId, sessionRef, { toolCallId: call.id }) };
+                } catch (error) {
+                    return { ok: false, error };
+                }
+            })()
+                .finally(() => {
+                    entry.endedAt = Date.now();
+                    // Intentionally do NOT delete _sig here — see the block
+                    // comment above. The sig must outlive promise settlement
+                    // so a later same-turn streaming duplicate stays blocked
+                    // at the _eagerInFlightSigs.has(_sig) guard until the turn
+                    // boundary recreates the Map.
+                });
+            pending.set(call.id, entry);
+            return entry;
+        };
+        const startEagerRun = (calls, startIndex, dupSet) => {
+            for (let j = startIndex; j < calls.length; j += 1) {
+                const call = calls[j];
+                if (!call?.id || !isEagerDispatchable(call.name, tools)) break;
+                if (dupSet && dupSet.has(call.id)) continue;
+                if (!startEagerTool(call) && !pending.has(call.id)) break;
+            }
+        };
+        let _streamEagerBlocked = false;
+        opts.onToolCall = (call) => {
+            if (!isEagerDispatchable(call?.name, tools)) {
+                _streamEagerBlocked = true;
+                return;
+            }
+            if (_streamEagerBlocked) return;
+            startEagerTool(call);
+        };
+        // Repair any dangling assistant tool_use left over from a prior
+        // abort/error path before the provider sees the transcript. No-op
+        // on the healthy iteration cycle (every assistant tool_use is
+        // followed by tool results in the same loop body below).
+        _ensureTranscriptPairing(messages, sessionId);
+        // Strip soft-warn markers from prior tool results before the next
+        // send. Marker bytes (Tool-budget(xN), Same-file reads(xN), etc.)
+        // mutate every turn with dynamic counters, so leaving them in the
+        // transcript breaks server-side prefix cache lookup on later turns.
+        // The current turn's marker (if any) is appended AFTER this strip,
+        // so the model still sees the self-correct hint on its own iteration.
+        for (let _i = 0; _i < messages.length; _i++) {
+            const _m = messages[_i];
+            if (_m && _m.role === 'tool' && typeof _m.content === 'string' && _m.content.includes('⚠')) {
+                const _stripped = stripSoftWarns(_m.content);
+                if (_stripped !== _m.content) _m.content = _stripped;
+            }
+        }
+        const sendStartedAt = Date.now();
+        try {
+            response = await provider.send(messages, model, sendTools.length ? sendTools : undefined, opts);
+        } catch (sendErr) {
+            // Context-window-exceeded is a deterministic refusal: the request is
+            // simply too large. Retry ONCE with a stricter trim budget that
+            // force-drops older non-system / non-latest turns before surfacing
+            // the error. Unrelated errors (network, stall, auth, etc.) re-throw
+            // untouched — they are handled by the provider/bridge retry layers.
+            if (
+                !isContextOverflowError(sendErr)
+                || !(sessionRef && typeof sessionRef.contextWindow === 'number')
+            ) {
+                throw sendErr;
+            }
+            const overflowBudget = Math.floor(sessionRef.contextWindow * OVERFLOW_RETRY_TRIM_PERCENT);
+            const overflowReserve = estimateRequestReserveTokens(sendTools.length ? sendTools : tools);
+            const retrimmed = trimMessages(messages, overflowBudget, { reserveTokens: overflowReserve });
+            messages.length = 0;
+            messages.push(...retrimmed);
+            // The transcript prefix changed; the server-side conversation anchor
+            // (previous_response_id / WS continuation) is now invalid. Drop
+            // providerState so the retry starts a fresh chain instead of
+            // tripping a silent cache miss or hard mismatch.
+            providerState = undefined;
+            opts.providerState = undefined;
+            // Drop eager-dispatch state before the retry send. A tool_use
+            // streamed by the failed first send could otherwise orphan its
+            // eager result or be double-dispatched; force the retry's tools
+            // through the serial post-send path with a clean matching slate.
+            opts.onToolCall = undefined;
+            pending.clear();
+            _eagerInFlightSigs.clear();
+            try {
+                process.stderr.write(
+                    `[loop] context overflow on send (sess=${sessionId || 'unknown'} iter=${nextIteration}); ` +
+                    `retrying once at budget=${overflowBudget} reserve=${overflowReserve} ` +
+                    `messages=${messages.length}\n`,
+                );
+            } catch { /* best-effort */ }
+            response = await provider.send(messages, model, sendTools.length ? sendTools : undefined, opts);
+        }
+        opts.onToolCall = undefined;
+        // Capture opaque state for the next turn (may be undefined — that's
+        // the stateless contract for providers that don't use continuation).
+        providerState = response?.providerState ?? undefined;
+        iterations = nextIteration;
+        traceBridgeLoop({
+            sessionId,
+            iteration: iterations,
+            sendMs: Date.now() - sendStartedAt,
+            messageCount: Array.isArray(messages) ? messages.length : 0,
+            bodyBytesEst: estimateProviderPayloadBytes(messages, model, sendTools),
+        });
+        // Accumulate usage across iterations — every billable slot, not just
+        // input/output. Anthropic cache_read/cache_write typically stay 0 on
+        // the first iteration and surge on later ones (warm prefix reuse),
+        // so aggregating only the head would silently drop most of the
+        // cache-side tokens.
+        if (response.usage) {
+            if (lastUsage) {
+                lastUsage.inputTokens += response.usage.inputTokens || 0;
+                lastUsage.outputTokens += response.usage.outputTokens || 0;
+                lastUsage.cachedTokens = (lastUsage.cachedTokens || 0) + (response.usage.cachedTokens || 0);
+                lastUsage.cacheWriteTokens = (lastUsage.cacheWriteTokens || 0) + (response.usage.cacheWriteTokens || 0);
+                lastUsage.promptTokens = (lastUsage.promptTokens || 0) + (response.usage.promptTokens || 0);
+            }
+            else {
+                lastUsage = {
+                    inputTokens: response.usage.inputTokens || 0,
+                    outputTokens: response.usage.outputTokens || 0,
+                    cachedTokens: response.usage.cachedTokens || 0,
+                    cacheWriteTokens: response.usage.cacheWriteTokens || 0,
+                    promptTokens: response.usage.promptTokens || 0,
+                    raw: response.usage.raw,
+                };
+                // Snapshot the first turn separately so callers can show
+                // iter1 vs final cache-hit ratios — first iter is the
+                // warm-prefix signal, final iter is the steady-state
+                // efficiency signal after tool-result accumulation.
+                firstTurnUsage = { ...lastUsage };
+            }
+        }
+        // Provider may have returned despite an abort (SDKs that don't honour
+        // signal) — bail before processing any of its output.
+        throwIfAborted();
+        // Incremental metric persistence (fix A): push per-iteration token delta
+        // immediately so watchdog / bridge type=list sees live totals mid-turn.
+        if (sessionId && opts.onUsageDelta && response.usage) {
+            try {
+                opts.onUsageDelta({
+                    sessionId,
+                    iterationIndex: iterations,
+                    deltaInput: response.usage.inputTokens || 0,
+                    deltaOutput: response.usage.outputTokens || 0,
+                    // Cache delta carried alongside input/output so live metrics
+                    // reflect the same token classes the terminal aggregate adds;
+                    // additive — callers that ignore these fields keep working.
+                    deltaCachedRead: response.usage.cachedTokens || 0,
+                    deltaCacheWrite: response.usage.cacheWriteTokens || 0,
+                    ts: Date.now(),
+                });
+            } catch { /* best-effort — never break the loop */ }
+        }
+        // No tool calls. For PUBLIC bridge workers, the bridge contract
+        // (rules/bridge/00-common.md) requires either a tool call or a
+        // `<final-answer>` wrapped reply.
+        // A text-only turn without those tags violates the contract (e.g.
+        // Opus 4.6 emits 'Now I'll polish…' preamble before its first tool
+        // call) and used to leave the session idle until the idle sweep
+        // collected it. Re-prompt the worker with a contract reminder; cap
+        // at 2 nudges so a model that never complies still terminates the
+        // loop. Hidden roles (cycle1-agent / cycle2-agent / explorer /
+        // scheduler-task / webhook-handler) are exempt:
+        // their own role rules define a different output contract (pipe-
+        // separated chunker output, structured pipe-format, etc.) and a
+        // text-only terminal turn is the correct shape — nudging them
+        // produces a contradictory user message that traps the model in a
+        // tool-call-blocked vs contract-required oscillation.
+        if (!response.toolCalls?.length) {
+            // No tool calls. Decide between final-answer accept vs nudge.
+            //   - has content + non-hidden role → valid final, break.
+            //   - empty content + hidden role → contract allows text-only
+            //     terminal turn, break.
+            //   - empty content + non-hidden role → one soft nudge. Repeated
+            //     reminders waste turns and fragment the working context, so
+            //     the second empty turn is accepted as terminal.
+            const hasContent = typeof response.content === 'string' && response.content.trim().length > 0;
+            const isHidden = HIDDEN_ROLE_NAMES.has(sessionRole);
+            const stopReason = response.stopReason ?? response.stop_reason ?? null;
+            const isIncompleteStop = stopReason && INCOMPLETE_STOP_REASONS.has(stopReason);
+            if (!hasContent && !isHidden) {
+                if (contractNudges >= 1) break;
+                contractNudges += 1;
+                let nudgeMsg;
+                if (isIncompleteStop) {
+                    nudgeMsg = `[mixdog-runtime] Previous turn ended mid-synthesis (stopReason=${stopReason}) with empty content. Continue — emit <final-answer>...</final-answer> with your synthesis so far, or call more tools to finish.`;
+                } else {
+                    nudgeMsg = '[mixdog-runtime] Your previous response was empty (no <final-answer> tag and no tool call). Either emit your final answer wrapped in <final-answer>...</final-answer> tags, or continue with tool calls. Do not return an empty turn.';
+                }
+                messages.push({ role: 'user', content: nudgeMsg });
+                continue;
+            }
+            break;
+        }
+        const calls = response.toolCalls;
+        toolCallsTotal += calls.length;
+        // Per-turn batch shape — one row per assistant turn so trace
+        // consumers can derive multi-tool adoption ratio without scanning
+        // every assistant message body.
+        recordToolBatch(sessionId, calls.length);
+        onToolCall?.(iterations, calls);
+        // Append assistant message with tool calls. reasoningItems is the
+        // OpenAI Responses API replay payload (encrypted_content blobs);
+        // providers that ignore it just see an extra field and drop it,
+        // openai-oauth.convertMessagesToResponsesInput emits matching
+        // type:'reasoning' input items on the next turn to keep the Codex
+        // server-side cache prefix stable.
+        const _assistantTurnMsg = {
+            role: 'assistant',
+            content: response.content || '',
+            toolCalls: compactToolCallsForHistory(calls),
+            ...(Array.isArray(response.reasoningItems) && response.reasoningItems.length
+                ? { reasoningItems: response.reasoningItems }
+                : {}),
+            ...(typeof response.reasoningContent === 'string' && response.reasoningContent
+                ? { reasoningContent: response.reasoningContent }
+                : {}),
+        };
+        messages.push(_assistantTurnMsg);
+        // Execute each tool and append results.
+        //
+        // Intra-turn duplicate suppression: when an LLM emits two tool_use
+        // blocks with identical (name, args) inside the SAME assistant turn,
+        // re-executing wastes tokens. Restricted to tools with
+        // `readOnlyHint:true` (= isEagerDispatchable) — bash/write/edit/
+        // apply_patch may be intentional repeats with distinct side effects.
+        // Pre-pass identifies duplicates BEFORE startEagerRun so eager
+        // dispatch also skips them, not just the for-body.
+        const _duplicateCallIds = new Set();
+        const _dupFirstId = new Map();
+        {
+            const _firstIdBySig = new Map();
+            for (const c of calls) {
+                if (!c?.id) continue;
+                if (!isEagerDispatchable(c.name, tools)) {
+                    _firstIdBySig.clear();
+                    continue;
+                }
+                const sig = _intraTurnSig(c.name, c.arguments);
+                const first = _firstIdBySig.get(sig);
+                if (first === undefined) {
+                    _firstIdBySig.set(sig, c.id);
+                } else {
+                    _duplicateCallIds.add(c.id);
+                    _dupFirstId.set(c.id, first);
+                }
+            }
+        }
+        // R15: per-turn scalar read-count Map. Lifetime = this turn's tool-call batch.
+        // Declared between the duplicate-detection block and the for-loop so it resets
+        for (let callIndex = 0; callIndex < calls.length; callIndex += 1) {
+            const call = calls[callIndex];
+            if (isBuiltinTool(call.name)) {
+                call.name = canonicalizeBuiltinToolName(call.name);
+            }
+            if (_duplicateCallIds.has(call.id)) {
+                const _firstId = _dupFirstId.get(call.id);
+                const _stub = `[intra-turn-dedup] identical read-only \`${call.name}\` call was already executed in this same assistant turn as tool_use_id=${_firstId}. The first call's tool_result is in context immediately above; skipping re-execution to save tokens. If you needed a different slice of the file, narrow the next call (different path / offset / limit / pattern) so it has a distinct signature.`;
+                messages.push({
+                    role: 'tool',
+                    content: _stub,
+                    toolCallId: call.id,
+                });
+                continue;
+            }
+            // Cross-iteration repeat-failure guard. Distinct from the
+            // intra-turn dedup above (which spans ONE assistant turn and
+            // resets every turn): when the model re-issues an IDENTICAL
+            // (name,args) call that has already failed REPEAT_FAIL_LIMIT times
+            // in a row across iterations, stop re-executing — the result will
+            // not change, and each retry burns a full (often slow) LLM
+            // round-trip until the hard iteration cap. Steer it to change
+            // approach instead.
+            const _repeatFailSig = _intraTurnSig(call.name, call.arguments);
+            {
+                const _rfg = sessionRef?._repeatFailGuard;
+                if (_rfg && _rfg.sig === _repeatFailSig && _rfg.count >= REPEAT_FAIL_LIMIT) {
+                    messages.push({
+                        role: 'tool',
+                        content: `[repeat-failure-guard] This exact \`${call.name}\` call (identical arguments) has already failed ${_rfg.count} times in a row; not re-executing because the result will not change. Change approach: use different arguments, a different tool, or skip this step.`,
+                        toolCallId: call.id,
+                    });
+                    continue;
+                }
+            }
+            if (sessionId) markSessionToolCall(sessionId, call.name);
+            let result;
+            let toolStartedAt;
+            let toolEndedAt;
+            const toolKind = getToolKind(call.name);
+            // Cross-turn read dedup. Mirrors Anthropic Claude Code's
+            // fileReadCache.ts: if the path's stat tuple (mtime/size/ino/dev)
+            // is unchanged since a prior read in THIS session, return the cached
+            // body instead of executing. Both scalar and array/object-array path
+            // forms are cached — keyed by (abs, offset, limit, mode, n) per entry.
+            //
+            // Scoped-tool cache (grep/glob/list + graph lookups): same idea
+            // but keyed by (toolName, canonical args) without per-file stat.
+            // These tools scan many files so a single stat tuple cannot cover
+            // them. The scoped cache registers dependency roots and write-class
+            // tools evict entries whose root contains the touched path.
+            let _readCacheHit = null;
+            let _scopedCacheHit = null;
+            let _executeOk = false;
+            let _resultKind = 'normal';
+            if (sessionId && _isReadTool(call.name)) {
+                _readCacheHit = tryReadCached({ sessionId, args: call.arguments, cwd });
+            } else if (sessionId && _isScopedCacheableTool(call.name)) {
+                _scopedCacheHit = tryScopedToolCached({ sessionId, toolName: _stripMcpPrefix(call.name), args: call.arguments, cwd });
+            }
+            try {
+                if (_readCacheHit !== null) {
+                    toolStartedAt = Date.now();
+                    toolEndedAt = toolStartedAt;
+                    const _body = _readCacheHit.content;
+                    // Return the cached body byte-for-byte instead of a
+                    // human-readable cache marker. The marker made public
+                    // bridge workers treat a successful cached read as a
+                    // meta instruction and repeat the same read loop.
+                    result = _body;
+                    _resultKind = 'cache-hit';
+                    _executeOk = true;
+                } else if (_scopedCacheHit !== null) {
+                    toolStartedAt = Date.now();
+                    toolEndedAt = toolStartedAt;
+                    const _body = _scopedCacheHit.content;
+                    result = _body;
+                    _resultKind = 'scoped-cache-hit';
+                    _executeOk = true;
+                } else {
+                // Fallback for providers that don't stream tool calls early:
+                // execute a contiguous read-only run in parallel, but never
+                // cross a write/bash/MCP boundary that may change state.
+                if (isEagerDispatchable(call.name, tools)) {
+                    startEagerRun(calls, callIndex, _duplicateCallIds);
+                }
+                let eager = pending.get(call.id);
+                if (eager !== undefined && eager.mutationEpoch < _mutationEpoch) {
+                    pending.delete(call.id);
+                    eager = undefined;
+                }
+                if (eager !== undefined) {
+                    toolStartedAt = eager.startedAt;
+                    const settled = await eager.promise;
+                    if (!settled.ok) throw settled.error;
+                    result = settled.value;
+                    toolEndedAt = eager.endedAt ?? Date.now();
+                    const _eagerKind = classifyResultKind(result);
+                    if (_eagerKind === 'error') {
+                        _resultKind = 'error';
+                        _executeOk = false;
+                    } else {
+                        _executeOk = true;
+                    }
+                } else {
+                    toolStartedAt = Date.now();
+                    // Runtime permission guard. Schema profiles may hide
+                    // tools for routing efficiency, but this remains the
+                    // safety boundary for any tool_use that still reaches
+                    // the loop. _preDispatchDeny is the SHARED helper used
+                    // by both the eager dispatch path (startEagerTool) and
+                    // this serial path — keeps the bridge-owned control-
+                    // plane reject, role guards, wrapper guards, and
+                    // permission guards consistent across both paths.
+                    const _denyMsg = _preDispatchDeny(call, toolKind, sessionRef);
+                    if (_denyMsg !== null) {
+                        result = _denyMsg;
+                        toolEndedAt = Date.now();
+                        _resultKind = 'error';
+                    } else {
+                        const permBlocked = _checkWorkerPermission(call.name, call.arguments, sessionRef);
+                        if (permBlocked !== null) {
+                            result = permBlocked;
+                            toolEndedAt = Date.now();
+                            _resultKind = 'error';
+                        } else {
+                            result = await executeTool(call.name, call.arguments, cwd, sessionId, sessionRef, { toolCallId: call.id });
+                            toolEndedAt = Date.now();
+                            // Boundary: tool-return string convention → structural kind.
+                            // The only prefix check in this codebase; downstream layers
+                            // operate on _resultKind.
+                            if (classifyResultKind(result) === 'error') {
+                                _resultKind = 'error';
+                                _executeOk = false;
+                            } else {
+                                _executeOk = true;
+                            }
+                            // _resultKind stays 'normal' when tool returned a non-error string.
+                        }
+                    }
+                }
+                } // close: else branch of _readCacheHit check
+            }
+            catch (err) {
+                if (toolStartedAt === undefined) toolStartedAt = Date.now();
+                toolEndedAt = Date.now();
+                result = `Error: ${err instanceof Error ? err.message : String(err)}`;
+                _resultKind = 'error';
+            }
+            // Update the cross-iteration repeat-failure guard with this call's
+            // outcome: bump the consecutive-failure count for an identical
+            // signature, or clear it the moment the same call succeeds.
+            if (sessionRef) {
+                const _failed = !_executeOk || _resultKind === 'error';
+                if (_failed) {
+                    sessionRef._repeatFailGuard = (sessionRef._repeatFailGuard?.sig === _repeatFailSig)
+                        ? { sig: _repeatFailSig, count: sessionRef._repeatFailGuard.count + 1 }
+                        : { sig: _repeatFailSig, count: 1 };
+                } else if (sessionRef._repeatFailGuard?.sig === _repeatFailSig) {
+                    sessionRef._repeatFailGuard = null;
+                }
+            }
+            // A failed executed call keeps its FULL argument body in history so the
+            // model can retry against the original (a large apply_patch `patch` /
+            // edit `old_string` would otherwise be hidden behind a
+            // `[mixdog compacted …]` placeholder). Restored IMMEDIATELY — not at end
+            // of loop — so an abort or post-processing throw after this point cannot
+            // leave a failed edit compacted. Cache-safe: _assistantTurnMsg is not
+            // transmitted until the next provider.send. Early-continue paths (dedup /
+            // repeat-failure-guard) never reach here and stay compacted.
+            if ((!_executeOk || _resultKind === 'error') && call?.id) {
+                restoreToolCallBodyForId(_assistantTurnMsg, calls, call.id);
+            }
+            // Cross-turn cache maintenance — gate on both _executeOk and _resultKind==='normal'.
+            // _executeOk=false catches permission-blocked / catch-path / partial-fail results.
+            // _resultKind==='normal' ensures cache-hit refs are never re-stored (structural,
+            // no prefix sniffing).
+            // NOTE: setReadCached / setScopedToolCached are deferred below (after
+            // compressToolResult) so the cache holds the same content as conversation
+            // history. Cache-hit refs point to a tool_use_id whose message body matches
+            // exactly what's stored — no phantom full body.
+            if (sessionId && _executeOk && _resultKind === 'normal') {
+                const _toolBare = _stripMcpPrefix(call.name);
+                if (_readCacheHit === null && _isReadTool(call.name)) {
+                    // Post-edit advisory: handle BOTH scalar and array forms
+                    // of args.path. The array form (path:[a,b,c] or
+                    // path:[{path:a},{path:b}]) was a coverage gap in R1 —
+                    // an LLM that edits X then reads [X,Y] should still see
+                    // the advisory for X.
+                    const _argsPath = call.arguments?.path;
+                    const _pathList = [];
+                    if (typeof _argsPath === 'string') {
+                        _pathList.push(_argsPath);
+                    } else if (typeof call.arguments?.file_path === 'string') {
+                        _pathList.push(call.arguments.file_path);
+                    } else if (Array.isArray(_argsPath)) {
+                        for (const _item of _argsPath) {
+                            if (typeof _item === 'string') _pathList.push(_item);
+                            else if (_item && typeof _item === 'object') {
+                                const _itemPath = typeof _item.path === 'string' ? _item.path : _item.file_path;
+                                if (typeof _itemPath === 'string') _pathList.push(_itemPath);
+                            }
+                        }
+                    }
+                    const _marks = [];
+                    for (const _p of _pathList) {
+                        const _m = consumePostEditMark({ sessionId, path: _p, cwd });
+                        if (_m) _marks.push({ path: _p, mark: _m });
+                    }
+                } else if (_toolBare === 'apply_patch') {
+                    // apply_patch's args are a unified-diff text in `patch`
+                    // (resolved against `base_path` or cwd). Parse the diff
+                    // headers (`--- a/path` / `+++ b/path`) to extract the
+                    // touched paths and invalidate / mark each one. Falls
+                    // back to a full session clear only when no paths could
+                    // be parsed (malformed diff or unknown format).
+                    const _argsBase = call.arguments?.base_path;
+                    const _patchBase = (typeof _argsBase === 'string' && _argsBase.length > 0)
+                        ? (isAbsolute(_argsBase) ? _argsBase : resolvePath(cwd || process.cwd(), _argsBase))
+                        : (cwd || process.cwd());
+                    const _touched = extractTouchedPathsFromPatch(call.arguments?.patch);
+                    if (_touched.length > 0) {
+                        for (const _p of _touched) {
+                            invalidatePathForSession(sessionId, _p, _patchBase);
+                            markPostEdit({ sessionId, path: _p, cwd: _patchBase, toolName: 'apply_patch' });
+                            // R20: cross-dispatch prefetch cache invalidation.
+                            invalidatePrefetchCache(_p, _patchBase);
+                        }
+                    } else {
+                        clearReadDedupSession(sessionId);
+                        // R20: path unknown — can't target; no-op on prefetch cache
+                        // (stat-validation at lookup time will naturally reject stale entries).
+                    }
+                    // Targeted scoped-cache invalidation: only evict entries whose
+                    // dep paths intersect the touched set. Full wipe is the fallback
+                    // when no paths were extracted (D).
+                    if (_touched.length > 0) {
+                        clearScopedToolsForSessionPaths(sessionId, _touched, _patchBase);
+                    } else {
+                        clearScopedToolsForSession(sessionId);
+                    }
+                } else if (_isScalarWriteEditTool(call.name)) {
+                    // Scalar `args.path` only: precise invalidate + advisory mark.
+                    // Array-form (`edits[]`/`writes[]`): the tool may have partial-
+                    // failed across paths and the result string aggregates;
+                    // full-clear instead of falsely marking every path.
+                    const _scalarPath = call.arguments?.path || call.arguments?.file_path;
+                    const _hasArrayForm = Array.isArray(call.arguments?.edits)
+                        || Array.isArray(call.arguments?.writes);
+                    if (_hasArrayForm) {
+                        clearReadDedupSession(sessionId);
+                        clearScopedToolsForSession(sessionId);
+                        // R20: array-form — walk each entry, extract its path,
+                        // and invalidate the prefetch cache + mark post-edit for
+                        // every distinct touched path. Falls back to the top-
+                        // level `path` (or `file_path`) when an entry omits its
+                        // own path. This covers both edit edits[] and write
+                        // writes[] forms; entries without a resolvable path are
+                        // silently skipped (their stat-validation safety net at
+                        // next lookup still applies).
+                        const _topPath = call.arguments?.path || call.arguments?.file_path;
+                        const _entries = call.arguments?.edits || call.arguments?.writes || [];
+                        const _seenPaths = new Set();
+                        for (const _e of _entries) {
+                            const _ep = _e?.path || _e?.file_path || _topPath;
+                            if (typeof _ep === 'string' && _ep && !_seenPaths.has(_ep)) {
+                                _seenPaths.add(_ep);
+                                invalidatePathForSession(sessionId, _ep, cwd);
+                                markPostEdit({ sessionId, path: _ep, cwd, toolName: _toolBare });
+                                invalidatePrefetchCache(_ep, cwd);
+                            }
+                        }
+                        if (_seenPaths.size > 0) {
+                            clearScopedToolsForSessionPaths(sessionId, [..._seenPaths], cwd);
+                        }
+                    } else if (typeof _scalarPath === 'string') {
+                        invalidatePathForSession(sessionId, _scalarPath, cwd);
+                        markPostEdit({ sessionId, path: _scalarPath, cwd, toolName: _toolBare });
+                        // R20: cross-dispatch prefetch cache invalidation.
+                        invalidatePrefetchCache(_scalarPath, cwd);
+                        // Targeted scoped-cache invalidation for the single touched path (D).
+                        clearScopedToolsForSessionPaths(sessionId, [_scalarPath], cwd);
+                    } else {
+                        // No path extractable — full wipe fallback.
+                        clearScopedToolsForSession(sessionId);
+                    }
+                }
+            } // end _executeOk+_resultKind gate (scoped tool cache set)
+            // E: mutation tools (apply_patch / write / edit) must invalidate caches
+            // even on returned-error/partial-fail — the file state is unknown after
+            // an error exit, and some tools report failure as an Error: result string
+            // rather than throwing.
+            // This block runs unconditionally (not gated on _executeOk or _resultKind).
+            if (sessionId && (!_executeOk || _resultKind === 'error') && (_stripMcpPrefix(call.name) === 'apply_patch' || _isScalarWriteEditTool(call.name))) {
+                clearReadDedupSession(sessionId);
+            }
+            if (_isMutationTool(call.name)) {
+                _mutationEpoch += 1;
+            }
+            // Bash always clears scoped cache UNCONDITIONALLY — a mutating bash
+            // that throws or fails partway can still leave stale find_symbol / grep entries.
+            // Must not be gated on _executeOk or _resultKind.
+            if (sessionId && _isBashTool(call.name)) {
+                clearScopedToolsForSession(sessionId);
+            }
+            // R17 compression pipeline — correct ordering (compress → cache → push):
+            //   1. compressToolResult: lossless ANSI/dedup/separator passes.
+            //   2. setReadCached / setScopedToolCached: cache stores the SAME result that
+            //      goes into conversation history. Cache-hit refs point to the tool_use_id
+            //      whose message body matches — no phantom full body.
+            //   3. offload → hint → message push.
+            // Offload FIRST — before compress. Large RAW output goes to a disk sidecar
+            // + ~2K preview before any in-place shrink (lossless compress) can reduce
+            // it below the offload threshold and pre-empt the sidecar. When offload
+            // fires it replaces `result` with a short preview stub (<2K) referencing
+            // the on-disk path; the later compress is a no-op on that stub. compress
+            // then only touches output that stayed inline (<= threshold).
+            // Per-tool post-processing backstop. The executeTool try/catch
+            // above terminates BEFORE offload/compress/trim/hint/cache writes/
+            // trace/messages.push, so a maybeOffloadToolResult rejection (or
+            // any downstream throw) would otherwise leave the assistant
+            // tool_use message with no matching tool result. Wrap the whole
+            // post-processing window through messages.push() in a catch; on
+            // failure push a synthetic Error: tool result for this call.id
+            // and skip the cache writes for it.
+            let _postProcessOk = true;
+            try {
+                // Offload thresholds are keyed by BARE tool name
+                // (INLINE_THRESHOLD_BY_TOOL: grep=20k, bash=30k, read=Infinity, ...),
+                // so strip the MCP prefix exactly as the cache write below does.
+                // Otherwise an mcp__..__grep name misses its 20k grep cap and
+                // silently falls back to the 50k default — per-tool limits ignored.
+                const _toolBare = _stripMcpPrefix(call.name);
+                result = await maybeOffloadToolResult(sessionId, call.id, _toolBare, result);
+                result = compressToolResult(call.name, call.arguments, result, { sessionId, toolKind });
+                traceBridgeTool({
+                    sessionId,
+                    iteration: iterations,
+                    toolName: call.name,
+                    toolKind,
+                    toolMs: toolEndedAt - toolStartedAt,
+                    toolArgs: call.arguments,
+                    role: sessionRef?.role || null,
+                    model: sessionRef?.model || null,
+                    resultKind: _resultKind,
+                    resultText: result,
+                });
+                // Cache stores run AFTER compress+trim+offload+hint AND after all other
+                // post-processing (trace) so stored content == history content. Placing
+                // the cache writes immediately before messages.push ensures ANY throw
+                // earlier in post-processing skips the cache entirely — no stale or
+                // partial result is ever cached. Cache-hit refs pointing to an offloaded
+                // tool_use will show the offload stub; LLM can still recover the full
+                // body via the disk path in that stub.
+                if (sessionId && _executeOk && _resultKind === 'normal') {
+                    if (_scopedCacheHit === null && _isScopedCacheableTool(call.name)) {
+                        const _outcome = sessionRef?._scopedCacheOutcomeByCallId?.get(call.id);
+                        setScopedToolCached({
+                            sessionId,
+                            toolName: _toolBare,
+                            args: call.arguments,
+                            cwd,
+                            content: result,
+                            toolUseId: call.id,
+                            complete: _outcome ? _outcome.complete : true,
+                        });
+                        sessionRef?._scopedCacheOutcomeByCallId?.delete(call.id);
+                    }
+                    if (_readCacheHit === null && _isReadTool(call.name)) {
+                        // Pass tool_use id so future cache-hits can reference the body's location in history.
+                        setReadCached({ sessionId, args: call.arguments, cwd, content: result, toolUseId: call.id });
+                    }
+                }
+                messages.push({
+                    role: 'tool',
+                    content: result,
+                    toolCallId: call.id,
+                    toolKind: _resultKind,
+                });
+            } catch (postErr) {
+                _postProcessOk = false;
+                // Post-processing failed AFTER a successful exec: the result is
+                // replaced with an error below, so preserve this call's full body
+                // too for a clean retry (mirrors the failed-exec path above).
+                if (call?.id) restoreToolCallBodyForId(_assistantTurnMsg, calls, call.id);
+                const _postMsg = `Error: tool result post-processing failed for "${call.name}": ${postErr instanceof Error ? postErr.message : String(postErr)}`;
+                // Always emit a matching tool result so the assistant
+                // tool_use isn't orphaned. Cache writes are placed at the
+                // end of the try block (immediately before messages.push),
+                // so ANY throw in post-processing reaches this catch before
+                // the cache is written — stale/partial results are never
+                // cached. The next read on the same path/scope re-executes
+                // naturally.
+                messages.push({
+                    role: 'tool',
+                    content: _postMsg,
+                    toolCallId: call.id,
+                    toolKind: 'error',
+                });
+            }
+            // Soft-cancel after each tool: if close landed during execution,
+            // discard the rest of the batch and skip the next provider.send.
+            throwIfAborted();
+        }
+        // About to re-send with tool results — transition back to connecting for the next turn.
+        if (sessionId) updateSessionStage(sessionId, 'connecting');
+    }
+    return {
+        ...response,
+        usage: lastUsage || response.usage,
+        lastTurnUsage: response.usage,
+        firstTurnUsage: firstTurnUsage || response.usage,
+        iterations,
+        toolCallsTotal,
+        providerState,
+    };
+}