User Prompt Handler
Relevant source files
The following files were used as context for generating this wiki page:
The UserPromptHandler is a specialized component within the TDD Guard system responsible for intercepting and processing manual commands issued by the user through the Claude Code interface. Its primary function is to manage the active state of the TDD enforcement engine by parsing specific user prompts into administrative actions.
This module acts as a bridge between the UserPromptSubmit hook event and the GuardManager. It allows users to toggle the TDD Guard on or off mid-session without modifying configuration files manually, providing immediate feedback and halting the command's propagation to the AI agent to prevent unnecessary processing.
Sources: src/hooks/userPromptHandler.ts:1-7, README.md:195-201
Core Architecture and Logic
The UserPromptHandler class encapsulates the logic for command detection and state transition. It relies on a GuardManager instance to persist the enabled or disabled state of the guard.
Command Processing Flow
When a user submits a prompt, the system triggers the UserPromptSubmit hook. The handler parses the incoming JSON data, verifies the event type, and checks the prompt content against a set of predefined constant commands.
The handler ensures that administrative commands are intercepted and not sent to the AI model.
Sources: src/hooks/userPromptHandler.ts:15-39, src/hooks/userPromptHandler.test.ts:32-37
Key Components and Methods
| Component | Type | Description |
|---|---|---|
GUARD_COMMANDS | Constant | Defines the recognized strings: tdd-guard on and tdd-guard off. |
processUserCommand | Method | The main entry point that parses hook data and updates guard state. |
getDisabledResult | Method | Checks if the guard is currently disabled and returns a neutral result to bypass further validation. |
createBlockResult | Method | Generates a ValidationResult that signals the system to stop further hook processing. |
Sources: src/hooks/userPromptHandler.ts:4-13, src/hooks/userPromptHandler.ts:41-55
Command Interaction and State Management
The handler interacts directly with the GuardManager to change the system's enforcement status. This change is reflected in subsequent tool operations (like Edit or Write).
Sequence of Operation
The following diagram illustrates how the UserPromptHandler interacts with the broader hook processing system to enable the guard.
Handled Commands
The handler is case-insensitive, ensuring that variations in user input do not prevent the command from executing.
tdd-guard on: Transitions the guard to an enabled state. Subsequent file operations will be validated against TDD principles.tdd-guard off: Disables the guard. File operations will proceed without AI-based TDD validation.
Sources: src/hooks/userPromptHandler.ts:22-38, src/hooks/userPromptHandler.test.ts:58-75
Integration with Hook Lifecycle
The UserPromptHandler is integrated into the processHookData function. It is called before the main validator logic to ensure that if a command is processed, the system can exit early.
// src/hooks/userPromptHandler.ts:41-47
private createBlockResult(message: string): ValidationResult {
return {
decision: undefined,
reason: message,
continue: false,
stopReason: message
}
}
If the decision is undefined but continue is false, the Claude Code hook system understands that the operation was handled administratively and should not result in an error or a prompt to the AI.
Sources: src/hooks/userPromptHandler.ts:41-47, src/hooks/processHookData.test.ts:303-315
Summary
The UserPromptHandler provides a critical UI-to-Engine interface for TDD Guard. By intercepting UserPromptSubmit events, it allows for real-time control over TDD enforcement, enabling or disabling the GuardManager based on simple text commands. This ensures a seamless developer experience where the tool can be toggled without disrupting the terminal environment or requiring manual configuration file edits.
Sources: src/hooks/userPromptHandler.ts:15-39, README.md:195-201