@agent-native/core 0.203.0 → 0.203.1-nightly-20261007183952

package/dist/agent/production-agent.js

@@ -44,6 +44,7 @@ import { isReasoningEffort, normalizeReasoningEffortForRequest, stepDownReasonin
 import { SYNTHETIC_TRAFFIC_BETA_E2E, SYNTHETIC_TRAFFIC_HEADER, } from "../shared/test-traffic.js";
 import { actionPreparationContinuationNote } from "./action-continuation-guidance.js";
 import { drainAgentWarnings, formatAgentWarningsForToolResult, } from "./action-warnings.js";
+import { clipHead } from "./clip-text.js";
 import { buildSystemManifestSections, readContextXraySystemSections, } from "./context-xray/manifest.js";
 import { AGENT_CHAT_BACKGROUND_RUN_FIELD, AGENT_CHAT_PROCESS_RUN_PATH, backgroundRuntimeDiagnosticDetail, dispatchPathTargetsNetlifyBackgroundFunction, isAgentChatDurableBackgroundEnabled, isAgentChatForegroundSelfChainEnabled, isInBackgroundFunctionRuntime, resolveAgentChatProcessRunDispatchPath, shouldUseBackgroundFunctionTimeoutForWorker, } from "./durable-background.js";
 import { applyContextXrayTransformForIteration } from "./engine/context-directives-transform.js";
@@ -51,19 +52,20 @@ import { attemptContinuationDispatch } from "./engine/continuation-dispatch-retr
 import { formatLlmCredentialErrorMessage, LLM_MISSING_CREDENTIALS_ERROR_CODE, LLM_MISSING_CREDENTIALS_MESSAGE, userFacingLlmCredentialError, } from "./engine/credential-errors.js";
 import { BUILDER_GATEWAY_INTERNAL_ERROR_CODE, isContextOverflowCode, isContextOverflowMessage, isProviderConnectionErrorMessage, PROVIDER_RATE_LIMITED_ERROR_CODE, PROVIDER_TRANSIENT_REJECTION_ERROR_CODE, } from "./engine/error-detail.js";
 import { resolveEngine, explicitEngineName, registerBuiltinEngines, getStoredModelForEngine, normalizeModelForEngine, isResolvedEngineUsableForRequest, } from "./engine/index.js";
+import { limitProviderTools, MAX_PROVIDER_TOOLS, } from "./engine/limit-provider-tools.js";
 import { resolveEmptyResponseRetryMaxOutputTokens, resolveMainChatMaxOutputTokens, resolveMaxOutputTokensForEngine, } from "./engine/output-tokens.js";
 import { PROVIDER_TO_ENV } from "./engine/provider-env-vars.js";
 import { JOURNALED_TOOL_REPLAY_PREFIX, RECOVERED_TOOL_REPLAY_PREFIX, loadedSkillPagesContext, loadPriorTurnToolCallJournal, seedRepeatedToolErrorCountsFromJournal, seedRepeatedToolCallCountsFromJournal, } from "./engine/tool-call-journal-seed.js";
 import { backfillEngineMessagesToolResults, stringifyToolUseInputForGateway, unmatchedToolResultReplayText, } from "./engine/translate-anthropic.js";
 import { EngineError } from "./engine/types.js";
-import { FOLLOW_UP_SUGGESTIONS_COMPLETION_INSTRUCTION, FOLLOW_UP_SUGGESTIONS_INSTRUCTION, FOLLOW_UP_SUGGESTIONS_MAX_OUTPUT_TOKENS, FOLLOW_UP_SUGGESTIONS_TOOL_NAME, followUpSuggestionsTool, identifyFollowUpSuggestions, parseFollowUpSuggestions, } from "./follow-up-suggestions.js";
+import { FOLLOW_UP_SUGGESTIONS_COMPLETION_SYSTEM_PROMPT, FOLLOW_UP_SUGGESTIONS_INSTRUCTION, FOLLOW_UP_SUGGESTIONS_MAX_OUTPUT_TOKENS, FOLLOW_UP_SUGGESTIONS_TOOL_NAME, buildFollowUpCompletionMessages, followUpSuggestionsTool, identifyFollowUpSuggestions, parseFollowUpSuggestions, } from "./follow-up-suggestions.js";
 import { filterHostedHarnessToolNames, normalizeHostedHarnessRuntime, } from "./harness/hosted.js";
 import { buildRecentUserRequestContext, buildJevRequestContext, preloadJevTools, } from "./jev-tool-prefetch.js";
 import { getDefaultMaxIterations, getDefaultMaxRunInputTokens, MAX_AGENT_MAX_ITERATIONS, MIN_AGENT_MAX_ITERATIONS, normalizeMaxIterations, normalizeMaxRunInputTokens, readAgentLoopSettings, } from "./loop-settings.js";
 import { getContextWindowForModel, resolveFallbackModel, } from "./model-config.js";
 import { maybeCompactThread, buildObservationalContext, hasObservationalMemory, serializeObservationalMemoryBlock, } from "./observational-memory/index.js";
 import { ProcessorChain, TripWire, toolCallsFromContent, } from "./processors.js";
-import { resolveUncheckedDefaultModelReplacement } from "./provider-model-selection.js";
+import { applyUncheckedDefaultModelReplacement } from "./provider-model-selection.js";
 import { startRun, subscribeToRun, replayCompletedTurn, getActiveRunForThread, getActiveRunForThreadAsync, getRun, abortRun, abortRunDurably, abortTurnByRefDurably, abortTurnDurably, getSlotHoldingRunId, tryClaimRunSlot, isHostedRuntime, resolveRunSoftTimeoutMs, resolveRunToolTimeoutCeilingMs, endsAfterToolResultWithoutAssistantFinal, endsDuringActionPreparation, } from "./run-manager.js";
 import { writeLedgerEntry, readLedgerEntry, clearLedgerForThread, AgentTurnInitiatorMismatchError, AgentTurnInitiatorUnavailableError, insertRun, insertRunEvent, isTurnAborted, markRunAborted, updateRunHeartbeat, updateRunStatusIfRunning, setRunError, setRunTerminalReason, claimBackgroundRun, readBackgroundRunClaim, recordRunDiagnostic, countRunsForTurn, RUN_DIAG_STAGE, UNCLAIMED_BACKGROUND_RUN_GRACE_MS, turnRunLedgerExhausted, } from "./run-store.js";
 import { buildCurrentTimeUserContext } from "./runtime-context.js";
@@ -72,8 +74,9 @@ import { consumeAgentToolApproval, createAgentToolApproval, isAgentToolAlwaysAll
 import { buildResumeJournalNote, findCompletedJournalEntry, } from "./tool-call-journal.js";
 import { redactSensitiveFields, sanitizeToolErrorText, sanitizeToolErrorValue, } from "./tool-error-redaction.js";
 import { describeToolResultImages, extractAgentImagesFromActionResult, } from "./tool-result-images.js";
-import { createToolSearchEntry, filterActionsForAgentDiscovery, searchToolRegistry, TOOL_SEARCH_ACTION_NAME, } from "./tool-search.js";
+import { createToolSearchEntry, extractToolSearchResultNames, filterActionsForAgentDiscovery, readLoadedToolNames, searchToolRegistry, TOOL_SEARCH_ACTION_NAME, withLoadedToolNames, } from "./tool-search.js";
 import { normalizeAgentActionScope, } from "./types.js";
+import { mergeFinalResponseGuards, readWriteReceipt, writeReceiptGuard, } from "./write-receipts.js";
 registerBuiltinEngines();
 export { PROVIDER_TO_ENV };
 /**
@@ -1081,6 +1084,11 @@ export function resolveSourceSweepToolCallThreshold() {
     return getAppConfig().agent.sourceSweepToolCallThreshold;
 }
 const EXPANDED_TOOL_SCHEMA_WARN_BYTES = 32_000;
+const MAX_TOOL_SEARCH_OVERFLOW_NAMES_SHOWN = 5;
+const PROVIDER_CORE_TOOL_NAMES = [
+    TOOL_SEARCH_ACTION_NAME,
+    FOLLOW_UP_SUGGESTIONS_TOOL_NAME,
+];
 const MAX_SCREEN_CONTEXT_CHARS = 10_000;
 function capScreenContext(text) {
     if (text.length <= MAX_SCREEN_CONTEXT_CHARS)
@@ -1841,6 +1849,36 @@ async function enrichMessage(message, references) {
     }
     return `${parts.join("\n\n")}\n\n${message}`;
 }
+/**
+ * Folds one loop attempt's usage into a running total. Every wrapper that
+ * re-enters `runAgentLoop` merges through this, so a field added to
+ * `AgentLoopUsage` cannot be reported by the loop and dropped by a wrapper.
+ */
+export function mergeAgentLoopUsage(total, next) {
+    total.inputTokens += next.inputTokens;
+    total.outputTokens += next.outputTokens;
+    total.cacheReadTokens += next.cacheReadTokens;
+    total.cacheWriteTokens += next.cacheWriteTokens;
+    for (const key of [
+        "builderCreditsUsed",
+        "llmCalls",
+        "followUpMs",
+        "followUpInputTokens",
+        "receiptUnverifiedCount",
+        "receiptChangedFalseCount",
+    ]) {
+        if (typeof next[key] === "number") {
+            total[key] = (total[key] ?? 0) + next[key];
+        }
+    }
+    total.engineName = next.engineName ?? total.engineName;
+    total.model = next.model;
+    if (next.usageReported)
+        total.usageReported = true;
+    // Keep the earliest attempt's first event — a later continuation
+    // attempt starting fresh must not overwrite genuine first-token timing.
+    total.firstEngineEventAtMs ??= next.firstEngineEventAtMs;
+}
 function collectTextParts(parts) {
     return parts
         .filter((part) => part.type === "text")
@@ -2255,6 +2293,51 @@ const INTERRUPTED_TOOL_LEDGER_RECOVERY_TIMEOUT_MS = 5_000;
 const MAX_IDENTICAL_TOOL_ERRORS = 3;
 export const MAX_SAME_ERROR_ACROSS_ARGUMENTS = 3;
 export const MAX_IDENTICAL_TOOL_CALLS = 8;
+const MAX_ALREADY_LOADED_TOOL_SEARCHES = 4;
+const MAX_STOP_ERROR_LINE_CHARS = 300;
+/** `error: message` for a JSON `{ error, message }` result; `undefined` when the text is not one. */
+function jsonErrorCause(text) {
+    if (!text.startsWith("{"))
+        return undefined;
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+        // coercion-ok: unparseable text is not a JSON error result; the caller reads its first line
+    }
+    catch {
+        return undefined;
+    }
+    const { error, message } = (parsed ?? {});
+    if (typeof error !== "string" || !error.trim())
+        return undefined;
+    return typeof message === "string" && message.trim()
+        ? `${error}: ${message}`
+        : error;
+}
+function errorCauseLine(text) {
+    const body = text.trim().replace(/^Error running [^\s:]+:\s*/, "");
+    return ((jsonErrorCause(body) ?? body)
+        .split(/\r?\n/)
+        .find((line) => line.trim())
+        ?.trim() ?? "");
+}
+/**
+ * The line of a failed tool result that names the cause, for a message the
+ * user reads. It takes the credential-sanitized text and keeps identifiers and
+ * emails, since a column or account name is the diagnosis; the trace-grade
+ * `toolErrorSignature` redacts those. A pretty-printed JSON error opens with
+ * `Error running x: {`, and a `(errorCode: ...)` suffix keeps it from parsing,
+ * so a bare first line can be only a bracket.
+ */
+function stopErrorLine(sanitizedResult) {
+    const lines = sanitizedResult.split(/\r?\n/).filter((line) => line.trim());
+    for (const candidate of [sanitizedResult, ...lines]) {
+        const cause = errorCauseLine(candidate);
+        if (/[\p{L}\p{N}]/u.test(cause))
+            return cause;
+    }
+    return errorCauseLine(sanitizedResult) || "(no error text)";
+}
 function isToolCallTimeoutResult(content) {
     return /tool call timed out after \d+(?:\.\d+)? seconds?/i.test(content);
 }
@@ -2500,30 +2583,9 @@ const DEFAULT_INITIAL_TOOL_NAMES = new Set([
 function isDefaultInitialToolName(name) {
     return DEFAULT_INITIAL_TOOL_NAMES.has(name);
 }
-function extractToolSearchResultNames(value) {
-    if (!value || typeof value !== "object")
-        return [];
-    const result = value;
-    if (typeof result.query !== "string" || result.query.trim().length === 0) {
-        return [];
-    }
-    if (!Array.isArray(result.results))
-        return [];
-    const names = [];
-    for (const item of result.results) {
-        if (!item || typeof item !== "object")
-            continue;
-        const record = item;
-        if (record.callable === false)
-            continue;
-        const name = record.name;
-        if (typeof name === "string" && name.trim())
-            names.push(name);
-    }
-    return names;
-}
-function extractToolSearchResultNamesFromMessages(messages) {
+function readToolSearchHistory(messages) {
     const names = [];
+    let unreadable = 0;
     for (const message of messages) {
         if (message.role !== "user")
             continue;
@@ -2533,15 +2595,14 @@ function extractToolSearchResultNamesFromMessages(messages) {
                 typeof part.content !== "string") {
                 continue;
             }
-            try {
-                names.push(...extractToolSearchResultNames(JSON.parse(part.content)));
-            }
-            catch {
-                // Tool results are best-effort history hints; ignore non-JSON content.
-            }
+            const loaded = readLoadedToolNames(part.content);
+            if (loaded)
+                names.push(...loaded);
+            else
+                unreadable += 1;
         }
     }
-    return names;
+    return { names, unreadable };
 }
 function normalizeToolInputSchema(schema) {
     if (!schema)
@@ -3347,6 +3408,8 @@ export async function runAgentLoop(opts) {
         : providedAvailableTools;
     let completedFollowUpSuggestions;
     let completingFollowUpSuggestions = false;
+    let followUpCompletionContext = [];
+    let followUpStartedAt;
     let followUpCompletionFailed = false;
     const failFollowUpCompletion = (code) => {
         if (followUpCompletionFailed)
@@ -3382,8 +3445,8 @@ export async function runAgentLoop(opts) {
     const finalResponseGuardRequestText = opts.finalResponseGuardRequestText ??
         resolveFinalResponseGuardRequestText(messages);
     const availableToolMap = new Map((availableTools ?? tools).map((tool) => [tool.name, tool]));
-    const activeToolNames = new Set(tools.map((tool) => tool.name));
-    let activeTools = tools;
+    let activeTools = limitProviderTools(tools, PROVIDER_CORE_TOOL_NAMES);
+    const activeToolNames = new Set(activeTools.map((tool) => tool.name));
     let appAuthorizationPromise;
     const resolveTurnAppAuthorization = (userEmail, orgId) => {
         if (!appAuthorizationPromise) {
@@ -3401,36 +3464,85 @@ export async function runAgentLoop(opts) {
     };
     let expandedToolSchemaBytes = 0;
     let reportedExpandedToolSchemaBytes = false;
-    const expandActiveTools = (names) => {
-        const added = [];
-        for (const name of names) {
-            if (activeToolNames.has(name))
-                continue;
+    let alreadyLoadedToolSearches = 0;
+    // Tools loaded after the first request, least recently needed first.
+    const loadedToolNames = new Set();
+    const noteToolNeeded = (name) => {
+        if (loadedToolNames.delete(name))
+            loadedToolNames.add(name);
+    };
+    // `names` lead with what the model needs most. Below MAX_PROVIDER_TOOLS they
+    // append in registry order, so the tools prefix of the prompt cache survives.
+    // Past it the request keeps, in this order: tool-search and the follow-up
+    // tool, `pinned` (already promised this step) and `names`, the initial
+    // tools, then the other loaded tools most recently needed first, so the least
+    // recently needed loaded tools are evicted before any initial one. A tool
+    // that still does not fit is returned as overflow and never becomes active,
+    // so `activeTools` is exactly what the engine sends and nothing it dropped is
+    // reported as loaded.
+    const expandActiveTools = (names, pinned = new Set()) => {
+        const requested = new Set(names);
+        for (const name of requested)
+            noteToolNeeded(name);
+        const wanted = [...requested].flatMap((name) => {
             const tool = availableToolMap.get(name);
-            if (!tool)
-                continue;
-            activeToolNames.add(name);
-            expandedToolSchemaBytes += JSON.stringify(tool).length;
-            added.push(name);
-        }
-        if (added.length > 0) {
-            const expandedTools = (availableTools ?? tools).filter((tool) => activeToolNames.has(tool.name));
-            const prioritizedNames = new Set(names);
-            if (followUpRunId)
-                prioritizedNames.add(FOLLOW_UP_SUGGESTIONS_TOOL_NAME);
-            activeTools = [
-                ...expandedTools.filter((tool) => prioritizedNames.has(tool.name)),
-                ...expandedTools.filter((tool) => !prioritizedNames.has(tool.name)),
-            ];
+            return tool && !activeToolNames.has(name) ? [tool] : [];
+        });
+        const added = [];
+        const overflow = [];
+        if (wanted.length > 0) {
+            if (activeTools.length + wanted.length <= MAX_PROVIDER_TOOLS) {
+                const wantedNames = new Set(wanted.map((tool) => tool.name));
+                activeTools = [
+                    ...activeTools,
+                    ...(availableTools ?? tools).filter((tool) => wantedNames.has(tool.name)),
+                ];
+            }
+            else {
+                const byName = new Map([...activeTools, ...wanted].map((tool) => [tool.name, tool]));
+                const priority = new Set([
+                    ...PROVIDER_CORE_TOOL_NAMES,
+                    ...pinned,
+                    ...names,
+                    ...activeTools
+                        .map((tool) => tool.name)
+                        .filter((name) => !loadedToolNames.has(name)),
+                    ...[...loadedToolNames].reverse(),
+                ]);
+                activeTools = [...priority]
+                    .flatMap((name) => byName.get(name) ?? [])
+                    .slice(0, MAX_PROVIDER_TOOLS);
+            }
+            activeToolNames.clear();
+            for (const tool of activeTools)
+                activeToolNames.add(tool.name);
+            for (const name of loadedToolNames) {
+                if (!activeToolNames.has(name))
+                    loadedToolNames.delete(name);
+            }
+            for (const tool of wanted) {
+                if (!activeToolNames.has(tool.name)) {
+                    overflow.push(tool.name);
+                    continue;
+                }
+                added.push(tool.name);
+                loadedToolNames.add(tool.name);
+                expandedToolSchemaBytes += JSON.stringify(tool).length;
+            }
         }
         if (!reportedExpandedToolSchemaBytes &&
             expandedToolSchemaBytes > EXPANDED_TOOL_SCHEMA_WARN_BYTES) {
             reportedExpandedToolSchemaBytes = true;
             console.warn(`[agent-loop] expanded tool schemas reached ${expandedToolSchemaBytes} bytes across ${activeToolNames.size} active tools (runId=${opts.runId ?? "none"})`);
         }
-        return added;
+        return { added, overflow };
     };
-    expandActiveTools(extractToolSearchResultNamesFromMessages(messages));
+    const priorSearches = readToolSearchHistory(messages);
+    if (priorSearches.unreadable > 0) {
+        console.warn(`[agent-loop] ${priorSearches.unreadable} earlier tool-search result(s) could not be read, so the tools they loaded were not restored (runId=${opts.runId ?? "none"})`);
+    }
+    // Newest searches lead, so they win if history alone overflows the cap.
+    expandActiveTools(priorSearches.names.reverse());
     const processorChain = opts.processors && opts.processors.length > 0
         ? new ProcessorChain(opts.processors)
         : null;
@@ -3460,6 +3572,8 @@ export async function runAgentLoop(opts) {
         actions,
     });
     const toolResultHistory = [];
+    const turnReceipts = () => toolResultHistory.flatMap((result) => result.receipt ? [{ tool: result.name, ...result.receipt }] : []);
+    let receiptGuardRetried = false;
     const runCtx = getRequestRunContext();
     if (runCtx) {
         runCtx.toolCalls = toolCallHistory;
@@ -3618,44 +3732,28 @@ export async function runAgentLoop(opts) {
         let terminalStopReason;
         const toolCallErrors = new Map();
         let contextMessages = completingFollowUpSuggestions
-            ? [
-                ...messages,
-                {
-                    role: "user",
-                    content: [
-                        {
-                            type: "text",
-                            text: FOLLOW_UP_SUGGESTIONS_COMPLETION_INSTRUCTION,
-                        },
-                    ],
-                },
-            ]
+            ? followUpCompletionContext
             : messages;
-        try {
-            if (opts.threadId) {
-                contextMessages = await applyContextXrayTransformForIteration({
+        // The completion call carries a digest, not the conversation: the manifest
+        // and memory window describe the full thread, and the transform would
+        // overwrite this turn's manifest with the digest.
+        if (opts.threadId && !completingFollowUpSuggestions) {
+            contextMessages = await applyContextXrayTransformForIteration({
+                threadId: opts.threadId,
+                ownerEmail: opts.ownerEmail,
+                turnId: opts.turnId,
+                model,
+                messages: contextMessages,
+                systemSections: opts.systemSections,
+            });
+            if (opts.ownerEmail) {
+                contextMessages = await applyObservationalMemoryToContext(contextMessages, {
                     threadId: opts.threadId,
                     ownerEmail: opts.ownerEmail,
-                    turnId: opts.turnId,
-                    model,
-                    messages: contextMessages,
-                    systemSections: opts.systemSections,
+                    orgId: opts.orgId ?? null,
                 });
-                if (opts.ownerEmail) {
-                    contextMessages = await applyObservationalMemoryToContext(contextMessages, {
-                        threadId: opts.threadId,
-                        ownerEmail: opts.ownerEmail,
-                        orgId: opts.orgId ?? null,
-                    });
-                }
             }
         }
-        catch (error) {
-            if (signal.aborted || !completingFollowUpSuggestions)
-                throw error;
-            failFollowUpCompletion("context_error");
-            break;
-        }
         if (signal.aborted)
             break;
         for (let retry = 0;; retry++) {
@@ -3674,7 +3772,9 @@ export async function runAgentLoop(opts) {
                 }
                 const streamOpts = {
                     model,
-                    systemPrompt: continuationSystemPrompt,
+                    systemPrompt: completingFollowUpSuggestions
+                        ? FOLLOW_UP_SUGGESTIONS_COMPLETION_SYSTEM_PROMPT
+                        : continuationSystemPrompt,
                     messages: contextMessages,
                     tools: loopBreakerCloseout
                         ? []
@@ -3949,6 +4049,10 @@ export async function runAgentLoop(opts) {
                             usage.outputTokens += eventUsage.outputTokens;
                             usage.cacheReadTokens += eventUsage.cacheReadTokens;
                             usage.cacheWriteTokens += eventUsage.cacheWriteTokens;
+                            if (completingFollowUpSuggestions) {
+                                usage.followUpInputTokens =
+                                    (usage.followUpInputTokens ?? 0) + eventUsage.inputTokens;
+                            }
                             if (eventUsage.builderCreditsUsed !== undefined) {
                                 usage.builderCreditsUsed =
                                     (usage.builderCreditsUsed ?? 0) +
@@ -4070,6 +4174,9 @@ export async function runAgentLoop(opts) {
                 throw err;
             }
         }
+        if (completingFollowUpSuggestions && followUpStartedAt !== undefined) {
+            usage.followUpMs = Date.now() - followUpStartedAt;
+        }
         if (tripwire || followUpCompletionFailed)
             break;
         if (!assistantContent && toolCallErrors.size > 0) {
@@ -4252,6 +4359,8 @@ export async function runAgentLoop(opts) {
             }
             let guard = null;
             const finalResponseDraftText = collectTextParts(assistantContentForHistory);
+            const receipts = turnReceipts();
+            const receiptGuard = writeReceiptGuard(receipts, receiptGuardRetried);
             if (opts.finalResponseGuard) {
                 try {
                     guard = await opts.finalResponseGuard({
@@ -4261,6 +4370,7 @@ export async function runAgentLoop(opts) {
                         text: finalResponseDraftText,
                         toolCalls: [...toolCallHistory],
                         toolResults: [...toolResultHistory],
+                        receipts,
                         retryCount: finalGuardRetries,
                         executionMode: opts.executionMode ?? "act",
                     });
@@ -4270,6 +4380,11 @@ export async function runAgentLoop(opts) {
                     throw err;
                 }
             }
+            if (receiptGuard) {
+                guard = guard
+                    ? mergeFinalResponseGuards(receiptGuard, guard)
+                    : receiptGuard;
+            }
             if (guard) {
                 completedFollowUpSuggestions = undefined;
                 const retryMessage = typeof guard === "string" ? guard : guard.retryMessage;
@@ -4279,7 +4394,10 @@ export async function runAgentLoop(opts) {
                     : Math.max(0, Math.min(3, Math.trunc(guard.maxRetries ?? 1)));
                 if (finalGuardRetries < maxGuardRetries) {
                     if (typeof guard !== "string" && guard.expandToolSurface) {
-                        expandActiveTools([...availableToolMap.keys()]);
+                        expandActiveTools([...activeToolNames, ...availableToolMap.keys()]);
+                    }
+                    if (receiptGuard && receiptGuard.maxRetries > 0) {
+                        receiptGuardRetried = true;
                     }
                     finalGuardRetries += 1;
                     send({ type: "clear" });
@@ -4309,6 +4427,12 @@ export async function runAgentLoop(opts) {
                     completedFollowUpSuggestions === undefined &&
                     terminalStopReason === "end_turn") {
                     completingFollowUpSuggestions = true;
+                    followUpStartedAt = Date.now();
+                    followUpCompletionContext = buildFollowUpCompletionMessages({
+                        requestText: finalResponseGuardRequestText,
+                        replyText: finalResponseDraftText,
+                        toolNames: toolCallHistory.map((call) => call.name),
+                    });
                     continue;
                 }
             }
@@ -4370,7 +4494,12 @@ export async function runAgentLoop(opts) {
             return requestedActionStop === stop ? stop : null;
         };
         const approvedToolCallKeys = new Set(opts.approvedToolCalls ?? []);
+        // A tool-search in this step loads schemas the model can call only on the
+        // next step, so a sibling search must not read them as already callable.
+        const toolNamesLoadedThisStep = new Set();
+        let countedAlreadyLoadedSearchThisStep = false;
         const runToolCall = async (toolCall) => {
+            noteToolNeeded(toolCall.name);
             const actionEntry = actions[toolCall.name];
             const placeholderNormalization = actionEntry
                 ? normalizeOptionalToolPlaceholders(actionEntry.tool.parameters, toolCall.input)
@@ -4442,12 +4571,13 @@ export async function runAgentLoop(opts) {
                 name: toolCall.name,
                 input: normalizedToolInput,
             });
-            const recordToolResult = (content, isError, artifacts) => {
+            const recordToolResult = (content, isError, artifacts, receipt) => {
                 toolResultHistory.push({
                     name: toolCall.name,
                     content,
                     isError,
                     ...(artifacts?.length ? { artifacts } : {}),
+                    ...(receipt ? { receipt } : {}),
                 });
             };
             let directStop = null;
@@ -4483,9 +4613,12 @@ export async function runAgentLoop(opts) {
                     anyArgsCount >= MAX_SAME_ERROR_ACROSS_ARGUMENTS) {
                     const result = `Stopped after ${anyArgsCount} attempts at ${toolCall.name} that all failed the same way ` +
                         `with different arguments. Last error: ${sanitizedResult}`;
+                    const lastErrorLine = stopErrorLine(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.",
+                        message: `I stopped because the ${toolCall.name} action rejected ${anyArgsCount} different attempts the same way. ` +
+                            `Last error: ${lastErrorLine.length > MAX_STOP_ERROR_LINE_CHARS
+                                ? `${clipHead(lastErrorLine, MAX_STOP_ERROR_LINE_CHARS)}…`
+                                : lastErrorLine}\n\nAnything completed before this is saved.`,
                         errorCode: "repeated_tool_error_across_arguments",
                         details: sanitizedResult,
                     };
@@ -4955,6 +5088,7 @@ export async function runAgentLoop(opts) {
                 let toolResultImages;
                 let toolArtifacts = [];
                 let fileMutation;
+                let receipt;
                 try {
                     // The run may have been aborted while we waited above for an
                     // interrupted tool's ledger result (the wait can poll for minutes).
@@ -5083,6 +5217,8 @@ export async function runAgentLoop(opts) {
                         }
                     }
                     chatUIResult = resultForAgent;
+                    // Before stringify and truncation: a large result must not lose it.
+                    receipt = readWriteReceipt(resultForAgent);
                     toolArtifacts = detectArtifactReceipts(resultForAgent, toolCall.name);
                     if (toolResultImages) {
                         imageNotes = [
@@ -5090,6 +5226,18 @@ export async function runAgentLoop(opts) {
                             ...imageNotes,
                         ];
                     }
+                    let toolSearch;
+                    if (toolCall.name === TOOL_SEARCH_ACTION_NAME && !isError) {
+                        const matched = extractToolSearchResultNames(rawForAgent);
+                        const { added, overflow } = expandActiveTools(matched, toolNamesLoadedThisStep);
+                        for (const name of added)
+                            toolNamesLoadedThisStep.add(name);
+                        const loadedThisStep = matched.filter((name) => toolNamesLoadedThisStep.has(name));
+                        toolSearch = { matched, overflow, loadedThisStep };
+                        if (matched.length > 0) {
+                            resultForAgent = withLoadedToolNames(rawForAgent, loadedThisStep);
+                        }
+                    }
                     let resultStr = typeof resultForAgent === "string"
                         ? resultForAgent
                         : JSON.stringify(resultForAgent, null, 2);
@@ -5101,10 +5249,63 @@ export async function runAgentLoop(opts) {
                         resultStr = `${resultStr}\n\n${imageNotes.join("\n")}`;
                     }
                     result = resultStr;
-                    if (toolCall.name === TOOL_SEARCH_ACTION_NAME && !isError) {
-                        const added = expandActiveTools(extractToolSearchResultNames(rawForAgent));
-                        if (added.length > 0) {
-                            result += `\n\nLoaded matching tool schemas for next step: ${added.join(", ")}`;
+                    if (toolSearch) {
+                        const { matched, overflow, loadedThisStep } = toolSearch;
+                        const loadedNote = `Loaded matching tool schemas for the next step, not this one: ${loadedThisStep.join(", ")}`;
+                        if (loadedThisStep.length > 0) {
+                            result += `\n\n${loadedNote}`;
+                            alreadyLoadedToolSearches = 0;
+                        }
+                        else if (matched.length > 0 &&
+                            matched.every((name) => activeToolNames.has(name))) {
+                            const priorMessage = rawForAgent
+                                .message;
+                            result = JSON.stringify({
+                                ...resultForAgent,
+                                alreadyLoaded: true,
+                                message: [
+                                    `All ${matched.length} matches are already callable; call them directly.`,
+                                    typeof priorMessage === "string" ? priorMessage : "",
+                                ]
+                                    .filter(Boolean)
+                                    .join(" "),
+                            }, null, 2);
+                            // One count per step, reset by any progress: parallel searches
+                            // are one repeat, and a run that searches between writes is not
+                            // repeating.
+                            if (!countedAlreadyLoadedSearchThisStep) {
+                                countedAlreadyLoadedSearchThisStep = true;
+                                alreadyLoadedToolSearches += 1;
+                            }
+                            if (alreadyLoadedToolSearches >= MAX_ALREADY_LOADED_TOOL_SEARCHES) {
+                                requestedActionStop ??= {
+                                    message: `Stopped because tool-search was used ${alreadyLoadedToolSearches} times in a row to look for tools that were already callable, ` +
+                                        "which means the same step is repeating rather than making progress. " +
+                                        "Everything completed before this point is preserved above.",
+                                    errorCode: "repeated_tool_call",
+                                };
+                            }
+                        }
+                        if (overflow.length > 0) {
+                            const shown = overflow.slice(0, MAX_TOOL_SEARCH_OVERFLOW_NAMES_SHOWN);
+                            const more = overflow.length > shown.length
+                                ? `, and ${overflow.length - shown.length} more`
+                                : "";
+                            const overflowNote = `Could not load ${overflow.length} matched ${overflow.length === 1 ? "tool" : "tools"} because the per-request tool limit (${MAX_PROVIDER_TOOLS}) was reached: ${shown.join(", ")}${more}. They are not callable; use tools you already have.`;
+                            // A repeated search's own message says its matches are
+                            // available, which these are not.
+                            result =
+                                rawForAgent.repeated === true
+                                    ? JSON.stringify({
+                                        ...resultForAgent,
+                                        message: [
+                                            loadedThisStep.length > 0 ? loadedNote : "",
+                                            overflowNote,
+                                        ]
+                                            .filter(Boolean)
+                                            .join(" "),
+                                    }, null, 2)
+                                    : `${result}\n\n${overflowNote}`;
                         }
                     }
                 }
@@ -5168,12 +5369,25 @@ export async function runAgentLoop(opts) {
                     writeToolInterruptions.set(key, (writeToolInterruptions.get(key) ?? 0) + 1);
                 }
                 if (isError) {
+                    receipt = undefined;
                     if (result !== INTERRUPTED_TOOL_RESULT_MARKER) {
                         result = finalizeToolErrorResult(result);
                     }
                 }
                 else {
                     fileMutation = actionEntry.fileMutationProof?.(toolCall.input);
+                    // Only a write or a receipt is progress; a read-only call between
+                    // redundant searches is the same repeating step.
+                    if (!actionIsReadOnly || receipt)
+                        alreadyLoadedToolSearches = 0;
+                    if (receipt && receipt.verified !== true) {
+                        usage.receiptUnverifiedCount =
+                            (usage.receiptUnverifiedCount ?? 0) + 1;
+                    }
+                    if (receipt && !receipt.changed) {
+                        usage.receiptChangedFalseCount =
+                            (usage.receiptChangedFalseCount ?? 0) + 1;
+                    }
                 }
                 const agentWarnings = drainAgentWarnings();
                 if (agentWarnings.length > 0) {
@@ -5207,16 +5421,18 @@ export async function runAgentLoop(opts) {
                     ...(isError ? { isError: true } : {}),
                     ...(isError
                         ? { completedSideEffect: false }
-                        : !actionIsReadOnly
-                            ? { completedSideEffect: true }
-                            : {}),
+                        : receipt
+                            ? { completedSideEffect: receipt.changed }
+                            : !actionIsReadOnly
+                                ? { completedSideEffect: true }
+                                : {}),
                     ...(mcpApp ? { mcpApp } : {}),
                     ...(resolvedChatUI ? { chatUI: resolvedChatUI.chatUI } : {}),
                     ...(resolvedChatUI ? { chatUIResult: resolvedChatUI.result } : {}),
                     ...(fileMutation ? { fileMutation } : {}),
                     ...(toolArtifacts.length > 0 ? { artifacts: toolArtifacts } : {}),
                 });
-                recordToolResult(result, isError, toolArtifacts);
+                recordToolResult(result, isError, toolArtifacts, receipt);
                 if (!isError) {
                     noteToolCallSucceeded(actionEntry);
                     if (cacheKey) {
@@ -5675,26 +5891,7 @@ export async function runAgentLoopWithMainChatInternalContinuations(opts) {
         engineName: opts.engine.name,
         model: opts.model,
     };
-    const addUsage = (next) => {
-        usage.inputTokens += next.inputTokens;
-        usage.outputTokens += next.outputTokens;
-        usage.cacheReadTokens += next.cacheReadTokens;
-        usage.cacheWriteTokens += next.cacheWriteTokens;
-        if (next.builderCreditsUsed !== undefined) {
-            usage.builderCreditsUsed =
-                (usage.builderCreditsUsed ?? 0) + next.builderCreditsUsed;
-        }
-        usage.engineName = next.engineName ?? usage.engineName;
-        usage.model = next.model;
-        if (typeof next.llmCalls === "number") {
-            usage.llmCalls = (usage.llmCalls ?? 0) + next.llmCalls;
-        }
-        if (next.usageReported)
-            usage.usageReported = true;
-        // Keep the earliest attempt's first event — a later continuation
-        // attempt starting fresh must not overwrite genuine first-token timing.
-        usage.firstEngineEventAtMs ??= next.firstEngineEventAtMs;
-    };
+    const addUsage = (next) => mergeAgentLoopUsage(usage, next);
     const budgetStartedAt = opts.budgetStartedAt ?? Date.now();
     const resumeResumableErrorsInProcess = opts.resumeResumableErrorsInProcess === true;
     const maxContinuations = typeof opts.maxContinuations === "number" && opts.maxContinuations > 0
@@ -6832,21 +7029,14 @@ export function createProductionAgentHandler(options) {
         const storedModel = !requestModelIsExplicit && !configuredModelIsExplicit
             ? await getStoredModelForEngine(engine, { appId: options.appId })
             : undefined;
-        const modelSelection = resolveAgentModelSelection({
+        const modelSelection = await applyUncheckedDefaultModelReplacement(engine, resolveAgentModelSelection({
             requestModel,
             configuredModel,
             storedModel,
             defaultModel: engine.defaultModel,
-        });
-        // Only the engine default yields to the provider's checked models. A model
-        // the request or a stored default names still runs after it is unchecked,
-        // so chats already on it keep working.
-        const modelCandidate = modelSelection.source === "default"
-            ? ((await resolveUncheckedDefaultModelReplacement(engine)) ??
-                modelSelection.model)
-            : modelSelection.model;
+        }));
         workerStep("model_done");
-        const model = normalizeModelForEngine(engine, modelCandidate);
+        const model = normalizeModelForEngine(engine, modelSelection.model);
         let effectiveModel = model;
         let modelSelectionSource = modelSelection.source;
         const turnUsageLabel = normalizeUsageLabel(body.usageLabel);