Module formal_ai_files 

Structured read, edit and write tools of the experimental --use-formal-ai mode (issue #258). Mirrors js/src/lib/formal-ai-files.js.

The bash tool runs only programs without shell syntax, and its write programs (cp, mkdir, mv, rm, rmdir, touch) cannot change the text of a file. These three tools are the guarded replacement primitive instead of an interpreter: start itself reads and writes the one named workspace file, byte for byte, so comments, whitespace and unrelated content survive.

• read: the exact UTF-8 text of a regular file, bounded by START_FORMAL_AI_MAX_FILE_BYTES; it observes the file for later changes.
• edit: replaces one literal occurrence of old_string (or every one with replace_all) in a file read before, atomically, then reads it back.
• write: replaces an observed file, or creates one in an observed directory, atomically, then reads it back.

Paths follow the bash tool’s workspace policy (no absolute, escaping or symlinked-out paths), edit and write need START_FORMAL_AI_EFFECTS= workspace-write and an earlier observation of the target, and a file that changed since start read it is not overwritten.

Structs

FileArgs

Normalized arguments of a file tool call.

FileDecision

Whether a file tool call may run (the effect policy of #255).

FileReceipt

What an approved file call did.

Constants

FILE_TOOL_NAMES

Functions

describe_file_call

One-line rendering of a file call for notes and evidence.

evaluate_file_call

Decide whether a file tool call may run.

file_tool

The JSON schema of one file tool, as offered to Formal AI.

normalize_file_args

Normalize the JSON arguments of a file tool call, or say what is wrong.

run_file_call

Run an approved file tool call. context.contents maps paths to the SHA-256 start last saw, so a file changed since then is not overwritten.

sha256_hex

Hex SHA-256 of some bytes.