mindgraph-mcp 0.14.6 → 0.14.8

package/README.md

@@ -3,7 +3,7 @@
 [![npm](https://img.shields.io/npm/v/mindgraph-mcp)](https://www.npmjs.com/package/mindgraph-mcp)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 
-Model Context Protocol server for [MindGraph](https://mindgraph.cloud) — plug your persistent, structured knowledge graph into Claude Desktop, Claude Code, and any MCP-compatible client.
+Model Context Protocol server for [MindGraph](https://mindgraph.cloud) — plug your persistent, structured knowledge graph into Claude Desktop, Claude Code, Codex, and any MCP-compatible client.
 
 ## Install
 
@@ -77,7 +77,10 @@ which state you're in).
 
 The hooks open/rebind a Session at start and inject the current work brief,
 stamp every MindGraph tool call with verified session/repo/commit provenance,
-and prompt one reflection checkpoint before a substantial session ends. They
+and prompt one reflection checkpoint before a substantial session ends. A
+session automatically re-claims only *this* agent's own prior work; other
+tasks appear in the brief as context, and the agent claims one deliberately
+when it starts that work. They
 **fail open** — if MindGraph is unreachable, your coding session is never
 blocked. `--scope project` (with `--project-dir`) installs into a single
 repository's `.claude/settings.json` instead; `uninstall-hooks` reverses either
@@ -87,18 +90,36 @@ project settings.
 
 ### Coding agents (Codex)
 
-The server is harness-neutral — Codex gets the full coding tool surface today:
+Codex gets the same durable work substrate through its native command hooks.
+Register the MCP server with a distinct agent identity, then install the hooks:
 
 ```bash
 codex mcp add mindgraph --env MINDGRAPH_API_KEY=mg_your_key_here \
   --env MINDGRAPH_PROFILE=coding --env MINDGRAPH_HARNESS=codex \
+  --env MINDGRAPH_AGENT_ID=codex:your-name \
   -- npx -y mindgraph-mcp@latest
+
+npx -y mindgraph-mcp install-hooks --harness codex --scope user \
+  --api-key mg_your_key_here --agent-id codex:your-name
 ```
 
 (or the equivalent `[mcp_servers.mindgraph]` block in Codex's `config.toml`).
-The hooks adapter for Codex — automatic session lifecycle and brief injection —
-is planned; until then, ask the agent to call `mindgraph_plan resume_work` at
-the start of a session.
+The installer copies the pinned self-contained runner to
+`~/.mindgraph/bin/mindgraph-hook.cjs`, merge-safely upserts only entries marked
+`--owner mindgraph`, and writes user hooks to `$CODEX_HOME/hooks.json`
+(`~/.codex/hooks.json` by default). Use `--scope project --project-dir …` for
+`<project>/.codex/hooks.json`. Re-run the install command to refresh owned
+entries; foreign hooks are never changed. Codex requires newly installed or
+changed command hooks to be reviewed with `/hooks` before they run.
+
+At SessionStart the adapter opens/rebinds the graph Session and injects one
+bounded work brief, re-claiming only this agent's own prior work.
+PreToolUse replaces forged/absent invocation provenance
+while preserving model-selected work targets, PostToolUse updates only the
+disposable runtime ledger, Stop runs the once-per-session reflection
+checkpoint, and SessionEnd performs best-effort cleanup. All paths fail open:
+missing credentials or an unreachable MindGraph return Codex's no-op response
+and never block the coding session.
 
 ## What You Get
 
@@ -146,7 +167,7 @@ mindgraph-mcp install          Install into Claude Desktop config
 mindgraph-mcp install-code     Install into Claude Code (--hooks: also install session hooks)
 mindgraph-mcp uninstall        Remove from Claude Desktop config
 mindgraph-mcp uninstall-code   Remove from Claude Code
-mindgraph-mcp install-hooks    Install Claude Code hooks (--harness claude-code)
+mindgraph-mcp install-hooks    Install coding hooks (--harness claude-code|codex)
 mindgraph-mcp uninstall-hooks  Remove MindGraph-owned hook entries
 mindgraph-mcp status           Show installation status
 ```

package/dist/cli.js

@@ -2891,6 +2891,7 @@ async function handleRetrieve(client2, args) {
     limit,
     offset,
     include_chunks,
+    include_documents,
     include_graph,
     graph_expansion_limit,
     graph_max_depth,
@@ -2908,6 +2909,10 @@ async function handleRetrieve(client2, args) {
           node_types,
           layer,
           chunk_limit: include_chunks ? limit ?? 5 : 0,
+          // Scoped by default, never walled: the coding profile drops the
+          // document/article leg (the "Bob Work" class of noise) unless the
+          // model opts in for a genuinely document-shaped question.
+          ...process.env.MINDGRAPH_PROFILE === "coding" && !include_documents ? { article_limit: 0 } : {},
           include_graph,
           graph_expansion_limit: graph_expansion_limit ?? 3,
           graph_max_depth: graph_max_depth ?? 2
@@ -3940,6 +3945,10 @@ var init_tools = __esm({
               type: "number",
               description: "Pagination offset (for stale_derivations)"
             },
+            include_documents: {
+              type: "boolean",
+              description: "Include ingested documents and wiki articles in context results. The coding profile defaults these OFF so engineering questions aren't answered from unrelated ingested content; pass true when the question is about a document, spec, or article."
+            },
             include_chunks: {
               type: "boolean",
               description: "Include source document chunks in context results (default: false \u2014 set true to fetch full chunk text for citations or deep reading)"
@@ -4908,7 +4917,7 @@ Capture knowledge when the user shares something worth remembering:
     server = new import_server.Server(
       {
         name: "mindgraph",
-        version: "0.14.6"
+        version: "0.14.8"
       },
       {
         capabilities: {
@@ -5173,7 +5182,7 @@ function saveHookEnv(env, dir) {
 // src/cli-args.ts
 function parseArgs(argv) {
   const args = argv.slice(2);
-  let command = "serve";
+  let command2 = "serve";
   let apiKey = process.env.MINDGRAPH_API_KEY;
   let baseUrl = process.env.MINDGRAPH_BASE_URL;
   let scope = "project";
@@ -5215,16 +5224,16 @@ function parseArgs(argv) {
         break;
       case "--help":
       case "-h":
-        command = "help";
+        command2 = "help";
         break;
       default:
         if (!arg.startsWith("-")) {
-          command = arg;
+          command2 = arg;
         }
         break;
     }
   }
-  return { command, apiKey, baseUrl, scope, projectDir, harness, hooks, agentId };
+  return { command: command2, apiKey, baseUrl, scope, projectDir, harness, hooks, agentId };
 }
 function mcpAddFailureOutput(e) {
   const err5 = e;
@@ -5238,16 +5247,17 @@ function classifyMcpAddFailure(e) {
   return "other";
 }
 
-// src/claude-hooks.ts
+// src/hook-core.ts
 var import_node_crypto2 = __toESM(require("crypto"));
 var import_node_fs3 = __toESM(require("fs"));
 var import_node_os3 = __toESM(require("os"));
 var import_node_path3 = __toESM(require("path"));
 var import_node_child_process2 = require("child_process");
 init_codegraph();
-function defaultLedger(sessionId) {
+var NOOP = { kind: "noop" };
+function defaultLedger(sessionId, options) {
   return {
-    harness: "claude-code",
+    harness: options.harness,
     harnessSessionId: sessionId,
     materialToolCalls: 0,
     mutatingOperations: 0,
@@ -5264,7 +5274,8 @@ function runtimeDir(options) {
   return options.runtimeDir || process.env.MINDGRAPH_RUNTIME_DIR || import_node_path3.default.join(import_node_os3.default.homedir(), ".mindgraph", "runtime");
 }
 function ledgerPath(sessionId, options) {
-  const key = import_node_crypto2.default.createHash("sha256").update(`claude-code\0${sessionId}`).digest("hex");
+  const harness = "harness" in options ? options.harness : "claude-code";
+  const key = import_node_crypto2.default.createHash("sha256").update(`${harness}\0${sessionId}`).digest("hex");
   return import_node_path3.default.join(runtimeDir(options), `${key}.json`);
 }
 function waitBriefly(ms) {
@@ -5293,10 +5304,10 @@ function withLedger(sessionId, options, update) {
     }
   }
   if (lockFd === void 0) {
-    return update(defaultLedger(sessionId));
+    return update(defaultLedger(sessionId, options));
   }
   try {
-    let ledger = defaultLedger(sessionId);
+    let ledger = defaultLedger(sessionId, options);
     try {
       ledger = {
         ...ledger,
@@ -5347,8 +5358,9 @@ async function invocationContext(input, options) {
     workspaceFile: options.workspaceFile
   }).resolveRepository();
   return {
-    harness: "claude-code",
+    harness: options.harness,
     harnessSessionId: input.session_id,
+    harnessTurnId: input.turn_id,
     cwd: input.cwd,
     repoId: repository.repoId,
     branch: gitValue(input.cwd, ["branch", "--show-current"]),
@@ -5425,13 +5437,21 @@ async function repositoryScopeUids(input, client2, options, agentId) {
     )
   ];
 }
+function isOwnPriorWork(brief, agentId) {
+  const reason = string(brief?.selection_reason);
+  if (reason === "owned_live_lease" || reason === "same_agent_session_rebind") {
+    return true;
+  }
+  return string(object(brief?.lease)?.lease_owner_agent_id) === agentId;
+}
 async function sessionStart(input, client2, options) {
-  const agentId = options.agentId || process.env.MINDGRAPH_AGENT_ID || "claude-code";
+  const agentId = options.agentId || process.env.MINDGRAPH_AGENT_ID || options.harness;
+  const harnessLabel = options.harness === "claude-code" ? "Claude Code" : "Codex";
   const opened = object(
     await client2.session({
       action: "open",
-      label: `Claude Code ${input.session_id}`,
-      harness: "claude-code",
+      label: `${harnessLabel} ${input.session_id}`,
+      harness: options.harness,
       harness_session_id: input.session_id,
       model: input.model,
       agent_id: agentId
@@ -5449,7 +5469,7 @@ async function sessionStart(input, client2, options) {
   );
   const task = object(brief?.task);
   const lease = object(brief?.lease);
-  if (sessionUid && string(task?.uid) && number(task?.version)) {
+  if (sessionUid && string(task?.uid) && number(task?.version) && isOwnPriorWork(brief, agentId)) {
     try {
       const claimed = object(
         await client2.plan({
@@ -5474,7 +5494,11 @@ async function sessionStart(input, client2, options) {
     } catch {
     }
   }
-  withLedger(input.session_id, options, (ledger) => {
+  const briefText = boundedBrief(brief || { status: "no_eligible_work" });
+  const briefHash = import_node_crypto2.default.createHash("sha256").update(briefText).digest("hex");
+  const shouldInject = withLedger(input.session_id, options, (ledger) => {
+    const changed = ledger.lastBriefHash !== briefHash;
+    const reinjectCompact = options.reinjectUnchangedCompact && input.source === "compact";
     ledger.sessionUid = sessionUid;
     ledger.baselineWorktree = worktreeState(input.cwd);
     const selectedTask = object(brief?.task);
@@ -5486,14 +5510,10 @@ async function sessionStart(input, client2, options) {
     ledger.leaseEpoch = number(selectedLease?.lease_epoch);
     ledger.leaseExpiresAt = number(selectedLease?.lease_expires_at);
     ledger.executionUid = string(object(brief?.active_execution)?.uid) || string(latest?.uid);
-    return void 0;
+    ledger.lastBriefHash = briefHash;
+    return changed || reinjectCompact;
   });
-  return {
-    hookSpecificOutput: {
-      hookEventName: "SessionStart",
-      additionalContext: boundedBrief(brief || { status: "no_eligible_work" })
-    }
-  };
+  return shouldInject ? { kind: "context", context: briefText } : NOOP;
 }
 async function preTool(input, options) {
   const original = { ...input.tool_input || {} };
@@ -5518,12 +5538,7 @@ async function preTool(input, options) {
   if (ledger.taskVersion !== void 0 && updatedInput.expected_version === void 0) {
     updatedInput.expected_version = ledger.taskVersion;
   }
-  return {
-    hookSpecificOutput: {
-      hookEventName: "PreToolUse",
-      updatedInput
-    }
-  };
+  return { kind: "rewrite", updatedInput };
 }
 async function postTool(input, client2, options) {
   const name = input.tool_name || "";
@@ -5534,7 +5549,7 @@ async function postTool(input, client2, options) {
   let heartbeat;
   withLedger(input.session_id, options, (ledger) => {
     ledger.materialToolCalls += 1;
-    if (["Edit", "Write", "NotebookEdit"].includes(name) || name === "Bash" && action !== "read") {
+    if (["Edit", "Write", "NotebookEdit", "apply_patch"].includes(name) || name === "Bash" && action !== "read") {
       ledger.mutatingOperations += 1;
     }
     if (name.includes("mindgraph_capture") && !payload?.error) {
@@ -5574,7 +5589,7 @@ async function postTool(input, client2, options) {
           expected_version: heartbeat.taskVersion,
           lease_epoch: heartbeat.leaseEpoch,
           idempotency_key: `hook-heartbeat:${input.session_id}:${heartbeat.taskUid}:${Math.floor(nowSeconds / 60)}`,
-          agent_id: options.agentId || "claude-code"
+          agent_id: options.agentId || options.harness
         })
       );
       withLedger(input.session_id, options, (ledger) => {
@@ -5584,24 +5599,25 @@ async function postTool(input, client2, options) {
     } catch {
     }
   }
-  return {};
+  return NOOP;
 }
 function stop(input, options) {
-  if (input.stop_hook_active) return {};
+  if (input.stop_hook_active) return NOOP;
   return withLedger(input.session_id, options, (ledger) => {
     const changed = ledger.mutatingOperations >= 2 || ledger.baselineWorktree !== "unknown" && worktreeState(input.cwd) !== ledger.baselineWorktree;
     const substantial = Boolean(ledger.executionUid) || changed;
     if (!substantial || ledger.iterationCheckpointed || ledger.memoryWritten || ledger.stopNudged) {
-      return {};
+      return NOOP;
     }
     ledger.stopNudged = true;
     return {
-      decision: "block",
+      kind: "block",
       reason: "Substantial work is still uncheckpointed. Checkpoint the active iteration, capture one durable lesson/decision/risk, or explicitly state that nothing durable changed. If a local harness task should become authoritative outside this list, promote it once with a stable idempotency key; otherwise do not copy it."
     };
   });
 }
 async function sessionEnd(input, client2, options) {
+  const harnessLabel = options.harness === "claude-code" ? "Claude Code" : "Codex";
   const ledger = readLedger(input.session_id, options);
   if (ledger.executionUid && ledger.taskUid && ledger.sessionUid && ledger.taskVersion !== void 0 && ledger.leaseEpoch !== void 0) {
     try {
@@ -5613,9 +5629,9 @@ async function sessionEnd(input, client2, options) {
         expected_version: ledger.taskVersion,
         lease_epoch: ledger.leaseEpoch,
         release_lease: true,
-        summary: `Claude Code SessionEnd: ${input.reason || "interrupted"}`,
+        summary: `${harnessLabel} SessionEnd: ${input.reason || "interrupted"}`,
         idempotency_key: `session-end:${input.session_id}:${ledger.executionUid}`,
-        agent_id: options.agentId || "claude-code"
+        agent_id: options.agentId || options.harness
       });
     } catch {
     }
@@ -5625,19 +5641,19 @@ async function sessionEnd(input, client2, options) {
       await client2.session({
         action: "close",
         session_uid: ledger.sessionUid,
-        agent_id: options.agentId || "claude-code"
+        agent_id: options.agentId || options.harness
       });
     } catch {
     }
   }
-  return {};
+  return NOOP;
 }
-async function runClaudeHook(input, client2, options = {}) {
+async function runHookCore(input, client2, options) {
   switch (input.hook_event_name) {
     case "SessionStart":
       return sessionStart(input, client2, options);
     case "PreToolUse":
-      if (!input.tool_name?.startsWith("mcp__mindgraph__")) return {};
+      if (!input.tool_name?.startsWith("mcp__mindgraph__")) return NOOP;
       return preTool(input, options);
     case "PostToolUse":
       return postTool(input, client2, options);
@@ -5646,19 +5662,19 @@ async function runClaudeHook(input, client2, options = {}) {
         ledger.nativeTasksCreated += 1;
         return void 0;
       });
-      return {};
+      return NOOP;
     case "TaskCompleted":
       withLedger(input.session_id, options, (ledger) => {
         ledger.nativeTasksTerminal += 1;
         return void 0;
       });
-      return {};
+      return NOOP;
     case "Stop":
       return stop(input, options);
     case "SessionEnd":
       return sessionEnd(input, client2, options);
     default:
-      return {};
+      return NOOP;
   }
 }
 async function readHookInput(stream = process.stdin) {
@@ -5669,6 +5685,68 @@ async function readHookInput(stream = process.stdin) {
   return JSON.parse(Buffer.concat(chunks).toString("utf8"));
 }
 
+// src/claude-hooks.ts
+async function runClaudeHook(input, client2, options = {}) {
+  const output = await runHookCore(input, client2, {
+    ...options,
+    harness: "claude-code",
+    // D10: compaction is a new Claude context boundary, so the same brief must
+    // be re-injected even when its content hash is unchanged.
+    reinjectUnchangedCompact: true
+  });
+  switch (output.kind) {
+    case "context":
+      return {
+        hookSpecificOutput: {
+          hookEventName: "SessionStart",
+          additionalContext: output.context
+        }
+      };
+    case "rewrite":
+      return {
+        hookSpecificOutput: {
+          hookEventName: "PreToolUse",
+          updatedInput: output.updatedInput
+        }
+      };
+    case "block":
+      return { decision: "block", reason: output.reason };
+    case "noop":
+      return {};
+  }
+}
+
+// src/codex-hooks.ts
+async function runCodexHook(input, client2, options = {}) {
+  const output = await runHookCore(input, client2, {
+    ...options,
+    harness: "codex",
+    // B7's native contract suppresses repeated unchanged brief injections.
+    reinjectUnchangedCompact: false
+  });
+  switch (output.kind) {
+    case "context":
+      return {
+        hookSpecificOutput: {
+          hookEventName: "SessionStart",
+          additionalContext: output.context
+        }
+      };
+    case "rewrite":
+      return {
+        hookSpecificOutput: {
+          hookEventName: "PreToolUse",
+          permissionDecision: "allow",
+          updatedInput: output.updatedInput
+        }
+      };
+    case "block":
+      return { decision: "block", reason: output.reason };
+    case "noop":
+      return {};
+  }
+}
+
 // src/hook-installer.ts
 var import_node_fs4 = __toESM(require("fs"));
 var import_node_os4 = __toESM(require("os"));
@@ -5676,59 +5754,78 @@ var import_node_path4 = __toESM(require("path"));
 var import_node_crypto3 = __toESM(require("crypto"));
 var OWNER_MARKER = "--owner mindgraph";
 var RUNNER_RELATIVE = ".mindgraph/bin/mindgraph-hook.cjs";
-var COMMAND = `node "$HOME/${RUNNER_RELATIVE}" hook --harness claude-code --owner mindgraph`;
+function command(harness) {
+  return `node "$HOME/${RUNNER_RELATIVE}" hook --harness ${harness} --owner mindgraph`;
+}
+function windowsCommand(harness) {
+  return `node "%USERPROFILE%\\.mindgraph\\bin\\mindgraph-hook.cjs" hook --harness ${harness} --owner mindgraph`;
+}
 function installHookRunner(sourceFile, homeDir) {
   const target = import_node_path4.default.join(homeDir || import_node_os4.default.homedir(), RUNNER_RELATIVE);
   import_node_fs4.default.mkdirSync(import_node_path4.default.dirname(target), { recursive: true });
   import_node_fs4.default.copyFileSync(sourceFile, target);
   return target;
 }
-function uninstallHookRunner(homeDir) {
-  try {
-    import_node_fs4.default.rmSync(import_node_path4.default.join(homeDir || import_node_os4.default.homedir(), RUNNER_RELATIVE));
-  } catch {
+function settingsPath(harness, scope, projectDir = process.cwd(), codexHomeDir = process.env.CODEX_HOME || import_node_path4.default.join(import_node_os4.default.homedir(), ".codex")) {
+  if (harness === "codex") {
+    return scope === "user" ? import_node_path4.default.join(codexHomeDir, "hooks.json") : import_node_path4.default.join(projectDir, ".codex", "hooks.json");
   }
-}
-function settingsPath(scope, projectDir = process.cwd()) {
   return scope === "user" ? import_node_path4.default.join(import_node_os4.default.homedir(), ".claude", "settings.json") : import_node_path4.default.join(projectDir, ".claude", "settings.json");
 }
 function readSettings(file) {
   if (!import_node_fs4.default.existsSync(file)) return {};
   return JSON.parse(import_node_fs4.default.readFileSync(file, "utf8"));
 }
-function ownedHook(timeout) {
+function ownedHook(harness, timeout, additionalContextLimit) {
   return {
     type: "command",
-    command: COMMAND,
+    command: command(harness),
+    ...harness === "codex" ? { commandWindows: windowsCommand(harness) } : {},
     timeout,
-    statusMessage: "Syncing MindGraph session context"
+    statusMessage: "Syncing MindGraph session context",
+    ...additionalContextLimit === void 0 ? {} : { additionalContextLimit }
   };
 }
-function desiredEntries() {
-  return {
+function desiredEntries(harness) {
+  const common = {
     SessionStart: [
       {
-        matcher: "startup|resume|clear|compact|fork",
-        hooks: [ownedHook(20)]
+        matcher: harness === "claude-code" ? "startup|resume|clear|compact|fork" : "startup|resume|clear|compact",
+        // B7 live acceptance caught cold SessionStart calls crossing the
+        // inherited 20s edge in both harnesses: the hooks correctly failed
+        // open, but no brief reached the model. The same installed runner
+        // completed in 16.84s once warm. Keep a 30s cold-tenant margin.
+        hooks: [
+          ownedHook(
+            harness,
+            30,
+            harness === "codex" ? 3e3 : void 0
+          )
+        ]
       }
     ],
     PreToolUse: [
       {
         matcher: "mcp__mindgraph__.*",
-        hooks: [ownedHook(3)]
+        hooks: [ownedHook(harness, 3)]
       }
     ],
-    PostToolUse: [{ matcher: ".*", hooks: [ownedHook(5)] }],
-    TaskCreated: [{ hooks: [ownedHook(3)] }],
-    TaskCompleted: [{ hooks: [ownedHook(3)] }],
-    Stop: [{ hooks: [ownedHook(5)] }],
-    SessionEnd: [{ hooks: [ownedHook(8)] }]
+    PostToolUse: [{ matcher: ".*", hooks: [ownedHook(harness, 5)] }],
+    Stop: [{ hooks: [ownedHook(harness, 5)] }],
+    SessionEnd: [
+      { hooks: [ownedHook(harness, harness === "codex" ? 3 : 8)] }
+    ]
   };
+  return harness === "claude-code" ? {
+    ...common,
+    TaskCreated: [{ hooks: [ownedHook(harness, 3)] }],
+    TaskCompleted: [{ hooks: [ownedHook(harness, 3)] }]
+  } : common;
 }
 function hookCommand(value) {
   if (!value || typeof value !== "object" || Array.isArray(value)) return void 0;
-  const command = value.command;
-  return typeof command === "string" ? command : void 0;
+  const command2 = value.command;
+  return typeof command2 === "string" ? command2 : void 0;
 }
 function entryHasOwnedHook(value) {
   if (!value || typeof value !== "object" || Array.isArray(value)) return false;
@@ -5744,13 +5841,13 @@ function writeSettings(file, settings) {
   });
   import_node_fs4.default.renameSync(temporary, file);
 }
-function installClaudeHooks(scope, projectDir = process.cwd()) {
-  const file = settingsPath(scope, projectDir);
+function installHooks(harness, scope, projectDir = process.cwd(), codexHomeDir) {
+  const file = settingsPath(harness, scope, projectDir, codexHomeDir);
   const settings = readSettings(file);
   const hooks = settings.hooks && typeof settings.hooks === "object" && !Array.isArray(settings.hooks) ? settings.hooks : {};
   let added = 0;
   let updated = 0;
-  for (const [event, wanted] of Object.entries(desiredEntries())) {
+  for (const [event, wanted] of Object.entries(desiredEntries(harness))) {
     const current = Array.isArray(hooks[event]) ? [...hooks[event]] : [];
     const kept = current.filter((entry) => !entryHasOwnedHook(entry));
     const hadOwned = kept.length !== current.length;
@@ -5765,8 +5862,8 @@ function installClaudeHooks(scope, projectDir = process.cwd()) {
   writeSettings(file, settings);
   return { path: file, added, updated };
 }
-function uninstallClaudeHooks(scope, projectDir = process.cwd()) {
-  const file = settingsPath(scope, projectDir);
+function uninstallHooks(harness, scope, projectDir = process.cwd(), codexHomeDir) {
+  const file = settingsPath(harness, scope, projectDir, codexHomeDir);
   if (!import_node_fs4.default.existsSync(file)) return { path: file, removed: 0 };
   const settings = readSettings(file);
   const hooks = settings.hooks && typeof settings.hooks === "object" && !Array.isArray(settings.hooks) ? settings.hooks : {};
@@ -5801,6 +5898,18 @@ function uninstallClaudeHooks(scope, projectDir = process.cwd()) {
   writeSettings(file, settings);
   return { path: file, removed };
 }
+function installClaudeHooks(scope, projectDir = process.cwd()) {
+  return installHooks("claude-code", scope, projectDir);
+}
+function uninstallClaudeHooks(scope, projectDir = process.cwd()) {
+  return uninstallHooks("claude-code", scope, projectDir);
+}
+function installCodexHooks(scope, projectDir = process.cwd(), codexHomeDir) {
+  return installHooks("codex", scope, projectDir, codexHomeDir);
+}
+function uninstallCodexHooks(scope, projectDir = process.cwd(), codexHomeDir) {
+  return uninstallHooks("codex", scope, projectDir, codexHomeDir);
+}
 
 // src/cli.ts
 function getClaudeDesktopConfigPath() {
@@ -6010,8 +6119,8 @@ USAGE:
   mindgraph-mcp install-code     Install into Claude Code (--hooks: + session hooks)
   mindgraph-mcp uninstall        Remove from Claude Desktop config
   mindgraph-mcp uninstall-code   Remove from Claude Code
-  mindgraph-mcp install-hooks --harness claude-code [--scope user|project]
-  mindgraph-mcp uninstall-hooks --harness claude-code [--scope user|project]
+  mindgraph-mcp install-hooks --harness claude-code|codex [--scope user|project]
+  mindgraph-mcp uninstall-hooks --harness claude-code|codex [--scope user|project]
   mindgraph-mcp status           Show installation status
 
 OPTIONS:
@@ -6019,7 +6128,7 @@ OPTIONS:
   --base-url <url>    Custom API base URL (default: https://api.mindgraph.cloud)
   --scope <scope>     Hook settings scope: project (default) or user
   --project-dir <dir> Project root for project-scoped hooks
-  --harness <name>    Hook harness (currently claude-code)
+  --harness <name>    Hook harness (claude-code or codex)
   --help, -h          Show this help message
 
 EXAMPLES:
@@ -6157,8 +6266,8 @@ async function interactiveInit(baseUrl) {
   console.log("\nDone! Your knowledge graph is now connected.");
 }
 async function main2() {
-  const { command, apiKey, baseUrl, scope, projectDir, harness, hooks, agentId } = parseArgs(process.argv);
-  switch (command) {
+  const { command: command2, apiKey, baseUrl, scope, projectDir, harness, hooks, agentId } = parseArgs(process.argv);
+  switch (command2) {
     case "help":
       printUsage();
       break;
@@ -6191,14 +6300,15 @@ async function main2() {
       uninstallClaudeCode();
       break;
     case "install-hooks": {
-      if ((harness || "claude-code") !== "claude-code") {
-        throw new Error("only --harness claude-code is available in this release");
+      const hookHarness = harness || "claude-code";
+      if (hookHarness !== "claude-code" && hookHarness !== "codex") {
+        throw new Error("--harness must be claude-code or codex");
       }
       const runner = installHookRunner(__filename);
       console.log(`Installed pinned hook runner at ${runner}`);
-      const result = installClaudeHooks(scope, projectDir);
+      const result = hookHarness === "codex" ? installCodexHooks(scope, projectDir) : installClaudeHooks(scope, projectDir);
       console.log(
-        `Installed ${result.added} and refreshed ${result.updated} MindGraph Claude Code hook entries in ${result.path}`
+        `Installed ${result.added} and refreshed ${result.updated} MindGraph ${hookHarness === "codex" ? "Codex" : "Claude Code"} hook entries in ${result.path}`
       );
       printCodegraphStatus();
       if (apiKey || baseUrl || agentId) {
@@ -6212,18 +6322,22 @@ async function main2() {
       break;
     }
     case "uninstall-hooks": {
-      if ((harness || "claude-code") !== "claude-code") {
-        throw new Error("only --harness claude-code is available in this release");
+      const hookHarness = harness || "claude-code";
+      if (hookHarness !== "claude-code" && hookHarness !== "codex") {
+        throw new Error("--harness must be claude-code or codex");
       }
-      uninstallHookRunner();
-      const result = uninstallClaudeHooks(scope, projectDir);
+      const result = hookHarness === "codex" ? uninstallCodexHooks(scope, projectDir) : uninstallClaudeHooks(scope, projectDir);
       console.log(
-        `Removed ${result.removed} MindGraph Claude Code hooks from ${result.path}`
+        `Removed ${result.removed} MindGraph ${hookHarness === "codex" ? "Codex" : "Claude Code"} hooks from ${result.path}`
       );
       break;
     }
     case "hook": {
       const stored = loadHookEnv();
+      const hookHarness = harness || "claude-code";
+      if (hookHarness !== "claude-code" && hookHarness !== "codex") {
+        throw new Error("--harness must be claude-code or codex");
+      }
       const hookApiKey = apiKey ?? stored.apiKey;
       const hookBaseUrl = baseUrl ?? stored.baseUrl;
       if (!hookApiKey) {
@@ -6239,9 +6353,18 @@ async function main2() {
           maxRetries: 0,
           telemetrySurface: "mcp"
         });
-        const output = await runClaudeHook(input, client2, {
-          agentId: process.env.MINDGRAPH_AGENT_ID || stored.agentId || "claude-code"
-        });
+        const hookOptions = {
+          agentId: process.env.MINDGRAPH_AGENT_ID || stored.agentId || hookHarness
+        };
+        const output = hookHarness === "codex" ? await runCodexHook(
+          input,
+          client2,
+          hookOptions
+        ) : await runClaudeHook(
+          input,
+          client2,
+          hookOptions
+        );
         process.stdout.write(`${JSON.stringify(output)}
 `);
       } catch {
@@ -6257,7 +6380,7 @@ async function main2() {
       break;
     }
     default:
-      console.error(`Unknown command: ${command}`);
+      console.error(`Unknown command: ${command2}`);
       printUsage();
       process.exit(1);
   }

package/dist/index.js

@@ -2060,6 +2060,10 @@ var TOOLS = [
           type: "number",
           description: "Pagination offset (for stale_derivations)"
         },
+        include_documents: {
+          type: "boolean",
+          description: "Include ingested documents and wiki articles in context results. The coding profile defaults these OFF so engineering questions aren't answered from unrelated ingested content; pass true when the question is about a document, spec, or article."
+        },
         include_chunks: {
           type: "boolean",
           description: "Include source document chunks in context results (default: false \u2014 set true to fetch full chunk text for citations or deep reading)"
@@ -2923,6 +2927,7 @@ async function handleRetrieve(client2, args) {
     limit,
     offset,
     include_chunks,
+    include_documents,
     include_graph,
     graph_expansion_limit,
     graph_max_depth,
@@ -2940,6 +2945,10 @@ async function handleRetrieve(client2, args) {
           node_types,
           layer,
           chunk_limit: include_chunks ? limit ?? 5 : 0,
+          // Scoped by default, never walled: the coding profile drops the
+          // document/article leg (the "Bob Work" class of noise) unless the
+          // model opts in for a genuinely document-shaped question.
+          ...process.env.MINDGRAPH_PROFILE === "coding" && !include_documents ? { article_limit: 0 } : {},
           include_graph,
           graph_expansion_limit: graph_expansion_limit ?? 3,
           graph_max_depth: graph_max_depth ?? 2
@@ -3946,7 +3955,7 @@ if (PROFILE === "coding") {
 var server = new import_server.Server(
   {
     name: "mindgraph",
-    version: "0.14.6"
+    version: "0.14.8"
   },
   {
     capabilities: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mindgraph-mcp",
-  "version": "0.14.6",
+  "version": "0.14.8",
   "description": "MCP server for MindGraph — connect Claude Desktop, Claude Code, and any MCP client to your knowledge graph",
   "repository": {
     "type": "git",