gargoyle-receipts 0.14.2.dev0__tar.gz → 0.15.0.dev0__tar.gz

{gargoyle_receipts-0.14.2.dev0/gargoyle_receipts.egg-info → gargoyle_receipts-0.15.0.dev0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gargoyle-receipts
-Version: 0.14.2.dev0
+Version: 0.15.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.14.2.dev0`, on PyPI as `gargoyle-receipts`). The wire format is `gargoyle/3` and may
+Status: pre-release (`0.15.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
@@ -383,6 +383,7 @@ cannot attach receipts work unchanged. Configuration is by environment:
 | issuer `GARGOYLE_WITNESS_PATH` | the issuer's signed, hash-chained record of every decision (`gargoyle issuer` sets `witness.jsonl` beside the keys); `gargoyle audit --witness` reconciles a client's evidence against it, `--check-tree DIR` finds files changed outside the gate |
 | issuer `GARGOYLE_LOG_JSON` | one JSON line per decision on stderr: issued, refused, granted, declined, plan, enrolled |
 | `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_INSTRUCTIONS` | replaces the standing instructions the gate hands the model in the MCP handshake (default: all work on the target goes through these tools, a wait is normal, a refusal is final, plans and undo exist); the user never has to name the server |
 | `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_receipts-0.14.2.dev0 → gargoyle_receipts-0.15.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.14.2.dev0`, on PyPI as `gargoyle-receipts`). The wire format is `gargoyle/3` and may
+Status: pre-release (`0.15.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
@@ -345,6 +345,7 @@ cannot attach receipts work unchanged. Configuration is by environment:
 | issuer `GARGOYLE_WITNESS_PATH` | the issuer's signed, hash-chained record of every decision (`gargoyle issuer` sets `witness.jsonl` beside the keys); `gargoyle audit --witness` reconciles a client's evidence against it, `--check-tree DIR` finds files changed outside the gate |
 | issuer `GARGOYLE_LOG_JSON` | one JSON line per decision on stderr: issued, refused, granted, declined, plan, enrolled |
 | `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_INSTRUCTIONS` | replaces the standing instructions the gate hands the model in the MCP handshake (default: all work on the target goes through these tools, a wait is normal, a refusal is final, plans and undo exist); the user never has to name the server |
 | `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_receipts-0.14.2.dev0 → gargoyle_receipts-0.15.0.dev0}/gargoyle/mcp_server.py

@@ -100,6 +100,7 @@ ENV_POLL_SECONDS = "GARGOYLE_MCP_POLL_SECONDS"
 ENV_AUDIT_LOG = "GARGOYLE_MCP_AUDIT_LOG"
 ENV_STATE_PROBE = "GARGOYLE_MCP_STATE_PROBE"
 ENV_ADAPTER_SPEC = "GARGOYLE_MCP_ADAPTER_SPEC"    # with GARGOYLE_MCP_STATE_PROBE=graph: the tool mapping JSON
+ENV_INSTRUCTIONS = "GARGOYLE_MCP_INSTRUCTIONS"   # override the standing instructions the gate gives the model (default: gate_instructions())
 ENV_SNAPSHOT_DIR = "GARGOYLE_MCP_SNAPSHOT_DIR"   # where pre-change snapshots live (default: snapshots/ beside the audit log); "none" disables undo   # "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
 
@@ -284,6 +285,26 @@ def _without_gargoyle_meta(params: Dict[str, Any]) -> Dict[str, Any]:
     return forwarded
 
 
+def gate_instructions(target_id: str, upstream_instructions: Optional[str] = None, override: Optional[str] = None) -> str:
+    """The standing instructions an MCP server may hand the model in its
+    initialize answer; clients place them in the model's context for the
+    session. This is how the gate is mandated rather than named by the
+    user each time: the model is told, by the server itself, that all work
+    on this target goes through these tools, that a refusal is final, and
+    that there is nothing to type. The upstream's own instructions, if
+    any, follow the gate's."""
+    text = override if override else (
+        "Every operation on %s goes through this server's tools; do not use any other tool, built-in "
+        "capability or workaround for that target. Reads run at once. A write may pause for a human "
+        "approval: wait for the result, it is normal. A refused call is a decision, not an error: report "
+        "the reason to the user and stop; do not retry or route around it. For a task with several "
+        "writes, gargoyle_plan may ask for one approval covering them; gargoyle_revert undoes an approved "
+        "change through the same approval. The user never needs to name this server." % target_id)
+    if upstream_instructions:
+        text += "\n\n" + upstream_instructions
+    return text
+
+
 def client_label(params: Any) -> Optional[str]:
     """"name version" from an initialize request's clientInfo, or None."""
     info = params.get("clientInfo") if isinstance(params, dict) else None
@@ -348,6 +369,8 @@ class ServerState:
             )
         self.executed: List[Dict[str, Any]] = []
         self.plans: List[Dict[str, Any]] = []     # approved scoped grants: {"plan", "grants", "consumed": set()}
+        import os as _os
+        self.instructions: Optional[str] = _os.environ.get(ENV_INSTRUCTIONS) or None
         self.initialized = False
         self.client: Optional[str] = None     # "name version" from the MCP initialize handshake
 
@@ -576,6 +599,9 @@ def handle_message(state: ServerState, msg: Dict[str, Any]) -> Optional[Dict[str
         if method == "initialize":
             state.client = client_label(params)
         reply = _relay(state, msg)
+        if method == "initialize" and isinstance(reply, dict) and isinstance(reply.get("result"), dict) and state.config:
+            reply["result"]["instructions"] = gate_instructions(state.config.get("target_id", "the gated target"),
+                                                                reply["result"].get("instructions"), state.instructions)
         if method == "tools/list" and state.snapshots is not None and isinstance(reply, dict) \
                 and isinstance(reply.get("result"), dict) and isinstance(reply["result"].get("tools"), list):
             from gargoyle.revert import REVERT_TOOL_DEF
@@ -595,6 +621,7 @@ def handle_message(state: ServerState, msg: Dict[str, Any]) -> Optional[Dict[str
                 "protocolVersion": PROTOCOL_VERSION,
                 "capabilities": {"tools": {"listChanged": False}},
                 "serverInfo": SERVER_INFO,
+                "instructions": gate_instructions((state.config or {}).get("target_id", "the gated target"), None, state.instructions),
             },
         )
 

{gargoyle_receipts-0.14.2.dev0 → gargoyle_receipts-0.15.0.dev0}/gargoyle/remote.py

@@ -168,6 +168,10 @@ def build_remote_app(
             upstream_init["serverInfo"] = {"name": "gargoyle+" + str(upstream_init.get("serverInfo", {}).get("name", "upstream")),
                                            "version": SERVER_INFO["version"]}
         upstream.send({"jsonrpc": "2.0", "method": "notifications/initialized"})
+    from gargoyle.mcp_server import gate_instructions
+    import os as _os
+    upstream_init["instructions"] = gate_instructions(config.get("target_id", "the gated target"), upstream_init.get("instructions"),
+                                                      _os.environ.get("GARGOYLE_MCP_INSTRUCTIONS") or None)
 
     def new_state(principal: str, issuer_token: str) -> ServerState:
         nonlocal shared_evidence, shared_snapshots

{gargoyle_receipts-0.14.2.dev0 → gargoyle_receipts-0.15.0.dev0/gargoyle_receipts.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gargoyle-receipts
-Version: 0.14.2.dev0
+Version: 0.15.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.14.2.dev0`, on PyPI as `gargoyle-receipts`). The wire format is `gargoyle/3` and may
+Status: pre-release (`0.15.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
@@ -383,6 +383,7 @@ cannot attach receipts work unchanged. Configuration is by environment:
 | issuer `GARGOYLE_WITNESS_PATH` | the issuer's signed, hash-chained record of every decision (`gargoyle issuer` sets `witness.jsonl` beside the keys); `gargoyle audit --witness` reconciles a client's evidence against it, `--check-tree DIR` finds files changed outside the gate |
 | issuer `GARGOYLE_LOG_JSON` | one JSON line per decision on stderr: issued, refused, granted, declined, plan, enrolled |
 | `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_INSTRUCTIONS` | replaces the standing instructions the gate hands the model in the MCP handshake (default: all work on the target goes through these tools, a wait is normal, a refusal is final, plans and undo exist); the user never has to name the server |
 | `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_receipts-0.14.2.dev0 → gargoyle_receipts-0.15.0.dev0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "gargoyle-receipts"
-version = "0.14.2.dev0"
+version = "0.15.0.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.14.2.dev0 → gargoyle_receipts-0.15.0.dev0}/tests/test_mcp_self_issue.py

@@ -229,3 +229,27 @@ def test_every_decision_lands_in_the_evidence_log(tmp_path):
                    approver_public_keys={"approver-alice": approver.public_key()})
     assert v["accepted"] and (v["honored"], v["refused"]) == (1, 2)
     assert [r["reason"] for r in v["entries"]] == [ACCEPT_CHAIN_VERIFIED, ACCEPT_ENTRY_VERIFIED, ACCEPT_ENTRY_VERIFIED]
+
+
+def test_the_gate_hands_the_model_standing_instructions(monkeypatch):
+    """The initialize answer carries instructions in both modes, so the user
+    never has to name the server; an operator may override the text."""
+    from gargoyle.mcp_server import gate_instructions
+    client = TestClient(issuer_app())
+    state = middleware(client)
+    r = handle_message(state, {"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {}})
+    text = r["result"]["instructions"]
+    assert TARGET in text and "do not use any other tool" in text and "gargoyle_plan" in text and "never needs to name this server" in text
+    # Through a real upstream, the upstream's own instructions follow the gate's.
+    fixture = str(Path(__file__).parent / "fixtures" / "echo_mcp_server.py")
+    up = StdioUpstream([sys.executable, "-I", fixture])
+    try:
+        state = middleware(client); state.upstream = up
+        r = handle_message(state, {"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {}})
+        assert r["result"]["instructions"].startswith("Every operation on " + TARGET)
+    finally:
+        up.close()
+    monkeypatch.setenv("GARGOYLE_MCP_INSTRUCTIONS", "House rule: files only.")
+    state = middleware(client)
+    assert handle_message(state, {"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {}})["result"]["instructions"] == "House rule: files only."
+    assert gate_instructions("t", "Upstream says hi").endswith("Upstream says hi")

{gargoyle_receipts-0.14.2.dev0 → gargoyle_receipts-0.15.0.dev0}/tests/test_remote.py

@@ -79,6 +79,7 @@ def test_remote_gate_over_stdio_upstream(tmp_path):
         assert r.status_code == 200 and r.headers[SESSION_HEADER]
         sid = r.headers[SESSION_HEADER]
         assert r.json()["result"]["serverInfo"]["name"].startswith("gargoyle+")
+        assert "do not use any other tool" in r.json()["result"]["instructions"]
         assert rpc(c, alice, {"jsonrpc": "2.0", "method": "notifications/initialized"}, sid).status_code == 202
         # Tools: the upstream's plus undo.
         tools = rpc(c, alice, {"jsonrpc": "2.0", "id": 2, "method": "tools/list", "params": {}}, sid).json()["result"]["tools"]