File-system boundary

File operations are root-bounded, batch-oriented, and explicit about state.

file_hash

Streams up to 50 complete files into SHA-256 without returning their contents. Use it immediately before guarded changes, including AST-capable files.

file_read

Returns bounded slices from non-AST files only. Requests use zero-based, end-exclusive line ranges and are capped at 1,000 lines and 1 MiB. Responses include content, whole-file hash, size, truncation, and continuation metadata.

AST-capable files are rejected so callers use structural intelligence instead.

file_write

Creates new files atomically. Replacing an existing non-structurally-rewritable file requires a fresh expectedSha256 by default. Setting safety.require_hash = false makes the hash optional, but any supplied hash is still verified. Parent directories are created only after a guarded missing-parent result and a second root validation.

file_patch

The normal mutation API accepts a path-keyed batch. Each file receives one fresh hash and ordered operations under one deterministic lock:

• astRules for parseable, rewrite-supported source
• aiderBlocks for unsupported, unparseable, or inspection-only formats

Set preview: true to execute the formatted dry-run contract without committing. A fresh hash is required by default; safety.require_hash = false permits omission while retaining internal compare-and-swap protection and verification of any supplied hash. Formatting follows [formatting]: disabled mode preserves content, the first matching external route runs without a shell, and unmatched files use dprint.

file_rename

Renames multiple regular files in one root-bounded operation. Sources and destinations must share a configured root, destinations must not already exist, and every endpoint is locked for cooperating ast-mcp processes. Source hashes are required by default and optional only when safety.require_hash = false; supplied hashes are always enforced. Ordinary failures are rolled back when possible; the operation is no-replace but not crash-atomic, and external actors can race pathname checks.

file_chattr and file_delete

file_chattr applies bounded chmod and same-owner chown changes. file_delete requires a fresh hash by default, checks AST import references before deletion, and removes only newly empty ancestors inside the configured root. safety.require_hash = false permits omission for deletion, while supplied hashes remain enforced.