@gaunt-sloth/agent 2.0.0-alpha.2 → 2.0.0-alpha.21

package/dist/core/GthDeepAgent.js

@@ -1,12 +1,40 @@
+import { isShellToolEnabled, getEffectiveDevToolsConfig } 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 { 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, 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.
+ *
+ * deepagents' permission layer (`validatePath`) requires POSIX `/`-rooted glob paths, and its
+ * fs tools hand the SAME model-supplied path string to both the permission check and the native
+ * `path.resolve`/`fs` backend. On Windows a real cwd is `D:\...`, which can satisfy neither side
+ * as one string, so the EXT-13 real-path sandbox throws `Error: path must be absolute` on every
+ * turn and the agent hangs. The precise trigger is "the real cwd is not POSIX-rooted", so we key
+ * off that directly (not just `win32`): when true, run virtualMode (cwd→`/`) with virtual
+ * permissions — the pre-EXT-13 known-good behavior. POSIX keeps the EXT-13 real-path namespace.
+ */
+function shouldUseVirtualFs() {
+    return !getCurrentWorkDir().startsWith('/');
+}
 /**
  * Deep agent: builds a `createDeepAgent` graph (deepagents). All run/stream/event
  * plumbing lives in {@link GthAbstractAgent}; this class only knows how to construct
@@ -18,7 +46,10 @@ import { buildPermissions, FILESYSTEM_TOOL_NAMES, } from '#src/core/deepAgentPer
  *   {@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
@@ -26,13 +57,8 @@ import { buildPermissions, FILESYSTEM_TOOL_NAMES, } from '#src/core/deepAgentPer
  * 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
@@ -83,32 +109,120 @@ 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(', ')}`);
-        // Default: a virtual-root sandbox anchored at cwd (absolute paths / `..` cannot escape).
-        // `--allow-dir` (config.allowDirs) opts into widening: drop virtualMode so the listed real
-        // directories are reachable, and rely on the permission allow-rules (built in
-        // buildDeepAgentParams) to constrain access to cwd + those dirs. This removes a guardrail,
-        // so it is announced loudly by the exec command and surfaced here in the status log.
+        // 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 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), 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;
         if (widenFs) {
-            this.statusUpdate(StatusLevel.WARNING, `Filesystem sandbox widened beyond cwd (--allow-dir): ${allowDirs.join(', ')}`);
+            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: !widenFs,
+            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
+        // the backend uses real absolute paths (above), so inject the dynamic real cwd + path model
+        // into the prompt the model actually receives. Code mode only — the surface with full fs +
+        // 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 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-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
+        // never the underlying model name. 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.
+        const codeNotesPrompt = this.command === 'code'
+            ? appendCommitCoAuthorNote(appendOsShellNote(useVirtualFs
+                ? appendVirtualCwdNote(params.systemPrompt)
+                : appendCwdNote(params.systemPrompt, getCurrentWorkDir())), this.config?.commit?.coAuthor)
+            : 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. Config opt-out
+        // via `injectModelContext: false` (default ON, defaulted here at the read site); when off — or
+        // when no model resolves — 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 = this.config?.injectModelContext !== false
+            ? appendModelContextNote(codeNotesPrompt, resolveModelIdentity(this.config))
+            : codeNotesPrompt;
+        // 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);
         this.agent = createDeepAgent({
             model: params.model,
             tools: params.tools,
             // 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: params.systemPrompt,
+            systemPrompt,
             // eslint-disable-next-line @typescript-eslint/no-explicit-any
             middleware: middleware,
             backend,
             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.
+            interruptOn: params.interruptOn,
             checkpointer,
         });
         debugLog('Deep agent created successfully');
@@ -131,16 +245,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
@@ -158,11 +272,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
@@ -180,7 +295,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(', '));
         }
@@ -202,11 +317,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) => {
@@ -214,9 +338,24 @@ 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}`);
+                    // deepagents fs enforcement throws (middleware/fs.ts enforcePermission +
+                    // permissions/enforce.ts validatePath): a permission denial, or a path that is
+                    // relative / contains ".." or "~" / is empty. All are recoverable model-input errors.
+                    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
@@ -228,10 +367,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),
@@ -242,7 +464,10 @@ export class GthDeepAgent extends GthAbstractAgent {
             allowDirs: Array.isArray(this.config.allowDirs) && this.config.allowDirs.length > 0
                 ? this.config.allowDirs
                 : undefined,
-        });
+        }, 
+        // EXT-16: build virtual (`/`-rooted) permission rules when the backend will run in
+        // virtualMode (Windows), matching the FilesystemBackend created in init().
+        shouldUseVirtualFs());
         debugLogObject('Filesystem permissions', permissions);
         // Compose gsloth's system prompt (backstory + guidelines + per-command mode prompt +
         // system prompt) so identity profiles (Gaunt Sloth, sorcerer, fisher-alt, …) and
@@ -258,111 +483,116 @@ export class GthDeepAgent extends GthAbstractAgent {
                 : readChatPrompt(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 `run_shell_command`
+        // builtInTools entry enables it; use the shared core resolver so the interrupt wiring stays in
+        // lockstep with where the tool is actually emitted (CFG-18: resolved from `builtInTools`).
+        const devTools = getEffectiveDevToolsConfig(this.config ?? undefined, this.command);
+        // 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);
+        // EXT-12 — auto-approve (shellYolo) interplay with gating:
+        //   • In interactive `code` mode we KEEP the tool gated even when shellYolo pre-enables
+        //     auto-approval, so the runner's session flag governs it and `/auto-approve off` can
+        //     restore the per-command prompt mid-session. The runner seeds that flag ON from
+        //     shellYolo (see GthAgentRunner.init), so the user still sees no prompt by default; the
+        //     interactive event/stream path drains the interrupt and auto-approves silently.
+        //   • In non-interactive modes (exec / ask --write) a single-shot run does NOT drain
+        //     interrupts, so shellYolo keeps the tool UNGATED (runs inline without suspending),
+        //     preserving prior behaviour. There is no slash-command surface there to toggle anyway.
+        const isInteractive = this.command === 'code';
+        const gateShell = shellEnabled && (devTools?.shellYolo !== true || isInteractive);
+        const interruptOn = gateShell
+            ? { run_shell_command: { allowedDecisions: ['approve', 'reject'] } }
+            : undefined;
+        if (gateShell && devTools?.shellYolo === true) {
+            this.statusUpdate(StatusLevel.INFO, 'Shell tool (run_shell_command) auto-approved by config (shellYolo). Type /auto-approve off to require per-command approval.');
+        }
+        else 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.');
+        }
         return {
             model: this.config.llm,
             tools: passThroughTools,
             permissions,
             middleware,
             systemPrompt,
+            interruptOn,
         };
     }
 }
 /**
- * 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: 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).
  *
- * `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.
+ * 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.
  */
-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 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.';
+/**
+ * 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.
+ *
+ * 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.
+ */
+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