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 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 terminal_state: Option<Arc<TerminalState>>,
}

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.

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.

terminal_state: Option<Arc<TerminalState>>

Terminal state for job control (interactive mode, Unix only).

Implementations

impl ExecContext

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_stdin(&mut self, stdin: String)

Set stdin for this execution.

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