@trim21/personal-pi-extensions 0.1.664 → 0.1.669

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trim21/personal-pi-extensions",
-  "version": "0.1.664",
+  "version": "0.1.669",
   "type": "module",
   "description": "Custom pi coding-agent extensions: bwrap sandbox, workspace guard, opencode edit, and more",
   "keywords": [
@@ -88,7 +88,7 @@
     "node": ">=24.14"
   },
   "dependencies": {
-    "@cortexkit/aft-bridge": "0.58.0",
+    "@cortexkit/aft-bridge": "0.58.2",
     "@mozilla/readability": "^0.6.0",
     "@parcel/watcher": "^2.6.0",
     "@vscode/tree-sitter-wasm": "^0.3.1",
@@ -105,6 +105,6 @@
     "web-tree-sitter": "^0.27.0"
   },
   "optionalDependencies": {
-    "@cortexkit/aft-linux-x64": "0.58.0"
+    "@cortexkit/aft-linux-x64": "0.58.2"
   }
 }

package/src/aft/index.ts

@@ -8,6 +8,11 @@
  * openai_compatible / ollama 且有 base_url）时注册；aft 默认的本地 ONNX
  * fastembed 后端不使用。
  *
+ * 项目根是**会话工作目录**（`session_start` 的 `ctx.cwd`），不是 pi 进程的启动
+ * 目录：引擎按项目根建索引与调用图存储，用错会把用户家目录当项目根并自动关闭这
+ * 些能力。扩展自己只读用户级 aft.jsonc（路径与会话目录无关），项目级 aft.jsonc
+ * 由 bridge 按项目根自行读取。
+ *
  * bridge 状态（日志 + 常驻 aft 子进程）的生命周期跟 session 走：session_start
  * 时先解析 aft 二进制（含 GitHub release auto-download 兜底）——找不到就
  * notify warning 且不注册任何 aft 工具，避免模型看到只会抛 "not initialized"
@@ -19,7 +24,7 @@
  *   pi -e ./aft/index.ts
  */
 
-import { resolveCortexKitConfigPaths } from "@cortexkit/aft-bridge";
+import { resolveCortexKitUserConfigPath } from "@cortexkit/aft-bridge";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 
 import type { ToolBus } from "../lib/tool-bus.js";
@@ -27,6 +32,7 @@ import { registerToolsOnSessionStart } from "../lib/tool-registration.js";
 import { createAftState, findBinary, resolveSessionId, shutdownAftPool } from "./bridge.js";
 import { loadAftConfig } from "./config.js";
 import {
+  type AftToolContext,
   registerCallgraphTool,
   registerOutlineTool,
   registerSearchTool,
@@ -35,14 +41,15 @@ import {
 
 /**
  * aft 工具集：入口用它。`registerForSession` 必须在会话启动时调用——二进制
- * 探测、semantic_search 的提示、bridge 状态的创建都在里面；找不到二进制就不
- * 注册任何工具（避免模型看到只会抛 "not initialized" 的死工具）。
+ * 探测、semantic_search 的提示、bridge 状态（项目根 = 本会话的 `ctx.cwd`）的
+ * 创建都在里面；找不到二进制就不注册任何工具（避免模型看到只会抛
+ * "not initialized" 的死工具）。
  */
 export function createAftTools(pi: ExtensionAPI): {
   registerForSession(bus: ToolBus, ctx: ExtensionContext): Promise<void>;
 } {
-  const cwd = process.cwd();
-  const cfg = loadAftConfig(resolveCortexKitConfigPaths(cwd).userConfigPath);
+  // 扩展自己的门控只读用户级配置：项目级 aft.jsonc 由 bridge 按会话工作目录读。
+  const cfg = loadAftConfig(resolveCortexKitUserConfigPath());
   // bridge 状态跟 session 生命周期走，作用域就是本工厂闭包，不落到模块级。
   let state: Awaited<ReturnType<typeof createAftState>> | null = null;
 
@@ -55,7 +62,7 @@ export function createAftTools(pi: ExtensionAPI): {
     return state;
   };
 
-  const toolCtx = { cwd, getState };
+  const toolCtx: AftToolContext = { getState };
 
   async function registerForSession(bus: ToolBus, ctx: ExtensionContext): Promise<void> {
     if (!cfg.enabled) {
@@ -91,7 +98,7 @@ export function createAftTools(pi: ExtensionAPI): {
       registerSearchTool(bus, toolCtx);
     }
 
-    state = await createAftState(cwd, resolveSessionId(ctx), binaryPath, cfg.semanticRemote);
+    state = await createAftState(ctx.cwd, resolveSessionId(ctx), binaryPath, cfg.semanticRemote);
   }
 
   // 释放当前 session 的 bridge 状态。session_shutdown 是 pi 的正常生命周期；

package/src/aft/tools.ts

@@ -57,13 +57,13 @@ const AFT_GUIDELINES = readFileSync(
 ).trim();
 
 export interface AftToolContext {
-  cwd: string;
   /** 当前 session 的 bridge 状态；session 未初始化时抛错。 */
   getState(): AftState;
 }
 
 function bridgeFor(ctx: AftToolContext): AftProjectTransport {
-  return ctx.getState().pool.pool.getBridge(ctx.cwd);
+  const { pool } = ctx.getState();
+  return pool.pool.getBridge(pool.projectRoot);
 }
 
 /**
@@ -152,7 +152,7 @@ export function registerOutlineTool(bus: ToolBus, ctx: AftToolContext): void {
         filesMode = stats?.isDirectory() ?? false;
       }
       const rawArgs = compactArgs({
-        target: filesMode ? target : resolved,
+        target: resolved,
         files: filesMode || undefined,
         includeTests: params.includeTests,
       });

package/src/codemode/tool.ts

@@ -3,8 +3,9 @@
  * 的能力是调用 `tools.*`——每个嵌套调用都由主线程经本仓库的工具总线执行，因此工具实现
  * 内部的审批（工作区外写入、Bash 沙箱提权等）照常生效；codemode 不再加自己的确认层。
  *
- * 可调用集合：总线上实际注册的工具减去 codemode 自身，执行时再与 active 列表求交——
- * pi 自己的 `defaultTools` / `--tools` / 子代理白名单的排除因此同样生效。
+ * 可调用集合：总线上实际注册的工具减去 codemode 自身与 spawn-agent，执行时再与 active
+ * 列表求交——pi 自己的 `defaultTools` / `--tools` / 子代理白名单的排除因此同样生效。
+ * spawn-agent 被排除是因为它启动一个新的隔离会话、成本与运行时长都不适合放进脚本编排。
  *
  * wasm 在注册这个工具时编译一次（`createCodemodeSandbox`），worker 复用编译结果。
  */
@@ -26,6 +27,9 @@ import { CODEMODE_SOURCE_GRAMMAR, DEFAULT_OUTPUT_TOKENS, parseCodemodeSource } f
 
 export const CODEMODE_TOOL_NAME = "codemode";
 
+/** 不暴露给脚本的工具：codemode 自身（防递归）与 spawn-agent（见文件头注释）。 */
+const EXCLUDED_TOOL_NAMES: ReadonlySet<string> = new Set([CODEMODE_TOOL_NAME, "spawn-agent"]);
+
 /** 估计 token 用的字符数（与 pi 一致）。 */
 const CHARS_PER_TOKEN = 4;
 
@@ -56,7 +60,7 @@ function allowedToolNames(pi: ExtensionAPI): Set<string> | undefined {
 function collectTools(bus: ToolBus, allowed: Set<string> | undefined): CallableTool[] {
   return bus
     .list()
-    .filter((definition) => definition.name !== CODEMODE_TOOL_NAME)
+    .filter((definition) => !EXCLUDED_TOOL_NAMES.has(definition.name))
     .filter((definition) => allowed === undefined || allowed.has(definition.name))
     .map((definition) => ({
       name: definition.name,

package/src/spawn-agent.ts

@@ -131,7 +131,10 @@ const spawnAgentSchema = Type.Object({
     description:
       "Name of the subagent type to invoke. Choose one of the available subagent types listed in your system prompt.",
   }),
-  task: Type.String({ description: "Task to delegate to the subagent" }),
+  task: Type.String({
+    description:
+      "Self-contained task for the subagent, which sees none of this conversation: state the repository path, the exact question, and what the answer must contain (file paths with line numbers).",
+  }),
 });
 
 // ── result types ─────────────────────────────────────────────────────────────
@@ -499,9 +502,19 @@ export async function runAgent(
 export function formatAgentListSection(agents: AgentConfig[]): string {
   const lines = agents.map((a) => `- \`${a.name}\`: ${a.description}`);
   return [
+    "### Delegating to subagents",
+    "",
+    "Delegate a focused, read-only research task when the answer is a summary rather than source you must quote or edit:",
+    "",
+    "- locating code whose position is unknown, or answering a question that spans several files;",
+    "- several independent lookups at once — issue one `spawn-agent` call per lookup in the same message and they run concurrently;",
+    "- keeping the searching and reading out of your own context window.",
+    "",
+    "Do not delegate work you are about to do yourself — a single file you will edit, a change whose evidence must be the exact source text, or anything that writes. A subagent sees none of this conversation, so its task must be self-contained. Treat its answer as a pointer and read the location it names before acting on it.",
+    "",
     "### Available subagents",
     "",
-    "You can delegate tasks to the following subagent types by calling the `spawn-agent` tool with their name in the `agent` parameter:",
+    "Pass one of these names as the `agent` parameter:",
     "",
     ...lines,
   ].join("\n");
@@ -526,9 +539,11 @@ export function createSpawnAgentTool(): { register(bus: ToolBus): void } {
       bus.register<typeof spawnAgentSchema, SubagentDetails>({
         name: "spawn-agent",
         label: "spawn-agent",
+        promptSnippet: "Delegate focused research to a subagent with its own context window",
         description: [
-          "Delegate a task to a subagent that runs in an isolated session with its own context window, inside this pi process rather than a separate one.",
-          "The call blocks until the subagent finishes its turn; its final output comes back as the tool result.",
+          "Delegate a self-contained research task to a subagent that runs in an isolated session with its own context window, inside this pi process rather than a separate one.",
+          "The call blocks until the subagent finishes its turn and returns only its final answer: its intermediate tool calls are not visible to you.",
+          "Several `spawn-agent` calls issued in the same message run concurrently.",
           "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(" "),