controlzero 1.8.1__tar.gz → 1.9.0__tar.gz

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

@@ -1,5 +1,113 @@
 # 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
+
+The shipped Kiro IDE `.kiro.hook` templates used several **Kiro CLI** schema
+conventions instead of the **Kiro IDE** ones (the two hook systems have
+different event names and field keys). The most visible symptom was a
+customer-reported P0; auditing the templates against Kiro's IDE schema
+surfaced three more latent defects. All four are fixed, and a new regression
+test (`tests/test_kiro_hook_templates.py`) pins each so they cannot ship again.
+
+- **(P0) Prompt-submit hook rejected by the IDE.** `ide-prompt-submit.kiro.hook`
+  declared `"when": {"type": "userPromptSubmit"}`. `userPromptSubmit` is the
+  Kiro **CLI** event name; the IDE event is **`promptSubmit`**. The invalid
+  value made the IDE reject the entire hook file ("Hook file has invalid data
+  structure"), so the only active data-carrying IDE hook (prompt-submit, while
+  preToolUse ships disabled) never loaded and the IDE integration silently did
+  nothing. Now `promptSubmit`, with the matching `cz-kiro-adapter promptSubmit`
+  command. (The shim already accepts both spellings, so no behavior change.)
+
+- **Pre-tool-use tool filter used the wrong key.** `ide-pre-tool-use.kiro.hook`
+  filtered tools with `"patterns": ["*"]`; the Kiro IDE tool filter key for
+  `preToolUse`/`postToolUse` is **`toolTypes`** (array). Now `"toolTypes":
+  ["*"]`, so the hook is schema-correct if/when it is enabled (it still ships
+  `enabled: false` pending the upstream empty-payload bug).
+
+- **File-save hook passed a tool-event arg + could block saves.**
+  `ide-file-save.kiro.hook` ran `cz-kiro-adapter postToolUse`, but a
+  `fileEdited` runCommand does not deliver tool context; the adapter would then
+  fail closed (block) on the empty payload -- i.e. it could block file saves.
+  The command is now `cz-kiro-adapter fileEdited`, and the shim treats file
+  events as a post-write **observation**: it synthesizes a `fileSave` tool
+  call from whatever `USER_PROMPT` carries, still runs `hook-check` for the
+  audit row + secret scan, but **always exits 0** on a file event -- a deny is
+  surfaced on stderr as a warning rather than blocking. The file is already
+  written, so blocking is pointless; only tool events (preToolUse) gate.
+  `when.type` stays the valid `fileEdited` with `patterns`.
+
+- **Timeouts were ~83 minutes, not 5 seconds.** All three templates used
+  `"timeout": 5000`. Kiro IDE `then.timeout` is in **seconds** (default 60,
+  `0` disables), so `5000` meant ~83 minutes. Now `5` (seconds) on all three.
+
+The regression test parses every shipped `*.kiro.hook` and asserts: valid
+JSON; `when.type` in Kiro's 11-value IDE event set; tool events use
+`toolTypes` (not `patterns`) and file events use `patterns` (not `toolTypes`);
+`then.timeout` is a small integer (seconds); and the `runCommand` event
+argument is one the `cz-kiro-adapter` shim recognizes.
+
+### Known upstream Kiro limits (not fixed here -- tracked upstream)
+
+- IDE `preToolUse` delivers `USER_PROMPT={}` (no tool context): kirodotdev/Kiro
+  #7375 / #7408 / #7500. Our pre-tool-use IDE hook stays disabled.
+- IDE `postToolUse` delivers `toolArgs: {}` (kirodotdev/Kiro #6188), so
+  argument-level post-tool policy is bounded on the IDE surface regardless of
+  schema correctness.
+
 ## 1.8.0 -- 2026-06-15 (Kiro, epic gh#877)
 
 ### Added

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: controlzero
-Version: 1.8.1
+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.1 → 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.1 → 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.1"
+__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.1 → 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.1 → 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):

{controlzero-1.8.1 → controlzero-1.9.0}/controlzero/cli/kiro_adapter.py

@@ -7,8 +7,9 @@ on stdin like the Kiro CLI. This shim normalises that into the snake_case JSON
 shape ``controlzero hook-check`` consumes, marks the surface
 (``CZ_KIRO_SURFACE=ide`` so KiroIDEAdapter claims it), and pipes it through.
 
-Wire it as the IDE's preToolUse / postToolUse / userPromptSubmit hook command,
-e.g.::
+Wire it as the IDE's preToolUse / promptSubmit / fileEdited hook command (the
+IDE `when.type` event names -- note prompt-submit is ``promptSubmit`` on the
+IDE surface, NOT the Kiro CLI's ``userPromptSubmit``), e.g.::
 
     cz-kiro-adapter preToolUse
 
@@ -37,6 +38,12 @@ import subprocess
 import sys
 
 
+# Kiro IDE file events. These are a post-write OBSERVATION surface (scan the
+# saved file / audit it), never a gate, so the adapter must not fail closed on
+# them -- a file save can't be blocked by missing context.
+_FILE_EVENTS = frozenset({"fileEdited", "fileCreated", "fileDeleted"})
+
+
 def _event_from_argv(argv: list[str]) -> str:
     # First non-flag arg is the event name; default to preToolUse.
     for a in argv[1:]:
@@ -66,6 +73,25 @@ def _normalize(event: str, raw: str) -> dict | None:
         base["tool_input"] = {"prompt": raw}
         return base
 
+    if event in _FILE_EVENTS:
+        # File events are a POST-WRITE observation, not a gate: a save must
+        # never be blocked by missing context, so this branch NEVER returns
+        # None (no fail-closed). Kiro IDE does not document a guaranteed
+        # structured payload for a file-event runCommand (USER_PROMPT may be a
+        # path, a JSON object, or empty), so we synthesize a write-class tool
+        # call from whatever arrived and let hook-check scan/audit it.
+        base["tool_name"] = "fileSave"
+        payload: dict = {}
+        text = (raw or "").strip()
+        if text:
+            try:
+                parsed = json.loads(text)
+                payload = parsed if isinstance(parsed, dict) else {"raw": text}
+            except json.JSONDecodeError:
+                payload = {"file_path": text}  # most likely a bare path
+        base["tool_input"] = payload
+        return base
+
     raw = (raw or "").strip()
     if not raw:
         return None
@@ -122,6 +148,20 @@ def main(argv: list[str] | None = None) -> int:
         # controlzero not on PATH: never brick the IDE.
         print("controlzero(kiro): controlzero CLI not found; allowing", file=sys.stderr)
         return 0
+
+    if event in _FILE_EVENTS:
+        # OBSERVE-ONLY: a file event is post-write -- the file is already
+        # saved, so blocking is pointless and only disrupts the editor. We
+        # still run hook-check above for the audit row + secret scan, but a
+        # deny is surfaced as a warning and the save is allowed (exit 0).
+        if proc.returncode == 2:
+            print(
+                "controlzero(kiro): file-save policy flagged this write "
+                "(post-write, observe-only; not blocking the save)",
+                file=sys.stderr,
+            )
+        return 0
+
     return proc.returncode