feat: multi-agent support — strategic gap exposed by OpenACP (28+ agents) and cc-connect (10+ agents)

[OneStepAt4time]

Current state (2026-07-09)

• ✅ feat: Agent Profiles — first-class agents with names, configs, skills, and model routing #3971 (Agent Profiles) — shipped 2026-05-30, included in v0.6.7. Not a blocker.
• ✅ docs(adr): ADR-0034 multi-CLI runtime, supersede ADR-0023 #4842 (ADR-0034) — merged 2026-07-07. Ratifies ADR-0032, repeals the "Never: competing CLIs" rule of ADR-0023. Aegis becomes the control plane for ACP-compatible coding-agent CLIs.
• ✅ refactor(acp): AcpRunnerProfile foundation for multi-CLI (Phase 3.6 M1) #4843 (AcpRunnerProfile foundation) — merged 2026-07-09. Phase 3.6 M1. AcpRunnerProfile abstraction + ClaudeCodeProfile (default) + KimiProfile (MIT, ACP-native) in code. Zero behavior change yet — not wired.
• 🚧 Phase 3.6 active — multi-CLI architecture is now approved and the foundation code is merged. Next: wire runnerName through SessionInfo → ACP session → factory context, make createDefaultAcpBackendClient profile-aware, gate applyPermissionModeArgs on strategy, parameterise auth env prefixes.
• Blocker: None at architecture level. Implementation is gated on follow-up PRs (not filed yet). Ema's architecture approval is resolved.

Strategic Gap

Competitive research (#3003, #3004, #3016) identified multi-agent support as a critical differentiator gap:

• OpenACP supports 28+ AI agent backends
• cc-connect supports 10+ agents across 11 chat platforms
• Aegis currently supports Claude Code only

Why This Matters

Agent breadth is the #1 feature driving competitor adoption. Users want to orchestrate multiple AI tools, not just one.

Scope

• Define agent abstraction layer (AcpRunnerProfile — DONE in refactor(acp): AcpRunnerProfile foundation for multi-CLI (Phase 3.6 M1) #4843)
• Support at minimum: Claude Code (default), Kimi Code (native ACP), Gemini CLI (ACP-compatible)
• Maintain Aegis middleware positioning — orchestration, not agent logic
• Phase 3.6 scope — follow-up PRs to wire the profile into the spawn path

Competitive Intel

• research: OpenACP is the most dangerous competitor (ACP-native bridge, 346 ⭐, fast growth) #3003 — OpenACP analysis
• research: cc-connect v1.3.3-beta adds features overlapping Aegis (custom prompts, lifecycle hooks, web UI) #3004 — cc-connect analysis
• research: full competitive landscape — 8 orchestration competitors ranked by threat level #3016 — full competitive landscape

Next steps

1. Follow-up PR: wire runnerName through SessionInfo → ACP session → factory context
2. Follow-up PR: make createDefaultAcpBackendClient profile-aware
3. Follow-up PR: gate applyPermissionModeArgs on runner strategy
4. Follow-up PR: parameterise auth env prefixes per runner

Do not start these until Hephaestus has capacity (he's on Phase 3.6 per current sprint).

[OneStepAt4time]

Multi-Agent Support — Architecture Spec (Draft)

Author: Scribe | Date: 2026-05-11 | Status: Draft for Ema's review

---

TL;DR

Aegis already has the right abstraction (AcpBackendClient). Multi-agent support = multiple backend implementations, not a rewrite. Minimum viable: Claude Code (current) + Codex CLI + Gemini CLI.

---

Current Architecture

Session → AcpBackendClient → AcpChildProcess → claude-agent-acp (JSON-RPC over stdio)

The AcpBackendClient interface is already backend-agnostic — it's a JSON-RPC client over stdio. The AcpChildProcess spawns and supervises the binary. This maps cleanly to multiple agents.

Proposed Architecture

Session → AcpBackendClient → AcpChildProcess → Agent Binary
                                                    ├── claude-agent-acp (Claude Code)
                                                    ├── codex (Codex CLI)
                                                    └── gemini (Gemini CLI)

Key insight: No architecture change needed. Just add agent binary resolution + per-agent config.

Implementation Plan

Phase 1: Binary Resolution (2-3 days)

Add an agent field to session creation:

POST /v1/sessions
{
  "prompt": "review this code",
  "workDir": "/home/user/project",
  "agent": "codex"
}

Binary resolution:

• agent: "claude" → claude-agent-acp (current default)
• agent: "codex" → codex (Codex CLI, already ACP-compatible)
• agent: "gemini" → gemini (Gemini CLI, already ACP-compatible)

Config override:

{
  "agents": {
    "claude": { "bin": "claude-agent-acp", "args": [] },
    "codex": { "bin": "codex", "args": [] },
    "gemini": { "bin": "gemini", "args": [] }
  }
}

Phase 2: Per-Agent Environment (1-2 days)

Each agent needs different env vars:

• Claude: ANTHROPIC_API_KEY
• Codex: OPENAI_API_KEY
• Gemini: GEMINI_API_KEY or GOOGLE_API_KEY

Add agentEnv to config:

{
  "agents": {
    "codex": { "env": { "OPENAI_API_KEY": "..." } }
  }
}

Phase 3: Dashboard Agent Column (1-2 days)

• Add agent column to SessionTable
• Add agent filter to session list
• Show agent icon/badge per session

Phase 4: Smart Routing (Future)

• Route tasks to cheapest/fastest agent
• Use Claude for reasoning, Codex for code generation, Gemini for large context
• User-configurable routing rules

What ACP Already Handles

The ACP protocol is agent-agnostic by design:

• ✅ JSON-RPC over stdio — works with any ACP-compatible binary
• ✅ Session lifecycle (create, pause, resume, kill) — same for all agents
• ✅ Event streaming (notifications, responses) — same protocol
• ✅ Permission requests — same flow
• ✅ Tool calls — same schema

The heavy lifting is already done. Multi-agent is a configuration problem, not an architecture problem.

Competitive Positioning

Dimension	OpenACP	cc-connect	Aegis (proposed)
Agent count	28+	10+	3 (Claude, Codex, Gemini)
Install complexity	curl | bash	Binary download	npm + ag run
Enterprise auth	❌	❌	✅ OIDC/RBAC
Audit trail	❌	❌	✅ Hash chain
API-first	✅	❌	✅ REST + MCP
Dashboard	❌	✅ basic	✅ Full React
K8s deployment	❌	❌	✅ Helm

We don't need 28 agents. 3 agents with enterprise governance beats 28 agents without it.

Open Questions for Ema

1. Which agents first? Codex and Gemini are the obvious choices (ACP-compatible). Any others?
2. Default agent? Should claude remain the default when no agent field is specified?
3. Phase 4 activation? This spec is ready to implement. Does Ema want to activate Phase 4 early for this, or wait?
4. Smart routing? Should Phase 4 include cost-aware routing (route simple tasks to cheaper agents)?

Effort Estimate

Phase	Effort	Risk
Phase 1: Binary resolution	2-3 days	Low — ACP already handles it
Phase 2: Per-agent env	1-2 days	Low — config extension
Phase 3: Dashboard	1-2 days	Low — UI column
Total MVP	4-7 days	Low

---

This spec is based on competitive research from #3013 (Ruflo), #3014 (OMC), #3016 (landscape), #3003 (OpenACP), #3004 (cc-connect). Full analysis in docs/competitive-threat-matrix.md.

[OneStepAt4time]

Multi-Agent Gap Analysis — Hephaestus 🔨

Current Aegis Architecture (Claude Code Only)

Aegis is hard-coupled to a single agent backend:

• binary-resolver.ts: Resolves @agentclientprotocol/claude-agent-acp binary exclusively
• child-process.ts: Spawns ACP child process via node:child_process
• backend.ts: ACP JSON-RPC client (AcpBackendClient) — protocol is ACP-specific
• session.ts: Session lifecycle tied to CC UI states (idle, working, permission_prompt, etc.)
• session-service.ts: CRUD sessions bound to ACP protocol

The entire src/services/acp/ directory is Claude-Code-via-ACP. There is no abstraction layer, no Runner interface, no pluggable backend system.

What Multi-Agent Would Require

1. Runner Interface (abstraction layer)

interface AgentRunner {
  name: string;              // "claude-code", "codex", "gemini-cli"
  start(options: RunnerStartOptions): Promise<RunnerSession>;
  send(sessionId: string, message: string): Promise<void>;
  getStatus(sessionId: string): RunnerStatus;
  shutdown(sessionId: string, options?: ShutdownOptions): Promise<void>;
  onEvent(sessionId: string, handler: (event: RunnerEvent) => void): () => void;
}

This is the critical abstraction. Everything above it (REST API, MCP server, dashboard, events) stays the same. Everything below it (process management, protocol, binary resolution) becomes per-runner.

2. Runner Registry

const runners: Map<string, AgentRunner> = new Map();
runners.set("claude-code", new ClaudeCodeRunner());   // current ACP
runners.set("codex", new CodexRunner());               // new
runners.set("gemini-cli", new GeminiCliRunner());      // new

Config would specify which runners are available/enabled.

3. Protocol Adapters

• Claude Code: ACP JSON-RPC (current — keep as-is)
• Codex: Uses its own CLI protocol. Would need a Codex adapter.
• Gemini CLI: Similar CLI protocol. Adapter needed.
• Cursor: Desktop app, not CLI — different integration path (MCP? API?)

4. Session Router

The session creation endpoint would gain a runner parameter:

POST /v1/sessions { "runner": "codex", "prompt": "..." }

Default runner = "claude-code" for backward compatibility.

Competitive Analysis

Feature	Aegis	OpenACP	cc-connect	ruflo
Agent count	1	28+	10+	98
Runner abstraction	None	Agent adapters	Agent adapters	Agent adapters
Protocol	ACP only	ACP + native	Native per-agent	Native per-agent
Multi-agent in one session	No	Yes	Yes (relay)	Yes (swarm)

Effort Estimate (Research Phase)

Phase	Scope	Effort
Phase A: Runner interface design	TypeScript interface + registry	1-2 days
Phase B: Claude Code runner (extract current ACP code)	Refactor existing code behind interface	3-5 days
Phase C: Codex runner	New adapter	3-5 days
Phase D: Gemini CLI runner	New adapter	2-3 days
Phase E: Config + API surface	Runner selection, validation, docs	1-2 days

Total: ~10-17 days for 3-agent MVP (Claude Code + Codex + Gemini CLI)

Risks

1. Protocol stability: Codex/Gemini CLI protocols are not standardized. Changes break adapters.
2. Process management differences: Each agent has different lifecycle, exit behavior, signal handling.
3. Test matrix explosion: Every feature must be tested across N runners.
4. Security surface: More binaries = more attack surface. Each runner needs its own permission model.

Recommendation

Phase 4 scope, but Phase 3 prep is valid now:

1. Now (Phase 3): Design the Runner interface as an ADR. No implementation. This gives us the architectural target.
2. Phase 4: Implement Runner interface, extract Claude Code as first runner, add Codex as second.
3. Don't chase 28+ agents — ruflo has 98 and it's a maintaining nightmare. Target 3-5 well-supported runners.

ADR Proposal

I can draft ADR-0024: Agent Runner Interface — defining the abstraction layer, registry, and migration path from the current hardcoded ACP backend. This would be a design document, not code.

Decision needed from Ema: Approve ADR drafting? If yes, I'll write it as part of this research issue.

Refs: #3003 (OpenACP), #3004 (cc-connect), #3016 (competitive landscape), #3049 (ACP agent mode)