@visorcraft/idlehands 1.1.7 → 1.1.9

package/dist/agent.js

@@ -14,123 +14,19 @@ 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, getArgValidationIssues, stripMarkdownFences } from './agent/tool-calls.js';
+import { ToolError, ValidationError } from './tools/tool-error.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)
@@ -160,6 +56,24 @@ function looksLikeReadOnlyExecCommand(command) {
         return true;
     return false;
 }
+function execRcShouldSignalFailure(command) {
+    const cmd = String(command || '').toLowerCase();
+    if (!cmd)
+        return false;
+    // Common checks where non-zero usually means real failure.
+    if (/\b(?:npm|pnpm|yarn)\s+(?:run\s+)?(?:test|build|lint|typecheck|check)\b/.test(cmd))
+        return true;
+    if (/\bnode\s+--test\b/.test(cmd))
+        return true;
+    if (/\b(?:pytest|go\s+test|cargo\s+test|ctest|mvn\s+test|gradle\s+test)\b/.test(cmd))
+        return true;
+    if (/\b(?:cargo\s+build|go\s+build|tsc\b)\b/.test(cmd))
+        return true;
+    // Grep/rg no-match rc=1 should not be treated as failure.
+    if (/^\s*(?:rg|grep|ag|ack)\b/.test(cmd))
+        return false;
+    return false;
+}
 function withCachedExecObservationHint(content) {
     if (!content)
         return content;
@@ -188,6 +102,14 @@ function readOnlyExecCacheable(content) {
         return false;
     }
 }
+function ensureInformativeAssistantText(text, ctx) {
+    if (String(text ?? '').trim())
+        return text;
+    if (ctx.toolCalls > 0) {
+        return 'I completed the requested tool work, but I have no user-visible response text yet. Ask me to summarize what was done.';
+    }
+    return `I have no user-visible response text for this turn (turn=${ctx.turns}). Please try again or rephrase your request.`;
+}
 /** Errors that should break the outer agent loop, not be caught by per-tool handlers */
 class AgentLoopBreak extends Error {
     constructor(message) {
@@ -203,7 +125,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.
@@ -230,7 +152,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;
@@ -246,66 +168,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
@@ -385,155 +247,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) {
@@ -544,54 +406,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'])
             }
         });
     }
@@ -600,203 +444,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';
 }
@@ -805,6 +452,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':
@@ -839,148 +490,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);
@@ -1014,7 +523,7 @@ export async function createSession(opts) {
         modelMeta,
     });
     let supportsVision = supportsVisionModel(model, modelMeta, harness);
-    const sessionId = `session-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
+    const sessionId = `session-${timestampedId()}`;
     const hookCfg = cfg.hooks ?? {};
     const hookManager = opts.runtime?.hookManager ?? new HookManager({
         enabled: hookCfg.enabled !== false,
@@ -1082,7 +591,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'] : []),
     ];
@@ -2058,11 +1567,25 @@ export async function createSession(opts) {
         const hookObj = typeof hooks === 'function' ? { onToken: hooks } : hooks ?? {};
         let turns = 0;
         let toolCalls = 0;
-        const askId = `ask-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
+        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 });
@@ -2072,8 +1595,9 @@ export async function createSession(opts) {
             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 finalText = ensureInformativeAssistantText(text, { toolCalls, turns });
+            await hookManager.emit('ask_end', { askId, text: finalText, turns, toolCalls });
+            return { text: finalText, turns, toolCalls };
         };
         const rawInstructionText = userContentToText(instruction).trim();
         await hookManager.emit('ask_start', { askId, instruction: rawInstructionText });
@@ -2142,7 +1666,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',
@@ -2178,6 +1702,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;
@@ -2187,6 +1712,8 @@ export async function createSession(opts) {
         let lastTurnSigs = new Set();
         const consecutiveCounts = new Map();
         let malformedCount = 0;
+        let toolRepairAttempts = 0;
+        const MAX_TOOL_REPAIR_ATTEMPTS = 1;
         let noProgressTurns = 0;
         const NO_PROGRESS_TURN_CAP = 3;
         let noToolTurns = 0;
@@ -2219,6 +1746,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, _tool_call_id: toolCallId }, 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;
@@ -2280,7 +1843,6 @@ export async function createSession(opts) {
                 }
                 await maybeAutoDetectModelChange();
                 const beforeMsgs = messages;
-                const beforeTokens = estimateTokensFromMessages(beforeMsgs);
                 const compacted = enforceContextBudget({
                     messages: beforeMsgs,
                     contextWindow,
@@ -2289,7 +1851,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) {
@@ -2532,7 +2093,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.
@@ -2655,7 +2220,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.
@@ -2676,7 +2241,10 @@ export async function createSession(opts) {
                                 // Break the outer loop — this model won't self-correct
                                 throw new AgentLoopBreak(`tool ${name}: malformed JSON exceeded retry limit (${harness.toolCalls.retryOnMalformed}): ${rawArgs.slice(0, 200)}`);
                             }
-                            throw new Error(`tool ${name}: arguments not valid JSON: ${rawArgs.slice(0, 200)}`);
+                            throw new ToolError('invalid_args', `tool ${name}: arguments not valid JSON`, false, 'Return a valid JSON object for function.arguments.', { raw: rawArgs.slice(0, 200) });
+                        }
+                        if (args == null || typeof args !== 'object' || Array.isArray(args)) {
+                            throw new ValidationError([{ field: 'arguments', message: 'must be a JSON object', value: args }]);
                         }
                         const builtInFn = tools[name];
                         const isLspTool = LSP_TOOL_NAME_SET.has(name);
@@ -2684,13 +2252,20 @@ export async function createSession(opts) {
                         const hasMcpTool = mcpManager?.hasTool(name) === true;
                         if (!builtInFn && !isLspTool && !hasMcpTool && !isSpawnTask)
                             throw new Error(`unknown tool: ${name}`);
-                        // 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.
+                        // 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 argument validation.
+                        // - Required params
+                        // - Type/range/enums
+                        // - Unknown properties
                         if (builtInFn || isSpawnTask) {
                             const missing = getMissingRequiredParams(name, args);
                             if (missing.length) {
-                                throw new Error(`REQUIRED parameter(s) ${missing.map(p => `'${p}'`).join(', ')} missing. You MUST include ${missing.join(', ')} in every ${name} call.`);
+                                throw new ValidationError(missing.map((m) => ({ field: m, message: 'required parameter is missing', value: undefined })));
+                            }
+                            const argIssues = getArgValidationIssues(name, args);
+                            if (argIssues.length) {
+                                throw new ValidationError(argIssues.map((i) => ({ field: i.field, message: i.message, value: i.value })));
                             }
                         }
                         // ── Pre-dispatch safety screening (Phase 9) ──
@@ -2798,7 +2373,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.
@@ -2862,7 +2443,8 @@ export async function createSession(opts) {
                             }
                         }
                         // Hook: onToolResult (Phase 8.5 + Phase 7 rich display)
-                        const summary = reusedCachedReadOnlyExec
+                        let toolSuccess = true;
+                        let summary = reusedCachedReadOnlyExec
                             ? 'cached read-only exec observation (unchanged)'
                             : toolResultSummary(name, args, content, true);
                         const resultEvent = { id: callId, name, success: true, summary, result: content };
@@ -2872,6 +2454,14 @@ export async function createSession(opts) {
                                 const parsed = JSON.parse(content);
                                 if (parsed.out)
                                     resultEvent.execOutput = parsed.out;
+                                const rc = Number(parsed?.rc ?? NaN);
+                                if (Number.isFinite(rc)) {
+                                    resultEvent.execRc = rc;
+                                    const cmd = String(args?.command ?? '');
+                                    if (execRcShouldSignalFailure(cmd) && rc !== 0) {
+                                        toolSuccess = false;
+                                    }
+                                }
                             }
                             catch { }
                         }
@@ -2896,6 +2486,10 @@ export async function createSession(opts) {
                             }
                             catch { }
                         }
+                        resultEvent.success = toolSuccess;
+                        if (!toolSuccess && name === 'exec' && typeof resultEvent.execRc === 'number') {
+                            resultEvent.summary = `rc=${resultEvent.execRc} (command failed)`;
+                        }
                         await emitToolResult(resultEvent);
                         // Proactive LSP diagnostics after file mutations
                         if (lspManager?.hasServers() && lspCfg?.proactive_diagnostics !== false) {
@@ -2923,11 +2517,19 @@ export async function createSession(opts) {
                         return { id: callId, content };
                     };
                     const results = [];
+                    let invalidArgsThisTurn = false;
                     // Helper: catch tool errors but re-throw AgentLoopBreak (those must break the outer loop)
                     const catchToolError = async (e, tc) => {
                         if (e instanceof AgentLoopBreak)
                             throw e;
-                        const msg = e?.message ?? String(e);
+                        const te = e instanceof ToolError || e instanceof ValidationError
+                            ? e
+                            : ToolError.fromError(e, 'internal');
+                        if (te.code === 'invalid_args' || te.code === 'validation') {
+                            invalidArgsThisTurn = true;
+                        }
+                        const msg = te.message ?? String(e ?? 'unknown error');
+                        const toolErrorContent = te instanceof ValidationError ? te.toToolResult() : te.toToolResult();
                         // Fast-fail repeated blocked command loops with accurate reason labeling.
                         // Applies to direct exec attempts and spawn_task delegation attempts.
                         if (tc.function.name === 'exec' || tc.function.name === 'spawn_task') {
@@ -2956,11 +2558,17 @@ export async function createSession(opts) {
                                 }
                             }
                         }
-                        // Hook: onToolResult for errors (Phase 8.5)
                         const callId = resolveCallId(tc);
-                        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'}` };
+                        await emitToolResult({
+                            id: callId,
+                            name: tc.function.name,
+                            success: false,
+                            summary: `${te.code}: ${msg}`.slice(0, 240),
+                            errorCode: te.code,
+                            retryable: te.retryable,
+                            result: toolErrorContent,
+                        });
+                        return { id: callId, content: toolErrorContent };
                     };
                     // ── Anti-scan guardrails (§ read budget, dir scan, same-search) ──
                     const readOnlyInTurn = toolCallsArr.filter((tc) => isReadOnlyToolDynamic(tc.function.name));
@@ -2998,6 +2606,10 @@ export async function createSession(opts) {
                             }
                             catch (e) {
                                 results.push(await catchToolError(e, tc));
+                                if (FILE_MUTATION_TOOL_SET.has(tc.function.name)) {
+                                    // Fail-fast: after mutating tool failure, stop the remaining batch.
+                                    break;
+                                }
                             }
                         }
                     }
@@ -3012,6 +2624,10 @@ export async function createSession(opts) {
                             }
                             catch (e) {
                                 results.push(await catchToolError(e, tc));
+                                if (FILE_MUTATION_TOOL_SET.has(tc.function.name)) {
+                                    // Fail-fast: after mutating tool failure, stop the remaining batch.
+                                    break;
+                                }
                             }
                         }
                     }
@@ -3019,7 +2635,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
@@ -3052,6 +2669,15 @@ export async function createSession(opts) {
                             content: `[System] ⚠ Read budget: ${cumulativeReadOnlyCalls}/${READ_BUDGET_HARD}. ${remaining} reads remaining before hard stop. Use search_files or exec grep — do NOT continue reading files one at a time.`,
                         });
                     }
+                    // One bounded automatic repair attempt for invalid tool args.
+                    if (invalidArgsThisTurn && toolRepairAttempts < MAX_TOOL_REPAIR_ATTEMPTS) {
+                        toolRepairAttempts++;
+                        messages.push({
+                            role: 'user',
+                            content: '[system] Your previous tool call failed argument validation. Re-issue a corrected tool_calls array only. ' +
+                                'Do not narrate. Fix required/mistyped fields and unknown keys.',
+                        });
+                    }
                     // Hook: onTurnEnd (Phase 8.5)
                     await emitTurnEnd({
                         turn: turns,
@@ -3131,9 +2757,10 @@ export async function createSession(opts) {
                     continue;
                 }
                 noToolTurns = 0;
+                const assistantOutput = ensureInformativeAssistantText(assistantText, { toolCalls, turns });
                 // final assistant message
-                messages.push({ role: 'assistant', content: assistantText });
-                await persistReviewArtifact(assistantText).catch(() => { });
+                messages.push({ role: 'assistant', content: assistantOutput });
+                await persistReviewArtifact(assistantOutput).catch(() => { });
                 await emitTurnEnd({
                     turn: turns,
                     toolCalls,
@@ -3146,7 +2773,7 @@ export async function createSession(opts) {
                     ppTps,
                     tgTps,
                 });
-                return await finalizeAsk(assistantText);
+                return await finalizeAsk(assistantOutput);
             }
             const reason = `max iterations exceeded (${maxIters})`;
             const diag = lastSuccessfulTestRun
@@ -3293,30 +2920,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