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..aabcb7dfc2 --- /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`, 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 e348c070ff..ab1048a664 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,9 @@ 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 + 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/` diff --git a/plugins/external-agents/defaults.json b/plugins/external-agents/defaults.json index e717330823..201e2e8f81 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": "read-only" }, + "investigate": { "mode": "read-only" }, + "review": { "mode": "read-only" } + }, + "council": { "enabled": true } + }, "breaker": { "cooldown_hours": 24 }, "jobs": { "keep": 50 } } 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 new file mode 100644 index 0000000000..2075becc39 --- /dev/null +++ b/plugins/external-agents/providers/antigravity.yaml @@ -0,0 +1,62 @@ +schema: 1 +product: antigravity +docs_index: https://antigravity.google/docs/cli +help: + agy: [--help] + models: [models] +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: cli-default +model_flag: --model +effort_flag: --effort +always_args: [--output-format, json, --disable-slash-commands] +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 + config_paths: [.agents/] +modes: + read-only: + enforcement: approval-denial + settings: + agentMode: "" + allowNonWorkspaceAccess: false + settings_arg: --settings + 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: + 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 7f4e979450..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 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 model, effort or profile leaves the CLI's own configuration in charge.", "type": "object", "additionalProperties": false, "required": ["schema"], @@ -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: 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." }, + "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": "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", + "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, diff --git a/plugins/external-agents/skills/antigravity/SKILL.md b/plugins/external-agents/skills/antigravity/SKILL.md new file mode 100644 index 0000000000..e14042cc3c --- /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 + +- **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 + 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..e7e894982a --- /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. 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 +`--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..c622db5a6e --- /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. 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 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 + 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..e28dc48dfe --- /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; agy's own default applies. 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.