jaitus 0.3.3 → 0.3.5

package/README.md

@@ -94,49 +94,45 @@ changing a file or running a command, showing you exactly what it is about to do
 | `/hooks` | show lifecycle hooks |
 | `/tui [fullscreen\|default]` | switch renderer, relaunching with the conversation intact |
 | `/fork` | copy this conversation into a brand-new session |
-| `/theme [name]` | color theme: dark, light, daltonized, plain, auto |
-| `/scroll-speed [n]` | mouse-wheel speed, 0.25–10 |
+| `/theme [name]` | color theme: dark, light, ocean, daltonized, auto (the default: asks the terminal for its background colour) |
+| `/scroll-speed [n]` | mouse-wheel speed, 0.25–20 |
 | `/agent <task>` | run an isolated read-only side task |
 | `/cwd` | which directory the agent is working in |
 | `/clear` | start the conversation over |
 | `/undo` | drop the last exchange |
 | `/exit` | leave |
 
-Arrow keys, word-delete and history all work — history is kept in `~/.jaitus/history`
-and survives across sessions. Ctrl-C clears the line (or copies the selection,
-or interrupts a running turn) but never exits — only `/exit` leaves.
-
-Enter sends in one press — Tab completes a `/` command or `@` file without
-sending, Esc dismisses the suggestion first. `Ctrl+J`, `Shift+Enter` and
-`\+Enter` insert a newline. Up/Down (or `Ctrl+P`/`Ctrl+N`) moves inside a
-multiline prompt first, then through history. `Ctrl+R` searches history,
-`Shift+Tab` cycles permission modes, `Ctrl+T` shows session activity, `Ctrl+G`
-edits the draft in `$VISUAL`/`$EDITOR`, `Ctrl+S` stashes/recalls the draft,
-`Ctrl+_` undoes, `Ctrl+Y` pastes the last deletion, `Alt+B`/`F`/`D` do word
-jumps/edits, `?` on an empty prompt lists shortcuts. Large pastes collapse to
-`[Pasted text #N]` chips (full text still sends), `Ctrl+V` attaches a clipboard
-image, `:name:` inserts emoji, `! cmd &` or `Ctrl+B` backgrounds a command.
-
-Scrolling stays inside the app (alternate screen): `PgUp` /
-`PgDn` half a screen, `Ctrl+Home` / `Ctrl+End` top / bottom, mouse wheel a few
-lines. Scrolling up pauses auto-follow and shows new-message count — `Ctrl+End`
-or scroll to the bottom resumes. `JAITUS_SCROLL_SPEED` (1–20)
-multiplies wheel distance.
-`Ctrl+O` opens the transcript viewer: `/` searches, `n` / `N` next / previous,
-`j` / `k` lines, `Ctrl+u` / `Ctrl+d` half page, `Ctrl+b` / `Ctrl+f` / `Space`
-full page, `{` / `}` previous / next prompt, `g` / `G` ends, `[` dumps the full
-conversation to native scrollback for `Cmd+F` / tmux copy mode, `v` opens it in
-`$VISUAL` / `$EDITOR`, `q` / `Esc` returns.
-
-Drag selects inside the session and auto-copies on release (double-click word,
-triple-click line, `Shift+arrows` extends, `Ctrl+C` copies when a selection is
-active, `Ctrl+Shift+C` copies manually when auto-copy is off). Clipboard order:
-tmux buffer, `pbcopy` / `wl-copy` / `xclip` / `xsel` / `clip` / PowerShell
-`Set-Clipboard`, then OSC 52 over SSH. `jaitus config copyOnSelect on|off`
-toggles auto-copy. `JAITUS_DISABLE_MOUSE=1`
-keeps flicker-free rendering with native selection; `JAITUS_DISABLE_MOUSE_CLICKS=1`
-keeps wheel scrolling only. Hold `Shift` (`Option` in iTerm2, `Fn` in
-Terminal.app) for one-off native selection.
+Arrow keys, Home/End, `Ctrl+A`/`Ctrl+E`, `Ctrl+W` (delete a word), `Ctrl+U`/`Ctrl+K`
+(delete to the start/end) all work, and the cursor is drawn where you are typing.
+Prompt history is kept in `~/.jaitus/history` and carries over between sessions —
+Up/Down walk it. `Ctrl+C` copies a selection if there is one, otherwise interrupts a
+running turn or clears the line; it never exits — only `/exit` leaves.
+
+Enter sends. `Ctrl+J`, `Alt+Enter`, `Shift+Enter` (where the terminal reports it) and
+`\` then Enter insert a new line. Tab completes a `/` command or `@` file; Esc closes
+the suggestion list first (press Enter again to send what you typed), and twice on an
+empty prompt opens Rewind. `Shift+Tab` cycles permission modes, `Ctrl+P` opens the
+command palette, `Ctrl+L` clears the screen (the conversation stays — `/clear` starts
+over), `Ctrl+D` toggles debug details. `Ctrl+R` searches your past prompts (Enter
+puts the one you pick in the box, unsent); `Ctrl+O` searches the conversation and
+scrolls to the line you pick.
+
+**Pasting.** Right-click or `Ctrl+V` pastes the clipboard; a long paste becomes a
+`[#1 pasted 120 lines]` chip (the full text is sent). **Images:** drag an image file
+onto the terminal, paste a copied screenshot with `Alt+V`, type `/image path.png`, or
+mention `@screenshot.png` — each becomes an `[Image #N]` chip listed under the
+composer. Backspace over a chip removes it; only images whose chip is still in the
+message are sent. Screenshots over 3.5 MB are shrunk automatically.
+
+Scrolling stays inside the app: `PgUp`/`PgDn`, `Ctrl+Home`/`Ctrl+End`, the mouse wheel.
+Scrolling up pauses auto-follow; `Ctrl+End` (or a click in the conversation) returns
+to the live end. Panels (`/diff`, `/tasks`, `/help`) scroll with the arrows, PgUp/PgDn
+and the wheel.
+
+Drag selects and copies on release; double-click selects a word, triple-click a line.
+`jaitus config copyOnSelect off` turns auto-copy off — then `Ctrl+C` copies.
+`JAITUS_DISABLE_MOUSE=1` gives the terminal its own selection back. Hold `Shift`
+(`Option` in iTerm2) for a one-off native selection.
 
 ## Options
 
@@ -219,7 +215,7 @@ or pipes. Force either way with `JAITUS_FULLSCREEN=1` / `JAITUS_NO_FULLSCREEN=1`
   the default; without a terminal to ask in, an action that needs permission is refused
   rather than assumed.
 - Commands run with no TTY, so anything interactive exits instead of hanging forever.
-- The agent stops after 40 steps rather than looping on your bill.
+- The agent runs until the task is done. If it repeats the same action four times without changing anything it stops and says so, rather than looping on your bill.
 - `jaitus doctor` never prints your sign-in token — only whether you are signed in.
 
 ## Signing in

package/bin/jaitus.js

@@ -1,5 +1,18 @@
 #!/usr/bin/env node
-import main from '../src/index.js';
+// The app is imported only after an unfinished update has completed: importing it
+// statically would load a half-installed copy and crash before any check could run.
+// Node 20 is the floor — checked FIRST: loading the app on an older Node crashed in its
+// dependencies before this friendly message could print.
+if (Number(process.versions.node.split('.')[0]) < 20) {
+  process.stderr.write(`jaitus needs Node 20 or newer (you have ${process.versions.node}).
+`);
+  process.exit(1);
+}
+
+import { waitForPendingUpdate } from '../src/pendingUpdate.js';
+
+await waitForPendingUpdate().catch(() => false);
+const { default: main } = await import('../src/index.js');
 
 // Node 20 is the floor: the CLI uses global fetch, and on 18 it exists but streaming
 // bodies behave differently enough to matter. Better a clear message than a confusing

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jaitus",
-  "version": "0.3.3",
+  "version": "0.3.5",
   "description": "Jaitus — a coding agent in your terminal.",
   "type": "module",
   "bin": {
@@ -16,7 +16,7 @@
     "node": ">=20"
   },
   "scripts": {
-    "test": "node tests/source-sanity.js && node tests/rules.js && node tests/run.js && node tests/commands.js && node tests/login.js && node tests/session.js && node tests/openUrl.js && node tests/ink-tui.js && node tests/tui-render.js && node tests/mouse-e2e.js && node tests/environment.js && node tests/update.js && node tests/continuation.js && node tests/context-budget.js",
+    "test": "node tests/source-sanity.js && node tests/rules.js && node tests/run.js && node tests/commands.js && node tests/login.js && node tests/session.js && node tests/openUrl.js && node tests/ink-tui.js && node tests/tui-render.js && node tests/mouse-e2e.js && node tests/environment.js && node tests/update.js && node tests/continuation.js && node tests/steps.js && node tests/files.js && node tests/processes.js && node tests/security.js && node tests/context-budget.js",
     "preview": "node scripts/tui-preview.js",
     "prepublishOnly": "npm test"
   },

package/src/agent/loop.js

@@ -15,8 +15,12 @@
 //   • 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 hard iteration cap. A model that gets stuck in a read-file loop would otherwise
-//     spend real money until someone notices.
+//   • 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';
@@ -29,7 +33,9 @@ import { discoverMcpTools } from '../mcp.js';
 import { unifiedDiff } from '../diff.js';
 import { fromResponse, fromGatewayBody } from '../errors.js';
 
-const MAX_ITERATIONS = 40;
+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
@@ -48,6 +54,33 @@ export const CONTINUE_NOTE = 'Your previous reply was cut off before it finished
 // 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: ['→', '>'],
@@ -158,6 +191,67 @@ ${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;
+}
+
+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({
@@ -165,7 +259,7 @@ async function streamTurn({ client, messages, model, system, tools, onText, onTo
     max_tokens: MAX_OUTPUT_TOKENS,
     system: system || SYSTEM_PROMPT,
     tools,
-    messages,
+    messages: withinImageBudget(messages),
     stream: true,
   }, { signal });
 
@@ -269,7 +363,13 @@ async function streamTurn({ client, messages, model, system, tools, onText, onTo
     if (!blocks.size) throw e;
     cut = true;
   }
-  if (streamError) throw streamError;
+  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()]
@@ -295,19 +395,29 @@ 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,
+  subagents = true, onContext = null,
 }) {
+  // 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 };
   // 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.
-  const system = `${systemOverride || systemPrompt(cwd)}${extraSystem}`;
+  // 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 }) : null;
+  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 }] : []),
@@ -321,6 +431,8 @@ export async function runAgent({
 
   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;
@@ -372,6 +484,21 @@ export async function runAgent({
         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('');
@@ -384,6 +511,14 @@ export async function runAgent({
     }
     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.
@@ -398,7 +533,13 @@ export async function runAgent({
     totals.cached += (turn.usage.cache_read_input_tokens || 0) + (turn.usage.cache_creation_input_tokens || 0);
     totals.output += turn.usage.output_tokens || 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);
+    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);
@@ -429,14 +570,18 @@ export async function runAgent({
 
     // 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.
-    const blockedInPlan = permissions.mode === 'plan' && calls.some((call) => toolMap[call.name]?.needsPermission);
-    if (blockedInPlan) {
-      messages.pop();
-      const note = c.yellow(`  ${glyph('⏸', '[II]')}  plan mode — writes and commands are blocked; read-only inspection can continue. Shift+Tab to a doing mode to act.`);
-      if (tui?.notice) tui.notice('plan mode — writes and commands are blocked; read-only inspection can continue. Shift+Tab to a doing mode to act.', 'warn');
-      else if (tui) tui.print(note);
-      else if (!silent) out(note);
-      return { ...totals, stopReason: 'plan_blocked' };
+    // 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.
@@ -447,12 +592,46 @@ export async function runAgent({
 
     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;
@@ -470,7 +649,7 @@ export async function runAgent({
       const row = tui?.tool?.({ name: call.name, label, status: 'waiting', file: call.input?.path });
 
       try {
-        await permissions.request(tool, call.input, { cwd, tui });
+        await permissions.request(tool, call.input, { cwd, tui, signal });
       } catch (e) {
         if (e instanceof PermissionDenied) {
           const declined = `  ${c.red(glyph('✗', 'x'))} ${c.dim('declined')}`;
@@ -480,9 +659,14 @@ export async function runAgent({
           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.
-          const note = 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.`;
+          // 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;
         }
@@ -515,7 +699,7 @@ export async function runAgent({
         } else if (journal && call.name === 'run_command') {
           journal.snapshotTracked(cwd);
         }
-        const output = await tool.run(call.input, { 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,
@@ -529,11 +713,20 @@ export async function runAgent({
         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.
-        if (call.name === 'read_image' && !silent) {
-          const block = await readImageForModel(cwd, call.input?.path).catch(() => null);
-          if (block) results[results.length - 1] = { ...result(call.id, output, false), __images: [block] };
+        // 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)) {
@@ -576,18 +769,22 @@ export async function runAgent({
       }
     }
 
-    // Image blocks ride in the same user message as their tool_result, each following
-    // the result it belongs to — that is the shape the vision API expects.
-    const withImages = [];
+    // 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) {
-      withImages.push(r);
-      for (const img of r.__images || []) withImages.push(img);
+      for (const img of r.__images || []) images.push(img);
       delete r.__images;
     }
-    messages.push({ role: 'user', content: withImages });
+    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 without finishing. Say "continue" to keep going.`));
+  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' };
 }
@@ -604,7 +801,7 @@ export async function runAgent({
  * 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 }) {
+function makeSubagentTool({ client, model, cwd, signal, tui, permissions = null }) {
   return {
     name: 'task',
     needsPermission: false,
@@ -631,12 +828,14 @@ function makeSubagentTool({ client, model, cwd, signal, tui }) {
         messages,
         model,
         cwd: runCwd || cwd,
-        permissions: createPermissions({ mode: 'plan' }),
+        permissions: permissions?.fork ? permissions.fork({ mode: 'plan', interactive: false }) : createPermissions({ mode: 'plan', interactive: false }),
         signal,
         tui: null,
         silent: true,
         subagents: false,
-        maxIterations: 20,
+        // 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.',