events

events

BaseHookEvent dataclass

BaseHookEvent(_raw: dict[str, Any], ctx: HookContext)

Base class for all hook events, providing access to raw payload, context, and convenience methods.

tasks cached property

tasks: Tasks

The live task list for this session, read from Claude Code's native task store.

Unlike transcript-derived task_ops(), this reflects updates made by subagents, teammates, or resumed sessions, and is empty when the session has no task store — it never falls back to another session's tasks.

warn

warn(
    *parts: str | tuple[str, object] | object,
) -> HookResult

Emit a warning whose parts are auto-rendered and joined with newlines.

Each part is rendered by form: a plain str passes through verbatim; a (label, value) tuple becomes "{label}: {json}" with value JSON-encoded; any other object is JSON-encoded directly. Rendered parts are joined with "\n".

Parameters:

Name	Type	Description	Default
*parts	str | tuple[str, object] | object	Warning fragments, each a str, a (label, value) tuple, or any JSON-serializable object.	()

Returns:

Type	Description
HookResult	A warn :class:HookResult carrying the joined message.

ToolHookEvent dataclass

ToolHookEvent(_raw: dict[str, Any], ctx: HookContext)

Bases: BaseHookEvent

Event for tool-related hooks, adding tool name, input, command, and file access.

PreToolUseEvent dataclass

PreToolUseEvent(_raw: dict[str, Any], ctx: HookContext)

Bases: ToolHookEvent

Fires before a tool is executed. Return a block result to prevent execution.

PostToolUseEvent dataclass

PostToolUseEvent(_raw: dict[str, Any], ctx: HookContext)

Bases: ToolHookEvent

Fires after a tool completes successfully, with access to the tool response.

PostToolUseFailureEvent dataclass

PostToolUseFailureEvent(
    _raw: dict[str, Any], ctx: HookContext
)

Bases: ToolHookEvent

Fires after a tool fails, providing the error message and interrupt status.

UserPromptSubmitEvent dataclass

UserPromptSubmitEvent(
    _raw: dict[str, Any], ctx: HookContext
)

Bases: BaseHookEvent

Fires when the user submits a prompt, before the agent processes it.

StopEvent dataclass

StopEvent(_raw: dict[str, Any], ctx: HookContext)

Bases: BaseHookEvent

Fires when the agent is about to stop. Return a block result to prevent stopping.

SubagentStopEvent dataclass

SubagentStopEvent(_raw: dict[str, Any], ctx: HookContext)

Bases: BaseHookEvent

Fires when a subagent finishes. Provides agent_type for filtering.

SubagentStartEvent dataclass

SubagentStartEvent(_raw: dict[str, Any], ctx: HookContext)

Bases: BaseHookEvent

Fires when a subagent is launched. Provides agent_type for filtering.

PreCompactEvent dataclass

PreCompactEvent(_raw: dict[str, Any], ctx: HookContext)

Bases: BaseHookEvent

Fires before context compaction, providing the trigger and custom instructions.

NotificationEvent dataclass

NotificationEvent(_raw: dict[str, Any], ctx: HookContext)

Bases: BaseHookEvent

Fires on system notifications, providing message, title, and notification type.