> ## Documentation Index > Fetch the complete documentation index at: https://docs.rkat.ai/llms.txt > Use this file to discover all available pages before exploring further. # Hooks reference > Low-level hook surface reference: hook points, capabilities, execution modes, and payload fields. Use this page when you need exact hook vocabulary and structure rather than a procedural walkthrough. ## Core enums | Type | Values | | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `HookPoint` | `RunStarted`, `PreLlmRequest`, `PreToolExecution`, `TurnBoundary`, `PostLlmResponse`, `PostToolExecution`, `RunCompleted`, `RunFailed`, `RuntimeInputAccepted`, `RuntimeInputRejected`, `RuntimeInputDeduplicated`, `PeerIngressCommitted`, `PeerEgressCommitted`, `InteractionCompleted` | | `HookCapability` | `Observe`, `Guardrail` | | `HookExecutionMode` | `Foreground`, `Background` | `Rewrite` is not a capability. Runtime responses accept only an optional `decision` and reject unknown fields, including legacy `patches` payloads. ## Runtime families | Runtime | Input/output contract | | ---------- | ---------------------------------------------------------------------------------------------- | | in-process | Registered async Rust handler receives `HookInvocation` and returns `RuntimeHookResponse`. | | command | Invocation JSON on stdin, response JSON on stdout. Non-zero exit is a typed execution failure. | | HTTP | Invocation JSON in a POST body, response JSON in the body. | 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 | Field | Type | Hook point | | ----------------------------- | ------------------------- | ------------------- | | `point`, `session_id` | `HookPoint`, `SessionId` | all | | `turn_number` | `Option` | most points | | `prompt_input` | `Option` | `RunStarted` | | `error_report`, `error_class` | typed failure projections | `RunFailed` | | `llm_request` | `HookLlmRequest` | `PreLlmRequest` | | `llm_response` | `HookLlmResponse` | `PostLlmResponse` | | `tool_call` | `HookToolCall` | `PreToolExecution` | | `tool_result` | `HookToolResult` | `PostToolExecution` | 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: | Variant | Typed payload highlights | | ---------------------------- | ------------------------------------------------------------------------------------------------------ | | `runtime_input_accepted` | input id, runtime input kind, resolved handling mode | | `runtime_input_rejected` | attempted input id, runtime input kind, typed rejection reason | | `runtime_input_deduplicated` | attempted input id, runtime input kind, existing committed input id | | `peer_ingress_committed` | accepted comms kind, canonical peer, request id, sender taint declaration | | `peer_egress_committed` | egress kind, canonical peer id, envelope id, strongest typed delivery outcome, interaction correlation | | `interaction_completed` | interaction id, result text, optional structured output | 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 typed `HookFailureReason`: | Variant | Fields | | ------------------------ | ------------ | | `timeout` | `timeout_ms` | | `execution_failed` | `message` | | `config_invalid` | `message` | | `observe_only_violation` | none | Agent events are `hook_started`, `hook_completed`, `hook_failed`, and `hook_denied`. ## See also * [Hooks guide](/guides/hooks) * [Examples: Hooks](/examples/hooks)