controlzero 1.13.8__tar.gz → 1.13.9__tar.gz

{controlzero-1.13.8 → controlzero-1.13.9}/CHANGELOG.md

@@ -1,6 +1,50 @@
 # Changelog
 
-## 1.13.8 (2026-07-27): warn decisions reach the agent + Kiro IDE adapter unblocked (P0)
+## 1.13.9 (2026-07-28): Kiro IDE hooks execute on 1.0.x and stay in the correct project
+
+### Fixed
+
+- **Kiro IDE hooks no longer appear enabled while silently executing on
+  nothing on Kiro 1.0.x (#1952).** The installer now emits `preToolUse` and
+  `promptSubmit` hooks in the `.json` format read by Kiro's 1.0 hook loader,
+  while retaining the legacy hook files needed by older builds. It does not
+  dual-emit `fileEdited`, because both loaders can execute that event and
+  doing so would duplicate scans and audit rows. `promptSubmit` now actually
+  runs on current Kiro; `preToolUse` is installed in the working format but
+  remains disabled by its existing opt-in flag.
+- **Kiro payloads can no longer be claimed by the Claude Code adapter and
+  evaluated under the wrong project and DLP profile (#1945).** Kiro IDE 1.0+
+  and Kiro CLI v3 use PascalCase agent-harness events that overlap with Claude
+  Code. Kiro-specific payload signals now win routing, so attribution, API-key
+  selection, policy, and DLP configuration stay with the Kiro integration
+  instead of silently crossing tenants.
+- **An inherited `CONTROLZERO_CLIENT` can no longer redirect a Kiro IDE call
+  into another host's configuration (#1951).** The Kiro shim now pins its
+  client identity rather than preserving a value inherited from the launching
+  environment, preventing the same silent wrong-project and wrong-DLP-profile
+  outcome.
+- **A DLP mask match on a host that cannot rewrite tool input now tells the
+  agent what to fix (#1946).** The denial identifies the affected argument and
+  detector type without echoing the sensitive value, so the agent can retry
+  with the secret removed instead of dead-ending on a generic unsupported-mask
+  message.
+
+### Added
+
+- **`controlzero coverage` is generated from the adapters' declared
+  capabilities (#1947).** The CLI now exposes each host's enforcement tier,
+  deciding and observation events, argument delivery, rewrite support, and
+  known gaps from the same data used by adapter contracts.
+
+### Kiro IDE enforcement status
+
+Kiro IDE remains `tier=observe`; this release does **not** claim deterministic
+enforcement. It makes the enabled `promptSubmit` hook execute on Kiro 1.0.x and
+puts `preToolUse` one enable flag away from execution. Until that flag is
+enabled and the deterministic block path is verified end to end, the SDK's
+coverage declaration intentionally remains observe-only.
+
+## 1.13.8 (2026-07-27): warn decisions reach the agent + Kiro IDE adapter unblocked (P0)
 
 ### Added
 
@@ -214,7 +258,7 @@
   "cannot return rewritten tool arguments". **That was wrong**, and correcting
   it is why this paragraph exists (#202 no-false-claims):
 
-  | Host | Can rewrite tool input | Masking behaviour in 1.13.8 |
+  | Host | Can rewrite tool input | Masking behaviour in that release |
   | --- | --- | --- |
   | Claude Code | Yes -- `hookSpecificOutput.updatedInput` | **Masks and proceeds** |
   | Gemini CLI | Yes -- `hookSpecificOutput.tool_input` (BeforeTool) | **Masks and proceeds** |

{controlzero-1.13.8 → controlzero-1.13.9}/PKG-INFO

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

{controlzero-1.13.8 → controlzero-1.13.9}/controlzero/_internal/_messages.py

@@ -131,6 +131,51 @@ SYSTEM_MESSAGES: dict[str, dict[str, str]] = {
             "마스킹되지 않은 값을 전달하는 대신 차단합니다(기본 차단)."
         ),
     },
+    # DLP mask on a host whose hook protocol cannot accept rewritten tool input
+    # (every host except Claude Code + Gemini CLI). The mask escalates to a
+    # deny, and THIS is the text the model reads on that deny -- so it is
+    # written as an INSTRUCTION to the agent, not as a status line for a human.
+    # Goal: the agent re-issues the same call with the sensitive value removed,
+    # so the user's task completes in one extra round-trip instead of dead-
+    # ending. See controlzero/_internal/dlp_remediation.py.
+    #
+    # {findings} is TYPE + LOCATION only. It NEVER contains the detected value:
+    # echoing the secret into the model's context is the exact disclosure DLP
+    # exists to prevent (#1881, "PII never in cleartext").
+    #
+    # NO ``ko`` ENTRY, deliberately. The Korean pack is a professional draft
+    # pending customer review (see the module docstring), and an unreviewed
+    # machine translation of a SECURITY INSTRUCTION is worse than the English
+    # fallback -- a mistranslated "do not re-send the value" is a leak. Korean
+    # locales fall back to ``en``, which is exactly what they get today from the
+    # hard-coded English this replaces, so there is no regression to fix later.
+    "DLP_MASK_UNSUPPORTED:agent": {
+        "en": (
+            "Blocked: the tool arguments contain sensitive data, and this "
+            "agent host cannot accept redacted arguments, so the call was "
+            "blocked instead of masked. Findings: {findings}. To proceed, "
+            "retry the SAME call with the sensitive value removed -- refer to "
+            "it indirectly (an environment variable the tool expands, a "
+            "secret-manager reference, or a file path the tool reads) instead "
+            "of inlining it. Do not print, echo, restate, or re-send the value "
+            "in any form, including in a summary or an explanation."
+        ),
+    },
+    # Location-free fallback: a mask matched on the flattened argument text but
+    # no single argument leaf carries it (a pattern spanning the boundary
+    # between two concatenated values). Still actionable, just less precise.
+    "DLP_MASK_UNSUPPORTED:base": {
+        "en": (
+            "Blocked: the tool arguments contain sensitive data, and this "
+            "agent host cannot accept redacted arguments, so the call was "
+            "blocked instead of masked. To proceed, retry the SAME call with "
+            "the sensitive value removed -- refer to it indirectly (an "
+            "environment variable the tool expands, a secret-manager "
+            "reference, or a file path the tool reads) instead of inlining it. "
+            "Do not print, echo, restate, or re-send the value in any form, "
+            "including in a summary or an explanation."
+        ),
+    },
     # Tamper / quarantine (constructed in client.py + cli/main.py).
     "BUNDLE_TAMPERED": {
         "en": (

controlzero-1.13.9/controlzero/_internal/dlp_remediation.py

@@ -0,0 +1,245 @@
+"""Agent-actionable denial text for a DLP finding: TYPE + LOCATION, never VALUE.
+
+Why this module exists
+----------------------
+DLP can MASK a secret out of tool arguments, but only on hosts whose hook
+protocol accepts REWRITTEN tool input. Today that is Claude Code and Gemini CLI
+only (``CoverageDecl.can_rewrite_tool_input``); every other host -- Codex CLI,
+Cursor IDE, Cursor CLI, Kiro CLI, Kiro IDE, Antigravity, and the unknown-host
+fallback -- escalates a mask-rule match to a hard DENY.
+
+That deny used to say, in full:
+
+    DLP mask matched but this host cannot rewrite arguments
+
+which is true, actionable for nobody, and addressed to the wrong audience. The
+model that issued the call reads it, cannot tell WHICH argument tripped or WHAT
+it tripped on, and typically retries the identical call -- so the user's task
+dead-ends instead of completing.
+
+An **agent-actionable denial** closes that gap with no vendor change and no new
+config: the deny reason itself becomes an instruction precise enough that the
+model re-issues the SAME call with the sensitive value removed. One extra
+round-trip instead of a dead end. It works on every non-rewriting host because
+every one of them already routes ``decision.reason`` to a MODEL-visible field:
+
+===============  ==========================================================
+host             model-visible field carrying ``decision.reason``
+===============  ==========================================================
+codex_cli        ``hookSpecificOutput.permissionDecisionReason`` (+ stderr)
+cursor_ide       ``agent_message``
+cursor_cli       ``agent_message``
+kiro_cli         envelope ``reason`` + stderr (exit 2 sends stderr to the model)
+kiro_ide         envelope ``reason`` (v1 wraps hook output in ``<HOOK_INSTRUCTION>``)
+antigravity      envelope ``reason``
+unknown          envelope ``reason``
+===============  ==========================================================
+
+So NO adapter needed rewiring for this. The only thing that was missing was
+text worth putting in that channel.
+
+THE HARD CONSTRAINT
+-------------------
+**The message must NEVER contain the detected value.** Writing "found AWS key
+AKIA... at offset 34" would echo the secret straight into the model's context
+window -- which is the exact disclosure DLP exists to prevent, and a breach of
+the #1881 "PII never in cleartext" mandate. A deny that leaks the secret to the
+model is strictly worse than the uninformative deny it replaced.
+
+Findings are therefore described by TYPE (the rule's name + category, which are
+properties of the RULE definition, never of the matched bytes) and by LOCATION
+(the argument path). Nothing quotes, prefixes, suffixes, hashes-with-a-
+recoverable-prefix, or partially redacts the value; the value never enters this
+module's output by CONSTRUCTION, not by filtering -- there is no code path here
+that reads ``DLPMatch.matched_text``.
+
+The one value-derived input is an argument PATH SEGMENT: a dict KEY is attacker/
+model-controlled and could itself BE the secret (``{"AKIA...": "v"}``). That is
+the single echo route, and :func:`_safe_segment` closes it by scanning every
+segment and replacing any that matches a DLP rule with a fixed placeholder. It
+errs toward redacting (an all-caps key like ``ACCESSKEYID`` trips the SWIFT/BIC
+builtin and is redacted); losing a little location precision is the cheap side
+of that trade.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Optional
+
+from controlzero._internal._messages import system_message
+
+#: Placeholder for an argument-path segment that is ITSELF sensitive. A dict key
+#: is model-controlled, so ``{"AKIA...": "v"}`` would otherwise route the secret
+#: into the location clause. Value-free and fixed, exactly like the mask
+#: placeholder, so it can never carry a fragment of the original bytes.
+REDACTED_SEGMENT = "<redacted-key>"
+
+#: Path segment for a value that is not reachable by a name (a bare scalar
+#: passed as the whole argument object, or a leaf whose parents are all lists).
+ROOT_SEGMENT = "<tool arguments>"
+
+#: Cap on how many findings are enumerated. A pathological call can match
+#: hundreds of spans; an unbounded list would bury the instruction it exists to
+#: deliver and burn the model's context. The remainder is reported as a count.
+MAX_LISTED_FINDINGS = 5
+
+#: Cap on a rendered argument path. Deeply nested payloads produce long paths
+#: that add no actionable precision past a point.
+MAX_PATH_CHARS = 120
+
+
+@dataclass(frozen=True)
+class ArgFinding:
+    """One sensitive span, described by WHERE it is and WHAT KIND it is.
+
+    Deliberately carries no field that could hold the matched bytes. Adding one
+    would defeat the whole point of this module, so the dataclass shape is the
+    enforcement: there is nowhere for a value to live.
+    """
+
+    arg_path: str
+    rule_name: str
+    category: str
+
+
+def _safe_segment(scanner: Any, segment: str) -> str:
+    """Return ``segment`` unless the segment TEXT is itself sensitive.
+
+    A dict key comes from the model's own tool call, so it can be the secret
+    (``{"ghp_...": "note"}``). Scanning the segment and substituting a fixed
+    placeholder is what stops the location clause from becoming the leak.
+    """
+    if not segment:
+        return ROOT_SEGMENT
+    try:
+        if scanner.scan(segment):
+            return REDACTED_SEGMENT
+    except Exception:  # pragma: no cover - a scanner fault must not leak
+        # Fail toward redaction: if we cannot prove the segment is clean, do not
+        # print it. This branch mirrors the module-wide asymmetry -- an
+        # imprecise location costs a little usefulness, an echoed secret costs
+        # everything.
+        return REDACTED_SEGMENT
+    return segment
+
+
+def _join(parent: str, child: str) -> str:
+    return f"{parent}.{child}" if parent else child
+
+
+def _walk(
+    scanner: Any,
+    obj: Any,
+    path: str,
+    actions: frozenset,
+    out: list,
+    seen: set,
+) -> None:
+    """Collect ``ArgFinding`` per LEAF so each finding has a real location.
+
+    Per-leaf, not over the flattened blob ``extract_text_from_args`` produces:
+    the flat text's offsets do not map back to an argument, and "somewhere in
+    your arguments" is not a location the model can act on.
+    """
+    if isinstance(obj, dict):
+        for key, value in obj.items():
+            _walk(scanner, value, _join(path, _safe_segment(scanner, str(key))), actions, out, seen)
+        return
+    if isinstance(obj, (list, tuple)):
+        for index, item in enumerate(obj):
+            _walk(scanner, item, f"{path}[{index}]" if path else f"[{index}]", actions, out, seen)
+        return
+    if obj is None:
+        return
+    if isinstance(obj, str):
+        text = obj
+    elif isinstance(obj, (int, float, bool)):
+        # Scanned as text for the same reason the masker stringifies scalars:
+        # a Korean card / RRN / account number frequently arrives as a JSON
+        # NUMBER, and skipping it here would report no location for a finding
+        # the engine already decided to block on.
+        text = str(obj)
+    else:
+        return
+
+    location = path or ROOT_SEGMENT
+    if len(location) > MAX_PATH_CHARS:
+        location = location[:MAX_PATH_CHARS] + "..."
+
+    for match in scanner.scan(text):
+        if match.action not in actions:
+            continue
+        # One line per (location, rule) pair. Ten hits of the same rule in one
+        # argument is one instruction, not ten.
+        key = (location, match.rule_id)
+        if key in seen:
+            continue
+        seen.add(key)
+        out.append(
+            ArgFinding(
+                arg_path=location,
+                rule_name=match.rule_name,
+                category=match.category,
+            )
+        )
+
+
+def locate_findings(
+    scanner: Any,
+    args: Any,
+    *,
+    actions: frozenset = frozenset({"mask"}),
+) -> list:
+    """Describe every ``actions`` match in ``args`` by location + type.
+
+    ``actions`` is a NAMED POSITIVE SET, not a negation of something else, per
+    the CLAUDE.md controls mandate: a future DLP action lands OUTSIDE it and is
+    simply not described, rather than being silently swept in by an ``!=``.
+    """
+    out: list = []
+    seen: set = set()
+    _walk(scanner, args, "", actions, out, seen)
+    return out
+
+
+def _describe(findings: list) -> str:
+    """Render the findings clause. TYPE + LOCATION only -- never the value."""
+    clauses = [
+        f'argument "{f.arg_path}" contains a value matching the '
+        f'"{f.rule_name}" {f.category} detector'
+        for f in findings[:MAX_LISTED_FINDINGS]
+    ]
+    overflow = len(findings) - len(clauses)
+    if overflow > 0:
+        clauses.append(f"and {overflow} further match(es) in other arguments")
+    return "; ".join(clauses)
+
+
+def agent_remediation_message(
+    scanner: Any,
+    args: Any,
+    *,
+    actions: frozenset = frozenset({"mask"}),
+    locale: Optional[str] = None,
+) -> str:
+    """The deny reason handed to the MODEL on a non-rewriting host.
+
+    THE single helper this module exists to provide. Returns text that names
+    what was found and where, and tells the agent what to do next -- and that,
+    by construction, cannot contain the detected value.
+
+    Falls back to the location-free base message when nothing could be located
+    (e.g. a match that only exists across the boundary between two concatenated
+    arguments, so no single leaf carries it). Less useful, still never wrong,
+    and never a crash on the deny path.
+    """
+    findings = locate_findings(scanner, args, actions=actions)
+    key = "DLP_MASK_UNSUPPORTED:agent" if findings else "DLP_MASK_UNSUPPORTED:base"
+    message = system_message(key, locale, findings=_describe(findings))
+    # system_message returns None only for an unknown key. Both keys above are
+    # in the pack and the pack is pinned by tests, but the deny path must not
+    # raise, so a missing entry degrades to the legacy text rather than a
+    # traceback that would fail the hook open on hosts that read a crash as a
+    # pass.
+    return message or "DLP mask matched but this host cannot rewrite arguments"

{controlzero-1.13.8 → controlzero-1.13.9}/controlzero/_internal/enforcer.py

@@ -27,6 +27,7 @@ from controlzero._internal._messages import (
     resolve_locale,
     system_message,
 )
+from controlzero._internal.dlp_remediation import agent_remediation_message
 from controlzero._internal.dlp_scanner import (
     DLPScanner,
     extract_text_from_args,
@@ -1386,7 +1387,30 @@ class PolicyEvaluator:
                         "host_cannot_rewrite_arguments",
                     ),
                     policy_id=decision.policy_id,
-                    reason="DLP mask matched but this host cannot rewrite arguments",
+                    # AGENT-ACTIONABLE DENIAL. This deny's reason is routed to a
+                    # MODEL-visible field by every non-rewriting host (Codex's
+                    # permissionDecisionReason, Cursor's agent_message, the
+                    # Kiro / Antigravity / unknown envelope `reason`, plus
+                    # stderr), so it is the one channel that can get the user's
+                    # task unblocked without a vendor change: name the argument
+                    # and the detector precisely enough that the model re-issues
+                    # the SAME call with the secret removed.
+                    #
+                    # The legacy text ("DLP mask matched but this host cannot
+                    # rewrite arguments") was true and useless -- the model
+                    # could not tell WHICH argument tripped or WHAT on, so it
+                    # retried the identical call and the task dead-ended.
+                    #
+                    # TYPE + LOCATION only. The message can never carry the
+                    # detected value: echoing it here would put the secret in
+                    # the model's context window, which is the precise
+                    # disclosure this control exists to prevent. Enforced by
+                    # construction in dlp_remediation (nothing there reads
+                    # matched_text) and pinned by
+                    # tests/test_dlp_agent_remediation_1938.py.
+                    reason=agent_remediation_message(
+                        self._dlp_scanner, args, locale=self._locale
+                    ),
                     reason_code=REASON_CODE_DLP_BLOCKED,
                     evaluated_rules=decision.evaluated_rules,
                     dlp_findings=self._dlp_scanner.get_findings_for_audit(mask_matches),

{controlzero-1.13.8 → controlzero-1.13.9}/controlzero/cli/enforcement.py

@@ -149,7 +149,30 @@ ADAPTER_CONTRACTS: dict[str, AdapterContract] = {
         match_all_tokens=("*",),
         # preToolUse matchers are canonical tool names that MUST self-match.
         installer_matchers=("execute_bash", "fs_write", "fs_read", "use_aws"),
-        tested_agent_versions=">=1.23.0",
+        # This contract describes the **Kiro CLI** surface only (note
+        # ``version_command`` below is ``kiro-cli --version``); KiroIDEAdapter
+        # is versioned on a different scheme entirely and is NOT reconciled
+        # here -- see hosts/kiro.py.
+        #
+        # Was ">=1.23.0", a stale Amazon-Q-era claim: kiro-cli reported 1.x
+        # when this fixture was written (the fixture's own ``version_detect``
+        # note still said "kiro-cli is 1.x (rebranded Amazon Q), NOT 2.8.x").
+        # kiro-cli has since renumbered to 2.x -- the binary installed for
+        # verification reports ``kiro-cli 2.14.2``. The old range only kept
+        # producing a "tested" label at line ~483 by semver accident
+        # (2.14.2 >= 1.23.0), not because 1.23.0 means anything today.
+        #
+        # Floor 2.1.0: first build where preToolUse hooks fire at all
+        # (kirodotdev/Kiro#7697). Ceiling <3.0.0: bounds the 2.x binary major.
+        #
+        # CAVEAT, stated because the version range CANNOT enforce it: Kiro
+        # "CLI v3" is not a 3.x release -- it ships INSIDE the 2.x binary
+        # behind ``kiro-cli --v3`` (kiro.dev/docs/cli/v3.md: "V3 runs
+        # alongside your existing 2.x install"), and it changes the hook
+        # contract to PascalCase standalone files. So a --v3 run still reports
+        # 2.14.2 and still lands inside this range. Surface separation is done
+        # by payload signature in hosts/kiro.py, never by this string.
+        tested_agent_versions=">=2.1.0,<3.0.0",
         sdk_min_core_version="1.9.0",
         block_mechanism="exit_code",
         version_command=("kiro-cli", "--version"),

{controlzero-1.13.8 → controlzero-1.13.9}/controlzero/cli/hosts/claude_code.py

@@ -45,6 +45,7 @@ from __future__ import annotations
 from collections.abc import Mapping
 
 from controlzero.cli.hosts.base import CoverageDecl, CZDecision, HostAdapter
+from controlzero.cli.hosts.kiro import is_kiro_agent_payload
 
 # CONTROLZERO_CLIENT values that pin THIS adapter. A non-empty pin that is NOT
 # one of these means a different host was pinned -> this adapter must DEFER
@@ -131,6 +132,26 @@ class ClaudeCodeAdapter(HostAdapter):
             if env.get(hint):
                 return True
 
+        # Disambiguation #2: Kiro IDE 1.0+ / Kiro CLI v3 run the shared Kiro
+        # Agent Server harness, which emits PascalCase ``hook_event_name``
+        # ("PreToolUse") on stdin -- the same names Claude Code uses. Claude
+        # sits FIRST in the REGISTRY, so without this defer a Kiro
+        # agent-harness call is claimed here. The block would still land (both
+        # hosts exit 2), which is what makes it dangerous: the surface looks
+        # healthy while the audit SOURCE says claude_code and the per-agent
+        # config resolves under ~/.controlzero/integrations/claude_code/ --
+        # the WRONG project + DLP profile, silently.
+        #
+        # This runs AFTER the Anthropic env-hint check above, deliberately: an
+        # ambient CLAUDECODE is a positive Claude signal and must keep winning
+        # (Windows detection leans on it). ``is_kiro_agent_payload`` only
+        # claims a shared PreToolUse/PostToolUse name when ``transcript_path``
+        # is absent, and Claude Code always sends it -- so a genuine Claude
+        # payload is never deferred. See kiro.py for the verified payload
+        # shape and its vendor-source citation.
+        if is_kiro_agent_payload(payload):
+            return False
+
         # Stdin payload signature: PreToolUse always carries
         # ``hook_event_name`` (post-2024-10 schema) OR a
         # ``session_id`` + ``transcript_path`` + ``tool_input``