Core enums
Rewrite is not a capability. Runtime responses accept only an optional
decision and reject unknown fields, including legacy patches payloads.
Runtime families
Command and HTTP payloads are bounded by
payload_max_bytes (128 KiB by
default). Hook timeouts default to 5000 ms. Foreground runtime failures fail
closed through typed hook errors. Background hooks are non-blocking: saturation
can skip or drop their work, and their later failures do not retroactively fail
the foreground operation.
Payload highlights
External command/HTTP serialization also adds
prompt and error text
projections. They are serialize-only convenience fields and are never accepted
back as authority.
HookToolCall contains tool_use_id, name, typed arguments, and optional
ToolProvenance. HookToolResult contains the same identity/provenance plus
ordered content_blocks and is_error; its external wire form adds a derived
content text projection. HookLlmResponse.server_tool_content projects
provider-native server-tool blocks, such as web search, into typed kinds.
Decisions and ordering
Observe hooks never deny. Guardrail hooks may return Allow or typed
Deny { hook_id, reason_code, message, payload }. Foreground hooks run by
ascending priority and then registration order. The first denial short-circuits
remaining foreground and background hooks.
Background hooks are observational. Every background hook must have Observe
capability or configuration validation rejects it, regardless of hook point.
The six committed-fact points are always observe-only and reject Guardrail
capability in either execution mode. Their session-scoped dispatcher does not
join hook execution to the observed outcome, owns all spawned tasks, reaps
completed task handles, and aborts in-flight work on drop. Hook decisions and
runtime failures therefore cannot alter or delay committed facts.
Committed observation payloads
HookInvocation.observation is a tagged HookObservation union:
These payloads project exact committed receipts/events. Implementations never
re-read idempotency rows or reconstruct peer identity from display strings.
Event streams remain the ordered and replay-aware transport beneath this
reaction API.
Post-commit hooks are process-local best-effort reactions. Recovery may lose or
replay an invocation around a crash boundary; use event streams for durable
delivery and
interaction_id as the idempotency key for completion side
effects.
Failure reasons
Hook failure events carry one typedHookFailureReason:
Agent events are
hook_started, hook_completed, hook_failed, and
hook_denied.