klypix-mcp 1.37.0 → 1.38.0

package/README.md

@@ -20,7 +20,9 @@ Claude Code keeps its live hooks for auto-brief + auto-capture. Codex gets nativ
 tools, **automatic live-session presence**, and approval-free **smart task synchronization**
 from the authorized MCP connection itself. `brain_sync` is a bounded **Context Gateway**:
 one call returns task-relevant brain memory, meaningful active-task peers, structured
-exact-file conflicts, one-time notes, and automatic late-arrival overlap alerts. Idle MCP
+exact-file conflicts, one-time notes, and automatic late-arrival overlap alerts. The
+earlier session gets a best-effort live MCP logging notification within seconds, while
+the same alert remains guaranteed on its next KLYPIX action if its host hides logs. Idle MCP
 connections stay counted for diagnostics but are hidden from the task-peer list. MCP
 server instructions plus a managed Codex `AGENTS.md` block teach Codex to call it at task
 start, when scope changes, and on completion—no Codex hook approval required. Run inside a
@@ -35,8 +37,19 @@ npx klypix-mcp install --codex-hooks
 ```
 
 Codex owns this native layer's security decision and asks the user to review/trust the
-hooks on surfaces that expose hook management. `brain_doctor` reports it separately as
-off, execution-unverified, or active; the approval-free smart layer remains active either way.
+hooks on surfaces that expose hook management. Once trusted, the enhanced layer
+automatically injects bounded task-ranked brain memory on every prompt and warns before
+an exact overlapping file edit. `brain_doctor` reports it separately as off,
+execution-unverified, or active; the approval-free smart layer remains active either way.
+
+Prove the exact installed runtime with two isolated real MCP clients:
+
+```bash
+npx klypix-mcp conformance
+```
+
+The test touches only a temporary fixture. It verifies tool discovery, task memory,
+truthful peers, blocking overlap detection, proactive logging, and guaranteed in-band delivery.
 
 Give a project a brain by dropping a `brain.klypix` in it — the
 [KLYPIX app](https://klypix.com) does it in one click (*Save canvas as project brain*),
@@ -91,7 +104,7 @@ Any MCP client gets the tools and connection-lifecycle presence without host hoo
 If the vault contains `brain.klypix`, that MCP connection also appears as an active
 session. `brain_sync` adds compact task memory, expected-file coordination, task-only peer
 reporting, structured exact-overlap warnings, automatic conflict alerts, timing receipts,
-and one-time peer-note delivery. Then ask your
+best-effort proactive notifications, and guaranteed one-time peer-note delivery. Then ask your
 agent things like *"what did we decide about auth?"*, *"challenge this: let's switch
 to polling"*, or *"turn these notes into a board."*
 
@@ -132,7 +145,7 @@ it, enrich it with intent/files, and remove only their own channel. The TTL cove
 
 Future hosts get baseline support merely by connecting the MCP server. A deeper adapter
 can import `klypix-mcp/presence` and map lifecycle events to `upsertSession`,
-`removeSession`, and `receiveMessages`. The shared contract accepts `id`, `client`,
+`removeSession`, `peekMessages`, and `receiveMessages`. The shared contract accepts `id`, `client`,
 `surface`, `model`, `branch`, `intent`, touched `files`, and adapter `channel`;
 host-specific transcript parsing stays outside the protocol.
 

package/bin/klypix-conformance.mjs

@@ -0,0 +1,189 @@
+#!/usr/bin/env node
+// Self-contained KLYPIX MCP conformance test.
+//
+// Launches two real stdio clients against this exact installed server build,
+// using a temporary brain + isolated presence registry. It verifies the
+// Context Gateway, task memory, truthful task counts, exact overlap detection,
+// proactive MCP logging, and guaranteed next-action delivery without touching
+// the user's project or durable brain.
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { createRequire } from 'module';
+import { fileURLToPath } from 'url';
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
+import { LoggingMessageNotificationSchema } from '@modelcontextprotocol/sdk/types.js';
+import { buildKlypixMap } from '../src/klypix-core.mjs';
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const jsonMode = process.argv.includes('--json');
+const wait = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+const PKG_VERSION = (() => {
+  try { return createRequire(import.meta.url)('../package.json').version; }
+  catch {
+    try {
+      const stamp = JSON.parse(fs.readFileSync(path.join(here, '.brain-version.json'), 'utf8'));
+      return stamp.brainVersion || stamp.appVersion || 'deployed';
+    } catch { return 'deployed'; }
+  }
+})();
+const serverPath = [
+  path.join(here, 'klypix-mcp.mjs'),
+  path.join(here, 'klypix-mcp-server.mjs'),
+].find((candidate) => fs.existsSync(candidate));
+
+if (!serverPath) {
+  console.error('KLYPIX conformance failed: the MCP server executable is missing beside this command.');
+  process.exit(1);
+}
+
+const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'klypix-conformance-'));
+const vault = path.join(tempRoot, 'project');
+const isolatedHome = path.join(tempRoot, 'home');
+fs.mkdirSync(vault, { recursive: true });
+fs.mkdirSync(isolatedHome, { recursive: true });
+fs.writeFileSync(path.join(vault, 'brain.klypix'), await buildKlypixMap({
+  title: 'KLYPIX conformance brain',
+  kind: 'brain',
+  areas: [{
+    title: 'Brain',
+    cards: [{
+      text: 'Codex Context Gateway automatically coordinates active tasks and exact file overlaps across MCP sessions.',
+    }],
+  }],
+}));
+
+const baseEnv = Object.fromEntries(
+  Object.entries(process.env).filter(([, value]) => typeof value === 'string'),
+);
+
+async function connect(name, sessionId) {
+  const logs = [];
+  const transport = new StdioClientTransport({
+    command: process.execPath,
+    args: [serverPath, '--vault', vault],
+    env: {
+      ...baseEnv,
+      USERPROFILE: isolatedHome,
+      HOME: isolatedHome,
+      KLYPIX_SESSION_ID: sessionId,
+      KLYPIX_MCP_INBOX_POLL_MS: '250',
+      KLYPIX_RERANK: '0',
+    },
+    stderr: 'pipe',
+  });
+  const client = new Client({ name, version: '1.0.0' });
+  client.setNotificationHandler(LoggingMessageNotificationSchema, (notification) => {
+    logs.push(String(notification?.params?.data || ''));
+  });
+  await client.connect(transport);
+  await client.setLoggingLevel('info');
+  return { client, transport, logs };
+}
+
+const checks = {};
+const metrics = {};
+let a;
+let b;
+try {
+  a = await connect('codex-klypix-conformance-a', 'klypix-conformance-a');
+  b = await connect('codex-klypix-conformance-b', 'klypix-conformance-b');
+  const tools = await a.client.listTools();
+  checks.brainSyncDiscoverable = tools.tools?.some((tool) => tool.name === 'brain_sync') === true;
+
+  const aStart = await a.client.callTool({
+    name: 'brain_sync',
+    arguments: {
+      phase: 'start',
+      intent: 'Validate automatic Codex Context Gateway coordination',
+      files: ['src/conformance-overlap.ts'],
+    },
+  });
+  const bStart = await b.client.callTool({
+    name: 'brain_sync',
+    arguments: {
+      phase: 'start',
+      intent: 'Validate proactive overlap delivery from a second session',
+      files: ['src/conformance-overlap.ts'],
+    },
+  });
+  const aStructured = aStart.structuredContent || {};
+  const bStructured = bStart.structuredContent || {};
+  checks.taskMemory = Array.isArray(aStructured.context?.hits) && aStructured.context.hits.length > 0;
+  checks.truthfulTaskCount = bStructured.counts?.activeTasks === 2
+    && bStructured.peers?.length === 1;
+  checks.exactBlockingOverlap = bStructured.conflicts?.length === 1
+    && bStructured.conflicts[0]?.kind === 'exact-file'
+    && bStructured.conflicts[0]?.severity === 'blocking';
+  checks.alertQueued = bStructured.alertsQueued?.length === 1;
+  metrics.firstClientMs = aStructured.timingMs?.total ?? null;
+  metrics.secondClientMs = bStructured.timingMs?.total ?? null;
+
+  const pushDeadline = Date.now() + 4_000;
+  while (Date.now() < pushDeadline
+    && !a.logs.some((line) => line.includes('Automatic KLYPIX overlap alert'))) {
+    await wait(100);
+  }
+  checks.proactiveLogging = a.logs.some((line) =>
+    line.includes('Automatic KLYPIX overlap alert'));
+  metrics.firstClientLogCount = a.logs.length;
+  if (!checks.proactiveLogging && a.logs.length) metrics.firstClientLogs = a.logs.slice(-4);
+
+  const aCheckpoint = await a.client.callTool({
+    name: 'brain_sync',
+    arguments: {
+      phase: 'checkpoint',
+      intent: 'Validate automatic Codex Context Gateway coordination',
+      files: ['src/conformance-overlap.ts'],
+    },
+  });
+  const checkpointStructured = aCheckpoint.structuredContent || {};
+  checks.guaranteedInBandDelivery = checkpointStructured.messages?.some((message) =>
+    String(message.text).includes('Automatic KLYPIX overlap alert')) === true;
+
+  await Promise.all([
+    a.client.callTool({ name: 'brain_sync', arguments: { phase: 'complete' } }),
+    b.client.callTool({ name: 'brain_sync', arguments: { phase: 'complete' } }),
+  ]);
+} catch (error) {
+  checks.runtime = false;
+  checks.error = error?.message || String(error);
+} finally {
+  await Promise.allSettled([a?.client?.close(), b?.client?.close()]);
+  fs.rmSync(tempRoot, { recursive: true, force: true });
+}
+
+const required = [
+  'brainSyncDiscoverable',
+  'taskMemory',
+  'truthfulTaskCount',
+  'exactBlockingOverlap',
+  'alertQueued',
+  'proactiveLogging',
+  'guaranteedInBandDelivery',
+];
+const ok = required.every((name) => checks[name] === true);
+const result = {
+  ok,
+  packageVersion: PKG_VERSION,
+  checks,
+  metrics,
+  contract: {
+    proactive: 'best-effort MCP logging notification',
+    guaranteed: 'same alert on the next KLYPIX action',
+  },
+};
+
+if (jsonMode) {
+  process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+} else {
+  console.log(`KLYPIX MCP conformance v${PKG_VERSION}: ${ok ? 'PASS' : 'FAIL'}`);
+  for (const name of required) {
+    console.log(`  ${checks[name] ? '✓' : '✗'} ${name}`);
+  }
+  if (checks.error) console.log(`  error: ${checks.error}`);
+  console.log(`  memory/coordination: ${metrics.firstClientMs ?? '?'}ms / ${metrics.secondClientMs ?? '?'}ms`);
+  console.log('  proactive notifications are best-effort; next-action delivery is guaranteed.');
+}
+process.exit(ok ? 0 : 1);

package/bin/klypix-install.mjs

@@ -276,7 +276,11 @@ try {
     for (const f of ['global-brain-hook.mjs', 'brain-semantic.mjs', 'brain-note.mjs', 'brain-git-hook.mjs', 'klypix-format.mjs', 'klypix-core.mjs', 'agent-rules.mjs', 'brain-doctor.mjs', 'agent-presence.mjs', 'mcp-presence.mjs', 'codex-brain-hook.mjs', 'codex-hooks.mjs', 'canvas-view-app.html']) {
         const s = path.join(SRC, f); if (exists(s)) staged.push({ dst: f, content: fs.readFileSync(s, 'utf8') });
     }
-    for (const [src, dst] of [['klypix-mcp.mjs', 'klypix-mcp-server.mjs'], ['klypix-a2a.mjs', 'klypix-a2a-server.mjs']]) {
+    for (const [src, dst] of [
+        ['klypix-mcp.mjs', 'klypix-mcp-server.mjs'],
+        ['klypix-a2a.mjs', 'klypix-a2a-server.mjs'],
+        ['klypix-conformance.mjs', 'klypix-conformance.mjs'],
+    ]) {
         const s = path.join(BIN, src); if (exists(s)) staged.push({ dst, content: flatten(fs.readFileSync(s, 'utf8')) });
     }
     for (const st of staged) fs.writeFileSync(path.join(BRAIN_DIR, st.dst + '.klypix-new'), st.content);
@@ -344,10 +348,10 @@ try {
     else console.error(`⚠ readiness: ${notWired.length} hook(s) did NOT take (${notWired.join(', ')}) — the brain will read but not capture/sync. Re-run \`npx klypix-mcp install --force\` or check ${SETTINGS}.`);
     console.log(`✓ MCP server runs from the local bundle (node ${fwd(path.join(BRAIN_DIR, 'klypix-mcp-server.mjs'))}) — no npx cache, works offline, always the installed version.`);
     if (migrated) console.log(`✓ migrated ${migrated.file} klypix-canvas server: ${migrated.from} → ${migrated.to} (backup: .mcp.json.klypix-bak). Reconnect (/mcp) or restart to pick it up.`);
-    console.log('  Claude Code keeps its existing auto-brief/capture hooks; Codex gets the brain_sync Context Gateway (compact task memory + clean peers + automatic conflict alerts) with no hook trust prompt.');
-    console.log('  Optional mechanical Codex lifecycle capture: re-run with `--codex-hooks`, then approve/review KLYPIX in a Codex surface that supports hook trust.');
+    console.log('  Claude Code keeps its existing auto-brief/capture hooks; Codex gets the brain_sync Context Gateway (compact task memory + clean peers + proactive/guaranteed conflict alerts) with no hook trust prompt.');
+    console.log('  Enhanced Codex auto-context + pre-edit overlap guard: re-run with `--codex-hooks`, then approve/review KLYPIX once in a Codex surface that supports hook trust.');
     console.log('  ⚠ Open sessions keep their OLD server until relaunched: fully quit & reopen the app (a session resume / new chat does NOT respawn the MCP server). `brain_doctor`\'s RUNNING line confirms when you\'re current.');
-    console.log('  Verify anytime: `npx klypix-mcp doctor` (is the brain current + wired + in sync, who else is live).');
+    console.log('  Verify anytime: `npx klypix-mcp doctor`; prove two-client behavior with `npx klypix-mcp conformance`.');
 } catch (e) {
     if (gotLock) releaseLock();
     console.error(`✗ install failed: ${e?.message || e}`);

package/bin/klypix-mcp.mjs

@@ -57,6 +57,11 @@ if (process.argv[2] === 'link') { await import('./klypix-link.mjs'); process.exi
 // projection in sync? One verdict, one reconcile block. Exits 1 on drift (CI gate).
 if (process.argv[2] === 'doctor') { await import('./klypix-doctor.mjs'); process.exit(0); }
 
+// `npx klypix-mcp conformance` — launch two real, isolated MCP clients against
+// this exact installed server and verify task memory, truthful peers, blocking
+// overlap detection, proactive logging, and guaranteed next-action delivery.
+if (process.argv[2] === 'conformance') { await import('./klypix-conformance.mjs'); process.exit(0); }
+
 // `npx klypix-mcp garden-code` — the HUMAN half of the garden approval gate.
 // brain_garden's apply requires an 8-char code derived from the exact dormant
 // candidate set + day; the agent is deliberately never shown it. The human runs
@@ -106,7 +111,10 @@ const vaultArgIdx = process.argv.indexOf('--vault');
 const VAULT = resolveVault(vaultArgIdx >= 0 ? process.argv[vaultArgIdx + 1] : undefined);
 const server = new McpServer(
   { name: 'klypix-canvas', version: PKG_VERSION },
-  { instructions: KLYPIX_MCP_INSTRUCTIONS },
+  {
+    instructions: KLYPIX_MCP_INSTRUCTIONS,
+    capabilities: { logging: {} },
+  },
 );
 const mcpPresence = createMcpPresence({ server, initialVault: VAULT });
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "klypix-mcp",
-  "version": "1.37.0",
+  "version": "1.38.0",
   "description": "Every project gets a brain — one open .klypix file your AI agents read, write, and argue from, over MCP. Works with Claude, Codex, Cursor, Cline, any model.",
   "type": "module",
   "license": "Apache-2.0",
@@ -26,6 +26,7 @@
   },
   "bin": {
     "klypix-mcp": "bin/klypix-mcp.mjs",
+    "klypix-conformance": "bin/klypix-conformance.mjs",
     "klypix-link": "bin/klypix-link.mjs",
     "klypix-doctor": "bin/klypix-doctor.mjs",
     "klypix-a2a": "bin/klypix-a2a.mjs",
@@ -55,7 +56,7 @@
     "node": ">=18"
   },
   "scripts": {
-    "test": "node test/codex-hooks.mjs && node test/agent-presence.mjs && node test/context-gateway.mjs && node test/brain-doctor.mjs && node test/version-currency.mjs && node test/ship-capture.mjs && node test/lane-message.mjs && node test/brain-quality.mjs && node test/brief-and-recall.mjs && node test/layout-cluster.mjs && node test/brain-ask.mjs && node test/field-report-2026-07-04.mjs && node test/autoprop.mjs && node test/overlay-recency-2026-07-12.mjs && node test/brain-challenge.mjs && node test/brain-lens.mjs && node test/brain-kind.mjs && node test/rule-drafts.mjs && node test/claim-engine.mjs && node test/canvas-view.mjs && node test/status-completeness.mjs"
+    "test": "node test/codex-hooks.mjs && node test/agent-presence.mjs && node test/context-gateway.mjs && node test/conformance.mjs && node test/brain-doctor.mjs && node test/version-currency.mjs && node test/ship-capture.mjs && node test/lane-message.mjs && node test/brain-quality.mjs && node test/brief-and-recall.mjs && node test/layout-cluster.mjs && node test/brain-ask.mjs && node test/field-report-2026-07-04.mjs && node test/autoprop.mjs && node test/overlay-recency-2026-07-12.mjs && node test/brain-challenge.mjs && node test/brain-lens.mjs && node test/brain-kind.mjs && node test/rule-drafts.mjs && node test/claim-engine.mjs && node test/canvas-view.mjs && node test/status-completeness.mjs"
   },
   "dependencies": {
     "@modelcontextprotocol/ext-apps": "^1.7.4",

package/src/agent-presence.mjs

@@ -292,6 +292,39 @@ export function receiveMessages({
   }
 }
 
+// Non-destructive inbox preview for MCP logging notifications. Unlike
+// receiveMessages(), this NEVER appends the session id to message.seen, so a
+// host that ignores notifications cannot make a coordination warning vanish.
+// The next KLYPIX tool result or lifecycle hook still receives + acknowledges
+// the same message through the guaranteed in-band path.
+export function peekMessages({
+  brainPath,
+  sessionId,
+  ignoreTexts = [],
+  home,
+  now = Date.now(),
+}) {
+  if (!brainPath || !sessionId) return [];
+  const data = readLane(laneFileFor(brainPath, home));
+  const sessions = pruneSessions(data.sessions, now);
+  const messages = pruneMessages(data.messages, now);
+  const me = sessions.find((session) => session.id === sessionId);
+  const ignored = new Set(ignoreTexts.map((value) =>
+    String(value || '').replace(/\s+/g, ' ').trim().toLowerCase()));
+  const shown = [];
+  const seenText = new Set();
+  for (const message of messages) {
+    if (message.from === sessionId
+      || (Array.isArray(message.seen) && message.seen.includes(sessionId))
+      || !messageTargetsSession(message, me, sessionId)) continue;
+    const key = String(message.text || '').replace(/\s+/g, ' ').trim().toLowerCase();
+    if (!key || ignored.has(key) || seenText.has(key)) continue;
+    seenText.add(key);
+    shown.push(message);
+  }
+  return shown.slice(0, 6);
+}
+
 // Queue a one-time coordination message directly on the shared presence lane.
 // `dedupeKey` makes machine-generated alerts (for example, exact file overlap)
 // idempotent without weakening deliberate brain_message notes.

package/src/brain-doctor.mjs

@@ -290,7 +290,7 @@ export function render(r, opts = {}) {
   else L.push(`${hmark} ${c.bold}CLAUDE${c.rst}   existing 4-hook capture path intact: ${r.hooks.wired.join(', ')}`);
   const chmark = r.layers.codexHooks === 'warning' ? warn : ok;
   const smart = r.codexSmart?.globalInstructions
-    ? 'approval-free Context Gateway active (task memory + clean peers + auto-alerts)'
+    ? 'approval-free Context Gateway active (task memory + clean peers + proactive/guaranteed alerts)'
     : 'approval-free brain_sync Context Gateway available through MCP';
   if (r.codexHooks.error) {
     L.push(`${chmark} ${c.bold}CODEX${c.rst}    automatic MCP presence + ${smart}; optional native-hook config unreadable: ${c.yel}${r.codexHooks.error}${c.rst}`);
@@ -298,9 +298,9 @@ export function render(r, opts = {}) {
     L.push(`${chmark} ${c.bold}CODEX${c.rst}    automatic MCP presence + ${smart} · native hooks off ${c.dim}(optional)${c.rst}`);
   } else if (r.codexHooks.executionStatus !== 'observed') {
     L.push(`${chmark} ${c.bold}CODEX${c.rst}    automatic MCP presence + ${smart} · ${c.yel}native hooks configured but execution not verified${c.rst}`);
-    L.push(`        ${c.dim}Context Gateway memory/coordination already works. Native hooks add mechanical lifecycle capture on Codex surfaces that support trust review.${c.rst}`);
+    L.push(`        ${c.dim}Context Gateway memory/coordination already works. Once trusted, native hooks auto-inject task memory and warn before exact overlapping edits.${c.rst}`);
   } else {
-    L.push(`${chmark} ${c.bold}CODEX${c.rst}    automatic MCP presence + ${smart} · native hooks active ${c.dim}(last observed ${r.codexHooks.lastExecutedAt})${c.rst}`);
+    L.push(`${chmark} ${c.bold}CODEX${c.rst}    automatic MCP presence + ${smart} · native auto-context + pre-edit guard active ${c.dim}(last observed ${r.codexHooks.lastExecutedAt})${c.rst}`);
   }
 
   // TOOLS

package/src/codex-brain-hook.mjs

@@ -8,11 +8,14 @@ import {
   findProjectBrain,
   formatPresenceMessage,
   formatReceivedMessages,
+  postPresenceMessage,
   receiveMessages,
   removeSession,
   upsertSession,
 } from './agent-presence.mjs';
 import { recordCodexHookExecution } from './codex-hooks.mjs';
+import { opBrainTaskContext } from './klypix-core.mjs';
+import { findPresenceConflicts } from './mcp-presence.mjs';
 
 function readInput() {
   try {
@@ -84,6 +87,53 @@ function emitSystemMessage(parts) {
   process.stdout.write(JSON.stringify({ continue: true, systemMessage }));
 }
 
+function formatConflictWarning(conflicts, event) {
+  if (!conflicts.length) return '';
+  const moment = event === 'PreToolUse' ? 'before this edit runs' : 'after this file operation';
+  return [
+    `KLYPIX BLOCKING exact-file overlap detected ${moment}:`,
+    ...conflicts.map((peer) =>
+      `- ${String(peer.id).slice(0, 12)}${peer.intent ? ` "${String(peer.intent).slice(0, 90)}"` : ''}: ${peer.files.join(', ')}`),
+    'Coordinate file ownership now. Do not continue overlapping edits until one session yields or the scopes are separated.',
+  ].join('\n');
+}
+
+function queueConflictAlerts({ brainPath, sessionId, intent, conflicts, turnId }) {
+  const queued = [];
+  for (const peer of conflicts) {
+    const filesKey = peer.files.map((file) => String(file).toLowerCase()).sort().join('|');
+    const result = postPresenceMessage({
+      brainPath,
+      from: sessionId,
+      to: peer.id,
+      text: `Automatic KLYPIX pre-edit overlap alert: ${String(sessionId).slice(0, 12)}`
+        + `${intent ? ` is working on "${String(intent).slice(0, 110)}"` : ' is editing'}`
+        + ` and reports the same file(s): ${peer.files.join(', ')}. Coordinate ownership now.`,
+      dedupeKey: `hook-overlap|${sessionId}|${peer.id}|${turnId || 'turn'}|${filesKey}`,
+    });
+    if (result.posted) queued.push(peer.id);
+  }
+  return queued;
+}
+
+async function compactTaskContext(projectDir, prompt, files) {
+  if (!prompt) return '';
+  try {
+    const result = await opBrainTaskContext({
+      vault: projectDir,
+      intent: String(prompt).slice(0, 2000),
+      files,
+      k: 4,
+      budgetChars: 1800,
+    });
+    return result?.context
+      ? result.blocks?.filter((block) => block.kind === 'text').map((block) => block.text).filter(Boolean).join('\n\n') || ''
+      : '';
+  } catch {
+    return '';
+  }
+}
+
 async function main() {
   const input = readInput();
   const event = String(input.hook_event_name || input.hookEventName || '');
@@ -100,7 +150,9 @@ async function main() {
 
   const projectDir = path.dirname(brainPath);
   const prompt = input.prompt || input.user_prompt || input.userPrompt;
-  const files = event === 'PostToolUse' ? touchedFiles(input, projectDir) : undefined;
+  const files = event === 'PreToolUse' || event === 'PostToolUse'
+    ? touchedFiles(input, projectDir)
+    : (event === 'UserPromptSubmit' ? [] : undefined);
   const sessions = upsertSession({
     brainPath,
     id: sessionId,
@@ -111,6 +163,7 @@ async function main() {
     branch: gitBranch(cwd),
     intent: prompt === undefined ? undefined : prompt,
     files,
+    replaceFiles: event === 'UserPromptSubmit',
     event,
     channel: 'lifecycle',
     cwd,
@@ -118,6 +171,19 @@ async function main() {
 
   const ignored = event === 'PostToolUse' ? ownBrainMessageText(input) : [];
   const messages = receiveMessages({ brainPath, sessionId, ignoreTexts: ignored });
+  const conflicts = (event === 'PreToolUse' || event === 'PostToolUse')
+    ? findPresenceConflicts(sessions, sessionId)
+    : [];
+  if (conflicts.length) {
+    const me = sessions.find((session) => session.id === sessionId);
+    queueConflictAlerts({
+      brainPath,
+      sessionId,
+      intent: me?.intent || '',
+      conflicts,
+      turnId: input.turn_id || input.turnId || '',
+    });
+  }
   if (event === 'SessionStart') {
     emitSystemMessage([
       formatPresenceMessage(sessions, sessionId, { includeSolo: true }),
@@ -126,12 +192,22 @@ async function main() {
     return;
   }
   if (event === 'UserPromptSubmit') {
+    const me = sessions.find((session) => session.id === sessionId);
+    const context = await compactTaskContext(projectDir, prompt, me?.files || []);
     emitSystemMessage([
+      context,
       formatPresenceMessage(sessions, sessionId),
       formatReceivedMessages(messages),
     ]);
     return;
   }
+  if (event === 'PreToolUse' || event === 'PostToolUse') {
+    emitSystemMessage([
+      formatConflictWarning(conflicts, event),
+      formatReceivedMessages(messages),
+    ]);
+    return;
+  }
   if (messages.length) emitSystemMessage([formatReceivedMessages(messages)]);
 }
 

package/src/codex-hooks.mjs

@@ -10,6 +10,7 @@ import crypto from 'crypto';
 export const CODEX_PRESENCE_EVENTS = [
   'SessionStart',
   'UserPromptSubmit',
+  'PreToolUse',
   'Stop',
   'PostToolUse',
   'SessionEnd',
@@ -29,10 +30,19 @@ export function resolveCodexHooksPath(home = os.homedir()) {
 }
 
 export function codexPresenceGroups(command) {
-  const handler = (timeout = 5) => ({ type: 'command', command, timeout });
+  const handler = (timeout = 5, statusMessage) => ({
+    type: 'command',
+    command,
+    timeout,
+    ...(statusMessage ? { statusMessage } : {}),
+  });
   return {
-    SessionStart: [{ hooks: [handler()] }],
-    UserPromptSubmit: [{ hooks: [handler()] }],
+    SessionStart: [{ hooks: [handler(5, 'Loading KLYPIX project awareness')] }],
+    UserPromptSubmit: [{ hooks: [handler(5, 'Syncing KLYPIX task context')] }],
+    PreToolUse: [{
+      matcher: 'apply_patch|Edit|Write',
+      hooks: [handler(5, 'Checking KLYPIX file ownership')],
+    }],
     Stop: [{ hooks: [handler()] }],
     PostToolUse: [{ hooks: [handler()] }],
     SessionEnd: [{ hooks: [handler(3)] }],

package/src/mcp-presence.mjs

@@ -12,6 +12,7 @@ import {
   findProjectBrain,
   formatPresenceMessage,
   formatReceivedMessages,
+  peekMessages,
   postPresenceMessage,
   receiveMessages,
   removeSession,
@@ -19,6 +20,7 @@ import {
 } from './agent-presence.mjs';
 
 export const MCP_HEARTBEAT_MS = 60_000;
+export const MCP_INBOX_POLL_MS = 3_000;
 
 // Standard MCP server instructions are the approval-free awareness path. Hosts
 // that surface InitializeResult.instructions to the model learn the same
@@ -185,19 +187,25 @@ export function createMcpPresence({
   env = process.env,
   home,
   heartbeatMs = MCP_HEARTBEAT_MS,
+  inboxPollMs = MCP_INBOX_POLL_MS,
   now = () => Date.now(),
   setIntervalFn = setInterval,
   clearIntervalFn = clearInterval,
 } = {}) {
   const sessionId = resolveMcpSessionId({ env });
+  const effectiveInboxPollMs = Number(env?.KLYPIX_MCP_INBOX_POLL_MS)
+    || Number(inboxPollMs)
+    || MCP_INBOX_POLL_MS;
   let vault = path.resolve(initialVault || process.cwd());
   let brainPath = null;
   let timer = null;
+  let inboxTimer = null;
   let started = false;
   let lastPeers = '';
   let taskStartedAt = 0;
   const sentTexts = new Set();
   const notifiedConflicts = new Set();
+  const announcedMessageIds = new Set();
 
   const clientInfo = () => {
     let version = {};
@@ -209,12 +217,37 @@ export function createMcpPresence({
   };
 
   const sendNotice = (message) => {
-    if (!message || typeof server?.sendLoggingMessage !== 'function') return;
+    if (!message || typeof server?.sendLoggingMessage !== 'function') return false;
     Promise.resolve(server.sendLoggingMessage({
       level: 'info',
       logger: 'klypix-presence',
       data: message,
     })).catch(() => {});
+    return true;
+  };
+
+  // Best-effort proactive path: MCP logging notifications can surface an
+  // overlap while the older session is still working. This deliberately PEEKS
+  // instead of acknowledging. Hosts are allowed to hide logging notifications,
+  // so the same warning remains unread and is guaranteed to arrive in-band on
+  // the next KLYPIX tool result / brain_sync call.
+  const pollInbox = () => {
+    if (!brainPath) return [];
+    const pending = peekMessages({
+      brainPath,
+      sessionId,
+      ignoreTexts: [...sentTexts],
+      home,
+      now: now(),
+    }).filter((message) => !announcedMessageIds.has(message.id));
+    if (!pending.length) return [];
+    if (sendNotice(formatReceivedMessages(pending, now()))) {
+      for (const message of pending) announcedMessageIds.add(message.id);
+      while (announcedMessageIds.size > 100) {
+        announcedMessageIds.delete(announcedMessageIds.values().next().value);
+      }
+    }
+    return pending;
   };
 
   const touch = ({
@@ -271,7 +304,9 @@ export function createMcpPresence({
 
   const stop = () => {
     if (timer) clearIntervalFn(timer);
+    if (inboxTimer) clearIntervalFn(inboxTimer);
     timer = null;
+    inboxTimer = null;
     if (brainPath) removeSession({
       brainPath,
       id: sessionId,
@@ -282,6 +317,7 @@ export function createMcpPresence({
     brainPath = null;
     started = false;
     lastPeers = '';
+    announcedMessageIds.clear();
   };
 
   const start = (nextVault = vault, details = {}) => {
@@ -302,7 +338,12 @@ export function createMcpPresence({
       replaceFiles: details.replaceFiles === true,
     });
     timer = setIntervalFn(() => touch(), Math.max(5_000, Number(heartbeatMs) || MCP_HEARTBEAT_MS));
+    inboxTimer = setIntervalFn(
+      () => pollInbox(),
+      Math.max(250, effectiveInboxPollMs),
+    );
     timer?.unref?.();
+    inboxTimer?.unref?.();
     return first;
   };
 
@@ -398,6 +439,10 @@ export function createMcpPresence({
         ts: message.ts,
       })),
       alertsQueued,
+      delivery: {
+        proactive: 'mcp-logging-best-effort',
+        guaranteed: 'next-klypix-action',
+      },
       timingMs: { coordination: durationMs },
     };
     const text = [
@@ -429,6 +474,7 @@ export function createMcpPresence({
     start,
     stop,
     touch,
+    pollInbox,
     sync,
     noteSent,
     decorateToolResult,