@trim21/personal-pi-extensions 0.0.216 → 0.0.217

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trim21/personal-pi-extensions",
-  "version": "0.0.216",
+  "version": "0.0.217",
   "type": "module",
   "description": "Custom pi coding-agent extensions: bwrap sandbox, workspace guard, opencode edit, and more",
   "keywords": [
@@ -22,6 +22,7 @@
     "lint": "eslint .",
     "format": "prettier --write .",
     "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
     "prepare": "husky"
   },
   "peerDependencies": {
@@ -35,6 +36,7 @@
     "@earendil-works/pi-coding-agent": "^0.84.1",
     "@eslint/js": "10.0.1",
     "@types/node": "^24.13.3",
+    "@vitest/coverage-v8": "^4.1.10",
     "eslint": "^10.8.1",
     "eslint-config-prettier": "10.1.8",
     "eslint-plugin-erasable-syntax-only": "0.4.2",
@@ -56,13 +58,10 @@
       "src/session-name.ts",
       "src/bwrap/index.ts",
       "src/workspace-guard.ts",
-      "src/opencode-edit.ts",
-      "src/opencode-read.ts",
-      "src/opencode-write.ts",
+      "src/opencode/index.ts",
       "src/bash-default-timeout.ts",
       "src/gh-readonly.ts",
       "src/spawn-agent.ts",
-      "src/opencode-todo.ts",
       "src/question.ts",
       "src/talk/index.ts"
     ],

package/src/claude-code/common.ts

@@ -0,0 +1,29 @@
+import { isAbsolute, normalize } from "node:path";
+
+export interface FileSnapshot {
+  digest: string;
+  textEditable: boolean;
+}
+
+export interface ClaudeCodeState {
+  readonly reads: Map<string, FileSnapshot>;
+}
+
+export function createClaudeCodeState(): ClaudeCodeState {
+  return { reads: new Map() };
+}
+
+export function requireAbsolutePath(filePath: string, parameter = "file_path"): string {
+  if (!isAbsolute(filePath)) {
+    throw new Error(`The ${parameter} parameter must be an absolute path, not a relative path.`);
+  }
+  return normalize(filePath);
+}
+
+export function throwIfAborted(signal: AbortSignal | undefined): void {
+  if (signal?.aborted) throw new Error("Operation aborted");
+}
+
+export function snapshotsEqual(left: FileSnapshot, right: FileSnapshot): boolean {
+  return left.digest === right.digest;
+}

package/src/claude-code/files.ts

@@ -0,0 +1,320 @@
+import { createHash } from "node:crypto";
+import { constants } from "node:fs";
+import { access, mkdir, readFile, stat, writeFile } from "node:fs/promises";
+import { dirname, extname } from "node:path";
+
+import type { ImageContent, TextContent } from "@earendil-works/pi-ai";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import {
+  generateDiffString,
+  generateUnifiedPatch,
+  withFileMutationQueue,
+} from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+
+import {
+  type ClaudeCodeState,
+  type FileSnapshot,
+  requireAbsolutePath,
+  snapshotsEqual,
+  throwIfAborted,
+} from "./common.js";
+
+const DEFAULT_READ_LINES = 2000;
+const SAMPLE_BYTES = 4096;
+const IMAGE_MIMES = new Map<string, string>([
+  [".gif", "image/gif"],
+  [".jpeg", "image/jpeg"],
+  [".jpg", "image/jpeg"],
+  [".png", "image/png"],
+  [".webp", "image/webp"],
+]);
+
+export interface FileToolDetails {
+  diff?: string;
+  patch?: string;
+  firstChangedLine?: number;
+}
+
+function snapshotOf(content: Uint8Array | string, textEditable = true): FileSnapshot {
+  return { digest: createHash("sha256").update(content).digest("hex"), textEditable };
+}
+
+async function assertReadableFile(filePath: string): Promise<Awaited<ReturnType<typeof stat>>> {
+  const value = await stat(filePath);
+  if (!value.isFile()) throw new Error(`File not found: ${filePath}`);
+  await access(filePath, constants.R_OK);
+  return value;
+}
+
+function isBinary(sample: Uint8Array): boolean {
+  let suspicious = 0;
+  for (const byte of sample) {
+    if (byte === 0) return true;
+    if (byte < 9 || (byte > 13 && byte < 32)) suspicious++;
+  }
+  return sample.length > 0 && suspicious / sample.length > 0.3;
+}
+
+function splitFileLines(content: string): string[] {
+  if (content === "") return [];
+  const lines = content.split("\n");
+  if (content.endsWith("\n")) lines.pop();
+  return lines;
+}
+
+export function formatReadOutput(
+  content: string,
+  offset = 1,
+  limit = DEFAULT_READ_LINES,
+): { text: string; complete: boolean; 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,
+      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,
+      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 };
+}
+
+function countMatches(content: string, needle: string): number {
+  if (needle === "") return 0;
+  let count = 0;
+  let index = 0;
+  while ((index = content.indexOf(needle, index)) !== -1) {
+    count++;
+    index += needle.length;
+  }
+  return count;
+}
+
+export function exactReplace(
+  content: string,
+  oldString: string,
+  newString: string,
+  replaceAll = false,
+): string {
+  if (oldString === newString)
+    throw new Error("No changes to apply: old_string and new_string are identical.");
+  if (oldString === "") throw new Error("old_string must not be empty.");
+  const matches = countMatches(content, oldString);
+  if (matches === 0) throw new Error("String to replace not found in file.");
+  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, provide more context to make old_string unique.`,
+    );
+  }
+  if (replaceAll) return content.split(oldString).join(newString);
+  const index = content.indexOf(oldString);
+  return content.slice(0, index) + newString + content.slice(index + oldString.length);
+}
+
+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.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}`);
+  }
+}
+
+export function registerFileTools(pi: ExtensionAPI, state: ClaudeCodeState): void {
+  pi.registerTool({
+    name: "Read",
+    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.",
+      "Results use cat -n style line numbers starting at 1. Images are returned visually.",
+      "This tool reads files, not directories.",
+    ].join("\n"),
+    parameters: Type.Object(
+      {
+        file_path: Type.String({ description: "The absolute path to the file to read" }),
+        offset: Type.Optional(
+          Type.Number({ description: "The line number to start reading from" }),
+        ),
+        limit: Type.Optional(Type.Number({ description: "The number of lines to read" })),
+        pages: Type.Optional(
+          Type.String({ description: 'Page range for PDF files (for example "1-5" or "3")' }),
+        ),
+      },
+      { additionalProperties: false },
+    ),
+    async execute(_id, params, signal) {
+      throwIfAborted(signal);
+      const filePath = requireAbsolutePath(params.file_path);
+      if (
+        params.offset !== undefined &&
+        (!Number.isSafeInteger(params.offset) || params.offset < 1)
+      ) {
+        throw new Error("offset must be a positive integer");
+      }
+      if (params.limit !== undefined && (!Number.isSafeInteger(params.limit) || params.limit < 1)) {
+        throw new Error("limit must be a positive integer");
+      }
+      await assertReadableFile(filePath);
+      throwIfAborted(signal);
+
+      const extension = extname(filePath).toLowerCase();
+      if (extension === ".pdf") {
+        throw new Error(
+          "PDF page rendering is not supported by this pi tool host. Use an external PDF extraction tool before calling Read.",
+        );
+      }
+      const imageMime = IMAGE_MIMES.get(extension);
+      if (imageMime) {
+        const image = await readFile(filePath);
+        const data = image.toString("base64");
+        const content: (TextContent | ImageContent)[] = [
+          { type: "text", text: `Read image file [${imageMime}]` },
+          { type: "image", data, mimeType: imageMime },
+        ];
+        state.reads.set(filePath, snapshotOf(image, false));
+        return { content, details: undefined };
+      }
+
+      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,
+      );
+      state.reads.set(filePath, snapshotOf(buffer));
+      return { content: [{ type: "text", text: formatted.text }], details: undefined };
+    },
+  });
+
+  pi.registerTool({
+    name: "Edit",
+    label: "Edit",
+    description: [
+      "Performs exact string replacements in files.",
+      "You must use Read on the file before editing it.",
+      "old_string must match exactly and must be unique unless replace_all is true.",
+      "This tool does not use regular expressions or fuzzy matching.",
+    ].join("\n"),
+    parameters: Type.Object(
+      {
+        file_path: Type.String({ description: "The absolute path to the file to modify" }),
+        old_string: Type.String({ description: "The text to replace" }),
+        new_string: Type.String({ description: "The text to replace it with" }),
+        replace_all: Type.Optional(
+          Type.Boolean({ description: "Replace all occurrences of old_string", default: false }),
+        ),
+      },
+      { additionalProperties: false },
+    ),
+    async execute(_id, params, signal) {
+      throwIfAborted(signal);
+      const filePath = requireAbsolutePath(params.file_path);
+      return withFileMutationQueue(filePath, async () => {
+        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");
+        state.reads.set(filePath, snapshotOf(updated));
+        const diff = generateDiffString(original, updated);
+        return {
+          content: [{ type: "text", text: `The file ${filePath} has been updated successfully.` }],
+          details: {
+            diff: diff.diff,
+            patch: generateUnifiedPatch(filePath, original, updated),
+            firstChangedLine: diff.firstChangedLine,
+          } satisfies FileToolDetails,
+        };
+      });
+    },
+  });
+
+  pi.registerTool({
+    name: "Write",
+    label: "Write",
+    description: [
+      "Writes a file to the local filesystem.",
+      "This tool overwrites an existing file with the full content provided.",
+      "If the file exists, you must use Read first. Prefer Edit for partial changes.",
+    ].join("\n"),
+    parameters: Type.Object(
+      {
+        file_path: Type.String({
+          description: "The absolute path to the file to write (must be absolute, not relative)",
+        }),
+        content: Type.String({ description: "The content to write to the file" }),
+      },
+      { additionalProperties: false },
+    ),
+    async execute(_id, params, signal) {
+      throwIfAborted(signal);
+      const filePath = requireAbsolutePath(params.file_path);
+      return withFileMutationQueue(filePath, async () => {
+        let original: string | undefined;
+        try {
+          const value = await stat(filePath);
+          if (value.isFile()) {
+            await requireCurrentRead(state, filePath);
+            original = await readFile(filePath, "utf8");
+          }
+        } catch (error) {
+          if (!(error instanceof Error && "code" in error && error.code === "ENOENT")) throw error;
+        }
+        throwIfAborted(signal);
+        await mkdir(dirname(filePath), { recursive: true });
+        await writeFile(filePath, params.content, "utf8");
+        state.reads.set(filePath, snapshotOf(params.content));
+        const diff = generateDiffString(original ?? "", params.content);
+        return {
+          content: [{ type: "text", text: `File created successfully at: ${filePath}` }],
+          details: {
+            diff: diff.diff,
+            patch: generateUnifiedPatch(filePath, original ?? "", params.content),
+            firstChangedLine: diff.firstChangedLine,
+          } satisfies FileToolDetails,
+        };
+      });
+    },
+  });
+}

package/src/claude-code/index.ts

@@ -0,0 +1,15 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+import { createClaudeCodeState } from "./common.js";
+import { registerFileTools } from "./files.js";
+import { registerSearchTools } from "./search.js";
+import { registerSessionTools } from "./session-tools.js";
+import { registerShellTools } from "./shell.js";
+
+export default function claudeCodeTools(pi: ExtensionAPI): void {
+  const state = createClaudeCodeState();
+  registerFileTools(pi, state);
+  registerSearchTools(pi);
+  registerShellTools(pi);
+  registerSessionTools(pi);
+}

package/src/claude-code/search.ts

@@ -0,0 +1,218 @@
+import { glob as fsGlob, stat } from "node:fs/promises";
+import { isAbsolute, resolve } from "node:path";
+
+import { StringEnum } from "@earendil-works/pi-ai";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+
+import { throwIfAborted } from "./common.js";
+
+const GLOB_RESULT_LIMIT = 100;
+const GREP_OUTPUT_MODES = ["content", "files_with_matches", "count"] as const;
+
+type GrepOutputMode = (typeof GREP_OUTPUT_MODES)[number];
+
+function searchRoot(path: string | undefined, cwd: string): string {
+  if (!path) return cwd;
+  return isAbsolute(path) ? path : resolve(cwd, path);
+}
+
+function truncateOutput(output: string, maxCharacters = 30_000): string {
+  if (output.length <= maxCharacters) return output;
+  return `${output.slice(0, maxCharacters)}\n\n[Output truncated at ${maxCharacters} characters]`;
+}
+
+export async function globFiles(
+  pattern: string,
+  cwd: string,
+  signal?: AbortSignal,
+): Promise<string[]> {
+  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.
+    }
+  }
+  return matches
+    .toSorted((left, right) => right.mtimeMs - left.mtimeMs || left.path.localeCompare(right.path))
+    .slice(0, GLOB_RESULT_LIMIT)
+    .map((match) => match.path);
+}
+
+interface GrepParameters {
+  pattern: string;
+  path?: string;
+  glob?: string;
+  output_mode?: GrepOutputMode;
+  "-B"?: number;
+  "-A"?: number;
+  "-C"?: number;
+  context?: number;
+  "-n"?: boolean;
+  "-i"?: boolean;
+  type?: string;
+  head_limit?: number;
+  offset?: number;
+  multiline?: boolean;
+}
+
+export function buildGrepArguments(params: GrepParameters, cwd: string): string[] {
+  const mode = params.output_mode ?? "files_with_matches";
+  const args = ["--color=never"];
+  switch (mode) {
+    case "files_with_matches": {
+      args.push("--files-with-matches");
+      break;
+    }
+    case "count": {
+      args.push("--count-matches");
+      break;
+    }
+    case "content": {
+      args.push("--no-heading", "--with-filename");
+      if (params["-n"] !== false) args.push("--line-number");
+      const before = params["-B"];
+      const after = params["-A"];
+      const around = params.context ?? params["-C"];
+      if (around === undefined) {
+        if (before !== undefined) args.push("--before-context", String(before));
+        if (after !== undefined) args.push("--after-context", String(after));
+      } else args.push("--context", String(around));
+
+      break;
+    }
+    // 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));
+  return args;
+}
+
+export function pageGrepOutput(output: string, offset = 0, headLimit = 0): string {
+  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"));
+}
+
+export function registerSearchTools(pi: ExtensionAPI): void {
+  pi.registerTool({
+    name: "Glob",
+    label: "Glob",
+    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.",
+    ].join("\n"),
+    parameters: Type.Object(
+      {
+        pattern: Type.String({ description: "The glob pattern to match files against" }),
+        path: Type.Optional(
+          Type.String({
+            description:
+              "The directory to search in. If omitted, the current working directory is used.",
+          }),
+        ),
+      },
+      { additionalProperties: false },
+    ),
+    async execute(_id, params, signal, _onUpdate, ctx) {
+      const root = searchRoot(params.path, ctx.cwd);
+      const matches = await globFiles(params.pattern, root, signal);
+      return {
+        content: [
+          { type: "text", text: matches.length > 0 ? matches.join("\n") : "No files found" },
+        ],
+        details: { count: matches.length },
+      };
+    },
+  });
+
+  pi.registerTool({
+    name: "Grep",
+    label: "Grep",
+    description: [
+      "A powerful search tool built on ripgrep.",
+      "Supports regular expressions, file globs, file types, multiline matching, context lines, and paginated output.",
+      'output_mode defaults to "files_with_matches"; use "content" for matching lines or "count" for match counts.',
+    ].join("\n"),
+    parameters: Type.Object(
+      {
+        pattern: Type.String({ description: "The regular expression pattern to search for" }),
+        path: Type.Optional(
+          Type.String({
+            description: "File or directory to search. Defaults to the current directory.",
+          }),
+        ),
+        glob: Type.Optional(
+          Type.String({ description: 'Glob filter such as "*.js" or "*.{ts,tsx}"' }),
+        ),
+        output_mode: Type.Optional(
+          StringEnum(GREP_OUTPUT_MODES, {
+            description: "Output mode. Defaults to files_with_matches.",
+          }),
+        ),
+        "-B": Type.Optional(
+          Type.Number({ description: "Lines to show before each match in content mode" }),
+        ),
+        "-A": Type.Optional(
+          Type.Number({ description: "Lines to show after each match in content mode" }),
+        ),
+        "-C": Type.Optional(
+          Type.Number({ description: "Lines to show before and after each match" }),
+        ),
+        context: Type.Optional(
+          Type.Number({ description: "Lines to show before and after each match" }),
+        ),
+        "-n": Type.Optional(
+          Type.Boolean({ description: "Show line numbers in content mode; defaults true" }),
+        ),
+        "-i": Type.Optional(Type.Boolean({ description: "Case-insensitive search" })),
+        type: Type.Optional(
+          Type.String({ description: "ripgrep file type such as js, py, rust, or go" }),
+        ),
+        head_limit: Type.Optional(
+          Type.Number({ description: "Limit output to the first N entries after offset" }),
+        ),
+        offset: Type.Optional(Type.Number({ description: "Skip the first N output entries" })),
+        multiline: Type.Optional(
+          Type.Boolean({ description: "Allow patterns to span multiple lines" }),
+        ),
+      },
+      { additionalProperties: false },
+    ),
+    async execute(_id, params, signal, _onUpdate, ctx) {
+      if (
+        params.offset !== undefined &&
+        (!Number.isSafeInteger(params.offset) || params.offset < 0)
+      ) {
+        throw new Error("offset must be a non-negative integer");
+      }
+      if (
+        params.head_limit !== undefined &&
+        (!Number.isSafeInteger(params.head_limit) || params.head_limit < 0)
+      ) {
+        throw new Error("head_limit must be a non-negative integer");
+      }
+      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 text = pageGrepOutput(result.stdout, params.offset ?? 0, params.head_limit ?? 0);
+      return { content: [{ type: "text", text }], details: undefined };
+    },
+  });
+}

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

@@ -0,0 +1,201 @@
+import { StringEnum } from "@earendil-works/pi-ai";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+
+const TODO_STATUSES = ["pending", "in_progress", "completed"] as const;
+const OTHER_OPTION = "Other";
+const DONE_OPTION = "Done";
+
+type TodoStatus = (typeof TODO_STATUSES)[number];
+
+export interface ClaudeCodeTodo {
+  content: string;
+  status: TodoStatus;
+  activeForm: string;
+}
+
+interface QuestionOption {
+  label: string;
+  description: string;
+}
+
+interface QuestionInput {
+  question: string;
+  header: string;
+  options: QuestionOption[];
+  multiSelect: boolean;
+}
+
+function formatTodos(todos: readonly ClaudeCodeTodo[]): string[] | undefined {
+  if (todos.length === 0) return undefined;
+  const markers: Record<TodoStatus, string> = {
+    pending: " ",
+    in_progress: ">",
+    completed: "x",
+  };
+  return todos.map((todo) => {
+    const text = todo.status === "in_progress" ? todo.activeForm : todo.content;
+    return `- [${markers[todo.status]}] ${text}`;
+  });
+}
+
+async function askSingle(
+  question: QuestionInput,
+  ctx: ExtensionContext,
+  signal: AbortSignal | undefined,
+): Promise<string> {
+  const title = `${question.header}: ${question.question}`;
+  const selected = await ctx.ui.select(
+    title,
+    [...question.options.map((option) => option.label), OTHER_OPTION],
+    { signal },
+  );
+  if (selected === undefined) return "Unanswered";
+  if (selected !== OTHER_OPTION) return selected;
+  const answer = await ctx.ui.input(title, "Type your answer", { signal });
+  return answer?.trim() || "Unanswered";
+}
+
+async function askMultiple(
+  question: QuestionInput,
+  ctx: ExtensionContext,
+  signal: AbortSignal | undefined,
+): Promise<string> {
+  const title = `${question.header}: ${question.question}`;
+  const remaining = new Set(question.options.map((option) => option.label));
+  const selected: string[] = [];
+  while (remaining.size > 0) {
+    const choice = await ctx.ui.select(title, [...remaining, OTHER_OPTION, DONE_OPTION], {
+      signal,
+    });
+    if (choice === undefined || choice === DONE_OPTION) break;
+    if (choice === OTHER_OPTION) {
+      const answer = await ctx.ui.input(title, "Type your answer", { signal });
+      if (answer?.trim()) selected.push(answer.trim());
+      break;
+    }
+    if (remaining.delete(choice)) selected.push(choice);
+  }
+  return selected.length > 0 ? selected.join(", ") : "Unanswered";
+}
+
+export function registerSessionTools(pi: ExtensionAPI): void {
+  const todoSchema = Type.Object(
+    {
+      todos: Type.Array(
+        Type.Object(
+          {
+            content: Type.String({ minLength: 1 }),
+            status: StringEnum(TODO_STATUSES),
+            activeForm: Type.String({ minLength: 1 }),
+          },
+          { additionalProperties: false },
+        ),
+        { description: "The updated todo list" },
+      ),
+    },
+    { additionalProperties: false },
+  );
+
+  pi.registerTool({
+    name: "TodoWrite",
+    label: "Todo Write",
+    description: [
+      "Use this tool to create and manage a structured task list for the current coding session.",
+      "Pass the complete updated todo list on every call.",
+      "Keep exactly one task in_progress while work remains and mark tasks completed immediately after finishing them.",
+      "Each task needs an imperative content form and a present-continuous activeForm.",
+    ].join("\n"),
+    parameters: todoSchema,
+    execute(_id, params, _signal, _onUpdate, ctx) {
+      const todos = params.todos.map((todo) => ({
+        content: todo.content.trim(),
+        status: todo.status,
+        activeForm: todo.activeForm.trim(),
+      }));
+      if (todos.some((todo) => todo.content === "" || todo.activeForm === "")) {
+        throw new Error("Todo content and activeForm must not be blank.");
+      }
+      const inProgress = todos.filter((todo) => todo.status === "in_progress");
+      if (inProgress.length > 1) throw new Error("Only one todo may be in_progress at a time.");
+      ctx.ui.setWidget("claude-code-todos", formatTodos(todos));
+      return Promise.resolve({
+        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.",
+          },
+        ],
+        details: { todos },
+      });
+    },
+  });
+
+  const optionSchema = Type.Object(
+    {
+      label: Type.String({ description: "Concise display text for the option" }),
+      description: Type.String({ description: "Explanation of the option" }),
+    },
+    { additionalProperties: false },
+  );
+  const questionSchema = Type.Object(
+    {
+      question: Type.String({ description: "The complete question to ask" }),
+      header: Type.String({ description: "Very short label displayed with the question" }),
+      options: Type.Array(optionSchema, {
+        minItems: 2,
+        maxItems: 4,
+        description: "The available choices; do not include an Other option",
+      }),
+      multiSelect: Type.Boolean({
+        default: false,
+        description: "Allow the user to select multiple options",
+      }),
+    },
+    { additionalProperties: false },
+  );
+
+  pi.registerTool({
+    name: "AskUserQuestion",
+    label: "Ask User Question",
+    description: [
+      "Ask the user questions during execution to gather preferences, clarify requirements, or choose an implementation direction.",
+      "Users can always provide their own answer through the automatically supplied Other option.",
+      "Use multiSelect for questions where multiple choices may apply.",
+      'If you recommend an option, put it first and append "(Recommended)" to its label.',
+    ].join("\n"),
+    parameters: Type.Object(
+      {
+        questions: Type.Array(questionSchema, {
+          minItems: 1,
+          maxItems: 4,
+          description: "Questions to ask the user",
+        }),
+      },
+      { additionalProperties: false },
+    ),
+    executionMode: "sequential",
+    async execute(_id, params, signal, _onUpdate, ctx) {
+      if (!ctx.hasUI) throw new Error("Cannot ask questions: interactive UI is not available");
+      const answers: Record<string, string> = {};
+      for (const question of params.questions) {
+        if (signal?.aborted) throw new Error("Operation aborted");
+        answers[question.question] = question.multiSelect
+          ? await askMultiple(question, ctx, signal)
+          : await askSingle(question, ctx, signal);
+      }
+      const formatted = Object.entries(answers)
+        .map(([question, answer]) => `"${question}"="${answer}"`)
+        .join(", ");
+      return {
+        content: [
+          {
+            type: "text",
+            text: `User has answered your questions: ${formatted}. You can now continue with the user's answers in mind.`,
+          },
+        ],
+        details: { questions: params.questions, answers },
+      };
+    },
+  });
+}

package/src/claude-code/shell.ts

@@ -0,0 +1,97 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { createBashTool } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+
+const DEFAULT_TIMEOUT_MS = 120_000;
+const MAX_TIMEOUT_MS = 600_000;
+
+interface MarkerResult {
+  text: string;
+  cwd: string | undefined;
+}
+
+function stripCwdMarker(text: string, marker: string): MarkerResult {
+  const match = new RegExp(String.raw`${marker}([^\n]+)${marker}`).exec(text);
+  if (!match) return { text, cwd: undefined };
+  return { text: text.replace(match[0], "").trimEnd(), cwd: match[1] };
+}
+
+function wrapCommand(command: string, marker: string): string {
+  return [
+    command,
+    "__pi_cc_status=$?",
+    "wait",
+    String.raw`printf '\n${marker}%s${marker}\n' "$PWD"`,
+    "exit $__pi_cc_status",
+  ].join("\n");
+}
+
+export function registerShellTools(pi: ExtensionAPI): void {
+  let persistentCwd: string | undefined;
+
+  pi.registerTool({
+    name: "Bash",
+    label: "Bash",
+    description: [
+      "Executes a given bash command synchronously and returns its output.",
+      "The working directory persists between commands, but shell state does not.",
+      "timeout is in milliseconds, defaults to 120000, and may not exceed 600000.",
+      "Every command runs in the foreground. Background command execution is not supported; shell jobs are waited for before the tool returns.",
+    ].join("\n"),
+    parameters: Type.Object(
+      {
+        command: Type.String({ description: "The command to execute" }),
+        timeout: Type.Optional(
+          Type.Number({ description: "Optional timeout in milliseconds (max 600000)" }),
+        ),
+        description: Type.Optional(
+          Type.String({ description: "Clear, concise description of the command" }),
+        ),
+      },
+      { additionalProperties: false },
+    ),
+    async execute(id, params, signal, onUpdate, ctx) {
+      const timeout = params.timeout ?? DEFAULT_TIMEOUT_MS;
+      if (!Number.isFinite(timeout) || timeout <= 0 || timeout > MAX_TIMEOUT_MS) {
+        throw new Error(`timeout must be between 1 and ${MAX_TIMEOUT_MS} milliseconds`);
+      }
+
+      const marker = `__PI_CC_CWD_${id.replaceAll("-", "_")}_${Date.now()}__`;
+      const bash = createBashTool(persistentCwd ?? ctx.cwd);
+      try {
+        const result = await bash.execute(
+          id,
+          { command: wrapCommand(params.command, marker), timeout: timeout / 1000 },
+          signal,
+          onUpdate
+            ? (update) => {
+                const content = update.content.map((item) => {
+                  if (item.type !== "text") return item;
+                  return { ...item, text: stripCwdMarker(item.text, marker).text };
+                });
+                onUpdate({ ...update, content });
+              }
+            : undefined,
+        );
+        const content = result.content.map((item) => {
+          if (item.type !== "text") return item;
+          const cleaned = stripCwdMarker(item.text, marker);
+          if (cleaned.cwd) persistentCwd = cleaned.cwd;
+          return { ...item, text: cleaned.text || "(no output)" };
+        });
+        return { ...result, content };
+      } catch (error) {
+        if (!(error instanceof Error)) throw error;
+        const cleaned = stripCwdMarker(error.message, marker);
+        if (cleaned.cwd) persistentCwd = cleaned.cwd;
+        const timeoutMatch = /Command timed out after [\d.]+ seconds/.exec(cleaned.text);
+        const message = timeoutMatch
+          ? cleaned.text.slice(0, timeoutMatch.index) +
+            `Command timed out after ${timeout} milliseconds` +
+            cleaned.text.slice(timeoutMatch.index + timeoutMatch[0].length)
+          : cleaned.text;
+        throw new Error(message, { cause: error });
+      }
+    },
+  });
+}

package/src/{opencode-edit.ts → opencode/edit.ts}

@@ -10,7 +10,7 @@
  * Known gaps (intentionally not implemented): LSP diagnostics in the result,
  * formatter run.
  *
- * The matching engine (replacers + replace()) lives in opencode-edit-engine.ts
+ * The matching engine (replacers + replace()) lives in opencode/edit-engine.ts
  * and is also used by workspace-guard for the diff preview.
  *
  * Usage:
@@ -35,7 +35,7 @@ import {
   replace,
   restoreLineEndings,
   stripBom,
-} from "./opencode-edit-engine.js";
+} from "./edit-engine.js";
 
 // ── schema ────────────────────────────────────────────────────────────────────
 

package/src/opencode/index.ts

@@ -0,0 +1,40 @@
+/**
+ * opencode —— 统一注册 opencode 风格工具扩展。
+ *
+ * 聚合 read / edit / write / todo 四个工具，一次加载全部注册；
+ * 各工具的公开 API（匹配引擎、纯函数等）也从这里重新导出，方便
+ * 测试与其他模块（如 workspace-guard）引用。
+ *
+ * Usage:
+ *   pi -e ./opencode/index.ts
+ *
+ * spawn-agent 的子代理按声明工具单独加载 `opencode/{read,edit,write}.ts`，
+ * 避免把未声明的工具注入子代理工具集。
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+import opencodeEdit from "./edit.js";
+import opencodeRead from "./read.js";
+import opencodeTodo from "./todo.js";
+import opencodeWrite from "./write.js";
+
+export { default as opencodeEdit } from "./edit.js";
+export {
+  detectLineEnding,
+  normalizeForEdit,
+  normalizeToLF,
+  replace,
+  restoreLineEndings,
+  stripBom,
+} from "./edit-engine.js";
+export { default as opencodeRead, truncateHead, type TruncationResult } from "./read.js";
+export { default as opencodeTodo } from "./todo.js";
+export { default as opencodeWrite, resolveBom } from "./write.js";
+
+export default function opencode(pi: ExtensionAPI) {
+  opencodeRead(pi);
+  opencodeEdit(pi);
+  opencodeWrite(pi);
+  opencodeTodo(pi);
+}

package/src/{opencode-todo.ts → opencode/todo.ts}

@@ -26,7 +26,7 @@ import { StringEnum } from "@earendil-works/pi-ai";
 import { type ExtensionAPI, truncateToVisualLines } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 
-import { type ToolPendant } from "./lib/pendant.js";
+import { type ToolPendant } from "../lib/pendant.js";
 
 // ── constants ────────────────────────────────────────────────────────────────
 

package/src/{opencode-write.ts → opencode/write.ts}

@@ -28,7 +28,7 @@ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { withFileMutationQueue } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 
-import { stripBom } from "./opencode-edit-engine.js";
+import { stripBom } from "./edit-engine.js";
 
 /**
  * opencode: desiredBom = source.bom || next.bom —— 优先保留原文件 BOM，

package/src/session-name.ts

@@ -33,8 +33,6 @@ import {
 } from "@earendil-works/pi-ai";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 
-import { jsoncToJson } from "./lib/jsonc.js";
-
 // ── constants ────────────────────────────────────────────────────────────────
 
 /** ~/.pi/agent/settings.json：sessionName 配置所在文件 */
@@ -98,8 +96,7 @@ export interface UserMessageLike {
 /**
  * 读取 ~/.pi/agent/settings.json 的 sessionName 配置。
  * provider 缺省时回退到 defaultProvider；文件缺失 / JSON 损坏 / 无 sessionName
- * 时返回 undefined。支持 jsonc（注释/尾逗号），与 pi 文档的 settings.json
- * 示例一致。
+ * 时返回 undefined。
  */
 export function loadSessionNameConfig(settingsPath = SETTINGS_PATH): SessionNameConfig | undefined {
   let raw: string;
@@ -109,7 +106,7 @@ export function loadSessionNameConfig(settingsPath = SETTINGS_PATH): SessionName
     return undefined;
   }
   try {
-    const parsed: unknown = JSON.parse(jsoncToJson(raw));
+    const parsed: unknown = JSON.parse(raw);
     if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return undefined;
     const settings = parsed as Record<string, unknown>;
     const sn = settings.sessionName;

package/src/spawn-agent.ts

@@ -62,9 +62,9 @@ const UNCONDITIONAL_EXTENSIONS = ["workspace-guard.ts", "bwrap/index.ts"] as con
  * subagent uses the enhanced implementation instead of the built-in one.
  */
 const TOOL_EXTENSION_OVERRIDES: Record<string, string> = {
-  read: "opencode-read.ts",
-  edit: "opencode-edit.ts",
-  write: "opencode-write.ts",
+  read: "opencode/read.ts",
+  edit: "opencode/edit.ts",
+  write: "opencode/write.ts",
 };
 
 // ── schema ───────────────────────────────────────────────────────────────────

package/src/workspace-guard.ts

@@ -22,7 +22,7 @@ import {
 } from "@earendil-works/pi-coding-agent";
 
 import { resolveHomePath } from "./lib/path.js";
-import { normalizeForEdit, replace } from "./opencode-edit-engine.js";
+import { normalizeForEdit, replace } from "./opencode/edit-engine.js";
 
 const WRITE_TOOLS = new Set(["write", "edit"]);
 const ALWAYS_ALLOW = ["/tmp"];

package/src/lib/jsonc.ts

@@ -1,67 +0,0 @@
-/**
- * Minimal JSONC → JSON conversion for small user-edited config files.
- *
- * Strips line and block comments and trailing commas outside of string
- * literals, so a stray comment in a config file does not silently void the
- * whole file (the way a plain `JSON.parse` would).
- */
-
-export function jsoncToJson(raw: string): string {
-  let out = "";
-  let inString = false;
-  let i = 0;
-  while (i < raw.length) {
-    const c = raw[i];
-    if (inString) {
-      out += c;
-      if (c === "\\" && i + 1 < raw.length) {
-        out += raw[i + 1];
-        i += 2;
-        continue;
-      }
-      if (c === '"') inString = false;
-      i++;
-      continue;
-    }
-    switch (c) {
-      case '"': {
-        inString = true;
-        out += c;
-        i++;
-        continue;
-      }
-      case "/": {
-        if (raw[i + 1] === "/") {
-          while (i < raw.length && raw[i] !== "\n") i++;
-          continue;
-        }
-        if (raw[i + 1] === "*") {
-          i += 2;
-          while (i < raw.length && !(raw[i] === "*" && raw[i + 1] === "/")) i++;
-          i += 2;
-          continue;
-        }
-        out += c;
-        i++;
-        continue;
-      }
-      case ",": {
-        // Drop a trailing comma before } or ] (outside strings).
-        let j = i + 1;
-        while (j < raw.length && /\s/.test(raw[j])) j++;
-        if (raw[j] === "}" || raw[j] === "]") {
-          i++;
-          continue;
-        }
-        out += c;
-        i++;
-        continue;
-      }
-      default: {
-        out += c;
-        i++;
-      }
-    }
-  }
-  return out;
-}