@trim21/personal-pi-extensions 0.1.651 → 0.1.653

package/src/lib/tools-config.ts

@@ -0,0 +1,277 @@
+/**
+ * 本仓库工具注册的配置：`~/.pi/agent/settings.json` 的 `personalExtensions` section。
+ *
+ * ```jsonc
+ * {
+ *   "personalExtensions": {
+ *     "fileIo": "claude-code",
+ *     "fileIoByModel": [{ "models": ["glm-*"], "fileIo": "opencode" }],
+ *     "disabledTools": ["talk-*", { "tools": ["web_*"], "models": ["gpt-*"] }],
+ *     "enabledTools": [{ "tools": ["web_search"], "models": ["glm-*"] }]
+ *   }
+ * }
+ * ```
+ *
+ * 工具名与模型名都用 minimatch 通配模式匹配；模型名同时试 `model.id` 与
+ * `provider/model` 两种写法。带 `models` 的条目只在当前模型命中时才参与判定。
+ * 非法字段/条目被忽略并产出警告，不影响其余配置生效。
+ */
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import { minimatch } from "minimatch";
+import { Type } from "typebox";
+import { Value } from "typebox/value";
+
+// ── schema ───────────────────────────────────────────────────────────────────
+
+const fileIoSchema = Type.Union([Type.Literal("claude-code"), Type.Literal("opencode")]);
+
+const fileIoByModelEntrySchema = Type.Object({
+  models: Type.Array(Type.String()),
+  fileIo: fileIoSchema,
+});
+
+const toolRuleSchema = Type.Object({
+  tools: Type.Array(Type.String()),
+  models: Type.Optional(Type.Array(Type.String())),
+});
+
+// ── 类型 ─────────────────────────────────────────────────────────────────────
+
+export type FileIoToolset = "claude-code" | "opencode";
+
+export type ToolRuleField = "disabledTools" | "enabledTools";
+
+export interface FileIoByModelEntry {
+  models: readonly string[];
+  fileIo: FileIoToolset;
+}
+
+export interface ToolPatternRule {
+  tools: readonly string[];
+  /** 空表示对所有模型生效。 */
+  models: readonly string[];
+}
+
+export interface ToolsConfig {
+  /** 兜底的文件 IO 工具集。 */
+  fileIo: FileIoToolset;
+  /** 按模型覆盖文件 IO 工具集，按顺序取首条命中。 */
+  fileIoByModel: readonly FileIoByModelEntry[];
+  disabledTools: readonly ToolPatternRule[];
+  enabledTools: readonly ToolPatternRule[];
+  /** 解析阶段发现的问题，由调用方在能提示用户时上报。 */
+  warnings: readonly string[];
+}
+
+export interface ModelIdentity {
+  id: string;
+  provider?: string;
+}
+
+export interface UnmatchedPattern {
+  field: ToolRuleField;
+  pattern: string;
+}
+
+export interface ToolAvailability {
+  /** 该工具名是否被禁用（命中 disabledTools 且未命中 enabledTools）。 */
+  isDisabled(name: string): boolean;
+  /** 哪些模式没匹配到任何工具（含被规则禁用的工具）。 */
+  unmatchedPatterns(declaredNames: readonly string[]): UnmatchedPattern[];
+}
+
+export const DEFAULT_FILE_IO: FileIoToolset = "claude-code";
+
+// ── 读取与解析 ───────────────────────────────────────────────────────────────
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function parseFileIo(value: unknown, field: string, warnings: string[]): FileIoToolset | undefined {
+  if (value === undefined) {
+    return undefined;
+  }
+  if (Value.Check(fileIoSchema, value)) {
+    return value;
+  }
+  warnings.push(
+    `${field}: invalid value ${JSON.stringify(value)} ignored (expected "claude-code" or "opencode")`,
+  );
+  return undefined;
+}
+
+function parseFileIoByModel(
+  value: unknown,
+  field: string,
+  warnings: string[],
+): FileIoByModelEntry[] {
+  if (value === undefined) {
+    return [];
+  }
+  if (!Array.isArray(value)) {
+    warnings.push(`${field}: expected an array, ignored`);
+    return [];
+  }
+
+  const entries: FileIoByModelEntry[] = [];
+  for (const [index, entry] of value.entries()) {
+    if (Value.Check(fileIoByModelEntrySchema, entry)) {
+      entries.push({ models: [...entry.models], fileIo: entry.fileIo });
+      continue;
+    }
+    warnings.push(
+      `${field}[${index}]: invalid entry ignored (expected { models: string[], fileIo: "claude-code" | "opencode" })`,
+    );
+  }
+  return entries;
+}
+
+function parseToolRules(value: unknown, fieldPath: string, warnings: string[]): ToolPatternRule[] {
+  if (value === undefined) {
+    return [];
+  }
+  if (!Array.isArray(value)) {
+    warnings.push(`${fieldPath}: expected an array, ignored`);
+    return [];
+  }
+
+  const rules: ToolPatternRule[] = [];
+  for (const [index, entry] of value.entries()) {
+    if (typeof entry === "string") {
+      rules.push({ tools: [entry], models: [] });
+      continue;
+    }
+    if (Value.Check(toolRuleSchema, entry)) {
+      rules.push({ tools: [...entry.tools], models: entry.models ? [...entry.models] : [] });
+      continue;
+    }
+    warnings.push(
+      `${fieldPath}[${index}]: invalid entry ignored (expected a tool name pattern or { tools, models })`,
+    );
+  }
+  return rules;
+}
+
+/** 解析 `personalExtensions` section（纯函数，便于测试）。 */
+export function parseToolsConfig(section: unknown, source = "personalExtensions"): ToolsConfig {
+  const warnings: string[] = [];
+
+  if (section === undefined) {
+    return {
+      fileIo: DEFAULT_FILE_IO,
+      fileIoByModel: [],
+      disabledTools: [],
+      enabledTools: [],
+      warnings,
+    };
+  }
+  if (!isRecord(section)) {
+    warnings.push(`${source}: expected an object, ignored`);
+    return {
+      fileIo: DEFAULT_FILE_IO,
+      fileIoByModel: [],
+      disabledTools: [],
+      enabledTools: [],
+      warnings,
+    };
+  }
+
+  return {
+    fileIo: parseFileIo(section.fileIo, `${source}.fileIo`, warnings) ?? DEFAULT_FILE_IO,
+    fileIoByModel: parseFileIoByModel(section.fileIoByModel, `${source}.fileIoByModel`, warnings),
+    disabledTools: parseToolRules(section.disabledTools, `${source}.disabledTools`, warnings),
+    enabledTools: parseToolRules(section.enabledTools, `${source}.enabledTools`, warnings),
+    warnings,
+  };
+}
+
+/** 读取全局 settings.json；文件缺失 / 损坏 / 无该 section 时用默认值。 */
+export function readToolsConfig(settingsPath = join(getAgentDir(), "settings.json")): ToolsConfig {
+  let section: unknown;
+  try {
+    const parsed: unknown = JSON.parse(readFileSync(settingsPath, "utf8"));
+    section = isRecord(parsed) ? parsed.personalExtensions : undefined;
+  } catch {
+    return parseToolsConfig(undefined);
+  }
+  return parseToolsConfig(section);
+}
+
+// ── 判定 ─────────────────────────────────────────────────────────────────────
+
+function matchesPattern(pattern: string, value: string): boolean {
+  return minimatch(value, pattern);
+}
+
+function modelCandidates(model: ModelIdentity | undefined): string[] {
+  if (!model) {
+    return [];
+  }
+  return model.provider ? [model.id, `${model.provider}/${model.id}`] : [model.id];
+}
+
+function matchesModel(patterns: readonly string[], model: ModelIdentity | undefined): boolean {
+  if (patterns.length === 0) {
+    return true;
+  }
+  const candidates = modelCandidates(model);
+  return patterns.some((pattern) =>
+    candidates.some((candidate) => matchesPattern(pattern, candidate)),
+  );
+}
+
+function ruleMatches(
+  rule: ToolPatternRule,
+  name: string,
+  model: ModelIdentity | undefined,
+): boolean {
+  return (
+    rule.tools.some((pattern) => matchesPattern(pattern, name)) && matchesModel(rule.models, model)
+  );
+}
+
+export function resolveFileIoToolset(
+  config: ToolsConfig,
+  model: ModelIdentity | undefined,
+): FileIoToolset {
+  for (const entry of config.fileIoByModel) {
+    if (matchesModel(entry.models, model)) {
+      return entry.fileIo;
+    }
+  }
+  return config.fileIo;
+}
+
+export function resolveToolAvailability(
+  config: ToolsConfig,
+  model: ModelIdentity | undefined,
+): ToolAvailability {
+  return {
+    isDisabled(name) {
+      const disabled = config.disabledTools.some((rule) => ruleMatches(rule, name, model));
+      if (!disabled) {
+        return false;
+      }
+      return config.enabledTools.every((rule) => !ruleMatches(rule, name, model));
+    },
+
+    unmatchedPatterns(declaredNames) {
+      const unmatched: UnmatchedPattern[] = [];
+      for (const field of ["disabledTools", "enabledTools"] as const) {
+        for (const rule of config[field]) {
+          for (const pattern of rule.tools) {
+            if (declaredNames.every((name) => !matchesPattern(pattern, name))) {
+              unmatched.push({ field, pattern });
+            }
+          }
+        }
+      }
+      return unmatched;
+    },
+  };
+}

package/src/opencode/bash.ts

@@ -13,6 +13,8 @@ import {
 } from "../bwrap/runtime.js";
 import { resolveWorkdir } from "../lib/path.js";
 import { createRequestPolicy } from "../lib/request-policy.js";
+import type { ToolBus } from "../lib/tool-bus.js";
+import { registerToolsOnSessionStart } from "../lib/tool-registration.js";
 
 const DEFAULT_TIMEOUT_MS = 120_000;
 const MAX_TIMEOUT_MS = 7_200_000;
@@ -48,10 +50,13 @@ export default function opencodeBash(
   pi: ExtensionAPI,
   runtime: BwrapRuntime = createBwrapRuntime(createRequestPolicy(pi.events)),
 ): void {
+  registerToolsOnSessionStart(pi, (bus) => registerBashTool(bus, pi, runtime));
+}
+
+export function registerBashTool(bus: ToolBus, pi: ExtensionAPI, runtime: BwrapRuntime): void {
   // 每个扩展实例持有自己的 runtime：不依赖模块级全局状态，状态随扩展
   // 实例生命周期（进程启动 / /reload / session 切换时工厂重建即重置）。
-  runtime.setup(pi);
-  pi.registerTool({
+  bus.register({
     name: "bash",
     label: "bash",
     description: [

package/src/opencode/files.ts

@@ -30,6 +30,7 @@ import { createInterface } from "node:readline";
 import type { ImageContent, TextContent } from "@earendil-works/pi-ai";
 import {
   type ExtensionAPI,
+  type ExtensionContext,
   generateDiffString,
   generateUnifiedPatch,
   withFileMutationQueue,
@@ -50,10 +51,17 @@ import {
 } from "../lib/file-reads.js";
 import { appendLspDiagnosticText } 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 { 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 { applyEdit, normalizeToLF, stripBom } from "./edit-engine.js";
 
@@ -402,8 +410,8 @@ async function formatDirectoryEntries(dirPath: string): Promise<string[]> {
 /** 会更新 reads 记账（src/lib/file-reads.ts）并随 details 持久化快照的工具名。 */
 const READS_TOOL_NAMES = new Set(["read", "edit", "write", "lsp-rename"]);
 
-function registerReadTool(pi: ExtensionAPI, getService: () => LspService, state: ReadsState): void {
-  pi.registerTool({
+function registerReadTool(bus: ToolBus, getService: () => LspService, state: ReadsState): void {
+  bus.register({
     name: "read",
     label: "read",
     description: `Read the contents of a file. Supports text files and images (jpg, png, gif, webp). Images are sent as attachments. For text files, output is truncated to ${DEFAULT_MAX_LINES} lines or ${DEFAULT_MAX_BYTES / 1024}KB (whichever is hit first). Use offset/limit for large files. A negative offset counts from the end of the file (offset=-2 reads the last 2 lines). When you need the full file, continue with offset until complete.`,
@@ -598,12 +606,12 @@ const editSchema = Type.Object({
 });
 
 function registerEditTool(
-  pi: ExtensionAPI,
+  bus: ToolBus,
   getService: () => LspService,
   policy: RequestPolicy,
   state: ReadsState,
 ): void {
-  pi.registerTool({
+  bus.register({
     name: "edit",
     label: "edit",
     description:
@@ -775,12 +783,12 @@ export function resolveBom(
 }
 
 function registerWriteTool(
-  pi: ExtensionAPI,
+  bus: ToolBus,
   getService: () => LspService,
   policy: RequestPolicy,
   state: ReadsState,
 ): void {
-  pi.registerTool({
+  bus.register({
     name: "write",
     label: "write",
     description:
@@ -864,64 +872,103 @@ function registerWriteTool(
 // ── 入口 ─────────────────────────────────────────────────────────────────────
 
 function registerFileTools(
-  pi: ExtensionAPI,
+  bus: ToolBus,
   getService: () => LspService,
   policy: RequestPolicy,
   state: ReadsState,
 ): void {
-  registerReadTool(pi, getService, state);
-  registerEditTool(pi, getService, policy, state);
-  registerWriteTool(pi, getService, policy, state);
+  registerReadTool(bus, getService, state);
+  registerEditTool(bus, getService, policy, state);
+  registerWriteTool(bus, getService, policy, state);
   // lsp-rename / inspect 工具由 manager 的 onEnabled 回调注册，不在这里注册。
 }
 
 export interface OpencodeFileToolOptions extends LspServiceOptions {
   /** 与 bash runtime 共享的非沙盒请求策略；独立入口不传，自建一份。 */
   policy?: RequestPolicy;
+  /** 聚合入口注入的总线（与同入口其他模块共享）；独立入口不传，自建一份。 */
+  bus?: ToolBus;
+  /** 聚合入口注入的共享 LSP manager（与另一套文件工具集共享同一份）。 */
+  manager?: LspManager;
 }
 
-/** 独立入口：创建 LSP manager（session_start 时按配置启用）并注册文件工具。 */
-export default function opencodeFileTools(
+/** 一套文件工具集：reads state 归实例所有，LSP 与请求策略可以由入口注入共享。 */
+export interface OpencodeFileToolset {
+  register(bus: ToolBus): void;
+  onLspEnabled(bus: ToolBus, service: LspService): void;
+  restoreReads(ctx: ExtensionContext): void;
+}
+
+/**
+ * 创建文件工具集。入口在会话启动、知道本会话模型之后再调用 `register`。
+ */
+export function createOpencodeFileTools(
   pi: ExtensionAPI,
   options?: OpencodeFileToolOptions,
-): void {
-  // 聚合入口（index.ts）注入与 bash runtime 共享的那一份；独立入口自建并靠
-  // pi.events 跟随同一开关。
+): OpencodeFileToolset {
+  // 聚合入口注入与 bash runtime 共享的那一份；独立入口自建并靠 pi.events 跟随
+  // 同一开关。
   const policy = options?.policy ?? createRequestPolicy(pi.events);
   const state = createReadsState();
-  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 bus = options?.bus ?? createToolRegistration(pi).bus;
+
+  const toolset: OpencodeFileToolset = {
+    register(currentBus) {
+      registerFileTools(currentBus, () => manager.mustLazyGetService(), policy, state);
+    },
+
+    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 时的指纹对比照样要求重新 read。
+    restoreReads(ctx) {
+      restoreReads(state, ctx.sessionManager, READS_TOOL_NAMES);
     },
-    options,
-  );
+  };
+
+  const manager =
+    options?.manager ??
+    createLspManager(
+      pi,
+      { onEnabled: (_pi, service) => toolset.onLspEnabled(bus, service) },
+      options,
+    );
+
+  return toolset;
+}
+
+/** 独立入口：创建文件工具集并在每次会话启动时注册。 */
+export default function opencodeFileTools(
+  pi: ExtensionAPI,
+  options?: OpencodeFileToolOptions,
+): void {
+  const registration = createToolRegistration(pi);
+  const toolset = createOpencodeFileTools(pi, { ...options, bus: registration.bus });
 
-  // 扩展实例在进程启动 / /reload / /new / /resume / /fork 时重建，内存里的已读
-  // 记账随之丢失，这里从当前分支的历史工具结果恢复；digest 仍是当时的值，文件
-  // 若在此期间被外部修改，edit 时的指纹对比照样要求重新 read。
   pi.on("session_start", (_event, ctx) => {
-    restoreReads(state, ctx.sessionManager, READS_TOOL_NAMES);
+    toolset.restoreReads(ctx);
   });
   // rewind / 树内跳转走 branch()，只发 session_tree：重放当前分支，丢弃被抛弃
   // 分支的记账，避免 state 与当前分支脱节。
   pi.on("session_tree", (_event, ctx) => {
-    restoreReads(state, ctx.sessionManager, READS_TOOL_NAMES);
+    toolset.restoreReads(ctx);
+  });
+  registration.onSessionStart(() => {
+    toolset.register(registration.bus);
   });
-
-  // 文件工具无条件注册；service 惰性获取，disabled 时为 no-op。
-  registerFileTools(pi, () => manager.mustLazyGetService(), policy, state);
 }

package/src/opencode/glob.ts

@@ -18,6 +18,8 @@ import { fileURLToPath } from "node:url";
 import type { ExtensionAPI, ExtensionContext } 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 { didYouMean } from "./files.js";
 import { RIPGREP_RESULT_LIMIT, runRipgrep } from "./ripgrep.js";
 
@@ -82,7 +84,11 @@ async function glob(
 }
 
 export default function opencodeGlob(pi: ExtensionAPI): void {
-  pi.registerTool({
+  registerToolsOnSessionStart(pi, registerGlobTool);
+}
+
+export function registerGlobTool(bus: ToolBus): void {
+  bus.register({
     name: "glob",
     label: "glob",
     description: [

package/src/opencode/grep.ts

@@ -21,6 +21,8 @@ import { Type } from "typebox";
 
 import { isRecord } from "../lib/narrow.js";
 import { parseWithSchema } from "../lib/parse-with-schema.js";
+import type { ToolBus } from "../lib/tool-bus.js";
+import { registerToolsOnSessionStart } from "../lib/tool-registration.js";
 import { didYouMean } from "./files.js";
 import { RIPGREP_RESULT_LIMIT, runRipgrep } from "./ripgrep.js";
 
@@ -178,7 +180,11 @@ async function grep(
 }
 
 export default function opencodeGrep(pi: ExtensionAPI): void {
-  pi.registerTool({
+  registerToolsOnSessionStart(pi, registerGrepTool);
+}
+
+export function registerGrepTool(bus: ToolBus): void {
+  bus.register({
     name: "grep",
     label: "grep",
     description: [

package/src/opencode/index.ts

@@ -11,25 +11,70 @@
  * allowlist 只暴露声明的子集（与 claude-code 三件套映射同一文件一致）。
  */
 
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-
-import { createBwrapRuntime } from "../bwrap/runtime.js";
-import { createRequestPolicy } from "../lib/request-policy.js";
-import opencodeBash from "./bash.js";
-import opencodeFileTools from "./files.js";
-import opencodeGlob from "./glob.js";
-import opencodeGrep from "./grep.js";
-import opencodeQuestion from "./question.js";
-import opencodeTodo from "./todo.js";
-
-export default function opencode(pi: ExtensionAPI) {
-  // 非沙盒请求策略由本入口创建，注入文件工具与 bash runtime 共享同一份；
-  // 独立入口（web/fetch.ts 等）各自创建一份并经 pi.events 保持同步。
-  const policy = createRequestPolicy(pi.events);
-  opencodeFileTools(pi, { policy });
-  opencodeGrep(pi);
-  opencodeGlob(pi);
-  opencodeTodo(pi);
-  opencodeQuestion(pi);
-  opencodeBash(pi, createBwrapRuntime(policy));
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+import { type BwrapRuntime, createBwrapRuntime } from "../bwrap/runtime.js";
+import type { LspManager } from "../lib/lsp/lsp.js";
+import { createRequestPolicy, type RequestPolicy } from "../lib/request-policy.js";
+import type { ToolBus } from "../lib/tool-bus.js";
+import { registerToolsOnSessionStart } from "../lib/tool-registration.js";
+import { registerBashTool } from "./bash.js";
+import { createOpencodeFileTools } from "./files.js";
+import { registerGlobTool } from "./glob.js";
+import { registerGrepTool } from "./grep.js";
+import { registerQuestionTool } from "./question.js";
+import { registerTodoTool } from "./todo.js";
+
+export interface OpencodeToolsetOptions {
+  bus?: ToolBus;
+  policy?: RequestPolicy;
+  runtime?: BwrapRuntime;
+  manager?: LspManager;
+}
+
+/** opencode 风格工具集的共享部件：入口与独立默认导出都从这里取。 */
+export function createOpencodeTools(pi: ExtensionAPI, options?: OpencodeToolsetOptions) {
+  // 非沙盒请求策略由本工具集创建，注入文件工具与 bash runtime 共享同一份。
+  const policy = options?.policy ?? createRequestPolicy(pi.events);
+  const runtime = options?.runtime ?? createBwrapRuntime(policy);
+  // 独立入口（不经 src/index.ts 的共享服务）要自己接上 bwrap 的会话钩子与 /bwrap* 命令。
+  if (options?.runtime === undefined) {
+    runtime.setup(pi);
+  }
+  const fileTools = createOpencodeFileTools(pi, {
+    policy,
+    bus: options?.bus,
+    manager: options?.manager,
+  });
+
+  return {
+    fileTools,
+    /** 会话启动 / 分支切换时恢复已读记账。 */
+    restoreReads(ctx: ExtensionContext): void {
+      fileTools.restoreReads(ctx);
+    },
+    /** 把本工具集的工具注册到总线。 */
+    register(bus: ToolBus): void {
+      fileTools.register(bus);
+      registerGrepTool(bus);
+      registerGlobTool(bus);
+      registerTodoTool(bus);
+      registerQuestionTool(bus);
+      registerBashTool(bus, pi, runtime);
+    },
+  };
+}
+
+export default function opencode(pi: ExtensionAPI, options?: { bus?: ToolBus }): void {
+  const tools = createOpencodeTools(pi, { bus: options?.bus });
+
+  pi.on("session_start", (_event, ctx) => tools.restoreReads(ctx));
+  // rewind / 树内跳转只发 session_tree 不发 session_start，同样要重放当前分支。
+  pi.on("session_tree", (_event, ctx) => tools.restoreReads(ctx));
+
+  // 全部工具在同一次 session_start 里注册：禁用规则可以带 models，只有那时
+  // 才知道本会话的模型。
+  registerToolsOnSessionStart(pi, (bus) => {
+    tools.register(bus);
+  });
 }

package/src/opencode/question.ts

@@ -24,6 +24,8 @@
 import type { ExtensionAPI, ExtensionContext } 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 { selectMultiple, selectWithOptionalInput } from "../lib/ui.js";
 
 // ── constants ────────────────────────────────────────────────────────────────
@@ -145,8 +147,12 @@ async function askMultiple(
 
 // ── extension ────────────────────────────────────────────────────────────────
 
-export default function question(pi: ExtensionAPI) {
-  pi.registerTool<typeof questionParamsSchema, QuestionDetails>({
+export default function question(pi: ExtensionAPI): void {
+  registerToolsOnSessionStart(pi, registerQuestionTool);
+}
+
+export function registerQuestionTool(bus: ToolBus): void {
+  bus.register<typeof questionParamsSchema, QuestionDetails>({
     name: TOOL_NAME,
     label: "Question",
     description: QUESTION_DESCRIPTION,