hooks-reference

name	hooks-reference
model	sonnet
description	Produces a hook script scaffold and settings.json registration block by looking up the correct lifecycle event, exit code pattern, and configuration for a Claude Code hook. Use when: "write a new hook", "hook is not firing", "block a tool call mechanically", "configure sub-agent coordination", "implement a security block pattern".
license	proprietary
category	system-health
triggers	["write a new hook","hook is not firing","block a tool call mechanically","configure sub-agent coordination","implement a security block pattern"]
tier	1
agents	["primary"]
tool_dependencies	["file_system"]
inputs	[{"name":"hook_requirement","type":"string","description":"Description of what the hook should do — block a tool, coordinate agents, implement a security gate, etc.","required":true}]
outputs	[{"name":"hook_scaffold","type":"string","description":"Hook script scaffold and settings.json registration block for the specified lifecycle event and exit code pattern"}]

Hooks Reference

I. Philosophy

Hooks are the mechanical enforcement layer of agent safety and observability. Unlike CLAUDE.md instructions, which guide agent behavior through documentation, hooks execute code at lifecycle boundaries where the agent cannot override them. A well-designed hook system makes dangerous operations impossible rather than merely discouraged.

This skill is a reference card, not a tutorial. It assumes you know what hooks are and need to quickly find the right event, the right exit code, or the right configuration pattern. For architectural understanding, read the seed_hooks_lifecycle_mastery and seed_mechanical_safety_enforcement seeds.

II. When to Use

• Writing a new hook and need to know which event type to target.
• Debugging why a hook is not firing (wrong event name, wrong exit code).
• Reviewing the full lifecycle to understand execution order.
• Implementing a security block pattern (exit code 2).
• Configuring hooks in .claude/settings.json or plugin hooks/hooks.json.
• Building sub-agent coordination via SubagentStart/SubagentStop hooks.

Do not use this skill for designing observability dashboards (use observability-dashboard instead) or for understanding the correction-capture pipeline (use reflect-and-learn instead).

III. All 26 Lifecycle Events

Events are organized by category. The "Block?" column indicates whether exit 2 halts execution.

Session Events

Event	Block?	Notes
SessionStart	No	Fires on session open. Stdout added to Claude context. Write to $CLAUDE_ENV_FILE to persist env vars.
SessionEnd	No	Fires on session termination. Output ignored.
InstructionsLoaded	No	Fires after CLAUDE.md and system prompt load.
CwdChanged	No	Fires when working directory changes. Write to $CLAUDE_ENV_FILE to inject env vars for subsequent Bash calls.

User / Prompt Events

Event	Block?	Notes
UserPromptSubmit	Yes (exit 2)	Fires before prompt is processed. Stdout added to Claude context. Exit 2 blocks submission.