@llblab/pi-actors 0.36.0 → 0.37.1

package/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 ## Unreleased
 
+## 0.37.1: Subagent Recipe Prompt Injection Hotfix
+
+- `[Recipes]` Fixed actor recipe context injection for child `pi -p` launches with options after the print flag, so packaged subagent recipes such as `subagent-review` and `pipeline-review-readiness` append context to the actual prompt instead of corrupting `--model` or other option values.
+- `[Guidance]` Tightened onboarding, actor-skill, and recipe-library guidance so agents prefer maintained packaged review recipes via `spawn file=<recipe>` before rebuilding script commands or creating unnecessary wrappers.
+
+## 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/prompts.d.ts

@@ -6,7 +6,7 @@
 export declare const REGISTER_TOOL_DESCRIPTION: string;
 export declare const REGISTER_TOOL_PROMPT_SNIPPET = "Register persistent command templates as agent-callable tools";
 export declare const REGISTER_TOOL_GUIDELINES: string[];
-export declare const ONBOARDING_SYSTEM_PROMPT = "pi-actors quick model:\n- Local-first actor memory: persist trusted local capabilities instead of rebuilding shell recipes.\n- Layers: task -> command template -> recipe/tool -> spawn -> run:<id>; tool:<name> wraps registered capabilities.\n- Command templates stay sync: string leaf, array sequence, object node; flags include args/defaults, parallel, when, timeout, delay, retry, failure, recover, repeat, output.\n- Placeholders support typed/default args plus {value??fallback} and {flag?yes:no}.\n- ~/.pi/agent/recipes/*.json is actor muscle memory: every recipe there is auto-registered as an agent tool across sessions; register_tool writes there.\n- Recipes own template directly and may declare metadata/defaults/imports/mailbox/artifacts; files >1 MiB or import depth >32 fail closed.\n- Recipe imports are local variables; imported recipes are definitions, not nested async runs; parent async:true creates one run.\n- Actor-mode trigger: if work may outlive this turn, need steering/follow-up/artifacts, run as a service, fan out, or be resumed/inspected later, use spawn -> message -> inspect instead of ad hoc shell backgrounding.\n- Use spawn/message/inspect for actor-level start/send/observe; short foreground checks can stay ordinary tools/templates; avoid runtime/FIFO/outbox vocabulary in public guidance.\n- Run state lives under ~/.pi/agent/tmp/pi-actors/runs; inspect status/tail/messages/mailbox/files/artifacts intentionally and avoid busy-polling.\n- Maintain ~/.pi/agent/recipes like MEMORY.md for capabilities: keep useful tools, curate stale ones, and fix/remove/disable invalid recipes flagged by registry warnings; packaged/ad hoc recipes are lower-priority components; offer to save successful recurring patterns only after confirmation.\n- Long fanout = parent async recipe wrapping template(parallel:true) and imports; packaged fanout recipes bubble branch completion messages; grow recurring multi-agent workflows as packaged recipes/pipelines, not ad hoc external scripts.\n- For any non-trivial actor use or pi-actors change, read the bundled actors skill first; for deeper guidance, inspect installed extension sources/docs/recipes because README/docs are not automatically in context.";
+export declare const ONBOARDING_SYSTEM_PROMPT = "pi-actors quick model:\n- Local-first actor memory: persist trusted local capabilities instead of rebuilding shell recipes.\n- Layers: task -> command template -> recipe/tool -> spawn -> run:<id>; tool:<name> wraps registered capabilities.\n- Command templates stay sync: string leaf, array sequence, object node; flags include args/defaults, parallel, when, timeout, delay, retry, failure, recover, repeat, output.\n- Placeholders support typed/default args plus {value??fallback} and {flag?yes:no}.\n- ~/.pi/agent/recipes/*.json is actor muscle memory: every recipe there is auto-registered as an agent tool across sessions; register_tool writes there.\n- Recipes own template directly and may declare metadata/defaults/imports/mailbox/artifacts; files >1 MiB or import depth >32 fail closed.\n- Recipe imports are local variables; imported recipes are definitions, not nested async runs; parent async:true creates one run.\n- Actor-mode trigger: if work may outlive this turn, need steering/follow-up/artifacts, run as a service, fan out, or be resumed/inspected later, use spawn -> message -> inspect instead of ad hoc shell backgrounding.\n- Use spawn/message/inspect for actor-level start/send/observe; short foreground checks can stay ordinary tools/templates; avoid runtime/FIFO/outbox vocabulary in public guidance.\n- Run state lives under ~/.pi/agent/tmp/pi-actors/runs; inspect status/tail/messages/mailbox/files/artifacts intentionally and avoid busy-polling.\n- Maintain ~/.pi/agent/recipes like MEMORY.md for capabilities: keep useful tools, curate stale ones, and fix/remove/disable invalid recipes flagged by registry warnings; packaged/ad hoc recipes are lower-priority components; offer to save successful recurring patterns only after confirmation.\n- Prefer maintained packaged recipes/pipelines with spawn file=<recipe> before ad hoc scripts/wrappers; long fanout = parent async recipe wrapping template(parallel:true) and imports.\n- For any non-trivial actor use or pi-actors change, read the bundled actors skill first; for deeper guidance, inspect installed extension sources/docs/recipes because README/docs are not automatically in context.";
 export declare const REGISTER_TOOL_PARAM_DESCRIPTIONS: {
     readonly name: "Tool name in snake_case (e.g., 'transcribe')";
     readonly description: "Describe what the tool does for the LLM. Required unless deleting; omitted updates keep the old description.";

package/dist/lib/prompts.js

@@ -25,7 +25,7 @@ export const ONBOARDING_SYSTEM_PROMPT = `pi-actors quick model:
 - Use spawn/message/inspect for actor-level start/send/observe; short foreground checks can stay ordinary tools/templates; avoid runtime/FIFO/outbox vocabulary in public guidance.
 - Run state lives under ~/.pi/agent/tmp/pi-actors/runs; inspect status/tail/messages/mailbox/files/artifacts intentionally and avoid busy-polling.
 - Maintain ~/.pi/agent/recipes like MEMORY.md for capabilities: keep useful tools, curate stale ones, and fix/remove/disable invalid recipes flagged by registry warnings; packaged/ad hoc recipes are lower-priority components; offer to save successful recurring patterns only after confirmation.
-- Long fanout = parent async recipe wrapping template(parallel:true) and imports; packaged fanout recipes bubble branch completion messages; grow recurring multi-agent workflows as packaged recipes/pipelines, not ad hoc external scripts.
+- Prefer maintained packaged recipes/pipelines with spawn file=<recipe> before ad hoc scripts/wrappers; long fanout = parent async recipe wrapping template(parallel:true) and imports.
 - For any non-trivial actor use or pi-actors change, read the bundled actors skill first; for deeper guidance, inspect installed extension sources/docs/recipes because README/docs are not automatically in context.`;
 export const REGISTER_TOOL_PARAM_DESCRIPTIONS = {
     name: "Tool name in snake_case (e.g., 'transcribe')",

package/dist/lib/recipes-context.js

@@ -10,14 +10,66 @@ function commandName(command) {
 function isPiCommand(command) {
     return commandName(command) === "pi";
 }
+const PI_PRINT_FLAGS = new Set(["-p", "--print"]);
+const PI_VALUE_OPTIONS = new Set([
+    "--api-key",
+    "--append-system-prompt",
+    "--exclude-tools",
+    "--extension",
+    "--fork",
+    "--mode",
+    "--model",
+    "--models",
+    "--name",
+    "--prompt-template",
+    "--provider",
+    "--session",
+    "--session-dir",
+    "--skill",
+    "--system-prompt",
+    "--theme",
+    "--thinking",
+    "--tools",
+]);
+const PI_SHORT_VALUE_OPTIONS = new Set(["-e", "-n", "-t", "-xt"]);
+function isPiPrintFlag(arg) {
+    return PI_PRINT_FLAGS.has(arg);
+}
+function isPiOption(arg) {
+    return arg.startsWith("-") && arg !== "-";
+}
+function piOptionConsumesNextArg(arg) {
+    if (arg.includes("="))
+        return false;
+    return PI_VALUE_OPTIONS.has(arg) || PI_SHORT_VALUE_OPTIONS.has(arg);
+}
+function isPiFileArgument(arg) {
+    return arg.startsWith("@") && arg.length > 1;
+}
 function findPrintPromptIndex(args) {
+    let printMode = false;
+    let positionalOnly = false;
+    let promptIndex;
     for (let index = 0; index < args.length; index += 1) {
         const arg = args[index];
-        if ((arg === "-p" || arg === "--print") && index + 1 < args.length) {
-            return index + 1;
+        if (!positionalOnly && arg === "--") {
+            positionalOnly = true;
+            continue;
+        }
+        if (!positionalOnly && isPiPrintFlag(arg)) {
+            printMode = true;
+            continue;
+        }
+        if (!positionalOnly && isPiOption(arg)) {
+            if (piOptionConsumesNextArg(arg))
+                index += 1;
+            continue;
         }
+        if (!printMode || isPiFileArgument(arg))
+            continue;
+        promptIndex = index;
     }
-    return undefined;
+    return promptIndex;
 }
 function matchesActorContext(record, context) {
     if (!context)

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,