@llblab/pi-actors 0.58.1 → 0.58.2

package/dist/lib/runtime.js

@@ -5,6 +5,7 @@
  */
 import { existsSync, watch } from "node:fs";
 import { basename, dirname } from "node:path";
+import * as Identity from "./identity.js";
 import * as Paths from "./paths.js";
 import * as RecipesDiscovery from "./recipes-discovery.js";
 import * as RecipesReferences from "./recipes-references.js";
@@ -15,6 +16,8 @@ export function createAutoToolsRuntime(deps) {
     const tools = new Map();
     const runtimeToolFingerprints = new Map();
     const runtimeTools = new Set();
+    // Host declarations survive deactivation; retain their observed provenance separately.
+    const runtimeToolSources = new Map();
     const recipeRoot = deps.recipeRoot ?? Paths.getRecipeRoot();
     const status = {
         active_tool_count: 0,
@@ -28,9 +31,13 @@ export function createAutoToolsRuntime(deps) {
             ctx.ui.notify(message, type);
     }
     function getToolNameBlocker(name) {
-        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) {
         return JSON.stringify({
@@ -61,13 +68,15 @@ export function createAutoToolsRuntime(deps) {
         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)));
     }
     function activationFor(name) {
@@ -81,10 +90,14 @@ export function createAutoToolsRuntime(deps) {
         };
     }
     function registerRuntimeTool(cfg) {
+        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) {
@@ -129,7 +142,7 @@ export function createAutoToolsRuntime(deps) {
             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");
@@ -141,7 +154,7 @@ export function createAutoToolsRuntime(deps) {
                     : "  - 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, resolutionContext) {
         const warnings = [];
@@ -170,6 +183,7 @@ export function createAutoToolsRuntime(deps) {
             const blocker = getToolNameBlocker(cfg.name);
             if (blocker) {
                 warnings.push(blocker);
+                tools.delete(cfg.name);
                 continue;
             }
             registerRuntimeTool(cfg);
@@ -195,7 +209,7 @@ export function createAutoToolsRuntime(deps) {
         }),
         getToolStatus: (name) => {
             const cfg = tools.get(name);
-            if (!cfg)
+            if (!cfg || getToolNameBlocker(name))
                 return undefined;
             const usage = cfg.sourcePath
                 ? RecipesUsage.readRecipeUsage(cfg.sourcePath)
@@ -217,8 +231,8 @@ export function createAutoToolsRuntime(deps) {
                 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),
@@ -271,7 +285,7 @@ export function createRecipeToolReloadWatcher(runtime, deps = {}) {
         failureNotified = true;
         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.", "warning");
+            ctx.ui.notify("- report: Recipe live reload watcher failed\n- instruction: restart the session or use actors_tool_register again to refresh recipe tools.", "warning");
         }
         catch (error) {
             reportCallbackError(error);

package/dist/lib/tool-review-scheduler.js

@@ -264,7 +264,7 @@ export function applyApprovedToolReviewAtSessionBoundary(options = {}) {
                 ...state,
                 failedStage: "approval_state",
                 lastError: "approved review path is unavailable",
-                nextAction: "message target=runtime action=review.retry input={\"scope\":\"tool\"}",
+                nextAction: "actors_control_apply target=runtime action=review.retry input={\"scope\":\"tool\"}",
                 phase: "processing_failed",
                 updatedAt: (options.now ?? (() => new Date()))().toISOString(),
             };
@@ -287,7 +287,7 @@ export function applyApprovedToolReviewAtSessionBoundary(options = {}) {
                     ...state,
                     failedStage: "transaction",
                     lastError: `tool review transaction remained ${transaction.phase}`,
-                    nextAction: "message target=runtime action=review.retry input={\"scope\":\"tool\"}",
+                    nextAction: "actors_control_apply target=runtime action=review.retry input={\"scope\":\"tool\"}",
                     phase: "processing_failed",
                     updatedAt: (options.now ?? (() => new Date()))().toISOString(),
                 };
@@ -316,7 +316,7 @@ export function applyApprovedToolReviewAtSessionBoundary(options = {}) {
                     ...pending,
                     failedStage: "lineage",
                     lastError: error instanceof Error ? error.message : String(error),
-                    nextAction: "message target=runtime action=review.retry input={\"scope\":\"tool\"}",
+                    nextAction: "actors_control_apply target=runtime action=review.retry input={\"scope\":\"tool\"}",
                 };
                 writeJsonAtomic(statePath, failedPending);
                 return { outcome: "lineage_pending", state: failedPending };
@@ -337,7 +337,7 @@ export function applyApprovedToolReviewAtSessionBoundary(options = {}) {
                 ...state,
                 failedStage: "transaction",
                 lastError: error instanceof Error ? error.message : String(error),
-                nextAction: "message target=runtime action=review.retry input={\"scope\":\"tool\"}",
+                nextAction: "actors_control_apply target=runtime action=review.retry input={\"scope\":\"tool\"}",
                 phase: "processing_failed",
                 updatedAt: (options.now ?? (() => new Date()))().toISOString(),
             };
@@ -401,7 +401,7 @@ export function createToolReviewScheduler(deps) {
                             ...existing,
                             failedStage: processed.stage ?? "review_result",
                             lastError: processed.error ?? "automatic tool reviewer failed",
-                            nextAction: "message target=runtime action=review.retry input={\"scope\":\"tool\"}",
+                            nextAction: "actors_control_apply target=runtime action=review.retry input={\"scope\":\"tool\"}",
                             phase: processed.outcome === "processing_failed"
                                 ? "processing_failed"
                                 : "failed",
@@ -437,7 +437,7 @@ export function createToolReviewScheduler(deps) {
                                 attempts: existing.attempts + 1,
                                 failedStage: "review_launch",
                                 lastError: error instanceof Error ? error.message : String(error),
-                                nextAction: "message target=runtime action=review.retry input={\"scope\":\"tool\"}",
+                                nextAction: "actors_control_apply target=runtime action=review.retry input={\"scope\":\"tool\"}",
                                 phase: "failed",
                                 updatedAt: now().toISOString(),
                             });
@@ -471,7 +471,7 @@ export function createToolReviewScheduler(deps) {
                             failedStage: "review_launch",
                             inputPath: batch.inputPath,
                             lastError: error instanceof Error ? error.message : String(error),
-                            nextAction: "message target=runtime action=review.retry input={\"scope\":\"tool\"}",
+                            nextAction: "actors_control_apply target=runtime action=review.retry input={\"scope\":\"tool\"}",
                             phase: "failed",
                             reviewerInputPath: batch.reviewerInputPath,
                             reviewId: batch.reviewId,

package/dist/lib/tools-access.js

@@ -33,7 +33,7 @@ export function sessionMismatchError(input) {
     const actor = input.run ? `run:${input.run}` : (input.target ?? "session");
     return Object.assign(new Error(`${actor} reason=session_mismatch owner_session=${ownerSession} current_session=${currentSession} hint=inspect_runtime_runs`), {
         current_session: input.currentSession,
-        hint: "inspect target=runtime view=runs",
+        hint: "actors_inspect target=runtime view=runs",
         owner_session: input.expectedSession,
         reason: "session_mismatch",
         run: input.run,

package/dist/lib/tools-inspect.js

@@ -145,10 +145,10 @@ function runtimeTriage(ctx, deps) {
         trace_diagnostic_count: traceDiagnostics.length, trace_diagnostics: traceDiagnostics.slice(0, 40),
         attention_events: attentionEvents.slice(-40).reverse(),
         next_actions: [
-            ...(failed.length ? ["inspect target=runtime view=runs status=failed"] : []),
-            ...new Set([...staleControls, ...backpressuredRuns].slice(0, 3).map((entry) => `inspect target=run:${entry.run} view=control`)),
+            ...(failed.length ? ["actors_inspect target=runtime view=runs status=failed"] : []),
+            ...new Set([...staleControls, ...backpressuredRuns].slice(0, 3).map((entry) => `actors_inspect target=run:${entry.run} view=control`)),
             ...(attentionEvents.length
-                ? attentionEvents.slice(-3).map((entry) => `inspect target=run:${String(entry.run)} view=trace source=runtime`)
+                ? attentionEvents.slice(-3).map((entry) => `actors_inspect target=run:${String(entry.run)} view=trace source=runtime`)
                 : []),
         ],
     };
@@ -209,7 +209,7 @@ function formatInspectFailure(fields, next) {
         return { omittable, full, selected };
     });
     // Only producer-known read-only inspect literals become a typed next, never a parsed action.
-    const typedNext = next ? { next: { tool: "inspect", target: next[0], view: next[1] } } : undefined;
+    const typedNext = next ? { next: { tool: "actors_inspect", target: next[0], view: next[1] } } : undefined;
     const nextFallback = { next_action: omitted };
     const document = () => ({ ...Object.assign({}, ...parts.map((part) => part.selected)),
         ...(typedNext ?? nextFallback) });
@@ -336,15 +336,15 @@ function inspectRecipeIdentity(identity, resolutionContext, namespaces, inventor
         ...(rejectedReason ? { rejected_reason: rejectedReason } : {}),
         next_actions: resolvable
             ? [
-                `spawn recipe=${identity}`,
-                `register_tool name=<tool-name> from=${identity}`,
+                `actors_run_spawn recipe=${identity}`,
+                `actors_tool_register name=<tool-name> from=${identity}`,
             ]
             : roots.length === 0 && skill
                 ? [
                     `activate Skill ${skill}`,
-                    `inspect target=recipes view=doctor identity=${identity}`,
+                    `actors_inspect target=recipes view=doctor identity=${identity}`,
                 ]
-                : ["inspect target=recipes view=imports verbose=true"],
+                : ["actors_inspect target=recipes view=imports verbose=true"],
     };
 }
 function inspectRecipes(requestedView, input, deps, context) {
@@ -583,7 +583,7 @@ function compactResult(target, view, details) {
             ? String(details.next_actions[0])
             : details.callable_now === true
                 ? `call tool ${name}`
-                : `register_tool name=${name} update=true`;
+                : `actors_tool_register name=${name} update=true`;
         const hint = ToolsResponse.nextActionMetadata(next, Limits.RUN_DELIVERY_MODEL_MAX_BYTES);
         const required = compactArguments("required_args", details.required_args);
         const optional = compactArguments("optional_args", details.optional_args);
@@ -601,7 +601,7 @@ function compactResult(target, view, details) {
 }
 export function createInspectToolDefinition(deps = {}) {
     return {
-        name: "inspect",
+        name: "actors_inspect",
         label: "Inspect",
         description: "Inspect a Run's Recipe, Trace, or Control evidence, or runtime/recipe/tool diagnostics.",
         parameters: Schema.objectSchema({

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

@@ -1,5 +1,5 @@
 /**
- * Public Control facade under the stable `message` tool name.
+ * Public Control facade under the stable `actors_control_apply` tool name.
  * Zones: Control request validation, Run/runtime dispatch, recipient-scoped receipts
  * Owns public Control execution; journaling, delivery, and lifecycle mutation stay in Run domains.
  */

package/dist/lib/tools-message.js

@@ -1,5 +1,5 @@
 /**
- * Public Control facade under the stable `message` tool name.
+ * Public Control facade under the stable `actors_control_apply` tool name.
  * Zones: Control request validation, Run/runtime dispatch, recipient-scoped receipts
  * Owns public Control execution; journaling, delivery, and lifecycle mutation stay in Run domains.
  */
@@ -40,9 +40,9 @@ function controlDocument(render, order) {
 }
 /** Only producer-known read-only inspect literals become typed next; other advice stays opaque content. */
 function controlNextPart(action) {
-    const inspect = /^inspect target=([^\s]+) view=([^\s]+)$/u.exec(action);
+    const inspect = /^actors_inspect target=([^\s]+) view=([^\s]+)$/u.exec(action);
     if (inspect) {
-        return ToolsResponse.selectYamlNode("next", { tool: "inspect", target: inspect[1], view: inspect[2] }, CONTROL_BUDGET);
+        return ToolsResponse.selectYamlNode("next", { tool: "actors_inspect", target: inspect[1], view: inspect[2] }, CONTROL_BUDGET);
     }
     const wellFormed = action.isWellFormed();
     const omitted = { next: { instruction: wellFormed ? "[omitted]" : "[unavailable]",
@@ -107,24 +107,24 @@ export function compactControlResult(request, result) {
 }
 function runNextActions(run, result) {
     if (result.stopped === true)
-        return [`inspect target=run:${run} view=trace`];
+        return [`actors_inspect target=run:${run} view=trace`];
     if (result.stopped === false || result.archived === false || result.pruned === false) {
         if (result.reason === "ownership changed" || result.reason === "run generation changed") {
-            return ["inspect target=runtime view=runs"];
+            return ["actors_inspect target=runtime view=runs"];
         }
         if (result.stopped === false && result.reason !== "not running")
-            return [`inspect target=run:${run} view=trace`];
+            return [`actors_inspect target=run:${run} view=trace`];
     }
     if (result.delivery === "queued" || result.delivery === "delivered") {
-        return [`inspect target=run:${run} view=control`];
+        return [`actors_inspect target=run:${run} view=control`];
     }
     return [];
 }
 export function createControlToolDefinition(deps = {}) {
     return {
-        name: "message",
+        name: "actors_control_apply",
         label: "Control",
-        description: "Apply one Control action to an existing Run or the pi-actors runtime.",
+        description: "Apply one Run/runtime Control action. This is not chat or peer messaging.",
         parameters: Schema.objectSchema({
             target: Schema.stringSchema("Run target run:<id>, or literal runtime."),
             action: Schema.stringSchema("Lowercase ASCII Control action, at most 64 characters."),
@@ -214,7 +214,7 @@ export function createControlToolDefinition(deps = {}) {
                         // Admission-era correlation is not current reply-scope proof after an awaited dispatch.
                         // Display one whole caller-owned id or an explicit whole-id omission; the warning stays literal.
                         const identity = controlSelected("run", run);
-                        const next = controlNextPart("inspect target=runtime view=runs");
+                        const next = controlNextPart("actors_inspect target=runtime view=runs");
                         const render = () => ({ ...identity.selected, action: request.action,
                             result: "request failed", delivery: "unconfirmed", handling: "unconfirmed",
                             warning: "Effects may already exist.\nDo not repeat automatically.", ...next.selected });

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

@@ -1,7 +1,7 @@
 /**
- * Public register_tool behavior
- * Zones: runtime tool registration, tool registry mutation, register_tool schema
- * Owns the public register_tool definition that persists local agent capabilities
+ * Public actors_tool_register behavior
+ * Zones: runtime tool registration, tool registry mutation, actors_tool_register schema
+ * Owns the public actors_tool_register definition that persists local agent capabilities
  */
 import * as Registry from "./registry.ts";
 import * as Schema from "./schema.ts";

package/dist/lib/tools-register.js

@@ -1,7 +1,7 @@
 /**
- * Public register_tool behavior
- * Zones: runtime tool registration, tool registry mutation, register_tool schema
- * Owns the public register_tool definition that persists local agent capabilities
+ * Public actors_tool_register behavior
+ * Zones: runtime tool registration, tool registry mutation, actors_tool_register schema
+ * Owns the public actors_tool_register definition that persists local agent capabilities
  */
 import * as Prompts from "./prompts.js";
 import * as Registry from "./registry.js";
@@ -15,7 +15,7 @@ const objectSchema = Schema.objectSchema;
 const looseObjectSchema = Schema.looseObjectSchema;
 export function createRegisterToolDefinition(deps) {
     return {
-        name: "register_tool",
+        name: "actors_tool_register",
         label: "Register Tool",
         description: Prompts.REGISTER_TOOL_DESCRIPTION,
         promptSnippet: Prompts.REGISTER_TOOL_PROMPT_SNIPPET,

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

@@ -28,7 +28,7 @@ export declare function formatYamlNotice(value: Record<string, string | number |
 /** Close one rendered YAML header; a separate opaque body gets exactly one delimiter pair. */
 export declare function frameMetadataDocument(header: string, body?: string): string;
 export declare function formatMarkdownField(key: string, value: string, depth?: number): string;
-export declare function formatInspectNextAction(target: string, view: string, verbose?: boolean): string;
+export declare function formatInspectNextAction(target: string, view: string, verbose?: boolean, tool?: string): string;
 export declare function formatLiteralBlock(value: string): string;
 export type RunSnapshotRendering = {
     readonly state: "available";

package/dist/lib/tools-response.js

@@ -163,8 +163,8 @@ export function formatMarkdownField(key, value, depth = 0) {
         ? `${indent}- ${key}:\n${indent}  ${value.replaceAll(/\r\n|\r|\n/gu, newline => `${newline}${indent}  `)}`
         : `${indent}- ${key}: ${value}`;
 }
-export function formatInspectNextAction(target, view, verbose) {
-    return ["- next:", formatMarkdownField("tool", "inspect", 1), formatMarkdownField("target", target, 1),
+export function formatInspectNextAction(target, view, verbose, tool = "inspect") {
+    return ["- next:", formatMarkdownField("tool", tool, 1), formatMarkdownField("target", target, 1),
         formatMarkdownField("view", view, 1), ...(verbose === undefined ? [] : [formatMarkdownField("verbose", String(verbose), 1)])].join("\n");
 }
 export function formatLiteralBlock(value) {
@@ -292,19 +292,19 @@ function launchModelPolicy(value) {
     }
     return fields;
 }
-const RUN_FILE_INVESTIGATION_COMMAND = "inspect target=runtime view=runs verbose=true";
+const RUN_FILE_INVESTIGATION_COMMAND = "actors_inspect target=runtime view=runs verbose=true";
 /** Frozen older completion-format text: new launch layout must not change this shared packet helper. */
 export function formatRunFileNavigationHandoff() {
-    return `Files (optional; current session):\n\`${RUN_FILE_INVESTIGATION_COMMAND}\``;
+    return "Files (optional; current session):\n`inspect target=runtime view=runs verbose=true`";
 }
 export function runNextActions(run) {
     const id = String(run ?? "").trim();
     if (!id)
         return [];
     return [
-        `inspect target=run:${id} view=recipe`,
-        `inspect target=run:${id} view=trace`,
-        `inspect target=run:${id} view=control`,
+        `actors_inspect target=run:${id} view=recipe`,
+        `actors_inspect target=run:${id} view=trace`,
+        `actors_inspect target=run:${id} view=control`,
         RUN_FILE_INVESTIGATION_COMMAND,
     ];
 }
@@ -342,7 +342,7 @@ export function compactAsyncRunStatus(value) {
         fields.killed = true;
     if (status.draft_recipe)
         fields.draft_recipe = String(status.draft_recipe);
-    const hint = { file_investigation: "optional; current session", next: { tool: "inspect", target: "runtime", view: "runs", verbose: true } };
+    const hint = { file_investigation: "optional; current session", next: { tool: "actors_inspect", target: "runtime", view: "runs", verbose: true } };
     const hasNavigation = Object.hasOwn(status, "file_navigation");
     let navigation;
     if (hasNavigation) {
@@ -504,23 +504,23 @@ export function recipeRegistryNextActions(summary, view) {
         : 0;
     const topAction = asRecord(summary.top_action);
     if (view !== "doctor" && (invalid > 0 || diagnostics > 0)) {
-        actions.push("inspect target=recipes view=doctor");
+        actions.push("actors_inspect target=recipes view=doctor");
     }
     if (view === "doctor" && typeof topAction.action === "string") {
         actions.push(String(topAction.action));
     }
     if (summary.skill_recipe_catalog_partial === true) {
-        actions.push("inspect target=recipes view=imports verbose=true");
+        actions.push("actors_inspect target=recipes view=imports verbose=true");
     }
     if ((Array.isArray(summary.retained) && summary.retained.length > 0) ||
         (Array.isArray(summary.retained_diagnostics) && summary.retained_diagnostics.length > 0)) {
-        actions.push("inspect target=recipes view=summary verbose=true");
+        actions.push("actors_inspect target=recipes view=summary verbose=true");
     }
     if (drafts.length > 0) {
-        actions.push("inspect target=recipes view=summary verbose=true");
+        actions.push("actors_inspect target=recipes view=summary verbose=true");
         const firstPath = typeof drafts[0]?.path === "string" ? drafts[0].path : undefined;
         if (firstPath)
-            actions.push(`spawn file=${firstPath}`);
+            actions.push(`actors_run_spawn file=${firstPath}`);
     }
     return [...new Set(actions)].slice(0, 4);
 }
@@ -530,11 +530,11 @@ export function compactYamlDocument(value) {
     return `\n${text.replace(/\n$/u, "")}`;
 }
 function recipeInspectionHint(action) {
-    if (action === "inspect target=recipes view=doctor")
+    if (action === "actors_inspect target=recipes view=doctor")
         return { view: "doctor" };
-    if (action === "inspect target=recipes view=imports verbose=true")
+    if (action === "actors_inspect target=recipes view=imports verbose=true")
         return { view: "imports", verbose: true };
-    if (action === "inspect target=recipes view=summary verbose=true")
+    if (action === "actors_inspect target=recipes view=summary verbose=true")
         return { view: "summary", verbose: true };
     return undefined;
 }
@@ -542,7 +542,7 @@ function recipeInspectionHint(action) {
 export function nextActionMetadata(action, byteBudget) {
     const hint = recipeInspectionHint(action);
     if (hint) {
-        const typed = { next: { tool: "inspect", target: "recipes", ...hint } };
+        const typed = { next: { tool: "actors_inspect", target: "recipes", ...hint } };
         return { full: typed, selected: typed };
     }
     const instruction = selectYamlField("instruction", action, byteBudget);
@@ -551,7 +551,7 @@ export function nextActionMetadata(action, byteBudget) {
 /** Only these existing read-only inspection hints become action nodes; other advice stays content. */
 export function formatInspectionHint(action) {
     const hint = recipeInspectionHint(action);
-    return hint ? formatInspectNextAction("recipes", hint.view, hint.verbose) : formatMarkdownField("instruction", action);
+    return hint ? formatInspectNextAction("recipes", hint.view, hint.verbose, "actors_inspect") : formatMarkdownField("instruction", action);
 }
 export function compactRecipeRegistry(summary) {
     const count = (key, source) => Array.isArray(source) ? source.length : 0;

package/dist/lib/tools-spawn.js

@@ -90,7 +90,7 @@ function runIdFromTarget(target) {
 }
 export function createSpawnToolDefinition() {
     return {
-        name: "spawn",
+        name: "actors_run_spawn",
         label: "Spawn",
         description: "Create one controllable Run from a Recipe file or inline command template.",
         parameters: Schema.objectSchema({

package/dist/lib/tools.d.ts

@@ -25,4 +25,11 @@ export interface CoreActorToolDefinitionDeps<TContext extends RuntimeToolContext
 }
 export declare function resolveActiveRuntimeTool(name: string, activeTools: Pick<Map<string, unknown>, "has">, getDefinition: (name: string) => unknown): unknown;
 export declare const RESERVED_TOOL_NAMES: Set<string>;
+export declare const LEGACY_TOOL_NAMES: {
+    readonly register_tool: "actors_tool_register";
+    readonly spawn: "actors_run_spawn";
+    readonly message: "actors_control_apply";
+    readonly inspect: "actors_inspect";
+};
+export declare function createLegacyActorToolDefinitions(definitions: ActorToolDefinition[]): ActorToolDefinition[];
 export declare function createCoreActorToolDefinitions<TContext extends RuntimeToolContext>(deps: CoreActorToolDefinitionDeps<TContext>): ActorToolDefinition[];

package/dist/lib/tools.js

@@ -18,11 +18,36 @@ export const RESERVED_TOOL_NAMES = new Set([
     "find",
     "grep",
     "ls",
+    "actors_tool_register",
+    "actors_run_spawn",
+    "actors_control_apply",
+    "actors_inspect",
     "register_tool",
     "message",
     "spawn",
     "inspect",
 ]);
+// Compatibility dispatch is registered but omitted from model declarations and normal
+// callable listings. Active legacy names still execute saved native tool calls.
+export const LEGACY_TOOL_NAMES = {
+    register_tool: "actors_tool_register",
+    spawn: "actors_run_spawn",
+    message: "actors_control_apply",
+    inspect: "actors_inspect",
+};
+export function createLegacyActorToolDefinitions(definitions) {
+    return Object.entries(LEGACY_TOOL_NAMES).map(([name, canonical]) => {
+        const definition = definitions.find((tool) => tool.name === canonical);
+        if (!definition)
+            throw new Error(`Missing canonical actor tool: ${canonical}`);
+        return {
+            ...definition, name, exposure: "deferred",
+            description: `Compatibility dispatch for ${canonical}; use the canonical tool for new calls.`,
+            promptSnippet: undefined, promptGuidelines: undefined,
+            prepareLoadout: () => ({ hiddenDeclarations: Object.keys(LEGACY_TOOL_NAMES) }),
+        };
+    });
+}
 export function createCoreActorToolDefinitions(deps) {
     return [
         ToolsRegister.createRegisterToolDefinition({