@iowarp/clio-coder 0.5.0 → 0.5.2

package/src/tools/context/index.ts

@@ -3,14 +3,9 @@ import path from "node:path";
 import type { ContextRecalledPayload } from "../../core/bus-events.js";
 import type { ClioSettings } from "../../core/config.js";
 import { settingsAwareness } from "../../core/settings-awareness.js";
-import {
-	SKILL_INSTALL_OFFER_OPTION_NEVER,
-	SKILL_INSTALL_OFFER_OPTION_NOT_NOW,
-	SKILL_INSTALL_OFFER_OPTION_PROJECT,
-	SKILL_INSTALL_OFFER_OPTION_USER,
-	SKILL_SUGGESTION_ANCHOR,
-} from "../../core/skill-activation.js";
+import { SKILL_SUGGESTION_ANCHOR } from "../../core/skill-activation.js";
 import { ToolNames } from "../../core/tool-names.js";
+import type { BudgetProvider } from "../../domains/context/budget/inspection.js";
 import type { WorkerRecall } from "../../domains/context/worker/recall.js";
 import { foldWorkingSet } from "../../domains/context/working-set/fold.js";
 import {
@@ -21,7 +16,9 @@ import {
 	resolveRecall,
 } from "../../domains/context/working-set/recall.js";
 import {
+	buildSkillCatalogView,
 	checkSkillDrift,
+	checkSkillDriftBatch,
 	discoverMarketplaceSkills,
 	installedSkillNames,
 	installedSkillPackages,
@@ -30,6 +27,7 @@ import {
 	type MarketplaceSkill,
 	modelVisibleSkills,
 	type Skill,
+	type SkillCatalogRowKind,
 } from "../../domains/resources/index.js";
 import type { SessionEntryInput } from "../../domains/session/contract.js";
 import type { SessionEntry } from "../../domains/session/entries.js";
@@ -78,6 +76,8 @@ export interface ContextSessionDeps {
 }
 
 export interface ContextToolDeps {
+	/** Refreshes this run's native budget; absent for external/worker registries. */
+	getContextBudget?: BudgetProvider;
 	/** Live session view, including overrides. Omit when no authoritative settings snapshot exists. */
 	getSettings?: () => Readonly<ClioSettings>;
 	/** Run-scoped evidence port; never reads or appends the parent session. */
@@ -294,84 +294,29 @@ function marketplaceRowsFor(
 	}
 }
 
-function renderSkillsList(
-	skills: ReadonlyArray<Skill>,
-	marketplace: ReadonlyArray<MarketplaceSkill>,
-	marketplaceOffered: boolean,
-	modelActivation: boolean,
-	packages: ReturnType<typeof installedSkillPackages> = [],
-): string {
-	if (skills.length === 0 && marketplace.length === 0 && packages.length === 0) {
-		// A registry that never offers the marketplace (a worker) must not
-		// claim none is configured; it simply has nothing to list.
-		return marketplaceOffered
-			? "No skills are available in Clio and no additional marketplace skills were found."
-			: "No skills are available in Clio.";
-	}
-	// The header names the listing and nothing more. The reply protocol is
-	// stated once, as the recency anchor at the bottom, because that is the
-	// line literal models act on; a second copy up here cost every listing
-	// call the same sentences again.
-	const lines = ["Available skills.", ""];
-
-	const native = skills.filter((skill) => skill.source === "clio-coder" || skill.source === "plugin");
-	const discovered = skills.filter((skill) => skill.source !== "clio-coder" && skill.source !== "plugin");
-	lines.push(`Ready skills in Clio (${native.length}):`);
-	if (native.length === 0) lines.push("- none");
-	for (const skill of native) {
-		lines.push(`- ${skill.name} (source: ${skill.source}; scope: ${skill.scope}): ${skill.description}`);
-	}
-	if (discovered.length > 0) {
-		lines.push("", "Explicitly supplied session skills (not installed packages):");
-		for (const skill of discovered) {
-			lines.push(
-				`- ${skill.name} (source: ${skill.source}; scope: ${skill.scope}; file: ${skill.filePath}): ${skill.description}`,
-			);
-		}
-		lines.push(
-			"These skills were explicitly supplied for this session. Preserve their source; session availability does not mean Clio installed or copied them.",
-		);
-	}
-
-	if (packages.length > 0) {
-		lines.push("", `Installed packages providing skills (${packages.length}):`);
-		for (const pkg of packages)
-			lines.push(
-				`- ${pkg.name} (scope: ${pkg.scope}; origin: ${pkg.origin === "catalog" ? "marketplace catalog" : pkg.origin}; state: ${pkg.state}; path: ${pkg.path})`,
-			);
-	}
-	lines.push(
-		"",
-		"Other-agent skill folders are discovery-only. Explicitly import into Clio before use; the trust-imports setting does not install or activate loose files.",
-	);
-
-	if (marketplace.length > 0) {
-		// Installable rows are suggested exactly like installed ones: the
-		// operator's /skill <name> prompts to install before it runs, so the
-		// model's move is the same suggest-and-wait. Only the body is out of
-		// reach until then, which is why the description is all that appears.
-		lines.push("", "Marketplace (additional skills available to install; /skill <name> offers to install):");
-		for (const entry of marketplace) {
-			const category = entry.category ? ` [${entry.category}]` : "";
-			lines.push(`- ${entry.name}${category}: ${entry.description}`);
-		}
-	}
-	// Recency anchor with an exact reply shape: literal models act on an output
-	// template where they skip conditional prose in the header.
-	lines.push(
-		"",
-		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 additions still require operator approval. 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
-		// option labels so the harness recognizes and handles the answer.
-		lines.push(
-			`When no installed skill serves the task but a marketplace skill above genuinely does, you may instead ask the operator with ask_user (mode=single_question, header "Install skill") whether to install it, offering exactly: "${SKILL_INSTALL_OFFER_OPTION_PROJECT}", "${SKILL_INSTALL_OFFER_OPTION_USER}", "${SKILL_INSTALL_OFFER_OPTION_NOT_NOW}", "${SKILL_INSTALL_OFFER_OPTION_NEVER}". The harness handles those exact offer options. An explicit operator request or approval also authorizes the documented library install CLI. After installation, refresh the inventory; distinguish installed from ready and report /library reload when required.`,
-		);
+/**
+ * Ready rows whose installed content no longer matches the hash recorded for
+ * it, resolved for the whole listing in one manifest read.
+ *
+ * Drift used to be checked only in the activation branch below, so the listing
+ * reported a drifted skill as ready with no caveat and the warning arrived only
+ * after the model had already spent its turn loading it. This is the same
+ * comparison, one step earlier, through the batched entry point so a listing
+ * does not re-parse the pin manifest once per row.
+ *
+ * It annotates and nothing else. The skill stays listed, stays ready and stays
+ * loadable, the installed copy keeps its ownership, and the activation warning
+ * is unchanged. A skill with no recorded hash is not marked, because absence of
+ * evidence is not drift, and a failure here yields an unmarked listing rather
+ * than no listing.
+ */
+function driftedSkillNames(skills: ReadonlyArray<Skill>, cwd: string): Set<string> {
+	try {
+		const reports = checkSkillDriftBatch(skills, cwd);
+		return new Set([...reports].filter(([, report]) => report.verdict === "mismatch").map(([name]) => name));
+	} catch {
+		return new Set<string>();
 	}
-	return lines.join("\n");
 }
 
 function runWorkspaceScope(
@@ -496,38 +441,71 @@ function runSkillsScope(
 						cwdFromDeps(deps),
 						deps.getSkillLoaderOptions?.().trustProjectCompatRoots === true,
 					);
-		const rendered = renderSkillsList(
-			visible,
-			marketplace,
-			deps.skillMarketplace !== false,
-			options?.pendingSkillPolicy?.modelActivation === true,
+		// The catalog is bounded but not small, and it has to fit the per-call cap
+		// like any observation. It is cut by whole rows with the reply protocol
+		// reserved first, rather than by head-truncating the finished string:
+		// head truncation keeps the head, and the tail is the one line a model
+		// acts on. `query`, `limit` and `offset` are the context tool's existing
+		// optional arguments, wired here so a caller can ask for less than all of
+		// it; omitting them still lists every row.
+		const view = buildSkillCatalogView({
+			skills: visible,
 			packages,
-		);
-		// 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.
-		const truncation = truncateHead(rendered, { maxBytes: reservation.callCapBytes, maxLines: Number.MAX_SAFE_INTEGER });
-		const total = visible.length + marketplace.length + packages.length;
+			marketplace,
+			drifted: driftedSkillNames(visible, cwdFromDeps(deps)),
+			marketplaceOffered: deps.skillMarketplace !== false,
+			modelActivation: options?.pendingSkillPolicy?.modelActivation === true,
+			query: typeof args.query === "string" ? args.query : "",
+			limit: typeof args.limit === "number" ? args.limit : undefined,
+			offset: typeof args.offset === "number" ? args.offset : 0,
+			capBytes: reservation.callCapBytes,
+		});
+		// Shown rows are selected by the row's own stable key, not by its name. An
+		// installed standalone skill has a ready row and a package row under one
+		// name, and the same package id can be installed at user and project scope,
+		// so a name set puts rows in `details` that the text never carried.
+		const shownKeys = new Set(view.rows.map((row) => row.key));
+		const shown = (kind: SkillCatalogRowKind, identity: string): boolean => shownKeys.has(`${kind}:${identity}`);
 		return finalizeObservation({
 			tool: ToolNames.Context,
 			unit: "entries",
-			output: truncation.content,
-			...(truncation.truncated ? { fullOutput: rendered } : {}),
-			shownCount: total,
-			totalCount: total,
-			truncated: truncation.truncated,
+			output: view.text,
+			shownCount: view.shown,
+			totalCount: view.total,
+			truncated: view.nextOffset !== undefined || view.shown < view.total,
+			// Offsets index the filtered result set. A continuation carrying only
+			// the offset would be applied to the unfiltered catalog, which repeats
+			// rows and skips matches, so the envelope says the query is part of it.
+			...(view.nextOffset !== undefined
+				? {
+						next: view.filtered ? `offset=${view.nextOffset} with the same query` : `offset=${view.nextOffset}`,
+					}
+				: {}),
 			details: {
-				skills: visible.map((skill) => ({
-					name: skill.name,
-					scope: skill.scope,
-					source: skill.source,
-					path: skill.filePath,
-				})),
-				installedPackages: packages,
-				marketplace: marketplace.map((entry) => ({
-					name: entry.name,
-					...(entry.category ? { category: entry.category } : {}),
-				})),
+				// Rows on this page, so a caller reading `details` sees the same
+				// listing the text carries. The totals beside them are how a
+				// filtered or paged view is told apart from a complete one.
+				skills: visible
+					.filter((skill) => shown("ready", skill.filePath) || shown("session", skill.filePath))
+					.map((skill) => ({
+						name: skill.name,
+						scope: skill.scope,
+						source: skill.source,
+						path: skill.filePath,
+						...(view.driftedNames.includes(skill.name) ? { drift: "mismatch" } : {}),
+					})),
+				installedPackages: packages.filter((pkg) => shown("package", `${pkg.scope}:${pkg.path}`)),
+				marketplace: marketplace
+					.filter((entry) => shown("marketplace", entry.sourceUrl))
+					.map((entry) => ({
+						name: entry.name,
+						...(entry.category ? { category: entry.category } : {}),
+					})),
+				totalSkills: visible.length,
+				totalPackages: packages.length,
+				totalMarketplace: marketplace.length,
+				...(view.filtered ? { query: (args.query as string).trim(), matchMode: view.matchMode } : {}),
+				...(view.driftedNames.length > 0 ? { drifted: view.driftedNames } : {}),
 			},
 			reservation,
 			...(options ? { options } : {}),
@@ -767,6 +745,52 @@ function runRecallScope(
 	});
 }
 
+/** A byte-fitted JSON observation. Inspection never spills to disk. */
+function runBudgetScope(
+	deps: ContextToolDeps,
+	reservation: ObservationReservation,
+	options?: ToolInvokeOptions,
+): ToolResult {
+	const inspection = deps.getContextBudget?.() ?? {
+		status: "unavailable",
+		reason:
+			"This run has no native session budget port. Worker and external-agent budgets are not the parent session's budget.",
+	};
+	const payload =
+		inspection.status === "available"
+			? {
+					...inspection,
+					mode: "enforced",
+					admissionNote:
+						"Submission and continuation enforce input plus reserved output against the effective window. Counts are estimates unless provider-attested; pressure advice remains advisory.",
+				}
+			: inspection;
+	const full = JSON.stringify(payload);
+	const fits = Buffer.byteLength(full, "utf8") <= reservation.callCapBytes;
+	// Do not pass fullOutput to finalizeObservation: an inspection must not
+	// persist its view even when an optional projection contains huge text.
+	const output = fits
+		? full
+		: JSON.stringify({
+				status: "unavailable",
+				reason: "observation-limit",
+				message:
+					"The budget view exceeds the available observation bytes. Continue in a follow-up turn; do not retry this turn.",
+			});
+	return finalizeObservation({
+		tool: ToolNames.Context,
+		unit: "results",
+		format: "json",
+		output,
+		shownCount: fits ? 1 : 0,
+		totalCount: 1,
+		totalBytes: Buffer.byteLength(full, "utf8"),
+		truncated: !fits,
+		reservation,
+		...(options ? { options } : {}),
+	});
+}
+
 export function createContextTool(deps: ContextToolDeps = {}): ToolSpec {
 	return {
 		...contextToolSurface,
@@ -782,12 +806,21 @@ export function createContextTool(deps: ContextToolDeps = {}): ToolSpec {
 					message: `context: scope "${scope}" is a gateway capability now: call gateway(op="call", capability="${capability}", args={...}) or gateway(op="describe", capability="${capability}") for its arguments.`,
 				};
 			}
-			if (scope !== "workspace" && scope !== "settings" && scope !== "skills" && scope !== "recall") {
+			if (
+				scope !== "workspace" &&
+				scope !== "settings" &&
+				scope !== "skills" &&
+				scope !== "recall" &&
+				scope !== "budget"
+			) {
 				return {
 					kind: "error",
-					message: `context: scope must be workspace, settings, skills, or recall; got '${scope}'`,
+					message: `context: scope must be workspace, settings, skills, recall, or budget; got '${scope}'`,
 				};
 			}
+			if (scope === "budget" && Object.keys(args).some((key) => key !== "scope")) {
+				return { kind: "error", message: 'context: scope="budget" accepts only scope; it inspects the current request.' };
+			}
 			const selfCap = scope === "skills" ? OBSERVE_SELF_CAPS.contextSkills : OBSERVE_SELF_CAPS.contextWorkspace;
 			// Reserved before any scope handler runs, so an exhausted pool answers
 			// with the notice and no scope does its work for nothing.
@@ -796,6 +829,7 @@ export function createContextTool(deps: ContextToolDeps = {}): ToolSpec {
 				return observationBudgetExhausted({
 					tool: ToolNames.Context,
 					unit: scope === "skills" ? "entries" : "results",
+					...(scope === "budget" ? { format: "json" as const } : {}),
 					reservation,
 					subject: `scope=${scope}`,
 					hint: "Continue in a follow-up turn.",
@@ -838,6 +872,7 @@ export function createContextTool(deps: ContextToolDeps = {}): ToolSpec {
 					...(options ? { options } : {}),
 				});
 			}
+			if (scope === "budget") return runBudgetScope(deps, reservation, options);
 			if (scope === "workspace") return runWorkspaceScope(deps, reservation, options);
 			if (scope === "recall") return runRecallScope(deps, args, reservation, options);
 			return runSkillsScope(deps, args, reservation, options);

package/src/tools/context/surface.ts

@@ -12,22 +12,26 @@ import type { ToolSurface } from "../lazy-tool.js";
 export const contextToolSurface = {
 	name: ToolNames.Context,
 	description:
-		"Environment context: scope=settings explains current effective settings, autonomy, configured limits, and exact UI commands without exposing credentials; scope=workspace returns the git/project snapshot, scope=skills lists ready skills, installed package states and marketplace options, or loads a ready skill by name, scope=recall returns an exact persisted evicted or summarized tool result by ref; omit ref to discover historical results by query with bounded limit/offset pages. Clio's documentation and the recipe catalog are gateway capabilities (clio_docs, clio_library). For repository code and the repo's generated wiki use code_nav (mode=wiki).",
+		"Environment context: scope=settings explains effective settings, autonomy, limits and UI commands without credentials; workspace returns the git/project snapshot; budget inspects the native session's live request budget (read-only, shadow policy); skills lists ready skills, installed states and marketplace options, or loads a ready skill by name; recall retrieves persisted evicted/summarized tool results by ref, or discovers them by query with limit/offset pages. Clio docs and recipes: gateway capabilities clio_docs and clio_library. Repository code/wiki: code_nav (mode=wiki).",
 	parameters: Type.Object({
-		scope: StringEnum(["workspace", "settings", "skills", "recall"], { description: "Context source." }),
+		scope: StringEnum(["workspace", "settings", "skills", "recall", "budget"], { description: "Context source." }),
+		// These three carry three scopes each. The attached-schema byte budget in
+		// tests/contracts/gateway-prompt.test.ts had 18 bytes of headroom, so
+		// naming scope=skills here is paid for by compressing the wording rather
+		// than by widening a budget that exists to keep the prompt small.
 		query: Type.Optional(
 			Type.String({
 				description:
-					"scope=settings: settings path, section, or terms; scope=recall without ref: path, tool, or ref terms.",
+					"scope=settings: path/section/terms; scope=recall (no ref): path/tool/ref terms; scope=skills: narrow the list.",
 			}),
 		),
 		name: Type.Optional(Type.String({ description: "scope=skills: skill name to load; omit to list." })),
-		limit: Type.Optional(Type.Number({ description: "scope=settings or recall: bounded page size (max 12)." })),
+		limit: Type.Optional(
+			Type.Number({ description: "scope=settings/recall: page size (max 12); scope=skills: rows (max 200)." }),
+		),
 		ref: Type.Optional(Type.String({ description: "scope=recall: exact persisted result ref; omit for discovery." })),
 		offset: Type.Optional(
-			Type.Number({
-				description: "scope=settings or recall discovery: zero-based offset; follow nextOffset (default 0).",
-			}),
+			Type.Number({ description: "scope=settings, recall, or skills: 0-based offset; follow nextOffset." }),
 		),
 		include_tree: Type.Optional(Type.Boolean({ description: "scope=skills: list files under the skill base_dir." })),
 	}),

package/src/tools/core-bootstrap.ts

@@ -1,6 +1,7 @@
 import type { ContextRecalledPayload } from "../core/bus-events.js";
 import type { ClioSettings } from "../core/config.js";
 import { ToolNames } from "../core/tool-names.js";
+import type { BudgetProvider } from "../domains/context/budget/inspection.js";
 import type { WorkerRecall } from "../domains/context/worker/recall.js";
 import type { LoadSkillsInput } from "../domains/resources/index.js";
 import type { SessionContract } from "../domains/session/contract.js";
@@ -40,6 +41,8 @@ import { webFetchToolSurface, webReadToolSurface } from "./web-fetch-surface.js"
 import { writeTool } from "./write.js";
 
 export interface CoreToolBootstrapDeps {
+	/** Native session accounting only. Worker registries do not inherit it. */
+	getContextBudget?: BudgetProvider;
 	getSettings?: () => Readonly<ClioSettings>;
 	workerRecall?: WorkerRecall;
 	session?: SessionContract;
@@ -164,6 +167,7 @@ export function registerCoreTools(registry: ToolRegistry, deps: CoreToolBootstra
 		),
 	});
 	const skillToolDeps = {
+		...(deps.getContextBudget ? { getContextBudget: deps.getContextBudget } : {}),
 		...(deps.getSettings ? { getSettings: deps.getSettings } : {}),
 		...(deps.workerRecall ? { workerRecall: deps.workerRecall } : {}),
 		getCwd: () => deps.session?.current()?.cwd ?? process.cwd(),

package/src/tools/observation.ts

@@ -306,6 +306,8 @@ function bumpExhaustedStreak(key: string | null): number {
 export function observationBudgetExhausted(input: {
 	tool: string;
 	unit: ObservationUnit;
+	/** Preserve parseable JSON for structured inspection tools, without offloading. */
+	format?: ObservationFormat;
 	reservation: ObservationReservation;
 	subject: string;
 	hint: string;
@@ -322,7 +324,11 @@ export function observationBudgetExhausted(input: {
 		recordSpentBytes(reservation, byteLength(message));
 		return { kind: "error", message };
 	}
-	const output = `[observation budget exhausted for this turn before ${tool} ${subject}: ${spent}. ${hint}]`;
+	const message = `observation budget exhausted for this turn before ${tool} ${subject}: ${spent}. ${hint}`;
+	const output =
+		input.format === "json"
+			? JSON.stringify({ status: "unavailable", reason: "observation-budget-exhausted", message })
+			: `[${message}]`;
 	const shownBytes = byteLength(output);
 	recordSpentBytes(reservation, shownBytes);
 	const budget = budgetDetails(reservation);
@@ -336,7 +342,7 @@ export function observationBudgetExhausted(input: {
 		// the full size is the message itself; keep totalBytes >= shownBytes.
 		totalBytes: shownBytes,
 		truncated: true,
-		format: "text",
+		format: input.format ?? "text",
 		...(budget !== null ? { budget } : {}),
 	};
 	return { kind: "ok", output, details: { observation } };

package/src/tools/policy.ts

@@ -36,6 +36,7 @@ export const TOOL_PLANES: Readonly<Record<BuiltinToolName, PlaneExpectation>> =
 	[ToolNames.Find]: { plane: "observe", actionClass: "read", executionMode: "parallel" },
 	[ToolNames.Ls]: { plane: "observe", actionClass: "read", executionMode: "parallel" },
 	[ToolNames.CodeNav]: { plane: "observe", actionClass: "read", executionMode: "parallel" },
+	[ToolNames.SelfCompact]: { plane: "orchestrate", actionClass: "read", executionMode: "sequential" },
 	[ToolNames.Context]: { plane: "observe", actionClass: "read", executionMode: "parallel" },
 	[ToolNames.CredentialPresent]: { plane: "observe", actionClass: "read", executionMode: "parallel" },
 	// clio_docs and clio_library are the bundled-documentation and recipe-catalog
@@ -191,6 +192,8 @@ export function validateBuiltinToolPolicy(
 	const includeLedgerTools = options.includeLedgerTools ?? false;
 	const includeNetworkTools = options.includeNetworkTools ?? true;
 	const required = new Set<ToolName>(Object.values(ToolNames));
+	// The native interactive host alone supplies the durable continuity port.
+	required.delete(ToolNames.SelfCompact);
 	for (const tool of [...required]) {
 		if (!includeSessionTools && SESSION_BOUND_TOOLS.has(tool)) required.delete(tool);
 		if (!includeDispatchTools && DISPATCH_BOUND_TOOLS.has(tool)) required.delete(tool);

package/src/tools/self-compact.ts

@@ -0,0 +1,31 @@
+import { Type } from "typebox";
+import { ToolNames } from "../core/tool-names.js";
+import type { ToolSpec } from "./registry.js";
+
+export type RequestSelfCompact = (note: unknown, toolCallId: string, signal?: AbortSignal) => Promise<string>;
+
+/** Admission only. The native host owns reduction after this receipt settles. */
+export function createSelfCompactTool(request: RequestSelfCompact): ToolSpec {
+	return {
+		name: ToolNames.SelfCompact,
+		description:
+			"Save an exact handoff note and compact context before continuing this task. Call alone, with no sibling tools. Include current objective, decisions, evidence, paths, and next steps. A pending receipt is not proof of completion.",
+		parameters: Type.Object({
+			note_to_self: Type.String({
+				maxLength: 8192,
+				description: "Assistant-authored handoff text; nonblank, at most 8192 UTF-8 bytes. Preserved exactly.",
+			}),
+		}),
+		baseActionClass: "read",
+		executionMode: "sequential",
+		async run(args, options) {
+			try {
+				const note = (args as { note_to_self?: unknown }).note_to_self;
+				const output = await request(note, options?.toolCallId ?? "", options?.signal);
+				return { kind: "ok", output };
+			} catch (error) {
+				return { kind: "error", message: error instanceof Error ? error.message : String(error) };
+			}
+		},
+	};
+}

package/src/tools/surface.ts

@@ -39,6 +39,7 @@ export const TOOL_PLACEMENT: Readonly<Record<BuiltinToolName, ToolPlacement>> =
 	[ToolNames.Ls]: "direct",
 	[ToolNames.CodeNav]: "direct",
 	[ToolNames.Context]: "direct",
+	[ToolNames.SelfCompact]: "direct",
 	[ToolNames.CredentialPresent]: "gateway",
 	[ToolNames.ClioDocs]: "gateway",
 	[ToolNames.ClioLibrary]: "gateway",

package/src/tools/tasks.ts

@@ -174,7 +174,7 @@ export function createTasksTool(deps: TasksToolDeps): ToolSpec {
 			"pick moves one operator task uN onto the board; start marks one task active (the current focus); " +
 			"done completes a task (started or still pending) and requires note as the " +
 			"evidence the work actually finished; block parks it with a required reason; drop cancels it; list shows the board. " +
-			"For operator handoff, pick the intended uN and use its linked tN; CLI hand does not pick it. Never pick unrelated tasks. " +
+			"For operator handoff, pick the intended uN before work and use its linked tN; CLI hand alone does not pick it. Never pick unrelated tasks. " +
 			"Before claiming completion, list: the linked row must be completed and the operator task done on the same session/board link; report IDs and states. " +
 			"Work that did not happen is blocked or dropped, never done. A self-created plan is not operator authorization. " +
 			"For proposal-only work, plan/add with initialStatus=blocked and note naming the pending operator decision; " +

package/dist/chunk-CTFPFW3H.js

@@ -1,44 +0,0 @@
-import { createRequire as __clioCreateRequire } from "node:module"; const require = __clioCreateRequire(import.meta.url);
-import {
-  StringEnum
-} from "./chunk-L7G7K4I2.js";
-import {
-  ToolNames
-} from "./chunk-V4XJWDHR.js";
-import {
-  typebox_exports
-} from "./chunk-GH5ZR6JP.js";
-import {
-  init_esm_shims
-} from "./chunk-ECBHH7LU.js";
-
-// src/tools/context/surface.ts
-init_esm_shims();
-var contextToolSurface = {
-  name: ToolNames.Context,
-  description: "Environment context: scope=settings explains current effective settings, autonomy, configured limits, and exact UI commands without exposing credentials; scope=workspace returns the git/project snapshot, scope=skills lists ready skills, installed package states and marketplace options, or loads a ready skill by name, scope=recall returns an exact persisted evicted or summarized tool result by ref; omit ref to discover historical results by query with bounded limit/offset pages. Clio's documentation and the recipe catalog are gateway capabilities (clio_docs, clio_library). For repository code and the repo's generated wiki use code_nav (mode=wiki).",
-  parameters: typebox_exports.Object({
-    scope: StringEnum(["workspace", "settings", "skills", "recall"], { description: "Context source." }),
-    query: typebox_exports.Optional(
-      typebox_exports.String({
-        description: "scope=settings: settings path, section, or terms; scope=recall without ref: path, tool, or ref terms."
-      })
-    ),
-    name: typebox_exports.Optional(typebox_exports.String({ description: "scope=skills: skill name to load; omit to list." })),
-    limit: typebox_exports.Optional(typebox_exports.Number({ description: "scope=settings or recall: bounded page size (max 12)." })),
-    ref: typebox_exports.Optional(typebox_exports.String({ description: "scope=recall: exact persisted result ref; omit for discovery." })),
-    offset: typebox_exports.Optional(
-      typebox_exports.Number({
-        description: "scope=settings or recall discovery: zero-based offset; follow nextOffset (default 0)."
-      })
-    ),
-    include_tree: typebox_exports.Optional(typebox_exports.Boolean({ description: "scope=skills: list files under the skill base_dir." }))
-  }),
-  baseActionClass: "read",
-  executionMode: "parallel"
-};
-
-export {
-  contextToolSurface
-};
-//# sourceMappingURL=chunk-CTFPFW3H.js.map