dave-code 1.0.4 → 1.2.0

package/bin/toolRuntime.js

@@ -0,0 +1,1607 @@
+import fs from 'fs';
+import path from 'path';
+import crypto from 'crypto';
+import readline from 'readline';
+import { execFile, spawn } from 'child_process';
+
+const backgroundTasks = new Map();
+const workspaceShellCwds = new Map();
+const workspaceShellSessions = new Map();
+const workspaceTodos = new Map();
+const mutationHistory = new Map();
+
+async function recordMutation(workspaceRoot, entry) {
+  const history = mutationHistory.get(workspaceRoot) || [];
+  if (typeof entry.content === 'string' || Buffer.isBuffer(entry.content)) {
+    const backupDir = path.join(workspaceRoot, '.rollback-tmp');
+    await fs.promises.mkdir(backupDir, { recursive: true });
+    const backupPath = path.join(backupDir, crypto.createHash('sha256').update(`${Date.now()}:${entry.path}`).digest('hex'));
+    await fs.promises.writeFile(backupPath, entry.content, typeof entry.content === 'string' ? 'utf8' : undefined);
+    entry.backupPath = backupPath;
+    delete entry.content;
+  }
+  history.push({ ...entry, at: Date.now() });
+  mutationHistory.set(workspaceRoot, history.slice(-100));
+}
+
+export async function undoLastMutation(workspaceRoot) {
+  const history = mutationHistory.get(workspaceRoot) || [];
+  const entry = history.pop();
+  if (!entry) return { ok: false, message: 'No mutation is available to undo.' };
+  mutationHistory.set(workspaceRoot, history);
+  const target = entry.path ? resolveWorkspacePath(entry.path, workspaceRoot) : null;
+  if (entry.kind === 'write') {
+    if (entry.existed) await fs.promises.writeFile(target, await fs.promises.readFile(entry.backupPath, 'utf8'), 'utf8');
+    else if (fs.existsSync(target)) await fs.promises.unlink(target);
+  } else if (entry.kind === 'move') {
+    const source = resolveWorkspacePath(entry.source, workspaceRoot);
+    const destination = resolveExistingWorkspacePath(entry.destination, workspaceRoot);
+    await fs.promises.mkdir(path.dirname(source), { recursive: true });
+    await fs.promises.rename(destination, source);
+  } else if (entry.kind === 'delete') {
+    if (entry.directory) await fs.promises.mkdir(target, { recursive: true });
+    else {
+      await fs.promises.mkdir(path.dirname(target), { recursive: true });
+      await fs.promises.copyFile(entry.backupPath, target);
+    }
+  } else if (entry.kind === 'mkdir' && !entry.existed && fs.existsSync(target)) {
+    await fs.promises.rmdir(target);
+  }
+  if (entry.backupPath && fs.existsSync(entry.backupPath)) await fs.promises.unlink(entry.backupPath);
+  return { ok: true, message: `Undid ${entry.kind}: ${entry.path || `${entry.source} -> ${entry.destination}`}` };
+}
+
+export const SUPPORTED_TOOLS = new Set([
+  'LIST_DIR',
+  'INSPECT_FILE',
+  'READ_FILE',
+  'READ_NOTEBOOK',
+  'SEARCH_GREP',
+  'GLOB_FILES',
+  'EDIT_FILE',
+  'WRITE_FILE',
+  'MAKE_DIR',
+  'MOVE_PATH',
+  'DELETE_PATH',
+  'RUN_COMMAND'
+  ,'READ_TASK_OUTPUT'
+  ,'KILL_TASK'
+  ,'UPDATE_TODOS'
+]);
+export const MUTATING_TOOLS = new Set([
+  'EDIT_FILE', 'WRITE_FILE', 'MAKE_DIR', 'MOVE_PATH', 'DELETE_PATH', 'RUN_COMMAND', 'KILL_TASK'
+]);
+export const TOOL_DEFINITIONS = [
+  { name: 'LIST_DIR', description: 'List one directory inside the workspace.', inputSchema: { type: 'object', properties: { path: { type: 'string' } }, required: ['path'], additionalProperties: false } },
+  { name: 'INSPECT_FILE', description: 'Return a compact structural outline with imports, symbols, and line numbers. Prefer this before reading an unfamiliar file.', inputSchema: { type: 'object', properties: { path: { type: 'string' } }, required: ['path'], additionalProperties: false } },
+  { name: 'READ_FILE', description: 'Read a UTF-8 text file or inclusive line range. Large results are paged to the active context budget; continue with the returned cursor.', inputSchema: { type: 'object', properties: { path: { type: 'string' }, startLine: { type: 'integer', minimum: 1 }, endLine: { type: 'integer', minimum: 1 }, cursor: { type: 'integer', minimum: 1 } }, required: ['path'], additionalProperties: false } },
+  { name: 'READ_NOTEBOOK', description: 'Read the private project notebook on demand. With no sections or query, return only its compact catalog.', inputSchema: { type: 'object', properties: { sections: { type: 'array', items: { type: 'string' }, maxItems: 12 }, query: { type: 'string' }, maxTokens: { type: 'integer', minimum: 100, maximum: 4000 } }, additionalProperties: false } },
+  { name: 'SEARCH_GREP', description: 'Search workspace files with ripgrep-compatible regex, glob, context, case, and output controls.', inputSchema: { type: 'object', properties: { pattern: { type: 'string' }, query: { type: 'string' }, glob: { type: 'string' }, outputMode: { type: 'string', enum: ['content', 'files_with_matches', 'count'] }, contextLines: { type: 'integer', minimum: 0, maximum: 20 }, caseInsensitive: { type: 'boolean' }, literal: { type: 'boolean' } }, additionalProperties: false } },
+  { name: 'GLOB_FILES', description: 'List workspace files matching a glob, newest modified first.', inputSchema: { type: 'object', properties: { pattern: { type: 'string' } }, required: ['pattern'], additionalProperties: false } },
+  { name: 'EDIT_FILE', description: 'Replace exact, unique text in an existing file.', inputSchema: { type: 'object', properties: { path: { type: 'string' }, oldText: { type: 'string' }, newText: { type: 'string' }, replaceAll: { type: 'boolean' } }, required: ['path', 'oldText', 'newText'], additionalProperties: false } },
+  { name: 'WRITE_FILE', description: 'Create or completely replace a UTF-8 text file.', inputSchema: { type: 'object', properties: { path: { type: 'string' }, content: { type: 'string' } }, required: ['path', 'content'], additionalProperties: false } },
+  { name: 'MAKE_DIR', description: 'Create a directory inside the workspace.', inputSchema: { type: 'object', properties: { path: { type: 'string' } }, required: ['path'], additionalProperties: false } },
+  { name: 'MOVE_PATH', description: 'Move or rename a workspace path.', inputSchema: { type: 'object', properties: { source: { type: 'string' }, destination: { type: 'string' } }, required: ['source', 'destination'], additionalProperties: false } },
+  { name: 'DELETE_PATH', description: 'Delete a file or an empty directory inside the workspace.', inputSchema: { type: 'object', properties: { path: { type: 'string' } }, required: ['path'], additionalProperties: false } },
+  { name: 'RUN_COMMAND', description: 'Run a command in the workspace shell after user confirmation, optionally in the background.', inputSchema: { type: 'object', properties: { command: { type: 'string' }, runInBackground: { type: 'boolean' }, timeoutSeconds: { type: 'integer', minimum: 1, maximum: 600 } }, required: ['command'], additionalProperties: false } },
+  { name: 'READ_TASK_OUTPUT', description: 'Read captured output and status for a background command.', inputSchema: { type: 'object', properties: { taskId: { type: 'string' } }, required: ['taskId'], additionalProperties: false } },
+  { name: 'KILL_TASK', description: 'Stop a background command after confirmation.', inputSchema: { type: 'object', properties: { taskId: { type: 'string' } }, required: ['taskId'], additionalProperties: false } }
+  ,{ name: 'UPDATE_TODOS', description: 'Publish the current long-task checklist for the user.', inputSchema: { type: 'object', properties: { todos: { type: 'array', items: { type: 'object', properties: { content: { type: 'string' }, status: { type: 'string', enum: ['pending', 'in_progress', 'completed'] } }, required: ['content', 'status'], additionalProperties: false }, maxItems: 30 } }, required: ['todos'], additionalProperties: false } }
+];
+
+export const SCAN_TOOL_DEFINITIONS = [{
+  name: 'COMMIT_CONTEXT_PLAN',
+  description: 'Commit the active-context token budget and advisory starting files for the formal repository task.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      budgetTokens: { type: 'integer', minimum: 4096 },
+      contextBudgetTokens: { type: 'integer', minimum: 4096 },
+      turnBudgetTokens: { type: 'integer', minimum: 4096 },
+      rationale: { type: 'string' },
+      files: {
+        type: 'array',
+        items: {
+          type: 'object',
+          properties: {
+            path: { type: 'string' },
+            reason: { type: 'string' },
+            strategy: { type: 'string', enum: ['outline', 'targeted', 'full'] },
+            required: { type: 'boolean' },
+            estimatedTokens: { type: 'integer', minimum: 0 }
+          },
+          required: ['path'],
+          additionalProperties: false
+        }
+      },
+      notebook: {
+        type: 'object',
+        properties: {
+          action: { type: 'string', enum: ['reuse', 'build', 'update'] },
+          sections: { type: 'array', items: { type: 'string' }, maxItems: 12 },
+          notebookBudgetTokens: { type: 'integer', minimum: 0 }
+        },
+        additionalProperties: false
+      },
+      recommendedFiles: {
+        type: 'array',
+        items: {
+          type: 'object',
+          properties: { path: { type: 'string' }, reason: { type: 'string' }, strategy: { type: 'string' } },
+          required: ['path'], additionalProperties: false
+        }
+      },
+      notebookReuse: {
+        type: 'object',
+        properties: {
+          rationale: { type: 'string' },
+          trustedSections: { type: 'array', items: { type: 'string' } },
+          verifyFiles: {
+            type: 'array',
+            items: {
+              type: 'object',
+              properties: { path: { type: 'string' }, reason: { type: 'string' }, strategy: { type: 'string' } },
+              required: ['path', 'reason'], additionalProperties: false
+            }
+          },
+          stalePaths: { type: 'array', items: { type: 'string' } }
+        },
+        additionalProperties: false
+      }
+    },
+    required: ['rationale'],
+    additionalProperties: false
+  }
+}];
+
+export function getToolDefinitions(mode = 'chat') {
+  if (mode === 'note') return [];
+  if (mode === 'scan') return SCAN_TOOL_DEFINITIONS;
+  return TOOL_DEFINITIONS.filter(tool => mode === 'code' || !MUTATING_TOOLS.has(tool.name));
+}
+const DEFAULT_TEXT_EXTS = new Set([
+  '.js', '.json', '.txt', '.md', '.html', '.css', '.yml', '.yaml',
+  '.sh', '.bat', '.cmd', '.py', '.cpp', '.h', '.c', '.go', '.rs',
+  '.java', '.ts', '.tsx', '.jsx'
+]);
+
+function decodeEntities(value) {
+  return String(value || '')
+    .replace(/&lt;/g, '<')
+    .replace(/&gt;/g, '>')
+    .replace(/&quot;/g, '"')
+    .replace(/&amp;/g, '&');
+}
+
+function buildEditArgument(filePath, oldText, newText, replaceAll = false) {
+  return `${filePath}\n<<<SEARCH\n${oldText}\n===REPLACE\n${newText}\n>>>END${replaceAll ? '\nALL' : ''}`;
+}
+
+export function containsToolProtocolLeak(reply = '') {
+  const text = String(reply || '');
+  if (!text.trim()) return false;
+  if (/<[^>\r\n]{0,120}DSML[^>\r\n]{0,120}(?:tool_calls|invoke|parameter)[^>\r\n]*>/i.test(text)) return true;
+  return /<<\s*(?:LIST_DIR|INSPECT_FILE|READ_FILE|READ_NOTEBOOK|SEARCH_GREP|GLOB_FILES|EDIT_FILE|WRITE_FILE|MAKE_DIR|MOVE_PATH|DELETE_PATH|RUN_COMMAND|READ_TASK_OUTPUT|KILL_TASK|UPDATE_TODOS|COMMIT_CONTEXT_PLAN)\s*:/i.test(text);
+}
+
+export function resolveBudgetFinishResponse({
+  reply = '',
+  nativeToolCalls = [],
+  repairAttempts = 0,
+  lang = 'en',
+  reason = 'budget'
+} = {}) {
+  const leakedToolRequest = nativeToolCalls.length > 0 || containsToolProtocolLeak(reply);
+  if (!leakedToolRequest) return { action: 'accept', reply: String(reply || '') };
+  if (repairAttempts < 1) return { action: 'retry', reply: '' };
+  return {
+    action: 'fallback',
+    reply: reason === 'no-progress'
+      ? (lang === 'cn'
+          ? '已停止无进展的重复读取。模型在工具关闭后仍尝试重复调用，相关协议内容已被拦截；当前证据不足以生成可靠的完整结论。'
+          : 'The no-progress read loop was stopped. The model still attempted another tool call after tools were disabled, so the protocol output was blocked; the current evidence is insufficient for a reliable complete conclusion.')
+      : (lang === 'cn'
+          ? '已按要求停止继续读取。模型仍尝试调用工具，相关协议内容已被拦截；基于当前证据无法生成可靠的完整结论。'
+          : 'Further reading has stopped as requested. The model still attempted a tool call, so the protocol output was blocked; the current evidence is insufficient for a reliable complete conclusion.')
+  };
+}
+
+function stableToolValue(value) {
+  if (Array.isArray(value)) return value.map(stableToolValue);
+  if (!value || typeof value !== 'object') return value;
+  return Object.fromEntries(
+    Object.keys(value).sort().map(key => [key, stableToolValue(value[key])])
+  );
+}
+
+export function createToolCallSignature(toolName, toolArg) {
+  return `${String(toolName || '').toUpperCase()}:${JSON.stringify(stableToolValue(toolArg || {}))}`;
+}
+
+export function resolveRepeatedToolRequest({
+  signature = '',
+  previousSignature = '',
+  identicalResultCount = 0,
+  blockedSignature = ''
+} = {}) {
+  if (!signature || signature !== previousSignature || identicalResultCount < 2) {
+    return { action: 'allow' };
+  }
+  if (blockedSignature !== signature) {
+    return { action: 'redirect', blockedSignature: signature };
+  }
+  return { action: 'finish', blockedSignature: signature };
+}
+
+function parseDSMLToolCall(text) {
+  const trimmed = String(text || '').trim();
+  if (!/^<｜｜DSML｜｜tool_calls>[\s\S]*<\/｜｜DSML｜｜tool_calls>$/.test(trimmed)) return null;
+  const invokePattern = /<｜｜DSML｜｜invoke\s+name="([^"]+)">([\s\S]*?)<\/｜｜DSML｜｜invoke>/g;
+  const invokes = [...trimmed.matchAll(invokePattern)];
+  if (invokes.length === 0) return null;
+  if (invokes.length !== 1) {
+    return { error: 'Tool parse error: exactly one DSML invocation is allowed.' };
+  }
+
+  const invoke = invokes[0];
+  const sourceName = invoke[1];
+  const body = invoke[2];
+  const params = {};
+  const parameterPattern = /<｜｜DSML｜｜parameter\s+name="([^"]+)"[^>]*>([\s\S]*?)<\/｜｜DSML｜｜parameter>/g;
+  for (const match of body.matchAll(parameterPattern)) {
+    params[match[1]] = decodeEntities(match[2]);
+  }
+
+  const key = sourceName.toLowerCase();
+  const filePath = String(params.filePath || params.path || params.file_path || '').trim();
+  let toolName;
+  let toolArg;
+
+  if (key === 'read') {
+    toolName = 'READ_FILE';
+    const offset = Math.max(1, Number.parseInt(params.offset || '1', 10) || 1);
+    const limit = Math.max(1, Number.parseInt(params.limit || '0', 10) || 0);
+    toolArg = limit ? `${filePath}:${offset}-${offset + limit - 1}` : filePath;
+  } else if (key === 'write') {
+    toolName = 'WRITE_FILE';
+    toolArg = `${filePath}\n${params.content || params.text || ''}`;
+  } else if (key === 'edit' || key === 'strreplace') {
+    toolName = 'EDIT_FILE';
+    toolArg = buildEditArgument(
+      filePath,
+      params.oldString || params.old_string || params.oldText || '',
+      params.newString || params.new_string || params.newText || '',
+      String(params.replaceAll || params.replace_all || '').toLowerCase() === 'true'
+    );
+  } else if (key === 'bash' || key === 'shell' || key === 'runcommand') {
+    toolName = 'RUN_COMMAND';
+    toolArg = params.command || params.cmd || '';
+  } else if (key === 'grep' || key === 'search') {
+    toolName = 'SEARCH_GREP';
+    toolArg = params.pattern || params.query || params.text || '';
+  } else if (key === 'glob' || key === 'list' || key === 'listdir') {
+    toolName = 'LIST_DIR';
+    toolArg = params.path || params.directory || '.';
+  } else if (key === 'delete' || key === 'remove') {
+    toolName = 'DELETE_PATH';
+    toolArg = filePath;
+  } else if (key === 'move' || key === 'rename') {
+    toolName = 'MOVE_PATH';
+    toolArg = `${params.source || params.from || filePath}\n${params.destination || params.to || ''}`;
+  } else if (key === 'mkdir' || key === 'makedir') {
+    toolName = 'MAKE_DIR';
+    toolArg = filePath || params.directory || '';
+  } else {
+    return { error: `Tool parse error: unsupported DSML tool "${sourceName}".` };
+  }
+
+  return {
+    toolName,
+    toolArg,
+    match: invoke,
+    recovered: true,
+    sourceFormat: 'dsml',
+    remainingCalls: 0,
+    thoughtText: ''
+  };
+}
+
+export function createToolTagStreamFilter() {
+  let mode = 'pending';
+  let buffer = '';
+
+  function push(chunk) {
+    const text = String(chunk || '');
+    if (!text) return '';
+    if (mode === 'text') return text;
+    if (mode === 'reasoning') {
+      buffer += text;
+      const closeIndex = buffer.toLowerCase().indexOf('</think>');
+      if (closeIndex === -1) return '';
+      const remainder = buffer.slice(closeIndex + 8);
+      buffer = '';
+      mode = 'pending';
+      return push(remainder);
+    }
+    buffer += text;
+    const trimmed = buffer.trimStart();
+    const lower = trimmed.toLowerCase();
+    const upper = trimmed.toUpperCase();
+
+    if (!trimmed) return '';
+    if (lower.startsWith('<think>')) {
+      mode = 'reasoning';
+      const closeIndex = lower.indexOf('</think>');
+      if (closeIndex !== -1) {
+        const remainder = trimmed.slice(closeIndex + 8);
+        buffer = '';
+        mode = 'pending';
+        return push(remainder);
+      }
+      return '';
+    }
+    if ('<think>'.startsWith(lower) || 'reasoning_content:'.startsWith(lower)) return '';
+    if (lower.startsWith('reasoning_content:')) {
+      mode = 'reasoning';
+      return '';
+    }
+    const toolPrefixes = Array.from(SUPPORTED_TOOLS).map(tool => `<<${tool}:`);
+    if (toolPrefixes.some(prefix => prefix.startsWith(upper))) return '';
+    if (toolPrefixes.some(prefix => upper.startsWith(prefix))) {
+      mode = 'tool';
+      return '';
+    }
+    if (trimmed.startsWith('<<')) {
+      if (/^<<[A-Z_]+\s*:/.test(trimmed)) mode = 'tool';
+      return '';
+    }
+    if ('<<'.startsWith(trimmed)) return '';
+
+    mode = 'text';
+    const output = buffer;
+    buffer = '';
+    return output;
+  }
+
+  function finish() {
+    const trimmed = buffer.trimStart().toLowerCase();
+    if (mode === 'pending' && !trimmed.startsWith('<<') && !trimmed.startsWith('<think') && !trimmed.startsWith('reasoning_content:')) {
+      mode = 'text';
+      const output = buffer;
+      buffer = '';
+      return output;
+    }
+    return '';
+  }
+
+  return {
+    push,
+    finish,
+    isTool: () => mode === 'tool' || /^<<[A-Z_]+\s*:/.test(buffer.trimStart())
+  };
+}
+
+export function parseToolCall(reply = '') {
+  const text = String(reply).trim();
+  if (text.startsWith('<｜｜DSML｜｜tool_calls>')) {
+    const dsml = parseDSMLToolCall(text);
+    if (dsml) return dsml;
+  }
+
+  if (!text.startsWith('<<')) return null;
+  const match = text.match(/^<<([A-Z_]+):\s*([\s\S]*)>>$/);
+  if (!match) return { error: 'Tool parse error: legacy calls must occupy the complete message as <<TOOL_NAME: arguments>>.' };
+  if (/<<[A-Z_]+\s*:/.test(match[2])) {
+    return { error: 'Tool parse error: exactly one legacy tool call is allowed.' };
+  }
+
+  const toolName = match[1];
+  if (!SUPPORTED_TOOLS.has(toolName)) {
+    return {
+      error: `Tool parse error: unsupported tool "${toolName}". Supported tools: ${Array.from(SUPPORTED_TOOLS).join(', ')}.`
+    };
+  }
+
+  return {
+    toolName,
+    toolArg: match[2],
+    match,
+    recovered: false,
+    thoughtText: ''
+  };
+}
+
+export function isInsidePath(childPath, rootPath) {
+  const relative = path.relative(rootPath, childPath);
+  return relative === '' || (!!relative && !relative.startsWith('..') && !path.isAbsolute(relative));
+}
+
+function canonicalExistingPath(targetPath) {
+  return fs.realpathSync.native(targetPath);
+}
+
+function canonicalRoot(workspaceRoot) {
+  const root = canonicalExistingPath(path.resolve(workspaceRoot));
+  return process.platform === 'win32' ? root.toLowerCase() : root;
+}
+
+function comparablePath(value) {
+  const normalized = path.resolve(value);
+  return process.platform === 'win32' ? normalized.toLowerCase() : normalized;
+}
+
+function nearestExistingAncestor(targetPath) {
+  let current = path.resolve(targetPath);
+  while (!fs.existsSync(current)) {
+    const parent = path.dirname(current);
+    if (parent === current) break;
+    current = parent;
+  }
+  return current;
+}
+
+export function resolveWorkspacePath(rawPath, workspaceRoot) {
+  const trimmed = String(rawPath || '').trim();
+  if (!trimmed) {
+    throw new Error('Path is empty.');
+  }
+
+  const resolved = path.isAbsolute(trimmed)
+    ? path.resolve(trimmed)
+    : path.resolve(workspaceRoot, trimmed);
+  const root = path.resolve(workspaceRoot);
+
+  if (!isInsidePath(resolved, root)) {
+    throw new Error(`Access outside workspace is blocked: ${trimmed}`);
+  }
+
+  const realRoot = canonicalRoot(workspaceRoot);
+  const ancestor = nearestExistingAncestor(resolved);
+  const realAncestor = comparablePath(canonicalExistingPath(ancestor));
+  if (!isInsidePath(realAncestor, realRoot)) {
+    throw new Error(`Workspace path resolves through a link outside the workspace: ${trimmed}`);
+  }
+  if (fs.existsSync(resolved)) {
+    const realTarget = comparablePath(canonicalExistingPath(resolved));
+    if (!isInsidePath(realTarget, realRoot)) {
+      throw new Error(`Workspace path resolves outside the workspace: ${trimmed}`);
+    }
+    return resolved;
+  }
+  return resolved;
+}
+
+export function resolveExistingWorkspacePath(rawPath, workspaceRoot) {
+  const value = String(rawPath || '').trim();
+  let resolved;
+  let originalError;
+  try {
+    resolved = resolveWorkspacePath(value, workspaceRoot);
+    if (fs.existsSync(resolved)) return resolved;
+  } catch (error) {
+    originalError = error;
+  }
+  const fileName = value.replace(/\\/g, '/').split('/').filter(Boolean).at(-1);
+  const suggestions = [];
+  if (fileName && !['.', '..'].includes(fileName)) {
+    const visit = (directory, depth) => {
+      if (depth > 6 || suggestions.length >= 5) return;
+      let entries = [];
+      try {
+        entries = fs.readdirSync(directory, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name));
+      } catch {
+        return;
+      }
+      for (const entry of entries) {
+        if (suggestions.length >= 5) break;
+        if (['node_modules', '.git', '.gemini'].includes(entry.name)) continue;
+        const fullPath = path.join(directory, entry.name);
+        if (entry.isDirectory()) visit(fullPath, depth + 1);
+        else if (entry.isFile() && entry.name === fileName) suggestions.push(path.relative(workspaceRoot, fullPath));
+      }
+    };
+    visit(workspaceRoot, 0);
+  }
+  const hint = suggestions.length
+    ? ` Candidate path${suggestions.length === 1 ? '' : 's'}: ${suggestions.join(', ')}. Retry with one exact workspace-relative path.`
+    : '';
+  if (originalError) throw new Error(`${originalError.message}${hint}`);
+  throw new Error(`Path does not exist inside workspace: ${value}.${hint}`);
+}
+
+export function isSensitivePath(filePath) {
+  const normalized = String(filePath || '').replace(/\\/g, '/').toLowerCase();
+  const base = path.posix.basename(normalized);
+  return base === '.env' || base.startsWith('.env.') ||
+    ['.npmrc', '.netrc'].includes(base) || base.startsWith('credentials') || base.startsWith('secrets') ||
+    /^(id_rsa|id_ed25519)(\.|$)/.test(base) ||
+    /\.(pem|key|p12|pfx|jks|keystore|crt|cer)$/.test(base) ||
+    normalized.split('/').includes('.git');
+}
+
+function contentHash(content) {
+  return crypto.createHash('sha256').update(content).digest('hex');
+}
+
+async function looksBinary(filePath) {
+  const handle = await fs.promises.open(filePath, 'r');
+  try {
+    const buffer = Buffer.alloc(8192);
+    const { bytesRead } = await handle.read(buffer, 0, buffer.length, 0);
+    return buffer.subarray(0, bytesRead).includes(0);
+  } finally {
+    await handle.close();
+  }
+}
+
+function buildFileOutline(content, relPath, maxItems = 120) {
+  const lines = String(content || '').split('\n');
+  const items = [];
+  const patterns = [
+    /^\s*(?:import\s|export\s+.*\sfrom\s|const\s+\w+\s*=\s*require\s*\()/,
+    /^\s*(?:export\s+)?(?:async\s+)?function\s+[\w$]+/,
+    /^\s*(?:export\s+)?class\s+[\w$]+/,
+    /^\s*(?:export\s+)?(?:const|let|var)\s+[\w$]+\s*=\s*(?:async\s*)?(?:\([^)]*\)|[\w$]+)\s*=>/,
+    /^\s*(?:def|class)\s+[\w_]+/,
+    /^\s*(?:pub\s+)?(?:async\s+)?fn\s+[\w_]+/,
+    /^\s*(?:func|type|interface|struct|enum)\s+[\w_]+/,
+    /^\s*#{1,6}\s+\S/
+  ];
+  for (let index = 0; index < lines.length && items.length < maxItems; index++) {
+    const line = lines[index].trimEnd();
+    if (patterns.some(pattern => pattern.test(line))) {
+      items.push(`${index + 1}: ${line.trim().slice(0, 220)}`);
+    }
+  }
+  const header = `[File outline: ${relPath} · ${lines.length} lines · ${Buffer.byteLength(content, 'utf8')} bytes]`;
+  if (items.length === 0) return `${header}\nNo recognizable declarations. Use SEARCH_GREP or a targeted READ_FILE range.`;
+  return `${header}\n${items.join('\n')}`;
+}
+
+function trackerEntry(readTracker, relPath, identity) {
+  if (!readTracker?.files) return null;
+  const current = readTracker.files.get(relPath);
+  if (current?.identity === identity) return current;
+  const next = { identity, full: false, outline: false, ranges: [], rangeContents: new Map() };
+  readTracker.files.set(relPath, next);
+  return next;
+}
+
+function rangeAlreadyRead(entry, startLine, endLine) {
+  return Boolean(entry?.full || entry?.ranges?.some(([start, end]) => start <= startLine && end >= endLine));
+}
+
+export function truncateToolResult(text, maxChars = 12000) {
+  const clean = String(text || '');
+  if (clean.length <= maxChars) return clean;
+  return `${clean.slice(0, maxChars)}\n\n[Tool result truncated: ${clean.length - maxChars} characters omitted. Use narrower search terms or READ_FILE line ranges.]`;
+}
+
+function parseReadArgument(toolArg) {
+  if (toolArg && typeof toolArg === 'object') {
+    const rawStart = toolArg.cursor ?? toolArg.startLine ?? toolArg.start_line;
+    const startLine = Math.max(1, Number.parseInt(rawStart ?? '1', 10) || 1);
+    const rawEnd = toolArg.endLine ?? toolArg.end_line;
+    const endLine = rawEnd === undefined || rawEnd === null ? null : Math.max(1, Number.parseInt(rawEnd, 10) || 1);
+    if (endLine !== null && endLine < startLine) {
+      throw new Error('Invalid line range: end line must be greater than or equal to start line.');
+    }
+    return {
+      filePath: String(toolArg.path ?? toolArg.filePath ?? ''),
+      startLine,
+      endLine,
+      hasRange: rawStart !== undefined || endLine !== null
+    };
+  }
+  let filePath = String(toolArg || '').trim();
+  let startLine = 1;
+  let endLine = null;
+  const rangeMatch = filePath.match(/:(\d+)-(\d+)$/);
+  if (rangeMatch) {
+    filePath = filePath.slice(0, -rangeMatch[0].length);
+    startLine = parseInt(rangeMatch[1], 10);
+    endLine = parseInt(rangeMatch[2], 10);
+  }
+  if (endLine !== null && endLine < startLine) {
+    throw new Error('Invalid line range: end line must be greater than or equal to start line.');
+  }
+  return { filePath, startLine, endLine, hasRange: !!rangeMatch };
+}
+
+async function readLinePage(filePath, startLine, endLine, maxChars) {
+  const input = fs.createReadStream(filePath, { encoding: 'utf8' });
+  const rl = readline.createInterface({ input, crlfDelay: Infinity });
+  const lines = [];
+  let lineNumber = 0;
+  let chars = 0;
+  let nextCursor = null;
+  try {
+    for await (const line of rl) {
+      lineNumber++;
+      if (lineNumber < startLine) continue;
+      if (endLine !== null && lineNumber > endLine) break;
+      const rendered = `${lineNumber}: ${line}`;
+      if (lines.length && chars + rendered.length + 1 > maxChars) {
+        nextCursor = lineNumber;
+        break;
+      }
+      lines.push(rendered);
+      chars += rendered.length + 1;
+    }
+  } finally {
+    rl.close();
+    input.destroy();
+  }
+  const suffix = nextCursor
+    ? `\n\n[Continuation cursor: ${nextCursor}. Call READ_FILE with the same path and cursor ${nextCursor}${endLine !== null ? ` (original endLine ${endLine})` : ''}.]`
+    : '';
+  return { content: lines.join('\n') + suffix, lineCount: lines.length, nextCursor, lastLine: lineNumber };
+}
+
+function buildWritePreview(filePath, oldContent, newContent, existed) {
+  const relName = path.basename(filePath);
+  if (!existed) {
+    return [
+      `Create ${relName}`,
+      previewLines(newContent, '+')
+    ].join('\n');
+  }
+
+  if (oldContent === newContent) {
+    return `${relName}: no content changes.`;
+  }
+
+  const oldLines = oldContent.replace(/\r\n/g, '\n').split('\n');
+  const newLines = newContent.replace(/\r\n/g, '\n').split('\n');
+  const rows = oldLines.length + 1;
+  const cols = newLines.length + 1;
+  if (rows * cols > 2_000_000) {
+    return [`Update ${relName}`, '@@ large-file diff @@', previewLines(oldContent, '-', 40), previewLines(newContent, '+', 40)].join('\n');
+  }
+  const lcs = Array.from({ length: rows }, () => new Uint32Array(cols));
+  for (let i = oldLines.length - 1; i >= 0; i--) {
+    for (let j = newLines.length - 1; j >= 0; j--) {
+      lcs[i][j] = oldLines[i] === newLines[j] ? lcs[i + 1][j + 1] + 1 : Math.max(lcs[i + 1][j], lcs[i][j + 1]);
+    }
+  }
+  const ops = [];
+  let i = 0;
+  let j = 0;
+  let oldLine = 1;
+  let newLine = 1;
+  while (i < oldLines.length || j < newLines.length) {
+    if (i < oldLines.length && j < newLines.length && oldLines[i] === newLines[j]) {
+      ops.push({ type: ' ', text: oldLines[i], oldLine: oldLine++, newLine: newLine++ }); i++; j++;
+    } else if (j < newLines.length && (i >= oldLines.length || lcs[i][j + 1] >= lcs[i + 1][j])) {
+      ops.push({ type: '+', text: newLines[j++], oldLine: null, newLine: newLine++ });
+    } else {
+      ops.push({ type: '-', text: oldLines[i++], oldLine: oldLine++, newLine: null });
+    }
+  }
+  const changed = ops.map((op, index) => op.type === ' ' ? -1 : index).filter(index => index >= 0);
+  const groups = [];
+  for (const index of changed) {
+    const group = groups.at(-1);
+    if (!group || index - group.at(-1) > 6) groups.push([index]);
+    else group.push(index);
+  }
+  const hunks = groups.map(group => {
+    const slice = ops.slice(Math.max(0, group[0] - 3), Math.min(ops.length, group.at(-1) + 4));
+    const oldStart = slice.find(op => op.oldLine !== null)?.oldLine ?? oldLine;
+    const newStart = slice.find(op => op.newLine !== null)?.newLine ?? newLine;
+    const oldCount = slice.filter(op => op.type !== '+').length;
+    const newCount = slice.filter(op => op.type !== '-').length;
+    return [`@@ -${oldStart},${oldCount} +${newStart},${newCount} @@`, ...slice.map(op => `${op.type}${op.text}`)].join('\n');
+  });
+  return [`Update ${relName}`, ...hunks].join('\n');
+}
+
+function previewLines(text, marker, maxLines = 60) {
+  const lines = String(text || '').split('\n');
+  const shown = lines.slice(0, maxLines).map(line => `${marker} ${line}`).join('\n');
+  if (lines.length <= maxLines) return shown;
+  return `${shown}\n... ${lines.length - maxLines} more lines omitted`;
+}
+
+function parseEditArgument(toolArg) {
+  if (toolArg && typeof toolArg === 'object') {
+    return {
+      filePath: toolArg.path || toolArg.filePath || '',
+      oldText: toolArg.oldText ?? toolArg.oldString ?? '',
+      newText: toolArg.newText ?? toolArg.newString ?? '',
+      replaceAll: toolArg.replaceAll === true
+    };
+  }
+  const raw = String(toolArg || '');
+  if (raw.trimStart().startsWith('{')) {
+    const parsed = JSON.parse(raw);
+    return {
+      filePath: parsed.path || parsed.filePath || '',
+      oldText: parsed.oldText ?? parsed.oldString ?? '',
+      newText: parsed.newText ?? parsed.newString ?? '',
+      replaceAll: parsed.replaceAll === true
+    };
+  }
+
+  const normalized = raw.replace(/\r\n/g, '\n');
+  const firstNewline = normalized.indexOf('\n');
+  if (firstNewline === -1) throw new Error('EDIT_FILE requires a path and SEARCH/REPLACE blocks.');
+  const filePath = normalized.slice(0, firstNewline).trim();
+  const body = normalized.slice(firstNewline + 1);
+  const searchMarker = '<<<SEARCH\n';
+  const replaceMarker = '\n===REPLACE\n';
+  const endMarker = '\n>>>END';
+  if (!body.startsWith(searchMarker)) throw new Error('EDIT_FILE is missing <<<SEARCH.');
+  const replaceIndex = body.indexOf(replaceMarker, searchMarker.length);
+  const endIndex = body.lastIndexOf(endMarker);
+  if (replaceIndex === -1 || endIndex === -1 || endIndex < replaceIndex) {
+    throw new Error('EDIT_FILE requires ===REPLACE and >>>END markers.');
+  }
+  return {
+    filePath,
+    oldText: body.slice(searchMarker.length, replaceIndex),
+    newText: body.slice(replaceIndex + replaceMarker.length, endIndex),
+    replaceAll: /\nALL\s*$/.test(body.slice(endIndex + endMarker.length))
+  };
+}
+
+function countOccurrences(content, search) {
+  if (!search) return 0;
+  let count = 0;
+  let offset = 0;
+  while ((offset = content.indexOf(search, offset)) !== -1) {
+    count++;
+    offset += search.length;
+  }
+  return count;
+}
+
+function parseMoveArgument(toolArg) {
+  if (toolArg && typeof toolArg === 'object') {
+    return {
+      source: String(toolArg.source || toolArg.from || '').trim(),
+      destination: String(toolArg.destination || toolArg.to || '').trim()
+    };
+  }
+  const raw = String(toolArg || '').trim();
+  if (raw.startsWith('{')) {
+    const parsed = JSON.parse(raw);
+    return {
+      source: parsed.source || parsed.from || '',
+      destination: parsed.destination || parsed.to || ''
+    };
+  }
+  const [source = '', destination = ''] = raw.split(/\r?\n/, 2);
+  return { source: source.trim(), destination: destination.trim() };
+}
+
+function runExecutable(file, args, cwd, signal, maxBuffer = 8 * 1024 * 1024) {
+  return new Promise((resolve, reject) => {
+    const child = execFile(file, args, { cwd, windowsHide: true, maxBuffer }, (error, stdout, stderr) => {
+      signal?.removeEventListener('abort', abort);
+      if (error && error.code === 'ENOENT') reject(error);
+      else resolve({ exitCode: typeof error?.code === 'number' ? error.code : (error ? 1 : 0), stdout: String(stdout || ''), stderr: String(stderr || ''), error });
+    });
+    const abort = () => child.kill();
+    if (signal?.aborted) abort();
+    else signal?.addEventListener('abort', abort, { once: true });
+  });
+}
+
+async function automaticSyntaxCheck(filePath, workspaceRoot, signal) {
+  if (!['.js', '.mjs'].includes(path.extname(filePath).toLowerCase())) return '';
+  const checked = await runExecutable(process.execPath, ['--check', filePath], workspaceRoot, signal);
+  return checked.exitCode === 0
+    ? '\nAutomatic validation: node --check passed.'
+    : `\nAutomatic validation failed (file was not rolled back):\n${checked.stderr || checked.stdout}`;
+}
+
+function persistentShell(workspaceRoot) {
+  const current = workspaceShellSessions.get(workspaceRoot);
+  if (current && !current.child.killed && current.child.exitCode === null) return current;
+  const windows = process.platform === 'win32';
+  const child = windows
+    ? spawn('powershell.exe', ['-NoLogo', '-NoProfile', '-NonInteractive', '-Command', '-'], { cwd: workspaceRoot, windowsHide: true, stdio: ['pipe', 'pipe', 'pipe'] })
+    : spawn(process.env.SHELL || '/bin/sh', [], { cwd: workspaceRoot, windowsHide: true, stdio: ['pipe', 'pipe', 'pipe'] });
+  const state = { child, windows, queue: Promise.resolve() };
+  child.unref();
+  child.stdin?.unref?.();
+  child.stdout?.unref?.();
+  child.stderr?.unref?.();
+  child.on('exit', () => { if (workspaceShellSessions.get(workspaceRoot) === state) workspaceShellSessions.delete(workspaceRoot); });
+  workspaceShellSessions.set(workspaceRoot, state);
+  return state;
+}
+
+export async function closeWorkspaceShell(workspaceRoot) {
+  const state = workspaceShellSessions.get(workspaceRoot);
+  if (state) {
+    workspaceShellSessions.delete(workspaceRoot);
+    if (state.child.exitCode === null && !state.child.killed) {
+      await new Promise(resolve => {
+        const timer = setTimeout(resolve, 2000);
+        state.child.once('exit', () => { clearTimeout(timer); resolve(); });
+        state.child.kill();
+      });
+    }
+  }
+  workspaceShellCwds.delete(workspaceRoot);
+}
+
+function runWorkspaceCommand(command, workspaceRoot, signal, timeoutMs = 120000) {
+  const state = persistentShell(workspaceRoot);
+  const run = () => new Promise(resolve => {
+    const marker = `__DAVE_COMMAND_DONE_${crypto.randomBytes(8).toString('hex')}__:`;
+    const limit = 8 * 1024 * 1024;
+    let stdout = '';
+    let stderr = '';
+    let truncated = false;
+    let settled = false;
+    const append = (target, chunk) => {
+      const next = target + String(chunk || '');
+      if (next.length <= limit) return next;
+      truncated = true;
+      return next.slice(0, limit);
+    };
+    const cleanup = () => {
+      clearTimeout(timer);
+      state.child.stdout.off('data', onStdout);
+      state.child.stderr.off('data', onStderr);
+      state.child.off('exit', onExit);
+      signal?.removeEventListener('abort', abort);
+    };
+    const finish = (exitCode, extraError = '') => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      resolve({
+        exitCode,
+        stdout: `${stdout.replace(new RegExp(`\\r?\\n?${marker}-?\\d+\\r?\\n?`), '')}${truncated ? '\n[Command output truncated at 8 MiB.]' : ''}`,
+        stderr: `${stderr}${extraError}`,
+        truncated
+      });
+    };
+    const onStdout = chunk => {
+      stdout = append(stdout, chunk);
+      const match = stdout.match(new RegExp(`${marker}(-?\\d+)`));
+      if (match) finish(Number(match[1]) || 0);
+    };
+    const onStderr = chunk => { stderr = append(stderr, chunk); };
+    const onExit = code => finish(code ?? 1, '\nPersistent shell exited unexpectedly.');
+    const abort = () => { state.child.kill(); finish(130, '\nCommand cancelled.'); };
+    const timer = setTimeout(() => { state.child.kill(); finish(124, `\nCommand timed out after ${timeoutMs}ms.`); }, timeoutMs);
+    state.child.stdout.on('data', onStdout);
+    state.child.stderr.on('data', onStderr);
+    state.child.once('exit', onExit);
+    if (signal?.aborted) return abort();
+    signal?.addEventListener('abort', abort, { once: true });
+    const trailer = state.windows
+      ? `\nif ($?) { $daveCode = 0 } elseif ($LASTEXITCODE -is [int]) { $daveCode = $LASTEXITCODE } else { $daveCode = 1 }; [Console]::Out.WriteLine('${marker}' + $daveCode)\n`
+      : `\ndave_code=$?; printf '${marker}%s\\n' "$dave_code"\n`;
+    state.child.stdin.write(`${command}\n${trailer}`);
+  });
+  const task = state.queue.then(run, run);
+  state.queue = task.catch(() => {});
+  return task;
+}
+
+function startBackgroundCommand(command, cwd) {
+  const taskId = `task-${Date.now().toString(36)}-${crypto.randomBytes(3).toString('hex')}`;
+  const child = spawn(command, { cwd, shell: true, windowsHide: true });
+  const task = { id: taskId, command, cwd, child, output: '', exitCode: null, startedAt: Date.now() };
+  const append = chunk => {
+    task.output += String(chunk || '');
+    if (task.output.length > 8 * 1024 * 1024) task.output = `[Earlier output truncated]\n${task.output.slice(-8 * 1024 * 1024)}`;
+  };
+  child.stdout?.on('data', append);
+  child.stderr?.on('data', append);
+  child.on('exit', code => { task.exitCode = code ?? 1; task.endedAt = Date.now(); });
+  backgroundTasks.set(taskId, task);
+  return task;
+}
+
+export async function executeToolCall({
+  toolName,
+  toolArg,
+  workspaceRoot,
+  toolCallId = '',
+  emit = () => {},
+  requestPermission = async () => false,
+  lang = 'cn',
+  mode = 'chat',
+  signal,
+  readTracker,
+  permissionPolicy = { mode: 'ask', rules: [] },
+  contextPlan,
+  remainingBudgetTokens,
+  readNotebook = async () => null
+}) {
+  const budgetTokens = Math.max(4096, Number(contextPlan?.budgetTokens) || 24000);
+  const remaining = Math.max(500, Number(remainingBudgetTokens) || budgetTokens);
+  const maxToolChars = Math.max(4000, Math.min(240000, Math.floor(Math.min(budgetTokens, remaining) * 2.8)));
+  const cn = lang === 'cn';
+  const startedAt = Date.now();
+
+  function event(type, data = {}) {
+    emit(type, { tool: toolName, toolCallId, ...data });
+  }
+
+  function success(modelResult, displaySummary, data = {}) {
+    const durationMs = Date.now() - startedAt;
+    event('tool.completed', { displaySummary, durationMs, ...data });
+    return { ok: true, result: modelResult, modelResult, displaySummary, status: 'Done', data };
+  }
+
+  function failure(error) {
+    const modelResult = `Tool ${toolName} failed: ${error.message}`;
+    const displaySummary = cn ? `${toolName} 失败 · ${error.message}` : `${toolName} failed · ${error.message}`;
+    event('tool.failed', { displaySummary, error: error.message, durationMs: Date.now() - startedAt });
+    return { ok: false, result: modelResult, modelResult, displaySummary, status: 'Failed' };
+  }
+
+  const sessionAllowedTools = permissionPolicy.allowedTools instanceof Set
+    ? permissionPolicy.allowedTools
+    : (permissionPolicy.allowedTools = new Set(permissionPolicy.allowedTools || []));
+
+  function ruleMatches(rule, request) {
+    const match = String(rule || '').match(/^([A-Z_]+)\((.*)\)$/);
+    if (!match || match[1] !== toolName) return false;
+    const value = toolName === 'RUN_COMMAND'
+      ? String(toolArg?.command ?? toolArg ?? '')
+      : String(request.target || toolArg?.path || toolArg?.filePath || toolArg?.source || '');
+    const escaped = match[2].replace(/[.+^${}()|[\]\\]/g, '\\$&').replace(/\*\*/g, '§§').replace(/\*/g, '[^/\\\\]*').replace(/§§/g, '.*');
+    return new RegExp(`^${escaped}$`, process.platform === 'win32' ? 'i' : '').test(value.replace(/\\/g, '/'));
+  }
+
+  async function authorize(request) {
+    if (!MUTATING_TOOLS.has(toolName) || ['DELETE_PATH', 'MOVE_PATH'].includes(toolName)) {
+      return Boolean(await requestPermission(request));
+    }
+    if (sessionAllowedTools.has(toolName)) return true;
+    if ((permissionPolicy.rules || []).some(rule => ruleMatches(rule, request))) return true;
+    const sessionPrompt = String(request.prompt || '').replace(/\(y\/n\)/gi, '(y/a/n)');
+    const decision = await requestPermission({ ...request, prompt: sessionPrompt, allowSession: true });
+    const allowed = decision === true || decision === 'always' || decision === 'a';
+    if (allowed && (permissionPolicy.mode === 'acceptEdits' || decision === 'always' || decision === 'a')) {
+      sessionAllowedTools.add(toolName);
+    }
+    return allowed;
+  }
+
+  try {
+    if (MUTATING_TOOLS.has(toolName) && mode !== 'code') {
+      throw new Error(`Workspace mutation is blocked in ${mode} mode. Use /code <request> to authorize one coding turn.`);
+    }
+
+    if (toolName === 'UPDATE_TODOS') {
+      const todos = Array.isArray(toolArg?.todos) ? toolArg.todos.slice(0, 30).map(todo => ({
+        content: String(todo.content || '').trim().slice(0, 300),
+        status: ['pending', 'in_progress', 'completed'].includes(todo.status) ? todo.status : 'pending'
+      })).filter(todo => todo.content) : [];
+      workspaceTodos.set(workspaceRoot, todos);
+      event('todos.updated', { todos });
+      return success(`Updated task checklist: ${todos.length} items.`, cn ? `已更新任务清单 · ${todos.length} 项` : `Updated checklist · ${todos.length} items`, { count: todos.length });
+    }
+
+    if (toolName === 'LIST_DIR') {
+      const rawPath = toolArg && typeof toolArg === 'object' ? toolArg.path : toolArg;
+      const resolvedPath = resolveExistingWorkspacePath(String(rawPath || '.').trim() || '.', workspaceRoot);
+      const relPath = path.relative(workspaceRoot, resolvedPath) || '.';
+      event('tool.started', { target: relPath, label: cn ? `正在查看 ${relPath}` : `Listing ${relPath}` });
+      const entries = await fs.promises.readdir(resolvedPath, { withFileTypes: true });
+      const rows = await Promise.all(entries.map(async entry => {
+        if (entry.isDirectory()) return `${entry.name} (Dir)`;
+        if (entry.isSymbolicLink()) return `${entry.name} (Symlink)`;
+        const stat = await fs.promises.stat(path.join(resolvedPath, entry.name));
+        return `${entry.name} (File, ${stat.size}B)`;
+      }));
+      const result = rows.join('\n') || '(Empty directory)';
+      return success(
+        truncateToolResult(result, maxToolChars),
+        cn ? `已查看 ${relPath} · ${entries.length} 项` : `Listed ${relPath} · ${entries.length} items`,
+        { target: relPath, itemCount: entries.length }
+      );
+    }
+
+    if (toolName === 'INSPECT_FILE') {
+      const rawPath = toolArg && typeof toolArg === 'object' ? toolArg.path : toolArg;
+      const resolvedPath = resolveExistingWorkspacePath(String(rawPath || '').trim(), workspaceRoot);
+      const relPath = path.relative(workspaceRoot, resolvedPath);
+      if (isSensitivePath(relPath) || isSensitivePath(fs.realpathSync.native(resolvedPath))) {
+        throw new Error(`INSPECT_FILE refuses sensitive paths: ${relPath}`);
+      }
+      const stat = await fs.promises.stat(resolvedPath);
+      if (!stat.isFile()) throw new Error(`INSPECT_FILE target is not a file: ${relPath}`);
+      if (stat.size > 2 * 1024 * 1024) throw new Error(`File is too large to inspect: ${stat.size} bytes.`);
+      if (await looksBinary(resolvedPath)) throw new Error(`INSPECT_FILE refuses binary content: ${relPath}`);
+      const identity = `${stat.size}:${stat.mtimeMs}`;
+      const tracked = trackerEntry(readTracker, relPath, identity);
+      if (tracked?.outline) {
+        return success(
+          tracked.outlineContent || `[Cached outline unavailable; inspect ${relPath} again.]`,
+          cn ? `已复用 ${relPath} 的文件大纲` : `Reused outline for ${relPath}`,
+          { target: relPath, cached: true, outline: true }
+        );
+      }
+      event('tool.started', { target: relPath, label: cn ? `正在分析 ${relPath} 的结构` : `Inspecting structure of ${relPath}` });
+      const content = await fs.promises.readFile(resolvedPath, 'utf8');
+      const outline = buildFileOutline(content, relPath);
+      if (tracked) { tracked.outline = true; tracked.outlineContent = outline; }
+      return success(
+        outline,
+        cn ? `已建立 ${relPath} 的文件大纲` : `Outlined ${relPath}`,
+        { target: relPath, lineCount: content.split('\n').length, outline: true }
+      );
+    }
+
+    if (toolName === 'READ_FILE') {
+      const { filePath, startLine, endLine, hasRange } = parseReadArgument(toolArg);
+      const resolvedPath = resolveExistingWorkspacePath(filePath, workspaceRoot);
+      const relPath = path.relative(workspaceRoot, resolvedPath);
+      const rangeText = hasRange ? `:${startLine}-${endLine ?? 'EOF'}` : '';
+      const target = `${relPath}${rangeText}`;
+      const realReadTarget = fs.realpathSync.native(resolvedPath);
+      if (isSensitivePath(relPath) || isSensitivePath(realReadTarget)) {
+        const displaySummary = cn ? `敏感文件读取确认 · ${relPath}` : `Sensitive file read · ${relPath}`;
+        event('permission.requested', { kind: 'sensitive-read', target: relPath, displaySummary });
+        const allowed = await authorize({
+          kind: 'sensitive-read',
+          prompt: cn
+            ? `读取 ${relPath} 会将内容发送给模型，是否允许？(y/n): `
+            : `Reading ${relPath} sends its content to the model. Allow? (y/n): `,
+          displaySummary
+        });
+        event('permission.resolved', { kind: 'sensitive-read', target: relPath, allowed, displaySummary });
+        if (!allowed) {
+          const modelResult = `Sensitive file read denied by user: ${relPath}`;
+          return { ok: true, cancelled: true, result: modelResult, modelResult, displaySummary, status: 'Cancelled' };
+        }
+      }
+      event('tool.started', { target, label: cn ? `正在读取 ${target}` : `Reading ${target}` });
+      const stat = await fs.promises.stat(resolvedPath);
+      if (!stat.isFile()) throw new Error(`READ_FILE target is not a file: ${relPath}`);
+      if (await looksBinary(resolvedPath)) throw new Error(`READ_FILE refuses binary content: ${relPath}`);
+      const identity = `${stat.size}:${stat.mtimeMs}`;
+      const tracked = trackerEntry(readTracker, relPath, identity);
+
+      if (!hasRange && tracked?.full) {
+        return success(
+          tracked.fullContent,
+          cn ? `已复用 ${relPath} · 文件未变化` : `Reused ${relPath} · unchanged`,
+          { target: relPath, cached: true }
+        );
+      }
+
+      if (hasRange) {
+        const rangeKey = `${startLine}:${endLine ?? '*'}`;
+        const cachedRange = tracked?.rangeContents?.get(rangeKey);
+        if (cachedRange) {
+          return success(
+            cachedRange,
+            cn ? `已复用 ${target} · 文件未变化` : `Reused ${target} · unchanged`,
+            { target, cached: true }
+          );
+        }
+        const ranged = await readLinePage(resolvedPath, startLine, endLine, maxToolChars);
+        const rangedResult = ranged.content;
+        if (tracked) {
+          tracked.ranges.push([startLine, ranged.nextCursor ? ranged.nextCursor - 1 : ranged.lastLine]);
+          if (!tracked.rangeContents) tracked.rangeContents = new Map();
+          tracked.rangeContents.set(rangeKey, rangedResult);
+        }
+        return success(
+          rangedResult,
+          cn ? `已读取 ${target} · ${ranged.lineCount} 行` : `Read ${target} · ${ranged.lineCount} lines`,
+          { target, lineCount: ranged.lineCount, totalLines: null, nextCursor: ranged.nextCursor }
+        );
+      }
+
+      if (stat.size > maxToolChars) {
+        const page = await readLinePage(resolvedPath, 1, null, maxToolChars);
+        if (tracked) {
+          tracked.full = false;
+          tracked.ranges.push([1, page.nextCursor ? page.nextCursor - 1 : page.lastLine]);
+          tracked.rangeContents.set('1:*', page.content);
+        }
+        return success(
+          page.content,
+          cn ? `已读取 ${relPath} · ${page.lineCount} 行${page.nextCursor ? ' · 可继续' : ''}` : `Read ${relPath} · ${page.lineCount} lines${page.nextCursor ? ' · continuation available' : ''}`,
+          { target: relPath, lineCount: page.lineCount, totalLines: null, nextCursor: page.nextCursor, paged: true }
+        );
+      }
+      const content = await fs.promises.readFile(resolvedPath, 'utf8');
+      const lines = content.split('\n');
+      const fullResult = truncateToolResult(content, maxToolChars);
+      if (tracked) { tracked.full = true; tracked.fullContent = fullResult; }
+      return success(
+        fullResult,
+        cn ? `已读取 ${relPath} · ${lines.length} 行` : `Read ${relPath} · ${lines.length} lines`,
+        { target: relPath, lineCount: lines.length, totalLines: lines.length }
+      );
+    }
+
+    if (toolName === 'READ_NOTEBOOK') {
+      event('tool.started', { label: cn ? '正在按需读取项目笔记' : 'Reading project notebook on demand' });
+      const request = toolArg && typeof toolArg === 'object' ? toolArg : {};
+      const requestedMax = Math.max(100, Math.min(4000, Number(request.maxTokens) || 2000));
+      const allowedMax = Math.max(100, Math.min(requestedMax, remaining));
+      const result = await readNotebook({
+        sections: Array.isArray(request.sections) ? request.sections.map(String).slice(0, 12) : [],
+        query: String(request.query || ''),
+        maxTokens: allowedMax
+      });
+      if (!result) throw new Error('No private project notebook is available for this workspace.');
+      return success(
+        truncateToolResult(String(result), Math.min(maxToolChars, allowedMax * 4)),
+        cn ? `已读取项目笔记 · 上限 ${allowedMax} Token` : `Read project notebook · up to ${allowedMax} tokens`,
+        { maxTokens: allowedMax }
+      );
+    }
+
+    if (toolName === 'EDIT_FILE') {
+      const { filePath, oldText, newText, replaceAll } = parseEditArgument(toolArg);
+      if (!filePath) throw new Error('EDIT_FILE path is empty.');
+      if (!oldText) throw new Error('EDIT_FILE search text is empty.');
+      const resolvedPath = resolveExistingWorkspacePath(filePath, workspaceRoot);
+      const relPath = path.relative(workspaceRoot, resolvedPath);
+      const oldContent = await fs.promises.readFile(resolvedPath, 'utf8');
+      const expectedHash = contentHash(oldContent);
+      const eol = oldContent.includes('\r\n') ? '\r\n' : '\n';
+      const normalizedContent = oldContent.replace(/\r\n/g, '\n');
+      const normalizedOld = String(oldText).replace(/\r\n/g, '\n');
+      const normalizedNew = String(newText).replace(/\r\n/g, '\n');
+      if (readTracker?.files) {
+        const stat = await fs.promises.stat(resolvedPath);
+        const identity = `${stat.size}:${stat.mtimeMs}`;
+        const entry = readTracker.files.get(relPath);
+        if (!entry || entry.identity !== identity) {
+          throw new Error(`EDIT_FILE requires reading ${relPath} first. Use READ_FILE or INSPECT_FILE.`);
+        }
+        const matchOffset = normalizedContent.indexOf(normalizedOld);
+        const startLine = normalizedContent.slice(0, Math.max(0, matchOffset)).split('\n').length;
+        const endLine = startLine + normalizedOld.split('\n').length - 1;
+        if (!rangeAlreadyRead(entry, startLine, endLine)) {
+          throw new Error(`EDIT_FILE requires reading ${relPath}:${startLine}-${endLine} first with READ_FILE.`);
+        }
+      }
+      const matches = countOccurrences(normalizedContent, normalizedOld);
+      if (matches === 0) {
+        throw new Error(`EDIT_FILE search text was not found in ${relPath}. Read the exact current lines and retry.`);
+      }
+      if (matches > 1 && !replaceAll) {
+        throw new Error(`EDIT_FILE search text matched ${matches} locations in ${relPath}. Include more surrounding context or set replaceAll.`);
+      }
+
+      const updatedNormalized = replaceAll
+        ? normalizedContent.split(normalizedOld).join(normalizedNew)
+        : normalizedContent.replace(normalizedOld, normalizedNew);
+      const updatedContent = eol === '\r\n' ? updatedNormalized.replace(/\n/g, '\r\n') : updatedNormalized;
+      const preview = buildWritePreview(resolvedPath, oldContent, updatedContent, true);
+      const displaySummary = cn
+        ? `修改 ${relPath} · ${replaceAll ? matches : 1} 处`
+        : `Edit ${relPath} · ${replaceAll ? matches : 1} replacement${matches === 1 ? '' : 's'}`;
+      event('permission.requested', { kind: 'edit', target: relPath, displaySummary, preview });
+      const proceed = await authorize({
+        kind: 'edit',
+        prompt: cn ? '应用此局部修改？(y/n): ' : 'Apply this focused edit? (y/n): ',
+        displaySummary,
+        preview
+      });
+      event('permission.resolved', {
+        kind: 'edit',
+        target: relPath,
+        allowed: proceed,
+        displaySummary: proceed
+          ? (cn ? '已确认局部修改' : 'Focused edit approved')
+          : (cn ? `已取消修改 ${relPath}` : `Cancelled edit to ${relPath}`)
+      });
+      if (!proceed) {
+        const modelResult = `Edit cancelled by user: ${relPath}`;
+        return { ok: true, cancelled: true, result: modelResult, modelResult, displaySummary, status: 'Cancelled' };
+      }
+
+      event('tool.started', { target: relPath, label: cn ? `正在修改 ${relPath}` : `Editing ${relPath}` });
+      resolveExistingWorkspacePath(filePath, workspaceRoot);
+      const currentContent = await fs.promises.readFile(resolvedPath, 'utf8');
+      if (contentHash(currentContent) !== expectedHash) {
+        throw new Error(`${relPath} changed while awaiting confirmation. Read the file again before editing.`);
+      }
+      await recordMutation(workspaceRoot, { kind: 'write', path: relPath, existed: true, content: currentContent });
+      await fs.promises.writeFile(resolvedPath, updatedContent, 'utf8');
+      const validation = await automaticSyntaxCheck(resolvedPath, workspaceRoot, signal);
+      const modelResult = `Successfully edited ${relPath}: ${replaceAll ? matches : 1} replacement(s).${validation}`;
+      return success(modelResult, cn ? `已修改 ${relPath} · ${replaceAll ? matches : 1} 处` : `Edited ${relPath} · ${replaceAll ? matches : 1} replacement(s)`, {
+        target: relPath,
+        replacements: replaceAll ? matches : 1
+      });
+    }
+
+    if (toolName === 'WRITE_FILE') {
+      let filePathPart;
+      let fileContentPart;
+      if (toolArg && typeof toolArg === 'object') {
+        filePathPart = String(toolArg.path || toolArg.filePath || '');
+        fileContentPart = String(toolArg.content ?? '');
+      } else {
+        const rawArg = String(toolArg || '');
+        const firstNewline = rawArg.indexOf('\n');
+        filePathPart = firstNewline === -1 ? rawArg : rawArg.slice(0, firstNewline);
+        fileContentPart = firstNewline === -1 ? '' : rawArg.slice(firstNewline + 1);
+      }
+      const resolvedPath = resolveWorkspacePath(filePathPart.trim(), workspaceRoot);
+      const existed = fs.existsSync(resolvedPath);
+      const oldContent = existed ? await fs.promises.readFile(resolvedPath, 'utf8') : '';
+      const expectedHash = existed ? contentHash(oldContent) : null;
+      const relPath = path.relative(workspaceRoot, resolvedPath);
+      if (existed && readTracker?.files) {
+        const stat = await fs.promises.stat(resolvedPath);
+        const entry = readTracker.files.get(relPath);
+        if (!entry || entry.identity !== `${stat.size}:${stat.mtimeMs}`) {
+          throw new Error(`WRITE_FILE requires reading ${relPath} first. Use READ_FILE or INSPECT_FILE.`);
+        }
+      }
+      const preview = buildWritePreview(resolvedPath, oldContent, fileContentPart, existed);
+      const displaySummary = cn
+        ? `${existed ? '修改' : '创建'} ${relPath}`
+        : `${existed ? 'Update' : 'Create'} ${relPath}`;
+      event('permission.requested', { kind: 'write', target: relPath, displaySummary, preview });
+      const proceed = await authorize({
+        kind: 'write',
+        prompt: cn ? '应用此文件更改？(y/n): ' : 'Apply this file change? (y/n): ',
+        displaySummary,
+        preview
+      });
+      event('permission.resolved', {
+        kind: 'write',
+        target: relPath,
+        allowed: proceed,
+        displaySummary: proceed
+          ? (cn ? '已确认文件更改' : 'File change approved')
+          : (cn ? `已取消修改 ${relPath}` : `Cancelled change to ${relPath}`)
+      });
+      if (!proceed) {
+        const modelResult = `Write cancelled by user: ${relPath}`;
+        return { ok: true, cancelled: true, result: modelResult, modelResult, displaySummary, status: 'Cancelled' };
+      }
+
+      event('tool.started', { target: relPath, label: cn ? `正在写入 ${relPath}` : `Writing ${relPath}` });
+      resolveWorkspacePath(filePathPart.trim(), workspaceRoot);
+      if (existed) {
+        const currentContent = await fs.promises.readFile(resolvedPath, 'utf8');
+        if (contentHash(currentContent) !== expectedHash) {
+          throw new Error(`${relPath} changed while awaiting confirmation. Read the file again before writing.`);
+        }
+      } else if (fs.existsSync(resolvedPath)) {
+        throw new Error(`${relPath} was created while awaiting confirmation. Read it before writing.`);
+      }
+      await recordMutation(workspaceRoot, { kind: 'write', path: relPath, existed, ...(existed ? { content: oldContent } : {}) });
+      await fs.promises.mkdir(path.dirname(resolvedPath), { recursive: true });
+      await fs.promises.writeFile(resolvedPath, fileContentPart, 'utf8');
+      const validation = await automaticSyntaxCheck(resolvedPath, workspaceRoot, signal);
+      const modelResult = `Successfully wrote file: ${relPath}${validation}`;
+      return success(
+        modelResult,
+        cn ? `已${existed ? '修改' : '创建'} ${relPath}` : `${existed ? 'Updated' : 'Created'} ${relPath}`,
+        { target: relPath, created: !existed, bytes: Buffer.byteLength(fileContentPart, 'utf8') }
+      );
+    }
+
+    if (toolName === 'MAKE_DIR') {
+      const rawPath = toolArg && typeof toolArg === 'object' ? toolArg.path : toolArg;
+      const resolvedPath = resolveWorkspacePath(String(rawPath || '').trim(), workspaceRoot);
+      const directoryExisted = fs.existsSync(resolvedPath);
+      const relPath = path.relative(workspaceRoot, resolvedPath);
+      const displaySummary = cn ? `创建目录 ${relPath}` : `Create directory ${relPath}`;
+      event('permission.requested', { kind: 'mkdir', target: relPath, displaySummary });
+      const proceed = await authorize({
+        kind: 'mkdir',
+        prompt: cn ? `创建目录 ${relPath}？(y/n): ` : `Create directory ${relPath}? (y/n): `,
+        displaySummary
+      });
+      event('permission.resolved', { kind: 'mkdir', target: relPath, allowed: proceed, displaySummary });
+      if (!proceed) {
+        const modelResult = `Directory creation cancelled by user: ${relPath}`;
+        return { ok: true, cancelled: true, result: modelResult, modelResult, displaySummary, status: 'Cancelled' };
+      }
+      event('tool.started', { target: relPath, label: cn ? `正在创建目录 ${relPath}` : `Creating directory ${relPath}` });
+      resolveWorkspacePath(String(rawPath || '').trim(), workspaceRoot);
+      if (!directoryExisted && fs.existsSync(resolvedPath)) {
+        throw new Error(`${relPath} appeared while awaiting confirmation. Inspect it before continuing.`);
+      }
+      await recordMutation(workspaceRoot, { kind: 'mkdir', path: relPath, existed: directoryExisted });
+      await fs.promises.mkdir(resolvedPath, { recursive: true });
+      return success(
+        `Successfully created directory: ${relPath}`,
+        cn ? `已创建目录 ${relPath}` : `Created directory ${relPath}`,
+        { target: relPath }
+      );
+    }
+
+    if (toolName === 'MOVE_PATH') {
+      const { source, destination } = parseMoveArgument(toolArg);
+      if (!source || !destination) throw new Error('MOVE_PATH requires source and destination paths.');
+      const sourcePath = resolveExistingWorkspacePath(source, workspaceRoot);
+      const destinationPath = resolveWorkspacePath(destination, workspaceRoot);
+      const sourceIdentity = await fs.promises.lstat(sourcePath);
+      const sourceRel = path.relative(workspaceRoot, sourcePath);
+      const destinationRel = path.relative(workspaceRoot, destinationPath);
+      if (fs.existsSync(destinationPath)) throw new Error(`MOVE_PATH destination already exists: ${destinationRel}`);
+      const displaySummary = cn ? `移动 ${sourceRel} → ${destinationRel}` : `Move ${sourceRel} -> ${destinationRel}`;
+      event('permission.requested', { kind: 'move', target: sourceRel, displaySummary });
+      const proceed = await authorize({
+        kind: 'move',
+        prompt: cn ? `移动到 ${destinationRel}？(y/n): ` : `Move to ${destinationRel}? (y/n): `,
+        displaySummary
+      });
+      event('permission.resolved', { kind: 'move', target: sourceRel, allowed: proceed, displaySummary: proceed ? displaySummary : (cn ? '已取消移动' : 'Move cancelled') });
+      if (!proceed) {
+        const modelResult = `Move cancelled by user: ${sourceRel}`;
+        return { ok: true, cancelled: true, result: modelResult, modelResult, displaySummary, status: 'Cancelled' };
+      }
+      event('tool.started', { target: sourceRel, label: cn ? `正在移动 ${sourceRel}` : `Moving ${sourceRel}` });
+      resolveExistingWorkspacePath(source, workspaceRoot);
+      resolveWorkspacePath(destination, workspaceRoot);
+      if (fs.existsSync(destinationPath)) throw new Error(`${destinationRel} appeared while awaiting confirmation.`);
+      const currentSourceIdentity = await fs.promises.lstat(sourcePath);
+      if (currentSourceIdentity.dev !== sourceIdentity.dev || currentSourceIdentity.ino !== sourceIdentity.ino || currentSourceIdentity.mtimeMs !== sourceIdentity.mtimeMs || currentSourceIdentity.size !== sourceIdentity.size) {
+        throw new Error(`${sourceRel} changed while awaiting confirmation. Inspect it again before moving.`);
+      }
+      await recordMutation(workspaceRoot, { kind: 'move', source: sourceRel, destination: destinationRel });
+      await fs.promises.mkdir(path.dirname(destinationPath), { recursive: true });
+      await fs.promises.rename(sourcePath, destinationPath);
+      return success(`Successfully moved ${sourceRel} to ${destinationRel}`, displaySummary, { source: sourceRel, destination: destinationRel });
+    }
+
+    if (toolName === 'DELETE_PATH') {
+      const rawPath = toolArg && typeof toolArg === 'object' ? toolArg.path : toolArg;
+      const resolvedPath = resolveExistingWorkspacePath(String(rawPath || '').trim(), workspaceRoot);
+      const relPath = path.relative(workspaceRoot, resolvedPath);
+      if (!relPath) throw new Error('Deleting the workspace root is not allowed.');
+      const stat = await fs.promises.lstat(resolvedPath);
+      const deleteIdentity = { dev: stat.dev, ino: stat.ino, mtimeMs: stat.mtimeMs, size: stat.size };
+      if (stat.isDirectory()) {
+        const entries = await fs.promises.readdir(resolvedPath);
+        if (entries.length > 0) throw new Error('DELETE_PATH only removes files or empty directories.');
+      }
+      const displaySummary = cn ? `删除 ${relPath}` : `Delete ${relPath}`;
+      event('permission.requested', { kind: 'delete', target: relPath, displaySummary });
+      const proceed = await authorize({
+        kind: 'delete',
+        prompt: cn ? `确认删除 ${relPath}？(y/n): ` : `Delete ${relPath}? (y/n): `,
+        displaySummary
+      });
+      event('permission.resolved', { kind: 'delete', target: relPath, allowed: proceed, displaySummary: proceed ? displaySummary : (cn ? '已取消删除' : 'Delete cancelled') });
+      if (!proceed) {
+        const modelResult = `Delete cancelled by user: ${relPath}`;
+        return { ok: true, cancelled: true, result: modelResult, modelResult, displaySummary, status: 'Cancelled' };
+      }
+      event('tool.started', { target: relPath, label: cn ? `正在删除 ${relPath}` : `Deleting ${relPath}` });
+      resolveExistingWorkspacePath(String(rawPath || '').trim(), workspaceRoot);
+      const currentDeleteIdentity = await fs.promises.lstat(resolvedPath);
+      if (currentDeleteIdentity.dev !== deleteIdentity.dev || currentDeleteIdentity.ino !== deleteIdentity.ino || currentDeleteIdentity.mtimeMs !== deleteIdentity.mtimeMs || currentDeleteIdentity.size !== deleteIdentity.size) {
+        throw new Error(`${relPath} changed while awaiting confirmation. Inspect it again before deleting.`);
+      }
+      await recordMutation(workspaceRoot, {
+        kind: 'delete', path: relPath, directory: stat.isDirectory(),
+        ...(!stat.isDirectory() ? { content: await fs.promises.readFile(resolvedPath) } : {})
+      });
+      if (stat.isDirectory()) await fs.promises.rmdir(resolvedPath);
+      else await fs.promises.unlink(resolvedPath);
+      return success(`Successfully deleted: ${relPath}`, cn ? `已删除 ${relPath}` : `Deleted ${relPath}`, { target: relPath });
+    }
+
+    if (toolName === 'READ_TASK_OUTPUT') {
+      const taskId = String(toolArg?.taskId ?? toolArg ?? '').trim();
+      const task = backgroundTasks.get(taskId);
+      if (!task) throw new Error(`Unknown background task: ${taskId}`);
+      const status = task.exitCode === null ? 'running' : `exited ${task.exitCode}`;
+      return success(truncateToolResult(`Task: ${taskId}\nStatus: ${status}\n${task.output || '(no output yet)'}`, maxToolChars), cn ? `后台任务 ${taskId} · ${status}` : `Background task ${taskId} · ${status}`, { taskId, status, exitCode: task.exitCode });
+    }
+
+    if (toolName === 'KILL_TASK') {
+      const taskId = String(toolArg?.taskId ?? toolArg ?? '').trim();
+      const task = backgroundTasks.get(taskId);
+      if (!task) throw new Error(`Unknown background task: ${taskId}`);
+      const proceed = await authorize({ kind: 'kill-task', target: taskId, prompt: cn ? `停止后台任务 ${taskId}？(y/n): ` : `Stop background task ${taskId}? (y/n): `, displaySummary: `Kill ${taskId}` });
+      if (!proceed) return { ok: true, cancelled: true, result: `Task stop cancelled: ${taskId}`, modelResult: `Task stop cancelled: ${taskId}`, displaySummary: 'Cancelled', status: 'Cancelled' };
+      if (task.exitCode === null) task.child.kill();
+      return success(`Stopped background task: ${taskId}`, cn ? `已停止 ${taskId}` : `Stopped ${taskId}`, { taskId });
+    }
+
+    if (toolName === 'RUN_COMMAND') {
+      const rawCommand = toolArg && typeof toolArg === 'object' ? toolArg.command : toolArg;
+      const command = String(rawCommand || '').trim();
+      if (!command) throw new Error('RUN_COMMAND command is empty.');
+      const displaySummary = cn ? `运行命令: ${command}` : `Run command: ${command}`;
+      event('permission.requested', { kind: 'command', displaySummary, preview: `$ ${command}` });
+      const proceed = await authorize({
+        kind: 'command',
+        prompt: cn
+          ? '此命令不受沙箱限制，可能影响工作区外部。仍要运行？(y/n): '
+          : 'This command is not sandboxed and may affect paths outside the workspace. Run it? (y/n): ',
+        displaySummary,
+        preview: `$ ${command}`
+      });
+      event('permission.resolved', { kind: 'command', allowed: proceed, displaySummary: proceed ? (cn ? '已允许命令执行' : 'Command approved') : (cn ? '已取消命令' : 'Command cancelled') });
+      if (!proceed) {
+        const modelResult = `Command cancelled by user: ${command}`;
+        return { ok: true, cancelled: true, result: modelResult, modelResult, displaySummary, status: 'Cancelled' };
+      }
+      event('tool.started', { label: cn ? `正在运行 ${command}` : `Running ${command}` });
+      const shellCwd = workspaceShellCwds.get(workspaceRoot) || workspaceRoot;
+      const cdMatch = command.match(/^cd(?:\s+(.+))?$/i);
+      if (cdMatch) {
+        const nextCwd = resolveExistingWorkspacePath(path.resolve(shellCwd, cdMatch[1] || '.'), workspaceRoot);
+        if (!(await fs.promises.stat(nextCwd)).isDirectory()) throw new Error(`Not a directory: ${cdMatch[1]}`);
+        const setLocation = process.platform === 'win32'
+          ? `Set-Location -LiteralPath '${nextCwd.replace(/'/g, "''")}'`
+          : `cd '${nextCwd.replace(/'/g, `'"'"'`)}'`;
+        const changed = await runWorkspaceCommand(setLocation, workspaceRoot, signal, 10000);
+        if (changed.exitCode !== 0) throw new Error(changed.stderr || `Could not change shell directory to ${nextCwd}`);
+        workspaceShellCwds.set(workspaceRoot, nextCwd);
+        return success(`Shell working directory: ${path.relative(workspaceRoot, nextCwd) || '.'}`, cn ? '已更新 Shell 工作目录' : 'Shell directory updated', { cwd: nextCwd });
+      }
+      if (toolArg?.runInBackground === true) {
+        const task = startBackgroundCommand(command, shellCwd);
+        return success(`Background task started: ${task.id}\nCommand: ${command}`, cn ? `后台任务已启动 · ${task.id}` : `Background task started · ${task.id}`, { taskId: task.id, background: true });
+      }
+      const timeoutMs = Math.max(1000, Math.min(600000, (Number(toolArg?.timeoutSeconds) || 120) * 1000));
+      const commandResult = await runWorkspaceCommand(command, workspaceRoot, signal, timeoutMs);
+      const combined = [
+        `Command: ${command}`,
+        `Exit code: ${commandResult.exitCode}`,
+        commandResult.stdout ? `stdout:\n${commandResult.stdout}` : '',
+        commandResult.stderr ? `stderr:\n${commandResult.stderr}` : ''
+      ].filter(Boolean).join('\n');
+      const modelResult = truncateToolResult(combined, maxToolChars);
+      if (commandResult.exitCode !== 0) {
+        const failedSummary = cn ? `命令失败 · 退出码 ${commandResult.exitCode}` : `Command failed · exit ${commandResult.exitCode}`;
+        event('tool.failed', { displaySummary: failedSummary, error: commandResult.stderr || commandResult.error?.message || failedSummary, durationMs: Date.now() - startedAt });
+        return { ok: false, result: modelResult, modelResult, displaySummary: failedSummary, status: 'Failed', data: { exitCode: commandResult.exitCode } };
+      }
+      return success(modelResult, cn ? '命令执行完成' : 'Command completed', { exitCode: 0 });
+    }
+
+    if (toolName === 'GLOB_FILES') {
+      const pattern = String(toolArg?.pattern ?? toolArg ?? '').trim();
+      if (!pattern) throw new Error('GLOB_FILES pattern is empty.');
+      event('tool.started', { label: cn ? `正在匹配文件 ${pattern}` : `Matching files ${pattern}` });
+      let paths;
+      try {
+        const rg = await runExecutable('rg', ['--files', '-g', pattern, '-g', '!.git/**', '-g', '!node_modules/**'], workspaceRoot, signal);
+        paths = rg.stdout.split(/\r?\n/).filter(Boolean);
+      } catch (error) {
+        if (error.code !== 'ENOENT') throw error;
+        paths = [];
+        const matcher = new RegExp(`^${pattern.replace(/[.+^${}()|[\]\\]/g, '\\$&').replace(/\*\*/g, '§§').replace(/\*/g, '[^/]*').replace(/§§/g, '.*').replace(/\?/g, '.')}$`, process.platform === 'win32' ? 'i' : '');
+        async function walk(dir) {
+          for (const entry of await fs.promises.readdir(dir, { withFileTypes: true })) {
+            if (['.git', 'node_modules'].includes(entry.name)) continue;
+            const full = path.join(dir, entry.name);
+            const rel = path.relative(workspaceRoot, full).replace(/\\/g, '/');
+            if (entry.isDirectory()) await walk(full);
+            else if (entry.isFile() && matcher.test(rel)) paths.push(rel);
+          }
+        }
+        await walk(workspaceRoot);
+      }
+      const rows = (await Promise.all(paths.filter(file => !isSensitivePath(file)).map(async file => {
+        const stat = await fs.promises.stat(path.join(workspaceRoot, file));
+        return { file, mtimeMs: stat.mtimeMs };
+      }))).sort((a, b) => b.mtimeMs - a.mtimeMs).slice(0, 500);
+      const modelResult = rows.length ? rows.map(row => `${row.file}\t${new Date(row.mtimeMs).toISOString()}`).join('\n') : `No files matched ${pattern}`;
+      return success(modelResult, cn ? `匹配 ${pattern} · ${rows.length} 个文件` : `Matched ${pattern} · ${rows.length} files`, { pattern, count: rows.length });
+    }
+
+    if (toolName === 'SEARCH_GREP') {
+      const request = toolArg && typeof toolArg === 'object' ? toolArg : { query: toolArg };
+      const rawQuery = request.pattern ?? request.query;
+      const query = String(rawQuery || '').trim();
+      if (!query) throw new Error('Search query is empty.');
+      event('tool.started', { query, label: cn ? `正在搜索 “${query}”` : `Searching "${query}"` });
+      try {
+        const args = ['--color', 'never', '--no-heading', '--max-count', '50', '-g', '!.git/**', '-g', '!node_modules/**', '-g', '!.env*', '-g', '!*.pem', '-g', '!*.key'];
+        const outputMode = request.outputMode || 'content';
+        if (outputMode === 'files_with_matches') args.push('--files-with-matches');
+        else if (outputMode === 'count') args.push('--count');
+        else args.push('--line-number');
+        if (request.literal === true || (request.pattern === undefined && request.query !== undefined)) args.push('--fixed-strings');
+        if (request.caseInsensitive) args.push('--ignore-case');
+        if (Number(request.contextLines) > 0 && outputMode === 'content') args.push('--context', String(Math.min(20, Number(request.contextLines))));
+        if (request.glob) args.push('--glob', String(request.glob));
+        args.push('--', query, '.');
+        const rg = await runExecutable('rg', args, workspaceRoot, signal);
+        if (![0, 1].includes(rg.exitCode)) throw new Error(`ripgrep failed (${rg.exitCode}): ${rg.stderr.trim()}`);
+        const output = rg.stdout.split(/\r?\n/).filter(line => {
+          if (!line || line === '--') return true;
+          let candidate = line;
+          if (outputMode === 'content') candidate = line.match(/^(.+?)(?::|-)\d+(?::|-)/)?.[1] || line;
+          else if (outputMode === 'count') candidate = line.replace(/:\d+\s*$/, '');
+          candidate = candidate.replace(/^\.\//, '').replace(/^\.\\/, '');
+          return !isSensitivePath(candidate);
+        }).join('\n').trim();
+        const matchCount = output ? output.split(/\r?\n/).length : 0;
+        return success(
+          truncateToolResult(output || `No matches found for "${query}"`, maxToolChars),
+          cn ? `搜索 “${query}” · ${matchCount} 行` : `Searched "${query}" · ${matchCount} lines`,
+          { query, matchCount, engine: 'ripgrep', outputMode }
+        );
+      } catch (error) {
+        if (error.code !== 'ENOENT') throw error;
+      }
+      const results = [];
+      let totalMatches = 0;
+      let searchWasPartial = false;
+      const maxTotalMatches = 50;
+
+      async function searchGrep(dir, depth = 0) {
+        if (depth > 6) {
+          searchWasPartial = true;
+          return;
+        }
+        if (totalMatches >= maxTotalMatches) return;
+        const entries = (await fs.promises.readdir(dir, { withFileTypes: true }))
+          .sort((a, b) => a.name.localeCompare(b.name));
+        for (const entry of entries) {
+          if (totalMatches >= maxTotalMatches) break;
+          const file = entry.name;
+          if (file === 'node_modules' || file === '.git' || file === '.gemini' || file === 'package-lock.json') continue;
+          const fullPath = path.join(dir, file);
+          if (isSensitivePath(path.relative(workspaceRoot, fullPath))) continue;
+          try {
+            if (entry.isDirectory()) {
+              await searchGrep(fullPath, depth + 1);
+            } else if (entry.isFile()) {
+              const stat = await fs.promises.stat(fullPath);
+              const ext = path.extname(file).toLowerCase();
+              if (!DEFAULT_TEXT_EXTS.has(ext) && stat.size >= 100000) continue;
+              const content = await fs.promises.readFile(fullPath, 'utf8');
+              if (!content.includes(query)) continue;
+              const lines = content.split('\n');
+              const fileMatches = [];
+              for (let i = 0; i < lines.length; i++) {
+                if (lines[i].includes(query)) {
+                  const text = lines[i].trim();
+                  fileMatches.push({ lineNum: i + 1, text: text.length > 140 ? `${text.slice(0, 137)}...` : text });
+                  totalMatches++;
+                  if (totalMatches >= maxTotalMatches) break;
+                }
+              }
+              if (fileMatches.length > 0) {
+                results.push({ file: path.relative(workspaceRoot, fullPath), matches: fileMatches });
+              }
+            }
+          } catch (e) {
+            searchWasPartial = true;
+          }
+        }
+      }
+
+      await searchGrep(workspaceRoot);
+      if (results.length === 0) {
+        const modelResult = `No matches found for "${query}"${searchWasPartial ? '\n[Search was partial because some paths were too deep or unreadable.]' : ''}`;
+        return success(modelResult, cn ? `搜索 “${query}” · 无结果` : `Searched "${query}" · no matches`, { query, matchCount: 0, partial: searchWasPartial });
+      }
+      let output = 'Found matches:\n';
+      for (const result of results) {
+        output += `- ${result.file}:\n`;
+        for (const match of result.matches) {
+          output += `    Line ${match.lineNum}: ${match.text}\n`;
+        }
+      }
+      if (totalMatches >= maxTotalMatches) {
+        output += `[Search truncated at ${maxTotalMatches} matches. Use a narrower query if needed.]\n`;
+      }
+      if (searchWasPartial) output += '[Search was partial because some paths were too deep or unreadable.]\n';
+      return success(
+        truncateToolResult(output, maxToolChars),
+        cn ? `搜索 “${query}” · ${totalMatches} 处` : `Searched "${query}" · ${totalMatches} matches`,
+        { query, matchCount: totalMatches, truncated: totalMatches >= maxTotalMatches, partial: searchWasPartial }
+      );
+    }
+
+    return failure(new Error(`Unknown tool: ${toolName}`));
+  } catch (error) {
+    return failure(error);
+  }
+}