From f3f22b434f8ccf3ca3bf7bb8adc3dff7e035c54d Mon Sep 17 00:00:00 2001 From: Kyle Sexton <153232337+kyle-sexton@users.noreply.github.com> Date: Sat, 21 Nov 2026 12:09:47 -0500 Subject: [PATCH 1/7] feat(external-agents): add the Antigravity provider record, config keys and defaults Add providers/antigravity.yaml from agy 1.5.14 probes: read-only runs use a per-run settings file with agentMode "" (agy's default mode), since --mode accepts only accept-edits, auto and plan; soft-denies are read from the denied_actions JSON field, with the stderr notice as a second signal. Add the antigravity block to the team config schema and its bundled defaults (task write, investigate and review read-only, council member on). Refs #17786 Co-Authored-By: Claude Opus 5.5 --- ...at-external-agents-antigravity-d2818a6e.md | 7 +++ plugins/external-agents/defaults.json | 9 +++ .../providers/antigravity.yaml | 58 +++++++++++++++++++ .../schemas/external-agents.schema.json | 38 ++++++++++++ 4 files changed, 112 insertions(+) create mode 100644 .changes/external-agents/feat-external-agents-antigravity-d2818a6e.md create mode 100644 plugins/external-agents/providers/antigravity.yaml diff --git a/.changes/external-agents/feat-external-agents-antigravity-d2818a6e.md b/.changes/external-agents/feat-external-agents-antigravity-d2818a6e.md new file mode 100644 index 0000000000..7e4a64930b --- /dev/null +++ b/.changes/external-agents/feat-external-agents-antigravity-d2818a6e.md @@ -0,0 +1,7 @@ +--- +bump: minor +--- + +### Added + +- Google Antigravity (`agy`) support: a provider record, the `antigravity` keys in `/external-agents.yaml`, and bundled defaults (task runs write, investigate and review runs read-only, council member on). Read-only runs use agy's default approval mode through a per-run settings file, so writes and commands are refused and reported as blocked. diff --git a/plugins/external-agents/defaults.json b/plugins/external-agents/defaults.json index e717330823..17a9f8d23c 100644 --- a/plugins/external-agents/defaults.json +++ b/plugins/external-agents/defaults.json @@ -9,6 +9,15 @@ }, "council": { "enabled": true } }, + "antigravity": { + "timeout_seconds": 1800, + "uses": { + "task": { "mode": "write" }, + "investigate": { "mode": "read-only" }, + "review": { "mode": "read-only" } + }, + "council": { "enabled": true } + }, "breaker": { "cooldown_hours": 24 }, "jobs": { "keep": 50 } } diff --git a/plugins/external-agents/providers/antigravity.yaml b/plugins/external-agents/providers/antigravity.yaml new file mode 100644 index 0000000000..c47ac9c1ed --- /dev/null +++ b/plugins/external-agents/providers/antigravity.yaml @@ -0,0 +1,58 @@ +schema: 1 +product: antigravity +docs_index: https://antigravity.google/docs/cli +binary: + name: agy + candidates: + win32: + - "{LOCALAPPDATA}/agy/bin/agy.exe" + linux: + - "{HOME}/.local/bin/agy" + darwin: + - "{HOME}/.local/bin/agy" +version: + args: [--version] + sources: + standalone: github:google-antigravity/antigravity-cli +unset_model: skip-with-notice +model_flag: --model +effort_flag: --effort +always_args: [--output-format, json] +prompt: + form: "-p={prompt}" +resume: + args: [--conversation, "{thread}"] +output: + kind: json_envelope + status_field: status + success_value: SUCCESS + message_field: response + thread_field: conversation_id + error_field: error +review: + kind: diff_file + dir_arg: --add-dir +modes: + read-only: + enforcement: approval-denial + settings: + agentMode: "" + allowNonWorkspaceAccess: false + settings_arg: --settings + prompt_preface: "This run is read-only: shell commands and file writes are refused, so use only your file-reading tools." + write: + enforcement: sandbox + args: + run: [--mode, auto] + resume: [--mode, auto] + settings: + allowNonWorkspaceAccess: false + settings_arg: --settings + fallback_warning: + pattern: "--mode auto is not available" + severity: notice +soft_deny: + - kind: json_array_nonempty + field: denied_actions + - kind: stderr_substring + text: "permission that headless mode cannot prompt for" diff --git a/plugins/external-agents/schemas/external-agents.schema.json b/plugins/external-agents/schemas/external-agents.schema.json index 1455ba560b..6ecce17401 100644 --- a/plugins/external-agents/schemas/external-agents.schema.json +++ b/plugins/external-agents/schemas/external-agents.schema.json @@ -51,6 +51,44 @@ } } }, + "antigravity": { + "description": "Settings for the Google Antigravity CLI (agy).", + "type": "object", + "additionalProperties": false, + "properties": { + "model": { "type": "string", "description": "Model slug passed to the CLI, from `agy models`. Unset: the run is skipped with a notice naming this key." }, + "effort": { "type": "string", "description": "Reasoning effort passed to the CLI. Unset: the CLI's own setting." }, + "binary_path": { "type": "string", "description": "Absolute path to the CLI binary, tried before every other location." }, + "timeout_seconds": { "type": "integer", "minimum": 1, "default": 1800, "description": "Seconds before a run is stopped and recorded timed-out." }, + "update_hint": { "type": "string", "description": "Text shown beside the daily check's line when the CLI is behind its latest release, such as how your machines update it." }, + "uses": { + "type": "object", + "additionalProperties": false, + "properties": { + "task": { + "type": "object", + "additionalProperties": false, + "properties": { "mode": { "type": "string", "enum": ["read-only", "write"], "default": "write", "description": "Default and ceiling for task runs." } } + }, + "investigate": { + "type": "object", + "additionalProperties": false, + "properties": { "mode": { "type": "string", "enum": ["read-only", "write"], "default": "read-only", "description": "Default and ceiling for investigate runs." } } + }, + "review": { + "type": "object", + "additionalProperties": false, + "properties": { "mode": { "type": "string", "enum": ["read-only"], "default": "read-only", "description": "Reviews always run read-only." } } + } + } + }, + "council": { + "type": "object", + "additionalProperties": false, + "properties": { "enabled": { "type": "boolean", "default": true, "description": "Whether review:council may run this CLI as a member." } } + } + } + }, "breaker": { "type": "object", "additionalProperties": false, From d15a8564cf661453470b712d5008433726aa92b1 Mon Sep 17 00:00:00 2001 From: Kyle Sexton <153232337+kyle-sexton@users.noreply.github.com> Date: Sat, 21 Nov 2026 12:57:00 -0500 Subject: [PATCH 2/7] fix(external-agents): state the personal-layer rule for antigravity.binary_path Refs #17786 Co-Authored-By: Claude Opus 5.5 --- plugins/external-agents/schemas/external-agents.schema.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/plugins/external-agents/schemas/external-agents.schema.json b/plugins/external-agents/schemas/external-agents.schema.json index c5e42c6f7d..c5f9ffaed5 100644 --- a/plugins/external-agents/schemas/external-agents.schema.json +++ b/plugins/external-agents/schemas/external-agents.schema.json @@ -58,7 +58,7 @@ "properties": { "model": { "type": "string", "description": "Model slug passed to the CLI, from `agy models`. Unset: the run is skipped with a notice naming this key." }, "effort": { "type": "string", "description": "Reasoning effort passed to the CLI. Unset: the CLI's own setting." }, - "binary_path": { "type": "string", "description": "Absolute path to the CLI binary, tried before every other location." }, + "binary_path": { "type": "string", "description": "Absolute path to the CLI binary, tried before every other location. Read from the personal layer only: a value in the committed team file is ignored, since it picks the executable that runs." }, "timeout_seconds": { "type": "integer", "minimum": 1, "default": 1800, "description": "Seconds before a run is stopped and recorded timed-out." }, "update_hint": { "type": "string", "description": "Text shown beside the daily check's line when the CLI is behind its latest release, such as how your machines update it." }, "uses": { From e168cf9239e5691e55a7fe0343cd8418f6e915f8 Mon Sep 17 00:00:00 2001 From: Kyle Sexton <153232337+kyle-sexton@users.noreply.github.com> Date: Sat, 21 Nov 2026 15:13:29 -0500 Subject: [PATCH 3/7] fix(external-agents): flag agy workspace config in reviews; correct the schema's unset-model text A reviewed branch that changes .agents/ (workspace hooks, agents) now gets the pre-launch notice. Refs #17786 Co-Authored-By: Claude Opus 5.5 --- plugins/external-agents/providers/antigravity.yaml | 1 + plugins/external-agents/schemas/external-agents.schema.json | 2 +- 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/plugins/external-agents/providers/antigravity.yaml b/plugins/external-agents/providers/antigravity.yaml index c47ac9c1ed..0cb14db38d 100644 --- a/plugins/external-agents/providers/antigravity.yaml +++ b/plugins/external-agents/providers/antigravity.yaml @@ -32,6 +32,7 @@ output: review: kind: diff_file dir_arg: --add-dir + config_paths: [.agents/] modes: read-only: enforcement: approval-denial diff --git a/plugins/external-agents/schemas/external-agents.schema.json b/plugins/external-agents/schemas/external-agents.schema.json index c5f9ffaed5..d359b00277 100644 --- a/plugins/external-agents/schemas/external-agents.schema.json +++ b/plugins/external-agents/schemas/external-agents.schema.json @@ -2,7 +2,7 @@ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://raw.githubusercontent.com/melodic-software/claude-code-plugins/main/plugins/external-agents/schemas/external-agents.schema.json", "title": "External-agents team config", - "description": "Schema for a repository's /external-agents.yaml ( defaults to docs/conventions): the team layer of the external-agents plugin. A personal /external-agents.local.yaml overrides it per key. Layers: docs/contracts/config-cascade/README.md. Each product is one top-level key holding the same per-product keys; an unset model, effort or profile leaves the CLI's own configuration in charge.", + "description": "Schema for a repository's /external-agents.yaml ( defaults to docs/conventions): the team layer of the external-agents plugin. A personal /external-agents.local.yaml overrides it per key. Layers: docs/contracts/config-cascade/README.md. Each product is one top-level key holding its per-product keys; an unset effort or profile leaves the CLI's own configuration in charge, and an unset model does too unless the product's model description says the run is skipped.", "type": "object", "additionalProperties": false, "required": ["schema"], From 93f5759294e371e7a16ab25c497ab4bc511ea8bb Mon Sep 17 00:00:00 2001 From: Kyle Sexton <153232337+kyle-sexton@users.noreply.github.com> Date: Sat, 21 Nov 2026 15:28:36 -0500 Subject: [PATCH 4/7] fix(external-agents): pass --disable-slash-commands to every agy run Probed on agy 1.5.14: a prompt starting with /models expanded into a refused command without the flag and reached the model as text with it. Refs #17786 Co-Authored-By: Claude Opus 5.5 --- plugins/external-agents/providers/antigravity.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/plugins/external-agents/providers/antigravity.yaml b/plugins/external-agents/providers/antigravity.yaml index 0cb14db38d..49067eb524 100644 --- a/plugins/external-agents/providers/antigravity.yaml +++ b/plugins/external-agents/providers/antigravity.yaml @@ -17,7 +17,7 @@ version: unset_model: skip-with-notice model_flag: --model effort_flag: --effort -always_args: [--output-format, json] +always_args: [--output-format, json, --disable-slash-commands] prompt: form: "-p={prompt}" resume: From a9b0f9f927612918a587120f34fd45403d9c92bd Mon Sep 17 00:00:00 2001 From: Kyle Sexton <153232337+kyle-sexton@users.noreply.github.com> Date: Sat, 21 Nov 2026 15:49:09 -0500 Subject: [PATCH 5/7] feat(external-agents): cache agy help and model list on update Refs #17786 Co-Authored-By: Claude Opus 5.5 --- plugins/external-agents/providers/antigravity.yaml | 3 +++ 1 file changed, 3 insertions(+) diff --git a/plugins/external-agents/providers/antigravity.yaml b/plugins/external-agents/providers/antigravity.yaml index 49067eb524..4b6b2effab 100644 --- a/plugins/external-agents/providers/antigravity.yaml +++ b/plugins/external-agents/providers/antigravity.yaml @@ -1,6 +1,9 @@ schema: 1 product: antigravity docs_index: https://antigravity.google/docs/cli +help: + agy: [--help] + models: [models] binary: name: agy candidates: From d07e21a4f1b5810ee968d0dd3985f7693dfe855a Mon Sep 17 00:00:00 2001 From: Kyle Sexton <153232337+kyle-sexton@users.noreply.github.com> Date: Sat, 21 Nov 2026 16:13:13 -0500 Subject: [PATCH 6/7] feat(external-agents): add the /external-agents:antigravity skill Drives external-agents run, review, status, result, cancel and update for agy, on the Codex skill's shape. Adds the agy prerequisite with its daily latest-release check, and a read-only preface that names the refused search commands (live: investigate ok, a write attempt blocked-by-mode). Refs #17786 Co-Authored-By: Claude Opus 5.5 --- ...at-external-agents-antigravity-d2818a6e.md | 2 +- plugins/external-agents/README.md | 9 +- plugins/external-agents/prerequisites.json | 25 ++++ .../providers/antigravity.yaml | 2 +- .../skills/antigravity/SKILL.md | 110 ++++++++++++++++++ .../skills/antigravity/reference/jobs.md | 25 ++++ .../skills/antigravity/reference/routing.md | 28 +++++ .../skills/antigravity/reference/run.md | 62 ++++++++++ .../skills/antigravity/reference/update.md | 43 +++++++ 9 files changed, 301 insertions(+), 5 deletions(-) create mode 100644 plugins/external-agents/skills/antigravity/SKILL.md create mode 100644 plugins/external-agents/skills/antigravity/reference/jobs.md create mode 100644 plugins/external-agents/skills/antigravity/reference/routing.md create mode 100644 plugins/external-agents/skills/antigravity/reference/run.md create mode 100644 plugins/external-agents/skills/antigravity/reference/update.md diff --git a/.changes/external-agents/feat-external-agents-antigravity-d2818a6e.md b/.changes/external-agents/feat-external-agents-antigravity-d2818a6e.md index 7e4a64930b..b8abba7bc4 100644 --- a/.changes/external-agents/feat-external-agents-antigravity-d2818a6e.md +++ b/.changes/external-agents/feat-external-agents-antigravity-d2818a6e.md @@ -4,4 +4,4 @@ bump: minor ### Added -- Google Antigravity (`agy`) support: a provider record, the `antigravity` keys in `/external-agents.yaml`, and bundled defaults (task runs write, investigate and review runs read-only, council member on). Read-only runs use agy's default approval mode through a per-run settings file, so writes and commands are refused and reported as blocked. +- Google Antigravity (`agy`) support: a provider record, the `antigravity` keys in `/external-agents.yaml`, bundled defaults (task runs write, investigate and review runs read-only, council member on), and the agy prerequisite with its daily latest-release check. The `/external-agents:antigravity` skill drives the `external-agents` command for agy the way `/external-agents:codex` does for Codex. Read-only runs use agy's default approval mode through a per-run settings file, so writes and commands are refused and reported as blocked; write runs use agy's auto mode, whose limit is agy's sandbox plus agy's own review. Every agy run passes `--disable-slash-commands`, so a prompt starting with `/` reaches the model as text, and a review warns when the branch changes agy's `.agents/` workspace configuration. agy runs are skipped until `antigravity.model` is set. diff --git a/plugins/external-agents/README.md b/plugins/external-agents/README.md index e348c070ff..9bae01163c 100644 --- a/plugins/external-agents/README.md +++ b/plugins/external-agents/README.md @@ -11,7 +11,7 @@ none of its text or code is copied). ## Status In progress: `run`, `review`, `status`, `result`, `cancel` and `update` work, and -`/external-agents:codex` drives them. +`/external-agents:codex` and `/external-agents:antigravity` drive them. ## Surface @@ -20,6 +20,8 @@ In progress: `run`, `review`, `status`, `result`, `cancel` and `update` work, an outside this plugin reads its install path or its scripts. - **`/external-agents:codex`**: hands a task, an investigation or a review to Codex, in the foreground or background, and reads back, resumes or cancels its jobs. +- **`/external-agents:antigravity`**: the same for Google's Antigravity CLI (`agy`). agy runs + only with a model configured (`antigravity.model`). - No hooks, no agents and no `commands/` folder: nothing runs until you or a council run asks. claude.ai organization plugin sync skips this plugin, because it ships a top-level `bin/` @@ -37,8 +39,9 @@ anyway. gitignored), `` being the repository's convention home, by default `docs/conventions`. Keys are in [`schemas/external-agents.schema.json`](schemas/external-agents.schema.json); layers and precedence are in the -[config-cascade contract](../../docs/contracts/config-cascade/README.md). An unset model, effort or -profile leaves the CLI's own configuration in charge. +[config-cascade contract](../../docs/contracts/config-cascade/README.md). An unset effort or profile +leaves the CLI's own configuration in charge, and so does an unset model, except for agy, whose +runs are skipped until `antigravity.model` is set. ## Job files diff --git a/plugins/external-agents/prerequisites.json b/plugins/external-agents/prerequisites.json index 91ecf8a7ef..b541a2bcf3 100644 --- a/plugins/external-agents/prerequisites.json +++ b/plugins/external-agents/prerequisites.json @@ -41,6 +41,31 @@ "install": { "docs": "https://github.com/openai/codex" } + }, + { + "id": "agy", + "kind": "cli", + "need": "optional", + "for": [ + "plugin" + ], + "detect": { + "any": [ + "agy" + ], + "version": { + "args": [ + "--version" + ], + "pattern": "([0-9]+(?:\\.[0-9]+)+)", + "min": "0", + "latest": "github:google-antigravity/antigravity-cli" + } + }, + "degrade": "Without the Antigravity CLI (agy), Antigravity runs are reported unavailable and council's Antigravity member is skipped; other CLIs are unaffected.", + "install": { + "docs": "https://antigravity.google/docs/install" + } } ] } diff --git a/plugins/external-agents/providers/antigravity.yaml b/plugins/external-agents/providers/antigravity.yaml index 4b6b2effab..d634e72cbf 100644 --- a/plugins/external-agents/providers/antigravity.yaml +++ b/plugins/external-agents/providers/antigravity.yaml @@ -43,7 +43,7 @@ modes: agentMode: "" allowNonWorkspaceAccess: false settings_arg: --settings - prompt_preface: "This run is read-only: shell commands and file writes are refused, so use only your file-reading tools." + prompt_preface: "This run is read-only: every shell command, search commands such as grep, find and ls included, and every file write is refused. Read files by path with your file-reading tool." write: enforcement: sandbox args: diff --git a/plugins/external-agents/skills/antigravity/SKILL.md b/plugins/external-agents/skills/antigravity/SKILL.md new file mode 100644 index 0000000000..fa3f9667a9 --- /dev/null +++ b/plugins/external-agents/skills/antigravity/SKILL.md @@ -0,0 +1,110 @@ +--- +description: "Hands a task, investigation or review to Google's Antigravity CLI (agy, Gemini models) and reads back its jobs. Use when the user asks for Gemini or Antigravity: 'ask Gemini', 'have Gemini do X', 'Gemini second opinion', 'Antigravity review of this branch', 'run this through agy', 'is the Gemini job done', 'cancel the agy run', 'is agy ready', 'update antigravity'. A multi-reviewer panel is /review:council." +argument-hint: "[run |review --base |status []|result |cancel |update]" +user-invocable: true +disable-model-invocation: false +allowed-tools: + - "Bash(external-agents run antigravity:*)" + - "Bash(external-agents review antigravity:*)" + - "Bash(external-agents status:*)" + - "Bash(external-agents result:*)" + - "Bash(external-agents cancel:*)" + - "Bash(external-agents update antigravity:*)" +shell: bash +metadata: + workflow-stage: implement + summary: Hand tasks, investigations and reviews to the Antigravity CLI and read back its jobs +--- + +# Antigravity + +**Arguments.** `[run |review --base |status []|result |cancel |update]`. +A bare request that is not one of the other actions is `run`. + +This skill drives the plugin's `external-agents` command, which is on the Bash `PATH` while the +plugin is enabled. The command is the only thing that starts agy; never call `agy` yourself, and +never look up the plugin's install path. Delegate only when the user asks for Gemini or +Antigravity. + +## Actions + +| Action | Command | Read | +|---|---|---| +| `run` (default): a task (may write) or an investigation (read-only) | `external-agents run antigravity --use task\|investigate --prompt-file ` | [reference/run.md](reference/run.md) | +| `review`: agy reviews this branch, read-only | `external-agents review antigravity --base [--brief-file ]` | [reference/run.md](reference/run.md#review) | +| `status`, `result`, `cancel` | `external-agents status []`, `result `, `cancel ` | [reference/jobs.md](reference/jobs.md) | +| `update`: readiness, CLI facts, version and routing check | `external-agents update antigravity` | [reference/update.md](reference/update.md) | +| Choosing a model or effort | none: config keys only | [reference/routing.md](reference/routing.md) | + +## Reporting a run + +- **First reply line:** `Mode: ()`, taken from the job, never from what was asked: the + `mode:` line of `external-agents status ` (the job id is the `job: ` line on stderr). + A review is always `Mode: read-only (review)`. When the mode ceiling lowered a write request, say + so and name the config key the notice names. +- Then the command's first stdout line, then agy's final message verbatim. That message is agy's + answer, not yours: relay it, and add your own reading only below it, labeled as yours. +- Exit codes (`scripts/lib/runner.mjs:12`): `0` ok, `1` failed, `2` usage or refused, `3` blocked + by the mode, `4` agy unavailable or skipped. On `1`, `2` or `4`, report the first line and the + CLI's error and stop: never do the task yourself in agy's place. On `4`, point the user to + `external-agents update antigravity`. + +## Prompts + +Write the prompt with the Write tool to a file in a gitignored scratch folder (this repository's +convention, else the session scratchpad) and pass it with `--prompt-file`; the command keeps its +own copy in the job folder. Name the files and paths agy should read; never paste file contents, +diffs or logs into the prompt. For an investigation, name the paths: a read-only agy run reads +files by path and cannot search or list directories. + +## Background runs + +Run the same command with the Bash tool's `run_in_background`; you are notified when it exits, so +do not poll. The job id prints only at the end, so while it runs, find it with bare +`external-agents status`. Stop a run with `external-agents cancel `, which stops agy's whole +process tree; stopping the background Bash task alone may leave agy running. + +## Next + +`/review:council` for a ranked, multi-reviewer review of the same change, with agy as one member. + +## Gotchas + +- **No model configured means no run.** agy runs are skipped (`antigravity: skipped (...)`, exit + `4`) until `antigravity.model` is set in `/external-agents.yaml` or `.local.yaml`; the + notice names the key. Relay it and stop; never pick a model for the user. Model slugs come from + `models.txt` in the `cli facts:` folder `update` prints. +- **A refused action makes the run `blocked-by-mode`, even with a full answer.** agy keeps going + after a refusal and may still answer well; the command records the run `blocked-by-mode`, exits + `3` and prints the answer. Relay the answer, name the refused actions from the first line, and + never report a task done. +- **A write task's limit is agy's sandbox plus agy's own review.** `--mode auto` keeps commands + in agy's terminal sandbox, but its review lets commands it judges safe and reversible run outside + it ([Terminal sandbox](https://antigravity.google/docs/sandbox/)). Sandboxed commands have no + network by default, but a write task on WSL (agy 1.5.14) reached the internet with and without + `--sandbox`, so treat write mode as having network access. Never ask agy to push, open or + merge pull requests, or run `gh` or `az`; Claude Code stays the only actor for those. +- **Check the work, not the warning.** agy may print `--mode auto is not available ...; + continuing in the default mode` (relayed as a `notice:`) and still run in auto mode, writes + included. Before reporting a task done, check that its files exist; trust neither the notice nor + the exit code alone. +- **On Windows, auto-mode commands cannot write files** (`EPERM`, observed on agy 1.5.14, also + with an added directory), so a build or test that writes output fails there. For those, run + from WSL. +- **Workspace configuration from the branch loads into agy.** agy reads hooks from + `.agents/hooks.json` in the workspace ([Hooks](https://antigravity.google/docs/hooks/)), plus + the user's `~/.gemini/config/hooks.json` and installed agy plugins. The command prints a + `notice:` when a reviewed change touches `.agents/`; relay it before the findings. +- **The breaker refuses runs after an unavailable-class failure** until the time it prints. + `external-agents update antigravity` closes it once agy is ready again; do not retry in a loop. +- **`antigravity.binary_path` is read only from an untracked personal file** + (`/external-agents.local.yaml`, absolute path, file named `agy`, or `agy.exe` on + Windows). Set anywhere else, it is ignored with a `notice: config:` line; relay that notice. +- **Plugin data directory.** Job files, logs, the breaker and the CLI-facts cache live in this + plugin's data directory, which the command works out for itself; never pass or set + `CLAUDE_PLUGIN_DATA`. A `notice:` saying another plugin's `CLAUDE_PLUGIN_DATA` is not used is + expected. A checkout that is not installed refuses to run until `CLAUDE_PLUGIN_DATA` names a + directory starting with `external-agents-` (see the plugin README's Job files section). +- **CLI flags come from the CLI.** When a question turns on what an agy flag or subcommand does, + read the help `update` captured (`agy.txt` in its `cli facts:` folder), not this skill and not + memory. diff --git a/plugins/external-agents/skills/antigravity/reference/jobs.md b/plugins/external-agents/skills/antigravity/reference/jobs.md new file mode 100644 index 0000000000..fa589c6bb3 --- /dev/null +++ b/plugins/external-agents/skills/antigravity/reference/jobs.md @@ -0,0 +1,25 @@ +# Jobs: status, result, cancel + +Every run and review writes one job file when agy starts and updates it when agy ends. Jobs are +grouped per repository (all worktrees of one repository share a group; outside a repository, one +`no-repo` group), and the command lists, reads and cancels only the current directory's group. +The newest `jobs.keep` finished jobs per group are kept. Codex and agy jobs share the group. + +```bash +external-agents status # every job in this repository, newest first +external-agents status # one job: status line, then id, use, mode, times, exit code, thread_id, CLI version, paths +external-agents result # status line, then agy's final message +external-agents cancel # stop a running job and its process tree +``` + +- **`status`** settles stale jobs: a `running` job whose process is gone is rewritten + `failed (process exited)`. Use `status ` for the `mode:` the reply's first line needs and + the `thread_id` (agy's conversation id) a resume needs. +- **`result`** exits like the run did (`0`, `1` or `3`), and `1` while the job is still running; + report a running job as running, not as failed. +- **`cancel`** refuses when the job is not running, or when it cannot confirm the recorded pid is + still that job's process; nothing is killed then. A cancelled job is recorded `cancelled`. +- **Paths.** `status ` prints `log_path` (agy's JSON result) and `final_message_path`. Read + the final message; open the log only to explain a failure or a refused action, and quote only + the lines that matter. Job files can hold prompts and output: never copy them out of the + plugin's data directory, into a commit, an issue or a pull request. diff --git a/plugins/external-agents/skills/antigravity/reference/routing.md b/plugins/external-agents/skills/antigravity/reference/routing.md new file mode 100644 index 0000000000..f761db4dc9 --- /dev/null +++ b/plugins/external-agents/skills/antigravity/reference/routing.md @@ -0,0 +1,28 @@ +# Routing: model and effort + +This skill holds no model names and no effort defaults. agy needs a model for every run: one the +user names for the run, or `antigravity.model` from config; with neither, the run is skipped. An +effort passes only when `antigravity.effort` is set. Which model and effort each agent role in a +multi-agent run uses is `/multi-agent:route`'s config, not this skill's. + +agy's model slugs name a thinking level (for example a `-medium` suffix), and agy also takes +`--effort`. Which one wins when both are given is not documented; when the user sets both, say so +and suggest setting only the slug. + +When the user asks which Gemini model or effort to use, or `update` prints `routing: due`, read the +sources below and answer from them, citing the section: + +- The models this agy version offers: `models.txt` in the `cli facts:` folder from + `external-agents update antigravity`. +- Index of the Antigravity CLI docs, to find a page that moved: + [Get started](https://antigravity.google/docs/cli). +- Which models exist and how to pick one: + [Choose a model § Choose a model](https://antigravity.google/docs/models/#choose-a-model) and + [§ Reasoning model](https://antigravity.google/docs/models/#reasoning-model). +- Thinking levels and effort: + [Choose a model § Select a model](https://antigravity.google/docs/models/#select-a-model) and + [Effort command](https://antigravity.google/docs/cli/commands/effort). + +A recommendation goes to the user as a config change for them to make (`antigravity.model`, +`antigravity.effort`), with the section it rests on. On `routing: due`, the check is the one in +[update.md § Routing refresh](update.md#routing-refresh). diff --git a/plugins/external-agents/skills/antigravity/reference/run.md b/plugins/external-agents/skills/antigravity/reference/run.md new file mode 100644 index 0000000000..844eb7f654 --- /dev/null +++ b/plugins/external-agents/skills/antigravity/reference/run.md @@ -0,0 +1,62 @@ +# Run and review + +## Run + +```bash +external-agents run antigravity --use --prompt-file [--mode read-only|write] [--model ] [--resume |--last] +``` + +- **Pick the use from the request.** `task` when agy should change files; `investigate` when it + should only read and answer. The use's configured mode (`antigravity.uses..mode`, bundled + values in the plugin's `defaults.json`) is both the default and the ceiling. Pass + `--mode read-only` to run a task without writes; `--mode write` never lifts a read-only ceiling. +- **Model.** agy needs one: with neither `--model` nor `antigravity.model` set, the run is skipped + with a notice naming the key, exit `4`. Pass `--model` only when the user names one for this run; + otherwise rely on `antigravity.model`. `antigravity.effort` passes `--effort` when set. Choosing + one: [routing.md](routing.md). +- **Resume** continues an agy conversation this plugin started. `--resume ` takes a + `thread_id` from `external-agents status `; a thread that is not in this repository's job + files is refused. `--last` resumes this plugin's newest job with a thread in this repository. A + resumed run gets the current use's mode again. +- **Timeout.** A run that passes `antigravity.timeout_seconds` is stopped and recorded + `timed-out`. +- agy works in the current directory. Run from the repository or worktree agy should work in. + +### How each mode holds + +- **read-only** runs agy's default mode with a per-run settings file; agy refuses every shell + command and file write it would have to ask about, and the command records each refusal from + agy's `denied_actions` field. The prompt gets a preface saying so, so name the files to read. +- **write** runs `--mode auto` with a per-run settings file that turns off agy's access beyond the + workspace (`allowNonWorkspaceAccess: false`). Its limits are in the hub's gotchas: agy's sandbox + plus agy's own review (which let a write outside the workspace through on WSL), network access, + and no file writes from commands on Windows. + +### First stdout line + +`antigravity: ` with a parenthesized reason and details when there are any, such as the +refused actions and the mode that refused them. Statuses: `ok`, `failed`, `blocked-by-mode`, +`timed-out`, `cancelled`. A run stopped before agy started prints `antigravity: failed (...)`, +`antigravity: skipped (...)`, `antigravity: unavailable: ...` or `antigravity: refused: ...`. +agy's final message follows the line whenever agy produced one. + +stderr carries `job: ` and any `notice:` lines (mode ceiling, config problems, agy's own +warnings, a foreign `CLAUDE_PLUGIN_DATA`). Relay every notice. + +## Review + +```bash +external-agents review antigravity --base [--brief-file ] [--model ] +``` + +- Always read-only, whatever any config says. `` must be a commit that shares history with + `HEAD`; the review covers the merge base with it up to `HEAD`. +- The command writes the diff into the job's own folder, gives agy read access to that folder + only, and names the file in the prompt; agy never runs `git`. +- `--brief-file` adds review instructions (a focus, a threat model). Write it like a prompt file: + paths and questions, no pasted contents. +- First line: `antigravity: ran (...)`, `antigravity: failed (...)` or + `antigravity: skipped (...)`; this is the same line council reads. Findings follow `ran` only. + Exit `0` for `ran`, else `1`, `2` or `4`. +- A `notice:` about `.agents/` means the branch carries agy workspace configuration (hooks) that + loads into the review: relay it before the findings. diff --git a/plugins/external-agents/skills/antigravity/reference/update.md b/plugins/external-agents/skills/antigravity/reference/update.md new file mode 100644 index 0000000000..b73f176aab --- /dev/null +++ b/plugins/external-agents/skills/antigravity/reference/update.md @@ -0,0 +1,43 @@ +# Update + +```bash +external-agents update antigravity +``` + +Checks that agy is ready and refreshes what the plugin knows about it. It never installs or +upgrades anything: a missing agy is installed through the user's dotfiles install, and an upgrade +follows the hint the user set in `antigravity.update_hint`. + +Run it when a run reports agy unavailable or the breaker open, when the user asks whether agy is +ready, and after an agy upgrade. Exit `0` when agy is ready, `4` when it is missing or logged out. + +## Reading the output + +One line per check; act on each: + +| Line | What to do | +|---|---| +| `antigravity: ready` | Ready; the breaker is closed. `ready (check: ...)` names checks below that need a look | +| `antigravity: unavailable: ...` | Relay it: it says what to install or log in to. Stop | +| `version:`, `login:` | Report them when the user asked about readiness | +| `cli facts: ` | `agy.txt` (agy's help) and `models.txt` (`agy models`) for this version. Read them for any flag, subcommand or model question; then do the model check below | +| `version check:` | A newer release: tell the user once | +| `docs index:` | `unreachable`: say the routing pointers could not be checked | +| `routing: due; re-read the routing pointers` | Do the routing refresh below | +| `routing: checked earlier today` | Nothing | +| `config keys: none passed` | Expected: agy takes flags, not config keys | + +## Model check + +Read `antigravity.model` from `/external-agents.yaml` and `/external-agents.local.yaml` +(the local file wins). When it is set and its slug is not a line's first column in `models.txt`, +tell the user the configured model is not in this agy version's list, name the key, and quote the +closest slugs from the file. Unset: say nothing here; a run reports the skip itself. Change no +config file yourself. + +## Routing refresh + +On `routing: due`, fetch the pages [routing.md](routing.md) lists and compare them with the model +and effort the user configured (`antigravity.model` and `antigravity.effort`). When a configured +model is marked retired or deprecated there, tell the user, name the config key and link the page. +Change no config file yourself. With nothing configured, there is nothing to compare: say nothing. From 4c26fd83ac1794e970222c7788e19318586ed67b Mon Sep 17 00:00:00 2001 From: Kyle Sexton <153232337+kyle-sexton@users.noreply.github.com> Date: Sat, 21 Nov 2026 17:08:16 -0500 Subject: [PATCH 7/7] feat(external-agents): run agy on its own default model and make agy writes opt-in With no antigravity.model set, agy now runs on the model it ships instead of being skipped (owner, 2026-11-21: use agy's default). Every agy use is read-only by default; writes need antigravity.uses.task.mode: write, because agy's write mode has no network isolation (owner: "Opt-in write"). Refs #17786 Co-Authored-By: Claude Opus 5.5 --- .../feat-external-agents-antigravity-d2818a6e.md | 2 +- plugins/external-agents/README.md | 8 ++++---- plugins/external-agents/defaults.json | 2 +- plugins/external-agents/providers/antigravity.yaml | 2 +- .../schemas/external-agents.schema.json | 6 +++--- plugins/external-agents/skills/antigravity/SKILL.md | 8 ++++---- .../skills/antigravity/reference/routing.md | 6 +++--- .../skills/antigravity/reference/run.md | 10 +++++----- .../skills/antigravity/reference/update.md | 4 ++-- 9 files changed, 24 insertions(+), 24 deletions(-) diff --git a/.changes/external-agents/feat-external-agents-antigravity-d2818a6e.md b/.changes/external-agents/feat-external-agents-antigravity-d2818a6e.md index b8abba7bc4..aabcb7dfc2 100644 --- a/.changes/external-agents/feat-external-agents-antigravity-d2818a6e.md +++ b/.changes/external-agents/feat-external-agents-antigravity-d2818a6e.md @@ -4,4 +4,4 @@ bump: minor ### Added -- Google Antigravity (`agy`) support: a provider record, the `antigravity` keys in `/external-agents.yaml`, bundled defaults (task runs write, investigate and review runs read-only, council member on), and the agy prerequisite with its daily latest-release check. The `/external-agents:antigravity` skill drives the `external-agents` command for agy the way `/external-agents:codex` does for Codex. Read-only runs use agy's default approval mode through a per-run settings file, so writes and commands are refused and reported as blocked; write runs use agy's auto mode, whose limit is agy's sandbox plus agy's own review. Every agy run passes `--disable-slash-commands`, so a prompt starting with `/` reaches the model as text, and a review warns when the branch changes agy's `.agents/` workspace configuration. agy runs are skipped until `antigravity.model` is set. +- Google Antigravity (`agy`) support: a provider record, the `antigravity` keys in `/external-agents.yaml`, bundled defaults (every use read-only, council member on), and the agy prerequisite with its daily latest-release check. The `/external-agents:antigravity` skill drives the `external-agents` command for agy the way `/external-agents:codex` does for Codex. Read-only runs use agy's default approval mode through a per-run settings file, so writes and commands are refused and reported as blocked. Writes are opt-in through `antigravity.uses.task.mode: write`, because agy's auto mode, whose limit is agy's sandbox plus agy's own review, has no network isolation. With no `antigravity.model` set, agy's own default model runs. Every agy run passes `--disable-slash-commands`, so a prompt starting with `/` reaches the model as text, and a review warns when the branch changes agy's `.agents/` workspace configuration. diff --git a/plugins/external-agents/README.md b/plugins/external-agents/README.md index 9bae01163c..ab1048a664 100644 --- a/plugins/external-agents/README.md +++ b/plugins/external-agents/README.md @@ -21,7 +21,8 @@ In progress: `run`, `review`, `status`, `result`, `cancel` and `update` work, an - **`/external-agents:codex`**: hands a task, an investigation or a review to Codex, in the foreground or background, and reads back, resumes or cancels its jobs. - **`/external-agents:antigravity`**: the same for Google's Antigravity CLI (`agy`). agy runs - only with a model configured (`antigravity.model`). + read-only unless you opt in to writes with `antigravity.uses.task.mode: write`, because agy's + write mode has no network isolation. - No hooks, no agents and no `commands/` folder: nothing runs until you or a council run asks. claude.ai organization plugin sync skips this plugin, because it ships a top-level `bin/` @@ -39,9 +40,8 @@ anyway. gitignored), `` being the repository's convention home, by default `docs/conventions`. Keys are in [`schemas/external-agents.schema.json`](schemas/external-agents.schema.json); layers and precedence are in the -[config-cascade contract](../../docs/contracts/config-cascade/README.md). An unset effort or profile -leaves the CLI's own configuration in charge, and so does an unset model, except for agy, whose -runs are skipped until `antigravity.model` is set. +[config-cascade contract](../../docs/contracts/config-cascade/README.md). An unset model, effort or +profile leaves the CLI's own configuration in charge. ## Job files diff --git a/plugins/external-agents/defaults.json b/plugins/external-agents/defaults.json index 17a9f8d23c..201e2e8f81 100644 --- a/plugins/external-agents/defaults.json +++ b/plugins/external-agents/defaults.json @@ -12,7 +12,7 @@ "antigravity": { "timeout_seconds": 1800, "uses": { - "task": { "mode": "write" }, + "task": { "mode": "read-only" }, "investigate": { "mode": "read-only" }, "review": { "mode": "read-only" } }, diff --git a/plugins/external-agents/providers/antigravity.yaml b/plugins/external-agents/providers/antigravity.yaml index d634e72cbf..2075becc39 100644 --- a/plugins/external-agents/providers/antigravity.yaml +++ b/plugins/external-agents/providers/antigravity.yaml @@ -17,7 +17,7 @@ version: args: [--version] sources: standalone: github:google-antigravity/antigravity-cli -unset_model: skip-with-notice +unset_model: cli-default model_flag: --model effort_flag: --effort always_args: [--output-format, json, --disable-slash-commands] diff --git a/plugins/external-agents/schemas/external-agents.schema.json b/plugins/external-agents/schemas/external-agents.schema.json index d359b00277..b9d41d3e27 100644 --- a/plugins/external-agents/schemas/external-agents.schema.json +++ b/plugins/external-agents/schemas/external-agents.schema.json @@ -2,7 +2,7 @@ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://raw.githubusercontent.com/melodic-software/claude-code-plugins/main/plugins/external-agents/schemas/external-agents.schema.json", "title": "External-agents team config", - "description": "Schema for a repository's /external-agents.yaml ( defaults to docs/conventions): the team layer of the external-agents plugin. A personal /external-agents.local.yaml overrides it per key. Layers: docs/contracts/config-cascade/README.md. Each product is one top-level key holding its per-product keys; an unset effort or profile leaves the CLI's own configuration in charge, and an unset model does too unless the product's model description says the run is skipped.", + "description": "Schema for a repository's /external-agents.yaml ( defaults to docs/conventions): the team layer of the external-agents plugin. A personal /external-agents.local.yaml overrides it per key. Layers: docs/contracts/config-cascade/README.md. Each product is one top-level key holding its per-product keys; an unset model, effort or profile leaves the CLI's own configuration in charge.", "type": "object", "additionalProperties": false, "required": ["schema"], @@ -56,7 +56,7 @@ "type": "object", "additionalProperties": false, "properties": { - "model": { "type": "string", "description": "Model slug passed to the CLI, from `agy models`. Unset: the run is skipped with a notice naming this key." }, + "model": { "type": "string", "description": "Model slug passed to the CLI, from `agy models`. Unset: no `--model` is passed and agy uses its own default." }, "effort": { "type": "string", "description": "Reasoning effort passed to the CLI. Unset: the CLI's own setting." }, "binary_path": { "type": "string", "description": "Absolute path to the CLI binary, tried before every other location. Read from the personal layer only: a value in the committed team file is ignored, since it picks the executable that runs." }, "timeout_seconds": { "type": "integer", "minimum": 1, "default": 1800, "description": "Seconds before a run is stopped and recorded timed-out." }, @@ -68,7 +68,7 @@ "task": { "type": "object", "additionalProperties": false, - "properties": { "mode": { "type": "string", "enum": ["read-only", "write"], "default": "write", "description": "Default and ceiling for task runs." } } + "properties": { "mode": { "type": "string", "enum": ["read-only", "write"], "default": "read-only", "description": "Default and ceiling for task runs. Write is opt-in: agy's write mode has no network isolation (ADR 0119)." } } }, "investigate": { "type": "object", diff --git a/plugins/external-agents/skills/antigravity/SKILL.md b/plugins/external-agents/skills/antigravity/SKILL.md index fa3f9667a9..e14042cc3c 100644 --- a/plugins/external-agents/skills/antigravity/SKILL.md +++ b/plugins/external-agents/skills/antigravity/SKILL.md @@ -70,10 +70,10 @@ process tree; stopping the background Bash task alone may leave agy running. ## Gotchas -- **No model configured means no run.** agy runs are skipped (`antigravity: skipped (...)`, exit - `4`) until `antigravity.model` is set in `/external-agents.yaml` or `.local.yaml`; the - notice names the key. Relay it and stop; never pick a model for the user. Model slugs come from - `models.txt` in the `cli facts:` folder `update` prints. +- **Write is opt-in.** Every use runs read-only until the user sets + `antigravity.uses.task.mode: write` in `/external-agents.yaml` or `.local.yaml`, because + agy's write mode has no network isolation (next gotchas). A task asked for while the ceiling is + read-only runs read-only; relay the notice naming that key, and never set it yourself. - **A refused action makes the run `blocked-by-mode`, even with a full answer.** agy keeps going after a refusal and may still answer well; the command records the run `blocked-by-mode`, exits `3` and prints the answer. Relay the answer, name the refused actions from the first line, and diff --git a/plugins/external-agents/skills/antigravity/reference/routing.md b/plugins/external-agents/skills/antigravity/reference/routing.md index f761db4dc9..e7e894982a 100644 --- a/plugins/external-agents/skills/antigravity/reference/routing.md +++ b/plugins/external-agents/skills/antigravity/reference/routing.md @@ -1,8 +1,8 @@ # Routing: model and effort -This skill holds no model names and no effort defaults. agy needs a model for every run: one the -user names for the run, or `antigravity.model` from config; with neither, the run is skipped. An -effort passes only when `antigravity.effort` is set. Which model and effort each agent role in a +This skill holds no model names and no effort defaults. A run passes a model only when the user +names one or `antigravity.model` is set, and an effort only when `antigravity.effort` is set; +otherwise agy's own default model decides, so runs follow whatever agy ships. Which model and effort each agent role in a multi-agent run uses is `/multi-agent:route`'s config, not this skill's. agy's model slugs name a thinking level (for example a `-medium` suffix), and agy also takes diff --git a/plugins/external-agents/skills/antigravity/reference/run.md b/plugins/external-agents/skills/antigravity/reference/run.md index 844eb7f654..c622db5a6e 100644 --- a/plugins/external-agents/skills/antigravity/reference/run.md +++ b/plugins/external-agents/skills/antigravity/reference/run.md @@ -8,12 +8,12 @@ external-agents run antigravity --use --prompt-file [- - **Pick the use from the request.** `task` when agy should change files; `investigate` when it should only read and answer. The use's configured mode (`antigravity.uses..mode`, bundled - values in the plugin's `defaults.json`) is both the default and the ceiling. Pass + values in the plugin's `defaults.json`) is both the default and the ceiling. Every use is + read-only by default: writes need `antigravity.uses.task.mode: write` from the user. Pass `--mode read-only` to run a task without writes; `--mode write` never lifts a read-only ceiling. -- **Model.** agy needs one: with neither `--model` nor `antigravity.model` set, the run is skipped - with a notice naming the key, exit `4`. Pass `--model` only when the user names one for this run; - otherwise rely on `antigravity.model`. `antigravity.effort` passes `--effort` when set. Choosing - one: [routing.md](routing.md). +- **Model and effort.** Pass `--model` only when the user names one for this run. Otherwise pass + nothing: `antigravity.model` and `antigravity.effort` from config apply when set, and agy's own + default applies when not. Choosing one: [routing.md](routing.md). - **Resume** continues an agy conversation this plugin started. `--resume ` takes a `thread_id` from `external-agents status `; a thread that is not in this repository's job files is refused. `--last` resumes this plugin's newest job with a thread in this repository. A diff --git a/plugins/external-agents/skills/antigravity/reference/update.md b/plugins/external-agents/skills/antigravity/reference/update.md index b73f176aab..e28dc48dfe 100644 --- a/plugins/external-agents/skills/antigravity/reference/update.md +++ b/plugins/external-agents/skills/antigravity/reference/update.md @@ -32,8 +32,8 @@ One line per check; act on each: Read `antigravity.model` from `/external-agents.yaml` and `/external-agents.local.yaml` (the local file wins). When it is set and its slug is not a line's first column in `models.txt`, tell the user the configured model is not in this agy version's list, name the key, and quote the -closest slugs from the file. Unset: say nothing here; a run reports the skip itself. Change no -config file yourself. +closest slugs from the file. Unset: say nothing; agy's own default applies. Change no config file +yourself. ## Routing refresh