@llblab/pi-actors 0.46.1 → 0.48.0

package/dist/lib/prompts.d.ts

@@ -4,20 +4,21 @@
  * Owns LLM-facing descriptions, prompt snippets, guidelines, and parameter descriptions
  */
 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_PROMPT_SNIPPET = "Register persistent Recipes or 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 and shell-free: string leaves split into executable + argv, infer .js/.mjs through node\u2192bun\u2192deno run and .sh through bash, and treat operators such as && as literal arguments; use template arrays for sequencing or an explicit trusted shell/script when shell semantics are required. Flags include args/defaults, parallel, concurrency, min_successful, when, timeout, delay, retry, failure, recover, repeat, accept_output, output.\n- Placeholders support typed/default args plus {value??fallback} and {flag?yes:no}.\n- ~/.pi/agent/recipes/*.json is actor muscle memory: valid admitted recipes are reconciled as tools across sessions; register_tool writes there and reports current activation truth.\n- Recipes own template directly and may declare metadata/defaults/imports/control/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 internal transport vocabulary in public guidance.\n- Run state lives under ~/.pi/agent/tmp/pi-actors/runs. Inspect intentionally and avoid busy-polling. Terminal and coordinator-bound notifications queue as Pi follow-ups so concurrently completed actors can reach the coordinator after current work instead of steering between tool calls. Terminal follow-up content stays minimal: run, status, one base path, and relative artifact names only; semantic output stays in non-LLM details and run state. When a deferred actor result gates the next step, wait for its terminal follow-up; do not schedule continuation loops, repeatedly inspect, or mutate its reviewed scope while it runs. Inspect early only for an operator request, a meaningful actor event, or diagnosis of an overdue/stuck run.\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; active-Skill and explicit file Recipes remain components outside user tool discovery; offer to save successful recurring patterns only after confirmation.\n- Prefer maintained active-Skill Recipes with spawn recipe=<skill>/<recipe> before ad hoc scripts/wrappers; explicit file Recipes use exact .json/.md paths; review swarms inherit current model/thinking, preflight before fanout, and expose quorum/concurrency/TTL knobs unless explicit args are passed.\n- For any non-trivial actor use or pi-actors change, read the bundled actors skill first. Before launching multiple actors/subagents for parallel implementation, independent artifact generation, delegated audit, or review, also read the bundled swarm skill; the coordinator owns decomposition, disjoint scopes, launch correctness, integration, and final validation. 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 Skill routing:\n- Treat active bundled Skills as the operating authority.\n- For non-trivial pi-actors operation, diagnosis, or development, load and read the actors Skill before acting.\n- For work requiring multiple actors or subagents, additionally load and read the swarm Skill.\n- For capability-specific selection or constraints, load the owning capability Skill; actors owns generic mechanics and swarm owns multi-actor methodology.\n- Keep a Skill Recipe distinct from a registered tool and a Recipe spawn distinct from registered-tool invocation; actors owns the proof rules.\n- Treat persistence or registration as distinct from current callability; actors owns activation proof.\n- On failure or disagreement, preserve the logical Recipe identity, stop, and follow actors diagnosis; never bypass the owning Skills with copied contracts, helper paths, shell evaluation, or background-process workarounds.\n- If a capability Skill conflicts with actors about generic mechanics, follow actors and report the stale capability guidance.\n- README and docs are human-facing references, not the normal agent operating path.\n- AGENTS, source, and tests are implementation protocol and evidence; use them when changing or debugging the extension, not as substitutes for operating Skills.";
 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.";
-    readonly draft: "Promote a draft recipe path from ~/.pi/agent/recipes/drafts into an active named recipe under ~/.pi/agent/recipes. Requires name; use update=true to overwrite.";
+    readonly from: "Recipe to specialize by canonical <skill>/<recipe> identity or explicit .json/.md path. Inherits async, args/types, source defaults, artifacts, Control, and runtime origins.";
+    readonly defaults: "Optional caller-owned defaults. Keys and values must satisfy the effective source or command-template argument contract.";
+    readonly draft: "Promote a captured draft Recipe path from ~/.pi/agent/recipes/drafts. This is a source mode; do not combine it with from or template.";
     readonly async: "Set true for a co-located async template recipe. Omit for ordinary command templates or file-backed recipe references.";
-    readonly template: "Command template with {arg} or {arg=default} placeholders, or a template recipe JSON path/name. With async, this is the co-located recipe body. Bare recipe names resolve under ~/.pi/agent/recipes. Omitted updates keep the old template. Empty string deletes the tool.";
+    readonly template: "Trusted command template with {arg} or {arg=default} placeholders. To specialize a Recipe, use from instead. Omitted updates keep the old template; empty string deletes the tool.";
     readonly templateArray: "Sequential command-template composition array. Leaves may be strings or objects with template/defaults/timeout/retry/failure/recover.";
     readonly templateNull: "Delete the tool when template is null.";
     readonly args: "Optional comma-separated placeholder declarations. Usually omit because args are derived from template placeholders. Interactive shorthand defaults are accepted and normalized. Example: file,lang,mode=fast";
     readonly update: "Set to true to overwrite an existing tool registration.";
-    readonly values: "Optional default runtime placeholder values for a co-located template recipe.";
 };
 export declare function formatRegisteredToolPromptSnippet(template: unknown): string;
 export declare function formatRecipeToolPromptSnippet(recipe: string, asyncRecipe: boolean): string;

package/dist/lib/prompts.js

@@ -3,41 +3,40 @@
  * Zones: prompts, onboarding, tool schema copy
  * Owns LLM-facing descriptions, prompt snippets, guidelines, and parameter descriptions
  */
-export const REGISTER_TOOL_DESCRIPTION = "Register a persistent custom tool from a command template, template recipe path, or co-located template recipe. " +
-    "Definitions are stored as recipe files under ~/.pi/agent/recipes across reloads. " +
-    "Use update=true to overwrite an existing tool, template=null/empty to delete.";
-export const REGISTER_TOOL_PROMPT_SNIPPET = "Register persistent command templates as agent-callable tools";
+export const REGISTER_TOOL_DESCRIPTION = "Register a persistent custom tool from one maintained Recipe, command template, or captured draft. " +
+    "Use from for Recipe specialization, template for trusted commands, or draft for promotion. " +
+    "Definitions persist under ~/.pi/agent/recipes; activation is reported separately.";
+export const REGISTER_TOOL_PROMPT_SNIPPET = "Register persistent Recipes or command templates as agent-callable tools";
 export const REGISTER_TOOL_GUIDELINES = [
-    "Use register_tool to wrap trusted local commands, scripts, programs, libraries, or template recipes as persistent pi tools.",
-    "After register_tool succeeds, trust its callable_now and activation result; persisted definitions remain available for admission after reload.",
+    "Use register_tool from=<skill>/<recipe> with defaults={...} to specialize a maintained Recipe without copying its contract.",
+    "Use register_tool template only for trusted command templates, and use register_tool draft only for captured draft promotion.",
+    "After register_tool succeeds, trust its callable_now and activation result; persistence alone is not callability.",
     'Set template=null or template="" in register_tool to delete a persisted tool.',
     "Set update=true in register_tool to overwrite an existing tool registration.",
 ];
-export const ONBOARDING_SYSTEM_PROMPT = `pi-actors quick model:
-- Local-first actor memory: persist trusted local capabilities instead of rebuilding shell recipes.
-- Layers: task -> command template -> recipe/tool -> spawn -> run:<id>; tool:<name> wraps registered capabilities.
-- Command templates stay sync and shell-free: string leaves split into executable + argv, infer .js/.mjs through node→bun→deno run and .sh through bash, and treat operators such as && as literal arguments; use template arrays for sequencing or an explicit trusted shell/script when shell semantics are required. Flags include args/defaults, parallel, concurrency, min_successful, when, timeout, delay, retry, failure, recover, repeat, accept_output, output.
-- Placeholders support typed/default args plus {value??fallback} and {flag?yes:no}.
-- ~/.pi/agent/recipes/*.json is actor muscle memory: valid admitted recipes are reconciled as tools across sessions; register_tool writes there and reports current activation truth.
-- Recipes own template directly and may declare metadata/defaults/imports/control/artifacts; files >1 MiB or import depth >32 fail closed.
-- Recipe imports are local variables; imported recipes are definitions, not nested async runs; parent async:true creates one run.
-- 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.
-- Use spawn/message/inspect for actor-level start/send/observe; short foreground checks can stay ordinary tools/templates; avoid internal transport vocabulary in public guidance.
-- Run state lives under ~/.pi/agent/tmp/pi-actors/runs. Inspect intentionally and avoid busy-polling. Terminal and coordinator-bound notifications queue as Pi follow-ups so concurrently completed actors can reach the coordinator after current work instead of steering between tool calls. Terminal follow-up content stays minimal: run, status, one base path, and relative artifact names only; semantic output stays in non-LLM details and run state. When a deferred actor result gates the next step, wait for its terminal follow-up; do not schedule continuation loops, repeatedly inspect, or mutate its reviewed scope while it runs. Inspect early only for an operator request, a meaningful actor event, or diagnosis of an overdue/stuck run.
-- 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; active-Skill and explicit file Recipes remain components outside user tool discovery; offer to save successful recurring patterns only after confirmation.
-- Prefer maintained active-Skill Recipes with spawn recipe=<skill>/<recipe> before ad hoc scripts/wrappers; explicit file Recipes use exact .json/.md paths; review swarms inherit current model/thinking, preflight before fanout, and expose quorum/concurrency/TTL knobs unless explicit args are passed.
-- For any non-trivial actor use or pi-actors change, read the bundled actors skill first. Before launching multiple actors/subagents for parallel implementation, independent artifact generation, delegated audit, or review, also read the bundled swarm skill; the coordinator owns decomposition, disjoint scopes, launch correctness, integration, and final validation. For deeper guidance, inspect installed extension sources/docs/recipes because README/docs are not automatically in context.`;
+export const ONBOARDING_SYSTEM_PROMPT = `pi-actors Skill routing:
+- Treat active bundled Skills as the operating authority.
+- For non-trivial pi-actors operation, diagnosis, or development, load and read the actors Skill before acting.
+- For work requiring multiple actors or subagents, additionally load and read the swarm Skill.
+- For capability-specific selection or constraints, load the owning capability Skill; actors owns generic mechanics and swarm owns multi-actor methodology.
+- Keep a Skill Recipe distinct from a registered tool and a Recipe spawn distinct from registered-tool invocation; actors owns the proof rules.
+- Treat persistence or registration as distinct from current callability; actors owns activation proof.
+- On failure or disagreement, preserve the logical Recipe identity, stop, and follow actors diagnosis; never bypass the owning Skills with copied contracts, helper paths, shell evaluation, or background-process workarounds.
+- If a capability Skill conflicts with actors about generic mechanics, follow actors and report the stale capability guidance.
+- README and docs are human-facing references, not the normal agent operating path.
+- AGENTS, source, and tests are implementation protocol and evidence; use them when changing or debugging the extension, not as substitutes for operating Skills.`;
 export const REGISTER_TOOL_PARAM_DESCRIPTIONS = {
     name: "Tool name in snake_case (e.g., 'transcribe')",
     description: "Describe what the tool does for the LLM. Required unless deleting; omitted updates keep the old description.",
-    draft: "Promote a draft recipe path from ~/.pi/agent/recipes/drafts into an active named recipe under ~/.pi/agent/recipes. Requires name; use update=true to overwrite.",
+    from: "Recipe to specialize by canonical <skill>/<recipe> identity or explicit .json/.md path. Inherits async, args/types, source defaults, artifacts, Control, and runtime origins.",
+    defaults: "Optional caller-owned defaults. Keys and values must satisfy the effective source or command-template argument contract.",
+    draft: "Promote a captured draft Recipe path from ~/.pi/agent/recipes/drafts. This is a source mode; do not combine it with from or template.",
     async: "Set true for a co-located async template recipe. Omit for ordinary command templates or file-backed recipe references.",
-    template: "Command template with {arg} or {arg=default} placeholders, or a template recipe JSON path/name. With async, this is the co-located recipe body. Bare recipe names resolve under ~/.pi/agent/recipes. Omitted updates keep the old template. Empty string deletes the tool.",
+    template: "Trusted command template with {arg} or {arg=default} placeholders. To specialize a Recipe, use from instead. Omitted updates keep the old template; empty string deletes the tool.",
     templateArray: "Sequential command-template composition array. Leaves may be strings or objects with template/defaults/timeout/retry/failure/recover.",
     templateNull: "Delete the tool when template is null.",
     args: "Optional comma-separated placeholder declarations. Usually omit because args are derived from template placeholders. Interactive shorthand defaults are accepted and normalized. Example: file,lang,mode=fast",
     update: "Set to true to overwrite an existing tool registration.",
-    values: "Optional default runtime placeholder values for a co-located template recipe.",
 };
 export function formatRegisteredToolPromptSnippet(template) {
     const rendered = typeof template === "string" ? template : JSON.stringify(template);

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

@@ -69,5 +69,9 @@ export declare function createRecipeIntegrityManifest(result: RecipesDiscoveryRe
 export declare function getShadowedLaunchDiagnostic(result: RecipesDiscoveryResult, id: string): Record<string, unknown> | undefined;
 export declare function listDraftRecipes(root: string): Array<Record<string, unknown>>;
 export declare function summarizeDiscovery(result: RecipesDiscoveryResult): Record<string, unknown>;
+export declare function summarizeRegisteredToolArgs(tool: RegisteredTool): {
+    optional: string[];
+    required: string[];
+};
 export declare function admitUserRecipe(sourcePath: string, resolutionContext: RecipeResolutionContext, authoredRecipe?: Record<string, unknown>, mutableUsage?: boolean): UserRecipeAdmission;
 export declare function toRegisteredTool(entry: DiscoveredRecipe): RegisteredTool | undefined;

package/dist/lib/recipes-discovery.js

@@ -134,7 +134,7 @@ function readDiscoveredRecipe(root, file, priority, defaultTool = false, mutable
             mutableUsage,
             resolutionContext,
             diagnostics: [
-                `Failed to load recipe ${file}: ${error instanceof Error ? error.message : String(error)}`,
+                `Recipe ${id} rejected: ${error instanceof Error ? error.message : String(error)}`,
             ],
             riskLabels: [],
             shadows: [],
@@ -699,6 +699,18 @@ function projectRegisteredTool(identity, path, cfg, mutableUsage) {
             : {}),
     };
 }
+export function summarizeRegisteredToolArgs(tool) {
+    const publicArgs = tool.args.filter((arg) => !RecipesReferences.isRuntimeOwnedRecipeInput(arg));
+    const inlineDefaults = Schema.getExplicitToolArgDefaults(tool.recipe?.args);
+    const required = publicArgs.filter((arg) => !Object.hasOwn(tool.defaults, arg) &&
+        !Object.hasOwn(inlineDefaults, arg));
+    const requiredSet = new Set(required);
+    const optional = publicArgs.filter((arg) => !requiredSet.has(arg));
+    if (tool.recipe?.async === true) {
+        optional.push("run_id", "transport_context");
+    }
+    return { optional, required };
+}
 function boundedAdmissionDiagnostic(error) {
     const message = error instanceof Error ? error.message : String(error);
     return message.length <= 4096 ? message : `${message.slice(0, 4095)}…`;

package/dist/lib/recipes-references.js

@@ -72,7 +72,7 @@ export function inventoryActiveSkillRecipeComponents(context) {
     for (const [skill, roots] of Object.entries(context.namespaces)) {
         if (roots.length > 1) {
             rejected.push({
-                reason: `Duplicate active Skill identity ${skill}: ${roots.join(", ")}`,
+                reason: `Duplicate active Skill identity ${skill} (${roots.length} active definitions); exact Recipe resolution is ambiguous. Next: inspect target=recipes view=doctor identity=${skill}/<recipe>`,
                 skill,
             });
             continue;
@@ -175,10 +175,11 @@ function qualifiedRecipeNameForFile(file, context) {
 }
 function assertRecipeReferencePrefixWasNotRemoved(value) {
     if (value.startsWith("std:")) {
-        throw new Error("std: Recipe references were removed in pi-actors 0.46.\nUse <skill>/<recipe> or an explicit .json/.md file path.");
+        throw new Error("std: Recipe references were removed in pi-actors 0.46. Use <skill>/<recipe> or an explicit .json/.md file path. Next: inspect target=recipes view=status to identify the active owning Skill.");
     }
     if (value.startsWith("skill:")) {
-        throw new Error("skill: Recipe references were removed in pi-actors 0.46.\nUse <skill>/<recipe> without a prefix.");
+        const identity = value.slice("skill:".length);
+        throw new Error(`skill: Recipe references were removed in pi-actors 0.46. Use ${identity} without a prefix. Next: inspect target=recipes view=doctor identity=${identity}`);
     }
 }
 function skillRecipeCandidates(value, context) {
@@ -188,12 +189,15 @@ function skillRecipeCandidates(value, context) {
     const [, skillName, recipeName] = match;
     const roots = [...(context.namespaces[skillName] ?? [])];
     if (roots.length === 0)
-        throw new Error(`Active Skill Recipe not found: ${skillName}/${recipeName}`);
+        throw new Error(`Active Skill Recipe not found: ${skillName}/${recipeName}. Owning Skill "${skillName}" is not active. Next: activate Skill ${skillName}, then inspect target=recipes view=doctor identity=${skillName}/${recipeName}`);
     if (roots.length > 1)
-        throw new Error(`Duplicate active Skill identity ${skillName}: ${roots.join(", ")}`);
+        throw new Error(`Duplicate active Skill identity ${skillName} (${roots.length} active definitions); ${skillName}/${recipeName} cannot resolve unambiguously. Next: inspect target=recipes view=doctor identity=${skillName}/${recipeName}`);
     const root = roots[0];
     const candidates = ["json", "md"].map((extension) => resolve(root, `${recipeName}.${extension}`));
     const existing = candidates.filter((candidate) => existsSync(candidate));
+    if (existing.length === 0) {
+        throw new Error(`Skill Recipe component not found: ${skillName}/${recipeName}; owning Skill "${skillName}" is active. Next: inspect target=recipes view=doctor identity=${skillName}/${recipeName}`);
+    }
     if (existing.length > 1) {
         throw new Error(`Skill Recipe stem collision: ${skillName}/${recipeName} has both .json and .md files`);
     }
@@ -223,7 +227,7 @@ function findOwningSkillDir(recipeFile) {
 function assertRecipeHasNoDeclaredName(raw) {
     if (!Object.hasOwn(raw, "name"))
         return;
-    throw new Error("Recipe.name was removed in pi-actors 0.46.\nFile-backed Recipe identity is derived from its file name.");
+    throw new Error("Recipe.name was removed in pi-actors 0.46. File-backed Recipe identity is derived from its file name. Next: remove the name field, keep the intended filename stem, then inspect target=recipes view=doctor.");
 }
 function assertRuntimeRecipeValuesNotDeclared(raw) {
     const args = Array.isArray(raw.args)

package/dist/lib/registry.d.ts

@@ -10,27 +10,29 @@ export interface RegisterToolInput {
     description?: string;
     async?: boolean;
     template?: CommandTemplates.CommandTemplateValue | null;
+    from?: string;
+    defaults?: Record<string, unknown>;
     draft?: string;
     args?: string;
     update?: boolean;
-    values?: Record<string, unknown>;
 }
 export interface RegisterToolResultDetails {
     active_tool?: boolean;
     activation?: "current_session" | "unverified";
+    activation_boundary?: string;
     args?: string[];
     async?: boolean;
     callable_now?: boolean;
-    config?: string;
     defaults?: Record<string, string>;
-    draft?: string;
     host_registered?: boolean;
+    next_actions?: string[];
+    optional_args?: string[];
     persisted?: boolean;
     promoted?: boolean;
     registry_active?: boolean;
+    required_args?: string[];
     resolved?: boolean;
-    recipeName?: string;
-    template?: CommandTemplates.CommandTemplateValue;
+    source?: string;
     templateWarnings?: string[];
     tool: string;
     validated?: boolean;
@@ -42,6 +44,12 @@ export interface RegisterToolResult {
     }>;
     details: RegisterToolResultDetails;
 }
+interface RuntimeActivation {
+    active_tool: boolean;
+    activation: "current_session" | "unverified";
+    callable_now: boolean;
+    host_registered: boolean;
+}
 export interface RegisterToolRuntimeDeps<TContext> {
     configPath: string;
     recipeRoot?: string;
@@ -49,13 +57,9 @@ export interface RegisterToolRuntimeDeps<TContext> {
     getTools: () => Map<string, Config.RegisteredTool>;
     getActiveTools: () => string[];
     notify: (ctx: TContext, message: string, type: "info" | "warning" | "error") => void;
-    registerRuntimeTool: (cfg: Config.RegisteredTool) => {
-        active_tool: boolean;
-        activation: "current_session" | "unverified";
-        callable_now: boolean;
-        host_registered: boolean;
-    } | void;
+    registerRuntimeTool: (cfg: Config.RegisteredTool) => RuntimeActivation | void;
     reservedToolNames: Set<string>;
     setActiveTools: (toolNames: string[]) => void;
 }
 export declare function executeRegisterTool<TContext>(params: unknown, ctx: TContext, deps: RegisterToolRuntimeDeps<TContext>): Promise<RegisterToolResult>;
+export {};

package/dist/lib/registry.js

@@ -35,6 +35,42 @@ function getRecipeRoot(deps) {
 function getToolRecipePath(deps, name) {
     return join(getRecipeRoot(deps), `${name}.json`);
 }
+function activationBoundary(activation) {
+    if (activation?.callable_now)
+        return "current_session";
+    if (!activation)
+        return "session_activation_unverified";
+    if (!activation.host_registered)
+        return "host_registration";
+    if (!activation.active_tool)
+        return "active_tool_set";
+    return "callability_verification";
+}
+function recipeDoctorAction(source) {
+    return /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*\/[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/u.test(source)
+        ? `inspect target=recipes view=doctor identity=${source}`
+        : "inspect target=recipes view=doctor";
+}
+function registrationNextActions(tool, source, callableNow) {
+    if (callableNow) {
+        return [
+            `call tool ${tool}`,
+            `inspect target=tool:${tool} view=status`,
+        ];
+    }
+    return [
+        `inspect target=tool:${tool} view=status`,
+        ...(source === "template" || source === "draft"
+            ? []
+            : [recipeDoctorAction(source)]),
+    ];
+}
+function activeSkillSummary(resolutionContext) {
+    const names = Object.keys(RecipesReferences.getActiveSkillRecipeNamespaces(resolutionContext.activeSkills))
+        .sort()
+        .slice(0, 20);
+    return names.length > 0 ? names.join(", ") : "<none>";
+}
 function assertDraftPath(deps, draft) {
     const draftRoot = resolve(getRecipeRoot(deps), "drafts");
     const path = resolve(draft);
@@ -79,18 +115,33 @@ function promoteDraftRecipe(name, input, ctx, deps) {
     writeJsonAtomic(targetPath, authoredRecipe);
     const promoted = RecipesDiscovery.admitUserRecipe(targetPath, resolutionContext).tool;
     tools.set(name, promoted);
-    deps.registerRuntimeTool(promoted);
+    const activation = deps.registerRuntimeTool(promoted) ?? undefined;
+    const argSummary = RecipesDiscovery.summarizeRegisteredToolArgs(promoted);
+    const callableNow = activation?.callable_now ?? false;
+    const nextActions = registrationNextActions(name, "draft", callableNow);
     deps.notify(ctx, `Promoted draft recipe: ${name}`, "info");
     return {
         content: [
-            textContent(ExecutionOutput.formatToolText(`${existing ? "Updated" : "Registered"} tool "${name}" from draft recipe.`)),
+            textContent(ExecutionOutput.formatToolText(`${existing ? "Updated" : "Registered"} tool "${name}" from draft; callable_now=${callableNow}; next=${nextActions[0]}.`)),
         ],
         details: {
+            active_tool: activation?.active_tool ?? false,
+            activation: activation?.activation ?? "unverified",
+            activation_boundary: activationBoundary(activation),
             args: promoted.args,
-            config: targetPath,
-            draft: draftPath,
+            callable_now: callableNow,
+            defaults: promoted.defaults,
+            host_registered: activation?.host_registered ?? false,
+            next_actions: nextActions,
+            optional_args: argSummary.optional,
+            persisted: true,
             promoted: true,
+            registry_active: tools.get(name) === promoted,
+            required_args: argSummary.required,
+            resolved: true,
+            source: "draft",
             tool: name,
+            validated: true,
         },
     };
 }
@@ -120,7 +171,7 @@ function deleteTool(name, ctx, deps) {
         content: [
             textContent(ExecutionOutput.formatToolText(`Deleted tool "${name}". Reload to remove it from the complete registry.`)),
         ],
-        details: { config: recipePath, tool: name },
+        details: { tool: name },
     };
 }
 function readAuthoritativeStoredTool(deps, name) {
@@ -144,7 +195,25 @@ function readAuthoritativeStoredTool(deps, name) {
         return { exists: true };
     }
 }
+function looksLikeRecipeReference(value) {
+    const trimmed = value.trim();
+    return (trimmed.endsWith(".json") ||
+        trimmed.endsWith(".md") ||
+        /^[^/:\\]+\/[^/:\\]+$/.test(trimmed));
+}
+function assertTemplateIsNotNestedRecipe(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return;
+    const record = value;
+    if (typeof record.template === "string" &&
+        looksLikeRecipeReference(record.template) &&
+        (Object.keys(record).length === 1 ||
+            ["artifacts", "async", "control", "description", "imports", "values"].some((key) => Object.hasOwn(record, key)))) {
+        throw new Error(ExecutionOutput.formatToolText("Nested Recipe-shaped templates are not a register_tool source mode. Next: retry with from=<skill>/<recipe> and defaults={...}."));
+    }
+}
 function getInputTemplate(value) {
+    assertTemplateIsNotNestedRecipe(value);
     if (typeof value === "string")
         return value.trim();
     if (value === null || value === undefined)
@@ -173,15 +242,61 @@ function getRegistrationResolutionContext(ctx, deps) {
     }
     return RecipesContext.createEmptyRecipeResolutionContext("offline-register-tool", getRecipeRoot(deps));
 }
+function normalizeDefaults(value) {
+    if (value === undefined)
+        return undefined;
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error(ExecutionOutput.formatToolText("Tool defaults must be an object."));
+    }
+    return { ...value };
+}
+function normalizeFromReference(value, resolutionContext) {
+    const trimmed = value.trim();
+    if (!trimmed) {
+        throw new Error(ExecutionOutput.formatToolText("Tool from must be a non-empty Recipe reference. Next: retry register_tool with from=<skill>/<recipe> or an explicit .json/.md path."));
+    }
+    if (trimmed.startsWith("std:")) {
+        throw new Error(ExecutionOutput.formatToolText("std: Recipe references were removed; use <skill>/<recipe> or an explicit .json/.md file path."));
+    }
+    if (trimmed.startsWith("skill:")) {
+        throw new Error(ExecutionOutput.formatToolText(`skill: Recipe references were removed; use ${trimmed.slice("skill:".length)} without a prefix.`));
+    }
+    if (trimmed.endsWith(".json") || trimmed.endsWith(".md")) {
+        return resolve(resolutionContext.cwd, trimmed);
+    }
+    if (!looksLikeRecipeReference(trimmed)) {
+        throw new Error(ExecutionOutput.formatToolText("Tool from must use <skill>/<recipe> or an explicit .json/.md file path."));
+    }
+    return trimmed;
+}
 function buildAuthoredRecipe(input, existing, existingRecipe) {
     const explicitArgs = input.args === undefined
         ? undefined
         : Schema.parseToolArgDeclarations(input.args);
     if (explicitArgs?.error)
         throw new Error(ExecutionOutput.formatToolText(explicitArgs.error));
+    const from = typeof input.from === "string" ? input.from.trim() : "";
     const description = (input.description ?? existing?.description ?? "").trim();
-    if (!description) {
-        throw new Error(ExecutionOutput.formatToolText("Tool description is required unless deleting."));
+    if (!description && !from) {
+        throw new Error(ExecutionOutput.formatToolText("Tool description is required for command-template registration."));
+    }
+    const inputDefaults = normalizeDefaults(input.defaults);
+    if (from) {
+        const runtimeOwnedDefault = Object.keys(inputDefaults ?? {}).find((key) => RecipesReferences.isRuntimeOwnedRecipeInput(key));
+        if (runtimeOwnedDefault) {
+            throw new Error(ExecutionOutput.formatToolText(`Tool defaults cannot set runtime-owned input: ${runtimeOwnedDefault}. Next: remove that default and retry register_tool; the runtime supplies it.`));
+        }
+        const authored = {
+            ...(description ? { description } : {}),
+            template: from,
+        };
+        const retainedDefaults = inputDefaults ??
+            (existingRecipe?.defaults && typeof existingRecipe.defaults === "object"
+                ? existingRecipe.defaults
+                : undefined);
+        if (retainedDefaults && Object.keys(retainedDefaults).length > 0)
+            authored.defaults = retainedDefaults;
+        return authored;
     }
     const template = getInputTemplate(input.template);
     if (template === null) {
@@ -202,17 +317,47 @@ function buildAuthoredRecipe(input, existing, existingRecipe) {
         authored.async = input.async;
     if (explicitArgs) {
         authored.args = explicitArgs.declarations;
-        if (Object.keys(explicitArgs.defaults).length > 0)
-            authored.defaults = explicitArgs.defaults;
+        const defaults = { ...explicitArgs.defaults, ...(inputDefaults ?? {}) };
+        if (Object.keys(defaults).length > 0)
+            authored.defaults = defaults;
+        else
+            delete authored.defaults;
+    }
+    else if (inputDefaults !== undefined) {
+        if (Object.keys(inputDefaults).length > 0)
+            authored.defaults = inputDefaults;
         else
             delete authored.defaults;
     }
-    if (input.values && typeof input.values === "object")
-        authored.values = input.values;
     return authored;
 }
+function assertRegisterToolInputModes(input) {
+    const record = input;
+    if (Object.hasOwn(record, "values")) {
+        throw new Error(ExecutionOutput.formatToolText("register_tool values was removed. Next: retry register_tool with defaults for caller inputs, or use from=<skill>/<recipe> for maintained composition."));
+    }
+    const fromProvided = Object.hasOwn(record, "from");
+    if (fromProvided &&
+        (typeof input.from !== "string" || input.from.trim().length === 0)) {
+        throw new Error(ExecutionOutput.formatToolText("Tool from must be a non-empty Recipe reference. Next: retry register_tool with from=<skill>/<recipe> or an explicit .json/.md path."));
+    }
+    const draftProvided = typeof input.draft === "string" && input.draft.trim().length > 0;
+    const templateProvided = Object.hasOwn(record, "template");
+    const modeCount = Number(fromProvided) + Number(draftProvided) + Number(templateProvided);
+    if (modeCount > 1) {
+        throw new Error(ExecutionOutput.formatToolText("Use exactly one register_tool source mode: from, template, or draft. Next: remove the extra source fields and retry register_tool."));
+    }
+    if (fromProvided &&
+        (Object.hasOwn(record, "args") || Object.hasOwn(record, "async"))) {
+        throw new Error(ExecutionOutput.formatToolText("register_tool from inherits args and async behavior. Next: retry register_tool with from and optional defaults only; omit args and async."));
+    }
+}
 function executeRegisterToolUnlocked(params, ctx, deps) {
-    const input = params;
+    const rawInput = params && typeof params === "object"
+        ? params
+        : {};
+    assertRegisterToolInputModes(rawInput);
+    let input = rawInput;
     if (!input.name)
         return listTools(deps);
     const name = Identity.normalizeToolName(input.name);
@@ -224,6 +369,23 @@ function executeRegisterToolUnlocked(params, ctx, deps) {
     if (typeof input.draft === "string" && input.draft.trim()) {
         return promoteDraftRecipe(name, input, ctx, deps);
     }
+    const resolutionContext = getRegistrationResolutionContext(ctx, deps);
+    const requestedSource = typeof rawInput.from === "string" ? rawInput.from.trim() : undefined;
+    if (typeof input.from === "string") {
+        try {
+            input = {
+                ...input,
+                from: normalizeFromReference(input.from, resolutionContext),
+            };
+        }
+        catch (error) {
+            const reason = error instanceof Error ? error.message.trim() : String(error);
+            const diagnosticSource = requestedSource?.startsWith("skill:")
+                ? requestedSource.slice("skill:".length)
+                : requestedSource ?? "";
+            throw new Error(ExecutionOutput.formatToolText(`Recipe source "${requestedSource}" is invalid: ${reason}. Active Skills: ${activeSkillSummary(resolutionContext)}. Next: ${recipeDoctorAction(diagnosticSource)}`));
+        }
+    }
     const templateProvided = Object.hasOwn(input, "template");
     const template = getInputTemplate(input.template);
     if (templateProvided && (template === null || template === ""))
@@ -237,15 +399,17 @@ function executeRegisterToolUnlocked(params, ctx, deps) {
     if ((authoritative.exists || existing) && !input.update) {
         throw new Error(ExecutionOutput.formatToolText(`Tool "${name}" already registered. Use update=true to overwrite.`));
     }
-    if (template === undefined && !existing) {
-        throw new Error(ExecutionOutput.formatToolText("Tool template is required for new registrations."));
+    if (template === undefined && !input.from && !existing) {
+        throw new Error(ExecutionOutput.formatToolText("New registration requires exactly one source mode: from, template, or draft. Next: retry register_tool with one source field."));
     }
     const recipePath = getToolRecipePath(deps, name);
     const authoredRecipe = buildAuthoredRecipe(input, existing, authoritative.recipe);
-    const resolutionContext = getRegistrationResolutionContext(ctx, deps);
     const candidate = RecipesDiscovery.admitUserRecipe(recipePath, resolutionContext, authoredRecipe);
     if (!candidate.validated || !candidate.tool) {
-        throw new Error(ExecutionOutput.formatToolText(`Tool recipe validation failed: ${candidate.diagnostics.join("; ")}`));
+        const sourceDiagnostic = requestedSource
+            ? `Recipe source "${requestedSource}" validation failed: ${candidate.diagnostics.join("; ")}. Active Skills: ${activeSkillSummary(resolutionContext)}. Next: ${recipeDoctorAction(requestedSource)}`
+            : `Tool recipe validation failed: ${candidate.diagnostics.join("; ")}`;
+        throw new Error(ExecutionOutput.formatToolText(sourceDiagnostic));
     }
     const activeBefore = deps.getActiveTools();
     let persisted = false;
@@ -265,7 +429,7 @@ function executeRegisterToolUnlocked(params, ctx, deps) {
             (!activation.host_registered ||
                 !activation.active_tool ||
                 !activation.callable_now)) {
-            throw new Error(`Host activation verification failed: ${JSON.stringify(activation)}`);
+            throw new Error(`Tool "${name}" activation failed at ${activationBoundary(activation)}; host_registered=${activation.host_registered}, active_tool=${activation.active_tool}, callable_now=${activation.callable_now}. Registration was rolled back. Next: inspect target=runtime view=status; do not use spawn as proof of tool invocation.`);
         }
     }
     catch (error) {
@@ -292,27 +456,33 @@ function executeRegisterToolUnlocked(params, ctx, deps) {
     const warningText = templateWarnings.length > 0
         ? `\nWarnings:\n${templateWarnings.map((warning) => `- ${warning}`).join("\n")}`
         : "";
-    const outcomeText = activation?.callable_now
-        ? `${existing ? "Updated" : "Registered"} and activated tool "${name}"`
-        : `Persisted tool "${name}"; current-session activation is unverified`;
+    const callableNow = activation?.callable_now ?? false;
+    const source = requestedSource ?? "template";
+    const argSummary = RecipesDiscovery.summarizeRegisteredToolArgs(cfg);
+    const nextActions = registrationNextActions(name, source, callableNow);
+    const outcomeText = callableNow
+        ? `${existing ? "Updated" : "Registered"} tool "${name}" from ${source}; callable_now=true`
+        : `Persisted tool "${name}" from ${source}; callable_now=false; activation_boundary=${activationBoundary(activation)}`;
     return {
         content: [
-            textContent(ExecutionOutput.formatToolText(`${outcomeText} (args: ${Schema.formatToolArgs(cfg.args)}).${warningText}`)),
+            textContent(ExecutionOutput.formatToolText(`${outcomeText}; required=${Schema.formatToolArgs(argSummary.required)}; optional=${Schema.formatToolArgs(argSummary.optional)}; next=${nextActions[0]}.${warningText}`)),
         ],
         details: {
             active_tool: activation?.active_tool ?? false,
             activation: activation?.activation ?? "unverified",
+            activation_boundary: activationBoundary(activation),
             args: cfg.args,
-            callable_now: activation?.callable_now ?? false,
-            config: recipePath,
+            callable_now: callableNow,
             defaults: cfg.defaults,
             host_registered: activation?.host_registered ?? false,
+            next_actions: nextActions,
+            optional_args: argSummary.optional,
             persisted: true,
             registry_active: tools.get(name) === cfg,
+            required_args: argSummary.required,
             resolved: true,
+            source,
             ...(cfg.recipe?.async !== undefined ? { async: cfg.recipe.async } : {}),
-            ...(cfg.recipe?.name ? { recipeName: cfg.recipe.name } : {}),
-            ...(cfg.template ? { template: cfg.template } : {}),
             ...(templateWarnings.length > 0 ? { templateWarnings } : {}),
             tool: name,
             validated: true,