Struct ToolContext 

pub struct ToolContext<Ctx> {
    pub app: Ctx,
    pub metadata: HashMap<String, Value>,
    /* private fields */
}

Context passed to tool execution

Fields

app: Ctx

Application-specific context (e.g., user_id, db connection)

metadata: HashMap<String, Value>

Tool-specific metadata

Implementations

impl<Ctx> ToolContext<Ctx>

pub fn new(app: Ctx) -> ToolContext<Ctx>

pub fn from_seed( seed: &ToolContextSeed, app: Ctx, deps: HostDependencies, ) -> ToolContext<Ctx>

Reconstruct a ToolContext from a durable seed and host-provided runtime dependencies.

This is the authoritative reconstruction path. Workers should use this (or a host’s crate::seed::ExecutionContextFactory) instead of chaining builder methods, so that the context shape is deterministic and auditable.

The event authority is constructed internally from ToolContextSeed::sequence_offset to guarantee monotonic sequencing — callers cannot accidentally supply a misaligned authority.

pub fn with_metadata( self, key: impl Into<String>, value: Value, ) -> ToolContext<Ctx>

pub fn with_event_store( self, store: Arc<dyn EventStore>, thread_id: ThreadId, turn: usize, authority: Arc<dyn EventAuthority>, ) -> ToolContext<Ctx>

Bind the tool context to the event store for a specific thread/turn.

pub async fn emit_event(&self, event: AgentEvent) -> Result<(), Error>

where Ctx: Sync,

Emit an event through the configured event store (if set).

The event is wrapped in an agent_sdk_foundation::AgentEventEnvelope with a unique ID, sequence number, and timestamp before publishing.

Errors

Returns an error if the configured event store cannot persist the event.

pub fn event_authority(&self) -> Option<Arc<dyn EventAuthority>>

Get a clone of the event authority (if set).

This is useful for tools that spawn subprocesses (like subagents) and need to wrap events with the same sequencing authority as the parent’s turn log.

pub fn with_cancel_token(self, token: CancellationToken) -> ToolContext<Ctx>

Set the cancellation token for propagating cancellation to subtasks.

pub fn cancel_token(&self) -> Option<CancellationToken>

Get the cancellation token (if set).

Used by tools that spawn long-running subtasks (like subagents) to propagate cancellation from the parent.

pub const fn with_tool_timeout(self, timeout: Duration) -> ToolContext<Ctx>

Set the per-tool execution timeout enforced at the SDK boundary.

The agent loop populates this from AgentConfig::tool_timeout_ms; callers can also set it directly when constructing a context.

pub const fn tool_timeout(&self) -> Option<Duration>

Get the per-tool execution timeout (if set).

Read by the agent loop’s SDK-boundary execution race; tools do not normally need to consult this themselves.

pub fn with_subagent_semaphore( self, semaphore: Arc<Semaphore>, ) -> ToolContext<Ctx>

Set a shared semaphore for limiting concurrent subagent threads.

pub fn subagent_semaphore(&self) -> Option<Arc<Semaphore>>

Get the subagent thread-limiting semaphore (if set).

Trait Implementations

impl<Ctx> Clone for ToolContext<Ctx>

where Ctx: Clone,

fn clone(&self) -> ToolContext<Ctx>

Returns a duplicate of the value.

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

Performs copy-assignment from source.