controlzero 1.11.4__tar.gz → 1.11.6__tar.gz

{controlzero-1.11.4 → controlzero-1.11.6}/CHANGELOG.md

@@ -1,5 +1,64 @@
 # Changelog
 
+## 1.11.6 -- 2026-06-21 (cross-surface enforcement hardening: Kiro v3 + Antigravity honesty + warn-mode)
+
+Ships the #1373 / #65 cross-surface enforcement work and follow-ups that landed
+after 1.11.5 was published.
+
+### Fixed
+
+- **Kiro CLI v3 enforcement (#1375 / #1378).** The shipping kiro-cli (>= 2.8.x)
+  enforces ONLY via an agent-config `hooks.preToolUse` block on the default
+  agent. `controlzero install kiro` now writes `~/.kiro/agents/controlzero.json`
+  (matchers `execute_bash` / `fs_write` / `fs_read` / `use_aws`, interpreter-
+  pinned `hook-check --strict`) and sets it as the default agent. The legacy v2
+  embedded `settings.json` hooks and standalone `.kiro/hooks/*.json` are ignored
+  by the shipping CLI. Host-verified on kiro-cli 2.8.1: a denied bash command is
+  blocked; an allowed file read proceeds.
+- **Crash-proof hook entry (#1189 / #1377).** `python -m controlzero` and the
+  console scripts route through the crash-proof `hook_entry`, so a broken
+  install fails CLOSED, not open.
+- **Kiro deciding-gate fail-close (#1377).** A non-{0,2} hook exit is treated as
+  a block, not a silent allow.
+- **Antigravity #202 honesty (#1373 / #1377).** The agy adapter is `observe`
+  (covered families `file_read` / `file_search`), not a false `enforced` claim;
+  it emits the documented stdout `{"decision":...}` envelope. agy default-mode
+  enforcement is host-side (COMING SOON), not SDK-fixable.
+- **Audit-probe isolation (#1375 / #1377).** kiro/cursor init + verify self-test
+  probes run with an isolated HOME, so synthetic denies never pollute
+  `~/.controlzero/audit.log`.
+
+### Added
+
+- **`default_action` posture toggle is first-class (#1374).** The no-rule-match
+  posture (`deny` default | `warn` | `allow`) is documented + surfaced in the
+  init templates, with a new deny-list recipe. Comment-only in templates; the
+  default stays `deny`.
+- **Kiro sub-agent bypass warning (#7671).** `controlzero install kiro` warns
+  that Kiro does not fire preToolUse hooks for sub-agent tool calls (upstream
+  kiro #7671) -- direct tool calls are governed, subagent calls are not.
+
+## 1.11.5 -- 2026-06-19 (cross-surface CONTROLZERO_CLIENT foreign-pin fail-open)
+
+Closes a routing fail-open where an explicit `CONTROLZERO_CLIENT` pin -- set by
+`controlzero install <host>` so a kiro/codex/antigravity/cursor hook routes to
+the right adapter -- was NOT authoritative. The `ClaudeCodeAdapter` is first in
+the registry and falls through to ambient Anthropic env hints (`CLAUDECODE` /
+`CLAUDE_CODE` / ...), so a correctly installed foreign-host hook that ALSO
+carried an ambient `CLAUDECODE` (e.g. launched from a Claude Code-spawned shell)
+was hijacked to the Claude adapter, which renders the wrong wire shape and reads
+as allow on a destructive tool call.
+
+### Fixed
+
+- **Foreign `CONTROLZERO_CLIENT` pin now defers (cross-surface fail-open).**
+  Every host adapter's `claim()` defers when `CONTROLZERO_CLIENT` names a
+  DIFFERENT client, via the shared `HostAdapter._pinned_elsewhere` helper, so an
+  installer-pinned hook can never be hijacked by an ambient `CLAUDECODE`;
+  `UnknownHostAdapter` stays the always-claim backstop. A 7-surface guard matrix
+  (`tests/test_hosts_adapter.py`) pins it fail-if-reverted. Mirrors the Node SDK
+  fix. gh#81.
+
 ## 1.11.4 -- 2026-06-17 (close the count==0 degraded fail-open + stale-empty-cache replay + cached-bundle integrity, gh#1303)
 
 Closes a degraded-bundle fail-open in the count-provenance discriminator plus
@@ -715,7 +774,7 @@ secret-value-leak guard that gates every outbound HITL payload.
   POSTs a HITL approval request, builds the body from the
   `PolicyDecision`, threads in `X-CZ-Requestor-Email` from
   `~/.controlzero/config.yaml`, sends a per-call `Idempotency-Key`, and
-  returns a `PendingApproval`. Maps backend error codes E1305-E1308 onto
+  returns a `PendingApproval`. Maps backend error codes E1705-E1708 onto
   the matching SDK exceptions. (#577)
 
 ### Conformance

{controlzero-1.11.4 → controlzero-1.11.6}/PKG-INFO

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

controlzero-1.11.6/controlzero/__main__.py

@@ -0,0 +1,23 @@
+"""Enable ``python -m controlzero`` to run the CLI.
+
+The Kiro CLI / Cursor hook commands pin the interpreter as
+``"<sys.executable>" -m controlzero hook-check --strict`` (#1265) so the host
+invokes the exact, importable controlzero the user installed, never a bare
+``controlzero`` that PATH might resolve to a broken or shadowing install.
+
+CRITICAL (#1373 / re-opens #1189): this entry MUST route through the crash-proof
+``hook_entry.cli`` shim, NOT ``controlzero.cli.main:cli`` directly. The
+interpreter-pin made every Kiro/Cursor hook run ``python -m controlzero
+hook-check`` -> this module. A direct unguarded ``from controlzero.cli.main
+import cli`` raises a bare nonzero traceback on a broken/partial install (missing
+transitive dep, packaging defect); Kiro reads any exit code that is neither 0
+nor 2 as "warn / proceed" -> the tool RUNS while audit may log a deny. Routing
+through ``hook_entry.cli`` fails SAFE (exit 2 = block) on an import crash for a
+hook invocation -- closing the exact #1189 fail-open the console script already
+fixed but ``-m controlzero`` had silently bypassed.
+"""
+
+from controlzero.cli.hook_entry import cli
+
+if __name__ == "__main__":
+    cli()

{controlzero-1.11.4 → controlzero-1.11.6}/controlzero/cli/__main__.py

@@ -3,11 +3,16 @@
 Mirrors the ``controlzero`` console-script entry point. Used by
 ``controlzero kiro verify`` to invoke hook-check as a subprocess in a way
 that works even when the console script is not on PATH (e.g. CI, venvs).
+
+Routes through the crash-proof ``hook_entry.cli`` shim (#1189 / #1373): this is
+a hook-invocation path, so an import crash on a broken install must fail SAFE
+(exit 2 = block), never escape as a bare nonzero traceback that a host reads as
+"warn / proceed".
 """
 
 from __future__ import annotations
 
-from controlzero.cli.main import cli
+from controlzero.cli.hook_entry import cli
 
 if __name__ == "__main__":
     cli()

{controlzero-1.11.4 → controlzero-1.11.6}/controlzero/cli/doctor.py

@@ -353,7 +353,9 @@ def _antigravity_dry_run_roundtrips() -> bool:
         adapter = select_adapter({}, {"CONTROLZERO_CLIENT": "antigravity"})
         if getattr(adapter, "name", "") != "antigravity":
             return False
-        out = adapter.render(
+        # render_envelope is the per-host wire dict; render() folds it into a
+        # RenderResult (exit code + stdout). The dry-run inspects the envelope.
+        out = adapter.render_envelope(
             CZDecision(effect="allow", reason="doctor dry-run", reason_code="RULE_MATCH")
         )
         return isinstance(out, dict) and out.get("decision") == "allow"

controlzero-1.11.6/controlzero/cli/hook_entry.py

@@ -0,0 +1,118 @@
+"""Crash-proof console-script entry point for the ``controlzero`` CLI (#1189).
+
+The ``controlzero`` console script declared in ``pyproject.toml`` MUST NOT be
+pointed directly at ``controlzero.cli.main:cli``. The pip-generated wrapper
+imports the target at module load with no guard, so a top-level import crash in
+``controlzero/cli/main.py`` (a missing transitive dependency, a packaging
+defect, a syntax error in any eagerly-imported submodule) raises before
+``cli()`` runs. The wrapper then exits nonzero with a traceback, and a host that
+treats nonzero-with-no-decision as "proceed" (Claude Code's PreToolUse falls
+back to allow on a hook it cannot evaluate) silently lets the tool call
+through. That is a fail-OPEN on the governance hot path -- the exact defect
+QA #1189 flagged.
+
+This shim makes the entry point crash-proof:
+
+  * The heavy import of ``controlzero.cli.main`` happens inside a try/except
+    with a ``sys.path`` source-checkout fallback, mirroring
+    ``tools/cz-kiro-adapter`` so a dev checkout that has not been pip-installed
+    still resolves the package.
+  * If the import or evaluation of the CLI cannot complete AT ALL and this is a
+    hook invocation (``hook-check`` on argv -- the governance hot path), the
+    shim fails SAFE: it writes a hard, human-readable error to stderr and exits
+    with the host's DENY/block code (Claude Code PreToolUse = exit 2), never a
+    silent allow.
+  * For a non-hook invocation (interactive ``controlzero ...`` usage) a broken
+    install should surface its traceback so the user can fix it -- there is no
+    governance decision at stake -- so the shim re-raises in that case.
+
+What this shim does NOT change: the runtime fail-OPEN contract that lives
+inside ``hook_check`` (E1501 bad-JSON, E1502 timeout, empty stdin, missing
+tool_name) is intentional and is preserved. Those paths are reached only after
+the CLI imports successfully and represent a *decision* to pass through, not an
+import crash. This shim only converts the previously-silent import-crash
+fall-through into an explicit fail-safe deny.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+
+# Host block/deny exit codes for the hook hot path. Claude Code's PreToolUse
+# protocol treats exit 2 as "block"; Kiro reuses the same convention. We do not
+# have the resolved host adapter available before the import succeeds, so we use
+# the lowest-common-denominator block code (2), which every supported host
+# interprets as deny rather than allow.
+_HOOK_DENY_EXIT_CODE = 2
+
+_HOOK_SUBCOMMANDS = frozenset({"hook-check"})
+
+
+def _is_hook_invocation(argv: list[str]) -> bool:
+    """True when the process was launched on the governance hot path.
+
+    The ``hook-check`` subcommand is what hosts (Claude Code, Kiro, Codex,
+    Gemini, Antigravity) wire into their PreToolUse hooks. Detecting it on argv
+    lets the shim choose fail-SAFE (deny) on an import crash for hook calls
+    while leaving interactive CLI usage to surface its traceback normally.
+    """
+    return any(arg in _HOOK_SUBCOMMANDS for arg in argv[1:])
+
+
+def cli() -> None:
+    """Crash-proof wrapper around ``controlzero.cli.main:cli``.
+
+    Defers the heavy import so an import-time crash cannot escape as a bare
+    nonzero traceback that a host would mistake for "allow".
+    """
+    try:
+        from controlzero.cli.main import cli as _real_cli
+    except ModuleNotFoundError:
+        # Possibly a source checkout where the package is not pip-installed.
+        # Add the SDK root to sys.path and retry once, mirroring
+        # tools/cz-kiro-adapter. controlzero/cli/hook_entry.py -> SDK root is
+        # three levels up (controlzero/cli/ -> controlzero/ -> SDK root).
+        _sdk_root = os.path.dirname(
+            os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+        )
+        if _sdk_root not in sys.path:
+            sys.path.insert(0, _sdk_root)
+        try:
+            from controlzero.cli.main import cli as _real_cli
+        except BaseException:  # noqa: BLE001 -- crash-proof boundary
+            _fail_safe_or_reraise()
+            return
+    except BaseException:  # noqa: BLE001 -- crash-proof boundary
+        # Any other top-level import failure (ImportError on a transitive dep,
+        # a syntax error in an eagerly-imported submodule, etc).
+        _fail_safe_or_reraise()
+        return
+
+    _real_cli()
+
+
+def _fail_safe_or_reraise() -> None:
+    """On import failure: fail-safe DENY for hook calls, re-raise otherwise.
+
+    Reads the live exception from ``sys.exc_info`` so it can re-raise the
+    original traceback for interactive usage.
+    """
+    if _is_hook_invocation(sys.argv):
+        exc = sys.exc_info()[1]
+        # Hard, loud error to stderr -- never a silent allow. The host sees a
+        # nonzero block exit code and denies the tool call.
+        sys.stderr.write(
+            "[Control Zero] hook entry point could not load the policy engine "
+            f"({type(exc).__name__}: {exc}); DENYING this tool call (fail-safe). "
+            "Reinstall the controlzero package to restore policy enforcement.\n"
+        )
+        sys.stderr.flush()
+        sys.exit(_HOOK_DENY_EXIT_CODE)
+    # Not a hook invocation: surface the real traceback so the user can fix
+    # their install. No governance decision is at stake here.
+    raise
+
+
+if __name__ == "__main__":
+    cli()

{controlzero-1.11.4 → controlzero-1.11.6}/controlzero/cli/hosts/__init__.py

@@ -55,9 +55,18 @@ known host treats no-decision as "proceed") and the universal
 from __future__ import annotations
 
 from controlzero.cli.hosts.antigravity import AntigravityAdapter
-from controlzero.cli.hosts.base import CZDecision, HostAdapter
+from controlzero.cli.hosts.base import (
+    AdapterError,
+    CoverageDecl,
+    CZDecision,
+    HostAdapter,
+    RenderResult,
+    ToolCall,
+)
 from controlzero.cli.hosts.claude_code import ClaudeCodeAdapter
 from controlzero.cli.hosts.codex_cli import CodexCLIAdapter
+from controlzero.cli.hosts.cursor import CursorIDEAdapter
+from controlzero.cli.hosts.cursor_cli import CursorCLIAdapter
 from controlzero.cli.hosts.gemini_cli import GeminiCLIAdapter
 from controlzero.cli.hosts.kiro import KiroCLIAdapter, KiroIDEAdapter
 from controlzero.cli.hosts.unknown import UnknownHostAdapter
@@ -77,8 +86,10 @@ REGISTRY: list[HostAdapter] = [
     CodexCLIAdapter(),
     GeminiCLIAdapter(),
     AntigravityAdapter(),  # distinct toolCall / PreToolCall signature
+    CursorCLIAdapter(),    # beforeShellExecution + top-level `command`, no tool_name (before KiroCLI)
     KiroCLIAdapter(),      # camelCase hook_event_name (disjoint from Claude PascalCase)
     KiroIDEAdapter(),      # CZ_KIRO_SURFACE=ide / TERM_PROGRAM=kiro (shim-set)
+    CursorIDEAdapter(),    # cursor_version / generation_id payload marker or CURSOR_* env (after KiroIDE)
     UnknownHostAdapter(),  # always claims; must stay at the tail
 ]
 
@@ -105,9 +116,15 @@ def select_adapter(payload: dict, env) -> HostAdapter:
 
 __all__ = [
     "CZDecision",
+    "ToolCall",
+    "RenderResult",
+    "CoverageDecl",
+    "AdapterError",
     "HostAdapter",
     "ClaudeCodeAdapter",
     "CodexCLIAdapter",
+    "CursorCLIAdapter",
+    "CursorIDEAdapter",
     "GeminiCLIAdapter",
     "AntigravityAdapter",
     "KiroCLIAdapter",

{controlzero-1.11.4 → controlzero-1.11.6}/controlzero/cli/hosts/antigravity.py

@@ -55,7 +55,7 @@ from __future__ import annotations
 import os
 from typing import Mapping
 
-from controlzero.cli.hosts.base import CZDecision, HostAdapter
+from controlzero.cli.hosts.base import CoverageDecl, CZDecision, HostAdapter
 
 # File-based EVENT names (NOT the in-process SDK class names). PreToolUse is
 # the deciding gate; PostToolUse is observe-only.
@@ -70,9 +70,62 @@ _ANTIGRAVITY_HOOK_EVENTS = frozenset(
 # disambiguators. Antigravity's unambiguous signal is the ``toolCall`` envelope,
 # which the claim below keys on first.
 _ANTIGRAVITY_CLAIM_EVENTS = frozenset({"PreInvocation", "PostInvocation"})
-_CLIENT_ALIASES = frozenset({"antigravity", "agy", "antigravity-cli"})
+# CONTROLZERO_CLIENT values the adapter CLAIMS as Antigravity. Includes the
+# surface-split forms (#58) so an install pinning CONTROLZERO_CLIENT=
+# antigravity_ide / antigravity_cli is still claimed.
+_CLIENT_ALIASES = frozenset(
+    {"antigravity", "agy", "antigravity-cli", "antigravity_ide", "antigravity_cli"}
+)
 _ENV_PREFIXES = ("ANTIGRAVITY_", "AGY_")
 
+# Surface split (#58): one adapter governs BOTH the Antigravity IDE and the
+# ``agy`` CLI -- they share the SAME external PreToolUse stdout-decision hook
+# contract, the same engine-executed ``~/.gemini/config/hooks.json``, and the
+# same sanitized hook environment (only a GEMINI_PROJECT_DIR-style whitelist is
+# forwarded; arbitrary user env vars do NOT reach the hook subshell -- verified
+# cmux#4768). Enforcement is therefore IDENTICAL on both; the founder wants the
+# AUDIT/coverage SOURCE label to distinguish them.
+#
+# There is NO runtime signal that tells the IDE apart from the CLI at hook time
+# (Google's own docs + blog confirm a shared harness + synced settings; the
+# stdin payload carries no surface marker, and the env is sanitized). So the
+# split is INSTALL-TIME: each installer writes the surface into the hook command
+# as ``CONTROLZERO_CLIENT=antigravity_ide`` / ``=antigravity_cli`` (an env var
+# set INSIDE the executed command survives agy's env sanitization because the
+# shell running the command sets it -- it is not inherited from the parent).
+#
+# Back-compat (#58): a bare ``antigravity`` (old SDKs / env-only detection)
+# stays ``antigravity`` -- its own canonical value, NOT remapped -- so existing
+# audit rows and pre-split emitters are never downgraded or rewritten.
+_SOURCE_ANTIGRAVITY = "antigravity"
+_SOURCE_ANTIGRAVITY_IDE = "antigravity_ide"
+_SOURCE_ANTIGRAVITY_CLI = "antigravity_cli"
+# CONTROLZERO_CLIENT values that resolve to the CLI surface. The CLI install
+# pins ``antigravity_cli``; the legacy agy aliases also resolve to CLI since
+# ``agy`` IS the CLI.
+_CLI_SURFACE_CLIENTS = frozenset({"antigravity_cli", "agy", "antigravity-cli"})
+
+
+def _resolve_antigravity_source(env: Mapping[str, str] | None = None) -> str:
+    """Resolve the canonical audit SOURCE for the Antigravity surface (#58).
+
+    Install-time split: the installer pins ``CONTROLZERO_CLIENT`` in the hook
+    command so the runtime knows which surface fired:
+
+    * ``antigravity_ide`` -> ``antigravity_ide`` (the IDE installer).
+    * ``antigravity_cli`` / ``agy`` / ``antigravity-cli`` -> ``antigravity_cli``
+      (the agy CLI installer; the legacy agy aliases ARE the CLI).
+    * anything else (bare ``antigravity``, unset, env-only detection) ->
+      ``antigravity`` -- the back-compat value, never remapped.
+    """
+    src = env if env is not None else os.environ
+    raw = (src.get("CONTROLZERO_CLIENT") or "").strip().lower()
+    if raw == _SOURCE_ANTIGRAVITY_IDE:
+        return _SOURCE_ANTIGRAVITY_IDE
+    if raw in _CLI_SURFACE_CLIENTS:
+        return _SOURCE_ANTIGRAVITY_CLI
+    return _SOURCE_ANTIGRAVITY
+
 # Source-confirmed decision tokens for PreToolUse output.
 _VALID_DECISIONS = frozenset({"allow", "deny", "ask", "force_ask"})
 
@@ -130,16 +183,76 @@ def _resolve_hitl_decision(env: Mapping[str, str] | None = None) -> str:
 
 class AntigravityAdapter(HostAdapter):
     name = "antigravity"
-    canonical_source = "antigravity"
-    # Antigravity decides from the stdout JSON, NOT the exit code. A non-zero
-    # exit is read as a fail-closed deny that would override an ``ask`` /
-    # ``allow`` verdict (turning a HITL prompt into a hard block), so the
-    # hook-check command must exit 0 for this host and let the JSON decide.
+    # Antigravity's documented block contract is the stdout JSON
+    # ``{"decision":"deny"}``, NOT the exit code -- so ``decision_via_exit_code``
+    # stays False (the base exit-code folding does not apply; this adapter owns
+    # its own exit-code rule via ``_exit_code_for`` below).
     decision_via_exit_code = False
 
+    # Coverage-as-data (#202, #1373). HONESTY: shipped Antigravity (1.0.1 /
+    # 1.0.3) does NOT route the run_command / Bash / file-WRITE family through
+    # the user PreToolUse hook -- it uses a NATIVE confirmation dialog. Our
+    # adapter is therefore never invoked for those destructive calls, so even a
+    # perfect deny verdict is never consulted: we CANNOT enforce them. Claiming
+    # tier="enforced" over ``covered_tool_families=("*",)`` was a #202 false
+    # claim (issue #1373).
+    #
+    # So the tier is ``observe`` (the not-functional-end-to-end posture this
+    # adapter-tier enum carries; mirrors how kiro_ide declares the bounded IDE
+    # surface). The maturity story for the shell/file family on the public
+    # surfaces is COMING SOON -- not GA/BETA -- until Antigravity ships a real
+    # shell-blocking hook path (partner-integration track). ``covered_tool_
+    # families`` is narrowed to the families agy actually ROUTES to the hook
+    # (reads / observe: file_read, file_search; PostToolUse observe) -- NOT the
+    # shell/Bash/file_write family. ``block_mechanism`` is ``stdout_decision``:
+    # agy's documented contract is the stdout ``{"decision":"deny"}`` token, and
+    # ``decision_via_exit_code=False`` so the exit code stays 0 (a deliberate
+    # #1248 decision -- a non-zero hook exit on agy is risky / unverified, so we
+    # rely on the documented stdout deny, which blocks).
+    #
+    # CRITICAL still holds: agy reads an empty / decision-less stdout as
+    # invalid_args -> DENY, so empty_stdout_is="deny" and the render envelope
+    # ALWAYS carries an explicit decision.
+    coverage = CoverageDecl(
+        tier="observe",
+        block_mechanism="stdout_decision",
+        deciding_events=("PreToolUse",),
+        observe_events=("PostToolUse", "PostInvocation", "Stop"),
+        delivers_tool_args=True,
+        empty_stdout_is="deny",
+        # ONLY the families agy actually routes to the hook today: read /
+        # discovery tools (observed). The shell (run_command -> Bash) and the
+        # file-WRITE family (write_to_file / replace_file_content) are
+        # intentionally ABSENT -- agy never calls our hook for them, so we
+        # cannot enforce them (#1373). Adding them back here would re-open the
+        # #202 false claim guarded by TestAntigravityCoverageHonesty1373 in
+        # tests/test_antigravity_adapter.py.
+        covered_tool_families=("file_read", "file_search"),
+        min_core_version="1.9.0",
+        adapter_contract_version="1",
+    )
+
+    @property
+    def canonical_source(self) -> str:  # type: ignore[override]
+        """Audit SOURCE label, split IDE vs CLI at install time (#58).
+
+        Resolved from ``CONTROLZERO_CLIENT`` so the single adapter governs both
+        surfaces (shared hook contract -> identical enforcement) while the audit
+        row distinguishes ``antigravity_ide`` from ``antigravity_cli``. A bare
+        ``antigravity`` (old SDKs / env-only detection) stays ``antigravity``
+        for back-compat. ``name`` stays ``"antigravity"`` so the fail-closed
+        guards that key on the adapter NAME are unaffected by the source split.
+        """
+        return _resolve_antigravity_source()
+
     def claim(self, payload: dict, env: Mapping[str, str]) -> bool:
         if (env.get("CONTROLZERO_CLIENT") or "").strip().lower() in _CLIENT_ALIASES:
             return True
+        # Cross-surface routing fail-open backstop: a foreign pin defers so the
+        # pinned host's adapter (not this one) claims the call -- even when an
+        # ambient ANTIGRAVITY_/AGY_ env var is also present.
+        if self._pinned_elsewhere(env, _CLIENT_ALIASES):
+            return False
         for key in env:
             if key.upper().startswith(_ENV_PREFIXES):
                 return True
@@ -169,7 +282,34 @@ class AntigravityAdapter(HostAdapter):
             normalized["tool_input"] = args if isinstance(args, dict) else {}
         return normalized
 
-    def render(self, decision: CZDecision) -> dict:
+    def _verdict(self, decision: CZDecision) -> str:
+        """Single source of truth for the agy decision TOKEN.
+
+        The stdout envelope (``render_envelope``) derives from THIS method.
+        agy decides from this stdout token (the exit code stays 0 per #1248):
+
+        * HITL (``requires_approval`` deny) -> ``_resolve_hitl_decision()``
+          (``force_ask`` by default; ``ask``/``deny``/``allow`` only via an
+          explicit ``CZ_ANTIGRAVITY_HITL_DECISION`` override).
+        * hard deny -> ``"deny"``.
+        * allow / warn -> ``"allow"``.
+        """
+        if decision.is_hitl:
+            return _resolve_hitl_decision()
+        if decision.is_deny:
+            return "deny"
+        return "allow"
+
+    # NOTE (#1373): agy intentionally does NOT override the exit code. agy's
+    # documented block contract is the stdout ``{"decision":"deny"}`` token, and
+    # ``decision_via_exit_code=False`` keeps the exit code 0 for every decision
+    # (the deliberate #1248 design -- a non-zero hook exit on agy is unverified
+    # / risky, so we rely on the stdout deny, which blocks). An exit-2 backstop
+    # was considered (finding F1) and dropped: it could not be validated against
+    # a live agy and would contradict #1248. The honest posture is the
+    # CoverageDecl above (tier=observe; shell/file COMING SOON).
+
+    def render_envelope(self, decision: CZDecision) -> dict:
         """Render to Antigravity's PreToolUse stdout-JSON contract.
 
         ALWAYS emits an explicit ``decision`` key. An empty / decision-less
@@ -177,14 +317,10 @@ class AntigravityAdapter(HostAdapter):
         (cmux#5358), so silence-that-still-prints-{} is never produced here.
         camelCase per the external contract; Control Zero diagnostic
         metadata is namespaced under ``controlzero`` so it cannot collide
-        with agy's reserved output keys.
+        with agy's reserved output keys. The decision token comes from the
+        single-source ``_verdict``.
         """
-        if decision.is_hitl:
-            verdict = _resolve_hitl_decision()
-        elif decision.is_deny:
-            verdict = "deny"
-        else:
-            verdict = "allow"
+        verdict = self._verdict(decision)
 
         envelope: dict = {
             "decision": verdict,