@estebanforge/pi-ask-antigravity 1.0.0 → 1.1.0

package/README.md

@@ -2,7 +2,9 @@
 
 A [Pi](https://github.com/earendil-works/pi-coding-agent) extension that exposes the **`AskAntigravity`** tool: delegate a self-contained sub-task to Google Antigravity's `agy` CLI and stream its response back into the Pi session.
 
-It is the `AskClaude`-style delegation pattern, pointed at Gemini via `agy`. The tool answers to three names the CLI is known by — **gemini**, **antigravity**, and **agy** — surfaced in its description so the model maps any of them to this single tool.
+It is the `AskClaude`-style delegation pattern (from pi-claude-bride extension), pointed at Gemini via `agy`. The tool answers to three names the CLI is known by — **gemini**, **antigravity**, and **agy** — surfaced in its description so the model maps any of them to this single tool.
+
+<img width="1512" height="845" alt="image" src="https://github.com/user-attachments/assets/3e1a8f19-64d2-43ab-a30f-47f39daa151d" />
 
 ## Install
 
@@ -49,11 +51,40 @@ Verbose `agy models` strings (`Gemini 3.5 Flash (Medium)`) are hostile to natura
 | `pro low` | latest Pro, Low |
 | `3.5 flash` | pinned version, default tier |
 | `3.1 pro` | pinned Pro version (→ High) |
+| `sonnet` | Claude Sonnet 4.6 (Thinking) |
+| `opus` | Claude Opus 4.6 (Thinking) |
+| `gpt-oss` | GPT-OSS 120B (Medium) |
 | `Gemini 3.5 Flash (Medium)` | exact passthrough |
 
 - **Latest** = highest version number available for the family.
 - **Default tier**: Flash → Medium, Pro → High. Overridable per-config (below).
 - When a tier is unavailable for a family, the nearest is chosen with ties broken toward the higher tier (so "latest and greatest" wins).
+- The non-Gemini aliases (`sonnet`, `opus`, `gpt-oss`) are a static overlay merged with the live `agy models` catalog. Live entries always win on case-insensitive full-string equality, so an updated `agy` listing takes precedence over the hardcoded fallback.
+
+## Execution modes (`mode`)
+
+| Mode | Flag | Use when |
+| --- | --- | --- |
+| `plan` | `--mode plan` | agy reviews and plans without writing. Use for cross-review and read-only tasks. |
+| `accept-edits` (default) | `--mode accept-edits` | agy applies edits directly inside the workspace. |
+
+For agy's orthogonal `--sandbox` shell-containment flag, set `AGY_EXTRA_ARGS=--sandbox` in your environment. The extension does not expose it as a `mode` value because `--sandbox` controls command containment, not edit persistence.
+
+Recommended pairings:
+
+```text
+# Gemini produces, Claude reviews
+AskAntigravity prompt="Implement the approved refactor" mode=accept-edits
+AskAntigravity prompt="Review the resulting diff" model=opus mode=plan digest=true
+
+# Claude produces, Gemini reviews
+AskAntigravity prompt="Fix the parser root cause" model=opus mode=accept-edits
+AskAntigravity prompt="Review the resulting diff" model=pro mode=plan digest=true
+```
+
+## Compact output (`digest`)
+
+Set `digest: true` to prefix the prompt with `(Use compact digests, not full file contents.)` so `agy` returns summaries instead of full file payloads. Defaults on for `plan`, off for `accept-edits`. Use `true` for any read-only call (review, exploration, planning) where full file contents are noise.
 
 ## Configuration
 
@@ -82,8 +113,9 @@ Interactive picker for the default model and default thinking. If the project co
 | `prompt` | yes | Self-contained task. agy cannot see the Pi conversation. |
 | `cwd` | no | Workspace agy runs in. Defaults to the project root. |
 | `model` | no | Alias or exact id. Omit for the configured default. |
+| `mode` | no | `plan` (review-only) or `accept-edits` (agy applies edits, default). |
+| `digest` | no | Prefix the prompt with `(Use compact digests, not full file contents.)`. Defaults on for `plan`, off for `accept-edits`. |
 | `conversationId` | no | Omit for a one-shot (agy starts fresh). Pass the id from a prior call's result (`details.conversationId`) to resume that agy conversation with full context. See [Two modes](#two-modes-one-shot-vs-continued-conversation). |
-| `skipPermissions` | no | Pass `--dangerously-skip-permissions`. Needed for mutating tasks. |
 | `timeoutMinutes` | no | Hard cap on the run. Default 10. |
 
 ## Environment

package/extensions/index.ts

@@ -37,7 +37,7 @@ import {
 	getSettingsListTheme,
 	type ExtensionAPI,
 } from "@earendil-works/pi-coding-agent";
-import { StringEnum } from "@earendil-works/pi-ai";
+
 import { Container, SettingsList, Text, type SettingItem } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
 
@@ -66,16 +66,70 @@ const FAMILY_DEFAULT_TIER: Record<Family, ThinkingTier> = {
 
 const TIER_RANK: Record<ThinkingTier, number> = { low: 0, medium: 1, high: 2 };
 
+// Mode = which agy tool-loop policy to apply. Distinct from the alias layer.
+//   "plan"         → --mode plan     (no edits; review-only)
+//   "accept-edits" → --mode accept-edits (agy applies edits)
+//
+// Note: agy's --sandbox flag is an orthogonal shell-containment setting
+// (not an "edit preview" mode), so it is not exposed here. Users who need
+// it can pass it via the AGY_EXTRA_ARGS env var.
+type Mode = "plan" | "accept-edits";
+
+// Static alias overlay for non-Gemini models agy may or may not surface in
+// `agy models` depending on plan. When the live catalog contains an entry
+// whose full string equals the overlay target, the live entry wins. When it
+// does not (older agy, missing model, plan gate), the overlay entry resolves
+// the alias so the user can still type "sonnet" and get a working answer.
+//   "sonnet"   -> Claude Sonnet 4.6 (Thinking)
+//   "opus"     -> Claude Opus 4.6 (Thinking)
+//   "gpt-oss"  -> GPT-OSS 120B (Medium)
+const STATIC_ALIAS_OVERLAY: ReadonlyArray<ModelEntry> = [
+	{ full: "Claude Sonnet 4.6 (Thinking)", family: "other", version: null, tier: null },
+	{ full: "Claude Opus 4.6 (Thinking)", family: "other", version: null, tier: null },
+	{ full: "GPT-OSS 120B (Medium)", family: "other", version: null, tier: null },
+];
+
+// Short alias → overlay full string. Used by resolveModel to recognize
+// friendly short names ("sonnet") that the family-parser (flash/pro) does
+// not match. The overlay entries are also merged into the live catalog for
+// exact-string passthrough, so this map only needs to cover the short names.
+const STATIC_SHORT_ALIAS: ReadonlyMap<string, string> = new Map([
+	["sonnet", "Claude Sonnet 4.6 (Thinking)"],
+	["opus", "Claude Opus 4.6 (Thinking)"],
+	["gpt-oss", "GPT-OSS 120B (Medium)"],
+]);
+
+/** Merge the live catalog with the static alias overlay. Live entries win on
+ *  case-insensitive full-string equality so an updated `agy models` listing
+ *  always takes precedence over the hardcoded fallback. */
+function mergeCatalog(live: ModelEntry[]): ModelEntry[] {
+	const seen = new Set(live.map((e) => e.full.toLowerCase()));
+	const merged = [...live];
+	for (const entry of STATIC_ALIAS_OVERLAY) {
+		if (!seen.has(entry.full.toLowerCase())) merged.push(entry);
+	}
+	return merged;
+}
+
 // agy conversation ids are UUID DB-stems (e.g. "9e6fdc2f-f9f9-4096-95fc-7852528b50cc").
 // Reject anything that isn't, so a leading-dash value can't misbind on agy's
-// arg parser as the token after --conversation.
-const CONV_ID_RE = /^[A-Za-z0-9]{1,128}$/;
+// arg parser as the token after --conversation. First char must be
+// alphanumeric (rejects leading-dash flag injection); hyphens allowed in the
+// body because real UUIDs contain them.
+const CONV_ID_RE = /^[A-Za-z0-9][A-Za-z0-9-]{0,127}$/;
 
 const AGY_DESCRIPTION = `Delegate a self-contained sub-task to Google Antigravity. agy is the CLI for Gemini, so this tool is reached under three equivalent names the user may use interchangeably: **gemini**, **antigravity**, and **agy**. When the user says "ask gemini", "ask antigravity", "ask agy", or otherwise refers to any of these, call THIS tool. agy runs its OWN tool loop: it can read, write, edit, and execute inside the workspace, then returns its final answer. Use for a second opinion from a different model family, Gemini-specific reasoning, or isolated sub-tasks you do not need to drive step-by-step. Provide a complete, self-contained task description; agy will not see this conversation.
 
 TWO MODES (you choose):
 - **One-shot (isolated)**: omit conversationId. agy starts fresh with no memory of prior calls. Use for independent questions.
-- **Continued conversation**: pass the conversationId returned in the PREVIOUS call's details (details.conversationId). agy resumes that conversation with full context intact — use for follow-ups, multi-turn refinement, or when the user says "ask agy to follow up / continue / now do X based on what you just did". Thread the id from each result into the next call.`;
+- **Continued conversation**: pass the conversationId returned in the PREVIOUS call's details (details.conversationId). agy resumes that conversation with full context intact — use for follow-ups, multi-turn refinement, or when the user says "ask agy to follow up / continue / now do X based on what you just did". Thread the id from each result into the next call.
+
+EXECUTION MODES (param: mode):
+- **plan**: agy reviews and plans without writing. Use for cross-review and read-only tasks.
+- **accept-edits** (default): agy applies edits directly inside the workspace.
+- For agy's orthogonal \`--sandbox\` shell-containment flag, set the \`AGY_EXTRA_ARGS=--sandbox\` env var.
+
+COMPACT OUTPUT (param: digest): when true, the prompt is prefixed to request compact digests instead of full file contents. Defaults on for plan, off for accept-edits. Use true whenever you do not need full file payloads (review, exploration, planning).`;
 
 // --- Types -----------------------------------------------------------------
 
@@ -225,6 +279,22 @@ function resolveModel(
 	const exact = entries.find((e) => e.full.toLowerCase() === lower);
 	if (exact) return exact.full;
 
+	// 1b. Static short alias ("sonnet" / "opus" / "gpt-oss"). Checked
+	//     before the family parser because none of these names contain
+	//     "flash" or "pro" and would otherwise return null below. The
+	//     resolved full string is then re-validated against the catalog
+	//     in step 1's second pass on the next call, so renaming the
+	//     overlay entry in code still wins on exact-string match.
+	//     The case-insensitive lookup matches mergeCatalog's dedup logic
+	//     so the "live entries win" guarantee holds even when agy lists
+	//     the model under different casing than the overlay.
+	if (STATIC_SHORT_ALIAS.has(lower)) {
+		const target = STATIC_SHORT_ALIAS.get(lower) as string;
+		const targetLower = target.toLowerCase();
+		const fromCatalog = entries.find((e) => e.full.toLowerCase() === targetLower);
+		return fromCatalog ? fromCatalog.full : target;
+	}
+
 	// 2. Parse the alias.
 	let family: Family | null = lower.includes("flash")
 		? "flash"
@@ -252,14 +322,27 @@ function resolveModel(
 		const versioned = candidates.filter((e) => e.version === version);
 		if (versioned.length > 0) candidates = versioned;
 	} else {
-		const versions = candidates
-			.map((e) => e.version)
-			.filter((v): v is string => v !== null)
-			.sort(compareVersionsDesc);
-		if (versions.length > 0) {
-			const top = versions[0];
-			const latest = candidates.filter((e) => e.version === top || e.version === null);
-			if (latest.length > 0) candidates = latest;
+		// Prefer Google's official `gemini-*-latest` aliases (entries with no
+		// parseable version in their name, e.g. "Gemini Flash Latest") when
+		// the user did NOT pin a specific version. The alias is the
+		// versionless pointer Google intends for "the current release" and
+		// hot-swaps on every release, while versioned entries like
+		// "Gemini 3.6 Flash (Medium)" stay available via explicit pinning
+		// (e.g. "3.6 flash medium"). Falls back to the highest versioned
+		// entry if no alias is present in the catalog.
+		const aliases = candidates.filter((e) => e.version === null);
+		if (aliases.length > 0) {
+			candidates = aliases;
+		} else {
+			const versions = candidates
+				.map((e) => e.version)
+				.filter((v): v is string => v !== null)
+				.sort(compareVersionsDesc);
+			if (versions.length > 0) {
+				const top = versions[0];
+				const latest = candidates.filter((e) => e.version === top);
+				if (latest.length > 0) candidates = latest;
+			}
 		}
 	}
 
@@ -372,6 +455,8 @@ function newConversationId(dir: string, before: Set<string>): string | null {
 interface AgyDetails {
 	model: string | null;
 	resolvedModel: string | null;
+	mode: Mode;
+	digest: boolean;
 	conversationId: string | null;
 	exitCode: number;
 	aborted: boolean;
@@ -382,9 +467,12 @@ interface AgyDetails {
 
 export default async function (pi: ExtensionAPI) {
 	const binary = resolveAgy();
-	// Discovered once at load; frozen for the session (including the
-	// StringEnum model param). Run /reload after an `agy update` to refresh.
-	const discovered = await discoverModels(binary).catch(() => []);
+	// Discovered once at load; frozen for the session. Run /reload after an
+	// `agy update` to refresh. Failure is non-fatal: resolveModel falls back
+	// to passthrough so exact slugs typed by the user still work. The static
+	// alias overlay (sonnet / opus / gpt-oss) is merged on top so those
+	// aliases resolve even when agy doesn't surface them in the live catalog.
+	const discovered = mergeCatalog(await discoverModels(binary).catch(() => []));
 
 	// --- /agy: view / change default model + thinking ---------------------
 
@@ -498,27 +586,17 @@ export default async function (pi: ExtensionAPI) {
 
 	// --- Tool registration -------------------------------------------------
 
-	// Model param: free string (friendly alias OR exact). We surface the
-	// discovered models as a StringEnum when available so the model gets a
-	// bounded list, but also accept arbitrary input that resolves through
-	// the alias map. Description carries the alias grammar.
-	const modelParam = discovered.length
-		? Type.Optional(
-				StringEnum(
-					// Offer friendly aliases plus the full exact strings.
-					[...new Set([...MODEL_OPTIONS, ...discovered.map((e) => e.full)])],
-					{
-						description:
-							"Model alias or exact id. Friendly: 'flash' (latest Flash), 'pro' (latest Pro), 'gemini' (=flash). Add a tier: 'flash high', 'pro low'. Pin a version: '3.5 flash'. Exact: 'Gemini 3.5 Flash (Medium)'. Omit for the configured default.",
-					},
-				),
-			)
-		: Type.Optional(
-				Type.String({
-					description:
-						"Model alias or exact id. Friendly: 'flash', 'pro', 'gemini'. Add tier: 'flash high'. Omit for default.",
-				}),
-			);
+	// Model param: free string (friendly alias OR exact). Previously this
+	// was a StringEnum built from the live catalog; that made tiered/pinned
+	// aliases ("flash high", "3.5 flash") fail AJV validation before
+	// resolveModel ever saw them. Type.String() lets the resolver handle
+	// every documented form and falls back to agy for unknown slugs.
+	const modelParam = Type.Optional(
+		Type.String({
+			description:
+				"Model alias or exact id. Friendly: 'flash' (latest Flash, prefers the gemini-flash-latest alias), 'pro' (latest Pro, prefers gemini-pro-latest), 'gemini' (=flash). Add a tier: 'flash high', 'pro low'. Pin a version: '3.5 flash'. Exact: 'Gemini 3.5 Flash (Medium)'. Omit for the configured default.",
+		}),
+	);
 
 	pi.registerTool({
 		name: "AskAntigravity",
@@ -535,10 +613,23 @@ export default async function (pi: ExtensionAPI) {
 				}),
 			),
 			model: modelParam,
-			skipPermissions: Type.Optional(
+			mode: Type.Optional(
+				Type.Union(
+					[
+						Type.Literal("plan"),
+						Type.Literal("accept-edits"),
+					],
+					{
+						description:
+							"agy execution mode. 'plan' = review-only, no edits (--mode plan). 'accept-edits' = agy applies edits directly (--mode accept-edits, default). For agy's orthogonal --sandbox shell-containment flag, set the AGY_EXTRA_ARGS env var.",
+						default: "accept-edits",
+					},
+				),
+			),
+			digest: Type.Optional(
 				Type.Boolean({
 					description:
-						"Pass --dangerously-skip-permissions so agy auto-approves its own write/edit/exec tool calls. Required for tasks that mutate files. Use with care.",
+						"Request compact digests instead of full file contents. When true, the prompt is prefixed with '(Use compact digests, not full file contents.)'. Defaults on for plan, off for accept-edits.",
 				}),
 			),
 			conversationId: Type.Optional(
@@ -569,6 +660,8 @@ export default async function (pi: ExtensionAPI) {
 					details: {
 						model: null,
 						resolvedModel: null,
+						mode: "accept-edits",
+						digest: false,
 						conversationId: null,
 						exitCode: 0,
 						aborted: false,
@@ -581,6 +674,21 @@ export default async function (pi: ExtensionAPI) {
 
 			const config = loadConfig();
 			const requestedModel = (params.model as string | undefined) ?? config.defaultModel;
+			// Defensive: reject leading-dash model values that could misbind
+			// on agy's arg parser when spliced as the `--model` value. Same
+			// threat model as CONV_ID_RE — a leading-dash value can't be a
+			// model id, so refuse it instead of letting it reach argv.
+			if (typeof params.model === "string" && params.model.trim().startsWith("-")) {
+				return {
+					content: [
+						{
+							type: "text",
+							text: `model value "${params.model}" starts with "-" — not a valid model id. Use a friendly alias (e.g. "flash", "pro", "gemini") or a known exact id (e.g. "Gemini 3.5 Flash (Medium)").`,
+						},
+					],
+					details: emptyDetails(requestedModel, null),
+				};
+			}
 			const resolved =
 				resolveModel(requestedModel, discovered, config.defaultThinking) ?? requestedModel;
 
@@ -617,18 +725,32 @@ export default async function (pi: ExtensionAPI) {
 				typeof rawConvId === "string" && rawConvId.length > 0 && CONV_ID_RE.test(rawConvId);
 			const snapshot = isContinuation ? null : snapshotConversations(CONVERSATIONS_DIR);
 
+			const mode: Mode = (params.mode as Mode | undefined) ?? "accept-edits";
+			// digest default: on for plan (review-only contexts where full file
+			// contents are noise), off for accept-edits (agy applies edits and
+			// may need richer context for diffs).
+			const useDigest: boolean =
+				typeof params.digest === "boolean"
+					? params.digest
+					: mode === "plan";
+			const finalPrompt: string = useDigest
+				? `(Use compact digests, not full file contents.)\n${params.prompt}`
+				: params.prompt;
+
 			const args: string[] = ["--add-dir", cwd];
 			const extra = extraArgs();
 			if (extra.length) args.push(...extra);
 			if (resolved) args.push("--model", resolved);
-			if (params.skipPermissions) args.push("--dangerously-skip-permissions");
+			args.push("--mode", mode);
 			if (isContinuation) args.push("--conversation", rawConvId as string);
 			args.push("--print-timeout", `${timeoutMin}m`);
-			args.push("-p", params.prompt);
+			args.push("-p", finalPrompt);
 
 			const details: AgyDetails = {
 				model: requestedModel,
 				resolvedModel: resolved,
+				mode,
+				digest: useDigest,
 				conversationId: isContinuation ? (rawConvId as string) : null,
 				exitCode: 0,
 				aborted: false,
@@ -847,6 +969,8 @@ function emptyDetails(model: string | null, resolvedModel: string | null): AgyDe
 	return {
 		model,
 		resolvedModel,
+		mode: "accept-edits",
+		digest: false,
 		conversationId: null,
 		exitCode: 0,
 		aborted: false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@estebanforge/pi-ask-antigravity",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Pi tool that delegates a self-contained sub-task to Google Antigravity's agy CLI (the CLI for Gemini). Friendly model aliases (flash/pro/gemini), configurable default model + thinking, and the AskAntigravity delegation tool.",
   "keywords": [
     "pi-package",