@robota-sdk/agent-tools 3.0.0-beta.79 → 3.0.0-beta.81

package/dist/node/index.js

@@ -1,12 +1,17 @@
-import { chmod, mkdir, readFile, readdir, rename, rm, stat, writeFile } from "node:fs/promises";
-import { basename, dirname, isAbsolute, join, posix, resolve, sep } from "node:path";
-import { ToolExecutionError, ValidationError, logger, resolvePlatformShell, zodToJsonSchema } from "@robota-sdk/agent-core";
-import { spawn } from "node:child_process";
-import { killProcessTree } from "@robota-sdk/agent-process";
-import { z } from "zod";
+import { chmod, mkdir, open, readFile, readdir, rename, rm, stat, writeFile } from "node:fs/promises";
+import { basename, dirname, isAbsolute, join, posix, resolve } from "node:path";
+import { spawn, spawnSync } from "node:child_process";
 import { randomBytes, randomUUID } from "node:crypto";
+import { chmodSync, cpSync, createReadStream, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, readlinkSync, realpathSync, renameSync, rmSync, statSync, symlinkSync, writeFileSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { FunctionTool, PROTECTED_DIRECTORY_NAMES, PROTECTED_FILE_NAMES, TOOL_SEARCH_TOOL_NAME, ToolExecutionError, ValidationError, createBoundedOutput, registerToolPermissionProfile, resolvePlatformShell, splitCommandSegments, subprocessTraceEnvironment, zodToJsonSchema } from "@robota-sdk/agent-core";
+import { z } from "zod";
+import { killProcessTree } from "@robota-sdk/agent-process";
+import { fetchWithEgressPolicy, isPathInside } from "@robota-sdk/agent-core/node";
 import fg from "fast-glob";
 import pLimit from "p-limit";
+import { EventEmitter } from "node:events";
+import { Worker } from "node:worker_threads";
 //#region src/sandbox/e2b-sandbox-client.ts
 var E2BSandboxClient = class {
 	sandbox;
@@ -108,12 +113,42 @@ var InMemorySandboxClient = class {
 	}
 };
 //#endregion
+//#region src/sandbox/containment.ts
+function describeExecutionContainment(client) {
+	if (client === void 0) return "host";
+	return `sandbox-${client.filesystem ?? "separate"}`;
+}
+/** Whether file tools must read and write through the sandbox rather than the host filesystem. */
+function routesFilesThroughSandbox(client) {
+	return describeExecutionContainment(client) === "sandbox-separate";
+}
+//#endregion
+//#region src/sandbox/manifest-enforceability.ts
+/**
+* Refuse a manifest whose security-bearing fields the built-in applicator cannot enforce.
+*
+* Emptiness is what is checked, not presence: `environment: {}` and `permissions: {}` request
+* nothing, so refusing them would fail a caller that asked for no controls at all. `permissions`
+* counts as empty when neither list has an entry — `{ read: [] }` is a declared-but-empty policy,
+* not a policy.
+*/
+function refuseUnenforceableManifestControls(manifest) {
+	const unenforceable = [];
+	if (manifest.environment && Object.keys(manifest.environment).length > 0) unenforceable.push("environment");
+	const permissions = manifest.permissions;
+	const requestsSomething = (value) => Array.isArray(value) ? value.length > 0 : value !== void 0;
+	if (permissions && Object.values(permissions).some(requestsSomething)) unenforceable.push("permissions");
+	if (unenforceable.length === 0) return;
+	throw new Error(`workspace manifest requests ${unenforceable.join(" and ")}, which this sandbox client cannot enforce. The built-in applicator applies entries only. Supply a sandbox client that implements applyManifest and honours these fields, or remove them from the manifest — they were previously accepted and silently ignored, which reported a sandbox policy that was never applied (issue #2027).`);
+}
+//#endregion
 //#region src/sandbox/workspace-manifest.ts
 const DEFAULT_TARGET_ROOT = "/workspace";
 const WINDOWS_ABSOLUTE_PATH_PATTERN = /^[A-Za-z]:[\\/]/;
 const SHELL_QUOTE_PATTERN = /'/g;
 async function applyWorkspaceManifest(sandboxClient, manifest, options = {}) {
 	if (sandboxClient.applyManifest) return sandboxClient.applyManifest(manifest, options);
+	refuseUnenforceableManifestControls(manifest);
 	const targetRoot = normalizeSandboxRoot(options.targetRoot ?? DEFAULT_TARGET_ROOT);
 	const appliedEntries = [];
 	for (const [rawPath, entry] of Object.entries(manifest.entries)) {
@@ -210,8 +245,20 @@ async function runSandboxCommand(sandboxClient, command) {
 function resolveHostSourcePath(source, hostRoot) {
 	return isAbsolute(source) ? resolve(source) : resolve(hostRoot ?? process.cwd(), source);
 }
+/**
+* Remove every trailing `/`, by index scan.
+*
+* Not `replace(/\/+$/, '')`: that run has no start anchor, so the engine retries it from every offset inside the
+* run and each retry re-scans to the end — 3.0 s on a 100 K run (`js/polynomial-redos`, SEC-003). The backslash
+* conversion in {@link normalizeSandboxRoot} manufactures such a run from a Windows-style path.
+*/
+function trimTrailingSlashes(value) {
+	let end = value.length;
+	while (end > 0 && value[end - 1] === "/") end -= 1;
+	return value.slice(0, end);
+}
 function normalizeSandboxRoot(root) {
-	const normalized = root.replace(/\\/g, "/").replace(/\/+$/, "");
+	const normalized = trimTrailingSlashes(root.replace(/\\/g, "/"));
 	if (!normalized.startsWith("/")) throw new Error("workspace manifest targetRoot must be an absolute sandbox path");
 	return normalized.length === 0 ? "/" : normalized;
 }
@@ -227,286 +274,740 @@ function assertUnreachable(value) {
 	throw new Error(`unsupported workspace manifest entry: ${JSON.stringify(value)}`);
 }
 //#endregion
-//#region src/registry/tool-registry.ts
+//#region src/sandbox/os-sandbox-policy.ts
 /**
-* Tool registry implementation
-* Manages tool registration, validation, and retrieval
+* What an OS-level sandbox lets a command touch, written once per backend (issue #3082).
+*
+* The same policy becomes bubblewrap arguments on Linux and a Seatbelt profile on macOS:
+* - the whole filesystem is readable except the `denyRead` paths;
+* - writes are allowed only inside the workspace, the temporary directories and `allowWrite`;
+* - inside the workspace, the files that configure git, the agent, MCP servers and shells stay
+*   read-only, so a confined command cannot change what the next session trusts;
+* - the network is either reachable or not. There is no per-domain allowlist: that needs a proxy
+*   process the OS cannot enforce, and a boundary here is only worth what the OS enforces.
 */
-var ToolRegistry = class {
-	tools = /* @__PURE__ */ new Map();
-	/**
-	* Register a tool
-	*/
-	register(tool) {
-		if (!tool.schema?.name) throw new ValidationError("Tool must have a valid schema with name");
-		const toolName = tool.schema.name;
-		this.validateToolSchema(tool.schema);
-		if (this.tools.has(toolName)) logger.warn(`Tool "${toolName}" is already registered, overriding`, {
-			toolName,
-			existingTool: this.tools.get(toolName)?.constructor.name
-		});
-		this.tools.set(toolName, tool);
-		logger.debug(`Tool "${toolName}" registered successfully`, {
-			toolName,
-			toolType: tool.constructor.name,
-			parameters: Object.keys(tool.schema.parameters?.properties || {})
-		});
-	}
-	/**
-	* Unregister a tool
-	*/
-	unregister(name) {
-		if (!this.tools.has(name)) {
-			logger.warn(`Attempted to unregister non-existent tool "${name}"`);
-			return;
+/** An isolated worktree's files are ordinary workspace files. */
+const WRITABLE_INSIDE_PROTECTED = [".robota/worktrees", ".claude/worktrees"];
+function join$1(root, relative) {
+	let end = root.length;
+	while (end > 0 && root[end - 1] === "/") end -= 1;
+	return `${root.slice(0, end)}/${relative}`;
+}
+/**
+* Workspace entries a confined command must not write, relative to the root. `.git` is read-only
+* as a whole: the files that make git run something (config, hooks, `commondir`, per-worktree
+* config) are too many and too easy to add to for a list inside it to stay complete, so git
+* commands that write run unconfined, through the ordinary permission path.
+*/
+function protectedWorkspaceEntries() {
+	return [...PROTECTED_DIRECTORY_NAMES, ...PROTECTED_FILE_NAMES];
+}
+/** The `bwrap` argument vector that runs `command args` under the policy. */
+function bubblewrapArguments(input) {
+	const { policy } = input;
+	const args = [
+		"--ro-bind",
+		"/",
+		"/",
+		"--dev",
+		"/dev",
+		"--proc",
+		"/proc"
+	];
+	for (const path of [
+		policy.root,
+		...policy.tempDirectories,
+		...policy.allowWrite
+	]) args.push("--bind-try", path, path);
+	for (const entry of protectedWorkspaceEntries()) {
+		const path = join$1(policy.root, entry);
+		if (input.exists(path)) args.push("--ro-bind", path, path);
+	}
+	for (const entry of WRITABLE_INSIDE_PROTECTED) {
+		const path = join$1(policy.root, entry);
+		if (!input.exists(path)) continue;
+		args.push("--bind", path, path);
+		for (const name of input.listDirectory(path)) {
+			const gitFile = join$1(path, `${name}/.git`);
+			if (input.exists(gitFile)) args.push("--ro-bind", gitFile, gitFile);
 		}
-		this.tools.delete(name);
-		logger.debug(`Tool "${name}" unregistered successfully`);
 	}
-	/**
-	* Get tool by name
-	*/
-	get(name) {
-		return this.tools.get(name);
+	for (const hidden of policy.denyRead) {
+		if (!input.exists(hidden.path)) continue;
+		if (hidden.directory) args.push("--tmpfs", hidden.path);
+		else args.push("--ro-bind", "/dev/null", hidden.path);
 	}
-	/**
-	* Get all registered tools
-	*/
-	getAll() {
-		return Array.from(this.tools.values());
+	if (!policy.network) {
+		if (input.seccompDescriptor === void 0) throw new Error("A sandbox without network needs the Unix-socket seccomp filter.");
+		args.push("--unshare-net", "--seccomp", String(input.seccompDescriptor));
 	}
-	/**
-	* Get tool schemas
-	*/
-	getSchemas() {
-		const tools = this.getAll();
-		logger.debug("[TOOL-FLOW] ToolRegistry.getSchemas() - Tools before schema extraction", {
-			count: tools.length,
-			tools: tools.map((t) => ({
-				name: t.schema?.name ?? "unnamed",
-				hasSchema: !!t.schema,
-				schemaType: typeof t.schema,
-				toolType: t.constructor?.name || "unknown"
-			}))
-		});
-		return this.getAll().map((tool) => tool.schema);
+	args.push("--unshare-pid", "--die-with-parent", "--new-session", "--chdir", input.cwd);
+	args.push("--", input.command);
+	return [...args, ...input.args];
+}
+function regexEscape(path) {
+	return path.replace(/[\\^$.*+?()[\]{}|"]/g, (char) => `\\${char}`);
+}
+function quote(path) {
+	return `"${path.replace(/\\/g, "\\\\").replace(/"/g, "\\\"")}"`;
+}
+/**
+* The Seatbelt profile for `sandbox-exec -p`. Later rules win, so the order below is the policy:
+* deny writes, allow the writable places, deny the protected entries again, reopen worktrees.
+*/
+function seatbeltProfile(policy) {
+	const writable = [
+		policy.root,
+		...policy.tempDirectories,
+		...policy.allowWrite
+	].map((path) => `(subpath ${quote(path)})`).join(" ");
+	const protectedEntries = protectedWorkspaceEntries().map((entry) => {
+		const path = join$1(policy.root, entry);
+		return PROTECTED_FILE_NAMES.includes(entry) ? `(literal ${quote(path)})` : `(subpath ${quote(path)})`;
+	});
+	const worktrees = WRITABLE_INSIDE_PROTECTED.map((entry) => `(subpath ${quote(join$1(policy.root, entry))})`);
+	const pinned = [`(literal ${quote(join$1(policy.root, ".git"))})`, ...WRITABLE_INSIDE_PROTECTED.map((entry) => `(regex #"^${regexEscape(join$1(policy.root, entry))}/[^/]+/\\.git$")`)];
+	const lines = [
+		"(version 1)",
+		"(allow default)",
+		"(deny file-write*)",
+		`(allow file-write* ${writable} (literal "/dev/null") (regex #"^/dev/tty") (regex #"^/dev/fd/"))`,
+		`(deny file-write* ${protectedEntries.join(" ")})`,
+		`(allow file-write* ${worktrees.join(" ")})`,
+		`(deny file-write* ${pinned.join(" ")})`
+	];
+	if (policy.denyRead.length > 0) {
+		const hidden = policy.denyRead.map((entry) => entry.directory ? `(subpath ${quote(entry.path)})` : `(literal ${quote(entry.path)})`);
+		lines.push(`(deny file-read* ${hidden.join(" ")})`);
+	}
+	if (!policy.network) lines.push("(deny network*)");
+	return lines.join("\n");
+}
+//#endregion
+//#region src/sandbox/os-sandbox-seccomp.ts
+/**
+* The seccomp filter bubblewrap loads when a confined command has no network (issue #3082).
+*
+* `--unshare-net` removes every network interface, but a Unix socket is a file: a daemon listening
+* on one outside the sandbox (a container engine, the session bus, an ssh agent) is still reachable
+* through the read-only filesystem, and is a way to run anything on the host. The filter refuses
+* creating an `AF_UNIX` socket, and refuses `io_uring_setup`, which could create one without the
+* `socket` system call. A system call from another ABI (x32, 32-bit compat) is refused whole, since
+* its numbers differ and the checks below would not see it. macOS's Seatbelt `(deny network*)`
+* already covers Unix sockets.
+*/
+const BPF_LD_W_ABS = 32;
+const BPF_JMP_JEQ_K = 21;
+const BPF_JMP_JSET_K = 69;
+const BPF_RET_K = 6;
+const SECCOMP_RET_ALLOW = 2147418112;
+const SECCOMP_RET_ERRNO = 327680;
+const EPERM = 1;
+const EAFNOSUPPORT = 97;
+const AF_UNIX = 1;
+const X32_SYSCALL_BIT = 1073741824;
+/** `struct seccomp_data` offsets. */
+const OFFSET_NR = 0;
+const OFFSET_ARCH = 4;
+const OFFSET_ARG0_LOW = 16;
+const ARCHITECTURES = {
+	x64: {
+		audit: 3221225534,
+		socket: 41,
+		ioUringSetup: 425
+	},
+	arm64: {
+		audit: 3221225655,
+		socket: 198,
+		ioUringSetup: 425
 	}
-	/**
-	* Check if tool exists
-	*/
-	has(name) {
-		return this.tools.has(name);
+};
+function instruction(code, jt, jf, k) {
+	return [
+		code,
+		jt,
+		jf,
+		k
+	];
+}
+/**
+* The filter as bytes `bwrap --seccomp` reads, or `undefined` for a processor architecture it has
+* no system call numbers for — the caller then refuses to confine rather than confine with a gap.
+*/
+function unixSocketSeccompFilter(arch = process.arch) {
+	const target = ARCHITECTURES[arch];
+	if (target === void 0) return void 0;
+	const errno = (code) => SECCOMP_RET_ERRNO | code;
+	const program = [
+		instruction(BPF_LD_W_ABS, 0, 0, OFFSET_ARCH),
+		instruction(BPF_JMP_JEQ_K, 1, 0, target.audit),
+		instruction(BPF_RET_K, 0, 0, errno(EPERM)),
+		instruction(BPF_LD_W_ABS, 0, 0, OFFSET_NR),
+		instruction(BPF_JMP_JSET_K, 0, 1, X32_SYSCALL_BIT),
+		instruction(BPF_RET_K, 0, 0, errno(EPERM)),
+		instruction(BPF_JMP_JEQ_K, 0, 1, target.ioUringSetup),
+		instruction(BPF_RET_K, 0, 0, errno(EPERM)),
+		instruction(BPF_JMP_JEQ_K, 0, 3, target.socket),
+		instruction(BPF_LD_W_ABS, 0, 0, OFFSET_ARG0_LOW),
+		instruction(BPF_JMP_JEQ_K, 0, 1, AF_UNIX),
+		instruction(BPF_RET_K, 0, 0, errno(EAFNOSUPPORT)),
+		instruction(BPF_RET_K, 0, 0, SECCOMP_RET_ALLOW)
+	];
+	const bytes = new Uint8Array(program.length * 8);
+	const view = new DataView(bytes.buffer);
+	program.forEach(([code, jt, jf, k], index) => {
+		view.setUint16(index * 8, code, true);
+		view.setUint8(index * 8 + 2, jt);
+		view.setUint8(index * 8 + 3, jf);
+		view.setUint32(index * 8 + 4, k >>> 0, true);
+	});
+	return bytes;
+}
+//#endregion
+//#region src/sandbox/os-sandbox-client.ts
+/**
+* OS-level confinement of shell commands over the host filesystem (issue #3082): bubblewrap on
+* Linux and WSL2, Seatbelt (`sandbox-exec`) on macOS. Other platforms have no backend; the client
+* reports that instead of pretending.
+*
+* It is a `shared` sandbox client: file tools stay on the host under the path guard, and the shell
+* tool starts the wrapped invocation itself. Settings are live — `/sandbox` changes them for the
+* next command without rebuilding the session.
+*/
+const DEFAULT_OS_SANDBOX_SETTINGS = Object.freeze({
+	enabled: false,
+	autoAllowBashIfSandboxed: true,
+	excludedCommands: [],
+	allowWrite: [],
+	denyRead: [],
+	network: false
+});
+const SEATBELT_EXECUTABLE = "/usr/bin/sandbox-exec";
+function defaultProbe(command, args) {
+	const result = spawnSync(command, [...args], {
+		timeout: 5e3,
+		encoding: "utf8"
+	});
+	if (result.error !== void 0) return {
+		ok: false,
+		detail: result.error.message
+	};
+	const detail = (result.stderr ?? "").trim().split("\n")[0];
+	return result.status === 0 ? { ok: true } : {
+		ok: false,
+		...detail ? { detail } : {}
+	};
+}
+/** Find the platform's backend and check it can actually start a sandbox here. */
+function detectOsSandbox(options = {}) {
+	const platform = options.platform ?? process.platform;
+	const probe = options.probe ?? defaultProbe;
+	if (platform === "linux") {
+		if (unixSocketSeccompFilter(options.arch ?? process.arch) === void 0) return {
+			backend: "bubblewrap",
+			missing: [`a seccomp filter for ${options.arch ?? process.arch} (x64 and arm64 are supported)`]
+		};
+		const check = probe("bwrap", [
+			"--ro-bind",
+			"/",
+			"/",
+			"--dev",
+			"/dev",
+			"--unshare-pid",
+			"true"
+		]);
+		if (check.ok) return {
+			backend: "bubblewrap",
+			executable: "bwrap",
+			missing: []
+		};
+		return {
+			backend: "bubblewrap",
+			missing: [check.detail?.includes("ENOENT") ? "bubblewrap (install the `bubblewrap` package)" : `bubblewrap cannot create a sandbox here${check.detail ? `: ${check.detail}` : ""}`]
+		};
 	}
-	/**
-	* Clear all tools
-	*/
-	clear() {
-		const toolCount = this.tools.size;
-		this.tools.clear();
-		logger.debug(`Cleared ${toolCount} tools from registry`);
+	if (platform === "darwin") {
+		const check = probe(SEATBELT_EXECUTABLE, [
+			"-p",
+			"(version 1)(allow default)",
+			"/usr/bin/true"
+		]);
+		if (check.ok) return {
+			backend: "seatbelt",
+			executable: SEATBELT_EXECUTABLE,
+			missing: []
+		};
+		return {
+			backend: "seatbelt",
+			missing: [`sandbox-exec cannot run${check.detail ? `: ${check.detail}` : ""}`]
+		};
+	}
+	return {
+		missing: [],
+		unsupportedPlatform: platform
+	};
+}
+function realPathOrSelf(path) {
+	try {
+		return realpathSync(path);
+	} catch {
+		return path;
+	}
+}
+function isDirectory(path) {
+	try {
+		return statSync(path).isDirectory();
+	} catch {
+		return false;
+	}
+}
+/** Give the owner read, write and search permission throughout an entry, never following links. */
+function grantOwnerAccess(path) {
+	const stat = lstatSync(path);
+	if (stat.isSymbolicLink()) return;
+	chmodSync(path, stat.mode | 448);
+	if (!stat.isDirectory()) return;
+	for (const name of readdirSync(path)) grantOwnerAccess(`${path}/${name}`);
+}
+function isSymbolicLink(path) {
+	try {
+		return lstatSync(path).isSymbolicLink();
+	} catch {
+		return false;
+	}
+}
+/** The program a shell line starts first — what `excludedCommands` names. */
+function firstProgram(shellCommand) {
+	return shellCommand.trim().split(/\s+/)[0];
+}
+var OsSandboxClient = class {
+	filesystem = "shared";
+	root;
+	availability;
+	homeDirectory;
+	current;
+	inFlight = 0;
+	baseline = [];
+	/** Entries a clean-up could not restore, with the state they must return to. */
+	unresolved = /* @__PURE__ */ new Map();
+	constructor(options) {
+		this.root = realPathOrSelf(options.root);
+		this.availability = options.availability;
+		this.homeDirectory = options.homeDirectory ?? homedir();
+		this.current = {
+			...DEFAULT_OS_SANDBOX_SETTINGS,
+			...options.settings
+		};
+	}
+	status() {
+		return {
+			settings: this.current,
+			availability: this.availability,
+			active: this.current.enabled && this.availability.executable !== void 0
+		};
+	}
+	/** Change the settings for the next command. */
+	configure(settings) {
+		this.current = {
+			...this.current,
+			...settings
+		};
+	}
+	/** Whether `shellCommand` would run confined. */
+	confines(shellCommand) {
+		if (!this.status().active) return false;
+		if (splitCommandSegments(shellCommand).length !== 1) return true;
+		const program = firstProgram(shellCommand);
+		return program === void 0 || !this.current.excludedCommands.includes(program);
+	}
+	autoApproves(shellCommand) {
+		if (!this.current.autoAllowBashIfSandboxed || !this.confines(shellCommand)) return false;
+		if (this.unresolved.size > 0) return false;
+		return !this.protectedEntryStates().some((state) => state.kind === "symlink" && !this.resolvesOutsideWritableWorkspace(state.path));
+	}
+	wrapCommand(invocation, shellCommand) {
+		if (!this.confines(shellCommand)) return invocation;
+		const policy = this.policy();
+		const executable = this.availability.executable;
+		if (this.availability.backend === "seatbelt") return {
+			command: executable,
+			args: [
+				"-p",
+				seatbeltProfile(policy),
+				invocation.command,
+				...invocation.args
+			],
+			cwd: invocation.cwd
+		};
+		const filter = policy.network ? void 0 : unixSocketSeccompFilter();
+		if (!this.protectedEntryStates().some((state) => state.path.endsWith("/.robota") && state.kind === "symlink")) mkdirSync(`${this.root}/.robota`, { recursive: true });
+		const args = bubblewrapArguments({
+			policy,
+			exists: (path) => existsSync(path) && !isSymbolicLink(path),
+			listDirectory: (path) => readdirSync(path),
+			cwd: invocation.cwd,
+			command: invocation.command,
+			args: invocation.args,
+			...filter !== void 0 ? { seccompDescriptor: 3 } : {}
+		});
+		if (this.inFlight === 0) this.baseline = this.protectedEntryStates().map((state) => this.unresolved.get(state.path) ?? state);
+		this.inFlight += 1;
+		let finished = false;
+		return {
+			command: executable,
+			args,
+			cwd: invocation.cwd,
+			...filter !== void 0 ? { inputDescriptors: [filter] } : {},
+			afterExit: () => {
+				if (finished) return void 0;
+				finished = true;
+				this.inFlight -= 1;
+				return this.restoreProtectedEntries(this.baseline);
+			}
+		};
 	}
 	/**
-	* Get tool names
+	* How each protected entry stands before a command: bubblewrap can mount an existing entry
+	* read-only, but not one that does not exist yet, and a symlink it mounts through to its target
+	* while the link itself stays replaceable. Read with `lstat`, so a dangling link is not "missing".
 	*/
-	getToolNames() {
-		return Array.from(this.tools.keys());
+	protectedEntryStates() {
+		return protectedWorkspaceEntries().map((entry) => {
+			const path = `${this.root}/${entry}`;
+			try {
+				return lstatSync(path).isSymbolicLink() ? {
+					path,
+					kind: "symlink",
+					target: readlinkSync(path)
+				} : {
+					path,
+					kind: "present"
+				};
+			} catch {
+				return {
+					path,
+					kind: "missing"
+				};
+			}
+		});
 	}
 	/**
-	* Get tools by pattern
+	* Undo what the command did to protected entries it could reach: one it created where none
+	* existed is moved into `.robota/sandbox-quarantine`, and a symlink it replaced is restored. Moved,
+	* not deleted, so nothing the host wrote meanwhile is lost.
 	*/
-	getToolsByPattern(pattern) {
-		const regex = typeof pattern === "string" ? new RegExp(pattern) : pattern;
-		return this.getAll().filter((tool) => regex.test(tool.schema.name));
+	/** Whether a path's real location is under the read-only mounts: not the workspace, temp or `allowWrite`. */
+	resolvesOutsideWritableWorkspace(path) {
+		let real;
+		try {
+			real = realpathSync(path);
+		} catch {
+			return false;
+		}
+		const policy = this.policy();
+		return ![
+			policy.root,
+			...policy.tempDirectories,
+			...policy.allowWrite
+		].some((area) => real === area || real.startsWith(`${area}/`));
 	}
 	/**
-	* Get tool count
+	* Never throws: this runs as the command's process closes, and an exception there would take the
+	* host down and leave the entry in place. The quarantine is outside the workspace, under the
+	* user's `~/.robota`, where the command cannot reach it; what cannot be moved there is removed.
 	*/
-	size() {
-		return this.tools.size;
+	restoreProtectedEntries(before) {
+		const quarantine = `${this.quarantineRoot(before)}/${Date.now()}-${randomUUID()}`;
+		const notes = [];
+		for (const state of before) {
+			if (state.kind === "present") continue;
+			try {
+				const now = this.protectedEntryStates().find((entry) => entry.path === state.path);
+				if (state.kind === "missing" && now.kind === "missing") {
+					this.unresolved.delete(state.path);
+					continue;
+				}
+				if (state.kind === "symlink" && now.kind === "symlink" && now.target === state.target) {
+					this.unresolved.delete(state.path);
+					continue;
+				}
+				if (now.kind !== "missing") notes.push(this.setAside(state.path, quarantine));
+				if (state.kind === "symlink") symlinkSync(state.target, state.path);
+				this.unresolved.delete(state.path);
+			} catch (error) {
+				this.unresolved.set(state.path, state);
+				notes.push(`could not restore ${state.path} (${error instanceof Error ? error.message : String(error)}); commands will ask until it is removed`);
+			}
+		}
+		if (notes.length === 0) return void 0;
+		return `[sandbox] A confined command may not create or replace git, agent, MCP or shell configuration: ${notes.join("; ")}.`;
 	}
 	/**
-	* Validate tool schema
+	* Where set-aside entries go: the workspace's own `.robota`, when it was a real directory before
+	* the command — then it was mounted read-only, so the command could not reach it, and a rename
+	* within one filesystem needs no permission inside the entry. Otherwise the user's `~/.robota`.
+	* Decided from the baseline: what is there now may be the command's own replacement.
 	*/
-	validateToolSchema(schema) {
-		if (!schema.name || typeof schema.name !== "string") throw new ValidationError("Tool schema must have a valid name");
-		if (!schema.description || typeof schema.description !== "string") throw new ValidationError("Tool schema must have a description");
-		if (!schema.parameters || typeof schema.parameters !== "object" || schema.parameters === null || Array.isArray(schema.parameters)) throw new ValidationError("Tool schema must have parameters object");
-		if (schema.parameters.type !== "object") throw new ValidationError("Tool parameters type must be \"object\"");
-		if (schema.parameters.properties) for (const propName of Object.keys(schema.parameters.properties)) {
-			const propSchema = schema.parameters.properties[propName];
-			if (!propSchema?.type) throw new ValidationError(`Parameter "${propName}" must have a type`);
-			if (![
-				"string",
-				"number",
-				"boolean",
-				"array",
-				"object"
-			].includes(propSchema.type)) throw new ValidationError(`Parameter "${propName}" has invalid type "${propSchema.type}"`);
-		}
-		if (schema.parameters.required) {
-			const properties = schema.parameters.properties || {};
-			for (const requiredField of schema.parameters.required) if (!properties[requiredField]) throw new ValidationError(`Required parameter "${requiredField}" is not defined in properties`);
+	quarantineRoot(before) {
+		const robota = `${this.root}/.robota`;
+		return before.some((state) => state.path === robota && state.kind === "present") ? `${robota}/sandbox-quarantine` : `${this.homeDirectory}/.robota/sandbox-quarantine`;
+	}
+	setAside(path, quarantine) {
+		const destination = `${quarantine}/${basename(path)}`;
+		mkdirSync(quarantine, { recursive: true });
+		try {
+			renameSync(path, destination);
+		} catch (error) {
+			if (this.inFlight > 0) throw error;
+			grantOwnerAccess(path);
+			if (error.code === "EXDEV") {
+				cpSync(path, destination, {
+					recursive: true,
+					verbatimSymlinks: true
+				});
+				rmSync(path, {
+					recursive: true,
+					force: true
+				});
+			} else renameSync(path, destination);
 		}
+		return `moved ${path} to ${destination}`;
 	}
-};
-//#endregion
-//#region src/implementations/function-tool/parameter-validator.ts
-/**
-* Validate individual parameter type against its schema.
-* Returns an error string if invalid, undefined if valid.
-*/
-function validateParameterType(key, value, schema) {
-	switch (schema["type"]) {
-		case "string":
-			if (typeof value !== "string") return `Parameter "${key}" must be a string, got ${typeof value}`;
-			break;
-		case "number":
-			if (typeof value !== "number" || isNaN(value)) return `Parameter "${key}" must be a number, got ${typeof value}`;
-			break;
-		case "boolean":
-			if (typeof value !== "boolean") return `Parameter "${key}" must be a boolean, got ${typeof value}`;
-			break;
-		case "array":
-			if (!Array.isArray(value)) return `Parameter "${key}" must be an array, got ${typeof value}`;
-			if (schema.items) for (let i = 0; i < value.length; i++) {
-				const itemError = validateParameterType(`${key}[${i}]`, value[i], schema.items);
-				if (itemError) return itemError;
+	/** The policy for the current settings, with every path made absolute and real. */
+	policy() {
+		const absolute = (path) => {
+			const expanded = path === "~" || path.startsWith("~/") ? `${this.homeDirectory}${path.slice(1)}` : path;
+			return realPathOrSelf(isAbsolute(expanded) ? expanded : resolve(this.root, expanded));
+		};
+		const temp = [...new Set([tmpdir(), "/tmp"].filter(existsSync).map(realPathOrSelf))];
+		return {
+			root: this.root,
+			tempDirectories: temp,
+			allowWrite: this.current.allowWrite.map(absolute),
+			denyRead: this.current.denyRead.map((path) => {
+				const resolved = absolute(path);
+				return {
+					path: resolved,
+					directory: isDirectory(resolved)
+				};
+			}),
+			network: this.current.network
+		};
+	}
+	run(command, options = {}) {
+		const shell = resolvePlatformShell();
+		const cwd = options.workingDirectory ?? this.root;
+		const invocation = this.wrapCommand({
+			command: shell.command,
+			args: shell.commandArgs(command),
+			cwd
+		}, command);
+		return new Promise((resolveRun, reject) => {
+			const extra = invocation.inputDescriptors ?? [];
+			let child;
+			try {
+				child = spawn(invocation.command, [...invocation.args], {
+					cwd: invocation.cwd,
+					stdio: [
+						"ignore",
+						"pipe",
+						"pipe",
+						...extra.map(() => "pipe")
+					],
+					...options.timeoutMs !== void 0 ? { timeout: options.timeoutMs } : {}
+				});
+			} catch (error) {
+				invocation.afterExit?.();
+				reject(error instanceof Error ? error : new Error(String(error)));
+				return;
 			}
-			break;
-		case "object":
-			if (typeof value !== "object" || value === null || Array.isArray(value)) return `Parameter "${key}" must be an object, got ${typeof value}`;
-			break;
+			extra.forEach((data, index) => {
+				const stream = child.stdio[index + 3];
+				stream?.on("error", () => void 0);
+				stream?.end(Buffer.from(data));
+			});
+			let stdout = "";
+			let stderr = "";
+			child.stdout?.on("data", (chunk) => stdout += chunk.toString());
+			child.stderr?.on("data", (chunk) => stderr += chunk.toString());
+			child.on("error", (error) => {
+				invocation.afterExit?.();
+				reject(error);
+			});
+			child.on("close", (code) => {
+				const note = invocation.afterExit?.();
+				resolveRun({
+					stdout: note === void 0 ? stdout : `${stdout}\n${note}`,
+					...stderr ? { stderr } : {},
+					exitCode: code ?? 1
+				});
+			});
+		});
 	}
-	if (schema.enum && schema.enum.length > 0) {
-		const enumValues = schema.enum;
-		let isValidEnum = false;
-		for (const enumValue of enumValues) if (value === enumValue) {
-			isValidEnum = true;
-			break;
-		}
-		if (!isValidEnum) return `Parameter "${key}" must be one of: ${enumValues.join(", ")}, got ${value}`;
+	readFile(path) {
+		return Promise.resolve(readFileSync(path, "utf8"));
 	}
+	writeFile(path, content) {
+		writeFileSync(path, content, "utf8");
+		return Promise.resolve();
+	}
+};
+//#endregion
+//#region src/retrieval/repo-map-index.ts
+/** Persisted-schema version — bump when `IRepoMapIndex`'s serialized shape changes incompatibly. */
+const REPO_MAP_INDEX_VERSION = 1;
+/** Parse one corpus file into an index entry. */
+function parseEntry(parser, file) {
+	const parsed = parser.parse(file.path, file.content);
+	return {
+		path: file.path,
+		definitions: parsed.definitions,
+		references: parsed.references
+	};
+}
+/** Parse the whole corpus once into a serializable repo-map index. */
+function buildRepoMapIndex(options) {
+	return {
+		version: 1,
+		entries: options.corpus.map((file) => parseEntry(options.parser, file))
+	};
 }
 /**
-* Collect all validation errors for the given parameters against a schema.
+* Apply corpus changes to a built index INCREMENTALLY (SELFHOST-003 P3): re-parse only the `upserted`
+* files and drop `removed` paths, reusing every unchanged entry. Returns a new index (the input is not
+* mutated). A file present in both `removed` and `upserted` is upserted (re-parse wins); a path repeated
+* within `upserted` is de-duplicated last-wins, so the result always has one entry per path — matching a
+* full rebuild (entry order does not affect ranking). Unchanged entries are REUSED BY REFERENCE; index
+* entries are treated as immutable, so callers must not mutate an entry in place.
 */
-function getValidationErrors(parameters, schemaRequired, schemaProperties, additionalProperties) {
-	const errors = [];
-	for (const field of schemaRequired) if (!(field in parameters)) errors.push(`Missing required parameter: ${field}`);
-	for (const [key, value] of Object.entries(parameters)) {
-		const paramSchema = schemaProperties[key];
-		if (!paramSchema) {
-			if (additionalProperties === true) continue;
-			if (additionalProperties && typeof additionalProperties === "object") {
-				const additionalTypeError = validateParameterType(key, value, additionalProperties);
-				if (additionalTypeError) errors.push(additionalTypeError);
-				continue;
-			}
-			errors.push(`Unknown parameter: ${key}`);
-			continue;
-		}
-		const typeError = validateParameterType(key, value, paramSchema);
-		if (typeError) errors.push(typeError);
-	}
-	return errors;
+function updateRepoMapIndex(index, changes, parser) {
+	const upsertedByPath = new Map((changes.upserted ?? []).map((file) => [file.path, file]));
+	const touched = /* @__PURE__ */ new Set([...changes.removed ?? [], ...upsertedByPath.keys()]);
+	const kept = index.entries.filter((entry) => !touched.has(entry.path));
+	const upserted = [...upsertedByPath.values()].map((file) => parseEntry(parser, file));
+	return {
+		version: index.version,
+		entries: [...kept, ...upserted]
+	};
+}
+/** Serialize a built index to a neutral JSON string for persistence by the surface. */
+function serializeRepoMapIndex(index) {
+	return JSON.stringify(index);
 }
 /**
-* Validate parameters and return a structured result.
+* Restore a built index from its serialized form. Throws on malformed JSON or an unsupported
+* `version` — a stale/incompatible persisted index must be rebuilt, never silently mis-ranked.
 */
-function validateToolParameters(parameters, schemaRequired, schemaProperties, additionalProperties) {
-	const errors = getValidationErrors(parameters, schemaRequired, schemaProperties, additionalProperties);
+function deserializeRepoMapIndex(serialized) {
+	const parsed = JSON.parse(serialized);
+	if (parsed.version !== 1) throw new Error(`Unsupported repo-map index version ${String(parsed.version)} (expected 1); rebuild the index.`);
+	if (!Array.isArray(parsed.entries)) throw new Error("Malformed repo-map index: missing `entries`.");
+	for (const entry of parsed.entries) if (typeof entry?.path !== "string" || !Array.isArray(entry?.definitions) || !Array.isArray(entry?.references)) throw new Error("Malformed repo-map index: a corrupt entry — rebuild the index.");
 	return {
-		isValid: errors.length === 0,
-		errors
+		version: parsed.version,
+		entries: parsed.entries
 	};
 }
 //#endregion
-//#region src/implementations/function-tool.ts
+//#region src/retrieval/repo-map-adapter.ts
 /**
-* Function tool implementation
-* Wraps a JavaScript function as a tool with schema validation
+* SELFHOST-003: neutral repo-map ranking adapter — mirrors `InMemorySandboxClient`.
 *
-* Implements IFunctionTool without extending AbstractTool to avoid
-* circular runtime dependency (tools → agents → tools).
-*/
-var FunctionTool = class {
-	schema;
-	fn;
-	eventService;
-	constructor(schema, fn) {
-		this.schema = schema;
-		this.fn = fn;
-		this.validateConstructorInputs();
-	}
-	/**
-	* Get tool name
-	*/
-	getName() {
-		return this.schema.name;
-	}
-	/**
-	* Set EventService for post-construction injection.
-	* Accepts EventService as-is without transformation.
-	* Caller is responsible for providing properly configured EventService.
-	*/
-	setEventService(eventService) {
-		this.eventService = eventService;
-	}
-	/**
-	* Execute the function tool
-	*/
-	async execute(parameters, context) {
-		const toolName = this.schema.name;
-		if (!this.validate(parameters)) throw new ValidationError(`Invalid parameters for tool "${toolName}": ${getValidationErrors(parameters, this.schema.parameters.required || [], this.schema.parameters.properties || {}, this.schema.parameters.additionalProperties).join(", ")}`);
-		const startTime = Date.now();
-		let result;
-		try {
-			result = await this.fn(parameters, context);
-		} catch (error) {
-			if (error instanceof ToolExecutionError || error instanceof ValidationError) throw error;
-			throw new ToolExecutionError(`Function tool execution failed: ${error instanceof Error ? error.message : String(error)}`, toolName, error instanceof Error ? error : new Error(String(error)), {
-				parameterCount: Object.keys(parameters || {}).length,
-				hasContext: !!context
-			});
-		}
-		const executionTime = Date.now() - startTime;
-		return {
-			success: true,
-			data: result,
-			metadata: {
-				executionTime,
-				toolName,
-				parameters
+* Ranks a corpus of source files by graph centrality relative to the active files / mentioned
+* identifiers, within a token budget. It is a NEUTRAL mechanism: it works on ANY repo given a corpus
+* and an injected source parser — it carries no repo paths and no domain content. The heavy parser is
+* injected as the duck-typed `IRetrievalSourceParser` (like `E2BSandboxClient` duck-types the E2B SDK),
+* and the corpus is supplied from the surface.
+*
+* P2 (index build + persistence): the corpus is parsed ONCE into an `IRepoMapIndex` at construction
+* (or supplied prebuilt/persisted via `{ index }`), so `retrieve()` ranks without re-parsing.
+*
+* Ranking model (aider repo-map style): a definition's score is the weighted number of references to it
+* across the corpus, references FROM an active file weighted higher (personalization), plus a boost for
+* a directly-mentioned identifier. Entries are emitted most-relevant-first, truncated to the budget.
+*/
+/** References from an active file weigh more (personalization toward the current focus). */
+const ACTIVE_FILE_WEIGHT = 3;
+/** A directly-mentioned identifier is a strong relevance signal. */
+const MENTION_BOOST = 5;
+/**
+* Estimate the token cost of one repo-map entry (neutral chars/4 heuristic). Uses the same rendering
+* shape the tool prints (`file:line  kind name`) so the budgeted estimate matches the emitted output.
+*/
+function estimateTokens(symbol) {
+	const line = `${symbol.file}:${symbol.line}  ${symbol.kind} ${symbol.name}`;
+	return Math.max(1, Math.ceil(line.length / 4));
+}
+const symbolKey = (s) => `${s.file}::${s.name}::${s.line}`;
+var RepoMapRetrievalAdapter = class {
+	index;
+	constructor(options) {
+		if (options.index) this.index = options.index;
+		else if (options.parser && options.corpus) this.index = buildRepoMapIndex({
+			parser: options.parser,
+			corpus: options.corpus
+		});
+		else throw new Error("RepoMapRetrievalAdapter requires either { index } or { parser, corpus }.");
+	}
+	async retrieve(request) {
+		return selectWithinBudget(rankSymbols(this.index.entries.map((entry) => ({
+			file: entry.path,
+			parsed: {
+				definitions: entry.definitions,
+				references: entry.references
 			}
-		};
-	}
-	/**
-	* Validate parameters (simple boolean result)
-	*/
-	validate(parameters) {
-		return getValidationErrors(parameters, this.schema.parameters.required || [], this.schema.parameters.properties || {}, this.schema.parameters.additionalProperties).length === 0;
-	}
-	/**
-	* Validate tool parameters with detailed result
-	*/
-	validateParameters(parameters) {
-		return validateToolParameters(parameters, this.schema.parameters.required || [], this.schema.parameters.properties || {}, this.schema.parameters.additionalProperties);
-	}
-	/**
-	* Get tool description
-	*/
-	getDescription() {
-		return this.schema.description;
-	}
-	/**
-	* Validate constructor inputs
-	*/
-	validateConstructorInputs() {
-		if (!this.schema) throw new ValidationError("Tool schema is required");
-		if (!this.fn || typeof this.fn !== "function") throw new ValidationError("Tool function is required and must be a function");
-		if (!this.schema.name) throw new ValidationError("Tool schema must have a name");
+		})), request), request.tokenBudget);
 	}
 };
+/** Index every definition in the corpus by its name (a name may be defined in several files). */
+function indexDefinitions(parsed) {
+	const defsByName = /* @__PURE__ */ new Map();
+	for (const { parsed: file } of parsed) for (const def of file.definitions) {
+		const list = defsByName.get(def.name) ?? [];
+		list.push(def);
+		defsByName.set(def.name, list);
+	}
+	return defsByName;
+}
+/** Score each definition by weighted reference count + personalization + mention boost. */
+function rankSymbols(parsed, request) {
+	const activeFiles = new Set(request.activeFiles ?? []);
+	const mentioned = new Set(request.mentionedIdentifiers ?? []);
+	const defsByName = indexDefinitions(parsed);
+	const scoreByKey = /* @__PURE__ */ new Map();
+	const bump = (s, delta) => {
+		scoreByKey.set(symbolKey(s), (scoreByKey.get(symbolKey(s)) ?? 0) + delta);
+	};
+	for (const { file, parsed: source } of parsed) {
+		const weight = activeFiles.has(file) ? ACTIVE_FILE_WEIGHT : 1;
+		for (const ref of source.references) for (const def of defsByName.get(ref) ?? []) if (def.file !== file) bump(def, weight);
+	}
+	for (const name of mentioned) for (const def of defsByName.get(name) ?? []) bump(def, MENTION_BOOST);
+	const ranked = [];
+	for (const defs of defsByName.values()) for (const def of defs) ranked.push({
+		...def,
+		score: scoreByKey.get(symbolKey(def)) ?? 0,
+		tokens: estimateTokens(def)
+	});
+	ranked.sort((a, b) => b.score - a.score || a.file.localeCompare(b.file) || a.line - b.line || a.name.localeCompare(b.name));
+	return ranked;
+}
+/** Take the most-relevant-first prefix whose cumulative tokens fit the budget. */
+function selectWithinBudget(ranked, tokenBudget) {
+	const symbols = [];
+	let totalTokens = 0;
+	for (const entry of ranked) {
+		if (totalTokens + entry.tokens > tokenBudget) break;
+		symbols.push(entry);
+		totalTokens += entry.tokens;
+	}
+	return {
+		symbols,
+		totalTokens
+	};
+}
+//#endregion
+//#region src/implementations/function-tool.ts
 /**
 * Helper function to create a function tool from a simple function
 */
@@ -520,11 +1021,12 @@ function createFunctionTool(name, description, parameters, fn) {
 /**
 * Helper function to create a function tool from Zod schema
 */
-function createZodFunctionTool(name, description, zodSchema, fn) {
+function createZodFunctionTool(name, description, zodSchema, fn, residency = {}) {
 	const schema = {
 		name,
 		description,
-		parameters: zodToJsonSchema(zodSchema)
+		parameters: zodToJsonSchema(zodSchema),
+		...residency.deferLoading !== void 0 && { deferLoading: residency.deferLoading }
 	};
 	const wrappedFn = async (parameters, context) => {
 		const parseResult = zodSchema.safeParse(parameters);
@@ -535,6 +1037,460 @@ function createZodFunctionTool(name, description, zodSchema, fn) {
 	return new FunctionTool(schema, wrappedFn);
 }
 //#endregion
+//#region src/tool-permission-profiles.ts
+/**
+* What the permission system is told about the tools THIS package defines. CORE-030.
+*
+* The classification used to live in `@robota-sdk/agent-core`'s `permission-mode.ts`, as a matrix
+* keyed on a closed union of product tool names — a vendor-neutral foundation holding a product's
+* tool inventory, two layers below the code that defines it, with nothing coupling the two lists.
+* They drifted: `CodebaseRetrieval` is defined here and the matrix had never heard of it, so a
+* read-only retrieval prompted on every call and was refused outright in plan mode.
+*
+* A tool's own package declares what it does. The foundation decides what each MODE does about that
+* kind of action, and neither restates the other's half.
+*
+* `packages/agent-tools/src/__tests__/tool-permission-profiles.test.ts` asserts that every tool this
+* package produces appears here, so adding a tool without classifying it fails rather than silently
+* inheriting the prompt-on-every-call fallback.
+*/
+/**
+* Every tool this package defines, and what the permission system needs to know about it.
+*
+* `argument.key` is which argument a pattern like `Read(/src/**)` is matched against, and
+* `argument.kind` how (CORE-049: a URL is parsed, a path is segment-wise, a command is a glob). A tool without
+* one cannot be narrowed by an argument pattern at all — the gate treats such a pattern as
+* unevaluable and prompts rather than proceeding, which is why the ones that CAN be narrowed say so.
+*/
+const AGENT_TOOL_PERMISSION_PROFILES = {
+	Read: {
+		argument: {
+			key: "filePath",
+			kind: "path"
+		},
+		riskClass: "inspect"
+	},
+	Glob: {
+		argument: {
+			key: "pattern",
+			kind: "text"
+		},
+		riskClass: "inspect"
+	},
+	Grep: {
+		argument: {
+			key: "pattern",
+			kind: "text"
+		},
+		riskClass: "inspect"
+	},
+	WebFetch: {
+		argument: {
+			key: "url",
+			kind: "url"
+		},
+		riskClass: "inspect"
+	},
+	WebSearch: {
+		argument: {
+			key: "query",
+			kind: "text"
+		},
+		riskClass: "inspect"
+	},
+	CodebaseRetrieval: { riskClass: "inspect" },
+	AskUserQuestion: { riskClass: "inspect" },
+	ToolSearch: {
+		argument: {
+			key: "query",
+			kind: "text"
+		},
+		riskClass: "inspect"
+	},
+	ComputerView: { riskClass: "inspect" },
+	Write: {
+		argument: {
+			key: "filePath",
+			kind: "path"
+		},
+		riskClass: "modify"
+	},
+	Edit: {
+		argument: {
+			key: "filePath",
+			kind: "path"
+		},
+		riskClass: "modify"
+	},
+	Shell: {
+		argument: {
+			key: "command",
+			kind: "command"
+		},
+		riskClass: "execute",
+		aliases: ["Bash"]
+	},
+	Bash: {
+		argument: {
+			key: "command",
+			kind: "command"
+		},
+		riskClass: "execute",
+		aliases: ["Shell"]
+	},
+	Computer: { riskClass: "execute" }
+};
+/**
+* Tell the permission system about every tool this package defines. Idempotent.
+*
+* Not exported: the one caller is the line below. A registration a consumer could choose to skip is
+* a registration that might not happen, which is the state this change exists to leave behind.
+*/
+function registerAgentToolPermissionProfiles() {
+	for (const [toolName, profile] of Object.entries(AGENT_TOOL_PERMISSION_PROFILES)) registerToolPermissionProfile(toolName, profile);
+}
+registerAgentToolPermissionProfiles();
+//#endregion
+//#region src/retrieval/retrieval-tool.ts
+/**
+* SELFHOST-003: the `CodebaseRetrieval` tool — mirrors the `create*Tool(options)` pattern.
+*
+* Composes over the injected `IRetrievalAdapter` (via `IRetrievalToolOptions`). It carries NO corpus and
+* NO domain content itself — the adapter (built from a surface-supplied parser + corpus) does the
+* ranking. With no adapter the tool reports unavailability (it is added to the default set only when an
+* adapter is present — see `createDefaultTools`).
+*/
+/** Default token budget when the caller does not specify one. */
+const DEFAULT_TOKEN_BUDGET = 1e3;
+const RetrievalSchema = z.object({
+	activeFiles: z.array(z.string()).optional().describe("Repo-relative files currently in focus; the map is ranked toward what they reference."),
+	mentionedIdentifiers: z.array(z.string()).optional().describe("Symbol names to bias the map toward (e.g. identifiers named in the task)."),
+	tokenBudget: z.number().int().positive().optional().describe(`Maximum tokens for the returned map (default ${DEFAULT_TOKEN_BUDGET}).`)
+});
+/** Render the ranked symbols as a compact, deterministic repo map. */
+function formatRepoMap(symbols) {
+	return symbols.map((symbol) => `${symbol.file}:${symbol.line}  ${symbol.kind} ${symbol.name}`).join("\n");
+}
+async function retrievalTool(args, options = {}) {
+	if (!options.adapter) return "Codebase retrieval is not available in this session.";
+	const result = await options.adapter.retrieve({
+		...args.activeFiles ? { activeFiles: args.activeFiles } : {},
+		...args.mentionedIdentifiers ? { mentionedIdentifiers: args.mentionedIdentifiers } : {},
+		tokenBudget: args.tokenBudget ?? DEFAULT_TOKEN_BUDGET
+	});
+	if (result.symbols.length === 0) return "No relevant symbols found within the token budget.";
+	return `Most relevant symbols (~${result.totalTokens} tokens):\n${formatRepoMap(result.symbols)}`;
+}
+function createRetrievalTool(options = {}) {
+	return createZodFunctionTool("CodebaseRetrieval", "Retrieve the most relevant slice of the codebase (a ranked repo map of symbols) for the current task, within a token budget. Provide the files you are focused on and/or identifiers named in the task; returns the highest-centrality definitions first.", RetrievalSchema, async (params) => retrievalTool(params, options));
+}
+//#endregion
+//#region src/computer-use/computer-tool.ts
+/**
+* SELFHOST-010: the `ComputerView` (perceive) + `Computer` (act) tools — mirror the `create*Tool(options)`
+* pattern, split along the permission boundary.
+*
+* `createComputerTool({ driver })` registers BOTH tool names over one injected `IComputerDriver`. The split
+* is purely the permission-bearing boundary (the repo's own `Read`(auto)-vs-`Shell`(approve) precedent):
+* - `ComputerView` calls `driver.screenshot()` — a perceive with no action argument (gated `auto` like `Read`).
+* - `Computer` takes a single typed mutating `action`, executes it via `driver.act()`, and returns the
+*   resulting screenshot so the model re-perceives (gated `approve`/`deny` like `Shell`).
+*
+* The typed action union stays WHOLE in the driver contract (`./types.ts`); this file only maps the
+* tool-boundary argument onto it. With no driver the tools report unavailability — they are added to the
+* default set ONLY when a driver is present (adapter-gated; there is NO host fallback — see
+* `createDefaultTools`).
+*/
+const UNAVAILABLE_MESSAGE = "Computer use is not available in this session (no driver injected).";
+const MouseButtonSchema = z.enum([
+	"left",
+	"right",
+	"middle"
+]);
+const PointSchema = z.object({
+	x: z.number(),
+	y: z.number()
+});
+/**
+* The `Computer` action argument. A flat object (not a discriminated union) so it converts to JSON schema
+* — `type` selects the action and the remaining fields are validated per type in {@link buildAction}. The
+* strongly-typed discriminated union lives in the driver contract (`TComputerAction`).
+*/
+const ActionSchema = z.object({
+	type: z.enum([
+		"click",
+		"double_click",
+		"type",
+		"keypress",
+		"scroll",
+		"drag",
+		"wait",
+		"takeover"
+	]).describe("Which action to perform."),
+	x: z.number().optional().describe("X coordinate (click/double_click/scroll)."),
+	y: z.number().optional().describe("Y coordinate (click/double_click/scroll)."),
+	button: MouseButtonSchema.optional().describe("Mouse button (click/double_click/drag)."),
+	text: z.string().optional().describe("Text to type (type)."),
+	keys: z.array(z.string()).optional().describe("Keys to press as a chord (keypress)."),
+	deltaX: z.number().optional().describe("Horizontal wheel delta (scroll)."),
+	deltaY: z.number().optional().describe("Vertical wheel delta (scroll)."),
+	path: z.array(PointSchema).optional().describe("Points to drag through (drag)."),
+	ms: z.number().optional().describe("Milliseconds to wait (wait)."),
+	reason: z.string().optional().describe("Human-readable reason surfaced to the user (takeover).")
+});
+const ComputerSchema = z.object({ action: ActionSchema.describe("The single mutating action to perform.") });
+const ComputerViewSchema = z.object({});
+/** Raised when the tool-boundary action argument is missing fields the action type requires. */
+var InvalidComputerActionError = class extends Error {};
+function requireNumber(value, field, type) {
+	if (typeof value !== "number") throw new InvalidComputerActionError(`Action '${type}' requires numeric '${field}'.`);
+	return value;
+}
+/** Map the flat tool-boundary argument onto the strongly-typed driver action union. */
+function buildAction(args) {
+	const button = args.button;
+	switch (args.type) {
+		case "click": return {
+			type: "click",
+			x: requireNumber(args.x, "x", "click"),
+			y: requireNumber(args.y, "y", "click"),
+			...button ? { button } : {}
+		};
+		case "double_click": return {
+			type: "double_click",
+			x: requireNumber(args.x, "x", "double_click"),
+			y: requireNumber(args.y, "y", "double_click"),
+			...button ? { button } : {}
+		};
+		case "type":
+			if (typeof args.text !== "string") throw new InvalidComputerActionError("Action 'type' requires 'text'.");
+			return {
+				type: "type",
+				text: args.text
+			};
+		case "keypress":
+			if (!args.keys || args.keys.length === 0) throw new InvalidComputerActionError("Action 'keypress' requires non-empty 'keys'.");
+			return {
+				type: "keypress",
+				keys: args.keys
+			};
+		case "scroll": return {
+			type: "scroll",
+			x: requireNumber(args.x, "x", "scroll"),
+			y: requireNumber(args.y, "y", "scroll"),
+			deltaX: requireNumber(args.deltaX, "deltaX", "scroll"),
+			deltaY: requireNumber(args.deltaY, "deltaY", "scroll")
+		};
+		case "drag":
+			if (!args.path || args.path.length < 2) throw new InvalidComputerActionError("Action 'drag' requires a 'path' of at least two points.");
+			return {
+				type: "drag",
+				path: args.path,
+				...button ? { button } : {}
+			};
+		case "wait": return {
+			type: "wait",
+			...typeof args.ms === "number" ? { ms: args.ms } : {}
+		};
+		case "takeover": return {
+			type: "takeover",
+			...args.reason ? { reason: args.reason } : {}
+		};
+		default: {
+			const exhaustive = args.type;
+			throw new InvalidComputerActionError(`Unknown action type: ${String(exhaustive)}`);
+		}
+	}
+}
+/** `ComputerView` — perceive the current surface (returns a screenshot). Gated `auto` like `Read`. */
+async function perceive(options) {
+	if (!options.driver) return JSON.stringify({
+		success: false,
+		error: UNAVAILABLE_MESSAGE
+	});
+	const screenshot = await options.driver.screenshot();
+	return JSON.stringify(screenshot ? {
+		success: true,
+		screenshot
+	} : {
+		success: true,
+		takeover: true
+	});
+}
+/** `Computer` — execute one typed mutating action and return the resulting screenshot. Gated like `Shell`. */
+async function act(args, options) {
+	if (!options.driver) return JSON.stringify({
+		success: false,
+		error: UNAVAILABLE_MESSAGE
+	});
+	let action;
+	try {
+		action = buildAction(args.action);
+	} catch (err) {
+		return JSON.stringify({
+			success: false,
+			error: err instanceof Error ? err.message : String(err)
+		});
+	}
+	const outcome = await options.driver.act(action);
+	const result = {
+		success: true,
+		...outcome.screenshot ? { screenshot: outcome.screenshot } : {},
+		...outcome.takeover ? { takeover: true } : {}
+	};
+	return JSON.stringify(result);
+}
+/** Build the `ComputerView` perceive tool over the injected driver. */
+function createComputerViewTool(options = {}) {
+	return createZodFunctionTool("ComputerView", "Perceive the computer/browser surface: capture and return a screenshot of the current screen so you can reason about what to do next. Read-only — it never changes anything.", ComputerViewSchema, async () => perceive(options));
+}
+/** Build the `Computer` act tool over the injected driver. */
+function createComputerActTool(options = {}) {
+	return createZodFunctionTool("Computer", "Perform one mutating action on the computer/browser surface (click, double_click, type, keypress, scroll, drag, wait, or takeover) and return the resulting screenshot. Use `takeover` to hand control to the human for sensitive input (credentials/payment); perception is paused during a takeover.", ComputerSchema, async (params) => act(params, options));
+}
+/**
+* Create BOTH computer-use tools — `ComputerView` (perceive) and `Computer` (act) — over one injected
+* driver. Mirrors `create*Tool(options)`; returns the pair so the assembly layer can spread them into the
+* default set adapter-gated (see `createDefaultTools`).
+*/
+function createComputerTool(options = {}) {
+	return [createComputerViewTool(options), createComputerActTool(options)];
+}
+//#endregion
+//#region src/computer-use/page-computer-driver.ts
+const DEFAULT_MEDIA_TYPE = "image/png";
+const DEFAULT_WAIT_MS = 500;
+/** Encode raw screenshot bytes to base64 (accepts the page's `Uint8Array` or an already-encoded string). */
+function encodeScreenshot(bytes) {
+	if (typeof bytes === "string") return bytes;
+	return Buffer.from(bytes).toString("base64");
+}
+var PageComputerDriver = class {
+	page;
+	mediaType;
+	defaultWaitMs;
+	suspended = false;
+	constructor(options) {
+		this.page = options.page;
+		this.mediaType = options.mediaType ?? DEFAULT_MEDIA_TYPE;
+		this.defaultWaitMs = options.defaultWaitMs ?? DEFAULT_WAIT_MS;
+	}
+	async capture() {
+		const type = this.mediaType === "image/jpeg" ? "jpeg" : "png";
+		return {
+			data: encodeScreenshot(await this.page.screenshot({ type })),
+			mediaType: this.mediaType
+		};
+	}
+	async wait(ms) {
+		if (this.page.waitForTimeout) {
+			await this.page.waitForTimeout(ms);
+			return;
+		}
+		await new Promise((resolve) => setTimeout(resolve, ms));
+	}
+	async screenshot() {
+		if (this.suspended) return;
+		return this.capture();
+	}
+	async act(action) {
+		if (action.type === "takeover") {
+			await this.beginTakeover(action.reason);
+			return { takeover: true };
+		}
+		if (this.suspended) return { takeover: true };
+		const { mouse, keyboard } = this.page;
+		switch (action.type) {
+			case "click":
+				await mouse.click(action.x, action.y, action.button ? { button: action.button } : void 0);
+				break;
+			case "double_click":
+				await mouse.click(action.x, action.y, {
+					clickCount: 2,
+					...action.button ? { button: action.button } : {}
+				});
+				break;
+			case "type":
+				await keyboard.type(action.text);
+				break;
+			case "keypress":
+				await keyboard.press(action.keys.join("+"));
+				break;
+			case "scroll":
+				await mouse.move(action.x, action.y);
+				await mouse.wheel(action.deltaX, action.deltaY);
+				break;
+			case "drag":
+				await this.performDrag(action);
+				break;
+			case "wait":
+				await this.wait(action.ms ?? this.defaultWaitMs);
+				break;
+		}
+		return { screenshot: await this.capture() };
+	}
+	/** Move the pointer along a multi-point path with the button held (mouse down → moves → up). */
+	async performDrag(action) {
+		if (action.path.length < 2) throw new Error("computer drag requires a path of at least 2 points (start + end)");
+		const { mouse } = this.page;
+		const [first, ...rest] = action.path;
+		const button = action.button ? { button: action.button } : void 0;
+		await mouse.move(first.x, first.y);
+		await mouse.down(button);
+		for (const point of rest) await mouse.move(point.x, point.y);
+		await mouse.up(button);
+	}
+	async beginTakeover(_reason) {
+		this.suspended = true;
+	}
+	async endTakeover() {
+		this.suspended = false;
+	}
+};
+//#endregion
+//#region src/builtins/shell-tool-description.ts
+/**
+* Dedicated-tool routing hints, keyed by the sibling tool's registered name. A hint is only
+* emitted when that sibling is actually part of the registered tool set (NEUT-002) — the
+* description must not route the model to tools that do not exist in a given assembly.
+*/
+const SIBLING_ROUTING_HINTS = [
+	{
+		toolName: "Glob",
+		hint: " - File search: Use Glob (NOT find or ls)"
+	},
+	{
+		toolName: "Grep",
+		hint: " - Content search: Use Grep (NOT grep or rg)"
+	},
+	{
+		toolName: "Read",
+		hint: " - Read files: Use Read (NOT cat/head/tail)"
+	},
+	{
+		toolName: "Edit",
+		hint: " - Edit files: Use Edit (NOT sed/awk)"
+	}
+];
+/**
+* Build the OS-aware tool description so the model writes syntax the host shell can run.
+* When `availableTools` is provided, sibling routing hints are restricted to tools in that set;
+* when omitted, the full default hint set is included (default assembly registers all siblings).
+*/
+function buildShellToolDescription(shell, availableTools) {
+	const hints = availableTools ? SIBLING_ROUTING_HINTS.filter((entry) => availableTools.includes(entry.toolName)) : SIBLING_ROUTING_HINTS;
+	const routingBlock = hints.length > 0 ? [`IMPORTANT: Avoid using this tool to run \`find\`, \`grep\`, \`cat\`, \`head\`, \`tail\`, \`sed\`, \`awk\`, or \`echo\` commands. Instead, use the appropriate dedicated tool:`, ...hints.map((entry) => entry.hint)] : [];
+	return [
+		`Executes a command in the host shell and returns its output.`,
+		``,
+		`Active shell: ${shell.label}. ${shell.syntaxHint}`,
+		``,
+		`Each command runs in a fresh shell in workingDirectory (default: the configured working directory); no shell state carries over between calls.`,
+		``,
+		...routingBlock
+	].join("\n");
+}
+//#endregion
 //#region src/builtins/shell-tool.ts
 /**
 * ShellTool — execute a host shell command via child_process.spawn (TERM-008).
@@ -545,35 +1501,36 @@ function createZodFunctionTool(name, description, zodSchema, fn) {
 *
 * Returns an IToolInvocationResult JSON string. A non-zero exit is returned as success:true with
 * exitCode set (the command ran, it just exited non-zero — the LLM decides what to do with that).
+*
+* ## SEC-007 — why `workingDirectory` is NOT path-contained (a deliberate decision, not an omission)
+*
+* `Read`/`Write`/`Edit` are contained by `checkPathWithinCwd`, and SEC-007 extended that to `Glob`
+* and `Grep`. This tool is deliberately excluded, and the reason is what the tool IS: it runs an
+* arbitrary command in a shell. A guard on `cwd` is undone by the first `cd ..` — or by an absolute
+* path in the command itself — so it would constrain nothing an attacker-controlled command cannot
+* trivially step around, while LOOKING like a boundary in the code and in review.
+*
+* That appearance is the actual hazard. SEC-006's R9 lesson was "'the guard is still there' is not a
+* verdict": a check that reads as containment but is not one is worse than no check, because the next
+* reviewer stops asking. The real boundary for this tool is the permission layer (every invocation is
+* permission-gated at call time) and the sandbox seam below — which is why SEC-006 already recorded
+* `js/indirect-command-line-injection` at the spawn site as a false positive on those same grounds.
+*
+* What the containment root DOES do here: it supplies the DEFAULT working directory. Binding a tool
+* to a session root and then silently running its commands in `process.cwd()` was a real defect — an
+* assembly that scoped its file tools to a workspace still ran `Shell` wherever the host process
+* happened to be started.
 */
 /** POSIX children are spawned detached so a process-group kill reaps grandchildren (CORE-023). */
 const SPAWN_DETACHED = process.platform !== "win32";
 const DEFAULT_TIMEOUT_MS$2 = 12e4;
+/** ARCH-056: most bytes retained per stream while the child runs (head); the rest is dropped. */
+const MAX_CAPTURED_OUTPUT_BYTES = 2e6;
 const ShellSchema = z.object({
 	command: z.string().describe("The shell command to execute"),
 	timeout: z.number().optional().describe("Optional timeout in milliseconds (max 600000). Default is 120000 (2 minutes)"),
 	workingDirectory: z.string().optional().describe("Working directory for the command. Defaults to the current working directory")
 });
-/** Build the OS-aware tool description so the model writes syntax the host shell can run. */
-function buildShellToolDescription(shell) {
-	return [
-		`Executes a command in the host shell and returns its output.`,
-		``,
-		`Active shell: ${shell.label}. ${shell.syntaxHint}`,
-		``,
-		`The working directory persists between commands, but shell state does not.`,
-		``,
-		`IMPORTANT: Avoid using this tool to run \`find\`, \`grep\`, \`cat\`, \`head\`, \`tail\`, \`sed\`, \`awk\`, or \`echo\` commands. Instead, use the appropriate dedicated tool:`,
-		` - File search: Use Glob (NOT find or ls)`,
-		` - Content search: Use Grep (NOT grep or rg)`,
-		` - Read files: Use Read (NOT cat/head/tail)`,
-		` - Edit files: Use Edit (NOT sed/awk)`,
-		``,
-		`For simple commands, keep the description brief (5-10 words). For complex commands, include enough context to clarify what the command does.`,
-		``,
-		`Output is limited to 30,000 characters. Longer output will be middle-truncated.`
-	].join("\n");
-}
 /** Run a shell command through the sandbox client, surfacing failures as a structured result. */
 async function runInSandbox(command, timeout, workingDirectory, options) {
 	try {
@@ -600,44 +1557,86 @@ async function runInSandbox(command, timeout, workingDirectory, options) {
 * Run a shell command and return stdout + stderr.
 * Resolves with the IToolInvocationResult JSON string.
 */
-async function runShell(args, options = {}, signal) {
+async function runShell(args, options, shell, signal, traceEnv) {
 	const { command, timeout: rawTimeout = DEFAULT_TIMEOUT_MS$2, workingDirectory } = args;
 	const timeout = Math.min(rawTimeout, 6e5);
-	if (options.sandboxClient) return runInSandbox(command, timeout, workingDirectory, options);
-	const shell = resolvePlatformShell();
-	if (signal?.aborted) return JSON.stringify({
+	const effectiveCwd = workingDirectory ?? options.cwd;
+	if (effectiveCwd === void 0) return JSON.stringify({
 		success: false,
 		output: "",
-		error: "Aborted before start"
+		error: "Shell tool has no working directory: it was constructed without a `cwd` (ARCH-010). This is an assembly bug — the tool would otherwise run in whatever directory the host process was started in."
 	});
+	if (options.sandboxClient && options.sandboxClient.wrapCommand === void 0) return runInSandbox(command, timeout, workingDirectory ?? options.cwd, options);
+	const hostInvocation = {
+		command: shell.command,
+		args: shell.commandArgs(command),
+		cwd: effectiveCwd
+	};
+	const invocation = options.sandboxClient?.wrapCommand?.(hostInvocation, command) ?? hostInvocation;
+	let released = false;
+	const release = () => {
+		if (released) return void 0;
+		released = true;
+		try {
+			return invocation.afterExit?.();
+		} catch (error) {
+			return `[sandbox] clean-up failed: ${error instanceof Error ? error.message : String(error)}`;
+		}
+	};
+	if (signal?.aborted) {
+		release();
+		return JSON.stringify({
+			success: false,
+			output: "",
+			error: "Aborted before start"
+		});
+	}
 	return new Promise((resolve) => {
-		const stdoutChunks = [];
-		const stderrChunks = [];
+		const stdoutOutput = createBoundedOutput({ maxBytes: MAX_CAPTURED_OUTPUT_BYTES });
+		const stderrOutput = createBoundedOutput({ maxBytes: MAX_CAPTURED_OUTPUT_BYTES });
 		let timedOut = false;
 		let settled = false;
-		const child = spawn(shell.command, shell.commandArgs(command), {
-			cwd: workingDirectory ?? process.cwd(),
-			env: process.env,
-			stdio: [
-				"pipe",
-				"pipe",
-				"pipe"
-			],
-			detached: SPAWN_DETACHED
+		let child;
+		try {
+			child = spawn(invocation.command, [...invocation.args], {
+				cwd: invocation.cwd,
+				env: traceEnv === void 0 ? process.env : subprocessTraceEnvironment(process.env, traceEnv),
+				stdio: [
+					"pipe",
+					"pipe",
+					"pipe",
+					...(invocation.inputDescriptors ?? []).map(() => "pipe")
+				],
+				detached: SPAWN_DETACHED
+			});
+		} catch (error) {
+			const note = release();
+			const message = error instanceof Error ? error.message : String(error);
+			resolve(JSON.stringify({
+				success: false,
+				output: note ?? "",
+				error: message
+			}));
+			return;
+		}
+		(invocation.inputDescriptors ?? []).forEach((data, index) => {
+			const stream = child.stdio[index + 3];
+			stream?.on("error", () => void 0);
+			stream?.end(Buffer.from(data));
 		});
 		child.stdin?.end();
-		child.stdout.on("data", (chunk) => {
-			stdoutChunks.push(chunk);
+		child.stdout?.on("data", (chunk) => {
+			stdoutOutput.append(chunk);
 		});
-		child.stderr.on("data", (chunk) => {
-			stderrChunks.push(chunk);
+		child.stderr?.on("data", (chunk) => {
+			stderrOutput.append(chunk);
 		});
 		const timer = setTimeout(() => {
 			timedOut = true;
 			killProcessTree(child, { processGroup: SPAWN_DETACHED });
 			settle({
 				success: false,
-				output: Buffer.concat(stdoutChunks).toString("utf8"),
+				output: stdoutOutput.toString(),
 				error: `Command timed out after ${timeout}ms`
 			});
 		}, timeout);
@@ -652,12 +1651,13 @@ async function runShell(args, options = {}, signal) {
 			killProcessTree(child, { processGroup: SPAWN_DETACHED });
 			settle({
 				success: false,
-				output: Buffer.concat(stdoutChunks).toString("utf8"),
+				output: stdoutOutput.toString(),
 				error: "Aborted"
 			});
 		}
 		signal?.addEventListener("abort", onAbort, { once: true });
 		child.on("error", (err) => {
+			if (child.pid === void 0) release();
 			settle({
 				success: false,
 				output: "",
@@ -665,21 +1665,23 @@ async function runShell(args, options = {}, signal) {
 			});
 		});
 		child.on("close", (code) => {
+			const note = release();
 			if (timedOut) {
 				settle({
 					success: false,
-					output: Buffer.concat(stdoutChunks).toString("utf8"),
+					output: stdoutOutput.toString(),
 					error: `Command timed out after ${timeout}ms`,
 					exitCode: code ?? void 0
 				});
 				return;
 			}
-			const stdout = Buffer.concat(stdoutChunks).toString("utf8");
-			const stderr = Buffer.concat(stderrChunks).toString("utf8");
+			const stdout = stdoutOutput.toString();
+			const stderr = stderrOutput.toString();
 			const exitCode = code ?? 0;
+			const combined = stderr ? `${stdout}\nstderr:\n${stderr}` : stdout;
 			settle({
 				success: true,
-				output: stderr ? `${stdout}\nstderr:\n${stderr}` : stdout,
+				output: note === void 0 ? combined : `${combined}\n${note}`,
 				exitCode
 			});
 		});
@@ -692,38 +1694,96 @@ async function runShell(args, options = {}, signal) {
 * model writes the right syntax regardless of which alias it calls.
 */
 function createHostShellTool(name, options) {
-	return createZodFunctionTool(name, buildShellToolDescription(resolvePlatformShell()), ShellSchema, async (params, context) => {
-		return runShell(params, options, context?.signal);
+	const shell = resolvePlatformShell({ executable: options.shellExecutable });
+	return createZodFunctionTool(name, options.description ?? buildShellToolDescription(shell, options.availableTools), ShellSchema, async (params, context) => {
+		return runShell(params, options, shell, context?.signal, context?.shellTraceEnv);
 	});
 }
 /**
 * Create a `Shell` tool instance — register with the Robota agent tools registry.
 * The description is resolved at creation time for the host's active shell.
 */
-function createShellTool(options = {}) {
+function createShellTool(options) {
 	return createHostShellTool("Shell", options);
 }
 /**
 * Create a `Bash` tool instance — the model-familiar alias of the same OS-aware shell tool.
 */
-function createBashTool(options = {}) {
+function createBashTool(options) {
 	return createHostShellTool("Bash", options);
 }
-/** `Shell` tool instance — register with the Robota agent tools registry. */
-const shellTool = createShellTool();
-/** `Bash` tool instance — model-familiar alias of {@link shellTool}. */
-const bashTool = createBashTool();
 //#endregion
 //#region src/builtins/path-guard.ts
 /**
-* Returns a JSON-serialized IToolInvocationResult error when filePath is outside cwd.
-* Returns undefined when the path is within cwd or cwd is not set.
+* Returns a JSON-serialized IToolInvocationResult error when filePath is outside cwd, or when NO
+* containment root is configured. Returns undefined only when the path is inside a configured root.
+*
+* This sentence used to end "or cwd is not set" — the fail-open default ARCH-010 removed. It sat
+* directly above the two functions that implement the distinction, which is the worst place for a
+* comment to say the opposite of the code.
+*
+* SEC-006: containment is decided on the CANONICAL (symlink-resolved) paths, via the shared
+* `isPathInside` SSOT in agent-core. A purely lexical `resolve()` + `startsWith` comparison let
+* `<cwd>/link/secret` through when `link -> /etc`, because `resolve` does not consult the filesystem
+* and so cannot see a symlink — while the subsequent `readFile`/`writeFile` followed the link out of
+* the sandbox. For `Write`/`Edit` that meant creating files anywhere the process could reach, and
+* since symlinks are ordinary committed git content, pointing the agent at an untrusted clone was
+* enough to arm it.
+*
+* The same defect existed in the CLI's monitor asset server; both now share one implementation,
+* because two containment checks that can disagree are their own defect.
 */
+/**
+* Whether a host path is inside the tool's containment root — the single predicate every builtin
+* asks, whatever it does with the answer.
+*
+* `checkPathWithinCwd` turns a `false` into the tool-result error a tool RETURNS; the enumerating
+* tools (`Glob`, `Grep`) instead SKIP the entry mid-walk and must not fabricate an error per file.
+* Both ask this one question, which asks agent-core's `isPathInside` SSOT — so there is no second
+* containment rule that could disagree with the first (SEC-006's stated defect, SEC-007 keeping it
+* true as the guard's reach widens).
+*
+* `cwd === undefined` means no containment root is configured, and the answer is NO — ARCH-010.
+*
+* This used to return `true` there: with no root, everything was inside it. A guard whose default is
+* "allow" is not a guard, it is a guard that has to be remembered, and the architecture audit found
+* three independent layers that had forgotten. `pack-coding` had already written the consequence into
+* its own source — "file tools constructed with no options carry a DISARMED working-directory guard:
+* their `Read` will happily return `/etc/hostname`" — and the child-process subagent worker called
+* `createDefaultTools()` with no argument, so a subagent got exactly that. Measured, not inferred:
+* before this change a rootless `Read` of `/etc/hostname` returned the file.
+*
+* Refusing instead means a construction site that forgets the root fails loudly on its first file
+* access rather than silently running unconfined. The root is also required by the tool factories now,
+* so reaching this branch at all is an assembly bug — which is why the error says so specifically
+* rather than reporting an ordinary out-of-root path.
+*/
+function isWithinCwd(filePath, cwd) {
+	if (cwd === void 0) return false;
+	return isPathInside(cwd, filePath);
+}
+/**
+* Where a RELATIVE host path the model supplied is anchored: the containment root, never
+* `process.cwd()` (issue #2429). `Read`/`Write`/`Edit` declare `filePath` absolute, but nothing
+* makes the model comply, and `isPathInside` canonicalises a relative candidate against the PROCESS
+* directory — so a relative path was confined to one root and judged against another. Same rule as
+* `resolveSearchRoot` for the enumerating tools. With no root there is nothing to anchor to; the path
+* is returned as written and `checkPathWithinCwd` refuses it (ARCH-010).
+*/
+function resolveHostPath(filePath, cwd) {
+	if (cwd === void 0) return filePath;
+	return resolve(cwd, filePath);
+}
 function checkPathWithinCwd(filePath, cwd) {
-	if (cwd === void 0) return void 0;
-	const resolved = resolve(filePath);
-	const cwdResolved = resolve(cwd);
-	if (resolved !== cwdResolved && !resolved.startsWith(cwdResolved + sep)) {
+	if (cwd === void 0) {
+		const result = {
+			success: false,
+			output: "",
+			error: `Access denied: "${filePath}" cannot be checked because no containment root is configured for this tool. This is an assembly bug, not a path problem — the tool was constructed without a \`cwd\`, so it has no boundary to enforce (ARCH-010).`
+		};
+		return JSON.stringify(result);
+	}
+	if (!isWithinCwd(filePath, cwd)) {
 		const result = {
 			success: false,
 			output: "",
@@ -732,6 +1792,28 @@ function checkPathWithinCwd(filePath, cwd) {
 		return JSON.stringify(result);
 	}
 }
+/**
+* Resolve an LLM-supplied search root for an ENUMERATING tool, and refuse one that escapes (SEC-007).
+*
+* A relative `requested` anchors to the CONTAINMENT ROOT, not to `process.cwd()`: anchoring them to
+* two different directories is how a "contained" search silently starts somewhere else. `error`
+* carries the tool-result JSON to return, or is `undefined` when the root is allowed.
+*
+* With no root there is nothing to anchor to, so this refuses rather than reaching for the process
+* directory (ARCH-010). The previous `cwd ?? process.cwd()` was that reach: harmless once the guard
+* below refuses anyway, but it read as a supported fallback, which is the pattern being removed.
+*/
+function resolveSearchRoot(requested, cwd) {
+	if (cwd === void 0) return {
+		root: "",
+		error: checkPathWithinCwd(requested ?? "", void 0)
+	};
+	const root = requested ? resolve(cwd, requested) : cwd;
+	return {
+		root,
+		error: checkPathWithinCwd(root, cwd)
+	};
+}
 //#endregion
 //#region src/builtins/read-tool.ts
 /**
@@ -740,7 +1822,24 @@ function checkPathWithinCwd(filePath, cwd) {
 * Supports offset/limit for partial reads. Detects binary files and refuses to
 * return their raw bytes. Default limit is 2000 lines.
 */
+const DEFAULT_READ_DESCRIPTION = "Reads a file from the local filesystem.\n\nBy default, reads up to 2000 lines from the beginning of the file. You can optionally specify offset and limit for partial reads.\n\nResults are returned using cat -n format, with line numbers starting at 1.\n\nThe filePath parameter must be an absolute path, not a relative path.";
 const DEFAULT_LIMIT$1 = 2e3;
+const MAX_READ_BYTES = 4 * 1024 * 1024;
+const READ_CHUNK_BYTES$2 = 64 * 1024;
+/** A budget refusal is a hard failure so a workflow cannot treat it as file content. */
+var ReadByteLimitError = class extends ToolExecutionError {
+	boundary;
+	constructor(boundary) {
+		super(`Read ${boundary} exceeds its UTF-8 byte limit`, "Read");
+		this.boundary = boundary;
+	}
+};
+/** Abort is a hard failure; the workflow must not accept a partial read. */
+var ReadCancelledError = class extends ToolExecutionError {
+	constructor() {
+		super("Read cancelled", "Read");
+	}
+};
 const ReadSchema = z.object({
 	filePath: z.string().describe("The absolute path to the file to read"),
 	offset: z.number().optional().describe("The line number to start reading from (1-based). Only provide if the file is too large to read at once"),
@@ -766,25 +1865,49 @@ function formatWithLineNumbers(lines, startLine) {
 	}).join("\n");
 }
 function formatReadResult(filePath, content, startLine, limit) {
-	const allLines = content.split("\n");
-	if (allLines[allLines.length - 1] === "") allLines.pop();
-	const zeroBasedStart = startLine - 1;
-	const selectedLines = allLines.slice(zeroBasedStart, zeroBasedStart + limit);
-	const output = formatWithLineNumbers(selectedLines, startLine);
-	const totalLines = allLines.length;
+	const selectedLines = [];
+	let selectedMinimumBytes = 0;
+	let totalLines = 0;
+	let lineStart = 0;
+	const selectedStart = Math.trunc(startLine - 1);
+	const selectedEnd = Math.trunc(startLine - 1 + limit);
+	while (lineStart < content.length) {
+		const newline = content.indexOf("\n", lineStart);
+		const lineEnd = newline === -1 ? content.length : newline;
+		totalLines++;
+		if (totalLines > selectedStart && totalLines <= selectedEnd) {
+			const line = content.slice(lineStart, lineEnd);
+			selectedMinimumBytes += Buffer.byteLength(line, "utf8") + String(startLine + selectedLines.length).length + 1;
+			if (selectedMinimumBytes > MAX_READ_BYTES) throw new ReadByteLimitError("output");
+			selectedLines.push(line);
+		}
+		if (newline === -1) break;
+		lineStart = newline + 1;
+	}
 	const returnedLines = selectedLines.length;
+	const header = returnedLines < totalLines ? `[File: ${filePath} (lines ${startLine}-${startLine + returnedLines - 1} of ${totalLines})]\n` : `[File: ${filePath} (${totalLines} lines)]\n`;
+	const width = String(startLine + returnedLines - 1).length;
+	let outputBytes = Buffer.byteLength(header, "utf8") + Math.max(0, returnedLines - 1);
+	for (const line of selectedLines) outputBytes += width + 1 + Buffer.byteLength(line, "utf8");
+	if (outputBytes > MAX_READ_BYTES) throw new ReadByteLimitError("output");
 	const result = {
 		success: true,
-		output: (returnedLines < totalLines ? `[File: ${filePath} (lines ${startLine}-${startLine + returnedLines - 1} of ${totalLines})]\n` : `[File: ${filePath} (${totalLines} lines)]\n`) + output
+		output: header + formatWithLineNumbers(selectedLines, startLine)
 	};
 	return JSON.stringify(result);
 }
-async function readFileTool(args, options = {}) {
-	const { filePath, offset, limit = DEFAULT_LIMIT$1 } = args;
+async function readFileTool(args, options) {
+	if (options.signal?.aborted) throw new ReadCancelledError();
+	const { offset, limit = DEFAULT_LIMIT$1 } = args;
+	const filePath = options.sandboxClient ? args.filePath : resolveHostPath(args.filePath, options.cwd);
 	const startLine = offset !== void 0 && offset > 0 ? offset : 1;
 	if (options.sandboxClient) try {
-		return formatReadResult(filePath, await options.sandboxClient.readFile(filePath), startLine, limit);
+		const content = await options.sandboxClient.readFile(filePath);
+		if (options.signal?.aborted) throw new ReadCancelledError();
+		if (Buffer.byteLength(content, "utf8") > MAX_READ_BYTES) throw new ReadByteLimitError("input");
+		return formatReadResult(filePath, content, startLine, limit);
 	} catch (err) {
+		if (err instanceof ReadByteLimitError || err instanceof ReadCancelledError) throw err;
 		const result = {
 			success: false,
 			output: "",
@@ -813,10 +1936,35 @@ async function readFileTool(args, options = {}) {
 		};
 		return JSON.stringify(result);
 	}
-	let buffer;
+	let buffer = Buffer.alloc(0);
+	let binaryFile = false;
 	try {
-		buffer = await readFile(filePath);
+		const handle = await open(filePath, "r");
+		try {
+			const chunks = [];
+			const chunk = Buffer.allocUnsafe(READ_CHUNK_BYTES$2);
+			let bytes = 0;
+			let binaryCheckedBytes = 0;
+			while (bytes <= MAX_READ_BYTES) {
+				if (options.signal?.aborted) throw new ReadCancelledError();
+				const { bytesRead } = await handle.read(chunk, 0, Math.min(chunk.length, 4194305 - bytes), null);
+				if (bytesRead === 0) break;
+				const binaryCheckLength = Math.min(bytesRead, 8192 - binaryCheckedBytes);
+				if (binaryCheckLength > 0 && isBinary(chunk.subarray(0, binaryCheckLength))) {
+					binaryFile = true;
+					break;
+				}
+				binaryCheckedBytes += binaryCheckLength;
+				bytes += bytesRead;
+				if (bytes > MAX_READ_BYTES) throw new ReadByteLimitError("input");
+				chunks.push(Buffer.from(chunk.subarray(0, bytesRead)));
+			}
+			if (!binaryFile) buffer = Buffer.concat(chunks, bytes);
+		} finally {
+			await handle.close();
+		}
 	} catch (err) {
+		if (err instanceof ReadByteLimitError || err instanceof ReadCancelledError) throw err;
 		const result = {
 			success: false,
 			output: "",
@@ -824,7 +1972,8 @@ async function readFileTool(args, options = {}) {
 		};
 		return JSON.stringify(result);
 	}
-	if (isBinary(buffer)) {
+	if (options.signal?.aborted) throw new ReadCancelledError();
+	if (binaryFile) {
 		const result = {
 			success: false,
 			output: "",
@@ -837,25 +1986,30 @@ async function readFileTool(args, options = {}) {
 /**
 * Create a ReadTool instance — register with Robota agent tools registry.
 */
-function createReadTool(options = {}) {
-	return createZodFunctionTool("Read", "Reads a file from the local filesystem.\n\nBy default, reads up to 2000 lines from the beginning of the file. You can optionally specify offset and limit for partial reads.\n\nResults are returned using cat -n format, with line numbers starting at 1.\n\nThe file_path parameter must be an absolute path, not a relative path.", ReadSchema, async (params) => {
+function createReadTool(options) {
+	return createZodFunctionTool("Read", options.description ?? DEFAULT_READ_DESCRIPTION, ReadSchema, async (params) => {
 		return readFileTool(params, options);
 	});
 }
-/**
-* ReadTool instance — register with Robota agent tools registry.
-*/
-const readTool = createReadTool();
 //#endregion
 //#region src/builtins/atomic-file-write.ts
 const TEMP_RANDOM_BYTES = 6;
 const PRESERVED_MODE_BITS = 4095;
 const MISSING_FILE_ERROR_CODE = "ENOENT";
+/**
+* NEUT-009: this marker used to carry the consumer's product name, so a neutral tool library wrote
+* that name onto every temporary file it created — inherited by any other product built on it. The
+* marker now says what the file IS, which is all it was ever for.
+*
+* The product name is not quoted here either: the ratchet counts prose, deliberately, because a
+* library whose comments teach the product's layout is coupled to it just as firmly.
+*/
+const TEMP_MARKER = ".atomic-tmp-";
 function createTempFilePath(filePath) {
 	const dir = dirname(filePath);
 	const name = basename(filePath);
 	const suffix = randomBytes(TEMP_RANDOM_BYTES).toString("hex");
-	return join(dir, `.${name}.robota-tmp-${process.pid}-${Date.now()}-${suffix}`);
+	return join(dir, `.${name}${TEMP_MARKER}${process.pid}-${Date.now()}-${suffix}`);
 }
 async function readExistingMode(filePath) {
 	try {
@@ -886,12 +2040,14 @@ async function atomicWriteUtf8File(filePath, content) {
 /**
 * WriteTool — write content to a file, auto-creating parent directories.
 */
+const DEFAULT_WRITE_DESCRIPTION = "Writes a file to the local filesystem. This will overwrite an existing file if one exists.\n\nPrefer the Edit tool for modifying existing files — it only sends the changed text. Use this tool to create new files or for complete rewrites.\n\nParent directories are created automatically when missing.";
 const WriteSchema = z.object({
 	filePath: z.string().describe("The absolute path to the file to write"),
 	content: z.string().describe("The content to write to the file")
 });
-async function writeFileTool(args, options = {}) {
-	const { filePath, content } = args;
+async function writeFileTool(args, options) {
+	const { content } = args;
+	const filePath = options.sandboxClient ? args.filePath : resolveHostPath(args.filePath, options.cwd);
 	if (!options.sandboxClient) {
 		const pathError = checkPathWithinCwd(filePath, options.cwd);
 		if (pathError !== void 0) return pathError;
@@ -916,15 +2072,11 @@ async function writeFileTool(args, options = {}) {
 /**
 * Create a WriteTool instance — register with Robota agent tools registry.
 */
-function createWriteTool(options = {}) {
-	return createZodFunctionTool("Write", "Writes a file to the local filesystem. This will overwrite an existing file if one exists.\n\nALWAYS prefer the Edit tool for modifying existing files — it only sends the diff. Only use this tool to create new files or for complete rewrites.\n\nNEVER create documentation files (*.md) or README files unless explicitly requested by the user.", WriteSchema, async (params) => {
+function createWriteTool(options) {
+	return createZodFunctionTool("Write", options.description ?? DEFAULT_WRITE_DESCRIPTION, WriteSchema, async (params) => {
 		return writeFileTool(params, options);
 	});
 }
-/**
-* WriteTool instance — register with Robota agent tools registry.
-*/
-const writeTool = createWriteTool();
 //#endregion
 //#region src/builtins/edit-tool.ts
 /**
@@ -933,22 +2085,67 @@ const writeTool = createWriteTool();
 * By default, requires the oldString to appear exactly once in the file
 * (ensuring surgical edits). Pass replaceAll:true to replace all occurrences.
 */
+const DEFAULT_EDIT_DESCRIPTION = "Performs exact string replacements in files.\n\noldString must exactly match the file's current content, including whitespace and indentation — reading the file first (e.g. with a file-read tool) is the reliable way to copy exact text.\n\nThe edit will FAIL if oldString is not unique in the file. Either provide more surrounding context to make it unique, or set replaceAll to change every instance.";
 const EditSchema = z.object({
 	filePath: z.string().describe("The absolute path to the file to modify"),
 	oldString: z.string().describe("The text to replace (must be an exact match of existing content)"),
-	newString: z.string().describe("The text to replace it with (must be different from old_string)"),
-	replaceAll: z.boolean().optional().describe("Replace all occurrences of old_string (default: false). Useful for renaming variables")
+	newString: z.string().describe("The text to replace it with (must be different from oldString)"),
+	replaceAll: z.boolean().optional().describe("Replace all occurrences of oldString (default: false). Useful for renaming variables")
 });
-async function editFileTool(args, options = {}) {
-	const { filePath, oldString, newString, replaceAll = false } = args;
+const MAX_EDIT_FILE_BYTES = 4 * 1024 * 1024;
+const READ_CHUNK_BYTES$1 = 64 * 1024;
+/** Marks a refusal that must not surface a partial or crashed read to the caller. */
+var EditByteLimitError = class extends Error {
+	boundary;
+	constructor(boundary) {
+		super(`Edit ${boundary} exceeds its ${MAX_EDIT_FILE_BYTES}-byte limit`);
+		this.boundary = boundary;
+	}
+};
+/**
+* Read a file as UTF-8 while rejecting as soon as more than `maxBytes` bytes have arrived —
+* before the whole content is materialized. Reading actual bytes off the stream (rather than
+* trusting stat() size) also catches a file that grows after being stat'd, or has no stable
+* size at all (a named pipe).
+*/
+async function readBoundedUtf8File(filePath, maxBytes) {
+	const stream = createReadStream(filePath, { highWaterMark: READ_CHUNK_BYTES$1 });
+	const chunks = [];
+	let bytes = 0;
+	try {
+		for await (const chunk of stream) {
+			const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+			bytes += buffer.length;
+			if (bytes > maxBytes) throw new EditByteLimitError("input");
+			chunks.push(buffer);
+		}
+	} finally {
+		stream.destroy();
+	}
+	return Buffer.concat(chunks, bytes).toString("utf8");
+}
+async function editFileTool(args, options) {
+	const { oldString, newString, replaceAll = false } = args;
+	const filePath = options.sandboxClient ? args.filePath : resolveHostPath(args.filePath, options.cwd);
 	if (!options.sandboxClient) {
 		const pathError = checkPathWithinCwd(filePath, options.cwd);
 		if (pathError !== void 0) return pathError;
 	}
 	let content;
 	try {
-		content = options.sandboxClient ? await options.sandboxClient.readFile(filePath) : await readFile(filePath, "utf8");
+		if (options.sandboxClient) {
+			content = await options.sandboxClient.readFile(filePath);
+			if (Buffer.byteLength(content, "utf8") > MAX_EDIT_FILE_BYTES) throw new EditByteLimitError("input");
+		} else content = await readBoundedUtf8File(filePath, MAX_EDIT_FILE_BYTES);
 	} catch (err) {
+		if (err instanceof EditByteLimitError) {
+			const result = {
+				success: false,
+				output: "",
+				error: `${err.message}: ${filePath}`
+			};
+			return JSON.stringify(result);
+		}
 		const result = {
 			success: false,
 			output: "",
@@ -964,17 +2161,28 @@ async function editFileTool(args, options = {}) {
 		};
 		return JSON.stringify(result);
 	}
-	if (!replaceAll) {
-		if (content.indexOf(oldString) !== content.lastIndexOf(oldString)) {
-			const result = {
-				success: false,
-				output: "",
-				error: `oldString is not unique in file (found ${content.split(oldString).length - 1} occurrences). Provide more context to make it unique, or use replaceAll:true.`
-			};
-			return JSON.stringify(result);
-		}
+	let parts = [];
+	if (replaceAll) parts = content.split(oldString);
+	else if (content.indexOf(oldString) !== content.lastIndexOf(oldString)) {
+		const result = {
+			success: false,
+			output: "",
+			error: `oldString is not unique in file (found ${content.split(oldString).length - 1} occurrences). Provide more context to make it unique, or use replaceAll:true.`
+		};
+		return JSON.stringify(result);
+	}
+	const count = replaceAll ? parts.length - 1 : 1;
+	const oldBytes = Buffer.byteLength(oldString, "utf8");
+	const newBytes = Buffer.byteLength(newString, "utf8");
+	if (Buffer.byteLength(content, "utf8") - count * oldBytes + count * newBytes > MAX_EDIT_FILE_BYTES) {
+		const result = {
+			success: false,
+			output: "",
+			error: `Edit output exceeds its ${MAX_EDIT_FILE_BYTES}-byte limit: ${filePath}`
+		};
+		return JSON.stringify(result);
 	}
-	const updated = replaceAll ? content.split(oldString).join(newString) : content.slice(0, content.indexOf(oldString)) + newString + content.slice(content.indexOf(oldString) + oldString.length);
+	const updated = replaceAll ? parts.join(newString) : content.slice(0, content.indexOf(oldString)) + newString + content.slice(content.indexOf(oldString) + oldString.length);
 	try {
 		if (options.sandboxClient) await options.sandboxClient.writeFile(filePath, updated);
 		else await atomicWriteUtf8File(filePath, updated);
@@ -986,7 +2194,6 @@ async function editFileTool(args, options = {}) {
 		};
 		return JSON.stringify(result);
 	}
-	const count = replaceAll ? content.split(oldString).length - 1 : 1;
 	const matchIdx = content.indexOf(oldString);
 	const startLine = matchIdx >= 0 ? content.substring(0, matchIdx).split("\n").length : 1;
 	const result = {
@@ -999,40 +2206,110 @@ async function editFileTool(args, options = {}) {
 /**
 * Create an EditTool instance — register with Robota agent tools registry.
 */
-function createEditTool(options = {}) {
-	return createZodFunctionTool("Edit", "Performs exact string replacements in files.\n\nYou must use the Read tool at least once before editing. When editing text from Read output, preserve the exact indentation.\n\nThe edit will FAIL if old_string is not unique in the file. Either provide more surrounding context to make it unique, or use replace_all to change every instance.\n\nALWAYS prefer editing existing files over creating new ones.", EditSchema, async (params) => {
+function createEditTool(options) {
+	return createZodFunctionTool("Edit", options.description ?? DEFAULT_EDIT_DESCRIPTION, EditSchema, async (params) => {
 		return editFileTool(params, options);
 	});
 }
+//#endregion
+//#region src/builtins/glob-tool.ts
+/**
+* GlobTool — fast file pattern search using fast-glob.
+*
+* Excludes node_modules and .git by default.
+* Results are sorted by modification time (most recently modified first) among the candidates
+* enumerated before any candidate ceiling was hit (see DEFAULT_MAX_GLOB_CANDIDATES) — ordering is
+* not guaranteed across the full match set when the search tree is larger than that ceiling.
+*
+* SEC-007: when a containment root is configured the enumeration is confined to it. Listing the
+* filesystem is a disclosure in its own right — a sandbox that stops the model reading a file but
+* lets it map everything around that file is not a sandbox.
+*/
+const DEFAULT_MAX_RESULTS = 1e3;
+/**
+* Ceiling on how many raw glob matches are pulled off `fast-glob`'s match STREAM before enumeration
+* stops, independent of `limit`/`DEFAULT_MAX_RESULTS`.
+*
+* `fg(pattern)` (the promise form) materializes every match into memory and only then stats and
+* slices to `limit` — a pattern like `**\/*` under a huge tree allocates and stats the whole match
+* set no matter how small `limit` is. Streaming lets the walk stop as soon as this many CANDIDATES
+* have been seen, so memory and stat fan-out scale with this ceiling, not with the tree.
+*/
+const DEFAULT_MAX_GLOB_CANDIDATES = 5e4;
+const GlobSchema = z.object({
+	pattern: z.string().describe("The glob pattern to match files against (e.g. \"**/*.ts\", \"src/**/*.tsx\")"),
+	path: z.string().optional().describe("The directory to search in. Defaults to the current working directory. Must be a valid directory path if provided"),
+	limit: z.number().optional().describe("Maximum number of results to return (default: 1000). Use a smaller limit to save context space")
+});
+/** Cap on concurrent `stat` calls during the mtime sort, so a large match set cannot storm the FS. */
+const STAT_CONCURRENCY_LIMIT = 100;
+/**
+* Drop every match whose CANONICAL path escapes the containment root, then stat the survivors for the
+* mtime sort, newest first.
+*
+* Containment is decided per RESULT as well as per root (SEC-007): a `..` in the pattern, or an
+* absolute pattern, produces a match the search root never vouched for. Decided canonically through
+* the shared guard — a symlink named `escape` is a plain segment, so no amount of segment validation
+* would catch it.
+*/
+async function containedMatchesByMtime(matches, cwd, containmentRoot) {
+	const limit = pLimit(STAT_CONCURRENCY_LIMIT);
+	return (await Promise.all(matches.map((p) => limit(async () => {
+		const absPath = resolve(cwd, p);
+		if (!isWithinCwd(absPath, containmentRoot)) return void 0;
+		try {
+			return {
+				path: p,
+				mtime: (await stat(absPath)).mtimeMs
+			};
+		} catch {
+			return {
+				path: p,
+				mtime: 0
+			};
+		}
+	})))).filter((entry) => entry !== void 0).sort((a, b) => b.mtime - a.mtime);
+}
 /**
-* EditTool instance — register with Robota agent tools registry.
+* Pull matches off `fast-glob`'s streaming API one at a time, stopping at `maxCandidates` instead of
+* materializing the whole match set (see {@link DEFAULT_MAX_GLOB_CANDIDATES}). Exported for tests that
+* need a smaller ceiling than the real default.
 */
-const editTool = createEditTool();
-//#endregion
-//#region src/builtins/glob-tool.ts
+async function collectGlobMatches(pattern, options, maxCandidates) {
+	const matches = [];
+	let truncated = false;
+	const stream = fg.stream(pattern, options);
+	for await (const entry of stream) {
+		if (matches.length >= maxCandidates) {
+			truncated = true;
+			break;
+		}
+		matches.push(entry);
+	}
+	return {
+		matches,
+		truncated
+	};
+}
 /**
-* GlobTool — fast file pattern search using fast-glob.
-*
-* Excludes node_modules and .git by default.
-* Results are sorted by modification time (most recently modified first).
+* Exported (rather than module-private) so tests can drive it with a `maxCandidates` far smaller than
+* {@link DEFAULT_MAX_GLOB_CANDIDATES} — the real default is too large to exercise cheaply — without
+* adding any test-only knob to the public `createGlobTool` factory or its schema.
 */
-const DEFAULT_MAX_RESULTS = 1e3;
-const GlobSchema = z.object({
-	pattern: z.string().describe("The glob pattern to match files against (e.g. \"**/*.ts\", \"src/**/*.tsx\")"),
-	path: z.string().optional().describe("The directory to search in. Defaults to the current working directory. Must be a valid directory path if provided"),
-	limit: z.number().optional().describe("Maximum number of results to return (default: 1000). Use a smaller limit to save context space")
-});
-async function globFileTool(args) {
+async function globFileTool(args, options, maxCandidates = DEFAULT_MAX_GLOB_CANDIDATES) {
 	const { pattern, path: basePath } = args;
-	const cwd = basePath ? resolve(basePath) : process.cwd();
-	let matches;
+	const containmentRoot = options.cwd;
+	const { root: cwd, error: rootError } = resolveSearchRoot(basePath, containmentRoot);
+	if (rootError) return rootError;
+	let candidates;
 	try {
-		matches = await fg(pattern, {
+		candidates = await collectGlobMatches(pattern, {
 			cwd,
 			ignore: ["**/node_modules/**", "**/.git/**"],
 			dot: true,
-			absolute: false
-		});
+			absolute: false,
+			followSymbolicLinks: false
+		}, maxCandidates);
 	} catch (err) {
 		const result = {
 			success: false,
@@ -1041,63 +2318,39 @@ async function globFileTool(args) {
 		};
 		return JSON.stringify(result);
 	}
-	const limit = pLimit(100);
-	const withMtime = await Promise.all(matches.map((p) => limit(async () => {
-		const absPath = resolve(cwd, p);
-		try {
-			return {
-				path: p,
-				mtime: (await stat(absPath)).mtimeMs
-			};
-		} catch {
-			return {
-				path: p,
-				mtime: 0
-			};
-		}
-	})));
-	withMtime.sort((a, b) => b.mtime - a.mtime);
+	const { matches, truncated: candidatesTruncated } = candidates;
+	const withMtime = await containedMatchesByMtime(matches, cwd, containmentRoot);
 	const maxResults = args.limit ?? DEFAULT_MAX_RESULTS;
 	const totalMatches = withMtime.length;
 	const truncated = totalMatches > maxResults;
 	const sorted = (truncated ? withMtime.slice(0, maxResults) : withMtime).map((f) => f.path);
 	let output = sorted.length > 0 ? sorted.join("\n") : "(no matches)";
 	if (truncated) output += `\n\n[Showing ${maxResults} of ${totalMatches} matches. Use limit parameter to see more.]`;
+	if (candidatesTruncated) output += `\n\n[Candidate search stopped early; the search tree has more matches than this tool scans in one call. Results are ordered among the scanned candidates only — narrow the pattern or path to see the rest.]`;
 	return JSON.stringify({
 		success: true,
 		output
 	});
 }
+const DEFAULT_GLOB_DESCRIPTION = "Fast file pattern matching tool that works with any codebase size.\n\nSupports glob patterns like '**/*.js' or 'src/**/*.ts'. Returns matching file paths sorted by modification time.\n\nUse this tool when you need to find files by name patterns.\n\nDefault limit is 1000 results. Use the limit parameter if you need fewer results to save context space.";
 /**
-* GlobTool instance — register with Robota agent tools registry.
+* Create a GlobTool instance — register with Robota agent tools registry.
 */
-const globTool = createZodFunctionTool("Glob", "Fast file pattern matching tool that works with any codebase size.\n\nSupports glob patterns like '**/*.js' or 'src/**/*.ts'. Returns matching file paths sorted by modification time.\n\nUse this tool when you need to find files by name patterns. When doing an open-ended search that may require multiple rounds, use the Agent tool instead.\n\nDefault limit is 1000 results. Use the limit parameter if you need fewer results to save context space.", GlobSchema, async (params) => {
-	return globFileTool(params);
-});
+function createGlobTool(options) {
+	return createZodFunctionTool("Glob", options.description ?? DEFAULT_GLOB_DESCRIPTION, GlobSchema, async (params) => {
+		return globFileTool(params, options);
+	});
+}
 //#endregion
-//#region src/builtins/grep-tool.ts
+//#region src/builtins/grep-search.ts
 /**
-* GrepTool — recursive regex content search.
-*
-* Supports three output modes:
-* - files_with_matches (default): return only file paths that contain a match
-* - content: return matching lines with optional context lines
-* - count: return per-file match counts as "path:count" rows
+* The `Grep` tool's search internals — file enumeration and per-file matching.
 *
-* headLimit caps the number of result lines; excess is truncated with a marker.
+* Split out of `grep-tool.ts` (SEC-007) when adding containment pushed that file past the
+* anti-monolith limit. The split is by responsibility, not by line count: this module is HOW the
+* search is performed, while `grep-tool.ts` is the tool SURFACE — schema, model-facing description,
+* factory, and the result envelope. Neither half needs to know the other's concerns.
 */
-const GrepSchema = z.object({
-	pattern: z.string().describe("The regular expression pattern to search for in file contents"),
-	path: z.string().optional().describe("File or directory to search in. Defaults to the current working directory"),
-	glob: z.string().optional().describe("Glob pattern to filter files (e.g. \"*.ts\", \"*.{ts,tsx}\"). Only files matching this pattern will be searched"),
-	contextLines: z.number().optional().describe("Number of context lines to show before and after each match. Only applies when outputMode is \"content\". Default: 0"),
-	outputMode: z.enum([
-		"files_with_matches",
-		"content",
-		"count"
-	]).optional().describe("Output mode: \"files_with_matches\" shows only file paths (default), \"content\" shows matching lines with context, \"count\" shows per-file match counts"),
-	headLimit: z.number().int().positive().optional().describe("Maximum number of result lines (file paths, content lines, or count rows) to return. Excess results are truncated with a marker line")
-});
 /** Convert a simple glob to a RegExp for file name filtering. */
 function globToRegex(glob) {
 	const escaped = glob.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*\*/g, ".+").replace(/\*/g, "[^/]*");
@@ -1108,10 +2361,29 @@ function matchesGlob(filename, glob) {
 	if (glob === void 0) return true;
 	return globToRegex(glob).test(filename);
 }
-/** Gather all files under a directory recursively, excluding node_modules/.git. */
-async function collectFiles(dirPath, glob) {
+/**
+* Ceiling on how many directory entries `collectFiles` will `stat` before it stops walking.
+*
+* Without a cap, enumeration and stat fan-out scale with the whole tree under the search root,
+* not with any result limit — a directory with millions of files makes every `Grep` call walk and
+* stat millions of entries before `headLimit` ever gets a chance to truncate the OUTPUT. This bounds
+* the WALK itself.
+*/
+const DEFAULT_MAX_COLLECTED_FILES = 5e4;
+/**
+* Gather files under a directory recursively, excluding node_modules/.git, stopping once `maxFiles`
+* entries have been visited.
+*
+* `containmentRoot` (SEC-007) drops any entry whose CANONICAL path escapes the root, before it is
+* descended into or read. `stat` follows symlinks, so without this a link inside the root pointing
+* out of it made the whole target tree readable — including, for a symlinked FILE, its contents.
+*/
+async function collectFiles(dirPath, glob, containmentRoot, maxFiles = DEFAULT_MAX_COLLECTED_FILES) {
 	const results = [];
+	let visited = 0;
+	let truncated = false;
 	async function walk(current) {
+		if (truncated) return;
 		let entryNames;
 		try {
 			entryNames = await readdir(current);
@@ -1119,8 +2391,15 @@ async function collectFiles(dirPath, glob) {
 			return;
 		}
 		for (const name of entryNames) {
+			if (truncated) return;
 			if (name === "node_modules" || name === ".git") continue;
 			const fullPath = join(current, name);
+			if (!isWithinCwd(fullPath, containmentRoot)) continue;
+			if (visited >= maxFiles) {
+				truncated = true;
+				return;
+			}
+			visited++;
 			let fileStat;
 			try {
 				fileStat = await stat(fullPath);
@@ -1134,10 +2413,13 @@ async function collectFiles(dirPath, glob) {
 		}
 	}
 	await walk(dirPath);
-	return results;
+	return {
+		files: results,
+		truncated
+	};
 }
 /** Search a single file for lines matching the regex. */
-function searchFile(content, filePath, regex, contextLines, outputMode) {
+function searchFile(content, filePath, regex, contextLines, outputMode, maxOutputBytes) {
 	const lines = content.split("\n");
 	const matchingIndices = [];
 	for (let i = 0; i < lines.length; i++) if (regex.test(lines[i])) matchingIndices.push(i);
@@ -1147,23 +2429,229 @@ function searchFile(content, filePath, regex, contextLines, outputMode) {
 	const includedIndices = /* @__PURE__ */ new Set();
 	for (const idx of matchingIndices) for (let c = Math.max(0, idx - contextLines); c <= Math.min(lines.length - 1, idx + contextLines); c++) includedIndices.add(c);
 	const outputLines = [];
+	let outputBytes = 0;
 	const sortedIndices = Array.from(includedIndices).sort((a, b) => a - b);
 	let prevIdx;
+	let matchingCursor = 0;
 	for (const idx of sortedIndices) {
 		if (prevIdx !== void 0 && idx > prevIdx + 1) outputLines.push("--");
 		const lineNum = idx + 1;
-		const marker = matchingIndices.includes(idx) ? ":" : "-";
-		outputLines.push(`${filePath}:${lineNum}${marker}${lines[idx]}`);
+		while (matchingIndices[matchingCursor] < idx) matchingCursor++;
+		const row = `${filePath}:${lineNum}${matchingIndices[matchingCursor] === idx ? ":" : "-"}${lines[idx]}`;
+		outputBytes += Buffer.byteLength(row, "utf8") + 1;
+		if (maxOutputBytes !== void 0 && outputBytes > maxOutputBytes) throw new Error("byte limit");
+		outputLines.push(row);
 		prevIdx = idx;
 	}
 	return outputLines;
 }
-async function grepFileTool(args) {
+//#endregion
+//#region src/builtins/isolated-grep-search.ts
+const BOOTSTRAP = `
+const { parentPort } = require('node:worker_threads');
+const searchFile = ${searchFile.toString()};
+let outputBytes = 0;
+parentPort.on('message', (request) => {
+  try {
+    const regex = new RegExp(request.pattern);
+    const matches = searchFile(request.content, request.filePath, regex, request.contextLines, request.outputMode, 4 * 1024 * 1024);
+    let bytes = 0;
+    for (const match of matches) { bytes += Buffer.byteLength(match, 'utf8') + 1; if (outputBytes + bytes > 4 * 1024 * 1024) throw new Error('byte limit'); }
+    outputBytes += bytes;
+    parentPort.postMessage({ id: request.id, matches });
+  } catch (error) { parentPort.postMessage({ id: request.id, error: error?.message === 'byte limit' ? 'Grep search exceeded its byte limit' : 'Invalid grep regex execution' }); }
+});
+`;
+var GrepProcessWorker = class extends EventEmitter {
+	child = spawn(process.execPath, ["-e", `
+const searchFile = ${searchFile.toString()};
+const readline = require('node:readline');
+let outputBytes = 0;
+readline.createInterface({ input: process.stdin }).on('line', line => {
+  const request = JSON.parse(line);
+  try {
+    const regex = new RegExp(request.pattern);
+    const matches = searchFile(request.content, request.filePath, regex, request.contextLines, request.outputMode, 4 * 1024 * 1024);
+    let bytes = 0;
+    for (const match of matches) { bytes += Buffer.byteLength(match, 'utf8') + 1; if (outputBytes + bytes > 4 * 1024 * 1024) throw new Error('byte limit'); }
+    outputBytes += bytes;
+    process.stdout.write(JSON.stringify({ id: request.id, matches }) + String.fromCharCode(10));
+  } catch (error) { process.stdout.write(JSON.stringify({ id: request.id, error: error?.message === 'byte limit' ? 'Grep search exceeded its byte limit' : 'Invalid grep regex execution' }) + String.fromCharCode(10)); }
+});
+`], {
+		env: {
+			BUN_BE_BUN: "1",
+			...process.env.SystemRoot ? { SystemRoot: process.env.SystemRoot } : {}
+		},
+		cwd: tmpdir(),
+		stdio: "pipe"
+	});
+	closed;
+	constructor() {
+		super();
+		let pending = "";
+		this.child.stdout.setEncoding("utf8");
+		this.child.stdout.on("data", (chunk) => {
+			pending += chunk;
+			if (Buffer.byteLength(pending, "utf8") > 25166848) {
+				this.emit("error");
+				return;
+			}
+			let newline;
+			while ((newline = pending.indexOf("\n")) >= 0) {
+				const line = pending.slice(0, newline);
+				pending = pending.slice(newline + 1);
+				try {
+					this.emit("message", JSON.parse(line));
+				} catch {
+					this.emit("error");
+				}
+			}
+		});
+		this.child.stderr.resume();
+		this.child.on("error", () => this.emit("error"));
+		this.child.stdin.on("error", () => this.emit("error"));
+		this.closed = new Promise((resolve) => {
+			this.child.once("close", () => {
+				this.emit("exit");
+				resolve();
+			});
+		});
+	}
+	postMessage(request) {
+		this.child.stdin.write(JSON.stringify(request) + "\n");
+	}
+	async terminate() {
+		if (this.child.exitCode === null && this.child.signalCode === null) this.child.kill("SIGKILL");
+		await this.closed;
+	}
+};
+/** One worker per grep invocation; a deadline or abort terminates it before the failure is exposed. */
+var IsolatedGrepSearch = class {
+	pattern;
+	signal;
+	worker = process.versions.bun ? new GrepProcessWorker() : new Worker(BOOTSTRAP, {
+		eval: true,
+		execArgv: [],
+		resourceLimits: {
+			maxOldGenerationSizeMb: 128,
+			maxYoungGenerationSizeMb: 32
+		}
+	});
+	pending = /* @__PURE__ */ new Map();
+	nextId = 0;
+	stopped = false;
+	termination;
+	timer;
+	abort = () => {
+		this.stop(/* @__PURE__ */ new Error("Grep search cancelled"));
+	};
+	constructor(pattern, signal) {
+		this.pattern = pattern;
+		this.signal = signal;
+		this.worker.on("message", (message) => {
+			const pending = this.pending.get(message.id);
+			if (!pending || this.stopped) return;
+			this.pending.delete(message.id);
+			if (Array.isArray(message.matches) && message.matches.every((m) => typeof m === "string")) pending.resolve(message.matches);
+			else pending.reject(new Error(message.error ?? "Invalid grep worker response"));
+		});
+		this.worker.on("error", () => {
+			this.stop(/* @__PURE__ */ new Error("Grep search worker failed"));
+		});
+		this.worker.once("exit", () => {
+			this.stop(/* @__PURE__ */ new Error("Grep search worker exited"));
+		});
+		this.timer = setTimeout(() => {
+			this.stop(/* @__PURE__ */ new Error("Grep search timed out"));
+		}, 2e3);
+		signal?.addEventListener("abort", this.abort, { once: true });
+		if (signal?.aborted) this.abort();
+	}
+	search(content, filePath, contextLines, outputMode) {
+		if (this.stopped) return Promise.reject(/* @__PURE__ */ new Error(this.signal?.aborted ? "Grep search cancelled" : "Grep search timed out"));
+		const id = this.nextId++;
+		return new Promise((resolve, reject) => {
+			this.pending.set(id, {
+				resolve,
+				reject
+			});
+			try {
+				this.worker.postMessage({
+					id,
+					content,
+					filePath,
+					pattern: this.pattern,
+					contextLines,
+					outputMode
+				});
+			} catch {
+				this.stop(/* @__PURE__ */ new Error("Grep search worker failed"));
+			}
+		});
+	}
+	async stop(error) {
+		if (this.termination) return this.termination;
+		this.stopped = true;
+		clearTimeout(this.timer);
+		this.signal?.removeEventListener("abort", this.abort);
+		this.termination = (async () => {
+			try {
+				await this.worker.terminate();
+			} catch {}
+			for (const pending of this.pending.values()) pending.reject(error ?? /* @__PURE__ */ new Error("Grep search stopped"));
+			this.pending.clear();
+		})();
+		return this.termination;
+	}
+};
+//#endregion
+//#region src/builtins/grep-tool.ts
+/**
+* GrepTool — recursive regex content search.
+*
+* Supports three output modes:
+* - files_with_matches (default): return only file paths that contain a match
+* - content: return matching lines with optional context lines
+* - count: return per-file match counts as "path:count" rows
+*
+* headLimit caps the number of result lines; excess is truncated with a marker.
+*
+* SEC-007: when a containment root is configured the search is confined to it. Grep is the most
+* disclosing of the file tools — `content` mode returns the matching LINES — so it must be contained
+* at least as strictly as `Read`, which it could otherwise stand in for.
+*/
+const GrepSchema = z.object({
+	pattern: z.string().describe("The regular expression pattern to search for in file contents"),
+	path: z.string().optional().describe("File or directory to search in. Defaults to the current working directory"),
+	glob: z.string().optional().describe("Glob pattern to filter files (e.g. \"*.ts\", \"*.{ts,tsx}\"). Only files matching this pattern will be searched"),
+	contextLines: z.number().optional().describe("Number of context lines to show before and after each match. Only applies when outputMode is \"content\". Default: 0"),
+	outputMode: z.enum([
+		"files_with_matches",
+		"content",
+		"count"
+	]).optional().describe("Output mode: \"files_with_matches\" shows only file paths (default), \"content\" shows matching lines with context, \"count\" shows per-file match counts"),
+	headLimit: z.number().int().positive().optional().describe("Maximum number of result lines (file paths, content lines, or count rows) to return. Excess results are truncated with a marker line")
+});
+/** The matcher consumes one file at a time; keep only a few reads outstanding. */
+const READ_CONCURRENCY_LIMIT = 8;
+const MAX_GREP_FILE_BYTES = 4 * 1024 * 1024;
+const READ_CHUNK_BYTES = 64 * 1024;
+/** A grep isolation failure is a hard tool failure, distinct from ordinary no-match/invalid-input results. */
+var GrepIsolationError = class extends ToolExecutionError {
+	reason;
+	constructor(reason) {
+		super(`Grep search ${reason === "timeout" ? "timed out" : reason === "cancelled" ? "cancelled" : reason === "limit" ? "exceeded its byte limit" : "worker failed"}`, "Grep");
+		this.reason = reason;
+	}
+};
+async function grepFileTool(args, options) {
 	const { pattern, path: searchPath, glob, contextLines = 0, outputMode = "files_with_matches", headLimit } = args;
-	const targetPath = searchPath ? resolve(searchPath) : process.cwd();
-	let regex;
+	const containmentRoot = options.cwd;
+	const { root: targetPath, error: rootError } = resolveSearchRoot(searchPath, containmentRoot);
+	if (rootError) return rootError;
 	try {
-		regex = new RegExp(pattern);
+		new RegExp(pattern);
 	} catch (err) {
 		const result = {
 			success: false,
@@ -1184,51 +2672,124 @@ async function grepFileTool(args) {
 		return JSON.stringify(result);
 	}
 	let files;
+	let filesTruncated = false;
 	if (targetStat.isFile()) files = [targetPath];
-	else files = await collectFiles(targetPath, glob);
-	const allOutputLines = [];
-	for (const filePath of files) {
-		let content;
-		try {
-			const buffer = await readFile(filePath);
-			const checkLen = Math.min(buffer.length, 8192);
-			let hasBinary = false;
-			for (let i = 0; i < checkLen; i++) if (buffer[i] === 0) {
-				hasBinary = true;
-				break;
+	else {
+		const collected = await collectFiles(targetPath, glob, containmentRoot);
+		files = collected.files;
+		filesTruncated = collected.truncated;
+	}
+	const search = new IsolatedGrepSearch(pattern, options.signal);
+	const readAbort = new AbortController();
+	const abortReads = () => readAbort.abort();
+	options.signal?.addEventListener("abort", abortReads, { once: true });
+	if (options.signal?.aborted) abortReads();
+	let perFileMatches;
+	try {
+		if (readAbort.signal.aborted) throw new GrepIsolationError("cancelled");
+		const orderedMatches = new Array(files.length);
+		let nextFile = 0;
+		let failure;
+		const readAndSearch = async (filePath) => {
+			let content;
+			try {
+				if ((await stat(filePath)).size > MAX_GREP_FILE_BYTES) throw new GrepIsolationError("limit");
+				const stream = createReadStream(filePath, {
+					highWaterMark: READ_CHUNK_BYTES,
+					signal: readAbort.signal
+				});
+				const chunks = [];
+				let bytes = 0;
+				try {
+					for await (const chunk of stream) {
+						if (readAbort.signal.aborted) throw new GrepIsolationError("cancelled");
+						const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+						bytes += buffer.length;
+						if (bytes > MAX_GREP_FILE_BYTES) throw new GrepIsolationError("limit");
+						chunks.push(buffer);
+					}
+				} finally {
+					stream.destroy();
+				}
+				const buffer = Buffer.concat(chunks, bytes);
+				const checkLen = Math.min(buffer.length, 8192);
+				let hasBinary = false;
+				for (let i = 0; i < checkLen; i++) if (buffer[i] === 0) {
+					hasBinary = true;
+					break;
+				}
+				if (hasBinary) return [];
+				content = buffer.toString("utf8");
+			} catch (error) {
+				if (error instanceof GrepIsolationError) throw error;
+				if (readAbort.signal.aborted) throw new GrepIsolationError("cancelled");
+				return [];
 			}
-			if (hasBinary) continue;
-			content = buffer.toString("utf8");
-		} catch {
-			continue;
-		}
-		const fileMatches = searchFile(content, filePath, regex, contextLines, outputMode);
-		allOutputLines.push(...fileMatches);
-	}
-	let outputLines = allOutputLines;
+			return search.search(content, filePath, contextLines, outputMode);
+		};
+		const worker = async () => {
+			while (failure === void 0 && nextFile < files.length) {
+				const index = nextFile++;
+				try {
+					orderedMatches[index] = await readAndSearch(files[index]);
+				} catch (error) {
+					if (failure === void 0) {
+						failure = error;
+						readAbort.abort();
+						search.stop(error instanceof Error ? error : /* @__PURE__ */ new Error("Grep search failed"));
+					}
+				}
+			}
+		};
+		await Promise.all(Array.from({ length: Math.min(READ_CONCURRENCY_LIMIT, files.length) }, worker));
+		if (failure !== void 0) throw failure;
+		perFileMatches = orderedMatches;
+	} catch (error) {
+		const message = error instanceof Error ? error.message : "";
+		throw error instanceof GrepIsolationError ? error : new GrepIsolationError(message.includes("timed out") ? "timeout" : message.includes("cancelled") ? "cancelled" : message.includes("byte limit") ? "limit" : "failed");
+	} finally {
+		options.signal?.removeEventListener("abort", abortReads);
+		await search.stop();
+	}
+	let outputBytes = 0;
+	for (const matches of perFileMatches) for (const match of matches) {
+		outputBytes += Buffer.byteLength(match, "utf8") + 1;
+		if (outputBytes > 4 * 1024 * 1024) throw new GrepIsolationError("limit");
+	}
+	let outputLines = perFileMatches.flat();
 	if (headLimit !== void 0 && outputLines.length > headLimit) {
 		const truncatedCount = outputLines.length - headLimit;
 		outputLines = [...outputLines.slice(0, headLimit), `(+${truncatedCount} more results truncated by headLimit)`];
 	}
+	if (filesTruncated) outputLines = [...outputLines, `[File enumeration stopped early; the search tree has more files than this tool scans in one call. Results may be incomplete — narrow the path or glob.]`];
 	const result = {
 		success: true,
 		output: outputLines.length > 0 ? outputLines.join("\n") : "(no matches)"
 	};
 	return JSON.stringify(result);
 }
+/** The registered name of the shell tool this package's default assembly ships (NEUT-002). */
+const DEFAULT_SHELL_TOOL_NAME = "Shell";
+/** Build the default description, referencing the actually-registered shell tool by name. */
+function buildGrepDescription(shellToolName) {
+	return `A powerful search tool built on regex matching.\n\nSupports full regex syntax (e.g., 'log.*Error', 'function\\\\s+\\\\w+'). Filter files with glob parameter (e.g., '*.js', '**/*.tsx').\n\nOutput modes: 'content' shows matching lines with context, 'files_with_matches' shows only file paths (default), 'count' shows per-file match counts.\n\nPrefer this tool over running grep or rg through the ${shellToolName} tool — it returns structured results directly.\n\nUse headLimit to control result size and save context space.`;
+}
 /**
-* GrepTool instance — register with Robota agent tools registry.
+* Create a GrepTool instance — register with Robota agent tools registry.
 */
-const grepTool = createZodFunctionTool("Grep", "A powerful search tool built on regex matching.\n\nSupports full regex syntax (e.g., 'log.*Error', 'function\\\\s+\\\\w+'). Filter files with glob parameter (e.g., '*.js', '**/*.tsx').\n\nOutput modes: 'content' shows matching lines with context, 'files_with_matches' shows only file paths (default), 'count' shows per-file match counts.\n\nUse this tool for ALL search tasks. NEVER invoke grep or rg as a Bash command.\n\nUse headLimit to control result size and save context space.", GrepSchema, async (params) => {
-	return grepFileTool(params);
-});
+function createGrepTool(options) {
+	return createZodFunctionTool("Grep", options.description ?? buildGrepDescription(options.shellToolName ?? DEFAULT_SHELL_TOOL_NAME), GrepSchema, async (params) => {
+		return grepFileTool(params, options);
+	});
+}
 //#endregion
 //#region src/builtins/web-fetch-tool.ts
 /**
 * WebFetchTool — fetch a URL and return its content as text.
 *
-* HTML is stripped to plain text for readability. Uses Node.js native fetch.
-* Output is capped at 30K chars (same as other tools).
+* HTML is stripped to plain text for readability. Fetches through the shared egress boundary
+* (`fetchWithEgressPolicy`, #2026): loopback / private / link-local / metadata destinations are
+* refused, redirects are re-validated, and the response is capped while streaming.
 */
 const DEFAULT_TIMEOUT_MS$1 = 3e4;
 const MAX_RESPONSE_BYTES = 5e6;
@@ -1236,9 +2797,83 @@ const WebFetchSchema = z.object({
 	url: z.string().describe("The URL to fetch"),
 	headers: z.record(z.string()).optional().describe("Optional HTTP headers as key-value pairs")
 });
+/**
+* Remove every `<tag>…</tag>` element — the linear equivalent of `replace(/<tag[\s\S]*?<\/tag>/gi, '')`.
+*
+* The regex form is quadratic: every `<tag` with no closing tag after it rescans to end of input, and the scan
+* then restarts at the next one. `htmlToText`'s input is a **response body from an arbitrary URL**, capped only
+* at {@link MAX_RESPONSE_BYTES} (5 MB) — 5 MB of `<script` would have taken minutes. Because the closing tag is
+* searched forward, its absence at one opener means no later opener can have one either, so the scan stops.
+*
+* Case folding is `[A-Z]`-only, not `toLowerCase()`: `toLowerCase()` can change a string's LENGTH (U+0130
+* lowercases to two code units), which would desynchronise the indices from the original text.
+*/
+function stripElement(html, tag) {
+	const openTag = `<${tag}`;
+	const closeTag = `</${tag}>`;
+	const haystack = html.replace(/[A-Z]/g, (c) => c.toLowerCase());
+	const parts = [];
+	let cursor = 0;
+	for (;;) {
+		const open = haystack.indexOf(openTag, cursor);
+		if (open < 0) break;
+		const close = haystack.indexOf(closeTag, open + openTag.length);
+		if (close < 0) break;
+		parts.push(html.slice(cursor, open));
+		cursor = close + closeTag.length;
+	}
+	parts.push(html.slice(cursor));
+	return parts.join("");
+}
+/**
+* Replace every `<…>` tag with a space — the linear equivalent of `replace(/<[^>]+>/g, ' ')`.
+*
+* Same defect, same input: `[^>]+` cannot cross a `>`, so a `<` with no `>` after it consumed the rest of the
+* document and then backtracked over it, once per `<`. A page of 200 K `<` characters took 12.6 s; the 5 MB the
+* fetch allows would have taken hours. `close === open + 1` reproduces the regex's `+` (a tag body must be at
+* least one character), so a literal `<>` is left in the text exactly as before.
+*/
+function stripTags(html) {
+	const parts = [];
+	let cursor = 0;
+	for (;;) {
+		const open = html.indexOf("<", cursor);
+		if (open < 0) break;
+		const close = html.indexOf(">", open + 1);
+		if (close < 0) break;
+		if (close === open + 1) {
+			parts.push(html.slice(cursor, open + 1));
+			cursor = open + 1;
+			continue;
+		}
+		parts.push(html.slice(cursor, open), " ");
+		cursor = close + 1;
+	}
+	parts.push(html.slice(cursor));
+	return parts.join("");
+}
+/**
+* The character entities {@link htmlToText} decodes, and the single alternation that matches them.
+*
+* SEC-004 (`js/double-escaping`): decoding these by CHAINED `.replace()` calls with `&amp;` first
+* decodes twice. `&amp;lt;` — how a page encodes the literal text `&lt;` so a browser DISPLAYS it —
+* became `&lt;` after the `&amp;` pass and then `<` after the `&lt;` pass, so a page reading
+* `&amp;lt;script&amp;gt;` came back out of a tag-stripping converter as `<script>`. One pass over
+* one alternation decodes each entity exactly once and never rescans its own output, so the decoder
+* is the inverse of the encoder for every input rather than only for singly-encoded ones.
+*/
+const HTML_ENTITIES = {
+	"&amp;": "&",
+	"&lt;": "<",
+	"&gt;": ">",
+	"&quot;": "\"",
+	"&#39;": "'",
+	"&nbsp;": " "
+};
+const HTML_ENTITY_PATTERN = /&(?:amp|lt|gt|quot|nbsp|#39);/g;
 /** Strip HTML tags and decode common entities to produce readable text. */
 function htmlToText(html) {
-	return html.replace(/<script[\s\S]*?<\/script>/gi, "").replace(/<style[\s\S]*?<\/style>/gi, "").replace(/<[^>]+>/g, " ").replace(/&amp;/g, "&").replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&quot;/g, "\"").replace(/&#39;/g, "'").replace(/&nbsp;/g, " ").replace(/\s+/g, " ").trim();
+	return stripTags(stripElement(stripElement(html, "script"), "style")).replace(HTML_ENTITY_PATTERN, (entity) => HTML_ENTITIES[entity]).replace(/\s+/g, " ").trim();
 }
 function classifyFetchError(err) {
 	if (!(err instanceof Error)) return String(err);
@@ -1251,7 +2886,7 @@ function classifyFetchError(err) {
 	if (code === "CERT_HAS_EXPIRED" || code === "UNABLE_TO_VERIFY_LEAF_SIGNATURE") return `Network error: SSL certificate error (${code}). The server's certificate is invalid. Do not retry with the same URL.`;
 	return `Network error: ${err.message} Check that the URL is correct and the server is reachable.`;
 }
-async function runWebFetch(args, signal) {
+async function runWebFetch(args, egress, signal) {
 	const { url, headers } = args;
 	try {
 		new URL(url);
@@ -1264,38 +2899,35 @@ async function runWebFetch(args, signal) {
 		return JSON.stringify(result);
 	}
 	try {
-		const controller = new AbortController();
-		const timeout = setTimeout(() => controller.abort(), DEFAULT_TIMEOUT_MS$1);
-		const fetchSignal = signal ? AbortSignal.any([controller.signal, signal]) : controller.signal;
-		const response = await fetch(url, {
+		const response = await fetchWithEgressPolicy(url, {
 			headers: {
 				"User-Agent": "Robota-CLI/3.0",
 				...headers ?? {}
 			},
-			signal: fetchSignal,
-			redirect: "follow"
-		});
-		clearTimeout(timeout);
+			signal,
+			timeoutMs: DEFAULT_TIMEOUT_MS$1,
+			maxResponseBytes: MAX_RESPONSE_BYTES
+		}, egress.policy, egress.deps);
 		if (!response.ok) {
-			const retryHint = response.status >= 500 ? " The server is temporarily unavailable — retrying may help." : " Do not retry with the same URL.";
+			const { rejection } = response;
 			const result = {
 				success: false,
 				output: "",
-				error: `HTTP ${response.status} ${response.statusText}.${retryHint}`
+				error: rejection.reason === "response_too_large" ? `Response too large (max ${MAX_RESPONSE_BYTES} bytes). Consider fetching a more specific URL or a paginated endpoint.` : `Blocked by egress policy: ${rejection.message} Do not retry with the same URL.`
 			};
 			return JSON.stringify(result);
 		}
-		const contentType = response.headers.get("content-type") ?? "";
-		const buffer = await response.arrayBuffer();
-		if (buffer.byteLength > MAX_RESPONSE_BYTES) {
+		if (response.status < 200 || response.status >= 300) {
+			const retryHint = response.status >= 500 ? " The server is temporarily unavailable — retrying may help." : " Do not retry with the same URL.";
 			const result = {
 				success: false,
 				output: "",
-				error: `Response too large: ${buffer.byteLength} bytes (max ${MAX_RESPONSE_BYTES}). Consider fetching a more specific URL or a paginated endpoint.`
+				error: `HTTP ${response.status} ${response.statusText}.${retryHint}`
 			};
 			return JSON.stringify(result);
 		}
-		let text = new TextDecoder().decode(buffer);
+		const contentType = response.headers.get("content-type") ?? "";
+		let text = new TextDecoder().decode(response.body);
 		if (contentType.includes("html")) text = htmlToText(text);
 		return JSON.stringify({
 			success: true,
@@ -1310,64 +2942,88 @@ async function runWebFetch(args, signal) {
 		return JSON.stringify(result);
 	}
 }
-const webFetchTool = createZodFunctionTool("WebFetch", "Fetch a URL and return its content as text. HTML pages are converted to plain text.", WebFetchSchema, async (params, context) => runWebFetch(params, context?.signal));
+const DEFAULT_WEB_FETCH_DESCRIPTION = "Fetch a URL and return its content as text. HTML pages are converted to plain text.";
+/**
+* Create a WebFetchTool instance — register with Robota agent tools registry.
+*/
+function createWebFetchTool(options = {}) {
+	const egress = options.egress ?? {};
+	return createZodFunctionTool("WebFetch", options.description ?? DEFAULT_WEB_FETCH_DESCRIPTION, WebFetchSchema, async (params, context) => runWebFetch(params, egress, context?.signal));
+}
+/**
+* WebFetchTool instance — register with Robota agent tools registry.
+*/
+const webFetchTool = createWebFetchTool();
+//#endregion
+//#region src/builtins/brave-search-provider.ts
+const BRAVE_SEARCH_ENDPOINT = "https://api.search.brave.com/res/v1/web/search";
+/** Brave caps `count` at 20 per request. */
+const BRAVE_MAX_COUNT = 20;
+/**
+* Create the Brave Search provider. Throws from `search()` when `BRAVE_API_KEY` is not set or
+* the API responds with an error — the tool layer surfaces the message as a structured result.
+*/
+function createBraveSearchProvider() {
+	return { async search({ query, limit }, signal) {
+		const apiKey = process.env["BRAVE_API_KEY"];
+		if (!apiKey) throw new Error("Web search requires BRAVE_API_KEY environment variable for the default Brave Search provider, or inject a custom search provider at the composition root.");
+		const params = new URLSearchParams({
+			q: query,
+			count: String(Math.min(limit, BRAVE_MAX_COUNT))
+		});
+		const response = await fetch(`${BRAVE_SEARCH_ENDPOINT}?${params}`, {
+			headers: {
+				Accept: "application/json",
+				"Accept-Encoding": "gzip",
+				"X-Subscription-Token": apiKey
+			},
+			...signal ? { signal } : {}
+		});
+		if (!response.ok) throw new Error(`Brave Search API error: HTTP ${response.status} ${response.statusText}`);
+		return ((await response.json()).web?.results ?? []).map((r) => ({
+			title: r.title,
+			url: r.url,
+			snippet: r.description
+		}));
+	} };
+}
 //#endregion
 //#region src/builtins/web-search-tool.ts
 /**
 * WebSearchTool — search the web and return results.
 *
-* Uses Brave Search API when BRAVE_API_KEY is set.
-* Returns an error with setup instructions otherwise.
+* Vendor-free tool layer (NEUT-008): composes over the duck-typed `IWebSearchProvider` port.
+* The default provider is the vendor-specific default adapter wired at creation time; a custom
+* provider is injected via `createWebSearchTool({ provider })`. Provider failures (missing
+* configuration, HTTP/network errors) are thrown by the provider and surfaced here as
+* structured error results.
 */
 const DEFAULT_LIMIT = 10;
 const DEFAULT_TIMEOUT_MS = 15e3;
+const DEFAULT_WEB_SEARCH_DESCRIPTION = "Search the web and return results with title, URL, and snippet.";
 const WebSearchSchema = z.object({
 	query: z.string().describe("The search query"),
 	limit: z.number().optional().describe(`Maximum number of results to return (default: ${DEFAULT_LIMIT})`)
 });
-async function runWebSearch(args, signal) {
+async function runWebSearch(args, provider, signal) {
 	const { query, limit = DEFAULT_LIMIT } = args;
-	const apiKey = process.env["BRAVE_API_KEY"];
-	if (!apiKey) return JSON.stringify({
-		success: false,
-		output: "",
-		error: "Web search requires BRAVE_API_KEY environment variable. Get a free API key at https://brave.com/search/api/ (2,000 queries/month free)."
-	});
 	try {
 		const controller = new AbortController();
 		const timeout = setTimeout(() => controller.abort(), DEFAULT_TIMEOUT_MS);
-		const fetchSignal = signal ? AbortSignal.any([controller.signal, signal]) : controller.signal;
-		const params = new URLSearchParams({
-			q: query,
-			count: String(Math.min(limit, 20))
-		});
-		const response = await fetch(`https://api.search.brave.com/res/v1/web/search?${params}`, {
-			headers: {
-				Accept: "application/json",
-				"Accept-Encoding": "gzip",
-				"X-Subscription-Token": apiKey
-			},
-			signal: fetchSignal
-		});
-		clearTimeout(timeout);
-		if (!response.ok) {
+		const searchSignal = signal ? AbortSignal.any([controller.signal, signal]) : controller.signal;
+		try {
+			const results = await provider.search({
+				query,
+				limit
+			}, searchSignal);
 			const result = {
-				success: false,
-				output: "",
-				error: `Brave Search API error: HTTP ${response.status} ${response.statusText}`
+				success: true,
+				output: JSON.stringify(results, null, 2)
 			};
 			return JSON.stringify(result);
+		} finally {
+			clearTimeout(timeout);
 		}
-		const results = ((await response.json()).web?.results ?? []).map((r) => ({
-			title: r.title,
-			url: r.url,
-			snippet: r.description
-		}));
-		const result = {
-			success: true,
-			output: JSON.stringify(results, null, 2)
-		};
-		return JSON.stringify(result);
 	} catch (err) {
 		const result = {
 			success: false,
@@ -1377,7 +3033,17 @@ async function runWebSearch(args, signal) {
 		return JSON.stringify(result);
 	}
 }
-const webSearchTool = createZodFunctionTool("WebSearch", "Search the web and return results with title, URL, and snippet.", WebSearchSchema, async (params, context) => runWebSearch(params, context?.signal));
+/**
+* Create a WebSearchTool instance — register with Robota agent tools registry.
+*/
+function createWebSearchTool(options = {}) {
+	const provider = options.provider ?? createBraveSearchProvider();
+	return createZodFunctionTool("WebSearch", options.description ?? DEFAULT_WEB_SEARCH_DESCRIPTION, WebSearchSchema, async (params, context) => runWebSearch(params, provider, context?.signal));
+}
+/**
+* WebSearchTool instance — register with Robota agent tools registry.
+*/
+const webSearchTool = createWebSearchTool();
 //#endregion
 //#region src/builtins/ask-user-question-tool.ts
 /**
@@ -1471,8 +3137,8 @@ async function askQuestions(args, ask) {
 /**
 * Create an `AskUserQuestion` tool instance — register with the Robota agent tools registry.
 */
-function createAskUserQuestionTool() {
-	return createZodFunctionTool("AskUserQuestion", ASK_USER_QUESTION_DESCRIPTION, AskUserQuestionSchema, async (params, context) => {
+function createAskUserQuestionTool(options = {}) {
+	return createZodFunctionTool("AskUserQuestion", options.description ?? ASK_USER_QUESTION_DESCRIPTION, AskUserQuestionSchema, async (params, context) => {
 		const args = params;
 		const ask = context?.ask;
 		const output = ask ? await askQuestions(args, ask) : {
@@ -1489,6 +3155,156 @@ function createAskUserQuestionTool() {
 /** `AskUserQuestion` tool instance — register with the Robota agent tools registry. */
 const askUserQuestionTool = createAskUserQuestionTool();
 //#endregion
-export { E2BSandboxClient, FunctionTool, InMemorySandboxClient, ToolRegistry, applyWorkspaceManifest, askUserQuestionTool, bashTool, createAskUserQuestionTool, createBashTool, createEditTool, createFunctionTool, createReadTool, createShellTool, createWriteTool, createZodFunctionTool, editTool, globTool, grepTool, readTool, shellTool, validateWorkspaceManifestPath, webFetchTool, webSearchTool, writeTool };
+//#region src/builtins/tool-search-matching.ts
+/** Both vendors default a tool search to five results; so does this one. */
+const DEFAULT_TOOL_SEARCH_LIMIT = 5;
+/**
+* Where a query matched, lowest first — the primary sort key.
+*
+* A tool whose NAME the query names is a better answer than one that merely mentions it in a
+* parameter description, and saying so is what makes "the top five" meaningful once a catalog is
+* large enough for the limit to bite.
+*/
+const RANK_EXACT_NAME = 0;
+const RANK_NAME = 1;
+const RANK_DESCRIPTION = 2;
+const RANK_PARAMETER = 3;
+/** Not a match at all — filtered out rather than ranked last. */
+const RANK_NONE = Number.POSITIVE_INFINITY;
+/** Every parameter name and description in a schema, including nested nodes. */
+function collectParameterText(node, into) {
+	if (node.description !== void 0) into.push(node.description);
+	for (const [name, child] of Object.entries(node.properties ?? {})) {
+		into.push(name);
+		collectParameterText(child, into);
+	}
+	if (node.items !== void 0) collectParameterText(node.items, into);
+	for (const branch of node.anyOf ?? []) collectParameterText(branch, into);
+}
+function rankMatch(schema, query) {
+	const name = schema.name.toLowerCase();
+	if (name === query) return RANK_EXACT_NAME;
+	if (name.includes(query)) return RANK_NAME;
+	if (schema.description.toLowerCase().includes(query)) return RANK_DESCRIPTION;
+	const parameterText = [];
+	collectParameterText(schema.parameters, parameterText);
+	if (parameterText.some((text) => text.toLowerCase().includes(query))) return RANK_PARAMETER;
+	return RANK_NONE;
+}
+/**
+* The tools a query selects, best match first and capped at `limit`.
+*
+* Ordering is total and deterministic: rank first, then name, so two tools that matched the same way
+* never trade places between calls. An empty query string matches nothing rather than everything —
+* "search for nothing" is a question with an empty answer, not a request for the whole catalog.
+*/
+function matchDeferredTools(schemas, query, limit) {
+	const needle = query.trim().toLowerCase();
+	if (needle.length === 0) return [];
+	return schemas.map((schema) => ({
+		schema,
+		rank: rankMatch(schema, needle)
+	})).filter((entry) => entry.rank !== RANK_NONE).sort((a, b) => a.rank - b.rank || (a.schema.name < b.schema.name ? -1 : 1)).slice(0, limit).map((entry) => entry.schema);
+}
+//#endregion
+//#region src/builtins/tool-search-tool.ts
+/**
+* ToolSearch — the model-facing half of client-side tool deferral (CLI-1990 § Solution 4).
+*
+* A tool that declares `deferLoading` is withheld from the request entirely while the tool-search
+* policy is engaged, so the model never sees its schema. This tool is how the model gets it back:
+* it searches the withheld catalog by query, or loads an exact list by name, and the runtime marks
+* the matches loaded — so the NEXT round's `tools` array carries their full definitions and they
+* stay callable for the rest of the session.
+*
+* Deliberately an ordinary function tool rather than a vendor block. Anthropic and OpenAI each ship
+* a server-side tool search, but neither reduces the request payload (the API needs every definition
+* to run the search), Gemini has no equivalent at all, and both vendors document a client-executed
+* search as the portable form. One shape therefore runs everywhere and saves both wire bytes and
+* context tokens.
+*
+* Two results are NOT errors, and the distinction is the contract:
+* - a query that matches nothing returns `{ loaded: [], unavailableSources: [] }` — a normal empty
+*   answer, mirroring the vendor's own empty `tool_references` array;
+* - an unknown entry in `names` throws, naming the entry, and loads nothing — asking for a tool that
+*   does not exist is a mistake to correct, not an empty search.
+*
+* `unavailableSources` is present and empty from day one. MCP-003 (the connection and capability
+* supervisor) fills it with servers that failed or need auth, so a model told "nothing matched" can
+* tell that apart from "the server holding it is down" — without a contract change here.
+*/
+/**
+* The registered name — agent-core's own constant, re-exported under this package's name so the
+* execution layer's unknown-tool remedy and this tool can never name two different things.
+*/
+const TOOL_SEARCH_NAME = TOOL_SEARCH_TOOL_NAME;
+const ToolSearchSchema = z.object({
+	query: z.string().optional().describe("Text matched case-insensitively against each withheld tool's name, description, and its parameters' names and descriptions. An exact tool name is a valid query."),
+	names: z.array(z.string().min(1)).optional().describe("Exact tool names to load, skipping the search. An unknown name is an error naming it."),
+	limit: z.number().int().positive().optional().describe(`Maximum tools to load from a query match (default 5).`)
+});
+const TOOL_SEARCH_DESCRIPTION = [
+	"Load tools whose definitions are withheld from your tool list, so you can call them.",
+	"",
+	"Some tools are deferred: they exist and are callable, but their schemas are not sent to you until",
+	"you load them here. If a capability you need is not in your tool list, search for it before",
+	"concluding it is unavailable — and if a tool call fails as \"deferred and not yet loaded\", load it",
+	"with this tool and call it again.",
+	"",
+	" - query: what you are trying to do (e.g. \"read a spreadsheet\", \"postgres\"). Matched against tool",
+	"   names, descriptions, and parameter names and descriptions. An exact tool name works too.",
+	` - names: load exactly these tools, skipping the search. Unknown names are an error.`,
+	` - limit: how many matches to load (default 5).`,
+	"",
+	"The result lists what is now loaded; those tools appear in your tool list from your next turn and",
+	"stay available. A query that matches nothing returns an empty list — that is a normal answer, not",
+	"a failure. `unavailableSources` names any tool source that could not be consulted."
+].join("\n");
+/**
+* The catalog the runtime injects, or a thrown wiring error.
+*
+* Its absence is not a runtime condition to degrade around: `ToolExecutionService` attaches this
+* port to every tool call it issues, so a missing one means this tool was invoked outside the
+* execution loop. Guessing an empty catalog there would report "nothing matched" for a search that
+* was never actually run.
+*/
+function requireCatalog(context) {
+	const catalog = context?.deferredTools;
+	if (!catalog) throw new Error(`${TOOL_SEARCH_NAME} requires the deferred-tool catalog, which the execution runtime injects; it was not present, so this tool was called outside the agent execution loop.`);
+	return catalog;
+}
+/** Which schemas this call loads: the exact `names`, else the query's ranked matches. */
+function selectTools(args, catalog) {
+	if (args.names !== void 0) return catalog.loadDeferredTools(args.names);
+	if (args.query === void 0) throw new Error(`${TOOL_SEARCH_NAME} needs either "query" to search for tools or "names" to load exact ones.`);
+	const matches = matchDeferredTools(catalog.listDeferredTools(), args.query, args.limit ?? 5);
+	return catalog.loadDeferredTools(matches.map((schema) => schema.name));
+}
+/**
+* Create a `ToolSearch` tool instance — register it RESIDENT with the agent's tool registry.
+*
+* It must never itself be deferred: a search tool the model cannot see is a catalog with no way in,
+* which is the state the vendor's own "at least one tool must stay resident" invariant forbids.
+*/
+function createToolSearchTool(options = {}) {
+	return createZodFunctionTool(TOOL_SEARCH_NAME, options.description ?? TOOL_SEARCH_DESCRIPTION, ToolSearchSchema, async (params, context) => {
+		const output = {
+			loaded: selectTools(params, requireCatalog(context)).map(({ name, description }) => ({
+				name,
+				description
+			})),
+			unavailableSources: []
+		};
+		const result = {
+			success: true,
+			output: JSON.stringify(output)
+		};
+		return JSON.stringify(result);
+	});
+}
+/** `ToolSearch` tool instance — register with the Robota agent tools registry. */
+const toolSearchTool = createToolSearchTool();
+//#endregion
+export { DEFAULT_OS_SANDBOX_SETTINGS, DEFAULT_TOOL_SEARCH_LIMIT, E2BSandboxClient, GrepIsolationError, InMemorySandboxClient, OsSandboxClient, PageComputerDriver, REPO_MAP_INDEX_VERSION, ReadByteLimitError, ReadCancelledError, RepoMapRetrievalAdapter, TOOL_SEARCH_NAME, applyWorkspaceManifest, askUserQuestionTool, bubblewrapArguments, buildRepoMapIndex, createAskUserQuestionTool, createBashTool, createBraveSearchProvider, createComputerActTool, createComputerTool, createComputerViewTool, createEditTool, createFunctionTool, createGlobTool, createGrepTool, createReadTool, createRetrievalTool, createShellTool, createToolSearchTool, createWebFetchTool, createWebSearchTool, createWriteTool, createZodFunctionTool, describeExecutionContainment, deserializeRepoMapIndex, detectOsSandbox, matchDeferredTools, protectedWorkspaceEntries, routesFilesThroughSandbox, seatbeltProfile, serializeRepoMapIndex, toolSearchTool, updateRepoMapIndex, validateWorkspaceManifestPath, webFetchTool, webSearchTool };
 
 //# sourceMappingURL=index.js.map