mcp-authz 0.3.0 → 0.5.0

package/dist/cli.js

@@ -1,9 +1,832 @@
 #!/usr/bin/env node
+import { n as holdsInexactNumber, r as parseChecked, t as hasDuplicateKey } from "./strict-json-DLKOgsGE.js";
 import { i as reconcile, r as definePolicy } from "./policy-BBp3Jq6G.js";
-import { readFileSync, writeFileSync } from "node:fs";
-import { resolve } from "node:path";
+import { c as suspicious, i as definitionOf, n as captureListings, o as missingDefinitions, r as changedFields, s as reveal, t as INSTRUCTIONS } from "./definitions-CyIy4YSZ.js";
+import { n as screenResult, r as withNotice, t as checkArguments } from "./screen-DxoujEpO.js";
+import { createRequire } from "node:module";
+import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { basename, dirname, extname, join, relative, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 import { parseArgs } from "node:util";
+import { spawn } from "node:child_process";
+import { createInterface } from "node:readline";
+import { setTimeout } from "node:timers/promises";
+import { tmpdir } from "node:os";
+//#region src/windows-job.ts
+/** Quote one argument for CreateProcessW's command line (not a shell). */
+function quoteWindowsArgument(value) {
+	return `"${value.replace(/(\\*)"/g, "$1$1\\\"").replace(/(\\+)$/, "$1$1")}"`;
+}
+/**
+* A PowerShell supervisor owns a kill-on-close Job Object. A small Node
+* launcher enters it while suspended, before it can create any descendants.
+* The supervisor keeps its handle until the launcher exits; closing it kills
+* every remaining descendant, even after their immediate parent has exited.
+* Only the supervisor owns the handle, so terminating it also kills the job.
+*/
+function windowsJobCommand(command, args) {
+	const crossSpawn = createRequire(import.meta.url).resolve("cross-spawn");
+	const directory = mkdtempSync(join(tmpdir(), "mcp-authz-job-"));
+	const specPath = join(directory, "spec.json");
+	writeFileSync(specPath, JSON.stringify({
+		command,
+		args
+	}), { mode: 384 });
+	const cleanup = () => rmSync(directory, {
+		recursive: true,
+		force: true
+	});
+	const launcher = [
+		`const fs = require('fs');`,
+		`const spawn = require(${JSON.stringify(crossSpawn)});`,
+		`const spec = JSON.parse(fs.readFileSync(${JSON.stringify(specPath)}, 'utf8'));`,
+		`fs.rmSync(${JSON.stringify(directory)}, { recursive: true, force: true });`,
+		`const child = spawn(spec.command, spec.args, { stdio: 'inherit' });`,
+		`child.on('error', error => { console.error(error.message); process.exit(1); });`,
+		`child.on('exit', code => process.exit(code ?? 1));`
+	].join("\n");
+	const commandLine = [
+		process.execPath,
+		"--input-type=commonjs",
+		"-e",
+		launcher
+	].map(quoteWindowsArgument).join(" ");
+	const encoded = Buffer.from(commandLine, "utf8").toString("base64");
+	const script = [
+		"$ErrorActionPreference = \"Stop\"",
+		"$ProgressPreference = 'SilentlyContinue'",
+		"Add-Type -TypeDefinition @'",
+		JOB_SUPERVISOR,
+		"'@",
+		`$line = [Text.Encoding]::UTF8.GetString([Convert]::FromBase64String('${encoded}'))`,
+		"try { exit ([McpAuthzJob]::Run($line)) }",
+		"catch { [Console]::Error.WriteLine($_.Exception.Message); exit 1 }"
+	].join("\n");
+	return {
+		specPath,
+		/** Remove the spec if the launcher never got to; safe to call twice. */
+		cleanup,
+		command: join(process.env.SystemRoot ?? "C:\\Windows", "System32", "WindowsPowerShell", "v1.0", "powershell.exe"),
+		args: [
+			"-NoLogo",
+			"-NoProfile",
+			"-NonInteractive",
+			"-EncodedCommand",
+			Buffer.from(script, "utf16le").toString("base64")
+		]
+	};
+}
+const JOB_SUPERVISOR = String.raw`
+using System;
+using System.ComponentModel;
+using System.Runtime.InteropServices;
+using System.Text;
+
+public static class McpAuthzJob {
+    [StructLayout(LayoutKind.Sequential)]
+    struct BasicLimits {
+        public long ProcessTime, JobTime;
+        public uint Flags;
+        public UIntPtr MinimumWorkingSet, MaximumWorkingSet;
+        public uint ActiveProcessLimit;
+        public UIntPtr Affinity;
+        public uint PriorityClass, SchedulingClass;
+    }
+    [StructLayout(LayoutKind.Sequential)]
+    struct IoCounters { public ulong ReadOps, WriteOps, OtherOps, ReadBytes, WriteBytes, OtherBytes; }
+    [StructLayout(LayoutKind.Sequential)]
+    struct ExtendedLimits {
+        public BasicLimits Basic;
+        public IoCounters Io;
+        public UIntPtr ProcessMemory, JobMemory, PeakProcessMemory, PeakJobMemory;
+    }
+    [StructLayout(LayoutKind.Sequential, CharSet = CharSet.Unicode)]
+    struct StartupInfo {
+        public uint Size;
+        public string Reserved, Desktop, Title;
+        public uint X, Y, XSize, YSize, XChars, YChars, Fill, Flags;
+        public ushort Show, ReservedSize;
+        public IntPtr ReservedData, Input, Output, Error;
+    }
+    [StructLayout(LayoutKind.Sequential)]
+    struct ProcessInfo { public IntPtr Process, Thread; public uint ProcessId, ThreadId; }
+
+    [DllImport("kernel32.dll", CharSet = CharSet.Unicode, SetLastError = true)]
+    static extern IntPtr CreateJobObjectW(IntPtr security, string name);
+    [DllImport("kernel32.dll", SetLastError = true)]
+    static extern bool SetInformationJobObject(IntPtr job, int infoClass, ref ExtendedLimits info, uint size);
+    [DllImport("kernel32.dll", SetLastError = true)]
+    static extern bool AssignProcessToJobObject(IntPtr job, IntPtr process);
+    [DllImport("kernel32.dll", CharSet = CharSet.Unicode, SetLastError = true)]
+    static extern bool CreateProcessW(string app, StringBuilder line, IntPtr processSecurity,
+        IntPtr threadSecurity, bool inherit, uint flags, IntPtr environment, string cwd,
+        ref StartupInfo startup, out ProcessInfo process);
+    [DllImport("kernel32.dll", SetLastError = true)]
+    static extern uint ResumeThread(IntPtr thread);
+    [DllImport("kernel32.dll", SetLastError = true)]
+    static extern uint WaitForSingleObject(IntPtr handle, uint milliseconds);
+    [DllImport("kernel32.dll", SetLastError = true)]
+    static extern bool GetExitCodeProcess(IntPtr process, out uint code);
+    [DllImport("kernel32.dll")]
+    static extern IntPtr GetStdHandle(int handle);
+    [DllImport("kernel32.dll", SetLastError = true)]
+    static extern bool TerminateProcess(IntPtr process, uint code);
+    [DllImport("kernel32.dll")]
+    static extern bool CloseHandle(IntPtr handle);
+
+    static void Check(bool success) {
+        if (!success) throw new Win32Exception(Marshal.GetLastWin32Error());
+    }
+
+    public static int Run(string commandLine) {
+        IntPtr job = CreateJobObjectW(IntPtr.Zero, null);
+        Check(job != IntPtr.Zero);
+        ProcessInfo process = new ProcessInfo();
+        bool assigned = false;
+        try {
+            ExtendedLimits limits = new ExtendedLimits();
+            limits.Basic.Flags = 0x2000; // JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE
+            Check(SetInformationJobObject(job, 9, ref limits, (uint)Marshal.SizeOf(typeof(ExtendedLimits))));
+            StartupInfo startup = new StartupInfo();
+            startup.Size = (uint)Marshal.SizeOf(typeof(StartupInfo));
+            startup.Flags = 0x100; // STARTF_USESTDHANDLES
+            startup.Input = GetStdHandle(-10);
+            startup.Output = GetStdHandle(-11);
+            startup.Error = GetStdHandle(-12);
+            Check(CreateProcessW(null, new StringBuilder(commandLine), IntPtr.Zero, IntPtr.Zero,
+                true, 0x4, IntPtr.Zero, null, ref startup, out process)); // CREATE_SUSPENDED
+            Check(AssignProcessToJobObject(job, process.Process));
+            assigned = true;
+            Check(ResumeThread(process.Thread) != UInt32.MaxValue);
+            Check(WaitForSingleObject(process.Process, UInt32.MaxValue) != UInt32.MaxValue);
+            uint code;
+            Check(GetExitCodeProcess(process.Process, out code));
+            return unchecked((int)code);
+        } finally {
+            // If assignment failed, the suspended launcher must also be reaped.
+            if (!assigned && process.Process != IntPtr.Zero) TerminateProcess(process.Process, 1);
+            CloseHandle(job);
+            if (process.Thread != IntPtr.Zero) CloseHandle(process.Thread);
+            if (process.Process != IntPtr.Zero) CloseHandle(process.Process);
+        }
+    }
+}
+`;
+//#endregion
+//#region src/wrap.ts
+/**
+* Roughly what a tool's definition costs in the model's context: its JSON, at
+* four characters a token. A guide for choosing what to hide, not a bill.
+*/
+function estimateTokens(tool) {
+	return Math.ceil(JSON.stringify(tool).length / 4);
+}
+function formatTokens(tokens) {
+	return tokens < 1e3 ? `~${tokens}` : `~${(tokens / 1e3).toFixed(1)}k`;
+}
+/** Resolves with the upstream's exit code. */
+function wrap(options, io) {
+	const listed = (name) => options.allow ? options.allow.includes(name) : !options.deny?.includes(name);
+	const changed = /* @__PURE__ */ new Map();
+	const drift = (tool) => {
+		if (!options.pinned) return void 0;
+		const approved = options.pinned.get(tool.name);
+		if (!approved) return options.allow ? "it was not offered when you approved this list" : void 0;
+		const fields = changedFields(approved, definitionOf(tool));
+		return fields.length > 0 ? `its ${fields.join(", ")} changed since you approved it` : void 0;
+	};
+	const visible = (name) => listed(name) && !changed.has(name);
+	const verified = /* @__PURE__ */ new Set();
+	const check = (tool) => {
+		const reason = drift(tool);
+		if (reason === void 0) {
+			changed.delete(tool.name);
+			verified.add(tool.name);
+			return;
+		}
+		verified.delete(tool.name);
+		if (listed(tool.name) && changed.get(tool.name) !== reason) {
+			changed.set(tool.name, reason);
+			io.log(`mcp-authz wrap: hid ${tool.name}: ${reason}. Review it with mcp-authz tools --check <config>, then --refresh to approve.`);
+		}
+	};
+	const windows = process.platform === "win32";
+	const upstream = windows ? windowsJobCommand(options.command, options.args) : void 0;
+	const child = spawn(upstream?.command ?? options.command, [...upstream?.args ?? options.args], {
+		stdio: [
+			"pipe",
+			"pipe",
+			"pipe"
+		],
+		detached: !windows,
+		windowsHide: true,
+		...options.cwd ? { cwd: options.cwd } : {}
+	});
+	child.stdin.on("error", () => {});
+	const listing = /* @__PURE__ */ new Set();
+	const discovering = /* @__PURE__ */ new Set();
+	const held = [];
+	let verifying;
+	let verifications = 0;
+	let verifyMeta;
+	const requestList = (meta, cursor) => {
+		verifyMeta = meta;
+		verifying = `mcp-authz-wrap/verify/${++verifications}`;
+		const params = {
+			...cursor ? { cursor } : {},
+			...meta ? { _meta: meta } : {}
+		};
+		child.stdin.write(`${JSON.stringify({
+			jsonrpc: "2.0",
+			id: verifying,
+			method: "tools/list",
+			params
+		})}\n`);
+	};
+	const calls = /* @__PURE__ */ new Map();
+	const forward = (line, message) => {
+		const name = message.params.name;
+		const approved = options.pinned?.get(name);
+		const wrong = approved && checkArguments(name, approved, message.params.arguments);
+		if (wrong) {
+			const error = {
+				code: -32602,
+				message: `Invalid params: ${wrong}`
+			};
+			send(JSON.stringify({
+				jsonrpc: "2.0",
+				id: message.id ?? null,
+				error
+			}));
+			return;
+		}
+		if (message.id !== void 0) calls.set(message.id, name);
+		child.stdin.write(`${line}\n`);
+	};
+	const release = (failure) => {
+		verifying = void 0;
+		for (const { line, message } of held.splice(0)) {
+			const name = message.params.name;
+			if (!failure && visible(name) && verified.has(name)) {
+				forward(line, message);
+				continue;
+			}
+			const error = {
+				code: -32602,
+				message: `Tool "${name}" is blocked by mcp-authz wrap: ${failure ?? changed.get(name) ?? "the server did not list it, so its definition could not be checked"}`
+			};
+			send(JSON.stringify({
+				jsonrpc: "2.0",
+				id: message.id ?? null,
+				error
+			}));
+		}
+	};
+	const seen = /* @__PURE__ */ new Map();
+	let reported = false;
+	const report = () => {
+		if (reported) return;
+		reported = true;
+		const hidden = [...seen.keys()].filter((name) => !visible(name)).sort();
+		const total = [...seen.values()].reduce((sum, tokens) => sum + tokens, 0);
+		const shown = total - hidden.reduce((sum, name) => sum + seen.get(name), 0);
+		io.log(`mcp-authz wrap: ${seen.size - hidden.length}/${seen.size} tools exposed (${formatTokens(shown)} of ${formatTokens(total)} tokens)` + (hidden.length > 0 ? `, hidden: ${hidden.join(", ")}` : ""));
+		for (const name of options.allow ?? options.deny ?? []) if (!seen.has(name)) io.log(`mcp-authz wrap: no tool named ${name}`);
+	};
+	onLines(io.input, (line) => {
+		if (stopping || line.trim() === "") return;
+		let value;
+		const refuse = (code, reason) => {
+			const id = value?.id;
+			const replyTo = typeof id === "string" || typeof id === "number" || holdsInexactNumber(id) ? id : null;
+			send(JSON.stringify({
+				jsonrpc: "2.0",
+				id: replyTo,
+				error: {
+					code,
+					message: reason
+				}
+			}));
+		};
+		try {
+			value = parseChecked(line);
+		} catch {
+			refuse(-32700, "Parse error: mcp-authz wrap forwards only messages it can read");
+			return;
+		}
+		if (typeof value !== "object" || value === null || Array.isArray(value)) {
+			refuse(-32600, "Invalid request: mcp-authz wrap forwards single JSON-RPC messages, not batches");
+			return;
+		}
+		if (hasDuplicateKey(line)) {
+			refuse(-32600, "Invalid request: mcp-authz wrap refuses a message that repeats a key");
+			return;
+		}
+		const message = value;
+		if (message.method !== void 0 && holdsInexactNumber(message.id)) {
+			refuse(-32600, "Invalid request: mcp-authz wrap cannot track an id it cannot hold exactly");
+			return;
+		}
+		if (message.method === "tools/list" && message.id !== void 0) listing.add(message.id);
+		if ((message.method === "initialize" || message.method === "server/discover") && message.id !== void 0) discovering.add(message.id);
+		const name = message.method === "tools/call" ? message.params?.name : void 0;
+		if (message.method === "tools/call" && (typeof name !== "string" || !visible(name))) {
+			const error = {
+				code: -32602,
+				message: typeof name !== "string" ? "tools/call needs a tool name" : changed.has(name) ? `Tool "${name}" is blocked by mcp-authz wrap: ${changed.get(name)}` : `Tool "${name}" is blocked by mcp-authz wrap`
+			};
+			send(JSON.stringify({
+				jsonrpc: "2.0",
+				id: message.id ?? null,
+				error
+			}));
+			return;
+		}
+		if (message.method === "tools/call" && options.pinned && !verified.has(name)) {
+			held.push({
+				line,
+				message
+			});
+			const meta = Object.fromEntries(Object.entries(message.params?._meta ?? {}).filter(([key]) => key.startsWith("io.modelcontextprotocol/")));
+			if (verifying === void 0) requestList(Object.keys(meta).length > 0 ? meta : void 0);
+			return;
+		}
+		if (message.method === "tools/call") forward(line, message);
+		else child.stdin.write(`${line}\n`);
+	});
+	io.output.on("error", () => void stop());
+	const send = (line) => {
+		if (io.output.writable) io.output.write(`${line}\n`);
+	};
+	const treeAlive = () => {
+		if (child.pid === void 0) return false;
+		if (windows) return child.exitCode === null && child.signalCode === null;
+		try {
+			process.kill(-child.pid, 0);
+			return true;
+		} catch {
+			return false;
+		}
+	};
+	const signalTree = (signal) => {
+		if (child.pid === void 0) return;
+		if (windows) {
+			child.kill("SIGKILL");
+			return;
+		}
+		try {
+			process.kill(-child.pid, signal);
+		} catch {}
+	};
+	const goneWithin = async (ms) => {
+		for (const deadline = Date.now() + ms; Date.now() < deadline; await setTimeout(25)) if (!treeAlive()) return true;
+		return !treeAlive();
+	};
+	const grace = options.graceMs ?? 2e3;
+	let stopping;
+	const stop = () => stopping ??= (async () => {
+		child.stdin.end();
+		for (const signal of ["SIGTERM", "SIGKILL"]) {
+			if (await goneWithin(grace)) return;
+			signalTree(signal);
+		}
+		await goneWithin(grace);
+	})();
+	io.input.on("end", stop);
+	if (io.signal?.aborted) stop();
+	else io.signal?.addEventListener("abort", stop, { once: true });
+	onLines(child.stdout, (line) => {
+		const message = parse(line);
+		const response = message?.method === void 0 && message?.id !== void 0;
+		if (response && message.id === verifying) {
+			if (!message.result?.tools) return release("the server would not list its tools to check it");
+			for (const tool of message.result.tools) check(tool);
+			if (message.result.nextCursor) requestList(verifyMeta, message.result.nextCursor);
+			else release();
+			return;
+		}
+		if (message?.method === "notifications/tools/list_changed") verified.clear();
+		if (response && listing.delete(message.id) && message.result?.tools) {
+			for (const tool of message.result.tools) {
+				seen.set(tool.name, estimateTokens(tool));
+				check(tool);
+			}
+			if (!message.result.nextCursor) report();
+			message.result.tools = message.result.tools.filter((tool) => visible(tool.name));
+			line = JSON.stringify(message);
+		}
+		if (response && discovering.delete(message.id) && options.pinned && message.result) {
+			const live = message.result.instructions;
+			const approved = options.pinned.get(INSTRUCTIONS)?.instructions;
+			if (live !== void 0 && live !== approved) {
+				delete message.result.instructions;
+				line = JSON.stringify(message);
+				io.log("mcp-authz wrap: removed the server's instructions: they changed since you approved them. Review with mcp-authz tools --check <config>, then --refresh to approve.");
+			}
+		}
+		const tool = response ? calls.get(message.id) : void 0;
+		if (message && tool !== void 0 && calls.delete(message.id) && message.result) {
+			const checked = parseChecked(line).result;
+			const screened = screenResult(tool, options.pinned?.get(tool) ?? {}, checked);
+			if (screened.verdict !== "pass") {
+				line = JSON.stringify(screened.verdict === "withhold" ? {
+					...message,
+					result: screened.result
+				} : withNotice(line, screened.notice));
+				io.log(`mcp-authz wrap: ${screened.warning}`);
+			}
+		}
+		send(line);
+	});
+	createInterface({ input: child.stderr }).on("line", io.log);
+	return new Promise((resolve) => {
+		child.on("exit", (code) => resolve(code ?? 1));
+		child.on("error", (error) => {
+			io.log(`mcp-authz wrap: could not start ${options.command}: ${error.message}. Install it, or give its full path in your config.`);
+			resolve(1);
+		});
+	}).then(async (code) => {
+		await stop();
+		upstream?.cleanup();
+		return code;
+	});
+}
+/**
+* Call `onLine` for each newline-terminated line, framed as the MCP SDKs frame
+* stdio: split on `\n` alone, with a trailing `\r` dropped. node:readline also
+* splits on `\r`, U+2028 and U+2029, which JSON allows unescaped inside a
+* string, so it would read one message as two where the server reads one.
+*/
+function onLines(stream, onLine) {
+	let buffered = "";
+	stream.setEncoding("utf8");
+	stream.on("data", (chunk) => {
+		buffered += chunk;
+		let newline;
+		while ((newline = buffered.indexOf("\n")) !== -1) {
+			onLine(buffered.slice(0, newline).replace(/\r$/, ""));
+			buffered = buffered.slice(newline + 1);
+		}
+	});
+	stream.on("end", () => {
+		if (buffered !== "") onLine(buffered.replace(/\r$/, ""));
+		buffered = "";
+	});
+}
+function parse(line) {
+	try {
+		const value = JSON.parse(line);
+		return typeof value === "object" && value !== null ? value : void 0;
+	} catch {
+		return;
+	}
+}
+//#endregion
+//#region src/wrap-config.ts
+/** Where the schema keeps the definitions; editors ignore an `x-` keyword. */
+const RECORDED = "x-mcp-authz-tools";
+/** Ask a stdio server for its tools, the way a client would. */
+async function discover$1(command, args, cwd) {
+	const { Client } = await import("@modelcontextprotocol/client");
+	const { StdioClientTransport } = await import("@modelcontextprotocol/client/stdio");
+	const client = new Client({
+		name: "mcp-authz-tools",
+		version: "1.0.0"
+	}, { versionNegotiation: { mode: "auto" } });
+	const env = Object.fromEntries(Object.entries(process.env).filter((entry) => entry[1] !== void 0));
+	const transport = new StdioClientTransport({
+		command,
+		args: [...args],
+		env,
+		...cwd ? { cwd } : {}
+	});
+	const raw = captureListings(transport);
+	await client.connect(transport);
+	try {
+		const tools = [];
+		let cursor;
+		do {
+			const page = await client.listTools(cursor ? { cursor } : void 0);
+			for (const tool of page.tools) tools.push({
+				name: tool.name,
+				hint: tool.annotations?.destructiveHint ? "destructive" : tool.annotations?.readOnlyHint ? "read-only" : "unknown",
+				description: reveal(tool.description?.split("\n")[0]?.trim() ?? ""),
+				params: Object.keys(tool.inputSchema.properties ?? {}).map((param) => tool.inputSchema.required?.includes(param) ? `${param} (required)` : param),
+				tokens: estimateTokens(raw.get(tool.name) ?? tool),
+				pin: definitionOf(raw.get(tool.name) ?? tool),
+				warnings: suspicious(definitionOf(raw.get(tool.name) ?? tool))
+			});
+			cursor = page.nextCursor;
+		} while (cursor);
+		const instructions = client.getInstructions();
+		return {
+			tools: tools.sort((a, b) => a.name.localeCompare(b.name)),
+			...typeof instructions === "string" ? { instructions } : {}
+		};
+	} finally {
+		await client.close();
+	}
+}
+/** Where the schema for a config lives: beside it, named after it. */
+function schemaPathFor(configPath) {
+	return join(dirname(configPath), `${basename(configPath, extname(configPath))}.schema.json`);
+}
+/**
+* Write the config and its schema.
+*
+* In a fresh config, only tools the server marks read-only start switched on,
+* and not those flagged for a closer read. Over an existing config, the choices
+* in it are kept, and a tool the server added or changed since starts commented
+* out, so a refresh keeps your edits and waits for you to approve the rest.
+* With no record to compare against, every tool counts as new.
+*/
+function writeWrapConfig(configPath, server, { tools, instructions }, previous) {
+	const schemaPath = schemaPathFor(configPath);
+	const isNew = (tool) => previous !== void 0 && !previous.recorded?.has(tool.name);
+	const isChanged = (tool) => {
+		const approved = previous?.recorded?.get(tool.name);
+		return approved !== void 0 && changedFields(approved, tool.pin).length > 0;
+	};
+	const chosen = (tool) => {
+		if (!previous) return tool.hint === "read-only" && tool.warnings.length === 0;
+		if (isNew(tool) || isChanged(tool)) return false;
+		const { allow, deny } = previous.options;
+		return allow ? allow.includes(tool.name) : !deny?.includes(tool.name);
+	};
+	const on = tools.filter(chosen);
+	const off = tools.filter((tool) => !chosen(tool));
+	const note = (tool) => ` //${tool.warnings.map((warning) => ` ⚠ ${warning} ·`).join("")} ${tool.hint} · ${formatTokens(tool.tokens)} tokens${tool.description ? ` · ${clip(tool.description)}` : ""}`;
+	const entries = [...on.map((tool) => `    ${JSON.stringify(tool.name)},${note(tool)}`), ...off.map((tool) => `    // ${JSON.stringify(tool.name)},${note(tool)}`)];
+	const text = [
+		"{",
+		`  "$schema": ${JSON.stringify(`./${basename(schemaPath)}`)},`,
+		"  // The server `mcp-authz wrap` runs. Its env comes from your client config.",
+		`  "server": {`,
+		`    "command": ${JSON.stringify(server.command)},`,
+		`    "args": [${server.args.map((arg) => JSON.stringify(arg)).join(", ")}],`,
+		"    // Where the server runs, relative to this file, so relative paths in",
+		"    // \"args\" mean the same wherever the client starts it.",
+		`    "cwd": ${JSON.stringify(storedCwd(configPath, server.cwd))}`,
+		"  },",
+		"  // The tools this session may see. Anything not listed is hidden, including",
+		"  // tools the server adds later. Uncomment a line to switch a tool on.",
+		"  \"allow\": [",
+		...entries,
+		"  ]",
+		"}",
+		""
+	].join("\n");
+	writeFileSync(configPath, text);
+	writeFileSync(schemaPath, `${JSON.stringify(schemaFor(tools, instructions), null, 2)}\n`);
+	return {
+		allowed: on.length,
+		commented: off.length,
+		added: tools.filter(isNew).length,
+		changed: tools.filter(isChanged).length,
+		tokens: {
+			allowed: sum(on),
+			total: sum(tools)
+		}
+	};
+}
+function sum(tools) {
+	return tools.reduce((total, tool) => total + tool.tokens, 0);
+}
+function schemaFor(tools, instructions) {
+	const names = {
+		type: "array",
+		items: { $ref: "#/definitions/tool" },
+		uniqueItems: true
+	};
+	return {
+		$schema: "http://json-schema.org/draft-07/schema#",
+		title: "mcp-authz wrap config",
+		type: "object",
+		required: ["server"],
+		additionalProperties: false,
+		not: { required: ["allow", "deny"] },
+		properties: {
+			$schema: { type: "string" },
+			server: {
+				type: "object",
+				required: ["command"],
+				additionalProperties: false,
+				properties: {
+					command: { type: "string" },
+					args: {
+						type: "array",
+						items: { type: "string" }
+					},
+					cwd: {
+						type: "string",
+						description: "Where the server runs, relative to this file or absolute."
+					}
+				}
+			},
+			allow: {
+				...names,
+				description: "Only these tools are shown."
+			},
+			deny: {
+				...names,
+				description: "Every tool but these is shown."
+			}
+		},
+		definitions: { tool: tools.length > 0 ? { anyOf: tools.map((tool) => ({
+			const: tool.name,
+			description: note(tool)
+		})) } : { not: {} } },
+		[RECORDED]: Object.fromEntries([...tools.map((tool) => [tool.name, tool.pin]), ...instructions === void 0 ? [] : [[INSTRUCTIONS, { instructions }]]])
+	};
+	function note(tool) {
+		const head = `${tool.hint} · ${formatTokens(tool.tokens)} tokens`;
+		const said = tool.description ? `${head} · ${tool.description}` : head;
+		return tool.params.length > 0 ? `${said}\n\nTakes: ${tool.params.join(", ")}` : said;
+	}
+}
+/**
+* What the schema beside a config recorded: each tool's definition, and the
+* server's instructions under `server:instructions`. Throws when the record is
+* missing or damaged, because wrap without it would filter by name alone while
+* looking exactly as protected as before.
+*/
+function recordedTools(configPath) {
+	const schemaPath = schemaPathFor(configPath);
+	const fail = (problem) => {
+		throw new Error(`${schemaPath}: ${problem}. It records what you approved, and wrap will not run without it. Run mcp-authz tools --refresh ${configPath} to record the server again; every tool starts switched off.`);
+	};
+	let schema;
+	try {
+		schema = JSON.parse(readFileSync(schemaPath, "utf8"));
+	} catch (error) {
+		return fail(error.code === "ENOENT" ? "missing" : "not valid JSON");
+	}
+	const recorded = schema?.[RECORDED];
+	if (typeof recorded !== "object" || recorded === null || Array.isArray(recorded)) return fail(`no "${RECORDED}" record in it`);
+	for (const [name, definition] of Object.entries(recorded)) if (typeof definition !== "object" || definition === null || Array.isArray(definition)) fail(`the record for "${name}" is not a definition`);
+	return new Map(Object.entries(recorded));
+}
+/** The record, or nothing when there is none to read: for a refresh, which writes a new one. */
+function recordedToolsIfAny(configPath) {
+	try {
+		return recordedTools(configPath);
+	} catch {
+		return;
+	}
+}
+/**
+* Read a config into what `wrap` takes, saying which file is wrong and how.
+* Without `record: false`, the record beside it must be there and must cover
+* every tool the config names.
+*/
+function readWrapConfig(configPath, { record = true } = {}) {
+	const fail = (problem) => {
+		throw new Error(`${configPath}: ${problem}`);
+	};
+	let text;
+	try {
+		text = readFileSync(configPath, "utf8");
+	} catch {
+		return fail(`cannot read it. Create it with: mcp-authz tools --out ${configPath} -- <server command>`);
+	}
+	let value;
+	try {
+		value = parseJsonc(text);
+	} catch (error) {
+		return fail(`not valid JSONC (${error instanceof Error ? error.message : String(error)}). Look for a missing comma or quote, or start again: move it aside (mv ${configPath} ${configPath}.bak), then run mcp-authz tools --out ${configPath} -- <server command>`);
+	}
+	const config = value;
+	const unknown = (object, known, prefix = "") => {
+		if (typeof object !== "object" || object === null) return;
+		for (const key of Object.keys(object)) if (!known.includes(key)) fail(`unknown key "${prefix}${key}"; expected one of: ${known.join(", ")}.`);
+	};
+	unknown(config, [
+		"$schema",
+		"server",
+		"allow",
+		"deny"
+	]);
+	unknown(config?.server, [
+		"command",
+		"args",
+		"cwd"
+	], "server.");
+	const strings = (list) => Array.isArray(list) && list.every((item) => typeof item === "string");
+	if (typeof config?.server?.command !== "string") fail("\"server.command\" must be a string.");
+	const cwd = config.server.cwd ?? ".";
+	if (typeof cwd !== "string") fail("\"server.cwd\" must be a path.");
+	const args = config.server.args ?? [];
+	if (!strings(args)) fail("\"server.args\" must be a list of strings.");
+	if (config.allow !== void 0 && config.deny !== void 0) fail("use \"allow\" or \"deny\", not both.");
+	for (const key of ["allow", "deny"]) if (config[key] !== void 0 && !strings(config[key])) fail(`"${key}" must be a list of tool names.`);
+	const pinned = record ? recordedTools(configPath) : void 0;
+	const unrecorded = (config.allow ?? config.deny ?? []).filter((name) => !pinned?.has(name));
+	if (pinned && unrecorded.length > 0) fail(`${unrecorded.map((name) => `"${name}"`).join(", ")} not in the record beside it. Fix the name, or run mcp-authz tools --refresh ${configPath} to record the server again.`);
+	return {
+		command: config.server.command,
+		args,
+		cwd: resolve(dirname(resolve(configPath)), cwd),
+		...pinned ? { pinned } : {},
+		...config.allow ? { allow: config.allow } : {},
+		...config.deny ? { deny: config.deny } : {}
+	};
+}
+function entryFor(configPath) {
+	return {
+		name: basename(configPath, extname(configPath)),
+		entry: {
+			command: "npx",
+			args: [
+				"-y",
+				"mcp-authz",
+				"wrap",
+				resolve(configPath)
+			]
+		}
+	};
+}
+/**
+* Add the entry to a client's MCP config file, creating it if need be. Only how
+* the server starts changes. Other servers, and every other setting on this one
+* (`env`, `disabled`, `timeout`, whatever the client supports), stay as they
+* were, so a rerun keeps your API key and your on/off choice.
+*/
+function writeClientConfig(clientPath, configPath) {
+	const { name, entry } = entryFor(configPath);
+	let existing = {};
+	if (existsSync(clientPath)) try {
+		existing = parseJsonc(readFileSync(clientPath, "utf8"));
+	} catch (error) {
+		const reason = error instanceof Error ? error.message : String(error);
+		throw new Error(`${clientPath}: not valid JSON (${reason}). Fix it, or pass --client-out a new file.`, { cause: error });
+	}
+	const kept = { ...existing.mcpServers?.[name] };
+	delete kept.url;
+	if (kept.type !== void 0 && kept.type !== "stdio") delete kept.type;
+	const merged = {
+		...existing,
+		mcpServers: {
+			...existing.mcpServers,
+			[name]: {
+				...kept,
+				...entry
+			}
+		}
+	};
+	writeFileSync(clientPath, `${JSON.stringify(merged, null, 2)}\n`);
+}
+/** The `mcpServers` entry that runs a config, ready to paste. */
+function clientEntry(configPath) {
+	const { name, entry } = entryFor(configPath);
+	const args = entry.args.map((arg) => JSON.stringify(arg));
+	return [
+		`${JSON.stringify(name)}: {`,
+		"  \"command\": \"npx\",",
+		`  "args": [${args.join(", ")}]`,
+		"}"
+	].join("\n");
+}
+/**
+* JSON with comments and trailing commas, which is what a person editing the
+* file will produce. Strings are copied whole, so `//` inside one is safe.
+*/
+function parseJsonc(text) {
+	let out = "";
+	for (let i = 0; i < text.length; i++) {
+		const char = text[i];
+		if (char === "\"") {
+			let end = i + 1;
+			while (end < text.length && text[end] !== "\"") end += text[end] === "\\" ? 2 : 1;
+			out += text.slice(i, end + 1);
+			i = end;
+		} else if (char === "/" && text[i + 1] === "/") {
+			while (i < text.length && text[i] !== "\n") i++;
+			out += "\n";
+		} else if (char === "/" && text[i + 1] === "*") {
+			const end = text.indexOf("*/", i + 2);
+			i = end === -1 ? text.length : end + 1;
+		} else {
+			if (char === "]" || char === "}") out = out.replace(/,\s*$/, "");
+			out += char;
+		}
+	}
+	return JSON.parse(out);
+}
+/**
+* Relative to the config when that is the shorter way to say it, as it is for
+* a config kept beside its server in a repo; otherwise absolute, so a copied
+* file still finds the server.
+*/
+function storedCwd(configPath, cwd) {
+	const relativeTo = relative(dirname(resolve(configPath)), cwd) || ".";
+	return relativeTo.length <= cwd.length ? relativeTo : cwd;
+}
+/** The first sentence, and no more than a line's worth of it. */
+function clip(text, max = 80) {
+	const sentence = /^.*?[.!?](?=\s|$)/.exec(text)?.[0] ?? text;
+	return sentence.length > max ? `${sentence.slice(0, max - 1)}…` : sentence;
+}
+//#endregion
 //#region src/cli.ts
 /**
 * Two questions a policy file cannot answer by being read.
@@ -14,6 +837,10 @@ import { parseArgs } from "node:util";
 * decision carries the permissions, and only `policy.explain` carries the rules
 * that produced them.
 *
+* `tools` and `wrap` answer a third: which of a server's tools should this
+* session see. `wrap` reads JSON lines and nothing more, so it works in front of
+* any stdio server; `tools` is the one command that speaks MCP as a client.
+*
 * Deliberately no colour library and no argument parser. `node:util` has one,
 * and a dependency here would be a dependency in every install of the package.
 */
@@ -24,6 +851,12 @@ const USAGE = `mcp-authz — inspect a policy without running a server
   mcp-authz record --upstream <url> [--token <bearer>] [--out <permissions.ts>]
   mcp-authz record <connector.ts|--upstream <url>> --check <permissions.ts>
   mcp-authz explain <policy.json> --identity <identity.json>|- [--capabilities <map.json>]
+  mcp-authz tools -- <command> [args...]
+  mcp-authz tools --out <name.jsonc> [--client-out <mcp.json>] -- <command> [args...]
+  mcp-authz tools --check <name.jsonc>
+  mcp-authz tools --refresh <name.jsonc>
+  mcp-authz wrap <name.jsonc>
+  mcp-authz wrap [--allow <a,b> | --deny <a,b>] -- <command> [args...]
 
 Files
   <policy.json>     the object you would hand definePolicy
@@ -32,6 +865,12 @@ Files
   --identity        an Identity, or a decoded token payload (iss, sub, email,
                     email_verified, hd). Use - to read it from stdin.
 
+wrap
+  Runs a stdio MCP server and hides tools from whoever connects. Put it in
+  front of the server in your client's MCP config. With neither flag every
+  tool passes through; names are exact and comma-separated. For a remote
+  server, wrap the bridge: -- npx -y mcp-remote <url>
+
 Exit codes
   0  fine, warnings included
   1  the policy is invalid, or a capability no role can reach
@@ -47,6 +886,10 @@ function main(argv) {
 			upstream: { type: "string" },
 			token: { type: "string" },
 			check: { type: "string" },
+			allow: { type: "string" },
+			deny: { type: "string" },
+			refresh: { type: "string" },
+			"client-out": { type: "string" },
 			help: {
 				type: "boolean",
 				short: "h"
@@ -54,10 +897,21 @@ function main(argv) {
 		}
 	});
 	const [command, policyPath] = positionals;
+	const dashes = argv.indexOf("--");
+	const upstream = dashes === -1 ? [] : argv.slice(dashes + 1);
+	const [, ownPath] = positionals.slice(0, positionals.length - upstream.length);
 	if (values.help || !command) {
 		process.stdout.write(USAGE);
 		return values.help ? 0 : 1;
 	}
+	if (command === "tools") {
+		if (values.check) return checkWrapConfig(values.check, upstream);
+		return listTools(upstream, values);
+	}
+	if (command === "wrap") return runWrap(upstream, {
+		...values,
+		config: ownPath
+	});
 	if (command === "record") {
 		if (values.upstream) return record({
 			upstream: values.upstream,
@@ -73,6 +927,10 @@ function main(argv) {
 		process.stderr.write(`${command} needs a path to a policy file.\n`);
 		return 1;
 	}
+	if (command === "check" && isWrapConfig(policyPath)) {
+		process.stderr.write(`${policyPath} is a wrap config. To compare it with its server, which starts the command it names, run: mcp-authz tools --check ${policyPath}\n`);
+		return 1;
+	}
 	const policy = definePolicy(readJson(policyPath));
 	const run = (capabilities) => {
 		if (command === "check") return check(policy, capabilities);
@@ -90,6 +948,180 @@ function main(argv) {
 	if (values.capabilities.endsWith(".json")) return run(new Map(Object.entries(readJson(values.capabilities))));
 	return importCapabilities(values.capabilities).then(run);
 }
+/**
+* Print the names `wrap` takes, with the hints that help choose between them,
+* and with --out or --refresh save them as a config `wrap <file>` runs.
+*/
+function listTools(upstream, flags) {
+	const refuse = (message) => (process.stderr.write(`${message}\n`), 1);
+	if (flags.refresh && upstream.length > 0) return refuse("tools --refresh reruns the server its config names, so it takes no command after --.");
+	if (flags.refresh && flags.out) return refuse("tools takes --out or --refresh, not both.");
+	const saved = flags.refresh ? readWrapConfig(flags.refresh, { record: false }) : void 0;
+	const [command, ...args] = saved ? [saved.command, ...saved.args] : upstream;
+	const cwd = saved?.cwd ?? process.cwd();
+	if (saved) announce(saved, flags.refresh);
+	if (!command) return refuse("tools needs the server command after --, e.g. tools -- npx -y some-mcp");
+	const target = flags.refresh ?? flags.out;
+	return discover(command, args, cwd).then((discovered) => {
+		if (discovered === void 0) return 1;
+		const { tools, instructions } = discovered;
+		const width = Math.max(...tools.map((tool) => tool.name.length));
+		const cost = tools.map((tool) => `${formatTokens(tool.tokens)} tokens`);
+		const costWidth = Math.max(...cost.map((text) => text.length));
+		tools.forEach((tool, i) => {
+			process.stdout.write(`${tool.name.padEnd(width)}  ${tool.hint.padEnd(11)}  ${cost[i].padStart(costWidth)}  ${tool.description}`.trimEnd() + "\n");
+		});
+		for (const tool of tools.filter((t) => t.warnings.length > 0)) process.stderr.write(`⚠ ${tool.name} ${tool.warnings.join(" and ")}: read its definition before you allow it.\n`);
+		if (instructions !== void 0) {
+			process.stderr.write(`\nThe server's instructions to the model, which wrap holds to this record:\n  ${reveal(instructions)}\n`);
+			for (const warning of suspicious({ instructions })) process.stderr.write(`⚠ the instructions ${warning}: read them before you use this server.\n`);
+		}
+		if (!target) {
+			process.stderr.write("\nSave these as a config wrap can run: tools --out <name>.jsonc -- ...\n");
+			return 0;
+		}
+		const recorded = existsSync(target) ? recordedToolsIfAny(target) : void 0;
+		const approved = recorded?.get("server:instructions") ?? {};
+		const live = instructions === void 0 ? {} : { instructions };
+		if (recorded && changedFields(approved, live).length > 0) process.stderr.write([
+			"",
+			...describeChange("server instructions", approved, live, "recorded by this refresh").map((line) => line.replace("until you approve it", "and approved by saving: read it")),
+			""
+		].join("\n"));
+		const previous = existsSync(target) ? {
+			options: readWrapConfig(target, { record: false }),
+			...recorded ? { recorded } : {}
+		} : void 0;
+		const { allowed, commented, added, changed, tokens } = writeWrapConfig(target, {
+			command,
+			args,
+			cwd
+		}, discovered, previous);
+		const summary = !previous ? `${allowed} read-only allowed, ${commented} commented out for you to choose` : recorded ? `${allowed} allowed, ${commented} commented out, ${added} new and ${changed} changed since last saved, left commented out` : `no record to compare against, so all ${commented} commented out for you to approve again`;
+		const lines = [
+			"",
+			`Saved ${target} (${summary}) and ${schemaPathFor(target)}.`,
+			`The model sees ${formatTokens(tokens.allowed)} of ${formatTokens(tokens.total)} tokens of tool definitions.`
+		];
+		if (flags["client-out"]) {
+			writeClientConfig(flags["client-out"], target);
+			lines.push(`Added it to ${flags["client-out"]}; give it the env the server needs there.`);
+		}
+		lines.push("Add this to your client's mcpServers, with the env the server needs:", "", clientEntry(target), "");
+		process.stdout.write(lines.join("\n"));
+		return 0;
+	});
+}
+/**
+* Discovery with a next step for the two common stops: a command that is not
+* installed, and a server that exits at once, which usually means it wants an
+* API key. The server's own message is already on stderr above this one.
+*/
+async function discover(command, args, cwd) {
+	try {
+		return await discover$1(command, args, cwd);
+	} catch (error) {
+		const code = error.code;
+		process.stderr.write(code === "ENOENT" ? `Could not start ${command}: command not found. Install it, or give its full path.\n` : "The server exited before listing its tools. Its own error, if it printed one, is above.\nIf it needs credentials, export them in this shell first: the env in your client\nconfig is not seen here.\n");
+		return;
+	}
+}
+/** Say what is about to run when the command comes from a file. */
+function announce(options, path) {
+	process.stderr.write(`Running ${[options.command, ...options.args].join(" ")} from ${path}\n`);
+}
+function isWrapConfig(path) {
+	if (path === "-") return false;
+	try {
+		const value = parseJsonc(readFileSync(path, "utf8"));
+		return typeof value === "object" && value !== null && "server" in value;
+	} catch {
+		return false;
+	}
+}
+/**
+* Ask the server what it offers now, and compare it with the config and with
+* the catalogue recorded beside it. Exits 1 on any difference, the way
+* `record --check` does, so CI notices an upgrade that renamed a tool.
+*/
+async function checkWrapConfig(path, upstream) {
+	if (upstream.length > 0) {
+		process.stderr.write("tools --check runs the server its config names, so it takes no command after --.\n");
+		return 1;
+	}
+	const options = readWrapConfig(path);
+	announce(options, path);
+	const found = await discover(options.command, options.args, options.cwd);
+	if (found === void 0) return 1;
+	const discovered = found.tools;
+	const live = discovered.map((tool) => tool.name);
+	const recorded = options.pinned;
+	const recordedNames = [...recorded.keys()].filter((name) => name !== INSTRUCTIONS);
+	const missing = (options.allow ?? options.deny ?? []).filter((name) => !live.includes(name));
+	const added = live.filter((name) => !recorded.has(name));
+	const removed = recordedNames.filter((name) => !live.includes(name));
+	const changed = discovered.flatMap((tool) => {
+		const approved = recorded.get(tool.name);
+		const fields = approved ? changedFields(approved, tool.pin) : [];
+		return fields.length > 0 ? [{
+			name: tool.name,
+			approved,
+			live: tool.pin,
+			fields
+		}] : [];
+	});
+	const approvedInstructions = recorded.get("server:instructions") ?? {};
+	const liveInstructions = found.instructions === void 0 ? {} : { instructions: found.instructions };
+	const instructionsChanged = changedFields(approvedInstructions, liveInstructions).length > 0;
+	if (missing.length === 0 && added.length === 0 && removed.length === 0 && changed.length === 0 && !instructionsChanged) {
+		process.stdout.write(`${live.length} tools, as recorded in ${schemaPathFor(path)}\n`);
+		return 0;
+	}
+	const lines = [`${path} does not match the server:`, ""];
+	for (const name of missing) lines.push(`  ? ${name}`, `      in "${options.allow ? "allow" : "deny"}", but the server has no such tool`);
+	for (const name of added) lines.push(`  + ${name}`, `      new since last saved; ${options.allow ? "hidden, since it is not in \"allow\"" : "shown"}`);
+	for (const name of removed) lines.push(`  - ${name}`, "      recorded, but the server no longer offers it");
+	for (const tool of changed) {
+		const state = options.allow?.includes(tool.name) ? "hidden by wrap" : "not in use";
+		lines.push(...describeChange(tool.name, tool.approved, tool.live, state));
+	}
+	if (instructionsChanged) lines.push(...describeChange("server instructions", approvedInstructions, liveInstructions, "removed by wrap"));
+	lines.push("", missing.length > 0 ? `Fix or remove the "?" names in ${path}, then run tools --refresh ${path} to record the rest.` : `Run tools --refresh ${path} to record the change. Your choices are kept; new and changed tools stay off until you switch them on.`, "");
+	process.stdout.write(lines.join("\n"));
+	return 1;
+}
+function runWrap(upstream, { allow, deny, config }) {
+	const refuse = (message) => (process.stderr.write(`${message}\n`), 1);
+	if (allow !== void 0 && deny !== void 0) return refuse("wrap takes --allow or --deny, not both.");
+	if (config !== void 0) {
+		if (upstream.length > 0) return refuse("wrap takes a config or a command after --, not both.");
+		if (allow !== void 0 || deny !== void 0) return refuse("wrap takes a config or --allow/--deny, not both: the list lives in the file.");
+	}
+	const names = (list) => list?.split(",").map((name) => name.trim()).filter(Boolean);
+	const [command, ...args] = upstream;
+	if (config === void 0 && !command) return refuse("wrap needs a config, e.g. wrap cases.jsonc, or the server command after --, e.g. wrap --deny x -- npx -y some-mcp");
+	const options = config ? readWrapConfig(config) : {
+		command,
+		args,
+		allow: names(allow),
+		deny: names(deny)
+	};
+	const stopped = new AbortController();
+	for (const signal of [
+		"SIGINT",
+		"SIGTERM",
+		"SIGHUP"
+	]) process.once(signal, () => stopped.abort());
+	return wrap(options, {
+		input: process.stdin,
+		output: process.stdout,
+		log: (line) => process.stderr.write(`${line}\n`),
+		signal: stopped.signal
+	}).then((code) => {
+		process.stdin.destroy();
+		return code;
+	});
+}
 /** Read the map out of a module `record` produced, or one written by hand. */
 async function importCapabilities(path) {
 	const loaded = await import(pathToFileURL(resolve(path)).href);
@@ -98,13 +1130,7 @@ async function importCapabilities(path) {
 	return new Map(Object.entries(map));
 }
 async function record(source, out, against) {
-	let toolkit;
-	try {
-		toolkit = await import("./testing.js");
-	} catch {
-		process.stderr.write("record needs @modelcontextprotocol/client, which is an optional peer.\n  npm install -D @modelcontextprotocol/client\n");
-		return 1;
-	}
+	const toolkit = await import("./testing.js");
 	let capabilities;
 	if ("upstream" in source) capabilities = await toolkit.recordUpstream(source.upstream, { bearer: source.token });
 	else {
@@ -130,24 +1156,42 @@ async function record(source, out, against) {
 async function drift(live, path) {
 	const loaded = await import(pathToFileURL(resolve(path)).href);
 	const priced = Object.keys(loaded.PERMISSIONS ?? {});
-	const recorded = loaded.FINGERPRINTS ?? {};
+	const recorded = new Map(Object.entries(loaded.DEFINITIONS ?? {}));
 	const added = live.names.filter((name) => !priced.includes(name));
 	const removed = priced.filter((name) => !live.names.includes(name));
-	const changed = live.names.filter((name) => priced.includes(name) && recorded[name] && recorded[name] !== live.fingerprints[name]);
-	const unbaselined = Object.keys(recorded).length === 0 ? ` — ${path} carries no FINGERPRINTS, so definitions were not compared; re-record to add one` : "";
-	if (added.length === 0 && removed.length === 0 && changed.length === 0) {
-		process.stdout.write(`${live.names.length} capabilities, names unchanged since ${path}${unbaselined}\n`);
+	const unrecorded = missingDefinitions(priced.filter((name) => live.names.includes(name)), recorded);
+	const changed = live.names.filter((name) => priced.includes(name) && recorded.has(name) && changedFields(recorded.get(name), live.definitions[name]).length > 0);
+	const approvedInstructions = recorded.get("server:instructions") ?? {};
+	const liveInstructions = live.definitions["server:instructions"] ?? {};
+	const instructionsChanged = changedFields(approvedInstructions, liveInstructions).length > 0;
+	if (added.length === 0 && removed.length === 0 && changed.length === 0 && unrecorded.length === 0 && !instructionsChanged) {
+		process.stdout.write(`${live.names.length} capabilities, unchanged since ${path}\n`);
 		return 0;
 	}
 	const lines = ["The server no longer matches the recorded capabilities:", ""];
 	for (const name of added) lines.push(`  + ${name}`, "      never priced, so nobody decided who may reach it");
 	for (const name of removed) lines.push(`  - ${name}`, "      priced here, but the server no longer offers it");
-	for (const name of changed) lines.push(`  ~ ${name}`, "      same name, different definition than the one recorded");
-	if (unbaselined) lines.push("", `Note:${unbaselined.slice(3)}`);
+	for (const name of unrecorded) lines.push(`  ? ${name}`, "      priced, but DEFINITIONS has no record of it, so a change would go unseen");
+	for (const name of changed) lines.push(...describeChange(name, recorded.get(name), live.definitions[name], "hidden by createMcpProxy"));
+	if (instructionsChanged) lines.push(...describeChange("server instructions", approvedInstructions, liveInstructions, "removed by createMcpProxy"));
 	lines.push("", "Re-record when the change is expected, and review the diff.", "");
 	process.stdout.write(lines.join("\n"));
 	return 1;
 }
+/**
+* A changed definition, with the words themselves: a changed description is
+* how a server steers the model, and "definition changed" alone gives you
+* nothing to judge.
+*/
+function describeChange(name, recorded, live, state) {
+	const fields = changedFields(recorded, live);
+	return [
+		`  ~ ${name}`,
+		`      ${fields.join(", ")} changed since recorded; ${state} until you approve it`,
+		...fields.flatMap((field) => [`      ${field} was: ${reveal(JSON.stringify(recorded[field]) ?? "(absent)")}`, `      ${field} now: ${reveal(JSON.stringify(live[field]) ?? "(absent)")}`]),
+		...suspicious(live).map((warning) => `      ⚠ now ${warning}`)
+	];
+}
 function check(policy, capabilities) {
 	const lines = [`${policy.roles.size} role${policy.roles.size === 1 ? "" : "s"}`, `${policy.permissions.length} permission${policy.permissions.length === 1 ? "" : "s"}`];
 	if (capabilities) lines.push(`${capabilities.size} capabilities`);