loom-agent 1.3.2 → 1.5.0

package/src/core/session.js

@@ -71,15 +71,34 @@ function isAbortError(err) {
   return /aborted|cancel(led|ed)/i.test(String(err.message || ''));
 }
 
+// Rate-limit errors — transient (429 / overloaded): wait and retry rather
+// than switching models. Checked BEFORE isQuotaError so a 429 never triggers
+// a spurious model switch.
+function isRateLimitError(err) {
+  if (!err) return false;
+  const status = Number(err.status || err.code || err.error?.status || 0);
+  if (status === 429 || status === 529) return true;
+  const msg = String(err.message || err.error?.message || '');
+  return /rate.?limit|too many requests|overloaded/i.test(msg);
+}
+
 // Quota/credits exhausted errors — the model is out of tokens (free tiers,
 // daily limits, billing caps). These are switch-to-another-model triggers.
+// Rate-limit wording is deliberately NOT matched here (see isRateLimitError).
 function isQuotaError(err) {
   if (!err) return false;
   const status = Number(err.status || err.code || err.error?.status || 0);
   if (status === 402) return true;
-  if (status === 429) return true;
   const msg = String(err.message || err.error?.message || err.body?.error?.message || '');
-  return /quota|exhausted|insufficient.{0,20}(balance|credits|quota)|out of (tokens|credits|balance)|no (more )?(tokens|credits|balance)|rate.?limit|billing limit|payment required|max.?quota|limit reached/i.test(msg);
+  return /quota|exhausted|insufficient.{0,20}(balance|credits|quota)|out of (tokens|credits|balance)|no (more )?(tokens|credits|balance)|billing limit|payment required|max.?quota|limit reached/i.test(msg);
+}
+
+// Context-overflow errors — the prompt exceeded the model window. Compacting
+// the conversation and retrying is the correct recovery (not a model switch).
+function isContextOverflowError(err) {
+  if (!err) return false;
+  const msg = String(err.message || err.error?.message || err.body?.error?.message || '');
+  return /prompt is too long|context_length_exceeded|input length.{0,40}maximum length|request_too_large|too many tokens|maximum context length|reduce the length/i.test(msg);
 }
 
 class Session {
@@ -93,6 +112,8 @@ class Session {
     this.tokensUsed = 0;
     this.tokensIn = 0;
     this.tokensOut = 0;
+    this.cacheReadTokens = 0;
+    this.cacheWriteTokens = 0;
     this.sessionCost = 0;
     this.permissions = new PermissionManager();
     // OpenCode-style permission tree (config.permission + config.agent.<id>.permission).
@@ -218,6 +239,7 @@ class Session {
     const plat = require('./platform').detect();
     const shell = plat.platform === 'win32' ? 'PowerShell 5.1' : 'bash/zsh';
     const hasWSL = plat.isWSL ? ' (WSL)' : '';
+    const hasTools = this.mode === 'build' || this.mode === 'plan';
     return `You are Loom, a terminal coding agent: fast, terse, action-first.
 
 ## Environment
@@ -228,41 +250,43 @@ class Session {
 
 ## Memory (from LOOM.md)
 ${memory}
-
+${hasTools ? `
 When the user states a durable preference, correction, or project fact ("we use bun", "never touch X", "deploy via Y"), persist it yourself: append ONE dated bullet under the "## Remembered" heading of ./LOOM.md using the edit tool (create the heading if missing). Keep it terse; don't ask permission for obvious preferences. Don't store secrets or one-off task details.
-
+` : ''}${this.mode === 'build' ? `
 ## Skills
 ${this.loadSkills()}
-
+` : ''}
 ## Behavior
 - Decide before acting: if the answer needs no external data, reply directly with ZERO tool calls. Simple or conversational questions are answered in one message, nothing runs.
-- When tools ARE needed, act first and batch independent calls (e.g., read a file, grep a symbol, glob files at once). Never call tools speculatively or one at a time when they can be batched.
+${hasTools ? `- When tools ARE needed, act first and batch independent calls (e.g., read a file, grep a symbol, glob files at once). Never call tools speculatively or one at a time when they can be batched.
 - Never call a time/date tool or a sequential-thinking tool — today's date is already in Environment, and you never need to "think" via a tool.
 - Extended thinking is ON when your model supports it: reason BEFORE you act and re-evaluate AFTER every tool result. For complex or multi-step tasks, think hard at each stage (plan → act → check) instead of rushing to the answer — this is what separates a good result from a guessed one.
-- Be terse in the final reply: say what changed and nothing else.
+` : ''}- Be terse in the final reply: say what changed and nothing else.
 - Never narrate ("I will now read the file…"). Just call the tool.
-- Prefer edits over full-file writes when the change is small.
+${this.mode === 'build' ? `- Prefer edits over full-file writes when the change is small.
 - After writing code, run any test/bench command the user has relied on if one exists.
-
+` : ''}
 ## Formatting
 - ALWAYS reply in Markdown. The terminal renders it with colors, so make every reply structured and readable:
 - Use **bold** for key terms and important results, \`inline code\` for file paths, symbols and commands, and fenced \`\`\` blocks for any code or config.
 - Use ## headings and - bullet lists to organize longer replies; keep code inside fenced blocks, never inline dumps.
 - Even one-line answers should still use markdown inline styling where it helps (e.g. "Done — **rewrote** \`src/app.ts\`: \`+12 -4\` lines, tests **pass**.").
 - Never reply with a wall of plain unstyled text — the user's UI highlights markdown, and raw text renders as a single flat color.
-- Multi-step work MUST be tracked with the todowrite tool (the UI mirrors it live in a sidebar and in the chat): call it up front with the task list, update item statuses (pending/in_progress/completed/cancelled) as you work, and call it one last time when done. Keep the list items terse ("Fix signup bug", not prose).
-
+${this.mode === 'build' ? `- Multi-step work MUST be tracked with the todowrite tool (the UI mirrors it live in a sidebar and in the chat): call it up front with the task list, update item statuses (pending/in_progress/completed/cancelled) as you work, and call it one last time when done. Keep the list items terse ("Fix signup bug", not prose).
+` : ''}
 ## Hard rules
-- Batch independent tool calls into a single response; never send one tool call at a time.
+${hasTools ? `- Batch independent tool calls into a single response; never send one tool call at a time.
 - You may only issue multiple tool calls if none of them depends on another's result.
 - Never guess a tool result — read it before your next call.
-- Never commit/push without explicit instruction. Never print API keys.
-- When a tool FAILS, do not retry the same call with the same arguments. After the first failure, change the approach: e.g. use read/grep to understand the state before trying an edit again, run a simpler variant of the command, or ask the user for the missing input (API key, path, permission). Three same-goal failures == stop and escalate: say what failed and suggest the fix instead of looping.
-- For long outputs (links, large files), stream whatever the tool gave you in one message — do not emit partial/truncated responses piecemeal.
-
+` : ''}- Never commit/push without explicit instruction. Never print API keys.
+${hasTools ? `- When a tool FAILS, do not retry the same call with the same arguments. After the first failure, change the approach: e.g. use read/grep to understand the state before trying an edit again, run a simpler variant of the command, or ask the user for the missing input (API key, path, permission). Three same-goal failures == stop and escalate: say what failed and suggest the fix instead of looping.
+` : ''}
+${this.mode === 'plan' ? `- For long outputs (links, large files), stream whatever the tool gave you in one message — do not emit partial/truncated responses piecemeal.
+` : ''}
 ## Mode
 You are in ${this.mode === 'build' ? 'BUILD MODE (full agent)' : this.mode === 'plan' ? 'PLAN MODE (read-only analysis)' : 'CHAT MODE (conversation only)'}.
 ${this.mode === 'build' ? `- You have all tools available: read, write, edit, bash, glob, grep, webfetch, and MCP tools.
+- bash runs on the user's machine. When isolation is genuinely needed (the user asked for the sandbox, or the command is risky/Linux-only), run it INSIDE Docker instead: the \`sandbox\` tool, or bash with sandbox:true — both execute via \`docker exec loom-sandbox sh -lc "<command>"\`. Never run a sandbox-intended command on the host, and never for ordinary commands.
 - Inspect, edit, and verify the result yourself end-to-end.
 - When done, summarize in 1-2 sentences.` : ''}${this.mode === 'plan' ? `- Read-only tools only: read, glob, grep, webfetch, todowrite. No MCP tools.
 - Investigate thoroughly, then output a "## Plan" with ordered steps (exact file path + what changes each step makes). No narration.` : ''}${this.mode === 'chat' ? `- No tools available; answer conversationally.
@@ -282,6 +306,19 @@ ${this.mode === 'build' ? `- You have all tools available: read, write, edit, ba
     return '\n\n## Acting as the "' + agent.name + '" agent\n' + agent.prompt + '\n';
   }
 
+  // Dynamic Docker-sandbox line, resolved lazily per turn (like _primaryBlock)
+  // so /sandbox setup / on / off apply to the NEXT turn without rebuilding the
+  // base prompt. Config-only read — never spawns docker (no TUI freezes).
+  _sandboxBlock() {
+    if (this.mode !== 'build') return '';
+    let ready = false;
+    try { ready = require('./sandbox').shouldUseSandbox(); } catch { return ''; }
+    if (!ready) return '';
+    return '\n\n## Sandbox (Docker, ready)\n'
+      + '- The loom-sandbox container is set up. When the user asks to run something "in the sandbox", or isolation is genuinely needed, run the command through `docker exec loom-sandbox sh -lc "<command>"` (workdir /workspace) — i.e. the `sandbox` tool, or bash with sandbox:true. NEVER run a sandbox-intended command directly on the host instead.\n'
+      + '- Ordinary commands stay on the host via plain bash (or bash with sandbox omitted).\n';
+  }
+
   // Create ./LOOM.md with a template when missing, so memory exists from the
   // first turn (Claude Code behavior). Disable with LOOM_MEM_AUTO=0 (tests).
   ensureMemoryFile() {
@@ -324,14 +361,53 @@ ${this.mode === 'build' ? `- You have all tools available: read, write, edit, ba
       if (!skills.length) return '(No skills installed. Run /skills to see options.)';
       // Compact index only — full instructions are injected per-turn by the
       // skill matcher when the user's message matches a skill's keywords.
+      // Descriptions are capped so one verbose skill can't bloat the system
+      // prompt (and its cache prefix) on every turn.
       return skills
-        .map((s) => `- ${s.name} (${s.source}): ${s.description || 'no description'}`)
+        .map((s) => {
+          let d = s.description || 'no description';
+          if (d.length > 80) d = d.slice(0, 77).trimEnd() + '…';
+          return `- ${s.name}: ${d}`;
+        })
         .join('\n');
     } catch (e) {
       return '(Skills unavailable: ' + e.message + ')';
     }
   }
 
+  // Cache-stable system prompt: the per-turn skill block is the ONLY part of
+  // the system prefix that changes between turns. Keeping it out of the system
+  // string (injected into the last user message instead) means Anthropic's
+  // system-prompt cache_control breakpoint stays byte-identical across turns
+  // even when a different skill matches, so cache reads keep hitting.
+  // Resolves the lazy primary/sandbox blocks once and caches them on
+  // _resolvedPrimary/_resolvedSandbox so estimateTokens sees the same strings
+  // that go out on the request.
+  _systemPrefix() {
+    this._resolvedPrimary = this._primaryBlock();
+    this._resolvedSandbox = this._sandboxBlock();
+    return this.systemPrompt + (this._agentBlock || '') + this._resolvedPrimary + this._resolvedSandbox;
+  }
+
+  // Older tool results are elided to a head+tail slice before they reach the
+  // provider. Kept in-memory verbatim for the TUI; only the payload shrinks.
+  // Keep the most recent TOOL_RESULT_RECENT messages untouched so the cache
+  // prefix and the model's working set stay stable.
+  ageHistory(messages) {
+    const AGE_HEAD = 2000, AGE_TAIL = 400, RECENT = 12;
+    if (!messages || messages.length <= RECENT) return messages;
+    const cutoff = messages.length - RECENT;
+    return messages.map((m, i) => {
+      if (i >= cutoff || m.role !== 'tool') return m;
+      const text = typeof m.content === 'string' ? m.content : (m.content == null ? '' : JSON.stringify(m.content));
+      if (text.length <= AGE_HEAD + AGE_TAIL + 60) return m;
+      return Object.assign({}, m, {
+        content: text.slice(0, AGE_HEAD) + '\n[…older tool result elided — re-read the file if still needed…]\n' + text.slice(-AGE_TAIL),
+        _aged: true,
+      });
+    });
+  }
+
   interrupt() {
     this.interrupted = true;
     if (this.abortController) this.abortController.abort();
@@ -367,6 +443,9 @@ ${this.mode === 'build' ? `- You have all tools available: read, write, edit, ba
     // trigger a refresh. Re-reading disk and re-init'ing the provider on every
     // message was noticeable overhead per turn.
     this.interrupted = false;
+    // Restored/compacted sessions may carry a history whose first row isn't
+    // a user message — Anthropic rejects that shape. Normalize once here.
+    this._normalizeHistory();
 
     // Skill auto-trigger: if the user's message mentions a skill keyword
     // (e.g. "slice", "gcode", "cad"), load the matched skill's instructions
@@ -391,6 +470,18 @@ ${this.mode === 'build' ? `- You have all tools available: read, write, edit, ba
       this._skillBlock = '';
     }
 
+    // userPromptSubmit hook: may veto the prompt outright, or inject extra
+    // context (lint output, ticket data) appended to the user's message.
+    try {
+      const gate = await hooks.runHook('userPromptSubmit', { prompt: text });
+      if (gate.blocked) {
+        return { type: 'error', content: 'Prompt blocked by userPromptSubmit hook.' + (gate.reason ? ' ' + gate.reason : '') };
+      }
+      if (gate.additionalContext) {
+        text = text + '\n\n<user-prompt-submit-hook>\n' + gate.additionalContext + '\n</user-prompt-submit-hook>';
+      }
+    } catch {}
+
     this.addMessage({ role: 'user', content: text });
     this.turnCount++;
     const turnAgent = this.agent?.id || null;
@@ -467,13 +558,24 @@ ${this.mode === 'build' ? `- You have all tools available: read, write, edit, ba
 
   // ─── Compaction ───
   // Rough token estimate from message text (chars/4) — used to decide when
-  // the context window is getting full.
+  // the context window is getting full. Includes the system prompt and the
+  // serialized tool schemas: with many MCP tools those can be tens of
+  // thousands of tokens that a messages-only estimate ignores.
   estimateTokens() {
     let chars = 0;
     for (const m of this.messages) {
       chars += String(m.content || '').length;
       for (const tc of m.toolCalls || []) chars += JSON.stringify(tc.input || {}).length;
     }
+    chars += String(this.systemPrompt || '').length;
+    chars += this._toolSchemaChars || 0;
+    // Per-turn system-prompt suffixes (agent/primary/sandbox) + the skill
+    // block ride on top of this.systemPrompt — include them or the estimate
+    // under-counts exactly the parts that grow the request.
+    chars += (this._agentBlock || '').length;
+    chars += (this._resolvedPrimary || '').length;
+    chars += (this._resolvedSandbox || '').length;
+    chars += (this._skillBlock || '').length;
     return Math.ceil(chars / 4);
   }
 
@@ -482,15 +584,39 @@ ${this.mode === 'build' ? `- You have all tools available: read, write, edit, ba
     return meta?.context || 200000;
   }
 
+  // Live context estimate for the /context TUI command: tokens (messages +
+  // system prompt + tool schemas), window size, and percent used. Recomputed
+  // on every call so it reflects the CURRENT conversation, not a startup
+  // snapshot.
+  contextEstimate() {
+    const tokens = this.estimateTokens();
+    const window = this.getContextWindow();
+    return { tokens, window, pct: Math.min(100, Math.round((tokens / window) * 100)) };
+  }
+
   shouldCompact() {
     if (this.messages.length < COMPACT_MIN_MESSAGES) return false;
     const threshold = this.config.compactThreshold ?? COMPACT_DEFAULT_THRESHOLD;
     return this.estimateTokens() > this.getContextWindow() * threshold;
   }
 
+  // Ensure a compacted/resumed history starts with a user message — Anthropic
+  // rejects conversations whose first row is assistant/tool. Called after
+  // compaction and at the start of each user turn (covers restored sessions).
+  _normalizeHistory() {
+    if (!this.messages.length || this.messages[0].role === 'user') return;
+    let start = 0;
+    while (start < this.messages.length && this.messages[start].role !== 'user') start++;
+    if (start >= this.messages.length) return; // no user row — leave alone
+    this.messages = this.messages.slice(start);
+  }
+
   // Real compaction: summarize the older messages with the model and keep the
   // most recent COMPACT_KEEP_MESSAGES verbatim. Falls back to truncation when
-  // no provider/key is available or the summary call fails.
+  // no provider/key is available or the summary call fails. The summary is
+  // stored as a USER-role row (not system): openai-compat drops history rows
+  // with role 'system', which silently discarded the summary on every
+  // non-Anthropic provider.
   async compact(callbacks = {}) {
     if (this.messages.length <= COMPACT_KEEP_MESSAGES + 2) {
       return { compacted: false, reason: 'conversation too short', removed: 0, method: 'none' };
@@ -522,9 +648,10 @@ ${this.mode === 'build' ? `- You have all tools available: read, write, edit, ba
 
     if (summary) {
       this.messages = [
-        { role: 'system', content: '[Compacted — earlier conversation summarized. Ask for details if you need specifics.]\n\n' + summary.slice(0, 8000) },
+        { role: 'user', content: '[Compacted — earlier conversation summarized. Ask for details if you need specifics.]\n\n' + summary.slice(0, 8000) },
         ...keep,
       ];
+      this._normalizeHistory();
       this.compactCount = (this.compactCount || 0) + 1;
       this.lastCompact = { at: Date.now(), method: 'summary', removed: head.length };
       if (callbacks.onCompact) callbacks.onCompact({ method: 'summary', removed: head.length, summary });
@@ -533,9 +660,10 @@ ${this.mode === 'build' ? `- You have all tools available: read, write, edit, ba
 
     // Fallback: drop the oldest messages, keep the recent tail verbatim.
     this.messages = [
-      { role: 'system', content: `[Compacted — ${head.length} earlier messages truncated. Ask for details if you need specifics.]` },
+      { role: 'user', content: `[Compacted — ${head.length} earlier messages truncated. Ask for details if you need specifics.]` },
       ...keep,
     ];
+    this._normalizeHistory();
     this.compactCount = (this.compactCount || 0) + 1;
     this.lastCompact = { at: Date.now(), method: 'truncate', removed: head.length };
     if (callbacks.onCompact) callbacks.onCompact({ method: 'truncate', removed: head.length, summary: null });
@@ -607,21 +735,55 @@ ${this.mode === 'build' ? `- You have all tools available: read, write, edit, ba
     let todowroteThisTurn = false;
     // Transient provider-error retry state.
     let providerRetries = 0;
+    // Reactive compaction already fired this turn (context-overflow 400).
+    let compactedThisTurn = false;
+    // Mid-turn compaction already fired this turn.
+    let compactedMidTurn = false;
     while (true) {
       if (this.interrupted) {
         return finishInterrupted();
       }
 
+      // Mid-turn compaction: a long tool loop can fill the window well past
+      // the threshold — compact before the next model call instead of dying
+      // with a context-overflow error.
+      if (ranTools && !compactedMidTurn && !this.interrupted && this.shouldCompact()) {
+        compactedMidTurn = true;
+        try {
+          const res = await this.compact(callbacks);
+          if (res.compacted && callbacks.onAutoCompact) callbacks.onAutoCompact(res);
+        } catch {}
+      }
+
       let resp;
       speed._turnStart = Date.now();
       speed._firstTokenAt = 0;
       speed._liveTokens = 0;
       try {
         resp = await this.getResponse(cb);
+        // Success: reset the transient-retry budget so one slow tool step
+        // doesn't consume a retry reserved for real failures.
+        providerRetries = 0;
       } catch (err) {
         if (isAbortError(err)) {
           return finishInterrupted();
         }
+        // Rate limit / overload: WAIT and retry (honor Retry-After when the
+        // provider sent one). Model switching on a 429 wastes the wait — the
+        // same limit usually applies across the account.
+        if (isRateLimitError(err)) {
+          if (providerRetries < PROVIDER_RETRIES) {
+            providerRetries++;
+            const waitMs = Math.min(
+              (err && err.retryAfterMs) || 1000 * Math.pow(2, providerRetries - 1),
+              30000
+            );
+            await new Promise((resolve) => setTimeout(resolve, waitMs));
+            if (this.interrupted) return finishInterrupted();
+            continue;
+          }
+          // Waited enough — fall through to a model switch as a last resort.
+        }
         // Model ran out of tokens → auto-switch to another model and retry once.
         if (isQuotaError(err)) {
           const fromKey = (this.provider.active?.name || '?') + '/' + (this.config.model?.[this.provider.active?.name] || '?');
@@ -633,6 +795,19 @@ ${this.mode === 'build' ? `- You have all tools available: read, write, edit, ba
             continue;
           }
         }
+        // Context overflow (prompt too long): compact and retry once per
+        // turn. This is the recovery path when the auto-compact threshold
+        // was missed (huge tool results, MCP schema growth mid-session).
+        if (isContextOverflowError(err) && !compactedThisTurn && this.messages.length > 10) {
+          compactedThisTurn = true;
+          try {
+            const res = await this.compact(callbacks);
+            if (res.compacted) {
+              if (callbacks.onAutoCompact) callbacks.onAutoCompact(res);
+              continue;
+            }
+          } catch {}
+        }
         // Transient provider failure (network blip, 5xx, stream reset): retry
         // the model call a couple of times instead of killing the turn
         // mid-task. No tools ran for this iteration, so a retry is side-effect
@@ -753,7 +928,7 @@ ${this.mode === 'build' ? `- You have all tools available: read, write, edit, ba
           : [];
         // Safety net: after all continuation budgets are spent, a
         // finish_reason=length reply still gets the explanatory placeholder
-        // instead of mystery silence.
+        // instead of mystery silence.
         const truncHint = resp.finishReason === 'length'
           ? '(the reply hit the max-tokens limit mid-stream — the model ran out of output budget before writing any text. Raise maxTokens in config, or /think off to free the thinking budget)'
           : '(the model ended the turn without any text)';
@@ -803,11 +978,15 @@ ${this.mode === 'build' ? `- You have all tools available: read, write, edit, ba
         // results flow through the TUI popup; doom_loop/external_directory
         // are checked separately where they apply.
         const permKey = { read:'read', edit:'edit', write:'edit', glob:'glob', grep:'grep', bash:'bash',
-                          task:'task', skill:'skill', lsp:'lsp', question:'question', ask:'question', webfetch:'webfetch',
-                          websearch:'websearch', browser:'browser' }[tc.name];
+                          sandbox:'bash', task:'task', skill:'skill', lsp:'lsp', question:'question', ask:'question', webfetch:'webfetch',
+                          websearch:'websearch', browser:'browser', todoread:'read' }[tc.name]
+                          || (tc.name.indexOf('mcp__') === 0 ? 'mcp' : undefined);
         const isMcpAdd = tc.name === 'mcp' && tc.input && tc.input.action === 'add';
         if (permKey || isMcpAdd) {
-          const arg = this.permissions.permissionArg(tc.name, tc.input || {});
+          // MCP tool calls are gated by the 'mcp' permission key with the
+          // FULL tool name as the pattern arg (mcp__github__search), so the
+          // user can allow exactly one server/tool.
+          const arg = permKey === 'mcp' ? tc.name : this.permissions.permissionArg(tc.name, tc.input || {});
           let action = this.permissions.resolve(tc.name, arg);
           // mcp add spawns arbitrary stdio servers with optional env secrets —
           // always ask unless the user saved a rule for the exact command.
@@ -849,7 +1028,7 @@ ${this.mode === 'build' ? `- You have all tools available: read, write, edit, ba
         // The permission gate above is the interactive check; mark the command
         // as approved so the tool-layer safety filter doesn't double-block
         // commands the user explicitly allowed.
-        const input = (tc.name === 'bash' || isMcpAdd) ? { ...tc.input, _approved: true } : tc.input;
+        const input = (tc.name === 'bash' || tc.name === 'sandbox' || isMcpAdd) ? { ...tc.input, _approved: true } : tc.input;
         // preToolUse hook: a user-configured command may veto this call.
         try {
           const gate = await hooks.runHook('preToolUse', { tool: tc.name, input: tc.input });
@@ -869,14 +1048,21 @@ ${this.mode === 'build' ? `- You have all tools available: read, write, edit, ba
             try { if (callbacks.onToolOutput) callbacks.onToolOutput(tc, chunk, kind); } catch {}
           },
         });
-        // postToolUse hook (informational — never blocks).
-        try { await hooks.runHook('postToolUse', { tool: tc.name, input: tc.input }); } catch {}
+        // postToolUse hook (informational — never blocks). tool_response lets
+        // audit hooks see what the tool actually returned (truncated to keep
+        // the hook's stdin small).
+        try {
+          const respText = outcome.error ? `Error: ${outcome.error}` : String(outcome.result ?? '');
+          await hooks.runHook('postToolUse', { tool: tc.name, input: tc.input, tool_response: respText.slice(0, 4000) });
+        } catch {}
         return { tc, outcome };
       }));
 
       for (const { tc, outcome } of outcomes) {
         const text = outcome.error ? `Error: ${outcome.error}` : String(outcome.result ?? '');
-        this.addMessage({ role: 'tool', toolCallId: tc.id, content: text });
+        // isError marks failed tool calls so Anthropic tool_results carry
+        // is_error:true (the model treats the text as an error report).
+        this.addMessage({ role: 'tool', toolCallId: tc.id, content: text, isError: !!outcome.error });
         // Persist real todo state when the model uses the todowrite tool.
         if (tc.name === 'todowrite' && !outcome.error) {
           todowroteThisTurn = true;
@@ -894,6 +1080,9 @@ ${this.mode === 'build' ? `- You have all tools available: read, write, edit, ba
     const tools = await getAllToolDefinitions(this.mode);
     // Agent-scoped turns (delegation) see only their agent's tool list.
     const toolDefs = this.agent ? filterToolDefs(this.agent, tools) : tools;
+    // Track schema size for estimateTokens — many MCP tools can add tens of
+    // thousands of tokens that a messages-only estimate ignores.
+    this._toolSchemaChars = toolDefs && toolDefs.length ? JSON.stringify(toolDefs).length : 0;
 
     // Budget router: when a level is active (free/cheap/best), pick the model
     // for THIS call without rewriting the user's saved provider/model. "Free"
@@ -951,7 +1140,7 @@ ${this.mode === 'build' ? `- You have all tools available: read, write, edit, ba
       maxTokens: this.config.maxTokens || 8192,
       temperature: this.config.temperature ?? 0.7,
       tools: toolDefs,
-      system: this.systemPrompt + (this._skillBlock || '') + (this._agentBlock || '') + this._primaryBlock(),
+      system: this._systemPrefix(),
       signal: this.abortController?.signal,
       // Extended thinking: models tagged 'reasoning' reason BEFORE every
       // reply — including after each tool result — so complex tasks get
@@ -970,11 +1159,28 @@ ${this.mode === 'build' ? `- You have all tools available: read, write, edit, ba
     this.abortController = new AbortController();
     opts.signal = this.abortController.signal;
 
+    // Inject the per-turn skill block into the LAST user message of a wire
+    // copy (never this.messages) — keeps the system prompt byte-stable for
+    // prompt caching while still steering this one turn. Then age older tool
+    // results so a huge read/grep output from 20 turns ago stops costing
+    // full input price on every later call.
+    let wire = this.messages;
+    if (this._skillBlock) {
+      wire = wire.slice();
+      for (let i = wire.length - 1; i >= 0; i--) {
+        if (wire[i].role === 'user') {
+          wire[i] = Object.assign({}, wire[i], { content: String(wire[i].content || '') + this._skillBlock });
+          break;
+        }
+      }
+    }
+    wire = this.ageHistory(wire);
+
     let resp;
     if (callbacks.onDelta || callbacks.onReasoning) {
-      resp = await provider.stream(this.messages, opts, callbacks.onDelta, callbacks.onReasoning);
+      resp = await provider.stream(wire, opts, callbacks.onDelta, callbacks.onReasoning);
     } else {
-      resp = await provider.chat(this.messages, opts);
+      resp = await provider.chat(wire, opts);
     }
 
     if (this.interrupted || (opts.signal && opts.signal.aborted)) {
@@ -992,22 +1198,41 @@ ${this.mode === 'build' ? `- You have all tools available: read, write, edit, ba
 
   // Normalize provider usage (OpenAI: prompt_tokens/completion_tokens, Anthropic: input_tokens/output_tokens)
   // into input/output counts, then add them to the session counters and the persistent lifetime tracker.
+  // Prompt-cache hits/writes are priced at ~0.1x/~1.25x the input rate (Anthropic's
+  // published cache rates; OpenAI/OpenRouter use the same 0.1x read discount).
+  // Anthropic's input_tokens EXCLUDES cached tokens (they arrive as separate
+  // cache_read_input_tokens/cache_creation_input_tokens); OpenAI/OpenRouter's
+  // prompt_tokens_details.cached_tokens is a SUBSET of prompt_tokens.
   recordUsage(usage, modelId, providerName) {
     if (!usage) return;
-    const input = usage.prompt_tokens || usage.input_tokens || usage.promptTokenCount || 0;
+    const rawIn = usage.prompt_tokens || usage.input_tokens || usage.promptTokenCount || 0;
     const output = usage.completion_tokens || usage.output_tokens || usage.candidatesTokenCount || 0;
+    const cacheRead = usage.cache_read_input_tokens
+      || usage.prompt_tokens_details?.cached_tokens
+      || usage.cachedContentTokenCount
+      || 0;
+    const cacheWrite = usage.cache_creation_input_tokens || 0;
+    // Anthropic input excludes cache tokens; OpenAI input includes the cached subset.
+    const input = providerName === 'anthropic' ? rawIn + cacheRead + cacheWrite : rawIn;
+    const uncachedIn = providerName === 'anthropic' ? rawIn : Math.max(0, rawIn - cacheRead - cacheWrite);
     const total = usage.total_tokens || usage.totalTokens || (input + output);
     if (!input && !output && !total) return;
 
     this.tokensIn += input;
     this.tokensOut += output;
     this.tokensUsed += total;
+    this.cacheReadTokens = (this.cacheReadTokens || 0) + cacheRead;
+    this.cacheWriteTokens = (this.cacheWriteTokens || 0) + cacheWrite;
 
     const { getModelMeta } = require('../providers');
     const meta = getModelMeta(providerName, modelId);
     let cost = 0;
     if (meta && (meta.priceIn || meta.priceOut)) {
-      cost = (input / 1e6) * (meta.priceIn || 0) + (output / 1e6) * (meta.priceOut || 0);
+      const priceIn = meta.priceIn || 0;
+      cost = (uncachedIn / 1e6) * priceIn
+        + (cacheRead / 1e6) * priceIn * 0.1
+        + (cacheWrite / 1e6) * priceIn * 1.25
+        + (output / 1e6) * (meta.priceOut || 0);
       this.sessionCost += cost;
     }
     const { recordUsage: persist } = require('./usage');
@@ -1047,6 +1272,8 @@ ${this.mode === 'build' ? `- You have all tools available: read, write, edit, ba
     this.tokensUsed = 0;
     this.tokensIn = 0;
     this.tokensOut = 0;
+    this.cacheReadTokens = 0;
+    this.cacheWriteTokens = 0;
     this.sessionCost = 0;
     this.todos = [];
     this.compactCount = 0;
@@ -1056,4 +1283,4 @@ ${this.mode === 'build' ? `- You have all tools available: read, write, edit, ba
   }
 }
 
-module.exports = { Session, MEMORY_TEMPLATE, isQuotaError, isAbortError };
+module.exports = { Session, MEMORY_TEMPLATE, isQuotaError, isAbortError, isRateLimitError, isContextOverflowError };

package/src/core/transcript-undo.js

@@ -0,0 +1,74 @@
+// Transcript undo/redo — the conversation-level counterpart to /restore
+// (which rewinds the FILE TREE). Each undoable step is one user turn: the
+// full transcript (UI messages + session messages + todos) captured right
+// before the turn ran, plus the restore-point id created for that same turn
+// so an undo can also offer to roll the working tree back.
+//
+// Pure engine, no TUI/reactivity — the App owns the stacks and passes plain
+// snapshots in, which keeps this unit-testable.
+
+const MAX_UNDO = 50;
+
+// A snapshot is an opaque object the caller builds (it knows how to clone its
+// own UI + session state). We only ever store and hand back references.
+// shape: { ui: any[], session: any[], todos: any[], restoreId?: string, label?: string }
+
+function cloneSnap(snap) {
+  // structuredClone is available on Node 18+/Bun; fall back to JSON for the
+  // plain-JSON session data (never holds functions or DOM handles).
+  if (typeof structuredClone === 'function') {
+    try { return structuredClone(snap); } catch {}
+  }
+  return JSON.parse(JSON.stringify(snap));
+}
+
+class TranscriptUndo {
+  constructor(max = MAX_UNDO) {
+    this.max = max;
+    this.undoStack = [];
+    this.redoStack = [];
+  }
+
+  // Record the state as it was BEFORE a turn ran. Clears the redo stack (a
+  // fresh action diverges history, like any editor). Returns the step object
+  // so callers can attach late-bound data (e.g. a restore-point id created in
+  // a background setTimeout) without relying on a fragile stack index.
+  push(beforeSnap, label) {
+    const step = cloneSnap(beforeSnap);
+    step.label = label || '';
+    this.undoStack.push(step);
+    if (this.undoStack.length > this.max) this.undoStack.shift();
+    // A new action invalidates the future.
+    this.redoStack.length = 0;
+    return step;
+  }
+
+  // Move one turn backward. `currentSnap` is the state we are leaving — it
+  // goes onto the redo stack so the undo can be re-done. Returns the snapshot
+  // to restore, or null when there is nothing to undo.
+  undo(currentSnap) {
+    if (!this.undoStack.length) return null;
+    const target = this.undoStack.pop();
+    if (currentSnap) this.redoStack.push(cloneSnap(currentSnap));
+    if (this.redoStack.length > this.max) this.redoStack.shift();
+    return target;
+  }
+
+  // Move one turn forward again. Returns the snapshot to restore, or null.
+  redo(currentSnap) {
+    if (!this.redoStack.length) return null;
+    const target = this.redoStack.pop();
+    if (currentSnap) this.undoStack.push(cloneSnap(currentSnap));
+    if (this.undoStack.length > this.max) this.undoStack.shift();
+    return target;
+  }
+
+  canUndo() { return this.undoStack.length > 0; }
+  canRedo() { return this.redoStack.length > 0; }
+  peekUndo() { return this.undoStack[this.undoStack.length - 1] || null; }
+  peekRedo() { return this.redoStack[this.redoStack.length - 1] || null; }
+  depth() { return { undo: this.undoStack.length, redo: this.redoStack.length }; }
+  clear() { this.undoStack.length = 0; this.redoStack.length = 0; }
+}
+
+module.exports = { TranscriptUndo, MAX_UNDO };