@iowarp/clio-coder 0.4.2 → 0.4.4

package/src/domains/providers/target-model-cache.ts

@@ -25,6 +25,7 @@ export interface TargetModelSnapshot {
 	runtimeId: string;
 	url: string | null;
 	models: string[];
+	modelLabels?: Record<string, string>;
 	observedAt: string;
 }
 
@@ -32,6 +33,7 @@ interface TargetModelCacheOptions {
 	cacheDir?: string;
 	nowMs?: number;
 	ttlMs?: number;
+	modelLabels?: Readonly<Record<string, string>>;
 }
 
 function targetCacheKey(targetId: string): string {
@@ -55,6 +57,22 @@ function normalizedModels(models: ReadonlyArray<string>): string[] {
 	return out;
 }
 
+function normalizedLabels(models: ReadonlyArray<string>, labels: unknown): Record<string, string> | undefined {
+	if (typeof labels !== "object" || labels === null || Array.isArray(labels)) return undefined;
+	const source = labels as Record<string, unknown>;
+	const out: Record<string, string> = {};
+	for (const id of models) {
+		const label = source[id];
+		if (typeof label !== "string") continue;
+		const trimmed = label.trim();
+		if (trimmed.length === 0 || trimmed.length > TARGET_MODEL_CACHE_MAX_MODEL_ID_CHARS || /[\r\n\0]/u.test(trimmed)) {
+			continue;
+		}
+		out[id] = trimmed;
+	}
+	return Object.keys(out).length > 0 ? out : undefined;
+}
+
 function parseSnapshot(value: unknown): TargetModelSnapshot | null {
 	if (typeof value !== "object" || value === null || Array.isArray(value)) return null;
 	const row = value as Partial<TargetModelSnapshot>;
@@ -66,7 +84,7 @@ function parseSnapshot(value: unknown): TargetModelSnapshot | null {
 	if (typeof row.observedAt !== "string" || !Number.isFinite(Date.parse(row.observedAt))) return null;
 	const models = normalizedModels(row.models);
 	if (models.length !== row.models.length) return null;
-	return {
+	const snapshot: TargetModelSnapshot = {
 		version: TARGET_MODEL_CACHE_VERSION,
 		targetId: row.targetId,
 		runtimeId: row.runtimeId,
@@ -74,6 +92,9 @@ function parseSnapshot(value: unknown): TargetModelSnapshot | null {
 		models,
 		observedAt: row.observedAt,
 	};
+	const modelLabels = normalizedLabels(models, row.modelLabels);
+	if (modelLabels !== undefined) snapshot.modelLabels = modelLabels;
+	return snapshot;
 }
 
 /** Read a fresh snapshot only when it still describes this target identity. */
@@ -102,7 +123,7 @@ export function readTargetModelSnapshot(
 export function recordTargetModelSnapshot(
 	target: Pick<TargetDescriptor, "id" | "runtime" | "url">,
 	models: ReadonlyArray<string>,
-	options: Pick<TargetModelCacheOptions, "cacheDir" | "nowMs"> = {},
+	options: Pick<TargetModelCacheOptions, "cacheDir" | "nowMs" | "modelLabels"> = {},
 ): boolean {
 	if (target.id.length === 0 || target.runtime.length === 0) return false;
 	const snapshot: TargetModelSnapshot = {
@@ -113,6 +134,8 @@ export function recordTargetModelSnapshot(
 		models: normalizedModels(models),
 		observedAt: new Date(options.nowMs ?? Date.now()).toISOString(),
 	};
+	const modelLabels = normalizedLabels(snapshot.models, options.modelLabels);
+	if (modelLabels !== undefined) snapshot.modelLabels = modelLabels;
 	try {
 		safeResourceWrite(targetModelSnapshotPath(target.id, options.cacheDir), `${JSON.stringify(snapshot, null, 2)}\n`, {
 			encoding: "utf8",

package/src/domains/providers/types/capability-flags.ts

@@ -20,6 +20,8 @@ export interface CapabilityFlags {
 	toolCallFormat?: ToolCallFormat;
 	reasoning: boolean;
 	thinkingFormat?: ThinkingFormat;
+	/** Probe-declared upstream control dialect only; never changes gateway routing or residency. */
+	thinkingControlRuntime?: "lmstudio" | "llamacpp";
 	structuredOutputs?: StructuredOutputMode;
 	vision: boolean;
 	audio: boolean;

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

@@ -22,7 +22,8 @@ export type RuntimeApiFamily =
 	| "rerank-http"
 	| "embeddings-http"
 	| "claude-agent-sdk"
-	| "claude-code-subprocess";
+	| "claude-code-subprocess"
+	| "external-agent-subprocess";
 
 export type RuntimeAuth = "api-key" | "oauth" | "aws-sdk" | "vertex-adc" | "claude-cli" | "none";
 
@@ -93,8 +94,14 @@ export interface ProbeResult {
 	ok: boolean;
 	latencyMs?: number;
 	error?: string;
+	/** Set when `error` is specifically the server rejecting the credential, not a reachability failure. */
+	authFailed?: boolean;
 	serverVersion?: string;
 	models?: string[];
+	/** Human-readable labels keyed by the exact wire id returned in `models`. */
+	modelLabels?: Record<string, string>;
+	/** Stable cause class for setup UX; `error` remains the redacted human diagnostic. */
+	failureKind?: "missing" | "authentication" | "unsupported-feature" | "catalog-unavailable" | "cancelled" | "generic";
 	/** Probe-only per-model load state when the runtime exposes it. */
 	modelStates?: Record<string, ProbeModelStatus>;
 	discoveredCapabilities?: Partial<CapabilityFlags>;
@@ -155,6 +162,18 @@ export interface RuntimeDescriptor {
 	headlessCommand?: string;
 	outputParser?: string;
 	defaultCapabilities: CapabilityFlags;
+	/**
+	 * Declares a black-box agent loop owned by an external executable. `tools`
+	 * in CapabilityFlags stays false because Clio neither sends nor observes
+	 * typed calls on this path; this field records the distinct external fact.
+	 */
+	externalAgentLoop?: {
+		tools: "externally-governed-unobserved";
+		network: "externally-governed-unobserved";
+		budget: "external-one-shot";
+		generatingRetry: "forbidden" | "allowed";
+		modelCatalog: "live-authoritative" | "static";
+	};
 	/**
 	 * When true, this id is a real, distinct runtime (e.g. `llamacpp-anthropic`,
 	 * the Anthropic Messages surface on llama.cpp, or the embed/rerank runtimes)

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

@@ -39,6 +39,24 @@ export interface LmStudioTargetSettings {
 	request?: LmStudioRequestSettings;
 }
 
+/** Per-request controls understood by a LiteLLM proxy. Values are optional so server policy remains authoritative by default. */
+export interface LiteLLMRequestSettings {
+	/** Extra LiteLLM request tags. Clio always adds `clio-coder`. */
+	tags?: string[];
+	/** Forward Clio's stable session id as `x-litellm-session-id`. Defaults to true. */
+	sendSessionId?: boolean;
+	/** Override the proxy/upstream request timeout through `x-litellm-timeout`. */
+	timeoutSeconds?: number;
+	/** Override LiteLLM's streamed-response timeout through `x-litellm-stream-timeout`. */
+	streamTimeoutSeconds?: number;
+	/** Override LiteLLM router retries for this request; this does not enable client-side SDK retries. */
+	numRetries?: number;
+}
+
+export interface LiteLLMTargetSettings {
+	request?: LiteLLMRequestSettings;
+}
+
 /**
  * Persisted target specification from settings.yaml (`targets:`). It binds a
  * user-facing target id to a RuntimeDescriptor id, target URL/auth metadata,
@@ -57,6 +75,7 @@ export interface TargetDescriptor {
 	gateway?: boolean;
 	pricing?: TargetPricing;
 	lmstudio?: LmStudioTargetSettings;
+	litellm?: LiteLLMTargetSettings;
 	/** Explicit request-slot limit for this inference endpoint. It overrides live discovery. */
 	maxConcurrentRequests?: number;
 }

package/src/domains/resources/index.ts

@@ -67,6 +67,7 @@ export {
 	modelVisibleSkills,
 	parsePendingSkillRequests,
 	parseSkillCommand,
+	SKILL_SURFACE_CLEAR_ARG,
 	type Skill,
 	type SkillCatalogInvalidReason,
 	type SkillCatalogValidity,
@@ -89,6 +90,8 @@ export {
 	type MarketplaceSkill,
 	type MarketplaceSkillOrigin,
 	type MarketplaceStatus,
+	marketplaceInstallShaping,
+	resolveMarketplaceShaping,
 } from "./skills/marketplace.js";
 export {
 	checkSkillDrift,

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

@@ -40,6 +40,20 @@ export interface InstallSkillInput {
 	force?: boolean;
 	/** Override the Clio config dir used for the user root (testing). */
 	configDir?: string;
+	/**
+	 * Absolute path of a local directory whose files are copied over the fetched
+	 * source before the install lands. Its SKILL.md becomes the installed skill
+	 * text, so the provenance stamps and the pinned hash describe the overlay.
+	 */
+	overlay?: string;
+	/** Top-level names dropped from the fetched source before the overlay is applied. */
+	exclude?: string[];
+}
+
+/** The overlay and exclude list a marketplace entry attaches to a source URL. */
+export interface SkillInstallShaping {
+	overlay?: string;
+	exclude?: string[];
 }
 
 export interface InstallSkillResult {
@@ -68,6 +82,12 @@ export interface UpdateSkillsInput {
 	all?: boolean;
 	/** Overwrite local modifications. */
 	force?: boolean;
+	/**
+	 * Recovers the overlay and exclude list an installed skill was shaped with,
+	 * keyed by its name and recorded source URL. Without it an update of a
+	 * remote-entry skill would refetch bare upstream and drop the wrapper.
+	 */
+	resolveShaping?: (skill: { name: string; sourceUrl: string }) => SkillInstallShaping | undefined;
 }
 
 /**
@@ -252,17 +272,51 @@ function fetchSource(spec: SkillSourceSpec): FetchedSource {
 	}
 }
 
-function copySkillDir(from: string, to: string): void {
+function copySkillDir(from: string, to: string, exclude: ReadonlyArray<string> = []): void {
 	mkdirSync(path.dirname(to), { recursive: true });
+	const excluded = new Set(exclude);
 	cpSync(from, to, {
 		recursive: true,
 		filter: (source) => {
 			const base = path.basename(source);
-			return base !== ".git" && base !== "node_modules";
+			if (base === ".git" || base === "node_modules") return false;
+			// `exclude` names top-level members only, so a nested `test/` inside
+			// a renderer stays where the upstream package put it.
+			return !(excluded.size > 0 && path.dirname(source) === from && excluded.has(base));
 		},
 	});
 }
 
+/**
+ * Shape a fetched source the way a marketplace remote entry asks: drop the
+ * excluded top-level members, then lay the overlay's files on top. The result
+ * is a fresh temporary tree so the fetched source (which may be an operator's
+ * own local directory) is never modified, and validation runs against what
+ * will actually be installed.
+ */
+function shapeSource(fetched: FetchedSource, shaping: SkillInstallShaping): FetchedSource {
+	const exclude = shaping.exclude ?? [];
+	if (!shaping.overlay && exclude.length === 0) return fetched;
+	if (shaping.overlay && !existsSync(shaping.overlay)) {
+		fetched.cleanup();
+		throw new Error(`skill overlay directory does not exist: ${shaping.overlay}`);
+	}
+	const tmp = mkdtempSync(path.join(tmpdir(), "clio-coder-skill-shape-"));
+	const shaped = path.join(tmp, "skill");
+	const cleanup = (): void => {
+		rmSync(tmp, { recursive: true, force: true });
+		fetched.cleanup();
+	};
+	try {
+		copySkillDir(fetched.skillDir, shaped, exclude);
+		if (shaping.overlay) copySkillDir(shaping.overlay, shaped);
+		return { skillDir: resolveSkillDir(shaped), cleanup };
+	} catch (err) {
+		cleanup();
+		throw err instanceof Error ? err : new Error(String(err));
+	}
+}
+
 let skillSwapSequence = 0;
 
 /**
@@ -328,7 +382,7 @@ export function installSkillFromSource(input: InstallSkillInput): InstallSkillRe
 	const cwd = input.cwd ?? process.cwd();
 	const scope = input.scope ?? "project";
 
-	const fetched = fetchSource(spec);
+	const fetched = shapeSource(fetchSource(spec), input);
 	try {
 		const { skill, warnings } = validateSourceSkill(fetched.skillDir);
 		const name = (input.name ?? skill.name).trim();
@@ -385,13 +439,18 @@ function managedSkills(cwd: string, configDir?: string): Skill[] {
 	);
 }
 
-function updateOne(skill: Skill, force: boolean): SkillUpdateReport {
+function updateOne(skill: Skill, force: boolean, shaping: SkillInstallShaping = {}): SkillUpdateReport {
 	const sourceUrl = skill.provenance?.installUrl;
 	if (!sourceUrl) return { name: skill.name, status: "no-source", detail: "no source-url provenance recorded" };
 	const spec = parseSkillSourceSpec(sourceUrl);
 	if (!spec) return { name: skill.name, status: "error", detail: `unsupported source-url: ${sourceUrl}` };
 
-	const fetched = fetchSource(spec);
+	let fetched: FetchedSource;
+	try {
+		fetched = shapeSource(fetchSource(spec), shaping);
+	} catch (err) {
+		return { name: skill.name, status: "error", detail: err instanceof Error ? err.message : String(err) };
+	}
 	try {
 		// The same gate a fresh install passes. Upstream may have moved on to a
 		// SKILL.md that no longer loads, and without this an update replaces a
@@ -441,11 +500,17 @@ function updateOne(skill: Skill, force: boolean): SkillUpdateReport {
 export function updateSkills(input: UpdateSkillsInput = {}): SkillUpdateReport[] {
 	const cwd = input.cwd ?? process.cwd();
 	const skills = managedSkills(cwd, input.configDir);
+	const shapingFor = (skill: Skill): SkillInstallShaping =>
+		(skill.provenance?.installUrl &&
+			input.resolveShaping?.({ name: skill.name, sourceUrl: skill.provenance.installUrl })) ||
+		{};
 	if (input.name) {
 		const skill = skills.find((entry) => entry.name === input.name);
 		if (!skill) return [{ name: input.name, status: "error", detail: "not found in Clio-managed skill roots" }];
-		return [updateOne(skill, input.force === true)];
+		return [updateOne(skill, input.force === true, shapingFor(skill))];
 	}
 	if (input.all !== true) throw new Error("updateSkills requires a name or all=true");
-	return skills.filter((skill) => skill.provenance?.installUrl).map((skill) => updateOne(skill, input.force === true));
+	return skills
+		.filter((skill) => skill.provenance?.installUrl)
+		.map((skill) => updateOne(skill, input.force === true, shapingFor(skill)));
 }

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

@@ -949,6 +949,13 @@ export function skillCatalogValidity(list: SkillList): SkillCatalogValidity {
 	return { ok: true, reason: null };
 }
 
+/**
+ * The one argument `/skill` reserves for itself: `/skill off` clears the tool
+ * surface an activated skill armed for the session instead of loading a skill
+ * by that name.
+ */
+export const SKILL_SURFACE_CLEAR_ARG = "off";
+
 export function parseSkillCommand(input: string): { name: string; args: string } | null {
 	const trimmed = input.trim();
 	if (!trimmed.startsWith("/skill ")) return null;

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

@@ -9,6 +9,7 @@ import {
 	installSkillFromSource,
 	isSkillName,
 	parseSkillSourceSpec,
+	type SkillInstallShaping,
 } from "./install.js";
 import { loadSkills, type Skill } from "./loader.js";
 
@@ -60,6 +61,14 @@ export interface MarketplaceSkill {
 	triggers?: string[];
 	origin: MarketplaceSkillOrigin;
 	requires?: LibraryRequirementRef[];
+	/**
+	 * Remote entry: a package-root-relative directory whose files are copied
+	 * over the fetched upstream tree at install. Clio owns only the overlay
+	 * (typically a wrapper SKILL.md); the upstream renderer is never vendored.
+	 */
+	overlay?: string;
+	/** Remote entry: top-level upstream members dropped at install. */
+	exclude?: string[];
 }
 
 export type MarketplaceStatus = "installed" | "installable" | "unavailable";
@@ -181,6 +190,12 @@ function parseMarketplaceIndex(indexPath: string, diagnostics: string[] = []): M
 			const requires = Array.isArray(record.requires)
 				? record.requires.filter((entry): entry is LibraryRequirementRef => typeof entry === "string")
 				: undefined;
+			const overlay = optionalString(record.overlay);
+			if (overlay && (path.isAbsolute(overlay) || overlay.split("/").includes(".."))) {
+				diagnostics.push(`skill marketplace index entry has an overlay outside the package: ${skill.name}`);
+				return [];
+			}
+			const exclude = optionalTriggerList(record.exclude);
 			return [
 				{
 					kind,
@@ -192,6 +207,8 @@ function parseMarketplaceIndex(indexPath: string, diagnostics: string[] = []): M
 					...(category ? { category } : {}),
 					...(triggers ? { triggers } : {}),
 					...(requires ? { requires } : {}),
+					...(overlay ? { overlay } : {}),
+					...(exclude ? { exclude } : {}),
 					origin: "index" as const,
 				},
 			];
@@ -284,25 +301,32 @@ export function discoverMarketplaceSkills(options: DiscoverMarketplaceOptions =
 	const skills: MarketplaceSkill[] = [];
 	const seen = new Set<string>();
 
+	const indexPath =
+		options.indexPath === null ? null : (options.indexPath ?? process.env.CLIO_CODER_SKILL_MARKETPLACE_INDEX ?? null);
+	const resolvedIndexPath = indexPath ?? defaultIndexPath();
+	const indexSkills =
+		options.indexPath !== null && resolvedIndexPath && existsSync(resolvedIndexPath)
+			? parseMarketplaceIndex(resolvedIndexPath, diagnostics)
+			: [];
+	// A remote entry's overlay folder is also a catalog package on disk, but
+	// installing that folder alone would land the wrapper without the upstream
+	// it wraps. The index entry that names the overlay is the whole skill.
+	const overlayNames = new Set(indexSkills.filter((skill) => skill.overlay).map((skill) => skill.name));
+
 	// Catalog packages first: real local files beat index pointers on name collisions.
 	const catalogDir = resolveCatalogDir(options);
 	if (catalogDir) {
 		for (const skill of catalogSkills(catalogDir, diagnostics)) {
-			if (seen.has(skill.name)) continue;
+			if (seen.has(skill.name) || overlayNames.has(skill.name)) continue;
 			seen.add(skill.name);
 			skills.push(skill);
 		}
 	}
 
-	const indexPath =
-		options.indexPath === null ? null : (options.indexPath ?? process.env.CLIO_CODER_SKILL_MARKETPLACE_INDEX ?? null);
-	const resolvedIndexPath = indexPath ?? defaultIndexPath();
-	if (options.indexPath !== null && resolvedIndexPath && existsSync(resolvedIndexPath)) {
-		for (const skill of parseMarketplaceIndex(resolvedIndexPath, diagnostics)) {
-			if (seen.has(skill.name)) continue;
-			seen.add(skill.name);
-			skills.push(skill);
-		}
+	for (const skill of indexSkills) {
+		if (seen.has(skill.name)) continue;
+		seen.add(skill.name);
+		skills.push(skill);
 	}
 
 	if (skills.length === 0 && diagnostics.length === 0) {
@@ -315,6 +339,34 @@ export function getMarketplaceSkills(options: DiscoverMarketplaceOptions = {}):
 	return discoverMarketplaceSkills(options).skills;
 }
 
+/**
+ * The install shaping a marketplace entry carries, with its overlay resolved
+ * to an absolute directory under the package root. An entry with neither
+ * field shapes nothing, so the caller can spread the result unconditionally.
+ */
+export function marketplaceInstallShaping(skill: MarketplaceSkill): SkillInstallShaping {
+	const shaping: SkillInstallShaping = {};
+	if (skill.overlay) shaping.overlay = path.join(resolvePackageRoot(), skill.overlay);
+	if (skill.exclude && skill.exclude.length > 0) shaping.exclude = [...skill.exclude];
+	return shaping;
+}
+
+/**
+ * Recover the shaping for an installed skill by name and recorded source URL,
+ * for `updateSkills`. Only a marketplace entry that still points at the same
+ * upstream URL applies; a skill installed from a URL the index no longer
+ * carries updates bare, as it was installed.
+ */
+export function resolveMarketplaceShaping(options: DiscoverMarketplaceOptions = {}) {
+	return (installed: { name: string; sourceUrl: string }): SkillInstallShaping | undefined => {
+		const entry = getMarketplaceSkills(options).find(
+			(skill) => skill.name === installed.name && skill.sourceUrl === installed.sourceUrl,
+		);
+		if (!entry || (!entry.overlay && !entry.exclude)) return undefined;
+		return marketplaceInstallShaping(entry);
+	};
+}
+
 /**
  * The single install entry point for every frontend (headless CLI, TUI
  * pending-skill prompt, skills hub). Source resolution, in precedence order:
@@ -339,7 +391,7 @@ export function installSkill(input: InstallSkillInput): InstallSkillResult {
 		if (!skill) {
 			throw new Error(`"${source}" is neither an existing local path nor available in the local marketplace`);
 		}
-		return installSkillFromSource({ ...input, source: skill.sourceUrl });
+		return installSkillFromSource({ ...input, ...marketplaceInstallShaping(skill), source: skill.sourceUrl });
 	}
 	return installSkillFromSource({ ...input, source });
 }

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:

package/src/domains/safety/autonomy.ts

@@ -68,6 +68,21 @@ export interface AutonomyMappingOptions {
 	exposure?: AutonomyExposure;
 }
 
+/**
+ * Whether the model may activate an installed skill itself rather than
+ * emitting the suggestion anchor and waiting for the operator to type
+ * `/skill <name>`.
+ *
+ * At `read-only` and `suggest` the operator asked to be consulted before the
+ * agent acts, and activation is an action. At `auto-edit` and `full-auto` they
+ * already said otherwise, and a skill can only narrow the tool surface, never
+ * widen it, so the gate buys no safety there. The level is the opt-in; there is
+ * no per-skill frontmatter flag for this.
+ */
+export function modelMayActivateSkills(level: AutonomyLevel): boolean {
+	return level === "auto-edit" || level === "full-auto";
+}
+
 /**
  * The §2.3 level-dependent matrix. `git_destructive` never reaches this
  * mapping in practice (the safety net blocks it first); it maps to deny

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/",

package/src/domains/safety/finish-contract-registration.ts

@@ -4,16 +4,22 @@
  * The chat-loop fires `turn_end` with the final assistant text and this
  * registration emits an advisory `inject_reminder` (severity "warn") when the
  * turn mutated workspace state but recorded no validation evidence and no
- * explicit limitation. The trigger is the observed mutation, not the wording of
- * the assistant's text. The chat-loop's generic effect application renders the
+ * `limitation` receipt. The trigger is the observed mutation, not the wording
+ * of the assistant's text, and the text never enters the assessment. The chat-loop's generic effect application renders the
  * notice, persists the session entry, and flushes the reminder into the next
  * model request. Every decision is also written to the audit ledger.
  */
 
 import { VERIFICATION_SCRIPT_FAMILY_HINT } from "../../core/verification-scripts.js";
 import type { MiddlewareEffect, MiddlewareHookInput, MiddlewareHookRegistration } from "../middleware/index.js";
+import type { UserTaskAcceptance } from "../user-tasks/acceptance.js";
 import type { CompletionContractAuditInput } from "./audit.js";
-import { assessFinishContract, type FinishContractAssessment } from "./finish-contract.js";
+import {
+	assessFinishContract,
+	DEFAULT_RECENT_ENTRY_LIMIT,
+	type FinishContractAssessment,
+	recentEntries,
+} from "./finish-contract.js";
 import type { Rigor } from "./rigor.js";
 
 export const FINISH_CONTRACT_REGISTRATION_ID = "assessor.finish-contract";
@@ -21,15 +27,15 @@ export const FINISH_CONTRACT_REGISTRATION_ID = "assessor.finish-contract";
 /**
  * High-rigor re-prompt directive. Injected dynamically via effects (never added
  * to the static system prompt) so the prompt prefix stays byte-stable. It tells
- * the model to validate with a verification-family command or to state what
- * could not be verified before claiming done. The command hint mirrors the
+ * the model to validate with a verification-family command or to record a
+ * `limitation` receipt before claiming done. The command hint mirrors the
  * vocabulary `detectValidationCommand` and `isVerificationScriptName` accept.
  */
 export const HIGH_RIGOR_REVALIDATION_MESSAGE =
 	`[Clio Coder] high-rigor finish gate: this completion claim has no validation evidence. ` +
 	`Before claiming done, run a verification command (the ${VERIFICATION_SCRIPT_FAMILY_HINT} family, ` +
-	`e.g. "npm run test", "npm run lint", "npm run build") or explicitly state what could not be verified ` +
-	`and why. Do not end the turn until you have validated or recorded the limitation.`;
+	`e.g. "npm run test", "npm run lint", "npm run build") or call the limitation tool with the scope ` +
+	`and reason of what could not be verified. Do not end the turn until you have validated or recorded the limitation.`;
 
 export interface CreateFinishContractRegistrationOptions {
 	/**
@@ -45,6 +51,7 @@ export interface CreateFinishContractRegistrationOptions {
 	 * limitation instead of merely warning.
 	 */
 	resolveRigor?: () => Rigor;
+	readActiveAcceptance?: (window: ReadonlyArray<unknown>) => UserTaskAcceptance | undefined;
 	/**
 	 * Record the contract's decision to the audit ledger. Optional; when wired
 	 * (production passes the safety audit sink), every turn_end decision — each
@@ -59,7 +66,7 @@ export function createFinishContractRegistration(
 ): MiddlewareHookRegistration {
 	return {
 		id: FINISH_CONTRACT_REGISTRATION_ID,
-		description: "advise when a turn mutated files without validation evidence or an explicit limitation",
+		description: "advise when a turn mutated files without validation evidence or a limitation receipt",
 		hooks: ["turn_end"],
 		evaluate(input: MiddlewareHookInput, context): ReadonlyArray<MiddlewareEffect> {
 			if (input.hook !== "turn_end") return [];
@@ -70,8 +77,9 @@ export function createFinishContractRegistration(
 			// finalAssistantStopMessage.
 			const stopReason = input.metadata?.stopReason;
 			if (stopReason !== undefined && stopReason !== "stop") return [];
-			const assistantText = input.text?.trim() ?? "";
-			if (assistantText.length === 0) return [];
+			// An empty final text is not a completion claim. The assessor reads
+			// only ledger receipts, so the text is otherwise unused here.
+			if ((input.text?.trim() ?? "").length === 0) return [];
 			let entries: ReadonlyArray<unknown> | null;
 			try {
 				entries = options.readSessionEntries();
@@ -79,21 +87,28 @@ export function createFinishContractRegistration(
 				return [];
 			}
 			if (entries === null) return [];
+			const rigor = options.resolveRigor?.() ?? "normal";
+			const activeAcceptance =
+				rigor === "high"
+					? options.readActiveAcceptance?.(recentEntries(entries, input.turnId ?? null, DEFAULT_RECENT_ENTRY_LIMIT))
+					: undefined;
 			const assessment = assessFinishContract({
-				assistantText,
 				sessionEntries: entries,
+				workspaceRoot: process.cwd(),
+				rigor,
+				...(activeAcceptance ? { activeAcceptance } : {}),
 				assistantTurnId: input.turnId ?? null,
 			});
-			const rigor = options.resolveRigor?.() ?? "normal";
 			recordDecision(options, input.turnId ?? null, assessment, rigor);
 			if (assessment.kind !== "engage") return [];
 			if (rigor === "high") {
 				// Withhold the completion and force a re-prompt: a continuation
 				// request carries the turn onward, and the paired reminder gives
 				// the directive its own visible system-reminder line.
+				const message = activeAcceptance?.verification.length ? assessment.message : HIGH_RIGOR_REVALIDATION_MESSAGE;
 				return [
-					{ kind: "request_continuation", message: HIGH_RIGOR_REVALIDATION_MESSAGE },
-					{ kind: "inject_reminder", message: HIGH_RIGOR_REVALIDATION_MESSAGE, severity: "warn" },
+					{ kind: "request_continuation", message },
+					{ kind: "inject_reminder", message, severity: "warn" },
 				];
 			}
 			return [{ kind: "inject_reminder", message: assessment.message, severity: "warn" }];