Hooks

Hooks are under active development. Today the runtime invokes on_turn_started / on_turn_finished around each Mantle turn, on_model_request / modify_model_request and on_model_response / modify_model_response on each main LLM loop iteration and on rephrase, confirm-rephrase, and the post-activate set_fields fill, on_tool_call / modify_tool_call and on_tool_result / modify_tool_result on the tool-call batch path, plus on_knowledge_query / modify_knowledge_query and on_knowledge_results / modify_knowledge_results around search_knowledge. Other catalogue points can be authored, validated, and packaged, but are not invoked yet.

Model request and response hooks run on the main LLM loop and on rephrase, confirm-rephrase, and the post-activate set_fields fill. On those three calls, RetryModel discards that completion instead of starting another main-loop iteration. A request-hook crash does not send the prompt. Hooks let you add optional steps to the Mantle turn path without replacing core components. Each hook is an async function registered with a point-specific decorator. Observe hooks (on_*) do not block the turn; if you register several for the same point, they run in parallel. Modify hooks (modify_*) are awaited and may return an updated payload.

Layout

Place hook modules at the agent root:

my-agent/
├── hooks.py              # optional single-file layout
└── hooks/                # optional folder layout
    └── redact_pii.py

Both layouts may coexist. The loader discovers hooks.py and nested hooks/**/*.py files (excluding __init__.py, __pycache__, and *.pyc). Shared project code under lib/ is importable during hook module loading, the same way as tool modules.

Registration

Import the decorator you need directly from rasa.mantle.hooks. Parentheses are mandatory, even when you only use defaults:

hooks/redact_pii.py

from rasa.mantle.hooks import (
    HookRejection,
    IncomingMessagePayload,
    ModelRequestPayload,
    ModelResponsePayload,
    RetryModel,
    ToolResultPayload,
    TurnFinishedPayload,
    modify_incoming_message,
    modify_model_request,
    modify_model_response,
    on_tool_result,
    on_turn_finished,
)


@modify_model_request()
async def redact_pii(request: ModelRequestPayload) -> ModelRequestPayload:
    return request.model_copy(update={"messages": request.messages})


@modify_model_response()
async def steer_or_drop(response: ModelResponsePayload) -> ModelResponsePayload:
    raise RetryModel(feedback="Only answer from retrieved passages.")


@modify_incoming_message()
async def drop_spam(message: IncomingMessagePayload) -> IncomingMessagePayload:
    if "spam" in message.text.lower():
        raise HookRejection(reason="spam detected")
    return message


@on_tool_result()
async def audit(result: ToolResultPayload) -> None:
    return None


@on_turn_finished()
async def mark_done(payload: TurnFinishedPayload) -> None:
    return None

Rules:

One modify hook per point. A second registration fails at train time and model load.
Many observe hooks per point. They run concurrently and unordered. The engine does not await them on the turn path.
Always async def. Synchronous handlers are rejected at validation.
Signatures: observe hooks take one typed payload and return None; modify hooks take one typed payload and return the same type.
Control flow is raised, never returned. Use exceptions for vetoes and model steering (see below).

Insertion points

Point	Observe	Modify	Control signals (modify only)	Fail on crash/timeout (modify)	Runtime
turn started	`on_turn_started`	—	—	—	wired
turn finished	`on_turn_finished`	—	—	—	wired
incoming message	`on_incoming_message`	`modify_incoming_message`	`HookRejection`	closed	not wired
model request	`on_model_request`	`modify_model_request`	—	closed	wired
model response	`on_model_response`	`modify_model_response`	`RetryModel`	open	wired
tool call	`on_tool_call`	`modify_tool_call`	`RetryModel`	closed	wired
tool result	`on_tool_result`	`modify_tool_result`	—	open	wired
knowledge query	`on_knowledge_query`	`modify_knowledge_query`	—	closed	wired
knowledge results	`on_knowledge_results`	`modify_knowledge_results`	—	open	wired
outgoing text	`on_outgoing_text`	`modify_outgoing_text`	`HookRejection`	open	not wired

Incoming-message and outgoing-text hooks apply to text only. Hooks for incoming audio, ASR partials, and outgoing audio are not available.

Control signals

Modify hooks signal intentional non-happy paths by raising exceptions:

HookRejection(reason=...) — veto this action. Allowed only at points listed in the table above.
RetryModel(feedback=...) — discard the current model response or tool call and steer the agentic loop with feedback. Allowed only on modify_model_response and modify_tool_call.

Raising a control signal at any other point is invalid hook behaviour and fails at train time when detected by the AST check. As a runtime backstop, an unsupported signal is logged and discarded, and the engine keeps the original payload. It never silently acquires rejection or retry semantics. RetryModel.feedback is a short note the engine adds to the next model request in the same turn. It is not saved in the conversation history, never appears as a user or bot message, and is never sent to the user. It only guides that next in-turn model call.

Multi-tool batches

There is still one registered modify_tool_call for the agent. When an LLM response contains several tool calls, the engine treats that single modifier as a preflight phase:

The engine invokes on_tool_call / modify_tool_call once per call in the LLM batch, sequentially in batch order, each time with that call’s own payload — before listen-only routing, the knowledge_searched latch, or any tool in the batch runs.
Only after every preflight invocation succeeds does routing and tool dispatch begin.
Confirmation and tool-constraint gates still run inside tool dispatch after preflight. A closed gate never reaches the tool body; confirmation resume later uses the (possibly hooked) stored arguments and does not re-run these hooks.

If any preflight invocation raises RetryModel, the entire batch is discarded, no tool in that batch runs, accompanying assistant text is not emitted, and the feedback steers the next model iteration. This prevents a retry requested for a later call from following an earlier tool side effect. Parallel preflight is out of scope for the first tool-call wiring. Unexpected modify_tool_call crashes or timeouts are fail-closed: the batch is not dispatched, accompanying text is not emitted, and the user hears utter_tool_call_hook_error (overridable in responses.yml). The exception text is not spoken. After each dispatched call returns, on_tool_result / modify_tool_result may rewrite the value persisted on tool_executed and replayed to the next provider request. That point has no control signals; unexpected crashes are fail-open and keep the original result. Tool-call ids and batch metadata are preserved. Tool-call and tool-result hooks run on the LLM tool-call batch path only. They do not run for other engine-driven tool invocations such as confirmation resume, settable writes, memory validation tools, or correction replay.

Knowledge search

on_knowledge_query / modify_knowledge_query run after the empty-query guard and before the references index is searched. on_knowledge_results / modify_knowledge_results run after retrieval and before passages are serialized back to the model. Both modifiers are change-only: they may rewrite the query or filter/reorder/empty passages, but they do not accept HookRejection or RetryModel. Unexpected query-hook crashes or timeouts are fail-closed and skip the search (the model receives the same safe empty-result note used when retrieval fails). Unexpected results-hook crashes or timeouts are fail-open and keep the original passages. Missing-index, empty-query, and retrieval-exception paths are unchanged when hooks are absent or succeed. KnowledgeQueryPayload / KnowledgeResultsPayload fields:

Field	Mutable?	Notes
`query`	yes (query point) / no (results point)	Search string passed to the references index
`passages`	yes (results point only)	Retrieved chunks as `{text, scope, source, score?}` dicts
`sender_id` / `call` / `channel`	no	Engine-owned identity

These hooks cannot block the turn. Do not raise HookRejection or RetryModel here. If you do, Mantle treats that as invalid modify behaviour. If modify_knowledge_query crashes or times out, Mantle skips the search. If modify_knowledge_results crashes, times out, or returns an unexpected shape, Mantle keeps the original passages.

Working example

hooks/rewrite_knowledge_search.py

import structlog

from rasa.mantle.hooks import (
    KnowledgeQueryPayload,
    KnowledgeResultsPayload,
    modify_knowledge_query,
    modify_knowledge_results,
    on_knowledge_query,
)

structlogger = structlog.get_logger()


@on_knowledge_query()
async def log_query(payload: KnowledgeQueryPayload) -> None:
    structlogger.debug(
        "hook.knowledge_query.observed",
        query=payload.query,
        sender_id=payload.sender_id,
    )


@modify_knowledge_query()
async def expand_query(payload: KnowledgeQueryPayload) -> KnowledgeQueryPayload:
    # Example: normalize short ticket-style queries before search.
    query = payload.query.strip()
    if query.isdigit():
        query = f"ticket {query}"
    return payload.model_copy(update={"query": query})


@modify_knowledge_results()
async def drop_low_scores(
    payload: KnowledgeResultsPayload,
) -> KnowledgeResultsPayload:
    passages = [
        passage
        for passage in payload.passages
        if float(passage.get("score") or 0.0) >= 0.2
    ]
    return payload.model_copy(update={"passages": passages})

Rejections and failures

Contract for incoming-message / outgoing-text wiring: When modify_incoming_message rejects text, the original user message remains the source-of-truth tracker event but is marked discarded. The LLM conversation projection excludes or safely masks it, and the user receives an incoming-message fallback. Fail-closed crash/timeout also must not run the engine on the original payload. When modify_outgoing_text rejects text, the original response is not emitted. A discarded bot utterance is stored and the user receives an outgoing-text fallback. An unexpected outgoing-text hook crash or timeout remains fail-open, so the original text is stored and sent. A point’s fail policy applies only to unexpected crashes and timeouts, never to intentional control signals. closed stops the current turn and fails gracefully; open logs and continues with the last good payload. Observe hooks are always non-blocking: they receive independent copies, and their mutations, errors, timeouts, or control signals have no effect on the turn.

Timeouts

Default timeouts:

Lane	Default `timeout_ms`
observe (`on_*`)	100
modify (`modify_*`) on text / LLM / tool / knowledge	500

Override per hook: @modify_model_request(timeout_ms=2000).

Payload wall

Every payload carries read-only identity fields:

sender_id
call (telephony/session metadata, when present)
channel (channel name and front-end metadata)

Hooks never receive access to the original tracker, the orchestrator, or raw tracker events. The runner copies the payload before calling a modify hook and restores engine-owned identity from the original input even when a modify hook returns different values for those fields. Use payload.model_copy(update={...}) to produce modify-hook return values:

from rasa.mantle.hooks import OutgoingTextPayload, modify_outgoing_text


@modify_outgoing_text()
async def rewrite(payload: OutgoingTextPayload) -> OutgoingTextPayload:
    return payload.model_copy(update={"text": payload.text.strip()})

Turn lifecycle

on_turn_started and on_turn_finished are observe-only. They run once per Mantle turn: started when the turn begins, finished when it ends — including when the turn fails unexpectedly — so you always see a matching pair. Neither point has a modify lane. Observers are scheduled concurrently and are not awaited on the turn path. Crashes, timeouts, mutations, and control signals from observers are logged and discarded — they cannot change tracker or engine state. TurnStartedPayload fields:

Field	Mutable?	Notes
`is_voice`	no	Whether this turn came from a voice channel
`turn_id`	no	Reserved; may be unset today
`sender_id`	no	Conversation / user id for this turn
`call`	no	Telephony/session metadata when present; empty unless the channel supplies it
`channel`	no	Channel name and front-end metadata

TurnFinishedPayload fields:

Field	Mutable?	Notes
`status`	no	Turn outcome: `completed`, `cancelled`, or `error`
`turn_id`	no	Reserved; may be unset today
`sender_id`	no	Conversation / user id for this turn
`call`	no	Telephony/session metadata when present; empty unless the channel supplies it
`channel`	no	Channel name and front-end metadata

TurnFinishedPayload.status reports the turn outcome:

Status	When
`completed`	The turn finished normally
`cancelled`	The turn was interrupted (for example, barge-in)
`error`	The turn failed

Working example

hooks/turn_timing.py

import time

import structlog

from rasa.mantle.hooks import (
    TurnFinishedPayload,
    TurnStartedPayload,
    on_turn_finished,
    on_turn_started,
)

structlogger = structlog.get_logger()

# Process-local timing only — observers must not mutate tracker/engine state.
_started_at: dict[str, float] = {}


@on_turn_started()
async def mark_start(payload: TurnStartedPayload) -> None:
    _started_at[payload.sender_id] = time.monotonic()
    structlogger.debug(
        "hook.turn.started",
        sender_id=payload.sender_id,
        is_voice=payload.is_voice,
        channel=payload.channel.name,
    )


@on_turn_finished()
async def mark_end(payload: TurnFinishedPayload) -> None:
    started = _started_at.pop(payload.sender_id, None)
    duration_ms = (
        None if started is None else round((time.monotonic() - started) * 1000)
    )
    structlogger.info(
        "hook.turn.finished",
        sender_id=payload.sender_id,
        status=payload.status,
        duration_ms=duration_ms,
        channel=payload.channel.name,
    )

Validation

Hook modules are validated during rasa train (before packaging). Validation checks:

import and syntax errors
unknown hook points
duplicate modify registrations
non-async handlers
payload type annotations and return types
unsupported control signals for each point

Fix validation errors before deploying — the same checks also apply at model load as a second line of defence.

`modify_model_request`

This wired insertion point runs once per main LLM loop iteration, and on rephrase, confirm-rephrase, and the post-activate set_fields fill, after the prompt is trimmed to the token budget and before the provider call. A crash here does not send the prompt. Empty-completion retries reuse that same hooked request (messages and allowlisted model_settings) without re-running hooks — the messages do not change between those attempts, so the hook result stays in effect for each retry. ModelRequestPayload fields:

Field	Mutable?	Notes
`messages`	yes	The chat messages about to be sent to the LLM
`model_settings`	yes	Allowlisted per-call overrides only (see below). Starts empty — the engine does not seed provider defaults into the payload; hooks supply any overrides for this path
`tool_names`	no	Read-only view of offered tool names
`iteration`	no	Current loop iteration
`sender_id` / `call` / `channel`	no	Engine-owned identity (`call` is populated only when telephony/session metadata is available)

You can change these model_settings keys: temperature, top_p, max_tokens, presence_penalty, frequency_penalty, stop, and seed. Values must match provider-safe types (numbers for the float/int keys; a string or list of strings for stop). Anything else is ignored — including API keys, the provider, and the model name. Hooks also cannot change which tools the LLM is offered. Message pass-through. Returned messages are forwarded to the provider as dict copies — Mantle does not validate roles/content or strip extra keys. An empty list still triggers the LLM call (the failure is a provider error, not HookExecutionError). Extra fields such as tool_calls or name are left in place intentionally so builders can shape provider-compatible payloads. This hook cannot block the turn. Do not raise HookRejection or RetryModel here. If you do, Mantle logs and ignores them, keeps the last good request, and still calls the LLM. If the hook crashes or times out, Mantle skips the LLM call and tells the user with utter_model_request_hook_error.

Working example

hooks/lower_temperature.py

import structlog

from rasa.mantle.hooks import ModelRequestPayload, modify_model_request, on_model_request

structlogger = structlog.get_logger()


@on_model_request()
async def log_request(request: ModelRequestPayload) -> None:
    # Observe lane: fire-and-forget; mutations have no effect.
    structlogger.debug(
        "hook.model_request.observed",
        message_count=len(request.messages),
        tool_count=len(request.tool_names),
        iteration=request.iteration,
        sender_id=request.sender_id,
    )


@modify_model_request()
async def cool_down(request: ModelRequestPayload) -> ModelRequestPayload:
    return request.model_copy(
        update={
            "messages": request.messages,
            "model_settings": {"temperature": 0.2},
        }
    )

`modify_model_response`

Runs once per main LLM loop iteration, and on rephrase, confirm-rephrase, and the post-activate set_fields fill, after the provider returns and before any user-visible text emit or tool dispatch. The modify lane may rewrite response text and tool calls; those rewritten values are what the engine uses. On the three quiet calls, RetryModel discards that completion. It does not start another main-loop iteration. ModelResponsePayload fields:

Field	Mutable?	Notes
`text`	yes	Assistant text from this completion (may be `None`)
`tool_calls`	yes	List of tool-call dicts with `id`, `tool_name`, `tool_args`, and optional `type`
`latency_ms`	no	Provider latency for this completion, when available
`sender_id` / `call` / `channel`	no	Engine-owned identity

Control signal: raise RetryModel(feedback=...) to discard this response (no text emit, no tool dispatch) and steer another model iteration. The feedback string is appended as an engine-only system note on the next request only. It is not stored on the tracker and is never sent to the user. Re-entry still counts toward the per-turn iteration cap; exhausting that cap uses the existing max-iterations result. Do not raise HookRejection here. Once an incoming message has been accepted, this point improves accuracy/safety by rewriting or steering — it cannot intentionally suppress the answer. An unsupported rejection is logged and discarded, and the original response proceeds. Unexpected modifier crashes, timeouts, or invalid return values are fail-open: Mantle keeps the original response and continues. RetryModel is intentional control flow and is never swallowed by fail-open handling. When a modify_model_response or modify_tool_call hook is registered, Mantle buffers the full main-LLM completion instead of streaming tokens live. Those hooks run only after the provider finishes; live streaming would let the user hear tokens the modifier might still rewrite or discard via RetryModel (including text dropped with a discarded tool-call batch). Channels that support streaming still receive the final (possibly hooked) text in one delivery. Observe-only hooks do not disable streaming. Changing between text-only and tool-call shapes also updates the knowledge_searched latch used for the search-then-answer loop — the latch follows the post-hook tool calls.

Working example

hooks/ground_answers.py

import structlog

from rasa.mantle.hooks import (
    ModelResponsePayload,
    RetryModel,
    modify_model_response,
    on_model_response,
)

structlogger = structlog.get_logger()


@on_model_response()
async def audit(response: ModelResponsePayload) -> None:
    structlogger.debug(
        "hook.model_response.observed",
        has_text=bool(response.text),
        tool_call_count=len(response.tool_calls),
        latency_ms=response.latency_ms,
        sender_id=response.sender_id,
    )


@modify_model_response()
async def require_grounding(response: ModelResponsePayload) -> ModelResponsePayload:
    # Drop tool calls the policy forbids before any dispatch.
    allowed = [
        call
        for call in response.tool_calls
        if call.get("tool_name") != "place_order"
    ]
    if len(allowed) != len(response.tool_calls):
        return response.model_copy(update={"tool_calls": allowed})

    # Steer another iteration when the text answer is ungrounded.
    if response.text and "according to" not in response.text.lower():
        raise RetryModel(
            feedback="Only make claims supported by the retrieved passages."
        )

    # Optional rewrite of user-visible text before emit.
    if response.text:
        return response.model_copy(update={"text": response.text.strip()})
    return response

`modify_tool_call`

Runs as a batch preflight before listen-only routing, the knowledge_searched latch, and any tool dispatch. For each call in the batch, Mantle invokes on_tool_call / modify_tool_call once — sequentially in batch order — with that call’s own payload. Only after every preflight invocation succeeds does routing and dispatch begin. Confirmation resume, settable writes, memory validation tools, and correction replay never reach this path. Confirmation and tool-constraint gates still run later inside dispatch after preflight. ToolCallPayload fields:

Field	Mutable?	Notes
`tool_name`	yes	Name of the tool about to run
`arguments`	yes	Tool arguments dict
`headers`	yes	Payload-only today — not plumbed into dispatch
`sender_id` / `call` / `channel`	no	Engine-owned identity

Engine-owned tool-call id and provider type are preserved across rewrites; hooks never receive or change them. Control signal: raise RetryModel(feedback=...) from any preflight invocation to discard the entire batch (no tool has run yet, and any accompanying assistant text is not emitted) and steer the next model iteration. The feedback string is appended as an engine-only system note on the next request only. Do not raise HookRejection here. An unsupported rejection is logged and discarded, and the original call proceeds through preflight. Unexpected modifier crashes or timeouts are fail-closed: the batch is not dispatched, accompanying text is not emitted, and the user hears utter_tool_call_hook_error. A registered modify_tool_call hook buffers the main completion the same way modify_model_response does, so live streaming cannot leak speech that preflight later discards. Observe-only on_tool_call hooks do not disable streaming.

Working example

hooks/guard_tool_calls.py

import structlog

from rasa.mantle.hooks import (
    RetryModel,
    ToolCallPayload,
    modify_tool_call,
    on_tool_call,
)

structlogger = structlog.get_logger()


@on_tool_call()
async def audit_call(call: ToolCallPayload) -> None:
    structlogger.debug(
        "hook.tool_call.observed",
        tool_name=call.tool_name,
        sender_id=call.sender_id,
    )


@modify_tool_call()
async def normalize_and_steer(call: ToolCallPayload) -> ToolCallPayload:
    if call.tool_name == "place_order" and not call.arguments.get("card_id"):
        raise RetryModel(feedback="Call place_order with a card_id.")
    if call.tool_name == "place_order":
        return call.model_copy(
            update={
                "arguments": {
                    **call.arguments,
                    "card_id": str(call.arguments["card_id"]).strip(),
                }
            }
        )
    return call

`modify_tool_result`

Runs after each dispatched tool returns and before the result is persisted on tool_executed and replayed to the next provider request. The modify lane may rewrite value, arguments, and is_error. ToolResultPayload fields:

Field	Mutable?	Notes
`tool_name`	no	Name of the tool that just ran
`arguments`	yes	Arguments used for this call (may be rewritten for persistence/replay)
`value`	yes	Result value persisted and replayed to the model
`is_error`	yes	Whether the result should be treated as an error
`sender_id` / `call` / `channel`	no	Engine-owned identity

Tool-call ids and batch metadata stay engine-owned. This hook has no control signals. Do not raise HookRejection or RetryModel here. If you do, Mantle logs and ignores them and keeps the last good result. Unexpected modifier crashes, timeouts, or invalid return values are fail-open: Mantle keeps the original result and continues. Langfuse tool-call span output uses the post-hook persisted result (same value stored on the tracker), so redaction in modify_tool_result applies to traces as well as prompt replay.

Working example

hooks/redact_tool_results.py

import structlog

from rasa.mantle.hooks import (
    ToolResultPayload,
    modify_tool_result,
    on_tool_result,
)

structlogger = structlog.get_logger()


@on_tool_result()
async def audit_result(result: ToolResultPayload) -> None:
    structlogger.debug(
        "hook.tool_result.observed",
        tool_name=result.tool_name,
        is_error=result.is_error,
        sender_id=result.sender_id,
    )


@modify_tool_result()
async def redact_pii(result: ToolResultPayload) -> ToolResultPayload:
    if result.tool_name != "lookup_customer":
        return result
    safe_args = {k: v for k, v in result.arguments.items() if k != "ssn"}
    return result.model_copy(
        update={
            "value": "redacted",
            "arguments": safe_args,
            "is_error": False,
        }
    )

File Reference

Language

Tools

Customizations

Runtime

Observability

Prompts

Schemas

Layout

Registration

Insertion points

Control signals

Multi-tool batches

Knowledge search

Working example

Rejections and failures

Timeouts

Payload wall

Turn lifecycle

Working example

Validation

`modify_model_request`

Working example

`modify_model_response`

Working example

`modify_tool_call`

Working example

`modify_tool_result`

Working example

​Layout

​Registration

​Insertion points

​Control signals

​Multi-tool batches

​Knowledge search

​Working example

​Rejections and failures

​Timeouts

​Payload wall

​Turn lifecycle

​Working example

​Validation

​modify_model_request

​Working example

​modify_model_response

​Working example

​modify_tool_call

​Working example

​modify_tool_result

​Working example

Layout

Registration

Insertion points

Control signals

Multi-tool batches

Knowledge search

Working example

Rejections and failures

Timeouts

Payload wall

Turn lifecycle

Working example

Validation

`modify_model_request`

Working example

`modify_model_response`

Working example

`modify_tool_call`

Working example

`modify_tool_result`

Working example