controlzero 1.5.1__tar.gz → 1.5.3__tar.gz

{controlzero-1.5.1 → controlzero-1.5.3}/CHANGELOG.md

@@ -1,5 +1,82 @@
 # Changelog
 
+## 1.5.3 -- 2026-05-12
+
+### Added
+
+- **Host-agent adapter base** (`controlzero/cli/hosts/`). A pluggable
+  per-host hook adapter pattern. Each adapter owns three things for
+  one host runtime: `claim(payload, env) -> bool` (recognise the
+  inbound hook call), `render(decision) -> dict` (translate the
+  canonical CZ Decision into the host's JSON envelope), and
+  `canonical_source` (backend audit alias). First adapter in
+  `REGISTRY` whose `claim()` returns True owns the call; a conservative
+  `UnknownHostAdapter` is the registry tail and always claims.
+  Adding Cursor / Windsurf / OpenClaw / Antigravity / the next
+  agent is now one file in `controlzero/cli/hosts/`, no edits to
+  `cli/main.py` or `audit_remote.py`.
+
+### Fixed
+
+- **Claude Code policy bypass on the allow path.** Pre-1.5.3 the SDK
+  emitted `{"decision": "allow", ...}` for every allow hook decision.
+  Anthropic's PreToolUse hook schema only accepts `"approve" | "block"`
+  -- the `"allow"` string crashed Claude Code's validator with
+  `Hook JSON output validation failed - (root): Invalid input` and
+  Claude Code dropped the hook decision (defaults to proceed). CloudShift
+  saw a `Write` correctly blocked, then a `PowerShell` command bypass
+  to the same intent. After 1.5.3 the Claude Code adapter renders
+  allow as `"approve"` and deny as `"block"`; Gemini CLI / Codex CLI
+  / unknown hosts each get their schema-correct shape. Customers who
+  hit this on 1.5.2 must upgrade.
+- **Source label for Claude Code hook on Windows.** Pre-1.5.3
+  detection relied on `CLAUDECODE=1` which Anthropic's Windows
+  launcher does not always export, so the audit row labelled the
+  agent as `python-sdk`. The Claude Code adapter now claims via the
+  stdin payload signature (presence of `hook_event_name` /
+  `session_id` + `tool_input`) in addition to env vars, so detection
+  survives env-var-stripped Windows hook subprocesses. Audit row
+  SOURCE column renders `Claude Code` instead of `Python SDK`.
+
+### Known follow-ups (not in 1.5.3)
+
+- Canonical-tool extractor coverage for shell-mediated file
+  operations (`PowerShell:New-Item`, `Bash:touch`, `Bash:rm`, etc.)
+  so a single `file_write` deny rule covers both the native `Write`
+  tool AND the equivalent shell command. The adapter base provides
+  the right home for this in the next release.
+- Wire-payload field gaps (`latency_ms`, `method_name`, `args`) on
+  the `/v1/sdk/audit` endpoint. Needs paired backend change.
+
+## 1.5.2 -- 2026-05-12
+
+### Fixed
+
+- **Windows Claude Code hook never delivered audit logs.** The
+  installer wrote `CONTROLZERO_API_KEY=cz_live_... controlzero hook-check`
+  into `~/.claude/settings.json`. The `VAR=value command` env-prefix
+  is bash-only and PowerShell / cmd.exe cannot parse it, so the
+  Claude Code hook subprocess failed to spawn on every PreToolUse
+  call. macOS / Linux were unaffected. After 1.5.2 the hook command
+  is plain `controlzero hook-check`; the api key flows through
+  `~/.controlzero/config.yaml` (already written by `install --api-key`)
+  on every supported platform. Side benefit: the cleartext key is
+  no longer embedded in `settings.json` on disk.
+- **Audit-log dashboard SOURCE column rendered `--` for direct-SDK
+  rows.** `detect_client_name()` returned the generic alias `"sdk"`
+  when no agent-runtime env vars were detected; the backend
+  `NormalizeSource` mapped `"sdk"` to `unknown`, and the frontend
+  rendered `unknown` as `--`. The default is now `"python-sdk"`,
+  which the backend maps to the canonical `python_sdk` source value
+  and the frontend renders as `Python SDK`.
+
+### Customer impact
+
+CloudShift / kh.lee reported on 2026-05-12 that Claude Code on
+Windows was not sending any audit logs to the dashboard, while the
+direct Python SDK script was sending logs without a populated
+SOURCE column. Both symptoms collapse to the two fixes above.
+
 ## 1.5.1 -- 2026-05-12 (SECURITY)
 
 ### Fixed

{controlzero-1.5.1 → controlzero-1.5.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: controlzero
-Version: 1.5.1
+Version: 1.5.3
 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.5.1 → controlzero-1.5.3}/controlzero/__init__.py

@@ -28,7 +28,7 @@ from controlzero.errors import (
 )
 from controlzero.policy_loader import load_policy
 
-__version__ = "1.5.1"
+__version__ = "1.5.3"
 
 __all__ = [
     "Client",

controlzero-1.5.3/controlzero/cli/hosts/__init__.py

@@ -0,0 +1,110 @@
+"""Host-agent adapter base for the hook-check command (1.5.3).
+
+Background
+----------
+Before 1.5.3 the hook subprocess wrote a single hard-coded JSON
+envelope to stdout regardless of which coding agent invoked it. Two
+bugs followed from that design:
+
+* Claude Code's PreToolUse hook spec only accepts
+  ``decision: "approve" | "block"``. The SDK emitted
+  ``decision: "allow"`` on the allow path, which Claude Code rejects
+  as ``Hook JSON output validation failed - (root): Invalid input``.
+  Claude Code then drops the hook decision and runs the call. Customer
+  saw a Write block correctly, then a PowerShell command bypass on
+  the same tool intent (2026-05-12).
+
+* Source detection relied on env vars Anthropic only exports on
+  macOS / Linux. On Windows the hook subprocess saw no
+  ``CLAUDECODE`` and ``detect_client_name()`` fell through to the
+  generic ``python-sdk`` default. The audit row mis-labelled the
+  agent as a direct SDK call.
+
+Both failure modes share a root: the SDK conflated "what decision
+did the policy engine make" with "what shape does the host expect
+on the wire." Splitting those two concerns is what this package
+does.
+
+Design
+------
+A ``HostAdapter`` owns three responsibilities for one host runtime:
+
+1. ``claim(payload, env)`` -- decide whether the inbound hook
+   invocation came from this host. First adapter to claim wins.
+   Adapters use BOTH stdin-payload signatures and env-var hints so
+   detection works even when the host's launcher strips env vars
+   (Windows Claude Code is the canonical case).
+2. ``render(decision)`` -- translate the canonical ``CZDecision``
+   into the JSON shape this host's hook validator accepts.
+3. ``canonical_source`` -- the backend ``audit.NormalizeSource``
+   alias (``claude_code`` / ``gemini_cli`` / ``codex_cli`` / etc.)
+   so the audit row's SOURCE column renders correctly.
+
+Adding a new host (Cursor, Windsurf, OpenClaw, Antigravity, the
+next agent that ships) is a single file in this package: subclass
+``HostAdapter``, append the instance to ``REGISTRY``. No edits to
+``cli/main.py``, ``audit_remote.py``, the policy engine, or the
+backend.
+
+A conservative ``UnknownHostAdapter`` sits at the bottom of the
+registry and is the final claim. It emits ``{}`` for allow (every
+known host treats no-decision as "proceed") and the universal
+``{"decision": "block", "reason": ...}`` for deny.
+"""
+
+from __future__ import annotations
+
+from controlzero.cli.hosts.base import CZDecision, HostAdapter
+from controlzero.cli.hosts.claude_code import ClaudeCodeAdapter
+from controlzero.cli.hosts.codex_cli import CodexCLIAdapter
+from controlzero.cli.hosts.gemini_cli import GeminiCLIAdapter
+from controlzero.cli.hosts.unknown import UnknownHostAdapter
+
+
+# Registry order = claim priority. First adapter whose ``claim()`` returns
+# True owns the call. The unknown fallback always claims so the order
+# above it MUST cover every supported host.
+#
+# IMPORTANT: keep this list ordered from most-specific to least-specific.
+# The Claude Code adapter goes first because Anthropic's PreToolUse
+# stdin payload is the most distinctive (it always carries a
+# ``tool_input`` envelope alongside a ``session_id`` field). Codex
+# / Gemini follow with their own signatures. Unknown is always last.
+REGISTRY: list[HostAdapter] = [
+    ClaudeCodeAdapter(),
+    CodexCLIAdapter(),
+    GeminiCLIAdapter(),
+    UnknownHostAdapter(),  # always claims; must stay at the tail
+]
+
+
+def select_adapter(payload: dict, env) -> HostAdapter:
+    """Pick the right host adapter for this hook invocation.
+
+    Iterates ``REGISTRY`` and returns the first adapter whose
+    ``claim()`` returns True. ``UnknownHostAdapter`` is the
+    backstop, so this function never raises.
+    """
+    for adapter in REGISTRY:
+        try:
+            if adapter.claim(payload, env):
+                return adapter
+        except Exception:  # noqa: BLE001
+            # An adapter's claim() must never crash the hook. If one
+            # does, skip it and try the next. Unknown is the floor.
+            continue
+    # Unreachable in practice (UnknownHostAdapter always claims),
+    # but mypy/runtime safety.
+    return REGISTRY[-1]
+
+
+__all__ = [
+    "CZDecision",
+    "HostAdapter",
+    "ClaudeCodeAdapter",
+    "CodexCLIAdapter",
+    "GeminiCLIAdapter",
+    "UnknownHostAdapter",
+    "REGISTRY",
+    "select_adapter",
+]

controlzero-1.5.3/controlzero/cli/hosts/base.py

@@ -0,0 +1,141 @@
+"""Canonical Decision + abstract HostAdapter contract.
+
+The CZ canonical Decision is the policy engine's single source of
+truth. It carries everything the audit log + downstream consumers
+need to reason about the decision. Adapters translate it on the
+way out to whatever shape the host hook validator accepts.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Mapping, Optional
+
+
+@dataclass(frozen=True)
+class CZDecision:
+    """The canonical Control Zero decision. Adapter-independent.
+
+    Adapters never construct one of these directly -- the hook_check
+    workflow builds it from the policy engine's
+    ``PolicyDecision`` + the resolved extractor + the tamper context.
+    Adapters consume it via ``HostAdapter.render(decision)`` to
+    produce the host-specific JSON envelope.
+
+    Fields
+    ------
+    effect : "allow" | "deny" | "warn"
+        Policy engine's verdict.
+    reason : str
+        Human-readable, branded message ("[Control Zero] ..."). Goes
+        to the agent (model-facing).
+    reason_code : str
+        Machine-readable enum (see ``controlzero._internal.enforcer``
+        REASON_CODE_*). Used by downstream consumers that branch on
+        why a decision happened.
+    policy_id : str
+        UUID of the rule that matched (or ``"<noop>"`` on no-rule
+        carve-outs). Empty string when not applicable.
+    tool : str
+        Canonical tool name post-extraction (e.g. ``"file_write"``,
+        ``"database"``, ``"network"``). Independent of host tool name.
+    method : str
+        Extracted method (e.g. SQL keyword for database, file path
+        for file_write). Empty string when not extractable.
+    extracted_action : str
+        ``f"{tool}:{method}"`` convenience shape the audit dashboard
+        renders. Empty string when not extractable.
+    semantic_class : str
+        Class-level normaliser parallel to ``method`` (e.g. SQL
+        ``read|write|admin|exec``). Empty outside SQL or when the
+        keyword has no class mapping.
+    tamper_detected : bool
+        True when the policy file HMAC or audit chain failed
+        verification. Carries through to host output so the agent
+        can surface a tamper notice.
+    audit_chain_broken : bool
+        True when the local audit chain hash sequence is broken.
+        Same surfacing rationale as ``tamper_detected``.
+    """
+
+    effect: str  # "allow" | "deny" | "warn"
+    reason: str
+    reason_code: str
+    policy_id: str = ""
+    tool: str = ""
+    method: str = ""
+    extracted_action: str = ""
+    semantic_class: str = ""
+    tamper_detected: bool = False
+    audit_chain_broken: bool = False
+
+    @property
+    def is_deny(self) -> bool:
+        return self.effect == "deny"
+
+    @property
+    def is_allow(self) -> bool:
+        return self.effect in ("allow", "warn")
+
+
+class HostAdapter:
+    """Per-host hook adapter. Subclass + register in REGISTRY.
+
+    A subclass needs three things:
+
+    * ``name`` -- short identifier used in logs ("claude_code").
+    * ``canonical_source`` -- backend ``audit.NormalizeSource`` alias
+      ("claude_code" / "gemini_cli" / "codex_cli" / "unknown").
+      This is what the audit row's SOURCE column resolves to so
+      the dashboard renders the right label.
+    * ``claim(payload, env)`` -- True when this adapter recognises
+      the inbound hook invocation. The registry tries adapters in
+      order; first claim wins. Use a combination of stdin payload
+      shape AND env vars so detection survives a host that doesn't
+      export the canonical env var on every platform.
+    * ``render(decision)`` -- map a ``CZDecision`` to the host's
+      JSON envelope. Return a ``dict`` ready for ``json.dumps``.
+
+    Subclasses may also override:
+
+    * ``extract_method(tool_name, tool_input)`` -- canonical-tool
+      extraction overrides. Most adapters inherit the shared
+      extractor from ``controlzero._internal.tool_extractors``; only
+      override when a host packs its tool args differently (e.g.
+      PowerShell's nested command syntax that needs parsing before
+      the canonical extractor can see ``file_write``).
+    """
+
+    #: Short identifier used in logs / metrics.
+    name: str = "base"
+
+    #: Backend ``audit.NormalizeSource`` alias. Must be one of the
+    #: canonical values in ``backend/internal/audit/source.go`` so
+    #: the dashboard renders the right label. Default is
+    #: ``"unknown"`` -- subclasses MUST override.
+    canonical_source: str = "unknown"
+
+    # -- detection --------------------------------------------------
+
+    def claim(self, payload: dict, env: Mapping[str, str]) -> bool:
+        """Return True if this adapter recognises this hook call."""
+        raise NotImplementedError
+
+    # -- rendering --------------------------------------------------
+
+    def render(self, decision: CZDecision) -> dict:
+        """Translate a CZDecision into this host's JSON envelope."""
+        raise NotImplementedError
+
+    # -- shared default extractor passthrough ----------------------
+
+    def extract_method(self, tool_name: str, tool_input: dict) -> tuple[str, str]:
+        """Default = shared extractor. Override for host-specific shells."""
+        from controlzero._internal.enforcer import extract_method  # local import to avoid cycle
+
+        return extract_method(tool_name, tool_input)
+
+
+# Convenience type-aliases used by tests.
+HostDecision = dict
+HostPayload = dict

controlzero-1.5.3/controlzero/cli/hosts/claude_code.py

@@ -0,0 +1,121 @@
+"""Claude Code PreToolUse hook adapter.
+
+Spec reference: https://docs.anthropic.com/en/docs/claude-code/hooks
+
+Stdin payload shape Claude Code sends (PreToolUse):
+::
+
+    {
+      "session_id": "uuid",
+      "transcript_path": "/path/to/transcript",
+      "cwd": "/working/dir",
+      "tool_name": "Write" | "Bash" | "Read" | "Edit" | ...,
+      "tool_input": { ...tool args... },
+      "hook_event_name": "PreToolUse"
+    }
+
+Stdout decision shape Claude Code accepts:
+::
+
+    {
+      "decision": "approve" | "block",   // optional; omit = proceed
+      "reason": "string"                  // shown to the model when block
+    }
+
+Critical: ``"decision": "allow"`` is **NOT** valid -- Claude Code
+rejects the hook output with
+``Hook JSON output validation failed - (root): Invalid input`` and
+falls back to its default (proceed). That is the 2026-05-12
+CloudShift PowerShell-bypass root cause.
+"""
+
+from __future__ import annotations
+
+from typing import Mapping
+
+from controlzero.cli.hosts.base import CZDecision, HostAdapter
+
+
+class ClaudeCodeAdapter(HostAdapter):
+    name = "claude_code"
+    canonical_source = "claude_code"
+
+    # Env-var hints (best-effort). On macOS / Linux the Anthropic
+    # launcher exports CLAUDECODE=1; on Windows the env-var may be
+    # missing depending on launcher version, so the stdin shape
+    # check below is the authoritative signal.
+    _ENV_HINTS = (
+        "CLAUDECODE",
+        "CLAUDE_CODE",
+        "CLAUDE_CODE_HOOK_VERSION",
+        "ANTHROPIC_CLI",
+    )
+
+    def claim(self, payload: dict, env: Mapping[str, str]) -> bool:
+        # Explicit env-var override always wins. ``CONTROLZERO_CLIENT``
+        # lets a power-user or CI environment force the right adapter.
+        if (env.get("CONTROLZERO_CLIENT") or "").strip().lower() in (
+            "claude-code",
+            "claude_code",
+            "claudecode",
+        ):
+            return True
+
+        # Env-var hint: any of the Anthropic-family vars present.
+        for hint in self._ENV_HINTS:
+            if env.get(hint):
+                return True
+
+        # Stdin payload signature: PreToolUse always carries
+        # ``hook_event_name`` (post-2024-10 schema) OR a
+        # ``session_id`` + ``transcript_path`` + ``tool_input``
+        # tuple. We accept either to handle older + newer Claude
+        # Code releases.
+        if isinstance(payload, dict):
+            if payload.get("hook_event_name") in (
+                "PreToolUse",
+                "PostToolUse",
+                "Notification",
+                "Stop",
+                "SubagentStop",
+            ):
+                return True
+            if (
+                "session_id" in payload
+                and "transcript_path" in payload
+                and ("tool_input" in payload or "tool_name" in payload)
+            ):
+                return True
+
+        return False
+
+    def render(self, decision: CZDecision) -> dict:
+        # Claude Code's PreToolUse hook spec:
+        #   decision: "approve" | "block" | (omit)
+        # On deny we emit "block". On allow we explicitly emit
+        # "approve" so Claude Code records that the hook ran AND
+        # decided yes (cleaner audit + bypasses any user-permission
+        # prompt that would otherwise interrupt the flow). The
+        # legacy "allow" string is REMOVED -- it crashed validation.
+        envelope: dict = {
+            "reason": decision.reason,
+            # Non-spec metadata fields. Claude Code is permissive
+            # about extras (per docs, "additional fields are
+            # ignored"). These keep the existing fields the SDK
+            # was emitting so any external consumer parsing the
+            # JSON keeps working.
+            "reason_code": decision.reason_code,
+            "tool": decision.tool,
+            "extracted_method": decision.method,
+            "action": decision.extracted_action,
+            "action_semantic_class": decision.semantic_class,
+            "tamper_detected": decision.tamper_detected,
+            "audit_chain_broken": decision.audit_chain_broken,
+        }
+        if decision.is_deny:
+            envelope["decision"] = "block"
+        else:
+            # Allow path. "approve" is the explicit positive signal;
+            # Claude Code accepts it without a permission prompt.
+            envelope["decision"] = "approve"
+        return envelope

controlzero-1.5.3/controlzero/cli/hosts/codex_cli.py

@@ -0,0 +1,54 @@
+"""Codex CLI PreToolUse hook adapter.
+
+Codex CLI ships its hook config at ``~/.codex/hooks.json`` with
+the PreToolUse contract verified March 2026:
+
+* Stdin: ``{ "tool_name", "tool_input", "session_id", "cwd" }``.
+* Stdout decision:
+  ``{ "decision": "allow" | "deny", "reason": "..." }``
+  or exit 2 + reason on stderr.
+* Codex launcher exports ``CODEX_HOME`` (path to ``~/.codex``),
+  ``CODEX_PROFILE`` (active profile name), and ``CODEX_CLI`` (a
+  mirror of the cross-SDK convention).
+"""
+
+from __future__ import annotations
+
+from typing import Mapping
+
+from controlzero.cli.hosts.base import CZDecision, HostAdapter
+
+
+class CodexCLIAdapter(HostAdapter):
+    name = "codex_cli"
+    canonical_source = "codex_cli"
+
+    _ENV_HINTS = ("CODEX_HOME", "CODEX_PROFILE", "CODEX_CLI")
+
+    def claim(self, payload: dict, env: Mapping[str, str]) -> bool:
+        if (env.get("CONTROLZERO_CLIENT") or "").strip().lower() in (
+            "codex-cli",
+            "codex_cli",
+            "codex",
+        ):
+            return True
+        for hint in self._ENV_HINTS:
+            if env.get(hint):
+                return True
+        return False
+
+    def render(self, decision: CZDecision) -> dict:
+        envelope: dict = {
+            "reason": decision.reason,
+            "reason_code": decision.reason_code,
+            "tool": decision.tool,
+            "extracted_method": decision.method,
+            "action": decision.extracted_action,
+            "action_semantic_class": decision.semantic_class,
+            "tamper_detected": decision.tamper_detected,
+            "audit_chain_broken": decision.audit_chain_broken,
+        }
+        # Codex spec uses allow / deny verbs (NOT Anthropic's
+        # approve / block).
+        envelope["decision"] = "deny" if decision.is_deny else "allow"
+        return envelope

controlzero-1.5.3/controlzero/cli/hosts/gemini_cli.py

@@ -0,0 +1,58 @@
+"""Gemini CLI BeforeTool hook adapter.
+
+Gemini CLI config lives at ``~/.gemini/settings.json``. The hook
+contract was verified against the public docs (April 2026):
+
+* Schema slot: ``hooks.BeforeTool[].hooks[]`` (array of
+  ``{ type: "command", command, timeout }``).
+* Stdin: ``{ tool_name, tool_input, session_id, cwd, ... }``.
+* Stdout decision: ``{ "decision": "deny", "reason": "..." }`` or
+  exit 2 to block. Anything else proceeds.
+
+Reference: https://www.geminicli.com/docs/hooks/reference
+"""
+
+from __future__ import annotations
+
+from typing import Mapping
+
+from controlzero.cli.hosts.base import CZDecision, HostAdapter
+
+
+class GeminiCLIAdapter(HostAdapter):
+    name = "gemini_cli"
+    canonical_source = "gemini_cli"
+
+    # Only true CLI runtime signals. ``GEMINI_API_KEY`` is set by
+    # anyone using Google's Python SDK directly and must NOT match
+    # (Bryan deny-deny incident, 2026-05-10 -- T78 / T92).
+    _ENV_HINTS = ("GEMINI_CLI", "GEMINI_SANDBOX", "GEMINI_SYSTEM_MD")
+
+    def claim(self, payload: dict, env: Mapping[str, str]) -> bool:
+        if (env.get("CONTROLZERO_CLIENT") or "").strip().lower() in (
+            "gemini-cli",
+            "gemini_cli",
+            "gemini",
+        ):
+            return True
+        for hint in self._ENV_HINTS:
+            if env.get(hint):
+                return True
+        return False
+
+    def render(self, decision: CZDecision) -> dict:
+        envelope: dict = {
+            "reason": decision.reason,
+            "reason_code": decision.reason_code,
+            "tool": decision.tool,
+            "extracted_method": decision.method,
+            "action": decision.extracted_action,
+            "action_semantic_class": decision.semantic_class,
+            "tamper_detected": decision.tamper_detected,
+            "audit_chain_broken": decision.audit_chain_broken,
+        }
+        if decision.is_deny:
+            envelope["decision"] = "deny"
+        # Gemini: omit decision on allow. Per docs, any non-deny
+        # body or exit 0 with no body proceeds.
+        return envelope

controlzero-1.5.3/controlzero/cli/hosts/unknown.py

@@ -0,0 +1,52 @@
+"""Conservative fallback adapter for unrecognised host runtimes.
+
+Always claims the call (final entry in REGISTRY) so the SDK never
+crashes when a brand-new agent invokes the hook before we have a
+dedicated adapter for it.
+
+Render rules:
+
+* On deny -- emit ``{"decision": "block", "reason": ...}``. Block
+  is universal: every host runtime we have seen treats ``block``
+  as the explicit "do not proceed" signal. If a future host uses
+  a different keyword we will catch it with a dedicated adapter
+  before the unknown fallback is hit.
+* On allow -- emit a body with NO ``decision`` field. Per every
+  known hook protocol, the absence of a decision means "no
+  opinion, proceed normally." Safer than guessing ``approve`` /
+  ``allow`` / ``ok`` and tripping a strict validator.
+"""
+
+from __future__ import annotations
+
+from typing import Mapping
+
+from controlzero.cli.hosts.base import CZDecision, HostAdapter
+
+
+class UnknownHostAdapter(HostAdapter):
+    name = "unknown"
+    # Canonical source value mapped in
+    # ``backend/internal/audit/source.go`` -- renders as ``--`` on
+    # the dashboard. Better than mislabelling.
+    canonical_source = "unknown"
+
+    def claim(self, payload: dict, env: Mapping[str, str]) -> bool:
+        # Final-fallback adapter: always claims.
+        return True
+
+    def render(self, decision: CZDecision) -> dict:
+        envelope: dict = {
+            "reason": decision.reason,
+            "reason_code": decision.reason_code,
+            "tool": decision.tool,
+            "extracted_method": decision.method,
+            "action": decision.extracted_action,
+            "action_semantic_class": decision.semantic_class,
+            "tamper_detected": decision.tamper_detected,
+            "audit_chain_broken": decision.audit_chain_broken,
+        }
+        if decision.is_deny:
+            envelope["decision"] = "block"
+        # Allow: NO decision field. Universal proceed.
+        return envelope