Struct ExecContext 

pub struct ExecContext {

    pub backend: Arc<dyn KernelBackend>,
    pub scope: Scope,
    pub cwd: PathBuf,
    pub prev_cwd: Option<PathBuf>,
    pub stdin: Option<String>,
    pub stdin_data: Option<Value>,
    pub stdin_data_rx: Option<Receiver<Option<Value>>>,
    pub pipe_stdin: Option<PipeReader>,
    pub pipe_stdout: Option<PipeWriter>,
    pub tool_schemas: Vec<ToolSchema>,
    pub tools: Option<Arc<ToolRegistry>>,
    pub job_manager: Option<Arc<JobManager>>,
    pub stderr: Option<StderrStream>,
    pub pipeline_position: PipelinePosition,
    pub interactive: bool,
    pub aliases: HashMap<String, String>,
    pub ignore_config: IgnoreConfig,
    pub output_limit: OutputLimitConfig,
    pub allow_external_commands: bool,
    pub nonce_store: NonceStore,
    pub trash_backend: Option<Arc<dyn TrashBackend>>,
    pub dispatcher: Option<Arc<dyn CommandDispatcher>>,
    pub cancel: CancellationToken,
    pub output_format: Option<OutputFormat>,
    pub current_invocation: Option<Box<(String, Vec<String>)>>,
    pub vfs_budget: Option<Arc<ByteBudget>>,
    pub watchdog: Option<Arc<Watchdog>>,
    pub overlay_handle: Option<Arc<OverlayHandle>>,
}

Execution context passed to tools.

Provides access to the backend (for file operations and tool dispatch), scope, and other kernel state.

Fields

backend: Arc<dyn KernelBackend>

Kernel backend for I/O operations.

This is the preferred way to access filesystem operations. Use backend.read(), backend.write(), etc.

scope: Scope

Variable scope.

cwd: PathBuf

Current working directory (VFS path).

prev_cwd: Option<PathBuf>

Previous working directory (for cd -).

stdin: Option<String>

Standard input for the tool (from pipeline).

stdin_data: Option<Value>

Structured data from pipeline (pre-parsed JSON from previous command). Tools can check this before parsing stdin to avoid redundant JSON parsing.

stdin_data_rx: Option<Receiver<Option<Value>>>

Sideband receiver for the previous stage’s structured .data, set by the concurrent pipeline runner. Resolved lazily via Self::resolve_stdin AFTER the pipe is drained — never pre-read — so a streaming upstream that only sends its data after writing the pipe can’t deadlock a consumer that awaits it. Non-Clone, so it’s moved on resolve.

pipe_stdin: Option<PipeReader>

Streaming pipe input (set when this command is in a concurrent pipeline).

pipe_stdout: Option<PipeWriter>

Streaming pipe output (set when this command is in a concurrent pipeline).

tool_schemas: Vec<ToolSchema>

Tool schemas for help command.

tools: Option<Arc<ToolRegistry>>

Tool registry reference (for tools that need to inspect available tools).

job_manager: Option<Arc<JobManager>>

Job manager for background jobs (optional).

stderr: Option<StderrStream>

Kernel stderr stream for real-time error output from pipeline stages.

When set, pipeline stages write stderr here instead of buffering in ExecResult.err. This allows stderr from all stages to stream to the terminal (or other sink) concurrently, matching bash behavior.

pipeline_position: PipelinePosition

Position of this command within a pipeline (for stdio decisions).

interactive: bool

Whether we’re running in interactive (REPL) mode.

aliases: HashMap<String, String>

Command aliases (name → expansion string).

ignore_config: IgnoreConfig

Ignore file configuration for file-walking tools.

output_limit: OutputLimitConfig

Output size limit configuration for agent safety.

allow_external_commands: bool

Whether external command execution is allowed.

When false, external commands (PATH lookup, exec, spawn) are blocked. Only kaish builtins and backend-registered tools (MCP) are available.

nonce_store: NonceStore

Confirmation nonce store for latch-gated operations.

Arc-shared across pipeline stages so nonces issued in one stage can be validated in another.

trash_backend: Option<Arc<dyn TrashBackend>>

Trash backend for safe file deletion.

Always present when the kernel creates the context (even if set -o trash is off — the backend exists so kaish-trash list/restore/empty work regardless of the trash flag).

dispatcher: Option<Arc<dyn CommandDispatcher>>

Command dispatcher for re-dispatching through the full resolution chain.

When set (via Kernel::into_arc()), builtins like timeout can dispatch inner commands through the full chain (user tools → builtins → .kai scripts → external commands) instead of being limited to backend.call_tool().

None when the Kernel was not wrapped via into_arc().

cancel: CancellationToken

Cancellation token for this execution path.

Populated by the kernel at execute entry, then propagated through pipeline stages, foreground forks (scatter workers, concurrent pipeline stages, $(...) cmdsubs), and into spawned external children. When the token fires, externals receive SIGTERM/SIGKILL via the wait_or_kill helper.

Default for stand-alone ExecContext constructors is a fresh, never-fired token so non-kernel test contexts behave as before.

output_format: Option<OutputFormat>

Per-execution output format override set by a builtin’s GlobalFlags flatten (e.g. --json). The dispatcher reads this after tool.execute() returns and applies the format via apply_output_format.

Builtins set this via GlobalFlags::apply(ctx); external commands don’t touch it.

current_invocation: Option<Box<(String, Vec<String>)>>

The command currently executing, captured at the dispatch seam as (dispatch_name, argv) where argv is the canonical ToolArgs::to_argv. A latch producer (latch_result/gate_overwrites) stamps this into the LatchRequest so Kernel::confirm can replay the exact invocation with --confirm=<nonce> — no re-parsing of the human hint. None for a direct tool.execute call in a unit test (no dispatch seam ran).

Boxed to keep ExecContext lean: it is cloned/rebuilt at every recursion level (pipeline stages, $(...), functions), so an inline (String, Vec<String>) would grow every frame and eat into the interpreter’s stack headroom (see GH #46/#47). The box is allocated once per gated command.

vfs_budget: Option<Arc<ByteBudget>>

Shared VFS memory budget for this kernel’s MemoryFs mounts.

Arc-cloned from the owning Kernel (or its fork parent) so all concurrent execution paths draw from the same pool. None means unbounded. Populated by Kernel::assemble and forwarded through child_for_pipeline / fork_inner so background jobs and scatter workers see the same cap as foreground execution.

watchdog: Option<Arc<Watchdog>>

The per-execute timeout watchdog, when a script timeout is in effect.

Populated by the kernel at execute entry (alongside cancel) and shared through child_for_pipeline so forks and pipeline stages can acquire patient holds against the same script clock. None when no timeout is configured — ToolCtx::patient then returns an inert guard.

overlay_handle: Option<Arc<OverlayHandle>>

Active overlay handle when the kernel was constructed with overlay: true.

Arc-cloned so forks and pipeline stages share the same transaction. None when no overlay is active (most kernels).

Implementations

impl ExecContext

pub const STREAM_CHUNK_SIZE: u64

Default chunk size for forward file scans. Bounds the memory a scan-oriented builtin holds at once, independent of file size.

pub fn new(vfs: Arc<VfsRouter>) -> Self

Create a new execution context with a VFS (uses LocalBackend without tools).

This constructor is for backward compatibility and tests that don’t need tool dispatch. For full tool support, use with_vfs_and_tools.

pub fn with_vfs_and_tools(vfs: Arc<VfsRouter>, tools: Arc<ToolRegistry>) -> Self

Create a new execution context with VFS and tool registry.

This is the preferred constructor for full kaish operation where tools need to be dispatched through the backend.

pub fn with_backend(backend: Arc<dyn KernelBackend>) -> Self

Create a new execution context with a custom backend.

pub fn with_vfs_tools_and_scope( vfs: Arc<VfsRouter>, tools: Arc<ToolRegistry>, scope: Scope, ) -> Self

Create a context with VFS, tools, and a specific scope.

pub fn with_scope(vfs: Arc<VfsRouter>, scope: Scope) -> Self

Create a context with a specific scope (uses LocalBackend without tools).

For tests that don’t need tool dispatch. For full tool support, use with_vfs_tools_and_scope.

pub fn with_backend_and_scope( backend: Arc<dyn KernelBackend>, scope: Scope, ) -> Self

Create a context with a custom backend and scope.

pub fn set_tool_schemas(&mut self, schemas: Vec<ToolSchema>)

Set the available tool schemas (for help command).

pub fn set_tools(&mut self, tools: Arc<ToolRegistry>)

Set the tool registry reference.

pub fn set_job_manager(&mut self, manager: Arc<JobManager>)

Set the job manager for background job tracking.

pub fn set_trash_backend(&mut self, backend: Arc<dyn TrashBackend>)

Set the trash backend.

pub fn set_stdin(&mut self, stdin: String)

Set stdin for this execution.

An explicit stdin string (< file, heredoc, here-string, or a pipeline hand-off) supersedes any inherited lazy pipe_stdin. Since read_stdin_* prefers pipe_stdin, clear it here so redirect precedence holds — a < file must beat a frontend-seeded piped stdin.

pub fn take_stdin(&mut self) -> Option<String>

Get stdin, consuming it.

pub fn set_stdin_with_data(&mut self, text: String, data: Option<Value>)

Set both text stdin and structured data.

Use this when passing output through a pipeline where the previous command produced structured data (e.g., JSON from MCP tools).

pub fn take_stdin_data(&mut self) -> Option<Value>

Take structured data if available, consuming it.

Tools can use this to avoid re-parsing JSON that was already parsed by a previous command in the pipeline.

pub async fn resolve_stdin(&mut self) -> Result<(Option<Value>, String), String>

Resolve stdin for a builtin that can consume either structured .data or raw text from the previous pipeline stage (jq, scatter, …). Returns (Some(data), _) when the upstream produced structured data, else (None, text).

Ordering matters and is the whole point: the pipe is drained to text FIRST, which runs the upstream producer to completion (it can’t be parked on pipe backpressure), and only THEN is the structured-data sideband awaited — by which point the producer has definitely sent it (it sends before writing/closing its pipe). A streaming upstream that emits a lot of text before sending its (absent) data therefore can’t deadlock us, and a fast structured producer (seq) is no longer lost to a startup race that a one-shot try_recv used to drop on the floor.

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

Resolve a path relative to cwd, normalizing . and .. components.

pub fn set_cwd(&mut self, path: PathBuf)

Change the current working directory.

Saves the old directory for cd - support.

pub fn get_prev_cwd(&self) -> Option<&PathBuf>

Get the previous working directory (for cd -).

pub async fn read_stdin_to_string(&mut self) -> Option<String>

Read all stdin (pipe or buffered string) into a String.

Prefers pipe_stdin if set (streaming pipeline), otherwise falls back to the buffered stdin string. Consumes the source.

pub async fn read_stdin_to_text(&mut self) -> Result<Option<String>, String>

Read stdin as text, erroring on non-UTF-8 instead of silently lossy-decoding it (which corrupts binary with U+FFFD).

The strict counterpart to Self::read_stdin_to_string, for text-only builtins (grep, sed, awk, cut, sort, jq, …): a binary stream is a loud error, not a mangle. Returns Ok(None) when there is no stdin at all. The Err is a ready-to-use message; callers prefix their name. See docs/binary-data.md and docs/issues.md.

pub async fn read_stdin_to_bytes(&mut self) -> Option<Vec<u8>>

Read all of stdin as raw bytes, preserving binary intact.

The byte-clean counterpart to Self::read_stdin_to_string, for binary-aware builtins (base64, xxd, checksum, wc -c, cmp, …). Returns None when there is no stdin at all (no pipe and no buffer); an empty pipe yields Some(vec![]). A buffered text stdin is returned as its UTF-8 bytes. See docs/binary-data.md.

pub fn child_for_pipeline(&self) -> Self

Create a child context for a pipeline stage.

Shares backend, tools, job_manager, aliases, cwd, and scope but has independent stdin/stdout pipes.

pub async fn build_ignore_filter(&self, root: &Path) -> Option<IgnoreFilter>

Build an IgnoreFilter from the current ignore configuration.

Returns None if no filtering is configured.

pub fn verify_nonce( &self, nonce: &str, command: &str, paths: &[&str], ) -> Result<(), String>

Validate a confirmation nonce against a command and paths.

Thin wrapper on NonceStore::validate for ergonomic use from builtins.

pub fn latch_result( &self, command: &str, paths: &[&str], reason: &str, confirm_hint: impl FnOnce(&str) -> String, ) -> ExecResult

Issue a nonce and build the standard exit-2 latch result.

reason explains why confirmation is needed (e.g., "latch enabled", "emptying trash is destructive"). The confirm_hint closure receives the nonce string so each tool can format its own re-run command.

The result includes structured data in .data for programmatic access:

{"nonce": "a3f7b2c1", "command": "rm", "paths": [...], "hint": "rm --confirm=a3f7b2c1 file", "ttl": 60}

pub async fn gate_overwrites( &mut self, command: &str, targets: &[(String, bool)], confirm: Option<&str>, confirm_hint: impl FnOnce(&str, &str) -> String, ) -> Result<HashMap<PathBuf, Vec<u8>>, ExecResult>

Gate a batch of truncating overwrites through latch + trash, the way rm gates deletes — so tee/patch/sed -i can’t silently clobber a file with no recoverable prior copy and no confirmation.

Each target is (display_path, is_append). A path that doesn’t exist yet or is an append has nothing to lose and passes. For an existing file under set -o trash, the prior content is copied to trash first (via trash_bytes) so it’s recoverable; the file is left in place for the caller to overwrite. Under set -o latch (and trash off) the batch needs --confirm=<nonce>: the first call returns an exit-2 latch result with one nonce scoping every latched path.

Ok(snapshots) means every snapshot is done and the caller may write all targets; snapshots maps each trash-snapshotted target’s resolved path to its prior bytes, so a byte-oriented caller can pass them as the expected to overwrite_checked for a binary-safe compare-and-swap. Err(result) is what the caller must return verbatim (the latch prompt, an invalid nonce, or a trash failure — never fall through to a destructive overwrite on error).

confirm_hint builds the re-run command shown in the latch prompt, given the nonce and the space-joined latched paths. Most callers want |nonce, joined| format!("{command} --confirm=\"{nonce}\" {joined}"), but a tool whose argv carries operands the operation can’t run without — e.g. sed -i’s expression — must reinject them here, or the advertised re-run will misbehave (or hang on stdin).

pub async fn expand_glob(&self, pattern: &str) -> Result<Vec<PathBuf>, String>

Expand a glob pattern to matching file paths.

Returns the matched paths (absolute). Used by builtins that accept glob patterns in their path arguments (ls, cat, head, tail, wc, etc.).

pub async fn expand_paths( &self, positional: &[Value], ) -> Result<Vec<String>, String>

Expand positional arguments, resolving glob patterns to relative paths.

Used by file-processing builtins (cat, head, tail, wc) that accept glob patterns in their path arguments. Non-string values are converted to strings (matching shell conventions).

pub async fn read_file_chunked<F>( &self, path: &Path, chunk_size: u64, f: F, ) -> BackendResult<()>

where F: FnMut(&[u8]) -> ControlFlow<()>,

Stream a file’s bytes forward in chunk_size slices, handing each non-empty chunk to f.

Reads are issued as positional read_range requests, so backends slice without materialising the whole file (LocalFs seeks; MemoryFs/OverlayFs slice their stored bytes). The loop terminates on the first empty chunk, which every backend returns once the offset reaches EOF. f returns a ControlFlow: Break stops the loop early (e.g. a consumer that has detected binary content and will discard the rest), so we don’t keep reading a file the caller is done with. This is the shared engine for scan-oriented builtins (wc, checksum, grep) that walk a file front-to-back and must not hold it all in memory.

Trait Implementations

impl ToolCtx for ExecContext

The kernel’s full execution context satisfies the trimmed portable ToolCtx contract that out-of-tree tools see.

Trusted in-tree builtins recover the concrete ExecContext (job control, pipes, dispatcher) through [ToolCtx::as_any_mut].

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

The backend for file I/O and tool dispatch.

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.

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).

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.