Per-session record of which paths an agent has read (or written), keyed by
the path string as the model passed it (lexical . components are normalized
away — see ReadLedger::normalize_key) and valued by a content hash of the
FULL file text plus whether the agent actually observed that full text. It
backs the read-before-edit / staleness guard on the
built-in edit_file/write_file tools: an edit (or an overwrite/append onto
an existing file) is licensed only once the session has observed that path’s
current content, so the model can’t blind-edit a file it never read or clobber
one that changed underneath it.
A default ledger plus lazily-created ledgers keyed by execution session.
Executors use this so a shared executor never lets one conversation’s read
authorize another conversation’s edit.
How a path stands relative to what an agent session has already observed —
the input to the read-before-edit / staleness guard (H1/F4-remainder,
audit 2026-07-06).
Like execute, but threads a per-session ReadLedger so the built-in
file tools enforce read-before-edit and content staleness: edit_file (and
write_file over an existing file) require the session to have read the path
first, and a successful read/write/edit records the current content so the
next edit is licensed. Opt-in — every in-repo executor call site uses this so
its agent gets the guard; the plain execute stays ungated for external
consumers of the stable API.