Codex subagents run specialized agents in parallel and merge their results into one answer. A custom agent cannot loosen the sandbox or approvals of the turn that spawned it, because subagents inherit them. They also use more tokens than a single agent, since each does its own model and tool work.
Defining a custom agent
Per OpenAI's subagents documentation, each custom agent is a standalone TOML file. Personal agents go in ~/.codex/agents/ and project agents in .codex/agents/. Each file must define name, description and developer_instructions. The name is the source of truth, not the file name. Optional fields cover the model and reasoning settings.
Built-in agents are default, worker and explorer. A custom agent with a matching name takes precedence.
Global settings
Under the agents section of config:
enabledturns multi-agent tools on or off, defaulting to true.max_concurrent_threads_per_sessioncaps open spawned-agent threads, excluding the primary.default_subagent_modeland a default reasoning effort set defaults for spawned agents, and explicit spawn values override them.
The page does not mention a maximum nesting depth, so do not assume one.
What is inherited
The documentation is firm: subagents inherit the parent turn's current sandbox and approval settings, including changes made through /permissions or a full-bypass flag. Settings in a custom agent file cannot override the parent's permissions, provider or MCP servers.
It also adds a caution that matters for review agents. Custom instructions can ask an agent to avoid edits, but that does not create a separate read-only sandbox. A "read-only reviewer" defined in text is a request, not a boundary. If you need a true read-only run, start the parent session in a read-only sandbox.
Cost
Subagent workflows use more tokens than single-agent runs. Budget for it by capping concurrent threads, choosing a smaller default model for spawned agents, and keeping spawn prompts focused. Also watch plan limits: the governance page says eligible Codex activity can consume workspace credits and exhausted limits can pause access.
When parallel helps
- Independent reads, such as scanning several packages for one pattern.
- Review of different files by separate agents, then one merged summary.
When tasks touch the same files, parallel edits invite conflicts, so keep write work in one thread.
Governance angle
Because approvals are inherited, your admin controls on sandbox modes and approval policy cover subagents automatically. That is the main reason to enforce those in requirements rather than rely on per-agent text.
Quick check
Can a custom agent file make a subagent read-only?
Not as a sandbox. Subagents inherit the parent's sandbox and approvals. Instructions are only a request.
Where do project-scoped Codex agents live?
In .codex/agents/ in the repository, as standalone TOML files.
Sources
Last reviewed: 19 October 2026.
