Event Model

The event model defines when hooks execute and what information they receive.

Event Timing

Events fire in a fixed sequence. This diagram shows the order guarantees:

┌─────────────────────────────────────────────────────────────────┐
│ SessionStart                                                    │
│   • Fires once when agent session begins                        │
│   • Environment setup, logging initialization                   │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│ UserPromptSubmit                                                │
│   • Fires when user input is submitted                          │
│   • Before model sees the input                                 │
│   • Can modify or block the input                               │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
              ┌───────────────────────────────┐
              │      Model Processing         │
              │  (outside hook visibility)    │
              └───────────────────────────────┘
                              │
         ┌────────────────────┴────────────────────┐
         ▼                                         ▼
┌─────────────────────┐                  ┌─────────────────────┐
│ PreToolUse          │                  │ PermissionRequest   │
│   • Before tool runs│                  │   • User approval   │
│   • Can block/allow │                  │     requested       │
└─────────────────────┘                  └─────────────────────┘
         │
         ▼
┌─────────────────────┐
│ (Tool Execution)    │
└─────────────────────┘
         │
         ▼
┌─────────────────────┐
│ PostToolUse         │
│   • After tool runs │
│   • Observe results │
└─────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│ SessionEnd                                                      │
│   • Fires when agent session terminates                         │
│   • Cleanup, summary logging                                    │
└─────────────────────────────────────────────────────────────────┘

The UserPromptSubmit → [Tool Events]* → Response cycle repeats for each user interaction. A single cycle might contain zero to many tool uses.

Session Events

Session events bracket the entire agent interaction.

SessionStart fires once when the agent session begins, before any user input is processed. Use it for logging initialization, environment validation, or setting up session-scoped resources. You get session ID, working directory, and configuration settings.

SessionEnd fires when the session terminates (normally or due to error). Use it to flush logs, cleanup resources, or compute session metrics. You get session ID, exit reason, and duration.

Input Events

Input events intercept communication between the user and the agent.

UserPromptSubmit

Fires when the user submits input, before the model processes it. You can inject context into every request, log inputs for audit, block sensitive topics, or modify prompts with additional instructions.

The hook receives raw user input, session context, and (if available) a previous conversation summary. You can modify the input text, add system context, or block the submission entirely.

PermissionRequest

Fires when the agent requests user approval (typically for tools requiring confirmation). You can auto-approve safe actions, auto-deny dangerous ones, or log permission decisions. The hook receives the requested action, tool name, and proposed arguments.

Tool Events

Tool events give you granular control over individual agent actions. They fire for every tool invocation.

PreToolUse

Fires before a tool executes. This is where most enforcement logic lives.

The hook receives tool name (bash, read, write, edit, etc.), tool arguments (command, file path, content), and session context. Based on this, you can:

• Allow the tool to proceed
• Block the tool with a feedback message
• Modify arguments (in some implementations)

Common enforcement patterns: block writes to protected paths, reject dangerous commands like rm -rf, validate arguments before execution, log all actions for audit.

PostToolUse

Fires after a tool completes. This is an observer event - you can log outputs, detect error patterns, collect metrics (file sizes, execution duration), or alert on specific output patterns. You cannot change what happened.

The hook receives tool name, arguments, exit status, output (stdout/stderr or file content), and execution duration.

Matchers

Hooks can filter which events they respond to using matchers. Instead of receiving every tool event, a hook can specify criteria:

Match: tool_name = "bash"
Match: tool_name = "write" AND path LIKE "*.py"
Match: tool_name = "bash" AND command CONTAINS "rm"

Matchers reduce overhead by avoiding hook invocation for irrelevant events. They also simplify hook logic by guaranteeing the event matches expected criteria.

Common Matcher Patterns

Pattern	Purpose
Tool name exact match	Handle specific tools differently
Path glob patterns	Restrict to certain directories or file types
Command substring	Catch dangerous command patterns
Tool category	Treat all file tools similarly

Pre-events (UserPromptSubmit, PreToolUse) are gates - they can stop actions. Post-events are observers - they can only watch and record.

Cross-Platform Event Support

Different runtimes support different events:

Event	Claude Code	Cline	Opencode
SessionStart	✓	✓	✓
SessionEnd	✓	✓	✓
UserPromptSubmit	✓	✓	-
PreToolUse	✓	✓	✓
PostToolUse	✓	✓	✓
PermissionRequest	✓	-	-

The core tool events (Pre/PostToolUse) are universal. Input interception varies by runtime.