Struct ToolContext 

pub struct ToolContext {

    pub cwd: PathBuf,
    pub sandbox: SandboxPolicy,
    pub multimodal_read: bool,
    pub require_read_before_edit: bool,
    pub read_paths: Arc<Mutex<HashSet<PathBuf>>>,
    pub notebook_aware: bool,
    pub shell_env: Option<Arc<HashMap<String, String>>>,
    pub nested_instructions: bool,
    pub injected_instruction_dirs: Arc<Mutex<HashSet<PathBuf>>>,
    pub network_policy: Option<NetworkPolicy>,
    pub bash_timeout_secs: Option<u64>,
    pub write_observer: Option<Arc<dyn WriteObserver>>,
    pub sandbox_os_enabled: Option<bool>,
    pub sandbox_escalation: SandboxEscalation,
    pub sandbox_env_policy: SandboxEnvPolicy,
    pub sandbox_approval_handler: Option<SandboxApprovalHandler>,
}

Ambient context passed to every tool invocation.

Fields

cwd: PathBuf

The working directory tools resolve relative paths against.

sandbox: SandboxPolicy

Filesystem confinement for write-capable tools.

multimodal_read: bool

P4c (S1.2 core.tools.read_file.multimodal): whether read_file (and view_image, unconditionally) returns a recognized image file as a model-visible image content block. false (the default) is byte-identical to today’s UTF-8-lossy-decode behavior.

require_read_before_edit: bool

P4c (S1.2 core.tools.edit_file.require_read_before_edit, UNIQUE CC row): whether edit_file refuses a path not yet read this conversation. false (the default) is byte-identical to today’s behavior — Self::read_paths is simply never consulted.

read_paths: Arc<Mutex<HashSet<PathBuf>>>

P4c: canonicalized paths read_file has successfully read so far this conversation — shared (via Arc<Mutex<_>>) across every clone of this context, since Agent constructs one ToolContext at startup and reuses it for every tool call. Consulted by EditFileTool only when Self::require_read_before_edit is true.

notebook_aware: bool

P4c (S1.2 core.tools.edit_file.notebook_aware, UNIQUE CC row “NotebookEdit”): whether edit_file accepts Jupyter cell replace/insert/delete operations against a .ipynb target. false (the default) is byte-identical to today’s exact-string-replace-only behavior.

shell_env: Option<Arc<HashMap<String, String>>>

P4c (S1.2 core.shell_env_snapshot): the user’s captured interactive-shell environment, if crate::Config::shell_env_snapshot is on — BashTool/PersistentShellTool merge this into the spawned process’s environment. None (the default) is byte-identical to today’s behavior: no extra environment is injected.

nested_instructions: bool

P4c (S1.4 core.nested_instructions, deferred from P4b): whether a file-touching tool injects an as-yet-unseen subdirectory’s own CLAUDE.md/AGENTS.md into its result the first time a path under it is touched. false (the default) is byte-identical to today’s behavior.

injected_instruction_dirs: Arc<Mutex<HashSet<PathBuf>>>

P4c: subdirectories (relative to Self::cwd) whose nested instructions have already been injected this conversation — shared across clones, same rationale as Self::read_paths. Consulted only when Self::nested_instructions is true.

network_policy: Option<NetworkPolicy>

P4c (S2 module 5 tools.web, S17): the network-domain policy web_fetch/web_search must respect, if one is configured. None (the default) means no policy is enforced — see NetworkPolicy’s doc comment for the honest-gap rationale.

bash_timeout_secs: Option<u64>

P4e (S3.1 core.tools.bash.timeout_secs, S14): the DEFAULT execution timeout (seconds) BashTool::execute falls back to when a model-issued call carries no timeout_ms argument of its own – see crate::config::ToolOverride::timeout_secs. None (the default) is byte-identical to today’s behavior: BashTool’s built-in DEFAULT_BASH_TIMEOUT_MS (120s) stands.

write_observer: Option<Arc<dyn WriteObserver>>

P5-9 (§2 module 20, D-5 shared write-path interception seam) — see WriteObserver’s doc comment. None (the default) is a true no-op: every write-tool call site’s if let Some(obs) = ... branch is simply never taken.

sandbox_os_enabled: Option<bool>

P5-10 (§2 module 12 permissions.sandbox): whether the OS-level backstop (Landlock/seatbelt) is engaged for the bash/shell subprocess — see crate::sandbox::os_sandbox_active. None (the default) preserves the pre-P5-10 trigger (confine whenever Self::sandbox isn’t SandboxPolicy::DangerFullAccess).

sandbox_escalation: SandboxEscalation

P5-10 (§2 module 12, escalation): what to do when a confining fs tier can’t actually be enforced on this platform/kernel — see crate::sandbox::SandboxEscalation. Defaults to Deny (fail-closed).

sandbox_env_policy: SandboxEnvPolicy

P5-10 (§2 module 12, env_policy): child-process environment sanitization for the spawned subprocess — see crate::sandbox::SandboxEnvPolicy. Defaults to Inherit (byte-identical to pre-P5-10 behavior).

sandbox_approval_handler: Option<SandboxApprovalHandler>

P5-10 (§2 module 12, escalation = "ask" → permissions.approvals, P5-1): the ambient handler crate::sandbox::decide_fs consults for an ask-tier sandbox-unenforceable decision. None (the default — no handler installed) is fail-closed, same posture as the P5-1 rule engine’s own Ask tier with no handler.

Implementations

impl ToolContext

pub fn new(cwd: impl Into<PathBuf>) -> Self

A context rooted at cwd with no confinement.

pub fn os_sandbox_active(&self) -> bool

P5-10: whether the OS-level backstop is active for this context — thin wrapper over crate::sandbox::os_sandbox_active.

pub fn mark_read(&self, path: &Path)

P4c: record path (canonicalized if possible, else the resolved path as-is) as having been read this conversation — called by ReadFileTool on every successful read, unconditionally (cheap; the set is only ever CONSULTED when Self::require_read_before_edit is on, but recording it unconditionally means turning the knob on mid-conversation sees every read that already happened).

pub fn was_read(&self, path: &Path) -> bool

P4c: whether path was previously recorded via Self::mark_read.

pub fn check_network(&self, url: &str) -> Result<()>

P4c (S2.1 S17): does url pass Self::network_policy, if one is configured? Ok(()) when no policy is set (the honest-gap default) or the policy is present-but-disabled; Err names the reason otherwise. A URL with no parseable host is denied whenever a policy is actively enforced (fail closed — an unparseable host can’t be matched against an allowlist).

pub fn resolve(&self, path: &str) -> PathBuf

Resolve a possibly-relative path against the working directory.

pub fn check_write(&self, path: &Path) -> Result<()>

Enforce the sandbox policy for a write to path. Err if denied.

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.