@nanhara/hara 0.122.3 → 0.122.5

package/dist/agent/loop.js

@@ -8,7 +8,8 @@ import { runHooks } from "../hooks.js";
 import { mapLimit, maxParallel } from "../concurrency.js";
 import { decideCommand, loadPermissionRules } from "../security/permissions.js";
 import { classifyRisk, guardianVeto, guardianEnabled, newBreaker, recordBlock } from "../security/guardian.js";
-import { recordCall } from "./repeat-guard.js";
+import { keyOf, looksFailed, recordCall } from "./repeat-guard.js";
+import { agentMaxRounds, agentRunTimeoutMs, formatAgentDuration } from "./limits.js";
 import { subdirHint } from "../context/subdir-hints.js";
 import { classifyError, failoverAction, errorHint } from "./failover.js";
 import { currentTodos, renderTodos } from "../tools/todo.js";
@@ -135,9 +136,114 @@ function composeSystem(cwd, projectContext, override, memory) {
         (memory ? `\n\n# Memory (durable — facts/decisions/prefs you've saved; use memory_search/get for more)\n${memory}` : "") +
         (skills ? `\n\n# Skills (capabilities you can load — call the \`skill\` tool with the id for full instructions before using one)\n${skills}` : ""));
 }
+const RUN_STOPPED = Symbol("agent-run-stopped");
+const REPEATED_FAILURE_LIMIT = 3;
+function showRunNotice(opts, message, critical = false) {
+    if (opts.quiet)
+        return;
+    if (opts.ctx.ui)
+        opts.ctx.ui.notice(message);
+    else {
+        try {
+            const rendered = process.stderr.isTTY ? (critical ? c.red(message) : c.yellow(message)) : message;
+            process.stderr.write(rendered + "\n");
+        }
+        catch {
+            /* diagnostics must never break lifecycle enforcement */
+        }
+    }
+}
+function warnRun(opts, life) {
+    if (life.disposed || life.warned || life.signal.aborted)
+        return;
+    life.warned = true;
+    showRunNotice(opts, `⚠ agent still running: ${formatAgentDuration(Date.now() - life.startedAt)} elapsed, round ${life.rounds}/${life.maxRounds}; hard stop at ${formatAgentDuration(life.timeoutMs)}.`);
+}
+function createRunLifecycle(opts) {
+    const timeoutMs = agentRunTimeoutMs(opts.timeoutMs);
+    const maxRounds = agentMaxRounds(opts.maxRounds);
+    const timeoutController = new AbortController();
+    const signal = opts.signal ? AbortSignal.any([opts.signal, timeoutController.signal]) : timeoutController.signal;
+    const startedAt = Date.now();
+    const life = {};
+    const timeoutTimer = setTimeout(() => {
+        if (life.disposed || signal.aborted)
+            return;
+        life.timedOut = true;
+        timeoutController.abort(new Error("agent run deadline reached"));
+    }, timeoutMs);
+    // This timer is the hard boundary for a provider/tool Promise that owns no event-loop handles. Keep it
+    // referenced while the run is active; unref would let headless Node exit with the run still unresolved.
+    // Long legitimate work gets an in-band heads-up; a fast active loop gets the same warning at 75% rounds.
+    const warningDelay = Math.min(5 * 60_000, Math.max(250, Math.floor(timeoutMs * 0.8)));
+    const warningTimer = setTimeout(() => warnRun(opts, life), warningDelay);
+    warningTimer.unref?.();
+    let removeStopListener = () => { };
+    const stopPromise = new Promise((resolveStopped) => {
+        const stopped = () => resolveStopped(RUN_STOPPED);
+        removeStopListener = () => signal.removeEventListener("abort", stopped);
+        if (signal.aborted)
+            stopped();
+        else
+            signal.addEventListener("abort", stopped, { once: true });
+    });
+    Object.assign(life, {
+        signal,
+        timeoutController,
+        timeoutTimer,
+        warningTimer,
+        stopPromise,
+        removeStopListener,
+        startedAt,
+        timeoutMs,
+        maxRounds,
+        rounds: 0,
+        timedOut: false,
+        warned: false,
+        limitAnnounced: false,
+        disposed: false,
+        failedCalls: new Map(),
+    });
+    return life;
+}
+function disposeRunLifecycle(life) {
+    life.disposed = true;
+    clearTimeout(life.timeoutTimer);
+    clearTimeout(life.warningTimer);
+    life.removeStopListener();
+}
+function hardStop(opts, life, kind, detail) {
+    const elapsedMs = Date.now() - life.startedAt;
+    const message = kind === "deadline"
+        ? `⛔ agent run stopped: total deadline ${formatAgentDuration(life.timeoutMs)} reached after ${life.rounds} round(s). No further model or tool calls will start. Increase it with \`hara config set runTimeoutMs 45m\` (maximum 2h) only for intentional long work.`
+        : kind === "max_rounds"
+            ? `⛔ agent run stopped: ${life.maxRounds}-round safety limit reached after ${formatAgentDuration(elapsedMs)}. This usually means the model is looping. Increase it with \`hara config set maxAgentRounds <n>\` (maximum 256) only if the extra rounds are intentional.`
+            : `⛔ agent run stopped: the same failing ${detail?.tool ?? "tool"} call repeated ${detail?.count ?? REPEATED_FAILURE_LIMIT} times. Change the approach or fix the reported cause before retrying.`;
+    const event = { kind, message, elapsedMs, rounds: life.rounds, timeoutMs: life.timeoutMs, maxRounds: life.maxRounds };
+    if (!life.limitAnnounced) {
+        life.limitAnnounced = true;
+        showRunNotice(opts, message, true);
+        try {
+            opts.onLimit?.(event);
+        }
+        catch { /* observers cannot weaken the hard stop */ }
+    }
+    return { status: "halted", error: message, stopReason: kind };
+}
 /** Provider-agnostic agentic loop. Mutates `history` in place. */
 export async function runAgent(history, opts) {
+    const life = createRunLifecycle(opts);
+    try {
+        return await runAgentInner(history, opts, life);
+    }
+    finally {
+        disposeRunLifecycle(life);
+    }
+}
+async function runAgentInner(history, opts, life) {
     const { provider, ctx } = opts;
+    const runSignal = life.signal;
+    const toolCtx = { ...ctx, signal: runSignal };
     const permRules = loadPermissionRules(ctx.cwd); // command-level allow/ask/deny policy for the bash tool
     let activeProvider = provider; // may switch to a fallback model on a recoverable error (app-failover)
     let triedFallback = false;
@@ -152,6 +258,21 @@ export async function runAgent(history, opts) {
         }
         return { status: "error", error: msg };
     };
+    const stoppedOutcome = () => life.timedOut
+        ? hardStop(opts, life, "deadline")
+        : interruptedOutcome();
+    const bounded = (promise) => {
+        if (runSignal.aborted)
+            return Promise.resolve(RUN_STOPPED);
+        return Promise.race([promise, life.stopPromise]);
+    };
+    const interactionFailure = (label, error) => {
+        const raw = error instanceof Error ? error.message : String(error ?? "unknown error");
+        const detail = redactSensitiveText(raw).text.trim().slice(0, 500) || "unknown error";
+        const message = `Interactive ${label} failed: ${detail}`;
+        showRunNotice(opts, message, true);
+        return { status: "error", error: message };
+    };
     // Warn at the interaction boundary without echoing the value. Headless/gateway stdout is the response
     // transport, so keep the banner to interactive surfaces; persistence is still redacted everywhere.
     const latestUser = [...history].reverse().find((m) => m.role === "user");
@@ -179,10 +300,32 @@ export async function runAgent(history, opts) {
     // unfinished items exist. Main loop only — quiet (sub-agent) runs share the global list and must not nag.
     let todoIdleRounds = 0;
     for (;;) {
+        // A cancellation that already happened is authoritative: do not start pending-input work, a provider
+        // request, or any later tool round merely to give it an already-aborted signal.
+        if (runSignal.aborted)
+            return stoppedOutcome();
+        if (life.rounds >= life.maxRounds)
+            return hardStop(opts, life, "max_rounds");
+        life.rounds += 1;
+        if (life.rounds >= Math.ceil(life.maxRounds * 0.75))
+            warnRun(opts, life);
         // Type-ahead steering: fold in anything the user submitted while the previous step ran, so it
         // reaches the model on this next call (drained after the last tool round; empty on the 1st pass).
-        if (opts.pendingInput) {
-            for (const m of await opts.pendingInput())
+        if (opts.pendingInput && !runSignal.aborted) {
+            let pending;
+            try {
+                // Defer the callback by one microtask so a synchronous throw follows the same explicit error path
+                // as a rejected Promise instead of escaping runAgent and leaving the caller to guess what failed.
+                pending = await bounded(Promise.resolve().then(() => opts.pendingInput()));
+            }
+            catch (error) {
+                if (runSignal.aborted)
+                    return stoppedOutcome();
+                return interactionFailure("pending-input channel", error);
+            }
+            if (pending === RUN_STOPPED)
+                return stoppedOutcome();
+            for (const m of pending)
                 history.push(m);
         }
         // system-reminder injection: event-driven context queued since the last call (todo staleness today)
@@ -230,17 +373,17 @@ export async function runAgent(history, opts) {
             }, 100);
         }
         // Stall watchdog: any stream event resets the clock; STALL_MS of silence aborts THIS attempt via
-        // its own controller (the user's opts.signal chains into it, so Esc still interrupts). The abort
+        // its own controller (the combined run signal chains into it, so Esc/deadline both interrupt). The abort
         // is then rewritten from "interrupted" to a timeout-class error so failover can take over.
         const STALL_MS = stallMs();
         const attempt = new AbortController();
-        const onUserAbort = () => attempt.abort();
+        const onRunAbort = () => attempt.abort();
         // AbortSignal does not replay an already-fired event to a late listener. A serve shutdown can cancel
         // while provider routing is still refreshing, so inherit that state synchronously before the call.
-        if (opts.signal?.aborted)
+        if (runSignal.aborted)
             attempt.abort();
         else
-            opts.signal?.addEventListener("abort", onUserAbort, { once: true });
+            runSignal.addEventListener("abort", onRunAbort, { once: true });
         let lastEvent = Date.now();
         let stalled = false;
         const stallTimer = setInterval(() => {
@@ -270,92 +413,109 @@ export async function runAgent(history, opts) {
                 else
                     attempt.signal.addEventListener("abort", onAttemptStop, { once: true });
             });
-            const providerTurn = activeProvider.turn({
-                system: composeSystem(ctx.cwd, opts.projectContext, opts.systemOverride, opts.memory),
-                history,
-                tools: specs,
-                // Any stream chunk keeps the connection considered alive — even suppressed reasoning_content, so a
-                // reasoning model thinking for a long while before its first `content` token can't be false-timed-out.
-                onActivity: () => {
-                    if (attempt.signal.aborted)
-                        return;
-                    lastEvent = Date.now();
-                },
-                onText: (d) => {
-                    if (attempt.signal.aborted)
-                        return;
-                    alive();
-                    if (opts.quiet)
-                        return;
-                    if (sink) {
-                        sink.text(d);
-                        return;
-                    }
-                    stopSpin();
-                    flushReasoningTail();
-                    if (md)
-                        md.push(d);
-                    else
-                        out(d);
-                },
-                onReasoning: sink || tty
-                    ? (d) => {
+            // Enter through a microtask so a cancellation/deadline that lands during routing/setup is observed
+            // immediately before the provider side effect starts. Promise.resolve(activeProvider.turn(...)) is
+            // insufficient here: a custom provider can throw synchronously before Promise.resolve ever sees it.
+            const providerTurn = Promise.resolve().then(() => {
+                if (attempt.signal.aborted || runSignal.aborted) {
+                    return { text: "", toolUses: [], stop: "error", errorMsg: "interrupted" };
+                }
+                return activeProvider.turn({
+                    system: composeSystem(ctx.cwd, opts.projectContext, opts.systemOverride, opts.memory),
+                    history,
+                    tools: specs,
+                    // Any stream chunk keeps the connection considered alive — even suppressed reasoning_content, so a
+                    // reasoning model thinking for a long while before its first `content` token can't be false-timed-out.
+                    onActivity: () => {
+                        if (attempt.signal.aborted)
+                            return;
+                        lastEvent = Date.now();
+                    },
+                    onText: (d) => {
                         if (attempt.signal.aborted)
                             return;
                         alive();
                         if (opts.quiet)
                             return;
                         if (sink) {
-                            sink.reasoning(d);
+                            sink.text(d);
                             return;
                         }
-                        // Terminal mode: render reasoning on its own dim lines (prefix `│ ` per line). Each
-                        // line is committed once and never overwritten — so a subsequent spinner tick can't
-                        // clobber it (the old `out(c.dim(d))` bug). Multi-line deltas split cleanly; the
-                        // current line resumes mid-output when the next delta arrives.
                         stopSpin();
-                        const lines = d.split("\n");
-                        for (let i = 0; i < lines.length; i++) {
-                            if (!reasoningOpen) {
-                                out(c.dim("│ "));
-                                reasoningOpen = true;
+                        flushReasoningTail();
+                        if (md)
+                            md.push(d);
+                        else
+                            out(d);
+                    },
+                    onReasoning: sink || tty
+                        ? (d) => {
+                            if (attempt.signal.aborted)
+                                return;
+                            alive();
+                            if (opts.quiet)
+                                return;
+                            if (sink) {
+                                sink.reasoning(d);
+                                return;
                             }
-                            out(c.dim(lines[i]));
-                            if (i < lines.length - 1) {
-                                out("\n");
-                                reasoningOpen = false;
+                            // Terminal mode: render reasoning on its own dim lines (prefix `│ ` per line). Each
+                            // line is committed once and never overwritten — so a subsequent spinner tick can't
+                            // clobber it (the old `out(c.dim(d))` bug). Multi-line deltas split cleanly; the
+                            // current line resumes mid-output when the next delta arrives.
+                            stopSpin();
+                            const lines = d.split("\n");
+                            for (let i = 0; i < lines.length; i++) {
+                                if (!reasoningOpen) {
+                                    out(c.dim("│ "));
+                                    reasoningOpen = true;
+                                }
+                                out(c.dim(lines[i]));
+                                if (i < lines.length - 1) {
+                                    out("\n");
+                                    reasoningOpen = false;
+                                }
                             }
                         }
-                    }
-                    : () => {
-                        if (!attempt.signal.aborted)
-                            alive();
-                    }, // quiet runs still feed the watchdog (reasoning-only stretches are progress)
-                signal: attempt.signal,
+                        : () => {
+                            if (!attempt.signal.aborted)
+                                alive();
+                        }, // quiet runs still feed the watchdog (reasoning-only stretches are progress)
+                    signal: attempt.signal,
+                });
             });
             opts.onProviderTurn?.(providerTurn);
             r = await Promise.race([providerTurn, attemptStopped]);
         }
         catch (error) {
-            if (!opts.signal?.aborted)
-                throw error;
-            r = { text: "", toolUses: [], stop: "error", errorMsg: "interrupted" };
+            // Provider launch/stream failures are turn results, not uncaught loop exceptions. This preserves the
+            // normal classifyError → fallback path for both synchronous throws and rejected provider promises.
+            r = runSignal.aborted
+                ? { text: "", toolUses: [], stop: "error", errorMsg: "interrupted" }
+                : {
+                    text: "",
+                    toolUses: [],
+                    stop: "error",
+                    errorMsg: error instanceof Error ? error.message : String(error),
+                };
         }
         finally {
             clearInterval(stallTimer);
             removeAttemptStop();
-            opts.signal?.removeEventListener("abort", onUserAbort);
+            runSignal.removeEventListener("abort", onRunAbort);
+            // Every exit path (sync throw, rejected promise, watchdog, Esc, deadline) owns the same terminal
+            // teardown. Leaving any of these after the try makes a failed provider strand the spinner/markdown.
+            stopSpin();
+            flushReasoningTail();
+            md?.end();
+            if (!opts.quiet && !sink)
+                out("\n");
         }
         // A watchdog abort surfaces from the provider as "interrupted" — rewrite it to a timeout-class
         // error (unless the USER really did interrupt) so classifyError → failover/fallback handles it.
-        if (stalled && r.stop === "error" && !opts.signal?.aborted) {
+        if (stalled && r.stop === "error" && !runSignal.aborted) {
             r = { ...r, errorMsg: `model stream timeout — no output for ${Math.round(STALL_MS / 1000)}s (stalled connection?)` };
         }
-        stopSpin();
-        flushReasoningTail();
-        md?.end();
-        if (!opts.quiet && !sink)
-            out("\n");
         if (r.usage && opts.stats) {
             opts.stats.input += r.usage.input;
             opts.stats.output += r.usage.output;
@@ -363,8 +523,8 @@ export async function runAgent(history, opts) {
         }
         // A provider may ignore AbortSignal and return a perfectly valid-looking tool_use after cancellation.
         // The original run signal is authoritative: do not append/approve/execute any late response.
-        if (opts.signal?.aborted)
-            return interruptedOutcome();
+        if (runSignal.aborted)
+            return stoppedOutcome();
         history.push({ role: "assistant", text: r.text, toolUses: r.toolUses });
         if (r.stop === "error") {
             const kind = classifyError(r.errorMsg ?? "");
@@ -440,26 +600,64 @@ export async function runAgent(history, opts) {
         // while planning, approving, or executing, so finalize the round with real results for work that already
         // completed and explicit interruption errors for everything else before persisting the session.
         const results = new Array(r.toolUses.length);
-        const finalizeInterruptedToolRound = () => {
+        const finalizeStoppedToolRound = () => {
+            const pendingMessage = life.timedOut
+                ? `Error: agent run deadline ${formatAgentDuration(life.timeoutMs)} reached before this tool call completed.`
+                : "Error: interrupted before this tool call completed.";
+            history.push({
+                role: "tool",
+                results: r.toolUses.map((tu, idx) => results[idx] ?? ({
+                    id: tu.id,
+                    name: tu.name,
+                    content: pendingMessage,
+                    isError: true,
+                })),
+            });
+            return stoppedOutcome();
+        };
+        const finalizeInteractionError = (label, error) => {
+            const outcome = interactionFailure(label, error);
+            const pendingMessage = `Error: ${outcome.error}. This tool call was not executed.`;
             history.push({
                 role: "tool",
                 results: r.toolUses.map((tu, idx) => results[idx] ?? ({
                     id: tu.id,
                     name: tu.name,
-                    content: "Error: interrupted before this tool call completed.",
+                    content: pendingMessage,
                     isError: true,
                 })),
             });
-            return interruptedOutcome();
+            return outcome;
+        };
+        if (runSignal.aborted)
+            return finalizeStoppedToolRound();
+        let repeatHalt = null;
+        const noteCall = (name, input, content, isError = false) => {
+            const note = recordCall(name, input, content, isError, ctx.todoScope);
+            const key = keyOf(name, input);
+            if (isError || looksFailed(content, name)) {
+                const count = (life.failedCalls.get(key) ?? 0) + 1;
+                // This is a *consecutive no-progress* streak, not a lifetime counter for the call. A different
+                // failure is a changed attempt; keep only that new streak instead of letting an old failure
+                // silently accumulate across intervening work.
+                life.failedCalls.clear();
+                life.failedCalls.set(key, count);
+                if (count >= REPEATED_FAILURE_LIMIT && !repeatHalt)
+                    repeatHalt = { tool: name, count };
+            }
+            else {
+                // Any successful action is progress (in particular edit/exec calls that may have fixed the
+                // underlying cause), so a later retry starts a fresh failure streak.
+                life.failedCalls.clear();
+            }
+            return note;
         };
-        if (opts.signal?.aborted)
-            return finalizeInterruptedToolRound();
         const plans = [];
         // Extra (per-run) tools win over the registry so a run-scoped tool can't be shadowed by a global one.
         const resolveTool = (name) => opts.extraTools?.find((t) => t.name === name) ?? getTool(name);
         for (const tu of r.toolUses) {
-            if (opts.signal?.aborted)
-                return finalizeInterruptedToolRound();
+            if (runSignal.aborted)
+                return finalizeStoppedToolRound();
             if (breakerHalt) {
                 // Circuit-breaker halted the run: refuse every remaining call in this round with a clear message
                 // (no hang, no further tools) so the model + user get a definitive stop.
@@ -503,9 +701,18 @@ export async function runAgent(history, opts) {
                 if (risk.level === "high") {
                     const safeRiskReason = redactToolSubprocessOutput(risk.reason);
                     const detail = redactToolSubprocessOutput(String(input.command ?? input.path ?? "").replace(/\s+/g, " ").trim().slice(0, 400));
-                    const verdict = await guardianVeto(opts.guardian.provider, { tool: tu.name, detail, classifierReason: safeRiskReason }, history, { signal: opts.signal });
-                    if (opts.signal?.aborted)
-                        return finalizeInterruptedToolRound();
+                    let verdictResult;
+                    try {
+                        verdictResult = await bounded(Promise.resolve().then(() => guardianVeto(opts.guardian.provider, { tool: tu.name, detail, classifierReason: safeRiskReason }, history, { signal: runSignal })));
+                    }
+                    catch (error) {
+                        if (runSignal.aborted)
+                            return finalizeStoppedToolRound();
+                        return finalizeInteractionError("guardian check", error);
+                    }
+                    if (verdictResult === RUN_STOPPED)
+                        return finalizeStoppedToolRound();
+                    const verdict = verdictResult;
                     if (verdict.decision === "block") {
                         const tripped = recordBlock(breaker); // deterministic circuit-breaker: N blocks → hard stop
                         plans.push({
@@ -526,11 +733,20 @@ export async function runAgent(history, opts) {
                             // (gateway/cron/-p, where `confirm` is auto-yes and there's no real user), abort SAFELY —
                             // never auto-continue past the breaker, and never hang.
                             const interactive = !!ctx.ask;
-                            const cont = interactive
-                                ? await opts.confirm(`${c.red("⛔ guardian circuit-breaker")} — ${breaker.blocks} high-risk actions blocked this turn. Continue anyway?`)
-                                : false;
-                            if (opts.signal?.aborted)
-                                return finalizeInterruptedToolRound();
+                            let contResult;
+                            try {
+                                contResult = interactive
+                                    ? await bounded(Promise.resolve().then(() => opts.confirm(`${c.red("⛔ guardian circuit-breaker")} — ${breaker.blocks} high-risk actions blocked this turn. Continue anyway?`, runSignal)))
+                                    : false;
+                            }
+                            catch (error) {
+                                if (runSignal.aborted)
+                                    return finalizeStoppedToolRound();
+                                return finalizeInteractionError("guardian confirmation", error);
+                            }
+                            if (contResult === RUN_STOPPED)
+                                return finalizeStoppedToolRound();
+                            const cont = contResult;
                             if (cont === false) {
                                 breakerHalt = true;
                             }
@@ -545,9 +761,18 @@ export async function runAgent(history, opts) {
             }
             const shouldConfirm = alwaysGate || (cmdDecision !== "allow" && needsConfirm(tool.kind, opts.approval) && !opts.autoApprove?.has(tu.name));
             if (shouldConfirm) {
-                const reply = await opts.confirm(`${c.yellow("⚠")}  ${c.bold(tu.name)} ${c.dim(preview)} — run?`);
-                if (opts.signal?.aborted)
-                    return finalizeInterruptedToolRound();
+                let replyResult;
+                try {
+                    replyResult = await bounded(Promise.resolve().then(() => opts.confirm(`${c.yellow("⚠")}  ${c.bold(tu.name)} ${c.dim(preview)} — run?`, runSignal)));
+                }
+                catch (error) {
+                    if (runSignal.aborted)
+                        return finalizeStoppedToolRound();
+                    return finalizeInteractionError("approval prompt", error);
+                }
+                if (replyResult === RUN_STOPPED)
+                    return finalizeStoppedToolRound();
+                const reply = replyResult;
                 if (reply === false) {
                     plans.push({ tu, tool, denied: "User denied this action." });
                     continue;
@@ -565,13 +790,22 @@ export async function runAgent(history, opts) {
             }
         }
         // Execute: read-only tools run concurrently; edit/exec run alone, in order.
-        if (opts.signal?.aborted)
-            return finalizeInterruptedToolRound();
+        if (runSignal.aborted)
+            return finalizeStoppedToolRound();
         const runOne = async (idx, p) => {
-            if (opts.signal?.aborted)
+            if (runSignal.aborted)
+                return;
+            if (repeatHalt) {
+                results[idx] = { id: p.tu.id, name: p.tu.name, content: "Error: not executed because the repeated-failure circuit-breaker stopped this run.", isError: true };
                 return;
+            }
             if (p.denied !== undefined) {
-                results[idx] = { id: p.tu.id, name: p.tu.name, content: p.denied, isError: true };
+                results[idx] = {
+                    id: p.tu.id,
+                    name: p.tu.name,
+                    content: p.denied + noteCall(p.tu.name, p.tu.input, p.denied, true),
+                    isError: true,
+                };
                 return;
             }
             activity.inc();
@@ -583,42 +817,59 @@ export async function runAgent(history, opts) {
                 if (missing.length) {
                     const msg = `Error: tool call NOT executed — missing required parameter${missing.length > 1 ? "s" : ""}: ` +
                         `${missing.join(", ")}. Send the call again with ALL required parameters (${(p.tool.input_schema.required ?? []).join(", ")}) present and complete.`;
-                    results[idx] = { id: p.tu.id, name: p.tu.name, content: msg + recordCall(p.tu.name, p.tu.input, msg, true, ctx.todoScope), isError: true };
+                    results[idx] = { id: p.tu.id, name: p.tu.name, content: msg + noteCall(p.tu.name, p.tu.input, msg, true), isError: true };
                     return;
                 }
-                if (opts.signal?.aborted)
+                if (runSignal.aborted)
                     return;
                 const pre = opts.hooks === false
                     ? { block: false, message: "" }
-                    : runHooks("PreToolUse", p.tu.name, p.tu.input, ctx.cwd); // a hook may veto the call
+                    : await runHooks("PreToolUse", p.tu.name, p.tu.input, ctx.cwd, 30_000, runSignal); // a hook may veto the call
                 if (pre.block) {
-                    results[idx] = { id: p.tu.id, name: p.tu.name, content: pre.message, isError: true };
+                    results[idx] = { id: p.tu.id, name: p.tu.name, content: pre.message + noteCall(p.tu.name, p.tu.input, pre.message, true), isError: true };
                     return;
                 }
-                if (opts.signal?.aborted)
+                if (runSignal.aborted)
                     return;
                 // Track the MAIN conversation's working files for post-compaction restore (quiet fan-out
                 // sub-agents read broadly — their files aren't "what the user was working on").
                 if (!opts.quiet && FILE_TOUCH_TOOLS.has(p.tu.name) && typeof p.tu.input?.path === "string") {
                     recordTouch(resolvePath(ctx.cwd, String(p.tu.input.path)), ctx.todoScope);
                 }
-                const res = await p.tool.run(p.tu.input, ctx);
+                // If a tool completes a side effect and aborts the parent synchronously, preserve that real result.
+                // A plain Promise.race can let the abort branch win the same microtask turn and falsely report the
+                // completed action as not run. Non-cooperative pending tools still lose to the hard stop immediately.
+                let settled;
+                const observedTool = p.tool.run(p.tu.input, toolCtx).then((value) => { settled = { ok: true, value }; return value; }, (error) => { settled = { ok: false, error }; throw error; });
+                try {
+                    opts.onToolRun?.(observedTool, { name: p.tool.name, kind: p.tool.kind });
+                }
+                catch { /* observers cannot affect execution */ }
+                const toolResult = await bounded(observedTool);
+                if (toolResult === RUN_STOPPED) {
+                    await Promise.resolve(); // allow an already-completed async tool's fulfillment handler to publish
+                    if (!settled)
+                        return;
+                    if (!settled.ok)
+                        throw settled.error;
+                }
+                const res = toolResult === RUN_STOPPED ? settled.value : toolResult;
                 // append any not-yet-seen subdirectory AGENTS.md/CLAUDE.md this call touched (monorepo-local conventions)
                 // + the repeat-guard's anti-spinning note when this exact call keeps failing (repeat-guard.ts)
-                results[idx] = { id: p.tu.id, name: p.tu.name, content: res + subdirHint(p.tu.input, ctx.cwd) + recordCall(p.tu.name, p.tu.input, res, false, ctx.todoScope) };
+                results[idx] = { id: p.tu.id, name: p.tu.name, content: res + subdirHint(p.tu.input, ctx.cwd) + noteCall(p.tu.name, p.tu.input, res) };
                 // The tool may have completed a side effect and then triggered/observed cancellation. Preserve its
                 // actual result in the closing tool round, but do not run any post hook or later tool afterward.
-                if (opts.signal?.aborted)
+                if (runSignal.aborted)
                     return;
                 if (opts.hooks !== false) {
-                    runHooks("PostToolUse", p.tu.name, { input: p.tu.input, result: res }, ctx.cwd); // observe-only
+                    await runHooks("PostToolUse", p.tu.name, { input: p.tu.input, result: res }, ctx.cwd, 30_000, runSignal); // observe-only
                 }
             }
             catch (e) {
-                const msg = `Error: ${e.message}`;
-                results[idx] = { id: p.tu.id, name: p.tu.name, content: msg + recordCall(p.tu.name, p.tu.input, msg, true, ctx.todoScope), isError: true };
-                if (opts.signal?.aborted)
+                if (runSignal.aborted)
                     return;
+                const msg = `Error: ${e.message}`;
+                results[idx] = { id: p.tu.id, name: p.tu.name, content: msg + noteCall(p.tu.name, p.tu.input, msg, true), isError: true };
             }
             finally {
                 activity.dec();
@@ -633,25 +884,29 @@ export async function runAgent(history, opts) {
             await mapLimit(idx, maxParallel(), (i) => runOne(i, plans[i])); // bounded fan-out (e.g. 20 parallel agents → 8 at a time)
         };
         for (let i = 0; i < plans.length; i++) {
-            if (opts.signal?.aborted)
-                return finalizeInterruptedToolRound();
+            if (runSignal.aborted)
+                return finalizeStoppedToolRound();
             const p = plans[i];
-            if (p.denied === undefined && p.tool?.kind === "read") {
+            // ask_user is interaction-safe but not parallel-safe: the TUI deliberately owns one prompt slot.
+            // Flush other reads and ask sequentially so two questions cannot overwrite each other and hang.
+            if (p.denied === undefined && p.tool?.kind === "read" && p.tool.name !== "ask_user") {
                 batch.push(i); // safe → accumulate to run concurrently
             }
             else {
                 await flush(); // flush pending reads before an edit/exec
-                if (opts.signal?.aborted)
-                    return finalizeInterruptedToolRound();
+                if (runSignal.aborted)
+                    return finalizeStoppedToolRound();
                 await runOne(i, p);
-                if (opts.signal?.aborted)
-                    return finalizeInterruptedToolRound();
+                if (runSignal.aborted)
+                    return finalizeStoppedToolRound();
             }
         }
         await flush();
-        if (opts.signal?.aborted)
-            return finalizeInterruptedToolRound();
+        if (runSignal.aborted)
+            return finalizeStoppedToolRound();
         history.push({ role: "tool", results });
+        if (repeatHalt)
+            return hardStop(opts, life, "repeat_loop", repeatHalt);
         // Synthesis nudge (CC's KN5, hara-shaped): a round that fanned out to several parallel agents just
         // produced N independent reports — remind the model to merge/reconcile them before acting, instead
         // of anchoring on whichever report happens to sit last in context.