feat #167: add --sandbox flag and CODEX_SANDBOX env var for review and task commands

[BryanBorck]

Closes #167

Problem

The plugin hardcodes sandbox: "read-only" for reviews and tasks, with no override. On Linux hosts where Codex's bwrap sandbox can't initialize (Devbox, EC2, VPS kernels missing CAP_NET_ADMIN), every review fails:

> /codex:review

bwrap: loopback: Failed RTM_NEWADDR: Operation not permitted
"I couldn't inspect the repository state or diff because all shell/file
access attempts were blocked by the sandbox."

Setting sandbox = "danger-full-access" in ~/.codex/config.toml has no effect — the plugin explicitly overrides it per-thread. There is currently no way to fix this without patching plugin source files, which get overwritten on every update.

Solution

Add a resolveSandbox() helper that resolves sandbox mode from:

1. --sandbox <mode> flag — per-call override (aliased as -s)
2. CODEX_SANDBOX env var — persistent override for sandboxed environments
3. Default — "read-only" for reviews, "workspace-write" when --write is passed (unchanged behavior)

Before

No way to override. Reviews fail silently in sandboxed environments.

After

One-time setup — add to ~/.zshrc or ~/.bashrc:

export CODEX_SANDBOX=danger-full-access

Then /codex:review just works. danger-full-access is safe in these environments because the host is already externally sandboxed (Devbox, Docker, Claude Code's own sandbox on EC2).

Or per-call:

/codex:review --sandbox danger-full-access

Note on ~/.codex/config.toml

Ideally the plugin should read the sandbox key from ~/.codex/config.toml, which the Codex CLI already respects for direct invocations. The plugin currently ignores config.toml entirely — it doesn't parse it for any setting. The env var approach in this PR is a pragmatic fix that doesn't require adding a TOML parser to a zero-dependency plugin, but proper config.toml support would be the right long-term solution.

Changes

• codex-companion.mjs: added resolveSandbox(), wired --sandbox into handleReviewCommand, handleTask, executeReviewRun, executeTaskRun, and buildTaskRequest
• lib/codex.mjs: runAppServerReview now respects options.sandbox instead of hardcoding "read-only"

Test plan

• Verified on Ubuntu 24.04 (kernel 6.17, Devbox) where bwrap fails with RTM_NEWADDR: Operation not permitted
• CODEX_SANDBOX=danger-full-access /codex:review completes end-to-end
• Without the env var or flag, default read-only behavior is unchanged
• Invalid sandbox values throw a clear error

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 9074d537ee

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[chatgpt-codex-connector]

Validate sandbox before enqueuing background tasks

The background branch in handleTask forwards options.sandbox into the stored job request without validating it, while validation only occurs later inside executeTaskRun via resolveSandbox. In environments where Codex is available, task --background --sandbox <invalid> will report a successful queue launch and then fail asynchronously in the worker, which is inconsistent with foreground behavior and gives users a misleading success response. Validate/normalize the sandbox value before calling enqueueBackgroundTask so invalid flags fail fast.

Useful? React with 👍 / 👎.