Wrap an ACP Server

chio sits between an editor or IDE and an ACP coding agent the same way it sits between an agent and an MCP tool server. The agent runs unmodified as a subprocess, chio intercepts every JSON-RPC message flowing in either direction, and policy-critical methods are guarded before they reach the agent or the filesystem. This guide walks through the full lifecycle: picking an upstream ACP agent, writing a policy that matches ACP's message surface, running the adapter, and reading the audit log.

Why Wrap ACP

ACP is the Agent Client Protocol used by coding agents and IDE sidecars: editors talk to agents over JSON-RPC 2.0 on stdio, and the agent exposes methods like session/prompt, session/request_permission, fs/read_text_file, fs/write_text_file, and terminal/create. It is a message-based protocol, not a tool-call-based one. The agent drives the session and emits session/update notifications that carry tool-call events as they happen.

That shape matters for governance. With MCP, chio intercepts a symmetric request-response pair for every tool use. With ACP, chio intercepts ongoing bidirectional traffic and promotes the observed tool-call events inside session updates into audit entries. Wrapping an ACP agent with chio gives you:

• A boundary for the IDE to trust. The editor still speaks ACP. The agent still speaks ACP. chio is transparent on the wire.
• Filesystem and terminal guards that apply to fs/read_text_file, fs/write_text_file, and terminal/create before the agent sees them.
• An audit trail of tool-call events observed in session updates, each with a SHA-256 content hash and the session, tool-call, and server identifiers already filled in.
• A promotion path to signed receipts so unsigned ACP audit entries can be cross-linked with MCP and A2A receipts in a single compliance query.

What You Need

Three things, mirroring the MCP flow:

1. An upstream ACP agent. Any agent that implements ACP over stdio JSON-RPC works. Examples below use a Claude-style coding agent binary invoked as claude-code, but the adapter is agent-agnostic: the proxy spawns whatever command you give it and pipes JSON-RPC through.
2. A policy file describing which paths the agent can read or write, which shell commands it can launch through ACP's terminal surface, and which tool-call kinds are allowed.
3. A signing seed if you want the ACP audit entries promoted into signed chio receipts. Without a seed the proxy still enforces guards and produces unsigned audit entries. With a seed the adapter runs in attestation-required mode and emits full receipts or an explicit attestation-gap artifact.

The Wrap Command

The canonical invocation mirrors chio mcp serve:

$ chio acp serve --policy <file> --server-id <id> --preset code-agent \
    -- <upstream-command> [args...]

Each flag does the same job it does for MCP, with one ACP-specific detail: the --server-id is baked into every audit entry and receipt as the server_id field, and ACP session compliance certificates use the acp-session:{session_id} capability-ID prefix to scope evidence to a single session.

A concrete invocation against a coding agent with a project-scoped path allowlist and a short command allowlist:

$ chio acp serve --policy ./acp-codeagent.yaml --server-id srv-coder \
    --preset code-agent \
    --allow-path /home/dev/project \
    --allow-command cargo \
    --allow-command git \
    --seed ./kernel.seed \
    -- claude-code --stdio

The proxy spawns the agent, wires stdio, and begins interposing on JSON-RPC traffic:

INFO loaded policy for ACP edge
  policy_path: ./acp-codeagent.yaml
  server_id:   srv-coder
  guards:      fs-guard, terminal-guard, permission-guard, tool-access

INFO spawning ACP agent
  command:    claude-code --stdio
  transport:  json-rpc/stdio
  paths:      /home/dev/project
  commands:   cargo, git

INFO attestation mode: required
  signer:     kernel-ed25519 (seed loaded)

INFO chio ACP edge ready
  intercepting session/*, fs/*, terminal/*

How ACP Flows Through Chio

The proxy treats the wire as a symmetric JSON-RPC stream. The editor writes requests and notifications into chio; chio reads each one, routes it by method, and decides whether to forward, block, or forward-with-attestation. Agent-to-editor messages are handled the same way in reverse.

Method by method, here is what the interceptor does. Names match the AcpMethod discriminator the proxy parses from every request.

Guard failures are returned as JSON-RPC errors on the original request id, using the server error code -32000 with a message that names the guard. The editor surfaces those as ordinary tool errors, so no client-side changes are required.

Policy Shape for ACP

The policy below is a sibling of the MCP filesystem policy. The guard names are the same. The differences are ACP-specific: tool access is stated in terms of ACP method and tool-call kind rather than flat MCP tool names, and terminal commands are modeled as first-class allowlist entries because terminal/create is a dedicated ACP method.

hushspec: "0.1.0"
name: acp-codeagent

rules:
  # ACP method + tool-call kind access. The proxy reads both the
  # method name and, for session/update events, the reported kind.
  tool_access:
    enabled: true
    default: block
    allow_methods:
      - session/new
      - session/prompt
      - session/update
      - session/request_permission
      - fs/read_text_file
      - fs/write_text_file
      - terminal/create
      - terminal/kill
      - terminal/output
      - terminal/wait_for_exit
    allow_kinds:
      - read
      - edit
      - execute

  # Path allowlist is enforced by FsGuard for both fs/* methods.
  path_allowlist:
    enabled: true
    read:
      - "/home/dev/project/**"
    write:
      - "/home/dev/project/src/**"
      - "/home/dev/project/tests/**"
    patch: []

  forbidden_paths:
    enabled: true
    patterns:
      - "**/.env"
      - "**/.env.*"
      - "**/*.pem"
      - "**/*.key"
      - "**/.ssh/**"
      - "**/.git/config"
    exceptions: []

  # TerminalGuard: only allow explicitly listed commands.
  shell_commands:
    enabled: true
    allow:
      - cargo
      - git
      - rg
    forbidden_patterns:
      - "(?i)\\bsudo\\b"
      - "(?i)\\bcurl\\b.*\\b(sh|bash|zsh)\\b"

  # Scan prompts, tool-call params, and tool results.
  secret_patterns:
    enabled: true

  # Velocity window sized for an interactive IDE session.
  velocity:
    enabled: true
    max_invocations: 600
    window_seconds: 300

Two ACP-specific policy patterns are worth calling out:

• Split read vs write paths. ACP coding agents typically need a wide read surface and a narrow write surface. Put the whole project under path_allowlist.read, but restrict path_allowlist.write to source and test directories. The FsGuard enforces the split per method.
• Deny-by-default terminal with a short allow list. ACP agents love to shell out. Set shell_commands.allow to the minimum set (build, test, and VCS), and use forbidden_patterns to stop pipe-to-shell tricks from making it through.

For the full policy grammar and how to test each guard offline with chio check, see Write a Policy.

Receipts for ACP Messages

Every session/update notification that carries a tool-call event produces an audit entry. The entry records the tool-call id, title, kind, status, session id, server id, a Unix timestamp, and a SHA-256 hex digest of the canonical JSON of the originating event. When a signing seed is loaded, the entry is also promoted into a chio receipt signed with the kernel's Ed25519 key.

The audit-entry shape the proxy emits before signing looks like this:

{
  "toolCallId": "tc_01HZ7Q8YB3N8G0XHB0T6KQ4F9R",
  "title": "edit src/main.rs",
  "kind": "edit",
  "status": "completed",
  "sessionId": "sess_01HZ7Q8YB3N8G0XHB0T6KQ4F9R",
  "timestamp": "1744993921",
  "serverId": "srv-coder",
  "contentHash": "8f3b2a4e9c1d0f7b6a5e2c3d4f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a",
  "capabilityId": "acp-session:sess_01HZ7Q8YB3N8G0XHB0T6KQ4F9R",
  "authorizationReceiptId": "rcpt-acp-01HZ7Q8YB3N8G0XHB0T6KQ4F9R",
  "enforcementMode": "cryptographically_enforced"
}

A few fields are ACP-specific:

• toolCallId is the ACP protocol's own stable id for the event. It is stable acrossToolCall and its subsequent ToolCallUpdate status transitions, so you can fold related entries together downstream.
• capabilityId takes the form acp-session:<session_id>. The chio cert acp command uses that prefix to pull every receipt that belongs to one session.
• enforcementMode is cryptographically_enforced when a live capability check allowed the underlying operation before the event was forwarded, or audit_only when the proxy merely observed the event.

When the kernel-backed signer is active, the audit entry is wrapped into a ChioReceipt with metadata.protocol = "acp" and metadata.session_id set, so it lands in the same receipt store as MCP and A2A receipts. For the full receipt format, verification procedure, and the attestation-gap shape that appears when signing cannot complete, see Receipts.

Tail the audit log for a running session:

$ chio receipt list --tool-server srv-coder --protocol acp

RECEIPT LOG (4 entries)

#1  2026-04-18T14:11:03Z  ALLOW  fs/read_text_file
    session:     sess_01HZ7Q8YB...
    tool_call:   tc_01HZ7Q8YB...
    enforcement: cryptographically_enforced
    signature:   ed25519:a3b4c5d6...

#2  2026-04-18T14:11:05Z  ALLOW  fs/write_text_file
    session:     sess_01HZ7Q8YB...
    path:        /home/dev/project/src/main.rs
    signature:   ed25519:e7f8a9b0...

#3  2026-04-18T14:11:09Z  DENY   terminal/create
    session:     sess_01HZ7Q8YB...
    guard:       terminal-guard
    reason:      command 'rm' not in allow list
    signature:   ed25519:c1d2e3f4...

#4  2026-04-18T14:11:12Z  ALLOW  session/update (tool_call: edit)
    session:     sess_01HZ7Q8YB...
    content:     8f3b2a4e9c1d0f7b...
    signature:   ed25519:d9e0f1a2...

4 entries, 3 allowed, 1 denied

Differences from the MCP Adapter

At a glance:

The practical upshot: MCP guards are evaluated at decision time, so every allow or deny is signed in line with the tool call. ACP guards are evaluated at decision time too, but the richest signal comes after the fact from session/update events. An ACP session produces a fan of receipts tied together by session_id, which is why ACP compliance certificates are session-scoped.

Troubleshooting

Common failure modes and how to read them from the proxy log.

Summary

Wrapping an ACP agent with chio gives you:

Next Steps

• Wrap an MCP Server · the sibling guide for tool-call-based servers. Worth reading back-to-back with this one.
• Write a Policy · full HushSpec reference for the guards mentioned above.
• Receipts · receipt format, verification, and the attestation-gap states ACP introduces.
• Native Tool Server · when you want the agent to speak chio directly instead of sitting behind an ACP adapter.