keywright-server 0.0.1__py3-none-any.whl

keywright_server/mcp_server.py

@@ -0,0 +1,1025 @@
+"""The agent-facing MCP server. Every agent sees access_*; gated tools appear as access allows."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import logging
+import time
+from typing import Any
+
+import mcp_types as types
+from keywright import hazards
+from keywright.classify import classify, classify_mcp
+from keywright.patterns import PATTERN_HELP, validate
+from mcp.server.lowlevel import Server
+from sqlalchemy import String, cast, func, select
+from sqlalchemy.exc import IntegrityError
+
+from . import (
+    __version__,
+    approvals,
+    audit,
+    bundles,
+    inventory,
+    inventory_mcp,
+    knowledge,
+    knowledge_mcp,
+    mcp_proxy,
+    nudges,
+    policy,
+    result_inspection,
+    semantic,
+    ssh,
+)
+from .db import session
+from .models import Agent, AuditEvent, Resource, now
+
+log = logging.getLogger("keywright.mcp")
+DEFAULT_WAIT = 90
+MAX_WAIT = 600
+MAX_OPERATIONS = 20
+
+_agent_cache: dict[str, tuple[float, str]] = {}  # token_hash -> (ts, agent_id)
+
+
+def hash_token(token: str) -> str:
+    return hashlib.sha256(token.encode()).hexdigest()
+
+
+async def resolve_agent(db, headers) -> Agent | None:
+    if not headers:
+        return None
+    auth = headers.get("authorization") or headers.get("Authorization") or ""
+    if not auth.lower().startswith("bearer "):
+        return None
+    token = auth[7:].strip()
+    if not token:
+        return None
+    h = hash_token(token)
+    agent = (await db.execute(select(Agent).where(Agent.token_hash == h))).scalar_one_or_none()
+    if agent is None or agent.disabled:
+        return None
+    agent.last_seen_at = now()
+    await db.commit()
+    return agent
+
+
+def _headers(ctx) -> dict[str, str] | None:
+    req = getattr(ctx, "request", None)
+    if req is not None and hasattr(req, "headers"):
+        return {k.lower(): v for k, v in req.headers.items()}
+    return None
+
+
+def _session_id(ctx, headers: dict[str, str] | None) -> str | None:
+    """Best available session identity.
+
+    Legacy streamable HTTP carries Mcp-Session-Id. The 2026-07-28 single-exchange mode has no
+    session at all, so clients that want per-process scoping can send X-Keywright-Session (the
+    pre-rename X-Gatekeeper-Session is still accepted for one release). With
+    neither there is no session, and "this session" approvals are not offered for the request.
+    """
+    if headers:
+        for h in ("mcp-session-id", "x-keywright-session", "x-gatekeeper-session"):
+            if headers.get(h):
+                return headers[h][:128]
+    return getattr(ctx, "session_id", None)
+
+
+# ---- tool definitions ---------------------------------------------------------------------------
+ACCESS_TOOLS = [
+    types.Tool(
+        name="access_list_resources",
+        description="List every resource Keywright brokers (SSH hosts, MCP servers) and your current standing on "
+                    "each: open, approval-required, locked, plus active grants and standing rules.",
+        input_schema={"type": "object", "properties": {}},
+        annotations=types.ToolAnnotations(read_only_hint=True),
+    ),
+    types.Tool(
+        name="access_request",
+        description="Ask the human for access before you need it, e.g. every read-only tool of a server in one "
+                    "request: patterns=[\"mcp/ha/tools/ha_get_*\", \"mcp/ha/tools/ha_search\"], or a named "
+                    "bundle the resource owner defined: \"mcp/ha/bundle/read-only\" (names and contents are in "
+                    "`bundles` from access_list_resources; the human sees the request grouped the same way). Blocks up to "
+                    "wait_seconds for a decision and returns approved | denied | pending. Gated tools also request "
+                    "automatically when called, so this is optional. " + PATTERN_HELP + " MCP calls are qualified by "
+                    "the argument keys each resource lists in access_list_resources, so a request or rule can name "
+                    "mcp/ha/tools/call_service/service=light.turn_on. Approval scopes: once (one use per listed scope), session "
+                    "(this MCP session id, or the X-Keywright-Session header you send; not offered when you have "
+                    "neither), ttl (15 minutes, 30 minutes, or 1 hour), always (admin UI only). "
+                    "Automatic approvals default to the exact command/tool arguments for every duration; "
+                    "the admin can explicitly choose broader patterns. Explicit access_request asks for patterns, "
+                    "or, with `operations`, for several exact SSH steps at once.",
+        input_schema={
+            "type": "object",
+            "properties": {
+                "patterns": {"type": "array", "items": {"type": "string"}, "minItems": 1,
+                             "description": "Permission paths, e.g. ssh/nvr/exec/journalctl, "
+                                            "mcp/ha/tools/ha_get_*, mcp/ha/tools/call_service/entity_id=light.*"},
+                "operations": {
+                    "type": "array", "minItems": 1, "maxItems": MAX_OPERATIONS,
+                    "description": "Instead of patterns: the exact SSH operations you are about to run, all in one "
+                                   "prompt. Each is {host, command} for ssh_run, {host, put, content, mode?} for "
+                                   "ssh_put (put = remote path), {host, get} for ssh_get, or {host, command, "
+                                   "to_host, to_path, append?} for ssh_capture; `user` is optional. "
+                                   "Approval binds each one exactly (same command line, same file contents), so "
+                                   "call the tools afterwards with identical arguments. Use this when you know "
+                                   "your next steps: one prompt instead of one per step, without a wide pattern.",
+                    "items": {"type": "object", "properties": {
+                        "host": {"type": "string"}, "command": {"type": "string"}, "put": {"type": "string"},
+                        "content": {"type": "string"}, "mode": {"type": "string"}, "get": {"type": "string"},
+                        "to_host": {"type": "string"}, "to_path": {"type": "string"}, "append": {"type": "boolean"},
+                        "to_user": {"type": "string"}, "user": {"type": "string"}}, "required": ["host"]},
+                },
+                "reason": {"type": "string", "description": "Shown to the human. Be specific."},
+                "wait_seconds": {"type": "integer", "default": DEFAULT_WAIT, "minimum": 0, "maximum": MAX_WAIT},
+            },
+            "required": ["reason"],
+        },
+    ),
+    types.Tool(
+        name="request_attention",
+        description="Ask the human to come back to this conversation: you have a question only they can "
+                    "answer, a choice to put to them, or you are done and want them to look. Reaches the "
+                    "same phone as approval prompts and stays on the Keywright dashboard until they clear "
+                    "it. It does NOT bring back an answer and does not wait: say what you need here, then "
+                    "ask it in the conversation and stop. Use it when you would otherwise sit idle while "
+                    "they are away from the keyboard. Do not use it for progress updates, and do not use "
+                    "it to chase a pending approval - that request is already on their phone. One ping per "
+                    "thing you need: repeats of the same message are folded into the one already waiting, "
+                    "and a second different ping inside a minute is refused.",
+        input_schema={
+            "type": "object",
+            "properties": {
+                "message": {"type": "string", "maxLength": nudges.MAX_MESSAGE,
+                            "description": "What you need from them, in a sentence or two, specific enough "
+                                           "to answer without re-reading the whole conversation."},
+                "context": {"type": "string", "maxLength": nudges.MAX_CONTEXT,
+                            "description": "Where the conversation is, e.g. host:/path or a project name. "
+                                           "The kw CLI fills this in; send it yourself if you know it."},
+            },
+            "required": ["message"],
+        },
+    ),
+    types.Tool(
+        name="access_status",
+        description="Check a pending access request by id (optionally wait up to wait_seconds).",
+        input_schema={
+            "type": "object",
+            "properties": {"request_id": {"type": "string"},
+                           "wait_seconds": {"type": "integer", "default": 0, "minimum": 0, "maximum": MAX_WAIT}},
+            "required": ["request_id"],
+        },
+        annotations=types.ToolAnnotations(read_only_hint=True),
+    ),
+]
+
+SSH_TOOL = types.Tool(
+    name="ssh_run",
+    description="Run one shell command on a brokered host (see access_list_resources for names). Fresh session "
+                "per call, no state carries over, output capped at 1 MiB. If the command needs approval, "
+                "Keywright asks the human and waits up to wait_seconds; give a clear `reason`.",
+    input_schema={
+        "type": "object",
+        "properties": {
+            "host": {"type": "string", "description": "Resource name, e.g. nvr"},
+            "command": {"type": "string"},
+            "reason": {"type": "string", "description": "Why you need this. Shown to the human if approval is needed."},
+            "timeout": {"type": "integer", "default": 300, "minimum": 1, "maximum": ssh.MAX_TIMEOUT},
+            "user": {"type": "string", "description": "Override remote user (subject to policy)."},
+            "wait_seconds": {"type": "integer", "default": DEFAULT_WAIT, "minimum": 0, "maximum": MAX_WAIT},
+        },
+        "required": ["host", "command"],
+    },
+)
+
+SSH_PUT_TOOL = types.Tool(
+    name="ssh_put",
+    description="Write a file on a brokered host (up to 1 MiB, text). Classified as ssh/<host>/put/<path>, so "
+                "a rule can allow a directory: ssh/nvr/put/etc/komodo/stacks/**. The human sees the path, size "
+                "and sha256, not the contents, and an exact approval covers exactly these contents at this "
+                "path. Written atomically (temp file, mode, rename); parent directories are created.",
+    input_schema={
+        "type": "object",
+        "properties": {
+            "host": {"type": "string", "description": "Resource name, e.g. nvr"},
+            "path": {"type": "string", "description": "Absolute remote path"},
+            "content": {"type": "string"},
+            "mode": {"type": "string", "default": "0644", "description": "Octal file mode, e.g. 0600"},
+            "reason": {"type": "string", "description": "Why you need this. Shown to the human if approval is needed."},
+            "user": {"type": "string", "description": "Override remote user (subject to policy)."},
+            "wait_seconds": {"type": "integer", "default": DEFAULT_WAIT, "minimum": 0, "maximum": MAX_WAIT},
+        },
+        "required": ["host", "path", "content"],
+    },
+)
+
+SSH_GET_TOOL = types.Tool(
+    name="ssh_get",
+    description="Read a file from a brokered host (capped at 1 MiB). Classified as ssh/<host>/get/<path>, so a "
+                "rule can allow a directory: ssh/nvr/get/etc/komodo/**.",
+    input_schema={
+        "type": "object",
+        "properties": {
+            "host": {"type": "string", "description": "Resource name, e.g. nvr"},
+            "path": {"type": "string", "description": "Absolute remote path"},
+            "reason": {"type": "string", "description": "Why you need this. Shown to the human if approval is needed."},
+            "user": {"type": "string", "description": "Override remote user (subject to policy)."},
+            "wait_seconds": {"type": "integer", "default": DEFAULT_WAIT, "minimum": 0, "maximum": MAX_WAIT},
+        },
+        "required": ["host", "path"],
+    },
+    annotations=types.ToolAnnotations(read_only_hint=True),
+)
+
+SSH_CAPTURE_TOOL = types.Tool(
+    name="ssh_capture",
+    description="Run a command on one host and deliver its stdout to a file on another (or the same) host "
+                "without returning it to you: for secrets, tokens and key material that must move between "
+                "machines but never through your context. Classified as the command on the source host plus "
+                "ssh/<to_host>/put/<to_path>; the human sees both halves in one prompt. You receive exit "
+                "codes, byte count and sha256 only; the audit log stores the same. Nothing is written unless "
+                "the command exits 0. Shape the output on the source side (print KEY=value) and set "
+                "append=true to add it to an env file; otherwise the file is replaced (mode 0600 by default).",
+    input_schema={
+        "type": "object",
+        "properties": {
+            "host": {"type": "string", "description": "Source resource name"},
+            "command": {"type": "string", "description": "Runs on the source host; its stdout is the payload"},
+            "to_host": {"type": "string", "description": "Destination resource name"},
+            "to_path": {"type": "string", "description": "Absolute path on the destination host"},
+            "append": {"type": "boolean", "default": False},
+            "mode": {"type": "string", "default": "0600", "description": "Octal mode when replacing the file"},
+            "reason": {"type": "string", "description": "Why you need this. Shown to the human if approval is needed."},
+            "user": {"type": "string", "description": "Override the source remote user (subject to policy)."},
+            "to_user": {"type": "string", "description": "Override the destination remote user (subject to policy)."},
+            "timeout": {"type": "integer", "default": 300, "minimum": 1, "maximum": ssh.MAX_TIMEOUT},
+            "wait_seconds": {"type": "integer", "default": DEFAULT_WAIT, "minimum": 0, "maximum": MAX_WAIT},
+        },
+        "required": ["host", "command", "to_host", "to_path"],
+    },
+)
+
+
+REFUSED_HINT = ("Keywright refuses this outright: it would destroy the host, a home directory or key material. "
+                "No approval can allow it. If the user really wants it, they run it by hand. Do not reword it.")
+FLAGGED_HINT = ("This operation is flagged as destructive: standing rules and timed grants do not cover it, "
+                "and the human can only allow this exact command line once. Do not reword it to avoid the flag.")
+
+
+def _handle(v: policy.Verdict, event) -> dict[str, Any]:
+    """What an agent can cite for one allowed call: the audit row, what allowed each path, and
+    the approval requests behind the grants or standing rules used."""
+    out = {"audit_id": event.id, "matched": dict(v.matched), "bound": dict(v.bound),
+           "consumed_grants": list(v.consumed_grants), "request_ids": sorted(v.request_ids)}
+    if v.hazard:
+        out["hazard"] = v.hazard
+    return out
+
+
+def _handle_text(handle: dict[str, Any]) -> str:
+    parts = [f"audit #{handle['audit_id']}"]
+    # A `**` match on an exact-command grant is that one command, not the host; say so.
+    parts += [f"{p} <- {src}" + (f" ({handle['bound'][p]})" if p in handle.get("bound", {}) else "")
+              for p, src in handle["matched"].items()]
+    if handle["request_ids"]:
+        parts.append("requests " + ", ".join(handle["request_ids"]))
+    if handle.get("hazard"):
+        parts.append(f"flagged {handle['hazard']}")
+    return "[keywright] " + " | ".join(parts)
+
+
+def _result(payload: dict[str, Any], *, text: str | None = None, is_error: bool = False) -> types.CallToolResult:
+    return types.CallToolResult(
+        content=[types.TextContent(type="text", text=text if text is not None else json.dumps(payload, indent=1))],
+        structured_content=payload,
+        is_error=is_error,
+    )
+
+
+def _error(kind: str, **extra: Any) -> types.CallToolResult:
+    return _result({"error": kind, **extra}, is_error=True)
+
+
+# ---- handlers -----------------------------------------------------------------------------------
+async def on_list_tools(ctx, params) -> types.ListToolsResult:
+    headers = _headers(ctx)
+    async with session() as db:
+        agent = await resolve_agent(db, headers)
+        if agent is None:
+            return types.ListToolsResult(tools=[])
+        sid = _session_id(ctx, headers)
+        tools = list(ACCESS_TOOLS)
+        resources = (await db.execute(select(Resource))).scalars().all()
+        if any(r.kind == "ssh" for r in resources):
+            tools += [SSH_TOOL, SSH_PUT_TOOL, SSH_GET_TOOL, SSH_CAPTURE_TOOL]
+        for r in resources:
+            if r.kind != "mcp":
+                continue
+            try:
+                upstream = await mcp_proxy.list_tools(r.name, r.config)
+            except Exception as e:  # noqa: BLE001
+                log.warning("upstream %s tools/list failed: %s", r.name, e)
+                continue
+            for t in upstream:
+                v = await policy.evaluate(db, agent, sid, [f"mcp/{r.name}/tools/{t.name}"],
+                                          consume=False, discovery=True)
+                if v.status in ("deny", "locked"):
+                    continue
+                tools.append(t.model_copy(update={
+                    "name": mcp_proxy.export_name(r.name, t.name),
+                    "description": f"[{r.name}] {t.description or ''}".strip(),
+                }))
+    return types.ListToolsResult(tools=tools)
+
+
+async def on_call_tool(ctx, params: types.CallToolRequestParams) -> types.CallToolResult:
+    headers = _headers(ctx)
+    args = params.arguments or {}
+    ua = (headers or {}).get("user-agent") or ""
+    audit.client_agent.set(ua[:64] if ua.startswith("keywright/") else None)
+    async with session() as db:
+        agent = await resolve_agent(db, headers)
+        if agent is None:
+            return _error("unauthorized", hint="Missing or unknown bearer token.")
+        sid = _session_id(ctx, headers)
+        name = params.name
+        try:
+            if name == "access_list_resources":
+                out = {"agent": agent.name, "session": sid,
+                       "resources": await policy.effective_access(db, agent, sid)}
+                if sid is None:
+                    out["session_note"] = approvals.NO_SESSION_NOTE
+                return _result(out)
+            if name == "access_request":
+                return await _access_request(db, agent, sid, args)
+            if name == "access_status":
+                return await _access_status(db, agent, args)
+            if name == "request_attention":
+                return await _request_attention(db, agent, sid, args)
+            if name == "ssh_run":
+                return await _ssh_run(db, agent, sid, args)
+            if name == "ssh_put":
+                return await _ssh_put(db, agent, sid, args)
+            if name == "ssh_get":
+                return await _ssh_get(db, agent, sid, args)
+            if name == "ssh_capture":
+                return await _ssh_capture(db, agent, sid, args)
+            split = mcp_proxy.split_name(name)
+            if split:
+                return await _proxy_call(db, agent, sid, split[0], split[1], args)
+        except Exception as e:
+            log.exception("tool %s failed", name)
+            await audit.record(db, tool=name, decision="error", agent=agent, session_id=sid,
+                               detail={"error": f"{type(e).__name__}: {e}"})
+            return _error("internal", message="Tool failed; see the admin audit log.")
+        return _error("unknown_tool", name=name)
+
+
+async def _access_request(db, agent: Agent, sid: str | None, args: dict[str, Any]) -> types.CallToolResult:
+    if args.get("operations") is not None:
+        if args.get("patterns"):
+            return _error("invalid_arguments", hint="Give either patterns or operations, not both.")
+        return await _access_request_operations(db, agent, sid, args)
+    try:
+        raw_patterns = args.get("patterns")
+        if not isinstance(raw_patterns, list) or not 1 <= len(raw_patterns) <= 64:
+            raise ValueError("Provide between 1 and 64 patterns")
+        pats = [validate(p) for p in raw_patterns]
+        if any(len(p) > 512 or len(p.split("/")) < 3 or "*" in "/".join(p.split("/")[:2]) for p in pats):
+            raise ValueError("Each pattern must identify one concrete resource")
+    except (ValueError, TypeError, AttributeError) as e:
+        return _error("invalid_pattern", message=str(e), hint=PATTERN_HELP)
+    pats, groups, err = await _expand_bundles(db, pats)
+    if err:
+        return err
+    reason = (args.get("reason") or "").strip()
+    wait_s = min(int(args.get("wait_seconds", DEFAULT_WAIT) or 0), MAX_WAIT)
+    v = await policy.evaluate(db, agent, sid, pats, consume=False)
+    if v.status == "allow":
+        return _result({"status": "approved", "note": "already allowed", "matched": v.matched})
+    if v.status == "deny":
+        return _error("denied", patterns=v.denied, hint="A standing deny rule covers this.")
+    if v.status == "locked":
+        return _error("locked", patterns=v.locked, hint="Cannot be granted from a prompt; needs a rule in the UI.")
+    if v.status == "unknown":
+        return _error("unknown_resource", patterns=v.unknown, hint="Call access_list_resources.")
+    missing = set(v.missing)
+    shown = {name: [p for p in ps if p in missing] for name, ps in groups.items()}
+    detail = {"bundles": {n: ps for n, ps in shown.items() if ps}} if any(shown.values()) else {}
+    req, _ = await _request_or_reuse(db, agent, sid, v.missing, reason, detail)
+    if req is None:
+        return _error("denied", retry_after=600, hint="Recently denied; ask the user before retrying.")
+    if wait_s:
+        await approvals.wait(req.id, wait_s)
+        await db.refresh(req)
+    return await _status_payload(db, req)
+
+
+ATTENTION_NEXT = ("The human has been pinged. Ask your question in the conversation now and stop; "
+                  "their answer comes back there, not here. Do not call this again for the same thing.")
+
+
+async def _request_attention(db, agent: Agent, sid: str | None, args: dict[str, Any]) -> types.CallToolResult:
+    """A ping, not a request: it authorizes nothing, so it is not evaluated against policy. The
+    limit that matters is the human's attention, and nudges.create owns that."""
+    try:
+        ping = await nudges.create(db, agent, sid, str(args.get("message") or ""),
+                                   str(args.get("context") or ""))
+    except ValueError as e:
+        return _error("invalid_arguments", message=str(e))
+    if ping.status == "throttled":
+        await audit.record(db, tool="attention", decision="throttled", agent=agent, session_id=sid,
+                           detail={"retry_after": ping.retry_after})
+        return _error("rate_limited", retry_after=ping.retry_after,
+                      hint="You pinged them moments ago. Ask in the conversation and wait instead.")
+    if ping.status == "backlog":
+        await audit.record(db, tool="attention", decision="throttled", agent=agent, session_id=sid,
+                           detail={"open": nudges.MAX_OPEN})
+        return _error("rate_limited", open_nudges=nudges.MAX_OPEN,
+                      hint=f"You already have {nudges.MAX_OPEN} unanswered pings waiting for them. "
+                           "Wait for those before asking for more of their attention.")
+    return _result({"status": ping.status, "nudge_id": ping.nudge.id,
+                    "notified": await _notified(db, ping.nudge.id, "nudge_id"),
+                    "note": ATTENTION_NEXT if ping.status == "sent"
+                    else "That exact message is already waiting on their phone; nothing new was sent. "
+                         + ATTENTION_NEXT})
+
+
+async def _access_request_operations(db, agent: Agent, sid: str | None, args: dict[str, Any]) -> types.CallToolResult:
+    """Several exact operations in one prompt. Each gets its own patterns and its own exact grant;
+    the human sees every command line, and later calls must repeat them verbatim to match."""
+    ops = args.get("operations")
+    if not isinstance(ops, list) or not 1 <= len(ops) <= MAX_OPERATIONS:
+        return _error("invalid_arguments", hint=f"operations must be a list of 1 to {MAX_OPERATIONS} items")
+    pending: list[dict[str, Any]] = []
+    allowed: dict[str, str] = {}
+    for i, op in enumerate(ops):
+        if not isinstance(op, dict) or not isinstance(op.get("host"), str):
+            return _error("invalid_arguments", index=i, hint="each operation is an object with a host")
+        res, user = await _ssh_target(db, op["host"], op.get("user"))
+        if res is None:
+            return _error("unknown_resource", index=i, host=op["host"], hint="Call access_list_resources for valid host names.")
+        try:
+            if isinstance(op.get("command"), str) and op["command"].strip() and isinstance(op.get("to_host"), str):
+                dst, to_user = await _ssh_target(db, op["to_host"], op.get("to_user"))
+                if dst is None:
+                    return _error("unknown_resource", index=i, host=op["to_host"], hint="Call access_list_resources.")
+                if not isinstance(op.get("to_path"), str):
+                    raise ValueError("a capture needs to_host and to_path")
+                required, detail = _capture_operation(res, op["command"].strip(), user, dst, op["to_path"], to_user,
+                                                      bool(op.get("append")))
+            elif isinstance(op.get("command"), str) and op["command"].strip():
+                required, detail = _run_operation(res, op["command"].strip(), user)
+            elif isinstance(op.get("put"), str):
+                if not isinstance(op.get("content"), str):
+                    raise ValueError("a put needs content")
+                required, detail, _ = _put_operation(res, op["put"], op["content"], user)
+            elif isinstance(op.get("get"), str):
+                required, detail = _get_operation(res, op["get"], user)
+            else:
+                raise ValueError("each operation needs a command, a put with content, or a get")
+        except ValueError as e:
+            return _error("invalid_arguments", index=i, hint=str(e))
+        if hazards.worst(detail.get("hazards")) == "critical":
+            await audit.record(db, tool="access_request", decision="refused", agent=agent, session_id=sid,
+                               patterns=required, detail=detail)
+            return _error("refused", index=i, hazards=detail["hazards"], hint=REFUSED_HINT)
+        v = await policy.evaluate(db, agent, sid, required, consume=False, operation=detail)
+        if v.status == "deny":
+            return _error("denied", index=i, patterns=v.denied, hint="A standing deny rule covers this.")
+        if v.status == "locked":
+            return _error("locked", index=i, patterns=v.locked, hint="Cannot be granted from a prompt; needs a rule in the UI.")
+        if v.status == "allow":
+            allowed.update(v.matched)
+            continue
+        pending.append({"patterns": v.missing, "operation": detail})
+    if not pending:
+        return _result({"status": "approved", "note": "already allowed", "matched": allowed})
+    patterns: list[str] = []
+    for item in pending:
+        patterns += [p for p in item["patterns"] if p not in patterns]
+    reason = (args.get("reason") or "").strip()
+    wait_s = min(int(args.get("wait_seconds", DEFAULT_WAIT) or 0), MAX_WAIT)
+    req, _ = await _request_or_reuse(db, agent, sid, patterns, reason, {"operations": pending})
+    if req is None:
+        return _error("denied", retry_after=600, hint="Recently denied; ask the user before retrying.")
+    if wait_s:
+        await approvals.wait(req.id, wait_s)
+        await db.refresh(req)
+    return await _status_payload(db, req)
+
+
+async def _expand_bundles(db, pats: list[str]) -> tuple[list[str], dict[str, list[str]], types.CallToolResult | None]:
+    """Replace mcp/<server>/bundle/<name> entries with the bundle's patterns. Returns (patterns,
+    {bundle name: its patterns}, error)."""
+    out: list[str] = []
+    groups: dict[str, list[str]] = {}
+    for p in pats:
+        parts = p.split("/")
+        if not (parts[0] == "mcp" and len(parts) == 4 and parts[2] == "bundle"):
+            if p not in out:
+                out.append(p)
+            continue
+        server, name = parts[1], parts[3]
+        res = (await db.execute(select(Resource).where(Resource.kind == "mcp", Resource.name == server))).scalar_one_or_none()
+        expanded = bundles.expand(server, (res.config or {}).get("bundles") if res else None, name)
+        if expanded is None:
+            return [], {}, _error("unknown_bundle", pattern=p,
+                                  available=sorted(((res.config or {}).get("bundles") or {}).keys()) if res else [],
+                                  hint="Bundles are defined per resource; see `bundles` in access_list_resources.")
+        groups[f"{server}/{name}"] = expanded
+        out.extend(x for x in expanded if x not in out)
+    return out, groups, None
+
+
+async def _access_status(db, agent: Agent, args: dict[str, Any]) -> types.CallToolResult:
+    req = await db.get(approvals.AccessRequest, args.get("request_id", ""))
+    if req is None or req.agent_id != agent.id:
+        return _error("not_found")
+    wait_s = min(int(args.get("wait_seconds", 0) or 0), MAX_WAIT)
+    if wait_s and req.status == "pending":
+        await approvals.wait(req.id, wait_s)
+        await db.refresh(req)
+    return await _status_payload(db, req)
+
+
+async def _status_payload(db, req) -> types.CallToolResult:
+    payload = {"request_id": req.id, "status": req.status, "patterns": req.patterns,
+               "scope": req.decision_scope, "decision_options": req.decision_options,
+               "deny_reason": req.deny_reason or None}
+    if "operations" in (req.detail or {}):
+        payload["operations"] = len(req.detail["operations"])
+    else:
+        # Enough to name the operation the approval was for, never its payload or arguments.
+        op = {k: v for k, v in (req.detail or {}).items()
+              if k in ("host", "command", "user", "path", "to_host", "to_path", "server", "tool")}
+        if op:
+            payload["operation"] = op
+    if req.status == "pending":
+        payload["notified"] = await _notified(db, req.id)
+        payload["hint"] = NOTIFIED_HINTS[payload["notified"]]
+    return _result(payload, is_error=req.status in ("denied", "expired"))
+
+
+NOTIFIED_HINTS = {
+    "sent": "The human has the notification and has not answered yet. Poll access_status(request_id, "
+            "wait_seconds) or tell the user what you asked for.",
+    "failed": "The notification could not be delivered. Tell the user to decide it in the admin UI.",
+    "none": "No notifier is configured. Tell the user to decide it in the admin UI.",
+}
+
+
+async def _notified(db, ref_id: str, key: str = "request_id") -> str:
+    """Whether the phone got this request or nudge: a wait that is long because the human is busy
+    looks, from the agent's side, exactly like a notification that never went out."""
+    from .notify.manager import manager
+
+    if not manager.active:
+        return "none"
+    events = (await db.execute(select(AuditEvent).where(
+        AuditEvent.tool == "notify", AuditEvent.decision == "error",
+        cast(AuditEvent.detail, String).contains(ref_id, autoescape=True)))).scalars().all()
+    return "failed" if any((e.detail or {}).get(key) == ref_id for e in events) else "sent"
+
+
+async def _request_or_reuse(db, agent, sid, patterns, reason, detail, required=None):
+    """Returns (request, reused). None when recently denied. A new single-operation request
+    carries Jev's verdict (semantic.py); in trust mode a clean verdict approves it once, exactly,
+    before anyone is notified. `required` is the full pattern list the verdict's guards look at;
+    `patterns` is what is still missing."""
+    if await approvals.recently_denied(db, agent, patterns):
+        return None, False
+    existing = await approvals.find_pending(db, agent, patterns, session_id=sid, detail=detail)
+    if existing:
+        return existing, True
+    count = await db.scalar(select(func.count()).select_from(approvals.AccessRequest).where(
+        approvals.AccessRequest.agent_id == agent.id, approvals.AccessRequest.status == "pending",
+        approvals.AccessRequest.expires_at > now()))
+    if count >= 50:
+        raise ValueError("Too many pending requests; wait for existing decisions")
+    verdict = await semantic.assess(db, required if required is not None else patterns, reason, detail)
+    auto = semantic.auto_approves(verdict)
+    req = await approvals.create(db, agent, sid, patterns, reason, detail, semantic=verdict, notify=not auto)
+    await semantic.record(db, req, agent, sid, verdict)
+    if auto:
+        req = await approvals.decide(db, req.id, "once", via="jev")
+    return req, False
+
+
+async def _gate(db, agent: Agent, sid: str | None, required: list[str], reason: str, detail: dict, wait_s: int,
+                tool: str) -> tuple[policy.Verdict | None, types.CallToolResult | None]:
+    """Shared gate for ssh_run and proxied tools. Returns (verdict, None) when allowed."""
+    level = hazards.worst(detail.get("hazards"))
+    if level == "critical":
+        await audit.record(db, tool=tool, decision="refused", agent=agent, session_id=sid, patterns=required, detail=detail)
+        return None, _error("refused", hazards=detail["hazards"], hint=REFUSED_HINT)
+    v = await policy.evaluate(db, agent, sid, required, operation=detail)
+    if v.allowed:
+        return v, None
+    if v.status == "deny":
+        await audit.record(db, tool=tool, decision="deny", agent=agent, session_id=sid, patterns=required, detail=detail)
+        return None, _error("denied", patterns=v.denied, hint="A standing deny rule covers this.")
+    if v.status == "locked":
+        await audit.record(db, tool=tool, decision="locked", agent=agent, session_id=sid, patterns=required, detail=detail)
+        return None, _error("locked", patterns=v.locked,
+                            hint="This resource can only be opened by a rule in the admin UI. Ask the user.")
+    if v.status == "unknown":
+        return None, _error("unknown_resource", patterns=v.unknown, hint="Call access_list_resources.")
+    req, _ = await _request_or_reuse(db, agent, sid, v.missing, reason, detail, required=required)
+    if req is None:
+        await audit.record(db, tool=tool, decision="deny", agent=agent, session_id=sid, patterns=required,
+                           detail={**detail, "note": "recently denied"})
+        return None, _error("denied", retry_after=600, hint="Recently denied by the human; do not retry blindly.")
+    if wait_s:
+        await approvals.wait(req.id, wait_s)
+        await db.refresh(req)
+    if req.status == "approved":
+        v = await policy.evaluate(db, agent, sid, required, operation=detail)
+        if v.allowed:
+            return v, None
+        return None, _error(v.status, hint="Access changed while awaiting approval; request access again.")
+    await audit.record(db, tool=tool, decision="pending" if req.status == "pending" else req.status, agent=agent,
+                       session_id=sid, patterns=required, detail={**detail, "request_id": req.id})
+    if req.status == "pending":
+        notified = await _notified(db, req.id)
+        extra = {"hazards": detail["hazards"], "hazard": level} if level else {}
+        return None, _error("approval_required", request_id=req.id, patterns=v.missing, notified=notified,
+                            hint=NOTIFIED_HINTS[notified] + (" " + FLAGGED_HINT if hazards.blocks(level) else ""), **extra)
+    return None, _error("denied" if req.status == "denied" else req.status, request_id=req.id,
+                        reason=req.deny_reason or None)
+
+
+async def _ssh_target(db, host: str, user_arg: str | None) -> tuple[Resource | None, str]:
+    res = (await db.execute(select(Resource).where(Resource.kind == "ssh", Resource.name == host))).scalar_one_or_none()
+    if res is None:
+        return None, ""
+    return res, (user_arg or "").strip() or res.config.get("user") or "root"
+
+
+def _user_patterns(res: Resource, user: str) -> list[str]:
+    return [f"ssh/{res.name}/user/{user}"] if user != (res.config.get("user") or "root") else []
+
+
+def _excerpt(text: str, limit: int = 2000, head: int = 600) -> str:
+    """Head and tail of a long stderr. Boot noise comes first; what happened is in the last lines."""
+    if len(text) <= limit:
+        return text
+    tail = limit - head
+    return f"{text[:head]}\n… [{len(text) - limit} characters omitted] …\n{text[-tail:]}"
+
+
+def _flagged(detail: dict[str, Any]) -> dict[str, Any]:
+    """The operation with its hazard flags. They ride along in requests, audit rows and results;
+    `access.operations` strips them before anything is bound to a grant."""
+    found = hazards.scan(detail)
+    return {**detail, "hazards": hazards.as_dicts(found)} if found else detail
+
+
+def _run_operation(res: Resource, command: str, user: str) -> tuple[list[str], dict[str, Any]]:
+    required = [*classify(res.name, command), *_user_patterns(res, user)]
+    return required, _flagged({"host": res.name, "command": command, "user": user, "resource_id": res.id})
+
+
+def _put_operation(res: Resource, path: str, content: str, user: str) -> tuple[list[str], dict[str, Any], bytes]:
+    """The prompt and the grant see the path and a digest of the contents, never the contents."""
+    body = content.encode()
+    if len(body) > ssh.MAX_PUT:
+        raise ValueError(f"content exceeds {ssh.MAX_PUT} bytes")
+    path = ssh.remote_path(path)
+    required = [f"ssh/{res.name}/put{path}", *_user_patterns(res, user)]
+    return required, _flagged({"host": res.name, "path": path, "sha256": hashlib.sha256(body).hexdigest(),
+                               "bytes": len(body), "user": user, "resource_id": res.id}), body
+
+
+def _get_operation(res: Resource, path: str, user: str) -> tuple[list[str], dict[str, Any]]:
+    path = ssh.remote_path(path)
+    return [f"ssh/{res.name}/get{path}", *_user_patterns(res, user)], \
+        _flagged({"host": res.name, "path": path, "user": user, "resource_id": res.id})
+
+
+def _capture_operation(src: Resource, command: str, user: str, dst: Resource, to_path: str, to_user: str,
+                       append: bool) -> tuple[list[str], dict[str, Any]]:
+    """Both halves in one operation: the grant names the command and where its output goes, so an
+    approval to capture never lets the same command return its output to the agent."""
+    to_path = ssh.remote_path(to_path)
+    required, detail = _run_operation(src, command, user)
+    required = [*required, f"ssh/{dst.name}/put{to_path}", *_user_patterns(dst, to_user)]
+    detail.pop("hazards", None)
+    return required, _flagged({**detail, "to_host": dst.name, "to_path": to_path, "to_user": to_user,
+                               "to_resource_id": dst.id, "append": bool(append)})
+
+
+async def _ssh_execute(db, agent: Agent, sid: str | None, tool: str, res: Resource, required: list[str],
+                       detail: dict[str, Any], v: policy.Verdict, command: str, user: str, *,
+                       timeout: int = 300, stdin: bytes | None = None):
+    """Run an allowed operation and audit it. Returns (RunResult, handle) or (None, error result)."""
+    await db.refresh(res)
+    started = time.monotonic()
+    try:
+        r = await ssh.run(res.config, command, timeout=timeout, user=user, **({"stdin": stdin} if stdin else {}))
+    except Exception as e:  # noqa: BLE001
+        stage, hint = ssh.failure_stage(e)
+        await audit.record(db, tool=tool, decision="error", agent=agent, session_id=sid, patterns=required,
+                           detail={**detail, "error": f"{type(e).__name__}: {e}", "stage": stage,
+                                   "matched": v.matched, "request_ids": v.request_ids},
+                           duration_ms=int((time.monotonic() - started) * 1000))
+        return None, _error("ssh_failed", stage=stage, hint=hint,
+                            message="SSH connection or command failed; see the admin audit log.")
+    if r.learned_host_key:
+        res.config = {**res.config, "host_key": r.learned_host_key}
+        await db.commit()
+    ev = await audit.record(db, tool=tool, decision="allow", agent=agent, session_id=sid, patterns=required,
+                            detail={**detail, "matched": v.matched, "consumed": v.consumed_grants,
+                                    "request_ids": v.request_ids,
+                                    "stdout_bytes": len(r.stdout), "stderr_bytes": len(r.stderr)},
+                            exit_code=r.exit_code, duration_ms=r.duration_ms)
+    return r, _handle(v, ev)
+
+
+async def _ssh_run(db, agent: Agent, sid: str | None, args: dict[str, Any]) -> types.CallToolResult:
+    host = (args.get("host") or "").strip()
+    command = (args.get("command") or "").strip()
+    if not host or not command:
+        return _error("invalid_arguments", hint="host and command are required")
+    res, user = await _ssh_target(db, host, args.get("user"))
+    if res is None:
+        return _error("unknown_resource", host=host, hint="Call access_list_resources for valid host names.")
+    required, detail = _run_operation(res, command, user)
+    wait_s = min(int(args.get("wait_seconds", DEFAULT_WAIT) or 0), MAX_WAIT)
+    v, err = await _gate(db, agent, sid, required, (args.get("reason") or "").strip(), detail, wait_s, "ssh_run")
+    if err:
+        return err
+    r, out = await _ssh_execute(db, agent, sid, "ssh_run", res, required, detail, v, command, user,
+                                timeout=int(args.get("timeout") or 300))
+    if r is None:
+        return out
+    handle = out
+    text = f"exit_code: {r.exit_code}\n"
+    if r.stdout:
+        text += f"--- stdout ---\n{r.stdout}\n"
+    if r.stderr:
+        text += f"--- stderr ---\n{r.stderr}\n"
+    if r.truncated:
+        text += "[output truncated at 1 MiB]\n"
+    text += _handle_text(handle) + "\n"
+    payload = {"exit_code": r.exit_code, "stdout": r.stdout, "stderr": r.stderr, "truncated": r.truncated,
+               "duration_ms": r.duration_ms, "keywright": handle}
+    return _result(payload, text=text, is_error=False)
+
+
+async def _ssh_put(db, agent: Agent, sid: str | None, args: dict[str, Any]) -> types.CallToolResult:
+    host = (args.get("host") or "").strip()
+    content = args.get("content")
+    if not host or not isinstance(args.get("path"), str) or not isinstance(content, str):
+        return _error("invalid_arguments", hint="host, path and content (a string) are required")
+    res, user = await _ssh_target(db, host, args.get("user"))
+    if res is None:
+        return _error("unknown_resource", host=host, hint="Call access_list_resources for valid host names.")
+    try:
+        required, detail, body = _put_operation(res, args["path"], content, user)
+        command = ssh.put_command(detail["path"], str(args.get("mode") or "0644"))
+    except ValueError as e:
+        return _error("invalid_arguments", hint=str(e))
+    wait_s = min(int(args.get("wait_seconds", DEFAULT_WAIT) or 0), MAX_WAIT)
+    v, err = await _gate(db, agent, sid, required, (args.get("reason") or "").strip(), detail, wait_s, "ssh_put")
+    if err:
+        return err
+    r, out = await _ssh_execute(db, agent, sid, "ssh_put", res, required, detail, v, command, user,
+                                timeout=120, stdin=body)
+    if r is None:
+        return out
+    if r.exit_code != 0:
+        return _error("put_failed", exit_code=r.exit_code, stderr=_excerpt(r.stderr), keywright=out,
+                      hint="The host refused the write; the path, its directory or the permissions are the usual causes.")
+    payload = {"written": detail["path"], "bytes": detail["bytes"], "sha256": detail["sha256"], "keywright": out}
+    return _result(payload, text=f"wrote {detail['bytes']} bytes to {detail['path']} (sha256 {detail['sha256'][:12]})\n"
+                   + _handle_text(out) + "\n")
+
+
+async def _ssh_get(db, agent: Agent, sid: str | None, args: dict[str, Any]) -> types.CallToolResult:
+    host = (args.get("host") or "").strip()
+    if not host or not isinstance(args.get("path"), str):
+        return _error("invalid_arguments", hint="host and path are required")
+    res, user = await _ssh_target(db, host, args.get("user"))
+    if res is None:
+        return _error("unknown_resource", host=host, hint="Call access_list_resources for valid host names.")
+    try:
+        required, detail = _get_operation(res, args["path"], user)
+    except ValueError as e:
+        return _error("invalid_arguments", hint=str(e))
+    wait_s = min(int(args.get("wait_seconds", DEFAULT_WAIT) or 0), MAX_WAIT)
+    v, err = await _gate(db, agent, sid, required, (args.get("reason") or "").strip(), detail, wait_s, "ssh_get")
+    if err:
+        return err
+    r, out = await _ssh_execute(db, agent, sid, "ssh_get", res, required, detail, v,
+                                ssh.get_command(detail["path"]), user, timeout=120)
+    if r is None:
+        return out
+    if r.exit_code != 0:
+        return _error("get_failed", exit_code=r.exit_code, stderr=_excerpt(r.stderr), keywright=out,
+                      hint="The host could not read the path; check that it exists and is readable.")
+    payload = {"path": detail["path"], "content": r.stdout, "truncated": r.truncated, "keywright": out}
+    return _result(payload, text=r.stdout + ("\n[content truncated at 1 MiB]" if r.truncated else "")
+                   + "\n" + _handle_text(out) + "\n")
+
+
+async def _ssh_capture(db, agent: Agent, sid: str | None, args: dict[str, Any]) -> types.CallToolResult:
+    host, to_host = (args.get("host") or "").strip(), (args.get("to_host") or "").strip()
+    command = (args.get("command") or "").strip()
+    if not host or not command or not to_host or not isinstance(args.get("to_path"), str):
+        return _error("invalid_arguments", hint="host, command, to_host and to_path are required")
+    src, user = await _ssh_target(db, host, args.get("user"))
+    dst, to_user = await _ssh_target(db, to_host, args.get("to_user"))
+    if src is None or dst is None:
+        return _error("unknown_resource", host=host if src is None else to_host,
+                      hint="Call access_list_resources for valid host names.")
+    append = bool(args.get("append"))
+    try:
+        required, detail = _capture_operation(src, command, user, dst, args["to_path"], to_user, append)
+        write = ssh.append_command(detail["to_path"]) if append else ssh.put_command(detail["to_path"],
+                                                                                     str(args.get("mode") or "0600"))
+    except ValueError as e:
+        return _error("invalid_arguments", hint=str(e))
+    wait_s = min(int(args.get("wait_seconds", DEFAULT_WAIT) or 0), MAX_WAIT)
+    v, err = await _gate(db, agent, sid, required, (args.get("reason") or "").strip(), detail, wait_s, "ssh_capture")
+    if err:
+        return err
+    # The payload exists only inside this call: it is never in a result, an audit row or a log line.
+    started = time.monotonic()
+    try:
+        r = await ssh.run(src.config, command, timeout=int(args.get("timeout") or 300), user=user)
+        if r.exit_code != 0 or r.truncated:
+            why = "output exceeds 1 MiB" if r.truncated else f"command exited {r.exit_code}"
+            ev = await audit.record(db, tool="ssh_capture", decision="allow", agent=agent, session_id=sid,
+                                    patterns=required, detail={**detail, "matched": v.matched, "consumed": v.consumed_grants,
+                                                               "request_ids": v.request_ids, "written": False,
+                                                               "stdout_bytes": len(r.stdout), "stderr_bytes": len(r.stderr)},
+                                    exit_code=r.exit_code, duration_ms=int((time.monotonic() - started) * 1000))
+            return _error("capture_failed", exit_code=r.exit_code, stderr=_excerpt(r.stderr), keywright=_handle(v, ev),
+                          hint=f"Nothing was written: {why}.")
+        body = r.stdout.encode()
+        await db.refresh(dst)
+        w = await ssh.run(dst.config, write, timeout=120, user=to_user, stdin=body)
+    except Exception as e:  # noqa: BLE001
+        stage, hint = ssh.failure_stage(e)
+        await audit.record(db, tool="ssh_capture", decision="error", agent=agent, session_id=sid, patterns=required,
+                           detail={**detail, "error": f"{type(e).__name__}: {e}", "stage": stage,
+                                   "matched": v.matched, "request_ids": v.request_ids},
+                           duration_ms=int((time.monotonic() - started) * 1000))
+        return _error("ssh_failed", stage=stage, hint=hint,
+                      message="SSH connection or command failed; see the admin audit log.")
+    for res, run in ((src, r), (dst, w)):
+        if run.learned_host_key:
+            res.config = {**res.config, "host_key": run.learned_host_key}
+    await db.commit()
+    digest = hashlib.sha256(body).hexdigest()
+    ev = await audit.record(db, tool="ssh_capture", decision="allow", agent=agent, session_id=sid, patterns=required,
+                            detail={**detail, "matched": v.matched, "consumed": v.consumed_grants,
+                                    "request_ids": v.request_ids, "written": w.exit_code == 0, "bytes": len(body),
+                                    "sha256": digest, "write_exit_code": w.exit_code, "stderr_bytes": len(r.stderr)},
+                            exit_code=r.exit_code, duration_ms=int((time.monotonic() - started) * 1000))
+    handle = _handle(v, ev)
+    if w.exit_code != 0:
+        return _error("put_failed", exit_code=w.exit_code, stderr=_excerpt(w.stderr), keywright=handle,
+                      hint="The command succeeded but the destination refused the write.")
+    verb = "appended" if append else "wrote"
+    payload = {"written": detail["to_path"], "to_host": dst.name, "append": append, "bytes": len(body),
+               "sha256": digest, "source_exit_code": r.exit_code, "source_stderr": _excerpt(r.stderr), "keywright": handle}
+    return _result(payload, text=f"{verb} {len(body)} bytes from {src.name} to {dst.name}:{detail['to_path']} "
+                   f"(sha256 {digest[:12]}); contents not returned\n" + _handle_text(handle) + "\n")
+
+
+async def _proxy_call(db, agent: Agent, sid: str | None, server: str, tool: str, args: dict[str, Any]) -> types.CallToolResult:
+    res = (await db.execute(select(Resource).where(Resource.kind == "mcp", Resource.name == server))).scalar_one_or_none()
+    if res is None:
+        return _error("unknown_tool", name=f"{server}{mcp_proxy.SEP}{tool}")
+    # Keywright's own control keys ride alongside the upstream tool's arguments and are removed
+    # here, so the upstream sees exactly what the caller asked for, the classifier and the human
+    # see the same, and a client cannot break a strict upstream by mistake. They are underscored
+    # so they cannot collide with an upstream parameter (`wait_seconds` is a real one somewhere).
+    args = dict(args)
+    reason = ""
+    if isinstance(args.get("_reason"), str):
+        reason = args.pop("_reason")
+    wait_s = DEFAULT_WAIT
+    if "_wait_seconds" in args:
+        try:
+            wait_s = max(0, min(int(args.pop("_wait_seconds") or 0), MAX_WAIT))
+        except (TypeError, ValueError):
+            return _error("invalid_arguments", hint="_wait_seconds must be an integer number of seconds.")
+    knowledge_call = res.config.get("adapter") == "knowledge"
+    internal = res.config.get("adapter") in ("keywright", "knowledge")
+    if internal:
+        try:
+            inventory_args = (knowledge_mcp if knowledge_call else inventory_mcp).validate(tool, args)
+        except (inventory.InventoryError, knowledge.KnowledgeError) as exc:
+            return _error("invalid_arguments", hint=str(exc))
+    required = classify_mcp(server, tool, args, res.config.get("arg_keys"))
+    detail = {"server": server, "tool": tool, "arguments": args, "resource_id": res.id}
+    prefix = f"mcp/{server}/"
+    found = hazards.scan_mcp(tool, [p[len(prefix):] for p in required if p.startswith(prefix)],
+                             res.config.get("hazard_tools"))
+    if found:
+        detail["hazards"] = hazards.as_dicts(found)
+    v, err = await _gate(db, agent, sid, required, reason, detail, wait_s, "mcp_call")
+    if err:
+        return err
+    await db.refresh(res)
+    started = time.monotonic()
+    try:
+        if internal:
+            # Start local write locks after approval, never while waiting for a human.
+            # The audit below commits both the changes and their attribution in one transaction.
+            await db.commit()
+            try:
+                if knowledge_call:
+                    result = await knowledge_mcp.execute(db, res.id, agent, tool, inventory_args)
+                    changes = []
+                else:
+                    result, changes = await inventory_mcp.execute(db, tool, inventory_args)
+                out = _result(result)
+                if changes:
+                    detail = {**detail, "changes": changes}
+            except (inventory.InventoryError, knowledge.KnowledgeError, IntegrityError) as exc:
+                await db.rollback()
+                await db.refresh(agent)
+                await db.refresh(res)
+                out = _error("knowledge_conflict" if knowledge_call else "inventory_conflict",
+                             hint=str(exc) if isinstance(exc, (inventory.InventoryError, knowledge.KnowledgeError))
+                             else "A conflicting record was saved. Read the current record and retry.")
+        else:
+            out = await mcp_proxy.call_tool(res.config, tool, args)
+    except Exception as e:  # noqa: BLE001
+        if internal:
+            await db.rollback()
+            await db.refresh(agent)
+            await db.refresh(res)
+        await audit.record(db, tool="mcp_call", decision="error", agent=agent, session_id=sid, patterns=required,
+                           detail={**detail, "error": (mcp_proxy.describe(e)
+                                   if res.config.get("result_inspection", "off") == "off"
+                                   else "Upstream failure; details suppressed by result inspection."),
+                                   "matched": v.matched, "request_ids": v.request_ids})
+        return _error("upstream_failed", message="Upstream call failed; see the admin audit log.")
+    upstream_is_error = bool(out.is_error)
+    out, inspection = await result_inspection.inspect(out, res.config)
+    try:
+        ev = await audit.record(db, tool="mcp_call", decision="allow", agent=agent, session_id=sid, patterns=required,
+                                detail={**detail, "matched": v.matched, "consumed": v.consumed_grants,
+                                        "request_ids": v.request_ids,
+                                        "is_error": upstream_is_error, "result_delivery": inspection},
+                                duration_ms=int((time.monotonic() - started) * 1000))
+    except Exception:
+        if internal:
+            await db.rollback()
+            await db.refresh(agent)
+            await db.refresh(res)
+        raise
+    if res.config.get("audit_handle", True):
+        # Add the trusted approval handle after result inspection.
+        handle = _handle(v, ev)
+        out = out.model_copy(update={
+            "meta": {**(out.meta or {}), "keywright": handle},
+            "content": [*out.content, types.TextContent(type="text", text=_handle_text(handle))],
+        })
+    return out
+
+
+def build_server() -> Server:
+    return Server(
+        "keywright",
+        version=__version__,
+        instructions=(
+            "Keywright brokers access to SSH hosts, MCP servers and LLM gateways. Call access_list_resources first. "
+            "Gated tools ask the human for approval automatically; always pass a specific `reason`. "
+            "To ask for several tools at once use access_request with patterns; a segment may end in * "
+            "(mcp/<server>/tools/ha_get_*) and MCP calls can be qualified by argument (.../service=light.turn_on). "
+            "A 'session' is your MCP session id or the X-Keywright-Session header you send; without one, "
+            "session-scoped approvals are not available and grants are once or time-limited. "
+            "If a call returns approval_required, wait with access_status or tell the user what you asked for. "
+            "Automatic approvals keep the exact command/tool arguments for once, timed, session, and permanent "
+            "access unless the human explicitly approves broader patterns. When you know your next SSH steps, "
+            "ask for them together: access_request(operations=[{host, command}, {host, put, content}, "
+            "{host, get}]) is one prompt and one exact grant per step. Prefer ssh_put/ssh_get over shell "
+            "redirection for files: they classify by path and never put file contents in the prompt. "
+            "A secret that only needs to reach another machine should go by ssh_capture, which delivers a "
+            "command's output straight to a file on the destination host without returning it to you. "
+            "Plain commands classify narrowly; loops, pipes and substitution need the host-wide ** pattern "
+            "and are approved one command line at a time. Destructive operations (recursive deletes of "
+            "system or home directories, formatting disks, destroying guests, volumes or pools, force "
+            "pushes, powering off, touching key material or login configuration) are flagged whatever "
+            "access you hold: the worst are refused outright, the rest always prompt the human and are "
+            "approved once, exactly. Never reword a command to get around a flag; tell the user instead. "
+            "Revocation blocks future calls; it does not stop running operations. "
+            "Never retry a denied request without new instructions from the user. ssh_failed is not a "
+            "decision: its `stage` (unreachable, hostkey, auth, exec) says where the connection broke, and "
+            "auth or hostkey failures need the admin to enrol or re-probe the host, not another attempt. "
+            "Only upstream TOOLS are proxied; upstream MCP resources (resources/read) and prompts are not "
+            "available through Keywright, so use a server's tool equivalents instead. A proxied tool takes "
+            "two optional control keys next to its own arguments, `_reason` (why, shown to the human) and "
+            "`_wait_seconds` (how long to wait for approval); Keywright removes both before forwarding."
+        ),
+        on_list_tools=on_list_tools,
+        on_call_tool=on_call_tool,
+    )