Govern Google Antigravity with Agentic Control Plane

See and control every tool call Antigravity makes — shell, file edits, browser actuation, MCP tools, subagents — from one dashboard, alongside your Claude Code, Codex, Cursor, and Grok Build sessions. Antigravity's hook vocabulary has a native ask; this hook puts your policy on that path.

TL;DR

curl -sf https://agenticcontrolplane.com/install.sh | bash

irm https://agenticcontrolplane.com/install.ps1 | iex

The installer detects Antigravity (the agy CLI or an existing ~/.gemini/antigravity-cli profile), drops the hook at ~/.acp/hooks/antigravity/hook.mjs, merges the registration into ~/.gemini/config/hooks.json (shared by the CLI, the IDE, and the app — merged under an acp key, never overwritten), and opens your browser once to provision a workspace into ~/.acp/credentials. The next Antigravity session is governed.

MIT-licensed, zero dependencies, one readable file — read it before you run it.

The ask that stays an ask

Antigravity is the first harness we’ve integrated whose hooks can hand a call to the human natively. When ACP policy answers ask, the hook returns force_ask — Antigravity renders its own approval card, and because force_ask deliberately ignores cached “Always Allow” grants, a local remembered approval can’t pre-empt a policy hold. (On Grok Build we document the opposite caveat — a local allow rule outranks an ACP ask. Here that gap doesn’t exist.)

Unattended, the same answer resolves correctly with no work on our side: headless Antigravity soft-denies unobtainable approvals itself, continuing the run with a stderr notice. The empty chair answers “no” natively.

What gets installed and where

The installer is idempotent: the merge writes the same acp key every time, so re-running it updates the registration rather than duplicating it. On a machine without Antigravity the section is a no-op. Under --local it is skipped and says so — this hook needs a workspace.

How it works

One layer, not three. Codex and Claude Code installs wire a hook, an MCP connector, and a model proxy; Antigravity gets the hook, and that’s a deliberate consequence of how Antigravity is built:

1. Hook layer — PreToolUse with matcher * reaches every tool call Antigravity dispatches: shell, file edits, browser actuation, MCP tools, and subagents, across every surface that reads the shared hooks.json. Because MCP tool names pass through the hook unchanged, MCP calls are checked on the same path as everything else — there is nothing for a separate connector to cover.
2. No model proxy. Antigravity’s Gemini endpoint is fixed; there is no base-URL override to point at the ACP proxy. So the cost X-ray that meters Claude Code, Codex, and Cursor model calls is not available here — Antigravity is listed as tool-call control only on that page, and this install writes nothing for it. Hooks see tool calls, not tokens.
3. Audit layer — every checked call lands in your ACP activity log as one row under the client name antigravity-hook, with the canonical tool name, the native tool name, the decision, its reason, the tier, and the session id.

What’s on the wire

Tool names. Antigravity’s native names (run_command, view_file, replace_file_content, …) are mapped to the canonical vocabulary before the policy check so content floors fire on input shape, with the native name preserved in the audit record as client_tool_name. run_command’s command string travels in args.CommandLine (verified live) and is lifted into the canonical command field alongside. Unknown and MCP tool names pass through. The full map is on the control-model page.

Failure posture

Antigravity’s hook core is fail-closed: a crashed, timed-out, or non-zero-exiting hook blocks the tool call. That’s the right default for a policy path — and it means a hook must never let an upstream outage become its own crash. This hook always answers in JSON with exit 0 and carries its own posture: gateway unreachable in an attended session fails open, loudly ([ACP] ⚠ UNGOVERNED plus a durable ~/.acp/lapse.log line — an ACP outage must never brick your session); unattended tiers fail closed. One retry on transport failure; an HTTP error status is the server answering and is never retried. The internal 4-second decision budget sits far below the registered 30-second timeout, so the answer always arrives before Antigravity’s error path.

One Antigravity-specific note: the hook environment is sanitized, so configuration rides in ~/.acp/config.json (snake_case keys), not env vars. Unattended fleets should pin "agent_tier": "background" there.

Setting up policy

Policy is set from the dashboard; the hook carries what the rules need to key on.

Tool policies. Rules key on the canonical vocabulary the hook maps to — Bash, Read, Write, Edit, Glob, Grep, WebSearch, WebFetch, Task — and, for shell, on the sub-command the gateway classifies from the leading token (Bash.git, Bash.npm, Bash.docker, …). A rule on Bash.git therefore covers run_command calls whose CommandLine starts with git, whatever Antigravity called the tool. MCP tools arrive under their own names.

Tiers. Antigravity’s payload has no permission-mode field, so the tier is the hook’s to resolve — in this order: ACP_AGENT_TIER if it reaches the hook, then agent_tier in ~/.acp/config.json, then background if CI is set in the environment, else interactive.

Standing floor. Above every workspace’s rules, a short hardline list denies unconditionally — recursive delete of the root, a system directory, or the home directory; mkfs; dd or a redirect onto a raw block device; a fork bomb; kill -1; shutdown, reboot, init 0/6, systemctl poweroff. The control-model page walks the live-verified case with the exact reason string.

Manual install

mkdir -p ~/.acp/hooks/antigravity ~/.gemini/config
curl -fsSL https://raw.githubusercontent.com/agentic-control-plane/antigravity-acp-plugin/main/hook.mjs \
  -o ~/.acp/hooks/antigravity/hook.mjs
# Merge the registration (never overwrite — hooks.json is shared):
curl -fsSL https://raw.githubusercontent.com/agentic-control-plane/antigravity-acp-plugin/main/hooks/acp.json \
  -o /tmp/acp-agy-hooks.json
node -e 'const fs=require("fs");const p=process.env.HOME+"/.gemini/config/hooks.json";let cur={};try{cur=JSON.parse(fs.readFileSync(p,"utf8"))}catch{};const add=JSON.parse(fs.readFileSync("/tmp/acp-agy-hooks.json","utf8"));fs.writeFileSync(p,JSON.stringify({...cur,...add},null,2))'

Credentials live at ~/.acp/credentials (the installer provisions them; or paste a workspace key from cloud.agenticcontrolplane.com). Check registration inside Antigravity with /hooks.

What you’ll see in the dashboard

Once a session has run, your console shows the calls under the client name antigravity-hook (the hook identifies itself as antigravity-hook/<version> on every request). Each row carries:

• tool_name — the canonical name the policy keyed on (Bash, Edit, …)
• client_tool_name — what Antigravity actually called (run_command, replace_file_content, …)
• the decision and its reason — for a deny, the reason is the same text the hook returned to Antigravity after its [ACP] Denied by policy: prefix
• agent_tier, and the session id, which is Antigravity’s own conversationId

That session id is what the end-of-session receipt links to: [ACP] Session receipt: N tool calls governed · … — review this session: https://cloud.agenticcontrolplane.com/sessions/<conversationId>. The receipt prints once, at Stop, and only for sessions in which at least one call was checked.

Troubleshooting

Hook isn’t firing. Inside Antigravity, /hooks lists what’s registered. Then check ~/.gemini/config/hooks.json has an acp key with "enabled": true and the three events — a hand-edit that dropped the key is the usual cause. The registration runs node "$HOME/.acp/hooks/antigravity/hook.mjs" …, so Antigravity has to be able to launch node; on a fail-closed core, a hook it can’t launch reports pre-tool hook failed and blocks the call rather than skipping it.

Nothing fires under --dangerously-skip-permissions. By design — Antigravity’s, not ours. The flag removes the hook layer entirely (verified live), so no hook is consulted and there is no record. Unblock headless runs with scoped permissions.allow rules instead.

[ACP] ⚠ UNGOVERNED: no credential. The hook found neither ACP_BEARER_TOKEN nor ~/.acp/credentials. Calls proceed unchecked until you connect: re-run the installer, or paste a workspace key into ~/.acp/credentials. Every such call also writes a ~/.acp/lapse.log line.

[ACP] ⚠ UNGOVERNED: gateway unreachable (…). An attended session failed open — the call ran without a policy check, and the lapse is logged. Check govern_base in ~/.acp/config.json if you’ve overridden it, and outbound network from the machine. One retry already happened before the warning; an HTTP error status from the gateway is never retried.

Every call is denied on a CI runner. The runner resolved to the background tier (set CI or a pinned agent_tier) and the gateway was unreachable, so the hook failed closed: the reason reads [ACP] Gateway unreachable (…) — background tier stays blocked when policy can't be consulted. That’s the intended safety net. Fix reachability and credentials on the runner; if you decide an outage should let that runner through, set "agent_tier": "interactive" in its ~/.acp/config.json, knowing the trade is a loud warning instead of a block.

No receipt at the end of the session. The receipt prints only when at least one call was checked, and only from the Stop hook — if the Stop entry is missing from the acp key, re-run the installer. Counters live in ~/.acp/antigravity-sessions/<conversationId>.json between calls.

Antigravity was skipped under --local. Expected: ACP’s on-device engine isn’t wired for Antigravity, and the installer says so. Run without --local to connect a workspace.

A force_ask card doesn’t look the way this page describes. This page doesn’t describe it — how the interactive TUI renders a force_ask reason is not something we have verified live, so it’s listed as pending below rather than pictured.

Verified vs. pending

Live-verified end to end on agy 1.1.21 (2026-08-26): the hook fires in real turns before the native permission layer; run_command’s payload key is CommandLine, normalized to the canonical shape — the production hardline floor denied a recursive root delete under the native tool name; headless soft-deny and the session receipt behave as documented.

One verified limit to plan around: --dangerously-skip-permissions bypasses the hook layer entirely — this hook (and any other) is simply not invoked under the flag, unlike Claude Code and Grok Build. Scoped permissions.allow rules, not the flag, are the right way to unblock headless runs; if you operate a fleet, treat the flag’s appearance as an alertable event. Still pending: force_ask rendering in the interactive TUI (offline-verified against the documented contract).

Verify the installer

The installer is open source — read every line before you run it.

How Antigravity’s own controls work — the permissions engine, sandbox, headless posture, and the enterprise plane: the control-model page. The permission rule language on its own: the permissions reference.

Frequently asked questions

Related

• Antigravity hooks reference — the five events, the stdin payload, the decision contract, fail-closed, and how to write your own
• Antigravity permissions reference — allow / ask / deny, the seven actions, prefix and regex: matching, the presets
• Antigravity’s control model, explained — the deep page, with a live-verified blocked call end to end
• Claude Code — the sibling hook contract, fail-open instead of fail-closed
• Codex CLI — hook plus MCP connector plus model proxy, the three-layer install
• Turn on Cost X-Ray — which harnesses can be metered, and why Antigravity isn’t one of them