improvement: document hook exit code 2 vs 1 semantics

[Luis85]

Context

Part of the plugin audit in #444 (§3, §8 Quick Wins). The Claude Code hook system inverts the standard Unix exit-code convention in a way that is not obvious and has caused production bugs:

Exit code 2 = blocking (Claude Code halts the action).
Exit code 1 = non-blocking (execution continues — most scripts' error default).

Hook scripts that exit 1 on invalid input are silently passing through. This is a common source of branch guard failures.

Work

1. Add a docs/hooks.md (or update docs/branching.md / relevant doc) with:
   • Exit-code semantics table: 0 = success, 1 = non-blocking error, 2 = blocking veto
   • Contrast with standard Unix convention
   • asyncRewake: true explained — runs hook in background but allows a delayed blocking veto
   • once: true explained — runs exactly once per session then removes itself
   • Security notes from research: Claude plugin developer best-practices audit — gaps, standards, refactor opportunities #444 §3 (injection vectors, CVE-2025-54795 summary)
2. Add a one-liner note to CLAUDE.md or the branch guard hook comment referencing this doc

Definition of Done

• docs/hooks.md (or updated equivalent) documents the exit-code inversion prominently
• Branch guard hook file has an inline comment citing the exit 2 requirement
• Verify gate green

References

• Parent audit: research: Claude plugin developer best-practices audit — gaps, standards, refactor opportunities #444 §3
• Official hooks docs: https://code.claude.com/docs/en/hooks
• CVE-2025-54795