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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gargoyle-receipts
-Version: 0.11.0.dev0
+Version: 0.12.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.11.0.dev0`, on PyPI as `gargoyle-receipts`). The wire format is `gargoyle/3` and may
+Status: pre-release (`0.12.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
@@ -292,6 +292,19 @@ and `gargoyle audit` verifies them later offline.
 and through the alternative with OPA in Docker for sites that run a policy
 engine.
 
+## Scoped grants
+
+One card per held call is right for a mailbox rule and wrong for a long
+task. The assistant can ask for a plan (`gargoyle_plan`): a list of steps,
+each a tool with exact arguments or argument patterns, and a note saying
+why. The issuer judges every step under the policy, signs the plan, and
+holds it as one card; the approver signs once; each later call matching
+an unused step runs without a card of its own until the plan expires.
+Every step is still bound, claimed once, and recorded with the plan and
+step that released it. The rules file decides what may be planned
+(`"plan": false` keeps a tool individual; sends should be), because a
+plan approves scope rather than content.
+
 ## Microsoft 365 and other targets: adapters
 
 What a held call changes is the adapter's business (`gargoyle.adapters`):

{gargoyle_receipts-0.11.0.dev0 → gargoyle_receipts-0.12.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.11.0.dev0`, on PyPI as `gargoyle-receipts`). The wire format is `gargoyle/3` and may
+Status: pre-release (`0.12.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
@@ -254,6 +254,19 @@ and `gargoyle audit` verifies them later offline.
 and through the alternative with OPA in Docker for sites that run a policy
 engine.
 
+## Scoped grants
+
+One card per held call is right for a mailbox rule and wrong for a long
+task. The assistant can ask for a plan (`gargoyle_plan`): a list of steps,
+each a tool with exact arguments or argument patterns, and a note saying
+why. The issuer judges every step under the policy, signs the plan, and
+holds it as one card; the approver signs once; each later call matching
+an unused step runs without a card of its own until the plan expires.
+Every step is still bound, claimed once, and recorded with the plan and
+step that released it. The rules file decides what may be planned
+(`"plan": false` keeps a tool individual; sends should be), because a
+plan approves scope rather than content.
+
 ## Microsoft 365 and other targets: adapters
 
 What a held call changes is the adapter's business (`gargoyle.adapters`):

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

@@ -311,6 +311,8 @@ 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("plan"):
+                why += " (plan %s step %d)" % (str(r["plan"].get("plan_id") or "?")[:8], r["plan"].get("step", -1) + 1)
             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]

{gargoyle_receipts-0.11.0.dev0 → gargoyle_receipts-0.12.0.dev0}/gargoyle/consumer.py

@@ -273,6 +273,7 @@ class Consumer:
         *,
         grant: Any = None,
         now: Optional[datetime] = None,
+        plan_release: Any = None,
     ) -> Verdict:
         """Decide whether to honor `envelope` for `call` ({"tool", "args",
         "principal"}, the principal being the one this consumer
@@ -321,7 +322,26 @@ class Consumer:
         # inside the signed region, so they are the issuer's word, not the
         # caller's. The grant is checked and claimed before the receipt is
         # claimed, so a refused grant leaves the receipt unspent.
-        if envelope["requires_approval"]:
+        if envelope["requires_approval"] and plan_release is not None:
+            # A scoped grant (gargoyle.plans): the plan's step is claimed once
+            # in place of a per-call grant id.
+            from gargoyle.plans import verify_plan_release
+            approver_keys = self._approver_keys(key_record_view, envelope.get("issuer_key_id"), now)
+            if not approver_keys:
+                return Verdict(False, REF_TARGET_NO_APPROVER_TRUST)
+            r = verify_plan_release(plan_release, envelope, call, issuer_public_keys=pinned_public_keys,
+                                    approver_public_keys=approver_keys, now=now, clock_skew=self.clock_skew)
+            if not r["accepted"]:
+                return Verdict(False, r["reason"])
+            plan = plan_release["plan"]
+            try:
+                plan_exp = datetime.fromisoformat(plan["not_after"]) + self.clock_skew
+            except (ValueError, TypeError, KeyError):
+                plan_exp = None
+            if not self.replay_cache.check_and_claim("plan:%s:%d" % (plan["plan_id"], r["step"]), plan_exp, now=now):
+                from gargoyle.plans import REF_PLAN_STEP_CONSUMED
+                return Verdict(False, REF_PLAN_STEP_CONSUMED)
+        elif envelope["requires_approval"]:
             grants = as_grant_list(grant)
             if not grants:
                 return Verdict(False, REF_TARGET_APPROVAL_REQUIRED)

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

@@ -192,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, "client": None})
+                           "verdict": None, "released_by": [], "state": None, "client": None, "plan": None})
             all_ok = False
             continue
         e = raw
@@ -218,14 +218,19 @@ def verify_log(
                                       now=_parse_at(e["at"]), historical=True)
                 ok, reason = p["accepted"], (ACCEPT_ENTRY_VERIFIED if p["accepted"] else p["reason"])
         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 []
+        plan_ref = None
+        grant_set = e["grant"]
+        if isinstance(grant_set, dict) and "plan" in grant_set and "step" in grant_set:
+            plan_ref = {"plan_id": (grant_set["plan"] or {}).get("plan_id"), "step": grant_set["step"]}
+            grant_set = grant_set.get("grants")
+        released_by = [g.get("approver_key_id") for g in (grant_set if isinstance(grant_set, list) else [grant_set])
+                       if isinstance(g, dict)] if grant_set 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,
-                       "state": state, "client": e.get("client")})
+                       "state": state, "client": e.get("client"), "plan": plan_ref})
         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.11.0.dev0 → gargoyle_receipts-0.12.0.dev0}/gargoyle/execution.py

@@ -218,10 +218,17 @@ def verify_chain(
         return {"accepted": False, "reason": provenance["reason"], "steps": steps}
 
     if envelope["requires_approval"]:
-        if not as_grant_list(grant):
+        from gargoyle.plans import is_plan_release, verify_plan_release
+        if is_plan_release(grant):
+            # Released by a scoped grant: the plan, its grants and the step,
+            # re-matched against the arguments the release recorded.
+            g = verify_plan_release(grant, envelope, {}, issuer_public_keys=issuer_public_keys,
+                                    approver_public_keys=approver_public_keys or {}, now=executed_at)
+        elif not as_grant_list(grant):
             steps.append(("approval", REF_EXEC_GRANT_MISSING))
             return {"accepted": False, "reason": REF_EXEC_GRANT_MISSING, "steps": steps}
-        g = verify_grants(grant, envelope=envelope, approver_public_keys=approver_public_keys or {}, now=executed_at)
+        else:
+            g = verify_grants(grant, envelope=envelope, approver_public_keys=approver_public_keys or {}, now=executed_at)
         steps.append(("approval", g["reason"]))
         if not g["accepted"]:
             return {"accepted": False, "reason": g["reason"], "steps": steps}

{gargoyle_receipts-0.11.0.dev0 → gargoyle_receipts-0.12.0.dev0}/gargoyle/issuer_service.py

@@ -40,7 +40,7 @@ it again when the call runs. The pending set is in memory: one instance.
 
 import json
 import os
-from datetime import datetime, timezone
+from datetime import datetime, timedelta, timezone
 from pathlib import Path
 from typing import Any, Callable, Dict, Optional
 
@@ -53,6 +53,8 @@ from gargoyle.approval import (REF_APPROVAL_APPROVER_NOT_ELIGIBLE, REF_APPROVAL_
                                verify_grant)
 from gargoyle.envelope import approval_terms
 from gargoyle.state import state_sha256, valid_description
+from gargoyle.plans import (REF_PLAN_MALFORMED, REF_PLAN_STEP_NOT_PLANNABLE, REF_PLAN_STEP_REFUSED, build_plan,
+                            sign_plan, valid_step)
 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)
@@ -108,6 +110,7 @@ def build_issuer_app(
     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
+    app.state.pending_plans: Dict[str, Dict[str, Any]] = {}   # approval_request_id -> signed plan (gargoyle.plans)
     registry = approver_registry if approver_registry is not None else ApproverRegistry(None)
     static_approvers = dict(approver_public_keys or {})
 
@@ -164,7 +167,20 @@ def build_issuer_app(
                        ttl_seconds=ttl_seconds, now=now())
         if result.envelope is None:
             return {"issued": False, "reason": result.decision.reason}
-        if result.envelope["requires_approval"]:
+        covered = False
+        plan_id = body.get("plan_id")
+        if result.envelope["requires_approval"] and isinstance(plan_id, str):
+            # The executor says an approved plan covers this call. No card then:
+            # the executor enforces the plan (step single use, grants, expiry)
+            # and the console should not show a hold nobody needs to act on.
+            # A false claim costs nothing here: without a valid release the
+            # executor refuses the call.
+            from gargoyle.plans import match_step
+            for arid_p, plan in app.state.pending_plans.items():
+                if plan["plan_id"] == plan_id and _complete(arid_p) and match_step(plan, body["tool"], body["args"]) is not None:
+                    covered = True
+                    break
+        if result.envelope["requires_approval"] and not covered:
             arid = result.envelope["approval_request_id"]
             app.state.pending[arid] = result.envelope
             app.state.pending_args[arid] = body["args"]
@@ -178,11 +194,75 @@ def build_issuer_app(
                     sys.stderr.write("gargoyle: on_hold failed: %s\n" % exc)
         return {"issued": True, "envelope": result.envelope}
 
+    @app.post("/plans")
+    async def post_plan(request: Request, authorization: Optional[str] = Header(default=None)):
+        """A scoped grant request: every step judged by the policy; the plan
+        signed and held when any step would be. Steps with exact arguments
+        are judged on them; a pattern step is judged with its patterns as the
+        argument values, so a broad pattern fails a narrow rule."""
+        who = authenticate(authorization)
+        try:
+            body = await request.json()
+        except Exception:
+            raise _refuse(400, REF_ISSUER_BAD_REQUEST)
+        steps = body.get("steps") if isinstance(body, dict) else None
+        if (not isinstance(body, dict) or not isinstance(body.get("target_url"), str) or not isinstance(steps, list)
+                or not steps or len(steps) > 200 or not all(valid_step(s) or ("args" in s and isinstance(s.get("tool"), str)) for s in steps)
+                or not isinstance(body.get("note", ""), str)):
+            raise _refuse(400, REF_ISSUER_BAD_REQUEST)
+        from gargoyle.envelope import args_sha256
+        norm, held, required, approvers = [], False, 1, set()
+        for s in steps:
+            if "args" in s:
+                judged_args, step = s["args"], {"tool": s["tool"], "args_sha256": args_sha256(s["args"])}
+            elif "args_sha256" in s:
+                return {"issued": False, "reason": REF_PLAN_MALFORMED}        # a hash alone cannot be judged
+            else:
+                judged_args, step = dict(s["match"]), {"tool": s["tool"], "match": dict(s["match"])}
+            interaction = {"tool": s["tool"], "args": judged_args, "principal": who["principal"],
+                           "groups": who.get("groups", []), "roles": who.get("roles", [])}
+            try:
+                d = policy.decide(body["target_url"], interaction)
+            except Exception:
+                return {"issued": False, "reason": REF_PLAN_STEP_REFUSED}
+            if not d.eligible:
+                return {"issued": False, "reason": REF_PLAN_STEP_REFUSED, "step": len(norm)}
+            if d.requires_approval:
+                if not d.plannable:
+                    return {"issued": False, "reason": REF_PLAN_STEP_NOT_PLANNABLE, "step": len(norm)}
+                held = True
+                required = max(required, d.approvals_required)
+                if d.approvers:
+                    approvers.update(d.approvers)
+            norm.append(step)
+        import uuid
+        approval = None
+        if required > 1 or approvers:
+            approval = {"required": required, **({"approvers": sorted(approvers)} if approvers else {})}
+        plan = sign_plan(build_plan(plan_id=str(uuid.uuid4()), approval_request_id=str(uuid.uuid4()), target_url=body["target_url"],
+                                    principal=who["principal"], policy_pin=policy.pin(), steps=norm,
+                                    not_after=now() + timedelta(seconds=min(ttl_seconds * 6, 3600)), note=body.get("note", ""),
+                                    approval=approval), signing_key, key_id)
+        if held:
+            app.state.pending_plans[plan["approval_request_id"]] = plan
+        return {"issued": True, "plan": plan, "held": held}
+
+    def _plan_terms(plan):
+        return approval_terms({"approval": plan["approval"]} if "approval" in plan else {})
+
     @app.get("/pending")
     async def pending(authorization: Optional[str] = Header(default=None)):
         authenticate(authorization)
         current = now()
         live = {}
+        for arid, plan in list(app.state.pending_plans.items()):
+            if datetime.fromisoformat(plan["not_after"]) <= current:
+                del app.state.pending_plans[arid]
+                app.state.grants.pop(arid, None)
+            elif len(app.state.grants.get(arid, [])) < _plan_terms(plan)["required"]:
+                have = app.state.grants.get(arid, [])
+                live[arid] = {"plan": plan, "collected": len(have), "required": _plan_terms(plan)["required"],
+                              "approvers": [g["approver_key_id"] for g in have]}
         for arid, env in list(app.state.pending.items()):
             if datetime.fromisoformat(env["not_after"]) <= current:
                 del app.state.pending[arid]           # an expired hold can never be released
@@ -199,7 +279,10 @@ def build_issuer_app(
 
     def _complete(arid: str) -> bool:
         env = app.state.pending.get(arid)
-        return env is not None and len(app.state.grants.get(arid, [])) >= approval_terms(env)["required"]
+        if env is None:
+            plan = app.state.pending_plans.get(arid)
+            return plan is not None and len(app.state.grants.get(arid, [])) >= _plan_terms(plan)["required"]
+        return len(app.state.grants.get(arid, [])) >= approval_terms(env)["required"]
 
     @app.post("/grants")
     async def post_grant(request: Request, authorization: Optional[str] = Header(default=None)):
@@ -210,18 +293,19 @@ def build_issuer_app(
             raise _refuse(400, REF_ISSUER_BAD_REQUEST)
         arid = grant.get("approval_request_id") if isinstance(grant, dict) else None
         env = app.state.pending.get(arid) if isinstance(arid, str) else None
-        if env is None:
+        plan = app.state.pending_plans.get(arid) if isinstance(arid, str) else None
+        if env is None and plan is None:
             return {"accepted": False, "reason": REF_ISSUER_UNKNOWN_HOLD}
         trusted = approver_keys()
         if not trusted:
             return {"accepted": False, "reason": REF_ISSUER_NO_APPROVER_TRUST}
-        g = verify_grant(grant, expected_decision_sha256=env["decision_sha256"],
+        g = verify_grant(grant, expected_decision_sha256=env["decision_sha256"] if env else plan["plan_sha256"],
                          expected_approval_request_id=arid, approver_public_keys=trusted,
                          gate_key_id=key_id, now=now())
         if not g["accepted"]:
             return {"accepted": False, "reason": g["reason"]}
-        # The receipt's own terms: distinct approvers, from the named set if any.
-        terms = approval_terms(env)
+        # The receipt's (or plan's) own terms: distinct approvers, from the named set if any.
+        terms = approval_terms(env) if env else _plan_terms(plan)
         have = app.state.grants.setdefault(arid, [])
         if any(h["approver_key_id"] == grant["approver_key_id"] for h in have):
             return {"accepted": False, "reason": REF_APPROVAL_DUPLICATE_APPROVER}
@@ -241,9 +325,10 @@ def build_issuer_app(
         except Exception:
             raise _refuse(400, REF_ISSUER_BAD_REQUEST)
         arid = body.get("approval_request_id") if isinstance(body, dict) else None
-        if not isinstance(arid, str) or arid not in app.state.pending:
+        if not isinstance(arid, str) or (arid not in app.state.pending and arid not in app.state.pending_plans):
             return {"declined": False, "reason": REF_ISSUER_UNKNOWN_HOLD}
-        del app.state.pending[arid]
+        app.state.pending_plans.pop(arid, None)
+        app.state.pending.pop(arid, None)
         app.state.pending_args.pop(arid, None)
         app.state.pending_state.pop(arid, None)
         app.state.grants.pop(arid, None)
@@ -253,13 +338,13 @@ def build_issuer_app(
     @app.get("/grants/{approval_request_id}")
     async def get_grant(approval_request_id: str, authorization: Optional[str] = Header(default=None)):
         authenticate(authorization)
-        env = app.state.pending.get(approval_request_id)
+        env = app.state.pending.get(approval_request_id) or app.state.pending_plans.get(approval_request_id)
         have = app.state.grants.get(approval_request_id, [])
         complete = _complete(approval_request_id)
         return {"pending": env is not None,
                 "grant": have[0] if complete and len(have) == 1 else None,
                 "grants": list(have) if complete else [],
-                "collected": len(have), "required": approval_terms(env)["required"] if env else None,
+                "collected": len(have), "required": (_plan_terms(env) if env and "plan_version" in env else approval_terms(env))["required"] if env else None,
                 "declined": approval_request_id in app.state.declined}
 
     @app.get("/approvers")

{gargoyle_receipts-0.11.0.dev0 → gargoyle_receipts-0.12.0.dev0}/gargoyle/mcp_server.py

@@ -138,7 +138,8 @@ 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, state: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+    def issue(self, target_url: str, tool: str, args: Any, state: Optional[Dict[str, Any]] = None,
+              plan_id: Optional[str] = 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
@@ -147,6 +148,8 @@ class IssuerClient:
             body_out: Dict[str, Any] = {"target_url": target_url, "tool": tool, "args": args}
             if state is not None:
                 body_out["state"] = state
+            if plan_id is not None:
+                body_out["plan_id"] = plan_id
             r = self._post("/issue", body_out)
         except Exception as exc:
             if type(exc).__name__ == "LoginRequired":
@@ -167,6 +170,19 @@ class IssuerClient:
             return {"envelope": None, "reason": body.get("reason") or REF_TARGET_ISSUER_UNAVAILABLE}
         return {"envelope": body.get("envelope"), "reason": None}
 
+    def plan(self, target_url: str, steps: List[Dict[str, Any]], note: str) -> Dict[str, Any]:
+        """Ask for a scoped grant: {"plan": signed plan, "held": bool} or
+        {"plan": None, "reason": ...}."""
+        try:
+            r = self._post("/plans", {"target_url": target_url, "steps": steps, "note": note})
+            body = r.json() if r.status_code == 200 else {}
+        except Exception as exc:
+            sys.stderr.write("gargoyle: issuer unreachable for a plan: %s\n" % exc)
+            return {"plan": None, "reason": REF_TARGET_ISSUER_UNAVAILABLE}
+        if not body.get("issued"):
+            return {"plan": None, "reason": body.get("reason") or REF_TARGET_ISSUER_UNAVAILABLE}
+        return {"plan": body["plan"], "held": bool(body.get("held")), "reason": None}
+
     def approver_keys(self) -> Dict[str, Any]:
         """The issuer's enrolled approvers as {upn: public key}; {} when the
         issuer cannot be reached (the static map then stands alone)."""
@@ -331,6 +347,7 @@ class ServerState:
                 executor_key_id=config.get("executor_key_id"),
             )
         self.executed: List[Dict[str, Any]] = []
+        self.plans: List[Dict[str, Any]] = []     # approved scoped grants: {"plan", "grants", "consumed": set()}
         self.initialized = False
         self.client: Optional[str] = None     # "name version" from the MCP initialize handshake
 
@@ -368,15 +385,24 @@ def _gate(state: ServerState, params: Dict[str, Any]) -> Dict[str, Any]:
         # target's current state goes with the request (gargoyle.state), so
         # a hold is approved against it and bound to it.
         probed = state.adapter.probe(name, args) if state.adapter is not None else None
-        res = state.issuer_client.issue(state.config["target_id"], name, args, state=probed[0] if probed else None)
+        # An approved plan may already cover this call; say so, and the
+        # issuer opens no hold for it.
+        release = _plan_release_for(state, name, args)
+        res = state.issuer_client.issue(state.config["target_id"], name, args, state=probed[0] if probed else None,
+                                        plan_id=release["plan"]["plan_id"] if release else None)
         if res["envelope"] is None:
             return refused(res["reason"])
         envelope, self_issued = res["envelope"], True
         if isinstance(envelope, dict) and envelope.get("requires_approval") is True and grant is None:
-            waited = state.issuer_client.wait_for_grant(str(envelope.get("approval_request_id")))
-            if waited["grant"] is None:
-                return refused(waited["reason"], envelope)
-            grant = waited["grant"]
+            # A scoped grant the human already signed may cover this call;
+            # otherwise wait for a card of its own.
+            if release is None:
+                waited = state.issuer_client.wait_for_grant(str(envelope.get("approval_request_id")))
+                if waited["grant"] is None:
+                    return refused(waited["reason"], envelope)
+                grant = waited["grant"]
+            else:
+                grant = release
 
     # 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.
@@ -386,10 +412,19 @@ def _gate(state: ServerState, params: Dict[str, Any]) -> Dict[str, Any]:
         from gargoyle.state import state_sha256 as _state_hash
         now_probe = state.adapter.probe(name, args)
         live_state = _state_hash(now_probe[0]) if now_probe is not None else None
-    verdict = state.consumer.check(envelope, call_for(name, args, state.config["principal"], live_state),
-                                   grant=grant)
+    from gargoyle.plans import is_plan_release
+    if is_plan_release(grant):
+        verdict = state.consumer.check(envelope, call_for(name, args, state.config["principal"], live_state),
+                                       plan_release=grant)
+    else:
+        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)
+    if is_plan_release(grant):
+        for active in state.plans:
+            if active["plan"]["plan_id"] == grant["plan"]["plan_id"]:
+                active["consumed"].add(grant["step"])
 
     # Undo material: for a held, state-bound call, keep the target as it is
     # right now (the state the receipt bound and the check just confirmed).
@@ -405,6 +440,61 @@ def _gate(state: ServerState, params: Dict[str, Any]) -> Dict[str, Any]:
             "self_issued": self_issued}
 
 
+def _plan_release_for(state: ServerState, tool: str, args: Any) -> Optional[Dict[str, Any]]:
+    """The release record for the first active plan with an unconsumed step
+    matching this call, or None."""
+    from datetime import datetime, timezone
+    from gargoyle.plans import match_step
+    now = datetime.now(timezone.utc)
+    for active in state.plans:
+        plan = active["plan"]
+        try:
+            if datetime.fromisoformat(plan["not_after"]) <= now:
+                continue
+        except (ValueError, TypeError):
+            continue
+        i = match_step(plan, tool, args, active["consumed"])
+        if i is not None:
+            return {"plan": plan, "grants": active["grants"], "step": i, "args": args}
+    return None
+
+
+PLAN_TOOL = "gargoyle_plan"
+PLAN_TOOL_DEF = {
+    "name": PLAN_TOOL,
+    "description": ("Ask the approver for one approval covering a bounded plan of changes instead of one card per "
+                    "change. steps: a list of {tool, args} (exact) or {tool, match: {argument: glob}}; note: what the "
+                    "plan is for, shown to the approver. Each later call matching an unused step runs without its "
+                    "own card, until the plan expires. Tools the policy keeps individual are refused here."),
+    "inputSchema": {"type": "object", "required": ["steps"],
+                    "properties": {"steps": {"type": "array"}, "note": {"type": "string"}}},
+}
+
+
+def _handle_plan(state: ServerState, params: Dict[str, Any]) -> Dict[str, Any]:
+    """gargoyle_plan: obtain the signed plan, wait for the human's grant,
+    then keep it active for matching calls."""
+    if state.issuer_client is None or state.consumer is None:
+        return {"content": [{"type": "text", "text": "refused: plans need self-issue mode"}], "isError": True,
+                "_meta": {EXECUTED_META_KEY: False, REASON_META_KEY: REF_TARGET_NOT_CONFIGURED}}
+    args = params.get("arguments") or {}
+    res = state.issuer_client.plan(state.config["target_id"], args.get("steps") or [], str(args.get("note") or ""))
+    if res["plan"] is None:
+        return {"content": [{"type": "text", "text": "refused: " + str(res["reason"])}], "isError": True,
+                "_meta": {EXECUTED_META_KEY: False, REASON_META_KEY: res["reason"]}}
+    plan, grants = res["plan"], []
+    if res["held"]:
+        waited = state.issuer_client.wait_for_grant(plan["approval_request_id"])
+        if waited["grant"] is None:
+            return {"content": [{"type": "text", "text": "refused: " + str(waited["reason"])}], "isError": True,
+                    "_meta": {EXECUTED_META_KEY: False, REASON_META_KEY: waited["reason"]}}
+        grants = waited["grant"] if isinstance(waited["grant"], list) else [waited["grant"]]
+    state.plans.append({"plan": plan, "grants": grants, "consumed": set()})
+    text = "plan %s approved: %d step(s) until %s" % (plan["plan_id"][:8], len(plan["steps"]), plan["not_after"])
+    return {"content": [{"type": "text", "text": text}], "isError": False,
+            "_meta": {EXECUTED_META_KEY: False, REASON_META_KEY: "PLAN_APPROVED", "gargoyle/plan": plan}}
+
+
 def _audit_meta(state: ServerState, gate: Dict[str, Any], outputs: Any, params: Dict[str, Any]) -> Dict[str, Any]:
     """What an honored result's _meta carries beyond executed/reason: the
     execution receipt when this server attests, and, when the receipt was
@@ -484,6 +574,9 @@ def handle_message(state: ServerState, msg: Dict[str, Any]) -> Optional[Dict[str
                 and isinstance(reply.get("result"), dict) and isinstance(reply["result"].get("tools"), list):
             from gargoyle.revert import REVERT_TOOL_DEF
             reply["result"]["tools"] = list(reply["result"]["tools"]) + [REVERT_TOOL_DEF]
+        if method == "tools/list" and state.issuer_client is not None and isinstance(reply, dict) \
+                and isinstance(reply.get("result"), dict) and isinstance(reply["result"].get("tools"), list):
+            reply["result"]["tools"] = list(reply["result"]["tools"]) + [PLAN_TOOL_DEF]
         return reply
 
     if method == "initialize":
@@ -524,10 +617,13 @@ def handle_message(state: ServerState, msg: Dict[str, Any]) -> Optional[Dict[str
 
     if method == "tools/list":
         from gargoyle.revert import REVERT_TOOL_DEF
-        return _success(msg_id, {"tools": ADVERTISED_TOOLS + ([REVERT_TOOL_DEF] if state.snapshots is not None else [])})
+        return _success(msg_id, {"tools": ADVERTISED_TOOLS + ([REVERT_TOOL_DEF] if state.snapshots is not None else [])
+                                 + ([PLAN_TOOL_DEF] if state.issuer_client is not None else [])})
 
     if method == "tools/call":
         from gargoyle.revert import REVERT_TOOL, plan_revert
+        if params.get("name") == PLAN_TOOL:
+            return _success(msg_id, _handle_plan(state, params))
         if params.get("name") == REVERT_TOOL:
             # An undo is a write the middleware composes from its snapshot; it
             # then goes through the gate exactly as the assistant's own writes.