@calliopelabs/cli 2.5.0 → 3.1.0

package/dist/tools.js

@@ -8,16 +8,13 @@ import * as fs from 'fs';
 import * as path from 'path';
 import * as os from 'os';
 import { StringDecoder } from 'string_decoder';
-import * as sandbox from './sandbox.js';
-import * as nativeSandbox from './sandbox-native.js';
-import { getAgtermTools, isAgtermTool, executeAgtermTool } from './agents/index.js';
+import * as sandbox from './sandbox/index.js';
 import { validatePath as scopeValidatePath, isInScope } from './scope.js';
 import { getPluginTools, isPluginTool, executePluginTool } from './plugins.js';
 import config from './config.js';
-import { applySkin, applyPalette, listSkins, listPalettes } from './hud/api.js';
-import { listCompanions } from './companions.js';
 import { generateDiff as generateFileDiff } from './diff.js';
-import { scuttlebotClient } from './scuttlebot/index.js';
+import { fleetActive, fleetMirrorToolCall } from './fleet.js';
+import { computeAnchorHash, anchorHashFooter } from './local-model.js';
 /**
  * Available tools for the agent
  */
@@ -273,36 +270,21 @@ export const TOOLS = [
     },
     {
         name: 'configure',
-        description: `Read, set, or list Calliope configuration options. Use this when the user asks to change settings, switch themes, providers, models, companions, or any preference through natural conversation. Always use action "list" first if you need to show available options.
+        description: `Read, set, or list Calliope configuration options. Use this when the user asks to change settings, switch themes, providers, models, or any preference through natural conversation. Always use action "list" first if you need to show available options.
 
 CONFIGURABLE SETTINGS:
 - defaultProvider: AI provider (anthropic, google, openai, together, openrouter, groq, fireworks, mistral, ollama, ai21, huggingface, litellm, bedrock, auto)
 - defaultModel: Model name string (provider-specific, e.g. "claude-sonnet-4-6", "gemini-2.0-flash", "gpt-4o")
-- persona: Agent persona style (calliope, muse, minimal)
 - maxIterations: Max agent loop iterations (0 = unlimited)
 - maxIterationTime: Max seconds per iteration (0 = no limit, default: 600)
-- fancyOutput: Enable rich formatting (true/false)
 - autoSaveHistory: Auto-save session history (true/false)
 - autoUpgrade: Check for updates on startup (true/false)
 - collapseTools: Auto-collapse tool output (true/false)
-- collapseThinking: Auto-collapse think blocks (true/false)
 - toolDisplayLimit: Show last N tools expanded (0 = all)
-- layout: UI layout (classic, response-top, response-bottom, split, zen, focus, dashboard, minimal)
-- density: Display density (normal, compact)
-- activeSkin: Terminal skin/theme name (use action "list" category "skins" to see options)
-- activePalette: Color palette name (use action "list" category "palettes" to see options)
-- activeCompanion: AI companion personality (use action "list" category "companions" to see options)
-- companionIntensity: Companion personality level (professional, immersive)
-- useEmojis: Show emojis in UI (true/false)
 - diffStyle: Diff display format (inline, unified, side-by-side)
-- borderStyle: UI border style (rounded, sharp, double, ascii, none)
-- bannerStyle: Startup banner (full, compact, none)
 - circuitBreakersEnabled: Safety circuit breakers (true/false)
 - sandboxMode: Code execution sandbox (auto, native, docker, off)
-- smartRoutingEnabled: Dynamic model routing (true/false)
-- smartRoutingCostSensitivity: Cost vs quality (0-1, 0=best quality, 1=cheapest)
-- recordSessions: Record session audit logs (true/false)
-- recordingRetentionDays: Auto-delete old recordings after N days (0 = keep forever)`,
+- sessionLogLimit: Cap retained session log items (0 = unlimited)`,
         parameters: {
             type: 'object',
             properties: {
@@ -321,8 +303,8 @@ CONFIGURABLE SETTINGS:
                 },
                 category: {
                     type: 'string',
-                    description: 'Category to list options for (for list action): skins, palettes, companions, providers, layouts, all',
-                    enum: ['skins', 'palettes', 'companions', 'providers', 'layouts', 'all'],
+                    description: 'Category to list options for (for list action): providers, layouts, all',
+                    enum: ['providers', 'layouts', 'all'],
                 },
             },
             required: ['action'],
@@ -354,13 +336,9 @@ CONFIGURABLE SETTINGS:
 ];
 /**
  * Get all available tools
- * Includes agent tools when agentEnabled is true
  */
-export function getTools(agentEnabled = false) {
+export function getTools() {
     const pluginTools = getPluginTools();
-    if (agentEnabled) {
-        return [...TOOLS, ...getAgtermTools(), ...pluginTools];
-    }
     return [...TOOLS, ...pluginTools];
 }
 /**
@@ -395,17 +373,11 @@ function validatePath(filePath, cwd) {
 /**
  * Execute a tool call
  */
-export async function executeTool(toolCall, cwd, timeout = 60000, onOutput) {
+export async function executeTool(toolCall, cwd, timeout = 60000, onOutput, options) {
     const { id, name, arguments: args } = toolCall;
-    // Mirror tool call to scuttlebot
-    if (scuttlebotClient.isEnabled()) {
-        await scuttlebotClient.mirrorToolCall(name, args).catch(() => {
-            // Silently fail - don't interrupt tool execution
-        });
-    }
-    // Handle agent tools
-    if (isAgtermTool(name)) {
-        return executeAgtermTool(toolCall, cwd);
+    // Mirror tool call to the fleet channel
+    if (fleetActive()) {
+        await fleetMirrorToolCall(name, args);
     }
     // Handle plugin tools
     if (isPluginTool(name)) {
@@ -425,7 +397,7 @@ export async function executeTool(toolCall, cwd, timeout = 60000, onOutput) {
                 if (typeof args.path !== 'string') {
                     return { toolCallId: id, result: 'Error: path must be a string', isError: true };
                 }
-                result = await readFile(args.path, cwd);
+                result = await readFile(args.path, cwd, options?.appendAnchorHash === true, options?.fs);
                 break;
             }
             case 'write_file': {
@@ -435,7 +407,7 @@ export async function executeTool(toolCall, cwd, timeout = 60000, onOutput) {
                 if (typeof args.content !== 'string') {
                     return { toolCallId: id, result: 'Error: content must be a string', isError: true };
                 }
-                result = await writeFile(args.path, args.content, cwd);
+                result = await writeFile(args.path, args.content, cwd, options?.fs);
                 break;
             }
             case 'list_files': {
@@ -520,42 +492,21 @@ export async function executeTool(toolCall, cwd, timeout = 60000, onOutput) {
                 if (action === 'list') {
                     const category = args.category || 'all';
                     const sections = [];
-                    if (category === 'skins' || category === 'all') {
-                        const skins = listSkins();
-                        const current = config.get('activeSkin');
-                        sections.push('SKINS (activeSkin):\n' + skins.map(s => `  ${s.name === current ? '→ ' : '  '}${s.name} - ${s.description}`).join('\n'));
-                    }
-                    if (category === 'palettes' || category === 'all') {
-                        const palettes = listPalettes();
-                        const current = config.get('activePalette');
-                        sections.push('PALETTES (activePalette):\n' + palettes.map(p => `  ${p.name === current ? '→ ' : '  '}${p.name} - ${p.description}`).join('\n'));
-                    }
-                    if (category === 'companions' || category === 'all') {
-                        const companions = listCompanions();
-                        const current = config.get('activeCompanion');
-                        sections.push('COMPANIONS (activeCompanion):\n' + companions.map(c => `  ${c.name === current ? '→ ' : '  '}${c.name} - ${c.description}`).join('\n'));
-                    }
                     if (category === 'providers' || category === 'all') {
                         const providers = ['anthropic', 'google', 'openai', 'together', 'openrouter', 'groq', 'fireworks', 'mistral', 'ollama', 'ai21', 'huggingface', 'litellm', 'bedrock', 'auto'];
                         const current = config.get('defaultProvider');
                         sections.push('PROVIDERS (defaultProvider):\n' + providers.map(p => `  ${p === current ? '→ ' : '  '}${p}`).join('\n'));
                     }
-                    if (category === 'layouts' || category === 'all') {
-                        const layouts = ['classic', 'response-top', 'response-bottom', 'split', 'zen', 'focus', 'dashboard', 'minimal'];
-                        const current = config.get('layout');
-                        sections.push('LAYOUTS (layout):\n' + layouts.map(l => `  ${l === current ? '→ ' : '  '}${l}`).join('\n'));
-                    }
                     if (category === 'all') {
                         // Also show current key settings
                         const currentSettings = [
-                            `density: ${config.get('density')}`,
-                            `companionIntensity: ${config.get('companionIntensity')}`,
-                            `useEmojis: ${config.get('useEmojis')}`,
                             `diffStyle: ${config.get('diffStyle')}`,
-                            `borderStyle: ${config.get('borderStyle')}`,
-                            `bannerStyle: ${config.get('bannerStyle')}`,
                             `sandboxMode: ${config.get('sandboxMode')}`,
-                            `smartRoutingEnabled: ${config.get('smartRoutingEnabled')}`,
+                            `collapseTools: ${config.get('collapseTools')}`,
+                            `toolDisplayLimit: ${config.get('toolDisplayLimit')}`,
+                            `maxIterations: ${config.get('maxIterations')}`,
+                            `sessionLogLimit: ${config.get('sessionLogLimit')}`,
+                            `routing.enabled: ${config.get('routing')?.enabled ?? false}`,
                             `defaultModel: ${config.get('defaultModel') || '(auto)'}`,
                         ];
                         sections.push('CURRENT SETTINGS:\n' + currentSettings.map(s => `  ${s}`).join('\n'));
@@ -583,16 +534,11 @@ export async function executeTool(toolCall, cwd, timeout = 60000, onOutput) {
                 }
                 // Only allow setting safe keys through conversation (allowlist)
                 const SAFE_CONFIG_KEYS = new Set([
-                    'defaultProvider', 'defaultModel', 'persona', 'maxIterations', 'maxIterationTime',
-                    'fancyOutput', 'autoSaveHistory', 'autoUpgrade',
-                    'collapseTools', 'collapseThinking', 'toolDisplayLimit',
-                    'layout', 'density',
-                    'activeSkin', 'activePalette', 'activeCompanion', 'activeThemePack',
-                    'companionIntensity', 'useEmojis', 'diffStyle', 'borderStyle', 'bannerStyle',
+                    'defaultProvider', 'defaultModel', 'maxIterations', 'maxIterationTime',
+                    'autoSaveHistory', 'autoUpgrade',
+                    'collapseTools', 'toolDisplayLimit', 'diffStyle',
                     'circuitBreakersEnabled', 'sandboxMode',
-                    'smartRoutingEnabled', 'smartRoutingCostSensitivity',
-                    'recordSessions', 'recordingRetentionDays', 'sessionLogLimit',
-                    'awsRegion', 'awsProfile',
+                    'sessionLogLimit',
                 ]);
                 if (!SAFE_CONFIG_KEYS.has(key)) {
                     return { toolCallId: id, result: `Error: "${key}" cannot be set through conversation. Use /keys command, environment variables, or edit the config file directly.`, isError: true };
@@ -606,31 +552,6 @@ export async function executeTool(toolCall, cwd, timeout = 60000, onOutput) {
                 else if (/^\d+(\.\d+)?$/.test(rawValue))
                     parsedValue = Number(rawValue);
                 try {
-                    // Special handling for HUD settings that need apply functions
-                    if (key === 'activeSkin') {
-                        const success = applySkin(rawValue);
-                        if (!success) {
-                            return { toolCallId: id, result: `Error: skin "${rawValue}" not found. Use action "list" category "skins" to see available skins.`, isError: true };
-                        }
-                        result = `Skin changed to "${rawValue}"`;
-                        break;
-                    }
-                    if (key === 'activePalette') {
-                        const success = applyPalette(rawValue);
-                        if (!success) {
-                            return { toolCallId: id, result: `Error: palette "${rawValue}" not found. Use action "list" category "palettes" to see available palettes.`, isError: true };
-                        }
-                        result = `Palette changed to "${rawValue}"`;
-                        break;
-                    }
-                    if (key === 'activeCompanion') {
-                        if (!listCompanions().some(c => c.name === rawValue)) {
-                            return { toolCallId: id, result: `Error: companion "${rawValue}" not found. Use action "list" category "companions" to see available companions.`, isError: true };
-                        }
-                        config.set('activeCompanion', rawValue);
-                        result = `Companion changed to "${rawValue}"`;
-                        break;
-                    }
                     // Generic config set
                     config.set(key, parsedValue);
                     result = `Set ${key} = ${JSON.stringify(parsedValue)}`;
@@ -660,7 +581,10 @@ export async function executeTool(toolCall, cwd, timeout = 60000, onOutput) {
                     return { toolCallId: id, result: 'Error: new_string must be a string', isError: true };
                 }
                 const replaceAll = args.replace_all === true;
-                result = await editFile(args.path, args.old_string, args.new_string, replaceAll, cwd);
+                // anchor_hash is optional and accepted from any caller; it is only
+                // advertised in the simplified local schema (feature 4).
+                const anchorHash = typeof args.anchor_hash === 'string' ? args.anchor_hash : undefined;
+                result = await editFile(args.path, args.old_string, args.new_string, replaceAll, cwd, anchorHash, options?.fs);
                 break;
             }
             case 'glob': {
@@ -708,7 +632,7 @@ export async function executeTool(toolCall, cwd, timeout = 60000, onOutput) {
  * SECURITY NOTE (#132): This denylist is ADVISORY / defense-in-depth only. It is
  * fundamentally unwinnable to perfectly screen an arbitrary `bash -c` string, so
  * treat this as a best-effort tripwire, NOT a security boundary. The real control
- * is the native sandbox (see src/sandbox-native.ts); when no sandbox is available
+ * is the native sandbox (see src/sandbox/native.ts); when no sandbox is available
  * the shell tool fails closed (see shouldUseNativeSandbox / executeShell).
  */
 const BLOCKED_COMMANDS = [
@@ -852,29 +776,11 @@ function validateShellPaths(command, cwd) {
     for (const p of extractedPaths) {
         const allowed = isInScope(p, cwd);
         if (!allowed) {
-            return 'Shell command blocked: "' + p + '" is outside allowed scope. Use /add-dir to expand scope.';
+            return 'Shell command blocked: "' + p + '" is outside allowed scope. Use /scope add to expand scope.';
         }
     }
     return null;
 }
-/**
- * Determine whether to use native sandboxing for shell commands based on config.
- *
- * sandboxMode values:
- *  - 'auto':   use native sandbox when available, otherwise run unsandboxed
- *  - 'native': require native sandbox (fail if unavailable)
- *  - 'docker': defer to Docker sandbox (handled elsewhere)
- *  - 'off':    no sandboxing
- */
-function shouldUseNativeSandbox() {
-    const mode = config.get('sandboxMode') || 'auto';
-    if (mode === 'off' || mode === 'docker')
-        return 'skip';
-    if (mode === 'native')
-        return 'require';
-    // 'auto': use if available
-    return nativeSandbox.isNativeSandboxAvailable() ? 'use' : 'skip';
-}
 /**
  * Execute a shell command
  */
@@ -890,8 +796,8 @@ async function executeShell(command, cwd, timeout, onOutput) {
         return `Error: ${scopeError}`;
     }
     // Check if native sandbox should be used
-    const sandboxDecision = shouldUseNativeSandbox();
-    if (sandboxDecision === 'require' && !nativeSandbox.isNativeSandboxAvailable()) {
+    const sandboxDecision = sandbox.shouldUseNativeSandbox();
+    if (sandboxDecision === 'require' && !sandbox.isNativeSandboxAvailable()) {
         return 'Error: Native sandbox required (sandboxMode=native) but not available on this platform.';
     }
     // 'auto' is best-effort: when no native backend exists (e.g. Linux/Windows
@@ -903,7 +809,7 @@ async function executeShell(command, cwd, timeout, onOutput) {
     if (sandboxDecision === 'use' || sandboxDecision === 'require') {
         // Network is OFF by default; opt in via CALLIOPE_SHELL_NETWORK=1 (#133).
         const networkEnabled = process.env.CALLIOPE_SHELL_NETWORK === '1';
-        const result = await nativeSandbox.executeInNativeSandbox(command, cwd, {
+        const result = await sandbox.executeInNativeSandbox(command, cwd, {
             timeout,
             networkEnabled,
         });
@@ -974,27 +880,41 @@ async function executeShell(command, cwd, timeout, onOutput) {
 }
 /**
  * Read a file
+ *
+ * When `appendAnchorHash` is set (local backends only), the current content hash
+ * is appended so the model can echo it back on a subsequent anchored edit_file
+ * (stale-view protection, feature 4).
  */
-async function readFile(filePath, cwd) {
+async function readFile(filePath, cwd, appendAnchorHash = false, fsDelegate) {
     const absPath = validatePath(filePath, cwd);
-    if (!fs.existsSync(absPath)) {
-        throw new Error(`File not found: ${absPath}`);
+    let content;
+    if (fsDelegate?.readTextFile) {
+        // Client-side fs (e.g. an ACP editor buffer that may hold unsaved changes).
+        // The client owns existence/size; a missing file surfaces as a thrown error
+        // that executeTool turns into a normal tool error.
+        content = await fsDelegate.readTextFile(absPath);
     }
-    const stats = fs.statSync(absPath);
-    if (stats.isDirectory()) {
-        throw new Error(`Path is a directory: ${absPath}`);
-    }
-    // Check file size (limit to 1MB)
-    if (stats.size > 1024 * 1024) {
-        throw new Error(`File too large (${Math.round(stats.size / 1024)}KB). Max 1MB.`);
+    else {
+        if (!fs.existsSync(absPath)) {
+            throw new Error(`File not found: ${absPath}`);
+        }
+        const stats = fs.statSync(absPath);
+        if (stats.isDirectory()) {
+            throw new Error(`Path is a directory: ${absPath}`);
+        }
+        // Check file size (limit to 1MB)
+        if (stats.size > 1024 * 1024) {
+            throw new Error(`File too large (${Math.round(stats.size / 1024)}KB). Max 1MB.`);
+        }
+        content = fs.readFileSync(absPath, 'utf-8');
     }
-    const content = fs.readFileSync(absPath, 'utf-8');
     // Inline file preview header (#119). The header carries the line count;
     // the full content follows once — no preview/footer, those duplicated the
     // first 20 lines on every read and cost ~20% extra tokens on short files.
     const totalLines = content.split('\n').length;
     const header = `[file: ${filePath} \u2014 ${totalLines} line${totalLines !== 1 ? 's' : ''}]\n${'─'.repeat(40)}`;
-    return `${header}\n${content}`;
+    const footer = appendAnchorHash ? anchorHashFooter(computeAnchorHash(content)) : '';
+    return `${header}\n${content}${footer}`;
 }
 /**
  * Generate a simple line-diff between old and new content
@@ -1009,9 +929,7 @@ function generateDiff(oldContent, newContent, maxLines = 20) {
     let deletions = 0;
     let changesShown = 0;
     let contextLines = 0;
-    // Use density setting: compact = 1 context line, normal = 3
-    const density = config.get('density') || 'normal';
-    const contextWindow = density === 'compact' ? 1 : 3;
+    const contextWindow = 3;
     // Compute line number width
     const lineNumWidth = Math.max(4, maxIdx.toString().length);
     const padNum = (n) => String(n).padStart(lineNumWidth, ' ');
@@ -1059,39 +977,46 @@ function generateDiff(oldContent, newContent, maxLines = 20) {
 /**
  * Write a file
  */
-async function writeFile(filePath, content, cwd) {
+async function writeFile(filePath, content, cwd, fsDelegate) {
     const absPath = validatePath(filePath, cwd);
-    // Create directory if needed
-    const dir = path.dirname(absPath);
-    if (!fs.existsSync(dir)) {
-        fs.mkdirSync(dir, { recursive: true });
-    }
     // Read existing content for diff
     let oldContent = '';
     let isNewFile = true;
-    if (fs.existsSync(absPath)) {
-        try {
-            const stats = fs.statSync(absPath);
-            if (!stats.isDirectory() && stats.size < 100 * 1024) {
-                oldContent = fs.readFileSync(absPath, 'utf-8');
+    if (fsDelegate?.writeTextFile) {
+        // Client-side fs: read the current buffer for the diff (absent = new file),
+        // then write through the client instead of touching local disk.
+        if (fsDelegate.readTextFile) {
+            try {
+                oldContent = await fsDelegate.readTextFile(absPath);
                 isNewFile = false;
             }
+            catch {
+                oldContent = '';
+                isNewFile = true;
+            }
         }
-        catch {
-            // Ignore errors reading old content
-        }
+        await fsDelegate.writeTextFile(absPath, content);
     }
-    // Auto-checkpoint before overwriting existing files (#20)
-    if (!isNewFile && oldContent) {
-        try {
-            const { createCheckpoint } = require('./checkpoint.js');
-            createCheckpoint(absPath, oldContent);
+    else {
+        // Create directory if needed
+        const dir = path.dirname(absPath);
+        if (!fs.existsSync(dir)) {
+            fs.mkdirSync(dir, { recursive: true });
         }
-        catch {
-            // Checkpoint module not available or failed - continue with write
+        if (fs.existsSync(absPath)) {
+            try {
+                const stats = fs.statSync(absPath);
+                if (!stats.isDirectory() && stats.size < 100 * 1024) {
+                    oldContent = fs.readFileSync(absPath, 'utf-8');
+                    isNewFile = false;
+                }
+            }
+            catch {
+                // Ignore errors reading old content
+            }
         }
+        fs.writeFileSync(absPath, content);
     }
-    fs.writeFileSync(absPath, content);
     // Generate diff output (#119)
     const DIFF_CAP = 50;
     const header = `[wrote: ${filePath}]\n${'─'.repeat(Math.min(filePath.length + 9, 60))}`;
@@ -1193,12 +1118,10 @@ function listFilesRecursive(dir, prefix, depth) {
  *  - 'off':    no sandboxing
  */
 async function executeCode(language, code, cwd, timeout) {
-    const mode = config.get('sandboxMode') || 'auto';
     const sandboxLang = language === 'node' ? 'node' : language;
-    // Determine execution strategy
-    const useDocker = mode === 'docker' || (mode === 'auto' && sandbox.isDockerAvailable());
-    const useNative = mode === 'native' || (mode === 'auto' && !sandbox.isDockerAvailable() && nativeSandbox.isNativeSandboxAvailable());
-    if (useDocker) {
+    // Determine execution strategy from sandboxMode config
+    const strategy = sandbox.selectCodeSandbox();
+    if (strategy === 'docker') {
         // Docker sandbox path (existing behaviour)
         const result = await sandbox.execute(sandboxLang, code, {
             timeout,
@@ -1217,7 +1140,7 @@ async function executeCode(language, code, cwd, timeout) {
         output += `Duration: ${result.duration}ms`;
         return output;
     }
-    if (useNative) {
+    if (strategy === 'native') {
         // Native OS sandbox path — write code to temp file and execute
         const fs = await import('fs');
         const os = await import('os');
@@ -1230,7 +1153,7 @@ async function executeCode(language, code, cwd, timeout) {
             : language === 'node' ? `node "${codePath}"`
                 : `bash "${codePath}"`;
         const startTime = Date.now();
-        const result = await nativeSandbox.executeInNativeSandbox(cmd, cwd, {
+        const result = await sandbox.executeInNativeSandbox(cmd, cwd, {
             timeout,
             readOnlyPaths: [tempDir],
         });
@@ -1425,16 +1348,42 @@ ${content}
  * Edit a file by replacing an exact string (in-place edit).
  * Supports single-occurrence enforcement or replace_all mode.
  */
-async function editFile(filePath, oldString, newString, replaceAll, cwd) {
+async function editFile(filePath, oldString, newString, replaceAll, cwd, anchorHash, fsDelegate) {
     const absPath = validatePath(filePath, cwd);
-    if (!fs.existsSync(absPath)) {
-        throw new Error(`File not found: ${absPath}`);
+    let content;
+    if (fsDelegate?.readTextFile) {
+        // Client-side fs: edit against the editor's current buffer, not disk.
+        content = await fsDelegate.readTextFile(absPath);
     }
-    const stats = fs.statSync(absPath);
-    if (stats.isDirectory()) {
-        throw new Error(`Path is a directory: ${absPath}`);
+    else {
+        if (!fs.existsSync(absPath)) {
+            throw new Error(`File not found: ${absPath}`);
+        }
+        const stats = fs.statSync(absPath);
+        if (stats.isDirectory()) {
+            throw new Error(`Path is a directory: ${absPath}`);
+        }
+        content = fs.readFileSync(absPath, 'utf-8');
+    }
+    // Persist the edited content through the delegate when available, else disk.
+    const writeUpdated = async (updated) => {
+        if (fsDelegate?.writeTextFile) {
+            await fsDelegate.writeTextFile(absPath, updated);
+        }
+        else {
+            fs.writeFileSync(absPath, updated);
+        }
+    };
+    // Stale-view protection (feature 4): if the caller supplied an anchor_hash, it
+    // must match the file's current content. A mismatch means the model is acting
+    // on an out-of-date view — fail loudly and tell it to re-read. Absent hash =
+    // no check (inert for cloud providers, which never see the param).
+    if (anchorHash !== undefined) {
+        const currentHash = computeAnchorHash(content);
+        if (anchorHash !== currentHash) {
+            throw new Error(`anchor_hash mismatch: file has changed since you read it (you sent "${anchorHash}", current is "${currentHash}"). Re-read ${filePath} before editing.`);
+        }
     }
-    const content = fs.readFileSync(absPath, 'utf-8');
     // Helper to build a compact edit diff from old_string/new_string (#119)
     const buildEditDiff = (oldStr, newStr, fPath, count) => {
         const DIFF_CAP = 50;
@@ -1476,7 +1425,7 @@ async function editFile(filePath, oldString, newString, replaceAll, cwd) {
         if (count === 0) {
             throw new Error(`old_string not found in file: ${absPath}`);
         }
-        fs.writeFileSync(absPath, updated);
+        await writeUpdated(updated);
         return buildEditDiff(oldString, newString, filePath, count);
     }
     // Count occurrences
@@ -1488,7 +1437,7 @@ async function editFile(filePath, oldString, newString, replaceAll, cwd) {
         throw new Error(`old_string matches ${occurrences} occurrences — use replace_all: true or make it more specific`);
     }
     const updated = content.replace(oldString, newString);
-    fs.writeFileSync(absPath, updated);
+    await writeUpdated(updated);
     return buildEditDiff(oldString, newString, filePath, 1);
 }
 /**