@trim21/personal-pi-extensions 0.0.231 → 0.0.233

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trim21/personal-pi-extensions",
-  "version": "0.0.231",
+  "version": "0.0.233",
   "type": "module",
   "description": "Custom pi coding-agent extensions: bwrap sandbox, workspace guard, opencode edit, and more",
   "keywords": [
@@ -36,6 +36,7 @@
     "@earendil-works/pi-coding-agent": "^0.84.1",
     "@eslint/js": "10.0.1",
     "@types/node": "^24.13.3",
+    "@typescript/native": "npm:typescript@^7.0.2",
     "@vitest/coverage-v8": "^4.1.10",
     "eslint": "^10.8.1",
     "eslint-config-prettier": "10.1.8",
@@ -48,7 +49,7 @@
     "lint-staged": "^17.3.0",
     "prettier": "^3.9.6",
     "typebox": "1.3.1",
-    "typescript": "^6.0.3",
+    "typescript": "npm:@typescript/typescript6@^6.0.2",
     "typescript-eslint": "^8.67.0",
     "vitest": "^4.1.10"
   },

package/src/claude-code/bash.md

@@ -0,0 +1,31 @@
+# Bash tool
+
+Executes a given bash command and returns its output.
+
+The working directory persists between commands, but shell state does not. The shell environment is initialized from the user's profile (bash or zsh).
+
+Commands run in a sandbox: no write access outside the workspace and no network access. Use the `dangerouslyDisableSandbox` parameter to request unsandboxed execution; the user must approve this request.
+
+IMPORTANT: Avoid using this tool to run `find`, `grep`, `cat`, `head`, `tail`, `sed`, `awk`, or `echo` commands, unless explicitly instructed or after you have verified that a dedicated tool cannot accomplish your task. Instead, use the appropriate dedicated tool as this will provide a much better experience for the user:
+
+- File search: Use Glob (NOT find or ls)
+- Content search: Use Grep (NOT grep or rg)
+- Read files: Use Read (NOT cat/head/tail)
+- Edit files: Use Edit (NOT sed/awk)
+- Write files: Use Write (NOT echo >/cat <<EOF)
+- Communication: Output text directly (NOT echo/printf)
+  While the Bash tool can do similar things, it's better to use the built-in tools as they provide a better user experience and make it easier to review tool calls and give permission.
+
+- You may specify an optional timeout in milliseconds (up to 600000ms / 10 minutes). By default, your command will timeout after 120000ms (2 minutes).
+- When issuing multiple commands:
+- If the commands are independent and can run in parallel, make multiple Bash tool calls in a single message. Example: if you need to run "git status" and "git diff", send a single message with two Bash tool calls in parallel.
+- If the commands depend on each other and must run sequentially, use a single Bash call with '&&' to chain them together.
+- Use ';' only when you need to run commands sequentially but don't care if earlier commands fail.
+- DO NOT use newlines to separate commands (newlines are ok in quoted strings).
+- For git commands:
+- Prefer to create a new commit rather than amending an existing commit.
+- Before running destructive operations (e.g., git reset --hard, git push --force, git checkout --), consider whether there is a safer alternative that achieves the same goal. Only use destructive operations when they are truly the best approach.
+- Never skip hooks (--no-verify) or bypass signing (--no-gpg-sign, -c commit.gpgsign=false) unless the user has explicitly asked for it. If a hook fails, investigate and fix the underlying issue.
+- Avoid unnecessary `sleep` commands:
+- Do not sleep between commands that can run immediately — just run them.
+- Do not retry failing commands in a sleep loop — diagnose the root cause.

package/src/claude-code/edit.md

@@ -0,0 +1,12 @@
+# Edit tool
+
+Performs exact string replacements in files.
+
+Usage:
+
+- You must use your Read tool at least once in the conversation before editing. This tool will error if you attempt an edit without reading the file.
+- When editing text from Read tool output, ensure you preserve the exact indentation (tabs/spaces) as it appears AFTER the line number prefix. The line number prefix format is: line number + tab. Everything after that is the actual file content to match. Never include any part of the line number prefix in the old_string or new_string.
+- ALWAYS prefer editing existing files in the codebase. NEVER write new files unless explicitly required.
+- Only use emojis if the user explicitly requests it. Avoid adding emojis to files unless asked.
+- The edit will FAIL if old_string is not unique in the file. Either provide a larger string with more surrounding context to make it unique or use replace_all to change every instance of old_string.
+- Use replace_all for replacing and renaming strings across the file.

package/src/claude-code/files.ts

@@ -1,7 +1,8 @@
 import { createHash } from "node:crypto";
-import { constants } from "node:fs";
+import { constants, readFileSync } from "node:fs";
 import { access, mkdir, readFile, stat, writeFile } from "node:fs/promises";
 import { dirname, extname } from "node:path";
+import { fileURLToPath } from "node:url";
 
 import type { ImageContent, TextContent } from "@earendil-works/pi-ai";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
@@ -23,6 +24,14 @@ import {
 
 const DEFAULT_READ_LINES = 2000;
 const SAMPLE_BYTES = 4096;
+
+/** 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();
+const WRITE_PROMPT = readFileSync(
+  fileURLToPath(new URL("write.md", import.meta.url)),
+  "utf8",
+).trim();
 const IMAGE_MIMES = new Map<string, string>([
   [".gif", "image/gif"],
   [".jpeg", "image/jpeg"],
@@ -163,6 +172,8 @@ export function registerFileTools(pi: ExtensionAPI, state: ClaudeCodeState): voi
       "Results use cat -n style line numbers starting at 1. Images are returned visually.",
       "This tool reads files, not directories.",
     ].join("\n"),
+    promptSnippet: "Read files from the local filesystem with line numbers",
+    promptGuidelines: [READ_PROMPT],
     parameters: Type.Object(
       {
         file_path: Type.String({ description: "The absolute path to the file to read" }),
@@ -231,6 +242,8 @@ export function registerFileTools(pi: ExtensionAPI, state: ClaudeCodeState): voi
       "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"),
+    promptSnippet: "Make exact string replacements in files",
+    promptGuidelines: [EDIT_PROMPT],
     parameters: Type.Object(
       {
         file_path: Type.String({ description: "The absolute path to the file to modify" }),
@@ -288,6 +301,8 @@ export function registerFileTools(pi: ExtensionAPI, state: ClaudeCodeState): voi
       "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"),
+    promptSnippet: "Create or overwrite files",
+    promptGuidelines: [WRITE_PROMPT],
     parameters: Type.Object(
       {
         file_path: Type.String({

package/src/claude-code/glob.md

@@ -0,0 +1,6 @@
+# Glob tool
+
+- Fast file pattern matching tool that works with any codebase size
+- Supports glob patterns like `**/*.js` or `src/**/*.ts`
+- Returns matching file paths sorted by modification time
+- Use this tool when you need to find files by name patterns

package/src/claude-code/glob.ts

@@ -5,8 +5,10 @@
  * independently (declare `Glob` in the frontmatter to get only this tool).
  */
 
+import { readFileSync } from "node:fs";
 import { glob as fsGlob, stat } from "node:fs/promises";
 import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
@@ -15,6 +17,9 @@ import { searchRoot, throwIfAborted } from "./common.js";
 
 const GLOB_RESULT_LIMIT = 100;
 
+/** Tool guidance, kept in markdown so it reads like documentation. */
+const GLOB_PROMPT = readFileSync(fileURLToPath(new URL("glob.md", import.meta.url)), "utf8").trim();
+
 export async function globFiles(
   pattern: string,
   cwd: string,
@@ -47,6 +52,8 @@ export function registerGlobTool(pi: ExtensionAPI): void {
       'Supports glob patterns such as "**/*.js" and "src/**/*.ts".',
       "Returns matching file paths sorted by modification time.",
     ].join("\n"),
+    promptSnippet: "Find files by name patterns",
+    promptGuidelines: [GLOB_PROMPT],
     parameters: Type.Object(
       {
         pattern: Type.String({ description: "The glob pattern to match files against" }),

package/src/claude-code/grep.md

@@ -0,0 +1,10 @@
+# Grep tool
+
+A powerful search tool built on ripgrep.
+
+- ALWAYS use Grep for search tasks. NEVER invoke `grep` or `rg` as a Bash command. The Grep tool has been optimized for correct permissions and access.
+- Supports full regex syntax (e.g., "log.*Error", "function\s+\w+")
+- Filter files with glob parameter (e.g., `*.js`, `**/*.tsx`) or type parameter (e.g., "js", "py", "rust")
+- Output modes: "content" shows matching lines, "files_with_matches" shows only file paths (default), "count" shows match counts
+- Pattern syntax: Uses ripgrep (not grep) - literal braces need escaping (use `interface\{\}` to find `interface{}` in Go code)
+- Multiline matching: By default patterns match within single lines only. For cross-line patterns like `struct \{[\s\S]*?field`, use multiline: true

package/src/claude-code/grep.ts

@@ -9,7 +9,9 @@
  * lines capped at 500 columns, and an implicit head_limit of 250 entries.
  */
 
+import { readFileSync } from "node:fs";
 import { stat } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
 
 import { StringEnum } from "@earendil-works/pi-ai";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
@@ -21,6 +23,9 @@ const GREP_OUTPUT_MODES = ["content", "files_with_matches", "count"] as const;
 
 type GrepOutputMode = (typeof GREP_OUTPUT_MODES)[number];
 
+/** Tool guidance, kept in markdown so it reads like documentation. */
+const GREP_PROMPT = readFileSync(fileURLToPath(new URL("grep.md", import.meta.url)), "utf8").trim();
+
 /** Version control directories excluded from searches (noise in results). */
 const VCS_DIRECTORIES_TO_EXCLUDE = [".git", ".svn", ".hg", ".bzr", ".jj", ".sl"] as const;
 
@@ -145,6 +150,8 @@ export function registerGrepTool(pi: ExtensionAPI): void {
       "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"),
+    promptSnippet: "Search file contents with regular expressions",
+    promptGuidelines: [GREP_PROMPT],
     parameters: Type.Object(
       {
         pattern: Type.String({ description: "The regular expression pattern to search for" }),

package/src/claude-code/read.md

@@ -0,0 +1,13 @@
+# Read tool
+
+Reads a file from the local filesystem. You can access any file directly by using this tool.
+
+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
+- 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
+- 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

@@ -116,6 +116,7 @@ export function registerSessionTools(pi: ExtensionAPI): void {
       "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"),
+    promptSnippet: "Plan and track work with a task list",
     parameters: todoSchema,
     execute(_id, params, _signal, _onUpdate, ctx) {
       const todos = params.todos.map((todo) => ({
@@ -174,6 +175,12 @@ export function registerSessionTools(pi: ExtensionAPI): void {
       "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"),
+    promptSnippet: "Ask the user questions during execution",
+    promptGuidelines: [
+      "Use AskUserQuestion when you need to gather preferences, clarify requirements, or choose an implementation direction.",
+      "Users can always provide their own answer through the automatically supplied Other option.",
+      'If you recommend an option, put it first and append "(Recommended)" to its label.',
+    ],
     parameters: Type.Object(
       {
         questions: Type.Array(questionSchema, {

package/src/claude-code/shell.ts

@@ -1,3 +1,6 @@
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 
@@ -7,10 +10,14 @@ import { resolveWorkdir } from "../lib/path.js";
 const DEFAULT_TIMEOUT_MS = 120_000;
 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);
   pi.registerTool({
     name: "Bash",
+    promptGuidelines: [BASH_PROMPT],
     label: "Bash",
     description: [
       "Executes a given bash command synchronously and returns its output.",

package/src/claude-code/write.md

@@ -0,0 +1,11 @@
+# Write tool
+
+Writes a file to the local filesystem.
+
+Usage:
+
+- This tool will overwrite the existing file if there is one at the provided path.
+- If this is an existing file, you MUST use the Read tool first to read the file's contents. This tool will fail if you did not read the file first.
+- Prefer the Edit tool for modifying existing files — it only sends the diff. Only use this tool to create new files or for complete rewrites.
+- NEVER create documentation files (*.md) or README files unless explicitly requested by the User.
+- Only use emojis if the user explicitly requests it. Avoid writing emojis to files unless asked.

package/src/spawn-agent.ts

@@ -60,9 +60,11 @@ const MAX_PROGRESS_LINES = 5;
  * without bash need no bwrap setup (there are no commands to sandbox).
  * (Workspace write protection is embedded in the opencode write/edit tools.)
  *
- * Claude Code style tools (capitalized names, e.g. `Grep`/`Glob`) map to
- * their split claude-code files, so a subagent can enable exactly the search
- * tools it declares — e.g. `Grep` without `Glob`.
+ * Claude Code style tools (capitalized names) map to their claude-code
+ * files, so a subagent can enable exactly the tools it declares — e.g. `Grep`
+ * without `Glob`. The stateful file tools (`Read`/`Edit`/`Write`) share one
+ * implementation file (they share a read-snapshot state); the `--tools`
+ * allowlist still exposes only the declared subset.
  */
 const TOOL_EXTENSION_OVERRIDES: Record<string, string> = {
   read: "opencode/read.ts",
@@ -71,6 +73,9 @@ const TOOL_EXTENSION_OVERRIDES: Record<string, string> = {
   bash: "opencode/bash.ts",
   Grep: "claude-code/grep.ts",
   Glob: "claude-code/glob.ts",
+  Read: "claude-code/files.ts",
+  Edit: "claude-code/files.ts",
+  Write: "claude-code/files.ts",
 };
 
 // ── schema ───────────────────────────────────────────────────────────────────
@@ -205,10 +210,17 @@ export function buildSubagentArgs(
   const tools = agent.tools ?? DEFAULT_TOOLS;
   // Load the opencode override for each built-in tool the agent declares
   // (read/edit/write), so the subagent uses the enhanced implementation
-  // instead of the built-in one.
+  // instead of the built-in one. Several tool names can map to the same
+  // implementation file (e.g. cc Read/Edit/Write → claude-code/files.ts);
+  // loading a file twice would run its extension factory twice and create
+  // separate closure states, so each file is loaded at most once.
+  const loadedOverrideFiles = new Set<string>();
   for (const tool of tools) {
     const ext = TOOL_EXTENSION_OVERRIDES[tool];
-    if (ext) args.push("-e", extensionPath(ext));
+    if (ext && !loadedOverrideFiles.has(ext)) {
+      loadedOverrideFiles.add(ext);
+      args.push("-e", extensionPath(ext));
+    }
   }
   args.push("--tools", tools.join(","));
   if (systemPromptPath) args.push("--append-system-prompt", systemPromptPath);