[hanaduy]

Description

Problem

A bare python3 or python in a box always runs Monty, Box's built-in Python subset (#371). An agent that needs -m pytest, a package, or a module Monty lacks gets a refusal. A [tool.python3] table the operator declares is accepted, but a bare python3 never runs it, and nothing tells the operator.

Running real Python through a writable venv has a second problem. Measured on main (61ade09, macOS, Homebrew Python 3.14.7): the agent wrote a .pth file into an in-project venv's site-packages through the Shell. Python ran it inside the tool, and again after the box ended, with the operator's full rights.

What changes

• monty = false. A new top-level box.toml key, default true. With Monty off, [tool.python3] or [tool.python] answers to both python3 and python, and nothing falls back to Monty. With no Python table, both names exit 126 with a reason, before any policy decision. The table name decides, not the file name. Both tables must name the same command as written, with no fixed arguments.
• The install is read-only. Box reads the tool's install from its files and never runs it. It recognizes a venv, a standard prefix, Homebrew and Debian, and refuses anything else. It refuses every write grant that reaches the folders Python loads code from, and every Shell or Monty write into them while the box runs. Folders that don't exist yet are covered, such as the user site. So are the base prefix's lib/, link targets outside the install, editable-install sources, and folders named by .pth lines. A file with another hard link refuses startup.
• Box adds the grants Python needs. These are reads on the install, a venv's pyvenv.cfg, the certificate bundle, and the libraries the install's extension modules load, plus, on macOS, metadata on the folder that holds the command, which Python resolves at startup. When the table has no filesystem list, Box also grants read and write on the workspace. An operator's own list replaces only the workspace grant. The startup notice marks each added grant.
• Libraries and commands named through links. A module usually names its library through links, such as Homebrew's /opt/homebrew/opt/openssl@3/lib/libssl.3.dylib. Box's own lists refuse a link, so each library entry is on the real file and carries the requested name, (loaded as …) in the startup notice, and Box grants the file to containment under that name. Containment's traversal walk now records each linked folder a chain passes through, such as /opt/homebrew/opt/python@3.14 in a Homebrew venv's python3, so macOS gets a metadata rule on it and the floor judges it like the other nodes.
• stdin. A program the Shell starts can't receive stdin yet. When the call's stdin carries data, Python gets a write-only descriptor, so reading it fails with EBADF instead of returning nothing, and Box adds one stderr line on failure. A call that would read its program from stdin (python3 -, or a bare python3 in a pipe) exits 126. Only a replaced name waits for the stdin answer. Other spawns are unchanged.
• Messages. Startup says what a bare python3 runs, on every box. It names a Python table that Monty leaves unused, and with Monty off it states the costs. Monty's refusals for -m, a program from stdin, and a failed import say how to run real Python. A failed write into the read-only install adds one stderr line.
• A macOS timeout test. It checks that [limits.shell] timeout kills a tool's process group, as the Linux tests already do.

Decisions this depends on

• Monty stays the default. Real Python takes three steps: monty = false, a [tool.python3] or [tool.python] table, and a shell:spawn permit on the resolved file.
• A refusal exits 126 with a reason and never runs Monty instead.
• Nothing in the box may write the Python install. A venv inside the project is therefore refused when the project is writable.
• [limits.shell] timeout bounds real Python too. There is no Python-only setting.
• Versioned names such as python3.14, and a venv's bin/ scripts such as pytest, behave as before.

docs/design/decisions.md rewrites #python-in-the-shell-is-monty and #a-bare-python-name-always-means-monty, keeping both anchors. It adds #box-refuses-writes-into-the-python-install and #box-grants-a-python-tool-its-install-and-the-workspace.

Interfaces that move (approval requested for each)

Surface	Change
box.toml keys	New top-level monty (bool, default true)
Stored records	monty = false is stored at record version 34; an older build refuses the box
Aliases	With Monty off, python3 and python reach the Python tool instead of Monty
Startup disclosure	One new line on every box; more lines with Monty off or an unused Python table; added grants are marked, and an added library shows (loaded as <name>)
Containment rules	A grant whose link chain passes through a linked folder now gets file-read-metadata on that folder link (macOS), and the floor and deny checks judge it. A grant spelled as a real path, which is every grant an operator writes, gets no new rule
Exit statuses and messages	New 126 reasons; Monty's -m exits 2 with its own text; Monty's hint texts; two new stderr lines
strands-shell public items	ReplacedCommands, RefusedCommands, SpawnStdin, HostSpawn.stdin and HostSpawn.name (new fields on a public struct), Kernel::replaces_command, Kernel::refused_command, ShellBuilder::replaced_commands, ShellBuilder::refused_commands, two VfsKernel fields, commands::REAL_PYTHON_HINT. crates/shell/UPSTREAM.md records each.

The broker protocol, CLI, policy actions and telemetry names don't change. A refused name raises no policy decision, so it leaves no decision record.

Known gaps

• Libraries that extension modules load on Linux. Box now adds a read grant for each library an extension module loads, such as Homebrew's opt/openssl@3/lib for ssl. On Linux that grant is mounted noexec, so a library outside the system folders (conda's lib/, for example) may still fail to load. Box also stops after 5000 extension modules without saying so.
• One library file named two ways. When two modules name the same file through different links, Box grants it under the first name, because containment takes one read grant per file. A load through the other name's links can fail.
• stdin forwarding into started programs. The write-only stdin is a stopgap until it exists.
• refactor(shell): migrate Box to upstream Strands Shell #414 moves the vendored Shell to upstream. The two Shell hooks here would move with it.
• feat(box, containment): add an experimental deny_write list to [agent.filesystem] #429 adds deny_write for the agent. It addresses the same in-project venv case from the agent's side.

Related Issues

Part of #371. Stacked on #417; merge after it. Follows #397. Takes the place of the design in #389.

Type of Change

New feature

Testing

• cargo build --workspace --locked --all-targets --all-features: ok.
• cargo test -p strands-box --lib --all-features: 1050+ passed.
• cargo test -p strands-shell: 2048 passed.
• cargo test -p strands-box --all-features --test four_inputs: 5 passed.
• cargo fmt --check and cargo clippy --workspace --all-targets --all-features with the workflow's flags: clean. Cargo.lock is unchanged.
• Full suite, dispatched by hand, because CI doesn't run on a pull request into a feature branch:
  • Both OSes and lint, on 60d7400: all passed. https://github.com/strands-agents/box/actions/runs/43506431252 The macOS job ran the new in-box Homebrew test on the runner's Homebrew Python 3.15.2, with the venv outside the home.
  • ci.yml on 60d7400, which adds Containment (both OSes) and Verdict, both of which skip a pull request into a feature branch: Containment, Verdict, lint and macOS unit tests passed. https://github.com/strands-agents/box/actions/runs/43506436419 Its Linux unit job failed once in tests/mcp_alias_fallback.rs with Text file busy while starting a test program. That file isn't touched here, the same test passed in the full suite's Linux job on the same commit, and it passed on 8ce3568.
  • On 8ce3568, the same in-box test failed on macOS with python3: realpath: …/venv/bin/: Operation not permitted, which 5191fad fixes, and skipped on Linux, where CI fails an unexpected skip, which 60d7400 fixes by making it macOS-only.
• End to end on Linux (Ubuntu 24.04 arm64, Debian CPython 3.12, a venv outside the project, monty = false and [tool.python3] with no filesystem table): 44 of 44 checks passed.
  • python3 and python run the venv;
  • ssl, sqlite3, lzma and hashlib import;
  • python3 -m pytest runs;
  • a .pth file can't be planted through the shell or through Python;
  • pip install fails with the read-only line;
  • piped stdin fails with EBADF and the no-stdin line;
  • python3 - and echo 1 | python3 exit 126;
  • python3.12 is refused;
  • with no permit, 126 default-deny;
  • with Monty on, the table is unused;
  • with Monty off and no tool, 126;
  • a venv inside the project is refused at startup;
  • [limits.shell] timeout stops Python, and the box keeps serving.
• End to end on macOS (macOS on arm64, Homebrew CPython 3.14.7, a venv outside the project, monty = false and [tool.python3] with no filesystem table), on 8ce3568: 49 of 49 checks passed. These are the Linux checks plus a box whose own table grants Homebrew's folders. Two earlier runs found the bugs that 8ce3568 fixes: every such box refused to start, because the library grants named Homebrew's links, and then exec of the venv's python3 failed, because nothing rendered the /opt/homebrew/opt/python@3.14 folder link.
  • ssl, sqlite3, lzma and hashlib import with no filesystem table;
  • reads outside the grants and writes into the venv raise PermissionError.

Main new tests:

• Record: the round trip at version 34, every older version refused, the two-table and fixed-argument refusals.

• Bare names and startup lines.

• Shell: a replaced name and a refused name.

• Install layouts on fake trees: hard links, link targets, missing folders, .pth paths, editable sources.

• Write grants refused in both directions, and Shell writes into the install refused.

• The added grants and their disclosure.

• Classifying stdin.

• The program-from-stdin argument scan.

• Libraries named through links: one entry per real file with the requested name; the translated config grants the file once, under that name, and a relinked name refuses the spawn.

• Containment (macOS): a file read and an exec chain through a linked folder render metadata on the folder link. Each fails without the walk change.

• In a box, tests/python_tool.rs: a venv of the runner's Homebrew Python with no filesystem table imports ssl, lzma, sqlite3 and decimal. It skips when the host has no Homebrew Python.

• I ran the relevant suites (just check, or cargo test --workspace --all-features)

• If I touched Rust, I ran cargo fmt --all and cargo clippy --workspace --all-targets --all-features -- -D warnings

Checklist

• I have read the CONTRIBUTING document
• I have reviewed and understand every line of code in this PR, including any generated by AI tools, and I can explain why it works
• My change is focused and reasonably small; I have split unrelated work into separate PRs
• I have added any necessary tests that prove my fix is effective or my feature works
• I have updated the documentation accordingly
• My changes generate no new warnings

[zastrowm]

None of this should be included in Box; Box does't need to know about this. If monty is disabled, it's up to the author to include python as a tool.

That's what I've been trying to emphasize - the only case that Box should special case python3 is for/using Monty. But if Monty is disabled, python should just be a normal tool