multi_agent.usage_hint renders an invalid collaboration spawn recipient

Summary

When native multi-agent support is enabled, the developer multi_agent.usage_hint renders this direct-call example:

to=functions.collaboration.spawn_agent

But the actual successful tool invocation is registered as:

{"namespace":"collaboration","name":"spawn_agent"}

The rendered recipient therefore does not resolve to the registered top-level tool. It is also unavailable inside functions.exec, where ALL_TOOLS has no collaboration operations.

What end users may see

Delegation can fail silently: a requested subagent is not launched, while Codex instead runs a harmless no-op such as true, potentially repeatedly, or selects another unrelated execution or wait operation. The no-op manifestation is intermittent; the inconsistent rendered recipient is the confirmed defect.

For workflows pursuing an active /goal, this can stall required delegation. The bad recipient does not itself change goal status, but a coordinator can incorrectly interpret the resulting no-op or missing delegate result as a blocker and explicitly mark the active goal blocked. This was observed in the affected long-running workflow and later had to be corrected manually.

Environment

• Codex CLI 0.153.4
• Linux
• Native multi-agent support enabled

Reproduction

1. Start Codex with agents enabled.
2. Run a read-only prompt-render inspection, for example:

codex -c agents.enabled=true debug prompt-input "delegation probe"

3. Inspect the native developer item of kind multi_agent.usage_hint.
4. Observe to=functions.collaboration.spawn_agent.
5. Inspect an actual successful direct spawn in the rollout: its function call uses namespace collaboration and name spawn_agent, not the nested functions.collaboration namespace.

With agents.enabled=false, this usage hint is absent. Varying the agent-slot count changes the native hint, which further indicates that it is generated by the native prompt renderer.

Impact

In one long-running session, the invalid hint coexisted with the valid direct tool. The model repeatedly selected exec with cmd: "true" rather than attempting a collaboration call. The transcript proves the model selected exec; it does not prove that this exact invalid literal deterministically caused each no-op. However, the hint is objectively inconsistent with the registered tool contract and can direct a model toward an unreachable recipient.

Related behavior is reported in #35620 and #37113, but this report is specifically about the incorrect recipient rendered in multi_agent.usage_hint.

Expected behavior

Every rendered to= recipient should resolve exactly against the top-level tool catalog exposed to the model. The spawn example should use:

to=collaboration.spawn_agent

or whatever recipient form is derived from the registered tool contract.

Proposed fix and regression

Render collaboration examples from the registered top-level tool catalog instead of maintaining a hard-coded namespace string.

Add a renderer test that:

1. Registers collaboration.spawn_agent.
2. Renders multi_agent.usage_hint.
3. Parses every to= recipient and asserts that it resolves in the registered top-level catalog.
4. Asserts the spawn example is collaboration.spawn_agent.
5. Renames the fixture namespace and verifies that the rendered recipient changes with it, proving it is derived rather than hard-coded.
6. Verifies that disabling agents emits neither the multi-agent hint nor collaboration tools.

A black-box regression can assert that debug prompt-input contains the valid recipient and not functions.collaboration.spawn_agent.

Start with the debug prompt-input entry point and the multi_agent.usage_hint renderer, then inspect the registered top-level tool catalog and existing renderer tests. Done means the rendered spawn recipient resolves against that catalog, changes with the registered namespace, and the hint and collaboration tools are absent when agents are disabled.