@llblab/pi-actors 0.46.0 → 0.46.1

package/dist/lib/runtime.js

@@ -7,11 +7,20 @@ import { existsSync, watch } from "node:fs";
 import { basename, dirname } from "node:path";
 import * as Paths from "./paths.js";
 import * as RecipesDiscovery from "./recipes-discovery.js";
+import * as RecipesUsage from "./recipes-usage.js";
 import * as ToolsLocal from "./tools-local.js";
 export function createAutoToolsRuntime(deps) {
     const tools = new Map();
     const runtimeToolFingerprints = new Map();
     const runtimeTools = new Set();
+    const recipeRoot = deps.recipeRoot ?? Paths.getRecipeRoot();
+    const status = {
+        active_tool_count: 0,
+        last_scan_counts: { active: 0, rejected: 0, scanned: 0 },
+        registry_generation: 0,
+        watch_status: "closed",
+        watched_root: recipeRoot,
+    };
     function notify(ctx, message, type) {
         if (ctx.hasUI)
             ctx.ui.notify(message, type);
@@ -44,13 +53,29 @@ export function createAutoToolsRuntime(deps) {
         const staleSet = new Set(stale);
         deps.setActiveTools(deps.getActiveTools().filter((name) => !staleSet.has(name)));
     }
+    function activationFor(name) {
+        const hostRegistered = deps.getAllTools?.().some((tool) => tool.name === name) ?? false;
+        const activeTool = deps.getActiveTools?.().includes(name) ?? false;
+        return {
+            active_tool: activeTool,
+            activation: hostRegistered && activeTool ? "current_session" : "unverified",
+            callable_now: hostRegistered && activeTool,
+            host_registered: hostRegistered,
+        };
+    }
     function registerRuntimeTool(cfg) {
         const fingerprint = getToolFingerprint(cfg);
-        if (runtimeToolFingerprints.get(cfg.name) === fingerprint)
-            return;
-        deps.registerTool(ToolsLocal.createRuntimeToolDefinition(cfg, deps.exec));
-        runtimeTools.add(cfg.name);
-        runtimeToolFingerprints.set(cfg.name, fingerprint);
+        if (runtimeToolFingerprints.get(cfg.name) !== fingerprint) {
+            deps.registerTool(ToolsLocal.createRuntimeToolDefinition(cfg, deps.exec));
+            runtimeTools.add(cfg.name);
+            runtimeToolFingerprints.set(cfg.name, fingerprint);
+        }
+        if (deps.getActiveTools && deps.setActiveTools) {
+            deps.setActiveTools([
+                ...new Set([...deps.getActiveTools(), cfg.name]),
+            ]);
+        }
+        return activationFor(cfg.name);
     }
     function isStartupActionableRegistryWarning(warning) {
         if (warning.includes(" shadows "))
@@ -82,11 +107,15 @@ export function createAutoToolsRuntime(deps) {
         }
         return `${lines.join("\n")}\n`;
     }
-    function loadTools(ctx) {
+    function loadTools(ctx, resolutionContext) {
         const warnings = [];
-        const recipeRoot = deps.recipeRoot ?? Paths.getRecipeRoot();
         const discovered = RecipesDiscovery.discoverRecipeSources([
-            { root: recipeRoot, defaultTool: true, mutableUsage: true },
+            {
+                root: recipeRoot,
+                defaultTool: true,
+                mutableUsage: true,
+                resolutionContext,
+            },
         ]);
         warnings.push(...discovered.diagnostics);
         tools.clear();
@@ -109,17 +138,47 @@ export function createAutoToolsRuntime(deps) {
             }
             registerRuntimeTool(cfg);
         }
+        status.active_tool_count = tools.size;
+        status.last_scan_at = new Date().toISOString();
+        status.last_scan_counts = {
+            active: tools.size,
+            rejected: discovered.entries.filter((entry) => entry.invalid).length,
+            scanned: discovered.entries.length,
+        };
+        status.registry_generation += 1;
+        status.resolution_generation = resolutionContext?.generation;
         const startupWarnings = warnings.filter(isStartupActionableRegistryWarning);
         if (startupWarnings.length > 0) {
             notify(ctx, formatRecipeToolWarnings(startupWarnings), "warning");
         }
     }
     return {
+        getStatus: () => ({
+            ...status,
+            last_scan_counts: { ...status.last_scan_counts },
+        }),
+        getToolStatus: (name) => {
+            const cfg = tools.get(name);
+            if (!cfg)
+                return undefined;
+            const usage = cfg.sourcePath
+                ? RecipesUsage.readRecipeUsage(cfg.sourcePath)
+                : undefined;
+            return {
+                ...activationFor(name),
+                launch_kind: usage?.launch_kind,
+                spawn_calls: Number(usage?.spawn_calls ?? 0),
+                tool_calls: Number(usage?.tool_calls ?? 0),
+            };
+        },
         getToolNameBlocker,
         getTools: () => tools,
         loadTools,
         notify,
         registerRuntimeTool,
+        setWatchStatus: (watchStatus) => {
+            status.watch_status = watchStatus;
+        },
     };
 }
 export function createRecipeToolReloadWatcher(runtime, deps = {}) {
@@ -129,6 +188,7 @@ export function createRecipeToolReloadWatcher(runtime, deps = {}) {
     let rootWatcher;
     let parentWatcher;
     let failureNotified = false;
+    const setWatchStatus = (watchStatus) => runtime.setWatchStatus?.(watchStatus);
     const close = () => {
         const closingRoot = rootWatcher;
         rootWatcher = undefined;
@@ -139,11 +199,13 @@ export function createRecipeToolReloadWatcher(runtime, deps = {}) {
         if (reloadTimeout)
             clearTimeout(reloadTimeout);
         reloadTimeout = undefined;
+        setWatchStatus("closed");
     };
     const notifyFailure = (ctx) => {
         if (failureNotified)
             return;
         failureNotified = true;
+        setWatchStatus("failed");
         ctx.ui.notify("Recipe live reload watcher failed; restart the session or use register_tool again to refresh recipe tools.", "warning");
     };
     const scheduleReload = (ctx) => {
@@ -151,7 +213,7 @@ export function createRecipeToolReloadWatcher(runtime, deps = {}) {
         if (reloadTimeout)
             clearTimeout(reloadTimeout);
         reloadTimeout = setTimeout(() => {
-            runtime.loadTools(ctx);
+            runtime.loadTools(ctx, deps.getResolutionContext?.());
             ctx.ui.notify("Recipe tools refreshed from ~/.pi/agent/recipes", "info");
         }, 150);
         reloadTimeout.unref?.();
@@ -181,6 +243,7 @@ export function createRecipeToolReloadWatcher(runtime, deps = {}) {
                 scheduleReload(ctx);
             });
             parentWatcher = watcher;
+            setWatchStatus("watching_parent");
             watcher.on("error", () => {
                 if (parentWatcher !== watcher)
                     return;
@@ -214,6 +277,7 @@ export function createRecipeToolReloadWatcher(runtime, deps = {}) {
                 scheduleReload(ctx);
             });
             rootWatcher = watcher;
+            setWatchStatus("watching_root");
             watcher.on("error", () => {
                 if (rootWatcher !== watcher)
                     return;

package/dist/lib/tools-inspect.d.ts

@@ -3,10 +3,13 @@
  * Zones: Run Recipe/Trace/Control views and runtime/recipe/tool diagnostics
  * Owns exact inspect target/view dispatch; source projection stays in domain modules.
  */
+import * as Runtime from "./runtime.ts";
 export interface InspectToolDeps<TContext = unknown> {
     getRunStatus?: (runOrDir: string) => Record<string, any>;
     getTool?: (name: string) => any | undefined;
+    getToolStatus?: (name: string) => Record<string, unknown> | undefined;
     listRuns?: () => Array<Record<string, any>>;
     recipeRoot?: string;
+    registryStatus?: () => Runtime.RecipeRegistryStatus;
 }
 export declare function createInspectToolDefinition<TContext = unknown>(deps?: InspectToolDeps<TContext>): any;

package/dist/lib/tools-inspect.js

@@ -4,7 +4,7 @@
  * Owns exact inspect target/view dispatch; source projection stays in domain modules.
  */
 import { statSync } from "node:fs";
-import { join } from "node:path";
+import { isAbsolute, join, relative } from "node:path";
 import * as AsyncRuns from "./async-runs.js";
 import * as ControlProjection from "./control-projection.js";
 import * as Inspector from "./inspector.js";
@@ -157,6 +157,15 @@ function inspectRuntime(view, input, ctx, deps) {
         return runtimeTriage(ctx, deps);
     throw new Error("inspect runtime supports view=status, view=runs, or view=triage.");
 }
+function portableSkillRecipePath(file, skill, namespaces) {
+    const root = namespaces[skill]?.[0];
+    if (!root)
+        return `<active-skill:${skill}>`;
+    const relation = relative(root, file);
+    return !relation.startsWith("..") && !isAbsolute(relation)
+        ? `<active-skill:${skill}>/${relation.replaceAll("\\", "/")}`
+        : `<active-skill:${skill}>`;
+}
 function inspectRecipes(view, deps, context) {
     if (view !== "status" &&
         view !== "summary" &&
@@ -172,30 +181,39 @@ function inspectRecipes(view, deps, context) {
     const discovered = RecipesDiscovery.discoverRecipeSources([
         { root: recipeRoot, defaultTool: true, mutableUsage: true },
     ]);
-    const skillContext = context && typeof context === "object" && "activeSkillRecipeContext" in context
-        ? context.activeSkillRecipeContext
+    const resolutionContext = context && typeof context === "object" && "recipeResolutionContext" in context
+        ? context.recipeResolutionContext
         : undefined;
-    const activeSkillContext = skillContext ?? RecipesReferences.EMPTY_ACTIVE_SKILL_RECIPE_CONTEXT;
+    const activeSkillContext = resolutionContext?.activeSkills ??
+        RecipesReferences.EMPTY_ACTIVE_SKILL_RECIPE_CONTEXT;
     const skillRecipeNamespaces = RecipesReferences.getActiveSkillRecipeNamespaces(activeSkillContext);
-    let skillRecipeComponents = [];
-    const skillRecipeComponentDiagnostics = [];
-    try {
-        skillRecipeComponents = RecipesReferences.listActiveSkillRecipeComponents(activeSkillContext).map((component) => ({
-            identity: component.identity,
-            source_kind: "active_skill_component",
-            skill: component.skill,
-            stem: component.stem,
-            imports: component.imports,
-        }));
-    }
-    catch (error) {
-        skillRecipeComponentDiagnostics.push({
-            error: error instanceof Error ? error.message : String(error),
-        });
-    }
+    const skillInventory = RecipesReferences.inventoryActiveSkillRecipeComponents(activeSkillContext);
+    const skillRecipeComponents = skillInventory.components.map((component) => ({
+        identity: component.identity,
+        source_kind: "active_skill_component",
+        skill: component.skill,
+        stem: component.stem,
+        imports: component.imports,
+    }));
+    const skillRecipeComponentDiagnostics = skillInventory.rejected.map((diagnostic) => ({
+        error: diagnostic.reason,
+        ...(diagnostic.file
+            ? {
+                file: portableSkillRecipePath(diagnostic.file, diagnostic.skill, skillRecipeNamespaces),
+            }
+            : {}),
+        skill: diagnostic.skill,
+        ...(diagnostic.stem ? { stem: diagnostic.stem } : {}),
+    }));
     const discoverySummary = RecipesDiscovery.summarizeDiscovery(discovered);
     const summary = {
         ...discoverySummary,
+        ...(deps.registryStatus
+            ? {
+                ...deps.registryStatus(),
+                watched_root: "~/.pi/agent/recipes",
+            }
+            : {}),
         active: Array.isArray(discoverySummary.active)
             ? discoverySummary.active.map((entry) => ({
                 ...entry,
@@ -204,6 +222,7 @@ function inspectRecipes(view, deps, context) {
             : discoverySummary.active,
         skill_recipe_components: skillRecipeComponents,
         skill_recipe_component_diagnostics: skillRecipeComponentDiagnostics,
+        skill_recipe_catalog_partial: skillInventory.partial,
         active_skill_recipe_identities: Object.keys(skillRecipeNamespaces).sort(),
         skill_recipe_namespace_diagnostics: Object.entries(skillRecipeNamespaces)
             .filter(([, roots]) => roots.length > 1)
@@ -307,6 +326,7 @@ function inspectTool(name, view, deps) {
         throw new Error(`registered tool not found: ${name}`);
     return {
         name,
+        ...(view === "status" ? deps.getToolStatus?.(name) : {}),
         description: tool.description,
         parameters: tool.parameters,
         promptSnippet: tool.promptSnippet,

package/dist/lib/tools-local.d.ts

@@ -6,9 +6,9 @@
 import * as ModelContext from "./model-context.ts";
 import type { RegisteredTool } from "./config.ts";
 import * as Execution from "./execution.ts";
-import * as RecipesReferences from "./recipes-references.ts";
+import type * as RecipeResolution from "./recipes-context.ts";
 export interface RuntimeToolContext extends ModelContext.CurrentModelContext {
-    activeSkillRecipeContext?: RecipesReferences.ActiveSkillRecipeContext;
+    recipeResolutionContext?: RecipeResolution.RecipeResolutionContext;
     cwd: string;
     sessionManager?: {
         getSessionId?: () => string;

package/dist/lib/tools-local.js

@@ -44,7 +44,8 @@ function shouldAddRuntimeToolUsageHint(error) {
     return (/^Argument \S+ must /.test(message) || /^Missing .* value: /.test(message));
 }
 function formatRuntimeToolUsageHint(cfg, required, includeRunId) {
-    const optional = cfg.args.filter((arg) => !required.includes(arg));
+    const optional = cfg.args.filter((arg) => !RecipesReferences.isRuntimeOwnedRecipeInput(arg) &&
+        !required.includes(arg));
     const exampleDefaults = {
         ...Schema.getExplicitToolArgDefaults(cfg.recipe?.args),
         ...cfg.defaults,
@@ -115,6 +116,8 @@ export function createRuntimeToolDefinition(cfg, exec) {
             ? new Set(cfg.args.filter((arg) => !Object.hasOwn(cfg.defaults, arg)))
             : Schema.getRequiredToolArgNames(requiredTemplateConfig);
     for (const arg of cfg.args) {
+        if (RecipesReferences.isRuntimeOwnedRecipeInput(arg))
+            continue;
         paramSchema[arg] = typedArgSchema(arg, cfg.argTypes?.[arg]);
         if (requiredArgs.has(arg))
             required.push(arg);
@@ -160,7 +163,7 @@ export function createRuntimeToolDefinition(cfg, exec) {
                         tool: cfg.name,
                         policy_values: ModelContext.withCurrentModelValues({ ...(cfg.recipe?.values ?? {}), ...values }, ctx),
                         values: resolveRecipeToolValues(cfg, values, ctx),
-                    }, ctx.cwd, { skillContext: ctx.activeSkillRecipeContext });
+                    }, ctx.cwd, { skillContext: ctx.recipeResolutionContext?.activeSkills });
                     return {
                         content: [
                             {

package/dist/lib/tools-response.js

@@ -91,6 +91,8 @@ export function compactAsyncRunStatus(value) {
     const result = asRecord(status.result);
     const run = String(status.run ?? "<unknown>");
     const tokens = [`run=${run}`, `status=${String(status.status ?? "unknown")}`];
+    if (status.launch_kind)
+        tokens.push(`launch_kind=${String(status.launch_kind)}`);
     tokens.push(...compactModelPolicy(status.model_policy ?? progress.model_policy));
     if (status.tool)
         tokens.push(`tool=${String(status.tool)}`);

package/dist/lib/tools-spawn.d.ts

@@ -4,9 +4,9 @@
  * Owns the public spawn execution path for run-backed actors
  */
 import * as ModelContext from "./model-context.ts";
-import * as RecipesReferences from "./recipes-references.ts";
+import type * as RecipeResolution from "./recipes-context.ts";
 export interface SpawnToolContext extends ModelContext.CurrentModelContext {
-    activeSkillRecipeContext?: RecipesReferences.ActiveSkillRecipeContext;
+    recipeResolutionContext?: RecipeResolution.RecipeResolutionContext;
     cwd: string;
     sessionManager?: {
         getSessionId?: () => string;

package/dist/lib/tools-spawn.js

@@ -111,7 +111,7 @@ export function createSpawnToolDefinition() {
                         artifacts: input.artifacts,
                     }
                     : {}),
-            }, ctx.cwd, { skillContext: ctx.activeSkillRecipeContext });
+            }, ctx.cwd, { skillContext: ctx.recipeResolutionContext?.activeSkills });
             const draftRecipe = writeSpawnDraftRecipe(input, meta);
             const nextActions = ToolsResponse.runNextActions(meta.run);
             const details = {

package/dist/lib/tools.d.ts

@@ -15,8 +15,11 @@ export interface CoreActorToolDefinitionDeps<TContext extends RuntimeToolContext
     configPath: string;
     getActiveTools: () => string[];
     getRuntimeTool: (name: string) => unknown;
+    getRuntimeToolStatus: (name: string) => Record<string, unknown> | undefined;
     handleRuntimeControl?: (action: string, input: unknown) => Record<string, unknown>;
-    registryRuntime: Pick<RegisterToolRuntimeDeps<TContext>, "getToolNameBlocker" | "getTools" | "notify" | "registerRuntimeTool">;
+    registryRuntime: Pick<RegisterToolRuntimeDeps<TContext>, "getToolNameBlocker" | "getTools" | "notify" | "registerRuntimeTool"> & {
+        getStatus(): import("./runtime.ts").RecipeRegistryStatus;
+    };
     setActiveTools: (toolNames: string[]) => void;
 }
 export declare function resolveActiveRuntimeTool(name: string, activeTools: Pick<Map<string, unknown>, "has">, getDefinition: (name: string) => unknown): unknown;

package/dist/lib/tools.js

@@ -41,6 +41,8 @@ export function createCoreActorToolDefinitions(deps) {
         }),
         ToolsInspect.createInspectToolDefinition({
             getTool: (name) => deps.getRuntimeTool(name),
+            getToolStatus: deps.getRuntimeToolStatus,
+            registryStatus: deps.registryRuntime.getStatus,
         }),
     ];
 }

package/dist/skills/actors/SKILL.md

@@ -19,9 +19,9 @@ Use the swarm skill separately for decomposition, quorum design, reviewer lenses
 - `spawn`: create one Run from a Recipe or inline command template.
 - `message`: send one actor-local Control to `run:<id>`, or the reserved review actions to `runtime`.
 - `inspect`: inspect `run:<id>`, `runtime`, `recipes`, or `tool:<name>`.
-- `register_tool`: persist a trusted capability; it does not address a running actor.
+- `register_tool`: persist a trusted capability; it does not address a running actor. Trust current-session callability only when its result says `callable_now: true`.
 
-A Run target exposes exactly three inspect views: `recipe`, `trace`, and `control`.
+A Run target exposes exactly three inspect views: `recipe`, `trace`, and `control`. Spawning a user Recipe is still a Recipe launch (`launch_kind: "spawn"`), not evidence that its registered tool was exposed or invoked; registered-tool execution reports `launch_kind: "tool"`, and `inspect target=tool:<name> view=status` separates both usage counts.
 
 ## Recipe
 
@@ -29,7 +29,7 @@ A Recipe defines execution. It may declare named typed args, inline fallbacks, c
 
 Do not declare Control for ordinary one-shot work. Runtime lifecycle actions such as `kill` stay runtime-owned and must not appear in Recipe Control declarations. Imported Recipes act as local definitions inside one Run; they do not create nested Runs unless execution explicitly spawns them.
 
-Prefer maintained Skill-owned Recipes over ad hoc wrappers. Skill Recipe identity is `<active Skill name>/<Recipe filename stem>`; Recipe files have no top-level `name`. `SKILL.md` `name` is Pi host metadata matching its directory, not an additional pi-actors identity field. Use `<skill>/<recipe>` for an exact direct component or an explicit `.json` / `.md` path. Entry paths resolve from invocation `cwd`; relative imports resolve from the importing Recipe directory. File-backed Recipes own `{recipe_dir}` and Skill Recipes own `{skill_dir}`; callers never pass or override these origins. Skill Recipes are components, not automatic tools. Keep model, thinking, mission, concurrency, quorum, and timeout choices caller-owned unless a Recipe documents a stable policy.
+Prefer maintained Skill-owned Recipes over ad hoc wrappers. Skill Recipe identity is `<active Skill name>/<Recipe filename stem>`; Recipe files have no top-level `name`. `SKILL.md` `name` is Pi host metadata matching its directory, not an additional pi-actors identity field. Use `<skill>/<recipe>` for an exact direct component or an explicit `.json` / `.md` path. Entry paths resolve from invocation `cwd`; relative imports resolve from the importing Recipe directory. File-backed Recipes own `{recipe_dir}` and Skill Recipes own `{skill_dir}`; callers never pass or override these origins. Skill Recipes are components, not automatic tools. A rejected component makes catalog inspection partial without blocking exact resolution of unrelated valid components in the same live session context. Keep model, thinking, mission, concurrency, quorum, and timeout choices caller-owned unless a Recipe documents a stable policy.
 
 ## Trace
 

package/docs/template-recipes.md

@@ -147,7 +147,9 @@ Resolution fails before launch when required current policy is unavailable. The
 
 ## Resolution Context
 
-User Recipes under `~/.pi/agent/recipes` remain intentionally registered tools, not an ambient import namespace. Each session receives an immutable active-Skill resolution context from Pi's loaded Skill metadata; pi-actors does not scan ambient Skill roots independently or keep a process-global mutable namespace. A launch captures its resolved graph, so later Skill changes affect only future launches. An invalid or missing exact target fails without fallback. Disabled Recipes cannot launch. Registry watchers converge after atomic changes without executing partial definitions.
+User Recipes under `~/.pi/agent/recipes` remain intentionally registered tools, not an ambient import namespace. Each session receives one immutable resolution context from Pi's loaded Skill metadata; spawn, user-Recipe admission, registration, schema derivation, live inspection, and watcher reconciliation consume that same context rather than scanning ambient Skill roots or keeping a process-global mutable namespace. A launch captures its resolved graph, so later Skill changes affect only future launches. An invalid or missing exact target fails without fallback. Disabled Recipes cannot launch. Registry watchers converge after atomic changes without executing partial definitions.
+
+Active-Skill catalog inventory is fail-soft diagnostic state, not exact-resolution authority. Invalid components are reported individually and make the catalog partial while unrelated valid `<skill>/<recipe>` references remain exactly resolvable.
 
 ## Validation
 

package/docs/tool-registry.md

@@ -6,7 +6,7 @@
 ~/.pi/agent/recipes/*.json
 ```
 
-Each active valid Recipe becomes an agent-callable tool. `register_tool` creates, updates, promotes, or deletes these files through fenced mutation paths.
+Each valid Recipe admitted against the current session context can become an agent-callable tool. `register_tool` creates, updates, promotes, or deletes these files through fenced mutation paths and reports the resulting activation state.
 
 ## Registration
 
@@ -20,9 +20,13 @@ Register a typed/defaulted template or Recipe-backed definition when reuse justi
 
 Promote an immutable captured draft only with its draft path and explicit target name. Name collisions require `update=true`. Invalid content fails before active mutation.
 
+Registration resolves the effective delegated contract before persistence, then reports distinct `persisted`, `registry_active`, `host_registered`, `active_tool`, and `callable_now` states. Treat the tool as callable in the current session only when `callable_now` is true; persistence alone is not activation proof.
+
 ## Resolution
 
-User Recipes are the only file-discovered tool source. Invalid or disabled user entries fail closed. Active Skill Recipes remain exact components outside tool discovery. Runtime reload watches the user Recipe root and converges after atomic changes; stale watcher generations cannot replace current registration state.
+User Recipes are the only file-discovered tool source. Invalid or disabled user entries fail closed. Active Skill Recipes remain exact components outside tool discovery. Spawn, registration, registry admission, schema derivation, and live inspection resolve against one immutable session context containing the current working directory and active Skills. Runtime reload watches the user Recipe root using that current context and converges after atomic changes; stale watcher generations cannot replace current registration state.
+
+Skill component inventory is diagnostic and fail-soft: valid components remain listed and exactly resolvable when an unrelated component is rejected. Recipe inspection reports rejected components and marks the catalog partial instead of treating one bad component as an empty catalog.
 
 Inspect registry state with:
 
@@ -31,7 +35,9 @@ inspect target=recipes view=status
 inspect target=tool:<name> view=status
 ```
 
-Recipe inspection reports active, shadowed, invalid, disabled, diagnostic, risk, usage, and review evidence. Tool inspection reports the current capability definition/schema; a registered tool is not a running actor.
+Recipe inspection reports generation, scan/watch state, active, shadowed, invalid, disabled, component rejection, diagnostic, risk, usage, and review evidence. Tool status reports current activation plus separate `tool_calls` and `spawn_calls`; tool schema reports the caller-owned capability contract. A registered tool is not a running actor.
+
+`spawn recipe=<name>` executes a Recipe and reports `launch_kind: "spawn"`; it does not prove that a registered tool was exposed or invoked. Registered-tool execution reports `launch_kind: "tool"`.
 
 ## Automatic Review
 

package/lib/async-runs.ts

@@ -161,6 +161,7 @@ export interface AsyncRunMeta {
   argv: string[];
   createdAt: string;
   cwd: string;
+  launch_kind?: AsyncRunLaunchSource;
   launch_source?: AsyncRunLaunchSource;
   launch_correlation?: {
     correlation_id?: string;
@@ -600,7 +601,10 @@ export function startRun(
       createdAt: new Date().toISOString(),
       cwd,
       ...(startParams.launch_source
-        ? { launch_source: startParams.launch_source }
+        ? {
+            launch_kind: startParams.launch_source,
+            launch_source: startParams.launch_source,
+          }
         : {}),
       ...(startParams.launch_correlation
         ? { launch_correlation: startParams.launch_correlation } : {}),

package/lib/execution.ts

@@ -83,6 +83,7 @@ export interface RegisteredToolExecutionResult {
     command: string;
     fullOutputPath?: string;
     killed: boolean;
+    launch_kind: "tool";
     stderrBytes?: number;
     stderrCapturedBytes?: number;
     stderrFile?: string;
@@ -1136,6 +1137,7 @@ export async function executeRegisteredTool(
       command,
       fullOutputPath: result.stdoutFile ?? formatted.fullOutputPath,
       killed: result.killed,
+      launch_kind: "tool",
       ...getCaptureDetails(result),
       ...(executed.branches.length > 0 ? { branches: executed.branches } : {}),
       ...(executed.failures.length > 0

package/lib/extension-runtime.ts

@@ -9,6 +9,7 @@ import * as CommandTemplates from "./command-templates.ts";
 import * as Paths from "./paths.ts";
 import * as Pi from "./pi.ts";
 import * as Prompts from "./prompts.ts";
+import * as RecipeResolution from "./recipes-context.ts";
 import * as RecipesReferences from "./recipes-references.ts";
 import * as RunUiRuntime from "./run-ui-runtime.ts";
 import * as Runtime from "./runtime.ts";
@@ -34,14 +35,21 @@ export function createActorExtensionRuntime(
   pi: Pi.ExtensionAPI,
 ): ActorExtensionRuntime {
   let activeRunContext: Pi.ExtensionContext | undefined;
-  const skillContextsBySession = new Map<
+  const recipeResolutionContextsBySession = new Map<
     string,
-    RecipesReferences.ActiveSkillRecipeContext
+    RecipeResolution.RecipeResolutionContext
   >();
   const getRunOwnerId = Pi.getSessionId;
-  const getSkillContext = (ctx: Pi.ExtensionContext) =>
-    skillContextsBySession.get(getRunOwnerId(ctx)) ??
-    RecipesReferences.EMPTY_ACTIVE_SKILL_RECIPE_CONTEXT;
+  const getRecipeResolutionContext = (ctx: Pi.ExtensionContext) => {
+    const sessionId = getRunOwnerId(ctx);
+    const resolutionContext = recipeResolutionContextsBySession.get(sessionId);
+    if (!resolutionContext) {
+      throw new Error(
+        `Recipe resolution context is unavailable for session ${sessionId}.`,
+      );
+    }
+    return resolutionContext;
+  };
   const automaticReview = AutomaticReviewRuntime.createAutomaticReviewRuntime({
     getActiveContext: () => activeRunContext,
     getRunOwnerId,
@@ -67,7 +75,7 @@ export function createActorExtensionRuntime(
         if (ctx && typeof ctx === "object") {
           nextArgs[4] = {
             ...(ctx as Record<string, unknown>),
-            activeSkillRecipeContext: getSkillContext(
+            recipeResolutionContext: getRecipeResolutionContext(
               ctx as Pi.ExtensionContext,
             ),
             getThinkingLevel: () => pi.getThinkingLevel(),
@@ -85,6 +93,7 @@ export function createActorExtensionRuntime(
     configPath: Paths.EXTENSION_RUNTIME_PATHS.configPath,
     exec: CommandTemplates.execCommandTemplate,
     getActiveTools: () => pi.getActiveTools(),
+    getAllTools: () => pi.getAllTools(),
     registerTool: (definition) => {
       const wrapped = withCurrentThinkingContext(definition);
       actorToolDefinitions.set(wrapped.name, wrapped);
@@ -93,13 +102,22 @@ export function createActorExtensionRuntime(
     reservedToolNames: Tools.RESERVED_TOOL_NAMES,
     setActiveTools: (toolNames) => pi.setActiveTools(toolNames),
   });
-  const recipeReload = Runtime.createRecipeToolReloadWatcher(runtime);
+  const recipeReload = Runtime.createRecipeToolReloadWatcher(runtime, {
+    getResolutionContext: () =>
+      activeRunContext
+        ? getRecipeResolutionContext(activeRunContext)
+        : undefined,
+  });
   return {
     beforeAgentStart(systemPrompt, skills, ctx) {
-      skillContextsBySession.set(
-        getRunOwnerId(ctx),
+      const sessionId = getRunOwnerId(ctx);
+      const resolutionContext = RecipeResolution.createRecipeResolutionContext(
+        sessionId,
+        ctx.cwd,
         RecipesReferences.createActiveSkillRecipeContext(skills),
       );
+      recipeResolutionContextsBySession.set(sessionId, resolutionContext);
+      runtime.loadTools(ctx, resolutionContext);
       return {
         systemPrompt: `${systemPrompt}\n\n${Prompts.ONBOARDING_SYSTEM_PROMPT}`,
       };
@@ -113,16 +131,17 @@ export function createActorExtensionRuntime(
       if (activeRunContext === ctx) automaticReview.schedule();
     },
     onSessionShutdown(reason, ctx) {
-      skillContextsBySession.delete(getRunOwnerId(ctx));
+      recipeResolutionContextsBySession.delete(getRunOwnerId(ctx));
       activeRunContext = undefined;
       automaticReview.close();
       recipeReload.close();
       runUiRuntime.shutdown(reason, ctx);
     },
     async onSessionStart(ctx) {
-      skillContextsBySession.set(
-        getRunOwnerId(ctx),
-        RecipesReferences.EMPTY_ACTIVE_SKILL_RECIPE_CONTEXT,
+      const sessionId = getRunOwnerId(ctx);
+      recipeResolutionContextsBySession.set(
+        sessionId,
+        RecipeResolution.createEmptyRecipeResolutionContext(sessionId, ctx.cwd),
       );
       ctx.ui.setWidget("zz-pi-actors-comms", undefined);
       activeRunContext = ctx;
@@ -132,7 +151,6 @@ export function createActorExtensionRuntime(
       await Temp.prepareExtensionTempDir(Paths.EXTENSION_RUNTIME_PATHS.tempDir);
       if (activeRunContext !== ctx) return;
       automaticReview.start(ctx);
-      runtime.loadTools(ctx);
       runUiRuntime.start(ctx);
       recipeReload.watch(ctx);
     },
@@ -148,6 +166,7 @@ export function createActorExtensionRuntime(
               runtime.getTools(),
               (activeName) => actorToolDefinitions.get(activeName),
             ),
+          getRuntimeToolStatus: runtime.getToolStatus,
           handleRuntimeControl: automaticReview.handleControl,
           registryRuntime: runtime,
           setActiveTools: (toolNames) => pi.setActiveTools(toolNames),

package/lib/inspector.ts

@@ -183,6 +183,7 @@ export function readActorInspectorRecipe(
       logical_reference: primaryLogicalReference,
       ...(typeof primary?.skill === "string" ? { skill: primary.skill } : {}),
       source_kind: primarySourceKind,
+      launch_kind: meta.launch_kind ?? meta.launch_source,
       launch_source: meta.launch_source,
     }),
     launch: redactedRecord({

package/lib/prompts.ts

@@ -14,7 +14,7 @@ export const REGISTER_TOOL_PROMPT_SNIPPET =
 
 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, the new tool is immediately callable and remains available after reload.",
+  "After register_tool succeeds, trust its callable_now and activation result; persisted definitions remain available for admission after reload.",
   '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.",
 ];
@@ -24,7 +24,7 @@ export const ONBOARDING_SYSTEM_PROMPT = `pi-actors quick model:
 - 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: every recipe there is auto-registered as an agent tool across sessions; register_tool writes there.
+- ~/.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.