@visorcraft/idlehands 1.1.6 → 1.1.8

package/dist/agent.js

@@ -3,6 +3,7 @@ import { enforceContextBudget, stripThinking, estimateTokensFromMessages, estima
 import * as tools from './tools.js';
 import { selectHarness } from './harnesses.js';
 import { BASE_MAX_TOKENS, deriveContextWindow, deriveGenerationParams, supportsVisionModel } from './model-customization.js';
+import { HookManager, loadHookPlugins } from './hooks/index.js';
 import { checkExecSafety, checkPathSafety } from './safety.js';
 import { loadProjectContext } from './context.js';
 import { loadGitContext, isGitDirty, stashWorkingTree } from './git.js';
@@ -13,123 +14,18 @@ import { LensStore } from './lens.js';
 import { SYS_CONTEXT_SCHEMA, collectSnapshot } from './sys/context.js';
 import { MCPManager } from './mcp.js';
 import { LspManager, detectInstalledLspServers } from './lsp.js';
+import { generateMinimalDiff, toolResultSummary, execCommandFromSig, formatDurationMs, looksLikePlanningNarration, capTextByApproxTokens, isLikelyBinaryBuffer, sanitizePathsInMessage, digestToolResult, } from './agent/formatting.js';
+import { parseToolCallsFromContent, getMissingRequiredParams, stripMarkdownFences } from './agent/tool-calls.js';
+export { parseToolCallsFromContent };
+import { reviewArtifactKeys, looksLikeCodeReviewRequest, looksLikeReviewRetrievalRequest, retrievalAllowsStaleArtifact, parseReviewArtifactStalePolicy, parseReviewArtifact, reviewArtifactStaleReason, gitHead, normalizeModelsResponse, } from './agent/review-artifact.js';
 import fs from 'node:fs/promises';
 import path from 'node:path';
-import { spawnSync } from 'node:child_process';
-import { stateDir, BASH_PATH as BASH } from './utils.js';
+import { stateDir, timestampedId } from './utils.js';
 function makeAbortController() {
     // Node 24: AbortController is global.
     return new AbortController();
 }
-/** Generate a minimal unified diff for Phase 7 rich display (max 20 lines, truncated). */
-function generateMinimalDiff(before, after, filePath) {
-    const bLines = before.split('\n');
-    const aLines = after.split('\n');
-    const out = [];
-    out.push(`--- a/${filePath}`);
-    out.push(`+++ b/${filePath}`);
-    // Simple line-by-line diff (find changed region)
-    let diffStart = 0;
-    while (diffStart < bLines.length && diffStart < aLines.length && bLines[diffStart] === aLines[diffStart])
-        diffStart++;
-    let bEnd = bLines.length - 1;
-    let aEnd = aLines.length - 1;
-    while (bEnd > diffStart && aEnd > diffStart && bLines[bEnd] === aLines[aEnd]) {
-        bEnd--;
-        aEnd--;
-    }
-    const contextBefore = Math.max(0, diffStart - 2);
-    const contextAfter = Math.min(Math.max(bLines.length, aLines.length) - 1, Math.max(bEnd, aEnd) + 2);
-    const bEndContext = Math.min(bLines.length - 1, contextAfter);
-    const aEndContext = Math.min(aLines.length - 1, contextAfter);
-    out.push(`@@ -${contextBefore + 1},${bEndContext - contextBefore + 1} +${contextBefore + 1},${aEndContext - contextBefore + 1} @@`);
-    let lineCount = 0;
-    const MAX_LINES = 20;
-    // Context before change
-    for (let i = contextBefore; i < diffStart && lineCount < MAX_LINES; i++) {
-        out.push(` ${bLines[i]}`);
-        lineCount++;
-    }
-    // Removed lines
-    for (let i = diffStart; i <= bEnd && i < bLines.length && lineCount < MAX_LINES; i++) {
-        out.push(`-${bLines[i]}`);
-        lineCount++;
-    }
-    // Added lines
-    for (let i = diffStart; i <= aEnd && i < aLines.length && lineCount < MAX_LINES; i++) {
-        out.push(`+${aLines[i]}`);
-        lineCount++;
-    }
-    // Context after change
-    const afterStart = Math.max(bEnd, aEnd) + 1;
-    for (let i = afterStart; i <= contextAfter && i < Math.max(bLines.length, aLines.length) && lineCount < MAX_LINES; i++) {
-        const line = i < aLines.length ? aLines[i] : bLines[i] ?? '';
-        out.push(` ${line}`);
-        lineCount++;
-    }
-    const totalChanges = (bEnd - diffStart + 1) + (aEnd - diffStart + 1);
-    if (lineCount >= MAX_LINES && totalChanges > MAX_LINES) {
-        out.push(`[+${totalChanges - MAX_LINES} more lines]`);
-    }
-    return out.join('\n');
-}
-/** Generate a one-line summary of a tool result for hooks/display. */
-function toolResultSummary(name, args, content, success) {
-    if (!success)
-        return content.slice(0, 120);
-    switch (name) {
-        case 'read_file':
-        case 'read_files': {
-            const lines = content.split('\n').length;
-            return `${lines} lines read`;
-        }
-        case 'write_file':
-            return `wrote ${args.path || 'file'}`;
-        case 'edit_file':
-            return content.startsWith('ERROR') ? content.slice(0, 120) : `applied edit`;
-        case 'insert_file':
-            return `inserted at line ${args.line ?? '?'}`;
-        case 'exec': {
-            try {
-                const r = JSON.parse(content);
-                const lines = (r.out || '').split('\n').filter(Boolean).length;
-                return `rc=${r.rc}, ${lines} lines`;
-            }
-            catch {
-                return content.slice(0, 80);
-            }
-        }
-        case 'list_dir': {
-            const entries = content.split('\n').filter(Boolean).length;
-            return `${entries} entries`;
-        }
-        case 'search_files': {
-            const matches = (content.match(/^\d+:/gm) || []).length;
-            return `${matches} matches`;
-        }
-        case 'spawn_task': {
-            const line = content.split(/\r?\n/).find((l) => l.includes('status='));
-            return line ? line.trim() : 'sub-agent task finished';
-        }
-        case 'vault_search':
-            return `vault results`;
-        default:
-            return content.slice(0, 80);
-    }
-}
 const CACHED_EXEC_OBSERVATION_HINT = '[idlehands hint] Reused cached output for repeated read-only exec call (unchanged observation).';
-function execCommandFromSig(sig) {
-    if (!sig.startsWith('exec:'))
-        return '';
-    const raw = sig.slice('exec:'.length);
-    try {
-        const parsed = JSON.parse(raw);
-        return typeof parsed?.command === 'string' ? parsed.command : '';
-    }
-    catch {
-        return '';
-    }
-}
 function looksLikeReadOnlyExecCommand(command) {
     const cmd = String(command || '').trim().toLowerCase();
     if (!cmd)
@@ -202,7 +98,7 @@ Rules:
 - Never use spawn_task to bypass confirmation/safety restrictions (for example blocked package installs). If a command is blocked, adapt the plan or ask the user for approval mode changes.
 - Read the target file before editing. You need the exact text for search/replace.
 - Use read_file with search=... to jump to relevant code; avoid reading whole files.
-- Use edit_file for surgical changes. Never rewrite entire files when a targeted edit works.
+- Prefer apply_patch or edit_range for code edits (token-efficient). Use edit_file only when exact old_text replacement is necessary.
 - Use insert_file for insertions (prepend/append/line).
 - Use exec to run commands, tests, builds; check results before reporting success.
 - When running commands in a subdirectory, use exec's cwd parameter — NOT "cd /path && cmd". Each exec call is a fresh shell; cd does not persist.
@@ -229,7 +125,7 @@ const DEFAULT_SUB_AGENT_RESULT_TOKEN_CAP = 4000;
 const APPROVAL_MODE_SET = new Set(['plan', 'reject', 'default', 'auto-edit', 'yolo']);
 const LSP_TOOL_NAMES = ['lsp_diagnostics', 'lsp_symbols', 'lsp_hover', 'lsp_definition', 'lsp_references'];
 const LSP_TOOL_NAME_SET = new Set(LSP_TOOL_NAMES);
-const FILE_MUTATION_TOOL_SET = new Set(['edit_file', 'write_file', 'insert_file']);
+const FILE_MUTATION_TOOL_SET = new Set(['edit_file', 'edit_range', 'apply_patch', 'write_file', 'insert_file']);
 function normalizeApprovalMode(value) {
     if (typeof value !== 'string')
         return undefined;
@@ -245,66 +141,6 @@ const APPROVAL_MODE_RANK = { plan: 0, reject: 1, default: 2, 'auto-edit': 3, yol
 function capApprovalMode(requested, parentMode) {
     return APPROVAL_MODE_RANK[requested] <= APPROVAL_MODE_RANK[parentMode] ? requested : parentMode;
 }
-function formatDurationMs(ms) {
-    if (!Number.isFinite(ms) || ms <= 0)
-        return '0.0s';
-    return `${(ms / 1000).toFixed(1)}s`;
-}
-function looksLikePlanningNarration(text, finishReason) {
-    const s = String(text ?? '').trim().toLowerCase();
-    if (!s)
-        return false;
-    // Incomplete streamed answer: likely still needs another turn.
-    if (finishReason === 'length')
-        return true;
-    // Strong completion cues: treat as final answer.
-    if (/(^|\n)\s*(done|completed|finished|final answer|summary:)\b/.test(s))
-        return false;
-    // Typical "thinking out loud"/plan chatter that should continue with tools.
-    return /\b(let me|i(?:'|’)ll|i will|i'm going to|i am going to|next i(?:'|’)ll|first i(?:'|’)ll|i need to|i should|checking|reviewing|exploring|starting by)\b/.test(s);
-}
-function approxTokenCharCap(maxTokens) {
-    const safe = Math.max(64, Math.floor(maxTokens));
-    return safe * 4;
-}
-function capTextByApproxTokens(text, maxTokens) {
-    const raw = String(text ?? '');
-    const maxChars = approxTokenCharCap(maxTokens);
-    if (raw.length <= maxChars)
-        return { text: raw, truncated: false };
-    const clipped = raw.slice(0, maxChars);
-    return {
-        text: `${clipped}\n\n[sub-agent] result truncated to ~${maxTokens} tokens (${raw.length} chars original)`,
-        truncated: true,
-    };
-}
-function isLikelyBinaryBuffer(buf) {
-    const n = Math.min(buf.length, 512);
-    for (let i = 0; i < n; i++) {
-        if (buf[i] === 0)
-            return true;
-    }
-    return false;
-}
-/**
- * Strip absolute paths from a message to prevent cross-project leaks in vault.
- * Paths within cwd are replaced with relative equivalents; other absolute paths
- * are replaced with just the basename.
- */
-function sanitizePathsInMessage(message, cwd) {
-    const normCwd = cwd.replace(/\/+$/, '');
-    // Match absolute Unix paths (at least 2 segments)
-    return message.replace(/\/(?:home|tmp|var|usr|opt|etc|root)\/[^\s"',;)\]}>]+/g, (match) => {
-        const normMatch = match.replace(/\/+$/, '');
-        if (normMatch.startsWith(normCwd + '/')) {
-            // Within cwd — make relative
-            return normMatch.slice(normCwd.length + 1);
-        }
-        // Outside cwd — strip to basename
-        const base = path.basename(normMatch);
-        return base || match;
-    });
-}
 async function buildSubAgentContextBlock(cwd, rawFiles) {
     const values = Array.isArray(rawFiles) ? rawFiles : [];
     const files = values
@@ -384,155 +220,155 @@ function buildToolsSchema(opts) {
         properties,
         required
     });
+    const str = () => ({ type: 'string' });
+    const bool = () => ({ type: 'boolean' });
+    const int = (min, max) => ({ type: 'integer', ...(min !== undefined && { minimum: min }), ...(max !== undefined && { maximum: max }) });
     const schemas = [
+        // ────────────────────────────────────────────────────────────────────────────
+        // Token-safe reads (require limit; allow plain output without per-line numbers)
+        // ────────────────────────────────────────────────────────────────────────────
         {
             type: 'function',
             function: {
                 name: 'read_file',
-                description: 'Read file contents with line numbers. Use search/context to jump to relevant code.',
+                description: 'Read a bounded slice of a file.',
                 parameters: obj({
-                    path: { type: 'string' },
-                    offset: { type: 'integer' },
-                    limit: { type: 'integer' },
-                    search: { type: 'string' },
-                    context: { type: 'integer' },
-                }, ['path'])
-            }
+                    path: str(),
+                    offset: int(1, 1_000_000),
+                    limit: int(1, 240),
+                    search: str(),
+                    context: int(0, 80),
+                    format: { type: 'string', enum: ['plain', 'numbered', 'sparse'] },
+                    max_bytes: int(256, 20_000),
+                }, ['path', 'limit']),
+            },
         },
         {
             type: 'function',
             function: {
                 name: 'read_files',
-                description: 'Batch read multiple files.',
+                description: 'Batch read bounded file slices.',
                 parameters: obj({
                     requests: {
                         type: 'array',
                         items: obj({
-                            path: { type: 'string' },
-                            offset: { type: 'integer' },
-                            limit: { type: 'integer' },
-                            search: { type: 'string' },
-                            context: { type: 'integer' },
-                        }, ['path'])
-                    }
-                }, ['requests'])
-            }
+                            path: str(),
+                            offset: int(1, 1_000_000),
+                            limit: int(1, 240),
+                            search: str(),
+                            context: int(0, 80),
+                            format: { type: 'string', enum: ['plain', 'numbered', 'sparse'] },
+                            max_bytes: int(256, 20_000),
+                        }, ['path', 'limit']),
+                    },
+                }, ['requests']),
+            },
         },
+        // ────────────────────────────────────────────────────────────────────────────
+        // Writes/edits
+        // ────────────────────────────────────────────────────────────────────────────
         {
             type: 'function',
             function: {
                 name: 'write_file',
-                description: 'Write a file (atomic). Creates parents. Makes a backup first.',
-                parameters: obj({ path: { type: 'string' }, content: { type: 'string' } }, ['path', 'content'])
-            }
+                description: 'Write file (atomic, backup).',
+                parameters: obj({ path: str(), content: str() }, ['path', 'content']),
+            },
         },
         {
             type: 'function',
             function: {
-                name: 'edit_file',
-                description: 'Search/replace exact text in a file. Fails if old_text not found.',
+                name: 'apply_patch',
+                description: 'Apply unified diff patch (multi-file).',
                 parameters: obj({
-                    path: { type: 'string' },
-                    old_text: { type: 'string' },
-                    new_text: { type: 'string' },
-                    replace_all: { type: 'boolean' }
-                }, ['path', 'old_text', 'new_text'])
-            }
+                    patch: str(),
+                    files: { type: 'array', items: str() },
+                    strip: int(0, 5),
+                }, ['patch', 'files']),
+            },
         },
         {
             type: 'function',
             function: {
-                name: 'insert_file',
-                description: 'Insert text at a specific line (0=prepend, -1=append).',
+                name: 'edit_range',
+                description: 'Replace a line range in a file.',
                 parameters: obj({
-                    path: { type: 'string' },
-                    line: { type: 'integer' },
-                    text: { type: 'string' }
-                }, ['path', 'line', 'text'])
-            }
+                    path: str(),
+                    start_line: int(1),
+                    end_line: int(1),
+                    replacement: str(),
+                }, ['path', 'start_line', 'end_line', 'replacement']),
+            },
         },
+        {
+            type: 'function',
+            function: {
+                name: 'edit_file',
+                description: 'Legacy exact replace (requires old_text). Prefer apply_patch/edit_range.',
+                parameters: obj({ path: str(), old_text: str(), new_text: str(), replace_all: bool() }, ['path', 'old_text', 'new_text']),
+            },
+        },
+        {
+            type: 'function',
+            function: {
+                name: 'insert_file',
+                description: 'Insert text at line (0=prepend, -1=append).',
+                parameters: obj({ path: str(), line: int(), text: str() }, ['path', 'line', 'text']),
+            },
+        },
+        // ────────────────────────────────────────────────────────────────────────────
+        // Bounded listings/search (expose existing caps)
+        // ────────────────────────────────────────────────────────────────────────────
         {
             type: 'function',
             function: {
                 name: 'list_dir',
-                description: 'List directory contents (optional recursive, max depth 3).',
-                parameters: obj({
-                    path: { type: 'string' },
-                    recursive: { type: 'boolean' },
-                }, ['path'])
-            }
+                description: 'List directory entries.',
+                parameters: obj({ path: str(), recursive: bool(), max_entries: int(1, 500) }, ['path']),
+            },
         },
         {
             type: 'function',
             function: {
                 name: 'search_files',
-                description: 'Search for a regex pattern in files under a directory.',
-                parameters: obj({
-                    pattern: { type: 'string' },
-                    path: { type: 'string' },
-                    include: { type: 'string' },
-                }, ['pattern', 'path'])
-            }
+                description: 'Search regex in files.',
+                parameters: obj({ pattern: str(), path: str(), include: str(), max_results: int(1, 100) }, ['pattern', 'path']),
+            },
         },
+        // ────────────────────────────────────────────────────────────────────────────
+        // Exec (minified schema)
+        // ────────────────────────────────────────────────────────────────────────────
         {
             type: 'function',
             function: {
                 name: 'exec',
-                description: 'Run a shell command (bash -c) with timeout; returns JSON rc/out/err. Each call is a new shell — cwd does not persist between calls.',
-                parameters: obj({
-                    command: { type: 'string', description: 'Shell command to run' },
-                    cwd: { type: 'string', description: 'Working directory (default: project root). Use this instead of cd.' },
-                    timeout: { type: 'integer', description: 'Timeout in seconds (default: 30, max: 120). Use 60-120 for npm install, builds, or test suites.' }
-                }, ['command'])
-            }
-        }
+                description: 'Run bash -c; returns JSON rc/out/err.',
+                parameters: obj({ command: str(), cwd: str(), timeout: int(1, 120) }, ['command']),
+            },
+        },
     ];
     if (opts?.allowSpawnTask !== false) {
         schemas.push({
             type: 'function',
             function: {
                 name: 'spawn_task',
-                description: 'Delegate a focused task to an isolated sub-agent session (no parent chat history).',
+                description: 'Run a sub-agent task (no parent history).',
                 parameters: obj({
-                    task: { type: 'string', description: 'Instruction for the sub-agent' },
-                    context_files: {
-                        type: 'array',
-                        description: 'Optional extra files to inject into sub-agent context',
-                        items: { type: 'string' },
-                    },
-                    model: { type: 'string', description: 'Optional model override for this task' },
-                    endpoint: { type: 'string', description: 'Optional endpoint override for this task' },
-                    max_iterations: { type: 'integer', description: 'Optional max turn cap for the sub-agent' },
-                    max_tokens: { type: 'integer', description: 'Optional max completion tokens for the sub-agent' },
-                    timeout_sec: { type: 'integer', description: 'Optional timeout for this sub-agent run (seconds)' },
-                    system_prompt: { type: 'string', description: 'Optional sub-agent system prompt override for this task' },
+                    task: str(),
+                    context_files: { type: 'array', items: str() },
+                    model: str(),
+                    endpoint: str(),
+                    max_iterations: int(),
+                    max_tokens: int(),
+                    timeout_sec: int(),
+                    system_prompt: str(),
                     approval_mode: { type: 'string', enum: ['plan', 'reject', 'default', 'auto-edit', 'yolo'] },
-                }, ['task'])
-            }
+                }, ['task']),
+            },
         });
     }
     if (opts?.activeVaultTools) {
-        schemas.push({
-            type: 'function',
-            function: {
-                name: 'vault_search',
-                description: 'Search vault entries (notes and previous tool outputs) to reuse prior high-signal findings.',
-                parameters: obj({
-                    query: { type: 'string' },
-                    limit: { type: 'integer' }
-                }, ['query'])
-            }
-        }, {
-            type: 'function',
-            function: {
-                name: 'vault_note',
-                description: 'Persist a concise, high-signal note into the Trifecta vault.',
-                parameters: obj({
-                    key: { type: 'string' },
-                    value: { type: 'string' }
-                }, ['key', 'value'])
-            }
-        });
+        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']) } });
     }
     // Phase 9: sys_context tool is only available in sys mode.
     if (opts?.sysMode) {
@@ -543,54 +379,36 @@ function buildToolsSchema(opts) {
             type: 'function',
             function: {
                 name: 'lsp_diagnostics',
-                description: 'Get current LSP diagnostics (errors/warnings) for a file or the whole project. Structured — replaces running build commands to check for errors.',
-                parameters: obj({
-                    path: { type: 'string', description: 'File path (omit for project-wide diagnostics)' },
-                    severity: { type: 'integer', description: '1=Error, 2=Warning, 3=Info, 4=Hint (default: config threshold)' },
-                }, [])
+                description: 'Get LSP diagnostics (errors/warnings) for file or project.',
+                parameters: obj({ path: str(), severity: int() }, [])
             }
         }, {
             type: 'function',
             function: {
                 name: 'lsp_symbols',
-                description: 'List all symbols (functions, classes, variables) in a file via LSP.',
-                parameters: obj({
-                    path: { type: 'string' },
-                }, ['path'])
+                description: 'List symbols (functions, classes, vars) in a file.',
+                parameters: obj({ path: str() }, ['path'])
             }
         }, {
             type: 'function',
             function: {
                 name: 'lsp_hover',
-                description: 'Get type info and documentation for a symbol at a position.',
-                parameters: obj({
-                    path: { type: 'string' },
-                    line: { type: 'integer' },
-                    character: { type: 'integer' },
-                }, ['path', 'line', 'character'])
+                description: 'Get type/docs for symbol at position.',
+                parameters: obj({ path: str(), line: int(), character: int() }, ['path', 'line', 'character'])
             }
         }, {
             type: 'function',
             function: {
                 name: 'lsp_definition',
-                description: 'Go to definition of a symbol at a given position.',
-                parameters: obj({
-                    path: { type: 'string' },
-                    line: { type: 'integer' },
-                    character: { type: 'integer' },
-                }, ['path', 'line', 'character'])
+                description: 'Go to definition of symbol at position.',
+                parameters: obj({ path: str(), line: int(), character: int() }, ['path', 'line', 'character'])
             }
         }, {
             type: 'function',
             function: {
                 name: 'lsp_references',
-                description: 'Find all references to a symbol at a given position.',
-                parameters: obj({
-                    path: { type: 'string' },
-                    line: { type: 'integer' },
-                    character: { type: 'integer' },
-                    max_results: { type: 'integer', description: 'Cap results (default 50)' },
-                }, ['path', 'line', 'character'])
+                description: 'Find all references to symbol at position.',
+                parameters: obj({ path: str(), line: int(), character: int(), max_results: int() }, ['path', 'line', 'character'])
             }
         });
     }
@@ -599,203 +417,6 @@ function buildToolsSchema(opts) {
     }
     return schemas;
 }
-/** @internal Exported for testing. Parses tool calls from model content when tool_calls array is empty. */
-export function parseToolCallsFromContent(content) {
-    // Fallback parser: if model printed JSON tool_calls in content.
-    const trimmed = content.trim();
-    const tryParse = (s) => {
-        try {
-            return JSON.parse(s);
-        }
-        catch {
-            return null;
-        }
-    };
-    // Case 1: whole content is JSON
-    const whole = tryParse(trimmed);
-    if (whole?.tool_calls && Array.isArray(whole.tool_calls))
-        return whole.tool_calls;
-    if (whole?.name && whole?.arguments) {
-        return [
-            {
-                id: 'call_0',
-                type: 'function',
-                function: { name: String(whole.name), arguments: JSON.stringify(whole.arguments) }
-            }
-        ];
-    }
-    // Case 2: raw JSON array of tool calls (model writes [{name, arguments}, ...])
-    const arrStart = trimmed.indexOf('[');
-    const arrEnd = trimmed.lastIndexOf(']');
-    if (arrStart !== -1 && arrEnd !== -1 && arrEnd > arrStart) {
-        const arrSub = tryParse(trimmed.slice(arrStart, arrEnd + 1));
-        if (Array.isArray(arrSub) && arrSub.length > 0 && arrSub[0]?.name) {
-            return arrSub.map((item, i) => ({
-                id: `call_${i}`,
-                type: 'function',
-                function: {
-                    name: String(item.name),
-                    arguments: typeof item.arguments === 'string' ? item.arguments : JSON.stringify(item.arguments ?? {})
-                }
-            }));
-        }
-    }
-    // Case 3: find a JSON object substring (handles tool_calls wrapper OR single tool-call)
-    const start = trimmed.indexOf('{');
-    const end = trimmed.lastIndexOf('}');
-    if (start !== -1 && end !== -1 && end > start) {
-        const sub = tryParse(trimmed.slice(start, end + 1));
-        if (sub?.tool_calls && Array.isArray(sub.tool_calls))
-            return sub.tool_calls;
-        if (sub?.name && sub?.arguments) {
-            return [
-                {
-                    id: 'call_0',
-                    type: 'function',
-                    function: { name: String(sub.name), arguments: typeof sub.arguments === 'string' ? sub.arguments : JSON.stringify(sub.arguments) }
-                }
-            ];
-        }
-    }
-    // Case 4: XML tool calls — used by Qwen, Hermes, and other models whose chat
-    // templates emit <tool_call><function=name><parameter=key>value</parameter></function></tool_call>.
-    // When llama-server's XML→JSON conversion fails (common with large write_file content),
-    // the raw XML leaks into the content field. This recovers it.
-    const xmlCalls = parseXmlToolCalls(trimmed);
-    if (xmlCalls?.length)
-        return xmlCalls;
-    // Case 5: Lightweight function-tag calls (seen in some Qwen content-mode outputs):
-    // <function=tool_name>
-    // {...json args...}
-    // </function>
-    // or single-line <function=tool_name>{...}</function>
-    const fnTagCalls = parseFunctionTagToolCalls(trimmed);
-    if (fnTagCalls?.length)
-        return fnTagCalls;
-    return null;
-}
-/**
- * Parse XML-style tool calls from content.
- * Format: <tool_call><function=name><parameter=key>value</parameter>...</function></tool_call>
- * Handles multiple tool call blocks and arbitrary parameter names/values.
- */
-function parseXmlToolCalls(content) {
-    // Quick bailout: no point parsing if there's no <tool_call> marker
-    if (!content.includes('<tool_call>'))
-        return null;
-    const calls = [];
-    // Match each <tool_call>...</tool_call> block.
-    // Using a manual scan instead of a single greedy regex to handle nested angle brackets
-    // in parameter values (e.g. TypeScript generics, JSX, comparison operators).
-    let searchFrom = 0;
-    while (searchFrom < content.length) {
-        const blockStart = content.indexOf('<tool_call>', searchFrom);
-        if (blockStart === -1)
-            break;
-        const blockEnd = content.indexOf('</tool_call>', blockStart);
-        if (blockEnd === -1)
-            break; // Truncated — can't recover partial tool calls
-        const block = content.slice(blockStart + '<tool_call>'.length, blockEnd);
-        searchFrom = blockEnd + '</tool_call>'.length;
-        // Extract function name: <function=name>...</function>
-        const fnMatch = block.match(/<function=(\w[\w.-]*)>/);
-        if (!fnMatch)
-            continue;
-        const fnName = fnMatch[1];
-        const fnStart = block.indexOf(fnMatch[0]) + fnMatch[0].length;
-        const fnEnd = block.lastIndexOf('</function>');
-        const fnBody = fnEnd !== -1 ? block.slice(fnStart, fnEnd) : block.slice(fnStart);
-        // Extract parameters: <parameter=key>value</parameter>
-        // Uses bracket-matching (depth counting) so that parameter values containing
-        // literal <parameter=...>...</parameter> (e.g. writing XML files) are handled
-        // correctly instead of being truncated at the inner close tag.
-        const args = {};
-        const openRe = /<parameter=(\w[\w.-]*)>/g;
-        const closeTag = '</parameter>';
-        let paramMatch;
-        while ((paramMatch = openRe.exec(fnBody)) !== null) {
-            const paramName = paramMatch[1];
-            const valueStart = paramMatch.index + paramMatch[0].length;
-            // Bracket-match: find the </parameter> that balances this open tag.
-            // Depth starts at 1; nested <parameter=...> increments, </parameter> decrements.
-            let depth = 1;
-            let scanPos = valueStart;
-            let closeIdx = -1;
-            while (scanPos < fnBody.length && depth > 0) {
-                const nextOpen = fnBody.indexOf('<parameter=', scanPos);
-                const nextClose = fnBody.indexOf(closeTag, scanPos);
-                if (nextClose === -1)
-                    break; // No more close tags — truncated
-                if (nextOpen !== -1 && nextOpen < nextClose) {
-                    // An open tag comes before the next close — increase depth
-                    depth++;
-                    scanPos = nextOpen + 1; // advance past '<' to avoid re-matching
-                }
-                else {
-                    // Close tag comes first — decrease depth
-                    depth--;
-                    if (depth === 0) {
-                        closeIdx = nextClose;
-                    }
-                    scanPos = nextClose + closeTag.length;
-                }
-            }
-            if (closeIdx === -1) {
-                // No matching close tag — take rest of body as value (truncated output)
-                args[paramName] = fnBody.slice(valueStart).trim();
-                break;
-            }
-            // Trim exactly the template-added leading/trailing newline, preserve internal whitespace
-            let value = fnBody.slice(valueStart, closeIdx);
-            if (value.startsWith('\n'))
-                value = value.slice(1);
-            if (value.endsWith('\n'))
-                value = value.slice(0, -1);
-            args[paramName] = value;
-            // Advance the regex past the close tag so the next openRe.exec starts after it
-            openRe.lastIndex = closeIdx + closeTag.length;
-        }
-        if (fnName && Object.keys(args).length > 0) {
-            calls.push({
-                id: `call_xml_${calls.length}`,
-                type: 'function',
-                function: {
-                    name: fnName,
-                    arguments: JSON.stringify(args)
-                }
-            });
-        }
-    }
-    return calls.length > 0 ? calls : null;
-}
-/** Check for missing required params by tool name — universal pre-dispatch validation */
-function getMissingRequiredParams(toolName, args) {
-    const required = {
-        read_file: ['path'],
-        read_files: ['requests'],
-        write_file: ['path', 'content'],
-        edit_file: ['path', 'old_text', 'new_text'],
-        insert_file: ['path', 'line', 'text'],
-        list_dir: ['path'],
-        search_files: ['pattern', 'path'],
-        exec: ['command'],
-        spawn_task: ['task'],
-        sys_context: [],
-        vault_search: ['query'],
-        vault_note: ['key', 'value']
-    };
-    const req = required[toolName];
-    if (!req)
-        return [];
-    return req.filter(p => args[p] === undefined || args[p] === null);
-}
-/** Strip markdown code fences (```json ... ```) from tool argument strings */
-function stripMarkdownFences(s) {
-    const trimmed = s.trim();
-    // Match ```json\n...\n``` or ```\n...\n```
-    const m = /^```(?:json)?\s*\n?([\s\S]*?)\n?```\s*$/.exec(trimmed);
-    return m ? m[1] : s;
-}
 function isReadOnlyTool(name) {
     return name === 'read_file' || name === 'read_files' || name === 'list_dir' || name === 'search_files' || name === 'vault_search' || name === 'sys_context';
 }
@@ -804,6 +425,10 @@ function planModeSummary(name, args) {
     switch (name) {
         case 'write_file':
             return `write ${args.path ?? 'unknown'} (${typeof args.content === 'string' ? args.content.split('\n').length : '?'} lines)`;
+        case 'apply_patch':
+            return `apply patch to ${Array.isArray(args.files) ? args.files.length : '?'} file(s)`;
+        case 'edit_range':
+            return `edit ${args.path ?? 'unknown'} lines ${args.start_line ?? '?'}-${args.end_line ?? '?'}`;
         case 'edit_file':
             return `edit ${args.path ?? 'unknown'} (replace ${typeof args.old_text === 'string' ? args.old_text.split('\n').length : '?'} lines)`;
         case 'insert_file':
@@ -838,148 +463,6 @@ function userDisallowsDelegation(content) {
         /\b(?:spawn[_\-\s]?task|sub[\-\s]?agents?|delegate|delegation)\b[^\n.]{0,50}\b(?:do not|don't|dont|not allowed|forbidden|no)\b/.test(text);
     return negationNearDelegation;
 }
-function reviewArtifactKeys(projectDir) {
-    const { projectId } = projectIndexKeys(projectDir);
-    return {
-        projectId,
-        latestKey: `artifact:review:latest:${projectId}`,
-        byIdPrefix: `artifact:review:item:${projectId}:`,
-    };
-}
-function looksLikeCodeReviewRequest(text) {
-    const t = text.toLowerCase();
-    if (!t.trim())
-        return false;
-    if (/^\s*\/review\b/.test(t))
-        return true;
-    if (/\b(?:code\s+review|security\s+review|review\s+the\s+(?:code|diff|changes|repo|repository|pr)|audit\s+the\s+code)\b/.test(t))
-        return true;
-    return /\breview\b/.test(t) && /\b(?:code|repo|repository|diff|changes|pull\s*request|pr)\b/.test(t);
-}
-function looksLikeReviewRetrievalRequest(text) {
-    const t = text.toLowerCase();
-    if (!t.trim())
-        return false;
-    if (/^\s*\/review\s+(?:print|show|replay|latest|last|full)\b/.test(t))
-        return true;
-    if (!/\breview\b/.test(t))
-        return false;
-    if (/\bprint\s+stale\s+review\s+anyway\b/.test(t))
-        return true;
-    if (/\b(?:print|show|display|repeat|paste|send|output|give)\b[^\n.]{0,80}\breview\b[^\n.]{0,40}\b(?:again|back)\b/.test(t))
-        return true;
-    if (/\b(?:print|show|display|repeat|paste|send|output|give)\b[^\n.]{0,80}\b(?:full|entire|complete|whole)\b[^\n.]{0,80}\breview\b/.test(t))
-        return true;
-    if (/\b(?:full|entire|complete|whole)\b[^\n.]{0,30}\bcode\s+review\b/.test(t) && /\b(?:print|show|display|repeat|paste|send|output|give)\b/.test(t))
-        return true;
-    if (/\b(?:print|show|display|repeat|paste|send|output|give)\b[^\n.]{0,80}\b(?:last|latest|previous)\b[^\n.]{0,40}\breview\b/.test(t))
-        return true;
-    return false;
-}
-function retrievalAllowsStaleArtifact(text) {
-    const t = text.toLowerCase();
-    if (!t.trim())
-        return false;
-    if (/\bprint\s+stale\s+review\s+anyway\b/.test(t))
-        return true;
-    if (/\b(?:force|override|ignore)\b[^\n.]{0,80}\b(?:stale|old|previous)\b[^\n.]{0,80}\breview\b/.test(t))
-        return true;
-    if (/\b(?:stale|old|previous)\b[^\n.]{0,80}\breview\b[^\n.]{0,80}\b(?:anyway|still|force|override|ignore)\b/.test(t))
-        return true;
-    return false;
-}
-function parseReviewArtifactStalePolicy(raw) {
-    const v = typeof raw === 'string' ? raw.toLowerCase().trim() : '';
-    if (v === 'block')
-        return 'block';
-    return 'warn';
-}
-function parseReviewArtifact(raw) {
-    try {
-        const parsed = JSON.parse(raw);
-        if (!parsed || typeof parsed !== 'object')
-            return null;
-        if (parsed.kind !== 'code_review')
-            return null;
-        if (typeof parsed.id !== 'string' || !parsed.id)
-            return null;
-        if (typeof parsed.createdAt !== 'string' || !parsed.createdAt)
-            return null;
-        if (typeof parsed.model !== 'string')
-            return null;
-        if (typeof parsed.projectId !== 'string' || !parsed.projectId)
-            return null;
-        if (typeof parsed.projectDir !== 'string' || !parsed.projectDir)
-            return null;
-        if (typeof parsed.prompt !== 'string')
-            return null;
-        if (typeof parsed.content !== 'string')
-            return null;
-        return parsed;
-    }
-    catch {
-        return null;
-    }
-}
-function gitHead(cwd) {
-    const inside = spawnSync(BASH, ['-lc', 'git rev-parse --is-inside-work-tree'], {
-        cwd,
-        encoding: 'utf8',
-        timeout: 1000,
-    });
-    if (inside.status !== 0 || !String(inside.stdout || '').trim().startsWith('true'))
-        return undefined;
-    const head = spawnSync(BASH, ['-lc', 'git rev-parse HEAD'], {
-        cwd,
-        encoding: 'utf8',
-        timeout: 1000,
-    });
-    if (head.status !== 0)
-        return undefined;
-    const sha = String(head.stdout || '').trim();
-    return sha || undefined;
-}
-function shortSha(sha) {
-    if (!sha)
-        return 'unknown';
-    return sha.slice(0, 8);
-}
-function reviewArtifactStaleReason(artifact, cwd) {
-    const currentHead = gitHead(cwd);
-    const currentDirty = isGitDirty(cwd);
-    if (artifact.gitHead && currentHead && artifact.gitHead !== currentHead) {
-        return `Stored review was generated at commit ${shortSha(artifact.gitHead)}; repository is now at ${shortSha(currentHead)}.`;
-    }
-    if (artifact.gitDirty === false && currentDirty) {
-        return 'Stored review was generated on a clean tree; working tree now has uncommitted changes.';
-    }
-    return '';
-}
-function normalizeModelsResponse(raw) {
-    if (Array.isArray(raw)) {
-        return {
-            data: raw
-                .map((m) => {
-                if (!m)
-                    return null;
-                if (typeof m === 'string')
-                    return { id: m };
-                if (typeof m.id === 'string' && m.id)
-                    return m;
-                return null;
-            })
-                .filter(Boolean)
-        };
-    }
-    if (raw && Array.isArray(raw.data)) {
-        return {
-            data: raw.data
-                .map((m) => (m && typeof m.id === 'string' && m.id ? m : null))
-                .filter(Boolean)
-        };
-    }
-    return { data: [] };
-}
 export async function createSession(opts) {
     const cfg = opts.config;
     let client = opts.runtime?.client ?? new OpenAIClient(cfg.endpoint, opts.apiKey, cfg.verbose);
@@ -989,6 +472,15 @@ export async function createSession(opts) {
     if (typeof cfg.response_timeout === 'number' && cfg.response_timeout > 0) {
         client.setResponseTimeout(cfg.response_timeout);
     }
+    if (typeof client.setConnectionTimeout === 'function' && typeof cfg.connection_timeout === 'number' && cfg.connection_timeout > 0) {
+        client.setConnectionTimeout(cfg.connection_timeout);
+    }
+    if (typeof client.setInitialConnectionCheck === 'function' && typeof cfg.initial_connection_check === 'boolean') {
+        client.setInitialConnectionCheck(cfg.initial_connection_check);
+    }
+    if (typeof client.setInitialConnectionProbeTimeout === 'function' && typeof cfg.initial_connection_timeout === 'number' && cfg.initial_connection_timeout > 0) {
+        client.setInitialConnectionProbeTimeout(cfg.initial_connection_timeout);
+    }
     // Health check + model list (cheap, avoids wasting GPU on chat warmups if unreachable)
     let modelsList = normalizeModelsResponse(await client.models().catch(() => null));
     let model = cfg.model && cfg.model.trim().length
@@ -1004,6 +496,44 @@ export async function createSession(opts) {
         modelMeta,
     });
     let supportsVision = supportsVisionModel(model, modelMeta, harness);
+    const sessionId = `session-${timestampedId()}`;
+    const hookCfg = cfg.hooks ?? {};
+    const hookManager = opts.runtime?.hookManager ?? new HookManager({
+        enabled: hookCfg.enabled !== false,
+        strict: hookCfg.strict === true,
+        warnMs: hookCfg.warn_ms,
+        allowedCapabilities: Array.isArray(hookCfg.allow_capabilities) ? hookCfg.allow_capabilities : undefined,
+        context: () => ({
+            sessionId,
+            cwd: cfg.dir ?? process.cwd(),
+            model,
+            harness: harness.id,
+            endpoint: cfg.endpoint,
+        }),
+    });
+    const emitDetached = (promise, eventName) => {
+        void promise.catch((error) => {
+            if (!process.env.IDLEHANDS_QUIET_WARNINGS) {
+                console.warn(`[hooks] async ${eventName} dispatch failed: ${error?.message ?? String(error)}`);
+            }
+        });
+    };
+    if (!opts.runtime?.hookManager && hookManager.isEnabled()) {
+        const loadedPlugins = await loadHookPlugins({
+            pluginPaths: Array.isArray(hookCfg.plugin_paths) ? hookCfg.plugin_paths : [],
+            cwd: cfg.dir ?? process.cwd(),
+            strict: hookCfg.strict === true,
+        });
+        for (const loaded of loadedPlugins) {
+            await hookManager.registerPlugin(loaded.plugin, loaded.path);
+        }
+    }
+    await hookManager.emit('session_start', {
+        model,
+        harness: harness.id,
+        endpoint: cfg.endpoint,
+        cwd: cfg.dir ?? process.cwd(),
+    });
     if (!cfg.i_know_what_im_doing && contextWindow > 131072) {
         console.warn('[warn] context_window is above 131072; this can increase memory usage and hurt throughput. Use --i-know-what-im-doing to proceed.');
     }
@@ -1034,7 +564,7 @@ export async function createSession(opts) {
         ? Number(cfg.mcp_call_timeout_sec)
         : (Number.isFinite(cfg.mcp?.call_timeout_sec) ? Number(cfg.mcp?.call_timeout_sec) : 30);
     const builtInToolNames = [
-        'read_file', 'read_files', 'write_file', 'edit_file', 'insert_file',
+        'read_file', 'read_files', 'write_file', 'apply_patch', 'edit_range', 'edit_file', 'insert_file',
         'list_dir', 'search_files', 'exec', 'vault_search', 'vault_note', 'sys_context',
         ...(spawnTaskEnabled ? ['spawn_task'] : []),
     ];
@@ -1276,6 +806,7 @@ export async function createSession(opts) {
         ];
         sessionMetaPending = sessionMeta;
         lastEditedPath = undefined;
+        initialConnectionProbeDone = false;
         mcpToolsLoaded = !mcpLazySchemaMode;
     };
     const restore = (next) => {
@@ -1298,6 +829,7 @@ export async function createSession(opts) {
     };
     let reqCounter = 0;
     let inFlight = null;
+    let initialConnectionProbeDone = false;
     let lastEditedPath;
     // Plan mode state (Phase 8)
     let planSteps = [];
@@ -1798,6 +1330,7 @@ export async function createSession(opts) {
         return fresh.data.map((m) => m.id).filter(Boolean);
     };
     const setModel = (name) => {
+        const previousModel = model;
         model = name;
         harness = selectHarness(model, cfg.harness && cfg.harness.trim() ? cfg.harness.trim() : undefined);
         const nextMeta = modelsList?.data?.find((m) => m.id === model);
@@ -1815,6 +1348,11 @@ export async function createSession(opts) {
             configuredTopP: cfg.top_p,
             baseMaxTokens: BASE_MAX_TOKENS,
         }));
+        emitDetached(hookManager.emit('model_changed', {
+            previousModel,
+            nextModel: model,
+            harness: harness.id,
+        }), 'model_changed');
     };
     const setEndpoint = async (endpoint, modelName) => {
         const normalized = endpoint.replace(/\/+$/, '');
@@ -2002,11 +1540,49 @@ export async function createSession(opts) {
         const hookObj = typeof hooks === 'function' ? { onToken: hooks } : hooks ?? {};
         let turns = 0;
         let toolCalls = 0;
+        const askId = `ask-${timestampedId()}`;
+        const emitToolCall = async (call) => {
+            hookObj.onToolCall?.(call);
+            await hookManager.emit('tool_call', { askId, turn: turns, call });
+        };
+        const emitToolStream = (stream) => {
+            try {
+                void hookObj.onToolStream?.(stream);
+            }
+            catch {
+                // best effort
+            }
+            try {
+                void hookManager.emit('tool_stream', { askId, turn: turns, stream });
+            }
+            catch {
+                // best effort
+            }
+        };
+        const emitToolResult = async (result) => {
+            await hookObj.onToolResult?.(result);
+            await hookManager.emit('tool_result', { askId, turn: turns, result });
+        };
+        const emitTurnEnd = async (stats) => {
+            await hookObj.onTurnEnd?.(stats);
+            await hookManager.emit('turn_end', { askId, stats });
+        };
+        const finalizeAsk = async (text) => {
+            await hookManager.emit('ask_end', { askId, text, turns, toolCalls });
+            return { text, turns, toolCalls };
+        };
         const rawInstructionText = userContentToText(instruction).trim();
+        await hookManager.emit('ask_start', { askId, instruction: rawInstructionText });
         const projectDir = cfg.dir ?? process.cwd();
         const reviewKeys = reviewArtifactKeys(projectDir);
         const retrievalRequested = looksLikeReviewRetrievalRequest(rawInstructionText);
         const shouldPersistReviewArtifact = looksLikeCodeReviewRequest(rawInstructionText) && !retrievalRequested;
+        if (!retrievalRequested && cfg.initial_connection_check !== false && !initialConnectionProbeDone) {
+            if (typeof client.probeConnection === 'function') {
+                await client.probeConnection();
+                initialConnectionProbeDone = true;
+            }
+        }
         if (retrievalRequested) {
             const latest = vault
                 ? await vault.getLatestByKey(reviewKeys.latestKey, 'system').catch(() => null)
@@ -2023,37 +1599,37 @@ export async function createSession(opts) {
                         'Reply with "print stale review anyway" to override, or request a fresh review.';
                     messages.push({ role: 'assistant', content: blocked });
                     hookObj.onToken?.(blocked);
-                    await hookObj.onTurnEnd?.({
+                    await emitTurnEnd({
                         turn: turns,
                         toolCalls,
                         promptTokens: cumulativeUsage.prompt,
                         completionTokens: cumulativeUsage.completion,
                     });
-                    return { text: blocked, turns, toolCalls };
+                    return await finalizeAsk(blocked);
                 }
                 const text = stale
                     ? `${artifact.content}\n\n[artifact note] ${stale}`
                     : artifact.content;
                 messages.push({ role: 'assistant', content: text });
                 hookObj.onToken?.(text);
-                await hookObj.onTurnEnd?.({
+                await emitTurnEnd({
                     turn: turns,
                     toolCalls,
                     promptTokens: cumulativeUsage.prompt,
                     completionTokens: cumulativeUsage.completion,
                 });
-                return { text, turns, toolCalls };
+                return await finalizeAsk(text);
             }
             const miss = 'No stored full code review found yet. Ask me to run a code review first, then I can replay it verbatim.';
             messages.push({ role: 'assistant', content: miss });
             hookObj.onToken?.(miss);
-            await hookObj.onTurnEnd?.({
+            await emitTurnEnd({
                 turn: turns,
                 toolCalls,
                 promptTokens: cumulativeUsage.prompt,
                 completionTokens: cumulativeUsage.completion,
             });
-            return { text: miss, turns, toolCalls };
+            return await finalizeAsk(miss);
         }
         const persistReviewArtifact = async (finalText) => {
             if (!vault || !shouldPersistReviewArtifact)
@@ -2062,7 +1638,7 @@ export async function createSession(opts) {
             if (!clean)
                 return;
             const createdAt = new Date().toISOString();
-            const id = `review-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
+            const id = `review-${timestampedId()}`;
             const artifact = {
                 id,
                 kind: 'code_review',
@@ -2098,6 +1674,7 @@ export async function createSession(opts) {
         // identical tool call signature counts across this ask() run
         const sigCounts = new Map();
         const toolNameByCallId = new Map();
+        const toolArgsByCallId = new Map();
         // Loop-break helper state: bump mutationVersion whenever a tool mutates files.
         // We also record the mutationVersion at which a given signature was last seen.
         let mutationVersion = 0;
@@ -2139,6 +1716,42 @@ export async function createSession(opts) {
             }
             return msg;
         };
+        const compactToolMessageForHistory = async (toolCallId, rawContent) => {
+            const toolName = toolNameByCallId.get(toolCallId) ?? 'tool';
+            const toolArgs = toolArgsByCallId.get(toolCallId) ?? {};
+            const rawMsg = { role: 'tool', tool_call_id: toolCallId, content: rawContent };
+            // Persist full-fidelity output immediately so live context can stay small.
+            if (vault && typeof vault.archiveToolResult === 'function') {
+                try {
+                    await vault.archiveToolResult(rawMsg, toolName);
+                }
+                catch (e) {
+                    console.warn(`[warn] vault archive failed: ${e instanceof Error ? e.message : String(e)}`);
+                }
+            }
+            let compact = rawContent;
+            if (lens) {
+                try {
+                    const lensCompact = await lens.summarizeToolOutput(rawContent, toolName, typeof toolArgs.path === 'string' ? String(toolArgs.path) : undefined);
+                    if (typeof lensCompact === 'string' && lensCompact.length && lensCompact.length < compact.length) {
+                        compact = lensCompact;
+                    }
+                }
+                catch {
+                    // ignore lens failures; fallback to raw
+                }
+            }
+            const success = !String(rawContent).startsWith('ERROR:');
+            const digested = digestToolResult(toolName, toolArgs, compact, success);
+            if (digested !== rawContent) {
+                return {
+                    role: 'tool',
+                    tool_call_id: toolCallId,
+                    content: `${digested}\n[full output archived in vault: tool=${toolName}, call_id=${toolCallId}]`,
+                };
+            }
+            return rawMsg;
+        };
         const persistFailure = async (error, contextLine) => {
             if (!vault)
                 return;
@@ -2193,13 +1806,13 @@ export async function createSession(opts) {
                 if (inFlight?.signal?.aborted)
                     break;
                 turns++;
+                await hookManager.emit('turn_start', { askId, turn: turns });
                 const wallElapsed = (Date.now() - wallStart) / 1000;
                 if (wallElapsed > cfg.timeout) {
                     throw new Error(`session timeout exceeded (${cfg.timeout}s) after ${wallElapsed.toFixed(1)}s`);
                 }
                 await maybeAutoDetectModelChange();
                 const beforeMsgs = messages;
-                const beforeTokens = estimateTokensFromMessages(beforeMsgs);
                 const compacted = enforceContextBudget({
                     messages: beforeMsgs,
                     contextWindow,
@@ -2208,7 +1821,6 @@ export async function createSession(opts) {
                     compactAt: cfg.compact_at ?? 0.8,
                     toolSchemaTokens: estimateToolSchemaTokens(getToolsSchema()),
                 });
-                const compactedDropped = beforeMsgs.length > compacted.length || estimateTokensFromMessages(compacted) < beforeTokens;
                 const compactedByRefs = new Set(compacted);
                 const dropped = beforeMsgs.filter((m) => !compactedByRefs.has(m));
                 if (dropped.length && vault) {
@@ -2233,9 +1845,9 @@ export async function createSession(opts) {
                 const callerSignal = hookObj.signal;
                 const onCallerAbort = () => ac.abort();
                 callerSignal?.addEventListener('abort', onCallerAbort, { once: true });
-                // Per-request timeout: the lesser of response_timeout (default 300s) or the remaining session wall time.
+                // Per-request timeout: the lesser of response_timeout (default 600s) or the remaining session wall time.
                 // This prevents a single slow request from consuming the entire session budget.
-                const perReqCap = cfg.response_timeout && cfg.response_timeout > 0 ? cfg.response_timeout : 300;
+                const perReqCap = cfg.response_timeout && cfg.response_timeout > 0 ? cfg.response_timeout : 600;
                 const wallRemaining = Math.max(0, cfg.timeout - (Date.now() - wallStart) / 1000);
                 const reqTimeout = Math.min(perReqCap, Math.max(10, wallRemaining));
                 const timer = setTimeout(() => ac.abort(), reqTimeout * 1000);
@@ -2389,7 +2001,7 @@ export async function createSession(opts) {
                         role: 'user',
                         content: '[system] Your previous response was empty (no text, no tool calls). Continue by either calling a tool with valid JSON arguments or giving a final answer.',
                     });
-                    await hookObj.onTurnEnd?.({
+                    await emitTurnEnd({
                         turn: turns,
                         toolCalls,
                         promptTokens: cumulativeUsage.prompt,
@@ -2451,7 +2063,11 @@ export async function createSession(opts) {
                     if (visible && hookObj.onToken)
                         hookObj.onToken('\n');
                     toolCalls += toolCallsArr.length;
-                    messages.push({ role: 'assistant', content: visible || '', tool_calls: toolCallsArr });
+                    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 });
                     // 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.
@@ -2574,7 +2190,7 @@ export async function createSession(opts) {
                                 `Hint: you repeated the same tool call ${loopThreshold} times with identical arguments. ` +
                                 `If the call succeeded, move on to the next step. ` +
                                 `If it failed, check that all required parameters are present and correct. ` +
-                                `For write_file/edit_file, ensure 'content'/'old_text'/'new_text' are included as strings.`);
+                                `For write_file/edit_file/apply_patch/edit_range, ensure required args are present (content/old_text/new_text/patch/files/start_line/end_line/replacement).`);
                         }
                     }
                     // Update consecutive tracking: save this turn's signatures for next turn comparison.
@@ -2603,6 +2219,8 @@ export async function createSession(opts) {
                         const hasMcpTool = mcpManager?.hasTool(name) === true;
                         if (!builtInFn && !isLspTool && !hasMcpTool && !isSpawnTask)
                             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 : {});
                         // Pre-dispatch check for missing required params.
                         // Universal: catches omitted params early with a clear, instructive error
                         // before the tool itself throws a less helpful message.
@@ -2638,8 +2256,8 @@ export async function createSession(opts) {
                             const searchTerm = typeof args.search === 'string' ? args.search : '';
                             // Fix 1: Hard cumulative budget — refuse reads past hard cap
                             if (cumulativeReadOnlyCalls > READ_BUDGET_HARD) {
-                                hookObj.onToolCall?.({ id: callId, name, args });
-                                hookObj.onToolResult?.({ id: callId, name, success: false, summary: 'read budget exhausted', result: '' });
+                                await emitToolCall({ id: callId, name, args });
+                                await emitToolResult({ id: callId, name, success: false, summary: 'read budget exhausted', result: '' });
                                 return { id: callId, content: `STOP: Read budget exhausted (${cumulativeReadOnlyCalls}/${READ_BUDGET_HARD} calls). Do NOT read more files. Use search_files or exec: grep -rn "pattern" path/ to find what you need.` };
                             }
                             // Fix 2: Directory scan detection — counts unique files per dir (re-reads are OK)
@@ -2654,8 +2272,8 @@ export async function createSession(opts) {
                                     blockedDirs.add(parentDir);
                                 }
                                 if (blockedDirs.has(parentDir) && uniqueCount > 8) {
-                                    hookObj.onToolCall?.({ id: callId, name, args });
-                                    hookObj.onToolResult?.({ id: callId, name, success: false, summary: 'dir scan blocked', result: '' });
+                                    await emitToolCall({ id: callId, name, args });
+                                    await emitToolResult({ id: callId, name, success: false, summary: 'dir scan blocked', result: '' });
                                     return { id: callId, content: `STOP: Directory scan detected — you've read ${uniqueCount} unique files from ${parentDir}/. Use search_files(pattern, '${parentDir}') or exec: grep -rn "pattern" ${parentDir}/ instead of reading files individually.` };
                                 }
                             }
@@ -2666,8 +2284,8 @@ export async function createSession(opts) {
                                     searchTermFiles.set(key, new Set());
                                 searchTermFiles.get(key).add(filePath);
                                 if (searchTermFiles.get(key).size >= 3) {
-                                    hookObj.onToolCall?.({ id: callId, name, args });
-                                    hookObj.onToolResult?.({ id: callId, name, success: false, summary: 'use search_files', result: '' });
+                                    await emitToolCall({ id: callId, name, args });
+                                    await emitToolResult({ id: callId, name, success: false, summary: 'use search_files', result: '' });
                                     return { id: callId, content: `STOP: You've searched ${searchTermFiles.get(key).size} files for "${searchTerm}" one at a time. This is what search_files does in one call. Use: search_files(pattern="${searchTerm}", path=".") or exec: grep -rn "${searchTerm}" .` };
                                 }
                             }
@@ -2689,12 +2307,12 @@ export async function createSession(opts) {
                             // Notify via confirmProvider.showBlocked if available
                             opts.confirmProvider?.showBlocked?.({ tool: name, args, reason: `plan mode: ${summary}` });
                             // Hook: onToolCall + onToolResult for plan-blocked actions
-                            hookObj.onToolCall?.({ id: callId, name, args });
-                            hookObj.onToolResult?.({ id: callId, name, success: true, summary: `⏸ ${summary} (blocked)`, result: blockedMsg });
+                            await emitToolCall({ id: callId, name, args });
+                            await emitToolResult({ id: callId, name, success: true, summary: `⏸ ${summary} (blocked)`, result: blockedMsg });
                             return { id: callId, content: blockedMsg };
                         }
                         // Hook: onToolCall (Phase 8.5)
-                        hookObj.onToolCall?.({ id: callId, name, args });
+                        await emitToolCall({ id: callId, name, args });
                         if (cfg.step_mode) {
                             const stepPrompt = `Step mode: execute ${name}(${JSON.stringify(args).slice(0, 200)}) ? [Y/n]`;
                             const ok = confirmBridge ? await confirmBridge(stepPrompt, { tool: name, args }) : true;
@@ -2717,7 +2335,13 @@ export async function createSession(opts) {
                                 content = await runSpawnTask(args);
                             }
                             else if (builtInFn) {
-                                const value = await builtInFn(ctx, args);
+                                const callCtx = {
+                                    ...ctx,
+                                    toolCallId: callId,
+                                    toolName: name,
+                                    onToolStream: emitToolStream,
+                                };
+                                const value = await builtInFn(callCtx, args);
                                 content = typeof value === 'string' ? value : JSON.stringify(value);
                                 if (name === 'exec') {
                                     // Successful exec clears blocked-loop counters.
@@ -2815,7 +2439,7 @@ export async function createSession(opts) {
                             }
                             catch { }
                         }
-                        hookObj.onToolResult?.(resultEvent);
+                        await emitToolResult(resultEvent);
                         // Proactive LSP diagnostics after file mutations
                         if (lspManager?.hasServers() && lspCfg?.proactive_diagnostics !== false) {
                             if (FILE_MUTATION_TOOL_SET.has(name)) {
@@ -2843,7 +2467,7 @@ export async function createSession(opts) {
                     };
                     const results = [];
                     // Helper: catch tool errors but re-throw AgentLoopBreak (those must break the outer loop)
-                    const catchToolError = (e, tc) => {
+                    const catchToolError = async (e, tc) => {
                         if (e instanceof AgentLoopBreak)
                             throw e;
                         const msg = e?.message ?? String(e);
@@ -2877,7 +2501,7 @@ export async function createSession(opts) {
                         }
                         // Hook: onToolResult for errors (Phase 8.5)
                         const callId = resolveCallId(tc);
-                        hookObj.onToolResult?.({ id: callId, name: tc.function.name, success: false, summary: msg || 'unknown error', result: `ERROR: ${msg || 'unknown error'}` });
+                        await emitToolResult({ id: callId, name: tc.function.name, success: false, summary: msg || 'unknown error', result: `ERROR: ${msg || 'unknown error'}` });
                         // Never return undefined error text; it makes bench failures impossible to debug.
                         return { id: callId, content: `ERROR: ${msg || 'unknown tool error'}` };
                     };
@@ -2916,7 +2540,7 @@ export async function createSession(opts) {
                                 results.push(await runOne(tc));
                             }
                             catch (e) {
-                                results.push(catchToolError(e, tc));
+                                results.push(await catchToolError(e, tc));
                             }
                         }
                     }
@@ -2930,7 +2554,7 @@ export async function createSession(opts) {
                                 results.push(await runOne(tc));
                             }
                             catch (e) {
-                                results.push(catchToolError(e, tc));
+                                results.push(await catchToolError(e, tc));
                             }
                         }
                     }
@@ -2938,7 +2562,8 @@ export async function createSession(opts) {
                     if (ac.signal.aborted)
                         break;
                     for (const r of results) {
-                        messages.push({ role: 'tool', tool_call_id: r.id, content: r.content });
+                        const compactToolMsg = await compactToolMessageForHistory(r.id, r.content);
+                        messages.push(compactToolMsg);
                     }
                     if (readOnlyExecTurnHints.length) {
                         const previews = readOnlyExecTurnHints
@@ -2972,7 +2597,7 @@ export async function createSession(opts) {
                         });
                     }
                     // Hook: onTurnEnd (Phase 8.5)
-                    await hookObj.onTurnEnd?.({
+                    await emitTurnEnd({
                         turn: turns,
                         toolCalls,
                         promptTokens: cumulativeUsage.prompt,
@@ -3015,7 +2640,7 @@ export async function createSession(opts) {
                                     `Original task:\n${clippedReminder}\n\n` +
                                     `Call the needed tools directly. If everything is truly complete, provide the final answer.`
                             });
-                            await hookObj.onTurnEnd?.({
+                            await emitTurnEnd({
                                 turn: turns,
                                 toolCalls,
                                 promptTokens: cumulativeUsage.prompt,
@@ -3035,7 +2660,7 @@ export async function createSession(opts) {
                         role: 'user',
                         content: '[system] Continue executing the task. Use tools now (do not just narrate plans). If complete, give the final answer.'
                     });
-                    await hookObj.onTurnEnd?.({
+                    await emitTurnEnd({
                         turn: turns,
                         toolCalls,
                         promptTokens: cumulativeUsage.prompt,
@@ -3053,7 +2678,7 @@ export async function createSession(opts) {
                 // final assistant message
                 messages.push({ role: 'assistant', content: assistantText });
                 await persistReviewArtifact(assistantText).catch(() => { });
-                await hookObj.onTurnEnd?.({
+                await emitTurnEnd({
                     turn: turns,
                     toolCalls,
                     promptTokens: cumulativeUsage.prompt,
@@ -3065,7 +2690,7 @@ export async function createSession(opts) {
                     ppTps,
                     tgTps,
                 });
-                return { text: assistantText, turns, toolCalls };
+                return await finalizeAsk(assistantText);
             }
             const reason = `max iterations exceeded (${maxIters})`;
             const diag = lastSuccessfulTestRun
@@ -3091,6 +2716,12 @@ export async function createSession(opts) {
                 })();
                 const err = new Error(`BUG: threw undefined in agent.ask() (turn=${turns}). lastMsg=${lastMsg?.role ?? 'unknown'}:${lastMsgPreview}`);
                 await persistFailure(err, `ask turn ${turns}`);
+                await hookManager.emit('ask_error', {
+                    askId,
+                    error: err.message,
+                    turns,
+                    toolCalls,
+                });
                 throw err;
             }
             await persistFailure(e, `ask turn ${turns}`);
@@ -3100,8 +2731,21 @@ export async function createSession(opts) {
             }
             // Never rethrow undefined; normalize to Error for debuggability.
             if (e === undefined) {
-                throw new Error('BUG: threw undefined (normalized at ask() boundary)');
+                const normalized = new Error('BUG: threw undefined (normalized at ask() boundary)');
+                await hookManager.emit('ask_error', {
+                    askId,
+                    error: normalized.message,
+                    turns,
+                    toolCalls,
+                });
+                throw normalized;
             }
+            await hookManager.emit('ask_error', {
+                askId,
+                error: e instanceof Error ? e.message : String(e),
+                turns,
+                toolCalls,
+            });
             throw e;
         }
     };
@@ -3148,6 +2792,7 @@ export async function createSession(opts) {
         replay,
         vault,
         lens,
+        hookManager,
         get lastEditedPath() {
             return lastEditedPath;
         },
@@ -3192,30 +2837,4 @@ async function autoPickModel(client, cached) {
         clearTimeout(timer);
     }
 }
-function parseFunctionTagToolCalls(content) {
-    const m = content.match(/<function=([\w.-]+)>([\s\S]*?)<\/function>/i);
-    if (!m)
-        return null;
-    const name = m[1];
-    const body = (m[2] ?? '').trim();
-    // If body contains JSON object, use it as arguments; else empty object.
-    let args = '{}';
-    const jsonStart = body.indexOf('{');
-    const jsonEnd = body.lastIndexOf('}');
-    if (jsonStart !== -1 && jsonEnd > jsonStart) {
-        const sub = body.slice(jsonStart, jsonEnd + 1);
-        try {
-            JSON.parse(sub);
-            args = sub;
-        }
-        catch {
-            // keep {}
-        }
-    }
-    return [{
-            id: 'call_0',
-            type: 'function',
-            function: { name, arguments: args }
-        }];
-}
 //# sourceMappingURL=agent.js.map