Allow spawn_agents_on_csv to use instruction files or custom agent roles

What feature would you like to see?

Please add a first-class way for spawn_agents_on_csv jobs to reuse instruction files and/or existing custom agent roles, instead of requiring the caller/model to inline a long per-row instruction string in the tool call.

One possible API shape:

{
  "csv_path": "tasks.csv",
  "instruction_path": ".codex/jobs/review-one-row.md",
  "agent_type": "reviewer",
  "id_column": "path",
  "output_csv_path": "out.csv"
}

Suggested semantics:

• instruction_path: read the file content once when creating the job, then use it as the existing instruction template. The current {column_name} substitution behavior should still apply.
• instruction and instruction_path: require exactly one, or allow both only with a clear precedence rule.
• agent_type: reuse the same role/custom-agent resolution used by spawn_agent, so CSV workers can run as default, worker, explorer, or a project/global custom agent from .codex/agents/*.toml / ~/.codex/agents/*.toml.
• If both agent_type and instruction_path are supplied, the role's developer_instructions define the worker role/config, while the instruction file defines the per-row task template.

Why this matters

spawn_agents_on_csv is useful for fan-out batch workflows, but the current interface makes complex jobs hard to reuse and hard to audit. The model has to place the full worker instructions directly in the instruction string. For realistic jobs, that can be hundreds of lines: rubric, output contract, examples, safety constraints, domain context, retry rules, etc.

That creates a few practical problems:

• Long tool arguments are fragile and noisy.
• The parent agent has to spend context copying instructions rather than referring to a stable file.
• Teams cannot review/version the batch worker prompt as a normal repository artifact.
• CSV workers cannot easily reuse the same custom subagent role that normal spawn_agent workflows use.
• There is no clean way to combine batch fan-out with per-role settings such as model, reasoning effort, sandbox, MCP servers, or skills config.

Codex already has adjacent abstractions that solve this elsewhere: custom agents are identified by name, and instruction files/config layers are already a documented part of Codex configuration. It would be natural for CSV fan-out workers to plug into the same mechanism.

Current behavior

Today spawn_agents_on_csv accepts an instruction string template and applies {column} placeholders from each CSV row. It does not expose an instruction_path parameter and does not expose an agent_type/custom-agent role parameter for workers.

The canonical demo in #12832 also shows the current inline-only shape:

instruction: "Run ... then output JSON ..."

That works for short tasks, but becomes unwieldy for complex/reusable batch workflows.

Related issues

• #12832 documents the current spawn_agents_on_csv multi-agent workflow.
• #15250 describes a related docs/runtime mismatch around invoking custom subagents by name in tool-backed sessions.
• #21546 asks for an explicit instruction-file option for codex exec, motivated by avoiding large inline instruction blocks.
• #18994 highlights the broader difficulty of packaging reusable subagent instructions in skills/workflows.

Possible implementation direction

For instruction_path, resolve the path relative to the turn cwd using the same path resolution style as csv_path / output_csv_path, read it during job creation, store the resolved instruction text in the job record, and leave the existing per-row template rendering unchanged.

For agent_type, persist the requested role name on the job and apply the same role resolution/config layering used by spawn_agent before spawning each worker. This would let batch jobs reuse built-in and custom agent roles without forcing the model to manually read and paste developer_instructions into the per-row prompt.