controlzero 1.4.2__tar.gz → 1.4.5__tar.gz

{controlzero-1.4.2 → controlzero-1.4.5}/.gitignore

@@ -194,7 +194,6 @@ SUMMARY_OFFENSIVE_*.md
 docs/deployment/
 docs/SSH_RECOVERY_GUIDE.md
 docs/HETZNER_OS_INSTALLATION.md
-docs/BACKUP_RECOVERY.md
 docs/VERCEL_SETUP_WEBAPPS.md
 scripts/fix-ssh-config.sh
 scripts/hetzner-post-install.sh
@@ -237,3 +236,6 @@ cz-revamp-live.png
 secrets/*.plain
 secrets/*.dec
 .claude/scheduled_tasks.lock
+
+# Local documentation, patent assets, and legal research (sensitive, never commit)
+doc_local/

controlzero-1.4.5/CHANGELOG.md

@@ -0,0 +1,71 @@
+# Changelog
+
+## 1.4.5 -- 2026-05-05
+
+### Added
+
+- **Cross-CLI canonical tool coverage** (#341). The shared
+  `tool_extractors.json` is now spec_version 2 and adds three new
+  canonical tools (`web_search`, `file_search`, `task`) plus extended
+  aliases so PowerShell shell-command emission, Codex CLI's
+  `apply_patch`, Gemini CLI's `read_many_files`, and the WebFetch
+  family all resolve to the existing canonical tools. One rule
+  `action: Bash:rm` now covers Claude Code, Gemini CLI, Codex CLI,
+  and PowerShell on Windows.
+- **SQL semantic-class layer** (#345/#350). New `sql_semantic_class()`
+  helper emits a parallel `database:read|write|admin|exec` action
+  alongside the existing per-keyword `database:SELECT|DROP|...`
+  action. Write portable rules like `allow: database:read` that cover
+  SELECT, EXPLAIN, SHOW, DESCRIBE, and CTE in one rule, without
+  enumerating every keyword the dialect accepts. Multi-statement
+  piggybacks like `SELECT 1; DROP TABLE x` correctly resolve to
+  `database:admin` so deny rules catch them. 21 new parity-test
+  fixtures (cross-SDK byte-identical with the Node sibling).
+
+### Documentation
+
+- New customer-facing reference at `docs/sdk/policies/canonical-tools.md`
+  explaining canonical tool names, alias coverage per host CLI, and
+  the contract for adding new clients.
+- New SQL semantic class section in `canonical-tools.md` plus updated
+  quickstart and read-only-database recipe.
+
+## 1.4.4 -- 2026-04-19
+
+### Fixed
+
+- Hosted mode now refreshes the policy bundle periodically (default 60 seconds) so dashboard edits reach long-running clients without a process restart. New `Client(refresh_interval_seconds=...)` constructor arg controls cadence: pass `None` to disable, `0` to refresh on every `guard()` call (tests only). Added public `Client.refresh()` for on-demand reloads and `Client.last_refreshed_at` for ops visibility. Swap is protected by a lock so multi-threaded callers never observe torn state.
+- Bundle translator now reads plural `actions: [...]` rules from the hosted bundle. Previously every such rule collapsed to a universal `*` match, turning narrow denies like `deny database:execute` into deny-all.
+- Backend now stamps `api_keys.last_used_at` on the SDK pull endpoint on both fresh-bundle and 304 paths, so the dashboard can distinguish "SDK online with cached bundle" from "SDK has never connected". Best-effort write; stamp failures never block the response.
+
+## 1.4.1 -- 2026-04-15
+
+### Added
+
+- `agent_name` arg + `CZ_AGENT_NAME` env var contract on the `Client` constructor (issue #71). Order: explicit arg > env > `default-agent`.
+- `CZ_DEBUG=1` (or `true`/`yes`/`on`) flips the controlzero logger to DEBUG at construction. Cheap escape hatch for support.
+- Optional install extras: `controlzero[google]`, `controlzero[openai]`, `controlzero[anthropic]` (issue #68). Pin the matching upstream SDK so users do not see import errors.
+- Cross-SDK action canonicalization parity test (issue #69). Mirrors the same fixture in the Node and Go SDKs.
+- Smoke + denial + error-propagation tests for the `wrap_google` integration (issue #68).
+
+## 1.4.0 -- 2026-04-15
+
+### Breaking changes
+
+- Integration wrappers now emit simplified action names (`llm:generate`, `embedding:generate`, `tool:call`) instead of provider-prefixed ones (`llm:openai:chat.completions.create`). Policies targeting the old action names must be updated. Provider and model move into `context` tags. See docs/integrations for current patterns.
+- Google integration rewritten against `google-genai` (deprecated `google.generativeai` removed). Install `google-genai`.
+- `integrations.langchain.agent.GovernedAgent` wrapping `AgentExecutor` is deprecated in LangChain v1.x. Use `integrations.langchain.modern.create_governed_agent`.
+
+### New integrations
+
+- `integrations.autogen` - first-party helper for autogen-agentchat v0.7+
+- `integrations.pydantic_ai` - first-party helper for pydantic-ai v1.x
+- `integrations.langchain.modern` - LangGraph create_agent pattern
+
+### New features
+
+- Policy rule `conditions` field is now evaluated in the local enforcer. Conditions are matched against merged context + args with glob patterns. All keys must match.
+
+### Enhancements
+
+- `integrations.litellm` - async + success/failure hooks for streaming audit.

{controlzero-1.4.2 → controlzero-1.4.5}/PKG-INFO

@@ -1,12 +1,12 @@
 Metadata-Version: 2.4
 Name: controlzero
-Version: 1.4.2
+Version: 1.4.5
 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
 Project-URL: Repository, https://github.com/controlzero/controlzero
 Project-URL: Examples, https://docs.controlzero.ai/sdk/integrations
-Author-email: Control Zero <hello@controlzero.ai>
+Author-email: Control Zero <team@controlzero.ai>
 License: Apache-2.0
 License-File: LICENSE
 Keywords: agents,ai,audit,governance,guardrails,llm,mcp,policy
@@ -23,9 +23,12 @@ Classifier: Topic :: Security
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: >=3.9
 Requires-Dist: click>=8.1.0
+Requires-Dist: cryptography>=41.0.0
+Requires-Dist: httpx>=0.25.0
 Requires-Dist: loguru>=0.7.0
 Requires-Dist: pydantic>=2.0.0
 Requires-Dist: pyyaml>=6.0
+Requires-Dist: zstandard>=0.22.0
 Provides-Extra: anthropic
 Requires-Dist: anthropic>=0.25.0; extra == 'anthropic'
 Provides-Extra: dev
@@ -79,7 +82,7 @@ print(cz.guard("read_file",   {"path": "/tmp/foo"}).decision)  # "allow"
 ## Install
 
 ```bash
-pip install control-zero
+pip install controlzero
 ```
 
 ## Why
@@ -251,6 +254,18 @@ cz = Client(api_key="cz_live_...", policy=local_policy, strict_hosted=True)
 # RuntimeError: manual policy override detected ...
 ```
 
+## Coding agent hooks
+
+`controlzero hook-check` runs inside Claude Code, Gemini CLI, and Codex CLI
+on every tool use and evaluates the call against your policy before it fires.
+It extracts a canonical `tool:method` from the tool arguments so rules can
+target `database:SELECT` vs `database:DROP`, or allow `Bash:git` while denying
+`Bash:rm`. Multi-statement SQL and compound shell commands are resolved to the
+most dangerous token, so a `SELECT ... ; DROP TABLE users;` payload matches
+`database:DROP`, not `database:SELECT`. See
+[Hook action extraction](https://docs.controlzero.ai/concepts/hook-extractor)
+for the full extraction rules, security model, and per-tool examples.
+
 ## Framework examples
 
 Full integration guides at [docs.controlzero.ai/sdk/integrations](https://docs.controlzero.ai/sdk/integrations):

{controlzero-1.4.2 → controlzero-1.4.5}/README.md

@@ -30,7 +30,7 @@ print(cz.guard("read_file",   {"path": "/tmp/foo"}).decision)  # "allow"
 ## Install
 
 ```bash
-pip install control-zero
+pip install controlzero
 ```
 
 ## Why
@@ -202,6 +202,18 @@ cz = Client(api_key="cz_live_...", policy=local_policy, strict_hosted=True)
 # RuntimeError: manual policy override detected ...
 ```
 
+## Coding agent hooks
+
+`controlzero hook-check` runs inside Claude Code, Gemini CLI, and Codex CLI
+on every tool use and evaluates the call against your policy before it fires.
+It extracts a canonical `tool:method` from the tool arguments so rules can
+target `database:SELECT` vs `database:DROP`, or allow `Bash:git` while denying
+`Bash:rm`. Multi-statement SQL and compound shell commands are resolved to the
+most dangerous token, so a `SELECT ... ; DROP TABLE users;` payload matches
+`database:DROP`, not `database:SELECT`. See
+[Hook action extraction](https://docs.controlzero.ai/concepts/hook-extractor)
+for the full extraction rules, security model, and per-tool examples.
+
 ## Framework examples
 
 Full integration guides at [docs.controlzero.ai/sdk/integrations](https://docs.controlzero.ai/sdk/integrations):

{controlzero-1.4.2 → controlzero-1.4.5}/controlzero/__init__.py

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

{controlzero-1.4.2 → controlzero-1.4.5}/controlzero/_internal/bundle.py

@@ -349,7 +349,7 @@ def _zstd_decompress(data: bytes) -> bytes:
 
     raise BundleVerificationError(
         "zstd decompression library not installed; "
-        "install with: pip install 'controlzero[hosted]' or pip install zstandard"
+        "install with: pip install -U controlzero (or pip install zstandard)"
     )
 
 
@@ -369,7 +369,41 @@ def translate_to_local_policy(payload: dict) -> dict:
 
     Policies are sorted by ``priority`` ascending so SDKs in every
     language produce identical decisions from identical input.
+
+    Schema 1.1 (#228 Phase 2) adds three top-level enforcement-default
+    knobs -- ``default_action``, ``default_on_missing``, and
+    ``default_on_tamper`` -- that the translator surfaces into the
+    local policy dict's ``settings`` block so downstream
+    :func:`controlzero.policy_loader.load_policy` can pick them up
+    unchanged. Missing or unknown values fall back to the canonical
+    deny/deny/warn (matches pre-1.1 hard-coded behaviour, so old
+    bundles keep working).
     """
+    # Lazy import to avoid a cycle: enforcer imports from this file
+    # via policy_loader via client. Importing at call time breaks the
+    # cycle cleanly while still letting translate_to_local_policy own
+    # the canonical-default fallback (one source of truth).
+    from controlzero._internal.enforcer import (
+        DEFAULT_BUNDLE_ACTION,
+        DEFAULT_BUNDLE_ON_MISSING,
+        DEFAULT_BUNDLE_ON_TAMPER,
+        VALID_DEFAULT_ACTIONS,
+        VALID_DEFAULT_ON_MISSING,
+        VALID_DEFAULT_ON_TAMPER,
+    )
+
+    default_action = payload.get("default_action")
+    if default_action not in VALID_DEFAULT_ACTIONS:
+        default_action = DEFAULT_BUNDLE_ACTION
+
+    default_on_missing = payload.get("default_on_missing")
+    if default_on_missing not in VALID_DEFAULT_ON_MISSING:
+        default_on_missing = DEFAULT_BUNDLE_ON_MISSING
+
+    default_on_tamper = payload.get("default_on_tamper")
+    if default_on_tamper not in VALID_DEFAULT_ON_TAMPER:
+        default_on_tamper = DEFAULT_BUNDLE_ON_TAMPER
+
     policies = payload.get("policies") or []
     policies = sorted(
         [p for p in policies if isinstance(p, dict)],
@@ -394,47 +428,184 @@ def translate_to_local_policy(payload: dict) -> dict:
                 flat.append(translated)
 
     if not flat:
-        # Empty policy set: default deny-all. An empty hosted project is
-        # not "everything allowed" -- it's "nothing configured yet."
+        # Empty policy set: synthetic catchall rule. The effect
+        # mirrors the bundle-level default_action so "empty bundle"
+        # continues to deliver the operator's chosen posture. Prior
+        # to #228 Phase 2 this was hard-coded to deny; now an org
+        # that ships an empty-bundle-with-default=allow gets the
+        # expected allow (with the same NO_ACTIVE_POLICIES
+        # reason_code so dashboards still bucket it as "nothing
+        # attached").
+        #
+        # Copy-choice note (2026-04-19, Bryan's P0): the previous
+        # message -- "No active policies. Define one in the Control Zero
+        # dashboard." -- presumed the user had not defined any policies.
+        # That presumption was wrong in the common case: the user had
+        # defined several, but the library-attachments state on the
+        # backend did not include any active attachment row, so the
+        # bundle arrived with zero policies while the dashboard Library
+        # tab still showed them. The new wording removes the
+        # presumption and points at the actual recovery action.
         flat.append({
-            "effect": "deny",
+            "effect": default_action,
             "action": "*",
             "reason": (
-                "No active policies. Define one in the Control Zero dashboard."
+                "No policies are active on this project. If the dashboard "
+                "shows attached policies, regenerate the policy bundle."
             ),
+            "reason_code": "NO_ACTIVE_POLICIES",
         })
 
-    return {"version": "1", "rules": flat}
+    return {
+        "version": "1",
+        "rules": flat,
+        "settings": {
+            "default_action": default_action,
+            "default_on_missing": default_on_missing,
+            "default_on_tamper": default_on_tamper,
+        },
+    }
+
+
+def make_bundle_missing_policy(
+    default_on_missing: Optional[str] = None,
+) -> dict:
+    """Build the synthetic local-policy dict used when the bundle cannot load.
+
+    Returned shape matches what :func:`translate_to_local_policy`
+    produces, so downstream :func:`controlzero.policy_loader.load_policy`
+    accepts it unchanged.
+
+    Args:
+        default_on_missing: Effect to apply -- ``"deny"`` or ``"allow"``.
+            ``None`` or an unknown value coerces to the canonical deny
+            default, matching the pre-#228 hard-coded behaviour.
+
+    The single catchall rule carries ``reason_code=BUNDLE_MISSING`` so
+    audit pipelines can distinguish "no bundle at all" (this path) from
+    "bundle loaded but empty" (``NO_ACTIVE_POLICIES``) and from
+    "rule set evaluated, nothing matched" (``NO_RULE_MATCH``).
+    """
+    from controlzero._internal.enforcer import (
+        DEFAULT_BUNDLE_ACTION,
+        DEFAULT_BUNDLE_ON_MISSING,
+        DEFAULT_BUNDLE_ON_TAMPER,
+        VALID_DEFAULT_ON_MISSING,
+    )
+
+    effect = default_on_missing if default_on_missing in VALID_DEFAULT_ON_MISSING else DEFAULT_BUNDLE_ON_MISSING
+    reason = (
+        "Policy bundle could not be loaded (never synced, backend "
+        "unreachable, or decrypt failed). "
+        f"Honoring default_on_missing={effect}."
+    )
+    return {
+        "version": "1",
+        "rules": [
+            {
+                "effect": effect,
+                "action": "*",
+                "reason": reason,
+                "reason_code": "BUNDLE_MISSING",
+            }
+        ],
+        "settings": {
+            # Stamp the resolved default triple onto the synthetic
+            # policy so downstream code that reads settings sees
+            # consistent values. default_action mirrors the missing
+            # effect so no-match behaviour is predictable.
+            "default_action": effect if effect in {"deny", "allow"} else DEFAULT_BUNDLE_ACTION,
+            "default_on_missing": effect,
+            "default_on_tamper": DEFAULT_BUNDLE_ON_TAMPER,
+        },
+    }
 
 
 def _translate_rule(rule: dict, policy_id: str) -> Optional[dict]:
-    """Translate a single backend rule to the local rule shape."""
-    effect = rule.get("effect") or rule.get("action") or "allow"
-    if effect not in ("allow", "deny", "warn", "audit"):
-        effect = "allow"
-
-    # Find the tool pattern. The backend may put it under several keys
-    # depending on the policy form (LLM, tool-call, etc.).
-    pattern = rule.get("tool")
-    if not pattern:
-        pattern = rule.get("pattern")
-    if not pattern:
+    """Translate a single backend rule to the local rule shape.
+
+    The backend (:file:`bundle_handler.go` ``PolicyRule``) emits rules
+    whose tool pattern lives under plural ``actions: [...]``. This
+    function used to ignore that key entirely and fell back to ``"*"``
+    for every such rule, causing e.g. a ``deny database:execute`` rule
+    to silently become ``deny *`` after round-tripping through the
+    bundle. Both the plural (backend wire-format) and the legacy
+    singular (``tool`` / ``pattern`` / ``action`` / ``match.tool``) forms
+    are now supported; plural wins when both are present.
+    """
+    # Accept several spellings of "effect". Policy engine has four
+    # canonical effects; anything else is treated as ``allow`` to stay
+    # fail-safe on forward-compat.
+    effect_raw = rule.get("effect")
+    if not effect_raw:
+        # Only fall back to rule["action"] for effect if it looks like
+        # one of the canonical effects. Otherwise "action" is a tool
+        # name and we should not use it here.
+        fallback = rule.get("action")
+        if fallback in ("allow", "deny", "warn", "audit"):
+            effect_raw = fallback
+    effect = effect_raw if effect_raw in ("allow", "deny", "warn", "audit") else "allow"
+
+    # Tool pattern resolution order:
+    #   1. plural ``actions`` (list, as emitted by the backend)
+    #   2. legacy singular ``tool`` / ``pattern``
+    #   3. legacy singular ``action`` (only if it is NOT an effect keyword)
+    #   4. nested ``match.tool`` / ``match.action``
+    #   5. default ``"*"`` (universal)
+    patterns: list[str] = []
+    raw_actions = rule.get("actions")
+    if isinstance(raw_actions, list):
+        patterns = [str(a) for a in raw_actions if isinstance(a, str) and a]
+
+    if not patterns:
+        candidate = rule.get("tool") or rule.get("pattern")
+        if candidate:
+            patterns = [str(candidate)]
+
+    if not patterns:
+        # Legacy singular "action" field -- only a tool pattern when
+        # it is NOT a canonical effect name (effect already captured
+        # above).
+        candidate = rule.get("action")
+        if candidate and candidate not in ("allow", "deny", "warn", "audit"):
+            patterns = [str(candidate)]
+
+    if not patterns:
         match = rule.get("match")
         if isinstance(match, dict):
-            pattern = match.get("tool") or match.get("action")
-    if not pattern:
+            candidate = match.get("tool") or match.get("action")
+            if candidate:
+                patterns = [str(candidate)]
+
+    if not patterns:
         # Final fallback: universal match. Combined with a non-allow
         # effect, this is still meaningful (e.g. deny-all).
-        pattern = "*"
+        patterns = ["*"]
 
     translated: dict = {
         "effect": effect,
-        "action": pattern,
+        # Emit plural ``actions`` so downstream
+        # :func:`controlzero.policy_loader.load_policy` can pass the
+        # full list through to :class:`PolicyRule.actions` unchanged.
+        # The loader accepts either ``action`` or ``actions``.
+        "actions": patterns if len(patterns) > 1 else patterns,
         "reason": rule.get("reason") or f"policy:{policy_id}",
     }
+    # Keep the singular ``action`` alias for single-pattern rules so
+    # older consumers that read the translated dict (tests, docs) still
+    # see a scalar. The loader prefers ``action`` when scalar.
+    if len(patterns) == 1:
+        translated["action"] = patterns[0]
 
     resources = rule.get("resources") or rule.get("resource")
     if resources:
         translated["resources"] = resources
 
+    # Propagate the machine-readable reason_code when the source rule
+    # carries one. Today only the synthetic empty-bundle deny (above)
+    # sets this; user-authored rules are unaffected.
+    rc = rule.get("reason_code")
+    if isinstance(rc, str) and rc:
+        translated["reason_code"] = rc
+
     return translated

{controlzero-1.4.2 → controlzero-1.4.5}/controlzero/_internal/enforcer.py

@@ -30,6 +30,64 @@ from controlzero._internal.dlp_scanner import (
 from controlzero._internal.types import PolicyRule
 
 
+# Canonical reason_code enum values. Stable machine-readable labels
+# so integrations + dashboards can branch on decision provenance
+# without regex-matching the human-readable `reason` string.
+#
+# Added 2026-04-19 after Bryan's P0: the SDK fail-closed with "No
+# active policies. Define one in the Control Zero dashboard." when
+# the user had in fact defined three; the three surfaces disagreed
+# because policy_attachments was empty. reason_code lets the hosted
+# dashboard, local-mode CLI, and audit ingestion distinguish the
+# fail-closed paths without parsing English text.
+#
+# Extended 2026-04-20 (#228 Phase 2) from 5 values to 8. Additions
+# are strictly additive: existing consumers that switch on the old
+# five keep working because the enum only grows. The three new codes
+# correspond to surfaces that previously had no machine label at all:
+#
+#   - RULE_MATCH         -- a user-authored rule fired (allow OR deny).
+#   - BUNDLE_MISSING     -- bundle could not be loaded (never synced,
+#                           backend 4xx/5xx, decrypt failure). Honors
+#                           `default_on_missing`.
+#   - DLP_BLOCKED        -- DLP rule overrode the policy-level allow.
+REASON_CODE_RULE_MATCH = "RULE_MATCH"
+REASON_CODE_NO_RULE_MATCH = "NO_RULE_MATCH"
+REASON_CODE_NO_ACTIVE_POLICIES = "NO_ACTIVE_POLICIES"
+REASON_CODE_BUNDLE_MISSING = "BUNDLE_MISSING"
+REASON_CODE_BUNDLE_TAMPERED = "BUNDLE_TAMPERED"
+REASON_CODE_MACHINE_QUARANTINED = "MACHINE_QUARANTINED"
+REASON_CODE_NETWORK_ERROR = "NETWORK_ERROR"
+REASON_CODE_DLP_BLOCKED = "DLP_BLOCKED"
+
+VALID_REASON_CODES = frozenset({
+    REASON_CODE_RULE_MATCH,
+    REASON_CODE_NO_RULE_MATCH,
+    REASON_CODE_NO_ACTIVE_POLICIES,
+    REASON_CODE_BUNDLE_MISSING,
+    REASON_CODE_BUNDLE_TAMPERED,
+    REASON_CODE_MACHINE_QUARANTINED,
+    REASON_CODE_NETWORK_ERROR,
+    REASON_CODE_DLP_BLOCKED,
+})
+
+# Canonical bundle-level default values. These must stay in lockstep
+# with the backend's `DefaultBundleAction` / `DefaultBundleOnMissing`
+# / `DefaultBundleOnTamper` constants (bundle_handler.go). They are
+# the values the SDK falls back to when a bundle (a) was built by an
+# old backend that predates schema 1.1 and has no default_* fields,
+# or (b) parses one of the fields as an unknown value. Matches the
+# pre-#228 hard-coded behaviour: no-match deny, missing-bundle deny,
+# tamper warn.
+DEFAULT_BUNDLE_ACTION = "deny"
+DEFAULT_BUNDLE_ON_MISSING = "deny"
+DEFAULT_BUNDLE_ON_TAMPER = "warn"
+
+VALID_DEFAULT_ACTIONS = frozenset({"deny", "allow", "warn"})
+VALID_DEFAULT_ON_MISSING = frozenset({"deny", "allow"})
+VALID_DEFAULT_ON_TAMPER = frozenset({"warn", "deny", "deny-all", "quarantine"})
+
+
 @dataclass
 class PolicyDecision:
     """Result of a policy evaluation.
@@ -38,13 +96,21 @@ class PolicyDecision:
         effect: One of "allow", "deny", "warn", "audit".
         decision: Alias for effect, for ergonomic Hello World code.
         policy_id: ID of the rule that matched, or None if no match.
-        reason: Human-readable reason for the decision.
+        reason: Human-readable reason for the decision. Keep this for
+            display / error messages; it can be translated, re-worded,
+            or localized without breaking consumers.
+        reason_code: Machine-readable code from the REASON_CODE_* set.
+            Stable across SDK versions -- automation should branch on
+            this, not on `reason`. Empty string when the decision
+            carries no structured reason (e.g. a plain user-policy
+            match).
         evaluated_rules: How many rules were checked before a match.
         dlp_findings: List of DLP match dicts for the audit trail.
     """
     effect: str
     policy_id: Optional[str] = None
     reason: Optional[str] = None
+    reason_code: str = ""
     evaluated_rules: int = 0
     dlp_findings: list[dict] = field(default_factory=list)
 
@@ -96,9 +162,16 @@ class PolicyEvaluator:
         self,
         rules: Optional[list[PolicyRule]] = None,
         dlp_scanner: Optional[DLPScanner] = None,
+        default_action: str = DEFAULT_BUNDLE_ACTION,
     ):
         self._rules: list[PolicyRule] = rules or []
         self._dlp_scanner: Optional[DLPScanner] = dlp_scanner
+        # Coerce unknown values to the canonical deny default. Keeps the
+        # evaluator safe even if a caller hands in a stale / bad value
+        # from a future schema -- SDK fails closed, never raises.
+        self._default_action: str = (
+            default_action if default_action in VALID_DEFAULT_ACTIONS else DEFAULT_BUNDLE_ACTION
+        )
 
     def load(self, rules: list[PolicyRule]) -> None:
         """Replace the rule set."""
@@ -108,6 +181,24 @@ class PolicyEvaluator:
         """Set or replace the DLP scanner."""
         self._dlp_scanner = scanner
 
+    def set_default_action(self, action: str) -> None:
+        """Replace the no-match default action.
+
+        Called by the Client after a hosted-policy refresh so the
+        bundle's resolved ``default_action`` takes effect without
+        rebuilding the evaluator. Unknown values coerce to the
+        canonical deny default, matching pre-#228 fail-closed
+        behaviour.
+        """
+        self._default_action = (
+            action if action in VALID_DEFAULT_ACTIONS else DEFAULT_BUNDLE_ACTION
+        )
+
+    @property
+    def default_action(self) -> str:
+        """The effective no-match default action."""
+        return self._default_action
+
     def evaluate(
         self,
         tool: str,
@@ -128,24 +219,58 @@ class PolicyEvaluator:
             PolicyDecision. Always returns; never raises.
         """
         action = f"{tool}:{method}"
-        resource = (context or {}).get("resource")
+
+        # Semantic-class layer (#345): when the action carries a
+        # canonical SQL class (database:read|write|admin|exec) the
+        # evaluator matches rules against BOTH the per-keyword action
+        # above AND this class action. A rule whose actions list
+        # contains `database:read` therefore fires for any read-shaped
+        # SQL (SELECT, EXPLAIN, SHOW, CTE, ...) regardless of dialect
+        # spelling, while existing per-keyword rules
+        # (`database:DROP`) keep working unchanged. Two sources for
+        # the class action: the caller may provide it in
+        # ``context['action_semantic_class']`` (used by the hook-check
+        # CLI), or we derive it on the fly from ``args['sql']`` when
+        # the tool is ``database`` and no class was provided.
+        ctx_dict = context or {}
+        semantic_action = ctx_dict.get("action_semantic_class") or ""
+        if not semantic_action and tool == "database" and args:
+            from controlzero._internal.hook_extractors import sql_semantic_class
+            sql_text = args.get("sql") if isinstance(args, dict) else None
+            if isinstance(sql_text, str) and sql_text:
+                cls = sql_semantic_class(sql_text)
+                if cls:
+                    semantic_action = f"{tool}:{cls}"
+        candidate_actions: list[str] = [action]
+        if semantic_action and semantic_action != action:
+            candidate_actions.append(semantic_action)
+
+        resource = ctx_dict.get("resource")
         evaluated = 0
 
         for rule in self._rules:
             evaluated += 1
-            if not _glob_any(rule.actions, action):
+            if not any(_glob_any(rule.actions, a) for a in candidate_actions):
                 continue
             if rule.resources:
                 if not resource or not _glob_any(rule.resources, resource):
                     continue
             if not self._conditions_match(rule.conditions, context, args):
                 continue
+            # Prefer the rule-declared reason_code (only synthetic
+            # rules set one today -- e.g. the empty-bundle
+            # NO_ACTIVE_POLICIES deny). Everything else defaults to
+            # RULE_MATCH so consumers can tell a user-authored rule
+            # firing apart from the no-match fallthrough below.
+            rule_code = getattr(rule, "reason_code", "") or ""
+            decision_code = rule_code or REASON_CODE_RULE_MATCH
             decision = PolicyDecision(
                 effect=rule.effect,
                 policy_id=rule.id or rule.name or None,
                 # User-provided reason wins. Falls back to canned text only if
                 # the rule had no `reason:` field in the source policy.
                 reason=rule.reason or f"Matched rule {rule.id or rule.name}".strip(),
+                reason_code=decision_code,
                 evaluated_rules=evaluated,
             )
             # DLP scan: only when the policy decision is "allow" and args exist
@@ -153,10 +278,27 @@ class PolicyEvaluator:
                 decision = self._apply_dlp_scan(decision, args)
             return decision
 
-        # Fail-closed default. No matching rule means deny.
+        # No-match default. Pre-#228 this was hard-coded to deny; as
+        # of Phase 2 the bundle can override it (default_action =
+        # deny|allow|warn). The reason_code stays NO_RULE_MATCH so
+        # "rule set evaluated, nothing matched" is distinguishable
+        # from "bundle was empty" (NO_ACTIVE_POLICIES) and "bundle
+        # was missing" (BUNDLE_MISSING).
+        #
+        # Reason-text note: the historical "fail-closed default"
+        # phrase is kept for the deny case so downstream consumers
+        # that regex-match the reason string (a pattern we actively
+        # discourage -- use reason_code instead) keep working.
+        if self._default_action == "deny":
+            reason = "No matching policy rule (fail-closed default)"
+        elif self._default_action == "allow":
+            reason = "No matching policy rule (default_action=allow)"
+        else:  # "warn"
+            reason = "No matching policy rule (default_action=warn)"
         return PolicyDecision(
-            effect="deny",
-            reason="No matching policy rule (fail-closed default)",
+            effect=self._default_action,
+            reason=reason,
+            reason_code=REASON_CODE_NO_RULE_MATCH,
             evaluated_rules=evaluated,
         )
 
@@ -224,6 +366,13 @@ class PolicyEvaluator:
                     f"DLP rule '{blocking.rule_name}' matched "
                     f"{blocking.category} content in tool arguments"
                 ),
+                # DLP_BLOCKED means: the tool-name policy said allow,
+                # but a DLP rule found a hit in the arguments and
+                # overrode the decision. Dashboards bucket this as a
+                # different failure surface from a rule-authored deny
+                # so ops can tell "my tool is blocked" from "my
+                # argument tripped a DLP guard" apart.
+                reason_code=REASON_CODE_DLP_BLOCKED,
                 evaluated_rules=decision.evaluated_rules,
                 dlp_findings=findings,
             )