mason-context 0.16.0 → 0.16.2

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 0.16.2 — 2026-09-09
+
+- Guard generated hooks when Mason is absent, and keep a checkout without local host setup quiet. Preserve active failure diagnostics and strict MCP startup; setup/status/teardown recognize the generated guard variants without project wrapper scripts.
+- Observe known read-only tools without rescanning audit inputs or advancing verification. Keep before/after capture for shell and unknown tools. Add a reproducible full-CLI hook benchmark and publish its measured scope and limits.
+- Document hook inputs, retained data, local versus optional networked features, MCP installation, and company mirrors. Require an explicit version with a custom release mirror to avoid public version discovery.
+- Exercise core CLI/MCP and hook paths with denied network operations, raw-input retention markers, inactive/invalid setup, and changed evidence before potentially mutating tools. On macOS, apply OS network denial to the tested process tree too.
+
+## 0.16.1 — 2026-09-08
+
+- Resolve references using literal import paths and declared Kotlin/Java package symbols. Separate explicit path mentions and uncertain name candidates; suppress config/document-name collisions and keep weak candidates out of compact task context with an omission count.
+- Include investigations in project-context guidance and route reusable project lessons into sourced proposals, preserving uncertainty and unknown attribution.
+- Add a two-session knowledge evaluation with ordinary prompts, independent digest-bound review, fresh-checkout reuse, negative controls, and current-guidance/file-notes comparisons. Mechanism validation and live agent outcomes are reported separately.
+
 ## 0.16.0 — 2026-09-08
 
 - Add `mason teardown` to disconnect all project hosts, or one with `--host codex|claude`. Support `--dir`, `--dry-run` and `--json`; retain decisions, configuration, maps, repair evidence and ignore rules. Global uninstall remains separate.

package/README.md

@@ -12,6 +12,8 @@
 
 Works through MCP, with automatic documentation checks for **Codex** and **Claude Code**. No concept map required.
 
+Core checks run locally with no model calls or telemetry. Results become context for your existing assistant. [Data, network access, and team installation](docs/data-and-network.md) covers storage, optional networked features, and internal mirrors.
+
 ## Get started
 
 Install on macOS or Linux:
@@ -74,6 +76,7 @@ Earlier read-only decision-retrieval evaluations scored **9.0/10 with Mason vs 7
 ## Documentation
 
 - [Setup, hooks, and upgrades](docs/setup.md)
+- [Data and network behavior](docs/data-and-network.md) · [Hook performance](docs/hook-performance.md)
 - [Audits, repair verification, and CI evidence](docs/checks.md)
 - [Decisions, tools, and optional architecture maps](docs/reference.md)
 - [Roadmap](ROADMAP.md) · [Changelog](CHANGELOG.md) · [MIT license](LICENSE)

package/dist/mason-auto.js

@@ -2521,7 +2521,7 @@ var init_evidence = __esm({
     init_dead_command();
     init_storage();
     exec7 = promisify8(execFile8);
-    engineVersion = true ? "0.16.0" : "development";
+    engineVersion = true ? "0.16.2" : "development";
     hash = (value) => createHash3("sha256").update(JSON.stringify(value)).digest("hex");
     content = readAuditInput;
     internal = (file) => file === ".mason" || file === ".mason/reports" || file.startsWith(".mason/reports/");
@@ -2628,6 +2628,25 @@ var init_store = __esm({
 
 // src/automation/runtime.ts
 import { randomUUID as randomUUID4 } from "crypto";
+async function observeReadOnlyTool(dir, event) {
+  const ws = await workspace(dir);
+  await withLock(ws.root, ws.directory, async () => {
+    const statePath = ws.directory + "/state.json";
+    const raw = await readStoreJson(ws.root, statePath);
+    if (raw === null) return;
+    const state = parseState(raw);
+    if (state.root !== ws.root || state.gitDir !== ws.gitDir || state.branch !== ws.branch) {
+      throw new Error("Automation state belongs to another branch or worktree; original evidence was retained.");
+    }
+    const session = event.host && event.sessionId ? state.sessions[hash([event.host, event.sessionId])] : null;
+    if (!session) return;
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    session.lastUsed = now;
+    session.events[event.event] = { at: now, count: (session.events[event.event]?.count ?? 0) + 1 };
+    await writeStoreJson(ws.root, statePath, state);
+  });
+  return { root: ws.root, directory: ws.directory };
+}
 function summarize(report) {
   const open = report.findings.filter((f) => f.status !== "resolved");
   return [
@@ -2896,6 +2915,7 @@ var init_model = __esm({
 // src/setup/launcher.ts
 import { execFile as execFile9 } from "child_process";
 import { promisify as promisify9 } from "util";
+import fs13 from "fs/promises";
 function globalCommand(args, platform = process.platform) {
   return platform === "win32" ? { command: "cmd.exe", args: ["/d", "/s", "/c", "mason", ...args] } : { command: "mason", args };
 }
@@ -2920,7 +2940,7 @@ var init_launcher = __esm({
     "use strict";
     init_evidence();
     init_model();
-    executingVersion = () => true ? "0.16.0" : "development";
+    executingVersion = () => true ? "0.16.2" : "development";
     mcpCommand = (host) => globalCommand(["--setup-host", host, "mcp"]);
     hookCommand = (host) => `mason --setup-host ${host} auto`;
   }
@@ -2933,7 +2953,7 @@ __export(observations_exports, {
   observeActivation: () => observeActivation,
   readObservation: () => readObservation
 });
-import fs13 from "fs/promises";
+import fs14 from "fs/promises";
 import { z as z8 } from "zod";
 function observationPath(directory, host, revision, version = executingVersion()) {
   return `${directory}/activation/${host}-${revision}-${hash(version).slice(0, 12)}.json`;
@@ -2949,9 +2969,9 @@ async function observeActivation(dir, event, options = {}) {
   const host = process.env.MASON_SETUP_HOST, revision = process.env.MASON_SETUP_REVISION;
   if (host !== "codex" && host !== "claude" || !revision || !process.env.MASON_SETUP_ROOT) return null;
   try {
-    const capturedDirectory = options.reportPath?.match(/^(\.mason\/reports\/automation\/[a-f0-9]{24})\/checks\//)?.[1];
-    const ws = capturedDirectory ? { root: await fs13.realpath(dir), directory: capturedDirectory } : await workspace(dir);
-    if (ws.root !== await fs13.realpath(process.env.MASON_SETUP_ROOT)) return null;
+    const capturedDirectory = options.directory?.match(/^\.mason\/reports\/automation\/[a-f0-9]{24}$/)?.[0] ?? options.reportPath?.match(/^(\.mason\/reports\/automation\/[a-f0-9]{24})\/checks\//)?.[1];
+    const ws = capturedDirectory ? { root: await fs14.realpath(dir), directory: capturedDirectory } : await workspace(dir);
+    if (ws.root !== await fs14.realpath(process.env.MASON_SETUP_ROOT)) return null;
     const setup = await loadSetup(ws.root);
     if (setup?.hosts[host]?.revision !== revision) return "Mason setup changed; restart the assistant to observe the current integration.";
     const directory = ws.directory + "/activation";
@@ -3022,13 +3042,13 @@ import { z as z9 } from "zod";
 function normalizeHook(host, raw) {
   hostSchema.parse(host);
   const input2 = inputSchema.parse(raw);
-  const readOnly = host === "claude" ? /^(Read|Glob|Grep|WebSearch|WebFetch)$/ : /^(read_file|list_dir|grep_files)$/;
-  return { cwd: input2.cwd, name: input2.hook_event_name, event: {
+  const readOnly = (host === "claude" ? /^(Read|Glob|Grep|WebSearch|WebFetch)$/ : /^(read_file|list_dir|grep_files|Read|Glob|Grep)$/).test(input2.tool_name ?? "");
+  return { cwd: input2.cwd, name: input2.hook_event_name, readOnly, event: {
     event: lifecycle[input2.hook_event_name],
     host,
     sessionId: input2.session_id,
     toolId: input2.tool_use_id,
-    mutating: !!input2.tool_name && !readOnly.test(input2.tool_name),
+    mutating: !!input2.tool_name && !readOnly,
     stopHookActive: input2.stop_hook_active || input2.permission_mode === "plan"
   } };
 }
@@ -3036,8 +3056,20 @@ async function runAutomationHook(host, stdin) {
   let name = "";
   try {
     if (Buffer.byteLength(stdin) > 1024 * 1024) throw new Error("Hook input exceeds 1 MiB.");
-    const input2 = normalizeHook(host, JSON.parse(stdin));
+    let raw;
+    try {
+      raw = JSON.parse(stdin);
+    } catch {
+      throw new Error("Hook input is not valid JSON.");
+    }
+    const input2 = normalizeHook(host, raw);
     name = input2.name;
+    if (["before_tool", "after_tool"].includes(input2.event.event) && input2.readOnly) {
+      const observed = await observeReadOnlyTool(input2.cwd, input2.event);
+      const { observeActivation: observeActivation3 } = await Promise.resolve().then(() => (init_observations(), observations_exports));
+      const warning2 = await observeActivation3(observed.root, input2.event.event, { sessionId: input2.event.sessionId, directory: observed.directory });
+      return warning2 ? { systemMessage: warning2 } : null;
+    }
     const result = await automate(input2.cwd, input2.event);
     const { observeActivation: observeActivation2 } = await Promise.resolve().then(() => (init_observations(), observations_exports));
     const warning = await observeActivation2(result.report.root, input2.event.event, {
@@ -3056,8 +3088,15 @@ async function runAutomationHook(host, stdin) {
     return { systemMessage: message2, ...["SessionStart", "UserPromptSubmit", "PreToolUse", "PostToolUse"].includes(name) ? { hookSpecificOutput: { hookEventName: name, additionalContext: message2 } } : {} };
   }
 }
+function managedHookCommand(host, platform = process.platform) {
+  const command = `mason --setup-host ${host} auto hook --host ${host}`;
+  return platform === "win32" ? `cmd.exe /d /s /c "where mason >nul 2>nul & if errorlevel 1 (exit /b 0) else (${command})"` : `if command -v mason >/dev/null 2>&1; then ${command}; fi`;
+}
+function knownManagedHookCommands(host) {
+  return [managedHookCommand(host, "linux"), managedHookCommand(host, "win32"), `mason --setup-host ${host} auto hook --host ${host}`];
+}
 function hookConfig(host, command = "npx --no-install --package mason-context mason-auto") {
-  const handler = { type: "command", command: command + " hook --host " + host, timeout: 30 };
+  const handler = { type: "command", command: command === `mason --setup-host ${host} auto` ? managedHookCommand(host) : command + " hook --host " + host, timeout: 30 };
   return { hooks: Object.fromEntries(HOOK_EVENTS.map((name) => [
     name,
     [{ ...["PreToolUse", "PostToolUse"].includes(name) ? { matcher: ".*" } : {}, hooks: [{ ...handler }] }]
@@ -3098,7 +3137,7 @@ __export(files_exports, {
   managedBlock: () => managedBlock,
   readText: () => readText
 });
-import fs14 from "fs/promises";
+import fs15 from "fs/promises";
 import path18 from "path";
 import { randomUUID as randomUUID5 } from "crypto";
 async function readText(root, file) {
@@ -3128,14 +3167,14 @@ async function applyEdit(root, edit) {
   if (edit.after === null) {
     const file2 = await storePath(root, edit.path);
     if (await readText(root, edit.path) !== edit.before) throw new Error("Input changed during removal: " + edit.path);
-    await fs14.unlink(file2);
+    await fs15.unlink(file2);
     return true;
   }
   const file = await storePath(root, edit.path, true);
   const temporary = path18.join(path18.dirname(file), ".mason-setup-" + randomUUID5() + ".tmp");
   try {
-    const mode = await fs14.stat(file).then((s) => s.mode & 511, () => 384);
-    const handle = await fs14.open(temporary, "wx", mode);
+    const mode = await fs15.stat(file).then((s) => s.mode & 511, () => 384);
+    const handle = await fs15.open(temporary, "wx", mode);
     try {
       await handle.writeFile(edit.after, "utf8");
       await handle.sync();
@@ -3143,10 +3182,10 @@ async function applyEdit(root, edit) {
       await handle.close();
     }
     if (await readText(root, edit.path) !== edit.before) throw new Error("Integration input changed during update: " + edit.path);
-    await fs14.rename(temporary, file);
+    await fs15.rename(temporary, file);
     return true;
   } finally {
-    await fs14.rm(temporary, { force: true });
+    await fs15.rm(temporary, { force: true });
   }
 }
 var init_files2 = __esm({
@@ -3248,9 +3287,9 @@ var init_init = __esm({
 
 Mason provides recorded decisions and file impact over MCP. A concept map is optional.
 
-- Task, bug, or change request \u2192 \`get_context\` with the task text and known files: matching decisions, related tests, impact, and any available map entries.
+- Task, bug, change request, or investigation of why the project works this way \u2192 \`get_context\` with the task text and known files: matching decisions, related tests, impact, and any available map entries.
 - Before editing a file \u2192 \`get_impact\` to check references, tests, and historical change partners.
-- Learned something the code cannot explain (a failed approach, an incident's cause, a workaround's reason, a review-settled convention) \u2192 \`save_decision\` with rationale, anchors, and any known owner, sources, and recorder. It creates a proposal immediately without setup or a map. Never invent attribution or record code-derivable facts, session trivia, or secrets.
+- Investigation or correction reveals a reusable project lesson \u2192 \`save_decision\` before finishing. Capture only the lasting constraint and reason, with anchors and known sources, owner, and recorder. This creates a proposal; never infer approval. Preserve uncertain causes and unknown attribution. Route project lessons here; keep personal preferences in agent memory. Skip code summaries, current checkout status, temporary task permissions, session trivia, and secrets. No qualifying lesson means no record.
 - Consult trust metadata before relying on entries: unknown or changed freshness requires inspection, and failed verification means the description must be corrected. Check approval too: proposals are suggestions, legacy records are unreviewed, and accepted decisions are recorded constraints subject to freshness checks. An accepted revision remains operative while a pending proposal is reviewed; keep both versions and their freshness distinct.
 - Asked to review or re-verify a decision \u2192 \`review_decision\` first to inspect content, sources, history, and code changes. Record acceptance, reaffirmation, or retirement only when authorized by the user or a cited team review, with the actual reviewer and reason. Never infer approval from unchanged code. Review and commit the local record through the normal project workflow.
 - For an architectural overview, use \`get_snapshot\` if a map is available. If \`map.status\` is missing or invalid, use available decisions and source evidence; do not start building a map unless requested.
@@ -3502,7 +3541,7 @@ async function planAutomationInstall(root, host, command) {
   const previous = record.hosts[host]?.command;
   const ownershipText = await readText(root, OWNERSHIP_PATH);
   const pending = ownershipText === null ? [] : ownershipSchema.parse(JSON.parse(ownershipText)).files[file]?.hookCommands ?? [];
-  const owned = /* @__PURE__ */ new Set([previous, ...pending, newCommand]);
+  const owned = /* @__PURE__ */ new Set([previous, ...pending, newCommand, ...knownManagedHookCommands(host)]);
   const hooks = existing.hooks ?? {};
   for (const event of HOOK_EVENTS) {
     hooks[event] = (hooks[event] ?? []).map((group) => ({
@@ -3606,6 +3645,7 @@ async function planTeardown(root, selected) {
   const commands = (host) => new Set([
     automation?.hosts[host]?.command,
     ...ownership.files[configPath(host)]?.hookCommands ?? [],
+    ...knownManagedHookCommands(host),
     hookConfig(host, hookCommand(host)).hooks.SessionStart[0].hooks[0].command,
     hookConfig(host).hooks.SessionStart[0].hooks[0].command
   ].filter((command) => !!command));
@@ -4335,7 +4375,7 @@ var init_evidence2 = __esm({
 });
 
 // src/review/review.ts
-import fs15 from "fs/promises";
+import fs16 from "fs/promises";
 import path20 from "path";
 import { execFile as execFile12 } from "child_process";
 import { promisify as promisify12 } from "util";
@@ -4415,7 +4455,7 @@ async function computeReview(rootDir, base, options = {}) {
     analyzed,
     async (relPath) => {
       try {
-        await fs15.access(path20.join(resolvedRoot, relPath));
+        await fs16.access(path20.join(resolvedRoot, relPath));
         return true;
       } catch {
         return false;
@@ -4569,7 +4609,7 @@ async function setupStatus(dir) {
       version: 1,
       status: pending.length ? "incomplete" : "not-configured",
       hosts: {},
-      next: pending.length ? "Setup did not finish. Rerun mason-auto setup --host " + pending[0] + " to resume using the retained original evidence." : "Run mason-auto setup --host codex or --host claude."
+      next: pending.length ? "Setup did not finish. Rerun mason-auto setup --host " + pending[0] + " to resume using the retained original evidence." : "Project hooks are inactive until local setup. Run mason setup --host codex or --host claude."
     };
   }
   const hosts2 = {};