@llblab/pi-actors 0.58.1 → 0.58.2

package/docs/tool-registry.md

@@ -6,20 +6,28 @@
 ~/.pi/agent/recipes/*.json
 ```
 
-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.
+Each valid Recipe admitted against the current session context can become an agent-callable tool. `actors_tool_register` creates, updates, promotes, or deletes these files through fenced mutation paths and reports the resulting activation state.
+
+## Public names and compatible dispatch
+
+The advertised tools are `actors_tool_register`, `actors_run_spawn`, `actors_control_apply`, and `actors_inspect`. Explicit old `register_tool` / `spawn` / `message` / `inspect` calls dispatch through the same schemas and executors. Legacy entries are deferred and active for saved native calls, with their declarations hidden through Pi's loadout hook; normal callable listings omit deferred entries, while explicit search and host registered/active inventories can still expose compatibility metadata. A deliberately restricted host loadout/permission policy remains authoritative. No saved definition, call, Recipe filename/logical reference, launch kind or completion packet is rewritten. An already loaded host is not automatically reloaded.
+
+New configurable tools use their functional owner's namespace in snake_case, for example `audio_transcribe`, `music_player`, or `repo_check`. This agent-facing naming guidance is not runtime ownership inference and does not impose a new Recipe field or reject/migrate legacy unprefixed names. Runtime admission refuses normalized collisions against all foreign host tools, including inactive tools; `update=true` does not override foreign ownership. Discovery leaves a colliding persisted Recipe intact but does not admit its exposure or report the foreign tool as that Recipe's callable activation.
+
+Control applies Run/runtime actions, not agent chat. All existing envelopes, activation proof and Run semantics remain unchanged.
 
 ## Registration
 
 Register a command template:
 
 ```text
-register_tool name=repo_check template="make check" description="Run repository checks"
+actors_tool_register name=repo_check template="make check" description="Run repository checks"
 ```
 
 Specialize a maintained Recipe without copying its contract:
 
 ```text
-register_tool name=music_player from=music-player/playback defaults={"source":"~/Music/1MIX"}
+actors_tool_register name=music_player from=music-player/playback defaults={"source":"~/Music/1MIX"}
 ```
 
 `from`, `template`, and `draft` are distinct source modes. `from` accepts exact `<skill>/<recipe>` identity or an explicit `.json` / `.md` path and inherits async behavior, args/types, source defaults, artifacts, Control, and runtime-owned origins. `defaults` may set only effective caller-owned args and must satisfy their types. `template` is only for trusted command definitions; specialization accepts caller `defaults`, while authored composition values belong in a Recipe file.
@@ -27,24 +35,24 @@ register_tool name=music_player from=music-player/playback defaults={"source":"~
 Promote an immutable captured draft only with its draft path and explicit target name:
 
 ```text
-register_tool name=repo_check draft=~/.pi/agent/recipes/drafts/<captured-recipe>.json
+actors_tool_register name=repo_check draft=~/.pi/agent/recipes/drafts/<captured-recipe>.json
 ```
 
 Delete a persisted definition through the same fenced mutation path:
 
 ```text
-register_tool name=repo_check template=null
+actors_tool_register name=repo_check template=null
 ```
 
-An empty `template` string is the equivalent deletion form. Do not delete registry files manually. Host-visible dynamic definitions may remain visible until reload because Pi cannot unregister them, but extension-local lookup rejects the deleted definition immediately. Name collisions for creation or replacement require `update=true`. Invalid content fails before active mutation.
+An empty `template` string is the equivalent deletion form. Do not delete registry files manually. Host-visible dynamic definitions may remain visible until reload because Pi cannot unregister them, but extension-local lookup rejects the deleted definition immediately. The runtime retains its observed host-declaration name/source-path provenance separately from active Recipe membership, allowing same-name recreation or restoration after temporary discovery loss. A different source-path replacement or normalized foreign name still blocks exposure, even inactive; namespacing is not ownership proof. This host metadata check cannot distinguish replacements with identical name/source metadata. `update=true` permits replacing an existing Recipe, never a foreign host tool. Invalid content fails before active mutation.
 
-Ordinary tool registration resolves the effective delegated contract before persistence, then reports logical `source`, effective `required_args` / `optional_args`, and distinct `persisted`, `registry_active`, `host_registered`, `active_tool`, and `callable_now` states. A callable result points to the actual generated tool as the next action. An uncallable result names its `activation_boundary` and status/doctor action without suggesting spawn as a substitute. Diagnose one maintained source with `inspect target=recipes view=doctor identity=<skill>/<recipe>`; diagnose final activation, source, schema summary, and separate spawn/tool usage with `inspect target=tool:<name> view=status`. Treat the tool as callable in the current session only when `callable_now` is true; persistence alone is not activation proof. Ordinary tool-registration results omit raw persisted paths and executable template/config payloads; retained receipts deliberately return the reusable file path, never an executable body.
+Ordinary tool registration resolves the effective delegated contract before persistence, then reports logical `source`, effective `required_args` / `optional_args`, and distinct `persisted`, `registry_active`, `host_registered`, `active_tool`, and `callable_now` states. A callable result points to the actual generated tool as the next action. An uncallable result names its `activation_boundary` and status/doctor action without suggesting spawn as a substitute. Diagnose one maintained source with `actors_inspect target=recipes view=doctor identity=<skill>/<recipe>`; diagnose final activation, source, schema summary, and separate spawn/tool usage with `actors_inspect target=tool:<name> view=status`. Treat the tool as callable in the current session only when `callable_now` is true; persistence alone is not activation proof. Ordinary tool-registration results omit raw persisted paths and executable template/config payloads; retained receipts deliberately return the reusable file path, never an executable body.
 
 ## Retain a New Capability Without Tool Exposure
 
 ```text
-register_tool name=repo_check expose=false template="make check" description="Run repository checks"
-register_tool name=review_changes expose=false from=swarm/lens-review
+actors_tool_register name=repo_check expose=false template="make check" description="Run repository checks"
+actors_tool_register name=review_changes expose=false from=swarm/lens-review
 ```
 
 This create-only mode writes `recipes/library/<name>.json`, not a tool-root entry. The optional Boolean `expose` is registration input, not a Recipe field; omitted/true preserves ordinary registration. A new name and exactly one template/from source are required. Retained update, null/empty deletion, draft promotion and direct managed disposable-draft dependencies, including Recipe-valued template leaves, are rejected. JSON/Markdown stem conflicts, invalid source/defaults, oversized candidates and unsafe storage fail without activating a tool; a same-named exposed tool is untouched. Retaining never calls host registration/activation ports, mutates the active-tool set or launches work.
@@ -54,10 +62,10 @@ Retained `from` stores compact logical/file delegation and inherits the effectiv
 Use the existing surfaces, supplying required caller values:
 
 ```text
-register_tool name=changes_review from=swarm/lens-review expose=false
-inspect target=recipes view=summary verbose=true
-spawn recipe=<exact retained path> values=<caller-owned inputs>
-register_tool name=changes_review from=<exact retained path>
+actors_tool_register name=changes_review from=swarm/lens-review expose=false
+actors_inspect target=recipes view=summary verbose=true
+actors_run_spawn recipe=<exact retained path> values=<caller-owned inputs>
+actors_tool_register name=changes_review from=<exact retained path>
 ```
 
 Inspection distinguishes retained rows from tool-root candidates and drafts, using the same active Skill context. Compact output gives a retained count; verbose detail gives exact paths, resolved execution mode, invalid/disabled state and diagnostics. Reads create no directories, usage, tools or Runs; an absent library is empty. Reuse only valid enabled definitions. The final step deliberately exposes a wrapper; verify `callable_now` and actual tool invocation separately. Deleting an admitted wrapper preserves its retained source and does not stop active Runs or turn deletion of an old standalone tool into safe retention. No automatic retention, review decision, source relocation or live migration is added. See [Management Inspection](./inspection.md) for views and coverage.
@@ -79,13 +87,13 @@ Skill component inventory is diagnostic and fail-soft: valid components remain l
 Inspect registry state with:
 
 ```text
-inspect target=recipes view=status
-inspect target=tool:<name> view=status
+actors_inspect target=recipes view=status
+actors_inspect target=tool:<name> view=status
 ```
 
 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. Inspect the complete target/view contract in [Management Inspection](./inspection.md). 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"`.
+`actors_run_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"`.
 
 Async registered tools add runtime-owned optional invocation parameters after resolving the Recipe contract:
 
@@ -114,8 +122,8 @@ Automatic draft/tool review remains silent and mechanically fenced:
 Reserved recovery uses runtime Controls:
 
 ```text
-message target=runtime action=review.retry input={"scope":"draft"}
-message target=runtime action=review.reset input={"scope":"tool"}
+actors_control_apply target=runtime action=review.retry input={"scope":"draft"}
+actors_control_apply target=runtime action=review.reset input={"scope":"tool"}
 ```
 
 Retry preserves authenticated transaction recovery. Reset rejects evidence that requires roll-forward.
@@ -130,7 +138,7 @@ Retained launches use the parent Recipe root's existing `.usage` owner, not a se
 
 ## Specializing Existing Recipes
 
-Use `register_tool from=<skill>/<recipe> defaults={...}` for one maintained capability under a persistent name or narrower defaults. Pi supplies one authoritative active-session Skill snapshot across global, project, package, settings, CLI, and extension-contributed locations. Registration resolves the source from that snapshot, stores only the logical direct-delegation reference plus caller specialization, and activates the tool from the already-resolved effective contract without ambient re-resolution. It does not copy async, args/types, Control, artifacts, helpers, or runtime-owned `{recipe_dir}`/`{skill_dir}`; symlinks and absolute helper paths are not substitutes. Named imports remain for multi-node Recipe composition, not one-source specialization. Skill Recipes remain components and are never exposed merely because their Skill is active. Install only specific capabilities; internal automatic-review Recipes must not become user-callable tools.
+Use `actors_tool_register from=<skill>/<recipe> defaults={...}` for one maintained capability under a persistent name or narrower defaults. Pi supplies one authoritative active-session Skill snapshot across global, project, package, settings, CLI, and extension-contributed locations. Registration resolves the source from that snapshot, stores only the logical direct-delegation reference plus caller specialization, and activates the tool from the already-resolved effective contract without ambient re-resolution. It does not copy async, args/types, Control, artifacts, helpers, or runtime-owned `{recipe_dir}`/`{skill_dir}`; symlinks and absolute helper paths are not substitutes. Named imports remain for multi-node Recipe composition, not one-source specialization. Skill Recipes remain components and are never exposed merely because their Skill is active. Install only specific capabilities; internal automatic-review Recipes must not become user-callable tools.
 
 ## Safety
 

package/docs/windows-process-observation.md

@@ -14,7 +14,7 @@ The goal is cheaper fresh observation with unchanged evidence strength, not a ca
 
 ### Bounded original-runner diagnostic
 
-The public SDK fixture now has a temporary observer, with failure-only output, for the first `overflow` Run in each layout driver. It reserves one constructor candidate through public `node:diagnostics_channel`, matches executable/full public arguments/state directory/PID at successful `spawn`, and retains that original object's `close` callback facts. Private receipt binding follows the unchanged durable capture and requires the exact frame object and immutable signature. An unrelated first candidate makes the diagnostic unavailable; there is no replacement search, spawn interception, product hook, extra query, timer or wait.
+The public SDK fixture now has a temporary observer, with failure-only output, for the first `overflow` Run in each layout driver. It reserves one constructor candidate through public `node:diagnostics_channel`, matches executable/full public arguments/state directory/PID at successful `actors_run_spawn`, and retains that original object's `close` callback facts. Private receipt binding follows the unchanged durable capture and requires the exact frame object and immutable signature. An unrelated first candidate makes the diagnostic unavailable; there is no replacement search, spawn interception, product hook, extra query, timer or wait.
 
 Optional `failure_evidence.original_runner` freezes original callback facts at settlement catch entry, captures available public runtime fields before callback revocation, attempts owned teardown, then projects frozen observations with post-attempt teardown uncertainty. The catch-only `runtime_terminal_fields` category reads `exitCode` and `signalCode` at most once each from the same retained original object: safe-integer/null yields `exit_code_set`, null/recognized builtin OS signal yields `signal_code_set`, and null/null yields `null_pair`. Invalid, read-faulted, unbound, uncovered, released or changed-capture observations yield `unavailable`; no raw code, signal or private cause is projected. Getter/catch-clock reentrancy can invalidate this new category but cannot replace frozen entry callback facts.
 

package/lib/draft-sleep.ts

@@ -497,7 +497,7 @@ export function createDraftSleepScheduler(
             ...existing,
             failedStage: processed.stage ?? "result_processing",
             lastError: processed.error ?? "automatic draft review processing failed",
-            nextAction: "message target=runtime action=review.retry input={\"scope\":\"draft\"}",
+            nextAction: "actors_control_apply target=runtime action=review.retry input={\"scope\":\"draft\"}",
             phase: "processing_failed",
             processingAttempts: (existing.processingAttempts ?? 0) + 1,
             updatedAt: now().toISOString(),
@@ -508,7 +508,7 @@ export function createDraftSleepScheduler(
           ...existing,
           failedStage: processed.stage ?? "review_result",
           lastError: processed.error ?? "automatic draft reviewer failed",
-          nextAction: "message target=runtime action=review.retry input={\"scope\":\"draft\"}",
+          nextAction: "actors_control_apply target=runtime action=review.retry input={\"scope\":\"draft\"}",
           phase: "failed",
           runId: undefined,
           updatedAt: now().toISOString(),
@@ -551,7 +551,7 @@ export function createDraftSleepScheduler(
           attempts: (prior?.batchId === batch.batchId ? prior.attempts : 0) + 1,
           failedStage: "review_launch",
           lastError: error instanceof Error ? error.message : String(error),
-          nextAction: "message target=runtime action=review.retry input={\"scope\":\"draft\"}",
+          nextAction: "actors_control_apply target=runtime action=review.retry input={\"scope\":\"draft\"}",
           batchId: batch.batchId,
           inputPath: batch.inputPath,
           phase: "failed",

package/lib/extension-runtime.ts

@@ -250,6 +250,9 @@ export function createActorExtensionRuntime(
         sessionId,
         RecipeResolution.createEmptyRecipeResolutionContext(sessionId, ctx.cwd),
       );
+      // Deferred compatibility dispatch needs activation only after the host binds its ports.
+      // Its loadout hook hides declarations; explicit later loadout restrictions still win.
+      pi.setActiveTools([...new Set([...pi.getActiveTools(), ...Object.keys(Tools.LEGACY_TOOL_NAMES)])]);
       ctx.ui.setWidget("zz-pi-actors-comms", undefined);
       activeRunContext = ctx;
       activeRunOwnerId = sessionId;
@@ -270,9 +273,7 @@ export function createActorExtensionRuntime(
       recipeReload.watch(ctx);
     },
     registerCoreTools() {
-      Pi.registerToolDefinitions(
-        pi,
-        Tools.createCoreActorToolDefinitions<Pi.ExtensionContext>({
+      const definitions = Tools.createCoreActorToolDefinitions<Pi.ExtensionContext>({
           configPath: Paths.EXTENSION_RUNTIME_PATHS.configPath,
           getActiveTools: () => pi.getActiveTools(),
           getRecipeResolutionContext: () =>
@@ -289,8 +290,9 @@ export function createActorExtensionRuntime(
           handleRuntimeControl: automaticReview.handleControl,
           registryRuntime: runtime,
           setActiveTools: (toolNames) => pi.setActiveTools(toolNames),
-        }).map(withCurrentThinkingContext),
-      );
+        });
+      const legacy = Tools.createLegacyActorToolDefinitions(definitions);
+      Pi.registerToolDefinitions(pi, [...definitions, ...legacy].map(withCurrentThinkingContext));
     },
   };
 }

package/lib/prompts.ts

@@ -11,20 +11,21 @@ export const REGISTER_TOOL_DESCRIPTION =
   "Definitions persist under ~/.pi/agent/recipes; activation is reported separately.";
 
 export const REGISTER_TOOL_PROMPT_SNIPPET =
-  "Persist command templates or Recipes with register_tool; use expose=false to retain without tool activation";
+  "Persist command templates or Recipes with actors_tool_register; use expose=false to retain without tool activation";
 
 export const REGISTER_TOOL_GUIDELINES = [
-  "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.",
-  "Use register_tool expose=false to retain a new named template/from Recipe without activation; update, delete and draft promotion are unsupported in this mode.",
-  "A register_tool retained_recipe receipt with activation=not_requested is deliberate retention, not failed activation; reuse its exact Recipe path through spawn.",
-  "When register_tool requests tool exposure, trust callable_now and activation; 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.",
+  "Use actors_tool_register from=<skill>/<recipe> with defaults={...} to specialize a maintained Recipe without copying its contract.",
+  "Use actors_tool_register template only for trusted command templates, and use actors_tool_register draft only for captured draft promotion.",
+  "Use actors_tool_register expose=false to retain a new named template/from Recipe without activation; update, delete and draft promotion are unsupported in this mode.",
+  "A actors_tool_register retained_recipe receipt with activation=not_requested is deliberate retention, not failed activation; reuse its exact Recipe path through actors_run_spawn.",
+  "When actors_tool_register requests tool exposure, trust callable_now and activation; persistence alone is not callability.",
+  'Set template=null or template="" in actors_tool_register to delete a persisted tool.',
+  "Set update=true in actors_tool_register to overwrite an existing tool registration.",
 ];
 
 export const ONBOARDING_SYSTEM_PROMPT = `pi-actors Skill routing:
 - Treat active bundled Skills as the operating authority.
+- Route actors_tool_register, actors_run_spawn, actors_control_apply, and actors_inspect to the actors Skill; use canonical tool names for new calls.
 - 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.
@@ -36,7 +37,7 @@ export const ONBOARDING_SYSTEM_PROMPT = `pi-actors Skill routing:
 - 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')",
+  name: "Tool name in snake_case under its functional owner's namespace (e.g., 'audio_transcribe' or 'music_player'); keep existing persisted names when updating",
   description:
     "Describe what the tool does for the LLM. Required unless deleting; omitted updates keep the old description.",
   from:

package/lib/recipes-references.ts

@@ -205,7 +205,7 @@ export function inventoryActiveSkillRecipeComponents(
   for (const [skill, roots] of Object.entries(context.namespaces)) {
     if (roots.length > 1) {
       rejected.push({
-        reason: `Duplicate active Skill identity ${skill} (${roots.length} active definitions); exact Recipe resolution is ambiguous. Next: inspect target=recipes view=doctor identity=${skill}/<recipe>`,
+        reason: `Duplicate active Skill identity ${skill} (${roots.length} active definitions); exact Recipe resolution is ambiguous. Next: actors_inspect target=recipes view=doctor identity=${skill}/<recipe>`,
         skill,
       });
       continue;
@@ -322,13 +322,13 @@ function qualifiedRecipeNameForFile(
 function assertRecipeReferencePrefixWasNotRemoved(value: string): void {
   if (value.startsWith("std:")) {
     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.",
+      "std: Recipe references were removed in pi-actors 0.46. Use <skill>/<recipe> or an explicit .json/.md file path. Next: actors_inspect target=recipes view=status to identify the active owning Skill.",
     );
   }
   if (value.startsWith("skill:")) {
     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}`,
+      `skill: Recipe references were removed in pi-actors 0.46. Use ${identity} without a prefix. Next: actors_inspect target=recipes view=doctor identity=${identity}`,
     );
   }
 }
@@ -343,11 +343,11 @@ function skillRecipeCandidates(
   const roots = [...(context.namespaces[skillName] ?? [])];
   if (roots.length === 0)
     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}`,
+      `Active Skill Recipe not found: ${skillName}/${recipeName}. Owning Skill "${skillName}" is not active. Next: activate Skill ${skillName}, then actors_inspect target=recipes view=doctor identity=${skillName}/${recipeName}`,
     );
   if (roots.length > 1)
     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}`,
+      `Duplicate active Skill identity ${skillName} (${roots.length} active definitions); ${skillName}/${recipeName} cannot resolve unambiguously. Next: actors_inspect target=recipes view=doctor identity=${skillName}/${recipeName}`,
     );
   const root = roots[0];
   const candidates = ["json", "md"].map((extension) =>
@@ -356,7 +356,7 @@ function skillRecipeCandidates(
   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}`,
+      `Skill Recipe component not found: ${skillName}/${recipeName}; owning Skill "${skillName}" is active. Next: actors_inspect target=recipes view=doctor identity=${skillName}/${recipeName}`,
     );
   }
   if (existing.length > 1) {
@@ -394,7 +394,7 @@ function findOwningSkillDir(recipeFile: string): string | undefined {
 function assertRecipeHasNoDeclaredName(raw: Record<string, unknown>): void {
   if (!Object.hasOwn(raw, "name")) return;
   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.",
+    "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 actors_inspect target=recipes view=doctor.",
   );
 }
 

package/lib/registry.ts

@@ -124,7 +124,7 @@ function listTools<TContext>(
         ),
       ),
     ],
-    details: { tool: "register_tool" },
+    details: { tool: "actors_tool_register" },
   };
 }
 
@@ -153,8 +153,8 @@ function activationBoundary(
 
 function recipeDoctorAction(source: string): string {
   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";
+    ? `actors_inspect target=recipes view=doctor identity=${source}`
+    : "actors_inspect target=recipes view=doctor";
 }
 
 function registrationNextActions(
@@ -165,11 +165,11 @@ function registrationNextActions(
   if (callableNow) {
     return [
       `call tool ${tool}`,
-      `inspect target=tool:${tool} view=status`,
+      `actors_inspect target=tool:${tool} view=status`,
     ];
   }
   return [
-    `inspect target=tool:${tool} view=status`,
+    `actors_inspect target=tool:${tool} view=status`,
     ...(source === "template" || source === "draft"
       ? []
       : [recipeDoctorAction(source)]),
@@ -236,7 +236,7 @@ function registrationReceiptText(data: {
   const omittedNext = omission("next_action", 1, !nextWellFormed);
   // This producer knows only its existing status hint; invocation advice stays opaque.
   const next = part(nextWellFormed
-    ? data.callable ? { instruction: data.next } : { next: { tool: "inspect", target: `tool:${data.tool}`, view: "status" } }
+    ? data.callable ? { instruction: data.next } : { next: { tool: "actors_inspect", target: `tool:${data.tool}`, view: "status" } }
     : omittedNext, omittedNext);
   const render = () => renderPart({ ...tool.selected, result: data.result, ...source.selected, callable_now: data.callable,
     ...(data.boundary === undefined ? {} : { activation_boundary: data.boundary }), ...required.selected, ...optional.selected,
@@ -307,7 +307,7 @@ function draftPathFailureText(kind: "root" | "missing", reference: string): stri
   const selected = registrySelected(kind === "root" ? "allowed_root" : "path", reference);
   const render = (): RegistryMetadata => ({ field: "draft", ...selected.selected,
     result: kind === "root" ? "Draft must be under the allowed root." : "Draft not found.",
-    ...(kind === "root" ? { instruction: "Use inspect target=recipes view=summary to list drafts." } : {}) });
+    ...(kind === "root" ? { instruction: "Use actors_inspect target=recipes view=summary to list drafts." } : {}) });
   return growRegistryDocument(render, [selected]);
 }
 
@@ -349,8 +349,8 @@ function draftReceiptText(result: "updated" | "registered", tool: string, callab
   const identity = part("tool", tool, { tool });
   const flag = part("callable_now", callable, { callable_now: callable });
   // Only this producer's exact canonical read-only status hint is typed, never body advice.
-  const status = /^inspect target=(tool:[a-z][a-z0-9_]{0,63}) view=status$/u.exec(next);
-  const hint = part("next_action", next, status ? { next: { tool: "inspect", target: status[1], view: "status" } } : { instruction: next });
+  const status = /^actors_inspect target=(tool:[a-z][a-z0-9_]{0,63}) view=status$/u.exec(next);
+  const hint = part("next_action", next, status ? { next: { tool: "actors_inspect", target: status[1], view: "status" } } : { instruction: next });
   const render = () => renderPart({ ...identity.selected, result, source: "draft", ...flag.selected, ...hint.selected });
   for (const current of [identity, flag, hint]) {
     if (current.selected === current.full) continue;
@@ -508,6 +508,8 @@ function deleteTool<TContext>(
       details: { tool: name },
     };
   }
+  const blocker = deps.getToolNameBlocker(name);
+  if (blocker) throw new Error(ExecutionOutput.formatToolText(blocker));
   const recipePath = getToolRecipePath(deps, name);
   if (existsSync(recipePath)) unlinkSync(recipePath);
   tools.delete(name);
@@ -580,7 +582,7 @@ function assertTemplateIsNotNestedRecipe(value: unknown): void {
   ) {
     throw new Error(
       ExecutionOutput.formatToolText(registryMetadataText({ field: "template",
-        result: "Nested Recipe-shaped templates are not a register_tool source mode.",
+        result: "Nested Recipe-shaped templates are not a actors_tool_register source mode.",
         instruction: "retry with from=<skill>/<recipe> and defaults={...}." })),
     );
   }
@@ -650,7 +652,7 @@ function normalizeFromReference(
   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.",
+        "Tool from must be a non-empty Recipe reference. Next: retry actors_tool_register with from=<skill>/<recipe> or an explicit .json/.md path.",
       ),
     );
   }
@@ -710,7 +712,7 @@ function buildAuthoredRecipe(
         ExecutionOutput.formatToolText(registryMetadataText({ field: "defaults",
           ...registrySelected("key", runtimeOwnedDefault).selected,
           result: "Tool defaults cannot set runtime-owned input.",
-          instruction: "remove that default and retry register_tool; the runtime supplies it." })),
+          instruction: "remove that default and retry actors_tool_register; the runtime supplies it." })),
       );
     }
     const authored: Record<string, unknown> = {
@@ -763,9 +765,9 @@ function assertRegisterToolInputModes(input: RegisterToolInput): void {
   const record = input as RegisterToolInput & Record<string, unknown>;
   if (Object.hasOwn(record, "values")) {
     throw new Error(
-      ExecutionOutput.formatToolText(registryMetadataText({ field: "values", result: "register_tool values was removed.",
+      ExecutionOutput.formatToolText(registryMetadataText({ field: "values", result: "actors_tool_register values was removed.",
         replacement_fields: ["defaults", "from"],
-        instruction: "retry register_tool with defaults for caller inputs, or use from=<skill>/<recipe> for maintained composition." })),
+        instruction: "retry actors_tool_register with defaults for caller inputs, or use from=<skill>/<recipe> for maintained composition." })),
     );
   }
   const fromProvided = Object.hasOwn(record, "from");
@@ -777,7 +779,7 @@ function assertRegisterToolInputModes(input: RegisterToolInput): void {
       ExecutionOutput.formatToolText(registryMetadataText({ field: "from",
         result: "Tool from must be a non-empty Recipe reference.",
         reference_forms: ["<skill>/<recipe>", "explicit .json path", "explicit .md path"],
-        instruction: "retry register_tool with from=<skill>/<recipe> or an explicit .json/.md path." })),
+        instruction: "retry actors_tool_register with from=<skill>/<recipe> or an explicit .json/.md path." })),
     );
   }
   const draftProvided =
@@ -787,9 +789,9 @@ function assertRegisterToolInputModes(input: RegisterToolInput): void {
     Number(fromProvided) + Number(draftProvided) + Number(templateProvided);
   if (modeCount > 1) {
     throw new Error(
-      ExecutionOutput.formatToolText(registryMetadataText({ result: "Use exactly one register_tool source mode.",
+      ExecutionOutput.formatToolText(registryMetadataText({ result: "Use exactly one actors_tool_register source mode.",
         source_modes: ["from", "template", "draft"],
-        instruction: "remove the extra source fields and retry register_tool." })),
+        instruction: "remove the extra source fields and retry actors_tool_register." })),
     );
   }
   if (
@@ -798,9 +800,9 @@ function assertRegisterToolInputModes(input: RegisterToolInput): void {
   ) {
     throw new Error(
       ExecutionOutput.formatToolText(registryMetadataText({ field: "from",
-        result: "register_tool from inherits args and async behavior.",
+        result: "actors_tool_register from inherits args and async behavior.",
         inherited_fields: ["args", "async"],
-        instruction: "retry register_tool with from and optional defaults only; omit args and async." })),
+        instruction: "retry actors_tool_register with from and optional defaults only; omit args and async." })),
     );
   }
 }
@@ -881,7 +883,7 @@ function executeRegisterToolUnlocked<TContext>(
     throw new Error(
       ExecutionOutput.formatToolText(registryMetadataText({ result: "New registration requires exactly one source mode.",
         source_modes: ["from", "template", "draft"],
-        instruction: "retry register_tool with one source field." })),
+        instruction: "retry actors_tool_register with one source field." })),
     );
   }
   const recipePath = getToolRecipePath(deps, name);
@@ -930,7 +932,7 @@ function executeRegisterToolUnlocked<TContext>(
         !activation.callable_now)
     ) {
       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.`,
+        `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: actors_inspect target=runtime view=status; do not use spawn as proof of tool invocation.`,
       );
     }
   } catch (error) {
@@ -1158,12 +1160,12 @@ function retainRecipe<TContext>(
           const facts = { kind: "retained_recipe" as const, result: "retained" as const, persisted: true, resolved: true,
             validated: true, activation: "not_requested" as const, async: admitted.async };
           const text = growRegistryDocument(() => ({ ...selectedName.selected, ...facts, ...recipe.selected, ...selectedSource.selected,
-            ...required.selected, ...optional.selected, next: { tool: "inspect", target: "recipes", view: "summary", verbose: true } }),
+            ...required.selected, ...optional.selected, next: { tool: "actors_inspect", target: "recipes", view: "summary", verbose: true } }),
             [recipe, selectedName, selectedSource, required, optional]);
           const result = {
             content: [textContent(ExecutionOutput.formatToolText(text))],
             details: { ...facts, tool: name, recipe: path, source, required_args: args.required, optional_args: args.optional,
-              next_actions: ["inspect target=recipes view=summary verbose=true"] },
+              next_actions: ["actors_inspect target=recipes view=summary verbose=true"] },
           };
           stage = "release";
           return result;
@@ -1174,7 +1176,7 @@ function retainRecipe<TContext>(
     const reason = error instanceof RetainedRecipeRefusal ? { reason: error.reason } : {};
     throw new Error(ExecutionOutput.formatToolText(registryMetadataText({ operation: "retain", stage, result: "unconfirmed",
       effects: "unknown; inspect retained inventory before retry", ...reason,
-      next: { tool: "inspect", target: "recipes", view: "summary", verbose: true } })), { cause: error });
+      next: { tool: "actors_inspect", target: "recipes", view: "summary", verbose: true } })), { cause: error });
   }
 }
 

package/lib/review-control.ts

@@ -115,7 +115,7 @@ export function controlAutomaticReview(
     };
   });
   if (result.changed === true) schedule(scope, options);
-  const nextActions = ["inspect target=recipes view=reviews"];
+  const nextActions = ["actors_inspect target=recipes view=reviews"];
   if (
     action === "review.retry" &&
     scope === "tool" &&

package/lib/run-evidence-policy.ts

@@ -69,8 +69,8 @@ export type RunControlAdmissionInput = {
 const PENDING_CONTROL_STATUSES = new Set<RunControlStatus>(["queued", "delivered", "claimed"]);
 const TERMINAL_CONTROL_STATUSES = new Set<RunControlStatus>(["handled", "failed"]);
 const CONTROL_ADMISSION_NEXT_ACTIONS = [
-  "inspect target=run:<id> view=control",
-  "inspect target=runtime view=triage",
+  "actors_inspect target=run:<id> view=control",
+  "actors_inspect target=runtime view=triage",
 ];
 
 function isCount(value: number): boolean {

package/lib/runtime.ts

@@ -8,6 +8,7 @@ import { existsSync, watch, type FSWatcher } from "node:fs";
 import { basename, dirname } from "node:path";
 
 import * as Config from "./config.ts";
+import * as Identity from "./identity.ts";
 import type { RegisteredToolExec } from "./execution.ts";
 import * as Paths from "./paths.ts";
 import type { RecipeResolutionContext } from "./recipes-context.ts";
@@ -36,7 +37,7 @@ export interface ToolRegistryRuntimeDeps {
   exec: RegisteredToolExec;
   recipeRoot?: string;
   getActiveTools?: () => string[];
-  getAllTools?: () => Array<{ name: string }>;
+  getAllTools?: () => Array<{ name: string; sourceInfo?: { path: string } }>;
   registerTool: (
     definition: ReturnType<typeof ToolsLocal.createRuntimeToolDefinition>,
   ) => void;
@@ -83,6 +84,8 @@ export function createAutoToolsRuntime(
   const tools = new Map<string, Config.RegisteredTool>();
   const runtimeToolFingerprints = new Map<string, string>();
   const runtimeTools = new Set<string>();
+  // Host declarations survive deactivation; retain their observed provenance separately.
+  const runtimeToolSources = new Map<string, string | undefined>();
   const recipeRoot = deps.recipeRoot ?? Paths.getRecipeRoot();
   const status: RecipeRegistryStatus = {
     active_tool_count: 0,
@@ -99,9 +102,14 @@ export function createAutoToolsRuntime(
     if (ctx.hasUI) ctx.ui.notify(message, type);
   }
   function getToolNameBlocker(name: string): string | undefined {
-    return deps.reservedToolNames.has(name)
-      ? `Reserved tool name: ${name}`
-      : undefined;
+    const normalized = Identity.normalizeToolName(name);
+    if ([...deps.reservedToolNames].some((reserved) => Identity.normalizeToolName(reserved) === normalized))
+      return `Reserved tool name: ${name}`;
+    const foreign = deps.getAllTools?.().find((tool) =>
+      Identity.normalizeToolName(tool.name) === normalized &&
+      !(tool.name === name && runtimeToolSources.has(name) &&
+        tool.sourceInfo?.path === runtimeToolSources.get(name)));
+    return foreign ? `Host tool name collision: ${name} conflicts with ${foreign.name}` : undefined;
   }
   function getToolFingerprint(cfg: Config.RegisteredTool): string {
     return JSON.stringify({
@@ -135,12 +143,15 @@ export function createAutoToolsRuntime(
   function deactivateMissingRuntimeTools(activeNames: Set<string>): void {
     const stale = [...runtimeTools].filter((name) => !activeNames.has(name));
     if (stale.length === 0) return;
+    const hostTools = deps.getAllTools?.();
+    const staleOwned = stale.filter((name) => !hostTools || hostTools.some((tool) =>
+      tool.name === name && tool.sourceInfo?.path === runtimeToolSources.get(name)));
     for (const name of stale) {
       runtimeTools.delete(name);
       runtimeToolFingerprints.delete(name);
     }
     if (!deps.getActiveTools || !deps.setActiveTools) return;
-    const staleSet = new Set(stale);
+    const staleSet = new Set(staleOwned);
     deps.setActiveTools(
       deps.getActiveTools().filter((name) => !staleSet.has(name)),
     );
@@ -157,10 +168,13 @@ export function createAutoToolsRuntime(
     };
   }
   function registerRuntimeTool(cfg: Config.RegisteredTool): RuntimeToolActivation {
+    const blocker = getToolNameBlocker(cfg.name);
+    if (blocker) throw new Error(blocker);
     const fingerprint = getToolFingerprint(cfg);
     if (runtimeToolFingerprints.get(cfg.name) !== fingerprint) {
       deps.registerTool(ToolsLocal.createRuntimeToolDefinition(cfg, deps.exec));
       runtimeTools.add(cfg.name);
+      runtimeToolSources.set(cfg.name, deps.getAllTools?.().find((tool) => tool.name === cfg.name)?.sourceInfo?.path);
       runtimeToolFingerprints.set(cfg.name, fingerprint);
     }
     if (deps.getActiveTools && deps.setActiveTools) {
@@ -215,7 +229,7 @@ export function createAutoToolsRuntime(
       lines.push(...other.map((warning) => `• ${warning}`));
       groups[groups.length] = ["other_diagnostics", start, lines.length];
     }
-    lines.push("Next: inspect target=recipes view=doctor");
+    lines.push("Next: actors_inspect target=recipes view=doctor");
     // Preserve the original layout join/coercion and its faults before projecting owned warning slots.
     void `${lines.join("\n")}\n`;
     let text = ToolsResponse.formatMarkdownField("report", "pi-actors recipe registry warning");
@@ -227,7 +241,7 @@ export function createAutoToolsRuntime(
           : "  - warning:\n    - result: unavailable\n    - reason: malformed_selected_text");
       }
     }
-    return text + "\n" + ToolsResponse.formatMarkdownField("instruction", "Next: inspect target=recipes view=doctor") + "\n";
+    return text + "\n" + ToolsResponse.formatMarkdownField("instruction", "Next: actors_inspect target=recipes view=doctor") + "\n";
   }
   function loadTools(
     ctx: RuntimeContext,
@@ -259,6 +273,7 @@ export function createAutoToolsRuntime(
       const blocker = getToolNameBlocker(cfg.name);
       if (blocker) {
         warnings.push(blocker);
+        tools.delete(cfg.name);
         continue;
       }
       registerRuntimeTool(cfg);
@@ -284,7 +299,7 @@ export function createAutoToolsRuntime(
     }),
     getToolStatus: (name) => {
       const cfg = tools.get(name);
-      if (!cfg) return undefined;
+      if (!cfg || getToolNameBlocker(name)) return undefined;
       const usage = cfg.sourcePath
         ? RecipesUsage.readRecipeUsage(cfg.sourcePath)
         : undefined;
@@ -305,8 +320,8 @@ export function createAutoToolsRuntime(
         next_actions: activation.callable_now
           ? [`call tool ${name}`]
           : [
-              `register_tool name=${name} update=true`,
-              `inspect target=tool:${name} view=status`,
+              `actors_tool_register name=${name} update=true`,
+              `actors_inspect target=tool:${name} view=status`,
             ],
         ...(usage?.launch_kind ? { launch_kind: usage.launch_kind } : {}),
         spawn_calls: Number(usage?.spawn_calls ?? 0),
@@ -372,7 +387,7 @@ export function createRecipeToolReloadWatcher(
     setWatchStatus("failed");
     try {
       ctx.ui.notify(
-        "- report: Recipe live reload watcher failed\n- instruction: restart the session or use register_tool again to refresh recipe tools.",
+        "- report: Recipe live reload watcher failed\n- instruction: restart the session or use actors_tool_register again to refresh recipe tools.",
         "warning",
       );
     } catch (error) {