feat: Native ACP (Agent Client Protocol) provider for multi-agent orchestration

[mrgoonie]

Summary

Implement a native Go ACP client provider (ACPProvider) that enables GoClaw to orchestrate any ACP-compatible coding agent (Claude Code, Codex CLI, Gemini CLI, Cursor, Kiro, etc.) as a subprocess via JSON-RPC 2.0 over stdio.

Motivation

• ClaudeCLIProvider exists but is Claude-specific — parsing stdout events from the claude binary
• Agent Client Protocol (ACP) standardizes editor↔agent communication, supported by 14+ agents
• One provider implementation covers all ACP agents through config-driven agent registry
• Enables multi-agent orchestration: delegate coding subtasks to specialized agents

Proposed Architecture

GoClaw Agent Loop
  └─ ACPProvider (new)
       ├─ ProcessPool (sessionKey → subprocess)
       ├─ JSON-RPC 2.0 Conn (bidirectional over stdio)
       ├─ ACP Session lifecycle (initialize → session/new → session/prompt)
       └─ Tool Bridge (agent→client requests)
            fs/readTextFile  → GoClaw workspace (sandboxed)
            fs/writeTextFile → GoClaw workspace (sandboxed)
            terminal/create  → exec with deny patterns
            permission/req   → auto-approve (configurable)

Implementation Plan

6 phases, ~16h estimated:

Phase	Description
1	ACP protocol types + JSON-RPC 2.0 transport (internal/providers/acp/)
2	Subprocess management + ACP session lifecycle (spawn, idle TTL, crash recovery)
3	ACPProvider implementing providers.Provider (Chat/ChatStream)
4	Tool bridge — handle agent fs/terminal/permission requests with security sandboxing
5	Config struct, DB provider type, gateway wiring (both config-based and DB-based)
6	Integration tests with mock ACP agent binary

Detailed plan: plans/260314-1239-acp-provider-integration/

Key Decisions

• Direction: GoClaw as ACP Client (not server)
• Transport: JSON-RPC 2.0 over stdio (agents as subprocesses)
• Implementation: Native Go — no external dependencies, no ACPX/Node.js required
• Scope: Generic — works with any ACP-compatible agent binary

New Files

internal/providers/acp/
├── types.go           # ACP protocol types
├── jsonrpc.go         # Bidirectional JSON-RPC 2.0
├── process.go         # Subprocess pool
├── session.go         # ACP session methods
├── tool_bridge.go     # Agent→client request handler
└── terminal.go        # Terminal registry

internal/providers/acp_provider.go   # Provider interface implementation
tests/integration/acp/               # Integration tests with mock agent

Security

• Workspace sandboxing: path traversal prevention on fs requests
• Shell deny patterns enforced on terminal/create
• Env filtering: strip GoClaw secrets from subprocess environment
• Permission model: configurable (approve-all / approve-reads / deny-all)

References

• ACP Spec
• ACP Schema
• ACPX CLI (reference client, TypeScript)
• OpenClaw (validates ACP in production)

[mrgoonie]

Architecture Diagrams

System Overview

graph TB
    subgraph GoClaw["GoClaw Gateway"]
        AL[Agent Loop] -->|ChatStream| ACP[ACPProvider]
        ACP --> PP[ProcessPool]
        PP -->|spawn/reuse| P1[ACPProcess 1<br/>sessionKey: user-123]
        PP -->|spawn/reuse| P2[ACPProcess 2<br/>sessionKey: user-456]
        ACP --> TB[ToolBridge]
    end

    subgraph Agents["ACP Agent Subprocesses"]
        P1 -->|stdio JSON-RPC| A1[claude-code]
        P2 -->|stdio JSON-RPC| A2[codex-cli]
    end

    A1 -->|fs/readTextFile| TB
    A1 -->|terminal/create| TB
    A2 -->|fs/writeTextFile| TB
    TB -->|sandboxed| WS[(Workspace<br/>Files)]

    style GoClaw fill:#1a1a2e,color:#fff
    style Agents fill:#16213e,color:#fff

Loading

ACP Session Lifecycle

sequenceDiagram
    participant AgentLoop as Agent Loop
    participant ACP as ACPProvider
    participant Pool as ProcessPool
    participant Proc as Subprocess
    participant Bridge as ToolBridge

    AgentLoop->>ACP: ChatStream req
    ACP->>Pool: GetOrSpawn sessionKey

    alt New session
        Pool->>Proc: exec.Command binary + stdio pipes
        Pool->>Proc: initialize capabilities
        Proc-->>Pool: AgentCaps
        Pool->>Proc: session/new
        Proc-->>Pool: sessionID
    end

    ACP->>Proc: session/prompt user message

    Note over Proc,Bridge: Agent works autonomously

    Proc-->>ACP: session/update text chunk 1
    ACP-->>AgentLoop: onChunk StreamChunk

    Proc->>Bridge: fs/readTextFile
    Bridge->>Bridge: validate path in workspace
    Bridge-->>Proc: file content

    Proc-->>ACP: session/update text chunk 2
    ACP-->>AgentLoop: onChunk StreamChunk

    Proc->>Bridge: terminal/create command
    Bridge->>Bridge: check deny patterns
    Bridge-->>Proc: terminalID
    Proc->>Bridge: terminal/output
    Bridge-->>Proc: stdout + exitStatus
    Proc->>Bridge: terminal/release

    Proc-->>ACP: session/update text chunk 3
    ACP-->>AgentLoop: onChunk StreamChunk

    Proc-->>ACP: PromptResponse stopReason endTurn
    ACP-->>AgentLoop: Done + ChatResponse

Loading

Process Lifecycle and Idle TTL

stateDiagram-v2
    [*] --> Spawning: GetOrSpawn
    Spawning --> Initializing: exec.Command + stdio
    Initializing --> Ready: initialize + session/new OK
    Ready --> Active: session/prompt
    Active --> Ready: response received
    Ready --> Idle: no prompts
    Idle --> Reaped: idleTTL expired
    Reaped --> [*]
    Active --> Crashed: process exit unexpected
    Crashed --> Spawning: next GetOrSpawn
    Active --> Cancelling: ctx.Done
    Cancelling --> Ready: session/cancel sent

Loading

JSON-RPC Bidirectional Flow

graph LR
    subgraph Client["GoClaw Client"]
        C1[Conn.Call] -->|request| STDIN
        STDOUT -->|response| C1
        STDOUT -->|notification| NH[NotifyHandler]
        STDOUT -->|agent request| RH[RequestHandler]
        RH -->|response| STDIN
    end

    subgraph Agent["ACP Agent Server"]
        STDIN -->|stdin| AP[Agent Process]
        AP -->|stdout| STDOUT
    end

    style Client fill:#0f3460,color:#fff
    style Agent fill:#533483,color:#fff

Loading