Struct TurnRunner 

pub struct TurnRunner<'a> {

    pub history: &'a dyn History,
    pub tools: &'a dyn ToolRegistry,
    pub session_tools: Option<Arc<dyn ToolRegistry>>,
    pub provider: &'a dyn LlmProvider,
    pub policy: Arc<dyn SandboxPolicy>,
    pub events: Arc<EventEmitter>,
    pub permissions: &'a PermissionGate,
    pub cancel: CancellationToken,
    pub config: &'a TurnConfig,
    pub config_arc: Option<Arc<TurnConfig>>,
    pub system_prompt: Option<Arc<str>>,
    pub cwd: &'a Path,
    pub fs: Arc<dyn FsBackend>,
    pub shell: Arc<dyn ShellBackend>,
    pub http: Arc<dyn HttpClient>,
    pub hosted_capabilities: HostedCapabilities,
    pub hooks: &'a dyn HookEngine,
    pub session_id: &'a SessionId,
    pub background: Option<BackgroundTasks>,
    pub goal: Option<Arc<GoalState>>,
    pub compaction_slot: Option<CompactionSlot>,
    pub history_arc: Option<Arc<dyn History>>,
    pub provider_arc: Option<Arc<dyn LlmProvider>>,
    pub session_cancel: Option<CancellationToken>,
    pub ingest_source: IngestSource,
    /* private fields */
}

All dependencies and accumulated state for a single turn execution.

This struct is constructed by crate::session::DefaultSession on each run_turn call, borrowing sub-components of the session and being dropped after the turn completes.

Fields

history: &'a dyn History

tools: &'a dyn ToolRegistry

session_tools: Option<Arc<dyn ToolRegistry>>

The same session tool pool as Self::tools, but as an owned Arc so it can be injected into crate::tool::ToolContext (which needs 'static/owned). Carries the fully assembled composite (built-in + MCP) so spawn_agent can build a child agent’s tool subset that includes mcp__* tools. None in legacy/test runners that only set the borrow.

provider: &'a dyn LlmProvider

policy: Arc<dyn SandboxPolicy>

The active policy for this turn’s snapshot. Owned as an Arc rather than borrowed: it flows with crate::tool::ToolContext into spawn_agent, where child agents wrap it with NonInteractivePolicy — must be the parent’s actual policy at this moment.

events: Arc<EventEmitter>

permissions: &'a PermissionGate

cancel: CancellationToken

config: &'a TurnConfig

config_arc: Option<Arc<TurnConfig>>

The same turn config as Self::config, as an owned Arc for injection into crate::tool::ToolContext so spawn_agent can let a child agent inherit the parent’s turn settings. None in legacy/test runners that only set the borrow.

system_prompt: Option<Arc<str>>

The system prompt resolved for this turn. Arc<str>: each build_request call clones it into CompletionRequest.system; the Arc reduces this to a reference count increment.

cwd: &'a Path

fs: Arc<dyn FsBackend>

shell: Arc<dyn ShellBackend>

http: Arc<dyn HttpClient>

hosted_capabilities: HostedCapabilities

Hosted capabilities determined at session startup. Reused directly on each turn when assembling requests, without re-querying.

hooks: &'a dyn HookEngine

Hook engine. The turn main loop emits Sync events at four points (UserPromptSubmit / PreToolUse / PostToolUse / PostToolUseFailure). Waits for hooks to finish before proceeding.

session_id: &'a SessionId

Current session ID. Injected into HookCtx so that hook handlers can route or audit by session.

background: Option<BackgroundTasks>

Session-level background task handle. When Some, enables the tool’s run_in_background capability (injected into tools via crate::tool::ToolContext::background); nested sub-agent turns receive None, structurally preventing background task self-replication.

goal: Option<Arc<GoalState>>

Shared state for the --goal goal-driven loop. When Some, this session is running in goal mode: it is injected into the goal_done tool via crate::tool::ToolContext::goal, and the goal-gate hook uses it in before_turn_end to allow or extend the session. None = non-goal mode (default).

compaction_slot: Option<CompactionSlot>

Session-level single-flight compaction slot. When Some, background full compaction is available — exceeding the soft watermark triggers an async summary compaction without blocking the current turn. Nested sub-agent turns pass None (sub-agent contexts are short-lived and should not spawn background tasks). Requires Arc<dyn History>/Arc<dyn LlmProvider> for the task to hold 'static references across turns, hence the accompanying history_arc/provider_arc.

history_arc: Option<Arc<dyn History>>

Arc<dyn History> for compaction_slot (points to the same object as the history borrow). Held by the background compaction task across turns. When None, background compaction is unavailable and falls back to synchronous compaction only.

provider_arc: Option<Arc<dyn LlmProvider>>

Arc for the provider used by compaction_slot. Same as above.

session_cancel: Option<CancellationToken>

Session-level cancellation token; the background compaction task’s cancellation token is derived from this one (independent of the turn’s cancel, cancelled when the session ends). When None, background compaction uses the turn’s cancel (sub-agent path).

ingest_source: IngestSource

The ingestion source for this turn’s input — determines the source field of the before_ingest step envelope. User turns use User; background continuation turns started by the session driver use Background.

Implementations

impl<'a> TurnRunner<'a>

pub async fn run( &self, prompt: Vec<ContentBlock>, ) -> Result<AcpStopReason, TurnError>

Runs a single turn.