@trim21/personal-pi-extensions 0.1.683 → 0.1.685

package/src/aft/tools.ts

@@ -20,18 +20,24 @@ import {
   type StatusSnapshot,
 } from "@cortexkit/aft-bridge";
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { type Static, Type } from "typebox";
+import { type Static, type TSchema, 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 { defineStructuredTool, type StructuredResult, type ToolBus } from "../lib/tool-bus.js";
 import {
   type AftState,
   callAftTool,
   resolveSessionId,
   SEMANTIC_INDEX_WAIT_TIMEOUT_MS,
 } from "./bridge.js";
+import {
+  aftCallgraphStructuredSchema,
+  aftOutlineStructuredSchema,
+  aftSearchStructuredSchema,
+  aftZoomStructuredSchema,
+} from "./schemas.js";
 
 /** 工具使用指南，以 markdown 形式维护，读起来像文档。 */
 const OUTLINE_PROMPT = readFileSync(
@@ -79,6 +85,24 @@ export function compactArgs(args: Record<string, unknown>): Record<string, unkno
   );
 }
 
+/**
+ * 结构化载荷：引擎自己的响应字段（去掉 envelope 的 request id）原样给脚本，外加我们
+ * 渲染的文本。引擎的 `success` / `code` 保留在载荷里——软失败（symbol_not_found、
+ * callgraph_building、search_lanes_unavailable）是「工具跑成了、引擎给出否定答案」，
+ * 脚本据 `code` 分支，而不是被当成调用异常。
+ */
+function aftPayload<TOutput extends TSchema>(
+  response: Record<string, unknown>,
+  text: string,
+): StructuredResult<Static<TOutput>> {
+  const value: Record<string, unknown> = { ...response, text };
+  // envelope 的 request id 是传输层的事，不进载荷
+  delete value.id;
+  // 载荷是引擎响应的原样透传（schema 只声明我们确证过的字段，其余允许通过），所以
+  // 编译期只能断言；类型正确性由脚本侧的声明与总线运行期的 Value.Parse 复核共同保证。
+  return { ok: true, value: value as Static<TOutput> };
+}
+
 /** 人类视角的调用记录：input params + 与 LLM 相同的输出结果。 */
 function buildPendantMarkdown(params: {
   title: string;
@@ -127,60 +151,64 @@ const OutlineParams = Type.Object(
 );
 
 export function registerOutlineTool(bus: ToolBus, ctx: AftToolContext): void {
-  bus.register({
-    name: "aft_outline",
-    label: "aft_outline",
-    description: [
-      "输出代码文件、目录的结构化大纲：函数/类/类型等符号及其行号范围；Markdown/HTML 返回标题层级。",
-      "用它在读取具体内容之前先了解文件结构。",
-      "深入了解某个符号用 aft_zoom；看跨文件调用关系用 aft_callgraph。",
-      "target 支持：文件路径（带签名的符号大纲）、目录路径（递归最多 200 文件）。只接受单个 target。",
-      "target 为目录时默认返回扁平文件树（语言、顶层符号数、字节大小）；传 files: false 可改回符号大纲。",
-    ].join("\n"),
-    promptSnippet: "Output structural outline of a file/directory",
-    promptGuidelines: [OUTLINE_PROMPT, AFT_GUIDELINES],
-    parameters: OutlineParams,
-    async execute(_id, params, signal, _onUpdate, extCtx) {
-      const target = coerceTargetParam(params.target);
-      if (typeof target !== "string" || target.length === 0) {
-        throw new Error("'target' must be a single path (array targets are not supported)");
-      }
-      const resolved = resolvePathArg(extCtx.cwd, target);
-      let filesMode = coerceBoolean(params.files);
-      if (params.files === undefined) {
-        const stats = await stat(resolved).catch(() => null);
-        filesMode = stats?.isDirectory() ?? false;
-      }
-      const rawArgs = compactArgs({
-        target: resolved,
-        files: filesMode || undefined,
-        includeTests: params.includeTests,
-      });
-
-      const subtitle = buildOutlineSubtitle(extCtx.cwd, target);
-
-      const { text, response } = await callAftTool(
-        bridgeFor(ctx),
-        "outline",
-        rawArgs,
-        resolveSessionId(extCtx),
-        undefined,
-        undefined,
-        signal,
-      );
-      const truncated = response.truncated === true;
-      return {
-        content: [{ type: "text", text }],
-        details: {
-          truncated,
-          params,
-          pendant: {
-            subtitle,
-          } satisfies ToolPendant,
-        },
-      };
-    },
-  });
+  bus.register(
+    defineStructuredTool({
+      name: "aft_outline",
+      label: "aft_outline",
+      description: [
+        "输出代码文件、目录的结构化大纲：函数/类/类型等符号及其行号范围；Markdown/HTML 返回标题层级。",
+        "用它在读取具体内容之前先了解文件结构。",
+        "深入了解某个符号用 aft_zoom；看跨文件调用关系用 aft_callgraph。",
+        "target 支持：文件路径（带签名的符号大纲）、目录路径（递归最多 200 文件）。只接受单个 target。",
+        "target 为目录时默认返回扁平文件树（语言、顶层符号数、字节大小）；传 files: false 可改回符号大纲。",
+      ].join("\n"),
+      promptSnippet: "Output structural outline of a file/directory",
+      promptGuidelines: [OUTLINE_PROMPT, AFT_GUIDELINES],
+      parameters: OutlineParams,
+      structuredSchema: aftOutlineStructuredSchema,
+      async execute(_id, params, signal, _onUpdate, extCtx) {
+        const target = coerceTargetParam(params.target);
+        if (typeof target !== "string" || target.length === 0) {
+          throw new Error("'target' must be a single path (array targets are not supported)");
+        }
+        const resolved = resolvePathArg(extCtx.cwd, target);
+        let filesMode = coerceBoolean(params.files);
+        if (params.files === undefined) {
+          const stats = await stat(resolved).catch(() => null);
+          filesMode = stats?.isDirectory() ?? false;
+        }
+        const rawArgs = compactArgs({
+          target: resolved,
+          files: filesMode || undefined,
+          includeTests: params.includeTests,
+        });
+
+        const subtitle = buildOutlineSubtitle(extCtx.cwd, target);
+
+        const { text, response } = await callAftTool(
+          bridgeFor(ctx),
+          "outline",
+          rawArgs,
+          resolveSessionId(extCtx),
+          undefined,
+          undefined,
+          signal,
+        );
+        const truncated = response.truncated === true;
+        return {
+          content: [{ type: "text", text }],
+          details: {
+            truncated,
+            params,
+            pendant: {
+              subtitle,
+            } satisfies ToolPendant,
+          },
+          structuredResult: aftPayload<typeof aftOutlineStructuredSchema>(response, text),
+        };
+      },
+    }),
+  );
 }
 
 /** 构建 aft_outline pendant 的 subtitle：`target="…"`（路径过长时显示上一级目录加文件名）。 */
@@ -211,61 +239,65 @@ const ZoomParams = Type.Object(
 );
 
 export function registerZoomTool(bus: ToolBus, ctx: AftToolContext): void {
-  bus.register({
-    name: "aft_zoom",
-    label: "aft_zoom",
-    description: [
-      "查看命名符号（函数/类/类型）的完整源码，或 Markdown/HTML 的标题段落内容。",
-      "需要理解某个具体符号时用它（读整个文件用 read）。",
-      "callgraph: true 时附带同文件内的调用关系标注。",
-      "同文件多符号用 `symbols` 数组。",
-    ].join("\n"),
-    promptSnippet: "Inspect the full source of a named symbol",
-    promptGuidelines: [ZOOM_PROMPT],
-    parameters: ZoomParams,
-    async execute(_id, params, signal, _onUpdate, extCtx) {
-      const rawArgs = compactArgs({
-        filePath: resolvePathArg(extCtx.cwd, params.path),
-        symbols: params.symbols,
-        contextLines: coerceOptionalInt(
-          params.contextLines,
-          "contextLines",
-          1,
-          Number.MAX_SAFE_INTEGER,
-        ),
-        callgraph: coerceBoolean(params.callgraph) || undefined,
-      });
-
-      const subtitle = buildZoomSubtitle(extCtx.cwd, params);
-
-      const { text, response } = await callAftTool(
-        bridgeFor(ctx),
-        "zoom",
-        rawArgs,
-        resolveSessionId(extCtx),
-        undefined,
-        undefined,
-        signal,
-      );
-      const truncated = response.truncated === true;
-      return {
-        content: [{ type: "text", text }],
-        details: {
-          truncated,
-          params,
-          pendant: {
-            subtitle,
-            markdown: buildPendantMarkdown({
-              title: "aft_zoom",
-              input: params,
-              output: text,
-              truncated,
-            }),
-          } satisfies ToolPendant,
-        },
-      };
-    },
-  });
+  bus.register(
+    defineStructuredTool({
+      name: "aft_zoom",
+      label: "aft_zoom",
+      description: [
+        "查看命名符号（函数/类/类型）的完整源码，或 Markdown/HTML 的标题段落内容。",
+        "需要理解某个具体符号时用它（读整个文件用 read）。",
+        "callgraph: true 时附带同文件内的调用关系标注。",
+        "同文件多符号用 `symbols` 数组。",
+      ].join("\n"),
+      promptSnippet: "Inspect the full source of a named symbol",
+      promptGuidelines: [ZOOM_PROMPT],
+      parameters: ZoomParams,
+      structuredSchema: aftZoomStructuredSchema,
+      async execute(_id, params, signal, _onUpdate, extCtx) {
+        const rawArgs = compactArgs({
+          filePath: resolvePathArg(extCtx.cwd, params.path),
+          symbols: params.symbols,
+          contextLines: coerceOptionalInt(
+            params.contextLines,
+            "contextLines",
+            1,
+            Number.MAX_SAFE_INTEGER,
+          ),
+          callgraph: coerceBoolean(params.callgraph) || undefined,
+        });
+
+        const subtitle = buildZoomSubtitle(extCtx.cwd, params);
+
+        const { text, response } = await callAftTool(
+          bridgeFor(ctx),
+          "zoom",
+          rawArgs,
+          resolveSessionId(extCtx),
+          undefined,
+          undefined,
+          signal,
+        );
+        const truncated = response.truncated === true;
+        return {
+          content: [{ type: "text", text }],
+          details: {
+            truncated,
+            params,
+            pendant: {
+              subtitle,
+              markdown: buildPendantMarkdown({
+                title: "aft_zoom",
+                input: params,
+                output: text,
+                truncated,
+              }),
+            } satisfies ToolPendant,
+          },
+          structuredResult: aftPayload<typeof aftZoomStructuredSchema>(response, text),
+        };
+      },
+    }),
+  );
 }
 
 /** 构建 aft_zoom pendant 的 subtitle：`path="…" symbol="…"`。 */
@@ -363,60 +395,64 @@ export async function callCallgraphWithBuildRetry(
 }
 
 export function registerCallgraphTool(bus: ToolBus, ctx: AftToolContext): void {
-  bus.register({
-    name: "aft_callgraph",
-    label: "aft_callgraph",
-    description: [
-      "基于真实调用图回答代码关系问题（谁调用我、影响面、调用链），替代 grep + read 的链条式排查。",
-      "op 语义：callers=调用点（改名/改签名前用）；impact=影响面（改一个符号会波及谁）；",
-      "call_tree=该函数调用了什么；trace_to=从入口如何执行到某符号；",
-      "trace_to_symbol=两符号间最短路径（需 toSymbol，歧义时需 toPath）；trace_data=追踪值在参数/赋值间的流转（需 expression）。",
-      "标记：~ = 仅按名字解析的边（可能指向同名符号）；[unresolved] = 未解析到定义的调用点。",
-    ].join("\n"),
-    promptSnippet: "Call graph and data-flow navigation",
-    promptGuidelines: [CALLGRAPH_PROMPT],
-    parameters: CallgraphParams,
-    async execute(_id, params, signal, _onUpdate, extCtx) {
-      const rawArgs = compactArgs({
-        op: params.op,
-        filePath: resolvePathArg(extCtx.cwd, params.path),
-        symbol: params.symbol,
-        depth: coerceOptionalInt(params.depth, "depth", 1, Number.MAX_SAFE_INTEGER),
-        expression: params.expression,
-        toSymbol: params.toSymbol,
-        toFile: params.toPath ? resolvePathArg(extCtx.cwd, params.toPath) : undefined,
-        includeTests: params.includeTests,
-        includeUnresolved: params.includeUnresolved,
-      });
-
-      const { text, response } = await callCallgraphWithBuildRetry(
-        bridgeFor(ctx),
-        rawArgs,
-        extCtx,
-        signal,
-      );
-      const out =
-        text ||
-        formatCallgraphSections(params.op, response, PLAIN_CALLGRAPH_THEME, {
-          includeUnresolved: coerceBoolean(params.includeUnresolved),
-        }).join("\n");
-      const truncated = response.truncated === true;
-      return {
-        content: [{ type: "text", text: out }],
-        details: {
-          truncated,
-          pendant: {
-            markdown: buildPendantMarkdown({
-              title: "aft_callgraph",
-              input: params,
-              output: out,
-              truncated,
-            }),
-          } satisfies ToolPendant,
-        },
-      };
-    },
-  });
+  bus.register(
+    defineStructuredTool({
+      name: "aft_callgraph",
+      label: "aft_callgraph",
+      description: [
+        "基于真实调用图回答代码关系问题（谁调用我、影响面、调用链），替代 grep + read 的链条式排查。",
+        "op 语义：callers=调用点（改名/改签名前用）；impact=影响面（改一个符号会波及谁）；",
+        "call_tree=该函数调用了什么；trace_to=从入口如何执行到某符号；",
+        "trace_to_symbol=两符号间最短路径（需 toSymbol，歧义时需 toPath）；trace_data=追踪值在参数/赋值间的流转（需 expression）。",
+        "标记：~ = 仅按名字解析的边（可能指向同名符号）；[unresolved] = 未解析到定义的调用点。",
+      ].join("\n"),
+      promptSnippet: "Call graph and data-flow navigation",
+      promptGuidelines: [CALLGRAPH_PROMPT],
+      parameters: CallgraphParams,
+      structuredSchema: aftCallgraphStructuredSchema,
+      async execute(_id, params, signal, _onUpdate, extCtx) {
+        const rawArgs = compactArgs({
+          op: params.op,
+          filePath: resolvePathArg(extCtx.cwd, params.path),
+          symbol: params.symbol,
+          depth: coerceOptionalInt(params.depth, "depth", 1, Number.MAX_SAFE_INTEGER),
+          expression: params.expression,
+          toSymbol: params.toSymbol,
+          toFile: params.toPath ? resolvePathArg(extCtx.cwd, params.toPath) : undefined,
+          includeTests: params.includeTests,
+          includeUnresolved: params.includeUnresolved,
+        });
+
+        const { text, response } = await callCallgraphWithBuildRetry(
+          bridgeFor(ctx),
+          rawArgs,
+          extCtx,
+          signal,
+        );
+        const out =
+          text ||
+          formatCallgraphSections(params.op, response, PLAIN_CALLGRAPH_THEME, {
+            includeUnresolved: coerceBoolean(params.includeUnresolved),
+          }).join("\n");
+        const truncated = response.truncated === true;
+        return {
+          content: [{ type: "text", text: out }],
+          details: {
+            truncated,
+            pendant: {
+              markdown: buildPendantMarkdown({
+                title: "aft_callgraph",
+                input: params,
+                output: out,
+                truncated,
+              }),
+            } satisfies ToolPendant,
+          },
+          structuredResult: aftPayload<typeof aftCallgraphStructuredSchema>(response, out),
+        };
+      },
+    }),
+  );
 }
 
 /**
@@ -612,75 +648,79 @@ const SearchParams = Type.Object(
 );
 
 export function registerSearchTool(bus: ToolBus, ctx: AftToolContext): void {
-  bus.register({
-    name: "aft_search",
-    label: "aft_search",
-    description: [
-      "一个工具完成代码搜索：概念、标识符、错误串、正则、字面量、文件名自动路由到合适的引擎并按相关度排序。",
-      "概念类查询（'ORM 如何构建并执行查询'）用自然语言整句——语义通道理解意图并匹配 docstring 和注释；",
-      "精确名字、字符串、正则保持简短（'^export'、'Cargo.lock'）。",
-      "索引首次构建时本调用会阻塞到构建完成，避免返回部分结果。",
-    ].join("\n"),
-    promptSnippet: "Search code by meaning or exact text",
-    promptGuidelines: [SEARCH_PROMPT],
-    parameters: SearchParams,
-    async execute(_id, params, signal, onUpdate, extCtx) {
-      if (typeof params.query !== "string" || params.query.trim().length === 0) {
-        throw new Error("'query' must be a non-empty string");
-      }
-      const rawArgs = compactArgs({
-        query: params.query,
-        topK: params.topK,
-        includeTests: params.includeTests,
-      });
-
-      const bridge = bridgeFor(ctx);
-      const formatProgress = createSemanticIndexProgressFormatter();
-      const stopProgress =
-        onUpdate === undefined
-          ? undefined
-          : subscribeBridgeStatus(bridge, (snapshot) => {
-              const text = formatProgress(snapshot);
-              if (text !== undefined) {
-                onUpdate({ content: [{ type: "text", text }], details: undefined });
-              }
-            });
-      let response: Record<string, unknown>;
-      let text: string;
-      try {
-        ({ text, response } = await callAftTool(
-          bridge,
-          "search",
-          rawArgs,
-          resolveSessionId(extCtx),
-          {
-            // 默认 search 传输超时仅 60s，会早于索引等待（600s）触发；覆盖为等待
-            // 上限 + 常规执行预算。超时只说明响应被挤掉而非 bridge 挂死，保留
-            // 常驻的语义索引/LSP 状态。
-            transportTimeoutMs: SEMANTIC_INDEX_WAIT_TIMEOUT_MS + 60_000,
-            keepBridgeOnTimeout: true,
+  bus.register(
+    defineStructuredTool({
+      name: "aft_search",
+      label: "aft_search",
+      description: [
+        "一个工具完成代码搜索：概念、标识符、错误串、正则、字面量、文件名自动路由到合适的引擎并按相关度排序。",
+        "概念类查询（'ORM 如何构建并执行查询'）用自然语言整句——语义通道理解意图并匹配 docstring 和注释；",
+        "精确名字、字符串、正则保持简短（'^export'、'Cargo.lock'）。",
+        "索引首次构建时本调用会阻塞到构建完成，避免返回部分结果。",
+      ].join("\n"),
+      promptSnippet: "Search code by meaning or exact text",
+      promptGuidelines: [SEARCH_PROMPT],
+      parameters: SearchParams,
+      structuredSchema: aftSearchStructuredSchema,
+      async execute(_id, params, signal, onUpdate, extCtx) {
+        if (typeof params.query !== "string" || params.query.trim().length === 0) {
+          throw new Error("'query' must be a non-empty string");
+        }
+        const rawArgs = compactArgs({
+          query: params.query,
+          topK: params.topK,
+          includeTests: params.includeTests,
+        });
+
+        const bridge = bridgeFor(ctx);
+        const formatProgress = createSemanticIndexProgressFormatter();
+        const stopProgress =
+          onUpdate === undefined
+            ? undefined
+            : subscribeBridgeStatus(bridge, (snapshot) => {
+                const text = formatProgress(snapshot);
+                if (text !== undefined) {
+                  onUpdate({ content: [{ type: "text", text }], details: undefined });
+                }
+              });
+        let response: Record<string, unknown>;
+        let text: string;
+        try {
+          ({ text, response } = await callAftTool(
+            bridge,
+            "search",
+            rawArgs,
+            resolveSessionId(extCtx),
+            {
+              // 默认 search 传输超时仅 60s，会早于索引等待（600s）触发；覆盖为等待
+              // 上限 + 常规执行预算。超时只说明响应被挤掉而非 bridge 挂死，保留
+              // 常驻的语义索引/LSP 状态。
+              transportTimeoutMs: SEMANTIC_INDEX_WAIT_TIMEOUT_MS + 60_000,
+              keepBridgeOnTimeout: true,
+            },
+            undefined,
+            signal,
+          ));
+        } finally {
+          stopProgress?.();
+        }
+        const truncated = response.truncated === true;
+        return {
+          content: [{ type: "text", text }],
+          details: {
+            truncated,
+            pendant: {
+              markdown: buildPendantMarkdown({
+                title: "aft_search",
+                input: params,
+                output: text,
+                truncated,
+              }),
+            } satisfies ToolPendant,
           },
-          undefined,
-          signal,
-        ));
-      } finally {
-        stopProgress?.();
-      }
-      const truncated = response.truncated === true;
-      return {
-        content: [{ type: "text", text }],
-        details: {
-          truncated,
-          pendant: {
-            markdown: buildPendantMarkdown({
-              title: "aft_search",
-              input: params,
-              output: text,
-              truncated,
-            }),
-          } satisfies ToolPendant,
-        },
-      };
-    },
-  });
+          structuredResult: aftPayload<typeof aftSearchStructuredSchema>(response, text),
+        };
+      },
+    }),
+  );
 }

package/src/codemode/declarations.ts

@@ -12,7 +12,8 @@ interface ToolLike {
   name: string;
   description?: string;
   parameters?: unknown;
-  structuredSchema?: unknown;
+  /** 只有声明了它的工具才可调用（见 `tool.ts` 的准入条件），因此这里是必需的。 */
+  structuredSchema: unknown;
 }
 
 type JsonSchema = Record<string, unknown>;
@@ -88,8 +89,7 @@ function renderType(schema: unknown, indent: string): string {
 function renderOverload(tool: ToolLike): string {
   const summary = tool.description?.split("\n", 1)[0]?.trim();
   const doc = summary ? `/** ${summary} */\n` : "";
-  const output =
-    tool.structuredSchema === undefined ? "string" : renderType(tool.structuredSchema, "");
+  const output = renderType(tool.structuredSchema, "");
   return `${doc}declare function call(name: ${JSON.stringify(tool.name)}, args: ${renderType(tool.parameters, "")}): Promise<${output}>;`;
 }
 

package/src/codemode/tool.ts

@@ -5,7 +5,7 @@
  * 自己的确认层），以及 `fs.read` / `fs.write` 两个文件原语（同样由主线程执行，与文件工具
  * 共用写审批与已读记账，见 fs.ts）。
  *
- * 可调用集合：总线上实际注册的工具减去 `EXCLUDED_TOOL_NAMES`，执行时再与 active
+ * 可调用集合：总线上实际注册的、**声明了 `structuredSchema`** 的工具，执行时再与 active
  * 列表求交——pi 自己的 `defaultTools` / `--tools` / 子代理白名单的排除因此同样生效。
  *
  * wasm 在注册这个工具时编译一次（`createCodemodeSandbox`），worker 复用编译结果。
@@ -32,30 +32,16 @@ import { CODEMODE_SOURCE_GRAMMAR, DEFAULT_OUTPUT_TOKENS, parseCodemodeSource } f
 export const CODEMODE_TOOL_NAME = "codemode";
 
 /**
- * 不暴露给脚本的工具：
- * - codemode 自身（防递归）；
- * - spawn-agent：它启动一个新的隔离会话，成本与运行时长都不适合放进脚本编排；
- * - 两套文件工具集的读写工具：脚本用 `fs.read` / `fs.write`（原文、不截断、按路径整体
- *   写入），不重复给一套为 LLM 上下文设计的行号/锚点语义；
- * - 两套工具集的搜索工具：脚本用 `call("Bash", { command })` 跑 `rg` / `grep` 更顺手——
- *   退出码可用、能拼管道，而这两个工具是给模型看结果的（相对路径、分组渲染、分页尾巴），
- *   声明块（尤其 Grep 的参数表与三选一输出）也白占 codemode 的描述篇幅。
+ * 准入条件：工具**声明了 `structuredSchema`** 才进 codemode。
+ *
+ * 脚本拿到的返回值必须有确定的形状——只给文本的工具在脚本里既没法当数据用（得解析文本），
+ * 也没有返回类型能写进声明。用「有没有结构化输出」当门槛，这条规则自己会维持一致：不给工具
+ * 加 schema 就不进集合，不需要维护一份会随工具增减而漂移的黑名单。因此下列工具天然不在集合
+ * 里，理由各自成立：`codemode` 自身与 `spawn-agent`（没有 schema）、文件读写工具（脚本用
+ * `fs.read` / `fs.write`，不重复一套为 LLM 上下文设计的行号/锚点语义）、搜索工具（脚本用
+ * `call("Bash", { command })` 跑 `rg`，退出码可用、能拼管道）、`lsp-rename`（写工具）以及
+ * talk / 会话工具（会把执行时间交给外部输入）。
  */
-const EXCLUDED_TOOL_NAMES: ReadonlySet<string> = new Set([
-  CODEMODE_TOOL_NAME,
-  "spawn-agent",
-  "Read",
-  "Edit",
-  "Write",
-  "read",
-  "edit",
-  "write",
-  "Grep",
-  "Glob",
-  "grep",
-  "glob",
-]);
-
 /** 估计 token 用的字符数（与 pi 一致）。 */
 const CHARS_PER_TOKEN = 4;
 
@@ -78,7 +64,8 @@ interface CallableTool {
   name: string;
   description?: string;
   parameters?: unknown;
-  structuredSchema?: unknown;
+  /** 准入条件：进集合的工具一定带着它（见上面的注释）。 */
+  structuredSchema: unknown;
 }
 
 /** 只在 pi 有 active 工具概念时才求交（子代理、`--tools` 等场景）。 */
@@ -94,7 +81,7 @@ function allowedToolNames(pi: ExtensionAPI): Set<string> | undefined {
 function collectTools(bus: ToolBus, allowed: Set<string> | undefined): CallableTool[] {
   return bus
     .list()
-    .filter((definition) => !EXCLUDED_TOOL_NAMES.has(definition.name))
+    .filter((definition) => definition.structuredSchema !== undefined)
     .filter((definition) => allowed === undefined || allowed.has(definition.name))
     .map((definition) => ({
       name: definition.name,