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

is_legacy_hooks_document

Return whether data looks like the legacy list-shaped hooks document.

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.

Legacy dotted-event migration helpers for Hooks v2 configuration.

Legacy documents are converted by the loader so lifecycle call sites dispatch only canonical events and do not duplicate old dotted-event hooks.

_LEGACY_EVENT_MAP is the authoritative list of legacy events migrated into Hooks v2. Events absent from it (e.g. permission.request, tool.use, tool.result) are dropped from the migrated configuration only; they continue to fire through the legacy dispatcher (deepagents_code.hooks.legacy) until the legacy system is removed.

Menu

migration

Attributes

Functions

Classes