Hooks API

For usage patterns and examples see Hooks guide. This page covers the type signatures.

HookMatcher

Pairs an optional regex filter with one or more async callbacks.

from agentix import HookMatcher

HookMatcher(
    matcher: str | None,         # regex matched against the event key (tool name for tool events)
                                 # None = match all invocations
    hooks: list[Callable],       # async callbacks, called in order
    timeout: float = 60.0,       # per-callback timeout in seconds; 0 = no timeout
)

SyncHookJSONOutput

Return value from hook callbacks to control behavior. Import as SyncHookJSONOutput (the concrete class) or use HookJSONOutput as the type annotation (union alias).

from agentix import SyncHookJSONOutput

SyncHookJSONOutput(
    continue_: bool = True,          # False stops the hook chain for this event
    decision: str | None = None,     # "allow" | "block" — PreToolUse only
    updated_output: str | None = None,     # replace tool result — PostToolUse only
    additional_context: str | None = None, # append to tool result — PostToolUse only
    suppressOutput: bool = False,    # hide event from session log
    reason: str | None = None,       # explanation recorded in logs
    stopReason: str | None = None,   # custom stop reason when continue_=False
    systemMessage: str | None = None,# inject a system message into the conversation
)

HookJSONOutput (exported from agentix) is the union SyncHookJSONOutput | AsyncHookJSONOutput. Instantiate SyncHookJSONOutput directly in callbacks.

Hook context types

Event	Context Type	Key hook_input fields
PreToolUse	ToolHookContext	tool_name, tool_input, tool_use_id, session_id
PostToolUse	ToolHookContext	tool_name, tool_input, tool_result, session_id
PostToolUseFailure	ToolHookContext	tool_name, error, session_id
UserPromptSubmit	PromptHookContext	prompt, expanded_prompt, slash_command, session_id
Stop	StopHookContext	reason, final_text, session_id
SubagentStart	SubagentHookContext	child_name, session_id
SubagentStop	SubagentHookContext	child_name, session_id
PreCompact	CompactHookContext	current_count, session_id
Notification	NotificationHookContext	message, level, session_id
PermissionRequest	PermissionHookContext	tool_name, decision, session_id

ToolHookContext also carries tool_name and tool_use_id as typed attributes (in addition to hook_input).

Typed context attributes

from agentix import (
    ToolHookContext,        # .tool_name, .tool_use_id
    PromptHookContext,      # .session_id
    StopHookContext,        # .session_id, .stop_reason
    SubagentHookContext,    # .child_name
    CompactHookContext,     # (base only)
    NotificationHookContext,# (base only)
    PermissionHookContext,  # .tool_name
)

Imports

from agentix import (
    HookMatcher,
    HookJSONOutput,
    SyncHookJSONOutput,
    AsyncHookJSONOutput,
    ToolHookContext,
    PromptHookContext,
    StopHookContext,
    SubagentHookContext,
    CompactHookContext,
    NotificationHookContext,
    PermissionHookContext,
)

Built-in hook helpers

from agentix.hooks import logging_hook_matchers, metrics_hook_matchers

# Structured console logging for all events
options = AgentixAgentOptions(hooks=logging_hook_matchers())

# Call counter — increments counter[tool_name] on PreToolUse
counts: dict[str, int] = {}
options = AgentixAgentOptions(hooks=metrics_hook_matchers(counts))

Hook timeout behavior

Callbacks that exceed their timeout are cancelled and logged as a warning. The agent run continues as if the hook returned None.

HookMatcher(matcher=None, hooks=[slow_hook], timeout=10.0)  # 10s limit
HookMatcher(matcher=None, hooks=[my_hook],   timeout=0)     # no timeout