HookApp

The main application class for registering and running hook handlers.

HookApp

Bases: HandlerRegistry

Main application for registering and running hook handlers.

__init__

__init__(
    state_dir: str | None = None,
    log_dir: str | None = None,
    log_level: str = "INFO",
    task_backend: BaseBackend | None = None,
)

Initialize HookApp.

Parameters:

Name	Type	Description	Default
state_dir	str | None	Directory for persistent state files	None
log_dir	str | None	Directory for JSONL event logs (enables built-in logging)	None
log_level	str	Logging verbosity	'INFO'
task_backend	BaseBackend | None	Backend for background tasks (default: InMemoryBackend)	None

run

run(
    stdin: IO[str] | None = None,
    stdout: IO[str] | None = None,
) -> None

Run the hook app, processing stdin and writing to stdout.

Parameters:

Name	Type	Description	Default
stdin	IO[str] | None	Input stream (default: sys.stdin)	None
stdout	IO[str] | None	Output stream (default: sys.stdout)	None

include

include(blueprint: Blueprint) -> None

Include a blueprint's handlers.

Parameters:

Name	Type	Description	Default
blueprint	Blueprint	Blueprint to include	required

middleware

middleware(func: Callable[..., Any]) -> Callable[..., Any]

Decorator to register middleware.

Middleware wraps all handler calls and can: - Execute code before/after handlers - Short-circuit by returning a response - Modify events or responses

Example

@app.middleware def timing(event, call_next): start = time.time() response = call_next(event) print(f"Took {time.time() - start:.3f}s") return response

Blueprint

Composable handler groups for organizing hooks.

Blueprint

Bases: HandlerRegistry

Composable collection of hook handlers.

Use blueprints to organize handlers into logical groups that can be included in the main HookApp.

Example

security = Blueprint("security")

@security.pre_tool("Bash") def no_sudo(event): if "sudo" in event.command: return deny("sudo not allowed")

app = HookApp() app.include(security)

__init__

__init__(name: str)

Initialize Blueprint.

Parameters:

Name	Type	Description	Default
name	str	Name for this blueprint (for debugging)	required