shell-hooks/README.md

shell-hooks

Shell side of the terminal collector (spec §1.4). Live as of v0.2. These snippets belong in the dotfiles repo and are sourced by the user's .zshrc; they are kept here so the privacy contract lives next to the code it constrains (and so the differential secret-typing test can drive the real file).

The one rule

Aggregate-only. The hooks emit counts, durations, and exit codes. They never read, store, or transmit the content of a command or a keystroke.

• No input tap, no CGEventTap, no PTY sniffing.
• Never reference the zle line buffer or capture argv.
• What leaves the shell is a number, flushed on precmd.

v0.2 ships the zle keypress counter: a widget wraps self-insert, does (( _SIGNALD_KEYS++ )), then calls the built-in insert. It receives the key in the editor and discards it — the character is never assigned to a variable that outlives the widget and never leaves the shell. On each precmd the hook appends one count record — <epoch_ms> <keys> <session_seconds> <session_id>, numbers only — to $SIGNALD_SPOOL. The session id is the shell's pid, so several shells can share one spool and signald still derives each shell's rate separately. signald consumes the spool on every tick (renames it aside, reads it, deletes it), so it never grows.

This contract is enforced by the forbidden-symbol scan and the differential secret-typing test in crates/signal-schema/tests/privacy_invariant.rs (plus the full-pipeline gate in crates/signald/tests/), which drive this file with a planted secret and fail the build if it — in any encoding — reaches the spool, the wire, or SQLite.

Files

• signald-hooks.zsh — the zle keystroke counter + precmd count flush (aggregate-only).