mcp-authz 0.4.0 → 0.5.0

package/dist/cli.js

@@ -1,5 +1,8 @@
 #!/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 { 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";
@@ -171,9 +174,42 @@ public static class McpAuthzJob {
 `;
 //#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 visible = (name) => options.allow ? options.allow.includes(name) : !options.deny?.includes(name);
+	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], {
@@ -188,13 +224,73 @@ function wrap(options, io) {
 	});
 	child.stdin.on("error", () => {});
 	const listing = /* @__PURE__ */ new Set();
-	const seen = /* @__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].filter((name) => !visible(name)).sort();
-		io.log(`mcp-authz wrap: ${seen.size - hidden.length}/${seen.size} tools exposed` + (hidden.length > 0 ? `, hidden: ${hidden.join(", ")}` : ""));
+		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) => {
@@ -202,9 +298,10 @@ function wrap(options, io) {
 		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: typeof id === "string" || typeof id === "number" ? id : null,
+				id: replyTo,
 				error: {
 					code,
 					message: reason
@@ -212,7 +309,7 @@ function wrap(options, io) {
 			}));
 		};
 		try {
-			value = JSON.parse(line);
+			value = parseChecked(line);
 		} catch {
 			refuse(-32700, "Parse error: mcp-authz wrap forwards only messages it can read");
 			return;
@@ -226,12 +323,17 @@ function wrap(options, io) {
 			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" ? `Tool "${name}" is blocked by mcp-authz wrap` : "tools/call needs a tool name"
+				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",
@@ -240,7 +342,17 @@ function wrap(options, io) {
 			}));
 			return;
 		}
-		child.stdin.write(`${line}\n`);
+		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) => {
@@ -285,12 +397,45 @@ function wrap(options, io) {
 	else io.signal?.addEventListener("abort", stop, { once: true });
 	onLines(child.stdout, (line) => {
 		const message = parse(line);
-		if (message?.method === void 0 && message?.id !== void 0 && listing.delete(message.id) && message.result?.tools) {
-			for (const tool of message.result.tools) seen.add(tool.name);
+		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);
@@ -328,34 +473,6 @@ function onLines(stream, onLine) {
 		buffered = "";
 	});
 }
-/**
-* Whether any object repeats a key, compared after unescaping, so `"name"` and
-* `"na\u006de"` are the same key. Only called on text JSON.parse accepted,
-* which is what lets it skip validating anything else.
-*/
-function hasDuplicateKey(text) {
-	const scopes = [];
-	for (let i = 0; i < text.length; i++) {
-		const char = text[i];
-		if (char === "{") scopes.push(/* @__PURE__ */ new Set());
-		else if (char === "[") scopes.push(void 0);
-		else if (char === "}" || char === "]") scopes.pop();
-		else if (char === "\"") {
-			let end = i + 1;
-			while (text[end] !== "\"") end += text[end] === "\\" ? 2 : 1;
-			let next = end + 1;
-			while (text[next] === " " || text[next] === "	" || text[next] === "\r" || text[next] === "\n") next++;
-			const scope = scopes.at(-1);
-			if (scope && text[next] === ":") {
-				const key = JSON.parse(text.slice(i, end + 1));
-				if (scope.has(key)) return true;
-				scope.add(key);
-			}
-			i = end;
-		}
-	}
-	return false;
-}
 function parse(line) {
 	try {
 		const value = JSON.parse(line);
@@ -366,6 +483,8 @@ function parse(line) {
 }
 //#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");
@@ -373,14 +492,16 @@ async function discover$1(command, args, cwd) {
 	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));
-	await client.connect(new StdioClientTransport({
+	const transport = new StdioClientTransport({
 		command,
 		args: [...args],
 		env,
 		...cwd ? { cwd } : {}
-	}));
+	});
+	const raw = captureListings(transport);
+	await client.connect(transport);
 	try {
 		const tools = [];
 		let cursor;
@@ -388,13 +509,20 @@ async function discover$1(command, args, cwd) {
 			const page = await client.listTools(cursor ? { cursor } : void 0);
 			for (const tool of page.tools) tools.push({
 				name: tool.name,
-				hint: tool.annotations?.readOnlyHint ? "read-only" : tool.annotations?.destructiveHint ? "destructive" : "unknown",
-				description: tool.description?.split("\n")[0]?.trim() ?? "",
-				params: Object.keys(tool.inputSchema.properties ?? {}).map((param) => tool.inputSchema.required?.includes(param) ? `${param} (required)` : param)
+				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);
-		return tools.sort((a, b) => a.name.localeCompare(b.name));
+		const instructions = client.getInstructions();
+		return {
+			tools: tools.sort((a, b) => a.name.localeCompare(b.name)),
+			...typeof instructions === "string" ? { instructions } : {}
+		};
 	} finally {
 		await client.close();
 	}
@@ -406,23 +534,28 @@ function schemaPathFor(configPath) {
 /**
 * Write the config and its schema.
 *
-* In a fresh config, destructive tools start commented out. Over an existing
-* config, the choices in it are kept and a tool the server added since starts
-* commented out, so a refresh keeps your edits and waits for you to switch new
-* tools on.
+* 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, previous) {
+function writeWrapConfig(configPath, server, { tools, instructions }, previous) {
 	const schemaPath = schemaPathFor(configPath);
-	const isNew = (name) => previous?.recorded !== void 0 && !previous.recorded.includes(name);
+	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 !== "destructive";
-		if (isNew(tool.name)) return false;
+		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.hint}${tool.description ? ` · ${clip(tool.description)}` : ""}`;
+	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 = [
 		"{",
@@ -444,14 +577,22 @@ function writeWrapConfig(configPath, server, tools, previous) {
 		""
 	].join("\n");
 	writeFileSync(configPath, text);
-	writeFileSync(schemaPath, `${JSON.stringify(schemaFor(tools), null, 2)}\n`);
+	writeFileSync(schemaPath, `${JSON.stringify(schemaFor(tools, instructions), null, 2)}\n`);
 	return {
 		allowed: on.length,
 		commented: off.length,
-		added: tools.filter((tool) => isNew(tool.name)).length
+		added: tools.filter(isNew).length,
+		changed: tools.filter(isChanged).length,
+		tokens: {
+			allowed: sum(on),
+			total: sum(tools)
+		}
 	};
 }
-function schemaFor(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" },
@@ -494,24 +635,51 @@ function schemaFor(tools) {
 		definitions: { tool: tools.length > 0 ? { anyOf: tools.map((tool) => ({
 			const: tool.name,
 			description: note(tool)
-		})) } : { not: {} } }
+		})) } : { not: {} } },
+		[RECORDED]: Object.fromEntries([...tools.map((tool) => [tool.name, tool.pin]), ...instructions === void 0 ? [] : [[INSTRUCTIONS, { instructions }]]])
 	};
 	function note(tool) {
-		const said = tool.description ? `${tool.hint} · ${tool.description}` : tool.hint;
+		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;
 	}
 }
-/** Every tool name the schema beside a config recorded, if it is there. */
+/**
+* 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 {
-		const tool = JSON.parse(readFileSync(schemaPathFor(configPath), "utf8")).definitions?.tool;
-		return tool ? (tool.anyOf ?? []).map((entry) => entry.const) : void 0;
+		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. */
-function readWrapConfig(configPath) {
+/**
+* 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}`);
 	};
@@ -551,10 +719,14 @@ function readWrapConfig(configPath) {
 	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 } : {}
 	};
@@ -568,7 +740,6 @@ function entryFor(configPath) {
 				"-y",
 				"mcp-authz",
 				"wrap",
-				"--config",
 				resolve(configPath)
 			]
 		}
@@ -682,10 +853,10 @@ const USAGE = `mcp-authz — inspect a policy without running a server
   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 --config <name.jsonc> --refresh
-  mcp-authz wrap [--allow <a,b> | --deny <a,b>] -- <command> [args...]
-  mcp-authz wrap --config <name.jsonc>
   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
@@ -697,7 +868,8 @@ Files
 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.
+  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
@@ -716,8 +888,7 @@ function main(argv) {
 			check: { type: "string" },
 			allow: { type: "string" },
 			deny: { type: "string" },
-			config: { type: "string" },
-			refresh: { type: "boolean" },
+			refresh: { type: "string" },
 			"client-out": { type: "string" },
 			help: {
 				type: "boolean",
@@ -728,6 +899,7 @@ 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;
@@ -736,7 +908,10 @@ function main(argv) {
 		if (values.check) return checkWrapConfig(values.check, upstream);
 		return listTools(upstream, values);
 	}
-	if (command === "wrap") return runWrap(upstream, values);
+	if (command === "wrap") return runWrap(upstream, {
+		...values,
+		config: ownPath
+	});
 	if (command === "record") {
 		if (values.upstream) return record({
 			upstream: values.upstream,
@@ -775,37 +950,59 @@ function main(argv) {
 }
 /**
 * Print the names `wrap` takes, with the hints that help choose between them,
-* and with --out or --refresh save them as a config `wrap --config` runs.
+* 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 && !flags.config) return refuse("--refresh rewrites a saved config: tools --config <name>.jsonc --refresh");
-	if (flags.config && upstream.length > 0) return refuse("tools takes --config or a command after --, not both: the config names its server.");
-	const saved = flags.config ? readWrapConfig(flags.config) : void 0;
+	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.config);
+	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.config : flags.out;
-	return discover(command, args, cwd).then((tools) => {
-		if (tools === void 0) return 1;
+	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));
-		for (const tool of tools) process.stdout.write(`${tool.name.padEnd(width)}  ${tool.hint.padEnd(11)}  ${tool.description}`.trimEnd() + "\n");
+		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),
-			recorded: recordedTools(target)
+			options: readWrapConfig(target, { record: false }),
+			...recorded ? { recorded } : {}
 		} : void 0;
-		const { allowed, commented, added } = writeWrapConfig(target, {
+		const { allowed, commented, added, changed, tokens } = writeWrapConfig(target, {
 			command,
 			args,
 			cwd
-		}, tools, previous);
-		const summary = previous ? `${allowed} allowed, ${commented} commented out, ${added} new since last saved, left commented out` : `${allowed} allowed, ${commented} destructive commented out`;
-		const lines = ["", `Saved ${target} (${summary}) and ${schemaPathFor(target)}.`];
+		}, 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.`);
@@ -854,23 +1051,42 @@ async function checkWrapConfig(path, upstream) {
 	}
 	const options = readWrapConfig(path);
 	announce(options, path);
-	const discovered = await discover(options.command, options.args, options.cwd);
-	if (discovered === void 0) return 1;
+	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 = recordedTools(path);
+	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 = recorded ? live.filter((name) => !recorded.includes(name)) : [];
-	const removed = recorded ? recorded.filter((name) => !live.includes(name)) : [];
-	if (missing.length === 0 && added.length === 0 && removed.length === 0) {
-		const against = recorded ? `as recorded in ${schemaPathFor(path)}` : `every name in ${path} found`;
-		process.stdout.write(`${live.length} tools, ${against}\n`);
+	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");
-	lines.push("", missing.length > 0 ? `Fix or remove the "?" names in ${path}, then run tools --config ${path} --refresh to record the rest.` : `Run tools --config ${path} --refresh to record the change. Your choices are kept; new tools stay off.`, "");
+	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;
 }
@@ -878,12 +1094,12 @@ 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 --config or a command after --, not both.");
-		if (allow !== void 0 || deny !== void 0) return refuse("wrap takes --config or --allow/--deny, not both: the list lives in the file.");
+		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 the server command after --, e.g. wrap --deny x -- npx -y some-mcp");
+	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,
@@ -940,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`);