hooks-system

# Hooks System

**Version:** 1.0.0
**Purpose:** Lifecycle hook patterns for validation, automation, security, and metrics in Claude Code workflows
**Status:** Production Ready

## Overview

Hooks are lifecycle callbacks that execute at specific points in the Claude Code workflow. They enable:
- **Validation** (block dangerous operations before execution)
- **Automation** (auto-format code after file changes)
- **Security** (enforce safety policies on commands and tools)
- **Metrics** (track tool usage, performance, costs)
- **Quality Control** (run tests after implementation changes)
- **Context Injection** (load project-specific context at session start)

Hooks transform Claude Code from a reactive assistant into a **proactive, policy-enforced development environment**.

---

## Hook Types Reference

Claude Code provides 7 hook types that fire at different lifecycle stages:

| Hook Type | When It Fires | Receives | Can Modify | Use Cases |
|-----------|---------------|----------|------------|-----------|
| **PreToolUse** | Before tool execution | Tool name, input | Tool input, can block | Validation, security checks, permission gates |
| **PostToolUse** | After tool completion | Tool name, input, output | Nothing (read-only) | Auto-format, metrics, notifications |
| **UserPromptSubmit** | User submits prompt | Prompt text | Nothing (read-only) | Complexity analysis, model routing, context injection |
| **SessionStart** | Session begins | Session metadata | Nothing (read-only) | Load project context, initialize environment |
| **Stop** | Main session stops | Session metadata | Nothing (read-only) | Completion validation, cleanup, final reports |
| **SubagentStop** | Sub-agent (Task) completes | Task metadata, output | Nothing (read-only) | Task metrics, result validation |
| **Notification** | System notification | Notification data | Nothing (read-only) | Alert logging, external integrations |
| **PermissionRequest** | Tool needs permission | Tool name, action | No