controlzero 1.5.8__tar.gz → 1.6.0__tar.gz

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

@@ -1,6 +1,9 @@
 # Worktrees
 .worktrees/
 
+# Preflight state (drift-confirmed marker etc.). Local-only, never committed.
+.preflight-state/
+
 # Transient QA / design captures at repo root.
 # Long-term reference screenshots live under docs-site/static/ or in Obsidian.
 /*.png

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

@@ -1,5 +1,75 @@
 # Changelog
 
+## v1.6.0 -- 2026-05-17 (HITL-6a, gh#542)
+
+First minor that turns the Human-in-the-Loop approval workflow on. 1.5.8
+prepared the field (escalate_on_deny acknowledged, HITL reason codes
+registered, validator additive); 1.6.0 ships the surface area: 11 exception
+codes, a PendingApproval dataclass with sync + async wait, an in-process
+mock backend, the request_approval HTTP path, the CLI test flag, and the
+secret-value-leak guard that gates every outbound HITL payload.
+
+### Added
+
+- **11 HITL exception classes** (E1701-E1711) -- `HITLTimeoutError`,
+  `HITLBackendUnreachableError`, `HITLPolicyVersionConflictError`,
+  `HITLNotConfiguredError`, `HITLNoApproverAvailable`,
+  `HITLIdentityNotInOrg`, `HITLIdentityRequired`,
+  `HITLIdentityClaimRejected`, `SecretValueLeakInPayload`,
+  `SecretApprovalRequired`, `SecretNotFound`. Inheritance is chosen so
+  existing `except PolicyDeniedError` blocks treat HITL timeouts and
+  approver-pool failures identically to a static deny. (#571)
+- **`controlzero.hitl` subpackage** with the `PendingApproval` dataclass
+  and `Status` enum. `PendingApproval` carries `request_id`,
+  `idempotency_key`, `status`, `created_at`, `expires_at`,
+  `decision_kind`, and `decided_by`; exposes `is_terminal()` and
+  `remaining_s()` for non-blocking checks. (#574)
+- **`MockApprovalBackend`** -- in-process fake of the two HITL endpoints
+  (`POST /api/approval-requests`, `GET /api/approval-requests/{id}`)
+  with five deterministic modes: `approve_after_2s`,
+  `approve_timed_after_2s`, `approve_forever_after_2s`,
+  `deny_after_2s`, and `timeout`. Thread-safe; one instance can serve
+  many concurrent pollers. (#572)
+- **Secret-value-leak guard** -- `is_likely_secret_value`,
+  `scan_payload_for_secret_leak`, and `raise_on_leak` reject any
+  outbound payload whose redacted-args dict still contains a
+  secret-shaped string. The check runs inside `request_approval()`
+  before the HTTP send. (#573)
+- **`controlzero test --hitl approve|deny|timeout`** CLI flag drives the
+  mock backend end-to-end from a shell, so customers can exercise HITL
+  paths without setting up a real approver. (#575)
+- **`PendingApproval.wait()` and `wait_async()`** -- polling loop with
+  jittered exponential backoff, capped at the dataclass's `expires_at`.
+  Honors a user-supplied `poll_fn` for tests; defaults to the SDK's
+  HTTP poller for production. Raises `HITLTimeoutError` on SLA expiry
+  and `HITLBackendUnreachableError` on network failure. (#576)
+- **`Client.request_approval(decision, message=..., timeout_s=...)`** --
+  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
+  the matching SDK exceptions. (#577)
+
+### Conformance
+
+The 49 HITL/secret vectors added to `tests/parity/decisions.json` in
+HITL-3 (gh#536) target this release: `min_sdk_version: "1.6.0"` and
+`requires_backend: true` flags gate them. A Python conformance runner
+that executes those vectors against the SDK is planned for phase 3 of
+issue #409; until that lands, this release is validated against the
+HITL-6a unit tests (155 new test cases across the seven slices) plus
+the pre-existing 156 SDK hook tests.
+
+### Unchanged
+
+- 11-line Hello World still works.
+- No breaking changes to existing public API: `Client.guard()`,
+  `Client.refresh()`, `load_policy()` all behave identically.
+- `escalate_on_deny` still defaults to `False`; policies without HITL
+  tags continue to run with zero HITL overhead.
+- Local-mode users pay no HITL cost: imports are lazy, no HTTP client
+  is constructed unless `request_approval()` is called.
+
 ## v1.5.8 -- 2026-05-16 (HITL-5a, gh#538)
 
 Additive minor preparing the SDK for the Human-in-the-Loop approval

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: controlzero
-Version: 1.5.8
+Version: 1.6.0
 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
@@ -28,6 +28,7 @@ Requires-Dist: httpx>=0.25.0
 Requires-Dist: loguru>=0.7.0
 Requires-Dist: pydantic>=2.0.0
 Requires-Dist: pyyaml>=6.0
+Requires-Dist: rfc8785<0.2,>=0.1.4
 Requires-Dist: rich>=13.0.0
 Requires-Dist: zstandard>=0.22.0
 Provides-Extra: anthropic
@@ -299,6 +300,154 @@ from controlzero import Client
 cz = Client()  # picks up the API key from env, audit ships remote
 ```
 
+## Human-in-the-Loop approvals
+
+Approvals let a policy block a tool call until a human approver decides allow or deny.
+An agent calls `client.request_approval(decision, ...)` whenever `guard()` returns a
+deny that is tagged `escalate_on_deny: true`, then waits on the returned
+`PendingApproval` for the human to respond.
+
+Basic flow:
+
+```python
+from controlzero import Client
+
+cz = Client(api_key="cz_live_...")  # approvals require hosted mode
+
+decision = cz.guard("delete_file", {"path": "/etc/passwd"})
+if decision.decision == "deny" and getattr(decision, "hitl_eligible", False):
+    pending = cz.request_approval(
+        decision,
+        message="agent wants to delete /etc/passwd; please confirm",
+        timeout_s=300,
+    )
+
+    # PendingApproval.wait() requires you to inject a `poll_fn`,
+    # a callable that returns the latest backend snapshot of the
+    # approval request. In 1.6.0 the SDK does NOT ship a built-in
+    # HTTP poller; you wire one yourself (or use the helper that
+    # ships with get_secret. See "Secret reads with approvals" below).
+    import httpx
+    api_url = "https://api.controlzero.ai"  # or your self-managed host
+
+    def poll_fn(request_id: str) -> dict:
+        resp = httpx.get(
+            f"{api_url}/api/approval-requests/{request_id}",
+            headers={"Authorization": f"Bearer {api_key}"},
+            timeout=10,
+        )
+        resp.raise_for_status()
+        return resp.json()
+
+    # Block until the human approves, denies, or the SLA expires.
+    resolved = pending.wait(poll_fn)
+    if resolved.status == "approved":
+        # proceed with the gated action
+        ...
+    else:
+        # denied or timed_out, abort the tool call
+        ...
+```
+
+`wait()` blocks the calling thread. For async code, use `wait_async()`,
+same contract, but the poll callable can be `async def` or a sync
+function (sync calls are dispatched to a thread executor so the event
+loop never blocks):
+
+```python
+async def async_poll(request_id: str) -> dict:
+    async with httpx.AsyncClient() as client:
+        resp = await client.get(
+            f"{api_url}/api/approval-requests/{request_id}",
+            headers={"Authorization": f"Bearer {api_key}"},
+            timeout=10,
+        )
+        resp.raise_for_status()
+        return resp.json()
+
+resolved = await pending.wait_async(async_poll)
+```
+
+A built-in HTTP poller is planned for 1.7.0.
+
+### Mock backend for tests
+
+The SDK ships an in-process `MockApprovalBackend` so tests can exercise approval paths
+without standing up the real backend. Wire it into the polling loop by passing
+`poll_fn`:
+
+```python
+from controlzero import PendingApproval
+from controlzero.hitl.mock import MockApprovalBackend
+
+backend = MockApprovalBackend("approve_after_2s", delay_s=0.05)
+created = backend.create_request({"canonical_action": "delete_file"})
+pending = PendingApproval(
+    request_id=created["request_id"],
+    idempotency_key="test-key",
+    status="pending",
+    created_at=created["created_at"],
+    expires_at=created["expires_at"],
+)
+resolved = pending.wait(poll_fn=lambda rid: backend.get_request(rid))
+assert resolved.status == "approved"
+```
+
+The five supported modes are `approve_after_2s`, `approve_timed_after_2s`,
+`approve_forever_after_2s`, `deny_after_2s`, and `timeout`.
+
+### Identity requirement
+
+Every approval request must carry the operator email so the backend can route to a
+real person and stamp identity provenance on the grant. Set it once via the CLI:
+
+```bash
+controlzero install <agent> --email you@example.com
+```
+
+If the email is missing, `request_approval()` raises `HITLIdentityRequired`
+(E1707) before any HTTP traffic.
+
+### Secret reads with approvals
+
+When a policy gates a secret behind approval, `client.get_secret(name)` raises
+`SecretApprovalRequired` (E1710) carrying a `pending` attribute the caller waits
+on:
+
+```python
+from controlzero.errors import SecretApprovalRequired
+
+try:
+    value = cz.get_secret("PROD_DB_PASSWORD")
+except SecretApprovalRequired as exc:
+    resolved = exc.pending.wait()
+    if resolved.status == "approved":
+        value = cz.get_secret("PROD_DB_PASSWORD")  # retry now that grant exists
+    else:
+        raise  # abort
+```
+
+### Exception classes
+
+The 11 approval-related exception codes raised by this surface. Class names retain
+the `HITL` prefix because they are part of the stable public SDK API:
+
+| Code  | Class                            | Meaning                                                    |
+| ----- | -------------------------------- | ---------------------------------------------------------- |
+| E1701 | `HITLTimeoutError`               | Approver did not decide before `timeout_s` elapsed.        |
+| E1702 | `HITLBackendUnreachableError`    | POST to the approval endpoint failed after retries.        |
+| E1703 | `HITLPolicyVersionConflictError` | SDK bundle is missing the rule that triggered the request. |
+| E1704 | `HITLNotConfiguredError`         | Org has no approval settings row configured.               |
+| E1705 | `HITLNoApproverAvailable`        | Approver pool is empty or no member is active.             |
+| E1706 | `HITLIdentityNotInOrg`           | Operator email is not a member of the API key's org.       |
+| E1707 | `HITLIdentityRequired`           | No operator email set on this install.                     |
+| E1708 | `HITLIdentityClaimRejected`      | Backend rejected the identity claim.                       |
+| E1709 | `SecretValueLeakInPayload`       | Outbound payload contains a secret-shaped string. Aborted. |
+| E1710 | `SecretApprovalRequired`         | Secret read requires approval; wait on `exc.pending`.      |
+| E1711 | `SecretNotFound`                 | Named secret does not exist in the configured vault.       |
+
+Full reference and runbooks: [docs.controlzero.ai/hitl](https://docs.controlzero.ai/hitl).
+
 ## License
 
 Apache 2.0

{controlzero-1.5.8 → controlzero-1.6.0}/README.md

@@ -246,6 +246,154 @@ from controlzero import Client
 cz = Client()  # picks up the API key from env, audit ships remote
 ```
 
+## Human-in-the-Loop approvals
+
+Approvals let a policy block a tool call until a human approver decides allow or deny.
+An agent calls `client.request_approval(decision, ...)` whenever `guard()` returns a
+deny that is tagged `escalate_on_deny: true`, then waits on the returned
+`PendingApproval` for the human to respond.
+
+Basic flow:
+
+```python
+from controlzero import Client
+
+cz = Client(api_key="cz_live_...")  # approvals require hosted mode
+
+decision = cz.guard("delete_file", {"path": "/etc/passwd"})
+if decision.decision == "deny" and getattr(decision, "hitl_eligible", False):
+    pending = cz.request_approval(
+        decision,
+        message="agent wants to delete /etc/passwd; please confirm",
+        timeout_s=300,
+    )
+
+    # PendingApproval.wait() requires you to inject a `poll_fn`,
+    # a callable that returns the latest backend snapshot of the
+    # approval request. In 1.6.0 the SDK does NOT ship a built-in
+    # HTTP poller; you wire one yourself (or use the helper that
+    # ships with get_secret. See "Secret reads with approvals" below).
+    import httpx
+    api_url = "https://api.controlzero.ai"  # or your self-managed host
+
+    def poll_fn(request_id: str) -> dict:
+        resp = httpx.get(
+            f"{api_url}/api/approval-requests/{request_id}",
+            headers={"Authorization": f"Bearer {api_key}"},
+            timeout=10,
+        )
+        resp.raise_for_status()
+        return resp.json()
+
+    # Block until the human approves, denies, or the SLA expires.
+    resolved = pending.wait(poll_fn)
+    if resolved.status == "approved":
+        # proceed with the gated action
+        ...
+    else:
+        # denied or timed_out, abort the tool call
+        ...
+```
+
+`wait()` blocks the calling thread. For async code, use `wait_async()`,
+same contract, but the poll callable can be `async def` or a sync
+function (sync calls are dispatched to a thread executor so the event
+loop never blocks):
+
+```python
+async def async_poll(request_id: str) -> dict:
+    async with httpx.AsyncClient() as client:
+        resp = await client.get(
+            f"{api_url}/api/approval-requests/{request_id}",
+            headers={"Authorization": f"Bearer {api_key}"},
+            timeout=10,
+        )
+        resp.raise_for_status()
+        return resp.json()
+
+resolved = await pending.wait_async(async_poll)
+```
+
+A built-in HTTP poller is planned for 1.7.0.
+
+### Mock backend for tests
+
+The SDK ships an in-process `MockApprovalBackend` so tests can exercise approval paths
+without standing up the real backend. Wire it into the polling loop by passing
+`poll_fn`:
+
+```python
+from controlzero import PendingApproval
+from controlzero.hitl.mock import MockApprovalBackend
+
+backend = MockApprovalBackend("approve_after_2s", delay_s=0.05)
+created = backend.create_request({"canonical_action": "delete_file"})
+pending = PendingApproval(
+    request_id=created["request_id"],
+    idempotency_key="test-key",
+    status="pending",
+    created_at=created["created_at"],
+    expires_at=created["expires_at"],
+)
+resolved = pending.wait(poll_fn=lambda rid: backend.get_request(rid))
+assert resolved.status == "approved"
+```
+
+The five supported modes are `approve_after_2s`, `approve_timed_after_2s`,
+`approve_forever_after_2s`, `deny_after_2s`, and `timeout`.
+
+### Identity requirement
+
+Every approval request must carry the operator email so the backend can route to a
+real person and stamp identity provenance on the grant. Set it once via the CLI:
+
+```bash
+controlzero install <agent> --email you@example.com
+```
+
+If the email is missing, `request_approval()` raises `HITLIdentityRequired`
+(E1707) before any HTTP traffic.
+
+### Secret reads with approvals
+
+When a policy gates a secret behind approval, `client.get_secret(name)` raises
+`SecretApprovalRequired` (E1710) carrying a `pending` attribute the caller waits
+on:
+
+```python
+from controlzero.errors import SecretApprovalRequired
+
+try:
+    value = cz.get_secret("PROD_DB_PASSWORD")
+except SecretApprovalRequired as exc:
+    resolved = exc.pending.wait()
+    if resolved.status == "approved":
+        value = cz.get_secret("PROD_DB_PASSWORD")  # retry now that grant exists
+    else:
+        raise  # abort
+```
+
+### Exception classes
+
+The 11 approval-related exception codes raised by this surface. Class names retain
+the `HITL` prefix because they are part of the stable public SDK API:
+
+| Code  | Class                            | Meaning                                                    |
+| ----- | -------------------------------- | ---------------------------------------------------------- |
+| E1701 | `HITLTimeoutError`               | Approver did not decide before `timeout_s` elapsed.        |
+| E1702 | `HITLBackendUnreachableError`    | POST to the approval endpoint failed after retries.        |
+| E1703 | `HITLPolicyVersionConflictError` | SDK bundle is missing the rule that triggered the request. |
+| E1704 | `HITLNotConfiguredError`         | Org has no approval settings row configured.               |
+| E1705 | `HITLNoApproverAvailable`        | Approver pool is empty or no member is active.             |
+| E1706 | `HITLIdentityNotInOrg`           | Operator email is not a member of the API key's org.       |
+| E1707 | `HITLIdentityRequired`           | No operator email set on this install.                     |
+| E1708 | `HITLIdentityClaimRejected`      | Backend rejected the identity claim.                       |
+| E1709 | `SecretValueLeakInPayload`       | Outbound payload contains a secret-shaped string. Aborted. |
+| E1710 | `SecretApprovalRequired`         | Secret read requires approval; wait on `exc.pending`.      |
+| E1711 | `SecretNotFound`                 | Named secret does not exist in the configured vault.       |
+
+Full reference and runbooks: [docs.controlzero.ai/hitl](https://docs.controlzero.ai/hitl).
+
 ## License
 
 Apache 2.0

{controlzero-1.5.8 → controlzero-1.6.0}/controlzero/__init__.py

@@ -26,12 +26,14 @@ from controlzero.errors import (
     PolicyLoadError,
     PolicyValidationError,
 )
+from controlzero.hitl import PendingApproval
 from controlzero.policy_loader import load_policy
 
-__version__ = "1.5.8"
+__version__ = "1.6.0"
 
 __all__ = [
     "Client",
+    "PendingApproval",
     "PolicyDecision",
     "PolicyDeniedError",
     "PolicyLoadError",

{controlzero-1.5.8 → controlzero-1.6.0}/controlzero/_internal/bundle.py

@@ -353,6 +353,114 @@ def _zstd_decompress(data: bytes) -> bytes:
     )
 
 
+# --- Version gate (gh#602) -------------------------------------------------
+
+
+def _parse_version_tuple(v: str) -> tuple:
+    """Parse a SemVer-ish version string into a tuple suitable for
+    ``<`` comparison. Stdlib only; no `packaging` dep on the hot path.
+
+    Handles three forms we ship across SDKs:
+
+    - ``"1.5.8"`` -> ``(1, 5, 8)``
+    - ``"v1.7.6"`` -> ``(1, 7, 6)`` (Go SDK tag prefix)
+    - ``"1.5.5a1"`` -> ``(1, 5, 5, "a1")`` (PEP 440 prerelease)
+
+    Pre-release suffixes sort BELOW the release of the same numeric
+    triple, matching PEP 440 + SemVer. Unknown / empty segments
+    fall back to 0 so a malformed value never raises -- the caller
+    interprets "unknown version" as "permissive" (do not block).
+
+    Returned tuples can be compared with normal Python tuple
+    comparison: missing trailing elements are treated as zero
+    (we left-pad with zeros to keep comparison stable across
+    `"1.5"` vs `"1.5.8"`).
+    """
+    if not v:
+        # Match the canonical 5-tuple shape so empty inputs compare
+        # cleanly against parsed releases (release sentinel = 1, suffix "").
+        return (0, 0, 0, 1, "")
+    s = v.strip()
+    if s.startswith("v") or s.startswith("V"):
+        s = s[1:]
+    # Split off a PEP 440 / SemVer prerelease suffix on the last numeric
+    # component. We only need to recognise the floor (alpha < release),
+    # not order alphas relative to each other; tuple ordering with the
+    # suffix carried as a string handles the rest.
+    nums: list = []
+    suffix = ""
+    parts = s.split(".")
+    for i, p in enumerate(parts):
+        # Strip non-numeric tail (e.g. "5a1" -> 5, suffix "a1").
+        digits = ""
+        for ch in p:
+            if ch.isdigit():
+                digits += ch
+            else:
+                break
+        try:
+            nums.append(int(digits) if digits else 0)
+        except ValueError:
+            nums.append(0)
+        if len(digits) < len(p):
+            suffix = p[len(digits):]
+            # Drop any further parts -- a suffix on a non-final segment
+            # is malformed, treat the rest as absent.
+            break
+    while len(nums) < 3:
+        nums.append(0)
+    if suffix:
+        # Prerelease sorts BELOW release: pad with a sentinel that
+        # compares less than the empty string of a release tuple.
+        # Python tuple comparison handles mixed types only if the
+        # types match at each index; we add the suffix as a string
+        # AND lower the patch number by one fractional step using a
+        # second tuple element. Simpler: always emit a final element
+        # so release tuples are (M, m, p, "") and prereleases are
+        # (M, m, p-1, suffix) which sorts below release naturally.
+        #
+        # Avoiding the subtract path keeps the function pure and
+        # easy to reason about: a prerelease ALWAYS appends a
+        # non-empty string; release ALWAYS appends "". Comparison
+        # then works because "" < "a1" is False but ("a1",) > ("",)
+        # in tuple order -- which is the OPPOSITE of what we want.
+        # The conventional fix: prerelease suffix gets a leading 0
+        # marker so it sorts BELOW the release sentinel.
+        return tuple(nums) + (0, suffix)
+    return tuple(nums) + (1, "")
+
+
+def check_min_sdk_version(payload: dict, sdk_version: str) -> None:
+    """Raise :class:`BundleRequiresNewerSDKError` if the bundle
+    declares a higher floor than ``sdk_version``.
+
+    Bundles without ``metadata.min_sdk_version`` are accepted
+    unconditionally (back-compat: every bundle minted before #602
+    omits the field).
+
+    No-op fast path covers 99% of bundles in the field, so the
+    cost is one ``.get("metadata", {}).get("min_sdk_version")``
+    indirection per load.
+    """
+    metadata = payload.get("metadata")
+    if not isinstance(metadata, dict):
+        return
+    required = metadata.get("min_sdk_version")
+    if not isinstance(required, str) or not required:
+        return
+    # Lazy import: errors -> _internal cycle is avoided because
+    # this is invoked at runtime, after both modules finished loading.
+    from controlzero.errors import BundleRequiresNewerSDKError
+
+    if _parse_version_tuple(sdk_version) >= _parse_version_tuple(required):
+        return
+    raise BundleRequiresNewerSDKError(
+        required=required,
+        actual=sdk_version,
+        upgrade_command="pip install -U controlzero",
+    )
+
+
 # --- Schema translation ----------------------------------------------------
 
 
@@ -618,4 +726,25 @@ def _translate_rule(rule: dict, policy_id: str) -> Optional[dict]:
     if isinstance(rc, str) and rc:
         translated["reason_code"] = rc
 
+    # gh#175 P1.1 outside-voice review: pass `clients` / `projects`
+    # selectors through to the local rule shape. Without this, the
+    # backend ships selector-scoped rules in the signed bundle but
+    # the SDK loader strips them and the engine treats the rule as
+    # unscoped -- the dashboard renders gate_matched="none" for
+    # selector-scoped denies (silent over-block).
+    clients = rule.get("clients")
+    if isinstance(clients, list) and clients:
+        translated["clients"] = [str(c) for c in clients if isinstance(c, str)]
+    projects = rule.get("projects")
+    if isinstance(projects, list) and projects:
+        translated["projects"] = [str(p) for p in projects if isinstance(p, str)]
+
+    # Same pattern (gh#538): the HITL `escalate_on_deny` tag was
+    # also being stripped at the bundle layer. Forward it when
+    # present so a customer pre-tagging rules for HITL keeps the
+    # tag through hosted distribution.
+    escalate = rule.get("escalate_on_deny")
+    if escalate is not None:
+        translated["escalate_on_deny"] = bool(escalate)
+
     return translated