residoo 0.5.0 → 0.6.0

package/README.md

@@ -40,6 +40,19 @@ Values are redacted in this report (first/last 4 characters only). Nothing
 scanned here left your machine; residoo makes no network calls.
 ```
 
+That's one snapshot. `residoo watch` runs the same engine continuously and
+alerts the moment a new secret lands, instead of waiting for you to
+remember to scan again; no other tool in the field has anything like it
+(see [Watch: continuous scanning](#watch-continuous-scanning)):
+
+```
+$ residoo watch
+watching 43 sources, 118 files · polling every 5s
+
+2026-09-03 14:02:11  [high]  AWS Access Key ID  AKIA****ABCD
+  claude-code · session-9f2c.jsonl:214 · rf1-8a3e91  Rotate: https://.../access_keys
+```
+
 > [!NOTE]
 > gitleaks and trufflehog scan **commits**. residoo scans the **conversation
 > transcripts** an AI agent leaves behind: a different, previously
@@ -116,6 +129,10 @@ reproduction; everything needed to rerun it ships in this repo.
 - **`residoo watch`**: continuous scanning instead of one snapshot, alerting
   the moment a new secret lands in a transcript. See
   [Watch: continuous scanning](#watch-continuous-scanning) below.
+- **`residoo mcp`**: query findings and manage rotation from inside Claude
+  Code itself, over a hand-rolled MCP server. See
+  [MCP: query findings from inside Claude Code](#mcp-query-findings-from-inside-claude-code)
+  below.
 
 ## Beyond transcripts: configs and planted persistence
 
@@ -288,7 +305,7 @@ As a GitHub Action (this repo doubles as a composite action):
 ```yaml
 steps:
   - uses: actions/checkout@v4
-  - uses: dandovdub/residoo@v0.5.0
+  - uses: dandovdub/residoo@v0.6.0
 ```
 
 As a pre-commit hook:
@@ -296,7 +313,7 @@ As a pre-commit hook:
 ```yaml
 repos:
   - repo: https://github.com/dandovdub/residoo
-    rev: v0.5.0
+    rev: v0.6.0
     hooks:
       - id: residoo
 ```
@@ -419,6 +436,37 @@ verified directly against each one's own `--help` output rather than
 assumed; see [docs/comparison.md](docs/comparison.md) for how the one
 adjacent thing, GitGuardian's `ggshield` AI hook, works differently.
 
+## MCP: query findings from inside Claude Code
+
+`residoo mcp` runs residoo as an MCP server over stdio, so Claude Code can
+query findings and manage the rotation ledger conversationally instead of
+you running the CLI in a terminal:
+
+```bash
+claude mcp add residoo -- residoo mcp
+```
+
+or add it directly to `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "residoo": { "type": "stdio", "command": "residoo", "args": ["mcp"] }
+  }
+}
+```
+
+Five tools, mirroring the CLI exactly: `residoo_scan` (a fresh scan,
+merged with rotation status), `residoo_check` (only what's new since the
+last check in this conversation, backed by the same engine as `watch`),
+`residoo_explain` (a rule's rotation runbook), and `residoo_ack` /
+`residoo_dismiss` (append to the local ledger). Every value returned is
+redacted the same way the CLI's own output is; nothing here makes a
+network call or touches the transcript files themselves. Like the rest of
+residoo, this is hand-rolled against the MCP spec directly, not built on
+`@modelcontextprotocol/sdk`: zero runtime dependencies stays true here
+too.
+
 ## Sources supported today
 
 43 sources: 42 transcript stores plus the agent-config source above, in two

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "residoo",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Find secrets leaking through your AI coding agent's session history. Zero network calls in the scan path, zero dependencies.",
   "license": "MIT",
   "author": "CloudRoam (https://cloudroam.io)",

package/src/cli.js

@@ -11,6 +11,8 @@ const {
   ROTATION_GUIDANCE, guidanceFor, loadAcks, loadDismissed, ackFinding, dismissFinding, renderRotation,
 } = require("./rotation");
 const { startWatch, isTailable } = require("./watch");
+const { startMcpServer } = require("./mcp");
+const { buildTools } = require("./mcpTools");
 
 /**
  * A source is unavailable for the ordinary reason (not installed — nothing
@@ -147,6 +149,20 @@ Watch:
   Ctrl+C stops cleanly and prints a session summary (skipped with --json,
   where the same information is one final NDJSON event).
 
+MCP:
+  residoo mcp              run residoo as an MCP server over stdio, so
+                          Claude Code (or any other MCP client) can query
+                          findings and manage rotation conversationally
+                          instead of a human running the CLI. No network
+                          calls, nothing destructive: the 5 exposed tools
+                          (residoo_scan, residoo_check, residoo_explain,
+                          residoo_ack, residoo_dismiss) mirror scan/watch/
+                          explain/ack/dismiss exactly, and every value
+                          returned is redacted the same way. Register it
+                          with "claude mcp add residoo -- residoo mcp".
+                          Zero runtime dependencies: the protocol is hand-
+                          rolled, not the official SDK.
+
 Rotation:
   residoo explain <rule-id>     full rotation runbook for one detection rule
                                 (where to revoke, steps, what revocation does)
@@ -571,6 +587,44 @@ async function runWatch(args) {
   return 0;
 }
 
+/**
+ * `residoo mcp`: run residoo as an MCP server over stdio. See src/mcp.js
+ * for the protocol engine and src/mcpTools.js for the tool catalog; this
+ * function is only the startup banner (stderr only -- see mcp.js's own
+ * doc comment on why stdout must never carry anything but protocol
+ * messages) and wiring SIGINT/SIGTERM to a clean stop, mirroring runWatch.
+ */
+async function runMcp(args) {
+  const { version } = require("../package.json");
+  const sources = availableSources();
+  process.stderr.write(
+    sources.length
+      ? `residoo mcp: ${sources.length} source(s) available on this machine: ${sources.map((s) => s.label()).join(", ")}\n`
+      : `residoo mcp: no known transcript sources found on this machine (residoo_scan will report none until one is installed and residoo mcp is restarted).\n`
+  );
+  process.stderr.write("residoo mcp: ready. Waiting for a client on stdin...\n");
+
+  const { promise, stop } = startMcpServer({
+    tools: buildTools({ sources }),
+    serverInfo: { name: "residoo", version },
+    instructions: "Find secrets leaking through this machine's AI coding agent session histories. All tool output is redacted; raw secret values are never returned. Nothing here is destructive: scanning is read-only, and ack/dismiss only append to a local audit ledger.",
+  });
+
+  let signalled = false;
+  const onSignal = () => {
+    if (signalled) return;
+    signalled = true;
+    stop();
+  };
+  process.once("SIGINT", onSignal);
+  process.once("SIGTERM", onSignal);
+
+  await promise;
+  process.removeListener("SIGINT", onSignal);
+  process.removeListener("SIGTERM", onSignal);
+  return 0;
+}
+
 async function main(argv) {
   const args = argv.slice(2);
   if (args.includes("-h") || args.includes("--help") || args.length === 0) {
@@ -584,6 +638,7 @@ async function main(argv) {
   if (cmd === "ack") return runAck(args);
   if (cmd === "dismiss") return runDismiss(args);
   if (cmd === "watch") return runWatch(args);
+  if (cmd === "mcp") return runMcp(args);
   if (cmd !== "scan") {
     process.stderr.write(`Unknown command "${cmd}". Try "residoo --help".\n`);
     return 2;

package/src/mcp.js

@@ -0,0 +1,266 @@
+"use strict";
+
+const { createInterface } = require("readline/promises");
+
+/**
+ * `residoo mcp`: a hand-rolled MCP (Model Context Protocol) server over
+ * stdio, so Claude Code (or any other MCP client) can query residoo's
+ * findings and rotation ledger directly instead of a human running the
+ * CLI in a terminal. No `@modelcontextprotocol/sdk` dependency -- residoo
+ * has zero runtime dependencies, no exceptions (see CONTRIBUTING.md), and
+ * MCP's stdio transport is newline-delimited JSON-RPC 2.0, which Node's
+ * own `readline` already handles; every `.jsonl` source adapter in
+ * src/sources/ hand-rolls the same kind of line-delimited JSON parsing.
+ *
+ * This file is the protocol engine only: framing, dispatch, version
+ * negotiation, the outgoing writer, shutdown. It has zero domain
+ * knowledge of scanning/rotation -- see src/mcpTools.js for the actual
+ * tool catalog. `tools` here is just a `Map<name, {name, description,
+ * inputSchema, handler}>` handed in by the caller (mirrors `startWatch`'s
+ * `sources` being handed in by its caller rather than looked up itself).
+ *
+ * Implements the Legacy (initialize-handshake) MCP era only
+ * (`2025-11-25`/`2025-06-18`/`2025-03-26`), which is Claude Code's own
+ * documented DEFAULT for every stdio server -- it only probes stdio
+ * servers for the newer, per-request "Modern" era
+ * (`server/discover`-based) when a user explicitly sets
+ * `MCP_PROTOCOL_NEGOTIATION=auto`. In that opt-in case, the generic
+ * "unknown method" handler below answers `server/discover` instantly with
+ * a plain JSON-RPC -32601, which is exactly what the MCP spec defines as
+ * triggering a Dual-era client's fallback to the Legacy handshake -- so
+ * this server works either way, and implementing `server/discover` itself
+ * is a deliberate, non-blocking v1 scope decision, not an oversight.
+ *
+ * Per the spec's own words: "The server MUST NOT write anything to its
+ * stdout that is not a valid MCP message." `send()` below is the ONLY
+ * function in this file (or in mcpTools.js) allowed to touch `output`;
+ * every log line, startup banner, and shutdown summary goes to
+ * `errOutput` instead. This is the same "stdout is sacred" discipline
+ * watch.js already established, enforced even more strictly here, since
+ * a single stray byte on stdout doesn't just create noise -- it can
+ * corrupt the client's JSON-RPC stream.
+ */
+
+const JSONRPC_VERSION = "2.0";
+
+// All three are "Legacy"-era (initialize-handshake) protocol revisions;
+// none of the wire shapes this file implements (initialize result,
+// tools/list, tools/call, isError) differ across them, so supporting all
+// three costs nothing beyond this list. If the client's requested version
+// isn't one of these, DEFAULT_PROTOCOL_VERSION is what we claim instead.
+const SUPPORTED_PROTOCOL_VERSIONS = ["2025-11-25", "2025-06-18", "2025-03-26"];
+const DEFAULT_PROTOCOL_VERSION = "2025-06-18";
+
+function negotiateProtocolVersion(requested) {
+  if (typeof requested === "string" && SUPPORTED_PROTOCOL_VERSIONS.includes(requested)) return requested;
+  return DEFAULT_PROTOCOL_VERSION;
+}
+
+/**
+ * `startMcpServer({tools, serverInfo, instructions, input, output,
+ * errOutput})` -> `{promise, stop}`. All I/O injectable (mirrors
+ * `startWatch`'s `{sources, options, out, errOut}` contract) so this can
+ * be driven by tests with fake streams and a stub tool map, with no real
+ * scanning involved.
+ */
+function startMcpServer({
+  tools,
+  serverInfo,
+  instructions,
+  input = process.stdin,
+  output = process.stdout,
+  errOutput = process.stderr,
+} = {}) {
+  const rl = createInterface({ input, crlfDelay: Infinity });
+  let stopped = false;
+  let requestsHandled = 0;
+
+  /**
+   * The single write path. `JSON.stringify` already escapes any raw `\n`
+   * inside a string VALUE as the two-character sequence `\` `n` (JSON's
+   * own grammar, RFC 8259, forbids a literal control character in a
+   * string) -- no per-field newline scrubbing is needed here. The only
+   * raw 0x0A byte in the whole write is the one appended below, as the
+   * stdio transport's own frame delimiter.
+   */
+  function send(message) {
+    let text;
+    try {
+      text = JSON.stringify(message);
+    } catch (err) {
+      // `message` contained something JSON.stringify can't serialize (a
+      // circular reference, a BigInt) -- a bug in a tool handler, not a
+      // reason to crash the connection or silently drop a reply the
+      // client may be blocked waiting on. `message.id`, when present,
+      // always came from JSON.parse on the client's own request and
+      // already passed the id-type check in handleLine, so it's
+      // independently safe to reserialize on its own here.
+      errOutput.write(`residoo mcp: failed to serialize outgoing message: ${err instanceof Error ? err.message : String(err)}\n`);
+      const fallbackId = message && typeof message === "object" && "id" in message ? message.id : null;
+      text = JSON.stringify({
+        jsonrpc: JSONRPC_VERSION, id: fallbackId,
+        error: { code: -32603, message: "Internal error: response could not be serialized" },
+      });
+    }
+    output.write(text + "\n");
+  }
+
+  function sendError(id, code, message, data) {
+    send({ jsonrpc: JSONRPC_VERSION, id, error: data === undefined ? { code, message } : { code, message, data } });
+  }
+
+  function sendResult(id, result) {
+    send({ jsonrpc: JSONRPC_VERSION, id, result });
+  }
+
+  function handleInitialize(params, id) {
+    const protocolVersion = negotiateProtocolVersion(params && params.protocolVersion);
+    sendResult(id, {
+      protocolVersion,
+      capabilities: { tools: {} },
+      serverInfo,
+      ...(instructions ? { instructions } : {}),
+    });
+  }
+
+  function handleToolsList(id) {
+    const list = [];
+    for (const tool of tools.values()) {
+      list.push({ name: tool.name, description: tool.description, inputSchema: tool.inputSchema });
+    }
+    sendResult(id, { tools: list });
+  }
+
+  async function handleToolsCall(params, id) {
+    if (!params || typeof params !== "object" || typeof params.name !== "string") {
+      sendError(id, -32602, "Invalid params: 'name' (string) is required");
+      return;
+    }
+    const tool = tools.get(params.name);
+    if (!tool) {
+      sendError(id, -32602, `Unknown tool: ${params.name}`);
+      return;
+    }
+
+    const args = params.arguments && typeof params.arguments === "object" && !Array.isArray(params.arguments)
+      ? params.arguments : {};
+    let result;
+    try {
+      // The handler owns its OWN input validation and is expected to
+      // return {content, isError:true} for both a bad-argument case and a
+      // genuine execution failure -- see SEP-1303: input validation
+      // errors are Tool Execution Errors, not Protocol Errors, so the
+      // model can see the message and self-correct in the same turn.
+      // This dispatcher does not and should not try to tell those two
+      // cases apart.
+      result = await tool.handler(args);
+      if (!result || !Array.isArray(result.content)) {
+        // Defensive: a handler bug in mcpTools.js must not corrupt the
+        // wire protocol -- fail safe into a well-formed isError result.
+        result = { content: [{ type: "text", text: "Tool returned no content (internal error)." }], isError: true };
+      }
+    } catch (err) {
+      // Anything a handler THROWS still lands as a tool execution error,
+      // not -32603 -- that code is reserved for bugs in this dispatcher
+      // itself, not in a tool. errOutput gets the full detail for
+      // operator debugging; the client only ever sees the message string.
+      errOutput.write(`residoo mcp: tool "${params.name}" threw: ${err instanceof Error ? (err.stack || err.message) : String(err)}\n`);
+      result = { content: [{ type: "text", text: `Failed: ${err instanceof Error ? err.message : String(err)}` }], isError: true };
+    }
+    sendResult(id, result);
+  }
+
+  async function dispatch(method, params, hasId, id) {
+    switch (method) {
+      case "initialize":
+        if (!hasId) return;
+        return handleInitialize(params, id);
+      case "notifications/initialized":
+        // A true notification by the method's own contract: never reply,
+        // even if a client mistakenly attached an id -- nothing in v1
+        // depends on this flag anyway (no server-initiated requests).
+        return;
+      case "tools/list":
+        if (!hasId) return;
+        return handleToolsList(id);
+      case "tools/call":
+        if (!hasId) return;
+        return handleToolsCall(params, id);
+      default:
+        // Includes a `server/discover` probe from a client with
+        // MCP_PROTOCOL_NEGOTIATION=auto (see file doc comment) -- MUST
+        // reply fast (no I/O, no await, above) so that fallback resolves
+        // immediately rather than after a client-side timeout.
+        if (!hasId) return;
+        sendError(id, -32601, `Method not found: ${method}`);
+    }
+  }
+
+  async function handleLine(line) {
+    if (line.trim() === "") return false;
+    let msg;
+    try {
+      msg = JSON.parse(line);
+    } catch {
+      // Per JSON-RPC 2.0 section 5: if the id could not even be
+      // determined (a parse failure means we never got that far), the
+      // error response's id MUST be null.
+      sendError(null, -32700, "Parse error");
+      errOutput.write(`residoo mcp: received unparseable line (${line.length} bytes): ${line.slice(0, 200)}\n`);
+      return false;
+    }
+    if (msg === null || typeof msg !== "object" || Array.isArray(msg)) {
+      sendError(null, -32600, "Invalid Request: expected a JSON object");
+      return false;
+    }
+
+    // Deliberately `hasOwnProperty`, never `msg.id` truthiness -- id:0 is
+    // a valid, falsy request id, and conflating "id key absent" (a
+    // notification: never reply, even with an error) with "id present but
+    // falsy" is exactly the kind of one-character bug that silently
+    // breaks a client's parser.
+    const hasId = Object.prototype.hasOwnProperty.call(msg, "id");
+    const id = hasId ? msg.id : undefined;
+    const idIsValidType = id === null || typeof id === "string" || typeof id === "number";
+
+    if (msg.jsonrpc !== JSONRPC_VERSION || typeof msg.method !== "string") {
+      if (!hasId) return false; // malformed NOTIFICATION: JSON-RPC promises no reply, ever
+      sendError(idIsValidType ? id : null, -32600, "Invalid Request");
+      return false;
+    }
+    if (hasId && !idIsValidType) {
+      // id present but not string/number/null: can't trust echoing it
+      // back (and can't safely re-serialize it if it's e.g. an object).
+      sendError(null, -32600, "Invalid Request: id must be a string, number, or null");
+      return false;
+    }
+
+    try {
+      await dispatch(msg.method, msg.params, hasId, id);
+    } catch (err) {
+      errOutput.write(`residoo mcp: internal error handling "${msg.method}": ${err instanceof Error ? (err.stack || err.message) : String(err)}\n`);
+      if (hasId) sendError(id, -32603, "Internal error");
+    }
+    return hasId;
+  }
+
+  function stop() {
+    if (stopped) return;
+    stopped = true;
+    rl.close(); // unblocks the `for await` loop below on its next iteration
+  }
+
+  const promise = (async () => {
+    for await (const line of rl) {
+      if (stopped) break;
+      if (await handleLine(line)) requestsHandled++;
+    }
+    if (!stopped) stopped = true;
+    errOutput.write(`residoo mcp: shutting down. Handled ${requestsHandled} request(s).\n`);
+    return { requestsHandled };
+  })();
+
+  return { promise, stop };
+}
+
+module.exports = { startMcpServer, SUPPORTED_PROTOCOL_VERSIONS, DEFAULT_PROTOCOL_VERSION };

package/src/mcpTools.js

@@ -0,0 +1,341 @@
+"use strict";
+
+const path = require("path");
+const { scan } = require("./scan");
+const {
+  ROTATION_GUIDANCE, guidanceFor, loadAcks, loadDismissed,
+  ackFinding, dismissFinding, renderRotation,
+} = require("./rotation");
+const { sweepOnce } = require("./watch");
+
+/**
+ * The tool catalog for `residoo mcp` (see src/mcp.js for the protocol
+ * engine that calls into this). Every handler here calls the same PURE
+ * engine functions the CLI itself uses (`scan`, `renderRotation`,
+ * `ackFinding`/`dismissFinding`, `guidanceFor`, `sweepOnce`) -- never
+ * `cli.js`'s `runX()` functions or `watch.js`'s `startWatch()`, since
+ * those specific functions write to stdout by design (they're the
+ * human-facing presenters), and this file's whole job is to never let a
+ * byte reach stdout except through mcp.js's own `send()`.
+ *
+ * `verify` is not exposed as a parameter on ANY tool here, on purpose: a
+ * human typing `--verify` at a terminal is a deliberate, legible act; an
+ * autonomous model choosing a network-triggering parameter mid-
+ * conversation is a different trust boundary, and a generic tool-approval
+ * prompt may not surface that a given call also makes a live vendor API
+ * request with a real secret. Every `scan()`/`sweepOnce()` call below
+ * hardcodes `verify: false`.
+ */
+
+const FINGERPRINT_PATTERN = /^rf1-[0-9a-f]{32}$/;
+
+function textResult(obj) {
+  return { content: [{ type: "text", text: JSON.stringify(obj) }] };
+}
+function errorResult(message) {
+  return { content: [{ type: "text", text: message }], isError: true };
+}
+
+function rejectUnknownKeys(args, allowed) {
+  const errs = [];
+  for (const k of Object.keys(args)) {
+    if (!allowed.has(k)) errs.push(`unexpected property "${k}"`);
+  }
+  return errs;
+}
+
+/** Shared arg shape for residoo_scan/residoo_check: includeNoisy, includeSuppressed, maxEntries. */
+function validateSweepArgs(args, allowedKeys) {
+  const errs = rejectUnknownKeys(args, allowedKeys);
+  if (args.includeNoisy !== undefined && typeof args.includeNoisy !== "boolean") errs.push("includeNoisy must be a boolean");
+  if (args.includeSuppressed !== undefined && typeof args.includeSuppressed !== "boolean") errs.push("includeSuppressed must be a boolean");
+  let maxEntries = 25;
+  if (args.maxEntries !== undefined) {
+    if (typeof args.maxEntries !== "number" || !Number.isInteger(args.maxEntries) || args.maxEntries < 1 || args.maxEntries > 200) {
+      errs.push("maxEntries must be an integer between 1 and 200");
+    } else {
+      maxEntries = args.maxEntries;
+    }
+  }
+  return { errs, includeNoisy: args.includeNoisy === true, includeSuppressed: args.includeSuppressed === true, maxEntries };
+}
+
+/** Drop the full step-by-step runbook (redundant once per shared rule id across many entries -- call residoo_explain for that) and any null-valued optional field. */
+function trimGuidance(g) {
+  if (!g) return null;
+  const out = { label: g.label };
+  if (g.rotateUrl) out.rotateUrl = g.rotateUrl;
+  if (g.consolePath) out.consolePath = g.consolePath;
+  if (g.revokeNote) out.revokeNote = g.revokeNote;
+  if (g.generic) out.generic = true;
+  return out;
+}
+
+function shapeRotationEntry(e) {
+  const out = {
+    fingerprint: e.fingerprint, ruleId: e.ruleId, label: e.label, preview: e.preview,
+    status: e.status, occurrences: e.occurrences, files: e.files, sources: e.sources,
+    guidance: trimGuidance(e.guidance),
+  };
+  if (e.ackedAt) out.ackedAt = e.ackedAt;
+  if (e.ackNote) out.ackNote = e.ackNote;
+  if (e.lastSeenMs != null) out.lastSeenAt = new Date(e.lastSeenMs).toISOString();
+  if (e.pairedSecretPreview) out.pairedSecretPreview = e.pairedSecretPreview;
+  if (e.pairedAccessKeyPreview) out.pairedAccessKeyPreview = e.pairedAccessKeyPreview;
+  if (e.pairedOtherPreview) { out.pairedOtherPreview = e.pairedOtherPreview; out.pairedOtherLabel = e.pairedOtherLabel; }
+  if (e.jwtExpiresAtMs != null) out.jwtExpiresAtMs = e.jwtExpiresAtMs;
+  return out;
+}
+
+function buildScanSummary(scope, counts, filesScanned, sourceCount) {
+  const scopeText = scope.type === "project" ? `project "${scope.projectDir}"` : `${sourceCount} source(s)`;
+  if (counts.distinct === 0) return `Scanned ${scopeText}, ${filesScanned} file(s). No secrets found.`;
+  const bits = [];
+  if (counts.pending > 0) bits.push(`${counts.pending} pending rotation`);
+  if (counts.acked > 0) bits.push(`${counts.acked} already acknowledged`);
+  if (counts.dismissed > 0) bits.push(`${counts.dismissed} dismissed`);
+  return `Scanned ${scopeText}, ${filesScanned} file(s). ${counts.distinct} distinct secret(s): ${bits.join(", ")}.`;
+}
+
+/**
+ * `buildTools({sources})` returns a fresh `Map<name, {name, description,
+ * inputSchema, handler}>` for one `residoo mcp` server invocation.
+ * Session-scoped state (the fingerprint-hallucination guard, and
+ * residoo_check's tracked/seen Maps) lives in this function's closure, not
+ * at module scope, so each server run gets its own clean state and tests
+ * can build independent tool sets without cross-test pollution.
+ *
+ * `sources` is captured ONCE here (evaluated by the caller before this is
+ * called), matching `residoo watch`'s own existing, documented limitation:
+ * an agent tool installed mid-session needs a restart to be picked up.
+ */
+function buildTools({ sources }) {
+  const sessionSeenFingerprints = new Set();
+  const checkTracked = new Map();
+  const checkSeen = new Map();
+  let checkStarted = false;
+
+  async function handleScan(args) {
+    const SCAN_KEYS = new Set(["projectDir", "includeNoisy", "includeSuppressed", "maxEntries"]);
+    const { errs, includeNoisy, includeSuppressed, maxEntries } = validateSweepArgs(args, SCAN_KEYS);
+    if (args.projectDir !== undefined && typeof args.projectDir !== "string") errs.push("projectDir must be a string");
+    if (errs.length) return errorResult(`Invalid arguments: ${errs.join("; ")}`);
+
+    let scanSources;
+    let scope = { type: "machine" };
+    if (args.projectDir !== undefined) {
+      const projectArtifacts = require("./sources/project-artifacts");
+      const resolved = path.resolve(args.projectDir);
+      const src = projectArtifacts.withRoot(resolved);
+      if (!src.available()) return errorResult(`"${args.projectDir}" is not a readable directory.`);
+      scanSources = [src];
+      scope = { type: "project", projectDir: resolved };
+    } else {
+      scanSources = sources;
+    }
+
+    const result = await scan({ sources: scanSources, includeNoisy, includeSuppressed, verify: false, noColor: true });
+    const acks = loadAcks();
+    const dismissed = loadDismissed();
+    const rotation = renderRotation(result.findings, acks, dismissed);
+    for (const e of rotation.entries) sessionSeenFingerprints.add(e.fingerprint);
+
+    const total = rotation.entries.length;
+    const truncated = total > maxEntries;
+    const entries = rotation.entries.slice(0, maxEntries).map(shapeRotationEntry);
+    const sourceCount = scope.type === "project" ? 1 : scanSources.length;
+
+    return textResult({
+      scannedAt: new Date().toISOString(),
+      scope,
+      filesScanned: result.filesScanned,
+      sourcesScanned: result.sourcesScanned,
+      bytesScanned: result.bytesScanned,
+      unreadable: { count: result.unreadableFiles.length, sample: result.unreadableFiles.slice(0, 5) },
+      counts: rotation.counts,
+      entries,
+      truncated,
+      truncatedCount: truncated ? total - maxEntries : 0,
+      summary: buildScanSummary(scope, rotation.counts, result.filesScanned, sourceCount),
+    });
+  }
+
+  async function handleCheck(args) {
+    const CHECK_KEYS = new Set(["includeNoisy", "includeSuppressed", "maxEntries"]);
+    const { errs, includeNoisy, includeSuppressed, maxEntries } = validateSweepArgs(args, CHECK_KEYS);
+    if (errs.length) return errorResult(`Invalid arguments: ${errs.join("; ")}`);
+
+    const firstCheckThisSession = !checkStarted;
+    checkStarted = true;
+
+    const ledger = { acks: loadAcks(), dismissed: loadDismissed() };
+    const events = [];
+    const emit = (e) => events.push(e);
+    const stats = await sweepOnce({
+      sources, tracked: checkTracked, seen: checkSeen, ledger,
+      options: { includeNoisy, includeSuppressed, verify: false, noColor: true }, emit,
+    });
+
+    const allNew = events.filter((e) => e.type === "finding");
+    const allReexposures = events.filter((e) => e.type === "reexposure");
+    for (const e of allNew) sessionSeenFingerprints.add(e.fingerprint);
+
+    const newFindings = allNew.slice(0, maxEntries).map((e) => ({
+      fingerprint: e.fingerprint, ruleId: e.ruleId, label: e.label, confidence: e.confidence,
+      source: e.source, relFile: e.relFile, line: e.line, lineIsAbsolute: e.lineIsAbsolute,
+      preview: e.preview, guidance: trimGuidance(e.guidance),
+    }));
+    const reExposures = allReexposures.slice(0, maxEntries).map((e) => ({ ruleId: e.ruleId, preview: e.preview, count: e.count }));
+    const droppedNew = Math.max(0, allNew.length - newFindings.length);
+    const droppedReexp = Math.max(0, allReexposures.length - reExposures.length);
+    const truncatedCount = droppedNew + droppedReexp;
+
+    let summary;
+    if (firstCheckThisSession && stats.loud === 0) {
+      summary = "First check this session -- baseline established, watching from now on. This does not mean nothing is on disk; call residoo_scan for that.";
+    } else if (stats.loud === 0 && stats.quiet === 0) {
+      summary = "Nothing new since the last check.";
+    } else {
+      const bits = [];
+      if (stats.loud > 0) bits.push(`${stats.loud} new finding(s)`);
+      if (stats.quiet > 0) bits.push(`${stats.quiet} re-exposure(s) of already-known secrets`);
+      summary = bits.join(", ") + " since your last check.";
+    }
+
+    return textResult({
+      checkedAt: new Date().toISOString(),
+      firstCheckThisSession,
+      newFindings,
+      reExposures,
+      counts: { newFindings: stats.loud, reExposures: stats.quiet, suppressedByLedger: stats.suppressedByLedger },
+      truncated: truncatedCount > 0,
+      truncatedCount,
+      summary,
+    });
+  }
+
+  async function handleExplain(args) {
+    const errs = rejectUnknownKeys(args, new Set(["ruleId"]));
+    if (args.ruleId !== undefined && typeof args.ruleId !== "string") errs.push("ruleId must be a string");
+    if (errs.length) return errorResult(`Invalid arguments: ${errs.join("; ")}`);
+
+    if (args.ruleId === undefined) {
+      const ruleIds = Object.keys(ROTATION_GUIDANCE).map((id) => ({ id, label: ROTATION_GUIDANCE[id].label }));
+      return textResult({ ruleIds });
+    }
+    const known = Object.prototype.hasOwnProperty.call(ROTATION_GUIDANCE, args.ruleId);
+    const g = guidanceFor(args.ruleId);
+    return textResult({
+      ruleId: args.ruleId, known, label: g.label,
+      rotateUrl: g.rotateUrl || null, consolePath: g.consolePath || null,
+      steps: g.steps, revokeNote: g.revokeNote, generic: g.generic === true,
+    });
+  }
+
+  async function resolveTool(kind, args) {
+    const errs = rejectUnknownKeys(args, new Set(["fingerprint", "note"]));
+    if (typeof args.fingerprint !== "string") {
+      errs.push("fingerprint is required and must be a string");
+    } else if (!FINGERPRINT_PATTERN.test(args.fingerprint)) {
+      errs.push("fingerprint must match ^rf1-[0-9a-f]{32}$ -- copy it verbatim from a prior residoo_scan/residoo_check result, never construct or guess one");
+    }
+    if (args.note !== undefined && typeof args.note !== "string") errs.push("note must be a string");
+    if (typeof args.note === "string" && args.note.length > 2000) errs.push("note must be 2000 characters or fewer");
+    if (errs.length) return errorResult(`Invalid arguments: ${errs.join("; ")}`);
+
+    let entry;
+    try {
+      entry = kind === "ack" ? ackFinding(args.fingerprint, args.note) : dismissFinding(args.fingerprint, args.note);
+    } catch (err) {
+      return errorResult(`Failed to ${kind === "ack" ? "acknowledge" : "dismiss"} finding: ${err instanceof Error ? err.message : String(err)}`);
+    }
+
+    const warning = sessionSeenFingerprints.has(args.fingerprint)
+      ? null
+      : "This fingerprint was not returned by a residoo_scan or residoo_check call in this session -- it may not correspond to a real finding. Relay this warning rather than treating the response as proof it matched something real.";
+
+    return textResult({
+      fingerprint: entry.fingerprint, at: entry.at, note: entry.note || null,
+      status: kind === "ack" ? "acked" : "dismissed", ledgerFile: entry.file, warning,
+      summary: `${kind === "ack" ? "Acknowledged" : "Dismissed"} ${entry.fingerprint} at ${entry.at}.`,
+    });
+  }
+
+  const tools = new Map();
+  tools.set("residoo_scan", {
+    name: "residoo_scan",
+    description: "Run a fresh, read-only secret scan across every AI coding agent transcript store residoo knows about on this machine (or, if projectDir is given, across one project's committed agent artifacts -- transcripts, agent configs, .env files -- instead), merged with the local rotation ledger so each distinct finding also shows whether it is pending, already acknowledged as rotated, or dismissed as not a real secret. Performs real local disk reads only (can take a few seconds on a machine with many/large transcripts); makes zero network calls and modifies nothing. Every secret is always returned as a short redacted preview (first/last 4 characters) -- the raw value is never included anywhere in the response. Use this for 'do I have any leaked secrets right now' or 'give me the full current picture.' For 'what is new since I last checked in this conversation', call residoo_check instead -- it is much cheaper and only reports newly-appeared findings, not everything on disk.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        projectDir: { type: "string", description: "Absolute path to a project/repo directory to scan instead of the machine-wide transcript stores (same as `residoo scan --project <dir>`). Omit for the default machine-wide scan." },
+        includeNoisy: { type: "boolean", default: false, description: "Also run residoo's two low-confidence heuristic rules (generic password/secret assignments) -- catches more, false-positives more. Off by default." },
+        includeSuppressed: { type: "boolean", default: false, description: "Include matches normally hidden because they look like vendor-documented example values or placeholder text. Off by default." },
+        maxEntries: { type: "integer", minimum: 1, maximum: 200, default: 25, description: "Cap on distinct findings returned in full detail, pending-first. Counts in the response are always exact even when the entry list is truncated." },
+      },
+      required: [],
+      additionalProperties: false,
+    },
+    handler: handleScan,
+  });
+  tools.set("residoo_check", {
+    name: "residoo_check",
+    description: "Report only what is NEW since the last time this tool was called in this conversation (or since the server started, on the first call). Backed by the same incremental engine as `residoo watch`, but called once per invocation instead of running continuously -- it tails newly-appended bytes and re-reads only files that changed, never a full disk crawl, so it is much cheaper than residoo_scan for a repeat check later in the same session. On the very FIRST call, it silently establishes a baseline and reports zero new findings by design -- this means 'watch just started,' not 'nothing is wrong'; the response's firstCheckThisSession field tells you which case you are in, and you should say so if it is true rather than implying a clean result. Call residoo_scan for a full picture of everything currently on disk. Never makes network calls, never modifies anything.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        includeNoisy: { type: "boolean", default: false, description: "Same meaning as residoo_scan." },
+        includeSuppressed: { type: "boolean", default: false, description: "Same meaning as residoo_scan." },
+        maxEntries: { type: "integer", minimum: 1, maximum: 200, default: 25, description: "Cap on new findings / re-exposures returned in full detail. Counts are always exact even when truncated." },
+      },
+      required: [],
+      additionalProperties: false,
+    },
+    handler: handleCheck,
+  });
+  tools.set("residoo_explain", {
+    name: "residoo_explain",
+    description: "Look up residoo's rotation runbook for one detection rule id (e.g. github_pat, aws_access_key_id) -- what the credential is, where to rotate/revoke it in the vendor's console, and numbered steps. Pure local lookup against residoo's built-in guidance table; no network calls, no prior scan needed. Pass the exact ruleId from a finding returned by residoo_scan or residoo_check -- do not guess one. Omit ruleId to get the full list of every rule id residoo has guidance for with a one-line label each. If a rule id is not recognized, this still returns a response (never errors) -- an honest generic fallback with known: false.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        ruleId: { type: "string", description: "A rule id from a prior finding's ruleId field. Omit to list every known rule id instead." },
+      },
+      required: [],
+      additionalProperties: false,
+    },
+    handler: handleExplain,
+  });
+  tools.set("residoo_ack", {
+    name: "residoo_ack",
+    description: "Record that the credential behind one specific finding has been rotated. This ONLY appends an entry to residoo's local rotation ledger (~/.residoo/rotations.json) -- the same additive, non-destructive audit file `residoo ack` writes from a terminal. It never touches, edits, or deletes the transcript file the secret was found in, and it does not rotate or revoke the credential itself -- the human still has to go do that at the vendor; use residoo_explain first if they need the steps. fingerprint MUST be copied verbatim from a fingerprint field returned by a prior residoo_scan or residoo_check call in this conversation -- never construct, guess, or reformat one; it is a hash, not something you can compute. Acknowledging a fingerprint that does not match any real finding silently records a no-op entry rather than erroring, which is why the response includes a warning field when the fingerprint was not seen earlier this session -- relay that warning to the user rather than treating a clean-looking response as proof it matched something real. note is optional free text; it is sanitized and length-capped server-side, but treat it as logged and do not put an actual secret value in it.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        fingerprint: { type: "string", pattern: "^rf1-[0-9a-f]{32}$", description: "Exact fingerprint string from a prior scan/check finding. Never invent one." },
+        note: { type: "string", maxLength: 2000, description: "Optional note on how/when it was rotated. Server-side sanitization caps this further and redacts any accidental secret-shaped text." },
+      },
+      required: ["fingerprint"],
+      additionalProperties: false,
+    },
+    handler: (args) => resolveTool("ack", args),
+  });
+  tools.set("residoo_dismiss", {
+    name: "residoo_dismiss",
+    description: "Record that one specific finding was reviewed and determined NOT to be a real secret (a test fixture, an already-dead example string, a vendor sample not on residoo's built-in suppression list) -- distinct from residoo_ack, which means a real credential was rotated. Same ledger, same fingerprint-must-come-from-a-prior-scan-or-check rule, same non-destructive guarantee (only appends to ~/.residoo/rotations.json; never touches the scanned file).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        fingerprint: { type: "string", pattern: "^rf1-[0-9a-f]{32}$", description: "Exact fingerprint string from a prior scan/check finding. Never invent one." },
+        note: { type: "string", maxLength: 2000, description: "Optional note on why it was dismissed. Server-side sanitization caps this further and redacts any accidental secret-shaped text." },
+      },
+      required: ["fingerprint"],
+      additionalProperties: false,
+    },
+    handler: (args) => resolveTool("dismiss", args),
+  });
+
+  return tools;
+}
+
+module.exports = { buildTools };