Hooks
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.
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
sessionboundaries, the built-inadmin_receiptand the Catalog kindsscriptandwebhook. Not built: the proposed boundaries,herdr_plugin,pi_extension, a digest pin on a consumer entry, andhttpswebhooks. - 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_consumerCatalog 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:
{
"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)
# <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:
[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_invalidand nothing is enqueued. - The worker. A delivery worker per consumer runs the consumer and enforces
deadline_ms. Ascriptthat outlives it is killed with its process group (timed_out). Awebhookthat does not answer in time istimed_out. - At most once. v1 has no retry. A consumer that needs every event reads
sequenceand 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.