@gaunt-sloth/core 2.0.0-alpha.3 → 2.0.0-alpha.31

package/dist/core/GthLangChainAgent.js

@@ -1,10 +1,284 @@
+import { SHELL_TOOL_NAME, commandAnswersApprovals, resolveApprovals, resolveGatedToolNames, resolveInterruptToolNames, resolveShellApprovalGate, } from '#src/config.js';
 import { StatusLevel } from '#src/core/types.js';
 import { GthAbstractAgent } from '#src/core/GthAbstractAgent.js';
 import { debugLog, debugLogObject } from '#src/utils/debugUtils.js';
-import { formatToolCalls } from '#src/utils/llmUtils.js';
+import { buildSystemMessages, formatToolCalls, readModePrompt } from '#src/utils/llmUtils.js';
 import { getCurrentWorkDir } from '#src/utils/systemUtils.js';
-import { AIMessage } from '@langchain/core/messages';
-import { createAgent, createMiddleware } from 'langchain';
+import { isToolAllowed } from '#src/utils/toolMatching.js';
+import { appendOsShellNote, appendCwdNote, appendCommitCoAuthorNote, appendModelContextNote, appendMcpServerInstructionsNote, resolveModelIdentity, } from '#src/utils/systemPromptNotes.js';
+import { isShellCommandFailedError } from '#src/core/shell/ShellCommandFailedError.js';
+import { extractDebugRequestExtras } from '#src/core/debugCapture.js';
+import { promoteTextEmittedToolCallMessage } from '#src/core/toolCallRepair/index.js';
+import { AIMessage, ToolMessage } from '@langchain/core/messages';
+import { createAgent, createMiddleware, humanInTheLoopMiddleware, } from 'langchain';
+/**
+ * GS2-36 — default cap for the tool-error retry budget: how many status:'error' tool results may
+ * accrue back-to-back (no successful tool result in between) before the run is ended gracefully.
+ * Small on purpose: it still lets the model try a couple of genuine recovery variants (the whole
+ * point of feeding errors back — GS2-32 showed the model routes around a surfaced error in 1–2
+ * tries) while stopping a runaway self-inflicted loop long before createAgent's coarse
+ * recursionLimit backstop would.
+ */
+export const MAX_CONSECUTIVE_TOOL_ERRORS = 5;
+/**
+ * GS2-36 — the tool-error retry budget as a standalone, testable middleware factory (exported so the
+ * real thing can be unit-tested and exercised in a real `createAgent` graph, mirroring
+ * `createPathNamespaceCorrectionMiddleware`).
+ *
+ * Runs in `beforeModel` (like langchain's own `modelCallLimitMiddleware`): after the tools node has
+ * appended its result(s) and before the next model call is spent, it walks the trailing messages and
+ * counts CONSECUTIVE errored tool results — a `ToolMessage` with `status: 'error'` (the shape the
+ * shell/MCP softeners produce; GthAbstractAgent maps `status==='error' → isError`). The walk skips
+ * the assistant tool-call requests between rounds, and RESETS on the first successful tool result
+ * (progress / diagnosis) or a Human/System message (a fresh user turn). Once the count reaches the
+ * cap it returns `{ jumpTo: 'end', messages: [<action-oriented notice>] }`, ending the run without
+ * spending another model call.
+ *
+ * Scope: counts `status: 'error'` results only. The recoverable fs error STRINGS
+ * (`write_file`/`edit_file`/…) are `status: 'success'` by the write_file precedent, so a pure fs
+ * error loop is deliberately NOT capped here — it stays bounded by the coarse `recursionLimit` and is
+ * the remit of the loop-DETECTION node (EXT-36). Counting `status: 'error'` overall (not per-tool)
+ * catches both same-tool and alternating-tool error loops with one robust rule.
+ */
+export function createToolErrorBudgetMiddleware(maxConsecutiveErrors = MAX_CONSECUTIVE_TOOL_ERRORS) {
+    return createMiddleware({
+        name: 'GthLeanToolErrorBudget',
+        beforeModel: {
+            canJumpTo: ['end'],
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            hook: (state) => {
+                const messages = Array.isArray(state?.messages) ? state.messages : [];
+                let consecutive = 0;
+                let lastErrorContent = '';
+                for (let i = messages.length - 1; i >= 0; i--) {
+                    const msg = messages[i];
+                    if (ToolMessage.isInstance(msg)) {
+                        if (msg.status === 'error') {
+                            consecutive++;
+                            if (!lastErrorContent) {
+                                lastErrorContent = typeof msg.content === 'string' ? msg.content : '';
+                            }
+                        }
+                        else {
+                            // A successful tool result — the model is making progress / diagnosing, so the
+                            // unrecovered-error streak is broken. Stop the walk (reset).
+                            break;
+                        }
+                    }
+                    else if (AIMessage.isInstance(msg)) {
+                        // The assistant tool-call request that produced the error above; skip and keep counting.
+                        // GS2-72: this `continue` INTENTIONALLY also skips the budget's OWN injected terminal
+                        // notice (itself an AIMessage). If the run re-enters beforeModel on the same thread after
+                        // a jumpTo:'end' (a re-invoke on the same thread — e.g. the no-checkpointer degrade of
+                        // the string path's empty-stream fallback, or a later turn that keeps erroring), skipping
+                        // the notice lets the walk still reach the errored results and re-trip deterministically.
+                        // Do NOT special-case the notice to reset/break here — treating it as a fresh-turn
+                        // boundary would let the capped loop resume.
+                        continue;
+                    }
+                    else {
+                        // A Human/System message: a fresh user-turn boundary — earlier errors don't count.
+                        break;
+                    }
+                }
+                if (consecutive >= maxConsecutiveErrors) {
+                    const firstLine = (lastErrorContent.split('\n')[0] ?? '').slice(0, 300);
+                    const notice = `Stopped after ${consecutive} consecutive failed tool calls to avoid a retry loop that ` +
+                        'keeps spending tokens without making progress' +
+                        (firstLine ? ` (last error: ${firstLine})` : '') +
+                        '. Do not repeat the same call: inspect the error, then change your approach — different ' +
+                        'arguments, a narrower path, or a different tool — or report the blocker to the user.';
+                    return { jumpTo: 'end', messages: [new AIMessage(notice)] };
+                }
+                return undefined;
+            },
+        },
+    });
+}
+/**
+ * EXT-36 — default number of consecutive identical `(tool, args)` calls before the tool-loop guard
+ * fires. Small on purpose: it must catch a genuine no-progress loop (a model re-issuing the SAME
+ * call verbatim) while never tripping a legitimate one-off retry (2x). Kept below GS2-36's coarser
+ * error cap (5) because a same-signature repeat is a stronger, more specific loop signal than "an
+ * error happened again".
+ */
+export const DEFAULT_TOOL_LOOP_THRESHOLD = 3;
+/**
+ * EXT-36 — normalise the `toolLoopGuard` config union (`false | true | { warn?, halt?, threshold? }`)
+ * into concrete {@link ToolLoopGuardOptions}, applying the WARN-ON-by-default policy at the read site
+ * (mirrors how `output.header` / `debugDump.redact` default with `!== false`, NOT in DEFAULT_CONFIG,
+ * so the effective-config snapshot never churns).
+ * - `false` → both modes off (a no-op guard);
+ * - `true` / absent → warn on, halt off, default threshold;
+ * - object → per-field, with warn defaulting ON and halt defaulting OFF.
+ */
+export function resolveToolLoopGuardOptions(setting) {
+    if (setting === false)
+        return { warn: false, halt: false };
+    if (setting === true || setting === undefined || setting === null)
+        return {};
+    return { warn: setting.warn, halt: setting.halt, threshold: setting.threshold };
+}
+/**
+ * EXT-36 — a deterministic, key-sorted stringify so `(tool, args)` signatures are stable regardless
+ * of object key order. No-args (`{}`) collapses to `"{}"`, so identical no-arg repeats collide BY
+ * DESIGN — that is exactly the loop signal. Known limitation: args carrying a volatile value (a
+ * timestamp / uuid) make every call look distinct, so the guard cannot see that loop; volatile-key
+ * stripping is deliberately NOT attempted (over-engineering for a rare, model-authored case).
+ */
+function stableStringify(value) {
+    if (value === null || typeof value !== 'object')
+        return JSON.stringify(value) ?? 'null';
+    if (Array.isArray(value))
+        return `[${value.map(stableStringify).join(',')}]`;
+    const record = value;
+    const keys = Object.keys(record).sort();
+    return `{${keys.map((k) => `${JSON.stringify(k)}:${stableStringify(record[k])}`).join(',')}}`;
+}
+/**
+ * The delimiter between a tool name and its serialised arguments in a call signature. U+0000 is
+ * chosen because a tool name cannot contain a control character, so no `(name, args)` pair can be
+ * spelled two ways and no pair of distinct calls can collide on one signature.
+ *
+ * It MUST stay written as this escape. A raw NUL byte in the source makes the whole file binary to
+ * ripgrep and ugrep, which then skip it in silence — every symbol in this file becomes invisible to
+ * a repo-wide search, and an empty result reads as proof of absence. `noRawControlBytes.spec.ts` guards
+ * the repo against the raw form returning.
+ */
+export const TOOL_CALL_SIGNATURE_DELIMITER = '\u0000';
+/**
+ * EXT-36 — the `(tool, args)` identity a repeat-detection streak is counted over. Exported so the
+ * delimiter invariant above is asserted directly rather than inferred from loop behaviour.
+ */
+export function toolCallSignature(name, args) {
+    return `${name}${TOOL_CALL_SIGNATURE_DELIMITER}${stableStringify(args ?? {})}`;
+}
+/**
+ * EXT-36 — the tool-loop guardrail as a standalone, testable middleware factory. The ORTHOGONAL
+ * sibling of {@link createToolErrorBudgetMiddleware}: GS2-36 caps a consecutive-tool-ERROR streak;
+ * this catches a **repeated identical `(tool, args)` / no-progress loop** — the same call re-issued
+ * verbatim, whether it keeps erroring OR keeps "succeeding" with the same result (the fs-error-string
+ * loop GS2-36's comment explicitly leaves to EXT-36).
+ *
+ * STATELESS (the critical trap): the factory runs ONCE per session, so a closure-held counter would
+ * bleed across every turn. Like GS2-36 it holds NO state — each `beforeModel` recomputes the streak
+ * from the message tail.
+ *
+ * Detection. A signature is `(tool_name, args_hash)`. Name + args live on `AIMessage.tool_calls[]`,
+ * NOT on the `ToolMessage` (softener ToolMessages carry only content+tool_call_id+status), so each
+ * `ToolMessage` is paired to its call by `tool_call_id === AIMessage.tool_calls[].id` to recover the
+ * signature. The backward walk counts CONSECUTIVE ToolMessages with the SAME signature; a DIFFERENT
+ * signature breaks the streak (the model tried something else = progress), and a Human/System message
+ * is a fresh-turn boundary. Assistant messages (the tool-call requests) are skipped. Known no-op
+ * (safe, never a false trip): a single AIMessage issuing PARALLEL tool calls yields back-to-back
+ * differing signatures, which the walk reads as progress and resets.
+ *
+ * Two modes (composable):
+ * - WARN (default ON, provably harmless): the default path must NOT change what the model sees.
+ *   Appending ANY message then re-invoking the model mutates its input — a *steer*, not a *warn* —
+ *   and is provider-unsafe by default (Gemini expects a trailing user turn → crash risk; Anthropic
+ *   treats a trailing assistant as PREFILL → the note silently becomes the opening of the model's own
+ *   next reply, corrupt with no error; a HumanMessage after a ToolMessage is two consecutive user
+ *   turns for Anthropic/Gemini). So WARN instead SURFACES a user-visible notice via {@link onWarn}
+ *   and returns `undefined` — zero `state.messages` mutation, zero control-flow. Fired statelessly
+ *   ONCE per streak at the exact crossing (`streak === threshold`): a still-looping streak on later
+ *   turns (`streak > threshold`) does not re-surface, while an interrupted-then-resumed loop
+ *   re-reaches `threshold` and surfaces again — no marker/`additional_kwargs` machinery needed.
+ * - HALT (opt-in only, active loop-breaking): at/over threshold, return
+ *   `{ jumpTo: 'end', messages: [new AIMessage(reason)] }` — a TERMINAL notice (the model is never
+ *   re-invoked after it, so the prefill/role hazard cannot arise; the GS2-72-proven clean-stream
+ *   path). NEVER throws. A validated behaviour change lives behind this opt-in.
+ *
+ * @param onWarn TUI-safe user-notice sink for WARN, wired at the read site to
+ *   `statusUpdate(StatusLevel.WARNING, …)` (routed through the agent's status callback the renderer
+ *   consumes, never raw stdout, so it can't leak over the Ink frame). Omitted → WARN still runs but
+ *   surfaces nothing (still zero model-input mutation).
+ */
+export function createToolLoopGuardMiddleware(options = {}, onWarn) {
+    const warn = options.warn ?? true;
+    const halt = options.halt ?? false;
+    const threshold = options.threshold ?? DEFAULT_TOOL_LOOP_THRESHOLD;
+    return createMiddleware({
+        name: 'GthLeanToolLoopGuard',
+        beforeModel: {
+            canJumpTo: ['end'],
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            hook: (state) => {
+                // `false` config resolves to warn:false + halt:false — a genuine no-op (fast bail).
+                if (!warn && !halt)
+                    return undefined;
+                const messages = Array.isArray(state?.messages) ? state.messages : [];
+                // Recover each tool call's signature by id — name + args are on the AIMessage, not the
+                // ToolMessage. One pass over all AIMessages builds the id → {sig, name} lookup.
+                const callById = new Map();
+                for (const msg of messages) {
+                    if (AIMessage.isInstance(msg) && Array.isArray(msg.tool_calls)) {
+                        for (const tc of msg.tool_calls) {
+                            const id = tc?.id;
+                            if (typeof id === 'string') {
+                                const name = typeof tc.name === 'string' ? tc.name : '';
+                                // Signature identity + its delimiter: see toolCallSignature.
+                                callById.set(id, { sig: toolCallSignature(name, tc.args), name });
+                            }
+                        }
+                    }
+                }
+                // Walk the tail backward, counting consecutive identical signatures since the last boundary.
+                let streak = 0;
+                let currentSig;
+                let currentName = '';
+                for (let i = messages.length - 1; i >= 0; i--) {
+                    const msg = messages[i];
+                    if (ToolMessage.isInstance(msg)) {
+                        const call = callById.get(msg.tool_call_id);
+                        // No paired call → cannot prove a repeat; treat as a boundary (never a false trip).
+                        if (!call)
+                            break;
+                        if (currentSig === undefined) {
+                            currentSig = call.sig;
+                            currentName = call.name;
+                            streak = 1;
+                        }
+                        else if (call.sig === currentSig) {
+                            streak++;
+                        }
+                        else {
+                            break; // different signature = the model tried something else = progress
+                        }
+                    }
+                    else if (AIMessage.isInstance(msg)) {
+                        continue; // the tool-call request — skip and keep counting the streak
+                    }
+                    else {
+                        break; // Human/System message: a fresh user turn resets everything.
+                    }
+                }
+                if (currentSig === undefined || streak < threshold)
+                    return undefined;
+                // HALT (opt-in): end the run cleanly — never a throw. Terminal, so the model is never
+                // re-invoked after this AIMessage (no prefill/role hazard). Takes precedence over WARN.
+                if (halt) {
+                    const notice = `Stopped after ${streak} identical calls to the \`${currentName}\` tool with the same ` +
+                        'arguments to avoid a loop that keeps spending tokens without making progress. ' +
+                        'The same call cannot yield a different result: change your approach — different ' +
+                        'arguments, a narrower step, or a different tool — or report the blocker to the user.';
+                    return { jumpTo: 'end', messages: [new AIMessage(notice)] };
+                }
+                // WARN (default): SURFACE a user-visible notice and DO NOT touch state.messages (return
+                // undefined → the model's input is byte-for-byte unchanged, so no prefill/role hazard on any
+                // provider). Fire once per streak at the exact crossing: `streak === threshold` is a
+                // stateless "fire once" — a still-looping streak (streak > threshold) stays quiet, while an
+                // interrupted-then-resumed loop re-reaches threshold and surfaces again.
+                if (warn && streak === threshold) {
+                    onWarn?.(`Tool-loop guard: the agent has called \`${currentName}\` with the same arguments ` +
+                        `${streak} times without new progress. It may be stuck — consider interrupting and ` +
+                        'refining the request.');
+                }
+                return undefined;
+            },
+        },
+    });
+}
 /**
  * Lean agent: builds a standard `createAgent` (ReAct) graph. All run/stream/event
  * plumbing lives in {@link GthAbstractAgent}; this class only knows how to construct
@@ -22,16 +296,16 @@ export class GthLangChainAgent extends GthAbstractAgent {
             streamOutput: this.config.streamOutput,
             debugLog: this.config.debugLog,
         });
-        this.statusUpdate(StatusLevel.INFO, `Workdir: ${getCurrentWorkDir()}`);
+        this.headerStatus(`Workdir: ${getCurrentWorkDir()}`);
         if (this.config.modelDisplayName) {
-            this.statusUpdate(StatusLevel.INFO, `Model: ${this.config.modelDisplayName}`);
+            this.headerStatus(`Model: ${this.config.modelDisplayName}`);
         }
         // An empty allowedTools allow-list disables every tool. Skip resolution entirely so we
         // don't contact MCP servers (and trigger OAuth) just to discard the result.
         const allowedTools = this.config.allowedTools;
         const toolsDisabled = Array.isArray(allowedTools) && allowedTools.length === 0;
         if (toolsDisabled) {
-            this.statusUpdate(StatusLevel.INFO, 'Tool loading disabled by allowedTools: []; MCP/A2A servers will not be contacted. Omit allowedTools for no filtering.');
+            this.headerStatus('Tool loading disabled by allowedTools: []; MCP/A2A servers will not be contacted. Omit allowedTools for no filtering.');
         }
         // Resolve tools via resolver or fall back to config tools only
         debugLog('Resolving tools...');
@@ -47,19 +321,20 @@ export class GthLangChainAgent extends GthAbstractAgent {
         // Combine all tools, then apply the allowedTools name allow-list when configured.
         let tools = [...resolvedTools, ...flattenedConfigTools];
         if (Array.isArray(allowedTools)) {
-            const allowed = new Set(allowedTools);
-            // Filter named tools by the allow-list. ServerTools (provider-native "magic objects" such
-            // as Anthropic web search) may have no `name`, so they can never be referenced in the
-            // allow-list - drop-by-default would silently remove them with no recourse. Retain such
-            // nameless tools instead; the allow-list is a name-based filter and cannot target them.
-            tools = tools.filter((tool) => !tool.name || allowed.has(tool.name));
+            // Filter named tools by the allow-list. Entries match by exact name, or glob-style when
+            // they contain `*` (e.g. `mcp__unimarket__*`) — see isToolAllowed. ServerTools
+            // (provider-native "magic objects" such as Anthropic web search) may have no `name`, so
+            // they can never be referenced in the allow-list - drop-by-default would silently remove
+            // them with no recourse. Retain such nameless tools instead; the allow-list is a name-based
+            // filter and cannot target them.
+            tools = tools.filter((tool) => !tool.name || isToolAllowed(tool.name, allowedTools));
         }
         if (tools.length > 0) {
             const toolNames = tools
                 .map((tool) => tool.name)
                 .filter((name) => name)
                 .join(', ');
-            this.statusUpdate(StatusLevel.INFO, `Loaded tools: ${toolNames}`);
+            this.headerStatus(`Loaded tools: ${toolNames}`);
             debugLog(`Total tools available: ${tools.length}`);
             debugLogObject('All Tools', toolNames.split(', '));
         }
@@ -87,15 +362,367 @@ export class GthLangChainAgent extends GthAbstractAgent {
                 return state;
             },
         });
-        // Combine all middleware
-        const middleware = [...configuredMiddleware, toolCallStatusMiddleware];
-        this.statusUpdate(StatusLevel.INFO, `Loaded middleware: ${middleware.map((m) => m.name).join(', ')}`);
-        // Create agent with configured middleware
+        // EXT-35: promote a text-emitted tool call to a native tool_call so the loop doesn't stall.
+        // Small/local models (Gemma, lmstudio, gpt-oss) often serialise a tool call as assistant TEXT
+        // instead of a native `tool_call`; the ReAct router then sees no tool_calls on the last message
+        // and ENDS the turn ("no tool calls = done"). This afterModel hook runs ONLY when the last
+        // AIMessage carries no native tool_calls (the native happy path is byte-for-byte untouched):
+        // it parses a STANDALONE text-emitted call (bracket / <function=…> / Harmony), gated HARD by the
+        // bound-tool allow-list + a payload-size cap + standalone-only, and — when it promotes — returns
+        // the rewritten message. Preserving the original message id is load-bearing: LangGraph's
+        // message-state reducer merges by id, so a same-id message REPLACES the model's text message in
+        // graph state; the router then sees the native tool_calls and routes to the tools node, so the
+        // loop continues instead of concluding done. Ported from the openclaw tool-call-repair reference.
+        // Bound-tool names are the allow-list; an empty toolset promotes nothing (prose-safe default).
+        const repairToolNames = new Set(tools.map((t) => t.name).filter((name) => Boolean(name)));
+        const toolCallRepairMiddleware = createMiddleware({
+            name: 'GthMiddlewareToolCallRepair',
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            afterModel: (state) => {
+                const lastMessage = state.messages[state.messages.length - 1];
+                if (!AIMessage.isInstance(lastMessage))
+                    return state;
+                if (lastMessage.tool_calls && lastMessage.tool_calls.length > 0)
+                    return state;
+                const promoted = promoteTextEmittedToolCallMessage(lastMessage, {
+                    allowedToolNames: repairToolNames,
+                });
+                if (!promoted)
+                    return state;
+                debugLog(`Repaired a text-emitted tool call into a native tool_call: ${formatToolCalls(promoted.tool_calls ?? [])}`);
+                // Replace-by-id (same id) so the reducer swaps the text message rather than appending.
+                return { messages: [promoted] };
+            },
+        });
+        // EXT-21: lean-path sibling of the deep agent's GthDeepShellExitSoftening (GthDeepAgent.ts).
+        // `exec` / `ask --write` route through this lean `createAgent` graph, whose run_* shell/dev
+        // tools (GthDevToolkit.executeCommand) THROW a ShellCommandFailedError on a non-zero exit or a
+        // timeout-kill. langchain's default ToolNode would catch that throw into a ToolMessage but leave
+        // it status:'success' (✓) — misreporting a failed command. Catch it here at the tool-wrap layer
+        // and return an error ToolMessage that PRESERVES the full stdout/stderr body: the model's
+        // observation is unchanged except the status flips to 'error', which drives the ✗ (isError)
+        // glyph (GthAbstractAgent maps status==='error' → isError). Returning a ToolMessage (rather than
+        // rethrowing) keeps it a normal, observed tool result — no run-abort, no retry loop. Recognised
+        // via isShellCommandFailedError (instanceof + structural fallback) since core cannot import the
+        // throw site in the agent package. Every OTHER throw is rethrown untouched so genuine failures
+        // and control-flow (GraphInterrupt / AbortError) still surface.
+        const shellExitSoftening = createMiddleware({
+            name: 'GthLeanShellExitSoftening',
+            wrapToolCall: async (request, handler) => {
+                try {
+                    return await handler(request);
+                }
+                catch (e) {
+                    if (isShellCommandFailedError(e)) {
+                        debugLog(`Softened shell/dev command failure (exit ${e.exitCode ?? 'timeout'}) into an ` +
+                            `error ToolMessage for '${e.command}'`);
+                        return new ToolMessage({
+                            content: e.output,
+                            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                            tool_call_id: request.toolCall?.id ?? '',
+                            status: 'error',
+                        });
+                    }
+                    throw e;
+                }
+            },
+        });
+        // MCP tool-execution errors are spec-compliant RESULTS, not fatal faults. Per the MCP spec
+        // (2025-11-25 & draft, "Server › Tools › Error Handling"), a tool that hits an API failure, an
+        // input-validation problem, or a business-logic error (e.g. a disabled capability) returns a
+        // normal tools/call result with `isError: true`, and the CLIENT *SHOULD* hand that error to the
+        // model so it can self-correct. `@langchain/mcp-adapters` instead surfaces such a result by
+        // THROWING a ToolException at call time (its `_convertCallToolResult`). Because we install a
+        // wrapToolCall middleware, langchain's ToolNode treats any error a middleware rethrows as a fatal
+        // "middleware error" (`errorFromMiddleware && handleToolErrors !== true` → throw) and aborts the
+        // whole turn instead of relaying the error to the model — the opposite of the spec's client
+        // SHOULD. This middleware closes that gap: it catches a thrown ToolException and RETURNS it as a
+        // status:'error' ToolMessage (→ isError → ✗), so the model observes the error and can retry or
+        // explain (matching the non-stream invoke path's ToolException handling). Scope & safety: matched
+        // by name === 'ToolException' (the adapter's marker), so GraphInterrupt and every non-MCP throw
+        // fall through the final rethrow untouched. The adapter ALSO wraps a call-time AbortError into a
+        // ToolException (its `_callTool` catch-all), so we RETHROW when the run's abort signal is set —
+        // otherwise softening here would swallow user cancellation that ToolNode's own `signal?.aborted`
+        // guard normally enforces (bypassed once we handle the error in middleware). MCP connect/auth
+        // (401/403) and load failures are handled at CONNECT time (resolvers.ts throwOnLoadError +
+        // onConnectionError), not here, so they stay fatal as intended.
+        const mcpToolErrorSoftening = createMiddleware({
+            name: 'GthMcpToolErrorSoftening',
+            wrapToolCall: async (request, handler) => {
+                try {
+                    return await handler(request);
+                }
+                catch (e) {
+                    if (e instanceof Error &&
+                        e.name === 'ToolException' &&
+                        !request.runtime?.signal?.aborted) {
+                        debugLog(`Softened MCP tool error into an error ToolMessage: ${e.message}`);
+                        return new ToolMessage({
+                            content: e.message,
+                            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                            tool_call_id: request.toolCall?.id ?? '',
+                            status: 'error',
+                        });
+                    }
+                    throw e;
+                }
+            },
+        });
+        // Debug-capture middleware (TUI `/debug` panel) — the lean-path sibling of GthDeepAgent's.
+        // Always installed but lazy: it reads `this.debugCapture` per call, so until the TUI attaches a
+        // sink it is a transparent pass-through (one extra await around the handler — the normal path
+        // pays nothing). `request.messages` is the real history at call time; `handler(request)`
+        // resolves to the AIMessage response. Without this, the TUI's System-prompt/Tools/Chat-history
+        // tabs stay empty on the (now default) lean backend.
+        const getDebugCapture = () => this.debugCapture;
+        const debugCaptureMiddleware = createMiddleware({
+            name: 'GthMiddlewareDebugCapture',
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            wrapModelCall: async (request, handler) => {
+                // GS2-56: stash the always-on last-model-request snapshot (extras + as-sent messages)
+                // UNCONDITIONALLY — before the `capture` short-circuit — so `/debug-dump` has the full
+                // model input even when no TUI `/debug` sink is attached (a non-TUI surface, or `/debug`
+                // never opened). Guarded: snapshotting must never break the run. The computed extras are
+                // reused for the sink below so extraction runs once.
+                let extras;
+                try {
+                    extras = extractDebugRequestExtras(request);
+                    this.setLastModelRequest(request.messages, extras);
+                }
+                catch {
+                    /* the always-on snapshot must never break the run */
+                }
+                const capture = getDebugCapture();
+                if (!capture)
+                    return handler(request);
+                try {
+                    capture.onRequest?.(request.messages, extras);
+                }
+                catch {
+                    /* a debug sink must never break the run */
+                }
+                const response = await handler(request);
+                try {
+                    capture.onResponse?.(response);
+                }
+                catch {
+                    /* a debug sink must never break the run */
+                }
+                return response;
+            },
+        });
+        // shellExitSoftening FIRST so it is the outermost wrapToolCall — it must see the raw
+        // ShellCommandFailedError throw before any user-configured middleware could transform it.
+        // mcpToolErrorSoftening sits right after it, still outboard of any user-configured middleware so
+        // it sees the raw ToolException before a user wrapToolCall could transform it. Order between the
+        // two softeners is not load-bearing: they catch DISJOINT conditions (a ShellCommandFailedError
+        // vs a name==='ToolException') and each rethrows what it doesn't recognize, so neither can
+        // swallow the other.
+        // EXT-35: toolCallRepairMiddleware sits AFTER toolCallStatusMiddleware in the array. afterModel
+        // nodes execute in reverse array order (the later one runs first), so repair runs BEFORE the
+        // status middleware — a promoted call is therefore reported by the "Requested tools:" line too.
+        // Correctness (routing) is order-independent: the router reads final graph state after all
+        // afterModel nodes, and repair replaces-by-id, so the promoted tool_calls are present regardless.
+        // GS2-36: cap a self-inflicted tool-error loop. The shell/MCP softeners above turn a failed
+        // run_*/MCP call into a status:'error' ToolMessage the model observes; a model that keeps
+        // re-issuing the same failing call would drain tokens turn after turn. This beforeModel guard
+        // ends the run gracefully once MAX_CONSECUTIVE_TOOL_ERRORS such results accrue with no successful
+        // tool result in between — a tighter, error-specific complement to createAgent's coarse
+        // recursionLimit (loop DETECTION proper is the separate EXT-36). Placed after the softeners and
+        // before user middleware so it can't be bypassed. Lean backend only (per GS2-36 scope); the deep
+        // backend keeps its own recursionLimit backstop.
+        const toolErrorBudget = createToolErrorBudgetMiddleware();
+        // EXT-36: the ORTHOGONAL loop guard — repeated identical (tool, args) / no-progress detection,
+        // the sibling of GS2-36's error budget above. It catches the case GS2-36 explicitly leaves open:
+        // a model re-issuing the SAME call verbatim, whether it keeps erroring or keeps "succeeding" with
+        // the same result. Placed at index 3, immediately AFTER toolErrorBudget (index 2) and BEFORE user
+        // middleware: beforeModel hooks run in forward order with jumpTo short-circuiting, so on a
+        // simultaneous trip GS2-36's coarse error cap wins first and EXT-36 fires on its own
+        // signature-repeat threshold otherwise; keeping it outboard of user middleware means it can't be
+        // bypassed. WARN is on by default and SURFACES a user notice WITHOUT touching state.messages (the
+        // default path must never mutate the model's input — appending a message + re-invoking is a
+        // provider-unsafe steer, not a warn); HALT (opt-in) actively breaks the loop via a terminal
+        // jumpTo:'end'. Default WARN-ON is applied here at the read site (resolveToolLoopGuardOptions),
+        // NOT in DEFAULT_CONFIG, so the
+        // effective-config snapshot never churns. Lean backend only (like GS2-36); the deep array is
+        // untouched. `toolLoopGuard: false` resolves to a no-op guard (still installed at index 3 so the
+        // placement is stable).
+        const toolLoopGuard = createToolLoopGuardMiddleware(resolveToolLoopGuardOptions(this.config.toolLoopGuard), 
+        // WARN surfaces through the same TUI-safe status channel every other agent notice uses
+        // (renderer-consumed, never raw stdout) so it can't leak over the Ink frame (TUI-C31).
+        (message) => statusUpdate(StatusLevel.WARNING, message));
+        // EXT-52: gate the opt-in run_shell_command tool behind the SAME per-command approval
+        // interrupt the deep backend has always wired (deepagents' `interruptOn` installs this very
+        // langchain `humanInTheLoopMiddleware` — see GthDeepAgent.buildDeepAgentParams). Without it,
+        // no interrupt ever fired on the lean (default) backend, so the runner's whole approval stack
+        // (`GthAgentRunner.decideToolApproval`: sessionYolo → allow-list → judge → human callback,
+        // fail-closed reject) was DEAD CODE on lean and shell commands ran unprompted. A matching tool
+        // call now suspends the graph with a HITLRequest interrupt; the runner drains it via
+        // getPendingToolInterrupts/streamResume (both backend-agnostic in GthAbstractAgent), so ONE
+        // gating code path drives both backends and the existing TUI + readline approval prompts fire
+        // identically on lean.
+        //
+        // The gate condition and its user-facing notices are the SHARED policy
+        // (`resolveShellApprovalGate`, EXT-12 semantics documented there); the two backends differ only
+        // in how they install the interrupt — directly as middleware here, via deepagents' `interruptOn`
+        // in GthDeepAgent.
+        const { gateShell, notice: shellGateNotice } = resolveShellApprovalGate(this.config ?? undefined, this.command);
+        //
+        // EXT-80: the shell is not the whole story. At `manual` and `write` every bound tool the
+        // rung's access class does not auto-grant — the write built-ins, MCP tools, custom tools — must
+        // reach the human, because those two rungs promise the user that anything beyond reading
+        // (respectively, beyond reading and writing files here) comes to them.
+        //
+        // **The interrupt is wired rung-INDEPENDENTLY, over every tool any rung could gate.** It is
+        // installed once, here, while `/approvals <rung>` moves the rung for the rest of the session
+        // without rebuilding this graph; a set that carried the rung would be frozen at the rung the
+        // session started on, and since the default is `assisted`, typing `/approvals manual` would
+        // leave exactly the write tools ungated. `GthAgentRunner.decideToolApproval` decides on the rung
+        // in force instead, which is where the rung has always been read — so wiring wider does not gate
+        // wider: at a rated rung a non-shell call is approved there with no rating call and no prompt.
+        //
+        // Both sets come from core's shared policy, which the deep backend and the runner also call, so
+        // no two of the three can disagree; and both read the FINAL tool array below rather than any
+        // static list, because a hand-written list cannot contain an MCP or custom tool, which is
+        // exactly what has to escalate.
+        const rung = resolveApprovals(this.config ?? undefined, this.command).rung;
+        const boundToolNames = tools
+            .map((tool) => tool?.name)
+            .filter((name) => typeof name === 'string' && name.length > 0);
+        // **What a surface that answers no approval gets — for BOTH sets below.** An interrupt nobody
+        // can answer suspends the graph forever: the tool never runs and the client is never asked. So
+        // such a surface is wired with exactly what the shell gate itself requires and nothing more,
+        // and is not TOLD it will be asked either. Neither the live set nor the interrupt set is a safe
+        // fallback here — both are non-empty at `manual` and `write`, which is precisely where an
+        // AG-UI server's writes and MCP calls would vanish, or be announced as approvable when nothing
+        // will ever approve them.
+        const answersApprovals = commandAnswersApprovals(this.command);
+        const noDrainTools = gateShell ? [SHELL_TOOL_NAME] : [];
+        // The LIVE gated set — what THIS rung gates — for the §4.5 tool descriptions below. Narrower
+        // than the interrupt set at the rated rungs, and it must stay so: a description promising an
+        // approval the runner will not ask for is the drift §4.5 calls worse than no description.
+        const gatedTools = answersApprovals
+            ? resolveGatedToolNames({ rung, gateShell, boundToolNames })
+            : noDrainTools;
+        // Rung-independent ONLY where something answers the interrupt.
+        const interruptTools = answersApprovals
+            ? resolveInterruptToolNames({ gateShell, boundToolNames })
+            : noDrainTools;
+        // Installed on the interrupt SET, not on `gateShell`: at a deterministic rung there is a gate to
+        // install even when the shell tool is disabled or the command emits no dev tools (a plain
+        // `chat` session with MCP servers). Keying the install off `gateShell` there would leave every
+        // one of those tools ungated while the rung's description promised otherwise.
+        const approvalMiddleware = interruptTools.length > 0
+            ? [
+                humanInTheLoopMiddleware({
+                    interruptOn: Object.fromEntries(interruptTools.map((name) => [
+                        name,
+                        { allowedDecisions: ['approve', 'reject'] },
+                    ])),
+                }),
+            ]
+            : [];
+        if (shellGateNotice) {
+            this.statusUpdate(shellGateNotice.level, shellGateNotice.message);
+        }
+        // EXT-58 (spec §4.5) — state the approvals posture where the model reads it: on the tool
+        // descriptions themselves. Every tool NOT auto-approved at the resolved rung gets the rung's
+        // sentence appended; every granted tool keeps its description exactly as written, because the
+        // ABSENCE of the sentence is what marks it free. `gatedTools` is the LIVE set for the rung in
+        // force — narrower than the interrupt set above, which covers every rung so the rung can still
+        // move — so a description can never promise an approval this rung will not ask for. Applied
+        // after the allowedTools filter and before createAgent, so the model only ever sees the final,
+        // suffixed set.
+        this.registerApprovalsAwareTools(tools, { rung, gatedTools });
+        // EXT-52 placement note: the HITL gate sits EARLY in the array — before user-configured
+        // middleware and, crucially, before toolCallRepairMiddleware — because afterModel hooks run in
+        // REVERSE array order (the EXT-35 rule above). The gate's afterModel therefore executes LAST,
+        // after EXT-35's repair has promoted a text-emitted `run_shell_command` into a native
+        // tool_call, so a small local model that serialises the call as text is gated too (were the
+        // gate appended last, like deepagents does on the deep path, it would run FIRST and a promoted
+        // shell call would bypass approval entirely).
+        const middleware = [
+            shellExitSoftening,
+            mcpToolErrorSoftening,
+            toolErrorBudget,
+            toolLoopGuard,
+            ...approvalMiddleware,
+            ...configuredMiddleware,
+            toolCallStatusMiddleware,
+            toolCallRepairMiddleware,
+            debugCaptureMiddleware,
+        ];
+        this.headerStatus(`Loaded middleware: ${middleware.map((m) => m.name).join(', ')}`);
+        // GS2-21: compose gsloth's system prompt (backstory + guidelines + per-command mode prompt +
+        // system prompt) EXACTLY as GthDeepAgent does, so identity profiles and `.gsloth.*.md` are
+        // honored on the lean backend too. Previously the lean agent gave the model NO system prompt
+        // (only the deep agent composed one), so `system-prompt.md` / the guidelines never reached
+        // the model — the robot (agent.backend: lean) behaved as if it never got its guidelines.
+        // This is passed to createAgent as `systemPrompt`, which langchain applies as the agent's
+        // static system message on every turn — NOT injected as a separate mid-conversation
+        // SystemMessage (a non-first system message that Anthropic rejects). GS2-79: which mode prompt
+        // a command gets is decided ONCE, in core's `readModePrompt` — 'code' the code-mode prompt,
+        // 'exec' the exec-mode prompt, 'review'/'pr' the REVIEW INSTRUCTIONS, chat/api/others the chat
+        // prompt — so this backend and the deep one cannot disagree, and a command left out of the
+        // selection can no longer be served the chat prompt by silent default.
+        const modePrompt = readModePrompt(this.command, this.config);
+        const systemMessages = buildSystemMessages(this.config, modePrompt);
+        const baseSystemPrompt = typeof systemMessages[0]?.content === 'string' ? systemMessages[0].content : undefined;
+        // GS2-27: in `code` mode append the SHARED code-mode notes the deep backend has always carried
+        // — the real-cwd / path-model note (EXT-13) and the OS + shell-dialect note (EXT-26). Both are
+        // backend-agnostic (the lean backend also exposes `run_shell_command` and runs on the real-fs
+        // cwd), so composing them here closes the deep-only drift that left a lean code session with no
+        // cwd value and no shell-dialect guidance (e.g. on Windows). The deepagents virtual-fs-namespace
+        // notes stay deep-only (lean never runs virtualMode). Same order the deep backend's real-path
+        // branch uses: cwd note first, OS/shell note last. `getCurrentWorkDir()` is already read above
+        // for the status line, so the value is free.
+        // GS2-34/EXT-83: resolve the active model identity ONCE, honouring the `injectModelContext`
+        // opt-out (default ON) at this single read site. Both consumers below take this same value, so
+        // the commit trailer and the model-context note can never disagree about which model is serving
+        // the session — and the opt-out means "my model identity stays out of the prompt", which covers
+        // the trailer as much as the identity line.
+        const modelIdentity = this.config.injectModelContext !== false ? resolveModelIdentity(this.config) : undefined;
+        // GS2-35: also append the commit co-authoring rule so the agent credits Gaunt Sloth (config
+        // `commit.coAuthor`, defaulting to the Gaunt Sloth account) in the `Co-Authored-By` trailer, and
+        // the EXT-83 commit-message rules (plain English, and passed by file — never inline, where the
+        // shell would expand the message before git runs). Same code-mode gate as the shell/cwd notes —
+        // the git-commit capability rides on `run_shell_command`, which is a code-mode tool.
+        // EXT-84: the effective `filesystem` is threaded in so the note names the writing tool only
+        // where that tool is registered. `this.config` is the command-merged value (getEffectiveConfig,
+        // above) — the SAME value handed to the tool resolver, so the note and the registered toolset
+        // cannot disagree. Mirrored on the deep backend.
+        const codeNotesPrompt = this.command === 'code'
+            ? appendCommitCoAuthorNote(appendOsShellNote(appendCwdNote(baseSystemPrompt, getCurrentWorkDir())), this.config.commit?.coAuthor, modelIdentity, this.config.filesystem)
+            : baseSystemPrompt;
+        // GS2-34: inject the resolved provider:model identity so the agent knows which model is serving
+        // it (to answer "what model are you?" and reason about its own capabilities/limits). Composed
+        // OUTSIDE the code-mode gate above — unlike the cwd/os-shell/commit notes, that question can
+        // arise in ANY mode (chat/ask/code/exec), so the identity must be visible everywhere. The
+        // `injectModelContext` opt-out is applied at the single read site above; when it is off — or
+        // when no model resolves — `modelIdentity` is undefined, nothing is appended, and the prompt is
+        // exactly as before. Backend-agnostic: the deep backend composes the same note (GS2-27). GS2-6's
+        // capability note is a deferred follow-up (bare provider:model identity only for now).
+        const modelContextPrompt = appendModelContextNote(codeNotesPrompt, modelIdentity);
+        // EXT-32: inject each connected MCP server's discovery `instructions` (captured during tool
+        // resolution) into the prompt — fenced + per-server-labelled as untrusted server-provided
+        // context. Mode-independent: MCP tools load in every mode, so their usage guidance applies in
+        // every mode (not just `code`). Empty/absent capture (or a resolver without the accessor) adds
+        // nothing. Composed through this shared path so it reaches the lean AND deep backends alike.
+        // When tools are disabled, resolveTools is skipped entirely (no MCP contact), so a REUSED
+        // resolver could still hold a prior run's capture — gate on toolsDisabled so no stale
+        // instructions leak into a tools-disabled session.
+        const mcpInstructions = toolsDisabled
+            ? []
+            : (this.resolvers?.getMcpServerInstructions?.() ?? []);
+        const systemPrompt = appendMcpServerInstructionsNote(modelContextPrompt, mcpInstructions);
+        // Create agent with configured middleware. Only pass systemPrompt when non-empty so we never
+        // hand createAgent an empty system message.
         this.agent = createAgent({
             model: this.config.llm,
             tools,
             middleware,
             checkpointer,
+            ...(systemPrompt ? { systemPrompt } : {}),
         });
         debugLog('React agent created successfully');
     }