controlzero 1.11.5__tar.gz → 1.11.6__tar.gz

{controlzero-1.11.5 → controlzero-1.11.6}/CHANGELOG.md

@@ -1,5 +1,43 @@
 # Changelog
 
+## 1.11.6 -- 2026-06-21 (cross-surface enforcement hardening: Kiro v3 + Antigravity honesty + warn-mode)
+
+Ships the #1373 / #65 cross-surface enforcement work and follow-ups that landed
+after 1.11.5 was published.
+
+### Fixed
+
+- **Kiro CLI v3 enforcement (#1375 / #1378).** The shipping kiro-cli (>= 2.8.x)
+  enforces ONLY via an agent-config `hooks.preToolUse` block on the default
+  agent. `controlzero install kiro` now writes `~/.kiro/agents/controlzero.json`
+  (matchers `execute_bash` / `fs_write` / `fs_read` / `use_aws`, interpreter-
+  pinned `hook-check --strict`) and sets it as the default agent. The legacy v2
+  embedded `settings.json` hooks and standalone `.kiro/hooks/*.json` are ignored
+  by the shipping CLI. Host-verified on kiro-cli 2.8.1: a denied bash command is
+  blocked; an allowed file read proceeds.
+- **Crash-proof hook entry (#1189 / #1377).** `python -m controlzero` and the
+  console scripts route through the crash-proof `hook_entry`, so a broken
+  install fails CLOSED, not open.
+- **Kiro deciding-gate fail-close (#1377).** A non-{0,2} hook exit is treated as
+  a block, not a silent allow.
+- **Antigravity #202 honesty (#1373 / #1377).** The agy adapter is `observe`
+  (covered families `file_read` / `file_search`), not a false `enforced` claim;
+  it emits the documented stdout `{"decision":...}` envelope. agy default-mode
+  enforcement is host-side (COMING SOON), not SDK-fixable.
+- **Audit-probe isolation (#1375 / #1377).** kiro/cursor init + verify self-test
+  probes run with an isolated HOME, so synthetic denies never pollute
+  `~/.controlzero/audit.log`.
+
+### Added
+
+- **`default_action` posture toggle is first-class (#1374).** The no-rule-match
+  posture (`deny` default | `warn` | `allow`) is documented + surfaced in the
+  init templates, with a new deny-list recipe. Comment-only in templates; the
+  default stays `deny`.
+- **Kiro sub-agent bypass warning (#7671).** `controlzero install kiro` warns
+  that Kiro does not fire preToolUse hooks for sub-agent tool calls (upstream
+  kiro #7671) -- direct tool calls are governed, subagent calls are not.
+
 ## 1.11.5 -- 2026-06-19 (cross-surface CONTROLZERO_CLIENT foreign-pin fail-open)
 
 Closes a routing fail-open where an explicit `CONTROLZERO_CLIENT` pin -- set by

{controlzero-1.11.5 → controlzero-1.11.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: controlzero
-Version: 1.11.5
+Version: 1.11.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

{controlzero-1.11.5 → controlzero-1.11.6}/controlzero/__init__.py

@@ -41,7 +41,7 @@ from controlzero.hitl.grant_protocol import (
 from controlzero.policy_loader import load_policy
 from controlzero.secrets import SecretRef, SecretStr, secret_ref
 
-__version__ = "1.11.5"
+__version__ = "1.11.6"
 
 __all__ = [
     "Client",

controlzero-1.11.6/controlzero/__main__.py

@@ -0,0 +1,23 @@
+"""Enable ``python -m controlzero`` to run the CLI.
+
+The Kiro CLI / Cursor hook commands pin the interpreter as
+``"<sys.executable>" -m controlzero hook-check --strict`` (#1265) so the host
+invokes the exact, importable controlzero the user installed, never a bare
+``controlzero`` that PATH might resolve to a broken or shadowing install.
+
+CRITICAL (#1373 / re-opens #1189): this entry MUST route through the crash-proof
+``hook_entry.cli`` shim, NOT ``controlzero.cli.main:cli`` directly. The
+interpreter-pin made every Kiro/Cursor hook run ``python -m controlzero
+hook-check`` -> this module. A direct unguarded ``from controlzero.cli.main
+import cli`` raises a bare nonzero traceback on a broken/partial install (missing
+transitive dep, packaging defect); Kiro reads any exit code that is neither 0
+nor 2 as "warn / proceed" -> the tool RUNS while audit may log a deny. Routing
+through ``hook_entry.cli`` fails SAFE (exit 2 = block) on an import crash for a
+hook invocation -- closing the exact #1189 fail-open the console script already
+fixed but ``-m controlzero`` had silently bypassed.
+"""
+
+from controlzero.cli.hook_entry import cli
+
+if __name__ == "__main__":
+    cli()

{controlzero-1.11.5 → controlzero-1.11.6}/controlzero/cli/__main__.py

@@ -3,11 +3,16 @@
 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).
+
+Routes through the crash-proof ``hook_entry.cli`` shim (#1189 / #1373): this is
+a hook-invocation path, so an import crash on a broken install must fail SAFE
+(exit 2 = block), never escape as a bare nonzero traceback that a host reads as
+"warn / proceed".
 """
 
 from __future__ import annotations
 
-from controlzero.cli.main import cli
+from controlzero.cli.hook_entry import cli
 
 if __name__ == "__main__":
     cli()

{controlzero-1.11.5 → controlzero-1.11.6}/controlzero/cli/hosts/antigravity.py

@@ -183,26 +183,51 @@ def _resolve_hitl_decision(env: Mapping[str, str] | None = None) -> str:
 
 class AntigravityAdapter(HostAdapter):
     name = "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.
+    # Antigravity's documented block contract is the stdout JSON
+    # ``{"decision":"deny"}``, NOT the exit code -- so ``decision_via_exit_code``
+    # stays False (the base exit-code folding does not apply; this adapter owns
+    # its own exit-code rule via ``_exit_code_for`` below).
     decision_via_exit_code = False
 
-    # Coverage-as-data (#202). Antigravity's PreToolUse gate sees the tool
-    # arguments and decides via the stdout JSON (block_mechanism is
-    # stdout_decision, NOT exit code). CRITICAL: agy reads an empty /
-    # decision-less stdout as invalid_args -> DENY, so empty_stdout_is="deny"
-    # and the render envelope ALWAYS carries an explicit decision. PostToolUse /
-    # PostInvocation / Stop are observe only.
+    # Coverage-as-data (#202, #1373). HONESTY: shipped Antigravity (1.0.1 /
+    # 1.0.3) does NOT route the run_command / Bash / file-WRITE family through
+    # the user PreToolUse hook -- it uses a NATIVE confirmation dialog. Our
+    # adapter is therefore never invoked for those destructive calls, so even a
+    # perfect deny verdict is never consulted: we CANNOT enforce them. Claiming
+    # tier="enforced" over ``covered_tool_families=("*",)`` was a #202 false
+    # claim (issue #1373).
+    #
+    # So the tier is ``observe`` (the not-functional-end-to-end posture this
+    # adapter-tier enum carries; mirrors how kiro_ide declares the bounded IDE
+    # surface). The maturity story for the shell/file family on the public
+    # surfaces is COMING SOON -- not GA/BETA -- until Antigravity ships a real
+    # shell-blocking hook path (partner-integration track). ``covered_tool_
+    # families`` is narrowed to the families agy actually ROUTES to the hook
+    # (reads / observe: file_read, file_search; PostToolUse observe) -- NOT the
+    # shell/Bash/file_write family. ``block_mechanism`` is ``stdout_decision``:
+    # agy's documented contract is the stdout ``{"decision":"deny"}`` token, and
+    # ``decision_via_exit_code=False`` so the exit code stays 0 (a deliberate
+    # #1248 decision -- a non-zero hook exit on agy is risky / unverified, so we
+    # rely on the documented stdout deny, which blocks).
+    #
+    # CRITICAL still holds: agy reads an empty / decision-less stdout as
+    # invalid_args -> DENY, so empty_stdout_is="deny" and the render envelope
+    # ALWAYS carries an explicit decision.
     coverage = CoverageDecl(
-        tier="enforced",
+        tier="observe",
         block_mechanism="stdout_decision",
         deciding_events=("PreToolUse",),
         observe_events=("PostToolUse", "PostInvocation", "Stop"),
         delivers_tool_args=True,
         empty_stdout_is="deny",
-        covered_tool_families=("*",),
+        # ONLY the families agy actually routes to the hook today: read /
+        # discovery tools (observed). The shell (run_command -> Bash) and the
+        # file-WRITE family (write_to_file / replace_file_content) are
+        # intentionally ABSENT -- agy never calls our hook for them, so we
+        # cannot enforce them (#1373). Adding them back here would re-open the
+        # #202 false claim guarded by TestAntigravityCoverageHonesty1373 in
+        # tests/test_antigravity_adapter.py.
+        covered_tool_families=("file_read", "file_search"),
         min_core_version="1.9.0",
         adapter_contract_version="1",
     )
@@ -257,6 +282,33 @@ class AntigravityAdapter(HostAdapter):
             normalized["tool_input"] = args if isinstance(args, dict) else {}
         return normalized
 
+    def _verdict(self, decision: CZDecision) -> str:
+        """Single source of truth for the agy decision TOKEN.
+
+        The stdout envelope (``render_envelope``) derives from THIS method.
+        agy decides from this stdout token (the exit code stays 0 per #1248):
+
+        * HITL (``requires_approval`` deny) -> ``_resolve_hitl_decision()``
+          (``force_ask`` by default; ``ask``/``deny``/``allow`` only via an
+          explicit ``CZ_ANTIGRAVITY_HITL_DECISION`` override).
+        * hard deny -> ``"deny"``.
+        * allow / warn -> ``"allow"``.
+        """
+        if decision.is_hitl:
+            return _resolve_hitl_decision()
+        if decision.is_deny:
+            return "deny"
+        return "allow"
+
+    # NOTE (#1373): agy intentionally does NOT override the exit code. agy's
+    # documented block contract is the stdout ``{"decision":"deny"}`` token, and
+    # ``decision_via_exit_code=False`` keeps the exit code 0 for every decision
+    # (the deliberate #1248 design -- a non-zero hook exit on agy is unverified
+    # / risky, so we rely on the stdout deny, which blocks). An exit-2 backstop
+    # was considered (finding F1) and dropped: it could not be validated against
+    # a live agy and would contradict #1248. The honest posture is the
+    # CoverageDecl above (tier=observe; shell/file COMING SOON).
+
     def render_envelope(self, decision: CZDecision) -> dict:
         """Render to Antigravity's PreToolUse stdout-JSON contract.
 
@@ -265,14 +317,10 @@ class AntigravityAdapter(HostAdapter):
         (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.
+        with agy's reserved output keys. The decision token comes from the
+        single-source ``_verdict``.
         """
-        if decision.is_hitl:
-            verdict = _resolve_hitl_decision()
-        elif decision.is_deny:
-            verdict = "deny"
-        else:
-            verdict = "allow"
+        verdict = self._verdict(decision)
 
         envelope: dict = {
             "decision": verdict,

{controlzero-1.11.5 → controlzero-1.11.6}/controlzero/cli/kiro_adapter.py

@@ -24,6 +24,13 @@ crashes the IDE -- on an unparseable / empty payload it applies
 CZ_KIRO_UNKNOWN_PAYLOAD (default ``closed`` = block, governance-safe; set to
 ``open`` to allow).
 
+The shim re-execs the SAME interpreter that installed it
+(``sys.executable -m controlzero hook-check``), not a bare ``controlzero`` on
+PATH, so a venv/renamed-bin/broken-global cannot make it ENOENT. If the engine
+still cannot be spawned, a DECIDING event (preToolUse / promptSubmit) FAILS
+CLOSED (block, exit 2) -- never a silent allow (#1373 / F2); a post-write file
+event stays observe-only (allow, exit 0).
+
 KNOWN UPSTREAM BUG (kiro #7375 / #7408 / #7500): IDE ``preToolUse`` currently
 delivers ``USER_PROMPT={}`` with no tool context, so argument-level pre-tool
 policy is bounded until upstream ships the fix. prompt-submit and post-tool-use
@@ -138,16 +145,39 @@ def main(argv: list[str] | None = None) -> int:
     env["CZ_KIRO_SURFACE"] = "ide"
     env.setdefault("CONTROLZERO_CLIENT", "kiro-ide")
     try:
+        # #1373 / F2 INTERPRETER RE-EXEC + FAIL CLOSED: re-exec the SAME
+        # interpreter that installed this shim (sys.executable) against the
+        # controlzero module, NOT a bare `controlzero` looked up on PATH. The
+        # interpreter that imported this module provably imports controlzero, so
+        # `-m controlzero hook-check` cannot ENOENT on a venv/renamed-bin/broken
+        # global the way a PATH lookup of `controlzero` can. On a spawn failure
+        # we now FAIL CLOSED for a deciding event (block, exit 2) instead of the
+        # old silent allow (exit 0) -- that allow was a fail-OPEN: every tool
+        # call slipped through unguarded while the audit still recorded the
+        # intended decision.
         proc = subprocess.run(
-            ["controlzero", "hook-check"],
+            [sys.executable, "-m", "controlzero", "hook-check"],
             input=json.dumps(payload),
             text=True,
             env=env,
         )
-    except FileNotFoundError:
-        # controlzero not on PATH: never brick the IDE.
-        print("controlzero(kiro): controlzero CLI not found; allowing", file=sys.stderr)
-        return 0
+    except (FileNotFoundError, OSError) as e:
+        if event in _FILE_EVENTS:
+            # A post-write file save is observe-only -- there is nothing to
+            # block, so a spawn failure cannot become a fail-open here.
+            print(
+                "controlzero(kiro): could not start the hook-check engine "
+                f"({e}); file event is observe-only, allowing the save",
+                file=sys.stderr,
+            )
+            return 0
+        # Deciding gate (preToolUse / promptSubmit): FAIL CLOSED, block.
+        print(
+            "controlzero(kiro): could not start the hook-check engine "
+            f"({e}); failing CLOSED for the deciding gate (blocking)",
+            file=sys.stderr,
+        )
+        return 2
 
     if event in _FILE_EVENTS:
         # OBSERVE-ONLY: a file event is post-write -- the file is already
@@ -162,7 +192,23 @@ def main(argv: list[str] | None = None) -> int:
             )
         return 0
 
-    return proc.returncode
+    # Deciding gate (preToolUse / promptSubmit): collapse the engine exit to a
+    # BINARY decision (#1373). hook-check emits 0 (allow) or 2 (deny) on a clean
+    # decision; ANY OTHER exit means the spawned engine CRASHED after starting
+    # (uncaught exception, OOM-kill 137, signal 128+n, a stray sys.exit(1)).
+    # Kiro reads any non-{0,2} exit as "warn / proceed" -> the tool RUNS while
+    # audit may already have logged a deny: the exact #1373 fail-open. So only a
+    # clean exit 0 allows; everything else fails CLOSED (block, exit 2).
+    if proc.returncode == 0:
+        return 0
+    if proc.returncode != 2:
+        print(
+            "controlzero(kiro): the hook-check engine exited with an unexpected "
+            f"code ({proc.returncode}); failing CLOSED for the deciding gate "
+            "(blocking) rather than letting the tool proceed",
+            file=sys.stderr,
+        )
+    return 2
 
 
 if __name__ == "__main__":