Architecture & Real-Run Walkthrough
Two-Layer Enforcement Flow
text
Agent Tool Call (Write / Edit / Bash / Read / Grep)
└─▶ Claude Code PreToolUse (offline, no --net, 30s–120s timeout)
├─ Parse error / rule match / stale cache ──▶ deny JSON + exit 2
└─ Exact pass ──────────────────────────────▶ silent exit 0 (host prompts preserved)
Git Lifecycle (pre-commit / pre-merge-commit / commit-msg / pre-push)
└─▶ Git Client Hooks (--net enabled: lazy cache refresh + single-slug lookup)
└─▶ Single Policy Engine policy/check.py (R1–R7 + ssh-keygen -Y check-novalidate)
├─ pass ──────────────────────────────▶ exit 0
└─ violation / error ─────────────────▶ exit 1 + masked diagnosticsOne Real Run: Write Tool Interception
- Extract Payload (
hooks/forbid-content.sh): Reads stdin JSON onWrite,Edit, orNotebookEdit(content/new_string/new_source). Invalid JSON triggers fail-closeddeny; empty content exits0silently. - Offline Engine Call (
hooks/_lib.sh->policy/check.py content): Invokescheck.py contentwithout--netso the check completes well inside the 120s hook timeout (a killed hook defaults to "no decision" in Claude Code). - Static & Cache Evaluation (
full_check): Runsscan()(R2within_b64_runfiltering +R7unskipped secret regexes masked to 8 chars) followed byprivate_check()(R4local seed patterns +R1cached private repo names within the6hTTL). Missing or expired caches returnerror, neverpass. - Output Mapping: Only exact stdout
passexits0silently (never emittingpermissionDecision: allow). AnyviolationorerroroutputspermissionDecision: denyJSON and exits2. - Final Git Gate (
hooks/git/*): Realgit commit,git merge, andgit pushevents re-run the same engine with--net, addingR3authorship,R5agent branch checks,R6SSH cryptographic verification, andknown_contentchecks againstgit ls-remotetips.
See the Code Map for exact source locations and maintainer entry points.