Hook System

Relevant source files

• .gitignore
• CHANGELOG.md
• LICENSE.md
• README.md
• demo.gif
• plugins/explanatory-output-style/.claude-plugin/plugin.json
• plugins/explanatory-output-style/README.md
• plugins/explanatory-output-style/hooks-handlers/session-start.sh
• plugins/explanatory-output-style/hooks/hooks.json
• plugins/learning-output-style/.claude-plugin/plugin.json
• plugins/learning-output-style/README.md
• plugins/learning-output-style/hooks-handlers/session-start.sh
• plugins/learning-output-style/hooks/hooks.json

The hook system provides extensibility points throughout Claude Code's lifecycle, allowing plugins and users to inject custom behavior at specific events such as session start, before/after tool execution, and during multi-agent workflows. Hooks are defined in JSON configuration files and execute external commands (typically shell scripts) that can modify context, block operations, or perform side effects.

For information about the plugin system that hosts hooks, see Plugin System. For MCP server integration, see MCP Server Integration.

Hook Types and Lifecycle Events

Claude Code supports seven distinct hook types that fire at different points in the execution lifecycle:

Hook Type	When It Fires	Common Use Cases
Setup	Triggered via --init, --init-only, or --maintenance CLI flags	Repository initialization, dependency installation, maintenance tasks
SessionStart	At the beginning of every session, before any user interaction	Adding system instructions, setting output styles, loading context
PreToolUse	Before each tool execution (Bash, Read, Write, etc.)	Validation, security checks, context injection, permission auditing
PostToolUse	After each tool execution completes	Logging, result processing, cleanup operations
ConfigChange	When configuration files change during a session	Enterprise security auditing, blocking unauthorized settings changes
TeammateIdle	When a subagent is waiting for work in multi-agent workflows	Coordination logic, status tracking
TaskCompleted	When a background task or subagent completes	Result aggregation, notification, cleanup
Stop	When a session ends (main agent or subagent)	Cleanup, analytics, saving state

Sources: CHANGELOG.md24-439 plugins/explanatory-output-style/hooks/hooks.json1-15

Hook Execution Flow

Sources: CHANGELOG.md40 CHANGELOG.md90 CHANGELOG.md424

Hook Definition Format

Hooks are defined in hooks/hooks.json files within plugins or project .claude directories. Each hook configuration specifies the event type and the command to execute.

Basic Hook Structure

Variable Substitution

Hook commands support environment variable substitution:

• ${CLAUDE_PLUGIN_ROOT}: Absolute path to the plugin directory
• ${CLAUDE_SESSION_ID}: Current session identifier (for use in skills)
• Standard environment variables are also available

Sources: plugins/explanatory-output-style/hooks/hooks.json1-15 plugins/learning-output-style/hooks/hooks.json1-15 CHANGELOG.md439

Hook Input and Output Protocol

Hook Execution Context

Hooks receive input via standard input as JSON and must output JSON to standard output. The input structure varies by hook type.

Hook Output Format

Hooks must output JSON with a hookSpecificOutput object containing hook-specific fields:

Exit Codes

Exit Code	Meaning	Behavior
0	Success/Allow	Hook completed successfully, operation continues
2	Block/Deny	Operation is blocked, stderr content shown to user
Other	Error	Hook failed, error logged

Sources: CHANGELOG.md153 CHANGELOG.md168 plugins/learning-output-style/hooks-handlers/session-start.sh1-16

Hook Types in Detail

SessionStart Hook

Fires once at the beginning of every session, after initialization but before the first user interaction. Deferred for performance optimization.

Purpose: Inject system instructions, configure output styles, add initial context

Output Fields:

• additionalContext: String appended to system prompt

Example Output:

Sources: CHANGELOG.md40 plugins/explanatory-output-style/hooks-handlers/session-start.sh1-15 plugins/learning-output-style/hooks-handlers/session-start.sh1-15

PreToolUse Hook

Fires before each tool execution, allowing inspection and modification of tool parameters or blocking the operation.

Purpose: Validation, security checks, context injection, permission auditing

Output Fields:

• additionalContext: Context added to the tool use message for the model to see

Blocking: Exit code 2 prevents tool execution and shows stderr to user

Platform Notes: Uses Git Bash on Windows instead of cmd.exe to ensure compatibility

Sources: CHANGELOG.md90 CHANGELOG.md439

PostToolUse Hook

Fires after each tool execution completes, receiving the tool result.

Purpose: Logging, result post-processing, analytics, cleanup

Sources: CHANGELOG.md90

Stop Hook

Fires when a session ends, either for the main agent or a subagent.

Purpose: Cleanup operations, analytics, saving state

Output Fields:

• last_assistant_message: The final assistant response text (added to avoid parsing transcript files)

Sources: CHANGELOG.md54

TeammateIdle and TaskCompleted Hooks

Multi-agent coordination hooks for background tasks and agent teams.

TeammateIdle: Fires when a subagent is waiting for work TaskCompleted: Fires when a background task or subagent finishes

Purpose: Multi-agent workflow coordination, status tracking, result aggregation

Sources: CHANGELOG.md205

Setup Hook

Triggered manually via CLI flags rather than automatically.

Trigger Commands:

• claude --init: Run setup and start session
• claude --init-only: Run setup only, exit afterward
• claude --maintenance: Run maintenance setup

Purpose: Repository initialization, dependency installation, one-time setup tasks

Sources: CHANGELOG.md424

ConfigChange Hook

Fires when configuration files change during an active session.

Purpose: Enterprise security auditing, blocking unauthorized settings changes

Use Case: Organizations can monitor and prevent configuration tampering

Sources: CHANGELOG.md24

Hook Management and Configuration

Hook Loading and Discovery

Hooks are discovered from multiple sources and merged by hook type. All hooks of the same type execute in sequence.

Sources: CHANGELOG.md120

Disabling Hooks

Hooks can be disabled via settings:

• User/Project Level: disableAllHooks: true in settings.json
• Managed Settings: Enterprise can enforce allowManagedHooksOnly to prevent user-defined hooks
• Hierarchy Enforcement: Non-managed settings cannot disable managed hooks

Sources: CHANGELOG.md28

Hot Reloading

Plugin-provided hooks become available immediately after plugin installation without requiring a restart.

Sources: CHANGELOG.md120

Performance Considerations

• SessionStart Deferral: SessionStart hooks execute after the UI is ready, reducing time-to-interactive by ~500ms
• Async Cancellation: Pending async hooks are cancelled when headless streaming sessions end to prevent resource leaks
• Saved Hook Context: Resuming sessions with saved_hook_context may impact startup performance

Sources: CHANGELOG.md40 CHANGELOG.md273 CHANGELOG.md297

Hook Execution Model

Synchronous vs Asynchronous Execution

Most hooks execute synchronously and block the operation until completion. The exception is ConfigChange hooks, which fire asynchronously when file watchers detect changes.

Backgrounded Commands

Hooks that intentionally background their commands must handle their own process management. Previously, backgrounded hooks could cause sessions to wait indefinitely.

Sources: CHANGELOG.md363

Error Handling

Exit code 2 explicitly blocks operations and displays stderr to the user, enabling hooks to provide feedback on why an operation was denied.

Sources: CHANGELOG.md153 CHANGELOG.md168

Real-World Hook Examples

Explanatory Output Style Plugin

Adds educational insights instructions at session start:

Hook Definition: plugins/explanatory-output-style/hooks/hooks.json1-15

Handler Implementation: plugins/explanatory-output-style/hooks-handlers/session-start.sh1-15

Behavior:

1. Executes at session start
2. Outputs JSON with additionalContext containing instructions
3. Model receives instructions to provide educational insights in conversation

Learning Output Style Plugin

Combines interactive learning with explanatory functionality:

Hook Definition: plugins/learning-output-style/hooks/hooks.json1-15

Handler Implementation: plugins/learning-output-style/hooks-handlers/session-start.sh1-16

Behavior:

1. SessionStart hook injects learning mode instructions
2. Instructs model to request user code contributions at decision points
3. Includes explanatory insights for educational value
4. Transforms interaction from passive to active learning

Sources: plugins/explanatory-output-style/README.md1-73 plugins/learning-output-style/README.md1-94

Hook System Architecture

Sources: CHANGELOG.md120 CHANGELOG.md90 plugins/explanatory-output-style/hooks/hooks.json1-15

Hook System Integration Points

The hook system integrates with multiple core systems:

System	Integration Point	Hook Types Used
Session Manager	Session initialization and teardown	SessionStart, Stop, Setup
Tool System	Before/after tool execution	PreToolUse, PostToolUse
Config Manager	File watcher events	ConfigChange
Agent System	Subagent lifecycle	TeammateIdle, TaskCompleted, SubagentStop
Plugin System	Plugin loading and hot-reload	All types (discovery)

Sources: CHANGELOG.md205 CHANGELOG.md24 CHANGELOG.md120

Best Practices

Hook Performance

• Keep SessionStart hooks lightweight to avoid degrading startup time
• Use async operations with proper cleanup in background hooks
• Exit quickly with appropriate exit codes

Hook Security

• Validate all inputs before processing
• Use exit code 2 to block operations and provide feedback
• Implement allowManagedHooksOnly for enterprise deployments
• Avoid sensitive data in hook output (may be logged)

Hook Portability

• Use ${CLAUDE_PLUGIN_ROOT} for relative paths
• Test hooks on multiple platforms (Unix, Windows, macOS)
• Handle Windows Git Bash differences (automatic on PreToolUse/PostToolUse)
• Provide clear error messages in stderr when blocking

Sources: CHANGELOG.md28 CHANGELOG.md90 CHANGELOG.md153