Codex subagents: configure roles and verify the workflow

Published on November 8, 2026 by Steven Jones

Codex subagents let a main coding Agent delegate bounded jobs to separate Agent threads, then inspect their findings before producing a combined answer. The useful question is not how many agents you can launch. It is whether each child investigated a different risk, returned evidence and finished before the coordinator approved the review.

This walkthrough uses a WordPress plugin review with deliberately seeded defects. It covers current Codex configuration, two custom roles, a repeatable launch prompt, an interruption drill and the evidence needed to confirm that delegation actually happened. The example is a test fixture, not a claim that a live Codex run has already produced the results described below.

Start with a read-only review, not an experimental flag

OpenAI’s Codex subagent documentation says current Codex releases enable subagent workflows by default. The older advice to switch on an experimental multi-agent feature is not the starting point for a current installation. In an interactive CLI session, you can ask directly for delegation and use /subagents to inspect the active and completed threads.

Use a committed review branch and a stable comparison target. If an Agent examines files while another Agent changes them, its findings can refer to different versions of the code. For this exercise, neither child may edit files or create further agents. Where a project also uses tools through MCP, check the separate permission boundary described in our Codex CLI MCP setup guide before treating the review as read-only.

codex --version
git rev-parse HEAD
git status --short
git diff --name-status main...HEAD
codex --sandbox read-only --ask-for-approval on-request

Replace main with your actual base branch. Record the CLI version and commit SHA alongside the review. Once Codex starts, use /status to record the active model, reasoning setting, permissions and session identifier. Do not fill those fields from a blog post: available models and effective settings depend on the client and account.

---

---

Configure two roles that cannot quietly take over each other’s jobs

Create .codex/config.toml in a trusted project. Current releases do not need agents.enabled = true, although explicitly disabling it will stop delegation. The concurrency limit below is intentional: a two-agent review is easier to audit than a large fan-out.

[agents]
max_concurrent_threads_per_session = 2
interrupt_message = true

Next, create the following files under .codex/agents/. The required keys are name, description and developer_instructions. We leave the model unspecified so each role inherits the parent’s supported configuration, rather than pinning a model that may be unavailable.

.codex/agents/security_reviewer.toml

name = "security_reviewer"
description = "Review WordPress admin actions for permission and request-validation risks."
developer_instructions = """
Read-only investigation. Inspect the changed admin action and its callers.
Check capability gates, nonces, input types, sanitisation and escaping.
Do not edit files, install tools or spawn more agents.
Return: finding, severity, file:line, triggering condition,
proposed verification, and any unverified assumptions.
"""

.codex/agents/test_reviewer.toml

name = "test_reviewer"
description = "Identify missing regression tests for the changed WordPress action."
developer_instructions = """
Read-only investigation. Inspect changed tests and the action they cover.
Identify missing authorised, unauthorised and malformed-input cases.
Do not edit files, install dependencies or spawn more agents.
Do not claim a test passed unless its command and result were observed.
Return: missing case, relevant file:line, suggested assertion,
and the validation command or fixture required.
"""

A TOML file proves that a role was defined, not that Codex dispatched it. Also, the instruction to avoid edits is behavioural guidance; the read-only sandbox selected for the parent is the actual local write boundary inherited by its children. MCP tools may have separate permissions. If you maintain reusable review policies as Codex Skills, keep the roles small and let the skill supply the longer checklist rather than duplicating it in every Agent file.

Use a known-defect WordPress fixture to test the handoffs

The test target is a private scratch branch containing an administrative form handler. This is deliberately insecure code for a review exercise. Do not ship it as a working plugin endpoint:

add_action('admin_post_diyai_save_banner', static function (): void {
    $text = $_POST['banner_text'] ?? '';
    update_option('diyai_banner_text', $text);
    wp_safe_redirect(admin_url('options-general.php?page=diyai-banner'));
    exit;
});

There are three planted review targets. The handler lacks a current_user_can('manage_options') check, it does not verify a nonce, and it passes request data directly into an option without first checking its type, unslashing and sanitising it. The admin_post_ hook requires an authenticated request, but authentication alone does not grant permission to change site settings. A nonce verifies request intent, not user authorisation. Output escaping must also be checked wherever the option is displayed.

For a WordPress integration test, aim to prove that a lower-privilege logged-in user cannot change the option, an authorised user without a valid nonce is rejected, and a valid authorised request stores an appropriately sanitised string. The form must generate the matching nonce. Run tests against a disposable site, never a production database. These are expected checks for the planted fixture, not observed findings from a subagent session.

Dispatch the children explicitly and demand independent evidence

Run the following prompt in the same Codex session that loaded the project configuration. The coordinator should have one job: allocate work, wait, verify and consolidate. It should not write a reassuring summary before its children have reported.

Review this branch against main. Spawn exactly two subagents in parallel:
1. security_reviewer: inspect the changed admin action and call sites.
   Report capability, nonce and input-handling issues with file:line evidence.
2. test_reviewer: inspect the existing tests and identify missing assertions
   for authorisation, CSRF and malformed input. Do not modify files.

Do not create additional agents. Give each child the same commit SHA.
Wait for both results. For every claim, label it observed, inferred or unverified.
Return one combined table with finding, child, evidence, severity,
independent check, and acceptance status. Mark incomplete tasks explicitly.
Do not claim tests were run unless their commands and outputs are available.

During execution, open /subagents. Confirm there are two actual child threads with the expected scopes. Capture their thread identifiers or session references, start and completion states, relevant tool activity and their final responses. A main-thread message saying it has ‘asked two agents’ is insufficient evidence. So is a polished report with no inspectable child activity.

The strongest return artefact is a concise finding with a file and line number, the risky condition, the reason it is exploitable or incorrect, and a direct way to disprove it. A reviewer that merely lists ‘add security checks’ has not established a finding. A second reviewer repeating the first Agent’s prose has not provided independent verification.

Interrupt one child and check whether the coordinator handles the gap.

Run a separate failure drill after the ordinary review. Start the same two-child task, then, while the test reviewer is active, ask the coordinator to stop that child. Use the subagent view to inspect what actually happened. The correct review outcome is not ‘both completed’: the stopped thread’s unreturned checks must remain incomplete until they are reassigned or independently verified.

If the coordinator presents the interrupted child’s partial notes as a finished test assessment, reject the result. Resume or rerun only the missing scope against the same commit, then ask the coordinator to reconcile the new response. The exact interruption event, returned partial artefact and recovery outcome are valuable evidence because they test the handoffs themselves rather than just the model’s ability to identify obvious defects.

What to record before calling the review verified

Evidence	Acceptance rule
Environment	Actual codex --version, OS, Git SHA, base branch, model and reasoning effort
Configuration	Exact config.toml, two role files, active sandbox and approval settings
Dispatch	Two inspectable child threads, distinct assignments and their start/finish states
Return artefacts	File:line findings or explicit ‘no finding’, plus test gaps and uncertainty labels
Interruption	Stopped or failed child identified; omitted checks not accepted as complete
Coordinator checks	Findings checked against the fixed commit, with reproducible validation steps
Cost and speed	Only report a comparison if the same task is repeated with a single-agent baseline

Keep a copy of the review transcript and the relevant child-thread details with the commit. Do not substitute configuration screenshots or isolated script tests for records of actual Agent dispatch. To compare performance, repeat the single-agent and two-agent versions on the same revision with the same model, constraints and acceptance criteria. Record end-to-end time, usage, correct findings, false positives and additional coordination work over multiple runs. Subagents consume additional tokens; parallelism is not automatically cheaper or faster.

Your search, your sources

Make DIY AI a preferred source

See more of our reporting in Google Top Stories, AI Overviews and AI Mode.

Add DIY AI on Google

Failure patterns that a clean final summary can hide

Symptom	Likely issue	What to do
No child threads appear	Delegation was not triggered or configuration was not loaded	Ask explicitly to spawn two agents; inspect /subagents and the effective config
Both agents return the same findings	Scopes overlap or each received the entire vague task	Split security and test-coverage contracts; require different evidence
Review stops at an approval	A tool action needs permission in the parent session	Inspect the requesting thread; approve only the intended operation or keep it blocked
Child reports tests passed but gives no command	Unsupported completion claim	Mark unverified and run the relevant tests independently
One child is cancelled but summary says complete	Coordinator has accepted a partial handoffs	Reopen the missing scope and require a fresh receipt

Reports from developers using parallel coding agents repeatedly describe the same practical trade-off: independent read-heavy tasks can justify the extra coordination, while several agents doing overlapping work often consume more allowance without improving the answer. That is why this example limits fan-out and preserves a stable commit. For a small one-file fix, one Agent plus deterministic tests is usually the simpler choice.

The acceptance gate is the real workflow.

Use Codex subagents for a review only when the jobs can be distinguished, the parent can inspect each return, and the final decision rests on checks outside the agents’ own assertions. For this WordPress example, do not approve the change until capability checks, nonce handling, input processing and the associated regression tests have been inspected against the actual code revision.

A role file, a prompt and a plausible combined answer are setup evidence. Actual child threads, returned artefacts, a documented interruption and independently validated findings are execution evidence. Keep those separate, and the workflow remains auditable even when one Agent fails.