FileWriteTool: Write File

FileWriteTool primarily addresses the "full-file write" problem and applies to two typical scenarios:

• Creating a new file: Generating content from scratch to create a file at the specified path.
• Overwriting an existing file: Completely replacing the original data of the current target file with a single block of new content. If FileEditTool is more like a precise scalpel, then FileWriteTool is "re laying an entire block of material." In Claude Code's engineering design, these two tasks are explicitly split across different tools rather than all being handed off to the underlying shell for execution, reflecting a design philosophy of clear separation of duties.

The strict input schema is defined in tools/FileWriteTool/FileWriteTool.ts:

const inputSchema = z.strictObject({
  file_path: z.string().describe('The absolute path to the file to write'),
  content: z.string().describe('The content to write to the file'),
})

The interface is extremely streamlined, containing only two core fields: where to write (file_path) and what to write (content). This clearly conveys a design signal: Write's single responsibility is full-content writing, not handling complex partial replacement logic.

Unlike a simple "overwrite and be done with it," FileWriteTool returns detailed operational context through its outputSchema:

type: z.enum(['create', 'update'])
structuredPatch: z.array(hunkSchema())
originalFile: z.string().nullable()
gitDiff: gitDiffSchema().optional()

This means Write does not execute silently, but actively retains the following key audit information:

• Operation type: Whether it is a creation (create) or an update (update)
• Original file snapshot: The complete content before overwriting (originalFile)
• Structured patch: Fine-grained differences based on hunks (structuredPatch)
• Git-view changes: Diff data for version control tracking (gitDiff)

A single FileWriteTool call goes through a clear industrial-grade process:

1. The model decides to create a new file or perform a full-file overwrite
2. FileWriteTool receives the command
3. Path and permission checks are performed
4. Target file state is confirmed
5. Complete content is written
6. structuredPatch / gitDiff is generated
7. Results are injected back and the validation phase begins

Like Edit, Write does not execute blindly. The source code includes strict file freshness checks:

if (!readTimestamp || readTimestamp.isPartialView) {
  return {
    result: false,
    message: 'File has not been read yet. Read it first before writing to it.',
  }
}

This emphasizes Claude Code's core security principle: read before write. For existing files, the latest timestamp must be fetched first, effectively preventing the model from overwriting content recently modified by others (or background processes) based on stale cache.

Even for full-file writes, Claude Code refuses to treat it as a "black-box operation." The source code explicitly imports relevant utilities:

import { countLinesChanged, getPatchForDisplay } from '../../utils/diff.js'
import { fetchSingleFileGitDiff } from '../../utils/gitDiff.js'

After writing, the system automatically completes three tasks:

• Stat lines changed: Quantify the scale of changes
• Generate displayable patch: Provide human-readable diff comparisons
• Link Git change view: Seamlessly integrate with repository version control This design allows the frontend UI and downstream models to precisely understand the actual impact scope of this write operation.

Clearly defining boundaries significantly improves developer experience:

• FileEditTool (Edit): Suitable for local modifications to existing content (e.g., changing variable names, adjusting the logic of a single function).
• FileWriteTool (Write): Suitable for creating new files or rewriting entire blocks of existing content. If the model only wants to change a single function, Write will often feel too heavy; but for generating new configuration files, new component skeletons, or new documentation, Write is highly appropriate. Claude Code emphasizes clear division of duties rather than "the more versatile, the better."

Incorrect. It integrates with permission controls, file timing checks, diff computation, and the Git view system.

False. Claude Code advocates matching tools to the operation granularity. Use Edit for surgical local changes, and Write for holistic refactoring.

Not entirely. It can also update existing files, but its core use case is "replacing entire blocks," not making minor adjustments to fragmented content.

• FileWriteTool is dedicated to full creation and overwrite, achieving a clear role through minimal input, complementing the incremental edits of FileEditTool.
• Output Is Audit: not only returning operation results, but also attaching raw snapshots, structured patches and Git diff data, ensuring the write process is fully traceable.
• Golden Rule of Read-First: built-in timing validation blocks overwrite requests for files that haven't been read, fundamentally eliminating conflicts caused by outdated state.
• Full-Pipeline Engineering: refuses downgrade to raw shell commands, instead seamlessly integrating permission controls, diff calculation and Git tracking, maintaining Claude Code's overall architecture as "controlled and auditable".