@trim21/personal-pi-extensions 0.1.650 → 0.1.652

package/README.md

@@ -10,6 +10,7 @@
 | ----------------------------------------- | --------------------------------------------------------------------------------------------- |
 | [opencode 工具集](#opencode-工具集)       | 小写 `read`/`edit`/`write`/`grep`/`glob`/`bash`/`todowrite`/`question`                        |
 | [Claude Code 工具集](#claude-code-工具集) | 大写 `Read`/`Edit`/`Write`/`Grep`/`Glob`/`Bash`/`TodoWrite`/`AskUserQuestion`                 |
+| [工具启用配置](#工具启用配置)             | `personalExtensions`：按模型选文件 IO 工具集、通配禁用/启用工具                               |
 | [bwrap](#bwrap)                           | 基于 bubblewrap 的 OS 级沙箱（内置两套工具集）：文件系统隔离 + 多档网络策略                   |
 | [写保护（内置）](#写保护内置)             | 写工具内置：限制文件写入在 workspace 内，外部写入需审批                                       |
 | [LSP（内置）](#lsp内置)                   | 文件工具内置 LSP 诊断 + `lsp-rename`/`lsp-inspect`/`lsp-find-definition`/`lsp-find-reference` |
@@ -23,13 +24,66 @@
 | [web](#web)                               | `web_search`（Search1API 搜索）与 `web_fetch`（正文提取 / 原样落盘）                          |
 | [openai-cost](#openai-cost)               | OpenAI Chat Completions，费用取自响应 `usage.cost`                                            |
 
-> **两套工具风格，按预期只启用其中一套**：本包同时提供 opencode 风格
-> （小写 `read`/`edit`/`write`/`grep`/`glob`/`bash`/`todowrite`/`question`）与 Claude Code
-> 风格（大写 `Read`/`Edit`/`Write`/`Grep`/`Glob`/`Bash`/`TodoWrite`/
-> `AskUserQuestion`）两套工具集，二者共享 bwrap 沙箱、写保护与 LSP 实现。两套同时
-> 启用会带来预期外的冗余：同名命令重复注册（如 `/bwrap` 出现 `/bwrap:1`
-> 后缀）、系统提示重复注入。请只启用其中一套：在 `~/.pi/agent/settings.json`
-> 的 `defaultTools` 中只列出一套，或启动时用 `--exclude-tools` 排除另一套。
+---
+
+## 工具启用配置
+
+所有工具由单一扩展入口 `src/index.ts` 注册（`package.json` 的 `pi.extensions` 只列
+`src/index.ts`、`src/session-name.ts`、`src/system-prompt/index.ts`）。启用的工具由
+`~/.pi/agent/settings.json` 的 `personalExtensions` section 决定：
+
+```jsonc
+{
+  "personalExtensions": {
+    // 兜底的文件 IO 工具集：opencode（小写 read/edit/write/grep/glob/bash）
+    // 或 claude-code（大写 Read/Edit/Write/Grep/Glob/Bash）
+    "fileIo": "claude-code",
+    // 按模型覆盖 fileIo，按顺序取第一条命中（工具名与模型名都是 minimatch 通配，
+    // 模型名同时试 model.id 与 provider/model）
+    "fileIoByModel": [{ "models": ["glm-*", "zhipu/*"], "fileIo": "opencode" }],
+    // 工具可用性规则：条目是工具名模式，或 { tools, models }
+    "disabledTools": ["talk-*", { "tools": ["web_*"], "models": ["gpt-*"] }],
+    "enabledTools": [{ "tools": ["web_search"], "models": ["glm-*"] }],
+  },
+}
+```
+
+规则：**命中 `disabledTools` 且未命中 `enabledTools` 的工具不注册**。带 `models` 的
+条目只在当前模型命中时参与判定。未配置该 section 时用 `fileIo: "claude-code"` 且不
+禁用任何工具。
+
+**判定时机是每个会话启动**：pi 在启动 / `/new` / `resume` / `/fork` / `/reload` 时重建
+扩展，注册就发生在 `session_start` 里（模型在扩展加载期读不到），因此新会话按自己的
+模型重新判定；**同一会话内 `/model` 切换不会改变工具集合**，换模型请开新会话。
+两个不同模型的会话可以同时用不同的工具集。
+
+配置里的非法取值、以及匹配不到任何工具的模式都会在会话启动时以 warning 通知报出。
+
+### 入口级排除项的迁移
+
+旧的 `packages[].extensions` 排除写法针对的是扩展入口文件，入口收敛后那些文件不再是
+扩展入口，改用 `personalExtensions` 表达：
+
+| 旧写法（`packages[].extensions`） | 新写法（`personalExtensions`）                                              |
+| --------------------------------- | --------------------------------------------------------------------------- |
+| `!src/opencode/index.ts`          | `"fileIo": "claude-code"`                                                   |
+| `!src/claude-code/index.ts`       | `"fileIo": "opencode"`                                                      |
+| `!src/web/search.ts`              | `"disabledTools": ["web_search"]`                                           |
+| `!src/web/fetch.ts`               | `"disabledTools": ["web_fetch"]`                                            |
+| `!src/talk/index.ts`              | `"disabledTools": ["talk-*"]`                                               |
+| `!src/aft/index.ts`               | `"disabledTools": ["aft_*"]`                                                |
+| `!src/gh-readonly.ts`             | `"disabledTools": ["read-github-*", "list-github-*", "wait-github-*", ...]` |
+| `!src/spawn-agent.ts`             | `"disabledTools": ["spawn-agent"]`                                          |
+| `!src/vision-agent.ts`            | `"disabledTools": ["describe_image"]`                                       |
+
+小技巧：可以用 `enabledTools` 做「全局禁用、某个模型才开」：
+
+```jsonc
+{
+  "disabledTools": ["web_*"],
+  "enabledTools": [{ "tools": ["web_search"], "models": ["glm-*"] }],
+}
+```
 
 ---
 
@@ -249,7 +303,11 @@ bwrap 已集成进 bash 工具实现（opencode 风格 `bash` 位于 `src/openco
 
 ## opencode 工具集
 
-opencode 风格工具集，随 `src/opencode/index.ts` 一次加载：`read` / `edit` / `write` / `grep` / `glob` / `bash` / `todowrite` / `question`，以及共享 LSP 工具。`grep` 替换 pi 内置 `grep`，`glob` 与 pi 内置 `find` 并存。各单工具文件（`src/opencode/grep.ts` 等）也可独立加载。
+opencode 风格工具集：`read` / `edit` / `write` / `grep` / `glob` / `bash` / `todowrite` / `question`，以及共享 LSP 工具。`grep` 替换 pi 内置 `grep`，`glob` 与 pi 内置 `find` 并存。
+
+启用方式：`personalExtensions.fileIo` 设为 `"opencode"`（或按模型在 `fileIoByModel` 里指定，见[工具启用配置](#工具启用配置)）。它与 Claude Code 工具集**只能启用一套**——两套都注册会让同名命令（如 `/bwrap`）重复注册、系统提示重复注入。各单工具文件（`src/opencode/grep.ts` 等）仍可单独 `-e` 加载。
+
+> **与 pi 内置工具重名的注意点**：pi 的工具表里有同名的内置项（`read` / `edit` / `write` / `bash` / `grep`…），而默认启用的内置工具只有 `read` / `bash` / `edit` / `write`。同名时该名字的启用状态由内置项决定，所以 `defaultTools: []`（关闭内置工具）会把这一套里的 `read`/`edit`/`write`/`bash`/`grep` 一起挡住，`grep` 在默认选择下也不可见。这些工具本身注册正常（`--tools read,grep` 显式列出即可用），要绕开这个限制请用 Claude Code 风格命名（`Read`/`Grep`… 无重名）。
 
 ### edit
 
@@ -320,7 +378,7 @@ pi -e ./src/opencode/index.ts
 
 ## Claude Code 工具集
 
-Claude Code 风格工具集，随 `src/claude-code/index.ts` 一次加载：`Read` / `Edit` / `Write` / `Grep` / `Glob` / `Bash` / `TodoWrite` / `AskUserQuestion`，以及共享 LSP 工具（`lsp-rename` / `lsp-inspect` / `lsp-find-definition` / `lsp-find-reference`）。各单工具文件（`src/claude-code/grep.ts` 等）也可独立加载。精确行为（输出格式、分页语义、匹配规则）见 `.agents/skills/claude-code-tools/SKILL.md`。
+Claude Code 风格工具集：`Read` / `Edit` / `Write` / `Grep` / `Glob` / `Bash` / `TodoWrite` / `AskUserQuestion`，以及共享 LSP 工具（`lsp-rename` / `lsp-inspect` / `lsp-find-definition` / `lsp-find-reference`）。这是默认启用的文件 IO 工具集（`personalExtensions.fileIo` 缺省 `"claude-code"`，见[工具启用配置](#工具启用配置)）；它与 opencode 工具集只能启用一套。各单工具文件（`src/claude-code/grep.ts` 等）仍可单独 `-e` 加载。精确行为（输出格式、分页语义、匹配规则）见 `.agents/skills/claude-code-tools/SKILL.md`。
 
 - **`Read` / `Edit` / `Write`**：与 opencode 风格共享 read-before-write 记账与文案（`File has not been read yet...` / `File has been modified since read...`），差异是三者都要求先 `Read`（`Edit` 用空 `old_string` 创建新文件、`Write` 创建新文件例外）。`Read` 支持 offset / limit 分页与 PDF `pages`
 - **`Grep` / `Glob`**：ripgrep 实现，行为跟随 Claude Code（`Glob` 带 `--no-ignore` / `--hidden` / `--sort=modified`，与 opencode 风格 `glob` 的差异是各自跟随上游）

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trim21/personal-pi-extensions",
-  "version": "0.1.650",
+  "version": "0.1.652",
   "type": "module",
   "description": "Custom pi coding-agent extensions: bwrap sandbox, workspace guard, opencode edit, and more",
   "keywords": [
@@ -64,17 +64,9 @@
   },
   "pi": {
     "extensions": [
-      "src/aft/index.ts",
-      "src/opencode/index.ts",
-      "src/claude-code/index.ts",
-      "src/vision-agent.ts",
+      "src/index.ts",
       "src/session-name.ts",
-      "src/gh-readonly.ts",
-      "src/spawn-agent.ts",
-      "src/system-prompt/index.ts",
-      "src/talk/index.ts",
-      "src/web/search.ts",
-      "src/web/fetch.ts"
+      "src/system-prompt/index.ts"
     ],
     "skills": [
       "src/talk/skills",
@@ -95,7 +87,7 @@
     "node": ">=24.14"
   },
   "dependencies": {
-    "@cortexkit/aft-bridge": "0.57.2",
+    "@cortexkit/aft-bridge": "0.58.0",
     "@mozilla/readability": "^0.6.0",
     "@parcel/watcher": "^2.6.0",
     "@vscode/tree-sitter-wasm": "^0.3.1",
@@ -111,6 +103,6 @@
     "web-tree-sitter": "^0.27.0"
   },
   "optionalDependencies": {
-    "@cortexkit/aft-linux-x64": "0.57.2"
+    "@cortexkit/aft-linux-x64": "0.58.0"
   }
 }

package/src/aft/index.ts

@@ -20,8 +20,10 @@
  */
 
 import { resolveCortexKitConfigPaths } from "@cortexkit/aft-bridge";
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 
+import type { ToolBus } from "../lib/tool-bus.js";
+import { registerToolsOnSessionStart } from "../lib/tool-registration.js";
 import { createAftState, findBinary, resolveSessionId, shutdownAftPool } from "./bridge.js";
 import { loadAftConfig } from "./config.js";
 import {
@@ -31,13 +33,16 @@ import {
   registerZoomTool,
 } from "./tools.js";
 
-export default function aftReadTools(pi: ExtensionAPI): void {
+/**
+ * aft 工具集：入口用它。`registerForSession` 必须在会话启动时调用——二进制
+ * 探测、semantic_search 的提示、bridge 状态的创建都在里面；找不到二进制就不
+ * 注册任何工具（避免模型看到只会抛 "not initialized" 的死工具）。
+ */
+export function createAftTools(pi: ExtensionAPI): {
+  registerForSession(bus: ToolBus, ctx: ExtensionContext): Promise<void>;
+} {
   const cwd = process.cwd();
   const cfg = loadAftConfig(resolveCortexKitConfigPaths(cwd).userConfigPath);
-  if (!cfg.enabled) {
-    return;
-  }
-
   // bridge 状态跟 session 生命周期走，作用域就是本工厂闭包，不落到模块级。
   let state: Awaited<ReturnType<typeof createAftState>> | null = null;
 
@@ -52,9 +57,11 @@ export default function aftReadTools(pi: ExtensionAPI): void {
 
   const toolCtx = { cwd, getState };
 
-  // 工具注册延迟到 session_start：先确认二进制可用再决定注册面。pi 允许在
-  // session_start 里 registerTool（工具表按 name 覆盖，跨 session 重复注册幂等）。
-  pi.on("session_start", async (_event, ctx) => {
+  async function registerForSession(bus: ToolBus, ctx: ExtensionContext): Promise<void> {
+    if (!cfg.enabled) {
+      return;
+    }
+
     const binaryPath = await findBinary();
     if (!binaryPath) {
       ctx.ui.notify(
@@ -66,23 +73,26 @@ export default function aftReadTools(pi: ExtensionAPI): void {
       return;
     }
 
-    registerOutlineTool(pi, toolCtx);
-    registerZoomTool(pi, toolCtx);
-    registerCallgraphTool(pi, toolCtx);
-    if (cfg.semanticSearch) {
-      if (cfg.semanticRemote) {
-        registerSearchTool(pi, toolCtx);
-      } else {
-        // 只开了开关、没配外部 embedding 后端：与其静默不注册，不如说明缺什么。
-        ctx.ui.notify(
-          "aft_search is not registered: semantic_search needs an external embedding backend (aft.jsonc semantic.backend = openai_compatible | ollama, plus base_url). The local ONNX fastembed default is not used here.",
-          "warning",
-        );
-      }
+    // 只开了 semantic_search 开关、没配外部 embedding 后端：与其静默不注册，
+    // 不如说明缺什么。
+    if (cfg.semanticSearch && !cfg.semanticRemote) {
+      ctx.ui.notify(
+        "aft_search is not registered: semantic_search needs an external embedding backend (aft.jsonc semantic.backend = openai_compatible | ollama, plus base_url). The local ONNX fastembed default is not used here.",
+        "warning",
+      );
+    }
+
+    // 先注册工具再建 bridge 状态：状态构建失败（如 bridge 起不来）时工具仍然
+    // 可见，错误按原样浮出给用户，而不是变成「工具消失」。
+    registerOutlineTool(bus, toolCtx);
+    registerZoomTool(bus, toolCtx);
+    registerCallgraphTool(bus, toolCtx);
+    if (cfg.semanticSearch && cfg.semanticRemote) {
+      registerSearchTool(bus, toolCtx);
     }
 
     state = await createAftState(cwd, resolveSessionId(ctx), binaryPath, cfg.semanticRemote);
-  });
+  }
 
   // 释放当前 session 的 bridge 状态。session_shutdown 是 pi 的正常生命周期；
   // beforeExit 兜底进程自然退出（不能注册 SIGINT/SIGTERM——那会吞掉 pi 主进程
@@ -105,4 +115,11 @@ export default function aftReadTools(pi: ExtensionAPI): void {
   pi.on("session_shutdown", async () => {
     await shutdown();
   });
+
+  return { registerForSession };
+}
+
+export default function aftReadTools(pi: ExtensionAPI): void {
+  const tools = createAftTools(pi);
+  registerToolsOnSessionStart(pi, (bus, ctx) => tools.registerForSession(bus, ctx));
 }

package/src/aft/tools.ts

@@ -19,12 +19,13 @@ import {
   PLAIN_CALLGRAPH_THEME,
   type StatusSnapshot,
 } from "@cortexkit/aft-bridge";
-import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { type Static, Type } from "typebox";
 import { Value } from "typebox/value";
 
 import { formatDisplayPath, formatSubtitlePath, resolvePathArg } from "../lib/path.js";
 import { type ToolPendant } from "../lib/pendant.js";
+import type { ToolBus } from "../lib/tool-bus.js";
 import {
   type AftState,
   callAftTool,
@@ -125,8 +126,8 @@ const OutlineParams = Type.Object(
   { additionalProperties: false },
 );
 
-export function registerOutlineTool(pi: ExtensionAPI, ctx: AftToolContext): void {
-  pi.registerTool({
+export function registerOutlineTool(bus: ToolBus, ctx: AftToolContext): void {
+  bus.register({
     name: "aft_outline",
     label: "aft_outline",
     description: [
@@ -209,8 +210,8 @@ const ZoomParams = Type.Object(
   { additionalProperties: false },
 );
 
-export function registerZoomTool(pi: ExtensionAPI, ctx: AftToolContext): void {
-  pi.registerTool({
+export function registerZoomTool(bus: ToolBus, ctx: AftToolContext): void {
+  bus.register({
     name: "aft_zoom",
     label: "aft_zoom",
     description: [
@@ -361,8 +362,8 @@ export async function callCallgraphWithBuildRetry(
   }
 }
 
-export function registerCallgraphTool(pi: ExtensionAPI, ctx: AftToolContext): void {
-  pi.registerTool({
+export function registerCallgraphTool(bus: ToolBus, ctx: AftToolContext): void {
+  bus.register({
     name: "aft_callgraph",
     label: "aft_callgraph",
     description: [
@@ -610,8 +611,8 @@ const SearchParams = Type.Object(
   { additionalProperties: false },
 );
 
-export function registerSearchTool(pi: ExtensionAPI, ctx: AftToolContext): void {
-  pi.registerTool({
+export function registerSearchTool(bus: ToolBus, ctx: AftToolContext): void {
+  bus.register({
     name: "aft_search",
     label: "aft_search",
     description: [

package/src/claude-code/files.ts

@@ -25,11 +25,18 @@ import {
 } from "../lib/file-reads.js";
 import { appendLspDiagnosticText, type DiagnosticReport } from "../lib/lsp/diagnostic.js";
 import { registerLspInspectTools } from "../lib/lsp/inspect-tool.js";
-import { createLspManager, type LspService, type LspServiceOptions } from "../lib/lsp/lsp.js";
+import {
+  createLspManager,
+  type LspManager,
+  type LspService,
+  type LspServiceOptions,
+} from "../lib/lsp/lsp.js";
 import { registerLspRenameTool } from "../lib/lsp/rename-tool.js";
 import { formatSubtitlePath } from "../lib/path.js";
 import type { ToolPendant } from "../lib/pendant.ts";
 import { createRequestPolicy, type RequestPolicy } from "../lib/request-policy.js";
+import type { ToolBus } from "../lib/tool-bus.js";
+import { createToolRegistration } from "../lib/tool-registration.js";
 import { guardWriteAccess } from "../lib/write-guard.js";
 import { didYouMean, resolveToolFilePath } from "./common.js";
 import { applyExactEdit } from "./edit-match.js";
@@ -173,12 +180,12 @@ export function formatReadOutput(
 }
 
 export function registerFileTools(
-  pi: ExtensionAPI,
+  bus: ToolBus,
   state: ReadsState,
   getService: () => LspService,
   policy: RequestPolicy,
 ): void {
-  pi.registerTool({
+  bus.register({
     name: "Read",
     label: "Read",
     description: [
@@ -312,7 +319,7 @@ export function registerFileTools(
     },
   });
 
-  pi.registerTool({
+  bus.register({
     name: "Edit",
     label: "Edit",
     description: [
@@ -493,7 +500,7 @@ export function registerFileTools(
     },
   });
 
-  pi.registerTool({
+  bus.register({
     name: "Write",
     label: "Write",
     description: [
@@ -591,72 +598,110 @@ export function registerFileTools(
 /** 会更新 reads state 并随 details 持久化快照的工具名。 */
 const FILE_TOOL_NAMES = new Set(["Read", "Edit", "Write", "lsp-rename"]);
 
-function restoreFileReads(
-  state: ReadsState,
-  sessionManager: ExtensionContext["sessionManager"],
-): void {
-  restoreReads(state, sessionManager, FILE_TOOL_NAMES);
-}
-
 export interface ClaudeCodeFileToolOptions extends LspServiceOptions {
   /** 与 bash runtime 共享的非沙盒请求策略；独立入口不传，自建一份。 */
   policy?: RequestPolicy;
+  /** 聚合入口注入的总线（与同入口其他模块共享）；独立入口不传，自建一份。 */
+  bus?: ToolBus;
+  /**
+   * 聚合入口注入的共享 LSP manager（两套文件工具集在同一个入口里共享一份，
+   * 否则 /lsp-* 命令与 LSP 服务会重复注册）；独立入口不传，自建一份。
+   */
+  manager?: LspManager;
 }
 
 /**
- * 独立扩展入口：files.ts 可单独经 `-e claude-code/files.ts` 加载（spawn-agent
- * 子代理把 Read/Edit/Write 工具名映射到本文件），无需经 index.ts。reads
- * state 归本文件所有：扩展实例内创建，并随 session 事件从历史分支恢复，
- * 与主进程 index.ts 聚合加载时的行为一致。
+ * 一套文件工具集：reads state 归实例所有，LSP 与请求策略可以由入口注入共享。
+ * 工具用 `register`、LSP 专属工具用 `onLspEnabled`（在 LSP 服务就绪时由
+ * manager 触发），已读记账恢复用 `restoreReads`。
  */
-export default function claudeCodeFileTools(
+export interface FileToolset {
+  register(bus: ToolBus): void;
+  onLspEnabled(bus: ToolBus, service: LspService): void;
+  restoreReads(ctx: ExtensionContext): void;
+}
+
+/**
+ * 创建文件工具集。入口在会话启动、知道本会话模型之后再调用 `register`；
+ * `restoreReads` 与 `onLspEnabled` 分别由会话事件与 LSP manager 触发。
+ *
+ * 独立扩展入口见文件末尾的默认导出：spawn-agent 子代理按工具名把
+ * Read/Edit/Write 映射到本文件并经 `-e` 加载，形态与聚合入口一致。
+ */
+export function createClaudeCodeFileTools(
   pi: ExtensionAPI,
   options?: ClaudeCodeFileToolOptions,
-): void {
+): FileToolset {
   const state = createReadsState();
-  // 聚合入口（index.ts）注入与 bash runtime 共享的那一份；独立入口（spawn-agent
-  // 按工具名 `-e` 加载本文件）自建一份，靠 pi.events 跟随同一开关。
+  // 聚合入口注入与 bash runtime 共享的那一份；独立入口自建并订阅 pi.events。
   const policy = options?.policy ?? createRequestPolicy(pi.events);
+  // 聚合入口注入自己的总线（与同入口其他模块共享）；独立入口自建一份。
+  const bus = options?.bus ?? createToolRegistration(pi).bus;
 
-  // LSP 专属工具（lsp-rename / inspect 族）仅在 lsp.json 存在 enabled 服务器时
-  // 注册（session_start 校验后）；本工具集跟踪 read-before-write 状态，rename
-  // 落盘的文件要标记为已读并随 details 持久化（restoreFileReads 依赖 details.reads）。
-  const manager = createLspManager(
-    pi,
-    {
-      onEnabled: (pi, service) => {
-        registerLspRenameTool(pi, service, {
-          policy,
-          recordReads: (applied) =>
-            recordReads(
-              state,
-              applied.map((fileEdit) => ({
-                path: fileEdit.path,
-                snapshot: snapshotOf(fileEdit.newText),
-              })),
-            ),
-        });
-        registerLspInspectTools(pi, service);
-      },
+  const toolset: FileToolset = {
+    register(currentBus) {
+      registerFileTools(currentBus, state, () => manager.mustLazyGetService(), policy);
     },
-    options,
-  );
 
-  // 扩展实例在进程启动 / /reload / /new / /resume / /fork 时重建，内存里的
-  // 已读记账随之丢失。这里从当前分支的历史工具结果里恢复：digest 是当时的值，
-  // 若文件在此期间被外部修改，Edit/Write 时的指纹对比仍会要求重新 Read，
-  // 防呆语义不因重建而弱化。
+    // LSP 专属工具（lsp-rename / inspect 族）仅在 lsp.json 有 enabled 服务器时
+    // 注册；本工具集跟踪 read-before-write 状态，rename 落盘的文件要标记为已读
+    // 并随 details 持久化（restoreReads 依赖 details.reads）。
+    onLspEnabled(currentBus, service) {
+      registerLspRenameTool(currentBus, service, {
+        policy,
+        recordReads: (applied) =>
+          recordReads(
+            state,
+            applied.map((fileEdit) => ({
+              path: fileEdit.path,
+              snapshot: snapshotOf(fileEdit.newText),
+            })),
+          ),
+      });
+      registerLspInspectTools(currentBus, service);
+    },
+
+    // 扩展实例在进程启动 / /reload / /new / /resume / /fork 时重建，内存里的
+    // 已读记账随之丢失。这里从当前分支的历史工具结果里恢复：digest 是当时的值，
+    // 若文件在此期间被外部修改，Edit/Write 时的指纹对比仍会要求重新 Read，
+    // 防呆语义不因重建而弱化。
+    restoreReads(ctx) {
+      restoreReads(state, ctx.sessionManager, FILE_TOOL_NAMES);
+    },
+  };
+
+  // 独立入口没有注入 manager 时自建一份（入口共享的那份由入口创建）。
+  const manager =
+    options?.manager ??
+    createLspManager(
+      pi,
+      { onEnabled: (_pi, service) => toolset.onLspEnabled(bus, service) },
+      options,
+    );
+
+  return toolset;
+}
+
+/**
+ * 独立扩展入口：files.ts 可单独经 `-e claude-code/files.ts` 加载（spawn-agent
+ * 子代理把 Read/Edit/Write 工具名映射到本文件），无需经 index.ts。
+ */
+export default function claudeCodeFileTools(
+  pi: ExtensionAPI,
+  options?: ClaudeCodeFileToolOptions,
+): void {
+  const registration = createToolRegistration(pi);
+  const toolset = createClaudeCodeFileTools(pi, { ...options, bus: registration.bus });
+
   pi.on("session_start", (_event, ctx) => {
-    restoreFileReads(state, ctx.sessionManager);
+    toolset.restoreReads(ctx);
   });
-
   // rewind / 树内跳转走 navigateTree → branch()，只发 session_tree 不发
-  // session_start，扩展实例也不重建。这里同样重放当前分支，丢弃被抛弃分支
-  // 的记账，避免 state 与当前分支脱节。
+  // session_start，扩展实例也不重建。这里同样重放当前分支。
   pi.on("session_tree", (_event, ctx) => {
-    restoreFileReads(state, ctx.sessionManager);
+    toolset.restoreReads(ctx);
+  });
+  registration.onSessionStart(() => {
+    toolset.register(registration.bus);
   });
-
-  // 文件工具无条件注册；service 惰性获取，disabled 时为 no-op。
-  registerFileTools(pi, state, () => manager.mustLazyGetService(), policy);
 }

package/src/claude-code/glob.ts

@@ -15,6 +15,8 @@ import { promisify } from "node:util";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 
+import type { ToolBus } from "../lib/tool-bus.js";
+import { registerToolsOnSessionStart } from "../lib/tool-registration.js";
 import { searchRoot, suggestPathUnderCwd, toRelativePath } from "./common.js";
 
 const GLOB_RESULT_LIMIT = 100;
@@ -110,8 +112,8 @@ export async function globFiles(
   };
 }
 
-export function registerGlobTool(pi: ExtensionAPI): void {
-  pi.registerTool({
+export function registerGlobTool(bus: ToolBus): void {
+  bus.register({
     name: "Glob",
     label: "Glob",
     description: [
@@ -167,6 +169,7 @@ export function registerGlobTool(pi: ExtensionAPI): void {
 }
 
 // 独立扩展入口：spawn-agent 子代理声明 `Glob` 工具时按本文件 `-e` 加载，
-// 无需经 index.ts / search.ts 聚合。registerGlobTool 本身就是 (pi) => void，
-// 可直接作为扩展 factory。
-export default registerGlobTool;
+// 无需经 index.ts / search.ts 聚合。
+export default function claudeCodeGlobTool(pi: ExtensionAPI): void {
+  registerToolsOnSessionStart(pi, registerGlobTool);
+}

package/src/claude-code/grep.ts

@@ -17,6 +17,8 @@ import { StringEnum } from "@earendil-works/pi-ai";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { type Static, Type } from "typebox";
 
+import type { ToolBus } from "../lib/tool-bus.js";
+import { registerToolsOnSessionStart } from "../lib/tool-registration.js";
 import { searchRoot, suggestPathUnderCwd, toRelativePath } from "./common.js";
 
 const GREP_OUTPUT_MODES = ["content", "files_with_matches", "count"] as const;
@@ -258,8 +260,8 @@ function relativizeCountLine(line: string, cwd: string): string {
   return line;
 }
 
-export function registerGrepTool(pi: ExtensionAPI): void {
-  pi.registerTool({
+export function registerGrepTool(bus: ToolBus, pi: ExtensionAPI): void {
+  bus.register({
     name: "Grep",
     label: "Grep",
     description: [
@@ -374,6 +376,7 @@ export function registerGrepTool(pi: ExtensionAPI): void {
 }
 
 // 独立扩展入口：spawn-agent 子代理声明 `Grep` 工具时按本文件 `-e` 加载，
-// 无需经 index.ts / search.ts 聚合。registerGrepTool 本身就是 (pi) => void，
-// 可直接作为扩展 factory。
-export default registerGrepTool;
+// 无需经 index.ts / search.ts 聚合。
+export default function claudeCodeGrepTool(pi: ExtensionAPI): void {
+  registerToolsOnSessionStart(pi, (bus) => registerGrepTool(bus, pi));
+}