agy-plugin-cc 0.6.0 → 0.6.4

package/README.md

@@ -4,6 +4,9 @@ Use Google's Antigravity CLI (`agy`) from inside Claude Code: delegate tasks to
 
 This plugin is for Claude Code users who want an easy way to start using Antigravity from the workflow they already have.
 
+> [!NOTE]
+> This is an open-source, third-party community project. It is not affiliated with, endorsed by, or sponsored by Anthropic or Google.
+
 ## What You Get
 
 - `/agy:review` for standard read-only code review
@@ -20,6 +23,7 @@ This plugin is for Claude Code users who want an easy way to start using Antigra
 - **Google account for Antigravity sign-in.**
   - Delegations contribute to your Antigravity usage limits. Check them anytime with `/agy:quota`.
 - **Node.js 18 or later**
+- **git**, for the review commands. The companion script collects the diff itself, so a missing git is reported as `git is not installed or not on PATH` rather than an empty review.
 
 ## Install
 
@@ -65,10 +69,12 @@ On Windows (PowerShell):
 irm https://antigravity.google/cli/install.ps1 | iex
 ```
 
+The plugin's own test suite runs on Windows as well as Linux in CI, including a check that it can actually execute the `.cmd` shims npm installs there.
+
 If agy is installed but not signed in yet, run it once interactively:
 
 ```bash
-!agy
+! agy
 ```
 
 After install, you should see:
@@ -156,6 +162,7 @@ Examples:
 **Notes:**
 
 - if you do not pass `--model` or `--effort`, agy chooses its own defaults
+- some models reject `--effort` outright (agy 1.2.4 refuses it for `claude-opus-4-6-thinking` before running anything); the rescue agent then reruns once without the flag and says so
 - write-capable runs use `--mode accept-edits` on the agy side; review and diagnosis runs stay read-only
 - follow-up rescue requests can continue the latest agy conversation
 
@@ -197,7 +204,7 @@ Afterwards, continue in a terminal with `agy --conversation <id>`, or from Claud
 
 ### `/agy:status`
 
-Shows active and recent background agy delegations in this session.
+Shows active and recent background agy work in this session. Two kinds appear, and both are listed: `agy:agy-rescue` subagent delegations from `/agy:rescue --background`, and backgrounded companion runs from `/agy:adversarial-review --background`, which are Claude Code background tasks rather than subagents.
 
 Examples:
 
@@ -214,7 +221,7 @@ Use it to:
 
 ### `/agy:result`
 
-Shows the stored final output of a finished background delegation, including the `conversation_id` so you can reopen that run with `/agy:continue` or `agy --conversation <id>`.
+Shows the stored final output of a finished background run, subagent delegation or companion review alike, including the `conversation_id` so you can reopen that run with `/agy:continue` or `agy --conversation <id>`.
 
 Examples:
 
@@ -236,7 +243,11 @@ Examples:
 
 ### `/agy:setup`
 
-Checks agy readiness through a companion script (`scripts/agy-setup.mjs`) that runs every check itself (agy on PATH, auth probe, tool-exercising probe for headless permission denial, stop-review gate state) and prints a single JSON report with `ready`, per-check sections, and `nextSteps`.
+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.
 
@@ -287,7 +298,11 @@ Then check in with:
 /agy:transfer
 ```
 
-Then continue in a terminal with `agy --conversation <id>`.
+Then continue in a terminal with:
+
+```bash
+agy --conversation <id>
+```
 
 ## How to Delegate
 
@@ -325,7 +340,7 @@ Either way, the result comes back with a `conversation_id`, so the thread stays
 
 Off by default. When enabled, a Stop hook runs a read-only `agy -p` review of the previous Claude turn before the session is allowed to end. The reviewer answers `ALLOW:` or `BLOCK:` on its first line; a block keeps the session open with the reviewer's reason. Turns without code changes are allowed through immediately.
 
-- Toggle per project with `/agy:setup gate on` / `gate off`; state lives in `.claude/agy.local.md` (`stop_review_gate: true`).
+- Toggle per workspace with `/agy:setup gate on` / `gate off`. The flag is stored outside the repository, under `CLAUDE_PLUGIN_DATA` and keyed by a hash of the workspace root, so there is nothing in your project to commit by mistake. A gate enabled under the older in-repository `.claude/agy.local.md` is still honoured until you set it through the command.
 - 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.
 
@@ -338,15 +353,55 @@ Job control stays thin too: `/agy:status`, `/agy:result`, and `/agy:cancel` read
 ## Layout
 
 ```
-.claude-plugin/plugin.json   manifest (plugin name: agy)
-agents/agy-rescue.md         forwarding subagent
-commands/                    rescue, review, adversarial-review, status, result, cancel, continue, quota, transfer, setup
-hooks/hooks.json             Stop hook wiring for the stop-review gate
-scripts/                     agy-setup.mjs, stop-review-gate-hook.mjs, npx-install.mjs (dependency-free node)
-schemas/                     adversarial review output shape
-skills/agy-cli-runtime/      CLI call contract
-skills/agy-result-handling/  output presentation rules
-package.json                 npm package (agy-plugin-cc) for the npx installer
+.
+├── .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
@@ -355,7 +410,7 @@ package.json                 npm package (agy-plugin-cc) for the npx installer
 
 If you are already signed into agy on this machine, that account works immediately here too. This plugin uses your local Antigravity CLI authentication.
 
-If you have not used Antigravity yet, install the CLI and run `!agy` once to sign in with your Google account, then run `/agy:setup` to confirm everything is ready.
+If you have not used Antigravity yet, [install the CLI](#install) and run `! agy` once to sign in with your Google account, then run [`/agy:setup`](#agysetup) to confirm everything is ready. Interactive agy needs a TTY, so the `! agy` form only works where the host gives the command a real terminal; otherwise sign in from a terminal of your own.
 
 ### Does the plugin use a separate Antigravity runtime?
 
@@ -363,12 +418,12 @@ 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; `/agy:setup` detects this and shows the fix.
+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.
 
 ### Does it spend my Antigravity quota?
 
-Yes. Delegations, reviews, and stop-review gate runs all contribute to your Antigravity usage limits. `/agy:quota` shows what is left per bucket and is itself quota-free.
+Yes. Delegations, reviews, and stop-review gate runs all contribute to your Antigravity usage limits. [`/agy:quota`](#agyquota) shows what is left per bucket and is itself quota-free.
 
 ### What does `npx agy-plugin-cc` actually do?
 
-It runs `claude plugin marketplace add Eakkapoom-Name/antigravity-plugin-cc` and `claude plugin install agy@antigravity-plugin-cc` through your local `claude` CLI, then points you at `/agy:setup`. It is safe to rerun.
+It runs `claude plugin marketplace add Eakkapoom-Name/antigravity-plugin-cc` and `claude plugin install agy@antigravity-plugin-cc` through your local `claude` CLI, then points you at [`/agy:setup`](#agysetup). It is safe to rerun. See [Install](#install) for the manual steps.

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "agy-plugin-cc",
-  "version": "0.6.0",
+  "version": "0.6.4",
   "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"
   },
   "files": [
     "scripts/npx-install.mjs",
+    "scripts/lib/process.mjs",
     "README.md",
     "LICENSE"
   ],
@@ -24,5 +25,10 @@
     "agy"
   ],
   "author": "toaster",
-  "license": "MIT"
+  "license": "MIT",
+  "scripts": {
+    "test": "node --test",
+    "check-version": "node scripts/bump-version.mjs --check",
+    "prepack": "node scripts/prepack-check.mjs"
+  }
 }

package/scripts/lib/process.mjs

@@ -0,0 +1,109 @@
+import fs from "node:fs";
+import path from "node:path";
+import process from "node:process";
+import { spawnSync } from "node:child_process";
+
+const DEFAULT_PATHEXT = ".COM;.EXE;.BAT;.CMD";
+
+// npm installs `agy` and `claude` on Windows as `.cmd` and `.ps1` shims, which
+// `spawnSync("agy", ...)` cannot execute: there is no `agy` file to exec.
+//
+// `shell: true` would fix it and must not be used. These commands are handed
+// prompt text, diffs, and file paths; routing any of that through a shell turns
+// argument data into shell syntax. Resolving the real file and spawning it
+// directly keeps arguments as arguments.
+//
+// This also replaces the `which` call the setup script used, which only existed
+// on Unix in the first place.
+export function resolveCommand(name, env = process.env) {
+  const raw = String(name ?? "");
+  if (!raw) {
+    return null;
+  }
+
+  const isWindows = process.platform === "win32";
+  const extensions = isWindows
+    ? ["", ...String(env.PATHEXT || DEFAULT_PATHEXT).split(";").filter(Boolean)]
+    : [""];
+
+  const exists = (candidate) => {
+    try {
+      return fs.statSync(candidate).isFile();
+    } catch {
+      return false;
+    }
+  };
+
+  // An explicit path is used as given; only PATH entries get the extension walk.
+  if (raw.includes("/") || raw.includes("\\")) {
+    const absolute = path.resolve(raw);
+    for (const extension of extensions) {
+      if (exists(absolute + extension)) {
+        return absolute + extension;
+      }
+    }
+    return null;
+  }
+
+  for (const dir of String(env.PATH || "").split(path.delimiter).filter(Boolean)) {
+    for (const extension of extensions) {
+      const candidate = path.join(dir, raw + extension);
+      if (exists(candidate)) {
+        return candidate;
+      }
+    }
+  }
+  return null;
+}
+
+export function commandAvailable(name, env = process.env) {
+  return resolveCommand(name, env) !== null;
+}
+
+const WINDOWS_BATCH = /\.(cmd|bat)$/i;
+
+// Resolving the shim is only half the job: Windows cannot exec a .cmd or .bat
+// image at all, and since the fix for CVE-2024-27980 Node refuses to try,
+// throwing EINVAL. Such a file has to be handed to cmd.exe.
+//
+// cmd.exe is invoked explicitly rather than through `shell: true` because the
+// difference is what stays fixed. Here the interpreter and the command file are
+// decided by this function and only the arguments are quoted. With
+// `shell: true` the whole line, command included, would be assembled from
+// caller-supplied text.
+export function quoteForCmd(value) {
+  const text = String(value ?? "");
+  // Windows argument rules: backslashes are literal unless they precede a
+  // quote, where they must be doubled.
+  const escaped = text.replace(/(\\*)"/g, '$1$1\\"').replace(/(\\*)$/, "$1$1");
+  return `"${escaped}"`;
+}
+
+export function buildCmdInvocation(target, args, env = process.env) {
+  // /d skips AutoRun commands from the registry, /s fixes how the outer quotes
+  // around the whole command are parsed, /c runs it and exits.
+  return {
+    file: env.ComSpec || "cmd.exe",
+    args: ["/d", "/s", "/c", `"${[target, ...args].map(quoteForCmd).join(" ")}"`]
+  };
+}
+
+// Spawns without a shell, always. When the command cannot be resolved the raw
+// name is passed through so the caller still gets a normal ENOENT result rather
+// than a different error shape from this layer.
+export function runCommand(name, args, options = {}) {
+  const resolved = resolveCommand(name) ?? name;
+
+  if (process.platform === "win32" && WINDOWS_BATCH.test(resolved)) {
+    const invocation = buildCmdInvocation(resolved, args);
+    return spawnSync(invocation.file, invocation.args, {
+      ...options,
+      shell: false,
+      // The argument vector is already quoted for cmd.exe above; letting Node
+      // quote it again would double the escaping.
+      windowsVerbatimArguments: true
+    });
+  }
+
+  return spawnSync(resolved, args, { ...options, shell: false });
+}

package/scripts/npx-install.mjs

@@ -4,14 +4,19 @@
 // `npx agy-plugin-cc` registers the marketplace and installs the plugin
 // through the user's local `claude` CLI. Safe to rerun.
 
-import { spawnSync } from "node:child_process";
+import fs from "node:fs";
 import process from "node:process";
+import { fileURLToPath } from "node:url";
+
+import { runCommand } from "./lib/process.mjs";
 
 const MARKETPLACE = "Eakkapoom-Name/antigravity-plugin-cc";
 const PLUGIN = "agy@antigravity-plugin-cc";
 
 function run(args) {
-  const result = spawnSync("claude", args, { encoding: "utf8" });
+  // Resolved through PATH and PATHEXT so the claude.cmd shim npm installs on
+  // Windows is found; a bare spawn of "claude" cannot execute it.
+  const result = runCommand("claude", args, { encoding: "utf8" });
   return {
     ok: result.status === 0,
     enoent: result.error?.code === "ENOENT",
@@ -19,8 +24,16 @@ function run(args) {
   };
 }
 
-function alreadyDone(output) {
-  return /already/i.test(output);
+// A rerun is a no-op, not a failure, but a bare /already/i over the combined
+// stdout and stderr also swallows any genuine failure whose message happens to
+// contain the word. Match the shape of a no-op instead. The two observed
+// messages are `Marketplace '<name>' already on disk` and
+// `Plugin "<name>" is already installed`; the rest are near neighbours.
+const ALREADY_DONE =
+  /\balready\s+(?:on disk|installed|added|exists?|present|registered|configured|up[- ]to[- ]date)\b/i;
+
+export function alreadyDone(output) {
+  return ALREADY_DONE.test(String(output ?? ""));
 }
 
 function fail(message) {
@@ -28,27 +41,44 @@ function fail(message) {
   process.exit(1);
 }
 
-console.log(`Adding marketplace ${MARKETPLACE} ...`);
-const add = run(["plugin", "marketplace", "add", MARKETPLACE]);
-if (add.enoent) {
-  fail(
-    "The `claude` CLI was not found on PATH. Install Claude Code first: https://code.claude.com/docs"
-  );
-}
-if (!add.ok && !alreadyDone(add.output)) {
-  fail(`Could not add the marketplace:\n${add.output}`);
-}
-console.log(add.ok ? "Marketplace added." : "Marketplace already added.");
+function main() {
+  console.log(`Adding marketplace ${MARKETPLACE} ...`);
+  const add = run(["plugin", "marketplace", "add", MARKETPLACE]);
+  if (add.enoent) {
+    fail(
+      "The `claude` CLI was not found on PATH. Install Claude Code first: https://code.claude.com/docs"
+    );
+  }
+  // Kept for claude CLI releases where a duplicate add exits non-zero. On the
+  // version this was measured against, both duplicate cases exit 0, so this
+  // branch is unreachable there and the message below is what reports the
+  // no-op. Removing it would break older installs for no gain.
+  if (!add.ok && !alreadyDone(add.output)) {
+    fail(`Could not add the marketplace:\n${add.output}`);
+  }
+  // A rerun succeeds rather than failing, so the exit status alone does not say
+  // whether anything changed; the message does.
+  console.log(alreadyDone(add.output) ? "Marketplace already added." : "Marketplace added.");
 
-console.log(`Installing ${PLUGIN} ...`);
-const install = run(["plugin", "install", PLUGIN]);
-if (!install.ok && !alreadyDone(install.output)) {
-  fail(`Could not install the plugin:\n${install.output}`);
-}
-console.log(install.ok ? "Plugin installed." : "Plugin already installed.");
+  console.log(`Installing ${PLUGIN} ...`);
+  const install = run(["plugin", "install", PLUGIN]);
+  if (!install.ok && !alreadyDone(install.output)) {
+    fail(`Could not install the plugin:\n${install.output}`);
+  }
+  console.log(alreadyDone(install.output) ? "Plugin already installed." : "Plugin installed.");
 
-console.log(`
+  console.log(`
 Done. Next steps:
   1. Start (or restart) Claude Code.
   2. Run /agy:setup to check that the Antigravity CLI (agy) is ready.
      If agy is not installed yet, see https://antigravity.google/docs/cli/install/`);
+}
+
+// Only install when invoked as a script; importing this module (for tests) must
+// not shell out to the claude CLI.
+if (
+  process.argv[1] &&
+  fs.realpathSync(process.argv[1]) === fs.realpathSync(fileURLToPath(import.meta.url))
+) {
+  main();
+}