controlzero 1.9.4__tar.gz → 1.9.6__tar.gz

{controlzero-1.9.4 → controlzero-1.9.6}/CHANGELOG.md

@@ -1,5 +1,79 @@
 # Changelog
 
+## 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
+
+- **Kiro CLI (`kiro-cli chat`) promoted BETA -> GA.** The CLI surface routes
+  the full event JSON (snake_case `tool_name` / `tool_input`) through the same
+  `controlzero hook-check` -> policy engine -> audit path Claude Code / Codex /
+  Gemini ship on, with argument-level deny rules and `agent="kiro"`
+  (`canonical_source="kiro_cli"`) attribution. The **Kiro IDE** surface stays
+  **limited preview**: upstream Kiro #6188 (open through IDE v0.12) delivers an
+  empty payload to IDE `preToolUse` hooks, so argument-level pre-tool blocking
+  is impossible IDE-side; the IDE Pre Tool Use hook still ships disabled.
+
+### Added
+
+- **`controlzero kiro verify`** -- install-validation self-test. Confirms the
+  Kiro CLI hook is wired into `settings.json` AND fires a synthetic known-deny
+  payload through the real hook to prove it blocks (exit 2). Exit 0 = installed
+  and enforcing; exit 1 = a problem (not wired, or a deny was not blocked).
+
+- **Strict mode for the Kiro CLI hook-check path (`CZ_KIRO_CLI_STRICT`).** When
+  set (the Kiro CLI installer wires it on by default), `hook-check` fails
+  **closed** (exit 2, with a cause-specific diagnostic) on empty stdin,
+  malformed JSON, a missing `tool_name`, or an installed-but-unreadable local
+  policy -- distinguishing "policy unreadable" from "no policy installed". The
+  Kiro CLI always delivers a well-formed payload, so such a payload is an
+  anomaly, not a benign passthrough. The default for every other host stays
+  fail-open so an agent is never bricked by a partial payload.
+
+### Fixed
+
+- Tightened the Kiro adapter docstring: IDE post-tool-use carries the tool
+  **name + result only** (`toolArgs` arrives empty, #6188), not the arguments.
+
 ## 1.9.4 -- 2026-06-16 (actionable E1101 / API-key-rejected message, #1254, epic gh#1247)
 
 ### Fixed
@@ -97,6 +171,7 @@ second-opinion). It is deliberately **narrow and gated**:
   bundle translator -> `PolicySettings`. Local YAML policies may set
   `settings.default_on_empty`. The dashboard observe-mode indicator +
   CLI `status` line remain a separate frontend/CLI follow-up.
+
 ## 1.9.1 -- 2026-06-16 (hosted-mode local audit log P0, epic gh#1247)
 
 ### Fixed

{controlzero-1.9.4 → controlzero-1.9.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: controlzero
-Version: 1.9.4
+Version: 1.9.6
 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
@@ -129,7 +129,7 @@ Templates available (`controlzero init -t <name>`):
 - `autogen` — AutoGen starter policy
 - `codex-cli` — Codex CLI hook starter
 - `gemini-cli` — Gemini CLI hook starter
-- `kiro` — Kiro (AWS IDE) hook starter (Beta)
+- `kiro` — Kiro (AWS) hook starter (CLI: GA; IDE: limited preview)
 - `antigravity` — Google Antigravity (IDE + `agy` CLI) hook starter (Beta)
 
 ## Loading a policy
@@ -225,14 +225,27 @@ to the Control Zero backend so your team can see it on the dashboard.
 
 ## Local audit log
 
-When running without an API key, every decision is written to `./controlzero.log`
-with daily rotation and 30-day retention. Tail it:
+Every decision (allow **and** deny) is written to a local audit log in **every
+mode** — local, hybrid, and hosted. The local log is never skipped, so
+`controlzero tail`, `cz debug-bundle`, and the tamper hash-chain always have a
+record to read.
 
 ```bash
 controlzero tail
 ```
 
-Configure rotation via the client:
+Default paths:
+
+- **Local / unenrolled mode** (no API key): `./controlzero.log`, with daily
+  rotation and 30-day retention.
+- **Hosted mode** (`CONTROLZERO_API_KEY` set): `~/.controlzero/audit.log` when you
+  do not pass an explicit `log_path`. Local audit is written **in addition to**
+  the remote dashboard sink, not instead of it — the remote sink is layered on
+  top. In hosted mode, PII and financial DLP `matched_text` is redacted from the
+  local plaintext row (the secret category is already hashed); the remote sink
+  keeps full fidelity.
+
+Configure rotation via the client (honoured in any mode):
 
 ```python
 cz = Client(
@@ -245,9 +258,6 @@ cz = Client(
 )
 ```
 
-When `CONTROLZERO_API_KEY` is set, audit ships to the remote dashboard and
-these `log_*` options are ignored with a warning.
-
 ## Hybrid mode
 
 Default (T103, 2026-05-12): when `CONTROLZERO_API_KEY` is set, the

{controlzero-1.9.4 → controlzero-1.9.6}/README.md

@@ -75,7 +75,7 @@ Templates available (`controlzero init -t <name>`):
 - `autogen` — AutoGen starter policy
 - `codex-cli` — Codex CLI hook starter
 - `gemini-cli` — Gemini CLI hook starter
-- `kiro` — Kiro (AWS IDE) hook starter (Beta)
+- `kiro` — Kiro (AWS) hook starter (CLI: GA; IDE: limited preview)
 - `antigravity` — Google Antigravity (IDE + `agy` CLI) hook starter (Beta)
 
 ## Loading a policy
@@ -171,14 +171,27 @@ to the Control Zero backend so your team can see it on the dashboard.
 
 ## Local audit log
 
-When running without an API key, every decision is written to `./controlzero.log`
-with daily rotation and 30-day retention. Tail it:
+Every decision (allow **and** deny) is written to a local audit log in **every
+mode** — local, hybrid, and hosted. The local log is never skipped, so
+`controlzero tail`, `cz debug-bundle`, and the tamper hash-chain always have a
+record to read.
 
 ```bash
 controlzero tail
 ```
 
-Configure rotation via the client:
+Default paths:
+
+- **Local / unenrolled mode** (no API key): `./controlzero.log`, with daily
+  rotation and 30-day retention.
+- **Hosted mode** (`CONTROLZERO_API_KEY` set): `~/.controlzero/audit.log` when you
+  do not pass an explicit `log_path`. Local audit is written **in addition to**
+  the remote dashboard sink, not instead of it — the remote sink is layered on
+  top. In hosted mode, PII and financial DLP `matched_text` is redacted from the
+  local plaintext row (the secret category is already hashed); the remote sink
+  keeps full fidelity.
+
+Configure rotation via the client (honoured in any mode):
 
 ```python
 cz = Client(
@@ -191,9 +204,6 @@ cz = Client(
 )
 ```
 
-When `CONTROLZERO_API_KEY` is set, audit ships to the remote dashboard and
-these `log_*` options are ignored with a warning.
-
 ## Hybrid mode
 
 Default (T103, 2026-05-12): when `CONTROLZERO_API_KEY` is set, the

{controlzero-1.9.4 → controlzero-1.9.6}/controlzero/__init__.py

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

controlzero-1.9.6/controlzero/cli/__main__.py

@@ -0,0 +1,13 @@
+"""Enable ``python -m controlzero.cli`` to run the Control Zero CLI.
+
+Mirrors the ``controlzero`` console-script entry point. Used by
+``controlzero kiro verify`` to invoke hook-check as a subprocess in a way
+that works even when the console script is not on PATH (e.g. CI, venvs).
+"""
+
+from __future__ import annotations
+
+from controlzero.cli.main import cli
+
+if __name__ == "__main__":
+    cli()

{controlzero-1.9.4 → controlzero-1.9.6}/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.4 → controlzero-1.9.6}/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):

{controlzero-1.9.4 → controlzero-1.9.6}/controlzero/cli/hosts/kiro.py

@@ -22,10 +22,13 @@ correct.
    stdin shape before piping to hook-check, and sets ``CZ_KIRO_SURFACE=ide``
    so KiroIDEAdapter claims the call.
 
-Known upstream bug (kiro #7375 / #7408 / #7500): IDE ``preToolUse`` currently
-delivers ``USER_PROMPT={}`` with no tool context, so IDE argument-level
-pre-tool policy is bounded; prompt-submit and post-tool-use carry data. See
-docs/integrations/kiro-hook-payloads.md. Pin the validated Kiro version.
+Known upstream bug (kiro #6188 / #7375 / #7408 / #7500): IDE ``preToolUse``
+currently delivers ``USER_PROMPT={}`` with no tool context, so IDE
+argument-level pre-tool policy is bounded. Prompt-submit carries the raw
+prompt text; post-tool-use carries the tool *name + result only* (``toolArgs``
+arrives empty, #6188), so IDE post-tool data does not include the tool's
+arguments. See docs/integrations/kiro-hook-payloads.md. Pin the validated
+Kiro version.
 
 Note on adapter ordering: Claude Code matches PascalCase ``hook_event_name``
 (``PreToolUse``), Kiro CLI matches camelCase (``preToolUse``) -- byte-disjoint,