Current State
Three agent adapters exist (Codex, Claude Code, Cursor), all implementing the same AgentAdapter interface. However, capabilities are heavily skewed:
Codex (most mature):
- Per-stage model selection (
models.plan, models.implement, etc.)
- Per-stage reasoning effort (
reasoningEfforts.plan, etc.)
- Per-stage fast mode toggle
- Sandbox control, Docker support, plugins/skillsets
- Output file management, usage extraction
Claude Code / Cursor (minimal):
- All 5 adapter methods implemented, but each routes through the same code path
- No per-stage model or configuration differentiation
- Claude: global model, maxTurns, allowedTools, permissionMode
- Cursor: global model, force flag
Meanwhile, agent-registry.types.ts already defines AgentStage and AgentModelDefinition.defaultFor — suggesting per-stage config was anticipated but not yet adopted by Claude/Cursor adapters.
Proposal
Phase 1 — Per-stage model for all adapters (the quick win)
- Extend
AgentAdapterRuntimeConfig.agent with models?: Partial<Record<AgentStage, string>> (mirroring codex config shape)
- Claude Code: use per-stage model in
runPlan / runReview / runGithubComment / runTaskIntake
- Cursor: same
- Codex: no change (already has this)
Phase 2 — Optional capability declaration
- Add
capabilities to AgentBackendDefinition (e.g., perStageModel, perStageReasoning, sandbox, docker, sessionResume, usageExtraction)
- Workflow layer can check capabilities before attempting adapter-specific features
- Adapters declare what they support; callers degrade gracefully
Phase 3 — Per-stage reasoning/effort for applicable adapters
- Extend the per-stage config to include reasoning effort where the underlying agent supports it
- Codex: already done, just needs to read from the unified config shape
- Claude: no equivalent (model choice is the tuning knob)
Benefits
- Claude Code and Cursor users get the same per-stage model flexibility as Codex
- New adapters have a clear capability contract to implement against
- Reduces the config shape divergence between adapter-specific sections (
codex.* vs agent.* vs cursor.*)
Notes
- This should be non-breaking — existing single-model configs continue to work as fallback
- The
AgentAdapter interface itself doesn't need to change (capabilities are metadata, not methods)
Current State
Three agent adapters exist (Codex, Claude Code, Cursor), all implementing the same
AgentAdapterinterface. However, capabilities are heavily skewed:Codex (most mature):
models.plan,models.implement, etc.)reasoningEfforts.plan, etc.)Claude Code / Cursor (minimal):
Meanwhile,
agent-registry.types.tsalready definesAgentStageandAgentModelDefinition.defaultFor— suggesting per-stage config was anticipated but not yet adopted by Claude/Cursor adapters.Proposal
Phase 1 — Per-stage model for all adapters (the quick win)
AgentAdapterRuntimeConfig.agentwithmodels?: Partial<Record<AgentStage, string>>(mirroring codex config shape)runPlan/runReview/runGithubComment/runTaskIntakePhase 2 — Optional capability declaration
capabilitiestoAgentBackendDefinition(e.g.,perStageModel,perStageReasoning,sandbox,docker,sessionResume,usageExtraction)Phase 3 — Per-stage reasoning/effort for applicable adapters
Benefits
codex.*vsagent.*vscursor.*)Notes
AgentAdapterinterface itself doesn't need to change (capabilities are metadata, not methods)