---
title: "Hooks"
description: "Proposed (ADR 0059): lifecycle hooks; a boundary (session.start.after and session.end.after live with the built-in admin_receipt; invocation.arm.after, brain.turn.settled.after and readiness.changed.after proposed) hands a typed event with ids, closed reasons and ms only to consumers the user supplies as hook_consumer Catalog entries (script on stdin, signed webhook; herdr plugin and pi extension later), registered under [lifecycle.observe]; one non-blocking enqueue at the commit, a deadline per delivery, at most once, one receipt per attempt with a closed disposition; Gate and Mutate only after the authority review."
type: "living"
source: "docs/contracts/hooks.v1.md"
verified: "2026-11-14"
group: "Contracts"
---

> **Living doc**, checked against the code 2026-11-14

hooks.v1 — a lifecycle boundary's typed event, from the subsystem that commits it to a consumer the user supplies

- Status: **accepted**, version 1.0 (ADR 0059 §3). Live: the two `session` boundaries, the built-in `admin_receipt`
  and the Catalog kinds `script` and `webhook`. Not built: the proposed boundaries, `herdr_plugin`, `pi_extension`,
  a digest pin on a consumer entry, and `https` webhooks.
- Scope: a **boundary** is a named transition that one subsystem commits. After the commit, the subsystem hands a
  typed event to each **consumer** and records one receipt per attempt. A consumer never changes, delays or reorders
  the transition it observes.
- The plugin point: a `hook_consumer` Catalog entry and one line in a loadout's `[lifecycle.observe]`.

## Classes

| class | when it runs | what it may return | v1 |
|---|---|---|---|
| `observe` | after the commit | nothing (its exit status or HTTP status is recorded only) | yes |
| `gate` | before the commit, under a fail-closed deadline | `allow`, `refuse {reason}` or `abstain`; it can only narrow | not built |
| `mutate` | after the commit, as its own owned effect | a settlement and a cleanup receipt | not built |

## Boundaries

A boundary id is `<scope>.<transition>.<before|after>`. The list is closed and grows only by a minor version. Only
the two `live` rows fire; a loadout or a manifest that names a `proposed` row is refused.

| boundary | class | owner | fires when | payload | state |
|---|---|---|---|---|---|
| `session.start.after` | observe | the voice connection | the initial `session_started` was sent with the session's resources committed | ids only | live (`admin_receipt`, `script`, `webhook`) |
| `session.end.after` | observe | the voice connection | a client's `end_session` closed with outcome `succeeded` and `session_ended` was sent | ids only | live (`admin_receipt`, `script`, `webhook`) |
| `invocation.arm.after` | observe | `TurnManager` | an arm was admitted (the detection or the STT alias), after one arm-transition owner exists | `armed_request_id`, `source` | proposed |
| `brain.turn.settled.after` | observe | the gateway's brain turn | the turn's brain ownership was released or quarantined | `turn_id`, `terminal`, `legs_ms` | proposed |
| `readiness.changed.after` | observe | each readiness owner | a `readiness` transition | `owner`, `state`, `reason`, `generation` | proposed |
| `session.start.before` | gate | the voice connection | after the request is validated, before composition is resolved | ids only | proposed |

A transport loss, a gateway stop, a radio rotation, the spoken restart and a model rebind do not fire
`session.end.after`.

## The event (to a consumer)

One JSON object, at most 4 KiB:

```json
{
  "schema": "vulpine.hooks/v1",
  "version": "1.0",
  "boundary": "session.end.after",
  "class": "observe",
  "delivery_id": "6f1c0a52-4a43-4f0e-9d0b-0d8a2b1e5c11",
  "invocation_id": "b0e8f3a4-1c2d-4e5f-8a9b-0c1d2e3f4a5b",
  "owner_component": "gateway.observe.session_end",
  "occurred_at_ms": 1793480000000,
  "sequence": 42,
  "session_id": "3d9b7c1e-2f4a-4b6c-8d0e-1f2a3b4c5d6e",
  "continuity_id": "operator:laptop:7",
  "reason": "end_session",
  "payload": {}
}
```

| field | type | rule |
|---|---|---|
| `schema` | string | always `vulpine.hooks/v1` |
| `version` | string | the minor the gateway speaks (`1.0`); a consumer ignores fields it does not know |
| `boundary` | string | one row of the table above |
| `class` | string | `observe` in v1 |
| `delivery_id` | uuid | unique per attempt; also the webhook's `webhook-id` |
| `invocation_id` | uuid | one per boundary firing, shared by every consumer of it |
| `owner_component` | string | the trace component of the owner |
| `occurred_at_ms` | integer | the commit's wall time, unix ms |
| `sequence` | integer | monotonic per consumer within one gateway process; a gap means a drop |
| `session_id`, `continuity_id`, `armed_request_id`, `turn_id`, `output_generation` | string, optional | present only when the boundary has that identity, never empty |
| `reason` | string, optional | the boundary's closed reason enum (`end_session` on `session.end.after`) |
| `payload` | object | the boundary's typed payload, ids, closed values and ms only |

An event never carries words, transcripts, prompts, brain output, file paths, raw audio, credentials, the owner's
capability or lease, the loadout's source, or a household name.

## Consumer kinds

| kind | how it is called | its answer | v1 |
|---|---|---|---|
| `admin_receipt` | built-in: one bounded row in the Admin Events store, one `try_lock` attempt | none | live |
| `script` | the entry's executable, a clean environment (`PATH=/usr/bin:/bin`, `VULPINE_HOOK_STATE_DIR` naming its own folder in the gateway's state folder, and its one named secret); the event as one line on stdin, then stdin closes; cwd is the entry's root; its own process group, killed whole at the deadline | the exit status, recorded (0 is `delivered`); stdout and stderr are read up to 4 KiB for the receipt's diagnostics and never parsed | built |
| `webhook` | one `POST` of the event over `http` to the manifest's URL (loopback, or a host on the gateway's `[hooks] webhook_hosts` list, which needs `network` declared), signed with Standard Webhooks (`webhook-id` is the `delivery_id`, `webhook-timestamp`, `webhook-signature`), the `whsec_` secret read at delivery from the environment variable `secret_env` names | the HTTP status: 2xx is `delivered` | built |
| `herdr_plugin` | one action of a linked herdr plugin, as a gateway-owned operation (ADR 0012) | the operation's receipt | not built |
| `pi_extension` | an event to the session's own Pi extensions over the RPC stream | none | not built |

## The manifest (`hook_consumer` Catalog entry)

```toml
# <catalog root>/hooks/porch-light/consumer.toml
id = "porch-light"
kind = "webhook"
hooks = ">= 1.0, < 2"                      # the contract range it speaks
boundaries = ["session.end.after"]
url = "http://127.0.0.1:8123/api/webhook/fox9-listening"
secret_env = "VULPINE_HOOK_PORCH_LIGHT_SECRET"
deadline_ms = 2000                         # the default; 1 to 10000
capabilities = ["house"]                   # ADR 0050 §2's closed set
```

Every field is closed: an unknown field refuses the manifest. The entry lives at `catalog/hooks/<id>/consumer.toml`
under the runtime root, and its `id` matches its folder. `boundaries` lists at least one live boundary. A `webhook`
needs `url` and `secret_env`. A `script` has `command = "bin/on-event"`, a file inside the entry, in place of `url`;
its `secret_env` is optional. `capabilities` takes values from the closed set `network`, `files`, `write`, `house`,
`messaging`, `agents`, `screen` and `memory`. Installing an entry binds nothing. This build does not pin an entry by
digest.

## Registration

The loadout binds consumers to boundaries. The single-value form is valid:

```toml
[lifecycle.observe]
"session.start.after" = "admin_receipt"
"session.end.after" = ["admin_receipt", "catalog:porch-light"]
```

A consumer is `admin_receipt` or `catalog:<id>`. A boundary lists one to 4 consumers, each once. They are enqueued
in the listed order and run independently. An absent boundary has no consumers.

Each Catalog consumer is admitted, and its delivery worker started, when a session binds. `[hooks] user_consumers`
(default `true`) is the master switch: when `false`, no Catalog consumer is admitted or fires, and a loadout that
names one still binds. The Admin's Hook consumers card has a switch per consumer, kept in
`<state>/hook-consumers.json`. It applies at once: a switched-off consumer's attempts are `dropped_unavailable`.

## Delivery

- **At the commit.** The owner captures the boundary's identity and makes one non-blocking enqueue per consumer onto
  that consumer's bounded queue (capacity 64). It never awaits, never takes a contended lock, and never spawns on the
  connection task. The target cost is under 0.05 ms.
- **The identity.** After the publication, the connection compares the identity it captured at the commit with its
  current one, then enqueues. A changed identity is `dropped_invalid` and nothing is enqueued.
- **The worker.** A delivery worker per consumer runs the consumer and enforces `deadline_ms`. A `script` that
  outlives it is killed with its process group (`timed_out`). A `webhook` that does not answer in time is
  `timed_out`.
- **At most once.** v1 has no retry. A consumer that needs every event reads `sequence` and treats a gap as a drop.

## The receipt

One per attempt, in the trace (one `hook_delivery` row in the gateway's `hooks.jsonl` trace) and the Admin (counts by
disposition and the newest eight per consumer), never with the payload:

| field | values |
|---|---|
| `delivery_id`, `invocation_id`, `boundary`, `consumer` | as in the event |
| `disposition` | `delivered`, `dropped_busy` (queue full), `dropped_invalid` (identity changed or the event failed its own bounds), `dropped_unavailable` (consumer off, missing or unqualified), `timed_out`, `failed` (non-zero exit, non-2xx, connection error), `rejected_store` (`admin_receipt` only) |
| `ms` | wall time of the attempt |
| `detail` | at most 256 characters of diagnostics, no payload |

## Errors

The loadout parse refuses an unknown boundary, a consumer name that is neither `admin_receipt` nor `catalog:<id>`, an
empty list, a consumer listed twice, and more than 4 consumers (`too_many_consumers`).

A Catalog consumer is admitted when a session binds. Its refusal names one reason: `unknown_consumer` (no such
entry), `boundary_not_declared`, `contract_unsupported`, `capability_undeclared` (a webhook off loopback without
`network`), `manifest_invalid` or `transport_not_allowed` (not `http`, or a host off loopback that `[hooks]
webhook_hosts` does not list). Each refuses the bind as `loadout_resolution_failed`. A delivery's failure is a receipt
and never an error of the session.

## The sample

`catalog/hooks/session-log` is a `script` consumer on both live boundaries: `bin/on-event` appends each event line to
`session-log.jsonl` in `VULPINE_HOOK_STATE_DIR`. A loadout turns it on with `"session.start.after" =
["admin_receipt", "catalog:session-log"]` and the same for `"session.end.after"`. The Admin's Hook consumers card
shows its deliveries and switches it off.

## Compatibility

Versioned under ADR 0059 §5. A minor may add a boundary, a consumer kind, an optional event field or a reason value,
and may widen a bound. It never removes or renames a boundary or a field, never changes when a boundary fires, and
never adds a required field. A deprecated boundary keeps firing for two minor releases or 90 days, whichever is
longer.
