feat(delegation): add Codex app-server subagent backend

[mxdhavgautam]

What does this PR do?

Adds an opt-in codex-app-server delegation backend so Hermes can run leaf subagents inside Codex's native app-server harness while keeping Hermes as the reliable top-level agent and nested-orchestration control plane.

Why this exists:

• Codex's app-server harness is powerful and useful for delegated coding workers because it owns Codex auth/session/runtime/tool semantics.
• Codex does not currently provide an official ACP server in the exact shape Hermes expects for subagents.
• Hermes can still support the workflow directly by speaking the Codex app-server JSON-RPC protocol for delegated children.
• Some users want low/no-reasoning Codex-harness leaf workers for consistency, while the parent Hermes agent handles planning, routing, aggregation, and product workflow.

This is intentionally narrower than routing all OpenAI turns through Codex app-server. It only affects delegate_task when the user explicitly configures:

delegation:
  provider: codex-app-server
  model: gpt-5.5
  reasoning_effort: none

Related but distinct work: #24182 explores full optional Codex app-server runtime routing. This PR focuses specifically on subagent delegation backend support.

Related Issue

Fixes #24445

Type of Change

• 🐛 Bug fix (non-breaking change that fixes an issue)
• ✨ New feature (non-breaking change that adds functionality)
• 🔒 Security fix
• 📝 Documentation update
• ✅ Tests (adding or improving test coverage)
• ♻️ Refactor (no behavior change)
• 🎯 New skill (bundled or hub)

Changes Made

• agent/codex_app_server_client.py

  • Adds CodexAppServerSubagent, a stdio JSON-RPC client for codex app-server delegation children.
  • Handles app-server startup, initialize/session lifecycle, turn execution, streaming events, final-response extraction, interrupt/close behavior, and error surfacing.
  • Normalizes bare codex commands to the required app-server invocation: codex app-server --listen stdio://.
  • Maps Hermes delegation reasoning effort into Codex effort semantics, including none.

• tools/delegate_tool.py

  • Treats delegation.provider: codex-app-server as a special delegation backend instead of a normal runtime provider.
  • Builds Codex app-server leaf workers as CodexAppServerSubagent children.
  • Keeps non-Codex delegation behavior unchanged.
  • Adds backend-aware orchestrator prompts:
    • Hermes-native orchestrators are told to use delegate_task.
    • Codex-native orchestrators, when explicitly enabled, are told about Codex-native spawn_agent / wait_agent style tools instead.
  • Defaults Codex app-server orchestrators back to Hermes-native AIAgent control plane so nested delegation remains reliable.
  • Adds experimental delegation.codex_native_orchestrators flag, default false, for dogfooding Codex-native nested spawning later.

• cli-config.yaml.example

  • Documents the new delegation backend knobs.

• hermes_cli/doctor.py

  • Adds Codex CLI detection / diagnostics relevant to this backend.

• scripts/install.sh

  • Adds install-time awareness for Codex CLI availability.

• Tests:

  • Adds tests/agent/test_codex_app_server_client.py for the app-server child client.
  • Extends tests/tools/test_delegate.py for Codex app-server credential resolution, native leaf construction, command normalization, and Hermes-vs-Codex orchestrator routing.
  • Extends tests/hermes_cli/test_doctor.py for the new doctor checks.

How to Test

Targeted 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

Result:

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

Local dogfood checks performed outside the unit suite:

1. Configured Hermes with:

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

2. Verified first-level Codex app-server subagents across terminal/file/web/reasoning tasks.

3. Verified a fresh Hermes process passes a strict nested/orchestrator acceptance test:

   • parent spawns orchestrator
   • orchestrator spawns two leaf workers
   • orchestrator aggregates both results
   • final marker returned: FRESH_PARENT_PASS

Dogfood environment:

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

Checklist

Code

• I've read the Contributing Guide
• My commit messages follow Conventional Commits (fix(scope):, feat(scope):, etc.)
• I searched for existing PRs to make sure this isn't a duplicate
• My PR contains only changes related to this fix/feature (no unrelated commits)
• I've run pytest tests/ -q and all tests pass
• I've added tests for my changes (required for bug fixes, strongly encouraged for features)
• I've tested on my platform: Ubuntu 24.04, Python 3.12.3, Codex CLI 0.129.0

Documentation & Housekeeping

• I've updated relevant documentation (README, docs/, docstrings) — config example and inline docs updated
• I've updated cli-config.yaml.example if I added/changed config keys — or N/A
• I've updated CONTRIBUTING.md or AGENTS.md if I changed architecture or workflows — N/A
• I've considered cross-platform impact (Windows, macOS) per the compatibility guide
• I've updated tool descriptions/schemas if I changed tool behavior — N/A, no schema changes required

For New Skills

N/A.

Screenshots / Logs

Relevant local test output:

25 passed in 5.90s

Fresh-process nested dogfood result:

FRESH_PARENT_PASS

Notes for reviewers

The important architectural choice is that Codex app-server is the default leaf backend only. Orchestrator children still default to Hermes-native AIAgent so they get real delegate_task semantics and aggregation. This avoids the stale failure mode seen during dogfooding where a Codex child exposed spawn_agent but not Hermes delegate_task, resulting in only one child result being surfaced.

If/when Codex-native nested orchestration becomes reliable enough to expose by default, the experimental gate is already present:

delegation:
  codex_native_orchestrators: true

[teknium1]

Thanks for the thorough implementation and the focused delegation design.

This automated hermes-sweeper review is closing this under the standing in-tree provider-integration policy:

• The PR adds a new Codex-specific delegation backend directly under agent/ and changes tools/delegate_tool.py.
• Hermes' policy is that new third-party/vendor integrations should ship as standalone plugin repositories rather than expanding the core tree.
• Current main already has a maintained Codex app-server runtime (agent/transports/codex_app_server.py and agent/codex_runtime.py), so a standalone integration can build on the existing direction without introducing a parallel core client.

This is not a judgment on the quality of the work. Please consider publishing the delegation backend as a standalone plugin repo, which users can install into ~/.hermes/plugins/ and share through #plugins-skills-and-skins.

---

Closed as not-planned per standing maintainer policy (in-tree-provider-integration). This is a design-direction decision, not a code-quality judgment — see the Contribution Rubric in AGENTS.md for what the project is looking for. If you believe this policy was misapplied to your change, comment here and a maintainer will take a look.