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

package/README.md

@@ -1,25 +1,75 @@
 # @gaunt-sloth/agent
 
-The deep-agent runtime for Gaunt Sloth. Consolidates what were previously
-`@gaunt-sloth/tools` and `@gaunt-sloth/api`:
-
-- Built-in tools and toolkits (filesystem, dev, custom, web fetch, status update)
-- Middleware registry (summarization, prompt caching, binary content injection)
-- MCP client + OAuth provider
-- A2A client and tools
-- The AG-UI server (`startAgUiServer`) and interactive session module
-- The ACP (Agent Client Protocol) server (`startAcpServer`), exposed as the
-  `gaunt-sloth-acp` binary
-- The `createResolvers` tool/middleware resolver wiring
-
-It builds on `@gaunt-sloth/core` (config, provider factory, lean langchain runtime).
-
-> **Running the ACP server:** prefer `gaunt-sloth --acp-agent` from the
-> [`gaunt-sloth`](../app) app, not the standalone `gaunt-sloth-acp` binary. The LLM
-> providers are `peerDependencies` of `@gaunt-sloth/core` that only the app declares, so a
-> bare `@gaunt-sloth/agent` install has no providers to construct a model from. See the
-> [app README → ACP server](../app/README.md#acp-server-editor-integration) for setup and a
-> Zed `settings.json` example.
-
-> `@gaunt-sloth/tools` and `@gaunt-sloth/api` are deprecated and now re-export
-> from this package.
+The agent runtime for Gaunt Sloth: built-in tools and toolkits (filesystem, dev/shell, web
+fetch, custom), the middleware registry, MCP client + OAuth provider, A2A client and tools, the
+AG-UI server (`startAgUiServer`), the ACP server (`startAcpServer`), the interactive session
+module, and the `createResolvers` tool/middleware resolver wiring. It builds on
+[`@gaunt-sloth/core`](https://www.npmjs.com/package/@gaunt-sloth/core) (config, provider
+factory, lean agent runtime).
+
+**When to depend on this package** — you are embedding the running agent: serving it to a web
+client over AG-UI, wiring its tools/middleware into your own host, or talking to MCP/A2A
+services. The fat [`gaunt-sloth`](https://www.npmjs.com/package/gaunt-sloth) CLI wires this same
+runtime into `gth chat` / `gth code` / `gth api`; install that instead if you want the terminal
+experience rather than a library.
+
+## Installation
+
+```bash
+npm install @gaunt-sloth/agent @langchain/anthropic
+```
+
+AI providers are optional peer dependencies of `@gaunt-sloth/core` — install the one(s) your
+config uses (see the core README's provider list).
+
+## Embedding: serve the agent over AG-UI
+
+I want a local web client to talk to the configured Gaunt Sloth agent over the
+[AG-UI protocol](https://github.com/ag-ui-protocol/ag-ui). With a `.gsloth.config.*` in the
+working directory:
+
+```js
+import { initConfig } from '@gaunt-sloth/core';
+import { startAgUiServer } from '@gaunt-sloth/agent';
+
+const config = await initConfig({});
+await startAgUiServer(config, config.commands?.api?.port ?? 3000);
+// POST /agents/:agentId/run now streams typed AG-UI SSE events
+```
+
+The server is intended for **local clients only** (a local web UI talking to a local agent); do
+not expose it to public networks. Port and CORS come from `commands.api.*` in the config — see
+[the configuration guide](https://github.com/pukeko-robotics/gaunt-sloth/blob/main/docs/configuration/index.md).
+
+## Binaries
+
+- **`gaunt-sloth-api`** — starts the AG-UI server standalone (the code above as a command):
+  `gaunt-sloth-api` (defaults to the `ag-ui` server on `commands.api.port`, 3000 by default).
+- **`gaunt-sloth-acp`** — runs the [Agent Client Protocol](https://agentclientprotocol.com/)
+  server over stdio, for ACP hosts (Zed, JetBrains). Prefer `gaunt-sloth --acp-agent` from the
+  [`gaunt-sloth`](https://www.npmjs.com/package/gaunt-sloth) app instead: the LLM providers are
+  `peerDependencies` of `@gaunt-sloth/core` that only the app declares, so a bare
+  `@gaunt-sloth/agent` install has no providers to construct a model from. See the
+  [app README → ACP server](https://github.com/pukeko-robotics/gaunt-sloth/blob/main/packages/app/README.md#acp-server-editor-integration)
+  for setup and a Zed `settings.json` example.
+
+## Exports
+
+- `@gaunt-sloth/agent` (the root export) is the public API: the AG-UI/ACP/interactive-session
+  modules, A2A client and tool, MCP utilities and OAuth provider, built-in tools config, the
+  middleware registry, the deep-agent factory, and `createResolvers`.
+- `@gaunt-sloth/agent/<path>.js` deep paths mirror the internal `dist/` layout 1:1 and are
+  deliberately kept open for reach-in (the fat CLI imports e.g.
+  `@gaunt-sloth/agent/resolvers.js`). They are supported at your own risk: internal files can
+  move between alpha/minor versions without a deprecation cycle. Prefer the root export where it
+  suffices.
+
+> `@gaunt-sloth/tools` and `@gaunt-sloth/api` are deprecated and now re-export from this
+> package.
+
+## Related packages
+
+- [`@gaunt-sloth/core`](https://www.npmjs.com/package/@gaunt-sloth/core) — Core utilities, config, and agent infrastructure ([source](https://github.com/pukeko-robotics/gaunt-sloth/tree/main/packages/core))
+- [`@gaunt-sloth/review`](https://www.npmjs.com/package/@gaunt-sloth/review) — Review engine with content/requirement sources (GitHub, Jira, file, text) and standalone CLI ([source](https://github.com/pukeko-robotics/gaunt-sloth/tree/main/packages/review))
+- [`@gaunt-sloth/batch`](https://www.npmjs.com/package/@gaunt-sloth/batch) — Batch / eval / workflow runtime ([source](https://github.com/pukeko-robotics/gaunt-sloth/tree/main/packages/batch))
+- [`gaunt-sloth`](https://www.npmjs.com/package/gaunt-sloth) — Main CLI application ([source](https://github.com/pukeko-robotics/gaunt-sloth/tree/main/packages/app))

package/dist/builtInToolsConfig.d.ts

@@ -10,15 +10,29 @@ export declare const AVAILABLE_BUILT_IN_TOOLS: {
     /**
      * Reference tool. Simply prints provided argument to the screen.
      */
-    readonly gth_status_update: "#src/tools/gthStatusUpdateTool.js";
+    readonly gth_status_update: '#src/tools/gthStatusUpdateTool.js';
     /**
      * Web fetch tool.
      */
-    readonly gth_web_fetch: "#src/tools/gthWebFetchTool.js";
+    readonly gth_web_fetch: '#src/tools/gthWebFetchTool.js';
     /**
      * AG-UI A2UI surface tool: lets the agent render an A2UI surface in the web client.
      */
-    readonly show_a2ui_surface: "#src/tools/showA2UISurfaceTool.js";
+    readonly show_a2ui_surface: '#src/tools/showA2UISurfaceTool.js';
+    /**
+     * Checklist / todo planning tool for the lean agent (the `write_todos` equivalent). Enabled
+     * by default (see {@link DEFAULT_CONFIG}); disable by setting your own `builtInTools`.
+     */
+    readonly gth_checklist: '#src/tools/gthChecklistTool.js';
+    /**
+     * Content-search (grep) tool: ripgrep-backed regex search over file CONTENTS, with an
+     * in-process JS fallback when `rg` is absent. Permission-light (no shell approval) and
+     * available in every mode. Named `gth_grep` to avoid colliding with the deep backend's
+     * built-in `grep`. Enabled by default (see {@link DEFAULT_CONFIG.builtInTools}, GS2-51); disable
+     * with `{ "builtInTools": { "gth_grep": { "enabled": false } } }`. Its searched corpus is
+     * selectable via the `fileSet` tool-config key (`gitignore` default / `all`).
+     */
+    readonly gth_grep: '#src/tools/gthGrepTool.js';
 };
 /**
  * Get default tools based on filesystem and built-in tools configuration

package/dist/builtInToolsConfig.js

@@ -3,6 +3,7 @@
  * Built-in tools config. {@link AVAILABLE_BUILT_IN_TOOLS} has a list of available tools.
  */
 import GthFileSystemToolkit from '#src/tools/GthFileSystemToolkit.js';
+import { getEffectiveDevToolsConfig, normalizeBuiltInTools, isBuiltInToolEntryEnabled, isFilesystemToolRegistered, DEV_TOOL_NAMES, } from '@gaunt-sloth/core/config.js';
 import { displayWarning } from '@gaunt-sloth/core/utils/consoleUtils.js';
 import { getCurrentWorkDir } from '@gaunt-sloth/core/utils/systemUtils.js';
 import GthDevToolkit from '#src/tools/GthDevToolkit.js';
@@ -25,6 +26,20 @@ export const AVAILABLE_BUILT_IN_TOOLS = {
      * AG-UI A2UI surface tool: lets the agent render an A2UI surface in the web client.
      */
     show_a2ui_surface: '#src/tools/showA2UISurfaceTool.js',
+    /**
+     * Checklist / todo planning tool for the lean agent (the `write_todos` equivalent). Enabled
+     * by default (see {@link DEFAULT_CONFIG}); disable by setting your own `builtInTools`.
+     */
+    gth_checklist: '#src/tools/gthChecklistTool.js',
+    /**
+     * Content-search (grep) tool: ripgrep-backed regex search over file CONTENTS, with an
+     * in-process JS fallback when `rg` is absent. Permission-light (no shell approval) and
+     * available in every mode. Named `gth_grep` to avoid colliding with the deep backend's
+     * built-in `grep`. Enabled by default (see {@link DEFAULT_CONFIG.builtInTools}, GS2-51); disable
+     * with `{ "builtInTools": { "gth_grep": { "enabled": false } } }`. Its searched corpus is
+     * selectable via the `fileSet` tool-config key (`gitignore` default / `all`).
+     */
+    gth_grep: '#src/tools/gthGrepTool.js',
 };
 /**
  * Get default tools based on filesystem and built-in tools configuration
@@ -33,15 +48,11 @@ export async function getDefaultTools(config, command) {
     const filesystemTools = filterFilesystemTools(config.filesystem, config.aiignore, config.binaryFormats);
     const builtInTools = await getBuiltInTools(config);
     // Dev tools (run commands etc.) are available to the interactive `code` command and to the
-    // scripted `exec` command — both are "do-the-job" runs — each via its own per-command config.
-    // `ask --write` (config.askWriteMode) opts `ask` into the same do-the-job tools, reusing the
-    // devTools config the --write flag copied onto commands.ask.
+    // scripted `exec` command — both are "do-the-job" runs. `ask --write` (config.askWriteMode) opts
+    // `ask` into the same do-the-job tools. CFG-18: the dev/shell config is resolved from the unified
+    // `builtInTools` registry by the shared core resolver (was per-command `devTools`).
     const askWrite = command === 'ask' && config.askWriteMode === true;
-    const devToolConfig = command === 'exec'
-        ? config.commands?.exec?.devTools
-        : askWrite
-            ? config.commands?.ask?.devTools
-            : config.commands?.code?.devTools;
+    const devToolConfig = getEffectiveDevToolsConfig(config, command);
     const devTools = await filterDevTools(askWrite ? 'code' : command, devToolConfig);
     const customTools = getCustomTools(config, command);
     return [...filesystemTools, ...devTools, ...customTools, ...builtInTools];
@@ -93,7 +104,13 @@ function getCustomTools(config, command) {
     return toolkit.getTools();
 }
 /**
- * Filter filesystem tools based on configuration
+ * Filter filesystem tools based on configuration.
+ *
+ * The decision itself lives in core ({@link isFilesystemToolRegistered}) rather than here, because
+ * the system-prompt notes need the same answer: a note that names a tool this filter did not
+ * register tells the model to call something that does not exist. Each tool is judged by the
+ * read/write class the toolkit stamped on it (`gthFileSystemType`), so the class is read from the
+ * tool rather than from a second table of names.
  */
 function filterFilesystemTools(filesystemConfig, aiignoreConfig, binaryFormats) {
     const toolkit = new GthFileSystemToolkit({
@@ -101,44 +118,26 @@ function filterFilesystemTools(filesystemConfig, aiignoreConfig, binaryFormats)
         aiignoreConfig,
         binaryFormats,
     });
-    if (filesystemConfig === 'all') {
-        return toolkit.getTools();
-    }
-    if (filesystemConfig === 'none') {
-        return [];
-    }
-    if (filesystemConfig === 'read') {
-        // Read-only: only allow read operations
-        return toolkit.getFilteredTools(['read']);
-    }
-    if (!Array.isArray(filesystemConfig)) {
-        return toolkit.getTools();
-    }
-    if (filesystemConfig.includes('all')) {
-        return toolkit.getTools();
-    }
-    // Handle an array of specific tool names or 'read'/'all'
-    const allowedTools = filesystemConfig.includes('read')
-        ? toolkit.getFilteredTools(['read'])
-        : [];
-    // Also allow specific tool names
-    const allowedToolNames = new Set(filesystemConfig.filter((name) => name !== 'read' && name !== 'all'));
-    const specificNamedTools = toolkit.getTools().filter((tool) => {
-        return tool.name && allowedToolNames.has(tool.name);
-    });
-    // Combine and deduplicate
-    const allAllowedTools = [...allowedTools, ...specificNamedTools];
-    return allAllowedTools.filter((tool, index, arr) => arr.findIndex((t) => t.name === tool.name) === index);
+    return toolkit.getTools().filter((tool) => isFilesystemToolRegistered(filesystemConfig, tool.name, 
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    tool.gthFileSystemType));
 }
 /**
  * Get built-in tools based on configuration
  */
 async function getBuiltInTools(config) {
     const tools = [];
-    if (!config.builtInTools) {
-        return tools;
-    }
-    for (const toolName of config.builtInTools) {
+    // CFG-18: `builtInTools` may be a string[] or the widened registry — normalize to a name→value
+    // lookup. Dev/shell tools (run_*, run_shell_command) are emitted by GthDevToolkit via the dev
+    // bucket, so skip them here (a registry entry for them is legitimate, not an unknown built-in).
+    const registry = normalizeBuiltInTools(config.builtInTools);
+    for (const [toolName, value] of Object.entries(registry)) {
+        if (DEV_TOOL_NAMES.includes(toolName)) {
+            continue;
+        }
+        if (!isBuiltInToolEntryEnabled(value)) {
+            continue;
+        }
         if (toolName in AVAILABLE_BUILT_IN_TOOLS) {
             try {
                 const tool = await import(AVAILABLE_BUILT_IN_TOOLS[toolName]);

package/dist/builtInToolsConfig.js.map

@@ -1 +1 @@
-{"version":3,"file":"builtInToolsConfig.js","sourceRoot":"","sources":["../src/builtInToolsConfig.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"builtInToolsConfig.js","sourceRoot":"","sources":["../src/builtInToolsConfig.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,oBAAoB,MAAM,oCAAoC,CAAC;AAEtE,OAAO,EAIL,0BAA0B,EAC1B,qBAAqB,EACrB,yBAAyB,EACzB,0BAA0B,EAC1B,cAAc,GAEf,MAAM,6BAA6B,CAAC;AACrC,OAAO,EAAE,cAAc,EAAE,MAAM,yCAAyC,CAAC;AACzE,OAAO,EAAE,iBAAiB,EAAE,MAAM,wCAAwC,CAAC;AAE3E,OAAO,aAAa,MAAM,6BAA6B,CAAC;AACxD,OAAO,gBAAgB,MAAM,gCAAgC,CAAC;AAE9D;;;;GAIG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG;IACtC;;OAEG;IACH,iBAAiB,EAAE,mCAAmC;IACtD;;OAEG;IACH,aAAa,EAAE,+BAA+B;IAC9C;;OAEG;IACH,iBAAiB,EAAE,mCAAmC;IACtD;;;OAGG;IACH,aAAa,EAAE,gCAAgC;IAC/C;;;;;;;OAOG;IACH,QAAQ,EAAE,2BAA2B;CAC7B,CAAC;AAEX;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,MAAiB,EACjB,OAAoB;IAEpB,MAAM,eAAe,GAAG,qBAAqB,CAC3C,MAAM,CAAC,UAAU,EACjB,MAAM,CAAC,QAAQ,EACf,MAAM,CAAC,aAAa,CACrB,CAAC;IACF,MAAM,YAAY,GAAG,MAAM,eAAe,CAAC,MAAM,CAAC,CAAC;IACnD,2FAA2F;IAC3F,iGAAiG;IACjG,kGAAkG;IAClG,oFAAoF;IACpF,MAAM,QAAQ,GAAG,OAAO,KAAK,KAAK,IAAI,MAAM,CAAC,YAAY,KAAK,IAAI,CAAC;IACnE,MAAM,aAAa,GAAG,0BAA0B,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClE,MAAM,QAAQ,GAAG,MAAM,cAAc,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,EAAE,aAAa,CAAC,CAAC;IAClF,MAAM,WAAW,GAAG,cAAc,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACpD,OAAO,CAAC,GAAG,eAAe,EAAE,GAAG,QAAQ,EAAE,GAAG,WAAW,EAAE,GAAG,YAAY,CAAC,CAAC;AAC5E,CAAC;AAED,KAAK,UAAU,cAAc,CAC3B,OAA+B,EAC/B,aAA4C;IAE5C,4FAA4F;IAC5F,uFAAuF;IACvF,2FAA2F;IAC3F,6FAA6F;IAC7F,sEAAsE;IACtE,IAAI,OAAO,KAAK,MAAM,IAAI,OAAO,KAAK,MAAM,EAAE,CAAC;QAC7C,OAAO,EAAE,CAAC;IACZ,CAAC;IACD,IAAI,OAAO,KAAK,MAAM,IAAI,CAAC,aAAa,EAAE,CAAC;QACzC,OAAO,EAAE,CAAC;IACZ,CAAC;IACD,oFAAoF;IACpF,MAAM,OAAO,GAAG,IAAI,aAAa,CAAC,aAAa,IAAI,EAAE,EAAE,OAAO,CAAC,CAAC;IAChE,OAAO,CAAC,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC;AACjC,CAAC;AAED;;;GAGG;AACH,SAAS,cAAc,CAAC,MAAiB,EAAE,OAAoB;IAC7D,sCAAsC;IACtC,IAAI,WAAkD,CAAC;IAEvD,IAAI,OAAO,IAAI,MAAM,CAAC,QAAQ,EAAE,CAAC,OAAO,CAAC,EAAE,CAAC;QAC1C,MAAM,SAAS,GAAG,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;QAC3C,4CAA4C;QAC5C,IAAI,aAAa,IAAI,SAAS,EAAE,CAAC;YAC/B,WAAW,GAAG,SAAS,CAAC,WAAW,CAAC;QACtC,CAAC;aAAM,CAAC;YACN,8BAA8B;YAC9B,WAAW,GAAG,MAAM,CAAC,WAAW,CAAC;QACnC,CAAC;IACH,CAAC;SAAM,CAAC;QACN,4DAA4D;QAC5D,WAAW,GAAG,MAAM,CAAC,WAAW,CAAC;IACnC,CAAC;IAED,mDAAmD;IACnD,IAAI,WAAW,KAAK,KAAK,IAAI,CAAC,WAAW,IAAI,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACnF,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,4CAA4C;IAC5C,MAAM,OAAO,GAAG,IAAI,gBAAgB,CAAC,WAAW,CAAC,CAAC;IAClD,OAAO,OAAO,CAAC,QAAQ,EAAE,CAAC;AAC5B,CAAC;AAED;;;;;;;;GAQG;AACH,SAAS,qBAAqB,CAC5B,gBAAuC,EACvC,cAGC,EACD,aAA0C;IAE1C,MAAM,OAAO,GAAG,IAAI,oBAAoB,CAAC;QACvC,kBAAkB,EAAE,CAAC,iBAAiB,EAAE,CAAC;QACzC,cAAc;QACd,aAAa;KACd,CAAC,CAAC;IACH,OAAO,OAAO,CAAC,QAAQ,EAAE,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CACxC,0BAA0B,CACxB,gBAAgB,EAChB,IAAI,CAAC,IAAI;IACT,8DAA8D;IAC7D,IAAY,CAAC,iBAAiB,CAChC,CACF,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,KAAK,UAAU,eAAe,CAAC,MAAiB;IAC9C,MAAM,KAAK,GAA8B,EAAE,CAAC;IAE5C,+FAA+F;IAC/F,8FAA8F;IAC9F,gGAAgG;IAChG,MAAM,QAAQ,GAAG,qBAAqB,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC;IAE5D,KAAK,MAAM,CAAC,QAAQ,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC;QACzD,IAAI,cAAc,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;YACtC,SAAS;QACX,CAAC;QACD,IAAI,CAAC,yBAAyB,CAAC,KAAK,CAAC,EAAE,CAAC;YACtC,SAAS;QACX,CAAC;QACD,IAAI,QAAQ,IAAI,wBAAwB,EAAE,CAAC;YACzC,IAAI,CAAC;gBACH,MAAM,IAAI,GAAG,MAAM,MAAM,CACvB,wBAAwB,CAAC,QAAiD,CAAC,CAC5E,CAAC;gBACF,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC;YAC/B,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,cAAc,CAAC,iCAAiC,QAAQ,MAAM,KAAK,EAAE,CAAC,CAAC;YACzE,CAAC;QACH,CAAC;aAAM,CAAC;YACN,cAAc,CAAC,0BAA0B,QAAQ,EAAE,CAAC,CAAC;QACvD,CAAC;IACH,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/core/GthDeepAgent.d.ts

@@ -1,11 +1,12 @@
 import type { GthConfig } from '@gaunt-sloth/core/config.js';
 import { GthAbstractAgent } from '@gaunt-sloth/core/core/GthAbstractAgent.js';
 import { type GthCommand } from '@gaunt-sloth/core/core/types.js';
+export { appendOsShellNote, appendCwdNote, appendCommitCoAuthorNote, appendModelContextNote, resolveModelIdentity, OS_SHELL_GUIDANCE, } from '@gaunt-sloth/core/utils/systemPromptNotes.js';
 import type { StructuredToolInterface } from '@langchain/core/tools';
 import type { BaseCheckpointSaver } from '@langchain/langgraph';
 import { type InterruptOnConfig } from 'langchain';
 import { type FilesystemPermission } from '#src/core/deepAgentPermissions.js';
-import type { DebugCapture, DebugRequestExtras } from '#src/core/debugCapture.js';
+export { extractDebugRequestExtras } from '#src/core/debugCapture.js';
 /**
  * The subset of `createDeepAgent` params that are independent of the transport
  * (the local runner vs. the ACP server). Both {@link GthDeepAgent.init} (which adds the
@@ -39,9 +40,14 @@ export interface GthDeepAgentParams {
      * `__interrupt__` (a `HITLRequest`) so a consumer can approve/reject before the tool runs;
      * resume with `new Command({ resume: { decisions: [...] } })` on the same `thread_id`.
      *
-     * gsloth currently sets this only for the opt-in `run_shell_command` tool (when its
-     * `devTools.shell` is enabled and `devTools.shellYolo` is NOT). Left `undefined` otherwise —
-     * including under yolo — so no tool is gated and runs never suspend for approval.
+     * gsloth sets this for the opt-in `run_shell_command` tool whenever the shell tool is
+     * enabled — including under `approvals.mode: "bypass"` in interactive `code` mode, where the tool
+     * stays gated so the session's own approvals mode governs it (the runner seeds that mode from
+     * config and, at `bypass`, approves a gated shell call without prompting or rating; the deny
+     * list still runs first, and `/approvals <mode>` can switch a session back to a rated mode
+     * mid-run, which only works while the tool is still gated). It is left `undefined` only for a non-interactive
+     * bypass run (exec / ask --write), whose single-shot path does not drain interrupts, so the tool
+     * there runs inline without suspending. See `getAgentBuildParams`.
      */
     interruptOn?: Record<string, boolean | InterruptOnConfig>;
 }
@@ -56,7 +62,10 @@ export interface GthDeepAgentParams {
  *   {@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
@@ -64,13 +73,6 @@ export interface GthDeepAgentParams {
  * middleware hardening without re-running `createDeepAgent` locally.
  */
 export declare 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 | undefined;
     init(command: GthCommand | undefined, configIn: GthConfig, checkpointer?: BaseCheckpointSaver | undefined): Promise<void>;
     /**
      * Assemble the transport-agnostic {@link GthDeepAgentParams}: resolve tools (with the
@@ -80,29 +82,47 @@ export declare class GthDeepAgent extends GthAbstractAgent {
      * runner ({@link init}) and the `deepagents-acp` ACP entry.
      */
     buildDeepAgentParams(command: GthCommand | undefined, configIn: GthConfig): Promise<GthDeepAgentParams>;
-    /**
-     * 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.
-     */
-    private getEffectiveDevToolsConfig;
 }
 /**
- * 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 declare function appendCwdNote(systemPrompt: string | undefined, cwd: string): string;
+export declare const PATH_NAMESPACE_GUIDANCE: string;
 /**
- * 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 (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 declare function appendVirtualCwdNote(systemPrompt: string | undefined): string;
+/**
+ * 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 declare function extractDebugRequestExtras(request: unknown): DebugRequestExtras | undefined;
+export declare function createPathNamespaceCorrectionMiddleware(appendCorrection: boolean): import("langchain").AgentMiddleware<undefined, undefined, unknown, readonly (import("@langchain/core/tools").ServerTool | import("@langchain/core/tools").ClientTool)[], readonly []>;