Claude Hooks Lifecycle
Relevant source files
The following files were used as context for generating this wiki page:
Claude Hooks Lifecycle manages the automated enforcement of Test-Driven Development (TDD) principles by intercepting tool operations and user interactions within Claude Code. The system operates by capturing events through three primary hook points: SessionStart, UserPromptSubmit, and PreToolUse/PostToolUse. This lifecycle ensures that the AI agent follows the Red-Green-Refactor cycle, blocking premature implementations or excessive changes.
The lifecycle is primarily orchestrated by the processHookData function, which routes incoming JSON data from Claude Code to specialized handlers for session management, user commands, and TDD validation.
Sources: README.md:14-22, CLAUDE.md:6-14, src/hooks/processHookData.ts:50-100
Hook Event Types
TDD Guard integrates with Claude Code through specific lifecycle events. Each event triggers a different processing path to maintain the integrity of the TDD environment.
| Hook Event | Purpose | Action Taken |
|---|---|---|
SessionStart | Initializes or resumes a session | Clears transient data (test results, modifications) while preserving configuration. |
UserPromptSubmit | Captures user input directly | Processes toggle commands like tdd-guard on/off. |
PreToolUse | Intercepts operations before execution | Validates file changes against TDD rules and checks for lint issues. |
PostToolUse | Occurs after a tool completes | Processes tool output, such as capturing new lint results. |
Sources: README.md:189-215, src/hooks/processHookData.ts:68-88, src/hooks/processHookData.test.ts:251-270
Data Flow Architecture
The following diagram illustrates how hook data flows from Claude Code through the TDD Guard validation engine.
The system uses a Storage abstraction (typically FileStorage or MemoryStorage) to maintain state between these hook calls, allowing PreToolUse to compare current modifications against previous test results.
Sources: src/hooks/processHookData.ts:50-105, src/hooks/processHookData.test.ts:72-100, CLAUDE.md:16-30
Detailed Lifecycle Stages
1. Session Initialization
When a session starts (startup, resume, or clear), the SessionHandler clears "transient" data. This ensures that test failures or code modifications from a previous project state do not influence the validation of the current session.
- Files Cleared:
test.json,modifications.json,lint.json,todos.json. - Files Preserved:
config.json(contains guard enable/disable status and ignore patterns).
Sources: src/hooks/processHookData.ts:68-72, src/hooks/processHookData.test.ts:251-275, src/config/Config.test.ts:40-65
2. Interaction & Command Handling
The UserPromptHandler intercepts prompt submissions. If a user enters specific control commands, the lifecycle bypasses TDD validation to update the internal state of the GuardManager.
3. Pre-Tool Validation Logic
This is the core of the lifecycle for Write, Edit, and MultiEdit operations. Before a file is modified, TDD Guard performs several checks:
- Ignore Patterns: Files matching
DEFAULT_IGNORE_PATTERNS(e.g.,node_modules/**,*.md) are skipped immediately. - Lint Notification: If tests are currently passing but lint errors exist, the system blocks the operation once to force a refactor/fix before new features are added.
- AI Validation: A
Contextis built from stored test results and proposed changes, then sent to an AI model to determine if TDD principles (like minimal implementation) are followed.
Sources: src/hooks/processHookData.ts:62-66, src/hooks/processHookData.ts:133-176, src/validation/prompts/rules.ts:1-20
4. Post-Tool Execution
After a tool execution completes, the PostToolLintHandler processes the output. This is primarily used to trigger linter runs and save the resulting issues to storage, which will be used in the next PreToolUse cycle.
Sources: src/hooks/processHookData.ts:84-88, src/hooks/processHookData.test.ts:145-155
TDD Validation Rules
The lifecycle enforces specific rules during the PreToolUse stage based on the operation type.
| Rule Category | Requirement | Source |
|---|---|---|
| Red Phase | Adding a single test is always allowed, even without prior test output. | rules.ts:7-11 |
| Green Phase | Minimal implementation to fix the specific failure (e.g., only a stub for "not defined"). | rules.ts:13-17 |
| Refactor Phase | Only allowed if tests are passing; no new behavior can be introduced. | rules.ts:19-24 |
| Multi-Edit | Total count of new tests across all edits in one operation must not exceed one. | multi-edit.ts:17-25 |
Summary
The Claude Hooks Lifecycle provides a structured pipeline for TDD enforcement. It ensures that the AI agent remains within the project's TDD boundaries by clearing session state, handling manual overrides, and performing context-aware validation of every code change against historical test results and linting status.
Sources: CLAUDE.md:6-14, src/hooks/processHookData.ts:107-130