Hooks Architecture
Relevant source files
The following files were used as context for generating this wiki page:
The Hooks Architecture provides a governed execution framework for the Claude Code agent estate. It enforces quality gates, manages workflow state, and invalidates stale review information during the development lifecycle. The system uses a set of Python-based scripts triggered by specific agent events to ensure that production edits remain compliant with the project's Hard Production Invariants.
Hooks serve as the primary enforcement mechanism for the Repo Production Workflow. They coordinate evidence recording, quality checks, and advisor consultations to maintain a verifiable audit trail of all code changes.
Hook Types and Lifecycle
The system categorizes hooks based on when they execute during the agent's interaction with the codebase. These are configured in ~/.claude/settings.json and executed by the agent environment.
The diagram shows how agent events trigger different hook categories to maintain governance and state.
Sources: README.md:14-23, CLAUDE.md:389-400
Key Hook Categories
| Hook Name | Event Trigger | Primary Responsibility |
|---|---|---|
PreToolUse | Before an agent uses a tool (e.g., Edit, Write) | Validates the action against the active workflow; advises on missing steps. |
PostToolUse | After a tool execution | Records evidence; supplies base OIDs for cumulative quality checks. |
SessionStart | When a session resumes or starts | Restores workflow continuity from the SQLite ledger. |
PreCompact | Before context window compaction | Flushes durable state snapshots (superseded by direct SQLite storage). |
Sources: hooks/tests/test_workflow_hooks.py:155-170, README.md:18-23, CLAUDE.md:395-400
Workflow State Management
Hooks interact with a central SQLite ledger to track the progress of a production pass. This state is repository-scoped and persists across agent sessions.
This diagram illustrates the relationship between hook scripts and the durable SQLite storage.
Sources: hooks/tests/test_workflow_hooks.py:270-285, CLAUDE.md:405-415
State Transitions and Invalidation
Hooks enforce strict state transitions. For example, any production edit or governance edit performed after a review has been recorded will automatically invalidate downstream review readiness. This forces the agent to re-earn verification and review status for the updated code tree.
- Edit Detection:
PreToolUsehooks monitor file changes. - State Check: The hook queries
workflow.py statusto determine the current phase. - Invalidation: If the phase is "complete" or "review-ready", the hook appends an
edit-invalidatedevent to the ledger. - Advice: The hook provides
additionalContextin its feedback to guide the agent back to the implementation or TDD phase.
Sources: hooks/tests/test_workflow_hooks.py:215-240, CLAUDE.md:396-398
Quality Gates and Evidence
The architecture uses specific scripts to act as quality gates during the verify phase of the workflow. These gates produce machine-readable JSON evidence that is recorded in the workflow ledger.
Production Quality Gate
The code_quality_gate.py script performs non-mutating checks against implementation standards. It identifies "Owner Competition" (multiple modules claiming the same responsibility) and "Duplicate Implementation" (repeated code patterns).
This sequence shows how quality feedback is integrated into the edit cycle.
Sources: skills/production-code/scripts/code_quality_gate.py, hooks/tests/test_workflow_hooks.py:115-130
Evidence Recording
Evidence is recorded using workflow.py record-preflight or record-production-code. The recorder requires specific JSON structures, such as a behaviorMap containing atomic behavior obligations.
- Behavior Map: A list of
contractandpreservationitems. - Proof: Verification commands and their observed results.
- Lateness: The system tracks "Late RED" events where a TDD test is run after production code has already changed.
Sources: hooks/tests/test_workflow_hooks.py:475-500, skills/repo-production-workflow/scripts/workflow.py
Governance Constraints
The hooks architecture enforces several "Hard Production Invariants" defined in the global rules:
- Mock Ban: Hooks and gates ensure that verification crosses real production interfaces. Test-only adapters or substituted collaborators are not accepted as production proof.
- Root-Cause-First: Fixes are blocked until a symptom is reproduced and a falsifiable hypothesis is recorded.
- Imaginary-Risk Ban: Guards or abstractions for theoretical failures are flagged as bloat.
Sources: CLAUDE.md:27-50, hooks/tests/test_workflow_hooks.py:650-670
The Hooks Architecture ensures that the Claude Code agent operates within a predictable, governed framework by linking tool usage directly to a durable, verifiable workflow state.