AgentHub/docs/superpowers/specs/2026-09-29-antigravity-parity-design.md

# Antigravity parity, part D: sessions, tokens and hooks

Issue: #40 part D. Date: 2026-09-29. Status: self-reviewed (the user asked for
autonomous work with a self-review per part). Mirrors parts C1 and C2
(`2026-09-29-codex-usage-design.md`, `2026-09-29-codex-hooks-design.md`).

## Spike: what agy offers

Verified on agy 1.2.13 in an isolated `HOME`. agy keeps its login in the OS
keyring, so that run used the user's own account.

### Tokens

Not in the transcript, but in agy's own SQLite file per conversation:
`~/.gemini/antigravity-cli/conversations/<conversation id>.db`.

- `gen_metadata` has one protobuf row per model call. Field 1 is a message
  whose field 19 is the model name (`gemini-3.8-flash`) and whose field 4 is
  `ModelUsageStats`.
- The field numbers were read from the proto descriptor embedded in the
  binary: 2 input, 3 output, 4 cache write, 5 cache read, 9 thinking.
- Input does not include cache reads. Output includes thinking (171 = 73 + 98).
- `trajectory_meta.cascade_id` is the conversation id.
- `trajectory_metadata_blob` holds the workspace as a `file://` URI.
- agy 1.0.0 wrote a `.pb` file instead, and Google's service refuses 1.0.0.

### Hooks

Documented at antigravity.google/docs/hooks.
- `~/.gemini/config/hooks.json` maps hook **names** to their events:
  `PreToolUse`/`PostToolUse` (`{matcher, hooks}` groups), and `PreInvocation`,
  `PostInvocation`, `Stop` (flat handler lists). A handler is
  `{type: "command", command, timeout (s)}`.
- agy asks for no trust.
- The payload carries `conversationId`, `workspacePaths`, `transcriptPath`
  (`brain/<id>/.system_generated/logs/transcript_full.jsonl`) and `modelName`.
  `PostToolUse` adds `toolCall {name, args}`, `stepIdx` and `error`. `Stop` adds
  `terminationReason` and `fullyIdle`.
- The hook runs with its cwd in `~/.gemini/config`, and `AGENTHUB_LANE_ID`
  does not reach it.

### Traps found in the spike

- **A `PreToolUse` hook that answers `{}` DENIES the tool** ("tool call denied
  by pre-tool hook"). There is no neutral answer:
  - `allow` would override the user's permission rules;
  - `ask` would force a prompt.
- **No permission event, and no Stop when a run ends on an API error** or on a
  permission that headless mode refused.
- `invocationNum` restarts at 0 for every run, including `--continue`.
- **Running `agy` self-updates `~/.local/bin/agy`**, even with another `HOME`.
  The spike took the user's install from 1.0.0 to 1.2.13; the old binary is kept
  as `agy.<n>.old`.

## Design

1. **Sessions and tokens** (`server/lib/antigravity-usage.js`, every
   `DASHBOARD_ANTIGRAVITY_POLL_MS`, default 15 s).
   - Each conversation file is opened read-only when its mtime (or its
     non-empty `-wal`'s) changes; the mtime lives in `antigravity_conversations`.
   - It becomes a `tool = 'antigravity'` session: its name and start come from
     the transcript, its cwd from the blob, its model from the last generation.
   - Tokens are written whole, per model.
   - The status reflects the session's last activity: the newest of its file
     (a non-empty `-wal` included), its transcript and its last hook event. It
     is quiet after ten minutes when it has any hook event — mid-turn a long
     tool call writes nothing, and after a `Stop` agy may be waiting for the
     user, with no exit hook to say otherwise — and after two minutes when it
     has none.
   - When a session settles to `completed`, its agents complete too, its
     waiting flags are cleared, and its antigravity lane is set `idle`, but only
     if the hooks left it `running` and it has no `run_id`. A `Stop` that marked
     it `error` keeps that `error`.
   - A file that is not agy's (`SQLITE_NOTADB`, `SQLITE_CORRUPT`, `no such
     table`) is recorded with `session_id` `''` and retried only once it
     changes or at the next server start; any other failure is retried on the
     next pass.
   - Only the CLI's directory is read.
   - Gemini families are added to `pricing-sync.js`, taken from Vertex AI's or
     the Gemini API's LiteLLM entries.
2. **Hooks** (`server/lib/antigravity-hooks.js`, Settings → Antigravity →
   **Antigravity hooks**, `GET/POST/DELETE /api/settings/antigravity-hooks`,
   `sameOriginGuard` on the writes).
   - The named hook `agenthub` has `PreInvocation`, `PostToolUse` and `Stop`,
     each `timeout: 5`. It never has `PreToolUse`.
   - Every other named hook is kept, and a non-object file is refused
     (`EBADJSON`).
   - The command is the stable path `~/.gemini/config/agenthub-hook.sh`. The
     script runs `scripts/hook-handler.js <Event> antigravity`, prints `{}`, and
     is refreshed at every start when it is ours.
3. **Route** (`antigravityHookInput` in `server/routes/hooks.js`).
   - A hook is accepted only with a UUID `conversationId` and a
     `transcriptPath` under the CLI's directory. That keeps out the
     Antigravity IDE, which loads the same global file.
   - `session_id` is the `conversationId` and `cwd` is `workspacePaths[0]`.
   - A `PreInvocation` becomes `UserPromptSubmit` when `invocationNum` is 0,
     when the session has no event yet, when its last event is a `Stop`, when
     the session is not `active`, or when its last event is more than two
     minutes old; any other is dropped. `PostToolUse` carries
     `tool_name`/`tool_input` and `step`. `Stop` stays `Stop` — as
     `stop_reason: "error"` when it carries a non-empty `error` or a
     `terminationReason` matching `/error|fail/i`, and dropped while
     `fullyIdle` is false. Every other event is dropped.
4. **Settings → Antigravity** (`AntigravityConfig.tsx`) holds Model Pricing
   (`vendor="google"`) and the hooks card. There is no sub-tab bar, because agy
   has no config surface AgentHub edits.

## Limits (documented, not fixable from here)

- There is no "needs your permission" state for an Antigravity lane: agy has no
  hook for it.
- A lane that a dashboard pane owns (`run_id`) keeps its run-owned status, as
  it does for Codex.
- The Antigravity IDE's sessions are not read.
- Sub-agents: none were seen in a CLI run, so nothing folds them.
- The formats are undocumented: a future agy may move them. A generation that
  no longer decodes is skipped, not guessed.

## Tests

- **Server:**
  - usage: the protobuf reader; the session and per-model tokens; no re-read;
    quiet → completed; the stuck lane set idle, while a paned one is kept;
    deleted stays deleted; another tool's row untouched; a hook-made cwd kept;
    a non-SQLite file skipped;
  - hooks: install with three events and no PreToolUse; the forwarder prints
    `{}`; other named hooks kept; remove; EBADJSON; a hook switched off is
    reported; the refresh is foreign-safe;
  - route: a turn on the antigravity lane only; later PreInvocations dropped;
    tool calls in the timeline; IDE and bad-id hooks ignored; the settings
    routes, including the cross-origin refusal;
  - handler: the `antigravity` marker, and an unknown marker dropped;
  - pricing: Gemini from Vertex AI, and another vendor refused.
- **Client:** the hooks card (install, a hook switched off, Refresh, Remove, a
  refusal).
- **End to end:** an isolated server on :4851 with `AGENTHUB_GEMINI_DIR` set.
  The hook was installed through the API, then a real `agy -p` read a file.
  Seen:
  - the lane went `running`;
  - the run ended with no Stop (a shell command refused in headless mode), and
    the poll set the lane back to `idle`;
  - the session had its name, cwd, model and tokens, and `view_file` in its
    timeline;
  - Settings → Antigravity showed the card as installed, with its three events.

## Found in the code review, fixed

- **Our own read-only open looked like activity.** On a file agy closed
  cleanly, better-sqlite3's read-only open leaves an empty `-wal`, whose fresh
  mtime flipped the session back to `active` with "Last active" set to the read
  time. An empty `-wal` no longer counts.
- **The poll undid the hooks' `running` within 15 s.** Activity is now the
  newest of the file, the transcript and the session's last hook event. The
  quiet window is ten minutes, not two, when that event is not a `Stop`,
  because a long tool call writes nothing until it ends.
- **A failed run showed as "ready for input".** A `Stop` carrying an `error`,
  or a `terminationReason` naming one, now arrives as `stop_reason: "error"`,
  and the poll keeps that `error`.
- **Stops and turns.**
  - A `Stop` with `fullyIdle: false` is dropped, since background work is
    still running.
  - The first `PreInvocation` after a `Stop` is a new prompt, whatever its
    `invocationNum`.
- **A script that is not ours** at the forwarder's path is never overwritten
  or removed (`EFOREIGN`, 400), in `codex-hooks.js` too.
- **A rewritten `hooks.json` keeps its mode**, in `codex-hooks.js` too.
- **Session id and symlinks.**
  - The session id is the file name's UUID; `cascade_id` is no longer read.
  - A symlinked `~/.gemini` is matched under both paths (`agyCliDirs`).
- **Settling and bad files.**
  - A file that is not agy's is recorded, so it is not re-read and warned
    about every 15 s.
  - Settling a session to `completed` also completes its agents and clears
    their waiting flags.
- **Docs.** `.env.example` now lists `DASHBOARD_ANTIGRAVITY_POLL_MS` and
  `AGENTHUB_GEMINI_DIR`.

## Found in the whole-change review, fixed

- **An open agy looked finished after a Stop.** The ten-minute window applied
  only while the last event was not a `Stop`, so a session waiting at the
  prompt settled to `completed` two minutes after each turn. agy fires no exit
  hook, so an open agy and a closed one look the same: any session with hook
  events now gets ten minutes, a hookless one two.
- **A turn after a missed Stop was lost.** A `PreInvocation` is now also a
  prompt when the session has no event yet, is not `active` (a run that ended
  with no Stop, a session the poll settled), or its last event is over two
  minutes old — not only on `invocationNum: 0` or after a `Stop`.
- **Error Stops.** Only a non-empty `error` counts, and a `terminationReason`
  counts when it matches `/error|fail/i`.
- **A bad file was never retried, a busy one was given up on.** A file that is
  not agy's is recorded with `session_id` `''`, and those rows are deleted at
  every server start (`startAntigravityUsagePoll`), so a newer AgentHub tries
  it again; any other read failure (a busy file, our own error) is no longer
  recorded, so the next pass retries it.
- **Settling left the session waiting.** It now clears the session's own
  waiting flag as well as its agents'.
- **A forwarder path that is not a file of ours** (other content, an unreadable
  file, a directory — `scriptIsOurs`) is never overwritten (`EFOREIGN`) or
  removed, in `codex-hooks.js` too.
- **A symlinked `hooks.json`** (a dotfiles repo's) left with no hook is emptied
  through the link instead of being unlinked, in both installers.