Adopt ACP as primary agent interface — shrink adapter surface (ADR-001)

[c-h-]

Summary

Per ADR-001 (filed in Obsidian, to be committed to repo), agentctl should adopt ACP as its primary agent interface strategy.

Background

ACPx provides a mature headless ACP client runtime with persistent sessions, cooperative cancel, fs/terminal callbacks, and a growing registry of ACP bridges for Claude Code, Codex, OpenCode, Pi, and more.

Today agentctl maintains 5+ bespoke adapters (~500-800 LOC each) that independently handle launch, resume, PTY management, output parsing, and lifecycle detection. This is the same problem ACP solves at the protocol level.

Proposed Changes

Phase 1: ACP-first for one adapter (proof of concept)

• Pick one adapter (recommend: Codex — simplest, good ACP bridge exists)
• Replace PTY launch/resume/output with ACPx or embedded ACP client
• Validate that daemon supervision, locks, metrics, and hooks still work over ACP sessions
• Benchmark: adapter LOC before vs after

Phase 2: Migrate remaining adapters

• Claude Code adapter → ACP (via @zed-industries/claude-agent-acp)
• OpenCode adapter → ACP (via opencode-ai acp)
• Pi / Pi Rust adapters → ACP (build or find bridges)
• Deprecate and remove PTY-scraping codepaths

Phase 3: Thin adapter model

• Adapters become config-only (ACP command, permission policy, agentctl-specific hooks)
• New runtime support = add ACP bridge reference to registry, done
• Document the new adapter contract

Phase 4: Upstream contributions

• Identify missing ACP capabilities needed by agentctl (webhooks on completion, fleet discovery)
• Contribute to ACPx or ACP spec where it benefits the ecosystem
• Consider releasing any new ACP bridges as standalone packages

What stays unchanged

• Daemon supervision architecture
• Fleet discovery (agentctl list)
• Worktree management and sweeps
• Directory locks and fuses
• Prometheus metrics
• Webhook/callback hooks
• OrgLoop integration
• CLI UX

ADR

Full ADR with rationale, consequences, and risk analysis: ADR-001 in Obsidian

Related

• ACPx analysis: acpx-vs-agentctl
• ACPx repo: https://github.com/openclaw/acpx