hermes - 💡(How to fix) Fix [Feature]: Codex app-server delegation backend for native-harness subagents

Problem or Use Case

Hermes already has a strong subagent abstraction through delegate_task, but today subagents are tied to Hermes' own provider/client loop or ACP-style child processes. That misses a useful option for OpenAI Codex users: running delegated workers inside the native Codex app-server harness.

The Codex harness is valuable because it is not just another HTTP model provider. It owns Codex session state, tool/runtime semantics, approval/sandbox behavior, streaming item events, and ChatGPT/Codex auth. Some users, myself included, prefer leaf subagents that are consistent in that harness, often with very low or no explicit reasoning effort, while the parent Hermes agent keeps orchestration and product-level workflow control.

The blocker is that Codex does not currently ship an official ACP server in the shape Hermes expects for subagents. Codex does expose codex app-server, so Hermes can support this use case by speaking that app-server protocol directly for delegated leaf workers.

This is related to, but intentionally narrower than, the draft full-runtime work in #24182. That PR explores routing entire Hermes OpenAI turns through Codex app-server. This request is specifically for delegation backend support:

• Keep Hermes as the top-level agent and orchestration/control plane.
• Add a codex-app-server delegation provider for subagents.
• Let leaf workers run inside Codex's native harness.
• Keep nested/orchestrator delegation safe and predictable by default.

Proposed Solution

Add an opt-in delegation backend:

delegation:
  provider: codex-app-server
  model: gpt-5.5
  reasoning_effort: none
  max_concurrent_children: 5
  max_spawn_depth: 2
  orchestrator_enabled: true

Expected behavior:

1. delegation.provider: codex-app-server is treated as a special delegation backend, not a normal runtime provider.

2. Leaf subagents are constructed as Codex app-server children and launched through:

   codex app-server --listen stdio://

3. The child client speaks Codex app-server JSON-RPC over stdio and maps app-server lifecycle/events into the delegate_task result shape.

4. delegation.reasoning_effort maps into Codex turn effort, including none for users who want fast/consistent harness workers without extra reasoning.

5. codex as a bare command is normalized to codex app-server --listen stdio://, because that is the actual protocol server Hermes needs.

6. Hermes doctor / install checks surface whether the Codex CLI is present and usable for this backend.

7. Nested/orchestrator behavior is backend-aware:

   • Codex app-server leaf workers use the native Codex harness.

   • Codex app-server orchestrator workers default back to Hermes-native AIAgent control plane, so recursive work uses real Hermes delegate_task aggregation.

   • Codex-native nested spawning remains experimental behind an explicit flag:

     delegation:
       codex_native_orchestrators: true

The last point matters because during dogfooding we hit the exact mismatch: a Codex app-server child exposed Codex-native collaboration tools such as spawn_agent, but not Hermes delegate_task. That made nested/orchestrator tests return only one child marker instead of aggregating all workers. Fresh-process tests passed once orchestrators defaulted back to Hermes as the reliable control plane while Codex remained the leaf backend.

Alternatives Considered

• Use ACP/Copilot ACP only. This does not cover Codex's native app-server harness and depends on an ACP interface Codex itself does not officially provide in the required shape.
• Treat codex-app-server as a normal runtime provider. That is leaky: it has no HTTP base_url/api_key provider semantics and needs subprocess lifecycle + protocol handling.
• Route the entire OpenAI runtime through Codex app-server. This is promising and is being explored separately in #24182, but it changes the top-level Hermes agent/tool loop. The delegation backend is narrower and lower-blast-radius.
• Make Codex-native orchestrators the default. Dogfooding showed this is not yet reliable because the child harness exposes Codex-native spawn/wait tools, not Hermes delegate_task. The safer default is Hermes-native orchestrators + Codex-native leaves.

Feature Type

Configuration option / Developer experience / Other: subagent delegation backend for the Codex native harness.

Suggested Labels

• type/feature
• tool/delegate
• comp/agent
• provider/openai
• innovation

Scope

Large: new client module plus delegation routing, install/doctor wiring, config example updates, and focused tests.

Contribution

• I'd like to implement this myself and submit a PR

I already have a working branch and am dogfooding it locally. Targeted tests are green, and a fresh Hermes process passed a nested delegation acceptance smoke test.

Current implementation status

Branch on my fork:

• mxdhavgautam:feat/codex-app-server-subagents

Main implementation files:

• agent/codex_app_server_client.py
• tools/delegate_tool.py
• hermes_cli/doctor.py
• scripts/install.sh
• cli-config.yaml.example

Test files:

• tests/agent/test_codex_app_server_client.py
• tests/tools/test_delegate.py
• tests/hermes_cli/test_doctor.py

Validation run on the branch:

python -m pytest \
  tests/tools/test_delegate.py::TestCodexAppServerDelegation \
  tests/tools/test_delegate.py::TestOrchestratorRoleBehavior \
  tests/agent/test_codex_app_server_client.py -q

25 passed in 5.90s

Additional hygiene checks:

python -m py_compile tools/delegate_tool.py agent/codex_app_server_client.py
git diff --check

Live dogfood notes:

• First-level Codex app-server subagents pass.
• Fresh-process nested/orchestrator acceptance passes.
• Existing long-running sessions can remain stale until the Hermes process reloads changed Python modules, which is expected for this kind of live patch.

Environment used for dogfooding:

Hermes CLI: v0.13.0
Codex CLI: codex-cli 0.129.0
Python: 3.12.3
OS: Ubuntu 24.04

Debug Report

N/A for the feature request. The PR includes targeted unit coverage and local dogfood results instead of a hermes debug share report.