Subagent spawn policy conflicts with repo-level workflow instructions

Same bug in codex cli 0.120.0 on Macos Tahoe

Reproduced with these steps:

• fresh chat in an empty folder or a project folder
• GPT 5.4 xhigh
• AGENTS.md (~/.codex/) has explicit ALWAYS use/spawn subagents for Context7 MCP calls (and other explicitly mentioned tools)

I asked the agent why it didn't use a subagent:

<img width="838" height="201" alt="Image" src="https://github.com/user-attachments/assets/272b6607-271f-4da5-b494-a8e6414eaf79" />

-------------------------------------

<img width="812" height="95" alt="Image" src="https://github.com/user-attachments/assets/b4955af6-a9d7-4d36-83f7-45c253224d80" />

Here is my AGENTS.md instruction:

<img width="1132" height="99" alt="Image" src="https://github.com/user-attachments/assets/41e67592-89e1-40e7-9124-25b68038c2b9" />

This happens with a lot of my AGENTS.md instructions about subagents usage.

After-edit reviews, git lookups, websearches etc. get the same "developer instruction priority" issue

+1

I think this issue is directly related to #18319.

In my session, the same policy-conflict pattern showed up:

• a local workflow/skill expected a bounded subagent step
• Codex claimed a higher-priority spawn restriction prevented it
• that restriction was not visible from the normal repo/config surfaces I could inspect

What made it worse in my case is that after I explicitly clarified that research should be delegated to an agent, Codex still did overlapping parent-thread work anyway.

So from my side, #16996 looks like the policy/preference/precedence half of the same broader failure mode reported in #18319: repo-level workflow intent and delegation expectations are not reconciling cleanly with higher-priority session behavior.

I literally have an entire Skill-based and Custom Agents setup centered around this workflow baked into my repo and AGENTS.md, and it still failed to follow it and claimed it was following the system/dev tool instructions, then it rebukes itself and states that obviously user instructions were clear to do the delegation, so those higher-priority instructions do not or should not have mattered. The agent is just confused and cannot follow user instructions.

and the issue is not just context bloat either, it's the core integrity and policy of my entire project based on this delegation policy workflow that requires and mandates independent blind reviews from subagents spawned, because the main agent cannot review itself, it's obviously biased towards no findings. if you simply spawn subagents to independently review the work, it will find a lot of issues the main agent never does. my entire workflow is centered around this for my project, and failing to follow it completely ruins my project, which is what happened. DAYS OF WORK WASTED, AND ANOTHER WEEK OF GOING BACK TO CLEAN UP THE MESS.

thread id: 019d8a20-42a1-7461-b1ad-f93ff7412892

Asked Codex to fix it, it suggested this addition to ~/.codex/config.toml:

[features.multi_agent_v2]
usage_hint_enabled = true
usage_hint_text = '''
Use `spawn_agent` autonomously when delegation materially improves the task.

Repository or workspace instructions such as AGENTS.md may define when and how delegation is appropriate. Treat those instructions as the user's standing delegation policy for the workspace. Do not require a separate live user request before spawning subagents.
'''

Now subagents work as in earlier versions of Codex and properly listen to global user instructions.

_Edit: note that this fix is brittle as it relies on undocumented configuration knobs that might potentially be removed in future builds. This should ideally be fixed by the Codex team rather than monkey patched by end users._

Adding a concrete variant of this failure mode from a long-running repo-governed workflow.

In this case the repository had an AGENTS.md / repo-resident workflow policy that explicitly authorized workflow-mandated role subagents. The local policy’s intent was roughly:

If the active repo canon / control-plane workflow requires reviewer, sweeper, sync-steward, adjudicator, or other named role agents as part of closure, that requirement counts as explicit user authorization to spawn the required subagents.

The repo workflow was built around stage-gated role lanes:

S2 sync steward
S3 policy-purpose adjudicator
S4 router
S5 closure readiness
S6 fresh reviewer
S7 sequential sweeper

But the main agent still treated the higher-priority generic spawn rule as requiring a fresh chat-level phrase like “spawn subagents” before using the repo-mandated role lanes. The result was that it produced stage artifacts and deterministic validator reports locally, but did not actually enact the role provenance the workflow required. In other words:

stage artifact exists

silently substituted for:

role was invoked with the repo-specified model/context policy

or:

role was explicitly waived with rationale and authority

This creates a subtle but serious failure mode for repo-governed workflows:

1. The user grants standing delegation authority in AGENTS.md / repo policy.
2. The workflow requires role-specific subagents for auditability, context separation, or independence.
3. After long context + compaction, the main agent forgets or distrusts that standing authority.
4. The agent falls back to local deterministic reports or asks for redundant authorization.
5. The repo appears to have passed its workcell stages, but the role-lane provenance is false or missing.

Expected behavior:

• Codex should have a first-class way to treat repo-policy-mandated delegation as scoped standing authorization, if allowed by the active session policy.
• If higher-priority policy forbids that, the agent should surface a precise conflict before producing substitute artifacts.
• The runtime should expose a capability/authority signal such as:

{
  "repoMandatedSubagentsAllowed": true,
  "source": "user/repo AGENTS.md",
  "scope": "workflow-mandated roles only",
  "requiresFreshChatAuthorization": false
}

or the opposite:

{
  "repoMandatedSubagentsAllowed": false,
  "reason": "higher-priority session policy requires explicit per-run delegation approval"
}

What should not happen is silent degradation from “spawn the required role lane” to “main agent writes the role report itself.”

This also ties into long-running/compacted sessions: user-granted delegation authority should not live only in the model’s transient chat memory. If the user has explicitly placed the authority in repo policy, Codex should either honor it as a durable scoped authority surface or clearly mark it as non-authoritative under the current session policy.

Adding a current 0.133.0 reproduction from a repo-governed multi-agent workflow.

Environment:

• Codex CLI: 0.133.0
• Platform: Linux x64
• Repo context: Juanma-Voltti/dev-tools, internal tracker issue https://github.com/Juanma-Voltti/dev-tools/issues/6679

Current signal:

• Repo/skill/SOUL surfaces explicitly grant standing authorization for bounded read-only / validation / codebase-exploration subagent fan-out.
• tool_search still exposes multi_agent_v1.spawn_agent with the blanket gate: "Only use spawn_agent if and only if the user explicitly asks..."
• That creates the same precedence conflict reported here: durable repo policy says bounded fan-out is authorized, but tool metadata says a fresh chat-level ask is required.

Primary repo surfaces already corrected:

• https://github.com/Juanma-Voltti/dev-tools/pull/6184
• https://github.com/Juanma-Voltti/dev-tools/pull/6676

Extra checks from today:

• Searching the repo did not find the stale blanket wording in source surfaces after those PRs.
• codex features list shows multi_agent=true, while multi_agent_v2 and enable_fanout are available but off by default.
• Temporary codex debug prompt-input --enable multi_agent_v2 and --enable enable_fanout produced byte-identical prompt input to default for this case, so I could not prove a local config-only workaround changes the model-visible authorization/tool contract.

Expected behavior:
The spawn_agent metadata should distinguish authority classes. Standing authorization from AGENTS.md / skills / repo doctrine should satisfy the ask for bounded info retrieval, validation, codebase exploration, and review probes. Fresh explicit approval should still be required for delegated edits, commits, PR creation, deploys, secrets, external side effects, or other high-blast-radius work.

Without that split, the runtime pushes long-running teams toward either redundant user prompts or serial parent-thread work, even when the repo has already encoded a scoped standing delegation policy.

Suggested policy fix:

Allow spawn_agent when either:

1. the user explicitly asks for sub-agents, delegation, or parallel work, or
2. an activated repo/workflow instruction explicitly calls for bounded sub-agent use.

If the activated workflow says to ask for permission first, Codex should ask once before spawning and then use sub-agents only at steps that actually call for them.

That keeps the guardrail against casual over-delegation, but avoids the current contradiction where a workflow can require a sub-agent while higher-priority tool policy says the model may not spawn one unless the user independently requests delegation.

In the meantime i simply use an orchestrator thread to spawn my new chats with explicit subagents authorizations among other things, it seems to work fine that way