@minhpnq1807/contextos 0.1.0 → 0.1.3

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 0.1.3
+
+- Separates runtime prompt/report/stats files per workspace under `~/.ctx/contextos/workspaces/<workspace-id>`.
+- Adds a local `.contextos/workspace.json` marker and `.gitignore` entry so workspace identity is stable without being pushed.
+- Keeps MCP/model caches shared at the ContextOS data root while isolating report, evidence, stats, and telemetry by project path.
+
+## 0.1.2
+
+- Adds local runtime telemetry for hook-visible tool, MCP, and command signals.
+- Uses telemetry evidence in Stop reports so runtime-only rules can be marked `followed` instead of staying `unknown` when matching tool/command signals are observed.
+- Shows runtime telemetry summaries in `ctx report` output.
+
+## 0.1.1
+
+- Fixes `sql.js` WASM resolution when ContextOS is executed from the published npm package through `npm exec` or `npx`.
+
 ## 0.1.0
 
 Initial public release.

package/README.md

@@ -4,10 +4,13 @@ ContextOS (`ctx`) is a Codex companion plugin for task-aware project context.
 
 It reads `AGENTS.md` guidance, scores the rules against the current prompt, suggests relevant files, records what context would have been injected, and reports lightweight compliance evidence after the task finishes.
 
+Published package: [`@minhpnq1807/contextos`](https://www.npmjs.com/package/@minhpnq1807/contextos)
+
 ## Quick Start
 
 ```bash
 npm install -g @minhpnq1807/contextos
+ctx --version
 ctx install
 ```
 
@@ -16,7 +19,7 @@ Restart Codex after installing, then use Codex normally. ContextOS runs through
 You can also run without a global install:
 
 ```bash
-npx @minhpnq1807/contextos install
+npx @minhpnq1807/contextos@latest install
 ```
 
 ## Demo Flow
@@ -67,8 +70,8 @@ With ContextOS, each prompt gets a compact block:
   - first, local prompt/file heuristics create seed candidates;
   - then, if `.code-review-graph/graph.db` exists, ContextOS queries `code-review-graph` semantic search and re-ranks graph-backed matches;
   - if no graph exists or graph lookup times out, it falls back to local heuristics.
-- Stores scheduled context and hook telemetry under `$CODEX_HOME/contextos`.
-- Reports rule outcomes as `followed`, `ignored`, or `unknown`.
+- Stores scheduled context and hook telemetry per workspace under `~/.ctx/contextos/workspaces/<workspace-id>`.
+- Reports rule outcomes as `followed`, `ignored`, or `unknown`, using runtime telemetry for tool/command rules when available.
 - Injects `additionalContext` into Codex by default.
 
 By default, ContextOS runs in injection mode. It adds task-relevant rules and files to the model context so the agent has the right project guidance at the moment it starts working.
@@ -78,27 +81,41 @@ By default, ContextOS runs in injection mode. It adds task-relevant rules and fi
 From the package:
 
 ```bash
-npx @minhpnq1807/contextos install
+npm install -g @minhpnq1807/contextos
+ctx install
+```
+
+Without a global install:
+
+```bash
+npx @minhpnq1807/contextos@latest install
 ```
 
 From this repository during local development:
 
 ```bash
-rtk node bin/ctx.js install
+node bin/ctx.js install
 ```
 
 `ctx install` does three things:
 
 1. Copies this package into `$CODEX_HOME/marketplaces/contextos`.
 2. Registers and installs `ctx@contextos` through Codex plugin marketplace commands.
-3. Downloads and caches the required local MiniLM embedding model under `$CODEX_HOME/contextos/models`.
-4. Warms `$CODEX_HOME/contextos/embeddings.db` for AGENTS rules and project file paths.
+3. Downloads and caches the required local MiniLM embedding model under `~/.ctx/contextos/models`.
+4. Warms `~/.ctx/contextos/embeddings.db` for AGENTS rules and project file paths.
 5. Registers the `ctx-mcp` MCP server and merges ContextOS global hooks into `$CODEX_HOME/hooks.json`.
 
 Restart Codex after installing.
 
 The embedding model is mandatory. `ctx install` intentionally fails if the model cannot be prepared, because otherwise the first prompt hook would have to cold-load or download the model.
 
+Verify the published package in any project:
+
+```bash
+npm exec --yes --package=@minhpnq1807/contextos@latest -- ctx --version
+npm exec --yes --package=@minhpnq1807/contextos@latest -- ctx debug -- "fix upload moderation flow"
+```
+
 ## Modes
 
 Injection mode is the default:
@@ -153,86 +170,39 @@ Run at least one Codex task with ContextOS enabled and let the task finish so th
 
 ### `Average efficiency: unknown`
 
-ContextOS only reports efficiency when git diff/status contains concrete evidence. Runtime-only rules, such as tool usage order, are shown as `unknown` unless they leave evidence in changed files.
-
-## Commands
-
-```bash
-ctx install
-ctx install --quiet
-ctx install --inject
-ctx install --copy
-ctx debug -- "fix auth login bug"
-ctx report
-ctx evidence
-ctx stats
-ctx embeddings warm -- "fix upload moderation flow"
-ctx --version
-```
-
-### `ctx debug`
-
-Runs ContextOS scheduling locally for a fake task and prints rule scores plus the final context that would be injected.
-
-```bash
-ctx debug -- "fix upload moderation flow"
-```
+ContextOS only reports efficiency when it has concrete evidence. Diff-based rules are measured from git diff/status. Runtime-only rules, such as tool usage order, are measured from local hook telemetry when Codex exposes tool or command metadata. If neither source proves the outcome, the rule remains `unknown`.
 
-### `ctx report`
+### `npm warn deprecated prebuild-install@7.1.3`
 
-Shows the last Stop-hook report.
+This warning comes from a transitive dependency in the local embedding/WASM stack. It does not block installation or runtime commands. ContextOS still runs normally if npm exits with code `0`.
 
-```bash
-ctx report
-```
-
-### `ctx evidence`
-
-Shows detailed rule-by-rule evidence for the last report:
-
-- status
-- rule text
-- source file
-- score
-- evidence reason
-
-```bash
-ctx evidence
-```
-
-### `ctx stats`
-
-Shows aggregate runtime stats:
-
-- prompts analyzed
-- reports generated
-- injected vs quiet prompts
-- average prompt analysis time
-- average efficiency
-- followed / ignored / unknown counts
-- hook event counts
-- last prompt and suggested files
+## Commands
 
-```bash
-ctx stats
-```
+| Command | Meaning | Use when | Output / side effect |
+| --- | --- | --- | --- |
+| `ctx install` | Installs ContextOS into Codex with prompt context injection enabled. | Normal setup after installing the npm package. | Copies the plugin into `$CODEX_HOME/marketplaces/contextos`, registers `ctx@contextos`, registers `ctx-mcp`, installs global hooks, downloads the embedding model, and warms caches. |
+| `ctx install --quiet` | Installs ContextOS in measurement-only mode. | You want reports and stats but do not want a visible `hook context` block in Codex. | Installs the same plugin/hooks, but prompt hooks return empty `additionalContext`. |
+| `ctx install --inject` | Installs ContextOS with explicit injection mode. | You want to be explicit in scripts or docs. | Same runtime behavior as `ctx install`. |
+| `ctx install --copy` | Copies only the plugin payload to `$CODEX_HOME/plugins/ctx`. | Local development or manual plugin experiments. | Does not register marketplace, MCP, or global hooks. |
+| `ctx debug -- "task"` | Runs the scheduler locally for a fake prompt. | You want to see which AGENTS.md rules and files ContextOS would inject before using Codex. | Prints rule scores, scoring reasons, suggested files, and final `additionalContext`. |
+| `ctx report` | Shows the last Stop-hook compliance report for the current workspace. | A Codex task has finished and you want the summary again. | Reads `~/.ctx/contextos/workspaces/<workspace-id>/last-report.json`. |
+| `ctx evidence` | Shows detailed evidence behind the last report for the current workspace. | You want to inspect why a rule was marked `followed`, `ignored`, or `unknown`. | Prints rule text, source file, score, status, and evidence reason. |
+| `ctx stats` | Shows aggregate runtime metrics for the current workspace. | You want to know whether ContextOS is active and useful over time. | Prints prompt count, report count, injected/quiet ratio, average prompt analysis time, efficiency, rule outcomes, hook events, and last suggested files for the current workspace only. |
+| `ctx embeddings warm -- "task"` | Prepares local semantic embedding caches. | First install, CI smoke checks, or after changing AGENTS.md/project files. | Loads/downloads `Xenova/all-MiniLM-L6-v2` and writes vectors to `~/.ctx/contextos/embeddings.db`. |
+| `ctx --version` | Prints the installed ContextOS CLI version. | You want to confirm which npm version is being executed. | Prints the version from package metadata. |
 
-### `ctx embeddings`
+## Runtime Files
 
-Builds local embeddings for semantic rule scoring.
+ContextOS writes shared caches to:
 
-```bash
-ctx embeddings warm -- "fix upload moderation flow"
+```text
+~/.ctx/contextos/
 ```
 
-`warm` downloads/loads the local `Xenova/all-MiniLM-L6-v2` model if needed and stores rule/prompt vectors plus project file path vectors in `$CODEX_HOME/contextos/embeddings.db`.
-
-## Runtime Files
-
-ContextOS writes runtime data to:
+Runtime prompt/report files are isolated by workspace:
 
 ```text
-$CODEX_HOME/contextos/
+~/.ctx/contextos/workspaces/<workspace-id>/
 ```
 
 Important files:
@@ -244,8 +214,17 @@ last-prompt-context.json  latest scheduled context
 last-report.json          latest compliance report
 prompt-history.jsonl      prompt scheduling history
 report-history.jsonl      report history
+telemetry.jsonl           local runtime signals from hooks, tools, and commands
 ```
 
+The workspace id is stored in the target repo at:
+
+```text
+.contextos/workspace.json
+```
+
+ContextOS also adds `.contextos/` to the repo `.gitignore` so the local marker is not pushed. If the marker cannot be written, ContextOS falls back to a deterministic id generated from the workspace real path.
+
 These files are local telemetry only. Hooks do not make network calls.
 
 ## Project Understanding
@@ -299,7 +278,7 @@ Codex prompt
 
 ## Rule Outcomes
 
-ContextOS uses a heuristic diff-based measurement.
+ContextOS uses heuristic evidence collection from git diff/status plus local runtime telemetry.
 
 ```text
 followed = evidence in the diff suggests the rule was applied
@@ -307,32 +286,34 @@ ignored  = evidence in the diff suggests the rule was violated
 unknown  = the rule was relevant, but the diff does not prove either way
 ```
 
-Example `unknown`: a rule says shell commands must run as `minh_dev`, but git diff does not record shell user identity. ContextOS cannot prove the rule was followed from code changes alone.
+For runtime-only rules, ContextOS also checks `telemetry.jsonl` for hook-visible tool names, MCP server names, and command metadata. A rule like "use code-review-graph before reading files" can be marked `followed` when telemetry contains a matching `code-review-graph` signal.
+
+Example `unknown`: a rule says shell commands must run as a specific OS user, but neither git diff nor hook telemetry records that user identity. ContextOS cannot prove the rule was followed from available evidence alone.
 
 ## Development
 
 Install dependencies:
 
 ```bash
-rtk npm install
+npm install
 ```
 
 Run tests:
 
 ```bash
-rtk npm test
+npm test
 ```
 
 Run MCP protocol and warm performance smoke:
 
 ```bash
-rtk npm run test:mcp
+npm run test:mcp
 ```
 
 Validate plugin schema:
 
 ```bash
-rtk npm run validate:plugin
+npm run validate:plugin
 ```
 
 Check the npm package contents:

package/bin/ctx.js

@@ -13,6 +13,7 @@ import { formatStats, loadStats } from "../plugins/ctx/lib/stats.js";
 import { modelCacheDir, warmRuleEmbeddings } from "../plugins/ctx/lib/embedding-scorer.js";
 import { warmFileEmbeddings } from "../plugins/ctx/lib/file-embedding-retriever.js";
 import { scoreContext } from "../plugins/ctx/lib/score-context.js";
+import { defaultDataRoot, workspaceDataDir, workspaceMarkerPath } from "../plugins/ctx/lib/workspace-data.js";
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const rootDir = path.resolve(__dirname, "..");
@@ -35,6 +36,15 @@ Usage:
 `;
 }
 
+function packageVersion() {
+  try {
+    const packageJson = JSON.parse(fs.readFileSync(path.join(rootDir, "package.json"), "utf8"));
+    return packageJson.version || "0.0.0";
+  } catch {
+    return "0.0.0";
+  }
+}
+
 function codexHome() {
   return process.env.CODEX_HOME || path.join(process.env.HOME || process.cwd(), ".codex");
 }
@@ -145,8 +155,9 @@ function runCodex(args) {
 }
 
 function loadLastReport() {
+  const workspaceDir = contextOSWorkspaceDataDir();
   const candidates = [
-    process.env.PLUGIN_DATA && path.join(process.env.PLUGIN_DATA, "last-report.json"),
+    path.join(workspaceDir, "last-report.json"),
     path.join(codexHome(), "contextos", "last-report.json"),
     path.join(codexHome(), "marketplaces", "contextos", "plugins", "ctx", ".data", "last-report.json"),
     path.join(codexHome(), "plugins", "ctx", ".data", "last-report.json"),
@@ -162,7 +173,11 @@ function loadLastReport() {
 }
 
 function contextOSDataDir() {
-  return process.env.PLUGIN_DATA || path.join(codexHome(), "contextos");
+  return defaultDataRoot();
+}
+
+function contextOSWorkspaceDataDir(cwd = process.cwd()) {
+  return workspaceDataDir({ cwd, dataRoot: contextOSDataDir() });
 }
 
 async function debug(task) {
@@ -180,6 +195,8 @@ async function debug(task) {
 
   console.log("ContextOS debug");
   console.log(`cwd: ${cwd}`);
+  console.log(`workspace data: ${contextOSWorkspaceDataDir(cwd)}`);
+  console.log(`workspace marker: ${workspaceMarkerPath(cwd)}`);
   console.log(`rules: ${rules.length}`);
   console.log(`mcp scorer: ${scored.telemetry.modelStatus}${scored.telemetry.model ? ` (${scored.telemetry.model})` : ""}`);
   console.log(`elapsed: ${scored.telemetry.elapsedMs}ms`);
@@ -230,7 +247,7 @@ try {
   if (!command || command === "--help" || command === "-h") {
     console.log(usage());
   } else if (command === "--version" || command === "-v") {
-    console.log("0.1.0");
+    console.log(packageVersion());
   } else if (command === "install") {
     await install({ copy: args.includes("--copy"), inject: !args.includes("--quiet") });
   } else if (command === "debug") {
@@ -251,7 +268,7 @@ try {
   } else if (command === "evidence") {
     console.log(formatEvidence(loadLastReport()));
   } else if (command === "stats") {
-    console.log(formatStats(loadStats(contextOSDataDir())));
+    console.log(formatStats(loadStats(contextOSWorkspaceDataDir())));
   } else {
     throw new Error(`Unknown command: ${command}\n\n${usage()}`);
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@minhpnq1807/contextos",
-  "version": "0.1.0",
+  "version": "0.1.3",
   "description": "Task-aware AGENTS.md context injection and compliance reporting for Codex.",
   "type": "module",
   "bin": {

package/plugins/ctx/bin/on-prompt.js

@@ -1,16 +1,20 @@
 #!/usr/bin/env node
-import { readStdinJson, writeJson, failOpen, logDebug, pluginDataDir } from "../lib/hook-io.js";
+import { readStdinJson, writeJson, failOpen, logDebug, pluginRuntimeFile, pluginDataRoot } from "../lib/hook-io.js";
 import { handlePromptPayload } from "../lib/prompt-hook.js";
+import { appendTelemetry } from "../lib/telemetry.js";
 
 const started = Date.now();
 
 try {
   const payload = await readStdinJson();
+  const cwd = payload.cwd || payload.working_directory;
 
   logDebug("UserPromptSubmit", payload);
+  appendTelemetry({ telemetryPath: pluginRuntimeFile("telemetry.jsonl", cwd), event: "UserPromptSubmit", payload });
   writeJson(await handlePromptPayload(payload, {
-    dataPath: pluginDataDir("last-prompt-context.json"),
-    historyPath: pluginDataDir("prompt-history.jsonl"),
+    dataPath: pluginRuntimeFile("last-prompt-context.json", cwd),
+    historyPath: pluginRuntimeFile("prompt-history.jsonl", cwd),
+    mcpDataDir: pluginDataRoot(),
     started
   }));
 } catch (error) {

package/plugins/ctx/bin/on-session-start.js

@@ -1,9 +1,12 @@
 #!/usr/bin/env node
-import { readStdinJson, writeJson, failOpen, logDebug } from "../lib/hook-io.js";
+import { readStdinJson, writeJson, failOpen, logDebug, pluginRuntimeFile } from "../lib/hook-io.js";
+import { appendTelemetry } from "../lib/telemetry.js";
 
 try {
   const payload = await readStdinJson();
+  const cwd = payload.cwd || payload.working_directory;
   logDebug("SessionStart", payload);
+  appendTelemetry({ telemetryPath: pluginRuntimeFile("telemetry.jsonl", cwd), event: "SessionStart", payload });
   writeJson({
     continue: true,
     suppressOutput: true,

package/plugins/ctx/bin/on-stop.js

@@ -1,14 +1,18 @@
 #!/usr/bin/env node
-import { readStdinJson, writeJson, failOpen, logDebug, pluginDataDir } from "../lib/hook-io.js";
+import { readStdinJson, writeJson, failOpen, logDebug, pluginRuntimeFile } from "../lib/hook-io.js";
 import { handleStopPayload } from "../lib/stop-hook.js";
+import { appendTelemetry } from "../lib/telemetry.js";
 
 try {
   const payload = await readStdinJson();
+  const cwd = payload.cwd || payload.working_directory;
   logDebug("Stop", payload);
+  appendTelemetry({ telemetryPath: pluginRuntimeFile("telemetry.jsonl", cwd), event: "Stop", payload });
   writeJson(handleStopPayload(payload, {
-    contextPath: pluginDataDir("last-prompt-context.json"),
-    reportPath: pluginDataDir("last-report.json"),
-    historyPath: pluginDataDir("report-history.jsonl")
+    contextPath: pluginRuntimeFile("last-prompt-context.json", cwd),
+    reportPath: pluginRuntimeFile("last-report.json", cwd),
+    historyPath: pluginRuntimeFile("report-history.jsonl", cwd),
+    telemetryPath: pluginRuntimeFile("telemetry.jsonl", cwd)
   }));
 } catch (error) {
   failOpen("Stop", error, {

package/plugins/ctx/lib/ctx-mcp-client.js

@@ -1,8 +1,9 @@
 import fs from "node:fs";
 import net from "node:net";
-import os from "node:os";
 import path from "node:path";
 
+import { defaultDataRoot } from "./workspace-data.js";
+
 const DEFAULT_TIMEOUT_MS = 1000;
 
 export function ctxMcpSocketPath(dataDir = defaultDataDir()) {
@@ -48,5 +49,5 @@ export async function callCtxScoreContext(payload, {
 }
 
 function defaultDataDir() {
-  return process.env.PLUGIN_DATA || path.join(process.env.CODEX_HOME || path.join(os.homedir(), ".codex"), "contextos");
+  return defaultDataRoot();
 }

package/plugins/ctx/lib/embedding-scorer.js

@@ -1,9 +1,11 @@
 import crypto from "node:crypto";
 import fs from "node:fs";
-import os from "node:os";
 import path from "node:path";
+import { createRequire } from "node:module";
 import { fileURLToPath } from "node:url";
 
+import { defaultDataRoot } from "./workspace-data.js";
+
 const DEFAULT_MODEL = "Xenova/all-MiniLM-L6-v2";
 const DEFAULT_TIMEOUT_MS = 800;
 const SEMANTIC_HIGH_THRESHOLD = 0.5;
@@ -13,12 +15,13 @@ let sqlPromise = null;
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const repoRoot = path.resolve(__dirname, "..", "..", "..");
+const require = createRequire(import.meta.url);
 
 export async function enhanceRuleScoresWithEmbeddings(
   rules,
   task,
   {
-    dataDir = path.join(os.homedir(), ".codex", "contextos"),
+    dataDir = defaultDataRoot(),
     sources = [],
     timeoutMs = Number(process.env.CONTEXTOS_EMBEDDING_TIMEOUT_MS || DEFAULT_TIMEOUT_MS),
     allowRemote = process.env.CONTEXTOS_EMBEDDING_ALLOW_REMOTE === "1",
@@ -50,7 +53,7 @@ export async function enhanceRuleScoresWithEmbeddings(
 export async function warmRuleEmbeddings({
   rules = [],
   task = "",
-  dataDir = path.join(os.homedir(), ".codex", "contextos"),
+  dataDir = defaultDataRoot(),
   sources = [],
   allowRemote = true
 } = {}) {
@@ -124,7 +127,7 @@ async function getExtractor({ allowRemote, dataDir }) {
   return extractorPromises.get(key);
 }
 
-export function modelCacheDir(dataDir = path.join(os.homedir(), ".codex", "contextos")) {
+export function modelCacheDir(dataDir = defaultDataRoot()) {
   return path.join(dataDir, "models");
 }
 
@@ -189,13 +192,21 @@ async function getSql() {
     sqlPromise = (async () => {
       const initSqlJs = (await import("sql.js")).default;
       return initSqlJs({
-        locateFile: (file) => path.join(repoRoot, "node_modules", "sql.js", "dist", file)
+        locateFile: locateSqlJsFile
       });
     })();
   }
   return sqlPromise;
 }
 
+function locateSqlJsFile(file) {
+  try {
+    return require.resolve(`sql.js/dist/${file}`);
+  } catch {
+    return path.join(repoRoot, "node_modules", "sql.js", "dist", file);
+  }
+}
+
 function cacheKey(text, sources) {
   return crypto
     .createHash("sha256")

package/plugins/ctx/lib/hook-io.js

@@ -1,10 +1,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { writeJsonFile } from "./fs-utils.js";
-
-function codexHome() {
-  return process.env.CODEX_HOME || path.join(process.env.HOME || process.cwd(), ".codex");
-}
+import { defaultDataRoot, workspaceDataDir } from "./workspace-data.js";
 
 export async function readStdinJson() {
   const chunks = [];
@@ -18,8 +15,19 @@ export function writeJson(value) {
   process.stdout.write(`${JSON.stringify(value)}\n`);
 }
 
-export function pluginDataDir(fileName = "") {
-  const root = process.env.PLUGIN_DATA || path.join(codexHome(), "contextos");
+export function pluginDataDir(fileName = "", cwd = process.cwd()) {
+  let root;
+  try {
+    root = workspaceDataDir({ cwd });
+    fs.mkdirSync(root, { recursive: true });
+  } catch {
+    return path.join(process.cwd(), ".contextos", fileName);
+  }
+  return path.join(root, fileName);
+}
+
+export function pluginDataRoot(fileName = "") {
+  const root = defaultDataRoot();
   try {
     fs.mkdirSync(root, { recursive: true });
   } catch {
@@ -28,10 +36,14 @@ export function pluginDataDir(fileName = "") {
   return path.join(root, fileName);
 }
 
+export function pluginRuntimeFile(fileName = "", cwd) {
+  return cwd ? pluginDataDir(fileName, cwd) : pluginDataRoot(fileName);
+}
+
 export function logDebug(event, payload) {
   const line = JSON.stringify({ at: new Date().toISOString(), event, payload });
   try {
-    fs.appendFileSync(pluginDataDir("debug.log"), `${line}\n`, "utf8");
+    fs.appendFileSync(pluginRuntimeFile("debug.log", payload?.cwd || payload?.working_directory), `${line}\n`, "utf8");
   } catch {
     // Logging must never break Codex hooks.
   }

package/plugins/ctx/lib/measure.js

@@ -3,6 +3,7 @@ import fs from "node:fs";
 import path from "node:path";
 
 import { tokenize } from "./analyzer.js";
+import { findRuntimeEvidence, runtimeKeywordsForRule } from "./telemetry.js";
 
 const COMPLIANCE_STOPWORDS = new Set([
   "always",
@@ -156,24 +157,38 @@ export function parseGitDiff(diff) {
   };
 }
 
-export function checkCompliance({ rules = [], addedLines = [] } = {}) {
+export function checkCompliance({ rules = [], addedLines = [], runtimeEvidence = {} } = {}) {
   const results = [];
 
   for (const rule of rules) {
     const lower = rule.content.toLowerCase();
     const keywords = extractComplianceKeywords(rule.content);
     const isRuntimeOnly = needsRuntimeEvidence(rule.content);
+    const runtimeMatch = isRuntimeOnly ? findRuntimeEvidence(rule, runtimeEvidence) : null;
     const kind = lower.includes("no ") || lower.includes("never") || lower.includes("khong")
       ? "forbidden"
       : "required";
 
+    if (isRuntimeOnly && runtimeMatch) {
+      results.push({
+        rule,
+        status: "followed",
+        kind: "runtime",
+        keywords: [...new Set([...keywords, ...runtimeKeywordsForRule(rule.content)])],
+        evidence: runtimeMatch.evidence
+      });
+      continue;
+    }
+
     if (!keywords.length || !addedLines.length) {
       results.push({
         rule,
         status: "unknown",
-        kind,
+        kind: isRuntimeOnly ? "runtime" : kind,
         keywords,
-        evidence: !addedLines.length ? "no added lines in git diff" : "no concrete compliance keywords found"
+        evidence: isRuntimeOnly
+          ? "requires runtime/tool-call telemetry; no matching runtime signal observed"
+          : (!addedLines.length ? "no added lines in git diff" : "no concrete compliance keywords found")
       });
       continue;
     }
@@ -184,7 +199,7 @@ export function checkCompliance({ rules = [], addedLines = [] } = {}) {
         status: "unknown",
         kind: "runtime",
         keywords,
-        evidence: "requires runtime/tool-call evidence, not git diff evidence"
+        evidence: "requires runtime/tool-call telemetry; no matching runtime signal observed"
       });
       continue;
     }
@@ -235,7 +250,8 @@ export function checkCompliance({ rules = [], addedLines = [] } = {}) {
 }
 
 function needsRuntimeEvidence(content) {
-  return RUNTIME_EVIDENCE_PATTERNS.some((pattern) => pattern.test(content));
+  return RUNTIME_EVIDENCE_PATTERNS.some((pattern) => pattern.test(content))
+    || runtimeKeywordsForRule(content).length > 0;
 }
 
 function findKeywordEvidence(lines, keywords) {

package/plugins/ctx/lib/prompt-hook.js

@@ -11,7 +11,8 @@ export async function handlePromptPayload(
     now = new Date(),
     started = Date.now(),
     injectContext = process.env.CONTEXTOS_INJECT !== "0",
-    scoreContextClient = callCtxScoreContext
+    scoreContextClient = callCtxScoreContext,
+    mcpDataDir
   } = {}
 ) {
   const prompt = payload.prompt || payload.message || payload.user_prompt || "";
@@ -25,7 +26,7 @@ export async function handlePromptPayload(
     openFiles,
     maxFiles: 3
   }, {
-    dataDir,
+    dataDir: mcpDataDir || dataDir,
     timeoutMs: Number(process.env.CONTEXTOS_MCP_BRIDGE_TIMEOUT_MS || 1000)
   });
 

package/plugins/ctx/lib/reporter.js

@@ -1,4 +1,4 @@
-export function buildReport({ cwd, prompt, relevantFiles, scheduled, gitSnapshot, compliance }) {
+export function buildReport({ cwd, prompt, relevantFiles, scheduled, gitSnapshot, compliance, runtimeEvidence }) {
   const followed = compliance.filter((item) => item.status === "followed");
   const ignored = compliance.filter((item) => item.status === "ignored");
   const unknown = compliance.filter((item) => item.status === "unknown");
@@ -13,6 +13,7 @@ export function buildReport({ cwd, prompt, relevantFiles, scheduled, gitSnapshot
     relevantFiles,
     changedFiles: gitSnapshot.changedFiles,
     warnings: gitSnapshot.warnings || [],
+    runtimeEvidence: summarizeRuntimeEvidence(runtimeEvidence),
     followed,
     ignored,
     unknown,
@@ -34,6 +35,9 @@ export function formatReport(report) {
   if (report.relevantFiles?.length) {
     lines.push(`Suggested files: ${report.relevantFiles.map((file) => file.path).join(", ")}`);
   }
+  if (report.runtimeEvidence?.signals?.length) {
+    lines.push(`Runtime telemetry: ${report.runtimeEvidence.signals.join(", ")}`);
+  }
 
   for (const warning of report.warnings || []) lines.push(`Warning: ${warning}`);
 
@@ -103,3 +107,15 @@ function truncate(value, max) {
   const normalized = String(value || "").replace(/\s+/g, " ").trim();
   return normalized.length > max ? `${normalized.slice(0, max - 3)}...` : normalized;
 }
+
+function summarizeRuntimeEvidence(runtimeEvidence = {}) {
+  const signals = [
+    ...(runtimeEvidence.toolSignals || []),
+    ...(runtimeEvidence.commandSignals || []),
+    ...(runtimeEvidence.signals || [])
+  ];
+  return {
+    signals: [...new Set(signals)].slice(0, 20),
+    sources: (runtimeEvidence.sources || []).slice(0, 10)
+  };
+}

package/plugins/ctx/lib/stop-hook.js

@@ -3,8 +3,9 @@ import fs from "node:fs";
 import { appendJsonLine, readJsonFile, writeJsonFile } from "./fs-utils.js";
 import { readGitSnapshot, checkCompliance } from "./measure.js";
 import { buildReport, formatReport } from "./reporter.js";
+import { loadRuntimeEvidence } from "./telemetry.js";
 
-export function handleStopPayload(payload, { contextPath, reportPath, historyPath } = {}) {
+export function handleStopPayload(payload, { contextPath, reportPath, historyPath, telemetryPath } = {}) {
   const cwd = payload.cwd || payload.working_directory || process.cwd();
   const promptContext = contextPath && fs.existsSync(contextPath) ? readJsonFile(contextPath) : null;
   const scheduledRules = [
@@ -12,14 +13,25 @@ export function handleStopPayload(payload, { contextPath, reportPath, historyPat
     ...(promptContext?.scheduled?.midRules || [])
   ];
   const gitSnapshot = readGitSnapshot({ cwd });
-  const compliance = checkCompliance({ rules: scheduledRules, addedLines: gitSnapshot.addedLines });
+  const runtimeEvidence = loadRuntimeEvidence({
+    telemetryPath,
+    since: promptContext?.at,
+    cwd,
+    payload
+  });
+  const compliance = checkCompliance({
+    rules: scheduledRules,
+    addedLines: gitSnapshot.addedLines,
+    runtimeEvidence
+  });
   const report = buildReport({
     cwd,
     prompt: promptContext?.prompt || "",
     relevantFiles: promptContext?.relevantFiles || [],
     scheduled: promptContext?.scheduled || null,
     gitSnapshot,
-    compliance
+    compliance,
+    runtimeEvidence
   });
 
   if (reportPath) writeJsonFile(reportPath, report);

package/plugins/ctx/lib/telemetry.js

@@ -0,0 +1,188 @@
+import fs from "node:fs";
+
+import { appendJsonLine } from "./fs-utils.js";
+
+const MAX_TEXT_VALUES = 80;
+const MAX_TEXT_LENGTH = 500;
+const MAX_EVENTS = 500;
+
+const TOOL_SIGNAL_KEYS = new Set([
+  "tool",
+  "tool_name",
+  "toolName",
+  "name",
+  "server",
+  "mcp",
+  "command",
+  "cmd"
+]);
+
+const SIGNAL_PATTERNS = [
+  /\bcode-review-graph\b/i,
+  /\brtk\b/i,
+  /\bdetect_changes\b/i,
+  /\bget_review_context\b/i,
+  /\bget_impact_radius\b/i,
+  /\bget_affected_flows\b/i,
+  /\bquery_graph\b/i,
+  /\bsemantic_search_nodes\b/i,
+  /\bget_architecture_overview\b/i,
+  /\blist_communities\b/i,
+  /\bagentmemory\b/i
+];
+
+export function appendTelemetry({ telemetryPath, event, payload, extra = {} }) {
+  if (!telemetryPath) return;
+  try {
+    appendJsonLine(telemetryPath, buildTelemetryEvent({ event, payload, extra }));
+  } catch {
+    // Telemetry is diagnostic; hooks must stay fail-open.
+  }
+}
+
+export function buildTelemetryEvent({ event, payload, extra = {}, at = new Date() }) {
+  const extracted = extractPayloadSignals(payload);
+  return {
+    at: at.toISOString(),
+    event,
+    cwd: payload?.cwd || payload?.working_directory || null,
+    ...extra,
+    signals: extracted.signals,
+    toolSignals: extracted.toolSignals,
+    commandSignals: extracted.commandSignals
+  };
+}
+
+export function loadRuntimeEvidence({ telemetryPath, since, cwd, payload } = {}) {
+  const events = [];
+  if (telemetryPath && fs.existsSync(telemetryPath)) {
+    const lines = fs.readFileSync(telemetryPath, "utf8").split(/\r?\n/).filter(Boolean).slice(-MAX_EVENTS);
+    for (const line of lines) {
+      try {
+        events.push(JSON.parse(line));
+      } catch {
+        // Ignore corrupt telemetry lines.
+      }
+    }
+  }
+
+  if (payload) {
+    events.push(buildTelemetryEvent({ event: payload.hook_event_name || "Stop", payload }));
+  }
+
+  const sinceMs = since ? Date.parse(since) : null;
+  const filtered = events.filter((event) => {
+    if (cwd && event.cwd && event.cwd !== cwd) return false;
+    if (sinceMs && event.at && Date.parse(event.at) < sinceMs) return false;
+    return true;
+  });
+
+  const signals = new Set();
+  const toolSignals = new Set();
+  const commandSignals = new Set();
+  const sources = [];
+
+  for (const event of filtered) {
+    for (const signal of event.signals || []) signals.add(signal);
+    for (const signal of event.toolSignals || []) toolSignals.add(signal);
+    for (const signal of event.commandSignals || []) commandSignals.add(signal);
+    if ((event.signals?.length || event.toolSignals?.length || event.commandSignals?.length) && sources.length < 20) {
+      sources.push({ at: event.at, event: event.event, cwd: event.cwd });
+    }
+  }
+
+  return {
+    signals: [...signals],
+    toolSignals: [...toolSignals],
+    commandSignals: [...commandSignals],
+    sources
+  };
+}
+
+export function findRuntimeEvidence(rule, runtimeEvidence = {}) {
+  const content = String(rule?.content || "");
+  const candidates = [
+    ...(runtimeEvidence.toolSignals || []),
+    ...(runtimeEvidence.commandSignals || []),
+    ...(runtimeEvidence.signals || [])
+  ];
+  const lowerCandidates = candidates.map((value) => String(value || "").toLowerCase());
+
+  const wanted = runtimeKeywordsForRule(content);
+  for (const keyword of wanted) {
+    const lowerKeyword = keyword.toLowerCase();
+    const match = lowerCandidates.find((candidate) => candidate.includes(lowerKeyword));
+    if (match) {
+      return {
+        keyword,
+        evidence: `runtime telemetry observed ${keyword}`
+      };
+    }
+  }
+
+  return null;
+}
+
+export function runtimeKeywordsForRule(content) {
+  const lower = String(content || "").toLowerCase();
+  const keywords = [];
+  for (const pattern of SIGNAL_PATTERNS) {
+    const match = lower.match(pattern);
+    if (match?.[0]) keywords.push(match[0]);
+  }
+  const backticks = [...String(content || "").matchAll(/`([^`]+)`/g)].map((match) => match[1]);
+  for (const value of backticks) {
+    if (SIGNAL_PATTERNS.some((pattern) => pattern.test(value))) keywords.push(value);
+  }
+  return [...new Set(keywords)];
+}
+
+function extractPayloadSignals(payload) {
+  const values = [];
+  const toolSignals = [];
+  const commandSignals = [];
+
+  walk(payload, [], (path, value) => {
+    if (values.length < MAX_TEXT_VALUES) values.push(value);
+    const key = path.at(-1) || "";
+    if (TOOL_SIGNAL_KEYS.has(key)) {
+      toolSignals.push(value);
+      if (key === "command" || key === "cmd") commandSignals.push(value);
+    }
+  });
+
+  const signals = [];
+  for (const value of values) {
+    for (const pattern of SIGNAL_PATTERNS) {
+      const match = String(value).match(pattern);
+      if (match?.[0]) signals.push(match[0]);
+    }
+  }
+
+  return {
+    signals: [...new Set(signals)],
+    toolSignals: [...new Set(toolSignals.filter(hasSignalPattern))],
+    commandSignals: [...new Set(commandSignals.filter(hasSignalPattern))]
+  };
+}
+
+function walk(value, path, onText) {
+  if (value == null) return;
+  if (typeof value === "string") {
+    const text = value.length > MAX_TEXT_LENGTH ? value.slice(0, MAX_TEXT_LENGTH) : value;
+    onText(path, text);
+    return;
+  }
+  if (typeof value !== "object") return;
+  if (Array.isArray(value)) {
+    value.slice(0, 100).forEach((item, index) => walk(item, [...path, String(index)], onText));
+    return;
+  }
+  for (const [key, item] of Object.entries(value).slice(0, 100)) {
+    walk(item, [...path, key], onText);
+  }
+}
+
+function hasSignalPattern(value) {
+  return SIGNAL_PATTERNS.some((pattern) => pattern.test(String(value || "")));
+}

package/plugins/ctx/lib/workspace-data.js

@@ -0,0 +1,83 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+const MARKER_DIR = ".contextos";
+const MARKER_FILE = "workspace.json";
+const IGNORE_ENTRY = ".contextos/";
+
+export function defaultDataRoot() {
+  return process.env.PLUGIN_DATA
+    || process.env.CONTEXTOS_HOME
+    || path.join(os.homedir(), ".ctx", "contextos");
+}
+
+export function workspaceDataDir({ cwd = process.cwd(), dataRoot = defaultDataRoot(), createMarker = true } = {}) {
+  const id = workspaceId({ cwd, createMarker });
+  const dir = path.join(dataRoot, "workspaces", id);
+  fs.mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+export function workspaceId({ cwd = process.cwd(), createMarker = true } = {}) {
+  const root = resolveWorkspaceRoot(cwd);
+  const markerPath = path.join(root, MARKER_DIR, MARKER_FILE);
+  const existing = readMarker(markerPath);
+  if (existing?.id) return existing.id;
+
+  const id = deterministicWorkspaceId(root);
+  if (createMarker) writeMarker({ root, markerPath, id });
+  return id;
+}
+
+export function resolveWorkspaceRoot(cwd = process.cwd()) {
+  try {
+    return fs.realpathSync(cwd);
+  } catch {
+    return path.resolve(cwd);
+  }
+}
+
+export function workspaceMarkerPath(cwd = process.cwd()) {
+  return path.join(resolveWorkspaceRoot(cwd), MARKER_DIR, MARKER_FILE);
+}
+
+function deterministicWorkspaceId(root) {
+  const base = path.basename(root) || "workspace";
+  const slug = base.toLowerCase().replace(/[^a-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "") || "workspace";
+  const hash = crypto.createHash("sha256").update(root).digest("hex").slice(0, 12);
+  return `${slug}-${hash}`;
+}
+
+function readMarker(markerPath) {
+  try {
+    return JSON.parse(fs.readFileSync(markerPath, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function writeMarker({ root, markerPath, id }) {
+  try {
+    fs.mkdirSync(path.dirname(markerPath), { recursive: true });
+    fs.writeFileSync(markerPath, `${JSON.stringify({ id, root }, null, 2)}\n`, "utf8");
+    ensureGitignore(root);
+  } catch {
+    // Marker files are only for stable local identity; deterministic ids still work.
+  }
+}
+
+function ensureGitignore(root) {
+  const gitignorePath = path.join(root, ".gitignore");
+  let content = "";
+  try {
+    content = fs.readFileSync(gitignorePath, "utf8");
+  } catch {
+    // Missing .gitignore is fine; create one below.
+  }
+  const lines = content.split(/\r?\n/).map((line) => line.trim());
+  if (lines.includes(IGNORE_ENTRY)) return;
+  const prefix = content && !content.endsWith("\n") ? "\n" : "";
+  fs.appendFileSync(gitignorePath, `${prefix}${IGNORE_ENTRY}\n`, "utf8");
+}

package/plugins/ctx/mcp/server.js

@@ -1,17 +1,16 @@
 #!/usr/bin/env node
 import fs from "node:fs";
 import net from "node:net";
-import os from "node:os";
-import path from "node:path";
 
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 
 import { modelCacheDir, warmRuleEmbeddings } from "../lib/embedding-scorer.js";
 import { scoreContext } from "../lib/score-context.js";
 import { ctxMcpSocketPath } from "../lib/ctx-mcp-client.js";
+import { defaultDataRoot } from "../lib/workspace-data.js";
 import { createContextOSMcpServer } from "./contextos-server.js";
 
-const dataDir = process.env.PLUGIN_DATA || path.join(process.env.CODEX_HOME || path.join(os.homedir(), ".codex"), "contextos");
+const dataDir = defaultDataRoot();
 const socketPath = ctxMcpSocketPath(dataDir);
 
 fs.mkdirSync(dataDir, { recursive: true });