Hooks
Intercept named runtime events, inspect the payload, and emit a JSON patch that CompozyOS applies in a deterministic order.
Hooks are the policy and observability layer between runtime events and the actions that follow. A declaration binds a named event to an executor; the executor returns a JSON patch; CompozyOS applies patches in declaration order and records the outcome on the session event stream.
In this section
Hook event catalog
Use this page for the complete event list, payload schemas, patch schemas, and which events support synchronous mutation.
Hook declaration format
Use this page when authoring hooks: matchers, subprocess executors, ordering, and execution behavior.
Management surfaces
Hooks are agent-manageable for mutable sources. The compozy__hooks toolset and the parallel
compozy hooks CLI both call the same hook normalization, validation, and persistence pipeline.
| Surface | Read tools | Mutation tools | CLI parity |
|---|---|---|---|
| Catalog | compozy__hooks_list, compozy__hooks_info | — | compozy hooks list, compozy hooks info |
| History | compozy__hooks_events, compozy__hooks_runs | — | compozy hooks events, compozy hooks runs |
| Declaration | — | compozy__hooks_create, compozy__hooks_update, compozy__hooks_delete | overlay edits in config.toml plus daemon reload |
| Lifecycle | — | compozy__hooks_enable, compozy__hooks_disable | overlay edits plus daemon reload |
Source-owned hooks (extension manifests, skill metadata, native daemon hooks) stay structurally
immutable through agent tools. Mutating tools require approval and reject secret-bearing
executor environments with deterministic codes such as HOOK_SOURCE_IMMUTABLE,
HOOK_SECRET_INPUT_FORBIDDEN, HOOK_VALIDATION_FAILED, and HOOK_APPROVAL_REQUIRED.