ACP integration

Use Agent Client Protocol (ACP) to connect an editor to CodeGraph, send prompts, receive streamed updates, and handle requests for files, terminal commands, and permissions. This reference helps integration developers choose a transport and implement the JSON-RPC connection. ACP v1 is the default and production-compatible profile. An experimental ACP v2 alpha profile is available behind CODEGRAPH_ACP_EXPERIMENTAL_V2=true. The profile is selected by initialize and remains fixed for the lifetime of that connection.

Both profiles use the same CodeGraph session core, workspace controls, permission requests, and Model Context Protocol (MCP) bridge. Image and audio capabilities are not advertised.

Transports and routes

HTTP session administration is available through GET /api/v1/admin/runtime/acp/sessions and DELETE /api/v1/admin/runtime/acp/sessions/{session_id}. HTTP protocol state and sessions are isolated by authenticated subject and project. WebSocket connections keep the project scope resolved from the token, machine credential, or explicitly enabled local-development boundary.

The HTTP endpoint collects ACP v1 prompt notifications and returns them in result._meta.codegraph.sessionUpdates. ACP v2 session/prompt is asynchronous and needs a streaming transport, so HTTP rejects it with JSON-RPC error -32004 before executing the turn.

Authentication boundary

The HTTP JSON-RPC and session routes require an administrator, the admin:all scope, or a service account with scenarios:execute. An unauthenticated localhost bypass exists only when local_dev_unauthenticated_surfaces_enabled is explicitly enabled.

WebSocket accepts a bearer access token or an API key. Machine credentials are additionally checked against project scope, the X-CodeGraph-Machine-Contract version, interface policy, and configured mTLS requirements. Transport authentication finishes before JSON-RPC parameters are parsed. Both ACP initialize responses advertise an empty authMethods list; the legacy v1 authenticate method therefore operates only inside an already verified transport boundary.

ACP v1 methods

For an already authenticated transport connection, the minimal initialization request is:

{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":1}}

Match the response by id: 1 and check result.protocolVersion: 1. An error response does not initialize the connection. This request alone does not create a session or execute a prompt.

Call initialize with protocolVersion: 1 before any other method. The server rejects an uninitialized request with -32002.

The standard v1 surface contains session/new, session/load, session/prompt, and session/cancel. During a prompt, the server can issue client requests for fs/read_text_file, fs/write_text_file, terminal operations, and session/request_permission. Clients must route responses by JSON-RPC request ID while continuing to process session/update notifications.

CodeGraph v1 prompts may opt in to those client calls with the _meta.codegraph.clientContext extension on a content block. Its readTextFiles array accepts objects with path. Each object in the terminals array contains command, an args array of strings, and optional cwd, env, or outputByteLimit. CodeGraph invokes only capabilities advertised at initialize, adds the returned editor-visible file content and terminal result to that prompt, and always releases a created terminal. This metadata is a CodeGraph extension, not a new standard ACP method.

CodeGraph-specific editor functions use the _codegraph/ namespace:

• _codegraph/thread/start, _codegraph/thread/resume, _codegraph/thread/fork, _codegraph/thread/list, _codegraph/thread/archive, and _codegraph/thread/compact;
• _codegraph/turn/start and _codegraph/turn/interrupt;
• _codegraph/diagnostics/subscribe, _codegraph/diagnostics/unsubscribe, and _codegraph/hover/request;
• _codegraph/item/fileChange/respondApproval.

Legacy unprefixed names remain available through an explicit compatibility adapter. Such responses carry _meta.codegraph.legacyMethod; new clients should use the namespaced methods.

Experimental ACP v2 profile

With CODEGRAPH_ACP_EXPERIMENTAL_V2=true, a connection may initialize with protocolVersion: 2, info.name, and info.version. The profile supports session/new, session/list, session/resume, session/close, session/delete, session/prompt, session/cancel, and $/cancel_request.

session/prompt acknowledges the request before the turn finishes. The client then receives session/update notifications, including state transitions and tool-call updates. Use stdio or WebSocket for this flow. Reinitializing a connection with another protocol version fails closed; open a new connection instead.

To roll back the experimental profile, set CODEGRAPH_ACP_EXPERIMENTAL_V2=false and restart ACP connections. ACP v1 does not depend on the v2 flag.

MCP servers and permission flow

session/new and the applicable resume/load flows accept ACP MCP descriptors for stdio and http transports. Stdio commands are resolved to an executable and run as a native argv with no shell. Environment and header entries must use name/value objects; names are validated and values cannot contain NUL, carriage-return, or newline characters.

HTTP MCP descriptors accept public HTTPS endpoints only. Credentials in the URL, query strings, fragments, loopback addresses, private networks, link-local addresses, and plaintext HTTP are rejected by the default URL policy. A platform administrator can allow additional addresses through an explicit allowlist. The address is validated before connection. For a server that redirects requests, configure outbound network restrictions that also cover redirect destinations.

Every declared MCP server must connect during session creation. If any connection fails, the server closes connections already opened for that request and removes the incomplete ACP session. Before invoking an MCP tool, CodeGraph sends session/request_permission; a denial or timeout prevents the call. Closing the session or transport releases the MCP subprocesses and network connections.

Workspace and terminal containment

File calls require an absolute workspaceRoot and target path. A path that resolves outside the root fails with outside workspace root. Writes also reject sensitive path fragments such as .git, .env, .ssh, .aws, .credentials, __pycache__, and node_modules. The check matches these fragments anywhere in the normalized, lowercase path, not only as complete directory names.

Terminal calls require the same absolute workspaceRoot; cwd must remain below it. Commands run as argv with shell=False. The checked-in allowlist contains bounded build and inspection commands. Interpreters and shells such as python, powershell, pwsh, cmd, bash, sh, py, python3, and node are blocked. Arguments must be a native list of strings without NUL or newline control characters.

Network routes use transport authentication and project scope. The workspace and terminal checks apply within that scope.

File-change approval

The server advertises an approval flow and sends the established item/fileChange/requestApproval notification. Clients answer with the canonical _codegraph/item/fileChange/respondApproval method; the unprefixed response name is accepted by the compatibility adapter. An unanswered request is declined after the configured timeout.

The fs/write_text_file method writes a file after checking its path within the workspace. For writes that require human approval, the client obtains and records approval first, then exposes the write operation. This is a separate step in the client’s workflow.

Runtime limits

Defaults in ACPRuntimeConfig bound the service to 100 concurrent sessions with a 60-minute session timeout, 128 pending agent-to-client requests per connection, 256 queued stdio notifications, and a 300-second approval timeout. The same configuration also controls terminal wait and cleanup timing, bridge polling, and streamed chunk sizes. Deployments may override these values through the unified runtime configuration; clients must not assume that defaults were retained.

Recovery checklist

1. Confirm the route prefix is /api/v1/admin/runtime/acp, not the historical /acp prefix.
2. Verify transport authentication before debugging JSON-RPC parameters.
3. Send one initialize request and keep that protocol profile for the connection.
4. Use stdio or WebSocket for ACP v2 prompts and agent-to-client requests.
5. For file or terminal errors, keep absolute workspaceRoot, path, and cwd values below the same root.
6. Treat a blocked executable, rejected MCP endpoint, or missing permission as a policy outcome.