@iowarp/clio-coder 0.3.0 → 0.3.2

package/src/tools/bash.ts

@@ -0,0 +1,204 @@
+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;
+}
+
+/** Bound a cumulative live snapshot without writing an offload file per tick. */
+function shapeBashProgress(rawOutput: string): ToolResult {
+	const truncation = truncateTail(rawOutput, {
+		maxLines: DEFAULT_MAX_LINES,
+		maxBytes: BASH_DISPLAY_MAX_BYTES - BASH_TAIL_NOTE_RESERVE,
+	});
+	const bytes = Buffer.byteLength(rawOutput, "utf8");
+	return {
+		kind: "ok",
+		output: truncation.content,
+		details: {
+			resultSize: {
+				bytes,
+				shownBytes: truncation.outputBytes,
+				maxBytes: BASH_DISPLAY_MAX_BYTES,
+				truncated: truncation.truncated,
+				policy: "tail",
+			},
+		},
+	};
+}
+
+// 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 runOptions: Parameters<typeof runBashCommand>[1] = {
+				cwd,
+				timeoutMs: timeout,
+				...(options?.signal === undefined ? {} : { signal: options.signal }),
+			};
+			if (options?.onUpdate !== undefined) {
+				runOptions.onUpdate = (progress) => {
+					options.onUpdate?.(shapeBashProgress(combineBashOutput(progress)));
+				};
+			}
+			const result = await runBashCommand(args.command, runOptions);
+			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,77 @@
+import type { SafeEventBus } from "../core/event-bus.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 { AutonomyLevel } from "../domains/safety/autonomy.js";
+import { builtin, toolPromptHintsForNames } from "./builtin-tool-catalog.js";
+import { assertRegisteredBuiltinTools, type CoreToolBootstrapDeps, registerCoreTools } from "./core-bootstrap.js";
+import { createDispatchRunEventRegistry, createDispatchTool } from "./dispatch.js";
+import type { DispatchBackgroundRegistry } from "./dispatch-background.js";
+import { lazyTool } from "./lazy-tool.js";
+import { monitorToolSurface } from "./monitor-surface.js";
+import type { ToolRegistry } from "./registry.js";
+import { steerToolSurface } from "./steer-surface.js";
+
+export { toolPromptHintsForNames };
+
+export interface ToolBootstrapDeps extends CoreToolBootstrapDeps {
+	dispatch?: DispatchContract;
+	bus?: SafeEventBus;
+	getAgentCatalog?: () => string;
+	getAgentSpecs?: () => ReadonlyArray<AgentSpec>;
+	getAgentRoleFacts?: AgentRoleFactsResolver;
+	getAutonomy?: () => AutonomyLevel;
+	getCostCeilingUsd?: () => number;
+	dispatchBackground?: DispatchBackgroundRegistry;
+}
+
+/**
+ * Registers the stable core surface first, then the orchestrator-only dispatch
+ * controls in their canonical order. Worker registries call registerCoreTools
+ * directly so their boot graph never evaluates dispatch implementations.
+ */
+export function registerAllTools(registry: ToolRegistry, deps: ToolBootstrapDeps = {}): void {
+	const registration = registerCoreTools(registry, deps);
+	if (deps.dispatch) {
+		const dispatch = deps.dispatch;
+		const dispatchRunEvents = createDispatchRunEventRegistry();
+		const dispatchToolDeps = {
+			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(
+				lazyTool(monitorToolSurface, async () =>
+					(await import("./monitor.js")).createMonitorTool({ dispatch, runEvents: dispatchRunEvents }),
+				),
+				{
+					path: "src/tools/monitor.ts",
+					scope: "core",
+				},
+			),
+		});
+		registry.register({
+			...builtin(
+				lazyTool(steerToolSurface, async () => (await import("./steer.js")).createSteerTool({ dispatch })),
+				{
+					path: "src/tools/steer.ts",
+					scope: "core",
+				},
+			),
+		});
+	}
+	assertRegisteredBuiltinTools(registry, registration, Boolean(deps.dispatch));
+}

package/src/tools/builtin-tool-catalog.ts

@@ -0,0 +1,265 @@
+import { type ToolName, ToolNames } from "../core/tool-names.js";
+import { OBSERVATION_POLICY_SLACK_BYTES, OBSERVE_SELF_CAPS } from "./observation.js";
+import { readMaxBytes } from "./read.js";
+import type { ToolMetadata, ToolSourceInfo, ToolSpec } from "./registry.js";
+
+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 installed and marketplace skills; when one matches the task, or the operator names a skill or asks how one works, suggest the operator run /skill <name> (a marketplace skill is offered for install) 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;
+}
+
+export function builtin<T extends ToolSpec>(spec: T, sourceInfo: ToolSourceInfo): T {
+	return withBuiltinMetadata(withSourceInfo(spec, sourceInfo));
+}

package/src/tools/codewiki/code-nav-surface.ts

@@ -0,0 +1,29 @@
+import { Type } from "typebox";
+import { ToolNames } from "../../core/tool-names.js";
+import { StringEnum } from "../../engine/ai.js";
+import type { ToolSurface } from "../lazy-tool.js";
+
+export const CODE_NAV_DEFAULT_LIMIT = 50;
+export const CODE_NAV_DEFAULT_ENTRY_LIMIT = 25;
+export const CODE_NAV_MAX_LIMIT = 200;
+
+export const codeNavToolSurface = {
+	name: ToolNames.CodeNav,
+	description:
+		"Navigate the indexed codewiki: mode=symbol finds files by symbol, path finds files by glob/regex/substring, entries lists likely entry points, outline lists file symbols, deps lists imports, and dependents lists importers. mode=wiki without query lists generated Markdown wiki pages; with query it resolves a page id/title and returns its summary plus a path to open with read. For Clio's bundled product docs use context scope=docs.",
+	parameters: Type.Object({
+		mode: StringEnum(["symbol", "path", "entries", "outline", "deps", "dependents", "wiki"], {
+			description: "Lookup mode.",
+		}),
+		query: Type.Optional(
+			Type.String({ description: "Symbol name, indexed path/pattern/substring, or wiki page id/title." }),
+		),
+		limit: Type.Optional(
+			Type.Number({
+				description: `Max results (default ${CODE_NAV_DEFAULT_LIMIT}, entries ${CODE_NAV_DEFAULT_ENTRY_LIMIT}, max ${CODE_NAV_MAX_LIMIT}).`,
+			}),
+		),
+	}),
+	baseActionClass: "read",
+	executionMode: "parallel",
+} satisfies ToolSurface;