agy-plugin-cc 0.6.4 → 0.7.0

package/README.md

@@ -9,13 +9,17 @@ This plugin is for Claude Code users who want an easy way to start using Antigra
 
 ## What You Get
 
+- `/agy:setup` for installation and authentication checks, and the stop-review gate toggle
 - `/agy:review` for standard read-only code review
 - `/agy:adversarial-review` for challenge-based review
 - `/agy:rescue`, `/agy:status`, `/agy:result`, and `/agy:cancel` for task delegation and job management
 - `/agy:continue` to follow up in an existing agy conversation
-- `/agy:quota` to check remaining Antigravity model quota
+- `/agy:whisper` for a one-shot question to agy with no repository context
+- `/agy:search` for a web search or a single page fetch through agy, second in the web tool order after Claude Code's own tools
+- `/agy:research` for a web-grounded investigation with a fixed report shape and sources, optionally written to a file
+- `/agy:image` to generate an image with agy and copy it into the project on request
 - `/agy:transfer` to hand the current session over to a resumable agy conversation
-- `/agy:setup` for installation and authentication checks, and the stop-review gate toggle
+- `/agy:quota` to check remaining Antigravity model quota
 - An optional stop-review gate: a Stop hook that has agy review the previous turn before the session can end
 
 ## Requirements
@@ -92,6 +96,29 @@ One simple first run is:
 
 ## Usage
 
+### `/agy:setup`
+
+Checks agy readiness through a companion script (`scripts/agy-setup.mjs`) that runs every check itself (agy on PATH, auth probe, a command probe and a file-read probe for headless permission denial, stop-review gate state) and prints a single JSON report with `ready`, per-check sections, and `nextSteps`.
+
+Headless agy auto-denies any tool its `permissions.allow` rules do not cover, and it reports the refusal as `denied_actions` on an otherwise successful-looking result. The two probes exercise a terminal command and a file read, because the two need different rules (`command(...)` and `read_file(*)`) and `--mode accept-edits` covers neither. The report names each denied tool and the rule for it. That settings edit is yours to make by hand, in your own terminal: in a Claude Code auto mode session the classifier blocks the agent from editing the file, from passing `--dangerously-skip-permissions`, and even from querying `agy -p "/permissions"`.
+
+When a probe fails, the report says which of three things went wrong rather than assuming a login problem: a real authentication failure, a restricted environment where the invoking shell blocked a syscall agy needs, or an unknown cause. Only the first is fixed by signing in again.
+
+You can also use `/agy:setup` to manage the optional stop-review gate.
+
+#### Enabling the stop-review gate
+
+```bash
+/agy:setup gate on
+/agy:setup gate off
+/agy:setup gate status
+```
+
+When the gate is enabled, the plugin uses a `Stop` hook to run a read-only agy review of the previous Claude turn before the session is allowed to end. If that review finds issues in code changes from that turn, the stop is blocked so Claude can address them first.
+
+> [!WARNING]
+> The gate adds an agy review round-trip to ending a turn and spends Antigravity quota. Only enable it when you plan to actively monitor the session.
+
 ### `/agy:review`
 
 Runs a read-only agy review of your current git diff.
@@ -177,16 +204,73 @@ Examples:
 /agy:continue 4f3062ab-b0d9-4874-b319-e42e9701e643 summarize what you changed
 ```
 
-### `/agy:quota`
+### `/agy:whisper`
 
-Shows remaining Antigravity model quota per bucket (Gemini and third-party groups, 5-hour and weekly windows) with reset times. Instant and quota-free.
+```text
+/agy:whisper what does SIGPIPE mean for a Node child process
+/agy:whisper --model gemini-3.5-pro --effort high explain CRDT merge semantics
+```
 
-Examples:
+One-shot: no repository, no `--add-dir`, no follow-up. The answer comes back
+with a `conversation_id`, so `/agy:continue <id> <follow-up>` picks it up. agy
+runs from an isolated temp directory, so it does not see your project. That is
+a working-directory change rather than a sandbox: agy's own
+`allowNonWorkspaceAccess` setting, with an absolute path in the prompt text,
+still reaches outside it. Nothing in this command's text is checked for a URL;
+the local-network guard belongs to `/agy:search` alone.
 
-```bash
-/agy:quota
+### `/agy:search`
+
+```text
+/agy:search what changed in the Node 24 permission model
+/agy:search https://nodejs.org/en/blog/release/v24.0.0
+```
+
+A bare question runs a web search and answers with a `Sources:` list. A single
+`http://` or `https://` URL fetches that page as markdown. Local, private,
+link-local, and other reserved-network targets, non-http schemes, and URLs
+carrying credentials are refused before agy runs. A URL-shaped word inside an
+ordinary search query is checked the same way, so a blocked address does not
+get through by arriving with other words around it. That check is made once, on
+the URL given; it does not follow redirects and cannot see a DNS answer that
+changes afterward (rebinding), since agy performs the actual fetch in its own
+process. It also covers this command only: `/agy:whisper`, `/agy:research` and
+`/agy:image` send their text to the same web-capable agy unchecked. The
+`agy-web` skill tells Claude Code to reach for this second, after
+its own WebSearch and WebFetch and before Tavily.
+
+### `/agy:research`
+
+```text
+/agy:research --effort high --out docs/notes/wasm-gc.md state of WebAssembly GC support
+/agy:research tradeoffs between SQLite WAL and rollback journal for a desktop app
 ```
 
+Fixed report shape: Summary, Key findings (each with its source), Disagreements
+and thin evidence, Caveats, Sources. `--effort` sets the depth. `--out <path>`
+writes the same markdown inside the workspace; the parent directory must exist
+and an existing file is never overwritten. agy runs isolated; the companion does
+the write.
+
+### `/agy:image`
+
+```text
+/agy:image --out assets/hero.png isometric illustration of a developer at a desk
+/agy:image a minimalist dark-mode login mockup, blue accent colour
+```
+
+agy writes the file under its own artifacts directory
+(`~/.gemini/antigravity-cli/brain/<conversation-id>/<generated-name>`). Without
+`--out` the command reports that path and copies nothing. With `--out <path>`
+the companion checks the file agy named really resolves, after symlinks, to
+somewhere inside that directory, then copies it inside the workspace; the
+parent directory must exist and an existing file is never overwritten. The
+copy is a byte-for-byte copy, not a re-encode, so a `--out` name whose
+extension differs from the file agy actually produced is copied as-is under
+the name given. That happens: a run that asked for a PNG came back as a
+1024x1024 JPEG, under a name agy chose itself. agy never sees `--out`; the
+companion resolves it and does the copy.
+
 ### `/agy:transfer`
 
 Seeds a fresh agy conversation with a handoff brief of the current session (goal, state, decisions, open items) and returns the `conversation_id` with both resume paths.
@@ -241,29 +325,16 @@ Examples:
 /agy:cancel task-abc123
 ```
 
-### `/agy:setup`
-
-Checks agy readiness through a companion script (`scripts/agy-setup.mjs`) that runs every check itself (agy on PATH, auth probe, a command probe and a file-read probe for headless permission denial, stop-review gate state) and prints a single JSON report with `ready`, per-check sections, and `nextSteps`.
-
-Headless agy auto-denies any tool its `permissions.allow` rules do not cover, and it reports the refusal as `denied_actions` on an otherwise successful-looking result. The two probes exercise a terminal command and a file read, because the two need different rules (`command(...)` and `read_file(*)`) and `--mode accept-edits` covers neither. The report names each denied tool and the rule for it. That settings edit is yours to make by hand, in your own terminal: in a Claude Code auto mode session the classifier blocks the agent from editing the file, from passing `--dangerously-skip-permissions`, and even from querying `agy -p "/permissions"`.
-
-When a probe fails, the report says which of three things went wrong rather than assuming a login problem: a real authentication failure, a restricted environment where the invoking shell blocked a syscall agy needs, or an unknown cause. Only the first is fixed by signing in again.
+### `/agy:quota`
 
-You can also use `/agy:setup` to manage the optional stop-review gate.
+Shows remaining Antigravity model quota per bucket (Gemini and third-party groups, 5-hour and weekly windows) with reset times. Instant and quota-free.
 
-#### Enabling the stop-review gate
+Examples:
 
 ```bash
-/agy:setup gate on
-/agy:setup gate off
-/agy:setup gate status
+/agy:quota
 ```
 
-When the gate is enabled, the plugin uses a `Stop` hook to run a read-only agy review of the previous Claude turn before the session is allowed to end. If that review finds issues in code changes from that turn, the stop is blocked so Claude can address them first.
-
-> [!WARNING]
-> The gate adds an agy review round-trip to ending a turn and spends Antigravity quota. Only enable it when you plan to actively monitor the session.
-
 ## Typical Flows
 
 ### Review Before Shipping
@@ -344,66 +415,6 @@ Off by default. When enabled, a Stop hook runs a read-only `agy -p` review of th
 - If agy is missing, the gate skips with a note instead of blocking.
 - Review failures and timeouts block with guidance to run `/agy:review` manually or turn the gate off.
 
-## Design
-
-Thin by design: no broker process, no job files. Every delegation is one `agy -p … --output-format json` call. Write-capable runs use `--mode accept-edits`; reviews run read-only. Foreground runs are capped near 9 minutes by the Bash tool ceiling; split longer work or use `--background`.
-
-Job control stays thin too: `/agy:status`, `/agy:result`, and `/agy:cancel` read Claude Code's own background task tracking instead of a job store, so they cover the current session only. Cross-session continuity lives agy-side via `conversation_id` and `/agy:rescue --resume`.
-
-## Layout
-
-```
-.
-├── .claude-plugin/
-│   ├── marketplace.json               marketplace catalog
-│   └── plugin.json                    manifest (plugin name: agy)
-├── agents/
-│   └── agy-rescue.md                  forwarding subagent
-├── commands/
-│   ├── adversarial-review.md
-│   ├── cancel.md
-│   ├── continue.md
-│   ├── quota.md
-│   ├── rescue.md
-│   ├── result.md
-│   ├── review.md
-│   ├── setup.md
-│   ├── status.md
-│   └── transfer.md
-├── hooks/
-│   └── hooks.json                     Stop hook wiring for the stop-review gate
-├── prompts/
-│   ├── adversarial-review.md          challenge-review prompt
-│   ├── review.md                      code-review prompt
-│   ├── stop-review-gate.md            stop-gate prompt
-│   └── transfer.md                    session handoff prompt
-├── schemas/
-│   └── review-output.schema.json      adversarial review output shape
-├── scripts/
-│   ├── lib/
-│   │   ├── agy.mjs                    agy invocation and result normalizing
-│   │   ├── git.mjs                    diff collection
-│   │   ├── process.mjs                spawn without a shell, Windows shims
-│   │   ├── prompts.mjs                prompt loader
-│   │   ├── state.mjs                  per-workspace state
-│   │   ├── stop-review.mjs            stop-review gate decision logic
-│   │   └── workspace.mjs              repository root resolution
-│   ├── agy-companion.mjs              review, transfer, quota, gate subcommands
-│   ├── agy-setup.mjs                  /agy:setup readiness report
-│   ├── bump-version.mjs               version metadata check and bump
-│   ├── npx-install.mjs                npx agy-plugin-cc installer
-│   ├── prepack-check.mjs              refuses to npm pack with .bak files present
-│   └── stop-review-gate-hook.mjs      stop-review gate (dependency-free node)
-├── skills/
-│   ├── agy-cli-runtime/               CLI call contract
-│   └── agy-result-handling/           output presentation rules
-├── tests/                             node --test suite, run with npm test
-├── CHANGELOG.md
-├── LICENSE
-├── README.md
-└── package.json                       npm package (agy-plugin-cc) for the npx installer
-```
-
 ## FAQ
 
 ### Do I need a separate Antigravity account for this plugin?
@@ -418,7 +429,45 @@ No. Every delegation is a call to the same local `agy` binary you would use dire
 
 ### Will it use the same agy settings I already have?
 
-Yes. The plugin picks up your existing configuration in `~/.gemini/antigravity-cli/settings.json`, including `permissions.allow` rules. Headless runs auto-deny tools not covered by those rules, file reads (`read_file(*)`) as well as commands (`command(*)` or a narrower target); [`/agy:setup`](#agysetup) detects both and shows the rule to add. You make that edit by hand, outside the agent session: an auto mode session cannot apply it for you.
+Yes, and one of those settings decides whether delegation works at all.
+
+agy's `toolPermission` setting decides whether headless delegation can work at
+all, and it is set in `~/.gemini/antigravity-cli/settings.json` or through agy's
+own `/config` screen. Measured on agy 1.2.4 with no allow-rules, and the same
+live harness (`npm run test:denials`) passed on agy 1.2.5 on 2026-09-18:
+
+| mode | headless behaviour |
+|---|---|
+| `always-proceed` | every tool approved, no sandbox, including reads and writes outside the workspace |
+| `request-review` | agy's default. Commands are refused because there is nobody to ask. A read of a file inside the workspace was allowed with no rule, though GitHub issue #21 reported one refused, so do not count on it. File writes are not refused |
+| `proceed-in-sandbox` | approves commands only when agy is started with `--sandbox`, which this plugin does not pass, so commands stay refused |
+| `strict` | refuses even a read of a file inside the workspace, and is the only mode that did |
+
+Anything else, including a typo, is accepted and silently read back as
+`request-review`, so a mode that never takes effect looks the same as one that
+does.
+
+When a delegation is refused anyway, the plugin resumes that conversation once,
+stating the constraint, rather than throwing the turn away. The result carries a
+`recovery` object naming what was denied on the first turn. The stop-review gate
+does not resume: a review that lost its file reads has nothing to say.
+
+On top of the mode, `permissions.allow` rules grant individual tools. Headless
+runs auto-deny anything not covered, file reads (`read_file(*)`, which also
+covers directory listing) as well as commands (`command(*)`). A narrower
+`command(git *)` is the safer intent but is unverified: on agy 1.2.4 a
+`command(pwd)` rule did not permit `pwd` while `command(*)` did, and agy never
+prints the target string it tried to match.
+
+[`/agy:setup`](#agysetup) reports your mode and the denied tools. You make any
+change by hand, outside the agent session: an auto mode session cannot apply it
+for you.
+
+If you want delegation to simply work, `always-proceed` is the setting that does
+it. Understand what you are granting first: every tool approved with no sandbox,
+reaching outside the workspace, and agy's own changelog records fixing a bug
+where outside-of-workspace writes were wrongly auto-approved in exactly that
+mode.
 
 ### Does it spend my Antigravity quota?
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agy-plugin-cc",
-  "version": "0.6.4",
+  "version": "0.7.0",
   "description": "Installer for the agy Claude Code plugin: use Google's Antigravity CLI (agy) from Claude Code to delegate tasks or review code.",
   "bin": {
     "agy-plugin-cc": "scripts/npx-install.mjs"
@@ -28,6 +28,7 @@
   "license": "MIT",
   "scripts": {
     "test": "node --test",
+    "test:denials": "node tests/live/run-denial-matrix.mjs",
     "check-version": "node scripts/bump-version.mjs --check",
     "prepack": "node scripts/prepack-check.mjs"
   }