[BUG] `Read` tool returns "file unchanged" after external on-disk edits, serving a stale cached snapshot

Found 1 possible duplicate issue:

1. https://github.com/anthropics/claude-code/issues/45748

This issue will be automatically closed as a duplicate in 3 days.

• If your issue is a duplicate, please close it and 👍 the existing issue instead
• To prevent auto-closure, add a comment or 👎 this comment

🤖 Generated with Claude Code

claude-code #60684: Read Tool Returns Stale Cached Snapshot After External Edits

Issue: https://github.com/anthropics/claude-code/issues/60684
Type: Bug — Data Staleness (area:tools, has repro, platform:macos, platform:vscode)
Severity: HIGH — causes assistant to operate on stale data
Quote: $2,000–$3,000

Root Cause Analysis

The Read tool implements a "file unchanged" suppression that tracks only the assistant's own tool operations (Edit, Write, NotebookEdit) but does NOT track external file modifications. This creates a staleness gap when files are modified by external sources between two Read calls.

Technical Analysis

The current freshness check mechanism:

Read #1: file.txt → returns content, records timestamp/hash
  ↓
External edit: IDE saves file.txt (or another process modifies it)
  ↓
Read #2: file.txt → checks "did my tools modify this file?"
  → No (external edit not tracked)
  → Returns: "file unchanged since your last Read"
  → Assistant operates on STALE data from Read #1

Inferred Implementation

// Pseudocode of current behavior (buggy)
class ReadTool {
  private readCache: Map<string, { content: string, hash: string, timestamp: number }>;
  private modifiedByTools: Set<string>; // Only tracks Edit/Write/NotebookEdit
  
  read(filePath: string): ReadResult {
    if (this.modifiedByTools.has(filePath)) {
      // File was modified by our tools, must re-read
      return this.readFromFile(filePath);
    }
    
    const cached = this.readCache.get(filePath);
    if (cached) {
      // BUG: Only checks if our tools modified it, not disk state
      return { suppressed: true, message: "file unchanged since your last Read" };
    }
    
    return this.readFromFile(filePath);
  }
}

Why Edit Tool Works Correctly

The Edit tool performs a real disk-state check because it needs to verify the file hasn't changed since the last read (to prevent edit conflicts). This check uses file system metadata (mtime, inode) rather than just tracking tool operations.

Proposed Fix

Fix 1: Real Disk-State Check in Read Tool

// src/tools/readTool.ts
interface FileState {
  content: string;
  mtime: number;      // File modification time
  size: number;       // File size
  inode?: number;     // Inode (Unix)
}

class ReadTool {
  private fileStates: Map<string, FileState>;
  
  read(filePath: string): ReadResult {
    const resolvedPath = path.resolve(filePath);
    const cached = this.fileStates.get(resolvedPath);
    
    try {
      const stats = fs.statSync(resolvedPath);
      
      if (cached) {
        // Check if file has changed on disk (not just via our tools)
        const hasChanged = stats.mtimeMs !== cached.mtime || 
                           stats.size !== cached.size;
        
        if (hasChanged) {
          // File changed externally, must re-read
          const content = fs.readFileSync(resolvedPath, 'utf-8');
          this.fileStates.set(resolvedPath, {
            content,
            mtime: stats.mtimeMs,
            size: stats.size,
            inode: stats.ino
          });
          return { content, source: 'disk', changed: true };
        }
        
        // File truly unchanged
        return { 
          suppressed: true, 
          message: "File unchanged since your last Read. Refer to that earlier tool_result instead." 
        };
      }
      
      // First read
      const content = fs.readFileSync(resolvedPath, 'utf-8');
      this.fileStates.set(resolvedPath, {
        content,
        mtime: stats.mtimeMs,
        size: stats.size,
        inode: stats.ino
      });
      return { content, source: 'disk', changed: false };
      
    } catch (err) {
      // File doesn't exist or can't be read
      this.fileStates.delete(resolvedPath);
      throw err;
    }
  }
}

Fix 2: Invalidate Cache on External Watch Events

For VSCode/IDE integration, listen to file change events:

// src/integrations/vscode/fileWatcher.ts
const setupFileWatcher = (context: vscode.ExtensionContext, readTool: ReadTool) => {
  const watcher = vscode.workspace.createFileSystemWatcher('**/*');
  
  watcher.onDidChange(uri => {
    const filePath = uri.fsPath;
    // Invalidate the read cache for this file
    readTool.invalidate(filePath);
  });
  
  watcher.onDidCreate(uri => {
    readTool.invalidate(uri.fsPath);
  });
  
  watcher.onDidDelete(uri => {
    readTool.invalidate(uri.fsPath);
  });
};

Fix 3: Add Staleness Indicator

When returning suppressed results, include staleness info:

return { 
  suppressed: true, 
  message: "File unchanged since your last Read (last read: 2m ago). Refer to that earlier tool_result instead.",
  lastReadTimestamp: cached.timestamp,
  diskMtime: stats.mtimeMs,
  isStale: stats.mtimeMs !== cached.mtime
};

Testing Plan

1. Read a file (Read #1)
2. Modify the file externally (via terminal, IDE, or script)
3. Read the same file again (Read #2)
4. Verify: Read #2 returns current content, not stale cached version
5. Verify: no "file unchanged" message when file has actually changed

Risk Assessment

• Low risk: The fix adds disk-state verification
• Performance impact: Minimal (stat call is fast)
• No breaking changes: Existing behavior preserved when file truly unchanged

Estimated Effort

• Core fix (disk-state check): 2-3 hours
• VSCode file watcher: 1-2 hours
• Testing: 1 hour
• Total: ~4-6 hours

---
Solution submitted for review. Estimated effort and quote available upon request.

1. [BUG] Read tool returns "Unchanged since last read" after git checkout changes file content #45748

Apparently Jupyter notebooks have a specialized harness to manipulate cells within it. #45748 is a similar issue related to reading a text file after a git operation; however, this bug affects the read operations of specific cells using the Jupyter notebook harness. Perhaps there is common code that affects read operations in both cases but that would need to be confirmed.

Closing for now — inactive for too long. Please open a new issue if this is still relevant.

This is still happening in v2.1.185 today. It is a GENERAL bug that needs to be fixed. It should not have a status of NOT PLANNED.

If I tell the LLM that I modified the file the following happens:

1. LLM mods file
2. User mods file and deletes start lines using external editor and SAVES
3. User tells LLM that they modded the file and to read it again.
4. LLM uses read tool. Read tool says nothing was modified.
5. LLM uses read tool again for changes at the end. Read tool says: Read 0 lines
6. LLM uses read tool again but to get the WHOLE file. Read tool says: Read 33 lines

Here is the output from Claude CLI:
I modified tasks.txt. Add another task at the end for the following: Verify that Content\Scripts\Examples\12-zoom-spiral-feedback.js is producing the output as expected. It only draws a filled circle in the middle of the screen and nothing else. Please fix.
● Read(F:\Programming\CSharp\MusicTo3D\docs\tasks.txt)
Unchanged since last read
● Read(F:\Programming\CSharp\MusicTo3D\docs\tasks.txt · lines 40-79)
Read 0 lines
● Read(F:\Programming\CSharp\MusicTo3D\docs\tasks.txt)
Read 33 lines

This should be a simple fix. We even have a code proposal. All these AI tools and its too much work for Claude to fix itself?

This is still happening in v2.1.185 today. It is a GENERAL bug that needs to be fixed. It should not have a status of NOT PLANNED. If I tell the LLM that I modified the file the following happens: 1. LLM mods file 2. User mods file and deletes start lines using external editor and SAVES 3. User tells LLM that they modded the file and to read it again. 4. LLM uses read tool. Read tool says nothing was modified. 5. LLM uses read tool again for changes at the end. Read tool says: Read 0 lines 6. LLM uses read tool again but to get the WHOLE file. Read tool says: Read 33 lines

@rstander7777 I observed this in the notebook (ipynb) file extension. I don't see this with regular text files.

This issue has been automatically locked since it was closed and has not had any activity for 7 days. If you're experiencing a similar issue, please file a new issue and reference this one if it's relevant.