@iowarp/clio-coder 0.4.2 → 0.4.3

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";
+		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/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/index.ts

@@ -19,6 +19,7 @@ export {
 	DEFAULT_AUTONOMY_LEVEL,
 	isAutonomyLevel,
 	mapAutonomy,
+	modelMayActivateSkills,
 } from "./autonomy.js";
 export type { SafetyContract, SafetyDecision } from "./contract.js";
 export type {

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

@@ -41,7 +41,7 @@ export function isSameOrDescendant(candidatePath: string, policyPath: string): b
 	const candidate = path.resolve(candidatePath);
 	const policy = path.resolve(policyPath);
 	const relative = path.relative(policy, candidate);
-	return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+	return relative === "" || (relative !== ".." && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative));
 }
 
 function expandTilde(rawPath: string): string {

package/src/domains/safety/policy-engine.ts

@@ -25,10 +25,12 @@ import {
 	extractCommandDeleteTargets,
 	extractCommandWriteTargets,
 	inlineShellScript,
-	tokenizeShellLike,
+	invokesClioSkillMutation,
+	scanShellLike,
 } from "./protected-artifacts.js";
 import { formatRejection, type RejectionMessage } from "./rejection-feedback.js";
 import { getCachedDefaultRulePacks, type PackId, type RulePacks } from "./rule-pack-loader.js";
+import { activeClioSkillRoots, skillMutationReason } from "./skill-authority.js";
 
 export type SafetyPolicySource =
 	| "damage-control:base"
@@ -194,6 +196,7 @@ export function createSafetyPolicyEngine(options: SafetyPolicyEngineOptions = {}
 	// cwd and roots to compare like against like (the design mandates no symlink chasing).
 	const writeRootCwd = path.resolve(options.cwd ?? process.cwd());
 	const writeRoots = (options.writeRoots ?? []).map((root) => resolvePathBoundary(writeRootCwd, root));
+	const skillRoots = activeClioSkillRoots(cwd);
 	const packs = options.rulePacks ?? getCachedDefaultRulePacks();
 	const projectPolicy = options.projectPolicy ?? loadProjectSafetyPolicy(cwd);
 	const projectPolicyRoot =
@@ -308,6 +311,27 @@ export function createSafetyPolicyEngine(options: SafetyPolicyEngineOptions = {}
 				return blockDecision(base, blockInput);
 			}
 
+			// Editing active instructions is an operator privilege at every autonomy
+			// level, in both the coordinator and the shared worker safety contract.
+			const mutationCommand = call.tool === ToolNames.Bash ? command : catalogCommand;
+			const skillReason =
+				mutationCommand !== null && invokesClioSkillMutation(mutationCommand)
+					? "skill installation and updates require the operator CLI or an explicit operator install choice; draft outside active skill roots"
+					: skillMutationReason(
+							skillRoots,
+							pathPolicyTargets(catalogCommand === null ? call : { tool: ToolNames.Bash, args: { command: catalogCommand } }),
+							callCwd,
+							mutationCommand,
+						);
+			if (skillReason !== null) {
+				return blockDecision(base, {
+					ruleId: "skill-authority",
+					reasonCode: "skill-authority",
+					reasons: [skillReason],
+					policySource: "builtin-classifier",
+				});
+			}
+
 			// The path policy runs regardless of project policy validity. When
 			// `.clio-coder/safety.yaml` is invalid, the loader has already dropped every
 			// project-authored path entry and forced `disableDefaultPathPolicy`
@@ -488,10 +512,10 @@ function stripQuotes(token: string): string {
  */
 function bashPathTokenCandidates(command: string): string[] {
 	const candidates: string[] = [];
-	for (const token of tokenizeShellLike(command)) {
+	for (const scanned of scanShellLike(command)) {
+		if (scanned.operator) continue;
+		const token = scanned.value;
 		if (token.length === 0) continue;
-		if (token === ";" || token === "&&" || token === "||" || token === "|" || token === ">" || token === ">>") continue;
-		if (token === "<" || token === "<<") continue;
 		// A token containing whitespace came from a quoted string of prose, not
 		// a path argument; and flags are not paths unless they embed one
 		// (--file=~/.aws/credentials).
@@ -821,9 +845,6 @@ function matchingProjectCommand(
 	return null;
 }
 
-/** Operators that end chain recognition; only `&&` keeps a chain readable. */
-const CHAIN_BREAKING_TOKENS: ReadonlySet<string> = new Set([";", "|", "||", ">", ">>", "<", "<<"]);
-
 /** Chain length ceiling. Real compound calls are two or three steps. */
 const CHAIN_MAX_SEGMENTS = 6;
 
@@ -856,14 +877,16 @@ function recognizeCommandChain(
 ): ChainRecognition | null {
 	const segments: string[][] = [];
 	let current: string[] = [];
-	for (const token of tokenizeShellLike(command)) {
-		if (token === "&&") {
+	for (const token of scanShellLike(command)) {
+		if (token.operator && token.value === "&&") {
 			segments.push(current);
 			current = [];
 			continue;
 		}
-		if (CHAIN_BREAKING_TOKENS.has(token)) return null;
-		current.push(token);
+		// Only an actual && operator joins recognizable commands. Quoted words
+		// remain argv and every other real operator makes this chain unrecognized.
+		if (token.operator) return null;
+		current.push(token.value);
 	}
 	segments.push(current);
 	if (segments.length < 2 || segments.length > CHAIN_MAX_SEGMENTS) return null;