controlzero 1.11.8__tar.gz → 1.11.9__tar.gz

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

@@ -1,5 +1,49 @@
 # Changelog
 
+## 1.11.9 -- 2026-06-25 (policy-posture remediation: honest hosted/local CLI, per-agent keys, key-validity diagnostics)
+
+### Added
+
+- **Severity-level CLI output (`controlzero.cli.output`).** All CLI prose now
+  routes through one renderer with INFO / WARNING / SUCCESS / ERROR levels:
+  WARNING + ERROR go to stderr, INFO + SUCCESS to stdout, colour honours
+  `NO_COLOR` / `CONTROLZERO_NO_COLOR` / `TERM=dumb` / non-TTY. No emojis. The
+  hook decision path and wire payloads are untouched -- the renderer is never
+  used inside `hook_check`, so decision reasons emit verbatim.
+- **Per-integration (per-agent) API keys.** Each coding agent can bind its own
+  project key at `integrations/<agent>/config.yaml`. Resolution order is
+  `env (explicit) > per-agent (for that agent) > global`, fully back-compatible
+  (no per-agent key -> falls back to the global key). Per-agent dir `0700` /
+  file `0600`; the raw key is never echoed. This lets one machine run different
+  agents bound to different projects, each enforcing its own hosted bundle.
+- **`controlzero status` rewrite.** Shows resolved runtime truth (mode, config
+  source, key, enrolled, audit dest) plus a per-agent bindings table and
+  per-key backend validity (active / expired / revoked) so a rejected key is
+  diagnosable from the CLI instead of only via the coarse E1101 at first tool
+  call (#1472).
+
+### Changed
+
+- **Honest hosted/local posture messaging.** One canonical wording each for the
+  HOSTED and LOCAL install paths, routed through every installer. The HOSTED
+  banner states that the local `policy.yaml` is IGNORED while an API key is set,
+  and the unmatched-tool default (DENY fail-closed unless the project is set to
+  Allow by default) -- removing the "install said ALLOW ALL but runtime denied"
+  ambiguity.
+- **Archive-on-hosted.** When an API key is configured, the local `policy.yaml`
+  (and its `.sig`) is moved (not deleted) into `archive/policy-<UTC-ts>.yaml`,
+  symlink-safe, every error non-fatal -- a hosted machine never silently runs a
+  stale local policy.
+
+### Fixed
+
+- **`synthetic:UNATTRIBUTED_DENY`** added to the synthetic policy-id catalog so
+  an unattributed fail-closed deny renders a stable, documented policy id across
+  every surface instead of an opaque blank (#1472).
+- **Audit attribution.** SDK audit wire builders forward `project_id`
+  unconditionally so signed-sink audit events are attributed to the right
+  project (pairs with the backend ingest fix).
+
 ## 1.11.8 -- 2026-06-22 (DLP mask enforcement + I/O capture: enrolled-machine capture fix + server-side PII redaction)
 
 ### Added

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: controlzero
-Version: 1.11.8
+Version: 1.11.9
 Summary: AI agent governance: policies, audit, and observability for tool calls. Works locally with no signup.
 Project-URL: Homepage, https://controlzero.ai
 Project-URL: Documentation, https://docs.controlzero.ai
@@ -185,6 +185,32 @@ rules:
 Rules are evaluated top to bottom. The first match wins. If no rule matches,
 the call is denied (fail-closed).
 
+## Localized block messages (`reason_localized`)
+
+The `reason` shown when a rule fires is plain UTF-8 text, so you can write it
+in any language. To serve more than one language from the same policy, add a
+`reason_localized` map and select a locale with the `CONTROLZERO_LOCALE`
+environment variable (e.g. `ko`, `ko-KR`):
+
+```yaml
+version: '1'
+rules:
+  - deny: 'delete_*'
+    reason: 'Deletes need human approval' # English default
+    reason_localized:
+      ko: '삭제는 사람의 승인이 필요합니다'
+  - allow: '*'
+```
+
+- When `CONTROLZERO_LOCALE` is unset (or set to a locale the rule has no entry
+  for), the plain `reason` is used -- existing behavior is unchanged.
+- The SDK's own built-in messages (no-rule-match, DLP block, empty/observe
+  bundle) ship an English default plus a Korean translation, selected the same
+  way. The packs are pure in-binary maps (no runtime i18n dependency), so this
+  is air-gap safe.
+- Localization is display-only: it never changes which rule matches or the
+  decided effect.
+
 ## Tamper detection and quarantine
 
 The policy YAML supports a `settings:` section that controls how the SDK

{controlzero-1.11.8 → controlzero-1.11.9}/README.md

@@ -131,6 +131,32 @@ rules:
 Rules are evaluated top to bottom. The first match wins. If no rule matches,
 the call is denied (fail-closed).
 
+## Localized block messages (`reason_localized`)
+
+The `reason` shown when a rule fires is plain UTF-8 text, so you can write it
+in any language. To serve more than one language from the same policy, add a
+`reason_localized` map and select a locale with the `CONTROLZERO_LOCALE`
+environment variable (e.g. `ko`, `ko-KR`):
+
+```yaml
+version: '1'
+rules:
+  - deny: 'delete_*'
+    reason: 'Deletes need human approval' # English default
+    reason_localized:
+      ko: '삭제는 사람의 승인이 필요합니다'
+  - allow: '*'
+```
+
+- When `CONTROLZERO_LOCALE` is unset (or set to a locale the rule has no entry
+  for), the plain `reason` is used -- existing behavior is unchanged.
+- The SDK's own built-in messages (no-rule-match, DLP block, empty/observe
+  bundle) ship an English default plus a Korean translation, selected the same
+  way. The packs are pure in-binary maps (no runtime i18n dependency), so this
+  is air-gap safe.
+- Localization is display-only: it never changes which rule matches or the
+  decided effect.
+
 ## Tamper detection and quarantine
 
 The policy YAML supports a `settings:` section that controls how the SDK

{controlzero-1.11.8 → controlzero-1.11.9}/controlzero/__init__.py

@@ -41,7 +41,7 @@ from controlzero.hitl.grant_protocol import (
 from controlzero.policy_loader import load_policy
 from controlzero.secrets import SecretRef, SecretStr, secret_ref
 
-__version__ = "1.11.8"
+__version__ = "1.11.9"
 
 __all__ = [
     "Client",

controlzero-1.11.9/controlzero/_internal/_messages.py

@@ -0,0 +1,273 @@
+"""In-binary localization pack for the SDK-GENERATED decision reasons.
+
+Why this exists ( checklist #25, gh#1439)
+--------------------------------------------------
+The user-facing ``reason`` string is carried end-to-end as UTF-8, so an
+operator can already localize ANY rule today by typing the target-language
+text into that rule's ``reason:`` -- or, for per-locale overrides, into the
+new ``reason_localized:`` map (a ``{locale: message}`` dict on the rule). That
+covers operator-authored rules. This module covers the OTHER half: the
+messages the SDK itself GENERATES for the no-rule-match / empty-bundle /
+missing-bundle / tampered / DLP paths. Those have no operator-authored text to
+carry, so they need an in-binary pack.
+
+No runtime i18n library is used: these are pure dict lookups, which keeps the
+SDK air-gap safe (the PoC ships self-hosted with no network).
+
+Contract
+--------
+- The ``en`` value is the single source of truth for the inline paths that now
+  read it (no-match, DLP, tamper, quarantine): it MUST stay byte-identical to
+  the legacy hard-coded string so existing consumers that regex-match the
+  ``reason`` text are unaffected. ``tests/test_localized_reason.py`` pins this.
+- English remains the literal DEFAULT whenever ``CONTROLZERO_LOCALE`` is unset
+  or a locale key is missing from a pack entry.
+- For the synthetic empty/missing-bundle rules the English text stays on the
+  rule's ``reason`` (unchanged bundle output); the pack supplies ONLY the
+  localized (non-en) override, looked up by the rule's ``reason_code``.
+
+KOREAN COPY IS A PROFESSIONAL DRAFT and MUST be reviewed/approved by the customer
+before being presented as final. See KO_Localization_2026-06-22 in the project
+vault. The English default is never blocked on that review.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Optional
+
+DEFAULT_LOCALE = "en"
+
+
+def resolve_locale(explicit: Optional[str] = None) -> str:
+    """Resolve the active locale.
+
+    Precedence: explicit arg > ``CONTROLZERO_LOCALE`` env > "" (English).
+    Returned lower-cased and stripped so lookups are case-insensitive.
+    """
+    if explicit:
+        return explicit.strip().lower()
+    return (os.environ.get("CONTROLZERO_LOCALE", "") or "").strip().lower()
+
+
+def _locale_candidates(locale: str) -> list[str]:
+    """Return lookup candidates for a locale, most specific first.
+
+    ``ko-KR`` / ``ko_KR`` -> ``["ko-kr", "ko"]`` so a pack keyed by the bare
+    primary subtag ("ko") still matches a region-qualified request.
+    """
+    loc = (locale or "").strip().lower()
+    if not loc:
+        return []
+    out = [loc]
+    for sep in ("-", "_"):
+        if sep in loc:
+            primary = loc.split(sep, 1)[0]
+            if primary and primary not in out:
+                out.append(primary)
+            break
+    return out
+
+
+# message key -> {locale -> template}. Templates use str.format placeholders
+# ({action}, {rule_name}, {category}). The English values for the inline paths
+# (NO_RULE_MATCH:*, DLP_BLOCKED:*, BUNDLE_TAMPERED, MACHINE_QUARANTINED) are
+# byte-identical to the legacy strings. For the synthetic-rule codes
+# (OBSERVE_MODE_NO_POLICY, NO_ACTIVE_POLICIES, BUNDLE_MISSING) the English is
+# documentation/parity only -- the live English comes from the rule's reason.
+SYSTEM_MESSAGES: dict[str, dict[str, str]] = {
+    # No-rule-match fallthrough (the most common block a Korean operator sees).
+    "NO_RULE_MATCH:deny": {
+        "en": (
+            "No matching policy rule for '{action}' (fail-closed default; "
+            "default_on_missing=deny). This tool is neither allowed nor "
+            "denied by any rule in your hosted policy, so it is blocked. "
+            "Add a rule that allows it (e.g. allow: '*' as a catch-all, or "
+            "allow: '{action}'), or set the project/org default to allow, "
+            "in the Control Zero dashboard."
+        ),
+        # ko: "'{action}'에 일치하는 정책 규칙이 없어 기본 차단됩니다 ..."
+        "ko": (
+            "'{action}'에 일치하는 정책 규칙이 없습니다(기본 차단; "
+            "default_on_missing=deny). 이 도구는 정책에서 허용되지도 "
+            "거부되지도 않았으므로 차단됩니다. Control Zero 대시보드에서 "
+            "이를 허용하는 규칙을 추가하거나(예: 포괄 규칙 allow: '*' 또는 "
+            "allow: '{action}'), 프로젝트/조직 기본값을 allow로 "
+            "설정하십시오."
+        ),
+    },
+    "NO_RULE_MATCH:allow": {
+        "en": "No matching policy rule for '{action}' (default_action=allow)",
+        # ko: "'{action}'에 일치하는 정책 규칙이 없습니다 (default_action=allow)"
+        "ko": "'{action}'에 일치하는 정책 규칙이 없습니다(default_action=allow)",
+    },
+    "NO_RULE_MATCH:warn": {
+        "en": "No matching policy rule for '{action}' (default_action=warn)",
+        # ko: "'{action}'에 일치하는 정책 규칙이 없습니다 (default_action=warn)"
+        "ko": "'{action}'에 일치하는 정책 규칙이 없습니다(default_action=warn)",
+    },
+    # DLP overrides (the tool-name policy allowed, but a DLP rule vetoed).
+    "DLP_BLOCKED:match": {
+        "en": (
+            "DLP rule '{rule_name}' matched {category} content in tool "
+            "arguments"
+        ),
+        # ko: "DLP 규칙 '{rule_name}'이(가) 도구 인자에서 {category} 콘텐츠와 ..."
+        "ko": (
+            "DLP 규칙 '{rule_name}'이(가) 도구 인자에서 {category} "
+            "콘텐츠와 일치하여 호출이 차단되었습니다."
+        ),
+    },
+    "DLP_BLOCKED:boundary": {
+        "en": (
+            "DLP rule '{rule_name}' matched {category} content that spans "
+            "argument boundaries and could not be safely masked; blocking "
+            "(fail-closed) rather than forwarding an un-redacted value"
+        ),
+        # ko: "DLP 규칙 '{rule_name}'이(가) 인자 경계에 걸친 {category} 콘텐츠와 ..."
+        "ko": (
+            "DLP 규칙 '{rule_name}'이(가) 인자 경계에 걸쳐 있는 "
+            "{category} 콘텐츠와 일치하여 안전하게 마스킹할 수 없으므로, "
+            "마스킹되지 않은 값을 전달하는 대신 차단합니다(기본 차단)."
+        ),
+    },
+    # Tamper / quarantine (constructed in client.py + cli/main.py).
+    "BUNDLE_TAMPERED": {
+        "en": (
+            "Policy tampering detected. Call blocked by tamper enforcement "
+            "policy."
+        ),
+        # ko: "정책 변조가 감지되었습니다. 변조 시행 정책에 의해 호출이 차단되었습니다."
+        "ko": (
+            "정책 변조가 감지되었습니다. 변조 시행 정책에 의해 호출이 "
+            "차단되었습니다."
+        ),
+    },
+    # CLI hook-check tamper enforcement (cli/main.py). Carries a {source}
+    # discriminator (policy_hmac / audit_chain) and the [Control Zero] prefix.
+    "BUNDLE_TAMPERED:cli": {
+        "en": (
+            "[Control Zero] Tamper detected ({source}). Blocked by enforcement "
+            "policy."
+        ),
+        # ko: "[Control Zero] 변조가 감지되었습니다({source}). 시행 정책에 의해 ..."
+        "ko": (
+            "[Control Zero] 변조가 감지되었습니다({source}). 시행 정책에 "
+            "의해 차단되었습니다."
+        ),
+    },
+    "MACHINE_QUARANTINED": {
+        "en": (
+            "Machine quarantined: policy tampering detected. All calls denied "
+            "until recovery."
+        ),
+        # ko: "머신이 격리되었습니다: 정책 변조가 감지되었습니다. 복구될 때까지 ..."
+        "ko": (
+            "머신이 격리되었습니다: 정책 변조가 감지되었습니다. 복구될 "
+            "때까지 모든 호출이 거부됩니다."
+        ),
+    },
+    # Synthetic empty / missing-bundle rules. English here is parity-only --
+    # the live English comes from the rule's `reason` (bundle output unchanged);
+    # the enforcer reads ONLY the localized (non-en) value below, by code.
+    "OBSERVE_MODE_NO_POLICY": {
+        "en": (
+            "OBSERVE MODE: no policies are active on this project, so "
+            "Control Zero is monitoring and auditing tool calls but "
+            "NOT enforcing -- every call is allowed and logged. Attach "
+            "a policy (or set the empty-project default to deny) in the "
+            "Control Zero dashboard to start enforcing."
+        ),
+        # ko: "관찰 모드: 이 프로젝트에 활성 정책이 없으므로 ... 차단하지 않습니다 ..."
+        "ko": (
+            "관찰 모드: 이 프로젝트에 활성 정책이 없으므로 Control Zero는 "
+            "도구 호출을 모니터링하고 감사 기록을 남기지만 차단하지는 "
+            "않습니다 -- 모든 호출이 허용되고 기록됩니다. 시행을 시작하려면 "
+            "Control Zero 대시보드에서 정책을 연결하거나(또는 빈 프로젝트 "
+            "기본값을 deny로 설정) 하십시오."
+        ),
+    },
+    "NO_ACTIVE_POLICIES": {
+        "en": (
+            "No policies are active on this project. If the dashboard "
+            "shows attached policies, regenerate the policy bundle."
+        ),
+        # ko: "이 프로젝트에 활성 정책이 없습니다. 대시보드에 연결된 정책이 표시되면 ..."
+        "ko": (
+            "이 프로젝트에 활성 정책이 없습니다. 대시보드에 연결된 정책이 "
+            "표시되면 정책 번들을 다시 생성하십시오."
+        ),
+    },
+    # BUNDLE_MISSING covers two English variants (degraded bundle vs. bundle
+    # not loaded), both reason_code=BUNDLE_MISSING. The localized override is a
+    # single accurate general message; the precise English stays on the rule.
+    "BUNDLE_MISSING": {
+        "en": (
+            "Policy bundle could not be loaded or produced zero enforceable "
+            "rules. Control Zero is failing CLOSED (deny) rather than allowing "
+            "every tool call. Regenerate the policy bundle in the Control Zero "
+            "dashboard; contact support if this persists."
+        ),
+        # ko: "정책 번들을 로드할 수 없거나 시행 가능한 규칙을 생성하지 못했습니다 ..."
+        "ko": (
+            "정책 번들을 로드할 수 없거나 시행 가능한 규칙을 생성하지 "
+            "못했습니다(미동기화, 백엔드 연결 불가, 복호화 실패 또는 손상/"
+            "부분/오래된 번들). Control Zero는 모든 호출을 허용하는 대신 "
+            "차단(기본 차단)합니다. Control Zero 대시보드에서 정책 번들을 "
+            "다시 생성하고, 문제가 지속되면 지원팀에 문의하십시오."
+        ),
+    },
+}
+
+
+def system_message(key: str, locale: Optional[str] = None, **fmt: object) -> Optional[str]:
+    """Return the fully-resolved system message for ``key``, English-default.
+
+    Resolution: ``pack[key][locale]`` (region subtag tolerated) falling back to
+    ``pack[key]["en"]``. Returns ``None`` only when ``key`` is unknown. Used by
+    the inline paths (no-match, DLP, tamper, quarantine) where the pack is the
+    source of the English text.
+    """
+    entry = SYSTEM_MESSAGES.get(key)
+    if not entry:
+        return None
+    template = None
+    for cand in _locale_candidates(resolve_locale(locale)):
+        if cand in entry:
+            template = entry[cand]
+            break
+    if template is None:
+        template = entry.get(DEFAULT_LOCALE)
+    if template is None:
+        return None
+    if fmt:
+        try:
+            return template.format(**fmt)
+        except (KeyError, IndexError):
+            return template
+    return template
+
+
+def localized_override(key: str, locale: Optional[str] = None, **fmt: object) -> Optional[str]:
+    """Return ONLY a non-English localized message for ``key``, else ``None``.
+
+    Unlike :func:`system_message` this never falls back to English. Used for
+    the synthetic empty/missing-bundle rules, whose English text stays on the
+    rule's ``reason`` (bundle output unchanged) -- the enforcer applies this
+    override only when an actual localized string exists for the active locale.
+    """
+    entry = SYSTEM_MESSAGES.get(key)
+    if not entry:
+        return None
+    for cand in _locale_candidates(resolve_locale(locale)):
+        if cand == DEFAULT_LOCALE:
+            continue
+        if cand in entry:
+            template = entry[cand]
+            if fmt:
+                try:
+                    return template.format(**fmt)
+                except (KeyError, IndexError):
+                    return template
+            return template
+    return None

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

@@ -943,4 +943,19 @@ def _translate_rule(rule: dict, policy_id: str) -> Optional[dict]:
     if escalate is not None:
         translated["escalate_on_deny"] = bool(escalate)
 
+    # #25 (gh#1439): the SAME allowlist-strip trap (the gh#175 /
+    # #1303 family). A backend-signed bundle copies only an allowlist of
+    # rule fields into the local rule shape; without this line a hosted
+    # policy's `reason_localized` map is silently dropped and a Korean
+    # operator would see only the English fallback. Forward it intact.
+    # (The backend bundle wire struct must ALSO carry the field -- see
+    # bundle_handler.go PolicyRule -- or it never reaches this translator.)
+    reason_localized = rule.get("reason_localized")
+    if isinstance(reason_localized, dict) and reason_localized:
+        translated["reason_localized"] = {
+            str(k).strip().lower(): str(v)
+            for k, v in reason_localized.items()
+            if isinstance(k, str) and isinstance(v, str)
+        }
+
     return translated

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

@@ -26,6 +26,11 @@ from controlzero._internal.dlp_scanner import (
     DLPScanner,
     extract_text_from_args,
 )
+from controlzero._internal._messages import (
+    localized_override,
+    resolve_locale,
+    system_message,
+)
 from controlzero._internal.types import PolicyRule
 
 # Phase 1B (#451): policy engine version stamped onto every
@@ -149,6 +154,10 @@ SYNTHETIC_BUNDLE_MISSING = "synthetic:BUNDLE_MISSING"
 SYNTHETIC_RESOURCE_GATE_SKIP = "synthetic:RESOURCE_GATE_SKIP"
 SYNTHETIC_QUARANTINE = "synthetic:QUARANTINE"
 SYNTHETIC_ENGINE_UNAVAILABLE = "synthetic:ENGINE_UNAVAILABLE"
+# Backend-stamped (audit ingest) on a deny that arrived with an empty
+# policy_id -- e.g. an old field SDK or a CLI fail-closed path. SDKs do not
+# emit it; it is listed here so downstream consumers recognize it.
+SYNTHETIC_UNATTRIBUTED_DENY = "synthetic:UNATTRIBUTED_DENY"
 
 VALID_SYNTHETIC_POLICY_IDS = frozenset({
     SYNTHETIC_NO_RULE_MATCH,
@@ -158,6 +167,7 @@ VALID_SYNTHETIC_POLICY_IDS = frozenset({
     SYNTHETIC_RESOURCE_GATE_SKIP,
     SYNTHETIC_QUARANTINE,
     SYNTHETIC_ENGINE_UNAVAILABLE,
+    SYNTHETIC_UNATTRIBUTED_DENY,
 })
 
 # Canonical bundle-level default values. These must stay in lockstep
@@ -224,7 +234,7 @@ class PolicyDecision:
     reason_code: str = ""
     evaluated_rules: int = 0
     dlp_findings: list[dict] = field(default_factory=list)
-    # DLP MASK action (#1278 kakaopay checklist #6, parity with the gateway
+    # DLP MASK action (#1278 the customer checklist #6, parity with the gateway
     # ``response_dlp.mask_text`` path). When a DLP rule matches with
     # action="mask" on an ALLOW decision, the enforcer redacts the sensitive
     # spans in the tool arguments (modify-and-proceed) and stashes the
@@ -329,6 +339,7 @@ class PolicyEvaluator:
         rules: Optional[list[PolicyRule]] = None,
         dlp_scanner: Optional[DLPScanner] = None,
         default_action: str = DEFAULT_BUNDLE_ACTION,
+        locale: Optional[str] = None,
     ):
         self._rules: list[PolicyRule] = rules or []
         self._dlp_scanner: Optional[DLPScanner] = dlp_scanner
@@ -338,6 +349,12 @@ class PolicyEvaluator:
         self._default_action: str = (
             default_action if default_action in VALID_DEFAULT_ACTIONS else DEFAULT_BUNDLE_ACTION
         )
+        # Active locale for user-facing reason localization (
+        # #25, gh#1439). None => read CONTROLZERO_LOCALE at construction.
+        # Empty string ("") means English, the default; reason text is
+        # then byte-identical to the pre-localization SDK so existing
+        # reason-regex consumers are unaffected.
+        self._locale: str = resolve_locale(locale)
 
     def load(self, rules: list[PolicyRule]) -> None:
         """Replace the rule set."""
@@ -365,6 +382,52 @@ class PolicyEvaluator:
         """The effective no-match default action."""
         return self._default_action
 
+    def set_locale(self, locale: Optional[str]) -> None:
+        """Set the active reason-localization locale (#25, gh#1439).
+
+        ``None`` re-reads ``CONTROLZERO_LOCALE``; an empty string forces
+        English. Localization is display-only -- it never changes which
+        rule matches or the effect, only the human-readable ``reason`` text.
+        """
+        self._locale = resolve_locale(locale)
+
+    @property
+    def locale(self) -> str:
+        """The effective reason-localization locale ("" == English)."""
+        return self._locale
+
+    def _resolve_reason(self, rule: PolicyRule) -> str:
+        """Resolve the human-readable reason for a matched rule, localized.
+
+        Priority (#25, gh#1439):
+          1. ``rule.reason_localized[locale]`` -- operator-authored override.
+          2. For SDK-generated synthetic rules (id ``synthetic:*``), the
+             in-binary localized system message keyed by ``reason_code``.
+          3. The plain ``rule.reason`` (English / operator text) -- the
+             DEFAULT whenever locale is unset/English or no override exists,
+             so reason-regex consumers see byte-identical output.
+          4. Canned ``Matched rule <id>`` when the rule carried no reason.
+
+        Localization is display-only; this never affects the decision.
+        """
+        loc = self._locale
+        if loc and loc != "en":
+            override = (getattr(rule, "reason_localized", None) or {}).get(loc)
+            if override:
+                return override
+            # Region-subtag tolerance (ko-KR -> ko) for the per-rule map.
+            rl = getattr(rule, "reason_localized", None) or {}
+            if rl:
+                primary = loc.split("-", 1)[0].split("_", 1)[0]
+                if primary in rl and rl[primary]:
+                    return rl[primary]
+            rule_id = rule.id or ""
+            if rule_id.startswith(SYNTHETIC_POLICY_ID_PREFIX) and getattr(rule, "reason_code", ""):
+                sys_msg = localized_override(rule.reason_code, loc)
+                if sys_msg:
+                    return sys_msg
+        return rule.reason or f"Matched rule {rule.id or rule.name}".strip()
+
     def evaluate(
         self,
         tool: str,
@@ -513,9 +576,11 @@ class PolicyEvaluator:
             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(),
+                # User-provided reason wins, localized when CONTROLZERO_LOCALE
+                # selects a locale the rule (or system pack) has copy for.
+                # Falls back to the plain reason / canned text otherwise, so
+                # English output is byte-identical to before (#25).
+                reason=self._resolve_reason(rule),
                 reason_code=decision_code,
                 evaluated_rules=evaluated,
                 gate_matched=gate_matched_value,
@@ -555,33 +620,28 @@ class PolicyEvaluator:
         # 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":
-            # #1247 (folded from #1257): a deny-by-default no-rule-match is
-            # the single most confusing block a customer hits -- a benign
-            # tool (e.g. `bash:find`) is denied not because a rule forbids
-            # it but because no rule mentions it and the bundle's
-            # default_on_missing is deny. The historical message ("fail-
-            # closed default") gave no path out and looked like a bug.
-            # Name the unmatched action and the exact remediation so the
-            # deny is self-explaining. The leading phrase keeps the legacy
-            # "fail-closed default" substring for any downstream regex
-            # consumer (reason_code=NO_RULE_MATCH is the supported signal;
-            # this is belt-and-suspenders). NOTE: this is the NON-EMPTY
-            # bundle path -- a genuinely empty bundle short-circuits to the
-            # synthetic OBSERVE catch-all above and never reaches here, so
-            # observe and self-explaining-deny compose cleanly.
-            reason = (
-                f"No matching policy rule for '{action}' (fail-closed default; "
-                "default_on_missing=deny). This tool is neither allowed nor "
-                "denied by any rule in your hosted policy, so it is blocked. "
-                "Add a rule that allows it (e.g. allow: '*' as a catch-all, or "
-                f"allow: '{action}'), or set the project/org default to allow, "
-                "in the Control Zero dashboard."
-            )
-        elif self._default_action == "allow":
-            reason = f"No matching policy rule for '{action}' (default_action=allow)"
-        else:  # "warn"
-            reason = f"No matching policy rule for '{action}' (default_action=warn)"
+        # #1247 (folded from #1257): a deny-by-default no-rule-match is the
+        # single most confusing block a customer hits -- a benign tool (e.g.
+        # `bash:find`) is denied not because a rule forbids it but because no
+        # rule mentions it and the bundle's default_on_missing is deny. The
+        # message names the unmatched action + exact remediation so the deny
+        # is self-explaining; it keeps the legacy "fail-closed default"
+        # substring for any downstream regex consumer (reason_code=
+        # NO_RULE_MATCH is the supported signal). NOTE: this is the NON-EMPTY
+        # bundle path -- a genuinely empty bundle short-circuits to the
+        # synthetic OBSERVE catch-all above.
+        #
+        # #25 (gh#1439): the three variant strings now live in the
+        # in-binary message pack keyed by NO_RULE_MATCH:<default_action>. The
+        # English values are byte-identical to the legacy strings, so this is
+        # a no-op when CONTROLZERO_LOCALE is unset; with ko set the Korean
+        # variant is surfaced. default_action is always one of deny/allow/warn
+        # (coerced in the constructor), so the pack key always resolves.
+        reason = system_message(
+            f"NO_RULE_MATCH:{self._default_action}",
+            self._locale,
+            action=action,
+        ) or f"No matching policy rule for '{action}'"
 
         # T79: distinguish the T83-class signature ("a rule's actions
         # matched but its resources gate excluded the call") from the
@@ -675,9 +735,13 @@ class PolicyEvaluator:
             return PolicyDecision(
                 effect="deny",
                 policy_id=decision.policy_id,
-                reason=(
-                    f"DLP rule '{blocking.rule_name}' matched "
-                    f"{blocking.category} content in tool arguments"
+                # #25 (gh#1439): localized via the in-binary pack;
+                # English byte-identical to legacy when locale unset.
+                reason=system_message(
+                    "DLP_BLOCKED:match",
+                    self._locale,
+                    rule_name=blocking.rule_name,
+                    category=blocking.category,
                 ),
                 # DLP_BLOCKED means: the tool-name policy said allow,
                 # but a DLP rule found a hit in the arguments and
@@ -735,11 +799,13 @@ class PolicyEvaluator:
                 return PolicyDecision(
                     effect="deny",
                     policy_id=decision.policy_id,
-                    reason=(
-                        f"DLP rule '{offending.rule_name}' matched "
-                        f"{offending.category} content that spans argument "
-                        "boundaries and could not be safely masked; blocking "
-                        "(fail-closed) rather than forwarding an un-redacted value"
+                    # #25 (gh#1439): localized via the in-binary
+                    # pack; English byte-identical to legacy when unset.
+                    reason=system_message(
+                        "DLP_BLOCKED:boundary",
+                        self._locale,
+                        rule_name=offending.rule_name,
+                        category=offending.category,
                     ),
                     reason_code=REASON_CODE_DLP_BLOCKED,
                     evaluated_rules=decision.evaluated_rules,