Expand description
The opt-in decision log: one JSON object per classification, appended to
~/.local/state/safe-chains/log.jsonl.
Off unless the hook is invoked with --log (records what did NOT auto-approve) or
--log-everything (records approvals too). See docs/design/decision-log.md.
Two properties govern everything here:
Logging can never change a verdict. A PreToolUse hook that crashes fails OPEN — the harness
runs the command — so a logging fault must not propagate. Every path in this module swallows its
errors: a missing $HOME, an unwritable directory, a full disk and a read-only filesystem all
result in nothing being written and the classification proceeding untouched. There is no ? that
escapes to the caller and no unwrap.
The mode is checked before the entry is built. --log’s whole advantage is that it does
nothing on the overwhelmingly common path (an approval), and that is only true if the
allow/deny test comes first. record returns before touching the engine, the filesystem or the
clock when the outcome is not one this mode keeps.
Structs§
- Context
- Everything about the invocation that is not the verdict. Borrowed rather than owned so building one costs nothing on the path where the mode discards it.
Enums§
- Mode
- What the log keeps.
- Outcome
- What safe-chains decided. Distinct from a bare bool because the three non-approvals need telling apart in triage: a denial is a classification, an abstain is a harness/tool mismatch, and a parse failure is a availability signal — a rise in them is how a parser regression shows up in the field.
Functions§
- record
- Append one entry, if this mode keeps that outcome. Never fails, never panics, never blocks the caller’s decision.