mixdog 0.9.2 → 0.9.4

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

@@ -1,284 +1,108 @@
 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, takeApplyPatchUiDiff } from '../tools/patch.mjs';
+import { canonicalizeBuiltinToolName, executeBuiltinTool, isBuiltinTool } from '../tools/builtin.mjs';
+import { takeApplyPatchUiDiff } from '../tools/patch.mjs';
 import { executeInternalTool, isInternalTool } from '../internal-tools.mjs';
-import { collectSkillsCached, loadSkillResource, buildSkillToolEnvelope } from '../context/collect.mjs';
-import { normalizeToolEnvelope, makeToolEnvelope } from './tool-envelope.mjs';
+import { normalizeToolEnvelope } from './tool-envelope.mjs';
 import { traceAgentLoop, traceAgentTool, traceAgentToolFailure, traceAgentCompact, estimateProviderPayloadBytes, messagePrefixHash, appendAgentTrace } from '../agent-trace.mjs';
-import { resolveSessionMaxLoopIterations } from '../agent-runtime/agent-loop-policy.mjs';
+import { resolveSessionMaxLoopIterations, WORKER_SOFT_CAP_ITERATIONS, isWorkerSoftCapSession } from '../agent-runtime/agent-loop-policy.mjs';
 import { isAgentOwner } from '../agent-owner.mjs';
-import { markSessionToolCall, updateSessionStage, SessionClosedError, getSessionAbortSignal, enqueuePendingMessage, bumpUsageMetricsEpoch } from './manager.mjs';
+import { markSessionToolCall, updateSessionStage, SessionClosedError, bumpUsageMetricsEpoch } from './manager.mjs';
 import {
-    estimateMessagesTokens,
-    estimateRequestReserveTokens,
-    sanitizeToolPairs,
-    resolveCompactBufferRatio,
-    resolveCompactBufferTokens,
-} from './context-utils.mjs';
-import {
-    recallFastTrackCompactMessages,
     pruneToolOutputs,
     pruneToolOutputsUnanchored,
     semanticCompactMessages,
     effectiveBudget as compactEffectiveBudget,
-    compactTypeIsRecallFastTrack,
-    compactTypeIsSemantic,
-    normalizeCompactType,
     DEFAULT_COMPACT_TYPE,
-    DEFAULT_COMPACTION_KEEP_TOKENS,
-    drainSessionCycle1,
-    countRawPendingRows,
 } from './compact.mjs';
 import { isContextOverflowError } from '../providers/retry-classifier.mjs';
 import { 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 { modelVisibleToolCompletionMessage } from '../../../shared/tool-execution-contract.mjs';
-import { createHash } from 'crypto';
 import { isInvalidToolArgsMarker, formatInvalidToolArgsResult } from '../providers/openai-compat-stream.mjs';
 
-// 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 _isMutationTool(name) {
-    const n = _stripMcpPrefix(name);
-    return n === 'apply_patch';
-}
-const SCOPED_CACHEABLE_TOOLS = new Set([
-    'code_graph',
-    'grep',
-    'list',
-    'glob',
-]);
-let codeGraphRuntimePromise = null;
-async function executeCodeGraphToolLazy(name, args, cwd, signal = null, options = {}) {
-    codeGraphRuntimePromise ??= import('../tools/code-graph.mjs');
-    const mod = await codeGraphRuntimePromise;
-    if (typeof mod.executeCodeGraphTool !== 'function') throw new Error('code_graph runtime is not available');
-    return mod.executeCodeGraphTool(name, args, cwd, signal, options);
-}
-function _isScopedCacheableTool(name) {
-    const n = _stripMcpPrefix(name);
-    return SCOPED_CACHEABLE_TOOLS.has(n);
-}
-function _isShellTool(name) {
-    const n = _stripMcpPrefix(name);
-    return n === 'shell' || n === 'bash_session';
-}
+import {
+    _stripMcpPrefix,
+    _isReadTool,
+    _isMutationTool,
+    _isScopedCacheableTool,
+    _isShellTool,
+    _intraTurnSig,
+} from './loop/tool-classify.mjs';
+import { preDispatchDenyForSession } from './loop/pre-dispatch-deny.mjs';
+import { runRecallFastTrackCompact } from './loop/recall-fasttrack.mjs';
+import { executeTool, _scopedCacheOutcomeForCall } from './loop/tool-exec.mjs';
 
 // 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 the remaining
-// control-plane / role scoping 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".
-//
-// This is NOT a permission gate — runtime permission enforcement was removed
-// (every tool call is trusted). What remains is architectural scoping:
-// agent 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 `agent` tool
-    // (type=spawn|send|close|list). Denying the one name blocks all worker
-    // session control.
-    'agent',
-    // 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 _agentOwned = sessionRef?.scope?.startsWith?.('agent:')
-        || isAgentOwner(sessionRef);
-    const _controlPlaneTool = WORKER_DENIED_TOOLS.has(name);
-    if (_agentOwned && _controlPlaneTool) {
-        return `Error: control-plane tool "${name}" is Lead-only and not available to agent workers.`;
-    }
-    const noToolAgent = sessionRef?.agent === 'cycle1-agent' || sessionRef?.agent === 'cycle2-agent';
-    if (noToolAgent) {
-        return `Error: tool "${name}" is not available in agent "${sessionRef.agent}". Re-emit the answer as pipe-separated text per the agent's output format (first character a digit, NO tool_use blocks, NO JSON, NO prose, NO apology).`;
-    }
-    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 { readFileSync as _readFileSync } from 'fs';
-import { fileURLToPath } from 'url';
-import { dirname, resolve as resolvePath, isAbsolute } from 'path';
-const MCP_TOOL_PREFIX = 'mcp__plugin_mixdog_mixdog__';
-const COMPACT_SAFETY_PERCENT = 1.00;
-const COMPACT_BUFFER_MAX_WINDOW_FRACTION = 0.25;
-
-function estimateMessagesTokensSafe(messages) {
-    try { return estimateMessagesTokens(messages); }
-    catch { return null; }
-}
-
-function compactDebugEnabled() {
-    return String(process.env.MIXDOG_COMPACT_DEBUG || '').trim() === '1';
-}
-
-function compactDiagnosticError(err) {
-    if (!err) return null;
-    const text = String(err?.message || err);
-    return text.length > 500 ? `${text.slice(0, 499)}…` : text;
-}
-
-function compactByteLength(text) {
-    try { return Buffer.byteLength(String(text || ''), 'utf8'); }
-    catch { return String(text || '').length; }
-}
-
-function compactDebugLog(scope, details = {}) {
-    if (!compactDebugEnabled()) return;
-    try { process.stderr.write(`[compact] ${scope} ${JSON.stringify(details)}\n`); }
-    catch { /* best-effort diagnostics only */ }
-}
-
-function steeringContentText(content) {
-    if (typeof content === 'string') return content;
-    if (Array.isArray(content)) {
-        return content.map((part) => {
-            if (typeof part === 'string') return part;
-            if (part?.type === 'text') return part.text || '';
-            if (part?.type === 'image') return '[Image]';
-            return part?.text || '';
-        }).filter(Boolean).join('\n');
-    }
-    return String(content ?? '');
-}
-
-function normalizeSteeringEntry(entry) {
-    if (typeof entry === 'string') {
-        const text = entry.trim();
-        return text ? { content: text, text } : null;
-    }
-    if (!entry || typeof entry !== 'object') return null;
-    const content = Object.prototype.hasOwnProperty.call(entry, 'content') ? entry.content : entry;
-    const text = typeof entry.text === 'string' ? entry.text.trim() : steeringContentText(content).trim();
-    if (Array.isArray(content)) return content.length > 0 ? { content, text } : null;
-    if (typeof content === 'string') {
-        const value = content.trim();
-        return value ? { content: value, text: text || value } : null;
-    }
-    const fallback = steeringContentText(content).trim();
-    return fallback ? { content: fallback, text: text || fallback } : null;
-}
-
-function mergeSteeringEntries(entries) {
-    const normalized = (Array.isArray(entries) ? entries : [])
-        .map(normalizeSteeringEntry)
-        .filter(Boolean);
-    if (normalized.length === 0) return null;
-    const displayText = normalized.map((entry) => entry.text || steeringContentText(entry.content))
-        .filter((text) => String(text || '').trim())
-        .join('\n');
-    if (normalized.every((entry) => typeof entry.content === 'string')) {
-        return {
-            content: normalized.map((entry) => entry.content).filter(Boolean).join('\n'),
-            text: displayText,
-            count: normalized.length,
-        };
-    }
-    const parts = [];
-    for (const entry of normalized) {
-        if (typeof entry.content === 'string') {
-            if (entry.content.trim()) parts.push({ type: 'text', text: entry.content });
-        } else if (Array.isArray(entry.content)) {
-            parts.push(...entry.content);
-        } else {
-            const text = steeringContentText(entry.content);
-            if (text.trim()) parts.push({ type: 'text', text });
-        }
-        parts.push({ type: 'text', text: '\n' });
-    }
-    while (parts.length && parts[parts.length - 1]?.type === 'text' && parts[parts.length - 1]?.text === '\n') parts.pop();
-    return { content: parts, text: displayText || steeringContentText(parts), count: normalized.length };
-}
-
-class AgentContextOverflowError extends Error {
-    constructor({ stage, sessionId, provider, model, contextWindow, budgetTokens, reserveTokens, messageTokensEst }, cause) {
-        const target = [provider, model].filter(Boolean).join('/') || 'target model';
-        const causeMsg = cause && cause.message ? `: ${cause.message}` : '';
-        super(
-            `agent context overflow (${target}, stage=${stage || 'compact'}): ` +
-            `latest turn cannot fit target context budget=${budgetTokens ?? 'unknown'} ` +
-            `reserve=${reserveTokens ?? 'unknown'} contextWindow=${contextWindow ?? 'unknown'} ` +
-            `messageTokensEst=${messageTokensEst ?? 'unknown'}${causeMsg}`,
-        );
-        this.name = 'AgentContextOverflowError';
-        this.code = 'AGENT_CONTEXT_OVERFLOW';
-        this.sessionId = sessionId || null;
-        this.provider = provider || null;
-        this.model = model || null;
-        this.contextWindow = contextWindow ?? null;
-        this.budgetTokens = budgetTokens ?? null;
-        this.reserveTokens = reserveTokens ?? null;
-        this.messageTokensEst = messageTokensEst ?? null;
-        if (cause) this.cause = cause;
-    }
-}
+import { resolve as resolvePath, isAbsolute } from 'path';
+import {
+    estimateMessagesTokensSafe,
+    compactDiagnosticError,
+    compactByteLength,
+    compactDebugLog,
+} from './loop/compact-debug.mjs';
+import { mergeSteeringEntries, steeringContentText } from './loop/steering.mjs';
+import {
+    crossTurnSignature,
+    crossTurnDedupStub,
+    SOFT_CAP_WRAPUP_MESSAGE,
+    SOFT_CAP_REFUSAL_STUB,
+} from './loop/completion-guards.mjs';
+import { isEditProgressTool } from './loop/completion-guards.mjs';
+import { agentContextOverflowError } from './loop/context-overflow.mjs';
+import { positiveTokenInt } from './loop/env.mjs';
+import { normalizeUsage, addUsage } from './loop/usage.mjs';
+import { HIDDEN_AGENT_NAMES } from './loop/hidden-agents.mjs';
+import {
+    resolveWorkerCompactPolicy,
+    compactionTelemetryPressureTokens,
+    compactTargetBudget,
+    shouldCompactForSession,
+    countPrunedToolOutputs,
+    rememberCompactTelemetry,
+    emitCompactEvent,
+    compactEventType,
+} from './loop/compact-policy.mjs';
+import {
+    isEagerDispatchable,
+    messagesArrayChanged,
+    getToolKind,
+    normalizeHookUpdatedToolOutput,
+    resolveToolResultAfterHook,
+    parseNativeToolSearchPayload,
+    buildAgentBashSessionArgs,
+    formatMissingToolApprovalUiDenial,
+    resolvePreToolAskApproval,
+    approvalGranted,
+    approvalReason,
+} from './loop/tool-helpers.mjs';
+import {
+    compactToolCallsForHistory,
+    restoreToolCallBodyForId,
+} from './loop/stored-tool-args.mjs';
+import { repairTranscriptBeforeProviderSend } from './loop/transcript-repair.mjs';
+import { classifyTerminationReason, INCOMPLETE_STOP_REASONS } from './loop/termination.mjs';
+import { createSteeringLadder } from './loop/steering-ladder.mjs';
 
-function agentContextOverflowError({ stage, sessionId, sessionRef, model, budgetTokens, reserveTokens, messageTokensEst }, cause) {
-    return new AgentContextOverflowError({
-        stage,
-        sessionId,
-        provider: sessionRef?.provider || null,
-        model: sessionRef?.model || model || null,
-        contextWindow: sessionRef?.contextWindow ?? null,
-        budgetTokens,
-        reserveTokens,
-        messageTokensEst,
-    }, cause);
-}
+// Facade re-exports: these symbols moved to split modules under ./loop/ but
+// remain part of loop.mjs's public surface (imported by scripts/tests and other
+// runtime modules). Re-export the already-imported local bindings so every
+// existing import path keeps working (no duplicate module binding).
+export {
+    preDispatchDenyForSession,
+    repairTranscriptBeforeProviderSend,
+    normalizeHookUpdatedToolOutput,
+    resolveToolResultAfterHook,
+    buildAgentBashSessionArgs,
+    formatMissingToolApprovalUiDenial,
+    resolvePreToolAskApproval,
+    approvalGranted,
+    approvalReason,
+};
 
-// Cache-hit results always inline the cached body. The earlier size-gated
-// `[cache-hit-ref]` branch confused agents 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
@@ -289,982 +113,8 @@ function agentContextOverflowError({ stage, sessionId, sessionRef, model, budget
 // 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 _AGENTS_JSON = resolvePath(dirname(fileURLToPath(import.meta.url)), '../../../../defaults/agents.json');
-let _hiddenAgentsCache = null;
-function _getHiddenAgents() {
-    if (_hiddenAgentsCache) return _hiddenAgentsCache;
-    try {
-        _hiddenAgentsCache = JSON.parse(_readFileSync(_AGENTS_JSON, 'utf8'));
-    } catch { _hiddenAgentsCache = { agents: [] }; }
-    return _hiddenAgentsCache;
-}
-// 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 {}
-    }
-}
-
-/**
- * Pre-provider transcript repair for the agent loop. Reattach valid tool
- * results (non-destructive) before any destructive orphan pairing cleanup.
- * Mutates `messages` in place to preserve the session array reference.
- */
-export function repairTranscriptBeforeProviderSend(messages, sessionId = null) {
-    if (!Array.isArray(messages)) return messages;
-    const sanitized = sanitizeToolPairs(messages);
-    if (sanitized !== messages) {
-        messages.length = 0;
-        messages.push(...sanitized);
-    }
-    _ensureTranscriptPairing(messages, sessionId);
-    return messages;
-}
-
-// 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;
-}
-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;
-}
-function normalizeUsage(usage) {
-    if (!usage) return null;
-    const costUsd = Number(usage.costUsd);
-    return {
-        inputTokens: usage.inputTokens || 0,
-        outputTokens: usage.outputTokens || 0,
-        cachedTokens: usage.cachedTokens || 0,
-        cacheWriteTokens: usage.cacheWriteTokens || 0,
-        promptTokens: usage.promptTokens || 0,
-        ...(Number.isFinite(costUsd) ? { costUsd } : {}),
-        raw: usage.raw,
-    };
-}
-function addUsage(total, usage) {
-    const delta = normalizeUsage(usage);
-    if (!delta) return total;
-    if (!total) return { ...delta };
-    const next = {
-        ...total,
-        inputTokens: (total.inputTokens || 0) + delta.inputTokens,
-        outputTokens: (total.outputTokens || 0) + delta.outputTokens,
-        cachedTokens: (total.cachedTokens || 0) + delta.cachedTokens,
-        cacheWriteTokens: (total.cacheWriteTokens || 0) + delta.cacheWriteTokens,
-        promptTokens: (total.promptTokens || 0) + delta.promptTokens,
-    };
-    if (delta.costUsd != null || total.costUsd != null) {
-        next.costUsd = (total.costUsd || 0) + (delta.costUsd || 0);
-    }
-    return next;
-}
-function positiveTokenInt(value) {
-    const n = Number(value);
-    return Number.isFinite(n) && n > 0 ? Math.floor(n) : null;
-}
-function envFlag(name, fallback = false) {
-    const v = process.env[name];
-    if (v === undefined) return fallback;
-    return !['0', 'false', 'off', 'no'].includes(String(v).trim().toLowerCase());
-}
-function envTokenInt(name) {
-    return positiveTokenInt(process.env[name]);
-}
-function resolveSemanticCompactSetting(sessionRef, cfg = {}) {
-    if (process.env.MIXDOG_AGENT_COMPACT_SEMANTIC !== undefined) return envFlag('MIXDOG_AGENT_COMPACT_SEMANTIC', true);
-    if (cfg.semantic === false || cfg.semantic === 'false' || cfg.semantic === 'off') return false;
-    if (cfg.semantic === true || cfg.semantic === 'true' || cfg.semantic === 'on') return true;
-    // The compact type is already explicit (`semantic` by default). Honor it
-    // directly instead of substituting another compaction path.
-    return true;
-}
-
-function resolveCompactTypeSetting(_sessionRef, cfg = {}) {
-    const configured = process.env.MIXDOG_AGENT_COMPACT_TYPE
-        ?? process.env.MIXDOG_COMPACT_TYPE
-        ?? cfg.type
-        ?? cfg.compactType
-        ?? cfg.compact_type;
-    return normalizeCompactType(configured, DEFAULT_COMPACT_TYPE);
-}
-
-async function runRecallFastTrackCompact({ sessionRef, messages, compactBudgetTokens, compactPolicy, sessionId, signal }) {
-    if (!sessionId) throw new Error('recall-fasttrack requires a session id');
-    const startedAt = Date.now();
-    const diagnostics = {
-        hydrateLimit: null,
-        ingestMs: null,
-        ingestSkipped: false,
-        ingestError: null,
-        initialDumpMs: null,
-        initialDumpBytes: null,
-        initialDumpChars: null,
-        initialRawPending: null,
-        cycle1Ms: null,
-        cycle1Skipped: false,
-        cycle1SkipReason: null,
-        cycle1Passes: null,
-        cycle1RawRemaining: null,
-        cycle1TextBytes: null,
-        cycle1Error: null,
-        finalRecallBytes: null,
-        finalRecallChars: null,
-        totalMs: null,
-    };
-    const query = `session:${sessionId}:all-chunks`;
-    const querySha = createHash('sha256').update(query).digest('hex').slice(0, 16);
-    const callerCtx = {
-        callerSessionId: sessionId || null,
-        callerCwd: sessionRef?.cwd || undefined,
-        routingSessionId: sessionId || null,
-        clientHostPid: sessionRef?.clientHostPid,
-        signal: signal || null,
-    };
-    const hydrateLimit = positiveTokenInt(sessionRef?.compaction?.recallIngestLimit)
-        || Math.max(500, Math.min(5000, messages.length || 0));
-    diagnostics.hydrateLimit = hydrateLimit;
-    let t0 = Date.now();
-    try {
-        await executeInternalTool('memory', {
-            action: 'ingest_session',
-            sessionId,
-            messages,
-            cwd: sessionRef?.cwd,
-            limit: hydrateLimit,
-        }, callerCtx);
-    } catch (err) {
-        diagnostics.ingestSkipped = true;
-        diagnostics.ingestError = compactDiagnosticError(err);
-        try { process.stderr.write(`[loop] recall-fasttrack ingest skipped (sess=${sessionId || 'unknown'}): ${err?.message || err}\n`); } catch {}
-    } finally {
-        diagnostics.ingestMs = Date.now() - t0;
-    }
-    const dumpArgs = {
-        action: 'dump_session_roots',
-        sessionId,
-        includeRaw: true,
-        limit: positiveTokenInt(sessionRef?.compaction?.recallChunkLimit ?? sessionRef?.compaction?.recallLimit) || hydrateLimit,
-    };
-    const runTool = (name, args) => executeInternalTool(name, args, callerCtx);
-    t0 = Date.now();
-    let recallText = await executeInternalTool('memory', dumpArgs, callerCtx);
-    diagnostics.initialDumpMs = Date.now() - t0;
-    diagnostics.initialDumpChars = String(recallText || '').length;
-    diagnostics.initialDumpBytes = compactByteLength(recallText);
-    diagnostics.initialRawPending = countRawPendingRows(recallText);
-    let cycle1Text = '';
-    const hasRawRows = /(?:^|\n)# raw_pending\s+\d+\s+id=/i.test(String(recallText || ''));
-    if (hasRawRows) {
-        t0 = Date.now();
-        try {
-            // Drain this session's cycle1 in window×concurrency units until no
-            // raw rows remain, so the injected root is fully chunked rather than
-            // carrying the unprocessed transcript tail (single-pass left raw in).
-            const drained = await drainSessionCycle1(runTool, {
-                sessionId,
-                dumpArgs,
-                deadlineMs: positiveTokenInt(sessionRef?.compaction?.recallCycle1DeadlineMs) || 120_000,
-                maxPasses: positiveTokenInt(sessionRef?.compaction?.recallCycle1MaxPasses) || 0,
-                cycleArgs: {
-                    min_batch: 1,
-                    session_cap: 1,
-                    batch_size: positiveTokenInt(sessionRef?.compaction?.recallCycle1BatchSize) || 100,
-                    rows_per_session: positiveTokenInt(sessionRef?.compaction?.recallRowsPerSession) || 100,
-                    window_size: positiveTokenInt(sessionRef?.compaction?.recallWindowSize) || 20,
-                    concurrency: positiveTokenInt(sessionRef?.compaction?.recallConcurrency) || 5,
-                },
-            });
-            recallText = drained.recallText;
-            cycle1Text = drained.cycle1Text;
-            diagnostics.cycle1Passes = drained.passes;
-            diagnostics.cycle1RawRemaining = drained.rawRemaining;
-            diagnostics.cycle1TextBytes = compactByteLength(cycle1Text);
-            if (drained.rawRemaining > 0) {
-                try { process.stderr.write(`[loop] recall-fasttrack drained passes=${drained.passes} rawRemaining=${drained.rawRemaining} (sess=${sessionId || 'unknown'})\n`); } catch {}
-            }
-        } catch (err) {
-            diagnostics.cycle1Error = compactDiagnosticError(err);
-            try { process.stderr.write(`[loop] recall-fasttrack cycle1 skipped (sess=${sessionId || 'unknown'}): ${err?.message || err}\n`); } catch {}
-        } finally {
-            diagnostics.cycle1Ms = Date.now() - t0;
-        }
-    } else {
-        diagnostics.cycle1Skipped = true;
-        diagnostics.cycle1SkipReason = 'session chunks already hydrated';
-        diagnostics.cycle1Passes = 0;
-        diagnostics.cycle1RawRemaining = 0;
-        cycle1Text = 'cycle1: skipped (session chunks already hydrated)';
-    }
-    const combinedRecallText = [`session_id=${sessionId}`, cycle1Text, recallText].map(v => String(v || '').trim()).filter(Boolean).join('\n\n');
-    diagnostics.finalRecallChars = combinedRecallText.length;
-    diagnostics.finalRecallBytes = compactByteLength(combinedRecallText);
-    const result = recallFastTrackCompactMessages(messages, compactBudgetTokens, {
-        reserveTokens: compactPolicy.reserveTokens,
-        force: true,
-        recallText: combinedRecallText,
-        query,
-        querySha,
-        allowEmptyRecall: true,
-        tailTurns: compactPolicy.tailTurns,
-        keepTokens: compactPolicy.keepTokens,
-        preserveRecentTokens: compactPolicy.preserveRecentTokens,
-    });
-    diagnostics.totalMs = Date.now() - startedAt;
-    if (result && typeof result === 'object') {
-        result.diagnostics = {
-            ...(result.diagnostics || {}),
-            pipeline: diagnostics,
-        };
-    }
-    compactDebugLog('recall-fasttrack pipeline', diagnostics);
-    return result;
-}
-const COMPACT_TARGET_RATIO = 0.02;
-const COMPACT_TARGET_MIN_TOKENS = 4_000;
-const COMPACT_TARGET_MAX_TOKENS = 16_000;
-function resolveCompactTargetRatio(cfg = {}) {
-    const raw = cfg.targetPercent
-        ?? cfg.targetPct
-        ?? cfg.targetRatio
-        ?? cfg.targetFraction
-        ?? process.env.MIXDOG_AGENT_COMPACT_TARGET_PERCENT
-        ?? process.env.MIXDOG_COMPACT_TARGET_PERCENT
-        ?? COMPACT_TARGET_RATIO;
-    const n = Number(raw);
-    if (!Number.isFinite(n) || n <= 0) return COMPACT_TARGET_RATIO;
-    return n > 1 ? n / 100 : n;
-}
-function resolveCompactTargetTokens(boundaryTokens, cfg = {}) {
-    const boundary = positiveTokenInt(boundaryTokens);
-    if (!boundary) return null;
-    const explicit = positiveTokenInt(cfg.targetTokens ?? cfg.target)
-        || envTokenInt('MIXDOG_AGENT_COMPACT_TARGET_TOKENS')
-        || envTokenInt('MIXDOG_COMPACT_TARGET_TOKENS');
-    if (explicit) return Math.max(1, Math.min(boundary, explicit));
-    const minTarget = Math.min(boundary, positiveTokenInt(cfg.targetMinTokens ?? cfg.minTargetTokens)
-        || envTokenInt('MIXDOG_AGENT_COMPACT_TARGET_MIN_TOKENS')
-        || envTokenInt('MIXDOG_COMPACT_TARGET_MIN_TOKENS')
-        || COMPACT_TARGET_MIN_TOKENS);
-    const maxTarget = Math.min(boundary, positiveTokenInt(cfg.targetMaxTokens ?? cfg.maxTargetTokens)
-        || envTokenInt('MIXDOG_AGENT_COMPACT_TARGET_MAX_TOKENS')
-        || envTokenInt('MIXDOG_COMPACT_TARGET_MAX_TOKENS')
-        || COMPACT_TARGET_MAX_TOKENS);
-    const byRatio = Math.max(1, Math.floor(boundary * resolveCompactTargetRatio(cfg)));
-    return Math.max(1, Math.min(boundary, maxTarget, Math.max(minTarget, byRatio)));
-}
-function resolveCompactKeepTokens(cfg = {}) {
-    return positiveTokenInt(cfg.keepTokens ?? cfg.keep?.tokens ?? cfg.preserveRecentTokens)
-        || envTokenInt('MIXDOG_AGENT_COMPACT_KEEP_TOKENS')
-        || DEFAULT_COMPACTION_KEEP_TOKENS;
-}
-function resolveWorkerCompactPolicy(sessionRef, tools) {
-    if (!sessionRef) return null;
-    const cfg = sessionRef.compaction || {};
-    const auto = cfg.auto !== false && envFlag('MIXDOG_AGENT_COMPACT_AUTO', true);
-    if (!auto) return { auto: false };
-    const contextWindow = positiveTokenInt(sessionRef.contextWindow ?? cfg.contextWindow);
-    const explicitBoundary = positiveTokenInt(sessionRef.compactBoundaryTokens ?? cfg.boundaryTokens);
-    const autoLimit = positiveTokenInt(sessionRef.autoCompactTokenLimit ?? cfg.autoCompactTokenLimit);
-    const boundaryTokens = explicitBoundary && contextWindow
-        ? Math.min(explicitBoundary, contextWindow)
-        : (explicitBoundary || contextWindow || autoLimit);
-    if (!boundaryTokens) return null;
-    const compactBoundaryTokens = Math.max(1, Math.floor(boundaryTokens * COMPACT_SAFETY_PERCENT));
-    // Only an explicit auto-compact limit STRICTLY BELOW the boundary acts as
-    // the trigger. A persisted value == boundary (legacy derived full-window
-    // autoCompactTokenLimit) would set autoTriggerTokens == boundary and
-    // collapse/override the default trigger, so it is ignored in favor of the
-    // default boundary trigger.
-    const autoTriggerTokens = autoLimit && autoLimit < compactBoundaryTokens ? Math.max(1, autoLimit) : null;
-    // Sanitized explicit limit: only a sub-boundary value is a real auto-compact
-    // limit. Anything >= boundary is a legacy derived full-window artifact and
-    // is reported as null so rememberCompactTelemetry does not re-persist it
-    // back onto the session and re-collapse the buffer on the next turn.
-    const explicitAutoCompactTokenLimit = autoTriggerTokens;
-    const bufferTokens = autoTriggerTokens
-        ? Math.max(0, compactBoundaryTokens - autoTriggerTokens)
-        : resolveCompactBufferTokens(compactBoundaryTokens, cfg);
-    const bufferRatio = compactBoundaryTokens ? (bufferTokens / compactBoundaryTokens) : resolveCompactBufferRatio(cfg);
-    const triggerTokens = autoTriggerTokens || Math.max(1, compactBoundaryTokens - bufferTokens);
-    const configuredReserve = positiveTokenInt(cfg.reservedTokens)
-        || envTokenInt('MIXDOG_AGENT_COMPACT_RESERVED_TOKENS')
-        || 0;
-    const requestReserve = estimateRequestReserveTokens(tools);
-    const keepTokens = resolveCompactKeepTokens(cfg);
-    const compactType = resolveCompactTypeSetting(sessionRef, cfg);
-    return {
-        auto: true,
-        type: compactType,
-        compactType,
-        prune: cfg.prune === true || envFlag('MIXDOG_AGENT_COMPACT_PRUNE', false),
-        boundaryTokens: compactBoundaryTokens,
-        triggerTokens,
-        bufferTokens,
-        bufferRatio,
-        contextWindow,
-        rawContextWindow: positiveTokenInt(sessionRef.rawContextWindow ?? cfg.rawContextWindow) || contextWindow,
-        effectiveContextWindowPercent: Number.isFinite(Number(sessionRef.effectiveContextWindowPercent ?? cfg.effectiveContextWindowPercent))
-            ? Number(sessionRef.effectiveContextWindowPercent ?? cfg.effectiveContextWindowPercent)
-            : null,
-        autoCompactTokenLimit: explicitAutoCompactTokenLimit,
-        semantic: compactTypeIsSemantic(compactType) && resolveSemanticCompactSetting(sessionRef, cfg),
-        recallFastTrack: compactTypeIsRecallFastTrack(compactType),
-        semanticTimeoutMs: positiveTokenInt(cfg.timeoutMs) || envTokenInt('MIXDOG_AGENT_COMPACT_TIMEOUT_MS') || 30_000,
-        tailTurns: positiveTokenInt(cfg.tailTurns) || envTokenInt('MIXDOG_AGENT_COMPACT_TAIL_TURNS') || 2,
-        keepTokens,
-        preserveRecentTokens: positiveTokenInt(cfg.preserveRecentTokens) || envTokenInt('MIXDOG_AGENT_COMPACT_PRESERVE_RECENT_TOKENS') || keepTokens,
-        reserveTokens: requestReserve + configuredReserve,
-        requestReserveTokens: requestReserve,
-        configuredReserveTokens: configuredReserve,
-    };
-}
-/** Transcript + request reserve only (never provider lastContextTokens). */
-function compactPressureTokens(messageTokensEst, policy) {
-    if (messageTokensEst === null) return 0;
-    return Math.max(0, messageTokensEst + (policy?.reserveTokens || 0));
-}
-
-/** Telemetry pressure when a reactive overflow retry forces the next compact. */
-function compactionTelemetryPressureTokens(messageTokensEst, policy, { reactivePending = false } = {}) {
-    const base = compactPressureTokens(messageTokensEst, policy);
-    if (!reactivePending) return base;
-    const floor = positiveTokenInt(policy?.triggerTokens) || positiveTokenInt(policy?.boundaryTokens) || 0;
-    return floor ? Math.max(base, floor) : base;
-}
-function compactTargetBudget(policy) {
-    const boundary = positiveTokenInt(policy?.boundaryTokens);
-    if (!boundary) return null;
-    const reserve = Math.max(0, Number(policy?.reserveTokens) || 0);
-    const targetEffective = resolveCompactTargetTokens(boundary, policy) || boundary;
-    return Math.max(1, Math.min(boundary, targetEffective + reserve));
-}
-function shouldCompactForSession(messageTokensEst, policy, { forceReactive = false } = {}) {
-    if (!policy?.auto || !policy.boundaryTokens) return false;
-    if (forceReactive) return true;
-    if (messageTokensEst === null) return true;
-    return compactPressureTokens(messageTokensEst, policy) >= (policy.triggerTokens || policy.boundaryTokens);
-}
-function countPrunedToolOutputs(before, after) {
-    if (!Array.isArray(before) || !Array.isArray(after)) return 0;
-    let count = 0;
-    const n = Math.min(before.length, after.length);
-    for (let i = 0; i < n; i += 1) {
-        if (before[i]?.role !== 'tool' || after[i]?.role !== 'tool') continue;
-        if (before[i]?.content !== after[i]?.content && after[i]?.compactedKind === 'tool_output_prune') count += 1;
-    }
-    return count;
-}
-function rememberCompactTelemetry(sessionRef, policy, meta = {}) {
-    if (!sessionRef || !policy) return;
-    const prev = sessionRef.compaction && typeof sessionRef.compaction === 'object'
-        ? sessionRef.compaction
-        : {};
-    const changed = meta.compactChanged === true || meta.pruneCount > 0;
-    sessionRef.compaction = {
-        ...prev,
-        auto: policy.auto !== false,
-        prune: policy.prune === true,
-        reservedTokens: policy.configuredReserveTokens || prev.reservedTokens || null,
-        requestReserveTokens: policy.requestReserveTokens || 0,
-        reserveTokens: policy.reserveTokens || 0,
-        boundaryTokens: policy.boundaryTokens || null,
-        triggerTokens: policy.triggerTokens || null,
-        bufferTokens: policy.bufferTokens || 0,
-        bufferRatio: policy.bufferRatio ?? prev.bufferRatio ?? null,
-        contextWindow: policy.contextWindow || null,
-        rawContextWindow: policy.rawContextWindow || null,
-        effectiveContextWindowPercent: policy.effectiveContextWindowPercent ?? null,
-        autoCompactTokenLimit: policy.autoCompactTokenLimit || null,
-        type: policy.compactType || policy.type || DEFAULT_COMPACT_TYPE,
-        compactType: policy.compactType || policy.type || DEFAULT_COMPACT_TYPE,
-        semantic: policy.semantic === true ? 'auto' : false,
-        recallFastTrack: policy.recallFastTrack === true,
-        semanticModel: policy.semanticModel || null,
-        semanticTimeoutMs: policy.semanticTimeoutMs || null,
-        tailTurns: policy.tailTurns || null,
-        keepTokens: policy.keepTokens || null,
-        preserveRecentTokens: policy.preserveRecentTokens || null,
-        lastCheckedAt: Date.now(),
-        lastBeforeTokens: meta.beforeTokens ?? null,
-        lastAfterTokens: meta.afterTokens ?? null,
-        lastPressureTokens: meta.pressureTokens ?? null,
-        currentEstimatedTokens: meta.pressureTokens ?? prev.currentEstimatedTokens ?? null,
-        lastApiRequestTokens: positiveTokenInt(sessionRef?.lastContextTokens) || prev.lastApiRequestTokens || null,
-        lastStage: meta.stage || prev.lastStage || null,
-        lastChanged: changed,
-        lastTrigger: meta.trigger || prev.lastTrigger || null,
-        lastSemantic: meta.semanticCompact === true,
-        lastSemanticError: Object.hasOwn(meta, 'semanticError')
-            ? (meta.semanticError ?? null)
-            : (prev.lastSemanticError ?? null),
-        lastRecallFastTrack: meta.recallFastTrack === true,
-        lastRecallFastTrackError: Object.hasOwn(meta, 'recallFastTrackError')
-            ? (meta.recallFastTrackError ?? null)
-            : (prev.lastRecallFastTrackError ?? null),
-        lastError: Object.hasOwn(meta, 'compactError') || Object.hasOwn(meta, 'lastError')
-            ? (meta.compactError ?? meta.lastError ?? null)
-            : (prev.lastError ?? null),
-        lastPruneCount: meta.pruneCount || 0,
-        lastDurationMs: meta.durationMs != null && Number.isFinite(Number(meta.durationMs))
-            ? Math.max(0, Math.round(Number(meta.durationMs)))
-            : null,
-        compactCount: (prev.compactCount || 0) + (changed ? 1 : 0),
-    };
-    if (changed) {
-        const changedAt = Date.now();
-        sessionRef.compaction.lastChangedAt = changedAt;
-        sessionRef.compaction.lastCompactAt = changedAt;
-        sessionRef.lastContextTokensStaleAfterCompact = true;
-    }
-    sessionRef.contextWindow = policy.contextWindow || sessionRef.contextWindow;
-    sessionRef.rawContextWindow = policy.rawContextWindow || sessionRef.rawContextWindow;
-    sessionRef.compactBoundaryTokens = policy.boundaryTokens || sessionRef.compactBoundaryTokens || null;
-    // Persist only the sanitized (sub-boundary) explicit limit. policy.autoCompactTokenLimit
-    // is already null for legacy derived full-window values, so a stale
-    // boundary-sized autoCompactTokenLimit on the session is cleared here rather
-    // than carried forward to re-collapse the buffer next turn.
-    {
-        const _boundary = positiveTokenInt(sessionRef.compactBoundaryTokens);
-        const _prevLimit = positiveTokenInt(sessionRef.autoCompactTokenLimit);
-        const _keepPrev = _prevLimit && (!_boundary || _prevLimit < _boundary) ? _prevLimit : null;
-        sessionRef.autoCompactTokenLimit = policy.autoCompactTokenLimit || _keepPrev || null;
-    }
-    if (policy.effectiveContextWindowPercent !== null) {
-        sessionRef.effectiveContextWindowPercent = policy.effectiveContextWindowPercent;
-    }
-}
-
-function emitCompactEvent(opts, event = {}) {
-    if (!opts || typeof opts.onCompactEvent !== 'function') return;
-    try { opts.onCompactEvent({ ts: Date.now(), ...event }); }
-    catch { /* best-effort UI/log hook */ }
-}
-
-function compactEventType(policy, fallback = DEFAULT_COMPACT_TYPE) {
-    return policy?.compactType || policy?.type || fallback;
-}
-const SKILL_TOOL_NAMES = new Set(['Skill', 'skills_list', 'skill_view']);
-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 res = loadSkillResource(name, cwd);
-    if (!res) return `Error: skill "${name}" not found`;
-    // Return the general tool envelope: the model-visible tool_result is the
-    // short stub (`Loaded skill: <name>`) and the full SKILL.md body is
-    // delivered ONCE as a separate injected role:'user' message (newMessages).
-    return buildSkillToolEnvelope(name, res.content, res.dir);
-}
-
-/** Normalize PostToolUse hook override values (legacy MCP text envelopes only). */
-export function normalizeHookUpdatedToolOutput(value) {
-    if (typeof value === 'string') return value;
-    if (value == null) return '';
-    if (typeof value === 'object' && Array.isArray(value.content)) {
-        const hasNonText = value.content.some((c) => c && typeof c === 'object' && c.type && c.type !== 'text');
-        if (hasNonText) return value;
-        return value.content
-            .map((c) => (c?.type === 'text' ? c.text || '' : JSON.stringify(c)))
-            .join('\n');
-    }
-    return value;
-}
-
-export function resolveToolResultAfterHook(originalResult, hookResult) {
-    if (!hookResult || typeof hookResult !== 'object' || hookResult.updatedToolOutput === undefined) {
-        return originalResult;
-    }
-    const updated = normalizeHookUpdatedToolOutput(hookResult.updatedToolOutput);
-    return updated === undefined ? originalResult : updated;
-}
-
-function parseNativeToolSearchPayload(toolName, result) {
-    if (toolName !== 'tool_search' || typeof result !== 'string') return null;
-    try {
-        const parsed = JSON.parse(result);
-        const native = parsed?.nativeToolSearch;
-        if (!native || typeof native !== 'object') return null;
-        const toolReferences = Array.isArray(native.toolReferences)
-            ? native.toolReferences.map((name) => String(name || '').trim()).filter(Boolean)
-            : [];
-        const openaiTools = Array.isArray(native.openaiTools)
-            ? native.openaiTools.filter((tool) => tool && typeof tool === 'object')
-            : [];
-        if (!toolReferences.length && !openaiTools.length) return null;
-        return {
-            toolReferences,
-            openaiTools,
-            summary: typeof native.summary === 'string' && native.summary
-                ? native.summary
-                : `Loaded deferred tools: ${toolReferences.join(', ') || openaiTools.map((tool) => tool.name).filter(Boolean).join(', ')}`,
-        };
-    } catch {
-        return null;
-    }
-}
-function extractBashSessionId(result) {
-    if (typeof result !== 'string') return null;
-    const match = BASH_SESSION_HEADER_RE.exec(result);
-    return match ? match[1] : null;
-}
-
-export function buildAgentBashSessionArgs(args, sessionRef) {
-    if (!isAgentOwner(sessionRef)) 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
-    // task_id that task control can resolve — otherwise the persistent
-    // session returns a [session: ...] header and task control reports "task 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;
-}
-
-export function formatMissingToolApprovalUiDenial(toolName, askReason) {
-    const reason = String(askReason || 'approval requested by hook').trim();
-    const name = String(toolName || 'tool');
-    return `Error: tool "${name}" denied by hook: approval required but no approval UI is available${reason ? ` (${reason})` : ''}`;
-}
-
-/**
- * Resolve PreToolUse `{ action: 'ask' }` against an optional approval callback.
- * Returns `{ denial }` when the tool must not run; otherwise `{ approval }`.
- */
-export async function resolvePreToolAskApproval({
-    toolName,
-    args,
-    cwd,
-    sessionId,
-    toolCallId,
-    askReason,
-    toolApprovalHook,
-}) {
-    const name = String(toolName || 'tool');
-    const reason = String(askReason || 'approval requested by hook').trim();
-    if (typeof toolApprovalHook !== 'function') {
-        return { denial: formatMissingToolApprovalUiDenial(name, reason) };
-    }
-    let approval;
-    try {
-        approval = await toolApprovalHook({
-            name,
-            args,
-            cwd,
-            sessionId,
-            toolCallId: toolCallId || null,
-            reason,
-        });
-    } catch (error) {
-        const detail = error?.message || String(error || 'approval failed');
-        return { denial: `Error: tool "${name}" denied by hook: ${detail}` };
-    }
-    if (!approvalGranted(approval)) {
-        const detail = approvalReason(approval, reason || 'not approved');
-        return { denial: `Error: tool "${name}" denied by hook: ${detail}` };
-    }
-    return { approval };
-}
-
-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;
-    const notificationSessionId = String(executeOpts.notifySessionId || sessionRef?.ownerSessionId || callerSessionId || '').trim();
-    const notifyFn = typeof executeOpts.notifyFn === 'function'
-        ? executeOpts.notifyFn
-        : (text, meta = {}) => {
-            if (!notificationSessionId) return;
-            try {
-                const visible = modelVisibleToolCompletionMessage(text, meta);
-                if (visible) enqueuePendingMessage(notificationSessionId, visible);
-            } catch { /* best effort */ }
-        };
-    const completionToolOpts = {
-        ...toolOpts,
-        sessionId: callerSessionId,
-        callerSessionId: notificationSessionId || callerSessionId,
-        routingSessionId: callerSessionId,
-        clientHostPid: sessionRef?.clientHostPid,
-        notifyFn,
-    };
-    const beforeToolHook = typeof executeOpts.beforeToolHook === 'function'
-        ? executeOpts.beforeToolHook
-        : sessionRef?.beforeToolHook;
-    const toolApprovalHook = typeof executeOpts.toolApprovalHook === 'function'
-        ? executeOpts.toolApprovalHook
-        : sessionRef?.toolApprovalHook;
-    if (beforeToolHook) {
-        try {
-            const decision = await beforeToolHook({
-                name,
-                args,
-                cwd,
-                sessionId: callerSessionId,
-                toolCallId: executeOpts.toolCallId || null,
-            });
-            const action = String(decision?.action || decision?.decision || '').toLowerCase();
-            if (action === 'deny' || action === 'block') {
-                const reason = decision?.reason ? `: ${decision.reason}` : '';
-                return `Error: tool "${name}" denied by hook${reason}`;
-            }
-            if (action === 'ask') {
-                const askReason = String(decision?.reason || 'approval requested by hook').trim();
-                const askOutcome = await resolvePreToolAskApproval({
-                    toolName: name,
-                    args,
-                    cwd,
-                    sessionId: callerSessionId,
-                    toolCallId: executeOpts.toolCallId || null,
-                    askReason,
-                    toolApprovalHook,
-                });
-                if (askOutcome.denial) return askOutcome.denial;
-                const approval = askOutcome.approval;
-                if (approval && typeof approval === 'object' && approval.args && typeof approval.args === 'object' && !Array.isArray(approval.args)) {
-                    args = approval.args;
-                }
-            }
-            if ((action === 'modify' || action === 'rewrite') && decision?.args && typeof decision.args === 'object' && !Array.isArray(decision.args)) {
-                args = decision.args;
-            }
-        } catch {
-            // Hooks are policy extensions. A broken hook must not wedge the agent loop.
-        }
-    }
-    const afterToolHook = typeof executeOpts.afterToolHook === 'function'
-        ? executeOpts.afterToolHook
-        : sessionRef?.afterToolHook;
-    const __result = await (async () => {
-    if (name === 'Skill') {
-        return viewSkill(cwd, args?.name);
-    }
-    if (name === 'skills_list') {
-        return buildSkillsListResponse(cwd);
-    }
-    if (name === 'skill_view') {
-        return viewSkill(cwd, args?.name);
-    }
-    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 (name === 'code_graph') {
-        // 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 executeCodeGraphToolLazy(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,
-            clientHostPid: sessionRef?.clientHostPid,
-            signal: executeOpts.signal,
-            routingSessionId: callerSessionId,
-            notifyFn,
-        });
-    }
-    if (name === 'shell') {
-        const routedArgs = buildAgentBashSessionArgs(args, sessionRef);
-        if (!routedArgs) {
-            // clientHostPid scopes background shell-jobs to the dispatching
-            // terminal's claude.exe pid (agent sessions store it on sessionRef);
-            // without it resolveJobOwnerHostPid falls back to the daemon-global env.
-            return executeBuiltinTool(name, args, cwd, completionToolOpts);
-        }
-        // Thread the session's AbortSignal so agent 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') {
-        const patchArgs = typeof args === 'string' ? { patch: args } : args;
-        return executePatchTool(name, patchArgs, cwd, { sessionId: callerSessionId, toolCallId: executeOpts.toolCallId || null });
-    }
-    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, completionToolOpts);
-    }
-    return formatUnknownBuiltinToolMessage(name, args, 'tool');
-    })();
-    if (typeof afterToolHook === 'function') {
-        try {
-            const hookResult = await afterToolHook({
-                name,
-                args,
-                cwd,
-                sessionId: callerSessionId,
-                toolCallId: executeOpts.toolCallId || null,
-                result: __result,
-            });
-            // Envelope-aware hook override: a PostToolUse hook may override the
-            // model-VISIBLE tool output (the envelope's `result` / stub), but it
-            // must NEVER drop the `newMessages` channel. Split first, apply the
-            // override to `result` only, then re-wrap so newMessages survive.
-            const { result: __res, newMessages: __nm } = normalizeToolEnvelope(__result);
-            const __overridden = resolveToolResultAfterHook(__res, hookResult);
-            if (__nm.length) return makeToolEnvelope(__overridden, __nm);
-            return __overridden;
-        } catch {
-            // PostToolUse hooks are best-effort; never let one break the tool result.
-        }
-    }
-    return __result;
-}
+// _scopedCacheOutcomeForCall and executeTool moved to ./loop/tool-exec.mjs
+// (imported above).
 /**
  * Agent loop: send → tool_call → execute → re-send → repeat until text.
  * sendOpts may include:
@@ -1276,38 +126,11 @@ async function executeTool(name, args, cwd, callerSessionId, sessionRef, execute
  *                wrapper can propagate a clean cancellation.
  *   - `onStageChange(stage)` / `onStreamDelta()` — forwarded to provider.send for heartbeats
  */
-// Source of truth: defaults/agents.json (loaded via _getHiddenAgents
-// above). Build the name Set eagerly at module load so HIDDEN_AGENT_NAMES
-// stays in sync with the declarative registry — no hardcoded duplicate.
-const HIDDEN_AGENT_NAMES = new Set(
-    (_getHiddenAgents().agents || []).map((r) => r && r.agent).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 function approvalGranted(value) {
-    if (value === true) return true;
-    if (!value || typeof value !== 'object') return false;
-    if (value.approved === true || value.allow === true || value.allowed === true) return true;
-    const decision = String(value.decision || value.action || value.result || '').trim().toLowerCase();
-    return decision === 'approve' || decision === 'approved' || decision === 'allow' || decision === 'yes';
-}
-
-export function approvalReason(value, fallback = '') {
-    if (value && typeof value === 'object') {
-        const reason = String(value.reason || value.message || '').trim();
-        if (reason) return reason;
-    }
-    return fallback;
-}
-
 export async function agentLoop(provider, messages, model, tools, onToolCall, cwd, sendOpts) {
     let iterations = 0;
     let toolCallsTotal = 0;
@@ -1403,11 +226,57 @@ export async function agentLoop(provider, messages, model, tools, onToolCall, cw
         return true;
     };
     const maxLoopIterations = resolveSessionMaxLoopIterations(sessionRef);
+    // ---- Completion-first loop guards (worker runaway prevention) ----
+    // Step 1 (escalation ladder) + the missed-parallelism / serial-rewording
+    // steering hints live in the createSteeringLadder controller below; it owns
+    // their cumulative counters and emits at most one hint per turn.
+    // _editCount counts any executed tool call whose def lacks readOnlyHint
+    // (i.e. edit/progress: apply_patch, bash, MCP writes, skills, ...).
+    let _editCount = 0;
+    // Step 2: cross-turn identical read-only call dedup. Map keyed by
+    // signature(name + stableStringify(args)) → { count, firstIteration }.
+    // Populated only for SUCCESSFUL isEagerDispatchable (read-only) calls.
+    // Bounded to 500 entries (drop-oldest / insertion order).
+    const _crossTurnCalls = new Map();
+    const _CROSS_TURN_CAP = 500;
+    let _dedupStubTotal = 0;
+    // Step 3: worker soft-cap wrap-up state.
+    const _softCapEnabled = isWorkerSoftCapSession(sessionRef);
+    let _softCapActive = false;      // tools disabled + wrap-up injected
+    let _softCapGraceTurns = 0;      // text-only grace turns consumed (max 2)
+    let _terminatedBySoftCap = false;
+    // Completion-first steering ladder controller. Owns the (cumulative) level-1
+    // fire count, the all-read-only / serial-single / same-file-grep streaks,
+    // and the level-2 latch. Threaded via live getters so it reads the loop's
+    // current `iterations` / `_editCount` on every call (no stale snapshots).
+    const _steeringLadder = createSteeringLadder({
+        sessionId,
+        sessionAgent,
+        tools,
+        getIterations: () => iterations,
+        softCapEnabled: _softCapEnabled,
+        getEditCount: () => _editCount,
+        readOnlyRole: String(sessionRef?.permission || sessionRef?.toolPermission || '') === 'read',
+        pushUserMessage: (msg) => messages.push(msg),
+        pushSystemReminder: (text) => messages.push({ role: 'user', content: `<system-reminder>\n${text}\n</system-reminder>`, meta: 'hook' }),
+    });
     // Tool execution must use the session cwd even when the caller omitted the
     // legacy positional cwd argument. Agent 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;
+    // Staged pre-cap warnings + one true hard stop. The ONLY count-based
+    // forced termination is the hard cap at maxLoopIterations (default 200):
+    // a genuine runaway guard. Before it, staged warnings fire at 50%/75%/90%
+    // of the cap steering the model to converge — warnings only, nothing is
+    // cut off early. All other runaway protection is behavior-based (steering
+    // ladder early wrap-up, REPEAT_FAIL_LIMIT), never a lower count.
+    let _iterWarnStage = 0;
+    const _iterWarnAt = [
+        Math.floor(maxLoopIterations * 0.5),
+        Math.floor(maxLoopIterations * 0.75),
+        Math.floor(maxLoopIterations * 0.9),
+    ];
     while (true) {
         throwIfAborted();
         if (iterations >= maxLoopIterations) {
@@ -1415,6 +284,43 @@ export async function agentLoop(provider, messages, model, tools, onToolCall, cw
             terminatedByCap = true;
             break;
         }
+        if (_iterWarnStage < _iterWarnAt.length && iterations >= _iterWarnAt[_iterWarnStage]) {
+            _iterWarnStage += 1;
+            const warnAt = _iterWarnAt[_iterWarnStage - 1];
+            const stageMsg = _iterWarnStage === 1
+                ? `Iteration budget notice: ${warnAt} of ${maxLoopIterations} iterations used. Converge on a conclusion: prefer finishing the current objective over opening new exploration.`
+                : `Iteration budget warning (stage ${_iterWarnStage}): ${warnAt} of ${maxLoopIterations} iterations used — the loop hard-stops at ${maxLoopIterations}. Wrap up now: summarize progress, state what remains, and finish with your best current result.`;
+            messages.push({ role: 'user', content: `<system-reminder>\n${stageMsg}\n</system-reminder>`, meta: 'hook' });
+            process.stderr.write(`[loop] iteration warning stage ${_iterWarnStage} at ${iterations} (sess=${sessionId || 'unknown'}); continuing with steer.\n`);
+            try {
+                appendAgentTrace({
+                    sessionId,
+                    iteration: iterations,
+                    kind: 'steer',
+                    payload: { tag: 'iteration_warning', stage: _iterWarnStage, at: iterations, unit: maxLoopIterations },
+                    agent: sessionAgent || null,
+                });
+            } catch { /* best-effort */ }
+        }
+        // Worker soft cap (Step 3): non-lead sessions that reach the soft-cap
+        // iteration count switch to a text-only wrap-up. On the FIRST crossing
+        // we disable tool defs (below, via _softCapActive) and inject the
+        // assistant-visible wrap-up directive as a user message so the next
+        // send produces a final text summary. Lead/TUI sessions never enter.
+        const _earlySoftCap = _steeringLadder.earlySoftCapArmed();
+        if (_softCapEnabled && !_softCapActive && (iterations >= WORKER_SOFT_CAP_ITERATIONS || _earlySoftCap)) {
+            _softCapActive = true;
+            messages.push({ role: 'user', content: `<system-reminder>\n${SOFT_CAP_WRAPUP_MESSAGE}\n</system-reminder>`, meta: 'hook' });
+            try {
+                appendAgentTrace({
+                    sessionId,
+                    iteration: iterations,
+                    kind: 'steer',
+                    payload: { tag: 'soft_cap_wrapup', soft_cap: WORKER_SOFT_CAP_ITERATIONS, early: _earlySoftCap, level2_fires: _steeringLadder.level2FireCount },
+                    agent: sessionAgent || null,
+                });
+            } catch { /* best-effort */ }
+        }
         // Drain queued steering/prompts BEFORE the
         // pre-send compact check. The compact decision must see the exact
         // message set that the next provider.send would receive, including
@@ -1446,6 +352,13 @@ export async function agentLoop(provider, messages, model, tools, onToolCall, cw
             const reactivePending = reactiveOverflowRetryPending === true;
             const shouldCompact = shouldCompactForSession(messageTokensEst, compactPolicy, { forceReactive: reactivePending });
             const pressureTokens = compactionTelemetryPressureTokens(messageTokensEst, compactPolicy, { reactivePending });
+            // A pending reactive-overflow retry makes THIS compact pass the
+            // recovery from a provider overflow refusal, not the proactive
+            // pressure trigger. Tag the emitted events so telemetry can tell
+            // them apart. Hoisted above the shouldCompact branch because the
+            // PostCompact hook below fires on BOTH paths (fixes a
+            // ReferenceError on the no-compact path).
+            const compactTrigger = reactivePending ? 'reactive' : 'auto';
             const compactBudgetTokens = shouldCompact
                 ? (compactTargetBudget({ ...compactPolicy, pressureTokens }) || compactPolicy.boundaryTokens)
                 : compactPolicy.boundaryTokens;
@@ -1459,12 +372,22 @@ export async function agentLoop(provider, messages, model, tools, onToolCall, cw
             } else {
                 try { opts.onStageChange?.('compacting'); } catch { /* best-effort */ }
                 const compactStartedAt = Date.now();
-                // A pending reactive-overflow retry makes THIS compact pass the
-                // recovery from a provider overflow refusal, not the proactive
-                // pressure trigger. Tag the emitted events so telemetry can tell
-                // them apart, then clear the one-shot flag.
-                const compactTrigger = reactiveOverflowRetryPending ? 'reactive' : 'auto';
+                // Clear the one-shot reactive-overflow flag now that this
+                // compact pass is consuming it (compactTrigger already
+                // captured it above).
                 reactiveOverflowRetryPending = false;
+                // PreCompact: bridge to the standard hook bus before compaction
+                // runs. session-property hook (manager/loop have no bus access).
+                // { trigger } normalized to 'auto'|'manual'. Best-effort.
+                {
+                    const _preCompactHook = typeof opts.preCompactHook === 'function'
+                        ? opts.preCompactHook
+                        : sessionRef?.preCompactHook;
+                    if (typeof _preCompactHook === 'function') {
+                        try { await _preCompactHook({ sessionId, cwd, trigger: compactTrigger === 'manual' ? 'manual' : 'auto' }); }
+                        catch { /* best-effort: PreCompact hook must never break compaction */ }
+                    }
+                }
                 rememberCompactTelemetry(sessionRef, compactPolicy, {
                     stage: 'compacting',
                     beforeTokens: messageTokensEst,
@@ -1792,6 +715,17 @@ export async function agentLoop(provider, messages, model, tools, onToolCall, cw
                     durationMs: compactDurationMs,
                 });
             }
+            // PostCompact: bridge to the standard hook bus after compaction
+            // completes. session-property hook; { trigger } 'auto'|'manual'.
+            {
+                const _postCompactHook = typeof opts.postCompactHook === 'function'
+                    ? opts.postCompactHook
+                    : sessionRef?.postCompactHook;
+                if (typeof _postCompactHook === 'function') {
+                    try { await _postCompactHook({ sessionId, cwd, trigger: compactTrigger === 'manual' ? 'manual' : 'auto' }); }
+                    catch { /* best-effort: PostCompact hook must never break the loop */ }
+                }
+            }
         }
         const nextIteration = iterations + 1;
         opts.iteration = nextIteration;
@@ -1801,7 +735,11 @@ export async function agentLoop(provider, messages, model, tools, onToolCall, cw
         } else {
             delete opts.toolChoice;
         }
-        const sendTools = forcedFirstToolDef && toolCallsTotal === 0 ? [forcedFirstToolDef] : tools;
+        // Soft-cap wrap-up (Step 3a): once active, send NO tool definitions so
+        // the provider can only emit text. Overrides the forced-first-tool path.
+        const sendTools = _softCapActive
+            ? []
+            : (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()
@@ -1842,11 +780,22 @@ export async function agentLoop(provider, messages, model, tools, onToolCall, cw
                 const _rfg = sessionRef?._repeatFailGuard;
                 if (_rfg && _rfg.sig === _sig && _rfg.count >= REPEAT_FAIL_LIMIT) return null;
             }
+            // Cross-turn dedup also gates eager dispatch (mirror of the
+            // repeat-failure guard above): a read-only call whose (name,args)
+            // signature already ran in an EARLIER turn must NOT be eagerly
+            // re-executed — the serial for-body pushes the [cross-turn-dedup]
+            // stub instead. Without this gate startEagerRun/onToolCall would
+            // re-run the call before the serial dedup check ever sees it.
+            {
+                const _ctSig = crossTurnSignature(call.name, call.arguments);
+                const _prior = _crossTurnCalls.get(_ctSig);
+                if (_prior && _prior.firstIteration < iterations) 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;
+            if (preDispatchDenyForSession(sessionRef, call, toolKind) !== null) return null;
             const entry = { startedAt: Date.now(), endedAt: null, mutationEpoch: _mutationEpoch };
             _eagerInFlightSigs.set(_sig, call.id);
             entry.promise = (async () => {
@@ -2082,13 +1031,18 @@ export async function agentLoop(provider, messages, model, tools, onToolCall, cw
         // the stateless contract for providers that don't use continuation).
         providerState = response?.providerState ?? undefined;
         iterations = nextIteration;
-        traceAgentLoop({
-            sessionId,
-            iteration: iterations,
-            sendMs: Date.now() - sendStartedAt,
-            messageCount: Array.isArray(messages) ? messages.length : 0,
-            bodyBytesEst: estimateProviderPayloadBytes(messages, model, sendTools),
-        });
+        // Payload byte estimate serializes the FULL messages+tools array —
+        // only pay that cost when verbose loop tracing is actually enabled
+        // (traceAgentLoop is a no-op otherwise).
+        if (process.env.MIXDOG_AGENT_TRACE_VERBOSE === '1') {
+            traceAgentLoop({
+                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),
@@ -2178,6 +1132,11 @@ export async function agentLoop(provider, messages, model, tools, onToolCall, cw
         // tool-call-blocked vs contract-required oscillation.
         if (!response.toolCalls?.length) {
             // No tool calls. Decide between final-answer accept vs nudge.
+            // Reviewer fix: a zero-tool turn (final-pre-send steering drain or
+            // contract nudge `continue`) must not bridge the all-read-only
+            // streak across non-tool turns — that would fire level-2 early on
+            // a worker that paused to synthesize text mid-run.
+            _steeringLadder.resetAllReadOnlyStreak();
             //   - has content + non-hidden role → valid final, break.
             //   - empty content + hidden role → contract allows text-only
             //     terminal turn, break.
@@ -2251,6 +1210,37 @@ export async function agentLoop(provider, messages, model, tools, onToolCall, cw
                 : {}),
         };
         messages.push(_assistantTurnMsg);
+        // Soft-cap wrap-up (Step 3b): tools are disabled but the model still
+        // emitted tool calls. Do NOT execute them — push a refusal stub for
+        // each (after the assistant turn is appended so tool_use/tool_result
+        // pairing stays valid) and consume a grace turn. After 2 grace turns,
+        // terminate via the soft-cap path so a model that never complies stops.
+        if (_softCapActive) {
+            for (const _c of calls) {
+                pushToolResultMessage({
+                    role: 'tool',
+                    content: SOFT_CAP_REFUSAL_STUB,
+                    toolCallId: _c.id,
+                    toolKind: 'error',
+                });
+            }
+            _softCapGraceTurns += 1;
+            try {
+                appendAgentTrace({
+                    sessionId,
+                    iteration: iterations,
+                    kind: 'steer',
+                    payload: { tag: 'soft_cap_wrapup', grace_turn: _softCapGraceTurns },
+                    agent: sessionAgent || null,
+                });
+            } catch { /* best-effort */ }
+            if (_softCapGraceTurns >= 2) {
+                _terminatedBySoftCap = true;
+                break;
+            }
+            if (sessionId) updateSessionStage(sessionId, 'connecting');
+            continue;
+        }
         // Execute each tool and append results.
         //
         // Intra-turn duplicate suppression: when an LLM emits two tool_use
@@ -2305,6 +1295,42 @@ export async function agentLoop(provider, messages, model, tools, onToolCall, cw
                 });
                 continue;
             }
+            // Cross-turn identical-call stub (Step 2): a SUCCESSFUL read-only
+            // (isEagerDispatchable) call whose (name,args) signature already ran
+            // in an EARLIER turn is not re-executed — its result is unchanged and
+            // already in context. Warn at the 2nd occurrence; append the "stuck"
+            // escalation tail once the session has emitted 5+ dedup stubs total.
+            // Never applies to write/bash/MCP/skill tools (not eager-dispatchable).
+            if (isEagerDispatchable(call.name, tools)) {
+                const _ctSig = crossTurnSignature(call.name, call.arguments);
+                const _prior = _crossTurnCalls.get(_ctSig);
+                if (_prior && _prior.firstIteration < iterations) {
+                    _prior.count += 1;
+                    _dedupStubTotal += 1;
+                    const _stub = crossTurnDedupStub(call.name, _prior.firstIteration, _dedupStubTotal >= 5);
+                    pushToolResultMessage({
+                        role: 'tool',
+                        content: _stub,
+                        toolCallId: call.id,
+                    });
+                    try {
+                        appendAgentTrace({
+                            sessionId,
+                            iteration: iterations,
+                            kind: 'steer',
+                            payload: {
+                                tag: 'cross_turn_dedup',
+                                tool: call.name,
+                                occurrence: _prior.count,
+                                first_iteration: _prior.firstIteration,
+                                dedup_stub_total: _dedupStubTotal,
+                            },
+                            agent: sessionAgent || null,
+                        });
+                    } catch { /* best-effort */ }
+                    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
@@ -2330,8 +1356,7 @@ export async function agentLoop(provider, messages, model, tools, onToolCall, cw
             let toolStartedAt;
             let toolEndedAt;
             const toolKind = getToolKind(call.name);
-            // Cross-turn read dedup. Mirrors a reference agent's
-            // fileReadCache.ts: if the path's stat tuple (mtime/size/ino/dev)
+            // Cross-turn read dedup: 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.
@@ -2415,12 +1440,12 @@ export async function agentLoop(provider, messages, model, tools, onToolCall, cw
                     // Runtime pre-dispatch deny. Schema profiles may hide
                     // tools for routing efficiency, but this remains the
                     // control-plane boundary for any tool_use that still
-                    // reaches the loop. _preDispatchDeny is the SHARED helper
+                    // reaches the loop. preDispatchDenyForSession is the SHARED helper
                     // used by both the eager dispatch path (startEagerTool)
                     // and this serial path — keeps the agent-owned control-
                     // plane reject and no-tool role guards consistent across
                     // both paths.
-                    const _denyMsg = _preDispatchDeny(call, toolKind, sessionRef);
+                    const _denyMsg = preDispatchDenyForSession(sessionRef, call, toolKind);
                     if (_denyMsg !== null) {
                         result = _denyMsg;
                         toolEndedAt = Date.now();
@@ -2460,6 +1485,36 @@ export async function agentLoop(provider, messages, model, tools, onToolCall, cw
                 result = _env.result;
                 if (_env.newMessages.length) _batchNewMessages.push(..._env.newMessages);
             }
+            // Bounded-map cleanup: a scoped-cache outcome recorded for this call.id
+            // (via _scopedCacheOutcomeForCall) is only ever consumed/deleted on the
+            // success path below (_executeOk && _resultKind==='normal'). A failed or
+            // errored call would otherwise leak its entry in
+            // sessionRef._scopedCacheOutcomeByCallId forever — reclaim it here.
+            if (sessionRef?._scopedCacheOutcomeByCallId instanceof Map && call?.id && (!_executeOk || _resultKind === 'error')) {
+                sessionRef._scopedCacheOutcomeByCallId.delete(call.id);
+            }
+            // PostToolUseFailure: a tool that resolved to a failure (thrown-error
+            // path -> `Error:` string, or an is_error result classified as
+            // 'error') fires the optional session failure hook. Same shape as
+            // afterToolHook; `result` carries the error text. Best-effort — a
+            // hook error must never wedge the tool loop.
+            if (!_executeOk || _resultKind === 'error') {
+                const _afterToolFailureHook = typeof opts.afterToolFailureHook === 'function'
+                    ? opts.afterToolFailureHook
+                    : sessionRef?.afterToolFailureHook;
+                if (typeof _afterToolFailureHook === 'function') {
+                    try {
+                        await _afterToolFailureHook({
+                            name: call.name,
+                            args: call.arguments,
+                            cwd,
+                            sessionId,
+                            toolCallId: call.id,
+                            result: typeof result === 'string' ? result : String(result ?? ''),
+                        });
+                    } catch { /* best-effort: PostToolUseFailure hook must never break the loop */ }
+                }
+            }
             // 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.
@@ -2626,7 +1681,9 @@ export async function agentLoop(provider, messages, model, tools, onToolCall, cw
                 // 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);
+                        const _outcomeMap = sessionRef?._scopedCacheOutcomeByCallId instanceof Map
+                            ? sessionRef._scopedCacheOutcomeByCallId : null;
+                        const _outcome = _outcomeMap?.get(call.id);
                         setScopedToolCached({
                             sessionId,
                             toolName: _toolBare,
@@ -2636,7 +1693,7 @@ export async function agentLoop(provider, messages, model, tools, onToolCall, cw
                             toolUseId: call.id,
                             complete: _outcome ? _outcome.complete : true,
                         });
-                        sessionRef?._scopedCacheOutcomeByCallId?.delete(call.id);
+                        _outcomeMap?.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.
@@ -2660,8 +1717,43 @@ export async function agentLoop(provider, messages, model, tools, onToolCall, cw
                     ...(_nativeToolSearch ? { nativeToolSearch: _nativeToolSearch } : {}),
                     ...(_applyPatchUiDiff ? { uiDiff: _applyPatchUiDiff } : {}),
                 });
+                // Completion-first bookkeeping (Steps 1 & 2). Only successful
+                // executions count. Edit/progress = any executed tool whose def
+                // lacks readOnlyHint (apply_patch/bash/MCP-write/skill/...).
+                // Read-only successful calls seed the cross-turn dedup map.
+                if (_executeOk) {
+                    const _isEager = isEagerDispatchable(call.name, tools);
+                    if (_isEager) {
+                        const _ctSig = crossTurnSignature(call.name, call.arguments);
+                        if (!_crossTurnCalls.has(_ctSig)) {
+                            _crossTurnCalls.set(_ctSig, { count: 1, firstIteration: iterations });
+                            if (_crossTurnCalls.size > _CROSS_TURN_CAP) {
+                                const _oldest = _crossTurnCalls.keys().next().value;
+                                _crossTurnCalls.delete(_oldest);
+                            }
+                        }
+                    } else {
+                        // A successful mutating (non-eager) tool invalidates the
+                        // cross-turn dedup map wholesale: any prior read/grep may
+                        // now return different content, so a post-edit
+                        // verification read must NOT be stubbed as "unchanged".
+                        if (isEditProgressTool(call.name, false)) {
+                            _crossTurnCalls.clear();
+                            _editCount += 1;
+                        }
+                    }
+                }
             } catch (postErr) {
                 _postProcessOk = false;
+                // Reviewer fix: the exec itself succeeded — if it was a
+                // mutating edit-progress tool, the file changes are real even
+                // though post-processing failed, so the cross-turn dedup map
+                // must still be invalidated (otherwise a later verification
+                // read could be stubbed as "unchanged" against stale sigs).
+                if (_executeOk && !isEagerDispatchable(call.name, tools) && isEditProgressTool(call.name, false)) {
+                    _crossTurnCalls.clear();
+                    _editCount += 1;
+                }
                 // 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).
@@ -2710,6 +1802,37 @@ export async function agentLoop(provider, messages, model, tools, onToolCall, cw
             if (!_nm || _nm.role !== 'user' || typeof _nm.content !== 'string' || !_nm.content) continue;
             messages.push({ role: 'user', content: _nm.content, ...(_nm.meta ? { meta: _nm.meta } : {}) });
         }
+        // PostToolBatch: the full parallel batch of tool calls for this
+        // assistant turn has resolved and all tool_results are pushed. Fire the
+        // optional session hook before the next model call. No matcher event.
+        // Block support: if the hook returns blocked===true, inject its reason
+        // as a system-note user message for the next send (natural mechanism —
+        // same channel the newMessages flush just used). Best-effort otherwise.
+        {
+            const _afterToolBatchHook = typeof opts.afterToolBatchHook === 'function'
+                ? opts.afterToolBatchHook
+                : sessionRef?.afterToolBatchHook;
+            if (typeof _afterToolBatchHook === 'function' && calls.length > 0) {
+                try {
+                    const _batchDecision = await _afterToolBatchHook({
+                        sessionId,
+                        cwd,
+                        toolCount: calls.length,
+                    });
+                    if (_batchDecision?.blocked === true) {
+                        const _reason = String(_batchDecision.reason || 'PostToolBatch hook blocked continuation').trim();
+                        if (_reason) {
+                            messages.push({ role: 'user', content: `<system-reminder>\n${_reason}\n</system-reminder>`, meta: 'hook' });
+                        }
+                    }
+                } catch { /* best-effort: PostToolBatch hook must never break the loop */ }
+            }
+        }
+        // Completion-first steering hints (missed-parallelism / all-read-only /
+        // serial-rewording). At most ONE hint per turn (priority: soft-cap >
+        // level-2 > same-file grep > level-1); soft-cap active suppresses all.
+        // The ladder controller owns the cumulative counters and streaks.
+        _steeringLadder.emitPostBatchSteering(calls, _softCapActive);
         // Mid-turn steering is drained at the next loop's pre-send point,
         // AFTER any auto-compact pass. Draining here would put the steering
         // user turn after the fresh tool results before compaction runs; then
@@ -2720,31 +1843,13 @@ export async function agentLoop(provider, messages, model, tools, onToolCall, cw
     }
     // Classify WHY the loop ended so agent-tool can promote an empty/abnormal
     // finish to an explicit Lead-facing error instead of a silent empty
-    // "completed". Determine "has content" exactly the way the no-tool-call
-    // branch above does (trimmed string content, or any reasoning content).
-    const _finalHasContent = (typeof response?.content === 'string' && response.content.trim().length > 0)
-        || (typeof response?.reasoningContent === 'string' && response.reasoningContent.trim().length > 0);
-    const _finalStopReason = response?.stopReason ?? response?.stop_reason ?? null;
-    const _finalIncompleteStop = _finalStopReason && INCOMPLETE_STOP_REASONS.has(_finalStopReason);
-    const _finalIsHidden = HIDDEN_AGENT_NAMES.has(sessionAgent);
-    let terminationReason;
-    if (terminatedByCap) {
-        // Real problem regardless of hidden/public: the loop never terminated
-        // on its own contract.
-        terminationReason = 'iteration_cap';
-    } else if (!_finalHasContent && _finalIncompleteStop) {
-        // Cut short mid-synthesis (token cap / provider pause). Real problem
-        // for hidden agents too.
-        terminationReason = 'truncated';
-    } else if (!_finalHasContent && !_finalIsHidden) {
-        // Empty terminal turn. Only public agents violate their contract by
-        // finishing empty — hidden agents (explorer/cycle/…) legitimately emit
-        // text-only/empty terminal turns per their own role contract, so leave
-        // terminationReason undefined for them.
-        terminationReason = 'empty';
-    } else {
-        terminationReason = undefined;
-    }
+    // "completed" (see classifyTerminationReason in ./loop/termination.mjs).
+    const terminationReason = classifyTerminationReason(response, {
+        terminatedByCap,
+        terminatedBySoftCap: _terminatedBySoftCap,
+        softCapActive: _softCapActive,
+        sessionAgent,
+    });
     return {
         ...response,
         usage: lastUsage || response.usage,