sentinel-ir-mcp 0.4.3 → 0.4.5

package/README.md

@@ -25,6 +25,29 @@ of safety. Other languages are not supported yet. What is detected in Python
 (and what is not) is listed in the
 [sentinel-ir README](https://gitlab.com/jakubrojicek11/sentinel-ir#python).
 
+**0.4.5** adds to that log the SHA-256 of every file the server read, so you
+can check later which version of a file the agent was shown (see
+[Audit log](#audit-log)).
+
+**0.4.4** can keep a log of what the agent asked for (off unless you turn it on):
+
+- **One question in `setup`:** *"Keep a log of what the agent asks for (file
+  names and results, never your code)? [y/N]"*. Or `setup --audit-log`;
+  `--no-audit-log` turns it off. Running `setup` again keeps the setting.
+- **One command to read it:** `npx -y sentinel-ir-mcp@0.4 log` prints the last
+  50 entries as plain lines, `--all` everything, `--json` for scripts:
+
+  ```text
+  2026-10-18 10:32:05 [cursor] file src/app.js: critical
+  2026-10-18 10:32:09 [cursor] REFUSED file secrets/aws.js: excluded by your settings
+  2026-10-18 10:33:40 [cursor] folder .: 42 file(s) (1 critical, 6 medium, 35 low), 3 excluded
+      critical src/app.js
+  ```
+- `doctor` says whether the log is on, where it is and how big, and proves the
+  log can be written. Details: [Audit log](#audit-log).
+
+Also uses `sentinel-ir` 0.4.5 (Python parse errors point where Python does).
+
 **0.4.3** lets you exclude files and folders:
 
 - **One question in `setup`:** *"Files or folders the agent must not read"*,
@@ -187,7 +210,7 @@ code 0 when everything passes, 1 otherwise; `--json` gives a machine-readable
 report.
 
 Only `setup` writes files, and only the client config. The MCP server itself
-stays read-only.
+reads only; the one exception is the [audit log](#audit-log), if you turn it on.
 
 **Cursor:** a server from a project `.cursor/mcp.json` starts switched off.
 Open Cursor Settings → Customize → MCPs and turn on the switch next to
@@ -317,12 +340,69 @@ npx -y sentinel-ir-mcp@0.4 setup --client cursor --exclude secrets --exclude "*.
 The exclusions only bind this server. An agent that can read files with
 other tools of its client is told about them, but this server cannot stop it.
 
+### Audit log
+
+```bash
+npx -y sentinel-ir-mcp@0.4 setup --client cursor --audit-log   # or answer "y" in setup
+npx -y sentinel-ir-mcp@0.4 log                                 # what the agent asked for
+```
+
+| system | folder |
+|---|---|
+| Windows | `%LOCALAPPDATA%\sentinel-ir-mcp\audit-log\` |
+| macOS | `~/Library/Logs/sentinel-ir-mcp/` |
+| Linux | `~/.local/state/sentinel-ir-mcp/audit-log/` (or `$XDG_STATE_HOME`) |
+
+`--audit-log=<folder>` uses another folder: a full path outside the project
+(the characters `" & | < > ^ % !` are refused because Windows starts the
+server through `cmd`). Then read it with `log --dir <folder>`.
+
+- **What is written:** one JSON line per tool call in `audit-YYYY-MM-DD.jsonl`
+  (local date): time, client name, tool, the path the agent asked for, the
+  result (risk, `analysisStatus`, file counts, up to 20 `critical`/`high` file
+  paths of a folder) or why it was refused (`excluded`, `outside`,
+  `not-found`, `too-large`), and the duration. A line when the server starts.
+- **Which version of a file (0.4.5):** for every file the server read, the
+  SHA-256 of the exact bytes it analyzed: `sha256` for `analyze_file`; for
+  `analyze_directory` the folder line gets a `call` id and `hashed` count,
+  and the hashes follow in `"event": "hashes"` lines (40 files each, same
+  `call` id), so no line gets long. `log` shows the first 12 digits for
+  files and the risky files of a folder; `log --json` has all of them. To check whether a file is still the
+  one the agent saw, compare with `certutil -hashfile <file> SHA256`
+  (Windows), `shasum -a 256 <file>` (macOS) or `sha256sum <file>` (Linux).
+  Pasted code (`analyze_code`) gets no hash: a very short snippet could be
+  guessed from it. The tool answers to the agent are unchanged.
+- **What is not written:** source code. For `analyze_code` only the size in
+  bytes, the language and the risk. Names of excluded files are not written
+  either, only their count. Long values are cut to 300 characters.
+- **Cleanup:** day files older than 30 days are deleted; a day stops 1 MB
+  below 50 MB with one line saying so, so parallel servers stay under 50 MB
+  too. Other files in the folder are never touched.
+- **Set by you only,** like exclusions: the agent and the project cannot turn
+  it on, off or move it. The log is never written inside the project.
+- **Safe to read:** a path with a newline cannot add a fake line (JSON
+  escapes it), and `log` shows control and bidi characters as `\u{1b}`, so a
+  path cannot recolor or rewrite your terminal.
+- **Never breaks the tools:** when the log cannot be written (disk full, no
+  permission) the tools answer as usual and the server says so once on stderr;
+  `doctor` reports it as `[FAIL]`. Several servers can share the folder: each
+  line is one append, so lines do not mix.
+- `doctor` adds one line, `doctor checked that the log can be written`, and
+  none of its own tool calls.
+- A day file that is a symlink, junction or hard link is not written to, on
+  Windows too, so the log cannot be used to overwrite another file.
+- It records only what the agent asked **this server** for. Other file tools
+  of your AI app are not in it.
+- Files are created readable by you only (`0600`, folder `0700`; on Windows
+  the folder in `%LOCALAPPDATA%` is private to your account).
+
 ### Options
 
 ```text
-sentinel-ir-mcp [--exclude <name>]... [--max-file-bytes <n>] [--max-files <n>] [--time-budget-ms <n>] [folder ...]
+sentinel-ir-mcp [--exclude <name>]... [--audit-log[=<folder>]] [--max-file-bytes <n>] [--max-files <n>] [--time-budget-ms <n>] [folder ...]
 
   --exclude <name>       file or folder the file tools refuse (repeatable, max 100); see Excluding files
+  --audit-log[=<folder>] keep a log of the tool calls (never source code); see Audit log
 
   --max-file-bytes <n>   largest file to analyze (default 1048576 = 1 MiB, max 2097152 = 2 MiB)
   --time-budget-ms <n>   analyze_directory starts no new file after this (default 30000, max 600000)
@@ -331,9 +411,10 @@ sentinel-ir-mcp [--exclude <name>]... [--max-file-bytes <n>] [--max-files <n>] [
 
 ## What the server can and cannot do
 
-- **Reads only.** The MCP server never writes files, runs commands or opens
-  network connections (only the separate `setup` command writes, and only the
-  client config file you confirm; `doctor` starts this package's own server). The only files it opens are `.js`/`.mjs`/`.cjs`/`.ts`/`.mts`/`.cts`/`.tsx`/`.py`/`.pyi` files up to
+- **Reads only.** The MCP server never writes project files, runs commands or
+  opens network connections. It writes only the [audit log](#audit-log) when
+  you turn it on (outside the project). The separate `setup` command writes
+  only the client config file you confirm; `doctor` starts this package's own server. The only files it opens are `.js`/`.mjs`/`.cjs`/`.ts`/`.mts`/`.cts`/`.tsx`/`.py`/`.pyi` files up to
   `--max-file-bytes`.
 - **Only inside the allowed folders.** Every path is resolved to its real path
   (symlinks followed) and must lie inside a folder given on the command line,

package/bin/sentinel-ir-mcp.js

@@ -9,33 +9,40 @@ const path = require("path");
 const { StdioServerTransport } = require("@modelcontextprotocol/sdk/server/stdio.js");
 const { createServer, DEFAULT_LIMITS } = require("../src/server");
 const { normalizePattern, ExcludeError, MAX_PATTERNS } = require("../src/exclude");
+const { AuditLogError, defaultAuditDir, normalizeAuditDir, assertOutsideProjects } = require("../src/auditLog");
 const { version } = require("../package.json");
 
-const USAGE = `sentinel-ir-mcp ${version} — MCP server for sentinel-ir (JavaScript and TypeScript)
+const USAGE = `sentinel-ir-mcp ${version} — MCP server for sentinel-ir (JavaScript, TypeScript and Python)
 
 Usage: sentinel-ir-mcp [options] [folder ...]
-       sentinel-ir-mcp setup | doctor | guide [--help]
+       sentinel-ir-mcp setup | doctor | guide | log [--help]
 
   setup                  Connect Sentinel-IR to an AI client (shows the change first)
   doctor                 Check Node.js, the client config and a real MCP connection
   guide                  Print short usage instructions for AI agents
+  log                    Show what the agent asked for (needs --audit-log)
 
   folder                 Folder(s) the file tools may read. A folder named like a
-                         command must be written as ./setup, ./doctor or ./guide. Without folders the
-                         server uses the MCP roots offered by the client; if the
+                         command must be written as ./setup, ./doctor, ./guide or
+                         ./log. Without folders the server uses the MCP roots offered by the client; if the
                          client offers none, only analyze_code works.
   --exclude <name>       A file or folder the file tools must refuse; repeat for more.
                          secrets = any file or folder named so, config/prod.js =
                          this path in an allowed folder, *.min.js = by mask,
                          ** = any folders. Set by you; the project cannot change it.
+  --audit-log            Write a log of what the agent asks this server for (paths,
+                         results, refusals; never source code) to
+                         ${defaultAuditDir()}
+  --audit-log=<folder>   The same log in another folder (a full path outside the project)
   --max-file-bytes <n>   Largest file to analyze (default ${DEFAULT_LIMITS.maxFileBytes}, max ${DEFAULT_LIMITS.hardMaxFileBytes})
   --time-budget-ms <n>   analyze_directory starts no new file after this time (default ${DEFAULT_LIMITS.timeBudgetMs}, max ${DEFAULT_LIMITS.hardMaxTimeBudgetMs})
   --max-files <n>        Default file limit for analyze_directory (default ${DEFAULT_LIMITS.maxFiles}, max ${DEFAULT_LIMITS.hardMaxFiles})
   -h, --help             Show this help
   -v, --version          Show the version
 
-The server only reads files. It never writes, executes or uses the network.
-Only "setup" writes, and only the client config file you confirm.`;
+The server only reads files. It never executes code or uses the network, and it
+writes nothing except the audit log when you turn it on. "setup" writes only the
+client config file you confirm. See the log with: sentinel-ir-mcp log`;
 
 function die(message) {
     process.stderr.write(`sentinel-ir-mcp: ${message}\n\n${USAGE}\n`);
@@ -70,6 +77,11 @@ function parseArgs(argv) {
                 die(e.message);
             }
             if (opts.exclude.length > MAX_PATTERNS) die(`at most ${MAX_PATTERNS} --exclude options`);
+        } else if (arg === "--audit-log") {
+            try { opts.auditDir = value === undefined ? defaultAuditDir() : normalizeAuditDir(value); } catch (e) {
+                if (!(e instanceof AuditLogError)) throw e;
+                die(e.message);
+            }
         } else if (arg.startsWith("-")) {
             die(`unknown option ${arg}`);
         } else {
@@ -80,6 +92,12 @@ function parseArgs(argv) {
             opts.roots.push(dir);
         }
     }
+    if (opts.auditDir) {
+        try { assertOutsideProjects(opts.auditDir, opts.roots); } catch (e) {
+            if (!(e instanceof AuditLogError)) throw e;
+            die(e.message);
+        }
+    }
     return opts;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sentinel-ir-mcp",
-  "version": "0.4.3",
+  "version": "0.4.5",
   "description": "MCP server for sentinel-ir: lets AI agents (Claude Desktop, Cursor, Windsurf, ...) read a compact structural IR of JavaScript, TypeScript and Python files instead of the raw source. Read-only, sandboxed to allowed folders.",
   "main": "src/server.js",
   "bin": {
@@ -19,7 +19,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.32.1",
-    "sentinel-ir": "^0.4.3",
+    "sentinel-ir": "^0.4.5",
     "zod": "^4.1.0"
   },
   "keywords": [

package/src/analyze.js

@@ -1,6 +1,7 @@
 "use strict";
 
 const fs = require("fs/promises");
+const { createHash } = require("crypto");
 const { constants, realpathSync } = require("fs");
 const path = require("path");
 const { analyzeAsync, compress } = require("sentinel-ir");
@@ -35,7 +36,7 @@ function resolveAllowed(requested, roots, excluder) {
 // path may be swapped for a symlink between the check and the read. The open
 // handle must be a regular file whose inode is the one now found at a real
 // path inside the allowed folders, and at most maxFileBytes are read.
-async function readInside(full, roots, maxFileBytes, label, excluder = NONE) {
+async function readInside(full, roots, maxFileBytes, label, excluder = NONE, onRead = null) {
     let handle;
     try {
         handle = await fs.open(full, OPEN_FLAGS);
@@ -73,6 +74,8 @@ async function readInside(full, roots, maxFileBytes, label, excluder = NONE) {
         }
         if (length > maxFileBytes) throw new TooLargeError(`File too large: ${label} grew past the limit of ${maxFileBytes} bytes`);
         if (length === buffer.length) throw new AccessError(`Access denied: ${label} changed while it was being read`);
+        // The audit log records which bytes were read, never the bytes.
+        if (onRead) onRead(createHash("sha256").update(buffer.subarray(0, length)).digest("hex"));
         return buffer.toString("utf8", 0, length);
     } finally {
         await handle.close();
@@ -94,7 +97,7 @@ async function analyzeCode(code, target, language) {
     return compress(ir);
 }
 
-async function analyzeFile(requested, roots, { maxFileBytes, excluder = NONE }) {
+async function analyzeFile(requested, roots, { maxFileBytes, excluder = NONE, hashes = null }) {
     const { real, display } = resolveAllowed(requested, roots, excluder);
     const stat = await fs.stat(real);
     if (!stat.isFile()) throw new AccessError(`Not a file: ${requested}`);
@@ -104,7 +107,7 @@ async function analyzeFile(requested, roots, { maxFileBytes, excluder = NONE })
     if (stat.size > maxFileBytes) {
         throw new AccessError(`File too large: ${requested} is ${stat.size} bytes, limit is ${maxFileBytes}`);
     }
-    const code = await readInside(real, roots, maxFileBytes, requested, excluder);
+    const code = await readInside(real, roots, maxFileBytes, requested, excluder, hashes && ((h) => hashes.set(display, h)));
     return analyzeCode(code, display);
 }
 
@@ -221,7 +224,7 @@ function fullEntry(rel, ir) {
 async function analyzeDirectory(
     requested,
     roots,
-    { maxFiles, maxFileBytes, recursive = true, timeBudgetMs = Infinity, detail = "summary", excluder = NONE }
+    { maxFiles, maxFileBytes, recursive = true, timeBudgetMs = Infinity, detail = "summary", excluder = NONE, hashes = null }
 ) {
     const started = Date.now();
     const { real, root, display } = resolveAllowed(requested, roots, excluder);
@@ -241,7 +244,9 @@ async function analyzeDirectory(
         // One file that cannot be read or analyzed must not hide the others.
         let ir;
         try {
-            ir = await analyzeCode(await readInside(full, [root], maxFileBytes, rel, excluder), rel);
+            let hash = null;
+            ir = await analyzeCode(await readInside(full, [root], maxFileBytes, rel, excluder, hashes && ((h) => { hash = h; })), rel);
+            if (hash) hashes.set(rel, hash);
         } catch (err) {
             if (err instanceof ExcludedError) {
                 skipped.excluded++;

package/src/auditLog.js

@@ -0,0 +1,230 @@
+"use strict";
+
+const crypto = require("crypto");
+const fs = require("fs");
+const path = require("path");
+const { homeOf } = require("./clients");
+
+// An optional record, for the user, of what the agent asked this server for.
+// One JSON object per line in one file per local day; never any source code.
+// Turned on only by the user (--audit-log on the command line the client
+// starts), never by the agent or by files in the project.
+
+const FILE_RE = /^audit-(\d{4})-(\d{2})-(\d{2})\.jsonl$/;
+const KEEP_DAYS = 30;
+const MAX_DAY_BYTES = 50 * 1024 * 1024;
+// A day stops this far below the limit, so lines that parallel servers append
+// in the same instant still end below MAX_DAY_BYTES (a line is at most ~10 kB).
+const DAY_RESERVE = 1024 * 1024;
+const MAX_TEXT = 300;
+const MAX_LISTED = 20;
+const HASHES_PER_LINE = 40;
+// Characters cmd.exe acts on: an MCP entry on Windows runs through "cmd /c".
+const UNSAFE_DIR = /["&|<>^%!\u0000-\u001f]/;
+const OPEN_FLAGS = fs.constants.O_WRONLY | fs.constants.O_APPEND | fs.constants.O_CREAT | (fs.constants.O_NOFOLLOW || 0);
+
+class AuditLogError extends Error {}
+
+function defaultAuditDir(env = process.env, platform = process.platform) {
+    if (platform === "win32") {
+        const local = env.LOCALAPPDATA || path.join(homeOf(env), "AppData", "Local");
+        return path.join(local, "sentinel-ir-mcp", "audit-log");
+    }
+    if (platform === "darwin") return path.join(homeOf(env), "Library", "Logs", "sentinel-ir-mcp");
+    const state = env.XDG_STATE_HOME || path.join(homeOf(env), ".local", "state");
+    return path.join(state, "sentinel-ir-mcp", "audit-log");
+}
+
+// "--audit-log" (default folder) or "--audit-log=<folder>"; must be absolute
+// because a client starts the server from a folder you do not choose.
+function normalizeAuditDir(raw) {
+    if (typeof raw !== "string" || raw.trim() === "") throw new AuditLogError("--audit-log=<folder> needs a folder");
+    const dir = raw.trim();
+    if (UNSAFE_DIR.test(dir)) throw new AuditLogError(`audit log folder "${raw}" contains a character that is not allowed (" & | < > ^ % !)`);
+    if (!path.isAbsolute(dir)) throw new AuditLogError(`audit log folder "${raw}" must be a full path, e.g. ${process.platform === "win32" ? "C:\\logs\\sentinel" : "/home/me/logs"}`);
+    return path.resolve(dir);
+}
+
+function isInside(child, parent) {
+    const rel = path.relative(parent, child);
+    return rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel));
+}
+
+function realOrResolved(p) {
+    // The folder may not exist yet: resolve its nearest existing parent.
+    let current = path.resolve(p);
+    const rest = [];
+    for (;;) {
+        try { return path.join(fs.realpathSync(current), ...rest.reverse()); } catch { /* go up */ }
+        const parent = path.dirname(current);
+        if (parent === current) return path.resolve(p);
+        rest.push(path.basename(current));
+        current = parent;
+    }
+}
+
+// A log inside the project could be committed or read by the agent.
+function assertOutsideProjects(dir, projects, caseInsensitive = process.platform === "win32" || process.platform === "darwin") {
+    const fold = (p) => (caseInsensitive ? p.toLowerCase() : p);
+    const real = fold(realOrResolved(dir));
+    for (const project of projects) {
+        if (isInside(real, fold(realOrResolved(project)))) {
+            throw new AuditLogError(`the audit log folder ${dir} is inside the project folder ${project}; pick a folder outside it`);
+        }
+    }
+}
+
+function pad(n) { return String(n).padStart(2, "0"); }
+function dayName(date) { return `audit-${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}.jsonl`; }
+
+function cut(value, max = MAX_TEXT) {
+    if (typeof value !== "string") return value;
+    if (value.length <= max) return value;
+    let end = max;
+    const code = value.charCodeAt(end - 1);
+    if (code >= 0xd800 && code <= 0xdbff) end--;
+    return value.slice(0, end) + "…";
+}
+
+function logFiles(dir) {
+    let names;
+    try { names = fs.readdirSync(dir); } catch { return []; }
+    return names.filter((n) => FILE_RE.test(n)).sort();
+}
+
+function pruneOld(dir, now) {
+    const limit = new Date(now);
+    limit.setHours(0, 0, 0, 0);
+    limit.setDate(limit.getDate() - KEEP_DAYS);
+    for (const name of logFiles(dir)) {
+        const [, y, m, d] = FILE_RE.exec(name);
+        if (new Date(Number(y), Number(m) - 1, Number(d)) < limit) {
+            try {
+                if (fs.lstatSync(path.join(dir, name)).isFile()) fs.unlinkSync(path.join(dir, name));
+            } catch { /* another server may have removed it */ }
+        }
+    }
+}
+
+// What a tool call is logged as: what was asked and the outcome, no code.
+function describeCall(tool, args, outcome) {
+    const entry = { tool };
+    if (tool === "analyze_code") {
+        entry.bytes = Buffer.byteLength(typeof args.code === "string" ? args.code : "", "utf8");
+        if (typeof args.target === "string") entry.target = cut(args.target);
+        if (typeof args.language === "string") entry.language = args.language;
+    } else {
+        entry.path = cut(typeof args.path === "string" ? args.path : ".");
+        if (tool === "analyze_directory") {
+            for (const [k, v] of [["max_files", args.max_files], ["recursive", args.recursive], ["detail", args.detail]]) if (v !== undefined) entry[k] = v;
+        }
+    }
+    if (outcome.error) {
+        entry.ok = false;
+        entry.reason = outcome.reason;
+        entry.message = cut(outcome.error);
+        return entry;
+    }
+    entry.ok = true;
+    const r = outcome.result;
+    if (tool === "analyze_directory") {
+        entry.analyzed = r.analyzed;
+        entry.riskCounts = r.riskCounts;
+        entry.incomplete = r.incomplete.length;
+        entry.excluded = r.skipped.excluded;
+        const notRead = r.skipped.tooLarge.length + r.skipped.unreadable.length + r.skipped.hardlinks.length;
+        if (notRead) entry.notRead = notRead;
+        if (r.truncated) entry.truncated = true;
+        if (r.timedOut) entry.timedOut = true;
+        // sha256 of every analyzed file, so the user can check later which
+        // version of each file the agent was shown. splitHashes moves the
+        // full list to lines of its own.
+        const hashes = args.hashes instanceof Map ? args.hashes : new Map();
+        const withHash = (f) => (hashes.has(f.path) ? { sha256: hashes.get(f.path) } : {});
+        const top = r.files.filter((f) => f.risk === "critical" || f.risk === "high").slice(0, MAX_LISTED);
+        if (top.length) entry.top = top.map((f) => ({ path: cut(f.path), risk: f.risk, ...withHash(f) }));
+        const files = r.files.filter((f) => hashes.has(f.path)).map((f) => ({ path: cut(f.path), risk: f.risk, ...withHash(f) }));
+        if (files.length) entry.files = files;
+    } else {
+        entry.risk = r.world && r.world.risk;
+        entry.analysisStatus = r.analysisStatus;
+        entry.language = r.language;
+        if (tool === "analyze_file" && r.mission && typeof r.mission.target === "string") entry.file = cut(r.mission.target);
+        if (tool === "analyze_file" && args.hashes instanceof Map && args.hashes.size) entry.sha256 = [...args.hashes.values()][0];
+    }
+    return entry;
+}
+
+// A folder can have 500 files: their hashes go in follow-up lines of at most
+// HASHES_PER_LINE files (usually under 20 kB each, so DAY_RESERVE still holds and
+// one write stays one line), linked to the call by a random "call" id.
+function splitHashes(entry) {
+    if (!Array.isArray(entry.files)) return [entry];
+    const { files, ...main } = entry;
+    main.call = crypto.randomBytes(6).toString("hex");
+    main.hashed = files.length;
+    const parts = Math.ceil(files.length / HASHES_PER_LINE);
+    const more = [];
+    for (let i = 0; i < parts; i++) {
+        more.push({ event: "hashes", call: main.call, part: i + 1, parts, files: files.slice(i * HASHES_PER_LINE, (i + 1) * HASHES_PER_LINE) });
+    }
+    return [main, ...more];
+}
+
+function createAuditLog({ dir, now = () => Date.now(), onError = (m) => process.stderr.write(`sentinel-ir-mcp: ${m}\n`) } = {}) {
+    if (!dir) return { active: false, record() {}, flush: async () => {} };
+    let queue = Promise.resolve();
+    let prunedFor = null;
+    let fullDay = null;
+    let failed = false;
+
+    async function append(line, file) {
+        await fs.promises.mkdir(dir, { recursive: true, mode: 0o700 });
+        // Once per server and day, so a server running for weeks still cleans up.
+        if (prunedFor !== file) { prunedFor = file; pruneOld(dir, now()); }
+        // Windows has no O_NOFOLLOW, so the checks below refuse a day file that
+        // is a symlink, junction or hard link on every system before any write.
+        const before = await fs.promises.lstat(file, { bigint: true }).catch((e) => {
+            if (e.code === "ENOENT") return null;
+            throw e;
+        });
+        if (before && !before.isFile()) throw new Error(`${file} is not a regular file`);
+        const handle = await fs.promises.open(file, OPEN_FLAGS, 0o600);
+        try {
+            const stat = await handle.stat({ bigint: true });
+            if (!stat.isFile()) throw new Error(`${file} is not a regular file`);
+            if (stat.nlink > 1n) throw new Error(`${file} has a second name (hard link); not writing`);
+            const after = await fs.promises.lstat(file, { bigint: true });
+            const same = (a) => a.isFile() && a.ino === stat.ino && a.dev === stat.dev;
+            if (!same(after) || (before && !same(before))) throw new Error(`${file} was replaced while opening; not writing`);
+            if (stat.size + BigInt(Buffer.byteLength(line)) > BigInt(MAX_DAY_BYTES - DAY_RESERVE)) {
+                if (fullDay !== file) {
+                    fullDay = file;
+                    await handle.write(JSON.stringify({ ts: new Date(now()).toISOString(), event: "full", limitBytes: MAX_DAY_BYTES }) + "\n");
+                }
+                return;
+            }
+            // One write per line: with O_APPEND lines of parallel servers do not interleave.
+            await handle.write(line);
+        } finally {
+            await handle.close();
+        }
+    }
+
+    function record(entry) {
+        const date = new Date(now());
+        const line = JSON.stringify({ ts: date.toISOString(), pid: process.pid, ...entry }) + "\n";
+        const file = path.join(dir, dayName(date));
+        queue = queue.then(() => append(line, file)).then(() => { failed = false; }, (err) => {
+            if (!failed) onError(`cannot write the audit log in ${dir}: ${err.message}`);
+            failed = true;
+        });
+    }
+
+    return { active: true, dir, record, flush: () => queue };
+}
+
+module.exports = {
+    AuditLogError, KEEP_DAYS, MAX_DAY_BYTES, FILE_RE,
+    defaultAuditDir, normalizeAuditDir, assertOutsideProjects, createAuditLog, describeCall, splitHashes, HASHES_PER_LINE, logFiles, dayName, cut
+};

package/src/cli.js

@@ -4,12 +4,13 @@ const readline = require("readline");
 const { runSetup } = require("./setup");
 const { runDoctor } = require("./doctor");
 const { GUIDE } = require("./guide");
+const { runLog } = require("./logView");
 const { CLIENT_NAMES, PACKAGE_SPEC } = require("./clients");
 
-const COMMANDS = Object.freeze(["setup", "doctor", "guide"]);
+const COMMANDS = Object.freeze(["setup", "doctor", "guide", "log"]);
 
 const HELP = {
-    setup: `Usage: sentinel-ir-mcp setup [--client <name>] [--project <folder>] [--exclude <name>]... [--no-exclude] [--global] [--config <file>] [--dry-run] [--yes]
+    setup: `Usage: sentinel-ir-mcp setup [--client <name>] [--project <folder>] [--exclude <name>]... [--no-exclude] [--audit-log[=<folder>]] [--no-audit-log] [--global] [--config <file>] [--dry-run] [--yes]
 
 Adds a "sentinel-ir" server to an AI client's MCP config. Shows the change first,
 backs up the old file and touches only the "sentinel-ir" entry.
@@ -21,6 +22,11 @@ backs up the old file and touches only the "sentinel-ir" entry.
                       path, *.min.js = by mask. Without it, setup asks (Enter = none)
                       and running setup again keeps the current list.
   --no-exclude        remove all exclusions
+  --audit-log         keep a log of what the agent asks for (never your code);
+                      see it with "sentinel-ir-mcp log". Without it, setup asks
+                      (Enter = no) and running setup again keeps the setting.
+  --audit-log=<folder>  the same, in this folder (full path, outside the project)
+  --no-audit-log      stop the log (files already written stay)
   --global            Cursor only: ~/.cursor/mcp.json instead of <project>/.cursor/mcp.json
   --config <file>     write this config file instead of the client's default
   --dry-run           show the change, write nothing
@@ -29,6 +35,14 @@ backs up the old file and touches only the "sentinel-ir" entry.
 
 Checks Node.js, the client config and a real MCP connection to this server.
 Exit code 0 when all checks pass, 1 otherwise.`,
+    log: `Usage: sentinel-ir-mcp log [--all] [--json] [--dir <folder>]
+
+Shows what the agent asked this server for, newest last (the last 50 entries).
+Needs the audit log turned on: sentinel-ir-mcp setup --audit-log
+
+  --all           every entry of the last 30 days
+  --json          the entries as JSON
+  --dir <folder>  a log folder set with --audit-log=<folder>`,
     guide: `Usage: sentinel-ir-mcp guide
 
 Prints short instructions for AI agents (for AGENTS.md or client rules).
@@ -36,12 +50,16 @@ Nothing is written.`
 };
 
 const REPEATABLE = new Set(["--exclude"]);
+// Flags that may carry a value with "=", but never take the next argument.
+const OPTIONAL_VALUE = new Set(["--audit-log"]);
 
 const FLAGS = {
     setup: {
         "--client": "client", "--project": "project", "--config": "config", "--exclude": "exclude",
-        "--no-exclude": true, "--global": true, "--dry-run": true, "--yes": true, "-y": true
+        "--no-exclude": true, "--audit-log": "auditLog", "--no-audit-log": true,
+        "--global": true, "--dry-run": true, "--yes": true, "-y": true
     },
+    log: { "--dir": "dir", "--all": true, "--json": true },
     doctor: { "--client": "client", "--project": "project", "--config": "config", "--global": true, "--json": true },
     guide: {}
 };
@@ -49,7 +67,7 @@ const FLAGS = {
 class UsageError extends Error {}
 
 function camel(flag) {
-    return { "-y": "yes", "--dry-run": "dryRun", "--no-exclude": "noExclude" }[flag] || flag.replace(/^--/, "");
+    return { "-y": "yes", "--dry-run": "dryRun", "--no-exclude": "noExclude", "--no-audit-log": "noAuditLog" }[flag] || flag.replace(/^--/, "");
 }
 
 function parse(command, argv) {
@@ -61,7 +79,10 @@ function parse(command, argv) {
         if (arg === "-h" || arg === "--help") return { help: true };
         if (arg.startsWith("--") && arg.includes("=")) [arg, value] = [arg.slice(0, arg.indexOf("=")), arg.slice(arg.indexOf("=") + 1)];
         if (!Object.prototype.hasOwnProperty.call(spec, arg)) throw new UsageError(`unknown ${arg.startsWith("-") ? "option" : "argument"} ${arg}`);
-        if (spec[arg] === true) {
+        if (OPTIONAL_VALUE.has(arg)) {
+            if (value === "") throw new UsageError(`${arg}= needs a folder`);
+            opts[spec[arg]] = value === undefined ? true : value;
+        } else if (spec[arg] === true) {
             if (value !== undefined) throw new UsageError(`${arg} takes no value`);
             opts[camel(arg)] = true;
         } else {
@@ -108,6 +129,7 @@ async function runCommand(command, argv, io = defaultIo()) {
         return 0;
     }
     if (command === "setup") return runSetup(opts, io);
+    if (command === "log") return runLog(opts, io);
     return runDoctor(opts, io);
 }
 

package/src/clients.js

@@ -60,6 +60,26 @@ function excludeArgs(exclude = []) {
     return exclude.map((p) => `--exclude=${p}`);
 }
 
+// audit: null = off, { dir: null } = the default folder, { dir } = that folder.
+function auditArgs(audit) {
+    if (!audit) return [];
+    return [audit.dir ? `--audit-log=${audit.dir}` : "--audit-log"];
+}
+
+function serverFlags(exclude = [], audit = null) {
+    return [...excludeArgs(exclude), ...auditArgs(audit)];
+}
+
+function entryAuditLog(args) {
+    let audit = null;
+    for (const raw of args) {
+        const a = String(raw);
+        if (a === "--audit-log") audit = { dir: null };
+        else if (a.startsWith("--audit-log=")) audit = { dir: a.slice("--audit-log=".length) };
+    }
+    return audit;
+}
+
 // Exclusions in an entry's arguments, in both spellings the server accepts.
 function entryExcludes(args) {
     const out = [];
@@ -71,14 +91,14 @@ function entryExcludes(args) {
     return out;
 }
 
-function npxEntry(folder, exclude = []) {
-    return { command: "npx", args: ["-y", PACKAGE_SPEC, ...excludeArgs(exclude), folder] };
+function npxEntry(folder, exclude = [], audit = null) {
+    return { command: "npx", args: ["-y", PACKAGE_SPEC, ...serverFlags(exclude, audit), folder] };
 }
 
 // On Windows npx is npx.cmd, which a client cannot start without a shell
 // (measured: spawn("npx") fails with ENOENT), so the entry goes through cmd /c.
-function serverEntry(folder, platform = process.platform, exclude = []) {
-    const { command, args } = npxEntry(folder, exclude);
+function serverEntry(folder, platform = process.platform, exclude = [], audit = null) {
+    const { command, args } = npxEntry(folder, exclude, audit);
     return platform === "win32" ? { command: "cmd", args: ["/c", command, ...args] } : { command, args };
 }
 
@@ -100,8 +120,8 @@ function windowsArgQuote(value) {
     return `"${value.replace(/(\\*)"/g, '$1$1\\"').replace(/(\\*)$/, "$1$1")}"`;
 }
 
-function vscodeConfig(project, exclude = []) {
-    return { name: SERVER_NAME, type: "stdio", ...npxEntry(project, exclude) };
+function vscodeConfig(project, exclude = [], audit = null) {
+    return { name: SERVER_NAME, type: "stdio", ...npxEntry(project, exclude, audit) };
 }
 
 // code.cmd/claude.cmd re-read their arguments through cmd.exe, which acts on
@@ -113,22 +133,23 @@ function cmdSafeJson(value) {
 
 // Windows forms were checked in CI against a .cmd shim (like code.cmd and
 // claude.cmd) from PowerShell 5.1, PowerShell 7 and cmd.exe.
-// Exclusions never contain " & | < > ^ % ! (normalizePattern refuses them).
-function installCommand(client, project, platform = process.platform, shell = "powershell", exclude = []) {
-    const json = JSON.stringify(vscodeConfig(project, exclude));
+// Exclusions and audit log folders never contain " & | < > ^ % ! (both are
+// checked before they get here).
+function installCommand(client, project, platform = process.platform, shell = "powershell", exclude = [], audit = null) {
+    const json = JSON.stringify(vscodeConfig(project, exclude, audit));
     const win = platform === "win32";
     if (client === "vscode") {
         if (!win) return `code --add-mcp ${shellQuote(json)}`;
-        return `code ${shell === "cmd" ? "" : "--% "}--add-mcp ${windowsArgQuote(cmdSafeJson(vscodeConfig(project, exclude)))}`;
+        return `code ${shell === "cmd" ? "" : "--% "}--add-mcp ${windowsArgQuote(cmdSafeJson(vscodeConfig(project, exclude, audit)))}`;
     }
     if (client === "claude-code") {
-        const ex = excludeArgs(exclude);
+        const ex = serverFlags(exclude, audit);
         if (win && shell !== "cmd") {
             // PowerShell prefers npm's claude.ps1 shim: a script gets `--` only when quoted, and --% does not apply to it.
             return `claude mcp add --transport stdio ${SERVER_NAME} '--' cmd /c npx -y ${PACKAGE_SPEC} ${ex.map((a) => powershellQuote(a) + " ").join("")}${powershellQuote(project)}`;
         }
         if (win && project.includes("%")) {
-            const config = { type: "stdio", ...serverEntry(project, "win32", exclude) };
+            const config = { type: "stdio", ...serverEntry(project, "win32", exclude, audit) };
             return `claude mcp add-json ${SERVER_NAME} ${windowsArgQuote(cmdSafeJson(config))}`;
         }
         const quote = win ? (a) => `"${a}"` : shellQuote;
@@ -149,5 +170,5 @@ function installLinks() {
 
 module.exports = {
     SERVER_NAME, PACKAGE_SPEC, WORKSPACE_VAR, CLIENTS, CLIENT_NAMES, FILE_CLIENTS,
-    homeOf, npxEntry, serverEntry, excludeArgs, entryExcludes, isWindowsNpxWrapper, shellQuote, powershellQuote, installCommand, installLinks
+    homeOf, npxEntry, serverEntry, excludeArgs, entryExcludes, serverFlags, entryAuditLog, isWindowsNpxWrapper, shellQuote, powershellQuote, installCommand, installLinks
 };

package/src/doctor.js

@@ -5,7 +5,8 @@ const path = require("path");
 const { Client } = require("@modelcontextprotocol/sdk/client/index.js");
 const { StdioClientTransport } = require("@modelcontextprotocol/sdk/client/stdio.js");
 const { version } = require("../package.json");
-const { SERVER_NAME, PACKAGE_SPEC, WORKSPACE_VAR, CLIENTS, FILE_CLIENTS, isWindowsNpxWrapper, entryExcludes, excludeArgs } = require("./clients");
+const { SERVER_NAME, PACKAGE_SPEC, WORKSPACE_VAR, CLIENTS, FILE_CLIENTS, isWindowsNpxWrapper, entryExcludes, entryAuditLog, serverFlags } = require("./clients");
+const { AuditLogError, defaultAuditDir, normalizeAuditDir, assertOutsideProjects, logFiles, dayName, createAuditLog } = require("./auditLog");
 const { readConfig } = require("./setup");
 const { createExcluder, ExcludeError } = require("./exclude");
 const { SKIP_DIRS } = require("./analyze");
@@ -49,7 +50,7 @@ function checkExcludes(client, label, args, file, add) {
     }
 }
 
-function checkConfig(client, file, explicit, project, add, platform) {
+function checkConfig(client, file, explicit, project, add, platform, env) {
     const label = CLIENTS[client].label;
     if (!file) {
         if (explicit) add("fail", `${client}.config`, `${label}: config location unknown on this system`, "Pass the config path with --config <file>.");
@@ -102,7 +103,39 @@ function checkConfig(client, file, explicit, project, add, platform) {
     if (folders.length === 0) add("warn", `${client}.folder`, `${label}: no folder given; the file tools rely on the client's MCP roots`);
     const exclude = checkExcludes(client, label, args, file, add);
     if (exclude === null) return null;
-    return { folders: resolved, exclude };
+    let audit = entryAuditLog(args);
+    if (audit) {
+        try {
+            const dir = audit.dir ? normalizeAuditDir(audit.dir) : defaultAuditDir(env, platform);
+            assertOutsideProjects(dir, resolved);
+            audit = { dir: audit.dir ? dir : null, path: dir };
+        } catch (e) {
+            if (!(e instanceof AuditLogError)) throw e;
+            add("fail", `${client}.audit`, `${label}: ${e.message}; the server will not start`,
+                `Run: npx -y ${PACKAGE_SPEC} setup --client ${client} --audit-log  (or --no-audit-log)`);
+            return { folders: resolved, exclude, audit: null, auditBroken: true };
+        }
+    }
+    return { folders: resolved, exclude, audit };
+}
+
+function formatBytes(n) {
+    if (n < 1024) return `${n} B`;
+    if (n < 1024 * 1024) return `${(n / 1024).toFixed(1)} kB`;
+    return `${(n / 1024 / 1024).toFixed(1)} MB`;
+}
+
+function describeAuditFolder(dir) {
+    const files = logFiles(dir);
+    let bytes = 0;
+    for (const f of files) {
+        try { bytes += fs.statSync(path.join(dir, f)).size; } catch { /* removed meanwhile */ }
+    }
+    return files.length ? `${files.length} day(s), ${formatBytes(bytes)}` : "empty so far";
+}
+
+function fileSize(file) {
+    try { return fs.statSync(file).size; } catch { return -1; }
 }
 
 function withTimeout(promise, ms, what) {
@@ -113,8 +146,13 @@ function withTimeout(promise, ms, what) {
     ]).finally(() => clearTimeout(timer));
 }
 
-async function checkHandshake(folders, exclude, add, timeoutMs) {
-    const transport = new StdioClientTransport({ command: process.execPath, args: [BIN, ...excludeArgs(exclude), ...folders], stderr: "pipe" });
+async function checkHandshake(folders, exclude, audit, add, timeoutMs) {
+    // Without the audit log, so the check does not fill it with its own calls;
+    // the log is proved below with one "check" line from the same writer.
+    const flags = serverFlags(exclude, null);
+    const transport = new StdioClientTransport({ command: process.execPath, args: [BIN, ...flags, ...folders], stderr: "pipe" });
+    const today = audit ? path.join(audit.path, dayName(new Date())) : null;
+    const before = today ? fileSize(today) : -1;
     const client = new Client({ name: "sentinel-ir-mcp-doctor", version });
     try {
         await withTimeout(client.connect(transport), timeoutMs, "MCP handshake");
@@ -133,6 +171,13 @@ async function checkHandshake(folders, exclude, add, timeoutMs) {
     } finally {
         await client.close().catch(() => {});
     }
+    if (!audit) return;
+    const log = createAuditLog({ dir: audit.path, onError: () => {} });
+    log.record({ event: "check", version });
+    await log.flush();
+    if (fileSize(today) > before) add("ok", "audit.write", `Audit log: can be written (doctor added one "check" line to ${today})`);
+    else add("fail", "audit.write", `Audit log: nothing could be written to ${audit.path}`,
+        "Check that the folder exists or can be created and that you may write to it (disk full?). The tools still work without the log.");
 }
 
 const MARK = { ok: "[ok]  ", warn: "[warn]", fail: "[FAIL]", skip: "[skip]" };
@@ -155,6 +200,8 @@ async function runDoctor(opts, io) {
     const names = opts.client ? (CLIENTS[opts.client] && CLIENTS[opts.client].kind === "file" ? [opts.client] : []) : FILE_CLIENTS;
     let folders = null;
     let exclude = [];
+    let audit = null;
+    let auditBroken = false;
     for (const client of names) {
         const ctx = { project, global: Boolean(opts.global), env: io.env, platform: io.platform };
         let file = opts.config ? path.resolve(io.cwd, opts.config) : CLIENTS[client].configPath(ctx);
@@ -164,8 +211,8 @@ async function runDoctor(opts, io) {
                 `Current ${CLIENTS[client].label} reads ${file || "a new location"}. Run: npx -y ${PACKAGE_SPEC} setup --client ${client}`);
             file = legacy;
         }
-        const found = checkConfig(client, file, Boolean(opts.client), project, add, io.platform);
-        if (found && folders === null) ({ folders, exclude } = found);
+        const found = checkConfig(client, file, Boolean(opts.client), project, add, io.platform, io.env);
+        if (found && folders === null) ({ folders, exclude, audit, auditBroken = false } = found);
     }
     if (folders === null) {
         let isDir = false;
@@ -177,7 +224,9 @@ async function runDoctor(opts, io) {
         }
     }
     for (const line of describeExcluded(exclude, folders, SKIP_DIRS)) add("ok", "exclude", line);
-    await checkHandshake(folders, exclude, add, opts.timeoutMs || 30000);
+    if (audit) add("ok", "audit", `Audit log: on, in ${audit.path} (${describeAuditFolder(audit.path)}); see it: npx -y ${PACKAGE_SPEC} log${audit.dir ? ` --dir "${audit.dir}"` : ""}`);
+    else if (!auditBroken) add("ok", "audit", `Audit log: off (turn it on: npx -y ${PACKAGE_SPEC} setup --audit-log)`);
+    await checkHandshake(folders, exclude, audit, add, opts.timeoutMs || 30000);
 
     const failed = checks.some((c) => c.status === "fail");
     if (opts.json) {

package/src/logView.js

@@ -0,0 +1,158 @@
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const { PACKAGE_SPEC } = require("./clients");
+const { AuditLogError, defaultAuditDir, normalizeAuditDir, logFiles, KEEP_DAYS } = require("./auditLog");
+
+const RECENT = 50;
+// Control, bidi and line-separator characters could rewrite the terminal or
+// fake a line: shown as \u{..} instead.
+const UNSAFE = /[\u0000-\u001f\u007f-\u009f\u200b-\u200f\u2028\u2029\u202a-\u202e\u2066-\u2069\ufeff]/g;
+
+function safe(value) {
+    return String(value).replace(UNSAFE, (c) => `\\u{${c.codePointAt(0).toString(16)}}`);
+}
+
+const REASONS = {
+    excluded: "excluded by your settings",
+    outside: "outside the project folder",
+    "not-found": "does not exist",
+    "too-large": "file too large",
+    "no-folders": "no project folder is set"
+};
+
+const TOOL_WORDS = { analyze_file: "file", analyze_directory: "folder", analyze_code: "pasted code" };
+
+function pad(n) { return String(n).padStart(2, "0"); }
+
+function localTime(ts) {
+    const d = new Date(ts);
+    if (Number.isNaN(d.getTime())) return "????-??-?? ??:??:??";
+    return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())} ${pad(d.getHours())}:${pad(d.getMinutes())}:${pad(d.getSeconds())}`;
+}
+
+function riskCounts(counts) {
+    if (!counts || typeof counts !== "object") return "";
+    const parts = ["critical", "high", "medium", "low"].filter((k) => Number(counts[k]) > 0).map((k) => `${Number(counts[k])} ${k}`);
+    return parts.length ? ` (${parts.join(", ")})` : "";
+}
+
+const SHA256 = /^[0-9a-f]{64}$/;
+// The first 12 hex digits are enough to compare by eye; --json has all 64.
+function shortHash(h) { return typeof h === "string" && SHA256.test(h) ? ` sha256 ${h.slice(0, 12)}` : ""; }
+
+function describe(e) {
+    if (e.event === "start") {
+        const folders = Array.isArray(e.folders) && e.folders.length ? ` for ${e.folders.map(safe).join(", ")}` : "";
+        return [`server started (sentinel-ir-mcp ${safe(e.version)})${folders}`];
+    }
+    if (e.event === "check") return [`doctor checked that the log can be written`];
+    if (e.event === "full") return [`the log for this day reached its size limit; nothing more is written today`];
+    if (typeof e.event === "string") return [`${safe(e.event).slice(0, 40)} (see log --json)`];
+    const what = TOOL_WORDS[e.tool] ? TOOL_WORDS[e.tool] : safe(e.tool);
+    const target = e.tool === "analyze_code" ? `${what} (${Number(e.bytes) || 0} bytes${e.language ? `, ${safe(e.language)}` : ""})` : `${what} ${safe(e.path)}`;
+    if (e.ok === false) {
+        const reason = REASONS[e.reason] || safe(e.message || e.reason || "failed");
+        return [`REFUSED ${target}: ${reason}`];
+    }
+    if (e.tool === "analyze_directory") {
+        const extra = [];
+        if (Number(e.excluded) > 0) extra.push(`${Number(e.excluded)} excluded`);
+        if (Number(e.notRead) > 0) extra.push(`${Number(e.notRead)} not read (too large or unreadable)`);
+        if (e.truncated) extra.push("stopped at the file limit");
+        if (e.timedOut) extra.push("stopped at the time limit");
+        if (Number(e.hashed) > 0) extra.push(`sha256 of ${Number(e.hashed)} file(s) in log --json`);
+        const lines = [`${target}: ${Number(e.analyzed) || 0} file(s)${riskCounts(e.riskCounts)}${extra.length ? `, ${extra.join(", ")}` : ""}`];
+        if (Array.isArray(e.top)) for (const f of e.top) if (f) lines.push(`    ${safe(f.risk).padEnd(8)} ${safe(f.path)}${shortHash(f.sha256)}`);
+        return lines;
+    }
+    const incomplete = e.analysisStatus && e.analysisStatus !== "complete" ? " (incomplete: broken code)" : "";
+    return [`${target}: ${safe(e.risk)}${incomplete}${shortHash(e.sha256)}`];
+}
+
+// Hash lines of a folder call are data for --json, not entries to read.
+function parseFile(file, { hashLines = true } = {}) {
+    const entries = [];
+    let damaged = 0;
+    let text;
+    try {
+        if (!fs.lstatSync(file).isFile()) return { entries, damaged };
+        text = fs.readFileSync(file, "utf8");
+    } catch { return { entries, damaged }; }
+    for (const line of text.split("\n")) {
+        if (line === "") continue;
+        try {
+            const e = JSON.parse(line);
+            if (e && typeof e === "object" && !Array.isArray(e) && (typeof e.tool === "string" || typeof e.event === "string")) {
+                if (hashLines || e.event !== "hashes") entries.push(e);
+            }
+            else damaged++;
+        } catch { damaged++; }
+    }
+    return { entries, damaged };
+}
+
+function printEntry(io, e) {
+    const client = e.client ? ` [${safe(e.client).slice(0, 40)}]` : "";
+    const [first, ...rest] = describe(e);
+    io.stdout.write(`${localTime(e.ts)}${client} ${first}\n`);
+    for (const line of rest) io.stdout.write(line + "\n");
+}
+
+// Files are read one at a time (a day can hold 50 MB), newest first for the
+// default view, which stops once it has enough entries.
+function runLog(opts, io) {
+    let dir;
+    try {
+        dir = opts.dir ? normalizeAuditDir(path.resolve(io.cwd, opts.dir)) : defaultAuditDir(io.env, io.platform);
+    } catch (e) {
+        if (!(e instanceof AuditLogError)) throw e;
+        io.stderr.write(`sentinel-ir-mcp log: ${e.message}\n`);
+        return 2;
+    }
+    const files = logFiles(dir).map((n) => path.join(dir, n));
+    let damaged = 0;
+    let count = 0;
+    let more = false;
+    let first = true;
+    const emit = opts.json
+        ? (e) => { io.stdout.write(`${first ? "" : ","}\n    ${JSON.stringify(e)}`); first = false; }
+        : (e) => printEntry(io, e);
+    if (opts.json) io.stdout.write(`{\n  "folder": ${JSON.stringify(dir)},\n  "entries": [`);
+    if (opts.all) {
+        for (const file of files) {
+            const r = parseFile(file, { hashLines: Boolean(opts.json) });
+            damaged += r.damaged;
+            for (const e of r.entries) emit(e);
+            count += r.entries.length;
+        }
+    } else {
+        let recent = [];
+        for (let i = files.length - 1; i >= 0 && recent.length < RECENT; i--) {
+            const r = parseFile(files[i], { hashLines: Boolean(opts.json) });
+            damaged += r.damaged;
+            recent = r.entries.concat(recent);
+            if (recent.length >= RECENT && i > 0) more = true;
+        }
+        if (recent.length > RECENT) { more = true; recent = recent.slice(-RECENT); }
+        for (const e of recent) emit(e);
+        count = recent.length;
+    }
+    if (opts.json) {
+        io.stdout.write(`${first ? "" : "\n  "}],\n  "damaged": ${damaged}\n}\n`);
+        return 0;
+    }
+    if (count === 0) {
+        io.stdout.write(`No audit log in ${dir}.\n` +
+            `Turn it on with: npx -y ${PACKAGE_SPEC} setup --audit-log\n` +
+            `Then restart the AI app; entries appear when the agent uses the tools.\n`);
+    } else {
+        const summary = more ? `Showing the last ${count} entries; --all shows everything.` : `${count} entries.`;
+        io.stdout.write(`\n${summary} Log folder: ${dir} (kept ${KEEP_DAYS} days)\n`);
+    }
+    if (damaged) io.stdout.write(`${damaged} damaged line(s) skipped.\n`);
+    return 0;
+}
+
+module.exports = { runLog, safe, describe };

package/src/server.js

@@ -6,6 +6,7 @@ const { version } = require("../package.json");
 const { AccessError, canonicalRoots, rootsFromUris } = require("./paths");
 const { analyzeCode, analyzeFile, analyzeDirectory } = require("./analyze");
 const { createExcluder } = require("./exclude");
+const { createAuditLog, describeCall, splitHashes } = require("./auditLog");
 
 const DEFAULT_LIMITS = Object.freeze({
     maxFileBytes: 1024 * 1024,
@@ -61,12 +62,27 @@ function fail(message) {
     return { content: [{ type: "text", text: message }], isError: true };
 }
 
-async function guarded(fn) {
+function refusalReason(err) {
+    if (!(err instanceof AccessError)) return "error";
+    const m = err.message;
+    if (m.startsWith("Excluded by the user")) return "excluded";
+    if (m.startsWith("File too large")) return "too-large";
+    if (m.includes("outside the allowed folders")) return "outside";
+    if (m.startsWith("No allowed folders")) return "no-folders";
+    if (m.startsWith("Not found")) return "not-found";
+    return "refused";
+}
+
+async function guarded(fn, audit) {
+    const started = Date.now();
     try {
-        return ok(await fn());
+        const result = await fn();
+        audit({ result }, Date.now() - started);
+        return ok(result);
     } catch (err) {
-        if (err instanceof AccessError) return fail(err.message);
-        return fail(`Analysis failed: ${err && err.message ? err.message : String(err)}`);
+        const message = err instanceof AccessError ? err.message : `Analysis failed: ${err && err.message ? err.message : String(err)}`;
+        audit({ error: message, reason: refusalReason(err) }, Date.now() - started);
+        return fail(message);
     }
 }
 
@@ -83,8 +99,23 @@ function createServer(options = {}) {
         timeBudgetMs: Math.min(options.timeBudgetMs ?? DEFAULT_LIMITS.timeBudgetMs, DEFAULT_LIMITS.hardMaxTimeBudgetMs)
     };
     const fixedRoots = canonicalRoots(options.roots || []);
+    const auditLog = options.auditLog || createAuditLog({ dir: options.auditDir });
 
     const server = new McpServer({ name: "sentinel-ir-mcp", version }, { instructions: INSTRUCTIONS + excludeNote });
+    if (auditLog.active) auditLog.record({ event: "start", version, folders: fixedRoots, exclusions: excluder.patterns.length });
+
+    function auditor(tool, args) {
+        if (!auditLog.active) return () => {};
+        return (outcome, ms) => {
+            try {
+                const info = server.server.getClientVersion();
+                const client = info && typeof info.name === "string" ? info.name.slice(0, 100) : undefined;
+                const [main, ...hashLines] = splitHashes({ client, ...describeCall(tool, args, outcome), ms });
+                auditLog.record(main);
+                for (const line of hashLines) auditLog.record(line);
+            } catch { /* logging must never break a tool call */ }
+        };
+    }
 
     // Folders given on the command line win. Otherwise ask the client for its
     // MCP roots on every call (they can change while the session runs).
@@ -112,7 +143,7 @@ function createServer(options = {}) {
             language: z.enum(["javascript", "typescript", "tsx", "python"]).optional().describe("Overrides the language picked from target (default javascript)")
         },
         annotations: { title: "Analyze JavaScript, TypeScript or Python source", ...READ_ONLY }
-    }, ({ code, target, language }) => guarded(() => analyzeCode(code, target, language)));
+    }, ({ code, target, language }) => guarded(() => analyzeCode(code, target, language), auditor("analyze_code", { code, target, language })));
 
     server.registerTool("analyze_file", {
         title: "Analyze a JavaScript, TypeScript or Python file",
@@ -124,7 +155,10 @@ function createServer(options = {}) {
             path: z.string().min(1).describe("File path, absolute or relative to the first allowed folder")
         },
         annotations: { title: "Analyze a JavaScript, TypeScript or Python file", ...READ_ONLY }
-    }, async ({ path }) => guarded(async () => analyzeFile(path, await allowedRoots(), { ...limits, excluder })));
+    }, async ({ path }) => {
+        const hashes = auditLog.active ? new Map() : null;
+        return guarded(async () => analyzeFile(path, await allowedRoots(), { ...limits, excluder, hashes }), auditor("analyze_file", { path, hashes }));
+    });
 
     server.registerTool("analyze_directory", {
         title: "Analyze a folder of JavaScript, TypeScript and Python files",
@@ -153,16 +187,20 @@ function createServer(options = {}) {
                 .describe("\"summary\" (default): short entries; \"full\": all facts per file, much larger")
         },
         annotations: { title: "Analyze a folder of JavaScript, TypeScript and Python files", ...READ_ONLY }
-    }, async ({ path, max_files, recursive, detail }) => guarded(async () =>
-        analyzeDirectory(path ?? ".", await allowedRoots(), {
+    }, async ({ path, max_files, recursive, detail }) => {
+        const hashes = auditLog.active ? new Map() : null;
+        return guarded(async () => analyzeDirectory(path ?? ".", await allowedRoots(), {
             maxFiles: max_files ?? limits.maxFiles,
             maxFileBytes: limits.maxFileBytes,
             timeBudgetMs: limits.timeBudgetMs,
             recursive: recursive ?? true,
             detail: detail ?? "summary",
-            excluder
-        })));
+            excluder,
+            hashes
+        }), auditor("analyze_directory", { path, max_files, recursive, detail, hashes }));
+    });
 
+    server.auditLog = auditLog;
     return server;
 }
 

package/src/setup.js

@@ -3,7 +3,8 @@
 const fs = require("fs");
 const path = require("path");
 const { isDeepStrictEqual } = require("util");
-const { SERVER_NAME, PACKAGE_SPEC, CLIENTS, homeOf, serverEntry, installCommand, shellQuote, powershellQuote, entryExcludes } = require("./clients");
+const { SERVER_NAME, PACKAGE_SPEC, CLIENTS, homeOf, serverEntry, installCommand, shellQuote, powershellQuote, entryExcludes, entryAuditLog } = require("./clients");
+const { AuditLogError, defaultAuditDir, normalizeAuditDir, assertOutsideProjects } = require("./auditLog");
 const { createExcluder, ExcludeError } = require("./exclude");
 const { describeExcluded } = require("./excludeReport");
 const { SKIP_DIRS } = require("./analyze");
@@ -138,6 +139,48 @@ async function chooseExcludes(opts, io, previous) {
     return toPatterns(answer.split(",").map((s) => s.trim()).filter(Boolean));
 }
 
+// --no-audit-log turns it off, --audit-log[=<folder>] on, otherwise the current
+// setting is kept; an interactive run asks, with Enter keeping it.
+async function chooseAuditLog(opts, io, previous, project) {
+    if (opts.noAuditLog && opts.auditLog) throw new SetupError("Use either --audit-log or --no-audit-log, not both.");
+    let audit;
+    if (opts.noAuditLog) audit = null;
+    else if (opts.auditLog === true) audit = { dir: null };
+    else if (typeof opts.auditLog === "string") audit = { dir: opts.auditLog };
+    else {
+        const current = previous && Array.isArray(previous.args) ? entryAuditLog(previous.args) : null;
+        audit = current;
+        if (!(opts.yes || opts.dryRun || !io.isTTY || !io.prompt)) {
+            const question = current
+                ? "Keep a log of what the agent asks for (file names and results, never your code)? (now: on; Enter = keep, n = off) "
+                : "Keep a log of what the agent asks for (file names and results, never your code)? [y/N] ";
+            const answer = (await io.prompt(question)).trim().toLowerCase();
+            if (answer === "y" || answer === "yes") audit = current || { dir: null };
+            else if (answer === "n" || answer === "no") audit = null;
+            else if (answer !== "") throw new SetupError(`Answer y or n, not "${answer}". Nothing was changed.`);
+        }
+    }
+    if (!audit) return null;
+    try {
+        const dir = audit.dir ? normalizeAuditDir(audit.dir) : null;
+        assertOutsideProjects(dir || defaultAuditDir(io.env, io.platform), [project], io.platform === "win32" || io.platform === "darwin");
+        return { dir };
+    } catch (e) {
+        if (e instanceof AuditLogError) throw new SetupError(`${e.message}. Nothing was changed.`);
+        throw e;
+    }
+}
+
+function describeAudit(audit, io) {
+    if (!audit) return `Audit log: off (turn it on with: npx -y ${PACKAGE_SPEC} setup --audit-log)
+`;
+    const dir = audit.dir || defaultAuditDir(io.env, io.platform);
+    return `Audit log: on, in ${dir} (only what the agent asked for and the results, never your code)
+` +
+        `  see it: npx -y ${PACKAGE_SPEC} log${audit.dir ? ` --dir ${hintArg(audit.dir, io.platform)}` : ""}
+`;
+}
+
 function describePlan(client, plan, project) {
     const lines = [
         `Client:  ${CLIENTS[client].label}`,
@@ -186,15 +229,17 @@ async function runSetup(opts, io) {
 
         if (spec.kind === "command") {
             const exclude = await chooseExcludes(opts, io, undefined);
+            const audit = await chooseAuditLog(opts, io, undefined, project);
             if (opts.config) throw new SetupError(`--config does not apply to ${spec.label}; it installs servers with its own command.`);
             if (io.platform === "win32") {
-                out(`${spec.label} adds MCP servers with its own command. Nothing was written. Run in PowerShell:\n\n  ${installCommand(client, project, "win32", "powershell", exclude)}\n\n` +
-                    `or in Command Prompt (cmd.exe):\n\n  ${installCommand(client, project, "win32", "cmd", exclude)}\n\n`);
+                out(`${spec.label} adds MCP servers with its own command. Nothing was written. Run in PowerShell:\n\n  ${installCommand(client, project, "win32", "powershell", exclude, audit)}\n\n` +
+                    `or in Command Prompt (cmd.exe):\n\n  ${installCommand(client, project, "win32", "cmd", exclude, audit)}\n\n`);
             } else {
-                out(`${spec.label} adds MCP servers with its own command. Nothing was written. Run:\n\n  ${installCommand(client, project, io.platform, undefined, exclude)}\n\n`);
+                out(`${spec.label} adds MCP servers with its own command. Nothing was written. Run:\n\n  ${installCommand(client, project, io.platform, undefined, exclude, audit)}\n\n`);
             }
             out(`Access: ${project} (only this folder, read-only)\n`);
             out(describeExcluded(exclude, [project], SKIP_DIRS).join("\n") + "\n");
+            out(describeAudit(audit, io));
             out(`Then check the connection${io.platform === "win32" ? " (PowerShell)" : ""}: npx -y ${PACKAGE_SPEC} doctor --client ${client} --project ${hintArg(project, io.platform)}\n`);
             out(percentNote(project));
             return 0;
@@ -209,9 +254,11 @@ async function runSetup(opts, io) {
         const seed = !opts.config && spec.legacyConfigPath ? spec.legacyConfigPath(ctx) : null;
         const { previous } = planFileChange(file, serverEntry(folder, io.platform), seed);
         const exclude = await chooseExcludes(opts, io, previous);
-        const plan = planFileChange(file, serverEntry(folder, io.platform, exclude), seed);
+        const audit = await chooseAuditLog(opts, io, previous, project);
+        const plan = planFileChange(file, serverEntry(folder, io.platform, exclude, audit), seed);
         out(describePlan(client, plan, project));
         out(describeExcluded(exclude, [project], SKIP_DIRS).join("\n") + "\n");
+        out(describeAudit(audit, io));
         out(percentNote(project));
 
         if (plan.action === "unchanged") {