gemini-cli - 💡(How to fix) Fix File Integrity Protection: Add Concurrency Lock and Hash-based Safe-Write to Mutating Tools [2 comments, 2 participants]

What would you like to be added?

Implement an optimistic concurrency control mechanism to prevent unintended data loss in multi-agent and user-interactive workflows. Specifically:

• Integrity Tokens: Extend read_file to return a file content hash/version token alongside the file content
• Concurrency Validation: Add an optional integrity_token parameter to write_file and replace tools that validates the file hasn't been modified since it was read
• Detect Concurrent Modifications: Before mutation, verify that the on-disk file state matches the version the agent last read
• Fail-Safe Behavior: Force tools to return a structured "Concurrent Modification Detected" error if the file has changed externally since the agent's last read

Why is this needed?

Currently, the agent relies on cached file content from earlier conversation turns to make edits, making it vulnerable to:

1. Stale Data Overwrites: The agent reads a file in Turn 1, then writes it in Turn 5+ based on the cached Turn 1 content, unaware that the file has been modified on disk in the meantime

2. Multi-Agent Race Conditions: When multiple agents operate on the same files concurrently, there's no mechanism to detect that another agent modified the target file between read and write operations

3. Silent User Edit Loss: If a user manually edits a file while the agent is planning/executing, the agent's write operation can silently revert those manual changes

4. No Read-Verify-Write Semantics: Unlike optimistic locking in databases (e.g., SQL's WHERE version = X), the agent has no way to verify the file's state before committing changes

Current Mitigation (Partial)

The edit tool includes a hash-based detection (lines 523-533 in edit.ts) that checks if the file has been modified on disk during LLM self-correction attempts:

const initialContentHash = hashContent(currentContent);
const onDiskContent = await this.config.getFileSystemService().readTextFile(this.resolvedPath);
const onDiskContentHash = hashContent(onDiskContent.replace(/\r\n/g, '\n'));

if (initialContentHash !== onDiskContentHash) {
  // Use latest content for correction attempt
}

However, this check:

• ✅ Occurs only during self-correction (when edit fails and retries)
• ❌ Does not prevent the edit from being applied if hashes mismatch
• ❌ Is unavailable for write_file and replace tools
• ❌ Doesn't protect the primary execution path (confirmation → execute)

Proposed Solution

Extend the integrity checking to all mutating tools with a formal token-based approach:

// read_file returns:
{ 
  content: "file content...",
  content_hash: "sha256:abc123..."  // New field
}

// write_file includes optional token:
{
  file_path: "app.js",
  content: "new content",
  expected_content_hash: "sha256:abc123"  // Verification before write
}

// If hash mismatches:
{
  error: {
    type: "CONCURRENT_MODIFICATION",
    message: "File was modified by another process since last read",
    current_hash: "sha256:def456",
    expected_hash: "sha256:abc123"
  }
}

Scope

Apply to all file mutation tools:

• write_file
• replace (edit tool)
• Both interactive and non-interactive modes

Related

• Partially addressed in edit.ts (lines 519-534) via self-correction hash checking
• Complements existing approval controls (policy engine, user confirmation)
• Does not replace approval mechanisms—works alongside them