gargoyle-receipts 0.9.0.dev0__tar.gz → 0.11.0.dev0__tar.gz

{gargoyle_receipts-0.9.0.dev0/gargoyle_receipts.egg-info → gargoyle_receipts-0.11.0.dev0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gargoyle-receipts
-Version: 0.9.0.dev0
+Version: 0.11.0.dev0
 Summary: Signed, single-use, argument-bound receipts and human-approval holds for agent tool calls.
 Author: Justin LaPorte
 License-Expression: Apache-2.0
@@ -59,7 +59,7 @@ your MCP server and lets through only what both agreed to.
 
 [![PyPI](https://img.shields.io/pypi/v/gargoyle-receipts)](https://pypi.org/project/gargoyle-receipts/)
 
-Status: pre-release (`0.9.0.dev0`, on PyPI as `gargoyle-receipts`). The wire format is `gargoyle/3` and may
+Status: pre-release (`0.11.0.dev0`, on PyPI as `gargoyle-receipts`). The wire format is `gargoyle/3` and may
 still change before the first release; it is specified in [SPEC.md](SPEC.md).
 
 ## What a receipt gives you
@@ -235,7 +235,10 @@ undone the same way: the middleware keeps what a held write replaced and
 offers `gargoyle_revert`, which composes the restoring write and sends it
 through the gate, held, shown as a diff, bound to the current state, and
 refused if anything changed since. The audit marks a revert from the
-state hashes alone.
+state hashes alone. Every entry also names the MCP client that asked, from
+its initialize handshake, so a fleet with Claude on some desks and ChatGPT
+on others still has one trail that says who, through what, did what. The
+receipt itself stays model-agnostic.
 
 The MCP middleware also keeps an evidence log: one hash-chained line per
 decision, refusals and declined holds included, so the trail answers "what
@@ -289,6 +292,22 @@ and `gargoyle audit` verifies them later offline.
 and through the alternative with OPA in Docker for sites that run a policy
 engine.
 
+## Microsoft 365 and other targets: adapters
+
+What a held call changes is the adapter's business (`gargoyle.adapters`):
+it describes the target's state before and after, tells the approver what
+the call means in plain words, and composes the call that undoes it. Files
+on the executor's host are the default. `GARGOYLE_MCP_STATE_PROBE=graph`
+selects the Graph adapter for a Microsoft Graph MCP server: inbox rules,
+calendar events, contacts and Teams membership are bound to their state,
+explained on the card ("creates inbox rule 'Fwd invoices' (to an outside
+address: x@evil.example)"), undone by the inverse Graph call, and a send
+is marked as something that cannot be undone. The adapter reads state
+through the upstream server itself, so the gate needs no Graph credential
+of its own. Which tool is which is a JSON spec; the reference naming is in
+`gargoyle/specs/graph-reference.json`, and a different server's names are
+mapped there, not in code.
+
 ## Remote mode
 
 Claude's hosted connectors (claude.ai in the browser, Claude Desktop's
@@ -338,6 +357,7 @@ cannot attach receipts work unchanged. Configuration is by environment:
 | issuer `GARGOYLE_APPROVERS_PATH`, `GARGOYLE_APPROVER_ROLE`, `GARGOYLE_APPROVER_GROUPS` | where enrolled approvers persist (default `approvers.json` beside the keys) and which Entra app role (default `Approver`) or groups may enroll |
 | `GARGOYLE_HOLD_WEBHOOK_URL`, `GARGOYLE_APPROVE_URL` | issuer: POST a notice of every new hold (Slack incoming-webhook shape, `text` plus the hold) with a link to the console; notice only, the grant still needs the approver's key |
 | `GARGOYLE_MCP_STATE_PROBE` | `filesystem` (default) binds a held file write to the file's current state: the approver sees the change as a diff, the call refuses if the file moved before the run (`REF_VERIFY_STATE_MISMATCH`), and the execution receipt records pre and post state; `none` disables |
+| `GARGOYLE_MCP_ADAPTER_SPEC` | with `GARGOYLE_MCP_STATE_PROBE=graph`: the tool-to-resource mapping JSON (default: the reference naming) |
 | `GARGOYLE_MCP_UPSTREAM_URL`, `GARGOYLE_MCP_UPSTREAM_TOKEN` | remote mode: the MCP server to front over Streamable HTTP, and its bearer |
 | `GARGOYLE_MCP_SNAPSHOT_DIR` | where the bytes a held, state-bound write replaces are kept (default `snapshots/` beside the audit log; `none` disables undo); the middleware then offers a `gargoyle_revert` tool that restores an approved change through the gate, held and state-bound like any write |
 | `GARGOYLE_MCP_AUDIT_LOG` | the evidence log: every decision, honored or refused, as one hash-chained JSON line with its receipt, grant and execution receipt; `gargoyle audit --log` verifies the file |

{gargoyle_receipts-0.9.0.dev0 → gargoyle_receipts-0.11.0.dev0}/README.md

@@ -21,7 +21,7 @@ your MCP server and lets through only what both agreed to.
 
 [![PyPI](https://img.shields.io/pypi/v/gargoyle-receipts)](https://pypi.org/project/gargoyle-receipts/)
 
-Status: pre-release (`0.9.0.dev0`, on PyPI as `gargoyle-receipts`). The wire format is `gargoyle/3` and may
+Status: pre-release (`0.11.0.dev0`, on PyPI as `gargoyle-receipts`). The wire format is `gargoyle/3` and may
 still change before the first release; it is specified in [SPEC.md](SPEC.md).
 
 ## What a receipt gives you
@@ -197,7 +197,10 @@ undone the same way: the middleware keeps what a held write replaced and
 offers `gargoyle_revert`, which composes the restoring write and sends it
 through the gate, held, shown as a diff, bound to the current state, and
 refused if anything changed since. The audit marks a revert from the
-state hashes alone.
+state hashes alone. Every entry also names the MCP client that asked, from
+its initialize handshake, so a fleet with Claude on some desks and ChatGPT
+on others still has one trail that says who, through what, did what. The
+receipt itself stays model-agnostic.
 
 The MCP middleware also keeps an evidence log: one hash-chained line per
 decision, refusals and declined holds included, so the trail answers "what
@@ -251,6 +254,22 @@ and `gargoyle audit` verifies them later offline.
 and through the alternative with OPA in Docker for sites that run a policy
 engine.
 
+## Microsoft 365 and other targets: adapters
+
+What a held call changes is the adapter's business (`gargoyle.adapters`):
+it describes the target's state before and after, tells the approver what
+the call means in plain words, and composes the call that undoes it. Files
+on the executor's host are the default. `GARGOYLE_MCP_STATE_PROBE=graph`
+selects the Graph adapter for a Microsoft Graph MCP server: inbox rules,
+calendar events, contacts and Teams membership are bound to their state,
+explained on the card ("creates inbox rule 'Fwd invoices' (to an outside
+address: x@evil.example)"), undone by the inverse Graph call, and a send
+is marked as something that cannot be undone. The adapter reads state
+through the upstream server itself, so the gate needs no Graph credential
+of its own. Which tool is which is a JSON spec; the reference naming is in
+`gargoyle/specs/graph-reference.json`, and a different server's names are
+mapped there, not in code.
+
 ## Remote mode
 
 Claude's hosted connectors (claude.ai in the browser, Claude Desktop's
@@ -300,6 +319,7 @@ cannot attach receipts work unchanged. Configuration is by environment:
 | issuer `GARGOYLE_APPROVERS_PATH`, `GARGOYLE_APPROVER_ROLE`, `GARGOYLE_APPROVER_GROUPS` | where enrolled approvers persist (default `approvers.json` beside the keys) and which Entra app role (default `Approver`) or groups may enroll |
 | `GARGOYLE_HOLD_WEBHOOK_URL`, `GARGOYLE_APPROVE_URL` | issuer: POST a notice of every new hold (Slack incoming-webhook shape, `text` plus the hold) with a link to the console; notice only, the grant still needs the approver's key |
 | `GARGOYLE_MCP_STATE_PROBE` | `filesystem` (default) binds a held file write to the file's current state: the approver sees the change as a diff, the call refuses if the file moved before the run (`REF_VERIFY_STATE_MISMATCH`), and the execution receipt records pre and post state; `none` disables |
+| `GARGOYLE_MCP_ADAPTER_SPEC` | with `GARGOYLE_MCP_STATE_PROBE=graph`: the tool-to-resource mapping JSON (default: the reference naming) |
 | `GARGOYLE_MCP_UPSTREAM_URL`, `GARGOYLE_MCP_UPSTREAM_TOKEN` | remote mode: the MCP server to front over Streamable HTTP, and its bearer |
 | `GARGOYLE_MCP_SNAPSHOT_DIR` | where the bytes a held, state-bound write replaces are kept (default `snapshots/` beside the audit log; `none` disables undo); the middleware then offers a `gargoyle_revert` tool that restores an approved change through the gate, held and state-bound like any write |
 | `GARGOYLE_MCP_AUDIT_LOG` | the evidence log: every decision, honored or refused, as one hash-chained JSON line with its receipt, grant and execution receipt; `gargoyle audit --log` verifies the file |

gargoyle_receipts-0.11.0.dev0/gargoyle/adapters.py

@@ -0,0 +1,279 @@
+"""Adapters: what a held call changes, in a form the gate can bind, show,
+and undo. The gate itself knows only tool names and arguments. An adapter
+knows the target: it describes the target's state before and after a call
+(gargoyle.state), tells the approver what the call means, and composes the
+call that restores the earlier state (gargoyle.revert).
+
+    probe(tool, args)   -> (description, bytes) | None
+        description: {"ref", "sha256", "size", "text"?, "summary"?, "irreversible"?}
+        bytes: the state's canonical bytes (the hash's preimage), kept as the
+        snapshot; None when the target does not exist
+    restore(meta, pre_bytes, post_bytes) -> {"params": {"name", "arguments"}} | {"reason": REF_REVERT_*}
+        the inverse call, given the sidecar and the two snapshots
+
+FilesystemAdapter: a tool with a path changes that file. GraphAdapter: a
+Microsoft Graph MCP server's tools change mail rules, events, contacts,
+Teams objects; which tool is which is a JSON spec (gargoyle/specs/
+graph-reference.json is the reference naming; map your server's names).
+The Graph adapter reads state through the upstream server itself, with
+the same credential the write will use, so the gate needs no Graph access
+of its own.
+"""
+
+import hashlib
+import json
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Tuple
+
+from gargoyle.envelope import canonical_json
+from gargoyle.state import describe, filesystem_probe, read_target
+
+REF_REVERT_UNKNOWN = "REF_REVERT_UNKNOWN"
+REF_REVERT_NEEDS_DELETE = "REF_REVERT_NEEDS_DELETE"
+REF_REVERT_NOT_TEXT = "REF_REVERT_NOT_TEXT"
+REF_REVERT_IRREVERSIBLE = "REF_REVERT_IRREVERSIBLE"
+REF_REVERT_UNSUPPORTED = "REF_REVERT_UNSUPPORTED"
+
+Probe = Optional[Tuple[Dict[str, Any], Optional[bytes]]]
+
+
+class FilesystemAdapter:
+    """Files on the executor's host (the stdio middleware's own case)."""
+
+    name = "filesystem"
+
+    def probe(self, tool: str, args: Any) -> Probe:
+        desc = filesystem_probe(tool, args)
+        if desc is None:
+            return None
+        return desc, read_target(desc)
+
+    def restore(self, meta: Dict[str, Any], pre: Optional[bytes], post: Optional[bytes]) -> Dict[str, Any]:
+        if pre is None:
+            return {"reason": REF_REVERT_NEEDS_DELETE}      # undoing a create is a delete, which the gate refuses
+        try:
+            text = pre.decode("utf-8")
+        except UnicodeDecodeError:
+            return {"reason": REF_REVERT_NOT_TEXT}
+        return {"params": {"name": "write_file", "arguments": {"path": meta["ref"], "content": text}}}
+
+
+def _tool_json(reply: Any) -> Any:
+    """The JSON a Graph MCP tool returned, from its text content."""
+    if not isinstance(reply, dict) or "result" not in reply:
+        return None
+    result = reply["result"]
+    if isinstance(result, dict) and result.get("isError"):
+        return None
+    if isinstance(result, dict) and isinstance(result.get("structuredContent"), (dict, list)):
+        return result["structuredContent"]
+    for item in (result.get("content") or []) if isinstance(result, dict) else []:
+        if isinstance(item, dict) and item.get("type") == "text":
+            try:
+                return json.loads(item["text"])
+            except (ValueError, TypeError):
+                return None
+    return None
+
+
+class GraphAdapter:
+    """A Microsoft Graph MCP server, by spec.
+
+    spec = {
+      "internal_domains": ["contoso.com"],
+      "kinds": {
+        "<kind>": {"label": "inbox rule", "name_field": "displayName", "id_field": "id",
+                   "list_tool": "...", "list_args": {}, "items_path": "value",
+                   "get_tool": "...", "id_arg": "id",
+                   "create_tool": "...", "create_arg": "rule",
+                   "update_tool": "...", "update_arg": "rule",
+                   "delete_tool": "...",
+                   "writable_fields": ["displayName", "sequence", "conditions", "actions", "isEnabled"]}
+      },
+      "tools": {
+        "<tool name>": {"kind": "<kind>", "op": "create" | "update" | "delete"},
+        "<tool name>": {"op": "irreversible", "label": "send mail", "summary": "sends mail to {toRecipients}: {subject}"}
+      }
+    }"""
+
+    name = "graph"
+
+    def __init__(self, upstream: Any, spec: Dict[str, Any]) -> None:
+        self.upstream = upstream
+        self.spec = spec
+        self._next_id = 0
+
+    @classmethod
+    def from_file(cls, upstream: Any, path: str) -> "GraphAdapter":
+        return cls(upstream, json.loads(Path(path).read_text(encoding="utf-8")))
+
+    # ---- talking to the upstream ----
+    def _call(self, tool: str, args: Dict[str, Any]) -> Any:
+        self._next_id += 1
+        reply = self.upstream.send({"jsonrpc": "2.0", "id": "gargoyle-probe-%d" % self._next_id, "method": "tools/call",
+                                    "params": {"name": tool, "arguments": args}})
+        return _tool_json(reply)
+
+    def _items(self, kind: Dict[str, Any]) -> Optional[List[Dict[str, Any]]]:
+        doc = self._call(kind["list_tool"], dict(kind.get("list_args") or {}))
+        if doc is None:
+            return None
+        items = doc
+        for key in (kind.get("items_path") or "").split("."):
+            if key:
+                items = items.get(key) if isinstance(items, dict) else None
+        if not isinstance(items, list):
+            return None
+        idf = kind.get("id_field", "id")
+        return sorted((i for i in items if isinstance(i, dict) and idf in i), key=lambda i: str(i[idf]))
+
+    def _item(self, kind: Dict[str, Any], item_id: str) -> Optional[Dict[str, Any]]:
+        doc = self._call(kind["get_tool"], {kind.get("id_arg", "id"): item_id})
+        return doc if isinstance(doc, dict) else None
+
+    # ---- descriptions ----
+    @staticmethod
+    def _desc(ref: str, obj: Any, summary: str, irreversible: bool = False) -> Tuple[Dict[str, Any], Optional[bytes]]:
+        data = canonical_json(obj).encode("utf-8") if obj is not None else None
+        desc = describe(ref, data, with_text=False)
+        if data is not None:
+            desc["text"] = json.dumps(obj, indent=2, sort_keys=True)
+        desc["summary"] = summary
+        if irreversible:
+            desc["irreversible"] = True
+        return desc, data
+
+    def _external(self, value: Any) -> List[str]:
+        """Addresses in `value` outside the internal domains."""
+        internal = [d.lower() for d in self.spec.get("internal_domains", [])]
+        found: List[str] = []
+
+        def walk(v):
+            if isinstance(v, str) and "@" in v:
+                dom = v.rsplit("@", 1)[1].strip(">").lower()
+                if internal and dom not in internal:
+                    found.append(v)
+            elif isinstance(v, dict):
+                for x in v.values():
+                    walk(x)
+            elif isinstance(v, list):
+                for x in v:
+                    walk(x)
+        walk(value)
+        return found
+
+    def probe(self, tool: str, args: Any) -> Probe:
+        rule = (self.spec.get("tools") or {}).get(tool)
+        if rule is None or not isinstance(args, dict):
+            return None
+        op = rule.get("op")
+        if op == "irreversible":
+            text = rule.get("summary", "{tool}").replace("{tool}", tool)
+            for k, v in args.items():
+                text = text.replace("{" + k + "}", v if isinstance(v, str) else json.dumps(v))
+            ext = self._external(args)
+            if ext:
+                text += " (to an outside address: %s)" % ", ".join(ext[:3])
+            return self._desc("%s:%s" % (tool, rule.get("label", tool)), None, text + ". Cannot be undone.", irreversible=True)
+        kind = (self.spec.get("kinds") or {}).get(rule.get("kind"))
+        if kind is None:
+            return None
+        label = kind.get("label", rule.get("kind"))
+        name_field = kind.get("name_field")
+        if op == "create":
+            items = self._items(kind)
+            if items is None:
+                return None
+            payload = args.get(kind.get("create_arg", "item"), args)
+            name = payload.get(name_field) if isinstance(payload, dict) and name_field else None
+            summary = "creates %s%s" % (label, (" '%s'" % name) if name else "")
+            ext = self._external(payload)
+            if ext:
+                summary += " (to an outside address: %s)" % ", ".join(ext[:3])
+            return self._desc("%s:all" % rule["kind"], items, summary + "; %d %s(s) exist now" % (len(items), label))
+        item_id = args.get(kind.get("id_arg", "id"))
+        if not isinstance(item_id, str) or not item_id:
+            return None
+        item = self._item(kind, item_id)
+        name = item.get(name_field) if isinstance(item, dict) and name_field else None
+        verb = "updates" if op == "update" else "deletes" if op == "delete" else op
+        summary = "%s %s%s" % (verb, label, (" '%s'" % name) if name else " " + item_id)
+        if op == "update":
+            ext = self._external(args.get(kind.get("update_arg", "item"), args))
+            if ext:
+                summary += " (to an outside address: %s)" % ", ".join(ext[:3])
+        if item is None:
+            summary += " (does not exist now)"
+        return self._desc("%s:%s" % (rule["kind"], item_id), item, summary)
+
+    # ---- undo ----
+    def restore(self, meta: Dict[str, Any], pre: Optional[bytes], post: Optional[bytes]) -> Dict[str, Any]:
+        rule = (self.spec.get("tools") or {}).get(meta.get("tool"))
+        if rule is None:
+            return {"reason": REF_REVERT_UNSUPPORTED}
+        if rule.get("op") == "irreversible":
+            return {"reason": REF_REVERT_IRREVERSIBLE}
+        kind = (self.spec.get("kinds") or {}).get(rule.get("kind")) or {}
+        idf = kind.get("id_field", "id")
+        load = lambda b: json.loads(b.decode("utf-8")) if b is not None else None
+        before, after = load(pre), load(post)
+        if rule["op"] == "create":
+            # The created object is the one in the post set that was not in the pre set.
+            if not isinstance(before, list) or not isinstance(after, list) or not kind.get("delete_tool"):
+                return {"reason": REF_REVERT_UNSUPPORTED}
+            old = {str(i.get(idf)) for i in before}
+            new = [i for i in after if str(i.get(idf)) not in old]
+            if len(new) != 1:
+                return {"reason": REF_REVERT_UNKNOWN}
+            return {"params": {"name": kind["delete_tool"], "arguments": {kind.get("id_arg", "id"): str(new[0][idf])}}}
+        if rule["op"] == "update":
+            if not isinstance(before, dict) or not kind.get("update_tool"):
+                return {"reason": REF_REVERT_UNSUPPORTED}
+            fields = kind.get("writable_fields")
+            body = {k: v for k, v in before.items() if (fields is None or k in fields) and k != idf}
+            return {"params": {"name": kind["update_tool"], "arguments": {kind.get("id_arg", "id"): str(before[idf]),
+                                                                           kind.get("update_arg", "item"): body}}}
+        if rule["op"] == "delete":
+            if not isinstance(before, dict) or not kind.get("create_tool"):
+                return {"reason": REF_REVERT_UNSUPPORTED}
+            fields = kind.get("writable_fields")
+            body = {k: v for k, v in before.items() if (fields is None or k in fields) and k != idf}
+            return {"params": {"name": kind["create_tool"], "arguments": {kind.get("create_arg", "item"): body}}}
+        return {"reason": REF_REVERT_UNSUPPORTED}
+
+
+def adapter_from_name(name: Any, upstream: Any = None, spec_path: Optional[str] = None) -> Any:
+    """GARGOYLE_MCP_STATE_PROBE: "filesystem" (default), "none", or "graph"
+    with GARGOYLE_MCP_ADAPTER_SPEC naming the tool mapping (default: the
+    reference naming shipped in gargoyle/specs/graph-reference.json)."""
+    if name is None or name == "" or name == "filesystem":
+        return FilesystemAdapter()
+    if name == "none":
+        return None
+    if name == "graph":
+        if upstream is None:
+            raise ValueError("the graph adapter needs the upstream server")
+        path = spec_path or str(Path(__file__).parent / "specs" / "graph-reference.json")
+        return GraphAdapter.from_file(upstream, path)
+    if hasattr(name, "probe"):
+        return name
+    if callable(name):
+        return _LegacyProbeAdapter(name)
+    raise ValueError("unknown state probe: %s" % name)
+
+
+class _LegacyProbeAdapter:
+    """A bare probe function (tool, args) -> description, for tests and
+    integrators who wrote one before adapters existed."""
+
+    name = "custom"
+
+    def __init__(self, fn) -> None:
+        self.fn = fn
+
+    def probe(self, tool: str, args: Any) -> Probe:
+        desc = self.fn(tool, args)
+        return None if desc is None else (desc, read_target(desc))
+
+    def restore(self, meta, pre, post):
+        return FilesystemAdapter().restore(meta, pre, post)

{gargoyle_receipts-0.9.0.dev0 → gargoyle_receipts-0.11.0.dev0}/gargoyle/cli.py

@@ -238,6 +238,7 @@ def cmd_remote(args) -> int:
     app = build_remote_app(config, tokens, upstream=upstream, issuer_url=env.get("GARGOYLE_MCP_ISSUER_URL"),
                            audit_log=env.get("GARGOYLE_MCP_AUDIT_LOG") or str(out / "remote-audit.jsonl"),
                            state_probe=args.state_probe, snapshot_dir=env.get("GARGOYLE_MCP_SNAPSHOT_DIR"),
+                           adapter_spec=args.adapter_spec or env.get("GARGOYLE_MCP_ADAPTER_SPEC"),
                            approval_timeout=float(env.get("GARGOYLE_MCP_APPROVAL_TIMEOUT_SECONDS", "300")))
     tls = {}
     if args.ssl_certfile or args.ssl_keyfile:
@@ -316,6 +317,8 @@ def cmd_audit(args) -> int:
                 why += " state %s -> %s" % (pre or "?", post or "?") if post else " state %s" % pre
             if r.get("reverts"):
                 why += " reverts #%d" % r["reverts"]
+            if r.get("client"):
+                why += " via " + r["client"]
             print("%4s %-5s %-8s %-24s %-28s %s%s" % (r["seq"] if r["seq"] is not None else "?",
                                                       "ok" if r["accepted"] else "FAIL", r["kind"] or "?",
                                                       (r["tool"] or "?")[:24], (r["principal"] or "?")[:28], r["reason"], why))
@@ -373,8 +376,9 @@ def main(argv=None) -> int:
     p.add_argument("--ssl-certfile"); p.add_argument("--ssl-keyfile")
     p.add_argument("--upstream-url", help="front a remote MCP server (Streamable HTTP)")
     p.add_argument("--upstream-token", help="bearer for that server (or GARGOYLE_MCP_UPSTREAM_TOKEN)")
-    p.add_argument("--state-probe", default="none", choices=["none", "filesystem"],
-                   help="filesystem only when the upstream is a local filesystem server on this host")
+    p.add_argument("--state-probe", default="none", choices=["none", "filesystem", "graph"],
+                   help="filesystem when the upstream is a local filesystem server on this host; graph for a Microsoft Graph MCP server")
+    p.add_argument("--adapter-spec", help="with --state-probe graph: the tool mapping JSON (default: the reference naming)")
     p.add_argument("--verbose", action="store_true")
     p.add_argument("rest", nargs=argparse.REMAINDER, help="-- <command> for a stdio server to front")
     p.set_defaults(fn=cmd_remote)

{gargoyle_receipts-0.9.0.dev0 → gargoyle_receipts-0.11.0.dev0}/gargoyle/evidence.py

@@ -48,8 +48,9 @@ from gargoyle.envelope import args_sha256, canonical_json, canonical_json_legacy
 from gargoyle.execution import verify_chain
 from gargoyle.verifier import verify_provenance
 
-EVIDENCE_VERSION = "gargoyle-evidence/2"          # entry hashes over RFC 8785 canonical JSON
-EVIDENCE_VERSIONS = {"gargoyle-evidence/1": canonical_json_legacy, EVIDENCE_VERSION: canonical_json}
+EVIDENCE_VERSION = "gargoyle-evidence/3"          # version 3 adds `client`; hashes over RFC 8785 canonical JSON
+EVIDENCE_VERSIONS = {"gargoyle-evidence/1": canonical_json_legacy, "gargoyle-evidence/2": canonical_json,
+                     EVIDENCE_VERSION: canonical_json}
 GENESIS = "0" * 64
 
 HONORED = "honored"
@@ -65,6 +66,11 @@ REF_EVIDENCE_UNCHAINED = "REF_EVIDENCE_UNCHAINED"       # a pre-chain {receipt,
 
 _FIELDS = ("evidence_version", "seq", "prev_sha256", "at", "kind", "tool", "args_sha256",
            "principal", "reason", "receipt", "grant", "execution", "entry_sha256")
+# Version 3 names the MCP client that made the call ("Claude Desktop 1.2", "ChatGPT"),
+# from the initialize handshake; null when the client did not say. The
+# receipt stays model-agnostic: this is evidence about the session, not a
+# bound field of the decision.
+_FIELDS_V3 = _FIELDS + ("client",)
 
 
 def entry_sha256(entry: Dict[str, Any]) -> str:
@@ -78,9 +84,11 @@ def entry_sha256(entry: Dict[str, Any]) -> str:
 
 def build_entry(*, seq: int, prev_sha256: str, kind: str, tool: str, args: Any, principal: str,
                 reason: str, receipt: Any = None, grant: Any = None, execution: Any = None,
-                at: Optional[datetime] = None) -> Dict[str, Any]:
+                at: Optional[datetime] = None, client: Optional[str] = None) -> Dict[str, Any]:
     if kind not in (HONORED, REFUSED):
         raise ValueError("kind must be honored or refused")
+    if client is not None and not isinstance(client, str):
+        raise ValueError("client must be a string or None")
     entry = {
         "evidence_version": EVIDENCE_VERSION,
         "seq": seq,
@@ -94,6 +102,7 @@ def build_entry(*, seq: int, prev_sha256: str, kind: str, tool: str, args: Any,
         "receipt": receipt,
         "grant": grant,
         "execution": execution,
+        "client": client,
     }
     entry["entry_sha256"] = entry_sha256(entry)
     return entry
@@ -121,13 +130,15 @@ class EvidenceLog:
                     self._seq, self._tail = int(last["seq"]), str(last["entry_sha256"])
 
     def append(self, kind: str, tool: str, args: Any, principal: str, reason: str, *,
-               receipt: Any = None, grant: Any = None, execution: Any = None) -> Dict[str, Any]:
+               receipt: Any = None, grant: Any = None, execution: Any = None,
+               client: Optional[str] = None) -> Dict[str, Any]:
         """Write one entry and return it. Raises OSError if the file cannot
         be written; the caller decides whether that stops the call."""
         if self._seq is None:
             self._load_tail()
         entry = build_entry(seq=self._seq + 1, prev_sha256=self._tail, kind=kind, tool=tool, args=args,
-                            principal=principal, reason=reason, receipt=receipt, grant=grant, execution=execution)
+                            principal=principal, reason=reason, receipt=receipt, grant=grant, execution=execution,
+                            client=client)
         with open(self.path, "a", encoding="utf-8") as f:
             f.write(json.dumps(entry, sort_keys=True) + "\n")
         self._seq, self._tail = entry["seq"], entry["entry_sha256"]
@@ -135,8 +146,10 @@ class EvidenceLog:
 
 
 def _well_formed(entry: Any) -> bool:
-    return (isinstance(entry, dict) and set(entry) == set(_FIELDS)
+    expected = _FIELDS_V3 if isinstance(entry, dict) and entry.get("evidence_version") == EVIDENCE_VERSION else _FIELDS
+    return (isinstance(entry, dict) and set(entry) == set(expected)
             and entry["evidence_version"] in EVIDENCE_VERSIONS
+            and (entry.get("client") is None or isinstance(entry.get("client"), str))
             and isinstance(entry["seq"], int) and entry["seq"] >= 1
             and isinstance(entry["prev_sha256"], str) and len(entry["prev_sha256"]) == 64
             and isinstance(entry["at"], str) and entry["kind"] in (HONORED, REFUSED)
@@ -179,7 +192,7 @@ def verify_log(
             rc = rc if isinstance(rc, dict) else {}
             report.append({"seq": None, "kind": None, "tool": rc.get("tool"), "principal": rc.get("principal"),
                            "accepted": False, "reason": REF_EVIDENCE_UNCHAINED if legacy else REF_EVIDENCE_MALFORMED,
-                           "verdict": None, "released_by": [], "state": None})
+                           "verdict": None, "released_by": [], "state": None, "client": None})
             all_ok = False
             continue
         e = raw
@@ -212,7 +225,7 @@ def verify_log(
                  if ex.get("pre_state_sha256") or ex.get("post_state_sha256") else None)
         report.append({"seq": e["seq"], "kind": e["kind"], "tool": e["tool"], "principal": e["principal"],
                        "accepted": ok, "reason": reason, "verdict": e["reason"], "released_by": released_by,
-                       "state": state})
+                       "state": state, "client": e.get("client")})
         all_ok = all_ok and ok
         # The chain continues from what the file says, so one bad entry is
         # reported once rather than cascading into every later one.