codemini-cli 0.3.4 → 0.3.6

package/src/core/tools.js

@@ -1,8 +1,8 @@
 import fs from 'node:fs/promises';
-import fsSync from 'node:fs';
 import path from 'node:path';
 import { spawn } from 'node:child_process';
 import net from 'node:net';
+import { escapeRegex, normalizePath } from './string-utils.js';
 import {
   classifyCommandIntent,
   hasReadyOutput,
@@ -13,22 +13,24 @@ import {
   terminateChild
 } from './shell.js';
 import { evaluateCommandPolicy } from './command-policy.js';
-import { queryAst, readAstNode, resolveAstTarget } from './ast.js';
+import { findEnclosingSymbol, queryAst, readAstNode, resolveAstTarget } from './ast.js';
 import { initializeProjectIndex, queryProjectIndex, refreshIndexedFile } from './project-index.js';
 import { checkReadDedup } from './agent-loop.js';
 import { TOOL_SKIP_DIRS as SKIP_DIRS, TEXT_EXTENSIONS, CODE_WRITE_GUARD_EXTENSIONS, LANGUAGE_FILE_TYPES } from './constants.js';
-import { sha256Prefixed as sha256, sha1 } from './crypto-utils.js';
+import { sha256Prefixed as sha256, sha256 as sha256Hash } from './crypto-utils.js';
 import { forgetMemory, listMemories, rememberMemory, searchMemories } from './memory-store.js';
 import { normalizeTodos } from './todo-state.js';
 const BACKGROUND_TASK_RECENT_OUTPUT_LIMIT = 80;
 const BACKGROUND_TASK_POLL_MS = 150;
+const MAX_AST_ENCLOSING_BYTES = 300_000;
+const MAX_AST_ENCLOSING_LINES = 5_000;
 const backgroundTaskRegistry = new Map();
 let backgroundTaskCounter = 0;
 let backgroundTaskLogCursorCounter = 0;
 
-function realpathIfExists(targetPath) {
+async function realpathIfExists(targetPath) {
   try {
-    return fsSync.realpathSync.native(targetPath);
+    return await fs.realpath(targetPath);
   } catch (error) {
     if (error?.code === 'ENOENT') return null;
     throw error;
@@ -40,11 +42,11 @@ function isWithinResolvedRoot(resolvedRoot, candidatePath) {
   return relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative));
 }
 
-function resolveInWorkspace(root, targetPath = '.') {
+async function resolveInWorkspace(root, targetPath = '.') {
   const absRoot = path.resolve(root);
-  const realRoot = fsSync.realpathSync.native(absRoot);
+  const realRoot = await fs.realpath(absRoot);
   const absTarget = path.resolve(absRoot, targetPath);
-  const realTarget = realpathIfExists(absTarget);
+  const realTarget = await realpathIfExists(absTarget);
   if (realTarget) {
     if (!isWithinResolvedRoot(realRoot, realTarget)) {
       throw new Error(`Path escapes workspace: ${targetPath}`);
@@ -53,13 +55,13 @@ function resolveInWorkspace(root, targetPath = '.') {
   }
 
   let probe = path.dirname(absTarget);
-  while (!realpathIfExists(probe)) {
+  while (!(await realpathIfExists(probe))) {
     const parent = path.dirname(probe);
     if (parent === probe) break;
     probe = parent;
   }
 
-  const resolvedProbe = realpathIfExists(probe);
+  const resolvedProbe = await realpathIfExists(probe);
   if (!resolvedProbe) {
     throw new Error(`Path escapes workspace: ${targetPath}`);
   }
@@ -71,12 +73,12 @@ function resolveInWorkspace(root, targetPath = '.') {
   return resolvedTarget;
 }
 
-function getBackgroundTasksDir(root) {
-  return path.join(resolveInWorkspace(root, '.codemini'), 'tasks');
+async function getBackgroundTasksDir(root) {
+  return path.join(await resolveInWorkspace(root, '.codemini'), 'tasks');
 }
 
 function toWorkspaceRelative(root, absPath) {
-  return path.relative(path.resolve(root), absPath).replace(/\\/g, '/');
+  return normalizePath(path.relative(path.resolve(root), absPath));
 }
 
 function trimLinePreview(line, maxLen = 180) {
@@ -85,10 +87,6 @@ function trimLinePreview(line, maxLen = 180) {
   return `${text.slice(0, maxLen - 3)}...`;
 }
 
-function escapeRegex(value) {
-  return String(value || '').replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-}
-
 function splitLines(text) {
   return String(text || '').split('\n');
 }
@@ -297,7 +295,7 @@ async function mapLimit(items, limit, worker) {
 const WALKER_CONCURRENCY = 8;
 
 async function walkTextFiles(root, startPath = '.', fileTypes = []) {
-  const abs = resolveInWorkspace(root, startPath);
+  const abs = await resolveInWorkspace(root, startPath);
   const allowedExts = new Set((Array.isArray(fileTypes) ? fileTypes : []).map((item) => `.${String(item || '').replace(/^\./, '')}`));
 
   async function visit(current) {
@@ -318,7 +316,7 @@ async function walkTextFiles(root, startPath = '.', fileTypes = []) {
 }
 
 async function walkWorkspaceEntries(root, startPath = '.', { includeHidden = false } = {}) {
-  const abs = resolveInWorkspace(root, startPath);
+  const abs = await resolveInWorkspace(root, startPath);
 
   async function visit(current) {
     const stat = await fs.stat(current);
@@ -369,41 +367,6 @@ function globToRegex(pattern) {
   return new RegExp(`^${regexBody}$`);
 }
 
-function getLineColumnForMatch(line, query, caseSensitive = false) {
-  const haystack = caseSensitive ? line : line.toLowerCase();
-  const needle = caseSensitive ? query : query.toLowerCase();
-  const index = haystack.indexOf(needle);
-  return index === -1 ? 1 : index + 1;
-}
-
-function classifyMatch(preview, query) {
-  const line = String(preview || '');
-  const escaped = escapeRegex(query);
-  const normalized = line.toLowerCase();
-  const queryLower = String(query || '').toLowerCase();
-  const definitionLeadPatterns = [
-    /^\s*(?:export\s+)?(?:async\s+)?function\b/i,
-    /^\s*(?:export\s+)?class\b/i,
-    /^\s*(?:export\s+)?(?:const|let|var)\b/i,
-    /^\s*(?:export\s+)?(?:interface|type|enum)\b/i,
-    /^\s*def\b/i,
-    /^\s*(?:public|private|protected)\s+[A-Za-z0-9_<>,[\]\s?]+\s+[A-Za-z0-9_$]+\s*\(/i
-  ];
-  if (definitionLeadPatterns.some((pattern) => pattern.test(line)) && normalized.includes(queryLower)) {
-    return 'definition';
-  }
-  if (new RegExp(String.raw`\b${escaped}\s*\(`, 'i').test(line)) return 'reference';
-  return 'text';
-}
-
-function matchSpecificity(preview, query) {
-  const line = String(preview || '');
-  const escaped = escapeRegex(query);
-  if (new RegExp(String.raw`\b${escaped}\b`, 'i').test(line)) return 0;
-  if (line.toLowerCase().includes(String(query || '').toLowerCase())) return 1;
-  return 2;
-}
-
 function findSymbolDefinition(lines, symbol) {
   const escaped = String(symbol || '').replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
   const patterns = [
@@ -555,7 +518,7 @@ function extractDirectCalls(lines, symbol, maxItems = 3, excludeRange = null) {
     if (excludeRange && i + 1 >= excludeRange.startLine && i + 1 <= excludeRange.endLine) continue;
     const line = String(lines[i] || '');
     if (!new RegExp(String.raw`\b${escaped}\s*\(`).test(line)) continue;
-    const blockLine = findEnclosingSymbol(lines, i + 1);
+    const blockLine = findEnclosingSymbolLine(lines, i + 1);
     const owner = blockLine ? trimLinePreview(lines[blockLine - 1], 220) : trimLinePreview(line, 220);
     const ownerName = blockLine ? extractSymbolName(lines[blockLine - 1]) : '';
     if (ownerName === symbol) continue;
@@ -578,7 +541,7 @@ function extractSymbolName(line) {
   return match?.[1] || '';
 }
 
-function findEnclosingSymbol(lines, anchorLine) {
+function findEnclosingSymbolLine(lines, anchorLine) {
   for (let i = Math.max(0, anchorLine - 1); i >= 0; i -= 1) {
     const name = extractSymbolName(lines[i]);
     if (name) return i + 1;
@@ -620,131 +583,8 @@ function buildUnifiedDiff(oldContent, newContent, filePath = 'file') {
   return body.join('\n');
 }
 
-function parseUnifiedPatch(patchText) {
-  const lines = splitLines(String(patchText || ''));
-  const files = [];
-  let current = null;
-
-  const pushCurrent = () => {
-    if (current) files.push(current);
-  };
-
-  for (let i = 0; i < lines.length; i += 1) {
-    const line = lines[i];
-    if (line.startsWith('--- ')) {
-      pushCurrent();
-      current = {
-        oldPath: line.slice(4).trim(),
-        newPath: '',
-        hunks: []
-      };
-      continue;
-    }
-    if (!current) continue;
-    if (line.startsWith('+++ ')) {
-      current.newPath = line.slice(4).trim();
-      continue;
-    }
-    if (line.startsWith('@@ ')) {
-      const match = line.match(/^@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@/);
-      if (!match) {
-        throw new Error(`invalid patch hunk header: ${line}`);
-      }
-      const hunk = {
-        oldStart: Number(match[1]),
-        oldCount: Number(match[2] || '1'),
-        newStart: Number(match[3]),
-        newCount: Number(match[4] || '1'),
-        lines: []
-      };
-      i += 1;
-      while (i < lines.length) {
-        const hunkLine = lines[i];
-        if (hunkLine.startsWith('@@ ') || hunkLine.startsWith('--- ')) {
-          i -= 1;
-          break;
-        }
-        if (hunkLine.startsWith('\')) {
-          i += 1;
-          continue;
-        }
-        if (hunkLine === '') {
-          hunk.lines.push(' ');
-          i += 1;
-          continue;
-        }
-        if (!/^[ +\-]/.test(hunkLine)) {
-          hunk.lines.push(` ${hunkLine}`);
-          i += 1;
-          continue;
-        }
-        if (!/^[ +\-]/.test(hunkLine)) {
-          throw new Error(`invalid patch line: ${hunkLine}`);
-        }
-        hunk.lines.push(hunkLine);
-        i += 1;
-      }
-      current.hunks.push(hunk);
-    }
-  }
-
-  pushCurrent();
-  return files.filter((file) => file.oldPath || file.newPath);
-}
-
-function applyHunkToLines(lines, hunk) {
-  const oldChunk = [];
-  const newChunk = [];
-  for (const line of hunk.lines) {
-    if (line.startsWith(' ')) {
-      const text = line.slice(1);
-      oldChunk.push(text);
-      newChunk.push(text);
-      continue;
-    }
-    if (line.startsWith('-')) {
-      oldChunk.push(line.slice(1));
-      continue;
-    }
-    if (line.startsWith('+')) {
-      newChunk.push(line.slice(1));
-    }
-  }
-
-  if (oldChunk.length === 0) {
-    const insertAt = Math.max(0, Number(hunk.oldStart || 1) - 1);
-    return [...lines.slice(0, insertAt), ...newChunk, ...lines.slice(insertAt)];
-  }
-
-  const lastStart = Math.max(0, lines.length - oldChunk.length);
-  const matches = [];
-  for (let start = 0; start <= lastStart; start += 1) {
-    let ok = true;
-    for (let offset = 0; offset < oldChunk.length; offset += 1) {
-      if (lines[start + offset] !== oldChunk[offset]) {
-        ok = false;
-        break;
-      }
-    }
-    if (ok) {
-      matches.push(start);
-      if (matches.length > 1) break;
-    }
-  }
-
-  if (matches.length === 0) {
-    throw new Error('patch hunk context not found');
-  }
-  if (matches.length > 1) {
-    throw new Error('patch hunk context not unique');
-  }
-
-  const start = matches[0];
-  return [...lines.slice(0, start), ...newChunk, ...lines.slice(start + oldChunk.length)];
-}
-
 async function getFileState(root, relativePath) {
-  const target = resolveInWorkspace(root, relativePath);
+  const target = await resolveInWorkspace(root, relativePath);
   const stat = await fs.stat(target);
   const content = await fs.readFile(target, 'utf8');
   return {
@@ -757,7 +597,7 @@ async function getFileState(root, relativePath) {
 
 async function readFile(root, args) {
   const normalizedArgs = normalizeReadArgs(args);
-  const target = resolveInWorkspace(root, normalizedArgs?.path);
+  const target = await resolveInWorkspace(root, normalizedArgs?.path);
   const stat = await fs.stat(target);
   const text = await fs.readFile(target, 'utf8');
   const lines = splitLines(text);
@@ -777,7 +617,7 @@ async function readFile(root, args) {
   endLine = Math.max(startLine, Math.min(endLine, totalLines));
 
   const tokenSeed = `${normalizedArgs?.path}|${stat.size}|${stat.mtimeMs}|${startLine}|${endLine}`;
-  const readToken = sha1(tokenSeed).slice(0, 16);
+  const readToken = sha256Hash(tokenSeed).slice(0, 16);
 
   if (wantsMetadataOnly) {
     return {
@@ -820,6 +660,11 @@ async function readFile(root, args) {
     };
   }
 
+  // Resolve enclosing structural symbol via Tree-sitter (best-effort, skipped for large files)
+  const shouldResolveEnclosing = text.length <= MAX_AST_ENCLOSING_BYTES && totalLines <= MAX_AST_ENCLOSING_LINES;
+  const anchorLine = Math.floor((startLine + endLine) / 2);
+  const enclosing = shouldResolveEnclosing ? await findEnclosingSymbol(text, normalizedArgs?.path, anchorLine) : null;
+
   return {
     path: normalizedArgs?.path,
     phase: 'content',
@@ -827,7 +672,8 @@ async function readFile(root, args) {
     end_line: endLine,
     total_lines: totalLines,
     truncated,
-    content
+    content,
+    ...(enclosing ? { enclosing_symbol: enclosing.name, enclosing_kind: enclosing.kind, enclosing_line: enclosing.start_line } : {})
   };
 }
 
@@ -840,7 +686,7 @@ async function writeFile(root, args) {
   if (rawPath === '.' || rawPath === './') {
     throw new Error('write requires a file path, not the workspace root');
   }
-  const target = resolveInWorkspace(root, rawPath);
+  const target = await resolveInWorkspace(root, rawPath);
   try {
     const stat = await fs.stat(target);
     if (stat.isDirectory()) {
@@ -889,6 +735,63 @@ async function writeFile(root, args) {
   };
 }
 
+async function prepareDeleteTarget(root, args) {
+  const normalizedArgs = normalizePathArgs(args, ['file', 'file_path', 'target', 'directory', 'dir']);
+  const rawPath = String(normalizedArgs?.path || '').trim();
+  if (!rawPath) {
+    throw new Error('delete requires a file or directory path');
+  }
+  const absRoot = path.resolve(root);
+  const realRoot = await fs.realpath(absRoot);
+  const originalTarget = path.resolve(absRoot, rawPath);
+  if (originalTarget === absRoot) {
+    throw new Error('delete requires a path inside the workspace, not the workspace root');
+  }
+  const resolvedTarget = await resolveInWorkspace(root, rawPath);
+  if (resolvedTarget === realRoot) {
+    throw new Error('delete requires a path inside the workspace, not the workspace root');
+  }
+
+  let rawStat;
+  let stat;
+  try {
+    rawStat = await fs.lstat(originalTarget);
+  } catch (error) {
+    if (error?.code === 'ENOENT') {
+      throw new Error(`delete target not found: ${rawPath}`);
+    }
+    throw error;
+  }
+  try {
+    stat = await fs.stat(resolvedTarget);
+  } catch (error) {
+    if (error?.code !== 'ENOENT') throw error;
+  }
+
+  const type = stat?.isDirectory?.() ? 'directory' : rawStat.isDirectory() ? 'directory' : 'file';
+  const pathInWorkspace = toWorkspaceRelative(root, originalTarget);
+  return {
+    originalTarget,
+    resolvedTarget,
+    path: pathInWorkspace,
+    name: path.basename(pathInWorkspace),
+    type
+  };
+}
+
+async function deletePath(root, args) {
+  const target = await prepareDeleteTarget(root, args);
+  await fs.rm(target.originalTarget, { recursive: true, force: false });
+
+  return {
+    ok: true,
+    path: target.path,
+    name: target.name,
+    type: target.type,
+    deleted: true
+  };
+}
+
 async function runCommand(root, config, args) {
   const command = args?.command || '';
   if (!command.trim()) {
@@ -1086,7 +989,7 @@ async function startBackgroundTask(root, config, args) {
   const successMatchers = normalizeSuccessMatchers(args?.success_matchers || args?.successMatchers);
   const portProbe = Number(args?.port_probe || args?.portProbe || 0) || 0;
   const httpProbe = normalizeHttpProbe(args?.http_probe || args?.httpProbe);
-  const outputDir = getBackgroundTasksDir(root);
+  const outputDir = await getBackgroundTasksDir(root);
   await fs.mkdir(outputDir, { recursive: true });
   const outputFileAbs = path.join(outputDir, `${taskId}.log`);
   await fs.writeFile(outputFileAbs, '', 'utf8');
@@ -1229,68 +1132,6 @@ async function stopBackgroundTask(_root, args) {
   return { ...snapshotBackgroundTask(task), stopped: true };
 }
 
-async function searchCode(root, args) {
-  const query = String(args?.query || args?.symbol || '').trim();
-  if (!query) throw new Error('search_code requires query');
-  const maxResults = Math.max(1, Math.min(50, Number(args?.max_results || 12)));
-  const caseSensitive = Boolean(args?.case_sensitive);
-  const files = await walkTextFiles(root, args?.path || '.', normalizeFileTypes(args));
-  const matches = [];
-
-  for (const filePath of files) {
-    const content = await fs.readFile(filePath, 'utf8');
-    const lines = splitLines(content);
-    for (let idx = 0; idx < lines.length; idx += 1) {
-      const line = lines[idx];
-      const haystack = caseSensitive ? line : line.toLowerCase();
-      const needle = caseSensitive ? query : query.toLowerCase();
-      if (!haystack.includes(needle)) continue;
-      matches.push({
-        file: toWorkspaceRelative(root, filePath),
-        line: idx + 1,
-        column: getLineColumnForMatch(line, query, caseSensitive),
-        preview: trimLinePreview(line),
-        kind: classifyMatch(line, query),
-        symbolHint: query
-      });
-      if (matches.length >= maxResults) {
-        matches.sort((left, right) => {
-          const kindRank = { definition: 0, reference: 1, text: 2 };
-          const specificity = matchSpecificity(left.preview, query) - matchSpecificity(right.preview, query);
-          if (specificity !== 0) return specificity;
-          if (kindRank[left.kind] !== kindRank[right.kind]) return kindRank[left.kind] - kindRank[right.kind];
-          return left.file.localeCompare(right.file) || left.line - right.line;
-        });
-        return {
-          query,
-          matches,
-          definitions: matches.filter((item) => item.kind === 'definition'),
-          references: matches.filter((item) => item.kind === 'reference'),
-          text_matches: matches.filter((item) => item.kind === 'text'),
-          truncated: true
-        };
-      }
-    }
-  }
-
-  matches.sort((left, right) => {
-    const kindRank = { definition: 0, reference: 1, text: 2 };
-    const specificity = matchSpecificity(left.preview, query) - matchSpecificity(right.preview, query);
-    if (specificity !== 0) return specificity;
-    if (kindRank[left.kind] !== kindRank[right.kind]) return kindRank[left.kind] - kindRank[right.kind];
-    return left.file.localeCompare(right.file) || left.line - right.line;
-  });
-
-  return {
-    query,
-    matches,
-    definitions: matches.filter((item) => item.kind === 'definition'),
-    references: matches.filter((item) => item.kind === 'reference'),
-    text_matches: matches.filter((item) => item.kind === 'text'),
-    truncated: false
-  };
-}
-
 async function grep(root, args) {
   const normalizedArgs = normalizePatternArgs(args, ['query', 'symbol', 'q'], ['directory', 'dir', 'cwd']);
   const pattern = String(normalizedArgs?.pattern || '').trim();
@@ -1349,7 +1190,7 @@ async function glob(root, args) {
 async function list(root, args) {
   const normalizedArgs = normalizePathArgs(args, ['dir', 'directory', 'target']);
   const relativePath = String(normalizedArgs?.path || '.').trim() || '.';
-  const target = resolveInWorkspace(root, relativePath);
+  const target = await resolveInWorkspace(root, relativePath);
   const entries = await fs.readdir(target, { withFileTypes: true });
   const includeHidden = Boolean(normalizedArgs?.include_hidden);
   const items = entries
@@ -1529,70 +1370,6 @@ async function insertRelative(root, args, mode) {
   return editResult(relativePath, mode, state.content, afterContent, changedLine);
 }
 
-async function generateDiff(root, args) {
-  const relativePath = String(args?.path || '').trim();
-  if (!relativePath) throw new Error('generate_diff requires path');
-  const state = await getFileState(root, relativePath);
-  const newContent = String(args?.new_content || '');
-  return {
-    path: relativePath,
-    old_hash: sha256(state.content),
-    new_hash: sha256(newContent),
-    diff: buildUnifiedDiff(state.content, newContent, relativePath)
-  };
-}
-
-async function applyPatch(root, args) {
-  const patchText = String(args?.patch || args?.content || '').trim();
-  if (!patchText) throw new Error('patch requires patch content');
-  const files = parseUnifiedPatch(patchText);
-  if (files.length === 0) throw new Error('patch contains no file changes');
-
-  const results = [];
-  for (const fileChange of files) {
-    const newPath = String(fileChange.newPath || '').trim();
-    const oldPath = String(fileChange.oldPath || '').trim();
-    const targetPath = newPath && newPath !== '/dev/null' ? newPath : oldPath;
-    if (!targetPath || targetPath === '/dev/null') {
-      throw new Error('patch requires a target file path');
-    }
-    const absTarget = resolveInWorkspace(root, targetPath);
-    let beforeContent = '';
-    let beforeLines = [];
-    try {
-      beforeContent = await fs.readFile(absTarget, 'utf8');
-      beforeLines = splitLines(beforeContent);
-    } catch (error) {
-      if (!(error && error.code === 'ENOENT')) throw error;
-    }
-
-    let nextLines = beforeLines;
-    for (const hunk of fileChange.hunks) {
-      nextLines = applyHunkToLines(nextLines, hunk);
-    }
-    const afterContent = nextLines.join('\n');
-
-    if (newPath === '/dev/null') {
-      await fs.rm(absTarget, { force: true });
-      results.push({
-        path: targetPath,
-        action: 'delete',
-        changed_line: 1,
-        diff_preview: `deleted ${targetPath}`,
-        diff: buildUnifiedDiff(beforeContent, '', targetPath),
-        new_hash: sha256('')
-      });
-      continue;
-    }
-
-    await fs.mkdir(path.dirname(absTarget), { recursive: true });
-    await fs.writeFile(absTarget, afterContent, 'utf8');
-    results.push(editResult(targetPath, beforeContent ? 'patch' : 'create', beforeContent, afterContent, 1));
-  }
-
-  return results.length === 1 ? results[0] : { ok: true, files: results };
-}
-
 async function openTarget(root, args) {
   const file = String(args?.file || args?.path || '').trim();
   if (!file) throw new Error('open_target requires file');
@@ -1843,7 +1620,7 @@ export function getBuiltinTools({ workspaceRoot = process.cwd(), config, onSyste
       function: {
         name: 'read',
         description:
-          'Inspect a file and return content directly by default. Demo-style aliases like file_path, offset, and limit are accepted. Use metadata_only=true only when you want file metadata without content. Do not use run with cat, head, or tail for file reads.',
+          'Inspect code or text files. Use read(path) for normal file or line-window reads, read(ast_target=...) for a node-scoped AST read, and read(path, query=..., capture_name=...) to run an inline Tree-sitter query before returning the first matched node. Prefer the AST forms when targeting a function, class, or method and you want tighter context. Demo-style aliases like file_path, offset, and limit are accepted. Use metadata_only=true only when you want file metadata without content. Do not use run with cat, head, or tail for file reads.',
         parameters: {
           type: 'object',
           properties: {
@@ -1856,7 +1633,11 @@ export function getBuiltinTools({ workspaceRoot = process.cwd(), config, onSyste
             max_chars: { type: 'number', description: 'Max chars to return' },
             include_content: { type: 'boolean', description: 'Legacy compatibility flag. Content is returned by default.' },
             read_token: { type: 'string', description: 'Legacy compatibility token. No longer required for content reads.' },
-            metadata_only: { type: 'boolean', description: 'Set true to return metadata without content.' }
+            metadata_only: { type: 'boolean', description: 'Set true to return metadata without content.' },
+            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.' },
+            capture_name: { type: 'string', description: 'Optional capture name to select when query is provided.' },
+            language: { type: 'string', description: 'Optional Tree-sitter language override for AST reads or inline queries.' }
           },
           required: []
         }
@@ -1900,6 +1681,26 @@ export function getBuiltinTools({ workspaceRoot = process.cwd(), config, onSyste
         }
       }
     },
+    {
+      type: 'function',
+      function: {
+        name: 'glob',
+        description:
+          'Find files by glob pattern. Use this when you already know a filename pattern such as src/**/*.ts. Aliases like query and directory are accepted.',
+        parameters: {
+          type: 'object',
+          properties: {
+            pattern: { type: 'string', description: 'Glob pattern' },
+            path: { type: 'string', description: 'Directory to search' },
+            query: { type: 'string', description: 'Alias for pattern' },
+            directory: { type: 'string', description: 'Alias for path' },
+            include_hidden: { type: 'boolean', description: 'Include dotfiles' },
+            max_results: { type: 'number', description: 'Max results' }
+          },
+          required: ['pattern']
+        }
+      }
+    },
     {
       type: 'function',
       function: {
@@ -1923,7 +1724,7 @@ export function getBuiltinTools({ workspaceRoot = process.cwd(), config, onSyste
       function: {
         name: 'edit',
         description:
-          'Edit existing files. Prefer one of these shapes: 1) {file, old_text, new_text} for exact text replacement, 2) {file, symbol, edit:{kind:"replace_block", new_content:"..."}} for block replacement, 3) {file, anchor_text, position:"before"|"after", content:"..."} for inserts. Demo-style aliases {file_path, old_string, new_string} are also accepted. Read first unless the exact target is already known. Prefer this over write for existing code changes.',
+          'Edit existing files. Prefer one of these shapes: 1) {file, old_text, new_text} for exact text replacement, 2) {file, symbol, edit:{kind:"replace_block", new_content:"..."}} for block replacement, 3) {file, anchor_text, position:"before"|"after", content:"..."} for inserts. Demo-style aliases {file_path, old_string, new_string} are also accepted. Read first unless the exact target is already known, and prefer read(ast_target=...) or read(path, query=...) before symbol- or block-level edits when you want tighter context. Prefer this over write for existing code changes.',
         parameters: {
           type: 'object',
           properties: {
@@ -1971,6 +1772,25 @@ export function getBuiltinTools({ workspaceRoot = process.cwd(), config, onSyste
         }
       }
     },
+    {
+      type: 'function',
+      function: {
+        name: 'delete',
+        description:
+          'Delete a file or directory inside the workspace. Use path, file, or file_path to point at the target. Missing targets fail. Workspace escape attempts are rejected.',
+        parameters: {
+          type: 'object',
+          properties: {
+            path: { type: 'string', description: 'File or directory path to delete' },
+            file: { type: 'string', description: 'Alias for path' },
+            file_path: { type: 'string', description: 'Alias for path' },
+            directory: { type: 'string', description: 'Alias for path' },
+            dir: { type: 'string', description: 'Alias for path' }
+          },
+          required: ['path']
+        }
+      }
+    },
     {
       type: 'function',
       function: {
@@ -2053,7 +1873,7 @@ export function getBuiltinTools({ workspaceRoot = process.cwd(), config, onSyste
       function: {
         name: 'ast_query',
         description:
-          'Run a Tree-sitter query on a code file and return ast_target objects. Use this when you need node-scoped reads or edits for functions, classes, or methods.',
+          'Run a Tree-sitter query on a code file and return ast_target objects. Use this for advanced AST workflows such as multi-match selection, explicit node caching, or when you plan to reuse ast_target across follow-up reads or edits. For a common one-shot function, class, or method read, prefer read(path, query=...) or read(ast_target=...).',
         parameters: {
           type: 'object',
           properties: {
@@ -2067,32 +1887,12 @@ export function getBuiltinTools({ workspaceRoot = process.cwd(), config, onSyste
         }
       }
     },
-    glob: {
-      type: 'function',
-      function: {
-        name: 'glob',
-        description:
-          'Find files by glob pattern. Use this when you already know a filename pattern such as src/**/*.ts. Aliases like query and directory are accepted.',
-        parameters: {
-          type: 'object',
-          properties: {
-            pattern: { type: 'string', description: 'Glob pattern' },
-            path: { type: 'string', description: 'Directory to search' },
-            query: { type: 'string', description: 'Alias for pattern' },
-            directory: { type: 'string', description: 'Alias for path' },
-            include_hidden: { type: 'boolean', description: 'Include dotfiles' },
-            max_results: { type: 'number', description: 'Max results' }
-          },
-          required: ['pattern']
-        }
-      }
-    },
     read_ast_node: {
       type: 'function',
       function: {
         name: 'read_ast_node',
         description:
-          'Read a previously selected AST node with compact structural context. Use this after ast_query before a scoped structural edit.',
+          'Read a previously selected AST node with compact structural context. Use this after ast_query when you want an explicit follow-up read of a cached node before a scoped structural edit. For common one-shot AST reads, prefer read(ast_target=...) or read(path, query=...).',
         parameters: {
           type: 'object',
           properties: {
@@ -2104,36 +1904,6 @@ export function getBuiltinTools({ workspaceRoot = process.cwd(), config, onSyste
         }
       }
     },
-    generate_diff: {
-      type: 'function',
-      function: {
-        name: 'generate_diff',
-        description: 'Generate a unified diff for proposed content. Use this when you want to preview or prepare a patch before applying it.',
-        parameters: {
-          type: 'object',
-          properties: {
-            path: { type: 'string' },
-            new_content: { type: 'string' }
-          },
-          required: ['path', 'new_content']
-        }
-      }
-    },
-    patch: {
-      type: 'function',
-      function: {
-        name: 'patch',
-        description: 'Apply one or more unified diff hunks to workspace files. Use this for prepared unified diffs instead of ad-hoc shell patching.',
-        parameters: {
-          type: 'object',
-          properties: {
-            patch: { type: 'string' },
-            content: { type: 'string' }
-          },
-          required: ['patch']
-        }
-      }
-    },
     remember_user: {
       type: 'function',
       function: {
@@ -2274,19 +2044,63 @@ export function getBuiltinTools({ workspaceRoot = process.cwd(), config, onSyste
   const definitions = [...primaryDefinitions];
 
   const handlers = {
-    read: (args) =>
-      readFile(workspaceRoot, {
+    read: async (args) => {
+      const inlineQuery = String(args?.query || '').trim();
+      const directAstTarget = args?.ast_target;
+
+      if (directAstTarget) {
+        const result = await readAstNode(workspaceRoot, {
+          ...args,
+          path: args?.path || directAstTarget?.path,
+          ast_target: directAstTarget
+        });
+        if (directAstTarget?.path) rememberAstSelection(directAstTarget.path, directAstTarget);
+        const readPath = String(result?.path || directAstTarget?.path || '').trim();
+        if (readPath) lastReadPath = readPath;
+        return result;
+      }
+
+      if (inlineQuery) {
+        const queryResult = await queryAst(workspaceRoot, args);
+        const firstTarget = queryResult?.matches?.[0]?.ast_target;
+        if (!firstTarget) {
+          return {
+            path: String(args?.path || '').trim(),
+            language: queryResult?.language,
+            query: inlineQuery,
+            capture_name: String(args?.capture_name || '').trim() || undefined,
+            matches: 0,
+            content: ''
+          };
+        }
+        rememberAstSelection(firstTarget.path, firstTarget);
+        const result = await readAstNode(workspaceRoot, {
+          ...args,
+          path: firstTarget.path,
+          ast_target: firstTarget
+        });
+        const readPath = String(result?.path || firstTarget?.path || '').trim();
+        if (readPath) lastReadPath = readPath;
+        return {
+          ...result,
+          query: inlineQuery,
+          capture_name: String(args?.capture_name || '').trim() || undefined,
+          matches: queryResult.matches.length
+        };
+      }
+
+      const result = await readFile(workspaceRoot, {
         ...args,
         default_lines: config.context?.read_file_default_lines ?? 220,
         max_chars:
           typeof args?.max_chars === 'number'
             ? args.max_chars
             : config.context?.read_file_max_chars ?? 24000
-      }).then((result) => {
-        const readPath = String(result?.path || args?.path || '').trim();
-        if (readPath) lastReadPath = readPath;
-        return result;
-      }),
+      });
+      const readPath = String(result?.path || args?.path || '').trim();
+      if (readPath) lastReadPath = readPath;
+      return result;
+    },
     query_project_index: async (args) => {
       await ensureProjectIndex();
       return queryProjectIndex(workspaceRoot, args);
@@ -2317,24 +2131,27 @@ export function getBuiltinTools({ workspaceRoot = process.cwd(), config, onSyste
       if (result?.path) await refreshProjectFile(result.path);
       return result;
     },
-    generate_diff: (args) => generateDiff(workspaceRoot, args),
-    patch: async (args) => {
+    write: async (args) => {
       await ensureProjectIndex();
-      const result = await applyPatch(workspaceRoot, args);
+      const result = await writeFile(workspaceRoot, args);
       if (result?.path) await refreshProjectFile(result.path);
-      if (Array.isArray(result?.files)) {
-        for (const item of result.files) {
-          if (item?.path) await refreshProjectFile(item.path);
-        }
-      }
       return result;
     },
-    write: async (args) => {
+    delete: Object.assign(async (args) => {
       await ensureProjectIndex();
-      const result = await writeFile(workspaceRoot, args);
+      const result = await deletePath(workspaceRoot, args);
       if (result?.path) await refreshProjectFile(result.path);
       return result;
-    },
+    }, {
+      prepareApproval: async (args) => {
+        const target = await prepareDeleteTarget(workspaceRoot, args);
+        return {
+          path: target.path,
+          name: target.name,
+          type: target.type
+        };
+      }
+    }),
     update_todos: async (args = {}) => {
       const oldTodos = normalizeTodos(typeof getTodos === 'function' ? getTodos() : []);
       const nextTodos = normalizeTodos(args?.todos);
@@ -2427,13 +2244,18 @@ export function getBuiltinTools({ workspaceRoot = process.cwd(), config, onSyste
     read(result) {
       if (typeof result === 'string') return result;
       if (!result || typeof result !== 'object') return String(result);
+      if (result.node && typeof result.content === 'string') {
+        const header = `[AST: ${result.path || '?'} ${result.node.node_type || 'node'} ${result.node.start_line || '?'}-${result.node.end_line || '?'}${result.matches ? `, matches ${result.matches}` : ''}]`;
+        return `${header}\n${result.content}`;
+      }
       // Phase 1 metadata: small, return as-is
       if (result.phase === 'metadata') {
         return JSON.stringify(result);
       }
       // Phase 2 content: structured header + head/tail content
       if (result.phase === 'content') {
-        const header = `[File: ${result.path}, lines ${result.start_line || 1}-${result.end_line || '?'}${result.total_lines ? ` of ${result.total_lines}` : ''}${result.truncated ? ', truncated' : ''}]`;
+        const enclosing = result.enclosing_symbol ? `, inside ${result.enclosing_kind || 'symbol'} ${result.enclosing_symbol}` : '';
+        const header = `[File: ${result.path}, lines ${result.start_line || 1}-${result.end_line || '?'}${result.total_lines ? ` of ${result.total_lines}` : ''}${result.truncated ? ', truncated' : ''}${enclosing}]`;
         const content = result.content || '';
         if (typeof content !== 'string' || content.length <= 3000) {
           return `${header}\n${content}`;
@@ -2545,6 +2367,14 @@ export function getBuiltinTools({ workspaceRoot = process.cwd(), config, onSyste
       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}`;
+    },
+
     run(result) {
       if (!result || typeof result !== 'object') return String(result);
       if (result.background) {
@@ -2598,25 +2428,6 @@ export function getBuiltinTools({ workspaceRoot = process.cwd(), config, onSyste
       return `removed ${Number(result?.removed || 0)} memory item(s)`;
     },
 
-    generate_diff(result) {
-      if (!result || typeof result !== 'object') return String(result);
-      const p = result.path || '';
-      const diff = result.diff || '';
-      if (diff.length <= 2000) return `${p ? `[${p}]\n` : ''}${diff}`;
-      return `${p ? `[${p}]\n` : ''}${diff.slice(0, 1997)}...\n[diff truncated: ${diff.length} chars total]`;
-    },
-
-    patch(result) {
-      if (!result || typeof result !== 'object') return String(result);
-      if (Array.isArray(result.files)) {
-        const names = result.files.slice(0, 10).map((f) => typeof f === 'string' ? f : f.path || '?');
-        return `patched ${result.files.length} file(s): ${names.join(', ')}${result.files.length > 10 ? ` ... +${result.files.length - 10} more` : ''}`;
-      }
-      const p = result.path || '';
-      const line = result.changed_line || 0;
-      return `patched ${p}${line > 0 ? ` @L${line}` : ''}${result.ok === false ? ` [FAILED: ${result.error || ''}]` : ''}`;
-    },
-
     ast_query(result) {
       if (!result || typeof result !== 'object') return String(result);
       if (!Array.isArray(result.matches)) return JSON.stringify(result);