@iowarp/clio-coder 0.4.8 → 0.4.9

package/src/tools/grep.ts

@@ -1,5 +1,7 @@
-import { readdirSync, readFileSync, statSync } from "node:fs";
+import { statSync } from "node:fs";
+import { readdir, readFile, stat } from "node:fs/promises";
 import path, { join, relative } from "node:path";
+import { setImmediate as yieldToLoop } from "node:timers/promises";
 import { Type } from "typebox";
 import { ToolNames } from "../core/tool-names.js";
 import { StringEnum } from "../engine/ai.js";
@@ -18,7 +20,16 @@ import {
 } from "./observation.js";
 import { resolveReadPath, toPosixPath } from "./path-utils.js";
 import type { ToolInvokeOptions, ToolResult, ToolSpec } from "./registry.js";
-import { SEARCH_SPAWN_TIMEOUT_MS, spawnLineStream, validateSearchPatternSize } from "./spawn-hygiene.js";
+import {
+	createSearchDiagnostics,
+	finishSearch,
+	newSearchCompleteness,
+	type SearchCompleteness,
+	searchNotice,
+	skipSearchPath,
+	spawnLineStream,
+	validateSearchPatternSize,
+} from "./spawn-hygiene.js";
 import { GREP_MAX_LINE_LENGTH, truncateHead, truncateLine } from "./truncate.js";
 
 const DEFAULT_LIMIT = 100;
@@ -68,6 +79,8 @@ interface RenderedLine {
 }
 
 interface GrepRenderInput {
+	search: SearchCompleteness;
+	fallback?: boolean;
 	withheldPaths: number;
 	mode: GrepMode;
 	lines: RenderedLine[];
@@ -88,16 +101,21 @@ const NO_MATCH_OUTPUT = "No matches found";
  * rendering when anything was cut, and close the envelope.
  */
 function renderGrepResult(input: GrepRenderInput): ToolResult {
-	const { mode, lines, matchCount, limitHit, limit, linesTruncated, reservation, options } = input;
+	const { mode, lines, matchCount, limitHit, limit, linesTruncated, reservation, options, search } = input;
+	const fallbackNotice = input.fallback
+		? "\n[Fallback search uses GENERATED_DIRS only; .gitignore is not applied.]"
+		: "";
 	if (lines.length === 0) {
 		return finalizeObservation({
 			tool: ToolNames.Grep,
 			withheldPaths: input.withheldPaths,
 			unit: MODE_UNITS[mode],
-			output: NO_MATCH_OUTPUT,
+			output:
+				(search.complete ? NO_MATCH_OUTPUT : "Search incomplete") + searchNotice(search, 0, "matches") + fallbackNotice,
+			details: { search },
 			shownCount: 0,
-			totalCount: 0,
-			truncated: false,
+			totalCount: search.complete ? 0 : null,
+			truncated: !search.complete,
 			reservation,
 			...(options ? { options } : {}),
 		});
@@ -115,7 +133,11 @@ function renderGrepResult(input: GrepRenderInput): ToolResult {
 	} else {
 		shownCount = truncation.outputLines;
 	}
-	const truncated = limitHit || truncation.truncated;
+	if (truncation.truncated && search.complete) {
+		search.complete = false;
+		search.reason = "limit";
+	}
+	const truncated = !search.complete || limitHit || truncation.truncated;
 	const next = limitHit ? `limit=${limit * 2}` : truncation.truncated && mode === "content" ? "mode=files" : undefined;
 	let output = truncation.content;
 	if (linesTruncated) {
@@ -125,12 +147,13 @@ function renderGrepResult(input: GrepRenderInput): ToolResult {
 		tool: ToolNames.Grep,
 		withheldPaths: input.withheldPaths,
 		unit: MODE_UNITS[mode],
-		output,
+		output: output + searchNotice(search, shownCount, "matches") + fallbackNotice,
+		details: { search },
 		// Offload only when the byte cap cut collected content; a bare match
 		// limit continues via `next`, and the offload would duplicate the body.
 		...(truncation.truncated ? { fullOutput } : {}),
 		shownCount,
-		totalCount: limitHit ? null : matchCount,
+		totalCount: search.complete ? matchCount : null,
 		truncated,
 		...(next !== undefined ? { next } : {}),
 		reservation,
@@ -237,22 +260,31 @@ async function runRipgrep(input: RgSearchInput): Promise<ToolResult> {
 		}
 	};
 
+	const search = newSearchCompleteness();
+	const diagnostics = createSearchDiagnostics(search, (filePath) => input.pathFilter.allows(path.resolve(filePath)));
 	const result = await spawnLineStream(input.rgPath, buildRgArgs(input), {
 		...(input.options?.signal ? { signal: input.options.signal } : {}),
 		onLine: input.mode === "content" ? onContentLine : onListLine,
+		onStderrLine: diagnostics.onLine,
 	});
-	if (result.aborted) return { kind: "error", message: "grep: operation aborted" };
-	if (result.timedOut) {
+	finishSearch(search, result);
+	if (result.spawnError !== null) return { kind: "error", message: `grep: failed to run rg: ${result.spawnError}` };
+	if (
+		!result.aborted &&
+		!result.timedOut &&
+		!result.stoppedEarly &&
+		result.exitCode !== 0 &&
+		result.exitCode !== 1 &&
+		matchCount === 0 &&
+		(diagnostics.realError || (search.skipped.count === 0 && !search.skipped.unknown))
+	) {
 		return {
 			kind: "error",
-			message: `grep: rg timed out after ${SEARCH_SPAWN_TIMEOUT_MS / 1000}s. Narrow the pattern, path, or glob, lower context, or use mode=files.`,
+			message: `grep: rg rejected the search or failed (exit code ${result.exitCode}). Check the pattern and search path.`,
 		};
 	}
-	if (result.spawnError !== null) return { kind: "error", message: `grep: failed to run rg: ${result.spawnError}` };
-	if (!result.stoppedEarly && result.exitCode !== 0 && result.exitCode !== 1) {
-		return { kind: "error", message: `grep: ${result.stderr.trim() || `ripgrep exited with code ${result.exitCode}`}` };
-	}
 	return renderGrepResult({
+		search,
 		withheldPaths: input.pathFilter.withheldPaths,
 		mode: input.mode,
 		lines: rendered,
@@ -310,7 +342,8 @@ interface FallbackSearchInput {
  * already-in-memory file content, never a second read. Aggregates the same
  * three mode shapes as the rg path.
  */
-function fallbackGrep(input: FallbackSearchInput): ToolResult {
+async function fallbackGrep(input: FallbackSearchInput): Promise<ToolResult> {
+	const search = newSearchCompleteness();
 	const built = buildMatchRegex(input.pattern, input.literal, input.ignoreCase);
 	if (!built.ok) return { kind: "error", message: built.message };
 	const regex = built.regex;
@@ -337,21 +370,32 @@ function fallbackGrep(input: FallbackSearchInput): ToolResult {
 		rendered.push({ text: truncatedLine.text, isMatch });
 	};
 
-	const searchFile = (filePath: string): void => {
-		if (limitHit || !input.pathFilter.allows(filePath)) return;
+	const searchFile = async (filePath: string): Promise<void> => {
+		if (limitHit || signal?.aborted || !input.pathFilter.allows(filePath)) return;
 		let buffer: Buffer;
 		try {
-			const stat = statSync(filePath);
-			if (!stat.isFile() || stat.size > FALLBACK_MAX_FILE_BYTES) return;
-			buffer = readFileSync(filePath);
+			const fileStat = await stat(filePath);
+			if (!fileStat.isFile() || fileStat.size > FALLBACK_MAX_FILE_BYTES) {
+				skipSearchPath(search, filePath, input.pathFilter.allows);
+				return;
+			}
+			buffer = await readFile(filePath);
 		} catch {
+			skipSearchPath(search, filePath, input.pathFilter.allows);
+			return;
+		}
+		if (looksBinary(buffer)) {
+			skipSearchPath(search, filePath, input.pathFilter.allows);
 			return;
 		}
-		if (looksBinary(buffer)) return;
 		const lines = buffer.toString("utf8").replace(/\r\n/g, "\n").replace(/\r/g, "\n").split("\n");
 		const rel = formatPath(filePath, input.searchPath, input.isDirectory);
 		let fileMatches = 0;
 		for (let i = 0; i < lines.length; i += 1) {
+			if (i % 1024 === 0) {
+				await yieldToLoop();
+				if (signal?.aborted) return;
+			}
 			const lineText = lines[i] ?? "";
 			regex.lastIndex = 0;
 			if (!regex.test(lineText)) continue;
@@ -384,35 +428,46 @@ function fallbackGrep(input: FallbackSearchInput): ToolResult {
 		}
 	};
 
-	const walk = (dir: string): void => {
+	const walk = async (dir: string): Promise<void> => {
+		await yieldToLoop();
 		if (limitHit || signal?.aborted) return;
 		let entries: import("node:fs").Dirent[];
 		try {
-			entries = readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name));
+			entries = (await readdir(dir, { withFileTypes: true })).sort((a, b) => a.name.localeCompare(b.name));
 		} catch {
+			skipSearchPath(search, dir, input.pathFilter.allows);
 			return;
 		}
 		for (const entry of entries) {
 			if (limitHit || signal?.aborted) return;
 			const absPath = join(dir, entry.name);
+			if (!input.pathFilter.allows(absPath)) continue;
 			if (entry.isDirectory()) {
 				if (ignored.has(entry.name)) continue;
-				walk(absPath);
+				await walk(absPath);
+				continue;
+			}
+			if (!entry.isFile()) {
+				skipSearchPath(search, absPath, input.pathFilter.allows);
 				continue;
 			}
-			if (!entry.isFile()) continue;
 			if (globMatcher) {
 				const relPath = normalizeGlobInput(relative(input.searchPath, absPath));
 				if (!globMatcher.test(relPath)) continue;
 			}
-			searchFile(absPath);
+			await searchFile(absPath);
 		}
 	};
 
-	if (input.isDirectory) walk(input.searchPath);
-	else searchFile(input.searchPath);
-	if (signal?.aborted) return { kind: "error", message: "grep: operation aborted" };
+	if (input.isDirectory) await walk(input.searchPath);
+	else await searchFile(input.searchPath);
+	if (signal?.aborted || limitHit) {
+		search.complete = false;
+		search.reason = signal?.aborted ? "cancelled" : "limit";
+	}
 	return renderGrepResult({
+		fallback: true,
+		search,
 		withheldPaths: input.pathFilter.withheldPaths,
 		mode: input.mode,
 		lines: rendered,
@@ -427,7 +482,7 @@ function fallbackGrep(input: FallbackSearchInput): ToolResult {
 
 export const grepTool: ToolSpec = {
 	name: ToolNames.Grep,
-	description: `Search file contents with ripgrep. mode=content (default) returns matching lines with paths and line numbers, mode=files returns only matching file paths, mode=count returns per-file match counts. Respects .gitignore and skips generated dirs unless include_ignored=true. Capped at ${DEFAULT_LIMIT} matches by default; truncated results say how to continue and where the full output was saved.`,
+	description: `Search file contents with ripgrep. mode=content (default) returns matching lines with paths and line numbers, mode=files returns only matching file paths, mode=count returns per-file match counts. Respects .gitignore and skips generated dirs unless include_ignored=true. Without rg, the async fallback uses GENERATED_DIRS only and does not apply .gitignore; unreadable, binary, oversized files and symlinks are reported as skipped. Capped at ${DEFAULT_LIMIT} matches by default; truncated results say how to continue and where the full output was saved.`,
 	parameters: Type.Object({
 		pattern: Type.String({ description: "Search pattern (regex by default)." }),
 		path: Type.Optional(Type.String({ description: "Directory or file to search." })),
@@ -499,7 +554,7 @@ export const grepTool: ToolSpec = {
 			if (rgPath) return await runRipgrep({ rgPath, ...shared });
 			// rg absent (offline/weak node): degrade to a bounded pure-Node search
 			// instead of failing content search outright.
-			return fallbackGrep(shared);
+			return await fallbackGrep(shared);
 		} finally {
 			releaseObservation(reservation);
 		}

package/src/tools/harness-extensions.ts

@@ -64,6 +64,9 @@ function createCommandTool(extension: LoadableExtension, tool: ExtensionCommandT
 		parameters: tool.inputSchema as TSchema,
 		baseActionClass: "execute",
 		executionMode: "sequential",
+		// Reached through gateway find/describe/call; the spec, its execute
+		// class, and its bash projection are unchanged by the placement.
+		placement: "gateway",
 		sourceInfo: { path: extension.manifestPath, scope: "domain", extension: extension.provenance },
 		metadata: {
 			objective: tool.description,

package/src/tools/ignore-policy.ts

@@ -3,10 +3,11 @@ import { dirname, join } from "node:path";
 import { toPosixPath } from "./path-utils.js";
 
 /**
- * One ignore policy for every path-walking OBSERVE tool. grep (rg), find (fd),
- * and the pure-Node fallback walkers all answer "which parts of the tree are
- * visible" from this module so the three surfaces never disagree about
- * gitignored, generated, or clio-internal paths.
+ * Shared exclusions for path-walking OBSERVE tools. Native rg/fd searches
+ * honor gitignore rules as well as generated-directory and internal-state
+ * exclusions. Pure-Node fallback walkers apply GENERATED_DIRS and internal
+ * exclusions only; they do not interpret .gitignore or .ignore files, so their
+ * visible paths can differ from native searches.
  *
  * The policy has three layers:
  *   1. ALWAYS excluded: clio-internal state and .git. Never searchable unless
@@ -14,7 +15,8 @@ import { toPosixPath } from "./path-utils.js";
  *      .clio-coder explicitly means the caller wants those paths).
  *   2. .gitignore: honored natively by rg/fd. Outside a git repo the binaries
  *      get --no-require-git so plain .gitignore/.ignore files still apply;
- *      inside a repo the default git-aware behavior keeps parent ignore rules
+ *      fallback walkers do not apply this layer. Inside a repo the default
+ *      git-aware behavior keeps parent ignore rules
  *      from leaking across nested-repo boundaries.
  *   3. GENERATED_DIRS: universal build/dependency noise force-excluded even
  *      when a project forgets to gitignore it.

package/src/tools/ls.ts

@@ -1,27 +1,84 @@
-import { readdirSync, statSync } from "node:fs";
+import { lstat, opendir, readlink, stat } from "node:fs/promises";
 import path from "node:path";
+import { setImmediate as yieldToLoop } from "node:timers/promises";
 import { Type } from "typebox";
 import { ToolNames } from "../core/tool-names.js";
+import { createSafetyPolicyEngine } from "../domains/safety/policy-engine.js";
 import {
-	createObservationPathFilter,
+	commitObservationReservation,
 	finalizeObservation,
 	OBSERVE_SELF_CAPS,
 	observationBudgetExhausted,
+	releaseObservation,
 	reserveObservation,
 } from "./observation.js";
 import { resolveReadPath } from "./path-utils.js";
 import type { ToolResult, ToolSpec } from "./registry.js";
+import { newSearchCompleteness, skipSearchPath } from "./spawn-hygiene.js";
 import { truncateHead } from "./truncate.js";
 
 const DEFAULT_LIMIT = 500;
 
 function parseLimit(value: unknown): number {
-	return typeof value === "number" && value > 0 ? Math.floor(value) : DEFAULT_LIMIT;
+	return typeof value === "number" && Number.isFinite(value) && value >= 1 ? Math.floor(value) : DEFAULT_LIMIT;
+}
+
+interface ListingEntry {
+	name: string;
+	order: number;
+}
+
+const compareEntries = (a: ListingEntry, b: ListingEntry): number =>
+	a.name.toLowerCase().localeCompare(b.name.toLowerCase()) || a.order - b.order;
+
+/** A max heap retains the earliest names, preserving directory read order for collation ties. */
+export class BoundedListingSelection {
+	private readonly entries: ListingEntry[] = [];
+	private nextOrder = 0;
+	constructor(private readonly limit: number) {}
+	get retained(): number {
+		return this.entries.length;
+	}
+	private entryAt(index: number): ListingEntry {
+		const entry = this.entries[index];
+		if (!entry) throw new Error("Invalid listing heap index");
+		return entry;
+	}
+	add(name: string): void {
+		const entry = { name, order: this.nextOrder++ };
+		if (this.entries.length < this.limit) {
+			this.entries.push(entry);
+			let i = this.entries.length - 1;
+			while (i > 0) {
+				const parent = Math.floor((i - 1) / 2);
+				if (compareEntries(this.entryAt(parent), entry) >= 0) break;
+				this.entries[i] = this.entryAt(parent);
+				i = parent;
+			}
+			this.entries[i] = entry;
+			return;
+		}
+		if (compareEntries(entry, this.entryAt(0)) >= 0) return;
+		this.entries[0] = entry;
+		let i = 0;
+		while (2 * i + 1 < this.entries.length) {
+			let child = 2 * i + 1;
+			if (child + 1 < this.entries.length && compareEntries(this.entryAt(child + 1), this.entryAt(child)) > 0) child++;
+			if (compareEntries(entry, this.entryAt(child)) >= 0) break;
+			this.entries[i] = this.entryAt(child);
+			i = child;
+		}
+		this.entries[i] = entry;
+	}
+	sorted(): string[] {
+		return [...this.entries].sort(compareEntries).map((entry) => entry.name);
+	}
 }
 
 export const lsTool: ToolSpec = {
 	name: ToolNames.Ls,
-	description: 'List directory entries sorted alphabetically, "/" suffix for directories, dotfiles included.',
+	description:
+		'List directory entries sorted alphabetically, "/" suffix for directories, dotfiles included. Symlinks render as name@ -> target, broken links as name@ (broken), and inaccessible entries are marked and counted.',
 	parameters: Type.Object({
 		path: Type.Optional(Type.String({ description: "Directory to list." })),
 		limit: Type.Optional(Type.Number({ description: `Max entries (default ${DEFAULT_LIMIT}).` })),
@@ -34,7 +91,7 @@ export const lsTool: ToolSpec = {
 		const limit = parseLimit(args.limit);
 
 		try {
-			const rootStat = statSync(root);
+			const rootStat = await stat(root);
 			if (!rootStat.isDirectory()) {
 				return { kind: "error", message: `ls: not a directory: ${root}` };
 			}
@@ -53,32 +110,63 @@ export const lsTool: ToolSpec = {
 			});
 		}
 
+		commitObservationReservation(reservation);
 		try {
-			const pathFilter = createObservationPathFilter(process.cwd(), options?.allowsObservationPath);
-			const entries = readdirSync(root)
-				.filter((entry) => pathFilter.allows(path.join(root, entry)))
-				.sort((a, b) => a.toLowerCase().localeCompare(b.toLowerCase()));
+			const policy = options?.allowsObservationPath ? undefined : createSafetyPolicyEngine({ cwd: process.cwd() });
+			const allows =
+				options?.allowsObservationPath ??
+				((entryPath: string) =>
+					policy?.evaluate({ tool: "read", args: { path: entryPath } }).reasonCode !== "path-policy:zeroAccessPaths");
+			let withheldPaths = 0;
+			let visibleCount = 0;
+			let scanned = 0;
+			const selection = new BoundedListingSelection(limit);
+			// Alphabetical selection requires examining every name, but only limit
+			// names are retained. No metadata calls are made for unselected entries.
+			for await (const entry of await opendir(root)) {
+				if (++scanned % 128 === 0) await yieldToLoop();
+				if (options?.signal?.aborted) return { kind: "error", message: "ls: operation aborted during enumeration" };
+				if (!allows(path.join(root, entry.name))) {
+					withheldPaths++;
+					continue;
+				}
+				visibleCount++;
+				selection.add(entry.name);
+			}
+			const entries = selection.sorted();
 			const outputEntries: string[] = [];
-			let entryLimitReached = false;
+			const entryLimitReached = visibleCount > limit;
+			const search = newSearchCompleteness();
 			for (const entry of entries) {
-				if (outputEntries.length >= limit) {
-					entryLimitReached = true;
-					break;
-				}
+				const entryPath = path.join(root, entry);
 				try {
-					const entryStat = statSync(path.join(root, entry));
-					outputEntries.push(entryStat.isDirectory() ? `${entry}/` : entry);
+					const entryStat = await lstat(entryPath);
+					if (entryStat.isSymbolicLink()) {
+						const target = await readlink(entryPath);
+						try {
+							await stat(entryPath);
+							outputEntries.push(`${entry}@ -> ${target}`);
+						} catch (error) {
+							const code = (error as NodeJS.ErrnoException).code;
+							outputEntries.push(`${entry}@ (${code === "ENOENT" || code === "ENOTDIR" ? "broken" : "unreadable"})`);
+							skipSearchPath(search, entryPath);
+						}
+					} else {
+						outputEntries.push(entryStat.isDirectory() ? `${entry}/` : entry);
+					}
 				} catch {
-					// Mirror the reference tool: skip entries that disappear or cannot be statted.
+					outputEntries.push(`${entry} (unreadable)`);
+					skipSearchPath(search, entryPath);
 				}
 			}
 
 			if (outputEntries.length === 0) {
 				return finalizeObservation({
 					tool: ToolNames.Ls,
-					withheldPaths: pathFilter.withheldPaths,
+					withheldPaths,
 					unit: "entries",
 					output: "(empty directory)",
+					details: { skipped: search.skipped, selection: { scanned, retained: selection.retained } },
 					shownCount: 0,
 					totalCount: 0,
 					truncated: false,
@@ -95,14 +183,15 @@ export const lsTool: ToolSpec = {
 			const truncated = entryLimitReached || truncation.truncated;
 			return finalizeObservation({
 				tool: ToolNames.Ls,
-				withheldPaths: pathFilter.withheldPaths,
+				withheldPaths,
 				unit: "entries",
 				output: truncation.content,
+				details: { skipped: search.skipped, selection: { scanned, retained: selection.retained } },
 				// Offload only when the byte cap cut collected entries; a bare
 				// entry limit continues via `next`.
 				...(truncation.truncated ? { fullOutput } : {}),
 				shownCount: truncation.outputLines,
-				totalCount: entries.length,
+				totalCount: visibleCount,
 				truncated,
 				...(entryLimitReached ? { next: `limit=${limit * 2}` } : {}),
 				reservation,
@@ -111,6 +200,8 @@ export const lsTool: ToolSpec = {
 		} catch (err) {
 			const msg = err instanceof Error ? err.message : String(err);
 			return { kind: "error", message: `ls: ${msg}` };
+		} finally {
+			releaseObservation(reservation);
 		}
 	},
 };

package/src/tools/policy.ts

@@ -1,5 +1,6 @@
 import { type BuiltinToolName, isBuiltinToolName, type ToolName, ToolNames } from "../core/tool-names.js";
 import { type ActionClass, classify } from "../domains/safety/action-classifier.js";
+import { DATA_OBSERVATION_SELF_CAP_BYTES, GATEWAY_FIND_SELF_CAP_BYTES } from "./gateway/caps.js";
 import { OBSERVATION_POLICY_SLACK_BYTES, OBSERVE_SELF_CAPS } from "./observation.js";
 import { readMaxBytes } from "./read.js";
 import type { ToolExecutionMode, ToolSpec } from "./registry.js";
@@ -11,7 +12,15 @@ import type { ToolExecutionMode, ToolSpec } from "./registry.js";
  * differently from what the policy engine assumes.
  */
 
-export type ToolPlane = "observe" | "mutate" | "execute" | "orchestrate" | "retrieve" | "interact" | "artifact";
+export type ToolPlane =
+	| "observe"
+	| "mutate"
+	| "execute"
+	| "orchestrate"
+	| "retrieve"
+	| "interact"
+	| "artifact"
+	| "gateway";
 
 interface PlaneExpectation {
 	plane: ToolPlane;
@@ -29,6 +38,12 @@ export const TOOL_PLANES: Readonly<Record<BuiltinToolName, PlaneExpectation>> =
 	[ToolNames.CodeNav]: { plane: "observe", actionClass: "read", executionMode: "parallel" },
 	[ToolNames.Context]: { plane: "observe", actionClass: "read", executionMode: "parallel" },
 	[ToolNames.CredentialPresent]: { plane: "observe", actionClass: "read", executionMode: "parallel" },
+	// clio_docs and clio_library are the bundled-documentation and recipe-catalog
+	// reads that used to be context scopes; same envelope, same read class.
+	[ToolNames.ClioDocs]: { plane: "observe", actionClass: "read", executionMode: "parallel" },
+	[ToolNames.ClioLibrary]: { plane: "observe", actionClass: "read", executionMode: "parallel" },
+	// data streams structured files and never writes; parallel like read.
+	[ToolNames.Data]: { plane: "observe", actionClass: "read", executionMode: "parallel" },
 	[ToolNames.Write]: { plane: "mutate", actionClass: "write", executionMode: "sequential" },
 	[ToolNames.Edit]: { plane: "mutate", actionClass: "write", executionMode: "sequential" },
 	[ToolNames.Bash]: { plane: "execute", actionClass: "execute", executionMode: "sequential" },
@@ -36,6 +51,9 @@ export const TOOL_PLANES: Readonly<Record<BuiltinToolName, PlaneExpectation>> =
 	// its containment posture, read class for its safety disposition.
 	[ToolNames.Git]: { plane: "execute", actionClass: "read", executionMode: "parallel" },
 	[ToolNames.Verify]: { plane: "execute", actionClass: "execute", executionMode: "sequential" },
+	// run_script runs one interpreter over one workspace script and projects
+	// itself to a bash command for the policy engine; execute class, sequential.
+	[ToolNames.RunScript]: { plane: "execute", actionClass: "execute", executionMode: "sequential" },
 	[ToolNames.Dispatch]: { plane: "orchestrate", actionClass: "dispatch", executionMode: "sequential" },
 	// monitor never mutates a run, so it stays read class and parallel.
 	[ToolNames.Monitor]: { plane: "orchestrate", actionClass: "read", executionMode: "parallel" },
@@ -62,16 +80,25 @@ export const TOOL_PLANES: Readonly<Record<BuiltinToolName, PlaneExpectation>> =
 	// nothing else. Read class so it never trips a safety gate; sequential so
 	// two decisions in one batch never race the supersede lookup.
 	[ToolNames.Decide]: { plane: "orchestrate", actionClass: "read", executionMode: "sequential" },
+	// web_read is the GET-only half of the split: no method, headers, or body,
+	// so it is never an outward action.
+	[ToolNames.WebRead]: { plane: "retrieve", actionClass: "read", executionMode: "parallel" },
 	[ToolNames.WebFetch]: { plane: "retrieve", actionClass: "read", executionMode: "parallel" },
 	[ToolNames.AskUser]: { plane: "interact", actionClass: "read", executionMode: "sequential" },
 	[ToolNames.Artifact]: { plane: "artifact", actionClass: "write", executionMode: "sequential" },
+	// gateway lists, describes, and calls secondary capabilities. Its own class
+	// is read; a call carries the capability's class through the same admission.
+	// Sequential because a call may park for approval or run a sequential
+	// capability, and two such calls in one batch must not interleave.
+	[ToolNames.Gateway]: { plane: "gateway", actionClass: "read", executionMode: "sequential" },
 };
 
 /**
  * OBSERVE envelope members and their self-caps. The registry policy cap must
  * sit at or above self cap + slack so the envelope's own notice line survives
  * the backstop. credential_present sits in the OBSERVE plane but returns a
- * typed boolean, so it carries no envelope cap.
+ * typed boolean, so it carries no envelope cap. The gateway is listed for its
+ * find listing, which uses the envelope's JSON stub rule.
  */
 const OBSERVE_ENVELOPE_SELF_CAPS: ReadonlyArray<[BuiltinToolName, () => number]> = [
 	[ToolNames.Read, () => readMaxBytes()],
@@ -79,16 +106,11 @@ const OBSERVE_ENVELOPE_SELF_CAPS: ReadonlyArray<[BuiltinToolName, () => number]>
 	[ToolNames.Find, () => OBSERVE_SELF_CAPS.find],
 	[ToolNames.Ls, () => OBSERVE_SELF_CAPS.ls],
 	[ToolNames.CodeNav, () => OBSERVE_SELF_CAPS.codeNav],
-	[
-		ToolNames.Context,
-		() =>
-			Math.max(
-				OBSERVE_SELF_CAPS.contextDocs,
-				OBSERVE_SELF_CAPS.contextSkills,
-				OBSERVE_SELF_CAPS.contextWorkspace,
-				OBSERVE_SELF_CAPS.contextLibrary,
-			),
-	],
+	[ToolNames.Context, () => Math.max(OBSERVE_SELF_CAPS.contextSkills, OBSERVE_SELF_CAPS.contextWorkspace)],
+	[ToolNames.ClioDocs, () => OBSERVE_SELF_CAPS.contextDocs],
+	[ToolNames.ClioLibrary, () => OBSERVE_SELF_CAPS.contextLibrary],
+	[ToolNames.Data, () => DATA_OBSERVATION_SELF_CAP_BYTES],
+	[ToolNames.Gateway, () => GATEWAY_FIND_SELF_CAP_BYTES],
 ];
 
 const SESSION_BOUND_TOOLS = new Set<ToolName>([]);
@@ -104,7 +126,7 @@ const PANES_BOUND_TOOLS = new Set<ToolName>([ToolNames.Panes]);
  */
 const LEDGER_BOUND_TOOLS = new Set<ToolName>([ToolNames.Ledger]);
 /** The RETRIEVE plane, omitted wholesale by a hermetic run (tools/network-policy.ts). */
-const NETWORK_BOUND_TOOLS = new Set<ToolName>([ToolNames.WebFetch]);
+const NETWORK_BOUND_TOOLS = new Set<ToolName>([ToolNames.WebRead, ToolNames.WebFetch]);
 
 export interface BuiltinToolPolicyOptions {
 	includeSessionTools?: boolean;

package/src/tools/presentation.ts

@@ -58,11 +58,15 @@ export const TOOL_PRESENTATION: Readonly<Record<string, ToolPresentationPolicy>>
 	[ToolNames.CodeNav]: FOLDED,
 	[ToolNames.Context]: FOLDED,
 	[ToolNames.CredentialPresent]: FOLDED,
+	[ToolNames.ClioDocs]: FOLDED,
+	[ToolNames.ClioLibrary]: FOLDED,
+	[ToolNames.Data]: FOLDED,
 	[ToolNames.Write]: FOLDED_WITH_DIFF,
 	[ToolNames.Edit]: FOLDED_WITH_DIFF,
 	[ToolNames.Bash]: FOLDED,
 	[ToolNames.Git]: FOLDED,
 	[ToolNames.Verify]: FOLDED,
+	[ToolNames.RunScript]: FOLDED,
 	[ToolNames.Dispatch]: FOLDED,
 	[ToolNames.Monitor]: FOLDED,
 	[ToolNames.Steer]: FOLDED,
@@ -71,9 +75,11 @@ export const TOOL_PRESENTATION: Readonly<Record<string, ToolPresentationPolicy>>
 	[ToolNames.Panes]: FOLDED,
 	[ToolNames.Limitation]: FOLDED,
 	[ToolNames.Decide]: FOLDED,
+	[ToolNames.WebRead]: FOLDED,
 	[ToolNames.WebFetch]: FOLDED,
 	[ToolNames.AskUser]: FOLDED,
 	[ToolNames.Artifact]: FOLDED,
+	[ToolNames.Gateway]: FOLDED,
 };
 
 function readStringField(args: unknown, key: string): string | null {