getprismo 0.1.11 → 0.1.14

package/README.md

@@ -22,17 +22,21 @@ prismodev catches it before, during, and after.
 
 ## the loop
 
-prismodev is three commands that cover an entire coding session:
+prismodev covers the full AI coding session:
 
 ```
 before you code     npx getprismo doctor
 while you code      npx getprismo watch
+noisy commands      npx getprismo shield -- npm test
 after you code      npx getprismo cc timeline
+agent-native        npx getprismo mcp
 ```
 
 **doctor** diagnoses the repo, applies safe fixes, and shows the before/after score.
 **watch** monitors context pressure live and warns when things go wrong.
 **cc timeline** reconstructs what happened in the session so you learn from it.
+**shield** runs noisy commands without dumping full output back into the agent context.
+**mcp** exposes PrismoDev as local tools so compatible agents can scan, search shield output, and request scoped context directly.
 
 ---
 
@@ -137,6 +141,51 @@ watch caught lockfiles entering context, a file being read 286 times, and tool o
 
 ---
 
+## new: context shield
+
+if you know a command may dump huge output, run it through prismo:
+
+```bash
+npx getprismo shield -- npm test
+npx getprismo shield -- pytest -q
+npx getprismo shield -- npm run build
+```
+
+shield executes the command locally, stores full stdout/stderr under `.prismo/shield/runs/`, indexes the output in `.prismo/shield/shield.sqlite` using SQLite FTS5 when available, and prints only a compact summary plus useful error lines.
+
+this is the lightweight context-sandbox layer: the full output stays on disk until you explicitly inspect it, instead of being pasted into the model context and re-sent every turn.
+
+example:
+
+```text
+Prismo Shield
+
+Command: npm test
+Exit: 1
+Captured: 186 KB (~46,500 tokens kept out of chat)
+
+Full Output Stored:
+- .prismo/shield/runs/2026-05-20T.../stdout.txt
+- .prismo/shield/runs/2026-05-20T.../stderr.txt
+- .prismo/shield/shield.sqlite
+
+Summary Returned To Context:
+- ERROR: auth.test.ts expected 200 received 401
+- FAIL src/auth/session.test.ts
+```
+
+search previous shield output without reloading whole logs:
+
+```bash
+npx getprismo shield last
+npx getprismo shield search "auth expected 200"
+npx getprismo shield search "AUTH_FAILURE" --json
+```
+
+this is intentionally not magic interception yet. it is a safe local-first primitive you can tell agents to use for noisy commands.
+
+---
+
 ## new: live guardrails mode
 
 the easiest proactive mode is:
@@ -485,6 +534,8 @@ no install needed. npx runs it directly.
 | `scan --ci` | fail CI when token-risk gates fail |
 | `optimize` | generate `.prismo/` context packs |
 | `context` | print paste-ready prompt for agents |
+| `shield` | run noisy commands while keeping full output out of chat |
+| `mcp` | expose PrismoDev tools over local MCP stdio |
 | `setup` | detect tools, logs, proxy readiness |
 | `usage` | show raw session token usage |
 | `init` | add npm scripts and .prismo/README.md |
@@ -526,6 +577,63 @@ npx getprismo watch codex                # only codex sessions
 npx getprismo watch claude               # only claude code sessions
 ```
 
+### shield mode
+
+```bash
+npx getprismo shield -- npm test
+npx getprismo shield -- pytest -q
+npx getprismo shield --json -- npm run build
+npx getprismo shield last
+npx getprismo shield search "auth failure"
+```
+
+### mcp mode
+
+```bash
+npx getprismo mcp
+npx getprismo mcp /path/to/repo
+```
+
+`mcp` starts a local stdio MCP server for agent clients. It exposes:
+
+- `prismo_scan`
+- `prismo_doctor_dry_run`
+- `prismo_watch_snapshot`
+- `prismo_shield_run`
+- `prismo_shield_search`
+- `prismo_shield_last`
+- `prismo_context_pack`
+- `prismo_firewall`
+- `prismo_cc_timeline`
+
+This lets an MCP-compatible agent search prior shielded test/build output, request scoped context packs, or inspect token-waste signals without pasting giant logs into the conversation.
+
+Generic MCP client config:
+
+```json
+{
+  "mcpServers": {
+    "prismodev": {
+      "command": "npx",
+      "args": ["-y", "getprismo", "mcp", "/path/to/your/repo"]
+    }
+  }
+}
+```
+
+For local development from this repo:
+
+```json
+{
+  "mcpServers": {
+    "prismodev": {
+      "command": "node",
+      "args": ["/path/to/prismodev/bin/prismo.js", "mcp", "/path/to/your/repo"]
+    }
+  }
+}
+```
+
 ---
 
 ## cc modes
@@ -671,8 +779,10 @@ lib/prismo-dev/constants.js      shared defaults, pricing, patterns
 lib/prismo-dev/context-optimize.js  context packs, scoped prompts
 lib/prismo-dev/doctor.js         doctor/dev/init orchestration
 lib/prismo-dev/fixes.js          safe ignore/template generation
+lib/prismo-dev/mcp.js            local MCP server and Prismo tool bindings
 lib/prismo-dev/report.js         terminal, markdown, ci reports
 lib/prismo-dev/scan.js           repo scanning, scoring, readiness
+lib/prismo-dev/shield.js         local command shield and searchable output index
 lib/prismo-dev/usage-watch.js    local logs, watch, cost, timeline
 ```
 
@@ -682,8 +792,11 @@ lib/prismo-dev/usage-watch.js    local logs, watch, cost, timeline
 
 ```bash
 npx getprismo --help
+npx getprismo --version
 npx getprismo doctor --help
 npx getprismo watch --help
+npx getprismo shield --help
+npx getprismo mcp --help
 npx getprismo cc --help
 npx getprismo scan --help
 ```

package/lib/prismo-dev/mcp.js

@@ -0,0 +1,264 @@
+function createTextResult(payload) {
+  const text = typeof payload === "string" ? payload : JSON.stringify(payload, null, 2);
+  return {
+    content: [{ type: "text", text }],
+  };
+}
+
+function normalizeArgs(args) {
+  return args && typeof args === "object" ? args : {};
+}
+
+function makeTool(name, description, properties = {}, required = []) {
+  return {
+    name,
+    description,
+    inputSchema: {
+      type: "object",
+      properties,
+      required,
+      additionalProperties: false,
+    },
+  };
+}
+
+function createMcpTools(deps) {
+  const {
+    rootDir,
+    scanRepo,
+    toJsonPayload,
+    runDoctor,
+    toDoctorJsonPayload,
+    getUsageSummary,
+    getClaudeCodeCostSummary,
+    runOptimize,
+    createOptimizeContext,
+    renderStarterPrompt,
+    runFirewall,
+    runShield,
+    runShieldLast,
+    runShieldSearch,
+  } = deps;
+
+  const pathProperty = {
+    type: "string",
+    description: "Repository path. Defaults to the repo used when the MCP server started.",
+  };
+  const limitProperty = {
+    type: "number",
+    description: "Maximum number of recent sessions or runs to inspect.",
+  };
+  const scopeProperty = {
+    type: "string",
+    description: "Optional scope such as frontend, backend, auth, tests, billing, or routing.",
+  };
+
+  const tools = [
+    makeTool("prismo_scan", "Scan a repo for AI coding token/context waste.", {
+      path: pathProperty,
+      includeUsage: { type: "boolean", description: "Include local Claude/Codex usage logs when available." },
+      limit: limitProperty,
+    }),
+    makeTool("prismo_doctor_dry_run", "Preview PrismoDev doctor fixes and before/after payoff without writing files.", {
+      path: pathProperty,
+      scope: scopeProperty,
+      limit: limitProperty,
+    }),
+    makeTool("prismo_watch_snapshot", "Return a one-shot local session/context pressure snapshot.", {
+      path: pathProperty,
+      tool: { type: "string", enum: ["all", "codex", "claude"], description: "Which local session logs to inspect." },
+      limit: limitProperty,
+    }),
+    makeTool("prismo_shield_run", "Run a noisy command through Prismo shield and store full output locally.", {
+      path: pathProperty,
+      command: {
+        type: "array",
+        items: { type: "string" },
+        description: "Command argv array, for example [\"npm\", \"test\"].",
+      },
+    }, ["command"]),
+    makeTool("prismo_shield_search", "Search stored shield stdout/stderr without loading full logs into context.", {
+      path: pathProperty,
+      query: { type: "string", description: "Text to search for in stored shield output." },
+      limit: limitProperty,
+    }, ["query"]),
+    makeTool("prismo_shield_last", "List recent shielded command runs.", {
+      path: pathProperty,
+      limit: limitProperty,
+    }),
+    makeTool("prismo_context_pack", "Generate or preview a scoped Prismo context pack/starter prompt.", {
+      path: pathProperty,
+      scope: scopeProperty,
+      dryRun: { type: "boolean", description: "When true, do not write .prismo files." },
+    }),
+    makeTool("prismo_firewall", "Generate a scoped context firewall policy for a task.", {
+      path: pathProperty,
+      task: { type: "string", description: "Task description such as auth-bug or frontend-test-failure." },
+      scope: scopeProperty,
+      dryRun: { type: "boolean", description: "When true, preview allowed/blocked context without writing files." },
+    }),
+    makeTool("prismo_cc_timeline", "Return the latest Claude Code session timeline/postmortem data.", {
+      path: pathProperty,
+      limit: limitProperty,
+    }),
+  ];
+
+  function resolveRoot(args) {
+    return args.path || rootDir || process.cwd();
+  }
+
+  async function callTool(name, rawArgs) {
+    const args = normalizeArgs(rawArgs);
+    const target = resolveRoot(args);
+
+    if (name === "prismo_scan") {
+      return createTextResult(toJsonPayload(scanRepo(target, {
+        includeUsage: Boolean(args.includeUsage),
+        usageLimit: Number(args.limit) || 5,
+      })));
+    }
+
+    if (name === "prismo_doctor_dry_run") {
+      const result = runDoctor(target, {
+        dryRun: true,
+        scope: args.scope || null,
+        limit: Number(args.limit) || 3,
+      });
+      return createTextResult(toDoctorJsonPayload(result));
+    }
+
+    if (name === "prismo_watch_snapshot") {
+      const summary = getUsageSummary({
+        cwd: target,
+        limit: Number(args.limit) || 3,
+        usageTool: args.tool || "all",
+      });
+      return createTextResult(summary);
+    }
+
+    if (name === "prismo_shield_run") {
+      return createTextResult(runShield(target, args.command));
+    }
+
+    if (name === "prismo_shield_search") {
+      return createTextResult(runShieldSearch(target, args.query, { limit: Number(args.limit) || 5 }));
+    }
+
+    if (name === "prismo_shield_last") {
+      return createTextResult(runShieldLast(target, { limit: Number(args.limit) || 5 }));
+    }
+
+    if (name === "prismo_context_pack") {
+      const scope = args.scope || null;
+      const result = runOptimize(target, { scope, dryRun: args.dryRun !== false });
+      const context = createOptimizeContext(target, scope);
+      return createTextResult({
+        ...result,
+        starterPrompt: renderStarterPrompt(context, scope),
+      });
+    }
+
+    if (name === "prismo_firewall") {
+      return createTextResult(runFirewall(target, {
+        task: args.task || args.scope || "general",
+        scope: args.scope || null,
+        dryRun: args.dryRun !== false,
+      }));
+    }
+
+    if (name === "prismo_cc_timeline") {
+      return createTextResult(getClaudeCodeCostSummary({
+        cwd: target,
+        limit: Number(args.limit) || 1,
+        mode: "timeline",
+      }));
+    }
+
+    throw new Error(`Unknown MCP tool: ${name}`);
+  }
+
+  return { tools, callTool };
+}
+
+function runMcpServer(deps) {
+  const readline = require("readline");
+  const { packageVersion = "0.0.0" } = deps;
+  const { tools, callTool } = createMcpTools(deps);
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+    terminal: false,
+  });
+
+  function send(message) {
+    process.stdout.write(`${JSON.stringify(message)}\n`);
+  }
+
+  async function handle(message) {
+    if (!message || !message.method) return;
+    if (!Object.prototype.hasOwnProperty.call(message, "id")) return;
+
+    try {
+      if (message.method === "initialize") {
+        send({
+          jsonrpc: "2.0",
+          id: message.id,
+          result: {
+            protocolVersion: "2024-11-05",
+            capabilities: { tools: {} },
+            serverInfo: { name: "prismodev", version: packageVersion },
+          },
+        });
+        return;
+      }
+
+      if (message.method === "tools/list") {
+        send({ jsonrpc: "2.0", id: message.id, result: { tools } });
+        return;
+      }
+
+      if (message.method === "tools/call") {
+        const params = normalizeArgs(message.params);
+        const result = await callTool(params.name, params.arguments);
+        send({ jsonrpc: "2.0", id: message.id, result });
+        return;
+      }
+
+      send({
+        jsonrpc: "2.0",
+        id: message.id,
+        error: { code: -32601, message: `Method not found: ${message.method}` },
+      });
+    } catch (error) {
+      send({
+        jsonrpc: "2.0",
+        id: message.id,
+        error: {
+          code: -32000,
+          message: error && error.message ? error.message : String(error),
+        },
+      });
+    }
+  }
+
+  rl.on("line", (line) => {
+    if (!line.trim()) return;
+    try {
+      handle(JSON.parse(line));
+    } catch (error) {
+      send({
+        jsonrpc: "2.0",
+        id: null,
+        error: {
+          code: -32700,
+          message: error && error.message ? error.message : String(error),
+        },
+      });
+    }
+  });
+}
+
+module.exports = {
+  createMcpTools,
+  runMcpServer,
+};

package/lib/prismo-dev/shield.js

@@ -0,0 +1,384 @@
+module.exports = function createShield(deps) {
+  const {
+    fs,
+    path,
+    estimateTokens,
+    formatBytes,
+    color,
+  } = deps;
+  const { spawnSync } = require("child_process");
+
+const SHIELD_SCHEMA_VERSION = 1;
+
+function nowId() {
+  return new Date().toISOString().replace(/[:.]/g, "-");
+}
+
+function ensureDir(dir) {
+  fs.mkdirSync(dir, { recursive: true });
+}
+
+function pickInterestingLines(text, limit = 24) {
+  const lines = String(text || "").split(/\r?\n/).filter(Boolean);
+  const interesting = [];
+  const patterns = [
+    /\b(error|failed|failure|exception|traceback|fatal|panic|segmentation fault)\b/i,
+    /\b(warn|warning|deprecated|timeout|denied|unauthorized|forbidden)\b/i,
+    /\b(assert|expected|received|diff|not found|cannot find|module not found)\b/i,
+  ];
+  for (const line of lines) {
+    if (patterns.some((pattern) => pattern.test(line))) interesting.push(line.slice(0, 500));
+    if (interesting.length >= limit) break;
+  }
+  if (interesting.length) return interesting;
+  return lines.slice(Math.max(0, lines.length - Math.min(limit, 12))).map((line) => line.slice(0, 500));
+}
+
+function summarizeOutput(stdout, stderr) {
+  const stdoutText = String(stdout || "");
+  const stderrText = String(stderr || "");
+  const combined = [stderrText, stdoutText].filter(Boolean).join("\n");
+  const totalBytes = Buffer.byteLength(stdoutText) + Buffer.byteLength(stderrText);
+  const totalTokens = estimateTokens(combined);
+  return {
+    stdoutBytes: Buffer.byteLength(stdoutText),
+    stderrBytes: Buffer.byteLength(stderrText),
+    totalBytes,
+    estimatedTokens: totalTokens,
+    interestingLines: pickInterestingLines(combined),
+  };
+}
+
+function renderStoredReadCommand(pathValue) {
+  return `sed -n '1,160p' ${JSON.stringify(pathValue)}`;
+}
+
+function shieldRoot(root) {
+  return path.join(root, ".prismo", "shield");
+}
+
+function shieldDbPath(root) {
+  return path.join(shieldRoot(root), "shield.sqlite");
+}
+
+function indexPath(root) {
+  return path.join(shieldRoot(root), "index.jsonl");
+}
+
+function sqlString(value) {
+  return `'${String(value == null ? "" : value).replace(/'/g, "''")}'`;
+}
+
+function sqliteAvailable() {
+  const result = spawnSync("sqlite3", ["--version"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
+  return result.status === 0;
+}
+
+function sqliteExec(dbPath, sql, json = false) {
+  const args = json ? ["-json", dbPath, sql] : [dbPath, sql];
+  const result = spawnSync("sqlite3", args, { encoding: "utf8", maxBuffer: 20 * 1024 * 1024 });
+  if (result.status !== 0) {
+    throw new Error((result.stderr || result.error?.message || "sqlite3 failed").trim());
+  }
+  if (!json) return null;
+  const out = String(result.stdout || "").trim();
+  return out ? JSON.parse(out) : [];
+}
+
+function ensureSqliteIndex(root) {
+  if (!sqliteAvailable()) return { available: false, reason: "sqlite3-not-found" };
+  ensureDir(shieldRoot(root));
+  const dbPath = shieldDbPath(root);
+  sqliteExec(dbPath, `
+    PRAGMA journal_mode=WAL;
+    CREATE TABLE IF NOT EXISTS shield_runs (
+      id TEXT PRIMARY KEY,
+      command TEXT NOT NULL,
+      cwd TEXT NOT NULL,
+      exit_code INTEGER NOT NULL,
+      started_at TEXT NOT NULL,
+      finished_at TEXT NOT NULL,
+      duration_ms INTEGER NOT NULL,
+      stdout_path TEXT NOT NULL,
+      stderr_path TEXT NOT NULL,
+      total_bytes INTEGER NOT NULL,
+      estimated_tokens INTEGER NOT NULL,
+      summary_json TEXT NOT NULL
+    );
+    CREATE VIRTUAL TABLE IF NOT EXISTS shield_output USING fts5(
+      run_id UNINDEXED,
+      command,
+      stream UNINDEXED,
+      content,
+      tokenize='unicode61'
+    );
+  `);
+  return { available: true, path: path.relative(root, dbPath).replace(/\\/g, "/") };
+}
+
+function indexShieldRun(root, payload, stdout, stderr) {
+  const sqlite = ensureSqliteIndex(root);
+  if (!sqlite.available) return { mode: "jsonl", sqlite };
+  const dbPath = shieldDbPath(root);
+  const runId = path.basename(payload.stored.directory);
+  sqliteExec(dbPath, `
+    INSERT OR REPLACE INTO shield_runs (
+      id, command, cwd, exit_code, started_at, finished_at, duration_ms,
+      stdout_path, stderr_path, total_bytes, estimated_tokens, summary_json
+    ) VALUES (
+      ${sqlString(runId)},
+      ${sqlString(payload.command)},
+      ${sqlString(payload.cwd)},
+      ${Number(payload.exitCode || 0)},
+      ${sqlString(payload.startedAt)},
+      ${sqlString(payload.finishedAt)},
+      ${Number(payload.durationMs || 0)},
+      ${sqlString(payload.stored.stdout)},
+      ${sqlString(payload.stored.stderr)},
+      ${Number(payload.output.totalBytes || 0)},
+      ${Number(payload.output.estimatedTokens || 0)},
+      ${sqlString(JSON.stringify(payload))}
+    );
+    DELETE FROM shield_output WHERE run_id = ${sqlString(runId)};
+    INSERT INTO shield_output (run_id, command, stream, content)
+      VALUES (${sqlString(runId)}, ${sqlString(payload.command)}, 'stdout', ${sqlString(stdout)});
+    INSERT INTO shield_output (run_id, command, stream, content)
+      VALUES (${sqlString(runId)}, ${sqlString(payload.command)}, 'stderr', ${sqlString(stderr)});
+  `);
+  return { mode: "sqlite-fts5", sqlite };
+}
+
+function readJsonlIndex(root) {
+  const filePath = indexPath(root);
+  if (!fs.existsSync(filePath)) return [];
+  return fs.readFileSync(filePath, "utf8")
+    .split(/\r?\n/)
+    .filter(Boolean)
+    .map((line) => {
+      try {
+        return JSON.parse(line);
+      } catch {
+        return null;
+      }
+    })
+    .filter(Boolean);
+}
+
+function readStoredText(root, relPath) {
+  const fullPath = path.join(root, relPath);
+  try {
+    return fs.readFileSync(fullPath, "utf8");
+  } catch {
+    return "";
+  }
+}
+
+function fallbackSearch(root, query, limit = 10) {
+  const needle = String(query || "").toLowerCase();
+  if (!needle) return [];
+  const rows = readJsonlIndex(root).reverse();
+  const results = [];
+  for (const row of rows) {
+    for (const stream of ["stderr", "stdout"]) {
+      const relPath = row.stored?.[stream];
+      const text = readStoredText(root, relPath || "");
+      const lower = text.toLowerCase();
+      const index = lower.indexOf(needle);
+      if (index < 0) continue;
+      const start = Math.max(0, index - 180);
+      const end = Math.min(text.length, index + needle.length + 320);
+      results.push({
+        runId: path.basename(row.stored.directory),
+        command: row.command,
+        stream,
+        path: relPath,
+        exitCode: row.exitCode,
+        finishedAt: row.finishedAt,
+        snippet: text.slice(start, end).replace(/\s+/g, " ").trim(),
+      });
+      if (results.length >= limit) return results;
+    }
+  }
+  return results;
+}
+
+function runShieldSearch(rootDir = process.cwd(), query = "", options = {}) {
+  const root = path.resolve(rootDir);
+  const limit = options.limit || 10;
+  if (!String(query || "").trim()) throw new Error("No search query provided. Use: prismo shield search \"error text\"");
+  const sqlite = ensureSqliteIndex(root);
+  if (sqlite.available && fs.existsSync(shieldDbPath(root))) {
+    try {
+      const phrase = `"${String(query).replace(/"/g, '""')}"`;
+      const rows = sqliteExec(shieldDbPath(root), `
+        SELECT
+          shield_output.run_id AS runId,
+          shield_output.command AS command,
+          shield_output.stream AS stream,
+          CASE shield_output.stream
+            WHEN 'stderr' THEN shield_runs.stderr_path
+            ELSE shield_runs.stdout_path
+          END AS path,
+          shield_runs.exit_code AS exitCode,
+          shield_runs.finished_at AS finishedAt,
+          snippet(shield_output, 3, '[', ']', ' ... ', 24) AS snippet
+        FROM shield_output
+        JOIN shield_runs ON shield_runs.id = shield_output.run_id
+        WHERE shield_output MATCH ${sqlString(phrase)}
+        ORDER BY rank
+        LIMIT ${Number(limit)};
+      `, true);
+      return { query, mode: "sqlite-fts5", results: rows };
+    } catch {
+      // FTS queries can reject punctuation-heavy input; fall back to JSONL/plain text scan.
+    }
+  }
+  return { query, mode: "jsonl-fallback", results: fallbackSearch(root, query, limit) };
+}
+
+function runShieldLast(rootDir = process.cwd(), options = {}) {
+  const root = path.resolve(rootDir);
+  const limit = options.limit || 5;
+  return {
+    mode: fs.existsSync(shieldDbPath(root)) ? "sqlite-fts5" : "jsonl-fallback",
+    runs: readJsonlIndex(root).reverse().slice(0, limit),
+  };
+}
+
+function runShield(rootDir = process.cwd(), commandArgs = [], options = {}) {
+  const root = path.resolve(rootDir);
+  if (!commandArgs.length) {
+    throw new Error("No command provided. Use: prismo shield -- npm test");
+  }
+
+  const startedAt = new Date();
+  const id = nowId();
+  const runsDir = path.join(root, ".prismo", "shield", "runs", id);
+  ensureDir(runsDir);
+
+  const command = commandArgs[0];
+  const args = commandArgs.slice(1);
+  const result = spawnSync(command, args, {
+    cwd: root,
+    encoding: "utf8",
+    maxBuffer: options.maxBuffer || 30 * 1024 * 1024,
+    shell: false,
+    env: process.env,
+  });
+
+  const finishedAt = new Date();
+  const stdout = result.stdout || "";
+  const stderr = result.stderr || "";
+  const stdoutPath = path.join(runsDir, "stdout.txt");
+  const stderrPath = path.join(runsDir, "stderr.txt");
+  const summary = summarizeOutput(stdout, stderr);
+  fs.writeFileSync(stdoutPath, stdout, "utf8");
+  fs.writeFileSync(stderrPath, stderr, "utf8");
+
+  const payload = {
+    schemaVersion: 1,
+    command: commandArgs.join(" "),
+    cwd: root,
+    exitCode: typeof result.status === "number" ? result.status : 1,
+    signal: result.signal || null,
+    error: result.error ? result.error.message : null,
+    startedAt: startedAt.toISOString(),
+    finishedAt: finishedAt.toISOString(),
+    durationMs: finishedAt.getTime() - startedAt.getTime(),
+    output: summary,
+    stored: {
+      stdout: path.relative(root, stdoutPath).replace(/\\/g, "/"),
+      stderr: path.relative(root, stderrPath).replace(/\\/g, "/"),
+      directory: path.relative(root, runsDir).replace(/\\/g, "/"),
+    },
+    next: [
+      "Feed the summary to the agent first; inspect full output only if needed.",
+      `Read stdout: ${renderStoredReadCommand(path.relative(root, stdoutPath).replace(/\\/g, "/"))}`,
+      `Read stderr: ${renderStoredReadCommand(path.relative(root, stderrPath).replace(/\\/g, "/"))}`,
+    ],
+  };
+  fs.writeFileSync(path.join(runsDir, "summary.json"), JSON.stringify(payload, null, 2), "utf8");
+  fs.mkdirSync(path.join(root, ".prismo", "shield"), { recursive: true });
+  fs.appendFileSync(path.join(root, ".prismo", "shield", "index.jsonl"), `${JSON.stringify(payload)}\n`, "utf8");
+  payload.index = indexShieldRun(root, payload, stdout, stderr);
+  fs.writeFileSync(path.join(runsDir, "summary.json"), JSON.stringify(payload, null, 2), "utf8");
+  return payload;
+}
+
+function renderShieldTerminal(result) {
+  const lines = [];
+  const exitTone = result.exitCode === 0 ? "green" : "red";
+  lines.push("");
+  lines.push(color("Prismo Shield", "bold"));
+  lines.push("");
+  lines.push(`Command: ${result.command}`);
+  lines.push(`Exit: ${color(String(result.exitCode), exitTone)}`);
+  lines.push(`Duration: ${result.durationMs}ms`);
+  lines.push(`Captured: ${formatBytes(result.output.totalBytes)} (~${result.output.estimatedTokens.toLocaleString()} tokens kept out of chat)`);
+  lines.push("");
+  lines.push("Full Output Stored:");
+  lines.push(`- ${result.stored.stdout}`);
+  lines.push(`- ${result.stored.stderr}`);
+  lines.push(`- ${result.stored.directory}/summary.json`);
+  lines.push("");
+  lines.push("Summary Returned To Context:");
+  result.output.interestingLines.slice(0, 24).forEach((line) => lines.push(`- ${line}`));
+  lines.push("");
+  lines.push("Next:");
+  lines.push("1. Give the agent this summary first.");
+  lines.push("2. Inspect the stored full output only if the summary is not enough.");
+  lines.push(`3. ${renderStoredReadCommand(result.stored.stderr)}`);
+  return lines.join("\n");
+}
+
+function renderShieldSearchTerminal(result) {
+  const lines = [];
+  lines.push("");
+  lines.push(color("Prismo Shield Search", "bold"));
+  lines.push("");
+  lines.push(`Query: ${result.query}`);
+  lines.push(`Index: ${result.mode}`);
+  lines.push(`Results: ${result.results.length}`);
+  lines.push("");
+  if (!result.results.length) {
+    lines.push("No matching shield output found.");
+    return lines.join("\n");
+  }
+  result.results.forEach((item, index) => {
+    lines.push(`${index + 1}. ${item.path} (${item.stream}, exit ${item.exitCode})`);
+    lines.push(`   ${item.command}`);
+    lines.push(`   ${String(item.snippet || "").slice(0, 700)}`);
+  });
+  lines.push("");
+  lines.push("Next:");
+  lines.push("Use the stored path above only if the snippet is not enough.");
+  return lines.join("\n");
+}
+
+function renderShieldLastTerminal(result) {
+  const lines = [];
+  lines.push("");
+  lines.push(color("Prismo Shield Last", "bold"));
+  lines.push("");
+  lines.push(`Index: ${result.mode}`);
+  if (!result.runs.length) {
+    lines.push("No shield runs found.");
+    return lines.join("\n");
+  }
+  result.runs.forEach((run, index) => {
+    lines.push(`${index + 1}. ${run.finishedAt}  exit ${run.exitCode}  ${run.command}`);
+    lines.push(`   ${run.stored.directory}/summary.json`);
+    lines.push(`   ${formatBytes(run.output.totalBytes)} (~${run.output.estimatedTokens.toLocaleString()} tokens kept out of chat)`);
+  });
+  return lines.join("\n");
+}
+
+  return {
+    renderShieldLastTerminal,
+    renderShieldSearchTerminal,
+    renderShieldTerminal,
+    runShieldLast,
+    runShieldSearch,
+    runShield,
+  };
+};

package/lib/prismo-dev-scan.js

@@ -3,6 +3,7 @@ const http = require("http");
 const https = require("https");
 const os = require("os");
 const path = require("path");
+const { version: PACKAGE_VERSION } = require("../package.json");
 
 const {
   HIGH_RISK_DIRS,
@@ -267,14 +268,36 @@ const {
   writeGeneratedFile,
 });
 
+const {
+  renderShieldLastTerminal,
+  renderShieldSearchTerminal,
+  renderShieldTerminal,
+  runShieldLast,
+  runShieldSearch,
+  runShield,
+} = require("./prismo-dev/shield")({
+  fs,
+  path,
+  estimateTokens,
+  formatBytes: (...args) => formatBytes(...args),
+  color,
+});
+
+const { runMcpServer } = require("./prismo-dev/mcp");
+
 function printHelp() {
   console.log(`Prismo CLI
 
 Usage:
+  prismo --version
   prismo dev [path]
   prismo init [--json] [--dry-run] [path]
   prismo doctor [--json] [--dry-run] [--apply-ignores-only] [--no-context-packs] [--limit N] [path]
   prismo firewall [task] [--json] [--dry-run] [path]
+  prismo shield [--json] [path] -- <command ...>
+  prismo shield last [--json] [--limit N] [path]
+  prismo shield search <query> [--json] [--limit N] [path]
+  prismo mcp [path]
   prismo setup [--json] [--proxy-url URL] [path]
   prismo scan [--fix] [--ci] [--json] [--usage] [--simple] [--no-report] [path]
   prismo optimize [scope] [--json] [path]
@@ -289,6 +312,8 @@ Commands:
   init        Add local PrismoDev helper docs and npm scripts when package.json exists.
   doctor      Diagnose, safely optimize, re-scan, and show before/after payoff.
   firewall    Generate allowed/blocked context policy files for an AI coding task.
+  shield      Run a noisy command, store full output locally, and return a compact summary.
+  mcp         Start a local MCP server exposing Prismo tools over stdio.
   scan        Run PrismoDev for Claude Code, Codex, Cursor, and AI coding workflows.
   optimize    Generate lightweight AI-readable project context files in .prismo/.
   context     Print a copy-pasteable compact context prompt for AI coding tools.
@@ -475,6 +500,45 @@ Examples:
 Output:
   Writes .prismo/context-firewall.md, .prismo/allowed-context.txt, .prismo/blocked-context.txt, and .prismo/firewall-prompt.md.
   The firewall is a local policy file for the agent to follow before reading files; it does not enforce filesystem access by itself.`,
+    shield: `Prismo Shield
+
+Usage:
+  prismo shield [--json] [path] -- <command ...>
+  prismo shield last [--json] [--limit N] [path]
+  prismo shield search <query> [--json] [--limit N] [path]
+
+Examples:
+  prismo shield -- npm test
+  prismo shield -- pytest -q
+  prismo shield --json -- npm run build
+  prismo shield last
+  prismo shield search "auth failure"
+
+Output:
+  Runs the command locally, stores full stdout/stderr under .prismo/shield/runs/, indexes output in SQLite FTS5 when available, and prints only a compact summary plus useful error lines.
+  Search and last retrieve prior shield runs without re-feeding full output into agent context.`,
+    mcp: `Prismo MCP Server
+
+Usage:
+  prismo mcp [path]
+
+Examples:
+  prismo mcp
+  prismo mcp /path/to/repo
+
+Tools exposed:
+  prismo_scan
+  prismo_doctor_dry_run
+  prismo_watch_snapshot
+  prismo_shield_run
+  prismo_shield_search
+  prismo_shield_last
+  prismo_context_pack
+  prismo_firewall
+  prismo_cc_timeline
+
+Output:
+  Starts a local JSON-RPC MCP server over stdio. Use it from MCP-compatible clients so agents can scan context waste, search shielded command output, and request scoped context without loading huge logs into chat.`,
     ci: `Prismo CI
 
 Usage:
@@ -513,6 +577,10 @@ Good first command for people who want to see the value before scanning a repo.`
 
 async function runCli(argv) {
   const [command, ...rest] = argv;
+  if (command === "--version" || command === "-v" || command === "version") {
+    console.log(PACKAGE_VERSION);
+    return;
+  }
   if (!command || command === "--help" || command === "-h") {
     printHelp();
     return;
@@ -521,8 +589,8 @@ async function runCli(argv) {
     printCommandHelp(command);
     return;
   }
-  if (!["dev", "init", "doctor", "firewall", "setup", "scan", "optimize", "context", "cc", "usage", "watch", "demo"].includes(command)) {
-    throw new Error(`Unknown command: ${command}. Try: prismo doctor, prismo watch, prismo firewall, prismo init, prismo scan, prismo optimize, prismo context, prismo cc, or prismo usage`);
+  if (!["dev", "init", "doctor", "firewall", "shield", "mcp", "setup", "scan", "optimize", "context", "cc", "usage", "watch", "demo"].includes(command)) {
+    throw new Error(`Unknown command: ${command}. Try: prismo doctor, prismo watch, prismo shield, prismo mcp, prismo firewall, prismo init, prismo scan, prismo optimize, prismo context, prismo cc, or prismo usage`);
   }
 
   if (command === "demo") {
@@ -604,6 +672,62 @@ async function runCli(argv) {
     return;
   }
 
+  if (command === "shield") {
+    const json = rest.includes("--json");
+    const limitIndex = rest.indexOf("--limit");
+    const limit = parsePositiveInt(limitIndex >= 0 ? rest[limitIndex + 1] : null, 5);
+    const positional = getPositionals(rest, new Set(["--limit"]));
+    if (positional[0] === "last") {
+      const target = positional[1] || process.cwd();
+      const result = runShieldLast(target, { limit });
+      if (json) console.log(JSON.stringify(result, null, 2));
+      else console.log(renderShieldLastTerminal(result));
+      return;
+    }
+    if (positional[0] === "search") {
+      const query = positional[1];
+      const target = positional[2] || process.cwd();
+      const result = runShieldSearch(target, query, { limit });
+      if (json) console.log(JSON.stringify(result, null, 2));
+      else console.log(renderShieldSearchTerminal(result));
+      return;
+    }
+    const separatorIndex = rest.indexOf("--");
+    const beforeSeparator = separatorIndex >= 0 ? rest.slice(0, separatorIndex) : [];
+    const commandArgs = separatorIndex >= 0 ? rest.slice(separatorIndex + 1) : getPositionals(rest);
+    const target = getPositionals(beforeSeparator)[0] || process.cwd();
+    const result = runShield(target, commandArgs);
+    if (json) {
+      console.log(JSON.stringify(result, null, 2));
+    } else {
+      console.log(renderShieldTerminal(result));
+    }
+    process.exitCode = result.exitCode;
+    return;
+  }
+
+  if (command === "mcp") {
+    const target = getPositionals(rest)[0] || process.cwd();
+    runMcpServer({
+      rootDir: path.resolve(target),
+      packageVersion: PACKAGE_VERSION,
+      scanRepo,
+      toJsonPayload,
+      runDoctor,
+      toDoctorJsonPayload,
+      getUsageSummary,
+      getClaudeCodeCostSummary,
+      runOptimize,
+      createOptimizeContext,
+      renderStarterPrompt,
+      runFirewall,
+      runShield,
+      runShieldLast,
+      runShieldSearch,
+    });
+    return;
+  }
+
   if (command === "setup") {
     const json = rest.includes("--json");
     const limitIndex = rest.indexOf("--limit");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "getprismo",
-  "version": "0.1.11",
+  "version": "0.1.14",
   "description": "Local AI coding workflow scanner for Codex, Claude Code, Cursor, and token-waste diagnostics.",
   "license": "MIT",
   "homepage": "https://github.com/shanirsh/prismodev#readme",