Hooks guide

Hooks let you run custom logic at defined points in the agent lifecycle and react to committed runtime, session, and comms facts. Use them for approval workflows, responsive UI, audit logging, telemetry, content filtering, or typed denials.

This page is the task-first guide. For the low-level type and payload inventory, see Hooks reference.

What this guide is for

Use this guide when you want to:

add approval gates
react to committed input and peer-delivery outcomes
update application UI from typed interaction completions
log or audit agent behavior
block unsafe tool inputs or outputs
choose between in-process, command, and HTTP hook runtimes

Hook points

Fourteen extension points are available:

HookPoint	Classification	When it fires
`RunStarted`	pre	Start of `Agent::run()`, before any LLM call
`PreLlmRequest`	pre	Before each LLM streaming call
`PreToolExecution`	pre	Before each individual tool call is dispatched
`TurnBoundary`	pre	Between turns, after all tool results are collected
`PostLlmResponse`	post	After the LLM response is received
`PostToolExecution`	post	After each tool execution completes
`RunCompleted`	post	After a successful run completes
`RunFailed`	post	After a run fails with an error
`RuntimeInputAccepted`	post-commit, observe-only	After runtime and session authority commit an accepted input
`RuntimeInputRejected`	terminal, observe-only	After runtime terminally rejects an input without committing admission
`RuntimeInputDeduplicated`	post-commit, observe-only	After an idempotent submission resolves to an existing committed input
`PeerIngressCommitted`	post-commit, observe-only	After runtime commits an accepted typed peer input
`PeerEgressCommitted`	post-commit, observe-only	After a peer send returns a successful typed delivery receipt
`InteractionCompleted`	post-commit, observe-only	After an interaction terminal is durably published

Classification is determined by the is_pre() and is_post() methods on HookPoint. Foreground hooks block loop progression; background hooks run asynchronously for observation. The six post-commit points are intrinsically observe-only. Their session-scoped dispatcher owns spawned tasks, reaps completed work, and aborts remaining work when the dispatcher is dropped. A returned denial, timeout, or hook runtime failure cannot change or delay the committed fact.

Capabilities

HookCapability	Purpose
`Observe`	Read-only logging and metrics
`Guardrail`	Can issue `Deny` decisions to block execution

The former Rewrite capability is deleted entirely; semantic patch authority is removed.

Execution modes

HookExecutionMode	Behavior
`Foreground`	Blocks loop progression. `Allow` / `Deny` decisions are handled synchronously.
`Background`	Runs asynchronously for observation.

All background hooks must be observe-only. A background hook with any capability other than Observe is rejected with HookEngineError::InvalidConfiguration, regardless of hook point.The six post-commit points also require Observe capability in either execution mode. They are always dispatched outside the outcome path; configuring one as Foreground only orders matching hook handlers within its owned observation task.

Semantic patch publication is retired. RuntimeHookResponse rejects unknown fields, so a runtime response carrying any legacy patches field fails closed during deserialization.

How to add a hook

Choose hook point and capability

Decide which HookPoint to fire at (e.g., PreToolExecution for tool guardrails) and whether the hook needs Observe or Guardrail.

Choose a runtime

Pick one of the three runtimes: in-process (Rust closure), command (subprocess), or HTTP (remote endpoint).

Add configuration

Add a [[hooks.entries]] block to the active realm config.toml (or register programmatically via HooksConfig).

Implement the handler

Write the handler that receives a HookInvocation and returns a RuntimeHookResponse with an optional decision.

Test with overrides

Use HookRunOverrides to test your hook in isolation through RPC, REST, MCP, or embedded builders before committing the config.

The docs below show run-scoped hook overrides conceptually, but the current CLI does not expose run-scoped hook override flags in normal builds. For now, use RPC, REST, MCP, or the SDK/embedded surfaces when you want per-run hook overrides.

Runtimes

In-process
Command (subprocess)
HTTP

Calls a registered Rust closure. Config:

{ "type": "in_process", "handler": "my-handler" }

(name is accepted as a legacy alias for handler.)The handler is registered at engine construction time via DefaultHookEngine::with_in_process_handler() or register_in_process_handler(). The handler type is:

type InProcessHookHandler = Arc<dyn Fn(HookInvocation) -> HandlerFuture + Send + Sync>;

Spawns a subprocess. The HookInvocation is serialized as JSON to stdin; the process must write a RuntimeHookResponse JSON object to stdout. Config:

{
  "type": "command",
  "command": "python3",
  "args": ["hooks/safety_check.py"],
  "env": { "LOG_LEVEL": "debug" }
}

The subprocess payload size is capped at payload_max_bytes (default 128 KiB). Non-zero exit codes produce HookEngineError::ExecutionFailed.

Sends a POST request to a URL. The HookInvocation is the JSON body; the response must be a RuntimeHookResponse JSON object. Config:

{
  "type": "http",
  "url": "https://hooks.example.com/safety",
  "method": "POST",
  "headers": { "Authorization": "Bearer <token>" }
}

The method defaults to "POST" if not specified. Response body size is capped at payload_max_bytes. Header values are literal configuration; the hook runtime does not expand environment-variable references.

Foreground hook runtime failures fail closed through typed HookEngineError values; they are never converted into warning-only success or a hook-local Deny decision. Every background hook is required to be Observe, because asynchronous work cannot safely publish a guardrail decision after loop progression.

Decisions and patches

HookDecision

pub enum HookDecision {
    Allow,
    Deny {
        hook_id: HookId,
        reason_code: HookReasonCode,
        message: String,
        payload: Option<Value>,  // optional structured data
    },
}

Reason codes:

HookReasonCode	Meaning
`PolicyViolation`	Business rule or policy constraint
`SafetyViolation`	Content safety check
`SchemaViolation`	Schema or format validation failure
`Timeout`	Hook-supplied denial reason indicating a timeout
`RuntimeError`	Hook-supplied denial reason indicating a runtime error

These are reason codes a hook response can supply with Deny, not automatic engine-denial outcomes. Engine timeouts and execution failures remain typed HookEngineError values, mapped to HookFailureReason::Timeout or HookFailureReason::ExecutionFailed in foreground HookFailed events.

Retired patch payloads

The HookPatch type is deleted entirely. Older payloads such as llm_request, assistant_text, tool_args, tool_result, and run_result fail closed during deserialization instead of being ignored or applied.Hooks can observe typed projections and return Allow or Deny. Canonical provider parameters, assistant text, tool arguments, tool results, and final run text are owned by the runtime and tool execution path.

Runtime hook response

All three runtimes return the same RuntimeHookResponse structure:

{
  "decision": { "decision": "deny", "hook_id": "my-guard", "reason_code": "policy_violation", "message": "blocked" }
}

decision is optional and is the only field. The struct is declared with deny_unknown_fields, so any legacy patches field — even an empty one — is rejected at deserialization.

Invocation payload

Hooks receive a HookInvocation struct containing contextual data. Fields are populated based on the hook point:

Field	Type	Populated at
`point`	`HookPoint`	Always
`session_id`	`SessionId`	Always
`turn_number`	`Option<u32>`	Most points
`prompt_input`	`Option<RunInput>`	`RunStarted`
`error_report`	`Option<AgentErrorReport>`	`RunFailed`
`error_class`	`Option<AgentErrorClass>`	`RunFailed`
`llm_request`	`Option<HookLlmRequest>`	`PreLlmRequest`
`llm_response`	`Option<HookLlmResponse>`	`PostLlmResponse`
`tool_call`	`Option<HookToolCall>`	`PreToolExecution`
`tool_result`	`Option<HookToolResult>`	`PostToolExecution`
`observation`	`Option<HookObservation>`	The six post-commit points

For command and HTTP hooks, the serialized wire payload additionally carries prompt and error strings. These are serialize-only projections of prompt_input and error_report; they are never stored fields and are never deserialized back as authority.

Supporting types

HookLlmRequest: max_tokens, temperature, provider_params, message_count
HookLlmResponse: assistant_text, tool_call_names, stop_reason, usage, server_tool_content (typed ServerToolKind projection of provider-native server-tool blocks in the response, e.g. web search — empty when none; lets a foreground hook classify provider-native content ingestion synchronously)
HookToolCall: tool_use_id, name, args, provenance (typed ToolProvenance of the called tool — kind + source id, e.g. an MCP server name — projected from the tool’s ToolDef; absent for tools without declared provenance)
HookToolResult: tool_use_id, name, content_blocks, is_error, provenance (as on HookToolCall; the wire payload adds a serialize-only content text projection)
HookObservation: a tagged typed union for accepted, rejected, or deduplicated runtime input; committed peer ingress or egress; and completed interaction facts

HookToolResult.content_blocks carries the typed tool-result blocks, including image blocks, in original order. The wire payload also serializes a content string — a text projection derived from content_blocks for external command/HTTP hooks; in Rust, use HookToolResult::text_projection(). Both are observational projections and cannot be returned as a rewrite.

Hooks versus event streams

Use hooks as the default in-process application reaction API. Event streams remain the canonical ordered transport for remote observers, replay-aware pipelines, transcript/audit projection, and resynchronization after stream truncation. Command receipts remain the direct result for the caller that initiated an action; the matching committed outcome is also projected through the hook surface. Post-commit hooks are process-local best-effort reactions, not durable delivery. A crash after the canonical event is published may lose a hook invocation, and recovery of a finalized outbox may replay one. Use event streams for durable or replay-aware consumption; hook handlers with external side effects should deduplicate by canonical ids such as interaction_id. Post-commit hooks are not synchronous policy seams. They cannot close an in-turn race or gate a same-turn write. Keep using synchronous points such as PostToolExecution when policy must join the agent loop before it advances.

Priority ordering and deny short-circuiting

Foreground hooks are sorted by priority (ascending), then by registration_index (ascending, for determinism when priorities are equal). Lower numeric priority values run first. When a foreground hook returns Deny:

Record denial

The denial is recorded as the merged decision.

Skip remaining foreground hooks

All remaining foreground hooks are skipped (short-circuit).

Skip background hooks

All background hooks are skipped (they only fire when no foreground Deny occurred).

A priority-1 guardrail that denies will prevent a priority-100 observer from running.

Configuration

Config file example (realm config.toml)

Hook configuration lives under the [hooks] table:

[hooks]
default_timeout_ms = 5000       # Default: 5000
payload_max_bytes = 131072      # Default: 128 * 1024 (128 KiB)
background_max_concurrency = 32 # Default: 32

[[hooks.entries]]
id = "safety-check"
enabled = true
point = "pre_tool_execution"
mode = "foreground"
capability = "guardrail"
priority = 10
# timeout_ms = 10000              # Optional; overrides default_timeout_ms

[hooks.entries.runtime]
type = "command"
command = "python3"
args = ["hooks/safety_check.py"]

HookEntryConfig fields

Field	Type	Default	Description
`id`	`HookId`	`"hook"`	Unique identifier for the hook
`enabled`	`bool`	`true`	Whether the hook is active
`point`	`HookPoint`	`TurnBoundary`	Which hook point to fire at
`mode`	`HookExecutionMode`	`Foreground`	Foreground or background
`capability`	`HookCapability`	`Observe`	What the hook can do
`priority`	`i32`	`100`	Execution order (lower runs first)
`timeout_ms`	`Option<u64>`	`None`	Override default timeout
`runtime`	`HookAdapterConfig`	in_process/noop	Runtime configuration

Layered config loading

Hook loading is runtime-root aware. In workspace-derived realms, global and project hook entries are layered (~/.rkat/config.toml then .rkat/config.toml) and merged with active realm config hooks. In non-workspace realms, realm config is primary and no project config may be discovered.

Per-run overrides

The HookRunOverrides struct allows per-request hook customization:

pub struct HookRunOverrides {
    pub entries: Vec<HookEntryConfig>,  // Additional hooks for this run
    pub disable: Vec<HookId>,           // Hook IDs to disable for this run
}

Disabled hooks are removed from the effective entry list. Override entries are appended after the filtered base entries. All resulting entries are re-validated.

CLI
RPC / REST / MCP

Run-scoped hook override flags are not currently exposed on the normal rkat run surface. Use JSON-RPC, REST, MCP, or SDK/embedded surfaces for per-run hook override testing.

Hook overrides are passed via HookParams:

{
  "hooks_override": {
    "disable": ["safety-check"],
    "entries": []
  }
}

Agent events

For ordinary agent-loop hook points, the session event stream can include:

Event	When
`HookStarted`	A foreground hook, or an actually launched ordinary background hook, starts execution
`HookCompleted`	A foreground hook returns without an execution failure; a denial is reported separately
`HookFailed`	A foreground hook fails or times out, including the hard engine-error path
`HookDenied`	A foreground hook returns a `Deny` decision

Ordinary background work does not promise a terminal HookCompleted or HookFailed session event. Later failures and capacity skips are observable through DefaultHookEngine::background_dispatch_ledger() and tracing; a capacity-skipped hook has not started and does not earn HookStarted. Post-commit reactions use a separate isolated dispatch path and do not promise these normal lifecycle session events.

SDK usage

Registering an in-process hook

use meerkat_hooks::{DefaultHookEngine, RuntimeHookResponse};
use meerkat_core::{HooksConfig, HookEntryConfig, HookId, HookPoint,
                   HookCapability, HookAdapterConfig};
use std::sync::Arc;

let mut config = HooksConfig::default();
config.entries.push(HookEntryConfig {
    id: HookId::new("my-guardrail"),
    point: HookPoint::PreToolExecution,
    capability: HookCapability::Guardrail,
    priority: 10,
    runtime: HookAdapterConfig::in_process("my-handler"),
    ..Default::default()
});

let engine = DefaultHookEngine::new(config)
    .with_in_process_handler(
        "my-handler",
        Arc::new(|invocation| {
            Box::pin(async move {
                // Inspect invocation.tool_call, return decision
                Ok(RuntimeHookResponse::default())
            })
        }),
    );

Using hook overrides in AgentBuildConfig

use meerkat_core::HookRunOverrides;

let overrides = HookRunOverrides {
    disable: vec![HookId::new("noisy-observer")],
    entries: vec![],
};

// Pass via AgentBuildConfig.hooks_override

Getting started

Concepts

Guides: Models And Hosting

Guides: Runtime Behavior

Guides: Orchestration

Examples: Foundations

Examples: Capabilities

Examples: Orchestration And Deployment

What this guide is for

Hook points

Capabilities

Execution modes

How to add a hook

Runtimes

Decisions and patches

Runtime hook response

Invocation payload

Hooks versus event streams

Priority ordering and deny short-circuiting

Configuration

Per-run overrides

Agent events

SDK usage

See also

​What this guide is for

​Hook points

​Capabilities

​Execution modes

​How to add a hook

​Runtimes

​Decisions and patches

​Runtime hook response

​Invocation payload

​Hooks versus event streams

​Priority ordering and deny short-circuiting

​Configuration

​Per-run overrides

​Agent events

​SDK usage

​See also

What this guide is for

Hook points

Capabilities

Execution modes

How to add a hook

Runtimes

Decisions and patches

Runtime hook response

Invocation payload

Hooks versus event streams

Priority ordering and deny short-circuiting

Configuration

Per-run overrides

Agent events

SDK usage

See also