codemini-cli 0.6.2 → 0.6.4

package/src/core/tools.js

@@ -30,13 +30,13 @@ import {
   sanitizeTextForModel,
   summarizeRunOutput
 } from './tool-output.js';
-import {
-  normalizeFilePathValue,
-  normalizePathArgs,
-  parseInlineRangePath,
-  normalizePatternArgs,
-  normalizeReadArgs,
-  normalizeWebFetchArgs,
+import {
+  normalizeFilePathValue,
+  normalizePathArgs,
+  parseInlineRangePath,
+  normalizePatternArgs,
+  normalizeReadArgs,
+  normalizeWebFetchArgs,
   normalizeWebSearchArgs,
   normalizeWriteArgs
 } from './tool-args.js';
@@ -150,64 +150,64 @@ function trimLinePreview(line, maxLen = 180) {
   return `${text.slice(0, maxLen - 3)}...`;
 }
 
-function splitLines(text) {
-  return String(text || '').split('\n');
-}
-
-function buildDiffPreview(beforeContent, afterContent) {
-  const beforeLines = splitLines(beforeContent);
-  const afterLines = splitLines(afterContent);
-  let prefix = 0;
-  while (
-    prefix < beforeLines.length &&
-    prefix < afterLines.length &&
-    beforeLines[prefix] === afterLines[prefix]
-  ) {
-    prefix += 1;
-  }
-
-  let beforeEnd = beforeLines.length - 1;
-  let afterEnd = afterLines.length - 1;
-  while (
-    beforeEnd >= prefix &&
-    afterEnd >= prefix &&
-    beforeLines[beforeEnd] === afterLines[afterEnd]
-  ) {
-    beforeEnd -= 1;
-    afterEnd -= 1;
-  }
-
-  const lines = [];
-  for (let i = prefix; i <= beforeEnd; i += 1) {
-    lines.push(`-${i + 1}| ${beforeLines[i]}`);
-  }
-  for (let i = prefix; i <= afterEnd; i += 1) {
-    lines.push(`+${i + 1}| ${afterLines[i]}`);
-  }
-  return lines.join('\n');
-}
-
-function clampNumber(value, min, max, fallback) {
-  const num = Number(value);
-  if (!Number.isFinite(num)) return fallback;
+function splitLines(text) {
+  return String(text || '').split('\n');
+}
+
+function buildDiffPreview(beforeContent, afterContent) {
+  const beforeLines = splitLines(beforeContent);
+  const afterLines = splitLines(afterContent);
+  let prefix = 0;
+  while (
+    prefix < beforeLines.length &&
+    prefix < afterLines.length &&
+    beforeLines[prefix] === afterLines[prefix]
+  ) {
+    prefix += 1;
+  }
+
+  let beforeEnd = beforeLines.length - 1;
+  let afterEnd = afterLines.length - 1;
+  while (
+    beforeEnd >= prefix &&
+    afterEnd >= prefix &&
+    beforeLines[beforeEnd] === afterLines[afterEnd]
+  ) {
+    beforeEnd -= 1;
+    afterEnd -= 1;
+  }
+
+  const lines = [];
+  for (let i = prefix; i <= beforeEnd; i += 1) {
+    lines.push(`-${i + 1}| ${beforeLines[i]}`);
+  }
+  for (let i = prefix; i <= afterEnd; i += 1) {
+    lines.push(`+${i + 1}| ${afterLines[i]}`);
+  }
+  return lines.join('\n');
+}
+
+function clampNumber(value, min, max, fallback) {
+  const num = Number(value);
+  if (!Number.isFinite(num)) return fallback;
   return Math.min(max, Math.max(min, num));
 }
 
-function normalizeWhitespace(value) {
-  return String(value || '')
-    .replace(/\s+/g, ' ')
-    .trim();
-}
-
-function semanticBoolean(value, fallback = false) {
-  if (typeof value === 'boolean') return value;
-  if (typeof value === 'number') return value !== 0;
-  const text = String(value ?? '').trim().toLowerCase();
-  if (!text) return fallback;
-  if (['true', '1', 'yes', 'y', 'on'].includes(text)) return true;
-  if (['false', '0', 'no', 'n', 'off'].includes(text)) return false;
-  return Boolean(value);
-}
+function normalizeWhitespace(value) {
+  return String(value || '')
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+function semanticBoolean(value, fallback = false) {
+  if (typeof value === 'boolean') return value;
+  if (typeof value === 'number') return value !== 0;
+  const text = String(value ?? '').trim().toLowerCase();
+  if (!text) return fallback;
+  if (['true', '1', 'yes', 'y', 'on'].includes(text)) return true;
+  if (['false', '0', 'no', 'n', 'off'].includes(text)) return false;
+  return Boolean(value);
+}
 
 function trimPreview(value, maxLen = 300) {
   const text = normalizeWhitespace(value);
@@ -991,6 +991,9 @@ async function writeFile(root, args, config = {}) {
   if (rawPath === '.' || rawPath === './') {
     throw new Error('write requires a file path, not the workspace root');
   }
+  if (normalizedArgs?.content == null) {
+    throw new Error('write requires content. For existing files, use edit with old_text/new_text or pass content with full_file_rewrite=true.');
+  }
   const target = await resolveInWorkspace(root, rawPath, config);
   try {
     const stat = await fs.stat(target);
@@ -1007,18 +1010,30 @@ async function writeFile(root, args, config = {}) {
   } catch {
     existed = false;
   }
-  if (existed && !normalizedArgs?.append && !normalizedArgs?.full_file_rewrite) {
-    throw new Error(
-      'write blocks full overwrite for existing files by default. Use read -> edit for existing file changes, or pass full_file_rewrite=true when a whole-file rewrite is truly intended.'
-    );
-  }
+  const nextContent = String(normalizedArgs.content ?? '');
+  if (existed && before === nextContent && !normalizedArgs?.append) {
+    return {
+      ok: true,
+      path: rawPath,
+      action: 'unchanged',
+      changed_line: 1,
+      diff_preview: '',
+      lines_added: 0,
+      lines_removed: 0
+    };
+  }
+  if (existed && !normalizedArgs?.append && !normalizedArgs?.full_file_rewrite) {
+    throw new Error(
+      `write target exists: ${rawPath}. Use edit for source changes, append=true to append, or full_file_rewrite=true to replace the whole file.`
+    );
+  }
   await fs.mkdir(path.dirname(target), { recursive: true });
   if (normalizedArgs?.append) {
-    await fs.appendFile(target, normalizedArgs?.content || '', 'utf8');
+    await fs.appendFile(target, nextContent, 'utf8');
   } else {
-    await fs.writeFile(target, normalizedArgs?.content || '', 'utf8');
+    await fs.writeFile(target, nextContent, 'utf8');
   }
-  const after = normalizedArgs?.append ? `${before}${normalizedArgs?.content || ''}` : normalizedArgs?.content || '';
+  const after = normalizedArgs?.append ? `${before}${nextContent}` : nextContent;
   const beforeLines = splitLines(before);
   const afterLines = splitLines(after);
   let changeLine = 0;
@@ -1029,17 +1044,17 @@ async function writeFile(root, args, config = {}) {
       break;
     }
   }
-  const changed = countChangedLines(before, after);
-  return {
-    ok: true,
-    path: rawPath,
-    action: normalizedArgs?.append ? 'append' : existed ? 'overwrite' : 'create',
-    changed_line: changeLine || Math.max(1, afterLines.length),
-    diff_preview: buildDiffPreview(before, after),
-    lines_added: changed.added,
-    lines_removed: changed.removed
-  };
-}
+  const changed = countChangedLines(before, after);
+  return {
+    ok: true,
+    path: rawPath,
+    action: normalizedArgs?.append ? 'append' : existed ? 'overwrite' : 'create',
+    changed_line: changeLine || Math.max(1, afterLines.length),
+    diff_preview: buildDiffPreview(before, after),
+    lines_added: changed.added,
+    lines_removed: changed.removed
+  };
+}
 
 async function prepareDeleteTarget(root, args, config = {}) {
   const normalizedArgs = normalizePathArgs(args, ['file', 'file_path', 'target', 'directory', 'dir']);
@@ -1437,8 +1452,8 @@ async function stopBackgroundTask(_root, args) {
   return { ...snapshotBackgroundTask(task), stopped: true };
 }
 
-async function builtinGrep(root, args, config = {}) {
-  const normalizedArgs = normalizePatternArgs(args, ['query', 'symbol', 'q'], ['directory', 'dir', 'cwd', 'file_path', 'file']);
+async function builtinGrep(root, args, config = {}) {
+  const normalizedArgs = normalizePatternArgs(args, ['query', 'symbol', 'q'], ['directory', 'dir', 'cwd', 'file_path', 'file']);
   const pattern = String(normalizedArgs?.pattern || '').trim();
   if (!pattern) throw new Error('grep requires pattern');
   const maxResults = Math.max(1, Math.min(200, Number(normalizedArgs?.max_results || 50)));
@@ -1472,8 +1487,8 @@ async function builtinGrep(root, args, config = {}) {
   return { pattern, matches, truncated: false };
 }
 
-async function builtinGlob(root, args, config = {}) {
-  const normalizedArgs = normalizePatternArgs(args, ['glob', 'query'], ['directory', 'dir', 'cwd', 'file_path', 'file']);
+async function builtinGlob(root, args, config = {}) {
+  const normalizedArgs = normalizePatternArgs(args, ['glob', 'query'], ['directory', 'dir', 'cwd', 'file_path', 'file']);
   const pattern = String(normalizedArgs?.pattern || '').trim();
   if (!pattern) throw new Error('glob requires pattern');
   const maxResults = Math.max(1, Math.min(500, Number(normalizedArgs?.max_results || 200)));
@@ -1493,8 +1508,8 @@ async function builtinGlob(root, args, config = {}) {
   };
 }
 
-async function builtinList(root, args, config = {}) {
-  const normalizedArgs = normalizePathArgs(args, ['dir', 'directory', 'file_path', 'file', 'target']);
+async function builtinList(root, args, config = {}) {
+  const normalizedArgs = normalizePathArgs(args, ['dir', 'directory', 'file_path', 'file', 'target']);
   const relativePath = String(normalizedArgs?.path || '.').trim() || '.';
   const target = await resolveInWorkspace(root, relativePath, config);
   const entries = await fs.readdir(target, { withFileTypes: true });
@@ -1634,10 +1649,10 @@ function countChangedLines(beforeContent, afterContent) {
   return { added: n - lcsLen, removed: m - lcsLen };
 }
 
-function editResult(pathText, action, beforeContent, afterContent, changedLine = 1) {
-  const diffPreview = buildDiffPreview(beforeContent, afterContent);
-  const changed = countChangedLines(beforeContent, afterContent);
-  return {
+function editResult(pathText, action, beforeContent, afterContent, changedLine = 1) {
+  const diffPreview = buildDiffPreview(beforeContent, afterContent);
+  const changed = countChangedLines(beforeContent, afterContent);
+  return {
     ok: true,
     path: pathText,
     action,
@@ -1647,24 +1662,24 @@ function editResult(pathText, action, beforeContent, afterContent, changedLine =
     lines_added: changed.added,
     lines_removed: changed.removed
   };
-}
-
-function lineRangeToOffsets(content, startLineRaw, endLineRaw) {
-  const lines = splitLines(content);
-  const totalLines = lines.length;
-  const startLine = Math.max(1, Math.min(totalLines, Number(startLineRaw) || 1));
-  const endLine = Math.max(startLine, Math.min(totalLines, Number(endLineRaw) || startLine));
-  let startOffset = 0;
-  for (let i = 1; i < startLine; i += 1) {
-    startOffset += lines[i - 1].length + 1;
-  }
-  let endOffset = startOffset;
-  for (let i = startLine; i <= endLine; i += 1) {
-    endOffset += lines[i - 1].length;
-    if (i < endLine) endOffset += 1;
-  }
-  return { startLine, endLine, startOffset, endOffset };
-}
+}
+
+function lineRangeToOffsets(content, startLineRaw, endLineRaw) {
+  const lines = splitLines(content);
+  const totalLines = lines.length;
+  const startLine = Math.max(1, Math.min(totalLines, Number(startLineRaw) || 1));
+  const endLine = Math.max(startLine, Math.min(totalLines, Number(endLineRaw) || startLine));
+  let startOffset = 0;
+  for (let i = 1; i < startLine; i += 1) {
+    startOffset += lines[i - 1].length + 1;
+  }
+  let endOffset = startOffset;
+  for (let i = startLine; i <= endLine; i += 1) {
+    endOffset += lines[i - 1].length;
+    if (i < endLine) endOffset += 1;
+  }
+  return { startLine, endLine, startOffset, endOffset };
+}
 
 async function replaceBlock(root, args, config = {}) {
   const relativePath = String(args?.path || '').trim();
@@ -1685,51 +1700,67 @@ async function replaceBlock(root, args, config = {}) {
   return editResult(relativePath, 'replace_block', state.content, afterContent, resolved.start_line);
 }
 
-async function replaceText(root, args, config = {}) {
-  const relativePath = String(args?.path || '').trim();
-  const oldText = String(args?.old_text || '');
-  const newText = String(args?.new_text || '');
-  const replaceAll = semanticBoolean(args?.replace_all ?? args?.replaceAll);
-  const state = await getFileState(root, relativePath, config);
-  if (!oldText) {
-    throw new Error('replace_text requires old_text');
-  }
-  const rangeStart = Number(args?.start_line || args?.line);
-  const rangeEnd = Number(args?.end_line || args?.line);
-  const hasRange = Number.isFinite(rangeStart) && rangeStart > 0;
-  const range = hasRange
-    ? lineRangeToOffsets(state.content, rangeStart, Number.isFinite(rangeEnd) && rangeEnd >= rangeStart ? rangeEnd : rangeStart)
-    : null;
-  const searchContent = range ? state.content.slice(range.startOffset, range.endOffset) : state.content;
-  const occurrences = searchContent.split(oldText).length - 1;
-  if (occurrences !== 1) {
-    if (replaceAll && occurrences > 0) {
-      const replaced = searchContent.replaceAll(oldText, newText);
-      const afterContent = range
-        ? `${state.content.slice(0, range.startOffset)}${replaced}${state.content.slice(range.endOffset)}`
-        : state.content.replaceAll(oldText, newText);
-      await fs.writeFile(state.target, afterContent, 'utf8');
-      const changedLine = range
-        ? range.startLine + splitLines(searchContent.slice(0, searchContent.indexOf(oldText))).length - 1
-        : splitLines(state.content.slice(0, state.content.indexOf(oldText))).length;
-      return editResult(relativePath, 'replace_text', state.content, afterContent, changedLine);
-    }
-    throw new Error(
-      occurrences === 0
-        ? 'replace_text old_text not found'
-        : 'replace_text old_text not unique; add a line range like path:"file.js:10-30" or set replace_all=true'
-    );
-  }
-  const replaced = searchContent.replace(oldText, newText);
-  const afterContent = range
-    ? `${state.content.slice(0, range.startOffset)}${replaced}${state.content.slice(range.endOffset)}`
-    : state.content.replace(oldText, newText);
-  await fs.writeFile(state.target, afterContent, 'utf8');
-  const changedLine = range
-    ? range.startLine + splitLines(searchContent.slice(0, searchContent.indexOf(oldText))).length - 1
-    : splitLines(state.content.slice(0, state.content.indexOf(oldText))).length;
-  return editResult(relativePath, 'replace_text', state.content, afterContent, changedLine);
-}
+async function replaceText(root, args, config = {}) {
+  const relativePath = String(args?.path || '').trim();
+  const oldText = String(args?.old_text || '');
+  const newText = String(args?.new_text || '');
+  const replaceAll = semanticBoolean(args?.replace_all ?? args?.replaceAll);
+  const state = await getFileState(root, relativePath, config);
+  if (!oldText) {
+    throw new Error('replace_text requires old_text');
+  }
+  const rangeStart = Number(args?.start_line || args?.line);
+  const rangeEnd = Number(args?.end_line || args?.line);
+  const hasRange = Number.isFinite(rangeStart) && rangeStart > 0;
+  const range = hasRange
+    ? lineRangeToOffsets(state.content, rangeStart, Number.isFinite(rangeEnd) && rangeEnd >= rangeStart ? rangeEnd : rangeStart)
+    : null;
+  const searchContent = range ? state.content.slice(range.startOffset, range.endOffset) : state.content;
+  const occurrences = searchContent.split(oldText).length - 1;
+  if (occurrences !== 1) {
+    if (replaceAll && occurrences > 0) {
+      const replaced = searchContent.replaceAll(oldText, newText);
+      const afterContent = range
+        ? `${state.content.slice(0, range.startOffset)}${replaced}${state.content.slice(range.endOffset)}`
+        : state.content.replaceAll(oldText, newText);
+      await fs.writeFile(state.target, afterContent, 'utf8');
+      const changedLine = range
+        ? range.startLine + splitLines(searchContent.slice(0, searchContent.indexOf(oldText))).length - 1
+        : splitLines(state.content.slice(0, state.content.indexOf(oldText))).length;
+      return editResult(relativePath, 'replace_text', state.content, afterContent, changedLine);
+    }
+    const baseLine = hasRange ? range.startLine : 1;
+    const baseOffset = hasRange ? range.startOffset : 0;
+    const lineDetails = [];
+    let searchPos = 0;
+    while (true) {
+      const pos = searchContent.indexOf(oldText, searchPos);
+      if (pos === -1) break;
+      const lineNum = baseLine + splitLines(searchContent.slice(0, pos)).length - 1;
+      const globalPos = baseOffset + pos;
+      const lStart = state.content.lastIndexOf('\n', globalPos) + 1;
+      const lEnd = state.content.indexOf('\n', globalPos);
+      const lineText = state.content.slice(lStart, lEnd >= 0 ? lEnd : void 0).trim();
+      lineDetails.push(`  Line ${lineNum}: ${lineText}`);
+      searchPos = pos + oldText.length;
+    }
+    const lineHint = lineDetails.length > 0 ? `\n${lineDetails.join('\n')}\n` : ' ';
+    throw new Error(
+      occurrences === 0
+        ? 'replace_text old_text not found'
+        : `replace_text old_text not unique; found ${occurrences} occurrences:${lineHint}Use path:"${relativePath}:N-M" to narrow the range, set replace_all=true, or provide more unique old_text`
+    );
+  }
+  const replaced = searchContent.replace(oldText, newText);
+  const afterContent = range
+    ? `${state.content.slice(0, range.startOffset)}${replaced}${state.content.slice(range.endOffset)}`
+    : state.content.replace(oldText, newText);
+  await fs.writeFile(state.target, afterContent, 'utf8');
+  const changedLine = range
+    ? range.startLine + splitLines(searchContent.slice(0, searchContent.indexOf(oldText))).length - 1
+    : splitLines(state.content.slice(0, state.content.indexOf(oldText))).length;
+  return editResult(relativePath, 'replace_text', state.content, afterContent, changedLine);
+}
 
 async function insertRelative(root, args, mode, config = {}) {
   const relativePath = String(args?.path || '').trim();
@@ -1776,62 +1807,62 @@ async function openTarget(root, args, config = {}) {
   };
 }
 
-function normalizeEditTargetArgs(args = {}) {
-  const rawFile = String(args?.file || args?.path || args?.file_path || '').trim();
-  const inlineRange = parseInlineRangePath(rawFile);
-  const file = normalizeFilePathValue(rawFile, { stripInlineRange: true }).trim();
-  const nestedEdit = args?.edit && typeof args.edit === 'object' ? args.edit : null;
-  const startLine = args?.start_line ?? args?.line ?? inlineRange?.start_line;
-  const endLine = args?.end_line ?? inlineRange?.end_line ?? args?.line;
-  if (nestedEdit) {
-    const normalizedEdit = { ...nestedEdit };
-    if (normalizedEdit.new_content == null && normalizedEdit.content != null) {
-      normalizedEdit.new_content = normalizedEdit.content;
-    }
-    if (normalizedEdit.old_text == null && normalizedEdit.old_string != null) {
-      normalizedEdit.old_text = normalizedEdit.old_string;
-    }
-    if (normalizedEdit.new_text == null && normalizedEdit.content != null && normalizedEdit.old_text != null) {
-      normalizedEdit.new_text = normalizedEdit.content;
-    }
-    if (normalizedEdit.new_text == null && normalizedEdit.new_string != null) {
-      normalizedEdit.new_text = normalizedEdit.new_string;
-    }
-    return {
-      path: file,
-      file,
-      start_line: startLine,
-      end_line: endLine,
-      ast_target: normalizedEdit.ast_target ?? args?.ast_target,
-      edit: normalizedEdit
-    };
-  }
+function normalizeEditTargetArgs(args = {}) {
+  const rawFile = String(args?.file || args?.path || args?.file_path || '').trim();
+  const inlineRange = parseInlineRangePath(rawFile);
+  const file = normalizeFilePathValue(rawFile, { stripInlineRange: true }).trim();
+  const nestedEdit = args?.edit && typeof args.edit === 'object' ? args.edit : null;
+  const startLine = args?.start_line ?? args?.line ?? inlineRange?.start_line;
+  const endLine = args?.end_line ?? inlineRange?.end_line ?? args?.line;
+  if (nestedEdit) {
+    const normalizedEdit = { ...nestedEdit };
+    if (normalizedEdit.new_content == null && normalizedEdit.content != null) {
+      normalizedEdit.new_content = normalizedEdit.content;
+    }
+    if (normalizedEdit.old_text == null && normalizedEdit.old_string != null) {
+      normalizedEdit.old_text = normalizedEdit.old_string;
+    }
+    if (normalizedEdit.new_text == null && normalizedEdit.content != null && normalizedEdit.old_text != null) {
+      normalizedEdit.new_text = normalizedEdit.content;
+    }
+    if (normalizedEdit.new_text == null && normalizedEdit.new_string != null) {
+      normalizedEdit.new_text = normalizedEdit.new_string;
+    }
+    return {
+      path: file,
+      file,
+      start_line: startLine,
+      end_line: endLine,
+      ast_target: normalizedEdit.ast_target ?? args?.ast_target,
+      edit: normalizedEdit
+    };
+  }
   const topLevelOldText = args?.old_text ?? args?.old_string;
   const topLevelContent = args?.content;
-  return {
-    path: file,
-    file,
-    start_line: startLine,
-    end_line: endLine,
-    ast_target: args?.ast_target,
-    edit: {
-      kind: args?.kind,
-      target: args?.target,
+  return {
+    path: file,
+    file,
+    start_line: startLine,
+    end_line: endLine,
+    ast_target: args?.ast_target,
+    edit: {
+      kind: args?.kind,
+      target: args?.target,
       new_content: args?.new_content ?? args?.content,
       old_text: args?.old_text,
       new_text: args?.new_text ?? (topLevelOldText != null && topLevelContent != null ? topLevelContent : undefined),
-      old_string: args?.old_string,
-      new_string: args?.new_string,
-      anchor_text: args?.anchor_text,
-      content: args?.content,
-      replace_all: args?.replace_all ?? args?.replaceAll
-    }
-  };
-}
+      old_string: args?.old_string,
+      new_string: args?.new_string,
+      anchor_text: args?.anchor_text,
+      content: args?.content,
+      replace_all: args?.replace_all ?? args?.replaceAll
+    }
+  };
+}
 
 async function editTarget(root, args, config = {}) {
-  const normalized = normalizeEditTargetArgs(args);
-  const file = normalized.file || normalizeFilePathValue(args?.recent_file || '', { stripInlineRange: true }).trim();
+  const normalized = normalizeEditTargetArgs(args);
+  const file = normalized.file || normalizeFilePathValue(args?.recent_file || '', { stripInlineRange: true }).trim();
   const astTarget = normalized.ast_target;
   const edit = normalized.edit || {};
   let kind = String(edit.kind || '').trim();
@@ -1842,6 +1873,7 @@ async function editTarget(root, args, config = {}) {
     edit.new_text = edit.new_string;
   }
   const hasContent = edit.new_content != null || edit.content != null;
+  const hasExplicitRewrite = edit.kind === 'rewrite_file' || args?.kind === 'rewrite_file';
   const hasTargetHint = Boolean(edit.symbol || args?.symbol || edit.line || args?.line || edit.target);
   if (!kind) {
     if (hasContent && hasTargetHint) {
@@ -1850,23 +1882,23 @@ async function editTarget(root, args, config = {}) {
       kind = 'replace_text';
     } else if ((edit.anchor_text != null || edit.target_text != null) && (edit.content != null || edit.new_content != null)) {
       kind = String(edit.position || edit.mode || args?.position || '').trim() === 'after' ? 'insert_after' : 'insert_before';
-    } else if (hasContent) {
+    } else if (hasContent && hasExplicitRewrite) {
       kind = 'rewrite_file';
     }
   }
-  if (!file || !kind) {
-    const recentFile = String(args?.recent_file || '').trim();
-    const rawArgs = typeof args?._raw === 'string' && args._raw.trim() ? ` Raw tool arguments: ${args._raw.trim()}.` : '';
-    const missing = !file
-      ? 'file path'
-      : edit.old_text != null && edit.new_text == null && edit.content == null
-        ? 'new_text'
-        : 'edit operation';
-    const hint = recentFile
-      ? ` If you meant the recently read file ${recentFile}, use edit with {file:"${recentFile}", old_text:"...", new_text:"..."} for a text replacement, or {file:"${recentFile}", edit:{kind:"rewrite_file", new_content:"..."}} for a full rewrite.`
-      : ' Use edit with {file:"path", old_text:"...", new_text:"..."} for a text replacement, or {file:"path", edit:{kind:"rewrite_file", new_content:"..."}} for a full rewrite.';
-    throw new Error(`edit requires ${missing}.${rawArgs}${hint}`);
-  }
+  if (!file || !kind) {
+    const recentFile = String(args?.recent_file || '').trim();
+    const rawArgs = typeof args?._raw === 'string' && args._raw.trim() ? ` Raw tool arguments: ${args._raw.trim()}.` : '';
+    const missing = !file
+      ? 'file path'
+      : edit.old_text != null && edit.new_text == null && edit.content == null
+        ? 'new_text'
+        : 'edit operation';
+    const hint = recentFile
+      ? ` If you meant the recently read file ${recentFile}, use edit with {file:"${recentFile}", old_text:"...", new_text:"..."} for a text replacement, or {file:"${recentFile}", kind:"rewrite_file", new_content:"..."} for a full rewrite.`
+      : ' Use edit with {file:"path", old_text:"...", new_text:"..."} for a text replacement, or {file:"path", kind:"rewrite_file", new_content:"..."} for a full rewrite.';
+    throw new Error(`edit requires ${missing}.${rawArgs}${hint}`);
+  }
   if (astTarget) {
     if (kind !== 'replace_block') {
       throw new Error('AST-scoped edit only supports replace_block');
@@ -1910,16 +1942,16 @@ async function editTarget(root, args, config = {}) {
       }, config);
     }
   }
-  if (kind === 'replace_text') {
-    return replaceText(root, {
-      path: file,
-      old_text: edit.old_text,
-      new_text: edit.new_text,
-      replace_all: edit.replace_all ?? args?.replace_all ?? args?.replaceAll,
-      start_line: edit.start_line ?? normalized.start_line,
-      end_line: edit.end_line ?? normalized.end_line
-    }, config);
-  }
+  if (kind === 'replace_text') {
+    return replaceText(root, {
+      path: file,
+      old_text: edit.old_text,
+      new_text: edit.new_text,
+      replace_all: edit.replace_all ?? args?.replace_all ?? args?.replaceAll,
+      start_line: edit.start_line ?? normalized.start_line,
+      end_line: edit.end_line ?? normalized.end_line
+    }, config);
+  }
   if (kind === 'insert_before') {
     return insertRelative(root, { path: file, anchor_text: edit.anchor_text, content: edit.content }, 'insert_before', config);
   }
@@ -1936,19 +1968,19 @@ async function editTarget(root, args, config = {}) {
   throw new Error(`edit does not support kind: ${kind}`);
 }
 
-export function getBuiltinTools({ workspaceRoot = process.cwd(), config, onSystemEvent, getTodos, onTodosUpdate, getPlanState, onPlanStateUpdate, fffAdapter }) {
+export function getBuiltinTools({ workspaceRoot = process.cwd(), config, onSystemEvent, getTodos, onTodosUpdate, getPlanState, onPlanStateUpdate, fffAdapter, backupManager }) {
   const emitSystemTool = (event) => {
     if (typeof onSystemEvent === 'function' && event) onSystemEvent(event);
   };
-  const astSelectionCache = new Map();
-  let lastAstTarget = null;
-  let lastReadPath = '';
-  let lastReadRange = null;
-  const rememberAstSelection = (filePath, astTarget) => {
-    const key = normalizePath(filePath).trim();
-    if (!key || !astTarget) return;
-    lastAstTarget = astTarget;
-    astSelectionCache.set(key, astTarget);
+  const astSelectionCache = new Map();
+  let lastAstTarget = null;
+  let lastReadPath = '';
+  let lastReadRange = null;
+  const rememberAstSelection = (filePath, astTarget) => {
+    const key = normalizePath(filePath).trim();
+    if (!key || !astTarget) return;
+    lastAstTarget = astTarget;
+    astSelectionCache.set(key, astTarget);
   };
   const hasExplicitBlockHints = (args = {}) =>
     Boolean(
@@ -1961,15 +1993,15 @@ export function getBuiltinTools({ workspaceRoot = process.cwd(), config, onSyste
         args?.edit?.line ||
         args?.edit?.target
     );
-  const resolveCachedAstTarget = (args = {}, { requireAstScope = false } = {}) => {
-    const file = normalizeFilePathValue(args?.path || args?.file || args?.file_path || args?.ast_target?.path || '', { stripInlineRange: true }).trim();
-    if (args?.ast_target) return args.ast_target;
-    if (file) {
-      if (requireAstScope && hasExplicitBlockHints(args)) return null;
-      return astSelectionCache.get(file) || null;
-    }
-    return lastAstTarget || null;
-  };
+  const resolveCachedAstTarget = (args = {}, { requireAstScope = false } = {}) => {
+    const file = normalizeFilePathValue(args?.path || args?.file || args?.file_path || args?.ast_target?.path || '', { stripInlineRange: true }).trim();
+    if (args?.ast_target) return args.ast_target;
+    if (file) {
+      if (requireAstScope && hasExplicitBlockHints(args)) return null;
+      return astSelectionCache.get(file) || null;
+    }
+    return lastAstTarget || null;
+  };
   const ensureProjectIndex = async () => {
     const eventId = `project-index:${Date.now()}`;
     const name = 'project_index(.codemini/project-map.json,.codemini/file-index.json)';
@@ -2021,17 +2053,17 @@ export function getBuiltinTools({ workspaceRoot = process.cwd(), config, onSyste
     {
       type: 'function',
       function: {
-        name: 'read',
-        description:
-          'Inspect code or text files. Use {path} for normal reads; file_path/file are accepted aliases. Use start_line/end_line or path:"src/app.ts:10-40" for ranges. Normal code reads include enclosing symbol metadata when available; read with query returns the matched AST node and ast_target.',
-        parameters: {
-          type: 'object',
-          properties: {
-            path: { type: 'string', description: 'File path to read. You can also include an inline range like src/app.ts:10-40.' },
-            file_path: { type: 'string', description: 'Alias for path' },
-            file: { type: 'string', description: 'Alias for path' },
-            start_line: { type: 'number', description: '1-based start line' },
-            end_line: { type: 'number', description: 'Inclusive end line' },
+        name: 'read',
+        description:
+          'Inspect code or text files. Use {path} for normal reads; file_path/file are accepted aliases. Use start_line/end_line or path:"src/app.ts:10-40" for ranges. Normal code reads include enclosing symbol metadata when available; read with query returns the matched AST node and ast_target.',
+        parameters: {
+          type: 'object',
+          properties: {
+            path: { type: 'string', description: 'File path to read. You can also include an inline range like src/app.ts:10-40.' },
+            file_path: { type: 'string', description: 'Alias for path' },
+            file: { type: 'string', description: 'Alias for path' },
+            start_line: { type: 'number', description: '1-based start line' },
+            end_line: { type: 'number', description: 'Inclusive end line' },
             max_chars: { type: 'number', description: 'Max chars to return' },
             ast_target: { type: 'object', description: 'AST target from ast_query or a prior AST selection. When provided, read returns that node instead of a line window.' },
             query: { type: 'string', description: 'Optional Tree-sitter query to run inline before reading the first matched AST node. Use with path for one-shot function/class/method reads.' },
@@ -2050,10 +2082,10 @@ export function getBuiltinTools({ workspaceRoot = process.cwd(), config, onSyste
           'Search file contents. Use this for code search before read or edit. Do not use run with grep or rg for normal code search.',
         parameters: {
           type: 'object',
-          properties: {
-            pattern: { type: 'string', description: 'Search pattern' },
-            path: { type: 'string', description: 'Directory or file to search. file_path/file/dir/directory/cwd are accepted aliases.' },
-            regex: { type: 'boolean', description: 'Treat pattern as regex' },
+          properties: {
+            pattern: { type: 'string', description: 'Search pattern' },
+            path: { type: 'string', description: 'Directory or file to search. file_path/file/dir/directory/cwd are accepted aliases.' },
+            regex: { type: 'boolean', description: 'Treat pattern as regex' },
             case_sensitive: { type: 'boolean', description: 'Case-sensitive matching' },
             max_results: { type: 'number', description: 'Max matches to return' },
             language: { type: 'string', description: 'Filter by language' },
@@ -2070,9 +2102,9 @@ export function getBuiltinTools({ workspaceRoot = process.cwd(), config, onSyste
         description: 'List files and directories in a workspace path. Use this for quick directory discovery before deeper reads.',
         parameters: {
           type: 'object',
-          properties: {
-            path: { type: 'string', description: 'Directory path to list. file_path/file/dir/directory are accepted aliases.' },
-            include_hidden: { type: 'boolean', description: 'Include dotfiles' }
+          properties: {
+            path: { type: 'string', description: 'Directory path to list. file_path/file/dir/directory are accepted aliases.' },
+            include_hidden: { type: 'boolean', description: 'Include dotfiles' }
           }
         }
       }
@@ -2080,9 +2112,9 @@ export function getBuiltinTools({ workspaceRoot = process.cwd(), config, onSyste
     {
       type: 'function',
       function: {
-        name: 'query_project_index',
-        description:
-          'Query the lightweight project index before broad file reads. Returns relevant files plus Symbol Graph summaries: symbol_id, type, range, signature, calls, called_by, imports, writes, and emits.',
+        name: 'query_project_index',
+        description:
+          'Query the lightweight project index before broad file reads. Returns relevant files plus Symbol Graph summaries: symbol_id, type, range, signature, calls, called_by, imports, writes, and emits.',
         parameters: {
           type: 'object',
           properties: {
@@ -2098,24 +2130,24 @@ export function getBuiltinTools({ workspaceRoot = process.cwd(), config, onSyste
     {
       type: 'function',
       function: {
-        name: 'edit',
-        description:
-          'Edit existing files. Prefer {path, old_text, new_text}; old_string/new_string and file_path/file are accepted aliases. If old_text is repeated, use path:"file:10-30" or rely on the most recent read range. Set replace_all=true to replace every match. Advanced kind/ast_target edits are still supported.',
-        parameters: {
-          type: 'object',
-          properties: {
-            path: { type: 'string', description: 'File path to edit. Inline ranges like src/app.js:10-30 are accepted.' },
-            file_path: { type: 'string', description: 'Alias for path' },
-            file: { type: 'string', description: 'Alias for path' },
-            new_content: { type: 'string', description: 'Replacement content' },
-            old_text: { type: 'string', description: 'Exact text to replace' },
-            new_text: { type: 'string', description: 'Replacement text' },
-            old_string: { type: 'string', description: 'Alias for old_text' },
-            new_string: { type: 'string', description: 'Alias for new_text' },
-            replace_all: { type: 'boolean', description: 'Replace all matching old_text occurrences' },
-            start_line: { type: 'number', description: 'Optional range start for disambiguating old_text' },
-            end_line: { type: 'number', description: 'Optional range end for disambiguating old_text' },
-            anchor_text: { type: 'string', description: 'Anchor text for inserts' },
+        name: 'edit',
+        description:
+          'Edit existing files. Prefer {path, old_text, new_text}; old_string/new_string and file_path/file are accepted aliases. If old_text is repeated, use path:"file:10-30" or rely on the most recent read range. Set replace_all=true to replace every match. Advanced kind/ast_target edits are still supported.',
+        parameters: {
+          type: 'object',
+          properties: {
+            path: { type: 'string', description: 'File path to edit. Inline ranges like src/app.js:10-30 are accepted.' },
+            file_path: { type: 'string', description: 'Alias for path' },
+            file: { type: 'string', description: 'Alias for path' },
+            new_content: { type: 'string', description: 'Replacement content' },
+            old_text: { type: 'string', description: 'Exact text to replace' },
+            new_text: { type: 'string', description: 'Replacement text' },
+            old_string: { type: 'string', description: 'Alias for old_text' },
+            new_string: { type: 'string', description: 'Alias for new_text' },
+            replace_all: { type: 'boolean', description: 'Replace all matching old_text occurrences' },
+            start_line: { type: 'number', description: 'Optional range start for disambiguating old_text' },
+            end_line: { type: 'number', description: 'Optional range end for disambiguating old_text' },
+            anchor_text: { type: 'string', description: 'Anchor text for inserts' },
             content: { type: 'string', description: 'Content to insert or append' },
             position: { type: 'string', description: 'before or after' },
             kind: { type: 'string', description: 'replace_block, replace_text, insert_before, insert_after, or rewrite_file' },
@@ -2125,23 +2157,23 @@ export function getBuiltinTools({ workspaceRoot = process.cwd(), config, onSyste
             line: { type: 'number', description: 'Line to target' },
             edit: { type: 'object', description: 'Structured edit input' }
           },
-          required: ['path']
+          required: ['path', 'content']
         }
       }
     },
     {
       type: 'function',
       function: {
-        name: 'write',
-        description:
-          'Create a new file, append to a file, or perform an explicit whole-file rewrite. Always include path and content; file_path/file are accepted aliases. For existing files, prefer edit after reading the relevant range. Overwriting an existing file requires full_file_rewrite=true.',
-        parameters: {
-          type: 'object',
-          properties: {
-            path: { type: 'string', description: 'Required file path like src/app.js or pages/index.html. Never omit this.' },
-            file_path: { type: 'string', description: 'Alias for path' },
-            file: { type: 'string', description: 'Alias for path' },
-            content: { type: 'string', description: 'Content to write' },
+        name: 'write',
+        description:
+          'Create a new file, append to a file, or perform an explicit whole-file rewrite. Always include path and content; file_path/file are accepted aliases. For existing files, prefer edit after reading the relevant range. Overwriting an existing file requires full_file_rewrite=true.',
+        parameters: {
+          type: 'object',
+          properties: {
+            path: { type: 'string', description: 'Required file path like src/app.js or pages/index.html. Never omit this.' },
+            file_path: { type: 'string', description: 'Alias for path' },
+            file: { type: 'string', description: 'Alias for path' },
+            content: { type: 'string', description: 'Content to write' },
             append: { type: 'boolean', description: 'Append instead of overwrite' },
             full_file_rewrite: { type: 'boolean', description: 'Set true for whole-file rewrites' }
           },
@@ -2157,12 +2189,12 @@ export function getBuiltinTools({ workspaceRoot = process.cwd(), config, onSyste
           'Delete a file or directory inside the workspace. Missing targets fail. Workspace escape attempts are rejected.',
         parameters: {
           type: 'object',
-          properties: {
-            path: { type: 'string', description: 'File or directory path to delete. file_path/file/target are accepted aliases.' },
-            file_path: { type: 'string', description: 'Alias for path' },
-            file: { type: 'string', description: 'Alias for path' },
-            target: { type: 'string', description: 'Alias for path' }
-          },
+          properties: {
+            path: { type: 'string', description: 'File or directory path to delete. file_path/file/target are accepted aliases.' },
+            file_path: { type: 'string', description: 'Alias for path' },
+            file: { type: 'string', description: 'Alias for path' },
+            target: { type: 'string', description: 'Alias for path' }
+          },
           required: ['path']
         }
       }
@@ -2530,7 +2562,36 @@ export function getBuiltinTools({ workspaceRoot = process.cwd(), config, onSyste
   };
 
   const definitions = [...primaryDefinitions];
-  const activeFffAdapter = fffAdapter || createFffAdapter({ workspaceRoot, config });
+  const activeFffAdapter = fffAdapter || createFffAdapter({ workspaceRoot, config });
+  async function backupNonGitPathOnce(rawPath) {
+    if (!backupManager || typeof backupManager.backupOnce !== 'function') return null;
+    const normalized = normalizeFilePathValue(rawPath || '', { stripInlineRange: true }).trim();
+    if (!normalized) return null;
+    try {
+      const backup = await backupManager.backupOnce(normalized);
+      return backup?.ok ? backup : null;
+    } catch (error) {
+      return {
+        ok: false,
+        path: normalized,
+        error: error instanceof Error ? error.message : String(error)
+      };
+    }
+  }
+  function attachBackup(result, backup) {
+    if (!backup || !result || typeof result !== 'object') return result;
+    return {
+      ...result,
+      non_git_backup: true,
+      backupPath: backup.backupPath || '',
+      backupRelativePath: backup.backupRelativePath || '',
+      backupCreated: backup.created === true,
+      backupReused: backup.reused === true,
+      backupSkipped: backup.skipped === true || (!backup.backupPath && backup.existed === true),
+      backupError: backup.error || '',
+      backupReason: backup.reason || ''
+    };
+  }
   let fffConnected = false;
 
   async function ensureFffConnected() {
@@ -2563,8 +2624,8 @@ export function getBuiltinTools({ workspaceRoot = process.cwd(), config, onSyste
     return builtinGlob(workspaceRoot, args, config);
   }
 
-  async function list(args) {
-    const normalizedArgs = normalizePathArgs(args, ['dir', 'directory', 'file_path', 'file', 'target']);
+  async function list(args) {
+    const normalizedArgs = normalizePathArgs(args, ['dir', 'directory', 'file_path', 'file', 'target']);
     if (!resolvesOutsideRoot(workspaceRoot, normalizedArgs?.path || '.') && activeFffAdapter?.list) {
       try {
         await ensureFffConnected();
@@ -2585,15 +2646,15 @@ export function getBuiltinTools({ workspaceRoot = process.cwd(), config, onSyste
           ...args,
           path: args?.path || directAstTarget?.path,
           ast_target: directAstTarget
-        });
-        if (directAstTarget?.path) rememberAstSelection(directAstTarget.path, directAstTarget);
-        const readPath = normalizePath(result?.path || directAstTarget?.path || '').trim();
-        if (readPath) {
-          lastReadPath = readPath;
-          lastReadRange = null;
-        }
-        return { ...result, ast_target: directAstTarget };
-      }
+        });
+        if (directAstTarget?.path) rememberAstSelection(directAstTarget.path, directAstTarget);
+        const readPath = normalizePath(result?.path || directAstTarget?.path || '').trim();
+        if (readPath) {
+          lastReadPath = readPath;
+          lastReadRange = null;
+        }
+        return { ...result, ast_target: directAstTarget };
+      }
 
       if (inlineQuery) {
         const queryResult = await queryAst(workspaceRoot, args);
@@ -2614,30 +2675,30 @@ export function getBuiltinTools({ workspaceRoot = process.cwd(), config, onSyste
           path: firstTarget.path,
           ast_target: firstTarget
         });
-        const readPath = normalizePath(result?.path || firstTarget?.path || '').trim();
-        if (readPath) {
-          lastReadPath = readPath;
-          lastReadRange = null;
-        }
-        return {
-          path: result.path,
-          language: result.language,
-          node: result.node,
-          content: result.content,
-          ast_target: firstTarget,
-          symbol: {
-            symbol_id: `${result.path}#${firstTarget.name || firstTarget.node_type || `${result.node.start_line}-${result.node.end_line}`}`,
-            type: result.node.node_type,
-            file: result.path,
-            range: {
-              start_line: result.node.start_line,
-              end_line: result.node.end_line
-            }
-          },
-          query: inlineQuery,
-          capture_name: String(args?.capture_name || '').trim() || undefined,
-          matches: queryResult.matches.length
-        };
+        const readPath = normalizePath(result?.path || firstTarget?.path || '').trim();
+        if (readPath) {
+          lastReadPath = readPath;
+          lastReadRange = null;
+        }
+        return {
+          path: result.path,
+          language: result.language,
+          node: result.node,
+          content: result.content,
+          ast_target: firstTarget,
+          symbol: {
+            symbol_id: `${result.path}#${firstTarget.name || firstTarget.node_type || `${result.node.start_line}-${result.node.end_line}`}`,
+            type: result.node.node_type,
+            file: result.path,
+            range: {
+              start_line: result.node.start_line,
+              end_line: result.node.end_line
+            }
+          },
+          query: inlineQuery,
+          capture_name: String(args?.capture_name || '').trim() || undefined,
+          matches: queryResult.matches.length
+        };
       }
 
       const result = await readFile(workspaceRoot, {
@@ -2648,14 +2709,14 @@ export function getBuiltinTools({ workspaceRoot = process.cwd(), config, onSyste
             ? args.max_chars
             : config.context?.read_file_max_chars ?? 24000
       }, config);
-      const readPath = normalizePath(result?.path || args?.path || '').trim();
-      if (readPath) {
-        lastReadPath = readPath;
-        lastReadRange = result?.phase === 'content'
-          ? { path: readPath, start_line: result.start_line, end_line: result.end_line }
-          : null;
-      }
-      return result;
+      const readPath = normalizePath(result?.path || args?.path || '').trim();
+      if (readPath) {
+        lastReadPath = readPath;
+        lastReadRange = result?.phase === 'content'
+          ? { path: readPath, start_line: result.start_line, end_line: result.end_line }
+          : null;
+      }
+      return result;
     },
     query_project_index: async (args) => {
       await ensureProjectIndex();
@@ -2681,16 +2742,20 @@ export function getBuiltinTools({ workspaceRoot = process.cwd(), config, onSyste
     edit: async (args) => {
       await ensureProjectIndex();
       const normalizedKind = String(args?.edit?.kind || args?.kind || '').trim();
-      const astTarget = resolveCachedAstTarget(args, { requireAstScope: normalizedKind === 'replace_block' });
-      const editPath = normalizeFilePathValue(args?.path || args?.file || args?.file_path || '', { stripInlineRange: true }).trim();
-      const shouldUseRecentReadRange =
-        editPath &&
-        lastReadRange?.path === editPath &&
-        !Number.isFinite(Number(args?.start_line || args?.line || args?.edit?.start_line)) &&
-        !Number.isFinite(Number(args?.end_line || args?.edit?.end_line));
-      const rangeArgs = shouldUseRecentReadRange
-        ? { start_line: lastReadRange.start_line, end_line: lastReadRange.end_line }
-        : {};
+      const hasReplaceTextArgs = args?.edit?.old_text != null || args?.old_text != null || args?.old_string != null;
+      const astTarget = hasReplaceTextArgs || (normalizedKind && normalizedKind !== 'replace_block')
+        ? null
+        : resolveCachedAstTarget(args, { requireAstScope: normalizedKind === 'replace_block' });
+      const editPath = normalizeFilePathValue(args?.path || args?.file || args?.file_path || args?.ast_target?.path || args?.edit?.target?.path || '', { stripInlineRange: true }).trim();
+      const shouldUseRecentReadRange =
+        editPath &&
+        lastReadRange?.path === editPath &&
+        !Number.isFinite(Number(args?.start_line || args?.line || args?.edit?.start_line)) &&
+        !Number.isFinite(Number(args?.end_line || args?.edit?.end_line));
+      const rangeArgs = shouldUseRecentReadRange
+        ? { start_line: lastReadRange.start_line, end_line: lastReadRange.end_line }
+        : {};
+      const backup = await backupNonGitPathOnce(editPath || astTarget?.path);
       const result = await editTarget(
         workspaceRoot,
         astTarget
@@ -2698,21 +2763,25 @@ export function getBuiltinTools({ workspaceRoot = process.cwd(), config, onSyste
           : { ...args, ...rangeArgs, recent_file: lastReadPath },
         config
       );
-      if (result?.path) await refreshProjectFile(result.path);
-      return result;
-    },
-    write: async (args) => {
-      await ensureProjectIndex();
-      const result = await writeFile(workspaceRoot, args, config);
-      if (result?.path) await refreshProjectFile(result.path);
-      return result;
-    },
-    delete: Object.assign(async (args) => {
-      await ensureProjectIndex();
-      const result = await deletePath(workspaceRoot, args, config);
-      if (result?.path) await refreshProjectFile(result.path);
-      return result;
-    }, {
+      if (result?.path) await refreshProjectFile(result.path);
+      return attachBackup(result, backup);
+    },
+    write: async (args) => {
+      await ensureProjectIndex();
+      const writePath = normalizeFilePathValue(args?.path || args?.file || args?.file_path || '', { stripInlineRange: true }).trim();
+      const backup = await backupNonGitPathOnce(writePath);
+      const result = await writeFile(workspaceRoot, args, config);
+      if (result?.path) await refreshProjectFile(result.path);
+      return attachBackup(result, backup);
+    },
+    delete: Object.assign(async (args) => {
+      await ensureProjectIndex();
+      const deletePathValue = normalizeFilePathValue(args?.path || args?.file || args?.file_path || args?.target || '', { stripInlineRange: true }).trim();
+      const backup = await backupNonGitPathOnce(deletePathValue);
+      const result = await deletePath(workspaceRoot, args, config);
+      if (result?.path) await refreshProjectFile(result.path);
+      return attachBackup(result, backup);
+    }, {
       prepareApproval: async (args) => {
         const target = await prepareDeleteTarget(workspaceRoot, args, config);
         return {
@@ -2994,41 +3063,50 @@ export function getBuiltinTools({ workspaceRoot = process.cwd(), config, onSyste
       return lines.join('\n');
     },
 
-    edit(result) {
-      if (!result || typeof result !== 'object') return String(result);
-      const p = result.path || '';
-      const action = result.action || '';
-      const line = result.changed_line || 0;
-      const summary = `${action} ${p}${line > 0 ? ` @L${line}` : ''}`;
-      const diffPreview = result.diff_preview || '';
-      if (diffPreview) {
-        const trimmed = diffPreview.length > 600 ? `${diffPreview.slice(0, 597)}...` : diffPreview;
+    edit(result) {
+      if (!result || typeof result !== 'object') return String(result);
+      const p = result.path || '';
+      const action = result.action || '';
+      const line = result.changed_line || 0;
+      const backup = result.backupPath
+        ? `\nbackup: ${result.backupPath}${result.backupReused ? ' (reused)' : ''}`
+        : '';
+      const summary = `${action} ${p}${line > 0 ? ` @L${line}` : ''}${backup}`;
+      const diffPreview = result.diff_preview || '';
+      if (diffPreview) {
+        const trimmed = diffPreview.length > 600 ? `${diffPreview.slice(0, 597)}...` : diffPreview;
         return `${summary}\n${trimmed}`;
       }
       return summary + (result.ok !== false ? '' : ` [FAILED: ${result.error || 'unknown'}]`);
     },
 
-    write(result) {
-      if (!result || typeof result !== 'object') return String(result);
-      const p = result.path || '';
-      const action = result.action || 'write';
-      const line = result.changed_line || 0;
-      const summary = `${action} ${p}${line > 0 ? ` @L${line}` : ''}`;
-      const diffPreview = result.diff_preview || '';
-      if (diffPreview) {
-        const trimmed = diffPreview.length > 600 ? `${diffPreview.slice(0, 597)}...` : diffPreview;
+    write(result) {
+      if (!result || typeof result !== 'object') return String(result);
+      const p = result.path || '';
+      const action = result.action || 'write';
+      const line = result.changed_line || 0;
+      const backup = result.backupPath
+        ? `\nbackup: ${result.backupPath}${result.backupReused ? ' (reused)' : ''}`
+        : '';
+      const summary = `${action} ${p}${line > 0 ? ` @L${line}` : ''}${backup}`;
+      const diffPreview = result.diff_preview || '';
+      if (diffPreview) {
+        const trimmed = diffPreview.length > 600 ? `${diffPreview.slice(0, 597)}...` : diffPreview;
         return `${summary}\n${trimmed}`;
       }
       return summary;
     },
 
-    delete(result) {
-      if (!result || typeof result !== 'object') return String(result);
-      if (result.ok === false) return JSON.stringify(result);
-      const kind = result.type || 'item';
-      const target = result.path || '';
-      return `[delete: ${kind}] deleted ${target}`;
-    },
+    delete(result) {
+      if (!result || typeof result !== 'object') return String(result);
+      if (result.ok === false) return JSON.stringify(result);
+      const kind = result.type || 'item';
+      const target = result.path || '';
+      const backup = result.backupPath
+        ? `\nbackup: ${result.backupPath}${result.backupReused ? ' (reused)' : ''}`
+        : '';
+      return `[delete: ${kind}] deleted ${target}${backup}`;
+    },
 
     run(result) {
       if (!result || typeof result !== 'object') return String(result);