trueline-mcp 2.2.0 → 2.4.0

package/README.md

@@ -8,7 +8,7 @@ VS Code Copilot, OpenCode, and Codex CLI.
 
 ## Installation
 
-**Claude Code** (recommended — hooks are automatic):
+**Claude Code** (recommended; hooks are automatic):
 
 ```
 /plugin marketplace add rjkaes/trueline-mcp
@@ -23,7 +23,7 @@ See [INSTALL.md](INSTALL.md) for platform-specific setup instructions.
 AI agents waste tokens in two ways:
 
 1. **Reading too much.** To find a function in a 500-line file, the agent
-   reads all 500 lines — most of which it doesn't need.
+   reads all 500 lines, most of which it doesn't need.
 
 2. **Echoing on edit.** The built-in `Edit` tool requires the agent to
    output the old text being replaced (`old_string`) plus the new text.
@@ -32,19 +32,19 @@ AI agents waste tokens in two ways:
 Both problems compound. A typical editing session reads dozens of files
 and makes multiple edits, burning through context on redundant content.
 
-And when things go wrong — stale reads, hallucinated anchors, ambiguous
-matches — the agent silently corrupts your code.
+And when things go wrong (stale reads, hallucinated anchors, ambiguous
+matches) the agent silently corrupts your code.
 
 ## How trueline fixes this
 
-trueline replaces Claude Code's built-in `Read` and `Edit` with four
-tools that are smaller, faster, and verified.
+trueline replaces the built-in `Read` and `Edit` with five tools that
+are smaller, faster, and verified.
 
-### 95% fewer input tokens with `trueline_outline`
+### Read less: `trueline_outline` + `trueline_read`
 
-Instead of reading an entire file to understand its structure,
-`trueline_outline` returns a compact AST outline — just the functions,
-classes, types, and declarations with their line ranges:
+Instead of reading an entire file, the agent starts with
+`trueline_outline`, a compact AST outline showing just the functions,
+classes, and declarations with their line ranges:
 
 ```
 1-10: (10 imports)
@@ -57,150 +57,53 @@ classes, types, and declarations with their line ranges:
 (12 symbols, 139 source lines)
 ```
 
-12 lines instead of 139. The agent sees the full structure, picks the
-ranges it needs, and reads only those — skipping hundreds of irrelevant
-lines.
+12 lines instead of 139. The agent sees the full structure, then reads
+only the ranges it needs, skipping hundreds of irrelevant lines.
 
 | File size   | Full read | Outline | Savings |
-|-------------|-----------|---------|---------|
+|-------------|-----------|---------|--------|
 | 140 lines   | 140 tokens | 12 tokens | 91% |
 | 245 lines   | 245 tokens | 14 tokens | 94% |
 | 504 lines   | 504 tokens | 4 tokens  | 99% |
 
-Every line range in the outline maps directly to a `trueline_read` call.
+`trueline_read` supports multiple disjoint ranges in a single call and
+an optional `hashes: false` mode for exploratory reads that saves ~3
+tokens per line.
 
-Supports 20+ languages: TypeScript, JavaScript, Python, Go, Rust, Java, C,
-C++, C#, Ruby, PHP, Kotlin, Swift, Scala, Elixir, Lua, Dart, Zig, Bash.
+### Find and fix: `trueline_search`
 
-### 44% fewer output tokens with `trueline_edit`
+When the agent knows what it's looking for, `trueline_search` finds
+lines by regex and returns them with enough context to edit immediately,
+no outline or read step needed.
 
-The built-in `Edit` makes the model echo back the text being replaced:
+A search-based workflow uses **~127 tokens** vs **~2000** for
+outline+read, a 93% reduction for targeted lookups.
 
-```json
-// Built-in Edit — model must output the old text
-{
-  "old_string": "export function handleRequest(req: Request) {\n  ...\n}",
-  "new_string": "export function handleRequest(req: Request) {\n  ...(new)...\n}"
-}
-```
-
-`trueline_edit` replaces old text with a compact line-range reference:
-
-```json
-// trueline_edit — just the range and the new content
-{
-  "edits": [{
-    "checksum": "1-50:a3b1c2d4",
-    "range": "12:kf..16:qz",
-    "content": "export function handleRequest(req: Request) {\n  ...(new)...\n}"
-  }]
-}
-```
-
-The model never echoes old text. For a typical 15-line edit:
-
-| | Built-in Edit | trueline_edit |
-|---|---|---|
-| Old text echoed (output tokens) | ~225 | 0 |
-| New text (output tokens) | ~225 | ~225 |
-| Range/checksum overhead | 0 | ~13 |
-| **Total output tokens** | **~470** | **~263** |
-| **Savings** | | **44%** |
-
-Output tokens are the most expensive token class. Cutting them by 44%
-on every edit adds up fast.
-
-### Targeted reads save more input tokens
+### Write less: `trueline_edit`
 
-`trueline_read` supports multiple disjoint ranges in a single call.
-Instead of re-reading a 2000-line file to edit two distant sections,
-the agent reads only the ranges it needs:
+The built-in `Edit` makes the model echo back the old text being
+replaced. `trueline_edit` replaces that with a compact line-range
+reference: the model only outputs the new content.
 
-```
-trueline_read(file_path: "big-file.ts", ranges: [{start: 45, end: 60}, {start: 200, end: 215}])
-```
+For a typical 15-line edit, that's **44% fewer output tokens**. Output
+tokens are the most expensive token class, so this adds up fast.
 
-30 lines instead of 2000 — with separate checksums for each range.
+Multiple edits can be batched in a single call and applied atomically.
 
-### Hash verification catches mistakes
+### Never corrupt: hash verification
 
 Every line from `trueline_read` carries a content hash. Every edit must
 present those hashes back, proving the agent is working against the
-file's actual content:
-
-```
-1:bx|import { Server } from "@modelcontextprotocol/sdk/server/index.js";
-2:dd|
-3:ew|const server = new Server({ name: "trueline-mcp", version: "0.1.0" });
-
-checksum: 1-3:8a64a3f7
-```
-
-If anything changed since the read — concurrent edits, model
-hallucination, stale context — the edit is rejected before any bytes
-hit disk. Three layers of protection:
-
-| Layer | What it catches |
-|-------|----------------|
-| Per-line hash | Changed content at edit boundaries |
-| Range checksum | Any change within the read window |
-| mtime guard | Concurrent modification by another process |
+file's actual content. If anything changed (concurrent edits, model
+hallucination, stale context) the edit is rejected before any bytes hit
+disk.
 
 No more silent corruption. No more ambiguous string matches.
 
-### Batch edits in one call
-
-The built-in `Edit` handles one replacement per call. `trueline_edit`
-accepts an array of edits applied atomically, cutting tool-call
-overhead for multi-site changes.
-
-## Workflow
-
-```
-trueline_outline (navigate)
-    → trueline_read (targeted ranges)
-    → trueline_diff (preview) [optional]
-    → trueline_edit (apply)
-```
-
-A `SessionStart` hook injects instructions directing the agent to use
-trueline tools. A `PreToolUse` hook blocks the built-in `Edit` tool and
-redirects to the trueline workflow. On other platforms, equivalent hooks
-are available via the `trueline-hook` CLI dispatcher — see
-[INSTALL.md](INSTALL.md).
-
-## Path access
-
-By default, trueline tools can access files inside the project directory.
-When running under Claude Code, `~/.claude/` is also allowed (it stores
-plans, memory, and settings). To allow additional directories on any
-platform, set `TRUELINE_ALLOWED_DIRS` to a colon-separated list of paths
-(semicolon-separated on Windows).
-
-## Runtime Engine Selection
-
-trueline runs on Bun, Deno, and Node.js. It will use whichever runtime is
-available on your system, but the choice matters for performance. Bun is the
-fastest by a comfortable margin, followed by Deno, with Node.js coming in last.
-If you have the option, install [Bun](https://bun.sh) — you'll notice the
-difference on large files and batch edits.
-
-## Benchmarks
-
-Measured on Apple M4 Max (48 GB) with Bun 1.3.9. Edit times include a
-fresh range-read for checksum verification.
-
-| File size | Read (full) | Read (100 lines) | Edit (11-line replace) |
-|-----------|-------------|-------------------|------------------------|
-| 10 KB / 100 lines | 0.4 ms | 0.3 ms | 0.6 ms |
-| 100 KB / 1K lines | 1.3 ms | 0.5 ms | 1.9 ms |
-| 1 MB / 10K lines | 2.1 ms | 3.7 ms | 15.4 ms |
-| 5 MB / 50K lines | 2.1 ms | 17.8 ms | 75.5 ms |
-| 10 MB / 100K lines | 2.2 ms | 37.7 ms | 152 ms |
+## Design
 
-Full reads cap at ~2 ms for files above 1 MB because the 2,000-line output
-limit triggers early truncation. Range reads and edits scale linearly with
-file size since they stream the entire file.
+See [DESIGN.md](DESIGN.md) for the protocol specification, hash
+algorithm details, streaming architecture, and security model.
 
 ## Development
 

package/dist/server.js

@@ -9391,7 +9391,7 @@ ${JSON.stringify(symbolNames, null, 2)}`);
 });
 
 // src/server.ts
-import { mkdir, realpath as realpath2 } from "node:fs/promises";
+import { mkdir as mkdir2, realpath as realpath3 } from "node:fs/promises";
 import { homedir as homedir2 } from "node:os";
 import { delimiter, join as join2 } from "node:path";
 
@@ -22353,7 +22353,7 @@ class StdioServerTransport {
 // package.json
 var package_default = {
   name: "trueline-mcp",
-  version: "2.2.0",
+  version: "2.4.0",
   type: "module",
   description: "Truth-verified file editing for AI coding agents via MCP",
   license: "Apache-2.0",
@@ -22396,7 +22396,8 @@ var package_default = {
     typecheck: "bun x tsc --noEmit",
     test: "bun test",
     lint: "bunx biome ci .",
-    "lint:fix": "bunx biome check --write ."
+    "lint:fix": "bunx biome check --write .",
+    benchmark: "bun run benchmarks/token-benchmark.ts"
   },
   dependencies: {
     "@modelcontextprotocol/sdk": "^1.26.0",
@@ -23399,6 +23400,7 @@ function editSummary(ops) {
 // src/tools/read.ts
 async function handleRead(params) {
   const { file_path, start_line, end_line, projectDir, allowedDirs } = params;
+  const includeHashes = params.hashes !== false;
   const validated = await validatePath(file_path, "Read", projectDir, allowedDirs);
   if (!validated.ok)
     return validated.error;
@@ -23469,7 +23471,7 @@ checksum: ${formatChecksum(rangeFirstLine, rangeLastLine, rangeChecksumHash)}
       if (rangeFirstLine === 0)
         rangeFirstLine = lineNumber;
       const h = fnv1aHashBytes(lineBytes, 0, lineBytes.length);
-      const prefix = Buffer.from(`${lineNumber}:${hashToLetters(h)}|`);
+      const prefix = includeHashes ? Buffer.from(`${lineNumber}:${hashToLetters(h)}|`) : Buffer.from(`${lineNumber}|`);
       const lineLen = prefix.length + lineBytes.length + 1;
       outputLines++;
       if (outputLines > MAX_OUTPUT_LINES || outputLen + lineLen > MAX_OUTPUT_BYTES) {
@@ -23559,9 +23561,24 @@ async function extractOutline(source, config2) {
   const lines = source.split(`
 `);
   const entries = [];
-  function firstLine(node) {
-    const line = lines[node.startPosition.row]?.trimEnd() ?? "";
-    return line.length > 150 ? `${line.slice(0, 147)}...` : line;
+  function extractSignature(node) {
+    const startRow = node.startPosition.row;
+    const endRow = node.endPosition.row;
+    const fl = lines[startRow]?.trimEnd() ?? "";
+    if (startRow === endRow || fl.includes("{")) {
+      return fl.length > 200 ? `${fl.slice(0, 197)}...` : fl;
+    }
+    const parts2 = [fl.trimEnd()];
+    for (let row = startRow + 1;row <= Math.min(endRow, startRow + 20); row++) {
+      const line = (lines[row] ?? "").trimEnd();
+      parts2.push(line.trim());
+      if (line.includes("{"))
+        break;
+    }
+    let sig = parts2.join(" ").replace(/\s+/g, " ").replace(/\(\s+/g, "(").replace(/,\s*\)/g, ")").replace(/\s*\{\s*$/, "");
+    if (sig.length > 200)
+      sig = `${sig.slice(0, 197)}...`;
+    return sig;
   }
   let skipStart = -1;
   let skipEnd = -1;
@@ -23621,7 +23638,7 @@ async function extractOutline(source, config2) {
         endLine: node.endPosition.row + 1,
         depth,
         nodeType: node.type,
-        text: firstLine(node)
+        text: extractSignature(node)
       });
       for (const child of node.children) {
         if (!child.isNamed)
@@ -23952,8 +23969,149 @@ async function handleOutline(params) {
   }
 }
 
+// src/tools/search.ts
+async function handleSearch(params) {
+  const { file_path, pattern, projectDir, allowedDirs } = params;
+  const contextLines = params.context_lines ?? 2;
+  const maxMatches = params.max_matches ?? 10;
+  const validated = await validatePath(file_path, "Read", projectDir, allowedDirs);
+  if (!validated.ok)
+    return validated.error;
+  let regex;
+  try {
+    regex = new RegExp(pattern);
+  } catch {
+    return errorResult(`Invalid regex pattern: "${pattern}"`);
+  }
+  const { resolvedPath } = validated;
+  const allLines = [];
+  const matchIndices = [];
+  try {
+    for await (const { lineBytes, lineNumber } of splitLines(resolvedPath, { detectBinary: true })) {
+      const h = fnv1aHashBytes(lineBytes, 0, lineBytes.length);
+      const text = lineBytes.toString("utf-8");
+      const isMatch = regex.test(text);
+      allLines.push({ lineNumber, content: lineBytes, hash: h, isMatch });
+      if (isMatch)
+        matchIndices.push(allLines.length - 1);
+    }
+  } catch (err2) {
+    if (err2 instanceof Error && err2.message.includes("binary")) {
+      return errorResult(`"${file_path}" appears to be a binary file`);
+    }
+    throw err2;
+  }
+  if (matchIndices.length === 0) {
+    return textResult(`No matches for pattern "${pattern}" in ${file_path}`);
+  }
+  const totalMatches = matchIndices.length;
+  const cappedIndices = matchIndices.slice(0, maxMatches);
+  const ranges = [];
+  for (const idx of cappedIndices) {
+    const start2 = Math.max(0, idx - contextLines);
+    const end = Math.min(allLines.length - 1, idx + contextLines);
+    if (ranges.length > 0 && start2 <= ranges[ranges.length - 1].end + 1) {
+      ranges[ranges.length - 1].end = end;
+    } else {
+      ranges.push({ start: start2, end });
+    }
+  }
+  const parts2 = [];
+  for (let i2 = 0;i2 < ranges.length; i2++) {
+    const range = ranges[i2];
+    let checksumHash = FNV_OFFSET_BASIS;
+    let firstLine = 0;
+    let lastLine = 0;
+    if (i2 > 0)
+      parts2.push("");
+    for (let idx = range.start;idx <= range.end; idx++) {
+      const line = allLines[idx];
+      if (firstLine === 0)
+        firstLine = line.lineNumber;
+      lastLine = line.lineNumber;
+      checksumHash = foldHash(checksumHash, line.hash);
+      const marker = line.isMatch ? "  ← match" : "";
+      parts2.push(`${line.lineNumber}:${hashToLetters(line.hash)}|${line.content.toString("utf-8")}${marker}`);
+    }
+    parts2.push("");
+    parts2.push(`checksum: ${formatChecksum(firstLine, lastLine, checksumHash)}`);
+  }
+  if (totalMatches > maxMatches) {
+    parts2.push("");
+    parts2.push(`(showing ${maxMatches} of ${totalMatches} matches — increase max_matches to see more)`);
+  }
+  return textResult(parts2.join(`
+`));
+}
+
+// src/tools/write.ts
+import { dirname as dirname3, resolve as resolve5, sep as sep2 } from "node:path";
+import { mkdir, realpath as realpath2, stat as stat4, writeFile } from "node:fs/promises";
+async function validateWritePath(file_path, projectDir, allowedDirs = []) {
+  const resolvedPath = file_path.startsWith("/") ? file_path : resolve5(projectDir ?? process.cwd(), file_path);
+  let realPath;
+  let exists = false;
+  try {
+    realPath = await realpath2(resolvedPath);
+    exists = true;
+    const fileStat = await stat4(realPath);
+    if (!fileStat.isFile()) {
+      return { ok: false, error: errorResult(`"${file_path}" is not a regular file`) };
+    }
+  } catch {
+    realPath = resolvedPath;
+    let ancestor = dirname3(resolvedPath);
+    let realAncestor;
+    while (ancestor !== dirname3(ancestor)) {
+      try {
+        realAncestor = await realpath2(ancestor);
+        break;
+      } catch {
+        ancestor = dirname3(ancestor);
+      }
+    }
+    if (!realAncestor) {
+      return { ok: false, error: errorResult(`No accessible ancestor directory for "${file_path}"`) };
+    }
+    const tail = resolvedPath.slice(ancestor.length);
+    realPath = realAncestor + tail;
+  }
+  let realBase;
+  try {
+    realBase = await realpath2(projectDir ? projectDir : process.cwd());
+  } catch {
+    return { ok: false, error: errorResult("Project directory not found or inaccessible") };
+  }
+  const resolvedAllowed = await Promise.all(allowedDirs.map((d) => realpath2(d).catch(() => d)));
+  const allBases = [realBase, ...resolvedAllowed];
+  const isContained = allBases.some((base) => realPath === base || realPath.startsWith(base + sep2));
+  if (!isContained) {
+    return { ok: false, error: errorResult(`Access denied: "${file_path}" is outside the project directory`) };
+  }
+  return { ok: true, resolvedPath: realPath, exists };
+}
+async function handleWrite(params) {
+  const { file_path, content, projectDir, allowedDirs } = params;
+  const createDirs = params.create_directories !== false;
+  const validated = await validateWritePath(file_path, projectDir, allowedDirs);
+  if (!validated.ok)
+    return validated.error;
+  const { resolvedPath } = validated;
+  if (createDirs) {
+    await mkdir(dirname3(resolvedPath), { recursive: true });
+  }
+  await writeFile(resolvedPath, content, "utf-8");
+  const readResult = await handleRead({ file_path: resolvedPath, projectDir, allowedDirs });
+  const checksumMatch = readResult.content[0].text.match(/checksum: (\S+)/);
+  const checksum = checksumMatch ? checksumMatch[1] : "0-0:00000000";
+  const verb = validated.exists ? "overwritten" : "created";
+  return textResult(`File ${verb}: ${file_path}
+
+checksum: ${checksum}`);
+}
+
 // src/update-check.ts
-import { readFile as readFile2, writeFile } from "node:fs/promises";
+import { readFile as readFile2, writeFile as writeFile2 } from "node:fs/promises";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
 var PACKAGE_NAME = "trueline-mcp";
@@ -23969,7 +24127,7 @@ async function readCache() {
   }
 }
 async function writeCache(entry) {
-  await writeFile(CACHE_FILE, JSON.stringify(entry)).catch(() => {});
+  await writeFile2(CACHE_FILE, JSON.stringify(entry)).catch(() => {});
 }
 async function fetchLatestVersion() {
   try {
@@ -24028,20 +24186,20 @@ var server = new McpServer({
   version: VERSION2
 });
 var rawProjectDir = process.env.CLAUDE_PROJECT_DIR ?? process.cwd();
-var projectDir = await realpath2(rawProjectDir).catch(() => rawProjectDir);
+var projectDir = await realpath3(rawProjectDir).catch(() => rawProjectDir);
 async function resolveAllowedDirs() {
   const dirs = [];
   if (process.env.CLAUDE_PROJECT_DIR) {
     const claudeDir = join2(homedir2(), ".claude");
-    await mkdir(claudeDir, { recursive: true }).catch(() => {});
-    const realClaudeDir = await realpath2(claudeDir).catch(() => null);
+    await mkdir2(claudeDir, { recursive: true }).catch(() => {});
+    const realClaudeDir = await realpath3(claudeDir).catch(() => null);
     if (realClaudeDir)
       dirs.push(realClaudeDir);
   }
   const extra = process.env.TRUELINE_ALLOWED_DIRS;
   if (extra) {
     for (const raw of extra.split(delimiter).filter(Boolean)) {
-      const resolved = await realpath2(raw).catch(() => null);
+      const resolved = await realpath3(raw).catch(() => null);
       if (resolved)
         dirs.push(resolved);
     }
@@ -24057,7 +24215,8 @@ server.registerTool("trueline_read", {
       start: exports_external.number().int().positive().describe("First line to read (1-based).").optional(),
       end: exports_external.number().int().positive().describe("Last line to read (1-based, inclusive).").optional()
     })).describe("Line ranges to read. Omit to read the whole file. Example: [{start: 10, end: 25}] or [{start: 1, end: 50}, {start: 200, end: 220}] for disjoint ranges. Each range gets its own checksum.")).optional(),
-    encoding: exports_external.string().describe("File encoding. Defaults to utf-8. Supported: utf-8, ascii, latin1.").optional()
+    encoding: exports_external.string().describe("File encoding. Defaults to utf-8. Supported: utf-8, ascii, latin1.").optional(),
+    hashes: exports_external.boolean().describe("Include per-line hashes in output. Defaults to true. Set to false for exploratory reads where you don't plan to edit — saves tokens. Checksums are always included.").optional()
   })
 }, async (params) => {
   return handleRead({ ...params, projectDir, allowedDirs });
@@ -24098,6 +24257,27 @@ server.registerTool("trueline_outline", {
 }, async (params) => {
   return handleOutline({ ...params, projectDir, allowedDirs });
 });
+server.registerTool("trueline_search", {
+  description: "Search a file by regex pattern. Returns matching lines with context, per-line hashes, and checksums — " + "ready for immediate editing. Use instead of outline+read when you know what pattern to look for.",
+  inputSchema: exports_external.object({
+    file_path: exports_external.string(),
+    pattern: exports_external.string().describe("Regex pattern to search for (line-by-line matching)."),
+    context_lines: exports_external.number().int().min(0).describe("Lines of context above/below each match. Default: 2.").optional(),
+    max_matches: exports_external.number().int().positive().describe("Maximum number of matches to return. Default: 10.").optional()
+  })
+}, async (params) => {
+  return handleSearch({ ...params, projectDir, allowedDirs });
+});
+server.registerTool("trueline_write", {
+  description: "Create or overwrite a file. Returns a checksum of the written content for verification. " + "To edit afterward, call trueline_read first to get per-line hashes.",
+  inputSchema: exports_external.object({
+    file_path: exports_external.string(),
+    content: exports_external.string().describe("The full file content to write."),
+    create_directories: exports_external.boolean().describe("Create parent directories if they don't exist. Default: true.").optional()
+  })
+}, async (params) => {
+  return handleWrite({ ...params, projectDir, allowedDirs });
+});
 var transport = new StdioServerTransport;
 try {
   await server.connect(transport);

package/hooks/core/instructions.js

@@ -11,6 +11,9 @@ const PLATFORM_RULES = {
     readAdvice:
       "Never use the built-in Read tool \u2014 use trueline_read instead. " +
       "trueline_read returns per-line hashes and checksums needed for trueline_edit.",
+    writeAdvice:
+      "Never use the built-in Write tool for files in the project directory \u2014 use trueline_write instead. " +
+      "trueline_write returns a checksum for verification. To edit afterward, call trueline_read first.",
     subagentRule: true,
   },
   "gemini-cli": {
@@ -18,6 +21,9 @@ const PLATFORM_RULES = {
     readAdvice:
       "Never use read_file or read_many_files \u2014 use trueline_read instead. " +
       "trueline_read returns per-line hashes and checksums needed for trueline_edit.",
+    writeAdvice:
+      "Never use write_file for files in the project directory \u2014 use trueline_write instead. " +
+      "trueline_write returns a checksum for verification. To edit afterward, call trueline_read first.",
     subagentRule: false,
   },
   "vscode-copilot": {
@@ -25,6 +31,9 @@ const PLATFORM_RULES = {
     readAdvice:
       "Never use the built-in Read tool \u2014 use trueline_read instead. " +
       "trueline_read returns per-line hashes and checksums needed for trueline_edit.",
+    writeAdvice:
+      "Never use the built-in Write tool for files in the project directory \u2014 use trueline_write instead. " +
+      "trueline_write returns a checksum for verification. To edit afterward, call trueline_read first.",
     subagentRule: false,
   },
   opencode: {
@@ -32,6 +41,9 @@ const PLATFORM_RULES = {
     readAdvice:
       "Never use the built-in view tool \u2014 use trueline_read instead. " +
       "trueline_read returns per-line hashes and checksums needed for trueline_edit.",
+    writeAdvice:
+      "Never use the built-in write tool for files in the project directory \u2014 use trueline_write instead. " +
+      "trueline_write returns a checksum for verification. To edit afterward, call trueline_read first.",
     subagentRule: false,
   },
   codex: {
@@ -39,6 +51,9 @@ const PLATFORM_RULES = {
     readAdvice:
       "Never use read_file or shell with cat/head/tail \u2014 use trueline_read instead. " +
       "trueline_read returns per-line hashes and checksums needed for trueline_edit.",
+    writeAdvice:
+      "Never use shell with echo/cat redirection for files in the project directory \u2014 use trueline_write instead. " +
+      "trueline_write returns a checksum for verification. To edit afterward, call trueline_read first.",
     subagentRule: false,
   },
 };
@@ -58,17 +73,22 @@ export function getInstructions(platform = "claude-code") {
 
   return `<trueline_mcp_instructions>
   <tools>
-    <tool name="trueline_read">Read a file; returns per-line hashes and a checksum per range. Supports multiple disjoint ranges in one call. Call before editing.</tool>
+    <tool name="trueline_read">Read a file; returns per-line hashes and a checksum per range. Supports multiple disjoint ranges in one call. Call before editing. Pass hashes=false for exploratory reads where you don't plan to edit — saves tokens while keeping checksums.</tool>
     <tool name="trueline_edit">Edit a file with hash verification. Replaces the built-in Edit tool, which is blocked. Each edit needs: checksum (from trueline_read for the covering range), range (startLine:hash..endLine:hash or +startLine:hash for insert-after), content (replacement lines as newline-separated string; empty string to delete). Pass all changes to the same file in the edits array.</tool>
     <tool name="trueline_diff">Preview edits as a unified diff without writing to disk.</tool>
     <tool name="trueline_outline">Get a compact structural outline of a source file (functions, classes, types, etc.) without reading full content. Often sufficient on its own for navigation and understanding. Use before trueline_read to identify the right line ranges when you do need to read.</tool>
+    <tool name="trueline_search">Search a file by regex. Returns matching lines with surrounding context, per-line hashes, and checksums \u2014 output is edit-ready (pass checksums directly to trueline_edit). Preferred over Grep for single-file searches because results include hashes for immediate editing. Preferred over outline+read when you know a pattern to search for.</tool>
+    <tool name="trueline_write">Create or overwrite a file. Returns a checksum for verification. To edit afterward, call trueline_read first to get per-line hashes. Use instead of the built-in Write tool for files in the project directory.</tool>
   </tools>
-  <workflow>trueline_outline (navigate / understand) \u2192 trueline_read (targeted ranges, only if needed) \u2192 trueline_diff (optional) \u2192 trueline_edit</workflow>
+  <workflow>trueline_outline (navigate / understand) → trueline_read (targeted ranges, only if needed) → trueline_diff (optional) → trueline_edit</workflow>
+  <workflow>trueline_search (find + read in one step) → trueline_edit (edit directly from search results, no re-read needed)</workflow>
   <rules>${editRule}
-    <rule>${rules.readAdvice}</rule>${subagentRule}
+    <rule>${rules.readAdvice}</rule>
+    <rule>${rules.writeAdvice}</rule>${subagentRule}
     <rule>trueline_outline is often enough by itself for questions about file structure, purpose, or navigation. Only call trueline_read when you actually need the source code (e.g. to edit, debug, or understand implementation details).</rule>
     <rule>After using trueline_outline, if you do need to read, use its line numbers to read only the specific ranges you need \u2014 do NOT read the entire file.</rule>
     <rule>Only read a full file (no ranges) when you have not used trueline_outline and the file is short, or you genuinely need every line.</rule>
-  </rules>
+    <rule>When you need to find a pattern in a specific file (e.g. to locate code before editing, find usages within a file, or search for a string), use trueline_search instead of Grep or outline+read. trueline_search returns hashes and checksums so you can edit immediately without a separate trueline_read call.</rule>
+    <rule>When you need to find a pattern across many files, use Grep to identify the files, then use trueline_search on individual files you need to edit.</rule>
 </trueline_mcp_instructions>`;
 }

package/hooks/core/routing.js

@@ -6,12 +6,15 @@
 // block/approve decisions. Returns normalized {action, reason} objects
 // that platform-specific formatters translate to the right JSON shape.
 
+import { stat } from "node:fs/promises";
+
 // Maps platform-specific built-in tool names to canonical names.
 const TOOL_ALIASES = {
   // Gemini CLI
   read_file: "Read",
   read_many_files: "Read",
   edit_file: "Edit",
+  write_file: "Write",
   run_shell_command: "Bash",
   // OpenCode
   view: "Read",
@@ -88,5 +91,30 @@ export async function routePreToolUse(toolName, toolInput, canAccessFn) {
     return null;
   }
 
+  if (canonical === "Write") {
+    if (typeof filePath === "string") {
+      const canWrite = await canAccessFn(filePath, "Edit");
+      if (canWrite) {
+        // Fall through to built-in Write for non-regular files (directories,
+        // devices, etc.) that trueline_write would reject.
+        try {
+          const s = await stat(filePath);
+          if (!s.isFile()) return null;
+        } catch {
+          // File doesn't exist yet — trueline_write can handle creation.
+        }
+        return {
+          action: "block",
+          reason:
+            "<trueline_redirect>" +
+            "Use trueline_write instead of Write for files in the project directory. " +
+            "trueline_write returns a checksum for verification." +
+            "</trueline_redirect>",
+        };
+      }
+    }
+    return null;
+  }
+
   return null;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trueline-mcp",
-  "version": "2.2.0",
+  "version": "2.4.0",
   "type": "module",
   "description": "Truth-verified file editing for AI coding agents via MCP",
   "license": "Apache-2.0",
@@ -43,7 +43,8 @@
     "typecheck": "bun x tsc --noEmit",
     "test": "bun test",
     "lint": "bunx biome ci .",
-    "lint:fix": "bunx biome check --write ."
+    "lint:fix": "bunx biome check --write .",
+    "benchmark": "bun run benchmarks/token-benchmark.ts"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.26.0",