controlzero 1.10.1__tar.gz → 1.11.5__tar.gz

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

@@ -1,5 +1,161 @@
 # 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
+the two residuals tracked on gh#1303 after the 1.9.8 degraded/empty fail-open
+fix. All live in the shared decision core / hosted cache, so all five host
+surfaces (Claude Code, Gemini CLI, Codex CLI, Antigravity, Kiro) inherit them.
+
+### Fixed
+
+- **`active_policy_count == 0` no longer treats a degraded bundle as genuinely
+  empty (gh#1303 fail-open).** Part 3 made the stamped count authoritative for
+  genuine-empty, but `genuinely_empty = (count == 0)` did NOT also require the
+  backend's explicit `policies: []`. A bundle with `active_policy_count == 0`
+  whose `policies` key was MISSING or non-list (truncated / malformed /
+  degraded) therefore read as a genuinely-empty project and fell through to
+  OBSERVE -> allow -- the rm-rf fail-open class. Genuine-empty now requires
+  `count == 0` AND an explicit `policies: []` (the backend always ships that
+  for an empty project -- `bundle_handler.go` builds `Policies` as
+  `make([]bundlePolicy, 0)` with no `omitempty`), so a `count == 0` paired with
+  a missing/malformed `policies` key now FAILS CLOSED (`BUNDLE_MISSING`). The
+  gh#1247 genuine-empty observe posture (count == 0 + explicit `[]`) is
+  preserved. The Node and Go SDKs are aligned to the same rule for cross-SDK
+  decision parity.
+- **Stale-empty-cache replay window (gh#1303 residual A).** A cached bundle
+  whose stamped `metadata.active_policy_count` was a legitimate `0` (the
+  project was empty when the bundle was minted) still read as genuinely-empty
+  AFTER a policy was later attached -- because a count cannot see time --
+  so replaying a stale cached empty bundle could silently OBSERVE-allow a
+  project that now HAS a policy. The shared core `translate_to_local_policy`
+  now takes a `genuine_empty_is_authoritative` flag; the hosted orchestrator
+  drops it to `False` once a cached bundle ages past
+  `BUNDLE_CACHE_GENUINE_EMPTY_TTL_S` (the bundle's signed `created_at` vs now).
+  A stale empty bundle then FAILS CLOSED (deny / re-fetch, `BUNDLE_MISSING`)
+  instead of replaying the gh#1247 observe. A FRESH empty bundle keeps the
+  gh#1247 genuine-empty observe posture, and a cached bundle WITH real rules
+  is still enforced as the last-known-good fallback at any age.
+- **Cached-bundle integrity verification (gh#1303 residual B).**
+  `load_cached_bundle` now verifies `sha256(blob) == the stored .meta
+  checksum`. On a mismatch (tampered / corrupt / truncated cache) the cache is
+  ignored and the caller re-fetches -- and, if the backend is unreachable,
+  fails closed -- rather than silently trusting a blob that no longer matches
+  its recorded checksum.
+
+## 1.11.3 -- 2026-06-17 (hosted mode no longer silently ignores a local policy file, #1265)
+
+### Fixed
+
+- **Hosted mode now warns when a local policy file is being ignored (#1265
+  follow-up).** With an API key set, `controlzero hook-check` enforces the
+  HOSTED dashboard bundle and intentionally ignores any local
+  `./controlzero.{yaml,yml,json}` or `~/.controlzero/policy.{yaml,yml,json}`
+  (T103, so a stale local file cannot silently shadow the dashboard). That
+  suppression was SILENT: a customer who dropped a project-local
+  `controlzero.yaml` with a deny rule, expecting it to enforce, got no signal
+  that hosted mode was winning and the file was inert. The hook now emits a
+  loud warning to **stderr** that names the ignored file and explains both
+  remedies -- set `CONTROLZERO_LOCAL_OVERRIDE=1` to use the local file, or edit
+  the policy in the dashboard. The warning is deduped once per process AND once
+  per machine per shadowed path (via a small marker under `~/.controlzero/`), so
+  it surfaces the signal without spamming stderr on every tool call in the
+  per-call hook-subprocess context. Enforcement behavior is UNCHANGED (hosted
+  still wins); the warning never touches stdout, so the exit-0/exit-2 hook
+  decision contract that Claude Code / Kiro / Codex read is unaffected.
+
+## 1.11.2 -- 2026-06-17 (Antigravity PostToolUse observe-only contract, #58)
+
+### Fixed
+
+- **PostToolUse is now observe-only on the Antigravity surface (#58).**
+  The installer wires `controlzero hook-check` to BOTH the `PreToolUse`
+  deciding gate and the `PostToolUse` observe event, but `hook-check` never
+  read the event name -- it ran the full deciding evaluator on every payload.
+  A `PostToolUse` event whose tool matched a deny rule therefore rendered a
+  post-execution `{"decision":"deny"}` (or `force_ask` for a HITL gate): a
+  contract-incorrect verdict on an observe-only event (the tool has already
+  run and cannot be un-run), and on agy's strict stdout schema a deny it can
+  neither honor nor cleanly interpret. `hook-check` now recognizes the
+  post-execution events (`PostToolUse` / `PostInvocation`, plus Kiro's
+  `postToolUse`) and emits the observe no-op **in the form each host expects**:
+  Antigravity (the empty-stdout-is-deny host, `decision_via_exit_code=False`)
+  gets an explicit `{"decision":"allow"}`; the exit-code hosts (Claude Code /
+  Gemini / Codex / Kiro) get **empty stdout + exit 0**, their documented "no
+  opinion, proceed" signal. `PostToolUse` is also a Claude Code event name, so
+  this path is reached on Claude / Gemini post payloads too -- emitting a
+  decision JSON (Claude's `approve`, ...) there would have changed their
+  post-hook stdout contract. The DECIDING gate (`PreToolUse`, and any payload
+  without a recognized post-event name) keeps its fail-closed deciding
+  semantics unchanged. The fix lives in the shared `hook-check` core, so all
+  five governed surfaces inherit it.
+
+
+## 1.11.1 -- 2026-06-17 (kiro-cli hook fail-open fix, #1265)
+
+### Fixed
+
+- **Kiro CLI hook no longer silently fails open (#1265).**
+  `controlzero kiro init` wired a BARE `controlzero hook-check` into
+  `~/.kiro/settings.json`. On a venv install (or a machine with a broken /
+  shadowing `controlzero` on PATH) kiro-cli's hook subshell resolved the wrong
+  interpreter, the hook crashed, and kiro-cli FAILED OPEN -- tools ran with no
+  enforcement, silently. The hook command is now **interpreter-pinned**:
+  `"<python>" -m controlzero hook-check --strict`, so kiro-cli runs the exact
+  Python that installed it regardless of PATH/venv. Strict mode moved from the
+  Windows-unparseable `CZ_KIRO_CLI_STRICT=1` bash env-prefix to a portable
+  `--strict` flag (the env var is still honored for back-compat). New
+  `python -m controlzero` entrypoint. `kiro init` now runs a fail-LOUD
+  self-check that WARNS if the installed hook does not block a synthetic deny.
+
+## 1.11.0 -- 2026-06-17 (secret references: plaintext out of the agent context)
+
+### Added
+
+- **Secret references (`czsec://`).** `controlzero.secret_ref(name)` returns an
+  opaque, value-free reference you can hold in the model context, put in tool
+  arguments, and pass around freely. It performs no fetch and carries no value.
+- **Egress-time resolution.** `controlzero exec -- CMD` and
+  `controlzero.secrets.run(cmd, env=...)` resolve any `czsec://` references in
+  the argv / environment to plaintext ONLY at the moment a child process is
+  spawned, injecting the value into the child's argv / environment. The
+  plaintext never re-enters the parent (agent) process. Resolution reuses
+  `Client.get_secret`, so it is still policy-gated, HITL-aware, and audited; the
+  audit line records the reference + a non-reversible fingerprint, never the
+  value.
+- **`SecretStr` taint wrapper.** When a value must live briefly in-process, it is
+  wrapped so `repr` / `str` / `format` redact and iteration is refused; the only
+  way to get the bytes is `.reveal()`, called at the egress call site.
+
+### Changed
+
+- **`Client.get_secret` now warns** (once per process) that it returns plaintext
+  into the agent context, pointing at `secret_ref` + `controlzero exec`. Set
+  `CONTROLZERO_SECRETS_PROTECTED=1` to BLOCK plaintext reads entirely
+  (`get_secret` raises before any fetch). Default behaviour is unchanged
+  (warn-only); existing callers keep working.
+
 ## 1.10.1 -- 2026-06-17 (upgrade nudge)
 
 ### Added
@@ -580,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.10.1 → controlzero-1.11.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: controlzero
-Version: 1.10.1
+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
@@ -333,7 +333,7 @@ Basic flow:
 ```python
 from controlzero import Client
 
-cz = Client(api_key="cz_live_...")  # approvals require hosted mode
+cz = Client(api_key="cz_live_...")  # approvals run on any Postgres-backed deployment: hosted (SaaS), self-managed, or air-gapped
 
 decision = cz.guard("delete_file", {"path": "/etc/passwd"})
 if decision.decision == "deny" and getattr(decision, "hitl_eligible", False):

{controlzero-1.10.1 → controlzero-1.11.5}/README.md

@@ -279,7 +279,7 @@ Basic flow:
 ```python
 from controlzero import Client
 
-cz = Client(api_key="cz_live_...")  # approvals require hosted mode
+cz = Client(api_key="cz_live_...")  # approvals run on any Postgres-backed deployment: hosted (SaaS), self-managed, or air-gapped
 
 decision = cz.guard("delete_file", {"path": "/etc/passwd"})
 if decision.decision == "deny" and getattr(decision, "hitl_eligible", False):

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

@@ -39,12 +39,16 @@ from controlzero.hitl.grant_protocol import (
     REASON_HITL_RETRY_LOOP,
 )
 from controlzero.policy_loader import load_policy
+from controlzero.secrets import SecretRef, SecretStr, secret_ref
 
-__version__ = "1.10.1"
+__version__ = "1.11.5"
 
 __all__ = [
     "Client",
     "PendingApproval",
+    "SecretRef",
+    "SecretStr",
+    "secret_ref",
     "REASON_HITL_BACKEND_UNREACHABLE",
     "REASON_HITL_GRANT_APPROVED",
     "REASON_HITL_GRANT_CANCELED",

controlzero-1.11.5/controlzero/__main__.py

@@ -0,0 +1,12 @@
+"""Enable ``python -m controlzero`` to run the CLI.
+
+The Kiro CLI hook command pins the interpreter as
+``"<sys.executable>" -m controlzero hook-check --strict`` (#1265) so kiro-cli
+invokes the exact, importable controlzero the user installed, never a bare
+``controlzero`` that PATH might resolve to a broken or shadowing install.
+"""
+
+from controlzero.cli.main import cli
+
+if __name__ == "__main__":
+    cli()

{controlzero-1.10.1 → controlzero-1.11.5}/controlzero/_internal/bundle.py

@@ -464,9 +464,55 @@ def check_min_sdk_version(payload: dict, sdk_version: str) -> None:
 # --- Schema translation ----------------------------------------------------
 
 
-def translate_to_local_policy(payload: dict) -> dict:
+def _bundle_active_policy_count(payload: dict) -> Optional[int]:
+    """Return ``metadata.active_policy_count`` -- the backend's LIVE count of
+    active policy attachments at bundle-build time (#1303 part 3) -- or
+    ``None`` when the field is absent / malformed (an older backend that
+    predates the field).
+
+    This is the AUTHORITATIVE empty-vs-degraded discriminator. ``0`` means a
+    genuinely-empty project (observe, #1247); ``>0`` means policies ARE
+    attached, so an empty translated rule set is a degraded / stripped /
+    stale bundle and must fail closed. ``None`` makes the caller fall back to
+    the older ``policies: []`` shape heuristic. Never raises -- a malformed
+    value is treated as absent (fall back), never as a genuine 0.
+    """
+    metadata = payload.get("metadata")
+    if not isinstance(metadata, dict):
+        return None
+    count = metadata.get("active_policy_count")
+    # bool is an int subclass -- reject it so a stray `true` is not read as 1.
+    if isinstance(count, bool) or not isinstance(count, int):
+        return None
+    if count < 0:
+        return None
+    return count
+
+
+def translate_to_local_policy(
+    payload: dict,
+    *,
+    genuine_empty_is_authoritative: bool = True,
+) -> dict:
     """Translate a decrypted bundle payload to the local policy dict shape.
 
+    Args:
+        payload: the decrypted bundle payload dict.
+        genuine_empty_is_authoritative: whether a stamped genuinely-empty
+            project (``metadata.active_policy_count == 0``, or an explicit
+            empty ``policies: []`` on older backends) may be TRUSTED as the
+            #1247 observe posture. Defaults to ``True`` -- a freshly-pulled
+            bundle is authoritative. The hosted orchestrator passes ``False``
+            when serving a STALE CACHED bundle (#1303 residual A: the
+            stale-empty-cache replay window). A cached genuine-empty signal
+            cannot see time -- a count that was a legitimate 0 when the project
+            WAS empty still reads as genuinely empty after policies are later
+            attached -- so once the cached bundle ages past the freshness
+            bound the empty signal is no longer trustworthy. With this flag
+            ``False`` an empty translated rule set fails CLOSED (re-fetch /
+            deny) instead of replaying a stale observe-allow. A FRESH empty
+            bundle keeps the #1247 genuine-empty observe path intact.
+
     The bundle's `policies` list comes from the backend in the shape
     produced by :func:`BundleHandler.SDKPull` (Go: bundlePolicy). The
     local :class:`PolicyEvaluator` expects the input format from
@@ -556,7 +602,49 @@ def translate_to_local_policy(payload: dict) -> dict:
             if translated is not None:
                 flat.append(translated)
 
-    if not flat and not (isinstance(raw_policies, list) and len(raw_policies) == 0):
+    # #1303 part 3: the backend stamps metadata.active_policy_count -- the LIVE
+    # attachment count at bundle-build time. It is the AUTHORITATIVE
+    # discriminator for the DEGRADED direction: >0 means policies ARE attached,
+    # so an empty translated rule set is a degraded/stripped bundle -> fail
+    # closed (catches a stripped bundle that still ships an explicit
+    # `policies: []` while the project HAS attachments, which the shape check
+    # alone read as genuinely empty).
+    #
+    # For the GENUINELY-EMPTY direction the count is NECESSARY BUT NOT
+    # SUFFICIENT: a genuine empty project requires count == 0 AND the backend's
+    # explicit `policies: []`. The backend ALWAYS ships that explicit empty list
+    # for an empty project (bundle_handler.go builds Policies as
+    # `make([]bundlePolicy, 0)` and the JSON field has no `omitempty`), so
+    # requiring it costs a legitimate empty project nothing. A count == 0 paired
+    # with a MISSING or non-list `policies` key is a truncated / malformed /
+    # degraded bundle, NOT a genuine empty project -- trusting the count alone
+    # there would OBSERVE -> allow-all a degraded bundle (the rm-rf fail-open
+    # class, #1303), so it must fail closed below. Count ABSENT (older backend
+    # that predates the field) -> fall back to the explicit `policies: []` shape
+    # check.
+    active_policy_count = _bundle_active_policy_count(payload)
+    explicit_empty_policies = isinstance(raw_policies, list) and len(raw_policies) == 0
+    if active_policy_count is not None:
+        genuinely_empty = active_policy_count == 0 and explicit_empty_policies
+    else:
+        genuinely_empty = explicit_empty_policies
+
+    # #1303 residual A (stale-empty-cache replay): the genuine-empty signal
+    # (count==0 / explicit `policies: []`) cannot see TIME. A count that was a
+    # legitimate 0 from when the project WAS empty still reads as genuinely
+    # empty after policies are later attached, so replaying a STALE cached
+    # empty bundle would observe-allow a project that now HAS a policy. The
+    # hosted orchestrator knows the bundle age (header.created_at) and passes
+    # genuine_empty_is_authoritative=False once a cached bundle is past its
+    # freshness bound; in that case we DROP the genuine-empty trust so the
+    # zero-rule outcome falls through to the BUNDLE_MISSING fail-closed branch
+    # below (re-fetch / deny) instead of replaying a stale observe. A FRESH
+    # empty bundle (the default, and every newly-pulled bundle) keeps the
+    # #1247 genuine-empty observe path.
+    if not genuine_empty_is_authoritative:
+        genuinely_empty = False
+
+    if not flat and not genuinely_empty:
         # #1303 FAIL-OPEN FIX (the empty-vs-degraded boundary). We have zero
         # translatable rules, but this is NOT a genuinely-empty project: the
         # payload carried attached policies that produced no enforceable rules,
@@ -568,10 +656,15 @@ def translate_to_local_policy(payload: dict) -> dict:
         # genuinely-empty observe path (#1247) below is reached ONLY when the
         # backend shipped an explicit empty list (`policies: []`).
         #
-        # NOTE: a stale CACHED bundle that legitimately held `policies: []` from
-        # when the project WAS empty is NOT caught here (it looks genuinely
-        # empty); that residual replay window is closed by bundle provenance +
-        # freshness (#1303 part 3 / backend active_policy_count).
+        # NOTE: with active_policy_count (part 3) a stripped bundle that ships
+        # `policies: []` while the project HAS attachments now fails closed
+        # above (count > 0). The remaining purely-time-based residual -- a
+        # stale CACHED bundle whose stamped count was a legitimate 0 from when
+        # the project WAS empty -- is now ALSO routed here: the hosted
+        # orchestrator drops genuine_empty_is_authoritative once the cached
+        # bundle ages past its freshness bound (#1303 residual A), which clears
+        # genuinely_empty above so this fail-closed branch is taken instead of
+        # the stale observe replay.
         # Reuse the registered BUNDLE_MISSING reason_code / synthetic id (both
         # already in VALID_REASON_CODES / VALID_SYNTHETIC_POLICY_IDS) so no new
         # error-catalog entry is introduced; the human-readable reason names the

{controlzero-1.10.1 → 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/exec_cmd.py

@@ -0,0 +1,90 @@
+"""``controlzero exec`` -- run a command with ``czsec://`` references resolved
+to plaintext at the spawn boundary, injected into the child ONLY.
+
+Usage::
+
+    controlzero exec --env OPENAI_API_KEY=czsec://prod/openai-key -- \
+        python my_agent.py
+
+    controlzero exec -- curl -H "Authorization: Bearer czsec://prod/token" https://api
+
+Any ``czsec://`` reference in ``--env`` values or in the command's arguments is
+resolved (policy-gated + audited, via ``Client.get_secret``) and placed into the
+child process's environment / argv. The reference -- not the secret -- is all
+that ever lived in the agent / model context; the plaintext appears only in the
+child. This process never prints the resolved value.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+
+import click
+
+from controlzero.secrets.reference import find_refs
+from controlzero.secrets.resolver import resolve_env, resolve_refs
+
+
+@click.command(
+    "exec",
+    context_settings={"ignore_unknown_options": True, "allow_interspersed_args": False},
+)
+@click.option(
+    "--env",
+    "env_overrides",
+    multiple=True,
+    metavar="NAME=VALUE",
+    help="Set a child env var; VALUE may be a czsec:// reference. Repeatable.",
+)
+@click.argument("command", nargs=-1, type=click.UNPROCESSED)
+def exec_cmd(env_overrides, command) -> None:
+    """Resolve czsec:// references at spawn and exec COMMAND with them."""
+    if not command:
+        raise click.UsageError("no command given (usage: controlzero exec -- CMD ARGS)")
+
+    # Parse --env NAME=VALUE overrides.
+    overrides = {}
+    for item in env_overrides:
+        if "=" not in item:
+            raise click.UsageError(f"--env expects NAME=VALUE, got {item!r}")
+        name, value = item.split("=", 1)
+        if not name:
+            raise click.UsageError(f"--env name is empty in {item!r}")
+        overrides[name] = value
+
+    # Build a Client only if there is actually something to resolve -- a plain
+    # exec with no references should not require an API key.
+    has_refs = any(find_refs(v) for v in overrides.values()) or any(
+        find_refs(tok) for tok in command
+    )
+    client = None
+    if has_refs:
+        from controlzero import Client
+
+        client = Client()
+        if getattr(client, "_api_key", None) is None:
+            raise click.ClickException(
+                "resolving czsec:// references requires CONTROLZERO_API_KEY "
+                "(the backend owns the secret store)"
+            )
+
+    # Resolve at the boundary. These are plaintext, destined for the child.
+    try:
+        resolved_argv = list(resolve_refs(command, client=client))
+        child_env = dict(os.environ)
+        if overrides:
+            child_env.update(resolve_env(overrides, client=client))
+    except Exception as exc:  # surface a clean error, never a half-resolved spawn
+        raise click.ClickException(f"secret resolution failed: {exc}") from exc
+
+    # execvpe replaces this interpreter, so no resolved plaintext lingers in a
+    # Python frame after the child starts.
+    try:
+        os.execvpe(resolved_argv[0], resolved_argv, child_env)
+    except FileNotFoundError:
+        raise click.ClickException(f"command not found: {resolved_argv[0]!r}")
+    except OSError as exc:
+        raise click.ClickException(f"failed to exec {resolved_argv[0]!r}: {exc}")
+    # Unreachable on success (process is replaced).
+    sys.exit(127)

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.10.1 → 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",