@introspection-ai/recipes 0.13.0 → 0.14.1

package/dist/recipe-agent.js

@@ -2,15 +2,9 @@ import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { basename, join } from "node:path";
 import { parse } from "yaml";
 import { mergeRecipeAgentModelConfig, parseRecipeAgentModelConfig, RecipeModelConfigError, } from "./recipe-model.js";
-import { isValidRecipeMcpToolSelection, packageResourcePaths, parseRecipeMcpToolSelection, readPiPackageManifest, RecipePackageError, } from "./recipe-package.js";
-import { mcpSelectionAllowsTool, normalizeMcpServerId, } from "./mcp.js";
+import { assertRecipePathContained, isValidRecipeMcpToolSelection, packageResourcePaths, parseRecipeMcpToolSelection, readPiPackageManifest, RecipePackageError, } from "./recipe-package.js";
+import { mcpSelectionAllowsTool, normalizeMcpServerId, } from "./mcp-policy.js";
 const INVALID_AGENT_MCP = Symbol("invalidAgentMcp");
-export const REQUIRED_RECIPE_AGENT_FIELDS = [
-    "model.name",
-    "model.thinkingLevel",
-    "tools",
-    "systemInstructions",
-];
 const AGENT_YAML_KEYS = new Set([
     "name",
     "from",
@@ -20,11 +14,10 @@ const AGENT_YAML_KEYS = new Set([
     "mcp",
     "skills",
     "subagents",
-    "extensions",
     "system_instructions",
-    "systemInstructions",
-    "prompt",
 ]);
+const PORTABLE_AGENT_NAME = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const MAX_INHERITANCE_DEPTH = 128;
 function asRecord(value) {
     return value && typeof value === "object" && !Array.isArray(value)
         ? value
@@ -32,9 +25,70 @@ function asRecord(value) {
 }
 function stringArray(value) {
     return Array.isArray(value)
-        ? value.filter((item) => typeof item === "string")
+        ? value
+            .filter((item) => typeof item === "string")
+            .map((item) => item.trim())
         : [];
 }
+function isNonEmptyStringArray(value) {
+    return (Array.isArray(value) &&
+        value.every((item) => typeof item === "string" && Boolean(item.trim())));
+}
+function invalidAgentField(data) {
+    if (!Object.hasOwn(data, "name")) {
+        return "name is required";
+    }
+    for (const key of ["name", "from"]) {
+        if (Object.hasOwn(data, key) &&
+            (typeof data[key] !== "string" || !data[key].trim())) {
+            return `${key} must be a non-empty string`;
+        }
+        if (Object.hasOwn(data, key) &&
+            typeof data[key] === "string" &&
+            !PORTABLE_AGENT_NAME.test(data[key])) {
+            return `${key} must use lowercase kebab-case`;
+        }
+    }
+    if (Object.hasOwn(data, "description") &&
+        typeof data.description !== "string") {
+        return "description must be a string";
+    }
+    for (const key of ["tools", "skills", "subagents"]) {
+        if (Object.hasOwn(data, key) && !isNonEmptyStringArray(data[key])) {
+            return `${key} must be an array of non-empty strings`;
+        }
+        if (Object.hasOwn(data, key) &&
+            new Set(stringArray(data[key])).size !== stringArray(data[key]).length) {
+            return `${key} must not contain duplicate entries`;
+        }
+    }
+    if (stringArray(data.tools).includes("agent")) {
+        return "tools must not declare the session-generated agent tool";
+    }
+    if (Object.hasOwn(data, "system_instructions")) {
+        const value = data.system_instructions;
+        if (!value || typeof value !== "object" || Array.isArray(value)) {
+            return "system_instructions must be an object";
+        }
+        const instructions = value;
+        const unknown = Object.keys(instructions).filter((key) => key !== "mode" && key !== "content");
+        if (unknown.length > 0) {
+            return `system_instructions has unsupported key(s): ${unknown.join(", ")}`;
+        }
+        if (typeof instructions.content !== "string") {
+            return "system_instructions.content must be a string";
+        }
+        if (!instructions.content.trim()) {
+            return "system_instructions.content must be non-empty";
+        }
+        if (Object.hasOwn(instructions, "mode") &&
+            instructions.mode !== "append" &&
+            instructions.mode !== "replace") {
+            return "system_instructions.mode must be append or replace";
+        }
+    }
+    return undefined;
+}
 function modelProjection(config) {
     if (!config)
         return undefined;
@@ -46,22 +100,48 @@ function modelProjection(config) {
     };
 }
 function parseSystemInstructions(data) {
-    const raw = asRecord(data.system_instructions ?? data.systemInstructions);
+    const raw = asRecord(data.system_instructions);
     if (Object.hasOwn(raw, "content") && typeof raw.content === "string") {
         const mode = raw.mode === "replace" ? "replace" : "append";
         return { mode, content: raw.content.trim() };
     }
-    const prompt = typeof data.prompt === "string" ? data.prompt.trim() : "";
-    return prompt ? { mode: "append", content: prompt } : undefined;
+    return undefined;
+}
+function mergeSystemInstructions(base, child) {
+    if (!base)
+        return child;
+    if (!child)
+        return base;
+    if (child.mode === "replace")
+        return child;
+    return {
+        mode: base.mode,
+        content: `${base.content}\n\n${child.content}`,
+    };
+}
+function normalizedMcpServerId(value) {
+    return (value
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9_-]+/g, "-")
+        .replace(/^-+|-+$/g, "") || "mcp");
+}
+function hasNormalizedMcpServerCollision(values) {
+    const seen = new Set();
+    for (const value of values) {
+        const normalized = normalizedMcpServerId(value);
+        if (seen.has(normalized))
+            return true;
+        seen.add(normalized);
+    }
+    return false;
 }
-function parseExtensions(data) {
-    const raw = asRecord(data.extensions);
-    const extensions = {};
-    if (Object.hasOwn(raw, "include"))
-        extensions.include = stringArray(raw.include);
-    if (Object.hasOwn(raw, "exclude"))
-        extensions.exclude = stringArray(raw.exclude);
-    return extensions.include || extensions.exclude ? extensions : undefined;
+function validActivationSelectors(selectors) {
+    if (selectors === undefined)
+        return true;
+    return (selectors.every((selector) => Boolean(selector.trim()) &&
+        (!selector.includes("*") || selector === "*")) &&
+        (!selectors.includes("*") || selectors.length === 1));
 }
 function parseMcp(data) {
     if (!Object.hasOwn(data, "mcp"))
@@ -69,11 +149,67 @@ function parseMcp(data) {
     const value = data.mcp;
     const validObject = Boolean(value) && typeof value === "object" && !Array.isArray(value);
     const raw = asRecord(value);
-    const mcp = {};
-    for (const [serverId, value] of Object.entries(raw)) {
-        mcp[serverId] = parseRecipeMcpToolSelection(value);
+    const rawServers = asRecord(raw.servers);
+    const servers = {};
+    for (const [serverId, serverValue] of Object.entries(rawServers)) {
+        const serverRaw = asRecord(serverValue);
+        servers[normalizedMcpServerId(serverId)] = {
+            ...parseRecipeMcpToolSelection(serverValue),
+            ...(Object.hasOwn(serverRaw, "defer")
+                ? {
+                    defer: stringArray(serverRaw.defer).map((selector) => selector.trim()),
+                }
+                : {}),
+            ...(Object.hasOwn(serverRaw, "eager")
+                ? {
+                    eager: stringArray(serverRaw.eager).map((selector) => selector.trim()),
+                }
+                : {}),
+        };
     }
-    if (!validObject) {
+    const mode = raw.mode === "cli" || raw.mode === "tools"
+        ? raw.mode
+        : undefined;
+    const mcp = {
+        ...(mode ? { mode } : {}),
+        servers,
+    };
+    const malformedServers = Object.entries(rawServers).some(([, serverValue]) => {
+        const server = asRecord(serverValue);
+        return (!serverValue ||
+            typeof serverValue !== "object" ||
+            Array.isArray(serverValue) ||
+            Object.keys(server).some((key) => !["include", "exclude", "defer", "eager"].includes(key)) ||
+            ["include", "exclude", "defer", "eager"].some((key) => {
+                if (!Object.hasOwn(server, key))
+                    return false;
+                const values = stringArray(server[key]);
+                return new Set(values).size !== values.length;
+            }) ||
+            ["defer", "eager"].some((key) => Object.hasOwn(server, key) &&
+                (!Array.isArray(server[key]) ||
+                    server[key].some((selector) => typeof selector !== "string"))) ||
+            !validActivationSelectors(Object.hasOwn(server, "defer")
+                ? stringArray(server.defer).map((selector) => selector.trim())
+                : undefined) ||
+            !validActivationSelectors(Object.hasOwn(server, "eager")
+                ? stringArray(server.eager).map((selector) => selector.trim())
+                : undefined) ||
+            (mode === "cli" &&
+                (Object.hasOwn(server, "defer") || Object.hasOwn(server, "eager"))));
+    });
+    const malformedStructured = malformedServers ||
+        !Object.hasOwn(raw, "servers") ||
+        (Object.hasOwn(raw, "mode") &&
+            raw.mode !== "cli" &&
+            raw.mode !== "tools") ||
+        Object.keys(rawServers).some((serverId) => !serverId.trim()) ||
+        hasNormalizedMcpServerCollision(Object.keys(rawServers)) ||
+        !raw.servers ||
+        typeof raw.servers !== "object" ||
+        Array.isArray(raw.servers) ||
+        Object.keys(raw).some((key) => !["mode", "servers"].includes(key));
+    if (!validObject || malformedStructured) {
         Object.defineProperty(mcp, INVALID_AGENT_MCP, {
             value: true,
             enumerable: false,
@@ -86,17 +222,9 @@ function mergeMcp(base, child) {
         return child;
     if (!child)
         return base;
-    const merged = { ...base };
-    for (const [serverId, childServer] of Object.entries(child)) {
-        const baseServer = base[serverId];
-        merged[serverId] = {
-            ...(baseServer?.include !== undefined ? { include: baseServer.include } : {}),
-            ...(baseServer?.exclude !== undefined ? { exclude: baseServer.exclude } : {}),
-            ...(childServer.include !== undefined ? { include: childServer.include } : {}),
-            ...(childServer.exclude !== undefined ? { exclude: childServer.exclude } : {}),
-        };
-    }
-    return merged;
+    // Capability policy is a review boundary: once a child declares `mcp`, the
+    // whole block replaces its base instead of silently retaining parent servers.
+    return child;
 }
 function readYaml(path) {
     return asRecord(parse(readFileSync(path, "utf8")));
@@ -141,14 +269,17 @@ function readRecipeAgentSources(recipeDir, opts = {}) {
     const sources = [];
     for (const path of recipeAgentFiles(recipeDir)) {
         const data = readYaml(path);
-        const fallbackName = basename(path).replace(/\.ya?ml$/i, "");
-        const explicitName = typeof data.name === "string" && Boolean(data.name.trim());
-        const name = explicitName ? data.name.trim() : fallbackName;
         const unknownKeys = Object.keys(data).filter((key) => !AGENT_YAML_KEYS.has(key));
         if (unknownKeys.length > 0) {
             opts.onInvalidFile?.(path, new Error(`Agent YAML at ${path} has unsupported key(s): ${unknownKeys.join(", ")}`));
             continue;
         }
+        const fieldError = invalidAgentField(data);
+        if (fieldError) {
+            opts.onInvalidFile?.(path, new Error(`Agent YAML at ${path}: ${fieldError}`));
+            continue;
+        }
+        const name = data.name;
         let modelConfig;
         try {
             modelConfig = parseRecipeAgentModelConfig(`Agent YAML at ${path}`, data.model);
@@ -160,11 +291,9 @@ function readRecipeAgentSources(recipeDir, opts = {}) {
             continue;
         }
         sources.push({
-            fallbackName,
-            explicitName,
             definition: {
                 name,
-                from: typeof data.from === "string" && data.from.trim() ? data.from.trim() : undefined,
+                from: typeof data.from === "string" ? data.from : undefined,
                 description: typeof data.description === "string" ? data.description : undefined,
                 model: modelProjection(modelConfig),
                 modelConfig,
@@ -172,53 +301,40 @@ function readRecipeAgentSources(recipeDir, opts = {}) {
                 mcp: parseMcp(data),
                 skills: Object.hasOwn(data, "skills") ? stringArray(data.skills) : undefined,
                 subagents: Object.hasOwn(data, "subagents") ? stringArray(data.subagents) : undefined,
-                extensions: parseExtensions(data),
                 systemInstructions: parseSystemInstructions(data),
+                declaredFields: [
+                    "description",
+                    "model",
+                    "tools",
+                    "mcp",
+                    "skills",
+                    "subagents",
+                    "system_instructions",
+                ].filter((key) => Object.hasOwn(data, key)),
             },
         });
     }
     return sources;
 }
-export function loadRecipeAgentDefinitions(recipeDir) {
+function definitionsFromSources(sources) {
     const rawDefinitions = new Map();
-    const aliases = new Map();
     const resolvedDefinitions = new Map();
     const definitions = new Map();
-    const sources = readRecipeAgentSources(recipeDir, {
-        onInvalidFile: (path, error) => {
-            console.warn(`[recipes] skipping ${path}: ${error.message}`);
-        },
-    });
     for (const source of sources) {
         rawDefinitions.set(source.definition.name, source.definition);
-        aliases.set(source.fallbackName, source.definition.name);
-    }
-    function resolveName(name) {
-        return rawDefinitions.has(name) ? name : aliases.get(name) ?? name;
-    }
-    function mergeExtensions(base, child) {
-        if (!base)
-            return child;
-        if (!child)
-            return base;
-        return {
-            ...(base.include ? { include: base.include } : {}),
-            ...(base.exclude ? { exclude: base.exclude } : {}),
-            ...(child.include ? { include: child.include } : {}),
-            ...(child.exclude ? { exclude: child.exclude } : {}),
-        };
     }
     function resolveDefinition(name, stack = []) {
-        const resolvedName = resolveName(name);
-        if (resolvedDefinitions.has(resolvedName))
-            return resolvedDefinitions.get(resolvedName);
-        if (stack.includes(resolvedName))
+        if (resolvedDefinitions.has(name))
+            return resolvedDefinitions.get(name);
+        if (stack.length >= MAX_INHERITANCE_DEPTH)
             return undefined;
-        const raw = rawDefinitions.get(resolvedName);
+        if (stack.includes(name))
+            return undefined;
+        const raw = rawDefinitions.get(name);
         if (!raw)
             return undefined;
         const base = raw.from
-            ? resolveDefinition(raw.from, [...stack, resolvedName])
+            ? resolveDefinition(raw.from, [...stack, name])
             : undefined;
         if (raw.from && !base)
             return undefined;
@@ -233,183 +349,128 @@ export function loadRecipeAgentDefinitions(recipeDir) {
             mcp: mergeMcp(base?.mcp, raw.mcp),
             skills: raw.skills ?? base?.skills ?? [],
             subagents: raw.subagents ?? base?.subagents ?? [],
-            skillsDeclared: raw.skills !== undefined || base?.skillsDeclared === true,
-            subagentsDeclared: raw.subagents !== undefined || base?.subagentsDeclared === true,
-            extensions: mergeExtensions(base?.extensions, raw.extensions),
-            systemInstructions: raw.systemInstructions ?? base?.systemInstructions,
+            systemInstructions: mergeSystemInstructions(base?.systemInstructions, raw.systemInstructions),
+            declaredFields: [...(raw.declaredFields ?? [])],
         };
-        resolvedDefinitions.set(resolvedName, definition);
+        resolvedDefinitions.set(name, definition);
         return definition;
     }
     for (const name of rawDefinitions.keys()) {
         const definition = resolveDefinition(name);
-        if (!definition) {
-            console.warn(`[recipes] skipping agent "${name}": ${fromChainSkipReason(name, rawDefinitions, resolveName)}`);
+        if (!definition)
             continue;
-        }
         definitions.set(name, definition);
     }
-    for (const [alias, name] of aliases) {
-        if (definitions.has(alias))
-            continue;
-        const definition = definitions.get(name);
-        if (definition)
-            definitions.set(alias, definition);
-    }
     return definitions;
 }
-/** Explain why an agent's from: chain failed to resolve (cycle or missing base). */
-function fromChainSkipReason(name, rawDefinitions, resolveName) {
-    const stack = [];
-    let current = resolveName(name);
-    for (;;) {
-        const raw = rawDefinitions.get(current);
-        if (!raw?.from)
-            return "from: chain failed to resolve";
-        const next = resolveName(raw.from);
-        if (!rawDefinitions.has(next)) {
-            return `from: "${raw.from}" does not exist in the recipe`;
-        }
-        if (stack.includes(next) || next === current) {
-            return `from: cycle detected (${[...stack, current, next].join(" -> ")})`;
-        }
-        stack.push(current);
-        current = next;
-    }
-}
-function recipeAgentFieldProvided(definition, field) {
-    if (field === "model.name")
-        return Boolean(definition.model?.name);
-    if (field === "model.thinkingLevel")
-        return Boolean(definition.model?.thinkingLevel);
-    if (field === "tools")
-        return definition.tools !== undefined;
-    if (field === "skills")
-        return definition.skills !== undefined;
-    if (field === "subagents")
-        return definition.subagents !== undefined;
-    return definition.systemInstructions !== undefined;
-}
-export function validateResolvedRecipeAgentDefinition(opts) {
+function validateResolvedRecipeAgentSource(opts, sources) {
     const rawDefinitions = new Map();
-    const aliases = new Map();
-    const explicitNames = new Map();
-    for (const source of readRecipeAgentSources(opts.recipeDir)) {
+    for (const source of sources) {
         rawDefinitions.set(source.definition.name, source.definition);
-        aliases.set(source.fallbackName, source.definition.name);
-        explicitNames.set(source.definition.name, source.explicitName);
-    }
-    function resolveName(name) {
-        return rawDefinitions.has(name) ? name : aliases.get(name) ?? name;
     }
     function inheritanceFinding(name, stack = []) {
-        const resolvedName = resolveName(name);
-        const definition = rawDefinitions.get(resolvedName);
+        if (stack.length >= MAX_INHERITANCE_DEPTH) {
+            return {
+                agentName: name,
+                field: "from",
+                message: `Recipe agent "${name}" exceeds the maximum from depth of ${MAX_INHERITANCE_DEPTH}`,
+            };
+        }
+        const definition = rawDefinitions.get(name);
         if (!definition) {
             return {
-                agentName: resolvedName,
+                agentName: name,
                 field: "from",
-                message: `Recipe agent "${resolvedName}" was not found`,
+                message: `Recipe agent "${name}" was not found`,
             };
         }
         if (!definition.from)
             return undefined;
-        const resolvedFrom = resolveName(definition.from);
+        const resolvedFrom = definition.from;
         if (stack.includes(resolvedFrom)) {
             return {
-                agentName: resolvedName,
+                agentName: name,
                 field: "from",
-                message: `Recipe agent "${resolvedName}" has cyclic from chain: ${[
+                message: `Recipe agent "${name}" has cyclic from chain: ${[
                     ...stack,
-                    resolvedName,
+                    name,
                     resolvedFrom,
                 ].join(" -> ")}`,
             };
         }
         if (!rawDefinitions.has(resolvedFrom)) {
             return {
-                agentName: resolvedName,
+                agentName: name,
                 field: "from",
-                message: `Recipe agent "${resolvedName}" inherits from missing agent "${definition.from}"`,
+                message: `Recipe agent "${name}" inherits from missing agent "${definition.from}"`,
             };
         }
-        return inheritanceFinding(definition.from, [...stack, resolvedName]);
+        return inheritanceFinding(definition.from, [...stack, name]);
     }
-    function resolvedFieldProvided(name, field, stack = []) {
-        const resolvedName = resolveName(name);
-        if (stack.includes(resolvedName))
+    function resolvedModelProvided(name, stack = []) {
+        if (stack.includes(name) ||
+            stack.length >= MAX_INHERITANCE_DEPTH)
             return false;
-        const definition = rawDefinitions.get(resolvedName);
+        const definition = rawDefinitions.get(name);
         if (!definition)
             return false;
-        if (recipeAgentFieldProvided(definition, field))
+        if (definition.model?.name)
             return true;
         return definition.from
-            ? resolvedFieldProvided(definition.from, field, [...stack, resolvedName])
+            ? resolvedModelProvided(definition.from, [...stack, name])
             : false;
     }
     function resolvedTools(name, stack = []) {
-        const resolvedName = resolveName(name);
-        if (stack.includes(resolvedName))
+        if (stack.includes(name) ||
+            stack.length >= MAX_INHERITANCE_DEPTH)
             return undefined;
-        const definition = rawDefinitions.get(resolvedName);
+        const definition = rawDefinitions.get(name);
         if (!definition)
             return undefined;
         if (definition.tools !== undefined)
             return definition.tools;
         return definition.from
-            ? resolvedTools(definition.from, [...stack, resolvedName])
+            ? resolvedTools(definition.from, [...stack, name])
             : undefined;
     }
     function resolvedMcp(name, stack = []) {
-        const resolvedName = resolveName(name);
-        if (stack.includes(resolvedName))
+        if (stack.includes(name) ||
+            stack.length >= MAX_INHERITANCE_DEPTH)
             return undefined;
-        const definition = rawDefinitions.get(resolvedName);
+        const definition = rawDefinitions.get(name);
         if (!definition)
             return undefined;
         const base = definition.from
-            ? resolvedMcp(definition.from, [...stack, resolvedName])
+            ? resolvedMcp(definition.from, [...stack, name])
             : undefined;
         return mergeMcp(base, definition.mcp);
     }
     function rawMcpChainInvalid(name, stack = []) {
-        const resolvedName = resolveName(name);
-        if (stack.includes(resolvedName))
+        if (stack.includes(name) ||
+            stack.length >= MAX_INHERITANCE_DEPTH)
             return false;
-        const definition = rawDefinitions.get(resolvedName);
+        const definition = rawDefinitions.get(name);
         if (!definition)
             return false;
         const rawMcp = definition.mcp;
         if (rawMcp?.[INVALID_AGENT_MCP] ||
-            Object.values(rawMcp ?? {}).some((selection) => !isValidRecipeMcpToolSelection(selection))) {
+            Object.values(rawMcp?.servers ?? {}).some((selection) => !isValidRecipeMcpToolSelection(selection))) {
             return true;
         }
         return definition.from
-            ? rawMcpChainInvalid(definition.from, [...stack, resolvedName])
+            ? rawMcpChainInvalid(definition.from, [...stack, name])
             : false;
     }
-    const agentName = resolveName(opts.agentName);
+    const agentName = opts.agentName;
     const findings = [];
-    if (opts.requireExplicitName && explicitNames.get(agentName) !== true) {
-        findings.push({
-            agentName,
-            field: "name",
-            severity: "warning",
-            message: `Recipe agent "${agentName}" must declare name`,
-        });
-    }
     const inheritance = inheritanceFinding(agentName);
     if (inheritance)
         findings.push(inheritance);
-    for (const field of opts.requiredFields ?? []) {
-        if (resolvedFieldProvided(agentName, field))
-            continue;
+    if (!resolvedModelProvided(agentName)) {
         findings.push({
             agentName,
-            field,
-            ...(field === "model.name" ? {} : { severity: "warning" }),
-            message: `Recipe agent "${agentName}" must declare ${field} directly or inherit it with from`,
+            field: "model.name",
+            message: `Recipe agent "${agentName}" must declare model.name directly or inherit it with from`,
         });
     }
     const mcp = resolvedMcp(agentName);
@@ -420,10 +481,10 @@ export function validateResolvedRecipeAgentDefinition(opts) {
             server.tools,
         ]))
         : undefined;
-    // Rust recipe-check owns detailed authoring diagnostics. This runtime guard
+    // The Recipe checker owns detailed authoring diagnostics. This session guard
     // only ensures malformed raw policies fail closed before agent startup.
     const invalidMcpPolicy = rawMcpChainInvalid(agentName) ||
-        Object.entries(mcp ?? {}).some(([serverId, selection]) => {
+        Object.entries(mcp?.servers ?? {}).some(([serverId, selection]) => {
             if (!serverId.trim() || !isValidRecipeMcpToolSelection(selection)) {
                 return true;
             }
@@ -436,17 +497,25 @@ export function validateResolvedRecipeAgentDefinition(opts) {
                 const value = toolName.trim();
                 return value !== "*" && !mcpSelectionAllowsTool(packageSelection, value);
             });
-        });
+        }) ||
+        Object.values(mcp?.servers ?? {}).some((selection) => (mcp?.mode !== "tools" &&
+            (selection.defer !== undefined || selection.eager !== undefined)) ||
+            !validActivationSelectors(selection.defer) ||
+            !validActivationSelectors(selection.eager) ||
+            [...(selection.defer ?? []), ...(selection.eager ?? [])].some((selector) => selector !== "*" && !mcpSelectionAllowsTool(selection, selector)));
     if (invalidMcpPolicy) {
         findings.push({
             agentName,
             field: "mcp",
             code: "mcp_invalid",
-            message: `Recipe agent "${agentName}" has an invalid MCP policy; run introspection check for details`,
+            message: `Recipe agent "${agentName}" has an invalid MCP policy`,
         });
     }
     return findings;
 }
+export function validateResolvedRecipeAgentDefinition(opts) {
+    return validateResolvedRecipeAgentSource(opts, readRecipeAgentSources(opts.recipeDir));
+}
 function isValidRecipeModelSpec(spec) {
     const slash = spec.indexOf("/");
     if (slash <= 0 || slash === spec.length - 1)
@@ -470,15 +539,11 @@ function validateRecipeAgentModelSpecs(sources) {
 }
 function validateRecipeAgentNames(sources) {
     const findings = [];
-    const explicitNameCounts = new Map();
-    const explicitNames = new Set();
+    const nameCounts = new Map();
     for (const source of sources) {
-        if (!source.explicitName)
-            continue;
-        explicitNames.add(source.definition.name);
-        explicitNameCounts.set(source.definition.name, (explicitNameCounts.get(source.definition.name) ?? 0) + 1);
+        nameCounts.set(source.definition.name, (nameCounts.get(source.definition.name) ?? 0) + 1);
     }
-    for (const [name, count] of explicitNameCounts) {
+    for (const [name, count] of nameCounts) {
         if (count <= 1)
             continue;
         findings.push({
@@ -487,20 +552,27 @@ function validateRecipeAgentNames(sources) {
             message: `Recipe agent name "${name}" is declared by multiple files`,
         });
     }
-    for (const source of sources) {
-        if (source.fallbackName === source.definition.name ||
-            !explicitNames.has(source.fallbackName)) {
-            continue;
-        }
-        findings.push({
-            agentName: source.definition.name,
-            field: "name",
-            message: `Recipe agent file alias "${source.fallbackName}" conflicts with an explicit agent name`,
-        });
-    }
     return findings;
 }
-export function validateRecipeAgentDefinitions(recipeDir) {
+function validateRecipeAgentSources(recipeDir, sources, invalidFileFindings) {
+    const agentNames = [
+        ...new Set(sources.map((source) => source.definition.name)),
+    ].sort();
+    return [
+        ...invalidFileFindings,
+        ...validateRecipeAgentNames(sources),
+        ...validateRecipeAgentModelSpecs(sources),
+        ...agentNames.flatMap((agentName) => validateResolvedRecipeAgentSource({
+            recipeDir,
+            agentName,
+        }, sources)),
+    ];
+}
+/**
+ * Parse agent YAML once, then validate and resolve the complete inheritance
+ * Recipe snapshot from that exact source.
+ */
+export function loadValidatedRecipeAgentDefinitions(recipeDir) {
     const invalidFileFindings = [];
     const sources = readRecipeAgentSources(recipeDir, {
         onInvalidFile: (path, error) => {
@@ -511,44 +583,20 @@ export function validateRecipeAgentDefinitions(recipeDir) {
             });
         },
     });
-    const agentNames = [...new Set(sources.map((source) => source.definition.name))].sort();
-    return [
-        ...invalidFileFindings,
-        ...validateRecipeAgentNames(sources),
-        ...validateRecipeAgentModelSpecs(sources),
-        ...agentNames.flatMap((agentName) => validateResolvedRecipeAgentDefinition({
-            recipeDir,
-            agentName,
-            requireExplicitName: true,
-            requiredFields: REQUIRED_RECIPE_AGENT_FIELDS,
-        })),
-    ];
-}
-export function resolveRecipeAgentName(opts) {
-    if (opts.agentName?.trim())
-        return opts.agentName.trim();
-    const definitions = loadRecipeAgentDefinitions(opts.recipeDir);
-    const defaultAgent = definitions.get("agent");
-    if (defaultAgent)
-        return defaultAgent.name;
-    const uniqueNames = [
-        ...new Set([...definitions.values()].map((definition) => definition.name)),
-    ];
-    if (uniqueNames.length === 1)
-        return uniqueNames[0];
-    if (uniqueNames.length === 0)
-        return "agent";
-    throw new Error("Recipe has multiple agents and no default entrypoint; add agents/agent.yaml or set PI_AGENT_NAME");
+    const definitions = definitionsFromSources(sources);
+    return {
+        definitions,
+        findings: validateRecipeAgentSources(recipeDir, sources, invalidFileFindings),
+    };
 }
-export function resolveRecipeAgentDefinition(opts) {
-    const agentName = resolveRecipeAgentName(opts);
-    const agent = loadRecipeAgentDefinitions(opts.recipeDir).get(agentName) ?? null;
-    return { agentName, agent };
+export function validateRecipeAgentDefinitions(recipeDir) {
+    return loadValidatedRecipeAgentDefinitions(recipeDir).findings;
 }
 export function loadRecipeSystemPrompt(recipeDir) {
     const path = join(recipeDir, "SYSTEM.md");
     if (!existsSync(path))
         return undefined;
+    assertRecipePathContained(recipeDir, path, "SYSTEM.md");
     const content = readFileSync(path, "utf8").trim();
     return content || undefined;
 }