@llblab/pi-actors 0.36.0 → 0.37.0

package/index.ts

@@ -106,7 +106,6 @@ export default function toolRegistryExtension(pi: Pi.ExtensionAPI) {
     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/lib/async-runs.ts

@@ -67,11 +67,7 @@ import {
   deliverRunMessage,
   type SendRunMessageOptions,
 } from "./runs-messages.ts";
-import {
-  buildRunStatus,
-  tailFile,
-  tailLines,
-} from "./runs-status.ts";
+import { buildRunStatus, tailFile, tailLines } from "./runs-status.ts";
 import { readJsonFileResilient } from "./state-readers.ts";
 
 const RUNNER_IDENTITY_GRACE_MS = 5000;
@@ -213,8 +209,9 @@ function assertNoActiveRunState(stateDir: string): void {
 
 function resolveRecipeFile(file: string): string {
   return (
-    RecipesReferences.getRecipePath(file, DEFAULT_RECIPE_ROOT) ??
-    RecipesReferences.resolveRecipePath(file, DEFAULT_RECIPE_ROOT)
+    RecipesReferences.resolveRecipeReferencePath(file, Paths.getRecipeRoot()) ??
+    RecipesReferences.getRecipePath(file, Paths.getRecipeRoot()) ??
+    RecipesReferences.resolveRecipePath(file, Paths.getRecipeRoot())
   );
 }
 

package/lib/command-templates.ts

@@ -134,18 +134,33 @@ export function resolveInheritedDefaultReferences(
   inheritedDefaults: Record<string, unknown> | undefined,
   runtimeValues: Record<string, unknown> = {},
 ): Record<string, unknown> | undefined {
-  if (!ownDefaults || !inheritedDefaults) return ownDefaults;
+  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/lib/recipes-references.ts

@@ -135,27 +135,55 @@ function recipeNameFiles(value: string): string[] {
   return [`${trimmed}.json`, `${trimmed}.md`];
 }
 
-function resolveRecipeImportPath(
+function recipeCandidatePaths(
   value: string,
   currentRecipeRoot: string,
-): string {
+): string[] {
   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: string,
+  currentRecipeRoot: string,
+): string {
+  const candidates = recipeCandidatePaths(value, currentRecipeRoot);
   return candidates.find((candidate) => existsSync(candidate)) ?? candidates[0];
 }
 
+export function resolveRecipeReferencePath(
+  value: unknown,
+  currentRecipeRoot = Paths.getRecipeRoot(),
+): string | undefined {
+  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: unknown,
   recipeRoot = Paths.getRecipeRoot(),
@@ -165,18 +193,7 @@ export function getRecipePath(
   if (!trimmed || hasWhitespace(trimmed)) 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: unknown): boolean {
@@ -483,7 +500,7 @@ export function getRecipeIdFromPath(file: string): string {
 }
 
 function readRecipeConfig(value: unknown): TemplateRecipeConfig | undefined {
-  const path = getRecipePath(value);
+  const path = resolveRecipeReferencePath(value);
   return path ? readResolvedRecipeConfig(path) : undefined;
 }
 
@@ -647,6 +664,7 @@ function applyDefaultsToTemplate(
 ): CommandTemplateValue {
   const cleanOverrides = { ...overrides };
   delete cleanOverrides.name;
+  delete cleanOverrides.template;
   delete cleanOverrides.values;
   if (typeof template === "object" && !Array.isArray(template)) {
     return {
@@ -686,6 +704,119 @@ function withActorRecipeContext(
   return { actorRecipeContext: context, template: value };
 }
 
+function loadDelegatedRecipe(
+  value: unknown,
+  currentRecipeFile: string,
+  stack: string[],
+  options: ReadResolvedRecipeConfigOptions,
+): TemplateRecipeConfig | undefined {
+  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: TemplateRecipeConfig,
+  overrides: Record<string, unknown> = {},
+): CommandTemplateValue {
+  return applyDefaultsToTemplate(
+    delegated.template,
+    delegated.values,
+    overrides,
+  );
+}
+
+function expandRecipeDelegations(
+  value: CommandTemplateValue,
+  currentRecipeFile: string,
+  stack: string[],
+  options: ReadResolvedRecipeConfigOptions = {},
+): CommandTemplateValue {
+  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 as CommandTemplateValue,
+          currentRecipeFile,
+          stack,
+          options,
+        ) as CommandTemplateConfig,
+    );
+  }
+  const record = value as Record<string, unknown>;
+  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 as CommandTemplateValue,
+            currentRecipeFile,
+            stack,
+            options,
+          ) as CommandTemplateConfig,
+      ),
+    } as CommandTemplates.CommandTemplateObjectConfig;
+  }
+  if (record.template && typeof record.template === "object") {
+    return {
+      ...record,
+      template: expandRecipeDelegations(
+        record.template as CommandTemplateValue,
+        currentRecipeFile,
+        stack,
+        options,
+      ),
+    } as CommandTemplates.CommandTemplateObjectConfig;
+  }
+  return value;
+}
+
+function getDirectDelegatedRecipe(
+  value: CommandTemplateValue,
+  currentRecipeFile: string,
+  stack: string[],
+  options: ReadResolvedRecipeConfigOptions = {},
+): TemplateRecipeConfig | undefined {
+  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: CommandTemplateValue,
   imports: Record<string, ImportedRecipe>,
@@ -807,7 +938,22 @@ export function readResolvedRecipeConfig(
   >;
   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 as Record<string, unknown>)
+          : {},
+      )
+    : expandRecipeDelegations(expandedImportsTemplate, path, stack, options);
   const recipeName = getRecipeIdFromPath(path);
   const templateWithContext = options.includeActorRecipeContext
     ? withActorRecipeContext(expandedTemplate, {
@@ -817,33 +963,53 @@ export function readResolvedRecipeConfig(
         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 as string[] }
-      : {}),
-    ...(isRecord(substituted.defaults)
-      ? { defaults: substituted.defaults }
-      : {}),
+      : Array.isArray(delegated?.args)
+        ? { args: delegated.args }
+        : {}),
+    ...(mergedDefaults ? { defaults: mergedDefaults } : {}),
     ...(typeof substituted.parallel === "boolean"
       ? { parallel: substituted.parallel }
       : {}),
@@ -865,31 +1031,31 @@ export function readResolvedRecipeConfig(
     ...(typeof substituted.output === "string"
       ? { output: substituted.output }
       : {}),
-    ...(isRecord(substituted.artifacts)
+    ...(isRecord(artifactSource)
       ? {
           artifacts: Object.fromEntries(
-            Object.entries(substituted.artifacts).filter(
+            Object.entries(artifactSource).filter(
               (entry): entry is [string, string] =>
                 typeof entry[1] === "string",
             ),
           ),
         }
       : {}),
-    ...(isRecord(substituted.mailbox)
+    ...(isRecord(mailboxSource)
       ? {
           mailbox: {
-            ...(Array.isArray(substituted.mailbox.accepts)
+            ...(Array.isArray(mailboxSource.accepts)
               ? {
-                  accepts: substituted.mailbox.accepts.filter(
+                  accepts: mailboxSource.accepts.filter(
                     (value): value is TemplateRecipeMailboxEntry =>
                       typeof value === "string" ||
                       (isRecord(value) && typeof value.type === "string"),
                   ),
                 }
               : {}),
-            ...(Array.isArray(substituted.mailbox.emits)
+            ...(Array.isArray(mailboxSource.emits)
               ? {
-                  emits: substituted.mailbox.emits.filter(
+                  emits: mailboxSource.emits.filter(
                     (value): value is TemplateRecipeMailboxEntry =>
                       typeof value === "string" ||
                       (isRecord(value) && typeof value.type === "string"),
@@ -899,7 +1065,8 @@ export function readResolvedRecipeConfig(
           },
         }
       : {}),
-    ...(substituted.retire_when === "children_terminal"
+    ...(substituted.retire_when === "children_terminal" ||
+    delegated?.retire_when === "children_terminal"
       ? { retire_when: "children_terminal" as const }
       : {}),
     ...(typeof substituted.retry === "number" ||

package/lib/registry.ts

@@ -50,7 +50,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: (
@@ -132,8 +132,8 @@ function promoteDraftRecipe<TContext>(
   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(
@@ -383,8 +383,8 @@ export async function executeRegisterTool<TContext>(
     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(

package/lib/runtime.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 { existsSync, watch, type FSWatcher } from "node:fs";
@@ -19,17 +19,12 @@ export interface RuntimeContext {
   };
 }
 
-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;
@@ -38,7 +33,7 @@ export interface ToolRegistryRuntimeDeps {
 }
 
 export interface ToolRegistryRuntime {
-  getExternalToolConflict(name: string): string | undefined;
+  getToolNameBlocker(name: string): string | undefined;
   getTools(): Map<string, Config.RegisteredTool>;
   loadTools(ctx: RuntimeContext): void;
   notify(
@@ -67,11 +62,9 @@ export function createAutoToolsRuntime(
   ) {
     if (ctx.hasUI) ctx.ui.notify(message, type);
   }
-  function getExternalToolConflict(name: string): string | undefined {
-    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: string): string | undefined {
+    return deps.reservedToolNames.has(name)
+      ? `Reserved tool name: ${name}`
       : undefined;
   }
   function getToolFingerprint(cfg: Config.RegisteredTool): string {
@@ -105,6 +98,7 @@ export function createAutoToolsRuntime(
     runtimeToolFingerprints.set(cfg.name, fingerprint);
   }
   function isStartupActionableRegistryWarning(warning: string): boolean {
+    if (warning.includes(" shadows ")) return false;
     if (
       warning.includes("invokes bash;") &&
       warning.includes("trusted executable content")
@@ -166,9 +160,9 @@ export function createAutoToolsRuntime(
     }
     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);
@@ -179,7 +173,7 @@ export function createAutoToolsRuntime(
     }
   }
   return {
-    getExternalToolConflict,
+    getToolNameBlocker,
     getTools: () => tools,
     loadTools,
     notify,

package/lib/tools.ts

@@ -27,7 +27,7 @@ export interface CoreActorToolDefinitionDeps<
   getRuntimeTool: (name: string) => unknown;
   registryRuntime: Pick<
     RegisterToolRuntimeDeps<TContext>,
-    "getExternalToolConflict" | "getTools" | "notify" | "registerRuntimeTool"
+    "getToolNameBlocker" | "getTools" | "notify" | "registerRuntimeTool"
   >;
   setActiveTools: (toolNames: string[]) => void;
 }
@@ -53,7 +53,7 @@ export function createCoreActorToolDefinitions<
     ToolsRegister.createRegisterToolDefinition<TContext>({
       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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-actors",
-  "version": "0.36.0",
+  "version": "0.37.0",
   "private": false,
   "description": "Local Actor Kernel for Pi",
   "keywords": [

package/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/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