controlzero 1.5.3__tar.gz → 1.5.4__tar.gz

{controlzero-1.5.3 → controlzero-1.5.4}/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 1.5.4 -- 2026-05-13
+
+### Changed
+
+- **Single-file local audit log** (T96, part of the SDK_LOCAL_LAYOUT
+  spec). Pre-1.5.4 the SDK split rows across `~/.controlzero/audit.log`
+  (policy-engine decisions) and `~/.controlzero/events.log` (carve-out +
+  hook lifecycle). Customers had to tail two files and `cz debug bundle`
+  had to merge both for support. After 1.5.4 every line lands in
+  `audit.log` (JSON Lines). Lifecycle entries carry the original `event`
+  key so `controlzero status` can still filter for carve-out events.
+  `controlzero status` reads BOTH `audit.log` AND `events.log` (legacy
+  fallback) so users upgrading from <= 1.5.3 keep seeing pre-upgrade
+  history; the migration shim in a follow-up release (T101) will rename
+  the legacy file in-place.
+
 ## 1.5.3 -- 2026-05-12
 
 ### Added

{controlzero-1.5.3 → controlzero-1.5.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: controlzero
-Version: 1.5.3
+Version: 1.5.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

{controlzero-1.5.3 → controlzero-1.5.4}/controlzero/__init__.py

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

{controlzero-1.5.3 → controlzero-1.5.4}/controlzero/cli/main.py

@@ -401,9 +401,22 @@ def status_cmd():
 
     # Summarize recent carve-out events so the user can see whether
     # their agent has been allowed-through without policy.
+    # 1.5.4 (T96): lifecycle events now land in audit.log alongside
+    # decisions. For users who upgraded from <=1.5.3, we ALSO
+    # read the legacy events.log so the status summary keeps
+    # showing pre-upgrade carve-out history. The migration shim
+    # (T101) renames events.log -> audit.log in a follow-up; this
+    # read-both behaviour is the one-release grace window.
+    _sources = []
+    if GLOBAL_AUDIT_PATH.exists():
+        _sources.append(GLOBAL_AUDIT_PATH)
     if GLOBAL_EVENTS_PATH.exists():
+        _sources.append(GLOBAL_EVENTS_PATH)
+    if _sources:
         try:
-            lines = GLOBAL_EVENTS_PATH.read_text(encoding="utf-8").splitlines()
+            lines: list[str] = []
+            for _src in _sources:
+                lines.extend(_src.read_text(encoding="utf-8").splitlines())
             carve_out_events = [
                 json.loads(l) for l in lines
                 if l.strip() and "unenrolled_first_run_allow" in l
@@ -984,16 +997,28 @@ def _resolve_default_on_missing() -> str:
 
 
 def _append_event(event: dict) -> None:
-    """Append a structured event to ~/.controlzero/events.log.
-
-    Used today for the unenrolled-first-run carve-out so
-    `controlzero status` can report whether the hook is currently
-    running in allow-all mode. Append-only JSON lines. Never raises
-    -- a disk failure here must not break the agent.
+    """Append a structured lifecycle event to ~/.controlzero/audit.log.
+
+    Used for the unenrolled-first-run carve-out (so `controlzero
+    status` can report whether the hook is allowing through without
+    policy), the T108 LOCAL_OVERRIDE governance event, and any
+    future hook-lifecycle event we want to surface to support.
+
+    1.5.4 (T96 -- SDK_LOCAL_LAYOUT spec): the SDK now writes ONE
+    JSONL file at ``~/.controlzero/audit.log``. Pre-1.5.4 the SDK
+    split rows across ``audit.log`` (decisions) and ``events.log``
+    (lifecycle). Customers had to tail two files; ``cz debug
+    bundle`` had to read two paths. The single-file layout
+    standardises everything.
+
+    Decision rows are written by the BearerAuditSink / local
+    AuditLogger (in JSON Lines too); we use an explicit
+    ``event_type`` field on lifecycle entries so a reader can
+    filter (decisions land without that key).
     """
     try:
         GLOBAL_POLICY_DIR.mkdir(parents=True, exist_ok=True)
-        with GLOBAL_EVENTS_PATH.open("a", encoding="utf-8") as f:
+        with GLOBAL_AUDIT_PATH.open("a", encoding="utf-8") as f:
             f.write(json.dumps(event) + "\n")
     except Exception:  # noqa: BLE001
         # Best-effort. Logging failure must not propagate.
@@ -1446,6 +1471,54 @@ def _write_api_key_config(api_key: str) -> None:
     )
 
 
+def _prefetch_bundle(api_key: str) -> None:
+    """Best-effort pre-warm of the hosted policy bundle at install time.
+
+    Called by `controlzero install <agent> --api-key cz_...`. Doing the
+    bundle pull now (a) surfaces an obvious install-time error if the
+    api_key is wrong or the network is dead, instead of failing
+    silently on the first hook call; and (b) eliminates the cold-start
+    spike Claude Code customers see on their first PreToolUse hook
+    after install.
+
+    Never raises -- a failed pre-fetch must not block the install. If
+    the pull fails, the first hook call will retry per the normal
+    hosted-mode path; the user has already gotten an installer warning
+    so they know to investigate.
+    """
+    try:
+        from controlzero.hosted_policy import load_hosted_policy
+        _local_source, parsed = load_hosted_policy(api_key)
+        rule_count = 0
+        try:
+            rule_count = len((parsed or {}).get("rules", []) or [])
+        except Exception:  # noqa: BLE001
+            rule_count = 0
+        click.echo(
+            f"  Pre-fetched hosted policy ({rule_count} rule"
+            f"{'s' if rule_count != 1 else ''}). First tool call will be fast."
+        )
+    except Exception as exc:  # noqa: BLE001
+        # Common failures: auth (HostedAuthError -> wrong api_key),
+        # network (HostedBootstrapError -> backend unreachable), or
+        # tamper (bundle signature mismatch). Surface ALL of them in
+        # the installer output so the user sees the problem now, not
+        # later. We do not exit non-zero: install completes; first
+        # hook call will retry and the user can re-run install once
+        # they fix the env.
+        click.echo("")
+        click.echo(
+            f"  WARNING: Could not pre-fetch hosted policy: {exc}",
+            err=True,
+        )
+        click.echo(
+            "  The install is complete. The SDK will retry on the "
+            "first tool call. If this keeps failing, double-check the "
+            "api_key + network reachability to https://api.controlzero.ai.",
+            err=True,
+        )
+
+
 def _print_api_key_status(api_key: Optional[str]) -> None:
     """Print API key configuration status after install."""
     if api_key:
@@ -1502,6 +1575,7 @@ def install_claude_code(force: bool, merge: bool, settings: Optional[str], api_k
             )
             sys.exit(1)
         _write_api_key_config(api_key)
+        _prefetch_bundle(api_key)
 
     template_path = TEMPLATE_DIR / "claude-code.yaml"
     if not template_path.exists():
@@ -1657,6 +1731,7 @@ def install_gemini_cli(force: bool, merge: bool, settings: Optional[str], api_ke
             )
             sys.exit(1)
         _write_api_key_config(api_key)
+        _prefetch_bundle(api_key)
 
     template_path = TEMPLATE_DIR / "gemini-cli.yaml"
     if not template_path.exists():
@@ -1825,6 +1900,7 @@ def install_codex_cli(force: bool, merge: bool, config: Optional[str], api_key:
             )
             sys.exit(1)
         _write_api_key_config(api_key)
+        _prefetch_bundle(api_key)
 
     template_path = TEMPLATE_DIR / "codex-cli.yaml"
     if not template_path.exists():

{controlzero-1.5.3 → controlzero-1.5.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "controlzero"
-version = "1.5.3"
+version = "1.5.4"
 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.3 → controlzero-1.5.4}/tests/test_cli_carve_out.py

@@ -85,17 +85,25 @@ def test_carve_out_no_api_key_no_enrollment_allows(tmp_path, monkeypatch):
 
 
 def test_carve_out_logs_event_for_status(tmp_path, monkeypatch):
-    """Carve-out runs must append a JSON line to events.log so
+    """Carve-out runs must append a JSON line to the audit log so
     `controlzero status` can report the count.
+
+    1.5.4 (T96 / SDK_LOCAL_LAYOUT): lifecycle events now land in
+    audit.log alongside decisions, not in a separate events.log.
     """
     cli_main = _reload_cli(tmp_path, monkeypatch)
     runner = CliRunner()
     payload = json.dumps({"tool_name": "Bash", "tool_input": {}})
     runner.invoke(cli_main.cli, ["hook-check"], input=payload)
 
-    events_path = cli_main.GLOBAL_EVENTS_PATH
-    assert events_path.exists()
-    lines = events_path.read_text().splitlines()
+    audit_path = cli_main.GLOBAL_AUDIT_PATH
+    assert audit_path.exists(), (
+        "T96: lifecycle events must land in audit.log after 1.5.4"
+    )
+    lines = [
+        l for l in audit_path.read_text().splitlines()
+        if l.strip() and "unenrolled_first_run_allow" in l
+    ]
     assert len(lines) == 1
     ev = json.loads(lines[0])
     assert ev["event"] == "unenrolled_first_run_allow"

controlzero-1.5.4/tests/test_t96_single_audit_log.py

@@ -0,0 +1,126 @@
+"""Regression tests for T96 -- single-file local audit log (1.5.4).
+
+Before 1.5.4 the SDK wrote decision rows to ``~/.controlzero/audit.log``
+and lifecycle events (carve-out, hook errors) to a separate
+``~/.controlzero/events.log``. Two log paths confused customers and
+``cz debug bundle`` had to merge both.
+
+After 1.5.4 ``_append_event()`` writes to ``audit.log`` directly.
+``controlzero status`` still reads BOTH files (legacy events.log
+fallback) so users upgrading from <= 1.5.3 keep seeing pre-upgrade
+carve-out history; the migration shim (T101) renames the legacy file
+in a follow-up release.
+"""
+
+from __future__ import annotations
+
+import json
+
+import pytest
+
+import controlzero.cli.main as cli_main
+
+
+def test_append_event_writes_to_audit_log_not_events_log(tmp_path, monkeypatch):
+    audit_path = tmp_path / "audit.log"
+    events_path = tmp_path / "events.log"
+    monkeypatch.setattr(cli_main, "GLOBAL_POLICY_DIR", tmp_path)
+    monkeypatch.setattr(cli_main, "GLOBAL_AUDIT_PATH", audit_path)
+    monkeypatch.setattr(cli_main, "GLOBAL_EVENTS_PATH", events_path)
+
+    cli_main._append_event({
+        "event": "unenrolled_first_run_allow",
+        "tool_name": "Bash",
+        "reason_code": "RULE_MATCH",
+        "ts": 1715000000.0,
+    })
+
+    # T96 invariant: writes land in audit.log, NOT events.log.
+    assert audit_path.exists(), "audit.log should exist after _append_event"
+    assert not events_path.exists(), (
+        "events.log MUST NOT be created by 1.5.4 -- T96 collapsed the "
+        "two log files into one"
+    )
+
+    lines = audit_path.read_text().splitlines()
+    assert len(lines) == 1
+    parsed = json.loads(lines[0])
+    assert parsed["event"] == "unenrolled_first_run_allow"
+    assert parsed["tool_name"] == "Bash"
+
+
+def test_status_reads_carve_out_events_from_audit_log(tmp_path, monkeypatch):
+    # Status pulls carve-out lifecycle events out of audit.log. Pre-1.5.4
+    # they lived in events.log; the status command now sees them in
+    # audit.log because _append_event writes there.
+    audit_path = tmp_path / "audit.log"
+    events_path = tmp_path / "events.log"
+    monkeypatch.setattr(cli_main, "GLOBAL_POLICY_DIR", tmp_path)
+    monkeypatch.setattr(cli_main, "GLOBAL_AUDIT_PATH", audit_path)
+    monkeypatch.setattr(cli_main, "GLOBAL_EVENTS_PATH", events_path)
+
+    # Mix decision rows + lifecycle rows in audit.log (the post-1.5.4
+    # reality). Status must filter to the carve-out rows only.
+    audit_path.write_text("\n".join([
+        json.dumps({"decision": "allow", "tool": "Read", "ts": 1.0}),
+        json.dumps({"event": "unenrolled_first_run_allow", "tool_name": "Bash", "ts": 2.0}),
+        json.dumps({"decision": "deny", "tool": "Write", "ts": 3.0}),
+        json.dumps({"event": "unenrolled_first_run_allow", "tool_name": "Edit", "ts": 4.0}),
+    ]) + "\n")
+
+    from click.testing import CliRunner
+
+    runner = CliRunner()
+    result = runner.invoke(cli_main.cli, ["status"])
+    assert result.exit_code == 0
+    assert "carve-out allows: 2" in result.output
+
+
+def test_status_falls_back_to_legacy_events_log_for_pre_1_5_4_history(
+    tmp_path, monkeypatch
+):
+    # The migration grace window: users upgrading from <= 1.5.3 have
+    # carve-out history in events.log. status_cmd reads both files so
+    # the pre-upgrade summary keeps showing until the migration shim
+    # (T101) renames the file.
+    audit_path = tmp_path / "audit.log"
+    events_path = tmp_path / "events.log"
+    monkeypatch.setattr(cli_main, "GLOBAL_POLICY_DIR", tmp_path)
+    monkeypatch.setattr(cli_main, "GLOBAL_AUDIT_PATH", audit_path)
+    monkeypatch.setattr(cli_main, "GLOBAL_EVENTS_PATH", events_path)
+
+    # Pre-1.5.4 history lives in events.log:
+    events_path.write_text(
+        json.dumps(
+            {"event": "unenrolled_first_run_allow", "tool_name": "LegacyBash", "ts": 1.0}
+        )
+        + "\n"
+    )
+    # Post-upgrade row lands in audit.log:
+    audit_path.write_text(
+        json.dumps(
+            {"event": "unenrolled_first_run_allow", "tool_name": "Bash", "ts": 2.0}
+        )
+        + "\n"
+    )
+
+    from click.testing import CliRunner
+
+    runner = CliRunner()
+    result = runner.invoke(cli_main.cli, ["status"])
+    assert result.exit_code == 0
+    # Both rows surface in the summary count.
+    assert "carve-out allows: 2" in result.output
+
+
+def test_append_event_silently_swallows_disk_errors(tmp_path, monkeypatch):
+    # The "never brick the agent" guarantee: if the audit.log open
+    # fails (read-only volume, full disk, perm denied), _append_event
+    # must NOT raise.
+    bad_path = tmp_path / "definitely-not-writable" / "audit.log"
+    monkeypatch.setattr(cli_main, "GLOBAL_POLICY_DIR", tmp_path / "no-dir")
+    monkeypatch.setattr(cli_main, "GLOBAL_AUDIT_PATH", bad_path)
+
+    # Should not raise even though the directory can't be created in
+    # some scenarios; the function is best-effort.
+    cli_main._append_event({"event": "x"})

controlzero-1.5.4/tests/test_t99_install_prefetch_bundle.py

@@ -0,0 +1,184 @@
+"""Regression tests for T99 -- `controlzero install --api-key` pre-fetches
+the hosted policy bundle at install time (1.5.4/1.5.5 depending on which
+PR merges first).
+
+Before T99 the installer wrote the api_key to ~/.controlzero/config.yaml
+and exited. The first PreToolUse hook call did the bundle fetch, which:
+
+* Hid auth errors (wrong api_key) until the customer ran their agent.
+* Added a 1-2s cold-start spike to the first hook call.
+
+After T99 the installer calls _prefetch_bundle(api_key) immediately
+after _write_api_key_config(api_key). On success it prints the rule
+count. On failure (auth, network, tamper) it prints a WARNING to stderr
+and exits cleanly -- the install completes either way so the user is
+not left with a half-configured machine, but they SEE the problem now.
+"""
+
+from __future__ import annotations
+
+from unittest import mock
+
+import pytest
+
+import controlzero.cli.main as cli_main
+
+
+def test_prefetch_bundle_prints_rule_count_on_success(capsys):
+    fake_parsed = {"rules": [{"id": "r1"}, {"id": "r2"}, {"id": "r3"}]}
+
+    with mock.patch(
+        "controlzero.hosted_policy.load_hosted_policy",
+        return_value=("inline", fake_parsed),
+    ):
+        cli_main._prefetch_bundle("cz_live_abc123")
+
+    captured = capsys.readouterr()
+    assert "Pre-fetched hosted policy (3 rules)" in captured.out
+    assert "WARNING" not in captured.err
+    assert "WARNING" not in captured.out
+
+
+def test_prefetch_bundle_singular_rule_text(capsys):
+    fake_parsed = {"rules": [{"id": "only"}]}
+    with mock.patch(
+        "controlzero.hosted_policy.load_hosted_policy",
+        return_value=("inline", fake_parsed),
+    ):
+        cli_main._prefetch_bundle("cz_live_abc123")
+    captured = capsys.readouterr()
+    assert "1 rule)" in captured.out  # not "1 rules"
+
+
+def test_prefetch_bundle_handles_empty_rules_list(capsys):
+    fake_parsed = {"rules": []}
+    with mock.patch(
+        "controlzero.hosted_policy.load_hosted_policy",
+        return_value=("inline", fake_parsed),
+    ):
+        cli_main._prefetch_bundle("cz_live_abc123")
+    captured = capsys.readouterr()
+    # Zero is a legitimate (pre-attach) state -- show the count, not
+    # an error. Cf. project_424_real_root_causes.md.
+    assert "Pre-fetched hosted policy (0 rules)" in captured.out
+
+
+def test_prefetch_bundle_warns_on_auth_failure_but_does_not_raise(capsys):
+    # Common failure: customer pasted the wrong api_key. We must NOT
+    # raise -- install must complete -- but we MUST surface the error
+    # in stderr so they see it before their first agent run.
+    with mock.patch(
+        "controlzero.hosted_policy.load_hosted_policy",
+        side_effect=RuntimeError("HostedAuthError: 401"),
+    ):
+        # No exception leaks out:
+        cli_main._prefetch_bundle("cz_live_wrong")
+
+    captured = capsys.readouterr()
+    assert "WARNING: Could not pre-fetch hosted policy" in captured.err
+    assert "HostedAuthError: 401" in captured.err
+    assert "double-check the api_key" in captured.err
+
+
+def test_prefetch_bundle_warns_on_network_failure(capsys):
+    with mock.patch(
+        "controlzero.hosted_policy.load_hosted_policy",
+        side_effect=ConnectionError("Connection refused"),
+    ):
+        cli_main._prefetch_bundle("cz_live_abc123")
+
+    captured = capsys.readouterr()
+    assert "WARNING: Could not pre-fetch hosted policy" in captured.err
+    assert "Connection refused" in captured.err
+    # Must mention the SDK will retry so the user knows install is OK:
+    assert "retry on the first tool call" in captured.err
+
+
+def test_prefetch_bundle_handles_missing_rules_key_gracefully(capsys):
+    # Defensive: backend may return a parsed bundle with no rules key
+    # (legacy shape, malformed response). The rule_count fallback is
+    # 0, no exception.
+    with mock.patch(
+        "controlzero.hosted_policy.load_hosted_policy",
+        return_value=("inline", {"unexpected": "shape"}),
+    ):
+        cli_main._prefetch_bundle("cz_live_abc123")
+    captured = capsys.readouterr()
+    assert "Pre-fetched hosted policy (0 rules)" in captured.out
+
+
+def test_install_claude_code_calls_prefetch_when_api_key_present(tmp_path, monkeypatch):
+    """End-to-end: install claude-code --api-key X must call _prefetch_bundle."""
+    monkeypatch.setattr(cli_main, "GLOBAL_POLICY_DIR", tmp_path / ".controlzero")
+    monkeypatch.setattr(
+        cli_main, "GLOBAL_POLICY_PATH", tmp_path / ".controlzero" / "policy.yaml"
+    )
+    monkeypatch.setattr(
+        cli_main, "GLOBAL_CONFIG_PATH", tmp_path / ".controlzero" / "config.yaml"
+    )
+    monkeypatch.setattr(
+        cli_main, "GLOBAL_AUDIT_PATH", tmp_path / ".controlzero" / "audit.log"
+    )
+
+    settings_path = tmp_path / ".claude" / "settings.json"
+
+    fake_parsed = {"rules": [{"id": "r1"}]}
+    with mock.patch(
+        "controlzero.hosted_policy.load_hosted_policy",
+        return_value=("inline", fake_parsed),
+    ) as mocked:
+        from click.testing import CliRunner
+
+        runner = CliRunner()
+        result = runner.invoke(
+            cli_main.cli,
+            [
+                "install",
+                "claude-code",
+                "--api-key",
+                "cz_live_testkey",
+                "--settings",
+                str(settings_path),
+                "--force",
+            ],
+        )
+
+    assert result.exit_code == 0, result.output
+    mocked.assert_called_once_with("cz_live_testkey")
+    assert "Pre-fetched hosted policy (1 rule)" in result.output
+
+
+def test_install_without_api_key_does_NOT_prefetch(tmp_path, monkeypatch):
+    """No api_key = no network call (offline install must stay offline)."""
+    monkeypatch.setattr(cli_main, "GLOBAL_POLICY_DIR", tmp_path / ".controlzero")
+    monkeypatch.setattr(
+        cli_main, "GLOBAL_POLICY_PATH", tmp_path / ".controlzero" / "policy.yaml"
+    )
+    monkeypatch.setattr(
+        cli_main, "GLOBAL_CONFIG_PATH", tmp_path / ".controlzero" / "config.yaml"
+    )
+    monkeypatch.setattr(
+        cli_main, "GLOBAL_AUDIT_PATH", tmp_path / ".controlzero" / "audit.log"
+    )
+
+    settings_path = tmp_path / ".claude" / "settings.json"
+
+    with mock.patch(
+        "controlzero.hosted_policy.load_hosted_policy"
+    ) as mocked:
+        from click.testing import CliRunner
+
+        runner = CliRunner()
+        result = runner.invoke(
+            cli_main.cli,
+            [
+                "install",
+                "claude-code",
+                "--settings",
+                str(settings_path),
+                "--force",
+            ],
+        )
+
+    assert result.exit_code == 0, result.output
+    mocked.assert_not_called()