enhance-hooks

# enhance-hooks

Analyze hook definitions and scripts for safety, correctness, and best practices.

## Workflow

1. **Discover** - Find hook files (.md, .sh, .json)
2. **Classify** - Identify hook type and event
3. **Parse** - Extract frontmatter and script content
4. **Check** - Run all pattern checks against knowledge below
5. **Filter** - Apply certainty filtering
6. **Report** - Generate markdown output
7. **Fix** - Apply auto-fixes if --fix flag present

---

## Hook Knowledge Reference

### What Are Hooks

Hooks are automated actions triggered at specific points in a Claude Code session. They enable validation, monitoring, and control of Claude's actions through bash commands or LLM-based evaluation.

### Hook Lifecycle (Complete Reference)

Hooks fire in this sequence:

| Order | Event | Description | Matcher Required |
|-------|-------|-------------|------------------|
| 1 | `SessionStart` | Session begins or resumes | No |
| 2 | `UserPromptSubmit` | User submits a prompt | No |
| 3 | `PreToolUse` | Before tool execution (can modify/block) | Yes |
| 4 | `PermissionRequest` | When permission dialog appears | Yes |
| 5 | `PostToolUse` | After tool succeeds | Yes |
| 6 | `SubagentStart` | When spawning a subagent | No |
| 7 | `SubagentStop` | When subagent finishes | No |
| 8 | `Stop` | Claude finishes responding | No |
| 9 | `PreCompact` | Before context compaction | No |
| 10 | `SessionEnd` | Session terminates | No |
| 11 | `Notification` | Claude Code sends notifications | No |

### Hook Types

**Command Hooks** (`type: "command"`):
- Execute bash commands with full stdin/stdout control
- Available for all events

**Prompt Hooks** (`type: "prompt"`):
- Use LLM evaluation for intelligent, context-aware decisions
- **Only supported for `Stop` and `SubagentStop` events**

### Configuration Locations

| File | Location | Scope | Committed |
|------|----------|-------|-----------|
| User settings | `~/.claude/settings.json` | All projects | No |
| Project settin