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.
- When this is the page you want
- Declaring one
- MCP servers
- Kiro CLI
- Claude, via ACP
- GitHub Copilot CLI, via ACP
- The other built-in ids
- Others
- 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:
- Leave it out and a built-in id keeps its own. Pointing
kiro-cliat a different binary does not switch off Kiro’s credits and meter. "extensions": []switches them off. That is the only way to get a built-in id running on the bare protocol.- 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:
- 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. - 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:
- v2 works out the window size; v3 does not. v2 reads
/context showonce 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. - 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-toolsinargsmakes 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/v3selects Kiro’s engine (defaultv2).kiro-cli-v3already passesv3. Writing the flag yourself on akiro-clientry 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 usekiro-cli-v3.- Kiro loads its own MCP config too —
.kiro/settings/mcp.jsonand~/.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 inai.mcpServers, and can show up as tools you never forwarded. Remove or"disabled": truethe entry in Kiro’s own config if you wantai.mcpServersto 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 oneai.mcpServersdeclared. 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:
- Its Allow All switch is set off, and set off again if it turns on.
- 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.
- A message that starts with
/allow-all,/yolo,/autopilot,/permissions,/add-dir,/cwdor/sandboxis not sent. Each one stops Copilot asking or widens the folders it may use. --disallow-temp-dirstops Copilot using the system temp folder without asking.- 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 fullai.acpAgentskey reference.- Agent SDKs — the built-in
ghcp/claudeproviders this page is the alternative to. ai@1— the args every provider shares, whichever one runs the session.