Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
28 commits
Select commit Hold shift + click to select a range
1dce343
feat(external-agents): scaffold the plugin and exempt its bin/ from t…
kyle-sexton Nov 21, 2026
5c9a0c7
fix(external-agents): mark the copied prerequisites scripts executable
kyle-sexton Nov 21, 2026
7e6f7fe
feat(external-agents): add the runner foundations: config, provider r…
kyle-sexton Nov 21, 2026
b213f5b
fix(external-agents): read binary_path from the personal layer only
kyle-sexton Nov 21, 2026
7f7eff9
feat(external-agents): add run, review, status, result and cancel wit…
kyle-sexton Nov 21, 2026
9b1b127
fix(external-agents): harden failure reporting, breaker closing, canc…
kyle-sexton Nov 21, 2026
c3b425b
fix(external-agents): end a timed-out version or login query with a s…
kyle-sexton Nov 21, 2026
555ff8d
fix(external-agents): run a briefed Codex review without --base and f…
kyle-sexton Nov 21, 2026
cea1e5b
fix(external-agents): read config from the convention home the reposi…
kyle-sexton Nov 21, 2026
c1c8f2d
fix(external-agents): tighten which executable a config file may choose
kyle-sexton Nov 21, 2026
5a4b567
fix(external-agents): keep the review status line on every path and s…
kyle-sexton Nov 21, 2026
c6d9f7f
fix(external-agents): print the status line when a run or review hits…
kyle-sexton Nov 21, 2026
c68a00f
fix(external-agents): mark the ordinal-suffix regex for the spell che…
kyle-sexton Nov 21, 2026
b9a03e9
feat(review): run Codex members through the external-agents command
kyle-sexton Nov 21, 2026
e570396
docs(review): say where council-plan's member verb is documented
kyle-sexton Nov 21, 2026
f77053f
feat(review): restore fanout's adversarial Codex run as a briefed review
kyle-sexton Nov 21, 2026
3b342a4
feat(external-agents): add the update action and scope briefed reviews
kyle-sexton Nov 21, 2026
6f7e206
Merge branch 'feat/external-agents-council' into feat/external-agents
kyle-sexton Nov 21, 2026
5375bdb
Merge remote-tracking branch 'origin/main' into feat/external-agents
kyle-sexton Nov 21, 2026
dbb0102
fix(external-agents): pin the agy record changes and name hooks in th…
kyle-sexton Nov 21, 2026
4b9c45e
feat(external-agents): add the Codex skill
kyle-sexton Nov 21, 2026
3b19613
fix(external-agents): cache help a CLI prints on stderr
kyle-sexton Nov 21, 2026
ef8ae7f
fix(external-agents): keep Codex prompt files out of consumer repos
kyle-sexton Nov 21, 2026
11a074e
fix(external-agents): use the implement stage and the new agy read-on…
kyle-sexton Nov 21, 2026
c6486fe
Merge remote-tracking branch 'origin/main' into feat/external-agents
kyle-sexton Nov 21, 2026
9418abc
docs(external-agents): record the plugin, bin/ and runner decisions
kyle-sexton Nov 21, 2026
277e545
fix(external-agents): honor the council opt-out and keep finishing jo…
kyle-sexton Nov 21, 2026
89a5ca9
Apply fix-docs on feat/external-agents
melodic-automation-lanes[bot] Nov 21, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 7 additions & 0 deletions .changes/external-agents/feat-external-agents-95264810.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
---
bump: minor
---

### Added

- The `external-agents` plugin: hands tasks and reviews to other vendors' official coding-agent CLIs through their documented headless surfaces, Codex first. This release ships the `external-agents` command (`run`, `review`, `status`, `result`, `cancel`, and `update`, which reports a CLI's version, login and latest release, caches its help per version (from stderr when a CLI prints its help there, and reported when a help command prints nothing), and checks its docs index and the config keys the runner passes), the team config schema for `<home>/external-agents.yaml`, and the Codex prerequisite with its daily latest-release check. Every run passes the mode's sandbox and never an approval bypass; a briefed review names its merge base and changed files; a run whose commands the sandbox refused is recorded `blocked-by-mode`, not `ok`; a CLI that is missing, logged out or over its usage limit is refused until its next trial time; `cancel` and the run timeout stop the whole process tree. The `/external-agents:codex` skill drives the command: it runs a Codex task or investigation in the foreground or background, resumes a thread, reviews a branch, and reads back `status`, `result`, `cancel` and `update`, with its first reply line naming the mode the job ran in, model and effort guidance as pointers to the Codex docs, and no model passed unless one is configured. It replaces OpenAI's `codex@openai-codex` plugin.
12 changes: 12 additions & 0 deletions .changes/review/feat-external-agents-council-d5b9c833.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
---
bump: minor
---

### Changed

- `/review:council` Codex members and `/review:fanout`'s Codex surface now run `external-agents review codex`, the command the `external-agents` plugin puts on the Bash `PATH`, instead of locating the OpenAI Codex plugin's install path. With that plugin not enabled, the member or surface reports `skipped (external-agents not enabled)`. Fanout's adversarial Codex run passes its own bundled brief, `skills/fanout/context/codex-adversarial-brief.md`, through `--brief-file`.
- `council-plan.mjs member` reads a script member's captured output and exit code as its council status (`ran`, `skipped (<reason>)` or `failed (<reason>)`) and its findings, finding the status line after any notices.

### Removed

- `scripts/codex-review.sh` and its test.
13 changes: 13 additions & 0 deletions .claude-plugin/marketplace.json
Original file line number Diff line number Diff line change
Expand Up @@ -972,6 +972,19 @@
],
"defaultEnabled": false
},
{
"name": "external-agents",
"source": "./plugins/external-agents",
"category": "workflow",
"tags": [
"codex",
"external-agents",
"cross-vendor",
"delegation",
"review",
"cli"
]
},
{
"name": "source-control",
"source": "./plugins/source-control",
Expand Down
2 changes: 1 addition & 1 deletion .github/workflows/pr-require-checks.yml
Original file line number Diff line number Diff line change
Expand Up @@ -2512,7 +2512,7 @@ jobs:
# cannot see one that is absent, as when a merge silently drops a
# plugin.json the catalog still lists (#1547). Repo-wide and static, so
# it always runs.
- name: Check every catalog entry resolves to a present, name-matching plugin manifest, and no plugin has a top-level bin/
- name: Check every catalog entry resolves to a present, name-matching plugin manifest, and no plugin but external-agents has a top-level bin/
id: plugin_manifest_presence
continue-on-error: true
shell: bash scripts/run-hygiene-gate.sh plugin-manifest-presence {0}
Expand Down
Original file line number Diff line number Diff line change
@@ -1,6 +1,8 @@
# Reject the three unused official plugin components, each with a recheck trigger

- Status: accepted
- Status: accepted; the `bin/` verdict partly superseded by
[ADR 0118](0118-ship-the-external-agents-command-in-bin-and-exempt-it-from-the-no-bin-gate.md)
for the external-agents plugin
- Date: 2026-07-12

## Decision
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,65 @@
# Replace the official Codex plugin with one external-agents plugin and a skill per CLI

- Status: accepted
- Date: 2026-11-21
- Refs: [#17954](https://github.com/melodic-software/claude-code-plugins/pull/17954) (the plugin and
the council switch-over), [#17967](https://github.com/melodic-software/claude-code-plugins/pull/17967)
(the Antigravity skill); owner interview of 2026-11-20 and 2026-11-21 (Q4, Q13, Q14, Q16, Q21,
Q28); [ADR 0118](0118-ship-the-external-agents-command-in-bin-and-exempt-it-from-the-no-bin-gate.md),
[ADR 0119](0119-run-every-external-cli-through-one-runner-over-provider-records-with-per-use-sandbox-ceilings.md)

## Context

OpenAI's `codex@openai-codex` plugin ([openai/codex-plugin-cc](https://github.com/openai/codex-plugin-cc))
was how sessions and the council review lanes reached Codex. It ships legacy `commands/`, a
proactive forwarding agent and hooks that run in every session. It drives `codex app-server`,
which OpenAI documents as experimental, and its prompting guidance names retired models. Upstream's
last push was 2026-07-08, and it had 546 open issues and pull requests when this was recorded. Council
reached into the plugin's private script by install path. The owner also wants the same pattern for
other vendors' CLIs: Gemini/Antigravity now, then Cursor, and maybe Grok's.

## Decision

1. **Replace, do not wrap.** The marketplace ships its own plugin, `external-agents`, and dotfiles
turn the official plugin off after it releases. The official plugin is cited as the upstream
source and none of its text or code is copied.
2. **One plugin, one skill per CLI.** `/external-agents:codex` is the first skill and
`/external-agents:antigravity` the second. Every skill shares the plugin's runner, job store,
CLI-facts cache and breaker. Another vendor's CLI is added as a provider record and a skill.
3. **No agent, no hooks, no `commands/`.** Delegation happens only when asked: a skill invocation,
or a council run that names the member. When the plugin is unused, nothing runs.
4. **The name and boundary is non-Anthropic coding-agent CLIs.** Only official vendor CLIs are in
scope: no third-party Claude Code plugin and no Claude provider. `multi-agent` stays Claude-only
and unchanged.
5. **Each skill learns its CLI from the CLI.** Facts come from the CLI's own help, cached per CLI
version, and each skill cites the vendor's docs index without copying from it.

## Considered options

- **Keep the official plugin and fix around it.** Rejected (Q4): the hooks cost every session,
the run surface is experimental, and upstream is not taking changes.
- **One plugin per vendor CLI.** Rejected (Q13): each plugin would duplicate the runner, job
store and breaker, so the copies would drift.
- **A forwarding agent, as upstream ships.** Rejected (Q14): a model hop that adds a turn and makes
the output shape depend on the model. Skills and the command reach the CLI directly.
- **Session hooks (a stop-time review gate, session transfer).** Rejected (Q16): they run whether
or not Codex is used, and the owner dropped both features.
- **Drive `codex app-server` or the Codex SDK.** Rejected: OpenAI documents `codex exec` as the
headless surface and calls the app server experimental
([non-interactive mode](https://learn.chatgpt.com/docs/non-interactive-mode.md)).

## Consequences

- Council's Codex member and `/external-agents:codex` move to the new plugin. Council no longer
looks up another plugin's install path.
- A new CLI costs one provider record, one skill and its tests. Each CLI's permission limits
differ, and ADR 0119 records them.
- Until dotfiles turn the official plugin off, both plugins are installed. Its hooks keep running
until then.

## Revisit triggers

- OpenAI resumes maintaining the official plugin and it reaches parity with current Claude Code
plugin guidance.
- A vendor CLI's headless surface cannot be described by a provider record and needs its own code
path.
Original file line number Diff line number Diff line change
@@ -0,0 +1,57 @@
# Ship the external-agents command in bin/ and exempt it from the no-bin gate

- Status: accepted
- Date: 2026-11-21
- Supersedes in part: [ADR 0021](0021-reject-the-three-unused-official-plugin-components.md), its
`bin/` verdict, for the external-agents plugin only
- Refs: [#17954](https://github.com/melodic-software/claude-code-plugins/pull/17954); owner interview
of 2026-11-21 (Q61, Q62: "go w/ recomendations");
[ADR 0117](0117-replace-the-official-codex-plugin-with-one-external-agents-plugin-and-a-skill-per-cli.md)

## Context

Council runs each member from a script, and `review:brief-reviewer` has no Skill tool, so neither
can invoke a skill. Before this change, council reached Codex by locating the official plugin's
install path and running its private script. ADR 0021 rejected `bin/` marketplace-wide. Its recheck
trigger was a script the consumer runs as a bare command. Council, the skills and a person at a
shell now all run `external-agents` that way, so the trigger has fired.
`scripts/check-plugin-manifest-presence.sh` rule 3 fails any plugin with a top-level `bin/`,
because claude.ai organization plugin sync rejects one (#5850).

## Decision

1. **`plugins/external-agents/bin/external-agents` is the plugin's one public command**, on the
Bash `PATH` while the plugin is enabled. Council's adapter runs `external-agents review <provider>`
and the skills run the same command. Nothing outside the plugin names its scripts or install path.
2. **The no-bin gate exempts this plugin by name.** Rule 3 skips `external-agents` only. Its test
proves every other plugin's `bin/` still fails.
3. **Organization sync skips external-agents.** The rest of the marketplace still syncs. The
plugin drives local CLIs, so it has nothing to do on claude.ai.
4. **A missing command is a skipped member, never a failure or a fallback answer.** When
`external-agents` is not on `PATH` (plugin disabled, or `PATH` delivery failed), council prints
`skipped (external-agents not enabled)`.

## Considered options

- **A council skill member, run from the main thread (design T1 option B).** Rejected by the owner
(Q62): it loads the skill once per member, and the output shape then depends on the model.
- **Invoke the script by `${CLAUDE_PLUGIN_ROOT}` path from council.** Rejected: council would have
to find another plugin's install path, the coupling this change removes.
- **Keep ADR 0021's marketplace-wide rejection.** Rejected: its recheck trigger fired, and no
`scripts/` path lets a script in another plugin call this one without that lookup.

## Consequences

- The exemption is one named plugin. Any other plugin that wants `bin/` needs its own record.
- `PATH` delivery is per session and can fail silently
([anthropics/claude-code#68066](https://github.com/anthropics/claude-code/issues/68066)). When it
fails, council's Codex member reports skipped instead of running.
- The component-stances table in `docs/plugin-philosophy.md` keeps `bin/` at Decline, with this
plugin named as the exception.

## Revisit triggers

- claude.ai organization sync accepts a plugin with a top-level `bin/`, so the exemption can become
the rule.
- A script can invoke a skill, or `review:brief-reviewer` gains the Skill tool.
- A second plugin needs a bare command on `PATH`.
Original file line number Diff line number Diff line change
@@ -0,0 +1,83 @@
# Run every external CLI through one runner over provider records, with per-use sandbox ceilings

- Status: accepted
- Date: 2026-11-21
- Refs: [#17954](https://github.com/melodic-software/claude-code-plugins/pull/17954) (runner, Codex
record), [#17967](https://github.com/melodic-software/claude-code-plugins/pull/17967) (Antigravity
record and its defaults); owner interview of 2026-11-20 and 2026-11-21 (Q20, Q31, Q42, Q51, Q59,
Q64, and "Opt-in write");
[ADR 0117](0117-replace-the-official-codex-plugin-with-one-external-agents-plugin-and-a-skill-per-cli.md)

## Context

The plugin hands work to CLIs that run in the user's repositories, with the user's credentials,
outside Claude Code's permission system. Each CLI enforces its own limits differently. A Codex run
whose writes were refused still exits 0. A run of agy (the Antigravity CLI) can fall back to
another mode and say so only in a notice. The owner asked for "the safest yet extensible and
configurable method".

## Decision

1. **Provider records are data, and one runner is the only code that starts a CLI.** Each CLI's
argv, modes, output shape, resume arguments, review kind and denial rules live in
`providers/<product>.yaml`, checked against one schema that rejects unknown keys. The runner in
`scripts/lib/runner.mjs` reads the record. It records every job in its own file (command, CLI
version, exit, duration, status) and keeps the newest 50 per repository.
2. **Each use runs in a sandbox mode, and the configured mode is both its default and its ceiling.**
Review and investigate are read-only. Task is write for Codex. For agy, task is read-only by
default, and write is one line in a personal or team file (`antigravity.uses.task.mode`, shipped
in #17967). The mode is passed on every run, resume included, with no approval prompt and no
escalation path, and a bypass flag is never passed. A request above the ceiling runs at the
ceiling, and the reply names the config key. Prompts never carry file contents.
3. **Exit 0 is not success.** A run is `ok` only when the CLI exits 0, its output shows a completed
turn and no error, its final message is non-empty, and none of its commands or writes was
denied. Any denial makes the run `blocked-by-mode`, even when the CLI then answers another way.
The answer still prints.
4. **Per-CLI limits are stated, not implied.**
- Codex: the sandbox is the only boundary. MCP servers and hooks configured in the repository
under review run outside it. The runner counts their calls and warns when the branch changes
`.codex/`.
- agy: the boundary is agy's sandbox plus agy's own review of commands. Write mode has no network
isolation. Read-only mode leaves agy only its file-reading tool. No mode restricts web access,
by owner decision.
5. **A repository never chooses what runs.** `<product>.binary_path` is honored only from an
untracked personal file, only as an absolute path, and only when the file name is the CLI's own.
6. **Job and breaker files stay in this plugin's data folder.** That folder is the caller's,
then the installed copy's own, then `CLAUDE_PLUGIN_DATA` only when the name is
`external-agents-*`, because the Bash environment can carry another plugin's value.
7. **Config lives in `external-agents.yaml` on the config-cascade layers.** These are the plugin
default, userConfig, the team file and the personal `.local` file. Nothing is kept under
`~/.claude`, and no model or flag is pinned. With no model configured, the runner passes none,
and the CLI runs on its own default model (agy included, by owner decision of 2026-11-21).

## Considered options

- **A runner per CLI.** Rejected: each would carry its own success rule, retention and breaker, and
the safety rules would drift between them.
- **A Bash runner.** Rejected (design T4): the shared libraries are `.mjs`, and one Node file runs
on Windows and POSIX alike.
- **Exit code alone as success.** Rejected: probes showed refused writes exiting 0.
- **Mark an agy run `ok` when it recovers from a denied command.** Rejected: a recovered run read as
blocked still shows its answer, while a blocked run read as done hides lost work.
- **An escalation opt-in (`--approve-for-me` or a config flag).** Rejected (Q31, Q59): no escalation
without a configured ceiling, and none was configured.
- **agy write by default, or agy's hard-wall sandbox setting.** Rejected: write mode has no network
isolation, so the owner made write opt-in. The hard wall hides user-local toolchains such as mise
and nvm (Q64).
- **`binary_path` from any config layer.** Rejected (security gate): a committed file in a reviewed
branch could pick the executable.

## Consequences

- An agy investigate run that tries one shell command ends with exit 3 and `blocked-by-mode`, even
when its answer is right.
- Codex flag drift is fixed in a record, not in code. `update` re-reads help when the CLI version
changes.
- A user who wants agy to write sets one config line and accepts that write mode has no network
isolation.

## Revisit triggers

- Codex starts exiting non-zero on sandbox denials, so exit code could carry success.
- agy gains network isolation in write mode, or a sandbox that keeps user-local toolchains.
- Codex runs repository MCP servers and hooks inside its sandbox.
1 change: 1 addition & 0 deletions docs/catalog.md
Original file line number Diff line number Diff line change
Expand Up @@ -117,6 +117,7 @@ plugin manifests and kept in sync by CI. Never hand-edit it; the category vocabu

- [`session-flow`](../plugins/session-flow): Session lifecycle: workflow (next stage), handoff (save-point, resume prompt), continue-in-background, keep-going (resume after a stall), find-handoff, clean-stop, retro and running-retro, audit-sessions, audit-friction, orient (where the session stands), orchestrate, reanchor (verify assumptions), reconcile (retire finished work), recommend-skills, tidy-work (.work tiers), step-away (run unattended, report on return), go-with-recommendations (accept after an evidence check), check, setup.
- [`multi-agent`](../plugins/multi-agent): Workflow and model-routing guidance for multi-agent work: assess (workflow, subagent or single context), route (the role map a workflow script reads from args, keeping fan-out stages off a frontier model), audit-defaults (rechecks bundled defaults against upstream, or sweeps the repo's model and workflow guidance, via a read-only drift-audit workflow), check (whether node resolves and the fetch gate is registered), and setup (writes a user, team or local layer after a preview and a yes).
- [`external-agents`](../plugins/external-agents): Hands tasks and reviews to other vendors' official coding-agent CLIs (Codex first) through their documented headless surfaces: one skill per CLI, one shared runner with per-use sandbox ceilings, job files and a breaker, and the external-agents command that review:council calls.

## Presentation

Expand Down
Loading
Loading