jaitus 0.3.12 → 0.3.14

package/src/agent/loop.js

@@ -1,980 +1,998 @@
-// ─── The agent loop ─────────────────────────────────────────────────────────────
-//
-// Send the conversation to Jaitus, stream the reply, run any tools it asked for, append
-// the results, and go again — until it stops asking for tools. That is the whole idea;
-// everything else here is making it behave under real conditions.
-//
-// Notes on the parts that are easy to get wrong:
-//
-//   • Streaming is parsed as server-sent events. Tool arguments arrive as `input_json_delta`
-//     fragments that only become valid JSON once concatenated, so they are buffered per
-//     content block and parsed at the end, never incrementally.
-//   • The assistant turn is appended EXACTLY as the model produced it, tool_use blocks
-//     included. Paraphrasing it breaks the pairing with tool_result and the next turn
-//     is rejected.
-//   • Every tool_use must get a tool_result, including ones that failed or were refused.
-//     A missing result is a malformed conversation, and the error text is also how the
-//     model learns to try something else.
-//   • A stuck detector, not a step count. A model caught in a loop would otherwise spend
-//     real money until someone notices — but a fixed cap of 40 steps also stopped every
-//     long, perfectly healthy task halfway and made the user type "continue". A run now
-//     ends when the model finishes, or when it repeats the same call with the same input
-//     STUCK_REPEATS times with no file changed in between (see `stuck` below). A very
-//     high backstop remains so no run is unbounded.
-
-import { byName, toolSchemas, ToolError, readImageForModel } from './tools.js';
-import { PermissionDenied } from './permissions.js';
-import path from 'node:path';
-import fs from 'node:fs';
-import os from 'node:os';
-import { loadContext, loadIgnore, CONTEXT_FILE } from '../project.js';
-import { c, out, write, spinner, glyph } from '../ui.js';
-import { discoverMcpTools } from '../mcp.js';
-import { unifiedDiff } from '../diff.js';
-import { fromResponse, fromGatewayBody, JaitusError } from '../errors.js';
-
-const MAX_ITERATIONS = 1000;
-const STUCK_REPEATS = 4;
-const POLLING_TOOLS = new Set(['background_read', 'background_list']);
-
-// Room for a long answer or a large file in one reply. The models behind Jaitus reason
-// before they answer, and that reasoning is spent from the same budget — at 8192 a long
-// answer, or any file of a few hundred lines, was cut off partway.
-export const MAX_OUTPUT_TOKENS = 32000;
-
-// A reply that stopped before it finished — the output limit, or a connection dropped
-// somewhere between the provider and here — is continued, not presented as the answer.
-// Bounded, so a model that never finishes cannot loop on the user's allowance.
-export const MAX_CONTINUATIONS = 4;
-export const CONTINUE_NOTE = 'Your previous reply was cut off before it finished (an output limit or a dropped connection). '
-  + 'Continue from exactly where it stopped: do not repeat or summarise what you already wrote, and do not mention this note. '
-  + 'If you were in the middle of a tool call, make that call again in full.';
-
-// A request that failed before anything arrived (a network blip) is tried again this
-// many times before it is reported.
-const NETWORK_RETRIES = 2;
-
-// Gateway answers that mean "not right now", not "no".
-const TRANSIENT_CODES = new Set(['busy', 'unavailable', 'timeout', 'interrupted', 'internal', 'maintenance']);
-const BUSY_RETRIES = 3;
-const MAX_RETRY_WAIT_MS = 30_000;
-
-/** How long to wait before retrying `e`, or null when it must not be retried. */
-export function retryDelay(e, attempt = 0) {
-  const code = e?.code;
-  const hinted = Number(e?.retryAfter) > 0 ? Number(e.retryAfter) * 1000 : null;
-  if (code === 'rate_limited') {
-    // A short window is waited out; a cap that resets in hours is a limit, not a blip.
-    if (hinted == null) return 2000 * (attempt + 1);
-    return hinted <= MAX_RETRY_WAIT_MS ? hinted : null;
-  }
-  if (!TRANSIENT_CODES.has(code) || code === 'internal') return null;
-  return Math.min(MAX_RETRY_WAIT_MS, hinted ?? 1500 * 2 ** attempt);
-}
-
-function sleepUnlessAborted(ms, signal) {
-  return new Promise((resolve) => {
-    if (signal?.aborted) return resolve(false);
-    const t = setTimeout(() => { signal?.removeEventListener?.('abort', onAbort); resolve(true); }, ms);
-    const onAbort = () => { clearTimeout(t); resolve(false); };
-    signal?.addEventListener?.('abort', onAbort, { once: true });
-  });
-}
-
-/** opencode tool icon per tool, muted when done. ASCII twins included. */
-const TOOL_MARKS = {
-  run_command: ['$', '$'], read_file: ['→', '>'], read_image: ['→', '>'],
-  list_files: ['→', '>'], write_file: ['←', '<'], edit_file: ['←', '<'],
-  search: ['✱', '*'], web_fetch: ['%', '%'], web_search: ['◈', 'o'],
-  background_run: ['◉', 'o'], todo_write: ['⚙', '*'],
-};
-const toolMark = (name) => {
-  const [uni, ascii] = TOOL_MARKS[name] || ['⚙', '*'];
-  return c.dim(glyph(uni, ascii));
-};
-
-export const SYSTEM_PROMPT = `You are Jaitus, a coding agent running in a developer's terminal, inside their project directory.
-
-You work directly on this computer. Your tools read, search, create and edit the files in
-the project and run shell commands in it, and you can fetch web pages. When the user asks
-about their files, their code or their machine, use the tools and answer from what you
-find — never say you cannot access local files, because you can.
-
-How to work:
-- Investigate before you change anything. Read the files you are about to edit; do not guess at their contents.
-- Prefer edit_file over write_file for existing files. Keep changes minimal and in the style of the surrounding code.
-- Run the project's own tests or build after a change when one exists, and report the real result — including when it fails.
-- Use run_command for anything the shell does better: git, tests, package managers, linters.
-- Never invent a file path, a function name, or a test result. If you are unsure, look.
-- Every turn re-sends the whole conversation, so make independent reads, searches and
-  listings together in ONE turn rather than one per turn. Read the part of a large file you
-  need (offset/limit) rather than all of it.
-- For current news or other web facts, report only details grounded in web_search or
-  web_fetch output. Include the supplied source URLs; never fill a missing headline or
-  date from memory.
-
-How to talk:
-- Be concise. This is a terminal, not a document.
-- Say what you did and what happened, not what you are about to do.
-- If something is blocked or you are missing information, say so plainly and ask.
-- No preamble, no restating the question back.`;
-
-/**
- * The project's own briefing, appended to the system prompt.
- *
- * Fenced and labelled rather than concatenated, so instructions written by whoever owns
- * the repo are visibly the repo's and cannot be mistaken for part of Jaitus's own rules.
- */
-/**
- * Where the agent is: the facts it would otherwise guess at, and guess wrong.
- *
- * Without these, the model did not know which folder it was in, which OS its commands
- * would run on (cmd.exe and /bin/sh disagree about almost everything), or today's date —
- * and a model that does not know where it is tends to say it cannot see your files. The
- * listing is the top level only, names not contents, and respects .jaitusignore.
- */
-export function environmentBlock(cwd, { now = new Date(), platform = process.platform } = {}) {
-  if (!cwd) return '';
-  const osName = { win32: 'Windows', darwin: 'macOS', linux: 'Linux' }[platform] || platform;
-  const shell = platform === 'win32' ? 'cmd.exe (run_command uses it)' : '/bin/sh (run_command uses it)';
-  // The repository may start above the working directory, and .git may be a file that
-  // points elsewhere (a worktree or submodule).
-  let branch = null;
-  for (let dir = cwd, i = 0; i < 40; i++) {
-    const dotGit = path.join(dir, '.git');
-    try {
-      let gitDir = dotGit;
-      if (fs.statSync(dotGit).isFile()) {
-        const m = /^gitdir:\s*(.+)$/m.exec(fs.readFileSync(dotGit, 'utf8'));
-        if (m) gitDir = path.resolve(dir, m[1].trim());
-      }
-      const head = fs.readFileSync(path.join(gitDir, 'HEAD'), 'utf8').trim();
-      branch = head.startsWith('ref: refs/heads/') ? head.slice(16) : `detached at ${head.slice(0, 7)}`;
-      break;
-    } catch { /* not here; look one level up */ }
-    const parent = path.dirname(dir);
-    if (parent === dir) break;
-    dir = parent;
-  }
-  let listing = '';
-  try {
-    const ignore = loadIgnore(cwd);
-    const SKIP = new Set(['.git', 'node_modules']);
-    const names = fs.readdirSync(cwd, { withFileTypes: true })
-      .filter((d) => !SKIP.has(d.name) && !ignore.matches(d.isDirectory() ? `${d.name}/` : d.name) && !ignore.matches(d.name))
-      .map((d) => (d.isDirectory() ? `${d.name}/` : d.name))
-      .sort((a, b) => (b.endsWith('/') - a.endsWith('/')) || a.localeCompare(b));
-    const MAX = 60;
-    listing = names.slice(0, MAX).join('\n') + (names.length > MAX ? `\n… and ${names.length - MAX} more` : '');
-  } catch { /* unreadable: the tools will say why */ }
-  return `
-
-<environment>
-Working directory: ${cwd}
-Platform: ${osName} (${os.release()})
-Shell: ${shell}
-Today: ${now.toISOString().slice(0, 10)}
-Git: ${branch ? `yes, branch ${branch}` : 'no repository at this folder'}
-Top level of the working directory:
-${listing || '(empty)'}
-</environment>`;
-}
-
-export function systemPrompt(cwd) {
-  const project = cwd ? loadContext(cwd) : null;
-  const base = `${SYSTEM_PROMPT}${environmentBlock(cwd)}`;
-  if (!project) return base;
-  return `${base}
-
-The project you are working in ships a ${CONTEXT_FILE} with notes for you. Follow it where
-it applies, and prefer what it says over your own assumptions about this codebase.
-
-<${CONTEXT_FILE}>
-${project}
-</${CONTEXT_FILE}>`;
-}
-
-/**
- * Every earlier image is sent again with every request, and the gateway accepts at most
- * 10 MB per request — three or four screenshots into a conversation, every turn failed.
- * The newest images are kept up to IMAGE_BUDGET bytes of base64; older ones are replaced
- * by a line saying one was there. The history itself is not changed.
- */
-/**
- * Make a history well-formed after any interruption: every assistant tool_use has a
- * tool_result in the next message. A run stopped by Esc, a failed permission prompt or
- * a gateway error partway through could leave a tool call with no result — and both
- * provider formats reject that, so every later request in the session failed. Missing
- * results are filled in as "not run"; an assistant turn that ends the history with tool
- * calls gets its results appended.
- */
-export function repairToolPairs(messages) {
-  for (let i = 0; i < messages.length; i++) {
-    const m = messages[i];
-    if (m?.role !== 'assistant' || !Array.isArray(m.content)) continue;
-    const ids = m.content.filter((b) => b?.type === 'tool_use').map((b) => b.id);
-    if (!ids.length) continue;
-    const next = messages[i + 1];
-    const have = new Set(next?.role === 'user' && Array.isArray(next.content)
-      ? next.content.filter((b) => b?.type === 'tool_result').map((b) => b.tool_use_id) : []);
-    const missing = ids.filter((id) => !have.has(id));
-    if (!missing.length) continue;
-    const filled = missing.map((id) => result(id, 'Not run: the task was interrupted before this step.', true));
-    if (next?.role === 'user') {
-      const content = Array.isArray(next.content) ? next.content : [{ type: 'text', text: String(next.content ?? '') }];
-      const results = content.filter((b) => b?.type === 'tool_result');
-      const rest = content.filter((b) => b?.type !== 'tool_result');
-      messages[i + 1] = { ...next, content: [...results, ...filled, ...rest] };
-    } else {
-      messages.splice(i + 1, 0, { role: 'user', content: filled });
-    }
-  }
-  return messages;
-}
-
-// ── Keeping the conversation small ────────────────────────────────────────────
-//
-// Every request re-sends the whole conversation, and in real use that re-send — cached,
-// but not free — was ~75% of what a session cost: 109 requests averaged 46k tokens of
-// context each, most of it tool output from many steps ago (a file read at step 3 is
-// still paid for at step 60). This is the documented "clear old tool results" strategy
-// (Anthropic's context editing, clear_tool_uses; Claude Code's micro-compaction): once
-// the conversation passes TRIM_AT, the outputs of all but the KEEP_RECENT latest tool
-// calls are replaced with a line saying they were cleared and can be re-run. It clears
-// at least TRIM_AT_LEAST at a time, because each clearing breaks the prompt cache once
-// — clearing a little on every step would cost more than it saves. Small results (a
-// "file written", an exit code) are kept: they carry meaning and cost nothing.
-// 100k was the documented default for 200k-window models. Here the window is up to 1M, so
-// that ceiling was rarely near: production requests averaged 53k tokens and two thirds of
-// all input tokens came from requests over 60k. At 40k a clearing (one cache break, ~17
-// credits on glm-5.3-flash) pays for itself within about ten later requests.
-export const TRIM_AT = 40_000;          // estimated tokens of conversation
-export const KEEP_RECENT = 6;           // latest tool results always kept whole
-export const TRIM_AT_LEAST = 12_000;    // estimated tokens a clearing must free
-const TRIM_MIN_CHARS = 1_500;           // results shorter than this are never cleared
-const CLEARED = '[Output cleared';
-
-const blockChars = (b) => {
-  if (b?.type === 'text') return (b.text || '').length;
-  if (b?.type === 'tool_use') return JSON.stringify(b.input || {}).length;
-  if (b?.type === 'tool_result') return typeof b.content === 'string' ? b.content.length : JSON.stringify(b.content || '').length;
-  return 0;
-};
-export function conversationTokens(messages) {
-  let chars = 0;
-  for (const m of messages || []) chars += typeof m?.content === 'string' ? m.content.length : (Array.isArray(m?.content) ? m.content.reduce((n, b) => n + blockChars(b), 0) : 0);
-  return Math.ceil(chars / 4);
-}
-
-/**
- * Clear old tool outputs in place when the conversation is large. Returns how many
- * estimated tokens were freed (0 when nothing was worth clearing).
- */
-export function clearOldToolResults(messages, { at = TRIM_AT, keep = KEEP_RECENT, atLeast = TRIM_AT_LEAST } = {}) {
-  if (conversationTokens(messages) < at) return 0;
-  const names = new Map();
-  for (const m of messages) {
-    if (m?.role === 'assistant' && Array.isArray(m.content)) for (const b of m.content) if (b?.type === 'tool_use') names.set(b.id, b.name);
-  }
-  const results = [];
-  for (const m of messages) {
-    if (m?.role !== 'user' || !Array.isArray(m.content)) continue;
-    m.content.forEach((b, i) => { if (b?.type === 'tool_result') results.push({ m, i, b }); });
-  }
-  const candidates = results.slice(0, Math.max(0, results.length - keep)).filter(({ b }) => {
-    const text = typeof b.content === 'string' ? b.content : '';
-    return text.length >= TRIM_MIN_CHARS && !text.startsWith(CLEARED);
-  });
-  const freed = Math.ceil(candidates.reduce((n, { b }) => n + blockChars(b), 0) / 4);
-  if (freed < atLeast) return 0;
-  for (const { m, i, b } of candidates) {
-    const chars = blockChars(b);
-    const name = names.get(b.tool_use_id) || 'this tool';
-    m.content[i] = { ...b, content: `${CLEARED}: ${name} returned ${chars.toLocaleString()} characters here, removed to keep the conversation small. Run it again if you need it.]` };
-  }
-  return freed;
-}
-
-export const IMAGE_BUDGET = 6_000_000;
-export function withinImageBudget(messages, budget = IMAGE_BUDGET) {
-  let used = 0;
-  let changed = false;
-  const out = messages.slice();
-  for (let i = out.length - 1; i >= 0; i--) {
-    const m = out[i];
-    if (!Array.isArray(m?.content) || !m.content.some((b) => b?.type === 'image')) continue;
-    // Walk this message's blocks newest-last, so within a message the later images win.
-    const kept = new Array(m.content.length);
-    for (let j = m.content.length - 1; j >= 0; j--) {
-      const b = m.content[j];
-      if (b?.type !== 'image') { kept[j] = b; continue; }
-      const size = String(b.source?.data || '').length;
-      if (used + size <= budget) { used += size; kept[j] = b; continue; }
-      kept[j] = { type: 'text', text: '[An image was attached here earlier; it is no longer included, to keep the request small.]' };
-      changed = true;
-    }
-    out[i] = { ...m, content: kept };
-  }
-  return changed ? out : messages;
-}
-
-/** One streamed request. Returns { content, stopReason, usage }. */
-async function streamTurn({ client, messages, model, system, tools, onText, onToolStart, signal }) {
-  const res = await client.messages({
-    model,
-    max_tokens: MAX_OUTPUT_TOKENS,
-    system: system || SYSTEM_PROMPT,
-    tools,
-    messages: withinImageBudget(messages),
-    stream: true,
-  }, { signal });
-
-  if (!res.ok) throw await fromResponse(res);
-  const requestId = res.headers?.get?.('x-request-id') || '';
-
-  // Blocks are keyed by the index the stream gives them, because they interleave.
-  const blocks = new Map();
-  let stopReason = null;
-  // Whether the stream ended the way a finished message ends. A stream that just stops
-  // — no message_stop, no stop reason — was cut, and used to be taken as a complete,
-  // silent answer: the "it stops midway for no reason" bug.
-  let sawStop = false;
-  // `credits` is what the gateway counted against the plan for this request — real cost,
-  // the one unit the plan, the dashboard and this CLI all show.
-  const usage = { input_tokens: 0, output_tokens: 0, cache_read_input_tokens: 0, cache_creation_input_tokens: 0, credits: 0 };
-  // Usage can arrive at the START of a stream (Anthropic-format providers) or only at
-  // the END, in message_delta (OpenAI-format providers, translated by the gateway —
-  // their usage exists only once generation finishes). Reading input from message_start
-  // alone recorded every OpenAI-format turn as 0 input tokens.
-  const takeUsage = (u) => {
-    if (!u) return;
-    for (const k of ['input_tokens', 'output_tokens', 'cache_read_input_tokens', 'cache_creation_input_tokens', 'credits']) {
-      if (u[k] != null && Number.isFinite(Number(u[k]))) usage[k] = Number(u[k]);
-    }
-  };
-  let buffer = '';
-  // A stream that never ends must die here, not in GC hell: the buffer below grows
-  // with every chunk and each arrival re-splits all of it, so a runaway provider
-  // (twelve silent minutes and counting, seen in the wild) grows memory
-  // quadratically until V8 falls over near 4 GB. Past the cap the turn ends as a
-  // cut (continued from what arrived) or, with nothing received, as a retryable
-  // timeout — never as a crash.
-  const MAX_STREAM_BUFFER = 8 * 1024 * 1024;
-  // A failure reported INSIDE the stream, after a 200. Recorded here and thrown after
-  // the parse below: handle() runs inside a try whose catch exists to skip keepalives,
-  // so throwing from it would be swallowed — which is how a mid-stream error used to
-  // end an answer halfway with no explanation at all.
-  let streamError = null;
-
-  const handle = (event) => {
-    switch (event.type) {
-      case 'error':
-        streamError = fromGatewayBody(200, event, { requestId });
-        break;
-      case 'message_start':
-        takeUsage(event.message?.usage);
-        break;
-      case 'content_block_start': {
-        const b = event.content_block || {};
-        blocks.set(event.index, b.type === 'tool_use'
-          ? { type: 'tool_use', id: b.id, name: b.name, json: '' }
-          : { type: 'text', text: '' });
-        if (b.type === 'tool_use') onToolStart?.(b.name);
-        break;
-      }
-      case 'content_block_delta': {
-        const b = blocks.get(event.index);
-        if (!b) break;
-        const d = event.delta || {};
-        if (d.type === 'text_delta' && typeof d.text === 'string') {
-          b.text += d.text;
-          onText?.(d.text);
-        } else if (d.type === 'input_json_delta' && typeof d.partial_json === 'string') {
-          b.json += d.partial_json;
-        }
-        break;
-      }
-      case 'message_delta':
-        if (event.delta?.stop_reason) stopReason = event.delta.stop_reason;
-        takeUsage(event.usage);
-        break;
-      case 'message_stop':
-        sawStop = true;
-        break;
-      default:
-        break;
-    }
-  };
-
-  // fetch() yields Uint8Array, NOT a Node Buffer. `uint8.toString('utf8')` ignores the
-  // argument and returns "101,118,101,…" — comma-joined byte values — so the whole
-  // stream parses to nothing and the agent appears to answer with silence.
-  //
-  // TextDecoder with stream:true is also the only correct choice for a different reason:
-  // a multi-byte character can be split across two chunks, and decoding each chunk
-  // independently would corrupt it. The decoder holds the partial bytes until complete.
-  const decoder = new TextDecoder();
-
-  let cut = false;
-  try {
-    for await (const chunk of res.body) {
-      buffer += decoder.decode(chunk, { stream: true });
-      if (buffer.length > MAX_STREAM_BUFFER) {
-        // Breaking the loop releases the reader (the socket is cancelled), so the
-        // runaway stops arriving too — not just stops being kept.
-        if (!blocks.size) throw new JaitusError({ code: 'timeout', status: 504, message: 'Jaitus took too long to respond. Try again.' });
-        cut = true;
-        break;
-      }
-      const frames = buffer.split('\n\n');
-      buffer = frames.pop() || '';
-      for (const frame of frames) {
-        for (const line of frame.split('\n')) {
-          if (!line.startsWith('data:')) continue;
-          const raw = line.slice(5).trim();
-          if (!raw || raw === '[DONE]') continue;
-          try { handle(JSON.parse(raw)); } catch { /* keepalive or partial */ }
-        }
-      }
-      if (streamError) break;
-    }
-  } catch (e) {
-    // Esc is the only abort that reads as an interruption. Any OTHER AbortError —
-    // the request timeout in api.js firing mid-body, a dropped socket — is a `timeout`
-    // JaitusError so the agent loop backs off and retries it (TRANSIENT_CODES) instead
-    // of reporting "Interrupted." for something the user never stopped.
-    if (signal?.aborted) throw e;
-    if (e?.name === 'AbortError') throw new JaitusError({ code: 'timeout', status: 504, message: 'Jaitus took too long to respond. Try again.' });
-    // The connection dropped mid-answer. What arrived is kept and continued from; with
-    // nothing received yet, the caller retries the request instead.
-    if (!blocks.size) throw e;
-    cut = true;
-  }
-  if (streamError) {
-    // The provider dropped out after part of the answer had arrived. What arrived is
-    // kept and continued from, exactly as when OUR connection drops — it used to be
-    // thrown away with a "Something went wrong" and the task stopped.
-    if (blocks.size && TRANSIENT_CODES.has(streamError.code)) cut = true;
-    else throw streamError;
-  }
-  if (cut || (!sawStop && !stopReason)) stopReason = 'cut';
-
-  const content = [...blocks.entries()]
-    .sort((a, b) => a[0] - b[0])
-    .map(([, b]) => {
-      if (b.type !== 'tool_use') return { type: 'text', text: b.text };
-      let input = {};
-      // The fragments only form valid JSON once joined. An empty string is a
-      // no-argument call, which is legitimate.
-      try { input = b.json.trim() ? JSON.parse(b.json) : {}; } catch { input = { __parse_error: b.json }; }
-      return { type: 'tool_use', id: b.id, name: b.name, input };
-    })
-    .filter((b) => b.type !== 'text' || b.text.length);
-
-  return { content, stopReason, usage };
-}
-
-/**
- * Run one user request to completion.
- * `messages` is mutated so the caller keeps the conversation across turns.
- */
-export async function runAgent({
-  client, messages, model, cwd, permissions, signal, tui = null,
-  extraSystem = '', maxIterations = MAX_ITERATIONS, silent = false,
-  onText = null, onEvent = null, systemOverride = null, journal = null,
-  subagents = true, onContext = null, trimContext = true,
-}) {
-  // Loop detection. A call is identified by its tool, its input, and how many files had
-  // been changed when it was made — so edit → test → edit → test is progress (the count
-  // moves), while reading the same file over and over is not.
-  let changes = 0;
-  const repeats = new Map();
-  // input = fresh input, cached = prompt-cache reads (billed far cheaper), and
-  // context = the real size of the last prompt sent, as the provider counted it.
-  const totals = { input: 0, cached: 0, output: 0, tools: 0, context: 0, credits: 0 };
-  // Read once per request, not per turn: an agent that rewrites JAITUS.md mid-task
-  // should not change the rules it is being judged by halfway through.
-  // The model is told when it is in plan mode — it used to find out only by having its
-  // writes refused, after it had already tried them.
-  const planNote = permissions?.mode === 'plan'
-    ? '\n\nPLAN MODE is on: you can read, list, search and fetch, but nothing you write and no command you run will be carried out. Investigate, then answer with a concrete plan (files, changes, order, risks). The user switches modes when they want it done.'
-    : '';
-  const system = `${systemOverride || systemPrompt(cwd)}${extraSystem}${planNote}`;
-  const mcp = await discoverMcpTools(cwd).catch(() => []);
-  // Subagents are offered only to the top-level agent. A subagent that can spawn
-  // subagents is an unbounded fan-out on a metered gateway, and the depth that would
-  // actually help — one — is the depth that is safe.
-  const subagent = subagents ? makeSubagentTool({ client, model, cwd, signal, tui, permissions }) : null;
-  const availableTools = [
-    ...toolSchemas(),
-    ...(subagent ? [{ name: subagent.name, description: subagent.description, input_schema: subagent.input_schema }] : []),
-    ...mcp.map((tool) => ({ name: tool.name, description: tool.description, input_schema: tool.input_schema })),
-  ];
-  const toolMap = {
-    ...byName,
-    ...(subagent ? { [subagent.name]: subagent } : {}),
-    ...Object.fromEntries(mcp.map((tool) => [tool.name, tool])),
-  };
-
-  let continuations = 0;
-  let networkRetries = 0;
-  let busyRetries = 0;
-  let planNoticeShown = false;
-  // True while the previous reply is being continued: its text is still on screen as
-  // one live message, and the continuation must extend it rather than start another.
-  let continuing = false;
-
-  for (let iteration = 0; iteration < maxIterations; iteration++) {
-    // Old tool outputs are cleared once the conversation is large (see TRIM_AT) — in
-    // place, so the saved session shrinks too and the cache stays warm afterwards.
-    if (trimContext) {
-      const freed = clearOldToolResults(messages);
-      if (freed && tui?.notice) tui.notice(`Cleared old tool output (~${Math.round(freed / 1000)}k tokens) to keep each request small.`, 'info');
-    }
-    let streamed = false;
-    const spin = tui ? { stop: () => {}, update: () => {} } : (silent ? { stop: () => {}, update: () => {} } : spinner(glyph('Working…', 'Working...')));
-    if (tui) tui.setStatus(`${c.brand(glyph('•', '*'))} ${c.brand(glyph('Working…', 'Working...'))}`);
-    // Codex-style assistant cell: the • leads the turn the way › leads the
-    // user's. In scrollback the marker lands before the first streamed chunk.
-    let turnVoiced = false;
-
-    let turn;
-    try {
-      turn = await streamTurn({
-        client,
-        messages,
-        model,
-        system,
-        tools: availableTools,
-        signal,
-        onText: (text) => {
-          onText?.(text);
-          if (!streamed) {
-            spin.stop(); streamed = true;
-            if (tui) tui.clearStatus();
-            else if (!silent && !onText) { out(''); write(`${c.dim(glyph('•', '*'))} `); }
-          }
-          if (tui) {
-            // The transcript entry draws its own speaker mark now, so the loop no
-            // longer prepends one — two marks on the same line was the tell that the
-            // renderer and the loop each thought they owned the lead glyph.
-            turnVoiced = true;
-            tui.printStream(text);
-          } else if (!silent && !onText) write(text);
-        },
-        onToolStart: () => spin.update(glyph('Working…', 'Working...')),
-      });
-    } catch (e) {
-      spin.stop();
-      // Esc during streaming: stop mid-sentence, keep what landed, don't treat it
-      // as an error. The partial text is already on screen.
-      // A network failure before anything arrived: try again, briefly, before reporting.
-      // Anything the gateway itself refused (a limit, a sign-in problem) has a status and
-      // is reported at once — retrying it would only repeat the refusal.
-      if (!(signal?.aborted || e?.name === 'AbortError') && !e?.status && networkRetries < NETWORK_RETRIES) {
-        networkRetries += 1;
-        await new Promise((r) => setTimeout(r, 800 * networkRetries));
-        iteration -= 1;
-        continue;
-      }
-      // Busy, rate-limited for a moment, unavailable, timed out: the gateway says to
-      // back off and retry (it sends Retry-After), and nothing used to — one provider 429
-      // ended a task halfway. A limit (plan, free tier, a daily cap hours away) or a
-      // sign-in problem is never retried.
-      const wait = retryDelay(e, busyRetries);
-      if (!(signal?.aborted || e?.name === 'AbortError') && wait != null && busyRetries < BUSY_RETRIES) {
-        busyRetries += 1;
-        const secs = Math.max(1, Math.round(wait / 1000));
-        if (tui?.setStatus) tui.setStatus(`${c.yellow('!')} ${c.dim(`Jaitus is busy — trying again in ${secs}s (${busyRetries} of ${BUSY_RETRIES})`)}`);
-        const ok = await sleepUnlessAborted(wait, signal);
-        tui?.clearStatus?.();
-        if (!ok) return { ...totals, stopReason: 'interrupted' };
-        iteration -= 1;
-        continue;
-      }
-      if (signal?.aborted || e?.name === 'AbortError') {
-        if (tui) tui.flushStream();
-        if (streamed && !silent) out('');
-        if (tui?.notice) tui.notice('Interrupted.', 'warn');
-        else if (tui) tui.print(c.yellow(`  ${glyph('⏹', '[x]')}  Interrupted.`));
-        else if (!silent) out(c.yellow(`  ${glyph('⏹', '[x]')}  Interrupted.`));
-        return { ...totals, stopReason: 'interrupted' };
-      }
-      throw e;
-    }
-    spin.stop();
-    networkRetries = 0;
-    busyRetries = 0;
-    // A reply the provider's content filter stopped is cut short; say so rather than
-    // letting half an answer pass for the whole one.
-    if (turn.stopReason === 'refusal') {
-      const why = 'The answer was stopped partway by a content filter. Rephrasing the request usually gets past it.';
-      if (tui?.notice) tui.notice(why, 'warn');
-      else if (!silent) out(c.yellow(`  ${why}`));
-    }
-    const incomplete = turn.stopReason === 'max_tokens' || turn.stopReason === 'cut';
-    // A tool call cut off halfway has JSON that is not whole; it is dropped and the model
-    // is asked to make it again.
-    if (incomplete) turn.content = turn.content.filter((b) => b.type !== 'tool_use' || b.input?.__parse_error === undefined);
-    const willContinue = incomplete && continuations < MAX_CONTINUATIONS && !turn.content.some((b) => b.type === 'tool_use');
-    if (!willContinue) {
-      if (tui) tui.flushStream();
-      if (streamed || continuing) { if (tui) tui.printStream('\n'); else if (!silent && !onText) out(''); }
-    }
-
-    totals.input += turn.usage.input_tokens || 0;
-    totals.cached += (turn.usage.cache_read_input_tokens || 0) + (turn.usage.cache_creation_input_tokens || 0);
-    totals.output += turn.usage.output_tokens || 0;
-    totals.credits += Number(turn.usage.credits) || 0;
-    const promptSize = (turn.usage.input_tokens || 0) + (turn.usage.cache_read_input_tokens || 0) + (turn.usage.cache_creation_input_tokens || 0);
-    if (promptSize) {
-      totals.context = promptSize + (turn.usage.output_tokens || 0);
-      // The header's context meter moves after every step. It used to be told only when
-      // the whole run returned, so through a long task — and after one stopped with
-      // Esc or an error — it sat at 0.
-      try { onContext?.(totals.context); } catch { /* the meter never breaks a turn */ }
-    }
-    // The work bar's live count. It was declared and drawn but never fed, so it never
-    // appeared; now it moves after every step of the turn.
-    tui?.setTurnTokens?.(totals.input + totals.cached + totals.output);
-
-    if (willContinue) {
-      continuations += 1;
-      continuing = true;
-      const text = turn.content.filter((b) => b.type === 'text');
-      if (text.length) messages.push({ role: 'assistant', content: text });
-      messages.push({ role: 'user', content: [{ type: 'text', text: CONTINUE_NOTE }] });
-      onEvent?.({ type: 'continued', reason: turn.stopReason, count: continuations });
-      continue;
-    }
-    continuing = false;
-    if (incomplete && !turn.content.some((b) => b.type === 'tool_use')) {
-      // Still unfinished after every continuation: say so, rather than let a partial
-      // answer pass as a whole one.
-      const why = 'The reply was still unfinished after several continuations. Ask for the rest, or narrow the request.';
-      if (tui?.notice) tui.notice(why, 'warn');
-      else if (!silent) out(c.yellow(`  ${why}`));
-    }
-
-    // Append the assistant turn verbatim — tool_use blocks and all.
-    messages.push({ role: 'assistant', content: turn.content });
-    onEvent?.({ type: 'assistant_turn', content: turn.content, usage: turn.usage, iteration });
-
-    const calls = turn.content.filter((b) => b.type === 'tool_use');
-
-    // Plan mode: read-only by decree. The turn's text still lands (the model can think
-    // out loud), but nothing on disk or in a shell is allowed to happen.
-    // web_fetch is not a write: in plan mode it goes to its own prompt instead of ending the turn.
-    // Plan mode: a write or command gets a "not run — plan instead" result, the reads in
-    // the same batch still run, and the turn — with the plan the model just wrote — stays
-    // in the history. It used to pop the whole turn, so "ok, do it" found no plan to do.
-    const planBlocked = permissions.mode === 'plan'
-      ? new Set(calls.filter((call) => toolMap[call.name]?.needsPermission && !toolMap[call.name]?.network).map((call) => call.id))
-      : new Set();
-    if (planBlocked.size && !planNoticeShown) {
-      planNoticeShown = true;
-      const text = 'Plan mode — writes and commands are not run; the agent can still read. Shift+Tab (or /code) to let it act.';
-      if (tui?.notice) tui.notice(text, 'warn');
-      else if (!silent) out(c.yellow(`  ${glyph('⏸', '[II]')}  ${text}`));
-    }
-
-    // Esc pressed while the model was mid-turn: stop before any more tools run.
-    if (signal?.aborted) {
-      if (!silent) out(c.yellow(`  ${glyph('⏹', '[x]')}  Interrupted.`));
-      return { ...totals, stopReason: 'interrupted' };
-    }
-
-    if (!calls.length) { tui?.bellIfAway?.(); return { ...totals, stopReason: turn.stopReason }; }
-
-    // The same call, same input, nothing changed since: STUCK_REPEATS times is a loop.
-    // Checked before running, so the repeat that proves it is not paid for again.
-    const stuckOn = calls.find((call) => {
-      // Polling is supposed to repeat: background_read's own description says "poll
-      // this", and four polls of a starting dev server are not a loop.
-      if (POLLING_TOOLS.has(call.name)) return false;
-      const key = `${changes}\u0000${call.name}\u0000${JSON.stringify(call.input ?? null)}`;
-      const n = (repeats.get(key) || 0) + 1;
-      repeats.set(key, n);
-      return n >= STUCK_REPEATS;
-    });
-    if (stuckOn) {
-      // Every tool_use still gets a result — the model is told why these did not run, so
-      // after "continue" it does not simply make the same call a fifth time.
-      messages.push({ role: 'user', content: calls.map((call) => result(call.id,
-        `Not run: this exact call was already made ${STUCK_REPEATS - 1} times with no file changed since, and the run was stopped as stuck. Do something different.`, true)) });
-      const label = toolMap[stuckOn.name]?.summarise ? toolMap[stuckOn.name].summarise(stuckOn.input) : stuckOn.name;
-      const why = `Stopped: it made the same ${stuckOn.name} call (${String(label).slice(0, 60)}) ${STUCK_REPEATS} times without changing anything, so it looks stuck. Tell it what to do differently, or say "continue".`;
-      if (tui?.notice) tui.notice(why, 'warn');
-      else if (!silent) out(c.yellow(`\n${why}`));
-      tui?.bellIfAway?.();
-      return { ...totals, stopReason: 'stuck' };
-    }
-
-    // Every call gets a result, whatever happened.
-    const results = [];
-    for (const call of calls) {
-      const tool = toolMap[call.name];
-      totals.tools += 1;
-
-      // Esc during a batch stops the REST of it. The check used to run once before the
-      // batch, so after Esc the remaining calls still prompted and ran.
-      if (signal?.aborted) {
-        results.push(result(call.id, 'Not run: the user stopped the task.', true));
-        continue;
-      }
-      if (planBlocked.has(call.id)) {
-        results.push(result(call.id, 'Not run: plan mode is on, so nothing is written and no command runs. Finish investigating with read-only tools, then present your plan as your answer — the user will switch modes when they want it carried out.', true));
-        continue;
-      }
-      if (!tool) {
-        results.push(result(call.id, `No such tool: ${call.name}`, true));
-        continue;
-      }
-      if (call.input?.__parse_error !== undefined) {
-        results.push(result(call.id, 'Your tool arguments were not valid JSON. Send them again.', true));
-        continue;
-      }
-
-      const label = tool.summarise ? tool.summarise(call.input) : call.name;
-      const activityId = tui?.recordActivity?.({ name: call.name, label, status: 'waiting' });
-      // One row per call, mutated in place through waiting → running → ok/failed. The
-      // previous surface printed a fresh line per state change, so a session with
-      // twenty tool calls scrolled sixty lines of near-duplicates past the answer.
-      const row = tui?.tool?.({ name: call.name, label, status: 'waiting', file: call.input?.path });
-
-      try {
-        await permissions.request(tool, call.input, { cwd, tui, signal });
-      } catch (e) {
-        if (e instanceof PermissionDenied) {
-          const declined = `  ${c.red(glyph('✗', 'x'))} ${c.dim('declined')}`;
-          if (row) row.update({ status: 'denied', error: e.comment ? `declined — "${e.comment}"` : 'declined' });
-          else if (tui) tui.print(declined);
-          else if (!silent) out(declined);
-          tui?.recordActivity?.({ id: activityId, name: call.name, label, status: 'failed', detail: 'Permission declined by user.' });
-          // Told to the model, not just the user: it needs to know to stop trying and
-          // propose something else instead. A decision comment rides along verbatim.
-          // A run that could not ask (one-shot, a script) says so — "the user declined"
-          // was untrue there, and hid the hint about --yes from everyone.
-          if (e.headless) totals.denied = (totals.denied || 0) + 1;
-          const note = e.headless
-            ? `Not permitted in this run: ${e.message} Do not retry it; finish what you can without it and say what was left undone.`
-            : e.comment
-              ? `The user declined this action with this instruction, which overrides your plan: "${e.comment}". Do not retry the declined action; follow the instruction instead.`
-              : `The user declined this action. Do not retry it; ask what they would prefer.`;
-          results.push(result(call.id, note, true));
-          continue;
-        }
-        throw e;
-      }
-
-      tui?.recordActivity?.({ id: activityId, name: call.name, label, status: 'running' });
-      row?.update({ status: 'running' });
-      const spin2 = tui ? { stop: () => {} } : (silent ? { stop: () => {} } : spinner(`${call.name}: ${label}`.slice(0, 100)));
-      const toolStarted = Date.now();
-      // Live elapsed ticker on the status row while a tool runs (1s cadence,
-      // silent when animations are off — progress you can watch, not noise).
-      let elapsedTimer = null;
-      const stopElapsed = () => { if (elapsedTimer) { clearInterval(elapsedTimer); elapsedTimer = null; } };
-      if (tui && tui.animationsOn?.()) {
-        const toolStatus = () => `${c.brand(glyph('•', '*'))} ${call.name}: ${c.dim(String(label).slice(0, 60))} ${c.dim(`· ${((Date.now() - toolStarted) / 1000).toFixed(0)}s`)}`;
-        tui.setStatus(toolStatus());
-        elapsedTimer = setInterval(() => tui.setStatus(toolStatus()), 1000);
-        if (elapsedTimer.unref) elapsedTimer.unref();
-      } else if (tui) {
-        tui.setStatus(`${c.brand(glyph('•', '*'))} ${call.name}: ${c.dim(String(label).slice(0, 70))}`);
-      }
-      try {
-        // Rewind safety net: before the agent overwrites or creates a file, remember
-        // what was there. write_file/edit_file take their targets from the input;
-        // run_command's target is unknowable, so its calls snapshot the whole
-        // tracked set instead (cheap: only files already touched this session).
-        if (journal && ['write_file', 'edit_file'].includes(call.name) && call.input?.path) {
-          try { journal.snapshotFile(path.resolve(cwd, String(call.input.path))); } catch { /* path never existed */ }
-        } else if (journal && call.name === 'run_command') {
-          journal.snapshotTracked(cwd);
-        }
-        const output = await tool.run(call.input, { cwd, signal });
-        spin2.stop(); stopElapsed();
-        const took = ((Date.now() - toolStarted) / 1000).toFixed(1);
-        // opencode tool icons: $ shell, ← edits, → reads, ✱ search,
-        // % fetch, ◈ websearch, ◉ subagents, ⚙ everything else. Done
-        // rows rest muted; failures stay red.
-        const done = `  ${toolMark(call.name)} ${c.dim(String(label).slice(0, 100))} ${c.dim(`· ${took}s`)}`;
-        if (row) {
-          tui.clearStatus();
-          // The whole output travels with the row (capped), so a click can open it.
-          row.update({ status: 'ok', took, preview: previewFor(call.name, output), full: String(output ?? '').slice(0, 200_000) });
-        } else if (tui) { tui.clearStatus(); tui.print(done, 'tool'); } else if (!silent) out(done);
-        tui?.recordActivity?.({ id: activityId, name: call.name, label, status: 'ok', detail: String(output).slice(0, 2000) });
-        onEvent?.({ type: 'tool_result', name: call.name, input: call.input, ok: true, output });
-        results.push(result(call.id, output, false));
-        // A changed file is progress: calls made after it are not repeats of those before.
-        if (['write_file', 'edit_file'].includes(call.name)) changes += 1;
-        // read_image: the pixels ride along as an image block in the tool-result
-        // message, so the model actually sees the picture instead of a caption of it.
-        // read_image: the pixels ride along in this message, after the results. When no
-        // image can be attached the call FAILED and says why — it used to report success
-        // either way, and the model then described a picture it never saw.
-        if (call.name === 'read_image') {
-          let block = null;
-          let why = '';
-          try { block = await readImageForModel(cwd, call.input?.path); } catch (e) { why = e.message; }
-          results[results.length - 1] = block
-            ? { ...result(call.id, 'The image is attached to this message, after the tool results.', false), __images: [block] }
-            : result(call.id, why || 'The image could not be attached.', true);
-        }
-        // todo_write: the checklist is for the human — checkbox cells with progress.
-        if (call.name === 'todo_write' && Array.isArray(call.input?.todos)) {
-          if (tui?.todo) tui.todo(call.input.todos);
-          else if (!silent) {
-            const icon = { pending: c.dim(glyph('☐', '[ ]')), in_progress: c.accent(glyph('◐', '[>]')), completed: c.accent(glyph('☑', '[x]')) };
-            for (const t of call.input.todos.slice(0, 12)) {
-              out(`  ${(icon[t?.status] || icon.pending)} ${t?.status === 'completed' ? c.dim(String(t?.task || '').slice(0, 90)) : String(t?.task || '').slice(0, 90)}`);
-            }
-          }
-        }
-
-        // A write or an edit shows what it actually did. The journal snapshotted the
-        // file a few lines above, so the "before" side is already in memory — and a
-        // claim like "Edited src/index.js" is exactly the kind of thing that turns out
-        // to have changed the wrong line.
-        if (tui?.diff && journal && ['write_file', 'edit_file'].includes(call.name) && call.input?.path) {
-          try {
-            const absolute = path.resolve(cwd, String(call.input.path));
-            const before = journal.latestSnapshot(absolute);
-            if (before !== null) {
-              const { readFileSync } = await import('node:fs');
-              const patch = unifiedDiff(before, readFileSync(absolute, 'utf8'), { file: call.input.path });
-              if (patch) tui.diff(String(call.input.path), patch);
-            }
-          } catch { /* a missing diff never blocks the turn */ }
-        }
-      } catch (e) {
-        spin2.stop(); stopElapsed();
-        const msg = e instanceof ToolError ? e.message : `${e.message}`;
-        const took = ((Date.now() - toolStarted) / 1000).toFixed(1);
-        const bad = `  ${c.red(glyph('✗', 'x'))} ${c.dim(String(label).slice(0, 80))} ${c.dim(`· ${took}s`)} — ${msg.slice(0, 120)}`;
-        if (row) {
-          tui.clearStatus();
-          row.update({ status: 'failed', took, error: msg.split('\n')[0].slice(0, 200), preview: msg.includes('\n') ? msg : '', full: msg.slice(0, 200_000) });
-        } else if (tui) { tui.clearStatus(); tui.print(bad, 'tool'); } else if (!silent) out(bad);
-        tui?.recordActivity?.({ id: activityId, name: call.name, label, status: 'failed', detail: msg.slice(0, 2000) });
-        onEvent?.({ type: 'tool_result', name: call.name, input: call.input, ok: false, error: msg });
-        results.push(result(call.id, msg, true));
-      }
-    }
-
-    // Every tool_result first, then any images, in the same user message. Anthropic's
-    // format requires the results to lead the message; an image between two results
-    // (read_image followed by another call in one batch) was a rejected request.
-    const images = [];
-    for (const r of results) {
-      for (const img of r.__images || []) images.push(img);
-      delete r.__images;
-    }
-    messages.push({ role: 'user', content: [...results, ...images] });
-    if (signal?.aborted) {
-      if (!silent) out(c.yellow(`  ${glyph('⏹', '[x]')}  Interrupted.`));
-      return { ...totals, stopReason: 'interrupted' };
-    }
-  }
-
-  if (!silent) out(c.yellow(`\nStopped after ${maxIterations} steps — the safety limit for one request. Say "continue" to keep going.`));
-  tui?.bellIfAway?.();
-  return { ...totals, stopReason: 'max_iterations' };
-}
-
-/**
- * A read-only subagent, as a tool the model can call.
- *
- * The point is context, not concurrency. "Find every place that reads the session file"
- * costs forty tool results, and forty tool results spent in the main conversation are
- * forty tool results the main conversation is still carrying three turns later. A
- * subagent spends them in its own window and returns the paragraph that mattered.
- *
- * Read-only by construction: it is handed a permissions object in plan mode, so every
- * write and every shell command is refused no matter what the parent's mode is. A
- * subagent the user never sees must not be able to change the disk.
- */
-function makeSubagentTool({ client, model, cwd, signal, tui, permissions = null }) {
-  return {
-    name: 'task',
-    needsPermission: false,
-    description: 'Delegate a read-only investigation to a separate agent with its own context window. '
-      + 'Use it when answering needs a lot of searching and reading whose intermediate output you do not need to keep — '
-      + '"find every caller of X", "work out how Y is wired", "check whether Z is covered by tests". '
-      + 'The subagent can read, list, search and fetch, but cannot write files or run commands. '
-      + 'Give it a self-contained brief: it cannot see this conversation. It returns its findings as text.',
-    input_schema: {
-      type: 'object',
-      properties: {
-        description: { type: 'string', description: 'Three to five words naming the task, for the activity row.' },
-        prompt: { type: 'string', description: 'The full self-contained brief, including what to report back.' },
-      },
-      required: ['description', 'prompt'],
-    },
-    summarise: (input) => String(input.description || 'subagent'),
-    async run(input, { cwd: runCwd }) {
-      const { createPermissions } = await import('./permissions.js');
-      const messages = [{ role: 'user', content: String(input.prompt || '') }];
-      let answer = '';
-      const result = await runAgent({
-        client,
-        messages,
-        model,
-        cwd: runCwd || cwd,
-        permissions: permissions?.fork ? permissions.fork({ mode: 'plan', interactive: false }) : createPermissions({ mode: 'plan', interactive: false }),
-        signal,
-        tui: null,
-        silent: true,
-        subagents: false,
-        // Read-only research across a codebase is many small reads; 20 cut it off
-        // mid-search. The stuck detector is what catches a loop.
-        maxIterations: 100,
-        extraSystem: '\n\nYou are a subagent. You cannot ask questions and nobody will read your intermediate '
-          + 'steps — only your final message. End with the findings themselves, with exact file paths and line '
-          + 'numbers where they apply, not a description of how you looked.',
-        onText: (text) => { answer += text; },
-      });
-      const trimmed = answer.trim();
-      if (!trimmed) return `The subagent finished (${result.stopReason}) without reporting anything.`;
-      return `${trimmed}\n\n[subagent: ${result.tools} tool calls, ${result.input + result.output} tokens]`;
-    },
-  };
-}
-
-/**
- * What of a tool's output is worth putting on screen.
- *
- * Not everything: a `read_file` the agent asked for is the agent's business, and
- * echoing 400 lines of it buries the reasoning that follows. A command's output, a
- * search's hits and a fetch's first lines are the ones a human reads over the agent's
- * shoulder — so those get a preview and the rest get a row.
- */
-function previewFor(name, output) {
-  const text = String(output ?? '');
-  if (!text.trim()) return '';
-  switch (name) {
-    case 'run_command':
-    case 'background_read':
-      return text;
-    case 'search':
-    case 'list_files':
-    case 'web_search':
-      return text;
-    case 'web_fetch':
-      return text.split('\n').slice(0, 8).join('\n');
-    case 'read_file':
-    case 'read_image':
-    case 'write_file':
-    case 'edit_file':
-    case 'todo_write':
-      return '';
-    default:
-      return text.length > 400 ? '' : text;
-  }
-}
-
-function result(id, content, isError) {
-  return { type: 'tool_result', tool_use_id: id, content: String(content), is_error: isError };
-}
+// ─── The agent loop ─────────────────────────────────────────────────────────────
+//
+// Send the conversation to Jaitus, stream the reply, run any tools it asked for, append
+// the results, and go again — until it stops asking for tools. That is the whole idea;
+// everything else here is making it behave under real conditions.
+//
+// Notes on the parts that are easy to get wrong:
+//
+//   • Streaming is parsed as server-sent events. Tool arguments arrive as `input_json_delta`
+//     fragments that only become valid JSON once concatenated, so they are buffered per
+//     content block and parsed at the end, never incrementally.
+//   • The assistant turn is appended EXACTLY as the model produced it, tool_use blocks
+//     included. Paraphrasing it breaks the pairing with tool_result and the next turn
+//     is rejected.
+//   • Every tool_use must get a tool_result, including ones that failed or were refused.
+//     A missing result is a malformed conversation, and the error text is also how the
+//     model learns to try something else.
+//   • A stuck detector, not a step count. A model caught in a loop would otherwise spend
+//     real money until someone notices — but a fixed cap of 40 steps also stopped every
+//     long, perfectly healthy task halfway and made the user type "continue". A run now
+//     ends when the model finishes, or when it repeats the same call with the same input
+//     STUCK_REPEATS times with no file changed in between (see `stuck` below). A very
+//     high backstop remains so no run is unbounded.
+
+import { byName, toolSchemas, ToolError, readImageForModel } from './tools.js';
+import { PermissionDenied } from './permissions.js';
+import path from 'node:path';
+import fs from 'node:fs';
+import os from 'node:os';
+import { loadContext, loadIgnore, CONTEXT_FILE } from '../project.js';
+import { c, out, write, spinner, glyph } from '../ui.js';
+import { discoverMcpTools } from '../mcp.js';
+import { unifiedDiff } from '../diff.js';
+import { fromResponse, fromGatewayBody, JaitusError } from '../errors.js';
+import { explainFailure } from '../serviceNotice.js';
+
+const MAX_ITERATIONS = 1000;
+const STUCK_REPEATS = 4;
+const POLLING_TOOLS = new Set(['background_read', 'background_list']);
+
+// Room for a long answer or a large file in one reply. The models behind Jaitus reason
+// before they answer, and that reasoning is spent from the same budget — at 8192 a long
+// answer, or any file of a few hundred lines, was cut off partway.
+export const MAX_OUTPUT_TOKENS = 32000;
+
+// A reply that stopped before it finished — the output limit, or a connection dropped
+// somewhere between the provider and here — is continued, not presented as the answer.
+// Bounded, so a model that never finishes cannot loop on the user's allowance.
+export const MAX_CONTINUATIONS = 4;
+export const CONTINUE_NOTE = 'Your previous reply was cut off before it finished (an output limit or a dropped connection). '
+  + 'Continue from exactly where it stopped: do not repeat or summarise what you already wrote, and do not mention this note. '
+  + 'If you were in the middle of a tool call, make that call again in full.';
+
+// A request that failed before anything arrived (a network blip) is tried again this
+// many times before it is reported.
+const NETWORK_RETRIES = 2;
+
+// Gateway answers that mean "not right now", not "no".
+const TRANSIENT_CODES = new Set(['busy', 'unavailable', 'timeout', 'interrupted', 'internal', 'maintenance']);
+const BUSY_RETRIES = 3;
+const MAX_RETRY_WAIT_MS = 30_000;
+// A blip (busy, unavailable, timed out) is retried quickly or not at all. The gateway's
+// Retry-After for these is 30-60 s, and waiting that out three times kept the user on
+// "Working…" for a minute and a half before saying anything — with every provider
+// switched off, the "Jaitus is unavailable" that used to appear at once took 90 s.
+const BLIP_MAX_WAIT_MS = 8_000;
+
+/** How long to wait before retrying `e`, or null when it must not be retried. */
+export function retryDelay(e, attempt = 0) {
+  const code = e?.code;
+  // The gateway knows when trying again cannot help (nothing is switched on to answer).
+  if (e?.noRetry) return null;
+  const hinted = Number(e?.retryAfter) > 0 ? Number(e.retryAfter) * 1000 : null;
+  if (code === 'rate_limited') {
+    // A short window is waited out; a cap that resets in hours is a limit, not a blip.
+    if (hinted == null) return 2000 * (attempt + 1);
+    return hinted <= MAX_RETRY_WAIT_MS ? hinted : null;
+  }
+  if (!TRANSIENT_CODES.has(code) || code === 'internal') return null;
+  if (hinted != null) return Math.min(BLIP_MAX_WAIT_MS, hinted);
+  // ±25% spread: every CLI cut off by the same restart would otherwise retry in the
+  // same instant and arrive together.
+  return Math.min(BLIP_MAX_WAIT_MS, Math.round(2000 * 2 ** attempt * (0.75 + Math.random() * 0.5)));
+}
+
+function sleepUnlessAborted(ms, signal) {
+  return new Promise((resolve) => {
+    if (signal?.aborted) return resolve(false);
+    const t = setTimeout(() => { signal?.removeEventListener?.('abort', onAbort); resolve(true); }, ms);
+    const onAbort = () => { clearTimeout(t); resolve(false); };
+    signal?.addEventListener?.('abort', onAbort, { once: true });
+  });
+}
+
+/** opencode tool icon per tool, muted when done. ASCII twins included. */
+const TOOL_MARKS = {
+  run_command: ['$', '$'], read_file: ['→', '>'], read_image: ['→', '>'],
+  list_files: ['→', '>'], write_file: ['←', '<'], edit_file: ['←', '<'],
+  search: ['✱', '*'], web_fetch: ['%', '%'], web_search: ['◈', 'o'],
+  background_run: ['◉', 'o'], todo_write: ['⚙', '*'],
+};
+const toolMark = (name) => {
+  const [uni, ascii] = TOOL_MARKS[name] || ['⚙', '*'];
+  return c.dim(glyph(uni, ascii));
+};
+
+export const SYSTEM_PROMPT = `You are Jaitus, a coding agent running in a developer's terminal, inside their project directory.
+
+You work directly on this computer. Your tools read, search, create and edit the files in
+the project and run shell commands in it, and you can fetch web pages. When the user asks
+about their files, their code or their machine, use the tools and answer from what you
+find — never say you cannot access local files, because you can.
+
+How to work:
+- Investigate before you change anything. Read the files you are about to edit; do not guess at their contents.
+- Prefer edit_file over write_file for existing files. Keep changes minimal and in the style of the surrounding code.
+- Run the project's own tests or build after a change when one exists, and report the real result — including when it fails.
+- Use run_command for anything the shell does better: git, tests, package managers, linters.
+- Never invent a file path, a function name, or a test result. If you are unsure, look.
+- Every turn re-sends the whole conversation, so make independent reads, searches and
+  listings together in ONE turn rather than one per turn. Read the part of a large file you
+  need (offset/limit) rather than all of it.
+- For current news or other web facts, report only details grounded in web_search or
+  web_fetch output. Include the supplied source URLs; never fill a missing headline or
+  date from memory.
+
+How to talk:
+- Be concise. This is a terminal, not a document.
+- Say what you did and what happened, not what you are about to do.
+- If something is blocked or you are missing information, say so plainly and ask.
+- No preamble, no restating the question back.`;
+
+/**
+ * The project's own briefing, appended to the system prompt.
+ *
+ * Fenced and labelled rather than concatenated, so instructions written by whoever owns
+ * the repo are visibly the repo's and cannot be mistaken for part of Jaitus's own rules.
+ */
+/**
+ * Where the agent is: the facts it would otherwise guess at, and guess wrong.
+ *
+ * Without these, the model did not know which folder it was in, which OS its commands
+ * would run on (cmd.exe and /bin/sh disagree about almost everything), or today's date —
+ * and a model that does not know where it is tends to say it cannot see your files. The
+ * listing is the top level only, names not contents, and respects .jaitusignore.
+ */
+export function environmentBlock(cwd, { now = new Date(), platform = process.platform } = {}) {
+  if (!cwd) return '';
+  const osName = { win32: 'Windows', darwin: 'macOS', linux: 'Linux' }[platform] || platform;
+  const shell = platform === 'win32' ? 'cmd.exe (run_command uses it)' : '/bin/sh (run_command uses it)';
+  // The repository may start above the working directory, and .git may be a file that
+  // points elsewhere (a worktree or submodule).
+  let branch = null;
+  for (let dir = cwd, i = 0; i < 40; i++) {
+    const dotGit = path.join(dir, '.git');
+    try {
+      let gitDir = dotGit;
+      if (fs.statSync(dotGit).isFile()) {
+        const m = /^gitdir:\s*(.+)$/m.exec(fs.readFileSync(dotGit, 'utf8'));
+        if (m) gitDir = path.resolve(dir, m[1].trim());
+      }
+      const head = fs.readFileSync(path.join(gitDir, 'HEAD'), 'utf8').trim();
+      branch = head.startsWith('ref: refs/heads/') ? head.slice(16) : `detached at ${head.slice(0, 7)}`;
+      break;
+    } catch { /* not here; look one level up */ }
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  let listing = '';
+  try {
+    const ignore = loadIgnore(cwd);
+    const SKIP = new Set(['.git', 'node_modules']);
+    const names = fs.readdirSync(cwd, { withFileTypes: true })
+      .filter((d) => !SKIP.has(d.name) && !ignore.matches(d.isDirectory() ? `${d.name}/` : d.name) && !ignore.matches(d.name))
+      .map((d) => (d.isDirectory() ? `${d.name}/` : d.name))
+      .sort((a, b) => (b.endsWith('/') - a.endsWith('/')) || a.localeCompare(b));
+    const MAX = 60;
+    listing = names.slice(0, MAX).join('\n') + (names.length > MAX ? `\n… and ${names.length - MAX} more` : '');
+  } catch { /* unreadable: the tools will say why */ }
+  return `
+
+<environment>
+Working directory: ${cwd}
+Platform: ${osName} (${os.release()})
+Shell: ${shell}
+Today: ${now.toISOString().slice(0, 10)}
+Git: ${branch ? `yes, branch ${branch}` : 'no repository at this folder'}
+Top level of the working directory:
+${listing || '(empty)'}
+</environment>`;
+}
+
+export function systemPrompt(cwd) {
+  const project = cwd ? loadContext(cwd) : null;
+  const base = `${SYSTEM_PROMPT}${environmentBlock(cwd)}`;
+  if (!project) return base;
+  return `${base}
+
+The project you are working in ships a ${CONTEXT_FILE} with notes for you. Follow it where
+it applies, and prefer what it says over your own assumptions about this codebase.
+
+<${CONTEXT_FILE}>
+${project}
+</${CONTEXT_FILE}>`;
+}
+
+/**
+ * Every earlier image is sent again with every request, and the gateway accepts at most
+ * 10 MB per request — three or four screenshots into a conversation, every turn failed.
+ * The newest images are kept up to IMAGE_BUDGET bytes of base64; older ones are replaced
+ * by a line saying one was there. The history itself is not changed.
+ */
+/**
+ * Make a history well-formed after any interruption: every assistant tool_use has a
+ * tool_result in the next message. A run stopped by Esc, a failed permission prompt or
+ * a gateway error partway through could leave a tool call with no result — and both
+ * provider formats reject that, so every later request in the session failed. Missing
+ * results are filled in as "not run"; an assistant turn that ends the history with tool
+ * calls gets its results appended.
+ */
+export function repairToolPairs(messages) {
+  for (let i = 0; i < messages.length; i++) {
+    const m = messages[i];
+    if (m?.role !== 'assistant' || !Array.isArray(m.content)) continue;
+    const ids = m.content.filter((b) => b?.type === 'tool_use').map((b) => b.id);
+    if (!ids.length) continue;
+    const next = messages[i + 1];
+    const have = new Set(next?.role === 'user' && Array.isArray(next.content)
+      ? next.content.filter((b) => b?.type === 'tool_result').map((b) => b.tool_use_id) : []);
+    const missing = ids.filter((id) => !have.has(id));
+    if (!missing.length) continue;
+    const filled = missing.map((id) => result(id, 'Not run: the task was interrupted before this step.', true));
+    if (next?.role === 'user') {
+      const content = Array.isArray(next.content) ? next.content : [{ type: 'text', text: String(next.content ?? '') }];
+      const results = content.filter((b) => b?.type === 'tool_result');
+      const rest = content.filter((b) => b?.type !== 'tool_result');
+      messages[i + 1] = { ...next, content: [...results, ...filled, ...rest] };
+    } else {
+      messages.splice(i + 1, 0, { role: 'user', content: filled });
+    }
+  }
+  return messages;
+}
+
+// ── Keeping the conversation small ────────────────────────────────────────────
+//
+// Every request re-sends the whole conversation, and in real use that re-send — cached,
+// but not free — was ~75% of what a session cost: 109 requests averaged 46k tokens of
+// context each, most of it tool output from many steps ago (a file read at step 3 is
+// still paid for at step 60). This is the documented "clear old tool results" strategy
+// (Anthropic's context editing, clear_tool_uses; Claude Code's micro-compaction): once
+// the conversation passes TRIM_AT, the outputs of all but the KEEP_RECENT latest tool
+// calls are replaced with a line saying they were cleared and can be re-run. It clears
+// at least TRIM_AT_LEAST at a time, because each clearing breaks the prompt cache once
+// — clearing a little on every step would cost more than it saves. Small results (a
+// "file written", an exit code) are kept: they carry meaning and cost nothing.
+// 100k was the documented default for 200k-window models. Here the window is up to 1M, so
+// that ceiling was rarely near: production requests averaged 53k tokens and two thirds of
+// all input tokens came from requests over 60k. At 40k a clearing (one cache break, ~17
+// credits on glm-5.3-flash) pays for itself within about ten later requests.
+export const TRIM_AT = 40_000;          // estimated tokens of conversation
+export const KEEP_RECENT = 6;           // latest tool results always kept whole
+export const TRIM_AT_LEAST = 12_000;    // estimated tokens a clearing must free
+const TRIM_MIN_CHARS = 1_500;           // results shorter than this are never cleared
+const CLEARED = '[Output cleared';
+
+const blockChars = (b) => {
+  if (b?.type === 'text') return (b.text || '').length;
+  if (b?.type === 'tool_use') return JSON.stringify(b.input || {}).length;
+  if (b?.type === 'tool_result') return typeof b.content === 'string' ? b.content.length : JSON.stringify(b.content || '').length;
+  return 0;
+};
+export function conversationTokens(messages) {
+  let chars = 0;
+  for (const m of messages || []) chars += typeof m?.content === 'string' ? m.content.length : (Array.isArray(m?.content) ? m.content.reduce((n, b) => n + blockChars(b), 0) : 0);
+  return Math.ceil(chars / 4);
+}
+
+/**
+ * Clear old tool outputs in place when the conversation is large. Returns how many
+ * estimated tokens were freed (0 when nothing was worth clearing).
+ */
+export function clearOldToolResults(messages, { at = TRIM_AT, keep = KEEP_RECENT, atLeast = TRIM_AT_LEAST } = {}) {
+  if (conversationTokens(messages) < at) return 0;
+  const names = new Map();
+  for (const m of messages) {
+    if (m?.role === 'assistant' && Array.isArray(m.content)) for (const b of m.content) if (b?.type === 'tool_use') names.set(b.id, b.name);
+  }
+  const results = [];
+  for (const m of messages) {
+    if (m?.role !== 'user' || !Array.isArray(m.content)) continue;
+    m.content.forEach((b, i) => { if (b?.type === 'tool_result') results.push({ m, i, b }); });
+  }
+  const candidates = results.slice(0, Math.max(0, results.length - keep)).filter(({ b }) => {
+    const text = typeof b.content === 'string' ? b.content : '';
+    return text.length >= TRIM_MIN_CHARS && !text.startsWith(CLEARED);
+  });
+  const freed = Math.ceil(candidates.reduce((n, { b }) => n + blockChars(b), 0) / 4);
+  if (freed < atLeast) return 0;
+  for (const { m, i, b } of candidates) {
+    const chars = blockChars(b);
+    const name = names.get(b.tool_use_id) || 'this tool';
+    m.content[i] = { ...b, content: `${CLEARED}: ${name} returned ${chars.toLocaleString()} characters here, removed to keep the conversation small. Run it again if you need it.]` };
+  }
+  return freed;
+}
+
+export const IMAGE_BUDGET = 6_000_000;
+export function withinImageBudget(messages, budget = IMAGE_BUDGET) {
+  let used = 0;
+  let changed = false;
+  const out = messages.slice();
+  for (let i = out.length - 1; i >= 0; i--) {
+    const m = out[i];
+    if (!Array.isArray(m?.content) || !m.content.some((b) => b?.type === 'image')) continue;
+    // Walk this message's blocks newest-last, so within a message the later images win.
+    const kept = new Array(m.content.length);
+    for (let j = m.content.length - 1; j >= 0; j--) {
+      const b = m.content[j];
+      if (b?.type !== 'image') { kept[j] = b; continue; }
+      const size = String(b.source?.data || '').length;
+      if (used + size <= budget) { used += size; kept[j] = b; continue; }
+      kept[j] = { type: 'text', text: '[An image was attached here earlier; it is no longer included, to keep the request small.]' };
+      changed = true;
+    }
+    out[i] = { ...m, content: kept };
+  }
+  return changed ? out : messages;
+}
+
+/** One streamed request. Returns { content, stopReason, usage }. */
+export async function streamTurn({ client, messages, model, system, tools, onText, onToolStart, signal, maxTokens = MAX_OUTPUT_TOKENS }) {
+  const res = await client.messages({
+    model,
+    max_tokens: maxTokens,
+    system: system || SYSTEM_PROMPT,
+    tools,
+    messages: withinImageBudget(messages),
+    stream: true,
+  }, { signal });
+
+  if (!res.ok) throw await fromResponse(res);
+  const requestId = res.headers?.get?.('x-request-id') || '';
+
+  // Blocks are keyed by the index the stream gives them, because they interleave.
+  const blocks = new Map();
+  let stopReason = null;
+  // Whether the stream ended the way a finished message ends. A stream that just stops
+  // — no message_stop, no stop reason — was cut, and used to be taken as a complete,
+  // silent answer: the "it stops midway for no reason" bug.
+  let sawStop = false;
+  // `credits` is what the gateway counted against the plan for this request — real cost,
+  // the one unit the plan, the dashboard and this CLI all show.
+  const usage = { input_tokens: 0, output_tokens: 0, cache_read_input_tokens: 0, cache_creation_input_tokens: 0, credits: 0 };
+  // Usage can arrive at the START of a stream (Anthropic-format providers) or only at
+  // the END, in message_delta (OpenAI-format providers, translated by the gateway —
+  // their usage exists only once generation finishes). Reading input from message_start
+  // alone recorded every OpenAI-format turn as 0 input tokens.
+  const takeUsage = (u) => {
+    if (!u) return;
+    for (const k of ['input_tokens', 'output_tokens', 'cache_read_input_tokens', 'cache_creation_input_tokens', 'credits']) {
+      if (u[k] != null && Number.isFinite(Number(u[k]))) usage[k] = Number(u[k]);
+    }
+  };
+  let buffer = '';
+  // A stream that never ends must die here, not in GC hell: the buffer below grows
+  // with every chunk and each arrival re-splits all of it, so a runaway provider
+  // (twelve silent minutes and counting, seen in the wild) grows memory
+  // quadratically until V8 falls over near 4 GB. Past the cap the turn ends as a
+  // cut (continued from what arrived) or, with nothing received, as a retryable
+  // timeout — never as a crash.
+  const MAX_STREAM_BUFFER = 8 * 1024 * 1024;
+  // A failure reported INSIDE the stream, after a 200. Recorded here and thrown after
+  // the parse below: handle() runs inside a try whose catch exists to skip keepalives,
+  // so throwing from it would be swallowed — which is how a mid-stream error used to
+  // end an answer halfway with no explanation at all.
+  let streamError = null;
+
+  const handle = (event) => {
+    switch (event.type) {
+      case 'error':
+        streamError = fromGatewayBody(200, event, { requestId });
+        break;
+      case 'message_start':
+        takeUsage(event.message?.usage);
+        break;
+      case 'content_block_start': {
+        const b = event.content_block || {};
+        blocks.set(event.index, b.type === 'tool_use'
+          ? { type: 'tool_use', id: b.id, name: b.name, json: '' }
+          : { type: 'text', text: '' });
+        if (b.type === 'tool_use') onToolStart?.(b.name);
+        break;
+      }
+      case 'content_block_delta': {
+        const b = blocks.get(event.index);
+        if (!b) break;
+        const d = event.delta || {};
+        if (d.type === 'text_delta' && typeof d.text === 'string') {
+          b.text += d.text;
+          onText?.(d.text);
+        } else if (d.type === 'input_json_delta' && typeof d.partial_json === 'string') {
+          b.json += d.partial_json;
+        }
+        break;
+      }
+      case 'message_delta':
+        if (event.delta?.stop_reason) stopReason = event.delta.stop_reason;
+        takeUsage(event.usage);
+        break;
+      case 'message_stop':
+        sawStop = true;
+        break;
+      default:
+        break;
+    }
+  };
+
+  // fetch() yields Uint8Array, NOT a Node Buffer. `uint8.toString('utf8')` ignores the
+  // argument and returns "101,118,101,…" — comma-joined byte values — so the whole
+  // stream parses to nothing and the agent appears to answer with silence.
+  //
+  // TextDecoder with stream:true is also the only correct choice for a different reason:
+  // a multi-byte character can be split across two chunks, and decoding each chunk
+  // independently would corrupt it. The decoder holds the partial bytes until complete.
+  const decoder = new TextDecoder();
+
+  let cut = false;
+  try {
+    for await (const chunk of res.body) {
+      buffer += decoder.decode(chunk, { stream: true });
+      if (buffer.length > MAX_STREAM_BUFFER) {
+        // Breaking the loop releases the reader (the socket is cancelled), so the
+        // runaway stops arriving too — not just stops being kept.
+        if (!blocks.size) throw new JaitusError({ code: 'timeout', status: 504, message: 'Jaitus took too long to respond. Try again.' });
+        cut = true;
+        break;
+      }
+      const frames = buffer.split('\n\n');
+      buffer = frames.pop() || '';
+      for (const frame of frames) {
+        for (const line of frame.split('\n')) {
+          if (!line.startsWith('data:')) continue;
+          const raw = line.slice(5).trim();
+          if (!raw || raw === '[DONE]') continue;
+          try { handle(JSON.parse(raw)); } catch { /* keepalive or partial */ }
+        }
+      }
+      if (streamError) break;
+    }
+  } catch (e) {
+    // Esc is the only abort that reads as an interruption. Any OTHER AbortError —
+    // the request timeout in api.js firing mid-body, a dropped socket — is a `timeout`
+    // JaitusError so the agent loop backs off and retries it (TRANSIENT_CODES) instead
+    // of reporting "Interrupted." for something the user never stopped.
+    if (signal?.aborted) throw e;
+    // The connection dropped (or went silent) mid-answer. What arrived is kept and
+    // continued from; with nothing received yet, the caller retries the request.
+    if (!blocks.size) {
+      if (e?.name === 'AbortError') throw new JaitusError({ code: 'timeout', status: 504, message: 'Jaitus took too long to respond. Try again.' });
+      throw e;
+    }
+    cut = true;
+  }
+  if (streamError) {
+    // The provider dropped out after part of the answer had arrived. What arrived is
+    // kept and continued from, exactly as when OUR connection drops — it used to be
+    // thrown away with a "Something went wrong" and the task stopped.
+    if (blocks.size && TRANSIENT_CODES.has(streamError.code)) cut = true;
+    else throw streamError;
+  }
+  if (cut || (!sawStop && !stopReason)) stopReason = 'cut';
+
+  const content = [...blocks.entries()]
+    .sort((a, b) => a[0] - b[0])
+    .map(([, b]) => {
+      if (b.type !== 'tool_use') return { type: 'text', text: b.text };
+      let input = {};
+      // The fragments only form valid JSON once joined. An empty string is a
+      // no-argument call, which is legitimate.
+      try { input = b.json.trim() ? JSON.parse(b.json) : {}; } catch { input = { __parse_error: b.json }; }
+      return { type: 'tool_use', id: b.id, name: b.name, input };
+    })
+    .filter((b) => b.type !== 'text' || b.text.length);
+
+  return { content, stopReason, usage };
+}
+
+/**
+ * Run one user request to completion.
+ * `messages` is mutated so the caller keeps the conversation across turns.
+ */
+export async function runAgent({
+  client, messages, model, cwd, permissions, signal, tui = null,
+  extraSystem = '', maxIterations = MAX_ITERATIONS, silent = false,
+  onText = null, onEvent = null, systemOverride = null, journal = null,
+  subagents = true, onContext = null, trimContext = true,
+}) {
+  // Loop detection. A call is identified by its tool, its input, and how many files had
+  // been changed when it was made — so edit → test → edit → test is progress (the count
+  // moves), while reading the same file over and over is not.
+  let changes = 0;
+  const repeats = new Map();
+  // input = fresh input, cached = prompt-cache reads (billed far cheaper), and
+  // context = the real size of the last prompt sent, as the provider counted it.
+  const totals = { input: 0, cached: 0, output: 0, tools: 0, context: 0, credits: 0 };
+  // Read once per request, not per turn: an agent that rewrites JAITUS.md mid-task
+  // should not change the rules it is being judged by halfway through.
+  // The model is told when it is in plan mode — it used to find out only by having its
+  // writes refused, after it had already tried them.
+  const planNote = permissions?.mode === 'plan'
+    ? '\n\nPLAN MODE is on: you can read, list, search and fetch, but nothing you write and no command you run will be carried out. Investigate, then answer with a concrete plan (files, changes, order, risks). The user switches modes when they want it done.'
+    : '';
+  const system = `${systemOverride || systemPrompt(cwd)}${extraSystem}${planNote}`;
+  const mcp = await discoverMcpTools(cwd).catch(() => []);
+  // Subagents are offered only to the top-level agent. A subagent that can spawn
+  // subagents is an unbounded fan-out on a metered gateway, and the depth that would
+  // actually help — one — is the depth that is safe.
+  const subagent = subagents ? makeSubagentTool({ client, model, cwd, signal, tui, permissions }) : null;
+  const availableTools = [
+    ...toolSchemas(),
+    ...(subagent ? [{ name: subagent.name, description: subagent.description, input_schema: subagent.input_schema }] : []),
+    ...mcp.map((tool) => ({ name: tool.name, description: tool.description, input_schema: tool.input_schema })),
+  ];
+  const toolMap = {
+    ...byName,
+    ...(subagent ? { [subagent.name]: subagent } : {}),
+    ...Object.fromEntries(mcp.map((tool) => [tool.name, tool])),
+  };
+
+  let continuations = 0;
+  let networkRetries = 0;
+  let busyRetries = 0;
+  let planNoticeShown = false;
+  // True while the previous reply is being continued: its text is still on screen as
+  // one live message, and the continuation must extend it rather than start another.
+  let continuing = false;
+
+  for (let iteration = 0; iteration < maxIterations; iteration++) {
+    // Old tool outputs are cleared once the conversation is large (see TRIM_AT) — in
+    // place, so the saved session shrinks too and the cache stays warm afterwards.
+    if (trimContext) {
+      const freed = clearOldToolResults(messages);
+      if (freed && tui?.notice) tui.notice(`Cleared old tool output (~${Math.round(freed / 1000)}k tokens) to keep each request small.`, 'info');
+    }
+    let streamed = false;
+    const spin = tui ? { stop: () => {}, update: () => {} } : (silent ? { stop: () => {}, update: () => {} } : spinner(glyph('Working…', 'Working...')));
+    if (tui) tui.setStatus(`${c.brand(glyph('•', '*'))} ${c.brand(glyph('Working…', 'Working...'))}`);
+    // Codex-style assistant cell: the • leads the turn the way › leads the
+    // user's. In scrollback the marker lands before the first streamed chunk.
+    let turnVoiced = false;
+
+    let turn;
+    try {
+      turn = await streamTurn({
+        client,
+        messages,
+        model,
+        system,
+        tools: availableTools,
+        signal,
+        onText: (text) => {
+          onText?.(text);
+          if (!streamed) {
+            spin.stop(); streamed = true;
+            if (tui) tui.clearStatus();
+            else if (!silent && !onText) { out(''); write(`${c.dim(glyph('•', '*'))} `); }
+          }
+          if (tui) {
+            // The transcript entry draws its own speaker mark now, so the loop no
+            // longer prepends one — two marks on the same line was the tell that the
+            // renderer and the loop each thought they owned the lead glyph.
+            turnVoiced = true;
+            tui.printStream(text);
+          } else if (!silent && !onText) write(text);
+        },
+        onToolStart: () => spin.update(glyph('Working…', 'Working...')),
+      });
+    } catch (e) {
+      spin.stop();
+      // Esc during streaming: stop mid-sentence, keep what landed, don't treat it
+      // as an error. The partial text is already on screen.
+      // A network failure before anything arrived: try again, briefly, before reporting.
+      // Anything the gateway itself refused (a limit, a sign-in problem) has a status and
+      // is reported at once — retrying it would only repeat the refusal.
+      if (!(signal?.aborted || e?.name === 'AbortError') && !e?.status && networkRetries < NETWORK_RETRIES) {
+        networkRetries += 1;
+        await new Promise((r) => setTimeout(r, 800 * networkRetries));
+        iteration -= 1;
+        continue;
+      }
+      // Busy, rate-limited for a moment, unavailable, timed out: the gateway says to
+      // back off and retry (it sends Retry-After), and nothing used to — one provider 429
+      // ended a task halfway. A limit (plan, free tier, a daily cap hours away) or a
+      // sign-in problem is never retried.
+      const wait = retryDelay(e, busyRetries);
+      if (!(signal?.aborted || e?.name === 'AbortError') && wait != null && busyRetries < BUSY_RETRIES) {
+        busyRetries += 1;
+        const secs = Math.max(1, Math.round(wait / 1000));
+        const what = e?.code === 'busy' || e?.code === 'rate_limited' ? 'Jaitus is busy' : (e?.title || 'Jaitus did not answer');
+        if (tui?.setStatus) tui.setStatus(`${c.yellow('!')} ${c.dim(`${what} — trying again in ${secs}s (${busyRetries} of ${BUSY_RETRIES})`)}`);
+        const ok = await sleepUnlessAborted(wait, signal);
+        tui?.clearStatus?.();
+        if (!ok) return { ...totals, stopReason: 'interrupted' };
+        iteration -= 1;
+        continue;
+      }
+      if (signal?.aborted || e?.name === 'AbortError') {
+        if (tui) tui.flushStream();
+        if (streamed && !silent) out('');
+        if (tui?.notice) tui.notice('Interrupted.', 'warn');
+        else if (tui) tui.print(c.yellow(`  ${glyph('⏹', '[x]')}  Interrupted.`));
+        else if (!silent) out(c.yellow(`  ${glyph('⏹', '[x]')}  Interrupted.`));
+        return { ...totals, stopReason: 'interrupted' };
+      }
+      // Out of retries: say what the status page knows (back-at time, known problem).
+      // Asked of the same service the request went to; a client with no address (a test
+      // double) asks nothing.
+      if (client?.baseUrl) await explainFailure(e, { baseUrl: client.baseUrl }).catch(() => {});
+      throw e;
+    }
+    spin.stop();
+    networkRetries = 0;
+    busyRetries = 0;
+    // A reply the provider's content filter stopped is cut short; say so rather than
+    // letting half an answer pass for the whole one.
+    if (turn.stopReason === 'refusal') {
+      const why = 'The answer was stopped partway by a content filter. Rephrasing the request usually gets past it.';
+      if (tui?.notice) tui.notice(why, 'warn');
+      else if (!silent) out(c.yellow(`  ${why}`));
+    }
+    const incomplete = turn.stopReason === 'max_tokens' || turn.stopReason === 'cut';
+    // A tool call cut off halfway has JSON that is not whole; it is dropped and the model
+    // is asked to make it again.
+    if (incomplete) turn.content = turn.content.filter((b) => b.type !== 'tool_use' || b.input?.__parse_error === undefined);
+    const willContinue = incomplete && continuations < MAX_CONTINUATIONS && !turn.content.some((b) => b.type === 'tool_use');
+    if (!willContinue) {
+      if (tui) tui.flushStream();
+      if (streamed || continuing) { if (tui) tui.printStream('\n'); else if (!silent && !onText) out(''); }
+    }
+
+    totals.input += turn.usage.input_tokens || 0;
+    totals.cached += (turn.usage.cache_read_input_tokens || 0) + (turn.usage.cache_creation_input_tokens || 0);
+    totals.output += turn.usage.output_tokens || 0;
+    totals.credits += Number(turn.usage.credits) || 0;
+    const promptSize = (turn.usage.input_tokens || 0) + (turn.usage.cache_read_input_tokens || 0) + (turn.usage.cache_creation_input_tokens || 0);
+    if (promptSize) {
+      totals.context = promptSize + (turn.usage.output_tokens || 0);
+      // The header's context meter moves after every step. It used to be told only when
+      // the whole run returned, so through a long task — and after one stopped with
+      // Esc or an error — it sat at 0.
+      try { onContext?.(totals.context); } catch { /* the meter never breaks a turn */ }
+    }
+    // The work bar's live count. It was declared and drawn but never fed, so it never
+    // appeared; now it moves after every step of the turn.
+    tui?.setTurnTokens?.(totals.input + totals.cached + totals.output, totals.credits);
+
+    if (willContinue) {
+      continuations += 1;
+      continuing = true;
+      const text = turn.content.filter((b) => b.type === 'text');
+      if (text.length) messages.push({ role: 'assistant', content: text });
+      messages.push({ role: 'user', content: [{ type: 'text', text: CONTINUE_NOTE }] });
+      onEvent?.({ type: 'continued', reason: turn.stopReason, count: continuations });
+      continue;
+    }
+    continuing = false;
+    if (incomplete && !turn.content.some((b) => b.type === 'tool_use')) {
+      // Still unfinished after every continuation: say so, rather than let a partial
+      // answer pass as a whole one.
+      const why = 'The reply was still unfinished after several continuations. Ask for the rest, or narrow the request.';
+      if (tui?.notice) tui.notice(why, 'warn');
+      else if (!silent) out(c.yellow(`  ${why}`));
+    }
+
+    // Append the assistant turn verbatim — tool_use blocks and all.
+    messages.push({ role: 'assistant', content: turn.content });
+    onEvent?.({ type: 'assistant_turn', content: turn.content, usage: turn.usage, iteration });
+
+    const calls = turn.content.filter((b) => b.type === 'tool_use');
+
+    // Plan mode: read-only by decree. The turn's text still lands (the model can think
+    // out loud), but nothing on disk or in a shell is allowed to happen.
+    // web_fetch is not a write: in plan mode it goes to its own prompt instead of ending the turn.
+    // Plan mode: a write or command gets a "not run — plan instead" result, the reads in
+    // the same batch still run, and the turn — with the plan the model just wrote — stays
+    // in the history. It used to pop the whole turn, so "ok, do it" found no plan to do.
+    const planBlocked = permissions.mode === 'plan'
+      ? new Set(calls.filter((call) => toolMap[call.name]?.needsPermission && !toolMap[call.name]?.network).map((call) => call.id))
+      : new Set();
+    if (planBlocked.size && !planNoticeShown) {
+      planNoticeShown = true;
+      const text = 'Plan mode — writes and commands are not run; the agent can still read. Shift+Tab (or /code) to let it act.';
+      if (tui?.notice) tui.notice(text, 'warn');
+      else if (!silent) out(c.yellow(`  ${glyph('⏸', '[II]')}  ${text}`));
+    }
+
+    // Esc pressed while the model was mid-turn: stop before any more tools run.
+    if (signal?.aborted) {
+      if (!silent) out(c.yellow(`  ${glyph('⏹', '[x]')}  Interrupted.`));
+      return { ...totals, stopReason: 'interrupted' };
+    }
+
+    if (!calls.length) { tui?.bellIfAway?.(); return { ...totals, stopReason: turn.stopReason }; }
+
+    // The same call, same input, nothing changed since: STUCK_REPEATS times is a loop.
+    // Checked before running, so the repeat that proves it is not paid for again.
+    const stuckOn = calls.find((call) => {
+      // Polling is supposed to repeat: background_read's own description says "poll
+      // this", and four polls of a starting dev server are not a loop.
+      if (POLLING_TOOLS.has(call.name)) return false;
+      const key = `${changes}\u0000${call.name}\u0000${JSON.stringify(call.input ?? null)}`;
+      const n = (repeats.get(key) || 0) + 1;
+      repeats.set(key, n);
+      return n >= STUCK_REPEATS;
+    });
+    if (stuckOn) {
+      // Every tool_use still gets a result — the model is told why these did not run, so
+      // after "continue" it does not simply make the same call a fifth time.
+      messages.push({ role: 'user', content: calls.map((call) => result(call.id,
+        `Not run: this exact call was already made ${STUCK_REPEATS - 1} times with no file changed since, and the run was stopped as stuck. Do something different.`, true)) });
+      const label = toolMap[stuckOn.name]?.summarise ? toolMap[stuckOn.name].summarise(stuckOn.input) : stuckOn.name;
+      const why = `Stopped: it made the same ${stuckOn.name} call (${String(label).slice(0, 60)}) ${STUCK_REPEATS} times without changing anything, so it looks stuck. Tell it what to do differently, or say "continue".`;
+      if (tui?.notice) tui.notice(why, 'warn');
+      else if (!silent) out(c.yellow(`\n${why}`));
+      tui?.bellIfAway?.();
+      return { ...totals, stopReason: 'stuck' };
+    }
+
+    // Every call gets a result, whatever happened.
+    const results = [];
+    for (const call of calls) {
+      const tool = toolMap[call.name];
+      totals.tools += 1;
+
+      // Esc during a batch stops the REST of it. The check used to run once before the
+      // batch, so after Esc the remaining calls still prompted and ran.
+      if (signal?.aborted) {
+        results.push(result(call.id, 'Not run: the user stopped the task.', true));
+        continue;
+      }
+      if (planBlocked.has(call.id)) {
+        results.push(result(call.id, 'Not run: plan mode is on, so nothing is written and no command runs. Finish investigating with read-only tools, then present your plan as your answer — the user will switch modes when they want it carried out.', true));
+        continue;
+      }
+      if (!tool) {
+        results.push(result(call.id, `No such tool: ${call.name}`, true));
+        continue;
+      }
+      if (call.input?.__parse_error !== undefined) {
+        results.push(result(call.id, 'Your tool arguments were not valid JSON. Send them again.', true));
+        continue;
+      }
+
+      const label = tool.summarise ? tool.summarise(call.input) : call.name;
+      const activityId = tui?.recordActivity?.({ name: call.name, label, status: 'waiting' });
+      // One row per call, mutated in place through waiting → running → ok/failed. The
+      // previous surface printed a fresh line per state change, so a session with
+      // twenty tool calls scrolled sixty lines of near-duplicates past the answer.
+      const row = tui?.tool?.({ name: call.name, label, status: 'waiting', file: call.input?.path });
+
+      try {
+        await permissions.request(tool, call.input, { cwd, tui, signal });
+      } catch (e) {
+        if (e instanceof PermissionDenied) {
+          const declined = `  ${c.red(glyph('✗', 'x'))} ${c.dim('declined')}`;
+          if (row) row.update({ status: 'denied', error: e.comment ? `declined — "${e.comment}"` : 'declined' });
+          else if (tui) tui.print(declined);
+          else if (!silent) out(declined);
+          tui?.recordActivity?.({ id: activityId, name: call.name, label, status: 'failed', detail: 'Permission declined by user.' });
+          // Told to the model, not just the user: it needs to know to stop trying and
+          // propose something else instead. A decision comment rides along verbatim.
+          // A run that could not ask (one-shot, a script) says so — "the user declined"
+          // was untrue there, and hid the hint about --yes from everyone.
+          if (e.headless) totals.denied = (totals.denied || 0) + 1;
+          const note = e.headless
+            ? `Not permitted in this run: ${e.message} Do not retry it; finish what you can without it and say what was left undone.`
+            : e.comment
+              ? `The user declined this action with this instruction, which overrides your plan: "${e.comment}". Do not retry the declined action; follow the instruction instead.`
+              : `The user declined this action. Do not retry it; ask what they would prefer.`;
+          results.push(result(call.id, note, true));
+          continue;
+        }
+        throw e;
+      }
+
+      tui?.recordActivity?.({ id: activityId, name: call.name, label, status: 'running' });
+      row?.update({ status: 'running' });
+      const spin2 = tui ? { stop: () => {} } : (silent ? { stop: () => {} } : spinner(`${call.name}: ${label}`.slice(0, 100)));
+      const toolStarted = Date.now();
+      // Live elapsed ticker on the status row while a tool runs (1s cadence,
+      // silent when animations are off — progress you can watch, not noise).
+      let elapsedTimer = null;
+      const stopElapsed = () => { if (elapsedTimer) { clearInterval(elapsedTimer); elapsedTimer = null; } };
+      if (tui && tui.animationsOn?.()) {
+        const toolStatus = () => `${c.brand(glyph('•', '*'))} ${call.name}: ${c.dim(String(label).slice(0, 60))} ${c.dim(`· ${((Date.now() - toolStarted) / 1000).toFixed(0)}s`)}`;
+        tui.setStatus(toolStatus());
+        elapsedTimer = setInterval(() => tui.setStatus(toolStatus()), 1000);
+        if (elapsedTimer.unref) elapsedTimer.unref();
+      } else if (tui) {
+        tui.setStatus(`${c.brand(glyph('•', '*'))} ${call.name}: ${c.dim(String(label).slice(0, 70))}`);
+      }
+      try {
+        // Rewind safety net: before the agent overwrites or creates a file, remember
+        // what was there. write_file/edit_file take their targets from the input;
+        // run_command's target is unknowable, so its calls snapshot the whole
+        // tracked set instead (cheap: only files already touched this session).
+        if (journal && ['write_file', 'edit_file'].includes(call.name) && call.input?.path) {
+          try { journal.snapshotFile(path.resolve(cwd, String(call.input.path))); } catch { /* path never existed */ }
+        } else if (journal && call.name === 'run_command') {
+          journal.snapshotTracked(cwd);
+        }
+        const output = await tool.run(call.input, { cwd, signal });
+        spin2.stop(); stopElapsed();
+        const took = ((Date.now() - toolStarted) / 1000).toFixed(1);
+        // opencode tool icons: $ shell, ← edits, → reads, ✱ search,
+        // % fetch, ◈ websearch, ◉ subagents, ⚙ everything else. Done
+        // rows rest muted; failures stay red.
+        const done = `  ${toolMark(call.name)} ${c.dim(String(label).slice(0, 100))} ${c.dim(`· ${took}s`)}`;
+        if (row) {
+          tui.clearStatus();
+          // The whole output travels with the row (capped), so a click can open it.
+          row.update({ status: 'ok', took, preview: previewFor(call.name, output), full: String(output ?? '').slice(0, 200_000) });
+        } else if (tui) { tui.clearStatus(); tui.print(done, 'tool'); } else if (!silent) out(done);
+        tui?.recordActivity?.({ id: activityId, name: call.name, label, status: 'ok', detail: String(output).slice(0, 2000) });
+        onEvent?.({ type: 'tool_result', name: call.name, input: call.input, ok: true, output });
+        results.push(result(call.id, output, false));
+        // A changed file is progress: calls made after it are not repeats of those before.
+        if (['write_file', 'edit_file'].includes(call.name)) changes += 1;
+        // read_image: the pixels ride along as an image block in the tool-result
+        // message, so the model actually sees the picture instead of a caption of it.
+        // read_image: the pixels ride along in this message, after the results. When no
+        // image can be attached the call FAILED and says why — it used to report success
+        // either way, and the model then described a picture it never saw.
+        if (call.name === 'read_image') {
+          let block = null;
+          let why = '';
+          try { block = await readImageForModel(cwd, call.input?.path); } catch (e) { why = e.message; }
+          results[results.length - 1] = block
+            ? { ...result(call.id, 'The image is attached to this message, after the tool results.', false), __images: [block] }
+            : result(call.id, why || 'The image could not be attached.', true);
+        }
+        // todo_write: the checklist is for the human — checkbox cells with progress.
+        if (call.name === 'todo_write' && Array.isArray(call.input?.todos)) {
+          if (tui?.todo) tui.todo(call.input.todos);
+          else if (!silent) {
+            const icon = { pending: c.dim(glyph('☐', '[ ]')), in_progress: c.accent(glyph('◐', '[>]')), completed: c.accent(glyph('☑', '[x]')) };
+            for (const t of call.input.todos.slice(0, 12)) {
+              out(`  ${(icon[t?.status] || icon.pending)} ${t?.status === 'completed' ? c.dim(String(t?.task || '').slice(0, 90)) : String(t?.task || '').slice(0, 90)}`);
+            }
+          }
+        }
+
+        // A write or an edit shows what it actually did. The journal snapshotted the
+        // file a few lines above, so the "before" side is already in memory — and a
+        // claim like "Edited src/index.js" is exactly the kind of thing that turns out
+        // to have changed the wrong line.
+        if (tui?.diff && journal && ['write_file', 'edit_file'].includes(call.name) && call.input?.path) {
+          try {
+            const absolute = path.resolve(cwd, String(call.input.path));
+            const before = journal.latestSnapshot(absolute);
+            if (before !== null) {
+              const { readFileSync } = await import('node:fs');
+              const patch = unifiedDiff(before, readFileSync(absolute, 'utf8'), { file: call.input.path });
+              if (patch) tui.diff(String(call.input.path), patch);
+            }
+          } catch { /* a missing diff never blocks the turn */ }
+        }
+      } catch (e) {
+        spin2.stop(); stopElapsed();
+        const msg = e instanceof ToolError ? e.message : `${e.message}`;
+        const took = ((Date.now() - toolStarted) / 1000).toFixed(1);
+        const bad = `  ${c.red(glyph('✗', 'x'))} ${c.dim(String(label).slice(0, 80))} ${c.dim(`· ${took}s`)} — ${msg.slice(0, 120)}`;
+        if (row) {
+          tui.clearStatus();
+          row.update({ status: 'failed', took, error: msg.split('\n')[0].slice(0, 200), preview: msg.includes('\n') ? msg : '', full: msg.slice(0, 200_000) });
+        } else if (tui) { tui.clearStatus(); tui.print(bad, 'tool'); } else if (!silent) out(bad);
+        tui?.recordActivity?.({ id: activityId, name: call.name, label, status: 'failed', detail: msg.slice(0, 2000) });
+        onEvent?.({ type: 'tool_result', name: call.name, input: call.input, ok: false, error: msg });
+        results.push(result(call.id, msg, true));
+      }
+    }
+
+    // Every tool_result first, then any images, in the same user message. Anthropic's
+    // format requires the results to lead the message; an image between two results
+    // (read_image followed by another call in one batch) was a rejected request.
+    const images = [];
+    for (const r of results) {
+      for (const img of r.__images || []) images.push(img);
+      delete r.__images;
+    }
+    messages.push({ role: 'user', content: [...results, ...images] });
+    if (signal?.aborted) {
+      if (!silent) out(c.yellow(`  ${glyph('⏹', '[x]')}  Interrupted.`));
+      return { ...totals, stopReason: 'interrupted' };
+    }
+  }
+
+  if (!silent) out(c.yellow(`\nStopped after ${maxIterations} steps — the safety limit for one request. Say "continue" to keep going.`));
+  tui?.bellIfAway?.();
+  return { ...totals, stopReason: 'max_iterations' };
+}
+
+/**
+ * A read-only subagent, as a tool the model can call.
+ *
+ * The point is context, not concurrency. "Find every place that reads the session file"
+ * costs forty tool results, and forty tool results spent in the main conversation are
+ * forty tool results the main conversation is still carrying three turns later. A
+ * subagent spends them in its own window and returns the paragraph that mattered.
+ *
+ * Read-only by construction: it is handed a permissions object in plan mode, so every
+ * write and every shell command is refused no matter what the parent's mode is. A
+ * subagent the user never sees must not be able to change the disk.
+ */
+function makeSubagentTool({ client, model, cwd, signal, tui, permissions = null }) {
+  return {
+    name: 'task',
+    needsPermission: false,
+    description: 'Delegate a read-only investigation to a separate agent with its own context window. '
+      + 'Use it when answering needs a lot of searching and reading whose intermediate output you do not need to keep — '
+      + '"find every caller of X", "work out how Y is wired", "check whether Z is covered by tests". '
+      + 'The subagent can read, list, search and fetch, but cannot write files or run commands. '
+      + 'Give it a self-contained brief: it cannot see this conversation. It returns its findings as text.',
+    input_schema: {
+      type: 'object',
+      properties: {
+        description: { type: 'string', description: 'Three to five words naming the task, for the activity row.' },
+        prompt: { type: 'string', description: 'The full self-contained brief, including what to report back.' },
+      },
+      required: ['description', 'prompt'],
+    },
+    summarise: (input) => String(input.description || 'subagent'),
+    async run(input, { cwd: runCwd }) {
+      const { createPermissions } = await import('./permissions.js');
+      const messages = [{ role: 'user', content: String(input.prompt || '') }];
+      let answer = '';
+      const result = await runAgent({
+        client,
+        messages,
+        model,
+        cwd: runCwd || cwd,
+        permissions: permissions?.fork ? permissions.fork({ mode: 'plan', interactive: false }) : createPermissions({ mode: 'plan', interactive: false }),
+        signal,
+        tui: null,
+        silent: true,
+        subagents: false,
+        // Read-only research across a codebase is many small reads; 20 cut it off
+        // mid-search. The stuck detector is what catches a loop.
+        maxIterations: 100,
+        extraSystem: '\n\nYou are a subagent. You cannot ask questions and nobody will read your intermediate '
+          + 'steps — only your final message. End with the findings themselves, with exact file paths and line '
+          + 'numbers where they apply, not a description of how you looked.',
+        onText: (text) => { answer += text; },
+      });
+      const trimmed = answer.trim();
+      if (!trimmed) return `The subagent finished (${result.stopReason}) without reporting anything.`;
+      return `${trimmed}\n\n[subagent: ${result.tools} tool calls, ${result.input + result.output} tokens]`;
+    },
+  };
+}
+
+/**
+ * What of a tool's output is worth putting on screen.
+ *
+ * Not everything: a `read_file` the agent asked for is the agent's business, and
+ * echoing 400 lines of it buries the reasoning that follows. A command's output, a
+ * search's hits and a fetch's first lines are the ones a human reads over the agent's
+ * shoulder — so those get a preview and the rest get a row.
+ */
+function previewFor(name, output) {
+  const text = String(output ?? '');
+  if (!text.trim()) return '';
+  switch (name) {
+    case 'run_command':
+    case 'background_read':
+      return text;
+    case 'search':
+    case 'list_files':
+    case 'web_search':
+      return text;
+    case 'web_fetch':
+      return text.split('\n').slice(0, 8).join('\n');
+    case 'read_file':
+    case 'read_image':
+    case 'write_file':
+    case 'edit_file':
+    case 'todo_write':
+      return '';
+    default:
+      return text.length > 400 ? '' : text;
+  }
+}
+
+function result(id, content, isError) {
+  return { type: 'tool_result', tool_use_id: id, content: String(content), is_error: isError };
+}