agent-controls
Three shell controls for developers who run Claude Code and the Codex CLI on a Linux or WSL2 workstation: a read boundary for Codex, a second review before Claude stops, and separate Claude Code profiles per account.
- Repository
- darblinko/agent-controls
- Revision
cff3ecb- Measured
- 2026-10-30
- License
- Apache-2.0
Problem
An agent process runs as the developer's user and can read whatever that user can read: other repositories, .env files, cloud and GitHub credentials, other Claude Code profiles and, on WSL, the Windows drives. Anything it reads can become part of a prompt sent to the model provider.
Codex's --sandbox read-only policy restricts writes and leaves reads open. In a probe on 2026-08-30, Codex started in read-only mode read a file at an arbitrary absolute path outside its --cd directory and listed the root of an unrelated repository. Project trust settings in config.toml govern approval prompts and do not set filesystem scope.
Separately, Claude Code can stop with failing tests or with changes no second reviewer has seen, and a session can run under the wrong account.
How it works
bin/codex-sandbox starts Codex in a bubblewrap mount namespace that holds only the configured root containing the current directory, the tool and state paths from the config, and read-only system directories. .env* files and other masked names are overmounted with /dev/null, except inside directories named node_modules, .git, .venv, venv and __pycache__, which the search prunes. On WSL, /mnt is empty, /init and /run are absent, and WSL_INTEROP and WSLENV are unset. The one exception is the target of /etc/resolv.conf, bound read-only when it resolves outside /etc, which can lie under /mnt or /run.
flowchart TD
cmd["codex ..."] --> wrapper["codex-sandbox"]
conf[("sandbox.conf")] --> wrapper
wrapper -->|"cwd outside every root"| refuse["exit 1"]
wrapper -->|"cwd inside a root"| ns
subgraph ns["bubblewrap namespace"]
sys["/usr and /etc, read-only"]
root["matched root: rw, ro, or listed subtrees"]
extra["tool and state paths"]
empty["empty tmpfs: /tmp, /home, HOME, /mnt"]
masked[".env* and mask files over /dev/null, pruned dirs excepted"]
sys ~~~ root ~~~ extra ~~~ empty ~~~ masked
end
hooks/codex-review-gate.sh is a Claude Code Stop hook. It runs the project's tests, then a Codex review of the uncommitted changes. Blocking findings return exit 2 and Claude continues. Rounds are capped per batch, a hash of the git status --short output, so a new changed file or a git add starts a new batch at round 1. After the last round the gate lets Claude stop and logs the open blockers.
flowchart TD
stop["Claude tries to stop"] --> changes{"uncommitted changes?"}
changes -->|"no, or this state is already approved"| allow["exit 0: Claude stops"]
changes -->|"yes"| tests{"REVIEW_GATE_TEST_CMD passes?"}
tests -->|"no"| fixtests["exit 2: test output to Claude"]
tests -->|"yes"| review["codex exec review, round N"]
review -->|"APPROVED"| record["write approval"] --> allow
review -->|"CHANGES_REQUESTED, rounds left"| fix["exit 2: review to Claude"]
review -->|"CHANGES_REQUESTED, last round"| override["log override"] --> allow
review -->|"Codex error or unparseable"| notify["exit 1: user sees error, no approval"]
shell/claude-profiles.sh defines claude_profile <name>, which sets CLAUDE_CONFIG_DIR=~/.claude-<name> and, when a token file for that profile exists, CLAUDE_CODE_OAUTH_TOKEN.
Measured results
The test suite drives the scripts directly. The sandbox tests check the bwrap arguments built from a config, and 5 of them start a stand-in Codex inside a real namespace. The gate tests run the hook against a throwaway git repository with Codex replaced by a stub. All 100 control tests pass at cff3ecb.
Run it
git clone https://github.com/darblinko/agent-controls ~/agent-controls cd ~/agent-controlsuvx pytest -qmkdir -p ~/.config/agent-controls cp examples/sandbox.conf ~/.config/agent-controls/sandbox.confcd ~/src/my-app export CODEX_SANDBOX_DRY_RUN=1 ~/agent-controls/bin/codex-sandbox exec "ls"
Limitations
- The network is shared with Codex. The sandbox limits what Codex can read; anything inside the bound root can still be sent anywhere the machine can reach.
- Masking matches file names when Codex starts. Secrets under other names, files created later, symbolic links and files inside the pruned directories are not masked.
- The tests check that
/runand/initare not bound and thatWSL_INTEROPandWSLENVare unset. Whether an absent/initdisables the WSLInterop binfmt_misc handler depends on its registration flags and is untested. - The calling shell's environment passes into the namespace, except
WSL_INTEROP,WSLENVandunsetenventries. - After the last review round, Claude may stop with blockers still open. They are logged in
.ai/reports/qa_decisions.jsonl. - The gate reviews uncommitted changes only.
- A stop that finds the review lock held by another live run exits 0 without tests or a review.
- Profile tokens travel as an environment variable readable by the same user's processes.
- The CI workflow has not run yet; the counts above come from a local run on WSL2.