Events

Event types for tools and lifecycle hooks.

Base Event

BaseEvent

Bases: BaseModel

Base model for all Claude Code hook events.

All events share these common fields from the hook input.

session_id instance-attribute

session_id: str

cwd instance-attribute

cwd: str

permission_mode class-attribute instance-attribute

permission_mode: str | None = None

transcript_path class-attribute instance-attribute

transcript_path: str | None = None

hook_event_name instance-attribute

hook_event_name: str

Tool Events

ToolEvent

Bases: BaseEvent

Base class for tool-related events (PreToolUse, PostToolUse).

tool_name instance-attribute

tool_name: str

tool_input instance-attribute

tool_input: dict[str, Any]

tool_use_id instance-attribute

tool_use_id: str

tool_response class-attribute instance-attribute

tool_response: dict[str, Any] | None = None

Bash

Bases: ToolEvent

Bash tool event with typed accessors.

command property

command: str

The bash command to execute.

description property

description: str | None

Optional description of the command.

timeout property

timeout: int | None

Optional timeout in milliseconds.

Write

Bases: ToolEvent

Write tool event.

file_path property

file_path: str

Path to file being written.

content property

content: str

Content to write.

Edit

Bases: ToolEvent

Edit tool event.

file_path property

file_path: str

Path to file being edited.

old_string property

old_string: str

String to replace.

new_string property

new_string: str

Replacement string.

Read

Bases: ToolEvent

Read tool event.

file_path property

file_path: str

Path to file being read.

offset property

offset: int | None

Optional line offset.

limit property

limit: int | None

Optional line limit.

Grep

Bases: ToolEvent

Grep tool event.

pattern property

pattern: str

Search pattern.

path property

path: str | None

Path to search in.

Glob

Bases: ToolEvent

Glob tool event.

pattern property

pattern: str

Glob pattern.

path property

path: str | None

Base path.

Task

Bases: ToolEvent

Task (subagent) tool event.

prompt property

prompt: str

Task prompt.

description property

description: str

Task description.

WebSearch

Bases: ToolEvent

WebSearch tool event.

query property

query: str

Search query.

WebFetch

Bases: ToolEvent

WebFetch tool event.

url property

url: str

URL to fetch.

prompt property

prompt: str

Prompt for processing.

Lifecycle Events

Stop

Bases: BaseEvent

Stop event - main agent finished responding.

stop_hook_active class-attribute instance-attribute

stop_hook_active: bool = False

SubagentStop

Bases: BaseEvent

SubagentStop event - subagent finished responding.

stop_hook_active class-attribute instance-attribute

stop_hook_active: bool = False

SessionStart

Bases: BaseEvent

SessionStart event - session begins or resumes.

source instance-attribute

source: str

SessionEnd

Bases: BaseEvent

SessionEnd event - session ends.

reason instance-attribute

reason: str

PreCompact

Bases: BaseEvent

PreCompact event - before context compaction.

trigger instance-attribute

trigger: str

custom_instructions class-attribute instance-attribute

custom_instructions: str | None = None

UserPromptSubmit

Bases: BaseEvent

UserPromptSubmit event - user submits a prompt.

prompt instance-attribute

prompt: str

Notification

Bases: BaseEvent

Notification event - notification sent.

message instance-attribute

message: str

notification_type instance-attribute

notification_type: str