"Vox shell operations boundaries"

Vox shell operations boundaries

Vox is a language and toolchain. It does not ship a general-purpose shell emulator as a product surface. This page names the three lanes agents and contributors should use so responsibilities stay clear.

Three lanes

LaneUse whenMechanism
Host shellYou are typing or pasting commands in a terminal (IDE, CI step, local automation harness).Real pwsh (or the platform shell your workflow uses). Prefer validating risky PowerShell with vox shell check against contracts/terminal/exec-policy.v1.yaml.
vox shellQuick manual smoke of the CLI or validating a PowerShell fragment against exec-policy.Subcommands: repl (micro-REPL, dev-only) and check (AST + policy). repl is not a substitute for pwsh and does not implement pipelines, session cd, or robust quoting.
.vox programsLogic lives in the Vox language (scripts, apps, generated Rust).Typed std.fs, std.path, std.process (argv-first). Do not rely on parsing arbitrary shell command strings in .vox as the default pattern.

Design principles (LLM-friendly, Vox-native)

  1. Argv-first subprocesses — std.process.run / run_ex / run_capture take a program name and argument list, not a shell line. This avoids quoting and injection hazards common in generated shell.
  2. Explicit path operations — compose paths with std.path.*; probe kind with std.fs.exists / is_file / is_dir; normalize with std.fs.canonicalize when comparing locations.
  3. Resolve tools before spawning — std.process.which resolves an executable on PATH to an absolute path when you need deterministic spawn behavior.
  4. Policy at the host boundary — exec-policy applies to PowerShell source checked by vox shell check, not to the repl passthrough path.

Explicit non-goals

  • A Vox-owned interpreter for bash/PowerShell syntax inside .vox.
  • Growing vox shell repl into a session-aware shell with pipelines, job control, or policy-gated arbitrary execution.
  • Duplicating exec-policy with a second allowlist unless a future product requirement is approved.