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

package/dist/core/GthDeepAgent.js

@@ -1,13 +1,28 @@
-import { isShellToolEnabled } from '@gaunt-sloth/core/config.js';
+import { SHELL_TOOL_NAME, commandAnswersApprovals, resolveApprovals, resolveGatedToolNames, resolveInterruptToolNames, resolveShellApprovalGate, } from '@gaunt-sloth/core/config.js';
 import { GthAbstractAgent } from '@gaunt-sloth/core/core/GthAbstractAgent.js';
 import { StatusLevel } from '@gaunt-sloth/core/core/types.js';
 import { debugLog, debugLogObject } from '@gaunt-sloth/core/utils/debugUtils.js';
-import { buildSystemMessages, formatToolCalls, readChatPrompt, readCodePrompt, readExecPrompt, } from '@gaunt-sloth/core/utils/llmUtils.js';
-import { getCurrentWorkDir } from '@gaunt-sloth/core/utils/systemUtils.js';
+import { buildSystemMessages, formatToolCalls, readModePrompt, } from '@gaunt-sloth/core/utils/llmUtils.js';
+import { getCurrentWorkDir, getProjectDir, getUseColour, setProjectDir, setUseColour, } from '@gaunt-sloth/core/utils/systemUtils.js';
+import { getConsoleLevel, setConsoleLevel } from '@gaunt-sloth/core/utils/consoleUtils.js';
+import { buildProfileSubagents } from '#src/core/subagentProfiles.js';
+import { isToolAllowed } from '@gaunt-sloth/core/utils/toolMatching.js';
+// GS2-27: the OS/shell-dialect and real-cwd notes are backend-agnostic (both backends expose
+// run_shell_command and run on the real-fs cwd), so their canonical source moved to core so the
+// lean backend composes them too. Imported here for GthDeepAgent.init()'s code-mode composition and
+// re-exported so existing importers of this module keep working.
+import { appendOsShellNote, appendCwdNote, appendCommitCoAuthorNote, appendModelContextNote, appendMcpServerInstructionsNote, resolveModelIdentity, } from '@gaunt-sloth/core/utils/systemPromptNotes.js';
+export { appendOsShellNote, appendCwdNote, appendCommitCoAuthorNote, appendModelContextNote, resolveModelIdentity, OS_SHELL_GUIDANCE, } from '@gaunt-sloth/core/utils/systemPromptNotes.js';
 import { AIMessage, ToolMessage } from '@langchain/core/messages';
+import { GraphInterrupt } from '@langchain/langgraph';
 import { createMiddleware } from 'langchain';
 import { createDeepAgent, FilesystemBackend } from 'deepagents';
-import { buildPermissions, FILESYSTEM_TOOL_NAMES, } from '#src/core/deepAgentPermissions.js';
+import { buildPermissions, DEEP_AGENT_BUILT_IN_TOOL_NAMES, FILESYSTEM_TOOL_NAMES, guardFilesystemBackend, } from '#src/core/deepAgentPermissions.js';
+import { extractDebugRequestExtras } from '#src/core/debugCapture.js';
+// Re-export so existing importers of this module (extractDebugRequestExtras.spec) keep working
+// now that the implementation lives in @gaunt-sloth/core.
+export { extractDebugRequestExtras } from '#src/core/debugCapture.js';
+import { ShellCommandFailedError } from '#src/tools/GthDevToolkit.js';
 /**
  * EXT-16: decide whether the deepagents filesystem backend must run in virtualMode.
  *
@@ -33,7 +48,10 @@ function shouldUseVirtualFs() {
  *   {@link FilesystemBackend}. gsloth's `.aiignore` + `filesystem` config are mapped
  *   onto deepagents `permissions` (see {@link buildPermissions}). Any resolved tool
  *   that reuses a deepagents filesystem-tool name is therefore superseded and dropped
- *   (`createDeepAgent` would otherwise throw on the collision).
+ *   (`createDeepAgent` would otherwise throw on the collision). EXT-14: the
+ *   `FilesystemBackend` itself is wrapped with {@link guardFilesystemBackend} before it
+ *   reaches `createDeepAgent`, adding a realpath (symlink-resolved) containment check the
+ *   permission globs alone can't provide.
  * - todos / subagents / summarization come from deepagents' standard middleware.
  *
  * The transport-agnostic param assembly lives in {@link buildDeepAgentParams} so the ACP
@@ -41,13 +59,8 @@ function shouldUseVirtualFs() {
  * middleware hardening without re-running `createDeepAgent` locally.
  */
 export class GthDeepAgent extends GthAbstractAgent {
-    /**
-     * Opt-in debug sink for the TUI `/debug` panel. Set AFTER {@link init} via
-     * `runner.getAgent()`; read lazily inside the `wrapModelCall` middleware so that when it
-     * is `undefined` (the normal path) the middleware is a transparent pass-through. Never
-     * touched by the lean agent or the AG-UI server, so those contracts are unchanged.
-     */
-    debugCapture;
+    // `debugCapture` (the opt-in TUI `/debug` sink) now lives on the shared GthAbstractAgent base
+    // so the lean backend supports it too; the wrapModelCall capture middleware below reads it.
     async init(command, configIn, checkpointer) {
         const params = await this.buildDeepAgentParams(command, configIn);
         // Runner-path only: surface requested tool calls to the console. This is intentionally
@@ -79,11 +92,24 @@ export class GthDeepAgent extends GthAbstractAgent {
             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. Symmetric with the lean backend.
+                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, extractDebugRequestExtras(request));
+                    capture.onRequest?.(request.messages, extras);
                 }
                 catch {
                     /* a debug sink must never break the run */
@@ -98,31 +124,54 @@ export class GthDeepAgent extends GthAbstractAgent {
                 return response;
             },
         });
-        const middleware = [...params.middleware, toolCallStatusMiddleware, debugCaptureMiddleware];
-        this.statusUpdate(StatusLevel.INFO, `Loaded middleware: ${middleware.map((m) => m.name).join(', ')}`);
+        // EXT-16: whether the deepagents fs backend runs in virtualMode. deepagents' permission layer
+        // requires POSIX `/`-rooted paths, so a Windows real cwd (`D:\...`) can't be expressed as a
+        // permission glob and the EXT-13 real-path mode hangs there (`Error: path must be absolute`).
+        // When the real cwd isn't POSIX-rooted, fall back to virtualMode (cwd→`/`) with virtual
+        // permissions — the pre-EXT-13 known-good Windows behavior. Computed here because the EXT-22 S1
+        // middleware (below), the backend, and the systemPrompt gate (further down) all key off it.
+        const useVirtualFs = shouldUseVirtualFs();
+        // EXT-22 (S1): last-word path-namespace correction. Appends the shared guidance as a trailing
+        // system-message block ONLY in code + virtualMode (where the fs virtual `/` root and the
+        // shell's real-OS paths diverge); a transparent pass-through otherwise. Added LAST in the
+        // middleware array so, being the innermost wrapModelCall, its block lands AFTER deepagents'
+        // "All file paths must start with a /." line (see handoff/spike-systemmessage-ordering.md).
+        const pathNamespaceCorrectionMiddleware = createPathNamespaceCorrectionMiddleware(this.command === 'code' && useVirtualFs);
+        const middleware = [
+            ...params.middleware,
+            toolCallStatusMiddleware,
+            debugCaptureMiddleware,
+            pathNamespaceCorrectionMiddleware,
+        ];
+        this.headerStatus(`Loaded middleware: ${middleware.map((m) => m.name).join(', ')}`);
         // EXT-13: the backend always runs in REAL-path mode (virtualMode off) so the deepagents fs
         // tools and the EXT-9 run_shell_command tool share ONE path namespace — real absolute paths
-        // rooted at cwd. Containment is enforced entirely by the permission allow/deny globs built in
+        // rooted at cwd. Containment is enforced by the permission allow/deny globs built in
         // buildDeepAgentParams (default: allow cwd/**, deny /**), which match what virtualMode used to
-        // give for free (see deepAgentPermissions + the EXT-13 symlink/`..` parity tests).
+        // give for free (see deepAgentPermissions + the EXT-13 symlink/`..` parity tests), PLUS the
+        // EXT-14 realpath guard wrapped around the backend below (closes the intermediate-symlinked-
+        // directory gap those lexical globs alone can't catch).
         // `--allow-dir` (config.allowDirs) further widens those allow-rules to reach extra real dirs;
         // it removes a guardrail, so it is announced loudly by the exec command and surfaced here.
         const allowDirs = this.config?.allowDirs;
         const widenFs = Array.isArray(allowDirs) && allowDirs.length > 0;
-        // EXT-16: deepagents' permission layer requires POSIX `/`-rooted paths, so a Windows real
-        // cwd (`D:\...`) can't be expressed as a permission glob and the EXT-13 real-path mode hangs
-        // there (`Error: path must be absolute`). When the real cwd isn't POSIX-rooted, fall back to
-        // virtualMode (cwd→`/`) with virtual permissions — the pre-EXT-13 known-good Windows behavior.
-        const useVirtualFs = shouldUseVirtualFs();
         if (widenFs) {
             this.statusUpdate(StatusLevel.WARNING, `Filesystem sandbox widened beyond cwd (--allow-dir): ${allowDirs.join(', ')}` +
                 (useVirtualFs
                     ? ' — note: on this platform the sandbox runs in virtual mode, so widening beyond cwd is not applied.'
                     : ''));
         }
-        const backend = new FilesystemBackend({
+        // EXT-14: layer the realpath containment guard around the backend deepagents' fs middleware
+        // (main agent AND every subagent — they all share this one `backend` reference, see
+        // guardFilesystemBackend's doc comment) reads/writes through. Closes the intermediate-
+        // symlinked-directory escape that the lexical allow/deny globs alone cannot catch.
+        const backend = guardFilesystemBackend(new FilesystemBackend({
             rootDir: getCurrentWorkDir(),
             virtualMode: useVirtualFs,
+        }), {
+            cwd: getCurrentWorkDir(),
+            virtual: useVirtualFs,
+            allowDirs: widenFs ? allowDirs : undefined,
         });
         // EXT-13 (part b): on the local-runner code path the model used to be told nothing about
         // where it is, so it assumed `/` was cwd and fed `/`-rooted paths to the real-fs shell. Now
@@ -131,15 +180,97 @@ export class GthDeepAgent extends GthAbstractAgent {
         // shell access; the ACP transport keeps virtualMode and re-roots per session, so this
         // real-path note must NOT leak there (which is why it lives in init(), not the
         // transport-agnostic buildDeepAgentParams).
-        // In virtualMode (EXT-16, Windows) the model correctly assumes the virtual root `/` IS cwd
-        // (the pre-EXT-13 behavior), so the real-cwd note must NOT be injected — it would mislabel
-        // the namespace. Only the real-path code path needs it.
-        const systemPrompt = this.command === 'code' && !useVirtualFs
-            ? appendCwdNote(params.systemPrompt, getCurrentWorkDir())
+        // In virtualMode (EXT-16, Windows) the real-cwd note must NOT be injected — it would mislabel
+        // the namespace (the fs tools' `/` is the virtual root, not the real cwd). Instead, EXT-22 (S2)
+        // injects the virtualMode path-namespace note so the model is told EARLY that the fs virtual
+        // `/` root and run_shell_command's real-OS paths differ (the S1 middleware repeats it as the
+        // authoritative last word after deepagents' `/`-rooted line). Non-code paths get neither.
+        // EXT-26: after the cwd/virtual-cwd note, append the OS + shell-dialect note so the model is
+        // told its host OS and which shell run_shell_command spawns (cmd.exe on Windows, /bin/sh on
+        // POSIX). This is ORTHOGONAL to the path-namespace notes above (those say WHERE it is; this
+        // says WHAT shell it speaks) and applies in BOTH code-mode branches, independent of
+        // virtualMode — the shell dialect matters on every platform. Non-code paths get nothing new.
+        // 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. Mirrors the lean backend seam.
+        const modelIdentity = this.config?.injectModelContext !== false ? resolveModelIdentity(this.config) : undefined;
+        // GS2-35: append the commit co-authoring rule (config `commit.coAuthor`, defaulting to the Gaunt
+        // Sloth account) so agent-authored commits credit Gaunt Sloth 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). Mirrors the lean backend seam so both
+        // compose the same shared note (GS2-27 parity); same code-mode gate as the shell/cwd notes and
+        // independent of virtualMode.
+        // EXT-84: the effective `filesystem` is threaded in so the note names the writing tool only
+        // where that tool is registered. It is the command-merged value set by buildDeepAgentParams
+        // (getEffectiveConfig) — NOT the `filesystem: 'none'` override used purely to keep gsloth's
+        // filesystem toolkit out of tool resolution, which says nothing about the fs access deepagents
+        // itself grants from the same value. Mirrors the lean backend seam.
+        const codeNotesPrompt = this.command === 'code'
+            ? appendCommitCoAuthorNote(appendOsShellNote(useVirtualFs
+                ? appendVirtualCwdNote(params.systemPrompt)
+                : appendCwdNote(params.systemPrompt, getCurrentWorkDir())), this.config?.commit?.coAuthor, modelIdentity, this.config?.filesystem)
             : params.systemPrompt;
+        // GS2-34: inject the resolved provider:model identity (mirrors the lean GthLangChainAgent seam so
+        // both backends compose the same shared note — GS2-27 parity). Composed OUTSIDE the code-mode
+        // gate above: "which model are you?" can be asked in ANY mode (chat/ask/code/exec), so the
+        // identity is visible everywhere, unlike the code-only cwd/os-shell/commit notes. 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. Lives in init() like the cwd note (not buildDeepAgentParams), so the
+        // deepagents-acp transport is unaffected, consistent with every other init()-composed note.
+        // GS2-6 capability note deferred.
+        const modelContextPrompt = appendModelContextNote(codeNotesPrompt, modelIdentity);
+        // EXT-32: inject the connected MCP servers' discovery `instructions` (captured by the resolver
+        // during buildDeepAgentParams' resolveTools call, above) into the prompt — fenced + per-server-
+        // labelled as untrusted server-provided context. Mode-independent (MCP tools load in every
+        // mode). This mirrors the lean backend's GthLangChainAgent seam so both backends compose the
+        // same shared note (GS2-27 shared-path parity). Lives in init() like the cwd note, so the ACP
+        // buildDeepAgentParams entry is intentionally unaffected. Empty capture adds nothing.
+        // When tools are disabled, buildDeepAgentParams skips resolveTools (no MCP contact), so a REUSED
+        // resolver could still hold a prior run's capture — gate on toolsDisabled (recomputed from the
+        // effective config buildDeepAgentParams set on `this.config`) so no stale instructions leak.
+        const deepToolsDisabled = Array.isArray(this.config?.allowedTools) && this.config.allowedTools.length === 0;
+        const mcpInstructions = deepToolsDisabled
+            ? []
+            : (this.resolvers?.getMcpServerInstructions?.() ?? []);
+        const systemPrompt = appendMcpServerInstructionsNote(modelContextPrompt, mcpInstructions);
+        // GS2-33 — resolve profile-backed subagents (config `subagents`). Runner-only, like the
+        // cwd/model-context notes above: it lives in init() (NOT the transport-agnostic
+        // buildDeepAgentParams), so the deepagents-acp path is unaffected and the child-config
+        // resolution's process-global side effects stay on the local-runner path. Each declared
+        // subagent's CHILD resolves its named profile through the GS2-1 cascade, so the deepagents `task`
+        // tool can dispatch it under that profile's own model + tools + prompt (e.g. a cheap flash-lite
+        // profile for recall/search while the parent runs on a strong model). Because resolving a child
+        // goes through initConfig — which mutates projectDir/consoleLevel/useColour exactly as the parent
+        // run's own initConfig did — snapshot and restore those globals so a child profile's console
+        // level / colour can never leak into the parent run.
+        let subagents;
+        const subagentSpecs = this.config?.subagents;
+        if (Array.isArray(subagentSpecs) && subagentSpecs.length > 0) {
+            const savedProjectDir = getProjectDir();
+            const savedConsoleLevel = getConsoleLevel();
+            const savedUseColour = getUseColour();
+            try {
+                subagents = await buildProfileSubagents(subagentSpecs, {
+                    command: this.command,
+                    resolveTools: this.resolvers?.resolveTools?.bind(this.resolvers),
+                });
+                this.headerStatus(`Loaded profile subagents: ${subagents.map((s) => s.name).join(', ')}`);
+            }
+            finally {
+                setProjectDir(savedProjectDir);
+                setConsoleLevel(savedConsoleLevel);
+                setUseColour(savedUseColour);
+            }
+        }
         this.agent = createDeepAgent({
             model: params.model,
             tools: params.tools,
+            // GS2-33 — profile-backed subagents (undefined when none configured → deepagents' default
+            // general-purpose subagent only, unchanged behaviour).
+            subagents,
             // gsloth's composed prompt, combined ADDITIVELY by deepagents with its base + fs prompts
             // into a single system message (avoids the two-system-message Anthropic rejection).
             systemPrompt,
@@ -149,7 +280,7 @@ export class GthDeepAgent extends GthAbstractAgent {
             permissions: params.permissions,
             // Per-tool human-in-the-loop gating (e.g. run_shell_command confirmation). When set,
             // deepagents installs humanInTheLoopMiddleware so a matching tool call suspends the graph
-            // for approval; `undefined` (the default, and under yolo) leaves every tool ungated.
+            // for approval; `undefined` (the default, and under bypass) leaves every tool ungated.
             interruptOn: params.interruptOn,
             checkpointer,
         });
@@ -173,16 +304,16 @@ export class GthDeepAgent 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 with filesystem access disabled. deepagents OWNS the filesystem
         // (its fs middleware + the `permissions` built below); gsloth's filesystem toolkit
@@ -200,11 +331,12 @@ export class GthDeepAgent extends GthAbstractAgent {
             ? []
             : this.extractAndFlattenTools(this.config.tools || []);
         debugLog(`User config tools loaded: ${flattenedConfigTools.length}`);
-        // Combine all tools, then apply the allowedTools name allow-list when configured.
+        // Combine all tools, then apply the allowedTools name allow-list when configured. Entries
+        // match by exact name, or glob-style when they contain `*` (e.g. `mcp__unimarket__*`) — see
+        // isToolAllowed. Nameless ServerTools are retained (they can't be named in the allow-list).
         let tools = [...resolvedTools, ...flattenedConfigTools];
         if (Array.isArray(allowedTools)) {
-            const allowed = new Set(allowedTools);
-            tools = tools.filter((tool) => !tool.name || allowed.has(tool.name));
+            tools = tools.filter((tool) => !tool.name || isToolAllowed(tool.name, allowedTools));
         }
         // Safety net: a custom/dev/MCP tool may still reuse a deepagents filesystem-tool
         // name (createDeepAgent throws on such a collision). Drop the colliding tool — the
@@ -222,7 +354,7 @@ export class GthDeepAgent extends GthAbstractAgent {
                 .map((tool) => tool.name)
                 .filter((name) => name)
                 .join(', ');
-            this.statusUpdate(StatusLevel.INFO, `Loaded tools: ${toolNames}`);
+            this.headerStatus(`Loaded tools: ${toolNames}`);
             debugLog(`Total tools available: ${passThroughTools.length}`);
             debugLogObject('All Tools', toolNames.split(', '));
         }
@@ -244,11 +376,20 @@ export class GthDeepAgent extends GthAbstractAgent {
             }
             return true;
         });
-        // Soften deepagents' fail-hard filesystem permission denials. By default a denied
-        // read/write THROWS, which aborts the whole run; wrap tool calls so a denial becomes
-        // a recoverable ToolMessage instead, letting the model continue and report it. This
-        // preserves gsloth's recoverable-denial UX (the old GthFileSystemToolkit returned a
-        // message rather than throwing).
+        // Soften deepagents' fail-hard filesystem tool throws. By default the permission layer
+        // THROWS on both a denied read/write AND on a malformed path the model supplied — a relative
+        // path, a `..`/`~` segment, or an empty string (deepagents' validatePath, run BEFORE the
+        // permission check in enforcePermission). Any of these aborts the WHOLE run. On the AG-UI
+        // transport that throw propagates out of streamWithEvents into the run handler's catch, which
+        // emits RUN_ERROR and ends the response WITHOUT a terminal RUN_FINISHED — and since AG-UI's
+        // protocol makes RUN_ERROR terminal ("no further events can be sent"), a consumer waiting for
+        // RUN_FINISHED hangs (EXT-24). Wrap tool calls so each of these becomes a recoverable error
+        // ToolMessage instead, letting the model observe the mistake, retry with a good path, and
+        // finish the run normally (reaching RUN_FINISHED). This preserves gsloth's recoverable-denial
+        // UX (the old GthFileSystemToolkit returned a message rather than throwing). Only these known
+        // fs path/permission messages are caught; every other throw (GraphInterrupt from a client-tool
+        // interrupt stub, AbortError on client disconnect, unexpected errors) is rethrown untouched so
+        // control-flow and genuine failures still surface.
         const fsDenialSoftening = createMiddleware({
             name: 'GthDeepFsDenialSoftening',
             wrapToolCall: async (request, handler) => {
@@ -256,9 +397,27 @@ export class GthDeepAgent extends GthAbstractAgent {
                     return await handler(request);
                 }
                 catch (e) {
+                    // EXT-25: rethrow control-flow throws BY TYPE, BEFORE the message regex below. A
+                    // GraphInterrupt (a client-tool interrupt() suspending the graph for HITL tool
+                    // approval) and an AbortError (caller cancellation) must ALWAYS propagate so the graph
+                    // suspends / cancels — never be converted into a benign ToolMessage. Mirrors the guard
+                    // in GthAbstractAgent (error.name checks + GraphInterrupt instanceof). Today these
+                    // survive only because their messages happen not to match the regex; guarding by type
+                    // stops a future regex broadening from silently swallowing the HITL suspend.
+                    if (e instanceof GraphInterrupt ||
+                        e?.name === 'GraphInterrupt' ||
+                        e?.name === 'AbortError') {
+                        throw e;
+                    }
                     const message = e instanceof Error ? e.message : String(e);
-                    if (/permission denied for (read|write)/i.test(message)) {
-                        debugLog(`Softened fs permission denial into a ToolMessage: ${message}`);
+                    // A permission denial, or a path that is relative / contains ".." or "~" / is empty —
+                    // all recoverable model-input errors. The live source of these throws is gsloth's own
+                    // realpath guard (guardFilesystemBackend); deepagents' enforcement used to throw the
+                    // same messages too, but since 1.11.1 it returns the equivalent error ToolMessage
+                    // itself and so never reaches this catch. Keep matching both: the observation the model
+                    // sees is identical either way, and the guard still depends on this softening.
+                    if (/permission denied for (read|write)|path must (be absolute|not contain|be a non-empty string)/i.test(message)) {
+                        debugLog(`Softened fs tool throw into a ToolMessage: ${message}`);
                         return new ToolMessage({
                             content: message,
                             // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -270,10 +429,93 @@ export class GthDeepAgent extends GthAbstractAgent {
                 }
             },
         });
-        // fsDenialSoftening first so it is the outermost wrapToolCall — it must see the throw
-        // from deepagents' permission-enforcing fs tools. The console-bound tool-call-status
-        // middleware is NOT added here (see GthDeepAgentParams.middleware); the runner appends it.
-        const middleware = [fsDenialSoftening, ...configuredMiddleware];
+        // EXT-20: sibling of fsDenialSoftening for the run_* (dev/shell) tools. GthDevToolkit's
+        // executeCommand now THROWS a ShellCommandFailedError on a non-zero exit or a timeout-kill
+        // (instead of resolving with the failure text), so the tool result no longer misreports
+        // status:'success' (✓). Catch it here and return an error ToolMessage that PRESERVES the full
+        // stdout/stderr body — the model's observation is unchanged except that status flips to
+        // 'error', which drives the ✗ (isError) glyph (GthAbstractAgent maps status==='error' →
+        // isError). Returning a ToolMessage (rather than rethrowing) also means the approved-then-failed
+        // command does NOT trigger a retry loop — it is a normal, observed tool result.
+        const shellExitSoftening = createMiddleware({
+            name: 'GthDeepShellExitSoftening',
+            wrapToolCall: async (request, handler) => {
+                try {
+                    return await handler(request);
+                }
+                catch (e) {
+                    if (e instanceof ShellCommandFailedError) {
+                        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;
+                }
+            },
+        });
+        // fsDenialSoftening first so it is the outermost wrapToolCall — it must see the throw from
+        // deepagents' permission-enforcing fs tools. shellExitSoftening sits right after it (still
+        // outboard of any user-configured middleware, so it always sees the raw ShellCommandFailedError
+        // throw before a user wrapToolCall could transform it). Order between the two softeners is not
+        // load-bearing: they catch DISJOINT conditions (a permission-denied regex vs an
+        // `instanceof ShellCommandFailedError`) and each rethrows what it doesn't recognize, so neither
+        // can swallow the other. The console-bound tool-call-status middleware is NOT added here (see
+        // GthDeepAgentParams.middleware); the runner appends it. mcpToolErrorSoftening sits alongside the
+        // other two softeners (still outboard of user middleware); it catches a DISJOINT condition
+        // (name==='ToolException') and rethrows everything else, so ordering among the three is not
+        // load-bearing.
+        const middleware = [
+            fsDenialSoftening,
+            shellExitSoftening,
+            mcpToolErrorSoftening,
+            ...configuredMiddleware,
+        ];
         // Map gsloth's .aiignore + filesystem mode onto deepagents permission rules. When
         // `--allow-dir` widens the sandbox, the backend runs without virtualMode, so paths are REAL
         // absolute paths: constrain read+write to cwd + the allowed dirs (everything else denied),
@@ -294,33 +536,98 @@ export class GthDeepAgent extends GthAbstractAgent {
         // `.gsloth.*.md` are honored. This is passed to createDeepAgent as `systemPrompt` — combined
         // additively with deepagents' base + fs prompts into ONE system message — rather than injected
         // as a separate SystemMessage per turn (which produced a non-first system message that
-        // Anthropic rejects). 'code' uses the code-mode prompt; 'exec' uses the prompt-as-script
-        // exec-mode prompt; chat/api/others use the chat prompt.
-        const modePrompt = this.command === 'code'
-            ? readCodePrompt(this.config)
-            : this.command === 'exec'
-                ? readExecPrompt(this.config)
-                : readChatPrompt(this.config);
+        // Anthropic rejects). GS2-79: which mode prompt a command gets is decided ONCE, in core's
+        // `readModePrompt` — 'code' the code-mode prompt, 'exec' the prompt-as-script exec-mode prompt,
+        // 'review'/'pr' the REVIEW INSTRUCTIONS, chat/api/others the chat prompt — so this backend and
+        // the lean 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 systemPrompt = typeof systemMessages[0]?.content === 'string' ? systemMessages[0].content : undefined;
-        // Gate the opt-in run_shell_command tool behind a per-command approval interrupt. The tool
-        // is only emitted (by GthDevToolkit, via builtInToolsConfig) when its devTools.shell flag is
-        // set; mirror the same per-command devTools resolution here so the interrupt is wired only
-        // when the tool actually exists. yolo (shellYolo) opts OUT of the confirmation: leave
-        // interruptOn undefined so the tool runs without suspending.
-        const devTools = this.getEffectiveDevToolsConfig();
-        // EXT-12 — pass the active command so the absent-config default (shell ON in `code`)
-        // is applied consistently with where the tool is actually emitted (GthDevToolkit).
-        const shellEnabled = isShellToolEnabled(devTools, this.command);
-        const interruptOn = shellEnabled && devTools?.shellYolo !== true
-            ? { run_shell_command: { allowedDecisions: ['approve', 'reject'] } }
+        // Gate the opt-in run_shell_command tool behind a per-command approval interrupt. The gate
+        // condition and its user-facing notices are the SHARED core policy (`resolveShellApprovalGate`,
+        // EXT-12 semantics documented there), so this backend and the lean one can never drift; here it
+        // is installed through deepagents' `interruptOn` rather than as middleware. The resolver reads
+        // the same `builtInTools` registry GthDevToolkit emits the tool from (CFG-18), so the wiring
+        // stays in lockstep with where the tool actually exists.
+        const { gateShell, notice: shellGateNotice } = resolveShellApprovalGate(this.config ?? undefined, this.command);
+        //
+        // EXT-80: at `manual` and `write` every bound tool the rung's access class does not
+        // auto-grant must reach the human. Both sets below come from core's shared policy — the same one
+        // the lean backend and `GthAgentRunner` call — so the three cannot disagree about what is gated.
+        //
+        // **The interrupt is wired rung-INDEPENDENTLY, over every tool any rung could gate.** It is
+        // built once, here, while `/approvals <rung>` moves the rung for the rest of the session without
+        // rebuilding the 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, so wiring wider does not gate wider.
+        //
+        // **`boundToolNames` must include deepagents' OWN tools.** deepagents registers its filesystem
+        // tools, `execute`, `task` and `write_todos` itself (this backend resolves with
+        // `filesystem: 'none'`), so they never appear in `passThroughTools`; deriving the set from that
+        // array alone would leave `write_file`, `edit_file`, `execute`, `task` and `write_todos` ungated
+        // at `manual` on this backend — precisely the defect this change exists to remove. Gating
+        // them by name works because deepagents installs the very same langchain
+        // `humanInTheLoopMiddleware`, which matches the model's tool CALLS by name in `afterModel` and so
+        // does not care which party registered the tool.
+        //
+        // Note this union keeps `execute`, unlike `additionalToolNames` below: that list answers "what
+        // may the rater offer as a granted alternative", a different question from "what must the gate
+        // stop". `execute` is deepagents' shell and has no access class, so it must be gated at both
+        // deterministic rungs and offered as an alternative at none.
+        const rung = resolveApprovals(this.config ?? undefined, this.command).rung;
+        const boundToolNames = [
+            ...passThroughTools
+                .map((tool) => tool?.name)
+                .filter((name) => typeof name === 'string' && name.length > 0),
+            ...DEEP_AGENT_BUILT_IN_TOOL_NAMES,
+        ];
+        // **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. This backend is ONE of the two the AG-UI server can
+        // run on — `apiAgUiModule.createConfiguredAgent` builds a `GthDeepAgent` only when
+        // `agent.backend === 'deep'` (and warns that it is experimental); every other configuration,
+        // the default included, gets the lean `GthLangChainAgent`, which carries the same wiring for
+        // the same reason. It matters on both: at `manual` and `write` the live set is non-empty, so a
+        // write, an MCP call, `task` or deepagents' own `write_todos` bookkeeping would simply vanish —
+        // or be announced to the model as approvable when nothing will ever approve it.
+        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.
+        const gatedTools = answersApprovals
+            ? resolveGatedToolNames({ rung, gateShell, boundToolNames })
+            : noDrainTools;
+        // Rung-independent ONLY where something answers the interrupt.
+        const interruptTools = answersApprovals
+            ? resolveInterruptToolNames({ gateShell, boundToolNames })
+            : noDrainTools;
+        // Keyed off the interrupt SET, not `gateShell`: at a deterministic rung there is a gate to
+        // install even when the shell tool is disabled, and deepagents installs no HITL middleware at
+        // all when `interruptOn` is undefined.
+        const interruptOn = interruptTools.length > 0
+            ? Object.fromEntries(interruptTools.map((name) => [name, { allowedDecisions: ['approve', 'reject'] }]))
             : undefined;
-        if (interruptOn) {
-            this.statusUpdate(StatusLevel.INFO, 'Shell tool (run_shell_command) enabled with per-command approval (interruptOn).');
-        }
-        else if (shellEnabled) {
-            this.statusUpdate(StatusLevel.WARNING, 'Shell tool (run_shell_command) enabled in YOLO mode: commands run WITHOUT confirmation.');
+        if (shellGateNotice) {
+            this.statusUpdate(shellGateNotice.level, shellGateNotice.message);
         }
+        // EXT-58 (spec §4.5) — the same tool-registration hook the lean backend calls, on the same LIVE
+        // gated set, so neither backend's descriptions can disagree with its own rung. That set is
+        // narrower than the `interruptOn` set above, which covers every rung so the rung can still move
+        // mid-session; describing from the wider one would promise approvals this rung does not ask
+        // for. deepagents registers its OWN filesystem tools (this backend
+        // resolves with `filesystem: 'none'`), so they never appear in `passThroughTools` and their
+        // descriptions are deepagents' rather than ours, which is why they cannot be suffixed here even
+        // though the gated set above does gate them. They are declared as additional registered names so
+        // the rater's granted-alternative list (§4.4) reflects the tools a deep session actually has.
+        // `execute` is deliberately excluded from THAT list: it is deepagents' shell, not a filesystem
+        // tool, and must never be offered as a granted alternative to a shell command.
+        this.registerApprovalsAwareTools(passThroughTools, {
+            rung,
+            gatedTools,
+            additionalToolNames: FILESYSTEM_TOOL_NAMES.filter((name) => name !== 'execute'),
+        });
         return {
             model: this.config.llm,
             tools: passThroughTools,
@@ -330,143 +637,76 @@ export class GthDeepAgent extends GthAbstractAgent {
             interruptOn,
         };
     }
-    /**
-     * Resolve the {@link GthDevToolsConfig} that applies to the active command, mirroring the
-     * per-command selection in `builtInToolsConfig.getDefaultTools` (which is what actually emits
-     * the dev tools): `exec` → `commands.exec.devTools`, `ask --write` → `commands.ask.devTools`,
-     * otherwise (`code`) → `commands.code.devTools`. Returns `undefined` for any other command,
-     * matching the toolkit being inert there. Kept private and side-effect-free so the interrupt
-     * wiring above and the tool emission stay in lockstep.
-     */
-    getEffectiveDevToolsConfig() {
-        const config = this.config;
-        if (!config)
-            return undefined;
-        const command = this.command;
-        const askWrite = command === 'ask' && config.askWriteMode === true;
-        if (command === 'exec')
-            return config.commands?.exec?.devTools;
-        if (askWrite)
-            return config.commands?.ask?.devTools;
-        if (command === 'code')
-            return config.commands?.code?.devTools;
-        return undefined;
-    }
 }
 /**
- * EXT-13 (part b): append a real-cwd / path-model note to the composed code-mode system prompt.
+ * EXT-22: shared virtualMode path-namespace guidance — ONE source of truth used by BOTH the S2
+ * early-framing note ({@link appendVirtualCwdNote}, injected into gsloth's composed systemPrompt =
+ * block 0) and the S1 last-word correction middleware
+ * ({@link createPathNamespaceCorrectionMiddleware}, appended after deepagents' `/`-rooted line).
+ *
+ * In a virtualMode `code` session (EXT-16, e.g. Windows) the deepagents filesystem tools use a
+ * VIRTUAL `/` root (= the working dir) while `run_shell_command` uses REAL native OS paths; the
+ * model conflates the two forms. This text draws the distinction and steers toward cwd-relative
+ * paths (the one form both tool families read alike).
  *
- * The default code-mode backend runs in REAL-path mode (no virtualMode), so the deepagents fs
- * tools and `run_shell_command` share one real-absolute-path namespace rooted at `cwd`. Neither
- * deepagents' base prompt nor `.gsloth.code.md` states the actual cwd, so without this the model
- * assumes `/` is cwd and hands `/`-rooted paths to the real-fs shell. The cwd is injected
- * dynamically (never baked into the .md). Returns the note alone when there is no base prompt.
+ * It deliberately does NOT equate the virtual root with a specific real path (no "`/` = D:\\work"):
+ * virtualMode withholds the real cwd on purpose (see the systemPrompt gate in {@link
+ * GthDeepAgent.init}), so the guidance is about the DISTINCTION between the two namespaces and the
+ * safety of relative paths, not a mapping between them.
  */
-export function appendCwdNote(systemPrompt, cwd) {
-    const cwdNote = `Working directory: ${cwd}\n` +
-        'Paths are real absolute filesystem paths (there is no virtual root). The working directory ' +
-        'above is where this session runs; relative paths resolve against it, and both the filesystem ' +
-        'tools (ls/glob/read_file/write_file/edit_file/grep) and run_shell_command operate on these ' +
-        'same real paths. Check the current directory before filesystem operations and prefer absolute ' +
-        'paths (or paths relative to the working directory); do not assume the current directory is "/".';
-    return systemPrompt ? `${systemPrompt}\n\n${cwdNote}` : cwdNote;
-}
+export const PATH_NAMESPACE_GUIDANCE = 'The filesystem tools (ls, read_file, write_file, edit_file, glob, grep) use a VIRTUAL root in ' +
+    'this session: a leading `/` means your working directory, and their paths are written ' +
+    '`/`-rooted relative to it (this is what "all file paths must start with a /" refers to). That ' +
+    '`/` is NOT the real operating-system filesystem root. run_shell_command is different: it runs ' +
+    'in the real operating system and uses real native paths (on Windows, e.g. ' +
+    '`C:\\Users\\...\\project`, with backslashes), never the virtual `/` root. A `/`-rooted path ' +
+    'from the filesystem tools is NOT a valid shell path and must never be passed to ' +
+    'run_shell_command. The one form that means the same thing to both tool families is a path ' +
+    'RELATIVE to the working directory (e.g. `src/index.ts`); prefer relative paths for both. When ' +
+    'you must be absolute, use `/`-rooted form ONLY for the filesystem tools and real native form ' +
+    'ONLY for run_shell_command.';
 /**
- * Scalar model-param fields worth surfacing in the `/debug` panel. Deliberately an
- * allowlist (NOT a whole-object dump) so no credential field (`apiKey`, `accessToken`, …)
- * can ever leak into the rendered debug view.
+ * EXT-22 (S2): virtualMode variant of {@link appendCwdNote}. On the `code` path when the fs
+ * backend runs in virtualMode (EXT-16), inject the shared path-namespace guidance EARLY in
+ * gsloth's composed systemPrompt (block 0) so the model is framed before deepagents' own prompt.
  *
- * `streaming` is intentionally NOT here: it is the model instance's static flag, which is
- * usually `false` even when the turn streams — the GthAgentRunner decides streaming by calling
- * `.stream()` vs `.invoke()`, not by this property — so surfacing it just misleads.
+ * This is early framing only: deepagents' hardcoded `/`-rooted line lands in a LATER block and can
+ * partially override block 0, so the authoritative last word is delivered by the S1 middleware
+ * ({@link createPathNamespaceCorrectionMiddleware}); see handoff/spike-systemmessage-ordering.md.
+ * Returns the note alone when there is no base prompt.
  */
-const DEBUG_MODEL_PARAM_KEYS = [
-    'model',
-    'modelName',
-    'modelId',
-    'deploymentName',
-    'temperature',
-    'topP',
-    'topK',
-    'maxTokens',
-    'maxOutputTokens',
-    'maxReasoningTokens',
-    'reasoningEffort',
-    'thinkingBudget',
-    'stop',
-    'provider',
-];
-/** Pull the key-free scalar model params from the (provider-specific) model instance. */
-function extractModelParams(model) {
-    if (!model || typeof model !== 'object')
-        return undefined;
-    const src = model;
-    const out = {};
-    for (const key of DEBUG_MODEL_PARAM_KEYS) {
-        const value = src[key];
-        if (value === undefined || value === null)
-            continue;
-        // Only scalars / scalar arrays — never nested objects that could carry credentials.
-        if (typeof value === 'object' && !Array.isArray(value))
-            continue;
-        out[key] = value;
-    }
-    // `model` / `modelName` / `modelId` are langchain aliases for the same value; collapse the
-    // duplicates so the panel shows the model id once instead of two identical lines.
-    if (typeof out.model !== 'string' && typeof out.modelName === 'string') {
-        out.model = out.modelName;
-    }
-    if (out.modelName === out.model)
-        delete out.modelName;
-    if (out.modelId === out.model)
-        delete out.modelId;
-    return Object.keys(out).length > 0 ? out : undefined;
-}
-/** Best-effort tool definition (name + description + schema) for the debug view. */
-function extractToolDefs(tools) {
-    if (!Array.isArray(tools) || tools.length === 0)
-        return undefined;
-    const defs = [];
-    for (const tool of tools) {
-        if (!tool || typeof tool !== 'object')
-            continue;
-        const t = tool;
-        const name = typeof t.name === 'string' ? t.name : undefined;
-        if (!name)
-            continue;
-        const description = typeof t.description === 'string' ? t.description : undefined;
-        // LangChain StructuredTools expose a Zod/JSON `schema`; some carry it on `lc_kwargs`.
-        const schema = t.schema ?? undefined;
-        defs.push({ name, description, schema });
-    }
-    return defs.length > 0 ? defs : undefined;
+export function appendVirtualCwdNote(systemPrompt) {
+    const note = `Filesystem vs shell path namespaces: ${PATH_NAMESPACE_GUIDANCE}`;
+    return systemPrompt ? `${systemPrompt}\n\n${note}` : note;
 }
 /**
- * Assemble the non-message request parts ({@link DebugRequestExtras}) for the `/debug`
- * panel from a `wrapModelCall` request, defensively and key-free. Never throws (the caller
- * already guards, but a debug sink must never break a run) and never dumps the raw model.
+ * EXT-22 (S1): the load-bearing path-namespace correction. A gsloth `wrapModelCall` middleware
+ * runs INNERMOST (inside deepagents' filesystem middleware), so appending a trailing block to
+ * `request.systemMessage` lands AFTER deepagents' hardcoded "All file paths must start with a /."
+ * line — giving gsloth the last word on path semantics (empirically verified; see
+ * handoff/spike-systemmessage-ordering.md). It APPENDS via `request.systemMessage.concat(...)`
+ * (mirroring how deepagents appends its own fs prompt), never string-splices, and returns a NEW
+ * request so it never mutates persisted state (no compounding across turns).
+ *
+ * `appendCorrection` gates it to `code` + virtualMode: only there do the fs virtual `/` root and
+ * the shell's real-OS paths diverge. On POSIX real-path mode deepagents' "start with /" is
+ * literally true, so the middleware is a transparent pass-through (like the debug-capture
+ * middleware when no sink is attached).
  */
-export function extractDebugRequestExtras(request) {
-    if (!request || typeof request !== 'object')
-        return undefined;
-    const req = request;
-    const systemMessage = req.systemMessage;
-    const systemPrompt = typeof req.systemPrompt === 'string' && req.systemPrompt
-        ? req.systemPrompt
-        : typeof systemMessage?.content === 'string'
-            ? systemMessage.content
-            : undefined;
-    const extras = {
-        systemPrompt,
-        tools: extractToolDefs(req.tools),
-        modelParams: extractModelParams(req.model),
-        toolChoice: req.toolChoice,
-    };
-    // Return undefined when nothing useful was captured so the renderer can show a clear empty state.
-    const hasAny = extras.systemPrompt !== undefined ||
-        extras.tools !== undefined ||
-        extras.modelParams !== undefined ||
-        extras.toolChoice !== undefined;
-    return hasAny ? extras : undefined;
+export function createPathNamespaceCorrectionMiddleware(appendCorrection) {
+    return createMiddleware({
+        name: 'GthDeepPathNamespaceCorrection',
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        wrapModelCall: async (request, handler) => {
+            if (!appendCorrection || !request?.systemMessage)
+                return handler(request);
+            const correction = 'IMPORTANT — path namespaces (authoritative; this overrides any earlier instruction that ' +
+                `implies every path is a simple \`/\`-rooted filesystem path): ${PATH_NAMESPACE_GUIDANCE}`;
+            return handler({ ...request, systemMessage: request.systemMessage.concat(correction) });
+        },
+    });
 }
+// The `/debug` request-extras extraction (extractDebugRequestExtras + its model-param / tool-def
+// allowlist helpers) now lives in @gaunt-sloth/core (`core/debugCapture.ts`) so the lean backend
+// shares it. Imported at the top of this module and re-exported for back-compat.
 //# sourceMappingURL=GthDeepAgent.js.map