controlzero 1.9.9__tar.gz → 1.11.4__tar.gz

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

@@ -1,5 +1,169 @@
 # Changelog
 
+## 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
+
+- **Soft upgrade nudge.** The backend now stamps
+  `metadata.recommended_sdk_version` on every bundle; when the running SDK is
+  below it, the SDK emits ONE non-fatal warning per process pointing at
+  `controlzero update`. It never raises and never changes enforcement -- it
+  just stops a customer stuck on a version that predates a fix (e.g. the
+  no-policy->observe posture and self-explaining deny, #1247/#1303) from
+  silently sitting on an already-fixed bug. Bundles without the field (older
+  backends) are a no-op.
+
+## 1.10.0 -- 2026-06-17 (self-update command)
+
+### Added
+
+- **`controlzero update`** -- self-update the SDK to the latest PyPI release.
+  Enforcement and audit fixes ship in the SDK, so a customer on an old version
+  keeps hitting already-fixed bugs (e.g. the no-policy->observe posture and
+  self-explaining deny, #1247/#1303) until they upgrade. This is the
+  one-command upgrade path: `controlzero update` checks PyPI, shows
+  `current -> latest`, and runs the matching upgrade (pip / pipx / uv,
+  detected from how the SDK was installed, always echoing the exact command and
+  falling back to a printed manual command on failure). `controlzero update
+  --check` reports only (exit 10 when an update is available) for scripts and
+  the upgrade nudge; `--yes` skips the prompt. Degrades gracefully and never
+  tracebacks when PyPI is unreachable.
+
 ## 1.9.9 -- 2026-06-17 (Antigravity tool vocab, JSON+YAML config parity, spool reliability)
 
 Follow-ups to the gh#1303 fail-open work plus two correctness fixes.

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: controlzero
-Version: 1.9.9
+Version: 1.11.4
 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.9.9 → controlzero-1.11.4}/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.9.9 → controlzero-1.11.4}/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.9.9"
+__version__ = "1.11.4"
 
 __all__ = [
     "Client",
     "PendingApproval",
+    "SecretRef",
+    "SecretStr",
+    "secret_ref",
     "REASON_HITL_BACKEND_UNREACHABLE",
     "REASON_HITL_GRANT_APPROVED",
     "REASON_HITL_GRANT_CANCELED",

controlzero-1.11.4/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.9.9 → controlzero-1.11.4}/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.11.4/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)