@iowarp/clio-coder 0.4.6 → 0.4.8

package/src/domains/agents/fleet-commands.ts

@@ -38,7 +38,14 @@ export const FLEET_COMMAND_DEFAULT_TIMEOUT_MS = 600_000;
  */
 export const FLEET_COMMAND_BASE_ENV: ReadonlyArray<string> = ["PATH", "HOME", "LANG", "LC_ALL", "TZ", "TMPDIR"];
 
+export interface FleetCommandArgumentSlot {
+	name: string;
+	maxLength: number;
+}
+
 export interface FleetCommand {
+	/** Operator-owned required positional data slots; omission forbids appended args. */
+	argumentSlots?: ReadonlyArray<FleetCommandArgumentSlot>;
 	id: string;
 	/** argv list, never a shell string: no quoting bugs and no shell injection. */
 	argv: ReadonlyArray<string>;
@@ -59,6 +66,18 @@ export interface FleetCommandRegistry {
 const CommandSchema = Type.Object(
 	{
 		argv: Type.Array(Type.String({ minLength: 1 }), { minItems: 1 }),
+		argumentSlots: Type.Optional(
+			Type.Array(
+				Type.Object(
+					{
+						name: Type.String({ pattern: "^[A-Za-z][A-Za-z0-9_-]{0,63}$" }),
+						maxLength: Type.Integer({ minimum: 1, maximum: 8192 }),
+					},
+					{ additionalProperties: false },
+				),
+				{ minItems: 1, maxItems: 64 },
+			),
+		),
 		cwd: Type.Optional(Type.String({ minLength: 1 })),
 		timeoutMs: Type.Optional(
 			Type.Integer({ minimum: FLEET_COMMAND_MIN_TIMEOUT_MS, maximum: FLEET_COMMAND_MAX_TIMEOUT_MS }),
@@ -114,7 +133,17 @@ export function parseFleetCommands(raw: string, sourcePath: string): FleetComman
 	if (schemaError !== null) throw new Error(`fleet commands ${sourcePath}: ${schemaError}`);
 	const registry = parsed as {
 		version: 1;
-		commands: Record<string, { argv: string[]; cwd?: string; timeoutMs?: number; env?: string[]; description?: string }>;
+		commands: Record<
+			string,
+			{
+				argv: string[];
+				argumentSlots?: FleetCommandArgumentSlot[];
+				cwd?: string;
+				timeoutMs?: number;
+				env?: string[];
+				description?: string;
+			}
+		>;
 	};
 	const commands = new Map<string, FleetCommand>();
 	for (const [id, entry] of Object.entries(registry.commands)) {
@@ -130,9 +159,16 @@ export function parseFleetCommands(raw: string, sourcePath: string): FleetComman
 				throw new Error(`fleet commands ${sourcePath}: command '${id}' env name '${name}' is not a variable name`);
 			}
 		}
+		if (entry.argumentSlots)
+			validateFleetCommandArgs(
+				{ id, argv: entry.argv, cwd: "", timeoutMs: 1000, env: [], description: "", argumentSlots: entry.argumentSlots },
+				entry.argumentSlots.map(() => "{{slot}}"),
+				{ allowTemplates: true },
+			);
 		commands.set(id, {
 			id,
 			argv: [...entry.argv],
+			...(entry.argumentSlots ? { argumentSlots: entry.argumentSlots.map((slot) => ({ ...slot })) } : {}),
 			cwd: entry.cwd === undefined ? "" : checkCwd(id, entry.cwd, sourcePath),
 			timeoutMs: entry.timeoutMs ?? FLEET_COMMAND_DEFAULT_TIMEOUT_MS,
 			env: [...(entry.env ?? [])],
@@ -152,3 +188,58 @@ export function loadFleetCommands(cwd: string): FleetCommandRegistry | null {
 	if (!existsSync(path)) return null;
 	return parseFleetCommands(readFileSync(path, "utf8"), path);
 }
+
+/** Bind authored code-step arguments before plan admission; each stays one argv token. */
+export function resolveFleetCommandArgs(
+	args: ReadonlyArray<string>,
+	vars: Readonly<Record<string, string>> = {},
+): string[] {
+	if (args.length > 64) throw new Error("fleet code args: at most 64 arguments are allowed");
+	return args.map((token) => {
+		const match = /^\{\{\s*([A-Za-z_][A-Za-z0-9_-]*)\s*\}\}$/u.exec(token);
+		if (!match && token.includes("{{")) throw new Error("fleet code args: placeholders must occupy a whole argument");
+		const value = match ? vars[match[1] ?? ""] : token;
+		if (value === undefined) throw new Error(`fleet code args: missing variable ${match?.[1]} (pass --var name=value)`);
+		if (value.includes("\0") || value.length > 8192)
+			throw new Error("fleet code args: invalid NUL or oversized argument");
+		return value;
+	});
+}
+
+/** Enforce operator-declared data slots; contracts cannot append flags or executable code. */
+export function validateFleetCommandArgs(
+	command: FleetCommand,
+	args: ReadonlyArray<string>,
+	options: { allowTemplates?: boolean } = {},
+): void {
+	const slots = command.argumentSlots ?? [];
+	if (
+		slots.length > 64 ||
+		new Set(slots.map((slot) => slot.name)).size !== slots.length ||
+		slots.some(
+			(slot) =>
+				!/^[A-Za-z][A-Za-z0-9_-]{0,63}$/u.test(slot.name) ||
+				!Number.isInteger(slot.maxLength) ||
+				slot.maxLength < 1 ||
+				slot.maxLength > 8192,
+		)
+	) {
+		throw new Error(`fleet command '${command.id}': invalid argumentSlots declaration`);
+	}
+	if (args.length !== slots.length) {
+		throw new Error(
+			`fleet command '${command.id}': expected ${slots.length} declared argument slots, got ${args.length}; the operator must declare argumentSlots in commands.yaml`,
+		);
+	}
+	for (let index = 0; index < slots.length; index++) {
+		const slot = slots[index];
+		const value = args[index];
+		if (!slot || typeof value !== "string") throw new Error(`fleet command '${command.id}': invalid argument`);
+		if (options.allowTemplates && /^\{\{\s*([A-Za-z_][A-Za-z0-9_-]*)\s*\}\}$/u.test(value)) continue;
+		if (value.length === 0 || value.length > slot.maxLength || value.includes("\0") || value.startsWith("-")) {
+			throw new Error(
+				`fleet command '${command.id}': argument '${slot.name}' must be nonempty data of at most ${slot.maxLength} characters, without NUL or a leading dash; fixed flags belong in argv`,
+			);
+		}
+	}
+}

package/src/domains/agents/fleet-contract.ts

@@ -1,3 +1,5 @@
+import { enabledPluginResourceRoots } from "../plugins/index.js";
+import { resolvePackagePathReference, resolvePackageReferences } from "../resources/package-references.js";
 /**
  * Repo-owned fleet contracts (Symphony P5: work policy lives in the repo,
  * versioned and strictly validated).
@@ -16,8 +18,12 @@ import { Type } from "typebox";
 import { Value } from "typebox/value";
 import { resolvePackageRoot } from "../../core/package-root.js";
 import { clioConfigDir } from "../../core/xdg.js";
-import { enabledExtensionResourceRoots } from "../extensions/index.js";
-import { type FleetCommandRegistry, loadFleetCommands } from "./fleet-commands.js";
+import {
+	type FleetCommandRegistry,
+	loadFleetCommands,
+	resolveFleetCommandArgs,
+	validateFleetCommandArgs,
+} from "./fleet-commands.js";
 import { parseFrontmatter } from "./frontmatter.js";
 import { normalizeWriteBoundary, WRITE_BOUNDARY_MAX_ENTRIES } from "./write-boundary.js";
 
@@ -111,6 +117,7 @@ export interface FleetContractCodeStep {
 	kind: "code";
 	id: string;
 	command: string;
+	args?: ReadonlyArray<string>;
 	scope: FleetStepScope;
 	dependencies: ReadonlyArray<string>;
 	commitFrom?: ReadonlyArray<string>;
@@ -119,7 +126,13 @@ export interface FleetContractCodeStep {
 
 /** The verification half of a loop: the question that decides continuation. */
 export type FleetContractLoopCheck =
-	| { kind: "code"; command: string; scope: FleetStepScope; writes?: ReadonlyArray<string> }
+	| {
+			kind: "code";
+			command: string;
+			args?: ReadonlyArray<string>;
+			scope: FleetStepScope;
+			writes?: ReadonlyArray<string>;
+	  }
 	| {
 			kind: "agent";
 			agent: string;
@@ -199,7 +212,7 @@ export interface FleetContract {
 	path: string;
 }
 
-export type FleetContractSource = "builtin" | "extension" | "user" | "project";
+export type FleetContractSource = "builtin" | "plugin" | "user" | "project";
 
 export interface FleetContractListing {
 	name: string;
@@ -291,6 +304,7 @@ function codeStepSchema(version: FleetContractVersion) {
 			kind: Type.Literal("code"),
 			id: Type.String({ minLength: 1 }),
 			command: Type.String({ minLength: 1 }),
+			args: Type.Optional(Type.Array(Type.String({ maxLength: 8192, pattern: "^[^\\u0000]*$" }), { maxItems: 64 })),
 			scope: FleetScopeSchema,
 			dependencies: Type.Array(Type.String({ minLength: 1 })),
 			...(version >= 3 ? { commitFrom: Type.Optional(Type.Array(Type.String({ minLength: 1 }), { minItems: 1 })) } : {}),
@@ -313,6 +327,7 @@ function loopStepSchema(version: FleetContractVersion) {
 					{
 						kind: Type.Literal("code"),
 						command: Type.String({ minLength: 1 }),
+						args: Type.Optional(Type.Array(Type.String({ maxLength: 8192, pattern: "^[^\\u0000]*$" }), { maxItems: 64 })),
 						scope: FleetScopeSchema,
 						...writesSchema(version),
 					},
@@ -412,12 +427,14 @@ type RawStep = {
 	id: string;
 	agent?: string;
 	command?: string;
+	args?: string[];
 	commitFrom?: string[];
 	writes?: string[];
 	maxAttempts?: number;
 	check?: {
 		kind: "code" | "agent" | "gate";
 		command?: string;
+		args?: string[];
 		agent?: string;
 		gate?: string;
 		scope: FleetStepScope;
@@ -488,7 +505,13 @@ function normalizeStep(step: RawStep): FleetContractStep {
 			dependencies: [...step.dependencies],
 			check:
 				check.kind === "code"
-					? { kind: "code", command: check.command ?? "", scope: check.scope, ...normalizedWrites(check.writes) }
+					? {
+							kind: "code",
+							command: check.command ?? "",
+							...(check.args ? { args: [...check.args] } : {}),
+							scope: check.scope,
+							...normalizedWrites(check.writes),
+						}
 					: check.kind === "gate"
 						? { kind: "gate", gate: check.gate ?? "" }
 						: {
@@ -512,6 +535,7 @@ function normalizeStep(step: RawStep): FleetContractStep {
 			kind: "code",
 			id: step.id,
 			command: step.command ?? "",
+			...(step.args ? { args: [...step.args] } : {}),
 			scope: step.scope,
 			dependencies: [...step.dependencies],
 			...(step.commitFrom !== undefined ? { commitFrom: [...step.commitFrom] } : {}),
@@ -901,13 +925,20 @@ export function fleetLoopSteps(contract: FleetContract): FleetContractLoopStep[]
  * check is a code step in every way that matters to the registry, so it is
  * bound to a real command by the same validation.
  */
-export function fleetCodeSteps(contract: FleetContract): Array<{ id: string; command: string }> {
-	const steps: Array<{ id: string; command: string }> = [];
+export function fleetCodeSteps(
+	contract: FleetContract,
+): Array<{ id: string; command: string; args?: ReadonlyArray<string> }> {
+	const steps: Array<{ id: string; command: string; args?: ReadonlyArray<string> }> = [];
 	for (const step of contract.steps) {
-		if (step.kind === "code") steps.push({ id: step.id, command: step.command });
+		if (step.kind === "code")
+			steps.push({ id: step.id, command: step.command, ...(step.args ? { args: step.args } : {}) });
 		else if (step.kind === "gate") steps.push({ id: step.id, command: step.run });
 		else if (step.kind === "loop" && step.check.kind === "code") {
-			steps.push({ id: fleetLoopCheckStepId(step.id, 1), command: step.check.command });
+			steps.push({
+				id: fleetLoopCheckStepId(step.id, 1),
+				command: step.check.command,
+				...(step.check.args ? { args: step.check.args } : {}),
+			});
 		}
 	}
 	return steps;
@@ -945,19 +976,26 @@ export class FleetCommandRegistryMissingError extends Error {
  * failure mode this whole mechanism exists to prevent: a green test phase that
  * never ran a test.
  */
-export function validateFleetCommands(contract: FleetContract, registry: FleetCommandRegistry | null): void {
+export function validateFleetCommands(
+	contract: FleetContract,
+	registry: FleetCommandRegistry | null,
+	vars?: Readonly<Record<string, string>>,
+): void {
 	const codeSteps = fleetCodeSteps(contract);
 	if (codeSteps.length === 0) return;
 	if (registry === null) {
 		throw new FleetCommandRegistryMissingError(contract.path, [...new Set(codeSteps.map((step) => step.command))].sort());
 	}
 	for (const step of codeSteps) {
-		if (!registry.commands.has(step.command)) {
+		const command = registry.commands.get(step.command);
+		if (!command) {
 			const known = [...registry.commands.keys()].sort().join(", ");
 			throw new Error(
 				`fleet contract ${contract.path}: step '${step.id}' names unknown command '${step.command}' (registered: ${known || "none"})`,
 			);
 		}
+		const args = vars === undefined ? (step.args ?? []) : resolveFleetCommandArgs(step.args ?? [], vars);
+		validateFleetCommandArgs(command, args, { allowTemplates: vars === undefined });
 	}
 }
 
@@ -971,21 +1009,48 @@ function builtinFleetsDir(): string {
 	return join(resolvePackageRoot(), "src", "domains", "agents", "fleets");
 }
 
-function fleetSources(cwd: string): ReadonlyArray<{ dir: string; source: FleetContractSource }> {
+export function resolveFleetReferences(
+	contract: FleetContract,
+	source: { source: FleetContractSource; rootPath?: string },
+): FleetContract {
+	if (!source.rootPath) return contract;
+	const context = { rootPath: source.rootPath, plugin: source.source === "plugin" };
+	// Authored text is resolved after schema parsing; paths cannot inject YAML keys.
+	return {
+		...contract,
+		body: resolvePackageReferences(contract.body, context),
+		steps: contract.steps.map((step) => {
+			if (step.kind === "code" && step.args)
+				return { ...step, args: step.args.map((arg) => resolvePackagePathReference(arg, context)) };
+			if (step.kind === "loop" && step.check.kind === "code" && step.check.args)
+				return {
+					...step,
+					check: { ...step.check, args: step.check.args.map((arg) => resolvePackagePathReference(arg, context)) },
+				};
+			return step;
+		}),
+	};
+}
+
+function fleetSources(cwd: string): ReadonlyArray<{ dir: string; source: FleetContractSource; rootPath?: string }> {
 	return [
 		{ dir: builtinFleetsDir(), source: "builtin" },
-		...enabledExtensionResourceRoots("fleets", cwd)
+		...enabledPluginResourceRoots("fleets", cwd)
 			.sort((left, right) => left.source.localeCompare(right.source))
-			.map((root) => ({ dir: root.path, source: "extension" as const })),
+			.map((root) => ({ dir: root.path, rootPath: root.rootPath, source: "plugin" as const })),
 		{ dir: join(clioConfigDir(), "fleets"), source: "user" },
 		{ dir: fleetsDir(cwd), source: "project" },
 	];
 }
 
-function fleetContractPath(cwd: string, name: string): { path: string; source: FleetContractSource } | null {
+function fleetContractPath(
+	cwd: string,
+	name: string,
+): { path: string; source: FleetContractSource; rootPath?: string } | null {
 	for (const source of [...fleetSources(cwd)].reverse()) {
 		const candidate = join(source.dir, `${name}.md`);
-		if (existsSync(candidate)) return { path: candidate, source: source.source };
+		if (existsSync(candidate))
+			return { path: candidate, source: source.source, ...(source.rootPath ? { rootPath: source.rootPath } : {}) };
 	}
 	return null;
 }
@@ -995,7 +1060,7 @@ export function loadFleetContract(cwd: string, name: string): FleetContract {
 	if (located === null) {
 		throw new Error(`fleet contract not found: ${join(fleetsDir(cwd), `${name}.md`)} (and no builtin named '${name}')`);
 	}
-	const contract = parseFleetContract(readFileSync(located.path, "utf8"), located.path);
+	const contract = resolveFleetReferences(parseFleetContract(readFileSync(located.path, "utf8"), located.path), located);
 	validateFleetCommands(contract, loadFleetCommands(cwd));
 	return contract;
 }
@@ -1027,12 +1092,15 @@ export function listFleetContracts(cwd: string): FleetContractListing[] {
 	}
 	const listings = new Map<string, FleetContractListing>();
 	const sources = fleetSources(cwd);
-	for (const { dir, source } of sources) {
+	for (const { dir, source, rootPath } of sources) {
 		for (const file of listDirectory(dir)) {
 			const path = join(dir, file);
 			const name = basename(file, ".md");
 			try {
-				const contract = parseFleetContract(readFileSync(path, "utf8"), path);
+				const contract = resolveFleetReferences(parseFleetContract(readFileSync(path, "utf8"), path), {
+					source,
+					...(rootPath ? { rootPath } : {}),
+				});
 				if (registryError !== null && fleetCodeSteps(contract).length > 0) throw new Error(registryError);
 				validateFleetCommands(contract, registry);
 				listings.set(name, { name, path, source, contract, error: null, needsCommands: null });

package/src/domains/agents/recipe.ts

@@ -131,20 +131,21 @@ export interface AgentRecipe {
 	resultContract: ResultContract;
 	product?: AgentProduct;
 	tags: ReadonlyArray<string>;
-	source: "builtin" | "extension" | "user" | "project";
+	source: "builtin" | "plugin" | "user" | "project";
 	filepath: string;
 	/** Persona prompt body. */
 	body: string;
 }
 
 export interface RecipeSource {
+	rootPath?: string;
 	dir: string;
 	source: AgentRecipe["source"];
-	/** Project root whose extension and skill resources are being discovered. */
+	/** Project root whose package and skill resources are being discovered. */
 	cwd?: string;
-	/** Stable provenance used to correlate resources from one extension. */
+	/** Stable provenance used to correlate resources from one package. */
 	origin?: string;
-	/** The declaring extension's skill root; extension agents may bind only here. */
+	/** The declaring package's skill root; package agents may bind only here. */
 	skillRoot?: string;
 }
 

package/src/domains/agents/registry.ts

@@ -1,8 +1,10 @@
 import { existsSync, readdirSync, readFileSync, realpathSync } from "node:fs";
 import path from "node:path";
+import { readSettings } from "../../core/config.js";
 import { resolvePackageRoot } from "../../core/package-root.js";
 import { clioConfigDir } from "../../core/xdg.js";
-import { enabledExtensionResourceRoots } from "../extensions/index.js";
+import { enabledPluginResourceRoots } from "../plugins/index.js";
+import { resolvePackageReferences } from "../resources/package-references.js";
 import { loadSkills } from "../resources/skills/loader.js";
 import { parseFrontmatter } from "./frontmatter.js";
 import { type AgentRecipe, type RecipeSource, recipeIdFromPath } from "./recipe.js";
@@ -15,6 +17,25 @@ export interface AgentRecipeDiagnostic {
 	source: RecipeSource["source"];
 	filepath: string;
 	message: string;
+	/**
+	 * Why a file is not in the catalog. `quarantine` is a parse/policy failure;
+	 * `ignored` is a reserved or protected id; `overridden` lost same-id
+	 * precedence to a later source. Absent on records from before this field.
+	 */
+	kind?: "quarantine" | "ignored" | "overridden";
+	/** Recipe id when it was parsed; quarantined files may not have one. */
+	id?: string;
+	/** Source that won, for `overridden`. */
+	by?: RecipeSource["source"];
+	/** Parsed audience of an ignored/overridden recipe, so listings can keep hiding internal ones. */
+	audience?: AgentRecipe["audience"];
+}
+
+/** Diagnostics are a bounded inspection aid, never a second catalog. */
+const MAX_AGENT_RECIPE_DIAGNOSTICS = 256;
+
+function recordDiagnostic(diagnostics: AgentRecipeDiagnostic[], diagnostic: AgentRecipeDiagnostic): void {
+	if (diagnostics.length < MAX_AGENT_RECIPE_DIAGNOSTICS) diagnostics.push(diagnostic);
 }
 
 function resolveBoundSkills(recipe: AgentRecipe, source: RecipeSource): AgentRecipe {
@@ -22,31 +43,35 @@ function resolveBoundSkills(recipe: AgentRecipe, source: RecipeSource): AgentRec
 	// Builtins may bind a package-owned skill. Custom recipes deliberately use
 	// only the operator's discovered skill roots; a recipe cannot smuggle an
 	// arbitrary filesystem path into worker context through a skill name.
-	const packageSkills = path.resolve(source.dir, "..", "..", "..", "..", "skills");
-	if (source.source === "extension" && source.skillRoot === undefined) {
-		throw new Error(`agent recipe: ${recipe.filepath}: extension declares bound skills but no skills resource root`);
+	const packageSkills = path.resolve(source.dir, "..", "..", "..", "..", "library", "skills");
+	if (source.source === "plugin" && source.skillRoot === undefined) {
+		throw new Error(
+			`agent recipe: ${recipe.filepath}: ${source.source} declares bound skills but no skills resource root`,
+		);
 	}
 	const skills =
-		source.source === "extension"
+		source.source === "plugin"
 			? loadSkills({
 					cwd: source.cwd ?? process.cwd(),
+					trustProjectCompatRoots: readSettings().integrations.projectResources.trustProjectImports,
 					disableDiscovery: true,
 					explicitSkillPaths: source.skillRoot === undefined ? [] : [source.skillRoot],
 				})
 			: loadSkills({
 					cwd: source.cwd ?? process.cwd(),
+					trustProjectCompatRoots: readSettings().integrations.projectResources.trustProjectImports,
 					...(source.source === "builtin" && existsSync(packageSkills) ? { explicitSkillPaths: [packageSkills] } : {}),
 				});
-	if (source.source === "extension" && source.skillRoot !== undefined) {
+	if (source.source === "plugin" && source.skillRoot !== undefined) {
 		const canonicalRoot = realpathSync(source.skillRoot);
 		for (const skill of skills.items) {
 			const relative = path.relative(canonicalRoot, realpathSync(skill.filePath));
 			if (relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
-				throw new Error(`agent recipe: ${recipe.filepath}: bound skill escapes its extension: ${skill.filePath}`);
+				throw new Error(`agent recipe: ${recipe.filepath}: bound skill escapes its ${source.source}: ${skill.filePath}`);
 			}
 		}
 	}
-	const byName = new Map(skills.items.map((skill) => [skill.name, skill.filePath]));
+	const byName = new Map(skills.items.filter((skill) => skill.trusted).map((skill) => [skill.name, skill.filePath]));
 	const missing = recipe.skills.filter((skill) => !byName.has(skill));
 	if (missing.length > 0) {
 		throw new Error(`agent recipe: ${recipe.filepath}: bound skill(s) unavailable: ${missing.join(", ")}`);
@@ -83,7 +108,11 @@ export function loadRecipesFromDir(
 		try {
 			const id = recipeIdFromPath(filepath, source.dir);
 			const raw = readFileSync(filepath, "utf8");
-			const { frontmatter, body } = parseFrontmatter(raw, filepath);
+			const { frontmatter, body: rawBody } = parseFrontmatter(raw, filepath);
+			const body = resolvePackageReferences(rawBody, {
+				...(source.rootPath ? { rootPath: source.rootPath } : {}),
+				plugin: source.source === "plugin",
+			});
 			const parsedRecipe = parseAgentRecipeSchema({ id, source: source.source, filepath, body, frontmatter });
 			const recipe = resolveBoundSkills(parsedRecipe, source);
 			// Policy validation runs before a recipe enters any catalog, prompt, or
@@ -93,7 +122,7 @@ export function loadRecipesFromDir(
 		} catch (error) {
 			if (source.source === "builtin") throw error;
 			const message = error instanceof Error ? error.message : String(error);
-			diagnostics.push({ source: source.source, filepath, message });
+			recordDiagnostic(diagnostics, { kind: "quarantine", source: source.source, filepath, message });
 			process.stderr.write(`[clio-coder:agents] quarantine path=${filepath} source=${source.source} reason=${message}\n`);
 		}
 	}
@@ -102,7 +131,21 @@ export function loadRecipesFromDir(
 	return recipes;
 }
 
-function mergeRecipes(...sources: ReadonlyArray<ReadonlyArray<AgentRecipe>>): ReadonlyArray<AgentRecipe> {
+function mergeRecipes(
+	diagnostics: AgentRecipeDiagnostic[],
+	...sources: ReadonlyArray<ReadonlyArray<AgentRecipe>>
+): ReadonlyArray<AgentRecipe> {
+	const ignored = (recipe: AgentRecipe, reason: string): void => {
+		process.stderr.write(`[clio-coder:agents] ignore id=${recipe.id} by=${recipe.source} reason=${reason}\n`);
+		recordDiagnostic(diagnostics, {
+			kind: "ignored",
+			id: recipe.id,
+			source: recipe.source,
+			audience: recipe.audience,
+			filepath: recipe.filepath,
+			message: `agent recipe ${recipe.id} from ${recipe.source} ignored: ${reason}`,
+		});
+	};
 	const byId = new Map<string, AgentRecipe>();
 	const builtinById = new Map<string, AgentRecipe>();
 	for (const group of sources) {
@@ -113,23 +156,35 @@ function mergeRecipes(...sources: ReadonlyArray<ReadonlyArray<AgentRecipe>>): Re
 	for (const group of sources) {
 		for (const recipe of group) {
 			if (recipe.source !== "builtin" && RESERVED_CUSTOM_AGENT_IDS.has(recipe.id)) {
-				process.stderr.write(`[clio-coder:agents] ignore id=${recipe.id} by=${recipe.source} reason=reserved-agent-id\n`);
+				ignored(recipe, "reserved-agent-id");
 				continue;
 			}
 			const builtin = builtinById.get(recipe.id);
-			if (recipe.source === "extension" && builtin) {
-				process.stderr.write(`[clio-coder:agents] ignore override id=${recipe.id} by=extension reason=reserved-builtin\n`);
+			if (recipe.source === "plugin" && builtin) {
+				ignored(recipe, "reserved-builtin");
 				continue;
 			}
 			if (recipe.source === "user" && builtin && isShadowAgent(normalizeAgentSpec(builtin))) {
-				process.stderr.write(`[clio-coder:agents] ignore override id=${recipe.id} by=user reason=reserved-shadow\n`);
+				ignored(recipe, "reserved-shadow");
 				continue;
 			}
 			if (recipe.source === "project" && builtin) {
-				process.stderr.write(`[clio-coder:agents] ignore override id=${recipe.id} by=project reason=reserved-builtin\n`);
+				ignored(recipe, "reserved-builtin");
 				continue;
 			}
-			if (byId.has(recipe.id)) process.stderr.write(`[clio-coder:agents] override id=${recipe.id} by=${recipe.source}\n`);
+			const previous = byId.get(recipe.id);
+			if (previous) {
+				process.stderr.write(`[clio-coder:agents] override id=${recipe.id} by=${recipe.source}\n`);
+				recordDiagnostic(diagnostics, {
+					kind: "overridden",
+					id: previous.id,
+					source: previous.source,
+					audience: previous.audience,
+					by: recipe.source,
+					filepath: previous.filepath,
+					message: `agent recipe ${previous.id} from ${previous.source} overridden by ${recipe.source}`,
+				});
+			}
 			byId.set(recipe.id, recipe);
 		}
 	}
@@ -138,9 +193,9 @@ function mergeRecipes(...sources: ReadonlyArray<ReadonlyArray<AgentRecipe>>): Re
 
 /**
  * Discover the one native-agent catalog used by listing, fleet admission, and
- * dispatch. Extension recipes occupy the same precedence slot as extension
- * fleets: after builtins and before operator/user and project recipes. Their
- * skill bindings remain constrained to the declaring extension's skill root.
+ * dispatch. Plugin recipes occupy the same precedence slot as plugin fleets:
+ * after builtins and before operator/user and project recipes. Their skill
+ * bindings remain constrained to the declaring plugin's skill root.
  */
 export function discoverAgentRecipes(
 	cwd = process.cwd(),
@@ -154,15 +209,16 @@ export function discoverAgentRecipes(
 		},
 		diagnostics,
 	);
-	const skillRoots = new Map(enabledExtensionResourceRoots("skills", cwd).map((root) => [root.source, root.path]));
-	const extensionRecipes = enabledExtensionResourceRoots("agents", cwd)
+	const skillRoots = new Map(enabledPluginResourceRoots("skills", cwd).map((root) => [root.source, root.path]));
+	const pluginRecipes = enabledPluginResourceRoots("agents", cwd)
 		.sort((left, right) => left.source.localeCompare(right.source))
 		.map((root) => {
 			const skillRoot = skillRoots.get(root.source);
 			return loadRecipesFromDir(
 				{
 					dir: root.path,
-					source: "extension",
+					source: "plugin",
+					rootPath: root.rootPath,
 					cwd,
 					origin: root.source,
 					...(skillRoot === undefined ? {} : { skillRoot }),
@@ -175,5 +231,5 @@ export function discoverAgentRecipes(
 		{ dir: path.join(cwd, ".clio-coder", "agents"), source: "project", cwd },
 		diagnostics,
 	);
-	return mergeRecipes(builtin, ...extensionRecipes, user, project);
+	return mergeRecipes(diagnostics, builtin, ...pluginRecipes, user, project);
 }

package/src/domains/config/extension.ts

@@ -116,13 +116,14 @@ export function createConfigBundle(
 		update(mutate) {
 			if (!snapshot) throw new Error("config domain not started");
 			const previous = snapshot;
-			const candidate = structuredClone(previous);
-			mutate(candidate);
-			assertAgentNamespace(candidate);
 			// Apply the effective-view delta to the user document under one lock,
 			// then validate it with the project layers before writing. In particular,
 			// a route may name a target supplied only by this workspace.
-			const normalized = updateLayeredSettings(process.cwd(), mutate);
+			const normalized = updateLayeredSettings(process.cwd(), (candidate) => {
+				const next = mutate(candidate) ?? candidate;
+				assertAgentNamespace(next);
+				return next;
+			});
 			snapshot = normalized;
 			setGitCommitAttributionEnabled(normalized.integrations.git.commitAttribution);
 			const diff = diffSettings(previous, normalized);