@gaunt-sloth/core 2.0.0-beta.1 → 2.0.0-beta.3

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/config/types.d.ts

@@ -662,6 +662,25 @@ export interface RatingConfig {
      * @default true
      */
     errorOnReviewFail?: boolean;
+    /**
+     * Wall-clock budget (ms) for the single rating model call.
+     *
+     * GS2-105 — rating is a SECOND model call fired from `afterAgent` once the review prose is
+     * already written, and it renders nothing while it runs. Without a bound, a model that fails to
+     * emit the rating tool call generates prose until its context window stops it: measured at 15,385
+     * tokens and 485 seconds on `gemma4:12b`, against a healthy rating call of ~50 seconds. The budget
+     * turns that silent hang into a bounded, legible failure, after which the existing
+     * missing-artifact path reports it and exits non-zero.
+     *
+     * It is a WALL-CLOCK budget for one call, not a per-token cap, because the per-token knob is not
+     * portable: `numPredict` is a constructor field on `ChatOllama` rather than a call option, and
+     * that provider declares `tool_choice?: never`, so neither of the obvious source-level remedies is
+     * available where this actually bites. `timeout` is a standard `RunnableConfig` field, so it works
+     * on every provider and genuinely aborts the request instead of merely abandoning it.
+     *
+     * @default 120000
+     */
+    timeoutMs?: number;
 }
 /**
  * Validation checks that can be skipped for custom command parameters.

package/dist/config/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/config/types.ts"],"names":[],"mappings":"AAmuBA,MAAM,CAAC,MAAM,uBAAuB,GAAG;IACrC,UAAU;IACV,WAAW;IACX,MAAM;IACN,UAAU;IACV,QAAQ;IACR,cAAc;IACd,KAAK;IACL,YAAY;IACZ,aAAa;IACb,QAAQ;CACA,CAAC"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/config/types.ts"],"names":[],"mappings":"AAsvBA,MAAM,CAAC,MAAM,uBAAuB,GAAG;IACrC,UAAU;IACV,WAAW;IACX,MAAM;IACN,UAAU;IACV,QAAQ;IACR,cAAc;IACd,KAAK;IACL,YAAY;IACZ,aAAa;IACb,QAAQ;CACA,CAAC"}

package/dist/constants.d.ts

@@ -42,6 +42,16 @@ export declare const CONFIG_SCHEMA_POINTER = "https://gauntsloth.app/schema/v2/g
  * Lives under `.gsloth/.gsloth-settings/` like other project settings.
  */
 export declare const SHELL_ALLOWLIST_FILE = "shell-allowlist.json";
+/**
+ * [[EXT-107]]: project-scoped persisted shell deny-list — the escalation menu's *always reject*
+ * choice. Its mirror on the refusal side, in the same directory and the same EXT-71 entry grammar,
+ * so the two files read identically to anyone who opens them.
+ *
+ * A separate file rather than a second array in {@link SHELL_ALLOWLIST_FILE}: the two lists have
+ * opposite failure modes, and a parse error that took the refusals down with the approvals would
+ * fail in the one direction this design never lets anything fail in.
+ */
+export declare const SHELL_DENYLIST_FILE = "shell-denylist.json";
 /**
  * The `additionalToolNamePrefix` handed to `MultiServerMCPClient` so every MCP tool name is
  * namespaced. Combined with `prefixToolNameWithServerName`, the adapter emits tool names shaped

package/dist/constants.js

@@ -42,6 +42,16 @@ export const CONFIG_SCHEMA_POINTER = 'https://gauntsloth.app/schema/v2/gsloth-co
  * Lives under `.gsloth/.gsloth-settings/` like other project settings.
  */
 export const SHELL_ALLOWLIST_FILE = 'shell-allowlist.json';
+/**
+ * [[EXT-107]]: project-scoped persisted shell deny-list — the escalation menu's *always reject*
+ * choice. Its mirror on the refusal side, in the same directory and the same EXT-71 entry grammar,
+ * so the two files read identically to anyone who opens them.
+ *
+ * A separate file rather than a second array in {@link SHELL_ALLOWLIST_FILE}: the two lists have
+ * opposite failure modes, and a parse error that took the refusals down with the approvals would
+ * fail in the one direction this design never lets anything fail in.
+ */
+export const SHELL_DENYLIST_FILE = 'shell-denylist.json';
 /**
  * The `additionalToolNamePrefix` handed to `MultiServerMCPClient` so every MCP tool name is
  * namespaced. Combined with `prefixToolNameWithServerName`, the adapter emits tool names shaped

package/dist/constants.js.map

@@ -1 +1 @@
-{"version":3,"file":"constants.js","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,UAAU,GAAG,SAAS,CAAC;AACpC,MAAM,CAAC,MAAM,mBAAmB,GAAG,kBAAkB,CAAC;AACtD,MAAM,CAAC,MAAM,WAAW,GAAG,cAAc,CAAC;AAC1C,MAAM,CAAC,MAAM,sBAAsB,GAAG,mBAAmB,CAAC;AAC1D,MAAM,CAAC,MAAM,wBAAwB,GAAG,qBAAqB,CAAC;AAC9D;;;;GAIG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,sBAAsB,CAAC;AAChE,MAAM,CAAC,MAAM,uBAAuB,GAAG,oBAAoB,CAAC;AAC5D,MAAM,CAAC,MAAM,sBAAsB,GAAG,mBAAmB,CAAC;AAC1D,MAAM,CAAC,MAAM,gBAAgB,GAAG,sBAAsB,CAAC;AACvD,MAAM,CAAC,MAAM,kBAAkB,GAAG,uBAAuB,CAAC;AAC1D,MAAM,CAAC,MAAM,2BAA2B,GAAG,mBAAmB,CAAC;AAC/D,MAAM,CAAC,MAAM,oBAAoB,GAAG,mBAAmB,CAAC;AACxD,MAAM,CAAC,MAAM,kBAAkB,GAAG,iBAAiB,CAAC;AACpD,MAAM,CAAC,MAAM,kBAAkB,GAAG,iBAAiB,CAAC;AACpD,MAAM,CAAC,MAAM,kBAAkB,GAAG,iBAAiB,CAAC;AACpD,MAAM,CAAC,MAAM,aAAa,GAAG,WAAW,CAAC;AACzC;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,4DAA4D,CAAC;AAClG;;;GAGG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,sBAAsB,CAAC;AAE3D;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,KAAK,CAAC;AAE1C;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,6BAA6B,GAAG,aAAa,CAAC;AAC3D,MAAM,CAAC,MAAM,8BAA8B,GAAG,qBAAqB,CAAC"}
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,UAAU,GAAG,SAAS,CAAC;AACpC,MAAM,CAAC,MAAM,mBAAmB,GAAG,kBAAkB,CAAC;AACtD,MAAM,CAAC,MAAM,WAAW,GAAG,cAAc,CAAC;AAC1C,MAAM,CAAC,MAAM,sBAAsB,GAAG,mBAAmB,CAAC;AAC1D,MAAM,CAAC,MAAM,wBAAwB,GAAG,qBAAqB,CAAC;AAC9D;;;;GAIG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,sBAAsB,CAAC;AAChE,MAAM,CAAC,MAAM,uBAAuB,GAAG,oBAAoB,CAAC;AAC5D,MAAM,CAAC,MAAM,sBAAsB,GAAG,mBAAmB,CAAC;AAC1D,MAAM,CAAC,MAAM,gBAAgB,GAAG,sBAAsB,CAAC;AACvD,MAAM,CAAC,MAAM,kBAAkB,GAAG,uBAAuB,CAAC;AAC1D,MAAM,CAAC,MAAM,2BAA2B,GAAG,mBAAmB,CAAC;AAC/D,MAAM,CAAC,MAAM,oBAAoB,GAAG,mBAAmB,CAAC;AACxD,MAAM,CAAC,MAAM,kBAAkB,GAAG,iBAAiB,CAAC;AACpD,MAAM,CAAC,MAAM,kBAAkB,GAAG,iBAAiB,CAAC;AACpD,MAAM,CAAC,MAAM,kBAAkB,GAAG,iBAAiB,CAAC;AACpD,MAAM,CAAC,MAAM,aAAa,GAAG,WAAW,CAAC;AACzC;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,4DAA4D,CAAC;AAClG;;;GAGG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,sBAAsB,CAAC;AAE3D;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,qBAAqB,CAAC;AAEzD;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,KAAK,CAAC;AAE1C;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,6BAA6B,GAAG,aAAa,CAAC;AAC3D,MAAM,CAAC,MAAM,8BAA8B,GAAG,qBAAqB,CAAC"}

package/dist/core/GthAbstractAgent.d.ts

@@ -132,7 +132,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
@@ -263,6 +263,37 @@ export declare abstract class GthAbstractAgent implements GthAgentInterface {
      * setup degrades to "no approval needed" instead of breaking the run.
      */
     getPendingToolInterrupts(runConfig: RunnableConfig): Promise<PendingToolInterrupt[]>;
+    /**
+     * [[TUI-C69]] §5.4 — remember that this call was bounced back to the agent as a negotiation
+     * round, so both display paths can tone its result row as a clarification request.
+     *
+     * A plain set rather than a queue: the ids are LangChain tool-call ids, unique per call, and the
+     * two display paths read the same one without either consuming it — a session drives one of them,
+     * never both. {@link clearRaterClarifications} empties it with the rest of the turn's state, so a
+     * long run cannot accumulate.
+     */
+    noteRaterClarification(toolCallId: string): void;
+    /**
+     * [[TUI-C69]] §5.4 — **forget the noted ids**, called at the top of every turn and on `/clear`.
+     *
+     * The set is keyed on tool-call ids, and an id is only meaningful while the result carrying it is
+     * being rendered. Holding them past that costs a string per rater rejection for the life of the
+     * process — small — and risks the thing that is not small: a LATER call that reuses a noted id
+     * renders as a clarification request whatever it actually was, so a successful command inherits
+     * the tone of an argument it had no part in.
+     *
+     * That reuse is not reachable with the providers installed today — `@langchain/ollama` mints
+     * `v4()` uuids, `@langchain/google` `lc-tool-call-${v4()}`, and OpenAI and Anthropic supply their
+     * own unique ids — but **the protection was the providers', not this code's**, which is a
+     * property no test here can hold and no bump has to preserve.
+     *
+     * On `/clear` it is the same argument `GthAgentRunner.resetThread` makes about the negotiation:
+     * state from before the user asked for the conversation to be forgotten must not decide how the
+     * conversation after it is drawn.
+     */
+    clearRaterClarifications(): void;
+    /** [[TUI-C69]] — the ids {@link noteRaterClarification} has been told about this turn. */
+    protected raterClarifications: Set<string>;
     protected processEventStream(stream: IterableReadableStream<[BaseMessage, Record<string, unknown>]>): AsyncGenerator<AgentStreamEvent>;
     cleanup(): Promise<void>;
     getEffectiveConfig(config: GthConfig, command: GthCommand | undefined): GthConfig;

package/dist/core/GthAbstractAgent.js

@@ -118,6 +118,84 @@ function pickReasoningDelta(kwargs) {
         return direct;
     return '';
 }
+/**
+ * [[TUI-C69]] §5.4 — **the tool-call ids a suspended graph's pending requests were built from.**
+ *
+ * LangChain's HITL middleware assembles its `actionRequests` from the last AI message's
+ * `tool_calls`, keeping `{ name, args, description }` and dropping the id — so a decision about a
+ * pending call has nothing to attribute it to on screen. The ids are still right there: the same
+ * `getState` snapshot that carries `tasks[].interrupts` carries `values.messages`, whose last
+ * `AIMessage` holds the very calls the middleware filtered. Measured against a real suspended
+ * graph rather than reasoned from the library's source, because a middleware hook that ran inside
+ * the model node instead of after it would leave this empty.
+ *
+ * Returns them in message order, for {@link claimToolCallId} to consume. Defensive throughout: an
+ * unexpected shape yields an empty list, and every id is then simply absent.
+ */
+function pendingToolCallIds(state) {
+    const messages = state?.values?.messages;
+    if (!Array.isArray(messages))
+        return [];
+    // The LAST message carrying tool calls is the one the interrupt suspended on. Earlier AI
+    // messages in the thread carry calls that already ran, and their ids must never be claimed.
+    for (let index = messages.length - 1; index >= 0; index--) {
+        const toolCalls = messages[index]?.tool_calls;
+        if (!Array.isArray(toolCalls) || toolCalls.length === 0)
+            continue;
+        const claimable = [];
+        for (const call of toolCalls) {
+            const name = call?.name;
+            const id = call?.id;
+            if (typeof name !== 'string' || typeof id !== 'string' || id.length === 0)
+                continue;
+            claimable.push({
+                name,
+                args: stableArgs(call?.args),
+                id,
+                claimed: false,
+            });
+        }
+        return claimable;
+    }
+    return [];
+}
+/**
+ * Match one pending action request back to its tool call and take that call's id.
+ *
+ * Name AND arguments, then FIRST unclaimed — which is exact rather than a correlation, because the
+ * request was built from that very object. The claim flag is what keeps two identical calls in one
+ * message (a model proposing the same command twice) from both taking the first id.
+ *
+ * **The arguments are half the match, and only one arrangement can show it.** Two calls of one name
+ * with the SAME arguments come back correctly under a name-only match too, because the claim flag
+ * alone puts them in order — so the case that discriminates is two calls of one name with DIFFERENT
+ * arguments whose requests arrive in the opposite order to the `tool_calls` they were built from.
+ * There, name-only gives every request an id and attaches each to the wrong command.
+ */
+function claimToolCallId(candidates, name, args) {
+    const wanted = stableArgs(args);
+    const match = candidates.find((c) => !c.claimed && c.name === name && c.args === wanted);
+    if (!match)
+        return undefined;
+    match.claimed = true;
+    return match.id;
+}
+/**
+ * A tool call's arguments as one comparable string, with the keys sorted so two objects that
+ * differ only in insertion order still match. Fail-soft: an unserialisable argument (a BigInt, a
+ * cycle) yields a token that matches nothing, so the id is simply not attributed.
+ */
+function stableArgs(args) {
+    if (!args || typeof args !== 'object')
+        return '{}';
+    try {
+        const entries = Object.entries(args).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0);
+        return JSON.stringify(entries);
+    }
+    catch {
+        return '<unserialisable>';
+    }
+}
 /**
  * Shared, graph-agnostic agent plumbing.
  *
@@ -262,7 +340,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
@@ -405,7 +483,7 @@ export class GthAbstractAgent {
                 // tool call gets its `✓ 📁 name(args…)` block here too. Only the plain surface reaches
                 // invoke (the TUI uses processMessagesWithEvents); observe() is fail-soft internally.
                 const allMessages = Array.isArray(response.messages) ? response.messages : [];
-                const toolIndication = createPlainToolIndication();
+                const toolIndication = createPlainToolIndication(undefined, (id) => this.raterClarifications.has(id));
                 for (const m of allMessages.slice(priorMessageCount)) {
                     this.recordRunStats(m);
                     toolIndication.observe(m);
@@ -516,7 +594,13 @@ export class GthAbstractAgent {
         // 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.
         // The TUI never runs this string path (it renders the typed event stream itself).
-        const toolIndication = createPlainToolIndication();
+        //
+        // [[TUI-C69]] §5.4 — the plain surface's twin of the typed event's `raterClarification`, read
+        // through a closure rather than handed a snapshot: the set is filled WHILE this stream is
+        // drained, because the runner notes the id at the moment it refuses the call, which is after
+        // this observer was built and before the refusal's own result arrives.
+        const raterClarifications = this.raterClarifications;
+        const toolIndication = createPlainToolIndication(undefined, (id) => raterClarifications.has(id));
         const interruptState = { escape: false, messageShown: false };
         const abortController = new AbortController();
         const showInterruptMessage = () => {
@@ -774,6 +858,8 @@ export class GthAbstractAgent {
         if (!Array.isArray(tasks)) {
             return [];
         }
+        // [[TUI-C69]] — the ids the action requests were built from, ready to be claimed in order.
+        const unclaimedIds = pendingToolCallIds(state);
         const pending = [];
         for (const task of tasks) {
             const interrupts = task?.interrupts;
@@ -789,15 +875,54 @@ export class GthAbstractAgent {
                     if (typeof name !== 'string')
                         continue;
                     const args = action?.args;
+                    const resolvedArgs = args && typeof args === 'object' ? args : {};
+                    const id = claimToolCallId(unclaimedIds, name, resolvedArgs);
                     pending.push({
                         name,
-                        args: args && typeof args === 'object' ? args : {},
+                        args: resolvedArgs,
+                        ...(id === undefined ? {} : { id }),
                     });
                 }
             }
         }
         return pending;
     }
+    /**
+     * [[TUI-C69]] §5.4 — remember that this call was bounced back to the agent as a negotiation
+     * round, so both display paths can tone its result row as a clarification request.
+     *
+     * A plain set rather than a queue: the ids are LangChain tool-call ids, unique per call, and the
+     * two display paths read the same one without either consuming it — a session drives one of them,
+     * never both. {@link clearRaterClarifications} empties it with the rest of the turn's state, so a
+     * long run cannot accumulate.
+     */
+    noteRaterClarification(toolCallId) {
+        if (toolCallId)
+            this.raterClarifications.add(toolCallId);
+    }
+    /**
+     * [[TUI-C69]] §5.4 — **forget the noted ids**, called at the top of every turn and on `/clear`.
+     *
+     * The set is keyed on tool-call ids, and an id is only meaningful while the result carrying it is
+     * being rendered. Holding them past that costs a string per rater rejection for the life of the
+     * process — small — and risks the thing that is not small: a LATER call that reuses a noted id
+     * renders as a clarification request whatever it actually was, so a successful command inherits
+     * the tone of an argument it had no part in.
+     *
+     * That reuse is not reachable with the providers installed today — `@langchain/ollama` mints
+     * `v4()` uuids, `@langchain/google` `lc-tool-call-${v4()}`, and OpenAI and Anthropic supply their
+     * own unique ids — but **the protection was the providers', not this code's**, which is a
+     * property no test here can hold and no bump has to preserve.
+     *
+     * On `/clear` it is the same argument `GthAgentRunner.resetThread` makes about the negotiation:
+     * state from before the user asked for the conversation to be forgotten must not decide how the
+     * conversation after it is drawn.
+     */
+    clearRaterClarifications() {
+        this.raterClarifications.clear();
+    }
+    /** [[TUI-C69]] — the ids {@link noteRaterClarification} has been told about this turn. */
+    raterClarifications = new Set();
     async *processEventStream(stream) {
         // Aggregate AIMessageChunks via concat so tool_call_chunks collapse into
         // tool_calls with complete args (per-chunk tool_calls only ever sees that
@@ -805,11 +930,30 @@ 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
         // it as a `text` event so every consumer (Ink TUI viewModel, AG-UI SSE) shows a clear notice.
         let refusalInfo = null;
+        const seenBinaryKeys = new Set();
+        const binaryBlocks = [];
         // TUI-C22 — one splitter for the whole stream so a <think> opened in one chunk and closed
         // several chunks later is tracked across the boundary. Reset at message boundaries via flush().
         const thinkSplitter = createThinkTagSplitter();
@@ -851,6 +995,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;
@@ -863,10 +1019,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))
@@ -887,6 +1048,16 @@ export class GthAbstractAgent {
             if (!refusalInfo) {
                 refusalInfo = detectRefusal(chunk);
             }
+            if (this.config?.writeBinaryOutputsToFile &&
+                (AIMessageChunk.isInstance(chunk) || AIMessage.isInstance(chunk))) {
+                for (const block of extractInlineBinaryBlocks(chunk.content)) {
+                    const binaryKey = `${block.mimeType}:${block.data.length}:${block.data}`;
+                    if (!seenBinaryKeys.has(binaryKey)) {
+                        seenBinaryKeys.add(binaryKey);
+                        binaryBlocks.push({ mimeType: block.mimeType, data: block.data });
+                    }
+                }
+            }
             if (AIMessageChunk.isInstance(chunk)) {
                 aggregatedAIChunk = aggregatedAIChunk ? aggregatedAIChunk.concat(chunk) : chunk;
                 // Reasoning deltas — Ollama (Qwen3, deepseek-r1), Anthropic, and OpenRouter surface
@@ -948,11 +1119,31 @@ export class GthAbstractAgent {
                 // Surface the real tool-result error signal (LangChain `ToolMessage.status`) so
                 // consumers render the ✗/error affordance from fact, not from sniffing the result
                 // text. Only attach the flag on error to keep the success event shape unchanged.
+                // [[TUI-C69]] §5.4 — the gate's own account of WHY this result is an error, when it was
+                // the auto-rater asking for a clarification rather than a tool that failed. Additive:
+                // `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: chunk.tool_call_id,
+                    id: toolCallId,
                     content,
                     ...(chunk.status === 'error' ? { isError: true } : {}),
+                    ...(this.raterClarifications.has(toolCallId) ? { raterClarification: true } : {}),
                 };
             }
         }
@@ -963,8 +1154,32 @@ 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) => ({
+                type: 'inlineData',
+                inlineData: block,
+            })), this.command);
+            for (const successMessage of processedContent.successMessages) {
+                this.statusUpdate(StatusLevel.SUCCESS, successMessage);
+            }
+            if (processedContent.renderedContent.trim().length > 0) {
+                yield { type: 'text', delta: '\n' + processedContent.renderedContent + '\n' };
+            }
+        }
         // EXT-41: aggregate-level fallback (I-1's robustness on this path too) — if no per-chunk
         // metadata flagged a refusal, inspect the final aggregated message's stop/finish reason. Then
         // surface any refusal as a `text` event so the user sees a clear notice instead of a silent