@iowarp/clio-coder 0.4.1 → 0.4.3

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

@@ -217,20 +217,8 @@ function defaultPrecedenceForScope(scope: ResourceScope): number {
  * this gate with skills: both substitute another agent's project file into
  * Clio's context, so one opt-in covers both.
  */
-let warnedLegacyProjectTrustEnv = false;
-
 export function projectCompatTrusted(explicit?: boolean): boolean {
-	if (explicit === true) return true;
-	if (process.env.CLIO_CODER_TRUST_PROJECT_RESOURCES === "1") return true;
-	if (process.env.CLIO_CODER_TRUST_PROJECT_SKILLS !== "1") return false;
-	if (!warnedLegacyProjectTrustEnv) {
-		warnedLegacyProjectTrustEnv = true;
-		process.emitWarning("CLIO_CODER_TRUST_PROJECT_SKILLS is deprecated; use CLIO_CODER_TRUST_PROJECT_RESOURCES instead", {
-			code: "CLIO_CODER_DEPRECATED_ENV",
-			type: "DeprecationWarning",
-		});
-	}
-	return true;
+	return explicit === true;
 }
 
 /**
@@ -453,7 +441,16 @@ function validateDescription(description: string | null): string[] {
 	return [];
 }
 
-function extractMetadata(frontmatter: Record<string, unknown>): Record<string, unknown> {
+/**
+ * The deprecation names the file: a bare "clio: skill metadata" warning at
+ * boot left the operator hunting across five compatibility roots for the
+ * SKILL.md that carried the key, and `doctor` scanned only two of them.
+ */
+function warnLegacySkillMetadata(filePath: string): void {
+	warnLegacyNaming(`clio: skill metadata in ${filePath}`, "clio-coder: skill metadata");
+}
+
+function extractMetadata(frontmatter: Record<string, unknown>, filePath: string): Record<string, unknown> {
 	const metadata: Record<string, unknown> = {};
 	for (const [key, value] of Object.entries(frontmatter)) {
 		if (CORE_FRONTMATTER_KEYS.has(key)) continue;
@@ -462,7 +459,7 @@ function extractMetadata(frontmatter: Record<string, unknown>): Record<string, u
 			continue;
 		}
 		if (key === "clio") {
-			warnLegacyNaming("clio: skill metadata", "clio-coder: skill metadata");
+			warnLegacySkillMetadata(filePath);
 			if (!("clio-coder" in frontmatter)) metadata.clioCoder = value;
 			continue;
 		}
@@ -471,13 +468,13 @@ function extractMetadata(frontmatter: Record<string, unknown>): Record<string, u
 	return metadata;
 }
 
-function extractProvenance(frontmatter: Record<string, unknown>): SkillProvenance | undefined {
+function extractProvenance(frontmatter: Record<string, unknown>, filePath: string): SkillProvenance | undefined {
 	// Provenance lives nested under the reserved `clio-coder:` block; the flat
 	// top-level keys remain readable for already-installed copies stamped
 	// before the nested form existed.
 	const canonicalRaw = frontmatter["clio-coder"];
 	const legacyRaw = frontmatter.clio;
-	if (legacyRaw !== undefined) warnLegacyNaming("clio: skill metadata", "clio-coder: skill metadata");
+	if (legacyRaw !== undefined) warnLegacySkillMetadata(filePath);
 	const clioCoderRaw = canonicalRaw ?? legacyRaw;
 	const clioCoder =
 		clioCoderRaw !== null && typeof clioCoderRaw === "object" && !Array.isArray(clioCoderRaw)
@@ -671,7 +668,7 @@ function loadSkillFile(
 		scope,
 		...(root.origin ? { source: root.origin } : {}),
 	};
-	const provenance = extractProvenance(parsed.frontmatter);
+	const provenance = extractProvenance(parsed.frontmatter, filePath);
 	const allowedTools = declaredToolSurface(parsed.frontmatter, "allowed-tools", filePath, diagnostics);
 	const disallowedTools = declaredToolSurface(parsed.frontmatter, "disallowed-tools", filePath, diagnostics);
 	const skill: Skill = {
@@ -691,7 +688,7 @@ function loadSkillFile(
 		pathSubject,
 		trusted: root.trusted ?? true,
 		precedence: root.precedence ?? defaultPrecedenceForScope(scope),
-		metadata: extractMetadata(parsed.frontmatter),
+		metadata: extractMetadata(parsed.frontmatter, filePath),
 		diagnostics,
 		...(provenance ? { provenance } : {}),
 	};
@@ -952,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/call-target.ts

@@ -168,7 +168,7 @@ const CALL_TARGET_FIELDS: Readonly<Record<string, ReadonlyArray<string>>> = {
 	grep: ["pattern", "path", "mode", "glob", "ignore_case", "literal", "context", "limit", "include_ignored"],
 	find: ["pattern", "path", "order", "limit", "include_ignored"],
 	ls: ["path", "limit"],
-	code_nav: ["mode", "query", "limit"],
+	code_nav: ["source", "mode", "query", "limit"],
 	context: ["scope", "query", "name", "limit", "ref", "include_tree"],
 	credential_present: ["name", "source", "file"],
 	write: ["path"],

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/loop-detector.ts

@@ -33,10 +33,12 @@ const DEFAULT_WINDOW_MS = 30_000;
 // stops them before they burn a turn. Callers that need a different cadence
 // pass `maxRepeats` explicitly.
 const DEFAULT_MAX_REPEATS = 3;
-// Sized so a consecutive or single-interleaved verbatim spiral still counts
-// its third repeat at any call latency, while an identical check separated by
-// two or more other calls (a fix-verify loop) stays below the threshold.
-const DEFAULT_KEEP_LAST_ATTEMPTS = 4;
+// Sized so a batch-shaped spiral still counts its third repeat at any call
+// latency: a model that re-emits the same parallel batch of up to sixteen
+// calls three times has every key inside the retained tail. Fix-verify loops
+// are not this detector's concern any more; the loop guard keys attempts by
+// the turn's write/edit epoch, so a check rerun after a change is a new key.
+const DEFAULT_KEEP_LAST_ATTEMPTS = 48;
 
 export function createLoopState(opts?: {
 	windowMs?: number;
@@ -138,6 +140,7 @@ export function observe(state: LoopDetectorState, key: string, now: number): [Lo
 		recent: next,
 		windowMs: state.windowMs,
 		maxRepeats: state.maxRepeats,
+		keepLastAttempts: keepLast,
 	};
 	return [newState, { looping, key, count }];
 }

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;