feat(agent): add Antigravity (agy) CLI agent

[peyton-alt]

https://entire.io/gh/entireio/cli/trails/444

Summary

Status: Preview. The integration ships with IsPreview() == true — users see a "(Preview)" label in the agent selector, entire agent list, and the hook-install message. Known limitations are listed below and in docs/architecture/agent-guide.md ("Antigravity status: Preview").

First-class support for Antigravity CLI (agy), Google's successor to Gemini CLI, as a new Entire agent — the complete integration: lifecycle hooks, transcript decoding, native token counts, review-skill discovery, resume tracking, docs, and E2E wiring. Consolidates the previously stacked PRs #1356 (tokens) and #1381 (transcript decode) plus the gap-fix and review-fix rounds into this single parent.

Scope map (~7.2k insertions; ~60% tests):

Area	What
cmd/entire/cli/agent/antigravity/	agent package: 3 lifecycle hooks (pre-tool-use, pre-invocation, stop), transcript analyzers (prompts, positions, modified files), async-transcript handling, token tee (statusline.go/title_install.go), review-skill discovery
cmd/entire/cli/lifecycle.go, state.go, event.go	conditional TurnStart (resume tracking), out-of-band token baseline/delta, committed-state filtering for mid-turn commits
cmd/entire/cli/strategy/	empty-transcript degrade (agy-scoped), late-flush prompt recovery, checkpoint-scoped token resolution, agy summary/count cases
agent/skilldiscovery/	shared SKILL.md scanner (claude-code rewired onto it)
e2e + CI	agy runner with three auth modes (ADC → GEMINI_API_KEY → OAuth), trusted-workspace seeding, fatal-vs-transient classification, agy-log + hook-probe artifact capture; dispatch-only in workflows (see limitations)
docs	CLAUDE/AGENTS, architecture guide quirks section, checklist, e2e README

Real-agy quirks (all hardened in code + tests)

• invocationNum is 0-indexed; PreInvocation fires per model invocation. invocationNum > 0 emits a conditional TurnStart (Event.SuppressIfSessionActive) the dispatcher drops only when a turn is genuinely mid-flight — so resumes (agy --conversation) are tracked and follow-up invocations don't clobber the pre-prompt baseline.
• agy writes its transcript AFTER Stop. PrepareTranscript briefly waits then materializes a placeholder; condensation degrades to a files/prompt-only checkpoint (agy-scoped) and prompts are re-extracted late (resolvePromptsFromLateFlushedTranscript).
• Tokens have exactly one surface — the title/statusline JSON. The global title slot is claimed by entire hooks antigravity title-tee (wrap-preserving, doctor-checked); TurnStart snapshots a baseline, TurnEnd computes the delta (OutOfBandTokenSource).
• Tool args are double-encoded; decodeAgyString/decodeAgyBool tolerate both shapes. macOS /tmp symlinks resolved.
• No SessionStart hook surface → silent tracking (same as Cursor/OpenCode/Copilot/Pi). agy's PostToolUse/PostInvocation hooks are deliberately not installed — no lifecycle mapping, and they'd spawn a no-op subprocess per tool call.

Review & verification

• Three-dimension agent review (correctness / over-engineering / hooks-and-docs-vs-agy-1.0.15) followed by a 28-agent adversarially-verified full-implementation review; all 10 verified findings fixed (token double-counting, tokens lost on fully-committed turns, deletion-filter regression, cross-worktree title-tee uninstall, e2e retry masking, degrade scoping, hook-prefix matching, + 3 cleanups).
• Hook contract verified byte-for-byte against agy's official docs (1.0.15 changed no hook behavior).
• Analyzer methods validated against 385 real captured agy transcripts: 0 errors, 0 offset mismatches; full-pipeline replay of a real transcript reproduces prompts/files/checkpoint contents.
• Live smoke on this tip: entire agent add antigravity → real hook wiring → mid-turn commit with unwritten transcript → checkpoint + trailer + scoped tokens + entire status all correct. Real agy fired PreInvocation live (session state created); the model call itself is quota-gated (below).
• 2026-07-13 review round (3-reviewer pass + live testing on real agy): TestSingleSessionManualCommit passed live with real token counts; fresh-repo smoke verified install → live turn → commit → condensation → resume (agy --conversation) → token scoping across two commits. agy auto-updated 1.0.16→1.1.1 mid-session; hook wire contract re-verified unchanged, but agy 1.1 moved the skill-discovery directories — fixed, along with the ADC-mode quota-log peek, a doctor false-positive for non-agy teammates, an explicit Stop-hook timeout, and an agent remove warning about the global title-tee. Deferred minors are tracked as findings on trail 444.

Behavior note (all agents): the ghost-session fix intentionally changes shadow-branch preservation — a read-only ACTIVE session (no tracked files) no longer keeps its shadow branch alive on commit (phase_postcommit_test.go updated accordingly). Both checkpoint writers skip zero-file writes, so nothing such a session wrote can be stranded.

Known limitations (preview)

• Live agy E2E runs in the default matrix in agy's Gemini API-key mode (no account session; the shared GEMINI_API_KEY secret). agy ≤ 1.1.24 loaded .agents/hooks.json on that route but never executed the hooks (Hooks from .agents/hooks.json are loaded but never executed when authenticated via GEMINI_API_KEY (headless -p, 1.1.22) google-antigravity/antigravity-cli#893, still open upstream); bisecting the release binaries with a probe hook shows agy ≥ 1.1.25 executes them, and CI installs releases/latest (1.2.7 as of 2026-09-21). The optional ANTIGRAVITY_GOOGLE_APPLICATION_CREDENTIALS_JSON secret still switches the leg to ADC; the cloudcode-pa backend remains entitlement-gated (subject 110002). Fail-fast classification covers quota/entitlement walls plus GEMINI_API_KEY … not set / API_KEY_INVALID. Details in e2e/README.md.
• Transcript-derived file lists can be incomplete when agy persists a step with truncated_fields and drops TargetFile (reported by @ecgang, ~0.8% of replace_file_content calls in their corpus). Now logged as a WARN per dropped call instead of a silent skip; live PreToolUse stdin is never truncated so only the late-flush / first-turn fallbacks are affected. Awaiting a real fixture.
• Mid-turn-commit checkpoints record zero tokens (the turn's delta lands on the next condensation — totals stay correct; documented at the fallback).
• No in-agy banner (no SessionStart hook surface) — tracking is silent inside the agy UI; entire status is the visibility surface.
• First-turn mid-turn commits can produce a files/prompt-only checkpoint (agy's transcript lands after Stop); prompts recover on the next condensation.
• Token capture depends on entire hooks antigravity title-tee owning/wrapping agy's global title slot (doctor-checked, setup-repaired).
• Wire format captured on agy 1.0.14/1.0.15, re-verified unchanged on agy 1.1.1 (2026-07-13) and 1.1.22 (2026-08-27: still exactly 5 hook types; statusline/title payload unchanged). agy is fast-moving — 1.1 moved the skill directories (handled), 1.1.10 fixed hook ordering so Stop/PostInvocation fire reliably, 1.1.12 answers -p "/hooks" locally (used by entire doctor to verify the workspace hooks actually load, zero quota).

2026-08-27/28 update

• Merged origin/main (was 3 months behind): ported to local-dev removal, IsManagedHookCommand(cmd), AreHooksInstalled → (bool, error), 4-value RunIsolatedTextGeneratorCLI, main's skilldiscovery extraction.
• Fixed the CI install step: the agy release tarball ships the binary as antigravity, so the leg had never started in CI.
• Added GEMINI_API_KEY e2e mode, optional ADC, trusted-workspace seeding, agy-log + hook-probe artifacts (agy emits no log line for hook execution — the probe is how Fix external agents detection #893 was found).
• entire doctor: "Antigravity hooks: LOADED/NOT LOADED by agy" via agy -p /hooks --add-dir <root> --output-format json (version-gated ≥ 1.1.12), plus the untrusted-workspace trap from the test report.
• truncated_fields degrade path (above). Docs refreshed for 1.1.22.

2026-09-22 update (trail-444 review rounds after real Windows/macOS testing)

• Windows (confirmed on Windows 11 ARM64, agy 1.2.7): agy hands hook commands to cmd.exe, so the sh wrapper failed silently and nothing was tracked. Antigravity now installs the bare direct-shell wrapper (agent.WrapWindowsProductionSilentHookCommandDirect) when HookHostIsWindows(). The status store's root-relative names were backslash-joined on Windows and never created; they are slash-separated now and osroot.MkdirAllNoSymlink refuses backslash names.
• entire doctor: the agy -p /hooks probe was observed to run a full model turn on Windows and only proved agy parsed hooks.json, so it is opt-in (ENTIRE_ANTIGRAVITY_DOCTOR_PROBE=1). By default doctor now checks, at zero cost, that the installed hook entry is the shape this host needs (HooksEntryMatchesHost) and says how to reinstall. An unparseable agy version no longer produces "run agy update".
• Prompt loss on later-turn manual commits (user-reported, three checkpoints): the last rung of the condensation prompt ladder now extracts from the transcript bytes being stored (agent.TranscriptPromptExtractor) instead of re-reading the live path, and condensation logs which rung supplied the prompts. A new integration test runs two turns in agy's real order and commits each manually.
• Smaller: uninstall leaves a hooks.json with no Entire entry untouched; readers no longer leave orphan lock files; prune pairs a snapshot file with its lock; --add-dir must be absolute (documented, and the probe refuses a relative root); the merge-gating e2e.yml pins agy to 1.2.7 while nightly keeps latest.
• Re-test on the fixed head (2026-09-22): live two-turn agy conversation with a manual commit after each turn on entireio/entire-sandbox — both checkpoints carry the right prompt (the later turn at transcript offset 4), tokens recorded, status store under ~/.cache/entire/antigravity/status with no orphan locks, doctor clean without the probe. Full antigravity e2e suite: 48 pass / 3 skipped both locally and in CI; the 5 TestInteractive* failures were the harness, not the CLI — interactive agy in a never-run HOME shows a color-scheme chooser and a Terms consent before the prompt. The isolated HOME now seeds cache/onboarding.json as complete (established by walking onboarding in a scratch HOME and diffing), and the runner clicks through both screens as a fallback.
• Command smoke matrix (2026-09-22, sandbox, agy session present): agent list/add/remove, status (+--json), session list/current/info/tokens/stop, checkpoint list/explain/tokens/search, search, recap --static, activity, agent-help, doctor (default and with the probe opt-in), configure --summarize-provider antigravity, checkpoint explain --generate, dispatch --local --agent antigravity, clean --dry-run, disable/enable. Two real bugs found and fixed: agy 1.2.x ignores stdin in print mode, so GenerateText now passes the prompt in argv (dispatch --local had handed agy an empty prompt); and the summarizer had no condenser for agy's step JSONL, so explain --generate reported an empty transcript — antigravity.CondenseTranscript now feeds it. Both re-verified live.
• Shadow-branch pinning (review finding on the smoke-matrix head): the ghost-session fix had narrowed "active session with uncondensed content" to "active session with tracked files", which would let a sibling's condensation delete the only checkpoint of a session whose first step captured a transcript before any edit. The gate now uses the same test condensation uses (sessionHasShadowContent: files, written steps, or task checkpoints); the ghost still has none of those. Table test covers files-only and steps-only.
• Merged origin/main a third time (session-store tests; no code conflicts).
• Windows, on a real Windows host (2026-09-22 evening): the antigravity leg is now dispatchable in e2e-windows.yml (agy 1.2.7 from agy_cli_windows_x64.zip, API-key mode; the harness redirects USERPROFILE with HOME so agy and the entire hooks it spawns agree on the isolated home). TestSingleSessionManualCommit passed on windows-latest (run 35803986610): the cmd.exe wrapper fired PreInvocation/PreToolUse/Stop, agy wrote the file through a PreToolUse hook, the Stop hook saved the shadow checkpoint, and the commit carries its Entire-Checkpoint trailer. The first run failed only on the harness's sh -c probe hook, which cmd.exe cannot run and which made agy refuse the tool call; the probe now skips itself on Windows. Runner is x64; ARM64 remains the reviewer's manual evidence. Follow-up: add antigravity to the nightly Windows leg.
• 2026-09-23: Victor's Windows and review-round fixes landed directly on the branch. On top of them: the title-tee idempotency test stands up an agy on PATH (the tee is now only claimed where agy exists); the summary prompt's [Files Modified] list is bounded like the transcript; the e2e harness removes Antigravity's isolated home with the repo; the commit fast path treats only a missing or store-refused transcript as "no content" (any other stat error fails toward condensing); and the title-tee now preserves a pre-existing user title command on Windows — --wrap-b64 <base64url> where agy runs the slot through cmd.exe, re-run through cmd.exe by the tee, with uninstall restoring either form byte for byte. Previously that case failed on every model call on Windows (no tokens, user title gone); an older finding had deferred it with "revisit if agy ships on Windows". Review round on that head: a TTY mid-turn commit before agy's first Stop lost its trailer because the slow path required transcript growth before looking at hook-captured files (fixed: files carry the decision, growth is the fallback); the summary-prompt bounds had leaked into explain --full (display formatter is unbounded again, LLM callers use FormatCondensedTranscriptForPrompt); the Antigravity install hint used backticks the picker mangles.
• Merged main again for agent: remove IsPreview from the Agent interface #2554: agent.IsPreview is gone, so Antigravity's preview status is documentation only (AGENT.md, agent-guide.md); this branch's own selector/list preview labels were reverted before that.

2026-09-21 update

• Merged origin/main again (~905 commits; 14 conflicts). Main deleted e2e-isolated.yml / e2e-checkpoints-v2.yml and gave e2e.yml a test regex input, so the antigravity CI wiring now lives only in e2e.yml. Adapted to main's checks: StepContext.MetadataDirAbs removal, the writeTestFile helper removal, goconst on the hook type literal, the transcript-read ratchet (transcript_read_guard_test.go; antigravity registers one read like every other agent), the e2e prompt-timeout chain (boundPrompt), the userdirs consumer audit (the statusline tee now resolves through userdirs.CacheDirChecked), and the summary-capable provider pin (antigravity has GenerateText, so it joins the list and the README).

• Fix external agents detection #893 verified fixed upstream in agy 1.1.25 by bisecting real release binaries in an isolated HOME with modelProvider: gemini and a probe hooks.json: 1.1.22/1.1.23/1.1.24 fire nothing, 1.1.25/1.2.0/1.2.7 fire PreInvocation + Stop. The release notes never mention it. The antigravity leg is back in the default e2e.yml matrix and the dispatch-only caveats are rewritten (AGENT.md, agent-guide.md, e2e/README.md).

• Nightly install smoke (nightly-e2e.yml) gains an antigravity leg on Linux and macOS (agy from the latest release tarball, API-key mode, 25-minute step cap for the 2.5x multiplier). It can only go green once this PR is in a published nightly, since that workflow checks out the nightly tag.

• Model bump: agy 1.2.x dropped gemini-3.5-flash-low from agy models (both auth modes) and rejects it with invalid model selection; the harness default is now gemini-3.8-flash-low.

• CI run 35650998214 then passed TestSingleSessionManualCommit for antigravity in API-key mode (no ADC secret present, agy from releases/latest): the org GEMINI_API_KEY is valid and the full hook set, PreToolUse included, executes on that route.

• Live smoke on entire.io (2026-09-21): entire built from this branch drove real agy 1.2.7 sessions in API-key mode against entireio/entire-sandbox on both checkpoint backends — git-branch session (checkpoint 593b557e273d) and git-refs session (checkpoint 01M33B0YNF2RDS4ANXE7H8PZ2E). Hooks, title-tee, trailer, condensation, push and ingestion all worked; the three trail-444 findings (dedup/append race, bare os.Remove in prune, os.Stat on the transcript path) are fixed in 9f688a8763 by anchoring the status store on userdirs.CacheRoot and locking the dedup-append.

Follow-ups (deliberately out of scope)

• Record the model: agy's PreInvocation payload carries modelName, but checkpoint metadata leaves model empty today.
• entire.io's activity view labels these sessions "Unknown" while the search index says Antigravity — a web-side display mapping, not this repo.
• entire doctor could warn when agy < 1.1.25 runs in API-key mode (hooks load but never execute there).

Test plan

• mise run check green locally (fmt, lint 0 issues, unit + integration + canary) — re-run 2026-09-21 on the merged tree
• CI green on the merged tip
• e2e.yml antigravity leg green in API-key mode on agy latest, no ADC secret — run 35650998214 (TestSingleSessionManualCommit, 2026-09-21)
• Analyzer validation against 385 real transcripts + real-transcript pipeline replay
• Live smoke of install → hooks → commit → checkpoint → status on this tip
• mise run test:e2e --agent antigravity TestSingleSessionManualCommit — passed live 2026-07-13 (real agy, real tokens in the condensed checkpoint)
• Live fresh-repo smoke 2026-07-13: enable → live agy turn → commit/trailer/condensation → resume via agy --conversation → checkpoint-scoped token deltas across two commits

🤖 Generated with Claude Code

---

Note

Medium Risk
New agent code paths affect session lifecycle, hook-installed repo files, and checkpoint condensation; risk is mitigated by extensive tests but behavior depends on undocumented agy wire formats.

Overview
Adds preview first-class support for Antigravity CLI (agy): a new antigravity agent package that registers with Entire, installs five workspace hooks into .agents/hooks.json (entire entry → entire hooks antigravity <verb>), and maps hook stdin to lifecycle events (TurnStart, ToolUse, TurnEnd).

Lifecycle behavior is tailored to real agy quirks: TurnStart only when invocationNum == 0 (follow-up pre-invocations are ignored so baselines aren’t reset); Stop with fullyIdle → TurnEnd (so SaveStep/checkpoints run); post-invocation is a no-op because transcripts aren’t ready yet; PrepareTranscript creates an empty placeholder when the transcript file is still missing after stop. Pre-tool-use records touched files from mutating tools, including double-encoded args and parent-dir symlink normalization (macOS /tmp).

Also wires non-interactive GenerateText via agy -p, JSONL transcript chunk/reassemble (passthrough v1), registry/hooks CLI imports, integration tests over subprocess hooks, and optional E2E registration when agy is on PATH.

^{Reviewed by Cursor Bugbot for commit f141838. Configure here.}

[Copilot]

Pull request overview

Adds first-class preview support for the Antigravity (agy) CLI agent, wiring it into Entire’s agent registry, hook handling, transcript lifecycle, text generation, integration tests, and optional E2E coverage.

Changes:

• Introduces a new agent/antigravity package with identity, hook install/uninstall, lifecycle parsing, transcript handling, text generation, and discovery stubs.
• Registers Antigravity in hook routing, agent constants, tests, and E2E agent support.
• Adds fixtures and unit/integration coverage for Antigravity hook payloads, lifecycle behavior, hook config management, and transcript preparation.

Reviewed changes

Copilot reviewed 24 out of 24 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
e2e/agents/antigravity.go	Adds E2E runner support for agy.
e2e/agents/antigravity_test.go	Adds basic E2E agent identity tests.
cmd/entire/cli/integration_test/antigravity_test.go	Adds integration coverage for Antigravity hook flow.
cmd/entire/cli/hooks_cmd.go	Registers Antigravity hooks command package.
cmd/entire/cli/agent/registry.go	Adds Antigravity agent name/type constants.
cmd/entire/cli/agent/generate_external_test.go	Adds Antigravity text generation test coverage.
cmd/entire/cli/agent/antigravity/antigravity.go	Defines Antigravity agent identity and core methods.
cmd/entire/cli/agent/antigravity/antigravity_test.go	Tests agent registration, interfaces, and presence detection.
cmd/entire/cli/agent/antigravity/discovery.go	Adds review skill discovery stub.
cmd/entire/cli/agent/antigravity/generate.go	Adds non-interactive agy text generation.
cmd/entire/cli/agent/antigravity/hooks.go	Adds .agents/hooks.json install/uninstall/status handling.
cmd/entire/cli/agent/antigravity/hooks_test.go	Tests hook config installation behavior.
cmd/entire/cli/agent/antigravity/lifecycle.go	Maps Antigravity hook payloads to Entire lifecycle events.
cmd/entire/cli/agent/antigravity/lifecycle_test.go	Tests lifecycle parsing and file extraction edge cases.
cmd/entire/cli/agent/antigravity/transcript.go	Adds JSONL transcript read/chunk/reassemble and preparation.
cmd/entire/cli/agent/antigravity/transcript_test.go	Tests transcript round-trip and placeholder creation.
cmd/entire/cli/agent/antigravity/types.go	Defines Antigravity hook payload/config types.
cmd/entire/cli/agent/antigravity/types_test.go	Tests fixture decoding for hook payload types.
cmd/entire/cli/agent/antigravity/testdata/hook_stdin_pre_invocation.json	Adds PreInvocation fixture.
cmd/entire/cli/agent/antigravity/testdata/hook_stdin_post_invocation.json	Adds PostInvocation fixture.
cmd/entire/cli/agent/antigravity/testdata/hook_stdin_pre_tool_use.json	Adds PreToolUse fixture.
cmd/entire/cli/agent/antigravity/testdata/hook_stdin_post_tool_use.json	Adds PostToolUse fixture.
cmd/entire/cli/agent/antigravity/testdata/hook_stdin_stop.json	Adds Stop fixture.
cmd/entire/cli/agent/antigravity/testdata/transcript_sample.jsonl	Adds sample Antigravity JSONL transcript fixture.

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit f141838. Configure here.}