1@README.md
2
3## Notes for agents
4
5**The read-only filter errs one way only.** `read_only.rs` must never accept a command
6that can change something; rejecting one merely sends it to Jev. It does not parse
7shell: any character that could chain, redirect, substitute, glob or quote disqualifies
8the command. Do not "improve" it into a parser.
9
10**A program joins the list only if no argument can make it write or run something.**
11That is why `rg` excludes `--pre`, `tree` `-o`, `date` `-s`/`--set`, and `git` any
12option before the subcommand (`-c`, `-C`, `--exec-path`). Check the program's whole
13option list before adding it, and add the dangerous forms to
14`anything_that_could_write_is_not` in the same change.
15
16**Never let an unreadable event route anywhere but `ignore`.** `handle_json` answers a
17parse failure with `ignore`; a newer Claude Code's unknown event must not reach the
18daemon, which would refuse it.
19
20**The `abi` exports are a contract with `plugin/hooks/bridge.ts` and
21`plugin/hooks/jevhooks.d.ts`.** Renaming or re-typing `alloc`, `dealloc`, `handle` or
22`out_len` changes all three.