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 expresses observational intent, but is not by itself an enforced deny
barrier at ordinary foreground hook points: the current DefaultHookEngine
honors a foreground Deny even when the hook’s capability is Observe.
Use Guardrail to declare intended Allow / typed
Deny { hook_id, reason_code, message, payload } behavior. 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 engine suppresses decisions from Background mode; this is distinct from
the capability label alone.
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.