@yanzc/claude-pro 0.0.0-stage → 0.4.1

package/src/tools/bash.js

@@ -0,0 +1,227 @@
+// Bash tool plus background shell management (BashOutput / KillShell).
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { findShell, killTree, spawnShell, watchShell } from '../utils/shell.js';
+import { stripAnsi } from '../ui/ansi.js';
+import { toolResultsDir } from '../session.js';
+
+const background = new Map(); // id -> {child, command, output, readPos, status, exitCode, startedAt}
+let bgCounter = 0;
+
+function truncateOutput(text, max) {
+  if (text.length <= max) return text;
+  const head = text.slice(0, Math.floor(max * 0.4));
+  const tail = text.slice(-Math.floor(max * 0.6));
+  const dropped = text.slice(head.length, text.length - tail.length).split('\n').length;
+  return `${head}\n\n... [${dropped} lines truncated] ...\n\n${tail}`;
+}
+
+// Keep the full text of truncated output so the model can still get at it.
+function saveFullOutput(root, text) {
+  try {
+    const dir = toolResultsDir(root);
+    fs.mkdirSync(dir, { recursive: true });
+    const file = path.join(dir, `bash-${Date.now()}-${Math.random().toString(36).slice(2, 8)}.txt`);
+    fs.writeFileSync(file, text);
+    return file;
+  } catch {
+    return null;
+  }
+}
+
+// Append to a background shell's buffer. Past `max` characters only the newest `keep` are kept, and
+// `readPos` moves back by what was removed so it still marks the text the model has already read.
+export function appendOutput(bg, text, max = 5_000_000, keep = 2_000_000) {
+  bg.output += text;
+  if (bg.output.length > max) {
+    const cut = bg.output.length - keep;
+    bg.output = bg.output.slice(cut);
+    bg.readPos = Math.max(0, bg.readPos - cut);
+  }
+}
+
+function childEnv() {
+  const env = { ...process.env };
+  // Keep child processes non-interactive and colour free.
+  Object.assign(env, { GIT_EDITOR: 'true', GIT_PAGER: 'cat', PAGER: 'cat', NO_COLOR: '1', CLAUDE_PRO: '1' });
+  delete env.FORCE_COLOR;
+  // What commands run from here start must not believe they are a restartable session of this program.
+  for (const key of ['CLAUDE_PRO_SUPERVISED', 'CLAUDE_PRO_RESTART_FILE', 'CLAUDE_PRO_RESTARTED']) delete env[key];
+  return env;
+}
+
+export function shutdownBackgroundShells() {
+  for (const bg of background.values()) if (bg.status === 'running') killTree(bg.child);
+}
+
+export function listBackgroundShells() {
+  return [...background.entries()].map(([id, bg]) => ({ id, command: bg.command, status: bg.status, exitCode: bg.exitCode }));
+}
+
+export function makeBashTool(config) {
+  const shell = findShell(config);
+  const isCmd = shell.kind === 'cmd';
+  return {
+    name: 'Bash',
+    description: `Executes a given ${isCmd ? 'cmd.exe' : 'bash'} command with an optional timeout. The working directory persists between commands; shell state (variables, functions) does not.
+
+IMPORTANT: This tool is for terminal operations like git, npm, docker, running builds and tests. DO NOT use it for file operations (reading, writing, editing, searching, finding files) - use the specialized tools for this instead.
+
+Before executing the command:
+1. If the command will create new directories or files, first verify the parent directory exists (e.g. with ls).
+2. Always quote file paths that contain spaces with double quotes.
+
+Usage notes:
+- The command argument is required.
+- You can specify an optional timeout in milliseconds (up to ${config.bashMaxTimeout}ms / ${config.bashMaxTimeout / 60000} minutes). Default is ${config.bashDefaultTimeout}ms.
+- Write a clear, concise description of what the command does in 5-10 words.
+- If the output exceeds ${config.bashMaxOutput} characters, the middle is cut from what is returned to you, and the full output is saved to a file whose path is included so you can read it with Read or Grep.
+- You can use the \`run_in_background\` parameter to run the command in the background (dev servers, watchers, long builds). Use BashOutput to read its output later and KillShell to stop it. Never use \`&\` at the end of the command for this.
+- Commands run non-interactively: stdin is closed unless you pass the \`stdin\` parameter, whose text is fed to the command (answers to prompts, data for a script, a heredoc-free way to pipe input). Do not run commands that wait for keyboard interaction (use flags like --yes, and avoid interactive editors, \`git rebase -i\`, \`git add -i\`).
+- Avoid using search/read commands like \`find\`, \`grep\`, \`cat\`, \`head\`, \`tail\`, \`sed\`, \`awk\`, or \`echo\` for file work; use Glob, Grep, Read, Edit and Write instead.
+- When issuing multiple commands: if they are independent, make multiple Bash tool calls in parallel in a single message; if they depend on each other, chain them with '&&'.
+- Try to maintain your current working directory by using absolute paths and avoiding \`cd\`.${os.platform() === 'win32' && !isCmd ? '\n- This is Git Bash on Windows: use Unix syntax (forward slashes, /dev/null, $VAR). Windows paths like C:/Users/... also work.' : ''}
+
+# Committing changes with git
+Only create commits when requested by the user. When asked to commit: run git status, git diff and git log in parallel to understand the change and the repo's message style; stage only relevant files (never secrets such as .env); write a concise message focused on the "why"; pass the message via a HEREDOC. Do not force push, skip hooks (--no-verify), amend commits, change git config or push unless the user asked for that.`,
+    input_schema: {
+      type: 'object',
+      properties: {
+        command: { type: 'string', description: 'The command to execute' },
+        timeout: { type: 'number', description: `Optional timeout in milliseconds (max ${config.bashMaxTimeout})` },
+        description: { type: 'string', description: 'Clear, concise description of what this command does in 5-10 words, in active voice.' },
+        run_in_background: { type: 'boolean', description: 'Set to true to run this command in the background. Use BashOutput to read the output later.' },
+        stdin: { type: 'string', description: 'Optional text to feed to the command on standard input' },
+      },
+      required: ['command'],
+    },
+    summarize(input) { return input.command || ''; },
+    async call(input, ctx) {
+      const command = String(input.command || '').trim();
+      if (!command) return { isError: true, content: 'Empty command' };
+      const stdinText = typeof input.stdin === 'string' ? input.stdin : undefined;
+      const cwdFile = path.join(os.tmpdir(), `claude-pro-cwd-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+      let cwd = ctx.cwd;
+      if (!fs.existsSync(cwd)) cwd = ctx.projectRoot;
+
+      if (input.run_in_background) {
+        const child = spawnShell(shell, command, { cwd, env: childEnv(), stdin: stdinText });
+        const id = `bash_${++bgCounter}`;
+        const bg = { child, command, output: '', readPos: 0, status: 'running', exitCode: null, startedAt: Date.now() };
+        background.set(id, bg);
+        // Decode as a stream: a multi-byte character (CJK text) can be split between two chunks.
+        child.stdout.setEncoding('utf8');
+        child.stderr.setEncoding('utf8');
+        const onData = (d) => appendOutput(bg, stripAnsi(d));
+        child.stdout.on('data', onData);
+        child.stderr.on('data', onData);
+        child.on('close', (code) => { bg.status = bg.status === 'killed' ? 'killed' : 'completed'; bg.exitCode = code; });
+        child.on('error', (e) => { bg.status = 'failed'; bg.output += `\n${e.message}`; });
+        return { content: `Command running in background with ID: ${id}`, display: { summary: `Running in background (${id})` } };
+      }
+
+      const timeout = Math.min(Math.max(1000, input.timeout || config.bashDefaultTimeout), config.bashMaxTimeout);
+      return await new Promise((resolve, reject) => {
+        let output = '';
+        let timedOut = false;
+        let child;
+        try {
+          child = spawnShell(shell, command, { cwd, env: childEnv(), cwdFile, stdin: stdinText });
+        } catch (e) {
+          resolve({ isError: true, content: `Failed to start shell: ${e.message}` });
+          return;
+        }
+        const timer = setTimeout(() => { timedOut = true; killTree(child); }, timeout);
+        const onAbort = () => killTree(child);
+        ctx.signal?.addEventListener('abort', onAbort, { once: true });
+        const finish = (code, err) => {
+          clearTimeout(timer);
+          ctx.signal?.removeEventListener('abort', onAbort);
+          try {
+            const newCwd = fs.readFileSync(cwdFile, 'utf8').trim();
+            if (newCwd && fs.existsSync(newCwd)) ctx.setCwd(path.resolve(newCwd));
+          } catch { /* command may have exited early */ }
+          fs.rm(cwdFile, { force: true }, () => {});
+          if (ctx.signal?.aborted) {
+            reject(Object.assign(new Error('aborted'), { name: 'AbortError', partialOutput: output }));
+            return;
+          }
+          let text = stripAnsi(output).replace(/\r\n/g, '\n').replace(/\s+$/, '');
+          if (text.length > config.bashMaxOutput) {
+            const saved = saveFullOutput(ctx.projectRoot, text);
+            const size = text.length;
+            text = truncateOutput(text, config.bashMaxOutput);
+            if (saved) text += `\n\n(Output was ${size} characters and has been truncated. The full output is saved at ${saved}; use Read with offset/limit or Grep on that file to see the rest.)`;
+          }
+          if (err) text += `${text ? '\n' : ''}${err.message}`;
+          if (timedOut) text += `${text ? '\n' : ''}Command timed out after ${timeout}ms`;
+          const isError = timedOut || !!err || (code !== 0 && code !== null);
+          if (code && code !== 0 && !timedOut) text += `${text ? '\n' : ''}Exit code ${code}`;
+          resolve({ isError, content: text || '(no output)', display: { output: text, exitCode: code } });
+        };
+        watchShell(child, {
+          onOutput: (text) => {
+            output += text;
+            if (output.length > 10_000_000) output = output.slice(-5_000_000);
+            ctx.onProgress?.(stripAnsi(output));
+          },
+          done: finish,
+        });
+      });
+    },
+  };
+}
+
+export const BashOutputTool = {
+  name: 'BashOutput',
+  readOnly: true,
+  description: `Retrieves output from a running or completed background bash shell.
+- Takes a bash_id parameter identifying the shell
+- Always returns only new output since the last check, along with the shell status
+- Supports optional regex filtering to show only lines matching a pattern`,
+  input_schema: {
+    type: 'object',
+    properties: {
+      bash_id: { type: 'string', description: 'The ID of the background shell to retrieve output from' },
+      filter: { type: 'string', description: 'Optional regular expression to filter the output lines' },
+    },
+    required: ['bash_id'],
+  },
+  summarize(input) { return input.bash_id; },
+  async call(input) {
+    const bg = background.get(input.bash_id);
+    if (!bg) return { isError: true, content: `No background shell with id ${input.bash_id}. Known: ${[...background.keys()].join(', ') || 'none'}` };
+    let fresh = bg.output.slice(bg.readPos);
+    bg.readPos = bg.output.length;
+    if (input.filter) {
+      try {
+        const re = new RegExp(input.filter);
+        fresh = fresh.split('\n').filter((l) => re.test(l)).join('\n');
+      } catch (e) { return { isError: true, content: `Invalid filter regex: ${e.message}` }; }
+    }
+    fresh = truncateOutput(fresh.replace(/\r\n/g, '\n'), 30_000);
+    const status = `<status>${bg.status}</status>${bg.exitCode !== null ? `\n<exit_code>${bg.exitCode}</exit_code>` : ''}`;
+    return { content: `${status}\n<output>\n${fresh || '(no new output)'}\n</output>`, display: { summary: `${bg.status}${fresh ? `, ${fresh.split('\n').length} new lines` : ', no new output'}` } };
+  },
+};
+
+export const KillShellTool = {
+  name: 'KillShell',
+  description: 'Kills a running background bash shell by its ID.',
+  input_schema: {
+    type: 'object',
+    properties: { shell_id: { type: 'string', description: 'The ID of the background shell to kill' } },
+    required: ['shell_id'],
+  },
+  summarize(input) { return input.shell_id; },
+  async call(input) {
+    const bg = background.get(input.shell_id);
+    if (!bg) return { isError: true, content: `No background shell with id ${input.shell_id}` };
+    if (bg.status !== 'running') return { content: `Shell ${input.shell_id} is not running (status: ${bg.status})` };
+    bg.status = 'killed';
+    killTree(bg.child);
+    return { content: `Successfully killed shell: ${input.shell_id} (${bg.command})` };
+  },
+};

package/src/tools/effort.js

@@ -0,0 +1,41 @@
+// Effort: the model changes its own reasoning effort in the middle of a request, typically raising it for a hard
+// problem. The change lasts until the user's next message, which goes back to the effort the user chose.
+
+import { defaultEffort } from '../api.js';
+
+export const EFFORT_LEVELS = ['low', 'medium', 'high', 'xhigh', 'max'];
+
+export function makeEffortTool(config) {
+  return {
+    name: 'Effort',
+    description: `Change your own reasoning effort (output_config.effort) for the rest of the user's current request. From your next step on, every request uses the new level; at the user's next message it goes back to the level the user chose.
+
+Raise it when the task turns out to be hard and the current level is not enough: a bug you could not find after a couple of real attempts, a subtle concurrency or algorithmic problem, a design decision with many interacting constraints, a fix that keeps failing. Then work on with the higher level; do not ask the user first.
+
+Do not raise it for routine work, and do not switch back and forth: the prompt cache is kept per effort level, so each change makes the next request write the whole conversation to the cache again (a one-off cost about the size of the conversation). Lowering it is worth it only when the hard part is done and a long stretch of routine work remains.`,
+    input_schema: {
+      type: 'object',
+      properties: {
+        level: { type: 'string', enum: EFFORT_LEVELS, description: 'The new effort level' },
+        reason: { type: 'string', description: 'Why, in a few words. Shown to the user.' },
+      },
+      required: ['level', 'reason'],
+    },
+    summarize(input) { return `${input.level}${input.reason ? `: ${input.reason}` : ''}`; },
+    async call(input) {
+      const level = String(input.level || '').trim().toLowerCase();
+      if (!EFFORT_LEVELS.includes(level)) return { isError: true, content: `Unknown effort "${input.level}". Use one of: ${EFFORT_LEVELS.join(', ')}.` };
+      const shown = () => config.effort || defaultEffort(config.mainModel.id, config) || 'the model default';
+      const before = shown();
+      if (level === before) return { content: `The effort is already ${level}.` };
+      config.effortBoost = null;
+      const users = shown(); // the level the user chose, which the next message goes back to
+      config.effortBoost = level === users ? null : level;
+      if (!config.effortBoost) return { content: `Effort back to ${level}, the level the user chose.`, display: { summary: `Effort ${before} → ${level}` } };
+      return {
+        content: `Effort changed from ${before} to ${level} for the rest of this request; it goes back to ${users} at the user's next message.`,
+        display: { summary: `Effort ${before} → ${level}` },
+      };
+    },
+  };
+}

package/src/tools/files.js

@@ -0,0 +1,352 @@
+// Read, Write and Edit tools. Edits require that the file was read first and hasn't
+// changed on disk since, which prevents the model from clobbering changes it never saw.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { resolvePath, displayPath } from '../utils/paths.js';
+import { diffLines, makeHunks, countChanges, splitLines } from '../utils/diff.js';
+
+const MAX_LINES = 10_000;
+const MAX_LINE_CHARS = 20_000;
+const MAX_OUTPUT_CHARS = 400_000; // a read without offset/limit bigger than this is refused
+const HARD_MAX_CHARS = 400_000; // never return more than this in one read (about 100k tokens), even with an explicit limit
+const IMAGE_TYPES = { '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.gif': 'image/gif', '.webp': 'image/webp' };
+
+export function mtime(file) {
+  try { return fs.statSync(file).mtimeMs; } catch { return null; }
+}
+
+function isBinary(buf) {
+  const len = Math.min(buf.length, 8000);
+  for (let i = 0; i < len; i++) if (buf[i] === 0) return true;
+  return false;
+}
+
+// `crlf` is true when CRLF is the file's main line ending. Editing rewrites every line ending, so a
+// mostly-LF file with one stray CRLF must stay LF instead of being converted wholesale.
+function readText(file, buf = fs.readFileSync(file)) {
+  const raw = buf.toString('utf8');
+  const text = raw.charCodeAt(0) === 0xfeff ? raw.slice(1) : raw;
+  const crlfCount = (text.match(/\r\n/g) || []).length;
+  const bareLfCount = (text.match(/\n/g) || []).length - crlfCount;
+  return { text, bom: text !== raw, crlf: crlfCount > 0 && crlfCount >= bareLfCount };
+}
+
+export function numberLines(lines, start) {
+  return lines.map((l, i) => {
+    const line = l.length > MAX_LINE_CHARS ? l.slice(0, MAX_LINE_CHARS) + '… [line truncated]' : l;
+    return `${String(start + i).padStart(6)}\t${line}`;
+  }).join('\n');
+}
+
+function renderNotebook(json) {
+  const cells = json.cells || [];
+  return cells.map((cell, i) => {
+    const src = Array.isArray(cell.source) ? cell.source.join('') : (cell.source || '');
+    let out = `<cell id="${cell.id || i}" type="${cell.cell_type}">\n${src}\n</cell>`;
+    for (const o of cell.outputs || []) {
+      const text = o.text ? [].concat(o.text).join('') : o.data?.['text/plain'] ? [].concat(o.data['text/plain']).join('') : '';
+      if (text) out += `\n<output>\n${text.slice(0, 5000)}\n</output>`;
+    }
+    return out;
+  }).join('\n\n');
+}
+
+export const ReadTool = {
+  name: 'Read',
+  readOnly: true,
+  description: `Reads a file from the local filesystem. You can access any file directly by using this tool.
+Assume this tool is able to read all files on the machine. If the user provides a path to a file assume that path is valid. It is okay to read a file that does not exist; an error will be returned.
+
+Usage:
+- The file_path parameter should be an absolute path
+- By default, it reads up to ${MAX_LINES} lines starting from the beginning of the file
+- You can optionally specify a line offset and limit (especially handy for long files), but it's recommended to read the whole file by not providing these parameters
+- Any lines longer than ${MAX_LINE_CHARS} characters will be truncated
+- Results are returned using cat -n format, with line numbers starting at 1
+- This tool can read images (PNG, JPG, GIF, WEBP) and Jupyter notebooks (.ipynb)
+- This tool can only read files, not directories. To list a directory, use ls via the Bash tool.
+- You can call multiple tools in a single response. It is always better to speculatively read multiple potentially useful files in parallel.
+- If you read a file that exists but has empty contents you will receive a warning in place of file contents.`,
+  input_schema: {
+    type: 'object',
+    properties: {
+      file_path: { type: 'string', description: 'The absolute path to the file to read' },
+      offset: { type: 'number', description: 'The line number to start reading from. Only provide if the file is too large to read at once' },
+      limit: { type: 'number', description: 'The number of lines to read. Only provide if the file is too large to read at once.' },
+    },
+    required: ['file_path'],
+  },
+  summarize(input, ctx) {
+    const p = displayPath(resolvePath(input.file_path, ctx.cwd), ctx.cwd);
+    return input.offset || input.limit ? `${p}, lines ${input.offset || 1}-${(input.offset || 1) + (input.limit || MAX_LINES) - 1}` : p;
+  },
+  filePath(input, ctx) { return resolvePath(input.file_path, ctx.cwd); },
+  async call(input, ctx) {
+    const file = resolvePath(input.file_path, ctx.cwd);
+    let stat;
+    try { stat = fs.statSync(file); } catch {
+      return { isError: true, content: `File does not exist: ${file}` };
+    }
+    if (stat.isDirectory()) return { isError: true, content: `EISDIR: ${file} is a directory. Use the Bash tool with ls to list directories.` };
+    const ext = path.extname(file).toLowerCase();
+
+    if (IMAGE_TYPES[ext]) {
+      if (stat.size > 5 * 1024 * 1024) return { isError: true, content: `Image too large (${Math.round(stat.size / 1024)}KB, max 5MB).` };
+      const data = fs.readFileSync(file).toString('base64');
+      ctx.fileState.set(file, { mtimeMs: stat.mtimeMs });
+      return {
+        content: [{ type: 'image', source: { type: 'base64', media_type: IMAGE_TYPES[ext], data } }],
+        display: { summary: `Read image (${Math.round(stat.size / 1024)}KB)` },
+      };
+    }
+    if (ext === '.ipynb') {
+      try {
+        const nb = JSON.parse(fs.readFileSync(file, 'utf8'));
+        ctx.fileState.set(file, { mtimeMs: stat.mtimeMs });
+        return { content: renderNotebook(nb), display: { summary: `Read ${(nb.cells || []).length} cells` } };
+      } catch (e) {
+        return { isError: true, content: `Could not parse notebook: ${e.message}` };
+      }
+    }
+    const buf = fs.readFileSync(file);
+    if (isBinary(buf)) return { isError: true, content: `This appears to be a binary file (${stat.size} bytes) and cannot be displayed as text.` };
+
+    const { text } = readText(file, buf);
+    const lines = splitLines(text);
+    // `partial` records that part of the file was not shown, so Write can refuse to overwrite it.
+    const seen = (partial) => ctx.fileState.set(file, { mtimeMs: stat.mtimeMs, partial });
+    if (lines.length === 0) {
+      seen(false);
+      return { content: '<system-reminder>Warning: the file exists but the contents are empty.</system-reminder>', display: { summary: 'Read 0 lines (empty file)' } };
+    }
+    const start = Math.max(1, Math.floor(input.offset || 1));
+    if (start > lines.length) {
+      seen(true);
+      return { content: `<system-reminder>Warning: the file exists but is shorter than the provided offset (${start}). The file has ${lines.length} lines.</system-reminder>`, display: { summary: 'Read 0 lines' } };
+    }
+    const limit = Math.max(1, Math.floor(input.limit || MAX_LINES));
+    const slice = lines.slice(start - 1, start - 1 + limit);
+    let content = numberLines(slice, start);
+    if (content.length > MAX_OUTPUT_CHARS && !input.limit) {
+      return { isError: true, content: `File content (${Math.round(content.length / 1024)}KB) exceeds the maximum allowed size. Use the offset and limit parameters to read specific portions of the file, or use the Grep tool to search for specific content.` };
+    }
+    let cut = false;
+    let end = start + slice.length - 1;
+    if (content.length > HARD_MAX_CHARS) {
+      const kept = content.slice(0, HARD_MAX_CHARS);
+      const whole = kept.endsWith('\n'); // the cut fell between two lines
+      end = start + (kept.match(/\n/g) || []).length - (whole ? 1 : 0); // the last line shown
+      content = `${kept}${whole ? '' : '\n'}… [output cut at ${HARD_MAX_CHARS} characters: line ${end} is the last one shown${whole ? '' : ', and only in part'}; read on from there with offset/limit]`;
+      cut = true;
+    }
+    seen(cut || start > 1 || end < lines.length);
+    if (end < lines.length) content += `\n\n(File has ${lines.length} lines total; showing lines ${start}-${end}. Use offset/limit to read more.)`;
+    return { content, display: { summary: `Read ${slice.length} line${slice.length === 1 ? '' : 's'}` } };
+  },
+};
+
+// Validate that a file may be written: it must have been read and be unchanged since. With
+// `full`, which Write needs because it replaces the whole file, the read must also have covered
+// all of it; Edit only replaces text it matched exactly, so a partial read is enough there.
+export function checkFreshness(file, ctx, { full = false } = {}) {
+  const state = ctx.fileState.get(file);
+  if (!state) return 'File has not been read yet. Read it first before writing to it.';
+  if (full && state.partial) {
+    return 'File was only partly read (offset/limit), so Write would overwrite content you have not seen. Read the whole file first, or use Edit for targeted changes.';
+  }
+  const now = mtime(file);
+  if (now !== null && state.mtimeMs !== undefined && Math.abs(now - state.mtimeMs) > 1) {
+    return 'File has been modified since it was last read, either by the user or by a linter. Read it again before attempting to write it.';
+  }
+  return null;
+}
+
+function writeText(file, text, { crlf, bom }) {
+  let out = text;
+  if (crlf) out = out.replace(/\r?\n/g, '\r\n');
+  if (bom) out = String.fromCharCode(0xfeff) + out;
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, out, 'utf8');
+}
+
+// Where the new text of an edit is, for its result: "lines 12-18", "line 12", or "text removed at line 12".
+// The result used to show a snippet of the file around the change; it repeated new_string, which the model has
+// just written, and stayed in the conversation to be re-read by every later request. The line numbers are what
+// it still needs (for a Read with offset/limit); Claude Code's Edit also answers with a short confirmation.
+function changedLines(line, newStr) {
+  if (!newStr) return `text removed at line ${line}`;
+  const count = newStr.split('\n').length - (newStr.endsWith('\n') ? 1 : 0);
+  return count > 1 ? `lines ${line}-${line + count - 1}` : `line ${line}`;
+}
+
+export const WriteTool = {
+  name: 'Write',
+  editsFiles: true,
+  description: `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 editing an existing file when that is the natural place for a change, but create new files whenever the task needs them (code, tests, scripts, configs, data).
+- Do not create documentation files (*.md, READMEs) unless the user asks for them or the task clearly calls for one.
+- Only use emojis if the user explicitly requests it. Avoid writing emojis to files unless asked.`,
+  input_schema: {
+    type: 'object',
+    properties: {
+      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' },
+    },
+    required: ['file_path', 'content'],
+  },
+  summarize(input, ctx) { return displayPath(resolvePath(input.file_path, ctx.cwd), ctx.cwd); },
+  filePath(input, ctx) { return resolvePath(input.file_path, ctx.cwd); },
+  validate(input, ctx) {
+    if (typeof input.content !== 'string') return 'content must be a string';
+    const file = resolvePath(input.file_path, ctx.cwd);
+    if (fs.existsSync(file)) {
+      if (fs.statSync(file).isDirectory()) return `${file} is a directory`;
+      return checkFreshness(file, ctx, { full: true });
+    }
+    return null;
+  },
+  preview(input, ctx) {
+    const file = resolvePath(input.file_path, ctx.cwd);
+    const exists = fs.existsSync(file);
+    const newLines = splitLines(input.content);
+    if (!exists) return { kind: 'create', path: file, lines: newLines };
+    const ops = diffLines(splitLines(readText(file).text), newLines);
+    return { kind: 'diff', path: file, hunks: makeHunks(ops), ...countChanges(ops) };
+  },
+  async call(input, ctx) {
+    const err = this.validate(input, ctx);
+    if (err) return { isError: true, content: err };
+    const file = resolvePath(input.file_path, ctx.cwd);
+    const exists = fs.existsSync(file);
+    const prev = exists ? readText(file) : { text: '', crlf: false, bom: false };
+    const preview = this.preview(input, ctx);
+    writeText(file, input.content, prev);
+    ctx.fileState.set(file, { mtimeMs: mtime(file) });
+    const n = splitLines(input.content).length;
+    if (!exists) {
+      return {
+        content: `File created successfully at: ${file}`,
+        display: { summary: `Wrote ${n} line${n === 1 ? '' : 's'} to ${displayPath(file, ctx.cwd)}`, preview },
+      };
+    }
+    return {
+      content: `The file ${file} has been updated successfully.`,
+      display: { summary: changeSummary(preview), preview },
+    };
+  },
+};
+
+function changeSummary({ added, removed }) {
+  const parts = [];
+  if (added) parts.push(`${added} addition${added === 1 ? '' : 's'}`);
+  if (removed) parts.push(`${removed} removal${removed === 1 ? '' : 's'}`);
+  return parts.length ? `Updated with ${parts.join(' and ')}` : 'No changes';
+}
+
+// Apply old->new replacement to text. Returns {result, count, index} or {error}.
+export function applyEdit(text, oldStr, newStr, replaceAll) {
+  if (oldStr === newStr) return { error: 'No changes to make: old_string and new_string are exactly the same.' };
+  if (oldStr === '') {
+    if (text.length) return { error: 'Cannot use an empty old_string on a non-empty file. Use Write to replace the whole file.' };
+    return { result: newStr, count: 1, index: 0 };
+  }
+  let actualOld = oldStr;
+  let count = text.split(actualOld).length - 1;
+  if (count === 0) {
+    // Tolerate trailing whitespace differences at line ends.
+    const norm = (s) => s.replace(/[ \t]+\n/g, '\n');
+    if (norm(text).includes(norm(oldStr)) && norm(text) !== text) {
+      return { error: 'String to replace not found exactly (whitespace differs at line ends). Read the file again and copy the text exactly, including whitespace.' };
+    }
+    // Curly quote normalisation.
+    const straight = (s) => s.replace(/[‘’]/g, "'").replace(/[“”]/g, '"');
+    // Curly quotes are single UTF-16 units, so indices line up between the two forms.
+    const idx = straight(text).indexOf(straight(oldStr));
+    if (idx >= 0) {
+      actualOld = text.slice(idx, idx + oldStr.length);
+      count = text.split(actualOld).length - 1;
+    }
+  }
+  if (count === 0) return { error: `String to replace not found in file.\nString: ${oldStr}` };
+  if (count > 1 && !replaceAll) {
+    return { error: `Found ${count} matches of the string to replace, but replace_all is false. To replace all occurrences, set replace_all to true. To replace only one occurrence, please provide more context to uniquely identify the instance.\nString: ${oldStr}` };
+  }
+  const index = text.indexOf(actualOld);
+  const result = replaceAll ? text.split(actualOld).join(newStr) : text.slice(0, index) + newStr + text.slice(index + actualOld.length);
+  return { result, count, index };
+}
+
+export const EditTool = {
+  name: 'Edit',
+  editsFiles: true,
+  description: `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: spaces + line number + tab. Everything after that tab is the actual file content to match. Never include any part of the line number prefix in the old_string or new_string.
+- Prefer editing existing files when that is the natural place for a change; create new files whenever the task needs them.
+- 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. This parameter is useful if you want to rename a variable for instance.
+- To create a new file, pass an empty old_string with the full content as new_string (the file must not exist).`,
+  input_schema: {
+    type: 'object',
+    properties: {
+      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 (must be different from old_string)' },
+      replace_all: { type: 'boolean', default: false, description: 'Replace all occurrences of old_string (default false)' },
+    },
+    required: ['file_path', 'old_string', 'new_string'],
+  },
+  summarize(input, ctx) { return displayPath(resolvePath(input.file_path, ctx.cwd), ctx.cwd); },
+  filePath(input, ctx) { return resolvePath(input.file_path, ctx.cwd); },
+  // Compute the edit without writing. Returns {error} or {file, before, after, ...}.
+  plan(input, ctx) {
+    const file = resolvePath(input.file_path, ctx.cwd);
+    const oldStr = String(input.old_string ?? '').replace(/\r\n/g, '\n');
+    const newStr = String(input.new_string ?? '').replace(/\r\n/g, '\n');
+    if (!fs.existsSync(file)) {
+      if (oldStr !== '') return { error: `File does not exist: ${file}` };
+      return { file, created: true, before: '', after: newStr, meta: { crlf: false, bom: false } };
+    }
+    if (fs.statSync(file).isDirectory()) return { error: `${file} is a directory` };
+    const fresh = checkFreshness(file, ctx);
+    if (fresh) return { error: fresh };
+    const { text, crlf, bom } = readText(file);
+    const before = text.replace(/\r\n/g, '\n');
+    const r = applyEdit(before, oldStr, newStr, !!input.replace_all);
+    if (r.error) return { error: r.error };
+    return { file, before, after: r.result, index: r.index, count: r.count, meta: { crlf, bom }, newStr };
+  },
+  validate(input, ctx) { return this.plan(input, ctx).error || null; },
+  // `p` is an already computed plan, so call() does not read the file and redo the edit a second time.
+  preview(input, ctx, p = this.plan(input, ctx)) {
+    if (p.error) return null;
+    if (p.created) return { kind: 'create', path: p.file, lines: splitLines(p.after) };
+    const ops = diffLines(splitLines(p.before), splitLines(p.after));
+    return { kind: 'diff', path: p.file, hunks: makeHunks(ops), ...countChanges(ops) };
+  },
+  async call(input, ctx) {
+    const p = this.plan(input, ctx);
+    if (p.error) return { isError: true, content: p.error };
+    const preview = this.preview(input, ctx, p);
+    const prior = ctx.fileState.get(p.file);
+    writeText(p.file, p.after, p.meta);
+    // An edit does not show the rest of the file, so a partial read stays partial (a created file is all ours).
+    ctx.fileState.set(p.file, { mtimeMs: mtime(p.file), partial: !p.created && !!prior?.partial });
+    if (p.created) {
+      return { content: `File created successfully at: ${p.file}`, display: { summary: `Created ${displayPath(p.file, ctx.cwd)}`, preview } };
+    }
+    const line = p.before.slice(0, p.index).split('\n').length;
+    const text = input.replace_all
+      ? `The file ${p.file} has been updated successfully. All ${p.count} occurrences were replaced.`
+      : `The file ${p.file} has been updated successfully (${changedLines(line, p.newStr)}).`;
+    return { content: text, display: { summary: changeSummary(preview), preview } };
+  },
+};