hyperagents 1.2.3rc5.post3__py3-none-any.whl

hyperclaw/tools/approval.py

@@ -0,0 +1,949 @@
+"""
+The approval layer (tool standard wave 3): Send / Edit / Cancel.
+
+Every send, post or write the model asks for (every tool that is not
+read-only: `ask`-tier calls, and on the terminal shell / code / desktop
+control too; on every surface: terminal, Telegram, server/dashboard,
+sub-agents) is NOT run. It is
+stored in a durable queue, bound to a hash of the exact payload, and shown to
+the owner with its exact content. Only the owner can then:
+
+- Send   -> the stored payload runs, exactly once (compare-and-set on the
+            queue row, and the effect ledger key on top), and only if the
+            hash the owner approved still matches the stored payload;
+- Edit   -> the owner changes the content; the old item is superseded and a
+            new one (new id, new hash) is shown again;
+- Cancel -> nothing runs.
+
+The same queue holds:
+- task/plan changes (bench 15.6: "task changes are proposed, not applied");
+- calls from sub-agents (bench 18.5: they inherit the owner's approval limits;
+  an agent can never approve);
+- fetches by a tool that runs without asking (read tools, download,
+  open_url) of a URL that is not verbatim in the user's own words, or that
+  points at a private address (tools/egress.py);
+- service recovery actions on HyperClaw's own allowlisted services (17.4/17.5,
+  tools/service_guard.py).
+
+Store: $HYPERCLAW_ROOT/approvals/pending.sqlite3 (HYPERCLAW_APPROVAL_QUEUE
+overrides), mode 0600, directory 0700. State changes are compare-and-set
+updates on `pending_actions`; `approval_events` is append-only (triggers
+refuse UPDATE and DELETE). Restart-safe: a pending item survives a restart and
+can still be approved; an item that was executing when the process died is
+marked `uncertain` and never re-run. Stale items expire
+(HYPERCLAW_APPROVAL_TTL_S, default 24 h).
+
+Trusted per-contact auto-send is a config hook (`auto_send_allowed`), OFF by
+default: $HYPERCLAW_ROOT/approval.json {"auto_send": {"enabled": false,
+"contacts": [], "domains": []}}. Nothing is trusted until the owner writes
+that file.
+
+Design notes: the queue-and-approve shape (approve only WHERE status is
+'pending', reject, list pending) and the recipient-domain classification of
+the auto-send hook follow an earlier internal assistant's approval tiers; the
+domain list there was hard-coded and is config-driven and empty here.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import logging
+import os
+import secrets
+import sqlite3
+import threading
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Callable, Dict, Iterable, List, Optional, Tuple
+
+from . import egress
+from . import service_guard
+
+log = logging.getLogger("hyperclaw.tools.approval")
+
+DEFAULT_TTL_S = 24 * 3600
+
+# Item statuses.
+PENDING = "pending"
+EXECUTING = "executing"
+DONE = "done"
+FAILED = "failed"
+UNCERTAIN = "uncertain"
+CANCELLED = "cancelled"
+SUPERSEDED = "superseded"
+EXPIRED = "expired"
+FINAL = (DONE, FAILED, UNCERTAIN, CANCELLED, SUPERSEDED, EXPIRED)
+
+# Gate kinds (why an item needs the owner).
+KIND_ASK = "ask"
+KIND_PLAN = "plan_change"
+KIND_SERVICE = "service"
+KIND_URL = "unverified_url"
+KIND_PRIVATE = "private_target"
+
+PLAN_TOOLS = frozenset({"plan_create", "plan_update"})
+
+# Reads whose output is someone else's content (email, web, documents). After
+# one of these ran in a turn, text the model "found" there is data: a service
+# action needs the user's own words (17.5).
+PURE_COMPUTE = frozenset({"math", "hash", "uuid_generate", "base64_encode", "json_format",
+                          "regex_test", "time_info", "unit_convert", "memory_stats",
+                          "plan_status", "plan_next", "plan_list", "agent_status",
+                          "swarm_roster", "learning_stats"})
+
+# The one field a plain-text Edit replaces, per tool (else the owner sends JSON).
+EDIT_FIELD = {
+    "telegram": "message", "slack": "message", "discord": "message", "imessage": "message",
+    "email_send": "body", "email_draft": "body", "http_request": "body",
+    "calendar_create": "title", "plan_create": "goal", "bash": "command",
+    "python_exec": "code", "applescript": "script", "web_fetch": "url",
+    "github": "body", "sql_query": "query", "memory_forget": "query",
+    "image_generate": "prompt", "document_create": "notes",
+    # Writes and local actions (every non-read tool is gated).
+    "write_file": "content", "edit_file": "new_text", "clipboard_write": "text",
+    "memory_store": "content", "download": "url", "qr_code": "data",
+    "learning_log": "detail", "learning_feedback": "feedback", "agent_watch": "target",
+    "agent_start": "name",
+    "notification": "message", "speak": "text",
+    # Desktop / app control (terminal only).
+    "type_text": "text", "open_url": "url", "open_file": "path", "open_app": "app_name",
+    # Google Workspace (hyperclaw/google_workspace/tools.py EDIT_FIELD).
+    "gmail_send": "body", "gmail_create_draft": "body",
+    "calendar_create_event": "title", "calendar_update_event": "title",
+}
+
+# What a terminal-only action does, in one line, above its exact content.
+ACTION_LINE = {
+    "bash": "Run this exact command line in a shell on this computer",
+    "python_exec": "Run this exact Python code on this computer",
+    "applescript": "Run this exact AppleScript on this computer (it can control any app)",
+    "type_text": "Type this exact text into whichever app is in front",
+    "key_press": "Press these exact keys in whichever app is in front",
+    "mouse_click": "Click the mouse at this exact screen position",
+    "open_app": "Open this app",
+    "open_file": "Open this file on this computer",
+    "open_url": "Open this exact address in the browser",
+    "record_audio": "Record from this computer's microphone",
+    "notification": "Show this notification on this computer",
+    "speak": "Say this text out loud on this computer",
+    "agent_stop": "Stop this background monitor",
+    "agent_start": ("Start background watchers. They only ever message YOU, one line each "
+                    "(who, what, one line); they never open links, reply, post or act. "
+                    "Anything else waits for your Send"),
+    "agent_watch": "Add this to a background monitor's watch list",
+    "transcribe_audio": "Send this audio file to the transcription service and save the text",
+    "transcribe_video": "Send this video's audio to the transcription service and save the text",
+    "learning_reflect": "Summarise recent activity and save the summary in the learning log",
+    "vision": "Upload this image file to the image-analysis model and ask this question",
+    # Google Workspace (hyperclaw/google_workspace/tools.py ACTION_LINE).
+    "gmail_send": "Send this exact email from your Gmail",
+    "gmail_create_draft": "Save this exact email as a Gmail draft (it is not sent)",
+    "calendar_create_event": "Create this event in your Google Calendar",
+    "calendar_update_event": "Change this event in your Google Calendar",
+}
+
+_VERB = {"send": "send", "write": "make a change", "spend": "spend", "delete": "delete",
+         "system": "run an action", "read": "fetch"}
+
+_SCHEMA = """
+CREATE TABLE IF NOT EXISTS pending_actions (
+    id            TEXT PRIMARY KEY,
+    created       REAL NOT NULL,
+    expires       REAL NOT NULL,
+    conversation  TEXT NOT NULL,
+    surface       TEXT NOT NULL,
+    scope         TEXT NOT NULL,
+    requester     TEXT NOT NULL,
+    tool          TEXT NOT NULL,
+    args          TEXT NOT NULL,
+    payload_hash  TEXT NOT NULL,
+    kind          TEXT NOT NULL,
+    reason        TEXT,
+    untrusted     INTEGER NOT NULL DEFAULT 0,
+    status        TEXT NOT NULL,
+    decided_by    TEXT,
+    decided_at    REAL,
+    edit_of       TEXT,
+    result        TEXT,
+    receipt_id    TEXT,
+    notified      TEXT
+);
+CREATE INDEX IF NOT EXISTS pending_actions_status ON pending_actions (status, conversation);
+CREATE TABLE IF NOT EXISTS approval_events (
+    id           INTEGER PRIMARY KEY AUTOINCREMENT,
+    ts           REAL NOT NULL,
+    action_id    TEXT NOT NULL,
+    event        TEXT NOT NULL,
+    actor        TEXT,
+    payload_hash TEXT,
+    detail       TEXT
+);
+CREATE TRIGGER IF NOT EXISTS approval_events_no_update BEFORE UPDATE ON approval_events
+BEGIN SELECT RAISE(ABORT, 'approval_events is append-only'); END;
+CREATE TRIGGER IF NOT EXISTS approval_events_no_delete BEFORE DELETE ON approval_events
+BEGIN SELECT RAISE(ABORT, 'approval_events is append-only'); END;
+"""
+
+
+# ───────────────────────── identity ─────────────────────────
+
+@dataclass(frozen=True)
+class Actor:
+    """Who is deciding. Only role "owner" may Send, Edit or Cancel."""
+    role: str                    # "owner" | "guest" | "agent"
+    id: str = ""
+    surface: str = ""            # where the decision is made ("tui", "telegram", "server")
+
+    @property
+    def is_owner(self) -> bool:
+        return self.role == "owner"
+
+    def label(self) -> str:
+        return f"{self.role}:{self.surface or '-'}:{self.id or '-'}"
+
+
+TERMINAL_OWNER = Actor("owner", "local", "tui")
+
+
+# ───────────────────────── payload identity ─────────────────────────
+
+def canonical_args(args: Any) -> str:
+    return json.dumps(args if args is not None else {}, sort_keys=True, ensure_ascii=False,
+                      separators=(",", ":"), default=str)
+
+
+def payload_hash(tool: str, args: Any) -> str:
+    """sha256 over the exact tool and arguments (the approval binds to this)."""
+    return hashlib.sha256(f"{tool}\n{canonical_args(args)}".encode("utf-8")).hexdigest()
+
+
+@dataclass
+class PendingAction:
+    id: str
+    created: float
+    expires: float
+    conversation: str
+    surface: str
+    scope: str
+    requester: str
+    tool: str
+    args: Dict[str, Any]
+    payload_hash: str
+    kind: str
+    reason: str = ""
+    untrusted: bool = False
+    status: str = PENDING
+    decided_by: Optional[str] = None
+    decided_at: Optional[float] = None
+    edit_of: Optional[str] = None
+    result: Optional[str] = None
+    receipt_id: Optional[str] = None
+    notified: Optional[str] = None
+
+    @property
+    def short_hash(self) -> str:
+        return self.payload_hash[:16]
+
+    @classmethod
+    def from_row(cls, row: sqlite3.Row) -> "PendingAction":
+        d = dict(row)
+        d["args"] = json.loads(d["args"])
+        d["untrusted"] = bool(d.get("untrusted"))
+        return cls(**d)
+
+
+def _env_float(name: str, default: float) -> float:
+    try:
+        return float(os.environ.get(name, default))
+    except (TypeError, ValueError):
+        return float(default)
+
+
+def hyperclaw_root() -> Path:
+    return Path(os.environ.get("HYPERCLAW_ROOT", Path.home() / ".hyperclaw")).expanduser()
+
+
+def default_path() -> Path:
+    explicit = os.environ.get("HYPERCLAW_APPROVAL_QUEUE")
+    if explicit:
+        return Path(explicit).expanduser()
+    return hyperclaw_root() / "approvals" / "pending.sqlite3"
+
+
+class ApprovalError(Exception):
+    """A decision that was refused (not the owner, wrong hash, expired, ...)."""
+
+
+# ───────────────────────── the durable queue ─────────────────────────
+
+class ApprovalQueue:
+    def __init__(self, path: Optional[os.PathLike] = None):
+        self.path = Path(path) if path else default_path()
+        self._lock = threading.Lock()
+        self._ready = False
+
+    def _connect(self) -> sqlite3.Connection:
+        if not self._ready:
+            with self._lock:
+                if not self._ready:
+                    self.path.parent.mkdir(parents=True, exist_ok=True)
+                    try:
+                        os.chmod(self.path.parent, 0o700)
+                    except OSError:
+                        pass
+                    fd = os.open(self.path, os.O_CREAT | os.O_RDWR, 0o600)
+                    os.close(fd)
+                    con = sqlite3.connect(self.path, timeout=10, isolation_level=None)
+                    try:
+                        con.execute("PRAGMA journal_mode=WAL")
+                        con.executescript(_SCHEMA)
+                    finally:
+                        con.close()
+                    for p in (self.path, Path(f"{self.path}-wal"), Path(f"{self.path}-shm")):
+                        try:
+                            os.chmod(p, 0o600)
+                        except OSError:
+                            pass
+                    self._ready = True
+        con = sqlite3.connect(self.path, timeout=10, isolation_level=None)
+        con.row_factory = sqlite3.Row
+        return con
+
+    @staticmethod
+    def ttl_s() -> float:
+        return _env_float("HYPERCLAW_APPROVAL_TTL_S", DEFAULT_TTL_S)
+
+    @staticmethod
+    def _event(con, action_id: str, event: str, actor: str = "", payload_hash: str = "",
+               detail: str = "") -> None:
+        con.execute("INSERT INTO approval_events (ts, action_id, event, actor, payload_hash, "
+                    "detail) VALUES (?,?,?,?,?,?)",
+                    (time.time(), action_id, event, actor, payload_hash, (detail or "")[:500]))
+
+    # ── propose ──
+    def propose(self, *, tool: str, args: Dict[str, Any], conversation: str, surface: str,
+                scope: str = "owner", requester: str = "owner", kind: str = KIND_ASK,
+                reason: str = "", untrusted: bool = False,
+                edit_of: Optional[str] = None) -> PendingAction:
+        """Queue one call. An identical pending call in the same conversation
+        is returned as is (no second card for the same payload)."""
+        h = payload_hash(tool, args)
+        now = time.time()
+        con = self._connect()
+        try:
+            con.execute("BEGIN IMMEDIATE")
+            self._expire(con, now)
+            row = con.execute("SELECT * FROM pending_actions WHERE conversation=? AND "
+                              "payload_hash=? AND status=? ORDER BY created DESC LIMIT 1",
+                              (conversation, h, PENDING)).fetchone()
+            if row is not None and edit_of is None:
+                con.execute("COMMIT")
+                return PendingAction.from_row(row)
+            aid = secrets.token_hex(6)
+            con.execute(
+                "INSERT INTO pending_actions (id, created, expires, conversation, surface, scope, "
+                "requester, tool, args, payload_hash, kind, reason, untrusted, status, edit_of) "
+                "VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)",
+                (aid, now, now + self.ttl_s(), conversation, surface, scope, requester, tool,
+                 canonical_args(args), h, kind, reason, int(bool(untrusted)), PENDING, edit_of))
+            self._event(con, aid, "proposed", requester, h, reason)
+            con.execute("COMMIT")
+        except Exception:
+            _rollback(con)
+            raise
+        finally:
+            con.close()
+        return self.get(aid)
+
+    # ── readers ──
+    def get(self, action_id: str) -> Optional[PendingAction]:
+        con = self._connect()
+        try:
+            row = con.execute("SELECT * FROM pending_actions WHERE id=?",
+                              (str(action_id),)).fetchone()
+            return PendingAction.from_row(row) if row else None
+        finally:
+            con.close()
+
+    def pending(self, conversation: Optional[str] = None,
+                unnotified_only: bool = False) -> List[PendingAction]:
+        con = self._connect()
+        try:
+            con.execute("BEGIN IMMEDIATE")
+            self._expire(con, time.time())
+            con.execute("COMMIT")
+            q = "SELECT * FROM pending_actions WHERE status=?"
+            params: list = [PENDING]
+            if conversation:
+                q += " AND conversation=?"
+                params.append(conversation)
+            if unnotified_only:
+                q += " AND notified IS NULL"
+            q += " ORDER BY created"
+            return [PendingAction.from_row(r) for r in con.execute(q, params).fetchall()]
+        finally:
+            con.close()
+
+    def events(self, action_id: Optional[str] = None) -> List[Dict[str, Any]]:
+        con = self._connect()
+        try:
+            if action_id:
+                cur = con.execute("SELECT * FROM approval_events WHERE action_id=? ORDER BY id",
+                                  (action_id,))
+            else:
+                cur = con.execute("SELECT * FROM approval_events ORDER BY id")
+            return [dict(r) for r in cur.fetchall()]
+        finally:
+            con.close()
+
+    def mark_notified(self, action_id: str, note: str) -> None:
+        con = self._connect()
+        try:
+            con.execute("UPDATE pending_actions SET notified=? WHERE id=?", (note, action_id))
+        finally:
+            con.close()
+
+    # ── decisions ──
+    def _expire(self, con, now: float) -> None:
+        rows = con.execute("SELECT id, payload_hash FROM pending_actions WHERE status=? AND "
+                           "expires<=?", (PENDING, now)).fetchall()
+        for r in rows:
+            con.execute("UPDATE pending_actions SET status=?, decided_at=? WHERE id=? AND "
+                        "status=?", (EXPIRED, now, r["id"], PENDING))
+            self._event(con, r["id"], "expired", "", r["payload_hash"])
+
+    def expire_stale(self) -> int:
+        con = self._connect()
+        try:
+            con.execute("BEGIN IMMEDIATE")
+            before = con.total_changes
+            self._expire(con, time.time())
+            n = con.total_changes - before
+            con.execute("COMMIT")
+            return n // 2  # one update + one event row per item
+        finally:
+            con.close()
+
+    def recover_interrupted(self) -> List[str]:
+        """At startup: an item left `executing` (the process died mid-call)
+        may or may not have happened. Mark it uncertain; never re-run it."""
+        con = self._connect()
+        try:
+            con.execute("BEGIN IMMEDIATE")
+            rows = con.execute("SELECT id, payload_hash FROM pending_actions WHERE status=?",
+                               (EXECUTING,)).fetchall()
+            for r in rows:
+                con.execute("UPDATE pending_actions SET status=?, result=? WHERE id=? AND "
+                            "status=?", (UNCERTAIN, "interrupted while running; outcome "
+                                         "unknown", r["id"], EXECUTING))
+                self._event(con, r["id"], "uncertain", "", r["payload_hash"], "interrupted")
+            con.execute("COMMIT")
+            return [r["id"] for r in rows]
+        finally:
+            con.close()
+
+    def _decidable(self, con, action_id: str, actor: Actor) -> PendingAction:
+        if not isinstance(actor, Actor) or not actor.is_owner:
+            who = actor.label() if isinstance(actor, Actor) else repr(actor)
+            self._event(con, str(action_id), "refused", who, "", "not the owner")
+            raise ApprovalError("Only the owner can approve, edit or cancel this.")
+        self._expire(con, time.time())
+        row = con.execute("SELECT * FROM pending_actions WHERE id=?",
+                          (str(action_id),)).fetchone()
+        if row is None:
+            raise ApprovalError("No such pending action.")
+        item = PendingAction.from_row(row)
+        if item.status != PENDING:
+            raise ApprovalError(f"This action is already {item.status}; nothing was run.")
+        if payload_hash(item.tool, item.args) != item.payload_hash:
+            self._event(con, item.id, "refused", actor.label(), item.payload_hash,
+                        "stored payload does not match its hash")
+            raise ApprovalError("The stored payload does not match what was approved; refused.")
+        if item.tool in _terminal_only() and actor.surface != "tui":
+            raise ApprovalError("This action can only be approved in the HyperAgents "
+                                "terminal on the computer.")
+        return item
+
+    def claim(self, action_id: str, approved_hash: str, actor: Actor) -> PendingAction:
+        """Owner pressed Send for the payload whose hash is `approved_hash`.
+        Moves the item pending -> executing exactly once."""
+        con = self._connect()
+        try:
+            con.execute("BEGIN IMMEDIATE")
+            try:
+                item = self._decidable(con, action_id, actor)
+                h = str(approved_hash or "")
+                if len(h) < 16 or not item.payload_hash.startswith(h):
+                    self._event(con, item.id, "refused", actor.label(), h, "payload hash mismatch")
+                    raise ApprovalError("The approved content does not match the queued "
+                                        "payload (it was changed); nothing was run.")
+                cur = con.execute("UPDATE pending_actions SET status=?, decided_by=?, "
+                                  "decided_at=? WHERE id=? AND status=? AND payload_hash=?",
+                                  (EXECUTING, actor.label(), time.time(), item.id, PENDING,
+                                   item.payload_hash))
+                if cur.rowcount != 1:
+                    raise ApprovalError("This action was already decided; nothing was run.")
+                self._event(con, item.id, "approved", actor.label(), item.payload_hash)
+                con.execute("COMMIT")
+            except ApprovalError:
+                con.execute("COMMIT")  # keep the refusal event
+                raise
+        except ApprovalError:
+            raise
+        except Exception:
+            _rollback(con)
+            raise
+        finally:
+            con.close()
+        item.status = EXECUTING
+        item.decided_by = actor.label()
+        return item
+
+    def finish(self, action_id: str, status: str, result: str = "",
+               receipt_id: Optional[str] = None) -> None:
+        con = self._connect()
+        try:
+            con.execute("BEGIN IMMEDIATE")
+            con.execute("UPDATE pending_actions SET status=?, result=?, receipt_id=? WHERE id=? "
+                        "AND status=?", (status, (result or "")[:4000], receipt_id, action_id,
+                                         EXECUTING))
+            self._event(con, action_id, status, "", "", (result or "")[:300])
+            con.execute("COMMIT")
+        finally:
+            con.close()
+
+    def cancel(self, action_id: str, actor: Actor) -> PendingAction:
+        con = self._connect()
+        try:
+            con.execute("BEGIN IMMEDIATE")
+            try:
+                item = self._decidable(con, action_id, actor)
+                con.execute("UPDATE pending_actions SET status=?, decided_by=?, decided_at=? "
+                            "WHERE id=? AND status=?", (CANCELLED, actor.label(), time.time(),
+                                                        item.id, PENDING))
+                self._event(con, item.id, "cancelled", actor.label(), item.payload_hash)
+                con.execute("COMMIT")
+            except ApprovalError:
+                con.execute("COMMIT")
+                raise
+        finally:
+            con.close()
+        item.status = CANCELLED
+        return item
+
+    def supersede(self, action_id: str, new_args: Dict[str, Any], actor: Actor) -> PendingAction:
+        """Edit: the old item is superseded; the edited payload is a new
+        pending item (new id, new hash) that must be shown and sent again."""
+        con = self._connect()
+        try:
+            con.execute("BEGIN IMMEDIATE")
+            try:
+                item = self._decidable(con, action_id, actor)
+                con.execute("UPDATE pending_actions SET status=?, decided_by=?, decided_at=? "
+                            "WHERE id=? AND status=?", (SUPERSEDED, actor.label(), time.time(),
+                                                        item.id, PENDING))
+                self._event(con, item.id, "edited", actor.label(), item.payload_hash)
+                con.execute("COMMIT")
+            except ApprovalError:
+                con.execute("COMMIT")
+                raise
+        finally:
+            con.close()
+        return self.propose(tool=item.tool, args=new_args, conversation=item.conversation,
+                            surface=item.surface, scope=item.scope, requester=item.requester,
+                            kind=item.kind, reason=item.reason, untrusted=item.untrusted,
+                            edit_of=item.id)
+
+
+def _rollback(con) -> None:
+    try:
+        con.execute("ROLLBACK")
+    except sqlite3.Error:
+        pass
+
+
+def _terminal_only() -> frozenset:
+    from .surfaces import NEVER_FROM_CHAT
+    return NEVER_FROM_CHAT
+
+
+_QUEUES: Dict[str, ApprovalQueue] = {}
+_QUEUES_LOCK = threading.Lock()
+
+
+def get_queue() -> ApprovalQueue:
+    """The queue for the current HYPERCLAW_ROOT (read at call time)."""
+    p = str(default_path())
+    with _QUEUES_LOCK:
+        if p not in _QUEUES:
+            _QUEUES[p] = ApprovalQueue(p)
+        return _QUEUES[p]
+
+
+# ───────────────────────── trusted auto-send hook (OFF by default) ─────────────────────────
+
+def _approval_config() -> dict:
+    p = Path(os.environ.get("HYPERCLAW_APPROVAL_CONFIG", hyperclaw_root() / "approval.json"))
+    try:
+        with open(p, encoding="utf-8") as f:
+            cfg = json.load(f)
+        return cfg if isinstance(cfg, dict) else {}
+    except (OSError, ValueError):
+        return {}
+
+
+def _recipients(tool: str, args: dict) -> List[str]:
+    vals: List[str] = []
+    for k in ("to", "cc", "bcc", "recipient"):
+        v = args.get(k)
+        if isinstance(v, str):
+            vals.extend(x.strip().strip("<>").lower() for x in v.replace(";", ",").split(","))
+        elif isinstance(v, (list, tuple)):
+            vals.extend(str(x).strip().strip("<>").lower() for x in v)
+    return [v for v in vals if v]
+
+
+AUTO_SEND_TOOLS = frozenset({"email_send", "imessage"})
+
+
+def auto_send_allowed(tool: str, args: dict) -> bool:
+    """Trusted per-contact auto-send. OFF unless the owner's approval.json
+    sets auto_send.enabled = true AND every recipient of this message is a
+    listed contact or in a listed domain. Only plain sends to named people
+    (AUTO_SEND_TOOLS) can ever qualify."""
+    if tool not in AUTO_SEND_TOOLS:
+        return False
+    cfg = _approval_config().get("auto_send") or {}
+    if cfg.get("enabled") is not True:
+        return False
+    contacts = {str(c).strip().lower() for c in cfg.get("contacts") or [] if str(c).strip()}
+    domains = {str(d).strip().lower().lstrip("@") for d in cfg.get("domains") or []
+               if str(d).strip()}
+    rcpts = _recipients(tool, args or {})
+    if not rcpts:
+        return False
+    for r in rcpts:
+        dom = r.rsplit("@", 1)[-1] if "@" in r else None
+        if r not in contacts and not (dom and dom in domains):
+            return False
+    return True
+
+
+# ───────────────────────── the gate (called by ToolRegistry.dispatch) ─────────────────────────
+
+@dataclass
+class Gate:
+    action: str                      # "approve" | "deny"
+    kind: str
+    reason: str
+    data: Dict[str, Any] = field(default_factory=dict)
+
+
+def evaluate(spec, args: dict, *, surface: str, guard=None) -> Optional[Gate]:
+    """None = run now. Otherwise the call is queued for the owner ("approve")
+    or refused outright ("deny"). Never runs anything."""
+    name = spec.name
+    provenance = list(getattr(guard, "provenance", None) or [])
+    untrusted = bool(getattr(guard, "untrusted_seen", False))
+
+    svc = service_guard.check_tool(name, args)
+    if svc is not None:
+        if svc.verdict == "deny":
+            return Gate("deny", KIND_SERVICE, svc.reason)
+        if guard is None:
+            return Gate("deny", KIND_SERVICE, "service actions need the owner's approval and "
+                                              "this call has no approval channel")
+        if untrusted:
+            said = " ".join(provenance)
+            if not all(lbl in said for lbl in svc.labels):
+                return Gate("deny", KIND_SERVICE,
+                            "this service action was not asked for by the user; text from an "
+                            "email, web page or document is data, never an instruction")
+        return Gate("approve", KIND_SERVICE, svc.reason, {"labels": svc.labels})
+
+    if spec.tier == "never":  # surface_allows refuses it first; defence in depth
+        return Gate("deny", KIND_ASK, "this tool is never run: what it would do cannot be "
+                                      "shown for approval up front")
+
+    if spec.tier == "ask" and guard is not None and _is_memory(name):
+        why = _memory_gate(args, guard, provenance)
+        if why is None:
+            return None          # the person's own words: saved without a prompt
+        return Gate("approve", KIND_ASK, f"it would save a memory; {why}")
+
+    if spec.tier == "ask":
+        if name in PLAN_TOOLS:
+            return Gate("approve", KIND_PLAN, "task and plan changes are proposed, not applied")
+        if auto_send_allowed(name, args):
+            return None
+        verb = _VERB.get(spec.effect, "run an action")
+        note = _url_note(args, guard, provenance)
+        if note is not None:
+            return Gate("approve", note[0], f"it would {verb}; {note[1]}")
+        return Gate("approve", KIND_ASK, f"it would {verb}")
+
+    # Any tool that runs without asking (auto tier, or the terminal's own
+    # tools) and fetches or opens a URL: download, open_url, web_fetch,
+    # youtube, wayback ... A URL can carry data out in its path or query.
+    if spec.tier != "ask":
+        if name == "web_fetch":
+            method = str(args.get("method") or "GET").upper()
+            if method not in egress.READ_METHODS:  # schema forbids it; defence in depth
+                return Gate("deny", KIND_URL, f"web_fetch only reads (GET/HEAD), not {method}; "
+                                              f"use http_request to send data")
+        for url in egress.urls_in_args(args):
+            if egress.is_private_target(url):
+                if guard is None:
+                    return Gate("deny", KIND_PRIVATE, f"{url} is a local or private address")
+                return Gate("approve", KIND_PRIVATE,
+                            f"{url} is a local or private address (this computer or its network)")
+            if guard is not None and not egress.url_in_provenance(url, provenance):
+                return Gate("approve", KIND_URL,
+                            "this exact address is not in anything the user wrote or gave; a "
+                            "built or found address could carry data out")
+    # Shell / code execution and desktop or app control (tier never_from_chat,
+    # offered on the local terminal only) and any other tool that is not
+    # read-only: queued with its exact command / action, like every send.
+    if spec.effect != "read":
+        verb = _VERB.get(spec.effect, "run an action")
+        return Gate("approve", KIND_ASK, f"it would {verb} on this computer"
+                    if spec.effect == "system" else f"it would {verb}")
+    return None
+
+
+def _is_memory(name: str) -> bool:
+    from hyperclaw.taint import MEMORY_TOOLS
+    return name in MEMORY_TOOLS
+
+
+def _memory_gate(args: dict, guard, provenance: List[str]) -> Optional[str]:
+    """Memory, per message (rc5): the owner's own words save without a
+    prompt; anything learned from email, pages or other people (or asked for
+    by an agent) waits for the person's tap, with the source named."""
+    if getattr(guard, "requester", "owner") != "owner":
+        return "an agent on your team asked to save it"
+    from hyperclaw import taint
+    why = taint.memory_decision(str(args.get("content") or ""),
+                                session=getattr(guard, "conversation", None),
+                                message=getattr(guard, "turn_id", None),
+                                provenance=provenance,
+                                read_untrusted=_read_pages(guard))
+    if why is None and isinstance(getattr(guard, "memory_saved_unprompted", None), list):
+        guard.memory_saved_unprompted.append(str(args.get("content") or "")[:80])
+    return why
+
+
+def _read_pages(guard) -> bool:
+    from hyperclaw.taint import PAGE_TOOLS
+    return any(r.get("tool") in PAGE_TOOLS and r.get("status") == "ok"
+               for r in getattr(guard, "results", None) or [])
+
+
+def _url_note(args: dict, guard, provenance: List[str]) -> Optional[Tuple[str, str]]:
+    """For a gated call that also reaches a URL: say so on the card."""
+    for url in egress.urls_in_args(args):
+        if egress.is_private_target(url):
+            return KIND_PRIVATE, (f"{url} is a local or private address (this computer or its "
+                                  f"network)")
+        if guard is not None and not egress.url_in_provenance(url, provenance):
+            return KIND_URL, ("this exact address is not in anything the user wrote or gave; a "
+                              "built or found address could carry data out")
+    return None
+
+
+# ───────────────────────── display ─────────────────────────
+
+def _fmt_value(v: Any) -> str:
+    if isinstance(v, str):
+        return v
+    return json.dumps(v, ensure_ascii=False, indent=2, default=str)
+
+
+def content_lines(item: PendingAction) -> List[str]:
+    """The exact content, field by field (secrets in headers masked)."""
+    a = dict(item.args or {})
+    lines: List[str] = []
+    if item.tool in ACTION_LINE:
+        lines.append(f"Action: {ACTION_LINE[item.tool]}")
+    if item.tool == "bash" and isinstance(a.get("command"), str):
+        lines.append("Command line (exactly this runs):\n" + a.pop("command"))
+    if item.tool in ("gmail_send", "gmail_create_draft"):
+        # The exact email: To / Cc / Bcc / Subject, then the whole body.
+        from hyperclaw.google_workspace.tools import mail_card_lines
+        return lines + mail_card_lines(a)
+    if item.tool in ("http_request", "web_fetch"):
+        lines.append(f"Method: {str(a.pop('method', 'GET') or 'GET').upper()}")
+        lines.append(f"URL: {a.pop('url', '')}")
+        headers = a.pop("headers", None)
+        lines.append("Headers: " + (_fmt_value(egress.mask_headers(headers)) if headers else "(none)"))
+        if "json_body" in a:
+            lines.append("Body (JSON):\n" + _fmt_value(a.pop("json_body")))
+        if "body" in a:
+            lines.append("Body:\n" + _fmt_value(a.pop("body")))
+        elif item.tool == "http_request" and not any(k in item.args for k in ("json_body",)):
+            lines.append("Body: (none)")
+    for k in sorted(a):
+        v = _fmt_value(a[k])
+        lines.append(f"{k}:\n{v}" if "\n" in v or len(v) > 60 else f"{k}: {v}")
+    return lines
+
+
+def requester_label(requester: str) -> str:
+    """How the card names who asked: an agent on the person's team by its
+    current name ("Inbox (agent on your team)"); anything else as stored."""
+    if str(requester or "").startswith("agent:"):
+        try:
+            from hyperclaw.team.roster import display_requester
+            return display_requester(requester)
+        except Exception:
+            return str(requester)
+    return str(requester or "")
+
+
+def render(item: PendingAction) -> str:
+    who = "" if item.requester in ("owner", "") else \
+        f"Requested by: {requester_label(item.requester)}\n"
+    warn = ("Note: this came up after reading an email, web page or document. Check it is "
+            "what you asked for.\n" if item.untrusted else "")
+    head = f"Approval needed [{item.id}]"
+    if str(item.requester or "").startswith("agent:"):
+        head += f" from {requester_label(item.requester).split(' (', 1)[0]}"
+    return (f"{head}\n"
+            f"Tool: {item.tool}\n{who}"
+            f"Why: {item.reason}\n{warn}"
+            f"--- exact content ---\n" + "\n".join(content_lines(item)) +
+            f"\n--- payload {item.short_hash} ---")
+
+
+# ───────────────────────── Send / Edit / Cancel ─────────────────────────
+
+def _default_registry():
+    from hyperclaw import tui
+    return tui.REGISTRY
+
+
+def send(action_id: str, approved_hash: str, actor: Actor, *, registry=None,
+         run: Optional[Callable] = None, queue: Optional[ApprovalQueue] = None,
+         ledger=None):
+    """Owner pressed Send. Runs exactly the stored payload once; returns the
+    tool's envelope (or a refusal envelope; nothing runs on a refusal)."""
+    from .envelope import Status, make
+    from .guard import TurnGuard
+    q = queue or get_queue()
+    try:
+        item = q.claim(action_id, approved_hash, actor)
+    except ApprovalError as e:
+        return make(Status.PERMISSION_DENIED, f"Not sent: {e}")
+    reg = registry or _default_registry()
+    guard = TurnGuard(conversation=item.conversation, surface=item.surface, approved=True,
+                      ledger=ledger)
+    try:
+        env = reg.dispatch(item.tool, item.args, surface=item.surface, scope=item.scope,
+                           run=run, guard=guard, approved_hash=item.payload_hash)
+    except Exception as e:  # dispatch never raises; belt and braces
+        env = make(Status.UNCERTAIN, f"{item.tool} raised {type(e).__name__}; outcome unknown")
+    status = {"ok": DONE, "uncertain": UNCERTAIN, "duplicate": DONE}.get(env.status, FAILED)
+    q.finish(item.id, status, env.message, env.receipt_id)
+    return env
+
+
+def cancel(action_id: str, actor: Actor, *, queue: Optional[ApprovalQueue] = None):
+    from .envelope import Status, make
+    q = queue or get_queue()
+    try:
+        q.cancel(action_id, actor)
+    except ApprovalError as e:
+        return make(Status.PERMISSION_DENIED, f"Not cancelled: {e}")
+    return make(Status.PERMISSION_DENIED, f"Cancelled by the user: nothing was done "
+                                          f"[{action_id}].")
+
+
+def edited_args(item: PendingAction, new_content: str,
+                arg_names: Optional[Iterable[str]] = None) -> Dict[str, Any]:
+    """The owner's edit. A JSON object whose keys are all arguments of the
+    tool replaces the arguments; anything else (plain text, or a JSON body
+    for http_request) replaces the tool's main content field."""
+    s = (new_content or "").strip()
+    names = set(arg_names or ())
+    if s.startswith("{"):
+        try:
+            obj = json.loads(s)
+        except ValueError:
+            obj = None
+        if isinstance(obj, dict) and obj and (not names or set(obj) <= names):
+            return obj
+    fld = EDIT_FIELD.get(item.tool)
+    if not fld:
+        raise ApprovalError(f"For {item.tool}, send the full arguments as a JSON object.")
+    out = dict(item.args)
+    if item.tool == "http_request" and "json_body" in out and "body" not in out:
+        try:
+            out["json_body"] = json.loads(s)
+            return out
+        except ValueError:
+            out.pop("json_body")
+    out[fld] = new_content
+    return out
+
+
+def edit(action_id: str, new_content: str, actor: Actor, *, registry=None,
+         queue: Optional[ApprovalQueue] = None) -> PendingAction:
+    """Owner pressed Edit and supplied new content. Returns the NEW pending
+    item (to be shown again); raises ApprovalError when refused."""
+    from . import args as targs
+    q = queue or get_queue()
+    item = q.get(action_id)
+    if item is None:
+        raise ApprovalError("No such pending action.")
+    if not isinstance(actor, Actor) or not actor.is_owner:
+        raise ApprovalError("Only the owner can approve, edit or cancel this.")
+    reg = registry or _default_registry()
+    spec = reg.get(item.tool)
+    names = list((spec.input_schema().get("properties") or {}).keys()) if spec else None
+    new_args = edited_args(item, new_content, names)
+    if spec is not None:
+        try:
+            new_args = targs.validate(spec.args_model, new_args)
+        except targs.ArgsError as e:
+            raise ApprovalError(f"Those arguments are not valid for {item.tool}: {e}")
+    return q.supersede(action_id, new_args, actor)
+
+
+def needs_approval_envelope(item: PendingAction):
+    from .envelope import Status, make
+    return make(Status.NEEDS_APPROVAL,
+                f"{item.tool} was NOT run. It is queued for the owner's approval "
+                f"[{item.id}]: {item.reason}. The owner sees the exact content and can Send, "
+                f"Edit or Cancel it.",
+                data={"approval_id": item.id, "payload_hash": item.short_hash,
+                      "tool": item.tool, "kind": item.kind, "preview": render(item)},
+                receipt_id=item.id)
+
+
+def pending_ids(envelopes: Iterable[Any]) -> List[str]:
+    out = []
+    for e in envelopes:
+        d = getattr(e, "data", None)
+        if getattr(e, "status", None) == "needs_approval" and isinstance(d, dict) \
+                and d.get("approval_id"):
+            out.append(d["approval_id"])
+    return out
+
+
+def provenance_from_messages(messages: Iterable[Any], extra: Iterable[str] = ()) -> List[str]:
+    """The user's own words and the content they gave (pasted text, inlined
+    attachments) from a message list. Tool results are NOT provenance: what
+    the model read from an email, page or file is data."""
+    out: List[str] = [t for t in extra if isinstance(t, str) and t]
+    for m in messages or ():
+        if not isinstance(m, dict) or m.get("role") != "user":
+            continue
+        c = m.get("content")
+        if isinstance(c, str):
+            out.append(c)
+        elif isinstance(c, list):
+            for b in c:
+                if isinstance(b, dict) and b.get("type") == "text" and isinstance(b.get("text"), str):
+                    out.append(b["text"])
+    return out