@iowarp/clio-coder 0.4.2 → 0.4.4

package/src/interactive/turn-context.ts

@@ -641,8 +641,8 @@ export function createTurnContext(deps: TurnContextDeps): TurnContext {
 		if (!usage || !deps.observability) return;
 		if (usage.totalTokens <= 0 && usage.cost.total <= 0) return;
 		deps.observability.recordTokens(
-			agentRuntime.targetId,
-			agentRuntime.wireModelId,
+			usage.targetId ?? agentRuntime.targetId,
+			usage.modelId ?? agentRuntime.wireModelId,
 			usage.totalTokens,
 			usage.cost.total,
 			{
@@ -654,7 +654,11 @@ export function createTurnContext(deps: TurnContextDeps): TurnContext {
 				totalTokens: usage.totalTokens,
 				apiCalls: Math.max(1, Math.round(usage.apiCalls)),
 			},
-			agentRuntime.runtimeResolution.costProvenance,
+			usage.targetId === undefined && usage.modelId === undefined
+				? agentRuntime.runtimeResolution.costProvenance
+				: usage.cost.total > 0
+					? "estimated"
+					: "unknown",
 		);
 	};
 
@@ -915,8 +919,8 @@ export function createTurnContext(deps: TurnContextDeps): TurnContext {
 		if (!summaryLifecycleStarted) startSummaryLifecycle();
 		deps.bus?.emit(BusChannels.CompactionEnd, { trigger, at: Date.now() });
 
-		// The summarization call spends tokens on the same target the turn would
-		// have. The ledger entry carries its usage for a later reseed; this is the
+		// The checkpoint identifies the selected summary route; older results
+		// fall back to the active chat route. The ledger carries usage for reseed; this is the
 		// live sink, so `/cost` and the footer move the moment /context compact
 		// returns instead of staying byte-identical to before it ran.
 		recordCompactionUsage(agentRuntime, result);

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/view/artifacts.ts

@@ -1382,6 +1382,8 @@ function renderAccountabilitySummary(summary: AccountabilitySummary): string[] {
 		"# Accountability",
 		"",
 		`first-pass success: ${summary.firstPassRuns}/${summary.totalRuns} (${pct}%)`,
+		`unverified successes: ${summary.unverifiedSuccesses}`,
+		`ungrounded claims: ${summary.ungroundedClaims}`,
 		"",
 		"## Top failure causes",
 		"",

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

@@ -9,7 +9,7 @@
  * I/O, so every sequence below is testable as a pure fold.
  *
  * What a worker is saying and doing is not decided here. That is the canonical
- * {@link WorkerProgressSnapshot} projection in `worker-progress.ts`, which the
+ * {@link WorkerProgressSnapshot} projection in `src/domains/observability/worker-progress.ts`, which the
  * Fleet Runs board reads from the same events, so the two surfaces cannot drift
  * on the answer tail, the tool names, or what a call is touching. This module
  * owns the half the board has no use for: which assignment an event belongs to,
@@ -43,14 +43,18 @@ import type {
 } from "../core/bus-events.js";
 import type { RunKind } from "../domains/dispatch/types.js";
 import type { CanonicalTrustStatus } from "../domains/evidence/trust-status.js";
+import {
+	createWorkerProgressFold,
+	type WorkerProgressFold,
+	type WorkerProgressSnapshot,
+} from "../domains/observability/worker-progress.js";
 import type { WorkerRunOrigin, WorkerRunRuntime, WorkerRunRuntimeKind } from "../domains/session/index.js";
-import { createWorkerProgressFold, type WorkerProgressFold, type WorkerProgressSnapshot } from "./worker-progress.js";
 
 export {
 	boundSettledText,
 	WORKER_LIVE_TAIL_LINES,
 	WORKER_TOOL_NAME_LIMIT,
-} from "./worker-progress.js";
+} from "../domains/observability/worker-progress.js";
 export type { WorkerProgressSnapshot };
 
 export interface WorkerAttempt {
@@ -62,7 +66,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/tools/bootstrap.ts

@@ -5,6 +5,7 @@ import type { DispatchContract } from "../domains/dispatch/contract.js";
 import type { AgentRoleFactsResolver } from "../domains/dispatch/execution-role.js";
 import type { PanesOperations } from "../domains/mux/operations.js";
 import type { AutonomyLevel } from "../domains/safety/autonomy.js";
+import type { DecisionLedgerEntry } from "../domains/session/entries.js";
 import { builtin, toolPromptHintsForNames } from "./builtin-tool-catalog.js";
 import type { CompeteMuxWorktrees } from "./compete-worktrees.js";
 import { assertRegisteredBuiltinTools, type CoreToolBootstrapDeps, registerCoreTools } from "./core-bootstrap.js";
@@ -31,6 +32,8 @@ export interface ToolBootstrapDeps extends CoreToolBootstrapDeps {
 	/** Which optional `dispatch` schema blocks this session advertises; absent means every block. */
 	getDispatchSchemaComposition?: () => DispatchSchemaComposition;
 	dispatchBackground?: DispatchBackgroundRegistry;
+	/** Live decision board snapshot; dispatch seals its active refs onto every request. */
+	getDecisionBoard?: () => ReadonlyArray<DecisionLedgerEntry>;
 	/** Optional herdr worktree lifecycle for compete candidates. */
 	competeMuxWorktrees?: CompeteMuxWorktrees;
 	/**
@@ -66,6 +69,7 @@ export function registerAllTools(registry: ToolRegistry, deps: ToolBootstrapDeps
 			...(deps.getWorkerRosters ? { getWorkerRosters: deps.getWorkerRosters } : {}),
 			...(deps.getDispatchSchemaComposition ? { getSchemaComposition: deps.getDispatchSchemaComposition } : {}),
 			...(deps.dispatchBackground ? { background: deps.dispatchBackground } : {}),
+			...(deps.getDecisionBoard ? { getDecisionBoard: deps.getDecisionBoard } : {}),
 			...(deps.competeMuxWorktrees ? { competeWorktrees: { mux: deps.competeMuxWorktrees } } : {}),
 		};
 		registry.register({

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

@@ -45,6 +45,13 @@ const exactMutationPolicy = {
 // declares its posture explicitly.
 const TOOL_METADATA: Readonly<Record<string, ToolMetadata>> = {
 	// OBSERVE: read-class, parallel, envelope + shared turn budget.
+	[ToolNames.Evidence]: {
+		objective: "Inspect canonical evidence, trust status, gate decisions, and findings.",
+		uiLabel: "Evidence",
+		retrySafety: "idempotent",
+		resultSizePolicy: summaryPolicy("Inspect one run with evidence(mode=run, runId=<id>) to narrow the output."),
+		costLatency: "local_medium",
+	},
 	[ToolNames.Read]: {
 		objective: "Read exact UTF-8 file content with line and byte bounds.",
 		uiLabel: "Read",
@@ -240,6 +247,30 @@ const TOOL_METADATA: Readonly<Record<string, ToolMetadata>> = {
 		promptHint:
 			'When the operator asks to see a dispatched agent ("show me the tester"), call panes(action="show", target=<agent id>).',
 	},
+	[ToolNames.Limitation]: {
+		objective: "Record what the turn could not verify and why as a ledger receipt.",
+		uiLabel: "Limitation",
+		retrySafety: "idempotent",
+		resultSizePolicy: {
+			kind: "exact",
+			maxBytes: 4_096,
+			followUpHint: "Call limitation again with a narrower scope if the first call was rejected.",
+		},
+		costLatency: "local_fast",
+	},
+	[ToolNames.Decide]: {
+		objective: "Record a design decision with its rejected alternatives and rationale on the session decision board.",
+		uiLabel: "Decide",
+		// A repeated call with the same key supersedes the earlier record, so
+		// the surface as a whole is not retry safe.
+		retrySafety: "not_retry_safe",
+		resultSizePolicy: {
+			kind: "exact",
+			maxBytes: 4_096,
+			followUpHint: "The decision ref in the result is what receipts and commits cite.",
+		},
+		costLatency: "local_fast",
+	},
 	// RETRIEVE: network-class.
 	[ToolNames.WebFetch]: {
 		objective: "Fetch HTTP(S) text for explicit external research.",

package/src/tools/compete-worktrees.ts

@@ -616,7 +616,13 @@ export async function createCandidateWorktreeMapped(
  * builder changed nothing (an empty candidate is a legitimate ranking fact).
  */
 export function commitCandidateWork(worktree: CandidateWorktree, message: string): boolean {
-	return commitWorktreePath(worktree.path, COMPETE_COMMIT_IDENTITY, message);
+	// Context reads refresh these runtime files even in a read-only worker.
+	// The caller's pending .gitignore update is not part of the candidate base;
+	// exclude the exact files, while keeping operator-owned project assets.
+	return commitWorktreePath(worktree.path, COMPETE_COMMIT_IDENTITY, message, [
+		".clio-coder/codewiki.json",
+		".clio-coder/state.json",
+	]);
 }
 
 /** One-line stat summary of what a candidate branch changed relative to HEAD. */

package/src/tools/context/index.ts

@@ -181,20 +181,33 @@ function pendingSkillPolicyError(name: string, options: ToolInvokeOptions | unde
 	if (!policy) {
 		return NO_PENDING_SKILL_DENIAL;
 	}
+	const recipeBound = policyIsRecipeBound(policy);
+	// auto-edit / full-auto: the operator already chose to let the model act
+	// without being asked, and a skill only ever narrows the tool surface, so
+	// the model activates an installed skill itself under the same per-run
+	// policy `/skill` produces. A skill that is not installed still fails the
+	// lookup below with the operator-gated marketplace message.
+	if (policy.modelActivation === true && !recipeBound) {
+		if (!policy.loadedSkillNames.has(name)) return null;
+		const window = policy.carriedSurface === true ? "in this session" : "this turn";
+		return `context: skill ${name} already loaded ${window}; continue with the loaded workflow and call ask_user if an interview/choice is needed.`;
+	}
 	const allowed = [...new Set(policy.allowedSkillNames.map((entry) => entry.trim()).filter(Boolean))];
 	if (allowed.length === 0) {
 		return NO_PENDING_SKILL_DENIAL;
 	}
-	const recipeBound = policyIsRecipeBound(policy);
 	if (!allowed.includes(name)) {
-		return recipeBound
-			? `context: this agent run may load only its declared skill(s): ${allowed.join(", ")}.`
-			: `context: this turn has pending skill request(s): ${allowed.join(", ")}. Load only those before doing anything else.`;
+		if (recipeBound) return `context: this agent run may load only its declared skill(s): ${allowed.join(", ")}.`;
+		// A carried surface is a skill the operator activated on an earlier
+		// turn, not a request waiting to be loaded now. Claiming a pending
+		// request here would invite a retry of a load nothing asked for.
+		if (policy.carriedSurface === true) return NO_PENDING_SKILL_DENIAL;
+		return `context: this turn has pending skill request(s): ${allowed.join(", ")}. Load only those before doing anything else.`;
 	}
 	if (policy.loadedSkillNames.has(name)) {
-		return recipeBound
-			? `context: skill ${name} is already loaded in this run; continue with its workflow.`
-			: `context: pending skill ${name} already loaded this turn; continue with the loaded workflow and call ask_user if an interview/choice is needed.`;
+		if (recipeBound) return `context: skill ${name} is already loaded in this run; continue with its workflow.`;
+		const window = policy.carriedSurface === true ? "in this session" : "this turn";
+		return `context: pending skill ${name} already loaded ${window}; continue with the loaded workflow and call ask_user if an interview/choice is needed.`;
 	}
 	return null;
 }
@@ -274,6 +287,7 @@ function renderSkillsList(
 	skills: ReadonlyArray<Skill>,
 	marketplace: ReadonlyArray<MarketplaceSkill>,
 	marketplaceOffered: boolean,
+	modelActivation: boolean,
 ): string {
 	if (skills.length === 0 && marketplace.length === 0) {
 		// A registry that never offers the marketplace (a worker) must not
@@ -308,7 +322,9 @@ function renderSkillsList(
 	// template where they skip conditional prose in the header.
 	lines.push(
 		"",
-		`If one skill above matches the current task, begin your reply with the line \`${SKILL_SUGGESTION_ANCHOR}\` (a comma-separated sequence, in order, when several compose), then continue the task in the same turn without it; only the operator can run it. If none match, do not mention skills.`,
+		modelActivation
+			? `If one skill above matches the current task, load it now with context(scope="skills", name="<name>") and continue in the same turn; at this autonomy level you activate installed skills yourself and do not wait for the operator. Marketplace rows below are not installed and still need the operator. If none match, do not mention skills.`
+			: `If one skill above matches the current task, begin your reply with the line \`${SKILL_SUGGESTION_ANCHOR}\` (a comma-separated sequence, in order, when several compose), then continue the task in the same turn without it; only the operator can run it. If none match, do not mention skills.`,
 	);
 	if (marketplace.length > 0) {
 		// The offer protocol mirrors the marketplace-offer middleware: fixed
@@ -423,7 +439,12 @@ function runSkillsScope(
 		const list = loadSkills({ cwd: cwdFromDeps(deps), ...(deps.getSkillLoaderOptions?.() ?? {}) });
 		const visible = modelVisibleSkills(list.items);
 		const marketplace = marketplaceRowsFor(deps, list.items, options);
-		const rendered = renderSkillsList(visible, marketplace, deps.skillMarketplace !== false);
+		const rendered = renderSkillsList(
+			visible,
+			marketplace,
+			deps.skillMarketplace !== false,
+			options?.pendingSkillPolicy?.modelActivation === true,
+		);
 		// The catalog is bounded but not small: the whole listing must fit the
 		// per-call cap like any observation, and a cut list says so instead of
 		// silently dropping the marketplace tail.

package/src/tools/core-bootstrap.ts

@@ -1,6 +1,7 @@
 import type { ContextRecalledPayload } from "../core/bus-events.js";
 import type { LoadSkillsInput } from "../domains/resources/index.js";
 import type { SessionContract } from "../domains/session/contract.js";
+import type { DecisionBoardStore } from "../domains/session/decision-board.js";
 import type { SessionEntry } from "../domains/session/entries.js";
 import { createTaskBoardStore, type TaskBoardStore } from "../domains/session/task-board.js";
 import type { UserTasksStore } from "../domains/user-tasks/store.js";
@@ -12,11 +13,14 @@ import { builtin } from "./builtin-tool-catalog.js";
 import { codeNavToolSurface } from "./codewiki/code-nav-surface.js";
 import { contextToolSurface } from "./context/surface.js";
 import { credentialPresentTool } from "./credential-present.js";
+import { createDecideTool } from "./decide.js";
 import { editTool } from "./edit.js";
+import { evidenceTool } from "./evidence.js";
 import { findTool } from "./find.js";
 import { grepTool } from "./grep.js";
 import { lazyTool } from "./lazy-tool.js";
 import { createLedgerTool } from "./ledger.js";
+import { limitationTool } from "./limitation.js";
 import { lsTool } from "./ls.js";
 import { networkToolsDisabled } from "./network-policy.js";
 import { assertBuiltinToolPolicy } from "./policy.js";
@@ -36,6 +40,8 @@ export interface CoreToolBootstrapDeps {
 	onContextRecalled?: (payload: ContextRecalledPayload) => void;
 	askUser?: AskUserHandler;
 	taskBoard?: TaskBoardStore;
+	/** The session decision board the `decide` tool appends to; absent in worker registries, where the tool refuses. */
+	decisionBoard?: DecisionBoardStore;
 	userTasks?: UserTasksStore;
 	agentLedger?: AgentLedgerPort;
 	/**
@@ -65,6 +71,7 @@ export interface CoreToolRegistration {
 
 export function registerCoreTools(registry: ToolRegistry, deps: CoreToolBootstrapDeps = {}): CoreToolRegistration {
 	const includeNetworkTools = !networkToolsDisabled();
+	registry.register(builtin(evidenceTool, { path: "src/tools/evidence.ts", scope: "core" }));
 	registry.register({
 		...builtin(readTool, { path: "src/tools/read.ts", scope: "core" }),
 	});
@@ -125,6 +132,15 @@ export function registerCoreTools(registry: ToolRegistry, deps: CoreToolBootstra
 	registry.register({
 		...builtin(credentialPresentTool, { path: "src/tools/credential-present.ts", scope: "core" }),
 	});
+	registry.register({
+		...builtin(limitationTool, { path: "src/tools/limitation.ts", scope: "core" }),
+	});
+	registry.register({
+		...builtin(createDecideTool(deps.decisionBoard ? { decisionBoard: deps.decisionBoard } : {}), {
+			path: "src/tools/decide.ts",
+			scope: "core",
+		}),
+	});
 	const session = deps.session;
 	const readSessionEntries = deps.readSessionEntries;
 	registry.register({

package/src/tools/decide.ts

@@ -0,0 +1,136 @@
+import { Type } from "typebox";
+import { ToolNames } from "../core/tool-names.js";
+import type { DecisionBoardStore } from "../domains/session/decision-board.js";
+import { decisionRef } from "../domains/session/entries.js";
+import type { ToolResult, ToolSpec } from "./registry.js";
+import { byteLength } from "./truncate-utf8.js";
+
+/**
+ * The model's own design decisions, recorded on the session decision board
+ * beside the operator's `ask_user` answers. A `decide` call appends one
+ * `decisionLedger` entry with `origin: "agent"` and one `DecisionRecord` with
+ * `source: "agent"`, the alternatives the model rejected, and why. Dispatch
+ * seals every active decision's ref onto the run envelope and receipt, and
+ * the commit seams turn the same refs into `Clio-Decision:` trailers, so a
+ * receipt or a commit names the choices it was made under.
+ */
+
+export const DECIDE_CAPS = Object.freeze({
+	keyBytes: 64,
+	valueBytes: 512,
+	alternatives: 6,
+	alternativeBytes: 256,
+	rationaleBytes: 1024,
+	labelBytes: 128,
+});
+
+const KEBAB_KEY = /^[a-z0-9]+(?:-[a-z0-9]+)*$/u;
+
+export interface DecideToolDeps {
+	decisionBoard?: DecisionBoardStore;
+}
+
+function boundedText(value: unknown, field: string, cap: number): string | Error {
+	if (typeof value !== "string") return new Error(`decide: ${field} must be a string`);
+	const trimmed = value.trim();
+	if (trimmed.length === 0) return new Error(`decide: ${field} is required`);
+	if (byteLength(trimmed) > cap) return new Error(`decide: ${field} exceeds the ${cap}-byte cap`);
+	return trimmed;
+}
+
+function boundedAlternatives(value: unknown): string[] | Error {
+	if (!Array.isArray(value) || value.length === 0) {
+		return new Error("decide: alternatives must list at least one option you rejected");
+	}
+	if (value.length > DECIDE_CAPS.alternatives) {
+		return new Error(`decide: alternatives exceeds the ${DECIDE_CAPS.alternatives}-entry cap`);
+	}
+	const alternatives: string[] = [];
+	for (const [index, entry] of value.entries()) {
+		const text = boundedText(entry, `alternatives[${index}]`, DECIDE_CAPS.alternativeBytes);
+		if (text instanceof Error) return text;
+		alternatives.push(text);
+	}
+	return alternatives;
+}
+
+export function createDecideTool(deps: DecideToolDeps = {}): ToolSpec {
+	return {
+		name: ToolNames.Decide,
+		description:
+			"Record a design decision you made between two or more viable options, with the alternatives you rejected and why. Call it before implementing the choice; a later call with the same key supersedes the earlier record.",
+		parameters: Type.Object({
+			key: Type.String({
+				description: `Stable kebab-case name for the decision, e.g. "cache-key-shape" (at most ${DECIDE_CAPS.keyBytes} bytes).`,
+			}),
+			value: Type.String({ description: `The option you chose (at most ${DECIDE_CAPS.valueBytes} bytes).` }),
+			alternatives: Type.Array(Type.String(), {
+				description: `Options you considered and rejected, 1 to ${DECIDE_CAPS.alternatives} entries.`,
+			}),
+			rationale: Type.String({
+				description: `Why the chosen option won over the alternatives (at most ${DECIDE_CAPS.rationaleBytes} bytes).`,
+			}),
+			label: Type.Optional(Type.String({ description: "Short human-readable title for the decision." })),
+		}),
+		// Read class on purpose: the only effect is one session-ledger append,
+		// so it must stay available at every autonomy level without a prompt.
+		baseActionClass: "read",
+		executionMode: "sequential",
+		async run(args): Promise<ToolResult> {
+			const key = boundedText(args.key, "key", DECIDE_CAPS.keyBytes);
+			if (key instanceof Error) return { kind: "error", message: key.message };
+			if (!KEBAB_KEY.test(key)) {
+				return { kind: "error", message: "decide: key must be kebab-case (lowercase letters, digits, single hyphens)" };
+			}
+			const value = boundedText(args.value, "value", DECIDE_CAPS.valueBytes);
+			if (value instanceof Error) return { kind: "error", message: value.message };
+			const alternatives = boundedAlternatives(args.alternatives);
+			if (alternatives instanceof Error) return { kind: "error", message: alternatives.message };
+			const rationale = boundedText(args.rationale, "rationale", DECIDE_CAPS.rationaleBytes);
+			if (rationale instanceof Error) return { kind: "error", message: rationale.message };
+			let label: string | undefined;
+			if (args.label !== undefined && args.label !== null) {
+				const bounded = boundedText(args.label, "label", DECIDE_CAPS.labelBytes);
+				if (bounded instanceof Error) return { kind: "error", message: bounded.message };
+				label = bounded;
+			}
+			if (deps.decisionBoard === undefined) {
+				return { kind: "error", message: "decide: no session decision board is available in this context" };
+			}
+			let outcome: ReturnType<DecisionBoardStore["recordAgentDecision"]>;
+			try {
+				outcome = deps.decisionBoard.recordAgentDecision({
+					key,
+					value,
+					alternatives,
+					rationale,
+					...(label !== undefined ? { label } : {}),
+				});
+			} catch (error) {
+				return { kind: "error", message: error instanceof Error ? error.message : String(error) };
+			}
+			const ref = decisionRef(outcome.entry.interviewId, key);
+			const supersededNote =
+				outcome.superseded === null
+					? ""
+					: ` (supersedes ${decisionRef(outcome.superseded.interviewId, outcome.superseded.key)})`;
+			return {
+				kind: "ok",
+				output: `decision recorded: ${key} = ${value} [${ref}]${supersededNote}\n`,
+				details: {
+					decision: {
+						ref,
+						key,
+						value,
+						alternatives,
+						rationale,
+						...(label !== undefined ? { label } : {}),
+						...(outcome.superseded !== null
+							? { superseded: decisionRef(outcome.superseded.interviewId, outcome.superseded.key) }
+							: {}),
+					},
+				},
+			};
+		},
+	};
+}

package/src/tools/dispatch-admission.ts

@@ -246,6 +246,27 @@ export function createDispatchAdmissionController(deps: DispatchToolDeps): Dispa
 							argv: [...check.command],
 							cwd: resolve(process.cwd(), check.cwd),
 							timeoutMs: entry.timeoutMs,
+							// A judged check seals its kind and absolute file paths here, so
+							// host verification judges against what the catalog declared at
+							// admission rather than whatever the file says at run time.
+							...(check.kind !== "command" ? { kind: check.kind } : {}),
+							...(check.numeric !== undefined
+								? {
+										numeric: {
+											reference: resolve(process.cwd(), check.numeric.reference),
+											tolerance: { ...check.numeric.tolerance },
+										},
+									}
+								: {}),
+							...(check.perf !== undefined
+								? {
+										perf: {
+											...(check.perf.budget !== undefined ? { budget: structuredClone(check.perf.budget) } : {}),
+											...(check.perf.baseline !== undefined ? { baseline: resolve(process.cwd(), check.perf.baseline) } : {}),
+											...(check.perf.tolerance !== undefined ? { tolerance: { ...check.perf.tolerance } } : {}),
+										},
+									}
+								: {}),
 						};
 					}),
 				};

package/src/tools/dispatch-arguments.ts

@@ -50,6 +50,7 @@ const AUTO_BASELINE_BY_TASK_TYPE: Readonly<Record<AgentTaskType, string>> = {
 	// Read-only shapes.
 	code_review: "verifier",
 	research: "researcher",
+	world_knowledge: "world-knowledge",
 	code_read: "scout",
 	unknown: "scout",
 };

package/src/tools/dispatch-event-text.ts

@@ -1,3 +1,4 @@
+import { gatewayRoutingObservationFromRecord, gatewayRoutingObservationLabel } from "../core/gateway-routing.js";
 import { responseModelIdObservationFromRecord } from "../core/response-model-id.js";
 import { durableAssistantTextFromEvent } from "../domains/dispatch/event-pump.js";
 import type { RunReceipt } from "../domains/dispatch/types.js";
@@ -23,3 +24,12 @@ export function receiptResponseModelIdObservationLabel(receipt: Pick<RunReceipt,
 	});
 	return `response_model_id_observation=${labels.join(",")}`;
 }
+
+/** Human projection of gateway routes carried by a receipt. */
+export function receiptGatewayRoutingLabel(receipt: Pick<RunReceipt, "upstreamResponses">): string | null {
+	const observations = (receipt.upstreamResponses ?? [])
+		.map((response) => gatewayRoutingObservationFromRecord(response as unknown as Record<string, unknown>))
+		.filter((observation) => observation !== null);
+	if (observations.length === 0) return null;
+	return observations.map(gatewayRoutingObservationLabel).join(" | ");
+}