Mitchell Foutz Source on GitHub

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

  1. git clone https://github.com/darblinko/agent-controls ~/agent-controls
    cd ~/agent-controls
  2. uvx pytest -q
  3. mkdir -p ~/.config/agent-controls
    cp examples/sandbox.conf ~/.config/agent-controls/sandbox.conf
  4. cd ~/src/my-app
    export CODEX_SANDBOX_DRY_RUN=1
    ~/agent-controls/bin/codex-sandbox exec "ls"

Limitations