@iowarp/clio-coder 0.3.0 → 0.3.1

package/src/tools/bash.ts

@@ -0,0 +1,176 @@
+import { Type } from "typebox";
+import { BASH_HARD_CAP_BYTES, combineBashOutput, runBashCommand } from "../core/bash-exec.js";
+import { resolveSafeCwd } from "../core/safe-exec.js";
+import { ToolNames } from "../core/tool-names.js";
+import { expandPath } from "./path-utils.js";
+import type { ToolInvokeOptions, ToolResult, ToolResultDetails, ToolSpec } from "./registry.js";
+import { writeToolOffload } from "./result-shaping.js";
+import { DEFAULT_MAX_LINES, formatSize, truncateTail } from "./truncate.js";
+
+// What the model sees inline. The tail is where the failing assertion, compiler
+// error, and exit summary live, so we keep the LAST lines/bytes. The full
+// output is spilled to an offload file before truncating, so nothing is lost.
+const BASH_DISPLAY_MAX_BYTES = 16 * 1024;
+// Slack reserved so the continuation notice appended after truncation still
+// fits under the registry's per-tool bash budget without a second (head-first)
+// re-truncation cutting the tail we just preserved.
+const BASH_TAIL_NOTE_RESERVE = 512;
+
+interface ShapedBashOutput {
+	text: string;
+	details?: ToolResultDetails;
+}
+
+// Tail-truncate the combined output for display, spilling the full output to a
+// scratch file first when it overflows the display cap. Setting
+// `details.resultSize.offloadPath` tells the registry result-shaper to leave
+// this already-shaped (tail-biased) output alone instead of re-truncating it
+// head-first.
+function shapeBashOutput(
+	rawOutput: string,
+	context: Pick<ToolInvokeOptions, "sessionId" | "toolCallId"> | undefined,
+): ShapedBashOutput {
+	const truncation = truncateTail(rawOutput, {
+		maxLines: DEFAULT_MAX_LINES,
+		maxBytes: BASH_DISPLAY_MAX_BYTES - BASH_TAIL_NOTE_RESERVE,
+	});
+	if (!truncation.truncated) return { text: rawOutput };
+
+	const totalBytes = Buffer.byteLength(rawOutput, "utf8");
+	const offloadPath = writeToolOffload(rawOutput, context, BASH_HARD_CAP_BYTES);
+	const startLine = truncation.totalLines - truncation.outputLines + 1;
+	const scope = truncation.lastLinePartial
+		? `last ${formatSize(truncation.outputBytes)} of line ${truncation.totalLines} (line is large)`
+		: `lines ${startLine}-${truncation.totalLines} of ${truncation.totalLines}`;
+	const location = offloadPath !== null ? ` Full output saved to ${offloadPath}; read it with offset/limit.` : "";
+	const note = `[Output tail-truncated: showing ${scope} (${formatSize(BASH_DISPLAY_MAX_BYTES)} display limit).${location}]`;
+	const details: ToolResultDetails = {
+		resultSize: {
+			bytes: totalBytes,
+			shownBytes: truncation.outputBytes,
+			maxBytes: BASH_DISPLAY_MAX_BYTES,
+			truncated: true,
+			policy: "tail",
+			followUpHint: "Read the full-output offload file with offset/limit, or re-run a narrower command.",
+			...(offloadPath !== null ? { offloadPath } : {}),
+		},
+	};
+	return { text: `${truncation.content}\n\n${note}`, details };
+}
+
+function withDetails(base: ToolResult, details: ToolResultDetails | undefined): ToolResult {
+	if (details === undefined) return base;
+	if (base.kind === "ok") return { ...base, details };
+	return { ...base, details };
+}
+
+// A bash command whose first word is a plain file/dir observer has a
+// structured OBSERVE counterpart with paged, budget-aware results.
+const OBSERVE_COMMAND_PATTERN = /^\s*(?:cat|head|tail|ls|grep|rg|find)\b/;
+
+const OBSERVE_NUDGE_SESSION_LIMIT = 64;
+const observeNudgeSeenSessions = new Set<string>();
+
+/**
+ * One nudge per session, on the first successful observer-shaped bash call.
+ * Point-of-failure conditioning like the edit-result validation nudge:
+ * measured orientation runs opened with ten bash cat/ls calls while the
+ * structured observe tools sat unused in the surface; result-time text beats
+ * static prompt lines. Appending to the result keeps the per-session tool
+ * surface and prompt prefix byte-stable.
+ */
+function observeToolsNudge(command: string, sessionId: string | undefined): string {
+	if (!OBSERVE_COMMAND_PATTERN.test(command)) return "";
+	const key = sessionId ?? "no-session";
+	if (observeNudgeSeenSessions.has(key)) return "";
+	if (observeNudgeSeenSessions.size >= OBSERVE_NUDGE_SESSION_LIMIT) {
+		const oldest = observeNudgeSeenSessions.values().next().value;
+		if (oldest !== undefined) observeNudgeSeenSessions.delete(oldest);
+	}
+	observeNudgeSeenSessions.add(key);
+	return (
+		"\n\n[note: prefer the structured observe tools over shell file inspection: read pages files with " +
+		"offset/limit, ls lists directories, grep and find search, code_nav maps symbols. Their results are " +
+		"capped and continuable; keep bash for builds, git, and scripts.]"
+	);
+}
+
+export const bashTool: ToolSpec = {
+	name: ToolNames.Bash,
+	description:
+		"Execute a bash command and return stdout and stderr. Runs inside the session workspace. Default timeout 300000 ms.",
+	parameters: Type.Object({
+		command: Type.String({ description: "Bash command to execute." }),
+		cwd: Type.Optional(
+			Type.String({
+				description:
+					"Omit this. The command already runs at the session workspace root. Set it only to run in a subdirectory of that root, as a relative path; an absolute path outside the root is blocked.",
+			}),
+		),
+		timeout_ms: Type.Optional(Type.Number({ description: "Timeout in milliseconds." })),
+	}),
+	baseActionClass: "execute",
+	executionMode: "sequential",
+	async run(args, options): Promise<ToolResult> {
+		if (typeof args.command !== "string" || args.command.length === 0) {
+			return { kind: "error", message: "bash: missing command argument" };
+		}
+		const cwdArg = typeof args.cwd === "string" && args.cwd.length > 0 ? args.cwd : undefined;
+		// Pin the child's cwd inside the session workspace in the tool itself.
+		// The safety net blocks escaping cwd arguments at admission; this is the
+		// defense-in-depth mirror for paths that reach the tool directly, and it
+		// resolves `~` before checking so a home-relative cwd cannot slip past
+		// as an unexpanded literal.
+		let cwd: string;
+		try {
+			cwd = resolveSafeCwd(cwdArg === undefined ? undefined : expandPath(cwdArg), process.cwd());
+		} catch {
+			return {
+				kind: "error",
+				message: `bash: cwd '${cwdArg}' escapes workspace root '${process.cwd()}'; use a typed tool or a project policy entry with explicit cwd`,
+			};
+		}
+		const timeout = typeof args.timeout_ms === "number" && args.timeout_ms > 0 ? args.timeout_ms : 300_000;
+		try {
+			const result = await runBashCommand(args.command, {
+				cwd,
+				timeoutMs: timeout,
+				...(options?.signal === undefined ? {} : { signal: options.signal }),
+			});
+			const { error, aborted, timedOut, outputCapped } = result;
+			if (aborted) {
+				return { kind: "error", message: "bash: command aborted" };
+			}
+			const shaped = shapeBashOutput(combineBashOutput(result), options);
+			const output = shaped.text.trim();
+			if (timedOut) {
+				const status = `bash: command timed out after ${timeout}ms`;
+				return withDetails(
+					{ kind: "error", message: output.length > 0 ? `${output}\n\n${status}` : status },
+					shaped.details,
+				);
+			}
+			if (outputCapped) {
+				const status = `bash: command output exceeded ${BASH_HARD_CAP_BYTES} bytes and was stopped`;
+				return withDetails(
+					{ kind: "error", message: output.length > 0 ? `${output}\n\n${status}` : status },
+					shaped.details,
+				);
+			}
+			if (error) {
+				const code = typeof error.code === "number" ? error.code : (error as { code?: string }).code;
+				const status = `bash: command failed (exit ${code ?? "?"})`;
+				const message = output.length > 0 ? `${output}\n\n${status}` : `${status}: ${error.message}`;
+				return withDetails({ kind: "error", message }, shaped.details);
+			}
+			const body = shaped.text.length > 0 ? shaped.text : "(no output)";
+			return withDetails(
+				{ kind: "ok", output: `${body}${observeToolsNudge(args.command, options?.sessionId)}` },
+				shaped.details,
+			);
+		} catch (err) {
+			const msg = err instanceof Error ? err.message : String(err);
+			return { kind: "error", message: `bash: ${msg}` };
+		}
+	},
+};

package/src/tools/bootstrap.ts

@@ -0,0 +1,474 @@
+import type { SafeEventBus } from "../core/event-bus.js";
+import { type ToolName, ToolNames } from "../core/tool-names.js";
+import type { AgentSpec } from "../domains/agents/spec.js";
+import type { DispatchContract } from "../domains/dispatch/contract.js";
+import type { AgentRoleFactsResolver } from "../domains/dispatch/execution-role.js";
+import type { LoadSkillsInput } from "../domains/resources/index.js";
+import type { AutonomyLevel } from "../domains/safety/autonomy.js";
+import type { SessionContract } from "../domains/session/contract.js";
+import { createTaskBoardStore, type TaskBoardStore } from "../domains/session/task-board.js";
+import { probeWorkspace } from "../domains/session/workspace/index.js";
+import type { AgentLedgerPort } from "../worker/protocol.js";
+import { createArtifactTool } from "./artifact.js";
+import { type AskUserHandler, createAskUserTool } from "./ask-user.js";
+import { bashTool } from "./bash.js";
+import { codeNavTool } from "./codewiki/code-nav.js";
+import { createContextTool } from "./context/index.js";
+import { credentialPresentTool } from "./credential-present.js";
+import { createDispatchRunEventRegistry, createDispatchTool, type DispatchBackgroundRegistry } from "./dispatch.js";
+import { editTool } from "./edit.js";
+import { findTool } from "./find.js";
+import { grepTool } from "./grep.js";
+import { createLedgerTool } from "./ledger.js";
+import { lsTool } from "./ls.js";
+import { createMonitorTool } from "./monitor.js";
+import { networkToolsDisabled } from "./network-policy.js";
+import { OBSERVATION_POLICY_SLACK_BYTES, OBSERVE_SELF_CAPS } from "./observation.js";
+import { assertBuiltinToolPolicy } from "./policy.js";
+import { readMaxBytes, readTool } from "./read.js";
+import type { ToolMetadata, ToolRegistry, ToolSourceInfo, ToolSpec } from "./registry.js";
+import { gitTool } from "./safe-exec.js";
+import { createSteerTool } from "./steer.js";
+import { createTasksTool } from "./tasks.js";
+import { verifyTool } from "./verify/index.js";
+import { webFetchTool } from "./web-fetch.js";
+import { writeTool } from "./write.js";
+
+export interface ToolBootstrapDeps {
+	session?: SessionContract;
+	dispatch?: DispatchContract;
+	bus?: SafeEventBus;
+	askUser?: AskUserHandler;
+	/**
+	 * Shared task-board store so the tool, the turn-end nudge, and the TUI all
+	 * read one board. Absent (workers, headless without a session) the tool
+	 * gets a private in-memory board without ledger persistence.
+	 */
+	taskBoard?: TaskBoardStore;
+	/**
+	 * The run's agent-ledger port. The ledger tool is registered unconditionally
+	 * because attestedToolSignature signs the names a bare registry produces and
+	 * a conditional registration would drift that signature; only the injected
+	 * port varies, and its absence is what makes the tool answer that this run
+	 * has no coordination ledger.
+	 */
+	agentLedger?: AgentLedgerPort;
+	/** Agent fleet catalog renderer for the dispatch tool's list action. */
+	getAgentCatalog?: () => string;
+	getAgentSpecs?: () => ReadonlyArray<AgentSpec>;
+	/** Strict recipe facts the dispatch tool derives each request's execution role from. */
+	getAgentRoleFacts?: AgentRoleFactsResolver;
+	/** Session-effective autonomy for dispatch plan provenance and compete winner handling. */
+	getAutonomy?: () => AutonomyLevel;
+	/** Scheduling cost ceiling recorded on dispatch plan provenance. */
+	getCostCeilingUsd?: () => number;
+	/**
+	 * Operator-initiated attach-to-detach conversion of a running dispatch. Only
+	 * the interactive composition root wires it, because only that process has a
+	 * keypress to fire the control with.
+	 */
+	dispatchBackground?: DispatchBackgroundRegistry;
+	getSkillLoaderOptions?: () => Pick<
+		LoadSkillsInput,
+		"trustProjectCompatRoots" | "disableDiscovery" | "explicitSkillPaths"
+	>;
+}
+
+function withSourceInfo<T extends ToolSpec>(spec: T, sourceInfo: ToolSourceInfo): T {
+	return { ...spec, sourceInfo };
+}
+
+function withMetadata<T extends ToolSpec>(spec: T, metadata: ToolMetadata): T {
+	return { ...spec, metadata };
+}
+
+// Registry-backstop caps derive from the OBSERVE self-caps in
+// src/tools/observation.ts: policy cap = self cap + slack, so a tool's own
+// envelope notice (with its exact continuation call) survives shaping instead
+// of being cut again and replaced by a generic hint. The 16KB summary
+// policies are the explicit overrides for tools whose output is inherently
+// aggregate (shell, verification runs, git, dispatch receipts, web pages).
+const policyCap = (selfCapBytes: number): number => selfCapBytes + OBSERVATION_POLICY_SLACK_BYTES;
+
+const observePolicy = (selfCapBytes: number, followUpHint: string) =>
+	({ kind: "bounded", maxBytes: policyCap(selfCapBytes), followUpHint }) satisfies ToolMetadata["resultSizePolicy"];
+
+const summaryPolicy = (followUpHint: string) =>
+	({ kind: "summary", maxBytes: 16_384, followUpHint }) satisfies ToolMetadata["resultSizePolicy"];
+
+const exactMutationPolicy = {
+	kind: "exact",
+	maxBytes: 8_192,
+	followUpHint: "Inspect the changed file or git diff for exact follow-up context.",
+} satisfies ToolMetadata["resultSizePolicy"];
+
+// Per-tool metadata, organized by plane. OBSERVE tools share the observation
+// envelope, the turn budget pool, and derived policy caps; every other plane
+// declares its posture explicitly.
+const TOOL_METADATA: Readonly<Record<string, ToolMetadata>> = {
+	// OBSERVE: read-class, parallel, envelope + shared turn budget.
+	[ToolNames.Read]: {
+		objective: "Read exact UTF-8 file content with line and byte bounds.",
+		uiLabel: "Read",
+		retrySafety: "idempotent",
+		resultSizePolicy: observePolicy(
+			readMaxBytes(),
+			"Use offset/limit or a narrower locate/search tool call to inspect omitted content.",
+		),
+		costLatency: "local_fast",
+	},
+	[ToolNames.Grep]: {
+		objective: "Search file contents and return line-referenced matches.",
+		uiLabel: "Grep",
+		retrySafety: "idempotent",
+		resultSizePolicy: observePolicy(
+			OBSERVE_SELF_CAPS.grepContent,
+			"Refine the pattern, path, glob, context, or limit, or use mode=files, to inspect omitted matches.",
+		),
+		costLatency: "local_medium",
+	},
+	[ToolNames.Find]: {
+		objective: "Find paths by glob pattern with optional mtime ordering.",
+		uiLabel: "Find",
+		retrySafety: "idempotent",
+		resultSizePolicy: observePolicy(
+			OBSERVE_SELF_CAPS.find,
+			"Refine the pattern, path, or limit to inspect omitted paths.",
+		),
+		costLatency: "local_medium",
+	},
+	[ToolNames.Ls]: {
+		objective: "List directory entries.",
+		uiLabel: "List",
+		retrySafety: "idempotent",
+		resultSizePolicy: observePolicy(OBSERVE_SELF_CAPS.ls, "Raise limit or list a narrower directory."),
+		costLatency: "local_fast",
+	},
+	[ToolNames.CodeNav]: {
+		objective: "Navigate the codewiki index by symbol, path, entry points, outline, imports, or importers.",
+		uiLabel: "Nav",
+		retrySafety: "idempotent",
+		resultSizePolicy: observePolicy(OBSERVE_SELF_CAPS.codeNav, "Raise limit or use a narrower mode/query."),
+		costLatency: "local_fast",
+		promptHint:
+			"Use code_nav for indexed code navigation (modes: symbol, path, entries, outline, deps, dependents, wiki).",
+	},
+	[ToolNames.Context]: {
+		objective: "Return workspace, bundled-docs, or skill context.",
+		uiLabel: "Context",
+		retrySafety: "idempotent",
+		resultSizePolicy: observePolicy(
+			Math.max(OBSERVE_SELF_CAPS.contextDocs, OBSERVE_SELF_CAPS.contextSkills, OBSERVE_SELF_CAPS.contextWorkspace),
+			"Use a narrower query or scope to inspect omitted content.",
+		),
+		costLatency: "local_fast",
+		promptHint:
+			'Call context with scope="skills" to list available skills; when one matches the task, suggest the operator run /skill:<name> and never load it uninvited. When the user message carries a skill request, first load that skill via context (scope="skills", name=<skill>) before doing anything else.',
+	},
+	[ToolNames.CredentialPresent]: {
+		objective: "Check whether a credential key is present without returning its value.",
+		uiLabel: "Credential",
+		retrySafety: "idempotent",
+		resultSizePolicy: {
+			kind: "exact",
+			maxBytes: 4_096,
+			followUpHint: "Use the boolean result only; never ask to print the credential value.",
+		},
+		costLatency: "local_fast",
+	},
+	// MUTATE: write-class, sequential, file-mutation queue.
+	[ToolNames.Write]: {
+		objective: "Write a complete UTF-8 file.",
+		uiLabel: "Write",
+		retrySafety: "not_retry_safe",
+		resultSizePolicy: exactMutationPolicy,
+		costLatency: "local_fast",
+	},
+	[ToolNames.Edit]: {
+		objective: "Apply exact text replacements to one file.",
+		uiLabel: "Edit",
+		retrySafety: "not_retry_safe",
+		resultSizePolicy: exactMutationPolicy,
+		costLatency: "local_fast",
+	},
+	// EXECUTE: the safe-exec spine (bash offloads its own overflow).
+	[ToolNames.Bash]: {
+		objective: "Execute an explicit shell command when narrower tools are insufficient.",
+		uiLabel: "Shell",
+		retrySafety: "unknown",
+		resultSizePolicy: summaryPolicy(
+			"Use a narrower command or a dedicated verification/read/search tool to inspect omitted output.",
+		),
+		costLatency: "local_slow",
+	},
+	[ToolNames.Git]: {
+		objective: "Read-only git inspection: status, diff, or log.",
+		uiLabel: "Git",
+		retrySafety: "idempotent",
+		resultSizePolicy: summaryPolicy("Limit the diff/log to one path or fewer commits."),
+		costLatency: "local_fast",
+	},
+	[ToolNames.Verify]: {
+		objective: "Run declared verification checks (scripts or frontend artifacts).",
+		uiLabel: "Verify",
+		retrySafety: "retry_safe",
+		resultSizePolicy: summaryPolicy(
+			"Rerun the check with narrower args or inspect the named failing file/test directly.",
+		),
+		costLatency: "local_slow",
+	},
+	// ORCHESTRATE: agent-class, receipts as evidence.
+	[ToolNames.Tasks]: {
+		objective: "Declare and track the session task board with evidence-carrying completions.",
+		uiLabel: "Tasks",
+		// A repeated plan/start/done lands on the same board state; a repeated
+		// add duplicates a task, so the surface as a whole is not retry safe.
+		retrySafety: "not_retry_safe",
+		resultSizePolicy: {
+			kind: "exact",
+			maxBytes: 8_192,
+			followUpHint: 'Call tasks with action="list" to re-read the board.',
+		},
+		costLatency: "local_fast",
+		promptHint:
+			'When a request contains three or more distinct steps, declare the board before your first edit: tasks action="plan" with a title and the task list. ' +
+			'Mark one task active with "start" before working it, close it with "done" plus an evidence note ' +
+			'(what proves it works), and use "block" with a reason instead of silently stalling.',
+	},
+	[ToolNames.Ledger]: {
+		objective: "Coordinate with the peer workers of this dispatch through typed claims, findings, and reviews.",
+		uiLabel: "Ledger",
+		// A repeated post lands a second entry and spends another of the run's
+		// twenty posts, so the surface as a whole is not retry safe.
+		retrySafety: "not_retry_safe",
+		resultSizePolicy: {
+			kind: "exact",
+			maxBytes: 16_384,
+			followUpHint: 'Call ledger with action="read" and a since sequence to re-read only what is new.',
+		},
+		costLatency: "local_fast",
+	},
+	[ToolNames.Dispatch]: {
+		objective: "Dispatch bounded tasks to configured Clio workers.",
+		uiLabel: "Dispatch",
+		retrySafety: "not_retry_safe",
+		resultSizePolicy: summaryPolicy(
+			"Use the dispatch receipt paths or ask a narrower worker follow-up for omitted output.",
+		),
+		costLatency: "agent",
+		promptHint:
+			"Call dispatch with list:true only when the operator asks about agents, workers, or the fleet; never use it to inventory direct tools.",
+	},
+	[ToolNames.Monitor]: {
+		objective: "Inspect dispatched runs: state, recent events, receipts.",
+		uiLabel: "Monitor",
+		retrySafety: "idempotent",
+		resultSizePolicy: summaryPolicy("Use monitor(mode=receipt) or read the receipt path for full details."),
+		costLatency: "local_fast",
+	},
+	[ToolNames.Steer]: {
+		objective: "Guide or cancel a running dispatched worker.",
+		uiLabel: "Steer",
+		retrySafety: "not_retry_safe",
+		resultSizePolicy: {
+			kind: "exact",
+			maxBytes: 4_096,
+			followUpHint: "Use monitor(mode=status) to confirm the run state after steering.",
+		},
+		costLatency: "local_fast",
+	},
+	// RETRIEVE: network-class.
+	[ToolNames.WebFetch]: {
+		objective: "Fetch HTTP(S) text for explicit external research.",
+		uiLabel: "Fetch",
+		retrySafety: "retry_safe",
+		resultSizePolicy: {
+			kind: "bounded",
+			maxBytes: 16_384,
+			followUpHint: "Fetch a narrower URL or lower max_bytes to inspect a specific section.",
+		},
+		costLatency: "network",
+	},
+	// INTERACT: operator dialogue.
+	[ToolNames.AskUser]: {
+		objective: "Ask the operator structured questions.",
+		uiLabel: "Ask",
+		retrySafety: "not_retry_safe",
+		resultSizePolicy: {
+			kind: "exact",
+			maxBytes: 20_000,
+			followUpHint: "Proceed with stated assumptions if the operator cancels or no UI is available.",
+		},
+		costLatency: "local_slow",
+		promptHint:
+			'Use ask_user only when blocked on a decision the request does not answer; never ask about anything the operator already stated. One question per round in interview workflows, up to four tightly related questions otherwise, recommended option first. Finish with action="complete" and a compact decisions array before final prose. If cancelled, continue with defaults and do not ask again.',
+	},
+	// ARTIFACT: terminal writers.
+	[ToolNames.Artifact]: {
+		objective: "Write terminal plan/review/report documents that complete the turn.",
+		uiLabel: "Artifact",
+		retrySafety: "not_retry_safe",
+		resultSizePolicy: exactMutationPolicy,
+		costLatency: "local_fast",
+	},
+};
+
+/** Canonical, registry-owned prompt hints for an already-admitted tool set. */
+export function toolPromptHintsForNames(names: ReadonlyArray<ToolName>): ReadonlyArray<{ tool: string; hint: string }> {
+	const seen = new Set<string>();
+	const hints: Array<{ tool: string; hint: string }> = [];
+	for (const name of [...names].sort()) {
+		if (seen.has(name)) continue;
+		seen.add(name);
+		const hint = TOOL_METADATA[name]?.promptHint?.trim();
+		if (hint) hints.push({ tool: name, hint });
+	}
+	return hints;
+}
+
+function withBuiltinMetadata<T extends ToolSpec>(spec: T): T {
+	const metadata = TOOL_METADATA[spec.name];
+	return metadata ? withMetadata(spec, metadata) : spec;
+}
+
+function builtin<T extends ToolSpec>(spec: T, sourceInfo: ToolSourceInfo): T {
+	return withBuiltinMetadata(withSourceInfo(spec, sourceInfo));
+}
+
+/**
+ * Registers every tool on the supplied registry, grouped by plane. The
+ * context tool gains its workspace scope only when a session contract is
+ * supplied; dispatch/monitor/steer register only with a dispatch contract;
+ * the RETRIEVE plane is omitted when the process asked to be hermetic
+ * (tools/network-policy.ts), which is what makes a run without network a
+ * surface the model never sees rather than a call it can make and have denied.
+ */
+export function registerAllTools(registry: ToolRegistry, deps: ToolBootstrapDeps = {}): void {
+	const includeNetworkTools = !networkToolsDisabled();
+	registry.register({
+		...builtin(readTool, { path: "src/tools/read.ts", scope: "core" }),
+	});
+	registry.register({
+		...builtin(writeTool, { path: "src/tools/write.ts", scope: "core" }),
+	});
+	registry.register({
+		...builtin(editTool, { path: "src/tools/edit.ts", scope: "core" }),
+	});
+	registry.register({
+		...builtin(bashTool, { path: "src/tools/bash.ts", scope: "core" }),
+	});
+	registry.register({
+		...builtin(grepTool, { path: "src/tools/grep.ts", scope: "core" }),
+	});
+	registry.register({
+		...builtin(findTool, { path: "src/tools/find.ts", scope: "core" }),
+	});
+	registry.register({
+		...builtin(lsTool, { path: "src/tools/ls.ts", scope: "core" }),
+	});
+	if (includeNetworkTools) {
+		registry.register({
+			...builtin(webFetchTool, { path: "src/tools/web-fetch.ts", scope: "core" }),
+		});
+	}
+	registry.register({
+		...builtin(gitTool, { path: "src/tools/safe-exec.ts", scope: "core" }),
+	});
+	registry.register({
+		...builtin(verifyTool, { path: "src/tools/verify/index.ts", scope: "core" }),
+	});
+	registry.register({
+		...builtin(codeNavTool, { path: "src/tools/codewiki/code-nav.ts", scope: "core" }),
+	});
+	const skillToolDeps = {
+		getCwd: () => deps.session?.current()?.cwd ?? process.cwd(),
+		...(deps.getSkillLoaderOptions ? { getSkillLoaderOptions: deps.getSkillLoaderOptions } : {}),
+	};
+	if (deps.askUser) {
+		registry.register({
+			...builtin(createAskUserTool({ askUser: deps.askUser }), {
+				path: "src/tools/ask-user.ts",
+				scope: "core",
+			}),
+		});
+	}
+	registry.register({
+		...builtin(credentialPresentTool, { path: "src/tools/credential-present.ts", scope: "core" }),
+	});
+	const session = deps.session;
+	registry.register({
+		...builtin(
+			createContextTool({
+				...skillToolDeps,
+				...(session
+					? {
+							workspace: {
+								hasSession: () => session.current() !== null,
+								getSnapshot: () => session.current()?.workspace ?? null,
+								probeWorkspace: () => probeWorkspace(session.current()?.cwd ?? process.cwd()),
+								saveSnapshot: (snap) => {
+									const meta = session.current();
+									if (meta) meta.workspace = snap;
+								},
+							},
+						}
+					: {}),
+			}),
+			{ path: "src/tools/context/index.ts", scope: "core" },
+		),
+	});
+	registry.register({
+		...builtin(createArtifactTool({ getCwd: skillToolDeps.getCwd }), { path: "src/tools/artifact.ts", scope: "core" }),
+	});
+	registry.register({
+		...builtin(createLedgerTool(deps.agentLedger ? { agentLedger: deps.agentLedger } : {}), {
+			path: "src/tools/ledger.ts",
+			scope: "core",
+		}),
+	});
+	registry.register({
+		...builtin(createTasksTool({ board: deps.taskBoard ?? createTaskBoardStore() }), {
+			path: "src/tools/tasks.ts",
+			scope: "core",
+		}),
+	});
+	if (deps.dispatch) {
+		const dispatchRunEvents = createDispatchRunEventRegistry();
+		const dispatchToolDeps = {
+			dispatch: deps.dispatch,
+			runEvents: dispatchRunEvents,
+			getAgentSpecs: deps.getAgentSpecs ?? (() => []),
+			...(deps.bus ? { bus: deps.bus } : {}),
+			...(deps.getAgentCatalog ? { getAgentCatalog: deps.getAgentCatalog } : {}),
+			...(deps.getAgentRoleFacts ? { getAgentRoleFacts: deps.getAgentRoleFacts } : {}),
+			...(deps.getAutonomy ? { getAutonomy: deps.getAutonomy } : {}),
+			...(deps.getCostCeilingUsd ? { getCostCeilingUsd: deps.getCostCeilingUsd } : {}),
+			...(deps.dispatchBackground ? { background: deps.dispatchBackground } : {}),
+		};
+		registry.register({
+			...builtin(createDispatchTool(dispatchToolDeps), {
+				path: "src/tools/dispatch.ts",
+				scope: "core",
+			}),
+		});
+		registry.register({
+			...builtin(createMonitorTool({ dispatch: deps.dispatch, runEvents: dispatchRunEvents }), {
+				path: "src/tools/monitor.ts",
+				scope: "core",
+			}),
+		});
+		registry.register({
+			...builtin(createSteerTool({ dispatch: deps.dispatch }), {
+				path: "src/tools/steer.ts",
+				scope: "core",
+			}),
+		});
+	}
+
+	assertBuiltinToolPolicy(registry.listAll(), {
+		includeSessionTools: Boolean(session),
+		includeDispatchTools: Boolean(deps.dispatch),
+		includeInteractiveTools: Boolean(deps.askUser),
+		includeNetworkTools,
+	});
+}