@cjhyy/code-shell-core 0.5.0-rc.1 → 0.6.0-rc.1

package/dist/engine/turn-loop.js

@@ -5,12 +5,36 @@
  * pre_check → model_call → post_check → tool_exec → context_mgmt → hook_notify → next turn
  */
 import { initialTurnState, newTurnId } from "./turn-state.js";
+import { formatFriendlyError } from "./friendly-error.js";
 import { wrapHookMessages } from "../hooks/inject.js";
 import { ContextLimitError } from "../exceptions.js";
 import { logger } from "../logging/logger.js";
 import { checkTokenBudget, createBudgetTracker } from "./token-budget.js";
 import { StreamingToolQueue } from "./streaming-tool-queue.js";
 import { estimateTokens } from "../context/compaction.js";
+import { isTruncatedStop } from "../llm/stop-reason.js";
+import { isAbortError } from "../llm/client-base.js";
+import { crossedReactiveThreshold } from "./reactive-threshold.js";
+import { COMPLETE_GOAL_TOOL_NAME } from "../tool-system/builtin/complete-goal.js";
+import { CANCEL_GOAL_TOOL_NAME } from "../tool-system/builtin/cancel-goal.js";
+import { createGoalBudgetTracker, recordGoalUsage, goalBudgetExceeded, applyGoalExtension, limitProximity, GOAL_DEFAULT_MAX_STOP_BLOCKS, } from "./goal.js";
+/**
+ * 把一个 ToolResult 映射成发给 LLM 的 tool_result ContentBlock。
+ * 有 contentBlocks(view_image 的图片块)就原样用作 content;否则
+ * 用文本(成功用 result,失败用 "Error: ...")。抽成纯函数以便单测。
+ */
+export function toolResultToBlock(result) {
+    const block = {
+        type: "tool_result",
+        tool_use_id: result.id,
+        content: result.error
+            ? `Error: ${result.error}`
+            : result.contentBlocks ?? (result.result ?? "(no output)"),
+    };
+    if (result.isError || result.error)
+        block.is_error = true;
+    return block;
+}
 export class TurnLoop {
     deps;
     config;
@@ -26,7 +50,99 @@ export class TurnLoop {
     currentTurnLog = logger;
     /** Last emitted ctx token estimate; used to skip no-op usage_update events. */
     lastCtxEmit = -1;
-    constructor(deps, config) {
+    /**
+     * Consecutive on_stop blocks (Goal mode kept the agent going). Reset to 0
+     * on any unblocked completion. When it reaches config.maxStopBlocks the
+     * loop forces a stop so a stuck goal can't loop forever.
+     */
+    stopBlockCount = 0;
+    /**
+     * Run-scoped goal budget tracker (Goal mode). Hoisted to an instance field
+     * (not a run() local) so extend() can bump its budgets mid-run. Null when no
+     * goal or between runs.
+     */
+    goalTracker = null;
+    /**
+     * Whether an approaching_limit marker was already emitted for the current
+     * ceiling. Reset when the run advances past the moment (a fresh extension, or
+     * the goal completing) so the next approach re-announces. Prevents the marker
+     * being re-emitted every turn while still within the approach threshold.
+     */
+    approachAnnounced = false;
+    /**
+     * Extend the in-flight run's limits (TODO 3.1 — 运行中续轮/加预算). Mutates
+     * the maxTurns ceiling, the maxStopBlocks cap, and/or the live goal budgets;
+     * the loop re-reads all of them each turn so the change takes effect on the
+     * next iteration. No-op for fields not supplied. Returns the resulting
+     * effective limits.
+     */
+    extend(opts) {
+        const elapsedMs = this.goalTracker ? Date.now() - this.goalTracker.startedAtMs : 0;
+        const next = applyGoalExtension(this.config.maxTurns, this.goalTracker?.goal, this.goalTracker?.tokensUsed ?? 0, elapsedMs, opts);
+        this.config = { ...this.config, maxTurns: next.maxTurns };
+        if (this.goalTracker) {
+            // Replace the goal object rather than mutating its fields: the tracker's
+            // goal may be a shared/frozen reference, and goalBudgetExceeded reads
+            // tracker.goal.{tokenBudget,timeBudgetMs} live, so a fresh object with the
+            // new caps takes effect on the next turn either way.
+            this.goalTracker.goal = {
+                ...this.goalTracker.goal,
+                tokenBudget: next.tokenBudget,
+                timeBudgetMs: next.timeBudgetMs,
+            };
+        }
+        // Raise the consecutive-stop-block cap — for a re-blocked goal this is the
+        // limit that actually bites, so an extend that only bumped maxTurns/budgets
+        // couldn't keep it going. Resolve the current cap the same way the loop does.
+        const curCap = this.config.maxStopBlocks ?? GOAL_DEFAULT_MAX_STOP_BLOCKS;
+        const nextCap = typeof opts.addStopBlocks === "number" && opts.addStopBlocks > 0
+            ? curCap + Math.floor(opts.addStopBlocks)
+            : curCap;
+        this.config = { ...this.config, maxStopBlocks: nextCap };
+        // ANY extension resets the consecutive stop-block streak: the user just
+        // asked to keep going, so a goal that was repeatedly re-blocked shouldn't be
+        // immediately re-capped. (Previously only addTurns reset it, leaving a
+        // budget-only extension unable to un-stick a capped goal.)
+        const extended = (opts.addTurns ?? 0) > 0 ||
+            (opts.addStopBlocks ?? 0) > 0 ||
+            (opts.addTokenBudget ?? 0) > 0 ||
+            (opts.addTimeBudgetMs ?? 0) > 0;
+        if (extended) {
+            this.stopBlockCount = 0;
+            // Let the next approach re-announce against the raised ceilings.
+            this.approachAnnounced = false;
+        }
+        return { ...next, maxStopBlocks: nextCap };
+    }
+    /**
+     * Goal mode only: if the run is nearing EITHER stop ceiling (maxTurns or
+     * maxStopBlocks) and we haven't announced it yet, emit one approaching_limit
+     * marker so the UI can offer a "再续" button while the run is still live.
+     * Watches both limits because a re-blocked goal hits the stop-block cap long
+     * before maxTurns. Idempotent within an approach window via approachAnnounced.
+     */
+    maybeAnnounceApproachingLimit() {
+        if (!this.config.goal || this.approachAnnounced)
+            return;
+        const cap = this.config.maxStopBlocks ?? GOAL_DEFAULT_MAX_STOP_BLOCKS;
+        const prox = limitProximity(this.turnCount, this.config.maxTurns, this.stopBlockCount, cap);
+        if (!prox.approaching)
+            return;
+        this.approachAnnounced = true;
+        this.config.onStream?.({
+            type: "goal_progress",
+            status: "approaching_limit",
+            round: this.stopBlockCount,
+            turnsRemaining: prox.turnsRemaining,
+            stopBlocksRemaining: prox.stopBlocksRemaining,
+            nearest: prox.nearest,
+        });
+    }
+    constructor(deps, 
+    // Not readonly: extend() bumps maxTurns mid-run (TODO 3.1), and the
+    // constructor below rewrites onStream. The loop reads config fields fresh
+    // each turn so mutations take effect on the next iteration.
+    config) {
         this.deps = deps;
         this.config = config;
         // Wrap onStream so a single throwing handler can't silently break
@@ -67,11 +183,29 @@ export class TurnLoop {
      * `decision` / `stop`. Use this instead of `deps.hooks.emit` directly so
      * every emit carries the same context envelope.
      */
+    /**
+     * Persist a turn_stopped marker on a user Stop so a resume can rebuild the
+     * renderer's "你在 Ns 后停止了" line (the in-memory turn_end is lost on reload,
+     * which makes the interrupted turn fold behind the process-card header).
+     * Skipped for sub-agents — their signal.aborted is usually a parent abort,
+     * not a user Stop, and sub-agent turns aren't shown as interruptible. The
+     * underlying append is idempotent, so calling this at several abort returns
+     * for one Stop still writes a single marker.
+     */
+    markStopped() {
+        if (this.deps.isSubAgent === true)
+            return;
+        this.deps.transcript.appendTurnStopped();
+    }
     async emitHook(event, data = {}) {
         return this.deps.hooks.emit(event, {
             ...data,
             isSubAgent: this.deps.isSubAgent === true,
             sessionId: this.deps.sessionId,
+            // The run's abort signal, so handlers that make their own LLM calls
+            // (e.g. the Goal stop-judge) can be cut short when the user hits Stop
+            // mid-call instead of blocking until the sub-call returns.
+            signal: this.config.signal,
         });
     }
     /**
@@ -104,9 +238,10 @@ export class TurnLoop {
         this.lastCtxEmit = ctx;
         this.config.onStream({ type: "usage_update", promptTokens: ctx });
     }
-    emitCtxFromUsage(promptTokens, messages) {
+    emitCtxFromUsage(usage, messages) {
         if (!this.config.onStream)
             return;
+        const promptTokens = usage.promptTokens;
         // Reverse-derive overhead from this authoritative reading so the next
         // estimate-based emit (post-tool-result) is calibrated.
         const msgsEstimate = estimateTokens(messages);
@@ -122,7 +257,21 @@ export class TurnLoop {
         if (promptTokens === this.lastCtxEmit)
             return;
         this.lastCtxEmit = promptTokens;
-        this.config.onStream({ type: "usage_update", promptTokens });
+        // Forward the provider's cache counts so the UI can show a hit rate. Only
+        // attach fields the provider actually reported — a spread keeps them off
+        // the event entirely when undefined, so the renderer can tell "no cache
+        // info this turn" from "0 cached". Estimate-path emits don't call this and
+        // so carry no cache fields (correct: an estimate has no cache reading).
+        this.config.onStream({
+            type: "usage_update",
+            promptTokens,
+            ...(usage.cacheReadTokens !== undefined
+                ? { cacheReadTokens: usage.cacheReadTokens }
+                : {}),
+            ...(usage.cacheCreationTokens !== undefined
+                ? { cacheCreationTokens: usage.cacheCreationTokens }
+                : {}),
+        });
     }
     /**
      * Run the multi-turn agent loop until completion.
@@ -131,298 +280,596 @@ export class TurnLoop {
         let messages = [...initialMessages];
         let finalText = "";
         const budgetTracker = createBudgetTracker();
-        while (this.turnCount < this.config.maxTurns) {
-            this.turnCount++;
-            const state = initialTurnState(this.turnCount);
-            // Per-turn correlation ID. Every log written through `tlog` (or any
-            // child derived from it) is stamped with `turn` + `turnId`, so
-            // `jq 'select(.turnId == "...")'` reconstructs one turn's timeline.
-            // Span is *not* used for the loop itself because there are 6+ early
-            // returns; instead, each return-causing branch logs its own terminal
-            // event (model_error, completed, etc.).
-            const turnId = newTurnId();
-            const tlog = logger.child({ turn: this.turnCount, turnId });
-            this.currentTurnLog = tlog;
-            const turnStartedAt = Date.now();
-            tlog.info("turn.start", { cat: "turn", messageCount: messages.length });
-            // Tag downstream tool-exec / permission lines with this turn's IDs.
-            this.deps.toolExecutor.setLogger(tlog);
-            this.config.onStream?.({ type: "stream_request_start", turnNumber: this.turnCount });
-            const turnStartHook = await this.emitHook("on_turn_start", {
-                turnNumber: this.turnCount,
-            });
-            const turnStartInjection = wrapHookMessages(turnStartHook.messages);
-            if (turnStartInjection) {
-                messages.push(turnStartInjection);
-            }
-            // Approaching max turns: inject a warning so the model can wrap up
-            const turnsRemaining = this.config.maxTurns - this.turnCount;
-            if (turnsRemaining === 2) {
-                messages.push({
-                    role: "user",
-                    content: "<system-reminder>Warning: you have only 2 turns remaining before the turn limit is reached. " +
-                        "Start wrapping up your work and prepare a summary of what you've accomplished and what remains to be done.</system-reminder>",
-                });
-            }
-            else if (turnsRemaining === 0) {
-                messages.push({
-                    role: "user",
-                    content: "<system-reminder>This is your LAST turn. You MUST respond with a final text summary now. " +
-                        "Do NOT call any tools. Summarize what you have accomplished and list any remaining work.</system-reminder>",
-                });
-            }
-            // Pre-check: context management (async — may trigger LLM summarization)
-            messages = await this.deps.contextManager.manageAsync(messages);
-            // No pre-llm ctx emit here: the messages-only estimate would be ~16k
-            // smaller than the real prompt (system + tools not included), making
-            // the bar visibly drop on every submit. Post-llm/post-tool-result
-            // events carry an accurate value; if compaction shrank the array, the
-            // dedicated context_compact event has already informed the UI.
-            // post_compact hook: ContextManager just finished a manage() pass.
-            // If any non-micro tier fired, give handlers a chance to inject a
-            // <system-reminder> ("context was compacted — recall earlier
-            // decisions from the transcript") into THIS turn before the model
-            // call. Microcompact is lossless (just clearing redundant
-            // tool_results) so we suppress hook emits for it to keep token
-            // overhead down.
-            const pending = this.deps.consumePendingCompactInfo?.();
-            if (pending && pending.strategy !== "micro") {
-                const compactHook = await this.emitHook("post_compact", {
-                    strategy: pending.strategy,
-                    beforeTokens: pending.before,
-                    afterTokens: pending.after,
+        // Goal-mode run-scoped budget tracker (P0). Null when no goal. Stamps a
+        // wall-clock start now and accumulates prompt+completion tokens across
+        // every turn; the guardrail below force-stops the run once any configured
+        // budget is blown — the unattended-safety backstop.
+        this.goalTracker = this.config.goal
+            ? createGoalBudgetTracker(this.config.goal, Date.now())
+            : null;
+        const goalTracker = this.goalTracker;
+        // Fresh run: re-arm the approaching-limit announcement.
+        this.approachAnnounced = false;
+        // run() must never reject: the engine's post-run bookkeeping (saveState
+        // with the terminal reason, on_session_end hook) runs AFTER this call and
+        // outside the engine's try, so a throw here would leave the session
+        // frozen at status "active" on disk. Per-turn errors are already turned
+        // into return-reasons by callModelWithFallback; this outer guard catches
+        // throws from the surrounding scaffolding (contextManager.manageAsync,
+        // hook emits, guards) and surfaces them as a model_error result.
+        try {
+            while (this.turnCount < this.config.maxTurns) {
+                this.turnCount++;
+                // Abort fast-path: bail at the loop TOP before doing any per-turn work.
+                // Without this, an aborted child (parent abort, or the 30min per-call
+                // registry timeout) would run a full contextManager.manageAsync (itself
+                // an LLM summarization call) + model call + tool batch before the
+                // post-model check at the bottom of the loop noticed — exactly the
+                // sub-agent leak where a synchronous child kept burning turns/tokens for
+                // minutes after the parent Agent call already returned. The model call's
+                // own signal check only fires AFTER the call resolves; this guards the
+                // boundary between turns. (Mirrors Claude Code's query.ts, where the
+                // aborted check short-circuits before re-entering the streaming loop.)
+                if (this.config.signal?.aborted) {
+                    this.markStopped();
+                    return { text: finalText, reason: "aborted_streaming", messages };
+                }
+                // Step-gap steering: messages the host queued via Engine.enqueueSteer
+                // while the previous step was running. Splice them in as user messages so
+                // they join THIS step's request — no abort, no lost in-flight work. Same
+                // loop-top user-push pattern as turnStartInjection / turn-limit warnings
+                // below. Push to transcript too so they persist + survive resume.
+                const steered = this.deps.consumeSteer?.() ?? [];
+                for (const { id, text } of steered) {
+                    if (!text)
+                        continue;
+                    messages.push({ role: "user", content: text });
+                    this.deps.transcript.appendMessage("user", text);
+                    this.config.onStream?.({ type: "steer_injected", text, id });
+                }
+                const state = initialTurnState(this.turnCount);
+                // Per-turn correlation ID. Every log written through `tlog` (or any
+                // child derived from it) is stamped with `turn` + `turnId`, so
+                // `jq 'select(.turnId == "...")'` reconstructs one turn's timeline.
+                // Span is *not* used for the loop itself because there are 6+ early
+                // returns; instead, each return-causing branch logs its own terminal
+                // event (model_error, completed, etc.).
+                const turnId = newTurnId();
+                const tlog = logger.child({ turn: this.turnCount, turnId });
+                this.currentTurnLog = tlog;
+                const turnStartedAt = Date.now();
+                tlog.info("turn.start", { cat: "turn", messageCount: messages.length });
+                // Tag downstream tool-exec / permission lines with this turn's IDs.
+                this.deps.toolExecutor.setLogger(tlog);
+                this.config.onStream?.({ type: "stream_request_start", turnNumber: this.turnCount });
+                const turnStartHook = await this.emitHook("on_turn_start", {
+                    turnNumber: this.turnCount,
                 });
-                const compactInjection = wrapHookMessages(compactHook.messages);
-                if (compactInjection) {
-                    messages.push(compactInjection);
+                const turnStartInjection = wrapHookMessages(turnStartHook.messages);
+                if (turnStartInjection) {
+                    messages.push(turnStartInjection);
                 }
-            }
-            // Model call (with streaming fallback and max_output_tokens continuation)
-            // Track tool IDs streamed during this turn to avoid duplicate UI events
-            this.streamedToolIds.clear();
-            // Streaming tool queue: start concurrency-safe tools during streaming
-            const streamingQueue = new StreamingToolQueue(this.deps.toolExecutor);
-            let response;
-            try {
-                response = await this.callModelWithFallback(messages);
-            }
-            catch (err) {
-                if (err instanceof ContextLimitError) {
-                    // Progressive recovery: drop oldest API rounds, up to 3 retries
-                    const { dropOldestRounds } = await import("../context/compaction.js");
-                    let recovered = false;
-                    for (let retry = 1; retry <= 3; retry++) {
-                        tlog.warn("turn.ptl_recovery", { cat: "turn", retry, roundsToDrop: retry });
-                        messages = dropOldestRounds(messages, retry);
+                // Approaching max turns: inject a warning so the model can wrap up.
+                // (Model-facing only — the user-facing "再续" marker is handled by
+                // maybeAnnounceApproachingLimit below, which also watches the stop-block
+                // cap, the limit a re-blocked goal actually hits first.)
+                const turnsRemaining = this.config.maxTurns - this.turnCount;
+                if (turnsRemaining === 2) {
+                    messages.push({
+                        role: "user",
+                        content: "<system-reminder>Warning: you have only 2 turns remaining before the turn limit is reached. " +
+                            "Start wrapping up your work and prepare a summary of what you've accomplished and what remains to be done.</system-reminder>",
+                    });
+                }
+                else if (turnsRemaining === 1) {
+                    messages.push({
+                        role: "user",
+                        content: "<system-reminder>Warning: you have only 1 turn remaining before the turn limit is reached. " +
+                            "Wrap up your work now — your next turn will be your last.</system-reminder>",
+                    });
+                }
+                else if (turnsRemaining === 0) {
+                    messages.push({
+                        role: "user",
+                        content: "<system-reminder>This is your LAST turn. You MUST respond with a final text summary now. " +
+                            "Do NOT call any tools. Summarize what you have accomplished and list any remaining work.</system-reminder>",
+                    });
+                }
+                // Goal mode: announce once when nearing EITHER stop ceiling (turns or
+                // stop-blocks) so the UI can offer a "再续" button while still live.
+                this.maybeAnnounceApproachingLimit();
+                // Pre-check: context management (async — may trigger LLM summarization)
+                messages = await this.deps.contextManager.manageAsync(messages);
+                // manageAsync can itself issue an LLM summarization call lasting several
+                // seconds; if the signal aborted during it, stop here rather than
+                // proceeding into the (expensive) main model call. Belt to the loop-top
+                // brace: this catches an abort that landed *inside* context management.
+                if (this.config.signal?.aborted) {
+                    this.markStopped();
+                    return { text: finalText, reason: "aborted_streaming", messages };
+                }
+                // No pre-llm ctx emit here: the messages-only estimate would be ~16k
+                // smaller than the real prompt (system + tools not included), making
+                // the bar visibly drop on every submit. Post-llm/post-tool-result
+                // events carry an accurate value; if compaction shrank the array, the
+                // dedicated context_compact event has already informed the UI.
+                // post_compact hook: ContextManager just finished a manage() pass.
+                // If any non-micro tier fired, give handlers a chance to inject a
+                // <system-reminder> ("context was compacted — recall earlier
+                // decisions from the transcript") into THIS turn before the model
+                // call. Microcompact is lossless (just clearing redundant
+                // tool_results) so we suppress hook emits for it to keep token
+                // overhead down.
+                const pending = this.deps.consumePendingCompactInfo?.();
+                if (pending && pending.strategy !== "micro") {
+                    const compactHook = await this.emitHook("post_compact", {
+                        strategy: pending.strategy,
+                        beforeTokens: pending.before,
+                        afterTokens: pending.after,
+                    });
+                    const compactInjection = wrapHookMessages(compactHook.messages);
+                    if (compactInjection) {
+                        messages.push(compactInjection);
+                    }
+                }
+                // Model call (with streaming fallback and max_output_tokens continuation)
+                // Track tool IDs streamed during this turn to avoid duplicate UI events
+                this.streamedToolIds.clear();
+                // Streaming tool queue: start concurrency-safe tools during streaming
+                const streamingQueue = new StreamingToolQueue(this.deps.toolExecutor);
+                let response;
+                try {
+                    response = await this.callModelWithFallback(messages);
+                }
+                catch (err) {
+                    if (err instanceof ContextLimitError) {
+                        // Progressive recovery: drop oldest API rounds, up to 3 retries
+                        const { dropOldestRounds } = await import("../context/compaction.js");
+                        let recovered = false;
+                        for (let retry = 1; retry <= 3; retry++) {
+                            tlog.warn("turn.ptl_recovery", { cat: "turn", retry, roundsToDrop: retry });
+                            messages = dropOldestRounds(messages, retry);
+                            try {
+                                response = await this.callModelWithFallback(messages);
+                                recovered = true;
+                                break;
+                            }
+                            catch (retryErr) {
+                                if (!(retryErr instanceof ContextLimitError)) {
+                                    this.config.onStream?.({ type: "error", error: formatFriendlyError(retryErr) });
+                                    return { text: finalText, reason: "model_error", messages };
+                                }
+                            }
+                        }
+                        if (!recovered) {
+                            this.patchOrphanedToolUses(messages);
+                            this.config.onStream?.({
+                                type: "error",
+                                error: "Context limit exceeded after 3 recovery attempts",
+                            });
+                            return { text: finalText, reason: "prompt_too_long", messages };
+                        }
+                    }
+                    else if (isAbortError(err) || this.config.signal?.aborted) {
+                        // User pressed Stop: the in-flight model call rejected with an
+                        // AbortError. This is NOT a failure — the UI already shows the
+                        // "你在 Ns 后停止了" line, so emitting an error event would stack a
+                        // spurious red "Error:" block on top of an intentional stop.
+                        // Persist a turn_stopped marker so a resume can rebuild that line
+                        // (the renderer's turn_end is in-memory only; without this the
+                        // interrupted turn folds behind the process-card header on reload).
+                        this.patchOrphanedToolUses(messages);
+                        this.markStopped();
+                        return { text: finalText, reason: "aborted_streaming", messages };
+                    }
+                    else {
+                        this.patchOrphanedToolUses(messages);
+                        this.config.onStream?.({ type: "error", error: formatFriendlyError(err) });
+                        return { text: finalText, reason: "model_error", messages };
+                    }
+                }
+                // UI ctx bar: prefer the provider's authoritative promptTokens.
+                if (response.usage?.promptTokens !== undefined) {
+                    this.emitCtxFromUsage(response.usage, messages);
+                }
+                // Feed actual token usage back to the context manager so subsequent
+                // compaction decisions use hybrid (actual + delta) estimation rather than
+                // pure heuristics. Without this the manager falls back to char/4 estimates.
+                if (response.usage?.promptTokens !== undefined) {
+                    this.deps.contextManager.recordActualUsage(response.usage.promptTokens, messages.length);
+                }
+                // Truncation that cut off a TOOL CALL: the model overflowed
+                // max_output_tokens mid tool-call, so the arg JSON is incomplete (e.g. a
+                // Write whose `content` was clipped, leaving file_path unset). Executing
+                // it raised a misleading "Missing required parameter: file_path". Instead,
+                // tell the model its output was truncated and let the next turn retry —
+                // bounded by the outer maxTurns loop.
+                if (isTruncatedStop(response.stopReason) && response.toolCalls.length > 0) {
+                    tlog.info("turn.truncated_tool_call", {
+                        cat: "turn",
+                        toolCount: response.toolCalls.length,
+                    });
+                    if (response.text) {
+                        messages.push({ role: "assistant", content: response.text });
+                    }
+                    messages.push({
+                        role: "user",
+                        content: "<system-reminder>Your previous response was truncated by the max output token limit before the tool call finished, so its arguments are incomplete. Do not assume it ran. Either retry with a smaller/more focused tool call (e.g. write the file in sections via Edit), or raise this model's maxOutputTokens.</system-reminder>",
+                    });
+                    continue;
+                }
+                // Handle max_output_tokens: if response was truncated, do continuation
+                // (up to 3 times). Truncation is reported as finish_reason "length"
+                // (OpenAI) or stop_reason "max_tokens" (Anthropic) — isTruncatedStop
+                // accepts both, so the OpenAI streaming path triggers continuation too.
+                if (isTruncatedStop(response.stopReason) &&
+                    response.toolCalls.length === 0 &&
+                    response.text) {
+                    let combinedText = response.text;
+                    for (let retry = 0; retry < 3; retry++) {
+                        // Don't fire another continuation call if the user cancelled — without
+                        // this an abort during a truncated response could still issue up to 3
+                        // more model calls, emitting text after Stop.
+                        if (this.config.signal?.aborted)
+                            break;
+                        tlog.info("turn.max_tokens_continuation", { cat: "turn", retry: retry + 1 });
+                        const contMessages = [
+                            ...messages,
+                            { role: "assistant", content: combinedText },
+                            {
+                                role: "user",
+                                content: "<system-reminder>Your previous response was truncated due to length. Please continue from where you left off.</system-reminder>",
+                            },
+                        ];
                         try {
-                            response = await this.callModelWithFallback(messages);
-                            recovered = true;
+                            const contResponse = await this.deps.model.call(this.deps.systemPrompt, contMessages, this.deps.tools, this.config.onStream, this.config.signal);
+                            combinedText += contResponse.text;
+                            if (!isTruncatedStop(contResponse.stopReason) || contResponse.toolCalls.length > 0) {
+                                response = { ...contResponse, text: combinedText };
+                                break;
+                            }
+                        }
+                        catch {
                             break;
                         }
-                        catch (retryErr) {
-                            if (!(retryErr instanceof ContextLimitError)) {
-                                this.config.onStream?.({ type: "error", error: retryErr.message });
-                                return { text: finalText, reason: "model_error", messages };
-                            }
+                    }
+                    response = { ...response, text: combinedText };
+                }
+                // After any continuation, send latest usage so ctx bar reflects real context
+                if (response.usage?.promptTokens !== undefined) {
+                    this.emitCtxFromUsage(response.usage, messages);
+                }
+                // Goal-mode run-scoped accounting: add this turn's total token usage
+                // (prompt + completion) to the running total. Done after continuation so
+                // continued output is counted against the budget.
+                if (goalTracker && response.usage) {
+                    const used = (response.usage.promptTokens ?? 0) + (response.usage.completionTokens ?? 0);
+                    recordGoalUsage(goalTracker, used);
+                }
+                // Aborted?
+                if (this.config.signal?.aborted) {
+                    this.markStopped();
+                    return { text: finalText, reason: "aborted_streaming", messages };
+                }
+                // Accumulate text
+                if (response.text) {
+                    finalText = response.text;
+                }
+                // Goal budget guardrail (P0): a run that has blown its token/time budget
+                // is force-stopped regardless of what the model wants to do next (stop OR
+                // continue with tool calls). This is the unattended-safety backstop, so
+                // it sits BEFORE the "tool calls?" branch — both paths pass the gate.
+                if (goalTracker && goalBudgetExceeded(goalTracker, Date.now())) {
+                    tlog.info("turn.goal_budget_exhausted", {
+                        cat: "goal",
+                        tokensUsed: goalTracker.tokensUsed,
+                        tokenBudget: this.config.goal?.tokenBudget,
+                        timeBudgetMs: this.config.goal?.timeBudgetMs,
+                    });
+                    this.config.onStream?.({
+                        type: "assistant_message",
+                        message: {
+                            role: "assistant",
+                            content: "（Goal 预算已耗尽，强制停止。）",
+                        },
+                    });
+                    return { text: finalText, reason: "goal_budget_exhausted", messages };
+                }
+                // Post-check: tool calls?
+                if (response.toolCalls.length === 0) {
+                    // No tool use — final answer
+                    this.config.onStream?.({
+                        type: "assistant_message",
+                        message: { role: "assistant", content: finalText },
+                    });
+                    await this.emitHook("on_turn_end", {
+                        turnNumber: this.turnCount,
+                        hasToolUse: false,
+                    });
+                    messages.push({ role: "assistant", content: finalText });
+                    // on_stop seam: the model wants to stop. Give handlers (Goal mode)
+                    // a chance to BLOCK termination and keep the agent working. A
+                    // handler returning continueSession=true injects its messages and
+                    // we run another turn instead of returning. Bounded by
+                    // maxStopBlocks (consecutive) and the outer maxTurns ceiling.
+                    const maxStopBlocks = this.config.maxStopBlocks ?? GOAL_DEFAULT_MAX_STOP_BLOCKS;
+                    const stopHook = await this.emitHook("on_stop", {
+                        goal: this.config.goal,
+                        finalText,
+                        turnCount: this.turnCount,
+                    });
+                    // The judge's structured verdict (set by GoalStopHook in result.data)
+                    // rides back here so we can show goal progress WITHOUT a second LLM
+                    // call — `gaps` is whatever the judge already computed.
+                    const goalVerdict = stopHook.data?.goalVerdict;
+                    if (stopHook.continueSession && this.stopBlockCount < maxStopBlocks) {
+                        this.stopBlockCount++;
+                        // Goal visibility: one not_met marker per re-prompt. round counts
+                        // up with stopBlockCount so the UI can show "第 N 轮".
+                        this.config.onStream?.({
+                            type: "goal_progress",
+                            status: "not_met",
+                            round: this.stopBlockCount,
+                            gaps: goalVerdict?.gaps || undefined,
+                        });
+                        // The streak just grew — we may now be nearing the stop-block cap.
+                        // Announce here (before the next turn's top check) so the "再续"
+                        // button shows up against the limit that's actually about to bite.
+                        this.maybeAnnounceApproachingLimit();
+                        const injection = wrapHookMessages(stopHook.messages);
+                        if (injection) {
+                            messages.push(injection);
+                        }
+                        else {
+                            // No guidance from the handler — inject a generic nudge so the
+                            // model knows it must keep going rather than re-emitting the
+                            // same final answer.
+                            messages.push({
+                                role: "user",
+                                content: "<system-reminder>The goal is not yet complete. Continue working toward it.</system-reminder>",
+                            });
                         }
+                        tlog.info("turn.stop_blocked", {
+                            cat: "turn",
+                            stopBlockCount: this.stopBlockCount,
+                            maxStopBlocks,
+                            hasGuidance: !!injection,
+                        });
+                        continue;
                     }
-                    if (!recovered) {
-                        this.patchOrphanedToolUses(messages);
+                    if (stopHook.continueSession && this.stopBlockCount >= maxStopBlocks) {
+                        // Cap hit: stop anyway, but tell the user why we're not looping
+                        // forever on an unsatisfiable goal.
+                        tlog.info("turn.stop_block_cap", {
+                            cat: "turn",
+                            stopBlockCount: this.stopBlockCount,
+                            maxStopBlocks,
+                        });
                         this.config.onStream?.({
-                            type: "error",
-                            error: "Context limit exceeded after 3 recovery attempts",
+                            type: "goal_progress",
+                            status: "exhausted",
+                            round: this.stopBlockCount,
+                        });
+                        this.config.onStream?.({
+                            type: "assistant_message",
+                            message: {
+                                role: "assistant",
+                                content: `（Goal 续跑已达 ${maxStopBlocks} 次上限，先停下。）`,
+                            },
                         });
-                        return { text: finalText, reason: "prompt_too_long", messages };
                     }
+                    else if (this.config.goal && goalVerdict?.met) {
+                        // Goal run completed cleanly: the judge says met. round = total
+                        // rounds = prior blocks + this accepted final round.
+                        this.config.onStream?.({
+                            type: "goal_progress",
+                            status: "met",
+                            round: this.stopBlockCount + 1,
+                        });
+                    }
+                    this.stopBlockCount = 0;
+                    return { text: finalText, reason: "completed", messages };
                 }
-                else {
-                    this.patchOrphanedToolUses(messages);
-                    this.config.onStream?.({ type: "error", error: err.message });
-                    return { text: finalText, reason: "model_error", messages };
+                // Tool execution phase
+                tlog.info("turn.tool_use", { cat: "turn", tools: response.toolCalls.map((t) => t.toolName) });
+                const toolCalls = response.toolCalls.slice(0, this.config.maxToolCallsPerTurn);
+                // Per-turn cap: any calls beyond maxToolCallsPerTurn are NOT executed and
+                // NOT added to the assistant message below, so the model never sees a
+                // result for them. Without a heads-up it assumes all ran (acting on
+                // tool output that never happened). Remember the dropped ones so we can
+                // inject a reminder after the executed batch's results. (B-3)
+                const droppedToolCalls = response.toolCalls.slice(this.config.maxToolCallsPerTurn);
+                // Add assistant message with tool_use blocks to messages
+                const assistantBlocks = [];
+                if (response.text) {
+                    assistantBlocks.push({ type: "text", text: response.text });
                 }
-            }
-            // UI ctx bar: prefer the provider's authoritative promptTokens.
-            if (response.usage?.promptTokens !== undefined) {
-                this.emitCtxFromUsage(response.usage.promptTokens, messages);
-            }
-            // Feed actual token usage back to the context manager so subsequent
-            // compaction decisions use hybrid (actual + delta) estimation rather than
-            // pure heuristics. Without this the manager falls back to char/4 estimates.
-            if (response.usage?.promptTokens !== undefined) {
-                this.deps.contextManager.recordActualUsage(response.usage.promptTokens, messages.length);
-            }
-            // Handle max_output_tokens: if response was truncated, do continuation (up to 3 times)
-            if (response.stopReason === "max_tokens" &&
-                response.toolCalls.length === 0 &&
-                response.text) {
-                let combinedText = response.text;
-                for (let retry = 0; retry < 3; retry++) {
-                    tlog.info("turn.max_tokens_continuation", { cat: "turn", retry: retry + 1 });
-                    const contMessages = [
-                        ...messages,
-                        { role: "assistant", content: combinedText },
-                        {
-                            role: "user",
-                            content: "<system-reminder>Your previous response was truncated due to length. Please continue from where you left off.</system-reminder>",
-                        },
-                    ];
-                    try {
-                        const contResponse = await this.deps.model.call(this.deps.systemPrompt, contMessages, this.deps.tools, this.config.onStream, this.config.signal);
-                        combinedText += contResponse.text;
-                        if (contResponse.stopReason !== "max_tokens" || contResponse.toolCalls.length > 0) {
-                            response = { ...contResponse, text: combinedText };
-                            break;
-                        }
+                for (const tc of toolCalls) {
+                    assistantBlocks.push({
+                        type: "tool_use",
+                        id: tc.id,
+                        name: tc.toolName,
+                        input: tc.args,
+                    });
+                    // Only emit tool_use_start if not already emitted during streaming
+                    if (!this.streamedToolIds.has(tc.id)) {
+                        this.config.onStream?.({ type: "tool_use_start", toolCall: tc });
+                    }
+                    // Record in transcript
+                    this.deps.transcript.appendToolUse(tc.toolName, tc.id, tc.args);
+                }
+                messages.push({ role: "assistant", content: assistantBlocks });
+                // Execute tools — enqueue concurrency-safe tools for early start,
+                // drain remaining (unsafe) tools sequentially.
+                for (const tc of toolCalls) {
+                    streamingQueue.enqueue(tc);
+                }
+                const results = await streamingQueue.drain();
+                // Record results in transcript and stream
+                const resultBlocks = [];
+                for (const result of results) {
+                    resultBlocks.push(toolResultToBlock(result));
+                    this.deps.transcript.appendToolResult(result.id, result.toolName, result.result, result.error);
+                    this.config.onStream?.({ type: "tool_result", result });
+                }
+                // Fire-and-forget tool use summary (non-blocking). The whole chain is
+                // best-effort observability — a thrown onStream handler, a failed dynamic
+                // import, or a rejecting summarize must never surface as an unhandled
+                // rejection (Node can treat those as fatal). Swallow at the tail. (B-2)
+                if (this.config.onStream) {
+                    void import("./tool-summary.js")
+                        .then(({ generateToolUseSummary }) => {
+                        if (!this.deps.model.summarize)
+                            return;
+                        return generateToolUseSummary(toolCalls, results, this.deps.model.summarize).then((summary) => {
+                            if (summary) {
+                                this.config.onStream?.({ type: "tool_summary", summary });
+                            }
+                        });
+                    })
+                        .catch((err) => {
+                        this.currentTurnLog.warn("tool_summary.dispatch_failed", {
+                            cat: "turn",
+                            error: err.message,
+                        });
+                    });
+                }
+                messages.push({ role: "user", content: resultBlocks });
+                // B-3: tell the model which of its requested tool calls were dropped by
+                // the per-turn cap so it can re-issue them, instead of silently assuming
+                // they ran. Appended to the same user message that carries the results.
+                if (droppedToolCalls.length > 0) {
+                    tlog.info("turn.tool_calls_capped", {
+                        cat: "turn",
+                        executed: toolCalls.length,
+                        dropped: droppedToolCalls.length,
+                        cap: this.config.maxToolCallsPerTurn,
+                    });
+                    const droppedNames = droppedToolCalls.map((t) => t.toolName).join(", ");
+                    // Separate user message (not folded into the tool_result blocks) so the
+                    // OpenAI converter — which lifts tool_results into standalone role:tool
+                    // messages — keeps the reminder as a plain user turn after them.
+                    messages.push({
+                        role: "user",
+                        content: `<system-reminder>Only the first ${toolCalls.length} of your ${response.toolCalls.length} ` +
+                            `tool calls ran this turn (per-turn limit is ${this.config.maxToolCallsPerTurn}). ` +
+                            `These were NOT executed and produced no result — do NOT assume they ran: ${droppedNames}. ` +
+                            `Re-issue the ones you still need in the next turn.</system-reminder>`,
+                    });
+                }
+                // Tool results just pushed; recompute ctx so the bar updates *before*
+                // the next model round-trip — large tool outputs can move it sharply.
+                this.emitCtxFromMessages(messages);
+                // Goal mode P0: explicit completion. If the model called complete_goal,
+                // it has DECLARED the goal done — short-circuit to "completed" WITHOUT
+                // running the judge hook. The tool's result is already in `messages`
+                // above so the summary lands in the transcript. Reset the stop-block
+                // counter so a prior judge-driven block streak doesn't leak out. Also
+                // clear the PERSISTED goal so a later bare send doesn't re-inherit a goal
+                // the model just declared finished (the judge's onMet does this when IT
+                // decides; a self-report must do the same, else the goal outlives its
+                // completion and re-arms every follow-up turn).
+                if (goalTracker && toolCalls.some((tc) => tc.toolName === COMPLETE_GOAL_TOOL_NAME)) {
+                    tlog.info("turn.goal_self_reported_complete", { cat: "goal" });
+                    this.stopBlockCount = 0;
+                    this.deps.clearPersistedGoal?.();
+                    return { text: finalText, reason: "completed", messages };
+                }
+                // Goal mode: user-initiated cancellation. cancel_goal is the "strong
+                // intent" escape hatch — honor it ONLY when confirm===true (the guard the
+                // tool advertises). A confirmed cancel stops the run AND clears the
+                // persisted goal so it never re-arms; an unconfirmed call is a no-op here
+                // (the tool's own result string already told the model it was ignored).
+                const confirmedCancel = toolCalls.some((tc) => tc.toolName === CANCEL_GOAL_TOOL_NAME && tc.args?.confirm === true);
+                if (goalTracker && confirmedCancel) {
+                    tlog.info("turn.goal_user_cancelled", { cat: "goal" });
+                    this.stopBlockCount = 0;
+                    this.deps.clearPersistedGoal?.();
+                    return { text: finalText, reason: "completed", messages };
+                }
+                // Token budget check
+                const totalOutputTokens = this.deps.model.getOutputTokens?.() ?? 0;
+                const budgetDecision = checkTokenBudget(totalOutputTokens, this.config.tokenBudget ?? Infinity, budgetTracker);
+                if (budgetDecision === "stop") {
+                    tlog.info("turn.budget_stop", {
+                        cat: "turn",
+                        outputTokens: totalOutputTokens,
+                        budget: this.config.tokenBudget,
+                    });
+                    this.config.onStream?.({
+                        type: "assistant_message",
+                        message: { role: "assistant", content: finalText },
+                    });
+                    messages.push({ role: "assistant", content: finalText });
+                    return { text: finalText, reason: "completed", messages };
+                }
+                if (budgetDecision === "nudge") {
+                    messages.push({
+                        role: "user",
+                        content: "<system-reminder>You are approaching the token budget limit. Please start wrapping up your work and provide a summary.</system-reminder>",
+                    });
+                }
+                // Investigation guard: end-of-turn check. If too many consecutive
+                // read-only turns went by without any user-visible text or side-effecting
+                // tool, inject a reminder that will land at the top of the next turn.
+                const guard = this.deps.toolExecutor.getInvestigationGuard();
+                if (guard) {
+                    guard.noteText(response.text);
+                    const turnReminder = guard.turnEnded(this.turnCount);
+                    if (turnReminder) {
+                        messages.push({ role: "user", content: turnReminder });
+                        tlog.info("guard.silent_turn", { cat: "guard", turn: this.turnCount });
                     }
-                    catch {
-                        break;
+                }
+                // Task guard: nudge the model if it has an in_progress task that
+                // hasn't moved in several turns. TaskCreate is sticky in working
+                // memory for the first few turns only; without this, the spinner
+                // runs forever on tasks the model has mentally finished.
+                const taskGuard = this.deps.toolExecutor.getTaskGuard();
+                if (taskGuard) {
+                    const taskReminder = taskGuard.turnEnded(this.turnCount);
+                    if (taskReminder) {
+                        messages.push({ role: "user", content: taskReminder });
+                        tlog.info("guard.stale_task", { cat: "guard", turn: this.turnCount });
                     }
                 }
-                response = { ...response, text: combinedText };
-            }
-            // After any continuation, send latest usage so ctx bar reflects real context
-            if (response.usage?.promptTokens !== undefined) {
-                this.emitCtxFromUsage(response.usage.promptTokens, messages);
-            }
-            // Aborted?
-            if (this.config.signal?.aborted) {
-                return { text: finalText, reason: "aborted_streaming", messages };
-            }
-            // Accumulate text
-            if (response.text) {
-                finalText = response.text;
-            }
-            // Post-check: tool calls?
-            if (response.toolCalls.length === 0) {
-                // No tool use — final answer
-                this.config.onStream?.({
-                    type: "assistant_message",
-                    message: { role: "assistant", content: finalText },
-                });
+                // Hook: turn end
                 await this.emitHook("on_turn_end", {
                     turnNumber: this.turnCount,
-                    hasToolUse: false,
+                    hasToolUse: true,
+                    toolCallCount: toolCalls.length,
                 });
-                messages.push({ role: "assistant", content: finalText });
-                return { text: finalText, reason: "completed", messages };
-            }
-            // Tool execution phase
-            tlog.info("turn.tool_use", { cat: "turn", tools: response.toolCalls.map((t) => t.toolName) });
-            const toolCalls = response.toolCalls.slice(0, this.config.maxToolCallsPerTurn);
-            // Add assistant message with tool_use blocks to messages
-            const assistantBlocks = [];
-            if (response.text) {
-                assistantBlocks.push({ type: "text", text: response.text });
-            }
-            for (const tc of toolCalls) {
-                assistantBlocks.push({
-                    type: "tool_use",
-                    id: tc.id,
-                    name: tc.toolName,
-                    input: tc.args,
-                });
-                // Only emit tool_use_start if not already emitted during streaming
-                if (!this.streamedToolIds.has(tc.id)) {
-                    this.config.onStream?.({ type: "tool_use_start", toolCall: tc });
-                }
-                // Record in transcript
-                this.deps.transcript.appendToolUse(tc.toolName, tc.id, tc.args);
-            }
-            messages.push({ role: "assistant", content: assistantBlocks });
-            // Execute tools — enqueue concurrency-safe tools for early start,
-            // drain remaining (unsafe) tools sequentially.
-            for (const tc of toolCalls) {
-                streamingQueue.enqueue(tc);
-            }
-            const results = await streamingQueue.drain();
-            // Record results in transcript and stream
-            const resultBlocks = [];
-            for (const result of results) {
-                const content = result.error ? `Error: ${result.error}` : (result.result ?? "(no output)");
-                resultBlocks.push({
-                    type: "tool_result",
-                    tool_use_id: result.id,
-                    content,
-                });
-                this.deps.transcript.appendToolResult(result.id, result.toolName, result.result, result.error);
-                this.config.onStream?.({ type: "tool_result", result });
-            }
-            // Fire-and-forget tool use summary (non-blocking)
-            if (this.config.onStream) {
-                import("./tool-summary.js").then(({ generateToolUseSummary }) => {
-                    if (!this.deps.model.summarize)
-                        return;
-                    generateToolUseSummary(toolCalls, results, this.deps.model.summarize).then((summary) => {
-                        if (summary) {
-                            this.config.onStream?.({ type: "tool_summary", summary });
-                        }
-                    });
-                });
-            }
-            messages.push({ role: "user", content: resultBlocks });
-            // Tool results just pushed; recompute ctx so the bar updates *before*
-            // the next model round-trip — large tool outputs can move it sharply.
-            this.emitCtxFromMessages(messages);
-            // Token budget check
-            const totalOutputTokens = this.deps.model.getOutputTokens?.() ?? 0;
-            const budgetDecision = checkTokenBudget(totalOutputTokens, this.config.tokenBudget ?? Infinity, budgetTracker);
-            if (budgetDecision === "stop") {
-                tlog.info("turn.budget_stop", {
+                // Record turn boundary
+                this.deps.transcript.appendTurnBoundary();
+                this.config.onTurnBoundary?.(this.turnCount);
+                tlog.info("turn.end", {
                     cat: "turn",
-                    outputTokens: totalOutputTokens,
-                    budget: this.config.tokenBudget,
-                });
-                this.config.onStream?.({
-                    type: "assistant_message",
-                    message: { role: "assistant", content: finalText },
-                });
-                messages.push({ role: "assistant", content: finalText });
-                return { text: finalText, reason: "completed", messages };
-            }
-            if (budgetDecision === "nudge") {
-                messages.push({
-                    role: "user",
-                    content: "<system-reminder>You are approaching the token budget limit. Please start wrapping up your work and provide a summary.</system-reminder>",
+                    duration_ms: Date.now() - turnStartedAt,
+                    outcome: "continue",
                 });
             }
-            // Investigation guard: end-of-turn check. If too many consecutive
-            // read-only turns went by without any user-visible text or side-effecting
-            // tool, inject a reminder that will land at the top of the next turn.
-            const guard = this.deps.toolExecutor.getInvestigationGuard();
-            if (guard) {
-                guard.noteText(response.text);
-                const turnReminder = guard.turnEnded(this.turnCount);
-                if (turnReminder) {
-                    messages.push({ role: "user", content: turnReminder });
-                    tlog.info("guard.silent_turn", { cat: "guard", turn: this.turnCount });
-                }
-            }
-            // Task guard: nudge the model if it has an in_progress task that
-            // hasn't moved in several turns. TaskCreate is sticky in working
-            // memory for the first few turns only; without this, the spinner
-            // runs forever on tasks the model has mentally finished.
-            const taskGuard = this.deps.toolExecutor.getTaskGuard();
-            if (taskGuard) {
-                const taskReminder = taskGuard.turnEnded(this.turnCount);
-                if (taskReminder) {
-                    messages.push({ role: "user", content: taskReminder });
-                    tlog.info("guard.stale_task", { cat: "guard", turn: this.turnCount });
-                }
+        }
+        catch (err) {
+            // Unexpected throw from the per-turn scaffolding (manageAsync, hooks,
+            // guards). Patch any dangling tool_use so a later resume isn't poisoned,
+            // surface the error to the UI, and return a terminal reason so the
+            // engine's post-run saveState records model_error instead of leaving
+            // the session stuck at "active".
+            this.patchOrphanedToolUses(messages);
+            // A user-initiated Stop also bubbles here (an AbortError thrown from the
+            // per-turn scaffolding). Treat it as a clean abort, not a model_error —
+            // no error event, so the UI shows only the "你停止了本轮" line.
+            if (isAbortError(err) || this.config.signal?.aborted) {
+                this.markStopped();
+                return { text: finalText, reason: "aborted_streaming", messages };
             }
-            // Hook: turn end
-            await this.emitHook("on_turn_end", {
-                turnNumber: this.turnCount,
-                hasToolUse: true,
-                toolCallCount: toolCalls.length,
-            });
-            // Record turn boundary
-            this.deps.transcript.appendTurnBoundary();
-            this.config.onTurnBoundary?.(this.turnCount);
-            tlog.info("turn.end", {
+            this.currentTurnLog.error("turn.unhandled_error", {
                 cat: "turn",
-                duration_ms: Date.now() - turnStartedAt,
-                outcome: "continue",
+                error: err.message,
+                stack: err.stack?.split("\n").slice(0, 4).join("\n"),
             });
+            this.config.onStream?.({ type: "error", error: formatFriendlyError(err) });
+            return { text: finalText, reason: "model_error", messages };
         }
         // Max turns reached — do one final summarization call (no tools)
         logger.warn("turn.max_turns_reached", {
@@ -464,6 +911,7 @@ export class TurnLoop {
     async callModelWithFallback(messages) {
         // Wrap stream callback to track tool_use_start events and reactive compaction
         let streamingResponseTokens = 0;
+        let reactiveBucket = -1;
         const wrappedStream = this.config.onStream
             ? (event) => {
                 if (event.type === "tool_use_start" && event.toolCall?.id) {
@@ -474,8 +922,12 @@ export class TurnLoop {
                     streamingResponseTokens += Math.ceil(event.text.length / 4);
                 }
                 // Reactive compaction warning: if nearing context limit mid-stream,
-                // log a warning (actual compaction happens between turns)
-                if (streamingResponseTokens > 0 && streamingResponseTokens % 2000 === 0) {
+                // log a warning (actual compaction happens between turns). Gated to
+                // fire once per 2000-token bucket crossed — the old `% 2000 === 0`
+                // check essentially never matched the running accumulator.
+                const probe = crossedReactiveThreshold(streamingResponseTokens, reactiveBucket);
+                if (probe.crossed) {
+                    reactiveBucket = probe.bucket;
                     if (this.deps.contextManager.shouldReactiveCompact(messages, streamingResponseTokens)) {
                         this.currentTurnLog.warn("turn.reactive_compact_warning", {
                             cat: "turn",
@@ -494,6 +946,20 @@ export class TurnLoop {
             // If it's a context or rate limit error, don't fallback — propagate
             if (err instanceof ContextLimitError)
                 throw err;
+            // User cancelled (ESC / Stop / run signal). Falling back to a
+            // non-streaming call here re-sends the whole request the user just
+            // aborted. Propagate so the run unwinds cleanly instead of doing
+            // more work after cancellation.
+            //
+            // Check the run signal too, not only isAbortError(err): when a streaming
+            // request is aborted the error sometimes surfaces as a generic
+            // `Error: Request was aborted.` whose `name` is NOT "AbortError"
+            // (wrapping strips it), so isAbortError misses it and we'd fall back —
+            // re-issuing the cancelled request, which then throws "Aborted before
+            // LLM request" from withRetry and surfaces as a scary error on what was
+            // really just a cancel. The signal is the authoritative cancel source.
+            if (isAbortError(err) || this.config.signal?.aborted)
+                throw err;
             // Streaming might have partially emitted — send tombstone to revoke
             this.config.onStream?.({ type: "tombstone", messageId: `turn_${this.turnCount}` });
             this.currentTurnLog.warn("turn.streaming_fallback", {
@@ -504,51 +970,6 @@ export class TurnLoop {
             return await this.deps.model.callWithoutStreaming(this.deps.systemPrompt, messages, this.deps.tools, this.config.signal);
         }
     }
-    /**
-     * Execute tools with overlap: start concurrent-safe (read-only) tools
-     * immediately in parallel while sequential (write) tools run one-by-one.
-     * Both groups run simultaneously — we don't wait for safe tools to finish
-     * before starting unsafe ones.
-     */
-    async executeToolsOverlapped(calls) {
-        if (calls.length <= 1) {
-            // Single tool — no overlap needed
-            return this.deps.toolExecutor.executeAll(calls);
-        }
-        const safe = [];
-        const unsafe = [];
-        for (const call of calls) {
-            if (this.deps.toolExecutor.isConcurrencySafe(call.toolName)) {
-                safe.push(call);
-            }
-            else {
-                unsafe.push(call);
-            }
-        }
-        // If all same type, delegate directly
-        if (safe.length === 0 || unsafe.length === 0) {
-            return this.deps.toolExecutor.executeAll(calls);
-        }
-        // Run both groups simultaneously:
-        // - safe tools all in parallel
-        // - unsafe tools sequentially (but started at the same time as safe group)
-        const resultMap = new Map();
-        const safePromise = Promise.all(safe.map((c) => this.deps.toolExecutor.executeSingle(c)));
-        const unsafePromise = (async () => {
-            const results = [];
-            for (const call of unsafe) {
-                results.push(await this.deps.toolExecutor.executeSingle(call));
-            }
-            return results;
-        })();
-        const [safeResults, unsafeResults] = await Promise.all([safePromise, unsafePromise]);
-        for (const r of safeResults)
-            resultMap.set(r.id, r);
-        for (const r of unsafeResults)
-            resultMap.set(r.id, r);
-        // Return results in original call order for deterministic transcript
-        return calls.map((c) => resultMap.get(c.id));
-    }
     get currentTurn() {
         return this.turnCount;
     }
@@ -558,45 +979,57 @@ export class TurnLoop {
      * Prevents model confusion on the next turn.
      */
     patchOrphanedToolUses(messages) {
-        // Find the last assistant message with tool_use blocks
-        for (let i = messages.length - 1; i >= 0; i--) {
-            const msg = messages[i];
-            if (msg.role !== "assistant" || !Array.isArray(msg.content))
+        // Pre-compute every answered tool_use id across the WHOLE array, then scan
+        // forward and patch EVERY assistant message with a gap — not just the most
+        // recent one. The old version scanned backward and returned at the first
+        // all-answered assistant message, so when several earlier turns each left
+        // orphaned tool_uses (multi-turn API failures) only the latest got patched
+        // and the rest stayed unpaired → a 400 on the next call / on resume.
+        const answeredIds = new Set();
+        for (const msg of messages) {
+            if (!Array.isArray(msg.content))
                 continue;
-            const toolUseIds = [];
             for (const block of msg.content) {
-                if (block.type === "tool_use" && block.id)
-                    toolUseIds.push(block.id);
+                if (block.type === "tool_result" && block.tool_use_id) {
+                    answeredIds.add(block.tool_use_id);
+                }
             }
-            if (toolUseIds.length === 0)
+        }
+        let totalPatched = 0;
+        for (let i = 0; i < messages.length; i++) {
+            const msg = messages[i];
+            if (msg.role !== "assistant" || !Array.isArray(msg.content))
                 continue;
-            // Check if all tool_use IDs have corresponding tool_results
-            const answeredIds = new Set();
-            for (let j = i + 1; j < messages.length; j++) {
-                const rm = messages[j];
-                if (!Array.isArray(rm.content))
-                    continue;
-                for (const block of rm.content) {
-                    if (block.type === "tool_result" && block.tool_use_id) {
-                        answeredIds.add(block.tool_use_id);
-                    }
+            const orphanedIds = [];
+            for (const block of msg.content) {
+                if (block.type === "tool_use" && block.id && !answeredIds.has(block.id)) {
+                    orphanedIds.push(block.id);
                 }
             }
-            const orphanedIds = toolUseIds.filter((id) => !answeredIds.has(id));
             if (orphanedIds.length === 0)
-                return;
-            // Inject synthetic error results
+                continue;
+            // Synthetic error results, spliced in RIGHT AFTER the offending assistant
+            // message (not appended to the end) so each tool_use is paired in place.
+            // is_error must be set: the Anthropic provider only emits is_error when
+            // the flag is present, otherwise the model reads the cancellation as plain
+            // text output and assumes the tool succeeded.
             const errorBlocks = orphanedIds.map((id) => ({
                 type: "tool_result",
                 tool_use_id: id,
                 content: "Error: Tool execution was cancelled because the previous API call failed.",
+                is_error: true,
             }));
-            messages.push({ role: "user", content: errorBlocks });
+            messages.splice(i + 1, 0, { role: "user", content: errorBlocks });
+            for (const id of orphanedIds)
+                answeredIds.add(id);
+            totalPatched += orphanedIds.length;
+            i += 1; // skip the message we just spliced in
+        }
+        if (totalPatched > 0) {
             this.currentTurnLog.warn("turn.patched_orphaned_tool_uses", {
                 cat: "turn",
-                count: orphanedIds.length,
+                count: totalPatched,
             });
-            return; // Only patch the most recent orphaned set
         }
     }
 }