# HOOKS KNOWLEDGE BASE

## OVERVIEW
22+ lifecycle hooks intercepting/modifying agent behavior via PreToolUse, PostToolUse, UserPromptSubmit, and more.

## STRUCTURE
```
hooks/
├── sisyphus-orchestrator/      # Main orchestration & agent delegation (684 lines)
├── anthropic-context-window-limit-recovery/  # Auto-summarize at token limit (554 lines)
├── todo-continuation-enforcer.ts # Force completion of [ ] items (445 lines)
├── ralph-loop/                 # Self-referential dev loop (364 lines)
├── claude-code-hooks/          # settings.json hook compatibility layer
├── comment-checker/            # Prevents AI slop/excessive comments
├── auto-slash-command/         # Detects and executes /command patterns
├── rules-injector/             # Conditional rules from .claude/rules/
├── directory-agents-injector/  # Auto-injects local AGENTS.md files
├── directory-readme-injector/  # Auto-injects local README.md files
├── preemptive-compaction/      # Triggers summary at 85% usage
├── edit-error-recovery/        # Recovers from tool execution failures
├── thinking-block-validator/   # Ensures valid <thinking> format
├── context-window-monitor.ts   # Reminds agents of remaining headroom
├── session-recovery/           # Auto-recovers from session crashes
├── start-work/                 # Initializes work sessions (ulw/ulw)
├── think-mode/                 # Dynamic thinking budget adjustment
├── background-notification/    # OS notification on task completion
└── tool-output-truncator.ts    # Prevents context bloat from verbose tools
```

## HOOK EVENTS
| Event | Timing | Can Block | Description |
|-------|--------|-----------|-------------|
| PreToolUse | Before tool | Yes | Validate/modify inputs (e.g., directory-agents-injector) |
| PostToolUse | After tool | No | Append context/warnings (e.g., edit-error-recovery) |
| UserPromptSubmit | On prompt | Yes | Filter/modify user input (e.g., keyword-detector) |
| Stop | Session idle | No | Auto-continue tasks (e.g., todo-continuation-enforcer) |
| onSummarize | Compaction | No | State preservation (e.g., compaction-context-injector) |

## HOW TO ADD
1. Create `src/hooks/name/` with `index.ts` factory (e.g., `createMyHook`).
2. Implement `PreToolUse`, `PostToolUse`, `UserPromptSubmit`, `Stop`, or `onSummarize`.
3. Register in `src/hooks/index.ts`.

## PATTERNS
- **Context Injection**: Use `PreToolUse` to prepend instructions to tool inputs.
- **Resilience**: Implement `edit-error-recovery` style logic to retry failed tools.
- **Telegraphic UI**: Use `PostToolUse` to add brief warnings without bloating transcript.
- **Statelessness**: Prefer local file storage for state that must persist across sessions.

## ANTI-PATTERNS
- **Blocking**: Avoid blocking tools unless critical (use warnings in `PostToolUse` instead).
- **Latency**: No heavy computation in `PreToolUse`; it slows every interaction.
- **Redundancy**: Don't inject the same file multiple times; track state in session storage.
- **Prose**: Never use verbose prose in hook outputs; keep it technical and brief.