pi-file-write-guard
Read-before-write, staleness and truncation-write-back protection for pi's built-in write/edit tools
Package details
Install pi-file-write-guard from npm and Pi will load the resources declared by the package manifest.
$ pi install npm:pi-file-write-guard- Package
pi-file-write-guard- Version
0.1.0- Published
- Nov 15, 2026
- Downloads
- 346/mo · 346/wk
- Author
- xuqianhui
- License
- MIT
- Types
- extension
- Size
- 40 KB
- Dependencies
- 0 dependencies · 1 peer
Pi manifest JSON
{
"extensions": [
"./extensions/write-guard.ts"
]
}Security note
Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.
README
pi-file-write-guard
Stop pi's agent from destroying a file it only half-saw.
pi's built-in read returns at most 2000 lines / 50KB per call (hardcoded, no setting), and its
write is a full overwrite with no checks in front of it. So the everyday pattern
read the whole file → splice something in → write the whole file back
silently deletes everything past line 2000 (or past the byte cap) — the tail was never in the model's hands. The same missing checks let an agent overwrite a file it never read, or write a copy back over someone else's later edit.
This extension adds that missing layer to the built-in write / edit tools, including calls nested
inside codemode scripts.
pi install npm:pi-file-write-guard
What it blocks
| code | condition | what it prevents |
|---|---|---|
truncated_write |
target exists, new content is shorter, and it is still line-aligned at the same positions with the file (an exact prefix, or ≤2% positional mismatches) | writing back a truncated read and silently dropping the tail |
not_read |
target exists and was not read in this session | clobbering a file nobody looked at (path typo, config rewritten from memory) |
modified_since_read |
file mtime moved past the watermark and its content hash differs (a pure touch is allowed) |
reverting an edit made by the user, another tool, or a previous turn |
truncated_write is shape-based and needs no session state, so it keeps working after resume,
/tree or compaction — which is why it is the first gate.
The block reason carries the recovery path and ends with a machine-matchable line (write-guard: <code>).
Escapes (no deadlocks, but a blind retry does not pass)
- Third attempt: the same
code + path + contentreleased on its third try. A blind identical retry once is still blocked. - Read what you drop: for
truncated_write, a positional read atoffset >= the last line the new content keepsreleases the first attempt — the model has actually seen the part it is deleting. - Read fixes it: one read clears
not_read; one re-read clearsmodified_since_read. - Replay on resume:
session_start,session_treeandsession_compactrebuild read state from the session branch (structured fields only; the watermark is the tool-result timestamp, which is the conservative direction).
Configuration
Global <agent-dir>/extensions/write-guard.json (default ~/.pi/agent/extensions/write-guard.json) is
deep-merged with project <cwd>/.pi/write-guard.json, project winning. A malformed file falls back to
the defaults.
{
"enabled": true,
"mode": "block",
"requireRead": true,
"checkStaleness": true,
"exempt": ["**/generated/**", "/var/log/**"]
}
| key | default | meaning |
|---|---|---|
enabled |
true |
turn the extension off entirely |
mode |
"block" |
"warn" only notifies (migration aid) |
requireRead |
true |
enforce read-before-write |
checkStaleness |
true |
enforce the read-watermark check |
exempt |
[] |
absolute-path globs; a relative pattern is anchored as **/<pattern> |
Globs are matched by this package (src/glob.ts), not by node:path.matchesGlob: that matcher refuses
to let ** cross a dot-prefixed segment, so **/generated/** silently fails under ~/.cache.
Limits
- Only the built-in
write/edittools.bashredirection, MCP file tools and other extensions' file tools do not pass through here. - Binary targets (containing NUL) and files over 32MB are skipped.
- Content hashes are recorded for
writeand for full reads up to 1MB;editrecords none, so a write right after aneditof the same file can only pass on an unchanged mtime. - Deliberate tradeoff: the truncation gate is content-shaped, so replacing a truncated read with entirely different content is allowed (a read-state gate would block it as a false positive), and an append on top of a truncated view is not flagged.
Development
npm install
npm run check # tsc --noEmit + vitest
npm run pack:check
Layout: extensions/write-guard.ts wires pi's events; src/ is pure decision code
(config, glob, shape, readstate, replay); test/ covers each rule plus end-to-end handler
behaviour.
Release: npm publish (manual, from a tagged commit). See CHANGELOG.md.
License
MIT