Implement sandboxed execution: restricted mode + pluggable virtual filesystem

[lostbean]

Note: This PR depends on #3 (test fixes, already approved). The 4 test failures visible in CI are from pre-existing platform-dependent tests fixed in that PR — once #3 is merged, this branch will be green.

Motivation

When a command is not a builtin, a user-defined function, or an Interop binding, the interpreter falls through to spawning a real OS process via ExCmd. Commands like ls, cat, grep, curl, rm execute against the host with full access to the filesystem, network, and process table. There is no option to disable this fallback, and all filesystem access goes through File.* directly. This means there is no way to use the library as a sandboxed scripting environment.

Use Case

• AI Agent Shell Environment — An LLM-driven agent needs bash scripting constructs (variables, loops, conditionals, functions, string manipulation, arrays, arithmetic) against a virtual workspace via Interop bindings. Without sandboxing, an agent could run curl, rm -rf /, or any installed binary, and builtins like test -f or source would hit the real filesystem.
• Multi-Tenant Script Execution — A platform executing user-provided bash scripts needs to guarantee scripts cannot escape their sandbox, both in terms of process execution and filesystem access.
• Testing and Simulation — Tests exercising bash scripting logic should not depend on or affect the host filesystem. A virtual filesystem gives deterministic, isolated execution suitable for CI.

Requirements

• No code path may spawn an OS process in response to a user command (simple commands, absolute paths, command, exec, coproc, pipelines, command substitution, background jobs).
• All builtins, Interop commands, and user-defined bash functions remain fully functional.
• Blocked commands produce a stderr message mentioning "restricted" and return a non-zero exit code.
• The restricted flag inherits to subshells and command substitutions and is immutable once set.
• All filesystem access (builtins like test, cd, source, pwd, redirections, glob expansion) dispatches through a pluggable filesystem behaviour instead of calling File.* directly.
• When a non-LocalDisk filesystem is provided, restricted mode is automatically enforced.
• Default behavior is unchanged — purely additive, opt-in.

Proposed Solution

The solution has two layers:

1. Restricted Mode (Bash.ExternalProcess)

A new Bash.ExternalProcess module acts as a centralized gateway wrapping all user-facing OS process spawning (ExCmd.Process.start_link, ExCmd.stream, System.cmd). When restricted mode is active, all calls return {:error, :restricted}.

graph TD
    CP[CommandPort] --> EP[ExternalProcess]
    JP[JobProcess] --> EP
    CO[Coproc] --> EP
    PL[Pipeline] --> EP
    CM[Command builtin] --> EP
    EP -->|restricted?| ERR["{:error, :restricted}"]
    EP -->|allowed| EX[ExCmd / System.cmd]

Loading

The session carries the flag in options.restricted, defaulting to false. The set builtin filters :restricted from option changes, and shopt treats restricted_shell as read-only.

2. Pluggable Filesystem (Bash.Filesystem)

A behaviour with 16 callbacks covering all filesystem operations used by the interpreter. Stored in session state as a {module, config} tuple. All filesystem access (57+ call sites across 14 files) dispatches through Bash.Filesystem instead of calling File.* directly.

graph TD
    subgraph Callers
        T[Test builtin]
        CD[cd/pwd]
        SRC[source]
        CMD[Command/Pipeline]
        R[Redirections]
        G[Glob expansion]
    end
    Callers --> FS[Bash.Filesystem]
    FS --> LD[LocalDisk — default]
    FS --> VFS[Custom VFS adapter]

Loading

The default Bash.Filesystem.LocalDisk adapter delegates to Elixir's File and Erlang's :file modules. When a non-LocalDisk filesystem is provided, Session.init/1 automatically enables restricted mode to prevent a split-brain state where builtins use the VFS but external commands hit the real OS.

Usage

# Restricted mode only (real filesystem, no external commands)
{:ok, session} = Bash.Session.new(options: %{restricted: true})

# Full sandbox (virtual filesystem + auto-restricted)
{:ok, session} = Bash.Session.new(filesystem: {MyVFS, vfs_config})