# `Pixir.Tools.Bash`
[🔗](https://github.com/Ranvier-Technologies/pixir/blob/main/lib/pixir/tools/bash.ex#L1)

Run a shell command with the Workspace as the working directory.

Before crossing into host process execution, `execute/2` acquires a bounded
host-command lease from `Pixir.Tools.CommandBoundary` (ADR 0027). This keeps OS
process fanout separate from BEAM-local Subagent/Workflow fanout.

Runs via a `Port` so a hung command can be **killed on timeout** (closing the port
terminates the spawned process — no orphan), unlike a blocking `System.cmd/3`. The
timeout is an open knob: `context.bash_timeout_ms` or `config :pixir, :bash_timeout_ms`
(default 120s), capped by `bash_timeout_max_ms` (default 600s). Host-command
concurrency and queueing use `host_commands` config.

v0.1 safety confines the cwd and rejects shell tokens that visibly resolve outside
the workspace — parent-directory references, absolute paths, home/env-home paths, and
existing symlink-prefix escapes — before crossing the host boundary. Only RHS values
of leading POSIX environment assignments before a simple command are ignored; literal
path arguments, redirection targets, and non-leading `NAME=VALUE` values are still
checked. The accepted residual vector `VAR=/outside cmd $VAR` can expand at runtime,
because this is a conservative tripwire, not a full shell parser or sandbox. The
permission gate (ADR 0006) is still the higher-level guard: under `:ask`, non-safe
commands prompt; under `:read_only` they are refused.

---

*Consult [api-reference.md](api-reference.md) for complete listing*