@iowarp/clio-coder 0.4.3 → 0.4.5

package/src/domains/prompts/preload.ts

@@ -1,82 +1,156 @@
-/**
- * Project-context preload classification. One place owns the preload cliff:
- * the session compiler uses it to choose a full effective-handbook preload versus compact
- * synopsis, and reporting surfaces (context-init output, `clio-coder config
- * inspect`, the context-window overlay) use it to make the cliff visible.
- */
+import type { ProjectPromptContext } from "../context/contract.js";
+import { renderProjectContextFragment } from "../context/index.js";
+import { sha256 } from "./hash.js";
+import { safePrefixOffsets, sourceLineCount } from "./preload-prefix.js";
 
+/** Historical limits, measured in UTF-16 code units and rendered lines. */
 export const FULL_PROJECT_CONTEXT_MAX_CHARS = 8000;
 export const FULL_PROJECT_CONTEXT_MAX_LINES = 220;
-
-/** Fraction of a limit at which a full preload is flagged as near the cliff. */
-const NEAR_LIMIT_FRACTION = 0.9;
-
-export type ProjectPreloadMode = "full" | "synopsis" | "none";
+export type ProjectPreloadMode = "full" | "partial" | "synopsis" | "none";
 export type ProjectPreloadReason = "size" | "lines" | "no-clio-md";
-
+export interface ProjectPreloadSource {
+	path: string;
+	contentHash: string;
+	availableChars: number;
+	availableLines: number;
+	includedChars: number;
+	includedLines: number;
+	includedRange: [number, number] | null;
+	omittedRange: [number, number] | null;
+	omissionReason: "budget" | null;
+}
 export interface ProjectPreloadClass {
 	mode: ProjectPreloadMode;
-	/** Rendered project-context length in characters (untrimmed, as measured by the cliff). */
+	/** Available rendered UTF-16 code units; retained for historical readers. */
 	chars: number;
-	/** Rendered project-context line count. */
+	/** Available rendered lines, including the final split segment. */
 	lines: number;
-	/** Which limit forced the synopsis; null for full or none. */
 	reason: ProjectPreloadReason | null;
-	/** True when a full preload is within 10% of either limit. */
 	nearLimit: boolean;
-	/** Human line, e.g. "full (5.2kB, 130 lines)" or "synopsis (reason: size)". */
 	label: string;
+	/** Additive snapshot accounting; absent in historical full/synopsis records. */
+	includedChars?: number;
+	includedLines?: number;
+	sources?: ProjectPreloadSource[];
+	omittedSupportFragments?: number;
+	providerSupportsTools?: boolean | null;
 }
+const renderedLines = (text: string): number => (text.length === 0 ? 0 : text.split("\n").length);
 
-export interface ClassifyProjectPreloadInput {
-	/** True when at least one selected project handbook contributed to the rendered text. */
-	hasClioMd: boolean;
-	/** The rendered project prompt context (ProjectPromptContext.text). */
-	text: string;
-}
-
-function formatKb(chars: number): string {
-	return `${(chars / 1000).toFixed(1)}kB`;
+function coverage(path: string, source: string, included: string): ProjectPreloadSource {
+	const availableLines = sourceLineCount(source);
+	const includedLines = sourceLineCount(included);
+	return {
+		path,
+		contentHash: sha256(source),
+		availableChars: source.length,
+		availableLines,
+		includedChars: included.length,
+		includedLines,
+		includedRange: includedLines === 0 ? null : [1, includedLines],
+		omittedRange: included.length === source.length ? null : [includedLines + 1, availableLines],
+		omissionReason: included.length === source.length ? null : "budget",
+	};
 }
 
-/**
- * Classify how the session compiler will treat this project context. Must
- * mirror the selection in prompts/extension.ts exactly: full preload only
- * when a selected project handbook parses and the rendered text is within both the
- * char and line limits; empty text preloads nothing.
- */
-export function classifyProjectPreload(input: ClassifyProjectPreloadInput): ProjectPreloadClass {
-	const chars = input.text.length;
-	const lines = input.text.length === 0 ? 0 : input.text.split("\n").length;
-	if (input.text.trim().length === 0) {
-		return { mode: "none", chars, lines, reason: null, nearLimit: false, label: "none (no project context)" };
-	}
-	const reason: ProjectPreloadReason | null = !input.hasClioMd
-		? "no-clio-md"
-		: chars > FULL_PROJECT_CONTEXT_MAX_CHARS
-			? "size"
-			: lines > FULL_PROJECT_CONTEXT_MAX_LINES
-				? "lines"
-				: null;
-	if (reason !== null) {
+/** One selector owns delivered text and reporting; it never re-parses authored markers. */
+export function selectProjectPreload(
+	context: ProjectPromptContext,
+	providerSupportsTools: boolean | null = null,
+	options: { maxChars?: number; externalReadTools?: boolean } = {},
+): { text: string; classification: ProjectPreloadClass } {
+	const maxChars = options.maxChars ?? FULL_PROJECT_CONTEXT_MAX_CHARS;
+	const fits = (text: string): boolean =>
+		text.length <= maxChars && renderedLines(text) <= FULL_PROJECT_CONTEXT_MAX_LINES;
+	const chars = context.text.length;
+	const lines = renderedLines(context.text);
+	const classify = (
+		text: string,
+		mode: ProjectPreloadMode,
+		sources: ProjectPreloadSource[],
+		omittedSupportFragments: number,
+	): ProjectPreloadClass => {
+		const includedChars = text.length;
+		const includedLines = renderedLines(text);
+		const incomplete = sources.filter((source) => source.omissionReason !== null).length;
 		return {
-			mode: "synopsis",
+			mode,
 			chars,
 			lines,
-			reason,
-			nearLimit: false,
-			label: `synopsis (reason: ${reason})`,
+			includedChars,
+			includedLines,
+			sources,
+			omittedSupportFragments,
+			providerSupportsTools,
+			reason: mode !== "partial" ? null : chars > maxChars ? "size" : "lines",
+			nearLimit: mode === "full" && (chars > maxChars * 0.9 || lines > FULL_PROJECT_CONTEXT_MAX_LINES * 0.9),
+			label: `${mode} (included ${includedChars}/${chars} UTF-16 units, ${includedLines}/${lines} rendered lines; ${incomplete} of ${sources.length} handbook sources incomplete${providerSupportsTools === null ? "; tool capability unknown" : ""})`,
 		};
-	}
-	const nearLimit =
-		chars > FULL_PROJECT_CONTEXT_MAX_CHARS * NEAR_LIMIT_FRACTION ||
-		lines > FULL_PROJECT_CONTEXT_MAX_LINES * NEAR_LIMIT_FRACTION;
-	return {
-		mode: "full",
-		chars,
-		lines,
-		reason: null,
-		nearLimit,
-		label: `full (${formatKb(chars)}, ${lines} lines)`,
 	};
+	if (fits(context.text)) {
+		const sources = context.handbookSources.map(({ path, source }) => coverage(path, source, source));
+		return {
+			text: context.text,
+			classification: classify(context.text, context.text.length === 0 ? "none" : "full", sources, 0),
+		};
+	}
+	const retrieval =
+		providerSupportsTools === false
+			? "Remaining source text is unavailable to this target and cannot be recovered with tools in this session. Paths are source references."
+			: options.externalReadTools
+				? "External read tools are unknown. If available and permitted, read the listed omitted physical lines with your file-reading tool. Otherwise report the missing guidance to the parent. Reads use current disk content, which may differ from the captured source."
+				: `${providerSupportsTools === null ? "If tools are available, read" : "Read"} each omitted suffix with read({path: ABSOLUTE_PATH, offset: FIRST_OMITTED_LINE, limit: 200}); continue as needed. Reads use current disk content, which may differ from the captured source.`;
+	const header = [
+		"<project-preload>",
+		"Incomplete authored prefixes/excerpts: omitted guidance is not known from this preload. Read the selected sources before relying on project guidance.",
+		retrieval,
+	];
+	const totals = context.handbookSources.map(({ source }) => sourceLineCount(source));
+	const sourceRecord = (path: string, included: string, omitted: string): string =>
+		`${JSON.stringify(path)}: included physical lines ${included}; omitted physical lines ${omitted}.`;
+	const reservedRecords = context.handbookSources.map(({ path }, index) =>
+		sourceRecord(path, `none/${totals[index]}-${totals[index]}`, `none/${totals[index]}-${totals[index]} (budget)`),
+	);
+	const notice = (records: string[], omitted: number): string =>
+		[...header, ...records, `Support fragments omitted: ${omitted}.`, "</project-preload>"].join("\n");
+	const reservedNotice = notice(reservedRecords, context.supportFragments.length);
+	if (!fits(reservedNotice))
+		throw new Error(`project preload metadata-budget overflow for ${context.handbookSources.length} handbook sources`);
+	const excerpts = context.handbookSources.map(() => "");
+	const fragments = context.handbookSources.map(() => "");
+	const assemble = (metadata: string, support: readonly string[] = []): string =>
+		[metadata, ...fragments.filter(Boolean), ...support].join("\n\n");
+	// Allocate nearest first, while fragments retain the original ancestor-first order.
+	for (let index = context.handbookSources.length - 1; index >= 0; index--) {
+		const entry = context.handbookSources[index];
+		if (!entry) continue;
+		const { path, source } = entry;
+		for (const offset of safePrefixOffsets(source, maxChars).slice(1)) {
+			const previous = fragments[index] ?? "";
+			fragments[index] = renderProjectContextFragment(source.slice(0, offset), path);
+			if (!fits(assemble(reservedNotice))) {
+				fragments[index] = previous;
+				break;
+			}
+			excerpts[index] = source.slice(0, offset);
+		}
+	}
+	const support: string[] = [];
+	for (const fragment of context.supportFragments) {
+		if (fits(assemble(reservedNotice, [...support, fragment]))) support.push(fragment);
+	}
+	const sources = context.handbookSources.map(({ path, source }, index) =>
+		coverage(path, source, excerpts[index] ?? ""),
+	);
+	const records = sources.map((source) =>
+		sourceRecord(
+			source.path,
+			source.includedRange?.join("-") ?? "none",
+			source.omittedRange ? `${source.omittedRange.join("-")} (budget)` : "none",
+		),
+	);
+	const omitted = context.supportFragments.length - support.length;
+	const text = assemble(notice(records, omitted), support);
+	if (!fits(text)) throw new Error("project preload budget postcondition failed");
+	return { text, classification: classify(text, "partial", sources, omitted) };
 }

package/src/domains/providers/auth/backend-file.ts

@@ -1,9 +1,9 @@
-import { chmodSync, closeSync, existsSync, mkdirSync, openSync, readFileSync } from "node:fs";
+import { chmodSync, existsSync, mkdirSync, readFileSync } from "node:fs";
 import { readFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import { safeResourceWrite } from "../../../core/safe-resource-write.js";
 import { withStateFileLock, withStateFileLockSync } from "../../../core/state-file-lock.js";
-import { clioConfigDir } from "../../../core/xdg.js";
+import { resolveClioDirs } from "../../../core/xdg.js";
 import type { AuthOperationOptions } from "../../../engine/types.js";
 
 import type { AuthStorageBackend, LockResult } from "./storage.js";
@@ -20,7 +20,7 @@ function atomicWriteSecret(absPath: string, contents: string): void {
 }
 
 export function authStoragePath(): string {
-	return join(clioConfigDir(), "credentials.yaml");
+	return join(resolveClioDirs().config, "credentials.yaml");
 }
 
 export class FileAuthStorageBackend implements AuthStorageBackend {
@@ -34,18 +34,23 @@ export class FileAuthStorageBackend implements AuthStorageBackend {
 		mkdirSync(dirname(this.path), { recursive: true, mode: 0o700 });
 	}
 
-	private ensureFileExists(): void {
-		if (existsSync(this.path)) return;
-		const fd = openSync(this.path, "a", 0o600);
-		closeSync(fd);
-		chmodSync(this.path, 0o600);
+	// Writers publish complete files with an atomic rename, so a reader sees
+	// either the prior or next committed snapshot without creating a lockfile or
+	// initializing a missing home. Read-modify-write operations still take the
+	// exclusive lock below and read again inside it before merging changes.
+	read(): string | undefined {
+		try {
+			return readFileSync(this.path, "utf8");
+		} catch (error) {
+			if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined;
+			throw error;
+		}
 	}
 
 	withLock<T>(fn: (current: string | undefined) => LockResult<T>): T {
 		this.ensureParentDir();
-		this.ensureFileExists();
 		return withStateFileLockSync(this.path, () => {
-			const current = existsSync(this.path) ? readFileSync(this.path, "utf8") : undefined;
+			const current = this.read();
 			const { result, next } = fn(current);
 			if (next !== undefined) {
 				atomicWriteSecret(this.path, next);
@@ -60,7 +65,6 @@ export class FileAuthStorageBackend implements AuthStorageBackend {
 	): Promise<T> {
 		options?.signal?.throwIfAborted();
 		this.ensureParentDir();
-		this.ensureFileExists();
 		return withStateFileLock(
 			this.path,
 			async () => {

package/src/domains/providers/auth/storage.ts

@@ -38,6 +38,8 @@ export interface LockResult<T> {
 }
 
 export interface AuthStorageBackend {
+	/** A committed snapshot without creating storage or acquiring a write lock. */
+	read?(): string | undefined;
 	withLock<T>(fn: (current: string | undefined) => LockResult<T>): T;
 	withLockAsync<T>(
 		fn: (current: string | undefined) => Promise<LockResult<T>>,
@@ -305,11 +307,7 @@ export class AuthStorage {
 
 	reload(): void {
 		try {
-			let content: string | undefined;
-			this.backend.withLock((current) => {
-				content = current;
-				return { result: undefined };
-			});
+			const content = this.backend.read ? this.backend.read() : this.backend.withLock((current) => ({ result: current }));
 			const read = readStorageData(content);
 			this.data = read.data;
 			this.damage = read.damage;

package/src/domains/providers/catalog.ts

@@ -122,6 +122,8 @@ export interface CatalogBackedSynthesisInput {
 	runtimeId: string;
 	provider: string;
 	api: Api;
+	/** Use the catalog transport and its endpoint when no explicit target URL is configured. */
+	preferCatalogTransport?: boolean;
 	defaultBaseUrl: string;
 	defaultHeaders?: Record<string, string>;
 }
@@ -134,15 +136,28 @@ export function synthesizeCatalogBackedModel(input: CatalogBackedSynthesisInput)
 		null,
 		input.target.capabilities ?? null,
 	);
+	const api = input.preferCatalogTransport && input.target.url === undefined ? (builtin?.api ?? input.api) : input.api;
+	// A catalog endpoint, compatibility flags, and effort map describe one API.
+	// Explicit endpoints keep the runtime's API contract, even when a catalog
+	// model has moved to another transport (for example OpenRouter Claude).
+	const sameTransport = builtin?.api === api;
+	const catalogFields = { ...builtin };
+	if (input.preferCatalogTransport && !sameTransport) {
+		delete catalogFields.compat;
+		delete catalogFields.thinkingLevelMap;
+	}
 	const pricing = input.target.pricing;
 	const targetHeaders = input.target.auth?.headers;
 	const model: Model<Api> = {
-		...(builtin ?? {}),
+		...catalogFields,
 		id: input.wireModelId,
 		name: `${input.wireModelId} (${input.target.id})`,
-		api: input.api,
+		api,
 		provider: input.provider,
-		baseUrl: input.target.url ?? builtin?.baseUrl ?? input.defaultBaseUrl,
+		baseUrl:
+			input.target.url ??
+			(input.preferCatalogTransport && !sameTransport ? undefined : builtin?.baseUrl) ??
+			input.defaultBaseUrl,
 		reasoning: caps.reasoning,
 		input: caps.vision ? (builtin?.input.includes("image") ? builtin.input : ["text", "image"]) : ["text"],
 		cost: {

package/src/domains/providers/model-discovery.ts

@@ -76,10 +76,7 @@ export function modelResidencyForStatus(status: DiscoveryStatus | null | undefin
 }
 
 export function hasLiveModelCatalog(status: TargetStatus): boolean {
-	if (status.discoveredModelsSource === "probe" || status.discoveredModelsSource === "cache") return true;
-	// Unit-test and plugin mocks from before `discoveredModelsSource` still use
-	// `discoveredModels` to mean "this came from discovery".
-	return status.discoveredModelsSource === undefined && status.discoveredModels.length > 0;
+	return status.discoveredModelsSource === "probe" || status.discoveredModelsSource === "cache";
 }
 
 /**

package/src/domains/providers/models/local-models/clio-coder-local-coding-targets.yaml

@@ -1715,15 +1715,16 @@
         card's dial is reasoning strength with levels low, medium, high, and
         xhigh, set through the system prompt as "Reasoning strength: <value>",
         and the router passes it as chat_template_kwargs.reasoning_strength
-        pinned to xhigh. There is no off level on that scale, and no
-        ThinkingMechanism in this engine emits that key:
-        resolveRequestCapability populates chat_template_kwargs only with
-        enable_thinking or, on the harmony path, reasoning_effort. Encoding this
-        family as on-off would put a flag on the wire that this template does
-        not read while the TUI showed a working off/on dial, which is the
-        failure qwopus3.5-9b-v3 above was reclassified to stop. A real dial for
-        this family needs a per-family kwarg key in the engine, not a catalog
-        edit.
+        pinned to xhigh. There is no off level on that scale, so the family
+        stays always-on: encoding it as on-off would put an enable_thinking
+        flag on the wire that this template does not read while the TUI showed
+        a working off/on dial, which is the failure qwopus3.5-9b-v3 above was
+        reclassified to stop. The strength dial itself is driven per request:
+        thinking.chatTemplateKwargs.byLevel below maps Clio's thinking level to
+        chat_template_kwargs.reasoning_strength on llama.cpp, and LM Studio,
+        which drops chat_template_kwargs, reports that kwarg as undeliverable
+        instead of sending it. No per-level output has been measured yet, so
+        the always-on classification above stands until one is.
 
         Sampler provenance: temperature 1.0, top_p 0.95 and top_k 64 are the
         card's Best Practices values and the router preset uses the same three.
@@ -1743,7 +1744,7 @@
     gpuTiers:
       "32gb": "Agent-role target on a 32 GB card: UD-Q4_K_XL weights, q8_0 KV at ctx=131072, parallel=1, with the Q8_0 perception encoder and the DFlash drafter both resident."
     runtimePreference:
-      llamaCpp: "OpenAI-compatible chat completions with --jinja. Set the reasoning budget at launch with --chat-template-kwargs {\"reasoning_strength\": \"...\"}; there is no per-request field Clio can send for it."
+      llamaCpp: "OpenAI-compatible chat completions with --jinja. Clio drives the reasoning budget per request through chat_template_kwargs.reasoning_strength, mapped from the thinking level by thinking.chatTemplateKwargs.byLevel; a --chat-template-kwargs launch value is only the server default for requests that send none."
       openaiCompat: "Use when a gateway fronts the same llama.cpp chat-completions surface. Expect a reasoning trace on every response whatever the configured thinking level says."
     llamaCpp:
       ctxSize: 131072
@@ -1762,7 +1763,7 @@
       mechanism: always-on
       chatTemplateKwargs:
         byLevel:
-          # Card: reasoning strength low|medium|high|xhigh (scratchpad/catalog/models/unsloth-Muse-Glimmer-30B.md:35). The per-family kwarg key the note above asked for.
+          # Card: reasoning strength low|medium|high|xhigh (scratchpad/catalog/models/unsloth-Muse-Glimmer-30B.md:35). The per-family kwarg key the note above describes.
           key: reasoning_strength
           values:
             low: low
@@ -1774,9 +1775,10 @@
       guidance: |
         Muse Glimmer reasons on every turn and its strength scale has no off
         level, so Clio shows the dial as forced and budgets for a reasoning
-        preamble ahead of every answer. Change the amount of thinking at the
-        server, with the reasoning_strength chat-template kwarg; a per-request
-        thinking level cannot reach this model.
+        preamble ahead of every answer. The thinking level still sets how much
+        it thinks: on llama.cpp Clio sends reasoning_strength (low, medium,
+        high, xhigh) as a chat-template kwarg per request. LM Studio drops that
+        kwarg, so there the strength stays at the server's own default.
     serving: "Meta Superintelligence Lab Muse-Glimmer-30B, a dense 29.6B causal transformer with a ~1.8B ViT-G/14 perception encoder, interleaved local and global attention with a 2048 sliding window, and a DFlash block-diffusion drafter that proposes 16 tokens per forward pass. Card context length is 131072. Input is text plus image; the mini router additionally tags video, which the card does not claim, so the catalog follows the card."
 
 # ThinkingCap is a brevity finetune of Qwen3.6-27B and not the base model, so it

package/src/domains/providers/runtime-resolution.ts

@@ -665,14 +665,16 @@ function positiveWindow(value: number | null | undefined): number | undefined {
  *    (live model hint > knowledge base > catalog > runtime default > 8192).
  *  - `desired`: what Clio wants for coding. Local-native tiers still get a
  *    128k recommendation, but this is advisory only.
- *  - `effective`: what the target actually offers, most live source first:
- *    loaded > probe > target config override > model-specific knowledge >
- *    runtime descriptor default. Clio no longer invents a 128k effective
+ *  - `effective`: the configured target limit, capped by a known loaded window;
+ *    otherwise loaded > probe > model-specific knowledge > runtime descriptor
+ *    default. Clio no longer invents a 128k effective
  *    window for unknown local models; providers must probe it or users must
  *    configure an explicit override.
  *
- * The loaded window outranks everything below it because it is the only figure
- * that describes what the backend will serve this turn. A model whose weights
+ * A loaded window prevents configuration from overstating what the backend can
+ * serve this turn. An operator can also configure a smaller limit, including
+ * when a gateway advertises training capacity instead of serving capacity.
+ * A model whose weights
  * allow 262k but which is open at 100k fails at 100k, so planning against the
  * declared number means autocompact never fires in time.
  *
@@ -718,18 +720,18 @@ export function resolveContextWindowDetails(
 	const overrideWindow = positiveWindow(target.capabilities?.contextWindow);
 	let effective: number;
 	let source: ContextWindowSource;
-	if (loadedWindow !== undefined) {
+	if (loadedWindow !== undefined && (overrideWindow === undefined || loadedWindow <= overrideWindow)) {
 		effective = loadedWindow;
 		source = "loaded";
+	} else if (overrideWindow !== undefined) {
+		effective = overrideWindow;
+		source = "target-override";
 	} else if (probeWindow !== undefined) {
 		effective = probeWindow;
 		// Not "loaded": a probed window is what the target reported for the
 		// model, and only a runtime that names its resident instance's window
 		// has said anything about what is serving right now.
 		source = "probe";
-	} else if (overrideWindow !== undefined) {
-		effective = overrideWindow;
-		source = "target-override";
 	} else if (modelDeclared !== undefined) {
 		effective = modelDeclared;
 		source = modelDeclaredSource;

package/src/domains/providers/runtimes/claude/claude-code.ts

@@ -23,6 +23,15 @@ const claudeCodeRuntime: RuntimeDescriptor = {
 	headlessCommand: "claude -p --output-format stream-json",
 	outputParser: "claude-code-stream-json",
 	defaultCapabilities: claudeCodeCapabilities,
+	// The Claude CLI runs its own tool loop. Clio observes only the stream, so a
+	// declared per-tool budget is recorded as external-one-shot, never enforced.
+	externalAgentLoop: {
+		tools: "externally-governed-unobserved",
+		network: "externally-governed-unobserved",
+		budget: "external-one-shot",
+		generatingRetry: "allowed",
+		modelCatalog: "static",
+	},
 	synthesizeModel(target: TargetDescriptor, wireModelId: string, kb: KnowledgeBaseHit | null): Model<Api> {
 		return synthesizeClaudeDelegatedModel({
 			target,

package/src/domains/providers/runtimes/cloud/openrouter.ts

@@ -82,6 +82,7 @@ const openrouterRuntime: RuntimeDescriptor = {
 	displayName: "OpenRouter",
 	kind: "http",
 	tier: "cloud",
+	// Runtime fallback and explicit-URL contract; dispatch uses each synthesized model.api.
 	apiFamily: "openai-completions",
 	auth: "api-key",
 	credentialsEnvVar: "OPENROUTER_API_KEY",
@@ -101,6 +102,7 @@ const openrouterRuntime: RuntimeDescriptor = {
 			defaultCapabilities,
 			runtimeId: "openrouter",
 			api: "openai-completions",
+			preferCatalogTransport: true,
 			provider: "openrouter",
 			defaultBaseUrl: OPENROUTER_BASE_URL,
 			defaultHeaders: OPENROUTER_HEADERS,

package/src/domains/providers/support.ts

@@ -95,7 +95,7 @@ export function supportGroupLabel(group: ProviderSupportGroup): string {
 
 function classifyGroup(runtime: RuntimeDescriptor): ProviderSupportGroup {
 	if (runtime.id === "openai-codex") return "featured";
-	if (runtime.externalAgentLoop !== undefined) return "external-worker";
+	if (runtime.externalAgentLoop !== undefined && runtime.auth !== "claude-cli") return "external-worker";
 	if (runtime.id === "alcf") return "cloud-api";
 	if (runtime.auth === "oauth" || runtime.auth === "claude-cli") return "subscription";
 	if (catalogProviderForRuntime(runtime.id) || (runtime.auth === "api-key" && !runtime.probe)) {

package/src/domains/providers/types/runtime-descriptor.ts

@@ -171,7 +171,7 @@ export interface RuntimeDescriptor {
 		tools: "externally-governed-unobserved";
 		network: "externally-governed-unobserved";
 		budget: "external-one-shot";
-		generatingRetry: "forbidden";
+		generatingRetry: "forbidden" | "allowed";
 		modelCatalog: "live-authoritative" | "static";
 	};
 	/**

package/src/domains/resources/skills/promotion.ts

@@ -109,6 +109,8 @@ export function scorePromotionEntry(userText: string, entry: MarketplaceSkill):
 
 /**
  * The uninstalled marketplace entries that match the request, best first.
+ * Authored trigger hits precede token fallbacks, even when incidental
+ * description overlap ties or exceeds the trigger's numeric score.
  * `excludedNames` carries installed skills plus every decline scope the
  * caller tracks; the matcher itself is stateless.
  */
@@ -123,7 +125,12 @@ export function matchMarketplaceSkills(
 		const match = scorePromotionEntry(userText, entry);
 		if (match) matches.push(match);
 	}
-	return matches.sort((a, b) => b.score - a.score || a.entry.name.localeCompare(b.entry.name));
+	return matches.sort(
+		(a, b) =>
+			Number(b.matchedTrigger !== undefined) - Number(a.matchedTrigger !== undefined) ||
+			b.score - a.score ||
+			a.entry.name.localeCompare(b.entry.name),
+	);
 }
 
 /**

package/src/domains/safety/action-classifier.ts

@@ -84,6 +84,7 @@ function isUnderPrefix(abs: string, prefix: string): boolean {
 
 function baseClassify(tool: string): ActionClass | null {
 	switch (tool) {
+		case ToolNames.Evidence:
 		case ToolNames.Read:
 		case ToolNames.Grep:
 		case ToolNames.Find:
@@ -110,6 +111,12 @@ function baseClassify(tool: string): ActionClass | null {
 		// or survives the session, so it is reversible, local, and never gated
 		// behind a confirmation.
 		case ToolNames.Panes:
+		// limitation appends a typed receipt to the session ledger and touches
+		// nothing else, so it is never gated behind a confirmation.
+		case ToolNames.Limitation:
+		// decide appends the model's own design decision to the session
+		// decision board. One ledger append, no workspace effect, never gated.
+		case ToolNames.Decide:
 			return "read";
 		case ToolNames.Write:
 		case ToolNames.Edit:
@@ -203,7 +210,16 @@ function extractWritePath(tool: string, args: Record<string, unknown> | undefine
 	return tool === ToolNames.Artifact ? artifactDefaultPath(args?.kind) : null;
 }
 
+/** Shared by classification and registry exposure; an empty body still sends data. */
+export function webFetchIsOutward(args: Record<string, unknown> | undefined): boolean {
+	const method = typeof args?.method === "string" && args.method.length > 0 ? args.method.toUpperCase() : "GET";
+	return (method !== "GET" && method !== "HEAD") || args?.body !== undefined;
+}
+
 export function classify(call: ClassifierCall): Classification {
+	if (call.tool === ToolNames.WebFetch && webFetchIsOutward(call.args)) {
+		return { actionClass: "write", reasons: ["web-fetch:outward"] };
+	}
 	const base = baseClassify(call.tool);
 	if (base === null) {
 		return { actionClass: "unknown", reasons: [`unknown tool: ${call.tool}`] };

package/src/domains/safety/autonomy.ts

@@ -139,7 +139,16 @@ export function autonomyDenyRejection(level: AutonomyLevel, tool: string, action
 		detail:
 			`Clio is at autonomy ${level}: ${actionClass} actions are denied without prompting. ` +
 			"Describe the change you would make instead, so the operator can apply it or raise the autonomy level.",
-		hints: ["Propose the exact edit or command as text.", "The operator can change the level in /settings."],
+		hints: [
+			...(level === "read-only" && actionClass === "execute"
+				? [
+						"For independent permitted inspection, use the native read, grep, find, or ls tools when available. " +
+							"Do not use them to reproduce the denied execution or write; each call still follows its safety policy.",
+					]
+				: []),
+			"Propose the exact edit or command as text.",
+			"The operator can change the level in interactive /settings or start a new headless run with clio-coder run --autonomy <level>.",
+		],
 	};
 }
 

package/src/domains/safety/contract.ts

@@ -49,7 +49,11 @@ export interface SafetyContract {
 	isSubset(worker: ScopeSpec, orchestrator: ScopeSpec): boolean;
 
 	/** Immutable safety policy metadata for receipts, audit, and replay. */
-	readonly policy?: { metadata(posture?: string): SafetyPolicyMetadata };
+	readonly policy?: {
+		metadata(posture?: string): SafetyPolicyMetadata;
+		/** Pure search-result filter using the same compiled policy as admission. */
+		allowsObservationPath?(path: string): boolean;
+	};
 
 	/**
 	 * Shared audit sink. `recordCount` is for diagnostics; `recordToolCall` is

package/src/domains/safety/default-path-policy.ts

@@ -67,8 +67,10 @@ export const DEFAULT_DAMAGE_CONTROL_PATH_POLICY: PathPolicyInput = {
 		// widen its own permissions in two tool calls. Both are authored by the
 		// operator through the CLI (`clio-coder verifiers author` lands nothing
 		// before `--yes`), so model-side writes and deletes are refused.
+		// Skills also refuse model-side writes and deletes; installs go through `clio-coder skills install`.
 		".clio-coder/safety.yaml",
 		".clio-coder/verifiers.yaml",
+		".clio-coder/skills/",
 		"/etc/",
 		"/usr/",
 		"/bin/",
@@ -123,3 +125,14 @@ export function mergePathPolicyInputs(base: PathPolicyInput, override: PathPolic
 		noDeletePaths: [...(base.noDeletePaths ?? []), ...(override.noDeletePaths ?? [])],
 	};
 }
+
+/** Operator and host authority survives every project-local exemption. */
+export const OPERATOR_PATH_POLICY: PathPolicyInput = {
+	zeroAccessPaths: DEFAULT_DAMAGE_CONTROL_PATH_POLICY.zeroAccessPaths?.filter((entry) => entry.startsWith("~/")) ?? [],
+	readOnlyPaths:
+		DEFAULT_DAMAGE_CONTROL_PATH_POLICY.readOnlyPaths?.filter(
+			(entry) => entry.startsWith("~/") || entry.startsWith("/") || entry.startsWith(".clio-coder/"),
+		) ?? [],
+	noWritePaths: DEFAULT_DAMAGE_CONTROL_PATH_POLICY.noWritePaths ?? [],
+	noDeletePaths: DEFAULT_DAMAGE_CONTROL_PATH_POLICY.noDeletePaths?.filter((entry) => entry.startsWith("~/")) ?? [],
+};