28. Keep the venv last on PATH and review what a session leaves#

Date: 2026-10-07

Status#

Accepted. Supersedes ADR 27 except for its entry-point mount guard.

Context#

The sandbox contains the agent while it runs, not the code it leaves for something outside the sandbox to run later: venv packages and .pth files (uv run, pytest), Git hooks (git commit, pre-commit), Makefiles and VS Code tasks. The workspace, the venv and the caches are writable from the jail on purpose.

ADR 27 covered one slice of this, executables in a venv bin first on the outer PATH that shadow a system command, plus Git hooks, with a watcher outside the jail: inotify, quarantine, baselines, alerts and a shell prompt hook. That was about 650 lines in the audit core for one route among many. An end-of-session report instead would print in a terminal that often closes with the session (VS Code extension launches).

Decision#

  • The venv goes last on PATH. The image sets PATH=$PATH:/opt/venv/bin, as the jail already does, so nothing a session leaves there can shadow a system command. Devcontainers that put their venv first should append it.

  • The entry-point mount guard stays. It is a few lines in bwrap.py and protects Invariant 1 where a devcontainer still puts a writable directory first.

  • The rest is reviewed, not watched. Code a session leaves is not an escape on its own; it is the same exposure as an unreviewed contribution. The threat model says to review a session’s changes, and .git/hooks, before running project code outside the jail.

  • Removed: watch.py, the /run/claude-sandbox state directory, the alerts prompt hook, claude-sandbox alerts, doctor’s alerts check and the jail-off PID 1 special case. The watcher shipped only in the 5.0.0 betas, so there is no upgrade step.

Consequences#

  • In the image, the venv’s python, pytest and console scripts come after any system command of the same name; uv run is unchanged.

  • A devcontainer that keeps a writable venv first stays exposed to shadowing for every name but the sandbox’s own four.

  • Nothing tells the user what a session left; they review its changes.