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 path_errors: HashMap<String, String>,
    pub bm25_cache: Option<SharedBm25Cache>,
    pub progress_sender: Option<SharedProgressSender>,
    pub cancel: Option<CancellationToken>,
}

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.

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<SharedBm25Cache>

Shared in-memory BM25 index cache for semantic search.

progress_sender: Option<SharedProgressSender>

MCP progress notification sender for long-running operations.

cancel: Option<CancellationToken>

Cancellation token for this request, when the transport supplies one (#1781).

A synchronous tool that waits on a child process cannot observe an aborted call without it: the host stops waiting, but the wait loop keeps running and holds its thread until its own cap expires. Tools that block should consult this and return promptly when it fires.

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 lean_ctx::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 lean_ctx::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) -> Self

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.