Validated Hooks v2 configuration loading, merging, and hashing.
Precedence (highest first, earlier in reduction order):
{project_root}/.deepagents/hooks.json~/.deepagents/hooks.json (or config_dir/hooks.json in tests)hooks.json documents contributed by enabled pluginsSources are concatenated per event. Precedence is reduction order, not execution order: every matching handler runs, and the first one that stops processing decides the event.
A minimal v2 config with one event and one command handler:
{"hooks": {"Notification": [{"matcher": "agent_completed",
"hooks": [{"type": "command", "command": "bash notify.sh"}]}]}}Hook stdin payloads are the Claude-compatible envelope (hook_event_name +
session_id + event-specific fields), defined in
deepagents_code.hooks.models.wire.
Legacy list-shaped documents are migrated only for events whose lifecycle semantics genuinely match Hooks v2.
Provenance for groups handled without it, adding no origin or env overlay.
Return whether data looks like the legacy list-shaped hooks document.
Convert legacy dotted-event hook entries into Hooks v2 configuration.
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.
Return the project-scoped hooks configuration path.
Return the user-scoped hooks configuration path.
Load, validate, merge, and hash Hooks v2 configuration.
Return the canonical SHA-256 snapshot id for config.
Serialize configuration into a stable byte representation.
Decode one hooks document and fingerprint the exact bytes read.
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.
Top-level configuration grouped by hook event.
A matcher and its ordered hook handlers.
Origin of the matcher groups contributed by one hooks document.
A project or user hooks file, which defines no variables.
Origin and environment for groups one enabled plugin contributed.
Validated configuration plus load diagnostics and source paths.