write_file

Overwrite the contents of an existing file. To prevent silent stomping of concurrent edits, write_file requires the caller to supply expectedSha256 — the sha256 the agent received from its most recent read_file (or any earlier successful write/edit) of the same path. If the on-disk file no longer matches, the call returns stale_file and the agent must re-read before retrying.

import { createAgent } from "@comma-agents/core";

const agent = createAgent({
  name: "editor",
  model: "openai/gpt-4o",
  tools: ["read_file", "write_file"],
});

WriteFileToolConfig

Optional configuration for the factory.

WriteFileData

The structured payload returned on success.

Stale-file protocol

expectedSha256 must equal the sha256 of the bytes currently on disk. The simplest workflow is:

const read = await tool.read_file({ path: "src/server.ts" });
const next = transform(read.data.content);

await tool.write_file({
  path: "src/server.ts",
  content: next,
  expectedSha256: read.data.sha256,
});

If something else has changed the file in between, write_file returns stale_file with the message "Re-read the file to obtain the current sha256 and re-apply your edit." See the Stale file protocol page for the full lifecycle.

Newline and BOM preservation

When the on-disk file uses CRLF line endings or starts with a UTF-8 BOM, write_file preserves both. The agent supplies LF-only content; the tool re-applies the original newline style and prepends the BOM if one was present. This keeps writes safe for repositories that mix line endings.

Errors

Related

• read_file — produces the sha256 you pass back here.
• edit_file — change only a region of the file instead of rewriting it.
• apply_patch — apply a multi-file diff atomically.