WriteFile writes a complete UTF-8 text file. It creates workspace parent directories as needed, writes to a same-directory owner-only temporary file, syncs, and atomically renames into place. A final-component symlink is replaced as a node instead of followed to its target.

Contract

The JSON shape is {"path":"src/main.go","content":"package main\n"}. Preparation canonicalizes the target and emits one direct filesystem.write requirement whose scope and match are the same canonical path. The requirement includes an exact-path candidate for the contained target. WriteTarget returns that same canonical path for runner scheduling.

For a contained existing file, the tool requires a complete prior observation from ReadFile and compares its SHA-256 hash before replacing. A new absent file can be created without a prior read, but atomic no-replace publication reports FileCreateConflictError if another writer wins. A changed, missing, symlinked, or irregular target fails without clobbering it.

The session coordinator supplies the shared mutation and canonical path permits. A lease health failure blocks the commit. WithHostWrites enables a literal absolute target outside the workspace, subject to the consumer’s write authority. Host writes do not consult or update the observation map and are not covered by workspace checkpoint or undo. A missing host parent directory is not created automatically. Relative ../ remains invalid.

// Read first when overwriting an existing contained file. The observation
// lets WriteFile perform its compare-and-swap check.
writer := writefile.New(root, observations)
request, artifact, err := writer.PrepareCall(ctx, executionID,
	`{"path":"src/main.go","content":"package main\n"}`)
if err != nil {
	panic(err)
}
prepared := loop.WithPreparedCall(ctx, tool.PreparedCall{
	ExecutionID: executionID,
	Request: request,
	Artifact: artifact,
})
result, err := writer.InvokableRun(prepared, `{}`)

See ReadFile for observations, EditFile for exact replacements, and Safety, Permissions, and Gates for permits and gate decisions.

WriteFile

Contract

Source

Proof