WEB-4656: add Antigravity 2.0 hooks setup (Subscription mode)

[thatcatfromspace]

Summary

Adds Google Antigravity CLI (agy 1.0.5+) as a supported tool in this repo. Subscription (hooks) mode only. Pairs with the ai-gateway-data PR (#2109) for the control-plane enum.

Scope change during review: Originally targeted both the Antigravity 2.0 desktop IDE and the CLI via ~/.antigravity/settings.json. Empirical testing against agy 1.0.5 proved that path is never read and that several event types we wired (UserPromptSubmit, SessionStart) are silently dropped. The integration has been rewritten end-to-end against the verified agy CLI contract. Full empirical findings: see AGY-EMPIRICAL-FINDINGS.md at the workspace root.

Verified contract (from three empirical passes)

Aspect	Verified value
Install path	~/.gemini/config/hooks.json (single user-level location)
Schema wrap	{"hooks": {EVENT: [{matcher, hooks:[{type, command}]}]}}
Catch-all matcher	"" (empty string)
Supported events	PreToolUse, PostToolUse only. PreInvocation/PostInvocation/Stop parse but never exec. UserPromptSubmit/SessionStart silently dropped.
Stdin payload	camelCase: {conversationId, stepIdx, toolCall: {name, args}, transcriptPath, workspacePaths, artifactDirectoryPath}. PostToolUse adds error, may have toolCall: null
Stdout (override-allow)	Bare `{"decision": "allow"
Tool names	agy-native lowercase: run_command, view_file, edit_file, write_to_file, codebase_search, ask_permission (plus browser/notebook/subagent families). Args use PascalCase keys
Verified deny enforcement	Yes — {"decision":"deny","reason":"..."} blocks the tool call; reason reaches the model verbatim

What's installed

Per user:

• ~/.gemini/config/hooks.json — registers PreToolUse + PostToolUse hooks pointing at our scripts. Non-destructive merge (third-party hooks preserved).
• ~/.unbound/antigravity-hooks/unbound_pre_tool_use.py — policy decision script. POSTs to ${gateway}/hooks/antigravity with unbound_app_label: 'antigravity', maps response to bare native-proto decision.
• ~/.unbound/antigravity-hooks/unbound_post_tool_use.py — telemetry. Defensively skips POST when toolCall: null (agy fires PostToolUse on every step including non-tool turns).
• ~/.unbound/antigravity-hooks/_common.py — shared helper for stdin parsing, per-tool command/metadata extraction, urllib-based gateway POST (no curl argv leak), fail-open contract.
• ~/.unbound/config.json — api_key + gateway_url. Atomic write, O_NOFOLLOW, 0o600.

MDM variant enumerates user homes and runs the per-user installer under privilege drop.

Per-tool field extraction (in _common.py:_extract_command_and_metadata)

agy tool	command ←	metadata extras
run_command	args.CommandLine	cwd: args.Cwd
view_file	args.AbsolutePath	file_path: args.AbsolutePath
edit_file	args.Instruction	file_path: args.TargetFile, code_markdown_language
write_to_file	""	file_path: args.TargetFile
codebase_search	args.Query	target_directories: args.TargetDirectories
ask_permission	Action: Target	target, action, reason
(unknown future tool)	JSON-stringified args	args: <opaque>

Test plan

• antigravity/hooks/test_setup.py — 14/14 (install/clear, atomic write, idempotency, third-party preservation, catch-all matcher, unsupported-event regression)
• antigravity/hooks/scripts/test_hooks.py — 26/26 (agy-shape stdin fixtures × 6 tool names, null-toolCall skip, env-var conversationId fallback, allow/deny/ask, fail-open on every infra error, no-curl regression, gateway URL bake-in)
• antigravity/hooks/mdm/test_setup.py — 11/11 (MDM creds write, no argv leak, catch-all matcher, unsupported events absent, per-user path migration)
• claude-code/hooks/test_setup.py regression — 7/7 (no collateral damage)
• CI green pre-merge
• End-to-end on a real agy install once merged

Linear

WEB-4656 (sub-issue of WEB-4655).

Follow-up tickets, not blocking this PR

• WEB-4657 (gateway handler + dashboard card) — must drop the L442 UserPromptSubmit OR-clause from its plan; agy never fires it. APP_NATIVE_FILE_TOOLS['antigravity'] should use agy's real tool names from the table above.
• Antigravity 2.0 desktop IDE support — deferred. Would require its own path/contract investigation (different surface, different config root: ~/Library/Application Support/Antigravity/User/).

Greptile Summary

This PR adds Antigravity CLI (agy 1.0.5+) hook support in subscription mode, wiring PreToolUse (policy gate, synchronous) and PostToolUse (telemetry, async) into ~/.gemini/config/hooks.json. The implementation is grounded in three empirical passes against the real agy binary and replaces an earlier, incorrect scope that targeted unsupported events and a config path agy never reads.

Confidence Score: 5/5

The change is safe to merge: both hook scripts and installers correctly implement fail-open behavior, O_NOFOLLOW credential writes, and urllib-only authenticated calls.

All previous security concerns are addressed in the current code. The two remaining findings are narrow defensive hardening points that do not affect normal operation or policy enforcement.

antigravity/hooks/scripts/_common.py (_NoRedirectHandler) and antigravity/hooks/setup.py (rewrite_gateway_url_in_file) warrant a second look, but neither blocks merge.

Important Files Changed

Filename	Overview
antigravity/hooks/scripts/_common.py	Shared runtime helper: stdin parsing, credential loading, per-tool arg extraction, gateway POST via urllib. Clean fail-open contract overall; the _NoRedirectHandler returns None instead of raising, causing an AttributeError that escapes the post_to_gateway except clause (caught only by outer callers).
antigravity/hooks/setup.py	User-level installer: OAuth callback, config write (O_NOFOLLOW present), hook-script copy+URL bake, non-destructive hooks.json merge. The rewrite_gateway_url_in_file step does a non-atomic read+write_text that can leave _common.py empty on crash/disk-full.
antigravity/hooks/scripts/pre_tool_use.py	PreToolUse hook: reads agy stdin, POSTs to gateway, emits bare native-proto deny/ask on non-allow response. Fail-open on every error path. Correct agy stdout shape (no hookSpecificOutput wrapper).
antigravity/hooks/scripts/post_tool_use.py	PostToolUse telemetry hook: skips POST when toolCall is null (non-tool agy steps), delegates to fire_and_forget_telemetry. Minimal, correct, fail-open.
antigravity/hooks/mdm/setup.py	MDM installer: privilege-drop via fork, O_NOFOLLOW on all writes, in-memory URL substitution before write, urllib (not curl) for all authenticated requests. Solid security posture. Only PreToolUse and PostToolUse installed.
antigravity/hooks/scripts/test_hooks.py	26 hook-script integration tests using a real local HTTP server; covers all 6 agy tool shapes, null-toolCall skip, env-var conversationId fallback, allow/deny/ask decisions, fail-open on infra errors, and no-curl regression.
antigravity/hooks/test_setup.py	Setup integration tests: isolated HOME via reload, covers install/clear/idempotency, third-party hook preservation, catch-all matcher verification, unsupported-event regression lock.
antigravity/hooks/mdm/test_setup.py	MDM tests: _write_unbound_config_payload mode/permissions, config-before-hooks ordering, catch-all matcher, no-curl assertion for authenticated calls.

Sequence Diagram

sequenceDiagram
    participant agy as agy CLI
    participant pre as unbound_pre_tool_use.py
    participant post as unbound_post_tool_use.py
    participant common as _common.py
    participant gw as Unbound Gateway

    agy->>pre: stdin JSON (PreToolUse, camelCase)
    pre->>common: read_stdin_event()
    pre->>common: load_credentials()
    pre->>common: build_request_body(event, "PreToolUse")
    pre->>common: post_to_gateway(body, api_key, gateway_url)
    common->>gw: POST /hooks/antigravity (urllib, Authorization header)
    gw-->>common: "{"decision":"deny","reason":"..."}"
    common-->>pre: parsed dict
    pre->>agy: "stdout {"decision":"deny","reason":"..."} + exit 0"
    Note over pre,agy: Empty stdout + exit 0 = silent allow

    agy->>post: stdin JSON (PostToolUse, toolCall may be null)
    post->>common: read_stdin_event()
    alt toolCall is dict
        post->>common: fire_and_forget_telemetry(event, "PostToolUse")
        common->>gw: POST /hooks/antigravity (async, best-effort)
    else toolCall is null
        post->>agy: exit 0 (skip — non-tool step)
    end

Loading

_{Reviews (5): Last reviewed commit: "WEB-4656: rewrite Antigravity hook contr..." | Re-trigger Greptile}

[thatcatfromspace]

Greptile findings addressed:

Finding	Severity	Commit
UserPromptSubmit hook blocks prompt submission (missing async: True) — user-level	P1	cde71b5
Same UserPromptSubmit async issue — MDM variant	P1	cde71b5
write_unbound_config user-level open missing O_NOFOLLOW (MDM had it)	P2	cde71b5
install_for_user_payload docstring incorrectly claimed args are pickled across fork (they're inherited via copy-on-write; only the return value pickles)	P2	cde71b5
API key exposed in curl argv at runtime — hook-script POST shells out to curl -H "Authorization: Bearer <key>", leaking the bearer token to local users via ps auxe / /proc/<pid>/cmdline on every PreToolUse and telemetry call	P1 Security	766fbeb

The P1 security fix migrates _common.py::post_to_gateway from curl to stdlib urllib.request (same fix pattern as the earlier setup-time migration). Auth header now lives in-process. Side effects:

• Subprocess import removed from _common.py.
• test_hooks.py fake-curl PATH shim replaced with a local _FakeGateway HTTP server fixture (BaseHTTPRequestHandler on 127.0.0.1:0); all 14 prior tests ported.
• Added TestNoCurlAtRuntime (4 regression tests, one per hook script) that puts a fake-curl shim on PATH and asserts it is never invoked — locks the migration in place.
• urllib redirect-following blocked via a _NoRedirectHandler subclass so we preserve the no--L intent (gateway is one hop; redirects should surface as failures, not be silently followed).

Test counts: test_setup.py 13/13, scripts/test_hooks.py 19/19 (was 14), mdm/test_setup.py 10/10, claude-code/hooks/test_setup.py regression 7/7.

[thatcatfromspace]

@greptileai