Hooks

Hooks let you run custom logic at defined points in the agent lifecycle — before/after tool execution, LLM calls, or at turn boundaries. Use them for approval workflows, audit logging, 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
log or audit agent behavior
block unsafe tool inputs or outputs
choose between in-process, command, and HTTP hook runtimes

Hook points

Eight 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

Classification is determined by the is_pre() and is_post() methods on HookPoint. Foreground hooks block loop progression; background hooks run asynchronously for observation.

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.

Pre-point background hooks must be observe-only. A background hook on a is_pre() point with any capability other than Observe is rejected with HookEngineError::InvalidConfiguration.

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.

Hook runtime failures fail closed through typed HookEngineError values; they are never converted into warning-only success or a hook-local Deny decision. Pre-point background hooks are still required to be Observe, because they cannot safely block a pre-execution boundary after the loop has moved on.

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 timed out (system-generated)
`RuntimeError`	Hook execution failed (system-generated)

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`

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)

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.

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

The hook engine emits AgentEvent variants during execution:

Event	When
`HookStarted`	A hook begins execution
`HookCompleted`	A hook finishes successfully
`HookFailed`	A hook encounters an error
`HookDenied`	A hook returns a `Deny` decision

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

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

​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

Priority ordering and deny short-circuiting

Configuration

Per-run overrides

Agent events

SDK usage

See also