@gaunt-sloth/core 2.0.0-beta.2 → 2.0.0-beta.4

package/dist/config/shell-policy.d.ts

@@ -591,7 +591,7 @@ export declare function isToolGatedAtRung(options: {
  * summary (§4.4) are both built from this, so neither can tell the model a tool is free while the
  * gate escalates it.
  *
- * **It is NOT what the backends wire into the interrupt.** That is
+ * **It is NOT what the agent wires into the interrupt.** That is
  * {@link resolveInterruptToolNames}, and the two are different sets on purpose: the interrupt is
  * installed once, at agent init, while `/approvals <rung>` moves the rung underneath it for the rest
  * of the session. A set that carried the rung would be frozen at the rung the session started on —
@@ -626,7 +626,7 @@ export declare function resolveGatedToolNames(options: {
  */
 export declare function commandAnswersApprovals(command: GthCommand | undefined): boolean;
 /**
- * **The interrupt set: which tool names the backends wire into the approval interrupt.** Every bound
+ * **The interrupt set: which tool names the agent wires into the approval interrupt.** Every bound
  * tool that ANY rung could gate — the union of {@link resolveGatedToolNames} over
  * {@link APPROVAL_RUNGS}, which in practice is the shell plus every bound tool that is not a
  * built-in READ tool.

package/dist/config/shell-policy.js

@@ -660,7 +660,7 @@ export function isToolGatedAtRung(options) {
  * summary (§4.4) are both built from this, so neither can tell the model a tool is free while the
  * gate escalates it.
  *
- * **It is NOT what the backends wire into the interrupt.** That is
+ * **It is NOT what the agent wires into the interrupt.** That is
  * {@link resolveInterruptToolNames}, and the two are different sets on purpose: the interrupt is
  * installed once, at agent init, while `/approvals <rung>` moves the rung underneath it for the rest
  * of the session. A set that carried the rung would be frozen at the rung the session started on —
@@ -695,7 +695,7 @@ export function resolveGatedToolNames(options) {
  * unanswered. Measured, not inferred.
  *
  * So a command that answers nothing must be handed **no approval interrupt beyond what the shell
- * gate itself requires** — see the `interruptTools` wiring in both backends. In particular it must
+ * gate itself requires** — see the `interruptTools` wiring in the agent. In particular it must
  * NOT be handed the LIVE set for its configured rung: that set is non-empty at `manual` and
  * `write`, so it carries exactly the same trap, and `commands.api.approvals` (plus a root-level
  * `approvals`, which applies to every command) puts an ordinary config on those rungs.
@@ -735,7 +735,7 @@ export function commandAnswersApprovals(command) {
     return command === undefined ? true : (COMMAND_ANSWERS_APPROVALS[command] ?? true);
 }
 /**
- * **The interrupt set: which tool names the backends wire into the approval interrupt.** Every bound
+ * **The interrupt set: which tool names the agent wires into the approval interrupt.** Every bound
  * tool that ANY rung could gate — the union of {@link resolveGatedToolNames} over
  * {@link APPROVAL_RUNGS}, which in practice is the shell plus every bound tool that is not a
  * built-in READ tool.

package/dist/config/tool-descriptions.d.ts

@@ -17,7 +17,7 @@
  * 2. **The suffix is derived from the rung in force AND from the set of tools that rung actually
  *    gates.** "A description that disagrees with what the gate will actually do is worse than no
  *    description at all" (§4.5), so {@link isGrantedAtRung} takes the LIVE gated set as a parameter
- *    and both backends pass the SAME `resolveGatedToolNames` result. The two can therefore not
+ *    and the agent passes the SAME `resolveGatedToolNames` result. The two can therefore not
  *    drift: widening what a rung gates ([[EXT-30]]) widens the descriptions in the same breath.
  *    That set is narrower than the rung-independent one wired into the interrupt
  *    (`resolveInterruptToolNames`), because a call the live rung does not gate is approved on
@@ -25,7 +25,7 @@
  *
  * **Scope, per §4.3.** The *rater* covers the shell only: every other gated tool goes to the human
  * without a rating call until [[EXT-30]] widens the rater. The *gate* is wider than the rater. At
- * the two deterministic rungs (`manual`, `write`) both backends gate every bound tool the rung's
+ * the two deterministic rungs (`manual`, `write`) the agent gates every bound tool the rung's
  * access class does not auto-grant — the write built-ins, the shell, MCP tools (whatever their
  * `readOnlyHint` says) and custom tools — so at those rungs a non-granted call always reaches the
  * human. At `assisted`, `auto` and `bypass` the gated set is the shell alone.
@@ -132,7 +132,7 @@ export declare function getRungToolDescriptionSuffix(rung: ApprovalRung): string
  *
  * **This is the one implementation of that rule.** {@link isGrantedAtRung} decides a grant with it,
  * and `config/shell-policy.ts`'s `isToolGatedAtRung` decides gated-set membership with it — which
- * is in turn what the backends' interrupt set and `GthAgentRunner`'s own live-rung check are built
+ * is in turn what the agent's interrupt set and `GthAgentRunner`'s own live-rung check are built
  * from. So the gate cannot escalate a call the descriptions and the rater's granted list call free
  * — the drift §4.5 names as worse than having no description at all. Two derivations of one rule is
  * exactly what this function exists to prevent; do not inline it back into either caller.
@@ -150,7 +150,7 @@ export declare function isAccessClassGrantedAtRung(toolName: string, rung: Appro
  *   `resolveGatedToolNames` for the rung in force. **This is the parameter that keeps the
  *   descriptions honest**: a tool the rung does not gate cannot require approval, whatever a rung's
  *   table row says about tool classes, so it is granted. It is deliberately NOT the wider,
- *   rung-independent set the backends wire into `interruptOn` (`resolveInterruptToolNames`): a call
+ *   rung-independent set the agent wires into `interruptOn` (`resolveInterruptToolNames`): a call
  *   the live rung does not gate is auto-approved the moment it arrives at the runner, so describing
  *   it as needing approval would be a promise nothing keeps.
  *
@@ -182,7 +182,7 @@ export interface DescribableTool {
  * that is NOT auto-approved at that rung, and leave every granted tool's description untouched.
  *
  * Mutates in place (and returns the same array): the tools are about to be handed to
- * `createAgent`/`createDeepAgent`, and the array is freshly resolved per init. Idempotent — any
+ * `createAgent`, and the array is freshly resolved per init. Idempotent — any
  * previously-appended suffix is stripped first, so re-registration at a different rung replaces
  * the sentence rather than stacking one.
  *

package/dist/config/tool-descriptions.js

@@ -142,7 +142,7 @@ export function getRungToolDescriptionSuffix(rung) {
  *
  * **This is the one implementation of that rule.** {@link isGrantedAtRung} decides a grant with it,
  * and `config/shell-policy.ts`'s `isToolGatedAtRung` decides gated-set membership with it — which
- * is in turn what the backends' interrupt set and `GthAgentRunner`'s own live-rung check are built
+ * is in turn what the agent's interrupt set and `GthAgentRunner`'s own live-rung check are built
  * from. So the gate cannot escalate a call the descriptions and the rater's granted list call free
  * — the drift §4.5 names as worse than having no description at all. Two derivations of one rule is
  * exactly what this function exists to prevent; do not inline it back into either caller.
@@ -167,7 +167,7 @@ export function isAccessClassGrantedAtRung(toolName, rung) {
  *   `resolveGatedToolNames` for the rung in force. **This is the parameter that keeps the
  *   descriptions honest**: a tool the rung does not gate cannot require approval, whatever a rung's
  *   table row says about tool classes, so it is granted. It is deliberately NOT the wider,
- *   rung-independent set the backends wire into `interruptOn` (`resolveInterruptToolNames`): a call
+ *   rung-independent set the agent wires into `interruptOn` (`resolveInterruptToolNames`): a call
  *   the live rung does not gate is auto-approved the moment it arrives at the runner, so describing
  *   it as needing approval would be a promise nothing keeps.
  *
@@ -214,7 +214,7 @@ export function stripRungToolDescriptionSuffix(description) {
  * that is NOT auto-approved at that rung, and leave every granted tool's description untouched.
  *
  * Mutates in place (and returns the same array): the tools are about to be handed to
- * `createAgent`/`createDeepAgent`, and the array is freshly resolved per init. Idempotent — any
+ * `createAgent`, and the array is freshly resolved per init. Idempotent — any
  * previously-appended suffix is stripped first, so re-registration at a different rung replaces
  * the sentence rather than stacking one.
  *

package/dist/core/GthAbstractAgent.d.ts

@@ -9,6 +9,7 @@ import { BaseToolkit, StructuredToolInterface } from '@langchain/core/tools';
 import { IterableReadableStream } from '@langchain/core/utils/stream';
 import { BaseCheckpointSaver } from '@langchain/langgraph';
 import { type RefusalInfo } from '#src/core/refusal.js';
+import { type GthFinishReasonObservation, type GthTerminationReason, type GthTerminationSite } from '#src/core/terminationReason.js';
 /**
  * Shared, graph-agnostic agent plumbing.
  *
@@ -70,6 +71,19 @@ export declare abstract class GthAbstractAgent implements GthAgentInterface {
      * fully fail-soft (accumulation is guarded and never throws into a run).
      */
     private runStatsAcc;
+    /**
+     * [[EXT-159]] — why the current turn ended, set by whichever site inside this agent ended it.
+     * Reset at each turn boundary by {@link resetTerminationReason}, read by `GthAgentRunner`.
+     */
+    private terminationReason;
+    /**
+     * [[EXT-159]] — what the provider said about why each finished model message stopped, this turn.
+     *
+     * Reset with {@link terminationReason} at each turn boundary and read by `GthAgentRunner` for the
+     * debug dump. Bounded, because a long agentic turn produces one entry per model round and this
+     * has to be safe to keep for the whole session.
+     */
+    private finishReasonObservations;
     /**
      * EXT-58 — the names of the tools registered with the graph at the last {@link init}, recorded by
      * {@link registerApprovalsAwareTools}. Read by `GthAgentRunner` to build the rater's
@@ -132,7 +146,7 @@ export declare abstract class GthAbstractAgent implements GthAgentInterface {
      */
     protected compactHeaderStatus(): void;
     /**
-     * EXT-58 (spec §4.5) — the ONE tool-registration hook both backends call with their final tool
+     * EXT-58 (spec §4.5) — the ONE tool-registration hook every backend calls with its final tool
      * array, just before handing it to the graph builder. It does two things:
      *
      * 1. Appends the rung's approval sentence to every tool that is **not** auto-approved at that
@@ -189,6 +203,51 @@ export declare abstract class GthAbstractAgent implements GthAgentInterface {
     getRunStats(): GthRunStats;
     /** GS2-16 — fold one message (or chunk) into the run tally. Fully guarded (fail-soft). */
     protected recordRunStats(message: unknown): void;
+    /**
+     * [[EXT-159]] — forget the previous turn's termination reason. Called by `GthAgentRunner` at each
+     * turn boundary, for the same reason {@link resetRunStats} is.
+     */
+    resetTerminationReason(): void;
+    /** [[EXT-159]] — why this turn ended, or `null` when no site inside this agent classified it. */
+    getTerminationReason(): GthTerminationReason | null;
+    /**
+     * [[EXT-159]] — what the provider said about why each model message stopped, this turn.
+     *
+     * A copy, so a reader (the debug dump) cannot mutate the live record. An EMPTY list is itself
+     * meaningful and is not the same as a list of absences: it says no finished model message was
+     * observed at all, where an entry with a `null` token says one was observed and the provider said
+     * nothing.
+     */
+    getFinishReasonObservations(): readonly GthFinishReasonObservation[];
+    /**
+     * [[EXT-159]] — record the provider's stop/finish reason for one finished model message, and
+     * write it to the debug log.
+     *
+     * Called on EVERY finished message rather than only on the interesting ones, because the fact
+     * this exists to capture is as much "the provider said nothing" as "the provider said `length`".
+     * The debug log is where a maintainer looks first and it carried none of this; the ring buffer
+     * behind `debugLog` is populated whether or not on-disk debug logging was ever switched on, so
+     * the observation reaches `/debug-dump` from a default install too.
+     *
+     * Fail-soft, and bounded: a long agentic turn logs one entry per model round.
+     */
+    protected noteFinishReason(path: GthFinishReasonObservation['path'], message: unknown): void;
+    /**
+     * [[EXT-159]] — record why the turn ended, **first-write-wins**.
+     *
+     * The sites that classify are nested: the metadata reader and the cancellation paths sit inside
+     * the stream, which sits inside the runner's catches. Last-write-wins would let each outer layer
+     * overwrite the truer inner classification with its own coarser one — which is exactly the funnel
+     * this taxonomy replaces, rebuilt one level up. Fail-soft: classification never throws into a run.
+     */
+    protected noteTermination(reason: GthTerminationReason): void;
+    /**
+     * [[EXT-159]] — run the metadata feeder over a finished message and record what it found.
+     *
+     * The metadata reader is the half of the taxonomy that only works here, at the layer where a
+     * message's `response_metadata` is visible. Returns whether anything was classified.
+     */
+    protected noteStopMetadata(site: GthTerminationSite, message: unknown): boolean;
     /**
      * GS2-16 — best-effort count of messages already in the checkpointed thread state, used by
      * {@link invoke} as the baseline so it harvests only THIS turn's new messages rather than the
@@ -253,6 +312,13 @@ export declare abstract class GthAbstractAgent implements GthAgentInterface {
      * the client sends in `forwardedProps.command.resume`.
      */
     streamWithEventsResume(resumeValue: unknown, runConfig: RunnableConfig, queuedMessages?: BaseMessage[], signal?: AbortSignal): AsyncGenerator<AgentStreamEvent>;
+    /**
+     * [[EXT-159]] — which of the two clean endings a typed-event stream just took.
+     *
+     * Shared by {@link streamWithEvents} and {@link streamWithEventsResume} so the pair cannot drift:
+     * they catch the same union and owe the same distinction.
+     */
+    private classifyEventStreamEnd;
     /**
      * Inspect the checkpointed state for the thread and return the tool calls currently pending
      * human approval (empty array when the run finished normally). A LangGraph

package/dist/core/GthAbstractAgent.js

@@ -12,10 +12,22 @@ import { AIMessage, AIMessageChunk, ToolMessage } from '@langchain/core/messages
 import { IterableReadableStream } from '@langchain/core/utils/stream';
 import { interrupt, Command, GraphInterrupt } from '@langchain/langgraph';
 import { extractInlineBinaryBlocks, materializeBinaryOutputs, renderAssistantContent, } from '#src/utils/binaryOutputUtils.js';
-import { detectRefusal, buildRefusalMessage } from '#src/core/refusal.js';
+import { classifyRefusal, detectRefusal, detectStopMetadata, buildRefusalMessage, readStopReasonToken, } from '#src/core/refusal.js';
+import { terminationReason, } from '#src/core/terminationReason.js';
+import { terminationLogLine } from '#src/core/terminationNotice.js';
 import { answerTextOf, segmentAssistantContent, stripReasoningBlocks, } from '#src/core/reasoningBlocks.js';
 const THINK_OPEN = '<think>';
 const THINK_CLOSE = '</think>';
+/**
+ * [[EXT-159]] — how many per-message `finish_reason` observations one turn keeps.
+ *
+ * An agentic turn produces one per model round and the list is held for the life of the turn, so it
+ * is bounded rather than trusted to stay small. The cap drops the TAIL rather than the head: the
+ * observations that explain how a turn ENDED are the last ones, but a turn that has already made a
+ * thousand model rounds has a different problem, and keeping the head keeps the record of how it
+ * got there. Every observation reaches the debug log either way, so nothing is lost outright.
+ */
+const FINISH_REASON_OBSERVATION_MAX = 1000;
 /**
  * TUI-C22 — length of the longest suffix of `s` that is a *proper* (shorter-than-full) prefix of
  * `tag`. Used by {@link createThinkTagSplitter} to hold back a trailing partial that might complete
@@ -259,6 +271,19 @@ export class GthAbstractAgent {
      * fully fail-soft (accumulation is guarded and never throws into a run).
      */
     runStatsAcc = createRunStatsAccumulator();
+    /**
+     * [[EXT-159]] — why the current turn ended, set by whichever site inside this agent ended it.
+     * Reset at each turn boundary by {@link resetTerminationReason}, read by `GthAgentRunner`.
+     */
+    terminationReason = null;
+    /**
+     * [[EXT-159]] — what the provider said about why each finished model message stopped, this turn.
+     *
+     * Reset with {@link terminationReason} at each turn boundary and read by `GthAgentRunner` for the
+     * debug dump. Bounded, because a long agentic turn produces one entry per model round and this
+     * has to be safe to keep for the whole session.
+     */
+    finishReasonObservations = [];
     /**
      * EXT-58 — the names of the tools registered with the graph at the last {@link init}, recorded by
      * {@link registerApprovalsAwareTools}. Read by `GthAgentRunner` to build the rater's
@@ -340,7 +365,7 @@ export class GthAbstractAgent {
         this.statusUpdate(StatusLevel.INFO, runHeaderLine(command, label));
     }
     /**
-     * EXT-58 (spec §4.5) — the ONE tool-registration hook both backends call with their final tool
+     * EXT-58 (spec §4.5) — the ONE tool-registration hook every backend calls with its final tool
      * array, just before handing it to the graph builder. It does two things:
      *
      * 1. Appends the rung's approval sentence to every tool that is **not** auto-approved at that
@@ -416,6 +441,95 @@ export class GthAbstractAgent {
     recordRunStats(message) {
         accumulateMessage(this.runStatsAcc, message);
     }
+    /**
+     * [[EXT-159]] — forget the previous turn's termination reason. Called by `GthAgentRunner` at each
+     * turn boundary, for the same reason {@link resetRunStats} is.
+     */
+    resetTerminationReason() {
+        this.terminationReason = null;
+        this.finishReasonObservations = [];
+    }
+    /** [[EXT-159]] — why this turn ended, or `null` when no site inside this agent classified it. */
+    getTerminationReason() {
+        return this.terminationReason;
+    }
+    /**
+     * [[EXT-159]] — what the provider said about why each model message stopped, this turn.
+     *
+     * A copy, so a reader (the debug dump) cannot mutate the live record. An EMPTY list is itself
+     * meaningful and is not the same as a list of absences: it says no finished model message was
+     * observed at all, where an entry with a `null` token says one was observed and the provider said
+     * nothing.
+     */
+    getFinishReasonObservations() {
+        return [...this.finishReasonObservations];
+    }
+    /**
+     * [[EXT-159]] — record the provider's stop/finish reason for one finished model message, and
+     * write it to the debug log.
+     *
+     * Called on EVERY finished message rather than only on the interesting ones, because the fact
+     * this exists to capture is as much "the provider said nothing" as "the provider said `length`".
+     * The debug log is where a maintainer looks first and it carried none of this; the ring buffer
+     * behind `debugLog` is populated whether or not on-disk debug logging was ever switched on, so
+     * the observation reaches `/debug-dump` from a default install too.
+     *
+     * Fail-soft, and bounded: a long agentic turn logs one entry per model round.
+     */
+    noteFinishReason(path, message) {
+        try {
+            // No message means no observation — NOT an observation of absence. A turn whose stream
+            // produced nothing to aggregate has no provider statement to be missing, and recording a
+            // `null` token for it would make "the provider said nothing about this message" and "there
+            // was no message" read the same, which is the conflation this whole node is about.
+            if (!message || typeof message !== 'object')
+                return;
+            const token = readStopReasonToken(message);
+            if (this.finishReasonObservations.length < FINISH_REASON_OBSERVATION_MAX) {
+                this.finishReasonObservations.push({ at: new Date().toISOString(), path, token });
+            }
+            debugLog(`EXT-159 finish_reason path=${path} token=${token ?? '<absent>'}`);
+        }
+        catch {
+            /* fail-soft: observing why a message stopped must never be what stops a run */
+        }
+    }
+    /**
+     * [[EXT-159]] — record why the turn ended, **first-write-wins**.
+     *
+     * The sites that classify are nested: the metadata reader and the cancellation paths sit inside
+     * the stream, which sits inside the runner's catches. Last-write-wins would let each outer layer
+     * overwrite the truer inner classification with its own coarser one — which is exactly the funnel
+     * this taxonomy replaces, rebuilt one level up. Fail-soft: classification never throws into a run.
+     */
+    noteTermination(reason) {
+        try {
+            if (this.terminationReason)
+                return;
+            this.terminationReason = reason;
+            // [[EXT-159]] — written where the reason is DECIDED, not where a surface later reads it. The
+            // terminating error reached only `transcript.json` and never the debug log, so the artifact a
+            // maintainer opens first could not say why a run ended; logging at the decision means the
+            // line exists even for a run whose surface never got to ask.
+            debugLog(terminationLogLine(reason));
+        }
+        catch {
+            /* fail-soft: recording why a run ended must never be what ends it */
+        }
+    }
+    /**
+     * [[EXT-159]] — run the metadata feeder over a finished message and record what it found.
+     *
+     * The metadata reader is the half of the taxonomy that only works here, at the layer where a
+     * message's `response_metadata` is visible. Returns whether anything was classified.
+     */
+    noteStopMetadata(site, message) {
+        const stop = detectStopMetadata(message);
+        if (!stop)
+            return false;
+        this.noteTermination(terminationReason(site, 'metadata', stop));
+        return true;
+    }
     /**
      * GS2-16 — best-effort count of messages already in the checkpointed thread state, used by
      * {@link invoke} as the baseline so it harvests only THIS turn's new messages rather than the
@@ -498,6 +612,15 @@ export class GthAbstractAgent {
                 // (if declined) response as "Failed to get answer". A fallback-model attempt would hang
                 // here (see the extension point in GthAgentRunner.processMessages), but no runtime
                 // fallback-model config exists today, so we surface terminally.
+                // [[EXT-159]] — the metadata feeder, at the one layer that can see `response_metadata`.
+                // Records why the turn ended (a refusal, or an answer cut off against the output cap)
+                // before the refusal branch below decides what to SAY about it; a truncation says nothing
+                // and is classification only.
+                // [[EXT-159]] — and record what the provider said about why the message stopped, or that it
+                // said nothing. Separate from the classification above: the metadata feeder speaks only for
+                // a refusal or a truncation, while this is the raw fact, kept for every ending.
+                this.noteFinishReason('invoke', finalMessage);
+                this.noteStopMetadata('agent.invoke-stop-metadata', finalMessage);
                 const refusal = detectRefusal(finalMessage);
                 if (refusal) {
                     return this.surfaceRefusal(refusal);
@@ -541,6 +664,13 @@ export class GthAbstractAgent {
             debugLogError('invoke outer', error);
             if (error instanceof Error) {
                 if (error?.name === 'ToolException') {
+                    // [[EXT-159]] — a tool failure that becomes the turn's ANSWER ends the turn as much as a
+                    // throw does, and it is the one ending whose diagnostic string is returned rather than
+                    // raised, so nothing further up ever sees an error to classify.
+                    this.noteTermination(terminationReason('agent.invoke-tool-exception', 'exception', {
+                        category: 'tool_error',
+                        detail: error.name,
+                    }));
                     this.statusUpdate(StatusLevel.ERROR, `Tool execution failed: ${error?.message}`);
                     return `Tool execution failed: ${error?.message}`;
                 }
@@ -590,6 +720,11 @@ export class GthAbstractAgent {
         // EXT-37: bound so the stream `start()` closure can surface a detected refusal (WARNING +
         // returns the message to enqueue) without a `this` reference.
         const surfaceRefusal = (info) => this.surfaceRefusal(info);
+        // [[EXT-159]] — bound for the same reason as the two above: the stream `start()` closure's
+        // `this` is the stream source, not the agent, and the sites that end this turn live in it.
+        const noteTermination = (reason) => this.noteTermination(reason);
+        const noteStopMetadata = (site, message) => this.noteStopMetadata(site, message);
+        const noteFinishReason = (path, message) => this.noteFinishReason(path, message);
         // TUI-C30 — compact per-tool-call indication for the plain surface (`name(args…)` + the
         // canonical 10-line greyed preview when each ToolMessage lands). Per-stream state; emits at
         // INFO level so the existing consoleLevel gate governs it like the historical tool notices.
@@ -725,14 +860,33 @@ export class GthAbstractAgent {
                     // (so the drained result is non-empty and bypasses the empty-response retry) and print it
                     // once at WARNING level (surfaceRefusal). Any partial content already streamed is kept;
                     // the refusal notice follows it, and its explanation carries any model-provided text.
+                    // [[EXT-159]] — the provider's own word on why this message stopped, recorded before
+                    // either branch decides what to make of it, so the raw fact is kept on the refusal path
+                    // as well as the ordinary one.
+                    noteFinishReason('stream', aggregatedChunk);
                     if (refusalInfo) {
+                        // [[EXT-159]] — classified through `classifyRefusal` rather than mapped here, so this
+                        // site and the metadata feeder cannot come to disagree about what a refusal is.
+                        noteTermination(terminationReason('agent.stream-stop-metadata', 'metadata', classifyRefusal(refusalInfo)));
                         controller.enqueue(surfaceRefusal(refusalInfo));
                     }
+                    else if (aggregatedChunk) {
+                        // No refusal: the same reader still has something to say about an answer that was cut
+                        // off against the output cap. Classification only — nothing is surfaced.
+                        noteStopMetadata('agent.stream-stop-metadata', aggregatedChunk);
+                    }
                     debugLog(`Stream completed. Total chunks: ${totalChunks}`);
                     controller.close();
                 }
                 catch (error) {
                     if (interruptState.escape || (error instanceof Error && error.name === 'AbortError')) {
+                        // [[EXT-159]] — Esc, or a caller's abort. This turn ends with no error reaching the
+                        // runner at all (the stream is CLOSED, not errored), so if this site does not classify
+                        // it nothing downstream can: it is indistinguishable from a turn that simply finished.
+                        noteTermination(terminationReason('agent.stream-cancelled', 'control', {
+                            category: 'cancelled',
+                            detail: interruptState.escape ? 'escape' : 'AbortError',
+                        }));
                         showInterruptMessage();
                         controller.close();
                     }
@@ -787,6 +941,11 @@ export class GthAbstractAgent {
             if (e instanceof GraphInterrupt ||
                 e.name === 'GraphInterrupt' ||
                 e.name === 'AbortError') {
+                // [[EXT-159]] — two different endings share this branch and must not share a reason. A
+                // suspend is not a failure at all (the run is parked on an `interrupt()` and continues on
+                // a resume); an abort is the user stopping it. Both return CLEANLY, so this is the last
+                // point at which either is knowable.
+                this.noteTermination(this.classifyEventStreamEnd('agent.events-ended', e));
                 debugLog('Graph suspended (GraphInterrupt) or aborted by caller');
                 return;
             }
@@ -827,12 +986,27 @@ export class GthAbstractAgent {
             if (e instanceof GraphInterrupt ||
                 e.name === 'GraphInterrupt' ||
                 e.name === 'AbortError') {
+                // [[EXT-159]] — the resume path's twin of the same two endings; see {@link streamWithEvents}.
+                this.noteTermination(this.classifyEventStreamEnd('agent.events-resume-ended', e));
                 debugLog('Graph suspended (GraphInterrupt) or aborted by caller');
                 return;
             }
             throw e;
         }
     }
+    /**
+     * [[EXT-159]] — which of the two clean endings a typed-event stream just took.
+     *
+     * Shared by {@link streamWithEvents} and {@link streamWithEventsResume} so the pair cannot drift:
+     * they catch the same union and owe the same distinction.
+     */
+    classifyEventStreamEnd(site, error) {
+        const suspended = error instanceof GraphInterrupt || error?.name === 'GraphInterrupt';
+        return terminationReason(site, suspended ? 'control' : 'exception', {
+            category: suspended ? 'suspended' : 'cancelled',
+            detail: suspended ? 'GraphInterrupt' : 'AbortError',
+        });
+    }
     /**
      * Inspect the checkpointed state for the thread and return the tool calls currently pending
      * human approval (empty array when the run finished normally). A LangGraph
@@ -930,6 +1104,23 @@ export class GthAbstractAgent {
         let aggregatedAIChunk = null;
         let reasoningOpen = false;
         const flushed = new Set();
+        /**
+         * [[TUI-C100]] — the calls THIS stream has announced (`tool_start` + `tool_args`) and whose
+         * own result it has not yet seen.
+         *
+         * Kept here rather than derived from {@link aggregatedAIChunk} because the aggregate is nulled
+         * after every round (see the reset below) while the calls it announced can still be waiting —
+         * at the approval gate, or simply behind a sibling in the same message. A set that died with
+         * the aggregate would lose exactly the calls this exists to track.
+         *
+         * **Scoped to one invocation, deliberately.** A call held at the approval gate is announced in
+         * the stream that suspends and resolved in the stream that resumes, so its result lands where
+         * this set is empty — and it therefore never receives a `tool_end` at all. That is the correct
+         * outcome, not a leak: a stream may only speak for what it announced. What closes a call that
+         * produces no result anywhere is the turn-level drain in `GthAgentRunner`'s
+         * `processMessagesWithEvents`, which spans both streams.
+         */
+        const pendingEnds = new Set();
         // EXT-41: a content-policy refusal on this typed-event path was de-scoped by EXT-37 (there is
         // no empty-response retry here, so no wrong-retry bug), but it still rendered as a SILENT empty
         // turn. Capture it (first per-chunk signal wins; aggregate fallback at stream end) and surface
@@ -978,6 +1169,18 @@ export class GthAbstractAgent {
                 }
             }
         }
+        /**
+         * Announce every call the assistant message carries, once its arguments are complete.
+         *
+         * [[TUI-C100]] — **announcing a call is not ending it.** This runs when the round's FIRST
+         * `ToolMessage` lands, because that is what makes the streamed aggregate complete, so it speaks
+         * for every call in the message at once: the one that just returned, the ones still queued, and
+         * the one suspended at the approval gate with a human being asked about it. `tool_start` and
+         * `tool_args` are true for all of them — the model has finished emitting the arguments — and
+         * that is what puts a call on screen, with the arguments the human is about to rule on.
+         * `tool_end` is not: it waits for the call's own result, and is emitted beside it when that
+         * result reaches THIS stream — which for a gated call it never does. See `pendingEnds` above.
+         */
         function* flushAggregated() {
             if (!aggregatedAIChunk)
                 return;
@@ -990,10 +1193,15 @@ export class GthAbstractAgent {
                 flushed.add(id);
                 yield { type: 'tool_start', id, name: tc.name };
                 yield { type: 'tool_args', id, delta: JSON.stringify(tc.args ?? {}) };
-                yield { type: 'tool_end', id };
+                pendingEnds.add(id);
             }
             // Surface invalid tool calls too so the client at least sees the raw args
             // string the model produced, instead of silently dropping them.
+            //
+            // These END INLINE, unlike the calls above, and the asymmetry is the point: an invalid call
+            // is never dispatched, so there is no result to wait for and nothing that could later change
+            // what it says. Deferring it would leave a row that cannot progress sitting at `running`
+            // until the turn ended, in exchange for nothing.
             for (const tc of invalidToolCalls) {
                 const id = tc.id;
                 if (!id || flushed.has(id))
@@ -1090,6 +1298,20 @@ export class GthAbstractAgent {
                 // `isError` still says the call did not run, which is what the model, `gth eval`'s
                 // tool-result assertions and the ACP bridge all read.
                 const toolCallId = chunk.tool_call_id;
+                // [[TUI-C100]] — the call's own result is here, so NOW it has ended.
+                //
+                // **The guard is the stream's own honesty, not a favour to a downstream reader.** This
+                // generator may only close a call it opened, and the id it is holding a result for is
+                // routinely one it never announced: a gated call is announced in the stream that suspends
+                // and returns in the stream that resumes, where this set is empty. So the common gated flow
+                // is `tool_start`, `tool_args`, then a `tool_result` in a later stream with **no `tool_end`
+                // between them, and none at all** — do not read the line below as a promise that an end
+                // always precedes a result. Every consumer treats `tool_result` as terminal on its own, and
+                // the AG-UI bridge additionally closes its own framing from what it actually emitted rather
+                // than trusting this event to arrive.
+                if (pendingEnds.delete(toolCallId)) {
+                    yield { type: 'tool_end', id: toolCallId };
+                }
                 yield {
                     type: 'tool_result',
                     id: toolCallId,
@@ -1106,7 +1328,19 @@ export class GthAbstractAgent {
         if (reasoningOpen) {
             yield { type: 'reasoning_end' };
         }
-        // Flush any tool calls not followed by a ToolMessage (e.g. terminal tool calls).
+        // Announce any tool calls not followed by a ToolMessage (e.g. terminal tool calls), so a call
+        // the model asked for is never silently absent from the stream.
+        //
+        // [[TUI-C100]] — and deliberately NO `tool_end` sweep of {@link pendingEnds} here, which is
+        // the tempting shape and the wrong one. **A stream that ends with calls outstanding is what
+        // suspending at the approval gate LOOKS like**: the graph interrupts, this generator returns,
+        // and `GthAgentRunner.processMessagesWithEvents` only then opens the prompt
+        // (`resolveToolInterruptsWithEvents`). Ending them here would put the tick and the word `done`
+        // back on the row a moment before the human is asked about it — the defect, moved rather than
+        // fixed. A call held at the gate and a genuinely terminal one are indistinguishable from
+        // inside the stream, and the turn's end is the first point at which the human has been asked
+        // and the answer acted on — so a call still without a result THERE is one that will never have
+        // one, and the runner closes it as exactly that.
         yield* flushAggregated();
         if (this.config?.writeBinaryOutputsToFile && binaryBlocks.length > 0) {
             const processedContent = materializeBinaryOutputs(binaryBlocks.map((block) => ({
@@ -1128,10 +1362,20 @@ export class GthAbstractAgent {
         if (!refusalInfo && aggregatedAIChunk) {
             refusalInfo = detectRefusal(aggregatedAIChunk);
         }
+        // [[EXT-159]] — the typed-event path's raw provider statement, on both branches. This is the
+        // surface most users watch, and it recorded no `finish_reason` anywhere at all.
+        this.noteFinishReason('events', aggregatedAIChunk);
         if (refusalInfo) {
+            // [[EXT-159]] — the typed-event path's metadata site; classified through the same
+            // `classifyRefusal` the other two use.
+            this.noteTermination(terminationReason('agent.events-stop-metadata', 'metadata', classifyRefusal(refusalInfo)));
             debugLog(`Content-policy refusal detected on typed-event path (provider=${refusalInfo.provider} reason=${refusalInfo.reason})`);
             yield { type: 'text', delta: buildRefusalMessage(refusalInfo) };
         }
+        else if (aggregatedAIChunk) {
+            // No refusal, but the same reader still sees an answer cut off against the output cap.
+            this.noteStopMetadata('agent.events-stop-metadata', aggregatedAIChunk);
+        }
     }
     async cleanup() {
         debugLog('Cleaning up agent...');