@agent-native/core 0.153.4 → 0.153.5

package/dist/agent/engine/tool-call-journal-seed.d.ts

@@ -12,9 +12,33 @@ export interface PriorTurnToolCallSummary {
  * `PriorTurnToolCallSummary` for why this is a local shape, not an import. */
 export interface PriorTurnToolResultSummary {
     name: string;
+    /**
+     * Input of the `tool_start` this result was matched to, so the caller can
+     * rebuild the same `(tool, arguments)` breaker key its live counters use.
+     * Legacy `tool_done` events carry no input; those keep the positional
+     * FIFO-per-tool pairing documented in `tool-call-journal.ts`, so this is
+     * absent only when neither event carried one.
+     */
+    input?: unknown;
     content: string;
     isError: boolean;
 }
+/**
+ * Outcome of reading the per-turn ledger. `unreadable` is deliberately NOT the
+ * same value as a turn with no history: the repetition ledger, the read-only
+ * result cache and the write-replay hard block are all seeded from this read,
+ * so a swallowed ledger failure silently restores the per-chunk ceilings those
+ * mechanisms exist to remove.
+ */
+export type PriorTurnToolCallJournalRead = {
+    status: "read";
+    toolCallJournal: ToolCallJournal | null;
+    priorToolCalls: PriorTurnToolCallSummary[];
+    priorToolResults: PriorTurnToolResultSummary[];
+} | {
+    status: "unreadable";
+    error: string;
+};
 /**
  * Tool-call journal hard-block (resume safety). Snapshot the per-turn journal
  * ONCE here, before any tool runs in this chunk, so it reflects only PRIOR
@@ -25,9 +49,8 @@ export interface PriorTurnToolResultSummary {
  *
  * Loaded eagerly (not lazily mid-loop) so the current chunk's own
  * asynchronously-persisted tool_done events can never leak in and make a
- * same-chunk call wrongly short-circuit. Best-effort: any ledger failure
- * leaves the journal empty and all calls run normally. Fresh first-turn calls
- * see an empty journal and are unaffected.
+ * same-chunk call wrongly short-circuit. Fresh first-turn calls see an empty
+ * journal and are unaffected.
  *
  * Also returns the prior chunks' tool calls/results so the caller can seed
  * its own `toolCallHistory` / `toolResultHistory` accumulators — final
@@ -35,11 +58,5 @@ export interface PriorTurnToolResultSummary {
  * tools executed after the latest handoff. Otherwise a guard can reject a
  * grounded answer (or a successfully-created artifact) after the
  * evidence-producing query completed in a predecessor run.
- *
- * Moved verbatim out of `runAgentLoop`'s per-turn setup — behavior unchanged.
  */
-export declare function loadPriorTurnToolCallJournal(threadId: string | undefined, turnId?: string): Promise<{
-    toolCallJournal: ToolCallJournal | null;
-    priorToolCalls: PriorTurnToolCallSummary[];
-    priorToolResults: PriorTurnToolResultSummary[];
-}>;
+export declare function loadPriorTurnToolCallJournal(threadId: string | undefined, turnId?: string): Promise<PriorTurnToolCallJournalRead>;

package/dist/agent/engine/tool-call-journal-seed.js

@@ -10,9 +10,8 @@ import { classifyToolCallJournal, } from "../tool-call-journal.js";
  *
  * Loaded eagerly (not lazily mid-loop) so the current chunk's own
  * asynchronously-persisted tool_done events can never leak in and make a
- * same-chunk call wrongly short-circuit. Best-effort: any ledger failure
- * leaves the journal empty and all calls run normally. Fresh first-turn calls
- * see an empty journal and are unaffected.
+ * same-chunk call wrongly short-circuit. Fresh first-turn calls see an empty
+ * journal and are unaffected.
  *
  * Also returns the prior chunks' tool calls/results so the caller can seed
  * its own `toolCallHistory` / `toolResultHistory` accumulators — final
@@ -20,40 +19,55 @@ import { classifyToolCallJournal, } from "../tool-call-journal.js";
  * tools executed after the latest handoff. Otherwise a guard can reject a
  * grounded answer (or a successfully-created artifact) after the
  * evidence-producing query completed in a predecessor run.
- *
- * Moved verbatim out of `runAgentLoop`'s per-turn setup — behavior unchanged.
  */
 export async function loadPriorTurnToolCallJournal(threadId, turnId) {
-    const priorToolCalls = [];
-    const priorToolResults = [];
-    let toolCallJournal = null;
     if (!threadId) {
-        return { toolCallJournal, priorToolCalls, priorToolResults };
+        // No thread means no durable ledger exists for this turn at all — a true
+        // "no prior history", not a read that failed.
+        return {
+            status: "read",
+            toolCallJournal: null,
+            priorToolCalls: [],
+            priorToolResults: [],
+        };
     }
+    let priorEvents;
     try {
-        const priorEvents = await getCurrentTurnEventsForThread(threadId, turnId);
-        if (priorEvents.length > 0) {
-            for (const event of priorEvents) {
-                if (event.type === "tool_start") {
-                    priorToolCalls.push({
-                        name: event.tool,
-                        input: event.input,
-                    });
-                }
-                else if (event.type === "tool_done") {
-                    priorToolResults.push({
-                        name: event.tool,
-                        content: event.result,
-                        isError: event.isError === true,
-                    });
-                }
-            }
-            toolCallJournal = classifyToolCallJournal(priorEvents);
-        }
+        priorEvents = await getCurrentTurnEventsForThread(threadId, turnId);
+    }
+    catch (err) {
+        const error = err instanceof Error ? err.message : String(err);
+        console.warn(`[tool-call-journal] per-turn ledger read failed for thread ${threadId}: ${error}`);
+        return { status: "unreadable", error };
     }
-    catch {
-        // Journal is a hardening layer, never a gate — a failed ledger read just
-        // means no hard-block this turn.
+    const priorToolCalls = [];
+    const priorToolResults = [];
+    // Open `tool_start` inputs per tool, so a legacy `tool_done` with no input of
+    // its own can still be attributed to the arguments it ran with.
+    const openInputsByTool = new Map();
+    for (const event of priorEvents) {
+        if (event.type === "tool_start") {
+            priorToolCalls.push({ name: event.tool, input: event.input });
+            const queue = openInputsByTool.get(event.tool);
+            if (queue)
+                queue.push(event.input);
+            else
+                openInputsByTool.set(event.tool, [event.input]);
+        }
+        else if (event.type === "tool_done") {
+            const fifoInput = openInputsByTool.get(event.tool)?.shift();
+            priorToolResults.push({
+                name: event.tool,
+                input: event.input ?? fifoInput,
+                content: event.result,
+                isError: event.isError === true,
+            });
+        }
     }
-    return { toolCallJournal, priorToolCalls, priorToolResults };
+    return {
+        status: "read",
+        toolCallJournal: priorEvents.length > 0 ? classifyToolCallJournal(priorEvents) : null,
+        priorToolCalls,
+        priorToolResults,
+    };
 }

package/dist/agent/production-agent.d.ts

@@ -183,6 +183,8 @@ export interface ActionEntry {
     /** If true, completion does NOT trigger a screen-refresh change event.
      *  Set automatically by `defineAction` when `http.method === "GET"`. */
     readOnly?: boolean;
+    /** If true, a successful call returns evidence retrieved from a live source. */
+    grounding?: boolean;
     /** False keeps a read-only tool available in Act mode but hides/blocks it in
      *  Plan mode. Use for tools that perform substantive work even without
      *  mutating state. */
@@ -613,6 +615,21 @@ export declare const MAX_SAME_ERROR_ACROSS_ARGUMENTS = 6;
  * legitimate re-check after a write.
  */
 export declare const MAX_IDENTICAL_TOOL_CALLS = 8;
+/**
+ * A stop that ends the turn from inside the tool loop.
+ *
+ * `message` is the last thing the user reads, so it must name the remedy and
+ * must NOT quote a raw provider/tool error: both `isAutoRecoverableError`
+ * (client) and `isRecoverableContinuationError` (below) sniff this string for
+ * "timeout"/"connection"/"network", and a stop whose text happens to contain
+ * one is auto-continued into the very spiral it was raised to end. The raw
+ * error belongs in `details`, which nothing retries on.
+ */
+export interface TerminalActionStop {
+    message: string;
+    errorCode?: string;
+    details?: string;
+}
 /**
  * Convert ActionEntry registry to EngineTool array.
  */
@@ -687,6 +704,22 @@ export declare function findApprovedStructuredToolCall(history: AgentChatStructu
     input: unknown;
     callId: string;
 } | undefined;
+/**
+ * Tool errors the model has no way to clear: the missing thing lives outside
+ * the turn (a credential, a role grant, a connected account, a runtime, the
+ * user's own approval). Every retry costs a full round-trip carrying the whole
+ * transcript and lands on the identical error, so these stop on the FIRST
+ * occurrence rather than after `MAX_SAME_ERROR_ACROSS_ARGUMENTS` of them.
+ *
+ * The distinction is the one `stopForBigQueryNotConfigured` draws in
+ * templates/analytics: a *configuration* gap is permanent for this turn, a
+ * *query* failure is not. Anything the model can act on — a stale read to
+ * rebase, a bad argument, a full quota it can free, a wrong dataset name, a
+ * statement timeout — must stay out of this list and keep its retries.
+ * Precision over recall: a wrong match kills a turn that would have succeeded,
+ * which is worse than one more retry.
+ */
+export declare function permanentPreconditionRemedy(message: string): string | null;
 export declare function repeatedSourceSweepGuardMessage(opts: {
     toolName: string;
     priorCalls: number;

package/dist/agent/production-agent.js

@@ -2439,6 +2439,11 @@ async function waitForInterruptedToolLedgerEntry(opts) {
  * Dropping the echoed input costs nothing: the fault is already named by the
  * sentence before it, and two failures that differ ONLY in the arguments they
  * echo are the same failure.
+ *
+ * Numbers go the same way, for the same reason. A guard that reports its own
+ * running tally ("this turn already made 13 call(s)") hands the breaker a new
+ * key on every single decline, so the decline that exists to stop a spiral is
+ * itself uncountable.
  */
 function normalizeToolErrorForBreaker(error) {
     return (error
@@ -2446,6 +2451,7 @@ function normalizeToolErrorForBreaker(error) {
         .replace(/Received:\s*[\s\S]*?\.\s(?=Expected:|The tool was not executed)/g, "")
         // Bare JSON payloads some providers inline instead of a Received: span.
         .replace(/\{[\s\S]{0,2000}?\}/g, "{}")
+        .replace(/\d+/g, "#")
         .replace(/\s+/g, " ")
         .trim());
 }
@@ -2455,6 +2461,50 @@ function rateLimitRecoveryHint(message) {
     }
     return "\n\nProvider rate-limit guidance: stop retrying this provider in this turn. Report the rate limit as a coverage gap, include any evidence already gathered, and ask the user to retry after the provider quota resets if full coverage is required.";
 }
+/**
+ * Tool errors the model has no way to clear: the missing thing lives outside
+ * the turn (a credential, a role grant, a connected account, a runtime, the
+ * user's own approval). Every retry costs a full round-trip carrying the whole
+ * transcript and lands on the identical error, so these stop on the FIRST
+ * occurrence rather than after `MAX_SAME_ERROR_ACROSS_ARGUMENTS` of them.
+ *
+ * The distinction is the one `stopForBigQueryNotConfigured` draws in
+ * templates/analytics: a *configuration* gap is permanent for this turn, a
+ * *query* failure is not. Anything the model can act on — a stale read to
+ * rebase, a bad argument, a full quota it can free, a wrong dataset name, a
+ * statement timeout — must stay out of this list and keep its retries.
+ * Precision over recall: a wrong match kills a turn that would have succeeded,
+ * which is worse than one more retry.
+ */
+export function permanentPreconditionRemedy(message) {
+    const trimmed = message.replace(/\s+/g, " ").trim();
+    for (const pattern of PERMANENT_PRECONDITION_PATTERNS) {
+        if (pattern.test(trimmed))
+            return trimmed;
+    }
+    return null;
+}
+const PERMANENT_PRECONDITION_PATTERNS = [
+    // "Requires editor role on deck ZJshjrXhjx (have viewer)". The trailing space
+    // is load-bearing: it keeps "must have required property" out.
+    /\brequires? (?:an? |the )?[\w-]+ role\b/i,
+    // "Gemini API key not configured. Save GEMINI_API_KEY in settings." Only the
+    // not-configured/not-set wordings — "not found" is how providers report a
+    // missing dataset or record, which the model can and should correct.
+    /\b(?:api[ -]?keys?|access tokens?|credentials?|secrets?)\b[^.]{0,60}\bnot (?:configured|set|connected|available)\b/i,
+    /\bsave [A-Z][A-Z0-9_]{3,} in (?:the )?settings\b/i,
+    // "Connect Builder.io before indexing a design system from Figma or code."
+    /\bconnect\b[^;]{1,40}?\b(?:before|first|in settings)\b/i,
+    // "…is only available in local Plan runtime." Excludes "only available after
+    // …", which names a condition that clears on its own.
+    /\bonly available (?:in|on|from|to)\b/i,
+    // "Plan mode blocked `update-extension`. Switch to Act mode …" — cleared by
+    // the user approving the plan, never by the model trying again.
+    /\bplan mode blocked\b/i,
+    /\bno authenticated user\b/i,
+    // "SSRF blocked: refusing to fetch private/internal address (…)"
+    /\bssrf blocked\b/i,
+];
 const SOURCE_SWEEP_TOOL_NAME = /\b(?:api|calls?|deals?|docs?|events?|issues?|messages?|metrics?|provider|query|records?|request|search|source|tickets?|transcripts?)\b/i;
 const SOURCE_SWEEP_PROVIDER_TOKEN = /\b(?:amplitude|apollo|bigquery|commonroom|data-source|ga4|github|gong|grafana|hubspot|jira|mixpanel|notion|posthog|postgres|postgresql|pylon|sentry|slack|stripe)\b/i;
 const SOURCE_SWEEP_EXCLUDED_TOOLS = new Set([
@@ -3095,29 +3145,50 @@ export async function runAgentLoop(opts) {
     // calls/results are folded into `toolCallHistory` / `toolResultHistory` so
     // final response guards see evidence from earlier chunks of this turn.
     const consumedJournalKeys = new Set();
-    const { toolCallJournal, priorToolCalls: journaledPriorToolCalls, priorToolResults: journaledPriorToolResults, } = await loadPriorTurnToolCallJournal(opts.threadId, opts.turnId);
+    const journalRead = await loadPriorTurnToolCallJournal(opts.threadId, opts.turnId);
+    const toolCallJournal = journalRead.status === "read" ? journalRead.toolCallJournal : null;
+    const journaledPriorToolCalls = journalRead.status === "read" ? journalRead.priorToolCalls : [];
+    const journaledPriorToolResults = journalRead.status === "read" ? journalRead.priorToolResults : [];
     toolCallHistory.push(...journaledPriorToolCalls);
     toolResultHistory.push(...journaledPriorToolResults);
+    // Every per-turn ceiling below is seeded from that read, and the write-replay
+    // hard block is enforced from it. On a continuation we cannot tell an
+    // already-completed side effect from a fresh one without it, so a failed read
+    // stops the turn instead of quietly resuming with a blank ledger.
+    const unreadableJournalStop = journalRead.status === "unreadable" && isInternalContinuationTurn(messages)
+        ? {
+            message: "I stopped because I could not read this turn's run ledger, so I could not tell which steps had already finished. " +
+                "Retrying would risk repeating a step that already completed. Please send the request again.",
+            errorCode: "tool_call_journal_unreadable",
+            details: journalRead.error,
+        }
+        : null;
     const readOnlyToolResultCache = seedReadOnlyToolResultsFromHistory(messages, actions, seedReadOnlyToolResultsFromJournal(toolCallJournal, actions));
     const duplicateReadOnlyToolCalls = seedDuplicateReadOnlyToolCallsFromHistory(messages, actions);
     const writeToolInterruptions = seedWriteToolInterruptionsFromHistory(messages, actions);
+    // All three repetition ledgers are SEEDED from earlier chunks of this turn,
+    // like `toolCallHistory` and `toolResultHistory` above. A fresh Map makes the
+    // limit per-CHUNK rather than per-turn, and a turn may chain up to
+    // MAX_RUN_LOOP_CONTINUATIONS (6) or MAX_BACKGROUND_RUN_LOOP_CONTINUATIONS
+    // (20) of them — so the real ceiling becomes 20x the constant, and a spiral
+    // resumes with a clean slate at every chunk boundary.
     const repeatedToolErrors = new Map();
-    // Keyed WITHOUT the arguments — see MAX_SAME_ERROR_ACROSS_ARGUMENTS.
-    //
-    // SEEDED from earlier chunks of this turn, like `toolCallHistory` and
-    // `toolResultHistory` above. A fresh Map here would make the limit per-CHUNK
-    // rather than per-turn, and a turn may chain up to MAX_RUN_LOOP_CONTINUATIONS
-    // (6) or MAX_BACKGROUND_RUN_LOOP_CONTINUATIONS (20) of them — so the real
-    // ceiling would be 36 or 120 identical failures, not 6, and a spiral would
-    // resume with a clean slate at every chunk boundary.
+    /** Keyed WITHOUT the arguments — see MAX_SAME_ERROR_ACROSS_ARGUMENTS. */
     const repeatedToolErrorsAnyArgs = new Map();
-    for (const prior of toolResultHistory) {
+    const repeatedToolCalls = new Map();
+    for (const prior of journaledPriorToolCalls) {
+        const key = toolCallCacheKey(prior.name, prior.input);
+        repeatedToolCalls.set(key, (repeatedToolCalls.get(key) ?? 0) + 1);
+    }
+    for (const prior of journaledPriorToolResults) {
         if (!prior.isError)
             continue;
-        const key = `${prior.name}:${normalizeToolErrorForBreaker(prior.content)}`;
-        repeatedToolErrorsAnyArgs.set(key, (repeatedToolErrorsAnyArgs.get(key) ?? 0) + 1);
+        const normalized = normalizeToolErrorForBreaker(prior.content);
+        const anyArgsKey = `${prior.name}:${normalized}`;
+        repeatedToolErrorsAnyArgs.set(anyArgsKey, (repeatedToolErrorsAnyArgs.get(anyArgsKey) ?? 0) + 1);
+        const errorKey = `${toolCallCacheKey(prior.name, prior.input)}:${normalized}`;
+        repeatedToolErrors.set(errorKey, (repeatedToolErrors.get(errorKey) ?? 0) + 1);
     }
-    const repeatedToolCalls = new Map();
     let finalGuardRetries = 0;
     let emptyFinalResponseRetries = 0;
     let iterations = 0;
@@ -3125,6 +3196,31 @@ export async function runAgentLoop(opts) {
     // trailing `done` would overwrite the boundary the continuation logic reads.
     let endedAtLoopLimit = false;
     let terminalActionStop = null;
+    /**
+     * A stop is either a hand-off to the user (the two `input_required` codes) or
+     * a failed run. Failed runs MUST leave a terminal `error` event behind: the
+     * run row's status, `error_code`, `listErroredRuns`, the outcome counters and
+     * the client's retry affordance all key off that event, and a stop that only
+     * streams text is recorded as `status='completed', terminal_reason='done'` —
+     * a guard trip counted as a success.
+     */
+    const sendTerminalActionStop = (stop) => {
+        if (stop.errorCode === "needs-approval" ||
+            stop.errorCode === "awaiting-user-input") {
+            send({ type: "text", text: stop.message });
+            return;
+        }
+        // Sent ONLY as an error: both the live client and the thread rebuild render
+        // an error event's message as assistant text themselves, so also sending it
+        // as `text` prints the same sentence twice.
+        send({
+            type: "error",
+            error: stop.message,
+            errorCode: stop.errorCode ?? "tool_failed",
+            ...(stop.details ? { details: stop.details } : {}),
+            recoverable: false,
+        });
+    };
     // Overridden (raised tokens, lowered effort) only after an empty-final-
     // response retry below — kept separate from `opts.maxOutputTokens`/
     // `opts.reasoningEffort` so the very first attempt is unaffected and later
@@ -3151,6 +3247,11 @@ export async function runAgentLoop(opts) {
     while (true) {
         if (signal.aborted)
             break;
+        if (unreadableJournalStop) {
+            terminalActionStop = unreadableJournalStop;
+            sendTerminalActionStop(unreadableJournalStop);
+            break;
+        }
         const turnInputTokens = priorTurnInputTokens + usage.inputTokens;
         if (turnInputTokens > maxRunInputTokens) {
             // Terminal for the whole TURN, not a chunk boundary: emitting
@@ -3882,9 +3983,6 @@ export async function runAgentLoop(opts) {
         // call run. The model cannot populate this — it comes from the request.
         const approvedToolCallKeys = new Set(opts.approvedToolCalls ?? []);
         const runToolCall = async (toolCall) => {
-            // Counted before any journal/cache short-circuit: serving a repeat from
-            // cache still means the model is asking the same question again.
-            noteRepeatedToolCall(toolCall.name, toolCall.input);
             const actionEntry = actions[toolCall.name];
             const placeholderNormalization = actionEntry
                 ? normalizeOptionalToolPlaceholders(actionEntry.tool.parameters, toolCall.input)
@@ -3898,6 +3996,11 @@ export async function runAgentLoop(opts) {
             if (jsonStringCoercion.changed) {
                 toolCall = { ...toolCall, input: jsonStringCoercion.input };
             }
+            // Count after the same normalization that is persisted in the journal:
+            // a model can send a JSON-encoded object/array, while the action and
+            // ledger both see the coerced value. Serving a repeat from cache still
+            // counts as asking the same question again.
+            noteRepeatedToolCall(toolCall.name, toolCall.input);
             const toolInputNormalized = placeholderNormalization.changed || jsonStringCoercion.changed;
             const wireToolInput = JSON.stringify(toolCall.input ?? {});
             const normalizedToolInput = normalizeToolCallInputForHistory(toolCall.input);
@@ -3931,6 +4034,20 @@ export async function runAgentLoop(opts) {
             };
             const finalizeToolErrorResult = (rawResult) => {
                 const sanitizedResult = sanitizeToolErrorText(rawResult);
+                // Counting is the wrong instrument for a precondition the turn cannot
+                // satisfy: six identical round-trips through a missing API key cost the
+                // user minutes and end where the first one did. Classified first so the
+                // remedy reaches them on attempt one.
+                const permanentRemedy = permanentPreconditionRemedy(sanitizedResult);
+                if (permanentRemedy) {
+                    requestedActionStop ??= {
+                        message: `I stopped because ${toolCall.name} cannot run until this is fixed: ${permanentRemedy} Retrying would not have changed it, and anything completed before this is saved.`,
+                        errorCode: "permanent_precondition",
+                        details: sanitizedResult,
+                    };
+                    return (`Stopped: ${toolCall.name} cannot run until a setup step outside this turn is fixed. ` +
+                        `Do not retry it with different arguments. ${sanitizedResult}`);
+                }
                 const errorKey = `${toolCallCacheKey(toolCall.name, toolCall.input)}:${normalizeToolErrorForBreaker(sanitizedResult)}`;
                 const count = (repeatedToolErrors.get(errorKey) ?? 0) + 1;
                 repeatedToolErrors.set(errorKey, count);
@@ -3946,9 +4063,9 @@ export async function runAgentLoop(opts) {
                         `with different arguments. Last error: ${sanitizedResult}`;
                     requestedActionStop ??= {
                         message: `I stopped because the ${toolCall.name} action rejected ${anyArgsCount} different attempts the same way, ` +
-                            "so changing the arguments again would not have worked. Anything completed before this is saved. " +
-                            `Error: ${sanitizedResult}`,
+                            "so changing the arguments again would not have worked. Anything completed before this is saved.",
                         errorCode: "repeated_tool_error_across_arguments",
+                        details: sanitizedResult,
                     };
                     return result;
                 }
@@ -3961,15 +4078,23 @@ export async function runAgentLoop(opts) {
                 // can do; never instruct them to "fix the arguments".
                 requestedActionStop ??= {
                     message: `I stopped because the ${toolCall.name} action failed ${count} times in a row the same way, ` +
-                        "so retrying it again would not have worked. Anything completed before this is saved. " +
-                        `Error: ${sanitizedResult}`,
+                        "so retrying it again would not have worked. Anything completed before this is saved.",
                     errorCode: "repeated_identical_tool_error",
+                    details: sanitizedResult,
                 };
                 return result;
             };
-            if (sourceSweepGuard) {
-                sourceSweepDelegationGuardActive = true;
-                const result = sourceSweepGuard.message;
+            /**
+             * A guard refused to run the tool. Recorded as an ERROR, not as a plain
+             * result: a decline costs a full model round-trip carrying the whole
+             * transcript, and `noteRepeatedToolCall` keys on name+args, so a model
+             * iterating ids mints a fresh key every time and declines forever until
+             * `maxIterations`. Routing through `finalizeToolErrorResult` gives the
+             * existing breakers something to count — no new counter — while the text
+             * the model reads is still the guard's own guidance.
+             */
+            const declineToolCall = (guidance) => {
+                const result = finalizeToolErrorResult(guidance);
                 send({
                     type: "tool_start",
                     id: toolCall.id,
@@ -3982,9 +4107,10 @@ export async function runAgentLoop(opts) {
                     tool: toolCall.name,
                     input: toolCall.input,
                     result,
+                    isError: true,
                     completedSideEffect: false,
                 });
-                recordToolResult(result, false);
+                recordToolResult(result, true);
                 return {
                     type: "tool-result",
                     toolCallId: toolCall.id,
@@ -3992,31 +4118,13 @@ export async function runAgentLoop(opts) {
                     toolInput: wireToolInput,
                     content: result,
                 };
+            };
+            if (sourceSweepGuard) {
+                sourceSweepDelegationGuardActive = true;
+                return declineToolCall(sourceSweepGuard.message);
             }
             if (sourceSweepDelegationGuard) {
-                const result = sourceSweepDelegationGuard;
-                send({
-                    type: "tool_start",
-                    id: toolCall.id,
-                    tool: toolCall.name,
-                    input: toolCall.input,
-                });
-                send({
-                    type: "tool_done",
-                    id: toolCall.id,
-                    tool: toolCall.name,
-                    input: toolCall.input,
-                    result,
-                    completedSideEffect: false,
-                });
-                recordToolResult(result, false);
-                return {
-                    type: "tool-result",
-                    toolCallId: toolCall.id,
-                    toolName: toolCall.name,
-                    toolInput: wireToolInput,
-                    content: result,
-                };
+                return declineToolCall(sourceSweepDelegationGuard);
             }
             if (!actionEntry) {
                 const result = finalizeToolErrorResult(`Error: Unknown tool "${toolCall.name}"`);
@@ -4817,7 +4925,7 @@ export async function runAgentLoop(opts) {
             // TypeScript can't track ??= through async closures; cast to known type.
             const stop = requestedActionStop;
             terminalActionStop = stop;
-            send({ type: "text", text: stop.message });
+            sendTerminalActionStop(stop);
             break;
         }
     }
@@ -4893,6 +5001,10 @@ export async function runAgentLoop(opts) {
             }
         }
     }
+    // Assignments happen inside async tool-loop closures, which TypeScript cannot
+    // use for narrowing at this point. Snapshot the runtime value before the
+    // outcome branches so a stop is still represented as a possible value.
+    const finalTerminalActionStop = terminalActionStop;
     if (signal.aborted) {
         reportOutcome({ state: "canceled", message: "Agent run was aborted." });
     }
@@ -4904,26 +5016,26 @@ export async function runAgentLoop(opts) {
             message: `Agent stopped after ${maxIterations} iterations.`,
         });
     }
-    else if (terminalActionStop?.errorCode === "needs-approval") {
+    else if (finalTerminalActionStop?.errorCode === "needs-approval") {
         reportOutcome({
             state: "input_required",
             code: "needs_approval",
-            message: terminalActionStop.message,
+            message: finalTerminalActionStop.message,
         });
     }
-    else if (terminalActionStop?.errorCode === "awaiting-user-input") {
+    else if (finalTerminalActionStop?.errorCode === "awaiting-user-input") {
         reportOutcome({
             state: "input_required",
             code: "awaiting_user_input",
-            message: terminalActionStop.message,
+            message: finalTerminalActionStop.message,
         });
     }
-    else if (terminalActionStop) {
+    else if (finalTerminalActionStop) {
         reportOutcome({
             state: "failed",
-            code: terminalActionStop.errorCode ?? "tool_failed",
+            code: finalTerminalActionStop.errorCode ?? "tool_failed",
             retryable: false,
-            message: terminalActionStop.message,
+            message: finalTerminalActionStop.message,
         });
     }
     else {
@@ -5383,8 +5495,11 @@ async function emitRunText(run, text) {
  * per-turn journal the resume note uses (no new ledger read shape).
  */
 async function describeTurnProgress(threadId, turnId) {
-    const { toolCallJournal } = await loadPriorTurnToolCallJournal(threadId, turnId);
-    const completed = toolCallJournal?.completed ?? [];
+    const journalRead = await loadPriorTurnToolCallJournal(threadId, turnId);
+    if (journalRead.status === "unreadable") {
+        return "I could not read the run ledger, so I cannot say which steps completed.";
+    }
+    const completed = journalRead.toolCallJournal?.completed ?? [];
     if (completed.length === 0)
         return "No steps had completed yet.";
     const names = [...new Set(completed.map((entry) => entry.tool))];

package/dist/agent/run-loop-with-resume.d.ts

@@ -27,7 +27,7 @@ import type { ResolveRunSoftTimeoutOptions } from "./run-manager.js";
  * Rebuild the same safe continuation context for a logical turn that resumes
  * in a fresh hosted invocation.
  */
-export declare function appendDurableContinuationContext(messages: EngineMessage[], reason: AgentLoopContinuationReason, threadId: string): Promise<void>;
+export declare function appendDurableContinuationContext(messages: EngineMessage[], reason: AgentLoopContinuationReason, threadId: string, turnId?: string): Promise<void>;
 /**
  * Cap on continuation iterations inside a single
  * `runAgentLoopDirectWithSoftTimeout` invocation. The host's hard function