Struct ToolContext 

pub struct ToolContext {
    pub working_directory: String,
    pub user_id: Option<String>,
    pub metadata: HashMap<String, String>,
    pub capabilities: Option<Value>,
    pub idempotency_registry: Option<IdempotencyRegistry>,
    pub staging_backend: Option<Arc<dyn StagingBackend>>,
    pub intended_writes: Option<IntendedWrites>,
}

Execution context for a tool.

Provides the working directory, optional metadata, and permission capabilities to tool implementations.

Fields

working_directory: String

Current working directory for resolving relative paths

user_id: Option<String>

User ID (if authenticated)

metadata: HashMap<String, String>

Additional context data (application-specific key-value pairs)

capabilities: Option<Value>

Agent capabilities for permission checks (serialized as JSON value).

Consumers should serialize their concrete capability types into this field and deserialize when reading. This keeps the core crate free of capability type definitions.

idempotency_registry: Option<IdempotencyRegistry>

Per-run idempotency registry for mutating file operations.

When Some, write/delete/edit operations derive a content-addressed key and skip re-execution if the same key has already been processed in this run. None disables idempotency tracking (useful for tests or simple single-call use cases).

staging_backend: Option<Arc<dyn StagingBackend>>

Optional two-phase commit staging backend.

When Some, mutating file operations (write_file, edit_file, patch_file) stage their writes instead of applying them immediately. The caller is responsible for calling backend.commit() to finalize the writes, or backend.rollback() to discard them.

Staging is checked after the idempotency registry: if the same operation key is already cached, the cached result is returned without staging again.

intended_writes: Option<IntendedWrites>

Optional shared registry that tracks (path -> SHA-256) for every successful write_file in this run.

When Some, write_file records the hash of its content after the post-write read-back succeeds. The agent’s validation loop then re-reads each tracked file at finalisation and compares to detect post-validation clobber by a concurrent writer.

None disables hash tracking (CLI-driven tool invocations outside an agent). The cost of tracking is a HashMap insert per write.

Implementations

impl ToolContext

pub fn with_idempotency_registry(self) -> ToolContext

Attach a fresh idempotency registry to this context (builder pattern).

pub fn with_staging_backend( self, backend: Arc<dyn StagingBackend>, ) -> ToolContext

Attach a staging backend for two-phase commit file writes (builder pattern).

pub fn with_intended_writes(self) -> ToolContext

Attach a fresh intended-writes registry (builder pattern).

pub fn with_intended_writes_registry( self, registry: IntendedWrites, ) -> ToolContext

Attach an existing intended-writes registry — useful when the agent owns the registry and wants tool calls to share it (builder pattern).

pub fn record_write(&self, path: PathBuf, hash: [u8; 32])

Record the SHA-256 of content written to path in the attached intended-writes registry. No-op when no registry is attached (e.g., CLI-driven tool invocations outside an agent).

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<(), Error>

Formats the value using the given formatter.

impl Default for ToolContext

fn default() -> ToolContext

Returns the “default value” for a type.