Hooks examples

For the full guide, see Hooks.

Start here after you understand the normal session/tool flow. If you are new to Meerkat overall, read Examples: Sessions first.

Post-commit application reaction

Use a committed-fact point when the handler updates UI or telemetry but must never affect the operation it observes:

[[hooks.entries]]
id = "runtime-input-ui"
point = "runtime_input_accepted"
mode = "background"
capability = "observe"

[hooks.entries.runtime]
type = "http"
url = "http://127.0.0.1:4100/hooks/runtime-input"

The request carries HookInvocation.observation with observation_type = "runtime_input_accepted" and typed input id, kind, and handling mode. The operation has already committed. A denial-shaped response, hook failure, or timeout cannot change it.

Observer hook (background)

A post_tool_execution background hook that logs every tool call to a file. Background hooks run asynchronously and never block the agent loop.

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

{
  "jsonrpc": "2.0", "id": 1,
  "method": "session/create",
  "params": {
    "prompt": "Summarize this repo",
    "hooks_override": {
      "entries": [{
        "id": "audit-log",
        "point": "post_tool_execution",
        "mode": "background",
        "capability": "observe",
        "runtime": {
          "type": "command",
          "command": "python3",
          "args": ["hooks/log_tool.py"]
        },
        "timeout_ms": 3000
      }]
    }
  }
}

curl -X POST http://127.0.0.1:8080/sessions \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Summarize this repo",
    "hooks_override": {
      "entries": [{
        "id": "audit-log",
        "point": "post_tool_execution",
        "mode": "background",
        "capability": "observe",
        "runtime": {
          "type": "command",
          "command": "python3",
          "args": ["hooks/log_tool.py"]
        },
        "timeout_ms": 3000
      }]
    }
  }'

{
  "name": "meerkat_run",
  "arguments": {
    "prompt": "Summarize this repo",
    "enable_builtins": true,
    "hooks_override": {
      "entries": [{
        "id": "audit-log",
        "point": "post_tool_execution",
        "mode": "background",
        "capability": "observe",
        "runtime": {
          "type": "command",
          "command": "python3",
          "args": ["hooks/log_tool.py"]
        },
        "timeout_ms": 3000
      }]
    }
  }
}

result = await client.create_session(
    "Summarize this repo",
    hooks_override={
        "entries": [{
            "id": "audit-log",
            "point": "post_tool_execution",
            "mode": "background",
            "capability": "observe",
            "runtime": {
                "type": "command",
                "command": "python3",
                "args": ["hooks/log_tool.py"],
            },
            "timeout_ms": 3000,
        }]
    },
)

const result = await client.createSession("Summarize this repo", {
  hooksOverride: {
    entries: [{
      id: "audit-log",
      point: "post_tool_execution",
      mode: "background",
      capability: "observe",
      runtime: {
        type: "command",
        command: "python3",
        args: ["hooks/log_tool.py"],
      },
      timeout_ms: 3000,
    }],
  },
});

Guardrail hook (foreground)

A pre_tool_execution foreground hook that must approve each tool call before it runs. If the hook returns deny, the tool is not dispatched and the current run terminates with HookDenied. This is not an ordinary tool-error result that lets the agent continue.

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

{
  "jsonrpc": "2.0", "id": 1,
  "method": "session/create",
  "params": {
    "prompt": "Delete old logs",
    "hooks_override": {
      "entries": [{
        "id": "safety-gate",
        "point": "pre_tool_execution",
        "mode": "foreground",
        "capability": "guardrail",
        "runtime": {
          "type": "command",
          "command": "python3",
          "args": ["hooks/approve_tool.py"]
        },
        "timeout_ms": 5000
      }]
    }
  }
}

curl -X POST http://127.0.0.1:8080/sessions \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Delete old logs",
    "hooks_override": {
      "entries": [{
        "id": "safety-gate",
        "point": "pre_tool_execution",
        "mode": "foreground",
        "capability": "guardrail",
        "runtime": {
          "type": "command",
          "command": "python3",
          "args": ["hooks/approve_tool.py"]
        },
        "timeout_ms": 5000
      }]
    }
  }'

{
  "name": "meerkat_run",
  "arguments": {
    "prompt": "Delete old logs",
    "enable_builtins": true,
    "hooks_override": {
      "entries": [{
        "id": "safety-gate",
        "point": "pre_tool_execution",
        "mode": "foreground",
        "capability": "guardrail",
        "runtime": {
          "type": "command",
          "command": "python3",
          "args": ["hooks/approve_tool.py"]
        },
        "timeout_ms": 5000
      }]
    }
  }
}

result = await client.create_session(
    "Delete old logs",
    hooks_override={
        "entries": [{
            "id": "safety-gate",
            "point": "pre_tool_execution",
            "mode": "foreground",
            "capability": "guardrail",
            "runtime": {
                "type": "command",
                "command": "python3",
                "args": ["hooks/approve_tool.py"],
            },
            "timeout_ms": 5000,
        }]
    },
)

const result = await client.createSession("Delete old logs", {
  hooksOverride: {
    entries: [{
      id: "safety-gate",
      point: "pre_tool_execution",
      mode: "foreground",
      capability: "guardrail",
      runtime: {
        type: "command",
        command: "python3",
        args: ["hooks/approve_tool.py"],
      },
      timeout_ms: 5000,
    }],
  },
});

In-process hook (Rust only)

Rust

let engine = DefaultHookEngine::new(hooks_config)
    .with_in_process_handler(
        "pii-guard",
        Arc::new(|invocation| Box::pin(async move {
            let text = invocation.tool_call.as_ref()
                .map(|call| call.args.as_value().to_string()).unwrap_or_default();
            let decision = if contains_pii(&text) {
                Some(HookDecision::deny(
                    HookId::new("pii-guard"),
                    HookReasonCode::PolicyViolation,
                    "tool arguments contain PII",
                    None,
                ))
            } else {
                None
            };
            Ok(RuntimeHookResponse { decision })
        })),
    );

Hooks receive typed projections of the request, response, tool call, and tool result. They can allow, deny, or observe those facts; they cannot rewrite canonical LLM, tool, or run output.

Rust

let engine = DefaultHookEngine::new(hooks_config)
    .with_in_process_handler(
        "tool-audit",
        Arc::new(|invocation| Box::pin(async move {
            let content = invocation.tool_result.as_ref()
                .map(|r| r.text_projection()).unwrap_or_default();
            audit_tool_result(&content).await;
            Ok(RuntimeHookResponse::default())
        })),
    );

Gate a tool by provenance

Tool names are not sufficient authority when several MCP servers or bundles can publish the same logical operation. A pre_tool_execution hook can inspect the winning tool definition’s typed provenance:

let engine = DefaultHookEngine::new(hooks_config)
    .with_in_process_handler(
        "trusted-mcp-only",
        Arc::new(|invocation| Box::pin(async move {
            let denied = invocation.tool_call.as_ref().is_some_and(|call| {
                call.provenance.as_ref().is_some_and(|source| {
                    source.kind == ToolSourceKind::Mcp
                        && source.source_id.as_str() != "approved-server"
                })
            });
            Ok(RuntimeHookResponse {
                decision: denied.then(|| HookDecision::deny(
                    HookId::new("trusted-mcp-only"),
                    HookReasonCode::PolicyViolation,
                    "MCP source is not approved",
                    None,
                )),
            })
        })),
    );

The same provenance is present on HookToolResult, so post-execution audit hooks can attribute outputs to the exact selected source without re-resolving a tool name.

HTTP hook

A hook that POSTs the invocation payload to a remote URL. Useful for centralized policy servers.

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

{
  "jsonrpc": "2.0", "id": 1,
  "method": "session/create",
  "params": {
    "prompt": "Analyze quarterly data",
    "hooks_override": {
      "entries": [{
        "id": "policy-server",
        "point": "pre_llm_request",
        "mode": "foreground",
        "capability": "guardrail",
        "runtime": {
          "type": "http",
          "url": "https://hooks.example.com/policy",
          "method": "POST"
        },
        "timeout_ms": 10000
      }]
    }
  }
}

curl -X POST http://127.0.0.1:8080/sessions \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Analyze quarterly data",
    "hooks_override": {
      "entries": [{
        "id": "policy-server",
        "point": "pre_llm_request",
        "mode": "foreground",
        "capability": "guardrail",
        "runtime": {
          "type": "http",
          "url": "https://hooks.example.com/policy",
          "method": "POST"
        },
        "timeout_ms": 10000
      }]
    }
  }'

{
  "name": "meerkat_run",
  "arguments": {
    "prompt": "Analyze quarterly data",
    "enable_builtins": true,
    "hooks_override": {
      "entries": [{
        "id": "policy-server",
        "point": "pre_llm_request",
        "mode": "foreground",
        "capability": "guardrail",
        "runtime": {
          "type": "http",
          "url": "https://hooks.example.com/policy",
          "method": "POST"
        },
        "timeout_ms": 10000
      }]
    }
  }
}

result = await client.create_session(
    "Analyze quarterly data",
    hooks_override={
        "entries": [{
            "id": "policy-server",
            "point": "pre_llm_request",
            "mode": "foreground",
            "capability": "guardrail",
            "runtime": {
                "type": "http",
                "url": "https://hooks.example.com/policy",
                "method": "POST",
            },
            "timeout_ms": 10000,
        }]
    },
)

const result = await client.createSession("Analyze quarterly data", {
  hooksOverride: {
    entries: [{
      id: "policy-server",
      point: "pre_llm_request",
      mode: "foreground",
      capability: "guardrail",
      runtime: {
        type: "http",
        url: "https://hooks.example.com/policy",
        method: "POST",
      },
      timeout_ms: 10000,
    }],
  },
});

All 14 hook points

Hook point	Classification	When it fires
`run_started`	pre	Start of `Agent::run()`, before any LLM call
`pre_llm_request`	pre	Before each LLM streaming call
`pre_tool_execution`	pre	Before each individual tool call is dispatched
`turn_boundary`	pre	Between turns, after all tool results are collected
`post_llm_response`	post	After the LLM response is received
`post_tool_execution`	post	After each tool execution completes
`run_completed`	post	After a successful run completes
`run_failed`	post	After a run fails with an error
`runtime_input_accepted`	post-commit, observe-only	After runtime and session authority commit an accepted input
`runtime_input_rejected`	terminal, observe-only	After runtime terminally rejects an input
`runtime_input_deduplicated`	post-commit, observe-only	After idempotency resolves to an existing committed input
`peer_ingress_committed`	post-commit, observe-only	After runtime commits an accepted peer input
`peer_egress_committed`	post-commit, observe-only	After a successful typed peer delivery receipt
`interaction_completed`	post-commit, observe-only	After durable interaction-terminal publication

Foreground hooks halt loop progression until they return. Every hook in background mode is limited to observe capability, including post points. The six post-commit points are always dispatched asynchronously and require observe, regardless of their configured execution mode.

Disable a hook

Use the disable list to turn off hooks defined in the realm config without removing them.

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.

{
  "jsonrpc": "2.0", "id": 1,
  "method": "session/create",
  "params": {
    "prompt": "Quick test",
    "hooks_override": {
      "disable": ["safety-gate", "audit-log"]
    }
  }
}

curl -X POST http://127.0.0.1:8080/sessions \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Quick test",
    "hooks_override": {
      "disable": ["safety-gate", "audit-log"]
    }
  }'

{
  "name": "meerkat_run",
  "arguments": {
    "prompt": "Quick test",
    "enable_builtins": true,
    "hooks_override": {
      "disable": ["safety-gate", "audit-log"]
    }
  }
}

result = await client.create_session(
    "Quick test",
    hooks_override={
        "disable": ["safety-gate", "audit-log"]
    },
)

const result = await client.createSession("Quick test", {
  hooksOverride: {
    disable: ["safety-gate", "audit-log"],
  },
});

Hook events

Ordinary foreground hooks report lifecycle events in the session event stream. These examples show possible outcomes for the foreground safety-gate hook, not a single execution that both succeeds and fails.

// HookStarted -- emitted when a hook begins execution
{"type": "hook_started", "hook_id": "safety-gate", "point": "pre_tool_execution"}

// HookCompleted -- emitted when a hook finishes successfully
{"type": "hook_completed", "hook_id": "safety-gate", "point": "pre_tool_execution", "duration_ms": 42}

// HookDenied -- emitted when a hook blocks execution
{"type": "hook_denied", "hook_id": "safety-gate", "point": "pre_tool_execution", "reason_code": "policy_violation", "message": "rm -rf not allowed"}

// HookFailed -- emitted when a foreground hook errors or times out
{"type": "hook_failed", "hook_id": "safety-gate", "point": "pre_tool_execution", "reason": {"reason_code": "execution_failed", "message": "process exited with code 1"}}

An ordinary background hook such as audit-log may produce HookStarted when actually launched. Capacity skips and later failures are recorded in the in-process background dispatch ledger and tracing; a terminal HookCompleted or HookFailed session event is not promised for that asynchronous work. Post-commit reactions use a separate isolated dispatch path and do not promise these normal lifecycle session events.

Getting started

Concepts

Guides: Models And Hosting

Guides: Runtime Behavior

Guides: Orchestration

Examples: Foundations

Examples: Capabilities

Examples: Orchestration And Deployment

Post-commit application reaction

Observer hook (background)

Guardrail hook (foreground)

In-process hook (Rust only)

Gate a tool by provenance

HTTP hook

All 14 hook points

Disable a hook

Hook events

Next step

​Post-commit application reaction

​Observer hook (background)

​Guardrail hook (foreground)

​In-process hook (Rust only)

​Gate a tool by provenance

​HTTP hook

​All 14 hook points

​Disable a hook

​Hook events

​Next step

Post-commit application reaction

Observer hook (background)

Guardrail hook (foreground)

In-process hook (Rust only)

Gate a tool by provenance

HTTP hook

All 14 hook points

Disable a hook

Hook events

Next step