`'FileEditTool' edit file`

FileEditTool is the core tool in Claude Code used for precise file modifications. Its design purpose goes beyond simple "string replacement"; rather, it aims to build a secure, controlled editing model. Through mandatory pre-validation, Patch-driven writing, and rigorous conflict interception mechanisms, it ensures that AI's incremental modifications to existing files remain strictly under engineering control.

The value of FileEditTool is built upon heavy foundational dependencies. Examining the import logic in the source code tools/FileEditTool/FileEditTool.ts clearly reveals its design boundaries:

import { countLinesChanged } from '../../utils/diff.js'
import { fetchSingleFileGitDiff } from '../../utils/gitDiff.js'
import { checkWritePermissionForTool } from '../../utils/permissions/filesystem.js'
import { readFileSyncWithMetadata } from '../../utils/fileRead.js'
import { getPatchForEdit } from './utils.js'

These imports reveal a key fact: it is not a lightweight replacement tool, but a dispatch center that simultaneously coordinates Diff computation, Git version perspective, file system permissions, metadata verification, and Patch generation.

The tool's own definition similarly reflects Anthropic's strict control over behavioral boundaries:

export const FileEditTool = buildTool({
  name: FILE_EDIT_TOOL_NAME,
  searchHint: 'modify file contents in place',
  strict: true, // Core constraint to prevent the model from glossing over parameters
  ...
})

strict: true means Anthropic imposes strict constraints on the tool's input structure, ensuring the language model cannot casually shortcut parameter validation. Its internal editing pipeline achieves high synergy as follows:

The core design philosophy of FileEditTool lies in strictly forbidding blind edits. Within the validation pipeline, the tool rigorously checks whether the target file has been explicitly "read" by the current session. This directly eliminates three classic engineering pain points:

• Prevents the model from modifying based on stale content.
• Avoids catastrophic conflicts caused by users and AI operating on the same file simultaneously.
• Forces the model to fully comprehend the current code snapshot before rewriting.

The adjacent FileWriteTool leans toward whole-file overwrites, whereas FileEditTool explicitly focuses on in-place partial replacement scenarios. Within the write pipeline, the system tightly monitors the file's real-time state:

FILE_UNEXPECTEDLY_MODIFIED_ERROR

The system will directly block writes when the following occur:

1. Claude reads the file's initial snapshot.
2. External processes intervene (e.g., auto-formatting upon IDE save, automatic Linter fixes, or a developer manually overwriting).
3. Claude attempts to initiate a secondary edit based on an outdated old snapshot.

Such mechanisms are extremely common and critical in real-world projects. A typical operational workflow is as follows:

Many mistakenly believe FileEditTool is merely a "safer sed", which greatly underestimates its role in the engineering ecosystem. Understanding this tool requires clarifying the following core differences and design points:

The source code explicitly calls upon underlying patch and equivalence verification utilities:

import { getPatchForEdit } from './utils.js'
import { areFileEditsInputsEquivalent, findActualString } from './utils.js'

This defines the working mode of FileEditTool:

• Precisely locate the old code snippet.
• Generate local difference patches.
• Preserve the file's original topology.

It does not, and absolutely will not, execute the blunt operation of > regenerating the entire file before overwriting. This is fundamentally why Edit is always more sensible than Write when modifying a small piece of logic within an existing file.

• ❌ Misconception 1: Edit is fundamentally no different from Bash sed.
  ✅ Reality: Edit directly integrates with the permission system, file read-state caching, and real-time Diff tracking.
• ❌ Misconception 2: Edit is merely a text tool and doesn't involve engineering state.
  ✅ Reality: It deeply interlinks with Git Diff, LSP diagnostics, file history, and even skill directory activation.
• ❌ Misconception 3: Edit is just a "safer replacement".
  ✅ Reality: It is the controlled incremental editor of Claude Code.

Its synergy with other building blocks in the workflow is as follows:

• Controlled Model: FileEditTool is not a simple text replacer, but the controlled incremental editor of Claude Code.
• Strictly Forbids Blind Edits: By mandating file cache state validation and real-time conflict detection (FILE_UNEXPECTEDLY_MODIFIED_ERROR), it completely eliminates the risk of AI modifying outdated or other developers' code.
• Patch Excels Over Overwrite: By driving modifications via local difference patches, it maximally preserves the original engineering structure and contextual compatibility.
• Industrial-Grade Reliability: Its capabilities are deeply integrated into the permission system, Git Diff, and LSP ecosystem, offering far greater traceability and security for production environments than blindly running Bash sed commands.