`.agents/` writes blocked even when added via `--add-dir` or in `writable_roots`

.agents/ writes blocked even when added via --add-dir or in writable_roots

Summary

In codex-cli 0.130.0 on macOS, writes to any path under a workspace's .agents/ directory return Operation not permitted even when:

• The directory is the current working directory's subdirectory (workspace-write sandbox)
• .agents is explicitly passed via --add-dir .agents
• The startup banner confirms .agents appears in the sandbox writable list

This appears to be an intentional protection of the .agents/ namespace (used for plugin marketplace registry at .agents/plugins/marketplace.json and skills), but I could not find a documented way to override it for project-internal files that happen to live under .agents/ for reasons predating Codex's plugin convention.

Environment

• codex-cli 0.130.0 (Homebrew, native binary codex-darwin-arm64)
• macOS 25.5.0 (Darwin arm64)
• ~/.codex/config.toml: approval_policy = "never", [sandbox_workspace_write] with network_access = true only
• Project root: arbitrary repo with a pre-existing .agents/ directory containing internal artifacts (failure_ledger.md, eval_cases/, etc.) unrelated to Codex's plugin marketplace

Reproduction

cd <repo-root>   # repo-root contains an existing .agents/ directory
codex exec \
  --cd "$PWD" \
  --add-dir .agents \
  --skip-git-repo-check \
  --sandbox workspace-write \
  'Run: touch .agents/.codex_write_test ; echo exit=$?'

Startup banner shows .agents is included:

sandbox: workspace-write [workdir, /tmp, $TMPDIR, /<repo>/.agents, /Users/<user>/.codex/memories] (network access enabled)

But the command output is:

touch: .agents/.codex_write_test: Operation not permitted
exit=1

Controlled comparison (same session, same cwd, workspace-write, no --add-dir)

| Target | Result |
| --- | --- |
| touch scripts/.codex_test (existing non-dot subdir) | exit=0 ✅ |
| mkdir .codex_new_dotdir && touch .codex_new_dotdir/.codex_test (newly created dot subdir) | exit=0 ✅ |
| touch /tmp/.codex_test (writable root) | exit=0 ✅ |
| touch .agents/.codex_test (existing .agents/) | Operation not permitted ❌ |
| touch .agents/eval_cases/.codex_test (existing subpath) | Operation not permitted ❌ |

So:

• It is not a generic "dotdir" restriction (newly created dotdirs are writable).
• It is not a com.apple.provenance xattr issue (sibling scripts/ has the same xattr and is writable).
• It is specifically .agents/ that is blocked, even when explicitly added via --add-dir.

Questions

1. Is the .agents/ block intended to apply to all workspaces, regardless of whether the project actually uses Codex's plugin marketplace convention?
2. If yes, what is the recommended way to override it for projects that have an unrelated .agents/ directory (predating Codex's adoption of this path)?
3. Is [permissions] profile system (permission_profile / default_permissions in config.toml) the documented escape hatch? If so, could the docs include a minimal example that grants write for a project-specific subpath inside .agents/?
4. Should --add-dir .agents either succeed at granting write, or fail loudly at invocation time? The current behavior (silent override after the path is shown in the writable list) is confusing.

Workaround

For now we are routing .agents/ writes through Claude Code (which has no equivalent .agents/ block). It would be nice to keep the work in Codex when the project's .agents/ predates Codex's plugin marketplace convention.

Source reference

Strings in the binary point to cli/src/debug_sandbox/seatbelt.rs and mention FileSystemAccessMode with a 'none' beats 'write' precedence rule, plus a [permissions] profile system referenced via permission_profile / default_permissions. I could not find user-facing docs for the latter.

Related issues

Same "special dot-named directory blocked even after --add-dir" pattern, but for .git/ rather than .agents/:

• #23661 Linked worktree git add fails: .git/worktrees index.lock remains read-only despite --add-dir
• #7071 CLI sandbox: cannot commit because .git is read-only

And an opposite-direction issue for the same flag:

• #24214 codex exec --sandbox workspace-write --add-dir X: apply_patch tool ignores --add-dir whitelist and writes anywhere under --cd

These suggest --add-dir semantics are inconsistent across protected paths and underlying tools (exec vs apply_patch), and it might be worth documenting the intended boundaries.