controlzero 1.13.5__tar.gz → 1.13.7__tar.gz

{controlzero-1.13.5 → controlzero-1.13.7}/CHANGELOG.md

@@ -1,5 +1,56 @@
 # Changelog
 
+## 1.13.6 (2026-07-12): interpreter-pinned hook command (P0)
+
+### Fixed
+
+- **Claude Code / Gemini CLI / Codex CLI hook command is now interpreter-pinned,
+  not PATH-dependent (#1705, P0).** `controlzero install` wired the PreToolUse
+  hook as a bare `controlzero hook-check`; if a stale/older `controlzero`
+  binary (pre-`hook-check`) sat earlier on PATH than the interpreter that ran
+  install, the hook resolved to the wrong binary, errored with `invalid
+  choice: 'hook-check'`, and Claude Code HARD-BLOCKED every tool call. The
+  installer now writes `"<sys.executable>" -m controlzero hook-check` (the
+  same PATH-immune form #1265 shipped for Cursor / kiro-cli). The legacy bare
+  form is still recognised by hook-integrity / `verify` for back-compat, and
+  `verify` now WARNs (does not fail) when it finds a pre-#1705 bare command
+  still installed, recommending a re-`install` to migrate.
+
+## 1.13.5 (2026-07-06): HITL key-authed approval path + kiro-cli hook misattribution fix
+
+### Fixed
+
+- **SDK-driven HITL now works for key-authed agents (#1601, P0).**
+  `request_approval` POST `/api/approval-requests` and poll GET
+  `/api/approval-requests/{id}` sat under the browser/session `userAuth`
+  chain, so a `cz_live` API key got a 401 and HITL was non-functional for
+  real agents. Added a key-authed POST/GET `/v1/sdk/approval-requests`
+  surface (mirrors the already-working `/api/grants` precedent); org and
+  project resolve from the key, and the project is pinned to the key on
+  both create AND poll (an agent cannot target or read another project's
+  approval requests). The Python SDK now points at the key-authed path.
+- **E1709 leak-guard false-positive on ordinary English (#1601, P1).** The
+  entropy heuristic (`len>=24` + `entropy>3.5`) flagged plain text like the
+  default reason `"function requires approval"`, and
+  `enforce`/`guard_with_approval` swallowed the resulting
+  `SecretValueLeakInPayload` into a misleading `HITL_BACKEND_UNREACHABLE`
+  deny. The entropy heuristic is now gated on no-whitespace (a real
+  credential is a contiguous token), and the leak error propagates
+  distinctly instead of degrading to a backend-unreachable deny.
+- **Kiro CLI hooks misattributed to Codex CLI, mis-scoring the audit source
+  (#1655).** Kiro CLI is built on Codex and exports `CODEX_HOME`/
+  `CODEX_CLI`, so `CodexCLIAdapter.claim()` was winning on those env hints
+  before `KiroCLIAdapter` could check. `CodexCLIAdapter` now defers when
+  `hook_event_name` is a Kiro camelCase event (`preToolUse`, `postToolUse`,
+  `userPromptSubmit`, `agentSpawn`, `stop`) -- byte-disjoint from Codex's
+  PascalCase `PreToolUse`.
+- **Kiro IDE pre-tool-use hook UX.** The opaque "empty/unparseable IDE
+  payload; blocking" message now names the upstream bug (#7375/#7408/#7500),
+  explains the cause, and directs the user to disable the hook in Kiro IDE
+  Settings > Hooks. The shipped `ide-pre-tool-use.kiro.hook` template
+  name/description now leads with "[DO NOT ENABLE: blocks all tool calls]"
+  instead of burying the warning.
+
 ## 1.13.4 (2026-07-05): deny-wins fail-open fix (P0)
 
 ### Fixed

{controlzero-1.13.5 → controlzero-1.13.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: controlzero
-Version: 1.13.5
+Version: 1.13.7
 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: questionary<3,>=2.0.0
 Requires-Dist: rfc8785<0.2,>=0.1.4
 Requires-Dist: rich>=13.0.0
 Requires-Dist: zstandard>=0.23.0

{controlzero-1.13.5 → controlzero-1.13.7}/controlzero/__init__.py

@@ -41,7 +41,7 @@ from controlzero.hitl.grant_protocol import (
 from controlzero.policy_loader import load_policy
 from controlzero.secrets import SecretRef, SecretStr, secret_ref
 
-__version__ = "1.13.5"
+__version__ = "1.13.7"
 
 __all__ = [
     "Client",

{controlzero-1.13.5 → controlzero-1.13.7}/controlzero/audit_remote.py

@@ -18,6 +18,7 @@ Design constraints:
 """
 
 from __future__ import annotations
+from .hosted_policy import tls_verify
 
 import getpass
 import json
@@ -968,6 +969,7 @@ class RemoteAuditSink(_SpoolWiringMixin):
             content=body,
             headers=headers,
             timeout=FLUSH_TIMEOUT_S,
+            verify=tls_verify(),
         )
         if resp.status_code == 401:
             raise _AuthExpiredError("server returned 401")
@@ -1034,6 +1036,7 @@ class RemoteAuditSink(_SpoolWiringMixin):
                 content=body,
                 headers=headers,
                 timeout=FLUSH_TIMEOUT_S,
+                verify=tls_verify(),
             )
         return post
 
@@ -1192,6 +1195,7 @@ class BearerAuditSink(_SpoolWiringMixin):
             content=body,
             headers=headers,
             timeout=FLUSH_TIMEOUT_S,
+            verify=tls_verify(),
         )
         if resp.status_code == 401:
             raise _AuthExpiredError("server returned 401")
@@ -1244,6 +1248,7 @@ class BearerAuditSink(_SpoolWiringMixin):
                 content=body,
                 headers=headers,
                 timeout=FLUSH_TIMEOUT_S,
+                verify=tls_verify(),
             )
         return post
 

{controlzero-1.13.5 → controlzero-1.13.7}/controlzero/cli/enforcement.py

@@ -859,3 +859,34 @@ def installed_command(adapter: str, home: Optional[Path] = None, cwd: Optional[P
             return _first_cz_command(_load_json(settings), ("preToolUse",))
         return None
     return None
+
+
+# ---------------------------------------------------------------------------
+# Bare, PATH-shadowable hook command detection (#1705).
+# ---------------------------------------------------------------------------
+
+# Adapters whose installer now emits the interpreter-pinned
+# `"<sys.executable>" -m controlzero hook-check` form (#1705). A bare
+# `controlzero hook-check` found installed for one of these is either a
+# pre-#1705 install or a hand-edited config -- both are PATH-shadowable (a
+# stale/older `controlzero` earlier on PATH silently resolves instead of the
+# interpreter that ran install) and should be flagged so the operator
+# re-runs `controlzero install` to migrate. Cursor / Kiro CLI / Kiro v3
+# already pinned before #1705 (#1265); Antigravity intentionally still emits
+# the bare form and is not covered by this check.
+BARE_HOOK_COMMAND_ADAPTERS = ("claude_code", "gemini_cli", "codex_cli")
+
+# The literal bare command these adapters wrote before #1705.
+LEGACY_BARE_HOOK_CHECK_COMMAND = "controlzero hook-check"
+
+
+def is_bare_shadowable_hook_command(command: Optional[str]) -> bool:
+    """True if ``command`` is exactly the historical bare ``controlzero
+    hook-check`` form (#1705): PATH-dependent, so a stale/older
+    ``controlzero`` binary earlier on PATH can silently resolve instead of
+    the interpreter that ran install. The current installer emits the
+    interpreter-pinned ``"<sys.executable>" -m controlzero hook-check`` form
+    instead; this only flags configs that predate that fix (or were
+    hand-edited back to bare). ``None`` (no command installed) is not bare.
+    """
+    return command == LEGACY_BARE_HOOK_CHECK_COMMAND

{controlzero-1.13.5 → controlzero-1.13.7}/controlzero/cli/main.py

@@ -270,6 +270,43 @@ def init(template: str, out: str, force: bool):
     click.echo(f"  4. Use it in code: Client(policy_file='{out_path}')")
 
 
+@cli.command("setup", hidden=True)
+@click.option("--api-url", default=None,
+              help="Self-hosted / air-gap backend URL or host (e.g. https://cz.internal). "
+                   "Presence selects self-hosted mode; persisted to config.yaml.")
+@click.option("--api-key", default=None,
+              help="Control Zero API key (cz_live_/cz_test_). Env: CONTROLZERO_API_KEY.")
+@click.option("--agent", "agents", multiple=True,
+              help="Coding agent to wire (repeatable): claude-code, codex-cli, gemini-cli, "
+                   "kiro, cursor, antigravity. Env: CONTROLZERO_SETUP_AGENTS (comma list).")
+@click.option("--tls-ca-bundle", default=None,
+              help="CA bundle path for a self-signed air-gap endpoint. Persisted to config.")
+@click.option("--email", default=None, help="Your work email (Approvals attribution).")
+@click.option("--yes", "assume_yes", is_flag=True,
+              help="Non-interactive: resolve from flags/env, never prompt.")
+@click.pass_context
+def setup(ctx, api_url, api_key, agents, tls_ca_bundle, email, assume_yes):
+    """Guided onboarding: pick SaaS vs self-hosted, validate, wire agent hooks.
+
+    Interactive in a TTY; degrades to flags/env (exit 2 on missing input) in
+    CI/non-TTY. Hidden/beta -- existing install commands are unchanged.
+    """
+    from controlzero.cli.setup_wizard import Flags, run_setup
+
+    code = run_setup(
+        ctx,
+        Flags(
+            api_url=api_url,
+            api_key=api_key,
+            agents=tuple(agents),
+            tls_ca_bundle=tls_ca_bundle,
+            email=email,
+            assume_yes=assume_yes,
+        ),
+    )
+    sys.exit(code)
+
+
 @cli.command()
 @click.argument("policy_file", type=click.Path(exists=True), default="controlzero.yaml")
 def validate(policy_file: str):
@@ -1320,6 +1357,7 @@ def verify_cmd(as_json: bool, report: bool, prove: bool):
     if prove:
         sys.exit(_run_prove_enforcement(as_json))
 
+    from controlzero.cli import enforcement
     from controlzero.hook_integrity import (
         baseline_exists,
         check_hook_integrity,
@@ -1332,6 +1370,15 @@ def verify_cmd(as_json: bool, report: bool, prove: bool):
     has_baseline = baseline_exists(GLOBAL_POLICY_DIR)
     tamper = bool(hook_findings or env_findings)
 
+    # #1705: a bare, PATH-shadowable `controlzero hook-check` predates the
+    # interpreter-pinned fix (or was hand-edited back to bare). Not tamper --
+    # it is a recognised, working CZ hook -- so it does not affect `tamper` /
+    # the exit code, only surfaces as a WARN recommending re-install.
+    bare_adapters = [
+        a for a in enforcement.BARE_HOOK_COMMAND_ADAPTERS
+        if enforcement.is_bare_shadowable_hook_command(enforcement.installed_command(a))
+    ]
+
     if tamper and report:
         _report_hook_tamper(hook_findings, env_findings)
 
@@ -1342,6 +1389,7 @@ def verify_cmd(as_json: bool, report: bool, prove: bool):
             "baseline_tampered": integrity.baseline_tampered,
             "hook_findings": hook_findings,
             "env_findings": env_findings,
+            "bare_hook_command_adapters": bare_adapters,
         }, indent=2))
     else:
         click.echo("Control Zero tamper-resistance verify")
@@ -1364,6 +1412,14 @@ def verify_cmd(as_json: bool, report: bool, prove: bool):
                 click.echo(f"    - [env] {f['name']}: {f['reason']}")
         else:
             click.secho("  status           : OK (hooks intact)", fg="green")
+        for a in bare_adapters:
+            click.secho(
+                f"  ~ WARNING: {a} hook command is the bare, PATH-shadowable "
+                "'controlzero hook-check' form -- re-run `controlzero install "
+                f"{a.replace('_', '-')}` to migrate to the interpreter-pinned "
+                "form (#1705).",
+                fg="yellow",
+            )
 
     if not has_baseline:
         sys.exit(4)
@@ -1427,6 +1483,29 @@ _ANTIGRAVITY_PRETOOL_MATCHER = "*"     # agy special-cases "*" (NOT RE2-compiled
 _KIRO_POSTTOOL_MATCHER = "*"           # observe-only postToolUse match-all
 
 
+def _pinned_hook_check_command() -> str:
+    """Interpreter-pinned `controlzero hook-check` command for Claude Code /
+    Gemini CLI / Codex CLI (#1705).
+
+    A bare ``controlzero hook-check`` is PATH-dependent: the agent's hook
+    subshell resolves ``controlzero`` against ITS PATH at hook-execution time,
+    not against the interpreter that ran ``install``. If a stale/older
+    ``controlzero`` binary (one whose only subcommands are
+    ``setup``/``status``/``uninstall``, i.e. pre-``hook-check``) sits earlier
+    on PATH than the one installed into this interpreter's venv, the hook
+    resolves to the wrong binary, prints ``invalid choice: 'hook-check'``,
+    exits non-zero, and the agent HARD-BLOCKS every tool call -- bricking the
+    session. This actually happened (#1705).
+
+    Pinning ``sys.executable -m controlzero`` -- the same fix #1265 shipped
+    for Cursor / kiro-cli -- makes the agent invoke the EXACT interpreter that
+    ran install, which provably has ``hook-check``, regardless of PATH or venv
+    activation. Double-quoted so a space in the interpreter path survives
+    /bin/sh and cmd.exe.
+    """
+    return f'"{sys.executable}" -m controlzero hook-check'
+
+
 @cli.command("hook-check")
 @click.option(
     "--policy",
@@ -3566,6 +3645,45 @@ def _print_api_key_status(api_key: Optional[str]) -> None:
         click.echo("Tip: Pass --api-key cz_live_xxx to sync audit logs to the dashboard.")
 
 
+def _write_api_url_config(api_url: str) -> None:
+    """Persist ``api_url`` to ~/.controlzero/config.yaml (0600). The resolver
+    reads it (env > config > default), so a self-hosted / air-gap endpoint set
+    once at install reaches the agent hook WITHOUT exporting CONTROLZERO_API_URL
+    into every hook subprocess (the historical air-gap footgun). Scheme+host
+    only; the SDK strips a trailing slash and appends request paths itself."""
+    GLOBAL_POLICY_DIR.mkdir(parents=True, exist_ok=True)
+    try:
+        os.chmod(GLOBAL_POLICY_DIR, 0o700)
+    except OSError:
+        pass
+    config_data: dict = {}
+    if GLOBAL_CONFIG_PATH.exists():
+        try:
+            existing = yaml.safe_load(GLOBAL_CONFIG_PATH.read_text(encoding="utf-8"))
+            if isinstance(existing, dict):
+                config_data = existing
+        except Exception:  # noqa: BLE001
+            pass
+    config_data["api_url"] = api_url.rstrip("/")
+    GLOBAL_CONFIG_PATH.write_text(
+        yaml.safe_dump(config_data, default_flow_style=False),
+        encoding="utf-8",
+    )
+    try:
+        os.chmod(GLOBAL_CONFIG_PATH, 0o600)
+    except OSError:
+        pass
+
+
+def _api_url_install_callback(ctx, param, value):
+    """click callback for the shared --api-url install option. Persists the URL
+    at install time; expose_value=False keeps it off the command signature so no
+    install function needs an api_url parameter."""
+    if value:
+        _write_api_url_config(value)
+    return value
+
+
 def _bind_api_key_for_install(
     api_key: str,
     product: str,
@@ -3641,6 +3759,13 @@ def install():
     default=None,
     help="Your work email. Required for Approvals so the backend knows who's at the keyboard when the API key is shared across a team. Stored at ~/.controlzero/config.yaml.",
 )
+@click.option(
+    "--api-url",
+    default=None,
+    expose_value=False,
+    callback=_api_url_install_callback,
+    help="Base URL of a self-hosted / air-gap Control Zero backend (e.g. https://cz.internal). Persisted to ~/.controlzero/config.yaml so the hook targets it; overrides the SaaS default. env CONTROLZERO_API_URL still wins.",
+)
 def install_claude_code(force: bool, merge: bool, settings: Optional[str], api_key: Optional[str], email: Optional[str]):
     """Install controlzero as a Claude Code PreToolUse hook.
 
@@ -3736,7 +3861,10 @@ def install_claude_code(force: bool, merge: bool, settings: Optional[str], api_k
     # env-prefix was a Windows-portability bug (PowerShell / cmd.exe cannot
     # parse the syntax) AND placed the cleartext key into settings.json on
     # disk. Both go away here. See 2026-05-12 incident.
-    hook_command = "controlzero hook-check"
+    # Interpreter-pinned, not a bare `controlzero hook-check` -- see
+    # _pinned_hook_check_command() (#1705: a stale controlzero earlier on
+    # PATH otherwise hard-blocks every tool call).
+    hook_command = _pinned_hook_check_command()
     new_block = {
         "matcher": _CLAUDE_CODE_PRETOOL_MATCHER,
         "hooks": [
@@ -3828,6 +3956,13 @@ def install_claude_code(force: bool, merge: bool, settings: Optional[str], api_k
     default=None,
     help="Your work email. Required for Approvals so the backend knows who's at the keyboard when the API key is shared across a team.",
 )
+@click.option(
+    "--api-url",
+    default=None,
+    expose_value=False,
+    callback=_api_url_install_callback,
+    help="Base URL of a self-hosted / air-gap Control Zero backend (e.g. https://cz.internal). Persisted to ~/.controlzero/config.yaml so the hook targets it; overrides the SaaS default. env CONTROLZERO_API_URL still wins.",
+)
 def install_gemini_cli(force: bool, merge: bool, settings: Optional[str], api_key: Optional[str], email: Optional[str]):
     """Install controlzero as a Gemini CLI pre-tool-call hook.
 
@@ -3913,7 +4048,9 @@ def install_gemini_cli(force: bool, merge: bool, settings: Optional[str], api_ke
     # _write_api_key_config above). The legacy bash-only env-prefix
     # broke Windows; see the claude-code install path for the full
     # rationale.
-    hook_command = "controlzero hook-check"
+    # Interpreter-pinned, not a bare `controlzero hook-check` (#1705); see
+    # _pinned_hook_check_command().
+    hook_command = _pinned_hook_check_command()
 
     # Gemini CLI expects a nested structure:
     #   { matcher: "regex", hooks: [{ type: "command", command: "...", timeout: N }] }
@@ -4038,6 +4175,13 @@ def install_gemini_cli(force: bool, merge: bool, settings: Optional[str], api_ke
     default=None,
     help="Your work email. Required for Approvals so the backend knows who's at the keyboard when the API key is shared across a team.",
 )
+@click.option(
+    "--api-url",
+    default=None,
+    expose_value=False,
+    callback=_api_url_install_callback,
+    help="Base URL of a self-hosted / air-gap Control Zero backend (e.g. https://cz.internal). Persisted to ~/.controlzero/config.yaml so the hook targets it; overrides the SaaS default. env CONTROLZERO_API_URL still wins.",
+)
 def install_codex_cli(force: bool, merge: bool, config: Optional[str], api_key: Optional[str], email: Optional[str]):
     """Install controlzero as a Codex CLI tool approval hook.
 
@@ -4113,7 +4257,9 @@ def install_codex_cli(force: bool, merge: bool, config: Optional[str], api_key:
     # _write_api_key_config above). The legacy bash-only env-prefix
     # broke Windows; see the claude-code install path for the full
     # rationale.
-    hook_command = "controlzero hook-check"
+    # Interpreter-pinned, not a bare `controlzero hook-check` (#1705); see
+    # _pinned_hook_check_command().
+    hook_command = _pinned_hook_check_command()
 
     new_hook_entry = {
         "matcher": _CODEX_PRETOOL_MATCHER,
@@ -4571,6 +4717,13 @@ def _cursor_enforcement_probe(installed_cmd: str) -> tuple:
     help="Your work email. Required for Approvals so the backend knows who is "
     "at the keyboard when the API key is shared across a team.",
 )
+@click.option(
+    "--api-url",
+    default=None,
+    expose_value=False,
+    callback=_api_url_install_callback,
+    help="Base URL of a self-hosted / air-gap Control Zero backend (e.g. https://cz.internal). Persisted to ~/.controlzero/config.yaml so the hook targets it; overrides the SaaS default. env CONTROLZERO_API_URL still wins.",
+)
 def install_cursor(
     force: bool,
     merge: bool,
@@ -4785,6 +4938,13 @@ def install_cursor(
     default=None,
     help="Your work email. Required for Approvals so the backend knows who's at the keyboard when the API key is shared across a team.",
 )
+@click.option(
+    "--api-url",
+    default=None,
+    expose_value=False,
+    callback=_api_url_install_callback,
+    help="Base URL of a self-hosted / air-gap Control Zero backend (e.g. https://cz.internal). Persisted to ~/.controlzero/config.yaml so the hook targets it; overrides the SaaS default. env CONTROLZERO_API_URL still wins.",
+)
 def install_antigravity(
     force: bool,
     merge: bool,
@@ -6215,6 +6375,13 @@ def _run_kiro_uninstall(
     is_flag=True,
     help="Print what would change without writing anything to disk.",
 )
+@click.option(
+    "--api-url",
+    default=None,
+    expose_value=False,
+    callback=_api_url_install_callback,
+    help="Base URL of a self-hosted / air-gap Control Zero backend (e.g. https://cz.internal). Persisted to ~/.controlzero/config.yaml so the hook targets it; overrides the SaaS default. env CONTROLZERO_API_URL still wins.",
+)
 def install_kiro(
     surface: str,
     workspace: Optional[str],