done-done-axi 0.3.0 → 0.3.2

package/README.md

@@ -101,7 +101,7 @@ cd your-app
 done-done init
 ```
 
-`init` writes a minimal `.done-done.yaml` (only if you don't already have one) that names your app, and a commented global `~/.done-done/config.yaml` (only if there is none). done-done never picks the coding agent it starts: `init` asks you in a terminal, or takes `--agent <agent> --model <model>`. It never picks the judge either, the agent of its own that `verify` starts to look at each capture (never the one that did the work): `init` asks in a terminal, or takes `--judge <agent> --judge-model <model>`. The config keys are in the [reference](docs/reference.md#config). A plain `init` never overwrites an existing config. It also scaffolds a verify skill at `.agents/skills/verify-<app>` from the repo's own files, for your agent to finish with one live drive. Evidence lives outside the repo, in `~/.done-done/evidence/<app>`, so it outlives the checkout that captured it. Then describe how to capture proof — swap the command for whatever drives your real app and saves screenshots, recordings or logs:
+`init` writes a minimal `.done-done.yaml` (only if you don't already have one) that names your app, and a commented global `~/.done-done/config.yaml` (only if there is none). done-done never picks the coding agent it starts: `init` asks you in a terminal, or takes `--agent <agent> --model <model>`. It never picks the judge either, the agent of its own that `verify` starts to look at each capture: `init` asks in a terminal, or takes `--judge <agent> --judge-model <model>`. The judge must differ from the author by agent or by model: the same agent at another model is fine, the same agent and model is refused (`judge.allow_same: true` is an opt-out only). For example, with pi on DeepSeek as the author, `done-done init --agent pi --model commandcode/deepseek/deepseek-v4.1-flash --judge pi --judge-model zai/glm-5.3-flash` is accepted. The config keys are in the [reference](docs/reference.md#config). A plain `init` never overwrites an existing config. It also scaffolds a verify skill at `.agents/skills/verify-<app>` from the repo's own files, for your agent to finish with one live drive. Evidence lives outside the repo, in `~/.done-done/evidence/<app>`, so it outlives the checkout that captured it. Then describe how to capture proof — swap the command for whatever drives your real app and saves screenshots, recordings or logs:
 
 ```yaml
 journeys:
@@ -121,9 +121,9 @@ git add .done-done.yaml
 git commit -m "Add done-done"
 ```
 
-A `run -- <command>` whose command matches no recorded journey still runs, but its result hints that the recipe is not in the repo.
+A `run -- <command>` whose command matches no recorded journey still runs, but its result hints that the recipe is not in the repo. For a proof you drive by hand or by your agent instead of a journey, `done-done run --open` prints a run id and a folder to capture into, and `done-done run --close <run-id>` seals it ([how](docs/reference.md#run-a-journey)).
 
-At any point, `done-done doctor` checks the setup and changes nothing except the `--probe` call record. Each item reports `ok`, `warning` or `missing` with the exact fix command; an agent you have not set yet is `missing`, with the command that saves your choice. `done-done doctor --probe` also asks the agent one question to prove it answers. The items are listed in the [reference](docs/reference.md#check-the-setup).
+At any point, `done-done doctor` checks the setup and changes nothing except the `--probe` call record. Each item reports `ok`, `warning` or `missing` with the exact fix command; an agent you have not set yet is `missing`, with the command that saves your choice. `done-done doctor --probe` also asks the agent one question to prove it answers; on a new machine that probe fails until the agent is signed in (for pi, run `pi` and then `/login`). The quick start above never calls the agent, so `run` and `check` work before it. The judge also needs the optional `@byokit/decide@0.8.0` kit, which a plain npm install leaves out: until it is there, `doctor` reports the judge `missing`, and `verify`, `check --judge` and `design` cannot judge. Add it with the line `doctor` prints: `npx -y -p done-done-axi -p @byokit/decide@0.8.0 done-done-axi doctor`. The items are listed in the [reference](docs/reference.md#check-the-setup).
 
 `done-done maintain` keeps the verify skill true: it checks the skill's links and feature index, checks that every `file:line` it cites exists, and has your coding agent read the source for each feature, read-only, to report drift. It ends `clean`, `drift` with the findings to fix, or `blocked`. With `auto_fix: { maintain: <n> }` (as in no-mistakes; 0, the default, reports only), your judge first sorts each drift finding (a skill out of date, or a product that may be wrong, which stops and asks you), then your agent fixes the skill folder only, in a done-done worktree, and maintain runs again, up to n times. A clean end is `changed`: one commit on a `done-done/maintain-<run-id>` branch, your branch untouched ([reference](docs/reference.md#keep-the-verify-skill-true)).
 
@@ -147,6 +147,8 @@ No journey yet? `done-done verify --outcome "<what a user can now do>"` has your
 
 With `auto_fix: { verify: <n> }` (0, the default, reports only), a failed verify is fixed with your own agent: your judge first sorts each wrong screen (a product bug to fix, or a question that waits at the gate for you), then your agent fixes the product in a done-done worktree with your ignored files copied in, and verify runs again there, up to n times. A pass ends `changed`, with the fix on a `done-done/verify-<run-id>` branch and your branch untouched ([details](docs/reference.md#fix-the-product)).
 
+While a `verify` or `maintain` run goes, `done-done status` shows its steps and next move, `done-done attach` streams its events, and `done-done logs --step <name>` shows one step's log. `done-done rerun` runs a failed verify run again from the failed step, `done-done abort` stops a live run, `done-done signoff` writes a verify run's sign-off message, and `done-done history` lists past runs.
+
 Run `done-done` with no arguments to see the current config and the next step.
 
 ## What it checks
@@ -157,9 +159,10 @@ Run `done-done` with no arguments to see the current config and the next step.
 - ♻️ **Not reused**: Proof made only of files already used for a different claim fails, and so does citing the same file twice. A claim is named by `--claim-id <id>`, which defaults to your branch, so rewording it keeps its proof. Several claims on one branch each need their own `--claim-id`.
 - 🧾 **Honest claims**: Reads a pull request's `## Checks` block — from a file, a URL, or stdin — and makes sure every line is filled in.
 - 📌 **Verifiable later**: `receipt` records a passing check against the exact commit and the sha256 of every file it cited; `receipt --verify` re-checks it from any checkout of that commit on the same machine (a merge gate or a fresh clone), or in CI once the evidence folder is copied there ([how](docs/reference.md#where-proof-lives)).
-- 👀 **Shows the outcome** (on by default in `verify`; `check` and `receipt` with `--judge`): `verify` starts done-done's own judge, a fresh, tools-off agent on your own plan or key (Claude Code, opencode, pi or Gemini CLI, or your own OpenAI API key), to say whether each capture is the right screen for the claim (and each text capture, such as a log, JSON or CLI output, the right output), and a wrong one fails. You choose the judge (`done-done init --judge <agent> --judge-model <model>`, or pick it from the list `verify` shows in a terminal); done-done never picks one, and it is never the agent and model that did the work. `--no-judge` or `judge.enabled: false` skips it when you choose to, and `check` and `receipt` judge only with `--judge`.
+- 👀 **Shows the outcome** (on by default in `verify`; `check` and `receipt` with `--judge`): `verify` starts done-done's own judge, a fresh, tools-off agent on your own plan or key (Claude Code, opencode, pi or Gemini CLI, or your own OpenAI API key), to say whether each capture is the right screen for the claim (and each text capture, such as a log, JSON or CLI output, the right output), and a wrong one fails. You choose the judge (`done-done init --judge <agent> --judge-model <model>`, or pick it from the list `verify` shows in a terminal); done-done never picks one, and it must differ from the author by agent or by model (the same agent and model is refused). `--no-judge` or `judge.enabled: false` skips it when you choose to, and `check` and `receipt` judge only with `--judge`.
 - 🎨 **Looks right**: `done-done design <screens...> [--mock <screen>=<mock>]` has the same judge look at each captured screen, alone or next to its approved mock, and fails it on stretched or squashed images, clipped or squashed text, overlap, elements off-screen, blank or black strips and broken layout, naming each defect and where it is ([how](docs/reference.md#design-check)).
-- 🧩 **Page is clean** (with a `dom` block): each captured screen also needs its page-check record. A page that overflows the viewport, logs a console error, has a failed request or shows squashed text fails, unless an allow list names it ([how](docs/reference.md#dom-assertions)).
+- 📐 **Fits the screen**: `done-done look <url>` opens a web page in headless Chrome at a 390x844 phone viewport, captures it, and fails the journey that calls it on squashed text, clipped text, elements cut off by an edge or a page wider than the screen, naming each element, with no model ([how](docs/reference.md#look-check)).
+- 🧩 **Page is clean** (with a `dom` block): each captured screen also needs its page-check record. A page that overflows the viewport, logs a console error, has a failed request or shows squashed, clipped or cut-off UI fails, unless an allow list names it ([how](docs/reference.md#dom-assertions)).
 - 🔒 **Safe in CI**: `--trusted-ref origin/main` reads the rules from your main branch, so a pull request can't loosen them.
 
 Every answer is an exit code: **0** pass, **1** fail (or overridden at the gate), **2** usage or config error, **3** can't tell either way, **4** a `verify`, `maintain` or `rerun` run is still running, or a `verify` run waits at its gate.
@@ -185,12 +188,12 @@ Another fleet works the same way: add the include text to whatever your workers
 ## Learn more
 
 - [Vision](VISION.md): the three-tool family, the rules they share, and where done-done goes next.
-- [Full reference](docs/reference.md): every `init`, `doctor`, `run`, `check` and `receipt` option, the Checks block rules, each file check, and both config files.
+- [Full reference](docs/reference.md): every command and option, the Checks block rules, each file check, and both config files.
 - [Report a problem or ask a question](https://github.com/umeranjum17/done-done-axi/issues)
 
 ## What's next
 
-So far: `init`, `doctor`, `run`, `check`, `receipt`, `verify` (by journey or by your coding agent, with a gate you answer with `respond`), the capture judge (on by default in `verify`), the `design` visual check and the opt-in session hooks for Claude Code, Codex, opencode, Gemini CLI and pi. Coming next: help writing the proof steps for your app.
+So far: `init`, `doctor`, `run` (including `--open` and `--close`), `check`, `receipt`, `verify` (by journey or by your coding agent, with a gate you answer with `respond`), `maintain`, the capture judge (on by default in `verify`), the `design` visual check, the `look` step, the run tools (`status`, `attach`, `logs`, `rerun`, `abort`, `signoff`, `history`) and the opt-in session hooks for Claude Code, Codex, opencode, Gemini CLI and pi. Coming next: help writing the proof steps for your app.
 
 ## Develop
 

package/dist/agents.js

@@ -1,13 +1,16 @@
 import { spawn, spawnSync } from 'node:child_process';
 import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
-import { tmpdir } from 'node:os';
-import { dirname, isAbsolute, join } from 'node:path';
+import { homedir, tmpdir } from 'node:os';
+import { dirname, extname, isAbsolute, join } from 'node:path';
 import { stripVTControlCharacters } from 'node:util';
 import { AGENTS, ANSWERER_JUDGES, CHEAP, EFFORT_FLAGS, KEY_ROUTES, parseDuration, UsageError } from './config.js';
 import { isExecutable, onPath } from './judge.js';
 // argv never carries the prompt: it goes on stdin, or (file: true) into a 0600 prompt file the argv points at.
 // done-done parses the answer, validates it against the schema, and asks a tool-less call again, at most ASK_ATTEMPTS calls.
 const ASK_ATTEMPTS = 3;
+// A streaming agent that prints nothing for this long is stopped, so a hung CLI ends in minutes, not at the agent_timeout.
+// Only streaming adapters are watched: claude and gemini print their one answer at the end, so silence is their normal state.
+export const AGENT_IDLE_MS = 5 * 60_000;
 // What a user sees of an agent's error: no colour codes, only the last line that names an error (not a
 // stack frame, an indented field or a lone brace), at most 200 characters. The call record keeps the raw stderr.
 const ERROR_WORD = /\b(error|failed|denied|cancelled|refused|not|invalid|unauthorized)\b/i;
@@ -17,6 +20,27 @@ function errorLine(text) {
     const line = (top.findLast((l) => ERROR_WORD.test(l)) ?? top.at(-1) ?? lines.at(-1) ?? '').trim();
     return line.length > 200 ? `${line.slice(0, 199)}…` : line;
 }
+// A provider's rate limit (HTTP 429, a usage limit with its reset time). The CLI may retry it for many minutes, so the call stops at the first line that says so.
+const RATE_LIMIT = /\b429\b|rate[ -]?limit|usage limit|too many requests/i;
+const isRejectedRateLimit = (l) => {
+    try {
+        const e = JSON.parse(l);
+        return e.type === 'rate_limit_event' && e.rate_limit_info?.status === 'rejected';
+    }
+    catch {
+        return false;
+    }
+};
+// The first lines of an agent's stderr, one line: what it said before it failed or went quiet. Indented lines (stack frames, fields) are
+// left out, as in errorLine. '' when it said nothing.
+function stderrHead(stderr) {
+    const head = stripVTControlCharacters(stderr).split(/\r?\n/).filter((l) => /\w/.test(l) && !/^\s/.test(l)).slice(0, 2).map((l) => l.trim()).join(' | ');
+    return head.length > 300 ? `${head.slice(0, 299)}…` : head;
+}
+// opencode prints this on stderr and auto-rejects the ask when a headless run reaches a permission a non-interactive
+// call can never answer. The drive then ends with no answer, so name the permission and paths it refused instead of
+// the bare "no JSON object in the answer" its empty output would give.
+const PERMISSION_REJECT = /permission requested:\s*(\S+)\s*\(([^)]*)\);\s*auto-rejecting/;
 class ProviderError extends Error {
     detail;
     constructor(text, prefix = '', suffix = '') {
@@ -78,6 +102,7 @@ export function extractJsonObject(text, required = []) {
 // message chunks of acpx's JSON-RPC event stream. Every tool is denied, and a permission prompt is denied too, since
 // nobody can answer it. No model means the target's own default.
 const ACP = {
+    streams: true,
     argv: (c, dir) => ['--cwd', c.tools === 'none' ? dir : c.cwd, '--format', 'json', '--json-strict', '--deny-all',
         '--non-interactive-permissions', 'deny', ...(c.model ? ['--model', c.model] : []), c.agent.slice('acp:'.length), 'exec', '--file', '-'],
     answer: (out, c) => {
@@ -96,12 +121,21 @@ const PI_TOOL_LESS = ['--no-tools', '--no-extensions', '--no-skills', '--no-prom
 const ADAPTERS = {
     // claude -p: --json-schema puts the validated object in structured_output; --tools '' turns every tool off.
     // An edit step accepts edits only in cwd and --add-dir folders, and may run commands (the drive launches the app).
+    // The judge's call runs with the user's own sign-in, and with --safe-mode when safeMode is set.
+    // A call with images sends them as stream-json content blocks, as claude's SDK does, and its result is the event of type result.
     claude: {
-        argv: (c) => ['-p', '--output-format', 'json', '--json-schema', JSON.stringify(c.schema), '--model', c.model, '--no-session-persistence',
+        argv: (c) => ['-p', '--output-format', c.images?.length ? 'stream-json' : 'json', ...(c.images?.length ? ['--verbose', '--input-format', 'stream-json'] : []),
+            '--json-schema', JSON.stringify(c.schema), '--model', c.model, '--no-session-persistence',
             ...(c.tools === 'edit' ? ['--permission-mode', 'acceptEdits', '--allowedTools', 'Bash', ...(c.dirs ?? []).flatMap((d) => ['--add-dir', d])] : ['--tools', c.tools === 'read' ? 'Read,Grep,Glob' : '']),
-            ...(c.tools === 'edit' ? [] : ['--setting-sources', '']), ...(c.tools === 'read' ? ['--strict-mcp-config'] : [])],
-        answer: (out) => {
-            const r = JSON.parse(out);
+            ...(c.tools === 'edit' ? [] : ['--setting-sources', '']), ...(c.tools === 'read' ? ['--strict-mcp-config'] : []), ...(c.safeMode ? ['--safe-mode'] : [])],
+        stdin: (c, prompt) => (c.images?.length ? `${JSON.stringify({ type: 'user', session_id: '', parent_tool_use_id: null, message: { role: 'user', content: [
+                    ...c.images.flatMap((i) => [{ type: 'text', text: `Image: ${i.name.replace(/\.[^.]+$/, '')}` }, { type: 'image', source: { type: 'base64', media_type: `image/${extname(i.name).slice(1)}`, data: i.bytes.toString('base64') } }]),
+                    { type: 'text', text: prompt }
+                ] } })}\n` : prompt),
+        answer: (out, c) => {
+            const r = c.images?.length ? out.split('\n').filter((l) => l.startsWith('{')).map((l) => JSON.parse(l)).findLast((e) => e.type === 'result') : JSON.parse(out);
+            if (!r)
+                throw new ProviderError('claude printed no result');
             if (r.is_error)
                 throw new ProviderError(String(r.result || r.subtype));
             return r.structured_output;
@@ -111,6 +145,8 @@ const ADAPTERS = {
     // and the answer is the JSON object in the text parts of its JSON event stream.
     opencode: {
         file: true,
+        streams: true,
+        readsImages: true,
         argv: (c, dir) => ['run', 'Follow the attached instructions.', '--format', 'json', '-m', c.model, '-f', join(dir, 'prompt.md'), ...(c.images ?? []).flatMap((i) => ['-f', join(dir, i.name)])],
         answer: (out, c) => {
             const events = out.split('\n').filter((l) => l.startsWith('{')).map((l) => JSON.parse(l));
@@ -126,18 +162,37 @@ const ADAPTERS = {
             }
             return extractJsonObject(text, c.schema.required);
         },
-        // An edit step keeps the user's own permissions, where a folder outside cwd asks and so is refused in `run`; only the
-        // run's own folders are allowed.
-        env: (c) => ({ OPENCODE_PERMISSION: JSON.stringify(c.tools === 'edit' ? { external_directory: Object.fromEntries((c.dirs ?? []).flatMap((d) => [[d, 'allow'], [`${d}/*`, 'allow']])) } : { '*': 'deny' }) }),
+        // A headless `run` cannot answer a permission ask, so any ask auto-rejects and the drive ends with no answer.
+        // Driving the app runs commands that read or execute paths outside the repo (a browser, a system binary), so an
+        // edit step allows every external directory except the user's home folder, where only the run's own folders are
+        // allowed again; opencode's data folder (its login and database) is denied even when it is outside the home folder.
+        // opencode takes the last rule that matches, so the run folders come after the denies. Tool-less calls deny all.
+        env: (c) => {
+            if (c.tools !== 'edit')
+                return { OPENCODE_PERMISSION: JSON.stringify({ '*': 'deny' }) };
+            const home = homedir();
+            const data = join(process.env.XDG_DATA_HOME || join(home, '.local', 'share'), 'opencode');
+            return { OPENCODE_PERMISSION: JSON.stringify({ external_directory: {
+                        '*': 'allow', [home]: 'deny', [`${home}/*`]: 'deny', [data]: 'deny', [`${data}/*`]: 'deny',
+                        ...Object.fromEntries((c.dirs ?? []).flatMap((d) => [[d, 'allow'], [`${d}/*`, 'allow']])),
+                    } }) };
+        },
+        // A permission the run refused: the drive could not continue, so this is the reason, not a missing answer.
+        reject: (stderr) => {
+            const m = PERMISSION_REJECT.exec(stripVTControlCharacters(stderr));
+            return m ? `it asked for permission to ${m[1]} (${m[2]}), which a headless run cannot answer and auto-rejects` : '';
+        },
     },
-    // pi -p reads the prompt on stdin (probed 12 Oct: with no positional message, stdin becomes the user
+    // pi -p reads the prompt on stdin (probed: with no positional message, stdin becomes the user
     // message); --mode json streams JSONL events whose assistant message_end holds the answer text,
     // --no-session keeps the probe ephemeral. An @<file> argument attaches an image to that message.
-    // --no-tools turns every built-in and extension tool off (probed 13 Oct: a canary file outside the cwd went unread).
+    // --no-tools turns every built-in and extension tool off (probed: a canary file outside the cwd went unread).
     // A tool-less call also loads no extensions, skills, prompt templates or context files: they would add the user's own
-    // context to a fresh judge, and extension loading took 2 minutes on a real setup (probed 13 Oct), past the judge's timeout.
+    // context to a fresh judge, and extension loading took 2 minutes on a real setup (probed), past the judge's timeout.
     // Pi has no permission gate for edit steps, so doctor warns about it. Without a model, pi runs its own default.
     pi: {
+        streams: true,
+        readsImages: true,
         argv: (c, dir) => ['-p', '--mode', 'json', '--no-session', ...(c.tools === 'edit' ? [] : PI_TOOL_LESS), ...(c.model ? ['--model', c.model] : []), ...(c.images ?? []).map((i) => `@${join(dir, i.name)}`)],
         answer: (out, c) => {
             let text = '';
@@ -166,11 +221,12 @@ const ADAPTERS = {
     // answer, and --ephemeral keeps no session. An edit step runs in codex's workspace-write sandbox, which writes only the
     // repo, the run's folders (--add-dir) and $TMPDIR; it may use the network, since the drive launches the app and talks
     // to it, and it keeps the user's config.toml. Without a model, codex runs its own default.
-    // A tool-less call is refused: probed live 13 Oct, codex with the user's config.toml kept its MCP server, which read a
+    // A tool-less call is refused: codex with the user's config.toml kept its MCP server, which read a
     // canary file outside the folder, and --disable does not turn off its multi-agent tools.
     codex: {
+        streams: true,
         editOnly: 'codex cannot run tool-less: with your config.toml it keeps its MCP tools, which read files outside the folder',
-        // Seen live 13 Oct: each sandboxed command runs in its own process namespace, so a server or browser bridge started in the
+        // Each sandboxed command runs in its own process namespace, so a server or browser bridge started in the
         // background by one command was gone by the next one, and a drive that launched the app and then browsed it captured nothing.
         editNote: 'Your shell sandbox ends every process a command started, background ones too, when that command ends. So start what a task needs (an app, a server, a browser bridge), use it, save what it produces and stop it within one shell command (a script in $TMPDIR is fine).',
         argv: (c) => ['exec', '--json', '--ephemeral', ...(c.model ? ['-m', c.model] : []),
@@ -207,6 +263,7 @@ const ADAPTERS = {
     // policy folder and removes every tool, MCP ones too, from the model (its policy-engine.md). An @<file> in the -p text
     // attaches an image: per Gemini CLI's source, its own @-command code reads it, outside the tool policy, and only inside the cwd, the call's scratch folder; not yet proven live (Gemini CLI was not signed in on the test machine).
     gemini: {
+        readsImages: true,
         argv: (c, dir) => ['-p', ['Follow the instructions on stdin.', ...(c.images ?? []).map((i) => `@${i.name}`)].join(' '), '-o', 'json', '-m', c.model, '--approval-mode', c.tools === 'edit' ? 'auto_edit' : 'plan',
             ...(c.tools === 'none' ? ['--policy', join(dir, 'deny-all.toml'), '--skip-trust'] : []),
             ...(c.tools === 'edit' ? ['--allowed-tools', 'run_shell_command', ...(c.dirs ?? []).flatMap((d) => ['--include-directories', d])] : [])],
@@ -262,7 +319,6 @@ export function agentPath(agent, cfg) {
         acpxRuns.set(acpx, spawnSync(acpx, ['--version'], { stdio: 'ignore', timeout: 5_000 }).status === 0);
     return acpxRuns.get(acpx) ? acpx : '';
 }
-export const claudeBin = (cfg) => agentPath('claude', cfg);
 export const routeOf = (agent) => (agent === 'claude' ? 'claude-code' : `answerer:${agent}`);
 export const JUDGES = AGENTS.filter((a) => a === 'claude' || ANSWERER_JUDGES.includes(a));
 // Like the agent, the judge is exactly the one the user set; with none, done-done asks the user (in a terminal) or
@@ -288,14 +344,14 @@ export function selectJudge(cfg, found, fix = false) {
     if (fix && independence !== 'agent')
         throw new UsageError(`judge: the judge ${agent} (model ${model}) is the fixer's own agent (${found.agent}) at any model, and the judge is never the agent that did the work; judge.allow_same does not apply to auto_fix`, 'Ask the user for another judge agent and save it: done-done init --judge <agent> --judge-model <model>');
     if (independence === 'session-only' && !cfg.judge.allow_same)
-        throw new UsageError(`judge: the judge ${agent} (model ${model}) is the author's own agent and model (${found.agent}), and the judge is never the agent that did the work`, `Ask the user for another judge agent or model and save it: done-done init --judge <agent> --judge-model <model>; or set judge.allow_same: true in ~/.done-done/config.yaml to accept a fresh session of the same one`);
+        throw new UsageError(`judge: the judge ${agent} (model ${model}) is the author's own agent and model (${found.agent}), and the judge must differ from the author by agent or by model`, `done-done init --judge <agent> --judge-model <model>, with another agent or the same agent at another model; judge.allow_same: true in ~/.done-done/config.yaml is an opt-out only, for a fresh session of the same agent and model`);
     return { route, agent, model, independence, author: { agent: found.agent, model: found.model } };
 }
 const DRAIN_MS = 500;
 const OUTPUT_CAP = 64 << 20;
 // One agent process. An edit step gets its own process group, so whatever it started (a dev server, a browser) is
 // killed with it when it ends, times out or writes past the output cap.
-function start(bin, argv, c, cwd, input, env) {
+function start(bin, argv, c, cwd, input, env, idleMs) {
     const group = c.tools === 'edit';
     return new Promise((done) => {
         const child = spawn(bin, argv, { cwd, env, detached: group });
@@ -303,6 +359,39 @@ function start(bin, argv, c, cwd, input, env) {
         let stderr = '';
         let error;
         let drain;
+        let idle;
+        // A rate-limit line ends the call with that line, whatever the agent does next. On stdout the line must also say when it resets or retries,
+        // so an answer that only quotes a 429 from the app's code does not stop the call. A claude call with images streams JSON lines,
+        // and only a rejected rate_limit_event on stdout stops it, so its complete lines are parsed one at a time.
+        let pendingStdout = '';
+        const limited = (chunk, stdoutLine) => {
+            let line;
+            if (c.agent === 'claude' && c.images?.length) {
+                if (!stdoutLine)
+                    return;
+                const text = pendingStdout + chunk;
+                const end = text.lastIndexOf('\n') + 1;
+                pendingStdout = text.slice(end);
+                line = text.slice(0, end).split('\n').find(isRejectedRateLimit);
+            }
+            else {
+                line = stripVTControlCharacters(chunk).split(/\r?\n/).find((l) => RATE_LIMIT.test(l) && (!stdoutLine || /reset|retry/i.test(l)));
+            }
+            if (!line || error)
+                return;
+            error = new Error(`${c.agent} hit a rate limit and stopped: ${line.trim().slice(0, 200)}`);
+            kill();
+        };
+        // Any output (stdout or stderr) shows the agent is working; silence for idleMs is a hang.
+        const quiet = () => {
+            if (!idleMs)
+                return;
+            clearTimeout(idle);
+            idle = setTimeout(() => {
+                error = new Error(`${c.agent} printed nothing for ${Math.round(idleMs / 1000)}s`);
+                kill();
+            }, idleMs);
+        };
         const kill = () => {
             try {
                 if (group)
@@ -324,18 +413,24 @@ function start(bin, argv, c, cwd, input, env) {
         }, c.timeoutMs);
         child.on('error', (e) => {
             clearTimeout(timer);
+            clearTimeout(idle);
             done({ status: null, stdout, stderr, error: e });
         });
         if (!child.pid)
             return;
         if (group)
             c.onSpawn?.(child.pid);
+        quiet();
         child.stdout.setEncoding('utf8').on('data', (d) => {
+            quiet();
+            limited(d, true);
             stdout += d;
             if (stdout.length > OUTPUT_CAP)
                 overflow();
         });
         child.stderr.setEncoding('utf8').on('data', (d) => {
+            quiet();
+            limited(d, false);
             stderr += d;
             if (stderr.length > OUTPUT_CAP)
                 overflow();
@@ -348,6 +443,7 @@ function start(bin, argv, c, cwd, input, env) {
         });
         child.on('close', (status) => {
             clearTimeout(timer);
+            clearTimeout(idle);
             clearTimeout(drain);
             if (group)
                 kill();
@@ -374,8 +470,9 @@ export async function askAgent(c) {
             throw new Error(`no adapter for ${c.agent} yet`);
         if (adapter.editOnly && c.tools !== 'edit')
             throw new Error(adapter.editOnly);
-        for (const i of c.images ?? [])
-            writeFileSync(join(dir, i.name), i.bytes, { mode: 0o600 });
+        if (adapter.readsImages)
+            for (const i of c.images ?? [])
+                writeFileSync(join(dir, i.name), i.bytes, { mode: 0o600 });
         for (const [name, text] of Object.entries(adapter.files?.(c) ?? {}))
             writeFileSync(join(dir, name), text, { mode: 0o600 });
         const bin = c.path;
@@ -385,15 +482,20 @@ export async function askAgent(c) {
         for (;;) {
             attempts++;
             // An ask-again names what was wrong with the last answer. The trailer ends on words, not the schema: a weak model
-            // (Go Muse, 13 Oct) copied a schema that closed the prompt back as its answer.
+            // (seen with one opencode model) copied a schema that closed the prompt back as its answer.
             const schemaTrailer = `\n\nAnswer with only one JSON object that matches this JSON schema:\n${JSON.stringify(c.schema)}\nThat object holds your own values, never the schema itself, and you send no other text.\n`;
             const prompt = c.tools === 'edit' && adapter.editNote ? `${c.prompt}\n\n${adapter.editNote}` : c.prompt;
             const promptText = (attempts === 1 ? prompt : `${prompt}\n\nYour previous answer was not valid (${lastError}).`) + schemaTrailer;
             if (adapter.file)
                 writeFileSync(join(dir, 'prompt.md'), promptText, { mode: 0o600 });
-            res = await start(bin, argv(dir), c, cwd, adapter.file ? '' : promptText, { ...process.env, ...c.env, ...adapter.env?.(c) });
+            const input = adapter.file ? '' : adapter.stdin ? adapter.stdin(c, promptText) : promptText;
+            res = await start(bin, argv(dir), c, cwd, input, { ...process.env, ...c.env, ...adapter.env?.(c) }, adapter.streams ? c.idleMs ?? AGENT_IDLE_MS : 0);
             if (res.error)
                 throw res.error;
+            // A permission the run refused explains a call with no answer; name it rather than the exit code text.
+            const refused = adapter.reject?.(String(res.stderr ?? '')) ?? '';
+            if (res.status !== 0 && refused)
+                throw new ProviderError(refused, `${c.agent} exited ${res.status}: `);
             if (res.status !== 0) {
                 // An agent that exits non-zero may still say why in its own output (claude: a usage limit, a bad model).
                 let text = String(res.stderr || res.stdout).trim().slice(-500);
@@ -421,6 +523,9 @@ export async function askAgent(c) {
             catch (e) {
                 if (e instanceof ProviderError)
                     throw e;
+                // A refused permission is why there is no usable answer, not a bad answer: name it instead of "no JSON object".
+                if (refused)
+                    throw new ProviderError(refused, `${c.agent} did not finish: `);
                 // Only a tool-less call is asked again: an edit or read step may already have changed the repo or read it.
                 lastError = e.message;
                 if (c.tools !== 'none' || attempts >= (c.attempts ?? ASK_ATTEMPTS))
@@ -429,8 +534,13 @@ export async function askAgent(c) {
         }
     }
     catch (e) {
-        out = { ok: false, error: e.message };
-        failure = e instanceof ProviderError ? e.detail : e.message;
+        // A silent, hung or timed-out agent says why only on stderr, so its no-answer reason quotes that. A provider error already
+        // carries its own line, so it is left as it is.
+        const said = stderrHead(String(res?.stderr ?? ''));
+        const provider = e instanceof ProviderError;
+        const note = (text) => (!provider && said && !text.includes(said.split(' | ')[0]) ? `${text}; ${c.agent} stderr: ${said}` : text);
+        out = { ok: false, error: note(e.message), ...(!provider && said ? { stderr: said } : {}) };
+        failure = note(e instanceof ProviderError ? e.detail : e.message);
     }
     finally {
         if (dir)