@trim21/personal-pi-extensions 0.0.332 → 0.0.334

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trim21/personal-pi-extensions",
-  "version": "0.0.332",
+  "version": "0.0.334",
   "type": "module",
   "description": "Custom pi coding-agent extensions: bwrap sandbox, workspace guard, opencode edit, and more",
   "keywords": [

package/src/aft/callgraph.md

@@ -0,0 +1,18 @@
+### aft_callgraph tool
+
+基于真实调用图回答代码关系问题（谁调用我、影响面、调用链），替代 grep + read 的链条式排查。
+
+op 选择：
+
+- `callers`：谁调用了目标符号。改名/改签名前先查调用点。含测试文件用 `includeTests: true`。
+- `impact`：改动一个符号会波及谁（影响面分析）。与 callers 配合评估重构风险。
+- `call_tree`：目标符号调用了什么（展开调用链）。
+- `trace_to`：从某个入口函数如何执行到目标符号（调用链路径）。
+- `trace_to_symbol`：两个符号之间的最短路径。需要 `toSymbol`；同名符号歧义时用 `toPath` 指定目标文件。
+- `trace_data`：追踪某个值在参数/赋值间的流转。需要 `expression`（如参数名、变量名）。
+
+参数：`path`（包含目标符号的文件）+ `symbol` 必填；`depth` 限制遍历深度。
+
+标记含义：`~` = 仅按名字解析的边（可能指向同名符号）；`[unresolved]` = 未解析到定义的调用点（外部库/stdlib 默认折叠为每父节点一条摘要，`includeUnresolved: true` 逐个列出）。
+
+符号未定义或调用图索引仍在构建时返回文本说明，不报错。

package/src/aft/import.md

@@ -0,0 +1,12 @@
+### aft_import tool
+
+语言感知的 import 管理：add / remove。
+
+支持 TS, JS, TSX, Python, Rust, Go, Solidity, Java, C#, PHP, Kotlin, Scala, Swift, Ruby, Lua, C, C++, Perl, Vue。
+
+- `add`：添加默认导入（`default_import`）、具名导入（`names`，支持按名 `as` 别名，如 `['useState']`、`['ERC20', 'IERC20 as IToken']`）、命名空间导入（`namespace`，如 `import * as ns from 'mod'`）。
+- `remove`：移除整个 import（只给 `module`），或只移除其中某个具名导入（`remove_name`）。
+- 语言相关修饰符用 `modifiers`（如 Java/C# `static`、Swift `@testable`）；符号类导入用 `import_kind`（如 PHP `function`/`const`、Swift `struct`/`enum`）；仅类型导入用 `type_only`（仅 TS）。
+- `validate`：编辑后校验级别，默认 `syntax`，`full` 做完整校验。
+
+import 排序整理交给 lint（如 import/order + --fix），本工具不负责排序。写操作走路径级审批。

package/src/aft/imports.ts

@@ -6,6 +6,9 @@
  * 与 aft_refactor 相同：不支持 preview，写保护为路径级审批。
  */
 
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 
@@ -14,6 +17,12 @@ import { guardWriteAccess } from "../lib/write-guard.js";
 import { callAftTool } from "./bridge.js";
 import { type AftToolContext, bridgeFor, buildPendantMarkdown, resolvePathArg } from "./tools.js";
 
+/** 工具使用指南，以 markdown 形式维护，读起来像文档。 */
+const IMPORT_PROMPT = readFileSync(
+  fileURLToPath(new URL("import.md", import.meta.url)),
+  "utf8",
+).trim();
+
 const IMPORT_OPS = ["add", "remove"] as const;
 const VALIDATE_LEVELS = ["syntax", "full"] as const;
 
@@ -82,6 +91,7 @@ export function registerImportTool(pi: ExtensionAPI, ctx: AftToolContext): void
       "import 排序整理交给 lint（如 import/order + --fix），本工具不负责。",
     ].join("\n"),
     promptSnippet: "Language-aware import add / remove",
+    promptGuidelines: [IMPORT_PROMPT],
     parameters: ImportParams,
     async execute(_id, params, _signal, _onUpdate, extCtx) {
       if (params.module === undefined || params.module.trim() === "") {

package/src/aft/outline.md

@@ -0,0 +1,11 @@
+### aft_outline tool
+
+在读取具体内容之前先了解文件或目录的结构（比整文件 read 省 token）。
+
+- target 为文件路径时：返回该文件的符号大纲，每个符号带签名与行号（如 `function greet(name: string): void 5:12`）；Markdown/HTML 返回标题层级。适合先定位符号名和位置，再决定是否用 aft_zoom 看实现。
+- target 为目录路径时：默认返回扁平文件树（语言、顶层符号数、字节大小），一眼看清目录里有什么、规模多大；传 `files: false` 可切换为符号大纲（目录下每个文件的符号树，无签名，输出上限 30KB，超限截断）。
+- `includeTests` 只在符号大纲模式（`files: false`）生效：为 true 时包含测试文件，默认排除。
+- 目录递归上限 200 个文件；超出部分在结果中标记截断。
+- 只接受单个 target，不支持数组；跨文件批量用多次调用。
+
+分工：看结构用本工具；看某个符号的完整源码用 aft_zoom；看符号间调用关系用 aft_callgraph；按语义/文本搜代码用 aft_search。

package/src/aft/refactor.md

@@ -0,0 +1,9 @@
+### aft_refactor tool
+
+workspace-wide 重构：跨文件移动符号、抽函数、内联，自动更新引用与 import。
+
+- `move`：把顶层符号（非嵌套函数/类方法）移到另一个文件，全 workspace 重写 import 与引用；执行前自动创建 checkpoint。需要 `symbol` + `destination`；同名符号歧义时用 `scope` 消歧。注意：move / rename 整个文件请用 aft_move（OS 层操作，不更新引用）。
+- `extract`：把行区间抽成新函数（TS/JS/TSX、Python）。需要 `name` + `start_line` + `end_line`（1 起，含端点）。
+- `inline`：把调用点替换为函数体。需要 `symbol` + `call_site_line`（1 起）。
+
+重构是写操作：不支持 preview（无 diff 预览），写保护退化为路径级审批——workspace 内目标自动放行，外部路径需要确认。重构前先看影响面：对目标符号跑 aft_callgraph `impact`，确认波及范围符合预期再动手。

package/src/aft/refactor.ts

@@ -7,6 +7,9 @@
  * （workspace 内自动放行，外部路径经 write-guard 确认，无 diff 预览）。
  */
 
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
 import { coerceOptionalInt } from "@cortexkit/aft-bridge";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
@@ -16,6 +19,12 @@ import { guardWriteAccess } from "../lib/write-guard.js";
 import { callAftTool } from "./bridge.js";
 import { type AftToolContext, bridgeFor, buildPendantMarkdown, resolvePathArg } from "./tools.js";
 
+/** 工具使用指南，以 markdown 形式维护，读起来像文档。 */
+const REFACTOR_PROMPT = readFileSync(
+  fileURLToPath(new URL("refactor.md", import.meta.url)),
+  "utf8",
+).trim();
+
 const REFACTOR_OPS = ["move", "extract", "inline"] as const;
 
 function requireField(value: unknown, name: string, op: string): void {
@@ -68,6 +77,7 @@ export function registerRefactorTool(pi: ExtensionAPI, ctx: AftToolContext): voi
       "move / rename 整个文件用 aft_move（OS 层操作，不更新引用）；移动代码符号用本工具 op=move。",
     ].join("\n"),
     promptSnippet: "Workspace-wide symbol move / function extraction / inlining",
+    promptGuidelines: [REFACTOR_PROMPT],
     parameters: RefactorParams,
     async execute(_id, params, _signal, _onUpdate, extCtx) {
       const startLine = coerceOptionalInt(

package/src/aft/search.md

@@ -0,0 +1,11 @@
+### aft_search tool
+
+一个工具完成代码搜索，按意图自动路由到合适的引擎并按相关度排序。
+
+- 概念类查询（"ORM 如何构建并执行查询"）用自然语言整句：语义通道理解意图，匹配 docstring 与注释。
+- 精确的名字、字符串、正则保持简短（`^export`、`Cargo.lock`）：走词法/正则匹配通道。
+- `topK`：最大结果数，默认 10，最大 100。
+- `includeTests: true`：包含测试文件，默认排除。
+- `path`：仅当要搜索另一个 Git 项目时设置（绝对或 ~ 路径）；默认搜索当前项目。
+
+需要语义索引可用（aft.jsonc 中 `semantic_search: true` 且 embedding 后端就绪）；否则退化为词法/正则通道。启用语义索引时，首次调用会阻塞到索引构建完成，避免拿到部分结果。

package/src/aft/tools.ts

@@ -5,8 +5,11 @@
  * 由 Rust 侧（tree-sitter 符号表 / trigram 索引 / 调用图）计算。
  */
 
+import { readFileSync } from "node:fs";
+import { stat } from "node:fs/promises";
 import { homedir } from "node:os";
 import { isAbsolute, join, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
 
 import {
   type AftProjectTransport,
@@ -23,6 +26,21 @@ import { Type } from "typebox";
 import { type ToolPendant } from "../lib/pendant.js";
 import { callAftTool, SEMANTIC_INDEX_WAIT_TIMEOUT_MS } from "./bridge.js";
 
+/** 工具使用指南，以 markdown 形式维护，读起来像文档。 */
+const OUTLINE_PROMPT = readFileSync(
+  fileURLToPath(new URL("outline.md", import.meta.url)),
+  "utf8",
+).trim();
+const ZOOM_PROMPT = readFileSync(fileURLToPath(new URL("zoom.md", import.meta.url)), "utf8").trim();
+const CALLGRAPH_PROMPT = readFileSync(
+  fileURLToPath(new URL("callgraph.md", import.meta.url)),
+  "utf8",
+).trim();
+const SEARCH_PROMPT = readFileSync(
+  fileURLToPath(new URL("search.md", import.meta.url)),
+  "utf8",
+).trim();
+
 /** 解析 `~` 前缀与相对路径（相对 session cwd）。URL 与绝对路径原样返回。 */
 export function resolvePathArg(cwd: string, input: string): string {
   if (input === "~" || input.startsWith("~/")) {
@@ -84,16 +102,18 @@ const OutlineParams = Type.Object(
   {
     target: Type.String({
       description:
-        "要 outline 的对象：文件路径、目录路径或 URL（http:// 或 https://）。只接受单个 target；目录递归上限 200 个文件。",
+        "要 outline 的对象：文件路径或目录路径。只接受单个 target；目录递归上限 200 个文件。",
     }),
     files: Type.Optional(
       Type.Boolean({
         description:
-          "目录模式：为 true 时 target 必须是目录，返回带语言/符号数/字节大小的扁平文件树，而非符号大纲。",
+          "为 true 时 target 必须是目录，返回带语言/符号数/字节大小的扁平文件树，而非符号大纲。默认：target 为目录时 true，为文件时 false。",
       }),
     ),
     includeTests: Type.Optional(
-      Type.Boolean({ description: "目录大纲：包含测试文件。默认 false。" }),
+      Type.Boolean({
+        description: "目录符号大纲（files: false）模式：包含测试文件。默认 false。",
+      }),
     ),
   },
   { additionalProperties: false },
@@ -104,25 +124,28 @@ export function registerOutlineTool(pi: ExtensionAPI, ctx: AftToolContext): void
     name: "aft_outline",
     label: "aft_outline",
     description: [
-      "输出代码文件、目录、URL 的结构化大纲：函数/类/类型等符号及其行号范围；Markdown/HTML 返回标题层级。",
+      "输出代码文件、目录的结构化大纲：函数/类/类型等符号及其行号范围；Markdown/HTML 返回标题层级。",
       "用它在读取具体内容之前先了解文件结构（比整文件 read 省 token）。",
       "深入了解某个符号用 aft_zoom；看跨文件调用关系用 aft_callgraph。",
-      "target 支持：文件路径（带签名的符号大纲）、目录路径（递归最多 200 文件）、URL。只接受单个 target。",
-      "files: true 且 target 为目录时返回扁平文件树（语言、顶层符号数、字节大小）。",
+      "target 支持：文件路径（带签名的符号大纲）、目录路径（递归最多 200 文件）。只接受单个 target。",
+      "target 为目录时默认返回扁平文件树（语言、顶层符号数、字节大小）；传 files: false 可改回符号大纲。",
     ].join("\n"),
-    promptSnippet: "Output structural outline of a file/directory/URL",
+    promptSnippet: "Output structural outline of a file/directory",
+    promptGuidelines: [OUTLINE_PROMPT],
     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 or URL (array targets are not supported)");
+        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 filesMode = coerceBoolean(params.files);
       const rawArgs: Record<string, unknown> = {
-        target:
-          filesMode || target.startsWith("http://") || target.startsWith("https://")
-            ? target
-            : resolvePathArg(extCtx.cwd, target),
+        target: filesMode ? target : resolved,
       };
       if (filesMode) rawArgs.files = true;
       if (params.includeTests !== undefined) rawArgs.includeTests = params.includeTests;
@@ -139,23 +162,12 @@ export function registerOutlineTool(pi: ExtensionAPI, ctx: AftToolContext): void
   });
 }
 
-const ZoomTarget = Type.Object({
-  path: Type.String({ description: "文件路径（绝对或相对项目根）" }),
-  symbol: Type.String({ description: "该文件中的符号名" }),
-});
-
 const ZoomParams = Type.Object(
   {
-    path: Type.Optional(Type.String({ description: "文件路径（绝对或相对项目根）" })),
-    url: Type.Optional(Type.String({ description: "要 zoom 的 HTML/Markdown 文档 URL" })),
+    path: Type.String({ description: "文件路径（绝对或相对项目根）" }),
     symbols: Type.Optional(
       Type.Union([Type.String(), Type.Array(Type.String())], {
-        description: "符号名（代码）或标题文本（Markdown/HTML）；字符串或数组（同文件批量查询）。",
-      }),
-    ),
-    targets: Type.Optional(
-      Type.Union([ZoomTarget, Type.Array(ZoomTarget)], {
-        description: "跨文件批量：`{ path, symbol }` 或数组。与 path/url/symbols 互斥。",
+        description: "符号名（代码）或标题文本；字符串或数组（同文件批量查询）。",
       }),
     ),
     contextLines: Type.Optional(
@@ -180,51 +192,16 @@ export function registerZoomTool(pi: ExtensionAPI, ctx: AftToolContext): void {
       "查看命名符号（函数/类/类型）的完整源码，或 Markdown/HTML 的标题段落内容。",
       "需要理解某个具体符号时用它（读整个文件用 read）。",
       "callgraph: true 时附带同文件内的调用关系标注。",
-      "三种模式互斥，用且仅用一种：`{ path, symbols }`、`{ url, symbols }`、`{ targets }`。",
+      "同文件多符号用 `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 isEmpty = (v: unknown): boolean =>
-        v === undefined || v === null || v === "" || (Array.isArray(v) && v.length === 0);
-
-      const hasPath = !isEmpty(params.path);
-      const hasUrl = !isEmpty(params.url);
-      const hasSymbols = !isEmpty(params.symbols);
-      const hasTargets = !isEmpty(params.targets);
-
-      if (hasTargets && (hasPath || hasUrl || hasSymbols)) {
-        throw new Error("'targets' 与 'path'/'url'/'symbols' 互斥，只能提供一种模式");
-      }
-      if (hasPath && hasUrl) {
-        throw new Error("'path' 与 'url' 互斥，只能提供一种");
-      }
-      if (!hasTargets && !hasPath && !hasUrl) {
-        throw new Error("Provide exactly one of 'path', 'url', or 'targets'");
-      }
-
-      const rawArgs: Record<string, unknown> = {};
-      if (hasTargets) {
-        const targetList = params.targets;
-        if (!targetList) {
-          throw new Error("'targets' must be a non-empty object or array");
-        }
-        const list = Array.isArray(targetList) ? targetList : [targetList];
-        rawArgs.targets = list.map((t) => ({
-          filePath: resolvePathArg(extCtx.cwd, t.path),
-          symbol: t.symbol,
-        }));
-      } else if (hasUrl) {
-        rawArgs.url = params.url;
-        if (hasSymbols) rawArgs.symbols = params.symbols;
-      } else {
-        const filePath = params.path;
-        if (!filePath) {
-          throw new Error("'path' must be a non-empty string");
-        }
-        rawArgs.filePath = resolvePathArg(extCtx.cwd, filePath);
-        if (hasSymbols) rawArgs.symbols = params.symbols;
-      }
+      const rawArgs: Record<string, unknown> = {
+        filePath: resolvePathArg(extCtx.cwd, params.path),
+        ...(params.symbols && { symbols: params.symbols }),
+      };
 
       const contextLines = coerceOptionalInt(
         params.contextLines,
@@ -260,35 +237,15 @@ export function registerZoomTool(pi: ExtensionAPI, ctx: AftToolContext): void {
   });
 }
 
-/** 构建 aft_zoom pendant 的 subtitle：`path="…" symbol="…"`，url 模式为 `url="…"`。 */
+/** 构建 aft_zoom pendant 的 subtitle：`path="…" symbol="…"`。 */
 export function buildZoomSubtitle(
   cwd: string,
   params: Type.Static<typeof ZoomParams>,
 ): string | undefined {
-  const isEmpty = (v: unknown): boolean =>
-    v === undefined || v === null || v === "" || (Array.isArray(v) && v.length === 0);
-
-  const parts: string[] = [];
-  const targets = params.targets;
-  if (Array.isArray(targets)) {
-    for (const t of targets) {
-      parts.push(
-        `path="${formatDisplayPath(cwd, resolvePathArg(cwd, t.path))}" symbol="${t.symbol}"`,
-      );
-    }
-  } else if (targets) {
-    parts.push(
-      `path="${formatDisplayPath(cwd, resolvePathArg(cwd, targets.path))}" symbol="${targets.symbol}"`,
-    );
-  } else if (!isEmpty(params.url)) {
-    parts.push(`url="${params.url}"`);
-  } else if (params.path) {
-    const symbols = params.symbols;
-    const symbolStr = Array.isArray(symbols) ? symbols.join(", ") : symbols;
-    const pathPart = `path="${formatDisplayPath(cwd, resolvePathArg(cwd, params.path))}"`;
-    parts.push(symbolStr ? `${pathPart} symbol="${symbolStr}"` : pathPart);
-  }
-  return parts.length > 0 ? parts.join(" ") : undefined;
+  const symbols = params.symbols;
+  const symbolStr = Array.isArray(symbols) ? symbols.join(", ") : symbols;
+  const pathPart = `path="${formatDisplayPath(cwd, resolvePathArg(cwd, params.path))}"`;
+  return symbolStr ? `${pathPart} symbol="${symbolStr}"` : pathPart;
 }
 
 const CALLGRAPH_OPS = [
@@ -345,6 +302,7 @@ export function registerCallgraphTool(pi: ExtensionAPI, ctx: AftToolContext): vo
       "标记：~ = 仅按名字解析的边（可能指向同名符号）；[unresolved] = 未解析到定义的调用点。",
     ].join("\n"),
     promptSnippet: "Call graph and data-flow navigation",
+    promptGuidelines: [CALLGRAPH_PROMPT],
     parameters: CallgraphParams,
     async execute(_id, params, _signal, _onUpdate, extCtx) {
       const rawArgs: Record<string, unknown> = {
@@ -437,6 +395,7 @@ export function registerSearchTool(pi: ExtensionAPI, ctx: AftToolContext): void
       "启用语义索引时，首次调用会阻塞到索引构建完成，避免返回部分结果。",
     ].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) {

package/src/aft/zoom.md

@@ -0,0 +1,11 @@
+### aft_zoom tool
+
+查看命名符号（函数/类/类型）的完整源码，或 Markdown/HTML 文档的标题段落内容。
+
+- `path` 必填：文件路径（绝对或相对项目根）。
+- `symbols`：要查看的符号名；字符串或数组（同文件多个符号一次查询）。代码文件按符号名精确解析；Markdown/HTML 按标题文本匹配（可含空格，用完整标题字符串）。
+- `contextLines`：符号前后附加的上下文行数，默认 3。
+- `callgraph: true`：附带同文件内 calls-out / called-by 调用关系标注，帮助理解符号如何被使用、依赖谁。
+- 适合先 aft_outline 拿到符号名与行号，再 zoom 具体实现；不要用它读整个文件（用 read）。
+
+只支持本地文件路径，不支持 URL。

package/src/claude-code/bash.md

@@ -1,4 +1,4 @@
-# Bash tool
+### Bash tool
 
 Executes a given bash command and returns its output.
 

package/src/claude-code/edit.md

@@ -1,4 +1,4 @@
-# Edit tool
+### Edit tool
 
 Performs exact string replacements in files.
 

package/src/claude-code/files.ts

@@ -228,7 +228,7 @@ export function registerFileTools(
       "This tool reads files, not directories.",
     ].join("\n"),
     promptSnippet: "Read files from the local filesystem with line numbers",
-    promptGuidelines: [`- -\n${READ_PROMPT}`],
+    promptGuidelines: [READ_PROMPT],
     parameters: Type.Object(
       {
         file_path: Type.String({ description: "The absolute path to the file to read" }),
@@ -331,7 +331,7 @@ export function registerFileTools(
       "This tool does not use regular expressions or fuzzy matching.",
     ].join("\n"),
     promptSnippet: "Make exact string replacements in files",
-    promptGuidelines: [`- -\n${EDIT_PROMPT}`],
+    promptGuidelines: [EDIT_PROMPT],
     parameters: Type.Object(
       {
         file_path: Type.String({ description: "The absolute path to the file to modify" }),
@@ -502,7 +502,7 @@ export function registerFileTools(
       "If the file exists, you must use Read first. Prefer Edit for partial changes.",
     ].join("\n"),
     promptSnippet: "Create or overwrite files",
-    promptGuidelines: [`- -\n${WRITE_PROMPT}`],
+    promptGuidelines: [WRITE_PROMPT],
     parameters: Type.Object(
       {
         file_path: Type.String({

package/src/claude-code/glob.md

@@ -1,4 +1,4 @@
-# Glob tool
+### Glob tool
 
 - Fast file pattern matching tool that works with any codebase size
 - Supports glob patterns like `**/*.js` or `src/**/*.ts`

package/src/claude-code/glob.ts

@@ -111,7 +111,7 @@ export function registerGlobTool(pi: ExtensionAPI): void {
       "Returns matching file paths sorted by modification time (oldest first).",
     ].join("\n"),
     promptSnippet: "Find files by name patterns",
-    promptGuidelines: [`- -\n${GLOB_PROMPT}`],
+    promptGuidelines: [GLOB_PROMPT],
     parameters: Type.Object(
       {
         pattern: Type.String({ description: "The glob pattern to match files against" }),

package/src/claude-code/grep.md

@@ -1,4 +1,4 @@
-# Grep tool
+### Grep tool
 
 A powerful search tool built on ripgrep.
 

package/src/claude-code/grep.ts

@@ -241,7 +241,7 @@ export function registerGrepTool(pi: ExtensionAPI): void {
       'output_mode defaults to "files_with_matches"; use "content" for matching lines or "count" for match counts.',
     ].join("\n"),
     promptSnippet: "Search file contents with regular expressions",
-    promptGuidelines: [`- -\n${GREP_PROMPT}`],
+    promptGuidelines: [GREP_PROMPT],
     parameters: grepParametersSchema,
     async execute(_id, params, signal, _onUpdate, ctx) {
       if (

package/src/claude-code/read.md

@@ -1,4 +1,4 @@
-# Read tool
+### Read tool
 
 Reads a file from the local filesystem. You can access any file directly by using this tool.
 

package/src/claude-code/session-tools.ts

@@ -177,7 +177,7 @@ export function registerSessionTools(pi: ExtensionAPI): void {
       'If you recommend an option, put it first and append "(Recommended)" to its label.',
     ].join("\n"),
     promptSnippet: "Ask the user questions during execution",
-    promptGuidelines: [`- -\n${ASK_PROMPT}`],
+    promptGuidelines: [ASK_PROMPT],
     parameters: Type.Object(
       {
         questions: Type.Array(questionSchema, {

package/src/claude-code/shell.ts

@@ -79,7 +79,7 @@ export function registerShellTools(
   pi.registerTool({
     name: "Bash",
     promptSnippet: "execute command",
-    promptGuidelines: [`- -\n${BASH_PROMPT}`],
+    promptGuidelines: [BASH_PROMPT],
     label: "Bash",
     description: [
       "Executes a given bash command synchronously and returns its output.",

package/src/claude-code/write.md

@@ -1,4 +1,4 @@
-# Write tool
+### Write tool
 
 Writes a file to the local filesystem.
 

package/src/spawn-agent.ts

@@ -4,9 +4,9 @@
  *
  * The subagent definition comes from `~/.pi/agent/agents/*.md` (markdown with
  * YAML frontmatter, see spawn-agent-agents.ts). The extension discovers the
- * available subagent types once at startup and appends them to the system
- * prompt on every agent start (same pattern as the bwrap extension), so the
- * model always knows which `agent` names it can pass to the tool. Execution
+ * available subagent types once at startup and injects the list via the tool's
+ * `promptGuidelines`, so the model always knows which `agent` names it can
+ * pass to the tool. Execution
  * is blocking: the tool awaits the subagent process until it exits and
  * returns its final output to the parent model. Progress is streamed through
  * `onUpdate`, the same channel the built-in bash tool uses for live output.
@@ -622,7 +622,7 @@ function parseJsonRecord(line: string): Record<string, unknown> | null {
 export function formatAgentListSection(agents: AgentConfig[]): string {
   const lines = agents.map((a) => `- \`${a.name}\`: ${a.description}`);
   return [
-    "## Available subagents",
+    "### Available subagents",
     "",
     "You can delegate tasks to the following subagent types by calling the `spawn-agent` tool with their name in the `agent` parameter:",
     "",
@@ -653,15 +653,6 @@ export default function spawnAgent(pi: ExtensionAPI) {
   );
   const agentListSection = agents.length > 0 ? formatAgentListSection(agents) : null;
 
-  if (agentListSection) {
-    // Same pattern as the bwrap extension: append the list to the system
-    // prompt on every agent start. The system prompt is rebuilt each turn
-    // anyway, so a persistent per-session injection would add no value.
-    pi.on("before_agent_start", (event) => {
-      return { systemPrompt: `${event.systemPrompt}\n\n${agentListSection}` };
-    });
-  }
-
   pi.registerTool<typeof spawnAgentSchema, SubagentDetails>({
     name: "spawn-agent",
     label: "spawn-agent",
@@ -670,6 +661,7 @@ export default function spawnAgent(pi: ExtensionAPI) {
       "The `agent` parameter must be one of the available subagent types listed in the system prompt.",
       `Subagents run read-only (${DEFAULT_TOOLS.join(", ")}) unless the agent declares an explicit toolset.`,
     ].join(" "),
+    promptGuidelines: agentListSection ? [agentListSection] : undefined,
     parameters: spawnAgentSchema,
 
     async execute(_toolCallId, params, signal, onUpdate, ctx) {

package/src/system-prompt/index.ts

@@ -71,11 +71,11 @@ export function formatTools(
   return lines.length > 0 ? lines.join("\n") : "(none)";
 }
 
-/** 渲染工具特定 guideline bullets；为空时整个块（含标题）省略 */
+/** 渲染工具特定 guideline 块；为空时整个块（含标题）省略。guide 本身是 md 文档，直接拼接。 */
 export function formatGuidelines(promptGuidelines: string[] | undefined): string {
-  const bullets = (promptGuidelines ?? []).map((g) => g.trim()).filter((g) => g.length > 0);
-  if (bullets.length === 0) return "";
-  return `## Guidelines\n\n${bullets.map((g) => `- ${g}`).join("\n")}`;
+  const items = (promptGuidelines ?? []).map((g) => g.trim()).filter((g) => g.length > 0);
+  if (items.length === 0) return "";
+  return `## Guidelines\n\n${items.join("\n\n")}`;
 }
 
 /** 渲染 AGENTS.md 等上下文文件；为空时省略 */