Wrap an ACP Server

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.

ACP changes where Chio can observe actions. 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:

• Transparent ACP proxying. 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

You need three things:

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. Guard allowlists: the set of filesystem path prefixes the agent may read or write, and the terminal commands it may launch through ACP's terminal interface. These are plain string lists you set on AcpProxyConfig, not a policy document.
3. A kernel signer and capability checker, optionally. Pass a ReceiptSigner and a CapabilityChecker to start_with_kernel to promote ACP audit entries into signed Chio receipts and to gate terminal lifecycle calls. Without them, AcpProxy::start still enforces the built-in guards and produces unsigned audit entries.

Embed the Proxy

You wrap an ACP agent from Rust. Add the crate, build an AcpProxyConfig, and start an AcpProxy. The two required inputs are the agent command and the public key used to verify receipts. Builder methods add the path prefixes and commands the agent may use; with_allowed_path_prefix and with_allowed_command are both repeatable.

[dependencies]
chio-acp-proxy = "0.1"
anyhow = "1"

use chio_acp_proxy::{AcpProxy, AcpProxyConfig};

fn main() -> anyhow::Result<()> {
    // AcpProxyConfig::new(agent_command, public_key). All guard lists
    // start empty (deny-all); each builder call widens one of them.
    let config = AcpProxyConfig::new("claude-code", server_public_key_hex())
        .with_agent_args(vec!["--stdio".into()])
        .with_server_id("srv-coder")
        // Filesystem prefixes the agent may read or write (FsGuard).
        .with_allowed_path_prefix("/home/dev/project")
        // Terminal commands the agent may launch (TerminalGuard).
        .with_allowed_command("cargo")
        .with_allowed_command("git");

    // Standalone: built-in FsGuard + TerminalGuard only. No signer, no
    // capability checker -- audit entries are unsigned, and terminal
    // lifecycle calls (terminal/kill, terminal/release) are denied outright.
    let proxy = AcpProxy::start(config)?;
    run_stdio_loop(proxy)
}

For signed receipts and live capability checks, start the proxy with a kernel-backed ReceiptSigner and CapabilityChecker. The crate ships KernelReceiptSigner and KernelCapabilityChecker for this. The third argument sets the attestation mode: BestEffort (the default) logs signing failures but lets operations proceed; Required fails a call closed if its receipt cannot be signed.

use chio_acp_proxy::{AcpAttestationMode, AcpProxy};

// signer: impl ReceiptSigner, checker: impl CapabilityChecker -- both
// backed by your kernel (KernelReceiptSigner / KernelCapabilityChecker).
let proxy = AcpProxy::start_with_kernel(
    config,
    Some(Box::new(signer)),        // promote audit entries into signed receipts
    Some(Box::new(checker)),       // gate terminal lifecycle + capability checks
    AcpAttestationMode::Required,  // signing failures fail closed
)?;

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.

Configuring the Guards

The proxy has two built-in guards. Both are constructed directly from the plain allowlists on AcpProxyConfig; there is no policy document and no glob or regex grammar to learn.

• FsGuard — path prefixes from with_allowed_path_prefix, enforced on fs/read_text_file and fs/write_text_file. It is fail-closed: the path must be absolute and fall under an allowed prefix, an empty prefix set denies everything, and .. traversal or symlinks escaping the allowed tree are rejected before the prefix check. Prefix matches land on path boundaries, so /home/dev/project never matches /home/dev/project_evil.
• TerminalGuard — command allowlist from with_allowed_command, enforced on terminal/create. Also fail-closed: the command must be an exact match in the list, and arguments carrying shell-injection metacharacters (backtick, $(), |, ;, newlines) are rejected as defense-in-depth.

let config = AcpProxyConfig::new("claude-code", public_key)
    .with_agent_args(vec!["--stdio".into()])
    .with_server_id("srv-coder")
    // FsGuard prefix set. One list covers both reads and writes, so scope
    // it to what the agent may WRITE, not just what it may read.
    .with_allowed_path_prefix("/home/dev/project")
    // TerminalGuard allowlist. Build, test, and VCS only -- everything
    // else denies at terminal/create.
    .with_allowed_command("cargo")
    .with_allowed_command("git")
    .with_allowed_command("rg");

Two patterns are worth calling out. Keep the prefix set as narrow as the workflow allows. Because reads and writes share it, a wide prefix grants broad write access. Keep with_allowed_command to the minimum set an agent needs; the metacharacter check catches pipe-to-shell tricks smuggled through arguments. The allowlist defines the command boundary.

Neither built-in guard covers process lifecycle. To govern terminal/kill and terminal/release, install a CapabilityChecker through start_with_kernel; without one they are denied outright.

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 kernel-backed ReceiptSigner is installed, 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> when the entry carries no more specific capability id. chio cert generate --session-id matches on 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 whose ACP fields nest under metadata.acp (sessionId, toolCallId, capabilityId, enforcementMode, and the authorization-linkage fields), with the capability id defaulting to acp-session:<session_id>. An audit_only entry signs as a trace/observation receipt; a cryptographically_enforced one carries a mediated allow decision. Either way it lands in the same receipt store as MCP and A2A receipts. For the full receipt format and verification procedure, see Receipts.

List the receipts captured for a session with chio receipt list. There is no --protocol flag; scope the read to the ACP server with --tool-server. A local --receipt-db read fails closed unless you pass exactly one of --tenant <id> or --admin-all.

$ chio --receipt-db ./receipts.sqlite receipt list \
    --tool-server srv-coder --admin-all

{"id":"rcpt-acp-01HZ7Q8YB...","timestamp":1744993863,"capability_id":"acp-session:sess_01HZ7Q8YB...","tool_server":"srv-coder","tool_name":"fs/read_text_file","action":{"parameters":{"path":"/home/dev/project/src/main.rs"},"parameter_hash":"a3c8a200..."},"decision":{"verdict":"allow"},"content_hash":"8f3b2a4e...","policy_hash":"...","metadata":{"acp":{"sessionId":"sess_01HZ7Q8YB...","toolCallId":"tc_01HZ7Q8YB...","enforcementMode":"cryptographically_enforced"}},"kernel_key":"25403c1e...","signature":"a3b4c5d6..."}
{"id":"rcpt-acp-01HZ7Q8YC...","timestamp":1744993865,"capability_id":"acp-session:sess_01HZ7Q8YB...","tool_server":"srv-coder","tool_name":"fs/write_text_file","action":{"parameters":{"path":"/home/dev/project/src/main.rs"},"parameter_hash":"b71c9d04..."},"decision":{"verdict":"allow"},"content_hash":"5c1a77e2...","policy_hash":"...","metadata":{"acp":{"sessionId":"sess_01HZ7Q8YB...","toolCallId":"tc_01HZ7Q8YC...","enforcementMode":"cryptographically_enforced"}},"kernel_key":"25403c1e...","signature":"e7f8a9b0..."}
{"id":"rcpt-acp-01HZ7Q8YD...","timestamp":1744993869,"capability_id":"acp-session:sess_01HZ7Q8YB...","tool_server":"srv-coder","tool_name":"terminal/create","action":{"parameters":{"command":"rm"},"parameter_hash":"9f0e12a3..."},"decision":{"verdict":"deny","reason":"command 'rm' not in allow list","guard":"terminal-guard"},"content_hash":"3d2b90cc...","policy_hash":"...","metadata":{"acp":{"sessionId":"sess_01HZ7Q8YB...","toolCallId":"tc_01HZ7Q8YD..."}},"kernel_key":"25403c1e...","signature":"c1d2e3f4..."}

receipt list emits JSON Lines (one ChioReceipt per line) regardless of any format flag — there is no table renderer. The ACP-specific fields ride under each receipt's metadata.acp object (sessionId, toolCallId, enforcementMode, and the authorization-linkage fields). Pipe to jq to filter or fold the stream into whatever table view you want.

Compliance Certificates

The receipts are the raw evidence; a compliance certificate is the signed summary over one session. Generate it with the chio CLI command. Point chio cert generate at a session ID and a receipt store; it reads receipts whose capability id starts with acp-session:<session_id> and emits a signed ComplianceCertificate.

# Generate a signed certificate over one session's receipts.
$ chio cert generate --session-id sess_01HZ7Q8YB3N8G0XHB0T6KQ4F9R \
    --receipt-db ./receipts.sqlite \
    --budget-limit 600 \
    --output ./session-cert.json

# Verify it against the trusted kernel key. Add --full --receipt-db to
# re-verify every underlying receipt signature, not just the certificate's.
$ chio cert verify --certificate ./session-cert.json \
    --trusted-kernel-pubkey ./kernel.pub

# Inspect the body without verifying.
$ chio cert inspect --certificate ./session-cert.json

Session ID:     sess_01HZ7Q8YB3N8G0XHB0T6KQ4F9R
Schema:         chio.compliance.certificate.v1
Receipt count:  4
First receipt:  1744993921
Last receipt:   1744993932
Signatures:     valid
Chain:          continuous
Scope:          compliant
Budget:         compliant
Guards:         compliant

The certificate body reports the receipt count, the session's first and last receipt timestamps, and per-dimension verdicts — signatures valid, chain continuous, scope compliant, budget compliant, guards compliant — plus any anomalies. It is signed with the kernel's Ed25519 key, so a downstream consumer attests to a whole session without replaying the raw receipts.

Differences from the MCP Adapter

At a glance:

MCP guards are evaluated at decision time, and their allow or deny decisions are signed with the tool call. ACP guards are also evaluated at decision time; session/update events add tool-call observations afterward. ACP receipts share asession_id, so 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 · 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.