Not the same thing as Event Plugins. CAO has two unrelated plugin systems. Agent plugins are portable packages of skills and MCP servers that conform to the open Agent Plugins 1.0.0 specification and work across many agent clients. Event plugins are Python packages that run inside
cao-serverand react to CAO lifecycle events. Different formats, different audiences, different code. This page is about the first kind.
The committed pin lags by one release, and that is structural. The operator package's
mcp.jsonpins an exact published version (§7.2.1 allows a singlecommandtoken, so the manifest cannot execute anything but a released artifact), which means it can only ever name a release that already exists — never the one being built.scripts/build_agent_plugin.pyrefuses a pin whosecao-ops-mcp-serverdoes not bound its HTTP requests, and the release workflow'sregenerate-agent-pluginjob rebuilds the packages after publishing so the pin advances to the release containing that fix. Until such a release exists the committed package pins the newest published version; a plain rebuild still works, because the boundedness question is asked only when a build would change the pin or when--require-bounded-clientis passed. How that question is answered, and what the lag means formake check-agent-plugin, are described under CAO's own packages.
Warning
Installing an agent plugin runs untrusted code and content from that source. A plugin's skills become instructions injected into your agents' system prompts, and its MCP servers become subprocesses on your machine. CAO implements no trust model, no signing, and no provenance verification for agent plugins — the specification defers all three to a future revision, and CAO inherits that deferral rather than inventing its own. Install plugins only from sources you would trust with a shell on your machine.
A directory with a plugin.json manifest at its root:
my-plugin/
├── plugin.json # required manifest
├── skills/ # optional; each immediate child is one Agent Skill
│ └── my-skill/
│ └── SKILL.md
└── mcp.json # optional; MCP servers (see "MCP servers" below)
Because the format is an open specification rather than a CAO invention, the same directory is installable by any client that implements Agent Plugins 1.0.0 — and CAO ships itself in that format too (see CAO's own packages). The clients CAO itself exercises end to end are Kiro CLI and Claude Code; support in any other client is that client's claim to make, not something CAO verifies.
Installing third-party agent plugins into CAO needs nothing beyond CAO itself.
The two prerequisites below apply to the cao operator package — the one a
foreign client installs to drive CAO — and are also stated in that package's
manifest description:
| Prerequisite | Why |
|---|---|
uv on PATH |
The packaged MCP server is launched via uvx. The specification allows only a single command token, so the package cannot bundle a launcher. |
A CAO API server at http://127.0.0.1:9889 (cao-server) |
Every operator tool is an HTTP call to that server. |
CAO_AUTH_LOCAL_TOKEN, only when the CAO API has authentication enabled |
Every tool is a scope-gated HTTP call. The server attaches that token as Authorization: Bearer …, read from the environment of whatever client launched it — the package itself stores no credential. In IdP mode the client must also export the same AUTH0_DOMAIN / CAO_AUTH_JWKS_URI the API uses, so the server can tell the auth layer is on; in local-token mode the token alone is enough, because the same variable both enables auth and is the credential. With authentication disabled nothing is sent and no variable is needed. |
The posture is localhost-only. SERVER_HOST defaults to 127.0.0.1, the
package never reaches a remote endpoint, and nothing in it opens a listening
socket. If you override CAO_API_HOST or CAO_API_PORT to a non-loopback
address, you have knowingly left that posture — CAO has not silently changed it.
CAO will not start a server for you. If cao-server is not running, an
operator tool call returns a structured error naming the failed operation and
its cause. Self-starting a long-lived daemon on a fixed local port would take
the decision of when CAO is listening away from you, so it is rejected rather
than merely unimplemented.
Note
The command verb below is decided. Decision M1 is recorded as
Option A (signed off by the issue author, 2026-09-18, in
the #573 design): cao plugin names
agent plugins. That retracts a roadmap item, because docs/plugins.md had
promised cao plugin list / info / enable / disable for event plugins;
event plugins get cao event-plugin … if that surface is built. Deciding the
verb did not ship it. The surface is still gated; see the "built but not
shipped" note further down this section.
# Install from a local directory
cao plugin add ./path/to/my-plugin
# Install from a GitHub repository, optionally at a ref and/or subdirectory
cao plugin add https://github.com/owner/repo
cao plugin add https://github.com/owner/repo --ref v1.2.0 --subdir packages/my-plugin
# Check a candidate without installing it
cao plugin validate ./path/to/my-plugin
cao plugin validate ./path/to/my-plugin --json
# See what is installed, and which skill came from where
cao plugin list
cao plugin list --json
# Remove one (its persistent data is kept unless you ask otherwise)
cao plugin remove my-plugin
cao plugin remove my-plugin --purge-data--json on list and validate emits a machine-readable report for CI and
scripting. cao plugin add and cao plugin validate exit non-zero when a
plugin is not loadable.
Source-kind inference is syntactic; it does not probe the filesystem. Paths
beginning with ./, ../, /, or ~ are local, even when their names end in
.git or contain @ and :. Prefix an ambiguous local name such as
user@host:plugin with ./; without that prefix it is an SSH-style source
regardless of whether a same-named directory exists. The HTTP API also accepts
an explicit kind: "path". Filesystem checks belong to local-source resolution,
not to choosing the source kind.
A git source is cloned only over https:// or ssh:// (URL or scp-style
git@host:owner/repo.git) and only from an allowed host: github.com by
default. Set CAO_PLUGIN_ALLOWED_HOSTS to a comma-separated list of hostnames
to allow others (an internal GitLab or CodeCommit mirror, for example); the
list replaces the default, so include github.com if you still want it.
Entries are bare hostnames, matched case-insensitively: no scheme, port or
path (an entry like host:8443 matches nothing). A source may name any port
on an allowed host. The same shape as CAO_PROFILE_ALLOWED_HOSTS for
profile downloads.
file://, git://, http:// and remote-helper spellings such as ext:: are
refused before any git process starts, as are URLs carrying a query string,
fragment or embedded credential, and locations that are not git URLs at all
(a local path reaching the git branch through the API, for instance). For a
repository on this machine, pass its directory as a plain path source instead.
Independently of that check, every git CAO runs is pinned to
GIT_ALLOW_PROTOCOL=https:ssh and http.followRedirects=false, so the
transport rule holds inside git too and an allowed host cannot redirect the
clone somewhere the allowlist never saw (a renamed repository therefore fails
with git's own message; retype the new location).
The pip/uv requirement spelling is accepted for the two forms that map
cleanly onto a transport, and rewritten before the clone:
| You type | CAO clones |
|---|---|
git+https://host/path |
https://host/path |
git+ssh://host/path |
ssh://host/path |
Every other git+ form — git+file://, git+git://, git+http://, or a bare
git+something — is refused with a message naming the two supported forms.
Git would otherwise read git+file as the name of a remote helper and fail with
fatal: remote helper 'git+file' aborted session.
The same operations are available over the HTTP API — GET/POST /plugins,
POST /plugins/validate, DELETE /plugins/{name} — and in the web UI's
Plugins tab.
Note
The whole management surface is built but not shipped. Requirement 16.5
forbade it reaching end users while M1 was open. M1 is now decided, but
shipping is a separate maintainer decision, graduation, tracked in
#1244. Until
then the surface is off by default and refuses to execute: the cao plugin command group and all four
HTTP routes are gated on the CAO_AGENT_PLUGINS_ENABLED environment variable
(1/true/yes), the routes returning 404 and the command group erroring out
without it. The web Plugins tab is additionally gated off at build time by
PLUGINS_TAB_ENABLED in web/src/featureFlags.ts, and the four TUI rows are
Policy::Hidden and filtered out of the command palette entirely. To try the
surface before it graduates, export the variable:
export CAO_AGENT_PLUGINS_ENABLED=1Authorization is separate from that gate and still applies once it is open:
reads need cao:read or better, and install, validate and remove need
cao:write or cao:admin.
Two providers — Kiro CLI and OpenCode — read SKILL.md from disk during a
session rather than snapshotting it at launch. Removing a plugin can therefore
pull a skill out from under an agent that is mid-task and about to load it.
cao plugin remove checks running sessions and, if any profile references a
skill this plugin provides, reports which sessions and skills are affected and
asks for confirmation. It warns; it does not refuse — you may legitimately
want the plugin gone, and blocking removal while any long session runs would
make the store impossible to clean. --yes skips the prompt for scripted use.
The web UI applies the same gate before issuing its DELETE.
~/.aws/cli-agent-orchestrator/
├── agent-plugins/<name>/ # the plugin's own bytes; CAO never modifies them
├── agent-plugin-data/<name>/ # persistent plugin data; survives updates
└── skills/ # the global skill store (projection target)
Both directories are created 0o700 (owner-only). agent-plugin-data/ lives
outside agent-plugins/ deliberately: an update replaces a plugin's package
bytes wholesale, and the specification requires persistent data survive that.
cao plugin remove keeps it; --purge-data deletes it.
A plugin's skills are projected into the global skill store as managed symlinks:
~/.aws/cli-agent-orchestrator/skills/<skill-name>
-> ~/.aws/cli-agent-orchestrator/agent-plugins/<plugin>/skills/<skill-name>
That single mechanism reaches every provider through the pathway it already
uses — the runtime catalog, Copilot's baked .agent.md, Kiro's skill:// globs,
and OpenCode's config symlink. See
Agent-plugin-provided skills for the details and
the collision rules.
On a system where symlink creation is unavailable (Windows without Developer
Mode or elevation), CAO falls back to copying and reports that it did. You can
make the choice explicit with "skills": {"projection_mode": "copy"} in
settings.json.
A copied projection carries a .cao-projection.json recording a digest of the
bytes CAO wrote and the skill name it belongs to, and CAO replaces or removes such
a directory only when both still hold. So a copy you edited in place is left alone
and reported rather than overwritten or swept, a copy relocated to another name
confers no ownership, and a regular file at a projected skill name is never
removed. See
Agent-plugin-provided skills for the
full rule.
Every install and every validate produces a report of findings, each
citing the specification clause it enforces:
| Severity | Meaning |
|---|---|
fatal |
The plugin is rejected. Nothing is installed. |
skipped |
One skill, component type, or server entry was dropped. The rest still load. |
A plugin never widens an agent's tool allowlist. A plugin-provided MCP server
reaches an agent only if that agent's profile names it — "*", an explicit
@server-name, or a matching glob in allowedTools. A glob is matched
case-sensitively against the servers actually delivered to that agent, so
@plugin-* grants a delivered plugin-tools, @PLUGIN-* grants nothing, and a
pattern matching nothing delivered grants nothing. Servers you declare in the
profile yourself are still granted automatically; only plugin-provided ones are
excluded.
This is deliberate and fail-closed. Role defaults enumerate what they trust by
name, and a plugin appears in no role default — so a supervisor
(@cao-mcp-server, fs_read, fs_list, with no fs_write and no
execute_bash, precisely so it must delegate) and a reviewer (read-only) keep
exactly their designed posture when you install a plugin. Plugin servers obey the
same rule every other tool obeys: appear in the allowlist or do not run.
The cost is that a freshly installed plugin is inert until you name its server. That is the intended trade: you are present at the install, whereas the silent widening it replaces was not visible at all. To grant one:
allowedTools:
- "fs_read"
- "@plugin-tools" # or "@plugin-*", or "*" for everythingSee Tool restrictions for how allowedTools and roles
resolve.
A skill is validated over its whole tree, not just its top level, because
copy-mode projection copies the whole tree. A nested symlink that resolves outside
the plugin root (skill.link_escapes_root), one whose target is missing
(skill.link_dangling), a directory symlink forming a cycle
(skill.link_cycle), and a special file such as a FIFO or device
(skill.special_entry) each skip that skill only — its siblings and the rest
of the package still install. A skills/<name> that is itself a symlink
contained in the root stays permitted, as §4.1 requires.
cao plugin validate also measures each loaded skill against the Agent Skills
limits CAO's loader does not enforce: the name pattern ^[a-z0-9]+(-[a-z0-9]+)*$
(skill.name_pattern), a name of at most 64 characters (skill.name_length), a
description of at most 1024 characters (skill.description_length), and a body
of at most 500 lines after the frontmatter (skill.body_length). Each is a
WARNING: CAO still loads and delivers the skill and the exit status is
unchanged, but another Agent Skills client may reject it. The codes match the
cao-agent-plugin-audit skill's validator, which reports the same conditions as
failures.
Copy-mode projections are assembled in a staging directory and moved into place with a single rename, so the projected path only ever contains a complete tree. A failed copy leaves nothing behind: unmarked content at a projected path would be indistinguishable from a skill you created yourself, which would make every retry refuse to touch it. Staging lives beside the skills directory rather than inside it, so no glob aimed at the skills directory can observe a partial copy.
An MCP defect is scoped to what it actually invalidates. A defect in the
document — not an object, a missing or mismatched $schema, an unknown
top-level key, or an mcpServers that is not an object — disables MCP for the
plugin, because there is no well-formed entry left to keep. A defect in one
server entry skips that entry and delivers its siblings, and the package stays
loadable, so cao plugin validate still exits 0. Every per-entry code
(mcp.server_invalid, mcp.url_invalid, mcp.url_insecure,
mcp.headers_invalid, mcp.cwd_unsupported, mcp.transport_unsupported) is
reported at install and launch rather than logged quietly — a missing tool is
otherwise invisible.
| warning | Reported; nothing was dropped. |
| info | Informational. |
Failure is deliberately granular. One broken skill inside an otherwise valid
plugin is skipped with a report while its siblings install normally; a missing
skills/ directory is not an error at all; and a fatal manifest problem rejects
the plugin before any component loads, leaving your installed set byte-identical
to what it was.
Validation never reaches the network. CAO validates against schema bytes committed to its own repository, because the specification forbids retrieving a schema while loading a plugin — which also means a compromised schema host cannot change what CAO considers valid.
The schema-pin checks compare the recorded source URL and each schema URL/ID against their exact canonical values, separately from checking that the pin's policy is documented. A hostname mentioned in policy prose is not a URL validation rule.
A plugin may declare MCP servers in an mcp.json beside its plugin.json. CAO
validates it against the pinned mcp.schema.json, maps each server into its
internal MCP configuration, and merges the result into the mcpServers of every
agent profile it installs — the same dict from which each provider's native MCP
form is already derived. So a declared server reaches Kiro's agent JSON and
OpenCode's opencode.json with no per-provider work.
| When | Providers |
|---|---|
| Install time — written into a config file the CLI reads later | kiro_cli, opencode_cli |
| Launch time — recomputed each time a terminal is created | claude_code, codex, kimi_cli, cursor_cli, copilot_cli, antigravity_cli, omp, grok_cli, mcode |
| Never — the provider builds no MCP configuration at all | hermes, mock_cli |
The last row is reported, not silent: installing an agent for one of those
providers emits an mcp.provider_unsupported finding naming each server that
will not arrive. Only MCP is affected — the plugin's skills are delivered
normally.
Launch-time delivery is recomputed rather than persisted on purpose: the mapped
paths are absolute ${PLUGIN_ROOT}/${PLUGIN_DATA} expansions, so a stored copy
would go stale the moment CAO_HOME_DIR moved or a --force reinstall relocated
the root.
The rows above are maintained by hand, but the classification they describe is
machine-checked: test_mcp_launch_delivery.py asserts that every ProviderType
value falls into exactly one delivery bucket, so a newly supported provider cannot
be added without a test failing. Nothing parses this table — if you change the
code, change these rows too.
When the merge happens matters, and it is worth knowing as an operator:
cao install <agent>picks up whatever plugins are installed at that moment.cao plugin add/cao plugin removere-materialize the provider configs of agents you have already installed, so a plugin's servers appear on the agents you own without reinstalling each one, and are withdrawn when the plugin is removed. This is not cosmetic:mcpServersis written into each provider's config file and never re-read, so a removed plugin's servers must be actively taken out of those files — otherwise a provider would keep trying to launch a binary that removal just deleted from disk.
What "withdrawn" means depends on how a provider stores its config, and the difference is deliberate rather than an inconsistency:
- Kiro rewrites the agent's own file (
<name>.json) wholesale on every refresh, so a removed plugin's server is simply absent afterwards. - Copilot never stores plugin servers in a file. Its
<name>.agent.mdcarries only the agent's name, description and prompt, and the servers are passed with--additional-mcp-configeach time a terminal launches, which is why the table above lists it as launch time. A removed plugin's server is therefore absent from the next launch. A refresh still rewrites<name>.agent.md, because its prompt bakes in the skill catalog. - OpenCode shares one
opencode.jsonthat CAO edits in place, and CAO must never delete a key it might not own. A removed plugin's server is therefore disabled ("enabled": false), not deleted: OpenCode will not spawn it, and re-installing the plugin re-enables it. The trade is that the disabled entry — with its now-dangling command — stays visible inopencode mcp listuntil you remove it by hand. CAO now records a fingerprint of each plugin server it writes (seeopencode-cli.md), but still disables rather than prunes withdrawn entries; pruning on that record is tracked as a follow-up.
Server names collide the way skill names do, and are resolved by the same kind of
rule rather than by timing. A server your profile already declares always
wins — including CAO's own cao-mcp-server — and a plugin's same-named entry is
dropped with a report rather than merged, renamed, or prefixed. Between two
plugins claiming one name, the lexicographically smallest plugin name wins.
Renaming would be worse than dropping: the plugin's own documentation, and any
skill it ships that names the server, would describe something that no longer
answers. On OpenCode, that shared opencode.json may also hold servers you
wrote by hand; CAO applies the same rule there, dropping a plugin server with a
report rather than overwriting an entry it cannot prove it placed.
The same restraint applies to the per-agent tool grant OpenCode needs. CAO merges
into agent.<id>.tools and withdraws only the <servername>* keys it recorded
granting (in a cao-grants.json sidecar beside opencode.json) or can place inside
its own plugin store — so a model, prompt or "bash": false you set on a
CAO-installed agent survives every install, refresh and uninstall. See
opencode-cli.md for the exact rule.
A plugin's MCP servers are commands the plugin chose, run on your machine with your user's permissions. CAO expands only the two placeholders below, keeps every server's working directory and
./-rooted command inside the plugin's own directory, and warns about credential-shaped values — but it does not sandbox the process, and it cannot: an MCP server is meant to do real work. The consent gate is the untrusted-content warning printed at install time, which is why installing is an explicit act and whycao plugin validateexists to let you readmcp.jsonbefore you install it. CAO's own localhost-only posture is unchanged by this: nothing here opens a port or accepts a remote connection.
An unusable mcp.json disables MCP for that plugin and nothing else — its
skills still install and deliver. One bad server entry likewise invalidates only
that entry; its siblings load.
Two placeholders are expanded, and only these two:
| Placeholder | Expands to |
|---|---|
${PLUGIN_ROOT} |
the plugin's own directory |
${PLUGIN_DATA} |
the plugin's persistent data directory |
They are expanded only in args elements, env values, and cwd — never
in env keys, command, url, or header names and values. Expansion is
single-pass: text introduced by a replacement is not re-scanned, and any other
${...} is left exactly as written. CAO does not perform any further
substitution on a mapped entry, because the specification forbids it.
Some entries are rejected, always with a report and never silently:
-
commandmust be one token. It is never shell-split. A./-rooted command must resolve inside the plugin root. -
envmust not declarePLUGIN_ROOTorPLUGIN_DATA. CAO supplies both itself, after applying the plugin's ownenv; an entry that tries to override them is invalidated. -
cwdmust stay contained, checked after expansion against whichever root it is anchored to. Omitted, it defaults to the plugin root. How it then reaches the agent depends on what the target provider's config format can express, which is a per-provider fact rather than one rule:Delivery Providers How Native field codex,antigravity_cli,opencode_cli,kimi_cliThe format documents a working-directory key, so CAO writes it directly. Codex mcp_servers.<id>.cwdand Antigravitycwdare documented; OpenCode'sMcpLocalConfig.cwdand FastMCP'sStdioMCPServer.cwd(Kimi) are in their schemas./bin/shwrappergrok_cli,mcode,kiro_cli,claude_code,cursor_cli,copilot_cli,ompThe format has no working-directory key, so the command becomes /bin/sh -c 'cd -- "$1" && shift && exec "$@"' cao-cwd-shim <cwd> <command> <args…>.execreplaces the shell, the environment passes through, and argument boundaries survive because each argument stays a separate argv element.Nothing to carry hermes,mock_cliThese build no MCP configuration at all and already report mcp.provider_unsupportedper server.Each row was checked against that vendor's own MCP documentation on 2026-09-16. The table is exhaustive over CAO's providers and a test asserts that, so a newly added provider cannot silently inherit a policy. Only agent-plugin entries are wrapped — a
cwdyou wrote in a profile yourself is passed through untouched. -
A working directory this host cannot honour is reported, not ignored. On a host with no
/bin/sh, a wrapper provider's stdio servers are skipped withmcp.cwd_unsupportedrather than started in the wrong directory; remote servers in the same document are unaffected. -
A remote
urlmust behttps, orhttpto loopback. Cleartext to any other host is refused (mcp.url_insecure) because the plugin author, not the operator, chose the endpoint. Userinfo credentials, a fragment, a non-HTTP scheme and a missing host are refused asmcp.url_invalid. The schema'sformat: uricannot express any of this — in JSON Schemaformatis an annotation, not an assertion. -
Header names must be RFC 9110 tokens and values visible ASCII (space and tab allowed); otherwise
mcp.headers_invalid. Two names differing only in case are the same field supplied twice, so the entry is refused rather than silently resolved to whichever the serializer happens to keep. An authorization-shaped value stays a warning and is still delivered. -
A transport the target provider cannot carry is skipped, not failed over to a different one. Where the two vocabularies merely differ, the name is translated rather than refused — Grok writes
streamable-httpas its ownhttp. -
A server name the target provider cannot express is skipped. The specification puts no pattern on
mcpServerskeys, but a provider's own config format may: MiniMax Code accepts only^[a-z][a-z0-9]*(?:[._-][a-z0-9]+)*$, so a server calledAcmeis dropped with a report for that provider and delivered normally to every other. Reported rather than passed through because MiniMax's serializer rejects such a name while a terminal is being created — passing it on would cost you the agent, not just the tool. Codex applies the same rule with its own shape,^[A-Za-z0-9_-]+$, because there the name becomes a segment of a TOML dotted path in a-coverride: a dot would nest the entry under the wrong table, and the provider raises during terminal creation. Environment keys need no such rule on Codex — they are written as one quoted-key inline table on the value side, which expresses any key the specification allows. -
Credential-shaped
envandheadersvalues are warned about, never blocked. The specification forbids credentials there; usecao envand CAO's secret gate for real secrets.
CAO ships its own agent plugins, so any Agent-Plugins-compatible client can drive a CAO session, extend CAO, author and audit an agent plugin, or build an AG-UI client on CAO without CAO-specific integration code:
| Package | Install this if you are… | Skills | Also ships |
|---|---|---|---|
cao |
an operator driving CAO from another client | cao-session-management, cao-agent-routing, cao-supervisor-protocols, cao-worker-protocols |
the cao-ops MCP server |
cao-contributor |
a contributor extending CAO itself | cao-provider, cao-plugin, cao-contributing |
— |
cao-agent-plugin-lifecycle |
an author writing a new Agent Plugins 1.0.0 package or auditing an existing one | cao-agent-plugin-creator, cao-agent-plugin-audit |
— |
cao-ag-ui-builder (name provisional) |
a builder writing a UI or client on CAO's AG-UI surface, against CAO main |
agui-author |
— |
The skill names are the folder names you will see under
~/.aws/cli-agent-orchestrator/skills/ after installing, which is what makes a
collision report readable when one of them clashes with a skill you already have.
Every package is generated from CAO's own skills/ directory by
scripts/build_agent_plugin.py, and make check-agent-plugin fails if the
generated packages drift from it — so this table, the packages, and the shipped
skills cannot disagree for long.
Each package also carries a small Claude Code compatibility overlay:
.claude-plugin/plugin.json (identity only, mirrored from plugin.json) and,
for cao, a .mcp.json byte-identical to mcp.json. Claude Code (verified
against 2.1.226) discovers skills/ from the standard layout unchanged but
reads identity and MCP servers only from those two files; every other client
ignores dot-prefixed entries, and the validator discovers fixed locations only,
so the overlay changes nothing for Agent-Plugins-conformant clients. It is
generated and drift-guarded like every other package file.
The operator package's mcp.json declares one server, cao-ops, launched as
uvx --from cli-agent-orchestrator==<version> cao-ops-mcp-server — the
outside-a-session tool surface. The in-session cao-mcp-server is
deliberately not packaged: it derives its identity from a CAO_TERMINAL_ID that
a foreign client does not have, so its orchestration tools would fail on first
call. The version is pinned exactly, and the build refuses to write a pin that
is not already published on PyPI. cao-contributor ships no mcp.json at all:
authoring skills work through the host agent's own tools and need no CAO
runtime, so the uv and cao-server prerequisites do not apply to it.
cao-agent-plugin-lifecycle ships no mcp.json either: its skills need no CAO
runtime, and the audit skill's validator is a standalone script that carries its
own pinned copy of the schemas. Nor does cao-ag-ui-builder: agui-author
teaches the emit-side vocabulary (the six allow-listed generative-UI components
and the CUSTOM cao.generative_ui frame they ride in), which an agent sends
through the emit_ui tool CAO already gives it. Its recorded wire trace and the
gates that guard it live in examples/ag-ui/cao-dojo,
because a generated package may hold only its manifest, docs and skills.
The build also refuses to write a pin whose published cao-ops-mcp-server does
not bound its HTTP requests, and it decides that by inspecting the published
sdist for a timeout= on every requests.* call site. Not by comparing against
a version floor: a floor encodes "which release contains the fix" as a constant
somebody has to move on every release, and one set ahead of every published
version refuses legitimate patch releases outright. If the artifact cannot be
inspected — PyPI unreachable, no sdist, module renamed — the build says that
rather than reporting the release as unbounded. --skip-publish-check suppresses
this fetch along with the publication probe, so a local rebuild needs no network.
Because the pin lags, make check-agent-plugin verifies the committed packages
at the version they were built at, and its only version constraint is that
this version is not ahead of pyproject.toml. Releasing bumps pyproject.toml
on main before regenerate-agent-plugin repins, and demanding equality in that
window would fail CI on main and on every open PR for something that is not
wrong. Everything else the check covers — drift in any generated byte, validator
findings, allowlist agreement, mcp.json conformance — is unaffected. Strict
equality lives behind --check --require-current-pin, which that job runs after
it has pushed, so a forgotten repin is still caught, just not on everyone
else's PR.
To rebuild after editing a packaged skill without moving the pin, run
make agent-plugin-keep-pin (scripts/build_agent_plugin.py --keep-committed-pin).
It renders every package at the version the committed packages already pin, contacts
no PyPI, and
refuses, writing nothing, when the committed manifests are missing, unreadable or
disagree, naming each package and its version. make agent-plugin renders at
pyproject.toml's version and so moves the pin; that is the release job's step.
When make check-agent-plugin cannot tell the committed pin, it says why before
listing the drift that follows.
# From a clone
cao plugin add ./agent-plugin/cao
# From GitHub, without cloning
cao plugin add https://github.com/awslabs/cli-agent-orchestrator --subdir agent-plugin/caoInstall cao if you want to use a fleet; install cao-contributor if you
want to change CAO. Keeping them separate means each package's skills all
serve one story, rather than every foreign agent carrying repo-development
instructions it will never act on.
Both packages are generated from CAO's canonical skills/ tree by
scripts/build_agent_plugin.py and committed, with make check-agent-plugin
failing CI on any drift.
Note
The name cao-contributor and the packaged name of the event-plugin authoring
skill are provisional, pending maintainer decision M4.
Two routes reach a client, and they are worth keeping apart. Through CAO —
cao plugin add then cao install, which materializes the plugin's skills and
MCP servers into whatever provider you install for. Directly in a foreign
client — install the package with that client's own plugin mechanism, which is
what makes the package portable rather than CAO-specific.
Everything below starts from a clone:
cao plugin validate ./agent-plugin/cao # loadable? skills named? mcp present?
cao plugin add ./agent-plugin/caoKiro reads skills natively. cao install <profile> --provider kiro_cli writes
skill:// resource globs and the cao-ops server straight into the agent JSON,
so the plugin's four skills and its MCP server are configured at launch:
cao install developer --provider kiro_cli
# then inspect what CAO emitted:
# $CAO_AGENTS_DIR/developer.json -> resources[] has skill:// globs,
# mcpServers.cao-ops has PLUGIN_ROOT/PLUGIN_DATA expanded to real paths,
# allowedTools does NOT contain "@cao-ops" -- see the grant rule belowDelivery is not authorisation, and the difference is deliberate. A
plugin-provided MCP server is configured into the profile, but CAO does not
append @<server> to an allowedTools list that did not name it. Per issue #573
AC7, the alternative is worse: resolve_allowed_tools appends @<server> to any
allowlist that is not "*", so an unrelated cao plugin add would silently widen
every managed agent — including the roles whose defaults exist to deny.
supervisor is @cao-mcp-server, fs_read, fs_list with no fs_write and no
execute_bash precisely so that seat must delegate; reviewer is read-only by
the same design. The rule is fail-closed and is not special-cased by role, because
role defaults enumerate what they trust by name.
An operator opts in by naming the server in the profile's allowedTools:
allowedTools:
- "@builtin"
- fs_read
- "@cao-ops" # or a matching glob, or "*" — then it is grantedThe accepted cost is that a freshly installed plugin's tools are inert until named. That is visible, because the operator just ran the install; the widening it replaces was silent. Both halves are asserted by the dog-food recording (steps 3 and 3b).
Because Kiro powers install Agent Plugins natively, the same directory is also installable directly as a power — no CAO-specific packaging step.
Claude Code discovers the standard skills/ layout unchanged, but reads package
identity only from .claude-plugin/plugin.json and MCP servers only from
a root .mcp.json. Both are generated into each package (see
CAO's own packages), so the strict validator passes:
claude plugin validate ./agent-plugin/caoInstall it through Claude Code's marketplace flow (see Claude Code's own plugin
documentation for the current command names), then confirm two things
independently: the four skills are discovered, and the cao-ops server appears
with its tools callable. With no cao-server running, a tool call returns a
structured error naming the operation and the cause rather than hanging; start
one and the same call returns real data:
cao-server & # then, from the client, call cao-ops list_sessions
# -> {"success": true, "sessions": [...]}That two-state check is the useful one — it proves the tool is really wired to a local CAO rather than merely registered.
Antigravity CLI is a CAO provider, and it receives skills by runtime prompt
injection plus the load_skill MCP tool rather than by reading a skill
directory (see skills.md for the per-provider mechanism table):
cao install developer --provider antigravity_cliThe plugin's skills reach it through CAO's delivery, so no client-side plugin
install is required. For any Gemini-family or other client that accepts an MCP
server configuration, agent-plugin/cao/mcp.json is the portable declaration to
copy — it is the same mcpServers shape the standard defines, pinned to a
published cli-agent-orchestrator version, so it needs no CAO-specific
translation.
Verification status, stated plainly: the Kiro path and the Claude Code path above have been exercised end to end against live clients. The Gemini-family/other-client note describes the portable declaration those clients consume; it is not a claim that every such client has been tested.
The pipeline that installs those packages is exercised against itself by a
gated recorder: CAO installs its own cao agent
plugin through its own cao plugin / cao install commands and asserts the
result at every step. The GIF below is the captured run — but the prose is not
the evidence, the gate is: the recorder only produces a GIF when the
asserting script exits 0 and prints its PASS marker, so a regressed pipeline
cannot make a green recording. The CI job
Agent Plugins dog-food (shift-left recording) runs it on every change.
What each step asserts, and why it is the load-bearing one:
cao plugin validate— the manifest is loadable, its four shipped skills are named, andmcp_presentwith thecao-opsserver.cao plugin add— each skill is projected into the skill store as a symlink whose target resolves into the plugin store (asserted on the link target, not onlsoutput).cao install … --provider kiro_cli— the delivery fix, end to end: the agent JSON carries theskill://globs andcao-opswithPLUGIN_ROOT/PLUGIN_DATAexpanded to real paths inenv, and nox-cao-pre-expandedmarker leaked. The profile names noallowedTools, so@cao-opsis absent from the resolved list — the fail-closed rule below, asserted where it takes effect. A second install (step 3b) of a profile that does declareallowedTools: ["@builtin", fs_read, "@cao-ops"]gets the grant, so the recording proves both halves of the rule rather than one.cao install … --provider opencode_cli—opencode.jsongets a real boolean"enabled": true; and installing over a user's own same-named entry preserves it and emits a finding rather than clobbering it.cao plugin remove cao— cross-provider removal: absent from the rewritten Kiro/Copilot config; disabled ("enabled": false) on OpenCode's shared config. The opt-in profile keeps its operator-written@cao-opsentry through the removal — CAO withdraws the server it configured, not the allowlist entry it never wrote. The offline run asserts those written shapes; a live-gated step additionally observes, viaopencode mcp listand a sentinel wrapper, that a disabled entry is reporteddisabledand no subprocess is spawned for it (verified against OpenCode 1.18.15).
The runnable example, the offline-vs-live assertion matrix, and the recorder are
in examples/agent-plugins/agent-plugins-dogfood/.
cao-agent-plugin-lifecycle is not exercised by that recording, which
installs only cao. It is gated in CI by make check-agent-plugin, and it is
audited by a skill it carries: the cao-agent-plugin-audit validator, run
against the package, reported no fatal, skipped, limit or warning finding at the
commit that added the package. That audit is not run in CI; rerun it by hand.
uv run --script skills/cao-agent-plugin-audit/scripts/validate_agent_plugin.py ./agent-plugin/cao-agent-plugin-lifecycleAt the commit that added the package, this exits 0 and ends with
summary: 0 fatal, 0 skipped, 0 limit, 0 warning, 1 advisory; exit 0. The
advisory is the listing of the manifest's description beside the skills that
would load, which the audit prints whenever it reads a manifest, for a reader to
compare. On the same
package, CAO_AGENT_PLUGINS_ENABLED=1 cao plugin validate ./agent-plugin/cao-agent-plugin-lifecycle --json reports "loadable": true and
no findings, exit 0.
This table maps each client requirement in Agent Plugins 1.0.0 to the CAO code that implements it and the test or corpus case that proves it. The rows follow the client conformance checklist (21 items), with section numbers from the specification. The checklist is non-normative, and the specification governs where they differ. The guide for client authors is Implement an Agent Plugins client. A checklist item is split into more than one row where CAO's status differs between its parts.
The specification defines no conformance suite, so this table is CAO's own record, not a certification. Each test it names asserts the requirement on its row.
Statuses:
- Implemented: CAO does it, and the row names the evidence.
- Delegated: CAO does not launch MCP servers. It writes them into each provider's configuration or launch command (see Which providers receive plugin MCP servers), and the provider CLI starts and connects to them. A delegated row is a runtime behaviour of that CLI, which CAO's tests do not observe.
- Not implemented: the specification requires it and CAO does not do it.
- Not applicable: the requirement binds someone other than this client.
Code paths are relative to src/cli_agent_orchestrator/agent_plugins/, and line
numbers are as of 381d21a3. Test paths are relative to test/agent_plugins/. A
corpus case is a directory under fixtures/corpus/, and
test_conformance_corpus.py::test_corpus_case checks its expected findings in
fixtures/corpus/cases.json as an exact set.
| # | Requirement | Spec | Status | CAO code | Proven by |
|---|---|---|---|---|---|
| 1 | Load a plugin from a directory, and reject package paths that resolve outside the root, including through symlinks | §4.1, §11.1.1 | Implemented | validation.py:232 validate_plugin; containment.py:48 resolve_within_root; manifest.escapes_root (validation.py:328), skill.escapes_root, skill.link_escapes_root (:869), mcp.escapes_root (mcp_mapping.py:972) |
corpus skill-escapes-root, skill-symlink-inside-root; test_validation.py::TestTotalityOnHostileInputs::test_manifest_symlinked_outside_the_root; test_nested_containment.py::TestNestedLinksAreValidatedBeforeAnythingIsCopied::test_a_nested_link_to_an_external_file_skips_only_that_skill; test_mcp_mapping.py::TestLoadAndMap::test_an_mcp_json_symlinked_outside_the_root_is_refused |
| 2 | Select local manifest rules from $schema, and never retrieve a schema while loading |
§5.2 | Implemented | Vendored schemas pinned by sha256 in schemas/agent_plugins/1.0.0/PIN.json; validation.py:155 _refuse_retrieval; manifest.schema_unsupported (:450) |
corpus manifest-unsupported-schema; test_schema_pin.py::TestOfflineValidation::test_valid_plugin_validates_with_sockets_blocked, ::test_unknown_schema_is_rejected_offline_rather_than_fetched; test_schema_pin.py::TestRegistryRefusesRetrieval::test_remote_ref_resolution_is_refused |
| 3 | Validate the closed plugin.json schema, the required $schema and name, and the name constraints |
§5.2, §5.3, §5.5 | Implemented | manifest.schema_missing (validation.py:434); _schema_findings (:524), which reports manifest.invalid and manifest.name_invalid (:543) |
corpus manifest-missing-name, manifest-bad-name; test_validation.py::TestManifestFatality::test_missing_schema_field_is_fatal, ::test_name_constraint_violations_are_fatal |
| 4 | Report and ignore unknown top-level fields | §5.2 | Implemented | manifest.unknown_field (validation.py:511) |
corpus manifest-unknown-field; test_validation.py::TestManifestTolerances::test_unknown_top_level_field_is_a_warning_and_the_plugin_loads |
| 5 | Ignore a non-object extensions, and ignore unimplemented namespaces without validating their values |
§8.1, §11.1.3 | Implemented. CAO implements no namespace, so every well-formed extensions member is dropped unread |
manifest.extensions_not_object (validation.py:493); object-valued extensions dropped at :502 |
corpus extensions-not-object, extensions-unimplemented-namespace; test_validation.py::TestManifestTolerances::test_extension_namespace_contents_are_never_validated |
| 6 | Reject other fatal manifest violations before discovering any component | §5.2, §11.3.2 | Implemented | _validate_plugin_inner (validation.py:265) returns before _discover_skills (:580) and _map_mcp (:949) run |
corpus manifest-missing, manifest-invalid-json; test_conformance_corpus.py::TestCanonicalExample::test_a_fatal_violation_rejects_before_any_component_loads |
| # | Requirement | Spec | Status | CAO code | Proven by |
|---|---|---|---|---|---|
| 7 | Discover supported component types only from their fixed locations, and skills only one level deep | §6.1, §7.1 | Implemented | Fixed names skills and mcp.json (validation.py:72-73); _discover_skills reads immediate children only (:624) |
corpus mcp-present; test_validation.py::TestComponentDiscovery::test_skill_discovery_is_not_recursive |
| 8 | Treat a missing component location as valid absence | §6.2 | Implemented | _discover_skills and load_and_map (mcp_mapping.py:958) return no finding for an absent location |
corpus skills-absent; test_validation.py::TestComponentDiscovery::test_missing_skills_directory_is_not_an_error |
| 9a | Isolate an invalid component type, an invalid skill and an invalid MCP entry at their own boundaries | §6.2, §7.1, §7.2.2, §11.3.3 | Implemented | skills.not_a_directory (validation.py:612); skill.missing_skill_md (:677); skill.invalid (:699); mcp.not_a_file (mcp_mapping.py:990); mcp.invalid_json (:1007); mcp.server_invalid (:681) |
corpus skills-not-a-directory, skill-invalid-sibling, skill-missing-skill-md, mcp-invalid; test_validation.py::test_property_sibling_independence; test_validation.py::TestMcpComponentDiscovery::test_mcp_json_that_is_a_directory_is_skipped |
| 9b | Skip a skill that breaks the Agent Skills limits: the name pattern, the 64-character name, the 1024-character description and the 500-line body | §7.1 | Not implemented. CAO reports each as a WARNING and still loads the skill. Whether to enforce them is an open maintainer question |
agent_skills_limit_violations (src/cli_agent_orchestrator/utils/skills.py:232, outside agent_plugins/), reported at validation.py:719 |
test_skill_limits.py::TestEachLimit::test_a_broken_limit_is_a_warning_and_the_skill_still_loads, which pins the current non-enforcing behaviour |
| 10 | Ignore unsupported component types, and support at least one of skills or MCP servers | §7, §11.1.8, §11.3.1 | Implemented. CAO supports both | Discovery reads only the two fixed locations (validation.py:72-73), so nothing else in the package is read |
Support: test_validation.py::TestHappyPath::test_skills_are_discovered, test_validation.py::TestMcpComponentDiscovery::test_a_valid_mcp_json_is_mapped. No test plants an unsupported component directory, such as a client-extension directory, and checks that it is ignored |
| # | Requirement | Spec | Status | CAO code | Proven by |
|---|---|---|---|---|---|
| 11 | Support at least one of stdio and Streamable HTTP | §7.2.1 (Transport support) | Implemented, per provider. Eight providers carry stdio, Streamable HTTP and SSE; opencode_cli, codex and antigravity_cli carry stdio only; hermes and mock_cli have no MCP path, which is reported as mcp.provider_unsupported |
PROVIDER_TRANSPORTS (mcp_mapping.py:103) |
test_mcp_launch_delivery.py::TestEveryDeliveringProviderIsCovered::test_every_provider_type_has_a_transport_row; test_mcp_mapping.py::TestTransportMatrix::test_http_transports_map_for_providers_that_carry_them, ::test_a_provider_with_no_mcp_path_reports_provider_unsupported |
| 12 | Use each entry's declared transport for the initial connection attempt | §7.2.1 (Transport support) | Delegated. CAO never substitutes a transport: an unsupported one is skipped with mcp.transport_unsupported (mcp_mapping.py:771, §7.2.2 rule 4). The connection attempt is the provider CLI's |
_map_entry (mcp_mapping.py:719) |
CAO's half: test_mcp_mapping.py::TestTransportMatrix::test_an_unsupported_transport_is_skipped_not_substituted; test_mcp_launch_delivery.py::TestKimiCarriesTheDeclaredTransport::test_an_sse_plugin_server_reaches_kimi_as_transport_sse |
| 13 | Validate the closed top-level mcp.json and each server entry independently |
§7.2.1, §7.2.2 | Implemented | _document_errors (mcp_mapping.py:626); _server_errors (:646) |
corpus mcp-invalid; test_mcp_mapping.py::TestTheDocumentEntryBoundary::test_one_invalid_server_does_not_drop_its_valid_siblings; ::TestDocumentLevelFailures::test_an_unknown_top_level_key_still_disables_mcp |
| 14a | Keep a stdio command as one token, never split or placeholder-expanded, and resolve a ./ command against the plugin root |
§7.2.1 (stdio) | Implemented | _map_stdio (mcp_mapping.py:816); mcp.command_invalid (:835); mcp.command_escapes_root (:849) |
test_mcp_mapping.py::TestCommandIsOneToken::test_a_command_with_spaces_is_not_split, ::test_a_command_is_never_placeholder_expanded, ::test_a_dot_rooted_command_is_resolved_inside_the_plugin, ::test_a_dot_rooted_command_escaping_the_root_is_skipped |
| 14b | Resolve a bare command with the platform's executable search |
§7.2.1 (stdio) | Delegated. CAO passes a bare name through unchanged, and the provider CLI that spawns the server resolves it | _map_stdio (mcp_mapping.py:860) |
CAO's half: test_mcp_mapping.py::TestCommandIsOneToken::test_a_bare_command_passes_through_untouched |
| 15a | Provide a dedicated, writable PLUGIN_DATA directory that survives plugin updates |
§9.1 | Implemented. Created owner-only (0o700) at install, kept by cao plugin add --force, and kept on removal unless purged |
installer.py:198; store.py:122 plugin_data_dir |
test_installer.py::TestInstallHappyPath::test_install_creates_the_plugin_data_directory; test_store.py::TestPluginDataSurvivesUpdates::test_data_survives_a_publish_over_an_existing_name; test_install_ordering.py::TestDataDirectoryPrecedesPublish::test_reinstalling_preserves_existing_plugin_data; test_store.py::TestPermissions::test_store_directories_are_owner_only |
| 15b | Set PLUGIN_ROOT and PLUGIN_DATA after the configured env, and invalidate an entry that declares either name |
§9.1, §9.2 | Implemented, in the server configuration CAO writes | mcp.env_reserved_key (mcp_mapping.py:876); both names set last (:915-917) |
test_mcp_mapping.py::TestCaoSuppliedEnv::test_plugin_root_and_data_are_injected, ::test_a_plugin_declaring_a_reserved_key_invalidates_that_entry |
| 15c | Start the subprocess with that env overlaid on a base environment |
§9.1 | Delegated. The provider CLI chooses the base environment and starts the process. CAO has not traced each provider's spawn path | n/a | none |
| 16 | Expand only ${PLUGIN_ROOT} and ${PLUGIN_DATA}, single-pass, only in args, env values and cwd |
§9.2, §11.1.6 | Implemented | expand_placeholders (mcp_mapping.py:275), called only for args, env values and cwd in _map_stdio |
test_mcp_mapping.py::TestExpansionTargets::test_args_elements_are_expanded, ::test_env_values_are_expanded_but_keys_are_not, ::test_a_url_is_never_expanded, ::test_header_names_and_values_are_never_expanded; test_mcp_mapping.py::test_property_only_the_two_placeholders_are_replaced, ::test_property_expansion_is_single_pass; test_mcp_delivery.py::TestTheRealSeam::test_an_unrelated_placeholder_stays_literal_in_the_provider_config |
| 17a | Default cwd to the plugin root; accept only ./-, ${PLUGIN_ROOT}- or ${PLUGIN_DATA}-rooted forms; contain each after expansion |
§7.2.1 (stdio), §11.1.7 | Implemented. Providers without a native cwd key get a /bin/sh -c 'cd …' wrapper, or the entry is skipped with mcp.cwd_unsupported where /bin/sh is missing |
Default at mcp_mapping.py:891-893; containment mcp.cwd_escapes_root (:903); the form is the cwd pattern in the pinned mcp.schema.json, enforced per entry by _server_errors |
test_mcp_mapping.py::TestExpansionTargets::test_cwd_defaults_to_the_plugin_root, ::test_cwd_is_expanded_and_contained, ::test_a_plugin_data_rooted_cwd_is_checked_against_plugin_data; ::TestPerEntryIsolation::test_a_bad_cwd_invalidates_only_that_entry; ::TestCwdShim::test_the_shim_rewrites_command_and_args_and_drops_cwd; ::TestCwdUnavailable::test_stdio_entries_are_skipped_and_remote_siblings_still_map. No test plants a cwd in another form, such as a bare data |
| 17b | Remote url: absolute HTTP or HTTPS, no user information or fragment, HTTPS off loopback, never expanded |
§7.2.1 (Streamable HTTP) | Implemented | _remote_url_findings (mcp_mapping.py:495); mcp.url_invalid (:506); mcp.url_insecure (:545) |
test_mcp_mapping.py::TestRemoteUrlSemantics::test_cleartext_http_is_refused_off_loopback, ::test_cleartext_http_is_allowed_on_loopback, ::test_a_structurally_prohibited_url_is_refused |
| 17c | Headers: valid HTTP fields, no name repeated under different casing, never expanded | §7.2.1 (Streamable HTTP) | Implemented | _header_findings (mcp_mapping.py:552) |
test_mcp_mapping.py::TestRemoteHeaderSemantics::test_an_invalid_header_refuses_only_that_entry, ::test_names_differing_only_in_case_are_a_conflict |
| 17d | Never forward configured headers to another origin through a redirect or an SSE endpoint event without user authorization | §7.2.1 (Streamable HTTP) | Delegated. The provider CLI makes the HTTP connection | n/a | none |
| 18 | Continue loading after an independent MCP server fails to start, connect, authenticate or complete the handshake | §7.2.2 rule 5, §11.3.3 | Delegated. These failures happen in the provider CLI. CAO's configuration-time isolation is row 13 | n/a | none |
| # | Requirement | Spec | Status | CAO code | Proven by |
|---|---|---|---|---|---|
| 19 | Require mcp.json to target the same specification version as plugin.json; a mismatch disables only MCP |
§10.1, §7.2.2 rule 2 | Implemented. CAO pins one version, 1.0.0, so an mcp.json targeting another version is caught first by the unsupported-schema check and reported as mcp.schema_unsupported. The equality check covers a future second supported version |
mcp.schema_unsupported (mcp_mapping.py:361); mcp.schema_version_mismatch (:379) |
test_validation.py::TestMcpComponentDiscovery::test_a_version_mismatched_mcp_json_disables_mcp; test_mcp_mapping.py::TestDocumentLevelFailures::test_a_version_mismatch_with_plugin_json_disables_mcp |
| 20 | Never reassign a published canonical schema identifier to different contents | §10.1 | Not applicable. This binds the specification's publishers. On the client side, CAO pins the bytes it was built against and fails a build when they drift | schemas/agent_plugins/1.0.0/PIN.json |
test_schema_pin.py::TestPinIntegrity::test_vendored_bytes_hash_to_the_recorded_value; ::TestDriftGuard::test_check_fails_on_a_hash_mismatch |
| 21 | Let plugins keep targeting older versions under the client's compatibility policy | §10.1 | Implemented. CAO's policy is 1.0.0 only, the only published version, and any other version is rejected with manifest.schema_unsupported |
validation.py:450 |
test_validation.py::TestManifestFatality::test_unrecognized_schema_version_is_fatal_and_names_the_pin |
Two requirements fall outside the checklist and are covered above: the default working directory (§11.1.7) is row 17a, and the extension-directory rule (§8.2) applies only to a namespace a client implements, and CAO implements none.
- No trust model. Installing a plugin is equivalent to running untrusted code and content from its source. There is no signing and no provenance check.
- Prompt injection is the main exposure. Plugin skill content flows into
agents' system prompts. This is not new —
extra_skill_dirsalready admits third-party skill content — but installing a plugin is one command rather than a deliberate settings edit.cao plugin listshows which plugin contributed each skill, so provenance is always recoverable. - Paths are contained. Every path a plugin references is resolved with realpath and confined to that plugin's own root. A symlink whose target resolves inside the root is allowed; one that escapes is rejected, whatever the literal path looks like.
- No secrets in package data. The specification forbids credentials in MCP
envandheaders. CAO warns when a value looks credential-shaped and does not treat it as a supported mechanism. Usecao envand CAO's secret gate instead. - A plugin's MCP tools are not auto-authorised. Installing a plugin configures
its MCP servers into managed profiles but does not add
@<server>to anallowedToolslist that did not name it, socao plugin addcannot widen the deny-by-design roles. Naming the server (or a matching glob, or"*") is the operator's opt-in — see Kiro CLI. - No schema fetch at load time. Pinned bytes only.
- Skills — the skill system agent plugins deliver into
- Event Plugins — CAO's other, unrelated plugin system
- Agent Plugins 1.0.0 specification
