controlzero 1.8.2__tar.gz → 1.9.0__tar.gz

{controlzero-1.8.2 → controlzero-1.9.0}/CHANGELOG.md

@@ -1,5 +1,57 @@
 # Changelog
 
+## 1.9.0 -- 2026-06-15 (Antigravity install CLI, epic gh#925)
+
+### Added
+
+- **Google Antigravity (`agy`) governance -- BETA.** The `controlzero install
+  antigravity` / `uninstall antigravity` commands complete the Antigravity
+  integration on top of the host adapter that shipped in 1.8.0 (gh#927). Both
+  Antigravity surfaces (the IDE and the `agy` CLI) deliver the hook payload as
+  JSON on stdin, so they route directly through the shared
+  `controlzero hook-check` -> policy engine -> audit path with no shim, and
+  audit rows are attributed to `agent="antigravity"`.
+
+  - **Real EXTERNAL hooks.json contract.** Wires the `PreToolUse` (deciding
+    gate) + `PostToolUse` (observe) file-based events -- stdin JSON in, stdout
+    JSON out (camelCase), NOT exit-code based -- which is the contract the agy
+    IDE/CLI actually executes. (The in-process Python-SDK hook *class* names
+    `PreToolCallDecideHook` / `PostToolCallHook` are a different API and would
+    never fire from hooks.json.) The adapter ALWAYS emits an explicit
+    `{"decision": ...}`: an empty `{}` is read by agy as `invalid_args` and
+    DENIES the tool (cmux#5358), so silence-that-prints-`{}` is impossible.
+
+  - **`controlzero install antigravity`** (gh#928). Merges a `PreToolUse` +
+    `PostToolUse` block (broad `*` matcher) into the Antigravity `hooks.json`.
+    Writes the engine-EXECUTED path `~/.gemini/config/hooks.json` by default
+    and, for the user scope, also mirrors to the `agy` TUI `/hooks` display
+    path `~/.gemini/antigravity-cli/hooks.json` (antigravity-cli#49) so the
+    hook both fires AND displays; `<cwd>/.agents/hooks.json` with `--project`,
+    or a custom path with `--settings`. Idempotent (re-installs collapse to
+    one entry; byte-identical state), preserves pre-existing third-party hooks
+    (incl. ones sharing a block) and unrelated keys, and writes the
+    `~/.controlzero/policy.yaml` Antigravity template. `uninstall antigravity`
+    removes only the Control Zero entries (cleaning both paths) and preserves
+    your policy + audit log. Supports `--force` / `--merge` and `--api-key` /
+    `--email` for dashboard sync.
+
+  - **Human-in-the-loop on the wire.** A Control Zero approval gate (a deny
+    flagged `requires_approval`) maps to Antigravity's `ask` decision by
+    default. A plain `ask` can be auto-satisfied by a cached "Always Allow",
+    so set `CZ_ANTIGRAVITY_HITL_DECISION=force_ask` (a guaranteed prompt, once
+    verified on your pinned agy build) or `=deny` for a hard block. An
+    unrecognized value safely falls back to `ask`.
+
+  - **Agent fingerprint.** `detect_client_name()` now recognises Antigravity
+    via the `ANTIGRAVITY_` / `AGY_` env prefixes (checked BEFORE the Gemini CLI
+    branch, since Antigravity shares the `~/.gemini/` config lineage and may
+    also carry `GEMINI_*` vars). A stray `GEMINI_API_KEY` is never mislabeled
+    as Antigravity.
+
+  - **Docs.** New `docs/integrations/antigravity.md` install guide alongside
+    the existing `antigravity-hook-payloads.md` reference; `antigravity` added
+    to the SDK README template list, tagged **BETA**.
+
 ## 1.8.2 -- 2026-06-15 (Kiro IDE hook contract hotfix, epic gh#877)
 
 ### Fixed

{controlzero-1.8.2 → controlzero-1.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: controlzero
-Version: 1.8.2
+Version: 1.9.0
 Summary: AI agent governance: policies, audit, and observability for tool calls. Works locally with no signup.
 Project-URL: Homepage, https://controlzero.ai
 Project-URL: Documentation, https://docs.controlzero.ai
@@ -130,6 +130,7 @@ Templates available (`controlzero init -t <name>`):
 - `codex-cli` — Codex CLI hook starter
 - `gemini-cli` — Gemini CLI hook starter
 - `kiro` — Kiro (AWS IDE) hook starter (Beta)
+- `antigravity` — Google Antigravity (IDE + `agy` CLI) hook starter (Beta)
 
 ## Loading a policy
 

{controlzero-1.8.2 → controlzero-1.9.0}/README.md

@@ -76,6 +76,7 @@ Templates available (`controlzero init -t <name>`):
 - `codex-cli` — Codex CLI hook starter
 - `gemini-cli` — Gemini CLI hook starter
 - `kiro` — Kiro (AWS IDE) hook starter (Beta)
+- `antigravity` — Google Antigravity (IDE + `agy` CLI) hook starter (Beta)
 
 ## Loading a policy
 

{controlzero-1.8.2 → controlzero-1.9.0}/controlzero/__init__.py

@@ -40,7 +40,7 @@ from controlzero.hitl.grant_protocol import (
 )
 from controlzero.policy_loader import load_policy
 
-__version__ = "1.8.2"
+__version__ = "1.9.0"
 
 __all__ = [
     "Client",

controlzero-1.9.0/controlzero/cli/hosts/antigravity.py

@@ -0,0 +1,161 @@
+"""Google Antigravity (agy) external file-based hook adapter.
+
+Antigravity's EXTERNAL hook contract (the one wired through ``hooks.json``
+read by the IDE and the ``agy`` CLI) is distinct from the in-process
+Python-SDK hook *classes* (``PreToolCallDecideHook`` / ``PostToolCallHook``,
+registered via ``HookRunner``). Control Zero hooks via the FILE contract, so
+this adapter speaks that protocol -- not the SDK class names.
+
+External contract (verified against antigravity.google/docs/hooks and four
+real integrators -- antigravity-cli#49, cmux#5358, munder-difflin#52/#54,
+danicat.dev):
+
+* Events: ``PreToolUse`` (the deciding gate -- CAN deny), ``PostToolUse``
+  (observe only), plus ``PreInvocation`` / ``PostInvocation`` / ``Stop``
+  (model-call lifecycle; ``PreInvocation`` cannot deny). Control Zero's
+  governance gate is ``PreToolUse``; the post scan is ``PostToolUse``.
+  There is NO prompt-submit / UserPromptSubmit event.
+* Delivery: stdin = JSON in, stdout = JSON out, camelCase. NOT exit-code
+  based. (A crashing / non-zero / timed-out hook is read as a deny --
+  fail-closed -- so the renderer must never raise.)
+* PreToolUse INPUT: ``{toolCall:{name,args}, stepIdx, conversationId,
+  workspacePaths[], transcriptPath}`` (``artifactDirectoryPath`` may also
+  appear). ``normalize_payload`` flattens ``toolCall`` -> ``tool_name`` /
+  ``tool_input`` so the shared extractor + globs work unchanged.
+* PreToolUse OUTPUT: ``{"decision": "allow"|"deny"|"ask", "reason": "..."}``.
+  CRITICAL FAIL-CLOSED LANDMINE (cmux#5358): an empty / decision-less object
+  ``{}`` on stdout is read by agy as ``invalid_args`` and DENIES the tool.
+  We therefore ALWAYS emit an explicit ``{"decision": ...}`` -- the allow
+  path is ``{"decision":"allow"}``, never silence-that-still-prints-{}.
+
+HITL mapping: a Control Zero approval gate maps to ``ask`` by default. A
+plain ``ask`` CAN be auto-satisfied by a cached "Always Allow" (so it is not
+a guaranteed prompt); some agy builds also accept ``force_ask`` (always
+prompts). Because ``force_ask`` is not confirmed across all builds and an
+unrecognized decision risks the same ``invalid_args`` -> deny trap, the HITL
+decision token is configurable via ``CZ_ANTIGRAVITY_HITL_DECISION`` (default
+``ask``; set to ``force_ask`` once verified against your pinned agy, or
+``deny`` for a hard block-with-reason).
+
+Subagent tool calls fire the parent ``PreToolUse`` hook, so one adapter
+governs parent + subagents.
+
+Reference (pinned): see docs/integrations/antigravity-hook-payloads.md
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Mapping
+
+from controlzero.cli.hosts.base import CZDecision, HostAdapter
+
+# File-based EVENT names (NOT the in-process SDK class names). PreToolUse is
+# the deciding gate; PostToolUse is observe-only.
+_ANTIGRAVITY_HOOK_EVENTS = frozenset(
+    {"PreToolUse", "PostToolUse", "PreInvocation", "PostInvocation", "Stop"}
+)
+# Events SAFE to claim by name alone. PreToolUse / PostToolUse / Stop collide
+# with Claude Code's PascalCase event names, so a payload carrying ONLY one of
+# those (no toolCall envelope, no env marker) is ambiguous and must fall to
+# Claude Code (which sits ahead in the registry). PreInvocation / PostInvocation
+# are Antigravity-distinct -- no other host emits them -- so they are safe
+# disambiguators. Antigravity's unambiguous signal is the ``toolCall`` envelope,
+# which the claim below keys on first.
+_ANTIGRAVITY_CLAIM_EVENTS = frozenset({"PreInvocation", "PostInvocation"})
+_CLIENT_ALIASES = frozenset({"antigravity", "agy", "antigravity-cli"})
+_ENV_PREFIXES = ("ANTIGRAVITY_", "AGY_")
+
+# Source-confirmed decision tokens for PreToolUse output.
+_VALID_DECISIONS = frozenset({"allow", "deny", "ask", "force_ask"})
+_DEFAULT_HITL_DECISION = "ask"
+
+
+def _resolve_hitl_decision(env: Mapping[str, str] | None = None) -> str:
+    """Resolve the decision token used for a HITL approval gate.
+
+    Default ``ask`` (source-confirmed valid on every agy build). Operators
+    can opt into ``force_ask`` (guaranteed prompt) or ``deny`` once verified
+    against their pinned agy via ``CZ_ANTIGRAVITY_HITL_DECISION``. An
+    unrecognized value falls back to ``ask`` so we never emit a token that
+    could trip the ``invalid_args`` -> deny trap.
+    """
+    src = env if env is not None else os.environ
+    raw = (src.get("CZ_ANTIGRAVITY_HITL_DECISION") or "").strip().lower()
+    return raw if raw in _VALID_DECISIONS else _DEFAULT_HITL_DECISION
+
+
+class AntigravityAdapter(HostAdapter):
+    name = "antigravity"
+    canonical_source = "antigravity"
+    # Antigravity decides from the stdout JSON, NOT the exit code. A non-zero
+    # exit is read as a fail-closed deny that would override an ``ask`` /
+    # ``allow`` verdict (turning a HITL prompt into a hard block), so the
+    # hook-check command must exit 0 for this host and let the JSON decide.
+    decision_via_exit_code = False
+
+    def claim(self, payload: dict, env: Mapping[str, str]) -> bool:
+        if (env.get("CONTROLZERO_CLIENT") or "").strip().lower() in _CLIENT_ALIASES:
+            return True
+        for key in env:
+            if key.upper().startswith(_ENV_PREFIXES):
+                return True
+        if isinstance(payload, dict):
+            # Unambiguous Antigravity signal: the toolCall envelope.
+            if "toolCall" in payload:
+                return True
+            # Only the Antigravity-distinct lifecycle events are safe to claim
+            # by name; PreToolUse / PostToolUse / Stop collide with Claude Code
+            # and are disambiguated by toolCall / env instead.
+            if payload.get("hook_event_name") in _ANTIGRAVITY_CLAIM_EVENTS:
+                return True
+        return False
+
+    def normalize_payload(self, payload: dict) -> dict:
+        if not isinstance(payload, dict):
+            return payload
+        tool_call = payload.get("toolCall")
+        if not isinstance(tool_call, dict):
+            return payload
+        normalized = dict(payload)  # preserves conversationId / workspacePaths
+        name = tool_call.get("name")
+        args = tool_call.get("args")
+        if name is not None and not normalized.get("tool_name"):
+            normalized["tool_name"] = name
+        if args is not None and not normalized.get("tool_input"):
+            normalized["tool_input"] = args if isinstance(args, dict) else {}
+        return normalized
+
+    def render(self, decision: CZDecision) -> dict:
+        """Render to Antigravity's PreToolUse stdout-JSON contract.
+
+        ALWAYS emits an explicit ``decision`` key. An empty / decision-less
+        object would be read by agy as ``invalid_args`` and DENY the tool
+        (cmux#5358), so silence-that-still-prints-{} is never produced here.
+        camelCase per the external contract; Control Zero diagnostic
+        metadata is namespaced under ``controlzero`` so it cannot collide
+        with agy's reserved output keys.
+        """
+        if decision.is_hitl:
+            verdict = _resolve_hitl_decision()
+        elif decision.is_deny:
+            verdict = "deny"
+        else:
+            verdict = "allow"
+
+        envelope: dict = {
+            "decision": verdict,
+            "reason": decision.reason,
+            # Diagnostic metadata, namespaced so it never shadows a reserved
+            # agy key (decision / reason / permissionOverrides).
+            "controlzero": {
+                "reasonCode": decision.reason_code,
+                "tool": decision.tool,
+                "extractedMethod": decision.method,
+                "action": decision.extracted_action,
+                "actionSemanticClass": decision.semantic_class,
+                "tamperDetected": decision.tamper_detected,
+                "auditChainBroken": decision.audit_chain_broken,
+            },
+        }
+        return envelope

{controlzero-1.8.2 → controlzero-1.9.0}/controlzero/cli/hosts/base.py

@@ -127,6 +127,15 @@ class HostAdapter:
     #: Default is ``"unknown"`` -- subclasses MUST override.
     canonical_source: str = "unknown"
 
+    #: Whether the host signals a deny via the PROCESS EXIT CODE
+    #: (non-zero = block, the Claude Code / Gemini / Codex / Kiro
+    #: convention) or purely via the stdout JSON ``decision`` field.
+    #: Antigravity is stdout-JSON based: a non-zero exit is read as a
+    #: fail-closed deny that would OVERRIDE an ``ask``/``allow`` JSON
+    #: verdict, so its hook must exit 0 and let the JSON decide. The
+    #: hook-check command consults this to pick the deny/HITL exit code.
+    decision_via_exit_code: bool = True
+
     # -- detection --------------------------------------------------
 
     def claim(self, payload: dict, env: Mapping[str, str]) -> bool:

{controlzero-1.8.2 → controlzero-1.9.0}/controlzero/cli/hosts/claude_code.py

@@ -61,6 +61,20 @@ class ClaudeCodeAdapter(HostAdapter):
         ):
             return True
 
+        # Disambiguation: Google Antigravity's external hooks use the SAME
+        # PascalCase event names (PreToolUse / PostToolUse / Stop) but pack
+        # the call under a top-level ``toolCall`` envelope, which Claude Code
+        # never sends. If ``toolCall`` is present this is an Antigravity
+        # payload -- do NOT claim it (let the AntigravityAdapter claim it).
+        # This runs BEFORE the Anthropic env-hint check: an Antigravity hook
+        # subprocess can inherit CLAUDECODE / CLAUDE_CODE from a Claude-spawned
+        # parent shell, and claiming on that stale env hint would emit Claude's
+        # approve/block tokens -- invalid for Antigravity, read as a deny.
+        # Only the explicit CONTROLZERO_CLIENT=claude_code override above
+        # outranks the toolCall signal.
+        if isinstance(payload, dict) and "toolCall" in payload:
+            return False
+
         # Env-var hint: any of the Anthropic-family vars present.
         for hint in self._ENV_HINTS:
             if env.get(hint):