Struct TurnContext 

pub struct TurnContext {
    pub messages: Arc<Vec<Message>>,
    pub step_events_tx: Option<UnboundedSender<AgentEvent>>,
    pub tool_specs: Vec<ToolSpec>,
    pub streaming: bool,
    pub permission_hook: Option<Arc<dyn PermissionHook>>,
    pub exploring_plan_mode: Arc<AtomicBool>,
    pub permission_mode: PermissionMode,
    pub mailbox: Option<WorkerMailbox>,
    pub turn: u32,
    pub prompt_segments: Option<PromptSegments>,
    pub wall_timeout_secs: u64,
}

Everything the Kernel needs to execute one turn.

Prepared by the Wrapper (AgentRuntime). The Kernel does not know where these messages came from — could be fresh, compacted, or resumed.

Ownership

messages is an owned copy of the wrapper’s transcript. The kernel takes ownership and may mutate it freely during the ReAct loop (trimming old tool results, intra-turn compaction). The wrapper retains the canonical transcript and incorporates only the new messages from TurnOutcome::new_messages after the turn completes.

A full clone per turn is intentional: RunCore mutates the list in-place, so sharing via Arc would not eliminate the allocation. The clone is bounded by the max_transcript_chars trim that runs before each turn.

Fields

messages: Arc<Vec<Message>>

Shared reference to the wrapper’s transcript for this turn.

The kernel may mutate this list in-place via Arc::make_mut; the wrapper’s canonical transcript is unaffected until the kernel drops its reference.

step_events_tx: Option<UnboundedSender<AgentEvent>>

Channel to send agent events to the caller (runtime or test harness).

The kernel passes this channel directly to RunCore (Goal 219 Commit 1), so callers receive the same AgentEvent stream the kernel sees — no internal conversion.

tool_specs: Vec<ToolSpec>

Tool specifications to advertise to the LLM.

streaming: bool

Whether to stream LLM responses token-by-token.

permission_hook: Option<Arc<dyn PermissionHook>>

Optional permission hook for gating tool calls.

exploring_plan_mode: Arc<AtomicBool>

Goal-165: shared flag that enables agent-driven read-only plan mode. When true, write tools are blocked until exit_plan_mode is called.

permission_mode: PermissionMode

Goal-190: default permission mode for tools not covered by explicit config lists. Mirrors PermissionsConfig.mode for quick access.

mailbox: Option<WorkerMailbox>

Optional mailbox for mid-run message injection from a coordinator.

When set, the kernel drains this mailbox at the start of every step and appends any pending messages as user turns. This powers the send_message tool’s bidirectional coordinator ↔ worker flow.

turn: u32

Turn index (0-based), used to scope crate::tools::AuditMeta keys so that tool-call-id collisions across turns cannot cause audit metadata to be overwritten or lost.

prompt_segments: Option<PromptSegments>

Goal-328: structured prompt segments from assemble_system_prompt, forwarded to RunCore so it can size the static breakdown buckets. None when the caller did not provide one (legacy channels, tests).

wall_timeout_secs: u64

Goal 345: wall-clock timeout in seconds. When > 0, the step loop checks elapsed time and terminates cleanly with FinishReason::WallClockExceeded. Default 0 = unset.