Struct ToolContext 

pub struct ToolContext {

    pub session_id: SessionId,
    pub workspace_id: WorkspaceId,
    pub file_store: Option<Arc<dyn SessionFileSystem>>,
    pub storage_store: Option<Arc<dyn SessionStorageStore>>,
    pub image_store: Option<Arc<dyn ImageArtifactStore>>,
    pub provider_credential_store: Option<Arc<dyn ProviderCredentialStore>>,
    pub utility_llm_service: Option<Arc<dyn UtilityLlmService>>,
    pub mcp_invoker: Option<Arc<dyn McpToolInvoker>>,
    pub egress_service: Option<Arc<dyn EgressService>>,
    pub message_retriever: Option<Arc<dyn MessageRetriever>>,
    pub session_store: Option<Arc<dyn SessionStore>>,
    pub agent_store: Option<Arc<dyn AgentStore>>,
    pub connection_resolver: Option<Arc<dyn UserConnectionResolver>>,
    pub schedule_store: Option<Arc<dyn SessionScheduleStore>>,
    pub subagent_delegate: Option<Arc<dyn SubagentSessionDelegate>>,
    pub extensions: ToolContextExtensions,
    pub leased_resource_store: Option<Arc<dyn LeasedResourceStore>>,
    pub session_resource_registry: Option<Arc<dyn SessionResourceRegistry>>,
    pub session_task_registry: Option<Arc<dyn SessionTaskRegistry>>,
    pub event_emitter: Option<Arc<dyn EventEmitter>>,
    pub event_context: Option<EventContext>,
    pub tool_call_id: Option<String>,
    pub capability_registry: Option<CapabilityRegistry>,
    pub tool_registry: Option<Arc<ToolRegistry>>,
    pub visible_tool_names: Option<Arc<HashSet<String>>>,
    pub org_id: Option<OrgId>,
    pub network_access: Option<NetworkAccessList>,
    pub locale: Option<String>,
    pub budget_checker: Option<Arc<dyn BudgetChecker>>,
    pub payment_authority: Option<Arc<dyn PaymentAuthority>>,
    pub session_creation_authority: Option<Arc<dyn SessionCreationAuthority>>,
    pub subagent_spawn_store: Option<Arc<dyn SubagentSpawnStore>>,
    pub subagent_nesting_policy: SubagentNestingPolicy,
    pub reasoning_effort_handle: Option<ReasoningEffortHandle>,
    pub cancellation: Option<CancellationToken>,
}

Runtime context provided to tools during execution.

This context contains:

• Session ID for scoping operations
• Optional stores for tools that need external access

Tools that need context-aware execution (like filesystem tools) can use the execute_with_context method on the Tool trait.

Fields

session_id: SessionId

The session ID for the current execution

workspace_id: WorkspaceId

The workspace this session is attached to — the key for the virtual file store. For the default 1:1 session this equals WorkspaceId::from_uuid(session_id.uuid()); for a shared workspace it differs. File-system tools MUST key by this (via workspace_fs_key) rather than session_id so shared-workspace sessions read/write the attached workspace’s files. See knowledge/runtime-resources/workspace.md.

file_store: Option<Arc<dyn SessionFileSystem>>

Optional file store for filesystem operations

storage_store: Option<Arc<dyn SessionStorageStore>>

Optional storage store for key/value and secret storage

image_store: Option<Arc<dyn ImageArtifactStore>>

Optional durable image artifact store for tool-side media persistence.

provider_credential_store: Option<Arc<dyn ProviderCredentialStore>>

Optional provider credential store for tool-side API clients.

utility_llm_service: Option<Arc<dyn UtilityLlmService>>

Optional system utility LLM service for capability internals.

mcp_invoker: Option<Arc<dyn McpToolInvoker>>

Optional scoped-MCP tool invoker for capability internals that need to call an MCP server out-of-band (e.g. the guardrails mcp check delegating a decision to an external guardrail endpoint). The invoker resolves connections and credentials per the current session/org, so tenant scoping is enforced by the host that supplies it.

egress_service: Option<Arc<dyn EgressService>>

Optional outbound egress service for HTTP/API traffic.

message_retriever: Option<Arc<dyn MessageRetriever>>

Optional message retriever for tools that need conversation history access

session_store: Option<Arc<dyn SessionStore>>

Optional session store for tools that need session metadata access.

agent_store: Option<Arc<dyn AgentStore>>

Optional agent store for tools that need agent metadata access.

connection_resolver: Option<Arc<dyn UserConnectionResolver>>

Optional resolver for user connection tokens (lazy GitHub token lookup, etc.)

schedule_store: Option<Arc<dyn SessionScheduleStore>>

Optional session schedule store for scheduling tools.

subagent_delegate: Option<Arc<dyn SubagentSessionDelegate>>

Optional narrow child-session delegate for host-provided orchestration. The hosted PlatformStore seam itself is not named by core; a host adapter implements this contract and platform tools use typed extensions.

extensions: ToolContextExtensions

Type-erased, host-supplied extensions keyed by concrete type. Lets crates layered above core (e.g. everruns-platform) hang typed services on the tool context without core naming them (EVE-839).

leased_resource_store: Option<Arc<dyn LeasedResourceStore>>

Optional leased resource store for lifecycle-managed provider resources.

session_resource_registry: Option<Arc<dyn SessionResourceRegistry>>

Optional session resource registry — generic registry of active resources.

session_task_registry: Option<Arc<dyn SessionTaskRegistry>>

Optional session task registry — background work owned by the session (knowledge/runtime-resources/session-tasks.md).

event_emitter: Option<Arc<dyn EventEmitter>>

Optional event emitter for tools that need to stream progress updates. When set, tools can emit tool.progress events during execution.

event_context: Option<EventContext>

Event context for correlating progress events with the current tool call. Set by ActAtom when constructing the ToolContext.

tool_call_id: Option<String>

The tool call ID for the current execution (set by ActAtom). Used by tools to emit correlated progress events.

capability_registry: Option<CapabilityRegistry>

Optional capability registry for blueprint lookups.

tool_registry: Option<Arc<ToolRegistry>>

Optional registry of active built-in tools for meta-tools such as spawn_background that need to inspect or delegate to sibling tools.

visible_tool_names: Option<Arc<HashSet<String>>>

Optional allowlist of tools visible to the model for this turn. Registry-introspecting tools must filter through this before returning sibling tool metadata, because the execution registry can be a superset.

org_id: Option<OrgId>

Optional org ID for org-scoped operations.

network_access: Option<NetworkAccessList>

Merged network access list (harness ∩ agent ∩ session). When set, tools that make HTTP requests must check URLs against this list.

locale: Option<String>

Resolved locale for localized tool behavior (BCP 47, e.g. uk-UA). When set, tools that support localization use this to produce locale-appropriate descriptions, error messages, and prompts.

budget_checker: Option<Arc<dyn BudgetChecker>>

Optional budget checker for the check_budget tool.

payment_authority: Option<Arc<dyn PaymentAuthority>>

Optional internal payment authority for paid capability tools.

session_creation_authority: Option<Arc<dyn SessionCreationAuthority>>

Optional host authority for detached peer-session creation.

subagent_spawn_store: Option<Arc<dyn SubagentSpawnStore>>

Optional durable spawn handle store for subagent reattach (EVE-535). When set, subagent delegation uses claim/settle to prevent duplicate spawning on parent worker reclaim.

subagent_nesting_policy: SubagentNestingPolicy

Resolved subagent nesting policy for this turn.

reasoning_effort_handle: Option<ReasoningEffortHandle>

Optional live reasoning-effort handle (EVE-595). When set, a tool can change the reasoning effort mid-turn; subsequent LLM steps in the same run_turn re-read it and use the new effort.

cancellation: Option<CancellationToken>

Cooperative cancellation for this tool call.

The act atom cancels it when the call ends by any means — the turn was cancelled, the act future was dropped, or the tool simply returned. A tool that only awaits inside its own future needs nothing here: dropping the future already stops it. This exists for work a tool starts and leaves running — a child process, a detached watcher task, a prompt waiting on an answer — which would otherwise outlive the call that created it. Clone the token into that work and let it die with the call.

Implementations

impl ToolContext

pub fn workspace_fs_key(&self) -> SessionId

The virtual-file-store key for this execution, derived from the attached workspace. Carried through the SessionFileSystem trait’s SessionId parameter (the store keys by .uuid()), so a shared-workspace session addresses the workspace’s files rather than its own session-id keyspace.

pub fn with_workspace_id(self, workspace_id: WorkspaceId) -> Self

Override the attached workspace (default is the 1:1 session-derived id).

pub fn new(session_id: SessionId) -> Self

Create a new tool context with just a session ID

pub fn from_services( session_id: SessionId, services: &ToolContextServices, ) -> Self

Construct a production tool context from a validated runtime service snapshot.

pub fn with_file_store( session_id: SessionId, file_store: Arc<dyn SessionFileSystem>, ) -> Self

Create a context with a file store

pub fn with_storage_store( session_id: SessionId, storage_store: Arc<dyn SessionStorageStore>, ) -> Self

Create a context with a storage store

pub fn with_stores( session_id: SessionId, file_store: Arc<dyn SessionFileSystem>, storage_store: Arc<dyn SessionStorageStore>, ) -> Self

Create a context with both file store and storage store

pub fn with_message_retriever( self, retriever: Arc<dyn MessageRetriever>, ) -> Self

Add a message retriever to this context

pub fn with_session_store(self, store: Arc<dyn SessionStore>) -> Self

Add a session store to this context.

pub fn with_cancellation(self, token: CancellationToken) -> Self

Add a live reasoning-effort handle (EVE-595). Tools can call ReasoningEffortHandle::set on it to change the effort used by subsequent LLM steps within the same turn. Attach a cancellation token to this context (see ToolContext::cancellation).

pub fn is_cancelled(&self) -> bool

Whether this call has already been cancelled. A context with no token never reports cancellation.

pub fn with_reasoning_effort_handle(self, handle: ReasoningEffortHandle) -> Self

pub fn with_agent_store(self, store: Arc<dyn AgentStore>) -> Self

Add an agent store to this context.

pub fn with_connection_resolver( self, resolver: Arc<dyn UserConnectionResolver>, ) -> Self

Add a connection resolver to this context

pub fn with_image_store( session_id: SessionId, image_store: Arc<dyn ImageArtifactStore>, ) -> Self

Create a context with an image artifact store.

pub fn with_provider_credential_store( self, store: Arc<dyn ProviderCredentialStore>, ) -> Self

Set the provider credential store on this context.

pub fn with_utility_llm_service( self, service: Arc<dyn UtilityLlmService>, ) -> Self

Set the utility LLM service on this context.

pub fn with_mcp_invoker(self, invoker: Arc<dyn McpToolInvoker>) -> Self

Set the scoped-MCP tool invoker on this context.

pub fn with_egress_service(self, service: Arc<dyn EgressService>) -> Self

Set the outbound egress service on this context.

pub fn with_egress_service_opt( self, service: Option<Arc<dyn EgressService>>, ) -> Self

Set the outbound egress service on this context when available. Preserves any already-set service when service is None.

pub fn with_storage_store_arc(self, store: Arc<dyn SessionStorageStore>) -> Self

Set the session storage store on this context (builder method).

pub fn with_schedule_store(self, store: Arc<dyn SessionScheduleStore>) -> Self

Add a session schedule store to this context.

pub fn with_subagent_delegate( self, delegate: Arc<dyn SubagentSessionDelegate>, ) -> Self

Add a narrow child-session delegate to this context (EVE-839).

pub fn with_extension<T: Any + Send + Sync>(self, value: Arc<T>) -> Self

Insert a type-keyed host extension (e.g. everruns-platform’s PlatformStoreExt) and return the updated context.

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

Resolve a type-keyed host extension previously inserted via Self::with_extension.

pub fn with_leased_resource_store( self, store: Arc<dyn LeasedResourceStore>, ) -> Self

Add a leased resource store to this context.

pub fn with_session_resource_registry( self, registry: Arc<dyn SessionResourceRegistry>, ) -> Self

Add a session resource registry to this context.

pub fn with_session_task_registry( self, registry: Arc<dyn SessionTaskRegistry>, ) -> Self

Add a session task registry to this context.

pub fn with_org_id(self, org_id: OrgId) -> Self

Set org ID for org-scoped operations.

pub fn with_tool_registry(self, registry: Arc<ToolRegistry>) -> Self

Set the active built-in tool registry on this context.

pub fn with_visible_tool_names(self, names: Arc<HashSet<String>>) -> Self

Set the tool names visible to the model in this turn.

pub fn with_network_access( self, network_access: Option<NetworkAccessList>, ) -> Self

Set the merged network access list for URL filtering.

pub fn with_payment_authority( self, authority: Arc<dyn PaymentAuthority>, ) -> Self

Set the internal payment authority for paid capability operations.

pub fn with_subagent_spawn_store( self, store: Arc<dyn SubagentSpawnStore>, ) -> Self

Set the durable subagent spawn handle store (EVE-535).

pub fn with_subagent_nesting_policy(self, policy: SubagentNestingPolicy) -> Self

Set the resolved subagent nesting policy.

pub async fn emit_progress(&self, tool_name: &str, message: &str)

Emit a tool.progress event if an event emitter and context are available.

This is a best-effort helper: failures are logged but not propagated, so tools never fail just because a progress event couldn’t be sent.

pub async fn emit_tool_output(&self, tool_name: &str, delta: &str, stream: &str)

Emit a tool.output.delta event if an event emitter and context are available.

Streams incremental output chunks (e.g., stdout/stderr lines) for live rendering in UI and CLI. Best-effort: failures are logged, not propagated.

Trait Implementations

impl Clone for ToolContext

fn clone(&self) -> ToolContext

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.