Session Management
Relevant source files
The following files were used as context for generating this wiki page:
Session Management in TDD Guard handles the lifecycle of the TDD enforcement agent within a Claude Code session. Its primary purpose is to ensure that transient data is cleaned up during session transitions (start, resume, or clear) and that the necessary TDD validation rules are initialized.
The system ensures that while temporary state like test results and file modifications are wiped to prevent cross-contamination between tasks, persistent configuration and custom instructions remain intact.
Session Initialization and Lifecycle
When a new session is detected via the SessionStart hook, the SessionHandler coordinates the cleanup of transient storage and the setup of fundamental TDD rules. This process is triggered by specific session events: startup, resume, and clear.
Sources: src/hooks/sessionHandler.ts:13-24, src/contracts/schemas/toolSchemas.ts
The Session Start Flow
The sequence diagram below illustrates how the SessionHandler processes a session start event, interacting with the storage layer to prepare the environment.
Explanation: The SessionHandler validates the incoming JSON data against the SessionStartSchema before performing maintenance on the storage layer.
Sources: src/hooks/sessionHandler.ts:13-33, src/hooks/sessionHandler.test.ts:35-65
Data Persistence Categories
The system distinguishes between Transient Data, which is specific to the current TDD cycle, and Persistent Data, which governs the overall behavior of the guard across sessions.
Transient vs. Persistent Data
| Data Type | Category | Description | Source File |
|---|---|---|---|
| Test Results | Transient | Captured output from test runners (Jest, Vitest, etc.) | storage.getTest() |
| Modifications | Transient | Staged file edits and write operations | storage.getModifications() |
| Todos | Transient | Current task list from TodoWrite operations | storage.getTodo() |
| Lint Issues | Transient | Captured code quality issues | storage.getLint() |
| Config | Persistent | Guard enabled/disabled status and ignore patterns | storage.getConfig() |
| Instructions | Persistent | Custom TDD rules or default fundamental rules | storage.getInstructions() |
Sources: src/hooks/sessionHandler.test.ts:44-60, src/hooks/processHookData.test.ts:258-278
Session Components and Architecture
The SessionHandler class is the central orchestrator for session lifecycle events.
SessionHandler Class
The SessionHandler requires a Storage implementation (defaulting to FileStorage) to manage the state.
processSessionStart(hookData: string): The entry point for theSessionStarthook. It parses the hook data and triggers cleanup.ensureInstructionsExist(): Private method that checks if TDD rules are present in storage; if not, it populates them with the defaultRULESconstant.
Sources: src/hooks/sessionHandler.ts:7-33
Explanation: The SessionHandler depends on the Storage interface to perform data operations, ensuring loose coupling with the physical storage mechanism.
Sources: src/hooks/sessionHandler.ts:7-11
Session Event Validation
Events must match the SessionStartSchema to be processed. This schema enforces that the hook_event_name is exactly SessionStart and the source is one of the valid lifecycle triggers.
Valid Session Sources
- startup: Triggered when a new Claude Code session begins.
- resume: Triggered when an existing session is resumed.
- clear: Triggered when the session state is manually cleared.
Sources: src/contracts/schemas/toolSchemas.test.ts:33-55, src/hooks/sessionHandler.test.ts:80-87
Configuration Preservation
During session transitions, the GuardManager ensures that user settings are not lost. If a user has disabled the guard or set custom ignore patterns, these settings persist through session restarts.
it('should preserve config data when SessionStart event is received', async () => {
expect(await sut.getConfig()).toBe(JSON.stringify({ guardEnabled: true }))
})
Sources: src/hooks/processHookData.test.ts:275-277, src/hooks/sessionHandler.test.ts:59-61
Conclusion
Session Management ensures that TDD Guard remains in a clean, predictable state at the start of every developer interaction. By separating transient TDD cycle data from persistent configuration, the system provides a seamless experience where rules are always present but old test results do not interfere with new implementation tasks.