> ## Documentation Index
> Fetch the complete documentation index at: https://mantle.rasa.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Execution Loop

> The deterministic-first loop that runs every turn.

Every turn runs a deterministic-first loop:

1. **Apply inbound `set:` button taps** (when the user text is a valid
   payload from the latest agent message). The engine writes that memory
   field and runs its [memory validation tool](https://mantle.rasa.com/reference/tools.md#memory-validation-tools)
   before any LLM call. Stale or
   non-writable taps utter `utter_set_memory_button_skipped` and **skip** the
   rest of this loop. See
   [Set-memory payloads](https://mantle.rasa.com/reference/responses-yml.md#set-memory-payloads).
2. **Execute deterministic steps first**: ordered-block steps that need no
   model call (`execute_tool:`, `noop:`, `set_memory:`, `utter:`, and
   `collect:` steps whose value is already known, including a field just
   written by a `set:` tap). The framework also narrows
   what the LLM may do next, omitting `hidden` / `disabled` / engine-managed
   skills and hiding gated tools, though the routing choice itself is made by
   the LLM in step 4.
3. **Build a scoped prompt from live state**: the active skill's instructions
   filtered by `if:` markers, the tools whose `requires:` conditions currently
   hold, and the memory values readable in scope. A `set:` payload is omitted.
   A successful tap shows the button label instead, and that turn adds a system
   instruction that the field is already stored.
4. **Call the LLM.**
5. **If the LLM returns a tool call**: dispatch it, apply any memory writes the
   tool makes as it runs, check for newly-available deterministic steps, and
   loop back to step 2.
6. **Otherwise**: send any text. Then either wait for the user or loop from
   step 2. See [When the engine waits](#when-the-engine-waits).

One user message can go around this loop several times.

## Start a skill from a message

A typed user message whose whole text is `/` plus one skill folder name, such as
`/refund`, starts that skill before [step 2](#deterministic-steps), with no routing turn. The folder name has to be a
skill the router may already start. Hidden, disabled, and engine-managed
skills stay unstarted, and so does an ordered-block id. The match is
case-sensitive: `/Refund` is ordinary text. Voice turns never use the command.

The command is left out of the skill prompt. The stored user message is
unchanged. When another skill is already running, the command interrupts it
the same way `activate` does. While the agent is declining an unsupported
request, `activate` is refused, and so is this command: the message stays
ordinary text. Sending it for a routable skill that is already
running continues that skill, including while one of its ordered blocks is
open. If that block is still waiting on a collect field, this turn's prompt
names the field instead of the command. A hidden, disabled, or
engine-managed skill stays ordinary text even when that skill is already
running. A skill with an unmet precondition
starts its resolver instead.

`/refund please` is not a command, and neither is `/skill refund`. Both stay
as typed and are routed normally. A command that names a skill the router
cannot start is left as typed and routed normally. `/session_start`,
`/session_end`, and `/silence_timeout` are engine messages, not skill
commands. Validation rejects a skill folder with one of those names.

## When the engine waits

The engine waits for the next user message when:

* The stack is empty after a delivered response (the skill or block finished).
* An engaged `collect:` needs the user's answer.
* An ordered-block `execute_tool: listen` step runs.
* The LLM calls `listen()` alone (not mixed with text or other tools).

After a canned ordered-block `utter_*`, leftover hybrid prose or further
deterministic steps can still run in the same turn. On that follow-up LLM call,
a
[canned-response reminder](https://mantle.rasa.com/reference/prompt-templates.md#canned-response-reminder-injected)
tells the model not to repeat or paraphrase the canned reply. See
[`listen`](https://mantle.rasa.com/reference/tools).

## When the engine ends the conversation

Hangup is destructive and is not offered as an LLM tool. A skill must explicitly
execute `execute_tool: hangup` in an ordered block to end the conversation. Place an
`utter_*` goodbye before that step when a farewell is needed.

## State tracked per control level

| Control level | What the framework tracks |
| - | - |
| Skill routing | The dialogue stack (parent frames, sub-skill frames, interrupts) |
| Ordered block | A step pointer: the current step in the block |
| Prose with `if:` markers | Memory state, which determines which paragraphs are in the prompt |

These coexist. A hybrid skill, meaning prose with `if:` markers that also
references an ordered block, tracks both a step pointer and memory state at
once.

## Tool execution

A tool may be invoked by the LLM (a tool call) or by the framework (an
`execute_tool:` step). The function does not know or care which.

`tool_constraints` are checked in both cases, and in two places:

* when the tool schema is built, deciding whether the LLM sees the tool at all
* again at dispatch, before the function runs

Both **fail closed**. A `requires:` condition that cannot be evaluated hides
and blocks the tool rather than allowing it.

When the LLM issues a local or MCP tool call, Mantle validates the arguments
against the JSON schema offered to the model before confirmation or execution.
Missing, extra, or mistyped arguments are returned as a retryable error so the
model can correct the call in the same turn. Because the tool did not run, this
does not trigger its `on_failure` response. An imported MCP tool without a
usable object schema is treated the same way: the remote tool is not called.

Ordered `execute_tool` steps use the same check after memory fill. Those
arguments come from the step's `parameters:`, not from the model, so the LLM
cannot repair a schema-invalid payload. The engine stays on the step, does not
run the tool or `on_failure`, and yields so a later deterministic pass can
retry if missing memory has been filled. If the parameters themselves stay
invalid, the tool cannot run.

## Knowledge search changes the loop

When `search_knowledge` runs during a turn, the tool list for the remainder of
that turn collapses to `activate`, `search_knowledge`, and `cannot_help`, plus
`resolve_tool_confirmation` when a confirmation is pending so the pending gate
is never stranded. The active skill's lifecycle, collect, builder, and `listen`
tools are dropped so a grounded answer neither re-drives the skill nor ends
silently before presenting the retrieved information. They return on the next
turn.

Relatedly, `cannot_help` is withheld until a search has run whenever a knowledge
base is configured, so the model cannot decline before retrieval could have
answered.

If the model still mixes `listen` with a user-facing answer after a search, the
engine ignores `listen` and treats the text as the grounded reply: the
post-search trim ends so the skill can be parked and resume offered.

## Where conditions are evaluated

| Condition | Evaluated |
| - | - |
| `hidden` / `disabled` / engine-managed | When building the routable-skill list, every turn |
| `satisfied_when` (precondition binding) | When starting a skill that declares `precondition`, and again when the resolver completes. The check reads saved memory only ([details](https://mantle.rasa.com/reference/tools.md#precondition-check)). |
| `tool_constraints` `requires:` | At schema build and again at dispatch |
| Prose `if:` | At prompt build, every turn |
| `next:` branches | When a step advances |
| Ordered-block step `complete_when:` | When checking whether a step is already satisfied |
| Skill-level `complete_when` (`condition` / `criteria`) | On `complete`: `condition` must hold; `criteria` are judged before the skill can complete |

See [Conditions](https://mantle.rasa.com/reference/conditions.md) for expression grammar, and
[skill.md `complete_when`](https://mantle.rasa.com/reference/skill-md#complete_when) for the skill-level
mapping.

## Tracker events

Mantle appends these events to the conversation tracker. They are what Inspector
and Copilot read; you do not author them in YAML.

| Event | When | Payload |
| - | - | - |
| `skill_activated` | Skill-scoped activation (builder skills and defaults) | `skill_id` |
| `skill_completed` | Skill-scoped completion | `skill_id` |
| `skill_cancelled` | Skill cancelled (one per skill) | `skill_id`, `step_id` |
| `skill_interrupted` | Skill parked for a digression | `skill_id`, `step_id` |
| `skill_resumed` | Skill continues after a pause | `skill_id`, `step_id` |
| `ordered_block_entered` | An authored ordered block starts | `skill_id`, `block_id` |
| `ordered_block_completed` | The block finishes | `skill_id`, `block_id`, `step_id` |
| `ordered_block_cancelled` | The block is cancelled | `skill_id`, `block_id`, `step_id` |
| `ordered_block_interrupted` | The block is parked for a digression | `skill_id`, `block_id`, `step_id` |
| `ordered_block_resumed` | The block continues after a pause | `skill_id`, `block_id`, `step_id` |
| `tool_executed` | A local or MCP tool call was dispatched; schema-invalid LLM calls are recorded without running the tool so the LLM can retry | `tool_name`, `arguments`, `source` (`local` or `mcp`), `result`, `is_error`, `error_message`, `is_hint`; `mcp_server` only when `source` is `mcp` |
| `memory_set` | A declared memory key was written | `key`, `value` |
| `memory_cleared` | A declared memory key was cleared | `key` |

These are the only lifecycle, tool, and memory events Mantle writes. Skill
lifecycle is `skill_*`, block lifecycle is `ordered_block_*`, tool runs are
`tool_executed`, and memory writes are `memory_set` / `memory_cleared`.
`block_id` is the authored id (`submit`, `start`), not the compiled target id `{skill_id}__{block_id}`.
Inspector shows each `ordered_block_*` as a Block row.

`is_hint` on `tool_executed` classifies the result for later prompts. `false` is a
clean success. `true` is guidance, a partial apply, an error that a result hook
cleared, or a success that a result hook changed. It is unset for a run that did
not come from an LLM tool call, such as a confirmed tool run.

On later turns, a clean success from the built-in tools `set_memory`, `activate`,
`enter`, `complete`, and `cancel` is left out of the prompt once the agent has
replied to that turn. The event stays on the tracker. Errors, guidance, and
tools you define are always kept.

Session-start channel metadata is recorded as `memory_set` (key
`system.session_started_metadata`, after the session starts). A later session start
without channel metadata does not reuse the previous session's value.

A conversation that was started under CALM is not continued. Start it on a new
tracker. The turn is skipped and nothing is sent back. Operators see an error
log event named `mantle.turn.session_refused`.

## See also

* [The Runtime Loop](https://mantle.rasa.com/mantle/runtime-loop.md): the same loop, explained
* [Skills & Routing](https://mantle.rasa.com/mantle/skills.md#what-the-inspector-records): how Inspector shows these events
* [Constraint Table](https://mantle.rasa.com/reference/constraint-table.md): framework vs. LLM at each level
* [Tools reference](https://mantle.rasa.com/reference/tools.md): the built-in framework tools


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.