Gemini delegation

Gemini/Antigravity Delegation — Human-Relayed Handoff

Overview

Claude Code is always the orchestrator. Gemini runs inside the Antigravity IDE, which has no headless CLI — antigravity-ide chat only drives the running GUI and returns empty stdout with exit 0, so there is no way to read a result back programmatically. Every delegation therefore costs the user one manual relay step: they open Antigravity and give Gemini a single instruction.

Because of that cost, this is not a default. Propose it, state the payoff, and let the user decide.

The payoff is real and measured. On a repo-wide audit (2026-07-26) Gemini read 25 files / 194 KB (~49,600 tokens) while this orchestrator spent ~2,500 tokens writing the brief and verifying the result — roughly 95% saving, ~20x leverage. That ratio is the entire reason the mechanism exists.

Why not the SDK or the API

Two dead ends, both verified — do not re-investigate without new information:

• google-antigravity Python SDK: headless, but authenticates only via GEMINI_API_KEY or Vertex + ADC (confirmed by reading its models.py). There is no OAuth path, so it cannot reuse the IDE's Gemini Pro login. Using it would bill a separate API account rather than the existing plan.
• antigravity-ide chat -m ask|edit|agent: exists, but only sends the prompt into the GUI. Exit 0, empty stdout, no readable result.

The Gemini Pro plan quota — the thing that makes this cheap — is reachable only through the IDE, and the IDE is reachable only through a human.

When to Delegate

Strong fit — this is where the leverage is:

Task shape	Why Gemini
Read >5 files, then summarize/compare	Its context is cheap; ours is not
Repo-wide audit ("where else does X appear?")	Breadth beats depth here
Independent review of a design or diff	A second model catches different things
UI verification / screenshots / recordings	The orchestrator cannot do this at all
Scoped code writing behind an explicit fence	Proven workable — see the fencing rule below

Poor fit:

• Anything needing this conversation's history — the handoff file is the only context Gemini receives.
• Architecture and product decisions. Those stay with the orchestrator.
• Small mechanical edits — use Kilo CLI instead; it is headless and does not cost the user a relay step.

Rule of thumb: if the task is small enough that Kilo CLI can do it, use Kilo CLI. Gemini earns its relay cost only on breadth.

Invocation

Write the brief, then hand the user exactly one line to relay.

1. Write .gemini/antigravity/handoff/inbox/<slug>-plan.md (format: .gemini/antigravity/handoff/README.md).
2. Tell the user, verbatim:

   Open Antigravity, tell Gemini to read .gemini/antigravity/handoff/inbox/<slug>-plan.md and write its report to .gemini/antigravity/handoff/outbox/<slug>-report.md.

3. .claude/hooks/session_start.py announces new outbox/*-report.md files at the next session start.

Writing the Brief — Four Rules Learned From Failures

Each of these fixed an observed, reproduced failure. They are not style preferences.

1. Fence the scope, and name the expected failure. Gemini follows an explicit fence well, but "don't break things" is too vague to act on. When a correct result will make a gate go red, say so — otherwise it will helpfully "fix" the drift it was told only to detect:

- **Do NOT fix any of the drifts you find.** You will almost certainly make
  `python tools/garden.py` start FAILING, because there are real stale counts
  in the repo right now. **That failure is the expected, correct outcome.**

2. Demand evidence, never self-assessed confidence. A "Confident? Y/N" column came back 22-for-22 "Yes" — including on a finding that was wrong. The column carried zero information. Require the command and its output instead:

| Claim | Command run | Output (trimmed) |
Do not write a claim you did not actually run a command for.

3. Say explicitly which files may be touched — including the brief. The handoff README permits updating status: in the plan file; a brief saying "modify nothing but the report" contradicts it. Resolve it in the brief: "Do NOT edit this file. Leave status: pending."

4. State the ground truth measurement, not the number. Tell it how to measure (ls .kilo/skill | wc -l), never what the answer should be. A brief that leaks the expected answer cannot detect that the answer changed.

After Delegating — Verify 100%, Always

Both controlled tests produced errors that were invisible in Gemini's own summary and surfaced only under verification:

• Audit run: 1 of 22 findings was factually wrong, marked "Confident: Yes".
• Code run: shipped 2 false positives while self-reporting "unsure about: nothing".

The operating rule that follows: its evidence tables are reliable; its self-assessment is not. Never let a self-report substitute for a check.

1. Re-run every command in its evidence table yourself. Spot-checking is not enough — the wrong row looked exactly like the right ones.
2. Run the project's real gates (make check, python tools/garden.py, targeted pytest, security_scan.py).
3. For new checks, mutation-test them: break the thing the check guards and confirm the check goes red. A check that cannot fail is not a check.
4. For new code, re-derive the ground truth independently before accepting any list of "problems found" — false positives are the failure mode.

Concurrent-Edit Safety

Gemini edits the same working tree at the same time as this session. Before delegating anything that writes:

• Take a tools/shared_state.py lock for the files in scope; acquire_lock() returns False on a cross-engine conflict.
• Name every writable path in the brief and forbid everything else.
• Never delegate a write that overlaps a file being edited in this session.

Gemini also keeps its own artifacts outside the repo at ~/.gemini/antigravity-ide/brain/<session-uuid>/ (*.md + .metadata.json, plus .system_generated/logs/transcript.jsonl). Those are machine-readable and useful for auditing what it actually did — but they are not the handoff channel. The report file in outbox/ is.

Anti-patterns

Don't	Do Instead
Delegate a small mechanical edit to Gemini	Use Kilo CLI — headless, no relay cost to the user
Trust its "Confident: Yes" / "unsure about: nothing"	Re-run its evidence commands yourself
Write a brief without an explicit writable-file list	Fence the scope; name every path it may touch
Put the expected answer in the brief	Give the measurement command, not the number
Let a correct-but-red gate look like failure	Predict the red gate in the brief and call it correct
Delegate a write without a shared-state lock	acquire_lock() first; both engines share one tree
Try the SDK or antigravity-ide chat for a headless run	Neither reaches the Pro plan; use the file handoff