@llblab/pi-actors 0.36.0 → 0.37.0

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## Unreleased
 
+## 0.37.0: Direct Recipe Delegation And Quiet Overrides
+
+- `[Recipes]` Added direct recipe delegation from `template` strings so thin wrappers can point at ready recipe names/paths while preserving priority resolution, inherited metadata, and import-based composition for richer graphs.
+- `[Command Templates]` Fixed inherited/default placeholder resolution for arrays and repeat-indexed values, unblocking lens-swarm recipes that pass `lenses` through wrapper defaults into `{lenses.length}` and `{lenses[index]}`.
+- `[Registry]` Stopped treating same-name recipe/tool registration as a startup warning: higher-priority user recipes now quietly override lower-priority recipe/tool definitions as normal composition behavior, while reserved core tool names remain protected.
+
 ## 0.36.0: Recipe Diagnostics And Runtime Triage
 
 - `[Recipe Doctor]` Added deterministic advisory risk labels for discovered recipes, including shell, eval, filesystem mutation, network, external side effect, long-running, platform-specific, and secret-touching signals in verbose recipe inspection plus compact doctor risk counts.

package/dist/index.js

@@ -88,7 +88,6 @@ export default function toolRegistryExtension(pi) {
         configPath: Paths.EXTENSION_RUNTIME_PATHS.configPath,
         exec: CommandTemplates.execCommandTemplate,
         getActiveTools: () => pi.getActiveTools(),
-        getAllTools: () => pi.getAllTools(),
         registerTool: (definition) => {
             actorToolDefinitions.set(definition.name, definition);
             pi.registerTool(definition);

package/dist/lib/async-runs.js

@@ -20,7 +20,7 @@ import * as RunsStart from "./runs-start.js";
 import * as RunsIndex from "./runs-index.js";
 import { claimRunInboxMessageInStateDir, parseRunInboxLine, processRunInboxMessagesInStateDir, runInboxFile, updateRunInboxMessageStatusInStateDir, } from "./runs-mailbox.js";
 import { deliverRunMessage, } from "./runs-messages.js";
-import { buildRunStatus, tailFile, tailLines, } from "./runs-status.js";
+import { buildRunStatus, tailFile, tailLines } from "./runs-status.js";
 import { readJsonFileResilient } from "./state-readers.js";
 const RUNNER_IDENTITY_GRACE_MS = 5000;
 const DEFAULT_STATE_ROOT = Paths.getRunStateRoot();
@@ -77,8 +77,9 @@ function assertNoActiveRunState(stateDir) {
     RunsStart.assertNoActiveRunState(stateDir, readJson, RUNNER_PATH);
 }
 function resolveRecipeFile(file) {
-    return (RecipesReferences.getRecipePath(file, DEFAULT_RECIPE_ROOT) ??
-        RecipesReferences.resolveRecipePath(file, DEFAULT_RECIPE_ROOT));
+    return (RecipesReferences.resolveRecipeReferencePath(file, Paths.getRecipeRoot()) ??
+        RecipesReferences.getRecipePath(file, Paths.getRecipeRoot()) ??
+        RecipesReferences.resolveRecipePath(file, Paths.getRecipeRoot()));
 }
 function isMutableUsageRecipeFile(file) {
     const userRoot = resolve(DEFAULT_RECIPE_ROOT);

package/dist/lib/command-templates.js

@@ -44,18 +44,32 @@ function normalizeCommandTemplateDefaults(defaults) {
     return normalized;
 }
 export function resolveInheritedDefaultReferences(ownDefaults, inheritedDefaults, runtimeValues = {}) {
-    if (!ownDefaults || !inheritedDefaults)
+    if (!ownDefaults)
         return ownDefaults;
     const resolved = { ...ownDefaults };
+    const values = { ...(inheritedDefaults ?? {}), ...runtimeValues };
     for (const [key, value] of Object.entries(ownDefaults)) {
         if (typeof value !== "string")
             continue;
         const exact = /^\{([A-Za-z_][A-Za-z0-9_-]*)\}$/.exec(value);
-        if (!exact ||
-            Object.hasOwn(runtimeValues, exact[1]) ||
-            !Object.hasOwn(inheritedDefaults, exact[1]))
+        if (exact && Object.hasOwn(values, exact[1])) {
+            resolved[key] = values[exact[1]];
             continue;
-        resolved[key] = inheritedDefaults[exact[1]];
+        }
+        const indexed = value.match(/^\{([A-Za-z_][A-Za-z0-9_-]*)\[([A-Za-z_][A-Za-z0-9_-]*|\d+)\]\}$/);
+        if (!indexed)
+            continue;
+        const source = values[indexed[1]];
+        const indexValue = /^\d+$/.test(indexed[2])
+            ? indexed[2]
+            : values[indexed[2]];
+        const index = Number(indexValue);
+        if (Array.isArray(source) &&
+            Number.isInteger(index) &&
+            index >= 0 &&
+            index < source.length) {
+            resolved[key] = source[index] ?? "";
+        }
     }
     return resolved;
 }

package/dist/lib/recipes-references.d.ts

@@ -65,6 +65,7 @@ export interface ReadResolvedRecipeConfigOptions {
     includeActorRecipeContext?: boolean;
 }
 export declare function resolveRecipePath(value: string, recipeRoot?: string): string;
+export declare function resolveRecipeReferencePath(value: unknown, currentRecipeRoot?: string): string | undefined;
 export declare function getRecipePath(value: unknown, recipeRoot?: string): string | undefined;
 export declare function diagnoseRawRecipeConfigFailure(path: string): string | undefined;
 export declare function readRawRecipeConfig(path: string): Record<string, unknown> | undefined;

package/dist/lib/recipes-references.js

@@ -40,19 +40,43 @@ function recipeNameFiles(value) {
         return [trimmed];
     return [`${trimmed}.json`, `${trimmed}.md`];
 }
-function resolveRecipeImportPath(value, currentRecipeRoot) {
+function recipeCandidatePaths(value, currentRecipeRoot) {
     if (!isBareRecipeName(value))
-        return resolveRecipePath(value, currentRecipeRoot);
+        return [resolveRecipePath(value, currentRecipeRoot)];
     const roots = [
         Paths.getRecipeRoot(),
         currentRecipeRoot,
         Paths.getPackagedRecipeRoot(),
     ];
-    const candidates = [
+    return [
         ...new Set(roots.flatMap((root) => recipeNameFiles(value).map((file) => resolve(root, file)))),
     ];
+}
+function resolveRecipeImportPath(value, currentRecipeRoot) {
+    const candidates = recipeCandidatePaths(value, currentRecipeRoot);
     return candidates.find((candidate) => existsSync(candidate)) ?? candidates[0];
 }
+export function resolveRecipeReferencePath(value, currentRecipeRoot = Paths.getRecipeRoot()) {
+    if (typeof value !== "string")
+        return undefined;
+    const trimmed = value.trim();
+    if (!trimmed || hasWhitespace(trimmed))
+        return undefined;
+    for (const path of recipeCandidatePaths(trimmed, currentRecipeRoot)) {
+        if (!existsSync(path))
+            continue;
+        try {
+            const raw = readRawRecipeConfig(path);
+            if (raw && typeof raw === "object" && Object.hasOwn(raw, "template"))
+                return path;
+            return path;
+        }
+        catch {
+            return path;
+        }
+    }
+    return undefined;
+}
 export function getRecipePath(value, recipeRoot = Paths.getRecipeRoot()) {
     if (typeof value !== "string")
         return undefined;
@@ -61,20 +85,7 @@ export function getRecipePath(value, recipeRoot = Paths.getRecipeRoot()) {
         return undefined;
     if (trimmed.endsWith(".json") || trimmed.endsWith(".md"))
         return resolveRecipePath(trimmed, recipeRoot);
-    const jsonPath = resolveRecipePath(trimmed, recipeRoot);
-    const mdPath = resolveRecipePath(`${trimmed}.md`, recipeRoot);
-    const path = existsSync(jsonPath) ? jsonPath : mdPath;
-    if (!existsSync(path))
-        return undefined;
-    try {
-        const raw = readRawRecipeConfig(path);
-        return raw && typeof raw === "object" && Object.hasOwn(raw, "template")
-            ? path
-            : undefined;
-    }
-    catch {
-        return undefined;
-    }
+    return resolveRecipeReferencePath(trimmed, recipeRoot);
 }
 function isImportNode(value) {
     if (!isRecord(value) || Object.hasOwn(value, "template"))
@@ -344,7 +355,7 @@ export function getRecipeIdFromPath(file) {
     return basename(file, extname(file));
 }
 function readRecipeConfig(value) {
-    const path = getRecipePath(value);
+    const path = resolveRecipeReferencePath(value);
     return path ? readResolvedRecipeConfig(path) : undefined;
 }
 function isRecord(value) {
@@ -483,6 +494,7 @@ function mergeDefaults(...items) {
 function applyDefaultsToTemplate(template, defaults, overrides) {
     const cleanOverrides = { ...overrides };
     delete cleanOverrides.name;
+    delete cleanOverrides.template;
     delete cleanOverrides.values;
     if (typeof template === "object" && !Array.isArray(template)) {
         return {
@@ -509,6 +521,56 @@ function withActorRecipeContext(value, context) {
     }
     return { actorRecipeContext: context, template: value };
 }
+function loadDelegatedRecipe(value, currentRecipeFile, stack, options) {
+    const path = resolveRecipeReferencePath(value, dirname(currentRecipeFile));
+    if (!path)
+        return undefined;
+    const config = readResolvedRecipeConfig(path, [...stack, currentRecipeFile], options);
+    if (!config)
+        throw new Error(`Template recipe must define template: ${path}`);
+    if (config.disabled === true)
+        throw new Error(`Template recipe is disabled: ${path}`);
+    return config;
+}
+function applyDelegatedRecipeToNode(delegated, overrides = {}) {
+    return applyDefaultsToTemplate(delegated.template, delegated.values, overrides);
+}
+function expandRecipeDelegations(value, currentRecipeFile, stack, options = {}) {
+    if (typeof value === "string") {
+        const delegated = loadDelegatedRecipe(value, currentRecipeFile, stack, options);
+        return delegated ? applyDelegatedRecipeToNode(delegated) : value;
+    }
+    if (Array.isArray(value)) {
+        return value.map((item) => expandRecipeDelegations(item, currentRecipeFile, stack, options));
+    }
+    const record = value;
+    if (typeof record.template === "string") {
+        const delegated = loadDelegatedRecipe(record.template, currentRecipeFile, stack, options);
+        if (delegated)
+            return applyDelegatedRecipeToNode(delegated, record);
+    }
+    if (Array.isArray(record.template)) {
+        return {
+            ...record,
+            template: record.template.map((item) => expandRecipeDelegations(item, currentRecipeFile, stack, options)),
+        };
+    }
+    if (record.template && typeof record.template === "object") {
+        return {
+            ...record,
+            template: expandRecipeDelegations(record.template, currentRecipeFile, stack, options),
+        };
+    }
+    return value;
+}
+function getDirectDelegatedRecipe(value, currentRecipeFile, stack, options = {}) {
+    if (typeof value === "string")
+        return loadDelegatedRecipe(value, currentRecipeFile, stack, options);
+    if (!Array.isArray(value) && typeof value.template === "string") {
+        return loadDelegatedRecipe(value.template, currentRecipeFile, stack, options);
+    }
+    return undefined;
+}
 function expandImportNodes(value, imports, options = {}) {
     if (typeof value === "string")
         return value;
@@ -585,7 +647,14 @@ export function readResolvedRecipeConfig(file, stack = [], options = {}) {
     const template = getRecipeCommandTemplate(substituted);
     if (!template)
         return undefined;
-    const expandedTemplate = expandImportNodes(template, imports, options);
+    const expandedImportsTemplate = expandImportNodes(template, imports, options);
+    const delegated = getDirectDelegatedRecipe(expandedImportsTemplate, path, stack, options);
+    const expandedTemplate = delegated
+        ? applyDelegatedRecipeToNode(delegated, typeof expandedImportsTemplate === "object" &&
+            !Array.isArray(expandedImportsTemplate)
+            ? expandedImportsTemplate
+            : {})
+        : expandRecipeDelegations(expandedImportsTemplate, path, stack, options);
     const recipeName = getRecipeIdFromPath(path);
     const templateWithContext = options.includeActorRecipeContext
         ? withActorRecipeContext(expandedTemplate, {
@@ -595,33 +664,50 @@ export function readResolvedRecipeConfig(file, stack = [], options = {}) {
             role: stack.length > 0 ? "import" : "entry",
         })
         : expandedTemplate;
+    const mergedDefaults = mergeDefaults(delegated?.defaults, isRecord(substituted.defaults) ? substituted.defaults : undefined);
+    const artifactSource = isRecord(substituted.artifacts)
+        ? substituted.artifacts
+        : delegated?.artifacts;
+    const mailboxSource = isRecord(substituted.mailbox)
+        ? substituted.mailbox
+        : delegated?.mailbox;
     return {
         name: recipeName,
         ...(typeof substituted.description === "string" &&
             substituted.description.trim()
             ? { description: substituted.description.trim() }
-            : {}),
+            : typeof delegated?.description === "string"
+                ? { description: delegated.description }
+                : {}),
         ...(typeof substituted.disabled === "boolean"
             ? { disabled: substituted.disabled }
-            : {}),
+            : typeof delegated?.disabled === "boolean"
+                ? { disabled: delegated.disabled }
+                : {}),
         ...(substituted.async === true
             ? { async: true }
             : substituted.async === false
                 ? { async: false }
-                : {}),
+                : delegated?.async === true
+                    ? { async: true }
+                    : delegated?.async === false
+                        ? { async: false }
+                        : {}),
         ...(typeof substituted.state_dir === "string"
             ? { state_dir: substituted.state_dir }
-            : {}),
+            : typeof delegated?.state_dir === "string"
+                ? { state_dir: delegated.state_dir }
+                : {}),
         ...(Object.keys(imports).length > 0
             ? { imports: getRecipeImports(raw) }
             : {}),
         template: templateWithContext,
         ...(Array.isArray(substituted.args)
             ? { args: substituted.args }
-            : {}),
-        ...(isRecord(substituted.defaults)
-            ? { defaults: substituted.defaults }
-            : {}),
+            : Array.isArray(delegated?.args)
+                ? { args: delegated.args }
+                : {}),
+        ...(mergedDefaults ? { defaults: mergedDefaults } : {}),
         ...(typeof substituted.parallel === "boolean"
             ? { parallel: substituted.parallel }
             : {}),
@@ -643,30 +729,31 @@ export function readResolvedRecipeConfig(file, stack = [], options = {}) {
         ...(typeof substituted.output === "string"
             ? { output: substituted.output }
             : {}),
-        ...(isRecord(substituted.artifacts)
+        ...(isRecord(artifactSource)
             ? {
-                artifacts: Object.fromEntries(Object.entries(substituted.artifacts).filter((entry) => typeof entry[1] === "string")),
+                artifacts: Object.fromEntries(Object.entries(artifactSource).filter((entry) => typeof entry[1] === "string")),
             }
             : {}),
-        ...(isRecord(substituted.mailbox)
+        ...(isRecord(mailboxSource)
             ? {
                 mailbox: {
-                    ...(Array.isArray(substituted.mailbox.accepts)
+                    ...(Array.isArray(mailboxSource.accepts)
                         ? {
-                            accepts: substituted.mailbox.accepts.filter((value) => typeof value === "string" ||
+                            accepts: mailboxSource.accepts.filter((value) => typeof value === "string" ||
                                 (isRecord(value) && typeof value.type === "string")),
                         }
                         : {}),
-                    ...(Array.isArray(substituted.mailbox.emits)
+                    ...(Array.isArray(mailboxSource.emits)
                         ? {
-                            emits: substituted.mailbox.emits.filter((value) => typeof value === "string" ||
+                            emits: mailboxSource.emits.filter((value) => typeof value === "string" ||
                                 (isRecord(value) && typeof value.type === "string")),
                         }
                         : {}),
                 },
             }
             : {}),
-        ...(substituted.retire_when === "children_terminal"
+        ...(substituted.retire_when === "children_terminal" ||
+            delegated?.retire_when === "children_terminal"
             ? { retire_when: "children_terminal" }
             : {}),
         ...(typeof substituted.retry === "number" ||

package/dist/lib/registry.d.ts

@@ -39,7 +39,7 @@ export interface RegisterToolResult {
 export interface RegisterToolRuntimeDeps<TContext> {
     configPath: string;
     recipeRoot?: string;
-    getExternalToolConflict: (name: string) => string | undefined;
+    getToolNameBlocker: (name: string) => string | undefined;
     getTools: () => Map<string, Config.RegisteredTool>;
     getActiveTools: () => string[];
     notify: (ctx: TContext, message: string, type: "info" | "warning" | "error") => void;

package/dist/lib/registry.js

@@ -51,9 +51,9 @@ function promoteDraftRecipe(name, input, ctx, deps) {
     const targetPath = getToolRecipePath(deps, name);
     const tools = deps.getTools();
     const existing = tools.get(name);
-    const conflict = deps.getExternalToolConflict(name);
-    if (conflict)
-        throw new Error(ExecutionOutput.formatToolText(conflict));
+    const blocker = deps.getToolNameBlocker(name);
+    if (blocker)
+        throw new Error(ExecutionOutput.formatToolText(blocker));
     if ((existing || existsSync(targetPath)) && !input.update) {
         throw new Error(ExecutionOutput.formatToolText(`Tool "${name}" already registered. Use update=true to overwrite.`));
     }
@@ -238,9 +238,9 @@ export async function executeRegisterTool(params, ctx, deps) {
         return deleteTool(name, ctx, deps);
     const tools = deps.getTools();
     const existing = tools.get(name);
-    const conflict = deps.getExternalToolConflict(name);
-    if (conflict)
-        throw new Error(ExecutionOutput.formatToolText(conflict));
+    const blocker = deps.getToolNameBlocker(name);
+    if (blocker)
+        throw new Error(ExecutionOutput.formatToolText(blocker));
     if (existing && !input.update) {
         throw new Error(ExecutionOutput.formatToolText(`Tool "${name}" already registered. Use update=true to overwrite.`));
     }

package/dist/lib/runtime.d.ts

@@ -1,7 +1,7 @@
 /**
  * Tool registry runtime coordinator
  * Zones: runtime coordination, registry loading, pi tools
- * Owns persisted tool loading, conflict detection, runtime registration, and warning notification
+ * Owns persisted tool loading, reserved-name guards, runtime registration, and warning notification
  */
 import * as Config from "./config.ts";
 import type { RegisteredToolExec } from "./execution.ts";
@@ -12,22 +12,18 @@ export interface RuntimeContext {
         notify(message: string, type?: "info" | "warning" | "error"): void;
     };
 }
-export interface ToolInfoLike {
-    name: string;
-}
 export interface ToolRegistryRuntimeDeps {
     configPath: string;
     exec: RegisteredToolExec;
     packagedRecipeRoot?: string;
     recipeRoot?: string;
     getActiveTools?: () => string[];
-    getAllTools: () => ToolInfoLike[];
     registerTool: (definition: ReturnType<typeof ToolsLocal.createRuntimeToolDefinition>) => void;
     reservedToolNames: Set<string>;
     setActiveTools?: (toolNames: string[]) => void;
 }
 export interface ToolRegistryRuntime {
-    getExternalToolConflict(name: string): string | undefined;
+    getToolNameBlocker(name: string): string | undefined;
     getTools(): Map<string, Config.RegisteredTool>;
     loadTools(ctx: RuntimeContext): void;
     notify(ctx: RuntimeContext, message: string, type: "info" | "warning" | "error"): void;

package/dist/lib/runtime.js

@@ -1,7 +1,7 @@
 /**
  * Tool registry runtime coordinator
  * Zones: runtime coordination, registry loading, pi tools
- * Owns persisted tool loading, conflict detection, runtime registration, and warning notification
+ * Owns persisted tool loading, reserved-name guards, runtime registration, and warning notification
  */
 import { existsSync, watch } from "node:fs";
 import * as Paths from "./paths.js";
@@ -15,12 +15,9 @@ export function createAutoToolsRuntime(deps) {
         if (ctx.hasUI)
             ctx.ui.notify(message, type);
     }
-    function getExternalToolConflict(name) {
-        if (runtimeTools.has(name))
-            return undefined;
-        const existing = deps.getAllTools().find((tool) => tool.name === name);
-        return existing
-            ? `Tool "${name}" is already registered outside pi-actors.`
+    function getToolNameBlocker(name) {
+        return deps.reservedToolNames.has(name)
+            ? `Reserved tool name: ${name}`
             : undefined;
     }
     function getToolFingerprint(cfg) {
@@ -55,6 +52,8 @@ export function createAutoToolsRuntime(deps) {
         runtimeToolFingerprints.set(cfg.name, fingerprint);
     }
     function isStartupActionableRegistryWarning(warning) {
+        if (warning.includes(" shadows "))
+            return false;
         if (warning.includes("invokes bash;") &&
             warning.includes("trusted executable content"))
             return false;
@@ -104,9 +103,9 @@ export function createAutoToolsRuntime(deps) {
         }
         deactivateMissingRuntimeTools(new Set(tools.keys()));
         for (const cfg of tools.values()) {
-            const conflict = getExternalToolConflict(cfg.name);
-            if (conflict) {
-                warnings.push(conflict);
+            const blocker = getToolNameBlocker(cfg.name);
+            if (blocker) {
+                warnings.push(blocker);
                 continue;
             }
             registerRuntimeTool(cfg);
@@ -117,7 +116,7 @@ export function createAutoToolsRuntime(deps) {
         }
     }
     return {
-        getExternalToolConflict,
+        getToolNameBlocker,
         getTools: () => tools,
         loadTools,
         notify,

package/dist/lib/tools.d.ts

@@ -15,7 +15,7 @@ export interface CoreActorToolDefinitionDeps<TContext extends RuntimeToolContext
     configPath: string;
     getActiveTools: () => string[];
     getRuntimeTool: (name: string) => unknown;
-    registryRuntime: Pick<RegisterToolRuntimeDeps<TContext>, "getExternalToolConflict" | "getTools" | "notify" | "registerRuntimeTool">;
+    registryRuntime: Pick<RegisterToolRuntimeDeps<TContext>, "getToolNameBlocker" | "getTools" | "notify" | "registerRuntimeTool">;
     setActiveTools: (toolNames: string[]) => void;
 }
 export declare const RESERVED_TOOL_NAMES: Set<string>;

package/dist/lib/tools.js

@@ -25,7 +25,7 @@ export function createCoreActorToolDefinitions(deps) {
         ToolsRegister.createRegisterToolDefinition({
             configPath: deps.configPath,
             getActiveTools: deps.getActiveTools,
-            getExternalToolConflict: deps.registryRuntime.getExternalToolConflict,
+            getToolNameBlocker: deps.registryRuntime.getToolNameBlocker,
             getTools: deps.registryRuntime.getTools,
             notify: deps.registryRuntime.notify,
             registerRuntimeTool: deps.registryRuntime.registerRuntimeTool,

package/dist/skills/actors/SKILL.md

@@ -2,7 +2,7 @@
 name: actors
 description: Required practical guide for non-trivial pi-actors use. Read before using or changing spawn, message, inspect, actor runs, tools, recipes, command templates, async lifecycle, mailboxes, artifacts, and local orchestration mechanics.
 metadata:
-  version: 0.36.0
+  version: 0.37.0
 ---
 
 # Actors (pi-actors)
@@ -194,13 +194,14 @@ Rules:
 2. `async: true` makes spawned work a detached actor run.
 3. Public knobs belong in `args`/`defaults`; hidden launch mechanics stay inside `template`.
 4. Use `imports` to compose recipes; imported recipes are definitions, not nested async runs.
-5. When exposing an already-authored recipe as a user tool, make a small wrapper recipe in `~/.pi/agent/recipes` that imports the source recipe and uses a `{ "name": "alias" }` node. Do not copy the ready recipe's script command, defaults, mailbox, or artifacts into a second template.
-6. Declare `mailbox` for actors that accept or emit meaningful messages.
-7. Declare `artifacts` for durable outputs the coordinator should inspect.
-8. File-backed recipe identity comes from the filename basename; legacy top-level `name` fields are ignored by loaders.
-9. File-backed async recipes pass child `pi -p` actors a bounded JSONL recipe context bundle by default: raw entry/import recipe records, derived `name`, import path/alias, and `"you_are_here": true` on the launching recipe node. Set `"actor_context": false` or `"off"` to suppress it for minimal prompts.
-10. Keep packaged recipes generic: no machine-local paths, no private companion identities, no project-specific defaults unless the recipe is explicitly project-specific.
-11. Do not ship concrete model-version defaults in packaged recipes; expose `model`, `models`, and stage-specific model args so the caller must choose current policy at launch.
+5. Direct recipe delegation is the thin-wrapper case: when a `template` value is just a ready recipe name/path, the intended behavior is to delegate to that recipe rather than execute the recipe file as a program. Use this for simple handoffs and wrapper tools; use `imports` + `{ "name": "alias" }` when you need rich composition, multiple nodes, or import-specific values/defaults.
+6. When exposing an already-authored recipe as a user tool before direct delegation is available or when composition is needed, make a small wrapper recipe in `~/.pi/agent/recipes` that imports the source recipe and uses a `{ "name": "alias" }` node. Do not copy the ready recipe's script command, defaults, mailbox, or artifacts into a second template.
+7. Declare `mailbox` for actors that accept or emit meaningful messages.
+8. Declare `artifacts` for durable outputs the coordinator should inspect.
+9. File-backed recipe identity comes from the filename basename; legacy top-level `name` fields are ignored by loaders.
+10. File-backed async recipes pass child `pi -p` actors a bounded JSONL recipe context bundle by default: raw entry/import recipe records, derived `name`, import path/alias, and `"you_are_here": true` on the launching recipe node. Set `"actor_context": false` or `"off"` to suppress it for minimal prompts.
+11. Keep packaged recipes generic: no machine-local paths, no private companion identities, no project-specific defaults unless the recipe is explicitly project-specific.
+12. Do not ship concrete model-version defaults in packaged recipes; expose `model`, `models`, and stage-specific model args so the caller must choose current policy at launch.
 
 Priority for same-id recipes:
 
@@ -209,7 +210,7 @@ Priority for same-id recipes:
 3. Explicit ad hoc user recipe file outside `~/.pi/agent/recipes`.
 4. User recipe in `~/.pi/agent/recipes/*.json` or `*.md`: highest-priority operator tool surface.
 
-Only matching filename ids compete. Higher priority shadows lower priority; within one priority layer, same-id JSON shadows Markdown. An invalid or `disabled: true` higher-priority recipe blocks fallback so the agent does not silently run standard-library behavior when a user override is broken or intentionally disabled.
+Only matching filename ids compete. Higher priority shadows lower priority; within one priority layer, same-id JSON shadows Markdown. Same-id overrides are normal composition/delegation behavior, not startup-warning material. An invalid or `disabled: true` higher-priority recipe blocks fallback so the agent does not silently run standard-library behavior when a user override is broken or intentionally disabled.
 
 Muscle-memory lens: pi-actors has two durable executable-memory layers.
 
@@ -230,7 +231,21 @@ Cleanup rule: periodically inspect `~/.pi/agent/recipes` as the live muscle-memo
 
 Use it when a command/template/recipe should become durable agent muscle memory. Prefer typed args or placeholder-derived args; use `update=true` for replacement and `template=null` or `template=""` for deletion. `register_tool` should create/update/delete simple recipe files in the user recipe root; direct recipe-file editing is the right path when the wrapper needs `imports` or other top-level recipe metadata not exposed by the interactive mutation API.
 
-Ready-recipe registration pattern:
+Ready-recipe registration patterns:
+
+Thin delegation target shape:
+
+```json
+{
+  "description": "Run a ready recipe through a local tool name.",
+  "args": ["source:path", "volume:int=70"],
+  "template": "/path/to/ready-recipe.json"
+}
+```
+
+Delegation is for one-to-one handoff: expose or call a maintained recipe directly, preserving that recipe as the source of truth. If the runtime does not yet support direct recipe references in `template`, or if you need composition, use the import-node wrapper below.
+
+Composition/import wrapper:
 
 ```json
 {
@@ -243,16 +258,16 @@ Ready-recipe registration pattern:
 }
 ```
 
-Use this pattern whenever a reusable recipe already exists: packaged pi-actors components, project-local recipes, ad hoc reviewed recipe files, and especially skill-owned recipes that wrap skill scripts. The wrapper owns only the public tool name, description, optional narrowed args/defaults, and local usage metadata. The imported recipe remains the source of truth for the script path, default values, mailbox contract, artifacts, and future fixes.
+Use delegation or this import pattern whenever a reusable recipe already exists: packaged pi-actors components, project-local recipes, ad hoc reviewed recipe files, and especially skill-owned recipes that wrap skill scripts. The wrapper owns only the public tool name, description, optional narrowed args/defaults, and local usage metadata. The delegated/imported recipe remains the source of truth for the script path, default values, mailbox contract, artifacts, and future fixes.
 
 Tool-registration lenses are open-ended prompts for deciding what deserves durable tool status:
 
 1. **Reliability lens**: register wrappers for operations where agents commonly omit checks, run steps out of order, pass ambiguous inputs, or recover poorly from partial failure.
 2. **Safety lens**: prefer read-only diagnostics, dry-runs, preflights, confirmations, or bounded adapters around high-impact operations before registering direct action tools.
 3. **Context-affordance lens**: register tools whose mere presence in the injected capability list should steer agents toward the right operational habit.
-4. **Existing-recipe lens**: scan already-authored recipes before inventing a new tool. Packaged recipes, ad hoc project recipes, and recipes co-located under skill directories are the first candidates to import from a user-root wrapper when they match a recurring local workflow.
-5. **Skill-recipe lens**: when a skill ships a recipe for its script, local tools must import that recipe instead of calling the skill script directly. This preserves the skill's maintained interface and keeps future script/default changes centralized.
-6. **Composition lens**: register small semantic entrypoints over reusable recipe components instead of baking one large scenario-specific shell command into a tool.
+4. **Existing-recipe lens**: scan already-authored recipes before inventing a new tool. Packaged recipes, ad hoc project recipes, and recipes co-located under skill directories are the first candidates to delegate to or import from a user-root wrapper when they match a recurring local workflow.
+5. **Skill-recipe lens**: when a skill ships a recipe for its script, local tools must delegate to or import that recipe instead of calling the skill script directly. This preserves the skill's maintained interface and keeps future script/default changes centralized.
+6. **Composition lens**: register small semantic entrypoints over reusable recipe components instead of baking one large scenario-specific shell command into a tool; prefer direct delegation for one recipe, imports for composed graphs.
 7. **Portability lens**: keep recipe files transportable; make tool exposure a consequence of placement in `~/.pi/agent/recipes`, not recipe-owned markers or machine-local assumptions.
 
 Default bias: register diagnostic/preflight tools before action tools, and promote existing recipes before writing new orchestration. A good persistent tool shrinks the chance of a subtle operational mistake, not just the number of keystrokes.
@@ -260,7 +275,7 @@ Default bias: register diagnostic/preflight tools before action tools, and promo
 Tool templates may be:
 
 - A foreground command template.
-- A file-backed recipe name/path.
+- A file-backed recipe name/path for thin delegation.
 - A complete recipe body, optionally `async: true`.
 
 The user recipe root is the default tool set by location. It accepts canonical JSON recipes and literate Markdown recipes with frontmatter plus fenced `template`/`json recipe` blocks; same-id JSON shadows Markdown in the same priority layer. Packaged recipes are lower-priority standard-library components and are not tools unless copied or registered into the agent recipe root. Ideal runtime behavior is reactive: create/edit/delete recipe files, validate them, then connect valid tools or surface diagnostics without requiring agents to hand-maintain a separate registry.

package/dist/skills/swarm/SKILL.md

@@ -2,7 +2,7 @@
 name: swarm
 description: Subagent orchestration with scoped locks and quorum consensus. Use for multi-model review, parallel scoped work, delegated audit, and coordinated subagent execution.
 metadata:
-  version: 0.36.0
+  version: 0.37.0
 ---
 
 # Swarm

package/docs/template-recipes.md

@@ -292,9 +292,26 @@ An import binding may be either a string recipe path/name or an object with:
 
 A template node of `{ "name": "alias" }` is replaced with the imported recipe's command-template graph. Imported recipe defaults are merged with import `defaults`, import `values`, node `defaults`, and node `values`; later layers win. This lets a parent recipe embed a reusable recipe in a sequence or `parallel: true` branch without inventing a workflow language.
 
-Use imports as the default adapter for exposing ready recipes as local tools. A user-root recipe such as `~/.pi/agent/recipes/repo_context_check.json` should import the maintained source recipe and call `{ "name": "alias" }`, not duplicate the source recipe's script command. Skill scripts are the strongest version of this rule: when a skill provides `recipes/<name>.json` for its `scripts/*` entrypoint, local tools must import the skill recipe via `{agent}/skills/<skill>/recipes/<name>.json` instead of invoking the script path directly.
+Use imports as the default adapter for composed ready recipes. A user-root recipe such as `~/.pi/agent/recipes/repo_context_check.json` can import the maintained source recipe and call `{ "name": "alias" }` instead of duplicating the source recipe's script command. Skill scripts are the strongest version of this rule: when a skill provides `recipes/<name>.json` for its `scripts/*` entrypoint, local tools should delegate to or import the skill recipe instead of invoking the script path directly.
 
-Async composition stays explicit: importing a recipe reuses its command-template-shaped definition. It does not start a nested async run. Put `async: true` on the parent recipe when the combined imported graph should run detached as one run with one state dir. Ephemeral coordinator recipes may declare `retire_when: "children_terminal"` as an opt-in lifecycle hint for future graceful retirement handling; persistent services and implementer loops should omit it. For agent-callable fanout, prefer public inputs such as `prompts:array` plus `repeat: "{prompts.length}"`, then select each branch value with `{prompts[index]}` instead of baking concrete prompts or file names into the reusable recipe.
+## Direct Recipe Delegation
+
+A `template` string that resolves to a recipe name or recipe file path delegates to that recipe instead of executing the recipe file as a binary:
+
+```json
+{
+  "description": "Play music through the packaged player recipe.",
+  "async": true,
+  "defaults": { "source": "~/Music", "volume": "70" },
+  "template": "music-player"
+}
+```
+
+Delegation is a one-to-one handoff for thin wrappers and simple reuse. It uses the same bare-name priority as imports: user-root recipes under `~/.pi/agent/recipes`, then the importing recipe's directory, then packaged standard-library recipes. A higher-priority invalid or disabled recipe still blocks lower-priority fallback so operator overrides fail closed.
+
+Delegated recipes remain the source of truth for their command template, async setting, args/defaults, mailbox, artifacts, and future fixes. Wrapper recipe fields may narrow args/defaults or override lifecycle metadata. Use imports plus `{ "name": "alias" }` when you need rich composition, multiple recipe nodes, import-specific values/defaults, or a pipeline where the reusable recipe is only one step.
+
+Async composition stays explicit: importing or delegating to a recipe reuses its command-template-shaped definition. It does not start a nested async run. Put `async: true` on the parent recipe when the combined imported graph should run detached as one run with one state dir; thin delegation may inherit `async: true` from the delegated recipe. Ephemeral coordinator recipes may declare `retire_when: "children_terminal"` as an opt-in lifecycle hint for future graceful retirement handling; persistent services and implementer loops should omit it. For agent-callable fanout, prefer public inputs such as `prompts:array` plus `repeat: "{prompts.length}"`, then select each branch value with `{prompts[index]}` instead of baking concrete prompts or file names into the reusable recipe.
 
 ```json
 {