@iowarp/clio-coder 0.4.1 → 0.4.2

package/src/interactive/turn-context.ts

@@ -81,7 +81,7 @@ import {
 	type SessionPromptCompileRecord,
 } from "../domains/session/prompt-manifest.js";
 import type { AgentMessage, Usage } from "../engine/types.js";
-import type { ToolRegistry } from "../tools/registry.js";
+import { resolveToolPromptHint, type ToolRegistry } from "../tools/registry.js";
 import {
 	backendCacheVerdict,
 	extractUserText,
@@ -90,6 +90,7 @@ import {
 	toolNamesFromAgentState,
 } from "./chat-loop-messages.js";
 import { buildModelReplayAgentMessagesFromTurns } from "./model-session-replay.js";
+import { attachedToolSchemasFromState, mainPromptCacheIdentity } from "./prompt-cache-identity.js";
 import { renderCompactionSummaryLine, renderEvictionSkipLine } from "./renderers/compaction-summary.js";
 import type { TurnMiddleware } from "./turn-middleware.js";
 import type { AgentRuntime, ChatTurnState } from "./turn-state.js";
@@ -270,8 +271,8 @@ export function createTurnContext(deps: TurnContextDeps): TurnContext {
 	// before the operator did.
 	let lastPrewarm: PrewarmStats | null = null;
 	// The session system prompt, compiled once per session. Recompiles happen
-	// only on explicit events: the compile key (target, model, safety level,
-	// session id) changes, or a config hot-reload invalidates the cache. A
+	// only when the canonical identity of every live compile input changes, or
+	// a config hot-reload invalidates compiler-owned inputs. A
 	// recompile that changes the prompt text appends a "promptRecompiled"
 	// ledger entry so a cold provider cache is always explainable.
 	let sessionPrompt: CompiledSessionPrompt | null = null;
@@ -1021,8 +1022,8 @@ export function createTurnContext(deps: TurnContextDeps): TurnContext {
 
 		/**
 		 * Ensure the session system prompt is compiled and applied to the live
-		 * agent. Compiles only when the compile key (target, model, safety
-		 * level, session id) changes or a config hot-reload invalidated the
+		 * agent. Compiles only when the canonical live-input identity changes
+		 * or a config hot-reload invalidated compiler-owned inputs in the
 		 * cache; every other submit reuses the cached prompt byte-for-byte. A
 		 * compile whose text differs from the previous prompt queues a
 		 * "promptRecompiled" ledger entry (written once the session exists).
@@ -1032,14 +1033,9 @@ export function createTurnContext(deps: TurnContextDeps): TurnContext {
 			const settings = deps.getSettings();
 			const autonomy = settings.safety.autonomy ?? "auto-edit";
 			const sessionId = deps.session?.current()?.id ?? "";
-			const workingContextKey = [...sessionWorkingContextPaths].sort().join("\0");
-			const key = `${agentRuntime.targetId}|${agentRuntime.wireModelId}|${autonomy}|${sessionId}|${workingContextKey}`;
-			if (sessionPrompt && sessionPromptKey === key) {
-				lastSystemPromptReused = true;
-				return sessionPrompt;
-			}
+			const cwd = process.cwd();
 			const modelState = agentRuntime.agent.state.model as
-				| (typeof agentRuntime.agent.state.model & { clio?: { quirks?: LocalModelQuirks } })
+				| (typeof agentRuntime.agent.state.model & { clioCoder?: { quirks?: LocalModelQuirks } })
 				| undefined;
 			// `Context window: N` is the window the backend will actually serve
 			// this session, taken from the resolution the turn already ran rather
@@ -1057,13 +1053,14 @@ export function createTurnContext(deps: TurnContextDeps): TurnContext {
 			const contextWindow = typeof resolvedWindow === "number" && resolvedWindow > 0 ? resolvedWindow : null;
 			const contextWindowSource: ContextWindowSource | null =
 				contextWindow === null ? null : windowDetails.contextWindowSource;
-			const guidance = modelState?.clio?.quirks?.thinking?.guidance;
+			const guidance = modelState?.clioCoder?.quirks?.thinking?.guidance;
 			// Per-tool prompt hints come from registry metadata, derived once from
 			// the frozen surface per compile. The compiler renders them sorted by
 			// tool name, so the compiled text stays byte-stable for a given surface.
 			const toolNames = toolNamesFromAgentState(agentRuntime.agent.state.tools);
+			const attachedToolSchemas = attachedToolSchemasFromState(agentRuntime.agent.state.tools);
 			const toolPromptHints = toolNames.flatMap((name) => {
-				const hint = deps.toolRegistry?.get(name as ToolName)?.metadata?.promptHint;
+				const hint = resolveToolPromptHint(deps.toolRegistry?.get(name as ToolName)?.metadata?.promptHint, "session");
 				return hint ? [{ tool: name, hint }] : [];
 			});
 			const sessionInputs: SessionPromptInputs = {
@@ -1085,11 +1082,29 @@ export function createTurnContext(deps: TurnContextDeps): TurnContext {
 					);
 				}
 			}
+			const key = mainPromptCacheIdentity({
+				targetId: agentRuntime.targetId,
+				runtimeId: agentRuntime.runtimeId,
+				wireModelId: agentRuntime.wireModelId,
+				autonomy,
+				sessionId,
+				cwd,
+				workingContextPaths: [...sessionWorkingContextPaths],
+				contextWindowSource,
+				promptInputEpoch: deps.prompts.inputEpoch(),
+				sessionInputs,
+				attachedToolSchemas,
+			});
+			if (sessionPrompt && sessionPromptKey === key) {
+				lastSystemPromptReused = true;
+				return sessionPrompt;
+			}
 			try {
 				const result = await deps.prompts.compileSessionPrompt({
+					sessionId,
 					sessionInputs,
 					autonomy,
-					cwd: process.cwd(),
+					cwd,
 					workingContextPaths: [...sessionWorkingContextPaths],
 				});
 				const previousHash = sessionPromptHash ?? lastRecordedPromptHash();

package/src/interactive/yazi-bridge.ts

@@ -52,6 +52,10 @@ export type YaziBridgeOpenResult =
 
 export interface YaziBridge {
 	open(options?: { once?: boolean }): Promise<YaziBridgeOpenResult>;
+	/** Close the files pane and hand focus back to the composer; false when nothing was open. */
+	close(): Promise<boolean>;
+	/** True while the pane host still reports the files pane. */
+	isOpen(): boolean;
 	status(): Readonly<YaziBridgeStatus>;
 	dispose(): void;
 }
@@ -312,9 +316,12 @@ export function createYaziBridge(deps: YaziBridgeDeps): YaziBridge {
 		}
 		deps.setDraft(appendDraft(draft, batch.text));
 		deps.requestRender();
+		// The pick is the end of the operator's trip into the files pane, so the
+		// keyboard comes back to the composer without a click.
+		void deps.mux?.focusSelf();
 		deps.notice(
 			"info",
-			`${batch.inserted} ${batch.inserted === 1 ? "path" : "paths"} from the file pane added to the draft`,
+			`${batch.inserted} ${batch.inserted === 1 ? "path" : "paths"} from the files pane added to the draft`,
 		);
 		if (batch.plainPaths > 0) {
 			deps.notice(
@@ -366,6 +373,8 @@ export function createYaziBridge(deps: YaziBridgeDeps): YaziBridge {
 				if (disposed || ownGeneration !== generation) return;
 				paneCwd = choice.cwd;
 				if (choice.paths.length > 0) insert(choice.paths, choice.cwd);
+				// A cancelled pick still ends the trip; the composer gets the keyboard back.
+				else void deps.mux?.focusSelf();
 			},
 			onStopped: () => {
 				if (ownGeneration !== generation) return;
@@ -379,12 +388,16 @@ export function createYaziBridge(deps: YaziBridgeDeps): YaziBridge {
 			return { status: "unavailable", reason: "the file pane was closed while it was opening" };
 		}
 		active = result.session;
+		// An explicit open is a request to go and pick something, so the keyboard
+		// follows the pane. The dock tier itself never steals focus; this is the
+		// one caller entitled to ask.
+		await mux.focusPane(result.session.pane.paneId);
 		if (mode === "companion") {
 			livenessTimer = setTimeout(() => {
 				if (disposed || ownGeneration !== generation || sawLine || active === null) return;
 				const stale = active;
 				active = null;
-				deps.notice("warning", "the file-pane event stream did not start; reopening yazi in chooser mode");
+				deps.notice("warning", "the files pane did not report back in time; reopening it in pick mode");
 				void stale.close().finally(() => {
 					if (!disposed && ownGeneration === generation) void start("chooser", profileMode, dockShare);
 				});
@@ -394,16 +407,49 @@ export function createYaziBridge(deps: YaziBridgeDeps): YaziBridge {
 		return { status: "opened", mode, paneId: result.session.pane.paneId, existing: false };
 	};
 
+	/**
+	 * The pane host is the authority on whether the pane exists. `active` lags
+	 * it by one event at most, but a caller deciding between open and close
+	 * must not be told a pane is open when herdr already reported it gone.
+	 */
+	const liveSession = (): YaziSession | null => {
+		if (active === null) return null;
+		const mux = deps.mux;
+		if (mux?.available() && !mux.list().some((record) => record.ref.paneId === active?.pane.paneId)) {
+			active = null;
+			return null;
+		}
+		return active;
+	};
+
+	const closeActive = async (): Promise<boolean> => {
+		const session = liveSession();
+		if (session === null) return false;
+		generation += 1;
+		clearLiveness();
+		active = null;
+		await session.close();
+		// Closing the dock the operator was looking at would otherwise leave
+		// focus wherever herdr puts it after a close, which is not the composer.
+		await deps.mux?.focusSelf();
+		return true;
+	};
+
 	return {
 		async open(options = {}): Promise<YaziBridgeOpenResult> {
-			if (disposed) return { status: "unavailable", reason: "the file-pane bridge is closed" };
+			if (disposed) return { status: "unavailable", reason: "the files pane bridge is closed" };
 			const settings = deps.getSettings?.() ?? { mode: "companion", profile: "managed", followCwd: true };
-			if (active) {
+			const existing = liveSession();
+			if (existing) {
 				if (settings.followCwd) {
 					const cwd = deps.getCwd();
-					if (await active.pushCwd(cwd)) paneCwd = cwd;
+					if (await existing.pushCwd(cwd)) paneCwd = cwd;
 				}
-				return { status: "opened", mode: active.mode, paneId: active.pane.paneId, existing: true };
+				// Re-opening an open pane means "take me there": leave any zoom that
+				// hides it and put the keyboard in it.
+				await deps.mux?.unzoomSelf();
+				await deps.mux?.focusPane(existing.pane.paneId);
+				return { status: "opened", mode: existing.mode, paneId: existing.pane.paneId, existing: true };
 			}
 			const mode = options.once || settings.profile === "user" ? "chooser" : settings.mode;
 			if (!deps.mux?.available()) {
@@ -426,8 +472,16 @@ export function createYaziBridge(deps: YaziBridgeDeps): YaziBridge {
 				}
 				return result;
 			}
+			await deps.mux.unzoomSelf();
 			return await start(mode, settings.profile, settings.ratio);
 		},
+		close(): Promise<boolean> {
+			if (disposed) return Promise.resolve(false);
+			return closeActive();
+		},
+		isOpen(): boolean {
+			return liveSession() !== null;
+		},
 		status(): Readonly<YaziBridgeStatus> {
 			const snapshot = active?.snapshot();
 			return {

package/src/tools/agent-tools.ts

@@ -296,6 +296,35 @@ function errorMessage(err: unknown): string {
 	return err instanceof Error ? err.message : String(err);
 }
 
+/**
+ * The parameter schema as the provider should see it.
+ *
+ * TypeBox 1.x annotates every schema it builds with string-keyed markers
+ * (`~unsafe` on `Type.Unsafe`, `~optional` on `Type.Optional`, and so on).
+ * Unlike the older symbol keys they survive `JSON.stringify`, so each enum
+ * field reached the model as `{"~unsafe": null, "~optional": true, ...}`:
+ * 44 junk keys on the default surface, and a small model has no way to know
+ * that `"~unsafe": null` means nothing. Validation does not need them
+ * (`Value.Check` answers identically with and without), so the copy handed
+ * to the agent loop drops every `~`-prefixed key. Symbol keys are copied
+ * through untouched because pi-ai picks its coercion path by the TypeBox
+ * kind symbol on the root schema.
+ */
+function wireParameterSchema<T>(schema: T): T {
+	if (Array.isArray(schema)) return schema.map((entry) => wireParameterSchema(entry)) as T;
+	if (typeof schema !== "object" || schema === null) return schema;
+	const source = schema as Record<PropertyKey, unknown>;
+	const out: Record<PropertyKey, unknown> = {};
+	for (const key of Object.keys(source)) {
+		if (key.startsWith("~")) continue;
+		out[key] = wireParameterSchema(source[key]);
+	}
+	for (const symbol of Object.getOwnPropertySymbols(source)) {
+		out[symbol] = source[symbol];
+	}
+	return out as T;
+}
+
 function toAgentTool(
 	spec: ToolSpec,
 	registry: ToolRegistry,
@@ -305,7 +334,7 @@ function toAgentTool(
 	const tool: AgentTool<TSchema> = {
 		name: spec.name,
 		description: spec.description,
-		parameters: spec.parameters,
+		parameters: wireParameterSchema(spec.parameters),
 		label: spec.metadata?.uiLabel ?? spec.name,
 		async execute(
 			toolCallId: string,

package/src/tools/artifact.ts

@@ -20,7 +20,7 @@ import type { ToolResult, ToolSpec } from "./registry.js";
  * tree holds files a human asked for, and everything Clio generates on its own
  * belongs in the gitignored project directory. An explicit `path` still writes
  * wherever the caller says, inside the workspace. See core/artifact-paths.ts
- * and docs/artifact-placement.md.
+ * and docs/architecture/artifact-placement.md.
  *
  * Skills are not artifacts: a skill is a SKILL.md folder written with the
  * ordinary write tool and validated by the skills loader on load. The
@@ -83,7 +83,7 @@ async function writeTerminalArtifact(
 export function createArtifactTool(deps: ArtifactToolDeps = {}): ToolSpec {
 	return {
 		name: ToolNames.Artifact,
-		description: `Write a named artifact: kind=plan|review|report writes a terminal Markdown document and completes the turn. Without an explicit path it lands in ${CLIO_ARTIFACT_DIR}/ (PLAN.md, REVIEW.md, REPORT.md); pass path only when the user asked for a file at a specific place.`,
+		description: `Write a named artifact: kind=plan|review|report writes a terminal Markdown document and completes the turn, so close the task board (tasks done/block/drop) before writing it. Without an explicit path it lands in ${CLIO_ARTIFACT_DIR}/ (PLAN.md, REVIEW.md, REPORT.md); pass path only when the user asked for a file at a specific place.`,
 		parameters: Type.Object({
 			kind: StringEnum(ARTIFACT_KINDS, { description: "Artifact kind." }),
 			content: Type.String({ description: "Full Markdown body." }),

package/src/tools/ask-user.ts

@@ -92,13 +92,13 @@ export interface AskUserToolDeps {
 export const askUserParameters = Type.Object({
 	action: Type.Optional(
 		StringEnum(["ask", "complete"], {
-			description: "ask presents a round of questions; complete (exactly once) records decisions before final prose.",
+			description: "ask presents a round of questions; complete records the decisions, once, before final prose.",
 		}),
 	),
 	mode: Type.Optional(
 		StringEnum(["round", "single_question"], {
 			description:
-				"Caps how many questions this call may carry. single_question accepts exactly 1 and rejects the call otherwise (interviews); round accepts 1 to 4 tightly related confirmations. Default is round.",
+				"round (default) accepts 1 to 4 tightly related questions; single_question accepts exactly one, for interviews.",
 		}),
 	),
 	questions: Type.Optional(
@@ -135,7 +135,7 @@ export const askUserParameters = Type.Object({
 	exposure: Type.Optional(
 		StringEnum(["local", "outward"], {
 			description:
-				"Blast radius of this gate. local (default) stays inside the workspace. outward means answering it publishes or sends something the operator cannot take back (filing an issue or PR, posting a comment, pushing, releasing); at autonomy auto-edit an outward gate parks for the operator instead of being answered automatically.",
+				"local (default) stays inside the workspace; outward publishes or sends something the operator cannot take back (issue, PR, comment, push, release) and parks for the operator at auto-edit.",
 		}),
 	),
 });

package/src/tools/bash.ts

@@ -163,7 +163,7 @@ export const bashTool: ToolSpec = {
 		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.",
+					"Omit unless the command must run in a subdirectory of the workspace root, given as a relative path; outside the root is blocked.",
 			}),
 		),
 		timeout_ms: Type.Optional(Type.Number({ description: "Timeout in milliseconds." })),

package/src/tools/bootstrap.ts

@@ -10,6 +10,7 @@ import type { CompeteMuxWorktrees } from "./compete-worktrees.js";
 import { assertRegisteredBuiltinTools, type CoreToolBootstrapDeps, registerCoreTools } from "./core-bootstrap.js";
 import { createDispatchRunEventRegistry, createDispatchTool } from "./dispatch.js";
 import type { DispatchBackgroundRegistry } from "./dispatch-background.js";
+import type { DispatchSchemaComposition } from "./dispatch-schema.js";
 import { lazyTool } from "./lazy-tool.js";
 import { monitorToolSurface } from "./monitor-surface.js";
 import { panesToolSurface } from "./panes-surface.js";
@@ -27,6 +28,8 @@ export interface ToolBootstrapDeps extends CoreToolBootstrapDeps {
 	getAutonomy?: () => AutonomyLevel;
 	getCostCeilingUsd?: () => number;
 	getWorkerRosters?: () => WorkerRosters;
+	/** Which optional `dispatch` schema blocks this session advertises; absent means every block. */
+	getDispatchSchemaComposition?: () => DispatchSchemaComposition;
 	dispatchBackground?: DispatchBackgroundRegistry;
 	/** Optional herdr worktree lifecycle for compete candidates. */
 	competeMuxWorktrees?: CompeteMuxWorktrees;
@@ -61,6 +64,7 @@ export function registerAllTools(registry: ToolRegistry, deps: ToolBootstrapDeps
 			...(deps.getAutonomy ? { getAutonomy: deps.getAutonomy } : {}),
 			...(deps.getCostCeilingUsd ? { getCostCeilingUsd: deps.getCostCeilingUsd } : {}),
 			...(deps.getWorkerRosters ? { getWorkerRosters: deps.getWorkerRosters } : {}),
+			...(deps.getDispatchSchemaComposition ? { getSchemaComposition: deps.getDispatchSchemaComposition } : {}),
 			...(deps.dispatchBackground ? { background: deps.dispatchBackground } : {}),
 			...(deps.competeMuxWorktrees ? { competeWorktrees: { mux: deps.competeMuxWorktrees } } : {}),
 		};

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

@@ -4,7 +4,13 @@ import { BASH_DEFAULT_RESULT_DISPOSITION } from "./bash.js";
 import { OBSERVATION_POLICY_SLACK_BYTES, OBSERVE_SELF_CAPS } from "./observation.js";
 import { toolPresentationPolicy } from "./presentation.js";
 import { readMaxBytes } from "./read.js";
-import type { ToolMetadata, ToolSourceInfo, ToolSpec } from "./registry.js";
+import {
+	resolveToolPromptHint,
+	type ToolMetadata,
+	type ToolPromptHintRole,
+	type ToolSourceInfo,
+	type ToolSpec,
+} from "./registry.js";
 
 function withSourceInfo<T extends ToolSpec>(spec: T, sourceInfo: ToolSourceInfo): T {
 	return { ...spec, sourceInfo };
@@ -83,7 +89,7 @@ const TOOL_METADATA: Readonly<Record<string, ToolMetadata>> = {
 		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).",
+			"Use code_nav with source=workspace (default) for project code and source=clio for Clio's shipped code map; modes: symbol, path, entries, outline, deps, dependents, wiki (workspace only).",
 	},
 	[ToolNames.Context]: {
 		objective: "Return workspace, bundled-docs, or skill context.",
@@ -94,8 +100,14 @@ const TOOL_METADATA: Readonly<Record<string, ToolMetadata>> = {
 			"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; a [Marketplace] reminder naming an uninstalled skill may instead be offered through ask_user with its exact options, and the harness performs any install. When the user message carries a skill request, first load that skill via context (scope="skills", name=<skill>) before doing anything else. When an [evicted ...] marker names content you need, recall it with context(scope="recall", ref=...); re-read the file only when the marker says it changed.',
+		promptHint: {
+			session:
+				'On an explicit pending skill request, first load exactly that skill with context(scope="skills", name=<skill>). Follow a [Marketplace] reminder\'s exact ask_user options. Recall needed [evicted ...] content with context(scope="recall", ref=...).',
+			worker:
+				'This worker has no operator skill-activation channel; do not load or suggest skills. Recall needed [evicted ...] content with context(scope="recall", ref=...).',
+			boundWorker:
+				'Load only the harness-activated recipe-bound skills named in the persona, and only when they match the assigned task. This worker cannot install or suggest marketplace skills. Recall needed [evicted ...] content with context(scope="recall", ref=...).',
+		},
 	},
 	[ToolNames.CredentialPresent]: {
 		objective: "Check whether a credential key is present without returning its value.",
@@ -135,7 +147,7 @@ const TOOL_METADATA: Readonly<Record<string, ToolMetadata>> = {
 		resultDisposition: BASH_DEFAULT_RESULT_DISPOSITION,
 		costLatency: "local_slow",
 		promptHint:
-			"Bash output_policy defaults to bounded diagnostic tail. Use summary for noisy commands, metadata-only when only outcome and retrieval matter, and full only when output is known to fit the bounded result budget.",
+			"bash output_policy: omit for a bounded tail; summary for noisy commands; metadata-only when only the outcome matters; full only when the output is known to fit.",
 	},
 	[ToolNames.Git]: {
 		objective: "Read-only git inspection: status, diff, or log.",
@@ -167,9 +179,8 @@ const TOOL_METADATA: Readonly<Record<string, ToolMetadata>> = {
 		},
 		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.',
+			'For a request with three or more distinct steps, declare the board before the first edit: tasks(action="plan") with a title and the task list. ' +
+			"start one task before working it, close it with done plus an evidence note, and block with a reason instead of stalling.",
 	},
 	[ToolNames.Ledger]: {
 		objective: "Coordinate with the peer workers of this dispatch through typed claims, findings, and reviews.",
@@ -191,9 +202,10 @@ const TOOL_METADATA: Readonly<Record<string, ToolMetadata>> = {
 		resultSizePolicy: summaryPolicy(
 			"Use the dispatch receipt paths or ask a narrower worker follow-up for omitted output.",
 		),
+		// No hint: the Tool Contract's inventory line already says when
+		// dispatch(list:true) is the right answer, and the Fleet section says
+		// everything else about routing.
 		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.",
@@ -226,7 +238,7 @@ const TOOL_METADATA: Readonly<Record<string, ToolMetadata>> = {
 		},
 		costLatency: "local_fast",
 		promptHint:
-			'When the operator asks to see a dispatched agent ("show me the tester"), call panes with action="show" and the agent id. Utility panes are presets only; an arbitrary command is the operator\'s own /panes open.',
+			'When the operator asks to see a dispatched agent ("show me the tester"), call panes(action="show", target=<agent id>).',
 	},
 	// RETRIEVE: network-class.
 	[ToolNames.WebFetch]: {
@@ -252,7 +264,7 @@ const TOOL_METADATA: Readonly<Record<string, ToolMetadata>> = {
 		},
 		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.',
+			'Use ask_user only when blocked on a decision the request does not answer, never about something the operator already stated: one question per round in interviews, up to four related questions otherwise, recommended option first, then action="complete" with the decisions before final prose.',
 	},
 	// ARTIFACT: terminal writers.
 	[ToolNames.Artifact]: {
@@ -264,15 +276,21 @@ const TOOL_METADATA: Readonly<Record<string, ToolMetadata>> = {
 	},
 };
 
-/** 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>();
+/** Canonical, role-aware prompt hints for an already-admitted tool set. */
+export function toolPromptHintsForNames(
+	names: ReadonlyArray<ToolName>,
+	role: ToolPromptHintRole = "session",
+): ReadonlyArray<{ tool: string; hint: string }> {
+	const seenTools = new Set<string>();
+	const seenHints = 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 });
+		if (seenTools.has(name)) continue;
+		seenTools.add(name);
+		const hint = resolveToolPromptHint(TOOL_METADATA[name]?.promptHint, role);
+		if (!hint || seenHints.has(hint)) continue;
+		seenHints.add(hint);
+		hints.push({ tool: name, hint });
 	}
 	return hints;
 }
@@ -282,9 +300,21 @@ export function toolPromptHintsForNames(names: ReadonlyArray<ToolName>): Readonl
 // live panel (which has no registry) answer the fold question identically.
 function withBuiltinMetadata<T extends ToolSpec>(spec: T): T {
 	const metadata = TOOL_METADATA[spec.name];
-	return metadata
-		? withMetadata(spec, { ...metadata, presentation: toolPresentationPolicy(spec.name, undefined) })
-		: spec;
+	if (!metadata) return spec;
+	// The read cap is a guardrail (`safety.limits.readBytesPerCall`) installed
+	// from settings after this module loads, so the table's import-time value
+	// is the default, not the operator's. Recompute the policy cap when the tool
+	// is registered; the drift check in policy.ts compares against the live cap
+	// and a settings file raising the read cap used to fail boot.
+	const resultSizePolicy =
+		spec.name === ToolNames.Read
+			? observePolicy(readMaxBytes(), metadata.resultSizePolicy?.followUpHint ?? "")
+			: metadata.resultSizePolicy;
+	return withMetadata(spec, {
+		...metadata,
+		...(resultSizePolicy ? { resultSizePolicy } : {}),
+		presentation: toolPresentationPolicy(spec.name, undefined),
+	});
 }
 
 export function builtin<T extends ToolSpec>(spec: T, sourceInfo: ToolSourceInfo): T {

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

@@ -12,6 +12,12 @@ export const codeNavToolSurface = {
 	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({
+		source: Type.Optional(
+			StringEnum(["workspace", "clio"], {
+				description: "Code map source (default workspace).",
+				default: "workspace",
+			}),
+		),
 		mode: StringEnum(["symbol", "path", "entries", "outline", "deps", "dependents", "wiki"], {
 			description: "Lookup mode.",
 		}),