controlzero 1.5.8__tar.gz → 1.7.0__tar.gz

{controlzero-1.5.8 → controlzero-1.7.0}/CHANGELOG.md

@@ -1,5 +1,102 @@
 # Changelog
 
+## 1.7.0 -- 2026-05-19 (T86, gh#391)
+
+### Added
+
+- **Unknown-action validator at policy-load time** (T86, GitHub #391).
+  When `controlzero.policy_loader.load_policy()` parses a policy whose
+  rules target an action name that is not in the canonical-or-alias
+  table (typo, made-up name like `database:queryy`), the loader now
+  emits a `logging.WARNING` per offending action with a did-you-mean
+  suggestion list. The policy still loads -- the validator is
+  warn-not-block at the SDK level (the platform backend blocks publish
+  with 422 on the same condition).
+
+  This catches the silent "rule lands but never fires" class of bug
+  that T84's alias shim was created to prevent: a customer typing
+  `database:queryy` gets a one-line warning pointing at
+  `database:query (legacy)` instead of the rule silently never matching.
+
+  The validator's known-action set is the union of canonical SDK
+  extractor tools, host-tool aliases (e.g. `Read` -> `file_read`), the
+  four canonical SQL semantic classes plus every legacy alias from the
+  T84 alias table, and wildcards (`*`, `tool:*`, `*:method`). Adding
+  a new alias to `_internal/action_aliases.py` automatically widens
+  what the validator accepts.
+
+  See `docs/concepts/policies.md#validation` for the full contract.
+
+## v1.6.0 -- 2026-05-17 (HITL-6a, gh#542)
+
+First minor that turns the Human-in-the-Loop approval workflow on. 1.5.8
+prepared the field (escalate_on_deny acknowledged, HITL reason codes
+registered, validator additive); 1.6.0 ships the surface area: 11 exception
+codes, a PendingApproval dataclass with sync + async wait, an in-process
+mock backend, the request_approval HTTP path, the CLI test flag, and the
+secret-value-leak guard that gates every outbound HITL payload.
+
+### Added
+
+- **11 HITL exception classes** (E1701-E1711) -- `HITLTimeoutError`,
+  `HITLBackendUnreachableError`, `HITLPolicyVersionConflictError`,
+  `HITLNotConfiguredError`, `HITLNoApproverAvailable`,
+  `HITLIdentityNotInOrg`, `HITLIdentityRequired`,
+  `HITLIdentityClaimRejected`, `SecretValueLeakInPayload`,
+  `SecretApprovalRequired`, `SecretNotFound`. Inheritance is chosen so
+  existing `except PolicyDeniedError` blocks treat HITL timeouts and
+  approver-pool failures identically to a static deny. (#571)
+- **`controlzero.hitl` subpackage** with the `PendingApproval` dataclass
+  and `Status` enum. `PendingApproval` carries `request_id`,
+  `idempotency_key`, `status`, `created_at`, `expires_at`,
+  `decision_kind`, and `decided_by`; exposes `is_terminal()` and
+  `remaining_s()` for non-blocking checks. (#574)
+- **`MockApprovalBackend`** -- in-process fake of the two HITL endpoints
+  (`POST /api/approval-requests`, `GET /api/approval-requests/{id}`)
+  with five deterministic modes: `approve_after_2s`,
+  `approve_timed_after_2s`, `approve_forever_after_2s`,
+  `deny_after_2s`, and `timeout`. Thread-safe; one instance can serve
+  many concurrent pollers. (#572)
+- **Secret-value-leak guard** -- `is_likely_secret_value`,
+  `scan_payload_for_secret_leak`, and `raise_on_leak` reject any
+  outbound payload whose redacted-args dict still contains a
+  secret-shaped string. The check runs inside `request_approval()`
+  before the HTTP send. (#573)
+- **`controlzero test --hitl approve|deny|timeout`** CLI flag drives the
+  mock backend end-to-end from a shell, so customers can exercise HITL
+  paths without setting up a real approver. (#575)
+- **`PendingApproval.wait()` and `wait_async()`** -- polling loop with
+  jittered exponential backoff, capped at the dataclass's `expires_at`.
+  Honors a user-supplied `poll_fn` for tests; defaults to the SDK's
+  HTTP poller for production. Raises `HITLTimeoutError` on SLA expiry
+  and `HITLBackendUnreachableError` on network failure. (#576)
+- **`Client.request_approval(decision, message=..., timeout_s=...)`** --
+  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
+  the matching SDK exceptions. (#577)
+
+### Conformance
+
+The 49 HITL/secret vectors added to `tests/parity/decisions.json` in
+HITL-3 (gh#536) target this release: `min_sdk_version: "1.6.0"` and
+`requires_backend: true` flags gate them. A Python conformance runner
+that executes those vectors against the SDK is planned for phase 3 of
+issue #409; until that lands, this release is validated against the
+HITL-6a unit tests (155 new test cases across the seven slices) plus
+the pre-existing 156 SDK hook tests.
+
+### Unchanged
+
+- 11-line Hello World still works.
+- No breaking changes to existing public API: `Client.guard()`,
+  `Client.refresh()`, `load_policy()` all behave identically.
+- `escalate_on_deny` still defaults to `False`; policies without HITL
+  tags continue to run with zero HITL overhead.
+- Local-mode users pay no HITL cost: imports are lazy, no HTTP client
+  is constructed unless `request_approval()` is called.
+
 ## v1.5.8 -- 2026-05-16 (HITL-5a, gh#538)
 
 Additive minor preparing the SDK for the Human-in-the-Loop approval

{controlzero-1.5.8 → controlzero-1.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: controlzero
-Version: 1.5.8
+Version: 1.7.0
 Summary: AI agent governance: policies, audit, and observability for tool calls. Works locally with no signup.
 Project-URL: Homepage, https://controlzero.ai
 Project-URL: Documentation, https://docs.controlzero.ai
@@ -28,6 +28,7 @@ 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: rfc8785<0.2,>=0.1.4
 Requires-Dist: rich>=13.0.0
 Requires-Dist: zstandard>=0.22.0
 Provides-Extra: anthropic
@@ -299,6 +300,154 @@ from controlzero import Client
 cz = Client()  # picks up the API key from env, audit ships remote
 ```
 
+## Human-in-the-Loop approvals
+
+Approvals let a policy block a tool call until a human approver decides allow or deny.
+An agent calls `client.request_approval(decision, ...)` whenever `guard()` returns a
+deny that is tagged `escalate_on_deny: true`, then waits on the returned
+`PendingApproval` for the human to respond.
+
+Basic flow:
+
+```python
+from controlzero import Client
+
+cz = Client(api_key="cz_live_...")  # approvals require hosted mode
+
+decision = cz.guard("delete_file", {"path": "/etc/passwd"})
+if decision.decision == "deny" and getattr(decision, "hitl_eligible", False):
+    pending = cz.request_approval(
+        decision,
+        message="agent wants to delete /etc/passwd; please confirm",
+        timeout_s=300,
+    )
+
+    # PendingApproval.wait() requires you to inject a `poll_fn`,
+    # a callable that returns the latest backend snapshot of the
+    # approval request. In 1.6.0 the SDK does NOT ship a built-in
+    # HTTP poller; you wire one yourself (or use the helper that
+    # ships with get_secret. See "Secret reads with approvals" below).
+    import httpx
+    api_url = "https://api.controlzero.ai"  # or your self-managed host
+
+    def poll_fn(request_id: str) -> dict:
+        resp = httpx.get(
+            f"{api_url}/api/approval-requests/{request_id}",
+            headers={"Authorization": f"Bearer {api_key}"},
+            timeout=10,
+        )
+        resp.raise_for_status()
+        return resp.json()
+
+    # Block until the human approves, denies, or the SLA expires.
+    resolved = pending.wait(poll_fn)
+    if resolved.status == "approved":
+        # proceed with the gated action
+        ...
+    else:
+        # denied or timed_out, abort the tool call
+        ...
+```
+
+`wait()` blocks the calling thread. For async code, use `wait_async()`,
+same contract, but the poll callable can be `async def` or a sync
+function (sync calls are dispatched to a thread executor so the event
+loop never blocks):
+
+```python
+async def async_poll(request_id: str) -> dict:
+    async with httpx.AsyncClient() as client:
+        resp = await client.get(
+            f"{api_url}/api/approval-requests/{request_id}",
+            headers={"Authorization": f"Bearer {api_key}"},
+            timeout=10,
+        )
+        resp.raise_for_status()
+        return resp.json()
+
+resolved = await pending.wait_async(async_poll)
+```
+
+A built-in HTTP poller is planned for 1.7.0.
+
+### Mock backend for tests
+
+The SDK ships an in-process `MockApprovalBackend` so tests can exercise approval paths
+without standing up the real backend. Wire it into the polling loop by passing
+`poll_fn`:
+
+```python
+from controlzero import PendingApproval
+from controlzero.hitl.mock import MockApprovalBackend
+
+backend = MockApprovalBackend("approve_after_2s", delay_s=0.05)
+created = backend.create_request({"canonical_action": "delete_file"})
+pending = PendingApproval(
+    request_id=created["request_id"],
+    idempotency_key="test-key",
+    status="pending",
+    created_at=created["created_at"],
+    expires_at=created["expires_at"],
+)
+resolved = pending.wait(poll_fn=lambda rid: backend.get_request(rid))
+assert resolved.status == "approved"
+```
+
+The five supported modes are `approve_after_2s`, `approve_timed_after_2s`,
+`approve_forever_after_2s`, `deny_after_2s`, and `timeout`.
+
+### Identity requirement
+
+Every approval request must carry the operator email so the backend can route to a
+real person and stamp identity provenance on the grant. Set it once via the CLI:
+
+```bash
+controlzero install <agent> --email you@example.com
+```
+
+If the email is missing, `request_approval()` raises `HITLIdentityRequired`
+(E1707) before any HTTP traffic.
+
+### Secret reads with approvals
+
+When a policy gates a secret behind approval, `client.get_secret(name)` raises
+`SecretApprovalRequired` (E1710) carrying a `pending` attribute the caller waits
+on:
+
+```python
+from controlzero.errors import SecretApprovalRequired
+
+try:
+    value = cz.get_secret("PROD_DB_PASSWORD")
+except SecretApprovalRequired as exc:
+    resolved = exc.pending.wait()
+    if resolved.status == "approved":
+        value = cz.get_secret("PROD_DB_PASSWORD")  # retry now that grant exists
+    else:
+        raise  # abort
+```
+
+### Exception classes
+
+The 11 approval-related exception codes raised by this surface. Class names retain
+the `HITL` prefix because they are part of the stable public SDK API:
+
+| Code  | Class                            | Meaning                                                    |
+| ----- | -------------------------------- | ---------------------------------------------------------- |
+| E1701 | `HITLTimeoutError`               | Approver did not decide before `timeout_s` elapsed.        |
+| E1702 | `HITLBackendUnreachableError`    | POST to the approval endpoint failed after retries.        |
+| E1703 | `HITLPolicyVersionConflictError` | SDK bundle is missing the rule that triggered the request. |
+| E1704 | `HITLNotConfiguredError`         | Org has no approval settings row configured.               |
+| E1705 | `HITLNoApproverAvailable`        | Approver pool is empty or no member is active.             |
+| E1706 | `HITLIdentityNotInOrg`           | Operator email is not a member of the API key's org.       |
+| E1707 | `HITLIdentityRequired`           | No operator email set on this install.                     |
+| E1708 | `HITLIdentityClaimRejected`      | Backend rejected the identity claim.                       |
+| E1709 | `SecretValueLeakInPayload`       | Outbound payload contains a secret-shaped string. Aborted. |
+| E1710 | `SecretApprovalRequired`         | Secret read requires approval; wait on `exc.pending`.      |
+| E1711 | `SecretNotFound`                 | Named secret does not exist in the configured vault.       |
+
+Full reference and runbooks: [docs.controlzero.ai/hitl](https://docs.controlzero.ai/hitl).
+
 ## License
 
 Apache 2.0

{controlzero-1.5.8 → controlzero-1.7.0}/README.md

@@ -246,6 +246,154 @@ from controlzero import Client
 cz = Client()  # picks up the API key from env, audit ships remote
 ```
 
+## Human-in-the-Loop approvals
+
+Approvals let a policy block a tool call until a human approver decides allow or deny.
+An agent calls `client.request_approval(decision, ...)` whenever `guard()` returns a
+deny that is tagged `escalate_on_deny: true`, then waits on the returned
+`PendingApproval` for the human to respond.
+
+Basic flow:
+
+```python
+from controlzero import Client
+
+cz = Client(api_key="cz_live_...")  # approvals require hosted mode
+
+decision = cz.guard("delete_file", {"path": "/etc/passwd"})
+if decision.decision == "deny" and getattr(decision, "hitl_eligible", False):
+    pending = cz.request_approval(
+        decision,
+        message="agent wants to delete /etc/passwd; please confirm",
+        timeout_s=300,
+    )
+
+    # PendingApproval.wait() requires you to inject a `poll_fn`,
+    # a callable that returns the latest backend snapshot of the
+    # approval request. In 1.6.0 the SDK does NOT ship a built-in
+    # HTTP poller; you wire one yourself (or use the helper that
+    # ships with get_secret. See "Secret reads with approvals" below).
+    import httpx
+    api_url = "https://api.controlzero.ai"  # or your self-managed host
+
+    def poll_fn(request_id: str) -> dict:
+        resp = httpx.get(
+            f"{api_url}/api/approval-requests/{request_id}",
+            headers={"Authorization": f"Bearer {api_key}"},
+            timeout=10,
+        )
+        resp.raise_for_status()
+        return resp.json()
+
+    # Block until the human approves, denies, or the SLA expires.
+    resolved = pending.wait(poll_fn)
+    if resolved.status == "approved":
+        # proceed with the gated action
+        ...
+    else:
+        # denied or timed_out, abort the tool call
+        ...
+```
+
+`wait()` blocks the calling thread. For async code, use `wait_async()`,
+same contract, but the poll callable can be `async def` or a sync
+function (sync calls are dispatched to a thread executor so the event
+loop never blocks):
+
+```python
+async def async_poll(request_id: str) -> dict:
+    async with httpx.AsyncClient() as client:
+        resp = await client.get(
+            f"{api_url}/api/approval-requests/{request_id}",
+            headers={"Authorization": f"Bearer {api_key}"},
+            timeout=10,
+        )
+        resp.raise_for_status()
+        return resp.json()
+
+resolved = await pending.wait_async(async_poll)
+```
+
+A built-in HTTP poller is planned for 1.7.0.
+
+### Mock backend for tests
+
+The SDK ships an in-process `MockApprovalBackend` so tests can exercise approval paths
+without standing up the real backend. Wire it into the polling loop by passing
+`poll_fn`:
+
+```python
+from controlzero import PendingApproval
+from controlzero.hitl.mock import MockApprovalBackend
+
+backend = MockApprovalBackend("approve_after_2s", delay_s=0.05)
+created = backend.create_request({"canonical_action": "delete_file"})
+pending = PendingApproval(
+    request_id=created["request_id"],
+    idempotency_key="test-key",
+    status="pending",
+    created_at=created["created_at"],
+    expires_at=created["expires_at"],
+)
+resolved = pending.wait(poll_fn=lambda rid: backend.get_request(rid))
+assert resolved.status == "approved"
+```
+
+The five supported modes are `approve_after_2s`, `approve_timed_after_2s`,
+`approve_forever_after_2s`, `deny_after_2s`, and `timeout`.
+
+### Identity requirement
+
+Every approval request must carry the operator email so the backend can route to a
+real person and stamp identity provenance on the grant. Set it once via the CLI:
+
+```bash
+controlzero install <agent> --email you@example.com
+```
+
+If the email is missing, `request_approval()` raises `HITLIdentityRequired`
+(E1707) before any HTTP traffic.
+
+### Secret reads with approvals
+
+When a policy gates a secret behind approval, `client.get_secret(name)` raises
+`SecretApprovalRequired` (E1710) carrying a `pending` attribute the caller waits
+on:
+
+```python
+from controlzero.errors import SecretApprovalRequired
+
+try:
+    value = cz.get_secret("PROD_DB_PASSWORD")
+except SecretApprovalRequired as exc:
+    resolved = exc.pending.wait()
+    if resolved.status == "approved":
+        value = cz.get_secret("PROD_DB_PASSWORD")  # retry now that grant exists
+    else:
+        raise  # abort
+```
+
+### Exception classes
+
+The 11 approval-related exception codes raised by this surface. Class names retain
+the `HITL` prefix because they are part of the stable public SDK API:
+
+| Code  | Class                            | Meaning                                                    |
+| ----- | -------------------------------- | ---------------------------------------------------------- |
+| E1701 | `HITLTimeoutError`               | Approver did not decide before `timeout_s` elapsed.        |
+| E1702 | `HITLBackendUnreachableError`    | POST to the approval endpoint failed after retries.        |
+| E1703 | `HITLPolicyVersionConflictError` | SDK bundle is missing the rule that triggered the request. |
+| E1704 | `HITLNotConfiguredError`         | Org has no approval settings row configured.               |
+| E1705 | `HITLNoApproverAvailable`        | Approver pool is empty or no member is active.             |
+| E1706 | `HITLIdentityNotInOrg`           | Operator email is not a member of the API key's org.       |
+| E1707 | `HITLIdentityRequired`           | No operator email set on this install.                     |
+| E1708 | `HITLIdentityClaimRejected`      | Backend rejected the identity claim.                       |
+| E1709 | `SecretValueLeakInPayload`       | Outbound payload contains a secret-shaped string. Aborted. |
+| E1710 | `SecretApprovalRequired`         | Secret read requires approval; wait on `exc.pending`.      |
+| E1711 | `SecretNotFound`                 | Named secret does not exist in the configured vault.       |
+
+Full reference and runbooks: [docs.controlzero.ai/hitl](https://docs.controlzero.ai/hitl).
+
 ## License
 
 Apache 2.0

{controlzero-1.5.8 → controlzero-1.7.0}/controlzero/__init__.py

@@ -26,12 +26,14 @@ from controlzero.errors import (
     PolicyLoadError,
     PolicyValidationError,
 )
+from controlzero.hitl import PendingApproval
 from controlzero.policy_loader import load_policy
 
-__version__ = "1.5.8"
+__version__ = "1.7.0"
 
 __all__ = [
     "Client",
+    "PendingApproval",
     "PolicyDecision",
     "PolicyDeniedError",
     "PolicyLoadError",

controlzero-1.7.0/controlzero/_internal/action_validator.py

@@ -0,0 +1,182 @@
+"""T86 / GitHub #391 -- unknown-action validator (warn-only at SDK load).
+
+Pairs with the backend validator at
+``apps/control-zero-platform/backend/internal/policy/action_aliases.go``.
+The backend BLOCKS publish on unknown actions (422); the SDK
+WARNS at load time so a customer running local-policy mode (no
+backend) still sees the typo before the rule silently never fires.
+
+The known-action set is the union of:
+
+- Canonical tools (``database``, ``Bash``, ``http``, ``web_search``,
+  ``browser``, ``file_read``, ``file_write``, ``file_search``,
+  ``task``) plus their host-tool aliases from the SDK extractor
+  spec (``sdks/python/controlzero/controlzero/_internal/tool_extractors.json``).
+- For the ``database`` tool: the four canonical SQL semantic classes
+  (``read``/``write``/``admin``/``exec``), every legacy alias from
+  the T84 alias table, and the ambiguous ``delete`` alias.
+
+For every other tool the validator accepts ANY method (open
+extractor outputs -- Bash basenames, HTTP verbs, browser action
+strings, etc.). Wildcards (``*``, ``tool:*``, ``*:method``) always
+pass.
+"""
+from __future__ import annotations
+
+from typing import Iterable
+
+from controlzero._internal.action_aliases import TOOL as _ALIAS_TOOL
+from controlzero._internal.action_aliases import _AMBIGUOUS, _CLASSES
+
+# Mirror of the canonical tool set + host-aliases the extractors
+# accept. Source of truth is tool_extractors.json; this list is
+# updated alongside it.
+_CANONICAL_TOOLS: set[str] = {
+    "Bash", "database", "http", "web_search", "browser",
+    "file_read", "file_write", "file_search", "task",
+    # database aliases
+    "sql", "Database", "PostgreSQL", "MySQL", "postgres", "sqlite",
+    # Bash aliases
+    "bash", "shell", "ShellTool", "run_shell_command",
+    "PowerShell", "powershell", "Shell",
+    # http aliases
+    "fetch", "web_fetch", "WebFetch", "HTTPRequest", "request",
+    # web_search aliases
+    "WebSearch", "google_web_search", "SearchTool",
+    # browser aliases
+    "playwright", "Puppeteer",
+    # file_read aliases
+    "read_file", "Read", "ReadFile", "read_many_files",
+    # file_write aliases
+    "write_file", "Write", "WriteFile", "edit_file", "Edit",
+    "replace", "apply_patch",
+    # file_search aliases
+    "Grep", "grep_search", "Glob", "glob",
+    # task aliases
+    "Task", "Agent", "subagent", "spawn_agent",
+}
+
+_DATABASE_TOOL_ALIASES = {
+    "database", "sql", "Database", "PostgreSQL", "MySQL", "postgres", "sqlite",
+}
+
+
+def _build_known_database_methods() -> set[str]:
+    out: set[str] = {"*"}
+    for cls, aliases in _CLASSES.items():
+        out.add(cls)
+        for a in aliases:
+            out.add(a)
+    for alias in _AMBIGUOUS:
+        out.add(alias)
+    return out
+
+
+_KNOWN_DATABASE_METHODS = _build_known_database_methods()
+
+
+def is_known_action(action: str) -> bool:
+    """Return True if ``action`` is recognised by the SDK extractors / aliases."""
+    if not action:
+        return False
+    if action == "*":
+        return True
+    if ":" not in action:
+        return action in _CANONICAL_TOOLS
+    tool, _, method = action.partition(":")
+    if tool == "*":
+        return True
+    if tool not in _CANONICAL_TOOLS:
+        return False
+    if method == "*" or method == "":
+        return True
+    if tool in _DATABASE_TOOL_ALIASES:
+        return method in _KNOWN_DATABASE_METHODS
+    # Other tools: any method accepted (open extractor outputs).
+    return True
+
+
+def _levenshtein(a: str, b: str) -> int:
+    if a == b:
+        return 0
+    if not a:
+        return len(b)
+    if not b:
+        return len(a)
+    prev = list(range(len(b) + 1))
+    curr = [0] * (len(b) + 1)
+    for i in range(1, len(a) + 1):
+        curr[0] = i
+        for j in range(1, len(b) + 1):
+            cost = 0 if a[i - 1] == b[j - 1] else 1
+            curr[j] = min(prev[j] + 1, curr[j - 1] + 1, prev[j - 1] + cost)
+        prev, curr = curr, prev
+    return prev[len(b)]
+
+
+def _shares_tool_prefix(a: str, b: str) -> bool:
+    if ":" not in a or ":" not in b:
+        return False
+    ta, _, ma = a.partition(":")
+    tb, _, mb = b.partition(":")
+    if ta != tb or not ma or not mb:
+        return False
+    short = min(len(ma), len(mb))
+    overlap = 0
+    for i in range(short):
+        if ma[i].lower() != mb[i].lower():
+            break
+        overlap += 1
+    return overlap * 2 >= short
+
+
+def _candidates() -> list[tuple[str, bool]]:
+    """Enumerate (name, is_legacy) tuples for suggestion ranking."""
+    out: list[tuple[str, bool]] = []
+    for cls in _CLASSES:
+        out.append((f"{_ALIAS_TOOL}:{cls}", False))
+    for aliases in _CLASSES.values():
+        for a in aliases:
+            out.append((f"{_ALIAS_TOOL}:{a}", True))
+    for alias in _AMBIGUOUS:
+        out.append((f"{_ALIAS_TOOL}:{alias}", True))
+    for tool in _CANONICAL_TOOLS:
+        out.append((f"{tool}:*", False))
+    return out
+
+
+def suggest_for_action(action: str, max_suggestions: int = 3) -> list[str]:
+    """Return up to ``max_suggestions`` did-you-mean candidates for ``action``."""
+    max_distance = 3
+    cands = _candidates()
+    hits: list[tuple[str, int, bool]] = []
+    for name, legacy in cands:
+        d = _levenshtein(action, name)
+        if d > max_distance and not _shares_tool_prefix(action, name):
+            continue
+        hits.append((name, d, legacy))
+    # Sort by distance, then prefer canonical over legacy, then name.
+    hits.sort(key=lambda h: (h[1], h[2], h[0]))
+    out: list[str] = []
+    for name, _d, legacy in hits[:max_suggestions]:
+        out.append(f"{name} (legacy)" if legacy else name)
+    return out
+
+
+def validate_actions(actions: Iterable[str]) -> tuple[list[str], dict[str, list[str]]]:
+    """Return (unknown_actions, suggestions_map) for the given action list."""
+    unknown: list[str] = []
+    suggestions: dict[str, list[str]] = {}
+    seen: set[str] = set()
+    for a in actions:
+        if is_known_action(a):
+            continue
+        if a in seen:
+            continue
+        seen.add(a)
+        unknown.append(a)
+        suggestions[a] = suggest_for_action(a)
+    return unknown, suggestions
+
+
+__all__ = ["is_known_action", "suggest_for_action", "validate_actions"]