@llblab/pi-actors 0.58.0 → 0.58.2

package/lib/run-delivery.ts

@@ -69,7 +69,7 @@ export interface RunCompletionBatch {
   /** Retained singleton capture; absence preserves older indexed bytes. Never a new-capture selector. */
   readonly single_result?: true;
   /** Captured record-list shape; no public format/version choice or source authority. */
-  readonly result_layout?: "records" | "run_headers" | "headings" | "headings_flat_omissions" | "headings_outcomes" | "headings_shared_results" | "headings_shared_kinds" | "frontmatter_v1" | "frontmatter_v2" | "completion_yaml_core_v1" | "completion_yaml_files_v1";
+  readonly result_layout?: "records" | "run_headers" | "headings" | "headings_flat_omissions" | "headings_outcomes" | "headings_shared_results" | "headings_shared_kinds" | "frontmatter_v1" | "frontmatter_v2" | "completion_yaml_core_v1" | "completion_yaml_files_v1" | "completion_yaml_files_v2";
   /** Immutable scope/order/range data, not a caller-selected format or allocation authority. */
   readonly numbering?: RunCompletionNumbering;
   /** Formatting version/data only; no recipient ownership, read or publication capability. */
@@ -467,8 +467,12 @@ function isFrontmatterCompletionLayout(layout: unknown): boolean {
   return layout === "frontmatter_v1" || layout === "frontmatter_v2";
 }
 
+function isRootedCompletionLayout(layout: unknown): boolean {
+  return layout === "completion_yaml_files_v1" || layout === "completion_yaml_files_v2";
+}
+
 function isYamlCompletionLayout(layout: unknown): boolean {
-  return layout === "completion_yaml_core_v1" || layout === "completion_yaml_files_v1";
+  return layout === "completion_yaml_core_v1" || isRootedCompletionLayout(layout);
 }
 
 function isSharedCompletionLayout(layout: unknown): boolean {
@@ -895,7 +899,7 @@ export function requestRunCompletionStream(input: { tempDir: string; ownerId: st
 }
 
 export function admitRunCompletionBatch(input: AdmitRunCompletionBatchInput): RunCompletionBatch {
-  return captureCompletionBatch(input, false, "completion_yaml_files_v1");
+  return captureCompletionBatch(input, false, "completion_yaml_files_v2");
 }
 
 /** Kernel-only opt-in; ordinary Pi capture stays fenced until session/lifecycle integration is admitted. */
@@ -905,10 +909,10 @@ export function captureRunCompletionStreamBatch(input: AdmitRunCompletionBatchIn
 
 /** Private ordinary candidate composition; stream capture retains its separately gated codec. */
 export function captureRunCompletionYamlCandidateBatch(input: AdmitRunCompletionBatchInput): RunCompletionBatch {
-  return captureCompletionBatch(input, false, "completion_yaml_files_v1");
+  return captureCompletionBatch(input, false, "completion_yaml_files_v2");
 }
 
-function captureCompletionBatch(input: AdmitRunCompletionBatchInput, numbered: boolean, layout: "frontmatter_v2" | "completion_yaml_core_v1" | "completion_yaml_files_v1" = "frontmatter_v2"): RunCompletionBatch {
+function captureCompletionBatch(input: AdmitRunCompletionBatchInput, numbered: boolean, layout: "frontmatter_v2" | "completion_yaml_core_v1" | "completion_yaml_files_v1" | "completion_yaml_files_v2" = "frontmatter_v2"): RunCompletionBatch {
   const now = (input.now ?? new Date()).toISOString();
   if (Object.hasOwn(input, "presentationFormat")) throw new Error("Completion presentation selection is not supported; new batches use AX.");
   if (Object.hasOwn(input, "numbering")) throw new Error("Completion numbering is assigned only by journal capture");
@@ -1869,12 +1873,13 @@ type PreparedCompletionYamlProjection =
 function prepareCompletionYamlProjection(safe: RunCompletionBatch, candidates: readonly { row: CompletionRow; location?: CompletionPiece }[],
   references: ReadonlySet<number>, ordered: readonly RunCompletionBatchMember[]): PreparedCompletionYamlProjection {
   const packet: CompletionYamlPacket = { batchId: safe.batch_id, records: [] };
-  const rooted = safe.result_layout === "completion_yaml_files_v1";
+  const rooted = isRootedCompletionLayout(safe.result_layout);
+  const localSingleton = safe.result_layout === "completion_yaml_files_v2" && !safe.numbering && candidates.length === 1;
   if (!safe.batch_id.isWellFormed()) return { state: "unsupported" };
   for (const [index, { row, location }] of candidates.entries()) {
     const member = ordered[index]!;
     const displayed = safe.numbering ? safe.numbering.kind === "stream" ? safe.numbering.first_index + index : "?" : index;
-    const metadata: Record<string, CompletionYamlData> = { index: displayed };
+    const metadata: Record<string, CompletionYamlData> = localSingleton ? {} : { index: displayed };
     for (const piece of row.pieces) {
       if (piece.block) continue;
       if (!piece.field) return { state: "unsupported" };
@@ -1917,7 +1922,9 @@ function prepareCompletionYamlProjection(safe: RunCompletionBatch, candidates: r
     }
     packet.records.push({ metadata, parts });
   }
-  const service: Record<string, CompletionYamlData> = rooted ? { header_layout: "rooted_files_v1" } : {};
+  const service: Record<string, CompletionYamlData> = rooted ? {
+    header_layout: safe.result_layout === "completion_yaml_files_v2" ? "rooted_files_v2" : "rooted_files_v1",
+  } : {};
   const omitted = safe.members.length - candidates.length;
   if (omitted) {
     service.omitted_results = omitted;
@@ -2349,7 +2356,7 @@ export function readRunCompletionPresentation(content: string, value: unknown):
         !completionYamlKeys(hint, ["format", "content_sha256"]) || hint.format !== completionYamlCodec ||
         hint.content_sha256 !== createHash("sha256").update(content).digest("hex")) return full;
     const segments: NonNullable<RunCompletionPresentationView["segments"]>[number][] = [];
-    const rooted = core.packet.service?.header_layout === "rooted_files_v1";
+    const rooted = core.packet.service?.header_layout === "rooted_files_v1" || core.packet.service?.header_layout === "rooted_files_v2";
     const facts = Object.fromEntries(Object.entries(core.packet.service ?? {}).filter(([key]) => key !== "header_layout"));
     for (const [index, record] of core.packet.records.entries()) {
       if (index) segments.push({ kind: "separator", text: "\n" });
@@ -2581,6 +2588,8 @@ export function encodeCompletionYamlCarrier(input: unknown): { state: "available
       typeof packet.batchId !== "string" || !packet.batchId.length || !Array.isArray(packet.records) || packet.records.length > 64 ||
       (Object.hasOwn(packet, "service") && (!completionYamlMapping(packet.service) || !Object.keys(packet.service).length)) ||
       (!packet.records.length && !Object.hasOwn(packet, "service"))) return unavailable;
+  const localSingleton = packet.records.length === 1 && completionYamlMapping(packet.service) &&
+    packet.service.header_layout === "rooted_files_v2" && !Object.hasOwn(packet.service, "numbering");
   const rows: string[] = [];
   for (let index = 0; index < Math.max(1, packet.records.length); index++) {
     const row: CompletionYamlData | undefined = packet.records[index];
@@ -2596,13 +2605,15 @@ export function encodeCompletionYamlCarrier(input: unknown): { state: "available
       if (!completionYamlMapping(row) || !completionYamlKeys(row, ["metadata", "parts"]) ||
           !completionYamlMapping(row.metadata) || !Array.isArray(row.parts)) return unavailable;
       const meta = row.metadata;
-      if (!(meta.index === "?" || (typeof meta.index === "number" && Number.isSafeInteger(meta.index) && meta.index >= 0)) ||
+      const validIndex = localSingleton ? !Object.hasOwn(meta, "index")
+        : meta.index === "?" || (typeof meta.index === "number" && Number.isSafeInteger(meta.index) && meta.index >= 0);
+      if (!validIndex ||
           typeof meta.run !== "string" || !meta.run.length || typeof meta.state !== "string" || !meta.state.length ||
           (Object.hasOwn(meta, "kind") && meta.kind !== "primary" && meta.kind !== "diagnostic") ||
           Object.hasOwn(meta, completionYamlServiceKey) ||
           // JS enumerates array-index keys before semantic core fields; do not silently reorder the header.
           Object.keys(meta).some(key => /^(0|[1-9]\d*)$/u.test(key) && Number(key) < 4294967295)) return unavailable;
-      for (const key of ["index", "run", "state", ...(Object.hasOwn(meta, "kind") ? ["kind"] : []),
+      for (const key of [...(localSingleton ? [] : ["index"]), "run", "state", ...(Object.hasOwn(meta, "kind") ? ["kind"] : []),
         ...Object.keys(meta).filter(key => !["index", "run", "state", "kind"].includes(key))]) {
         Object.defineProperty(header, key, { value: meta[key]!, enumerable: true });
       }

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) {

package/lib/tool-review-scheduler.ts

@@ -404,7 +404,7 @@ export function applyApprovedToolReviewAtSessionBoundary(
         ...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" as const,
         updatedAt: (options.now ?? (() => new Date()))().toISOString(),
       };
@@ -427,7 +427,7 @@ export function applyApprovedToolReviewAtSessionBoundary(
           ...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" as const,
           updatedAt: (options.now ?? (() => new Date()))().toISOString(),
         };
@@ -458,7 +458,7 @@ export function applyApprovedToolReviewAtSessionBoundary(
           ...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 };
@@ -478,7 +478,7 @@ export function applyApprovedToolReviewAtSessionBoundary(
         ...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" as const,
         updatedAt: (options.now ?? (() => new Date()))().toISOString(),
       };
@@ -541,7 +541,7 @@ export function createToolReviewScheduler(
           ...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",
@@ -577,7 +577,7 @@ export function createToolReviewScheduler(
             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(),
           } satisfies ToolReviewAdmissionState);
@@ -612,7 +612,7 @@ export function createToolReviewScheduler(
           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/lib/tools-access.ts

@@ -55,7 +55,7 @@ export function sessionMismatchError(input: {
     ),
     {
       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/lib/tools-inspect.ts

@@ -171,13 +171,13 @@ function runtimeTriage(
     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"] : []),
+      ...(failed.length ? ["actors_inspect target=runtime view=runs status=failed"] : []),
       ...new Set([...staleControls, ...backpressuredRuns].slice(0, 3).map((entry) =>
-        `inspect target=run:${entry.run} view=control`,
+        `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`,
+            `actors_inspect target=run:${String(entry.run)} view=trace source=runtime`,
           )
         : []),
     ],
@@ -247,7 +247,7 @@ function formatInspectFailure(
     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) });
@@ -412,15 +412,15 @@ function inspectRecipeIdentity(
     ...(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"],
   };
 }
 
@@ -707,7 +707,7 @@ function compactResult(target: string, view: string, details: Record<string, unk
       ? 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);
@@ -727,7 +727,7 @@ export function createInspectToolDefinition<TContext = unknown>(
   deps: InspectToolDeps<TContext> = {},
 ): any {
   return {
-    name: "inspect",
+    name: "actors_inspect",
     label: "Inspect",
     description:
       "Inspect a Run's Recipe, Trace, or Control evidence, or runtime/recipe/tool diagnostics.",

package/lib/tools-message.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.
  */
@@ -52,9 +52,9 @@ function controlDocument(render: () => ControlDocument, order: readonly ControlP
 
 /** Only producer-known read-only inspect literals become typed next; other advice stays opaque content. */
 function controlNextPart(action: string): ControlPart {
-  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: ControlDocument = { next: { instruction: wellFormed ? "[omitted]" : "[unavailable]",
@@ -123,15 +123,15 @@ export function compactControlResult(
 }
 
 function runNextActions(run: string, result: Record<string, unknown>): string[] {
-  if (result.stopped === true) return [`inspect target=run:${run} view=trace`];
+  if (result.stopped === true) 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`];
+    if (result.stopped === false && result.reason !== "not running") 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 [];
 }
@@ -148,10 +148,10 @@ export function createControlToolDefinition<TContext = unknown>(
   deps: ControlToolDeps = {},
 ): any {
   return {
-    name: "message",
+    name: "actors_control_apply",
     label: "Control",
     description:
-      "Apply one Control action to an existing Run or the pi-actors runtime.",
+      "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."),
@@ -260,7 +260,7 @@ export function createControlToolDefinition<TContext = unknown>(
             // 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 = (): ControlDocument => ({ ...identity.selected, action: request.action,
               result: "request failed", delivery: "unconfirmed", handling: "unconfirmed",
               warning: "Effects may already exist.\nDo not repeat automatically.", ...next.selected });

package/lib/tools-register.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 Prompts from "./prompts.ts";
@@ -24,7 +24,7 @@ export function createRegisterToolDefinition<TContext>(
   deps: RegisterToolRuntimeDeps<TContext>,
 ) {
   return {
-    name: "register_tool",
+    name: "actors_tool_register",
     label: "Register Tool",
     description: Prompts.REGISTER_TOOL_DESCRIPTION,
     promptSnippet: Prompts.REGISTER_TOOL_PROMPT_SNIPPET,

package/lib/tools-response.ts

@@ -154,8 +154,8 @@ export function formatMarkdownField(key: string, value: string, depth = 0): stri
     : `${indent}- ${key}: ${value}`;
 }
 
-export function formatInspectNextAction(target: string, view: string, verbose?: boolean): string {
-  return ["- next:", formatMarkdownField("tool", "inspect", 1), formatMarkdownField("target", target, 1),
+export function formatInspectNextAction(target: string, view: string, verbose?: boolean, tool = "inspect"): string {
+  return ["- next:", formatMarkdownField("tool", tool, 1), formatMarkdownField("target", target, 1),
     formatMarkdownField("view", view, 1), ...(verbose === undefined ? [] : [formatMarkdownField("verbose", String(verbose), 1)])].join("\n");
 }
 
@@ -289,20 +289,20 @@ function launchModelPolicy(value: unknown): Record<string, unknown> {
   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(): string {
-  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: unknown): string[] {
   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,
   ];
 }
@@ -329,7 +329,7 @@ export function compactAsyncRunStatus(value: unknown): string {
   }
   if (result.killed === true) 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: unknown;
   if (hasNavigation) {
@@ -509,25 +509,25 @@ export function recipeRegistryNextActions(
     : 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}`);
+    if (firstPath) actions.push(`actors_run_spawn file=${firstPath}`);
   }
   return [...new Set(actions)].slice(0, 4);
 }
@@ -538,16 +538,18 @@ export function compactYamlDocument(value: Record<string, unknown>): string {
   return `\n${text.replace(/\n$/u, "")}`;
 }
 
+function recipeInspectionHint(action: string): { view: "doctor" | "imports" | "summary"; verbose?: true } | undefined {
+  if (action === "actors_inspect target=recipes view=doctor") return { view: "doctor" };
+  if (action === "actors_inspect target=recipes view=imports verbose=true") return { view: "imports", verbose: true };
+  if (action === "actors_inspect target=recipes view=summary verbose=true") return { view: "summary", verbose: true };
+  return undefined;
+}
+
 /** Only the closed read-only Recipe inspect literals become typed next; other advice stays opaque content. */
 export function nextActionMetadata(action: string, byteBudget: number): YamlPart {
-  const recognized = [
-    ["inspect target=recipes view=doctor", "doctor", false],
-    ["inspect target=recipes view=imports verbose=true", "imports", true],
-    ["inspect target=recipes view=summary verbose=true", "summary", true],
-  ] as const;
-  const match = recognized.find(([literal]) => literal === action);
-  if (match) {
-    const typed = { next: { tool: "inspect", target: "recipes", view: match[1], ...(match[2] ? { verbose: true } : {}) } };
+  const hint = recipeInspectionHint(action);
+  if (hint) {
+    const typed = { next: { tool: "actors_inspect", target: "recipes", ...hint } };
     return { full: typed, selected: typed };
   }
   const instruction = selectYamlField("instruction", action, byteBudget);
@@ -556,10 +558,8 @@ export function nextActionMetadata(action: string, byteBudget: number): YamlPart
 
 /** Only these existing read-only inspection hints become action nodes; other advice stays content. */
 export function formatInspectionHint(action: string): string {
-  if (action === "inspect target=recipes view=doctor") return formatInspectNextAction("recipes", "doctor");
-  if (action === "inspect target=recipes view=imports verbose=true") return formatInspectNextAction("recipes", "imports", true);
-  if (action === "inspect target=recipes view=summary verbose=true") return formatInspectNextAction("recipes", "summary", true);
-  return formatMarkdownField("instruction", action);
+  const hint = recipeInspectionHint(action);
+  return hint ? formatInspectNextAction("recipes", hint.view, hint.verbose, "actors_inspect") : formatMarkdownField("instruction", action);
 }
 
 export function compactRecipeRegistry(

package/lib/tools-spawn.ts

@@ -124,7 +124,7 @@ export function createSpawnToolDefinition<
   TContext extends SpawnToolContext,
 >(): any {
   return {
-    name: "spawn",
+    name: "actors_run_spawn",
     label: "Spawn",
     description:
       "Create one controllable Run from a Recipe file or inline command template.",

package/lib/tools.ts

@@ -54,12 +54,40 @@ 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",
+} as const;
+
+export function createLegacyActorToolDefinitions(
+  definitions: ActorToolDefinition[],
+): ActorToolDefinition[] {
+  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<
   TContext extends RuntimeToolContext,
 >(deps: CoreActorToolDefinitionDeps<TContext>): ActorToolDefinition[] {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-actors",
-  "version": "0.58.0",
+  "version": "0.58.2",
   "private": false,
   "description": "Local Actor Kernel for Pi",
   "keywords": [