1@README.md
2
3## Notes for agents
4
5**`jevhooks.js` is generated: never edit it.** `just mod` writes it from
6`crates/jevhooks-mod` (cargo wasm32 build, `wasm-opt -Oz`, `wasm2js -O2`). Rebuild and
7commit it with any change to `jevhooks-mod` or `jevhooks-events`, or the plugin runs
8the old routing. Update `jevhooks.d.ts` by hand with any change to the crate's `abi`
9exports.
10
11**Memory is touched only in `bridge.ts`.** wasm2js swaps the module's `ArrayBuffer`
12whenever memory grows, so a `Uint8Array` kept across a call into Rust can point at
13storage the module has already replaced. Never export `memory`, or a view over it,
14from `bridge.ts`; take every view from `memory.buffer` at the moment it is used.
15
16**`$` calls live in top-level functions of `register.tsx`.** Mods check `$` calls from
17the module source; a call written in a hook, or in a top-level function given `$`,
18passes (`claude plugin validate` reports it "via" that function).
19
20**Hooks beneath this plugin still run.** `classic.PreToolUse` and `classic.Stop` call
21`next(e)` and combine: a deny beneath wins, then an ask, then this plugin's allow.
22Returning without `next` would skip the user's own settings hooks.
23
24**The mod reaches the daemon with `$.http.fetch` and `socketPath`, not `$.mcp.call`.**
25`$.mcp.call` is an ordinary tool call: it goes through `tool.call` and the permission
26check (refused outside bypass mode, whatever the type docs say), raises the plugin's
27own hooks, and measured about 60 ms against 4 to 13.
28
29**`socketPath` must stay the path `crates/jevhooks-daemon/src/paths.rs` computes**
30(`$XDG_STATE_HOME`, else `$HOME/.local/state`, then `jevhooks/daemon.sock`). Change
31one and the other, or every event finds no daemon and silently passes.
32
33**`observe` never rejects and is never awaited.** Nothing waits on it, so nothing
34could handle a rejection; keep the `try`/`catch` and the `void`.
35
36**Every failure to reach the daemon is `undefined`, which means pass.** Do not turn a
37missing socket into an error a hook throws.