@robota-sdk/agent-tool-defaults 3.0.0-beta.100

package/README.md

@@ -0,0 +1,80 @@
+# @robota-sdk/agent-tool-defaults
+
+The Robota SDK's built-in default tool set. `createDefaultTools()` builds the tools an agent session
+gets when its composition root supplies no tool list of its own, using the tool factories from
+`@robota-sdk/agent-tools`. It implements no tool itself. File tools that run on the host are
+contained by the `cwd` you pass; with a `sandboxClient` that has its own filesystem, file paths go to
+the sandbox and `cwd` does not confine them. Adapter-gated tools appear only when you supply their
+adapter. Import it at a composition root (the place that assembles an agent), not from library code.
+
+## Installation
+
+```bash
+npm install @robota-sdk/agent-tool-defaults @robota-sdk/agent-core
+```
+
+## Usage
+
+```typescript
+import { ConversationAgent } from '@robota-sdk/agent-core';
+import type { IAIProvider } from '@robota-sdk/agent-core';
+import { createDefaultTools } from '@robota-sdk/agent-tool-defaults';
+
+declare const provider: IAIProvider;
+
+const agent = new ConversationAgent({
+  name: 'DevAgent',
+  aiProviders: [provider],
+  defaultModel: { provider: 'anthropic', model: 'claude-sonnet-4-6' },
+  tools: createDefaultTools({ cwd: process.cwd() }),
+});
+```
+
+`createDefaultTools()` is synchronous and performs no I/O, and the same options always produce the
+same set of tools. Most tools are built fresh on each call; `WebFetch` and `WebSearch` are shared
+instances.
+
+## Tools
+
+| Tool                       | Included when                                                   |
+| -------------------------- | --------------------------------------------------------------- |
+| `Shell`, `Bash`            | Always                                                          |
+| `Read`, `Write`, `Edit`    | Always                                                          |
+| `Glob`, `Grep`             | Unless a `sandboxClient` with a separate filesystem is supplied |
+| `WebFetch`, `WebSearch`    | Always                                                          |
+| `AskUserQuestion`          | Always                                                          |
+| `CodebaseRetrieval`        | `retrievalAdapter` is supplied                                  |
+| `ComputerView`, `Computer` | `computerDriver` is supplied                                    |
+
+With a `sandboxClient`, `Shell` and `Bash` run commands through the sandbox. When the sandbox has
+its own filesystem (the default for a client that does not declare `filesystem: 'shared'`), `Read`,
+`Write` and `Edit` also go through it, and `Glob` / `Grep` are left out because they have no
+sandbox path. File paths are then passed to the sandbox as given, and `cwd` does not confine them.
+When the sandbox shares the host filesystem, file tools stay on the host, contained by `cwd`.
+
+## Options
+
+`createDefaultTools(options: ICreateDefaultToolsOptions): FunctionTool[]`
+
+| Option             | Type                | Description                                                                                                                                                                |
+| ------------------ | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `cwd`              | `string`            | Required. The root that host file tools are contained by (not file tools routed to a separate-filesystem sandbox), and the default working directory for `Shell` / `Bash`. |
+| `sandboxClient`    | `ISandboxClient`    | Runs commands (and, on a separate filesystem, file tools) in a sandbox.                                                                                                    |
+| `shellExecutable`  | `string`            | Host-selected executable for `Shell` and `Bash`.                                                                                                                           |
+| `retrievalAdapter` | `IRetrievalAdapter` | Adds the `CodebaseRetrieval` tool.                                                                                                                                         |
+| `computerDriver`   | `IComputerDriver`   | Adds the `ComputerView` and `Computer` tools. There is no host fallback.                                                                                                   |
+
+`ISandboxClient`, `IRetrievalAdapter` and `IComputerDriver` are exported by
+`@robota-sdk/agent-tools`.
+
+## Related packages
+
+- [`@robota-sdk/agent-tools`](../agent-tools/README.md): the tool factories, the tool registry and
+  the sandbox clients.
+- [`@robota-sdk/agent-core`](../agent-core/README.md): the `ConversationAgent` agent and the tool contract.
+
+See [docs/SPEC.md](docs/SPEC.md) for the package contract.
+
+## License
+
+This package is dual-licensed under the [GNU AGPL-3.0](../../LICENSE) or a [commercial license](../../COMMERCIAL.md). See [LICENSING.md](../../LICENSING.md).

package/dist/node/index.cjs

@@ -0,0 +1 @@
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});let e=require("@robota-sdk/agent-tools");function t(t){let n=(0,e.routesFilesThroughSandbox)(t.sandboxClient),{editorFiles:r,...i}=t,{sandboxClient:a,...o}=t,s=n?i:o;return[(0,e.createShellTool)(i),(0,e.createBashTool)(i),(0,e.createReadTool)(s),(0,e.createWriteTool)(s),(0,e.createEditTool)(s),...n?[]:[(0,e.createGlobTool)(o),(0,e.createGrepTool)(o)],(0,e.createWebFetchTool)({userAgent:t.httpUserAgent}),(0,e.createWebSearchTool)(),(0,e.createAskUserQuestionTool)(),...t.retrievalAdapter?[(0,e.createRetrievalTool)({adapter:t.retrievalAdapter})]:[],...t.computerDriver?(0,e.createComputerTool)({driver:t.computerDriver}):[]]}exports.createDefaultTools=t;

package/dist/node/index.d.cts

@@ -0,0 +1,49 @@
+import { FunctionTool } from "@robota-sdk/agent-core";
+import { IComputerDriver, IEditorFileAccess, IRetrievalAdapter, ISandboxClient } from "@robota-sdk/agent-tools";
+//#region src/create-default-tools.d.ts
+/**
+ * Create the default set of CLI tools.
+ * Returns the standard tools.
+ */
+interface ICreateDefaultToolsOptions {
+  sandboxClient?: ISandboxClient;
+  /** Host-selected executable for Shell and Bash. */
+  shellExecutable?: string;
+  httpUserAgent?: string;
+  /**
+   * The execution root every file tool is contained by. REQUIRED — ARCH-010.
+   *
+   * It was optional, and `child-process-subagent-worker.ts` called this factory with no argument at
+   * all: `cwd` was `undefined`, the path guard was fail-open, and the subagent's `Read` returned
+   * `/etc/hostname`. Requiring it means a construction site that forgets does not compile, which is
+   * the only way a containment root stays a contract rather than a convention.
+   */
+  cwd: string;
+  /**
+   * An editor that has the workspace open, asked at each call. The host file tools read and write
+   * through what it offers and the searches say they read the disk; commands never use it, and a
+   * sandbox with its own filesystem keeps every file tool, since its files are not the editor's.
+   */
+  editorFiles?: () => IEditorFileAccess | undefined;
+  /** SELFHOST-003: when present, adds the adapter-gated `CodebaseRetrieval` tool (absent otherwise). */
+  retrievalAdapter?: IRetrievalAdapter;
+  /**
+   * SELFHOST-010: when present, adds the adapter-gated `ComputerView` + `Computer` tools. Unlike the
+   * shell tool's host `spawn` fallback, computer-use has NO host fallback — with no driver the tools are
+   * simply ABSENT (there is no safe library-side "local" screen to fall back to).
+   */
+  computerDriver?: IComputerDriver;
+}
+/**
+ * ARCH-035: returns `FunctionTool[]`, which is what every factory below actually returns.
+ *
+ * An earlier revision cast each one to `IToolWithEventService` because session assembly consumes that
+ * interface. The cast was lossy in the direction that mattered: `ICapabilityPack.tools` is
+ * `readonly FunctionTool[]`, so a pack CONSUMING this set could not assign it without a second cast
+ * back — one erasure creating the need for another. `FunctionTool` satisfies `IToolWithEventService`,
+ * so session assembly is unaffected and no cast is needed at either end.
+ */
+declare function createDefaultTools(options: ICreateDefaultToolsOptions): FunctionTool[];
+//#endregion
+export { type ICreateDefaultToolsOptions, createDefaultTools };
+//# sourceMappingURL=index.d.cts.map

package/dist/node/index.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.cts","names":[],"sources":["../../src/create-default-tools.ts"],"mappings":";;;;;;;UA+CiB;EACf,gBAAgB;;EAEhB;EACA;;;;;;;;;EASA;;;;;;EAMA,oBAAoB;;EAEpB,mBAAmB;;;;;;EAMnB,iBAAiB;;;;;;;;;;;iBAYH,mBAAmB,SAAS,6BAA6B"}

package/dist/node/index.d.ts

@@ -0,0 +1,49 @@
+import { IComputerDriver, IEditorFileAccess, IRetrievalAdapter, ISandboxClient } from "@robota-sdk/agent-tools";
+import { FunctionTool } from "@robota-sdk/agent-core";
+//#region src/create-default-tools.d.ts
+/**
+ * Create the default set of CLI tools.
+ * Returns the standard tools.
+ */
+interface ICreateDefaultToolsOptions {
+  sandboxClient?: ISandboxClient;
+  /** Host-selected executable for Shell and Bash. */
+  shellExecutable?: string;
+  httpUserAgent?: string;
+  /**
+   * The execution root every file tool is contained by. REQUIRED — ARCH-010.
+   *
+   * It was optional, and `child-process-subagent-worker.ts` called this factory with no argument at
+   * all: `cwd` was `undefined`, the path guard was fail-open, and the subagent's `Read` returned
+   * `/etc/hostname`. Requiring it means a construction site that forgets does not compile, which is
+   * the only way a containment root stays a contract rather than a convention.
+   */
+  cwd: string;
+  /**
+   * An editor that has the workspace open, asked at each call. The host file tools read and write
+   * through what it offers and the searches say they read the disk; commands never use it, and a
+   * sandbox with its own filesystem keeps every file tool, since its files are not the editor's.
+   */
+  editorFiles?: () => IEditorFileAccess | undefined;
+  /** SELFHOST-003: when present, adds the adapter-gated `CodebaseRetrieval` tool (absent otherwise). */
+  retrievalAdapter?: IRetrievalAdapter;
+  /**
+   * SELFHOST-010: when present, adds the adapter-gated `ComputerView` + `Computer` tools. Unlike the
+   * shell tool's host `spawn` fallback, computer-use has NO host fallback — with no driver the tools are
+   * simply ABSENT (there is no safe library-side "local" screen to fall back to).
+   */
+  computerDriver?: IComputerDriver;
+}
+/**
+ * ARCH-035: returns `FunctionTool[]`, which is what every factory below actually returns.
+ *
+ * An earlier revision cast each one to `IToolWithEventService` because session assembly consumes that
+ * interface. The cast was lossy in the direction that mattered: `ICapabilityPack.tools` is
+ * `readonly FunctionTool[]`, so a pack CONSUMING this set could not assign it without a second cast
+ * back — one erasure creating the need for another. `FunctionTool` satisfies `IToolWithEventService`,
+ * so session assembly is unaffected and no cast is needed at either end.
+ */
+declare function createDefaultTools(options: ICreateDefaultToolsOptions): FunctionTool[];
+//#endregion
+export { type ICreateDefaultToolsOptions, createDefaultTools };
+//# sourceMappingURL=index.d.ts.map

package/dist/node/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/create-default-tools.ts"],"mappings":";;;;;;;UA+CiB;EACf,gBAAgB;;EAEhB;EACA;;;;;;;;;EASA;;;;;;EAMA,oBAAoB;;EAEpB,mBAAmB;;;;;;EAMnB,iBAAiB;;;;;;;;;;;iBAYH,mBAAmB,SAAS,6BAA6B"}

package/dist/node/index.js

@@ -0,0 +1,2 @@
+import{createAskUserQuestionTool as e,createBashTool as t,createComputerTool as n,createEditTool as r,createGlobTool as i,createGrepTool as a,createReadTool as o,createRetrievalTool as s,createShellTool as c,createWebFetchTool as l,createWebSearchTool as u,createWriteTool as d,routesFilesThroughSandbox as f}from"@robota-sdk/agent-tools";function p(p){let m=f(p.sandboxClient),{editorFiles:h,...g}=p,{sandboxClient:_,...v}=p,y=m?g:v;return[c(g),t(g),o(y),d(y),r(y),...m?[]:[i(v),a(v)],l({userAgent:p.httpUserAgent}),u(),e(),...p.retrievalAdapter?[s({adapter:p.retrievalAdapter})]:[],...p.computerDriver?n({driver:p.computerDriver}):[]]}export{p as createDefaultTools};
+//# sourceMappingURL=index.js.map

package/dist/node/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../../src/create-default-tools.ts"],"sourcesContent":["/**\n * The DEFAULT TOOL SET — a composition leaf.\n *\n * ARCH-035 moved this out of `@robota-sdk/agent-framework`. It is a defaults aggregator, and\n * `.agents/project-structure.md` classifies that family as a composition leaf \"imported only at\n * composition roots (entry-point-only)\" — not something a mid-layer assembly library owns, publishes\n * and self-consumes.\n *\n * The move is what carries the guarantee. `agent-subagent-runner` may depend on `agent-framework`\n * (it needs `createSubagentSession` and friends) but has no manifest edge to THIS package, so\n * `import { createDefaultTools } from '@robota-sdk/agent-tool-defaults'` does not resolve there at\n * all. A neutral runner composing the product's tool surface is now a compile error rather than a\n * scan finding — the same shape ARCH-021 achieved on the provider axis with\n * `@robota-sdk/agent-builtin-providers`.\n *\n * `DEFAULT_TOOL_DESCRIPTIONS` deliberately did NOT come along: its only consumer builds the system\n * prompt synchronously, and dragging it here would force either a static edge back into this leaf or\n * a second async hop through prompt building. It stays beside its consumer in `agent-framework`.\n */\nimport {\n  createAskUserQuestionTool,\n  createShellTool,\n  createBashTool,\n  createReadTool,\n  createWriteTool,\n  createEditTool,\n  createRetrievalTool,\n  createComputerTool,\n  createGlobTool,\n  createGrepTool,\n  createWebFetchTool,\n  createWebSearchTool,\n  routesFilesThroughSandbox,\n} from '@robota-sdk/agent-tools';\n\nimport type { FunctionTool } from '@robota-sdk/agent-core';\nimport type {\n  IComputerDriver,\n  IEditorFileAccess,\n  IRetrievalAdapter,\n  ISandboxClient,\n} from '@robota-sdk/agent-tools';\n\n/**\n * Create the default set of CLI tools.\n * Returns the standard tools.\n */\nexport interface ICreateDefaultToolsOptions {\n  sandboxClient?: ISandboxClient;\n  /** Host-selected executable for Shell and Bash. */\n  shellExecutable?: string;\n  httpUserAgent?: string;\n  /**\n   * The execution root every file tool is contained by. REQUIRED — ARCH-010.\n   *\n   * It was optional, and `child-process-subagent-worker.ts` called this factory with no argument at\n   * all: `cwd` was `undefined`, the path guard was fail-open, and the subagent's `Read` returned\n   * `/etc/hostname`. Requiring it means a construction site that forgets does not compile, which is\n   * the only way a containment root stays a contract rather than a convention.\n   */\n  cwd: string;\n  /**\n   * An editor that has the workspace open, asked at each call. The host file tools read and write\n   * through what it offers and the searches say they read the disk; commands never use it, and a\n   * sandbox with its own filesystem keeps every file tool, since its files are not the editor's.\n   */\n  editorFiles?: () => IEditorFileAccess | undefined;\n  /** SELFHOST-003: when present, adds the adapter-gated `CodebaseRetrieval` tool (absent otherwise). */\n  retrievalAdapter?: IRetrievalAdapter;\n  /**\n   * SELFHOST-010: when present, adds the adapter-gated `ComputerView` + `Computer` tools. Unlike the\n   * shell tool's host `spawn` fallback, computer-use has NO host fallback — with no driver the tools are\n   * simply ABSENT (there is no safe library-side \"local\" screen to fall back to).\n   */\n  computerDriver?: IComputerDriver;\n}\n\n/**\n * ARCH-035: returns `FunctionTool[]`, which is what every factory below actually returns.\n *\n * An earlier revision cast each one to `IToolWithEventService` because session assembly consumes that\n * interface. The cast was lossy in the direction that mattered: `ICapabilityPack.tools` is\n * `readonly FunctionTool[]`, so a pack CONSUMING this set could not assign it without a second cast\n * back — one erasure creating the need for another. `FunctionTool` satisfies `IToolWithEventService`,\n * so session assembly is unaffected and no cast is needed at either end.\n */\nexport function createDefaultTools(options: ICreateDefaultToolsOptions): FunctionTool[] {\n  // Issue #3081: the sandbox's filesystem relation decides where file tools read and write. On a\n  // SEPARATE filesystem every file tool goes through the sandbox — and `Glob`/`Grep`, which have no\n  // sandbox path, are withheld, so a search can never read the host while an edit writes the\n  // sandbox. On a SHARED filesystem (commands confined over the host's) file tools stay on the host\n  // under the path guard, and only commands run through the sandbox.\n  const separate = routesFilesThroughSandbox(options.sandboxClient);\n  // An editor holds the host's files, so it reaches only the tools that work on them; commands keep\n  // the agent's own sandbox.\n  const { editorFiles: _hostFilesOnly, ...commandOptions } = options;\n  const { sandboxClient: _commandsOnly, ...hostFileOptions } = options;\n  const fileOptions = separate ? commandOptions : hostFileOptions;\n  return [\n    createShellTool(commandOptions),\n    createBashTool(commandOptions),\n    createReadTool(fileOptions),\n    createWriteTool(fileOptions),\n    createEditTool(fileOptions),\n    // SEC-007: built per call, NOT the module-level singletons. A singleton is context-free by\n    // construction, so registering one meant `Glob`/`Grep` could enumerate outside the session's\n    // working directory while `Read`/`Write`/`Edit` were contained.\n    ...(separate ? [] : [createGlobTool(hostFileOptions), createGrepTool(hostFileOptions)]),\n    // MUST 4: also built per call, for the same reason — `webFetchTool`/`webSearchTool` are\n    // module-level singletons in `agent-tools`, so two concurrently open sessions built from this\n    // set (e.g. two `sessionParticipant`s) shared them and tripped `resource-reused` even though\n    // nothing about a WebFetch/WebSearch tool actually needs to be shared across sessions.\n    createWebFetchTool({ userAgent: options.httpUserAgent }),\n    createWebSearchTool(),\n    createAskUserQuestionTool(),\n    // Retrieval is adapter-gated: absent when no adapter is supplied (there is no host fallback).\n    ...(options.retrievalAdapter\n      ? [createRetrievalTool({ adapter: options.retrievalAdapter })]\n      : []),\n    // Computer-use is adapter-gated on the driver: absent when no driver is supplied. There is NO host\n    // fallback (unlike the shell tool's host spawn) — no library-side \"local\" screen exists.\n    ...(options.computerDriver ? createComputerTool({ driver: options.computerDriver }) : []),\n  ];\n}\n"],"mappings":"mVAsFA,SAAgB,EAAmB,EAAqD,CAMtF,IAAM,EAAW,EAA0B,EAAQ,aAAa,EAG1D,CAAE,YAAa,EAAgB,GAAG,GAAmB,EACrD,CAAE,cAAe,EAAe,GAAG,GAAoB,EACvD,EAAc,EAAW,EAAiB,EAChD,MAAO,CACL,EAAgB,CAAc,EAC9B,EAAe,CAAc,EAC7B,EAAe,CAAW,EAC1B,EAAgB,CAAW,EAC3B,EAAe,CAAW,EAI1B,GAAI,EAAW,CAAC,EAAI,CAAC,EAAe,CAAe,EAAG,EAAe,CAAe,CAAC,EAKrF,EAAmB,CAAE,UAAW,EAAQ,aAAc,CAAC,EACvD,EAAoB,EACpB,EAA0B,EAE1B,GAAI,EAAQ,iBACR,CAAC,EAAoB,CAAE,QAAS,EAAQ,gBAAiB,CAAC,CAAC,EAC3D,CAAC,EAGL,GAAI,EAAQ,eAAiB,EAAmB,CAAE,OAAQ,EAAQ,cAAe,CAAC,EAAI,CAAC,CACzF,CACF"}

package/package.json

@@ -0,0 +1,77 @@
+{
+  "name": "@robota-sdk/agent-tool-defaults",
+  "version": "3.0.0-beta.100",
+  "description": "The SDK's built-in default tool set (createDefaultTools) as a composition leaf over agent-tools",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "dist/node/index.js",
+  "types": "dist/node/index.d.ts",
+  "exports": {
+    ".": {
+      "source": "./src/index.ts",
+      "node": {
+        "import": {
+          "types": "./dist/node/index.d.ts",
+          "default": "./dist/node/index.js"
+        },
+        "require": {
+          "types": "./dist/node/index.d.cts",
+          "default": "./dist/node/index.cjs"
+        }
+      },
+      "default": {
+        "import": {
+          "types": "./dist/node/index.d.ts",
+          "default": "./dist/node/index.js"
+        },
+        "require": {
+          "types": "./dist/node/index.d.cts",
+          "default": "./dist/node/index.cjs"
+        }
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "files": [
+    "dist",
+    "src",
+    "CHANGELOG.md"
+  ],
+  "devDependencies": {
+    "@types/node": "^22.19.21",
+    "rimraf": "^5.0.10",
+    "tsdown": "^0.22.14",
+    "vitest": "^3.2.6"
+  },
+  "license": "AGPL-3.0-only OR LicenseRef-Commercial",
+  "dependencies": {
+    "@robota-sdk/agent-core": "3.0.0-beta.100",
+    "@robota-sdk/agent-tools": "3.0.0-beta.100"
+  },
+  "volta": {
+    "extends": "../../package.json"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/woojubb/robota"
+  },
+  "bugs": {
+    "url": "https://github.com/woojubb/robota/issues"
+  },
+  "homepage": "https://robota.io/",
+  "scripts": {
+    "build": "rimraf dist && tsdown",
+    "build:js": "pnpm run build",
+    "build:types": "pnpm run build",
+    "typecheck": "tsgo --noEmit",
+    "test": "vitest run --passWithNoTests",
+    "test:coverage": "vitest run --coverage --passWithNoTests",
+    "lint": "eslint src/ --ext .ts",
+    "clean": "rimraf dist"
+  }
+}

package/src/__tests__/create-default-tools.test.ts

@@ -0,0 +1,289 @@
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { InMemorySandboxClient } from '@robota-sdk/agent-tools';
+import { afterAll, describe, expect, it } from 'vitest';
+
+import { createDefaultTools } from '../create-default-tools.js';
+
+import type { IRetrievalAdapter, IComputerDriver } from '@robota-sdk/agent-tools';
+
+/**
+ * ARCH-010 made `cwd` a required field of `ICreateDefaultToolsOptions`. The cases that assert the tool
+ * LIST never execute a tool and so never reach a path guard; this root is named once, here, so that
+ * inertness is visible rather than implied. The containment cases below choose their own roots.
+ * Every root sits, unmade, inside one private per-run directory rather than at a fixed name under
+ * /tmp that another local user could create first.
+ */
+const PRIVATE_BASE = mkdtempSync(join(tmpdir(), 'agent-test-create-tools-'));
+afterAll(() => rmSync(PRIVATE_BASE, { recursive: true, force: true }));
+const ASSEMBLY_ROOT = join(PRIVATE_BASE, 'create-tools-assembly-root');
+
+describe('createDefaultTools', () => {
+  it('assembles all default local tools and describes web tools as local tools', () => {
+    expect(createDefaultTools({ cwd: ASSEMBLY_ROOT }).map((tool) => tool.getName())).toEqual([
+      'Shell',
+      'Bash',
+      'Read',
+      'Write',
+      'Edit',
+      'Glob',
+      'Grep',
+      'WebFetch',
+      'WebSearch',
+      'AskUserQuestion',
+    ]);
+  });
+
+  it('accepts a separate-filesystem sandbox client, withholding the host-only search tools', () => {
+    const sandboxClient = new InMemorySandboxClient();
+
+    expect(
+      createDefaultTools({ sandboxClient, cwd: ASSEMBLY_ROOT }).map((tool) => tool.getName()),
+    ).toEqual([
+      'Shell',
+      'Bash',
+      'Read',
+      'Write',
+      'Edit',
+      'WebFetch',
+      'WebSearch',
+      'AskUserQuestion',
+    ]);
+  });
+
+  // SEC-007 — the reachability floor for the ENUMERATING tools. `Glob`/`Grep` used to be registered
+  // here as the module-level singletons, which take no `cwd` at all: the assembly's containment root
+  // reached `Read`/`Write`/`Edit` and stopped. A per-call instance is the whole fix, so the property
+  // asserted is that the assembly produces a CONTAINED tool, not merely that a factory can accept a
+  // `cwd` nobody passes.
+  it('SEC-007: Glob and Grep are bound to the assembly cwd, not context-free singletons', async () => {
+    const contained = createDefaultTools({ cwd: join(PRIVATE_BASE, 'sec007-assembly-scope') });
+    // ARCH-010 — this used to be `createDefaultTools()` with no root at all, which is no longer
+    // constructible. A SECOND root serves the same purpose and states it better: one shared singleton
+    // could not carry two different roots either way.
+    const otherRoot = createDefaultTools({ cwd: join(PRIVATE_BASE, 'sec007-other-scope') });
+
+    for (const name of ['Glob', 'Grep']) {
+      const tool = contained.find((candidate) => candidate.getName() === name);
+      expect(tool, `${name} must be part of the default set`).toBeDefined();
+      // A fresh instance per call — a shared singleton could not carry two different roots.
+      expect(tool).not.toBe(otherRoot.find((candidate) => candidate.getName() === name));
+
+      const parameters = { pattern: name === 'Grep' ? 'root' : '*', path: '/etc' };
+      const outcome = await tool!.execute(
+        parameters as never,
+        {
+          toolName: name,
+          parameters,
+        } as never,
+      );
+      const result = JSON.parse(String((outcome as { data?: unknown }).data)) as {
+        success: boolean;
+        error?: string;
+      };
+
+      expect(result.success, `${name} must refuse an out-of-root search root`).toBe(false);
+      expect(result.error).toContain('outside the working directory');
+    }
+  });
+
+  // MUST 4: `WebFetch`/`WebSearch` used to be the module-level singletons `webFetchTool` /
+  // `webSearchTool` from `@robota-sdk/agent-tools` — the SAME object on every call. Two
+  // concurrently open sessions each built from `createDefaultTools({cwd})` then shared them and
+  // tripped a resource guard's `resource-reused` even though nothing about either tool needs
+  // sharing across sessions. A fresh instance per call is the fix, mirroring Glob/Grep (SEC-007).
+  it('MUST 4: WebFetch and WebSearch are fresh instances per call, not context-free singletons', () => {
+    const first = createDefaultTools({ cwd: ASSEMBLY_ROOT });
+    const second = createDefaultTools({ cwd: ASSEMBLY_ROOT });
+    for (const name of ['WebFetch', 'WebSearch']) {
+      const a = first.find((tool) => tool.getName() === name);
+      const b = second.find((tool) => tool.getName() === name);
+      expect(a, `${name} must be part of the default set`).toBeDefined();
+      expect(b).toBeDefined();
+      expect(a).not.toBe(b);
+    }
+  });
+
+  // SELFHOST-003 TC-03: the retrieval adapter is threaded through assembly and the tool is
+  // adapter-gated — absent with no adapter, present (and only then) when an adapter is supplied.
+  it('TC-03: CodebaseRetrieval joins the default set only when a retrieval adapter is supplied', () => {
+    expect(createDefaultTools({ cwd: ASSEMBLY_ROOT }).map((tool) => tool.getName())).not.toContain(
+      'CodebaseRetrieval',
+    );
+
+    const retrievalAdapter: IRetrievalAdapter = {
+      retrieve: async () => ({ symbols: [], totalTokens: 0 }),
+    };
+    expect(
+      createDefaultTools({ retrievalAdapter, cwd: ASSEMBLY_ROOT }).map((tool) => tool.getName()),
+    ).toContain('CodebaseRetrieval');
+  });
+
+  // SELFHOST-010 TC-04: the computer driver is threaded through assembly and the ComputerView/Computer
+  // tools are adapter-gated — ABSENT with no driver (no host fallback), present only when a driver is
+  // supplied.
+  it('TC-04: ComputerView/Computer join the default set only when a computer driver is supplied', () => {
+    const withoutDriver = createDefaultTools({ cwd: ASSEMBLY_ROOT }).map((tool) => tool.getName());
+    expect(withoutDriver).not.toContain('ComputerView');
+    expect(withoutDriver).not.toContain('Computer');
+
+    const computerDriver: IComputerDriver = {
+      screenshot: async () => ({ data: 'x', mediaType: 'image/png' }),
+      act: async () => ({ screenshot: { data: 'x', mediaType: 'image/png' } }),
+    };
+    const withDriver = createDefaultTools({ computerDriver, cwd: ASSEMBLY_ROOT }).map((tool) =>
+      tool.getName(),
+    );
+    expect(withDriver).toContain('ComputerView');
+    expect(withDriver).toContain('Computer');
+  });
+});
+
+/**
+ * CLI-1990 TC-11 — the default tier is RESIDENT.
+ *
+ * Residency is declared by omission: a tool that says nothing about `deferLoading` is sent on every
+ * request, which is what every built-in must remain. Anthropic's own guidance is that standard tool
+ * calling beats a search under ten tools, so deferring any of these would be a measurable
+ * regression rather than a saving — and the invariant that at least one tool stays resident is
+ * satisfied by this tier alone.
+ */
+describe('CLI-1990 TC-11 — default tool residency', () => {
+  it('declares no deferLoading on any built-in — the whole tier is resident', () => {
+    const deferred = createDefaultTools({ cwd: ASSEMBLY_ROOT })
+      .filter((tool) => tool.schema.deferLoading !== undefined)
+      .map((tool) => tool.getName());
+    expect(deferred).toEqual([]);
+  });
+
+  it('keeps the ten built-ins ten — the search tool is added by session assembly, not here', () => {
+    const names = createDefaultTools({ cwd: ASSEMBLY_ROOT }).map((tool) => tool.getName());
+    expect(names).toEqual([
+      'Shell',
+      'Bash',
+      'Read',
+      'Write',
+      'Edit',
+      'Glob',
+      'Grep',
+      'WebFetch',
+      'WebSearch',
+      'AskUserQuestion',
+    ]);
+    expect(names).not.toContain('ToolSearch');
+  });
+
+  it('stays resident under the adapter gates too', () => {
+    const retrievalAdapter: IRetrievalAdapter = {
+      retrieve: async () => ({ symbols: [], totalTokens: 0 }),
+    };
+    const withRetrieval = createDefaultTools({ retrievalAdapter, cwd: ASSEMBLY_ROOT });
+    expect(withRetrieval.every((tool) => tool.schema.deferLoading === undefined)).toBe(true);
+  });
+});
+
+describe('file tools follow the sandbox filesystem relation (issue #3081)', () => {
+  it('a separate filesystem withholds Glob and Grep, and routes Read through the sandbox', async () => {
+    const sandboxClient = new InMemorySandboxClient();
+    await sandboxClient.writeFile('/sandbox/only.txt', 'inside the sandbox');
+    const tools = createDefaultTools({ cwd: '/sandbox', sandboxClient });
+    const names = tools.map((tool) => tool.getName());
+    expect(names).not.toContain('Glob');
+    expect(names).not.toContain('Grep');
+    const read = tools.find((tool) => tool.getName() === 'Read')!;
+    const result = await read.execute({ filePath: '/sandbox/only.txt' });
+    expect(JSON.stringify(result)).toContain('inside the sandbox');
+  });
+
+  it('a shared filesystem keeps every file tool on the host', async () => {
+    const shared = Object.assign(new InMemorySandboxClient(), { filesystem: 'shared' as const });
+    await shared.writeFile('/sandbox/only.txt', 'inside the sandbox');
+    const tools = createDefaultTools({ cwd: '/sandbox', sandboxClient: shared });
+    const names = tools.map((tool) => tool.getName());
+    expect(names).toContain('Glob');
+    expect(names).toContain('Grep');
+    const read = tools.find((tool) => tool.getName() === 'Read')!;
+    const result = await read.execute({ filePath: '/sandbox/only.txt' });
+    // The host has no /sandbox root, so the host read fails; it never consults the sandbox's files.
+    expect(JSON.stringify(result)).not.toContain('inside the sandbox');
+  });
+});
+
+/** Issue #3550 item 4 — an editor reaches the host file tools and the searches, never the commands. */
+describe('an editor reaches the host file tools only', () => {
+  function recordingEditor() {
+    const asked: string[] = [];
+    const requests: string[] = [];
+    const access = {
+      readTextFile: async (path: string) => {
+        requests.push(`read ${path}`);
+        return 'EDITOR TEXT\n';
+      },
+      writeTextFile: async (path: string) => {
+        requests.push(`write ${path}`);
+      },
+    };
+    return {
+      requests,
+      asked,
+      editorFiles: () => {
+        asked.push('asked');
+        return access;
+      },
+    };
+  }
+  const parse = (outcome: unknown) =>
+    JSON.parse(String((outcome as { data?: unknown }).data)) as { output: string };
+
+  it('Read and Write go through the editor and the searches say they read the disk', async () => {
+    const root = mkdtempSync(join(PRIVATE_BASE, 'editor-'));
+    writeFileSync(join(root, 'probe.txt'), 'DISK TEXT\n');
+    const editor = recordingEditor();
+    const tools = createDefaultTools({ cwd: root, editorFiles: editor.editorFiles });
+    const byName = (name: string) => tools.find((tool) => tool.getName() === name)!;
+
+    expect(parse(await byName('Read').execute({ filePath: 'probe.txt' })).output).toContain(
+      'EDITOR TEXT',
+    );
+    await byName('Write').execute({ filePath: 'out.txt', content: 'x' });
+    expect(editor.requests).toEqual([`read ${join(root, 'probe.txt')}`, `write ${join(root, 'out.txt')}`]);
+    expect(parse(await byName('Grep').execute({ pattern: 'DISK' })).output).toContain(
+      '[Searched the files on disk.',
+    );
+  });
+
+  it('Shell and Bash never ask for the editor', async () => {
+    const root = mkdtempSync(join(PRIVATE_BASE, 'editor-shell-'));
+    const editor = recordingEditor();
+    const tools = createDefaultTools({ cwd: root, editorFiles: editor.editorFiles });
+    for (const name of ['Shell', 'Bash']) {
+      const outcome = await tools
+        .find((tool) => tool.getName() === name)!
+        .execute({ command: 'echo shell-ok' });
+      expect(JSON.stringify(outcome)).toContain('shell-ok');
+    }
+    expect(editor.asked).toEqual([]);
+  });
+
+  it('a separate sandbox filesystem keeps every file tool, so the editor is not asked', async () => {
+    const sandboxClient = new InMemorySandboxClient();
+    await sandboxClient.writeFile('/sandbox/only.txt', 'inside the sandbox');
+    const editor = recordingEditor();
+    const tools = createDefaultTools({
+      cwd: '/sandbox',
+      sandboxClient,
+      editorFiles: editor.editorFiles,
+    });
+    const read = tools.find((tool) => tool.getName() === 'Read')!;
+    expect(JSON.stringify(await read.execute({ filePath: '/sandbox/only.txt' }))).toContain(
+      'inside the sandbox',
+    );
+    await tools.find((tool) => tool.getName() === 'Write')!.execute({
+      filePath: '/sandbox/out.txt',
+      content: 'x',
+    });
+    expect(editor.asked).toEqual([]);
+  });
+});