controlzero 1.5.6__tar.gz → 1.5.8__tar.gz

{controlzero-1.5.6 → controlzero-1.5.8}/.gitignore

@@ -239,3 +239,7 @@ secrets/*.dec
 
 # Local documentation, patent assets, and legal research (sensitive, never commit)
 doc_local/
+
+# Go build/module caches (generated by `go build`, `go test`, etc.)
+**/.gocache/
+**/.gomodcache/

{controlzero-1.5.6 → controlzero-1.5.8}/CHANGELOG.md

@@ -1,5 +1,62 @@
 # Changelog
 
+## v1.5.8 -- 2026-05-16 (HITL-5a, gh#538)
+
+Additive minor preparing the SDK for the Human-in-the-Loop approval
+workflow that ships in 1.6.0 (HITL-6a, gh#542). Pure additive: no
+behavior change on existing policies; no new public API surface.
+
+### Added
+
+- **`escalate_on_deny: bool` rule key** is acknowledged. Customers may
+  pre-tag deny rules for HITL eligibility; 1.5.8 persists the field
+  on `PolicyRule` (default `False`). The actual `request_approval()`
+  flow ships in 1.6.0; 1.5.8 ensures a customer pre-tagging rules
+  doesn't crash an old client.
+- **Typo guardrail** on rule keys. Unknown keys within Levenshtein-1
+  of a known key (`escalate_on_dney` -> `escalate_on_deny`) now print
+  a one-line "did you mean?" warning to stderr. Unknown keys far from
+  any known key remain silently accepted (additive contract).
+- **9 new HITL reason codes** registered in `VALID_REASON_CODES`:
+  `HITL_SDK_TIMEOUT`, `HITL_SLA_EXPIRED`, `HITL_BACKEND_UNREACHABLE`,
+  `HITL_POLICY_VERSION_CONFLICT`, `HITL_NO_APPROVER_AVAILABLE`,
+  `HITL_IDENTITY_NOT_IN_ORG`, `HITL_IDENTITY_REQUIRED`,
+  `HITL_IDENTITY_CLAIM_REJECTED`, `HITL_ARGS_HASH_MISMATCH`. 1.5.8
+  itself never emits these; registration ensures a 1.6.0+ client's
+  audit rows pass 1.5.8 ingest validation during a mixed-version
+  rollout.
+
+### Unchanged
+
+- 11-line Hello World still works.
+- All 156 existing SDK hook tests pass.
+- No new methods on `Client` or `PolicyDecision`.
+- Existing 1.5.7 policies parse identically (escalate_on_deny defaults
+  to `False`; legacy keys still in `_KNOWN_RULE_KEYS`).
+
+## v1.5.7 -- 2026-05-16 (PRIVACY)
+
+### Fixed
+
+- **Customer-context comments in the published wheel.** Codex +
+  Gemini outside-voice review surfaced several customer-context
+  strings + private monorepo path references that v1.5.6 missed:
+  - `controlzero/hosted_policy.py` referenced a customer-specific
+    possessive when describing the T104 cache-GC scenario. Rewritten
+    in neutral phrasing that preserves the technical context.
+  - `controlzero/enrollment.py` documented the wire-format contract
+    via a private monorepo path. Replaced with a pointer to the
+    public docs site.
+  - `controlzero/cli/hosts/base.py` and
+    `controlzero/cli/hosts/unknown.py` referenced an internal
+    backend filename in inline comments. Replaced with a generic
+    description of the constraint.
+  - Tests `test_t104_cache_gc.py` and `test_t103_precedence.py`
+    carried a geographic identifier and a customer-derived test
+    name (NOT in the published wheel since tests are excluded, but
+    scrubbed for consistency).
+- **No behavior change.** Comments + docstrings only.
+
 ## v1.5.6 -- 2026-05-15 (PRIVACY)
 
 ### Fixed

{controlzero-1.5.6 → controlzero-1.5.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: controlzero
-Version: 1.5.6
+Version: 1.5.8
 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.5.6 → controlzero-1.5.8}/controlzero/__init__.py

@@ -28,7 +28,7 @@ from controlzero.errors import (
 )
 from controlzero.policy_loader import load_policy
 
-__version__ = "1.5.6"
+__version__ = "1.5.8"
 
 __all__ = [
     "Client",

{controlzero-1.5.6 → controlzero-1.5.8}/controlzero/_internal/enforcer.py

@@ -66,6 +66,20 @@ REASON_CODE_DLP_BLOCKED = "DLP_BLOCKED"
 # decision is "audit" and policy_id is "<lifecycle>".
 REASON_CODE_LOCAL_OVERRIDE_ACTIVE = "LOCAL_OVERRIDE_ACTIVE"
 
+# HITL approval-flow reason codes (HITL-5a, gh#538). The actual
+# request-approval flow ships in 1.6.0 (HITL-6a, gh#542); 1.5.8
+# registers the codes so audit rows from a 1.6.0+ client can be
+# accepted by a 1.5.8 ingest path without rejection.
+REASON_CODE_HITL_SDK_TIMEOUT = "HITL_SDK_TIMEOUT"
+REASON_CODE_HITL_SLA_EXPIRED = "HITL_SLA_EXPIRED"
+REASON_CODE_HITL_BACKEND_UNREACHABLE = "HITL_BACKEND_UNREACHABLE"
+REASON_CODE_HITL_POLICY_VERSION_CONFLICT = "HITL_POLICY_VERSION_CONFLICT"
+REASON_CODE_HITL_NO_APPROVER_AVAILABLE = "HITL_NO_APPROVER_AVAILABLE"
+REASON_CODE_HITL_IDENTITY_NOT_IN_ORG = "HITL_IDENTITY_NOT_IN_ORG"
+REASON_CODE_HITL_IDENTITY_REQUIRED = "HITL_IDENTITY_REQUIRED"
+REASON_CODE_HITL_IDENTITY_CLAIM_REJECTED = "HITL_IDENTITY_CLAIM_REJECTED"
+REASON_CODE_HITL_ARGS_HASH_MISMATCH = "HITL_ARGS_HASH_MISMATCH"
+
 VALID_REASON_CODES = frozenset({
     REASON_CODE_RULE_MATCH,
     REASON_CODE_NO_RULE_MATCH,
@@ -76,6 +90,15 @@ VALID_REASON_CODES = frozenset({
     REASON_CODE_NETWORK_ERROR,
     REASON_CODE_DLP_BLOCKED,
     REASON_CODE_LOCAL_OVERRIDE_ACTIVE,
+    REASON_CODE_HITL_SDK_TIMEOUT,
+    REASON_CODE_HITL_SLA_EXPIRED,
+    REASON_CODE_HITL_BACKEND_UNREACHABLE,
+    REASON_CODE_HITL_POLICY_VERSION_CONFLICT,
+    REASON_CODE_HITL_NO_APPROVER_AVAILABLE,
+    REASON_CODE_HITL_IDENTITY_NOT_IN_ORG,
+    REASON_CODE_HITL_IDENTITY_REQUIRED,
+    REASON_CODE_HITL_IDENTITY_CLAIM_REJECTED,
+    REASON_CODE_HITL_ARGS_HASH_MISMATCH,
 })
 
 # Synthetic policy_id sentinels (T79 / the deny-deny postmortem,

{controlzero-1.5.6 → controlzero-1.5.8}/controlzero/_internal/types.py

@@ -23,3 +23,9 @@ class PolicyRule(BaseModel):
     # "NO_ACTIVE_POLICIES"). User-authored rules leave this empty and
     # the evaluator does not promote them to a code.
     reason_code: str = ""
+    # HITL escalation tag (HITL-5a, gh#538): when True and the rule's
+    # effect is `deny`, the SDK marks the resulting PolicyDecision as
+    # `hitl_eligible=True`. The actual approval-request flow ships in
+    # 1.6.0 (HITL-6a, gh#542); 1.5.8 just acknowledges the field so a
+    # customer pre-tagging rules for HITL doesn't crash an old client.
+    escalate_on_deny: bool = False

{controlzero-1.5.6 → controlzero-1.5.8}/controlzero/cli/hosts/__init__.py

@@ -36,9 +36,9 @@ A ``HostAdapter`` owns three responsibilities for one host runtime:
    (Windows Claude Code is the canonical case).
 2. ``render(decision)`` -- translate the canonical ``CZDecision``
    into the JSON shape this host's hook validator accepts.
-3. ``canonical_source`` -- the backend ``audit.NormalizeSource``
-   alias (``claude_code`` / ``gemini_cli`` / ``codex_cli`` / etc.)
-   so the audit row's SOURCE column renders correctly.
+3. ``canonical_source`` -- the backend-side source alias
+   (``claude_code`` / ``gemini_cli`` / ``codex_cli`` / etc.) so the
+   audit row's SOURCE column renders correctly.
 
 Adding a new host (Cursor, Windsurf, OpenClaw, Antigravity, the
 next agent that ships) is a single file in this package: subclass

{controlzero-1.5.6 → controlzero-1.5.8}/controlzero/cli/hosts/base.py

@@ -84,7 +84,7 @@ class HostAdapter:
     A subclass needs three things:
 
     * ``name`` -- short identifier used in logs ("claude_code").
-    * ``canonical_source`` -- backend ``audit.NormalizeSource`` alias
+    * ``canonical_source`` -- backend-side source alias
       ("claude_code" / "gemini_cli" / "codex_cli" / "unknown").
       This is what the audit row's SOURCE column resolves to so
       the dashboard renders the right label.
@@ -109,10 +109,9 @@ class HostAdapter:
     #: Short identifier used in logs / metrics.
     name: str = "base"
 
-    #: Backend ``audit.NormalizeSource`` alias. Must be one of the
-    #: canonical values in ``backend/internal/audit/source.go`` so
-    #: the dashboard renders the right label. Default is
-    #: ``"unknown"`` -- subclasses MUST override.
+    #: Backend audit source alias. Must be one of the canonical
+    #: values the dashboard accepts so the right label renders.
+    #: Default is ``"unknown"`` -- subclasses MUST override.
     canonical_source: str = "unknown"
 
     # -- detection --------------------------------------------------

{controlzero-1.5.6 → controlzero-1.5.8}/controlzero/cli/hosts/unknown.py

@@ -26,9 +26,8 @@ from controlzero.cli.hosts.base import CZDecision, HostAdapter
 
 class UnknownHostAdapter(HostAdapter):
     name = "unknown"
-    # Canonical source value mapped in
-    # ``backend/internal/audit/source.go`` -- renders as ``--`` on
-    # the dashboard. Better than mislabelling.
+    # Canonical source value the dashboard accepts -- renders as
+    # ``--`` on the dashboard. Better than mislabelling.
     canonical_source = "unknown"
 
     def claim(self, payload: dict, env: Mapping[str, str]) -> bool:

{controlzero-1.5.6 → controlzero-1.5.8}/controlzero/enrollment.py

@@ -19,10 +19,9 @@ private key lives in ``~/.controlzero/machine.key`` with mode 0600.
 A follow-up will plug in Keychain/DPAPI/secret-service per platform;
 the file-on-disk fallback stays as the bottom of the chain.
 
-Wire-format: see ``apps/control-zero-platform/backend/internal/api/
-middleware/machine_auth.go`` for the canonical signed string and
-header definitions. This module is the source of truth on the
-client side.
+Wire-format contract: see the public docs and OpenAPI spec for the
+machine-auth endpoint at https://docs.controlzero.ai. This module is
+the source of truth on the client side.
 """
 
 from __future__ import annotations

{controlzero-1.5.6 → controlzero-1.5.8}/controlzero/hosted_policy.py

@@ -138,8 +138,8 @@ def gc_stale_cache(active_api_key: str) -> int:
     T104 (2026-05-12, customer report): on key rotation the old key's cache files
     (``bootstrap-<oldscope>.json``, ``bundle-<oldscope>.bin``,
     ``bundle-<oldscope>.meta``) accumulated forever next to the new key's
-    files. John's machine carried a 25-day-old ``bundle-cz_live_566b.bin``
-    next to a fresh ``bootstrap-cz_live_1af8.json`` because the rotated
+    files. A customer reported a 25-day-old ``bundle-<oldscope>.bin`` left
+    next to a fresh ``bootstrap-<newscope>.json`` because the rotated
     key never invalidated the previous cache. We clean up on every fresh
     bootstrap so the cache directory always reflects exactly one active
     key per machine.

{controlzero-1.5.6 → controlzero-1.5.8}/controlzero/policy_loader.py

@@ -44,6 +44,63 @@ PolicyInput = Union[dict, str, Path]
 
 VALID_TAMPER_BEHAVIORS = {"warn", "deny", "deny-all", "quarantine"}
 
+# Known rule-level keys. Used by the typo guardrail (HITL-5a, gh#538)
+# to surface "did you mean?" warnings on near-misses. Unknown keys are
+# still silently accepted (additive contract; never break existing YAML)
+# but a Levenshtein-1 match on a known key fires a `_KNOWN_RULE_KEYS`
+# warning in stderr so the customer can self-correct.
+_KNOWN_RULE_KEYS = frozenset({
+    "id",
+    "name",
+    "deny",
+    "allow",
+    "effect",
+    "action",
+    "actions",
+    "resource",
+    "resources",
+    "when",
+    "conditions",
+    "reason",
+    "reason_code",
+    "escalate_on_deny",  # HITL tag (additive in 1.5.8; behavior in 1.6.0)
+})
+
+
+def _levenshtein_le_1(a: str, b: str) -> bool:
+    """Return True iff edit distance between `a` and `b` is exactly 0 or 1.
+
+    Used by the typo guardrail to suggest fixes for unknown rule keys
+    that are one keystroke away from a known one (e.g. `escalate_on_dnen`
+    -> `escalate_on_deny`). Pure-Python; no external dependency.
+    """
+    if a == b:
+        return True
+    la, lb = len(a), len(b)
+    if abs(la - lb) > 1:
+        return False
+    if la > lb:
+        a, b = b, a
+        la, lb = lb, la
+    # la <= lb; check for one substitution (la == lb) or one insertion
+    i = j = diffs = 0
+    while i < la and j < lb:
+        if a[i] != b[j]:
+            diffs += 1
+            if diffs > 1:
+                return False
+            if la == lb:
+                i += 1
+                j += 1
+            else:
+                j += 1  # insertion in b
+        else:
+            i += 1
+            j += 1
+    if j < lb:
+        diffs += lb - j
+    return diffs <= 1
+
 
 @dataclass
 class PolicySettings:
@@ -258,6 +315,21 @@ def _validate_and_translate(data: dict, source_label: str) -> ParsedPolicy:
             errors.append(f"rules[{i}]: must be a mapping, got {type(raw).__name__}")
             continue
 
+        # Typo guardrail (HITL-5a, gh#538): warn on unknown rule keys that
+        # are within Levenshtein-1 of a known key. Unknown keys are still
+        # silently accepted (additive contract); the warning is stderr-only.
+        for k in raw.keys():
+            if k in _KNOWN_RULE_KEYS:
+                continue
+            for known in _KNOWN_RULE_KEYS:
+                if _levenshtein_le_1(k, known):
+                    import sys as _sys
+                    _sys.stderr.write(
+                        f"controlzero: rules[{i}] unknown key {k!r}; "
+                        f"did you mean {known!r}?\n"
+                    )
+                    break
+
         # Determine effect from the keys present
         has_deny = "deny" in raw
         has_allow = "allow" in raw
@@ -339,6 +411,12 @@ def _validate_and_translate(data: dict, source_label: str) -> ParsedPolicy:
                 # emitted by bundle.translate_to_local_policy) set
                 # this today; user-authored rules leave it empty.
                 reason_code=str(raw.get("reason_code", "")),
+                # HITL escalation tag (HITL-5a, gh#538). Coerce truthy
+                # values; non-bool / missing => False. The actual
+                # request-approval flow ships in 1.6.0 (HITL-6a); 1.5.8
+                # just persists the field so old SDKs don't crash on
+                # rules that pre-tag for HITL.
+                escalate_on_deny=bool(raw.get("escalate_on_deny", False)),
             )
         )
 

{controlzero-1.5.6 → controlzero-1.5.8}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "controlzero"
-version = "1.5.6"
+version = "1.5.8"
 description = "AI agent governance: policies, audit, and observability for tool calls. Works locally with no signup."
 readme = "README.md"
 license = {text = "Apache-2.0"}

{controlzero-1.5.6 → controlzero-1.5.8}/tests/test_api_key_mask.py

@@ -19,12 +19,12 @@ from controlzero.client import _mask_api_key
 
 
 def test_mask_live_key_emits_only_public_prefix():
-    masked = _mask_api_key("cz_live_7ebef6b600015e3eaeda9149bf6d9c29a")
+    masked = _mask_api_key("cz_live_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
     assert masked == "cz_live_***"
 
 
 def test_mask_test_key_emits_only_public_prefix():
-    masked = _mask_api_key("cz_test_abcdef0123456789abcdef0123456789")
+    masked = _mask_api_key("cz_test_bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb")
     assert masked == "cz_test_***"
 
 
@@ -42,10 +42,10 @@ def test_mask_empty_string_returns_triple_star():
 
 
 def test_mask_never_leaks_secret_bytes_brute_force():
-    # The secret portion of a real production key (anonymised:
-    # do not use this value as-is, the customer rotated it after the
+    # Obviously-synthetic placeholder fixture. The 4-char window
+    # scan downstream remains meaningful: the masked output must not
     # 1.5.0 -> 1.5.1 incident on 2026-05-12).
-    secret_tail = "7ebef6b600015e3eaeda9149bf6d9c29a3a2a7a3075209112afde20888280de0"
+    secret_tail = "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
     for prefix in ("cz_live_", "cz_test_"):
         key = prefix + secret_tail
         masked = _mask_api_key(key)

{controlzero-1.5.6 → controlzero-1.5.8}/tests/test_env_dump_438.py

@@ -66,7 +66,7 @@ def test_env_dump_outputs_valid_json(monkeypatch):
 def test_env_dump_redacts_api_key_by_default(monkeypatch):
     monkeypatch.setenv(
         "CONTROLZERO_API_KEY",
-        "cz_live_7ebef6b600015e3eaeda9149bf6d9c29a3a2a7a3075209112afde20888280de0",
+        "cz_live_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
     )
     result = _invoke([])
     assert result.exit_code == 0
@@ -74,7 +74,7 @@ def test_env_dump_redacts_api_key_by_default(monkeypatch):
     masked = data["env"]["CONTROLZERO_API_KEY"]
     assert masked == "cz_live_***"
     # Defensive: the secret bytes MUST NOT appear anywhere in the dump.
-    secret_tail = "7ebef6b600015e3eaeda9149bf6d9c29a"
+    secret_tail = "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
     assert secret_tail not in result.output
 
 

controlzero-1.5.8/tests/test_hitl_reason_codes.py

@@ -0,0 +1,72 @@
+"""Tests for HITL-5a (gh#538): new HITL reason codes in 1.5.8.
+
+The 9 new codes are registered in VALID_REASON_CODES so a 1.6.0+ client
+emitting them via audit doesn't get rejected by a 1.5.8 ingest path.
+1.5.8 itself never EMITS these codes (no HITL flow yet); it just
+recognizes them.
+"""
+from __future__ import annotations
+
+from controlzero._internal.enforcer import (
+    REASON_CODE_DLP_BLOCKED,  # legacy sanity check
+    REASON_CODE_HITL_ARGS_HASH_MISMATCH,
+    REASON_CODE_HITL_BACKEND_UNREACHABLE,
+    REASON_CODE_HITL_IDENTITY_CLAIM_REJECTED,
+    REASON_CODE_HITL_IDENTITY_NOT_IN_ORG,
+    REASON_CODE_HITL_IDENTITY_REQUIRED,
+    REASON_CODE_HITL_NO_APPROVER_AVAILABLE,
+    REASON_CODE_HITL_POLICY_VERSION_CONFLICT,
+    REASON_CODE_HITL_SDK_TIMEOUT,
+    REASON_CODE_HITL_SLA_EXPIRED,
+    VALID_REASON_CODES,
+)
+
+
+HITL_CODES = (
+    REASON_CODE_HITL_SDK_TIMEOUT,
+    REASON_CODE_HITL_SLA_EXPIRED,
+    REASON_CODE_HITL_BACKEND_UNREACHABLE,
+    REASON_CODE_HITL_POLICY_VERSION_CONFLICT,
+    REASON_CODE_HITL_NO_APPROVER_AVAILABLE,
+    REASON_CODE_HITL_IDENTITY_NOT_IN_ORG,
+    REASON_CODE_HITL_IDENTITY_REQUIRED,
+    REASON_CODE_HITL_IDENTITY_CLAIM_REJECTED,
+    REASON_CODE_HITL_ARGS_HASH_MISMATCH,
+)
+
+
+def test_all_9_hitl_codes_exported():
+    # Module-level constants exist + are non-empty strings.
+    for c in HITL_CODES:
+        assert isinstance(c, str) and c.startswith("HITL_")
+
+
+def test_all_9_hitl_codes_in_valid_set():
+    for c in HITL_CODES:
+        assert c in VALID_REASON_CODES, f"{c!r} missing from VALID_REASON_CODES"
+
+
+def test_legacy_codes_still_in_valid_set():
+    # No regression: existing 1.5.7 codes remain registered.
+    assert REASON_CODE_DLP_BLOCKED in VALID_REASON_CODES
+
+
+def test_hitl_codes_match_design_doc_exactly():
+    # Spelling guard: any rename here breaks cross-SDK parity with the
+    # design doc + Node + Go. Lock them in.
+    assert REASON_CODE_HITL_SDK_TIMEOUT == "HITL_SDK_TIMEOUT"
+    assert REASON_CODE_HITL_SLA_EXPIRED == "HITL_SLA_EXPIRED"
+    assert REASON_CODE_HITL_BACKEND_UNREACHABLE == "HITL_BACKEND_UNREACHABLE"
+    assert REASON_CODE_HITL_POLICY_VERSION_CONFLICT == "HITL_POLICY_VERSION_CONFLICT"
+    assert REASON_CODE_HITL_NO_APPROVER_AVAILABLE == "HITL_NO_APPROVER_AVAILABLE"
+    assert REASON_CODE_HITL_IDENTITY_NOT_IN_ORG == "HITL_IDENTITY_NOT_IN_ORG"
+    assert REASON_CODE_HITL_IDENTITY_REQUIRED == "HITL_IDENTITY_REQUIRED"
+    assert REASON_CODE_HITL_IDENTITY_CLAIM_REJECTED == "HITL_IDENTITY_CLAIM_REJECTED"
+    assert REASON_CODE_HITL_ARGS_HASH_MISMATCH == "HITL_ARGS_HASH_MISMATCH"
+
+
+def test_valid_set_size_grew_by_exactly_9():
+    # 1.5.7 had 9 codes; 1.5.8 adds 9 -> 18. If anyone adds another
+    # code without updating this test, it fires so the addition is
+    # intentional + reviewed.
+    assert len(VALID_REASON_CODES) == 9 + 9