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 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.