@iowarp/clio-coder 0.4.1 → 0.4.3

package/src/interactive/turn-recovery.ts

@@ -217,6 +217,14 @@ export function createTurnRecovery(deps: TurnRecoveryDeps): TurnRecovery {
 		text: string,
 		initialFailure: TerminalAssistantFailure,
 	): Promise<boolean> => {
+		// A LiteLLM model id can be a deliberate physical route. Retrying it in
+		// Clio obscures the failure, delays operator recovery, and can multiply
+		// attempts beneath a gateway. Preserve and emit the one terminal failure;
+		// the operator can choose another advertised route with /model.
+		if (agentRuntime.runtimeId === "litellm") {
+			ensureFailureVisibleAndPersisted(initialFailure);
+			return true;
+		}
 		const settings = deps.retrySettings();
 		if (!settings.enabled || settings.maxRetries <= 0) return false;
 		if (initialFailure.stopReason === "aborted" || !isRetryableErrorMessage(initialFailure.errorMessage)) return false;

package/src/interactive/turn-runtime.ts

@@ -8,6 +8,7 @@
 import { performance } from "node:perf_hooks";
 import type { BackendCompletionTimings } from "../core/cache-telemetry.js";
 import type { ClioSettings } from "../core/config.js";
+import { gatewayRoutingObservationFromRecord, gatewayRoutingObservationLabel } from "../core/gateway-routing.js";
 import { attributedModelId } from "../core/response-model-id.js";
 import type { MiddlewareToolChoiceControl } from "../domains/middleware/index.js";
 import type { ObservabilityContract } from "../domains/observability/contract.js";
@@ -130,6 +131,8 @@ export interface TurnRuntimeDeps {
 	context: TurnContext;
 	middleware: TurnMiddleware;
 	retrySettings: () => RetrySettings;
+	/** Stable Clio session id forwarded only to gateway runtimes that understand it. */
+	sessionId?: () => string | undefined;
 	emit: (event: AgentEvent | AssistantDeltaEvent) => void;
 	emitNotice: (text: string) => void;
 	/** Tool-call id to its `performance.now()` start mark; spans only, never an instant. */
@@ -447,6 +450,11 @@ export function createTurnRuntime(deps: TurnRuntimeDeps): TurnRuntime {
 			cleanupSessionResources(state.runtime.agent.sessionId);
 		}
 		let getCurrentAgentSignal: () => AbortSignal | undefined = () => undefined;
+		const gatewaySessionId = target.runtime.id === "litellm" ? deps.sessionId?.() : undefined;
+		// message_start can follow response headers. Keep each invocation's
+		// monotonic anchor before that wait, including custom stream delegates.
+		let apiCallStartedAt: number | null = null;
+		let apiCallFirstDeltaAt: number | null = null;
 		const handle = deps.createAgent({
 			initialState: {
 				systemPrompt: fallbackIdentityPrompt(),
@@ -456,6 +464,11 @@ export function createTurnRuntime(deps: TurnRuntimeDeps): TurnRuntime {
 				messages: priorMessages,
 			},
 			maxRetryDelayMs: deps.retrySettings().maxDelayMs,
+			...(gatewaySessionId ? { sessionId: gatewaySessionId } : {}),
+			onStreamInvocation: () => {
+				apiCallStartedAt = performance.now();
+				apiCallFirstDeltaAt = null;
+			},
 			onPayload: async (payload, currentModel) => {
 				const thinkingPatched = patchProviderThinkingPayload(payload, currentModel, state.currentThinkingLevel);
 				const basePayload = thinkingPatched ?? payload;
@@ -575,10 +588,6 @@ export function createTurnRuntime(deps: TurnRuntimeDeps): TurnRuntime {
 
 		let streamStartedAt: number | null = null;
 		let firstAssistantDeltaAt: number | null = null;
-		// Per-API-call timing (T3.2): one assistant message per provider call,
-		// bounded by message_start/message_end; the first delta marks TTFT.
-		let apiCallStartedAt: number | null = null;
-		let apiCallFirstDeltaAt: number | null = null;
 		// First call of the run is the one whose verdict says whether the
 		// backend reused the session prefix; later calls in a tool loop are
 		// trivially warm.
@@ -669,6 +678,15 @@ export function createTurnRuntime(deps: TurnRuntimeDeps): TurnRuntime {
 			}
 			let publicEvent = enrichedEvent;
 			if (enrichedEvent.type === "message_end" && enrichedEvent.message?.role === "assistant") {
+				const gatewayRouting = gatewayRoutingObservationFromRecord(
+					enrichedEvent.message as unknown as Record<string, unknown>,
+				);
+				if (
+					gatewayRouting !== null &&
+					((gatewayRouting.attemptedFallbacks ?? 0) > 0 || (gatewayRouting.attemptedRetries ?? 0) > 0)
+				) {
+					deps.emitNotice(`[Clio Coder] ${gatewayRoutingObservationLabel(gatewayRouting)}`);
+				}
 				const interruptedUsage = estimatedUsageForInterruptedTurn(enrichedEvent.message, context.promptSideTokens());
 				if (interruptedUsage !== null) {
 					// Persistence records the same estimate, but it does so after the
@@ -718,17 +736,15 @@ export function createTurnRuntime(deps: TurnRuntimeDeps): TurnRuntime {
 			// mediator, a dropped frame) therefore stops suspending the watchdog
 			// at the turn that issued it instead of for the rest of the run.
 			if (publicEvent?.type === "turn_end") toolsInFlight = 0;
-			if (publicEvent?.type === "message_start" && publicEvent.message?.role === "assistant") {
-				apiCallStartedAt = eventClock;
-				apiCallFirstDeltaAt = null;
-			}
 			if (publicEvent?.type === "message_update") {
 				const assistantEvent = publicEvent.assistantMessageEvent as { type?: string; delta?: unknown };
 				const hasDelta =
-					assistantEvent.type === "text_delta" ||
-					assistantEvent.type === "thinking_delta" ||
 					assistantEvent.type === "toolcall_start" ||
-					assistantEvent.type === "toolcall_delta";
+					((assistantEvent.type === "text_delta" ||
+						assistantEvent.type === "thinking_delta" ||
+						assistantEvent.type === "toolcall_delta") &&
+						typeof assistantEvent.delta === "string" &&
+						assistantEvent.delta.length > 0);
 				if (hasDelta && firstAssistantDeltaAt === null) firstAssistantDeltaAt = eventClock;
 				if (hasDelta && apiCallFirstDeltaAt === null) apiCallFirstDeltaAt = eventClock;
 			}

package/src/interactive/turn-state.ts

@@ -127,6 +127,12 @@ export interface ChatTurnState {
 	/** A middleware request_continuation is waiting to resubmit after settle. */
 	pendingRequestContinuation: boolean;
 	currentPendingSkillPolicy: PendingSkillToolPolicy | undefined;
+	/**
+	 * Tool surface an activated skill narrowed, held across the operator's
+	 * later turns. Replaced when the operator activates a different skill,
+	 * cleared by `/skill off`, gone with the session.
+	 */
+	activeSkillSurface: PendingSkillToolPolicy | undefined;
 	currentAskUserPolicy: AskUserToolPolicy | undefined;
 	lastRunSnapshot: ChatLoopRunSnapshot | null;
 }
@@ -153,6 +159,7 @@ export function createTurnState(initialThinkingLevel: ThinkingLevel): ChatTurnSt
 		stalledTurnNudgeSpent: false,
 		pendingRequestContinuation: false,
 		currentPendingSkillPolicy: undefined,
+		activeSkillSurface: undefined,
 		currentAskUserPolicy: undefined,
 		lastRunSnapshot: null,
 	};

package/src/interactive/worker-receipts.ts

@@ -59,6 +59,7 @@ const PRESENTED_RESULT_CONTRACTS: ReadonlyArray<WorkerPresentedResultContract> =
 	"debugger-report",
 	"verifier-report",
 	"research-report",
+	"world-knowledge-report",
 	"scout-report",
 ];
 

package/src/interactive/worker-stream.ts

@@ -62,7 +62,12 @@ export interface WorkerAttempt {
 export type WorkerResultContract = "pass" | "fail" | "not-reached" | "unmeasured";
 
 /** Result kinds whose parsed envelopes have a dedicated transcript presentation. */
-export type WorkerPresentedResultContract = "debugger-report" | "verifier-report" | "research-report" | "scout-report";
+export type WorkerPresentedResultContract =
+	| "debugger-report"
+	| "verifier-report"
+	| "research-report"
+	| "world-knowledge-report"
+	| "scout-report";
 
 /**
  * Terminal facts a worker block reports. Sealed by the receipt when it can be

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.",
 		}),