gargoyle-receipts 0.6.1.dev0__tar.gz → 0.7.1.dev0__tar.gz

{gargoyle_receipts-0.6.1.dev0/gargoyle_receipts.egg-info → gargoyle_receipts-0.7.1.dev0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gargoyle-receipts
-Version: 0.6.1.dev0
+Version: 0.7.1.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.6.1.dev0`, on PyPI as `gargoyle-receipts`). The wire format is `gargoyle/3` and may
+Status: pre-release (`0.7.1.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
@@ -223,6 +223,15 @@ policy version authorized a specific call for a specific principal, a
 human's key released it, and exactly that call ran once, verifiable offline
 by anyone, in Python or TypeScript.
 
+A held call is approved against the state it was shown in. Before asking
+for the receipt the middleware hashes the target (a file's bytes, or its
+absence); the issuer binds that hash into the signed receipt; the console
+shows the proposed content as a diff against that state; after the human
+signs, the middleware hashes the target again and refuses if it moved; and
+the execution receipt carries the state before and after. An approval
+cannot be redirected by changing the file under it, and an audit shows not
+only that a write ran but what it changed.
+
 The MCP middleware also keeps an evidence log: one hash-chained line per
 decision, refusals and declined holds included, so the trail answers "what
 did the agent try" as well as "what did it do". `gargoyle audit --log`
@@ -304,6 +313,7 @@ cannot attach receipts work unchanged. Configuration is by environment:
 | issuer `GARGOYLE_ENTRA_CLIENT_ID`, `GARGOYLE_ENTRA_SCOPE` | lets the console sign approvers in with Entra (code flow with PKCE, no library); the browser generates a non-exportable key and enrolls it under the UPN |
 | 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_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 |
 
 **Issuing service** (`gargoyle.issuer_service`, run with uvicorn from

{gargoyle_receipts-0.6.1.dev0 → gargoyle_receipts-0.7.1.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.6.1.dev0`, on PyPI as `gargoyle-receipts`). The wire format is `gargoyle/3` and may
+Status: pre-release (`0.7.1.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
@@ -185,6 +185,15 @@ policy version authorized a specific call for a specific principal, a
 human's key released it, and exactly that call ran once, verifiable offline
 by anyone, in Python or TypeScript.
 
+A held call is approved against the state it was shown in. Before asking
+for the receipt the middleware hashes the target (a file's bytes, or its
+absence); the issuer binds that hash into the signed receipt; the console
+shows the proposed content as a diff against that state; after the human
+signs, the middleware hashes the target again and refuses if it moved; and
+the execution receipt carries the state before and after. An approval
+cannot be redirected by changing the file under it, and an audit shows not
+only that a write ran but what it changed.
+
 The MCP middleware also keeps an evidence log: one hash-chained line per
 decision, refusals and declined holds included, so the trail answers "what
 did the agent try" as well as "what did it do". `gargoyle audit --log`
@@ -266,6 +275,7 @@ cannot attach receipts work unchanged. Configuration is by environment:
 | issuer `GARGOYLE_ENTRA_CLIENT_ID`, `GARGOYLE_ENTRA_SCOPE` | lets the console sign approvers in with Entra (code flow with PKCE, no library); the browser generates a non-exportable key and enrolls it under the UPN |
 | 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_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 |
 
 **Issuing service** (`gargoyle.issuer_service`, run with uvicorn from

{gargoyle_receipts-0.6.1.dev0 → gargoyle_receipts-0.7.1.dev0}/gargoyle/cli.py

@@ -246,6 +246,10 @@ def cmd_audit(args) -> int:
             why = (" (%s)" % r["verdict"]) if r["kind"] == "refused" and r["verdict"] else ""
             if r.get("released_by"):
                 why += " released by " + ", ".join(r["released_by"])
+            if r.get("state"):
+                # A state-bound call: the target as it was approved, and as the run left it.
+                pre, post = (r["state"].get("pre") or "")[:8], (r["state"].get("post") or "")[:8]
+                why += " state %s -> %s" % (pre or "?", post or "?") if post else " state %s" % pre
             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))

{gargoyle_receipts-0.6.1.dev0 → gargoyle_receipts-0.7.1.dev0}/gargoyle/consumer.py

@@ -241,13 +241,14 @@ class Consumer:
         return self._executor_signing_key is not None
 
     def attest(self, envelope: Dict[str, Any], outputs: Any,
-               executed_at: Optional[datetime] = None) -> Dict[str, Any]:
+               executed_at: Optional[datetime] = None, post_state_sha256: Optional[str] = None) -> Dict[str, Any]:
         """The signed execution receipt for a call this consumer honored and
         the caller has just run with `outputs`. Raises when no executor key
         is configured: an unsigned statement of execution is not evidence."""
         if not self.attests:
             raise ValueError("this consumer has no executor signing key; cannot attest")
-        execution = build_execution_receipt(envelope=envelope, outputs=outputs, executed_at=executed_at)
+        execution = build_execution_receipt(envelope=envelope, outputs=outputs, executed_at=executed_at,
+                                            post_state_sha256=post_state_sha256)
         return sign_execution_receipt(execution, self._executor_signing_key, self.executor_key_id)
 
     def _approver_keys(self, key_record_view, gate_key_id, now) -> Dict[str, Any]:

{gargoyle_receipts-0.6.1.dev0 → gargoyle_receipts-0.7.1.dev0}/gargoyle/envelope.py

@@ -289,6 +289,9 @@ def build_envelope(
     on_behalf_of = call.get("on_behalf_of")
     if on_behalf_of is not None and not valid_principal(on_behalf_of):
         raise ValueError("call['on_behalf_of'], when present, must be a non-empty string")
+    state_hash = call.get("state_sha256")
+    if state_hash is not None and not (isinstance(state_hash, str) and len(state_hash) == 64):
+        raise ValueError("call['state_sha256'], when present, must be 64 hex characters")
     args_hash = args_sha256(call["args"])
     if timestamp_utc is None:
         timestamp_utc = datetime.now(timezone.utc).isoformat()
@@ -311,6 +314,8 @@ def build_envelope(
     }
     if on_behalf_of is not None:
         envelope["request_context"]["on_behalf_of"] = on_behalf_of
+    if state_hash is not None:
+        envelope["request_context"]["state_sha256"] = state_hash
     if approval is not None:
         envelope["approval"] = {"required": approval["required"]}
         if "approvers" in approval:

{gargoyle_receipts-0.6.1.dev0 → gargoyle_receipts-0.7.1.dev0}/gargoyle/evidence.py

@@ -160,7 +160,8 @@ def verify_log(
     {"accepted", "reason", "tail_sha256", "count", "honored", "refused",
      "entries": [{"seq", "kind", "tool", "principal", "accepted", "reason", "verdict", "released_by"}, ...]},
     `reason` the verification outcome, `verdict` what the executor recorded,
-    `released_by` the approver key ids of the grants an honored held call carried.
+    `released_by` the approver key ids of the grants an honored held call carried,
+    `state` {"pre", "post"} the target's state hashes when the call was state-bound.
     Verification continues past a bad entry so the report names every one."""
     trust = dict(issuer_public_keys=issuer_public_keys, executor_public_keys=executor_public_keys,
                  approver_public_keys=approver_public_keys)
@@ -178,7 +179,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": []})
+                           "verdict": None, "released_by": [], "state": None})
             all_ok = False
             continue
         e = raw
@@ -206,8 +207,12 @@ def verify_log(
         counts[e["kind"]] += 1
         released_by = [g.get("approver_key_id") for g in (e["grant"] if isinstance(e["grant"], list) else [e["grant"]])
                        if isinstance(g, dict)] if e["grant"] is not None else []
+        ex = e["execution"] if isinstance(e["execution"], dict) else {}
+        state = ({"pre": ex.get("pre_state_sha256"), "post": ex.get("post_state_sha256")}
+                 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})
+                       "accepted": ok, "reason": reason, "verdict": e["reason"], "released_by": released_by,
+                       "state": state})
         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.

{gargoyle_receipts-0.6.1.dev0 → gargoyle_receipts-0.7.1.dev0}/gargoyle/execution.py

@@ -78,11 +78,14 @@ def build_execution_receipt(
     envelope: Dict[str, Any],
     outputs: Any,
     executed_at: Optional[datetime] = None,
+    post_state_sha256: Optional[str] = None,
 ) -> Dict[str, Any]:
     """The unsigned execution receipt for a call the executor has just run
     under `envelope` (a receipt it honored, so decision_id is present) with
     `outputs` (any JSON value; only its hash is recorded). `executed_at`
-    must be timezone-aware; it defaults to now."""
+    must be timezone-aware; it defaults to now. When the receipt bound the
+    target's state, `pre_state_sha256` is copied from it and
+    `post_state_sha256` (gargoyle.state) records the state after the run."""
     if not isinstance(envelope, dict):
         raise TypeError("envelope must be the honored authorization receipt")
     for key in _BOUND_FROM_RECEIPT:
@@ -94,7 +97,9 @@ def build_execution_receipt(
         executed_at = datetime.now(timezone.utc)
     if executed_at.tzinfo is None:
         raise ValueError("executed_at must be timezone-aware (UTC)")
-    return {
+    if post_state_sha256 is not None and not (isinstance(post_state_sha256, str) and len(post_state_sha256) == 64):
+        raise ValueError("post_state_sha256 must be 64 hex characters")
+    out = {
         "execution_version": EXECUTION_VERSION,
         "decision_id": envelope["decision_id"],
         "decision_sha256": envelope["decision_sha256"],
@@ -104,6 +109,12 @@ def build_execution_receipt(
         "outputs_sha256": args_sha256(outputs),
         "executed_at": executed_at.isoformat(),
     }
+    pre = envelope["request_context"].get("state_sha256")
+    if pre is not None:
+        out["pre_state_sha256"] = pre
+    if post_state_sha256 is not None:
+        out["post_state_sha256"] = post_state_sha256
+    return out
 
 
 def sign_execution_receipt(execution: Dict[str, Any], signing_key: Any, key_id: str) -> Dict[str, Any]:
@@ -156,6 +167,13 @@ def verify_execution_receipt(
     for key in _BOUND_FROM_RECEIPT:
         if key not in envelope or serialize(execution[key]) != serialize(envelope[key]):
             return _reject(REF_EXEC_BINDING_MISMATCH)
+    # A state-bound receipt's execution receipt names the same pre-state.
+    pre = envelope["request_context"].get("state_sha256") if isinstance(envelope.get("request_context"), dict) else None
+    if (pre is not None or "pre_state_sha256" in execution) and execution.get("pre_state_sha256") != pre:
+        return _reject(REF_EXEC_BINDING_MISMATCH)
+    post = execution.get("post_state_sha256")
+    if post is not None and not (isinstance(post, str) and len(post) == 64):
+        return _reject(REF_EXEC_MALFORMED)
     if check_outputs:
         try:
             if args_sha256(outputs) != execution["outputs_sha256"]:

{gargoyle_receipts-0.6.1.dev0 → gargoyle_receipts-0.7.1.dev0}/gargoyle/issuer_service.py

@@ -52,6 +52,7 @@ STATIC = Path(__file__).resolve().parent / "static"
 from gargoyle.approval import (REF_APPROVAL_APPROVER_NOT_ELIGIBLE, REF_APPROVAL_DUPLICATE_APPROVER,
                                verify_grant)
 from gargoyle.envelope import approval_terms
+from gargoyle.state import state_sha256, valid_description
 from gargoyle.notify import notifier_from_env
 from gargoyle.approvers import (DEFAULT_APPROVER_ROLE, ENV_APPROVER_GROUPS, ENV_APPROVER_ROLE, ENV_APPROVERS_PATH,
                                 ApproverRegistry, may_enroll, valid_public_key_hex)
@@ -104,6 +105,7 @@ def build_issuer_app(
     app = FastAPI(title="Gargoyle issuing service")
     app.state.pending: Dict[str, Dict[str, Any]] = {}     # approval_request_id -> envelope
     app.state.pending_args: Dict[str, Any] = {}           # approval_request_id -> the call's arguments
+    app.state.pending_state: Dict[str, Any] = {}          # approval_request_id -> the target's state when held
     app.state.grants: Dict[str, Dict[str, Any]] = {}      # approval_request_id -> grant
     app.state.declined: set = set()                       # approval_request_ids a human refused
     registry = approver_registry if approver_registry is not None else ApproverRegistry(None)
@@ -147,6 +149,15 @@ def build_issuer_app(
         interaction = {**body.get("claims", {}), "tool": body["tool"], "args": body["args"],
                        "principal": who["principal"], "groups": who.get("groups", []),
                        "roles": who.get("roles", [])}
+        state = body.get("state")
+        if state is not None:
+            # The executor's description of the target before the call: its
+            # hash is bound into the receipt; the description is shown to
+            # the approver and seen by the policy.
+            if not valid_description(state):
+                raise _refuse(400, REF_ISSUER_BAD_REQUEST)
+            interaction["state_sha256"] = state_sha256(state)
+            interaction["state"] = {k: v for k, v in state.items() if k != "text"}
         if who["on_behalf_of"]:
             interaction["on_behalf_of"] = who["on_behalf_of"]
         result = issue(policy, body["target_url"], interaction, signing_key=signing_key, key_id=key_id,
@@ -157,6 +168,8 @@ def build_issuer_app(
             arid = result.envelope["approval_request_id"]
             app.state.pending[arid] = result.envelope
             app.state.pending_args[arid] = body["args"]
+            if state is not None:
+                app.state.pending_state[arid] = state
             if on_hold is not None:
                 try:
                     on_hold(result.envelope, body["args"])
@@ -174,10 +187,12 @@ def build_issuer_app(
             if datetime.fromisoformat(env["not_after"]) <= current:
                 del app.state.pending[arid]           # an expired hold can never be released
                 app.state.pending_args.pop(arid, None)
+                app.state.pending_state.pop(arid, None)
                 app.state.grants.pop(arid, None)
             elif not _complete(arid):
                 have = app.state.grants.get(arid, [])
                 live[arid] = {"envelope": env, "args": app.state.pending_args.get(arid),
+                              "state": app.state.pending_state.get(arid),
                               "collected": len(have), "required": approval_terms(env)["required"],
                               "approvers": [g["approver_key_id"] for g in have]}
         return {"pending": list(live.values())}
@@ -230,6 +245,7 @@ def build_issuer_app(
             return {"declined": False, "reason": REF_ISSUER_UNKNOWN_HOLD}
         del app.state.pending[arid]
         app.state.pending_args.pop(arid, None)
+        app.state.pending_state.pop(arid, None)
         app.state.grants.pop(arid, None)
         app.state.declined.add(arid)
         return {"declined": True, "reason": None}

{gargoyle_receipts-0.6.1.dev0 → gargoyle_receipts-0.7.1.dev0}/gargoyle/mcp_server.py

@@ -97,6 +97,7 @@ ENV_CLIENT_TOKEN = "GARGOYLE_MCP_CLIENT_TOKEN"
 ENV_APPROVAL_TIMEOUT = "GARGOYLE_MCP_APPROVAL_TIMEOUT_SECONDS"
 ENV_POLL_SECONDS = "GARGOYLE_MCP_POLL_SECONDS"
 ENV_AUDIT_LOG = "GARGOYLE_MCP_AUDIT_LOG"
+ENV_STATE_PROBE = "GARGOYLE_MCP_STATE_PROBE"   # "filesystem" (default): bind held calls to the target file's state; "none" to disable
 REF_TARGET_LOGIN_REQUIRED = "REF_TARGET_LOGIN_REQUIRED"   # Entra login mode and no usable token: run `gargoyle login`   # the evidence log: one hash-chained JSON line per decision, honored or refused
 
 # Self-issue refusals.
@@ -134,13 +135,16 @@ class IssuerClient:
     def _get(self, path: str) -> Any:
         return self._http.get(self.url + path, headers=self._headers(), timeout=self.request_timeout)
 
-    def issue(self, target_url: str, tool: str, args: Any) -> Dict[str, Any]:
+    def issue(self, target_url: str, tool: str, args: Any, state: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
         """{"envelope": ...} or {"envelope": None, "reason": ...}. The cause of
         an unavailable issuer (TLS, DNS, a refused connection) goes to stderr,
         where an MCP client's server log shows it; the refusal code stays
         generic."""
         try:
-            r = self._post("/issue", {"target_url": target_url, "tool": tool, "args": args})
+            body_out: Dict[str, Any] = {"target_url": target_url, "tool": tool, "args": args}
+            if state is not None:
+                body_out["state"] = state
+            r = self._post("/issue", body_out)
         except Exception as exc:
             if type(exc).__name__ == "LoginRequired":
                 sys.stderr.write("gargoyle: %s\n" % exc)
@@ -261,10 +265,14 @@ def _without_gargoyle_meta(params: Dict[str, Any]) -> Dict[str, Any]:
     return forwarded
 
 
-def call_for(tool: str, args: Any, principal: str) -> Dict[str, Any]:
+def call_for(tool: str, args: Any, principal: str, state_sha256: Optional[str] = None) -> Dict[str, Any]:
     """The call a receipt must bind to execute `tool` with `args` through a
-    server serving `principal`: the same three fields the issuer bound."""
-    return {"tool": tool, "args": args, "principal": principal}
+    server serving `principal`: the same three fields the issuer bound, plus
+    the target's current state hash when the receipt bound one."""
+    call = {"tool": tool, "args": args, "principal": principal}
+    if state_sha256 is not None:
+        call["state_sha256"] = state_sha256
+    return call
 
 
 class ServerState:
@@ -281,8 +289,11 @@ class ServerState:
         upstream: Optional[StdioUpstream] = None,
         issuer_client: Optional[IssuerClient] = None,
         audit_log: Optional[str] = None,
+        state_probe: Any = "filesystem",
     ) -> None:
+        from gargoyle.state import probe_from_name
         self.config = config
+        self.probe = state_probe if callable(state_probe) else probe_from_name(state_probe)
         self.upstream = upstream
         self.issuer_client = issuer_client
         self.evidence: Optional[EvidenceLog] = EvidenceLog(audit_log) if audit_log else None
@@ -331,8 +342,11 @@ def _gate(state: ServerState, params: Dict[str, Any]) -> Dict[str, Any]:
     if envelope is None and state.issuer_client is not None:
         # Self-issue: ask the issuing service, and wait for the human if it
         # flagged the call. Nothing below trusts the answer: the receipt is
-        # verified against the pinned issuer key like any other.
-        res = state.issuer_client.issue(state.config["target_id"], name, args)
+        # verified against the pinned issuer key like any other. The
+        # target's current state goes with the request (gargoyle.state), so
+        # a hold is approved against it and bound to it.
+        pre_state = state.probe(name, args) if state.probe is not None else None
+        res = state.issuer_client.issue(state.config["target_id"], name, args, state=pre_state)
         if res["envelope"] is None:
             return refused(res["reason"])
         envelope, self_issued = res["envelope"], True
@@ -342,7 +356,15 @@ def _gate(state: ServerState, params: Dict[str, Any]) -> Dict[str, Any]:
                 return refused(waited["reason"], envelope)
             grant = waited["grant"]
 
-    verdict = state.consumer.check(envelope, call_for(name, args, state.config["principal"]),
+    # A state-bound receipt is checked against the state as it is now, after
+    # any wait for approval: if the target moved, the call does not run.
+    live_state = None
+    if isinstance(envelope, dict) and isinstance(envelope.get("request_context"), dict) \
+            and "state_sha256" in envelope["request_context"] and state.probe is not None:
+        from gargoyle.state import state_sha256 as _state_hash
+        now_desc = state.probe(name, args)
+        live_state = _state_hash(now_desc) if now_desc is not None else None
+    verdict = state.consumer.check(envelope, call_for(name, args, state.config["principal"], live_state),
                                    grant=grant)
     if not verdict.honored:
         return refused(verdict.reason, envelope)
@@ -359,7 +381,7 @@ def _audit_meta(state: ServerState, gate: Dict[str, Any], outputs: Any, params:
     goes into the evidence log when one is configured, so a client that
     discards _meta still leaves evidence."""
     meta: Dict[str, Any] = {}
-    execution = _attest(state, gate["envelope"], outputs)
+    execution = _attest(state, gate["envelope"], outputs, params)
     if execution is not None:
         meta[EXECUTION_META_KEY] = execution
     if gate["self_issued"]:
@@ -385,12 +407,19 @@ def _record(state: ServerState, kind: str, gate: Dict[str, Any], params: Dict[st
         sys.stderr.write("gargoyle: evidence log unwritable: %s\n" % exc)
 
 
-def _attest(state: ServerState, envelope: Optional[Dict[str, Any]], outputs: Any) -> Optional[Dict[str, Any]]:
+def _attest(state: ServerState, envelope: Optional[Dict[str, Any]], outputs: Any,
+            params: Optional[Dict[str, Any]] = None) -> Optional[Dict[str, Any]]:
     """The signed execution receipt for an honored call, or None when this
-    server has no executor key."""
+    server has no executor key. For a state-bound call the target is
+    probed again after the run, so the receipt says what it changed."""
     if state.consumer is None or not state.consumer.attests or envelope is None:
         return None
-    return state.consumer.attest(envelope, outputs)
+    post = None
+    if params is not None and state.probe is not None and "state_sha256" in (envelope.get("request_context") or {}):
+        from gargoyle.state import state_sha256 as _state_hash
+        desc = state.probe(str(params.get("name")), params.get("arguments", {}))
+        post = _state_hash(desc) if desc is not None else None
+    return state.consumer.attest(envelope, outputs, post_state_sha256=post)
 
 
 def _success(msg_id: Any, result: Dict[str, Any]) -> Dict[str, Any]:
@@ -631,7 +660,8 @@ if __name__ == "__main__":
     _upstream = upstream_from_argv(sys.argv[1:])
     try:
         serve_stdio(ServerState(config_from_env(), upstream=_upstream, issuer_client=issuer_client_from_env(),
-                                audit_log=_os.environ.get(ENV_AUDIT_LOG) or None))
+                                audit_log=_os.environ.get(ENV_AUDIT_LOG) or None,
+                                state_probe=_os.environ.get(ENV_STATE_PROBE) or "filesystem"))
     finally:
         if _upstream is not None:
             _upstream.close()

gargoyle_receipts-0.7.1.dev0/gargoyle/state.py

@@ -0,0 +1,94 @@
+"""State-bound approval: the world the human saw is the world the call runs in.
+
+A held call is approved against what the approver was shown. Without this
+module that is the arguments alone; the target could change between the
+card and the run, and the executor would not notice. With it, the executor
+describes the target's current state before asking for the receipt, the
+issuer puts the state's hash into the receipt's signed request context,
+the approver's grant covers it, and at execution the executor describes
+the state again and refuses if it moved (REF_VERIFY_STATE_MISMATCH). The
+execution receipt then carries the pre-state and post-state hashes, so an
+auditor can see not only that the call ran but what it changed.
+
+The state description is the executor's own statement, as the execution
+receipt is; it binds the executor to one state, it does not make the
+executor honest. Its canonical form:
+
+    {"ref": <what was examined, e.g. the file path>,
+     "sha256": <hex of the bytes> | null when absent,
+     "size": <byte count> | null}
+
+and state_sha256 = sha256(canonical_json(description)). A `text` member
+(the bytes as UTF-8, when small enough) may travel beside the description
+to the issuer so the console can show a diff; it is not part of the hash,
+which already covers the bytes.
+
+The reference probe knows filesystem tools: for a tool that takes a path,
+the state is that file. Any executor can supply its own probe.
+"""
+
+import hashlib
+from typing import Any, Callable, Dict, Optional
+
+from gargoyle.envelope import canonical_json
+
+PROBE_TOOLS = ("write_file", "edit_file", "create_directory", "move_file", "delete_file")
+PATH_ARGS = ("path", "source")
+TEXT_LIMIT = 65536
+
+
+def describe(ref: str, data: Optional[bytes], *, with_text: bool = True) -> Dict[str, Any]:
+    """The state description for `ref` holding `data` (None when absent)."""
+    desc: Dict[str, Any] = {"ref": ref, "sha256": hashlib.sha256(data).hexdigest() if data is not None else None,
+                            "size": len(data) if data is not None else None}
+    if with_text and data is not None and len(data) <= TEXT_LIMIT:
+        try:
+            desc["text"] = data.decode("utf-8")
+        except UnicodeDecodeError:
+            pass
+    return desc
+
+
+def state_sha256(description: Dict[str, Any]) -> str:
+    """The hash the receipt binds: over ref, sha256 and size only."""
+    core = {"ref": description["ref"], "sha256": description.get("sha256"), "size": description.get("size")}
+    return hashlib.sha256(canonical_json(core).encode("utf-8")).hexdigest()
+
+
+def valid_description(d: Any) -> bool:
+    return (isinstance(d, dict) and isinstance(d.get("ref"), str) and bool(d["ref"])
+            and (d.get("sha256") is None or (isinstance(d["sha256"], str) and len(d["sha256"]) == 64))
+            and (d.get("size") is None or (isinstance(d["size"], int) and not isinstance(d["size"], bool) and d["size"] >= 0))
+            and (d.get("sha256") is None) == (d.get("size") is None)
+            and ("text" not in d or isinstance(d["text"], str))
+            and set(d) <= {"ref", "sha256", "size", "text"})
+
+
+def filesystem_probe(tool: str, args: Any) -> Optional[Dict[str, Any]]:
+    """The reference probe: for a filesystem tool with a path, the file's
+    current bytes (or absence). None for tools it does not know, so the
+    call is not state-bound."""
+    if tool not in PROBE_TOOLS or not isinstance(args, dict):
+        return None
+    path = next((args[k] for k in PATH_ARGS if isinstance(args.get(k), str) and args[k]), None)
+    if path is None:
+        return None
+    try:
+        with open(path, "rb") as f:
+            data = f.read()
+    except FileNotFoundError:
+        data = None
+    except IsADirectoryError:
+        return describe(path, b"", with_text=False)
+    except OSError:
+        return None
+    return describe(path, data)
+
+
+def probe_from_name(name: Optional[str]) -> Optional[Callable[[str, Any], Optional[Dict[str, Any]]]]:
+    """GARGOYLE_MCP_STATE_PROBE: "filesystem" (default) or "none"."""
+    if name in (None, "", "filesystem"):
+        return filesystem_probe
+    if name == "none":
+        return None
+    raise ValueError("unknown state probe: %s" % name)

{gargoyle_receipts-0.6.1.dev0 → gargoyle_receipts-0.7.1.dev0}/gargoyle/static/approve.html

@@ -23,6 +23,10 @@
   button { font:inherit; padding:8px 16px; border-radius:8px; border:1px solid var(--line); background:var(--card); color:var(--ink); cursor:pointer; }
   button.approve { background:var(--accent); border-color:var(--accent); color:#fff; font-weight:600; }
   button:disabled { opacity:.5; cursor:not-allowed; }
+  .state { margin:8px 0; }
+  pre.diff { max-height:320px; overflow:auto; }
+  .dadd { color:#1a7f37; } .ddel { color:#b42318; text-decoration:line-through; } .dctx { color:var(--muted, #777); }
+  .note { font-size:.9em; color:var(--muted, #777); }
   .actions { display:flex; gap:12px; align-items:center; }
   .empty { color:var(--muted); text-align:center; padding:48px 0; }
   .log { font-size:13px; color:var(--muted); margin-top:16px; }
@@ -48,7 +52,7 @@
   <div class="log" id="log"></div>
 </main>
 <script type="module">
-import { argsSha256, authorizeUrl, buildGrant, exchangeCode, generateApproverKey, importApproverKey, isoUtc, loadStoredKey,
+import { argsSha256, authorizeUrl, buildGrant, exchangeCode, generateApproverKey, importApproverKey, isoUtc, lineDiff, loadStoredKey,
          newGrantId, pkceChallenge, publicKeyHex, randomVerifier, signGrant, storeKey } from "./approve.js";
 
 const state = { token: null, key: null, keyId: null, ttl: 300, timer: null, seen: new Map() };
@@ -150,6 +154,7 @@ async function refresh() {
         ${required > 1 ? `<dt>approvals</dt><dd class="progress">${progress}</dd>` : ""}
         ${env.approval?.approvers ? `<dt>eligible</dt><dd>${env.approval.approvers.map(esc).join(", ")}${eligible ? "" : ' <span class="badge bad">not you</span>'}</dd>` : ""}
       </dl>
+      ${stateBlock(item)}
       <pre>${esc(JSON.stringify(item.args, null, 2))}</pre>
       <div class="actions">
         <button class="approve" ${bound && eligible && !mine ? "" : "disabled"}>Approve</button>
@@ -194,6 +199,26 @@ async function decline(card, id) {
   } catch (err) { card.querySelector(".result").innerHTML = `<span class="bad">${esc(err.message)}</span>`; }
 }
 
+// The state the executor saw when it asked (gargoyle.state), and the change
+// the call would make to it. The receipt binds this state: if the file
+// moves before the run, the executor refuses, so what you see here is what
+// the call will act on.
+function stateBlock(item) {
+  const st = item.state; if (!st) return "";
+  const args = item.args || {};
+  let head;
+  if (st.sha256 === null || st.sha256 === undefined) head = `creates <code>${esc(st.ref)}</code> (does not exist yet)`;
+  else head = `changes <code>${esc(st.ref)}</code> (${st.size} bytes now, state ${esc(String(st.sha256).slice(0, 12))}&hellip;)`;
+  let body = "";
+  if (typeof st.text === "string" && typeof args.content === "string") {
+    const rows = lineDiff(st.text, args.content).map((r) => `<span class="d${r.op === "+" ? "add" : r.op === "-" ? "del" : "ctx"}">${r.op} ${esc(r.text)}</span>`);
+    body = `<pre class="diff">${rows.join("\n")}</pre>`;
+  } else if (st.sha256 !== null && st.sha256 !== undefined && typeof args.content === "string") {
+    body = `<div class="note">current content is not text or is too large to show; the new content is below</div>`;
+  }
+  return `<div class="state"><strong>${head}</strong>${body}</div>`;
+}
+
 function esc(s) { return String(s).replace(/[&<>"']/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" }[c])); }
 </script>
 </body>

{gargoyle_receipts-0.6.1.dev0 → gargoyle_receipts-0.7.1.dev0}/gargoyle/static/approve.js

@@ -119,3 +119,21 @@ export async function storeKey(name, keyPair) {
     tx.oncomplete = () => resolve(); tx.onerror = () => reject(tx.error);
   });
 }
+
+// ---- What a held write changes: a line diff of the state the executor saw against the proposed content ----
+
+export function lineDiff(before, after) {
+  const a = before.split("\n"), b = after.split("\n");
+  const n = a.length, m = b.length;
+  const lcs = Array.from({ length: n + 1 }, () => new Array(m + 1).fill(0));
+  for (let i = n - 1; i >= 0; i--) for (let j = m - 1; j >= 0; j--) lcs[i][j] = a[i] === b[j] ? lcs[i + 1][j + 1] + 1 : Math.max(lcs[i + 1][j], lcs[i][j + 1]);
+  const out = []; let i = 0, j = 0;
+  while (i < n && j < m) {
+    if (a[i] === b[j]) { out.push({ op: " ", text: a[i] }); i++; j++; }
+    else if (lcs[i + 1][j] >= lcs[i][j + 1]) { out.push({ op: "-", text: a[i] }); i++; }
+    else { out.push({ op: "+", text: b[j] }); j++; }
+  }
+  while (i < n) out.push({ op: "-", text: a[i++] });
+  while (j < m) out.push({ op: "+", text: b[j++] });
+  return out;
+}

{gargoyle_receipts-0.6.1.dev0 → gargoyle_receipts-0.7.1.dev0}/gargoyle/verifier.py

@@ -70,6 +70,7 @@ REF_VERIFY_VERSION_UNSUPPORTED = "REF_VERIFY_VERSION_UNSUPPORTED"
 REF_VERIFY_REASSERT_INVALIDATED = "REF_VERIFY_REASSERT_INVALIDATED"
 REF_VERIFY_REASSERT_RE_EVALUATE_REQUIRED = "REF_VERIFY_REASSERT_RE_EVALUATE_REQUIRED"
 REF_VERIFY_BINDING_MISMATCH = "REF_VERIFY_BINDING_MISMATCH"
+REF_VERIFY_STATE_MISMATCH = "REF_VERIFY_STATE_MISMATCH"      # the target's state moved since the receipt bound it
 # The receipt names a different principal than the one the target
 # authenticated, or the target authenticated none.
 REF_VERIFY_PRINCIPAL_MISMATCH = "REF_VERIFY_PRINCIPAL_MISMATCH"
@@ -133,7 +134,7 @@ _REQUEST_CONTEXT_KEYS = (
 
 # The live call's keys: exactly these, plus optionally on_behalf_of.
 _CALL_KEYS = ("tool", "args", "principal")
-_OPTIONAL_CALL_KEYS = ("on_behalf_of",)
+_OPTIONAL_CALL_KEYS = ("on_behalf_of", "state_sha256")
 
 
 def _reject(reason: str) -> Dict[str, Any]:
@@ -211,6 +212,8 @@ def verify_provenance(
             return _reject(REF_VERIFY_ENVELOPE_ABSENT)
     if "on_behalf_of" in rc and not valid_principal(rc["on_behalf_of"]):
         return _reject(REF_VERIFY_ENVELOPE_ABSENT)
+    if "state_sha256" in rc and not (isinstance(rc["state_sha256"], str) and len(rc["state_sha256"]) == 64):
+        return _reject(REF_VERIFY_ENVELOPE_ABSENT)
     # A flagged receipt names the hold a grant must release; a receipt that
     # says so without naming it is unusable.
     if not isinstance(envelope["requires_approval"], bool):
@@ -405,4 +408,11 @@ def verify_envelope(
     if rc["args_sha256"] != live_args_hash:
         return _reject(REF_VERIFY_BINDING_MISMATCH)
 
+    # state: a receipt that binds the target's state (gargoyle.state) is
+    # honored only in that state. The executor supplies the hash it sees
+    # now; absent or different is a refusal. A live hash the receipt does
+    # not bind is ignored: it was not part of the decision.
+    if "state_sha256" in rc and call.get("state_sha256") != rc["state_sha256"]:
+        return _reject(REF_VERIFY_STATE_MISMATCH)
+
     return _accept()

{gargoyle_receipts-0.6.1.dev0 → gargoyle_receipts-0.7.1.dev0/gargoyle_receipts.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gargoyle-receipts
-Version: 0.6.1.dev0
+Version: 0.7.1.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.6.1.dev0`, on PyPI as `gargoyle-receipts`). The wire format is `gargoyle/3` and may
+Status: pre-release (`0.7.1.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
@@ -223,6 +223,15 @@ policy version authorized a specific call for a specific principal, a
 human's key released it, and exactly that call ran once, verifiable offline
 by anyone, in Python or TypeScript.
 
+A held call is approved against the state it was shown in. Before asking
+for the receipt the middleware hashes the target (a file's bytes, or its
+absence); the issuer binds that hash into the signed receipt; the console
+shows the proposed content as a diff against that state; after the human
+signs, the middleware hashes the target again and refuses if it moved; and
+the execution receipt carries the state before and after. An approval
+cannot be redirected by changing the file under it, and an audit shows not
+only that a write ran but what it changed.
+
 The MCP middleware also keeps an evidence log: one hash-chained line per
 decision, refusals and declined holds included, so the trail answers "what
 did the agent try" as well as "what did it do". `gargoyle audit --log`
@@ -304,6 +313,7 @@ cannot attach receipts work unchanged. Configuration is by environment:
 | issuer `GARGOYLE_ENTRA_CLIENT_ID`, `GARGOYLE_ENTRA_SCOPE` | lets the console sign approvers in with Entra (code flow with PKCE, no library); the browser generates a non-exportable key and enrolls it under the UPN |
 | 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_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 |
 
 **Issuing service** (`gargoyle.issuer_service`, run with uvicorn from

{gargoyle_receipts-0.6.1.dev0 → gargoyle_receipts-0.7.1.dev0}/gargoyle_receipts.egg-info/SOURCES.txt

@@ -27,6 +27,7 @@ gargoyle/policy.py
 gargoyle/published_record_source.py
 gargoyle/replay_cache.py
 gargoyle/rules.py
+gargoyle/state.py
 gargoyle/verifier.py
 gargoyle/static/approve.html
 gargoyle/static/approve.js
@@ -60,6 +61,7 @@ tests/test_opa.py
 tests/test_policy.py
 tests/test_published_record.py
 tests/test_rules.py
+tests/test_state.py
 tests/test_stdio_encoding.py
 tests/test_threshold.py
 tests/test_typescript_conformance.py

{gargoyle_receipts-0.6.1.dev0 → gargoyle_receipts-0.7.1.dev0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "gargoyle-receipts"
-version = "0.6.1.dev0"
+version = "0.7.1.dev0"
 description = "Signed, single-use, argument-bound receipts and human-approval holds for agent tool calls."
 readme = "README.md"
 requires-python = ">=3.12"

{gargoyle_receipts-0.6.1.dev0 → gargoyle_receipts-0.7.1.dev0}/tests/test_cli.py

@@ -112,7 +112,6 @@ def test_init_for_a_windows_client_and_audit_log_verification(tmp_path, monkeypa
     assert "4 entries (3 honored, 1 refused), 0 failed; chain EVIDENCE_VERIFIED" in out_text
     assert out_text.count(" ok ") == 4 and "refused  delete_file" in out_text
     assert "ENTRY_VERIFIED (DESTRUCTIVE_TOOL)" in out_text
-    assert "released by approver-1" in out_text          # the held write names who released it
     # A tampered entry is caught, and the hash-chain names it: editing the
     # execution receipt inside entry 2 changes its hash.
     lines = log.read_text().splitlines(); e = json.loads(lines[1]); e["execution"]["outputs_sha256"] = "0" * 64

{gargoyle_receipts-0.6.1.dev0 → gargoyle_receipts-0.7.1.dev0}/tests/test_evidence.py

@@ -151,3 +151,38 @@ def test_a_declined_hold_keeps_its_receipt_and_the_receipt_is_checked():
 def test_build_entry_rejects_unknown_kind():
     with pytest.raises(ValueError):
         build_entry(seq=1, prev_sha256=GENESIS, kind="maybe", tool="t", args={}, principal=PRINCIPAL, reason="x")
+
+
+def test_an_honored_held_call_reports_who_released_it(tmp_path):
+    """verify_log names the approver key ids behind an honored held call, so
+    the audit can print "released by <upn>"."""
+    from gargoyle.approval import build_grant, sign_grant
+    approver = Ed25519PrivateKey.generate()
+
+    class HoldAll:
+        def pin(self): return PIN
+        def decide(self, target_url, interaction): return Decision(ELIGIBLE, None, True)
+    env = _issue(HoldAll(), TARGET, {"tool": "write_file", "args": {"p": 1}, "principal": PRINCIPAL},
+                 signing_key=issuer, key_id="issuer-1", now=NOW).envelope
+    grant = sign_grant(build_grant(decision_sha256=env["decision_sha256"], approval_request_id=env["approval_request_id"],
+                                   grant_id="g-1", not_after=NOW + timedelta(minutes=10)), approver, "sysops@contoso.com")
+    ex = sign_execution_receipt(build_execution_receipt(envelope=env, outputs={"ok": True}, executed_at=RAN), executor, "executor-1")
+    log = EvidenceLog(str(tmp_path / "e.jsonl"))
+    log.append(HONORED, "write_file", {"p": 1}, PRINCIPAL, ACCEPT_CHAIN_VERIFIED, receipt=env, grant=grant, execution=ex)
+    log.append(REFUSED, "delete_file", {}, PRINCIPAL, "DESTRUCTIVE_TOOL")
+    v = verify_log(read_log(str(log.path)), approver_public_keys={"sysops@contoso.com": approver.public_key()}, **TRUST)
+    assert v["accepted"]
+    assert v["entries"][0]["released_by"] == ["sysops@contoso.com"] and v["entries"][1]["released_by"] == []
+    # And the CLI line carries it.
+    from gargoyle.cli import main
+    import json as _json
+    out = tmp_path / "deploy"; out.mkdir()
+    hexpub = lambda k: k.public_key().public_bytes(__import__("cryptography.hazmat.primitives.serialization", fromlist=["Encoding"]).Encoding.Raw,
+                                                   __import__("cryptography.hazmat.primitives.serialization", fromlist=["PublicFormat"]).PublicFormat.Raw).hex()
+    (out / "public-keys.json").write_text(_json.dumps({"issuer": {"issuer-1": hexpub(issuer)}, "executor": {"executor-1": hexpub(executor)},
+                                                        "approver": {"sysops@contoso.com": hexpub(approver)}}))
+    import io, contextlib
+    buf = io.StringIO()
+    with contextlib.redirect_stdout(buf):
+        assert main(["audit", "--log", str(log.path), "--out", str(out)]) == 0
+    assert "CHAIN_VERIFIED released by sysops@contoso.com" in buf.getvalue()

gargoyle_receipts-0.7.1.dev0/tests/test_state.py

@@ -0,0 +1,180 @@
+"""State-bound approval: a held call is approved against the target's state
+and runs only in that state. The middleware probes the file before asking,
+the issuer binds the hash into the receipt, the approver sees the change,
+the middleware probes again before running and refuses if the file moved,
+and the execution receipt records the state before and after."""
+
+from datetime import datetime, timedelta, timezone
+
+import pytest
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey
+from fastapi.testclient import TestClient
+
+from gargoyle.approval import build_grant, sign_grant
+from gargoyle.consumer import Consumer
+from gargoyle.envelope import build_envelope
+from gargoyle.execution import (ACCEPT_CHAIN_VERIFIED, REF_EXEC_BINDING_MISMATCH, build_execution_receipt,
+                                sign_execution_receipt, verify_chain, verify_execution_receipt)
+from gargoyle.issuer import issue
+from gargoyle.issuer_service import build_issuer_app
+from gargoyle.jws import encode
+from gargoyle.policy import ELIGIBLE, Decision
+from gargoyle.state import describe, filesystem_probe, probe_from_name, state_sha256, valid_description
+from gargoyle.verifier import REF_VERIFY_ENVELOPE_ABSENT, REF_VERIFY_STATE_MISMATCH, verify_envelope
+
+TARGET = "mcp://fs"
+PIN = {"policy_id": "p/1", "policy_sha256": "a" * 64}
+NOW = datetime(2026, 10, 19, 12, 0, tzinfo=timezone.utc)
+issuer, executor, approver, idp = (Ed25519PrivateKey.generate() for _ in range(4))
+ISSUER_KEYS = {"issuer-1": issuer.public_key()}
+
+
+class Hold:
+    def pin(self): return PIN
+    def decide(self, target_url, interaction): return Decision(ELIGIBLE, None, True)
+
+
+class Allow:
+    def pin(self): return PIN
+    def decide(self, target_url, interaction): return Decision(ELIGIBLE)
+
+
+def test_state_description_and_hash_cover_bytes_not_text():
+    d = describe("C:\\x\\notes.md", b"hello")
+    assert d["sha256"] and d["size"] == 5 and d["text"] == "hello"
+    assert state_sha256(d) == state_sha256({k: v for k, v in d.items() if k != "text"})
+    assert state_sha256(describe("p", b"hello")) != state_sha256(describe("p", b"hellO"))
+    absent = describe("p", None)
+    assert absent["sha256"] is None and absent["size"] is None and "text" not in absent
+    assert state_sha256(absent) != state_sha256(describe("p", b""))
+    assert valid_description(d) and valid_description(absent)
+    for bad in ({"ref": ""}, {"ref": "p", "sha256": "x", "size": 1}, {"ref": "p", "sha256": "a" * 64}, {"ref": "p", "extra": 1}):
+        assert not valid_description(bad), bad
+
+
+def test_filesystem_probe_reads_the_target_or_its_absence(tmp_path):
+    f = tmp_path / "n.md"; f.write_bytes(b"one\n")
+    d = filesystem_probe("write_file", {"path": str(f), "content": "two"})
+    assert d["ref"] == str(f) and d["size"] == 4 and d["text"] == "one\n"
+    gone = filesystem_probe("write_file", {"path": str(tmp_path / "new.md"), "content": "x"})
+    assert gone["sha256"] is None
+    assert filesystem_probe("read_file", {"path": str(f)}) is None           # not a state-changing tool
+    assert filesystem_probe("write_file", {"content": "x"}) is None          # nothing to probe
+    assert filesystem_probe("move_file", {"source": str(f), "destination": str(tmp_path / "m")})["size"] == 4
+    assert probe_from_name("none") is None and probe_from_name(None) is filesystem_probe
+    with pytest.raises(ValueError):
+        probe_from_name("magic")
+
+
+def test_receipt_binds_the_state_and_the_verifier_enforces_it():
+    pre = state_sha256(describe("p", b"one"))
+    call = {"tool": "write_file", "args": {"path": "p", "content": "two"}, "principal": "agent-7", "state_sha256": pre}
+    env = issue(Hold(), TARGET, call, signing_key=issuer, key_id="issuer-1", now=NOW).envelope
+    assert env["request_context"]["state_sha256"] == pre
+    live = {"tool": "write_file", "args": {"path": "p", "content": "two"}, "principal": "agent-7"}
+    kw = dict(record_source=PIN, pinned_public_keys=ISSUER_KEYS, now=NOW)
+    assert verify_envelope(env, dict(live, state_sha256=pre), TARGET, **kw)["accepted"]
+    assert verify_envelope(env, live, TARGET, **kw)["reason"] == REF_VERIFY_STATE_MISMATCH          # executor saw nothing
+    moved = state_sha256(describe("p", b"one and more"))
+    assert verify_envelope(env, dict(live, state_sha256=moved), TARGET, **kw)["reason"] == REF_VERIFY_STATE_MISMATCH
+    # Lowering the binding breaks the signature; a malformed hash is unusable; an unbound receipt ignores a live hash.
+    assert not verify_envelope(dict(env, request_context={**env["request_context"], "state_sha256": moved}),
+                               dict(live, state_sha256=moved), TARGET, **kw)["accepted"]
+    bad = dict(env, request_context={**env["request_context"], "state_sha256": "zz"})
+    assert verify_envelope(bad, live, TARGET, **kw)["reason"] == REF_VERIFY_ENVELOPE_ABSENT
+    free = issue(Allow(), TARGET, live, signing_key=issuer, key_id="issuer-1", now=NOW).envelope
+    assert verify_envelope(free, dict(live, state_sha256=pre), TARGET, **kw)["accepted"]
+    with pytest.raises(ValueError):
+        build_envelope(decision=ELIGIBLE, target_url=TARGET, call=dict(live, state_sha256="short"), policy_pin=PIN)
+
+
+def test_execution_receipt_records_pre_and_post_state():
+    pre = state_sha256(describe("p", b"one")); post = state_sha256(describe("p", b"two"))
+    call = {"tool": "write_file", "args": {"path": "p", "content": "two"}, "principal": "agent-7", "state_sha256": pre}
+    env = issue(Hold(), TARGET, call, signing_key=issuer, key_id="issuer-1", now=NOW).envelope
+    ex = sign_execution_receipt(build_execution_receipt(envelope=env, outputs={"ok": 1}, executed_at=NOW, post_state_sha256=post),
+                                executor, "executor-1")
+    assert ex["pre_state_sha256"] == pre and ex["post_state_sha256"] == post
+    keys = {"executor-1": executor.public_key()}
+    assert verify_execution_receipt(ex, env, keys)["accepted"]
+    grant = sign_grant(build_grant(decision_sha256=env["decision_sha256"], approval_request_id=env["approval_request_id"],
+                                   grant_id="g", not_after=NOW + timedelta(minutes=5)), approver, "approver-1")
+    chain = verify_chain(env, ex, grant=grant, issuer_public_keys=ISSUER_KEYS, executor_public_keys=keys,
+                         approver_public_keys={"approver-1": approver.public_key()})
+    assert chain["reason"] == ACCEPT_CHAIN_VERIFIED
+    # An execution receipt that drops or alters the pre-state does not describe this authorization.
+    forged = sign_execution_receipt({k: v for k, v in ex.items() if k not in ("pre_state_sha256", "executor_signature", "executor_key_id")},
+                                    executor, "executor-1")
+    assert verify_execution_receipt(forged, env, keys)["reason"] == REF_EXEC_BINDING_MISMATCH
+    with pytest.raises(ValueError):
+        build_execution_receipt(envelope=env, outputs={}, executed_at=NOW, post_state_sha256="nope")
+
+
+def _token(sub="agent-7"):
+    return encode({"sub": sub, "exp": int((datetime.now(timezone.utc) + timedelta(hours=1)).timestamp())}, idp, "idp-1")
+
+
+def test_middleware_refuses_when_the_file_moved_between_card_and_run(tmp_path):
+    """End to end: hold on a real file, the human approves, but the file was
+    edited meanwhile. The call does not run. Unchanged, it runs and the
+    execution receipt carries pre and post state."""
+    from gargoyle.mcp_server import IssuerClient, ServerState, _audit_meta, _gate
+    app = build_issuer_app(policy=Hold(), signing_key=issuer, key_id="issuer-1", idp_public_keys={"idp-1": idp.public_key()},
+                           approver_public_keys={"approver-1": approver.public_key()})
+    c = TestClient(app); h = {"Authorization": "Bearer " + _token()}
+
+    class Shim:
+        def post(self, url, json=None, headers=None, timeout=None): return c.post(url.replace("http://i", ""), json=json, headers=headers)
+        def get(self, url, headers=None, timeout=None): return c.get(url.replace("http://i", ""), headers=headers)
+
+    target = tmp_path / "notes.md"; target.write_text("one\n", encoding="utf-8")
+    params = {"name": "write_file", "arguments": {"path": str(target), "content": "two\n"}}
+    seen = {}
+
+    def approve_after_edit(seconds):
+        hold = c.get("/pending", headers=h).json()["pending"][0]
+        seen["state"] = hold["state"]
+        if seen.get("edit"):
+            target.write_text("someone else wrote this\n", encoding="utf-8")    # the world moved
+        env = hold["envelope"]
+        g = sign_grant(build_grant(decision_sha256=env["decision_sha256"], approval_request_id=env["approval_request_id"],
+                                   grant_id="g-" + env["approval_request_id"], not_after=datetime.now(timezone.utc) + timedelta(minutes=5)),
+                       approver, "approver-1")
+        c.post("/grants", json=g, headers=h)
+
+    def mw():
+        return ServerState({"pinned_public_keys": ISSUER_KEYS, "record": PIN, "target_id": TARGET, "principal": "agent-7",
+                            "approver_public_keys": {"approver-1": approver.public_key()},
+                            "executor_signing_key": executor, "executor_key_id": "executor-1"},
+                           issuer_client=IssuerClient("http://i", _token(), http=Shim(), approval_timeout=30, poll_seconds=0.01,
+                                                      sleep=approve_after_edit))
+
+    seen["edit"] = True
+    gate = _gate(mw(), params)
+    assert not gate["executed"] and gate["reason"] == REF_VERIFY_STATE_MISMATCH
+    assert seen["state"]["text"] == "one\n" and seen["state"]["size"] == 4         # what the approver was shown
+    assert target.read_text(encoding="utf-8") == "someone else wrote this\n"       # untouched by the gate
+
+    seen["edit"] = False
+    target.write_text("one\n", encoding="utf-8")
+    state = mw()
+    gate = _gate(state, params)
+    assert gate["executed"], gate["reason"]
+    target.write_text("two\n", encoding="utf-8")                                   # the upstream's effect, simulated
+    meta = _audit_meta(state, gate, {"ok": True}, params)
+    ex = meta["gargoyle/execution"]
+    assert ex["pre_state_sha256"] == state_sha256(describe(str(target), b"one\n"))
+    assert ex["post_state_sha256"] == state_sha256(describe(str(target), b"two\n"))
+    chain = verify_chain(gate["envelope"], ex, grant=gate["grant"], issuer_public_keys=ISSUER_KEYS,
+                         executor_public_keys={"executor-1": executor.public_key()}, approver_public_keys={"approver-1": approver.public_key()})
+    assert chain["reason"] == ACCEPT_CHAIN_VERIFIED
+    # The audit names the state transition.
+    from gargoyle.evidence import verify_log
+    entry = {"evidence_version": "gargoyle-evidence/2", "seq": 1, "prev_sha256": "0" * 64, "at": NOW.isoformat(), "kind": "honored",
+             "tool": "write_file", "args_sha256": gate["envelope"]["request_context"]["args_sha256"], "principal": "agent-7",
+             "reason": gate["reason"], "receipt": gate["envelope"], "grant": gate["grant"], "execution": ex}
+    from gargoyle.evidence import entry_sha256
+    entry["entry_sha256"] = entry_sha256(entry)
+    v = verify_log([entry], issuer_public_keys=ISSUER_KEYS, executor_public_keys={"executor-1": executor.public_key()},
+                   approver_public_keys={"approver-1": approver.public_key()})
+    assert v["accepted"] and v["entries"][0]["state"] == {"pre": ex["pre_state_sha256"], "post": ex["post_state_sha256"]}