controlzero 1.13.1__tar.gz → 1.13.2__tar.gz

{controlzero-1.13.1 → controlzero-1.13.2}/CHANGELOG.md

@@ -1,5 +1,30 @@
 # Changelog
 
+## 1.13.2 (2026-06-28): kiro-cli 2.10 install crash + cross-adapter hook hardening
+
+### Fixed
+
+- **kiro-cli Windows / non-UTF-8 install crash (Ken Lee report).** `controlzero
+  kiro init` captured kiro-cli's output in text mode using the OS locale codec, so
+  kiro-cli's UTF-8 output crashed the install's subprocess reader thread on
+  non-UTF-8 Windows locales (Korean CP949, Japanese SJIS, Chinese GBK). That crash
+  could leave the governance agent not set as default, so `kiro-cli chat` then ran
+  the built-in default agent ungoverned (no hooks, no audit). All kiro-cli
+  shell-outs now decode as UTF-8 (`errors="replace"`) and never crash the install.
+- **Codex hook-trust requirement surfaced at install.** Codex trust-gates the
+  non-managed `~/.codex/hooks.json` by hash and SKIPS it until trusted; the
+  installer now prints a loud ACTION-REQUIRED step (run `/hooks`, trust the Control
+  Zero hook, re-trust after every upgrade) instead of implying it enforces.
+- **Gemini defensive hooks gate.** The installer writes `hooksConfig.enabled=true`
+  so an admin/older build with hooks gated off does not silently run ungoverned.
+
+### Notes
+
+- kiro-cli 2.10 was verified live to FIRE embedded agent-config `preToolUse` hooks;
+  the canonical tool-name matchers (`execute_bash`/`fs_write`/`fs_read`/`use_aws`)
+  and the `"*"` all-tools token are correct on 2.10 (both new `shell` and legacy
+  `execute_bash` names match).
+
 ## 1.13.1 (2026-06-27): shell semantic-class enforcement
 
 ### Added

{controlzero-1.13.1 → controlzero-1.13.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: controlzero
-Version: 1.13.1
+Version: 1.13.2
 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.13.1 → controlzero-1.13.2}/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.1"
+__version__ = "1.13.2"
 
 __all__ = [
     "Client",

{controlzero-1.13.1 → controlzero-1.13.2}/controlzero/cli/main.py

@@ -3737,12 +3737,30 @@ def install_gemini_cli(force: bool, merge: bool, settings: Optional[str], api_ke
     ]
     before_tool.append(new_block)
 
+    # Defensive gate (cross-adapter drift audit, 2026-06-28): the Gemini CLI
+    # hooks subsystem is gated by hooksConfig.enabled. It defaults to true on
+    # current builds, but an admin policy or an older/disabled build can leave
+    # it off -- in which case our BeforeTool hook is silently never invoked
+    # (enforcement off, verify still green). Write the gate explicitly and make
+    # sure our hook is not in hooksConfig.disabled. Writing an unknown key is a
+    # harmless no-op on builds that do not read it, so this only ever helps.
+    hooks_config = existing.get("hooksConfig")
+    if not isinstance(hooks_config, dict):
+        hooks_config = {}
+        existing["hooksConfig"] = hooks_config
+    hooks_config["enabled"] = True
+    disabled = hooks_config.get("disabled")
+    if isinstance(disabled, list):
+        hooks_config["disabled"] = [
+            d for d in disabled if "controlzero" not in str(d)
+        ]
+
     settings_path.write_text(
         json.dumps(existing, indent=2) + "\n",
         encoding="utf-8",
     )
     _record_hook_baseline(settings_path)
-    click.echo(f"Updated {settings_path} (added BeforeTool hook)")
+    click.echo(f"Updated {settings_path} (added BeforeTool hook + hooksConfig.enabled)")
     click.echo("")
     click.echo("[Control Zero] Installed successfully.")
     click.echo("")
@@ -3972,13 +3990,26 @@ def install_codex_cli(force: bool, merge: bool, config: Optional[str], api_key:
     click.echo("")
     click.echo("[Control Zero] Installed successfully.")
     click.echo("")
+    # Codex trust-gates command hooks BY HASH: ~/.codex/hooks.json is a
+    # NON-managed hook, so Codex marks it "for review" and SKIPS it until the
+    # user trusts it -- until then NO tool call is governed (enforcement is
+    # silently OFF), and it re-locks on every upgrade that changes the hook
+    # command/hash. This is the #1 silent-non-enforcement trap on Codex, so
+    # surface it loudly. (developers.openai.com/codex/hooks; openai/codex#27833.)
+    click.echo("[Control Zero] ACTION REQUIRED -- trust the hook or it will NOT run:")
+    click.echo("  1. Open Codex:  codex")
+    click.echo("  2. Run  /hooks  and TRUST the Control Zero PreToolUse hook.")
+    click.echo("     Until trusted, Codex SKIPS the hook and tools run UNGOVERNED.")
+    click.echo("  3. Re-trust after every Control Zero upgrade (the hook hash changes).")
+    click.echo("")
     _print_posture_summary(hosted, "codex-cli", posture_default_action, posture_rule_count)
     if not hosted:
         click.echo("")
-        click.echo("Test it:")
-        click.echo("  1. Open Codex CLI in any project: codex")
-        click.echo("  2. Every tool call will show '[Control Zero] Allowed: <tool>'")
-        click.echo("  3. Add deny rules, then watch blocked tools show '[Control Zero] <reason>'")
+        click.echo("Verify it ACTUALLY enforces (not just installed):")
+        click.echo("  1. In Codex, after trusting the hook, add a deny rule and try that tool.")
+        click.echo("  2. A governed call shows '[Control Zero] Allowed: <tool>'; a blocked one")
+        click.echo("     shows '[Control Zero] <reason>'. If you see NEITHER, the hook is")
+        click.echo("     untrusted/skipped -- re-run /hooks and trust it.")
         click.echo("")
         click.echo(f"Edit your policy: {GLOBAL_POLICY_PATH}")
     click.echo(f"Audit log:        {GLOBAL_AUDIT_PATH}")
@@ -4315,6 +4346,8 @@ def _cursor_enforcement_probe(installed_cmd: str) -> tuple:
                 shell=True,
                 input=json.dumps(payload),
                 text=True,
+                encoding="utf-8",
+                errors="replace",
                 capture_output=True,
                 env=probe_env,
                 timeout=15,
@@ -5241,9 +5274,19 @@ _KIRO_V3_AGENT_NAME = "controlzero"
 _KIRO_V3_AGENT_DESCRIPTION = "Control Zero governance"
 # kiro-cli's built-in default agent -- what the default is restored to on uninstall.
 _KIRO_V3_BUILTIN_DEFAULT_AGENT = "kiro_default"
-# Internal Kiro tool names for the BLOCKING preToolUse trigger. NOT "*"/"shell":
-# execute_bash (shell), fs_write (write/edit/delete), fs_read (read/list/search),
-# use_aws (aws cli). postToolUse is observe-only so it uses a "*" catch-all.
+# Internal Kiro tool names for the BLOCKING preToolUse trigger. The matcher is
+# evaluated against kiro-cli's CANONICAL internal tool names (execute_bash /
+# fs_write / fs_read / use_aws); kiro normalizes the simplified aliases
+# (shell / write / read / aws) to these, so the canonical matchers fire on every
+# kiro-cli version (verified against current kiro docs + #4810/#4867 by the
+# 2026-06-28 cross-adapter drift audit). postToolUse is observe-only and uses
+# the documented "*" all-tools token. Pinned by
+# tests/test_kiro_cli_v210_hooks.py -- do NOT rewrite into a "shell|..."
+# alternation on the belief a tool rename broke them: it did not.
+#
+# NOTE: the Ken Lee kiro-cli 2.10 hooks-not-firing report is a SEPARATE issue
+# (install-time encoding/locale + the Kiro IDE >=1.0.0 legacy-schema drift),
+# NOT a preToolUse tool-name rename. Do not conflate.
 _KIRO_V3_PRE_TOOL_MATCHERS = ("execute_bash", "fs_write", "fs_read", "use_aws")
 
 
@@ -5290,9 +5333,21 @@ def _kiro_v3_set_default_agent(agent_name: str) -> tuple:
             ["kiro-cli", "agent", "set-default", agent_name],
             capture_output=True,
             text=True,
+            # Decode kiro-cli's UTF-8 output as UTF-8, NOT the OS locale codec.
+            # Without this, text=True uses locale.getpreferredencoding() -- e.g.
+            # CP949 on Korean Windows, SJIS on Japanese, GBK on Chinese -- and
+            # kiro-cli's em-dash/arrow output (byte 0xe2...) crashes the
+            # subprocess reader thread (UnicodeDecodeError). errors="replace"
+            # keeps any stray non-UTF-8 byte from ever crashing the install.
+            encoding="utf-8",
+            errors="replace",
             timeout=15,
         )
-    except (OSError, subprocess.SubprocessError) as e:
+    # Honor the "NEVER raises" contract: a best-effort kiro-cli shell-out must
+    # not crash `kiro init`. OSError/SubprocessError cover absent/failed
+    # kiro-cli; the broad guard also covers a decode/runtime surprise so the
+    # caller can turn it into a loud WARNING instead of a traceback.
+    except Exception as e:  # noqa: BLE001 -- best-effort, see docstring
         return False, str(e)
     detail = ((proc.stdout or "") + (proc.stderr or "")).strip()
     return proc.returncode == 0, detail
@@ -5319,9 +5374,14 @@ def _kiro_v3_create_agent_from_default() -> tuple:
             ],
             capture_output=True,
             text=True,
+            # See _kiro_v3_set_default_agent: decode as UTF-8 (not the OS locale
+            # codec) so non-ASCII kiro-cli output cannot crash the install on
+            # CP949/SJIS/GBK Windows.
+            encoding="utf-8",
+            errors="replace",
             timeout=15,
         )
-    except (OSError, subprocess.SubprocessError) as e:
+    except Exception as e:  # noqa: BLE001 -- best-effort, NEVER raises (docstring)
         return False, str(e)
     detail = ((proc.stdout or "") + (proc.stderr or "")).strip()
     return proc.returncode == 0, detail
@@ -6005,6 +6065,8 @@ def _kiro_cli_enforcement_probe(installed_cmd: str) -> tuple:
                 shell=True,
                 input=json.dumps(payload),
                 text=True,
+                encoding="utf-8",
+                errors="replace",
                 capture_output=True,
                 env=probe_env,
                 timeout=15,
@@ -6169,6 +6231,8 @@ def kiro_verify(settings: Optional[str]) -> None:
                     shell=True,
                     input=json.dumps(payload),
                     text=True,
+                    encoding="utf-8",
+                    errors="replace",
                     capture_output=True,
                     env=env,
                 )
@@ -6178,6 +6242,8 @@ def kiro_verify(settings: Optional[str]) -> None:
                      "--policy", str(pol)],
                     input=json.dumps(payload),
                     text=True,
+                    encoding="utf-8",
+                    errors="replace",
                     capture_output=True,
                     env=env,
                 )

{controlzero-1.13.1 → controlzero-1.13.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "controlzero"
-version = "1.13.1"
+version = "1.13.2"
 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.13.2/tests/test_kiro_cli_v210_hooks.py

@@ -0,0 +1,110 @@
+"""Regression tests for the kiro-cli install hardening (Ken Lee, 2026-06-28).
+
+The Ken Lee kiro-cli 2.10 report had TWO themes; this file guards the part that
+is a confirmed, code-level defect: the CP949 / locale ENCODING crash. The
+2026-06-28 cross-adapter drift audit verified the preToolUse MATCHERS were NOT
+the cause (kiro normalizes the simplified tool aliases shell/write/read/aws to
+the canonical names execute_bash/fs_write/fs_read/use_aws, so the canonical
+matchers fire on every kiro-cli version -- kiro #4810/#4867). These tests pin
+the canonical matchers so they are never "fixed" into an alias alternation, and
+guard the encoding fix.
+
+ENCODING bug: the kiro-cli shell-outs captured output in text mode using the OS
+locale codec, so kiro-cli's UTF-8 output (em-dash / arrow, byte 0xe2...) crashed
+the subprocess reader thread on non-UTF-8 Windows locales (Korean CP949,
+Japanese SJIS, Chinese GBK). All kiro-cli shell-outs now decode as
+encoding="utf-8", errors="replace" and honor the "NEVER raises" contract.
+"""
+
+import re
+import subprocess
+
+from controlzero.cli import main as m
+
+
+# ---------------------------------------------------------------------------
+# Matchers: pin the canonical set (audit-verified correct) so it is never
+# rewritten into an alias alternation on a mistaken "rename broke it" belief.
+# ---------------------------------------------------------------------------
+def test_pretooluse_matchers_are_the_canonical_kiro_tool_names():
+    assert m._KIRO_V3_PRE_TOOL_MATCHERS == (
+        "execute_bash",
+        "fs_write",
+        "fs_read",
+        "use_aws",
+    )
+
+
+def test_pretooluse_matchers_are_valid_regex_and_match_their_canonical_tool():
+    """Each canonical matcher is a valid regex (a malformed matcher silently
+    never fires) and matches its own tool name."""
+    for tool in m._KIRO_V3_PRE_TOOL_MATCHERS:
+        re.compile(tool)  # raises re.error if invalid
+        assert re.search(tool, tool)
+
+
+def test_posttooluse_uses_the_documented_all_tools_token():
+    """postToolUse is observe-only and uses kiro's documented "*" all-tools
+    token (special-cased by kiro, not a raw regex)."""
+    hooks = m._kiro_v3_canonical_hooks()
+    assert hooks["postToolUse"][0]["matcher"] == "*"
+    # preToolUse entries are the canonical names.
+    pre_matchers = [h["matcher"] for h in hooks["preToolUse"]]
+    assert pre_matchers == list(m._KIRO_V3_PRE_TOOL_MATCHERS)
+
+
+# ---------------------------------------------------------------------------
+# Encoding: kiro-cli shell-outs decode as UTF-8 and never crash the install.
+# ---------------------------------------------------------------------------
+def test_set_default_agent_decodes_utf8_not_locale_codec(monkeypatch):
+    """encoding='utf-8', errors='replace' so kiro-cli's non-ASCII output cannot
+    crash the reader thread on CP949/SJIS/GBK Windows."""
+    seen = {}
+
+    class FakeProc:
+        returncode = 0
+        stdout = "set-default ok"
+        stderr = ""
+
+    def fake_run(*args, **kwargs):
+        seen.update(kwargs)
+        return FakeProc()
+
+    monkeypatch.setattr(subprocess, "run", fake_run)
+    ok, _detail = m._kiro_v3_set_default_agent("controlzero")
+    assert ok is True
+    assert seen.get("encoding") == "utf-8"
+    assert seen.get("errors") == "replace"
+
+
+def test_create_agent_from_default_decodes_utf8(monkeypatch):
+    seen = {}
+
+    class FakeProc:
+        returncode = 0
+        stdout = ""
+        stderr = ""
+
+    def fake_run(*args, **kwargs):
+        seen.update(kwargs)
+        return FakeProc()
+
+    monkeypatch.setattr(subprocess, "run", fake_run)
+    ok, _detail = m._kiro_v3_create_agent_from_default()
+    assert ok is True
+    assert seen.get("encoding") == "utf-8"
+    assert seen.get("errors") == "replace"
+
+
+def test_set_default_agent_never_raises_on_any_subprocess_error(monkeypatch):
+    """The 'NEVER raises' contract: a decode/runtime surprise must become a
+    (False, detail) the caller turns into a loud WARNING, not a traceback that
+    aborts `kiro init` (the Thread-2 _readerthread crash Ken saw)."""
+
+    def boom(*args, **kwargs):
+        raise UnicodeDecodeError("cp949", b"\xe2", 0, 1, "illegal multibyte sequence")
+
+    monkeypatch.setattr(subprocess, "run", boom)
+    ok, detail = m._kiro_v3_set_default_agent("controlzero")
+    assert ok is False
+    assert detail  # carries the error string for the WARNING