Hooks¶

HookEngine ¶

HookEngine()

Manages global and per-room hook registration and execution.

register ¶

register(hook)

Register a global hook.

add_room_hook ¶

add_room_hook(room_id, hook)

Register a hook for a specific room.

remove_room_hook ¶

remove_room_hook(room_id, name)

Remove a room hook by name.

run_sync_hooks `async` ¶

run_sync_hooks(room_id, trigger, event, context, *, skip_event_filter=False)

Run sync hooks sequentially. Stops on block, passes modified events.

Parameters:

Name	Type	Description	Default
`room_id`	`str`	The room ID to run hooks for.	required
`trigger`	`HookTrigger`	The hook trigger type.	required
`event`	`RoomEvent \| Any`	The event to pass to hooks. For voice hooks, this may be a VoiceSession or str instead of RoomEvent.	required
`context`	`RoomContext`	The room context.	required
`skip_event_filter`	`bool`	If True, skip channel-based event filtering. Use this for voice hooks where event is not a RoomEvent.	`False`

run_async_hooks `async` ¶

run_async_hooks(room_id, trigger, event, context, *, skip_event_filter=False, name_prefix=None, exclude_name_prefix=None)

Run async hooks concurrently. Errors are logged, never raised.

Finds hooks regardless of their declared execution mode so that hooks registered with the default SYNC execution still fire for triggers that are only invoked asynchronously (e.g. AFTER_BROADCAST, lifecycle hooks, voice hooks).

Parameters:

Name	Type	Description	Default
`room_id`	`str`	The room ID to run hooks for.	required
`trigger`	`HookTrigger`	The hook trigger type.	required
`event`	`RoomEvent \| Any`	The event to pass to hooks. For voice hooks, this may be a VoiceSession or str instead of RoomEvent.	required
`context`	`RoomContext`	The room context.	required
`skip_event_filter`	`bool`	If True, skip channel-based event filtering. Use this for voice hooks where event is not a RoomEvent.	`False`
`name_prefix`	`str \| None`	Only run hooks whose name starts with this prefix.	`None`
`exclude_name_prefix`	`str \| None`	Skip hooks whose name starts with this prefix.	`None`

HookRegistration `dataclass` ¶

HookRegistration(trigger, execution, fn, priority=0, name='', timeout=30.0, channel_types=None, channel_ids=None, directions=None)

A registered hook function.

Attributes:

Name	Type	Description
`trigger`	`HookTrigger`	When the hook fires (BEFORE_BROADCAST, AFTER_BROADCAST, etc.)
`execution`	`HookExecution`	SYNC (can block/modify) or ASYNC (fire-and-forget)
`fn`	`SyncHookFn \| AsyncHookFn`	The hook function
`priority`	`int`	Lower numbers run first (default: 0)
`name`	`str`	Optional name for logging and removal
`timeout`	`float`	Max execution time in seconds (default: 30.0)
`channel_types`	`set[ChannelType] \| None`	Only run for events from these channel types (None = all)
`channel_ids`	`set[str] \| None`	Only run for events from these channel IDs (None = all)
`directions`	`set[ChannelDirection] \| None`	Only run for events with these directions (None = all)