subagents.md Codex Docs, 2026-04-17 00:44 UTC → 2026-05-18 22:01 UTC

60 60 

61Codex also reapplies the parent turn's live runtime overrides when it spawns a61Codex also reapplies the parent turn's live runtime overrides when it spawns a

62child. That includes sandbox and approval choices you set interactively during62child. That includes sandbox and approval choices you set interactively during

63the session, such as `/approvals` changes or `--yolo`, even if the selected63the session, such as `/permissions` changes or `--yolo`, even if the selected

64custom agent file sets different defaults.64custom agent file sets different defaults.

65 65 

66You can also override the sandbox configuration for individual [custom agents](#custom-agents), such as explicitly marking one to work in read-only mode.66You can also override the sandbox configuration for individual [custom agents](#custom-agents), such as explicitly marking one to work in read-only mode.

97Global subagent settings still live under `[agents]` in your [configuration](https://developers.openai.com/codex/config-basic#configuration-precedence).97Global subagent settings still live under `[agents]` in your [configuration](https://developers.openai.com/codex/config-basic#configuration-precedence).

98 98 

99| Field | Type | Required | Purpose |99| Field | Type | Required | Purpose |

100| --- | --- | --- | --- |100| -------------------------------- | ------ | :------: | ---------------------------------------------------------- |

101| `agents.max_threads` | number | No | Concurrent open agent thread cap. |101| `agents.max_threads` | number | No | Concurrent open agent thread cap. |

102| `agents.max_depth` | number | No | Spawned agent nesting depth (root session starts at 0). |102| `agents.max_depth` | number | No | Spawned agent nesting depth (root session starts at 0). |

103| `agents.job_max_runtime_seconds` | number | No | Default timeout per worker for `spawn_agents_on_csv` jobs. |103| `agents.job_max_runtime_seconds` | number | No | Default timeout per worker for `spawn_agents_on_csv` jobs. |

112### Custom agent file schema112### Custom agent file schema

113 113 

114| Field | Type | Required | Purpose |114| Field | Type | Required | Purpose |

115| --- | --- | --- | --- |115| ------------------------ | -------- | :------: | --------------------------------------------------------------- |

116| `name` | string | Yes | Agent name Codex uses when spawning or referring to this agent. |116| `name` | string | Yes | Agent name Codex uses when spawning or referring to this agent. |

117| `description` | string | Yes | Human-facing guidance for when Codex should use this agent. |117| `description` | string | Yes | Human-facing guidance for when Codex should use this agent. |

118| `developer_instructions` | string | Yes | Core instructions that define the agent's behavior. |118| `developer_instructions` | string | Yes | Core instructions that define the agent's behavior. |