@shomra/agent 0.3.17 → 0.3.19

package/src/mcp/connect-gate.mjs

@@ -0,0 +1,45 @@
+import { gateMachine } from '../core/api-client.mjs';
+import { breakerReset, breakerTrip, guardTimeoutMs } from '../core/circuit-breaker.mjs';
+import { detectEnv } from '../gate/environment.mjs';
+
+const LISTING_REPORT_TIMEOUT_MS = 2000;
+
+async function postJson(url, apiKey, body, timeoutMs) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    return await fetch(url, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', 'X-Shomra-Key': apiKey, Connection: 'close' },
+      body: JSON.stringify(body),
+      signal: controller.signal,
+    });
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+export async function requestConnectVerdict({ url, apiKey, server, agent, projectId }) {
+  try {
+    const response = await postJson(`${url}/gate/mcp-connect`, apiKey, {
+      server,
+      machine: gateMachine(),
+      env: detectEnv(),
+      agent,
+      projectId,
+      sessionId: process.env.SHOMRA_SESSION_ID || undefined,
+    }, guardTimeoutMs());
+    if (!response.ok) throw new Error(`HTTP ${response.status}`);
+    const verdict = await response.json();
+    breakerReset();
+    return { verdict };
+  } catch (error) {
+    breakerTrip();
+    return { error };
+  }
+}
+
+export function reportListing(url, apiKey, body) {
+  if (!url || !apiKey) return;
+  postJson(`${url}/gate/mcp-listing`, apiKey, body, LISTING_REPORT_TIMEOUT_MS).catch(() => {});
+}

package/src/mcp/hosts.mjs

@@ -0,0 +1,16 @@
+import os from 'node:os';
+import path from 'node:path';
+import { SELF_PATH } from '../agents/hook-command.mjs';
+
+export const MCP_HOST_CONFIGS = {
+  claude: { label: 'Claude Code', global: () => path.join(os.homedir(), '.claude.json'), local: () => path.join(process.cwd(), '.mcp.json') },
+  cursor: { label: 'Cursor', global: () => path.join(os.homedir(), '.cursor', 'mcp.json'), local: () => path.join(process.cwd(), '.cursor', 'mcp.json') },
+  gemini: { label: 'Gemini CLI', global: () => path.join(os.homedir(), '.gemini', 'settings.json'), local: () => path.join(process.cwd(), '.gemini', 'settings.json') },
+  windsurf: { label: 'Windsurf', global: () => path.join(os.homedir(), '.codeium', 'windsurf', 'mcp_config.json'), local: () => path.join(process.cwd(), '.windsurf', 'mcp_config.json') },
+};
+
+export const MCP_HOST_KEYS = Object.keys(MCP_HOST_CONFIGS);
+
+export function shomraMcpEntry() {
+  return { command: process.execPath, args: [SELF_PATH, 'mcp', 'serve'] };
+}

package/src/mcp/jsonrpc.mjs

@@ -0,0 +1,48 @@
+export const SHOMRA_REFUSED = -32001;
+
+export function safeJson(value) {
+  if (value == null) return '';
+  try {
+    const text = JSON.stringify(value);
+    return text.length > 20000 ? text.slice(0, 20000) : text;
+  } catch {
+    return '';
+  }
+}
+
+export function createLineFramer(onMessage) {
+  let buffer = '';
+  return (chunk) => {
+    buffer += chunk.toString('utf8');
+    let newline = buffer.indexOf('\n');
+    while (newline !== -1) {
+      const line = buffer.slice(0, newline).trim();
+      buffer = buffer.slice(newline + 1);
+      newline = buffer.indexOf('\n');
+      if (!line) continue;
+      try {
+        onMessage(JSON.parse(line), line);
+      } catch {
+        onMessage(null, line);
+      }
+    }
+  };
+}
+
+export function writeMessage(message) {
+  process.stdout.write(`${JSON.stringify(message)}\n`);
+}
+
+export function refusal(id, message, data) {
+  return { jsonrpc: '2.0', id, error: { code: SHOMRA_REFUSED, message, data } };
+}
+
+export function sendBlockedInitialize(reason, server, verdict) {
+  writeMessage(refusal(0, reason, {
+    source: 'shomra-mcp-shim',
+    server,
+    refusedBy: 'policy',
+    ...(verdict?.state ? { state: verdict.state } : {}),
+    ...(verdict?.eventId ? { eventId: verdict.eventId } : {}),
+  }));
+}

package/src/mcp/lookup.mjs

@@ -0,0 +1,50 @@
+import { clampInt } from '../core/numbers.mjs';
+
+export function parseEnvKV(str) {
+  const env = {};
+  for (const pair of String(str || '').split(',')) {
+    const i = pair.indexOf('=');
+    if (i > 0) env[pair.slice(0, i).trim()] = pair.slice(i + 1).trim();
+  }
+  return env;
+}
+
+const MCP_RUNNERS = new Set(['npx', '-y', '--yes', 'uvx', 'uv', 'node', 'bun', 'deno', 'python', 'python3', '-m', 'pipx', 'run', 'npm', 'pnpm', 'yarn', 'dlx', 'bunx']);
+
+export function mcpLookupId(server, name) {
+  if (server.url) return String(server.url);
+  const toks = [server.command, ...(server.args || [])].filter(Boolean).map(String);
+  for (const t of toks) {
+    if (MCP_RUNNERS.has(t) || t.startsWith('-')) continue;
+    if (/^@?[\w][\w./-]*$/.test(t)) return t;
+  }
+  return name;
+}
+
+export async function mcpLookup(url, id) {
+  const ctrl = new AbortController();
+  const timer = setTimeout(() => ctrl.abort(), clampInt(process.env.SHOMRA_API_TIMEOUT_MS, 15000, 1000, 60000));
+  try {
+    const res = await fetch(`${url}/catalog/lookup?id=${encodeURIComponent(id)}`, {
+      signal: ctrl.signal,
+      headers: { Accept: 'application/json', 'User-Agent': 'shomra-agent' },
+    });
+    if (!res.ok) throw new Error(`HTTP ${res.status}`);
+    return await res.json();
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+export function mcpIndexAlert(index) {
+  if (!index || !index.found || !index.scanned) return null;
+  if (index.verdict === 'FAIL' || (index.criticalCount ?? 0) > 0) return 'BLOCK';
+  if (index.verdict === 'REVIEW' || (index.highCount ?? 0) > 0) return 'FLAG';
+  return 'OK';
+}
+
+export function worstMcpVerdict(local, idxAlert) {
+  const rank = { ALLOW: 0, OK: 0, PASS: 0, FLAG: 1, REVIEW: 1, BLOCK: 2, FAIL: 2 };
+  const label = ['ALLOW', 'FLAG', 'BLOCK'];
+  return label[Math.max(rank[local] ?? 0, rank[idxAlert] ?? 0)];
+}

package/src/mcp/screening.mjs

@@ -0,0 +1,103 @@
+import { downrankCodeContext, grade, localScan } from '../detect/guard-signals.mjs';
+import { safeJson } from './jsonrpc.mjs';
+
+const MAX_EXTRACT_DEPTH = 12;
+const MAX_EXTRACT_BYTES = 256 * 1024;
+
+export const LISTING_KEY = {
+  'tools/list': 'tools',
+  'resources/list': 'resources',
+  'resources/templates/list': 'resourceTemplates',
+  'prompts/list': 'prompts',
+};
+
+export const RESULT_METHODS = new Set(['resources/read', 'prompts/get', 'completion/complete']);
+
+function extractResultText(value, depth = 0, collected = []) {
+  if (depth > MAX_EXTRACT_DEPTH || collected.join('').length > MAX_EXTRACT_BYTES) return collected;
+  if (typeof value === 'string') {
+    collected.push(value);
+    return collected;
+  }
+  if (Array.isArray(value)) {
+    for (const item of value) extractResultText(item, depth + 1, collected);
+    return collected;
+  }
+  if (value && typeof value === 'object') {
+    for (const [key, item] of Object.entries(value)) {
+      if (key === 'blob') continue;
+      if (typeof item === 'string') collected.push(item);
+      else extractResultText(item, depth + 1, collected);
+    }
+  }
+  return collected;
+}
+
+function isUnmaskedThreat(finding) {
+  return !finding.codeContext && (finding.severity === 'CRITICAL' || finding.category === 'injection');
+}
+
+export function screenResult(result) {
+  const text = extractResultText(result).join('\n');
+  if (!text.trim()) return { blocked: false };
+
+  const scan = localScan(text);
+  if (!scan.findings.some(isUnmaskedThreat)) return { blocked: false };
+
+  const ranked = downrankCodeContext(scan.findings);
+  const worst = ranked.find((f) => f.severity === 'CRITICAL' && !f.codeContext)
+    ?? ranked.find((f) => f.category === 'injection' && !f.codeContext)
+    ?? ranked[0];
+  return { blocked: true, label: worst?.label || 'malicious content' };
+}
+
+function descriptorText(entry, method) {
+  const descriptor = entry ?? {};
+  const parts = method === 'tools/list'
+    ? [descriptor.name ?? '', descriptor.description ?? '', safeJson(descriptor.annotations), safeJson(descriptor.inputSchema)]
+    : [
+      descriptor.name ?? '', descriptor.title ?? '', descriptor.description ?? '',
+      descriptor.uri ?? '', descriptor.uriTemplate ?? '', safeJson(descriptor.arguments),
+    ];
+  return parts.filter(Boolean).join('\n');
+}
+
+function descriptorLabel(entry) {
+  return String(entry?.name ?? entry?.uri ?? entry?.uriTemplate ?? 'unnamed');
+}
+
+function isPoisonedDescriptor(entry, method) {
+  const text = descriptorText(entry, method);
+  if (!text.trim()) return false;
+  const { findings } = localScan(text, { categories: ['injection', 'secret', 'egress'] });
+  return findings.some((f) => f.severity === 'CRITICAL' || f.severity === 'HIGH');
+}
+
+export function screenListing(method, result, deniedTools = []) {
+  const key = LISTING_KEY[method];
+  const entries = key && Array.isArray(result?.[key]) ? result[key] : null;
+  if (!entries) return { result, withheld: [], denied: [], total: 0 };
+
+  const denySet = new Set(deniedTools ?? []);
+  const kept = [];
+  const withheld = [];
+  const denied = [];
+  for (const entry of entries) {
+    if (method === 'tools/list' && denySet.has(String(entry?.name ?? ''))) {
+      denied.push(String(entry.name));
+    } else if (isPoisonedDescriptor(entry, method)) {
+      withheld.push(descriptorLabel(entry));
+    } else {
+      kept.push(entry);
+    }
+  }
+  if (!withheld.length && !denied.length) return { result, withheld: [], denied: [], total: entries.length };
+  return { result: { ...result, [key]: kept }, withheld, denied, total: entries.length };
+}
+
+export function screenToolCallArguments(toolArguments) {
+  const { findings } = localScan(safeJson(toolArguments), { categories: ['shell', 'injection', 'secret'] });
+  if (grade(findings).verdict !== 'BLOCK') return { blocked: false };
+  const label = findings.find((f) => f.severity === 'CRITICAL')?.label || 'dangerous tool call';
+  return { blocked: true, label };
+}

package/src/mcp/server-tools.mjs

@@ -0,0 +1,97 @@
+export const MCP_TOOLS = [
+  {
+    name: 'shomra_check',
+    description: 'Gate every AI artifact (MCP configs, skills, slash commands, hooks, rules files) under a path for security issues - local-first, no network needed. Returns findings with file, line, severity and verdict. Run this after editing AI artifacts.',
+    inputSchema: {
+      type: 'object',
+      properties: { path: { type: 'string', description: 'File or directory to check (default: workspace root).' } },
+    },
+  },
+  {
+    name: 'shomra_scan_models',
+    description: 'Detect the AI models the code loads (from_pretrained, hf_hub_download, SentenceTransformer, …) and look each up in the Shomra Model Index for known vulnerabilities. Returns each model\'s verdict, findings, and a safe-loading fix plan (kwargs to add to the load call). Run this after adding or changing model-loading code.',
+    inputSchema: {
+      type: 'object',
+      properties: { path: { type: 'string', description: 'File or directory to scan (default: workspace root).' } },
+    },
+  },
+  {
+    name: 'shomra_fix',
+    description: 'Generate a minimal security fix for one AI artifact. Returns the fixed content; set apply=true to write it to disk in place.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        file: { type: 'string', description: 'Path to the artifact to fix.' },
+        apply: { type: 'boolean', description: 'Write the fix to disk (default: false - return it only).' },
+      },
+      required: ['file'],
+    },
+  },
+  {
+    name: 'shomra_explain',
+    description: 'Explain the findings in one AI artifact: why each matters, a one-line exploit, and an honest false-positive read.',
+    inputSchema: {
+      type: 'object',
+      properties: { file: { type: 'string', description: 'Path to the artifact to explain.' } },
+      required: ['file'],
+    },
+  },
+  {
+    name: 'shomra_review_change',
+    description:
+      'Security-review content you are ABOUT TO WRITE, before writing it. Pass the proposed file content and its intended path; returns a verdict (ALLOW/FLAG/BLOCK) with findings and line numbers. Nothing is written to disk. Call this before creating or rewriting an MCP config, skill, slash command, subagent, hook, agent card, or rules/memory file - a BLOCK here costs nothing, the same content on disk costs a blocked tool call.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        content: { type: 'string', description: 'The full proposed file content.' },
+        path: { type: 'string', description: 'The path you intend to write it to (drives which checks apply).' },
+        kind: { type: 'string', description: 'Optional artifact kind: mcp, skill, command, subagent, hook, rules, agent-card, memory.' },
+      },
+      required: ['content', 'path'],
+    },
+  },
+  {
+    name: 'shomra_rules',
+    description:
+      'Get the security rules in force for this workspace - what Shomra\'s runtime firewall will refuse, tailored to what this repo actually contains, plus any org policy. Call this before writing shell commands, MCP configs, agent artifacts, or model-loading code so you do not generate something that will be blocked.',
+    inputSchema: {
+      type: 'object',
+      properties: { path: { type: 'string', description: 'Workspace root (default: workspace root).' } },
+    },
+  },
+  {
+    name: 'shomra_review_plan',
+    description:
+      'Threat-model a plan BEFORE implementing it. Pass your plan text; returns any attack paths it would create (untrusted input reaching execution, sensitive data reaching network egress, and so on) plus the conditions to satisfy while you build. Call this once you have a plan for any task that touches untrusted input, credentials, agent tools, or actions with consequences - building the guarded version first is far cheaper than retrofitting it after the firewall refuses a call.',
+    inputSchema: {
+      type: 'object',
+      properties: { plan: { type: 'string', description: 'Your plan, as prose. The steps you intend to take and what they will read and do.' } },
+      required: ['plan'],
+    },
+  },
+];
+
+export function mcpToolInvocation(name, rawArguments) {
+  const args = rawArguments || {};
+  if (name === 'shomra_check') return { args: ['check', args.path ? String(args.path) : '.'] };
+  if (name === 'shomra_scan_models') return { args: ['models', args.path ? String(args.path) : '.'] };
+  if (name === 'shomra_fix') return { args: ['fix', String(args.file || ''), ...(args.apply ? ['--apply'] : [])] };
+  if (name === 'shomra_explain') return { args: ['why', String(args.file || '')] };
+  if (name === 'shomra_review_change') {
+    if (typeof args.content !== 'string' || !args.path) {
+      return { error: 'shomra_review_change requires `content` and `path`.' };
+    }
+    return {
+      args: ['gate', '--stdin', '--path', String(args.path), ...(args.kind ? ['--kind', String(args.kind)] : [])],
+      stdin: args.content,
+    };
+  }
+  if (name === 'shomra_rules') return { args: ['rules', args.path ? String(args.path) : '.'] };
+  if (name === 'shomra_review_plan') {
+    if (typeof args.plan !== 'string' || !args.plan.trim()) {
+      return { error: 'shomra_review_plan requires `plan` text.' };
+    }
+    return { args: ['plan', '-'], stdin: args.plan };
+  }
+  return { error: `Unknown tool: ${name}` };
+}

package/src/mcp/server.mjs

@@ -0,0 +1,102 @@
+import path from 'node:path';
+import { SELF_PATH } from '../agents/hook-command.mjs';
+import { VERSION } from '../core/version.mjs';
+import { MCP_TOOLS, mcpToolInvocation } from './server-tools.mjs';
+
+const PROTOCOL_VERSION = '2024-11-05';
+const METHOD_NOT_FOUND = -32601;
+const INTERNAL_ERROR = -32603;
+const MAX_OUTPUT_BYTES = 64 * 1024 * 1024;
+
+function makeCliRunner(execFileSync, cwd) {
+  return function runCli(args, stdin) {
+    let stdout;
+    try {
+      stdout = execFileSync(process.execPath, [SELF_PATH, ...args, '--json'], {
+        encoding: 'utf8',
+        cwd,
+        maxBuffer: MAX_OUTPUT_BYTES,
+        ...(stdin != null ? { input: stdin } : { stdio: ['ignore', 'pipe', 'pipe'] }),
+      });
+    } catch (error) {
+      stdout = error.stdout ? String(error.stdout) : '';
+      if (!stdout) return { text: String(error.stderr || error.message || 'command failed') };
+    }
+    try {
+      return { data: JSON.parse(stdout) };
+    } catch {
+      return { text: stdout };
+    }
+  };
+}
+
+function callTool(runCli, name, toolArguments) {
+  const invocation = mcpToolInvocation(name, toolArguments);
+  if (invocation.error) return { text: invocation.error, isError: true };
+  return runCli(invocation.args, invocation.stdin);
+}
+
+function toolCallResult(result) {
+  const text = result.data !== undefined
+    ? JSON.stringify(result.data, null, 2)
+    : String(result.text != null ? result.text : '');
+  return { content: [{ type: 'text', text }], isError: !!result.isError };
+}
+
+function makeTransport() {
+  const send = (message) => process.stdout.write(`${JSON.stringify(message)}\n`);
+  return {
+    ok: (id, result) => send({ jsonrpc: '2.0', id, result }),
+    fail: (id, code, message) => send({ jsonrpc: '2.0', id, error: { code, message } }),
+  };
+}
+
+function handleRequest({ id, method, params }, { transport, runCli }) {
+  if (method === 'initialize') {
+    return transport.ok(id, {
+      protocolVersion: PROTOCOL_VERSION,
+      capabilities: { tools: {} },
+      serverInfo: { name: 'shomra', version: VERSION },
+    });
+  }
+  if (method === 'ping') return transport.ok(id, {});
+  if (method === 'tools/list') return transport.ok(id, { tools: MCP_TOOLS });
+  if (method === 'tools/call') {
+    const result = callTool(runCli, params && params.name, params && params.arguments);
+    return transport.ok(id, toolCallResult(result));
+  }
+  if (typeof method === 'string' && method.startsWith('notifications/')) return undefined;
+  if (id !== undefined) return transport.fail(id, METHOD_NOT_FOUND, `Method not found: ${method}`);
+  return undefined;
+}
+
+function parseRequest(line) {
+  const trimmed = line.trim();
+  if (!trimmed) return null;
+  try {
+    return JSON.parse(trimmed);
+  } catch {
+    return null;
+  }
+}
+
+export async function runMcpServer(flags) {
+  const { createInterface } = await import('node:readline');
+  const { execFileSync } = await import('node:child_process');
+
+  const cwd = flags.path ? path.resolve(String(flags.path)) : process.cwd();
+  const runCli = makeCliRunner(execFileSync, cwd);
+  const transport = makeTransport();
+
+  const reader = createInterface({ input: process.stdin });
+  reader.on('line', (line) => {
+    const request = parseRequest(line);
+    if (!request) return;
+    try {
+      handleRequest(request, { transport, runCli });
+    } catch (error) {
+      if (request.id !== undefined) transport.fail(request.id, INTERNAL_ERROR, String(error?.message || error));
+    }
+  });
+  await new Promise((resolve) => reader.on('close', resolve));
+}

package/src/mcp/shim.mjs

@@ -0,0 +1,205 @@
+import { gateMachine } from '../core/api-client.mjs';
+import { breakerOpen } from '../core/circuit-breaker.mjs';
+import { loadConfig, resolveSettings } from '../core/config.mjs';
+import { EXIT_USAGE } from '../core/exit-codes.mjs';
+import { red } from '../core/terminal.mjs';
+import { detectEnv } from '../gate/environment.mjs';
+import { envFlag } from '../guard/options.mjs';
+import { spawnGuardedServer } from './child-process.mjs';
+import { reportListing, requestConnectVerdict } from './connect-gate.mjs';
+import { createLineFramer, refusal, sendBlockedInitialize, writeMessage } from './jsonrpc.mjs';
+import { LISTING_KEY, RESULT_METHODS, screenListing, screenResult, screenToolCallArguments } from './screening.mjs';
+
+export { mcpConfigCandidates, unwrapMcpConfig, wrapMcpConfig } from './config-wrapping.mjs';
+
+const MAX_PENDING_REQUESTS = 1000;
+const USAGE = 'shomra mcp-guard --name <server> -- <command> [args…]';
+
+function note(message) {
+  process.stderr.write(`[shomra] ${message}\n`);
+}
+
+function readLaunchTarget(flags, positional) {
+  const argv = process.argv.slice(2);
+  const separator = argv.indexOf('--');
+  const childArgv = separator === -1 ? [] : argv.slice(separator + 1);
+  const [command, ...args] = childArgv;
+  const name = String(flags.name || positional[0] || command || '').trim();
+  return { name, command, args };
+}
+
+async function resolveConnectVerdict({ name, command, args, flags, settings, strict }) {
+  const { apiKey, url } = settings;
+  if (!apiKey || !url) {
+    if (strict) {
+      sendBlockedInitialize(
+        'Shomra is not configured on this machine (SHOMRA_GUARD_STRICT). Run: shomra init --key shm_…',
+        name,
+      );
+      process.exit(0);
+    }
+    return null;
+  }
+  if (!strict && breakerOpen()) return null;
+
+  const { verdict, error } = await requestConnectVerdict({
+    url,
+    apiKey,
+    server: { name, command, args },
+    agent: flags.agent ? String(flags.agent) : undefined,
+    projectId: flags.project ? String(flags.project) : undefined,
+  });
+  if (!error) return verdict;
+
+  if (strict) {
+    sendBlockedInitialize(`Shomra could not verify "${name}" (${error.message}); refused by fail-closed policy.`, name);
+    process.exit(0);
+  }
+  note(`mcp-guard: could not reach the backend (${error.message}); "${name}" started unverified.`);
+  return null;
+}
+
+function enforceConnectVerdict(verdict, name) {
+  if (!verdict) return;
+  if (verdict.decision === 'BLOCK') {
+    sendBlockedInitialize(
+      verdict.reason || `MCP server "${name}" is not permitted in this organization.`,
+      name,
+      verdict,
+    );
+    note(verdict.reason || `"${name}" refused.`);
+    process.exit(0);
+  }
+  if (verdict.decision === 'FLAG') note(verdict.reason || `"${name}" is unreviewed.`);
+}
+
+function launchServer(name, command, args) {
+  try {
+    return spawnGuardedServer(command, args);
+  } catch (error) {
+    sendBlockedInitialize(`Shomra refused to launch "${name}": ${error.message}`, name);
+    note(error.message);
+    return process.exit(0);
+  }
+}
+
+function trackableMethod(message) {
+  return message.method
+    && 'id' in message
+    && (LISTING_KEY[message.method] || RESULT_METHODS.has(message.method));
+}
+
+function createClientFilter({ child, pending, server }) {
+  return createLineFramer((message, line) => {
+    if (!message) {
+      child.stdin.write(`${line}\n`);
+      return;
+    }
+    if (trackableMethod(message)) {
+      if (pending.size >= MAX_PENDING_REQUESTS) pending.clear();
+      pending.set(JSON.stringify(message.id), message.method);
+    }
+    if (message.method === 'tools/call' && 'id' in message) {
+      const screen = screenToolCallArguments(message.params?.arguments);
+      if (screen.blocked) {
+        writeMessage(refusal(message.id, `Refused on-machine by Shomra: ${screen.label}.`, {
+          source: 'shomra-mcp-shim',
+          server,
+          tool: message.params?.name,
+          refusedBy: 'policy',
+        }));
+        return;
+      }
+    }
+    child.stdin.write(`${line}\n`);
+  });
+}
+
+function listingTelemetry({ settings, server, agent, withheld, total }) {
+  reportListing(settings.url, settings.apiKey, {
+    server,
+    withheld,
+    total,
+    machine: gateMachine(),
+    env: detectEnv(),
+    agent,
+    sessionId: process.env.SHOMRA_SESSION_ID || undefined,
+  });
+}
+
+function forwardResultMethod({ message, line, method, server }) {
+  const screen = screenResult(message.result);
+  if (!screen.blocked) {
+    process.stdout.write(`${line}\n`);
+    return;
+  }
+  note(`withheld a poisoned ${method} result from "${server}": ${screen.label}`);
+  writeMessage(refusal(
+    message.id,
+    `Shomra withheld this ${method} result: ${screen.label}. The content was not read into context - do not act on it.`,
+    { source: 'shomra-mcp-shim', server, method, refusedBy: 'content' },
+  ));
+}
+
+function forwardListing({ message, method, server, deniedTools, settings, agent }) {
+  const screened = screenListing(method, message.result, deniedTools);
+  if (screened.denied.length) {
+    note(`withheld ${screened.denied.length} tool(s) denied by policy on "${server}": ${screened.denied.join(', ')}`);
+  }
+  if (screened.withheld.length) {
+    note(`withheld ${screened.withheld.length} poisoned descriptor(s) from "${server}": ${screened.withheld.join(', ')}`);
+    listingTelemetry({ settings, server, agent, withheld: screened.withheld, total: screened.total });
+  } else if (method === 'tools/list' && screened.total) {
+    listingTelemetry({ settings, server, agent, withheld: [], total: screened.total });
+  }
+  writeMessage({ ...message, result: screened.result });
+}
+
+function createServerFilter({ pending, server, deniedTools, settings, agent }) {
+  return createLineFramer((message, line) => {
+    if (!message) {
+      process.stdout.write(`${line}\n`);
+      return;
+    }
+    const key = 'id' in message ? JSON.stringify(message.id) : null;
+    const method = key ? pending.get(key) : null;
+    if (!method || !message.result) {
+      process.stdout.write(`${line}\n`);
+      return;
+    }
+    pending.delete(key);
+
+    if (RESULT_METHODS.has(method)) forwardResultMethod({ message, line, method, server });
+    else forwardListing({ message, method, server, deniedTools, settings, agent });
+  });
+}
+
+export async function runMcpShim(flags, positional) {
+  const { name, command, args } = readLaunchTarget(flags, positional);
+  if (!command) {
+    console.error(`${red('✗')} Usage: ${USAGE}`);
+    process.exit(EXIT_USAGE);
+  }
+
+  const strict = envFlag('SHOMRA_GUARD_STRICT');
+  const settings = resolveSettings(loadConfig());
+  const agent = flags.agent ? String(flags.agent) : undefined;
+
+  const verdict = await resolveConnectVerdict({ name, command, args, flags, settings, strict });
+  enforceConnectVerdict(verdict, name);
+  const deniedTools = Array.isArray(verdict?.deniedTools) ? verdict.deniedTools.map(String) : [];
+
+  const child = launchServer(name, command, args);
+  child.on('error', (error) => {
+    note(`mcp-guard: failed to start "${command}": ${error.message}`);
+    process.exit(1);
+  });
+  child.on('exit', (code) => process.exit(code ?? 0));
+
+  const pending = new Map();
+  process.stdin.on('data', createClientFilter({ child, pending, server: name }));
+  child.stdout.on('data', createServerFilter({ pending, server: name, deniedTools, settings, agent }));
+  process.stdin.on('end', () => child.stdin.end());
+
+  await new Promise(() => {});
+}