Struct ToolLoop 

pub struct ToolLoop<'a> {

    pub exec: ResolvedAgentExecution<'a>,
    pub history: &'a mut Vec<ChatMessage>,
    pub history_has_trim_breadcrumb: &'a mut bool,
    pub injected_memory_preamble: &'a mut Option<MemoryPreamble>,
    pub channel_name: &'a str,
    pub channel_reply_target: Option<&'a str>,
    pub cancellation_token: Option<CancellationToken>,
    pub on_delta: Option<Sender<DraftEvent>>,
    pub shared_budget: Option<ExecutionTreeBudget>,
    pub channel: Option<&'a dyn Channel>,
    pub collected_receipts: Option<&'a Mutex<Vec<String>>>,
    pub event_tx: Option<Sender<TurnEvent>>,
    pub steering: Option<&'a mut Receiver<SteeringInput>>,
    pub new_messages_out: Option<&'a mut Vec<ChatMessage>>,
    pub image_cache: Option<ToolLoopImageState<'a>>,
    pub ingress: IngressContext,
    pub memory: Option<TurnMemory<'a>>,
    pub agent_alias: Option<&'a str>,
    pub parent_agent_alias: Option<&'a str>,
    pub turn_id: &'a str,
    pub served_route_sink: Option<ServedRouteSink>,
    pub sop_reassembly: Option<SopStepReassembly<'a>>,
}

Fields

exec: ResolvedAgentExecution<'a>

The resolved per-agent execution context: model binding, gated tool registry, approval, observability, and resolved runtime knobs. Stable for every turn to this agent; built once and reused. See ResolvedAgentExecution. Everything below is per-message turn state.

history: &'a mut Vec<ChatMessage>

history_has_trim_breadcrumb: &'a mut bool

The history owner’s authoritative record that history carries the synthetic trim breadcrumb after its leading system messages. Provenance is tracked beside the buffer — never inferred from localized message text — so a genuine user turn equal to the breadcrumb string keeps its turn-boundary role and a persisted crumb stays classified across locale changes for the runtime’s lifetime. Trim paths write back any crumb they insert through this reference.

injected_memory_preamble: &'a mut Option<MemoryPreamble>

Out-param the loop writes through when it injects a recalled-memory preamble onto the last user message for this turn’s provider request only: the exact rendered block. Write-back strips that block solely from the injected message’s position in the mutated history buffer — pre-injection canonical clones are replayed with no strip target, so a genuine user text starting with the same block survives byte-for-byte. The exact string (this turn’s literal rendered content, never a generic marker pattern) is what confirms the recorded position still holds the injected message, following the same recorded-not-inferred principle as history_has_trim_breadcrumb.

channel_name: &'a str

channel_reply_target: Option<&'a str>

cancellation_token: Option<CancellationToken>

on_delta: Option<Sender<DraftEvent>>

shared_budget: Option<ExecutionTreeBudget>

channel: Option<&'a dyn Channel>

collected_receipts: Option<&'a Mutex<Vec<String>>>

event_tx: Option<Sender<TurnEvent>>

steering: Option<&'a mut Receiver<SteeringInput>>

new_messages_out: Option<&'a mut Vec<ChatMessage>>

image_cache: Option<ToolLoopImageState<'a>>

ingress: IngressContext

memory: Option<TurnMemory<'a>>

The per-turn memory half for unified memory-context injection: the handle, raw recall query, session scopes, and spawn-site suppression. None for nested sub-turn sites and paths without a memory backend; the injection decision itself is keyed on ingress.origin.

agent_alias: Option<&'a str>

Observer metadata: agent alias and turn id, stamped onto every turn-level observer event so OTel spans correlate across the loop. This is the EFFECTIVE agent — the one whose policy/tools/provider this loop actually runs with. A nested cross-agent SOP step runs its sub-loop with the step agent here, never the delegating parent’s.

parent_agent_alias: Option<&'a str>

The delegating agent’s alias when this loop is a nested cross-agent execution (a live SOP step naming a different agent). Stamped next to agent_alias on observer records so security/audit consumers see both the acting authority and its parent. None for ordinary turns.

turn_id: &'a str

served_route_sink: Option<ServedRouteSink>

Optional sink the caller reads after the loop to learn the route that actually served the final LLM call (provider/model + resolved limits). Written every dispatching iteration, so a per-call vision switch is captured even when the provider returns no usage. None on paths that do not publish a terminal snapshot (tests, nested sub-turns).

sop_reassembly: Option<SopStepReassembly<'a>>

Handle the live SOP driver uses to re-assemble a nested step’s execution context when the step delegates to a different agent (see SopStepReassembly). None on every path that cannot reach Config or that never drives nested SOP steps; when None, a cross-agent step FAILS CLOSED (the step errors rather than running with the parent agent’s broader context).