Trait ToolCtx 

pub trait ToolCtx: Send + Sync {
    // Required methods
    fn backend(&self) -> &Arc<dyn KernelBackend>;
    fn cwd(&self) -> &Path;
    fn resolve_path(&self, path: &str) -> PathBuf;
    fn var(&self, name: &str) -> Option<Value>;
    fn set_var(&mut self, name: &str, value: Value);
    fn set_output_format(&mut self, format: OutputFormat);
    fn as_any(&self) -> &dyn Any;
    fn as_any_mut(&mut self) -> &mut dyn Any;

    // Provided method
    fn patient(&self, budget: Duration) -> PatientGuard { ... }
}

The portable execution context a tool sees.

This is deliberately small: it carries only what a well-behaved, out-of-tree tool needs. The kernel’s full ExecContext implements this trait; trusted in-tree builtins that need deeper state (job control, streaming pipes, the dispatcher) downcast through ToolCtx::as_any_mut.

Send + Sync are supertraits because tool execution is async: a &dyn ToolCtx shared with an async helper is held across await points, and for the resulting future to be Send the referent must be Sync. The kernel’s ExecContext already satisfies both.

Required Methods

fn backend(&self) -> &Arc<dyn KernelBackend>

The backend for file I/O and tool dispatch.

Tools reach the VFS (and re-dispatch other tools) through this handle.

fn cwd(&self) -> &Path

The current working directory, as a VFS path.

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

Resolve a (possibly relative) path against the cwd, normalizing . and .. lexically. Never touches the real filesystem.

fn var(&self, name: &str) -> Option<Value>

Read a variable from the current scope, cloned.

Returns None if the name is unset. Tools use this for configuration supplied by the frontend (e.g. HOSTNAME).

fn set_var(&mut self, name: &str, value: Value)

Set a variable in the current scope.

fn set_output_format(&mut self, format: OutputFormat)

Set the per-execution output format override (e.g. from --json).

The dispatcher reads this after execute() returns and applies the format to the result.

fn as_any(&self) -> &dyn Any

Escape hatch for trusted in-tree tools: recover the concrete context.

Out-of-tree tools must not rely on this — downcasting to a kernel type is exactly the coupling this trait exists to avoid. It is here so in-tree builtins needing job control / pipes / the dispatcher can keep full access without those internals leaking into the public surface.

fn as_any_mut(&mut self) -> &mut dyn Any

Mutable counterpart to ToolCtx::as_any.

Provided Methods

fn patient(&self, budget: Duration) -> PatientGuard

Suspend the script-level timeout watchdog while the returned guard is held, bounding the patient operation by budget instead.

For tools that legitimately outlive a script timeout (model/provider calls that run minutes): while the guard is held the script clock freezes and the watchdog fires only if the hold outlives budget. On drop the script clock resumes with the remaining time it had at acquire. Only Rust tool code can obtain the guard — script code has no path to it, so the script-level budget keeps its teeth.

Cancellation stays live while suspended: Kernel::cancel() and the embedder token fire immediately — only the timer pauses. A patient tool must still select! its wait against the cancellation token.

The explicit timeout builtin is not suspended: a user-requested bound on a command keeps its teeth regardless of patient holds.

The default implementation returns an inert guard (no watchdog to suspend); the kernel’s context overrides it.

Dyn Compatibility

This trait is dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors