controlzero 1.11.9__tar.gz → 1.13.0__tar.gz

{controlzero-1.11.9 → controlzero-1.13.0}/CHANGELOG.md

@@ -1,5 +1,73 @@
 # Changelog
 
+## 1.13.0 (2026-06-26): policy-condition operator vocab
+
+### Added
+
+- **Condition operators.** A rule condition value may now be a tagged envelope
+  `{op, value}` honoring a closed operator set: `equals`, `contains`, `glob`,
+  `matches` (regex, BETA), `gt`/`lt`/`gte`/`lte`, `in`/`not_in`,
+  `in_range`/`outside_range`, `exists`/`not_exists`. Read-only aliases
+  `matches_pattern`/`greater_than`/`less_than` are canonicalized on load, so
+  existing dashboard templates work with zero migration. A legacy scalar value
+  (a plain string or number) keeps its prior glob/equals behavior exactly, so
+  existing policies and signed bundles evaluate unchanged.
+- **File-path conditions.** `file_path` / `path` / `notebook_path` now feed the
+  `input_text` condition value, so a condition like "input_text contains .env"
+  fires on Read/Write/Edit tool calls.
+
+### Notes
+
+- Fail-closed: a missing field is no-match for every operator except
+  `exists`/`not_exists`; an unknown operator is rejected at load; a malformed
+  condition fails closed. `matches` is BETA and length-capped to bound regex
+  backtracking. Secret detection stays on the DLP scanner, not a regex condition.
+
+## 1.12.1 (2026-06-26): deny rules actually deny
+
+### Fixed
+
+- **Deny rules now actually deny (#1011).** A policy DENY rule with a condition
+  (e.g. "block Bash when the command contains rm -rf") could silently fail to
+  match, so the action ran anyway. Reconciled the rule-authoring vocabulary with
+  the engine: tool names match case-insensitively (a rule for `bash:*` catches
+  the canonical `Bash:rm`), the command text is matched as `input_text` by
+  CONTAINS, and conditions are no longer dropped when a hosted policy is
+  translated for local enforcement. A present-but-malformed condition now fails
+  closed at load instead of silently becoming an unconditional allow.
+
+## 1.12.0 -- 2026-06-25 (per-agent key authority + per-agent bundle cache + whoami)
+
+### Added
+
+- **`controlzero whoami`.** Prints which API key the SDK will actually use for a
+  surface (per-agent / env / global), its prefix only (never the full key), and
+  the project + org it resolves to. Diagnoses the most common "my audit logs are
+  missing" cause: a `CONTROLZERO_API_KEY` exported in the shell that maps to a
+  different project than the integration you installed, so events land in the
+  wrong tenant and the dashboard shows nothing.
+- **Per-agent bundle cache.** Each governed surface now caches its policy bundle
+  under `~/.controlzero/integrations/<agent>/cache/` (next to the per-agent
+  `config.yaml`), so two surfaces on one machine each bound to their own project
+  no longer share a bundle. A read fallback keeps existing installs working on
+  upgrade: an empty per-agent cache transparently reads the legacy shared cache
+  until the first fetch re-caches it (no fail-closed on upgrade).
+
+### Changed
+
+- **Per-agent key is now AUTHORITATIVE in the enforcement hook.** Hook-check
+  precedence becomes per-agent (for the active surface) > env > global. A key
+  installed via `install <agent> --api-key` / `kiro init --api-key` now wins over
+  a stale ambient `CONTROLZERO_API_KEY`, with a loud one-line warning when they
+  differ. This closes the silent wrong-tenant bug where a hook spooled + uploaded
+  + ingested correctly but attributed the events to whatever key was exported in
+  the shell, so the dashboard for the installed project showed "no audit entries".
+  Non-hook resolution (`status`, install-time display) is unchanged
+  (env > per-agent > global).
+- **Cache bundle extension is now `.czpolicy`** (was `.bin`), matching the UI
+  policy export (both are the same signed bundle format). Legacy `.bin` caches
+  are still read and garbage-collected, so nothing breaks on upgrade.
+
 ## 1.11.9 -- 2026-06-25 (policy-posture remediation: honest hosted/local CLI, per-agent keys, key-validity diagnostics)
 
 ### Added

{controlzero-1.11.9 → controlzero-1.13.0}/PKG-INFO

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

{controlzero-1.11.9 → controlzero-1.13.0}/controlzero/_internal/bundle.py

@@ -958,4 +958,21 @@ def _translate_rule(rule: dict, policy_id: str) -> Optional[dict]:
             if isinstance(k, str) and isinstance(v, str)
         }
 
+    # #1011 follow-up: the SAME allowlist-strip trap. A hosted rule's
+    # `conditions` (e.g. {input_text: "rm -rf"}) was being dropped here, so a
+    # condition authored in the dashboard NEVER reached the local enforcer, so
+    # the rule silently matched on actions only (or, with a tool-case mismatch,
+    # not at all). Forward BOTH alias keys verbatim whenever present (incl. a
+    # malformed/falsy shape: [] / "" / 0 / False), and let the loader apply ONE
+    # consistent precedence + shape validation (truthy-first; reject any
+    # non-dict; a genuine empty dict {} is "no conditions"). Collapsing to a
+    # single key HERE re-introduces a divergent precedence where a present `{}`
+    # could shadow a real alias (codex re-review), so the bundle stays dumb and
+    # the loader is the single source of truth. (The backend wire struct carries
+    # Conditions; see bundle_handler.go PolicyRule.)
+    if "conditions" in rule:
+        translated["conditions"] = rule["conditions"]
+    if "when" in rule:
+        translated["when"] = rule["when"]
+
     return translated

controlzero-1.13.0/controlzero/_internal/condition_ops.py

@@ -0,0 +1,226 @@
+"""Policy-condition operator table (single source of truth) for #1011 / #1495.
+
+A rule condition value is either a LEGACY SCALAR (string -> glob, number/bool ->
+equals; evaluated in enforcer._conditions_match, byte-identical to pre-#1495) or
+a TAGGED ENVELOPE ``{"op": <name>, "value": <scalar|array>, "case_insensitive"?:
+bool}``. This module evaluates the envelope operators ONLY; the scalar path stays
+in the enforcer so existing policies and signed bundles evaluate unchanged.
+
+This is the Python reference; the Node twin (conditionOps.ts) MUST agree
+byte-for-byte (cross-SDK parity is proven by tests/parity/decisions.json). Go is
+paused and not part of this contract; the Go BACKEND engine evaluates only the
+reserved server-side keys (time_range/ip_whitelist/tags) and defers tool-level
+conditions to the SDK (it has no tool args).
+
+FAIL-CLOSED LAW: a MISSING field (value is None) is NO-MATCH for EVERY operator
+except ``exists``/``not_exists``. A regex that will not compile, or a numeric op
+on a non-numeric field, is NO-MATCH (never an error that fails open).
+"""
+
+from __future__ import annotations
+
+import fnmatch
+import re
+from typing import Any
+
+# Read-only aliases canonicalised on evaluation so the shipped templates
+# (matches_pattern / greater_than / less_than) load and evaluate with ZERO data
+# migration. The dashboard going forward emits the canonical names.
+_OP_ALIASES = {
+    "matches_pattern": "matches",
+    "greater_than": "gt",
+    "less_than": "lt",
+    "greater_than_or_equal": "gte",
+    "less_than_or_equal": "lte",
+}
+
+# The closed operator set the engine honors. The Go publish-time validator (and
+# the frontend) reject any op not in here, so an inert/typo'd operator can never
+# ship.
+KNOWN_OPS = frozenset(
+    {
+        "glob",
+        "equals",
+        "contains",
+        "matches",
+        "gt",
+        "lt",
+        "gte",
+        "lte",
+        "in",
+        "not_in",
+        "outside_range",
+        "in_range",
+        "exists",
+        "not_exists",
+    }
+)
+
+
+# Reserved structured condition keys are matched by KEY NAME (the Go backend's
+# server-side matchers) and are NEVER interpreted as a {op,value} envelope, even
+# when their value nests a sub-key literally named `op` (e.g. a tag named "op").
+# This closes the tags:{op:...} collision hole. The caller checks the KEY against
+# this set before treating a value as an envelope.
+RESERVED_STRUCTURED_KEYS = frozenset({"time_range", "ip_whitelist", "tags"})
+
+
+def canonicalize_op(op: str) -> str:
+    """Map a read alias to its canonical operator name; pass through otherwise."""
+    return _OP_ALIASES.get(op, op)
+
+
+def is_envelope(value: Any) -> bool:
+    """True iff ``value`` is a tagged operator envelope: a dict with a string
+    ``op`` key. Reserved structured keys are disambiguated by KEY NAME upstream,
+    never here, and a runtime args/context value is never treated as an envelope.
+    """
+    return isinstance(value, dict) and isinstance(value.get("op"), str)
+
+
+def _as_float(x: Any):
+    """Coerce to float for numeric ops; return None if not numeric (-> NO-MATCH)."""
+    if isinstance(x, bool):  # bool is an int subclass; never treat as a number here
+        return None
+    if isinstance(x, (int, float)):
+        return float(x)
+    if isinstance(x, str):
+        try:
+            return float(x.strip())
+        except ValueError:
+            return None
+    return None
+
+
+def _as_list(operand: Any) -> list:
+    """Operand for in/not_in: a JSON array, or a legacy comma-separated string
+    ('Saturday,Sunday') split by this compat shim so the shipped templates work
+    unmodified. A None / empty operand yields an EMPTY list (the caller treats an
+    empty operand as NO-MATCH, fail-closed (codex P2: a missing `value` must not
+    turn `not_in` into match-everything))."""
+    if operand is None:
+        return []
+    if isinstance(operand, (list, tuple)):
+        return [x for x in operand if x is not None]
+    if isinstance(operand, str):
+        return [p.strip() for p in operand.split(",") if p.strip()]
+    return [operand]
+
+
+# matches (regex) is BETA: Python `re` has no per-match timeout, so a pathological
+# author-supplied pattern can backtrack catastrophically against adversarial field
+# input (codex P1 ReDoS). Until a timeout / RE2 binding lands, bound BOTH the
+# scanned input and the pattern length so practical backtracking is capped; the
+# publish-time validator (#1498) also caps the pattern. A regex error stays
+# fail-closed (NO-MATCH).
+_MATCHES_INPUT_CAP = 8192
+_MATCHES_PATTERN_CAP = 1024
+
+
+def _range_bounds(operand: Any):
+    """[lo, hi] for in_range/outside_range: a 2-element array, or a legacy
+    'lo-hi' / 'HH:MM-HH:MM' string. Returns (lo_str, hi_str) or None if malformed.
+    Comparison is lexical for HH:MM (24h zero-padded) and numeric otherwise; both
+    sides are compared as strings of the same kind, matching the Go matchTimeRange
+    lexical compare for time."""
+    if isinstance(operand, (list, tuple)) and len(operand) == 2:
+        return str(operand[0]), str(operand[1])
+    if isinstance(operand, str) and "-" in operand:
+        lo, _, hi = operand.partition("-")
+        lo, hi = lo.strip(), hi.strip()
+        if lo and hi:
+            return lo, hi
+    return None
+
+
+def _in_range(value: Any, lo: str, hi: str) -> bool:
+    """Inclusive lo<=value<=hi. Numeric when all three parse as numbers, else a
+    lexical string compare (so 'HH:MM' 24h times order correctly)."""
+    fv, flo, fhi = _as_float(value), _as_float(lo), _as_float(hi)
+    if fv is not None and flo is not None and fhi is not None:
+        return flo <= fv <= fhi
+    sv = str(value)
+    return lo <= sv <= hi
+
+
+def match_operator(
+    op: str, value: Any, operand: Any, case_insensitive: bool = False
+) -> bool:
+    """Evaluate one field-level envelope operator. ``value`` is the field value
+    from the merged context+args dict (None if the field is absent); ``operand``
+    is the envelope's ``value``. Returns True iff the condition is satisfied.
+    Unknown op -> False (fail-closed; the validator rejects it at publish too)."""
+    op = canonicalize_op(op)
+
+    # Presence ops are the ONLY ones where a missing field can be a match.
+    if op == "exists":
+        return value is not None
+    if op == "not_exists":
+        return value is None
+
+    # Every other op: a missing field is NO-MATCH (uniform, fail-closed).
+    if value is None:
+        return False
+
+    if op in ("gt", "lt", "gte", "lte"):
+        fv, fo = _as_float(value), _as_float(operand)
+        if fv is None or fo is None:
+            return False  # non-numeric operand/field -> NO-MATCH
+        if op == "gt":
+            return fv > fo
+        if op == "lt":
+            return fv < fo
+        if op == "gte":
+            return fv >= fo
+        return fv <= fo
+
+    if op in ("in", "not_in"):
+        items = [str(x) for x in _as_list(operand)]
+        if not items:
+            # Malformed / empty operand -> NO-MATCH for BOTH in and not_in
+            # (fail-closed; a deny does not over-fire, an allow does not
+            # over-allow). The validator rejects an empty operand at publish.
+            return False
+        if case_insensitive:
+            present = str(value).casefold() in {i.casefold() for i in items}
+        else:
+            present = str(value) in items
+        return present if op == "in" else not present
+
+    if op in ("in_range", "outside_range"):
+        bounds = _range_bounds(operand)
+        if bounds is None:
+            return False
+        inside = _in_range(value, bounds[0], bounds[1])
+        return inside if op == "in_range" else not inside
+
+    # String ops below.
+    sval, soperand = str(value), str(operand)
+    if case_insensitive:
+        sval, soperand = sval.casefold(), soperand.casefold()
+
+    if op == "equals":
+        # Exact equality; wildcards are LITERAL (unlike glob).
+        return sval == soperand
+
+    if op == "contains":
+        # Substring; the operand's own glob metachars are literal (not wildcards).
+        return soperand in sval
+
+    if op == "glob":
+        return fnmatch.fnmatchcase(sval, soperand)
+
+    if op == "matches":
+        # Regex (re.search). Author owns anchoring. BETA: bound input + pattern
+        # length to cap ReDoS backtracking (codex P1); uncompilable / runtime
+        # error -> NO-MATCH (fail-closed), never an exception that fails open.
+        if len(soperand) > _MATCHES_PATTERN_CAP:
+            return False
+        flags = re.IGNORECASE if case_insensitive else 0
+        try:
+            return re.search(soperand, sval[:_MATCHES_INPUT_CAP], flags) is not None
+        except re.error:
+            return False
+
+    # Unknown operator: fail-closed (the publish-time validator also rejects it).
+    return False

{controlzero-1.11.9 → controlzero-1.13.0}/controlzero/_internal/enforcer.py

@@ -516,7 +516,9 @@ class PolicyEvaluator:
 
         for rule in self._rules:
             evaluated += 1
-            if not any(_glob_any(rule.actions, a) for a in candidate_actions):
+            # Action gate: tool-case-insensitive so `bash:*` matches `Bash:rm`
+            # (#1011). Resource/client/project gates below stay case-sensitive.
+            if not any(_action_glob_any(rule.actions, a) for a in candidate_actions):
                 continue
             # Client + project gates (gh#175). A rule whose selector
             # excludes this request does NOT apply to this surface, so
@@ -676,10 +678,22 @@ class PolicyEvaluator:
         All condition keys must match. Missing key = no match. Context keys
         override args on collision. Nested ``context['tags']`` dict is flattened.
         """
-        if not rule_conditions:
+        # #1011 follow-up (codex P1): the non-dict guard MUST run before the
+        # falsy short-circuit, otherwise a falsy-but-malformed conditions ([],
+        # "", 0, False) would be read as "no conditions" and the rule would match
+        # unconditionally (an allow rule -> unconditional allow, fail-open). A
+        # corrupt/tampered or future-shaped signed rule is unverifiable, so the
+        # rule does NOT match: an allow rule then does not fire and the default
+        # posture governs (fail-closed); a deny rule simply does not contribute.
+        # `None` is the genuine "no conditions" case and matches.
+        if not isinstance(rule_conditions, dict):
+            return rule_conditions is None
+        if not rule_conditions:  # empty dict -> no conditions to satisfy
             return True
         import fnmatch as _fn
 
+        from .io_capture_producer import _INPUT_TEXT_KEYS
+
         merged: dict = {}
         if args:
             merged.update(args)
@@ -688,11 +702,71 @@ class PolicyEvaluator:
             tags = context.get("tags") or {}
             if isinstance(tags, dict):
                 merged.update(tags)
+        # #1011 follow-up: derive `input_text` (the key the dashboard/templates
+        # author, "command/input contains X") DETERMINISTICALLY from the payload
+        # rather than trusting a caller-supplied label. The raw command/content
+        # is the GROUND TRUTH of what runs, so it wins first: neither a benign
+        # `input_text` nor a benign pre-extracted `input_payload` can shadow a
+        # dangerous `command` (codex P1: a payload setting input_text="ls" or
+        # input_payload="ls" while command="rm -rf /" would otherwise bypass the
+        # deny under default allow). Precedence: the canonical _INPUT_TEXT_KEYS
+        # scan (the SAME order audit extraction uses, so enforcement and audit
+        # never drift), then the host's pre-extracted input_payload, then any
+        # existing input_text, each only as a fallback when nothing richer is
+        # present.
+        _derived = None
+        for _k in _INPUT_TEXT_KEYS:
+            _v = merged.get(_k)
+            if _v:
+                _derived = _v
+                break
+        if not _derived:
+            _derived = merged.get("input_payload")
+        if not _derived:
+            _derived = merged.get("input_text")
+        if _derived:
+            merged["input_text"] = _derived
+        from .condition_ops import (
+            RESERVED_STRUCTURED_KEYS,
+            is_envelope,
+            match_operator,
+        )
+
         for key, pattern in rule_conditions.items():
+            # #1495: a TAGGED ENVELOPE {op, value} dispatches to the shared
+            # operator table (equals/contains/matches/gt/lt/in/not_in/range/
+            # exists/...). Everything else is a LEGACY SCALAR and keeps the exact
+            # pre-#1495 glob/CONTAINS path below, so existing policies and signed
+            # bundles evaluate byte-identically. exists/not_exists are the only
+            # ops where a missing field can match, so the envelope branch runs
+            # BEFORE the missing-key short-circuit. A RESERVED structured key is
+            # matched by key name, never as an envelope (the tags:{op:...} hole).
+            if key not in RESERVED_STRUCTURED_KEYS and is_envelope(pattern):
+                if not match_operator(
+                    pattern["op"],
+                    merged.get(key),
+                    pattern.get("value"),
+                    bool(pattern.get("case_insensitive")),
+                ):
+                    return False
+                continue
             value = merged.get(key)
             if value is None:
                 return False
-            if not _fn.fnmatchcase(str(value), str(pattern)):
+            sval, spat = str(value), str(pattern)
+            # Only `input_text` (the dashboard's authored text-content key) uses
+            # CONTAINS for a plain pattern, so `input_text: "rm -rf"` catches
+            # `rm -rf /tmp/foo`. A pattern with glob metacharacters still uses
+            # fnmatch; EVERY other key (including the raw `command`/`prompt`
+            # sources) keeps exact-glob semantics, so an existing exact-match
+            # allowlist is never silently broadened into a substring match
+            # (codex P1 fail-open regression).
+            if key.casefold() in _TEXT_CONTENT_CONDITION_KEYS and not any(
+                c in spat for c in "*?["
+            ):
+                if spat not in sval:
+                    return False
+            elif not _fn.fnmatchcase(sval, spat):
                 return False
         return True
 
@@ -836,8 +910,58 @@ def _glob_any(patterns: list[str], value: str) -> bool:
 
     fnmatchcase is case-sensitive (matches policy semantics) and supports the
     same syntax users learn from .gitignore: *, ?, [seq], [!seq].
+
+    NOTE: this stays case-sensitive and is used for the resource / client /
+    project selector gates. Action matching uses :func:`_action_glob_any`,
+    which case-folds the tool segment (see below).
     """
     for p in patterns:
         if fnmatch.fnmatchcase(value, p):
             return True
     return False
+
+
+def _norm_action_tool(s: str) -> str:
+    """Case-fold ONLY the tool segment of an action token (the part before the
+    first ``:``); leave the method/arg glob untouched.
+
+    The canonical action the SDK emits is capital-tool (e.g. ``Bash:rm``, the
+    canonical TOOL NAME from the extractor spec), but a user or a policy
+    template may author the tool in any case (``bash:*``). The tool name is a
+    fixed, known vocabulary, so case is never meaningful for it; folding it lets
+    a user-authored rule reconcile with the call the agent actually makes. The
+    METHOD stays case-sensitive so method-cased semantics (e.g. ``database:DROP``
+    vs ``database:drop``) are preserved. A token with no ``:`` (e.g. the
+    universal ``*``) is folded whole, a no-op for glob metacharacters.
+    """
+    tool, sep, method = s.partition(":")
+    return (tool.casefold() + sep + method) if sep else s.casefold()
+
+
+def _action_glob_any(patterns: list[str], action: str) -> bool:
+    """Action-gate matcher: like :func:`_glob_any` but case-INSENSITIVE on the
+    tool segment of both the rule pattern and the action (see
+    :func:`_norm_action_tool`).
+
+    This is what makes a deny rule authored as ``bash:*`` actually match the
+    canonical ``Bash:rm`` (#1011 follow-up: a customer's deny rule silently
+    never fired because the matcher compared the tool case-sensitively).
+    """
+    a = _norm_action_tool(action)
+    for p in patterns:
+        if fnmatch.fnmatchcase(a, _norm_action_tool(p)):
+            return True
+    return False
+
+
+# The ONE condition key whose plain (metachar-free) pattern is matched by
+# CONTAINS (substring): `input_text`. It is the key the dashboard/templates
+# author for "the command/input contains X", and a user typing `rm -rf` means
+# "contains rm -rf", not "IS exactly rm -rf". Patterns WITH glob metachars still
+# use fnmatch. This set is deliberately NARROW: the raw payload keys (command,
+# input_payload, prompt, ...) are seeding SOURCES for input_text, not author-
+# facing condition keys. Briefly including them here broadened any existing
+# exact-match allowlist keyed on `command` into a substring match, a fail-open
+# regression (codex P1). Every key except `input_text` keeps exact-glob
+# semantics. (#1011 follow-up.)
+_TEXT_CONTENT_CONDITION_KEYS = frozenset({"input_text"})

{controlzero-1.11.9 → controlzero-1.13.0}/controlzero/_internal/io_capture_producer.py

@@ -69,15 +69,22 @@ _OUTPUT_EVENT_NAMES = frozenset(
 # in extraction priority order. The whole tool_input dict is the fallback when
 # none match (rendered as canonical JSON so the capture is still faithful).
 _INPUT_TEXT_KEYS = (
-    "command",      # Bash / run_command
-    "CommandLine",  # Antigravity run_command
-    "sql",          # database
-    "query",        # search / http
-    "prompt",       # prompt-style tools
-    "content",      # Write / file content
-    "new_string",   # Edit
-    "text",         # generic text tools
-    "url",          # http / browser
+    "command",       # Bash / run_command
+    "CommandLine",   # Antigravity run_command
+    "sql",           # database
+    "query",         # search / http
+    "prompt",        # prompt-style tools
+    "content",       # Write / file content
+    "new_string",    # Edit
+    "text",          # generic text tools
+    "url",           # http / browser
+    # File-target paths (#1011): so a condition like `input_text contains .env`
+    # on a Read/Write/Edit fires on the PATH being touched. Lower priority than
+    # the command/content keys above (a tool rarely carries both; if it does the
+    # executed text wins). These also enrich the audit input_payload.
+    "file_path",     # Read / Write / Edit
+    "path",          # Glob / Grep / LS
+    "notebook_path",  # NotebookEdit
 )
 
 # tool_response / tool_output field shapes a host may deliver on a PostToolUse

{controlzero-1.11.9 → controlzero-1.13.0}/controlzero/cli/agent_config.py

@@ -169,3 +169,53 @@ def resolve_api_key(
         return global_key, "global"
 
     return None, "none"
+
+
+def per_agent_api_key(
+    state_dir: Path, canonical_source: Optional[str]
+) -> Optional[str]:
+    """The api_key installed for THIS agent surface only -- no global fallback.
+
+    Unlike :func:`resolve_api_key` (env > per-agent > global), this returns
+    ONLY the per-agent ``integrations/<canonical_source>/config.yaml`` key, or
+    None. hook-check uses it to make a surface's installed key AUTHORITATIVE
+    over a stale ambient ``CONTROLZERO_API_KEY`` (#1011 follow-up): a surface
+    wired by ``install <agent> --api-key`` / ``kiro init --api-key`` must
+    attribute its audit to the project it was installed for, never to whatever
+    key happens to be exported in the shell. Never raises.
+    """
+    if not canonical_source:
+        return None
+    return _read_api_key_from_yaml(
+        per_agent_config_path(state_dir, canonical_source)
+    )
+
+
+def resolve_hook_api_key(
+    state_dir: Path,
+    canonical_source: Optional[str],
+    *,
+    env: Optional[dict] = None,
+) -> tuple[Optional[str], str, bool]:
+    """Resolve the hook-check api_key with PER-AGENT-AUTHORITATIVE precedence.
+
+    Unlike :func:`resolve_api_key` (env > per-agent > global), the enforcement
+    hook makes a surface's installed key win over a stale ambient env var
+    (#1011 follow-up): per-agent > env > global. This is what fixes the silent
+    wrong-tenant bug. Returns ``(api_key_or_None, source_label, overrode_env)``
+    where ``source_label`` is ``"per_agent"`` / ``"env"`` / ``"global"`` /
+    ``"none"`` and ``overrode_env`` is True when a per-agent key replaced a
+    DIFFERENT ambient ``CONTROLZERO_API_KEY`` (the case the hook warns about).
+    Never raises.
+    """
+    env = env if env is not None else os.environ
+    ambient = env.get("CONTROLZERO_API_KEY")
+    per_agent = per_agent_api_key(state_dir, canonical_source)
+    if per_agent:
+        return per_agent, "per_agent", bool(ambient and ambient != per_agent)
+    if ambient:
+        return ambient, "env", False
+    global_key = _read_api_key_from_yaml(state_dir / "config.yaml")
+    if global_key:
+        return global_key, "global", False
+    return None, "none", False