[Bug] V1 proactive guidance is skipped when subagent tools are hidden behind code mode #6844

Client or integration

Codex App

Area

Tools / MCP / web search

Summary

With V1 selected and "Tell Codex how to split work" enabled, Codex Desktop does not receive OpenCodex's proactive delegation guidance at Ultra. Native V1 subagents are available and callable through functions.exec / tools / ALL_TOOLS, but the request-visible tool declarations do not contain an individual spawn_agent tool.

Expected: the documented V1 Max/Ultra guidance should work when V1 collaboration tools are available behind code mode.
Actual: collabSurface(parsed) returns null, and multiAgentGuidanceText() returns null before checking the reasoning effort. No active developer <multi_agent_mode> item was found in the retained state for the affected chat. Saved turn metadata confirms that multiple affected turns used Ultra; the global config's Medium default does not explain those turns.

Root cause reproduced using the functions extracted from the installed OpenCodex executable: src/server/responses/collaboration.ts scans parsed.context.tools for the exact name spawn_agent. The observed envelope exposes the outer code-mode tools instead. A directly declared V1 spawn tool is a positive control and does generate the prompt at Max.

Source: https://github.com/lidge-jun/opencodex/blob/main/src/server/responses/collaboration.ts
Documentation: https://opencodex.me/guides/sub-agent-surface/

Suggested direction: recognize reliable collaboration-capability metadata for code-mode hosts, preserving direct-tool detection and the effort/guidance gates. Do not blindly treat every functions.exec request as V1-capable or use the global saved mode as proof of an existing conversation's surface. A host with no collaboration tools must remain a negative control. No software patch was installed during diagnosis. This report concerns V1 guidance, not V2 encrypted-task delivery. This is a proposed fix direction, not a validated patch. Search of existing issues and documentation did not identify an exact duplicate.

Reproduction

Desktop reproduction:

1. Use OpenCodex with multiAgentMode = "v1" and multiAgentGuidanceEnabled = true.
2. Use Codex Desktop's code-mode tool interface with a main model such as gpt-6.1-sol. Select Ultra for the chat.
3. Confirm native V1 tools are available inside functions.exec through tools / ALL_TOOLS (spawn_agent, send_input, resume_agent, close_agent, wait_agent).
4. Inspect only tool declaration identities and actual developer mode items. The affected chat's additional_tools envelope contains namespaces functions, clock, and mcp__cua_repl, with no directly declared spawn_agent.
5. Observe that no active proactive <multi_agent_mode> developer item is added. Explicitly authorized V1 delegation still works; a fresh DeepSeek Flash child completed successfully.

Minimal function-level reproduction in an OpenCodex source checkout (save as repro-v1-code-mode.ts, run with bun run repro-v1-code-mode.ts):

import { collabSurface, multiAgentGuidanceText } from "./src/server/responses/collaboration";

// Sanitized tool identities from the affected chat's wire-visible envelope.
const codeModeTools = [
  { namespace: "functions", name: "exec" },
  { namespace: "functions", name: "wait" },
  { namespace: "functions", name: "request_user_input" },
  { namespace: "functions", name: "request_user_input_async" },
  { namespace: "clock", name: "sleep" },
  { namespace: "mcp__cua_repl", name: "js" },
  { namespace: "mcp__cua_repl", name: "js_reset" },
];
const directV1Tools = [
  { namespace: "multi_agent_v1", name: "spawn_agent" },
  { namespace: "multi_agent_v1", name: "send_input" },
];

for (const [label, tools, effort] of [
  ["code-mode/max", codeModeTools, "max"],
  ["code-mode/ultra", codeModeTools, "ultra"],
  ["direct-v1/max", directV1Tools, "max"],
  ["direct-v1/medium", directV1Tools, "medium"],
] as const) {
  const parsed = {
    modelId: "gpt-6.1-sol", stream: true,
    context: { messages: [], tools },
    options: { reasoning: effort },
  } as any;
  const guidance = await multiAgentGuidanceText(parsed, {
    multiAgentGuidanceEnabled: true,
  });
  console.log({ label, surface: collabSurface(parsed), guidanceAdded: guidance !== null });
}

Observed results are provided below. The equivalent four cases were actually run against the installed executable's extracted functions; this source-checkout snippet is an equivalent reproduction, not a separately executed full integration test. Ultra can arrive as Max on the wire, so both values were tested. No live V1-vs-V2 benchmark or full end-to-end patched fix was run.

Version

2.81.0 (installed macOS OpenCodex runtime)

Operating system

macOS 27.0.1

Provider and model

OpenAI / gpt-6.1-sol; also observed Ultra turns on gpt-6-astra. Explicit V1 child test: deepseek/deepseek-flash.

Logs or error output

Read-only diagnostic using installed OpenCodex functions:
{"case":"Observed code-mode envelope at max","detectedSurface":null,"guidanceAdded":false}
{"case":"Observed code-mode envelope at ultra","detectedSurface":null,"guidanceAdded":false}
{"case":"Control: directly declared V1 tools at max","detectedSurface":"v1","guidanceAdded":true}
{"case":"Control: directly declared V1 tools at medium","detectedSurface":"v1","guidanceAdded":false}

Relevant control flow in collaboration.ts:
collabSurface(): no directly declared spawn_agent -> return null
multiAgentGuidanceText(): surface === null -> return null
The Max/Ultra check is later and is never reached for this tool layout.

These are synthetic diagnostic results, not raw request logs. No exception or HTTP error accompanies the missing guidance.

Screenshots and supporting files

No response

Redacted configuration

OpenCodex config (relevant fields only):

{
  "multiAgentMode": "v1",
  "multiAgentGuidanceEnabled": true,
  "subagentModels": [
    "gpt-6.1-sol",
    "gpt-6-astra",
    "deepseek/deepseek-flash"
  ]
}


All three catalog entries had multi_agent_version = "v1".
The chat's saved turn contexts confirm Ultra on multiple affected turns. The global config.toml default was Medium; the chat-specific effort was verified separately.
Codex used the bundled Desktop executable, reporting codex-cli 0.162.0-alpha.17.2. No alternative patched Codex binary was installed for this diagnosis.

Checks

• I searched existing issues and documentation.
• I removed secrets, tokens, account details, request credentials, and personal data.