agent-nuvira 3.2.0 → 3.3.1

package/dist/tools/tool-loop.js

@@ -16,13 +16,16 @@
  *   blocks after its response text (contract in TOOL_CONTRACT_JSON).
  */
 import { getTool, toolJsonSchemas } from './registry.js';
-import { detectPermissionSeeking, requestAuthorizesWrites, stripTrailingPermissionSeek, } from '../learning/autonomy-policy.js';
+import { detectPermissionSeeking, isAffirmativeReply, replyAsksTheReader, requestAuthorizesWrites, stripTrailingPermissionSeek, } from '../learning/autonomy-policy.js';
+import { envelopeFromPlan, envelopeFromRequest, getEnvelope, grantEnvelope, isEnvelopeKey, } from '../learning/intent-envelope.js';
+import { detectProcessComplaint, isTraceKey, repeatNudge, runTraceFor, RunTrace, } from '../learning/run-trace.js';
+import { wantsAuthoredArtifact } from '../learning/deliverable-class.js';
 import { normalizeFollowups } from './followup-utils.js';
-import { assessEditActivity, detectUnverifiedEditClaim, isVerificationTool, VERIFICATION_NUDGE, AUTHORIZED_WORK_NUDGE, } from './edit-verification.js';
+import { assessEditActivity, detectUnverifiedEditClaim, isVerificationTool, verificationNudgeFor, THINK_ONLY_ESCALATION, AUTHORIZED_WORK_NUDGE, deliverableNudge, } from './edit-verification.js';
 import { effectiveToolJsonSchemas, coreToolJsonSchemas, isToolEnabled, toolsetForTool } from './toolsets.js';
 import { appendToolArtifact } from './artifact-append.js';
 import { logger } from '../utils/logger.js';
-import { toUserFacingGenerationError } from '../inference/tool-call-utils.js';
+import { toUserFacingGenerationError, TEXTUAL_TOOL_CALL_HINT, isTextualFollowupsPayload, followupEntriesFromPayload, stripTrailingFollowupsHeader, } from '../inference/tool-call-utils.js';
 // ─── P3c — tool-fallback hints (switch tools when one fails) ────────────────
 // The ask: *"if one tool fails you switch to another and explore parallel
 // ways"* (round-2 row 25). Today the raw `Error: …` text is fed back and a
@@ -115,7 +118,8 @@ export function isThinkOnlyResponse(content) {
 }
 /**
  * Extract JSON fallback tool calls from model text:
- * `{"tool":"name","arguments":{...}}` blocks, possibly fenced or multiple.
+ * `{"tool":"name","arguments":{...}}` blocks, possibly fenced or multiple —
+ * plus the name-keyed `{"suggest_followups":[…]}` shape models actually write.
  * Uses brace-matching (string-aware) so nested argument objects parse
  * correctly. Returns the cleaned content (blocks stripped) + parsed calls.
  */
@@ -160,11 +164,59 @@ export function extractFallbackToolCalls(content) {
             // Unparseable block — dropped from the answer, no tool call.
         }
     }
+    // ── Pass 2: our tool's ARGUMENTS keyed by our own tool NAME ─────────────
+    //   {"suggest_followups":[{"label":"…","prompt":"…"}, …]}
+    // This is the shape models ACTUALLY hand-write: across 116 stored assistant
+    // turns the canonical `{"tool":"…"}` form appeared ZERO times and this one
+    // 14. Pass 1 could not see it at all, so the block was delivered verbatim to
+    // the reader AND the suggestions were thrown away (no chips, no menu).
+    //
+    // The block is consumed in exactly two cases: it parses to OUR payload (the
+    // shared predicate — the same one the strip uses, so the two can never
+    // disagree), or it does not parse at all (truncated scaffolding is never
+    // prose). A value that parses cleanly to something demonstrably NOT the
+    // contract — `{"suggest_followups": "a note"}` — is left untouched, so a
+    // user's own JSON still survives.
+    const namedAt = /\(?\s*\{\s*"suggest_followups"\s*:/g;
+    let named;
+    while ((named = namedAt.exec(cleaned)) !== null) {
+        const end = findMatchingBrace(cleaned, named.index);
+        if (end === -1) {
+            // Cut off mid-call: everything from the marker on is scaffolding.
+            cleaned = cleaned.slice(0, named.index);
+            strippedAny = true;
+            break;
+        }
+        const block = cleaned.slice(named.index, end + 1);
+        let parsed = null;
+        let unparseable = false;
+        try {
+            parsed = JSON.parse(block);
+        }
+        catch {
+            unparseable = true;
+        }
+        if (!unparseable && !isTextualFollowupsPayload(parsed))
+            continue;
+        cleaned = cleaned.slice(0, named.index) + cleaned.slice(end + 1);
+        namedAt.lastIndex = named.index;
+        strippedAny = true;
+        const entries = followupEntriesFromPayload(parsed);
+        if (entries) {
+            calls.push({
+                id: `call_${calls.length + 1}`,
+                name: 'suggest_followups',
+                arguments: { followups: entries },
+            });
+        }
+    }
     if (!strippedAny)
         return { text: content, calls };
     // Remove empty fenced blocks left behind when a fenced JSON block's BODY was
-    // the tool call (e.g. "```json\n\n```").
-    const text = cleaned.replace(/\n?```[a-z]*\s*\n?\s*```\s*/gi, '\n').trim();
+    // the tool call (e.g. "```json\n\n```"), plus any caption/separator the model
+    // put in FRONT of the block. Without the second step the delivered answer
+    // ends on a dangling `---` — the visible half of the leak this recovers from.
+    const text = stripTrailingFollowupsHeader(cleaned.replace(/\n?```[a-z]*\s*\n?\s*```\s*/gi, '\n')).trim();
     return { text, calls };
 }
 /**
@@ -256,6 +308,16 @@ const MAX_PARALLEL_READS = 4;
 // half-done and resumable in-context. These defaults resume the SAME turn a
 // bounded number of times — the model keeps its thread, completed tool calls
 // are never re-run, and the loop can never spin forever.
+/**
+ * Consecutive REASONING-ONLY steps the loop tolerates before it escalates, and
+ * then one more before it ends the turn.
+ *
+ * Small on purpose. A `<think>`-then-answer model needs a step or two, so the
+ * limit cannot be zero — but unbounded, this path is a spin: two live eval runs
+ * produced 31 reasoning-only steps, one tool call, and a 0% score on a task they
+ * were well able to do (see `THINK_ONLY_ESCALATION`).
+ */
+export const MAX_THINK_CONTINUES = 3;
 /** Default continuations granted per turn when the option is omitted. */
 export const DEFAULT_MAX_CONTINUATIONS = 2;
 /** Default extra steps granted per continuation. */
@@ -295,6 +357,30 @@ async function runToolLoopInner(opts, progress) {
     // G13 — bounded "the request already authorized this" nudges (see
     // detectPermissionSeeking).
     let permissionNudges = 0;
+    // Stage 2 — the repetition nudge's own bound (see the block after the
+    // permission nudge). Separate from `permissionNudges` on purpose: that one
+    // asks the model to PROCEED, this one asks it to stop REPEATING, and the two
+    // fire on independent evidence.
+    let repeatNudges = 0;
+    // Bounded think-only continuation (see THINK_ONLY_ESCALATION). Counts the
+    // consecutive reasoning-only steps so the loop cannot spin on them.
+    let thinkContinues = 0;
+    // G13b — bounded "the request asked for a file and none was written" nudges
+    // (see wantsAuthoredArtifact).
+    let deliverableNudges = 0;
+    /**
+     * G18 — the sink, wrapped so an observability failure can never become a
+     * turn failure (a recorder that throws is a bug in the instrument, not in
+     * the work being observed).
+     */
+    const traceEvent = (event) => {
+        try {
+            opts.onTraceEvent?.(event);
+        }
+        catch {
+            // Best-effort.
+        }
+    };
     // The EFFECTIVE bound: starts at maxSteps and is extended (never beyond the
     // continuation budget) so a turn that still has work can finish.
     let stepLimit = maxSteps;
@@ -325,6 +411,45 @@ async function runToolLoopInner(opts, progress) {
     // gate exactly as it was.
     const requestText = lastUserText(opts.messages);
     const authorization = requestAuthorizesWrites(requestText);
+    // ── INTENT ENVELOPE (the durable grant) ──────────────────────────────────
+    // `writesAuthorized` above answers "does the LAST message ask for files?" —
+    // once per turn, and forgotten at the turn boundary. That is why permission
+    // was re-asked for every operation and why an approval given minutes ago was
+    // worth nothing on the next turn. The envelope is the same verdict as a
+    // DURABLE, SCOPED object, keyed to the conversation (the dashboard console
+    // keeps one plan store per session and re-injects it every turn; the CLI keeps
+    // one per ChatCommand), so an approval outlives the turn that granted it.
+    //
+    // Grant order is deliberate: an APPROVED PLAN is the high-trust path (the user
+    // saw the plan and said yes), then a fresh directive request, then whatever is
+    // still live for this conversation.
+    const envelopeKey = isEnvelopeKey(context.planStore) ? context.planStore : undefined;
+    let envelope = getEnvelope(envelopeKey);
+    if (envelopeKey) {
+        const plan = context.planStore?.snapshot?.() ?? null;
+        if (plan && isAffirmativeReply(requestText)) {
+            envelope = envelopeFromPlan(plan.goal);
+            grantEnvelope(envelopeKey, envelope);
+            deps.onEvent?.('   ✅ Plan approved — running it under one grant; no per-step permission.');
+        }
+        else {
+            const fresh = envelopeFromRequest(requestText);
+            if (fresh) {
+                envelope = fresh;
+                grantEnvelope(envelopeKey, fresh);
+            }
+        }
+    }
+    // ── RUN TRACE (the loop's representation of its own behaviour) ────────────
+    // The envelope above answers "what may I do"; the trace answers "what have I
+    // been DOING" — the question nothing in the architecture could answer, which
+    // is why it could not notice its own loop and could not respond to a user
+    // asking about one. Keyed to the conversation like the envelope, with a
+    // per-turn fallback when there is no session handle so repetition WITHIN a
+    // single turn is still caught.
+    const traceKey = isTraceKey(context.planStore) ? context.planStore : undefined;
+    const runTrace = traceKey ? runTraceFor(traceKey) : new RunTrace();
+    progress.runTrace = runTrace;
     const ctx = {
         ...context,
         followups: context.followups || sink,
@@ -334,6 +459,11 @@ async function runToolLoopInner(opts, progress) {
         // ask for a commit? resolve to this CLI command?), and a single boolean
         // computed for a different question cannot answer any of them.
         authorizationRequest: requestText,
+        // The durable grant every gate consults FIRST (see learning/intent-envelope.ts).
+        envelope,
+        // 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,
     };
     // Resolve the tool set — stable JSON schemas for every native step
     // (derived from the registry's zod schemas, single source of truth).
@@ -389,6 +519,28 @@ async function runToolLoopInner(opts, progress) {
         return added;
     };
     const thread = [...messages];
+    // ── 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
+    // indifference, but because nothing held the fact that it had asked four
+    // times. Handing the trace in makes the honest answer possible; the framing
+    // line keeps it from being mistaken for a plan.
+    if (detectProcessComplaint(requestText)) {
+        deps.onEvent?.('   🪞 The user asked about your own behaviour — answering from the run trace.');
+        traceEvent({
+            kind: 'gate',
+            gate: 'repeat',
+            summary: `the user asked about the agent's own behaviour — trace provided (${runTrace.countAsks()} ask(s), ${runTrace.repeatedAskCount()} repeated)`,
+        });
+        thread.push({
+            role: 'system',
+            content: `${runTrace.selfReport()}\n\n` +
+                'The user is asking about THIS behaviour, not about the code. Answer them directly: ' +
+                'state what you did (how many questions you asked, which one you repeated, and what they ' +
+                'answered), acknowledge the repetition plainly if there was one, and say what you will do ' +
+                'instead. Do not answer a question about your own process with a plan for the work.',
+        });
+    }
     const 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).
@@ -525,7 +677,7 @@ async function runToolLoopInner(opts, progress) {
         // console, gateway) recovers the calls, and strip the block from the
         // visible answer either way: a raw `{"tool":…}` block must never be the
         // answer. Idempotent with the JSON transport (which already strips it).
-        if (response.toolCalls.length === 0 && response.content.includes('"tool"')) {
+        if (response.toolCalls.length === 0 && TEXTUAL_TOOL_CALL_HINT.test(response.content)) {
             const extracted = extractFallbackToolCalls(response.content);
             if (extracted.text !== response.content) {
                 response.content = extracted.text;
@@ -557,8 +709,63 @@ async function runToolLoopInner(opts, progress) {
             if (deps.isThinkOnly ? deps.isThinkOnly(response.content) : isThinkOnlyResponse(response.content)) {
                 // Feed an empty assistant step so the model continues in-context.
                 thread.push({ role: 'assistant', content: response.content });
-                deps.onEvent?.('   🧠 model reasoning… (continuing)');
-                continue;
+                thinkContinues += 1;
+                // AN EMPTY RESPONSE IS A FAILURE, NOT REASONING. `isThinkOnlyResponse('')`
+                // returns true, so a provider returning nothing (the loop arm falls over
+                // to `local/gpt-oss:120b-cloud`, which reliably returns length 0) was
+                // reported as "model reasoning… (continuing)" — the system's own evidence
+                // saying the agent was thinking when it was being handed nothing. That
+                // 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;
+                // 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
+                // a 0% score, printing "model reasoning… (continuing)" the whole way.
+                if (thinkContinues <= MAX_THINK_CONTINUES) {
+                    deps.onEvent?.(emptyResponse
+                        ? `   ⚠️ the provider returned an EMPTY response (${thinkContinues}/${MAX_THINK_CONTINUES}) — retrying the step.`
+                        : `   🧠 model reasoning… (continuing ${thinkContinues}/${MAX_THINK_CONTINUES})`);
+                    traceEvent({
+                        kind: 'decision',
+                        summary: emptyResponse
+                            ? 'the provider returned an empty response — no answer text and no tool call; the step was retried'
+                            : 'the model replied with its own reasoning instead of an answer — the step continued',
+                    });
+                    continue;
+                }
+                if (thinkContinues === MAX_THINK_CONTINUES + 1) {
+                    // One escalation: it has no answer yet, so tell it to act or answer.
+                    stepLimit += 1;
+                    deps.onEvent?.(emptyResponse
+                        ? '   ⚠️ The provider keeps returning empty responses — asking for one real step.'
+                        : '   🧠 Reasoning only, repeatedly — telling the model to act or answer now.');
+                    traceEvent({
+                        kind: 'gate',
+                        gate: 'repeat',
+                        summary: emptyResponse
+                            ? `the provider returned an empty response ${thinkContinues} times — one bounded escalation for a real step`
+                            : `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 });
+                    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.
+                bounded = true;
+                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.');
+                traceEvent({
+                    kind: 'gate',
+                    gate: 'repeat',
+                    summary: emptyResponse
+                        ? `the provider returned ${thinkContinues} consecutive empty responses — the turn ended; this is a transport failure, not agent stuckness`
+                        : `reasoning-only output repeated ${thinkContinues} times after an escalation — the turn ended to avoid an unbounded spin`,
+                });
+                break;
             }
             // ── Dangling-promise nudge (bounded, once) ──────────────────────────
             // The model closed the turn announcing what it is ABOUT to do ("I will
@@ -576,6 +783,11 @@ async function runToolLoopInner(opts, progress) {
                 intentNudges += 1;
                 stepLimit += 1;
                 deps.onEvent?.('   🔁 Answer announced an action but performed none — asking the model to carry it out.');
+                traceEvent({
+                    kind: 'gate',
+                    gate: 'promise',
+                    summary: 'the turn closed on an announced action with nothing performed — one bounded nudge to carry it out',
+                });
                 // The promise is NOT a candidate answer: drop it from the
                 // longest-substantive memory so the post-nudge answer (or result) is
                 // what the turn delivers. Safe because the gate only fires when no
@@ -608,6 +820,11 @@ async function runToolLoopInner(opts, progress) {
                 permissionNudges += 1;
                 stepLimit += 1;
                 deps.onEvent?.('   🤖 Turn ended asking permission for work the request already authorized — telling the model to proceed.');
+                traceEvent({
+                    kind: 'gate',
+                    gate: 'permission',
+                    summary: `the turn asked permission for authorized work (${authorization.reason}) — one bounded nudge to proceed`,
+                });
                 // The question must not become the delivered answer. When nothing was
                 // done this turn the whole step is the question, so drop it. When real
                 // work WAS done, keep the work and cut only the trailing question —
@@ -623,12 +840,65 @@ async function runToolLoopInner(opts, progress) {
                 thread.push({ role: 'user', content: AUTHORIZED_WORK_NUDGE });
                 continue;
             }
+            // ── Stage 2 — REPETITION nudge (bounded, once) ───────────────────────
+            // The permission nudge above fires only when the request AUTHORIZED the
+            // work, and it asks the model to PROCEED. A repeated question is a defect
+            // on its own terms: the user already answered it, whatever their latest
+            // message authorized — which is precisely the case a live turn fell
+            // through, because the complaint about repeated questions was itself the
+            // message that failed to authorize. This nudge therefore does NOT depend
+            // on authorization, and deliberately does NOT say "proceed" (unsafe when
+            // the answer was no) — it says the answer is in hand, so act on it or say
+            // what blocks you. The evidence is the RUN TRACE, not the current text.
+            if (repeatNudges < 1 &&
+                schemas.length > 0 &&
+                detectPermissionSeeking(response.content.length >= lastContent.length ? response.content : lastContent) &&
+                runTrace.priorAskMatches(response.content.length >= lastContent.length ? response.content : lastContent).length > 0) {
+                const closing = response.content.length >= lastContent.length ? response.content : lastContent;
+                repeatNudges += 1;
+                stepLimit += 1;
+                deps.onEvent?.('   🔁 The turn asked a question the user has already answered — telling the model to act on the answer.');
+                traceEvent({
+                    kind: 'gate',
+                    gate: 'repeat',
+                    summary: 'the turn repeated a question already asked and answered in this conversation — one bounded nudge to use the answer',
+                });
+                if (progress.successfulToolCalls.length === 0) {
+                    lastContent = '';
+                }
+                else {
+                    lastContent = stripTrailingPermissionSeek(closing);
+                }
+                thread.push({ role: 'assistant', content: response.content });
+                thread.push({ role: 'user', content: repeatNudge(closing, runTrace.priorAnswer(closing)) });
+                continue;
+            }
             // S1 (both exits): the MOST SUBSTANTIVE content seen wins here too —
             // a short closing step ("Sent it to her! ✅") with no tool calls must
             // not clobber the deliverable (poem/essay) the model composed in an
             // earlier step alongside a real tool call. Same rule as the
             // suggest_followups exit below.
             //
+            // G13b — DELIVERABLE GATE (no-tools path, the one a story ask actually
+            // takes). Same rule and same bounded budget as the concluding path BELOW,
+            // placed before it so the first ending that can satisfy the request gets
+            // the nudge, never both.
+            if (deliverableNudges < 1 && deliverableGateApplies(opts, response.content.length >= lastContent.length ? response.content : lastContent, progress, schemas.length, requestText)) {
+                deliverableNudges += 1;
+                stepLimit += 1;
+                deps.onEvent?.('   📄 The request asked for a file and none was written — asking the model to produce it.');
+                traceEvent({
+                    kind: 'gate',
+                    gate: 'deliverable',
+                    summary: authorization.requestedPath
+                        ? `an authored deliverable was requested at ${authorization.requestedPath} and no file was written — one bounded nudge to produce it`
+                        : '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) });
+                continue;
+            }
+            //
             // G1 — VERIFICATION GATE: before the turn can end, if it MUTATED the
             // workspace and ran nothing that observed the result, spend ONE bounded
             // nudge asking for the check. The gate is deliberately a nudge, not a
@@ -643,8 +913,20 @@ async function runToolLoopInner(opts, progress) {
                 verificationNudges += 1;
                 stepLimit += 1;
                 deps.onEvent?.('   🔎 Files were changed but nothing verified them — asking the model to run a check.');
+                traceEvent({
+                    kind: 'gate',
+                    gate: 'verification',
+                    summary: 'the turn mutated the workspace and nothing observed the result — one bounded nudge to verify',
+                });
                 thread.push({ role: 'assistant', content: response.content });
-                thread.push({ role: 'user', content: VERIFICATION_NUDGE });
+                // Stage 3 — name THIS project's strongest check instead of describing a
+                // 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),
+                });
                 continue;
             }
             return {
@@ -721,6 +1003,9 @@ async function runToolLoopInner(opts, progress) {
             return { call };
         });
         // ── Phase 2 — execute (read-only runs fan out; everything else serial) ──
+        /** Wall-clock per call id, so the G18 event can carry a real duration
+         *  without re-timing (the emit below is the only place that knows it). */
+        const toolDurations = new Map();
         const runOne = async (plan) => {
             const { call } = plan;
             if (plan.refuse !== undefined)
@@ -771,6 +1056,9 @@ async function runToolLoopInner(opts, progress) {
                 });
                 return `Error: ${message}`;
             }
+            finally {
+                toolDurations.set(call.id, Date.now() - startedAt);
+            }
         };
         const executed = new Array(plans.length).fill('');
         for (let i = 0; i < plans.length;) {
@@ -816,7 +1104,17 @@ async function runToolLoopInner(opts, progress) {
             // not a success, and a delivery tool only counts when it reported `✅`).
             // `toolCallsRun` stays the attempted list for telemetry; these two drive
             // the honesty flag and the trace outcome.
-            const ranOk = !rawResult.startsWith('Error:') &&
+            // A DECLINED call is not a success, whatever prefix it used. Found live on
+            // the first G18 verification run: `write_file` refused an absolute path
+            // that escaped the workspace and returned "… escapes the workspace … —
+            // denied" with NO `Error:` prefix, so the loop counted it as a call that
+            // RAN, pushed it to `successfulToolCalls`, and recorded it in the trace as
+            // "write_file ran". That is the exact shape G18 exists to eliminate — an
+            // outcome reading the same as its opposite — so the refusal classifier is
+            // now the authority for both the event KIND and the success verdict.
+            const refusal = classifyToolRefusal(rawResult);
+            const ranOk = refusal === null &&
+                !rawResult.startsWith('Error:') &&
                 (!DELIVERY_TOOL_NAMES.has(call.name) || deliveryResultSucceeded(rawResult));
             if (ranOk)
                 progress.successfulToolCalls.push(call.name);
@@ -830,13 +1128,25 @@ async function runToolLoopInner(opts, progress) {
                 if (call.name === 'edit_file' || call.name === 'write_file') {
                     const a = call.arguments;
                     const p = a?.path ?? a?.file_path ?? a?.file;
-                    if (typeof p === 'string' && p)
+                    if (typeof p === 'string' && p) {
                         progress.mutatedPaths.push(p);
+                        // 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.
+                        runTrace.recordMutation(call.name, p);
+                    }
                 }
                 else if (isVerificationTool(call.name)) {
                     progress.verificationEvidence.push({ tool: call.name, args: call.arguments, result: rawResult });
                 }
             }
+            else if (refusal !== null || rawResult.startsWith('Error:')) {
+                // Stage 2 — the other half of noticing a loop: the SAME refusal, twice.
+                // The run records it with its reason, so a later step (or a self-report)
+                // can see "blocked twice, identically" instead of rediscovering it — and
+                // so the repetition gate has a refusal signal as well as an ask signal.
+                runTrace.recordRefusal(call.name, refusal?.gate ?? 'error', rawResult);
+            }
             let resultText = executed[i];
             // P3c — on error/denial, append the deterministic fallback hint for
             // this tool (advisory — the model still decides; never on success).
@@ -849,6 +1159,24 @@ async function runToolLoopInner(opts, progress) {
             if (parallelTip)
                 resultText = `${resultText}\n\n${parallelTip}`;
             delivered[i] = resultText;
+            // G18 — record what this call DID, in the model's own call order, with the
+            // evidence a later reader needs: the args the gate saw, the first line of
+            // the result, the verdict, and the wall-clock. A declined call is recorded
+            // as a REFUSAL with its cause, so "nothing happened here" can never again
+            // read the same as "nothing was refused" (see classifyToolRefusal).
+            // `rawResult` is the pre-decoration text — hints and tips are the loop's
+            // own additions and must not be mistaken for what the tool returned.
+            const durationMs = toolDurations.get(call.id);
+            traceEvent({
+                kind: ranOk ? 'tool' : 'refusal',
+                tool: call.name,
+                ...(refusal?.gate ? { gate: refusal.gate } : {}),
+                summary: ranOk ? `${call.name} ran` : refusal?.summary ?? `${call.name} returned an error`,
+                args: summarizeArgs(call.arguments),
+                result: previewToolResult(rawResult),
+                ok: ranOk,
+                ...(durationMs !== undefined ? { durationMs } : {}),
+            });
             thread.push({ role: 'tool', toolCallId: call.id, content: resultText });
         }
         // Tiered exposure: after EVERY executed tool call, union any newly
@@ -923,8 +1251,38 @@ async function runToolLoopInner(opts, progress) {
                 verificationNudges += 1;
                 stepLimit += 1;
                 deps.onEvent?.('   🔎 Files were changed but nothing verified them — asking the model to run a check.');
+                traceEvent({
+                    kind: 'gate',
+                    gate: 'verification',
+                    summary: 'the turn mutated the workspace and nothing observed the result — one bounded nudge to verify',
+                });
+                thread.push({ role: 'assistant', content: response.content });
+                // Stage 3 — name THIS project's strongest check instead of describing a
+                // 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),
+                });
+                continue;
+            }
+            // G13b — DELIVERABLE GATE (concluding path). AFTER the verification gate
+            // on purpose: a turn that wrote nothing has nothing to verify, so the two
+            // cannot both apply, and this order leaves edit turns byte-identical.
+            if (deliverableNudges < 1 && deliverableGateApplies(opts, response.content.length >= lastContent.length ? response.content : lastContent, progress, schemas.length, requestText)) {
+                deliverableNudges += 1;
+                stepLimit += 1;
+                deps.onEvent?.('   📄 The request asked for a file and none was written — asking the model to produce it.');
+                traceEvent({
+                    kind: 'gate',
+                    gate: 'deliverable',
+                    summary: authorization.requestedPath
+                        ? `an authored deliverable was requested at ${authorization.requestedPath} and no file was written — one bounded nudge to produce it`
+                        : '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: VERIFICATION_NUDGE });
+                thread.push({ role: 'user', content: deliverableNudge(authorization.requestedPath) });
                 continue;
             }
             const content = response.content.length >= lastContent.length ? response.content : lastContent;
@@ -942,6 +1300,11 @@ async function runToolLoopInner(opts, progress) {
     // extends the bound otherwise) — the turn is honestly bounded.
     bounded = true;
     deps.onEvent?.(`   ⚠️ Tool loop reached its ${stepLimit}-step budget — returning the last response.`);
+    traceEvent({
+        kind: 'decision',
+        gate: 'budget',
+        summary: `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.',
         followups,
@@ -1092,6 +1455,8 @@ export async function runToolLoop(opts) {
     if (!result.cancelled && !result.generationFailed) {
         result.successfulToolCalls = [...progress.successfulToolCalls];
         result.deliveryConfirmed = progress.deliveryConfirmed;
+        // Stage 2 — the turn's own behaviour, as counts (see learning/run-trace.ts).
+        result.runTrace = progress.runTrace?.snapshot();
         // Judge the "I have sent it" claim against what actually DELIVERED, not
         // against the attempted tool list — a failed gateway_send must not silence
         // the honesty correction.
@@ -1117,9 +1482,55 @@ export async function runToolLoop(opts) {
         if (detectUnverifiedEditClaim(result.content, activity.mutations, activity.verifications)) {
             result.unverifiedEditClaim = true;
         }
+        // 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
+        // "finished" by any caller, whether or not the gate was enabled.
+        if (!result.cancelled &&
+            progress.mutatedPaths.length === 0 &&
+            !replyAsksTheReader(result.content) &&
+            wantsAuthoredArtifact(lastUserText(opts.messages))) {
+            result.undeliveredArtifact = true;
+        }
     }
     return result;
 }
+/**
+ * Does the DELIVERABLE gate apply to this turn (G13b)?
+ *
+ * The conjunction is the whole point, and every term is an independent fact:
+ *
+ *   - the request asks for an AUTHORED deliverable to be PRODUCED
+ *     (`wantsAuthoredArtifact` — the same predicate the engine router uses, so
+ *     "what the user asked for" is defined once);
+ *   - the turn wrote NOTHING (`mutatedPaths` is the loop's own evidence that a
+ *     write landed, so a turn that used a heredoc through `run_terminal` is not
+ *     nudged for a file it already wrote);
+ *   - tools are actually available (a caller that exposed none cannot comply);
+ *   - the turn did not END on a question to the reader (`replyAsksTheReader`).
+ *     This is the line between the two failures that look alike: "Do you want me
+ *     to create the files?" is a stall, and the permission nudge already settles
+ *     it above; "Which of these two titles do you prefer?" is a decision input
+ *     the user asked to be consulted on, and bulldozing it would be the manual
+ *     -cadence complaint in reverse;
+ *   - the bound is unspent, and the caller has not disabled the gate.
+ *
+ * A turn that already wrote something is deliberately out of scope: the gate is
+ * about the artifact never being produced, not about the artifact being short.
+ */
+function deliverableGateApplies(opts, content, progress, schemaCount, requestText) {
+    if (opts.requireDeliverable === false)
+        return false;
+    if (schemaCount === 0)
+        return false;
+    if (progress.mutatedPaths.length > 0)
+        return false;
+    if (!requestText.trim())
+        return false;
+    if (replyAsksTheReader(content))
+        return false;
+    return wantsAuthoredArtifact(requestText);
+}
 /**
  * The text of the LAST user message in the thread — what the user is actually
  * asking for right now, as opposed to the history above it. Used to derive
@@ -1138,6 +1549,62 @@ function lastUserText(messages) {
     }
     return '';
 }
+/**
+ * One bounded line from a tool result — the EVIDENCE a gate verdict read (G18).
+ *
+ * The first non-empty line, whitespace-collapsed: enough to tell an applied edit
+ * from a declined one ("Error: write_file: … needs explicit confirmation"), a
+ * failing test from a passing one, without pasting a whole file into the trace
+ * store. The store keeps the tail of a long run; a full result per call would
+ * push the interesting end of the turn out of it.
+ */
+function previewToolResult(result, max = 200) {
+    const first = (result || '').split(/\r?\n/).find((line) => line.trim() !== '') ?? '';
+    const flat = first.replace(/\s+/g, ' ').trim();
+    return flat.length > max ? `${flat.slice(0, max)}\u2026` : flat;
+}
+/**
+ * Classify a DECLINED call's result text (G18).
+ *
+ * The single class this exists for is the confirmation refusal: a tool that
+ * says "call ask_user first, then retry with confirm:true" has not failed — it
+ * has handed the decision to the user, and that is exactly the event the trace
+ * store could not see at all (the G18 audit read "0 refusals" and could not
+ * tell it from "no refusals"). The remaining cases are the loop's own guards,
+ * named so the record distinguishes *why* work did not happen: a guard is not a
+ * provider error — the turn can continue either way, and only the record knows.
+ *
+ * Returns null when the result is an ordinary tool/runtime error, so the caller
+ * keeps its own wording rather than inventing a cause.
+ */
+export function classifyToolRefusal(result) {
+    const text = result || '';
+    if (/needs explicit confirmation|requires confirmation|retry with confirm|call ask_user/i.test(text)) {
+        return { gate: 'confirmation', summary: 'declined until the user approves — the gate asked before acting' };
+    }
+    // A BOUNDARY denial is the other refusal that did not read as one. The
+    // workspace guard returns "… escapes the workspace (…) — denied" with no
+    // `Error:` prefix, so it counted as a successful call (found live). Anchored
+    // to the boundary phrasings rather than the bare word "denied", because a
+    // `run_terminal` that reads a log containing "Permission denied" is a
+    // successful call, not a refusal.
+    if (/escapes the workspace|outside the workspace|outside the project|outside this project|not allowed by the workspace/i.test(text)) {
+        return { gate: 'workspace', summary: 'declined — the path is outside the workspace the tools may touch' };
+    }
+    if (/already called|already dispatched/i.test(text)) {
+        return { summary: 'declined by the loop guard — that dispatch already happened this turn' };
+    }
+    if (/^Error: unknown tool/i.test(text)) {
+        return { summary: 'declined — the model called a tool that is not on its surface' };
+    }
+    if (/toolset is not loaded this turn/i.test(text)) {
+        return { summary: 'declined — that tool\'s toolset was never loaded this turn' };
+    }
+    if (/is disabled — its toolset is turned off/i.test(text)) {
+        return { summary: 'declined — the tool is turned off in configuration' };
+    }
+    return null;
+}
 /** Compact argument preview for the event line. */
 function summarizeArgs(args) {
     const first = Object.entries(args).slice(0, 1)[0];