@visorcraft/idlehands 1.1.17 → 1.2.1

package/dist/agent.js

@@ -17,6 +17,7 @@ import { LspManager, detectInstalledLspServers } from './lsp.js';
 import { generateMinimalDiff, toolResultSummary, execCommandFromSig, formatDurationMs, looksLikePlanningNarration, capTextByApproxTokens, isLikelyBinaryBuffer, sanitizePathsInMessage, digestToolResult, } from './agent/formatting.js';
 import { parseToolCallsFromContent, getMissingRequiredParams, getArgValidationIssues, stripMarkdownFences } from './agent/tool-calls.js';
 import { ToolError, ValidationError } from './tools/tool-error.js';
+import { ToolLoopGuard } from './agent/tool-loop-guard.js';
 export { parseToolCallsFromContent };
 import { reviewArtifactKeys, looksLikeCodeReviewRequest, looksLikeReviewRetrievalRequest, retrievalAllowsStaleArtifact, parseReviewArtifactStalePolicy, parseReviewArtifact, reviewArtifactStaleReason, gitHead, normalizeModelsResponse, } from './agent/review-artifact.js';
 import fs from 'node:fs/promises';
@@ -27,9 +28,13 @@ function makeAbortController() {
     return new AbortController();
 }
 const CACHED_EXEC_OBSERVATION_HINT = '[idlehands hint] Reused cached output for repeated read-only exec call (unchanged observation).';
-const CACHED_READ_OBSERVATION_HINT = '[idlehands hint] Reused cached output for repeated identical read call.';
 function looksLikeReadOnlyExecCommand(command) {
-    const cmd = String(command || '').trim().toLowerCase();
+    // Strip leading `cd <path> &&` / `cd <path>;` prefixes — cd is read-only
+    // navigation, the actual command that matters comes after.
+    let cmd = String(command || '').trim().toLowerCase();
+    if (!cmd)
+        return false;
+    cmd = cmd.replace(/^(\s*cd\s+[^;&|]+\s*(?:&&|;)\s*)+/i, '').trim();
     if (!cmd)
         return false;
     // Shell redirects are likely writes.
@@ -99,6 +104,25 @@ function withCachedExecObservationHint(content) {
         return `${content}\n${CACHED_EXEC_OBSERVATION_HINT}`;
     }
 }
+const REPLAYED_EXEC_HINT = '[idlehands hint] You already ran this exact command. This is the replayed result from your previous execution. Do NOT re-run it — use the output below to continue your task.';
+function withReplayedExecHint(content) {
+    if (!content)
+        return content;
+    try {
+        const parsed = JSON.parse(content);
+        const out = typeof parsed?.out === 'string' ? parsed.out : '';
+        if (out.includes(REPLAYED_EXEC_HINT))
+            return content;
+        parsed.out = out ? `${REPLAYED_EXEC_HINT}\n${out}` : REPLAYED_EXEC_HINT;
+        parsed.replayed = true;
+        return JSON.stringify(parsed);
+    }
+    catch {
+        if (content.includes(REPLAYED_EXEC_HINT))
+            return content;
+        return `${REPLAYED_EXEC_HINT}\n${content}`;
+    }
+}
 function readOnlyExecCacheable(content) {
     try {
         const parsed = JSON.parse(content);
@@ -109,18 +133,6 @@ function readOnlyExecCacheable(content) {
         return false;
     }
 }
-function withCachedReadObservationHint(content) {
-    if (!content)
-        return CACHED_READ_OBSERVATION_HINT;
-    if (content.includes(CACHED_READ_OBSERVATION_HINT))
-        return content;
-    // Keep cached read replay lightweight to avoid re-inflating context.
-    const lines = String(content).split(/\r?\n/);
-    const previewLines = lines.slice(0, 12);
-    const omitted = Math.max(0, lines.length - previewLines.length);
-    const trailer = omitted > 0 ? `\n# ... (${omitted} more lines omitted; use previous identical read result)` : '';
-    return `${CACHED_READ_OBSERVATION_HINT}\n${previewLines.join('\n')}${trailer}`;
-}
 function ensureInformativeAssistantText(text, ctx) {
     if (String(text ?? '').trim())
         return text;
@@ -155,6 +167,9 @@ Rules:
 - Use read_file with search=... to jump to relevant code; avoid reading whole files.
 - Never call read_file/read_files/list_dir twice in a row with identical arguments (same path/options). Reuse the previous result instead.
 - Prefer apply_patch or edit_range for code edits (token-efficient). Use edit_file only when exact old_text replacement is necessary.
+- Tool-call arguments MUST be strict JSON (double-quoted keys/strings, no comments, no trailing commas).
+- edit_range example: {"path":"src/foo.ts","start_line":10,"end_line":14,"replacement":"line A\nline B"}
+- apply_patch example: {"patch":"--- a/src/foo.ts\n+++ b/src/foo.ts\n@@ -10,2 +10,2 @@\n-old\n+new","files":["src/foo.ts"]}
 - write_file is for new files or explicit full rewrites only. Existing non-empty files require overwrite=true/force=true.
 - Use insert_file for insertions (prepend/append/line).
 - Use exec to run commands, tests, builds; check results before reporting success.
@@ -336,7 +351,7 @@ function buildToolsSchema(opts) {
             type: 'function',
             function: {
                 name: 'apply_patch',
-                description: 'Apply unified diff patch (multi-file).',
+                description: 'Apply unified diff patch (multi-file).\n\nUSAGE EXAMPLE:\n  apply_patch({\n    patch: "--- a/src/file.ts\\n+++ b/src/file.ts\\n@@ -1,5 +1,5 @@\\n-old text\\n+new text\\n",\n    files: ["src/file.ts"]\n  })\n\nThe patch must be valid unified diff text. Tool-call arguments must be valid JSON. Use strip=1 if paths include directory prefixes.\nFiles listed must match the paths in the diff.',
                 parameters: obj({
                     patch: str(),
                     files: { type: 'array', items: str() },
@@ -348,7 +363,7 @@ function buildToolsSchema(opts) {
             type: 'function',
             function: {
                 name: 'edit_range',
-                description: 'Replace a line range in a file.',
+                description: 'Replace a line range in a file.\n\nUSAGE EXAMPLE:\n  edit_range({\n    path: "src/file.ts",\n    start_line: 10,\n    end_line: 15,\n    replacement: "new content\\nmore content"\n  })\n\n- start_line and end_line are 1-indexed (first line is 1, not 0)\n- To delete lines, set replacement to empty string ""\n- To insert at a position, set start_line and end_line to the same value\n- Tool-call arguments must be valid JSON (double quotes, no trailing commas/comments)\n- The replacement text replaces the entire range inclusive',
                 parameters: obj({
                     path: str(),
                     start_line: int(1),
@@ -427,6 +442,11 @@ function buildToolsSchema(opts) {
     if (opts?.activeVaultTools) {
         schemas.push({ type: 'function', function: { name: 'vault_search', description: 'Search vault.', parameters: obj({ query: str(), limit: int() }, ['query']) } }, { type: 'function', function: { name: 'vault_note', description: 'Write vault note.', parameters: obj({ key: str(), value: str() }, ['key', 'value']) } });
     }
+    else if (opts?.passiveVault) {
+        // In passive mode, expose vault_search (read-only) so the model can recover
+        // compacted context on demand, but don't expose vault_note (write).
+        schemas.push({ type: 'function', function: { name: 'vault_search', description: 'Search vault memory for earlier context that was compacted away. Use sparingly — only when you need to recall specific details from earlier in the conversation.', parameters: obj({ query: str(), limit: int() }, ['query']) } });
+    }
     // Phase 9: sys_context tool is only available in sys mode.
     if (opts?.sysMode) {
         schemas.push(SYS_CONTEXT_SCHEMA);
@@ -671,6 +691,7 @@ export async function createSession(opts) {
     let mcpToolsLoaded = !mcpLazySchemaMode;
     const getToolsSchema = () => buildToolsSchema({
         activeVaultTools,
+        passiveVault: !activeVaultTools && vaultEnabled && vaultMode === 'passive',
         sysMode: cfg.mode === 'sys',
         lspTools: lspManager?.hasServers() === true,
         mcpTools: mcpToolsLoaded ? (mcpManager?.getEnabledToolSchemas() ?? []) : [],
@@ -1203,7 +1224,7 @@ export async function createSession(opts) {
             return 'Vault memory is available. Retrieve prior context with vault_search(query="...") when needed.';
         }
         if (vaultMode === 'passive') {
-            return 'Vault memory is in passive mode; relevant entries may be auto-injected when available.';
+            return 'Vault memory is in passive mode; relevant entries may be auto-injected. You can also use vault_search(query="...") to recover specific earlier context if needed.';
         }
         return '';
     };
@@ -1260,80 +1281,150 @@ export async function createSession(opts) {
             content: `${vaultContextHeader} Relevant entries for "${query}":\n${lines.join('\n')}`
         });
     };
-    const compactHistory = async (opts) => {
-        const beforeMessages = messages.length;
-        const beforeTokens = estimateTokensFromMessages(messages);
-        let compacted;
-        if (opts?.hard) {
-            const sys = messages[0]?.role === 'system' ? [messages[0]] : [];
-            const tail = messages.slice(-2);
-            compacted = [...sys, ...tail];
+    let compactionLockTail = Promise.resolve();
+    let compactionStats = {
+        inProgress: false,
+        lockHeld: false,
+        runs: 0,
+        failedRuns: 0,
+        beforeMessages: 0,
+        afterMessages: 0,
+        freedTokens: 0,
+        archivedToolMessages: 0,
+        droppedMessages: 0,
+        dryRun: false,
+    };
+    const runCompactionWithLock = async (reason, runner) => {
+        const prev = compactionLockTail;
+        let release = () => { };
+        compactionLockTail = new Promise((resolve) => {
+            release = () => resolve();
+        });
+        await prev;
+        compactionStats = {
+            ...compactionStats,
+            inProgress: true,
+            lockHeld: true,
+            lastReason: reason,
+            lastError: undefined,
+            updatedAt: new Date().toISOString(),
+            // Reset run stats before fresh calculation.
+            beforeMessages: 0,
+            afterMessages: 0,
+            freedTokens: 0,
+            archivedToolMessages: 0,
+            droppedMessages: 0,
+            dryRun: false,
+        };
+        try {
+            const result = await runner();
+            compactionStats = {
+                ...compactionStats,
+                ...result,
+                inProgress: false,
+                lockHeld: false,
+                runs: compactionStats.runs + 1,
+                lastReason: reason,
+                updatedAt: new Date().toISOString(),
+            };
+            return result;
         }
-        else {
-            compacted = enforceContextBudget({
-                messages,
-                contextWindow,
-                maxTokens,
-                minTailMessages: opts?.force ? 2 : 12,
-                compactAt: opts?.force ? 0.5 : (cfg.compact_at ?? 0.8),
-                toolSchemaTokens: estimateToolSchemaTokens(getToolsSchema()),
-                force: opts?.force,
-            });
+        catch (e) {
+            compactionStats = {
+                ...compactionStats,
+                inProgress: false,
+                lockHeld: false,
+                failedRuns: compactionStats.failedRuns + 1,
+                lastReason: reason,
+                lastError: e?.message ?? String(e),
+                updatedAt: new Date().toISOString(),
+            };
+            throw e;
         }
-        const compactedByRefs = new Set(compacted);
-        let dropped = messages.filter((m) => !compactedByRefs.has(m));
-        if (opts?.topic) {
-            const topic = opts.topic.toLowerCase();
-            dropped = dropped.filter((m) => !userContentToText(m.content ?? '').toLowerCase().includes(topic));
-            const keepFromTopic = messages.filter((m) => userContentToText(m.content ?? '').toLowerCase().includes(topic));
-            compacted = [...compacted, ...keepFromTopic.filter((m) => !compactedByRefs.has(m))];
+        finally {
+            release();
         }
-        const archivedToolMessages = dropped.filter((m) => m.role === 'tool').length;
-        const afterMessages = compacted.length;
-        const afterTokens = estimateTokensFromMessages(compacted);
-        const freedTokens = Math.max(0, beforeTokens - afterTokens);
-        if (!opts?.dry) {
-            if (dropped.length && vault) {
-                try {
-                    // Store the original/current user prompt before compaction so it survives context loss.
-                    let userPromptToPreserve = null;
-                    for (let i = messages.length - 1; i >= 0; i--) {
-                        const m = messages[i];
-                        if (m.role === 'user') {
-                            const text = userContentToText((m.content ?? '')).trim();
-                            if (text && !text.startsWith('[Trifecta Vault') && !text.startsWith('[Vault context') && text.length > 20) {
-                                userPromptToPreserve = text;
-                                break;
+    };
+    const compactHistory = async (opts) => {
+        const reason = opts?.reason
+            ?? (opts?.hard ? 'manual hard compaction'
+                : opts?.force ? 'manual force compaction'
+                    : 'manual compaction');
+        return await runCompactionWithLock(reason, async () => {
+            const beforeMessages = messages.length;
+            const beforeTokens = estimateTokensFromMessages(messages);
+            let compacted;
+            if (opts?.hard) {
+                const sys = messages[0]?.role === 'system' ? [messages[0]] : [];
+                const tail = messages.slice(-2);
+                compacted = [...sys, ...tail];
+            }
+            else {
+                compacted = enforceContextBudget({
+                    messages,
+                    contextWindow,
+                    maxTokens,
+                    minTailMessages: opts?.force ? 2 : 12,
+                    compactAt: opts?.force ? 0.5 : (cfg.compact_at ?? 0.8),
+                    toolSchemaTokens: estimateToolSchemaTokens(getToolsSchema()),
+                    force: opts?.force,
+                });
+            }
+            const compactedByRefs = new Set(compacted);
+            let dropped = messages.filter((m) => !compactedByRefs.has(m));
+            if (opts?.topic) {
+                const topic = opts.topic.toLowerCase();
+                dropped = dropped.filter((m) => !userContentToText(m.content ?? '').toLowerCase().includes(topic));
+                const keepFromTopic = messages.filter((m) => userContentToText(m.content ?? '').toLowerCase().includes(topic));
+                compacted = [...compacted, ...keepFromTopic.filter((m) => !compactedByRefs.has(m))];
+            }
+            const archivedToolMessages = dropped.filter((m) => m.role === 'tool').length;
+            const afterMessages = compacted.length;
+            const afterTokens = estimateTokensFromMessages(compacted);
+            const freedTokens = Math.max(0, beforeTokens - afterTokens);
+            if (!opts?.dry) {
+                if (dropped.length && vault) {
+                    try {
+                        // Store the original/current user prompt before compaction so it survives context loss.
+                        let userPromptToPreserve = null;
+                        for (let i = messages.length - 1; i >= 0; i--) {
+                            const m = messages[i];
+                            if (m.role === 'user') {
+                                const text = userContentToText((m.content ?? '')).trim();
+                                if (text && !text.startsWith('[Trifecta Vault') && !text.startsWith('[Vault context') && text.length > 20) {
+                                    userPromptToPreserve = text;
+                                    break;
+                                }
                             }
                         }
+                        if (userPromptToPreserve) {
+                            await vault.upsertNote('current_task', userPromptToPreserve.slice(0, 2000), 'system');
+                        }
+                        await vault.archiveToolMessages(dropped, new Map());
+                        await vault.note('compaction_summary', `Dropped ${dropped.length} messages (${freedTokens} tokens).`);
                     }
-                    if (userPromptToPreserve) {
-                        await vault.upsertNote('current_task', userPromptToPreserve.slice(0, 2000), 'system');
+                    catch {
+                        // best-effort
                     }
-                    await vault.archiveToolMessages(dropped, new Map());
-                    await vault.note('compaction_summary', `Dropped ${dropped.length} messages (${freedTokens} tokens).`);
                 }
-                catch {
-                    // best-effort
-                }
-            }
-            messages = compacted;
-            if (dropped.length) {
-                messages.push({ role: 'system', content: buildCompactionSystemNote('manual', dropped.length) });
-                await injectVaultContext().catch(() => { });
-                if (opts?.reason || opts?.force) {
-                    injectCompactionReminder(opts?.reason ?? 'history compaction');
+                messages = compacted;
+                if (dropped.length) {
+                    messages.push({ role: 'system', content: buildCompactionSystemNote('manual', dropped.length) });
+                    await injectVaultContext().catch(() => { });
+                    if (opts?.reason || opts?.force) {
+                        injectCompactionReminder(opts?.reason ?? 'history compaction');
+                    }
                 }
             }
-        }
-        return {
-            beforeMessages,
-            afterMessages,
-            freedTokens,
-            archivedToolMessages,
-            droppedMessages: dropped.length,
-            dryRun: !!opts?.dry,
-        };
+            return {
+                beforeMessages,
+                afterMessages,
+                freedTokens,
+                archivedToolMessages,
+                droppedMessages: dropped.length,
+                dryRun: !!opts?.dry,
+            };
+        });
     };
     const cumulativeUsage = { prompt: 0, completion: 0 };
     const turnDurationsMs = [];
@@ -1342,6 +1433,17 @@ export async function createSession(opts) {
     const tgSamples = [];
     let lastTurnMetrics;
     let lastServerHealth;
+    let lastToolLoopStats = { totalHistory: 0, signatures: [], outcomes: [], telemetry: {
+            callsRegistered: 0,
+            dedupedReplays: 0,
+            readCacheLookups: 0,
+            readCacheHits: 0,
+            warnings: 0,
+            criticals: 0,
+            recoveryRecommended: 0,
+            readCacheHitRate: 0,
+            dedupeRate: 0,
+        } };
     let lastModelsProbeMs = 0;
     const capturesDir = path.join(stateDir(), 'captures');
     let captureEnabled = false;
@@ -1690,6 +1792,10 @@ export async function createSession(opts) {
             await hookObj.onToolResult?.(result);
             await hookManager.emit('tool_result', { askId, turn: turns, result });
         };
+        const emitToolLoop = async (loop) => {
+            await hookObj.onToolLoop?.(loop);
+            await hookManager.emit('tool_loop', { askId, turn: turns, loop });
+        };
         const emitTurnEnd = async (stats) => {
             await hookObj.onTurnEnd?.(stats);
             await hookManager.emit('turn_end', { askId, stats });
@@ -1825,9 +1931,41 @@ export async function createSession(opts) {
         const blockedExecAttemptsBySig = new Map();
         // Cache successful read-only exec observations by exact signature.
         const execObservationCacheBySig = new Map();
-        // Cache successful read_file/read_files/list_dir results by exact signature.
+        // Cache ALL successful exec results so repeated identical calls under context
+        // pressure can replay the cached result instead of re-executing.
+        const lastExecResultBySig = new Map();
+        // Cache successful read_file/read_files/list_dir results by signature + mtime for invalidation.
         const readFileCacheBySig = new Map();
         const READ_FILE_CACHE_TOOLS = new Set(['read_file', 'read_files', 'list_dir']);
+        const toolLoopGuard = new ToolLoopGuard({
+            enabled: cfg.tool_loop_detection?.enabled,
+            historySize: cfg.tool_loop_detection?.history_size,
+            warningThreshold: cfg.tool_loop_detection?.warning_threshold,
+            criticalThreshold: cfg.tool_loop_detection?.critical_threshold,
+            globalCircuitBreakerThreshold: cfg.tool_loop_detection?.global_circuit_breaker_threshold,
+            readCacheTtlMs: cfg.tool_loop_detection?.read_cache_ttl_ms,
+            detectors: {
+                genericRepeat: cfg.tool_loop_detection?.detectors?.generic_repeat,
+                knownPollNoProgress: cfg.tool_loop_detection?.detectors?.known_poll_no_progress,
+                pingPong: cfg.tool_loop_detection?.detectors?.ping_pong,
+            },
+            perTool: Object.fromEntries(Object.entries(cfg.tool_loop_detection?.per_tool ?? {}).map(([tool, policy]) => [
+                tool,
+                {
+                    warningThreshold: policy?.warning_threshold,
+                    criticalThreshold: policy?.critical_threshold,
+                    globalCircuitBreakerThreshold: policy?.global_circuit_breaker_threshold,
+                    detectors: {
+                        genericRepeat: policy?.detectors?.generic_repeat,
+                        knownPollNoProgress: policy?.detectors?.known_poll_no_progress,
+                        pingPong: policy?.detectors?.ping_pong,
+                    },
+                },
+            ])),
+        });
+        const toolLoopWarningKeys = new Set();
+        let forceToollessRecoveryTurn = false;
+        let toollessRecoveryUsed = false;
         // Prevent repeating the same "stop rerunning" reminder every turn.
         const readOnlyExecHintedSigs = new Set();
         // Keep a lightweight breadcrumb for diagnostics on partial failures.
@@ -1950,51 +2088,63 @@ export async function createSession(opts) {
                     throw new Error(`session timeout exceeded (${cfg.timeout}s) after ${wallElapsed.toFixed(1)}s`);
                 }
                 await maybeAutoDetectModelChange();
-                const beforeMsgs = messages;
-                const compacted = enforceContextBudget({
-                    messages: beforeMsgs,
-                    contextWindow,
-                    maxTokens: maxTokens,
-                    minTailMessages: 12,
-                    compactAt: cfg.compact_at ?? 0.8,
-                    toolSchemaTokens: estimateToolSchemaTokens(getToolsSchema()),
-                });
-                const compactedByRefs = new Set(compacted);
-                const dropped = beforeMsgs.filter((m) => !compactedByRefs.has(m));
-                if (dropped.length && vault) {
-                    try {
-                        // Store the original/current user prompt before compaction so it survives context loss.
-                        // Find the last substantive user message that looks like a task/instruction.
-                        let userPromptToPreserve = null;
-                        for (let i = beforeMsgs.length - 1; i >= 0; i--) {
-                            const m = beforeMsgs[i];
-                            if (m.role === 'user') {
-                                const text = userContentToText((m.content ?? '')).trim();
-                                // Skip vault injection messages and short prompts
-                                if (text && !text.startsWith('[Trifecta Vault') && !text.startsWith('[Vault context') && text.length > 20) {
-                                    userPromptToPreserve = text;
-                                    break;
+                await runCompactionWithLock('auto context-budget compaction', async () => {
+                    const beforeMsgs = messages;
+                    const beforeTokens = estimateTokensFromMessages(beforeMsgs);
+                    const compacted = enforceContextBudget({
+                        messages: beforeMsgs,
+                        contextWindow,
+                        maxTokens: maxTokens,
+                        minTailMessages: 12,
+                        compactAt: cfg.compact_at ?? 0.8,
+                        toolSchemaTokens: estimateToolSchemaTokens(getToolsSchema()),
+                    });
+                    const compactedByRefs = new Set(compacted);
+                    const dropped = beforeMsgs.filter((m) => !compactedByRefs.has(m));
+                    if (dropped.length && vault) {
+                        try {
+                            // Store the original/current user prompt before compaction so it survives context loss.
+                            // Find the last substantive user message that looks like a task/instruction.
+                            let userPromptToPreserve = null;
+                            for (let i = beforeMsgs.length - 1; i >= 0; i--) {
+                                const m = beforeMsgs[i];
+                                if (m.role === 'user') {
+                                    const text = userContentToText((m.content ?? '')).trim();
+                                    // Skip vault injection messages and short prompts
+                                    if (text && !text.startsWith('[Trifecta Vault') && !text.startsWith('[Vault context') && text.length > 20) {
+                                        userPromptToPreserve = text;
+                                        break;
+                                    }
                                 }
                             }
+                            if (userPromptToPreserve) {
+                                await vault.upsertNote('current_task', userPromptToPreserve.slice(0, 2000), 'system');
+                            }
+                            const toArchive = lens
+                                ? await Promise.all(dropped.map((m) => archiveToolOutputForVault(m)))
+                                : dropped;
+                            await vault.archiveToolMessages(toArchive, toolNameByCallId);
                         }
-                        if (userPromptToPreserve) {
-                            await vault.upsertNote('current_task', userPromptToPreserve.slice(0, 2000), 'system');
+                        catch (e) {
+                            console.warn(`[warn] vault archive failed: ${e instanceof Error ? e.message : String(e)}`);
                         }
-                        const toArchive = lens
-                            ? await Promise.all(dropped.map((m) => archiveToolOutputForVault(m)))
-                            : dropped;
-                        await vault.archiveToolMessages(toArchive, toolNameByCallId);
                     }
-                    catch (e) {
-                        console.warn(`[warn] vault archive failed: ${e instanceof Error ? e.message : String(e)}`);
+                    messages = compacted;
+                    if (dropped.length) {
+                        messages.push({ role: 'system', content: buildCompactionSystemNote('auto', dropped.length) });
+                        await injectVaultContext().catch(() => { });
+                        injectCompactionReminder('auto context-budget compaction');
                     }
-                }
-                messages = compacted;
-                if (dropped.length) {
-                    messages.push({ role: 'system', content: buildCompactionSystemNote('auto', dropped.length) });
-                    await injectVaultContext().catch(() => { });
-                    injectCompactionReminder('auto context-budget compaction');
-                }
+                    const afterTokens = estimateTokensFromMessages(compacted);
+                    return {
+                        beforeMessages: beforeMsgs.length,
+                        afterMessages: compacted.length,
+                        freedTokens: Math.max(0, beforeTokens - afterTokens),
+                        archivedToolMessages: dropped.filter((m) => m.role === 'tool').length,
+                        droppedMessages: dropped.length,
+                        dryRun: false,
+                    };
+                });
                 const ac = makeAbortController();
                 inFlight = ac;
                 // If caller provided an AbortSignal (bench iteration timeout, etc), propagate it.
@@ -2019,11 +2169,13 @@ export async function createSession(opts) {
                 let resp;
                 try {
                     try {
+                        const toolsForTurn = forceToollessRecoveryTurn ? [] : getToolsSchema();
+                        const toolChoiceForTurn = forceToollessRecoveryTurn ? 'none' : 'auto';
                         resp = await client.chatStream({
                             model,
                             messages,
-                            tools: getToolsSchema(),
-                            tool_choice: 'auto',
+                            tools: toolsForTurn,
+                            tool_choice: toolChoiceForTurn,
                             temperature,
                             top_p: topP,
                             max_tokens: maxTokens,
@@ -2113,6 +2265,8 @@ export async function createSession(opts) {
                         },
                     }
                     : undefined;
+                const wasToollessRecoveryTurn = forceToollessRecoveryTurn;
+                forceToollessRecoveryTurn = false;
                 const choice0 = resp.choices?.[0] ?? legacyChoice;
                 const finishReason = choice0?.finish_reason ?? 'unknown';
                 const msg = choice0?.message;
@@ -2163,6 +2317,10 @@ export async function createSession(opts) {
                         }
                     }
                 }
+                if (wasToollessRecoveryTurn && toolCallsArr?.length) {
+                    // Recovery turn explicitly disables tools; ignore any stray tool-call output.
+                    toolCallsArr = undefined;
+                }
                 if (cfg.verbose) {
                     console.warn(`[turn ${turns}] finish_reason=${finishReason} content_chars=${content.length} visible_chars=${visible.length} tool_calls=${toolCallsArr?.length ?? 0}`);
                 }
@@ -2241,12 +2399,17 @@ export async function createSession(opts) {
                     // narration chunk starts on a fresh line (avoids wall-of-text output).
                     if (visible && hookObj.onToken)
                         hookObj.onToken('\n');
-                    toolCalls += toolCallsArr.length;
+                    const originalToolCallsArr = toolCallsArr;
+                    const preparedTurn = toolLoopGuard.prepareTurn(originalToolCallsArr);
+                    const replayByCallId = preparedTurn.replayByCallId;
+                    const parsedArgsByCallId = preparedTurn.parsedArgsByCallId;
+                    toolCallsArr = preparedTurn.uniqueCalls;
+                    toolCalls += originalToolCallsArr.length;
                     const assistantToolCallText = visible || '';
                     const compactAssistantToolCallText = assistantToolCallText.length > 900
                         ? `${assistantToolCallText.slice(0, 900)}\n[history-compacted: assistant narration truncated before tool execution]`
                         : assistantToolCallText;
-                    messages.push({ role: 'assistant', content: compactAssistantToolCallText, tool_calls: toolCallsArr });
+                    messages.push({ role: 'assistant', content: compactAssistantToolCallText, tool_calls: originalToolCallsArr });
                     // sigCounts is scoped to the entire ask() run (see above)
                     // Bridge ConfirmationProvider → legacy confirm callback for tools.
                     // If a ConfirmationProvider is given, wrap it; otherwise fall back to raw callback.
@@ -2290,20 +2453,64 @@ export async function createSession(opts) {
                     // We only treat repeated exec as a loop if no file mutations happened since the
                     // last time we saw that exact exec signature.
                     const turnSigs = new Set();
+                    const sigMetaBySig = new Map();
                     for (const tc of toolCallsArr) {
-                        const sig = `${tc.function.name}:${tc.function.arguments ?? '{}'}`;
+                        const callId = resolveCallId(tc);
+                        const parsedArgs = parsedArgsByCallId.get(callId) ?? {};
+                        const sig = toolLoopGuard.computeSignature(tc.function.name, parsedArgs);
                         turnSigs.add(sig);
+                        if (!sigMetaBySig.has(sig)) {
+                            sigMetaBySig.set(sig, { toolName: tc.function.name, args: parsedArgs });
+                        }
                     }
                     // Repeated read-only exec calls can be served from cache instead of hard-breaking.
                     const repeatedReadOnlyExecSigs = new Set();
                     const readOnlyExecTurnHints = [];
+                    // Repeated exec calls (any kind) can replay cached results under pressure.
+                    const replayExecSigs = new Set();
                     // Repeated read_file/read_files/list_dir calls can be served from cache.
                     const repeatedReadFileSigs = new Set();
+                    let shouldForceToollessRecovery = false;
+                    const criticalLoopSigs = new Set();
+                    for (const tc of toolCallsArr) {
+                        const callId = resolveCallId(tc);
+                        const args = parsedArgsByCallId.get(callId) ?? {};
+                        const detected = toolLoopGuard.detect(tc.function.name, args);
+                        const warning = toolLoopGuard.formatWarning(detected, tc.function.name);
+                        if (warning) {
+                            const warningKey = `${warning.level}:${warning.detector}:${detected.signature}`;
+                            if (!toolLoopWarningKeys.has(warningKey)) {
+                                toolLoopWarningKeys.add(warningKey);
+                                await emitToolLoop({
+                                    level: warning.level,
+                                    detector: warning.detector,
+                                    toolName: warning.toolName,
+                                    count: warning.count,
+                                    message: warning.message,
+                                });
+                                messages.push({
+                                    role: 'system',
+                                    content: `[tool-loop ${warning.level}] ${warning.message}. Stop repeating ${warning.toolName} with unchanged inputs; continue with analysis or next step.`,
+                                });
+                            }
+                        }
+                        if (toolLoopGuard.shouldDisableToolsNextTurn(detected)) {
+                            shouldForceToollessRecovery = true;
+                            criticalLoopSigs.add(detected.signature);
+                        }
+                    }
                     // Track whether a mutation happened since a given signature was last seen.
                     // (Tool-loop is single-threaded across turns; this is safe to keep in-memory.)
                     for (const sig of turnSigs) {
                         sigCounts.set(sig, (sigCounts.get(sig) ?? 0) + 1);
-                        const toolName = sig.split(':')[0];
+                        const sigMeta = sigMetaBySig.get(sig);
+                        const toolName = sigMeta?.toolName ?? sig.split(':')[0];
+                        if (criticalLoopSigs.has(sig)) {
+                            // Critical detector already fired for this signature; recover next turn
+                            // with tools disabled instead of throwing in per-tool hard-break logic.
+                            shouldForceToollessRecovery = true;
+                            continue;
+                        }
                         // For exec loops, only break if nothing changed since last identical exec.
                         if (toolName === 'exec') {
                             // If this exact exec signature was seen before, record the mutation version at that time.
@@ -2314,6 +2521,18 @@ export async function createSession(opts) {
                             mutationVersionBySig.set(sig, mutationVersion);
                             if (!hasMutatedSince) {
                                 const count = sigCounts.get(sig) ?? 0;
+                                // Early replay: if this exact exec was already run (count >= 2) and
+                                // we have a cached result, replay it instead of re-executing.  This
+                                // prevents the compaction death spiral where tool results get dropped,
+                                // the model forgets it ran the command, and re-runs it endlessly.
+                                // Skip read-only commands that already have their own observation cache —
+                                // those are handled by the dedicated read-only path at loopThreshold.
+                                const command = execCommandFromSig(sig);
+                                const hasReadOnlyCache = looksLikeReadOnlyExecCommand(command) && execObservationCacheBySig.has(sig);
+                                if (count >= 2 && lastExecResultBySig.has(sig) && !hasReadOnlyCache) {
+                                    replayExecSigs.add(sig);
+                                    continue;
+                                }
                                 let loopThreshold = harness.quirks.loopsOnToolError ? 3 : 6;
                                 // If the cached observation already tells the model "no matches found",
                                 // break much earlier — the model is ignoring the hint.
@@ -2326,7 +2545,8 @@ export async function createSession(opts) {
                                     await injectVaultContext().catch(() => { });
                                 }
                                 if (count >= loopThreshold) {
-                                    const command = execCommandFromSig(sig);
+                                    const sigArgs = sigMetaBySig.get(sig)?.args ?? {};
+                                    const command = typeof sigArgs?.command === 'string' ? String(sigArgs.command) : '';
                                     const canReuseReadOnlyObservation = looksLikeReadOnlyExecCommand(command) &&
                                         execObservationCacheBySig.has(sig);
                                     if (canReuseReadOnlyObservation) {
@@ -2337,8 +2557,8 @@ export async function createSession(opts) {
                                         }
                                         continue;
                                     }
-                                    const args = sig.slice(toolName.length + 1);
-                                    const argsPreview = args.length > 220 ? args.slice(0, 220) + '…' : args;
+                                    const argsPreviewRaw = JSON.stringify(sigArgs);
+                                    const argsPreview = argsPreviewRaw.length > 220 ? argsPreviewRaw.slice(0, 220) + '…' : argsPreviewRaw;
                                     throw new Error(`tool ${toolName}: identical call repeated ${loopThreshold}x across turns; breaking loop. ` +
                                         `args=${argsPreview}`);
                                 }
@@ -2396,23 +2616,30 @@ export async function createSession(opts) {
                                         content: `CRITICAL: DO NOT make another identical call for this ${resourceType}. It HAS NOT CHANGED. You already have the content. Move on to the NEXT step NOW.`,
                                     });
                                 }
-                                if (readFileCacheBySig.has(sig)) {
+                                const argsForSig = sigMetaBySig.get(sig)?.args ?? {};
+                                const replay = await toolLoopGuard.getReadCacheReplay(toolName, argsForSig, ctx.cwd);
+                                if (replay) {
                                     repeatedReadFileSigs.add(sig);
                                     continue;
                                 }
                             }
-                            // Hard-break at threshold
+                            // Deterministic recovery at threshold (no hard throw): force one no-tools turn.
                             if (consec >= hardBreakAt) {
-                                throw new Error(`tool ${toolName}: identical read repeated ${consec}x consecutively; breaking loop. ` +
-                                    `The resource content has not changed between reads.`);
+                                shouldForceToollessRecovery = true;
+                                messages.push({
+                                    role: 'system',
+                                    content: `[tool-loop critical] ${toolName} repeated ${consec}x with unchanged inputs. ` +
+                                        'Next turn will run with tools disabled so you must use existing results and provide a concrete next step/final response.',
+                                });
                             }
                             continue;
                         }
                         // Default behavior for mutating/other tools: break on repeated identical signature.
                         const loopThreshold = harness.quirks.loopsOnToolError ? 2 : 3;
                         if ((sigCounts.get(sig) ?? 0) >= loopThreshold) {
-                            const args = sig.slice(toolName.length + 1);
-                            const argsPreview = args.length > 220 ? args.slice(0, 220) + '…' : args;
+                            const argsObj = sigMetaBySig.get(sig)?.args ?? {};
+                            const argsRaw = JSON.stringify(argsObj);
+                            const argsPreview = argsRaw.length > 220 ? argsRaw.slice(0, 220) + '…' : argsRaw;
                             throw new Error(`tool ${toolName}: identical call repeated ${loopThreshold}x across turns; breaking loop. ` +
                                 `args=${argsPreview}\n` +
                                 `Hint: you repeated the same tool call ${loopThreshold} times with identical arguments. ` +
@@ -2423,6 +2650,31 @@ export async function createSession(opts) {
                     }
                     // Update consecutive tracking: save this turn's signatures for next turn comparison.
                     lastTurnSigs = turnSigs;
+                    if (shouldForceToollessRecovery) {
+                        if (!toollessRecoveryUsed) {
+                            forceToollessRecoveryTurn = true;
+                            toollessRecoveryUsed = true;
+                            messages.push({
+                                role: 'user',
+                                content: '[system] Critical tool loop detected. Next turn will run with tools disabled. ' +
+                                    'Use already available tool results to provide a concrete next step or final response; do not request more tools.',
+                            });
+                            await emitTurnEnd({
+                                turn: turns,
+                                toolCalls,
+                                promptTokens: cumulativeUsage.prompt,
+                                completionTokens: cumulativeUsage.completion,
+                                promptTokensTurn,
+                                completionTokensTurn,
+                                ttftMs,
+                                ttcMs,
+                                ppTps,
+                                tgTps,
+                            });
+                            continue;
+                        }
+                        throw new AgentLoopBreak('critical tool-loop persisted after one tools-disabled recovery turn. Stopping to avoid infinite loop.');
+                    }
                     const runOne = async (tc) => {
                         const name = tc.function.name;
                         const rawArgs = tc.function.arguments ?? '{}';
@@ -2452,6 +2704,7 @@ export async function createSession(opts) {
                             throw new Error(`unknown tool: ${name}`);
                         // Keep parsed args by call-id so we can digest/archive tool outputs with context.
                         toolArgsByCallId.set(callId, args && typeof args === 'object' && !Array.isArray(args) ? args : {});
+                        toolLoopGuard.registerCall(name, args && typeof args === 'object' && !Array.isArray(args) ? args : {}, callId);
                         // Pre-dispatch argument validation.
                         // - Required params
                         // - Type/range/enums
@@ -2556,7 +2809,7 @@ export async function createSession(opts) {
                                 return { id: callId, content: '[skipped by user: step mode]' };
                             }
                         }
-                        const sig = `${name}:${rawArgs || '{}'}`;
+                        const sig = toolLoopGuard.computeSignature(name, args && typeof args === 'object' && !Array.isArray(args) ? args : {});
                         let content = '';
                         let reusedCachedReadOnlyExec = false;
                         let reusedCachedReadTool = false;
@@ -2567,10 +2820,18 @@ export async function createSession(opts) {
                                 reusedCachedReadOnlyExec = true;
                             }
                         }
-                        if (READ_FILE_CACHE_TOOLS.has(name) && repeatedReadFileSigs.has(sig)) {
-                            const cached = readFileCacheBySig.get(sig);
+                        // Replay any exec result (read-only or not) when the loop detector flagged it.
+                        if (name === 'exec' && !reusedCachedReadOnlyExec && replayExecSigs.has(sig)) {
+                            const cached = lastExecResultBySig.get(sig);
                             if (cached) {
-                                content = withCachedReadObservationHint(cached);
+                                content = withReplayedExecHint(cached);
+                                reusedCachedReadOnlyExec = true; // skip re-execution below
+                            }
+                        }
+                        if (READ_FILE_CACHE_TOOLS.has(name) && repeatedReadFileSigs.has(sig)) {
+                            const replay = await toolLoopGuard.getReadCacheReplay(name, args, ctx.cwd);
+                            if (replay) {
+                                content = replay;
                                 reusedCachedReadTool = true;
                             }
                         }
@@ -2588,11 +2849,15 @@ export async function createSession(opts) {
                                 const value = await builtInFn(callCtx, args);
                                 content = typeof value === 'string' ? value : JSON.stringify(value);
                                 if (READ_FILE_CACHE_TOOLS.has(name) && typeof content === 'string' && !content.startsWith('ERROR:')) {
-                                    readFileCacheBySig.set(sig, content);
+                                    const baseCwd = typeof args?.cwd === 'string' ? String(args.cwd) : ctx.cwd;
+                                    await toolLoopGuard.storeReadCache(name, args, baseCwd, content);
                                 }
                                 if (name === 'exec') {
                                     // Successful exec clears blocked-loop counters.
                                     blockedExecAttemptsBySig.clear();
+                                    // Cache every exec result so repeated calls under context pressure
+                                    // can replay the result instead of re-executing.
+                                    lastExecResultBySig.set(sig, content);
                                     const cmd = String(args?.command ?? '');
                                     if (looksLikeReadOnlyExecCommand(cmd) && readOnlyExecCacheable(content)) {
                                         execObservationCacheBySig.set(sig, content);
@@ -2731,6 +2996,10 @@ export async function createSession(opts) {
                                 }
                             }
                         }
+                        toolLoopGuard.registerOutcome(name, args, {
+                            toolCallId: callId,
+                            result: content,
+                        });
                         return { id: callId, content };
                     };
                     const results = [];
@@ -2751,7 +3020,8 @@ export async function createSession(opts) {
                         // Applies to direct exec attempts and spawn_task delegation attempts.
                         if (tc.function.name === 'exec' || tc.function.name === 'spawn_task') {
                             const blockedMatch = msg.match(/^exec:\s*blocked\s*\(([^)]+)\)\s*without --no-confirm\/--yolo:\s*(.*)$/i)
-                                || msg.match(/^(spawn_task):\s*blocked\s*—\s*(.*)$/i);
+                                || msg.match(/^(spawn_task):\s*blocked\s*—\s*(.*)$/i)
+                                || msg.match(/^exec:\s*blocked\s+(background command\b[^.]*)\./i);
                             if (blockedMatch) {
                                 const reason = (blockedMatch[1] || blockedMatch[2] || 'blocked command').trim();
                                 let parsedArgs = {};
@@ -2763,7 +3033,8 @@ export async function createSession(opts) {
                                     ? String(parsedArgs?.command ?? '')
                                     : String(parsedArgs?.task ?? '');
                                 const normalizedReason = reason.toLowerCase();
-                                const aggregateByReason = normalizedReason.includes('package install/remove');
+                                const aggregateByReason = normalizedReason.includes('package install/remove')
+                                    || normalizedReason.includes('background command');
                                 const sig = aggregateByReason
                                     ? `${tc.function.name}|${reason}`
                                     : `${tc.function.name}|${reason}|${cmd}`;
@@ -2785,7 +3056,33 @@ export async function createSession(opts) {
                             retryable: te.retryable,
                             result: toolErrorContent,
                         });
-                        return { id: callId, content: toolErrorContent };
+                        let parsedArgs = {};
+                        try {
+                            const parsed = JSON.parse(tc.function.arguments ?? '{}');
+                            if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+                                parsedArgs = parsed;
+                            }
+                        }
+                        catch {
+                            // keep empty object
+                        }
+                        toolLoopGuard.registerOutcome(tc.function.name, parsedArgs, {
+                            toolCallId: callId,
+                            error: msg,
+                        });
+                        // Inject fallback guidance after 2 consecutive read_file/read_files failures.
+                        let resultContent = toolErrorContent;
+                        if (tc.function.name === 'read_file' || tc.function.name === 'read_files') {
+                            const failureCount = toolLoopGuard.getReadFileFailureCount();
+                            if (failureCount >= 2) {
+                                resultContent +=
+                                    `\n\n[WARNING: ${tc.function.name} has failed ${failureCount} times consecutively. ` +
+                                        'Try using `sed` and the `edit_range` tool; if those do not work, create a temporary file with the full contents and save it. ' +
+                                        'Then remove the existing file and rename the temporary file to bypass edit_file failing.]';
+                                toolLoopGuard.resetReadFileFailureCount();
+                            }
+                        }
+                        return { id: callId, content: resultContent };
                     };
                     // ── Anti-scan guardrails (§ read budget, dir scan, same-search) ──
                     const readOnlyInTurn = toolCallsArr.filter((tc) => isReadOnlyToolDynamic(tc.function.name));
@@ -2848,6 +3145,19 @@ export async function createSession(opts) {
                             }
                         }
                     }
+                    if (replayByCallId.size > 0) {
+                        const canonicalById = new Map(results.map((r) => [r.id, r.content]));
+                        for (const [dupId, canonicalId] of replayByCallId.entries()) {
+                            const canonical = canonicalById.get(canonicalId);
+                            if (canonical == null)
+                                continue;
+                            results.push({
+                                id: dupId,
+                                content: `[idlehands dedupe] Identical tool call replayed from ${canonicalId}. ` +
+                                    'Use that earlier tool result; no new execution was performed.',
+                            });
+                        }
+                    }
                     // Bail immediately if cancelled during tool execution
                     if (ac.signal.aborted)
                         break;
@@ -2895,6 +3205,8 @@ export async function createSession(opts) {
                                 'Do not narrate. Fix required/mistyped fields and unknown keys.',
                         });
                     }
+                    // Update session-level tool loop stats for observability
+                    lastToolLoopStats = toolLoopGuard.getStats();
                     // Hook: onTurnEnd (Phase 8.5)
                     await emitTurnEnd({
                         turn: turns,
@@ -3068,6 +3380,7 @@ export async function createSession(opts) {
         listModels,
         refreshServerHealth,
         getPerfSummary,
+        getToolLoopStats: () => lastToolLoopStats,
         captureOn,
         captureOff,
         captureLast,
@@ -3105,6 +3418,9 @@ export async function createSession(opts) {
         get planSteps() {
             return planSteps;
         },
+        get compactionStats() {
+            return { ...compactionStats };
+        },
         executePlanStep,
         clearPlan,
         compactHistory