Struct ToolContext 

pub struct ToolContext { /* private fields */ }

Proof that a tool invocation has passed the capability leash, carrying the least-authority caveats it is permitted to act under.

Constructible only inside this crate (see ToolContext::mint, called solely by crate::Gate::authorize). There is intentionally no public constructor and no pub field — that un-forgeability is the enforcement.

Implementations

impl ToolContext

pub fn caveats(&self) -> &Caveats

The effective (least-authority) caveats this invocation may act under.

pub fn sandbox_kind(&self) -> SandboxKind

The OS-level sandbox actually in force for this invocation.

pub fn strength_floor(&self) -> AxisEnforcement

The required fence strength (ADR 0012 D3): a confinement site refuses to spawn when the real backend cannot enforce every restricted axis at or above this floor. Default is the permissive AxisEnforcement::Advisory (set on the crate::Gate); a strong principal raises it to Kernel.

pub fn check_exec(&self, program: &str) -> Result<(), ToolError>

Leash check: may this invocation execute program?

Allowed iff exec is All, or the bounded exec scope contains the program as named (the string passed in, typically argv0 or a PATH-resolved absolute path) or its basename (Path::new(program).file_name()).

This is what makes bare-name grants usable: a grant of ["git"] allows git, /usr/bin/git, and /opt/homebrew/bin/git alike, because the resolved absolute path the interceptor hands in has basename git. To pin an exact executable instead, grant a full path: a grant of ["/usr/bin/git"] matches only /usr/bin/git, not a git found elsewhere on PATH.

Security tradeoff: a bare-name grant authorizes any binary named git reachable on PATH (PATH ordering / shadowing decides which one actually runs). When that ambiguity is unacceptable, grant the full path to pin exactly. A grant that contains a path separator only ever matches that exact path (its basename is still considered, but a grant like ["/bin/echo"] will not be matched by a bare echo because the grant’s own basename echo is compared against the program token, not the reverse — see [exec_scope_allows]). Out-of-scope programs are denied here, before the tool spawns anything.

pub fn check_net(&self, host: &str) -> Result<(), ToolError>

Leash check: may this invocation reach network host?

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

Leash check: may this invocation read path?

See Self::check_path_write for the canonicalization contract; the only difference is which axis (fs_read) is consulted.

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

Leash check: may this invocation write path?

Canonicalizes first, then tests membership (DESIGN §6): the path is resolved to a real, symlink-free location and rejected if it escapes the granted scope via .. or a symlink. Membership is a containment test against each granted scope entry (an entry authorizes that path and its descendants), computed on canonical paths — never a raw string prefix. This closes the @repo/../../etc traversal class.

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.