Skip to content

ACP is the single rich adapter; Claude is driven through it, not a native SDK

All Tracing/Interaction-capable agents are driven through one ACP (Agent Client Protocol) adapter — a single Python ACP client plus a per-agent normalization table. This includes Claude (via the claude-agent-acp npm adapter), Codex, Gemini, Factory Droid, and devin-cli. We deliberately do not maintain a separate native Claude Agent SDK adapter in the core, even though one exists and would avoid a Node dependency for Claude.

We accept a Node dependency for the npm-distributed agent adapters (Claude, Codex, Gemini) in exchange for one event-translation path, one interaction-handling path, and one place to add agents. Native-binary ACP agents (Factory Droid, Goose) need no Node; droid is the primary build target for the adapter.

Status

superseded by ADR 0010

The "ACP is the single rich adapter" claim no longer holds: ADR 0006 added a native Claude stream-json rich path and ADR 0009 an in-process OpenAI rich path, so those native adapters now carry the rich load. ADR 0010 records the replacement — a shared rich-adapter substrate behind the Trace contract. ACP is preserved as a future adapter — the aspiration of unifying all clients under one contract — but it is partial and uneven across providers today (not every capability is reachable from every agent), so it is no longer the mandated rich path; the native adapters carry the load while it matures.

Considered options

  • Two rich adapters: native claude-agent-sdk for Claude + ACP for the rest. Max fidelity and no Node for Claude, but two code paths to maintain and two interaction models.
  • One ACP adapter for everything, Claude via claude-agent-acp (chosen). Uniform, smallest surface; costs a Node dependency for npm-based agents and slightly less direct access to Claude-specific fields than the native SDK.

Consequences

  • Node must be available to launch npm-distributed adapters (Claude, Codex, Gemini); droid, Goose, and devin-cli are native.
  • A future native Claude Agent SDK adapter may be added as an optional no-Node alternative without changing the Trace or Interaction contracts.
  • Model selection is applied per-Adapter; for ACP agents the model is set via the launch command and/or ACP session config, and a model is only valid for the agents that support it (the matrix pairs models per-Harness).