Repository navigation
spawn_agent returns "unsupported call" despite multi_agent feature being enabled #10
Description
Environment:
- Codex CLI 0.134.0 (npm install)
- App-server daemon 0.131.0 (stale)
- codex features list shows multi_agent stable true
- Config has [features]\nsubagents = true (note: subagents is an unrecognized key; the correct key is multi_agent)
Steps to reproduce:
- Run a Codex CLI interactive session
- Attempt to call spawn_agent (which is listed among available tools)
- Receive error: unsupported call: spawn_agent
Expected behavior:
spawn_agent should successfully create a sub-agent or, if the runtime doesn't support it, the tool should not be presented as available to the model.
Actual behavior:
The tool is listed as available but returns "unsupported call: spawn_agent" when invoked. This suggests the tool definition is injected into the model's tool-use schema but the backend
routing (likely the app-server daemon) doesn't actually handle it.
Additional findings:
- The config had subagents = true (unrecognized key — silently ignored). The correct feature flag is multi_agent = true, though this didn't fix the issue since multi_agent was already
enabled by default. - The app-server daemon is stale (v0.131.0 vs CLI v0.134.0). Restarting/updating the app-server may be needed for spawn_agent routing.
- The app-server log shows codex_core::tools::router exec_command failures (No such file or directory), suggesting it's in a degraded state.
Suggested fix:
- Ensure spawn_agent is only exposed as an available tool when the runtime actually supports it (i.e., feature gate the tool registration)
- OR provide a more descriptive error message explaining what's missing (e.g., "spawn_agent requires the app-server daemon to be running and up-to-date")
- Document the prerequisite: what runtime components must be active for spawn_agent/wait_agent/close_agent to work
Activity
mountain commentedon May 28, 2026
Thanks for the detailed report. Based on the environment details here, the likely root cause is the Codex runtime split rather than codex-relay tool translation:
0.134.0.0.131.0and marked stale.multi_agentfeature being stable/enabled is consistent withspawn_agentbeing exposed to the model.codex-relayshould preserve these function-call primitives instead of filtering them: it forwardsspawn_agent/wait_agent/close_agentas normal function tools to the upstream model, then maps the selected function call back into a Responses APIfunction_callfor Codex to execute. Theunsupported call: spawn_agenterror means the Codex-side tool dispatcher that receives the returned call does not have a handler for it. A stale app-server daemon is the most plausible way to get that mismatch: the newer CLI/tool schema exposesspawn_agent, while the older daemon cannot route it.Recommended next steps:
0.131.0, update/reinstall Codex so both CLI and app-server are0.134.0or newer.[features] subagents = truekey and use[features] multi_agent = trueonly if you need to override the default.unsupported call: spawn_agentevent plus the inbound/v1/responsestools list, and we can look for a relay-side round-trip issue.For now I do not think codex-relay should default-filter subagent tools, because that would break supported Codex subagent workflows for users with a current runtime.
mountain commentedon May 28, 2026
Released
v0.2.2with additional debug support for this class of issue: https://github.com/MetaFARS/codex-relay/releases/tag/v0.2.2With
RUST_LOG=codex_relay=debug, the relay now logs tool names at the key boundaries without logging arguments or message content:response tools=...for tools received from Codexupstream tools=...for tools forwarded to the Chat Completions upstreamupstream function_calls=.../upstream stream function_calls=...for tool calls returned by the upstream modelThat should make it straightforward to verify whether
spawn_agentis preserved by the relay and whether the failure is happening after Codex receives the returned function call.mountain commentedon May 28, 2026
Re-reading this, I think my previous reply was too focused on the likely stale app-server root cause and not enough on the contract problem you reported.
The important issue here is:
spawn_agentis presented to the model as available, but the runtime that receives the returned function call may not actually be able to route it.v0.2.2only makes that boundary easier to diagnose; it does not fully address the UX failure.From the relay side, I do not think we can reliably auto-detect whether the local Codex app-server supports
spawn_agent/wait_agent/close_agent, because the relay only sees the/v1/responsesrequest and the tool schema Codex already chose to send. So I still do not want to silently filter these tools by default, since that would break users whose current Codex runtime does support multi-agent calls.But I agree this needs a relay-side mitigation/documentation path. I will keep this issue open and treat the actionable work as:
subagentsis not a recognized feature key, and stale daemons can expose tools that they cannot execute.spawn_agent,wait_agent, andclose_agentfrom the upstream model schema instead of letting the model select calls that Codex will reject.v0.2.2as the verification path for confirming whether the relay preserved the tool and whether the failure happened after the function call was returned to Codex.Thanks for pushing on this. The better framing is not “feature flag is off”; it is “tool availability and execution capability can get out of sync, and relay should give users a clear escape hatch when Codex sends tools that their runtime cannot route.”
mountain commentedon May 28, 2026
Opened draft PR #11 with the relay-side mitigation: #11
The PR keeps subagent tools enabled by default, adds an opt-in
CODEX_RELAY_TOOL_DENYLISTescape hatch, and documents the CLI/app-server version mismatch case. CI is green now.Please verify on the affected runtime with:
CODEX_RELAY_TOOL_DENYLIST=spawn_agent,wait_agent,close_agent codex-relayThat should remove those tools from the upstream model schema so the model cannot select calls that the stale Codex app-server rejects. I am leaving the PR as draft until we get runtime validation.