Agent Client Protocol (ACP)

ghcp and claude are built-in providers, each wired to its vendor’s own SDK. Eight more are built in over the Agent Client Protocol instead: kiro-cli, kiro-cli-v3, copilot-cli, claude-cli, gemini-cli, codex-cli, cursor-cli and opencode-cli. Each is a provider: an ai@1 task can name with nothing in settings.json; what you do need is the vendor’s CLI installed. ai.acpAgents in settings.json is the door for anything else that speaks ACP, and for changing how a built-in one is started.

  1. When this is the page you want
  2. Declaring one
    1. extensions — a vendor’s own extras
  3. MCP servers
    1. The directory limit applies here too
    2. Attached images go as the picture
    3. Answering each tool call yourself
    4. Every raw line the agent sends
  4. Kiro CLI
    1. What Kiro reports
    2. What v3 adds beyond the figures
  5. Claude, via ACP
  6. GitHub Copilot CLI, via ACP
  7. The other built-in ids
  8. Others
  9. Next

When this is the page you want

Not for ghcp or claude. Both already have a dedicated provider built on the vendor’s own SDK — see Agent SDKs. That stays the right way to reach either of them.

For Kiro. No SDK, so the CLI is the only way in. Two ids are built in — kiro-cli for its v2 engine and kiro-cli-v3 for the v3 beta. Install the CLI and name one. Either one reports what a turn charged in credits, how full the context window is, and your account’s usage this billing period — see Kiro CLI.

For Claude’s or Copilot’s own CLI over ACP — claude-cli and copilot-cli, also built in — for the one time it’s useful: comparing behaviour across agents, or standardising a team’s whole setup on one protocol rather than three vendor SDKs.

For Gemini CLI, Codex, Cursor or OpenCode — gemini-cli, codex-cli, cursor-cli, opencode-cli, built in. See the other built-in ids for what each needs installed.

For an agent this build ships no id for, or to change the command behind a built-in id. Both go under ai.acpAgents.


Declaring one

{
  "ai": {
    "acpAgents": {
      "kiro-cli": {
        "command": "kiro-cli",
        "args": ["acp"],
        "extensions": ["kiro-v2"]
      }
    }
  }
}

This is exactly the built-in kiro-cli entry, spelled out — you only write it to change something, such as a full path to the binary. provider: kiro-cli on an ai@1 task runs on it — same session shape as ghcp or claude: a response, and a tool call that is either answered for you or put to you as a card, depending on permissions:. Either way a path outside the session’s own directories is refused (see the directory limit). To run every ai@1 task and SDD phase on it instead of naming it per task, see making a provider the default.

The id can be anything except ghcp or claude. Those two are checked first, always — an acpAgents entry under either name is never reached. An entry under a built-in -cli id replaces the built-in one wholesale — except extensions, see below.

Full key reference (command, args, env, extensions, and the ${{ env.NAME }} gate): ai.acpAgents.

extensions — a vendor’s own extras

ACP does not cover everything an agent wants to say. Kiro sends what a turn charged, how full its window is and your account’s usage on channels of its own that the protocol never defined. An extensions list is how a runtime opts into reading them.

id Used by What it adds
kiro-v2 kiro-cli Kiro CLI’s v2 engine — _kiro.dev/metadata, plus its /context show and /usage slash commands after each turn
kiro-v3 kiro-cli-v3 Kiro CLI’s v3 engine — the same figures, sent as _meta on standard session_info_updates, plus _kiro/account/getUsage. See what v3 adds
copilot-cli copilot-cli Copilot CLI’s own sessionEvent notifications — what each turn charged, its context window, the folder boundary and the modes that must stay off, and Compact through its /compact
claude-cli claude-cli Claude’s ACP bridge — the folder boundary, the permission modes that must stay off, Compact through its /compact, and each model’s per-million price off its own description

Three rules:

  1. Leave it out and a built-in id keeps its own. Pointing kiro-cli at a different binary does not switch off Kiro’s credits and meter.
  2. "extensions": [] switches them off. That is the only way to get a built-in id running on the bare protocol.
  3. An id this build does not have is logged and skipped, naming the ones it does have. The agent still runs, just without those extras.

An entry with no extensions and no built-in id — any agent of your own — gets none, and runs on the protocol alone. Nothing is lost by that: a transcript, tool calls, plans and questions are all standard ACP.


MCP servers

Every server declared under ai.mcpServers is forwarded to an ACP agent too — same declaration, same ${{ env.NAME }} gate, same task-level mcp: selection ghcp/claude get. Nothing to add per agent.

stdio servers are always forwarded. ACP’s own capability flags never name stdio — it is the protocol’s baseline, not something an agent opts into. http and sse servers are only forwarded when the agent’s own initialize response actually advertised support for that transport; one that did not is left out and logged (system stream), naming the server and why, rather than sent and left to fail silently inside the agent.

A task’s mcp.tools is not applied to an ACP agent. mcp.servers is — a server the task did not select is not forwarded — but the protocol has no per-tool allow-or-deny at session/new the way Copilot’s and Claude’s own SDKs do, so every tool of a forwarded server reaches the agent regardless of the list, silently for now.

The directory limit applies here too

An ACP session is held to the same folders as the built-in providers — the task’s cwd and whatever the editor has open. See where a session may read and write for the whole rule and the one gap in it.

What is scanned here is the tool call ACP itself describes: the files it names in locations, and the raw input when the agent fills that in. A path outside the folders is refused and the refusal is logged, naming the tool and the path.

A refusal has to be one of the options the agent offered. The protocol gives no way to send a reason back with the answer, so this picks the agent’s own rejecting option — and when an agent offers none, the call is cancelled instead. Answering “allow” because nothing better was on the list is how a boundary gets lost.

The kind of call decides which folders apply. ACP names it, so a read or search may reach the read-only directories; every other kind, including one this build has not seen, is treated as a write.

Every other folder open in the editor is handed to the agent as ACP’s additionalDirectories, on both a new session and a resumed one. Without it an agent could not edit a file outside the first folder of a .code-workspace — on Kiro every such edit failed with ENOENT. This tells the agent where it may work; it does not widen the limit above, which is checked on this side either way.

Attached images go as the picture

An image attached to a message is sent as the image itself when the agent says it takes images. Any other file, an image the agent cannot take, or one that cannot be read, goes as a file link instead. Before this, a pasted screenshot reached the agent as a link only, so the model never saw it.

Answering each tool call yourself

permissions: manual on the ai@1 task — or Ask first switched on in the compose box — puts each request to you as a card instead of answering it. ACP agents read it, the same as Copilot does; Claude does not yet. See approving each request yourself for the whole rule.

Two things are ACP’s own:

  1. The choices on the card are the agent’s, not a fixed list. ACP sends the options it will accept — allow once, allow always, reject once, reject always — each under its own name, and the answer has to be one of their ids. Two options the agent named alike get the kind in brackets. “Allow always” is never shown, and never picked with Ask first off. After it, the agent stops asking about calls like that one, so the directory limit below never sees them. On Copilot CLI one “always” on a file edit covers every later edit in the session; on Claude it can save a rule into the repo’s .claude/settings.local.json, or switch the session to Bypass permissions when you accept a plan.
  2. The directory limit is checked first. A path outside the allowed folders is refused before any card is drawn, so Manual never gives you the chance to allow one.

With nobody watching (interactive unset), the call is allowed once and the log says the mode had nobody to ask — the same rule Copilot’s Manual follows. Closing a card without answering it, by stopping the turn or ending the session, cancels the call: it does not run.

command is resolved to an absolute path before it is sent. ACP’s own schema documents a stdio server’s command as an absolute path — stricter than the bare npx every MCP README (and ghcp/claude) accepts — and at least one real agent silently does not connect to a server declared the lenient way. A bare command is resolved against PATH first; a .cmd/.bat result (Windows only) is then wrapped for cmd.exe the same way Agent SDKs already documents for ghcp. Nothing to write differently — declare it the way every MCP README shows, same as for ghcp/claude.

The full session about to start — every capability the agent advertised and every server actually being sent, full command and args included — is logged in one block when the session opens (system stream): ACP agent '<id>' session: {...}. That block is the fastest way to tell “nothing was sent” from “it was sent and the agent dropped it” when a tool isn’t showing up.

Every raw line the agent sends

Beside that block, every line the agent writes on stdout — each ACP response, notification and request — is copied into the extension’s own output channel as [ACP_RAW] <agent>: <line>. Open it with Local Workflows: Show Logs and filter on ACP_RAW.

It goes there rather than into the run log because a turn streams hundreds of chunks and the run log is what the chat draws. It is the fastest way to tell “the agent said nothing” from “the agent said something this build did not draw”.

A stop is written into the run log with its reason — Sent session/cancel: Stop was pressed., or whatever else asked for it. An agent marks the tools it was running as cancelled for its own aborts too, so without that line the log could not tell the two apart. Claude and Copilot write the same thing in their own words (Sent interrupt:, Sent abort:).

Secrets the engine knows about are masked out of those lines first: a granted environment variable, an agent’s own env:, and an MCP server’s env or headers — each masked both as written and as it appears escaped inside a JSON string, because every ACP line is JSON. A secret the agent picked up on its own, from its own config or a file a tool read, is not known here and prints as it was sent.


Kiro CLI

Prerequisite: kiro-cli installed and signed in — kiro-cli login. kiro-cli whoami reporting you’re signed in does not mean the session token is still valid, since that check is local-state only; an expired token shows up as a slow session/new (repeated failing retries) followed by a -32603 Internal error on the very first prompt, which reads like a protocol bug and isn’t one. Run kiro-cli login again if you see that.

Two ids ship for it, one per engine:

provider: runs extensions
kiro-cli kiro-cli acp — the v2 engine, Kiro’s default kiro-v2
kiro-cli-v3 kiro-cli acp --agent-engine v3 --auth-method cli — the v3 beta (“KAS”) kiro-v3

Same binary, same sign-in, different engine. Neither is a separate install.

What Kiro reports

Both engines send credits, context and account usage — on channels nothing in Kiro’s public ACP docs describes, so every field is read as optional and a shape this build does not know costs that one message, never the session.

  Where it shows
What a turn charged, in credits the run’s cost lines and the usage card. Per turn, not a running total. A turn that ran no model — a slash command such as /tools — charges nothing and gets no line. Kiro never says which model a charge was for, so each bill is filed under the model the session runs on; a record saved before this sits under model not reported
How full the window is the context meter button in the strip across the top of the compose box. The popup behind it is the only place the window is drawn — the usage card is about what was charged, not about the window
What fills it the same popup: each context file and, on v2, each tool by name. v3 gives tokens with tools rolled up as builtin and mcp totals
Your account this billing period the Account section of the usage card, behind the Usage button — the plan, when the cycle resets, what is used against the allowance, and overage if the plan has it. A figure in money only shows with features.sessionCost on
Past the allowance a warning mark on the Usage button, so you see it without opening the card

Two differences worth knowing:

  1. v2 works out the window size; v3 does not. v2 reads /context show once and draws Kiro’s own percentage against that size for the rest of the session. v3’s token counts do not agree with its own percentage, so the share shown is Kiro’s figure and the parts are token counts beside it, with no size claimed.
  2. v3 replays old turns on resume. Those replayed updates are skipped, so resuming a session never charges a turn twice.

What v3 adds beyond the figures

All of this is the kiro-v3 extension. "extensions": [] switches the lot off.

  What happens
Modes v3 lists its modes — Default, Spec, Plan and the rest — as a session config option, so Mode appears on the compose box’s provider line, between the runtime and the model. It is drawn only for a runtime that lists modes
Autopilot is kept off Kiro’s autopilot is set to off with Ask first off as well as on. A tool call Kiro never asks about never reaches the directory limit. With Ask first off this engine answers the request itself, after the folder check; with it on you answer it
The end-of-turn review is accepted with Autopilot off, Kiro asks once for each write and then once more as the turn ends, for every file the turn changed. Each write was already allowed on its own card, so the second yes is given for you and the files are named in the log instead
Compact the context meter’s Compact sends Kiro’s own _kiro/session/compact. Kiro writes a summary and carries on from it. It refuses while a turn is running or a compact is already going, and says so
The MCP status line one line in the chat as the servers settle: MCP: ado connected (12 tools) · github failed - token expired. It is held back until your first message, so it is not the first thing on an empty screen

MCP can be off for your whole organisation. When your org’s Kiro settings turn MCP off, Kiro starts no MCP server at all — including every one this extension forwards from ai.mcpServers — and nothing would otherwise say so. The chat gets one line instead:

MCP: off - your org's Kiro admin turned MCP off. No MCP server was
started, including the ones sent from settings.json (reason:
admin_disabled).

api_failure in place of admin_disabled means Kiro could not read your org’s settings and turned MCP off to be safe, which is worth a retry. admin_disabled is a decision, and nothing on this side changes it.

The last account answer each runtime gave is kept in ~/.local-workflows/usage.json, so a new session shows your account straight away — as of when it was last fetched — instead of nothing until the CLI answers. It is in your profile, never in the workspace, and never reaches git.

{ "command": "kiro-cli", "args": ["acp"], "extensions": ["kiro-v2"] }
  • Logs are at %TEMP%\kiro-log\logs\kiro-chat.log — not stderr, and not ~/.kiro, which is the separate Kiro IDE’s own directory. Start there when an agent declared this way fails with an opaque error.
  • -a trust-all-tools in args makes Kiro answer its own tool-call permission requests before this engine ever sees one — which also means the directory limit never sees them. Do not set it unless you mean exactly that.
  • --agent-engine v1/v2/v3 selects Kiro’s engine (default v2). kiro-cli-v3 already passes v3. Writing the flag yourself on a kiro-cli entry changes the engine but not the extensions: v3 sends nothing on v2’s channels and answers v2’s commands with an internal error, so the credits and the meter go quiet. Name "extensions": ["kiro-v3"] with it, or just use kiro-cli-v3.
  • Kiro loads its own MCP config too — .kiro/settings/mcp.json and ~/.kiro/mcp-config.json — on top of whatever this engine forwards via ACP. There is no documented flag to turn that off. A server declared in one of those files runs alongside (or instead of) the one declared in ai.mcpServers, and can show up as tools you never forwarded. Remove or "disabled": true the entry in Kiro’s own config if you want ai.mcpServers to be the only source.
  • Two of Kiro’s own stderr lines never reach the task log: a client capability it did not get (... doesn't support form elicitation) and an OAuth registration attempt failing for a server from its own MCP config (see above), not one ai.mcpServers declared. Neither named anything this engine could act on, so both are filtered before logging — not this engine erroring, and not Kiro erroring either.

Claude, via ACP

provider: claude-cli, built in. An alternative to the built-in claude provider, using the official claude-agent-acp wrapper instead of this engine’s own Claude Agent SDK integration.

Prerequisite: npm install -g @agentclientprotocol/claude-agent-acp — not a dependency of this extension, an external binary you install yourself, the same as kiro-cli. It authenticates the same way the CLI does — the same sign-in claude itself uses.

Nothing to declare. The built-in entry is { "command": "claude-agent-acp", "extensions": ["claude-cli"] }; write that under ai.acpAgents.claude-cli only to change it.

Its mode list is Claude’s permission modes, and only Manual and Plan are offered. Accept edits, Auto and Bypass permissions run tool calls without asking, so the directory limit would never see them. If the session opens in one (a defaultMode in a Claude settings file) or moves to one (accepting a plan), it is put back in Manual and the chat says so. Leaving out "claude-cli" from extensions turns this off.

Compact in the context meter sends Claude’s own /compact as a message - a turn like any other, so it costs a model call.

The id cannot be claude. AgentProviders checks the built-in providers first and only falls back to ai.acpAgents for an id neither ghcp nor claude already owns — an entry named claude here is never reached, silently, because the built-in always answers first. That is why the shipped id is claude-cli.

Prefer the built-in claude provider for everyday use — it’s the same vendor SDK this wrapper is also built on, with one fewer process in the middle.


GitHub Copilot CLI, via ACP

provider: copilot-cli, built in. An alternative to the built-in ghcp provider.

Prerequisite: the same Copilot CLI the built-in provider needs — install it first if you haven’t. --acp --stdio is the same binary, a different mode.

Nothing to declare. The built-in entry is { "command": "copilot", "args": ["--acp", "--stdio", "--disallow-temp-dir"], "extensions": ["copilot-cli"] }; write that under ai.acpAgents.copilot-cli only to change it.

Copilot is kept asking about every tool call, so the directory limit sees each one:

  1. Its Allow All switch is set off, and set off again if it turns on.
  2. The mode list offers Agent and Plan. Autopilot turns Allow All on, so it is not offered, and a session that ends up in it is put back in Agent.
  3. A message that starts with /allow-all, /yolo, /autopilot, /permissions, /add-dir, /cwd or /sandbox is not sent. Each one stops Copilot asking or widens the folders it may use.
  4. --disallow-temp-dir stops Copilot using the system temp folder without asking.
  5. Copilot asks about paths outside its folders in a request of its own, which always says “read” and joins every path into one line. Each path is checked on its own, as a write unless the call that needs it only reads.

What each turn cost comes from Copilot’s own event feed: the credits each model call charged, on the turn’s “Turn finished” line (premium requests too, when hideCopilotPremiumRequests is off). The token counts on that line are the turn’s own; Copilot sends a running total for the whole session, which is taken apart per turn.

Compact in the context meter sends Copilot’s own /compact as a message. It is a turn like any other, so it costs a model call.

Same rule as Claude above: the id cannot be ghcp — that name is the built-in provider’s, and it is checked first every time. That is why the shipped id is copilot-cli.

GitHub’s own docs describe ACP support in Copilot CLI as public preview and subject to change — a real caveat, not boilerplate: at the time this was written, Copilot CLI’s ACP reference didn’t confirm session resume (session/load) or tool-call events (tool_call/tool_call_update) the way Claude’s and Kiro’s do. Verify those specifically before relying on this route for anything unattended.

Prefer the built-in ghcp provider for everyday use, for the same reason as Claude above.


The other built-in ids

Four more ship ready to name. Each needs its vendor’s CLI installed and signed in first; none is a dependency of this extension. Commands come from the ACP registry as of 2026-09.

provider: runs install
gemini-cli gemini --acp npm install -g @google/gemini-cli
codex-cli codex-acp npm install -g @agentclientprotocol/codex-acp — the ACP adapter for OpenAI Codex, same idea as claude-agent-acp
cursor-cli cursor-agent acp Cursor’s agent CLI, from cursor.com
opencode-cli opencode acp OpenCode, from opencode.ai

None of these four has been run end to end by this project the way Kiro, Claude and Copilot have. Read the ACP agent '<id>' session block the engine logs on initialize (see Others below) before trusting one with anything unattended.


Others

Any CLI that implements ACP works the same way — declare its command and whatever args put it into ACP mode, and it runs as a provider like any other. The ACP registry lists agents that speak the protocol; a growing list at the time of writing includes Cline, Devin, Goose, Qwen Code, Kimi and others beyond the eight built in.

If nothing is written here for the agent you’re adding: check its own documentation for an acp subcommand or an --acp flag — that’s the whole shape this page’s examples follow — declare it, and read the ACP agent '<id>' session: {...} block this engine logs on initialize (under "system", described above) to see what agentCapabilities it actually advertised before trusting it with anything unattended.


Next

  • settings.json — the full ai.acpAgents key reference.
  • Agent SDKs — the built-in ghcp/claude providers this page is the alternative to.
  • ai@1 — the args every provider shares, whichever one runs the session.

Back to top

Local Workflows is a VS Code extension. Everything it does is declared in a YAML file you own.


- 13-Oct-2026 02:53 PM +0000