controlzero 1.9.5__tar.gz → 1.9.7__tar.gz

{controlzero-1.9.5 → controlzero-1.9.7}/CHANGELOG.md

@@ -1,5 +1,67 @@
 # Changelog
 
+## 1.9.7 -- 2026-06-16 (hosted audit delivery for short-lived processes, gh#1292)
+
+Fixes a P0 found via a customer report: hosted-mode audit rows were written to
+the local `~/.controlzero/audit.log` but never reached the dashboard for
+short-lived processes (PreToolUse hooks, CLI one-shots).
+
+### Fixed
+
+- **Remote audit never delivered for short-lived processes (gh#1292).** Since
+  1.9.2 the hosted (`BearerAuditSink`) and enrolled (`RemoteAuditSink`) sinks
+  default to the durable encrypted spool, where `log()` WALs the row and an
+  opportunistic `daemon=True` thread drains it. A short-lived process exits
+  before that thread can finish its HTTPS POST, and `close()` was a fsync-only
+  boundary, so the row stayed on local disk and never shipped. The hosted sink
+  now hands the drain to a **detached `controlzero spool flush` child** that
+  outlives the process (no latency on the agent hot path; the keystore and
+  network work happen in the child, never on the close path). The api key
+  travels via the child's environment, never on its argv. The enrolled sink
+  (opt-in, off the hosted hot path) does a bounded, fail-open in-process drain
+  on close instead. Both paths are fail-open: any error leaves the durable WAL
+  intact for a later drain. The durable WAL guarantee is unchanged.
+
+## 1.9.6 -- 2026-06-16 (Antigravity GA-blocker hardening, gh#1248 / epic gh#925)
+
+Closes 3 of the prod-readiness GA blockers for the Antigravity (`agy`)
+integration. Antigravity stays **BETA** -- GA still requires a manual check
+against a real pinned agy build (agy cannot run headless in CI), which these
+changes do not perform.
+
+### Fixed
+
+- **Empty-stdout fail-closed on the Antigravity surface (blocker #1).** Every
+  `controlzero hook-check` error exit -- stdin read error, empty stdin,
+  malformed JSON, missing `tool_name`, and an invalid/unreadable policy --
+  previously emitted EMPTY stdout and exited 0. Agy decides from stdout JSON,
+  and empty stdout is undocumented (agy *currently* reads it as
+  `invalid_args` -> deny, but that is unverified across builds). On the
+  Antigravity surface those paths now emit an explicit
+  `{"decision":"deny", "reason":...}` so a parse/policy error DENIES
+  deterministically. Pass-through hosts (Claude Code / Gemini / Codex) keep
+  the documented empty-stdout = "no opinion, proceed" behavior unchanged.
+
+- **HITL approval gate no longer silently auto-approvable (blocker #2).** The
+  HITL decision token now defaults to `force_ask` (a MANDATORY prompt that
+  ignores agy's "Always Allow" cache) instead of `ask` (which a cached
+  approval can silently satisfy -- fail-OPEN on an approval-gated destructive
+  action). `CZ_ANTIGRAVITY_HITL_DECISION` selects the token; an empty or
+  unrecognized value falls back to `force_ask`, NEVER to `ask`. If a pinned
+  agy build rejects `force_ask`, set `CZ_ANTIGRAVITY_HITL_DECISION=deny` for a
+  hard block-with-reason. `ask`/`allow` remain available only as an explicit,
+  knowing operator downgrade.
+
+- **`doctor` checks the REAL Antigravity paths and verifies the hook is live
+  (blocker #3).** `controlzero doctor` previously checked
+  `~/.antigravity/config.json` -- a path the installer never writes. It now
+  scans the executed `~/.gemini/config/hooks.json` and the agy TUI mirror
+  `~/.gemini/antigravity-cli/hooks.json` (plus the cwd-relative project-scope
+  `.agents/hooks.json`), confirms a live `controlzero hook-check` `PreToolUse`
+  entry is present (`E1006` when missing), and runs a dry-run hook-check
+  round-trip to confirm the adapter renders an explicit decision rather than
+  empty stdout (`E1007` when it does not).
+
 ## 1.9.5 -- 2026-06-16 (Kiro CLI -> GA, epic gh#877)
 
 ### Changed

{controlzero-1.9.5 → controlzero-1.9.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: controlzero
-Version: 1.9.5
+Version: 1.9.7
 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

{controlzero-1.9.5 → controlzero-1.9.7}/controlzero/__init__.py

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

{controlzero-1.9.5 → controlzero-1.9.7}/controlzero/audit_remote.py

@@ -24,6 +24,7 @@ import json
 import logging
 import os
 import platform
+import sys
 import threading
 import uuid
 from datetime import datetime, timezone
@@ -110,6 +111,15 @@ _SPOOL_DEFAULT_DIR = "~/.controlzero/spool"
 # processes.
 _SPOOL_HOOK_BUDGET_S = 2.0
 _SPOOL_TIMER_BUDGET_S = 25.0
+# close() handoff budgets (#1292). A short-lived process (PreToolUse hook /
+# CLI one-shot) exits before the daemon drain ships its spooled rows, and
+# close() was a fsync-only boundary -- so the rows never reached the backend.
+# The hosted (Bearer) sink now hands the drain to a DETACHED uploader child
+# that outlives this process (no latency on the agent hot path, keystore +
+# network work happen off the close path). The enrolled sink -- opt-in, off
+# the hosted hot path -- does a bounded, fail-open in-process drain instead.
+_DETACHED_DRAIN_BUDGET_S = 30.0
+_CLOSE_DRAIN_BUDGET_S = 2.0
 
 
 def _build_wire_entry(
@@ -284,6 +294,11 @@ class _SpoolWiringMixin:
         self._drain_inflight = False
         self._drain_again = False
         self._drain_auth_blocked = False
+        # #1292: whether this process WAL-logged at least one entry (gates the
+        # close-time handoff so a pure-read process never spawns a drainer) and
+        # whether the detached drainer was already spawned (coalesce to one).
+        self._spool_logged = False
+        self._detached_drain_spawned = False
         self._spool = None
         self._spool_mode = "off"
         # Fast path: flag off/unset, NO hosted default, AND no spool
@@ -365,6 +380,10 @@ class _SpoolWiringMixin:
         except Exception as exc:  # noqa: BLE001
             logger.warning("controlzero: spool append failed (%s)", exc)
             return False
+        # This process has durably WAL-logged at least one entry; close() may
+        # need to hand its drain to a detached uploader so a short-lived
+        # process does not strand it (#1292).
+        self._spool_logged = True
         if self._spool_mode == _SPOOL_MODE_DURABLE:
             self._drain_async(budget_s=_SPOOL_HOOK_BUDGET_S)
         return True
@@ -377,6 +396,73 @@ class _SpoolWiringMixin:
     def _spool_drain_orphans(self) -> bool:
         return False
 
+    def _spawn_detached_drain(self) -> None:
+        """Hand the spool drain to a DETACHED child that outlives this
+        process, then return immediately (#1292).
+
+        A short-lived hosted process (PreToolUse hook / CLI one-shot) exits
+        before the in-process daemon drain can finish its HTTPS POST, so
+        durably-spooled rows never reach the backend -- close() was a
+        fsync-only boundary that stranded them. Spawning ``controlzero spool
+        flush`` in a new session lets the upload complete after this process
+        is gone: no latency on the agent hot path, and the keystore + network
+        work happen in the child, never on this close path (the founder
+        non-blocking-hook and no-keystore-on-close constraints).
+
+        Only the Bearer (hosted api-key) sink can be drained this way --
+        ``cz spool flush`` authenticates with the api key, which it reads from
+        the environment (never argv, so the key never lands in ``ps``). The
+        enrolled sink has no such entrypoint and uses an in-process close
+        drain instead.
+
+        Fail-open: any error leaves the durable WAL intact for a later drain
+        (next long-lived process, the timer, or an explicit ``cz spool
+        flush``)."""
+        if getattr(self, "_detached_drain_spawned", False):
+            return
+        if self._spool is None or not getattr(self, "_spool_logged", False):
+            return
+        api_key = getattr(self, "_api_key", None)
+        if not api_key:
+            return
+        try:
+            import subprocess
+
+            env = dict(os.environ)
+            env["CONTROLZERO_API_KEY"] = api_key
+            api_url = getattr(self, "_api_url", None)
+            if api_url:
+                env["CONTROLZERO_API_URL"] = api_url
+            popen_kwargs = dict(
+                stdin=subprocess.DEVNULL,
+                stdout=subprocess.DEVNULL,
+                stderr=subprocess.DEVNULL,
+                env=env,
+                close_fds=True,
+            )
+            if os.name == "nt":  # detach on Windows
+                popen_kwargs["creationflags"] = (
+                    getattr(subprocess, "DETACHED_PROCESS", 0)
+                    | getattr(subprocess, "CREATE_NEW_PROCESS_GROUP", 0)
+                )
+            else:  # POSIX: escape the process group so it outlives the parent
+                popen_kwargs["start_new_session"] = True
+            subprocess.Popen(  # noqa: S603 -- fixed argv, no shell, no user input
+                [
+                    sys.executable, "-m", "controlzero.cli.main",
+                    "spool", "flush",
+                    "--timeout", str(_DETACHED_DRAIN_BUDGET_S),
+                ],
+                **popen_kwargs,
+            )
+            self._detached_drain_spawned = True
+        except Exception as exc:  # noqa: BLE001 -- never block/crash the host
+            logger.warning(
+                "controlzero: detached spool drain spawn failed (%s); audit "
+                "rows remain durable in the spool for a later drain",
+                exc,
+            )
+
     def _drain_async(self, budget_s: float = _SPOOL_HOOK_BUDGET_S) -> None:
         """One opportunistic non-blocking drain in a daemon thread.
         Coalesced: at most one drain in flight per sink instance; an
@@ -506,8 +592,17 @@ class RemoteAuditSink(_SpoolWiringMixin):
         self._closed = True
         self._cancel_flush_timer()
         if self._spool_wal:
-            # Spool mode: every entry is already durable on disk; close
-            # is a final fsync boundary, NEVER a blocking network flush.
+            # DURABLE mode (enrolled, opt-in, off the hosted hot path) ships
+            # synchronously with a bounded, fail-open budget before the final
+            # fsync so a short-lived process does not strand its rows (#1292).
+            # spool_only is replay-only and must NEVER live-send on close.
+            if (self._spool_mode == _SPOOL_MODE_DURABLE
+                    and getattr(self, "_spool_logged", False)):
+                try:
+                    self._drain_once(blocking=True,
+                                     budget_s=_CLOSE_DRAIN_BUDGET_S)
+                except Exception:  # noqa: BLE001 -- fail-open; WAL preserved
+                    pass
             self._spool_close()
             return
         # Synchronous flush -- we are shutting down
@@ -748,8 +843,13 @@ class BearerAuditSink(_SpoolWiringMixin):
         self._closed = True
         self._cancel_flush_timer()
         if self._spool_wal:
-            # Spool mode: entries are already durable; close is a final
-            # fsync boundary, NEVER a blocking network flush.
+            # DURABLE mode hands the drain to a DETACHED child that outlives
+            # this (possibly short-lived) process so its rows are delivered;
+            # close() makes NO in-process network call -- the child does the
+            # keystore + network work off this hot path (#1292). spool_only is
+            # replay-only and must NEVER live-send on close -- only fsync.
+            if self._spool_mode == _SPOOL_MODE_DURABLE:
+                self._spawn_detached_drain()
             self._spool_close()
             return
         self._flush_sync()

{controlzero-1.9.5 → controlzero-1.9.7}/controlzero/cli/doctor.py

@@ -82,8 +82,18 @@ def _agent_paths() -> List[_AgentPath]:
                    "VS Code user settings"),
         _AgentPath("cline", home / "Library" / "Application Support" / "Code" / "User" / "globalStorage" / "saoudrizwan.claude-dev" / "settings" / "cline_mcp_settings.json",
                    "Cline MCP settings (macOS)"),
-        _AgentPath("antigravity", home / ".antigravity" / "config.json",
-                   "Antigravity config"),
+        # Antigravity (agy): the install writes the EXECUTED hook config to
+        # ~/.gemini/config/hooks.json and mirrors it to
+        # ~/.gemini/antigravity-cli/hooks.json for the agy TUI /hooks display
+        # (antigravity-cli#49). The pre-#1248 doctor checked
+        # ~/.antigravity/config.json -- a path the installer NEVER writes -- so
+        # it could neither find a leaked key there nor confirm the hook was
+        # live. Scan the real executed + mirror paths now. Project scope
+        # (<cwd>/.agents/hooks.json) is covered by the cwd-aware live check.
+        _AgentPath("antigravity", home / ".gemini" / "config" / "hooks.json",
+                   "Antigravity PreToolUse hook command"),
+        _AgentPath("antigravity", home / ".gemini" / "antigravity-cli" / "hooks.json",
+                   "Antigravity agy TUI /hooks mirror"),
         _AgentPath("adal", home / ".adal" / "config.json",
                    "Adal config"),
         _AgentPath("jetbrains", home / ".config" / "JetBrains" / "mcp.json",
@@ -243,6 +253,208 @@ def _check_global_environment() -> List[Finding]:
     return findings
 
 
+# -----------------------------------------------------------------------------
+# Antigravity hook liveness (GA blocker #3, issue #1248).
+#
+# The pre-#1248 doctor only scanned files for leaked keys. For Antigravity it
+# also checked the WRONG path (~/.antigravity/config.json), so it gave a user
+# zero signal about whether their governance hook was actually installed and
+# firing. These checks confirm the hook entry is present at the REAL executed
+# path AND that a dry-run hook-check round-trips a valid decision -- the two
+# things that have to be true for the gate to govern a single tool call.
+# -----------------------------------------------------------------------------
+
+# The substring that marks a Control Zero hook entry, matching the installer's
+# own self-detection (`_antigravity_hook_is_cz`). Kept in one place so a future
+# command-string change only edits here.
+_CZ_HOOK_MARKER = "controlzero hook-check"
+
+
+def _antigravity_executed_hook_paths() -> List[Path]:
+    """The hooks.json paths agy actually EXECUTES, in precedence order.
+
+    Project scope wins for a workspace, so it is checked first; the global
+    user file is the fallback. The TUI mirror (~/.gemini/antigravity-cli/...)
+    is a display surface, not an executed path, so it is intentionally NOT in
+    this list -- a hook present only in the mirror does not fire.
+    """
+    home = Path.home()
+    return [
+        Path.cwd() / ".agents" / "hooks.json",          # project scope (<cwd>)
+        home / ".gemini" / "config" / "hooks.json",      # global user (executed)
+    ]
+
+
+def _antigravity_mirror_path() -> Path:
+    """The agy TUI /hooks DISPLAY mirror (antigravity-cli#49).
+
+    A hook present ONLY here is shown in the agy `/hooks` UI but is NOT
+    executed, so it does not fire. Used purely as a presence signal so doctor
+    can warn about that display-but-not-live state.
+    """
+    return Path.home() / ".gemini" / "antigravity-cli" / "hooks.json"
+
+
+def _antigravity_hook_command_present(hooks_path: Path) -> bool:
+    """True iff hooks_path has a live PreToolUse Control Zero hook entry.
+
+    Mirrors the installer's written shape: top-level ``hooks`` ->
+    ``PreToolUse`` -> list of blocks each with a ``hooks`` list of
+    ``{type, command, ...}`` entries. A CZ entry is any whose ``command``
+    contains ``controlzero hook-check``. Tolerant of hand-edits / partial
+    shapes -- anything it cannot parse counts as "not present".
+    """
+    import json
+
+    try:
+        data = json.loads(hooks_path.read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return False
+    if not isinstance(data, dict):
+        return False
+    hooks = data.get("hooks")
+    if not isinstance(hooks, dict):
+        return False
+    pre = hooks.get("PreToolUse")
+    if not isinstance(pre, list):
+        return False
+    for block in pre:
+        if not isinstance(block, dict):
+            continue
+        block_hooks = block.get("hooks")
+        if not isinstance(block_hooks, list):
+            # Tolerate a malformed-but-valid-JSON shape (e.g. "hooks": 3);
+            # iterating a non-list would raise TypeError and crash doctor.
+            continue
+        for entry in block_hooks:
+            if not isinstance(entry, dict):
+                continue
+            cmd = entry.get("command")
+            if isinstance(cmd, str) and _CZ_HOOK_MARKER in cmd:
+                return True
+    return False
+
+
+def _antigravity_dry_run_roundtrips() -> bool:
+    """True iff a dry-run hook-check produces a valid Antigravity decision.
+
+    This is the "does the hook actually fire" half of the check. We do NOT
+    shell out to ``controlzero hook-check`` (slow, and a misconfigured PATH
+    would make a working install look broken). Instead we exercise the same
+    code path the hook runs: select the Antigravity adapter and render a
+    decision, asserting it emits an explicit ``decision`` token (never the
+    empty-stdout ``invalid_args`` trap). If the adapter import or render
+    raises, the round-trip has failed.
+    """
+    try:
+        from controlzero.cli.hosts import CZDecision, select_adapter
+
+        # Force Antigravity selection via the env signal its claim() honors.
+        adapter = select_adapter({}, {"CONTROLZERO_CLIENT": "antigravity"})
+        if getattr(adapter, "name", "") != "antigravity":
+            return False
+        out = adapter.render(
+            CZDecision(effect="allow", reason="doctor dry-run", reason_code="RULE_MATCH")
+        )
+        return isinstance(out, dict) and out.get("decision") == "allow"
+    except Exception:  # noqa: BLE001
+        return False
+
+
+def _check_antigravity_hook_live() -> List[Finding]:
+    """Confirm the Antigravity governance hook is installed AND can fire.
+
+    Respects agy's file precedence: the highest-precedence EXISTING executed
+    file wins (project scope <cwd>/.agents/hooks.json shadows the global
+    ~/.gemini/config/hooks.json), so that file alone determines liveness.
+
+    Emits at most one finding:
+
+    * If the authoritative executed file carries a CZ entry and the dry-run
+      round-trips -> no finding (the gate is live).
+    * If the authoritative executed file (or only the display mirror) lacks a
+      CZ entry -> WARN installed-but-not-live (or never installed). WARN, not
+      ERROR: a box that never installed the agy hook is a valid state, and
+      doctor exit 1 is reserved for active security problems (leaked keys,
+      bad perms).
+    * If the CZ entry is present but the dry-run does NOT round-trip -> ERROR:
+      the entry exists but the adapter cannot render a decision, so the gate
+      would emit empty stdout -> agy invalid_args / undefined behavior.
+    """
+    findings: List[Finding] = []
+    executed = _antigravity_executed_hook_paths()
+
+    # agy executes the HIGHEST-PRECEDENCE existing file only (project scope
+    # <cwd>/.agents/hooks.json shadows the global ~/.gemini/config/hooks.json).
+    # So the FIRST existing executed file is authoritative: if it carries a CZ
+    # entry the gate is live; if it does NOT, the workspace is ungoverned even
+    # when a lower-precedence file happens to have one. We must NOT fall through
+    # to that lower file, or doctor would falsely report "live" (codex P1).
+    authoritative = next((p for p in executed if p.exists()), None)
+    live_path = (
+        authoritative
+        if authoritative is not None and _antigravity_hook_command_present(authoritative)
+        else None
+    )
+
+    if live_path is None:
+        # Surface a not-live WARN when ANY agy hooks.json exists -- the
+        # authoritative executed file without a CZ entry, or only the
+        # display-only TUI mirror. A hook present only in the mirror (or absent
+        # from the executed file that wins) is shown in the agy `/hooks` UI yet
+        # does NOT govern tool calls -- exactly the misleading state to flag.
+        # Stay silent when no agy file exists at all so a non-Antigravity user
+        # gets no spurious warning.
+        mirror = _antigravity_mirror_path()
+        present = [p for p in executed if p.exists()]
+        if mirror.exists():
+            present.append(mirror)
+        if present:
+            mirror_only = all(p == mirror for p in present)
+            findings.append(Finding(
+                path=str(present[0]),
+                line=1,
+                col=1,
+                severity="WARN",
+                code="E1006",
+                message=(
+                    (
+                        "Antigravity hook appears only in the agy /hooks DISPLAY "
+                        "mirror (~/.gemini/antigravity-cli/hooks.json) -- that path "
+                        "is NOT executed, so the governance gate is NOT firing."
+                    )
+                    if mirror_only else
+                    (
+                        "Antigravity hooks.json exists but has no live "
+                        f"'{_CZ_HOOK_MARKER}' PreToolUse entry -- the governance "
+                        "gate is NOT firing for tool calls."
+                    )
+                ),
+                fix_hint="run `controlzero install antigravity` to (re)install the hook",
+            ))
+        return findings
+
+    # Hook entry is present -- verify it can actually render a decision.
+    if not _antigravity_dry_run_roundtrips():
+        findings.append(Finding(
+            path=str(live_path),
+            line=1,
+            col=1,
+            severity="ERROR",
+            code="E1007",
+            message=(
+                "Antigravity hook entry is installed but a dry-run hook-check "
+                "does NOT round-trip a decision -- the gate would emit empty "
+                "stdout (agy reads that as invalid_args / undefined)."
+            ),
+            fix_hint=(
+                "reinstall the SDK (`pip install -U control-zero`) and rerun "
+                "`controlzero install antigravity`; if it persists, file a bug"
+            ),
+        ))
+    return findings
+
+
 # -----------------------------------------------------------------------------
 # Public entrypoint. Wired into the CLI as `controlzero doctor`.
 # -----------------------------------------------------------------------------
@@ -257,6 +469,7 @@ def run_doctor(verbose: bool = False) -> int:
     findings.extend(_check_agent_key_leaks(_agent_paths()))
     findings.extend(_check_config_permissions())
     findings.extend(_check_global_environment())
+    findings.extend(_check_antigravity_hook_live())
 
     errors = [f for f in findings if f.severity == "ERROR"]
     warns = [f for f in findings if f.severity == "WARN"]
@@ -272,6 +485,16 @@ def run_doctor(verbose: bool = False) -> int:
             for ap in _agent_paths():
                 status = "exists" if ap.path.exists() else "absent"
                 cz_console.info(f"  {ap.agent:14s} {status:7s} {ap.path}")
+            _live = next(
+                (p for p in _antigravity_executed_hook_paths()
+                 if p.exists() and _antigravity_hook_command_present(p)),
+                None,
+            )
+            if _live is not None:
+                rt = "round-trips" if _antigravity_dry_run_roundtrips() else "BROKEN"
+                cz_console.info(f"  {'antigravity':14s} {'live':7s} {_live} (dry-run: {rt})")
+            else:
+                cz_console.info(f"  {'antigravity':14s} {'not-live':7s} (no executed PreToolUse hook entry)")
         return 0
 
     for f in findings:

{controlzero-1.9.5 → controlzero-1.9.7}/controlzero/cli/hosts/antigravity.py

@@ -28,14 +28,21 @@ danicat.dev):
   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).
+HITL mapping (GA blocker #2, issue #1248): a Control Zero approval gate maps to
+``force_ask`` by DEFAULT -- a MANDATORY prompt that ignores agy's "Always Allow"
+cache. A plain ``ask`` CAN be silently auto-satisfied by a cached "Always Allow"
+(fail-OPEN on an approval-gated destructive action), so it is NOT the default
+and is NEVER reached by the unrecognized-value fallback. The token is
+configurable via ``CZ_ANTIGRAVITY_HITL_DECISION``:
+
+* unset / unrecognized -> ``force_ask`` (fail-closed default).
+* ``force_ask`` -> guaranteed prompt.
+* ``deny`` -> hard block-with-reason. Use this as the fallback when a pinned agy
+  build is known to reject ``force_ask``; the gate then blocks rather than
+  silently auto-approving.
+* ``ask`` -> the legacy cache-bypassable behavior. Permitted only as an
+  explicit, knowing downgrade (fail-open).
+* ``allow`` -> defeats the gate; explicit override only.
 
 Subagent tool calls fire the parent ``PreToolUse`` hook, so one adapter
 governs parent + subagents.
@@ -68,21 +75,57 @@ _ENV_PREFIXES = ("ANTIGRAVITY_", "AGY_")
 
 # Source-confirmed decision tokens for PreToolUse output.
 _VALID_DECISIONS = frozenset({"allow", "deny", "ask", "force_ask"})
-_DEFAULT_HITL_DECISION = "ask"
+
+# HITL approval-gate token. GA blocker #2 (issue #1248): a plain ``ask`` CAN be
+# silently auto-satisfied by a cached "Always Allow" -- which is fail-OPEN on an
+# approval-gated destructive action. For a governance gate that is unacceptable,
+# so the safe default for a HITL gate is ``force_ask`` (a MANDATORY prompt that
+# ignores the cache). If a particular agy build rejects ``force_ask`` (older
+# builds may not implement it), the operator must fall back to ``deny`` -- a hard
+# block-with-reason -- NOT to ``ask``. ``ask`` is therefore no longer the default
+# and is never reached by the unrecognized-value fallback; an operator who wants
+# the cache-bypassable behavior must opt into it EXPLICITLY and knowingly.
+_DEFAULT_HITL_DECISION = "force_ask"
+# The fail-closed fallback for a HITL gate when the configured token is empty or
+# unrecognized. Must be a guaranteed-prompt / hard-block token, never ``ask``.
+_HITL_FALLBACK_DECISION = "force_ask"
+# Tokens that are SAFE for a HITL approval gate (cannot be silently
+# auto-approved from a cache). ``ask`` is deliberately excluded -- it is
+# cache-bypassable -- and ``allow`` is excluded because allowing outright defeats
+# the gate. Only an explicit operator override may select a non-safe token.
+_HITL_SAFE_DECISIONS = frozenset({"force_ask", "deny"})
 
 
 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.
+    GA blocker #2 (issue #1248): a HITL gate must never silently auto-approve.
+    A plain ``ask`` can be satisfied by agy's cached "Always Allow" (fail-OPEN),
+    so it is NOT a safe HITL token. The resolution rules are:
+
+    * Default (env unset): ``force_ask`` -- a MANDATORY prompt that ignores the
+      cache. This is the safe, fail-closed choice.
+    * Empty / unrecognized value: falls back to ``force_ask`` (NEVER ``ask``),
+      so a typo or an unset shell can never silently downgrade the gate to a
+      cache-bypassable token.
+    * Explicit operator override via ``CZ_ANTIGRAVITY_HITL_DECISION``:
+        - ``force_ask`` -- guaranteed prompt (the default).
+        - ``deny`` -- hard block-with-reason. This is the correct fallback when
+          a pinned agy build is known to reject ``force_ask`` (which would
+          otherwise trip the ``invalid_args`` -> deny trap anyway, but ``deny``
+          makes the block explicit and carries the reason).
+        - ``ask`` -- the LEGACY cache-bypassable behavior. Permitted only as an
+          explicit, knowing downgrade; it is fail-open and must not be used for
+          an approval-gated destructive action.
+        - ``allow`` -- defeats the gate entirely; permitted only as an explicit
+          override (e.g. a soak/observe deployment).
     """
     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
+    if raw in _VALID_DECISIONS:
+        return raw
+    # Empty or unrecognized -> fail closed to a guaranteed-prompt token.
+    return _HITL_FALLBACK_DECISION
 
 
 class AntigravityAdapter(HostAdapter):