[UX] Explain native-to-routed V2 compatibility and recovery state for preferred sub-agents #1533

Client or integration

OpenCodex Dashboard

Area

Dashboard / sub-agent delegation

Current status

The original UX problem remains, but the mitigation story changed after #1540 and #1556.

OpenCodex now has an experimental, opt-in encrypted V2 task recovery path. It is disabled by default and does not remove the underlying upstream limitation tracked in #92.

Therefore the Dashboard should no longer present V1 as the only workaround. It should explain the effective compatibility state of the selected preferred sub-agent.

Problem

The Dashboard allows a routed model such as deepseek/deepseek-v4-flash to be selected as the preferred sub-agent while default or v2 may place a native parent on the V2 collaboration surface.

For a native parent, the child task can arrive only as backend ciphertext. Without an eligible recovery path, dispatch fails with:

unreadable_encrypted_agent_task

The current configuration surface does not make that constraint clear when the user selects the routed preferred worker.

Expected UX

When a routed preferred worker is selected and the effective collaboration mode can produce native-parent -> routed-child V2 delegation, show contextual compatibility guidance near the preferred-model control.

The guidance should reflect the actual state:

Recovery unavailable or disabled

Explain that native-to-routed V2 delegation may fail because the task can be backend-encrypted.

Offer the reliable alternatives:

• use V1/plaintext-compatible collaboration behavior; or
• enable the experimental V2 recovery path if the deployment is eligible and the user accepts its documented limitations.

Experimental recovery enabled

Do not show the combination as fully equivalent to native V2 delivery.

Explain that OpenCodex may recover unreadable encrypted tasks through the compatibility path from #1540, and that this adds quota, latency, backend-coupling, and fidelity tradeoffs.

Routed-parent workflows

Do not block or incorrectly warn workflows where the task is already readable and the selected routed model is compatible.

Required behavior

• Link the warning/help text to V2 cross-provider sub-agent loses NEW_TASK body in encrypted_content #92 or the corresponding sub-agent documentation.
• Distinguish the upstream V2 transport limitation from an ordinary provider/model error.
• Reflect whether the experimental recovery path is enabled and eligible where that state is available to the Dashboard.
• Do not imply that enabling recovery fixes the upstream wire protocol.
• Do not force V1 globally merely because one routed preferred worker is configured.
• Preserve valid routed-parent and native-child workflows.

Original reproduction

1. Configure a routed preferred sub-agent such as deepseek/deepseek-v4-flash.
2. Use multiAgentMode: default or v2 with a native gpt-5.6-sol parent.
3. Spawn the routed child.
4. Without recovery, task delivery can fail before execution with unreadable_encrypted_agent_task.
5. Observe that the Dashboard gave no compatibility warning when the preferred worker was selected.

Related

• V2 cross-provider sub-agent loses NEW_TASK body in encrypted_content #92 - underlying upstream encrypted V2 task-delivery limitation
• fix(agents): add opt-in encrypted v2 recovery #1540 - merged experimental opt-in encrypted task recovery
• fix(agents): reroute recovered tasks through healthy fallback #1556 - merged fallback rerouting after successful recovery