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

[Zbyy0311]

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

[lidge-jun]

Closing: this is a UX documentation enhancement, not a defect. The V2 compatibility and recovery state explanation is a documentation/UX task that should be tracked separately from the bug queue.

[lidge-jun]

Reopened — reclassification does not justify closing. Keeping open as a valid UX improvement.

[Wibias]

Triage relationship

Parent tracker: #92.

This issue is the dashboard warning/recovery UX child of the upstream encrypted V2 task transport limitation. A mitigation here must not be treated as fixing the underlying protocol problem.

[lidge-jun]

리뷰 · 우선순위 34 / 80

라우트된 모델을 선호 서브에이전트로 고를 때, 네이티브 부모가 V2로 자식을 보내면 암호문만 와서 실패할 수 있는데, 대시보드가 그 상태를 설명하지 않는다는 UX 이슈입니다. #1540/#1556 이후 V1만 우회로 보여주면 안 되고, 실험적 V2 복구가 켜졌는지도 말해야 합니다.

현재 dev의 src/server/responses/core.ts는 실패 코드 unreadable_encrypted_agent_task를 냅니다. src/server/index.ts는 실험적 암호화 V2 복구가 켜지면 경고를 찍습니다. 대시보드 에이전트 설정은 src/server/management/agent-settings-routes.ts의 multiAgentMode와 multiAgentModeHintText입니다. 선호 워커가 라우트 모델일 때 네이티브-to-라우트 V2 호환 문구를 붙이는 필드는 이 라우트에 없습니다.

원하는 안내는 복구가 꺼져 있으면 암호문 실패 가능성과 V1 또는 실험 복구 옵션을 보여 주고, 켜져 있으면 네이티브 V2와 같다고 말하지 않는 것입니다. 라우트 부모처럼 이미 읽기 가능한 흐름은 잘못된 경고를 주면 안 됩니다. #92 업스트림 제한과 일반 프로바이더 오류도 구분해야 합니다.

해결방안: 선호 모델 컨트롤 옆에 실제 협업 모드와 복구 on/off를 반영한 문구를 두면 됩니다. 라우트 워커 하나 때문에 V1을 전역으로 강제하면 안 됩니다. 복구를 켠다고 업스트림 와이어가 고쳐지지는 않습니다. GUI 카피 위치는 이 라우트만으로 단정하지 않아 패치는 추측하지 않음.

이 댓글은 grok-bot이 작성했습니다

[lidge-jun]

리뷰 · 우선순위 34 / 80 · 유지

네이티브 부모 + 라우티드 preferred 서브에이전트면 V2 자식 태스크가 암호문으로 와서 unreadable_encrypted_agent_task로 죽음. #1540/#1556 실험적 복구는 기본 꺼져 있고, 업스트림 한계는 #92. 대시보드가 그 조합이 되는지, 복구가 켜져 있는지를 아직 안 보여 줌.

이건 UX 안내 이슈로 유지함. 암호 복호를 푸는 티켓이 아님. 피커에서 라우티드 자식을 고를 때 호환/복구 상태를 보여 주면 됨. V1만 워크어라운드로 적어 두면 안 됨.

해결방안: 대시보드 preferred 서브에이전트 쪽에 native→routed V2 호환 배지 + 복구 opt-in 여부. 코어 복호는 #92 쪽.

이 댓글은 grok-bot이 작성했습니다