@semalt-ai/code 1.19.0 → 1.20.1

package/lib/tool_registry.js

@@ -287,6 +287,22 @@ function _matchDual(text, template) {
   return results;
 }
 
+// 1-based starting line numbers of every literal occurrence of `needle` in
+// `data`. Used by replace_in_file's uniqueness guard to tell the model WHERE the
+// ambiguous matches are so it can add disambiguating context. Capped so a needle
+// that matches hundreds of times doesn't produce a giant error string.
+function _literalOccurrenceLines(data, needle, cap = 10) {
+  const lines = [];
+  let from = 0;
+  let idx;
+  while ((idx = data.indexOf(needle, from)) !== -1) {
+    lines.push(data.slice(0, idx).split('\n').length);
+    from = idx + needle.length;
+    if (lines.length >= cap) break;
+  }
+  return lines;
+}
+
 function _unwrapInnerTag(inner) {
   if (inner == null) return inner;
   const trimmed = String(inner).trim();
@@ -367,6 +383,12 @@ async function _execWriteAppend(ctx, action, args, options) {
   }
 
   try {
+    // Capture prior content so the diff can render at EXECUTION time (the agent
+    // loop hands _diffBefore/_diffAfter to onToolEnd). Non-existent file → '' →
+    // the diff renders as a new file. Cheap relative to the write itself.
+    let before = '';
+    try { before = await fsp.readFile(filePath, 'utf8'); } catch {}
+    const after = action === 'write' ? (content || '') : (before + (content || ''));
     const dir = path.dirname(filePath);
     if (dir && dir !== '.') await fsp.mkdir(dir, { recursive: true });
     if (action === 'write') await fsp.writeFile(filePath, content || '');
@@ -374,7 +396,7 @@ async function _execWriteAppend(ctx, action, args, options) {
     const verb = action === 'write' ? 'Wrote' : 'Appended to';
     _log(`  ${FG_GREEN}✓${RST} ${FG_GRAY}${verb} ${filePath}${RST}`);
     logToolCall(tag, { path: filePath, content }, true, 'ok');
-    return { status: 'ok', path: filePath, bytes: (content || '').length };
+    return { status: 'ok', path: filePath, bytes: (content || '').length, _diffBefore: before, _diffAfter: after };
   } catch (error) {
     _log(`  ${FG_RED}✗ ${error.message}${RST}`);
     logToolCall(tag, { path: filePath, content }, true, 'error');
@@ -383,25 +405,29 @@ async function _execWriteAppend(ctx, action, args, options) {
 }
 
 async function _permWriteAppend(ctx, action, args) {
-  const { _dryRun, renderDiff, DIFF_BUBBLE_INSET, writer } = ctx;
+  const { _dryRun, renderDiff, writer } = ctx;
   const _uiActive = ctx._uiActive;
   const filePath = args[0];
   const content = args[1];
   const tag = action === 'write' ? 'write_file' : 'append_file';
 
-  let existing = '';
-  try { existing = await fsp.readFile(filePath, 'utf8'); } catch {}
-  const finalContent = action === 'write' ? (content || '') : (existing + (content || ''));
-  const diffOutput = _uiActive
-    ? renderDiff(existing, finalContent, filePath, { inset: DIFF_BUBBLE_INSET })
-    : renderDiff(existing, finalContent, filePath);
-  if (!_uiActive) writer.scrollback(diffOutput);
+  // The full diff is rendered at EXECUTION time (the agent loop's onToolEnd),
+  // decoupled from this modal — so an auto-approved write shows its diff just
+  // like a manually-approved one, and the diff is shown exactly once. The modal
+  // therefore carries only a compact description, NOT the diff. The one path
+  // without an execution-time renderer (headless / oneshot, !_uiActive) still
+  // surfaces the diff here so a write is never silent there.
+  if (!_uiActive && !_dryRun) {
+    let existing = '';
+    try { existing = await fsp.readFile(filePath, 'utf8'); } catch {}
+    const finalContent = action === 'write' ? (content || '') : (existing + (content || ''));
+    writer.scrollback(renderDiff(existing, finalContent, filePath));
+  }
 
   if (_dryRun) return null;
 
   let desc = `${action === 'write' ? 'Write' : 'Append to'} ${filePath}`;
   if (content) desc += ` (${content.length} chars)`;
-  if (_uiActive) desc = `${desc}\n${diffOutput}`;
   return { actionType: 'file', description: desc, tag };
 }
 
@@ -620,10 +646,93 @@ function _finalizeGrep(raw, pattern) {
   return out;
 }
 
+// Resolve the grep `path` argument into a concrete search plan. `path` is no
+// longer a glob-only filter: it may denote an existing FILE (search just that
+// file, like search_in_file), an existing DIRECTORY (use it as the walk root),
+// or — when it is NOT an existing filesystem path — a GLOB filter applied to the
+// cwd walk (the legacy behavior, preserved for callers like `path="*.js"`). A
+// `path` that is a literal that does not exist falls into the glob branch and
+// simply matches zero candidate files; the wrapper's safety net then turns that
+// into a clear diagnostic instead of a silent {count:0}. Relative paths resolve
+// against the process cwd (statSync semantics), matching read_file/search_in_file.
+function _resolveGrepPath(pathArg) {
+  if (pathArg == null || pathArg === '') return { mode: 'none', baseDir: '.', pathGlob: null };
+  let st = null;
+  try { st = fs.statSync(pathArg); } catch { st = null; }
+  if (st && st.isFile()) return { mode: 'file', file: pathArg, display: pathArg };
+  if (st && st.isDirectory()) return { mode: 'dir', baseDir: pathArg, pathGlob: null };
+  return { mode: 'glob', baseDir: '.', pathGlob: pathArg };
+}
+
+// Grep a single explicit file (FILE-target mode). Engine-independent — an
+// explicitly named file is read directly (like search_in_file), which also means
+// it is searched even if .gitignore'd, since the model asked for THIS file. Binary
+// files yield no matches. Returns the same { matches:[{file,line,text}] } shape as
+// _grepNode so it flows through _finalizeGrep identically.
+function _grepFile({ pattern, ignoreCase, file, display, signal }) {
+  let re;
+  try { re = new RegExp(pattern, ignoreCase ? 'i' : ''); }
+  catch (err) { return { error: `Invalid regex pattern: ${err.message}` }; }
+  if (signal && signal.aborted) return { aborted: true };
+  let buf;
+  try { buf = fs.readFileSync(file); } catch (err) { return { error: err.message }; }
+  if (_isBinaryBuf(buf)) return { matches: [] };
+  const data = buf.toString('utf8');
+  const lines = data.split('\n');
+  if (data.endsWith('\n')) lines.pop();
+  const posix = _toPosix(display);
+  const matches = [];
+  for (let i = 0; i < lines.length; i++) {
+    if (re.test(lines[i])) matches.push({ file: posix, line: i + 1, text: lines[i] });
+  }
+  return { matches };
+}
+
+// Does the walk root contain ANY file grep would consider searching (passing the
+// gitignore + skip-dir + pathGlob filters)? Used ONLY by the safety net, and only
+// when a result came back empty — it answers "was there anything to search at
+// all?" so a glob that matched real files (true negative) is never demoted to an
+// error. Deliberately does NOT read file contents (no binary sniff): over-counting
+// errs toward returning {count:0}, the safe direction. Short-circuits on first hit.
+function _grepHasCandidate({ baseDir, pathGlob, signal }) {
+  const rules = _loadGitignore(baseDir);
+  const pf = pathGlob ? _globToRegExp(pathGlob) : null;
+  const pfBasename = pathGlob && !pathGlob.includes('/');
+  let found = false;
+  _walkTree(baseDir, {
+    rules,
+    signal,
+    onFile: (rel, name) => {
+      if (found) return;
+      if (pf && !pf.test(pfBasename ? name : rel)) return;
+      found = true;
+    },
+  });
+  return found;
+}
+
 // engine: 'auto' (rg if available, else Node), 'rg', or 'node'. Exported for
 // the parity tests, which drive both engines and assert deep equality.
-function _grepSearch({ pattern, pathGlob = null, ignoreCase = false, baseDir = '.', engine = 'auto', signal = null }) {
+//
+// `path` (when supplied) is the path-aware target: it is resolved via
+// _resolveGrepPath into a FILE read / DIRECTORY walk root / GLOB filter, and feeds
+// BOTH engines identically (FILE mode is a direct read, trivially engine-agnostic).
+// The legacy `pathGlob`/`baseDir` params are still honored directly for callers
+// that pre-resolve (the parity tests). The safety net fires ONLY on the `path`
+// pathway, so existing pathGlob/baseDir callers are byte-for-byte unaffected.
+function _grepSearch({ pattern, path: pathArg = null, pathGlob = null, ignoreCase = false, baseDir = '.', engine = 'auto', signal = null }) {
   if (typeof pattern !== 'string' || pattern === '') return { error: 'grep: pattern is required' };
+  const pathSupplied = pathArg != null && pathArg !== '';
+  if (pathSupplied) {
+    const plan = _resolveGrepPath(pathArg);
+    if (plan.mode === 'file') {
+      const raw = _grepFile({ pattern, ignoreCase, file: plan.file, display: plan.display, signal });
+      if (raw && (raw.error || raw.aborted)) return raw;
+      return _finalizeGrep(raw, pattern); // an existing file with 0 hits is a true negative, not an error
+    }
+    baseDir = plan.baseDir;
+    pathGlob = plan.pathGlob;
+  }
   const useRg = engine === 'rg' || (engine === 'auto' && !!_detectRipgrep());
   let raw;
   if (useRg) {
@@ -635,7 +744,17 @@ function _grepSearch({ pattern, pathGlob = null, ignoreCase = false, baseDir = '
     raw = _grepNode({ pattern, pathGlob, ignoreCase, baseDir, signal });
   }
   if (raw && (raw.error || raw.aborted)) return raw;
-  return _finalizeGrep(raw, pattern);
+  const out = _finalizeGrep(raw, pattern);
+  // Safety net (FIX 2): a `path` was supplied but there was NOTHING to search
+  // (path doesn't exist, or the glob/dir matched zero candidate files). Surface a
+  // diagnostic instead of a silent {count:0} that reads as "pattern absent". Gated
+  // strictly on zero CANDIDATE FILES — a glob that matched real files where the
+  // pattern just isn't present still returns {count:0} (a true negative).
+  if (out && !out.error && out.count === 0 && pathSupplied
+      && !_grepHasCandidate({ baseDir, pathGlob, signal })) {
+    return { error: `grep: path "${pathArg}" did not resolve to any file within the search root ${baseDir}` };
+  }
+  return out;
 }
 
 function _globSearch({ pattern, baseDir = '.', signal = null }) {
@@ -1170,6 +1289,53 @@ const TOOL_REGISTRY = [
       }
     },
   },
+  {
+    tool: 'view_image',
+    specNames: ['view_image'],
+    tags: ['view_image'],
+    // Both XML forms accepted: the attribute form `<view_image path="…"/>` and
+    // the inline form `<view_image>PATH</view_image>` (like read_file/download).
+    parseXml: (text) => {
+      const out = [];
+      for (const m of _matchDual(text, '<view_image\\s+path=Q([^Q]+)Q\\s*(?:><\\/view_image>|\\/>)')) {
+        out.push(['view_image', m[1]]);
+      }
+      for (const m of text.matchAll(/<view_image>([\s\S]*?)<\/view_image>/g)) {
+        out.push(['view_image', _unwrapInnerTag(m[1]).trim()]);
+      }
+      return out;
+    },
+    fromParams: (p) => (p.path ? ['view_image', String(p.path)] : null),
+    // Read-only: a local file read, so no permission gate (parity with read_file /
+    // grep, permission: () => null). Path safety + the size cap are enforced by
+    // readImage (via isPathSafe) inside execute, exactly as the /image command does.
+    permission: () => null,
+    // Stage a LOCAL image into vision context. Reuses readImage — the SAME encoder
+    // the /image slash command uses (read through isPathSafe, size-capped, magic-byte
+    // media-type detect, base64). The returned `image` record is collected by the
+    // agent loop and attached to the tool-result message's `images[]`, so api.js
+    // buildProviderMessages turns it into a provider image block on the next turn.
+    execute: async (ctx, args) => {
+      const [arg0 = null] = args;
+      const { _log, logToolCall, isPathSafe, getConfig, FG_GREEN, FG_GRAY, FG_RED, RST } = ctx;
+      const filePath = arg0;
+      try {
+        const { readImage } = require('./images');
+        const cfg = getConfig ? getConfig() : {};
+        const img = readImage(filePath, { maxBytes: cfg.image_max_bytes, isPathSafe });
+        const kb = Math.max(1, Math.round(img.bytes / 1024));
+        _log(`  ${FG_GREEN}✓${RST} ${FG_GRAY}Viewing image ${filePath} (${img.media_type}, ${kb} KB)${RST}`);
+        logToolCall('view_image', { path: filePath }, true, 'ok');
+        // `image` carries the base64 bytes for staging; it never enters the
+        // model-facing text (formatFileResult builds a short confirmation line).
+        return { status: 'ok', path: filePath, media_type: img.media_type, bytes: img.bytes, image: img };
+      } catch (error) {
+        _log(`  ${FG_RED}✗ ${error.message}${RST}`);
+        logToolCall('view_image', { path: filePath }, true, 'error');
+        return { error: error.message };
+      }
+    },
+  },
   {
     tool: 'write',
     specNames: ['write_file', 'create_file'],
@@ -1294,9 +1460,16 @@ const TOOL_REGISTRY = [
     permission: () => null,
     execute: async (ctx, args, options) => {
       const signal = (options && options.signal) || null;
-      const [pattern = null, pathGlob = null, ignoreCase = false, outputMode = null, headLimit, offset] = args;
-      const { _log, logToolCall, FG_GREEN, FG_GRAY, FG_RED, RST } = ctx;
-      const res = _grepSearch({ pattern, pathGlob, ignoreCase, baseDir: '.', engine: 'auto', signal });
+      const [pattern = null, pathArg = null, ignoreCase = false, outputMode = null, headLimit, offset] = args;
+      const { _log, logToolCall, isProtectedSecretPath, _secretReadError, FG_GREEN, FG_GRAY, FG_RED, RST } = ctx;
+      // Path-as-target now reads files directly, so apply the SAME secret-file read
+      // guard read_file/search_in_file use (the OS sandbox remains the outer
+      // confinement; this just refuses the credential/history files by name).
+      if (pathArg != null && pathArg !== '' && isProtectedSecretPath(pathArg)) {
+        logToolCall('grep', { pattern, path: pathArg }, false, 'denied');
+        return _secretReadError(pathArg);
+      }
+      const res = _grepSearch({ pattern, path: pathArg, ignoreCase, engine: 'auto', signal });
       if (res.aborted) { logToolCall('grep', { pattern }, true, 'aborted'); return res; }
       if (res.error) {
         _log(`  ${FG_RED}✗ ${res.error}${RST}`);
@@ -1310,7 +1483,7 @@ const TOOL_REGISTRY = [
       res.head_limit = _normHeadLimit(headLimit, require('./constants').DEFAULT_GREP_HEAD_LIMIT);
       res.offset = _normOffset(offset);
       _log(`  ${FG_GREEN}✓${RST} ${FG_GRAY}grep "${pattern}" — ${res.count} match(es)${RST}`);
-      logToolCall('grep', { pattern, path: pathGlob }, true, 'ok');
+      logToolCall('grep', { pattern, path: pathArg }, true, 'ok');
       return res;
     },
   },
@@ -1548,15 +1721,30 @@ const TOOL_REGISTRY = [
     tool: 'edit_file',
     specNames: ['edit_file'],
     tags: ['edit_file'],
-    parseXml: (text) => _matchDual(text, '<edit_file\\s+path=Q([^Q]+)Q\\s+line=Q(\\d+)Q>([\\s\\S]*?)<\\/edit_file>').map((m) => ['edit_file', m[1], parseInt(m[2], 10), m[3]]),
-    fromParams: (p) => (p.path && p.line !== undefined ? ['edit_file', p.path, parseInt(p.line, 10), p.content != null ? p.content : ''] : null),
-    permission: (ctx, args) => ({ actionType: 'file', description: `Edit line ${args[1]} in ${args[0]}`, tag: 'edit_file' }),
+    // Optional `end_line` (W.5 trailing-arg discipline: absent → the 4-element
+    // single-line tuple, byte-for-byte the prior behavior). When present, lines
+    // `line..end_line` are replaced wholesale by the content — a regex-free way
+    // to swap a block, pairing with read_file's start_line/end_line + line
+    // numbers (read a numbered slice, then replace that exact range).
+    parseXml: (text) => _matchDual(text, '<edit_file\\s+path=Q([^Q]+)Q\\s+line=Q(\\d+)Q(?:\\s+end_line=Q(\\d+)Q)?>([\\s\\S]*?)<\\/edit_file>').map((m) => {
+      const call = ['edit_file', m[1], parseInt(m[2], 10), m[4]];
+      if (m[3] != null) call.push(parseInt(m[3], 10));
+      return call;
+    }),
+    fromParams: (p) => {
+      if (!(p.path && p.line !== undefined)) return null;
+      const call = ['edit_file', p.path, parseInt(p.line, 10), p.content != null ? p.content : ''];
+      if (p.end_line != null) call.push(parseInt(p.end_line, 10));
+      return call;
+    },
+    permission: (ctx, args) => ({ actionType: 'file', description: args[4] != null ? `Edit lines ${args[1]}-${args[4]} in ${args[0]}` : `Edit line ${args[1]} in ${args[0]}`, tag: 'edit_file' }),
     execute: async (ctx, args) => {
-      const [arg0 = null, arg1 = null, arg2 = null] = args;
+      const [arg0 = null, arg1 = null, arg2 = null, arg3] = args;
       const { _log, logToolCall, isProtectedConfigPath, _protectedConfigWriteError, permissionManager, FG_GREEN, FG_GRAY, FG_RED, RST } = ctx;
       const filePath = arg0;
       const lineNum = arg1;
       const newContent = arg2;
+      const endLine = arg3; // undefined → single-line edit (unchanged)
       const blocked = permissionManager.readonlyBlock('edit_file');
       if (blocked) {
         logToolCall('edit_file', { path: filePath, line: lineNum }, false, 'denied');
@@ -1573,11 +1761,28 @@ const TOOL_REGISTRY = [
           logToolCall('edit_file', { path: filePath, line: lineNum }, true, 'error');
           return { error: `Line ${lineNum} out of range (file has ${lines.length} lines)` };
         }
-        lines[lineNum - 1] = newContent;
-        await fsp.writeFile(filePath, lines.join('\n'));
-        _log(`  ${FG_GREEN}✓${RST} ${FG_GRAY}Edited line ${lineNum} in ${filePath}${RST}`);
-        logToolCall('edit_file', { path: filePath, line: lineNum }, true, 'ok');
-        return { status: 'ok', path: filePath, line: lineNum };
+        if (endLine == null) {
+          // Single-line replace — exactly the prior behavior (no regression).
+          lines[lineNum - 1] = newContent;
+          const after = lines.join('\n');
+          await fsp.writeFile(filePath, after);
+          _log(`  ${FG_GREEN}✓${RST} ${FG_GRAY}Edited line ${lineNum} in ${filePath}${RST}`);
+          logToolCall('edit_file', { path: filePath, line: lineNum }, true, 'ok');
+          // _diffBefore/_diffAfter feed the execution-time diff renderer (onToolEnd).
+          return { status: 'ok', path: filePath, line: lineNum, _diffBefore: data, _diffAfter: after };
+        }
+        // Line-range replace: swap lines lineNum..endLine for newContent (which
+        // may itself be multi-line). No regex involved → no ReDoS surface.
+        if (endLine < lineNum || endLine > lines.length) {
+          logToolCall('edit_file', { path: filePath, line: lineNum, end_line: endLine }, true, 'error');
+          return { error: `Line range ${lineNum}-${endLine} out of range (file has ${lines.length} lines)` };
+        }
+        lines.splice(lineNum - 1, endLine - lineNum + 1, ...newContent.split('\n'));
+        const afterRange = lines.join('\n');
+        await fsp.writeFile(filePath, afterRange);
+        _log(`  ${FG_GREEN}✓${RST} ${FG_GRAY}Edited lines ${lineNum}-${endLine} in ${filePath}${RST}`);
+        logToolCall('edit_file', { path: filePath, line: lineNum, end_line: endLine }, true, 'ok');
+        return { status: 'ok', path: filePath, line: lineNum, end_line: endLine, _diffBefore: data, _diffAfter: afterRange };
       } catch (error) {
         _log(`  ${FG_RED}✗ ${error.message}${RST}`);
         logToolCall('edit_file', { path: filePath, line: lineNum }, true, 'error');
@@ -1594,7 +1799,7 @@ const TOOL_REGISTRY = [
     permission: () => null,
     execute: async (ctx, args) => {
       const [arg0 = null, arg1 = null] = args;
-      const { _log, logToolCall, isProtectedSecretPath, _secretReadError, _checkRegexSafety, FG_GREEN, FG_GRAY, FG_RED, RST } = ctx;
+      const { _log, logToolCall, isProtectedSecretPath, _secretReadError, _checkRegexSafety, _isLiteralPattern, FG_GREEN, FG_GRAY, FG_RED, RST } = ctx;
       const filePath = arg0;
       const pattern = arg1;
       if (isProtectedSecretPath(filePath)) {
@@ -1608,9 +1813,13 @@ const TOOL_REGISTRY = [
           logToolCall('search_in_file', { path: filePath, pattern }, true, 'error');
           return guardErr;
         }
-        const regex = new RegExp(pattern);
+        // A metacharacter-free pattern is matched literally (substring) — same
+        // line results as a regex for plain text, but unbounded by length so a
+        // long pasted block can be located. Genuine regexes still compile.
+        const isLiteral = _isLiteralPattern(pattern);
+        const test = isLiteral ? (content) => content.includes(pattern) : ((regex) => (content) => regex.test(content))(new RegExp(pattern));
         const matches = data.split('\n')
-          .map((content, idx) => regex.test(content) ? { line: idx + 1, content } : null)
+          .map((content, idx) => test(content) ? { line: idx + 1, content } : null)
           .filter(Boolean);
         _log(`  ${FG_GREEN}✓${RST} ${FG_GRAY}Found ${matches.length} match(es) in ${filePath}${RST}`);
         logToolCall('search_in_file', { path: filePath, pattern }, true, 'ok');
@@ -1626,16 +1835,43 @@ const TOOL_REGISTRY = [
     tool: 'replace_in_file',
     specNames: ['replace_in_file'],
     tags: ['replace_in_file'],
-    parseXml: (text) => _matchDual(text, '<replace_in_file\\s+path=Q([^Q]+)Q\\s+search=Q([^Q]*)Q\\s+replace=Q([^Q]*)Q>([\\s\\S]*?)<\\/replace_in_file>').map((m) => ['replace_in_file', m[1], m[2], m[3], m[4].trim()]),
-    fromParams: (p) => (p.path && p.search !== undefined ? ['replace_in_file', p.path, p.search, p.replace != null ? p.replace : '', p.flags || ''] : null),
+    // LITERAL by default (Claude Code Edit model): the search text is matched
+    // VERBATIM, byte-for-byte, no matter what regex-special chars it contains —
+    // so a copied code block with ( ) { } . [ ] just works. Regex is opt-in via
+    // `regex="true"`. Matching must be UNIQUE: 0 matches → error (no-op masked as
+    // success was the silent-corruption trap), >1 matches → error unless
+    // `replace_all="true"`. Inline body = regex flags (only meaningful with
+    // regex="true"). Attr-based parse (like read_file) so the optional flags
+    // appear in any order.
+    parseXml: (text) => {
+      const out = [];
+      const re = /<replace_in_file\b([^>]*?)>([\s\S]*?)<\/replace_in_file>/g;
+      for (const m of text.matchAll(re)) {
+        const attrStr = m[1] || '';
+        const body = m[2] != null ? m[2] : '';
+        const attr = (k) => {
+          const mm = attrStr.match(new RegExp(`${k}="([^"]*)"`)) || attrStr.match(new RegExp(`${k}='([^']*)'`));
+          return mm ? mm[1] : null;
+        };
+        const p = attr('path');
+        const search = attr('search');
+        if (p == null || search == null) continue;
+        const replace = attr('replace') != null ? attr('replace') : '';
+        out.push(['replace_in_file', p, search, replace, body.trim(), attr('regex') === 'true', attr('replace_all') === 'true']);
+      }
+      return out;
+    },
+    fromParams: (p) => (p.path && p.search !== undefined ? ['replace_in_file', p.path, p.search, p.replace != null ? p.replace : '', p.flags || '', p.regex === true || p.regex === 'true', p.replace_all === true || p.replace_all === 'true'] : null),
     permission: (ctx, args) => ({ actionType: 'file', description: `Replace in ${args[0]}`, tag: 'replace_in_file' }),
     execute: async (ctx, args) => {
-      const [arg0 = null, arg1 = null, arg2 = null, arg3 = null] = args;
+      const [arg0 = null, arg1 = null, arg2 = null, arg3 = null, arg4 = false, arg5 = false] = args;
       const { _log, logToolCall, isProtectedConfigPath, _protectedConfigWriteError, _checkRegexSafety, permissionManager, FG_GREEN, FG_GRAY, FG_RED, RST } = ctx;
       const filePath = arg0;
       const searchStr = arg1;
       const replaceStr = arg2;
       const flags = arg3 || '';
+      const useRegex = arg4 === true;
+      const replaceAll = arg5 === true;
       const blocked = permissionManager.readonlyBlock('replace_in_file');
       if (blocked) {
         logToolCall('replace_in_file', { path: filePath, search: searchStr }, false, 'denied');
@@ -1647,28 +1883,79 @@ const TOOL_REGISTRY = [
       }
       try {
         const data = await fsp.readFile(filePath, 'utf8');
-        const guardErr = _checkRegexSafety(searchStr, data);
-        if (guardErr) {
+        if (searchStr == null || searchStr === '') {
           logToolCall('replace_in_file', { path: filePath, search: searchStr }, true, 'error');
-          return guardErr;
+          return { error: 'replace_in_file: search string is empty — nothing to match.' };
+        }
+        let newData;
+        let count;
+        let remaining; // post-replace occurrences of the search string in newData
+        if (!useRegex) {
+          // LITERAL path (default): O(dataLen) substring match — no regex
+          // compiled, so a long block is matched verbatim with no ReDoS surface
+          // and no length bound. The replacement is raw text (no $1/$& handling).
+          const parts = data.split(searchStr);
+          count = parts.length - 1;
+          // ---- Uniqueness / occurrence guard (BEFORE writing) ----
+          if (count === 0) {
+            logToolCall('replace_in_file', { path: filePath, search: searchStr }, true, 'error');
+            return { error: `replace_in_file: search string not found in ${filePath} — file unchanged. Verify exact text including whitespace/indentation.` };
+          }
+          if (count > 1 && !replaceAll) {
+            const lines = _literalOccurrenceLines(data, searchStr);
+            const at = lines.length ? ` (matches start at line${lines.length > 1 ? 's' : ''} ${lines.join(', ')}${count > lines.length ? ', …' : ''})` : '';
+            logToolCall('replace_in_file', { path: filePath, search: searchStr }, true, 'error');
+            return { error: `replace_in_file: found ${count} matches but replace_all is not set${at}. Add surrounding context to uniquely identify ONE occurrence, or set replace_all:true to replace all ${count}.` };
+          }
+          if (replaceAll) {
+            newData = parts.join(replaceStr);
+          } else {
+            // count === 1: replace the single occurrence.
+            const idx = data.indexOf(searchStr);
+            newData = data.slice(0, idx) + replaceStr + data.slice(idx + searchStr.length);
+            count = 1;
+          }
+          remaining = newData.split(searchStr).length - 1;
+        } else {
+          // REGEX path (opt-in via regex:true): ReDoS guard applies. `g` flag OR
+          // replace_all replaces all; otherwise the match must be unique.
+          const guardErr = _checkRegexSafety(searchStr, data, false);
+          if (guardErr) {
+            logToolCall('replace_in_file', { path: filePath, search: searchStr }, true, 'error');
+            return guardErr;
+          }
+          const safeFlags = flags.replace(/[^gimsuy]/g, '');
+          const globalFlags = safeFlags.replace('g', '') + 'g';
+          const isGlobal = safeFlags.includes('g') || replaceAll;
+          count = (data.match(new RegExp(searchStr, globalFlags)) || []).length;
+          // ---- Uniqueness / occurrence guard (BEFORE writing) ----
+          if (count === 0) {
+            logToolCall('replace_in_file', { path: filePath, search: searchStr }, true, 'error');
+            return { error: `replace_in_file: pattern not found in ${filePath} — file unchanged. Verify the regex (or drop regex:true to match literally).` };
+          }
+          if (count > 1 && !isGlobal) {
+            logToolCall('replace_in_file', { path: filePath, search: searchStr }, true, 'error');
+            return { error: `replace_in_file: pattern matched ${count} times but neither the "g" flag nor replace_all is set. Refine the pattern to match ONE occurrence, or set replace_all:true to replace all ${count}.` };
+          }
+          const regex = new RegExp(searchStr, (isGlobal ? globalFlags : safeFlags.replace('g', '')) || undefined);
+          newData = data.replace(regex, replaceStr);
+          count = isGlobal ? count : 1;
+          remaining = (newData.match(new RegExp(searchStr, globalFlags)) || []).length;
         }
-        const safeFlags = flags.replace(/[^gimsuy]/g, '');
-        const regex = new RegExp(searchStr, safeFlags || undefined);
-        // Semantics (intentional, unchanged): String.prototype.replace replaces
-        // ALL matches only when the regex is global; without "g" it replaces just
-        // the first match. The returned count must equal the replacements actually
-        // performed — so count all matches when global, else 1 if there is a match
-        // (else 0). (Task 1.4c: previously count was computed with an always-global
-        // regex and overstated non-global replacements.)
-        const isGlobal = safeFlags.includes('g');
-        const count = isGlobal
-          ? (data.match(new RegExp(searchStr, safeFlags)) || []).length
-          : (new RegExp(searchStr, safeFlags).test(data) ? 1 : 0);
-        const newData = data.replace(regex, replaceStr);
         await fsp.writeFile(filePath, newData);
-        _log(`  ${FG_GREEN}✓${RST} ${FG_GRAY}Replaced ${count} occurrence(s) in ${filePath}${RST}`);
+        const result = { status: 'ok', path: filePath, count, _diffBefore: data, _diffAfter: newData };
+        // POST-REPLACE VERIFICATION: if the search string still appears (e.g. the
+        // replacement contains it, or matches overlapped), surface a warning
+        // instead of reporting clean success.
+        if (remaining > 0) {
+          result.warning = `replace_in_file: replaced ${count} occurrence(s), but the search string still appears ${remaining} time(s) in ${filePath} (the replacement may contain the search text, or matches overlapped).`;
+          _log(`  ${FG_GREEN}✓${RST} ${FG_GRAY}Replaced ${count} occurrence(s) in ${filePath} (${remaining} still present)${RST}`);
+        } else {
+          _log(`  ${FG_GREEN}✓${RST} ${FG_GRAY}Replaced ${count} occurrence(s) in ${filePath}${RST}`);
+        }
         logToolCall('replace_in_file', { path: filePath, search: searchStr }, true, 'ok');
-        return { status: 'ok', path: filePath, count };
+        // _diffBefore/_diffAfter feed the execution-time diff renderer (onToolEnd).
+        return result;
       } catch (error) {
         _log(`  ${FG_RED}✗ ${error.message}${RST}`);
         logToolCall('replace_in_file', { path: filePath, search: searchStr }, true, 'error');
@@ -2269,14 +2556,26 @@ const TOOL_REGISTRY = [
     tags: ['ask_user'],
     parseXml: (text) => _matchDual(text, '<ask_user\\s+question=Q([^Q]+)Q\\s*(?:><\\/ask_user>|\\/>)').map((m) => ['ask_user', m[1]]),
     fromParams: (p) => (p.question ? ['ask_user', p.question] : null),
-    permission: (ctx, args) => ({ actionType: 'user', description: `Ask user: ${args[0]}`, tag: 'ask_user' }),
+    // No permission descriptor: ask_user has no system side effects — it only
+    // prompts the interactive user, which IS the interaction. A separate "may I
+    // ask you?" gate would be pure friction (a double prompt before the real
+    // question/menu). A null descriptor also makes it available during plan mode
+    // (the plan-mode gate withholds only effectful tools, i.e. non-null
+    // descriptors), so the agent can ask clarifying questions while planning.
+    permission: () => null,
     execute: async (ctx, args) => {
       const [arg0 = null] = args;
-      const { _log, logToolCall, _parseNumberedOptions, permissionManager, writer, FG_YELLOW, FG_GRAY, RST, DIM } = ctx;
+      const { _log, logToolCall, _parseAskMenu, permissionManager, writer, FG_YELLOW, FG_GRAY, RST, DIM } = ctx;
       const question = arg0;
-      const options = _parseNumberedOptions(question);
+      // Display-only split: the menu gets ONLY the numbered options; the modal
+      // header gets ONLY the prose prompt (no duplication). The model-facing
+      // result below still carries the FULL original `question` (agent.js builds
+      // "User answered \"<question>\": <answer>" from it). Edge: a question with
+      // no prose before the numbers yields an empty prompt — fall back to the raw
+      // question so the modal never renders an empty header.
+      const { prompt, options } = _parseAskMenu(question);
       if (options.length >= 2) {
-        const selected = await permissionManager.captureSelect({ options });
+        const selected = await permissionManager.captureSelect({ prompt: prompt || question, options });
         logToolCall('ask_user', { question }, true, 'ok');
         return { question, answer: selected || options[0] };
       }
@@ -2543,6 +2842,11 @@ module.exports = {
   _grepSearch,
   _globSearch,
   _detectRipgrep,
+  // Path-aware grep target resolution + single-file grep (file/dir/glob path
+  // semantics + the unresolvable-path safety net). Exported for focused tests.
+  _resolveGrepPath,
+  _grepFile,
+  _grepHasCandidate,
   // grep output modes + bound normalizers (Task W.5).
   GREP_OUTPUT_MODES,
   _normGrepMode,