@trim21/personal-pi-extensions 0.0.242 → 0.0.244

package/README.md

@@ -17,6 +17,14 @@
 | [question](#question)           | opencode 风格的提问工具，阻塞式询问用户选择             |
 | [talk](#talk)                   | session 间消息传递，SQLite 邮箱 + 双向 ask 时间戳仲裁   |
 
+> **两套工具风格，按预期只启用其中一套**：本包同时提供 opencode 风格
+> （小写 `read`/`edit`/`write`/`bash`/`todowrite`/`question`）与 Claude Code
+> 风格（大写 `Read`/`Edit`/`Write`/`Bash`/`Grep`/`Glob`/`TodoWrite`/
+> `AskUserQuestion`）两套工具集，二者共享 bwrap 沙箱与写保护实现。两套同时
+> 启用会带来预期外的冗余：同名命令重复注册（如 `/bwrap` 出现 `/bwrap:1`
+> 后缀）、系统提示重复注入。请只启用其中一套：在 `~/.pi/agent/settings.json`
+> 的 `defaultTools` 中只列出一套，或启动时用 `--exclude-tools` 排除另一套。
+
 ---
 
 ## bwrap

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trim21/personal-pi-extensions",
-  "version": "0.0.242",
+  "version": "0.0.244",
   "type": "module",
   "description": "Custom pi coding-agent extensions: bwrap sandbox, workspace guard, opencode edit, and more",
   "keywords": [
@@ -64,7 +64,8 @@
       "src/talk/index.ts"
     ],
     "skills": [
-      "src/talk/skills"
+      "src/talk/skills",
+      "src/claude-code/skills"
     ]
   },
   "lint-staged": {

package/src/bwrap/runtime.ts

@@ -320,5 +320,3 @@ export class BwrapRuntime {
 export function createBwrapRuntime(): BwrapRuntime {
   return new BwrapRuntime();
 }
-
-export const bwrapRuntime = createBwrapRuntime();

package/src/claude-code/common.ts

@@ -1,4 +1,16 @@
-import { isAbsolute, normalize, resolve } from "node:path";
+import { readdirSync } from "node:fs";
+import { realpath, stat } from "node:fs/promises";
+import {
+  basename,
+  dirname,
+  extname,
+  isAbsolute,
+  join,
+  normalize,
+  relative,
+  resolve,
+  sep,
+} from "node:path";
 
 import { Type } from "typebox";
 import { Value } from "typebox/value";
@@ -34,6 +46,12 @@ export function searchRoot(path: string | undefined, cwd: string): string {
   return isAbsolute(path) ? path : resolve(cwd, path);
 }
 
+/** 相对 cwd 的路径（超出 cwd 则保留绝对路径），对齐 Claude Code 省 token。 */
+export function toRelativePath(filePath: string, cwd: string): string {
+  const relativePath = relative(cwd, filePath);
+  return relativePath.startsWith("..") ? filePath : relativePath;
+}
+
 export function throwIfAborted(signal: AbortSignal | undefined): void {
   if (signal?.aborted) throw new Error("Operation aborted");
 }
@@ -42,6 +60,68 @@ export function snapshotsEqual(left: FileSnapshot, right: FileSnapshot): boolean
   return left.digest === right.digest;
 }
 
+/**
+ * 同目录下"同名不同扩展名"的文件（如请求 foo.ts 不存在，目录里有 foo.js），
+ * 对齐 Claude Code 的 findSimilarFile。返回文件名（不含路径）。
+ */
+export function findSimilarFile(filePath: string): string | undefined {
+  try {
+    const dir = dirname(filePath);
+    const fileBaseName = basename(filePath, extname(filePath));
+    const similar = readdirSync(dir).find(
+      (name) => basename(name, extname(name)) === fileBaseName && join(dir, name) !== filePath,
+    );
+    return similar;
+  } catch {
+    // 目录不存在（ENOENT）属预期，其他错误同样不阻塞建议
+    return undefined;
+  }
+}
+
+/**
+ * Dropped-repo-folder 检测（对齐 Claude Code 的 suggestPathUnderCwd）：模型给出
+ * 的绝对路径可能少了仓库目录组件。若请求路径位于 cwd 的父目录下（但不在 cwd
+ * 内），把相对父目录的部分拼到 cwd 下，存在则返回完整路径。
+ */
+export async function suggestPathUnderCwd(
+  requestedPath: string,
+  cwd: string,
+): Promise<string | undefined> {
+  const cwdParent = dirname(cwd);
+  // realpath 解析请求路径的父目录（如 macOS /tmp → /private/tmp），保证与
+  // cwd 的前缀比较一致
+  let resolvedPath = requestedPath;
+  try {
+    const resolvedDir = await realpath(dirname(requestedPath));
+    resolvedPath = join(resolvedDir, basename(requestedPath));
+  } catch {
+    // 父目录不存在，用原路径
+  }
+  const cwdParentPrefix = cwdParent === sep ? sep : cwdParent + sep;
+  if (
+    resolvedPath === cwd ||
+    !resolvedPath.startsWith(cwdParentPrefix) ||
+    resolvedPath.startsWith(cwd + sep)
+  ) {
+    return undefined;
+  }
+  const relFromParent = relative(cwdParent, resolvedPath);
+  const correctedPath = join(cwd, relFromParent);
+  try {
+    await stat(correctedPath);
+    return correctedPath;
+  } catch {
+    return undefined;
+  }
+}
+
+/** "Did you mean" 建议：优先 cwd 重定位，其次同名不同扩展（对齐 Claude Code）。 */
+export async function didYouMean(filePath: string, cwd: string): Promise<string | undefined> {
+  const cwdSuggestion = await suggestPathUnderCwd(filePath, cwd);
+  if (cwdSuggestion) return cwdSuggestion;
+  return findSimilarFile(filePath);
+}
+
 /**
  * 从工具结果 details 里恢复文件已读记账（跨进程 resume / reload / fork）。
  * 数据来自 session 文件，可能缺失或损坏：逐条 TypeBox 校验，非法条目丢弃。

package/src/claude-code/edit-utils.ts

@@ -0,0 +1,116 @@
+/**
+ * Claude Code 风格 Edit 的字符串匹配工具（移植自真实 Claude Code 的
+ * FileEditTool/utils.ts）。
+ *
+ * - findActualString：先精确匹配，失败则做引号规范化匹配（文件里的花引号
+ *   与模型输出的直引号等价），返回文件中的真实文本；
+ * - preserveQuoteStyle：当 old_string 通过引号规范化命中时，把 new_string
+ *   里的直引号换成文件使用的花引号风格，保持文件的排版一致。
+ */
+
+export const LEFT_SINGLE_CURLY_QUOTE = "‘";
+export const RIGHT_SINGLE_CURLY_QUOTE = "’";
+export const LEFT_DOUBLE_CURLY_QUOTE = "“";
+export const RIGHT_DOUBLE_CURLY_QUOTE = "”";
+
+/** 把花引号规范化为直引号（匹配与替换两侧都用它做归一）。 */
+export function normalizeQuotes(str: string): string {
+  return str
+    .replaceAll(LEFT_SINGLE_CURLY_QUOTE, "'")
+    .replaceAll(RIGHT_SINGLE_CURLY_QUOTE, "'")
+    .replaceAll(LEFT_DOUBLE_CURLY_QUOTE, '"')
+    .replaceAll(RIGHT_DOUBLE_CURLY_QUOTE, '"');
+}
+
+/**
+ * 在文件内容中查找与搜索串匹配的实际文本。
+ * 先精确匹配；失败则把两侧花引号归一为直引号后重试，返回文件中的原文。
+ */
+export function findActualString(fileContent: string, searchString: string): string | null {
+  if (fileContent.includes(searchString)) return searchString;
+  const normalizedSearch = normalizeQuotes(searchString);
+  const normalizedFile = normalizeQuotes(fileContent);
+  const searchIndex = normalizedFile.indexOf(normalizedSearch);
+  if (searchIndex !== -1) {
+    return fileContent.slice(searchIndex, searchIndex + searchString.length);
+  }
+  return null;
+}
+
+/** 引号前是空白/行首/开括号/破折号时视为开引号，否则视为闭引号。 */
+function isOpeningContext(chars: string[], index: number): boolean {
+  if (index === 0) return true;
+  const prev = chars[index - 1];
+  return (
+    prev === " " ||
+    prev === "\t" ||
+    prev === "\n" ||
+    prev === "\r" ||
+    prev === "(" ||
+    prev === "[" ||
+    prev === "{" ||
+    prev === "\u2014" || // em dash
+    prev === "\u2013" // en dash
+  );
+}
+
+function applyCurlyDoubleQuotes(str: string): string {
+  const chars = [...str];
+  const result: string[] = [];
+  for (let i = 0; i < chars.length; i++) {
+    if (chars[i] === '"') {
+      result.push(isOpeningContext(chars, i) ? LEFT_DOUBLE_CURLY_QUOTE : RIGHT_DOUBLE_CURLY_QUOTE);
+    } else {
+      result.push(chars[i]);
+    }
+  }
+  return result.join("");
+}
+
+function applyCurlySingleQuotes(str: string): string {
+  const chars = [...str];
+  const result: string[] = [];
+  for (let i = 0; i < chars.length; i++) {
+    if (chars[i] === "'") {
+      // 缩写中的撇号（如 don't）用右花引号，不做开/闭判断
+      const prev = chars[i - 1];
+      const next = chars[i + 1];
+      const prevIsLetter = prev !== undefined && /\p{L}/u.test(prev);
+      const nextIsLetter = next !== undefined && /\p{L}/u.test(next);
+      if (prevIsLetter && nextIsLetter) {
+        result.push(RIGHT_SINGLE_CURLY_QUOTE);
+      } else {
+        result.push(
+          isOpeningContext(chars, i) ? LEFT_SINGLE_CURLY_QUOTE : RIGHT_SINGLE_CURLY_QUOTE,
+        );
+      }
+    } else {
+      result.push(chars[i]);
+    }
+  }
+  return result.join("");
+}
+
+/**
+ * 当 old_string 通过引号规范化命中（oldString !== actualOldString）时，
+ * 把 new_string 中的直引号换成文件实际使用的花引号风格。
+ */
+export function preserveQuoteStyle(
+  oldString: string,
+  actualOldString: string,
+  newString: string,
+): string {
+  if (oldString === actualOldString) return newString;
+  const hasDoubleQuotes =
+    actualOldString.includes(LEFT_DOUBLE_CURLY_QUOTE) ||
+    actualOldString.includes(RIGHT_DOUBLE_CURLY_QUOTE);
+  const hasSingleQuotes =
+    actualOldString.includes(LEFT_SINGLE_CURLY_QUOTE) ||
+    actualOldString.includes(RIGHT_SINGLE_CURLY_QUOTE);
+  if (!hasDoubleQuotes && !hasSingleQuotes) return newString;
+
+  let result = newString;
+  if (hasDoubleQuotes) result = applyCurlyDoubleQuotes(result);
+  if (hasSingleQuotes) result = applyCurlySingleQuotes(result);
+  return result;
+}

package/src/claude-code/files.ts

@@ -16,15 +16,31 @@ import { Type } from "typebox";
 import { guardWriteAccess } from "../lib/write-guard.js";
 import {
   type ClaudeCodeState,
+  didYouMean,
   type FileSnapshot,
   requireAbsolutePath,
   snapshotsEqual,
   throwIfAborted,
 } from "./common.js";
+import { findActualString, preserveQuoteStyle } from "./edit-utils.js";
 
-const DEFAULT_READ_LINES = 2000;
 const SAMPLE_BYTES = 4096;
 
+/** Read 全读时的文件大小上限（对齐 Claude Code 的 256KB）。 */
+const MAX_READ_SIZE_BYTES = 0.25 * 1024 * 1024;
+/** Read 输出 token 粗估上限（对齐 Claude Code 的 25K tokens；无 tokenizer，按 4 字符/token 估算）。 */
+const MAX_READ_TOKENS = 25_000;
+
+/** Edit 最大文件大小（stat 字节数），防止大文件 OOM（对齐 Claude Code）。 */
+const MAX_EDIT_FILE_SIZE = 1024 * 1024 * 1024; // 1 GiB
+
+function formatFileSize(bytes: number): string {
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+  if (bytes < 1024 * 1024 * 1024) return `${(bytes / 1024 / 1024).toFixed(1)} MB`;
+  return `${(bytes / 1024 / 1024 / 1024).toFixed(1)} GB`;
+}
+
 /** Tool guidance, kept in markdown so it reads like documentation. */
 const READ_PROMPT = readFileSync(fileURLToPath(new URL("read.md", import.meta.url)), "utf8").trim();
 const EDIT_PROMPT = readFileSync(fileURLToPath(new URL("edit.md", import.meta.url)), "utf8").trim();
@@ -71,54 +87,49 @@ function isBinary(sample: Uint8Array): boolean {
   return sample.length > 0 && suspicious / sample.length > 0.3;
 }
 
+/**
+ * 对齐 Claude Code 的 readFileInRange + addLineNumbers：
+ * - 剥离 UTF-8 BOM；
+ * - 非空文件按「每行 + 一个尾随空行」切分（真实 CC 的尾部 fragment 无条件
+ *   加入，等价于补一个 \n 再 split），所以 totalLines 总比编辑器显示行数多 1；
+ * - 每行去掉尾随 \r（CRLF → LF）。
+ */
 function splitFileLines(content: string): string[] {
-  if (content === "") return [];
-  const lines = content.split("\n");
-  if (content.endsWith("\n")) lines.pop();
-  return lines;
+  const text = content.replace(/^\uFEFF/, "");
+  if (text === "") return [];
+  return (text.endsWith("\n") ? text : `${text}\n`)
+    .split("\n")
+    .map((line) => (line.endsWith("\r") ? line.slice(0, -1) : line));
 }
 
+/**
+ * 格式化读取输出（对齐 Claude Code 的 addLineNumbers）：行号无 padding，
+ * limit 未指定时读取全部。无 PARTIAL 提示、无单行截断（由 execute 层的
+ * 字节/token 上限兜底）。
+ */
 export function formatReadOutput(
   content: string,
   offset = 1,
-  limit = DEFAULT_READ_LINES,
-): { text: string; complete: boolean; totalLines: number } {
+  limit?: number,
+): { text: string; totalLines: number } {
   const lines = splitFileLines(content);
   const totalLines = lines.length;
   if (totalLines === 0) {
-    if (offset > 1)
-      return {
-        text: `<system-reminder>Warning: the file exists but has fewer lines than the provided offset (${offset}). The file has 0 lines.</system-reminder>`,
-        complete: false,
-        totalLines,
-      };
     return {
-      text: "<system-reminder>Warning: the file exists but has empty contents.</system-reminder>",
-      complete: true,
+      text: "<system-reminder>Warning: the file exists but the contents are empty.</system-reminder>",
       totalLines,
     };
   }
   if (offset > totalLines) {
     return {
-      text: `<system-reminder>Warning: the file exists but has fewer lines than the provided offset (${offset}). The file has ${totalLines} lines.</system-reminder>`,
-      complete: false,
+      text: `<system-reminder>Warning: the file exists but is shorter than the provided offset (${offset}). The file has ${totalLines} lines.</system-reminder>`,
       totalLines,
     };
   }
-
-  const selected = lines.slice(offset - 1, offset - 1 + limit);
-  const numbered = selected
-    .map(
-      (line, index) =>
-        `${String(offset + index).padStart(6)}\t${line.length > 2000 ? line.slice(0, 2000) : line}`,
-    )
-    .join("\n");
-  const complete = offset === 1 && selected.length === totalLines;
-  const hasMore = offset - 1 + selected.length < totalLines;
-  const notice = hasMore
-    ? `\n\n<system-reminder>PARTIAL view: showing lines ${offset}-${offset + selected.length - 1} of ${totalLines}. Use offset and limit to read more.</system-reminder>`
-    : "";
-  return { text: numbered + notice, complete, totalLines };
+  const selected =
+    limit === undefined ? lines.slice(offset - 1) : lines.slice(offset - 1, offset - 1 + limit);
+  const text = selected.map((line, index) => `${offset + index}\t${line}`).join("\n");
+  return { text, totalLines };
 }
 
 function countMatches(content: string, needle: string): number {
@@ -155,15 +166,18 @@ export function exactReplace(
 
 async function requireCurrentRead(state: ClaudeCodeState, filePath: string): Promise<void> {
   const readSnapshot = state.reads.get(filePath);
-  if (!readSnapshot)
-    throw new Error(`File has not been read yet. Read it first before writing to it: ${filePath}`);
+  if (!readSnapshot) {
+    throw new Error("File has not been read yet. Read it first before writing to it.");
+  }
   if (!readSnapshot.textEditable) {
     throw new Error(`Cannot edit or overwrite a binary file with a text tool: ${filePath}`);
   }
   const currentContent = await readFile(filePath);
   const current = snapshotOf(currentContent);
   if (!snapshotsEqual(readSnapshot, current)) {
-    throw new Error(`File has been modified since read. Read it again before writing: ${filePath}`);
+    throw new Error(
+      "File has been modified since read, either by the user or by a linter. Read it again before attempting to write it.",
+    );
   }
 }
 
@@ -173,7 +187,7 @@ export function registerFileTools(pi: ExtensionAPI, state: ClaudeCodeState): voi
     label: "Read",
     description: [
       "Reads a file from the local filesystem. You can access any file directly using this tool.",
-      "The file_path parameter must be an absolute path. By default, it reads up to 2000 lines from the beginning.",
+      "The file_path parameter must be an absolute path. By default, it reads the entire file; files over 256 KB or 25K tokens require offset and limit.",
       "Results use cat -n style line numbers starting at 1. Images are returned visually.",
       "This tool reads files, not directories.",
     ].join("\n"),
@@ -192,7 +206,7 @@ export function registerFileTools(pi: ExtensionAPI, state: ClaudeCodeState): voi
       },
       { additionalProperties: false },
     ),
-    async execute(_id, params, signal) {
+    async execute(_id, params, signal, _onUpdate, ctx) {
       throwIfAborted(signal);
       const filePath = requireAbsolutePath(params.file_path);
       if (
@@ -204,7 +218,19 @@ export function registerFileTools(pi: ExtensionAPI, state: ClaudeCodeState): voi
       if (params.limit !== undefined && (!Number.isSafeInteger(params.limit) || params.limit < 1)) {
         throw new Error("limit must be a positive integer");
       }
-      await assertReadableFile(filePath);
+      // 文件不存在 → 友好错误 + Did you mean（对齐 Claude Code）
+      try {
+        await assertReadableFile(filePath);
+      } catch (error) {
+        if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+          const suggestion = await didYouMean(filePath, ctx.cwd);
+          throw new Error(
+            `File does not exist. Note: your current working directory is ${ctx.cwd}.${suggestion ? ` Did you mean ${suggestion}?` : ""}`,
+            { cause: error },
+          );
+        }
+        throw error;
+      }
       throwIfAborted(signal);
 
       const extension = extname(filePath).toLowerCase();
@@ -229,11 +255,21 @@ export function registerFileTools(pi: ExtensionAPI, state: ClaudeCodeState): voi
       const buffer = await readFile(filePath);
       if (isBinary(buffer.subarray(0, SAMPLE_BYTES)))
         throw new Error(`Cannot read binary file: ${filePath}`);
-      const formatted = formatReadOutput(
-        buffer.toString("utf8"),
-        params.offset ?? 1,
-        params.limit ?? DEFAULT_READ_LINES,
-      );
+      // 全读（limit 未传）时受字节上限约束（对齐 Claude Code）
+      if (params.limit === undefined && buffer.length > MAX_READ_SIZE_BYTES) {
+        throw new Error(
+          `File content (${formatFileSize(buffer.length)}) exceeds maximum allowed size (${formatFileSize(MAX_READ_SIZE_BYTES)}). Use offset and limit parameters to read specific portions of the file, or search for specific content instead of reading the whole file.`,
+        );
+      }
+      const text = buffer.toString("utf8");
+      const formatted = formatReadOutput(text, params.offset ?? 1, params.limit);
+      // 输出 token 粗估上限（无 tokenizer，4 字符/token），对读取范围生效
+      const estimatedTokens = Math.ceil(formatted.text.length / 4);
+      if (estimatedTokens > MAX_READ_TOKENS) {
+        throw new Error(
+          `File content (${estimatedTokens} tokens) exceeds maximum allowed tokens (${MAX_READ_TOKENS}). Use offset and limit parameters to read specific portions of the file, or search for specific content instead of reading the whole file.`,
+        );
+      }
       const snapshot = snapshotOf(buffer);
       state.reads.set(filePath, snapshot);
       return {
@@ -278,25 +314,109 @@ export function registerFileTools(pi: ExtensionAPI, state: ClaudeCodeState): voi
         },
       });
       return withFileMutationQueue(filePath, async () => {
+        const oldString = params.old_string;
+        const newString = params.new_string;
+        if (oldString === newString) {
+          throw new Error("No changes to make: old_string and new_string are exactly the same.");
+        }
+        // 空 old_string：创建新文件或填充空文件（不需要先 Read，对齐 Claude Code）
+        if (oldString === "") {
+          let exists = true;
+          try {
+            const value = await stat(filePath);
+            if (value.isFile()) {
+              const content = await readFile(filePath, "utf8");
+              if (content.trim() !== "") {
+                throw new Error("Cannot create new file - file already exists.");
+              }
+            }
+          } catch (error) {
+            if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+              exists = false;
+            } else {
+              throw error;
+            }
+          }
+          if (!exists) await mkdir(dirname(filePath), { recursive: true });
+          await writeFile(filePath, newString, "utf8");
+          const snapshot = snapshotOf(newString);
+          state.reads.set(filePath, snapshot);
+          return {
+            content: [
+              { type: "text", text: `The file ${filePath} has been updated successfully.` },
+            ],
+            details: { reads: { [filePath]: snapshot } } satisfies FileToolDetails,
+          };
+        }
+        const replaceAll = params.replace_all ?? false;
+        // 防止 OOM 的大文件检查（对齐 Claude Code）
+        try {
+          const { size } = await stat(filePath);
+          if (size > MAX_EDIT_FILE_SIZE) {
+            throw new Error(
+              `File is too large to edit (${formatFileSize(size)}). Maximum editable file size is ${formatFileSize(MAX_EDIT_FILE_SIZE)}.`,
+            );
+          }
+        } catch (error) {
+          if (!(error instanceof Error) || !("code" in error) || error.code !== "ENOENT") {
+            throw error;
+          }
+        }
+        let original: string;
+        try {
+          original = await readFile(filePath, "utf8");
+        } catch (error) {
+          if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+            const suggestion = await didYouMean(filePath, ctx.cwd);
+            throw new Error(
+              `File does not exist. Note: your current working directory is ${ctx.cwd}.${suggestion ? ` Did you mean ${suggestion}?` : ""}`,
+              { cause: error },
+            );
+          }
+          throw error;
+        }
+        if (extname(filePath).toLowerCase() === ".ipynb") {
+          throw new Error(
+            "File is a Jupyter Notebook. Use the NotebookEditTool to edit this file.",
+          );
+        }
         await requireCurrentRead(state, filePath);
         await access(filePath, constants.R_OK | constants.W_OK);
-        const original = await readFile(filePath, "utf8");
         throwIfAborted(signal);
-        const updated = exactReplace(
-          original,
-          params.old_string,
-          params.new_string,
-          params.replace_all ?? false,
-        );
-        await writeFile(filePath, updated, "utf8");
-        const snapshot = snapshotOf(updated);
+
+        // CRLF 规范化后匹配（old_string 不需要带 \r），写回时恢复原行尾
+        const crlfCount = (original.match(/\r\n/g) ?? []).length;
+        const lfCount = (original.match(/(?<!\r)\n/g) ?? []).length;
+        const lineEnding = crlfCount > lfCount ? "\r\n" : "\n";
+        const normalized = original.replaceAll("\r\n", "\n");
+        const actualOldString = findActualString(normalized, oldString) ?? oldString;
+        const matches = normalized.split(actualOldString).length - 1;
+        if (matches === 0) {
+          throw new Error(`String to replace not found in file.\nString: ${oldString}`);
+        }
+        if (!replaceAll && matches > 1) {
+          throw new Error(
+            `Found ${matches} matches of the string to replace, but replace_all is false. To replace all occurrences, set replace_all to true. To replace only one occurrence, please provide more context to uniquely identify the instance.\nString: ${oldString}`,
+          );
+        }
+        const actualNewString = preserveQuoteStyle(oldString, actualOldString, newString);
+        // split/join 与函数替换：replacement 含 $ 时不会触发 $& 等特殊语义
+        const updated = replaceAll
+          ? normalized.split(actualOldString).join(actualNewString)
+          : normalized.replace(actualOldString, () => actualNewString);
+        const restored = lineEnding === "\r\n" ? updated.replaceAll("\n", "\r\n") : updated;
+        await writeFile(filePath, restored, "utf8");
+        const snapshot = snapshotOf(restored);
         state.reads.set(filePath, snapshot);
-        const diff = generateDiffString(original, updated);
+        const diff = generateDiffString(original, restored);
+        const text = replaceAll
+          ? `The file ${filePath} has been updated. All occurrences were successfully replaced.`
+          : `The file ${filePath} has been updated successfully.`;
         return {
-          content: [{ type: "text", text: `The file ${filePath} has been updated successfully.` }],
+          content: [{ type: "text", text }],
           details: {
             diff: diff.diff,
-            patch: generateUnifiedPatch(filePath, original, updated),
+            patch: generateUnifiedPatch(filePath, original, restored),
             firstChangedLine: diff.firstChangedLine,
             reads: { [filePath]: snapshot },
           } satisfies FileToolDetails,
@@ -341,7 +461,9 @@ export function registerFileTools(pi: ExtensionAPI, state: ClaudeCodeState): voi
             original = await readFile(filePath, "utf8");
           }
         } catch (error) {
-          if (!(error instanceof Error && "code" in error && error.code === "ENOENT")) throw error;
+          if (!(error instanceof Error) || !("code" in error) || error.code !== "ENOENT") {
+            throw error;
+          }
         }
         throwIfAborted(signal);
         await mkdir(dirname(filePath), { recursive: true });
@@ -349,8 +471,12 @@ export function registerFileTools(pi: ExtensionAPI, state: ClaudeCodeState): voi
         const snapshot = snapshotOf(params.content);
         state.reads.set(filePath, snapshot);
         const diff = generateDiffString(original ?? "", params.content);
+        const text =
+          original === undefined
+            ? `File created successfully at: ${filePath}`
+            : `The file ${filePath} has been updated successfully.`;
         return {
-          content: [{ type: "text", text: `File created successfully at: ${filePath}` }],
+          content: [{ type: "text", text }],
           details: {
             diff: diff.diff,
             patch: generateUnifiedPatch(filePath, original ?? "", params.content),

package/src/claude-code/glob.ts

@@ -5,42 +5,100 @@
  * independently (declare `Glob` in the frontmatter to get only this tool).
  */
 
+import { execFile } from "node:child_process";
 import { readFileSync } from "node:fs";
-import { glob as fsGlob, stat } from "node:fs/promises";
-import { resolve } from "node:path";
+import { stat } from "node:fs/promises";
+import { basename, dirname, isAbsolute, join, sep } from "node:path";
 import { fileURLToPath } from "node:url";
+import { promisify } from "node:util";
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 
-import { searchRoot, throwIfAborted } from "./common.js";
+import { searchRoot, suggestPathUnderCwd, throwIfAborted, toRelativePath } from "./common.js";
 
 const GLOB_RESULT_LIMIT = 100;
 
+const execFileAsync = promisify(execFile);
+
 /** Tool guidance, kept in markdown so it reads like documentation. */
 const GLOB_PROMPT = readFileSync(fileURLToPath(new URL("glob.md", import.meta.url)), "utf8").trim();
 
+/**
+ * 从绝对 glob pattern 中提取搜索根目录和相对 pattern（rg 的 --glob 只接受
+ * 相对 pattern）。对齐 Claude Code 的 extractGlobBaseDirectory。
+ */
+function extractGlobBaseDirectory(pattern: string): {
+  baseDir: string;
+  relativePattern: string;
+} {
+  const globChars = /[*?[{]/;
+  const match = globChars.exec(pattern);
+  if (!match || match.index === undefined) {
+    // 无 glob 特殊字符：字面路径，目录部分作为 baseDir
+    return { baseDir: dirname(pattern), relativePattern: basename(pattern) };
+  }
+  const staticPrefix = pattern.slice(0, match.index);
+  const lastSepIndex = Math.max(staticPrefix.lastIndexOf("/"), staticPrefix.lastIndexOf(sep));
+  if (lastSepIndex === -1) return { baseDir: "", relativePattern: pattern };
+  let baseDir = staticPrefix.slice(0, lastSepIndex);
+  const relativePattern = pattern.slice(lastSepIndex + 1);
+  // 根目录 pattern（如 /*.txt）：baseDir 为空但应使用 "/"
+  if (baseDir === "" && lastSepIndex === 0) baseDir = "/";
+  return { baseDir, relativePattern };
+}
+
+/**
+ * 对齐 Claude Code 的 glob（rg --files）：按修改时间升序（最旧在前）排序，
+ * --no-ignore/--hidden 不尊重 gitignore、包含隐藏文件。相比真实 CC 额外排除
+ * .git（--hidden 会列出 .git 内容，属于噪音）。返回截断标记。
+ */
 export async function globFiles(
   pattern: string,
   cwd: string,
   signal?: AbortSignal,
-): Promise<string[]> {
+): Promise<{ files: string[]; truncated: boolean }> {
   throwIfAborted(signal);
-  const matches: { path: string; mtimeMs: number }[] = [];
-  for await (const match of fsGlob(pattern, { cwd, exclude: [".git/**"], withFileTypes: false })) {
-    throwIfAborted(signal);
-    const absolutePath = resolve(cwd, match);
-    try {
-      const value = await stat(absolutePath);
-      if (value.isFile()) matches.push({ path: absolutePath, mtimeMs: value.mtimeMs });
-    } catch {
-      // A concurrent filesystem change can remove a match before stat.
+  let searchDir = cwd;
+  let searchPattern = pattern;
+  if (isAbsolute(pattern)) {
+    const { baseDir, relativePattern } = extractGlobBaseDirectory(pattern);
+    if (baseDir) {
+      searchDir = baseDir;
+      searchPattern = relativePattern;
     }
   }
-  return matches
-    .toSorted((left, right) => right.mtimeMs - left.mtimeMs || left.path.localeCompare(right.path))
-    .slice(0, GLOB_RESULT_LIMIT)
-    .map((match) => match.path);
+  const args = [
+    "--files",
+    "--glob",
+    searchPattern,
+    "--sort=modified",
+    "--no-ignore",
+    "--hidden",
+    "--glob",
+    "!.git/**",
+  ];
+  let stdout: string;
+  try {
+    const result = await execFileAsync("rg", args, {
+      cwd: searchDir,
+      maxBuffer: 10 * 1024 * 1024,
+      ...(signal && { signal }),
+    });
+    stdout = result.stdout;
+  } catch (error) {
+    if (signal?.aborted) throwIfAborted(signal);
+    throw new Error(`ripgrep failed: ${error instanceof Error ? error.message : String(error)}`, {
+      cause: error,
+    });
+  }
+  // rg 输出相对 searchDir 的路径，转成绝对路径
+  const lines = stdout ? stdout.replace(/\n$/, "").split("\n") : [];
+  const absolutePaths = lines.map((path) => (isAbsolute(path) ? path : join(searchDir, path)));
+  return {
+    files: absolutePaths.slice(0, GLOB_RESULT_LIMIT),
+    truncated: absolutePaths.length > GLOB_RESULT_LIMIT,
+  };
 }
 
 export function registerGlobTool(pi: ExtensionAPI): void {
@@ -50,7 +108,7 @@ export function registerGlobTool(pi: ExtensionAPI): void {
     description: [
       "Fast file pattern matching tool that works with any codebase size.",
       'Supports glob patterns such as "**/*.js" and "src/**/*.ts".',
-      "Returns matching file paths sorted by modification time.",
+      "Returns matching file paths sorted by modification time (oldest first).",
     ].join("\n"),
     promptSnippet: "Find files by name patterns",
     promptGuidelines: [`- -\n${GLOB_PROMPT}`],
@@ -68,12 +126,30 @@ export function registerGlobTool(pi: ExtensionAPI): void {
     ),
     async execute(_id, params, signal, _onUpdate, ctx) {
       const root = searchRoot(params.path, ctx.cwd);
-      const matches = await globFiles(params.pattern, root, signal);
+      if (params.path) {
+        let stats;
+        try {
+          stats = await stat(root);
+        } catch (error) {
+          if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+            const suggestion = await suggestPathUnderCwd(root, ctx.cwd);
+            throw new Error(
+              `Directory does not exist: ${params.path}. Note: your current working directory is ${ctx.cwd}.${suggestion ? ` Did you mean ${suggestion}?` : ""}`,
+              { cause: error },
+            );
+          }
+          throw error;
+        }
+        if (!stats.isDirectory()) throw new Error(`Path is not a directory: ${params.path}`);
+      }
+      const { files, truncated } = await globFiles(params.pattern, root, signal);
+      const filenames = files.map((filePath) => toRelativePath(filePath, ctx.cwd));
+      const lines = truncated
+        ? [...filenames, "(Results are truncated. Consider using a more specific path or pattern.)"]
+        : filenames;
       return {
-        content: [
-          { type: "text", text: matches.length > 0 ? matches.join("\n") : "No files found" },
-        ],
-        details: { count: matches.length },
+        content: [{ type: "text", text: lines.length > 0 ? lines.join("\n") : "No files found" }],
+        details: { count: filenames.length },
       };
     },
   });

package/src/claude-code/grep.ts

@@ -17,7 +17,7 @@ import { StringEnum } from "@earendil-works/pi-ai";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 
-import { searchRoot, throwIfAborted } from "./common.js";
+import { searchRoot, suggestPathUnderCwd, throwIfAborted, toRelativePath } from "./common.js";
 
 const GREP_OUTPUT_MODES = ["content", "files_with_matches", "count"] as const;
 
@@ -70,7 +70,8 @@ export function buildGrepArguments(params: GrepParameters, cwd: string): string[
       break;
     }
     case "count": {
-      args.push("--count-matches");
+      // -c 统计匹配行数（对齐 Claude Code；--count-matches 是匹配次数）
+      args.push("-c");
       break;
     }
     case "content": {
@@ -90,10 +91,26 @@ export function buildGrepArguments(params: GrepParameters, cwd: string): string[
     // No default
   }
   if (params["-i"] === true) args.push("--ignore-case");
-  if (params.glob) args.push("--glob", params.glob);
   if (params.type) args.push("--type", params.type);
   if (params.multiline === true) args.push("--multiline", "--multiline-dotall");
-  args.push("--", params.pattern, searchRoot(params.path, cwd));
+  // glob 按逗号/空格拆分（花括号模式不拆），对齐 Claude Code
+  if (params.glob) {
+    const globPatterns: string[] = [];
+    for (const rawPattern of params.glob.split(/\s+/)) {
+      if (rawPattern.includes("{") && rawPattern.includes("}")) {
+        globPatterns.push(rawPattern);
+      } else {
+        globPatterns.push(...rawPattern.split(",").filter(Boolean));
+      }
+    }
+    for (const globPattern of globPatterns) {
+      if (globPattern) args.push("--glob", globPattern);
+    }
+  }
+  // 以 - 开头的 pattern 用 -e 显式声明，防止被 rg 当作选项
+  if (params.pattern.startsWith("-")) args.push("-e", params.pattern);
+  else args.push(params.pattern);
+  args.push(searchRoot(params.path, cwd));
   return args;
 }
 
@@ -120,8 +137,9 @@ export async function sortFilesByMtime(output: string): Promise<string> {
 /**
  * Append an occurrence/file summary to `filename:count` output (count mode),
  * mirroring Claude Code's "Found N occurrences across M files" result.
+ * `limitInfo`（如 "limit: 250, offset: 5"）非空时追加 pagination 说明。
  */
-export function summarizeCountOutput(output: string): string {
+export function summarizeCountOutput(output: string, limitInfo?: string): string {
   const lines = output.split("\n").filter((line) => line.includes(":"));
   let occurrences = 0;
   for (const line of lines) {
@@ -131,14 +149,61 @@ export function summarizeCountOutput(output: string): string {
   const files = lines.length;
   const occurrenceLabel = occurrences === 1 ? "occurrence" : "occurrences";
   const fileLabel = files === 1 ? "file" : "files";
-  return `${output.trimEnd()}\n\nFound ${occurrences} total ${occurrenceLabel} across ${files} ${fileLabel}.`;
+  return `${output.trimEnd()}\n\nFound ${occurrences} total ${occurrenceLabel} across ${files} ${fileLabel}.${limitInfo ? ` with pagination = ${limitInfo}` : ""}`;
 }
 
-export function pageGrepOutput(output: string, offset = 0, headLimit = 0): string {
+/**
+ * 对齐 Claude Code 的 applyHeadLimit：offset 跳过前 N 条；head_limit=0 表示
+ * 无限；appliedLimit 仅在真正截断时返回（模型据此知道可以继续分页）。
+ */
+export function pageGrepOutput(
+  output: string,
+  offset = 0,
+  headLimit = 0,
+): { lines: string[]; appliedLimit: number | undefined; appliedOffset: number | undefined } {
   const lines = output ? output.replace(/\n$/, "").split("\n") : [];
-  if (offset >= lines.length && lines.length > 0) return "No entries at this offset";
-  const selected = headLimit > 0 ? lines.slice(offset, offset + headLimit) : lines.slice(offset);
-  return truncateOutput(selected.join("\n"));
+  if (headLimit === 0) {
+    return {
+      lines: lines.slice(offset),
+      appliedLimit: undefined,
+      appliedOffset: offset > 0 ? offset : undefined,
+    };
+  }
+  const sliced = lines.slice(offset, offset + headLimit);
+  return {
+    lines: sliced,
+    appliedLimit: lines.length - offset > headLimit ? headLimit : undefined,
+    appliedOffset: offset > 0 ? offset : undefined,
+  };
+}
+
+/** 分页信息文本，仅包含实际发生/提供的部分（对齐 Claude Code）。 */
+function formatLimitInfo(
+  appliedLimit: number | undefined,
+  appliedOffset: number | undefined,
+): string {
+  const parts: string[] = [];
+  if (appliedLimit !== undefined) parts.push(`limit: ${appliedLimit}`);
+  if (appliedOffset) parts.push(`offset: ${appliedOffset}`);
+  return parts.join(", ");
+}
+
+/** content 模式行：路径前缀相对化（`/abs/path:line:content` 取第一个冒号）。 */
+function relativizeContentLine(line: string, cwd: string): string {
+  const colonIndex = line.indexOf(":");
+  if (colonIndex > 0) {
+    return toRelativePath(line.slice(0, colonIndex), cwd) + line.slice(colonIndex);
+  }
+  return line;
+}
+
+/** count 模式行：路径前缀相对化（`/abs/path:count` 取最后一个冒号）。 */
+function relativizeCountLine(line: string, cwd: string): string {
+  const colonIndex = line.lastIndexOf(":");
+  if (colonIndex > 0) {
+    return toRelativePath(line.slice(0, colonIndex), cwd) + line.slice(colonIndex);
+  }
+  return line;
 }
 
 export function registerGrepTool(pi: ExtensionAPI): void {
@@ -210,29 +275,88 @@ export function registerGrepTool(pi: ExtensionAPI): void {
       ) {
         throw new Error("head_limit must be a non-negative integer");
       }
+      if (params.path) {
+        const absolutePath = searchRoot(params.path, ctx.cwd);
+        try {
+          await stat(absolutePath);
+        } catch (error) {
+          if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+            const suggestion = await suggestPathUnderCwd(absolutePath, ctx.cwd);
+            throw new Error(
+              `Path does not exist: ${params.path}. Note: your current working directory is ${ctx.cwd}.${suggestion ? ` Did you mean ${suggestion}?` : ""}`,
+              { cause: error },
+            );
+          }
+          throw error;
+        }
+      }
       const result = await pi.exec("rg", buildGrepArguments(params, ctx.cwd), { signal });
       throwIfAborted(signal);
       if (result.code !== 0 && result.code !== 1) {
         throw new Error(result.stderr.trim() || `ripgrep exited with code ${result.code}`);
       }
-      if (result.code === 1 || result.stdout === "") {
-        return { content: [{ type: "text", text: "No files found" }], details: { matches: 0 } };
-      }
       const mode = params.output_mode ?? "files_with_matches";
-      // head_limit defaults to DEFAULT_HEAD_LIMIT; an explicit 0 means unlimited.
-      const stdout =
-        mode === "files_with_matches" ? await sortFilesByMtime(result.stdout) : result.stdout;
-      const text = pageGrepOutput(
-        stdout,
-        params.offset ?? 0,
-        params.head_limit ?? DEFAULT_HEAD_LIMIT,
-      );
+      const offset = params.offset ?? 0;
+      const headLimit = params.head_limit ?? DEFAULT_HEAD_LIMIT;
+      // rg 退出码 1 = 无匹配，stdout 为空
+      const stdout = result.code === 1 ? "" : result.stdout;
+
+      if (mode === "files_with_matches") {
+        if (stdout === "") {
+          return { content: [{ type: "text", text: "No files found" }], details: { matches: 0 } };
+        }
+        const sorted = await sortFilesByMtime(stdout);
+        const { lines, appliedLimit, appliedOffset } = pageGrepOutput(sorted, offset, headLimit);
+        const filenames = lines.map((filePath) => toRelativePath(filePath, ctx.cwd));
+        const limitInfo = formatLimitInfo(appliedLimit, appliedOffset);
+        const text = truncateOutput(
+          `Found ${filenames.length} ${filenames.length === 1 ? "file" : "files"}${limitInfo ? ` ${limitInfo}` : ""}\n${filenames.join("\n")}`,
+        );
+        return { content: [{ type: "text", text }], details: { matches: filenames.length } };
+      }
+
       if (mode === "count") {
+        if (stdout === "") {
+          return {
+            content: [
+              {
+                type: "text",
+                text: "No matches found\n\nFound 0 total occurrences across 0 files.",
+              },
+            ],
+            details: undefined,
+          };
+        }
+        const { lines, appliedLimit, appliedOffset } = pageGrepOutput(stdout, offset, headLimit);
+        const relativized = lines.map((line) => relativizeCountLine(line, ctx.cwd));
         return {
-          content: [{ type: "text", text: summarizeCountOutput(text) }],
+          content: [
+            {
+              type: "text",
+              text: truncateOutput(
+                summarizeCountOutput(
+                  relativized.join("\n"),
+                  formatLimitInfo(appliedLimit, appliedOffset),
+                ),
+              ),
+            },
+          ],
           details: undefined,
         };
       }
+
+      // content mode
+      if (stdout === "") {
+        return { content: [{ type: "text", text: "No matches found" }], details: undefined };
+      }
+      const { lines, appliedLimit, appliedOffset } = pageGrepOutput(stdout, offset, headLimit);
+      const relativized = lines.map((line) => relativizeContentLine(line, ctx.cwd)).join("\n");
+      const limitInfo = formatLimitInfo(appliedLimit, appliedOffset);
+      const text = truncateOutput(
+        limitInfo
+          ? `${relativized}\n\n[Showing results with pagination = ${limitInfo}]`
+          : relativized,
+      );
       return { content: [{ type: "text", text }], details: undefined };
     },
   });

package/src/claude-code/read.md

@@ -5,9 +5,9 @@ Reads a file from the local filesystem. You can access any file directly by usin
 Usage:
 
 - The file_path parameter must be an absolute path, not a relative path
-- By default, it reads up to 2000 lines starting from the beginning of the file
+- By default, it reads the entire file; files over 256 KB or 25K tokens require offset and limit to read specific portions
 - When you already know which part of the file you need, only read that part. This can be important for larger files.
-- Results are returned using cat -n format, with line numbers starting at 1
+- Results are returned as `<lineNumber>\t<content>` lines, 1-indexed (Claude Code Read format)
 - This tool allows you to read images (eg PNG, JPG, etc). When reading an image file the contents are presented visually.
 - This tool can only read files, not directories. To read a directory, use an ls command via the Bash tool.
 - If you read a file that exists but has empty contents you will receive a system reminder warning in place of file contents.

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

@@ -158,7 +158,8 @@ export function registerSessionTools(pi: ExtensionAPI): void {
         content: [
           {
             type: "text" as const,
-            text: "Todos have been modified successfully. Ensure that you continue to use the todo list to track your progress. Please proceed with the current tasks if applicable.",
+            // 与 Claude Code 的 TodoWrite 逐字一致（无结尾句号）
+            text: "Todos have been modified successfully. Ensure that you continue to use the todo list to track your progress. Please proceed with the current tasks if applicable",
           },
         ],
         details: { todos },

package/src/claude-code/shell.ts

@@ -4,7 +4,7 @@ import { fileURLToPath } from "node:url";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 
-import { bwrapRuntime } from "../bwrap/runtime.js";
+import { type BwrapRuntime, createBwrapRuntime } from "../bwrap/runtime.js";
 import { resolveWorkdir } from "../lib/path.js";
 
 const DEFAULT_TIMEOUT_MS = 120_000;
@@ -13,8 +13,15 @@ const MAX_TIMEOUT_MS = 600_000;
 /** Bash tool guidance, kept in markdown so it reads like documentation. */
 const BASH_PROMPT = readFileSync(fileURLToPath(new URL("bash.md", import.meta.url)), "utf8").trim();
 
-export function registerShellTools(pi: ExtensionAPI): void {
-  bwrapRuntime.setup(pi);
+/**
+ * runtime 由调用方注入：扩展工厂持有一个实例（不依赖模块级全局状态），
+ * 测试可注入预置模式的实例。状态随扩展实例生命周期，session 切换重建即重置。
+ */
+export function registerShellTools(
+  pi: ExtensionAPI,
+  runtime: BwrapRuntime = createBwrapRuntime(),
+): void {
+  runtime.setup(pi);
   pi.registerTool({
     name: "Bash",
     promptSnippet: "execute command",
@@ -58,7 +65,7 @@ export function registerShellTools(pi: ExtensionAPI): void {
       const cwd = params.workdir ? await resolveWorkdir(params.workdir, ctx.cwd) : ctx.cwd;
 
       try {
-        return await bwrapRuntime.execute({
+        return await runtime.execute({
           ctx: { ...ctx, cwd },
           toolCallId: id,
           command: params.command,

package/src/claude-code/skills/claude-code-tools/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: claude-code-tools
+description: Exact behavior of the Claude Code style tools (Read/Edit/Write/Grep/Glob/Bash/TodoWrite/AskUserQuestion) in the @trim21/personal-pi-extensions package: output formats, matching rules, read-before-write requirements, pagination semantics, and conventions. Load whenever you use these tools or are unsure how they behave.
+---
+
+# Claude Code Tools Behavior
+
+This package registers two parallel tool suites: opencode style (lowercase `read`/`edit`/`write`/`bash`/`todowrite`/`question`) and Claude Code style (capitalized `Read`/`Edit`/`Write`/`Bash`/`Grep`/`Glob`/`TodoWrite`/`AskUserQuestion`). They share the bwrap sandbox and write-guard. **Only one suite should be enabled** — enabling both duplicates commands (e.g. `/bwrap` vs `/bwrap:1`) and injects the bwrap system-prompt section twice.
+
+The capitalized tools below follow Claude Code behavior with a few deliberate deviations. Where behavior differs from stock Claude Code it is called out.
+
+## Read
+
+- Output is `<lineNumber>\t<content>` per line, 1-indexed, **no padding** (compact format).
+- Input is normalized: UTF-8 BOM stripped, `\r\n` → `\n` (CRLF stripped), and a trailing empty line is always present — **`totalLines` is one more than the editor line count** for non-empty files.
+- By default reads the **entire file**, capped at 256 KB (bytes) and a rough 25K-token estimate (4 chars/token, no tokenizer). Whole reads over either cap error with `File content (X) exceeds maximum allowed size/tokens (...) — use offset and limit`; providing `limit` bypasses the byte cap and only the selected range counts toward the token cap.
+- `offset`/`limit` are 1-based positive integers. Out-of-range offset returns `Warning: the file exists but is shorter than the provided offset (N). The file has M lines.`; empty files return `Warning: the file exists but the contents are empty.`
+- Missing file → `File does not exist. Note: your current working directory is <cwd>.` plus a `Did you mean ...?` suggestion (same-base different-extension, or a corrected path under cwd).
+
+## Edit / Write
+
+- **You must Read a file before editing or overwriting it.** The tool compares a content digest against the last read; after your own Edit/Write the recorded digest is refreshed, so consecutive edits by you are fine. An external change (user edit, linter, another process) triggers `File has been modified since read, either by the user or by a linter. Read it again before attempting to write it.` — re-Read before writing.
+- **Deviation from Claude Code:** staleness is checked by content digest, not mtime.
+
+### Edit specifics
+
+- Matching first tries an exact match, then a **quote-normalized match** (curly quotes in the file match straight quotes from the model); the replacement inherits the file's curly-quote style.
+- Matching happens on CRLF-normalized content — `old_string` never needs `\r` — and the file's dominant line ending is restored on write.
+- Empty `old_string` means create-or-fill: nonexistent file → create it; empty file → fill it; non-empty file → `Cannot create new file - file already exists.` Neither create nor fill requires a prior Read.
+- `old_string === new_string` → `No changes to make: old_string and new_string are exactly the same.`
+- Not found → `String to replace not found in file.\nString: <old_string>`
+- Multiple matches without `replace_all` → error listing the match count and asking for more context, with `\nString: <old_string>`.
+- `replace_all: true` success message: `The file X has been updated. All occurrences were successfully replaced.`
+- Missing file → `File does not exist. Note: your current working directory is <cwd>.` plus a `Did you mean ...?` suggestion (same-base different-extension, or a corrected path under cwd).
+- Files over 1 GiB are refused; `.ipynb` files are refused.
+
+### Write specifics
+
+- Creating a new file → `File created successfully at: X`; overwriting an existing file → `The file X has been updated successfully.` (the distinction is reported even though both are one tool).
+- New files need no prior Read; overwriting does.
+
+## Grep
+
+- Modes: `files_with_matches` (default), `content`, `count`. All output paths are **relative to cwd** (absolute when outside cwd).
+- `files_with_matches`: `Found N files\n<relative paths>` sorted by mtime, newest first. No matches → `No files found`.
+- `content`: `path:line:content` lines. No matches → `No matches found`.
+- `count`: per-file match-line counts (`-c` semantics, not match occurrences) plus `Found N total occurrences across M files.` No matches → `No matches found` + `Found 0 total occurrences across 0 files.`
+- `head_limit` defaults to 250 (0 = unlimited), `offset` skips entries. When truncation or offset actually applied, a pagination note is appended (`limit: N, offset: N`), e.g. `[Showing results with pagination = limit: N, offset: N]`.
+- `glob` accepts comma/space-separated patterns (brace patterns not split). `-i`, `-B/-A/-C`/`context`, `-n` (default true in content mode), `type`, `multiline` map to ripgrep flags. VCS dirs (`.git` etc.) are excluded.
+- A missing `path` → `Path does not exist: ... Note: your current working directory is <cwd>.` with a corrected-path suggestion when applicable.
+
+## Glob
+
+- Backed by ripgrep (`--files --sort=modified`): results are **oldest first**, hidden files included, `.git` excluded, up to 100 results.
+- Output paths are relative to cwd. When truncated, a final line `(Results are truncated. Consider using a more specific path or pattern.)` is appended.
+- No matches → `No files found`. `path` must be an existing directory, else `Directory does not exist: ...` / `Path is not a directory: ...`.
+
+## Bash
+
+- Commands run through the bwrap sandbox (modes: `allow-all` / `workspace-write` / `allow-net` / `readonly`), switchable via `/bwrap-*` commands. `dangerouslyDisableSandbox: true` requests one-time unsandboxed execution and needs user approval (denied in headless sessions).
+- `timeout` is in milliseconds, default 120000, max 600000. `workdir` overrides the working directory.
+- **Deviation from Claude Code:** no auto-backgrounding on timeout — a timed-out command is killed and the error reports the timeout.
+
+## TodoWrite
+
+- Full-list replacement semantics: pass the complete updated list every call; exactly one `in_progress` allowed; statuses `pending` | `in_progress` | `completed`; each item needs `content` and `activeForm`.
+- The list renders as a widget and is persisted in tool `details`; after a restart the widget is restored from the session branch. The list is **not** auto-cleared when all items are completed.
+
+## AskUserQuestion
+
+- Blocking: 1–4 questions, 2–4 options each; `multiSelect` for multiple selection. An `Other` free-text option is provided automatically.
+- Returns `User has answered your questions: "q"="a", ... . You can now continue with the user's answers in mind.`

package/src/opencode/bash.ts

@@ -1,14 +1,17 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 
-import { bwrapRuntime } from "../bwrap/runtime.js";
+import { createBwrapRuntime } from "../bwrap/runtime.js";
 import { resolveWorkdir } from "../lib/path.js";
 
 const DEFAULT_TIMEOUT_MS = 120_000;
 const MAX_TIMEOUT_MS = 600_000;
 
 export default function opencodeBash(pi: ExtensionAPI): void {
-  bwrapRuntime.setup(pi);
+  // 每个扩展实例持有自己的 runtime：不依赖模块级全局状态，状态随扩展
+  // 实例生命周期（进程启动 / /reload / session 切换时工厂重建即重置）。
+  const runtime = createBwrapRuntime();
+  runtime.setup(pi);
   pi.registerTool({
     name: "bash",
     label: "bash",
@@ -52,7 +55,7 @@ export default function opencodeBash(pi: ExtensionAPI): void {
       const cwd = params.workdir ? await resolveWorkdir(params.workdir, ctx.cwd) : ctx.cwd;
 
       try {
-        return await bwrapRuntime.execute({
+        return await runtime.execute({
           ctx: { ...ctx, cwd },
           toolCallId: id,
           command: params.command,

package/src/spawn-agent.ts

@@ -54,9 +54,9 @@ const MAX_PROGRESS_LINES = 5;
  * built-in tool, the matching opencode extension is loaded via `-e` so the
  * subagent uses the enhanced implementation instead of the built-in one.
  *
- * The bash override also carries the bwrap sandbox: opencode/bash.ts calls
- * bwrapRuntime.setup() and runs commands through bwrapRuntime.execute(), so
- * agents that declare the bash tool get sandboxing automatically. Agents
+ * The bash override also carries the bwrap sandbox: opencode/bash.ts creates
+ * its own bwrap runtime instance and runs commands through runtime.execute(),
+ * so agents that declare the bash tool get sandboxing automatically. Agents
  * without bash need no bwrap setup (there are no commands to sandbox).
  * (Workspace write protection is embedded in the opencode write/edit tools.)
  *