# Workspace‑Write vs. Read‑Only Sandbox Modes in the Codex Plugin for Claude Code

> Understand the difference between workspace-write and read-only sandbox modes in the Claude Code Codex plugin. Learn how to safely review or apply code changes with the right mode.

- Repository: [OpenAI/codex-plugin-cc](https://github.com/openai/codex-plugin-cc)
- Tags: deep-dive
- Published: 2026-08-03

---

**Read‑only mode blocks all file modifications for safe code reviews, while workspace‑write mode grants Codex full write access to apply code changes.**

The `openai/codex-plugin-cc` repository implements two distinct **sandbox execution modes** that control how the Codex runtime interacts with your workspace. These modes are the core mechanism that distinguishes inspection‑only operations from automated code modifications.

## How Sandbox Modes Are Selected

The plugin determines which sandbox to use at two critical points in the execution flow:

1. **Default initialization** — In `plugins/codex/scripts/lib/codex.mjs` at lines 68‑71, the `buildThreadParams` helper supplies `"read-only"` as the fallback:

```javascript
// plugins/codex/scripts/lib/codex.mjs#L68-L71
sandbox: options.sandbox ?? "read-only"

```

2. **Task‑time override** — In `plugins/codex/scripts/codex-companion.mjs` at line 491, the `executeTaskRun` function switches to `"workspace-write"` when the user explicitly requests a write‑enabled operation:

```javascript
// plugins/codex/scripts/codex-companion.mjs#L491
sandbox: request.write ? "workspace-write" : "read-only"

```

## Read‑Only Mode: Safe Inspection Without Side Effects

When Codex runs in **`read‑only`** mode, the runtime is restricted to pure read operations. This mode provides **guaranteed immutability** — the Codex process can inspect files, analyze code structure, run tests, and generate reviews, but any attempt to create, modify, or delete files is blocked at the sandbox level.

This mode is automatically selected for:

- `/codex:review` commands
- `/codex:adversarial-review` operations
- Any task where the `--write` flag is absent

```javascript
// Example: pure review with read-only sandbox
await runAppServerTurn(cwd, {
  model: "gpt-5.4",
  sandbox: "read-only",   // default – no file writes allowed
  prompt: "Please review the changes in this PR."
});

```

## Workspace‑Write Mode: Automated Code Modification

The **`workspace-write`** sandbox lifts all write restrictions, granting Codex the ability to create, edit, and delete files within the workspace. After execution, the plugin identifies modified files through `collectTouchedFiles` and surfaces them as *touched files* in the response.

This mode is activated for:

- `/codex:rescue` automation commands
- Any task invoked with the `--write` flag
- Explicit user requests for code generation or refactoring

```javascript
// Example: task with write permissions
await runAppServerTurn(cwd, {
  model: "gpt-5.4",
  sandbox: "workspace-write",   // write access granted
  prompt: "Fix the failing test and commit the patch."
});

```

## Side‑by‑Side Comparison

| Aspect | Read‑Only | Workspace‑Write |
|--------|-----------|-----------------|
| **File system access** | Read only | Read and write |
| **Use case** | Code review, analysis | Bug fixes, refactoring, file generation |
| **CLI trigger** | `/codex:review` | `/codex:rescue` or `--write` flag |
| **Safety guarantee** | Zero modifications | Changes tracked as *touched files* |
| **Source location** | Default in `buildThreadParams` | Conditional in `executeTaskRun` |

## Security and Workflow Implications

The **sandbox choice is the sole enforcement mechanism** separating review‑only from write‑allowed actions. This design provides:

- **Defense in depth**: Even if Codex generates code that attempts file operations, the read‑only sandbox blocks execution at the system level.
- **Explicit opt‑in**: Users must intentionally request write mode through flags or specific commands.
- **Auditability**: Write operations emit `collectTouchedFiles` metadata for change tracking.

## Summary

- **Read‑only sandbox** is the default safety mode that permits inspection without risk of repository modification.
- **Workspace‑write sandbox** enables full automation by granting Codex permission to apply code changes directly.
- The mode selection happens in `codex.mjs` (default) and `codex-companion.mjs` (task‑time override) based on the `write` flag.
- CLI commands map cleanly: review operations stay read‑only, rescue and `--write` tasks elevate to workspace‑write.

## Frequently Asked Questions

### How do I know which sandbox mode Codex is using?

The sandbox mode is visible in the plugin's internal `runAppServerTurn` calls. End users can infer the mode from the command: `/codex:review` always uses read‑only, while `/codex:rescue` or any `--write` invocation uses workspace‑write.

### Can Codex accidentally write files in read‑only mode?

No. The sandbox restriction is enforced at the runtime level, below the application layer. Even if Codex generates code containing file write operations, the underlying execution environment blocks those syscalls.

### What happens to files modified in workspace‑write mode?

The plugin's `collectTouchedFiles` mechanism tracks all changes. After task completion, modified files are reported back to the user for review, ensuring visibility into exactly what Codex altered.