@gaunt-sloth/core 2.0.0-alpha.9 → 2.0.0-beta.0

package/dist/core/GthAbstractAgent.js

@@ -1,5 +1,10 @@
+import { applyRungAwareToolDescriptions, } from '#src/config.js';
 import { StatusLevel, } from '#src/core/types.js';
 import { accumulateMessage, createRunStatsAccumulator, finalizeRunStats, } from '#src/core/runStats.js';
+import { collectDeclaredMcpToolAnnotations } from '#src/core/approvals/toolAnnotationSources.js';
+import { modelProviderLabel } from '#src/core/modelLabel.js';
+import { createPlainToolIndication } from '#src/core/plainToolIndication.js';
+import { runHeaderLine } from '#src/core/runHeader.js';
 import { debugLog, debugLogError, debugLogObject } from '#src/utils/debugUtils.js';
 import { ProgressIndicator } from '#src/utils/ProgressIndicator.js';
 import { stopWaitingForEscape, waitForEscape } from '#src/utils/systemUtils.js';
@@ -7,18 +12,123 @@ 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 { answerTextOf, segmentAssistantContent, stripReasoningBlocks, } from '#src/core/reasoningBlocks.js';
+const THINK_OPEN = '<think>';
+const THINK_CLOSE = '</think>';
+/**
+ * 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
+ * into `tag` on the next chunk (e.g. a chunk ending in `<thi` when the tag is `<think>`).
+ */
+function trailingPartialLen(s, tag) {
+    const max = Math.min(s.length, tag.length - 1);
+    for (let k = max; k > 0; k--) {
+        if (s.slice(s.length - k) === tag.slice(0, k))
+            return k;
+    }
+    return 0;
+}
+/**
+ * TUI-C22 — stateful separator of inline `<think>...</think>` thinking from answer text, robust to
+ * tags split across streamed chunks. Many thinking models served over an OpenAI-compatible `/v1`
+ * shim (qwen3 / deepseek-r1 over Ollama) inline their reasoning as `<think>…</think>` in the
+ * message `content` rather than in `additional_kwargs.reasoning_content`; without this it would
+ * render as answer text and the `/reasoning` panel would stay empty.
+ *
+ * `push(text)` returns the segments it can classify unambiguously *now*, buffering any trailing
+ * partial tag (so a `<think>` arriving as `<thi` + `nk>` across two chunks is still detected) and
+ * the run of thinking between an open and a not-yet-seen close tag. `flush()` drains the buffer at
+ * a message/stream boundary: an unterminated `<think>` at EOF yields its remainder as reasoning; a
+ * dangling non-tag partial (e.g. a lone `<` or `<thi` that never completed) yields as answer, so no
+ * text is ever dropped. Purely additive — text with no `<think>` passes straight through as answer.
+ */
+function createThinkTagSplitter() {
+    let buffer = '';
+    let inThink = false;
+    function push(text) {
+        const segments = [];
+        if (text.length === 0 && buffer.length === 0)
+            return segments;
+        buffer += text;
+        for (;;) {
+            if (inThink) {
+                const idx = buffer.indexOf(THINK_CLOSE);
+                if (idx >= 0) {
+                    if (idx > 0)
+                        segments.push({ kind: 'reasoning', text: buffer.slice(0, idx) });
+                    buffer = buffer.slice(idx + THINK_CLOSE.length);
+                    inThink = false;
+                    continue;
+                }
+                // No full close tag yet — emit reasoning except a trailing partial of `</think>`.
+                const hold = trailingPartialLen(buffer, THINK_CLOSE);
+                const emit = buffer.slice(0, buffer.length - hold);
+                if (emit.length > 0)
+                    segments.push({ kind: 'reasoning', text: emit });
+                buffer = hold > 0 ? buffer.slice(buffer.length - hold) : '';
+                break;
+            }
+            else {
+                const idx = buffer.indexOf(THINK_OPEN);
+                if (idx >= 0) {
+                    if (idx > 0)
+                        segments.push({ kind: 'answer', text: buffer.slice(0, idx) });
+                    buffer = buffer.slice(idx + THINK_OPEN.length);
+                    inThink = true;
+                    continue;
+                }
+                // No full open tag yet — emit answer except a trailing partial of `<think>`.
+                const hold = trailingPartialLen(buffer, THINK_OPEN);
+                const emit = buffer.slice(0, buffer.length - hold);
+                if (emit.length > 0)
+                    segments.push({ kind: 'answer', text: emit });
+                buffer = hold > 0 ? buffer.slice(buffer.length - hold) : '';
+                break;
+            }
+        }
+        return segments;
+    }
+    function flush() {
+        const segments = [];
+        if (buffer.length > 0) {
+            segments.push({ kind: inThink ? 'reasoning' : 'answer', text: buffer });
+        }
+        buffer = '';
+        inThink = false;
+        return segments;
+    }
+    return { push, flush };
+}
+/**
+ * Pick this chunk's or message's reasoning delta/content.
+ * Precedence:
+ *  1. `additional_kwargs.reasoning_content` — standard DeepSeek/Anthropic/OpenRouter convention.
+ *  2. `additional_kwargs.reasoning` — direct reasoning fallback if present.
+ */
+function pickReasoningDelta(kwargs) {
+    if (!kwargs)
+        return '';
+    const reasoningContent = kwargs.reasoning_content;
+    if (typeof reasoningContent === 'string' && reasoningContent.length > 0) {
+        return reasoningContent;
+    }
+    const direct = kwargs.reasoning;
+    if (typeof direct === 'string' && direct.length > 0)
+        return direct;
+    return '';
+}
 /**
  * Shared, graph-agnostic agent plumbing.
  *
- * Both the lean {@link GthLangChainAgent} (`createAgent`, in core) and the deep
- * `GthDeepAgent` (`createDeepAgent`, in `@gaunt-sloth/agent`) differ only in how they
- * build the compiled LangGraph in {@link init}; everything downstream — invoking,
+ * A backend differs from another only in how it builds the compiled LangGraph in {@link init} —
+ * today that is the lean {@link GthLangChainAgent} (`createAgent`, in core); everything downstream — invoking,
  * streaming to the console, emitting typed {@link AgentStreamEvent}s, client-tool
  * `interrupt()` stubbing, suspend/resume, and cleanup — is identical and lives here.
  *
- * The base operates solely on the structural {@link GthCompiledGraph} surface, so it
- * does NOT import `langchain`/`deepagents` graph builders. Subclasses construct the
- * graph and assign it to {@link agent} in their `init()`.
+ * The base operates solely on the structural {@link GthCompiledGraph} surface, so it does NOT
+ * import a graph builder. Subclasses construct the graph and assign it to {@link agent} in their
+ * `init()`.
  */
 export class GthAbstractAgent {
     statusUpdate;
@@ -26,6 +136,44 @@ export class GthAbstractAgent {
     agent = null;
     config = null;
     command = undefined;
+    /**
+     * GS2-95 — the name of the command the USER typed, as the run header should say it. Set from
+     * {@link GthAgentInitOptions#displayCommand} by the backend's `init`, and read by exactly one
+     * thing: {@link compactHeaderStatus}.
+     *
+     * Separate from {@link command} because that field is not a label — it selects the mode prompt,
+     * the approvals posture and the command-specific filesystem config. Naming the header off it is
+     * why `gth eval` used to open with `ask`, and moving it to fix the header would silently change
+     * which system prompt those runs execute under. Left `undefined` by every command whose init verb
+     * IS its name, which is most of them.
+     */
+    displayCommand = undefined;
+    /**
+     * Opt-in debug sink for the TUI `/debug` panel. Set AFTER {@link init} via
+     * `runner.getAgent()`; read lazily inside each backend's `wrapModelCall` capture middleware
+     * so that when it is `undefined` (the normal path) the middleware is a transparent
+     * pass-through. Lives on the base so every backend supports it; the AG-UI server / non-TUI
+     * callers simply never set it, so those contracts are unchanged.
+     */
+    debugCapture;
+    /**
+     * GS2-56 — the ALWAYS-ON snapshot of the most recent model request (extras + the as-sent,
+     * post-summarization messages), populated UNCONDITIONALLY at each backend's `wrapModelCall` feed
+     * site — NOT gated on {@link debugCapture} being attached. This is what lets `/debug-dump` render
+     * the full model input even when the TUI `/debug` panel was never opened and on non-TUI surfaces
+     * (the sink only ever fed the live `/debug` panel). O(1): a single overwritten reference retaining
+     * only the LAST call — no accumulation, so the "pay nothing until you need it" intent is kept.
+     */
+    lastModelRequest;
+    /**
+     * GS2-56 — stash the last model request (the as-sent messages + {@link DebugRequestExtras}).
+     * Called unconditionally from each backend's capture middleware, independent of the debug sink,
+     * so the snapshot is available to `/debug-dump` on every surface. Overwrites (retains only the
+     * most recent call). Callers already guard the invocation; kept trivial so it can never throw.
+     */
+    setLastModelRequest(messages, extras) {
+        this.lastModelRequest = { messages, extras };
+    }
     /**
      * GS2-16 — per-run analytics tally (token usage + invoked tool names) folded from the messages
      * flowing through {@link invoke} / the streaming paths. Reset at each turn boundary via
@@ -33,12 +181,147 @@ export class GthAbstractAgent {
      * fully fail-soft (accumulation is guarded and never throws into a run).
      */
     runStatsAcc = createRunStatsAccumulator();
+    /**
+     * 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
+     * granted-built-in list (§4.4), so a suggestion can only ever name a tool the model actually has.
+     */
+    registeredToolNames = [];
+    /**
+     * EXT-70 §4.7.1 — what the connected MCP servers DECLARED about their own tools, captured from
+     * the same registration hook as {@link registeredToolNames} and keyed by the registered tool
+     * name. Read by `GthAgentRunner` as the `mcp` half of a `DeclaredToolAnnotationLookup`.
+     *
+     * It is a record of claims, never of decisions: no trust is applied here (that is
+     * `createEffectiveToolAnnotationSource`'s only job), and an absent tool yields the fail-closed
+     * defaults rather than "declared nothing".
+     */
+    declaredMcpToolAnnotations = new Map();
     constructor(statusUpdate, resolvers) {
         this.statusUpdate = (level, message) => {
             statusUpdate(level, message);
         };
         this.resolvers = resolvers;
     }
+    /**
+     * GS2-101 — the run-header rung in force. An unset `output.header` resolves to `compact`: a run
+     * that was never configured opens with one attribution line and nothing else, and the technical
+     * preamble is opt-in via `output.header: 'debug'`.
+     *
+     * Defaulted HERE rather than in `DEFAULT_CONFIG` (the convention `injectModelContext` and
+     * `debugDump.redact` also follow) so the effective-config snapshot `gth config` prints does not
+     * grow a key nobody set.
+     */
+    get headerRung() {
+        return this.config?.output?.header ?? 'compact';
+    }
+    /**
+     * GS2-93 — emit one line of the technical run-header preamble (the Workdir/Model/Tools/Middleware
+     * block). Only the `debug` rung shows it; `compact` replaces the whole block with
+     * {@link compactHeaderStatus}'s single line and `none` shows nothing. A non-`debug` rung only ever
+     * reaches here in non-TUI text modes: the interactive TUI forces `debug` before init (see
+     * `createTuiSession`), and the TUI event path never goes through the interrupt-hint site, so the
+     * whole preamble stays visible there. Only INFO header lines route through this — real model/tool
+     * output, warnings and errors keep using {@link statusUpdate} directly.
+     */
+    headerStatus(message) {
+        if (this.headerRung !== 'debug')
+            return;
+        this.statusUpdate(StatusLevel.INFO, message);
+    }
+    /**
+     * GS2-93 — the `compact` rung's whole output: one line naming the command and the model that
+     * served it, in place of the preamble. Called once from the backend's `init`, after the command
+     * and effective config are in place. The string is {@link runHeaderLine}'s, shared with the review
+     * document's opening line so the two writers cannot drift.
+     *
+     * **This renders; it does not decide.** The word after the product name is
+     * {@link displayCommand} when the command supplied one and the init verb otherwise — GS2-93
+     * forbids a label table inside the agent, because naming a user-facing line is the command's call,
+     * not the runtime's.
+     *
+     * Two runs deliberately emit nothing here:
+     *
+     * - **`review` and `pr`** already open with `reviewHeadingBlock`, which renders this same line.
+     *   Emitting here as well would print the header twice on one screen.
+     * - **A run with no name at all** — the `pr` command's discovery sub-agent is the one such
+     *   caller, and it runs inside a `pr` whose header is already on screen. The name is what this
+     *   line is for, so with none there is nothing to say; inventing a word for it would be naming a
+     *   user-facing surface from inside the agent.
+     *
+     * The model half is the shared {@link modelProviderLabel} spelling (DL-6), and it is dropped
+     * rather than faked when nothing resolves (DL-7), leaving the command on its own.
+     */
+    compactHeaderStatus() {
+        if (this.headerRung !== 'compact')
+            return;
+        const command = this.displayCommand ?? this.command;
+        if (!command || command === 'review' || command === 'pr')
+            return;
+        const label = modelProviderLabel(this.config?.modelDisplayName, this.config?.modelProviderType);
+        this.statusUpdate(StatusLevel.INFO, runHeaderLine(command, label));
+    }
+    /**
+     * EXT-58 (spec §4.5) — the ONE tool-registration hook both backends call with their 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
+     *    rung, and leaves every granted tool's description untouched (the absence of the sentence is
+     *    what marks a tool free). See {@link applyRungAwareToolDescriptions}.
+     * 2. Records the registered tool names for {@link getRegisteredToolNames}, which feeds the
+     *    rater's granted-alternative list (§4.4).
+     * 3. EXT-70 §4.7.1 — records what the MCP servers declared about their own tools, for
+     *    {@link getDeclaredMcpToolAnnotations}. This is the ONE place a `tools/list` annotation
+     *    enters the approvals stack, and it enters as a claim: nothing here decides whether it is
+     *    believed.
+     *
+     * `gatedTools` MUST be the **LIVE gated set for the rung in force** — `resolveGatedToolNames` for
+     * that rung — and NOT the set the caller wires into the approval interrupt. The two are different
+     * on purpose: the interrupt is installed once, at agent init, and is deliberately
+     * rung-independent (`resolveInterruptToolNames`, the union over every rung) so that
+     * `/approvals <mode>` can move the mode underneath it for the rest of the session. Passing that
+     * wider set here would describe tools as needing approval that the live mode does not gate — and
+     * a call the live mode does not gate is auto-approved the moment it reaches the runner, so the
+     * sentence would be a promise nothing keeps.
+     *
+     * What keeps a description from promising an approval the gate will not ask for is therefore that
+     * both this and `GthAgentRunner`'s own check are projections of the SAME rule,
+     * `isToolGatedAtRung`, evaluated against the SAME live mode — §4.5's "a description that disagrees
+     * with what the gate will actually do is worse than no description at all".
+     *
+     * `additionalToolNames` covers tools the graph builder registers itself and that therefore never
+     * appear in `tools`. Their descriptions are not ours to write, so they cannot be suffixed here;
+     * they are recorded only so the rater's suggestion list reflects what the model actually has.
+     */
+    registerApprovalsAwareTools(tools, options) {
+        applyRungAwareToolDescriptions(tools, {
+            rung: options.rung,
+            gatedTools: options.gatedTools,
+        });
+        const names = tools
+            .map((tool) => tool?.name)
+            .filter((name) => typeof name === 'string' && name.length > 0);
+        this.registeredToolNames = [...names, ...(options.additionalToolNames ?? [])];
+        // `additionalToolNames` are deliberately NOT consulted: they are names the graph builder
+        // registers itself, with no tool object and therefore no declaration to read.
+        this.declaredMcpToolAnnotations = collectDeclaredMcpToolAnnotations(tools);
+        return tools;
+    }
+    /**
+     * EXT-58 — the tool names registered with the graph at the last {@link init} (empty before it).
+     * The runner intersects these with the built-in summaries table to build the rater's
+     * granted-alternative list, so the rater can never name a tool this session does not have.
+     */
+    getRegisteredToolNames() {
+        return [...this.registeredToolNames];
+    }
+    /**
+     * EXT-70 §4.7.1 — what the MCP servers declared for their tools at the last {@link init}, keyed
+     * by registered tool name (empty before it, and on a session with no MCP servers).
+     */
+    getDeclaredMcpToolAnnotations() {
+        return this.declaredMcpToolAnnotations;
+    }
     /**
      * GS2-16 — clear the per-run analytics tally so the next turn starts from zero. The runner
      * calls this at each turn boundary because it (and this agent) are reused across turns in an
@@ -73,6 +356,19 @@ export class GthAbstractAgent {
             return 0;
         }
     }
+    /**
+     * EXT-37 — surface a detected content-policy refusal: emit the clear, user-facing explanation at
+     * WARNING level (an empty-content refusal streams nothing, so without this the console shows
+     * nothing) and return the same message so it becomes the turn's terminal answer. Shared by the
+     * non-streaming {@link invoke} and streaming {@link streamFromInput} paths so both render a
+     * refusal identically. A refusal is a *successful* (if declined) response — never a retry.
+     */
+    surfaceRefusal(info) {
+        const message = buildRefusalMessage(info);
+        debugLog(`Content-policy refusal detected (provider=${info.provider} reason=${info.reason})`);
+        this.statusUpdate(StatusLevel.WARNING, message);
+        return message;
+    }
     /**
      * Invoke LLM with a message and runnable config.
      * For streaming use {@link #stream} method, streaming is preferred if model API supports it.
@@ -102,11 +398,38 @@ export class GthAbstractAgent {
                 const response = await this.agent.invoke({ messages }, runConfig);
                 // Harvest token usage + invoked tool names from THIS turn's new messages only (fail-soft)
                 // so the opt-in history recorder can populate `gth insights`.
+                // TUI-C32 residual f — the streaming path renders the compact per-tool indication via
+                // streamFromInput's observer; the non-streaming invoke path (`streamOutput: false`) had
+                // none, so a plain-surface tool call surfaced nothing after the legacy fs notices were
+                // dropped (residual b). Feed THIS turn's new messages through the SAME observer so each
+                // 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 : [];
-                for (const m of allMessages.slice(priorMessageCount))
+                const toolIndication = createPlainToolIndication();
+                for (const m of allMessages.slice(priorMessageCount)) {
                     this.recordRunStats(m);
+                    toolIndication.observe(m);
+                }
                 const finalMessage = response.messages[response.messages.length - 1];
-                const finalContent = finalMessage?.content;
+                // EXT-37: content-policy refusal. A successful response whose stop/finish reason is a
+                // refusal (OpenAI content_filter / Anthropic stop_reason=refusal / Bedrock
+                // guardrail_intervened) is terminal-but-clear: surface the model's explanation and RETURN
+                // it as the answer. It must NOT flow into the empty-response retry (a refusal is
+                // deterministic — retrying just burns a paid call). Returning a non-empty message means the
+                // caller writes it to the output file and exits ok, rather than re-wrapping a *successful*
+                // (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.
+                const refusal = detectRefusal(finalMessage);
+                if (refusal) {
+                    return this.surfaceRefusal(refusal);
+                }
+                // CFG-33: Gemini's thought summaries ride inside `content` as `thought: true` text blocks,
+                // which renderAssistantContent would print as part of the answer (and write to the output
+                // file). The plain surface has never shown reasoning — every other provider's arrives
+                // out-of-band in additional_kwargs — so drop them for rendering only; graph state keeps the
+                // message whole so the thought parts still replay as history.
+                const finalContent = stripReasoningBlocks(finalMessage?.content);
                 const processedContent = !this.config.writeBinaryOutputsToFile
                     ? {
                         renderedContent: renderAssistantContent(finalContent),
@@ -186,6 +509,14 @@ export class GthAbstractAgent {
         // GS2-16: bound so the stream `start()` closure (whose `this` is the stream source, not the
         // agent) can fold each chunk into the run tally. Fail-soft inside recordRunStats.
         const recordRunStats = (m) => this.recordRunStats(m);
+        // 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);
+        // 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.
+        // The TUI never runs this string path (it renders the typed event stream itself).
+        const toolIndication = createPlainToolIndication();
         const interruptState = { escape: false, messageShown: false };
         const abortController = new AbortController();
         const showInterruptMessage = () => {
@@ -200,7 +531,12 @@ export class GthAbstractAgent {
             if (!abortController.signal.aborted) {
                 abortController.abort();
             }
-        }, this.config.canInterruptInferenceWithEsc);
+        }, this.config.canInterruptInferenceWithEsc, 
+        // GS2-93: the interrupt hint is part of the run-header preamble, so only the `debug` rung
+        // prints it. The Esc/Q handler stays armed at every rung — the hint box is what goes, not the
+        // interrupt. This site only runs in the non-TUI text path (`streamFromInput`); the TUI event
+        // path never reaches it.
+        this.headerRung === 'debug');
         let stream;
         try {
             stream = await this.agent.stream(input, {
@@ -225,13 +561,44 @@ export class GthAbstractAgent {
                     let totalChunks = 0;
                     const seenBinaryBlocks = new Set();
                     const binaryBlocks = [];
+                    // EXT-37: a content-policy refusal's stop/finish reason rides on a chunk's
+                    // response_metadata (usually with empty content). Capture it here and surface it AFTER
+                    // the stream drains, so the returned text is non-empty and the run loop treats it as
+                    // terminal-but-clear instead of routing an empty streamed turn into the retry.
+                    let refusalInfo = null;
+                    // EXT-41: belt-and-suspenders — also concat the AI chunks so a refusal can be read off
+                    // the FINAL aggregated message's stop/finish reason, not only a per-chunk one. Some
+                    // providers surface the reason only on the assembled message (or split it across chunks
+                    // that concat into it); without this fallback such a refusal would be swallowed by the
+                    // empty-response retry, making the EXT-37 surfacing cosmetic on the DEFAULT streaming
+                    // surface. Reset at each tool round (below) so a prior round's reason can't concatenate
+                    // with the final turn's (mirrors processEventStream's per-round reset).
+                    let aggregatedChunk = null;
                     for await (const [chunk, _metadata] of stream) {
                         debugLogObject('Stream chunk', { chunk, _metadata });
                         // GS2-16: fold every chunk (AIMessageChunk usage/tool_calls, ToolMessage name) into
                         // the run tally before the text-only handling below.
                         recordRunStats(chunk);
+                        // EXT-37: first refusal signal wins; keep scanning chunks for text/binary as normal.
+                        if (!refusalInfo) {
+                            refusalInfo = detectRefusal(chunk);
+                        }
+                        // EXT-41: fold AI chunks into an aggregate for the aggregate-level refusal fallback,
+                        // resetting at tool-round boundaries so a prior round's stop/finish reason can't bleed
+                        // into the final turn's aggregate.
+                        if (AIMessageChunk.isInstance(chunk)) {
+                            aggregatedChunk = aggregatedChunk ? aggregatedChunk.concat(chunk) : chunk;
+                        }
+                        else if (chunk instanceof ToolMessage) {
+                            aggregatedChunk = null;
+                        }
+                        // TUI-C30: fold the chunk into the plain-surface tool indication (renders each
+                        // completed call when its ToolMessage arrives; a no-op for plain text chunks).
+                        toolIndication.observe(chunk);
                         if (AIMessage.isInstance(chunk)) {
-                            const text = chunk.text ?? '';
+                            // CFG-33: the ANSWER text only. `.text` folds Gemini's `thought: true` blocks into the
+                            // answer, which would print the model's thinking inline here and in the output file.
+                            const text = answerTextOf(chunk.content);
                             totalChunks++;
                             if (text.length > 0) {
                                 statusUpdate(StatusLevel.STREAM, text);
@@ -264,6 +631,19 @@ export class GthAbstractAgent {
                             statusUpdate(StatusLevel.SUCCESS, successMessage);
                         }
                     }
+                    // EXT-41: aggregate-level fallback — if no per-chunk metadata flagged a refusal, inspect
+                    // the FINAL aggregated message's stop/finish reason. Catches providers that expose the
+                    // reason only on the assembled message (or split across chunks that concat into it).
+                    if (!refusalInfo && aggregatedChunk) {
+                        refusalInfo = detectRefusal(aggregatedChunk);
+                    }
+                    // EXT-37: surface a captured refusal as the terminal answer. Enqueue the clear message
+                    // (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.
+                    if (refusalInfo) {
+                        controller.enqueue(surfaceRefusal(refusalInfo));
+                    }
                     debugLog(`Stream completed. Total chunks: ${totalChunks}`);
                     controller.close();
                 }
@@ -425,6 +805,52 @@ export class GthAbstractAgent {
         let aggregatedAIChunk = null;
         let reasoningOpen = false;
         const flushed = 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;
+        // 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();
+        // TUI-C22 — emit ordered answer/reasoning segments, opening/closing the reasoning block as the
+        // kind switches. Shares `reasoningOpen` with the reasoning_content path so the two compose
+        // (a reasoning_content delta then think-derived reasoning stays one open block; answer text
+        // closes it), preserving the exact existing event sequence when no <think> tags are present.
+        function* emitSegments(segments) {
+            for (const seg of segments) {
+                if (seg.text.length === 0)
+                    continue;
+                if (seg.kind === 'reasoning') {
+                    if (!reasoningOpen) {
+                        reasoningOpen = true;
+                        yield { type: 'reasoning_start' };
+                    }
+                    yield { type: 'reasoning_delta', delta: seg.text };
+                }
+                else {
+                    if (reasoningOpen) {
+                        reasoningOpen = false;
+                        yield { type: 'reasoning_end' };
+                    }
+                    yield { type: 'text', delta: seg.text };
+                }
+            }
+        }
+        // CFG-33 — emit a message's content segments in order. A segment already classified as the
+        // model's thinking (a Gemini `thought: true` block) goes straight to the reasoning channel;
+        // answer text still passes through the TUI-C22 think splitter, so an inline `<think>` tag is
+        // peeled exactly as before. With no reasoning block this is the previous `.text` behaviour.
+        function* emitContentSegments(segments) {
+            for (const segment of segments) {
+                if (segment.kind === 'reasoning') {
+                    yield* emitSegments([segment]);
+                }
+                else {
+                    yield* emitSegments(thinkSplitter.push(segment.text));
+                }
+            }
+        }
         function* flushAggregated() {
             if (!aggregatedAIChunk)
                 return;
@@ -456,41 +882,37 @@ export class GthAbstractAgent {
             // GS2-16: fold every chunk (AIMessageChunk usage/tool_calls, ToolMessage name) into the
             // run tally so the TUI turn can record real token/tool data. Fail-soft.
             this.recordRunStats(chunk);
+            // EXT-41: reuse EXT-37's detector (do NOT fork a second one). First per-chunk signal wins;
+            // a ToolMessage / normal chunk yields null, so a normal turn never surfaces a false refusal.
+            if (!refusalInfo) {
+                refusalInfo = detectRefusal(chunk);
+            }
             if (AIMessageChunk.isInstance(chunk)) {
                 aggregatedAIChunk = aggregatedAIChunk ? aggregatedAIChunk.concat(chunk) : chunk;
-                // Reasoning deltas — Ollama (Qwen3, deepseek-r1) and Anthropic surface
-                // thinking text in additional_kwargs.reasoning_content. Stream it as a
-                // separate event series so clients can render it apart from the answer.
-                const reasoningDelta = chunk.additional_kwargs?.reasoning_content;
-                if (typeof reasoningDelta === 'string' && reasoningDelta.length > 0) {
-                    if (!reasoningOpen) {
-                        reasoningOpen = true;
-                        yield { type: 'reasoning_start' };
-                    }
-                    yield { type: 'reasoning_delta', delta: reasoningDelta };
-                }
-                // Yield text incrementally — use this chunk's text (delta), not the
-                // aggregated content which is cumulative.
-                if (chunk.text) {
-                    if (reasoningOpen) {
-                        reasoningOpen = false;
-                        yield { type: 'reasoning_end' };
-                    }
-                    yield { type: 'text', delta: chunk.text };
+                // Reasoning deltas — Ollama (Qwen3, deepseek-r1), Anthropic, and OpenRouter surface
+                // thinking in additional_kwargs.reasoning_content. Stream
+                // it as a separate event series so clients can render it apart from the answer.
+                const reasoningDelta = pickReasoningDelta(chunk.additional_kwargs);
+                if (reasoningDelta.length > 0) {
+                    yield* emitSegments([{ kind: 'reasoning', text: reasoningDelta }]);
                 }
+                // Yield text incrementally — use this chunk's text (delta), not the aggregated content
+                // which is cumulative. TUI-C22 routes it through the think splitter so inline
+                // <think>...</think> (buffered across chunks) is peeled into the reasoning channel and
+                // stripped from the answer; text with no think tags passes straight through unchanged.
+                // CFG-33 classifies the chunk's content blocks first, in order, so Gemini's `thought: true`
+                // blocks reach the reasoning channel instead of the answer; answer text still goes through
+                // the think splitter, thought text does not (it is already classified).
+                yield* emitContentSegments(segmentAssistantContent(chunk.content));
             }
             else if (AIMessage.isInstance(chunk)) {
                 // Reasoning on a non-chunk AIMessage — a non-streamed / resumed thinking message
                 // (e.g. a checkpoint replay) still carries its thinking in
-                // additional_kwargs.reasoning_content. Mirror the AIMessageChunk branch and emit the
-                // same reasoning event series, otherwise the thought is silently dropped (TUI-C15).
-                const reasoningContent = chunk.additional_kwargs?.reasoning_content;
-                if (typeof reasoningContent === 'string' && reasoningContent.length > 0) {
-                    if (!reasoningOpen) {
-                        reasoningOpen = true;
-                        yield { type: 'reasoning_start' };
-                    }
-                    yield { type: 'reasoning_delta', delta: reasoningContent };
+                // additional_kwargs.reasoning_content. Mirror the AIMessageChunk branch and emit the same
+                // reasoning event series, otherwise the thought is silently dropped (TUI-C15).
+                const reasoningContent = pickReasoningDelta(chunk.additional_kwargs);
+                if (reasoningContent.length > 0) {
+                    yield* emitSegments([{ kind: 'reasoning', text: reasoningContent }]);
                 }
                 // Non-chunk AIMessage (e.g. on resumed runs) carries final tool_calls
                 // directly; merge them into the aggregate so flushAggregated emits them.
@@ -501,15 +923,17 @@ export class GthAbstractAgent {
                     });
                     aggregatedAIChunk = aggregatedAIChunk ? aggregatedAIChunk.concat(synthetic) : synthetic;
                 }
-                if (chunk.text) {
-                    if (reasoningOpen) {
-                        reasoningOpen = false;
-                        yield { type: 'reasoning_end' };
-                    }
-                    yield { type: 'text', delta: chunk.text };
-                }
+                yield* emitContentSegments(segmentAssistantContent(chunk.content));
+                // A non-chunk AIMessage is a COMPLETE message, not a delta — drain any residual now
+                // (an unterminated <think> becomes reasoning, a dangling partial becomes answer) so its
+                // buffered state never leaks into a subsequent message (TUI-C22).
+                yield* emitSegments(thinkSplitter.flush());
             }
             if (chunk instanceof ToolMessage) {
+                // TUI-C22 — drain buffered think text (emitting its segments, which may open/close
+                // reasoning) BEFORE closing the reasoning block, so a trailing reasoning slice can't land
+                // after reasoning_end or be dropped. A tool round ends the assistant message, so reset.
+                yield* emitSegments(thinkSplitter.flush());
                 if (reasoningOpen) {
                     reasoningOpen = false;
                     yield { type: 'reasoning_end' };
@@ -532,12 +956,27 @@ export class GthAbstractAgent {
                 };
             }
         }
+        // TUI-C22 — drain any buffered think text at stream end (an unterminated <think> surfaces as
+        // reasoning, a dangling partial as answer) before closing the reasoning block.
+        yield* emitSegments(thinkSplitter.flush());
         // Close any still-open reasoning block before flushing tool calls.
         if (reasoningOpen) {
             yield { type: 'reasoning_end' };
         }
         // Flush any tool calls not followed by a ToolMessage (e.g. terminal tool calls).
         yield* flushAggregated();
+        // 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
+        // empty turn. No statusUpdate here: consumers render the typed events, and a WARNING would
+        // double-render in the TUI.
+        if (!refusalInfo && aggregatedAIChunk) {
+            refusalInfo = detectRefusal(aggregatedAIChunk);
+        }
+        if (refusalInfo) {
+            debugLog(`Content-policy refusal detected on typed-event path (provider=${refusalInfo.provider} reason=${refusalInfo.reason})`);
+            yield { type: 'text', delta: buildRefusalMessage(refusalInfo) };
+        }
     }
     async cleanup() {
         debugLog('Cleaning up agent...');