chore: Archive update-hooks-lesson change
Move completed change to archive and create hooks-documentation spec.
This commit is contained in:
Luong NGUYEN
@@ -0,0 +1,36 @@
|
||||
# Change: Update Hooks Lesson Based on Official Documentation
|
||||
|
||||
## Why
|
||||
|
||||
The current hooks lesson (`blog-posts/06-hooks.md`) contains outdated and inaccurate information that doesn't match the official Claude Code hooks documentation. Key issues include:
|
||||
|
||||
1. **Incorrect hook event names**: Uses `PreToolUse:Write`, `PreCommit`, `PostCommit`, `PrePush` which don't exist
|
||||
2. **Missing hook events**: Doesn't cover `PermissionRequest`, `Stop`, `SubagentStop`, `PreCompact`, `SessionStart` (with matchers), `SessionEnd`
|
||||
3. **Wrong configuration format**: Shows string-based hook commands instead of the array-based matcher/hooks structure
|
||||
4. **Missing hook input/output**: Doesn't explain JSON stdin input or structured JSON output
|
||||
5. **Missing exit code semantics**: Exit code 2 for blocking vs other non-zero codes
|
||||
6. **Missing prompt-based hooks**: No coverage of `type: "prompt"` hooks for LLM-based evaluation
|
||||
7. **Missing security considerations**: No disclaimer or security best practices from official docs
|
||||
8. **Incorrect variable references**: Uses `${file_path}`, `${command}` instead of JSON stdin input
|
||||
|
||||
## What Changes
|
||||
|
||||
- **BREAKING**: Complete rewrite of hook event types and configuration format
|
||||
- Update all code examples to use correct array-based configuration structure
|
||||
- Add coverage of all 9 hook events: `PreToolUse`, `PermissionRequest`, `PostToolUse`, `Notification`, `UserPromptSubmit`, `Stop`, `SubagentStop`, `PreCompact`, `SessionStart`, `SessionEnd`
|
||||
- Add JSON hook input/output documentation with examples
|
||||
- Add hook matchers (tool patterns, regex support)
|
||||
- Add prompt-based hooks for `Stop`/`SubagentStop`
|
||||
- Add security considerations section with official disclaimer
|
||||
- Add environment variables section (`CLAUDE_PROJECT_DIR`, `CLAUDE_ENV_FILE`, `CLAUDE_CODE_REMOTE`)
|
||||
- Add plugin hooks documentation
|
||||
- Add MCP tool hook patterns (`mcp__<server>__<tool>`)
|
||||
- Update debugging section with `claude --debug` and verbose mode
|
||||
- Remove incorrect/non-existent hook types (`PreCommit`, `PostCommit`, `PrePush`)
|
||||
|
||||
## Impact
|
||||
|
||||
- **Affected specs**: hooks-documentation (new capability)
|
||||
- **Affected code**: `blog-posts/06-hooks.md` (complete rewrite)
|
||||
- **Affected examples**: Any example hook scripts in the repo need updating to use JSON stdin
|
||||
- **User impact**: Users following the current guide will have non-functional hooks; this update provides correct, working examples
|
||||
@@ -0,0 +1,124 @@
|
||||
# Hooks Documentation Specification
|
||||
|
||||
## ADDED 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
|
||||
@@ -0,0 +1,69 @@
|
||||
# Tasks: Update Hooks Lesson
|
||||
|
||||
## 1. Content Structure Update
|
||||
- [x] 1.1 Update introduction to explain hooks as event-driven automation scripts
|
||||
- [x] 1.2 Replace hook architecture diagram with correct event flow
|
||||
- [x] 1.3 Update hook types table with all 9 official hook events
|
||||
|
||||
## 2. Configuration Format
|
||||
- [x] 2.1 Rewrite configuration section with array-based matcher/hooks structure
|
||||
- [x] 2.2 Add hook matcher documentation (exact match, regex patterns, wildcards)
|
||||
- [x] 2.3 Add timeout configuration examples
|
||||
|
||||
## 3. Hook Events Documentation
|
||||
- [x] 3.1 Document PreToolUse event (matchers, decision control, updatedInput)
|
||||
- [x] 3.2 Document PermissionRequest event (decision behavior, messages)
|
||||
- [x] 3.3 Document PostToolUse event (block decision, additionalContext)
|
||||
- [x] 3.4 Document Notification event (matchers: permission_prompt, idle_prompt, etc.)
|
||||
- [x] 3.5 Document UserPromptSubmit event (block decision, context addition)
|
||||
- [x] 3.6 Document Stop event (block continuation, stop_hook_active)
|
||||
- [x] 3.7 Document SubagentStop event (subagent completion handling)
|
||||
- [x] 3.8 Document PreCompact event (manual vs auto matchers)
|
||||
- [x] 3.9 Document SessionStart event (startup/resume/clear/compact matchers, CLAUDE_ENV_FILE)
|
||||
- [x] 3.10 Document SessionEnd event (reason field)
|
||||
|
||||
## 4. Hook Input/Output
|
||||
- [x] 4.1 Document JSON stdin input structure (session_id, transcript_path, cwd, etc.)
|
||||
- [x] 4.2 Document exit code semantics (0=success, 2=blocking error, other=non-blocking)
|
||||
- [x] 4.3 Document JSON stdout output structure (continue, stopReason, hookSpecificOutput)
|
||||
- [x] 4.4 Add examples for each hook event's specific output format
|
||||
|
||||
## 5. Prompt-Based Hooks
|
||||
- [x] 5.1 Add section on type="prompt" hooks for Stop/SubagentStop
|
||||
- [x] 5.2 Document LLM response schema (decision, reason, continue, stopReason)
|
||||
- [x] 5.3 Add practical examples of intelligent stop hooks
|
||||
|
||||
## 6. Environment Variables
|
||||
- [x] 6.1 Document CLAUDE_PROJECT_DIR usage
|
||||
- [x] 6.2 Document CLAUDE_ENV_FILE for SessionStart env persistence
|
||||
- [x] 6.3 Document CLAUDE_CODE_REMOTE for web environment detection
|
||||
- [x] 6.4 Document plugin hook variables (${CLAUDE_PLUGIN_ROOT})
|
||||
|
||||
## 7. Security Section
|
||||
- [x] 7.1 Add official security disclaimer (USE AT YOUR OWN RISK)
|
||||
- [x] 7.2 Document security best practices (input validation, quoting, path traversal)
|
||||
- [x] 7.3 Add configuration safety notes (snapshot at startup, modification warnings)
|
||||
|
||||
## 8. Advanced Features
|
||||
- [x] 8.1 Add MCP tool hook patterns (mcp__<server>__<tool>)
|
||||
- [x] 8.2 Add plugin hooks documentation
|
||||
- [x] 8.3 Add project-specific hook script examples
|
||||
|
||||
## 9. Debugging and Troubleshooting
|
||||
- [x] 9.1 Update debugging section with claude --debug flag
|
||||
- [x] 9.2 Add verbose mode (ctrl+o) documentation
|
||||
- [x] 9.3 Update troubleshooting with correct error scenarios
|
||||
|
||||
## 10. Example Scripts
|
||||
- [x] 10.1 Rewrite format-code hook to use JSON stdin
|
||||
- [x] 10.2 Rewrite security-scan hook with proper JSON input parsing
|
||||
- [x] 10.3 Rewrite bash command validator example from official docs
|
||||
- [x] 10.4 Add intelligent stop hook example with prompt type
|
||||
- [x] 10.5 Remove non-existent PreCommit/PostCommit/PrePush examples
|
||||
|
||||
## 11. Final Cleanup
|
||||
- [x] 11.1 Update Mermaid diagrams for accuracy
|
||||
- [x] 11.2 Update variable reference table to reflect JSON input
|
||||
- [x] 11.3 Update best practices table
|
||||
- [x] 11.4 Update directory structure section
|
||||
- [x] 11.5 Verify all links and references
|
||||
Reference in New Issue
Block a user