ee0f4bd5d9
- Add comprehensive built-in commands reference (40+ commands) - Document argument handling ($ARGUMENTS, $1, $2, etc.) - Add bash execution syntax (! prefix) and file references (@ prefix) - Update frontmatter to official fields (allowed-tools, argument-hint, model, etc.) - Add Plugin Commands and MCP Slash Commands sections - Add SlashCommand Tool documentation for programmatic invocation - Add Skills vs Slash Commands comparison table - Create commit.md example with bash execution and context - Update existing examples to use official frontmatter format - Add OpenSpec proposal for change tracking
37 lines
2.3 KiB
Markdown
37 lines
2.3 KiB
Markdown
# 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
|