@iinm/plain-agent 1.8.10 → 1.9.0

package/README.md

@@ -322,17 +322,13 @@ Files are loaded in the following order. Settings in later files override earlie
   └── .plain-agent/
         ├── (3) config.json        # Project-specific configuration
         ├── (4) config.local.json  # Project-specific local configuration (including secrets)
-        ├── memory/                  # Task-specific memory files (auto-approvable, writable in sandbox)
-        ├── tmp/                     # Agent scratch space (auto-approvable, writable in sandbox)
-        ├── claude-code-plugins/     # Cached Claude Code plugins (auto-approvable, writable in sandbox)
-        ├── prompts/                 # Project-specific prompts
-        ├── agents/                  # Project-specific agent roles
-        ├── sandbox/                 # Sandbox runner scripts (run.sh, Dockerfile)
-        └── setup.sh                 # Initial setup script
+        ├── prompts/               # Project-specific prompts
+        ├── agents/                # Project-specific agent roles
+        ├── memory/                # Task-specific memory files
+        ├── sandbox/               # Sandbox runner scripts
+        └── tmp/                   # Agent scratch space
 ```
 
-Within `.plain-agent/`, only `memory/`, `tmp/`, and `claude-code-plugins/` are auto-approvable as tool input; everything else is executed on the host or changes agent behavior, so writes/reads require explicit approval. The sandbox runner mounts `.plain-agent/` read-only and re-overlays those three scratch directories as writable.
-
 ### Example
 
 <details>
@@ -563,6 +559,13 @@ You are a code simplifier. Your role is to refactor code while preserving its fu
 
 ## Claude Code Plugin Support
 
+Plugins are installed under `.plain-agent/claude-code-plugins/` and must be
+installed per project by running `plain install-claude-code-plugins` from
+the project root. Global installation (e.g., under `~/.plain-agent`) is not
+supported, because plugins may include skills that the agent invokes
+autonomously, and scoping them to the project keeps approval rules and
+permission management straightforward.
+
 Example:
 
 ```js

package/config/agents.predefined/sandbox-configurator.md

@@ -76,22 +76,18 @@ Generate `.plain-agent/sandbox/run.sh`. Use the following Node.js example as the
 set -eu -o pipefail
 
 # Mount .plain-agent/ as read-only over the writable project root, then
-# re-overlay the agent's scratch directories as writable. This prevents
-# in-sandbox modification of host-executed scripts (sandbox/run.sh,
-# setup.sh) and agent config (config.json, prompts/, agents/, ...).
+# re-overlay only memory/ and tmp/ as writable scratch space.
 working_dir=$(pwd)
 metadata_dir="$working_dir/.plain-agent"
 mkdir -p \
   "$metadata_dir/memory" \
-  "$metadata_dir/tmp" \
-  "$metadata_dir/claude-code-plugins"
+  "$metadata_dir/tmp"
 
 options=(
   --allow-write
   --mount-readonly "$metadata_dir:$metadata_dir"
   --mount-writable "$metadata_dir/memory:$metadata_dir/memory"
   --mount-writable "$metadata_dir/tmp:$metadata_dir/tmp"
-  --mount-writable "$metadata_dir/claude-code-plugins:$metadata_dir/claude-code-plugins"
   --volume plain-sandbox--global--home-npm:/home/sandbox/.npm
   --volume node_modules
 )

package/config/config.predefined.json

@@ -33,6 +33,10 @@
         },
         "action": "ask"
       },
+      {
+        "toolName": "read_file",
+        "action": "allow"
+      },
       {
         "toolName": { "$regex": "^(switch_to_subagent|switch_to_main_agent)$" },
         "action": "allow"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iinm/plain-agent",
-  "version": "1.8.10",
+  "version": "1.9.0",
   "description": "A lightweight CLI-based coding agent",
   "license": "MIT",
   "type": "module",

package/src/cliFormatter.mjs

@@ -2,17 +2,17 @@
  * @import { Message, MessageContentToolUse, MessageContentToolResult, ProviderTokenUsage } from "./model"
  * @import { CompactContextInput } from "./tools/compactContext"
  * @import { ExecCommandInput } from "./tools/execCommand"
- * @import { PatchFileInput } from "./tools/patchFile"
+ * @import { PatchBlock, PatchFileInput } from "./tools/patchFile"
+ * @import { ReadFileInput } from "./tools/readFile"
  * @import { WriteFileInput } from "./tools/writeFile"
  * @import { TmuxCommandInput } from "./tools/tmuxCommand"
  * @import { SwitchToSubagentInput } from "./tools/switchToSubagent"
  */
 
-import { execFile } from "node:child_process";
-import { mkdtemp, rm, writeFile } from "node:fs/promises";
-import os from "node:os";
-import path from "node:path";
+import fs from "node:fs/promises";
 import { styleText } from "node:util";
+import { parseBlocks } from "./tools/patchFile.mjs";
+import { diffLines } from "./utils/diffLines.mjs";
 import { noThrow } from "./utils/noThrow.mjs";
 
 /** Length above which a single-line arg forces block-form rendering. */
@@ -61,11 +61,9 @@ export function formatArgs(args) {
 /**
  * Format tool use for display.
  * @param {MessageContentToolUse} toolUse
- * @param {{ createDiff?: (oldContent: string, newContent: string) => Promise<string | null> }} [options]
  * @returns {Promise<string>}
  */
-export async function formatToolUse(toolUse, options = {}) {
-  const { createDiff = tryGitDiff } = options;
+export async function formatToolUse(toolUse) {
   const { toolName, input } = toolUse;
 
   if (toolName === "exec_command") {
@@ -91,43 +89,30 @@ export async function formatToolUse(toolUse, options = {}) {
   if (toolName === "patch_file") {
     /** @type {Partial<PatchFileInput>} */
     const patchFileInput = input;
-    const diff = patchFileInput.diff || "";
-
-    /** @type {{search:string; replace:string}[]} */
-    const diffs = [];
-    const matches = Array.from(
-      diff.matchAll(
-        /<<< [0-9a-z]{3} <<< SEARCH\n(.*?)\n=== [0-9a-z]{3} ===\n(.*?)\n?>>> [0-9a-z]{3} >>> REPLACE/gs,
-      ),
-    );
-    for (const match of matches) {
-      const [_, search, replace] = match;
-      diffs.push({ search, replace });
-    }
-
-    const highlightedDiff = await Promise.all(
-      diffs.map(async ({ search, replace }) => {
-        const gitDiffOutput = await createDiff(search, replace);
-        if (gitDiffOutput) {
-          return `${gitDiffOutput}\n-------\n${replace}`;
-        }
-        return [
-          `${styleText("yellow", "(git diff unavailable, showing plain diff)")}`,
-          "--- old",
-          `${search}`,
-          "+++ new",
-          `${replace}`,
-        ].join("\n");
-      }),
-    );
-
+    const filePath = patchFileInput.filePath ?? "";
+    const patch = patchFileInput.patch || "";
+    const rendered = await renderPatch(filePath, patch);
     return [
       `tool: ${toolName}`,
-      `path: ${patchFileInput.filePath}`,
-      `diff:\n${highlightedDiff.join("\n\n")}`,
+      `path: ${filePath}`,
+      `patch:\n${rendered}`,
     ].join("\n");
   }
 
+  if (toolName === "read_file") {
+    /** @type {Partial<ReadFileInput>} */
+    const readFileInput = input;
+    /** @type {string[]} */
+    const lines = [`tool: ${toolName}`, `filePath: ${readFileInput.filePath}`];
+    if (readFileInput.offset !== undefined) {
+      lines.push(`offset: ${readFileInput.offset}`);
+    }
+    if (readFileInput.limit !== undefined) {
+      lines.push(`limit: ${readFileInput.limit}`);
+    }
+    return lines.join("\n");
+  }
+
   if (toolName === "tmux_command") {
     /** @type {Partial<TmuxCommandInput>} */
     const tmuxCommandInput = input;
@@ -234,6 +219,13 @@ export function formatToolResult(toolResult) {
       .replace(/(^<error>|<\/error>$)/gm, styleText("red", "$1"));
   }
 
+  if (toolResult.toolName === "read_file") {
+    return contentString.replace(
+      /^(\s*\d+:[0-9a-f]{2}\|)/gm,
+      styleText("gray", "$1"),
+    );
+  }
+
   if (toolResult.toolName === "tmux_command") {
     return contentString
       .replace(/(^<stdout>|<\/stdout>$)/gm, styleText("blue", "$1"))
@@ -431,88 +423,144 @@ export async function printMessage(message) {
 }
 
 /**
- * Generate a colored unified diff using `git diff --color`.
- * Falls back to `null` if git is unavailable or if any step fails
- * (temp directory creation, file writing, git execution, or cleanup).
- * @param {string} oldContent
- * @param {string} newContent
- * @returns {Promise<string | null>}
+ * Render a patch_file `patch` string for terminal display.
+ *
+ * Attempts to show a side-by-side diff (- removed, + added,   unchanged)
+ * by parsing the patch and reading the target file. Falls back to plain
+ * syntax highlighting on any failure.
+ *
+ * @param {string} filePath
+ * @param {string} patch
+ * @returns {Promise<string>}
  */
-async function tryGitDiff(oldContent, newContent) {
-  const tmpDir = await noThrow(() =>
-    mkdtemp(path.join(os.tmpdir(), "git-diff-")),
-  );
-  if (tmpDir instanceof Error) {
-    console.error(
-      styleText("yellow", `git diff: mkdtemp failed: ${tmpDir.message}`),
-    );
-    return null;
+async function renderPatch(filePath, patch) {
+  if (!patch) {
+    return "";
   }
+  const fallback = highlightPatchPlain(patch);
 
-  const oldPath = path.join(tmpDir, "old");
-  const newPath = path.join(tmpDir, "new");
+  const nonce = extractPatchNonce(patch);
+  if (!nonce) {
+    return fallback;
+  }
 
+  /** @type {PatchBlock[]} */
+  let blocks;
   try {
-    const w1 = await noThrow(() => writeFile(oldPath, oldContent, "utf8"));
-    if (w1 instanceof Error) {
-      console.error(
-        styleText("yellow", `git diff: writeFile(old) failed: ${w1.message}`),
-      );
-      return null;
-    }
+    blocks = parseBlocks(patch, nonce);
+  } catch {
+    return fallback;
+  }
 
-    const w2 = await noThrow(() => writeFile(newPath, newContent, "utf8"));
-    if (w2 instanceof Error) {
-      console.error(
-        styleText("yellow", `git diff: writeFile(new) failed: ${w2.message}`),
-      );
-      return null;
+  let originalLines = null;
+  if (filePath) {
+    const original = await noThrow(() => fs.readFile(filePath, "utf8"));
+    if (!(original instanceof Error)) {
+      originalLines = splitContentLines(original);
     }
+  }
 
-    const diffResult = await noThrow(() => execGitDiff(oldPath, newPath));
-    if (diffResult instanceof Error) {
-      console.error(
-        styleText("yellow", `git diff: exec failed: ${diffResult.message}`),
-      );
-      return null;
-    }
+  return blocks
+    .map((block) => renderPatchBlock(block, originalLines, nonce))
+    .join("\n\n");
+}
 
-    return diffResult;
-  } finally {
-    const cleanup = await noThrow(() =>
-      rm(tmpDir, { recursive: true, force: true }),
+/**
+ * @param {PatchBlock} block
+ * @param {string[] | null} originalLines
+ * @param {string} nonce
+ * @returns {string}
+ */
+function renderPatchBlock(block, originalLines, nonce) {
+  /** @type {string[]} */
+  const out = [];
+  if (block.op === "replace") {
+    out.push(
+      styleText(
+        "cyan",
+        `@@@ ${nonce} ${block.start}:${block.startHash}-${block.end}:${block.endHash}`,
+      ),
     );
-    if (cleanup instanceof Error) {
-      console.error(
-        styleText("yellow", `git diff: cleanup failed: ${cleanup.message}`),
-      );
+    if (originalLines) {
+      const safeStart = Math.max(1, block.start);
+      const safeEnd = Math.min(originalLines.length, block.end);
+      const oldSlice = originalLines.slice(safeStart - 1, safeEnd);
+      // Use a real line diff so unchanged lines render as context
+      // (no color, "  " prefix) instead of being shown as both "- " and
+      // "+ ".
+      for (const op of diffLines(oldSlice, block.body)) {
+        if (op.type === "-") {
+          out.push(styleText("red", `- ${op.line}`));
+        } else if (op.type === "+") {
+          out.push(styleText("green", `+ ${op.line}`));
+        } else {
+          out.push(`  ${op.line}`);
+        }
+      }
+    } else {
+      // No file context available — fall back to listing the body as
+      // additions so the user can still see the new content.
+      for (const line of block.body) {
+        out.push(styleText("green", `+ ${line}`));
+      }
+    }
+  } else {
+    const afterSuffix = block.afterHash ? `:${block.afterHash}` : "";
+    out.push(styleText("cyan", `@@@ ${nonce} ${block.after}${afterSuffix}+`));
+    for (const line of block.body) {
+      out.push(styleText("green", `+ ${line}`));
     }
   }
+  out.push(styleText("cyan", `@@@ ${nonce}`));
+  return out.join("\n");
 }
 
 /**
- * Execute git diff accepting exit code 1 as success (differences found).
- * @param {string} oldPath
- * @param {string} newPath
- * @returns {Promise<string>}
+ * Verbatim highlighter used as fallback when block-aware rendering is not
+ * possible (parse error, missing nonce, etc.).
+ * @param {string} patch
+ * @returns {string}
  */
-function execGitDiff(oldPath, newPath) {
-  return new Promise((resolve, reject) => {
-    execFile(
-      "git",
-      ["--no-pager", "diff", "--color", "--no-index", "--", oldPath, newPath],
-      { encoding: "utf8", maxBuffer: 10 * 1024 * 1024 },
-      (error, stdout, stderr) => {
-        if (stderr) {
-          console.error(styleText("yellow", `git diff stderr: ${stderr}`));
-        }
-        // git diff returns exit code 1 when there are differences, which is expected
-        if (error && error.code !== 1) {
-          reject(error);
-        } else {
-          resolve(stdout);
-        }
-      },
-    );
-  });
+function highlightPatchPlain(patch) {
+  if (!patch) {
+    return "";
+  }
+  // Patch headers/closes look like "@@@ <nonce> ..." or "@@@ <nonce>".
+  const headerRegex = /^@@@\s+\S+(\s.*)?$/;
+  return patch
+    .split("\n")
+    .map((line) => {
+      if (headerRegex.test(line)) {
+        return styleText("cyan", line);
+      }
+      if (line === "") {
+        return line;
+      }
+      return styleText("green", line);
+    })
+    .join("\n");
+}
+
+/**
+ * Extract the nonce from the first open marker in a patch_file patch.
+ * @param {string} patch
+ * @returns {string | null}
+ */
+function extractPatchNonce(patch) {
+  const match = patch.match(/^@@@\s+(\S+)/m);
+  return match ? match[1] : null;
+}
+
+/**
+ * Split file content into lines, dropping the trailing empty element when
+ * the file ends with a newline (matches patch_file's own line indexing).
+ * @param {string} content
+ * @returns {string[]}
+ */
+function splitContentLines(content) {
+  const lines = content.split("\n");
+  if (lines.length > 0 && lines[lines.length - 1] === "") {
+    lines.pop();
+  }
+  return lines;
 }

package/src/main.mjs

@@ -24,6 +24,7 @@ import { createAskWebTool } from "./tools/askWeb.mjs";
 import { createCompactContextTool } from "./tools/compactContext.mjs";
 import { createExecCommandTool } from "./tools/execCommand.mjs";
 import { createPatchFileTool } from "./tools/patchFile.mjs";
+import { readFileTool } from "./tools/readFile.mjs";
 import { createSwitchToMainAgentTool } from "./tools/switchToMainAgent.mjs";
 import { createSwitchToSubagentTool } from "./tools/switchToSubagent.mjs";
 import { createTmuxCommandTool } from "./tools/tmuxCommand.mjs";
@@ -177,6 +178,7 @@ if (cliArgs.subcommand.type === "cost") {
 
   const builtinTools = [
     createExecCommandTool({ sandbox: appConfig.sandbox }),
+    readFileTool,
     writeFileTool,
     createPatchFileTool(),
     createTmuxCommandTool({ sandbox: appConfig.sandbox }),

package/src/mcpIntegration.mjs

@@ -149,8 +149,7 @@ async function createMCPTools(serverName, client) {
             const lineCount = formmatted.split("\n").length;
 
             return [
-              `Content is large (${resultString.length} characters, ${lineCount} lines) and saved to ${filePath}`,
-              "Use exec_command tool to find relevant parts.",
+              `Content is large (${resultString.length} characters, ${lineCount} lines) and saved to ${filePath}.`,
             ].join("\n");
           }),
       };

package/src/prompt.mjs

@@ -80,7 +80,6 @@ Call multiple tools at once when they don't depend on each other's results.
 Examples:
 - List directories or find files: fd [".", "./", "--max-depth", "3", "--type", "d", "--hidden"]
 - Search for strings: rg ["--heading", "--line-number", "pattern", "./"]
-- Read specific line ranges (max 200 lines): sed ["-n", "1,200p", "file.txt"]
 - Manage GitHub issues and PRs:
   Get PR details: gh ["pr", "view", "123", "--json", "title,body,url"]
   Get PR comment: gh ["api", "--method", "GET", "repos/<owner>/<repo>/pulls/comments/<id>", "--jq", "{user: .user.login, path: .path, line: .line, body: .body}"]

package/src/toolInputValidator.mjs

@@ -9,6 +9,17 @@ import {
 } from "./env.mjs";
 import { noThrowSync } from "./utils/noThrow.mjs";
 
+// Paths that must never be auto-approvable as tool input, even when
+// git-managed. Sandbox scripts run on the host and the project config files
+// drive auto-approval policy itself, so silent in-sandbox modification of
+// either could lead to host code execution or self-granted privilege
+// escalation.
+const UNSAFE_PROJECT_PATHS = [
+  path.join(AGENT_PROJECT_METADATA_DIR, "sandbox"),
+  path.join(AGENT_PROJECT_METADATA_DIR, "config.json"),
+  path.join(AGENT_PROJECT_METADATA_DIR, "config.local.json"),
+];
+
 /**
  * @param {unknown} input
  * @returns {boolean}
@@ -65,15 +76,14 @@ export function isSafeToolInputItem(arg) {
     return false;
   }
 
-  // Inside the agent metadata directory, only the agent's known scratch
-  // directories (memory, tmp, claude-code-plugins) are auto-approvable
-  // (and that exception applies even when those subdirectories are
-  // git-ignored). Other entries (sandbox/, setup.sh, config.json,
-  // prompts/, agents/, ...) are executed on the host or change agent
-  // behavior across sessions, so tool uses targeting them must require
-  // explicit approval even if the file is git-managed.
-  if (isInsideAgentMetadataDir(realPath)) {
-    return isSafePath(realPath);
+  // Always require approval for these, even if git-managed.
+  if (isUnsafeProjectPath(realPath)) {
+    return false;
+  }
+
+  // Always allow these even if git-ignored.
+  if (isSafePath(realPath)) {
+    return true;
   }
 
   // Deny git ignored files (which may contain sensitive information or should not be accessed)
@@ -166,12 +176,18 @@ function isSafePath(targetPath) {
  * @param {string} targetPath
  * @returns {boolean}
  */
-function isInsideAgentMetadataDir(targetPath) {
-  const metadataAbsPath = path.resolve(AGENT_PROJECT_METADATA_DIR);
-  return (
-    targetPath === metadataAbsPath ||
-    targetPath.startsWith(`${metadataAbsPath}${path.sep}`)
-  );
+function isUnsafeProjectPath(targetPath) {
+  for (const unsafePath of UNSAFE_PROJECT_PATHS) {
+    const unsafeAbsPath = path.resolve(unsafePath);
+    if (
+      targetPath === unsafeAbsPath ||
+      targetPath.startsWith(`${unsafeAbsPath}${path.sep}`)
+    ) {
+      return true;
+    }
+  }
+
+  return false;
 }
 
 /**

package/src/tools/patchFile.d.ts

@@ -1,4 +1,20 @@
 export type PatchFileInput = {
   filePath: string;
-  diff: string;
+  patch: string;
 };
+
+export type PatchBlock =
+  | {
+      op: "replace";
+      start: number;
+      end: number;
+      startHash: string;
+      endHash: string;
+      body: string[];
+    }
+  | {
+      op: "insert";
+      after: number;
+      afterHash: string;
+      body: string[];
+    };

package/src/tools/patchFile.mjs

@@ -1,9 +1,10 @@
 /**
  * @import { Tool } from '../tool'
- * @import { PatchFileInput } from './patchFile'
+ * @import { PatchBlock, PatchFileInput } from './patchFile'
  */
 
 import fs from "node:fs/promises";
+import { lineHash } from "../utils/lineHash.mjs";
 import { noThrow } from "../utils/noThrow.mjs";
 
 /**
@@ -17,35 +18,41 @@ export function createPatchFileTool(
     def: {
       name: "patch_file",
       description:
-        "Modify a file by replacing specific content with new content.",
+        "Modify a file by replacing or inserting content addressed by line numbers (1-indexed).",
       inputSchema: {
         type: "object",
         properties: {
           filePath: {
             type: "string",
           },
-          diff: {
+          patch: {
             description: `
 Format:
-<<< ${nonce} <<< SEARCH
-old content
-=== ${nonce} ===
+@@@ ${nonce} {start}:{startHash}-{end}:{endHash}
 new content
->>> ${nonce} >>> REPLACE
+@@@ ${nonce}
 
-<<< ${nonce} <<< SEARCH
-other old content
-=== ${nonce} ===
-other new content
->>> ${nonce} >>> REPLACE
+@@@ ${nonce} {N}:{afterHash}+
+inserted content
+@@@ ${nonce}
 
-- Content is searched as an exact match including indentation and line breaks.
-- The first match found will be replaced if there are multiple matches.
-          `.trim(),
+@@@ ${nonce} 0+
+prepended content
+@@@ ${nonce}
+
+- Line numbers are 1-indexed and refer to the original file;
+  "{start}-{end}" is inclusive.
+- Hashes are 2-hex-char digests of each line's full content as shown
+  by read_file (e.g. "a3"). They verify the LLM is targeting the
+  correct lines; on mismatch, re-read the file with read_file.
+- "{N}:{afterHash}+" inserts after line N; "0+" prepends (no hash
+  needed for line 0). "{lastLine}:{hash}+" appends.
+- Empty body deletes the range.
+            `.trim(),
             type: "string",
           },
         },
-        required: ["filePath", "diff"],
+        required: ["filePath", "patch"],
       },
     },
 
@@ -55,66 +62,16 @@ other new content
      */
     impl: async (input) =>
       await noThrow(async () => {
-        const { filePath, diff } = input;
-
-        // Validate marker counts: each block needs exactly one of each marker.
-        // Since nonce is random, duplicate markers mean the user accidentally
-        // included a marker line in their search/replace content (copy-paste error).
-        const searchMarker = `<<< ${nonce} <<< SEARCH`;
-        const sepMarker = `=== ${nonce} ===`;
-        const replaceMarker = `>>> ${nonce} >>> REPLACE`;
-        /** @type {(s: string, sub: string) => number} */
-        const count = (s, sub) => s.split(sub).length - 1;
-        const nSearch = count(diff, searchMarker);
-        const nSep = count(diff, sepMarker);
-        const nReplace = count(diff, replaceMarker);
-
-        if (nSearch !== nReplace) {
-          throw new Error(
-            `Mismatched block markers: found ${nSearch} "${searchMarker}" but ${nReplace} "${replaceMarker}". ` +
-              "Did you accidentally include a marker in your search/replace content?",
-          );
-        }
-        if (nSep !== nSearch) {
+        const { filePath, patch } = input;
+        const blocks = parseBlocks(patch, nonce);
+        if (blocks.length === 0) {
           throw new Error(
-            `Each diff block needs exactly one "${sepMarker}" separator, ` +
-              `but found ${nSep} separators for ${nSearch} block(s). ` +
-              "Did you accidentally include the separator marker in your search/replace content?",
+            `No patch blocks found. Each block must start with "@@@ ${nonce} ..." and end with "@@@ ${nonce}".`,
           );
         }
 
-        const content = await fs.readFile(filePath, "utf8");
-        const matches = Array.from(
-          diff.matchAll(
-            new RegExp(
-              `<<< ${nonce} <<< SEARCH\\n(.*?)\\n=== ${nonce} ===\\n(.*?)\\n?>>> ${nonce} >>> REPLACE`,
-              "gs",
-            ),
-          ),
-        );
-        if (matches.length === 0) {
-          throw new Error(
-            `Invalid diff format. Each markers must include the nonce: <<< ${nonce} <<< SEARCH, === ${nonce} ===, >>> ${nonce} >>> REPLACE`,
-          );
-        }
-        let newContent = content;
-        for (const match of matches) {
-          const [_, search, replace] = match;
-          if (!newContent.includes(search)) {
-            throw new Error(
-              JSON.stringify(`Search content not found: ${search}`),
-            );
-          }
-          // Escape $ characters in replacement string to prevent interpretation of $& $1 $$ patterns
-          const escapedReplace = replace.replace(/\$/g, "$$$$");
-          if (replace === "" && newContent.includes(`${search}\n`)) {
-            newContent = newContent.replace(`${search}\n`, "");
-          } else if (replace === "" && newContent.includes(`\n${search}`)) {
-            newContent = newContent.replace(`\n${search}`, "");
-          } else {
-            newContent = newContent.replace(search, escapedReplace);
-          }
-        }
+        const original = await fs.readFile(filePath, "utf8");
+        const newContent = applyBlocks(original, blocks);
         await fs.writeFile(filePath, newContent);
         return `Patched file: ${filePath}`;
       }),
@@ -131,3 +88,241 @@ other new content
     },
   };
 }
+
+/**
+ * Parse a patch string into a list of patch blocks.
+ * @param {string} patch
+ * @param {string} nonce
+ * @returns {PatchBlock[]}
+ */
+export function parseBlocks(patch, nonce) {
+  const openPrefix = `@@@ ${nonce} `;
+  const closeMarker = `@@@ ${nonce}`;
+  const lines = patch.split("\n");
+
+  /** @type {PatchBlock[]} */
+  const blocks = [];
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (line === "") {
+      continue;
+    }
+    if (line === closeMarker) {
+      throw new Error(
+        `Unexpected close marker "${closeMarker}" with no matching open block (line ${i + 1} of patch).`,
+      );
+    }
+    if (!line.startsWith(openPrefix)) {
+      throw new Error(
+        `Expected block header starting with "${openPrefix}" but got: ${JSON.stringify(line)} (line ${i + 1} of patch).`,
+      );
+    }
+
+    const headerArgs = line.slice(openPrefix.length);
+    const header = parseHeaderArgs(headerArgs);
+    const closeIdx = lines.indexOf(closeMarker, i + 1);
+    if (closeIdx === -1) {
+      throw new Error(
+        `Missing close marker "${closeMarker}" for block "${openPrefix}${headerArgs}".`,
+      );
+    }
+    const body = lines.slice(i + 1, closeIdx);
+    if (header.op === "insert" && body.length === 0) {
+      throw new Error(
+        `Insert block "${openPrefix}${headerArgs}" has empty body. Use a replace block to delete content.`,
+      );
+    }
+    blocks.push({ ...header, body });
+    i = closeIdx;
+  }
+  return blocks;
+}
+
+/**
+ * @param {string} original
+ * @param {PatchBlock[]} blocks
+ * @returns {string}
+ */
+export function applyBlocks(original, blocks) {
+  const hasTrailingNewline = original.endsWith("\n");
+  const lines = original.split("\n");
+  // Drop the trailing empty element produced by split() for both
+  // newline-terminated content and an empty input. This keeps line counts
+  // consistent with read_file (an empty file reports 0 lines).
+  if (lines.length > 0 && lines[lines.length - 1] === "") {
+    lines.pop();
+  }
+  const totalLines = lines.length;
+
+  validateBlocks(blocks, totalLines);
+  detectConflicts(blocks);
+
+  // Sort for bottom-up application.
+  // - Higher splice index first.
+  // - Tie: replace before insert (replace must run first so insert can
+  //   land at the same splice position post-replace).
+  // - Tie among inserts at the same point: later-in-source first, so the
+  //   first-in-source block ends up topmost in the inserted stack.
+  const indexed = blocks.map((block, sourceIdx) => ({
+    block,
+    sourceIdx,
+    spliceIndex: spliceIndexOf(block),
+  }));
+  indexed.sort((a, b) => {
+    if (a.spliceIndex !== b.spliceIndex) {
+      return b.spliceIndex - a.spliceIndex;
+    }
+    if (a.block.op !== b.block.op) {
+      return a.block.op === "replace" ? -1 : 1;
+    }
+    return b.sourceIdx - a.sourceIdx;
+  });
+
+  for (const { block } of indexed) {
+    if (block.op === "replace") {
+      const actualStart = lines[block.start - 1];
+      const expectedStartHash = block.startHash;
+      const actualStartHash = lineHash(actualStart ?? "");
+      if (actualStartHash !== expectedStartHash) {
+        throw new Error(
+          `Hash verification failed at line ${block.start}: expected hash ${expectedStartHash} but got ${actualStartHash} for line ${JSON.stringify(actualStart)}. The line numbers may be stale; re-read the file with read_file.`,
+        );
+      }
+      const actualEnd = lines[block.end - 1];
+      const expectedEndHash = block.endHash;
+      const actualEndHash = lineHash(actualEnd ?? "");
+      if (actualEndHash !== expectedEndHash) {
+        throw new Error(
+          `Hash verification failed at line ${block.end}: expected hash ${expectedEndHash} but got ${actualEndHash} for line ${JSON.stringify(actualEnd)}. The line numbers may be stale; re-read the file with read_file.`,
+        );
+      }
+      const removeCount = block.end - block.start + 1;
+      lines.splice(block.start - 1, removeCount, ...block.body);
+    } else {
+      if (block.after > 0) {
+        const actualAfter = lines[block.after - 1];
+        const expectedAfterHash = block.afterHash;
+        const actualAfterHash = lineHash(actualAfter ?? "");
+        if (actualAfterHash !== expectedAfterHash) {
+          throw new Error(
+            `Hash verification failed at line ${block.after}: expected hash ${expectedAfterHash} but got ${actualAfterHash} for line ${JSON.stringify(actualAfter)}. The line numbers may be stale; re-read the file with read_file.`,
+          );
+        }
+      }
+      lines.splice(block.after, 0, ...block.body);
+    }
+  }
+
+  let result = lines.join("\n");
+  if (hasTrailingNewline) {
+    result += "\n";
+  }
+  return result;
+}
+
+/**
+ * @param {string} headerArgs
+ * @returns {{ op: "replace"; start: number; end: number; startHash: string; endHash: string } | { op: "insert"; after: number; afterHash: string }}
+ */
+function parseHeaderArgs(headerArgs) {
+  // Replace form: "{start}:{startHash}-{end}:{endHash}"
+  const replaceMatch = headerArgs.match(
+    /^(\d+):([a-f0-9]{2})-(\d+):([a-f0-9]{2})\s*$/,
+  );
+  if (replaceMatch) {
+    const start = Number(replaceMatch[1]);
+    const end = Number(replaceMatch[3]);
+    if (start < 1) {
+      throw new Error(
+        `Invalid replace range "${headerArgs}": start must be >= 1.`,
+      );
+    }
+    if (end < start) {
+      throw new Error(
+        `Invalid replace range "${headerArgs}": end (${end}) must be >= start (${start}).`,
+      );
+    }
+    return {
+      op: "replace",
+      start,
+      end,
+      startHash: replaceMatch[2],
+      endHash: replaceMatch[4],
+    };
+  }
+  // Insert form: "0+" (no hash — there is no line 0 to verify)
+  if (/^0\+\s*$/.test(headerArgs)) {
+    return { op: "insert", after: 0, afterHash: "" };
+  }
+  // Insert form: "{N}:{afterHash}+"
+  const insertMatch = headerArgs.match(/^(\d+):([a-f0-9]{2})\+\s*$/);
+  if (insertMatch) {
+    return {
+      op: "insert",
+      after: Number(insertMatch[1]),
+      afterHash: insertMatch[2],
+    };
+  }
+  throw new Error(
+    `Invalid block header arguments: ${JSON.stringify(headerArgs)}. Expected "{start}:{startHash}-{end}:{endHash}" or "{N}:{afterHash}+" or "0+".`,
+  );
+}
+
+/**
+ * @param {PatchBlock} block
+ * @returns {number}
+ */
+function spliceIndexOf(block) {
+  return block.op === "replace" ? block.start - 1 : block.after;
+}
+
+/**
+ * @param {PatchBlock[]} blocks
+ * @param {number} totalLines
+ */
+function validateBlocks(blocks, totalLines) {
+  for (const block of blocks) {
+    if (block.op === "replace") {
+      if (totalLines < block.end) {
+        throw new Error(
+          `Replace range ${block.start}-${block.end} extends past end of file (${totalLines} lines).`,
+        );
+      }
+    } else if (block.after < 0 || totalLines < block.after) {
+      throw new Error(
+        `Insert position ${block.after}+ is outside [0, ${totalLines}].`,
+      );
+    }
+  }
+}
+
+/**
+ * @param {PatchBlock[]} blocks
+ */
+function detectConflicts(blocks) {
+  for (let i = 0; i < blocks.length; i++) {
+    for (let j = i + 1; j < blocks.length; j++) {
+      const a = blocks[i];
+      const b = blocks[j];
+      if (a.op === "replace" && b.op === "replace") {
+        if (a.start <= b.end && b.start <= a.end) {
+          throw new Error(
+            `Replace ranges overlap: ${a.start}-${a.end} and ${b.start}-${b.end}.`,
+          );
+        }
+      } else if (a.op === "replace" && b.op === "insert") {
+        if (a.start <= b.after && b.after < a.end) {
+          throw new Error(
+            `Insert at ${b.after}+ falls inside replace range ${a.start}-${a.end}.`,
+          );
+        }
+      } else if (a.op === "insert" && b.op === "replace") {
+        if (b.start <= a.after && a.after < b.end) {
+          throw new Error(
+            `Insert at ${a.after}+ falls inside replace range ${b.start}-${b.end}.`,
+          );
+        }
+      }
+    }
+  }
+}

package/src/tools/readFile.d.ts

@@ -0,0 +1,9 @@
+export type ReadFileInput = {
+  filePath: string;
+  offset?: number;
+  limit?: number;
+};
+
+export type ReadFileConfig = {
+  outputMaxLength?: number;
+};

package/src/tools/readFile.mjs

@@ -0,0 +1,139 @@
+/**
+ * @import { Tool } from '../tool'
+ * @import { ReadFileInput } from './readFile'
+ */
+
+import fs from "node:fs";
+import readline from "node:readline";
+import { lineHash } from "../utils/lineHash.mjs";
+import { noThrow } from "../utils/noThrow.mjs";
+
+const OUTPUT_MAX_LENGTH = 1024 * 8;
+
+/** @type {Tool} */
+export const readFileTool = {
+  def: {
+    name: "read_file",
+    description:
+      "Read a file with line numbers (1-indexed). Each line is prefixed with its number and a short content hash: `{no}:{hash}|{content}` (e.g. `1:a3|function hello() {`).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        filePath: {
+          type: "string",
+        },
+        offset: {
+          description: "1-indexed start line. Defaults to 1.",
+          type: "number",
+        },
+        limit: {
+          description: "Maximum number of lines to return.",
+          type: "number",
+        },
+      },
+      required: ["filePath"],
+    },
+  },
+
+  /**
+   * @param {ReadFileInput} input
+   * @returns {Promise<string | Error>}
+   */
+  impl: async (input) =>
+    await noThrow(async () => {
+      const { filePath } = input;
+      const offset = input.offset ?? 1;
+      const limit = input.limit;
+
+      if (!Number.isInteger(offset) || offset < 1) {
+        throw new Error("offset must be a positive integer (1-indexed)");
+      }
+      if (limit !== undefined && (!Number.isInteger(limit) || limit < 1)) {
+        throw new Error("limit must be a positive integer");
+      }
+
+      const lines = await readLineRange(filePath, offset, limit);
+      return formatNumberedLines(lines, offset);
+    }),
+};
+
+/**
+ * @param {string} filePath
+ * @param {number} offset
+ * @param {number | undefined} limit
+ * @returns {Promise<string[]>}
+ */
+async function readLineRange(filePath, offset, limit) {
+  const stream = fs.createReadStream(filePath, { encoding: "utf8" });
+  const rl = readline.createInterface({
+    input: stream,
+    crlfDelay: Number.POSITIVE_INFINITY,
+  });
+
+  /** @type {string[]} */
+  const lines = [];
+  let lineNo = 0;
+  // Line-number padding and tab separator are not counted toward the cap.
+  let acceptedLength = 0;
+
+  try {
+    for await (const line of rl) {
+      lineNo++;
+      if (lineNo < offset) {
+        continue;
+      }
+
+      const lineCost = line.length + 1;
+
+      if (acceptedLength + lineCost > OUTPUT_MAX_LENGTH) {
+        if (lines.length === 0) {
+          throw new Error(
+            `Output would exceed ${OUTPUT_MAX_LENGTH} characters at line ${lineNo}: ` +
+              "that line alone is too large to include. Consider reading the file with a different tool.",
+          );
+        }
+        const lastFitting = offset + lines.length - 1;
+        throw new Error(
+          `Output would exceed ${OUTPUT_MAX_LENGTH} characters at line ${lineNo}. ` +
+            `Lines ${offset}-${lastFitting} fit; read them with limit=${lines.length}, ` +
+            `then continue from offset=${lastFitting + 1}.`,
+        );
+      }
+
+      acceptedLength += lineCost;
+      lines.push(line);
+
+      if (limit !== undefined && lines.length >= limit) {
+        break;
+      }
+    }
+  } finally {
+    rl.close();
+    if (!stream.destroyed) {
+      stream.destroy();
+    }
+  }
+
+  return lines;
+}
+
+/**
+ * @param {string[]} lines
+ * @param {number} startLine 1-indexed line number of `lines[0]`.
+ * @returns {string}
+ */
+function formatNumberedLines(lines, startLine) {
+  if (lines.length === 0) {
+    return "";
+  }
+  const lastLineNo = startLine + lines.length - 1;
+  const width = String(lastLineNo).length;
+
+  const out = [];
+  for (let i = 0; i < lines.length; i++) {
+    const lineNo = String(startLine + i).padStart(width, " ");
+    const hash = lineHash(lines[i]);
+    out.push(`${lineNo}:${hash}|${lines[i]}`);
+  }
+  return out.join("\n");
+}

package/src/utils/diffLines.mjs

@@ -0,0 +1,91 @@
+/**
+ * @typedef {{ type: " " | "-" | "+"; line: string }} DiffOp
+ */
+
+/**
+ * Compute a unified-style line diff between two arrays.
+ *
+ * Returns an edit script that transforms `oldLines` into `newLines`,
+ * with three op kinds:
+ *   - " " : line is in both (context)
+ *   - "-" : line is only in old (removed)
+ *   - "+" : line is only in new (added)
+ *
+ * Within a hunk (a run of changes between context lines), all `-` ops
+ * appear before all `+` ops to match the conventional unified-diff
+ * presentation produced by `git diff` and friends.
+ *
+ * Implementation: standard O(N*M) longest-common-subsequence DP plus
+ * a backtrack pass. This is fine for the patch_file block sizes we
+ * expect (typically a few dozen lines per block); we avoid pulling in
+ * a Myers-diff dependency.
+ *
+ * @param {string[]} oldLines
+ * @param {string[]} newLines
+ * @returns {DiffOp[]}
+ */
+export function diffLines(oldLines, newLines) {
+  const n = oldLines.length;
+  const m = newLines.length;
+
+  // dp[i][j] = LCS length of oldLines[0..i) and newLines[0..j).
+  const dp = Array.from({ length: n + 1 }, () => new Array(m + 1).fill(0));
+  for (let i = 1; i <= n; i++) {
+    for (let j = 1; j <= m; j++) {
+      if (oldLines[i - 1] === newLines[j - 1]) {
+        dp[i][j] = dp[i - 1][j - 1] + 1;
+      } else {
+        dp[i][j] = Math.max(dp[i - 1][j], dp[i][j - 1]);
+      }
+    }
+  }
+
+  // Backtrack from (n, m) to (0, 0). We walk in reverse, accumulating
+  // pending deletes/adds until we hit a context line; then we flush
+  // them so that, after the final reverse, deletes appear before adds
+  // within each hunk.
+  /** @type {DiffOp[]} */
+  const ops = [];
+  /** @type {string[]} */
+  let pendingDel = [];
+  /** @type {string[]} */
+  let pendingAdd = [];
+
+  // While walking back, we push ops in reverse order. For each hunk we
+  // want the final order (after reverse()) to be: deletes-in-source-order
+  // then adds-in-source-order. So during the reverse walk we must push
+  // adds first, then deletes.
+  const flush = () => {
+    for (const line of pendingAdd) {
+      ops.push({ type: "+", line });
+    }
+    for (const line of pendingDel) {
+      ops.push({ type: "-", line });
+    }
+    pendingAdd = [];
+    pendingDel = [];
+  };
+
+  let i = n;
+  let j = m;
+  while (i > 0 || j > 0) {
+    if (i > 0 && j > 0 && oldLines[i - 1] === newLines[j - 1]) {
+      flush();
+      ops.push({ type: " ", line: oldLines[i - 1] });
+      i--;
+      j--;
+      continue;
+    }
+    if (j > 0 && (i === 0 || dp[i][j - 1] >= dp[i - 1][j])) {
+      pendingAdd.push(newLines[j - 1]);
+      j--;
+    } else {
+      pendingDel.push(oldLines[i - 1]);
+      i--;
+    }
+  }
+  flush();
+
+  ops.reverse();
+  return ops;
+}

package/src/utils/lineHash.mjs

@@ -0,0 +1,15 @@
+/**
+ * Compute a short hash of a line's full content (including whitespace).
+ * Uses the DJB2 hash algorithm, producing a 2-hex-char digest (256 values).
+ * @param {string} line
+ * @returns {string} 2-character lowercase hex string
+ */
+export function lineHash(line) {
+  let hash = 0;
+  for (let i = 0; i < line.length; i++) {
+    const char = line.charCodeAt(i);
+    hash = (hash << 5) - hash + char;
+    hash = hash & hash;
+  }
+  return Math.abs(hash).toString(16).padStart(2, "0").slice(0, 2);
+}