shield-kya 0.17.0__py3-none-any.whl

shield_kya/__init__.py

@@ -0,0 +1,383 @@
+"""In-process kya governance shim for Python agent frameworks.
+
+Delegates evaluation to the local kya CLI (`kya wrap --offline --json ...`),
+so Python tools share the same offline verdict path as the TypeScript SDK.
+Shipped adapters live in :mod:`shield_kya.integrations` (LangChain/LangGraph
+middleware, Pydantic AI capability, CrewAI global hook, Google ADK plugin,
+Agent Framework middleware, OpenAI Agents SDK guardrail, per-tool wrappers).
+Stdlib only.
+
+OSS semantics match `kya hook`: the shim is advisory and FAILS OPEN. A missing
+CLI, a timeout, non-JSON output, an unknown exit code, an empty verdict or any
+other shim error allows the call (first event logged at WARNING, every event at
+DEBUG). Only the local never-list blocks: a DENY verdict from the CLI, or, when
+there is no verdict, the same name-only never-list matched in Python. Pass
+``fail_closed=True`` (or set ``KYA_FAIL_CLOSED`` to 1/true/yes/on, hosted) to
+deny on those errors instead. ``strict=True`` also blocks REQUIRE_APPROVE.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import functools
+import inspect
+import json
+import logging
+import os
+import signal
+import subprocess
+from dataclasses import dataclass
+
+from shield_kya._never_list import js_trim, matches_never_list
+
+__version__ = "0.17.0"
+__all__ = ["DEFAULT_TIMEOUT_S", "Decision", "KyaDenied", "adecide", "decide",
+           "evaluate", "governed"]
+
+# Same budget as `kya hook` (4 s, under a host's 5 s hook limit).
+DEFAULT_TIMEOUT_S = 4.0
+
+log = logging.getLogger("shield_kya")
+_warned = False
+
+
+class KyaDenied(Exception):
+    """Raised when kya denies a tool call; the wrapped function never ran."""
+
+    def __init__(self, tool_id: str, verdict: str, reason_code: str) -> None:
+        super().__init__(f"kya {verdict}: {tool_id} ({reason_code or 'no reason'})")
+        self.tool_id = tool_id
+        self.verdict = verdict
+        self.reason_code = reason_code
+
+
+class KyaUnavailable(RuntimeError):
+    """The kya CLI gave no usable verdict (missing, timeout, bad output)."""
+
+
+@dataclass(frozen=True)
+class Decision:
+    """Outcome of one governed tool call."""
+
+    allowed: bool
+    verdict: str  # ALLOW / DENY / REQUIRE_APPROVE / FAIL_OPEN / FAIL_CLOSED
+    reason_code: str
+    tool_id: str
+
+    @property
+    def reason(self) -> str:
+        """Readable reason, suitable to hand back to the model on a deny."""
+        if self.verdict == "FAIL_CLOSED":
+            return f"KYA fail-closed: {self.tool_id} denied ({self.reason_code})"
+        if self.verdict == "REQUIRE_APPROVE":
+            return f"KYA strict mode: {self.tool_id} requires approval ({self.reason_code})"
+        return f"KYA denied {self.tool_id}: {self.reason_code or self.verdict}"
+
+    def raise_if_denied(self) -> None:
+        if not self.allowed:
+            raise KyaDenied(self.tool_id, self.verdict, self.reason_code)
+
+
+def _env_flag(name: str) -> bool:
+    return os.environ.get(name, "").strip().lower() in ("1", "true", "yes", "on")
+
+
+def _abs_path_entries() -> list:
+    """PATH entries that are absolute; empty, ".", "~" and other relative ones dropped."""
+    return [d for d in os.environ.get("PATH", "").split(os.pathsep) if d and os.path.isabs(d)]
+
+
+def _find_on_path(name: str) -> str | None:
+    """Look `name` up in ABSOLUTE PATH entries only.
+
+    Never the cwd: shutil.which() on Windows searches the current directory
+    first, so a cloned repo could plant kya.exe. Empty, "." and other relative
+    entries are skipped on every OS.
+    """
+    exts = [""]
+    if os.name == "nt":
+        exts = [e for e in os.environ.get("PATHEXT", ".COM;.EXE;.BAT;.CMD").split(";") if e]
+    for d in _abs_path_entries():
+        for ext in exts:
+            candidate = os.path.join(d, name + ext)
+            if os.path.isfile(candidate) and os.access(candidate, os.X_OK):
+                return candidate
+    return None
+
+
+def _cli() -> list:
+    override = os.environ.get("KYA_CLI")
+    if override:
+        # Must be absolute: a relative value would resolve against the agent's cwd.
+        if not os.path.isabs(override) or not os.path.isfile(override):
+            raise KyaUnavailable("KYA_CLI ignored: not an absolute path to a file")
+        if override.lower().endswith(".js"):
+            node = _find_on_path("node")
+            if node is None:
+                raise KyaUnavailable("KYA_CLI points at a .js file but node is not on PATH")
+            return [node, override]
+        exe = override
+    else:
+        found = _find_on_path("kya")
+        if found is None:
+            raise KyaUnavailable(
+                "kya CLI not found on PATH - install @shield-agent/kya "
+                "(npm i -g @shield-agent/kya) or set KYA_CLI"
+            )
+        exe = found
+    if os.name == "nt" and exe.lower().endswith((".cmd", ".bat")):
+        # cmd.exe re-parses argv, and the args JSON is model-controlled.
+        raise KyaUnavailable(
+            "refusing to run kya through a .cmd/.bat shim on Windows; set KYA_CLI "
+            "to the package's dist/cli.js (run with node)"
+        )
+    return [exe]
+
+
+# The CLI child gets an ALLOWLIST of the environment, never the rest: a framework may
+# have loaded a repo .env into os.environ (crewai runs load_dotenv() at import), and
+# variables like NODE_OPTIONS, OPENSSL_CONF or LD_PRELOAD run repo code in node, while
+# KYA_* ones redirect the trail or add a webhook. TMPDIR is left out on purpose.
+_CHILD_ENV = ("HOME", "USERPROFILE", "LANG", "TZ")
+_CHILD_ENV_NT = ("SYSTEMROOT", "WINDIR", "COMSPEC", "PATHEXT", "APPDATA", "LOCALAPPDATA",
+                 "TEMP", "TMP")
+# Privacy opt-outs: forwarded only when they switch something OFF, so a planted value
+# can only make the trail more private.
+_PRIVACY_OPT_OUTS = ("KYA_DIFF_PREVIEW", "KYA_SEND_PREVIEWS")
+_OFF = ("0", "false", "no", "off")
+
+
+def _env() -> dict:
+    # The npm/brew launcher is `#!/usr/bin/env node`: the child must not find a
+    # repo-planted ./node through a relative PATH entry either.
+    dirs = _abs_path_entries() or [d for d in os.defpath.split(os.pathsep) if os.path.isabs(d)]
+    keep = _CHILD_ENV + (_CHILD_ENV_NT if os.name == "nt" else ())
+    env = {k: v for k, v in os.environ.items()
+           if k in keep or k.startswith("LC_")
+           or (k in _PRIVACY_OPT_OUTS and v.strip().lower() in _OFF)}
+    return {**env, "PATH": os.pathsep.join(dirs), "KYA_SKIP_NODE_CHECK": "1"}
+
+
+def _kill(proc) -> None:
+    """Kill the CLI and anything it spawned (own session on POSIX)."""
+    try:
+        if os.name == "posix":
+            os.killpg(proc.pid, signal.SIGKILL)
+        else:
+            proc.kill()
+    except (ProcessLookupError, PermissionError):
+        pass
+
+
+def _parse(returncode: int, stdout: str, stderr: str) -> dict:
+    try:
+        data = json.loads(stdout)
+    except json.JSONDecodeError as exc:
+        raise KyaUnavailable(
+            f"kya returned non-JSON output (exit {returncode}): "
+            f"{stderr.strip()[:200] or stdout[:200]}"
+        ) from exc
+    # 0=allow, 1=deny, 4=hold - anything else is a transport/infra failure,
+    # not a policy verdict.
+    if returncode not in (0, 1, 4) or not isinstance(data, dict):
+        raise KyaUnavailable(
+            f"kya exited {returncode} (transport failure, not a verdict): "
+            f"{stderr.strip()[:200]}"
+        )
+    return data
+
+
+def _run_kya(argv: list, timeout: float = DEFAULT_TIMEOUT_S) -> dict:
+    try:
+        proc = subprocess.Popen(
+            [*_cli(), *argv], stdin=subprocess.DEVNULL, stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE, env=_env(), start_new_session=True,
+            encoding="utf-8", errors="replace")
+    except OSError as exc:
+        raise KyaUnavailable(f"kya could not start: {exc}") from exc
+    try:
+        out, err = proc.communicate(timeout=timeout)
+    except subprocess.TimeoutExpired as exc:
+        _kill(proc)
+        proc.communicate()
+        raise KyaUnavailable(f"kya timed out after {timeout:g}s") from exc
+    except BaseException:
+        _kill(proc)
+        proc.wait()
+        raise
+    return _parse(proc.returncode, out, err)
+
+
+async def _arun_kya(argv: list, timeout: float = DEFAULT_TIMEOUT_S) -> dict:
+    try:
+        proc = await asyncio.create_subprocess_exec(
+            *_cli(), *argv, stdin=asyncio.subprocess.DEVNULL,
+            stdout=asyncio.subprocess.PIPE, stderr=asyncio.subprocess.PIPE,
+            env=_env(), start_new_session=True)
+    except OSError as exc:
+        raise KyaUnavailable(f"kya could not start: {exc}") from exc
+    try:
+        out, err = await asyncio.wait_for(proc.communicate(), timeout)
+    except asyncio.TimeoutError as exc:
+        raise KyaUnavailable(f"kya timed out after {timeout:g}s") from exc
+    finally:
+        # Timeout or cancellation: never leave the CLI running behind us.
+        if proc.returncode is None:
+            _kill(proc)
+            await asyncio.shield(proc.wait())
+    return _parse(proc.returncode or 0, out.decode("utf-8", errors="replace"),
+                  err.decode("utf-8", errors="replace"))
+
+
+def _json_safe(value):
+    try:
+        json.dumps(value, allow_nan=False)  # NaN/Infinity is not JSON; the CLI rejects it
+        return value
+    except RecursionError:
+        return f"<unserializable {type(value).__name__}>"
+    except Exception:
+        pass
+    try:
+        return repr(value)
+    except Exception:
+        return f"<unserializable {type(value).__name__}>"
+
+
+def _bound_args(fn, args, kwargs) -> dict:
+    """Bound call arguments for `kya wrap --args`; never raises."""
+    try:
+        bound = inspect.signature(fn).bind(*args, **kwargs)
+        return {k: _json_safe(v) for k, v in bound.arguments.items()}
+    except Exception:
+        return {}
+
+
+def _full_tool_id(tool_id: str, server: str | None) -> str:
+    tid = js_trim(str(tool_id))
+    return f"{js_trim(str(server))}__{tid}" if server else tid
+
+
+def _wrap_argv(full_id: str, args: dict | None, irreversible: bool) -> list:
+    projected = {str(k): _json_safe(v) for k, v in (args or {}).items()}
+    # --flag=value: a tool id starting with "-" must not read as a flag.
+    argv = ["wrap", "--offline", "--json", f"--tool-id={full_id}",
+            f"--args={json.dumps(projected, allow_nan=False)}"]
+    if irreversible:
+        argv.append("--irreversible")
+    return argv
+
+
+def _fail_closed(flag: bool | None) -> bool:
+    return flag if flag is not None else _env_flag("KYA_FAIL_CLOSED")
+
+
+def _unavailable(full_id: str, message: str, fail_closed: bool | None) -> Decision:
+    """No verdict from the CLI. The never-list still blocks in every mode."""
+    global _warned
+    log.debug("KYA no verdict for %s: %s", full_id, message)
+    if matches_never_list(full_id):
+        log.warning("KYA no verdict for %s, never-list match, denying: %s", full_id, message)
+        return Decision(False, "DENY", "NEVER_EVENT", full_id)
+    if _fail_closed(fail_closed):
+        log.warning("KYA fail-closed, denying %s: %s", full_id, message)
+        return Decision(False, "FAIL_CLOSED", "KYA_UNAVAILABLE", full_id)
+    if not _warned:
+        _warned = True
+        log.warning("KYA advisory mode, allowing tool calls without a verdict: %s", message)
+    return Decision(True, "FAIL_OPEN", "KYA_UNAVAILABLE", full_id)
+
+
+def _decision(full_id: str, result: dict, strict: bool,
+              fail_closed: bool | None) -> Decision:
+    # Defense in depth: a hostile or stale CLI (KYA_CLI can come from a .env that a
+    # framework loads, e.g. crewai's import-time load_dotenv) cannot ALLOW a never-list tool.
+    if matches_never_list(full_id):
+        return Decision(False, "DENY", "NEVER_EVENT", full_id)
+    response = (result.get("eval") or {}).get("response") or {}
+    verdict = str(response.get("verdict", "")).upper()
+    reason = str(response.get("reasonCode", ""))
+    if verdict == "DENY":
+        return Decision(False, verdict, reason, full_id)
+    if verdict == "REQUIRE_APPROVE":
+        return Decision(not strict, verdict, reason, full_id)
+    if verdict == "ALLOW":
+        return Decision(True, verdict, reason, full_id)
+    return _unavailable(full_id, f"kya returned no usable verdict ({verdict or 'empty'})",
+                        fail_closed)
+
+
+# Same as the CLI's offline evaluate (baseTier): an empty tool id is DENY EMPTY_TOOL.
+_EMPTY = Decision(False, "DENY", "EMPTY_TOOL", "")
+
+
+def decide(tool_id: str, args: dict | None = None, *, server: str | None = None,
+           irreversible: bool = False, strict: bool = False,
+           fail_closed: bool | None = None,
+           timeout: float = DEFAULT_TIMEOUT_S) -> Decision:
+    """Evaluate one tool call via `kya wrap` (records the trail); never raises."""
+    full_id = _full_tool_id(tool_id, server)
+    if not full_id:
+        return _EMPTY
+    try:
+        result = _run_kya(_wrap_argv(full_id, args, irreversible), timeout)
+        return _decision(full_id, result, strict, fail_closed)
+    except Exception as exc:  # any shim/CLI error: fail open (or closed), never crash the agent
+        return _unavailable(full_id, str(exc) or type(exc).__name__, fail_closed)
+
+
+async def adecide(tool_id: str, args: dict | None = None, *, server: str | None = None,
+                  irreversible: bool = False, strict: bool = False,
+                  fail_closed: bool | None = None,
+                  timeout: float = DEFAULT_TIMEOUT_S) -> Decision:
+    """Async :func:`decide`: runs the CLI as an asyncio subprocess, never blocks the loop."""
+    full_id = _full_tool_id(tool_id, server)
+    if not full_id:
+        return _EMPTY
+    try:
+        result = await _arun_kya(_wrap_argv(full_id, args, irreversible), timeout)
+        return _decision(full_id, result, strict, fail_closed)
+    except Exception as exc:  # any shim/CLI error: fail open (or closed), never crash the agent
+        return _unavailable(full_id, str(exc) or type(exc).__name__, fail_closed)
+
+
+def evaluate(tool_id: str, args: dict | None = None,
+             timeout: float = DEFAULT_TIMEOUT_S) -> dict:
+    """Evaluate a tool call offline; returns the parsed eval-tool JSON dict.
+
+    A manual check, not a gate: CLI problems raise RuntimeError.
+    """
+    argv = ["eval-tool", "--offline", "--json", f"--tool-id={tool_id}",
+            f"--args={json.dumps(args or {})}"]
+    return _run_kya(argv, timeout)
+
+
+def governed(tool_id: str, server: str | None = None, irreversible: bool = False, *,
+             strict: bool = False, fail_closed: bool | None = None,
+             timeout: float = DEFAULT_TIMEOUT_S):
+    """Decorator: govern the wrapped callable (sync or async) at the tool boundary.
+
+    DENY raises KyaDenied without calling it (a plain function has no other
+    way to report a deny). ALLOW and REQUIRE_APPROVE run it; ``strict=True``
+    blocks REQUIRE_APPROVE too. CLI errors fail open unless ``fail_closed``.
+    Async functions are checked with :func:`adecide`, off the event loop.
+    """
+    opts = dict(server=server, irreversible=irreversible, strict=strict,
+                fail_closed=fail_closed, timeout=timeout)
+
+    def decorator(fn):
+        if inspect.iscoroutinefunction(fn):
+            @functools.wraps(fn)
+            async def awrapper(*args, **kwargs):
+                (await adecide(tool_id, _bound_args(fn, args, kwargs), **opts)).raise_if_denied()
+                return await fn(*args, **kwargs)
+
+            return awrapper
+
+        @functools.wraps(fn)
+        def wrapper(*args, **kwargs):
+            decide(tool_id, _bound_args(fn, args, kwargs), **opts).raise_if_denied()
+            return fn(*args, **kwargs)
+
+        return wrapper
+
+    return decorator

shield_kya/_never_list.py

@@ -0,0 +1,94 @@
+"""Port of `matchesNeverList` (sdks/kya/src/offline-evaluate.ts).
+
+Used only when the kya CLI gives no verdict, so the never-list keeps blocking
+in fail-open mode (same as the `kya hook` error path). Depends on the tool
+name alone. tests/test_never_list.py asserts this module against the shared
+vectors in sdks/kya/test/fixtures/never-list-vectors.json, which the TS suite
+asserts too, so the two lists cannot drift silently.
+"""
+
+from __future__ import annotations
+
+import re
+
+# SAMPLE_TOOLS with policyTier DENY (sample-tools.ts).
+DENY_SAMPLE_IDS = frozenset({"org.sample.never.event"})
+
+# Normalized MCP server ids and aliases (mcp-servers.ts mcpServerKeys()).
+MCP_SERVER_KEYS = frozenset({
+    "atlassian", "brave", "brave_search", "browser_use", "browseruse",
+    "chrome_devtools", "chromedevtools", "confluence", "context7", "devtools",
+    "exa", "fetch", "figma", "filesystem", "firecrawl", "fs", "github", "jira",
+    "linear", "ms_playwright", "n8n", "notion", "playwright", "postgres",
+    "postgresql", "sentry", "sequential_thinking", "sequentialthinking",
+    "serena", "slack", "supabase", "zapier",
+})
+
+# NEVER_LIST_VERBS (offline-evaluate.ts).
+NEVER_LIST_VERBS = ("drop", "truncate", "purge", "transfer")
+
+# Exactly what JS String.prototype.trim() removes: WhiteSpace (tab, VT, FF,
+# space, NBSP, BOM, Zs) and LineTerminator (LF, CR, U+2028, U+2029). Python's
+# str.strip() differs (it strips \x1c-\x1f and \x85, keeps the BOM).
+JS_TRIM = ("\t\n\x0b\x0c\r \xa0\u1680\u2000\u2001\u2002\u2003\u2004\u2005\u2006"
+           "\u2007\u2008\u2009\u200a\u2028\u2029\u202f\u205f\u3000\ufeff")
+
+_DESTRUCTIVE = re.compile("|".join(NEVER_LIST_VERBS))
+
+
+def _is_mcp_start_char(c: str) -> bool:
+    return "a" <= c <= "z" or "0" <= c <= "9"
+
+
+def _is_mcp_id_char(c: str) -> bool:
+    return _is_mcp_start_char(c) or c == "_" or c == "-"
+
+
+def _split_mcp_body(body: str) -> tuple[str, str] | None:
+    # Linear scan replacing the old lazy-regex split (CodeQL
+    # js/polynomial-redos on the TS twin). Reproduces the original pattern
+    # ^(?:mcp__)?([a-z0-9][a-z0-9_-]*?)(?:__|\.|\/)([a-z0-9][a-z0-9_-]*)$
+    # exactly, capture groups included: the first separator whose left side is
+    # a valid server and whose right side is a valid tool wins. `.`/`/` end the
+    # server candidate range, so the scan stops there. Mirror of splitMcpBody
+    # in sdks/kya/src/mcp-servers.ts; keep the two in lockstep.
+    n = len(body)
+    if n == 0 or not _is_mcp_start_char(body[0]):
+        return None
+    # suffix_ok[j]: every char from j to the end is an id char (one backward pass).
+    suffix_ok = [True] * (n + 1)
+    for j in range(n - 1, -1, -1):
+        suffix_ok[j] = suffix_ok[j + 1] and _is_mcp_id_char(body[j])
+    for i, c in enumerate(body):
+        sep_len = 2 if c == "_" and i + 1 < n and body[i + 1] == "_" else (1 if c in "./" else 0)
+        if sep_len:
+            t = i + sep_len
+            if t < n and _is_mcp_start_char(body[t]) and suffix_ok[t]:
+                return body[:i], body[t:]
+        if not _is_mcp_id_char(c):
+            break
+    return None
+
+
+def _parse_mcp_id(raw: str) -> tuple[str, str] | None:
+    # The optional `mcp__` group was greedy: try the body after the prefix
+    # first, then the whole string.
+    if raw.startswith("mcp__"):
+        return _split_mcp_body(raw[5:]) or _split_mcp_body(raw)
+    return _split_mcp_body(raw)
+
+
+def js_trim(value: str) -> str:
+    return value.strip(JS_TRIM)
+
+
+def matches_never_list(tool_id: str) -> bool:
+    raw = js_trim(tool_id).lower()
+    # Every sample tool has a policyTier; only the DENY ones match. No sample
+    # id parses as an MCP id, so checking the DENY set alone is equivalent.
+    if raw in DENY_SAMPLE_IDS:
+        return True
+    parsed = _parse_mcp_id(raw)
+    if not parsed or parsed[0].replace("-", "_") not in MCP_SERVER_KEYS:
+        return False
+    return bool(_DESTRUCTIVE.search(parsed[1]))

shield_kya/integrations/__init__.py

@@ -0,0 +1,109 @@
+"""Optional per-framework shims.
+
+- :mod:`shield_kya.integrations.langchain`: ``KyaMiddleware`` for
+  LangChain ``create_agent`` and LangGraph ``ToolNode`` (agent-wide; a DENY
+  goes back to the model as an error ``ToolMessage``).
+- :mod:`shield_kya.integrations.pydantic_ai`: ``KyaCapability`` (agent-wide;
+  a DENY becomes the tool result via ``SkipToolExecution``).
+- :mod:`shield_kya.integrations.crewai`: ``register()`` (global
+  ``PRE_TOOL_CALL`` hook; a DENY blocks via ``HookAborted``).
+- :mod:`shield_kya.integrations.adk`: ``KyaPlugin`` for Google ADK
+  (Runner-wide; a DENY becomes the tool result ``{"error": reason}``).
+- :mod:`shield_kya.integrations.agent_framework`: ``KyaMiddleware`` for
+  Microsoft Agent Framework (a ``FunctionMiddleware``; a DENY becomes the
+  function result).
+- :mod:`shield_kya.integrations.openai_agents`: ``attach(agent)`` puts a
+  KYA tool input guardrail on every function tool and MCP server of an
+  OpenAI Agents SDK agent (a DENY becomes the tool output via
+  ``reject_content``).
+- :mod:`shield_kya.integrations.langgraph` and the ``governed_tool`` /
+  ``wrap_tool(s)`` helpers: per-tool wrappers (a DENY raises ``KyaDenied``).
+
+Every adapter delegates verdicts to the kya CLI exactly like
+:func:`shield_kya.decide` (fail-open by default) and never imports its
+framework at package import time.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+
+import shield_kya
+from shield_kya import KyaDenied
+from shield_kya._never_list import matches_never_list
+
+__all__ = ["KyaDenied", "gate", "langgraph", "crewai", "pydantic_ai", "adk",
+           "agent_framework", "openai_agents"]
+
+
+def _mcp_names(exposed: str, original=None, local=None) -> list:
+    """The exposed tool name, then never-list candidates the framework still knows.
+
+    A framework that renames an MCP tool to ``<prefix>_<local>`` keeps the
+    original MCP name: check it, and ``<prefix>__<original>`` (frameworks prefix
+    with one underscore, the never-list needs two). Agent Framework strips
+    leading ``_.-`` from the local name in the exposed one, so the prefix is
+    found with the stripped form and joined to the raw, local and stripped names.
+    """
+    names = [exposed]
+    original = str(original or "")
+    local = str(local or original)
+    if original and original != exposed:
+        names.append(original)
+        stem = local.lstrip("_.-")
+        if stem and exposed.endswith("_" + stem) and len(exposed) > len(stem) + 1:
+            prefix = exposed[:-len(stem) - 1]
+            names += [f"{prefix}__{n}" for n in (original, local, stem)]
+    return list(dict.fromkeys(names))
+
+
+async def _adecide_names(get_names, args, opts: dict):
+    """:func:`shield_kya.adecide` for one call; returns ``(decision, reason)``, never raises.
+
+    ``get_names()`` gives the exposed name first, then other names the framework
+    keeps for the tool. If any is on the never-list that one is evaluated (and
+    denied). Every name is matched with the user's ``server=`` prefix and
+    without it: the framework already knows these names, and a prefix the
+    never-list does not know (``server="acme"``) must not hide
+    ``postgres__drop_table``. An unprefixed match is evaluated without ``server``.
+    Any error here, including in ``get_names``, goes through the fail-open /
+    never-list / fail-closed rules, never to the framework.
+    """
+    server = opts.get("server")
+    target = name = ""
+    srv = server
+    try:
+        names = [str(n) for n in get_names()]
+        target = name = names[0]
+        never = [(n, server) for n in names
+                 if matches_never_list(shield_kya._full_tool_id(n, server))]
+        if server:
+            never += [(n, None) for n in names
+                      if matches_never_list(shield_kya._full_tool_id(n, None))]
+        target, srv = never[0] if never else (name, server)
+        args = dict(args) if isinstance(args, Mapping) else {"input": args}
+        decision = await shield_kya.adecide(target, args, **{**opts, "server": srv})
+    except Exception as exc:
+        decision = shield_kya._unavailable(shield_kya._full_tool_id(target, srv), repr(exc),
+                                           opts.get("fail_closed"))
+    reason = decision.reason
+    if target != name:  # the model called the renamed tool: name it too
+        reason = (f"KYA denied {name}: its MCP name {target} is on the never-list "
+                  f"({decision.reason_code})")
+    return decision, reason
+
+
+def gate(tool_id: str, args: dict | None = None, *, server: str | None = None,
+         irreversible: bool = False, strict: bool = False,
+         fail_closed: bool | None = None,
+         timeout: float = shield_kya.DEFAULT_TIMEOUT_S) -> shield_kya.Decision:
+    """Evaluate one tool call via `kya wrap`; raise KyaDenied unless allowed.
+
+    Same semantics as :func:`shield_kya.governed`: ALLOW and REQUIRE_APPROVE
+    pass (``strict`` blocks REQUIRE_APPROVE), DENY raises KyaDenied, and CLI
+    errors fail open unless ``fail_closed``.
+    """
+    decision = shield_kya.decide(tool_id, args, server=server, irreversible=irreversible,
+                                 strict=strict, fail_closed=fail_closed, timeout=timeout)
+    decision.raise_if_denied()
+    return decision

shield_kya/integrations/adk.py

@@ -0,0 +1,92 @@
+"""Google ADK adapter: one Runner-wide KYA plugin.
+
+    from google.adk.apps import App
+    from shield_kya.integrations.adk import KyaPlugin
+
+    app = App(name="my_app", root_agent=agent, plugins=[KyaPlugin()])
+
+``KyaPlugin`` hooks ``before_tool_callback``: every tool call the Runner
+dispatches (sub-agents, ``AgentTool`` with its default ``include_plugins=True``,
+MCP toolsets, long-running tools, live mode and workflow tool nodes included)
+is checked with ``kya wrap``, as an asyncio subprocess, before it executes. A
+DENY returns ``{"error": "<reason>"}``, which ADK uses as the tool result
+instead of running the tool, so the model reads the reason and the run
+continues. ``strict=True`` raises ``KyaDenied`` instead (ADK re-raises it as a
+``RuntimeError`` and the run aborts) and blocks REQUIRE_APPROVE too. CLI errors
+fail open unless ``fail_closed=True`` / ``KYA_FAIL_CLOSED=1``; the never-list
+blocks either way, also when this plugin's own code fails.
+
+The tool id is the name the model called (``tool.name``). For an MCP tool the
+original MCP name is checked against the never-list too, and so is
+``<tool_name_prefix>__<original name>``: ADK prefixes with one underscore
+(``postgres_drop_table``), which the never-list would not recognize. Put the
+plugin last in ``plugins`` so it sees the args other plugins rewrote.
+
+Tested with google-adk 2.11.0. The plugin class is built on first access, so
+this module imports without google-adk.
+"""
+
+from __future__ import annotations
+
+import shield_kya
+from shield_kya.integrations import _adecide_names, _mcp_names
+
+# KyaPlugin is left out of __all__ so a star import works without google-adk.
+__all__: list = []
+
+
+def _names(tool) -> list:
+    """The exposed name, then the original name ADK keeps on an MCP tool."""
+    name = str(getattr(tool, "name", "") or "")
+    original = None
+    # Public raw_mcp_tool (google-adk 2.11.0), else the private field it wraps; a
+    # broken one falls through to the next and never drops the exposed name.
+    for attr in ("raw_mcp_tool", "_mcp_tool"):
+        try:
+            original = getattr(getattr(tool, attr, None), "name", None)
+        except Exception:
+            continue
+        if original:
+            break
+    return _mcp_names(name, original)
+
+
+def _build_plugin():
+    try:
+        from google.adk.plugins.base_plugin import BasePlugin
+    except ImportError as exc:
+        raise ImportError(
+            "google-adk>=2.11 is required for KyaPlugin (pip install 'google-adk>=2.11,<3')"
+        ) from exc
+
+    class KyaPlugin(BasePlugin):
+        """Gate every tool call of an ADK Runner (register it on the App)."""
+
+        def __init__(self, *, name: str = "shield_kya", server: str | None = None,
+                     irreversible: bool = False, strict: bool = False,
+                     fail_closed: bool | None = None,
+                     timeout: float = shield_kya.DEFAULT_TIMEOUT_S) -> None:
+            super().__init__(name=name)
+            self._opts = dict(server=server, irreversible=irreversible, strict=strict,
+                              fail_closed=fail_closed, timeout=timeout)
+
+        async def before_tool_callback(self, *, tool, tool_args, tool_context):
+            # Anything that escapes this hook becomes a RuntimeError that aborts the
+            # run; _adecide_names never raises, so only strict mode raises here.
+            decision, reason = await _adecide_names(lambda: _names(tool), tool_args, self._opts)
+            if decision.allowed:
+                return None
+            if self._opts["strict"]:
+                decision.raise_if_denied()
+            return {"error": reason}
+
+    KyaPlugin.__module__ = __name__
+    return KyaPlugin
+
+
+def __getattr__(name: str):
+    # ponytail: lazy class so the stdlib suite imports this module without google-adk.
+    if name == "KyaPlugin":
+        cls = globals()["KyaPlugin"] = _build_plugin()
+        return cls
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")