For agents, on top of README.md, which they read first.

Notes for agents

The read-only filter errs one way only. read_only.rs must never accept a command that can change something; rejecting one merely sends it to Jev. It does not parse shell: any character that could chain, redirect, substitute, glob or quote disqualifies the command. Do not "improve" it into a parser.

A program joins the list only if no argument can make it write or run something. That is why rg excludes --pre, tree -o, date -s/--set, and git any option before the subcommand (-c, -C, --exec-path). Check the program's whole option list before adding it, and add the dangerous forms to anything_that_could_write_is_not in the same change.

Never let an unreadable event route anywhere but ignore. handle_json answers a parse failure with ignore; a newer Claude Code's unknown event must not reach the daemon, which would refuse it.

The abi exports are a contract with plugin/hooks/bridge.ts and plugin/hooks/jevhooks.d.ts. Renaming or re-typing alloc, dealloc, handle or out_len changes all three.