controlzero 1.5.3__tar.gz → 1.5.5a1__tar.gz

{controlzero-1.5.3 → controlzero-1.5.5a1}/CHANGELOG.md

@@ -1,5 +1,55 @@
 # Changelog
 
+## 1.5.5a1 (pre-release) -- 2026-05-13
+
+This is a **pre-release**. `pip install control-zero` continues to
+resolve to the latest stable (1.5.3). To install this alpha:
+
+    pip install --pre control-zero
+    # or pin explicitly:
+    pip install control-zero==1.5.5a1
+
+Promotion to stable `1.5.5` will follow once we have soak time on the
+T96 + T101 layout changes in real customer environments.
+
+### Added
+
+- **`controlzero env-dump` diagnostic subcommand** (#438). Prints a
+  JSON snapshot of the SDK's effective environment: env vars
+  (redacted by default, `--show-secrets` to unredact with a loud
+  warning), host-adapter selection, file inventory (size + mtime,
+  not contents), and resolved API URL. With `--from-hook` it parses
+  a stdin payload so the output reflects what the hook subprocess
+  actually sees. Built for fast Windows-hook triage after the
+  2026-05-12 CloudShift incident -- a customer can now run a single
+  command and send us the JSON instead of guessing which env vars
+  their hook sees.
+
+- **Layout migration shim** (T101, SDK_LOCAL_LAYOUT spec). Folds any
+  legacy `~/.controlzero/events.log` into `audit.log` on first run of
+  the CLI or first `Client()` construction, then deletes the legacy
+  file. Writes a single `layout_migration` lifecycle marker into
+  `audit.log` so support can grep for the migration. Idempotent and
+  best-effort: a disk failure here never breaks the user's agent.
+  `controlzero status` no longer reads the legacy file; the shim
+  guarantees it's gone by the time any subcommand runs.
+
+## 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.5a1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: controlzero
-Version: 1.5.3
+Version: 1.5.5a1
 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.5a1}/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.5a1"
 
 __all__ = [
     "Client",

{controlzero-1.5.3 → controlzero-1.5.5a1}/controlzero/cli/main.py

@@ -11,6 +11,7 @@ import os
 import sys
 import threading
 import time
+from datetime import datetime, timezone
 from pathlib import Path
 from typing import Optional
 
@@ -79,6 +80,16 @@ def cli():
       controlzero test <tool>    Dry-run a tool call against the policy
       controlzero tail           Follow the local audit log
     """
+    # T101 layout-migration shim: fold any legacy ~/.controlzero/events.log
+    # into audit.log before the subcommand runs so downstream commands
+    # see the single-file layout the SDK_LOCAL_LAYOUT spec promises.
+    # Idempotent and best-effort: no-op when events.log is absent.
+    try:
+        from controlzero.layout_migration import run_layout_migration
+        run_layout_migration(GLOBAL_POLICY_DIR, sdk_version=__version__)
+    except Exception:  # noqa: BLE001
+        # Migration must never break the CLI.
+        pass
 
 
 @cli.command()
@@ -350,6 +361,146 @@ def policy_pull_cmd():
         click.echo(f"    ... and {len(rules) - 10} more")
 
 
+@cli.command("env-dump")
+@click.option(
+    "--show-secrets",
+    is_flag=True,
+    default=False,
+    help="Un-redact API keys and secret-like env vars. Use only when sharing with Control Zero support.",
+)
+@click.option(
+    "--from-hook",
+    is_flag=True,
+    default=False,
+    help="Read a hook-style JSON payload from stdin and report which host-agent adapter would claim it.",
+)
+def env_dump_cmd(show_secrets: bool, from_hook: bool):
+    """Print a redacted snapshot of the SDK's effective environment.
+
+    Designed for support: paste the JSON output into a ticket and the
+    Control Zero team can tell you (without round-trips) which host
+    adapter the SDK is selecting, which env vars are present, which
+    config files exist, and what API URL is in effect.
+
+    Examples:
+
+      controlzero env-dump
+      controlzero env-dump --from-hook < /tmp/claude-payload.json
+      controlzero env-dump --show-secrets    # un-redacts; DANGEROUS
+
+    Filed as #438 follow-up to the 2026-05-12 CloudShift Bug E episode
+    where source-detection on Windows was unknown without instrumenting
+    the customer's hook environment.
+    """
+    import platform as _platform
+    import re as _re
+
+    payload: dict = {}
+    if from_hook:
+        try:
+            raw = sys.stdin.read()
+            if raw.strip():
+                payload = json.loads(raw)
+        except (KeyboardInterrupt, EOFError, json.JSONDecodeError):
+            payload = {}
+
+    # Mask CONTROLZERO_API_KEY and *_TOKEN / *_KEY / *_SECRET env vars
+    # unless --show-secrets is passed.
+    _secret_pat = _re.compile(r"(TOKEN|KEY|SECRET|PASSWORD|CREDENTIAL)$", _re.IGNORECASE)
+    env_view: dict = {}
+    for k, v in sorted(os.environ.items()):
+        if not isinstance(v, str):
+            continue
+        # Keep ASCII-printable values, length-capped at 200 chars; non-
+        # printable env vars are usually accidental binary export and
+        # not useful for debugging.
+        if any(ord(c) < 32 or ord(c) > 126 for c in v):
+            redacted = f"<NON-PRINTABLE-LEN-{len(v)}>"
+        elif show_secrets:
+            redacted = v
+        elif k == "CONTROLZERO_API_KEY":
+            # Always preserve the public prefix so "is it a live or
+            # test key" is observable without leaking entropy.
+            if v.startswith("cz_live_"):
+                redacted = "cz_live_***"
+            elif v.startswith("cz_test_"):
+                redacted = "cz_test_***"
+            else:
+                redacted = "***"
+        elif _secret_pat.search(k):
+            redacted = f"<REDACTED-LEN-{len(v)}>"
+        else:
+            redacted = v if len(v) <= 200 else (v[:200] + f"...<+{len(v) - 200}>")
+        env_view[k] = redacted
+
+    # Host adapter selection.
+    try:
+        from controlzero.cli.hosts import select_adapter as _select_adapter
+        adapter = _select_adapter(payload, os.environ)
+        adapter_info = {
+            "name": adapter.name,
+            "canonical_source": adapter.canonical_source,
+        }
+    except Exception as exc:  # noqa: BLE001
+        adapter_info = {"name": "unknown", "error": str(exc)}
+
+    # Config + log file presence (size + mtime, NOT contents).
+    files = {}
+    for path in (
+        GLOBAL_POLICY_DIR / "config.yaml",
+        GLOBAL_POLICY_DIR / "policy.yaml",
+        GLOBAL_POLICY_DIR / "audit.log",
+        GLOBAL_POLICY_DIR / "events.log",  # legacy, pre-1.5.4
+        GLOBAL_POLICY_DIR / "enrollment.json",
+        Path.home() / ".claude" / "settings.json",
+        Path.home() / ".gemini" / "settings.json",
+        Path.home() / ".codex" / "hooks.json",
+    ):
+        try:
+            if path.exists():
+                stat = path.stat()
+                files[str(path)] = {
+                    "exists": True,
+                    "size_bytes": stat.st_size,
+                    "mtime_iso": datetime.fromtimestamp(
+                        stat.st_mtime, tz=timezone.utc
+                    ).isoformat(),
+                }
+            else:
+                files[str(path)] = {"exists": False}
+        except Exception as exc:  # noqa: BLE001
+            files[str(path)] = {"exists": "error", "error": str(exc)}
+
+    # Resolved hosted API URL.
+    api_url = os.environ.get("CONTROLZERO_API_URL", "https://api.controlzero.ai")
+
+    from controlzero import __version__ as _cz_version
+
+    dump = {
+        "controlzero_version": _cz_version,
+        "hostname": _platform.node(),
+        "system": _platform.system(),
+        "release": _platform.release(),
+        "machine": _platform.machine(),
+        "python_version": _platform.python_version(),
+        "python_executable": sys.executable,
+        "api_url": api_url,
+        "adapter": adapter_info,
+        "from_hook_payload_keys": sorted(payload.keys()) if payload else [],
+        "files": files,
+        "env": env_view,
+        "show_secrets": show_secrets,
+    }
+
+    if show_secrets:
+        click.echo(
+            "WARNING: env-dump was run with --show-secrets. The output below contains unredacted API keys, tokens, and credentials.",
+            err=True,
+        )
+
+    click.echo(json.dumps(dump, indent=2, sort_keys=True))
+
+
 @cli.command("status")
 def status_cmd():
     """Show enrollment state, policy source, and recent carve-out events.
@@ -401,9 +552,13 @@ def status_cmd():
 
     # Summarize recent carve-out events so the user can see whether
     # their agent has been allowed-through without policy.
-    if GLOBAL_EVENTS_PATH.exists():
+    # 1.5.5 (T101): the layout-migration shim runs in cli() before
+    # this subcommand, so any legacy events.log content has already
+    # been folded into audit.log by the time we get here. Only
+    # audit.log is read.
+    if GLOBAL_AUDIT_PATH.exists():
         try:
-            lines = GLOBAL_EVENTS_PATH.read_text(encoding="utf-8").splitlines()
+            lines = GLOBAL_AUDIT_PATH.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 +1139,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 +1613,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 +1717,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 +1873,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 +2042,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.5a1}/controlzero/client.py

@@ -127,6 +127,21 @@ class Client:
                 "Pass either `policy` or `policy_file`, not both."
             )
 
+        # T101 layout-migration shim: fold any legacy
+        # ~/.controlzero/events.log into audit.log on every Client
+        # construction. Idempotent and best-effort: no-op when the
+        # legacy file is absent. Mirrors the CLI shim.
+        try:
+            from controlzero import __version__ as _cz_version
+            from controlzero.layout_migration import run_layout_migration
+            _cz_home = Path(
+                os.environ.get("CONTROLZERO_HOME") or (Path.home() / ".controlzero")
+            )
+            run_layout_migration(_cz_home, sdk_version=_cz_version)
+        except Exception:  # noqa: BLE001
+            # Migration must never break the user's agent.
+            pass
+
         # Resolve API key from arg or env
         self._api_key = api_key or os.environ.get("CONTROLZERO_API_KEY")
 

controlzero-1.5.5a1/controlzero/layout_migration.py

@@ -0,0 +1,85 @@
+"""SDK_LOCAL_LAYOUT migration shim (T101).
+
+Pre-1.5.4 the Python SDK split CLI lifecycle events into a separate
+``~/.controlzero/events.log`` file. T96 (1.5.4) collapsed everything
+into the single ``audit.log`` JSONL file the SDK_LOCAL_LAYOUT spec
+mandates. This shim handles existing customer disks: if ``events.log``
+is still present, fold its lines into ``audit.log`` (preserving order),
+write a lifecycle marker so support can see the migration happened,
+then delete ``events.log``.
+
+Idempotent: no-op when ``events.log`` is absent. Safe to call on every
+CLI invocation and every Client construction. Never raises -- a disk
+failure here must not break the user's agent.
+
+The Node and Go SDKs ship the same shim under the same contract so a
+customer who copies ``~/.controlzero/`` from a Python install to a
+Node-only or Go-only install gets the same automatic cleanup.
+"""
+
+from __future__ import annotations
+
+import json
+from datetime import datetime, timezone
+from pathlib import Path
+
+
+def run_layout_migration(state_dir: Path, sdk_version: str = "unknown") -> int:
+    """Fold legacy ``events.log`` into ``audit.log`` and delete it.
+
+    Returns the number of lines migrated. 0 means no migration was
+    needed (either ``events.log`` didn't exist or it was empty).
+
+    Never raises. Any IOError or decode error is swallowed so the
+    SDK keeps working even if the migration fails.
+    """
+    try:
+        events_path = state_dir / "events.log"
+        audit_path = state_dir / "audit.log"
+
+        if not events_path.exists():
+            return 0
+
+        try:
+            raw = events_path.read_text(encoding="utf-8")
+        except OSError:
+            return 0
+
+        lines = [l for l in raw.splitlines() if l.strip()]
+
+        # Ensure the directory exists before we write the marker.
+        state_dir.mkdir(parents=True, exist_ok=True)
+
+        # Append the migrated lines to audit.log preserving order, then
+        # write a single lifecycle marker so support can grep
+        # `"layout_migration"` and see when this customer's disk was
+        # upgraded. Marker goes last so the migrated lines keep their
+        # original chronological position relative to the rest of the
+        # file.
+        with audit_path.open("a", encoding="utf-8") as f:
+            for line in lines:
+                f.write(line + "\n")
+            marker = {
+                "ts": datetime.now(timezone.utc).isoformat(),
+                "kind": "lifecycle",
+                "event_type": "layout_migration",
+                "sdk": "python",
+                "sdk_version": sdk_version,
+                "from": "events.log",
+                "to": "audit.log",
+                "lines_migrated": len(lines),
+            }
+            f.write(json.dumps(marker) + "\n")
+
+        # Delete the legacy file. If the unlink fails (permissions,
+        # busy file on Windows), leave it -- the next run will retry.
+        try:
+            events_path.unlink()
+        except OSError:
+            pass
+
+        return len(lines)
+    except Exception:
+        # Last-resort guard. Migration is best-effort; never break the
+        # agent because of it.
+        return 0

{controlzero-1.5.3 → controlzero-1.5.5a1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "controlzero"
-version = "1.5.3"
+version = "1.5.5a1"
 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.5a1}/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.5a1/tests/test_env_dump_438.py

@@ -0,0 +1,149 @@
+"""Regression tests for `controlzero env-dump` (#438).
+
+Filed as a follow-up to the 2026-05-12 CloudShift Bug E episode where
+source-detection on Windows took multiple rounds because we had no way
+to ask the customer "what env vars does YOUR hook subprocess see?"
+
+The subcommand prints a JSON snapshot of the SDK's effective
+environment: env vars (redacted by default), host-adapter selection,
+file inventory, API URL. \`--from-hook\` reads a stdin payload so the
+output reflects what the hook subprocess would resolve.
+"""
+
+from __future__ import annotations
+
+import json
+
+import pytest
+from click.testing import CliRunner
+
+from controlzero.cli.main import cli
+
+
+def _invoke(args, env=None, input=None):
+    # CliRunner version-portable: the `mix_stderr=False` parameter was
+    # removed in newer click releases. Tests instead use
+    # _extract_json() below to slice the JSON payload out of the
+    # combined output, ignoring any WARNING preamble from
+    # --show-secrets.
+    runner = CliRunner(env=env)
+    return runner.invoke(cli, ["env-dump", *args], input=input)
+
+
+def _extract_json(output: str) -> dict:
+    """Slice the JSON object out of mixed stdout/stderr output.
+
+    The env-dump JSON always starts with `{` on its own line and ends
+    with `}` on its own line; any WARNING prefix from --show-secrets
+    lives above. We grab from the first `{` to the last `}`.
+    """
+    start = output.find("{")
+    end = output.rfind("}")
+    if start < 0 or end < 0 or end < start:
+        raise AssertionError(f"no JSON envelope found in output: {output!r}")
+    return json.loads(output[start : end + 1])
+
+
+def test_env_dump_outputs_valid_json(monkeypatch):
+    monkeypatch.delenv("CONTROLZERO_CLIENT", raising=False)
+    result = _invoke([])
+    assert result.exit_code == 0, result.output
+    data = _extract_json(result.output)
+    assert "controlzero_version" in data
+    assert "hostname" in data
+    assert "api_url" in data
+    assert data["api_url"].startswith("http")
+    assert "adapter" in data
+    assert data["adapter"]["name"] in (
+        "claude_code",
+        "gemini_cli",
+        "codex_cli",
+        "unknown",
+    )
+    assert "env" in data
+    assert data["show_secrets"] is False
+
+
+def test_env_dump_redacts_api_key_by_default(monkeypatch):
+    monkeypatch.setenv(
+        "CONTROLZERO_API_KEY",
+        "cz_live_7ebef6b600015e3eaeda9149bf6d9c29a3a2a7a3075209112afde20888280de0",
+    )
+    result = _invoke([])
+    assert result.exit_code == 0
+    data = _extract_json(result.output)
+    masked = data["env"]["CONTROLZERO_API_KEY"]
+    assert masked == "cz_live_***"
+    # Defensive: the secret bytes MUST NOT appear anywhere in the dump.
+    secret_tail = "7ebef6b600015e3eaeda9149bf6d9c29a"
+    assert secret_tail not in result.output
+
+
+def test_env_dump_redacts_test_key_prefix(monkeypatch):
+    monkeypatch.setenv("CONTROLZERO_API_KEY", "cz_test_abcdef1234567890")
+    result = _invoke([])
+    data = _extract_json(result.output)
+    assert data["env"]["CONTROLZERO_API_KEY"] == "cz_test_***"
+
+
+def test_env_dump_redacts_generic_secret_envvars(monkeypatch):
+    monkeypatch.setenv("MY_SERVICE_TOKEN", "super-secret-value")
+    monkeypatch.setenv("DB_PASSWORD", "abc123")
+    monkeypatch.setenv("STRIPE_API_KEY", "sk_live_supersecret")
+    result = _invoke([])
+    data = _extract_json(result.output)
+    for k in ("MY_SERVICE_TOKEN", "DB_PASSWORD", "STRIPE_API_KEY"):
+        v = data["env"][k]
+        assert v.startswith("<REDACTED-LEN"), f"{k} not redacted: {v!r}"
+
+
+def test_env_dump_show_secrets_unredacts(monkeypatch):
+    monkeypatch.setenv("MY_SERVICE_TOKEN", "super-secret-value")
+    result = _invoke(["--show-secrets"])
+    data = _extract_json(result.output)
+    assert data["env"]["MY_SERVICE_TOKEN"] == "super-secret-value"
+    assert data["show_secrets"] is True
+    # Always-on warning when secrets are shown -- lives in stderr,
+    # NOT stdout (so a downstream `jq` pipe still works).
+    # WARNING goes to stderr but CliRunner mixes streams; the JSON
+    # extractor strips it from the parsed data, but it still shows
+    # in the combined `result.output` string.
+    assert "WARNING" in result.output
+
+
+def test_env_dump_from_hook_picks_right_adapter(monkeypatch):
+    monkeypatch.delenv("CONTROLZERO_CLIENT", raising=False)
+    monkeypatch.delenv("CLAUDECODE", raising=False)
+
+    # Claude Code's stdin signature:
+    payload = json.dumps({
+        "session_id": "01HX9Z6R3W6XAMPLE",
+        "transcript_path": "/Users/x/.claude/transcripts/abc.jsonl",
+        "cwd": "/Users/x/project",
+        "tool_name": "Write",
+        "tool_input": {"file_path": "/tmp/maruthi"},
+        "hook_event_name": "PreToolUse",
+    })
+    result = _invoke(["--from-hook"], input=payload)
+    assert result.exit_code == 0
+    data = _extract_json(result.output)
+    assert data["adapter"]["name"] == "claude_code"
+    assert "session_id" in data["from_hook_payload_keys"]
+    assert "tool_input" in data["from_hook_payload_keys"]
+
+
+def test_env_dump_lists_settings_files_without_revealing_contents(tmp_path, monkeypatch):
+    monkeypatch.setenv("HOME", str(tmp_path))
+    claude_settings = tmp_path / ".claude" / "settings.json"
+    claude_settings.parent.mkdir(parents=True)
+    claude_settings.write_text('{"hooks":{}}')
+
+    result = _invoke([])
+    data = _extract_json(result.output)
+    entry = data["files"].get(str(claude_settings))
+    assert entry is not None
+    assert entry["exists"] is True
+    assert entry["size_bytes"] > 0
+    assert "mtime_iso" in entry
+    # File CONTENTS must NOT be in the dump.
+    assert '"hooks":{}' not in result.output