"File has been unexpectedly modified" errors break Edit tool in VSCode extension

"File has been unexpectedly modified" errors break Edit tool in VSCode extension

Environment

• Claude Code Version: VSCode Extension
• OS: Windows 11
• Working Directory: Git repository with TypeScript/JavaScript files
• File Types Affected: .js, .ts files

Summary

The Edit tool consistently fails with "File has been unexpectedly modified. Read it again before attempting to write it." error, even when no manual edits are being made. The file appears to be modified by some VSCode background process between Claude's Read and Edit operations.

Steps to Reproduce

1. Open a JavaScript/TypeScript project in VSCode with Claude Code extension
2. Ask Claude to edit a file using the Edit tool
3. Observe that Edit tool fails with "File has been unexpectedly modified"
4. Note: This occurs even when user has not manually edited the file

Expected Behavior

The Edit tool should successfully apply changes to files that the user has not manually modified.

Actual Behavior

Edit tool fails repeatedly with "File has been unexpectedly modified" error, forcing fallback to complex workarounds using awk/sed commands which introduce their own issues (shell escaping problems, especially on Windows/Git Bash).

Example Workflow That Fails

1. Claude: Read file (lib/helpers.js) ✓
2. VSCode: Auto-format or linter runs in background
3. Claude: Edit file with changes ✗ "File has been unexpectedly modified"
4. Claude: Read file again ✓
5. VSCode: Auto-format runs again
6. Claude: Edit file ✗ "File has been unexpectedly modified"
... repeats indefinitely

Impact

This makes the Edit tool essentially unusable in the VSCode extension for active development workflows. Claude is forced to use:

• Complex awk/sed scripts (brittle, error-prone)
• Read entire file + Write back (loses granular editing benefits)
• Manual file operations via Bash (defeats purpose of Edit tool)

Suspected Root Cause

The Edit tool appears to:

1. Read file at time T1
2. Store file hash/timestamp
3. Perform edit operation at time T2
4. Verify file hasn't changed since T1

Between T1 and T2, some VSCode background process (possibly file watchers, formatters like Prettier, linters like ESLint, TypeScript compiler, or VSCode's own file sync) modifies the file, causing the verification to fail. This is speculation based on observed behavior - the actual cause has not been confirmed.

Suggested Fixes

Option 1: Add retry logic with brief delay

If "File has been unexpectedly modified" error occurs:

• Wait 100-500ms for file watchers to settle
• Re-read file automatically
• Retry edit operation
• Fail after 2-3 retries

Option 2: Detect common file watcher changes

• If file modification is only whitespace/formatting (same AST)
• Automatically re-read and apply edit to new version
• Only fail on substantive changes

Option 3: Lock file during edit

• Request file lock before Edit operation
• Prevent other processes from modifying during edit
• Release lock after edit completes

Additional Context

This issue significantly degrades the user experience in the VSCode extension compared to the CLI version. It's particularly frustrating because:

1. The file modifications are automatic (user didn't cause them)
2. The error message suggests user action ("Read it again") but doesn't help
3. The issues occurs both in CLI and VSCode extension.
4. Workarounds are significantly worse than the Edit tool

Related Issues

• Potentially related to file watching/auto-save behaviors in VSCode
• May affect all file types that have formatters/linters configured
• It started occuring after I upgraded from 2.0.27 to 2.0.31

---

Reported by: Akhil Kumar (akhil@apralabs.com)