Struct ToolContext 

pub struct ToolContext { /* private fields */ }

Context passed to every tool execution.

Callers insert typed inbound values with insert. Tools read those values with get or require, and attach host-only result metadata with insert_result. Result hooks inspect that metadata through result. Neither inbound values nor result metadata are sent to the model.

Every value is data: inserting serializes it, reading deserializes it, and the whole context is itself Serialize + Deserialize. Explicit scene serialization can therefore contain sensitive inbound values and must be protected by the host. Effect logs record only ToolResultContext: values explicitly published through insert_result, never inbound slots or runtime scopes. Replay uses the current dispatch’s inbound context; code must not treat mutations to inbound slots as durable output. Values with interior sharing (Arc<Mutex<_>>, atomics, channels) do not belong here; they belong to the tool instance.

Registry, server, and agent dispatch clone inbound values once per call. Map-level mutations (inserting, replacing, or removing typed slots) affect only that execution. The dispatch surface returns result metadata without replacing the caller’s inbound slots.

Slots use the value type’s declared ContextValue::KEY. Accessors need no key argument; types must use distinct keys to occupy distinct slots.

Implementations

impl ToolContext

pub const fn new() -> Self

Create an empty context.

pub fn insert<T: ContextValue>( &mut self, value: T, ) -> Result<Option<T>, ToolContextError>

Insert an inbound typed value, returning the displaced value if it decodes as T. A differently shaped displaced value is replaced successfully and returns None; decoding the previous value cannot undo a successful write.

Returns an encoding error if serialization fails, leaving the slot unchanged.

pub fn get<T: ContextValue>(&self) -> Result<Option<T>, ToolContextError>

Read an inbound typed value: Ok(None) when absent, a decode error when the stored value does not match T.

pub fn require<T: ContextValue>(&self) -> Result<T, ToolContextError>

Require an inbound typed value.

pub fn remove<T: ContextValue>(&mut self) -> Result<Option<T>, ToolContextError>

Remove an inbound typed value. The slot is removed even if decoding its former value fails.

pub fn insert_result<T: ContextValue>( &mut self, value: T, ) -> Result<Option<T>, ToolContextError>

Attach host-only metadata to this execution’s result.

pub fn result<T: ContextValue>(&self) -> Result<Option<T>, ToolContextError>

Read host-only result metadata.

pub fn require_result<T: ContextValue>(&self) -> Result<T, ToolContextError>

Require host-only result metadata.

pub fn contains<T: ContextValue>(&self) -> bool

Whether this context contains the inbound type T.

pub fn is_empty(&self) -> bool

Whether both maps are empty.

pub fn for_dispatch(&self) -> Self

Build the snapshot one dispatch runs against: the same inbound values and no result metadata. Runtimes call this per tool call so map-level mutations inside the call cannot leak into the caller’s context.

pub fn with_scope(self, scope: Arc<dyn Any + Send + Sync>) -> Self

Attach one of the driver’s scopes for the call (see the field).

pub fn with_scopes(self, scopes: Vec<Arc<dyn Any + Send + Sync>>) -> Self

Attach the driver’s scopes for the call, as the sink carries them.

pub fn scope<T: Any + Send + Sync>(&self) -> Option<Arc<T>>

Returns the first attached scope of type T, or None if absent.

pub fn clear_scope(&mut self)

Drop the scopes: the call is over and the context is data again.

pub fn accept_dispatch_result(&mut self, dispatched: Self)

Publish the result metadata a dispatch produced (see Self::for_dispatch) while keeping the caller’s inbound values.

pub fn result_context(&self) -> ToolResultContext

Snapshot only the values explicitly published with insert_result.

pub fn with_result_context(self, result: ToolResultContext) -> Self

Restore durable output while preserving this dispatch’s inbound values.

pub fn clear_dispatch_result(&mut self)

Drop the previous dispatch’s result metadata before starting another.

Trait Implementations

impl Clone for ToolContext

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for ToolContext

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for ToolContext

fn default() -> Self

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for ToolContext

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Eq for ToolContext

impl PartialEq for ToolContext

fn eq(&self, other: &Self) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl Serialize for ToolContext

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.