controlzero 1.11.4__tar.gz → 1.11.5__tar.gz

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

@@ -1,5 +1,26 @@
 # Changelog
 
+## 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 install <host>` so a kiro/codex/antigravity/cursor hook routes to
+the right adapter -- was NOT authoritative. The `ClaudeCodeAdapter` is first in
+the registry and falls through to ambient Anthropic env hints (`CLAUDECODE` /
+`CLAUDE_CODE` / ...), so a correctly installed foreign-host hook that ALSO
+carried an ambient `CLAUDECODE` (e.g. launched from a Claude Code-spawned shell)
+was hijacked to the Claude adapter, which renders the wrong wire shape and reads
+as allow on a destructive tool call.
+
+### Fixed
+
+- **Foreign `CONTROLZERO_CLIENT` pin now defers (cross-surface fail-open).**
+  Every host adapter's `claim()` defers when `CONTROLZERO_CLIENT` names a
+  DIFFERENT client, via the shared `HostAdapter._pinned_elsewhere` helper, so an
+  installer-pinned hook can never be hijacked by an ambient `CLAUDECODE`;
+  `UnknownHostAdapter` stays the always-claim backstop. A 7-surface guard matrix
+  (`tests/test_hosts_adapter.py`) pins it fail-if-reverted. Mirrors the Node SDK
+  fix. gh#81.
+
 ## 1.11.4 -- 2026-06-17 (close the count==0 degraded fail-open + stale-empty-cache replay + cached-bundle integrity, gh#1303)
 
 Closes a degraded-bundle fail-open in the count-provenance discriminator plus
@@ -715,7 +736,7 @@ secret-value-leak guard that gates every outbound HITL payload.
   POSTs a HITL approval request, builds the body from the
   `PolicyDecision`, threads in `X-CZ-Requestor-Email` from
   `~/.controlzero/config.yaml`, sends a per-call `Idempotency-Key`, and
-  returns a `PendingApproval`. Maps backend error codes E1305-E1308 onto
+  returns a `PendingApproval`. Maps backend error codes E1705-E1708 onto
   the matching SDK exceptions. (#577)
 
 ### Conformance

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: controlzero
-Version: 1.11.4
+Version: 1.11.5
 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.4 → controlzero-1.11.5}/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.4"
+__version__ = "1.11.5"
 
 __all__ = [
     "Client",

{controlzero-1.11.4 → controlzero-1.11.5}/controlzero/cli/doctor.py

@@ -353,7 +353,9 @@ def _antigravity_dry_run_roundtrips() -> bool:
         adapter = select_adapter({}, {"CONTROLZERO_CLIENT": "antigravity"})
         if getattr(adapter, "name", "") != "antigravity":
             return False
-        out = adapter.render(
+        # render_envelope is the per-host wire dict; render() folds it into a
+        # RenderResult (exit code + stdout). The dry-run inspects the envelope.
+        out = adapter.render_envelope(
             CZDecision(effect="allow", reason="doctor dry-run", reason_code="RULE_MATCH")
         )
         return isinstance(out, dict) and out.get("decision") == "allow"

controlzero-1.11.5/controlzero/cli/hook_entry.py

@@ -0,0 +1,118 @@
+"""Crash-proof console-script entry point for the ``controlzero`` CLI (#1189).
+
+The ``controlzero`` console script declared in ``pyproject.toml`` MUST NOT be
+pointed directly at ``controlzero.cli.main:cli``. The pip-generated wrapper
+imports the target at module load with no guard, so a top-level import crash in
+``controlzero/cli/main.py`` (a missing transitive dependency, a packaging
+defect, a syntax error in any eagerly-imported submodule) raises before
+``cli()`` runs. The wrapper then exits nonzero with a traceback, and a host that
+treats nonzero-with-no-decision as "proceed" (Claude Code's PreToolUse falls
+back to allow on a hook it cannot evaluate) silently lets the tool call
+through. That is a fail-OPEN on the governance hot path -- the exact defect
+QA #1189 flagged.
+
+This shim makes the entry point crash-proof:
+
+  * The heavy import of ``controlzero.cli.main`` happens inside a try/except
+    with a ``sys.path`` source-checkout fallback, mirroring
+    ``tools/cz-kiro-adapter`` so a dev checkout that has not been pip-installed
+    still resolves the package.
+  * If the import or evaluation of the CLI cannot complete AT ALL and this is a
+    hook invocation (``hook-check`` on argv -- the governance hot path), the
+    shim fails SAFE: it writes a hard, human-readable error to stderr and exits
+    with the host's DENY/block code (Claude Code PreToolUse = exit 2), never a
+    silent allow.
+  * For a non-hook invocation (interactive ``controlzero ...`` usage) a broken
+    install should surface its traceback so the user can fix it -- there is no
+    governance decision at stake -- so the shim re-raises in that case.
+
+What this shim does NOT change: the runtime fail-OPEN contract that lives
+inside ``hook_check`` (E1501 bad-JSON, E1502 timeout, empty stdin, missing
+tool_name) is intentional and is preserved. Those paths are reached only after
+the CLI imports successfully and represent a *decision* to pass through, not an
+import crash. This shim only converts the previously-silent import-crash
+fall-through into an explicit fail-safe deny.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+
+# Host block/deny exit codes for the hook hot path. Claude Code's PreToolUse
+# protocol treats exit 2 as "block"; Kiro reuses the same convention. We do not
+# have the resolved host adapter available before the import succeeds, so we use
+# the lowest-common-denominator block code (2), which every supported host
+# interprets as deny rather than allow.
+_HOOK_DENY_EXIT_CODE = 2
+
+_HOOK_SUBCOMMANDS = frozenset({"hook-check"})
+
+
+def _is_hook_invocation(argv: list[str]) -> bool:
+    """True when the process was launched on the governance hot path.
+
+    The ``hook-check`` subcommand is what hosts (Claude Code, Kiro, Codex,
+    Gemini, Antigravity) wire into their PreToolUse hooks. Detecting it on argv
+    lets the shim choose fail-SAFE (deny) on an import crash for hook calls
+    while leaving interactive CLI usage to surface its traceback normally.
+    """
+    return any(arg in _HOOK_SUBCOMMANDS for arg in argv[1:])
+
+
+def cli() -> None:
+    """Crash-proof wrapper around ``controlzero.cli.main:cli``.
+
+    Defers the heavy import so an import-time crash cannot escape as a bare
+    nonzero traceback that a host would mistake for "allow".
+    """
+    try:
+        from controlzero.cli.main import cli as _real_cli
+    except ModuleNotFoundError:
+        # Possibly a source checkout where the package is not pip-installed.
+        # Add the SDK root to sys.path and retry once, mirroring
+        # tools/cz-kiro-adapter. controlzero/cli/hook_entry.py -> SDK root is
+        # three levels up (controlzero/cli/ -> controlzero/ -> SDK root).
+        _sdk_root = os.path.dirname(
+            os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+        )
+        if _sdk_root not in sys.path:
+            sys.path.insert(0, _sdk_root)
+        try:
+            from controlzero.cli.main import cli as _real_cli
+        except BaseException:  # noqa: BLE001 -- crash-proof boundary
+            _fail_safe_or_reraise()
+            return
+    except BaseException:  # noqa: BLE001 -- crash-proof boundary
+        # Any other top-level import failure (ImportError on a transitive dep,
+        # a syntax error in an eagerly-imported submodule, etc).
+        _fail_safe_or_reraise()
+        return
+
+    _real_cli()
+
+
+def _fail_safe_or_reraise() -> None:
+    """On import failure: fail-safe DENY for hook calls, re-raise otherwise.
+
+    Reads the live exception from ``sys.exc_info`` so it can re-raise the
+    original traceback for interactive usage.
+    """
+    if _is_hook_invocation(sys.argv):
+        exc = sys.exc_info()[1]
+        # Hard, loud error to stderr -- never a silent allow. The host sees a
+        # nonzero block exit code and denies the tool call.
+        sys.stderr.write(
+            "[Control Zero] hook entry point could not load the policy engine "
+            f"({type(exc).__name__}: {exc}); DENYING this tool call (fail-safe). "
+            "Reinstall the controlzero package to restore policy enforcement.\n"
+        )
+        sys.stderr.flush()
+        sys.exit(_HOOK_DENY_EXIT_CODE)
+    # Not a hook invocation: surface the real traceback so the user can fix
+    # their install. No governance decision is at stake here.
+    raise
+
+
+if __name__ == "__main__":
+    cli()

{controlzero-1.11.4 → controlzero-1.11.5}/controlzero/cli/hosts/__init__.py

@@ -55,9 +55,18 @@ known host treats no-decision as "proceed") and the universal
 from __future__ import annotations
 
 from controlzero.cli.hosts.antigravity import AntigravityAdapter
-from controlzero.cli.hosts.base import CZDecision, HostAdapter
+from controlzero.cli.hosts.base import (
+    AdapterError,
+    CoverageDecl,
+    CZDecision,
+    HostAdapter,
+    RenderResult,
+    ToolCall,
+)
 from controlzero.cli.hosts.claude_code import ClaudeCodeAdapter
 from controlzero.cli.hosts.codex_cli import CodexCLIAdapter
+from controlzero.cli.hosts.cursor import CursorIDEAdapter
+from controlzero.cli.hosts.cursor_cli import CursorCLIAdapter
 from controlzero.cli.hosts.gemini_cli import GeminiCLIAdapter
 from controlzero.cli.hosts.kiro import KiroCLIAdapter, KiroIDEAdapter
 from controlzero.cli.hosts.unknown import UnknownHostAdapter
@@ -77,8 +86,10 @@ REGISTRY: list[HostAdapter] = [
     CodexCLIAdapter(),
     GeminiCLIAdapter(),
     AntigravityAdapter(),  # distinct toolCall / PreToolCall signature
+    CursorCLIAdapter(),    # beforeShellExecution + top-level `command`, no tool_name (before KiroCLI)
     KiroCLIAdapter(),      # camelCase hook_event_name (disjoint from Claude PascalCase)
     KiroIDEAdapter(),      # CZ_KIRO_SURFACE=ide / TERM_PROGRAM=kiro (shim-set)
+    CursorIDEAdapter(),    # cursor_version / generation_id payload marker or CURSOR_* env (after KiroIDE)
     UnknownHostAdapter(),  # always claims; must stay at the tail
 ]
 
@@ -105,9 +116,15 @@ def select_adapter(payload: dict, env) -> HostAdapter:
 
 __all__ = [
     "CZDecision",
+    "ToolCall",
+    "RenderResult",
+    "CoverageDecl",
+    "AdapterError",
     "HostAdapter",
     "ClaudeCodeAdapter",
     "CodexCLIAdapter",
+    "CursorCLIAdapter",
+    "CursorIDEAdapter",
     "GeminiCLIAdapter",
     "AntigravityAdapter",
     "KiroCLIAdapter",

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

@@ -55,7 +55,7 @@ from __future__ import annotations
 import os
 from typing import Mapping
 
-from controlzero.cli.hosts.base import CZDecision, HostAdapter
+from controlzero.cli.hosts.base import CoverageDecl, CZDecision, HostAdapter
 
 # File-based EVENT names (NOT the in-process SDK class names). PreToolUse is
 # the deciding gate; PostToolUse is observe-only.
@@ -70,9 +70,62 @@ _ANTIGRAVITY_HOOK_EVENTS = frozenset(
 # 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"})
+# CONTROLZERO_CLIENT values the adapter CLAIMS as Antigravity. Includes the
+# surface-split forms (#58) so an install pinning CONTROLZERO_CLIENT=
+# antigravity_ide / antigravity_cli is still claimed.
+_CLIENT_ALIASES = frozenset(
+    {"antigravity", "agy", "antigravity-cli", "antigravity_ide", "antigravity_cli"}
+)
 _ENV_PREFIXES = ("ANTIGRAVITY_", "AGY_")
 
+# Surface split (#58): one adapter governs BOTH the Antigravity IDE and the
+# ``agy`` CLI -- they share the SAME external PreToolUse stdout-decision hook
+# contract, the same engine-executed ``~/.gemini/config/hooks.json``, and the
+# same sanitized hook environment (only a GEMINI_PROJECT_DIR-style whitelist is
+# forwarded; arbitrary user env vars do NOT reach the hook subshell -- verified
+# cmux#4768). Enforcement is therefore IDENTICAL on both; the founder wants the
+# AUDIT/coverage SOURCE label to distinguish them.
+#
+# There is NO runtime signal that tells the IDE apart from the CLI at hook time
+# (Google's own docs + blog confirm a shared harness + synced settings; the
+# stdin payload carries no surface marker, and the env is sanitized). So the
+# split is INSTALL-TIME: each installer writes the surface into the hook command
+# as ``CONTROLZERO_CLIENT=antigravity_ide`` / ``=antigravity_cli`` (an env var
+# set INSIDE the executed command survives agy's env sanitization because the
+# shell running the command sets it -- it is not inherited from the parent).
+#
+# Back-compat (#58): a bare ``antigravity`` (old SDKs / env-only detection)
+# stays ``antigravity`` -- its own canonical value, NOT remapped -- so existing
+# audit rows and pre-split emitters are never downgraded or rewritten.
+_SOURCE_ANTIGRAVITY = "antigravity"
+_SOURCE_ANTIGRAVITY_IDE = "antigravity_ide"
+_SOURCE_ANTIGRAVITY_CLI = "antigravity_cli"
+# CONTROLZERO_CLIENT values that resolve to the CLI surface. The CLI install
+# pins ``antigravity_cli``; the legacy agy aliases also resolve to CLI since
+# ``agy`` IS the CLI.
+_CLI_SURFACE_CLIENTS = frozenset({"antigravity_cli", "agy", "antigravity-cli"})
+
+
+def _resolve_antigravity_source(env: Mapping[str, str] | None = None) -> str:
+    """Resolve the canonical audit SOURCE for the Antigravity surface (#58).
+
+    Install-time split: the installer pins ``CONTROLZERO_CLIENT`` in the hook
+    command so the runtime knows which surface fired:
+
+    * ``antigravity_ide`` -> ``antigravity_ide`` (the IDE installer).
+    * ``antigravity_cli`` / ``agy`` / ``antigravity-cli`` -> ``antigravity_cli``
+      (the agy CLI installer; the legacy agy aliases ARE the CLI).
+    * anything else (bare ``antigravity``, unset, env-only detection) ->
+      ``antigravity`` -- the back-compat value, never remapped.
+    """
+    src = env if env is not None else os.environ
+    raw = (src.get("CONTROLZERO_CLIENT") or "").strip().lower()
+    if raw == _SOURCE_ANTIGRAVITY_IDE:
+        return _SOURCE_ANTIGRAVITY_IDE
+    if raw in _CLI_SURFACE_CLIENTS:
+        return _SOURCE_ANTIGRAVITY_CLI
+    return _SOURCE_ANTIGRAVITY
+
 # Source-confirmed decision tokens for PreToolUse output.
 _VALID_DECISIONS = frozenset({"allow", "deny", "ask", "force_ask"})
 
@@ -130,16 +183,51 @@ def _resolve_hitl_decision(env: Mapping[str, str] | None = None) -> str:
 
 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
 
+    # 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 = CoverageDecl(
+        tier="enforced",
+        block_mechanism="stdout_decision",
+        deciding_events=("PreToolUse",),
+        observe_events=("PostToolUse", "PostInvocation", "Stop"),
+        delivers_tool_args=True,
+        empty_stdout_is="deny",
+        covered_tool_families=("*",),
+        min_core_version="1.9.0",
+        adapter_contract_version="1",
+    )
+
+    @property
+    def canonical_source(self) -> str:  # type: ignore[override]
+        """Audit SOURCE label, split IDE vs CLI at install time (#58).
+
+        Resolved from ``CONTROLZERO_CLIENT`` so the single adapter governs both
+        surfaces (shared hook contract -> identical enforcement) while the audit
+        row distinguishes ``antigravity_ide`` from ``antigravity_cli``. A bare
+        ``antigravity`` (old SDKs / env-only detection) stays ``antigravity``
+        for back-compat. ``name`` stays ``"antigravity"`` so the fail-closed
+        guards that key on the adapter NAME are unaffected by the source split.
+        """
+        return _resolve_antigravity_source()
+
     def claim(self, payload: dict, env: Mapping[str, str]) -> bool:
         if (env.get("CONTROLZERO_CLIENT") or "").strip().lower() in _CLIENT_ALIASES:
             return True
+        # Cross-surface routing fail-open backstop: a foreign pin defers so the
+        # pinned host's adapter (not this one) claims the call -- even when an
+        # ambient ANTIGRAVITY_/AGY_ env var is also present.
+        if self._pinned_elsewhere(env, _CLIENT_ALIASES):
+            return False
         for key in env:
             if key.upper().startswith(_ENV_PREFIXES):
                 return True
@@ -169,7 +257,7 @@ class AntigravityAdapter(HostAdapter):
             normalized["tool_input"] = args if isinstance(args, dict) else {}
         return normalized
 
-    def render(self, decision: CZDecision) -> dict:
+    def render_envelope(self, decision: CZDecision) -> dict:
         """Render to Antigravity's PreToolUse stdout-JSON contract.
 
         ALWAYS emits an explicit ``decision`` key. An empty / decision-less