@iowarp/clio-coder 0.4.1 → 0.4.3

package/src/core/config.ts

@@ -525,6 +525,57 @@ function validateLmStudioSettings(
 	return Object.keys(out).length > 0 ? out : undefined;
 }
 
+function validateLiteLLMSettings(
+	issues: Issues,
+	path: string,
+	value: unknown,
+): ClioSettings["targets"][number]["litellm"] | undefined {
+	if (!isPlainObject(value)) {
+		issues.add(path, `expected a map, got ${describe(value)}`);
+		return undefined;
+	}
+	issues.unknownKeys(path, value, ["request"]);
+	const out: NonNullable<ClioSettings["targets"][number]["litellm"]> = {};
+	if ("request" in value) {
+		if (!isPlainObject(value.request)) {
+			issues.add(`${path}.request`, `expected a map, got ${describe(value.request)}`);
+		} else {
+			issues.unknownKeys(`${path}.request`, value.request, [
+				"tags",
+				"sendSessionId",
+				"timeoutSeconds",
+				"streamTimeoutSeconds",
+				"numRetries",
+			]);
+			const request: NonNullable<typeof out.request> = {};
+			if ("tags" in value.request) {
+				const parsed = expectStringArray(issues, `${path}.request.tags`, value.request.tags);
+				if (parsed !== undefined) {
+					const invalidTag = parsed.find((tag) => tag.includes(","));
+					if (invalidTag) issues.add(`${path}.request.tags`, "tags may not contain commas");
+					else if (parsed.length > 0) request.tags = [...new Set(parsed)];
+				}
+			}
+			if ("sendSessionId" in value.request) {
+				const parsed = expectBoolean(issues, `${path}.request.sendSessionId`, value.request.sendSessionId);
+				if (parsed !== undefined) request.sendSessionId = parsed;
+			}
+			for (const key of ["timeoutSeconds", "streamTimeoutSeconds"] as const) {
+				if (key in value.request) {
+					const parsed = expectNumber(issues, `${path}.request.${key}`, value.request[key], { min: 0.001, max: 86_400 });
+					if (parsed !== undefined) request[key] = parsed;
+				}
+			}
+			if ("numRetries" in value.request) {
+				const parsed = expectInteger(issues, `${path}.request.numRetries`, value.request.numRetries, { min: 0, max: 100 });
+				if (parsed !== undefined) request.numRetries = parsed;
+			}
+			if (Object.keys(request).length > 0) out.request = request;
+		}
+	}
+	return Object.keys(out).length > 0 ? out : undefined;
+}
+
 function validateTarget(issues: Issues, path: string, value: unknown): ClioSettings["targets"][number] | null {
 	if (!isPlainObject(value)) {
 		issues.add(path, `expected a map, got ${describe(value)}`);
@@ -542,6 +593,7 @@ function validateTarget(issues: Issues, path: string, value: unknown): ClioSetti
 		"gateway",
 		"pricing",
 		"lmstudio",
+		"litellm",
 		"maxConcurrentRequests",
 	]);
 	const id = "id" in value ? expectString(issues, `${path}.id`, value.id) : undefined;
@@ -593,6 +645,10 @@ function validateTarget(issues: Issues, path: string, value: unknown): ClioSetti
 		const v = validateLmStudioSettings(issues, `${path}.lmstudio`, value.lmstudio);
 		if (v !== undefined) target.lmstudio = v;
 	}
+	if ("litellm" in value) {
+		const v = validateLiteLLMSettings(issues, `${path}.litellm`, value.litellm);
+		if (v !== undefined) target.litellm = v;
+	}
 	if ("maxConcurrentRequests" in value) {
 		const v = expectInteger(issues, `${path}.maxConcurrentRequests`, value.maxConcurrentRequests, { min: 1 });
 		if (v !== undefined) target.maxConcurrentRequests = v;
@@ -1486,7 +1542,11 @@ export function validateSettings(raw: unknown): SettingsValidationResult {
 		if (!isPlainObject(raw.context)) issues.add("context", `expected a map, got ${describe(raw.context)}`);
 		else {
 			const context = raw.context;
-			issues.unknownKeys("context", context, ["workingSet", "compaction", "memory"]);
+			issues.unknownKeys("context", context, ["toolResultMaxBytes", "workingSet", "compaction", "memory"]);
+			if ("toolResultMaxBytes" in context) {
+				const parsed = expectInteger(issues, "context.toolResultMaxBytes", context.toolResultMaxBytes, { min: 4096 });
+				if (parsed !== undefined) settings.context.toolResultMaxBytes = parsed;
+			}
 			if ("workingSet" in context) {
 				if (!isPlainObject(context.workingSet))
 					issues.add("context.workingSet", `expected a map, got ${describe(context.workingSet)}`);

package/src/core/defaults.ts

@@ -412,6 +412,7 @@ export interface MemorySettings {
 }
 
 export interface ContextSettings {
+	toolResultMaxBytes: number;
 	workingSet: WorkingSetSettings;
 	compaction: DurableCompactionSettings;
 	memory: MemorySettings;
@@ -447,13 +448,13 @@ export const DEFAULT_SETTINGS = {
 	chat: {
 		target: null as string | null,
 		model: null as string | null,
-		thinkingLevel: "off" as ThinkingLevel,
+		thinkingLevel: "low" as ThinkingLevel,
 		modelPicker: {
 			cycleSet: [] as string[],
 			favorites: [] as string[],
 			recentLimit: 12,
 		} as ModelSelectorSettings,
-		maxOutputTokens: 32768,
+		maxOutputTokens: 0,
 		prewarm: true,
 		retry: {
 			enabled: true,
@@ -491,6 +492,7 @@ export const DEFAULT_SETTINGS = {
 		history: { maxRuns: GUARDRAIL_DEFAULTS.maxDispatchRuns, journal: true },
 	} as FleetSettings,
 	context: {
+		toolResultMaxBytes: 65536,
 		workingSet: DEFAULT_WORKING_SET_SETTINGS,
 		compaction: {
 			auto: true,
@@ -582,12 +584,12 @@ targets: []
 chat:
   target: null
   model: null
-  thinkingLevel: off
+  thinkingLevel: low
   modelPicker:
     cycleSet: []
     favorites: []
     recentLimit: 12
-  maxOutputTokens: 32768
+  maxOutputTokens: 0
   prewarm: true
   retry:
     enabled: true
@@ -626,6 +628,7 @@ fleet:
     journal: true
 
 context:
+  toolResultMaxBytes: 65536
   workingSet:
     enabled: true
     policy: structural-v1

package/src/core/dispatch-outcome.ts

@@ -0,0 +1,16 @@
+/**
+ * Shared mapping from a `DispatchFailed` payload's `reason` field to the
+ * terminal status it implies. Both the observability projection's run
+ * summary (src/domains/observability/projection.ts) and the interactive
+ * dispatch board (src/interactive/dispatch-board.ts) derive a run's status
+ * from the same DispatchCompleted/DispatchFailed bus events; before this
+ * module existed they each carried their own copy of this exact mapping,
+ * kept in sync only by a comment asking the next editor to remember to.
+ */
+export type DispatchFailureStatus = "dead" | "aborted" | "failed";
+
+export function resolveDispatchFailureStatus(reason: unknown): DispatchFailureStatus {
+	if (reason === "dead" || reason === "stalled") return "dead";
+	if (reason === "interrupted" || reason === "canceled") return "aborted";
+	return "failed";
+}

package/src/core/external-diagnostic.ts

@@ -0,0 +1,44 @@
+const REDACTED = "[redacted]";
+
+/**
+ * Sanitize free-form text received from an external process before it crosses
+ * into errors, receipts, transcripts, evidence, or model-catalog snapshots.
+ */
+function redactExternalDiagnostic(input: string): string {
+	return input
+		.replace(/\b(?:authorization|proxy-authorization)\s*:\s*[^\r\n]+/giu, `Authorization: ${REDACTED}`)
+		.replace(/\b(?:set-cookie|cookie)\s*:\s*[^\r\n]+/giu, `Cookie: ${REDACTED}`)
+		.replace(/\bbearer\s+[A-Za-z0-9._~+/-]+=*/giu, `Bearer ${REDACTED}`)
+		.replace(
+			/\b(?:api[_-]?key|access[_-]?token|refresh[_-]?token|token|secret|password)\s*[:=]\s*[^\s,;]+/giu,
+			(match) => {
+				const separator = match.includes(":") ? ":" : "=";
+				return `${match.slice(0, match.indexOf(separator)).trim()}${separator}${REDACTED}`;
+			},
+		)
+		.replace(/\beyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\b/gu, REDACTED)
+		.replace(
+			/(?:~|\/[A-Za-z0-9._-]+(?:\/[A-Za-z0-9._-]+)*)\/\.(?:gemini\/antigravity-cli|antigravitycli)(?:\/[^\s]*)?/gu,
+			"[redacted credential path]",
+		)
+		.replace(/https?:\/\/[^\s"'<>]+/giu, (url) => {
+			try {
+				const parsed = new URL(url);
+				if (/(?:auth|oauth|login|signin|callback)/iu.test(parsed.pathname)) return "[redacted authorization URL]";
+				parsed.username = "";
+				parsed.password = "";
+				parsed.search = "";
+				parsed.hash = "";
+				return parsed.toString();
+			} catch {
+				return REDACTED;
+			}
+		});
+}
+
+export function boundedExternalDiagnostic(input: string, maxBytes = 8192): string {
+	const redacted = redactExternalDiagnostic(input).trim();
+	const bytes = Buffer.from(redacted, "utf8");
+	if (bytes.byteLength <= maxBytes) return redacted;
+	return `${bytes.subarray(0, Math.max(0, maxBytes - 32)).toString("utf8")}\n[diagnostic truncated]`;
+}

package/src/core/gateway-routing.ts

@@ -0,0 +1,157 @@
+/**
+ * Durable routing facts reported by an AI gateway for one upstream response.
+ *
+ * The gateway is authoritative for the physical deployment that served an
+ * alias. Clio deliberately records only the host portion of an upstream API
+ * base: LiteLLM deployments may embed paths, query credentials, or user-info
+ * in the configured URL, none of which belongs in a session or sealed receipt.
+ */
+export interface LiteLLMGatewayRoutingObservation {
+	gateway: "litellm";
+	callId?: string;
+	modelGroup?: string;
+	modelName?: string;
+	apiBaseHost?: string;
+	deploymentId?: string;
+	attemptedFallbacks?: number;
+	attemptedRetries?: number;
+	overheadMs?: number;
+	responseDurationMs?: number;
+	version?: string;
+}
+
+export type GatewayRoutingObservation = LiteLLMGatewayRoutingObservation;
+
+/**
+ * Preserve the provider's diagnostic while making Clio's failure policy
+ * explicit and actionable. LiteLLM targets deliberately do not enter Clio's
+ * transient retry ladder: a named route is an operator choice, not permission
+ * to substitute another model behind their back.
+ */
+export function liteLLMRouteFailureMessage(
+	errorMessage: string | null | undefined,
+	targetId: string,
+	modelId: string,
+): string {
+	const providerMessage = errorMessage?.trim() || "LiteLLM request failed.";
+	const advice =
+		`LiteLLM route '${modelId}' on target '${targetId}' failed. ` +
+		"Clio did not retry or substitute another model; select a different route with /model, then resend.";
+	return providerMessage.includes(advice) ? providerMessage : `${providerMessage}\n\n${advice}`;
+}
+
+interface HeaderReader {
+	get(name: string): string | null;
+}
+
+function nonEmptyString(value: unknown): string | undefined {
+	return typeof value === "string" && value.trim().length > 0 ? value.trim() : undefined;
+}
+
+function nonnegativeNumber(value: unknown): number | undefined {
+	if (typeof value === "number" && Number.isFinite(value) && value >= 0) return value;
+	if (typeof value !== "string" || value.trim().length === 0) return undefined;
+	const parsed = Number(value);
+	return Number.isFinite(parsed) && parsed >= 0 ? parsed : undefined;
+}
+
+function nonnegativeInteger(value: unknown): number | undefined {
+	const parsed = nonnegativeNumber(value);
+	return parsed === undefined ? undefined : Math.floor(parsed);
+}
+
+function apiBaseHost(value: unknown): string | undefined {
+	const raw = nonEmptyString(value);
+	if (raw === undefined) return undefined;
+	try {
+		return new URL(raw).host || undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+function storedApiBaseHost(value: unknown): string | undefined {
+	const raw = nonEmptyString(value);
+	if (raw === undefined) return undefined;
+	try {
+		return new URL(raw.includes("://") ? raw : `http://${raw}`).host || undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+/** Read LiteLLM's response headers without retaining sensitive API-base data. */
+export function liteLLMGatewayRoutingFromHeaders(headers: HeaderReader): GatewayRoutingObservation | null {
+	const callId = nonEmptyString(headers.get("x-litellm-call-id"));
+	const modelGroup = nonEmptyString(headers.get("x-litellm-model-group"));
+	const modelName = nonEmptyString(headers.get("x-litellm-model-name"));
+	const host = apiBaseHost(headers.get("x-litellm-model-api-base"));
+	const deploymentId = nonEmptyString(headers.get("x-litellm-model-id"));
+	const attemptedFallbacks = nonnegativeInteger(headers.get("x-litellm-attempted-fallbacks"));
+	const attemptedRetries = nonnegativeInteger(headers.get("x-litellm-attempted-retries"));
+	const overheadMs = nonnegativeNumber(headers.get("x-litellm-overhead-duration-ms"));
+	const responseDurationMs = nonnegativeNumber(headers.get("x-litellm-response-duration-ms"));
+	const version = nonEmptyString(headers.get("x-litellm-version"));
+	const observation: GatewayRoutingObservation = {
+		gateway: "litellm",
+		...(callId !== undefined ? { callId } : {}),
+		...(modelGroup !== undefined ? { modelGroup } : {}),
+		...(modelName !== undefined ? { modelName } : {}),
+		...(host !== undefined ? { apiBaseHost: host } : {}),
+		...(deploymentId !== undefined ? { deploymentId } : {}),
+		...(attemptedFallbacks !== undefined ? { attemptedFallbacks } : {}),
+		...(attemptedRetries !== undefined ? { attemptedRetries } : {}),
+		...(overheadMs !== undefined ? { overheadMs } : {}),
+		...(responseDurationMs !== undefined ? { responseDurationMs } : {}),
+		...(version !== undefined ? { version } : {}),
+	};
+	return Object.keys(observation).length > 1 ? observation : null;
+}
+
+/** Parse a live message, persisted session row, or receipt response defensively. */
+export function gatewayRoutingObservationFromRecord(
+	record: Readonly<Record<string, unknown>>,
+): GatewayRoutingObservation | null {
+	const value = record.gatewayRouting;
+	if (value === null || typeof value !== "object" || Array.isArray(value)) return null;
+	const raw = value as Record<string, unknown>;
+	if (raw.gateway !== "litellm") return null;
+	const callId = nonEmptyString(raw.callId);
+	const modelGroup = nonEmptyString(raw.modelGroup);
+	const modelName = nonEmptyString(raw.modelName);
+	const host = storedApiBaseHost(raw.apiBaseHost);
+	const deploymentId = nonEmptyString(raw.deploymentId);
+	const attemptedFallbacks = nonnegativeInteger(raw.attemptedFallbacks);
+	const attemptedRetries = nonnegativeInteger(raw.attemptedRetries);
+	const overheadMs = nonnegativeNumber(raw.overheadMs);
+	const responseDurationMs = nonnegativeNumber(raw.responseDurationMs);
+	const version = nonEmptyString(raw.version);
+	const observation: GatewayRoutingObservation = {
+		gateway: "litellm",
+		...(callId !== undefined ? { callId } : {}),
+		...(modelGroup !== undefined ? { modelGroup } : {}),
+		...(modelName !== undefined ? { modelName } : {}),
+		...(host !== undefined ? { apiBaseHost: host } : {}),
+		...(deploymentId !== undefined ? { deploymentId } : {}),
+		...(attemptedFallbacks !== undefined ? { attemptedFallbacks } : {}),
+		...(attemptedRetries !== undefined ? { attemptedRetries } : {}),
+		...(overheadMs !== undefined ? { overheadMs } : {}),
+		...(responseDurationMs !== undefined ? { responseDurationMs } : {}),
+		...(version !== undefined ? { version } : {}),
+	};
+	return Object.keys(observation).length > 1 ? observation : null;
+}
+
+/** Compact human projection for receipts and operator notices. */
+export function gatewayRoutingObservationLabel(observation: GatewayRoutingObservation): string {
+	const route = [observation.modelGroup, observation.modelName].filter(Boolean).join("->");
+	const destination = [route, observation.apiBaseHost ? `@${observation.apiBaseHost}` : ""].filter(Boolean).join("");
+	const parts = [
+		"gateway=litellm",
+		...(destination ? [`route=${destination}`] : []),
+		...(observation.attemptedFallbacks !== undefined ? [`fallbacks=${observation.attemptedFallbacks}`] : []),
+		...(observation.attemptedRetries !== undefined ? [`retries=${observation.attemptedRetries}`] : []),
+		...(observation.overheadMs !== undefined ? [`overhead_ms=${observation.overheadMs}`] : []),
+	];
+	return parts.join(" ");
+}

package/src/core/guardrails.ts

@@ -2,17 +2,11 @@
  * Guardrail policy values: the numeric backstops that bound runaway agent
  * behavior (tool-call budgets, tool output byte caps, dispatch ledger size).
  *
- * These are durable operator policy, the same species as
- * `compaction.threshold`, so their primary home is the `guardrails:` section
- * of settings.yaml. The composition roots (orchestrator entry and worker
- * runtime) wire that section in via {@link configureGuardrails}; consumers
- * resolve values through {@link resolveGuardrail}, which layers a per-process
- * env override on top for CI and one-off experiments:
- *
- *   env var  >  settings.yaml guardrails  >  built-in default
- *
- * Every value is a positive safe integer; invalid overrides fall through to
- * the next layer rather than erroring.
+ * These are durable operator policy, so their only configurable home is the
+ * canonical version 2 settings tree. Composition roots project that tree into
+ * this process through {@link configureGuardrails}; hot-path consumers resolve
+ * the current projection through {@link resolveGuardrail} without reading
+ * settings.yaml themselves.
  */
 
 export interface GuardrailValues {
@@ -66,16 +60,6 @@ export const GUARDRAIL_DEFAULTS: GuardrailValues = {
 	internalDispatchTimeoutMs: 15 * 60 * 1000,
 };
 
-/** Per-process env overrides, one per guardrail. */
-export const GUARDRAIL_ENV_VARS: Readonly<Record<keyof GuardrailValues, string>> = {
-	turnToolCallBudget: "CLIO_CODER_TURN_TOOL_CALL_BUDGET",
-	workerToolCallCap: "CLIO_CODER_WORKER_TOOL_CALL_CAP",
-	maxDispatchRuns: "CLIO_CODER_MAX_DISPATCH_RUNS",
-	readMaxBytes: "CLIO_CODER_READ_MAX_BYTES",
-	observationTurnBudgetBytes: "CLIO_CODER_OBSERVATION_TURN_BUDGET_BYTES",
-	internalDispatchTimeoutMs: "CLIO_CODER_INTERNAL_DISPATCH_TIMEOUT_MS",
-};
-
 /** Project canonical v2 settings leaves onto the process-local guardrail registry. */
 export function guardrailValuesFromSettings(settings: {
 	safety: {
@@ -100,15 +84,6 @@ export function guardrailValuesFromSettings(settings: {
 	};
 }
 
-/**
- * Older env spellings that still read. `CLIO_CODER_MAX_RUNS` was the only
- * guardrail whose variable was not the SCREAMING_SNAKE of its key, and CI
- * environments already set it, so it keeps working behind the canonical name.
- */
-const GUARDRAIL_ENV_ALIASES: Readonly<Partial<Record<keyof GuardrailValues, string>>> = {
-	maxDispatchRuns: "CLIO_CODER_MAX_RUNS",
-};
-
 /**
  * One-shot annotation attached to the first tool result inside the reserve
  * window. Advisory: the call that carried it still ran; only subsequent
@@ -178,28 +153,14 @@ export function mentionsWorkerToolCallCap(text: string | null | undefined): bool
 let configured: Partial<GuardrailValues> = {};
 
 /**
- * Install the settings.yaml `guardrails:` section. Called once per process by
- * the composition roots; later calls replace the whole layer (used by tests).
+ * Install the effective settings projection. Later calls replace the whole
+ * layer when a session override or configuration reload changes the view.
  */
 export function configureGuardrails(values: Partial<GuardrailValues> | undefined): void {
 	configured = { ...(values ?? {}) };
 }
 
-function parsePositiveSafeInt(raw: string | undefined): number | undefined {
-	if (raw === undefined) return undefined;
-	const normalized = raw.trim();
-	if (!/^[1-9]\d*$/.test(normalized)) return undefined;
-	const parsed = Number(normalized);
-	return Number.isSafeInteger(parsed) ? parsed : undefined;
-}
-
-/** Resolve one guardrail: env override > configured settings > default. */
-export function resolveGuardrail(key: keyof GuardrailValues, env: NodeJS.ProcessEnv = process.env): number {
-	const alias = GUARDRAIL_ENV_ALIASES[key];
-	return (
-		parsePositiveSafeInt(env[GUARDRAIL_ENV_VARS[key]]) ??
-		(alias ? parsePositiveSafeInt(env[alias]) : undefined) ??
-		configured[key] ??
-		GUARDRAIL_DEFAULTS[key]
-	);
+/** Resolve one guardrail from the effective settings projection or its default. */
+export function resolveGuardrail(key: keyof GuardrailValues): number {
+	return configured[key] ?? GUARDRAIL_DEFAULTS[key];
 }

package/src/core/prompt-hint.ts

@@ -0,0 +1,9 @@
+/** Collapse descriptor-authored prompt guidance to one byte-stable line. */
+export function normalizePromptHint(text: string | undefined): string | undefined {
+	if (!text) return undefined;
+	const normalized = text
+		.replace(/[\r\n]+/gu, " ")
+		.replace(/\s+/gu, " ")
+		.trim();
+	return normalized.length > 0 ? normalized : undefined;
+}

package/src/core/safe-exec.ts

@@ -24,6 +24,18 @@ const ENV_ALLOWLIST = [
 	"TMP",
 	"CI",
 	"NO_COLOR",
+	// Platform/session location variables needed by installed local CLIs. These
+	// locate operator-owned state; provider keys and Clio gates are deliberately
+	// absent from this allowlist.
+	"XDG_CONFIG_HOME",
+	"XDG_CACHE_HOME",
+	"XDG_STATE_HOME",
+	"APPDATA",
+	"LOCALAPPDATA",
+	"SYSTEMROOT",
+	"WINDIR",
+	"COMSPEC",
+	"PATHEXT",
 ] as const;
 
 export interface SafeCommandResult {
@@ -49,10 +61,13 @@ export interface RunCommandVectorOptions {
 	env?: Record<string, string>;
 }
 
-export function buildSafeToolEnv(extra: Record<string, string> = {}): NodeJS.ProcessEnv {
+export function buildSafeToolEnv(
+	extra: Record<string, string> = {},
+	source: NodeJS.ProcessEnv = process.env,
+): NodeJS.ProcessEnv {
 	const env: NodeJS.ProcessEnv = {};
 	for (const key of ENV_ALLOWLIST) {
-		const value = process.env[key];
+		const value = source[key];
 		if (value !== undefined) env[key] = value;
 	}
 	for (const [key, value] of Object.entries(extra)) {

package/src/core/skill-activation.ts

@@ -58,6 +58,90 @@ export interface PendingSkillToolPolicy {
 	loadedSkillNames: Set<string>;
 	/** Declared tool policy per successfully loaded skill, recorded by context(scope=skills). */
 	loadedSkillPolicies: Map<string, SkillDeclaredToolPolicy>;
+	/**
+	 * True once this policy is a surface that outlived the turn that armed it.
+	 * The narrowing is identical; the flag exists so a load request the policy
+	 * does not cover reads as "only the operator activates skills" rather than
+	 * claiming a pending request that no longer exists.
+	 */
+	carriedSurface?: boolean;
+	/**
+	 * True when the session's autonomy level lets the model activate an
+	 * installed skill itself instead of emitting the suggestion anchor and
+	 * waiting for `/skill`. Activation is the same per-run policy the operator's
+	 * path produces: skills only ever narrow the tool surface, so this grants
+	 * nothing the level had not already granted. Marketplace (not yet
+	 * installed) skills stay operator-gated at every level.
+	 */
+	modelActivation?: boolean;
+}
+
+/**
+ * The surface that stays armed after an interactive turn ends.
+ *
+ * A skill an operator loaded narrows the tools for the workflow it started,
+ * and a multi-turn workflow (an interview skill asking a question per turn)
+ * is still inside that workflow on the operator's next message. Dropping the
+ * narrowing at turn end handed the workflow back the full surface partway
+ * through, which is how a `bash` call correctly refused in turn one ran in
+ * turn six. Returns undefined when nothing declared a narrowing, which is the
+ * signal to clear whatever surface was armed before.
+ */
+export function armedSkillSurface(policy: PendingSkillToolPolicy | undefined): PendingSkillToolPolicy | undefined {
+	if (!policy) return undefined;
+	const declared = [...policy.loadedSkillPolicies.entries()].filter(
+		([, declaration]) => (declaration.allowedTools?.length ?? 0) > 0 || (declaration.disallowedTools?.length ?? 0) > 0,
+	);
+	if (declared.length === 0) return undefined;
+	return {
+		allowedSkillNames: [...policy.allowedSkillNames],
+		requests: [...policy.requests],
+		loadedSkillNames: new Set(policy.loadedSkillNames),
+		loadedSkillPolicies: new Map(declared),
+		carriedSurface: true,
+	};
+}
+
+/** Skill names contributing a declaration to an armed surface, for the operator notice. */
+export function skillSurfaceNames(policy: PendingSkillToolPolicy | undefined): ReadonlyArray<string> {
+	return policy ? [...policy.loadedSkillPolicies.keys()] : [];
+}
+
+/**
+ * The same names, each tagged with who activated it. A skill the operator
+ * named arrives as a pending request; anything else was activated by the model
+ * under `modelActivation`, and the operator's one line about the surface is
+ * where that distinction has to be visible.
+ */
+export function skillSurfaceLabels(policy: PendingSkillToolPolicy | undefined): ReadonlyArray<string> {
+	if (!policy) return [];
+	return [...policy.loadedSkillPolicies.keys()].map((name) =>
+		policy.requests.some((request) => request.name === name) ? `${name} (operator)` : `${name} (model)`,
+	);
+}
+
+/**
+ * Stamp (or clear) the model-activation grant on the policy this turn runs
+ * under, creating one when nothing else did. Mutates in place so a surface
+ * carried from an earlier turn keeps its identity, and re-stamps every turn so
+ * a level change takes effect on the next message rather than the next skill.
+ */
+export function withModelSkillActivation(
+	policy: PendingSkillToolPolicy | undefined,
+	enabled: boolean,
+): PendingSkillToolPolicy | undefined {
+	if (policy) {
+		policy.modelActivation = enabled;
+		return policy;
+	}
+	if (!enabled) return undefined;
+	return {
+		allowedSkillNames: [],
+		requests: [],
+		loadedSkillNames: new Set<string>(),
+		loadedSkillPolicies: new Map<string, SkillDeclaredToolPolicy>(),
+		modelActivation: true,
+	};
 }
 
 /**
@@ -75,6 +159,8 @@ export interface SkillToolSurfaceViolation {
 	mergedAllowedTools: ReadonlyArray<string> | null;
 	/** Skills whose disallowed-tools name the tool directly. */
 	disallowedBy: ReadonlyArray<string>;
+	/** True when the surface outlived the turn that armed it, which changes the lifetime the block message states. */
+	carriedSurface: boolean;
 }
 
 /**
@@ -98,15 +184,16 @@ export function evaluateSkillToolSurface(
 	if (SKILL_SURFACE_EXEMPT_TOOLS.has(tool)) return null;
 	const entries = [...policy.loadedSkillPolicies.entries()];
 	const skills = entries.map(([name]) => name);
+	const carriedSurface = policy.carriedSurface === true;
 	const disallowedBy = entries
 		.filter(([, declared]) => declared.disallowedTools?.includes(tool) === true)
 		.map(([name]) => name);
-	if (disallowedBy.length > 0) return { skills, mergedAllowedTools: null, disallowedBy };
+	if (disallowedBy.length > 0) return { skills, mergedAllowedTools: null, disallowedBy, carriedSurface };
 	const allowLists = entries.map(([, declared]) => declared.allowedTools);
 	if (allowLists.some((list) => list === undefined || list.length === 0)) return null;
 	const merged = [...new Set(allowLists.flatMap((list) => [...(list ?? [])]))];
 	if (merged.includes(tool)) return null;
-	return { skills, mergedAllowedTools: merged, disallowedBy: [] };
+	return { skills, mergedAllowedTools: merged, disallowedBy: [], carriedSurface };
 }
 
 /**

package/src/domains/agents/builtins/architect.md

@@ -1,7 +1,7 @@
 ---
 version: 1
 name: Architect
-description: Designs coding changes across boundaries, contracts, migrations, and validation gates; slices an existing plan into an executable dependency-ordered sprint via its bound cut-it skill.
+description: Designs a change across boundaries and slices it into a sprint. Covers contracts, migrations, and validation gates, and turns an existing plan into a dependency-ordered sprint through its bound cut-it skill.
 tools:
   required: [artifact, context]
   optional: [read, grep, find, ls, code_nav, git, ledger]
@@ -22,8 +22,7 @@ You are Architect, the base design agent for coding work.
 Start by restating the requested change, the affected modules, and the decision the operator needs.
 Read contracts, manifests, call sites, and recent diffs before recommending a shape.
 Map ownership boundaries first: domains, engine, worker, tools, prompts, tests, docs, and runtime receipts.
-Before broad exploration, check `code_nav mode=wiki` and read `.clio-coder/wiki/quickstart.md` when a wiki exists.
-Use codewiki tools only when the assignment is navigation-heavy. Otherwise rely on the provided context and targeted reads.
+When `code_nav` is among your tools and a wiki exists, check `code_nav mode=wiki` and read `.clio-coder/wiki/quickstart.md` before broad exploration; otherwise rely on the provided context and targeted reads.
 Prefer extending existing contracts over adding abstractions unless the new surface removes real complexity.
 Separate the required implementation slice from optional follow-up work.
 Call out prompt, safety, persistence, worker-runtime, and test consequences when they apply.

package/src/domains/agents/builtins/coder.md

@@ -1,7 +1,7 @@
 ---
 version: 1
 name: Coder
-description: Implements bounded code changes, repairs, and behavior-preserving refactors.
+description: Implements bounded code changes, repairs, and refactors. Behavior-preserving by default.
 tools:
   required: [read, {anyOf: [write, edit]}, context]
   optional: [grep, find, ls, web_fetch, git, verify, code_nav, bash, ledger]
@@ -21,12 +21,13 @@ tags: [implementation, repair, refactor]
 You are Coder, the base implementation agent.
 Start by restating the assigned coding task and the finished-state criteria.
 Read the local code, tests, and call sites before changing files.
-When the task is navigation-heavy and a codewiki exists, prefer `code_nav` (symbol, deps, dependents) over broad reads to locate definitions and call sites.
+When `code_nav` is among your tools, prefer it (symbol, deps, dependents) over broad reads to locate definitions and call sites.
 Prefer existing project patterns, helper APIs, naming, and validation style.
 Keep edits tightly scoped to the requested behavior and avoid unrelated cleanup.
 Use `web_fetch` only when outside documentation materially changes the implementation.
 Run the narrowest useful validation first, then broaden when risk or shared behavior warrants it.
 Use `git` (op=diff) before finishing to verify the diff matches the task.
+Make each read and verification call once: an identical repeated call is blocked and costs a round, so re-read the earlier result instead of calling again.
 If a requested simplification would change behavior, stop and report the boundary.
 Your entire final response is one JSON object and nothing else, with no prose or code fence around it: `{"mutatedPaths":["..."],"validations":[{"name":"...","passed":true,"evidence":"..."}]}`. Report every mutation and at least one concrete validation result.
 `validations` is never empty and never a list of strings. Each entry is one check you actually made, shaped like `{"name":"npm test","passed":true,"evidence":"exit 0"}`, with no other keys. When the task changed nothing, the read or command you did run is still the validation: name it and quote what it showed.