agent-nuvira 3.3.13 → 3.3.15

package/dist/tools/tool-loop.js

@@ -15,7 +15,8 @@
  * - JSON fallback: the model emits `{"tool":"<name>","arguments":{...}}`
  *   blocks after its response text (contract in TOOL_CONTRACT_JSON).
  */
-import { getTool, toolJsonSchemas } from './registry.js';
+import { getTool, listTools, toolJsonSchemas } from './registry.js';
+import { effectClassOfTool } from './capability-registry.js';
 // A1 — build-command recognition, shared with effect verification so "a build"
 // means the same thing to both the launch check and the honesty guard.
 import { isBuildCommand } from '../utils/effect-verification.js';
@@ -29,6 +30,10 @@ import { runBeforeToolHooks, runToolOutcomeHooks, toolHookRefusalText, } from '.
 // when the run is a resume; `stepDigest` is over the whole input, so a step whose
 // thread or tool schema changed MISSES and is paid for again (see the module).
 import { stepDigest } from '../learning/step-checkpoint.js';
+// P7 — the identical-command guard's memory. The loop drops it when a WRITE is
+// applied, so a repaired project can re-run its own check (see the context below).
+import { resetTerminalFailureStreaks } from './run-terminal.js';
+import { createRunCommandMemo } from './command-memo.js';
 // WS6 (#28) — the declared fault seam. `faultAt` is a null check when this
 // process declared no fault (`NUVIRA_INJECT_FAULT`), so an ordinary turn is
 // unaffected.
@@ -37,6 +42,8 @@ import { detectPermissionSeeking, isAffirmativeReply, replyAsksTheReader, reques
 import { envelopeFromPlan, envelopeFromRequest, getEnvelope, grantEnvelope, isEnvelopeKey, } from '../learning/intent-envelope.js';
 import { detectProcessComplaint, isTraceKey, noProgressNudge, repeatNudge, repeatedFailureNudge, runTraceFor, RunTrace, } from '../learning/run-trace.js';
 import { wantsAuthoredArtifact } from '../learning/deliverable-class.js';
+import { isAuthoredReadBack } from '../learning/turn-report.js';
+import { parseLongFormTarget, countWords } from '../learning/long-form.js';
 import { normalizeFollowups } from './followup-utils.js';
 // The capability mode (balanced | max) — `max` widens the loop's own reasoning
 // budget as well as routing, so "cost is not a concern" means the agent may
@@ -46,6 +53,7 @@ import { isMaxCapability } from '../config/capability-mode.js';
 // compaction digest is injected in every mode, only under `max`, or never.
 import { isWorkDigestEnabled } from '../config/work-digest.js';
 import { assessEditActivity, detectUnverifiedEditClaim, isVerificationTool, verificationNudgeFor, THINK_ONLY_ESCALATION, AUTHORIZED_WORK_NUDGE, deliverableNudge, } from './edit-verification.js';
+import { createHarnessDirectiveSink } from './harness-directive.js';
 import { effectiveToolJsonSchemas, coreToolJsonSchemas, isToolEnabled, toolsetForTool } from './toolsets.js';
 import { deliverablesNamedIn, recordStepHandoff } from '../agents/step-handoff.js';
 import { fenceUntrustedToolOutput } from './untrusted-content.js';
@@ -254,6 +262,15 @@ export function extractFallbackToolCalls(content) {
             // A QUOTED tool block with no closing brace: the model was cut off
             // mid-call. Everything from the marker on is leaked scaffolding, not
             // answer text — strip it and stop (nothing valid can follow).
+            //
+            // Item 6 — surface it as an UNPARSEABLE call when we saw the tool's name,
+            // so the loop refuses it with the truncation cause and the sectioned path.
+            // Dropping it silently (the old behaviour) is how a cut-off delivery failed
+            // with nothing to tell the model why.
+            const name = /^\s*\(?\s*\{\s*"tool"\s*:\s*"([^"]+)"/.exec(cleaned.slice(m.index))?.[1];
+            if (name) {
+                calls.push({ id: `call_${calls.length + 1}`, name, arguments: {}, argumentsError: 'unparseable' });
+            }
             cleaned = cleaned.slice(0, m.index);
             strippedAny = true;
             break;
@@ -269,15 +286,25 @@ export function extractFallbackToolCalls(content) {
         try {
             const parsed = JSON.parse(block);
             if (parsed.tool && typeof parsed.tool === 'string') {
+                // Item 6 — the fallback transport is TEXT, so "did the arguments arrive?"
+                // is decided HERE. A block that parses but carries no `arguments` object
+                // is the empty-payload signature; flagging it lets the loop refuse it with
+                // the REAL cause instead of executing `{}` and answering "path is required".
+                const rawArgs = parsed.arguments;
+                const isPlainObject = rawArgs !== null && typeof rawArgs === 'object' && !Array.isArray(rawArgs);
                 calls.push({
                     id: `call_${calls.length + 1}`,
                     name: parsed.tool,
-                    arguments: parsed.arguments && typeof parsed.arguments === 'object' ? parsed.arguments : {},
+                    arguments: isPlainObject ? rawArgs : {},
+                    ...(isPlainObject ? {} : { argumentsError: rawArgs === undefined ? 'empty' : 'unparseable' }),
                 });
             }
         }
         catch {
-            // Unparseable block — dropped from the answer, no tool call.
+            // A brace-MATCHED but unparseable block (the model's own JSON typo, e.g. a
+            // trailing comma) is dropped from the answer, no call — a truncation has no
+            // closing brace and is handled above. Item 6 covers the truncated case there;
+            // this stays silent by design so a typo cannot become a phantom refusal.
         }
     }
     // ── Pass 2: our tool's ARGUMENTS keyed by our own tool NAME ─────────────
@@ -387,31 +414,51 @@ function findMatchingBrace(text, start) {
 }
 // ─── Parallel read-only execution (W2) ──────────────────────────────────────
 /**
- * Tools that are READ-ONLY and therefore safe to execute concurrently when the
- * model emits several of them in ONE step. Everything else — writes, terminal
- * commands, pipeline dispatch, delegation, `tool_search` (it mutates the
- * tiering state), `plan_todo`, `ask_user` (it blocks on user input) — stays
- * strictly serial and in the model's original order.
+ * Tools that READ the world but must still run SERIALLY, because they change
+ * HARNESS state or block on input rather than changing the world.
  *
- * Why this matters: tool results are fed back one step at a time and the step
- * budget is bounded (16), so N independent reads used to cost N sequential
- * round-trips of wall-clock. Reading several files/searches is the single most
- * common investigation pattern, so it becomes one bounded fan-out.
+ * `effectClass: 'read'` is NECESSARY but NOT SUFFICIENT for safe fan-out — this is
+ * the second half of the fact, and it is a property of the HARNESS, not of the
+ * effect. `tool_search` mutates the tiering state that decides which tools exist
+ * in the NEXT step; `ask_user` blocks on the human. Fanning either out would let
+ * two siblings disagree about the world they are reading.
  *
- * The list is deliberately an ALLOWLIST (never a denylist): a tool added to
- * the registry later is SERIAL by default until it is reviewed as read-only.
- */
-export const PARALLEL_SAFE_TOOL_NAMES = new Set([
-    'read_file',
-    'list_dir',
-    'glob',
-    'code_search',
-    'web_search',
-    'read_page',
+ * Pinned by `parallel-tool-exec.test.ts`, which asserts each of these is serial
+ * WHILE its declared effect is genuinely `read`.
+ */
+const READ_BUT_SERIAL = new Set([
+    'tool_search', // mutates the tiering state
+    'ask_user', // blocks on user input
 ]);
-/** Whether a tool may run concurrently with sibling calls in the same step. */
+/**
+ * Whether a tool may run concurrently with sibling calls in the same step.
+ *
+ * DERIVED FROM THE CAPABILITY REGISTRY, not a hand-maintained allowlist. This used
+ * to be a six-name list that had to be reviewed by hand whenever a read tool was
+ * added — so any new read tool, and every read-only MCP tool discovered at
+ * runtime, silently lost the fan-out. The effect class answers it now.
+ *
+ * THE SAFETY DIRECTION IS UNCHANGED, which is the part that matters: a tool the
+ * registry does not describe maps to `local-state`, so a newly registered tool is
+ * still SERIAL until someone declares it a read. `READ_BUT_SERIAL` is the one
+ * hand-written exception, and it is a harness fact rather than an effect guess.
+ */
 export function isParallelSafeTool(name) {
-    return PARALLEL_SAFE_TOOL_NAMES.has(name);
+    if (READ_BUT_SERIAL.has(name))
+        return false;
+    return effectClassOfTool(name) === 'read';
+}
+let _parallelSafeNames = null;
+/**
+ * Every REGISTRY tool that currently qualifies, derived by filtering with
+ * `isParallelSafeTool` — so the set and the predicate can never disagree. Built
+ * lazily, because the registry must be fully loaded before it can be enumerated.
+ */
+export function parallelSafeToolNames() {
+    if (!_parallelSafeNames) {
+        _parallelSafeNames = new Set(listTools().map((t) => t.name).filter(isParallelSafeTool));
+    }
+    return _parallelSafeNames;
 }
 /** Max concurrent read-only calls per step (bounded fan-out) when the model
  *  has no harness opinion — see `ModelHarnessProfile.maxParallelReads`, which
@@ -434,6 +481,36 @@ const MAX_PARALLEL_READS = 4;
  * were well able to do (see `THINK_ONLY_ESCALATION`).
  */
 export const MAX_THINK_CONTINUES = 3;
+/**
+ * P2 — how many times the SAME model may answer with nothing before the loop
+ * insists on a handoff. One, deliberately: a single empty completion can be a
+ * blip at a shared endpoint, but a model that resolves with nothing twice has
+ * demonstrated it is not answering this step, and re-calling it is the loop that
+ * killed a real turn (five consecutive empties, then the turn reported itself
+ * bounded with zero tool calls).
+ */
+export const MAX_SAME_MODEL_EMPTY_RETRIES = 1;
+/**
+ * P2 — ceiling on mid-turn handoffs, so a caller whose pool churns through
+ * unusable models cannot spin. Each handoff is a genuinely different candidate
+ * (the caller must refuse to hand back the same pair), so this only bounds a
+ * pathological pool; a real one is exhausted well before it.
+ */
+export const MAX_MODEL_HANDOFFS_PER_TURN = 5;
+/**
+ * P3 — the turn's ATTEMPT budget, kept separate from its STEP budget.
+ *
+ * A mid-turn handoff spends model calls that produced nothing: the empty
+ * completion that triggered it, and the first call to the replacement (which
+ * may itself come back empty). Charging those to the same budget that governs
+ * the actual WORK means a run against two or three dead models exhausts its
+ * road before it has done anything — the exact way a task gets abandoned while
+ * capable models are still queued. Each handoff therefore GRANTS two extra
+ * steps of credit (capped), so hand-offs cannot be cut short by step
+ * accounting; everything else — the step budget, the continuation budget, the
+ * think-only cap — is untouched.
+ */
+export const MAX_HANDOFF_ATTEMPT_CREDIT = MAX_MODEL_HANDOFFS_PER_TURN * 2;
 /**
  * Consecutive steps that RAN tools and had NO success before the loop asks the
  * model to diagnose the stall. This generalises {@link RunTrace.repeatedFailure}
@@ -533,6 +610,21 @@ async function runToolLoopInner(opts, progress) {
     // Bounded think-only continuation (see THINK_ONLY_ESCALATION). Counts the
     // consecutive reasoning-only steps so the loop cannot spin on them.
     let thinkContinues = 0;
+    // P2 — empty-response accounting. `emptyRetriesOnCurrentModel` is the streak
+    // of usable-nothing responses from the model currently serving the turn; it
+    // resets the moment that model produces anything usable (or is replaced), so
+    // "twice in a row" means twice in a row from THAT model. `modelHandoffs`
+    // bounds how many times the turn may move.
+    let emptyRetriesOnCurrentModel = 0;
+    let modelHandoffs = 0;
+    // P3 — the ATTEMPT budget (see MAX_HANDOFF_ATTEMPT_CREDIT): step credit
+    // granted by mid-turn handoffs, so a run against several dead models cannot
+    // exhaust its road before it has done any work.
+    let handoffAttemptCredit = 0;
+    // Why the turn is ending. The two `break`s in the empty/think-only path mean
+    // opposite things (a model shortage vs. one model spinning), so the reason is
+    // recorded explicitly rather than re-derived at the exit.
+    let exitTermination = null;
     // G13b — bounded "the request asked for a file and none was written" nudges
     // (see wantsAuthoredArtifact).
     let deliverableNudges = 0;
@@ -561,6 +653,12 @@ async function runToolLoopInner(opts, progress) {
     const maxParallelReads = Math.max(1, opts.maxParallelReads ?? MAX_PARALLEL_READS);
     const followups = [];
     const toolCallsRun = [];
+    // A call whose arguments never ARRIVED is not a call the model made: it is a
+    // payload that did not fit in one model output (measured: 59 of them in one
+    // turn). Counted per turn so the loop can escalate, and once-nudged so the
+    // escalation itself cannot loop.
+    let malformedToolCalls = 0;
+    let malformedCallNudges = 0;
     // S5 — the plan_todo loop guard is split by ACTION (see the guard below):
     // repeated CREATES were the observed planner loop; UPDATES are the tracking
     // that keeps the user's checklist honest. Counted across the whole turn, like
@@ -633,8 +731,31 @@ async function runToolLoopInner(opts, progress) {
     // so a `finding` in the same step can check its cited command/path against
     // what really happened (see `enforceEvidenceProvenance`).
     const executedActions = progress.executedActions;
+    // P7 — a WRITE makes the world different, so a command that already failed may
+    // now succeed. `run_terminal`'s identical-command guard exists to stop blind
+    // repeats (the live run burned three back-to-back attempts), but a repaired
+    // project re-running its own check is the ONE case that must never be refused:
+    // with the guard's cap, that call would be rejected before it could ever
+    // succeed and clear the streak — a deadlock where a fixed project could not
+    // run its check again. Every tool that mutates the workspace announces it on
+    // `autonomy:write-applied`, so the streak is dropped exactly when something
+    // changed, and a blind repeat at the same timeout still counts.
+    //
+    // `run_terminal` announces on the SAME event when IT proceeds autonomously, but
+    // that is a statement about its own command, not a change to the world — letting
+    // it invalidate the streak would mean the guard could never accumulate on the
+    // exact commands it exists for. Payloads name their emitter, so its event is
+    // excluded by name while any other write (write_file, edit_file, git, …) counts.
+    const baseEmit = context.emit;
+    const emitWithWriteInvalidation = (event, data, source) => {
+        if (event === 'autonomy:write-applied' && data?.tool !== 'run_terminal') {
+            resetTerminalFailureStreaks();
+        }
+        baseEmit?.(event, data, source);
+    };
     const ctx = {
         ...context,
+        emit: emitWithWriteInvalidation,
         followups: context.followups || sink,
         executedActions,
         writesAuthorized: authorization,
@@ -648,6 +769,15 @@ async function runToolLoopInner(opts, progress) {
         // The run's own behaviour, so a gate can refuse to RE-ASK a question the
         // user already answered (see learning/run-trace.ts).
         runTrace,
+        // C3 — the commands THIS run already answered.
+        //
+        // Created here, so its lifetime is exactly the tool loop's: one answer's
+        // worth of steps, discarded after. That is the honest granularity — a probe
+        // (`node --version`) is a fact about this run's environment, while
+        // idempotent setup (`mkdir -p out`) is only safely skippable while the run
+        // that created the directory is still going. A caller may inject its own
+        // memo (a test, or a longer-lived session scope), and then it is honoured.
+        commandMemo: context.commandMemo ?? createRunCommandMemo(),
     };
     // Resolve the tool set — stable JSON schemas for every native step
     // (derived from the registry's zod schemas, single source of truth).
@@ -703,8 +833,29 @@ async function runToolLoopInner(opts, progress) {
         return added;
     };
     const thread = [...messages];
+    // Every harness-authored nudge is delivered through ONE channel: a marked
+    // `system` directive that the model ACTS ON, deduped by gate within the turn,
+    // instead of a `user` message it answers (see tools/harness-directive.ts).
+    const harness = createHarnessDirectiveSink();
     /** Serving pairs the loop has already told the model about, oldest first. */
     const routeFeedState = { pairs: [] };
+    // ── C4 residual: the plan the conversation ALREADY has is shown, not hidden ──
+    // The C4 experiment measured the shape of this failure: the plan store keeps the
+    // plan (and now carries its progress across a re-declaration), but the model was
+    // never SHOWN it — the store was read only to answer "does a plan exist". So a
+    // later turn could not reference "step 3 is done" (which the tool's own
+    // description promises) and re-declared the plan instead. Handing the plan back
+    // at the top of every turn makes the carried progress visible and names the one
+    // correct move (update), instead of relying on the model to guess that a plan is
+    // already tracked.
+    //
+    // Bounded, and only when there is work left: a finished plan is not re-shown, and
+    // a long plan is capped rather than allowed to dominate the context it exists to
+    // protect.
+    const existingPlan = context.planStore?.snapshot?.() ?? null;
+    if (existingPlan && existingPlan.steps.length > 0 && existingPlan.steps.some((s) => s.status !== 'done')) {
+        thread.push({ role: 'system', content: planContextBlock(existingPlan) });
+    }
     // ── Stage 2: answer a question ABOUT the run from the run ────────────────
     // The live audit's worst moment was the user asking "why are you asking me
     // this again and again?" and the turn replying with an edit plan — not through
@@ -727,7 +878,9 @@ async function runToolLoopInner(opts, progress) {
                 'instead. Do not answer a question about your own process with a plan for the work.',
         });
     }
-    const budgetChars = opts.threadBudgetChars ?? DEFAULT_THREAD_BUDGET_CHARS;
+    // C5 — `let`, not `const`: a mid-turn handoff can install a different model, and
+    // the budget must follow it (see `threadBudgetAfterSwitch`).
+    let budgetChars = opts.threadBudgetChars ?? DEFAULT_THREAD_BUDGET_CHARS;
     // P3d — per-turn parallel suggester: after 2+ successful independent gather
     // steps, one advisory delegate suggestion fires (bounded, deterministic).
     const parallel = makeParallelSuggester();
@@ -744,6 +897,38 @@ async function runToolLoopInner(opts, progress) {
     // clobber it — otherwise the delivered answer is lost and the turn ends
     // with an empty/bounded response (the "where is the essay?" bug).
     let lastContent = '';
+    /**
+     * How many PRODUCTIVE actions had SUCCEEDED when `lastContent` was written.
+     *
+     * WHY THIS EXISTS (D1 — the delivered answer contradicted the run's own
+     * evidence). `lastContent` used to be replaced only when the new text was at
+     * least as long, so the delivered answer was the LONGEST text of the turn —
+     * and the model's own later correction could never take over. Measured in
+     * `trace-1791300903944-upblb7` (an 82-step run): the longest step was **seq 65
+     * (4,024 chars)** — the "Built and verified. Here's the rundown." draft — while
+     * seq 80 ("Hold on — that README note claims `sentence-transformers` needs a
+     * `torch` build, but I never actually tested that install. Let me check rather
+     * than assert.") and seq 82 ("My README claim was **wrong** — torch-2.14.1 and
+     * sentence-transformers-6.1.0 do resolve…") are 155 and 165 chars. Both are
+     * corrections of the draft, both are shorter, so the run delivered the draft
+     * and the user read an assertion the agent had already disproved itself.
+     *
+     * The rule the length check was reaching for is "a trailing WRAPPER must not
+     * clobber the essay". Length is the wrong proxy for that, because a correction
+     * is also short. What actually separates them is whether the turn DID something
+     * in between: text written after real work is an account of a LATER state and
+     * supersedes; a closing paragraph written with no work since is presentation.
+     * So a later answer wins when real work happened after the stored one.
+     *
+     * The presentation calls in `NON_PRODUCTIVE_TOOLS` are excluded on purpose —
+     * `suggest_followups` is what the end-of-response contract forces, it changes
+     * nothing, and it is precisely the call that produces the trailing wrapper
+     * this rule must still ignore (the same set `hasProductiveAction` uses, so the
+     * two cannot drift).
+     */
+    let workCallsBeforeLastContent = 0;
+    /** A capture happened this step; stamp it at the top of the NEXT one (see below). */
+    let pendingContentStamp = false;
     let bounded = false;
     // D2.2 — has this turn already pre-flighted the project's build prerequisites?
     // Checked once, before the FIRST build command the turn plans to run.
@@ -784,7 +969,7 @@ async function runToolLoopInner(opts, progress) {
         // many-file edit). Extend the budget a bounded number of times and keep
         // the SAME thread — completed tool calls are never re-run — instead of
         // telling the user "I reached my step limit" with the task unfinished.
-        if (steps >= stepLimit) {
+        if (steps >= stepLimit + handoffAttemptCredit) {
             if (continuations < maxContinuations) {
                 continuations += 1;
                 stepLimit += continuationSteps;
@@ -796,9 +981,23 @@ async function runToolLoopInner(opts, progress) {
         // P4 — check cancellation BEFORE each step (a pre-aborted signal never
         // spends a model call) and after tool executions (below).
         if (opts.signal?.aborted) {
-            return { content: '', followups, toolCalls: toolCallsRun, steps, ...(opts.resume ? { replayedSteps } : {}), bounded: false, cancelled: true };
+            return { content: '', followups, toolCalls: toolCallsRun, steps, ...(opts.resume ? { replayedSteps } : {}), bounded: false, cancelled: true, termination: 'cancelled' };
         }
         steps += 1;
+        // D1 — the work completed BEFORE this step's response is written. Snapshotted
+        // at the TOP of the iteration, where the previous step's tool calls have
+        // already run and been counted, so a step's OWN tool calls can never make its
+        // own answer look superseded by the next step's closing wrapper. See
+        // `workCallsBeforeLastContent`.
+        const workAtIterationStart = countProductiveWork(progress);
+        // Stamp an answer captured LAST step with the work count as of the END of that
+        // step. Doing it here (rather than at capture) is what keeps a step's OWN tool
+        // calls from making its own answer look superseded: the essay step that also
+        // wrote a file must not be replaced by the closing paragraph written next.
+        if (pendingContentStamp) {
+            workCallsBeforeLastContent = workAtIterationStart;
+            pendingContentStamp = false;
+        }
         // Mechanical thread budget: trim BEFORE the model call so a provider
         // request never exceeds the window (deterministic — no LLM summarizer,
         // no latency, no drift; see trimThreadBudget).
@@ -871,7 +1070,7 @@ async function runToolLoopInner(opts, progress) {
             // generation failure: the caller discards the turn. No error text, no
             // fallback — the fetch itself aborted on the caller's signal.
             if (opts.signal?.aborted) {
-                return { content: '', followups, toolCalls: toolCallsRun, steps, ...(opts.resume ? { replayedSteps } : {}), bounded: false, cancelled: true };
+                return { content: '', followups, toolCalls: toolCallsRun, steps, ...(opts.resume ? { replayedSteps } : {}), bounded: false, cancelled: true, termination: 'cancelled' };
             }
             // Generation failure — surface what we have rather than crash the turn.
             // generationFailed is TRUE only when NOTHING happened yet (no content, no
@@ -936,6 +1135,10 @@ async function runToolLoopInner(opts, progress) {
                 ...(opts.resume ? { replayedSteps } : {}),
                 bounded: false,
                 continuations,
+                ...(modelHandoffs > 0 ? { modelHandoffs } : {}),
+                // Nothing to deliver means the provider walk itself gave up — every
+                // candidate was tried and none answered. That IS the evidenced shortage.
+                termination: delivered === '' ? 'no-capable-candidate' : 'delivered',
                 generationFailed: delivered === '' || !madeProgress,
             };
         }
@@ -970,10 +1173,21 @@ async function runToolLoopInner(opts, progress) {
         const responseThinkOnly = deps.isThinkOnly
             ? deps.isThinkOnly(response.content)
             : isThinkOnlyResponse(response.content);
-        if (response.content.trim() && !responseThinkOnly && response.content.length >= lastContent.length) {
+        const responseIsSubstantive = response.content.trim() !== '' && !responseThinkOnly && !isBareAcknowledgment(response.content);
+        const workSinceLastContent = workAtIterationStart > workCallsBeforeLastContent;
+        if (responseIsSubstantive && (response.content.length >= lastContent.length || workSinceLastContent)) {
             lastContent = response.content;
+            // Stamp what this answer is an account OF, so the next step can tell an
+            // update from a wrapper (see `workCallsBeforeLastContent`). Deferred to the
+            // top of the next iteration so it includes THIS step's own work.
+            pendingContentStamp = true;
         }
         const { toolCalls } = response;
+        // P2 — the model just produced something usable (text, or at least one tool
+        // call), so its empty-response streak is over: a later blip starts a NEW
+        // streak rather than inheriting one from twenty steps ago.
+        if (toolCalls.length > 0 || !responseThinkOnly)
+            emptyRetriesOnCurrentModel = 0;
         if (toolCalls.length === 0) {
             // No tools → end turn UNLESS the content is think-only (
             // isThinkOnlyResponse: continue instead of ending).
@@ -994,6 +1208,86 @@ async function runToolLoopInner(opts, progress) {
                 // is the exact class of defect this work exists to remove, so the two
                 // cases are named apart even though they are bounded together.
                 const emptyResponse = response.content.trim().length === 0;
+                // ── P2 — MID-TURN MODEL HANDOFF ────────────────────────────────────
+                // An empty completion is a PROVIDER failure, not a state of mind, and
+                // re-asking the model that just returned nothing is what killed a real
+                // run: five consecutive empties from one model, then `bounded: true`
+                // with zero tool calls, while healthy models sat configured and unused.
+                // So once THIS model has had its single retry, the loop asks the caller
+                // for a different candidate. The caller owns the pool (exclusions,
+                // credentials, cooldowns) and refuses to hand back the same pair; a
+                // `false` means there is genuinely nothing else, and we fall through to
+                // the bounded escalation below — unchanged behaviour for a turn with no
+                // alternative (and for every caller that supplies no hook at all).
+                if (emptyResponse &&
+                    deps.requestModelSwitch &&
+                    modelHandoffs < MAX_MODEL_HANDOFFS_PER_TURN &&
+                    emptyRetriesOnCurrentModel >= MAX_SAME_MODEL_EMPTY_RETRIES) {
+                    let switched = false;
+                    try {
+                        switched = (await deps.requestModelSwitch('empty')) === true;
+                    }
+                    catch {
+                        // A broken switch hook must never kill the turn — fall through to the
+                        // bounded path exactly as if it had answered `false`.
+                        switched = false;
+                    }
+                    if (switched) {
+                        modelHandoffs += 1;
+                        // ── C5 — RE-FIT THE THREAD TO THE MODEL THAT NOW ANSWERS ──────
+                        // `budgetChars` was resolved before this loop started, from the pair
+                        // the turn BEGAN on — and the handoff worth catching is the one to a
+                        // SMALLER window, which is precisely the case that overflows. The
+                        // caller knows the session, so it re-resolves; `undefined` keeps the
+                        // budget (an unknown window must not silently shrink the thread).
+                        // The trim runs at the TOP of the next iteration, before the call, so
+                        // a NEW budget is applied to the very next request — and when it is
+                        // smaller, that trim is what makes the handoff fit.
+                        const refitted = deps.threadBudgetAfterSwitch?.();
+                        if (typeof refitted === 'number' && refitted > 0 && refitted !== budgetChars) {
+                            deps.onEvent?.(`   📐 thread budget re-fitted for the handoff model: ` +
+                                `${Math.round(budgetChars / 1000)}K → ${Math.round(refitted / 1000)}K chars.`);
+                            budgetChars = refitted;
+                        }
+                        // P3 — the ATTEMPT budget: the empty completion that triggered this
+                        // handoff, and the first call to the replacement model, are not the
+                        // user's work — grant the step credit so a run against a couple of
+                        // dead models cannot exhaust its road before it has done anything.
+                        handoffAttemptCredit = Math.min(MAX_HANDOFF_ATTEMPT_CREDIT, handoffAttemptCredit + 2);
+                        // The streak and the think streak belong to the model that failed.
+                        emptyRetriesOnCurrentModel = 0;
+                        thinkContinues = 0;
+                        // ── DROP THE FAILED MODEL'S PRIVATE REASONING ─────────────────
+                        // Every assistant turn records `reasoningContent`, and the wire
+                        // layer echoes it back on that assistant message — which is
+                        // REQUIRED when the SAME model retries (some reasoning models fail
+                        // the request without their own prior reasoning; see
+                        // `reasoning-cache.ts`). After a HANDOFF the next model is a
+                        // DIFFERENT model, and replaying a stranger's chain-of-thought
+                        // either gets the request rejected by the target API (foreign
+                        // `reasoning_content` / tool-call ids) or anchors the new model to
+                        // the reasoning that already failed. Strip it on a pair change; a
+                        // same-model retry keeps it untouched, which is where the
+                        // requirement actually comes from.
+                        // NOTE: `thread` (the loop's own working copy, line ~1398), not
+                        // `messages` — the assistant turns live here.
+                        for (const prior of thread) {
+                            if (prior.role === 'assistant' && prior.reasoningContent) {
+                                delete prior.reasoningContent;
+                            }
+                        }
+                        deps.onEvent?.(`   🔀 That model returned nothing usable — handing the turn to a different model (handoff ${modelHandoffs}/${MAX_MODEL_HANDOFFS_PER_TURN}).`);
+                        traceEvent({
+                            kind: 'gate',
+                            gate: 'handoff',
+                            summary: `the provider returned an empty response twice — the turn handed off to a different model ` +
+                                `(handoff ${modelHandoffs}/${MAX_MODEL_HANDOFFS_PER_TURN}) instead of re-asking the same one`,
+                        });
+                        continue;
+                    }
+                }
+                if (emptyResponse)
+                    emptyRetriesOnCurrentModel += 1;
                 // BOUNDED (see THINK_ONLY_ESCALATION). Continuing on reasoning is right
                 // for a `<think>`-then-answer model and catastrophic without a limit:
                 // two live eval runs produced 31 reasoning-only steps, one tool call and
@@ -1024,13 +1318,18 @@ async function runToolLoopInner(opts, progress) {
                             : `the model produced reasoning-only output ${thinkContinues} times with no tool call and no answer — ` +
                                 'one bounded escalation to act or answer',
                     });
-                    thread.push({ role: 'user', content: THINK_ONLY_ESCALATION });
+                    harness.push(thread, 'think-only', THINK_ONLY_ESCALATION);
                     continue;
                 }
                 // Still spinning after the escalation: END the turn rather than burn the
                 // rest of the budget. `bounded` is set so every surface reads this as
-                // "stopped before finishing", never as a completed answer.
+                // "stopped before finishing", never as a completed answer — and P3 names
+                // WHICH kind of stop this is, because the two demand opposite responses:
+                // every model that answered returned nothing (a model shortage, which
+                // the caller must report as such) versus one model that kept thinking
+                // (a bounded stop that says nothing about the other models).
                 bounded = true;
+                exitTermination = emptyResponse ? 'no-capable-candidate' : 'reasoning-spin';
                 deps.onEvent?.(emptyResponse
                     ? '   ⚠️ Empty responses kept coming — ending the turn instead of spinning. This is a PROVIDER failure, not the agent thinking.'
                     : '   🧠 Reasoning-only output kept repeating — ending the turn instead of spinning.');
@@ -1071,11 +1370,8 @@ async function runToolLoopInner(opts, progress) {
                 // would outrank and suppress the nudge entirely.
                 lastContent = '';
                 thread.push({ role: 'assistant', content: response.content });
-                thread.push({
-                    role: 'user',
-                    content: 'You announced an action you were about to take, but no tool was called and nothing was done. ' +
-                        'Either carry it out now with the tools available, or reply with the actual answer — do not end the turn on a promise.',
-                });
+                harness.push(thread, 'promise', 'You announced an action you were about to take, but no tool was called and nothing was done. ' +
+                    'Either carry it out now with the tools available, or reply with the actual answer — do not end the turn on a promise.');
                 continue;
             }
             // ── G13 — AUTHORIZED-WORK nudge (bounded, once) ──────────────────────
@@ -1113,7 +1409,7 @@ async function runToolLoopInner(opts, progress) {
                     lastContent = stripTrailingPermissionSeek(response.content.length >= lastContent.length ? response.content : lastContent);
                 }
                 thread.push({ role: 'assistant', content: response.content });
-                thread.push({ role: 'user', content: AUTHORIZED_WORK_NUDGE });
+                harness.push(thread, 'permission', AUTHORIZED_WORK_NUDGE);
                 continue;
             }
             // ── Stage 2 — REPETITION nudge (bounded, once) ───────────────────────
@@ -1146,7 +1442,7 @@ async function runToolLoopInner(opts, progress) {
                     lastContent = stripTrailingPermissionSeek(closing);
                 }
                 thread.push({ role: 'assistant', content: response.content });
-                thread.push({ role: 'user', content: repeatNudge(closing, runTrace.priorAnswer(closing)) });
+                harness.push(thread, 'repeat', repeatNudge(closing, runTrace.priorAnswer(closing)));
                 continue;
             }
             // ── ZERO-ACTION gate (bounded, once) ────────────────────────────────
@@ -1172,7 +1468,7 @@ async function runToolLoopInner(opts, progress) {
                 // The non-answer must not become the delivered answer either way.
                 lastContent = '';
                 thread.push({ role: 'assistant', content: response.content });
-                thread.push({ role: 'user', content: zeroActionNudge(currentAsk(opts)) });
+                harness.push(thread, 'action', zeroActionNudge(currentAsk(opts)));
                 continue;
             }
             // S1 (both exits): the MOST SUBSTANTIVE content seen wins here too —
@@ -1197,7 +1493,7 @@ async function runToolLoopInner(opts, progress) {
                         : 'an authored deliverable was requested and no file was written — one bounded nudge to produce it',
                 });
                 thread.push({ role: 'assistant', content: response.content });
-                thread.push({ role: 'user', content: deliverableNudge(authorization.requestedPath) });
+                harness.push(thread, 'deliverable', deliverableNudge(authorization.requestedPath));
                 continue;
             }
             //
@@ -1225,10 +1521,7 @@ async function runToolLoopInner(opts, progress) {
                 // preference order. A live turn reached for `node -c` because the nudge
                 // left the choice to the model; `verificationNudgeFor` reads the
                 // workspace and asks for the real command, so there is nothing to guess.
-                thread.push({
-                    role: 'user',
-                    content: verificationNudgeFor(ctx.cwd ?? process.cwd(), progress.mutatedPaths),
-                });
+                harness.push(thread, 'verification', verificationNudgeFor(ctx.cwd ?? process.cwd(), progress.mutatedPaths));
                 continue;
             }
             // SELF-REVIEW (no-tools exit) — a substantial, already-verified turn is
@@ -1244,7 +1537,7 @@ async function runToolLoopInner(opts, progress) {
                     summary: 'a substantial turn that changed files reached its end — one bounded nudge to check the result against the original ask',
                 });
                 thread.push({ role: 'assistant', content: response.content });
-                thread.push({ role: 'user', content: review });
+                harness.push(thread, 'self-review', review);
                 continue;
             }
             return {
@@ -1255,6 +1548,8 @@ async function runToolLoopInner(opts, progress) {
                 ...(opts.resume ? { replayedSteps } : {}),
                 bounded: false,
                 continuations,
+                ...(modelHandoffs > 0 ? { modelHandoffs } : {}),
+                termination: 'delivered',
             };
         }
         // ── Execute tool calls (results fed back, next step) ──────────────
@@ -1286,6 +1581,9 @@ async function runToolLoopInner(opts, progress) {
         // their nudge into this queue and it is flushed after the results, keeping
         // the assistant→tool group intact. (Without this, a pinned/strict run died
         // on the third model call and looked like a provider fault.)
+        // Planning-time directives, flushed as harness directives once the step's
+        // tool-call group is complete. Kept as {gate, content} so the same channel
+        // (and the same per-turn dedupe) covers them.
         const deferredUserNudges = [];
         const plans = toolCalls.map((call) => {
             const tool = getTool(call.name);
@@ -1361,6 +1659,24 @@ async function runToolLoopInner(opts, progress) {
                         `Call tool_search with {"action":"load","toolset":"${ownerToolset?.name ?? ''}"} first — its tools become callable immediately.`,
                 };
             }
+            if (call.argumentsError &&
+                // 'unparseable' is unambiguous: argument bytes ARRIVED and could not be
+                // used, which is the shape of a truncation. 'empty' is only a defect
+                // when the tool actually REQUIRES an argument — a schema with no required
+                // field is legitimately callable with none, and the Gemini wire omits an
+                // empty `args` object, so a blanket refusal there would be a FALSE refusal
+                // of a real no-argument call (git, plan_todo). Item 6.
+                (call.argumentsError === 'unparseable' || toolRequiresArguments(call.name))) {
+                // F1 — the call was never made: the argument payload did not arrive.
+                // Refusing here is the whole point: executing it as `{}` reported a tool
+                // call that "ran" with no input, hid the real cause (an output-budget
+                // truncation) from the model, and burned 59 round trips in one turn.
+                malformedToolCalls += 1;
+                return {
+                    call,
+                    refuse: malformedToolCallRefusal({ name: call.name, argumentsError: call.argumentsError }, { finishReason: response.finishReason, attempt: malformedToolCalls }),
+                };
+            }
             if (!isToolEnabled(call.name, context.configManager)) {
                 // I1 execution gate: a disabled tool is rejected at runtime even if
                 // the model hallucinated its name — the toggle is never cosmetic.
@@ -1551,7 +1867,7 @@ async function runToolLoopInner(opts, progress) {
                 try {
                     const findings = checkProjectPrerequisites(createNodePrereqFs(opts.context?.cwd || process.cwd()));
                     if (findings.length > 0) {
-                        deferredUserNudges.push(formatPreflightFindings(findings));
+                        deferredUserNudges.push({ gate: 'prerequisite', content: formatPreflightFindings(findings) });
                         deps.onEvent?.(`   🧱 pre-flight: ${findings.length} missing project prerequisite(s) — handed the exact fix before building.`);
                         traceEvent({
                             kind: 'gate',
@@ -1635,7 +1951,7 @@ async function runToolLoopInner(opts, progress) {
                     ? `a workspace-directing turn was about to mutate without a plan — the first mutation batch (${blocked.join(', ')}) was refused once and the model asked to declare a plan first`
                     : 'a workspace-directing turn was about to mutate without a plan — one bounded nudge to declare one first',
             });
-            deferredUserNudges.push(planRequiredNudge(currentAsk(opts)));
+            deferredUserNudges.push({ gate: 'plan', content: planRequiredNudge(currentAsk(opts)) });
         }
         const executed = new Array(plans.length).fill('');
         for (let i = 0; i < plans.length;) {
@@ -1710,6 +2026,21 @@ async function runToolLoopInner(opts, progress) {
                     const p = a?.path ?? a?.file_path ?? a?.file;
                     if (typeof p === 'string' && p) {
                         progress.mutatedPaths.push(p);
+                        // Bundle 19 — keep what was WRITTEN, so the turn can be judged on its
+                        // artifact. Capped: a turn cannot grow the loop's memory without bound.
+                        if (progress.authoredArtifacts.length < AUTHORED_ARTIFACT_MAX) {
+                            const written = extractWrittenText(call.arguments);
+                            progress.authoredArtifacts.push({
+                                tool: call.name,
+                                path: p,
+                                // The TEXT is capped for memory, but the WORD COUNT is taken from the
+                                // FULL text: a long document must be measured whole. Measuring the
+                                // first 20k characters instead under-counts a long-with-long-words
+                                // document and FALSELY flags it as short — see `detectArtifactShortfall`.
+                                content: written.slice(0, AUTHORED_ARTIFACT_MAX_CHARS),
+                                words: countWords(written),
+                            });
+                        }
                         // Stage 2 — the run's own record of what it CHANGED, so a self-report
                         // can answer "what have you been doing" from data rather than from a
                         // re-read of the transcript.
@@ -1860,7 +2191,7 @@ async function runToolLoopInner(opts, progress) {
         // complete (every call id has a `tool` result). This is the first point a
         // user/system message may safely follow the batch.
         for (const nudge of deferredUserNudges)
-            thread.push({ role: 'user', content: nudge });
+            harness.push(thread, nudge.gate, nudge.content);
         // Track the generalized stall: a step that RAN tools but succeeded at none
         // of them extends the streak; any success clears it. A text-only step (no
         // tools) leaves it as it was — the model is thinking, not failing.
@@ -1878,6 +2209,21 @@ async function runToolLoopInner(opts, progress) {
         // right after the step's results are in the thread, and the next model
         // step sees it. Bounded once per turn and keyed on the action so the same
         // repeat cannot trigger it twice.
+        // ── A payload that does not fit in one output ────────────────────────────
+        // The refusal above already says so per call; this adds ONE mid-turn nudge
+        // naming the delivery strategy, because a model stuck re-emitting a too-large
+        // call needs the alternative, not a third identical error.
+        if (malformedToolCalls >= 3 && malformedCallNudges < 1) {
+            malformedCallNudges += 1;
+            stepLimit += 1;
+            deps.onEvent?.(`   📦 ${malformedToolCalls} calls arrived with no usable arguments — telling the model to build the artifact in sections.`);
+            traceEvent({
+                kind: 'gate',
+                gate: 'malformed-call',
+                summary: `${malformedToolCalls} tool calls this turn carried no usable arguments (payload larger than one model output) — one bounded nudge to deliver in sections`,
+            });
+            harness.push(thread, 'malformed-call', malformedCallNudge(malformedToolCalls));
+        }
         if (diagnosisNudges < 1) {
             const repeated = runTrace.repeatedFailure();
             if (repeated && repeated.times >= 2) {
@@ -1890,7 +2236,7 @@ async function runToolLoopInner(opts, progress) {
                     summary: `the same action failed ${repeated.times} times (${repeated.tool}: ${repeated.action.slice(0, 120)}) — ` +
                         'one bounded nudge to diagnose the root cause and change the approach',
                 });
-                thread.push({ role: 'user', content: repeatedFailureNudge(repeated) });
+                harness.push(thread, 'diagnosis', repeatedFailureNudge(repeated));
             }
             else if (failedToolSteps >= NO_PROGRESS_STALL_STEPS) {
                 // Stage 2 — no SINGLE action repeated, but the last N steps each ran
@@ -1904,7 +2250,7 @@ async function runToolLoopInner(opts, progress) {
                     summary: `${failedToolSteps} consecutive steps ran tools and none succeeded — ` +
                         'one bounded nudge to diagnose the shared cause and change the approach',
                 });
-                thread.push({ role: 'user', content: noProgressNudge(runTrace.recentFailures(3), failedToolSteps) });
+                harness.push(thread, 'diagnosis', noProgressNudge(runTrace.recentFailures(3), failedToolSteps));
             }
         }
         // Tiered exposure: after EVERY executed tool call, union any newly
@@ -1935,7 +2281,7 @@ async function runToolLoopInner(opts, progress) {
         // P4 — cancellation during/after tool execution: do NOT request another
         // model step on a cancelled turn (the user already walked away).
         if (opts.signal?.aborted) {
-            return { content: '', followups, toolCalls: toolCallsRun, steps, ...(opts.resume ? { replayedSteps } : {}), bounded: false, cancelled: true };
+            return { content: '', followups, toolCalls: toolCallsRun, steps, ...(opts.resume ? { replayedSteps } : {}), bounded: false, cancelled: true, termination: 'cancelled' };
         }
         // ── endsAgentStep — a successful dispenser's RESULT is the answer ────────
         // `build`/`resume`/`repair`/`document`/`website`/`analyze`/`test`/`publish`
@@ -1965,6 +2311,8 @@ async function runToolLoopInner(opts, progress) {
                 ...(opts.resume ? { replayedSteps } : {}),
                 bounded: false,
                 continuations,
+                ...(modelHandoffs > 0 ? { modelHandoffs } : {}),
+                termination: 'delivered',
             };
         }
         // End-of-response semantics (the contract: "END EVERY RESPONSE by
@@ -2011,10 +2359,7 @@ async function runToolLoopInner(opts, progress) {
                 // preference order. A live turn reached for `node -c` because the nudge
                 // left the choice to the model; `verificationNudgeFor` reads the
                 // workspace and asks for the real command, so there is nothing to guess.
-                thread.push({
-                    role: 'user',
-                    content: verificationNudgeFor(ctx.cwd ?? process.cwd(), progress.mutatedPaths),
-                });
+                harness.push(thread, 'verification', verificationNudgeFor(ctx.cwd ?? process.cwd(), progress.mutatedPaths));
                 continue;
             }
             // G13b — DELIVERABLE GATE (concluding path). AFTER the verification gate
@@ -2032,7 +2377,7 @@ async function runToolLoopInner(opts, progress) {
                         : 'an authored deliverable was requested and no file was written — one bounded nudge to produce it',
                 });
                 thread.push({ role: 'assistant', content: response.content });
-                thread.push({ role: 'user', content: deliverableNudge(authorization.requestedPath) });
+                harness.push(thread, 'deliverable', deliverableNudge(authorization.requestedPath));
                 continue;
             }
             // ZERO-ACTION gate (concluding exit) — the same bounded pass as the
@@ -2050,7 +2395,7 @@ async function runToolLoopInner(opts, progress) {
                 });
                 lastContent = '';
                 thread.push({ role: 'assistant', content: response.content });
-                thread.push({ role: 'user', content: zeroActionNudge(currentAsk(opts)) });
+                harness.push(thread, 'action', zeroActionNudge(currentAsk(opts)));
                 continue;
             }
             // SELF-REVIEW (concluding exit) — same bounded pass, placed AFTER the
@@ -2066,7 +2411,7 @@ async function runToolLoopInner(opts, progress) {
                     summary: 'a substantial turn that changed files reached its end — one bounded nudge to check the result against the original ask',
                 });
                 thread.push({ role: 'assistant', content: response.content });
-                thread.push({ role: 'user', content: review });
+                harness.push(thread, 'self-review', review);
                 continue;
             }
             const content = response.content.length >= lastContent.length ? response.content : lastContent;
@@ -2078,17 +2423,52 @@ async function runToolLoopInner(opts, progress) {
                 ...(opts.resume ? { replayedSteps } : {}),
                 bounded: false,
                 continuations,
+                ...(modelHandoffs > 0 ? { modelHandoffs } : {}),
+                termination: 'delivered',
             };
         }
     }
     // Reaching here means the continuation budget is spent (the in-loop check
     // extends the bound otherwise) — the turn is honestly bounded.
     bounded = true;
-    deps.onEvent?.(`   ⚠️ Tool loop reached its ${stepLimit}-step budget — returning the last response.`);
+    // P3 — the exit SAYS which ending this was. The live trace reported "the step
+    // budget (17) was reached" after FIVE model calls and zero tool calls: the
+    // empty-response path had ended the turn, and this shared tail claimed the road
+    // had run out when it had not. A reader cannot tell a model shortage from a
+    // budget from that line, which is the whole reason `termination` exists.
+    if (exitTermination === 'no-capable-candidate') {
+        deps.onEvent?.('   ⚠️ Every model that answered returned nothing usable — ending the turn and reporting exactly what was tried.');
+    }
+    else if (exitTermination === 'reasoning-spin') {
+        deps.onEvent?.('   🧠 Reasoning-only output kept repeating — ending the turn instead of spinning.');
+    }
+    else {
+        deps.onEvent?.(`   ⚠️ Tool loop reached its ${stepLimit}-step budget — returning the last response.`);
+    }
+    // P3 — BUG SIGNAL. Nothing was delivered and the caller could still have
+    // handed the work to another model, so this ending is a GAP IN THE ROAD, not a
+    // shortage of models. It is said out loud (invariant 2: a failure is never
+    // silent) and named on the result, so the caller's report does not have to
+    // guess which of the two it was serving the user.
+    // `exitTermination === null` is what makes this a BUDGET claim: when the empty
+    // path already chose an ending it said WHY (a model shortage, a reasoning
+    // spin), and re-labelling that as a budget gap would be the exact dishonesty
+    // this work removes — the reason must be the one that actually applied.
+    const budgetGapWithCandidates = exitTermination === null &&
+        lastContent.trim() === '' &&
+        !!deps.requestModelSwitch &&
+        modelHandoffs < MAX_MODEL_HANDOFFS_PER_TURN;
+    if (budgetGapWithCandidates) {
+        logger.warn(`   ⚠️ the turn ran out of steps with nothing delivered while a model handoff was still available ` +
+            `(handoffs used ${modelHandoffs}/${MAX_MODEL_HANDOFFS_PER_TURN}) — this is a BUDGET gap, not a model shortage`);
+    }
     traceEvent({
         kind: 'decision',
         gate: 'budget',
-        summary: `the step budget (${stepLimit}) was reached — the turn ended on its last response instead of finishing`,
+        summary: budgetGapWithCandidates
+            ? `the step budget (${stepLimit}) was reached with nothing delivered while model handoffs were still available ` +
+                `(handoffs used ${modelHandoffs}/${MAX_MODEL_HANDOFFS_PER_TURN}) — a budget gap, not a model shortage`
+            : `the step budget (${stepLimit}) was reached — the turn ended on its last response instead of finishing`,
     });
     return {
         content: lastContent || 'I reached my step limit for this request.',
@@ -2098,6 +2478,11 @@ async function runToolLoopInner(opts, progress) {
         ...(opts.resume ? { replayedSteps } : {}),
         bounded: true,
         continuations,
+        ...(modelHandoffs > 0 ? { modelHandoffs } : {}),
+        // An exit the empty/think path chose says exactly why; otherwise the road
+        // simply ran out, and `budget-exhausted` admits that rather than dressing it
+        // up as a model shortage.
+        termination: exitTermination ?? 'budget-exhausted',
     };
 }
 // ─── Honest-answer guard ────────────────────────────────────────────────────
@@ -2155,12 +2540,129 @@ export function detectUnverifiedDeliveryClaim(content, toolsRun) {
     }
     return false;
 }
+/**
+ * Tools whose SUCCESS means a file could have been written, even though the loop
+ * cannot see it: an editor (tracked in `mutatedPaths`), a shell whose command
+ * redirected a file, an executed snippet. Used only to keep the file-claim guard
+ * conservative — if any of these SUCCEEDED, the turn's own record does not
+ * contradict a "I wrote the file" claim, so the guard stays silent.
+ */
+const FILE_WRITE_CAPABLE_TOOLS = new Set([
+    'write_file',
+    'edit_file',
+    'apply_patch',
+    'multi_edit',
+    'patch_file',
+    'run_terminal',
+    'run_cli',
+    'code_execution',
+]);
+/**
+ * Past-tense sentences that ASSERT a FILE was produced. Deliberately about
+ * writing/creating/saving a file — not about reading one, and not about sending
+ * one (`detectUnverifiedDeliveryClaim` covers sends).
+ */
+const FILE_WRITE_CLAIM_RE = [
+    /\b(?:has|have)\s+been\s+(?:written|saved|created|produced|generated)\b/i,
+    /\bi(?:'ve|\s+have)\s+(?:just\s+|now\s+|successfully\s+)?(?:written|saved|created|produced|generated)\b/i,
+    /\b(?:the\s+)?(?:file|document|guide|report|chapter|artifact|deliverable|write-?up|script|manifest)\b[^.]{0,50}\b(?:now\s+)?contains\b/i,
+    /\b(?:written|saved|created|produced|generated)\s+(?:it\s+)?(?:to|into)\s+(?:disk\b|\S+\.\w{1,6}\b)/i,
+    /\b(?:the\s+)?(?:file|document|report|guide|artifact|deliverable)\b[^.]{0,40}\b(?:is|are)\s+(?:now\s+)?(?:on\s+disk|written|saved|created|ready)\b/i,
+];
+/**
+ * True when the answer CLAIMS a file was produced and the turn's own record says
+ * none was. This is the sibling of `detectUnverifiedDeliveryClaim` (which covers
+ * SENDS), and it closes a gap found live: a turn wrote nothing, then replied
+ * "The guide has been written and saved as GUIDE.md … contains a full ~5,000-word
+ * technical guide", and NO flag could see it.
+ *
+ * Why it is not redundant with `undeliveredArtifact`: that flag is a function of
+ * the ASK (it is gated on the request classifying as an authored deliverable), so
+ * an ask the classifier does not recognise — or a plain code ask that happens to
+ * be answered with a fabricated "I saved it" — produced no disclosure at all. This
+ * one is a function of what the turn DID: a completed file claim, contradicted by
+ * the absence of any write. The two are made mutually exclusive at the call site so
+ * one turn is never reported under two names.
+ *
+ * Conservative by construction, so an honest turn is never flagged: it fires only
+ * when NOTHING was mutated AND no write-capable tool succeeded; a heredoc through
+ * `run_terminal`, an `edit_file`, or any executed snippet therefore exempts the
+ * turn, because the run's record cannot contradict the claim.
+ */
+export function detectUnverifiedFileClaim(content, evidence) {
+    const text = (content || '').trim();
+    if (!text)
+        return false;
+    if (evidence.mutatedPaths.length > 0)
+        return false;
+    if (evidence.successfulToolCalls.some((n) => FILE_WRITE_CAPABLE_TOOLS.has(n)))
+        return false;
+    const sentences = text.split(/(?<=[.!?\u3002\uff01\uff1f])\s+|\n+/);
+    for (const sentence of sentences) {
+        const s = sentence.trim();
+        if (!s || NON_CLAIM_CONTEXT_RE.test(s))
+            continue;
+        if (FILE_WRITE_CLAIM_RE.some((re) => re.test(s)))
+            return true;
+    }
+    return false;
+}
 /**
  * Tool-shaped actions a first-person imminent promise can drop. Matched by
  * STEM (`\w*` suffix) so "scaffold" covers "scaffolding", "write" covers
  * "writing", etc. — the promise is usually phrased as a gerund ("start by
  * scaffolding").
  */
+/**
+ * Bundle 23 (item 13) — how far short of a stated magnitude counts as a miss.
+ * Half, deliberately: "about 5000 words" delivered as 4,200 is a tighter draft,
+ * not a shortfall, and an over-eager version of this flag would be ignored like
+ * every other noisy guard. Under half is materially not what was asked for.
+ */
+export const ARTIFACT_SHORTFALL_RATIO = 0.5;
+/**
+ * How much of a delivered artifact travels to the corpus (item 13). Bounded on
+ * purpose: a candidate row is a SAMPLE to fit a signal to, not a copy of the
+ * user's document, and an unbounded row would turn a collection file into a
+ * second copy of everything the agent ever wrote.
+ */
+export const AUTHORED_DELIVERABLE_EXCERPT_MAX = 2000;
+/**
+ * Compare a written artifact against an EXPLICIT magnitude the ask named.
+ *
+ * This is item 13's honest half: the delivered artifact is measured AGAINST THE
+ * REQUEST, deterministically, instead of judging quality from a model's
+ * vocabulary. It fires only when the ask states a number ("about 5000 words",
+ * "a 100 page story") — a plain "write a long document" names no magnitude, so
+ * there is nothing to compare against and this must not invent one.
+ *
+ * Returns null unless the file is under `ARTIFACT_SHORTFALL_RATIO` of the target,
+ * so an honest document is never flagged. An empty file returns null too — a
+ * missing artifact is the omission/undelivered gates' job, not a shortfall's.
+ */
+export function detectArtifactShortfall(ask, artifact) {
+    const target = parseLongFormTarget(ask || '');
+    // Only an EXPLICIT magnitude counts: `source` is the quoted number the parser
+    // matched, while the default-book branch (a book with no number in the ask) has
+    // no quotes — inventing a target there would measure the document against a
+    // number the user never said.
+    if (!target || !target.source.startsWith('"'))
+        return null;
+    // `words` is the count of the FULL artifact when the caller supplies it; counting
+    // `content` (which may be a capped prefix) instead would measure the storage
+    // limit, not the document, and could flag a long deliverable as short.
+    const deliveredWords = artifact.words ?? countWords(artifact.content);
+    if (deliveredWords === 0)
+        return null;
+    if (deliveredWords >= target.wordsTarget * ARTIFACT_SHORTFALL_RATIO)
+        return null;
+    return {
+        path: artifact.path,
+        deliveredWords,
+        targetWords: target.wordsTarget,
+        source: target.source,
+    };
+}
 const INTENT_ACTION_STEM = '(?:creat|writ|build|scaffold|implement|generat|add|edit|updat|modif|refactor|run|execut|install|configur|read|inspect|send|post|upload|deploy|publish|fetch|search|apply|fix|delet|remov|mov|renam|copi|compil|set\\s+up)';
 /**
  * A first-person IMMINENT promise to act. Immediacy is required, because that
@@ -2225,6 +2727,82 @@ export function detectUnfulfilledIntentPromise(content) {
     }
     return false;
 }
+// ─── Bundle 19 — an artifact that declares ITSELF incomplete ────────────────
+/**
+ * Statements an ARTIFACT makes about being incomplete — read from the file the turn
+ * WROTE, never from the model's prose.
+ *
+ * WHY THIS EXISTS (measured 2026-10-07). Asked for a ~2500-word design document, a
+ * real turn wrote 25 words to `DESIGN.md` and reported success. The file contained
+ * `## 1. Introduction ... (full content omitted for brevity) ...` — it announced the
+ * content and then omitted it — and its own verification ("read the file back and
+ * confirm all sections are present") is true of a list of headings. No existing flag
+ * could see it: `unverifiedEdit` needs an unobserved mutation (the file WAS read
+ * back), `undeliveredArtifact` needs nothing written (a file exists), and there is
+ * content, so nothing is empty.
+ *
+ * WHY THIS IS NOT A "PHRASE LIST" IN THE SENSE THIS PROGRAMME REMOVES. Those decide
+ * whether work is GOOD, from a model's vocabulary. This reads a factual statement the
+ * artifact makes about itself — the same distinction as `unfulfilledPromise` (an
+ * announced action) and `detectUnverifiedDeliveryClaim` (a claim contradicted by the
+ * run). A document saying "content omitted" is not a quality judgement; it is the
+ * artifact reporting its own incompleteness.
+ *
+ * DELIBERATELY NARROW. Each pattern requires an OMISSION word bound to content or a
+ * section. The bare word `placeholder` is NOT matched (HTML `placeholder=` attributes
+ * would fire on ordinary code), and neither is a bare `TODO` — a TODO is a plan for
+ * later work, not a claim that this file is finished.
+ */
+const ARTIFACT_OMISSION_RE = [
+    /\(\s*(?:the\s+)?(?:full\s+)?content\s+omitted/i,
+    /\bcontent\s+(?:is\s+|was\s+)?omitted\s+for\s+(?:brevity|space|length|conciseness|readability)\b/i,
+    /\bomitted\s+for\s+(?:brevity|space|length|conciseness|readability)\b/i,
+    /\b(?:the\s+)?(?:rest|remainder)\s+of\s+(?:this\s+)?(?:document|report|article|file)\s+(?:is|are|was|were)?\s*(?:omitted|not\s+included|intentionally\s+left\s+out)/i,
+    // A section RANGE may sit between the noun and the adverb/verb: the measured
+    // "Sections 2-9 intentionally omitted." failed the adjacency form that only
+    // allowed whitespace there. The range is optional, so "Content omitted." and
+    // "Details omitted." still match; a bare prose "omits" does not.
+    /\b(?:sections?|content|details?)\s+(?:\d+(?:\s*[-–—]\s*\d+)?\s+)?(?:intentionally\s+|deliberately\s+)?omitted\b/i,
+    /\bplaceholder\s+for\s+(?:the\s+)?(?:full|actual|real|complete)\s+(?:content|document|section|report|article)\b/i,
+];
+/**
+ * The statement an artifact makes about its own incompleteness, or `null`.
+ * Returns the MATCHED TEXT so the report can quote what the file said about itself.
+ */
+export function detectSelfDeclaredOmission(text) {
+    const body = text || '';
+    if (!body)
+        return null;
+    for (const re of ARTIFACT_OMISSION_RE) {
+        const m = body.match(re);
+        if (m?.[0])
+            return m[0].trim();
+    }
+    return null;
+}
+/** Cap on the content kept per artifact, and on how many are kept, so a long turn cannot grow the loop's memory. */
+const AUTHORED_ARTIFACT_MAX_CHARS = 20_000;
+const AUTHORED_ARTIFACT_MAX = 40;
+/**
+ * The text a mutation call WROTE, from whichever field carries it. `''` when the call
+ * carries no literal body (an append by path, a patch with no text).
+ */
+/**
+ * The text a write actually carried — UNCAPPED, so a caller can measure the WHOLE
+ * artifact (word count) and cap only what it stores. Capping here would make the
+ * measurement a property of the storage limit rather than of the file.
+ */
+function extractWrittenText(args) {
+    if (!args || typeof args !== 'object')
+        return '';
+    const a = args;
+    for (const key of ['content', 'new_string', 'newText', 'text', 'body', 'patch']) {
+        const v = a[key];
+        if (typeof v === 'string' && v)
+            return v;
+    }
+    return '';
+}
 // ─── Build honesty (A3 Part 2) ──────────────────────────────────────────────
 /**
  * Past-tense sentences that ASSERT a BUILD, or its artifact, came out good.
@@ -2366,6 +2944,7 @@ export async function runToolLoop(opts) {
         successfulToolCalls: [],
         deliveryConfirmed: false,
         mutatedPaths: [],
+        authoredArtifacts: [],
         verificationEvidence: [],
         executedActions: [],
     };
@@ -2406,12 +2985,66 @@ export async function runToolLoop(opts) {
         // runs whether or not the nudge was enabled, so the flag is never a
         // function of configuration.
         const activity = assessEditActivity(result.successfulToolCalls, progress.verificationEvidence, progress.mutatedPaths);
-        if (activity.needsVerification) {
+        // Bundle 21/25 — the authored-document demotion, applied WHERE THE FLAGS ARE
+        // SET so every surface agrees without a per-caller conditional: the trace
+        // outcome, the console warning, the working-state ledger and the turn report all
+        // read these two flags. For an authored deliverable that was written and then
+        // READ BACK, the read-back IS the meaningful check — a code-style "no observing
+        // run" verdict would contradict the `delivered-and-read-back` verdict the report
+        // deliberately produces. Measured live: a turn that wrote and read back GUIDE.md
+        // recorded `unverifiedEdit: true` on the trace while its report said
+        // `delivered-and-read-back`.
+        const authoredReadBack = isAuthoredReadBack(lastUserText(opts.messages), result.successfulToolCalls);
+        if (activity.needsVerification && !authoredReadBack) {
             result.unverifiedEdit = true;
         }
-        if (detectUnverifiedEditClaim(result.content, activity.mutations, activity.verifications)) {
+        if (detectUnverifiedEditClaim(result.content, activity.mutations, activity.verifications) &&
+            !authoredReadBack) {
             result.unverifiedEditClaim = true;
         }
+        // Bundle 19 — ARTIFACT honesty. A file the turn wrote says its own content was
+        // omitted, so the turn is NOT finished work however complete its prose reads.
+        // Judged on the artifact, never on the model's vocabulary, and recorded with the
+        // artifact's own words so a reader can see exactly what it admitted.
+        for (const artifact of progress.authoredArtifacts) {
+            const statement = detectSelfDeclaredOmission(artifact.content);
+            if (statement) {
+                result.artifactIncomplete = { path: artifact.path, statement };
+                break;
+            }
+        }
+        // Bundle 23 (item 13) — ARTIFACT-VS-ASK honesty. When the ask named an explicit
+        // magnitude and the turn wrote a SINGLE artifact far short of it, the delivered
+        // file is not what was asked for. Skipped when the artifact already admits its
+        // own omission (that is the stronger, self-incriminating signal), and bounded to
+        // one artifact because an append/sectioned delivery cannot be measured here
+        // without risking a false "short".
+        if (!result.artifactIncomplete && progress.authoredArtifacts.length === 1) {
+            const shortfall = detectArtifactShortfall(lastUserText(opts.messages), progress.authoredArtifacts[0]);
+            if (shortfall)
+                result.artifactShortfall = shortfall;
+        }
+        // Item 13 (round 3) — COLLECT the case a quality signal would have to be fit
+        // to, instead of inventing a rule for it. A single authored artifact that
+        // tripped NEITHER check above is the "fluent, on-length" shape: the one no
+        // live run has produced as a miss, and the one no deterministic rule can judge
+        // (judging it from vocabulary is the defect this programme exists to remove).
+        // So the FACTS travel — path, length, a bounded excerpt — and a caller records
+        // them with a later user verdict as the label. No judgement is made here.
+        if (!result.artifactIncomplete && !result.artifactShortfall && progress.authoredArtifacts.length === 1) {
+            const artifact = progress.authoredArtifacts[0];
+            const ask = lastUserText(opts.messages) || '';
+            const target = parseLongFormTarget(ask);
+            result.authoredDeliverable = {
+                path: artifact.path,
+                deliveredWords: artifact.words,
+                // Only an EXPLICIT magnitude is carried — `source` is the quoted number the
+                // parser matched, while the default-book branch invents one. A corpus that
+                // recorded an invented target would fit a signal to a number nobody asked for.
+                ...(target && target.source.startsWith('"') ? { targetWords: target.wordsTarget } : {}),
+                excerpt: artifact.content.slice(0, AUTHORED_DELIVERABLE_EXCERPT_MAX),
+            };
+        }
         // G13b — DELIVERABLE honesty, the same way and for the same reason: the
         // flag is a function of what the turn DID, never of configuration. A turn
         // that was asked for a file and wrote none must not be readable as
@@ -2424,6 +3057,18 @@ export async function runToolLoop(opts) {
             wantsAuthoredArtifact(lastUserText(opts.messages))) {
             result.undeliveredArtifact = true;
         }
+        // Bundle 20 — FILE-CLAIM honesty, the complement of the flag above. That one
+        // is a function of the ASK; this is a function of the ANSWER: a reply that says
+        // a file was produced while the turn mutated nothing. Skipped when
+        // `undeliveredArtifact` already fired, so one turn is never reported under two
+        // names.
+        if (!result.undeliveredArtifact &&
+            detectUnverifiedFileClaim(result.content, {
+                mutatedPaths: progress.mutatedPaths,
+                successfulToolCalls: result.successfulToolCalls,
+            })) {
+            result.unverifiedFileClaim = true;
+        }
         // ZERO-ACTION honesty — a request that DIRECTED work on the workspace was
         // answered with nothing at all: no tool succeeded, nothing was written. The
         // flag is a function of what the turn DID, never of configuration, so a
@@ -2527,6 +3172,22 @@ const NON_PRODUCTIVE_TOOLS = new Set(['suggest_followups']);
 function hasProductiveAction(progress) {
     return progress.successfulToolCalls.some((name) => !NON_PRODUCTIVE_TOOLS.has(name));
 }
+/**
+ * How many PRODUCTIVE actions have SUCCEEDED this turn — the cardinality of the
+ * very predicate `hasProductiveAction` answers, so the two cannot drift. D1 uses
+ * it to tell a later answer written after real work (an update, which supersedes)
+ * from a closing wrapper written after none (presentation, which must not). It
+ * reads the loop's own success record — `successfulToolCalls`, appended only for
+ * calls that actually ran — so a refused or failed call is never mistaken for
+ * work, and `suggest_followups` (which merely concludes) is never counted.
+ */
+function countProductiveWork(progress) {
+    let n = 0;
+    for (const name of progress.successfulToolCalls)
+        if (!NON_PRODUCTIVE_TOOLS.has(name))
+            n += 1;
+    return n;
+}
 /**
  * Does the ZERO-ACTION gate apply to this turn?
  *
@@ -2638,6 +3299,107 @@ function previewToolResult(result, max = 200) {
  * Returns null when the result is an ordinary tool/runtime error, so the caller
  * keeps its own wording rather than inventing a cause.
  */
+/** How many steps of an existing plan are re-shown to the model (bounded). */
+export const PLAN_CONTEXT_MAX_STEPS = 12;
+/**
+ * The block that hands the model the plan its own conversation already tracks.
+ *
+ * Written to make the correct next move obvious rather than merely possible: the
+ * step ids are given verbatim (so `update` can address them), the statuses are the
+ * stored truth, and the one thing a model tends to do instead — declare the plan
+ * again — is named as wrong, because a re-declaration under the same goal now
+ * carries progress but still replaces the step LIST the user is watching.
+ */
+export function planContextBlock(plan) {
+    const shown = plan.steps.slice(0, PLAN_CONTEXT_MAX_STEPS);
+    const hidden = plan.steps.length - shown.length;
+    const lines = shown.map((s) => `  - ${s.id} [${s.status}] ${s.description}${s.note ? ` — ${s.note}` : ''}`);
+    const open = plan.steps.filter((s) => s.status !== 'done').length;
+    return [
+        `📋 The plan this conversation is already tracking (${plan.steps.length - open}/${plan.steps.length} done, revision ${plan.revision}):`,
+        `  goal: ${plan.goal}`,
+        ...lines,
+        ...(hidden > 0 ? [`  … and ${hidden} more step(s).`] : []),
+        `Advance THIS plan: call \`plan_todo\` with action "update", the step id above and its new status. ` +
+            'Do NOT declare it again with action "create" — the checklist the user is watching is this one, and ' +
+            're-declaring replaces its steps. Work the next open step.',
+    ].join('\n');
+}
+/**
+ * The refusal a tool call gets when its ARGUMENTS never arrived.
+ *
+ * Measured defect (dashboard session `4e2b0e51…-1791349543186`, 2026-10-07): the
+ * goal "deliver complete document" produced **59 `write_file` calls with empty
+ * arguments**, plus 14 `run_terminal` and 2 `code_execution` — 73 of the turn's 81
+ * calls. Each one was executed as `{}`, so the model's feedback was
+ * `write_file: path is required`, which names the wrong problem: the model HAD
+ * asked for a write, with a payload (a whole design document) that could not fit
+ * in one output. It diagnosed "my calls were emitted empty", retried 59 times,
+ * and the turn ended `bounded: true` with no document. Two things were missing
+ * and both are here: the REAL cause, and a way to succeed at all.
+ *
+ * The refusal is `Error:`-prefixed because the call genuinely did not run — the
+ * loop's honest accounting (successful calls, mutations, verification) depends
+ * on that prefix, so a call that never reached a tool is never counted as one.
+ */
+export function malformedToolCallRefusal(call, opts = {}) {
+    const attempt = opts.attempt ?? 1;
+    const cause = call.argumentsError === 'empty'
+        ? 'the call arrived with NO arguments at all'
+        : "the call's arguments arrived incomplete and could not be parsed";
+    const why = opts.finishReason === 'length'
+        ? 'the provider stopped this step at its output-token limit (finish_reason: "length"), so the payload was cut off before the arguments were complete'
+        : 'this is what a payload too large to emit in ONE step looks like on the wire — nothing was lost on this side';
+    const escape = 'Send the payload in PIECES instead of one call: `write_file` the FIRST section, then call `write_file` again ' +
+        'with mode:"append" for each further section (or write a smaller file and grow it with `edit_file`). ' +
+        'Do NOT re-send this call unchanged — it cannot succeed, and every attempt is a full round trip.';
+    const escalation = attempt >= 3
+        ? ` (This is time ${attempt} this turn that a call arrived with no usable arguments — change the SHAPE of the call, not its wording.)`
+        : '';
+    return `Error: ${call.name}: NOT run — ${cause}, so the tool never saw your input. Reason: ${why}. ${escape}${escalation}`;
+}
+/**
+ * Whether a tool's schema declares at least one REQUIRED argument (item 6).
+ *
+ * This is what lets the empty-arguments refusal reach the JSON-fallback and
+ * Gemini wires without refusing a legitimate no-argument call: a `git` or
+ * `plan_todo` call with `{}` is a real call, but a `write_file` with `{}` is a
+ * truncated one. Read from the tool's own JSON schema (derived from its zod
+ * schema, never hand-kept), so a tool added later is judged by what it declares.
+ * When the schema cannot be read the answer is conservative (`true`): a
+ * malformed payload is the more likely cause, and the refusal is guidance, not a
+ * wall — the model can still retry with arguments.
+ */
+function toolRequiresArguments(name) {
+    try {
+        const [schema] = toolJsonSchemas([name]);
+        // An unregistered name is not a call to honour — refuse, as before.
+        if (!schema)
+            return true;
+        const required = schema.parameters.required;
+        // No `required` key means the tool declares no required argument, so an empty
+        // payload IS a legitimate call (list_dir). An empty array means the same.
+        if (Array.isArray(required))
+            return required.length > 0;
+        return false;
+    }
+    catch {
+        // A schema that cannot be read is treated conservatively: a malformed payload
+        // is the more likely cause, and the refusal is guidance the model can act on.
+        return true;
+    }
+}
+/**
+ * The one bounded mid-turn nudge for the same defect, pushed after the results of
+ * the step that produced it — so a model that keeps re-sending a payload too large
+ * for one output is told the strategy, not merely that it failed again.
+ */
+export function malformedCallNudge(attempts) {
+    return (`Your last ${attempts} tool call(s) this turn arrived WITHOUT usable arguments — the payload did not fit in one ` +
+        'model output and was cut off. Nothing is wrong with your plan; the DELIVERY shape is. Build the artifact in ' +
+        'sections: `write_file` the first part, then `write_file` with mode:"append" for each next part (keep each call ' +
+        'under ~120 lines). Do not repeat the single large call.');
+}
 export function classifyToolRefusal(result) {
     const text = result || '';
     if (/needs explicit confirmation|requires confirmation|retry with confirm|call ask_user/i.test(text) ||
@@ -2677,11 +3439,50 @@ export function classifyToolRefusal(result) {
     return null;
 }
 /** Compact argument preview for the event line. */
-function summarizeArgs(args) {
-    const first = Object.entries(args).slice(0, 1)[0];
-    if (!first)
+/**
+ * The argument fields that say WHAT a call acts on — the useful half of a
+ * one-field preview, in preference order.
+ *
+ * MEASURED (2026-10-07, live): a routing-design run printed
+ * `⚙ write_file({confirm: true})` five times and `⚙ edit_file({allow_multiple:
+ * false})` four times on its console. Both calls were COMPLETE — the preview
+ * simply took the FIRST key the model happened to emit, which is a boolean
+ * default, so the one thing a watcher needs (WHICH FILE) was invisible. A
+ * progress line that names `confirm` instead of the path is worse than no line:
+ * it looks like the agent is confirming something it never wrote.
+ *
+ * The fallback stays "first entry" so an unknown tool is still previewed rather
+ * than blanked.
+ */
+const IDENTIFYING_ARG_KEYS = [
+    'path',
+    'filePath',
+    'file',
+    'paths',
+    'command',
+    'pattern',
+    'query',
+    'url',
+    'goal',
+    'name',
+    'question',
+    'tool',
+    'action',
+    'claim',
+];
+/**
+ * A one-field preview of a tool call's arguments, preferring the IDENTIFYING
+ * field ({@link IDENTIFYING_ARG_KEYS}) over whichever key was emitted first.
+ *
+ * Exported for the test that pins the preference — the bug it fixed was not a
+ * crash but a true statement that named the wrong thing.
+ */
+export function summarizeArgs(args) {
+    const entries = Object.entries(args);
+    if (entries.length === 0)
         return '{}';
-    const [key, value] = first;
+    const picked = IDENTIFYING_ARG_KEYS.map((k) => entries.find(([key]) => key === k)).find((e) => e !== undefined) ?? entries[0];
+    const [key, value] = picked;
     const v = typeof value === 'string' ? value : JSON.stringify(value);
     return `{${key}: ${v.length > 40 ? v.slice(0, 40) + '…' : v}}`;
 }