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 sqldb_store: Option<SessionSqlDbStoreRef>,
    pub message_retriever: Option<Arc<dyn MessageRetriever>>,
    pub session_store: Option<Arc<dyn SessionStore>>,
    pub session_mutator: Option<Arc<dyn SessionMutator>>,
    pub agent_store: Option<Arc<dyn AgentStore>>,
    pub connection_resolver: Option<Arc<dyn UserConnectionResolver>>,
    pub schedule_store: Option<Arc<dyn SessionScheduleStore>>,
    pub platform_store: Option<Arc<dyn PlatformStore>>,
    pub knowledge_store: Option<Arc<dyn KnowledgeStore>>,
    pub knowledge_index_search: Option<Arc<dyn KnowledgeIndexSearch>>,
    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>,
}

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 specs/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.

sqldb_store: Option<SessionSqlDbStoreRef>

Optional session SQL database store

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.

session_mutator: Option<Arc<dyn SessionMutator>>

Optional session mutator for tools that need to update session metadata.

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.

platform_store: Option<Arc<dyn PlatformStore>>

Optional platform store for org-level management tools.

knowledge_store: Option<Arc<dyn KnowledgeStore>>

Optional knowledge store backing the search_knowledge tool.

knowledge_index_search: Option<Arc<dyn KnowledgeIndexSearch>>

Optional hybrid retrieval over bound Knowledge Indexes for the search_index tool. Server-implemented; populated only on the server act path alongside platform_store / connection_resolver.

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 (specs/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.

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_sqldb_store(self, sqldb_store: SessionSqlDbStoreRef) -> Self

Add a SQL database store to this context

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_session_mutator(self, mutator: Arc<dyn SessionMutator>) -> Self

Add a session mutator to this context.

pub fn with_reasoning_effort_handle(self, handle: ReasoningEffortHandle) -> 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.

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_platform_store(self, store: Arc<dyn PlatformStore>) -> Self

Add a platform store to this context.

pub fn with_knowledge_index_search( self, search: Arc<dyn KnowledgeIndexSearch>, ) -> Self

Add a Knowledge Index search service to this context (for search_index).

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.