opencode-workflow-guard 1.15.5 → 1.16.0

package/src/lib/mcp-inventory.ts

@@ -0,0 +1,86 @@
+/**
+ * Host MCP server inventory for the guard's MCP policy.
+ *
+ * The MCP policy identifies a guarded live-system call by name tokens
+ * (`github`, `azure`, `ado`, ...). That static list covers the common servers,
+ * but it cannot learn a server the operator renamed, and it cannot tell when
+ * the host's roster changed.
+ *
+ * `ctx.mcp.list()` reports the servers for this location, and the
+ * `mcp.tools.changed` event says when that roster went stale. Together they
+ * widen the guarded token set from host-declared names only.
+ *
+ * Two deliberate limits:
+ *
+ * - **Widen-only.** A server the operator removed must not silently unguard a
+ *   tool that still names it. Removal therefore contributes nothing; the
+ *   static defaults in `policies/mcp.ts` remain the floor.
+ * - **Never a replacement for the policy.** A token learned here only reaches
+ *   the same `mcpMutationTool` decision the static list already used. Nothing
+ *   here can allow a call the policy would otherwise block.
+ */
+
+import { addGuardedMcpTokens, GUARDED_MCP_SERVERS } from "../policies/mcp.ts";
+
+/** A server name counts as guarded when it names a known live-system product. */
+const GUARDED_SERVER_TOKEN_RE =
+	/(?:^|[^a-z0-9])(?:github|gh|azure|azmcp|ado|devops|azuredevops)(?:[^a-z0-9]|$)/;
+
+/**
+ * Turn a host server name into tokens for the policy's token scan.
+ *
+ * Host names are free-form (`github`, `github-enterprise`, `Azure DevOps`), so
+ * a guarded server contributes its tokens rather than a single literal. A name
+ * that does not look guarded contributes nothing.
+ */
+export function guardedTokensFromServerName(serverName: string): string[] {
+	if (!serverName || !GUARDED_SERVER_TOKEN_RE.test(serverName.toLowerCase())) return [];
+	return serverName
+		.toLowerCase()
+		.replace(/[^a-z0-9]+/g, " ")
+		.trim()
+		.split(" ")
+		.filter(Boolean);
+}
+
+/**
+ * Read the MCP servers the host reports.
+ *
+ * `undefined` means "the host could not tell us", which is different from an
+ * empty roster. Callers must not treat unknown as "nothing is guarded".
+ *
+ * The 2.0.10 MCP domain types `list` with a location filter and returns
+ * `{ data: [...] }`; the duck-typed read tolerates a bare array too, because a
+ * shape mismatch must degrade to unknown rather than throw.
+ */
+export async function listHostMcpServerNames(ctx: unknown): Promise<string[] | undefined> {
+	const api = (ctx as { mcp?: { list?: (input?: unknown) => Promise<unknown> } } | undefined)?.mcp;
+	if (!api || typeof api.list !== "function") return undefined;
+	try {
+		const result = await api.list.call(api, {});
+		const data = (result as { data?: unknown } | undefined)?.data;
+		const entries = Array.isArray(data) ? data : Array.isArray(result) ? result : undefined;
+		if (!entries) return undefined;
+		return entries
+			.map((entry) => (typeof entry === "string" ? entry : (entry as { name?: unknown })?.name))
+			.filter((name): name is string => typeof name === "string" && name.length > 0);
+	} catch {
+		return undefined;
+	}
+}
+
+/**
+ * Merge host-declared server names into the guarded token set.
+ *
+ * Returns the tokens this call added, so the caller can journal widening once
+ * instead of logging the whole set on every event. `undefined` input (host
+ * could not answer) adds nothing and is not an error.
+ */
+export function recordHostMcpServers(serverNames: readonly string[] | undefined): string[] {
+	if (!serverNames) return [];
+	const tokens = serverNames.flatMap((name) => guardedTokensFromServerName(name));
+	return addGuardedMcpTokens(tokens);
+}
+
+/** Static defaults, for callers that only need to report the floor. */
+export const STATIC_GUARDED_MCP_SERVERS = GUARDED_MCP_SERVERS;

package/src/lib/permission-seat.ts

@@ -0,0 +1,119 @@
+/**
+ * V2 permission seat: `ctx.permission.hook("evaluate")`.
+ *
+ * Two enforcement seats, deliberately complementary:
+ *
+ * - `evaluate` sees the host's normalized permission check (an `action` plus
+ *   its `resources`) before anything runs, so a denial there means the tool
+ *   never starts. It does NOT see raw tool input, so tool-lifecycle work
+ *   (todo transitions, stale-write observations, post-edit snapshots) stays in
+ *   `execute.before`.
+ * - `execute.before` sees the raw arguments and aborts with a specific
+ *   remediation message, but only after the permission layer has allowed.
+ *
+ * The seat can only tighten. An explicit configured `deny` is final: the host
+ * never invokes the hook for it (it resolves deny first and only calls the hook
+ * when the configured effect is allow/ask). A hook denial is therefore always a
+ * response to something the host would otherwise permit.
+ *
+ * Every decision here is a simulation of the policy core: `simulate: true`
+ * skips mutation accounting, file claims, verification runs, and durable audit
+ * writes, because the same call is evaluated for real in `execute.before`.
+ */
+
+import { guardToolCallImpl } from "./guard-dispatcher.ts";
+import { getSessionBoundWorkspace, runWithRuntimeState } from "./state.ts";
+import { mcpMutationTool } from "../policies/mcp.ts";
+import type { PolicyDecision } from "./types.ts";
+
+/** The subset of the host's permission evaluation this seat reads. */
+export interface PermissionSeatEvent {
+	readonly sessionID: string;
+	readonly agent?: string;
+	readonly action: string;
+	readonly resources: readonly string[];
+	readonly effect: "allow" | "deny" | "ask";
+}
+
+export interface PermissionSeatDeps {
+	workspaceRoot: string;
+	client: unknown;
+}
+
+export interface PermissionSeatResult {
+	/** The effect the seat leaves in place. */
+	effect: "allow" | "deny";
+	/** Set only when the seat denied. */
+	decision?: PolicyDecision;
+	/** The guard tool the action was mapped onto, for attribution. */
+	mappedTool?: string;
+}
+
+const EDIT_ACTIONS = new Set(["edit", "write", "patch", "apply_patch"]);
+
+function mappedToolFor(action: string): { tool: string; input: (resource: string) => unknown } | undefined {
+	if (action === "shell" || action === "bash") {
+		return { tool: "bash", input: (resource) => ({ command: resource }) };
+	}
+	if (action === "read" || action === "read_file") {
+		return { tool: "read", input: (resource) => ({ filePath: resource }) };
+	}
+	if (EDIT_ACTIONS.has(action)) {
+		// `edit` is the canonical mutation tool name: it carries the tamper,
+		// secret, boundary, protected-branch, and todo checks.
+		return { tool: "edit", input: (resource) => ({ filePath: resource }) };
+	}
+	return undefined;
+}
+
+/**
+ * Evaluate one host permission request. Returns the effect to leave in place.
+ *
+ * Unmapped actions (`external_directory`, `glob`, `grep`, `webfetch`,
+ * `websearch`, `question`, `subagent`, ...) stay with the host: config policy
+ * and the user prompt are the right seats for them, and the guard's shell,
+ * file, and MCP checks have nothing to add. The hook still journals them.
+ */
+export async function evaluatePermissionSeat(
+	event: PermissionSeatEvent,
+	deps: PermissionSeatDeps,
+): Promise<PermissionSeatResult> {
+	if (event.effect === "deny") return { effect: "deny" };
+	const resources = event.resources.filter((resource): resource is string => typeof resource === "string" && resource.length > 0);
+	if (resources.length === 0) return { effect: "allow" };
+	const workspaceRoot = getSessionBoundWorkspace(event.sessionID) || deps.workspaceRoot;
+	const context = { sessionID: event.sessionID, agent: event.agent, worktree: workspaceRoot, simulate: true };
+	const decide = (tool: string, input: unknown): Promise<PolicyDecision> =>
+		runWithRuntimeState(workspaceRoot, deps.client, () => guardToolCallImpl(tool, input, context));
+
+	const mapping = mappedToolFor(event.action);
+	if (mapping) {
+		for (const resource of resources) {
+			const decision = await decide(mapping.tool, mapping.input(resource));
+			if (decision.status !== "allowed") {
+				return {
+					effect: "deny",
+					decision: { ...decision, message: `[workflow-guard permission.evaluate] ${decision.message}` },
+					mappedTool: mapping.tool,
+				};
+			}
+		}
+		return { effect: "allow", mappedTool: mapping.tool };
+	}
+
+	// `<server>_<tool>` MCP actions: only the guarded live-system servers are
+	// mapped (GitHub/Azure DevOps), matching the execute.before MCP policy.
+	for (const resource of resources) {
+		if (!mcpMutationTool(event.action) && !mcpMutationTool(resource)) continue;
+		const decision = await decide(event.action, {});
+		if (decision.status !== "allowed") {
+			return {
+				effect: "deny",
+				decision: { ...decision, message: `[workflow-guard permission.evaluate] ${decision.message}` },
+				mappedTool: event.action,
+			};
+		}
+		return { effect: "allow", mappedTool: event.action };
+	}
+	return { effect: "allow" };
+}

package/src/lib/plugin-instance.ts

@@ -0,0 +1,124 @@
+/**
+ * Process-local plugin instance registry.
+ *
+ * OpenCode 2 merges plugin arrays instead of replacing them, so naming the same
+ * package in both the global and the project config loads the same entrypoint
+ * twice under two ids. Two instances register duplicate hooks and duplicate
+ * tool definitions: every tool call is evaluated and audited twice, and the two
+ * instances can disagree about `effectiveRoot` in the same tick, which primes
+ * the process-global workspace latch from two roots.
+ *
+ * The first instance for a (module path, workspace root) key owns enforcement.
+ * A later instance with the same key stays inert and records a warn-level
+ * duplicate so the misconfiguration is visible in the audit trail. Different
+ * workspace roots are legitimate (concurrent loops share one process) and get
+ * independent keys.
+ */
+
+import { realpathSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { resolve } from "node:path";
+import { audit } from "./audit.ts";
+
+export interface PluginInstanceInfo {
+	/** Stable key: resolved module path plus resolved workspace root. */
+	key: string;
+	modulePath: string;
+	workspaceRoot: string;
+	/** True when this key already had an active instance in this process. */
+	duplicate: boolean;
+}
+
+interface ActiveInstance {
+	modulePath: string;
+	workspaceRoot: string;
+	registrations: number;
+}
+
+// Deliberately process-global, not module-global: OpenCode can load the same
+// package twice from two distinct paths (a cache copy plus a source checkout),
+// and each copy evaluates this module separately. A `Symbol.for` slot on
+// `globalThis` gives both copies one registry so the duplicate stays visible
+// even when the module instances differ.
+const INSTANCE_REGISTRY = Symbol.for("opencode-workflow-guard.plugin-instances.v1");
+const globalRegistry = globalThis as unknown as Record<symbol, Map<string, ActiveInstance> | undefined>;
+const activeInstances: Map<string, ActiveInstance> =
+	globalRegistry[INSTANCE_REGISTRY] ?? (globalRegistry[INSTANCE_REGISTRY] = new Map());
+
+/** Resolved path of the loaded plugin module; the stable half of the key. */
+export function loadedPluginModulePath(moduleUrl: string = import.meta.url): string {
+	const lexical = (() => {
+		try {
+			return fileURLToPath(moduleUrl);
+		} catch {
+			return moduleUrl;
+		}
+	})();
+	try {
+		return realpathSync(lexical);
+	} catch {
+		return lexical;
+	}
+}
+
+function canonicalRoot(root: string): string {
+	try {
+		return realpathSync(resolve(root));
+	} catch {
+		return resolve(root);
+	}
+}
+
+export function pluginInstanceKey(modulePath: string, workspaceRoot: string): string {
+	return `${canonicalRoot(workspaceRoot)}::${modulePath}`;
+}
+
+/**
+ * Register one setup call. A duplicate key is journaled at warn level and the
+ * caller must stay inert: returning early is what makes the load count one
+ * policy decision per tool call instead of two.
+ */
+export function registerPluginInstance(options: {
+	modulePath?: string;
+	workspaceRoot: string;
+}): PluginInstanceInfo {
+	const modulePath = options.modulePath ?? loadedPluginModulePath();
+	const workspaceRoot = canonicalRoot(options.workspaceRoot);
+	const key = pluginInstanceKey(modulePath, workspaceRoot);
+	const existing = activeInstances.get(key);
+	if (existing) {
+		existing.registrations++;
+		audit({
+			ts: new Date().toISOString(),
+			tool: "plugin.instance",
+			decision: "allow",
+			phase: "event",
+			reason: "duplicate_plugin_load",
+			input: { instanceKey: key, modulePath, workspaceRoot, registrations: existing.registrations },
+		});
+		return { key, modulePath, workspaceRoot, duplicate: true };
+	}
+	activeInstances.set(key, { modulePath, workspaceRoot, registrations: 1 });
+	audit({
+		ts: new Date().toISOString(),
+		tool: "plugin.instance",
+		decision: "allow",
+		phase: "event",
+		reason: "plugin_loaded",
+		input: { instanceKey: key, modulePath, workspaceRoot },
+	});
+	return { key, modulePath, workspaceRoot, duplicate: false };
+}
+
+/** Drop one registration. The key is reusable once every registration is gone. */
+export function releasePluginInstance(key: string): void {
+	const existing = activeInstances.get(key);
+	if (!existing) return;
+	existing.registrations--;
+	if (existing.registrations <= 0) activeInstances.delete(key);
+}
+
+/** Test seam: forget every live instance so fixtures can re-register. */
+export function resetPluginInstancesForTesting(): void {
+	activeInstances.clear();
+}

package/src/lib/policy-posture.ts

@@ -0,0 +1,227 @@
+/**
+ * Static policy posture for OpenCode 2.
+ *
+ * Three enforcement seats exist, and this module feeds the only one a
+ * repository cannot lift. `ctx.permission.hook("evaluate")` and
+ * `execute.before` run inside the plugin, so removing the plugin removes them.
+ * Static policies are configuration the host evaluates itself.
+ *
+ * Two host shapes exist and they are not interchangeable:
+ *
+ * - **OpenCode 2.0.x** reads `experimental.policies` and requires
+ *   `action: "permission"`. Its evaluator matches the composite string
+ *   `<permission action>:<resource>` as a whole-string glob
+ *   (`opencode.config.policy` in the 2.0.15 binary). A deny surfaces as
+ *   "Blocked by configuration policy".
+ * - **OpenCode 2.1.x** reads a top-level `policies` array and requires
+ *   `action: "tool.use"` instead. It ignores `experimental.policies`.
+ *
+ * Each host silently ignores the key it does not read, which makes a
+ * single-key posture look applied while enforcing nothing. The default
+ * therefore emits both keys. `--format 2.0` and `--format next` remain for
+ * pinning one host, and the reason to avoid them is the failure above.
+ *
+ * Schema acceptance is not runtime acceptance: `@opencode/schema` 2.0.10
+ * admits a top-level `policies` array that the 2.0.15 runtime never reads.
+ * The envelopes below were verified by live denial canaries on both hosts,
+ * not by decoding config.
+ *
+ * The plugin never writes another tool's configuration. The caller prints the
+ * block and the operator decides where it lands, because a plugin that can
+ * install its own static rails has just moved them back inside the plugin.
+ */
+
+/** Static invariants: each one holds for every session, with no runtime input. */
+export interface StaticInvariant {
+	/** Stable id, used by tests and documentation. */
+	id: string;
+	/** Host permission action the rule applies to. */
+	action: string;
+	/** Resources denied for that action, before the `<action>:` prefix. */
+	resources: readonly string[];
+	/** Why this cannot be left to a runtime hook. */
+	reason: string;
+}
+
+/**
+ * The invariants, in the order they are emitted.
+ *
+ * Every entry is a denial. A posture that grants access would be a second,
+ * weaker policy engine living in a config file, and the plugin already owns
+ * that job.
+ */
+export const STATIC_INVARIANTS: readonly StaticInvariant[] = [
+	{
+		id: "protected-trunk-push",
+		action: "shell",
+		resources: [
+			// The host matches the whole command string, so `git push * main`
+			// covers `git push origin main` and `git push -f origin main`, while
+			// the refspec forms need their own entries.
+			"git push * main",
+			"git push * master",
+			"git push * HEAD:main",
+			"git push * HEAD:master",
+		],
+		reason:
+			"Pushing to protected trunk must stay blocked even when the plugin is absent or disabled. The runtime git policy already refuses this; the static rule removes the dependency on it. A whole-string glob cannot see a compound command line or an exotic refspec, so this is a floor, not a sandbox: the plugin seat covers the rest.",
+	},
+	{
+		id: "live-control-plane-write",
+		action: "edit",
+		resources: [
+			// No `~/` here. On 2.0.x, `~` and `$HOME` are expanded only for the
+			// `permissions` key, not for `experimental.policies`, so a tilde
+			// resource would never match an absolute path. A leading `*/` is
+			// version-independent and covers every home directory.
+			"*/.config/opencode/*",
+			"/etc/opencode/*",
+			"*/Library/Application Support/opencode/*",
+		],
+		reason:
+			"An agent that can edit the live control plane can rewrite the rules that constrain it, including the plugin list. The tamper policy is a runtime check; this rule is a configuration-level one.",
+	},
+	{
+		id: "secret-material-read",
+		action: "read",
+		resources: ["*/.ssh/*", "*id_rsa*"],
+		reason:
+			"Private keys should never enter a model context, regardless of which session or role asks. The secret policy depends on the plugin being loaded.",
+	},
+	{
+		id: "external-directory-widening",
+		action: "external_directory",
+		resources: ["*"],
+		reason:
+			"`external_directory` defaults to allow, so a foreign read needs no approval. Denying it statically is what keeps the write boundary a boundary rather than an advisory. This is the strict posture: drop this rule if cross-repository reads are part of normal work.",
+	},
+	{
+		id: "code-mode-surface",
+		action: "execute",
+		resources: ["*"],
+		reason:
+			"Code Mode wraps tools behind a single `execute` surface, and its nested calls reach the tool layer on a path this guard does not evaluate. Denying `execute` removes that surface where the host asserts the action. The qualified hosts (2.0.15 and 2.1.3) register no `execute` tool and never assert an `execute` permission action, so this rule is inert on both; the plugin's read-only pruning plus `execute.before` remain the coverage.",
+	},
+];
+
+export type PolicyPostureFormat = "2.0" | "next" | "both";
+
+export interface StaticPolicyRule {
+	action: string;
+	resource: string;
+	effect: "deny";
+}
+
+export interface PolicyPosture {
+	format: PolicyPostureFormat;
+	/**
+	 * Rules as `{ action, resource }` pairs with the resource unprefixed. The
+	 * host builds the `<action>:<resource>` string when it matches; `config`
+	 * holds the enveloped form that is actually pasted into a config file.
+	 */
+	rules: StaticPolicyRule[];
+	/** Config fragment, ready to print. Never written by the plugin. */
+	config: Record<string, unknown>;
+	/** Human-readable rationale per invariant, for the printed header. */
+	rationale: Array<{ id: string; reason: string }>;
+}
+
+/**
+ * Compose one rule. The host matches `resource` against `<action>:<resource>`,
+ * so the action name is part of the string, not a separate field.
+ */
+function ruleFor(invariant: StaticInvariant, resource: string): StaticPolicyRule {
+	return { action: invariant.action, resource, effect: "deny" };
+}
+
+function rulesFor(invariants: readonly StaticInvariant[]): StaticPolicyRule[] {
+	return invariants.flatMap((invariant) => invariant.resources.map((resource) => ruleFor(invariant, resource)));
+}
+
+/**
+ * Envelope a rule list for the target host.
+ *
+ * `2.0` uses `experimental.policies` with the `permission` action, which is
+ * what the 2.0.x evaluator compares. `next` uses the top-level `policies`
+ * array with `tool.use`, which is what 2.1.x reads. `both` emits each rule
+ * under its own host's key: neither host reads the other's key, so the
+ * duplicate cannot double-apply or conflict.
+ */
+function envelope(
+	format: PolicyPostureFormat,
+	rules: readonly StaticPolicyRule[],
+): Record<string, unknown> {
+	const legacy = {
+		experimental: {
+			policies: rules.map((rule) => ({
+				action: "permission",
+				resource: `${rule.action}:${rule.resource}`,
+				effect: rule.effect,
+			})),
+		},
+	};
+	const current = {
+		policies: rules.map((rule) => ({
+			action: "tool.use",
+			resource: `${rule.action}:${rule.resource}`,
+			effect: rule.effect,
+		})),
+	};
+	if (format === "2.0") return legacy;
+	if (format === "next") return current;
+	return { ...legacy, ...current };
+}
+
+export function buildPolicyPosture(options?: { format?: PolicyPostureFormat }): PolicyPosture {
+	const format = options?.format ?? "both";
+	const rules = rulesFor(STATIC_INVARIANTS);
+	return {
+		format,
+		rules,
+		config: envelope(format, rules),
+		rationale: STATIC_INVARIANTS.map((invariant) => ({ id: invariant.id, reason: invariant.reason })),
+	};
+}
+
+function commentLines(lines: readonly string[]): string {
+	return lines
+		.flatMap((line) => line.split("\n"))
+		.map((line) => (line.trim() ? `// ${line}` : "//"))
+		.join("\n");
+}
+
+/**
+ * Render the posture as JSONC.
+ *
+ * The header states precedence and residual risk, because the file that
+ * carries these rules is also the file an operator will trim. A trimmed rule
+ * that was never explained looks like cruft, and cruft gets deleted.
+ */
+export function renderPolicyPosture(options?: { format?: PolicyPostureFormat }): string {
+	const posture = buildPolicyPosture(options);
+	const header = commentLines([
+		"Workflow Guard static policy posture. Generated, never installed automatically.",
+		"",
+		`Target: OpenCode ${
+			posture.format === "2.0"
+				? "2.0.x only (experimental.policies, action \"permission\")"
+				: posture.format === "next"
+					? "2.1.x only (top-level policies, action \"tool.use\")"
+					: "2.0.x and 2.1.x (both keys; each host reads its own and ignores the other)"
+		}.`,
+		"",
+		"Precedence, highest first: managed preferences and Console policies, then /etc/opencode,",
+		"then ~/.config/opencode, then project opencode.json(c). Later rules win within one",
+		"ruleset, so keep these denies after any broad allow you add.",
+		"",
+		"Residual risk: policies are configuration. They do not sandbox plugin code, and any",
+		"process that can write the file that carries them can remove them. Place this block",
+		"in the system or global config, not in a project file.",
+		"",
+		"Every rule below is a deny. Nothing here grants access; runtime decisions stay with",
+		"the plugin's permission-evaluate and execute-before seats.",
+		"",
+		...posture.rationale.flatMap(({ id, reason }) => [`${id}: ${reason}`, ""]),
+	]);
+	return `${header}\n${JSON.stringify(posture.config, null, 2)}\n`;
+}

package/src/lib/read-only-tools.ts

@@ -0,0 +1,61 @@
+/**
+ * Tool pruning for read-only subagent roles.
+ *
+ * `execute.before` already denies a mutation from a read-only role, but only
+ * after the model has planned the call and the host has admitted it. The V2
+ * `session.hook("context")` sees the per-request tool snapshot, so the
+ * stronger invariant is to remove the mutating tools before the model can
+ * choose them.
+ *
+ * This is a narrowing only. The `execute.before` seat stays in place as the
+ * backstop: tools supplied by an ACP agent or a nested Code Mode call may not
+ * appear in the host snapshot, and a pruned list is not an authorization
+ * boundary on its own.
+ */
+
+/**
+ * Tools removed from a read-only role's request.
+ *
+ * - `write`/`edit`/`patch`/`apply_patch` author file contents.
+ * - `shell`/`bash` author bytes through redirects and can mutate git state.
+ * - `execute` is Code Mode, which runs nested tool calls. Nested calls are not
+ *   documented to fire the guard's hooks, so a read-only role must not reach
+ *   them.
+ * - `todowrite` replaces the whole task list; read-only roles do not plan work.
+ * - `subagent`/`task` can delegate a mutation to a child that runs with the
+ *   child's own role.
+ * - `guard_worktree_create`/`guard_worktree_cleanup` mutate repository state
+ *   and are already denied by the dispatcher for this role.
+ */
+export const READ_ONLY_PRUNED_TOOLS: readonly string[] = [
+	"write",
+	"edit",
+	"patch",
+	"apply_patch",
+	"shell",
+	"bash",
+	"execute",
+	"todowrite",
+	"subagent",
+	"task",
+	"guard_worktree_create",
+	"guard_worktree_cleanup",
+];
+
+/**
+ * Delete the mutating tools from a per-request tool snapshot.
+ *
+ * Returns the ids actually removed, so the caller can journal the narrowing.
+ * The snapshot is host-owned and mutable for the duration of the request;
+ * deleting a key affects only the outgoing call.
+ */
+export function pruneToolsForReadOnlyRole(tools: Record<string, unknown> | undefined): string[] {
+	if (!tools || typeof tools !== "object") return [];
+	const removed: string[] = [];
+	for (const id of READ_ONLY_PRUNED_TOOLS) {
+		if (!(id in tools)) continue;
+		delete tools[id];
+		removed.push(id);
+	}
+	return removed;
+}