Skip to content

Refactor: unify agent adapter capabilities with per-stage configuration #197

@zhangweijian97

Description

@zhangweijian97

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)

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions