# hooks-documentation Specification

## Purpose
TBD - created by archiving change update-hooks-lesson. Update Purpose after archive.
## Requirements
### Requirement: Hook Event Types Documentation
The hooks lesson SHALL document all 9 official hook events with their correct names, matchers, and behavior.

#### Scenario: Complete hook event coverage
- **WHEN** a user reads the hooks lesson
- **THEN** they find documentation for PreToolUse, PermissionRequest, PostToolUse, Notification, UserPromptSubmit, Stop, SubagentStop, PreCompact, SessionStart, and SessionEnd events

#### Scenario: No deprecated hook events
- **WHEN** a user searches for PreCommit, PostCommit, or PrePush hooks
- **THEN** they do not find these as they are not valid Claude Code hook events

### Requirement: Hook Configuration Format
The hooks lesson SHALL document the correct array-based configuration format with matchers and hooks arrays.

#### Scenario: Configuration structure
- **WHEN** a user views hook configuration examples
- **THEN** they see the structure: `{ "hooks": { "EventName": [{ "matcher": "Pattern", "hooks": [{ "type": "command", "command": "..." }] }] } }`

#### Scenario: Matcher patterns
- **WHEN** a user needs to match specific tools
- **THEN** they find documentation for exact string matching, regex patterns, and wildcards

### Requirement: Hook Input Documentation
The hooks lesson SHALL document the JSON stdin input that hooks receive.

#### Scenario: JSON input structure
- **WHEN** a user writes a hook script
- **THEN** they understand the input includes session_id, transcript_path, cwd, permission_mode, hook_event_name, tool_name, tool_input, and tool_use_id

#### Scenario: Event-specific input fields
- **WHEN** a user writes a hook for a specific event
- **THEN** they find documentation for event-specific input fields (e.g., stop_hook_active for Stop event)

### Requirement: Hook Output Documentation
The hooks lesson SHALL document hook output semantics including exit codes and JSON stdout structure.

#### Scenario: Exit code semantics
- **WHEN** a user implements a hook
- **THEN** they understand exit code 0 means success, exit code 2 means blocking error (stderr used as error message), and other codes mean non-blocking error

#### Scenario: JSON output format
- **WHEN** a hook needs to control behavior
- **THEN** the user can output JSON with continue, stopReason, suppressOutput, systemMessage, and hookSpecificOutput fields

#### Scenario: Event-specific output
- **WHEN** a user writes a PreToolUse hook
- **THEN** they can output permissionDecision (allow/deny/ask), permissionDecisionReason, and updatedInput

### Requirement: Prompt-Based Hooks Documentation
The hooks lesson SHALL document type="prompt" hooks for LLM-based evaluation on Stop and SubagentStop events.

#### Scenario: Prompt hook configuration
- **WHEN** a user wants intelligent stop evaluation
- **THEN** they find documentation for configuring type="prompt" hooks with prompt text and timeout

#### Scenario: LLM response schema
- **WHEN** using prompt-based hooks
- **THEN** the user understands the expected response schema with decision (approve/block), reason, continue, stopReason, and systemMessage

### Requirement: Environment Variables Documentation
The hooks lesson SHALL document all environment variables available to hooks.

#### Scenario: Standard environment variables
- **WHEN** a user writes a hook script
- **THEN** they can use CLAUDE_PROJECT_DIR for the absolute project path

#### Scenario: SessionStart environment persistence
- **WHEN** using SessionStart hooks
- **THEN** the user can persist environment variables via CLAUDE_ENV_FILE

#### Scenario: Remote environment detection
- **WHEN** running in web environment
- **THEN** hooks can check CLAUDE_CODE_REMOTE to detect this

### Requirement: Security Documentation
The hooks lesson SHALL include security considerations and best practices from the official documentation.

#### Scenario: Security disclaimer
- **WHEN** a user reads about hooks
- **THEN** they see a clear disclaimer that hooks execute arbitrary shell commands at their own risk

#### Scenario: Security best practices
- **WHEN** a user implements hooks
- **THEN** they find guidance on input validation, shell variable quoting, path traversal prevention, and sensitive file handling

### Requirement: MCP Tool Hook Patterns
The hooks lesson SHALL document how to create hooks for MCP tools.

#### Scenario: MCP tool matching
- **WHEN** a user wants to hook into MCP tool calls
- **THEN** they find documentation for the pattern `mcp__<server>__<tool>` and regex matching

### Requirement: Plugin Hooks Documentation
The hooks lesson SHALL document how plugins can provide hooks.

#### Scenario: Plugin hook configuration
- **WHEN** a plugin needs to provide hooks
- **THEN** documentation covers hooks/hooks.json structure and ${CLAUDE_PLUGIN_ROOT} variable

### Requirement: Debugging Documentation
The hooks lesson SHALL document how to debug hook execution.

#### Scenario: Debug mode
- **WHEN** hooks are not working as expected
- **THEN** users can enable `claude --debug` for detailed hook execution logs

#### Scenario: Verbose mode
- **WHEN** using Claude Code interactively
- **THEN** users can enable verbose mode (ctrl+o) to see hook execution progress

### Requirement: Working Example Scripts
The hooks lesson SHALL provide working example scripts that use JSON stdin input.

#### Scenario: Bash command validator
- **WHEN** a user wants to validate bash commands
- **THEN** they find a working Python script that reads JSON stdin and validates commands

#### Scenario: Intelligent stop hook
- **WHEN** a user wants automatic task completion verification
- **THEN** they find a working prompt-based stop hook example

### Requirement: Context Usage Reporting Hook Example
The hooks lesson SHALL include a correct, working example showing how to create a hook that reports context/token usage after each Claude response.

#### Scenario: Token calculation is correct
- **WHEN** a user copies the context-usage.py example
- **AND** runs it as a Stop hook
- **THEN** the hook correctly calculates estimated tokens from total character count
- **AND** displays a non-zero token count proportional to conversation length

#### Scenario: User learns to create context monitoring hook
- **WHEN** a user reads the context usage reporter example
- **THEN** they find a complete Python script that reads the transcript file
- **AND** they understand how to estimate token usage from conversation history
- **AND** they see the configuration for Stop hooks
- **AND** they understand the limitations of token estimation

#### Scenario: Hook output format is documented
- **WHEN** a user implements the context usage hook
- **THEN** they can generate a one-line report showing used tokens and remaining capacity
- **AND** the output shows realistic token counts based on conversation size