agent-from-zero 0.1.0 → 0.27.0

package/dist/loop.js

@@ -1,11 +1,16 @@
 import chalk from "chalk"; // terminal colors for status lines
 import ora from "ora"; // the "thinking..." spinner while waiting for the first token
-import { toolDefinitions, dispatch, snapshotFileState, restoreFileState } from "./tools.js"; // the tool manuals + the executor + file-state isolation
+import { toolDefinitions, dispatch, snapshotFileState, restoreFileState, isReadOnlyTool } from "./tools.js"; // the tool manuals + the executor + file-state isolation
 import { classifyError, ApiErrorKind } from "./errors.js"; // failure taxonomy
 import { checkPermission } from "./permissions.js"; // the allow/ask/deny gate
+import { previewChange } from "./diff.js"; // show the diff before a write so approval is informed
 import { estimateHistoryTokens, compactHistory, COMPACT_AT, MAX_COMPACTIONS_PER_QUERY, MAX_COMPACT_FAILURES } from "./context.js"; // context management
 import { SUB_AGENT_PROMPT } from "./prompt.js"; // the sub-agent's own constitution
-export const MAX_ROUNDS = 15; // model→tool round cap per query
+import { emit } from "./telemetry.js"; // local-only event log (no-op unless the CLI armed it)
+import { runHooks } from "./hooks.js"; // user lifecycle hooks (PreToolUse / PostToolUse / Stop)
+import { recordUsage } from "./cost.js"; // meter token usage from the stream
+import { mark, thinkingWord, spinnerText } from "./ui.js"; // centralized terminal styling (markers, spinner)
+import { printToolSummary } from "./tui.js"; // collapsible tool output
 export const MAX_RETRIES = 10; // total failed API calls per query, across all rounds
 export const MAX_RATE_LIMIT_RETRIES = 3; // 429s get their own, much smaller budget
 export const MAX_CONSECUTIVE_FAILURES = 3; // the circuit breaker
@@ -18,7 +23,6 @@ const STALL_WARN_MS = 30_000; // events arriving slowly → log only. Slow is no
 export var TerminateReason;
 (function (TerminateReason) {
     TerminateReason["Done"] = "done";
-    TerminateReason["RoundCap"] = "round_cap";
     TerminateReason["CircuitBreaker"] = "circuit_breaker";
     TerminateReason["RetryBudgetExhausted"] = "retry_budget_exhausted";
     TerminateReason["RateLimitBudgetExhausted"] = "rate_limit_budget_exhausted";
@@ -27,6 +31,12 @@ export var TerminateReason;
     TerminateReason["FatalApiError"] = "fatal_api_error";
     TerminateReason["UserInterrupt"] = "user_interrupt";
 })(TerminateReason || (TerminateReason = {}));
+// Which model should a delegated sub-agent run on? The configured sub-agent
+// model if set and non-blank, otherwise the same model as the orchestrator.
+// Pulled out as a pure function so the tiering rule is testable on its own.
+export function subAgentModelFor(opts) {
+    return opts.subAgentModel?.trim() || opts.model;
+}
 // The task tool: the parent's handle on sub-agents. Defined here (not in
 // tools.ts) because running it needs the loop itself — it IS a loop.
 const taskTool = {
@@ -47,18 +57,53 @@ On error: a failed sub-agent returns [sub-agent failed: reason] — retry with a
         },
     },
 };
+// The ask_user tool: the model's handle on the user. When it needs the human to
+// choose between options, it calls this instead of asking in prose — and gets
+// back clean, structured selections rather than a free-text paragraph to parse.
+const askUserTool = {
+    type: "function",
+    function: {
+        name: "ask_user",
+        description: `Ask the user one or more multiple-choice questions and get back their selections. Use this WHENEVER you need the user to make a decision between options (which approach, which file, yes/no/which) — it is easier for them to pick than to type, and the answers come back unambiguous.
+Provide each question with 2–4 concrete options. Do NOT use it for open-ended input that has no clear options; ask in prose for that.
+If the user cancels, you'll be told — then proceed with your best judgment or ask again.`,
+        parameters: {
+            type: "object",
+            properties: {
+                questions: {
+                    type: "array",
+                    description: "The questions to ask, each with a list of options",
+                    items: {
+                        type: "object",
+                        properties: {
+                            question: { type: "string", description: "The question text" },
+                            options: { type: "array", items: { type: "string" }, description: "2–4 concrete choices" },
+                        },
+                        required: ["question", "options"],
+                    },
+                },
+            },
+            required: ["questions"],
+        },
+    },
+};
 // Run one sub-agent: a fresh conversation, same tools minus task, same
 // permission gate, and the parent's file read-state protected by a snapshot.
 async function runSubAgent(description, opts) {
+    emit("agent_subagent_spawn"); // delegation is worth counting
+    const subModel = subAgentModelFor(opts); // the tier this delegated work runs on
+    // Show the delegation, and the model when it differs from the orchestrator's —
+    // the tiering should be visible, not a silent surprise on the bill.
     if (!opts.quiet)
-        console.log(chalk.blue(`  ⎿ sub-agent started: ${description.slice(0, 100)}`)); // show the delegation
+        console.log(mark.subAgentStart(description.slice(0, 100), subModel !== opts.model ? subModel : "")); // annotate the tier only on a real switch
+    await runHooks("SubagentStart", { description: description.slice(0, 200), model: subModel }); // lifecycle hook (observational)
     const snapshot = snapshotFileState(); // what the sub-agent reads, the parent has NOT seen
     try {
         const subMessages = [
             { role: "system", content: SUB_AGENT_PROMPT }, // its own, smaller constitution
             { role: "user", content: description }, // the task is its entire world
         ];
-        const result = await runLoop(subMessages, { ...opts, subAgent: true }); // recurse, flagged as sub-agent
+        const result = await runLoop(subMessages, { ...opts, subAgent: true, model: subModel }); // recurse as a sub-agent, on its own tier
         if (result.reason === TerminateReason.Done && result.finalText?.trim()) {
             // The framing matters: the parent must treat this as material to verify,
             // not as conclusions to copy — the most common multi-agent failure mode.
@@ -68,8 +113,9 @@ async function runSubAgent(description, opts) {
     }
     finally {
         restoreFileState(snapshot); // the parent's read-before-edit state, exactly as it was
+        await runHooks("SubagentStop", { description: description.slice(0, 200) }); // lifecycle hook (observational)
         if (!opts.quiet)
-            console.log(chalk.blue("  ⎿ sub-agent done")); // close the bracket
+            console.log(mark.subAgentDone); // close the bracket
     }
 }
 // Exponential backoff with jitter: 500ms, 1s, 2s, ... ±25%, capped.
@@ -86,56 +132,92 @@ async function interruptibleSleep(ms, isInterrupted) {
         await new Promise((r) => setTimeout(r, Math.min(SLICE, ms - waited))); // sleep one slice (or the remainder)
     }
 }
+let modelCallSeq = 0; // increments per model call — seeds the rotating spinner word
 // One streaming model call: prints text as it arrives, assembles tool calls
 // from their deltas, and guards the stream with a two-level watchdog.
 async function streamModelCall(messages, // the full history to send
 opts) {
     const idleAbort = new AbortController(); // the watchdog's own kill switch
     const signal = AbortSignal.any([opts.signal, idleAbort.signal]); // either the user or the watchdog can abort
+    const word = thinkingWord(modelCallSeq++); // a rotating "thinking" word for this call
+    const startedAt = Date.now(); // for the spinner's live elapsed counter
+    let streamedChars = 0; // bytes of content+reasoning streamed this call → a live token estimate
     const spinner = opts.quiet
         ? null // the eval harness wants silence
-        : ora({ text: opts.subAgent ? "sub-agent working..." : "thinking...", discardStdin: false }).start(); // discardStdin:false — ora would otherwise eat Ctrl+C
+        : ora({ text: spinnerText(word, 0, !!opts.subAgent, opts.model), discardStdin: false }).start(); // discardStdin:false — ora would otherwise eat Ctrl+C
     let lastEvent = Date.now(); // when did we last hear ANYTHING from the stream?
     let stallWarned = false; // only warn once per quiet stretch
     // The two-level watchdog, checked once per second:
     // - idle (nothing at all for 90s) → cut the stream, let the retry layer handle it
     // - stall (slow but alive for 30s) → log it and keep waiting
+    // It also ticks the spinner: elapsed seconds + a live token estimate (~chars/4).
     const watchdog = setInterval(() => {
+        if (spinner?.isSpinning)
+            spinner.text = spinnerText(word, Math.floor((Date.now() - startedAt) / 1000), !!opts.subAgent, opts.model, Math.round(streamedChars / 4));
         const quietMs = Date.now() - lastEvent; // ms since the last event
-        if (quietMs > IDLE_TIMEOUT_MS)
+        if (quietMs > IDLE_TIMEOUT_MS) {
+            emit("agent_watchdog_idle"); // record the cut — these should be rare
             idleAbort.abort(); // dead — cut it
+        }
         else if (quietMs > STALL_WARN_MS && !stallWarned) {
             stallWarned = true; // don't repeat the warning every second
+            emit("agent_watchdog_stall"); // record the slowness — pattern-spotting data
             console.log(chalk.dim(`  [watchdog] stream quiet for ${Math.round(quietMs / 1000)}s — still waiting (slow ≠ dead)`));
         }
     }, 1000);
     try {
+        emit("agent_api_call"); // one event per attempt — retries show up as extra calls
         const stream = await opts.client.chat.completions.create(
         // Sub-agents do NOT get the task tool: one level of delegation only.
         // Nested spawning means orphan processes and debugging hell.
-        { model: opts.model, messages, tools: opts.subAgent ? toolDefinitions : [...toolDefinitions, taskTool], stream: true }, { signal });
+        // include_usage adds a final chunk carrying token counts — that is how we
+        // meter cost without a second (counting) request.
+        { model: opts.model, messages, tools: opts.subAgent ? toolDefinitions() : [...toolDefinitions(), taskTool, askUserTool], stream: true, stream_options: { include_usage: true } }, { signal });
         let content = ""; // accumulated answer text
-        let printedPrefix = false; // have we printed the 🤖 prefix yet?
+        let printedPrefix = false; // have we printed the answer prefix yet?
+        let printedThinking = false; // have we started printing the reasoning trace yet?
         const calls = []; // tool calls under assembly, indexed by delta.index
         for await (const chunk of stream) {
             lastEvent = Date.now(); // feed the watchdog
             stallWarned = false; // the stream spoke — reset the stall warning
+            if (chunk.usage)
+                recordUsage(chunk.usage); // the final usage chunk — meter it
             const delta = chunk.choices[0]?.delta; // this chunk's increment
             if (!delta)
                 continue; // keep-alive or usage chunk — nothing to do
+            // Reasoning models (e.g. deepseek-reasoner / R1) stream their thinking in a
+            // separate `reasoning_content` field BEFORE the answer. Show it dimly so a
+            // switch to a reasoning model is visibly different — but do NOT keep it:
+            // the reasoning is not the answer and must not be replayed in later turns.
+            const reasoning = delta.reasoning_content;
+            if (reasoning) {
+                streamedChars += reasoning.length; // count reasoning toward the live token estimate
+                if (spinner?.isSpinning)
+                    spinner.stop();
+                if (!opts.quiet && !opts.subAgent) {
+                    if (!printedThinking) {
+                        process.stdout.write("\n" + chalk.dim("💭 thinking: ")); // label the trace once
+                        printedThinking = true;
+                    }
+                    process.stdout.write(chalk.dim(reasoning)); // stream the thinking, dimmed
+                }
+            }
             if (delta.content) {
+                streamedChars += delta.content.length; // count the answer toward the live token estimate
                 if (spinner?.isSpinning)
                     spinner.stop(); // first token: replace the spinner with real output
                 if (!opts.quiet && !opts.subAgent) {
                     // Only the top-level agent streams to the screen — a sub-agent's
                     // inner monologue would be mistaken for the answer.
+                    if (printedThinking && !printedPrefix)
+                        process.stdout.write("\n"); // end the thinking block before the answer
                     if (!printedPrefix) {
-                        process.stdout.write("\n🤖 "); // prefix once, then stream raw
+                        process.stdout.write("\n" + mark.answer); // prefix once (⏺), then stream raw
                         printedPrefix = true;
                     }
                     process.stdout.write(delta.content); // print the token immediately — this IS the streaming UX
                 }
-                content += delta.content; // always keep it for the history
+                content += delta.content; // always keep it for the history (the answer only, never the reasoning)
             }
             for (const tc of delta.tool_calls ?? []) {
                 if (spinner?.isSpinning)
@@ -159,11 +241,116 @@ opts) {
             spinner.stop(); // and never leave a zombie spinner
     }
 }
+// Run one tool call end to end: log it, run it through the permission gate,
+// ask the human if needed, execute, and return the paired result. Read-only
+// calls (allow/deny only, never "ask") are safe to run via this from inside a
+// Promise.all batch; calls that can prompt must be awaited one at a time.
+async function runOneCall(call, opts) {
+    const indent = opts.subAgent ? chalk.blue("  ⎿ ") : ""; // sub-agent activity is visually nested
+    if (!opts.quiet) {
+        // Compact one-line summary — long args are hidden behind Tab.
+        const summary = indent + mark.tool(call.name, call.args.length > 60 ? call.args.slice(0, 57) + "..." : call.args);
+        const full = `tool: ${call.name}\nargs: ${call.args}`;
+        printToolSummary(summary, full);
+    }
+    // The permission gate sits between the model's intent and execution.
+    const v = checkPermission(call.name, call.args);
+    emit("agent_tool_call", { tool: call.name }); // every attempt, allowed or not
+    // For file-changing tools, show the diff BEFORE the gate decides. A filename
+    // ("edit_file: cart.js") is not enough to approve safely; the actual +/- lines
+    // are. Skipped for a hard deny (nothing will run) and in quiet sub-agent runs.
+    if (!opts.quiet && v.decision !== "deny" && (call.name === "write_file" || call.name === "edit_file")) {
+        const preview = previewChange(call.name, call.args);
+        if (preview)
+            console.log(preview.replace(/^/gm, indent)); // nest under the sub-agent marker if any
+    }
+    let content; // what goes back to the model as the tool result
+    if (v.decision === "deny") {
+        emit("agent_tool_denied", { tool: call.name }); // hard blocks, per tool
+        if (!opts.quiet)
+            console.log(mark.denied(v.reason)); // tell the user we blocked it
+        content = `[permission] Denied: ${v.reason}. This is a hard rule — do not try to work around it; pick a different approach or ask the user.`; // teach the model the boundary
+    }
+    else if (v.decision === "ask") {
+        // Optional LLM judge: for a run_bash command the rules couldn't classify,
+        // ask the judge first. It can only DOWNGRADE ask→allow for the clearly
+        // safe; anything else still goes to the human. The judge never sees a deny.
+        let autoAllowed = false;
+        if (opts.judge && call.name === "run_bash") {
+            let cmd = "";
+            try {
+                cmd = JSON.parse(call.args).command ?? "";
+            }
+            catch { /* leave empty → judge will ask */ }
+            if (cmd && (await opts.judge.classify(cmd)) === "allow") {
+                autoAllowed = true;
+                if (!opts.quiet)
+                    console.log(mark.judge); // visible — the user can see the judge worked
+            }
+        }
+        const ok = autoAllowed || (await opts.confirm(`${call.name} (${v.reason}):\n   ${v.summary}`, call.name)); // judge-allowed, or pause and ask the human
+        if (!ok)
+            emit("agent_tool_declined", { tool: call.name }); // the human said no — that is signal
+        if (!ok && !opts.quiet)
+            console.log(mark.declined); // make the refusal visible
+        content = ok
+            ? await runWithHooks(call, opts) // approved — run it (PreToolUse can still block)
+            : `[permission] The user declined this action. Ask them how to proceed, or choose a safer alternative.`; // declined — tell the model
+    }
+    else {
+        content = await runWithHooks(call, opts); // allow — run it (PreToolUse can still block)
+    }
+    return { id: call.id, content }; // paired by id for the API
+}
+// Run an approved tool call, surrounded by the user's lifecycle hooks.
+// PreToolUse can block (exit 2) — its stderr is fed back to the model as the
+// reason, exactly like a permission denial, so the model adapts instead of
+// retrying. PostToolUse is observational; if it blocks, its message is appended
+// to the tool result as extra context (e.g. "lint failed on the file you just
+// wrote"). Sub-agents skip hooks: hooks are about the human's project policy,
+// not internal delegation.
+async function runWithHooks(call, opts) {
+    if (opts.subAgent)
+        return execute(call, opts); // sub-agents run hook-free
+    const pre = await runHooks("PreToolUse", { tool: call.name, args: call.args }); // before
+    if (pre.block) {
+        emit("agent_hook_block", { event: "PreToolUse", tool: call.name }); // a hook said no
+        if (!opts.quiet)
+            console.log(mark.hookBlock("PreToolUse")); // make it visible
+        return `[hook] A PreToolUse hook blocked this call: ${pre.feedback}. Treat this as a hard boundary — adjust your approach.`;
+    }
+    // A PreToolUse hook may REWRITE the arguments (e.g. add a commit trailer). The
+    // permission gate already ran on the original args; the rewrite only narrows or
+    // annotates, never escalates past a deny. Validate it's parseable, then use it.
+    if (pre.rewrite) {
+        try {
+            JSON.parse(pre.rewrite); // must be valid JSON args
+            if (!opts.quiet)
+                console.log(chalk.dim(`  ⎿ PreToolUse hook rewrote the arguments`));
+            call = { ...call, args: pre.rewrite };
+        }
+        catch {
+            /* malformed rewrite — ignore, run the original args */
+        }
+    }
+    const result = await execute(call, opts); // the actual work
+    const post = await runHooks("PostToolUse", { tool: call.name, args: call.args, result }); // after
+    if (post.block) {
+        // PostToolUse cannot undo the action, but it can tell the model something
+        // is wrong with the result — surface that as appended context.
+        return `${result}\n\n[hook] PostToolUse: ${post.feedback}`;
+    }
+    return result;
+}
 // Execute one approved tool call. The task tool is special — it is not in the
 // registry because running it needs the loop itself (it IS a loop).
 async function execute(call, opts) {
+    // ask_user is special like task: running it needs the CLI's prompt, not the
+    // tool registry. It presents a form and feeds the selections back to the model.
+    if (call.name === "ask_user")
+        return runAskUser(call, opts);
     if (call.name !== "task")
-        return dispatch(call.name, call.args); // ordinary tools go through the registry
+        return dispatch(call.name, call.args, opts.signal); // ordinary tools go through the registry (signal lets Ctrl+C kill run_bash)
     if (opts.subAgent)
         return "[error] Sub-agents cannot spawn sub-agents. Do the work yourself."; // one level of delegation only
     let description = ""; // the sub-task text
@@ -177,6 +364,29 @@ async function execute(call, opts) {
         return "[error] task requires a non-empty description argument.";
     return runSubAgent(description, opts); // spawn the worker
 }
+// Present the ask_user form and turn the selections into a tool result. The
+// model called this to get a decision; we give it clean question→answer pairs.
+async function runAskUser(call, opts) {
+    if (opts.subAgent)
+        return "[error] Sub-agents cannot ask the user. Decide yourself, or report back to the parent."; // only the top-level agent talks to the human
+    if (!opts.askUser)
+        return "[error] No interactive prompt is available in this session — ask in plain text instead.";
+    let questions = [];
+    try {
+        questions = JSON.parse(call.args).questions ?? [];
+    }
+    catch {
+        /* fall through */
+    }
+    // Keep only well-formed questions (text + at least two options).
+    questions = (questions ?? []).filter((q) => q && typeof q.question === "string" && Array.isArray(q.options) && q.options.length >= 2);
+    if (!questions.length)
+        return "[error] ask_user needs at least one question with two or more options.";
+    const answers = await opts.askUser(questions);
+    if (!answers)
+        return "The user dismissed the question form without answering. Proceed with your best judgment, or ask again if you truly need their input."; // cancelled / non-interactive
+    return `The user answered:\n${answers.map((a) => `- ${a.question} → ${a.answer}`).join("\n")}`; // organized, unambiguous
+}
 // Run one compaction attempt and keep score. Returns true on success.
 // Every automatic behavior keeps a failure count — that is what lets the
 // caller stop a hot failure loop instead of compacting forever.
@@ -184,13 +394,19 @@ async function tryCompact(messages, // history to compact (mutated in place)
 opts, // for client/model/signal
 compaction) {
     try {
+        if (!opts.subAgent)
+            await runHooks("PreCompact", {}); // lifecycle hook (top-level only; hooks are the human's project policy)
         await compactHistory(messages, opts.client, opts.model, opts.signal); // do the actual work
         compaction.count++; // one more successful compaction this query
         compaction.failures = 0; // success resets the failure streak
+        emit("agent_compaction_ok"); // worth counting — frequent compaction means tasks are too big
+        if (!opts.subAgent)
+            await runHooks("PostCompact", {}); // observational
         return true;
     }
     catch {
         compaction.failures++; // failed — count it against the breaker
+        emit("agent_compaction_failed"); // a failure streak here trips the breaker
         return false;
     }
 }
@@ -201,7 +417,7 @@ opts) {
     // The loop's mutable state: budgets and counters, rewritten every iteration.
     const attempts = { total: 0, rateLimited: 0, consecutive: 0 };
     const compaction = { count: 0, failures: 0 }; // compaction score card for this query
-    for (let round = 1; round <= MAX_ROUNDS; round++) {
+    for (let round = 1;; round++) {
         // One round = one successful model call + its tool results.
         // The inner loop retries the model call until it succeeds or a budget dies.
         while (true) {
@@ -240,6 +456,7 @@ opts) {
                 }
                 if (!e.retryable)
                     return { reason: TerminateReason.FatalApiError, detail: `${e.kind}: ${e.message}` }; // bad key etc. — stop now
+                emit("agent_api_error", { kind: e.kind, attempt: attempts.total + 1 }); // classified, greppable
                 attempts.total++; // every failure consumes the overall budget
                 attempts.consecutive++; // ...and the breaker counter
                 if (e.kind === ApiErrorKind.RateLimited)
@@ -276,36 +493,47 @@ opts) {
                     : {}), // omit the field entirely when there were no calls
             });
             if (!out.toolCalls.length) {
+                // The model wants to stop. A Stop hook gets the last word: if it exits
+                // 2, the agent is NOT done — its stderr becomes a new instruction and
+                // the loop continues. This is how you build test-driven AI: a Stop hook
+                // runs the tests, blocks while they fail, and the agent keeps fixing.
+                // Sub-agents are exempt — Stop hooks are the human's project policy.
+                if (!opts.subAgent) {
+                    const stop = await runHooks("Stop", { finalText: out.content }); // give hooks the last word
+                    if (stop.block) {
+                        emit("agent_hook_block", { event: "Stop" }); // the agent was sent back to work
+                        if (!opts.quiet)
+                            console.log(chalk.yellow(`\n↩ Stop hook: not done yet — ${stop.feedback.slice(0, 120)}`)); // show why
+                        messages.push({ role: "user", content: `[Stop hook] You are not finished: ${stop.feedback}` }); // inject the instruction
+                        break; // exit the inner while → advance the round counter
+                    }
+                }
                 return { reason: TerminateReason.Done, finalText: out.content }; // no tool calls = final answer (already streamed to the screen)
             }
-            // Execute every tool call, each behind the permission gate.
-            for (const call of out.toolCalls) {
-                const indent = opts.subAgent ? chalk.blue("  ⎿ ") : ""; // sub-agent activity is visually nested
-                if (!opts.quiet)
-                    console.log(indent + chalk.cyan(`🔧 ${call.name}`) + chalk.dim(` ${call.args.slice(0, 120)}`)); // show what the model wants to do
-                // The permission gate sits between the model's intent and execution.
-                const v = checkPermission(call.name, call.args);
-                let content; // what goes back to the model as the tool result
-                if (v.decision === "deny") {
-                    if (!opts.quiet)
-                        console.log(chalk.red(`  ⛔ denied: ${v.reason}`)); // tell the user we blocked it
-                    content = `[permission] Denied: ${v.reason}. This is a hard rule — do not try to work around it; pick a different approach or ask the user.`; // teach the model the boundary
-                }
-                else if (v.decision === "ask") {
-                    const ok = await opts.confirm(`${call.name} (${v.reason}):\n   ${v.summary}`); // pause and ask the human
-                    if (!ok && !opts.quiet)
-                        console.log(chalk.yellow("  ✋ declined")); // make the refusal visible
-                    content = ok
-                        ? await execute(call, opts) // approved — actually run it
-                        : `[permission] The user declined this action. Ask them how to proceed, or choose a safer alternative.`; // declined — tell the model
-                }
-                else {
-                    content = await execute(call, opts); // allow — run without ceremony
+            // Execute the tool calls. Read-only calls (read_file/search) in a
+            // contiguous run are executed CONCURRENTLY — they cannot conflict and
+            // never need an interactive prompt. Anything that writes or executes runs
+            // ALONE and in order: writes can depend on each other, and we can only ask
+            // the human one question at a time. This greedy batching mirrors how
+            // Claude Code parallelizes safe reads while serializing risky work.
+            let i = 0; // index into out.toolCalls
+            while (i < out.toolCalls.length) {
+                const batch = []; // a run of safe, parallelizable calls
+                while (i < out.toolCalls.length && isReadOnlyTool(out.toolCalls[i].name))
+                    batch.push(out.toolCalls[i++]);
+                if (batch.length) {
+                    // Run the whole read-only batch at once, preserving result order.
+                    const results = await Promise.all(batch.map((c) => runOneCall(c, opts)));
+                    for (const r of results)
+                        messages.push({ role: "tool", tool_call_id: r.id, content: r.content });
+                    continue; // back to the top — the next call is non-read-only
                 }
-                messages.push({ role: "tool", tool_call_id: call.id, content }); // feed the result back, paired by id
+                // A single non-read-only call: gate, maybe ask, execute — all serial.
+                const r = await runOneCall(out.toolCalls[i++], opts);
+                messages.push({ role: "tool", tool_call_id: r.id, content: r.content });
             }
             break; // round complete, move to the next one
         }
     }
-    return { reason: TerminateReason.RoundCap }; // ran out of rounds before a final answer
+    // loop is unbounded — other safeguards (circuit breaker, retry budget, compaction guard) still apply
 }