Each distinct legacy event name becomes its own matcher group so a single entry subscribed to both session.start and user.prompt still runs once per mapped name with the matching reconstructed stdin payload.

function

project_hooks_path

Return the project-scoped hooks configuration path.

function

user_hooks_path

Return the user-scoped hooks configuration path.

function

load_hooks_config

Load, validate, merge, and hash Hooks v2 configuration.

function

compute_snapshot_id

Return the canonical SHA-256 snapshot id for config.

function

canonical_hooks_bytes

Serialize configuration into a stable byte representation.

class

CommandHandlerSpec

Configuration for a synchronous command hook.

Currently only type: "command" is supported. Additional handler types remain a discriminated-union extension point and are rejected until implemented.

When argv is set, the runner launches via create_subprocess_exec and ignores shell metacharacters in command.

argv is a temporary legacy-migration compatibility field. Remove it with hooks.legacy and hooks.migration after September 1, 2026.

class

HooksConfig

Top-level configuration grouped by hook event.

class

MatcherGroup

A matcher and its ordered hook handlers.

class

HookDiagnostic

Structured diagnostic produced while processing a hook.

class