Struct ToolContext 

pub struct ToolContext {

    pub project_root: String,
    pub extra_roots: Vec<String>,
    pub minimal: bool,
    pub resolved_paths: HashMap<String, String>,
    pub crp_mode: CrpMode,
    pub cache: Option<SharedCache>,
    pub session: Option<Arc<RwLock<SessionState>>>,
    pub tool_calls: Option<Arc<RwLock<Vec<ToolCallRecord>>>>,
    pub agent_id: Option<Arc<RwLock<Option<String>>>>,
    pub workflow: Option<Arc<RwLock<Option<WorkflowRun>>>>,
    pub ledger: Option<Arc<RwLock<ContextLedger>>>,
    pub client_name: Option<Arc<RwLock<String>>>,
    pub client_role: Option<String>,
    pub shell_access: Option<bool>,
    pub pipeline_stats: Option<Arc<RwLock<PipelineStats>>>,
    pub call_count: Option<Arc<AtomicUsize>>,
    pub autonomy: Option<Arc<AutonomyState>>,
    pub pressure_snapshot: Option<ContextPressure>,
    pub path_errors: HashMap<String, String>,
    pub bm25_cache: Option<Arc<Mutex<Option<Bm25CacheEntry>>>>,
    pub progress_sender: Option<SharedProgressSender>,
}

Context passed to tool handlers. Contains pre-resolved values that many tools need, avoiding repeated async lock acquisition inside handlers. Extended with shared server state for tools that need cache/session access.

Clone exists for per-op delegation (#1088): a batch op with its own path clones the ctx and swaps in that op’s resolved path.

Fields

project_root: String

extra_roots: Vec<String>

Session-scoped trusted roots (MCP roots/list, config extra_roots), snapshotted from the session so sync handlers can honor them without an async lock. Empty = single-root jail behaviour (#403).

minimal: bool

resolved_paths: HashMap<String, String>

Pre-resolved paths keyed by argument name (e.g. “path” -> “/abs/dir”).

crp_mode: CrpMode

CRP mode for compression-aware tools.

cache: Option<SharedCache>

Shared cache handle for tools that need read/write access.

session: Option<Arc<RwLock<SessionState>>>

Shared session handle for tools that need session access.

tool_calls: Option<Arc<RwLock<Vec<ToolCallRecord>>>>

Tool call records for session-aware tools (e.g. ctx_session status).

agent_id: Option<Arc<RwLock<Option<String>>>>

Current agent identity for multi-agent tools.

workflow: Option<Arc<RwLock<Option<WorkflowRun>>>>

Active workflow run state.

ledger: Option<Arc<RwLock<ContextLedger>>>

Context ledger for handoff operations.

client_name: Option<Arc<RwLock<String>>>

Client name (cursor, claude, etc.).

client_role: Option<String>

Optional MCP client role supplied by the session/request context. Absent preserves the backward-compatible permissive default.

shell_access: Option<bool>

Optional shell permission supplied by the session/request context. None preserves the backward-compatible permissive default.

pipeline_stats: Option<Arc<RwLock<PipelineStats>>>

Pipeline stats for metrics/proof tools.

call_count: Option<Arc<AtomicUsize>>

Global call counter for context tools.

autonomy: Option<Arc<AutonomyState>>

Autonomy state for search repeat detection.

pressure_snapshot: Option<ContextPressure>

Pre-computed context pressure snapshot for synchronous gate decisions.

path_errors: HashMap<String, String>

Errors from path resolution (PathJail rejection, secret path, etc.). Keyed by argument name (e.g. “path” -> “path escapes project root: …”).

bm25_cache: Option<Arc<Mutex<Option<Bm25CacheEntry>>>>

Shared in-memory BM25 index cache for semantic search.

progress_sender: Option<SharedProgressSender>

MCP progress notification sender for long-running operations.

Implementations

impl ToolContext

pub fn resolved_path(&self, arg: &str) -> Option<&str>

pub fn path_error(&self, key: &str) -> Option<&str>

Returns the path resolution error for a given key, if any.

pub fn resolve_path_sync(&self, path: &str) -> Result<String, String>

Sync path resolution using project_root + session extra_roots. Thin wrapper over crate::core::path_resolve::resolve_tool_path_with_roots for sync tool handlers.

pub fn ensure_writable(&self, resolved_path: &str) -> Result<(), String>

Default-deny write gate for the read-only tier (#475). Write-capable tool handlers must call this with an already-resolved absolute path before touching the filesystem; it errors if the path is inside a configured read_only_roots subtree. A no-op (always Ok) when no read-only roots are configured, so non-users pay nothing. Thin wrapper over the single choke point crate::core::pathjail::enforce_writable — the low-level atomic writers call the same function, so this is the ergonomic, early-error layer, not the only line of defence.

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 Default for ToolContext

fn default() -> Self

Minimal context: project_root empty, all shared-state handles None. Single source for the one-shot CLI ctx (cli::call_cmd::oneshot_ctx) and the empty_ctx test helper — adding a field no longer breaks either.