hyperagents 1.2.3rc5.post3__py3-none-any.whl

hyperclaw/client_guard.py

@@ -0,0 +1,717 @@
+"""
+Restricted-client guard: content about a restricted client never reaches an
+outside model.
+
+Rule (Vaughn, 12 Oct 2026; CLIENT-AI-RESTRICTIONS 11 Oct): when the ACTIVE
+model is from an outside provider (anything that is not Hyper's own model,
+HyperSpeed V2), nothing involving a restricted client reaches it from Gmail,
+Slack, Calendar, Meet transcripts, Drive, Docs, Sheets, Slides or GitLab,
+whether the lead model or a specialist asked for it.
+
+Two layers:
+
+1. **Connector-result boundary** (``screen`` / ``filter_tool_result`` /
+   ``filter_items``): before a connector read enters any model request, every
+   item (one email thread, one event, one file, one transcript, one Slack or
+   GitLab item) that names a restricted client (name, alias, domain or
+   project name, also inside forwards and threads that never show the
+   client's domain) is withheld. Anything that could not be checked (binary,
+   unreadable, an unknown shape) is withheld too: when unsure, withhold.
+2. **Final check on the outgoing request body** (``redact_request`` /
+   ``final_check``), run by the cost guard's adapters, which every model call
+   in the package already goes through (tests/unit/test_cost_guard.py). An
+   outside request that still carries restricted content has those strings
+   replaced by a plain note; whatever cannot be replaced stops the request
+   (``RestrictedContentBlocked``) and nothing is sent.
+
+Every withholding is recorded on the current task, and the answer ends with
+one plain line saying what was left out and that switching to HyperSpeed V2
+includes it (``reply_note``). The note never names the client, so the note
+itself can never trip the guard.
+
+Configuration. No client is named in the package: it ships with an EMPTY
+default list. The list comes from the install profile:
+
+- the managed config (``hyperclaw/managed_config.py``), key
+  ``restricted_clients``: Hyper's list for the install (team and client
+  installs get it in their team profile);
+- ``restricted_clients_required: true`` in the same file: the profile MUST
+  carry a list. If it is missing, empty or unreadable while an outside
+  model is active, ALL connector content is withheld, and the user is told
+  why (fail safe);
+- ``$HYPERCLAW_ROOT/config/restricted_clients.json`` (or
+  ``HYPERCLAW_RESTRICTED_CLIENTS``): the owner may ADD entries, never
+  remove one.
+
+With no list and nothing required, there is nothing to withhold.
+
+Entry shape: ``{"name": "...", "aliases": [...], "domains": [...],
+"projects": [...]}``.
+"""
+from __future__ import annotations
+
+import contextlib
+import contextvars
+import html
+import json
+import logging
+import os
+import re
+import threading
+import unicodedata
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Dict, Iterable, List, Optional, Tuple
+
+log = logging.getLogger("hyperclaw.client_guard")
+
+# Shipped empty on purpose: no client is named in shipped code. The real
+# list arrives in each install's profile (managed config).
+DEFAULT_CLIENTS: Tuple[dict, ...] = ()
+
+# Said when the profile requires a list but has none (no client named).
+PROFILE_MISSING_NOTE = ("Withheld: the restricted-client list is missing from your install "
+                        "profile, so nothing from your connected accounts is shown to an "
+                        "outside model. Ask Vaughn to fix your install profile, or switch to "
+                        "HyperSpeed V2 (/model).")
+
+USER_FILE = "restricted_clients.json"
+ENV_FILE = "HYPERCLAW_RESTRICTED_CLIENTS"
+
+# What the model and the user see in place of withheld content. It never
+# names the client (so it can never trip the guard itself).
+PLACEHOLDER = ("[withheld: this is about a client whose agreement keeps their data on Hyper's "
+               "own models; switch to HyperSpeed V2 to include it]")
+
+# The sources this guard covers (taint origins and tool families).
+SOURCES = ("gmail", "slack", "google_calendar", "google_meet", "google_drive", "google_docs",
+           "google_sheets", "google_slides", "gitlab")
+SOURCE_LABELS = {
+    "gmail": "email", "slack": "Slack", "google_calendar": "calendar",
+    "google_meet": "Meet", "google_drive": "Drive", "google_docs": "Docs",
+    "google_sheets": "Sheets", "google_slides": "Slides", "gitlab": "GitLab",
+    "email": "email", "calendar": "calendar", "request": "earlier messages",
+}
+
+# Model tools whose results are connector content from the covered sources.
+# The Google Workspace tools register theirs (hyperclaw/google_workspace).
+CONNECTOR_TOOL_SOURCES: Dict[str, str] = {
+    "email_read": "gmail", "email_search": "gmail", "calendar_read": "google_calendar",
+    # GitLab reader (team of agents, rc5)
+    "gitlab_review_queue": "gitlab",
+    # hyperclaw/google_workspace/tools.py
+    "gmail_search": "gmail", "gmail_read_thread": "gmail", "gmail_read_attachment": "gmail",
+    "calendar_list_events": "google_calendar", "calendar_freebusy": "google_calendar",
+    "drive_search": "google_drive", "drive_read": "google_drive", "docs_read": "google_docs",
+    "sheets_read": "google_sheets", "slides_read": "google_slides",
+    "meet_list_records": "google_meet", "meet_read_transcript": "google_meet",
+}
+# One result is one item (a thread with all its messages, one file, one
+# transcript): withheld whole, never message by message.
+WHOLE_RESULT_TOOLS = frozenset({"gmail_read_thread", "gmail_read_attachment", "drive_read",
+                                "docs_read", "sheets_read", "slides_read",
+                                "meet_read_transcript"})
+# Of those, the legacy readers that return headers only (no body): their
+# results can't be checked for a forward or a thread that names the client
+# in the body, so under an outside model they are withheld whole.
+HEADER_ONLY_TOOLS = frozenset({"email_read", "email_search", "calendar_read"})
+
+
+# ───────────────────────── configuration ─────────────────────────
+
+@dataclass(frozen=True)
+class RestrictedClient:
+    name: str
+    aliases: Tuple[str, ...] = ()
+    domains: Tuple[str, ...] = ()
+    projects: Tuple[str, ...] = ()
+
+    def terms(self) -> List[str]:
+        return [t for t in (self.name,) + self.aliases + self.projects if t]
+
+
+def _strs(v: Any) -> Tuple[str, ...]:
+    if isinstance(v, str):
+        v = [v]
+    if not isinstance(v, (list, tuple)):
+        return ()
+    out = []
+    for x in v:
+        if isinstance(x, str) and x.strip():
+            out.append(x.strip())
+    return tuple(dict.fromkeys(out))
+
+
+def _entry(d: Any) -> Optional[RestrictedClient]:
+    if not isinstance(d, dict):
+        return None
+    name = d.get("name")
+    if not isinstance(name, str) or not name.strip():
+        return None
+    domains = tuple(x.lower().lstrip("@").strip(".") for x in _strs(d.get("domains")))
+    return RestrictedClient(name=name.strip(), aliases=_strs(d.get("aliases")),
+                            domains=tuple(x for x in domains if x),
+                            projects=_strs(d.get("projects")))
+
+
+def _root() -> Path:
+    return Path(os.environ.get("HYPERCLAW_ROOT", Path.home() / ".hyperclaw")).expanduser()
+
+
+def user_file() -> Path:
+    explicit = os.environ.get(ENV_FILE, "").strip()
+    if explicit:
+        return Path(explicit).expanduser()
+    return _root() / "config" / USER_FILE
+
+
+def _read_list(p: Path) -> list:
+    try:
+        if not p.is_file():
+            return []
+        data = json.loads(p.read_text(encoding="utf-8"))
+    except Exception as e:  # noqa: BLE001 -- never fatal: the defaults still apply
+        log.warning("restricted clients file %s unreadable (%s); defaults apply", p,
+                    type(e).__name__)
+        return []
+    if isinstance(data, dict):
+        data = data.get("restricted_clients")
+    return data if isinstance(data, list) else []
+
+
+def _managed() -> Tuple[list, bool, bool]:
+    """(profile list, list required, profile readable). A managed file that
+    exists but can't be read counts as requiring a list it doesn't have."""
+    try:
+        from hyperclaw import managed_config
+        data, ok = managed_config.raw()      # system file, else the verified team profile
+    except Exception:
+        return [], True, False
+    if not ok:
+        return [], True, False
+    if data is None:
+        return [], False, True
+    lst = data.get("restricted_clients")
+    return ((lst if isinstance(lst, list) else []),
+            data.get("restricted_clients_required") is True, True)
+
+
+def clients() -> List[RestrictedClient]:
+    """The restricted list in force: the install profile's list plus the
+    owner's additions (the package itself ships none)."""
+    defaults = [c for c in (_entry(d) for d in DEFAULT_CLIENTS) if c]
+    managed, _required, _ok = _managed()
+    mlist = [c for c in (_entry(d) for d in managed) if c]
+    extra = [c for c in (_entry(d) for d in _read_list(user_file())) if c]
+    return defaults + mlist + extra
+
+
+def placeholder() -> str:
+    """What stands in for withheld content (never names a client)."""
+    return PROFILE_MISSING_NOTE if profile_missing() else PLACEHOLDER
+
+
+def profile_missing() -> bool:
+    """The install profile requires a restricted-client list (or can't be
+    read) and has no valid entry: fail safe, withhold all connector content."""
+    managed, required, _ok = _managed()
+    if not required:
+        return False
+    return not any(_entry(d) for d in managed)
+
+
+def active() -> bool:
+    """Is there anything to protect? A list in force, or a missing required one."""
+    return profile_missing() or bool(matcher()._pats)
+
+
+# ───────────────────────── detection ─────────────────────────
+
+_ZW = re.compile(r"[­​-‏⁠]")
+_SEP = r"[\s\-_.·/]*"
+
+
+def normalize(text: str) -> str:
+    """NFKC, HTML entities decoded, zero-width characters removed, lower case."""
+    t = unicodedata.normalize("NFKC", str(text))
+    t = html.unescape(t)
+    t = _ZW.sub("", t)
+    return t.lower()
+
+
+def _term_pattern(term: str) -> str:
+    term = normalize(term).strip()
+    if re.fullmatch(r"[a-z]{2,6}", term) and term == term.strip():
+        # A short acronym: also "a.b.g." and "a b g".
+        body = r"[.\s]?".join(re.escape(ch) for ch in term) + r"\.?"
+    else:
+        parts = [p for p in re.split(r"[\s\-_.]+", term) if p]
+        body = _SEP.join(re.escape(p) for p in parts) if parts else re.escape(term)
+    return r"(?<![a-z0-9])" + body + r"(?![a-z0-9])"
+
+
+def _domain_pattern(dom: str) -> str:
+    return r"(?<![a-z0-9-])" + re.escape(dom.lower()) + r"(?![a-z0-9-])"
+
+
+class Matcher:
+    def __init__(self, entries: Iterable[RestrictedClient]):
+        self.entries = list(entries)
+        self._pats: List[Tuple[str, re.Pattern]] = []
+        for c in self.entries:
+            pats = [_term_pattern(t) for t in c.terms()] + [_domain_pattern(d)
+                                                             for d in c.domains]
+            if pats:
+                self._pats.append((c.name, re.compile("|".join(pats))))
+
+    def find(self, text: Any) -> List[str]:
+        """Names of the restricted clients `text` involves (any string inside it)."""
+        found: List[str] = []
+        for s in strings(text):
+            n = normalize(s)
+            for name, pat in self._pats:
+                if name not in found and pat.search(n):
+                    found.append(name)
+        return found
+
+    def hits(self, value: Any) -> bool:
+        return bool(self.find(value))
+
+
+_CACHE: Dict[str, Any] = {}
+_CACHE_LOCK = threading.Lock()
+
+
+def matcher() -> Matcher:
+    """The matcher for the list in force (rebuilt when a config file changes)."""
+    key_parts = []
+    for p in (user_file(),):
+        try:
+            key_parts.append(f"{p}:{p.stat().st_mtime_ns}")
+        except OSError:
+            key_parts.append(f"{p}:-")
+    try:
+        from hyperclaw import managed_config
+        key_parts.append(managed_config.source_key())
+    except Exception:
+        key_parts.append("managed:-")
+    key = "|".join(key_parts)
+    with _CACHE_LOCK:
+        if _CACHE.get("key") != key:
+            _CACHE["key"] = key
+            _CACHE["m"] = Matcher(clients())
+        return _CACHE["m"]
+
+
+def reset_cache() -> None:
+    with _CACHE_LOCK:
+        _CACHE.clear()
+
+
+def strings(value: Any, depth: int = 0) -> Iterable[str]:
+    if depth > 12 or value is None:
+        return
+    if isinstance(value, str):
+        yield value
+    elif isinstance(value, dict):
+        for k, v in value.items():
+            if isinstance(k, str):
+                yield k
+            yield from strings(v, depth + 1)
+    elif isinstance(value, (list, tuple, set)):
+        for v in value:
+            yield from strings(v, depth + 1)
+    elif hasattr(value, "model_dump"):
+        yield from strings(value.model_dump(), depth + 1)
+    elif hasattr(value, "__dict__") and not isinstance(value, type):
+        yield from strings(vars(value), depth + 1)
+    elif isinstance(value, (int, float, bool)):
+        return
+    else:
+        yield str(value)
+
+
+def checkable(value: Any, depth: int = 0) -> bool:
+    """False for anything this guard can't read as text (bytes, unknown objects)."""
+    if depth > 12:
+        return False
+    if value is None or isinstance(value, (str, int, float, bool)):
+        return True
+    if isinstance(value, (bytes, bytearray, memoryview)):
+        return False
+    if isinstance(value, dict):
+        return all(checkable(v, depth + 1) for v in value.values())
+    if isinstance(value, (list, tuple, set)):
+        return all(checkable(v, depth + 1) for v in value)
+    return False
+
+
+# ───────────────────────── is the active model outside? ─────────────────────────
+
+_OVERRIDE: contextvars.ContextVar = contextvars.ContextVar("hyperclaw_client_guard_model",
+                                                           default=None)
+
+
+def is_hyper_provider(provider: Optional[str]) -> bool:
+    """Hyper's own model (HyperSpeed V2, or a provider configured with origin
+    hyper). Anything unknown is outside."""
+    name = str(provider or "").strip()
+    if not name:
+        return False
+    try:
+        from hyperclaw import hyperspeed
+        if name == hyperspeed.PROVIDER_NAME:
+            return True
+    except Exception:
+        pass
+    try:
+        from hyperclaw.providers import registry
+        prov = registry().providers.get(name)
+        return prov is not None and getattr(prov, "origin", "") == "hyper"
+    except Exception:
+        return False
+
+
+@contextlib.contextmanager
+def model_scope(provider: str):
+    """Run the body as if `provider` were the active model (a caller that
+    knows exactly which model its reads go to: the digest, the brief, tests)."""
+    tok = _OVERRIDE.set(str(provider or ""))
+    try:
+        yield
+    finally:
+        _OVERRIDE.reset(tok)
+
+
+def note_model(provider: str) -> None:
+    """Called by the cost guard before every model request: the providers a
+    task's model calls went to (lead and specialists share the task)."""
+    try:
+        from hyperclaw.cost_guard import current_task
+        t = current_task()
+        if t is not None:
+            t.model_providers.add(str(provider or "unknown"))
+    except Exception:
+        pass
+
+
+def _third_party_live() -> bool:
+    """Could an outside model answer on this install at all? Unsure -> True."""
+    try:
+        from hyperclaw.providers import registry
+        for p in registry().providers.values():
+            if getattr(p, "origin", "customer") != "hyper" and getattr(p, "live", False):
+                return True
+        return False
+    except Exception:
+        return True
+
+
+def outside_model_active() -> bool:
+    """True when content read now could reach an outside model.
+
+    1. an explicit ``model_scope``;
+    2. the current task's model calls so far: any outside provider -> True
+       (a specialist on an outside model counts);
+    3. nothing known: True unless no outside provider is live on this
+       install. When unsure, withhold."""
+    o = _OVERRIDE.get()
+    if o is not None:
+        return not is_hyper_provider(o)
+    try:
+        from hyperclaw.cost_guard import current_task
+        t = current_task()
+        provs = set(getattr(t, "model_providers", ()) or ()) if t is not None else set()
+    except Exception:
+        provs = set()
+    if provs:
+        return any(not is_hyper_provider(p) for p in provs)
+    return _third_party_live()
+
+
+# ───────────────────────── withheld notes ─────────────────────────
+
+_FALLBACK_WITHHELD: Dict[str, int] = {}
+
+
+def _record(source: str, n: int) -> None:
+    if n <= 0:
+        return
+    try:
+        from hyperclaw.cost_guard import current_task
+        t = current_task()
+    except Exception:
+        t = None
+    if t is None:
+        _FALLBACK_WITHHELD[source] = _FALLBACK_WITHHELD.get(source, 0) + n
+        return
+    t.withheld[source] = t.withheld.get(source, 0) + n
+
+
+record = _record     # public name for the connector readers
+
+
+def withheld_counts(t: Any = None) -> Dict[str, int]:
+    if t is None:
+        return dict(_FALLBACK_WITHHELD)
+    return dict(getattr(t, "withheld", {}) or {})
+
+
+def note_text(counts: Dict[str, int]) -> str:
+    """One plain line: what was left out, and that V2 includes it."""
+    total = sum(counts.values())
+    if total <= 0:
+        return ""
+    kinds = sorted({SOURCE_LABELS.get(s, s.replace("_", " ")) for s in counts})
+    what = ", ".join(kinds)
+    items = "1 item" if total == 1 else f"{total} items"
+    return (f"Left out: {items} ({what}) about a client whose agreement keeps their data on "
+            f"Hyper's own models, because the model answering now is from an outside "
+            f"provider. Switch to HyperSpeed V2 (/model) to include them.")
+
+
+def reply_note(t: Any) -> str:
+    counts = withheld_counts(t)
+    if sum(counts.values()) > 0 and profile_missing():
+        return PROFILE_MISSING_NOTE
+    return note_text(counts)
+
+
+def message_note(n: int, source: str) -> str:
+    if n <= 0:
+        return ""
+    if profile_missing():
+        return (PROFILE_MISSING_NOTE + " Tell the user exactly this; do not guess what was "
+                "left out.")
+    label = SOURCE_LABELS.get(source, source)
+    items = "1 item" if n == 1 else f"{n} items"
+    return (f"Withheld {items} from {label}: about a client whose agreement keeps their data on "
+            f"Hyper's own models, and the model answering now is from an outside provider. "
+            f"Tell the user plainly that {items} {'was' if n == 1 else 'were'} left out and that "
+            f"switching to HyperSpeed V2 includes {'it' if n == 1 else 'them'}. Do not guess what "
+            f"{'it says' if n == 1 else 'they say'}.")
+
+
+# ───────────────────────── layer 1: the connector-result boundary ─────────────────────────
+
+def involves(value: Any) -> bool:
+    """Withhold this? The profile's required list is missing (fail safe),
+    it names a restricted client, or it can't be checked. With no list in
+    force (and none required) nothing is withheld."""
+    if profile_missing():
+        return True
+    m = matcher()
+    if not m._pats:
+        return False
+    return (not checkable(value)) or m.hits(value)
+
+
+def filter_items(items: List[Any], source: str, *, outside: Optional[bool] = None,
+                 record: bool = True) -> Tuple[List[Any], int]:
+    """Keep the items that don't involve a restricted client. Under Hyper's
+    own model everything is kept. Returns (kept, withheld count)."""
+    if outside is None:
+        outside = outside_model_active()
+    if not outside or not active():
+        return list(items), 0
+    kept, n = [], 0
+    for it in items:
+        if involves(it):
+            n += 1
+        else:
+            kept.append(it)
+    if record:
+        _record(source, n)
+    return kept, n
+
+
+def screen(value: Any, source: str, *, outside: Optional[bool] = None,
+           record: bool = True) -> Tuple[Any, int]:
+    """Whole-value screen: (value, 0) or (PLACEHOLDER, 1)."""
+    if outside is None:
+        outside = outside_model_active()
+    if not outside or not involves(value):
+        return value, 0
+    if record:
+        _record(source, 1)
+    return placeholder(), 1
+
+
+# Envelope data keys that hold one connector item per list element.
+ITEM_KEYS = ("items", "messages", "threads", "events", "files", "records", "entries",
+             "results")
+
+
+def filter_tool_result(tool: str, env: Any, *, outside: Optional[bool] = None) -> Any:
+    """The registry boundary for a connector tool's OK envelope: items that
+    involve a restricted client are withheld (lists of items one by one,
+    anything else whole), and the message says so. Other envelopes pass."""
+    source = CONNECTOR_TOOL_SOURCES.get(tool)
+    if source is None or getattr(env, "status", None) != "ok":
+        return env
+    if outside is None:
+        outside = outside_model_active()
+    if not outside or not active():
+        return env
+    data = env.data
+    withheld = 0
+    if tool in HEADER_ONLY_TOOLS:
+        new_data, withheld = placeholder(), 1
+        _record(source, 1)
+        msg = (f"{tool} can't show message or event bodies, so it can't check them for a client "
+               f"whose agreement keeps their data on Hyper's own models; nothing it read is "
+               f"shown while an outside model is answering. Use the Google Workspace tools "
+               f"(they check each thread and event), or switch to HyperSpeed V2.")
+        return env.model_copy(update={"data": new_data, "message": msg})
+    if tool not in WHOLE_RESULT_TOOLS and isinstance(data, dict) \
+            and any(isinstance(data.get(k), list) for k in ITEM_KEYS):
+        new_data = dict(data)
+        for k in ITEM_KEYS:
+            if isinstance(data.get(k), list):
+                kept, n = filter_items(data[k], source, outside=True)
+                new_data[k] = kept
+                withheld += n
+        rest = {k: v for k, v in new_data.items() if k not in ITEM_KEYS
+                and k not in ("withheld", "note")}
+        if involves(rest):          # e.g. a thread subject at the top level
+            _record(source, 1)
+            withheld += 1
+            new_data = {"withheld": withheld, "note": placeholder()}
+        elif withheld:
+            new_data["withheld"] = int(new_data.get("withheld") or 0) + withheld
+    else:
+        new_data, withheld = screen(data, source, outside=True)
+    msg = env.message
+    if involves(msg):
+        msg = f"{tool} completed."
+        if not withheld:
+            withheld = 1
+            _record(source, 1)
+            new_data = placeholder()
+    if not withheld:
+        return env
+    note = message_note(withheld, source)
+    return env.model_copy(update={"data": new_data, "message": (msg + " " + note).strip()})
+
+
+# ───────────────────────── layer 2: the outgoing request body ─────────────────────────
+
+class RestrictedContentBlocked(Exception):
+    """An outside model request still carried restricted content that could
+    not be withheld: the request was NOT sent."""
+
+    def __init__(self, provider: str = ""):
+        self.provider = provider
+        super().__init__(self.user_message)
+
+    @property
+    def user_message(self) -> str:
+        return ("Not sent: this request includes content about a client whose agreement keeps "
+                "their data on Hyper's own models, and the model answering now is from an "
+                "outside provider. Nothing was sent to it. Switch to HyperSpeed V2 (/model), or "
+                "start a new conversation (/reset) without that content.")
+
+
+# Request keys that carry content. Everything else (model, max_tokens, ...)
+# is left alone.
+REQUEST_CONTENT_KEYS = ("system", "messages", "input", "instructions", "prompt", "tools")
+# Inside messages: protocol fields that are never content.
+_PROTOCOL_KEYS = frozenset({"role", "type", "id", "tool_use_id", "tool_call_id", "name",
+                            "model", "cache_control", "media_type", "stop_reason",
+                            "index", "status"})
+
+
+def _redact(value: Any, m: Matcher, counter: list, *, paragraphs: bool = False,
+            key: str = "", depth: int = 0) -> Any:
+    if depth > 16:
+        return value
+    if isinstance(value, str):
+        if key in _PROTOCOL_KEYS or not m.hits(value):
+            return value
+        if key == "arguments":       # an OpenAI tool call's JSON arguments
+            counter[0] += 1
+            return json.dumps({"withheld": placeholder()})
+        if paragraphs:               # the system prompt: only the paragraphs that match
+            parts = re.split(r"(\n\s*\n)", value)
+            out = []
+            for p in parts:
+                if p.strip() and m.hits(p):
+                    counter[0] += 1
+                    out.append(placeholder())
+                else:
+                    out.append(p)
+            return "".join(out)
+        counter[0] += 1
+        return placeholder()
+    if isinstance(value, dict):
+        return {k: _redact(v, m, counter, paragraphs=paragraphs, key=str(k), depth=depth + 1)
+                for k, v in value.items()}
+    if isinstance(value, list):
+        return [_redact(v, m, counter, paragraphs=paragraphs, key=key, depth=depth + 1)
+                for v in value]
+    if isinstance(value, tuple):
+        return tuple(_redact(v, m, counter, paragraphs=paragraphs, key=key, depth=depth + 1)
+                     for v in value)
+    if hasattr(value, "model_dump"):        # SDK message objects in a history
+        try:
+            return _redact(value.model_dump(), m, counter, paragraphs=paragraphs, key=key,
+                           depth=depth + 1) if m.hits(value) else value
+        except Exception:
+            return value
+    return value
+
+
+class _ConnectorContent:
+    """Fail-safe matcher when the profile's required list is missing: any
+    string that is connector content (type tag or the taint ledger)."""
+
+    def hits(self, value: Any) -> bool:
+        from hyperclaw import taint
+        for s in strings(value):
+            if isinstance(s, taint.TaintedText):
+                return True
+            try:
+                if taint._matches_any(s):
+                    return True
+            except Exception:
+                return True          # can't check: withhold
+        return False
+
+
+def _request_matcher():
+    return _ConnectorContent() if profile_missing() else matcher()
+
+
+def redact_request(provider: str, kw: dict) -> dict:
+    """For an SDK call's keyword arguments: under an outside provider, every
+    content string that names a restricted client is replaced by the note
+    (whole message content; for the system prompt, the matching paragraphs).
+    Returns the kwargs to send (a copy when anything changed)."""
+    if is_hyper_provider(provider) or not isinstance(kw, dict):
+        return kw
+    m = _request_matcher()
+    counter = [0]
+    out = dict(kw)
+    for k in REQUEST_CONTENT_KEYS:
+        if k in out and out[k] is not None and k != "tools":
+            out[k] = _redact(out[k], m, counter, paragraphs=(k in ("system", "instructions")))
+    if counter[0]:
+        _record("request", counter[0])
+        log.info("client guard: withheld %d restricted part(s) from a %s request",
+                 counter[0], provider or "?")
+        return out
+    return kw
+
+
+def final_check(provider: str, request: Any) -> None:
+    """Last check before a request leaves: an outside provider's request that
+    still involves a restricted client is stopped. Raises
+    RestrictedContentBlocked; nothing is sent."""
+    if is_hyper_provider(provider):
+        return
+    if request is None:
+        return
+    if _request_matcher().hits(request):
+        log.warning("client guard: stopped a %s request carrying restricted content",
+                    provider or "?")
+        raise RestrictedContentBlocked(provider)