@iowarp/clio-coder 0.4.9 → 0.5.0

package/src/tools/compete-worktrees.ts

@@ -32,10 +32,16 @@ import {
 	unlinkSync,
 	writeFileSync,
 } from "node:fs";
-import { hostname } from "node:os";
 import { join, relative, resolve } from "node:path";
 import type { RunGateWorktreeProvenance, RunKind } from "../domains/dispatch/types.js";
 import { captureWorkspaceCheckpoint, workspaceCheckpointRef } from "../domains/dispatch/workspace-checkpoint.js";
+import {
+	currentProcessLease,
+	ownerIsAlive,
+	type ProcessLease,
+	processSnapshot,
+	validProcessLease,
+} from "./process-lease.js";
 import {
 	commitWorktreePath,
 	isCanonicalWorktreePathInside,
@@ -103,16 +109,10 @@ interface CompeteGroupManifest {
 	createdAt: string;
 	updatedAt: string;
 	winnerIndex?: number;
-	owner: CompeteProcessLease;
+	owner: ProcessLease;
 	runs: CompeteRunLease[];
 }
 
-interface CompeteProcessLease {
-	host: string;
-	pid: number;
-	birthToken: string | null;
-}
-
 interface CompeteRunLease {
 	runId: string;
 	pid: number | null;
@@ -148,79 +148,6 @@ function errorMessage(err: unknown): string {
 	return err instanceof Error ? err.message : String(err);
 }
 
-interface ProcessSnapshot {
-	alive: boolean;
-	birthToken: string | null;
-}
-
-/**
- * Return a PID-reuse-resistant process identity where the host exposes one.
- * Linux's kernel start ticks are stable for the lifetime of a process. The
- * portable fallback uses `ps` start time; if neither is available we retain
- * liveness but refuse to signal a live PID during restart recovery.
- */
-function processSnapshot(pid: number): ProcessSnapshot {
-	if (!Number.isSafeInteger(pid) || pid <= 0) return { alive: false, birthToken: null };
-	try {
-		process.kill(pid, 0);
-	} catch (err) {
-		if ((err as NodeJS.ErrnoException).code !== "EPERM") return { alive: false, birthToken: null };
-	}
-
-	try {
-		const stat = readFileSync(`/proc/${pid}/stat`, "utf8").trim();
-		const close = stat.lastIndexOf(")");
-		if (close > 0) {
-			// Fields after the command name start at kernel field 3. Field 3 is
-			// process state and field 22 (index 19 here) is starttime in ticks.
-			const fields = stat
-				.slice(close + 1)
-				.trim()
-				.split(/\s+/u);
-			if (fields[0] === "Z") return { alive: false, birthToken: fields[19] ?? null };
-			const startTicks = fields[19];
-			if (startTicks !== undefined && /^\d+$/u.test(startTicks)) {
-				return { alive: true, birthToken: `linux:${startTicks}` };
-			}
-		}
-	} catch {
-		// Non-Linux host or procfs unavailable; try the portable fallback.
-	}
-
-	try {
-		const started = execFileSync("ps", ["-o", "lstart=", "-p", String(pid)], {
-			encoding: "utf8",
-			stdio: ["ignore", "pipe", "ignore"],
-			timeout: 2_000,
-		}).trim();
-		if (started.length > 0) return { alive: true, birthToken: `ps:${started}` };
-	} catch {
-		// The PID exists, but it cannot be identified strongly enough to kill.
-	}
-	return { alive: true, birthToken: null };
-}
-
-function currentProcessLease(): CompeteProcessLease {
-	return {
-		host: hostname(),
-		pid: process.pid,
-		birthToken: processSnapshot(process.pid).birthToken,
-	};
-}
-
-function validProcessLease(value: unknown): value is CompeteProcessLease {
-	if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
-	const lease = value as Record<string, unknown>;
-	return (
-		typeof lease.host === "string" &&
-		lease.host.length > 0 &&
-		typeof lease.pid === "number" &&
-		Number.isSafeInteger(lease.pid) &&
-		lease.pid > 0 &&
-		(lease.birthToken === null || typeof lease.birthToken === "string")
-	);
-}
-
 function validRunLease(value: unknown): value is CompeteRunLease {
 	if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
 	const lease = value as Record<string, unknown>;
@@ -233,16 +160,6 @@ function validRunLease(value: unknown): value is CompeteRunLease {
 	);
 }
 
-function ownerIsAlive(owner: CompeteProcessLease): boolean {
-	if (owner.host !== hostname()) return true;
-	const snapshot = processSnapshot(owner.pid);
-	if (!snapshot.alive) return false;
-	// A null identity cannot distinguish PID reuse, so preserving is the only
-	// safe choice. Supported hosts normally provide a token above.
-	if (owner.birthToken === null || snapshot.birthToken === null) return true;
-	return owner.birthToken === snapshot.birthToken;
-}
-
 function waitForProcessExit(pid: number, birthToken: string): boolean {
 	const deadline = Date.now() + PROCESS_EXIT_GRACE_MS;
 	const sleeper = new Int32Array(new SharedArrayBuffer(4));

package/src/tools/context/docs-engine.ts

@@ -3,9 +3,9 @@ import { basename, join, relative, resolve } from "node:path";
 import { resolvePackageRoot } from "../../core/package-root.js";
 
 // Deterministic, dependency-free retrieval over Clio's bundled human docs,
-// serving context(scope=docs). This intentionally avoids embeddings or network
-// calls so docs retrieval works in a packaged offline CLI, but it is still
-// richer than grep: it builds a section index with heading hierarchy, line
+// serving the `clio_docs` gateway capability. It intentionally avoids
+// embeddings or network calls so retrieval works in a packaged offline CLI.
+// It is still richer than grep: it builds a section index with heading hierarchy, line
 // ranges, light stemming, controlled Clio vocabulary aliases, phrase boosts,
 // and BM25-style body scoring.
 
@@ -22,6 +22,12 @@ const PHRASE_BODY_BOOST = 3.0;
 const PHRASE_HEADING_BOOST = 7.0;
 const COVERAGE_BOOST = 4.0;
 const EXPANDED_TERM_WEIGHT = 0.45;
+const NONCURRENT_REFERENCE_WEIGHT = 0.25;
+
+const NONCURRENT_REFERENCE_PATH =
+	/^docs\/(?:history\/|gui\/(?!readme\.md$)|process\/[^/]*(?:proposal|audit-v\d|battletest-\d{4})[^/]*\.md$)/iu;
+const EXPLICIT_NONCURRENT_INTENT =
+	/\b(?:histor(?:y|ical|ic)|archives?|archived|proposal|proposed|blueprints?|design|spec(?:ification)?s?|roadmaps?|audits?|legacy|previous|older|old)\b/iu;
 
 const STOP_WORDS = new Set([
 	"a",
@@ -199,8 +205,16 @@ function unique<T>(items: ReadonlyArray<T>): T[] {
 	return [...new Set(items)];
 }
 
-function slugify(heading: string): string {
-	return normalizeText(heading).replace(/\s+/g, "-") || "section";
+function slugify(heading: string, counts: Map<string, number>): string {
+	const base = heading
+		.replace(/<[^>]*>/g, "")
+		.replace(/[`*_~]/g, "")
+		.toLowerCase()
+		.replace(/[^\p{L}\p{N}_\s-]/gu, "")
+		.replace(/\s/g, "-");
+	const count = counts.get(base) ?? 0;
+	counts.set(base, count + 1);
+	return count > 0 ? `${base}-${count}` : base;
 }
 
 function titleFromFile(name: string): string {
@@ -227,6 +241,7 @@ function parseSections(file: string, markdown: string): RawSection[] {
 	let buffer: string[] = [];
 	let inFence = false;
 	const stack: Array<{ level: number; text: string }> = [];
+	const headingCounts = new Map<string, number>();
 
 	const breadcrumbFor = (): string => {
 		const parts = stack.map((entry) => entry.text);
@@ -243,7 +258,7 @@ function parseSections(file: string, markdown: string): RawSection[] {
 				heading,
 				breadcrumb: breadcrumbFor(),
 				level,
-				anchor: heading === "(overview)" ? "" : `#${slugify(heading)}`,
+				anchor: heading === "(overview)" ? "" : `#${slugify(heading, headingCounts)}`,
 				startLine: headingLine,
 				bodyStartLine,
 				endLine: Math.max(headingLine, endLine),
@@ -469,6 +484,21 @@ function scoreSection(index: DocsIndex, section: IndexedSection, plan: QueryPlan
 	};
 }
 
+/**
+ * Keep historical records and GUI design blueprints searchable, but let current
+ * operator guidance lead ordinary self-help queries. Their paths and names are
+ * the status markers already used by the docs tree; an explicit history/design
+ * query removes the demotion so those documents remain directly retrievable.
+ */
+function prioritizeCurrentGuidance(entry: ScoredSection, query: string): ScoredSection {
+	if (!NONCURRENT_REFERENCE_PATH.test(entry.section.file) || EXPLICIT_NONCURRENT_INTENT.test(query)) return entry;
+	return {
+		...entry,
+		score: entry.score * NONCURRENT_REFERENCE_WEIGHT,
+		signals: unique(["historical/design reference demotion", ...entry.signals]).slice(0, 6),
+	};
+}
+
 function cleanSnippet(text: string): string {
 	return text
 		.replace(/^\s{0,3}#{1,6}\s+/gm, "")
@@ -560,7 +590,7 @@ function resultPayload(index: DocsIndex, plan: QueryPlan, scored: ReadonlyArray<
 		results,
 		followUp:
 			results.length > 0
-				? "Cited files are Clio's bundled docs: read them from the installed documentation path named in your prompt, never by searching the workspace for them. For more depth, run another context scope=docs query with more specific terms."
+				? 'Cited files are Clio\'s bundled docs: read them from the installed documentation path named in your prompt, never by searching the workspace for them. For more depth, call gateway(op="call", capability="clio_docs", args={query:"<more specific terms>"}).'
 				: "Try Clio vocabulary such as target, autonomy, dispatch, evidence, middleware, context, validation, install, or model catalog.",
 	};
 }
@@ -572,9 +602,8 @@ export type DocsCorpusOutcome =
 /**
  * List the bundled-docs corpus without running a query: the file set plus the
  * doc/section counts a successful search already carries under `corpus`. This
- * is what the model wants when it sends `scope=docs` with no query — an index
- * to pick a search term from — and it saves the wasted round the old
- * `requires query` error forced. Bounded: the corpus is a handful of files.
+ * lets the model inspect the corpus through `clio_docs` with no query before
+ * choosing a search term. Bounded: the corpus is a handful of files.
  */
 export function listDocsCorpus(): DocsCorpusOutcome {
 	const loaded = loadDocsIndex();
@@ -589,7 +618,7 @@ export function listDocsCorpus(): DocsCorpusOutcome {
 			excludes: ["docs/html/**"],
 		},
 		followUp:
-			"Pass query=<terms> to search these bundled docs; they ship with Clio and are not workspace files. " +
+			'Call gateway(op="call", capability="clio_docs", args={query:"<terms>"}) to search these bundled docs; omit query to list the corpus. They ship with Clio and are not workspace files. ' +
 			"Try Clio vocabulary such as target, autonomy, dispatch, evidence, middleware, context, validation, install, or model catalog.",
 	};
 	return { ok: true, payload, fileCount: index.files.length };
@@ -620,7 +649,10 @@ export function searchDocs(query: string, limitArg: unknown): DocsSearchOutcome
 	if (!loaded.ok) return { ok: false, message: loaded.message };
 	const limit = clampDocsLimit(limitArg);
 	const ranked = loaded.index.sections
-		.map((section) => scoreSection(loaded.index, section, plan))
+		.map((section) => {
+			const scored = scoreSection(loaded.index, section, plan);
+			return scored === null ? null : prioritizeCurrentGuidance(scored, query);
+		})
 		.filter((entry): entry is ScoredSection => entry !== null)
 		.sort(
 			(a, b) =>

package/src/tools/context/index.ts

@@ -1,6 +1,8 @@
 import { type Dirent, readdirSync } from "node:fs";
 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,
@@ -21,6 +23,8 @@ import {
 import {
 	checkSkillDrift,
 	discoverMarketplaceSkills,
+	installedSkillNames,
+	installedSkillPackages,
 	type LoadSkillsInput,
 	loadSkills,
 	type MarketplaceSkill,
@@ -74,6 +78,8 @@ export interface ContextSessionDeps {
 }
 
 export interface ContextToolDeps {
+	/** 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. */
 	workerRecall?: WorkerRecall;
 	getCwd?: () => string;
@@ -278,7 +284,7 @@ function marketplaceRowsFor(
 	if (deps.getSkillLoaderOptions?.().disableDiscovery === true) return [];
 	const policy = options?.pendingSkillPolicy;
 	if (policy && policyIsRecipeBound(policy)) return [];
-	const installedNames = new Set(installed.map((skill) => skill.name));
+	const installedNames = installedSkillNames(installed, cwdFromDeps(deps));
 	try {
 		return discoverMarketplaceSkills({ cwd: cwdFromDeps(deps) }).skills.filter(
 			(entry) => !installedNames.has(entry.name),
@@ -293,31 +299,58 @@ function renderSkillsList(
 	marketplace: ReadonlyArray<MarketplaceSkill>,
 	marketplaceOffered: boolean,
 	modelActivation: boolean,
+	packages: ReturnType<typeof installedSkillPackages> = [],
 ): string {
-	if (skills.length === 0 && marketplace.length === 0) {
+	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 installed and no marketplace is configured." : "No skills are installed.";
+		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.", ""];
-	if (skills.length > 0) {
-		lines.push("Installed:");
-		for (const skill of skills) {
-			lines.push(`- ${skill.name} (${skill.scope}): ${skill.description}`);
+
+	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}`,
+			);
 		}
-	} else {
-		lines.push("Installed: none.");
+		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 (not installed; /skill <name> offers to install):");
+		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}`);
@@ -328,15 +361,14 @@ function renderSkillsList(
 	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 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, 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 the answer, and the model
-		// never performs an install itself.
+		// 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 the answer and any install; never install or load a skill yourself.`,
+			`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.`,
 		);
 	}
 	return lines.join("\n");
@@ -359,7 +391,12 @@ function runWorkspaceScope(
 	// Orientation is where the model actually looks before multi-step work, so
 	// the snapshot carries a one-line pointer at the skill catalog. Pointer
 	// only: no catalog entries here, and loading stays operator-gated.
-	const payload = withSkillsPointer(deps, snap);
+	const payload = {
+		...withSkillsPointer(deps, snap),
+		...(deps.getSettings
+			? { configuration: 'For current autonomy, limits, and configuration guidance, call context(scope="settings").' }
+			: {}),
+	};
 	return finalizeObservation({
 		tool: ToolNames.Context,
 		unit: "results",
@@ -387,7 +424,7 @@ function withSkillsPointer(deps: ContextToolDeps, snap: WorkspaceSnapshot): Reco
 	if (installed === 0 && installable === 0) return { ...snap };
 	return {
 		...snap,
-		skills: `Skills: ${installed} installed, ${installable} installable from the marketplace. If one matches this task, or the operator names a skill, list them with context(scope="skills") and suggest /skill <name> to the operator; load only on operator request.`,
+		skills: `Skills: ${installed} available in Clio (ready workflows, not a marketplace installation count), ${installable} installable from the marketplace. If one matches this task, or the operator names a skill, list them with context(scope="skills") and suggest /skill <name> to the operator; load only on operator request.`,
 	};
 }
 
@@ -451,17 +488,26 @@ function runSkillsScope(
 		const list = loadSkills({ cwd: cwdFromDeps(deps), ...(deps.getSkillLoaderOptions?.() ?? {}) });
 		const visible = modelVisibleSkills(list.items);
 		const marketplace = marketplaceRowsFor(deps, list.items, options);
+		const packages =
+			deps.skillMarketplace === false || deps.getSkillLoaderOptions?.().disableDiscovery === true
+				? []
+				: installedSkillPackages(
+						list.items,
+						cwdFromDeps(deps),
+						deps.getSkillLoaderOptions?.().trustProjectCompatRoots === true,
+					);
 		const rendered = renderSkillsList(
 			visible,
 			marketplace,
 			deps.skillMarketplace !== false,
 			options?.pendingSkillPolicy?.modelActivation === true,
+			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;
+		const total = visible.length + marketplace.length + packages.length;
 		return finalizeObservation({
 			tool: ToolNames.Context,
 			unit: "entries",
@@ -471,7 +517,13 @@ function runSkillsScope(
 			totalCount: total,
 			truncated: truncation.truncated,
 			details: {
-				skills: visible.map((skill) => ({ name: skill.name, scope: skill.scope })),
+				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 } : {}),
@@ -490,15 +542,30 @@ function runSkillsScope(
 		visible.find((item) => item.name === name) ??
 		list.items.find((item) => item.name === name && operatorRequestedManualSkill(item, pendingRequest));
 	if (!skill) {
+		if (deps.skillMarketplace !== false && deps.getSkillLoaderOptions?.().disableDiscovery !== true) {
+			const installed = installedSkillPackages(
+				list.items,
+				cwdFromDeps(deps),
+				deps.getSkillLoaderOptions?.().trustProjectCompatRoots === true,
+			).find((pkg) => pkg.names.includes(name));
+			if (installed && installed.state !== "ready")
+				return {
+					kind: "error",
+					message: `context: skill "${name}" is installed in ${installed.scope} scope but ${installed.state}. Inspect it in /library; do not reinstall it.`,
+				};
+		}
 		const unavailable = list.items.find((item) => item.name === name);
 		if (unavailable) {
 			return {
 				kind: "error",
 				message: unavailable.trusted
 					? `context: skill "${name}" requires explicit operator activation with /skill ${name}; it disables model invocation. Do not retry this load.`
-					: `context: skill "${name}" was discovered in an untrusted ${unavailable.source}/${unavailable.scope} source and cannot be activated. Open /library to inspect its source and trust or install a reviewed native package. Do not retry this load.`,
+					: unavailable.source === "plugin"
+						? `context: skill "${name}" is imported but untrusted. Review it in /library, then enable integrations.projectResources.trustProjectImports to use it. Do not retry this load.`
+						: `context: skill "${name}" is discovered in ${unavailable.source}/${unavailable.scope}, not imported into Clio. Use interop adopt or library import explicitly; the trust setting alone does not activate it. Do not retry this load.`,
 			};
 		}
+
 		// A marketplace entry is a skill that exists and is not installed. Saying
 		// "unknown skill" about it denies the operator a thing the listing just
 		// offered; name the state and the one move that changes it.
@@ -506,7 +573,7 @@ function runSkillsScope(
 		if (installable) {
 			return {
 				kind: "error",
-				message: `context: skill "${name}" is not installed; it is available in the marketplace. Ask the operator to run /skill ${name}, which offers to install it, and wait. Do not retry this load.`,
+				message: `context: skill "${name}" is not installed; it is available in the marketplace. If installation has not been declined, offer /skill ${name} to install it. If the operator chose Not now or Cancel, continue without this skill and do not offer it again. Do not retry this load.`,
 			};
 		}
 		const available = visible.map((item) => item.name).join(", ");
@@ -715,10 +782,10 @@ 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 !== "skills" && scope !== "recall") {
+			if (scope !== "workspace" && scope !== "settings" && scope !== "skills" && scope !== "recall") {
 				return {
 					kind: "error",
-					message: `context: scope must be workspace, skills, or recall; got '${scope}'`,
+					message: `context: scope must be workspace, settings, skills, or recall; got '${scope}'`,
 				};
 			}
 			const selfCap = scope === "skills" ? OBSERVE_SELF_CAPS.contextSkills : OBSERVE_SELF_CAPS.contextWorkspace;
@@ -734,6 +801,43 @@ export function createContextTool(deps: ContextToolDeps = {}): ToolSpec {
 					hint: "Continue in a follow-up turn.",
 				});
 			}
+			if (scope === "settings") {
+				if (!deps.getSettings)
+					return {
+						kind: "error",
+						message:
+							"An authoritative live settings snapshot is unavailable in this run. Ask the user to open /settings or run clio-coder config inspect; do not infer current limits from defaults.",
+					};
+				const offset = args.offset === undefined ? 0 : args.offset;
+				const limit = args.limit === undefined ? 12 : args.limit;
+				if (
+					typeof offset !== "number" ||
+					!Number.isSafeInteger(offset) ||
+					offset < 0 ||
+					typeof limit !== "number" ||
+					!Number.isSafeInteger(limit) ||
+					limit < 1 ||
+					limit > 12
+				)
+					return { kind: "error", message: "Use a non-negative integer offset and a limit from 1 to 12." };
+				const snapshot = settingsAwareness(
+					deps.getSettings(),
+					typeof args.query === "string" ? args.query : "",
+					offset,
+					limit,
+				);
+				return finalizeObservation({
+					tool: ToolNames.Context,
+					unit: "entries",
+					format: "json",
+					output: JSON.stringify(snapshot, null, 2),
+					shownCount: snapshot.rows.length,
+					totalCount: snapshot.total,
+					truncated: snapshot.nextOffset !== null,
+					reservation,
+					...(options ? { 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/library.ts

@@ -63,7 +63,7 @@ const WORKER_UNAVAILABLE =
 	"Work from the resources your assignment already bound, and record the gap with the limitation tool if it blocks the task.";
 
 const OPERATOR_NOTE =
-	"Read-only catalog: you cannot install or activate from here. Suggest /library to the operator for packages and /skill <name> for a skill. A hint row is a catalog claim, not a loaded recipe, and cannot be invoked.";
+	"Read-only catalog: this tool does not install or activate. For an operator-requested installation, use clio-coder library install kind:name --user or --project through bash with operator approval. /library is the interactive package manager; /skill <name> activates a skill. A hint row is a catalog claim, not a loaded recipe, and cannot be invoked.";
 const NOTE_SKILLS_OFF = "Skill discovery is off for this run, so no skill rows are listed.";
 const NOTE_INVENTORY_CAPPED =
 	"The inventory returned as many records as it carries, so this listing and its install evidence are incomplete; narrow with kind or query.";

package/src/tools/context/surface.ts

@@ -4,25 +4,30 @@ import { StringEnum } from "../../engine/ai.js";
 import type { ToolSurface } from "../lazy-tool.js";
 
 /**
- * The permanent context schema keeps the three scopes the base agent needs on
- * every turn: workspace state, skill activation, and recall of evicted
+ * The permanent context schema keeps the scopes the base agent needs on
+ * every turn: workspace state, effective settings, skill activation, and recall of evicted
  * results. Clio's bundled documentation and the recipe catalog are secondary
  * reads and live behind the gateway as `clio_docs` and `clio_library`.
  */
 export const contextToolSurface = {
 	name: ToolNames.Context,
 	description:
-		"Environment context: scope=workspace returns the git/project snapshot, scope=skills lists installed and marketplace skills or loads an installed one 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 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: Type.Object({
-		scope: StringEnum(["workspace", "skills", "recall"], { description: "Context source." }),
+		scope: StringEnum(["workspace", "settings", "skills", "recall"], { description: "Context source." }),
 		query: Type.Optional(
-			Type.String({ description: "scope=recall without ref: path, tool, or ref terms; omit to list." }),
+			Type.String({
+				description:
+					"scope=settings: settings path, section, or terms; scope=recall without ref: path, tool, or ref terms.",
+			}),
 		),
 		name: Type.Optional(Type.String({ description: "scope=skills: skill name to load; omit to list." })),
-		limit: Type.Optional(Type.Number({ description: "scope=recall: max refs (default 8, max 12)." })),
+		limit: Type.Optional(Type.Number({ description: "scope=settings or recall: bounded page size (max 12)." })),
 		ref: Type.Optional(Type.String({ description: "scope=recall: exact persisted result ref; omit for discovery." })),
 		offset: Type.Optional(
-			Type.Number({ description: "scope=recall discovery: zero-based offset; follow nextOffset (default 0)." }),
+			Type.Number({
+				description: "scope=settings or recall discovery: zero-based offset; follow nextOffset (default 0).",
+			}),
 		),
 		include_tree: Type.Optional(Type.Boolean({ description: "scope=skills: list files under the skill base_dir." })),
 	}),

package/src/tools/core-bootstrap.ts

@@ -1,4 +1,5 @@
 import type { ContextRecalledPayload } from "../core/bus-events.js";
+import type { ClioSettings } from "../core/config.js";
 import { ToolNames } from "../core/tool-names.js";
 import type { WorkerRecall } from "../domains/context/worker/recall.js";
 import type { LoadSkillsInput } from "../domains/resources/index.js";
@@ -39,6 +40,7 @@ import { webFetchToolSurface, webReadToolSurface } from "./web-fetch-surface.js"
 import { writeTool } from "./write.js";
 
 export interface CoreToolBootstrapDeps {
+	getSettings?: () => Readonly<ClioSettings>;
 	workerRecall?: WorkerRecall;
 	session?: SessionContract;
 	/** Full ledger of the current session; context(scope=recall) folds it. Absent in worker registries. */
@@ -162,6 +164,7 @@ export function registerCoreTools(registry: ToolRegistry, deps: CoreToolBootstra
 		),
 	});
 	const skillToolDeps = {
+		...(deps.getSettings ? { getSettings: deps.getSettings } : {}),
 		...(deps.workerRecall ? { workerRecall: deps.workerRecall } : {}),
 		getCwd: () => deps.session?.current()?.cwd ?? process.cwd(),
 		...(deps.getSkillLoaderOptions ? { getSkillLoaderOptions: deps.getSkillLoaderOptions } : {}),