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_global_hook ¶

remove_global_hook(name)

Remove a global hook by name.

remove_room_hook ¶

remove_room_hook(room_id, name)

Remove a room hook by name.

has_hooks ¶

has_hooks(trigger=None)

Whether a hook is registered — for trigger, or for any trigger at all.

O(1) either way: a set lookup, or the set's emptiness. The framework skips the work only a hook would consume when nothing is listening — the context built for BEFORE_DELIVER, the room history loaded for the inbound pipeline — so it runs a handful of times per message, never per hook. Global and room hooks alike are in the index; identity hooks live in the framework's own registry, and a caller that needs both asks both.

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)