multi-agent.md Codex Docs, 2026-03-03 00:35 UTC → 2026-03-03 18:20 UTC

51- Ask Codex directly to steer a running sub-agent, stop it, or close completed agent threads.51- Ask Codex directly to steer a running sub-agent, stop it, or close completed agent threads.

52- The `wait` tool supports long polling windows for monitoring workflows (up to 1 hour per call).52- The `wait` tool supports long polling windows for monitoring workflows (up to 1 hour per call).

53 53 

54## Process CSV batches with sub-agents

55 

56Use `spawn_agents_on_csv` when you have many similar tasks that can be expressed as one row per work item. Codex reads the CSV, spawns one worker sub-agent per row, waits for the full batch to finish, and exports the combined results to CSV.

57 

58This works well for repeated audits such as:

59 

60- reviewing one file, package, or service per row

61- checking a list of incidents, PRs, or migration targets

62- generating structured summaries for many similar inputs

63 

64The tool accepts:

65 

66- `csv_path` for the source CSV

67- `instruction` for the worker prompt template, using `{column_name}` placeholders

68- `id_column` when you want stable item ids from a specific column

69- `output_schema` when each worker should return a JSON object with a fixed shape

70- `output_csv_path`, `max_concurrency`, and `max_runtime_seconds` for job control

71 

72Each worker must call `report_agent_job_result` exactly once. If a worker exits without reporting a result, that row is marked as failed in the exported CSV.

73 

74Example prompt:

75 

76```

77Create /tmp/components.csv with columns path,owner and one row per frontend component.

78 

79Then call spawn_agents_on_csv with:

80- csv_path: /tmp/components.csv

81- id_column: path

82- instruction: "Review {path} owned by {owner}. Return JSON with keys path, risk, summary, and follow_up via report_agent_job_result."

83- output_csv_path: /tmp/components-review.csv

84- output_schema: an object with required string fields path, risk, summary, and follow_up

85```

86 

87When you run this through `codex exec`, Codex shows a single-line progress update on `stderr` while the batch is running. The exported CSV includes the original row data plus metadata such as `job_id`, `item_id`, `status`, `last_error`, and `result_json`.

88 

89Related runtime settings:

90 

91- `agents.max_threads` caps how many agent threads can stay open concurrently.

92- `agents.job_max_runtime_seconds` sets the default per-worker timeout for CSV fan-out jobs. A per-call `max_runtime_seconds` override takes precedence.

93- `sqlite_home` controls where Codex stores the SQLite-backed state used for agent jobs and their exported results.

94 

54## Approvals and sandbox controls95## Approvals and sandbox controls

55 96 

56Sub-agents inherit your current sandbox policy, but they run with97Sub-agents inherit your current sandbox policy.

57non-interactive approvals. If a sub-agent attempts an action that would require98 

58a new approval, that action fails and the error is surfaced in the parent99In interactive CLI sessions, approval requests can surface from inactive agent

59workflow.100threads even while you are looking at the main thread. The approval overlay

101shows the source thread label, and you can press `o` to open that thread before

102you approve, reject, or answer the request.

103 

104In non-interactive flows, or whenever a run cannot surface a fresh approval,

105an action that needs new approval fails and the error is surfaced back to the

106parent workflow.

107 

108Codex also reapplies the parent turn’s live runtime overrides when it spawns a

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

110the session, such as `/approvals` changes or `--yolo`, even if the selected

111agent role loads a config file with different defaults.

60 112 

61You can also override the sandbox configuration for individual [agent roles](#agent-roles) such as explicitly marking an agent to work in read-only mode.113You can also override the sandbox configuration for individual [agent roles](#agent-roles) such as explicitly marking an agent to work in read-only mode.

62 114 

88| --- | --- | --- | --- |140| --- | --- | --- | --- |

89| `agents.max_threads` | number | No | Maximum number of concurrently open agent threads. |141| `agents.max_threads` | number | No | Maximum number of concurrently open agent threads. |

90| `agents.max_depth` | number | No | Maximum nesting depth for spawned agent threads (root session starts at 0). |142| `agents.max_depth` | number | No | Maximum nesting depth for spawned agent threads (root session starts at 0). |

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

91| `[agents.<name>]` | table | No | Declares a role. `<name>` is used as the `agent_type` when spawning an agent. |144| `[agents.<name>]` | table | No | Declares a role. `<name>` is used as the `agent_type` when spawning an agent. |

92| `agents.<name>.description` | string | No | Human-facing role guidance shown to Codex when it decides which role to use. |145| `agents.<name>.description` | string | No | Human-facing role guidance shown to Codex when it decides which role to use. |

93| `agents.<name>.config_file` | string (path) | No | Path to a TOML config layer applied to spawned agents for that role. |146| `agents.<name>.config_file` | string (path) | No | Path to a TOML config layer applied to spawned agents for that role. |

96 149 

97- Unknown fields in `[agents.<name>]` are rejected.150- Unknown fields in `[agents.<name>]` are rejected.

98- `agents.max_depth` defaults to `1`, which allows a direct child agent to spawn but prevents deeper nesting.151- `agents.max_depth` defaults to `1`, which allows a direct child agent to spawn but prevents deeper nesting.

152- `agents.job_max_runtime_seconds` is optional. When you leave it unset, `spawn_agents_on_csv` falls back to its per-call default timeout of 1800 seconds per worker.

99- Relative `config_file` paths are resolved relative to the `config.toml` file that defines the role.153- Relative `config_file` paths are resolved relative to the `config.toml` file that defines the role.

100- `agents.<name>.config_file` is validated at config load time and must point to an existing file.154- `agents.<name>.config_file` is validated at config load time and must point to an existing file.

101- If a role name matches a built-in role (for example, `explorer`), your user-defined role takes precedence.155- If a role name matches a built-in role (for example, `explorer`), your user-defined role takes precedence.