@iowarp/clio-coder 0.4.7 → 0.4.9

package/src/domains/observability/accountability.ts

@@ -2,8 +2,8 @@
  * Accountability read model. A pure aggregation over the sidecar evidence index
  * (see evidence-index.ts) that yields a rolling first-pass-success rate and a
  * failure-cause tag histogram for the session. This is presentation-grade
- * read-only data: it recomputes nothing, it only folds the rows that Slice 2
- * already wrote when each dispatch run finalized. Those rows are
+ * read-only data: it recomputes nothing, it only folds the rows written
+ * when each dispatch run finalized. Those rows are
  * forensic-derived and are the authority for user-visible first-pass-success
  * rates. The receipt summary is the conservative integrity-covered snapshot,
  * so a false receipt summary and a true forensic row is an intentional

package/src/domains/observability/background-memory-usage.ts

@@ -27,6 +27,7 @@ export interface BackgroundMemoryStepUsage {
 	output: number;
 	cacheRead: number;
 	cacheWrite: number;
+	cacheWrite1h?: number;
 	reasoning: number;
 	totalTokens: number;
 	costUsd: number;
@@ -83,6 +84,7 @@ export function backgroundMemoryUsageRow(
 			output: usage.output,
 			cacheRead: usage.cacheRead,
 			cacheWrite: usage.cacheWrite,
+			...(usage.cacheWrite1h === undefined ? {} : { cacheWrite1h: usage.cacheWrite1h }),
 			reasoning: usage.reasoning,
 			totalTokens: usage.totalTokens,
 			costUsd: usage.costUsd,
@@ -122,6 +124,7 @@ export function recordBackgroundMemoryStep(input: RecordBackgroundMemoryStepInpu
 			output: input.usage.output,
 			cacheRead: input.usage.cacheRead,
 			cacheWrite: input.usage.cacheWrite,
+			...(input.usage.cacheWrite1h === undefined ? {} : { cacheWrite1h: input.usage.cacheWrite1h }),
 			reasoningTokens: input.usage.reasoning,
 			totalTokens: input.usage.totalTokens,
 			apiCalls: 1,

package/src/domains/observability/compaction-usage.ts

@@ -29,6 +29,7 @@ function observedUsage(call: CompactionCallObservation): OutOfTurnUsage {
 		output: reading(raw.output),
 		cacheRead: reading(raw.cacheRead),
 		cacheWrite: reading(raw.cacheWrite),
+		...(raw.cacheWrite1h === undefined ? {} : { cacheWrite1h: reading(raw.cacheWrite1h) }),
 		reasoning: reasoning !== null && reasoning > 0 ? reasoning : null,
 		totalTokens: reading(raw.totalTokens),
 		costUsd,
@@ -72,6 +73,7 @@ export function recordFailedCompactionCalls(
 				output: usage.output ?? 0,
 				cacheRead: usage.cacheRead ?? 0,
 				cacheWrite: usage.cacheWrite ?? 0,
+				...(typeof usage.cacheWrite1h === "number" ? { cacheWrite1h: usage.cacheWrite1h } : {}),
 				reasoningTokens: usage.reasoning ?? 0,
 				totalTokens: usage.totalTokens ?? 0,
 				apiCalls: 1,

package/src/domains/observability/contract.ts

@@ -76,6 +76,8 @@ export interface ObservabilityRunSummary {
 	contextWindow?: number;
 	lastContextTokens?: number;
 	progress?: WorkerProgressSnapshot;
+	/** Existing validator identity/conformance, admitted with the verified receipt answer. */
+	resultContract?: { kind: string; conformance: string };
 	receiptId?: string;
 	retry?: { attempt: number; dueAtMs: number; reason: string };
 	steerAcknowledgement?: { receivedAtMs: number; chars: number };
@@ -132,7 +134,9 @@ export interface ObservabilitySnapshot {
 /** Runtime readers supplied after dispatch is composed, avoiding a domain dependency cycle. */
 export interface ObservabilityRunReaders {
 	dispatchSnapshot?: () => DispatchSnapshot;
-	readReceipt?: (runId: string) => { text?: string; trust?: CanonicalTrustStatus } | null;
+	readReceipt?: (
+		runId: string,
+	) => { text?: string; trust?: CanonicalTrustStatus; contractKind?: string; contract?: string } | null;
 }
 
 /** Run projection controls shared by the contract and the in-memory projection. */
@@ -160,8 +164,8 @@ export interface ObservabilityContract extends ObservabilityRunProjection {
 	/**
 	 * Rolling first-pass-success rate, unverified successes, ungrounded claims,
 	 * and failure-cause histogram, aggregated
-	 * from the sidecar evidence index on call. Read-only: it folds rows Slice 2
-	 * already wrote and recomputes no evidence.
+	 * from the sidecar evidence index on call. It folds rows written at dispatch
+	 * completion and recomputes no evidence.
 	 */
 	accountability(): AccountabilitySummary;
 	/** Latest completed assistant stream throughput for compact footer display. */

package/src/domains/observability/cost.ts

@@ -127,6 +127,7 @@ export interface UsageBreakdown {
 	output: number;
 	cacheRead: number;
 	cacheWrite: number;
+	cacheWrite1h?: number;
 	reasoningTokens: number;
 	totalTokens: number;
 	apiCalls?: number;
@@ -151,6 +152,7 @@ export interface CostEntry {
 	output: number;
 	cacheRead: number;
 	cacheWrite: number;
+	cacheWrite1h?: number;
 	reasoningTokens: number;
 	apiCalls?: number;
 	/** Absent on an ordinary turn's call. */
@@ -215,6 +217,7 @@ export function createCostTracker(): CostTracker {
 				output,
 				cacheRead,
 				cacheWrite,
+				...(breakdown?.cacheWrite1h === undefined ? {} : { cacheWrite1h: breakdown.cacheWrite1h }),
 				reasoningTokens,
 				...(apiCalls !== undefined ? { apiCalls } : {}),
 				...(label !== undefined ? { label } : {}),
@@ -224,6 +227,7 @@ export function createCostTracker(): CostTracker {
 			totals.output += output;
 			totals.cacheRead += cacheRead;
 			totals.cacheWrite += cacheWrite;
+			if (breakdown?.cacheWrite1h !== undefined) totals.cacheWrite1h = (totals.cacheWrite1h ?? 0) + breakdown.cacheWrite1h;
 			totals.reasoningTokens += reasoningTokens;
 			totals.totalTokens += tokens;
 			return resolvedUsd;
@@ -247,6 +251,7 @@ export function createCostTracker(): CostTracker {
 			totals.output = 0;
 			totals.cacheRead = 0;
 			totals.cacheWrite = 0;
+			delete totals.cacheWrite1h;
 			totals.reasoningTokens = 0;
 			totals.totalTokens = 0;
 		},

package/src/domains/observability/evidence-index.ts

@@ -1,8 +1,8 @@
 /**
  * Sidecar evidence index. A compact, append/merge-by-runId ledger written
  * under `<stateDir>/evidence-index.json` whenever a dispatch run completes and
- * the forensic evidence bundle is built (see extension.ts). Slice 6 reads this
- * to surface a rolling first-pass-success rate and a failure-cause histogram in
+ * the forensic evidence bundle is built (see extension.ts). The accountability
+ * read model uses this to surface a rolling first-pass-success rate and a failure-cause histogram in
  * observability without re-running the heavy `buildEvidence` aggregator.
  *
  * The file is a JSON array kept as a bounded ring (newest rows win, capped at

package/src/domains/observability/extension.ts

@@ -64,6 +64,7 @@ function recordDispatchCost(
 			output: payload.outputTokenCount ?? 0,
 			cacheRead: payload.cacheReadTokenCount ?? 0,
 			cacheWrite: payload.cacheWriteTokenCount ?? 0,
+			...(payload.cacheWrite1hTokenCount === undefined ? {} : { cacheWrite1h: payload.cacheWrite1hTokenCount }),
 			reasoningTokens: payload.reasoningTokenCount ?? 0,
 			totalTokens: payload.tokenCount,
 		},

package/src/domains/observability/out-of-turn-usage.ts

@@ -78,6 +78,7 @@ export interface OutOfTurnUsage {
 	output: number | null;
 	cacheRead: number | null;
 	cacheWrite: number | null;
+	cacheWrite1h?: number | null;
 	reasoning: number | null;
 	totalTokens: number | null;
 	costUsd: number | null;
@@ -253,6 +254,7 @@ function asOutOfTurnUsageRow(value: unknown): OutOfTurnUsageRow | null {
 			output: reading(usage.output),
 			cacheRead: reading(usage.cacheRead),
 			cacheWrite: reading(usage.cacheWrite),
+			...(usage.cacheWrite1h === undefined ? {} : { cacheWrite1h: nullableNumber(usage.cacheWrite1h) }),
 			reasoning: reading(usage.reasoning),
 			totalTokens: reading(usage.totalTokens),
 			costUsd: reading(usage.costUsd),

package/src/domains/observability/projection.ts

@@ -401,6 +401,7 @@ export function createObservabilityProjection(bus: SafeEventBus, deps: Projectio
 	function applyIdentity(summary: RunEntry, id: Partial<DispatchRunIdentity>): void {
 		// A lifecycle update must earn its trust again from the current receipt.
 		delete summary.trust;
+		delete summary.resultContract;
 		if (typeof id.agentId === "string" && id.agentId.length > 0) summary.agentId = id.agentId;
 		if (typeof id.targetId === "string" && id.targetId.length > 0) summary.targetId = id.targetId;
 		if (typeof id.wireModelId === "string" && id.wireModelId.length > 0) summary.modelId = id.wireModelId;
@@ -459,11 +460,20 @@ export function createObservabilityProjection(bus: SafeEventBus, deps: Projectio
 	}
 
 	function settleFromReceipt(summary: RunEntry): void {
+		delete summary.resultContract;
 		try {
 			const facts = runReaders.readReceipt?.(summary.runId);
 			// A failed or retired seal cannot supply the board's terminal answer.
 			const text = facts?.trust?.artifactIntegrity.state === "verified" ? facts.text : undefined;
 			summary.progressFold.settle(typeof text === "string" && text.trim().length > 0 ? text : undefined);
+			if (
+				typeof text === "string" &&
+				text.trim().length > 0 &&
+				typeof facts?.contractKind === "string" &&
+				typeof facts.contract === "string"
+			) {
+				summary.resultContract = { kind: facts.contractKind, conformance: facts.contract };
+			}
 			if (facts?.trust !== undefined) summary.trust = summarizeTrustStatus(facts.trust);
 		} catch {
 			summary.progressFold.settle();

package/src/domains/observability/trace-store.ts

@@ -202,6 +202,7 @@ export interface TraceSpendInput {
 	outputTokens: number;
 	cacheReadTokens: number;
 	cacheWriteTokens: number;
+	cacheWrite1hTokens?: number;
 	reasoningTokens: number;
 	totalTokens: number;
 	inputCostUsd?: number | null;
@@ -234,6 +235,7 @@ export interface SessionTurnUsage {
 	outputTokens: number;
 	cacheReadTokens: number;
 	cacheWriteTokens: number;
+	cacheWrite1hTokens?: number;
 	reasoningTokens: number;
 	totalTokens: number;
 	costUsd?: number | null;
@@ -363,6 +365,7 @@ export interface TracePhaseRow {
 	output_tokens: number | null;
 	cache_read_tokens: number | null;
 	cache_write_tokens: number | null;
+	cache_write_1h_tokens?: number | null;
 	reasoning_tokens: number | null;
 	total_tokens: number | null;
 	input_cost_usd: number | null;
@@ -443,7 +446,7 @@ CREATE TABLE phases (
   error TEXT,
   started_at TEXT,
   ended_at TEXT,
-  input_tokens INTEGER, output_tokens INTEGER, cache_read_tokens INTEGER, cache_write_tokens INTEGER,
+  input_tokens INTEGER, output_tokens INTEGER, cache_read_tokens INTEGER, cache_write_tokens INTEGER, cache_write_1h_tokens INTEGER,
   reasoning_tokens INTEGER, total_tokens INTEGER,
   input_cost_usd REAL, output_cost_usd REAL, cache_read_cost_usd REAL, cache_write_cost_usd REAL,
   total_cost_usd REAL,
@@ -544,6 +547,13 @@ function ensureRunSourceColumn(db: DatabaseSync): void {
 	db.prepare("UPDATE runs SET source = 'session' WHERE assignment_id = ?").run(SESSION_TRACE_ASSIGNMENT_ID);
 }
 
+/** Missing lifetime detail stays NULL in older traces; it cannot be reconstructed. */
+function ensureCacheWriteLifetimeColumn(db: DatabaseSync): void {
+	const columns = db.prepare("PRAGMA table_info(phases)").all() as { name: string }[];
+	if (!columns.some((column) => column.name === "cache_write_1h_tokens"))
+		db.exec("ALTER TABLE phases ADD COLUMN cache_write_1h_tokens INTEGER;");
+}
+
 /**
  * Finalize `running` rows whose recorded owner is on this host and provably
  * dead (pid gone, or alive under a different birth token, i.e. reused). Rows
@@ -591,6 +601,7 @@ export class TraceStore {
 		this.transaction(() => {
 			ensureProcessOwnerColumns(this.db);
 			ensureRunSourceColumn(this.db);
+			ensureCacheWriteLifetimeColumn(this.db);
 			reconcileAbandonedRuns(this.db);
 		});
 	}
@@ -799,7 +810,7 @@ export class TraceStore {
 	recordSpend(input: TraceSpendInput): void {
 		this.transaction(() => {
 			this.db
-				.prepare(`UPDATE phases SET input_tokens=?, output_tokens=?, cache_read_tokens=?, cache_write_tokens=?,
+				.prepare(`UPDATE phases SET input_tokens=?, output_tokens=?, cache_read_tokens=?, cache_write_tokens=?, cache_write_1h_tokens=?,
           reasoning_tokens=?, total_tokens=?, input_cost_usd=?, output_cost_usd=?, cache_read_cost_usd=?,
           cache_write_cost_usd=?, total_cost_usd=?, context_tokens=?, context_window=? WHERE phase_id=? AND run_id=?`)
 				.run(
@@ -807,6 +818,7 @@ export class TraceStore {
 					input.outputTokens,
 					input.cacheReadTokens,
 					input.cacheWriteTokens,
+					input.cacheWrite1hTokens ?? null,
 					input.reasoningTokens,
 					input.totalTokens,
 					input.inputCostUsd ?? null,
@@ -982,7 +994,7 @@ export class TraceStore {
 				);
 			this.db
 				.prepare(`UPDATE phases SET status=?, attempt=?, retries=?, ended_at=?, error=?, input_tokens=?, output_tokens=?,
-          cache_read_tokens=?, cache_write_tokens=?, reasoning_tokens=?, total_tokens=?, total_cost_usd=?
+          cache_read_tokens=?, cache_write_tokens=?, cache_write_1h_tokens=?, reasoning_tokens=?, total_tokens=?, total_cost_usd=?
           WHERE phase_id=?`)
 				.run(
 					success ? "success" : "fail",
@@ -994,6 +1006,7 @@ export class TraceStore {
 					input.outputTokenCount ?? null,
 					input.cacheReadTokenCount ?? null,
 					input.cacheWriteTokenCount ?? null,
+					input.cacheWrite1hTokenCount ?? null,
 					input.reasoningTokenCount ?? null,
 					input.tokenCount ?? null,
 					input.costUsd ?? null,
@@ -1113,7 +1126,7 @@ export class TraceStore {
 				.run(input.status, input.at, usage?.totalTokens ?? null, usage?.costUsd ?? null, input.runId);
 			this.db
 				.prepare(`UPDATE phases SET status=?, ended_at=?, error=?, input_tokens=?, output_tokens=?,
-          cache_read_tokens=?, cache_write_tokens=?, reasoning_tokens=?, total_tokens=?, total_cost_usd=?
+          cache_read_tokens=?, cache_write_tokens=?, cache_write_1h_tokens=?, reasoning_tokens=?, total_tokens=?, total_cost_usd=?
           WHERE phase_id=?`)
 				.run(
 					input.status,
@@ -1123,6 +1136,7 @@ export class TraceStore {
 					usage?.outputTokens ?? null,
 					usage?.cacheReadTokens ?? null,
 					usage?.cacheWriteTokens ?? null,
+					usage?.cacheWrite1hTokens ?? null,
 					usage?.reasoningTokens ?? null,
 					usage?.totalTokens ?? null,
 					usage?.costUsd ?? null,
@@ -1186,13 +1200,24 @@ function traceDatabaseFootprintBytes(path: string): number {
 	return total;
 }
 
+export interface TraceRunCursor {
+	startedAt: string;
+	runId: string;
+}
+
+export interface TraceRunsPageOptions {
+	before?: TraceRunCursor;
+	limit?: number;
+	filter?: { source?: TraceRunRow["source"]; status?: TraceRunRow["status"]; q?: string };
+}
+
 export class TraceReader {
 	readonly db: DatabaseSync;
 	/**
 	 * `runs.source` is an additive column (see ensureRunSourceColumn) a
 	 * TraceStore writer backfills in place. A read-only reader can open a
 	 * database no writer has touched since before the column existed — the
-	 * trace viewer opening a dormant install's trace.sqlite fresh is the
+	 * web application opening a dormant install's trace.sqlite fresh is the
 	 * realistic case — and cannot ALTER TABLE to fix that itself, so it
 	 * derives the same value the migration would have written instead.
 	 */
@@ -1223,6 +1248,40 @@ export class TraceReader {
 			.all(clampInt(limit, 1, 500)) as unknown as TraceRunRow[];
 	}
 
+	/** Stable keyset pagination, including read-only databases predating runs.source. */
+	runsPage({ before, limit = 50, filter = {} }: TraceRunsPageOptions = {}): {
+		runs: TraceRunRow[];
+		nextBefore: TraceRunCursor | null;
+	} {
+		const size = clampInt(limit, 1, 500);
+		const where: string[] = [],
+			args: SQLInputValue[] = [];
+		if (before) {
+			where.push("(started_at < ? OR (started_at = ? AND run_id < ?))");
+			args.push(before.startedAt, before.startedAt, before.runId);
+		}
+		if (filter.source) {
+			where.push("source = ?");
+			args.push(filter.source);
+		}
+		if (filter.status) {
+			where.push("status = ?");
+			args.push(filter.status);
+		}
+		if (filter.q) {
+			where.push("(run_id LIKE ? OR agent LIKE ? OR model LIKE ? OR status LIKE ? OR request LIKE ?)");
+			args.push(...Array<string>(5).fill(`%${filter.q}%`));
+		}
+		const rows = this.db
+			.prepare(
+				`SELECT * FROM (SELECT ${this.runsSourceExpr} FROM runs) ${where.length ? `WHERE ${where.join(" AND ")}` : ""} ORDER BY started_at DESC, run_id DESC LIMIT ?`,
+			)
+			.all(...args, size + 1) as unknown as TraceRunRow[];
+		const runs = rows.slice(0, size),
+			last = runs.at(-1);
+		return { runs, nextBefore: rows.length > size && last ? { startedAt: last.started_at, runId: last.run_id } : null };
+	}
+
 	run(runId: string): TraceRunRow | null {
 		return (
 			(this.db.prepare(`SELECT ${this.runsSourceExpr} FROM runs WHERE run_id=?`).get(runId) as unknown as
@@ -1567,6 +1626,7 @@ function terminalUsage(input: DispatchCompletedPayload | DispatchFailedPayload):
 		output: input.outputTokenCount ?? 0,
 		cache_read: input.cacheReadTokenCount ?? 0,
 		cache_write: input.cacheWriteTokenCount ?? 0,
+		...(input.cacheWrite1hTokenCount === undefined ? {} : { cache_write_1h: input.cacheWrite1hTokenCount }),
 		reasoning_tokens: input.reasoningTokenCount ?? 0,
 		total_tokens: input.tokenCount,
 	};

package/src/domains/prompts/compiler.ts

@@ -4,7 +4,8 @@ import { normalizePromptHint } from "../../core/prompt-hint.js";
 import type { ToolName } from "../../core/tool-names.js";
 import { TOOL_RESULT_TRUST_CONTRACT } from "../../core/untrusted-content.js";
 import { resolveClioDirs } from "../../core/xdg.js";
-import type { AutonomyLevel } from "../safety/autonomy.js";
+import { directSurfaceNames } from "../../tools/surface.js";
+import { type AutonomyLevel, isAutonomyLevel, modelMayActivateSkills } from "../safety/autonomy.js";
 import { ceilChars } from "../session/context-accounting.js";
 import type { FragmentTable, LoadedFragment } from "./fragment-loader.js";
 import { sha256 } from "./hash.js";
@@ -235,10 +236,9 @@ function sessionCanDispatch(inputs: SessionPromptInputs): boolean {
 }
 
 /**
- * Whether `context` is on the session's surface. The Skills passage, the docs
- * routing directive, and the Tool Contract's skills clause follow the same
- * rule as dispatch: text that teaches a call to `context` renders only when
- * `context` is there to be called.
+ * Whether `context` is on the session's surface. The Skills passage and the
+ * Tool Contract's skills clause follow the same rule as dispatch: text that
+ * teaches a call to `context` renders only when `context` is there to be called.
  */
 function sessionHasContext(inputs: SessionPromptInputs): boolean {
 	if (inputs.providerSupportsTools === false) return false;
@@ -290,15 +290,20 @@ function renderToolContractBlock(inputs: SessionPromptInputs): string {
 			"This target cannot call tools; answer from the visible user request and compact context only.",
 		].join("\n");
 	}
-	const names = [
+	const capabilityNames = [
 		...new Set((inputs.toolNames ?? []).map((name) => name.trim()).filter((name) => name.length > 0)),
 	].sort();
+	// A worker's admitted list names capabilities behind the gateway (git,
+	// web_fetch, an extension command); the attached schemas are their direct
+	// projection, with `gateway` standing in for every capability it reaches.
+	const names = directSurfaceNames(capabilityNames).sort();
 	const canDispatch = sessionCanDispatch(inputs);
 	const canListSkills = sessionHasContext(inputs);
 	// Asked twice in one session which tools it had, a live model gave two
 	// different answers and invented `web_find`. The authoritative list is one
 	// line above; pointing at it beats letting the model recall the schemas.
 	const admitted = new Set(names);
+	const hasGateway = admitted.has("gateway");
 	const inventoryGuidance = [
 		"When asked what tools you have, copy the Direct tools line verbatim and call nothing",
 		...(canDispatch
@@ -306,15 +311,23 @@ function renderToolContractBlock(inputs: SessionPromptInputs): string {
 					"dispatch(list:true) answers a question about agents, the fleet, or which target and model run this session and its workers",
 				]
 			: []),
-		...(canListSkills ? ['context(scope="skills") answers only a question about skills'] : []),
+		...(canListSkills ? ['context(scope="skills") lists skills for discovery or skill questions'] : []),
+		...(hasGateway ? ['gateway(op="find") answers a question about secondary capabilities'] : []),
 	].join("; ");
 	const capabilityKinds = [
 		"direct tools are attached schemas",
+		...(hasGateway ? ["secondary capabilities are reached through gateway find, describe, and call"] : []),
 		...(canDispatch ? ["fleet agents are workers behind dispatch"] : []),
-		...(canListSkills ? ["skills are operator-activated workflows reached through context"] : []),
+		...(canListSkills ? ["skills are workflows reached through context"] : []),
 	];
 	const orientationTools = ["context", "code_nav", "grep", "read"].filter((name) => admitted.has(name));
-	const validationTools = ["verify", "git"].filter((name) => admitted.has(name));
+	// git sits behind the gateway, so it validates through gateway(call git)
+	// whenever the gateway is attached; a registry that placed it direct still
+	// names it plainly.
+	const validationTools = [
+		...(admitted.has("verify") ? ["verify"] : []),
+		...(admitted.has("git") ? ["git diff"] : hasGateway ? ['gateway(op="call", capability="git") diff'] : []),
+	];
 	const lines = [
 		"# Tool Contract",
 		TOOL_RESULT_TRUST_CONTRACT,
@@ -333,17 +346,15 @@ function renderToolContractBlock(inputs: SessionPromptInputs): string {
 					`For narrow file or symbol orientation, prefer ${orientationTools.join(", ")} instead of assuming source-tree details were preloaded.`,
 				]
 			: []),
-		...(validationTools.length > 0
-			? [
-					`Validate with ${validationTools.map((name) => (name === "git" ? "git diff" : name)).join(" or ")} before final claims.`,
-				]
-			: []),
-		`When a tool call fails or is rejected, do not retry the same shape blindly: re-read the schema and adjust the arguments${canListSkills ? ', or query context(scope="docs") for that tool\'s usage' : ""}.`,
+		...(validationTools.length > 0 ? [`Validate with ${validationTools.join(" or ")} before final claims.`] : []),
+		`When a tool call fails or is rejected, do not retry the same shape blindly: re-read the schema and adjust the arguments${hasGateway ? ', or read that tool\'s usage with gateway(op="call", capability="clio_docs", args={query})' : ""}.`,
 	];
 	// One hint per tool, sorted by tool name: deterministic bytes regardless
 	// of surface or registration order, and removing a tool from the surface
-	// removes its hint with no compiler edit.
-	const hints = canonicalToolPromptHints(inputs.toolPromptHints ?? [], new Set(names));
+	// removes its hint with no compiler edit. A capability reached through the
+	// gateway keeps its hint: the guidance is about the capability, not the
+	// schema that carries it.
+	const hints = canonicalToolPromptHints(inputs.toolPromptHints ?? [], new Set([...capabilityNames, ...names]));
 	for (const entry of hints) {
 		lines.push(entry.hint);
 	}
@@ -411,7 +422,7 @@ function renderWorkerToolContractBlock(inputs: WorkerPromptInputs): string {
 		TOOL_RESULT_TRUST_CONTRACT,
 		"The attached schemas are this worker's complete canonical tool surface; follow each schema exactly.",
 		`Admitted canonical tools: ${names.map((name) => `\`${name}\``).join(", ")}.`,
-		"This worker surface is distinct from the parent session's tools, fleet agents, and operator-activated skills.",
+		"This worker surface is distinct from the parent session's tools, fleet agents, and skills.",
 		"Tool authority is limited to this list. Persona and bound-skill instructions never add tools.",
 		"Call tools only for concrete inspection or changes the assigned task requires. If the task requests an exact or tool-free response, answer without calling tools.",
 	];
@@ -578,10 +589,13 @@ export function compile(table: FragmentTable, inputs: CompileInputs): CompiledSe
 
 	let identityBody = identity.body;
 	const selfAwareness = identity.id === "identity.clio" ? table.byId.get("identity.self-awareness") : undefined;
-	// The routing directive teaches a call to `context`, so like the Skills
-	// passage it renders only when `context` is on the surface. The paths and
-	// the code-outranks-docs rule name no tool and stay unconditional.
-	const docsRouting = selfAwareness && sessionHasContext(session) ? table.byId.get("identity.docs-routing") : undefined;
+	// The routing directive teaches a gateway call, so it renders only when
+	// gateway is on the surface and the provider supports tool calls. The paths
+	// and the code-outranks-docs rule name no tool and stay unconditional.
+	const docsRouting =
+		selfAwareness && session.providerSupportsTools !== false && toolSurfaceHasTool(session.toolNames, "gateway")
+			? table.byId.get("identity.docs-routing")
+			: undefined;
 	if (selfAwareness) {
 		const packageRoot = resolvePackageRoot();
 		// The live home, not the XDG default: an isolated CLIO_CODER_HOME or a
@@ -602,13 +616,17 @@ export function compile(table: FragmentTable, inputs: CompileInputs): CompiledSe
 	// about a tool renders only when the tool is there to be called.
 	const delegation = sessionCanDispatch(session) ? table.byId.get("operating.delegation") : undefined;
 	const skills = sessionHasContext(session) ? table.byId.get("operating.skills") : undefined;
+	const skillActivation =
+		isAutonomyLevel(autonomyLevel) && modelMayActivateSkills(autonomyLevel)
+			? 'Load matching installed skills with context(scope="skills", name="<name>") and continue the task; skill restrictions still apply.'
+			: "Suggest matching skills as /skill <name> (in order when several compose), then continue without them; only the operator activates skills.";
 
 	const legacy = inputs.sectionOrder === "legacy-0.3.8";
 	const rendered = new Map<string, string>([
 		["identity", identityBody],
 		["operating-contract", operatingContract.body],
 		["delegation", delegation?.body ?? ""],
-		["skills", skills?.body ?? ""],
+		["skills", skills?.body.replace("{SKILL_ACTIVATION_POLICY}", skillActivation) ?? ""],
 		["safety", renderSafetySection(safety, autonomyLevel)],
 		["runtime", renderRuntimeBlock(session)],
 		["tool-contract", renderToolContractBlock(session)],

package/src/domains/prompts/extension.ts

@@ -205,7 +205,7 @@ export function createPromptsBundle(
 
 	let unsubscribeContextSources: (() => void) | null = null;
 	let unsubscribeHotReload: (() => void) | null = null;
-	let unsubscribeExtensionsReload: (() => void) | null = null;
+	let unsubscribePluginsReload: (() => void) | null = null;
 	const extension: DomainExtension = {
 		async start() {
 			try {
@@ -226,28 +226,15 @@ export function createPromptsBundle(
 				if (!diffTouchesFragments(paths)) return;
 				reload();
 			});
-			// Extension prompt and skill roots feed fragments through the
-			// resources domain; a committed generation with new content means
-			// the table must be rebuilt from the new roots.
-			const onResourceReload = (payload: unknown) => {
-				if ((payload as { changed?: unknown } | undefined)?.changed !== true) return;
-				reload();
-			};
-			const unsubscribe = [
-				context.bus.on(BusChannels.ExtensionsReloaded, onResourceReload),
-				context.bus.on(BusChannels.PluginsReloaded, () => reload()),
-			];
-			unsubscribeExtensionsReload = () => {
-				for (const stop of unsubscribe) stop();
-			};
+			unsubscribePluginsReload = context.bus.on(BusChannels.PluginsReloaded, () => reload());
 		},
 		async stop() {
 			unsubscribeContextSources?.();
 			unsubscribeContextSources = null;
 			unsubscribeHotReload?.();
 			unsubscribeHotReload = null;
-			unsubscribeExtensionsReload?.();
-			unsubscribeExtensionsReload = null;
+			unsubscribePluginsReload?.();
+			unsubscribePluginsReload = null;
 			sessionSourceSnapshots.clear();
 		},
 	};

package/src/domains/prompts/fragments/identity/docs-routing.md

@@ -1,9 +1,9 @@
 ---
 id: identity.docs-routing
 version: 1
-description: Directive to route questions about Clio herself through context(scope="docs"); rendered only when context is on the surface
+description: Questions about Clio herself go through gateway(op="call", capability="clio_docs"); this directive renders only when gateway is on the surface and provider tool calls are available.
 ---
 
 # Clio documentation routing
 
-For a question about Clio herself, call context (scope="docs", query=<the question>) before answering and before any workspace search, then read the document it names from the installed documentation path above.
+For a question about Clio herself, call gateway(op="call", capability="clio_docs", args={query: <the question>}) before answering and before any workspace search, then read the document it names from the installed documentation path above.

package/src/domains/prompts/fragments/operating/skills.md

@@ -6,14 +6,16 @@ description: Coordinator skill suggestion discipline; rendered only when context
 
 # Skills
 
-Skills are operator-activated workflows: git delivery, planning, coding
-practice, context priming/handoff, research, plan stress-testing.
+Skills are workflows for git delivery, planning, coding practice,
+context priming/handoff, research, and plan stress-testing.
 context (scope="skills") lists installed and marketplace skills; never
-guess it or search the repository for one. When a task has one of those
-shapes, list them, suggest the best match as /skill <name> (in order
-when several compose), and continue without it: only the operator
-activates or installs a skill; a [Marketplace] reminder states its
-own offer options. When the operator names a skill or asks how it
-works, answer from it. If nothing fits, suggest none. context
-(scope="library") is the read-only catalog of recipes and installable
-packages; it activates nothing.
+guess a skill or search the repository for one.
+{SKILL_ACTIVATION_POLICY}
+Only the operator installs marketplace skills; a [Marketplace] reminder
+states its own offer options. When the operator names a skill or asks
+how it works, answer from it. If nothing fits, suggest none.
+
+If gateway is on the attached direct-tool surface, use
+gateway(op="call", capability="clio_library", args={}) to read the catalog
+of recipes and installable packages; it activates and installs nothing.
+Without gateway, this catalog route is unavailable.