@capybara-hq/kernel 0.1.0-rc.2 → 0.1.0-rc.3

package/dist/tools/registry.d.ts

@@ -7,13 +7,8 @@ import { KernelConfigService } from "../infra/config/kernel-config.service.js";
 import { KernelDb } from "../infra/database/kernel-db.js";
 import type { OrgRole } from "../orgs/roles.js";
 import { BuiltinTools } from "./builtins/builtin-tools.js";
+export { BUILTIN_TOOL_NAMES } from "./builtin-names.js";
 export { canonicalJson } from "./canonical-json.js";
-/**
- * 内核内置工具的名字（Task 10 / Task 19 实现；M5 T8 加沙箱工具）。保存 agent 时内置工具引用按这份清单校验，
- * 不依赖当前是否已注册，避免实现落地顺序影响已保存的定义；运行时未注册的照常报不可用。
- * `skill_write`（M5 T15）由 agent 定义显式引用才可用（负责人决定 agent 能否改自己的技能）。
- */
-export declare const BUILTIN_TOOL_NAMES: readonly ["ask_user", "read_tool_output", "tool_search", "skill_load", "skill_write", "sandbox_bash", "sandbox_read", "sandbox_write", "sandbox_edit", "sandbox_glob", "sandbox_grep", "sandbox_deliver", "agent"];
 /** 保存 agent 时引用校验的问题（`path` 为 `tools.<i>`）。 */
 export interface ToolRefIssue {
     path: string;
@@ -21,7 +16,7 @@ export interface ToolRefIssue {
 }
 /**
  * 内置工具处理函数的上下文：在 SDK 的 `ToolCallContext` 之上，管线额外传入本步解析出的工具
- * （`tool_search` 据此搜索）。插件处理函数收到的仍是 `ToolCallContext`。
+ * （`ToolSearch` 据此搜索）。插件处理函数收到的仍是 `ToolCallContext`。
  */
 export interface BuiltinCallContext extends ToolCallContext {
     tools?: readonly ResolvedTool[];
@@ -39,7 +34,7 @@ export interface BuiltinCallContext extends ToolCallContext {
     sandboxConversationId?: string;
 }
 /**
- * 内置工具的结果：`ToolResult` 之外可带 `loadedTools`（`tool_search` 加载的工具 key，
+ * 内置工具的结果：`ToolResult` 之外可带 `loadedTools`（`ToolSearch` 加载的工具 key，
  * 管线写进 `tool_result.loadedTools`）。
  */
 export type BuiltinResult = (ToolResult & {
@@ -52,7 +47,7 @@ export type BuiltinResult = (ToolResult & {
 }) | InputRequired;
 /** 内置工具的处理函数（插件的 `ToolHandler` 可直接赋给它）。 */
 export type BuiltinHandler = (input: unknown, ctx: BuiltinCallContext) => Promise<BuiltinResult>;
-/** 内核内置工具（`ask_user` 等，Task 10 实现具体工具）；key 就是 `spec.name`。 */
+/** 内核内置工具（`AskUserQuestion` 等，Task 10 实现具体工具）；key 就是 `spec.name`。 */
 export interface BuiltinTool {
     spec: ToolSpec;
     defaultPolicy: "allow" | "ask";
@@ -116,7 +111,7 @@ export interface ResolvedTool {
      */
     requiredRole?: OrgRole;
 }
-/** 不可用的引用：`ref` 尽量写成模型认识的工具 key（`docs__search`、`docs__*`），否则 `app:<id>`。 */
+/** 不可用的引用：`ref` 尽量写成模型认识的工具 key（`mcp__docs__search`、`mcp__docs__*`），否则 `app:<id>`。 */
 export interface UnavailableTool {
     ref: string;
     reason: string;
@@ -148,7 +143,7 @@ export interface AgentTools {
      */
     hidden?: UnavailableTool[];
     /**
-     * 本步是否启用 `tool_search`（spec 5.5）：启用时 `tools` 末尾含 `tool_search`，构建请求时只放内置工具
+     * 本步是否启用 `ToolSearch`（spec 5.5）：启用时 `tools` 末尾含 `ToolSearch`，构建请求时只放内置工具
      * 与已加载工具的完整定义，其余进目录。缺省视为未启用。
      */
     toolSearch?: boolean;
@@ -178,7 +173,7 @@ export declare class ToolRegistry {
     private readonly extensions;
     private readonly builtinTools;
     /**
-     * `tools.searchThreshold*` and the sub-agent limits. Absent (some tests): `tool_search` is never
+     * `tools.searchThreshold*` and the sub-agent limits. Absent (some tests): `ToolSearch` is never
      * offered and the sub-agent limits are the schema defaults.
      */
     private readonly config?;
@@ -188,11 +183,11 @@ export declare class ToolRegistry {
     /** The installed connectors (`connector@1`, from the extension registry). */
     extensions: Pick<ExtensionRegistry, "list">, builtinTools: Pick<BuiltinTools, "list">, 
     /**
-     * `tools.searchThreshold*` and the sub-agent limits. Absent (some tests): `tool_search` is never
+     * `tools.searchThreshold*` and the sub-agent limits. Absent (some tests): `ToolSearch` is never
      * offered and the sub-agent limits are the schema defaults.
      */
     config?: Pick<KernelConfigService, "get"> | undefined);
-    /** The kernel's builtin tools (`tool_search` is added by {@link forAgent}, not by definitions). */
+    /** The kernel's builtin tools (`ToolSearch` is added by {@link forAgent}, not by definitions). */
     private get builtins();
     /** `host.list("connector")` 中 `kind` 匹配的第一个实现；未安装返回 undefined。 */
     findConnector(kind: string): Connector | undefined;
@@ -228,23 +223,23 @@ export declare class ToolRegistry {
         issues: ToolRefIssue[];
     }>;
     /**
-     * 解析 agent 引用的工具（见类注释），再判定是否启用 `tool_search`：组织设置 `toolSearch === "on"`，且
+     * 解析 agent 引用的工具（见类注释），再判定是否启用 `ToolSearch`：组织设置 `toolSearch === "on"`，且
      * 可用工具数 > `tools.searchThresholdTools` 或其定义的估算 token > `tools.searchThresholdTokens`。
-     * 启用时把内置 `tool_search` 追加到末尾。定义里显式引用的 `tool_search` 忽略（由这里按设置管理）。
-     * `skillLoad`：对话日志里有技能目录快照（`skills_catalog`，Ruling M17）→ 加入内置 `skill_load`（始终完整加载）；
-     * 定义里显式引用的 `skill_load` 同样忽略。
+     * 启用时把内置 `ToolSearch` 追加到末尾。定义里显式引用的 `ToolSearch` 忽略（由这里按设置管理）。
+     * `skillLoad`：对话日志里有技能目录快照（`skills_catalog`，Ruling M17）→ 加入内置 `Skill`（始终完整加载）；
+     * 定义里显式引用的 `Skill` 同样忽略。
      */
     forAgent(orgId: string, def: {
         tools: readonly AgentToolRef[];
         skillLoad?: boolean;
-        /** The definition's sub-agent roster source: the `agent` tool's description lists it. */
+        /** The definition's sub-agent roster source: the `Agent` tool's description lists it. */
         subagents?: AgentDefinition["subagents"];
     }): Promise<AgentTools>;
-    /** 是否启用 `tool_search`（见 {@link forAgent}）；先比阈值，超过才读组织设置。 */
+    /** 是否启用 `ToolSearch`（见 {@link forAgent}）；先比阈值，超过才读组织设置。 */
     private searchActive;
     private resolve;
     /**
-     * `subagents.maxConcurrentPerRun` with the organization's override, for the `agent` tool's
+     * `subagents.maxConcurrentPerRun` with the organization's override, for the `Agent` tool's
      * description (§4.3). A change of the limit changes the tool's spec hash; replays read the
      * definition logged by hash, so no drift reason is involved. Without config (some tests): the
      * schema default.

package/dist/tools/registry.js

@@ -8,6 +8,7 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
     return function (target, key) { decorator(target, key, paramIndex); }
 };
 import { createHash } from "node:crypto";
+import { connectorToolKey, extensionToolKey } from "@capybara-hq/plugin-sdk";
 import { Inject, Injectable } from "@nestjs/common";
 import { ExtensionHost } from "../extensions/host.js";
 import { ExtensionRegistry } from "../extensions/registry.js";
@@ -17,27 +18,14 @@ import { readOrgSettings } from "../orgs/settings.service.js";
 import { estimateTokens } from "../runtime/context/tokens.js";
 import { SUBAGENT_LIMIT_DEFAULTS, subagentLimits } from "../runtime/subagents/limits.js";
 import { resolveRoster } from "../runtime/subagents/roster.js";
-import { AGENT_TOOL, agentToolSpec } from "./builtins/agent.js";
+import { AGENT_TOOL, BUILTIN_TOOL_NAMES, SKILL_LOAD, TOOL_SEARCH } from "./builtin-names.js";
+import { agentToolSpec } from "./builtins/agent.js";
 import { BuiltinTools } from "./builtins/builtin-tools.js";
-import { SANDBOX_TOOL_NAMES } from "./builtins/sandbox/names.js";
 import { canonicalJson } from "./canonical-json.js";
-import { toolKey, toolKeyIssue } from "./naming.js";
+import { legacyKeySaveText } from "./legacy-keys.js";
+import { toolKeyIssue } from "./naming.js";
+export { BUILTIN_TOOL_NAMES } from "./builtin-names.js";
 export { canonicalJson } from "./canonical-json.js";
-/**
- * 内核内置工具的名字（Task 10 / Task 19 实现；M5 T8 加沙箱工具）。保存 agent 时内置工具引用按这份清单校验，
- * 不依赖当前是否已注册，避免实现落地顺序影响已保存的定义；运行时未注册的照常报不可用。
- * `skill_write`（M5 T15）由 agent 定义显式引用才可用（负责人决定 agent 能否改自己的技能）。
- */
-export const BUILTIN_TOOL_NAMES = [
-    "ask_user",
-    "read_tool_output",
-    "tool_search",
-    "skill_load",
-    "skill_write",
-    ...SANDBOX_TOOL_NAMES,
-    // phase C: dispatches sub-agents; its description is built per agent from the roster
-    "agent",
-];
 /** The first 16 hex digits of sha256(canonicalJson(v)): a fingerprint independent of key order. */
 export function contentHash(v) {
     return createHash("sha256").update(canonicalJson(v)).digest("hex").slice(0, 16);
@@ -68,10 +56,8 @@ export function specHash(spec) {
 export function policyFromAnnotations(a) {
     return a?.readOnlyHint === true ? "allow" : "ask";
 }
-/** 内置 `tool_search` 的名字（由注册表按组织设置与阈值自动加入，不进 agent 定义）。 */
-const TOOL_SEARCH = "tool_search";
-/** 内置 `skill_load` 的名字（对话日志里有技能目录快照时由注册表自动加入，不进 agent 定义）。 */
-const SKILL_LOAD = "skill_load";
+// `ToolSearch` is added by the registry by org setting and threshold, `Skill` when the log has a
+// skills catalog snapshot; neither comes from agent definitions (`./builtin-names.ts`).
 /** 工具定义（模型可见三项）的估算 token 数（与请求估算同一口径）。 */
 function estimateToolTokens(tools) {
     return estimateTokens([], [], tools.map((t) => ({
@@ -114,7 +100,7 @@ let ToolRegistry = class ToolRegistry {
     /** The installed connectors (`connector@1`, from the extension registry). */
     extensions, builtinTools, 
     /**
-     * `tools.searchThreshold*` and the sub-agent limits. Absent (some tests): `tool_search` is never
+     * `tools.searchThreshold*` and the sub-agent limits. Absent (some tests): `ToolSearch` is never
      * offered and the sub-agent limits are the schema defaults.
      */
     config) {
@@ -124,7 +110,7 @@ let ToolRegistry = class ToolRegistry {
         this.builtinTools = builtinTools;
         this.config = config;
     }
-    /** The kernel's builtin tools (`tool_search` is added by {@link forAgent}, not by definitions). */
+    /** The kernel's builtin tools (`ToolSearch` is added by {@link forAgent}, not by definitions). */
     get builtins() {
         return this.builtinTools.list();
     }
@@ -205,13 +191,19 @@ let ToolRegistry = class ToolRegistry {
             const path = `tools.${i}`;
             if (ref.kind === "builtin") {
                 if (!BUILTIN_TOOL_NAMES.includes(ref.name)) {
-                    issues.push({ path, message: `Built-in tool "${ref.name}" does not exist` });
+                    const renamed = legacyKeySaveText(ref.name);
+                    issues.push({
+                        path,
+                        message: renamed === null
+                            ? `Built-in tool "${ref.name}" does not exist`
+                            : `Built-in tool ${renamed}`,
+                    });
                     return;
                 }
                 claim(path, ref.name, `builtin:${ref.name}`);
             }
             else if (ref.kind === "plugin") {
-                const key = toolKey(ref.plugin, ref.name);
+                const key = extensionToolKey(ref.plugin, ref.name);
                 if (!pluginTools.some((x) => x.plugin === ref.plugin && x.spec.name === ref.name)) {
                     issues.push({ path, message: `Plugin tool "${key}" does not exist` });
                     return;
@@ -238,18 +230,18 @@ let ToolRegistry = class ToolRegistry {
                         });
                         continue;
                     }
-                    claim(path, toolKey(app.slug, name), `connector:${app.id}:${name}`);
+                    claim(path, connectorToolKey(app.slug, name), `connector:${app.id}:${name}`);
                 }
             }
         });
         return { keys: new Set(owner.keys()), issues };
     }
     /**
-     * 解析 agent 引用的工具（见类注释），再判定是否启用 `tool_search`：组织设置 `toolSearch === "on"`，且
+     * 解析 agent 引用的工具（见类注释），再判定是否启用 `ToolSearch`：组织设置 `toolSearch === "on"`，且
      * 可用工具数 > `tools.searchThresholdTools` 或其定义的估算 token > `tools.searchThresholdTokens`。
-     * 启用时把内置 `tool_search` 追加到末尾。定义里显式引用的 `tool_search` 忽略（由这里按设置管理）。
-     * `skillLoad`：对话日志里有技能目录快照（`skills_catalog`，Ruling M17）→ 加入内置 `skill_load`（始终完整加载）；
-     * 定义里显式引用的 `skill_load` 同样忽略。
+     * 启用时把内置 `ToolSearch` 追加到末尾。定义里显式引用的 `ToolSearch` 忽略（由这里按设置管理）。
+     * `skillLoad`：对话日志里有技能目录快照（`skills_catalog`，Ruling M17）→ 加入内置 `Skill`（始终完整加载）；
+     * 定义里显式引用的 `Skill` 同样忽略。
      */
     async forAgent(orgId, def) {
         const { tools, unavailable, hidden } = await this.resolve(orgId, def);
@@ -277,7 +269,7 @@ let ToolRegistry = class ToolRegistry {
         }
         return { tools, unavailable, hidden, toolSearch };
     }
-    /** 是否启用 `tool_search`（见 {@link forAgent}）；先比阈值，超过才读组织设置。 */
+    /** 是否启用 `ToolSearch`（见 {@link forAgent}）；先比阈值，超过才读组织设置。 */
     async searchActive(orgId, tools) {
         const cfg = this.config?.get().tools;
         if (!cfg || !this.builtins.some((b) => b.spec.name === TOOL_SEARCH))
@@ -329,7 +321,7 @@ let ToolRegistry = class ToolRegistry {
                     unavailable.push({ ref: ref.name, reason: why });
                     continue;
                 }
-                // `agent`: the description lists this definition's roster (sub-agents spec §4.3); with an
+                // `Agent`: the description lists this definition's roster (sub-agents spec §4.3); with an
                 // empty roster there is nothing to dispatch, so the tool is not offered at all
                 let spec = b.spec;
                 if (b.spec.name === AGENT_TOOL) {
@@ -349,7 +341,7 @@ let ToolRegistry = class ToolRegistry {
                 });
             }
             else if (ref.kind === "plugin") {
-                const key = toolKey(ref.plugin, ref.name);
+                const key = extensionToolKey(ref.plugin, ref.name);
                 const t = pluginTools.find((x) => x.plugin === ref.plugin && x.spec.name === ref.name);
                 if (!t) {
                     unavailable.push({ ref: key, reason: "Plugin tool does not exist" });
@@ -381,7 +373,7 @@ let ToolRegistry = class ToolRegistry {
                     unavailable.push({ ref: `app:${ref.connectorId}`, reason: "App does not exist" });
                     continue;
                 }
-                const all = toolKey(app.slug, "*");
+                const all = connectorToolKey(app.slug, "*");
                 if (app.deleted) {
                     unavailable.push({ ref: all, reason: `App ${app.slug} was deleted` });
                     continue;
@@ -403,7 +395,7 @@ let ToolRegistry = class ToolRegistry {
                 // 「all」里未启用的工具不算 agent 点名要的，不进 unavailable（不提醒），只记进 hidden 备查
                 const notEnabled = ref.tools === "all" ? hidden : unavailable;
                 for (const t of wanted) {
-                    const key = toolKey(app.slug, t.name);
+                    const key = connectorToolKey(app.slug, t.name);
                     // 远端已不再提供（漂移检测置停用并标记，见 drift.ts）：与「没有这一行」同一个事实
                     if ("missing" in t || t.gone) {
                         notEnabled.push({ ref: key, reason: `Tool no longer exists in app ${app.slug}` });
@@ -440,7 +432,7 @@ let ToolRegistry = class ToolRegistry {
         return { tools, unavailable, hidden };
     }
     /**
-     * `subagents.maxConcurrentPerRun` with the organization's override, for the `agent` tool's
+     * `subagents.maxConcurrentPerRun` with the organization's override, for the `Agent` tool's
      * description (§4.3). A change of the limit changes the tool's spec hash; replays read the
      * definition logged by hash, so no drift reason is involved. Without config (some tests): the
      * schema default.

package/dist/tools/resources.d.ts

@@ -1,6 +1,6 @@
 import { type ConnectorSession, type ToolResult, type ToolSpec } from "@capybara-hq/plugin-sdk";
 /**
- * 连接器 resources 的两个内核工具（brief：`<connectorSlug>__list_resources`、`<connectorSlug>__read_resource {uri}`）。
+ * 连接器 resources 的两个内核工具（brief：`mcp__<slug>__list_resources`、`mcp__<slug>__read_resource {uri}`）。
  *
  * 设计：安装 / 刷新连接器时，连接器会话带 `listResources` 方法即视为支持 resources（不额外调用，免得多一次外连
  * 和多一种失败），内核把这两个工具作为 `source = 'resources'` 的行写进 `connector_tools`（迁移 0013）。这样它们和

package/dist/tools/resources.js

@@ -1,6 +1,6 @@
 import { ToolError, } from "@capybara-hq/plugin-sdk";
 /**
- * 连接器 resources 的两个内核工具（brief：`<connectorSlug>__list_resources`、`<connectorSlug>__read_resource {uri}`）。
+ * 连接器 resources 的两个内核工具（brief：`mcp__<slug>__list_resources`、`mcp__<slug>__read_resource {uri}`）。
  *
  * 设计：安装 / 刷新连接器时，连接器会话带 `listResources` 方法即视为支持 resources（不额外调用，免得多一次外连
  * 和多一种失败），内核把这两个工具作为 `source = 'resources'` 的行写进 `connector_tools`（迁移 0013）。这样它们和

package/dist/tools/tools.module.js

@@ -48,7 +48,7 @@ ToolsModule = __decorate([
             StorageModule,
             SkillsModule,
             OrgLockModule,
-            // the `agent` tool's dispatch
+            // the `Agent` tool's dispatch
             SubagentsModule,
             // the builtin sandbox and skill tools run in the conversation's sandbox
             SandboxModule,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@capybara-hq/kernel",
-  "version": "0.1.0-rc.2",
+  "version": "0.1.0-rc.3",
   "description": "Capybara kernel: config, database, plugin host and HTTP API of the Capybara agent platform",
   "license": "Apache-2.0",
   "repository": {
@@ -64,7 +64,7 @@
     "yaml": "^2.9.1",
     "yauzl": "3.4.0",
     "zod": "^4.6.7",
-    "@capybara-hq/plugin-sdk": "^0.1.0-rc.0"
+    "@capybara-hq/plugin-sdk": "^0.1.0-rc.1"
   },
   "devDependencies": {
     "@langchain/langgraph-checkpoint-validation": "^1.2.0",

package/src/migrations/0063_tool_keys_claude_code.sql

@@ -0,0 +1,220 @@
+-- Tool naming (spec docs/superpowers/specs/2026-10-29-tool-naming-claude-code-design.md §8.2):
+-- the release candidates' tool keys in mutable state become the current keys. Builtins by the
+-- frozen map of packages/kernel/src/tools/legacy-keys.ts (LEGACY_BUILTINS); an rc `<x>__<tool>`
+-- key becomes `mcp__<x>__<tool>` when `x` is a connector of the row's org (or the row records its
+-- connector) and `plugin__<x>__<tool>` when `x` is an extension of the deployment
+-- (extension_installs, or extension_name_owners for config-declared ones); when both or neither,
+-- the row stays and the kernel's startup notice `tools.legacy_key_unmapped` counts it.
+-- Keys in the current format never match. A grant whose new key already exists for the same
+-- owner is left as it is (the primary key). Decided approvals and answered questions are
+-- history and stay. Logs and recordings are never rewritten (§8). Idempotent: a second run
+-- matches nothing it could change.
+
+-- capybara:allow-destructive rewrites rc tool keys in place (the old keys no longer name a tool; the kernel reads only the new ones)
+UPDATE tool_grants g
+SET tool_key = m.new_key
+FROM (VALUES
+  ('sandbox_bash', 'Bash'), ('sandbox_read', 'Read'), ('sandbox_write', 'Write'),
+  ('sandbox_edit', 'Edit'), ('sandbox_glob', 'Glob'), ('sandbox_grep', 'Grep'),
+  ('sandbox_deliver', 'Deliver'), ('skill_load', 'Skill'), ('skill_write', 'SkillWrite'),
+  ('ask_user', 'AskUserQuestion'), ('read_tool_output', 'ReadToolOutput'),
+  ('tool_search', 'ToolSearch'), ('agent', 'Agent')
+) AS m(old_key, new_key)
+WHERE g.tool_key = m.old_key
+  AND NOT EXISTS (
+    SELECT 1 FROM tool_grants x
+    WHERE x.org_id = g.org_id AND x.account_id = g.account_id AND x.agent_id = g.agent_id
+      AND x.tool_key = m.new_key
+  );
+
+-- capybara:allow-destructive rewrites rc tool keys in place (the old keys no longer name a tool; the kernel reads only the new ones)
+UPDATE tool_grants g
+SET tool_key = CASE
+  WHEN g.connector_id IS NOT NULL OR (
+    EXISTS (SELECT 1 FROM connectors c
+            WHERE c.org_id = g.org_id AND c.deleted_at IS NULL
+              AND c.slug = split_part(g.tool_key, '__', 1))
+    AND split_part(g.tool_key, '__', 1) NOT IN (
+      SELECT name FROM extension_installs UNION SELECT name FROM extension_name_owners)
+  ) THEN 'mcp__' || g.tool_key
+  ELSE 'plugin__' || g.tool_key
+END
+WHERE g.tool_key ~ '^[a-z0-9][a-z0-9_-]*__.' AND g.tool_key !~ '^(mcp|plugin)__'
+  AND (
+    g.connector_id IS NOT NULL
+    OR (
+      EXISTS (SELECT 1 FROM connectors c
+              WHERE c.org_id = g.org_id AND c.deleted_at IS NULL
+                AND c.slug = split_part(g.tool_key, '__', 1))
+    ) <> (
+      split_part(g.tool_key, '__', 1) IN (
+        SELECT name FROM extension_installs UNION SELECT name FROM extension_name_owners)
+    )
+  )
+  AND NOT EXISTS (
+    SELECT 1 FROM tool_grants x
+    WHERE x.org_id = g.org_id AND x.account_id = g.account_id AND x.agent_id = g.agent_id
+      AND x.tool_key IN ('mcp__' || g.tool_key, 'plugin__' || g.tool_key)
+  );
+
+-- capybara:allow-destructive rewrites rc tool keys in place (the old keys no longer name a tool; the kernel reads only the new ones)
+UPDATE conversation_tool_grants g
+SET tool_key = m.new_key
+FROM (VALUES
+  ('sandbox_bash', 'Bash'), ('sandbox_read', 'Read'), ('sandbox_write', 'Write'),
+  ('sandbox_edit', 'Edit'), ('sandbox_glob', 'Glob'), ('sandbox_grep', 'Grep'),
+  ('sandbox_deliver', 'Deliver'), ('skill_load', 'Skill'), ('skill_write', 'SkillWrite'),
+  ('ask_user', 'AskUserQuestion'), ('read_tool_output', 'ReadToolOutput'),
+  ('tool_search', 'ToolSearch'), ('agent', 'Agent')
+) AS m(old_key, new_key)
+WHERE g.tool_key = m.old_key
+  AND NOT EXISTS (
+    SELECT 1 FROM conversation_tool_grants x
+    WHERE x.conversation_id = g.conversation_id AND x.tool_key = m.new_key
+  );
+
+-- capybara:allow-destructive rewrites rc tool keys in place (the old keys no longer name a tool; the kernel reads only the new ones)
+UPDATE conversation_tool_grants g
+SET tool_key = CASE
+  WHEN g.connector_id IS NOT NULL OR (
+    EXISTS (SELECT 1 FROM connectors c
+            WHERE c.org_id = v.org_id AND c.deleted_at IS NULL
+              AND c.slug = split_part(g.tool_key, '__', 1))
+    AND split_part(g.tool_key, '__', 1) NOT IN (
+      SELECT name FROM extension_installs UNION SELECT name FROM extension_name_owners)
+  ) THEN 'mcp__' || g.tool_key
+  ELSE 'plugin__' || g.tool_key
+END
+FROM conversations v
+WHERE v.id = g.conversation_id
+  AND g.tool_key ~ '^[a-z0-9][a-z0-9_-]*__.' AND g.tool_key !~ '^(mcp|plugin)__'
+  AND (
+    g.connector_id IS NOT NULL
+    OR (
+      EXISTS (SELECT 1 FROM connectors c
+              WHERE c.org_id = v.org_id AND c.deleted_at IS NULL
+                AND c.slug = split_part(g.tool_key, '__', 1))
+    ) <> (
+      split_part(g.tool_key, '__', 1) IN (
+        SELECT name FROM extension_installs UNION SELECT name FROM extension_name_owners)
+    )
+  )
+  AND NOT EXISTS (
+    SELECT 1 FROM conversation_tool_grants x
+    WHERE x.conversation_id = g.conversation_id
+      AND x.tool_key IN ('mcp__' || g.tool_key, 'plugin__' || g.tool_key)
+  );
+
+-- capybara:allow-destructive rewrites rc tool keys of pending approvals in place (resumed by run and call id, never by key)
+UPDATE approvals a
+SET tool_key = m.new_key
+FROM (VALUES
+  ('sandbox_bash', 'Bash'), ('sandbox_read', 'Read'), ('sandbox_write', 'Write'),
+  ('sandbox_edit', 'Edit'), ('sandbox_glob', 'Glob'), ('sandbox_grep', 'Grep'),
+  ('sandbox_deliver', 'Deliver'), ('skill_load', 'Skill'), ('skill_write', 'SkillWrite'),
+  ('ask_user', 'AskUserQuestion'), ('read_tool_output', 'ReadToolOutput'),
+  ('tool_search', 'ToolSearch'), ('agent', 'Agent')
+) AS m(old_key, new_key)
+WHERE a.status = 'pending' AND a.tool_key = m.old_key;
+
+-- capybara:allow-destructive rewrites rc tool keys of pending approvals in place (resumed by run and call id, never by key)
+UPDATE approvals a
+SET tool_key = CASE
+  WHEN a.connector_id IS NOT NULL OR (
+    EXISTS (SELECT 1 FROM connectors c
+            WHERE c.org_id = a.org_id AND c.deleted_at IS NULL
+              AND c.slug = split_part(a.tool_key, '__', 1))
+    AND split_part(a.tool_key, '__', 1) NOT IN (
+      SELECT name FROM extension_installs UNION SELECT name FROM extension_name_owners)
+  ) THEN 'mcp__' || a.tool_key
+  ELSE 'plugin__' || a.tool_key
+END
+WHERE a.status = 'pending'
+  AND a.tool_key ~ '^[a-z0-9][a-z0-9_-]*__.' AND a.tool_key !~ '^(mcp|plugin)__'
+  AND (
+    a.connector_id IS NOT NULL
+    OR (
+      EXISTS (SELECT 1 FROM connectors c
+              WHERE c.org_id = a.org_id AND c.deleted_at IS NULL
+                AND c.slug = split_part(a.tool_key, '__', 1))
+    ) <> (
+      split_part(a.tool_key, '__', 1) IN (
+        SELECT name FROM extension_installs UNION SELECT name FROM extension_name_owners)
+    )
+  );
+
+-- capybara:allow-destructive rewrites rc tool keys of pending questions in place (resumed by run and call id, never by key)
+UPDATE questions q
+SET spec = jsonb_set(q.spec, '{toolKey}', to_jsonb(m.new_key))
+FROM (VALUES
+  ('sandbox_bash', 'Bash'), ('sandbox_read', 'Read'), ('sandbox_write', 'Write'),
+  ('sandbox_edit', 'Edit'), ('sandbox_glob', 'Glob'), ('sandbox_grep', 'Grep'),
+  ('sandbox_deliver', 'Deliver'), ('skill_load', 'Skill'), ('skill_write', 'SkillWrite'),
+  ('ask_user', 'AskUserQuestion'), ('read_tool_output', 'ReadToolOutput'),
+  ('tool_search', 'ToolSearch'), ('agent', 'Agent')
+) AS m(old_key, new_key)
+WHERE q.status = 'pending' AND q.spec->>'toolKey' = m.old_key;
+
+-- capybara:allow-destructive rewrites rc tool keys of pending questions in place (resumed by run and call id, never by key)
+UPDATE questions q
+SET spec = jsonb_set(
+  q.spec,
+  '{toolKey}',
+  to_jsonb(CASE
+    WHEN EXISTS (SELECT 1 FROM connectors c
+                 WHERE c.org_id = q.org_id AND c.deleted_at IS NULL
+                   AND c.slug = split_part(q.spec->>'toolKey', '__', 1))
+    THEN 'mcp__' || (q.spec->>'toolKey')
+    ELSE 'plugin__' || (q.spec->>'toolKey')
+  END)
+)
+WHERE q.status = 'pending'
+  AND q.spec->>'toolKey' ~ '^[a-z0-9][a-z0-9_-]*__.' AND q.spec->>'toolKey' !~ '^(mcp|plugin)__'
+  AND (
+    EXISTS (SELECT 1 FROM connectors c
+            WHERE c.org_id = q.org_id AND c.deleted_at IS NULL
+              AND c.slug = split_part(q.spec->>'toolKey', '__', 1))
+  ) <> (
+    split_part(q.spec->>'toolKey', '__', 1) IN (
+      SELECT name FROM extension_installs UNION SELECT name FROM extension_name_owners)
+  );
+
+-- What the startup notice counts (rows the statements above could not map), each over a partial
+-- index holding only such rows, so the count at every start reads nearly empty indexes. The
+-- predicate is the one of countLegacyToolKeys (packages/kernel/src/tools/legacy-data.ts).
+CREATE INDEX IF NOT EXISTS tool_grants_legacy_key_idx ON tool_grants (org_id)
+  WHERE (tool_key = ANY (ARRAY['sandbox_bash', 'sandbox_read', 'sandbox_write', 'sandbox_edit',
+    'sandbox_glob', 'sandbox_grep', 'sandbox_deliver', 'skill_load', 'skill_write', 'ask_user',
+    'read_tool_output', 'tool_search', 'agent']::text[])
+    OR (tool_key ~ '^[a-z0-9][a-z0-9_-]*__.' AND tool_key !~ '^(mcp|plugin)__'));
+CREATE INDEX IF NOT EXISTS conversation_tool_grants_legacy_key_idx
+  ON conversation_tool_grants (conversation_id)
+  WHERE (tool_key = ANY (ARRAY['sandbox_bash', 'sandbox_read', 'sandbox_write', 'sandbox_edit',
+    'sandbox_glob', 'sandbox_grep', 'sandbox_deliver', 'skill_load', 'skill_write', 'ask_user',
+    'read_tool_output', 'tool_search', 'agent']::text[])
+    OR (tool_key ~ '^[a-z0-9][a-z0-9_-]*__.' AND tool_key !~ '^(mcp|plugin)__'));
+CREATE INDEX IF NOT EXISTS approvals_legacy_key_idx ON approvals (org_id)
+  WHERE status = 'pending'
+    AND (tool_key = ANY (ARRAY['sandbox_bash', 'sandbox_read', 'sandbox_write', 'sandbox_edit',
+    'sandbox_glob', 'sandbox_grep', 'sandbox_deliver', 'skill_load', 'skill_write', 'ask_user',
+    'read_tool_output', 'tool_search', 'agent']::text[])
+    OR (tool_key ~ '^[a-z0-9][a-z0-9_-]*__.' AND tool_key !~ '^(mcp|plugin)__'));
+CREATE INDEX IF NOT EXISTS questions_legacy_key_idx ON questions (org_id)
+  WHERE status = 'pending'
+    AND ((spec->>'toolKey') = ANY (ARRAY['sandbox_bash', 'sandbox_read', 'sandbox_write',
+    'sandbox_edit', 'sandbox_glob', 'sandbox_grep', 'sandbox_deliver', 'skill_load', 'skill_write',
+    'ask_user', 'read_tool_output', 'tool_search', 'agent']::text[])
+    OR ((spec->>'toolKey') ~ '^[a-z0-9][a-z0-9_-]*__.' AND (spec->>'toolKey') !~ '^(mcp|plugin)__'));
+
+-- Read before Write / Edit (spec §4.5): EventLog.latestFileState reads the latest tool_result of
+-- a conversation whose view names a file, on every Write and Edit. Without this index it scans
+-- the conversation's events backwards through the primary key, filtering each payload (EXPLAIN
+-- on a 20 000-event conversation: every row removed by the filter for a path never read); with
+-- it, one index probe. Partial: only tool_result rows. Built without CONCURRENTLY (a migration
+-- runs in one transaction), which locks conversation_events against writes while it builds: this
+-- assumes release-candidate-sized event tables, as the event indexes of 0025 and 0040 did. A
+-- deployment with a large table builds it CONCURRENTLY by hand before upgrading; IF NOT EXISTS
+-- then skips it here.
+CREATE INDEX IF NOT EXISTS conversation_events_file_state_idx
+  ON conversation_events (conversation_id, ((payload->'view'->'file'->>'path')), seq DESC)
+  WHERE type = 'tool_result';

package/dist/tools/builtins/sandbox/names.d.ts

@@ -1,7 +0,0 @@
-/**
- * 沙箱内置工具的名字（M5 T8，Ruling M12：工具 key 只能含字母数字、`_`、`-`，所以是 `sandbox_<动作>`）。
- * 单独成文件：注册表与策略判定只需要名字，不引入工具实现。
- */
-export declare const SANDBOX_TOOL_NAMES: readonly ["sandbox_bash", "sandbox_read", "sandbox_write", "sandbox_edit", "sandbox_glob", "sandbox_grep", "sandbox_deliver"];
-/** 组织设置 `sandboxToolPolicy` 为 `ask` 时需要审批的沙箱工具（只读的 read / glob / grep 除外）。 */
-export declare const SANDBOX_ASK_TOOL_NAMES: ReadonlySet<string>;

package/dist/tools/builtins/sandbox/names.js

@@ -1,20 +0,0 @@
-/**
- * 沙箱内置工具的名字（M5 T8，Ruling M12：工具 key 只能含字母数字、`_`、`-`，所以是 `sandbox_<动作>`）。
- * 单独成文件：注册表与策略判定只需要名字，不引入工具实现。
- */
-export const SANDBOX_TOOL_NAMES = [
-    "sandbox_bash",
-    "sandbox_read",
-    "sandbox_write",
-    "sandbox_edit",
-    "sandbox_glob",
-    "sandbox_grep",
-    "sandbox_deliver",
-];
-/** 组织设置 `sandboxToolPolicy` 为 `ask` 时需要审批的沙箱工具（只读的 read / glob / grep 除外）。 */
-export const SANDBOX_ASK_TOOL_NAMES = new Set([
-    "sandbox_bash",
-    "sandbox_write",
-    "sandbox_edit",
-    "sandbox_deliver",
-]);