@odingard/guardian-mcp 0.3.3 → 0.4.0

package/README.md

@@ -39,6 +39,18 @@ npm i -g @odingard/guardian-mcp
 
 Nothing executes without a Guardian capability — the model's output is a proposal, never an action.
 
+Only a call whose receipt status is `sent-verified` is returned as a plain
+result. Every other outcome is an MCP tool error (`isError: true`) that says
+what happened:
+
+- DENY, or Guardian could not be reached: nothing was done. A denial says not
+  to retry the same call; an outage says to try again later.
+- Receipt status `not-sent`: `outcome: "not-done"`, the call was not done.
+- Receipt status `outcome-pending` or `outcome-unconfirmed`, or an execute
+  answer that was refused or lost: `outcome: "unknown"`. The call may have
+  been done, so check (`guardian_receipt`, or the target system) before
+  retrying.
+
 ## Govern an existing MCP server: `guardian-mcp proxy` (0.3)
 
 Put Guardian in front of any stdio MCP server you already use, such as
@@ -62,11 +74,12 @@ upstream server's tools unchanged, and every call is decided first:
 }
 ```
 
-| Decision  | What happens                                                                                                                                 |
-| --------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
-| **ALLOW** | The call is forwarded to the upstream server, then the capability is redeemed and the receipt recorded.                                      |
-| **ASK**   | Nothing is forwarded. The exact call is held under a `requestId`; after a human approves, `guardian_claim` forwards exactly that call, once. |
-| **DENY**  | Nothing is forwarded, ever. The same applies if Guardian is unreachable.                                                                     |
+| Decision                 | What happens                                                                                                                                                                                                                                                                                           |
+| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| **ALLOW**                | The call is forwarded to the upstream server, then the capability is redeemed and the receipt recorded. The upstream result is returned unchanged, with Guardian's `requestId` under `_meta["com.odingard/guardian"]`, so the client can fetch the receipt with `guardian_receipt`.                    |
+| **ASK**                  | Nothing is forwarded. The exact call is held under a `requestId`; after a human approves, `guardian_claim` forwards exactly that call, once.                                                                                                                                                           |
+| **DENY**                 | Nothing is forwarded, ever. The result is an MCP tool error (`isError: true`) with the reason code and, when Guardian made a record of it, the `requestId`.                                                                                                                                            |
+| **Guardian unreachable** | Nothing is forwarded. The result is a tool error (`isError: true`) whose JSON keeps `decision: "DENY"` with `reasonCode: "SERVICE_UNAVAILABLE"`, and its message says Guardian could not be reached and the call can be tried again later. A held call stays held, so `guardian_claim` can be retried. |
 
 - `guardian_claim` and `guardian_receipt` are added to the tool list.
 - The upstream server never receives `GUARDIAN_*` settings, so it never sees
@@ -79,20 +92,59 @@ upstream server's tools unchanged, and every call is decided first:
   for the agent.
   - Since 0.3.1 the proxy does not try to register tools itself.
   - `GUARDIAN_AUTO_REGISTER=true` turns that back on, but it is denied unless
-    the agent's grant pins `mcp.install`.
+    the agent's grant pins `mcp.install`, and it only works for a tool that
+    has no entry yet. An "already registered" answer is refused
+    (`RECORD_TRANSPORT_UNVERIFIED`) and nothing is forwarded, including after
+    a proxy restart for an entry the proxy created itself. Once the entries
+    exist, run the proxy without it.
   - When Guardian refuses, the result says what to fix.
 - Held calls live in the proxy process. Restarting the proxy drops them, and
   nothing is forwarded.
+- **Cancelled requests are not forwarded.** If the client cancels a
+  `tools/call` (or it times out) before the call is sent upstream, for
+  example while Guardian is still deciding, the call is not forwarded and the
+  capability is not redeemed. A `guardian_claim` cancelled that way keeps the
+  call held with its approval, so the next `guardian_claim` forwards it
+  without asking the person again. Once a call has been sent upstream it runs
+  to its real outcome, which is recorded.
+- **A second `guardian_claim` of the same `requestId`** says the call was
+  already forwarded and must not be proposed again. If the first claim has
+  finished, its result is returned again after that notice; if it is still
+  running, the answer says to check `guardian_receipt`. The proxy remembers
+  the last 1000 claimed requests. A `requestId` it does not hold is answered
+  with "this claim forwarded nothing", and a reminder to check
+  `guardian_receipt` if it was claimed before.
+- An unexpected proxy error after a call was forwarded says the call may
+  have run, never that it was not forwarded.
 
 `guardian-mcp --help` prints usage. A missing setting prints a one-line
 message naming it instead of a stack trace.
 
-## Govern a remote MCP server: `guardian-mcp proxy --url` (unreleased)
+### Pin the contents of file arguments: `--pin-file` (0.4)
+
+Approval binds the exact arguments. A file path is an argument; the file's contents are not, unless you declare the argument with `--pin-file`.
+
+```bash
+guardian-mcp proxy --pin-file upload_file:path --pin-file send_email:attachment -- npx -y my-mcp-server
+```
+
+For each declared `<tool>:<argument>` the proxy (the SDK on your machine) reads the file the path names, puts its SHA-256 in the approved arguments, and checks it again just before the call is forwarded. Guardian's servers never see the file. If the file changed, nothing is forwarded, the capability is not redeemed, and the result says `CONTENT_CHANGED_SINCE_APPROVAL`; propose the call again for a new approval. A call held for approval keeps the arguments that were proposed, pins included, and `guardian_claim` checks the file against them. After a proxy restart a claim finds nothing; call the tool again, which pins the file again. The upstream server receives the approved arguments without the reserved key `guardianContentPins`. In code: `createGovernedProxy({ ..., pinFiles: { upload_file: ["path"] } })`.
+
+- The mode is always `recheck`: the upstream server opens the path itself, so a short window remains between the check and its open.
+- Stdio upstreams only. With `--url` (HTTP or SSE) the path names a file on another machine, so `--pin-file` is refused at start (`CONTENT_PIN_REMOTE_UPSTREAM`). Paths on a remote MCP server are not pinned.
+- File paths must be absolute. The proxy does not resolve relative paths or `~`.
+- Content pinning is supported on Linux and macOS. On Windows a declared file argument is refused (`CONTENT_PIN_UNSUPPORTED_PLATFORM`).
+- **Digest privacy:** the SHA-256 of each pinned file is sent to Guardian, shown to the approver and kept in receipts. For a small or low-entropy file (a token, a PIN, a short config value), anyone who sees the digest can guess the contents offline by hashing candidates. Do not pin files like that, or treat the digest as sensitive as the file.
+- This stops a changed file from running under an approval given for different contents. It does not protect against code that bypasses the proxy, and files a tool opens without naming them in a declared argument are not pinned.
+
+## Govern a remote MCP server: `guardian-mcp proxy --url` (0.3.3 and later)
 
-**Status: not yet proven live.** This is tested against local Streamable
-HTTP and SSE MCP servers and a fake Guardian only. Nothing has run against a
-real Guardian or a real hosted server such as Composio. Composio's
-`x-api-key` header is unconfirmed.
+**Status: tested against a real Guardian; production proof pending.** It ran
+end to end over Streamable HTTP against the real Guardian server code (allow,
+ask then approve, deny, outage), not yet on hosted production. SSE is tested
+against local servers and a stand-in Guardian only, and no real hosted server
+such as Composio has been tried. Composio's `x-api-key` header is
+unconfirmed.
 
 The proxy can also front an MCP server that runs online, such as Composio.
 The agent still starts `guardian-mcp` over stdio like any
@@ -157,7 +209,8 @@ A server that takes a Bearer key: `--url https://mcp.example.com/mcp --header
   unavailable" error. The upstream's error text (which can quote its URL
   path, response body or headers) is not shown to the agent or logged;
   `guardian-mcp tools --url` prints it with the URL, its path identifiers,
-  query values and header values scrubbed.
+  query values and header values scrubbed. Each query value is scrubbed as
+  typed (a `+` stays a `+`), percent-decoded, and with `+` read as a space.
 
 What is **not** governed: a remote server the agent connects to directly
 (for example an MCP client's own `"url"` entry, or a model provider's hosted
@@ -175,9 +228,8 @@ MCP connector), and anything the agent does without MCP. Also not covered:
   [ZeroClaw](../../examples/zeroclaw/README.md) and
   [your own container (CrewAI, LangGraph, AutoGen)](../../examples/byo/README.md).
   Runnable example: `examples/remote-mcp.mjs` (SIMULATED by default, LIVE with
-  Guardian settings). It runs inside this repository, where the workspace
-  links the unreleased guardian-mcp; the published `@odingard/guardian-mcp`
-  0.3.2 does not have `--url` yet.
+  Guardian settings). `--url` is in the published `@odingard/guardian-mcp`
+  from 0.3.3.
 
 ## See what you are about to govern: `guardian-mcp tools`
 
@@ -197,8 +249,10 @@ createIssue     Ask me first  "create" may change something  ⚠ name not accept
 
 How the suggestions are made:
 
-- The server's own MCP annotations (`readOnlyHint`, `destructiveHint`) are used first.
-- Otherwise the tool's verb decides. `get`, `list` and `search` suggest Allow; everything else suggests Ask.
+- A tool the server marks destructive (`destructiveHint`) suggests Ask.
+- So does a tool whose name contains a verb that changes something or sends data out, anywhere in the name (`create`, `update`, `delete`, `replace`, `send`, `run`, `write` and similar), even when the server marks it read-only. `get_or_create_customer`, `find_and_replace` and `list_and_delete_old_files` suggest Ask.
+- Otherwise a tool the server marks read-only (`readOnlyHint`) suggests Allow, and so does a name that starts with a read verb (`get`, `list`, `search`, `read`, `describe`, `show`, `view`, `find`, `lookup`, `count`, `inspect`).
+- Everything else suggests Ask, including `fetch` (it can send data to any URL) and `status`.
 
 They are suggestions only: you set the real modes in the console. Tool names that break Guardian's naming rule are flagged, because every call to them would be denied. Add `--json` for machine-readable output.
 

package/dist/index.js

@@ -16,6 +16,11 @@ var USAGE = `guardian-mcp \u2014 route an agent's tool calls through Guardian (A
 Usage:
   guardian-mcp                               Guardian tools (guardian_invoke_tool, guardian_claim, guardian_receipt)
   guardian-mcp proxy -- <command> [args...]  Govern every tool of an existing stdio MCP server
+  guardian-mcp proxy --pin-file <tool>:<arg> [--pin-file ...] -- <command> [args...]
+                                             Also pin the file a path argument names: its SHA-256
+                                             goes into the approved arguments and is checked again
+                                             just before the call is forwarded (stdio upstreams
+                                             only; the path must be absolute)
   guardian-mcp proxy --url <https-url> [--transport streamable-http|sse] [--header "Name: value"]...
                                              Govern every tool of a remote MCP server (Streamable
                                              HTTP by default, or SSE). The agent still talks stdio.
@@ -64,9 +69,24 @@ function parseCli(argv, env) {
     };
   }
   if (argv[0] === "proxy") {
-    const target = parseTarget("proxy", argv.slice(1), env);
+    const pins = extractPinFiles(argv.slice(1));
+    if (!pins.ok) return pins;
+    const target = parseTarget("proxy", pins.rest, env);
     if (!target.ok) return target;
-    mode = { kind: "proxy", ...target.target };
+    const declared = Object.keys(pins.pinFiles).length > 0;
+    if (declared && "remote" in target.target) {
+      return {
+        ok: false,
+        message: `guardian-mcp proxy: --pin-file is supported only for a stdio upstream (CONTENT_PIN_REMOTE_UPSTREAM). A remote MCP server opens paths on another machine, so the proxy cannot check the file it will read.
+
+${USAGE}`
+      };
+    }
+    mode = {
+      kind: "proxy",
+      ...target.target,
+      ...declared ? { pinFiles: pins.pinFiles } : {}
+    };
   } else if (argv.length > 0) {
     return {
       ok: false,
@@ -135,6 +155,42 @@ function expandEnv(cmd, value, env, where) {
     value: value.replace(ENV_REF, (_, name) => env[name])
   };
 }
+function extractPinFiles(argv) {
+  const pinFiles = {};
+  const rest = [];
+  const fail = (message) => ({
+    ok: false,
+    message: `guardian-mcp proxy: ${message}
+
+${USAGE}`
+  });
+  let i = 0;
+  for (; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "--") break;
+    let value;
+    if (arg === "--pin-file") {
+      value = argv[++i];
+    } else if (arg.startsWith("--pin-file=")) {
+      value = arg.slice("--pin-file=".length);
+    } else {
+      rest.push(arg);
+      continue;
+    }
+    const colon = value?.lastIndexOf(":") ?? -1;
+    const tool = colon > 0 ? value.slice(0, colon) : "";
+    const name = colon > 0 ? value.slice(colon + 1) : "";
+    if (!tool || !name || name.includes(".")) {
+      return fail(
+        '--pin-file needs "<tool>:<argument>", naming a top-level argument.'
+      );
+    }
+    const list = pinFiles[tool] ??= [];
+    if (!list.includes(name)) list.push(name);
+  }
+  rest.push(...argv.slice(i));
+  return { ok: true, pinFiles, rest };
+}
 function parseTarget(cmd, argv, env) {
   const fail = (message) => ({
     ok: false,
@@ -235,6 +291,18 @@ function secretsOf(target) {
   const parsed2 = new URL(url);
   if (parsed2.search) out.add(parsed2.search.slice(1));
   for (const v of parsed2.searchParams.values()) if (v.length >= 4) out.add(v);
+  for (const pair of parsed2.search.slice(1).split("&")) {
+    const raw = pair.slice(pair.indexOf("=") + 1);
+    if (pair.indexOf("=") < 0 || raw.length < 4) continue;
+    const forms = [raw, raw.replace(/\+/g, " ")];
+    for (const form of [...forms]) {
+      try {
+        forms.push(decodeURIComponent(form));
+      } catch {
+      }
+    }
+    for (const form of forms) if (form.length >= 4) out.add(form);
+  }
   for (const segment of parsed2.pathname.split("/")) {
     if (segment.length >= 16 || segment.length >= 8 && /\d/.test(segment)) {
       out.add(segment);
@@ -308,11 +376,26 @@ var TOOLS = [
   }
 ];
 function jsonResult(payload) {
-  return { content: [{ type: "text", text: JSON.stringify(payload, null, 2) }] };
+  return {
+    content: [{ type: "text", text: JSON.stringify(payload, null, 2) }]
+  };
 }
 function errorResult(message) {
   return { isError: true, content: [{ type: "text", text: message }] };
 }
+function jsonError(payload) {
+  return { ...jsonResult(payload), isError: true };
+}
+var CHECK_FIRST = "Call guardian_receipt with this requestId, or check the target system, before retrying.";
+function denied(reasonCode, requestId) {
+  const code = reasonCode ?? "DENIED";
+  return jsonError({
+    decision: "DENY",
+    reasonCode: code,
+    ...requestId ? { requestId } : {},
+    message: code === "SERVICE_UNAVAILABLE" ? "Guardian could not be reached, so nothing was done. Try again later." : "Guardian denied this call. Nothing was done. Do not retry the same call."
+  });
+}
 async function requestAndExecute(client2, result) {
   if (!result.ok) {
     const heldRequestId = result.requestId;
@@ -324,33 +407,62 @@ async function requestAndExecute(client2, result) {
         next: "Held for human approval. Call guardian_claim with this requestId after approval."
       });
     }
-    return jsonResult({ decision: "DENY", reasonCode: result.reasonCode });
+    return denied(
+      result.reasonCode,
+      typeof heldRequestId === "string" && heldRequestId.length > 0 ? heldRequestId : void 0
+    );
   }
   if (result.decision === "ALLOW" && result.capabilityToken) {
     const executed = await client2.execute({
       requestId: result.requestId,
       capabilityToken: result.capabilityToken
     });
-    return jsonResult(
-      executed.ok ? {
+    if (!executed.ok) {
+      return jsonError({
+        decision: "ALLOW",
+        requestId: result.requestId,
+        outcome: "unknown",
+        executionFailed: executed.reasonCode,
+        message: `Guardian could not confirm the outcome (${executed.reasonCode}). The call may have been done. ${CHECK_FIRST}`
+      });
+    }
+    const status = executed.receipt?.status;
+    if (status === "sent-verified") {
+      return jsonResult({
         decision: "ALLOW",
         requestId: result.requestId,
         receipt: executed.receipt
-      } : {
+      });
+    }
+    if (status === "not-sent") {
+      return jsonError({
         decision: "ALLOW",
         requestId: result.requestId,
-        executionFailed: executed.reasonCode
-      }
-    );
+        outcome: "not-done",
+        receipt: executed.receipt,
+        message: "Guardian did not send the call (receipt status not-sent). It was not done."
+      });
+    }
+    return jsonError({
+      decision: "ALLOW",
+      requestId: result.requestId,
+      outcome: "unknown",
+      receipt: executed.receipt,
+      message: `The outcome is unknown (receipt status ${typeof status === "string" ? status : "missing"}). The call may have been done. ${CHECK_FIRST}`
+    });
   }
-  return jsonResult({
-    decision: result.decision,
-    requestId: result.requestId,
-    ...result.reasonCode ? { reasonCode: result.reasonCode } : {},
-    ...result.decision === "ASK" ? {
+  if (result.decision === "ASK") {
+    return jsonResult({
+      decision: "ASK",
+      requestId: result.requestId,
+      ...result.reasonCode ? { reasonCode: result.reasonCode } : {},
       message: "Held for human approval. Call guardian_claim with this requestId after approval."
-    } : {}
-  });
+    });
+  }
+  return denied(
+    result.reasonCode ?? (result.decision === "DENY" ? void 0 : "MISSING_CAPABILITY"),
+    result.requestId
+  );
 }
 async function handleToolCall(options, name, arguments_) {
   const { client: client2, defaultConnectionId, adapterId } = options;
@@ -410,12 +522,85 @@ var READ_VERBS = /* @__PURE__ */ new Set([
   "find",
   "lookup",
   "count",
-  "inspect",
-  "status",
-  "fetch"
+  "inspect"
+]);
+var WRITE_VERBS = /* @__PURE__ */ new Set([
+  "add",
+  "append",
+  "apply",
+  "approve",
+  "archive",
+  "assign",
+  "buy",
+  "cancel",
+  "charge",
+  "clear",
+  "close",
+  "commit",
+  "copy",
+  "create",
+  "delete",
+  "deploy",
+  "destroy",
+  "disable",
+  "drop",
+  "edit",
+  "enable",
+  "exec",
+  "execute",
+  "fork",
+  "grant",
+  "import",
+  "insert",
+  "install",
+  "invite",
+  "kill",
+  "lock",
+  "merge",
+  "modify",
+  "move",
+  "notify",
+  "patch",
+  "pay",
+  "post",
+  "publish",
+  "purge",
+  "push",
+  "put",
+  "refund",
+  "remove",
+  "rename",
+  "replace",
+  "reply",
+  "reset",
+  "restart",
+  "restore",
+  "revoke",
+  "rm",
+  "run",
+  "save",
+  "schedule",
+  "sell",
+  "send",
+  "set",
+  "share",
+  "sign",
+  "start",
+  "stop",
+  "submit",
+  "sync",
+  "transfer",
+  "trigger",
+  "truncate",
+  "uninstall",
+  "unlock",
+  "update",
+  "upload",
+  "upsert",
+  "write"
 ]);
-function firstWord(name) {
-  return name.replace(/([a-z0-9])([A-Z])/g, "$1_$2").toLowerCase().split(/[^a-z0-9]+/).find(Boolean) ?? "";
+function words(name) {
+  return name.replace(/([a-z0-9])([A-Z])/g, "$1_$2").toLowerCase().split(/[^a-z0-9]+/).filter(Boolean);
 }
 function suggestTool(tool) {
   const governable = GUARDIAN_TOOL_NAME.test(tool.name) && tool.name.length <= 64;
@@ -428,6 +613,16 @@ function suggestTool(tool) {
       governable
     };
   }
+  const tokens = words(tool.name);
+  const writeVerb = tokens.find((token) => WRITE_VERBS.has(token));
+  if (writeVerb) {
+    return {
+      name: tool.name,
+      suggestedMode: "ask",
+      why: `"${writeVerb}" may change something`,
+      governable
+    };
+  }
   if (annotations.readOnlyHint === true) {
     return {
       name: tool.name,
@@ -436,7 +631,7 @@ function suggestTool(tool) {
       governable
     };
   }
-  const verb = firstWord(tool.name);
+  const verb = tokens[0] ?? "";
   if (READ_VERBS.has(verb)) {
     return {
       name: tool.name,
@@ -482,6 +677,8 @@ function renderSuggestions(serverCommand, tools, remote = false) {
 
 // src/proxy.ts
 import {
+  CONTENT_PIN_KEY,
+  CONTENT_PIN_REMOTE_UPSTREAM,
   createGuardianContext,
   runThroughGuardian,
   settle,
@@ -490,8 +687,40 @@ import {
   GuardianExecutionFailed,
   GuardianRecordTransportRequired
 } from "@odingard/guardian-sdk";
+var ContentPinConfigError = class extends Error {
+  constructor(reasonCode, message) {
+    super(message);
+    this.reasonCode = reasonCode;
+    this.name = "ContentPinConfigError";
+  }
+  reasonCode;
+};
+function pinFilesToFileArgs(pinFiles) {
+  const fileArgs = {};
+  for (const [toolName, args] of Object.entries(pinFiles ?? {})) {
+    if (args.length === 0) continue;
+    fileArgs[toolName] = Object.fromEntries(
+      args.map((arg) => [arg, "recheck"])
+    );
+  }
+  return fileArgs;
+}
 var CLAIM_TOOL = "guardian_claim";
 var RECEIPT_TOOL = "guardian_receipt";
+var GUARDIAN_RESULT_META = "com.odingard/guardian";
+var UNAVAILABLE = "SERVICE_UNAVAILABLE";
+function unreachableResult(toolName, requestId) {
+  return jsonResult2(
+    {
+      decision: "DENY",
+      toolName,
+      reasonCode: UNAVAILABLE,
+      ...requestId ? { requestId } : {},
+      message: `Guardian could not be reached, so ${toolName} was not checked and nothing was forwarded. Try again later.`
+    },
+    true
+  );
+}
 var PROXY_GOVERNANCE_TOOLS = [
   {
     name: CLAIM_TOOL,
@@ -518,6 +747,14 @@ function jsonResult2(payload, isError = false) {
     content: [{ type: "text", text: JSON.stringify(payload, null, 2) }]
   };
 }
+function withRequestId(result, requestId) {
+  if (!requestId) return result;
+  const meta = typeof result._meta === "object" && result._meta !== null ? result._meta : {};
+  return {
+    ...result,
+    _meta: { ...meta, [GUARDIAN_RESULT_META]: { requestId } }
+  };
+}
 function isDecisionResult(value) {
   return typeof value === "object" && value !== null && "guardian" in value && typeof value.guardian === "object";
 }
@@ -533,6 +770,14 @@ var UPSTREAM_RESULT = /* @__PURE__ */ Symbol("guardian-mcp.upstreamResult");
 function upstreamRan(value) {
   return typeof value === "object" && value !== null && Object.prototype.hasOwnProperty.call(value, UPSTREAM_RESULT);
 }
+var UpstreamCallCancelled = class extends Error {
+  constructor(toolName) {
+    super("the call was cancelled before it was forwarded");
+    this.toolName = toolName;
+    this.name = "UpstreamCallCancelled";
+  }
+  toolName;
+};
 var UpstreamListFailed = class extends Error {
   constructor() {
     super(
@@ -541,16 +786,50 @@ var UpstreamListFailed = class extends Error {
     this.name = "UpstreamListFailed";
   }
 };
-function callUpstream(upstream, name, args) {
-  return async () => {
+function forwardable(approved) {
+  const record = approved !== null && typeof approved === "object" && !Array.isArray(approved) ? { ...approved } : {};
+  delete record[CONTENT_PIN_KEY];
+  return record;
+}
+function callUpstream(upstream, name, signal, forwarding) {
+  return async (approved) => {
+    const args = forwardable(approved);
+    if (signal?.aborted) {
+      throw new UpstreamCallCancelled(name);
+    }
+    forwarding.sent = true;
     try {
-      return { [UPSTREAM_RESULT]: await upstream.callTool(name, args) };
-    } catch {
+      return {
+        [UPSTREAM_RESULT]: await upstream.callTool(
+          name,
+          args,
+          signal ? { signal } : void 0
+        )
+      };
+    } catch (err) {
+      if (err instanceof UpstreamCallCancelled) {
+        forwarding.sent = false;
+        throw err;
+      }
       throw new UpstreamCallFailed(name);
     }
   };
 }
-function failure(err, toolName) {
+function cancelledResult(toolName, requestId) {
+  return jsonResult2(
+    {
+      toolName,
+      ...requestId ? { requestId } : {},
+      cancelled: true,
+      message: requestId ? `The request was cancelled before ${toolName} was forwarded. Nothing was forwarded; the approved call is still held, so call ${CLAIM_TOOL} with this requestId to forward it.` : `The request was cancelled before ${toolName} was forwarded. Nothing was forwarded.`
+    },
+    true
+  );
+}
+function failure(err, toolName, forwarding) {
+  if (err instanceof UpstreamCallCancelled) {
+    return cancelledResult(toolName);
+  }
   if (err instanceof UpstreamCallFailed) {
     return jsonResult2(
       {
@@ -561,6 +840,19 @@ function failure(err, toolName) {
       true
     );
   }
+  if (err instanceof GuardianExecutionFailed && !err.localEffectRan && (err.reasonCode === "CONTENT_CHANGED_SINCE_APPROVAL" || err.reasonCode.startsWith("CONTENT_PIN_"))) {
+    return jsonResult2(
+      {
+        decision: "ALLOW",
+        toolName,
+        requestId: err.requestId,
+        executionFailed: err.reasonCode,
+        localEffectRan: false,
+        message: err.reasonCode === "CONTENT_CHANGED_SINCE_APPROVAL" ? "A file named in the approved call changed since it was approved. Nothing was forwarded and the capability was not redeemed. Propose the call again; it needs a new approval." : "A file named in the approved call could not be checked against its approval. Nothing was forwarded and the capability was not redeemed."
+      },
+      true
+    );
+  }
   if (err instanceof GuardianExecutionFailed) {
     return jsonResult2(
       {
@@ -569,12 +861,16 @@ function failure(err, toolName) {
         requestId: err.requestId,
         executionFailed: err.reasonCode,
         localEffectRan: err.localEffectRan,
-        message: err.localEffectRan ? "The upstream call ran but Guardian refused to redeem the capability. Treat this as an incident, not a success." : "Guardian could not redeem the capability; the call was not completed."
+        ...err.outcomeUnknown ? { outcomeUnknown: true } : {},
+        message: err.outcomeUnknown ? err.localEffectRan ? `The upstream call ran, but Guardian could not confirm that it was recorded. Do not call it again; check this requestId with ${RECEIPT_TOOL}.` : `Guardian could not confirm whether the call completed. It may have run. Do not call it again; check this requestId with ${RECEIPT_TOOL}.` : err.localEffectRan ? "The upstream call ran but Guardian refused to redeem the capability. Do not call it again. Treat this as an incident, not a success." : "Guardian could not redeem the capability; the call was not completed."
       },
       true
     );
   }
   if (err instanceof GuardianDenied) {
+    if (err.reasonCode === UNAVAILABLE) {
+      return unreachableResult(toolName, err.requestId);
+    }
     return jsonResult2(
       {
         decision: "DENY",
@@ -599,17 +895,35 @@ function failure(err, toolName) {
   return jsonResult2(
     {
       toolName,
-      error: "Guardian proxy error; the call was not forwarded."
+      error: forwarding.sent ? "Guardian proxy error after the call was forwarded. It may have run; check before retrying." : "Guardian proxy error; the call was not forwarded."
     },
     true
   );
 }
+var CLAIMED_REQUESTS_LIMIT = 1e3;
 function createGovernedProxy(options) {
   const { upstream, log = () => {
   } } = options;
+  const fileArgs = pinFilesToFileArgs(options.pinFiles);
+  if (Object.keys(fileArgs).length > 0 && options.upstreamTransport === "remote") {
+    throw new ContentPinConfigError(
+      CONTENT_PIN_REMOTE_UPSTREAM,
+      "guardian-mcp proxy: --pin-file is supported only for a stdio upstream. A remote (HTTP/SSE) MCP server opens paths on another machine, so the proxy cannot check the file it will read."
+    );
+  }
   const toolInvokeRequestIds = /* @__PURE__ */ new Set();
   const pendingCalls = /* @__PURE__ */ new Map();
   const pendingInstalls = /* @__PURE__ */ new Map();
+  const claimedCapabilities = /* @__PURE__ */ new Map();
+  const claimedRequests = /* @__PURE__ */ new Map();
+  const rememberClaim = (requestId, entry) => {
+    claimedRequests.delete(requestId);
+    claimedRequests.set(requestId, entry);
+    while (claimedRequests.size > CLAIMED_REQUESTS_LIMIT) {
+      const oldest = claimedRequests.keys().next().value;
+      claimedRequests.delete(oldest);
+    }
+  };
   const recordingClient = {
     ...options.client,
     async request(invocation) {
@@ -629,8 +943,30 @@ function createGovernedProxy(options) {
     onDeny: "result",
     installRecordTransport: options.autoRegister ?? false,
     ...options.adapterId ? { adapterId: options.adapterId } : {},
-    ...options.agentName ? { agentName: options.agentName } : {}
+    ...options.agentName ? { agentName: options.agentName } : {},
+    ...Object.keys(fileArgs).length > 0 ? { fileArgs } : {}
   });
+  ctx.installed ??= /* @__PURE__ */ new Set();
+  ctx.proposedInputs = /* @__PURE__ */ new Map();
+  function heldSetupStep(toolName, requestId) {
+    const held = ctx.heldSetup?.get(`${options.connectionId}:${toolName}`);
+    return held?.requestId === requestId ? held.step : void 0;
+  }
+  function tracked() {
+    let allowed;
+    return {
+      ctx: {
+        ...ctx,
+        options: {
+          ...ctx.options,
+          onReceipt: (event) => {
+            allowed = event.requestId;
+          }
+        }
+      },
+      allowedRequestId: () => allowed
+    };
+  }
   let upstreamTools = null;
   async function loadTools() {
     if (upstreamTools) return upstreamTools;
@@ -647,8 +983,10 @@ function createGovernedProxy(options) {
     upstreamTools = tools;
     return tools;
   }
-  function toCallResult(toolName, args, output) {
-    if (upstreamRan(output)) return output[UPSTREAM_RESULT];
+  function toCallResult(toolName, args, output, allowedRequestId) {
+    if (upstreamRan(output)) {
+      return withRequestId(output[UPSTREAM_RESULT], allowedRequestId);
+    }
     if (!isDecisionResult(output)) {
       return jsonResult2(
         {
@@ -661,7 +999,9 @@ function createGovernedProxy(options) {
     const g = output.guardian;
     if (g.decision === "ASK") {
       if (toolInvokeRequestIds.has(g.requestId)) {
-        pendingCalls.set(g.requestId, { name: toolName, args });
+        const proposed = ctx.proposedInputs?.get(g.requestId) ?? args;
+        ctx.proposedInputs?.delete(g.requestId);
+        pendingCalls.set(g.requestId, { name: toolName, args, proposed });
         return jsonResult2({
           decision: "ASK",
           toolName,
@@ -670,40 +1010,92 @@ function createGovernedProxy(options) {
         });
       }
       pendingInstalls.set(g.requestId, toolName);
+      const step = heldSetupStep(toolName, g.requestId);
       return jsonResult2({
         decision: "ASK",
         toolName,
         requestId: g.requestId,
-        message: `First use of ${toolName} needs a human to approve registering it with Guardian. After approval call ${CLAIM_TOOL} with this requestId, then retry the original call.`
+        message: step === "enable" ? `Switching on ${toolName} for this agent needs a human to approve it in Guardian. After approval call ${CLAIM_TOOL} with this requestId (or retry the original call).` : `First use of ${toolName} needs a human to approve registering it with Guardian. After approval call ${CLAIM_TOOL} with this requestId, then retry the original call.`
       });
     }
     if (g.decision === "DENY") {
-      return jsonResult2({
-        decision: "DENY",
-        toolName,
-        reasonCode: g.reasonCode,
-        ...g.requestId ? { requestId: g.requestId } : {},
-        message: g.message
-      });
+      if (g.reasonCode === UNAVAILABLE) {
+        return unreachableResult(toolName, g.requestId);
+      }
+      return jsonResult2(
+        {
+          decision: "DENY",
+          toolName,
+          reasonCode: g.reasonCode,
+          ...g.requestId ? { requestId: g.requestId } : {},
+          message: g.message
+        },
+        true
+      );
     }
     return jsonResult2({ decision: "ALLOW", toolName, requestId: g.requestId });
   }
-  async function claim(requestId) {
+  function alreadyClaimed(requestId) {
+    const seen = claimedRequests.get(requestId);
+    if (!seen) return void 0;
+    if (seen.state === "forwarding" || !seen.result) {
+      return jsonResult2(
+        {
+          toolName: seen.toolName,
+          requestId,
+          alreadyClaimed: true,
+          message: `This approved call is already being forwarded by an earlier ${CLAIM_TOOL}. Do not propose ${seen.toolName} again; wait, then call ${RECEIPT_TOOL} with this requestId to see what happened.`
+        },
+        true
+      );
+    }
+    const notice = {
+      type: "text",
+      text: `This requestId was already claimed and ${seen.toolName} was already forwarded. Do not propose it again. The earlier result follows.`
+    };
+    const earlier = seen.result;
+    return {
+      ...earlier,
+      isError: true,
+      content: [
+        notice,
+        ...Array.isArray(earlier.content) ? earlier.content : []
+      ]
+    };
+  }
+  async function claim(requestId, signal) {
+    const repeat = alreadyClaimed(requestId);
+    if (repeat) return repeat;
     const held = pendingCalls.get(requestId);
     if (held) {
+      if (signal?.aborted) {
+        return cancelledResult(held.name, requestId);
+      }
       pendingCalls.delete(requestId);
-      let claimed;
-      try {
-        claimed = await options.client.claim(requestId);
-      } catch {
+      const putBack = () => {
+        claimedRequests.delete(requestId);
         pendingCalls.set(requestId, held);
-        return jsonResult2(
-          { requestId, error: "Guardian unreachable; nothing was forwarded." },
-          true
-        );
+      };
+      rememberClaim(requestId, { toolName: held.name, state: "forwarding" });
+      let claimed;
+      const reused = claimedCapabilities.get(requestId);
+      if (reused) {
+        claimedCapabilities.delete(requestId);
+        claimed = reused;
+      } else {
+        try {
+          claimed = await options.client.claim(requestId);
+        } catch {
+          putBack();
+          return unreachableResult(held.name, requestId);
+        }
+      }
+      if (!claimed.ok && claimed.reasonCode === UNAVAILABLE) {
+        putBack();
+        return unreachableResult(held.name, requestId);
       }
       if (claimed.ok && claimed.decision === "ASK" || !claimed.ok && (claimed.reasonCode === "APPROVAL_PENDING" || claimed.reasonCode === "APPROVAL_REQUIRED")) {
-        pendingCalls.set(requestId, held);
+        putBack();
         return jsonResult2({
           decision: "ASK",
           toolName: held.name,
@@ -711,39 +1103,95 @@ function createGovernedProxy(options) {
           message: "Still awaiting human approval. Nothing was sent."
         });
       }
+      let result;
+      const forwarding = { sent: false };
       try {
+        const call = tracked();
         const output = await settle(
-          ctx,
+          call.ctx,
           held.name,
-          held.args,
+          held.proposed,
           claimed,
-          callUpstream(upstream, held.name, held.args)
+          callUpstream(upstream, held.name, signal, forwarding)
+        );
+        result = toCallResult(
+          held.name,
+          held.args,
+          output,
+          call.allowedRequestId()
         );
-        return toCallResult(held.name, held.args, output);
       } catch (err) {
-        return failure(err, held.name);
+        if (err instanceof UpstreamCallCancelled) {
+          putBack();
+          if (claimed.ok && claimed.decision === "ALLOW") {
+            claimedCapabilities.set(requestId, claimed);
+          }
+          return cancelledResult(held.name, requestId);
+        }
+        result = failure(err, held.name, forwarding);
       }
+      if (!claimed.ok || claimed.decision !== "ALLOW" || !claimed.capabilityToken) {
+        claimedRequests.delete(requestId);
+      } else {
+        rememberClaim(requestId, {
+          toolName: held.name,
+          state: "done",
+          result
+        });
+      }
+      return result;
     }
     const installFor = pendingInstalls.get(requestId);
     if (installFor) {
-      const claimed = await options.client.claim(requestId);
+      if (signal?.aborted) {
+        return jsonResult2(
+          {
+            toolName: installFor,
+            requestId,
+            cancelled: true,
+            message: `The request was cancelled. Nothing was claimed; call ${CLAIM_TOOL} with this requestId again.`
+          },
+          true
+        );
+      }
+      const key = `${options.connectionId}:${installFor}`;
+      const step = heldSetupStep(installFor, requestId) ?? "install";
+      const forgetHeld = () => {
+        if (ctx.heldSetup?.get(key)?.requestId === requestId) {
+          ctx.heldSetup.delete(key);
+        }
+      };
+      let claimed;
+      try {
+        claimed = await options.client.claim(requestId);
+      } catch {
+        return unreachableResult(installFor, requestId);
+      }
+      if (!claimed.ok && claimed.reasonCode === UNAVAILABLE) {
+        return unreachableResult(installFor, requestId);
+      }
       if (claimed.ok && claimed.decision === "ALLOW" && claimed.capabilityToken) {
+        forgetHeld();
+        pendingInstalls.delete(requestId);
         const executed = await options.client.execute({
           requestId: claimed.requestId,
           capabilityToken: claimed.capabilityToken
         });
-        pendingInstalls.delete(requestId);
-        ctx.ensured.add(`${options.connectionId}:${installFor}`);
+        if (executed.ok && step === "enable") {
+          ctx.ensured.add(key);
+        } else if (executed.ok) {
+          ctx.installed?.add(key);
+        }
         return jsonResult2(
           executed.ok ? {
             decision: "ALLOW",
             toolName: installFor,
-            message: `${installFor} is registered with Guardian. Retry the original call.`
+            message: step === "enable" ? `${installFor} is switched on for this agent. Retry the original call.` : `${installFor} is registered with Guardian. Retry the original call; switching it on for this agent may need one more approval.`
           } : { toolName: installFor, executionFailed: executed.reasonCode },
           !executed.ok
         );
       }
-      if (claimed.ok && claimed.decision === "ASK") {
+      if (claimed.ok && claimed.decision === "ASK" || !claimed.ok && (claimed.reasonCode === "APPROVAL_PENDING" || claimed.reasonCode === "APPROVAL_REQUIRED")) {
         return jsonResult2({
           decision: "ASK",
           toolName: installFor,
@@ -751,17 +1199,21 @@ function createGovernedProxy(options) {
           message: "Still awaiting human approval."
         });
       }
+      forgetHeld();
       pendingInstalls.delete(requestId);
-      return jsonResult2({
-        decision: "DENY",
-        toolName: installFor,
-        reasonCode: claimed.ok ? claimed.reasonCode ?? "MISSING_CAPABILITY" : claimed.reasonCode
-      });
+      return jsonResult2(
+        {
+          decision: "DENY",
+          toolName: installFor,
+          reasonCode: claimed.ok ? claimed.reasonCode ?? "MISSING_CAPABILITY" : claimed.reasonCode
+        },
+        true
+      );
     }
     return jsonResult2(
       {
         requestId,
-        error: "No held call with this requestId in this proxy session. Nothing was forwarded."
+        error: `This proxy holds no call with this requestId, so this claim forwarded nothing. If it was claimed before (in this or an earlier proxy session), the call may already have been forwarded: call ${RECEIPT_TOOL} with this requestId before proposing it again.`
       },
       true
     );
@@ -785,13 +1237,14 @@ function createGovernedProxy(options) {
         ...PROXY_GOVERNANCE_TOOLS
       ];
     },
-    async callTool(name, args) {
+    async callTool(name, args, callOptions) {
+      const signal = callOptions?.signal;
       if (name === CLAIM_TOOL) {
         const requestId = args.requestId;
         if (typeof requestId !== "string" || requestId.length === 0) {
           return jsonResult2({ error: "requestId is required" }, true);
         }
-        return claim(requestId);
+        return claim(requestId, signal);
       }
       if (name === RECEIPT_TOOL) {
         const requestId = args.requestId;
@@ -819,16 +1272,21 @@ function createGovernedProxy(options) {
       if (!tools.has(name)) {
         return jsonResult2({ error: `unknown tool: ${name}` }, true);
       }
+      if (signal?.aborted) {
+        return cancelledResult(name);
+      }
+      const forwarding = { sent: false };
       try {
+        const call = tracked();
         const output = await runThroughGuardian(
-          ctx,
+          call.ctx,
           name,
           args,
-          callUpstream(upstream, name, args)
+          callUpstream(upstream, name, signal, forwarding)
         );
-        return toCallResult(name, args, output);
+        return toCallResult(name, args, output, call.allowedRequestId());
       } catch (err) {
-        return failure(err, name);
+        return failure(err, name, forwarding);
       }
     }
   };
@@ -892,7 +1350,10 @@ function toolListFailure(target, err) {
 function clientUpstream(client2) {
   return {
     listTools: () => listAllTools(client2),
-    async callTool(name, args) {
+    async callTool(name, args, options) {
+      if (options?.signal?.aborted) {
+        throw new UpstreamCallCancelled(name);
+      }
       return await client2.callTool({
         name,
         arguments: args
@@ -960,23 +1421,39 @@ if (config.mode.kind === "proxy") {
     name: "guardian-mcp-proxy",
     version: VERSION
   });
-  const proxy = createGovernedProxy({
-    client,
-    connectionId: config.connectionId,
-    autoRegister: config.autoRegister,
-    ...config.adapterId ? { adapterId: config.adapterId } : {},
-    log: (message) => process.stderr.write(`${message}
+  let proxy;
+  try {
+    proxy = createGovernedProxy({
+      client,
+      connectionId: config.connectionId,
+      autoRegister: config.autoRegister,
+      upstreamTransport: "remote" in config.mode ? "remote" : "stdio",
+      ...config.mode.pinFiles ? { pinFiles: config.mode.pinFiles } : {},
+      ...config.adapterId ? { adapterId: config.adapterId } : {},
+      log: (message) => process.stderr.write(`${message}
 `),
-    upstream: clientUpstream(upstreamClient)
-  });
+      upstream: clientUpstream(upstreamClient)
+    });
+  } catch (err) {
+    process.stderr.write(
+      `${err instanceof Error ? err.message : "guardian-mcp proxy: invalid configuration."}
+`
+    );
+    await upstreamClient.close().catch(() => {
+    });
+    process.exit(2);
+  }
   server.setRequestHandler(ListToolsRequestSchema, async () => ({
     tools: await proxy.listTools()
   }));
   server.setRequestHandler(
     CallToolRequestSchema,
-    async (request) => await proxy.callTool(
+    async (request, extra) => await proxy.callTool(
       request.params.name,
-      request.params.arguments ?? {}
+      request.params.arguments ?? {},
+      // Cancelled (notifications/cancelled) or timed-out requests are
+      // not forwarded if the signal fires before the call is sent.
+      { signal: extra.signal }
     )
   );
 } else {

package/package.json

@@ -1,9 +1,10 @@
 {
   "name": "@odingard/guardian-mcp",
-  "version": "0.3.3",
+  "version": "0.4.0",
   "mcpName": "io.github.Odingard/guardian-mcp",
-  "description": "MCP server that routes an agent's tool calls through Guardian — the human authority layer for autonomous AI. Every tool call gets a deterministic ALLOW/ASK/DENY decision before anything executes; ASK holds for human approval, DENY never runs, every outcome carries a verifiable receipt.",
+  "description": "MCP server that routes an agent's tool calls through Guardian — the human authority layer for autonomous AI. Every tool call gets a deterministic ALLOW/ASK/DENY decision before anything executes; ASK holds for human approval, DENY never runs, and every allowed call that completes carries a verifiable receipt.",
   "license": "Apache-2.0",
+  "author": "Odingard Security LLC",
   "type": "module",
   "main": "dist/index.js",
   "bin": {
@@ -25,7 +26,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.32.2",
-    "@odingard/guardian-sdk": "^0.3.8"
+    "@odingard/guardian-sdk": "^0.4.0"
   },
   "devDependencies": {
     "@types/node": "^22",

package/server.json

@@ -2,7 +2,7 @@
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-10-17/server.schema.json",
   "name": "io.github.Odingard/guardian-mcp",
   "description": "Routes agent tool calls through Guardian for ALLOW/ASK/DENY before execution.",
-  "version": "0.3.3",
+  "version": "0.4.0",
   "tools": [
     {
       "name": "guardian_invoke_tool",
@@ -26,7 +26,7 @@
     {
       "registryType": "npm",
       "identifier": "@odingard/guardian-mcp",
-      "version": "0.3.3",
+      "version": "0.4.0",
       "transport": {
         "type": "stdio"
       },