@gamaze/hicortex 0.12.1 → 0.13.0

package/dist/index.js

@@ -23,6 +23,8 @@ const paths_js_1 = require("./paths.js");
 const features_js_1 = require("./features.js");
 const extensions_js_1 = require("./extensions.js");
 const state_js_1 = require("./state.js");
+const context_store_js_1 = require("./context-store.js");
+const lessons_context_js_1 = require("./lessons-context.js");
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
 const node_os_1 = require("node:os");
@@ -31,7 +33,10 @@ const node_os_1 = require("node:os");
 // ---------------------------------------------------------------------------
 const DEFAULT_SERVER_URL = "http://127.0.0.1:8787";
 const LESSONS_TIMEOUT_MS = 3000;
+const CONTEXT_TIMEOUT_MS = 3000;
 const HICORTEX_HOME = (0, paths_js_1.hicortexHome)();
+/** Harness name this plugin injects for — used to self-gate on GET /context `clients`. */
+const THIS_HARNESS = "oc";
 // ---------------------------------------------------------------------------
 // Module state — initialized in registerService.start()
 // ---------------------------------------------------------------------------
@@ -95,6 +100,54 @@ async function serverPost(path, body, timeoutMs) {
     }
 }
 // ---------------------------------------------------------------------------
+// Context layer (L2) — per-agent standing context (0.13)
+// ---------------------------------------------------------------------------
+/**
+ * Fetch GET /context (per-agent when an id is supplied) and build the
+ * `## Context` block via the shared gate (gateAndRenderContext), or null when
+ * nothing should be injected. The old-server guard is required only when an
+ * agent id was actually sent (amendment A2 — a bare fetch skips it). The server
+ * does the merge; the plugin stays dumb (no client-side mode logic).
+ */
+async function fetchOcContextBlock(agentId) {
+    const path = agentId ? `/context?agent=${encodeURIComponent(agentId)}` : "/context";
+    const { data } = await serverGet(path, CONTEXT_TIMEOUT_MS);
+    if (!data)
+        return null;
+    return (0, lessons_context_js_1.gateAndRenderContext)(data, THIS_HARNESS, { requireAgentEcho: agentId !== null });
+}
+/**
+ * Fetch /lessons and build the `## Hicortex Lessons` block, or null on any
+ * failure or when no lessons survive selection. Preserves the pre-0.13 lesson
+ * output; the caller prepends the `## Context` block and adds separators.
+ */
+async function buildLessonsBlock(project) {
+    const { data } = await serverGet("/lessons", LESSONS_TIMEOUT_MS);
+    if (!data || !data.lessons || data.lessons.length === 0)
+        return null;
+    const maxLessons = (0, features_js_1.lessonsLimit)();
+    const state = (0, state_js_1.loadState)(hicortexHome);
+    const moduleIndex = data.moduleIndex ?? state.moduleIndex;
+    const selected = await (0, extensions_js_1.getLessonSelector)().select(data.lessons, {
+        maxLessons,
+        project,
+        moduleIndex,
+    });
+    if (selected.length === 0)
+        return null;
+    const formatted = selected.map((l) => {
+        const titleMatch = l.content.match(/## Lesson: (.+)/);
+        const typeMatch = l.content.match(/\*\*Type:\*\* (\w+)/);
+        const severityMatch = l.content.match(/\*\*Severity:\*\* (\w+)/);
+        const title = titleMatch ? titleMatch[1] : l.content.slice(0, 150);
+        const meta = [severityMatch?.[1], typeMatch?.[1]].filter(Boolean).join(", ");
+        return `- ${title}${meta ? ` (${meta})` : ""}`;
+    });
+    return (`## Hicortex Lessons (auto-injected from long-term memory)\n` +
+        `These are actionable lessons learned from past sessions:\n\n` +
+        formatted.join("\n"));
+}
+// ---------------------------------------------------------------------------
 // Tool result formatter
 // ---------------------------------------------------------------------------
 function formatToolResults(results) {
@@ -158,40 +211,32 @@ exports.default = {
             },
         });
         // -----------------------------------------------------------------------
-        // Hook: before_agent_start — fetch lessons from server (fail-soft)
+        // Hook: before_agent_start — fetch context + lessons from server (fail-soft)
         // -----------------------------------------------------------------------
         api.on("before_agent_start", async (_event, ctx) => {
+            // Outer guard: the hook must NEVER throw (a rejection could block the
+            // agent). `ctx` itself can be nullish on some gateway variants, and the
+            // synchronous sanitize below runs before any per-fetch .catch — so the
+            // whole body is wrapped, not just the fetches.
             try {
-                // One fetch — build context and check cap from the same response.
-                const { data } = await serverGet("/lessons", LESSONS_TIMEOUT_MS);
-                if (!data || !data.lessons || data.lessons.length === 0)
-                    return {};
-                const maxLessons = (0, features_js_1.lessonsLimit)();
-                const state = (0, state_js_1.loadState)(hicortexHome);
-                const moduleIndex = data.moduleIndex ?? state.moduleIndex;
-                const selected = await (0, extensions_js_1.getLessonSelector)().select(data.lessons, {
-                    maxLessons,
-                    project: ctx.project,
-                    moduleIndex,
-                });
-                if (selected.length === 0)
+                // Per-agent context id: sanitize the OC agent id (a symbols-only id
+                // sanitizes to null → bare /context → global set). Null id never sends
+                // ?agent=, so an old server behaves exactly as before.
+                const agentId = (0, context_store_js_1.sanitizeAgentId)(ctx?.agentId ?? "");
+                // Fetch both concurrently with INDEPENDENT fail-soft: a /context
+                // failure must never cost the lessons block, and vice versa. The
+                // `## Context` block (standing context, 0.13) is prepended before
+                // `## Hicortex Lessons`, mirroring the CC hook.
+                const [contextBlock, lessonsBlock] = await Promise.all([
+                    fetchOcContextBlock(agentId).catch(() => null),
+                    buildLessonsBlock(ctx?.project).catch(() => null),
+                ]);
+                const blocks = [contextBlock, lessonsBlock].filter((b) => b !== null && b !== "");
+                if (blocks.length === 0)
                     return {};
-                const formatted = selected.map((l) => {
-                    const titleMatch = l.content.match(/## Lesson: (.+)/);
-                    const typeMatch = l.content.match(/\*\*Type:\*\* (\w+)/);
-                    const severityMatch = l.content.match(/\*\*Severity:\*\* (\w+)/);
-                    const title = titleMatch ? titleMatch[1] : l.content.slice(0, 150);
-                    const meta = [severityMatch?.[1], typeMatch?.[1]].filter(Boolean).join(", ");
-                    return `- ${title}${meta ? ` (${meta})` : ""}`;
-                });
-                const context = `\n\n## Hicortex Lessons (auto-injected from long-term memory)\n` +
-                    `These are actionable lessons learned from past sessions:\n\n` +
-                    formatted.join("\n") +
-                    "\n";
-                return { appendSystemContext: context };
+                return { appendSystemContext: `\n\n${blocks.join("\n\n")}\n` };
             }
             catch {
-                // Fail-soft — a broken lessons fetch must not block the agent
                 return {};
             }
         });

package/dist/init.d.ts

@@ -16,6 +16,13 @@
  *   - Install CC custom commands (/learn, /hicortex-activate)
  */
 import type { DomainDef } from "./types.js";
+/**
+ * Classify `claude mcp list` output for the hicortex entry. Pure (testable):
+ *   - "missing"    — hicortex not listed → registration didn't take
+ *   - "connected"  — listed AND reachable (✓/✔/Connected shown)
+ *   - "registered" — listed but connection not confirmed (server down / not restarted)
+ */
+export declare function parseMcpListStatus(mcpListOutput: string): "connected" | "registered" | "missing";
 /**
  * Parse a KEY=VALUE env file (e.g. ~/.hermes/.env or ~/.claude/settings.json env block).
  * Handles: comments (#), quoted values, empty lines.
@@ -37,6 +44,29 @@ export declare function persistAuthToken(configPath: string): {
     token: string;
     generated: boolean;
 };
+/**
+ * Decide the per-agent context id to persist at init (#179; CC default = global,
+ * owner decision 20.07.2026). `agentName` is an explicit opt-in only — there is
+ * NO hostname default, so an install with no `--agent-name` sends no `?agent=`
+ * and shares the global context (one user = one identity across machines).
+ *
+ * Empty string == unset everywhere: `--agent-name ""` (or whitespace-only) is
+ * the explicit way to opt BACK OUT — it CLEARS any existing `agentName` key and
+ * returns to global, rather than erroring as an invalid id.
+ *  - explicit `--agent-name <non-empty>` → the sanitized flag (error if it
+ *    sanitizes to null, so a bad flag is loud rather than silently ignored);
+ *  - explicit `--agent-name ""` / whitespace-only → `clear` (remove the key);
+ *  - no flag but an existing non-empty `agentName` → keep it untouched
+ *    (non-clobber like persistAuthToken / scaffoldDefaultDomains);
+ *  - no flag, no (non-empty) existing value → do not write (global by default).
+ * Pure + exported for testability; never touches disk.
+ */
+export declare function decideAgentName(existing: unknown, flag: string | undefined): {
+    write: boolean;
+    value: string | null;
+    clear?: boolean;
+    error?: string;
+};
 /**
  * Generic default memory domains scaffolded by server-mode init (issue #150).
  * Deliberately broad, high-level spheres — an editable STARTING POINT, not a
@@ -83,6 +113,7 @@ export declare function isEphemeralNpxPath(binPath: string): boolean;
 export declare function installSessionStartHook(settingsPath?: string): void;
 export declare function runInit(options?: {
     serverUrl?: string;
+    agentName?: string;
 }): Promise<void>;
 /**
  * Resolve the nightly hour (0–23, local time) for the generated schedule.

package/dist/init.js

@@ -18,9 +18,11 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.GENERIC_DEFAULT_DOMAINS = void 0;
+exports.parseMcpListStatus = parseMcpListStatus;
 exports.parseEnvFile = parseEnvFile;
 exports.generateAuthToken = generateAuthToken;
 exports.persistAuthToken = persistAuthToken;
+exports.decideAgentName = decideAgentName;
 exports.scaffoldDefaultDomains = scaffoldDefaultDomains;
 exports.isEphemeralNpxPath = isEphemeralNpxPath;
 exports.installSessionStartHook = installSessionStartHook;
@@ -34,6 +36,7 @@ const node_child_process_1 = require("node:child_process");
 const node_readline_1 = require("node:readline");
 const node_crypto_1 = require("node:crypto");
 const claude_md_js_1 = require("./claude-md.js");
+const context_store_js_1 = require("./context-store.js");
 const HICORTEX_HOME = (0, paths_js_1.hicortexHome)();
 const CC_SETTINGS = (0, node_path_1.join)((0, node_os_1.homedir)(), ".claude", "settings.json");
 const CC_COMMANDS_DIR = (0, node_path_1.join)((0, node_os_1.homedir)(), ".claude", "commands");
@@ -157,6 +160,54 @@ function registerCcMcp(serverUrl) {
     }
     // Add MCP tool permissions to settings.json so users don't get prompted
     allowHicortexTools();
+    // Post-install verification (finding #5): a registration that wrote files
+    // but didn't actually take can still look "done". Best-effort confirm and,
+    // either way, tell the user exactly how to check.
+    verifyCcMcp();
+}
+/**
+ * Classify `claude mcp list` output for the hicortex entry. Pure (testable):
+ *   - "missing"    — hicortex not listed → registration didn't take
+ *   - "connected"  — listed AND reachable (✓/✔/Connected shown)
+ *   - "registered" — listed but connection not confirmed (server down / not restarted)
+ */
+function parseMcpListStatus(mcpListOutput) {
+    // `claude mcp list` prints one line per server: "hicortex: <url> (SSE) - <status>".
+    // Anchor on the "hicortex:" line prefix (not a bare word match) so a
+    // differently-named MCP like "hicortex-foo" can't be mistaken for our entry,
+    // and read status from THAT line only.
+    const line = mcpListOutput.split(/\r?\n/).find((l) => /^\s*hicortex:/.test(l));
+    if (!line)
+        return "missing";
+    return /(✓|✔|connected)/i.test(line) ? "connected" : "registered";
+}
+/**
+ * Best-effort post-install check that the hicortex MCP is actually registered
+ * (and, when reachable, connected). NEVER fails init — if the claude CLI is
+ * absent (e.g. registration went via the ~/.claude.json fallback), we can't
+ * query it, so we just tell the user how to confirm. Closes the "looks
+ * configured but isn't, with no verification" gap.
+ */
+function verifyCcMcp() {
+    let out;
+    try {
+        out = (0, node_child_process_1.execSync)("claude mcp list", { encoding: "utf-8", stdio: "pipe" });
+    }
+    catch {
+        console.log("  ℹ After restarting Claude Code, confirm with `claude mcp list` (hicortex should show ✓ Connected).");
+        return;
+    }
+    switch (parseMcpListStatus(out)) {
+        case "connected":
+            console.log("  ✓ Verified: hicortex MCP registered and connected");
+            break;
+        case "registered":
+            console.log("  ✓ Verified: hicortex MCP registered — restart Claude Code, then `claude mcp list` should show it Connected");
+            break;
+        case "missing":
+            console.log("  ⚠ Could NOT confirm the hicortex MCP registration — run `claude mcp list`; if it's absent, re-run init.");
+            break;
+    }
 }
 function allowHicortexTools() {
     let settings = {};
@@ -701,6 +752,68 @@ function persistAuthToken(configPath) {
     (0, node_fs_1.writeFileSync)(configPath, JSON.stringify(config, null, 2));
     return { token, generated: true };
 }
+/**
+ * Decide the per-agent context id to persist at init (#179; CC default = global,
+ * owner decision 20.07.2026). `agentName` is an explicit opt-in only — there is
+ * NO hostname default, so an install with no `--agent-name` sends no `?agent=`
+ * and shares the global context (one user = one identity across machines).
+ *
+ * Empty string == unset everywhere: `--agent-name ""` (or whitespace-only) is
+ * the explicit way to opt BACK OUT — it CLEARS any existing `agentName` key and
+ * returns to global, rather than erroring as an invalid id.
+ *  - explicit `--agent-name <non-empty>` → the sanitized flag (error if it
+ *    sanitizes to null, so a bad flag is loud rather than silently ignored);
+ *  - explicit `--agent-name ""` / whitespace-only → `clear` (remove the key);
+ *  - no flag but an existing non-empty `agentName` → keep it untouched
+ *    (non-clobber like persistAuthToken / scaffoldDefaultDomains);
+ *  - no flag, no (non-empty) existing value → do not write (global by default).
+ * Pure + exported for testability; never touches disk.
+ */
+function decideAgentName(existing, flag) {
+    if (flag !== undefined) {
+        // Explicit empty / whitespace-only value → clear back to global (unset).
+        if (flag.trim() === "")
+            return { write: false, value: null, clear: true };
+        const s = (0, context_store_js_1.sanitizeAgentId)(flag);
+        if (s === null) {
+            return {
+                write: false,
+                value: null,
+                error: `Invalid --agent-name '${flag}'. Must contain letters or digits and sanitize to ^[a-z0-9][a-z0-9_-]*$ (max 64 chars). Pass --agent-name "" to clear it (global context).`,
+            };
+        }
+        return { write: true, value: s };
+    }
+    if (typeof existing === "string" && existing.trim().length > 0)
+        return { write: false, value: existing };
+    return { write: false, value: null };
+}
+/** Read config.json, set agentName, write it back. Used by the server path. */
+function writeAgentNameConfig(configPath, value) {
+    let config = {};
+    try {
+        config = JSON.parse((0, node_fs_1.readFileSync)(configPath, "utf-8"));
+    }
+    catch { /* new / unreadable → start fresh */ }
+    config.agentName = value;
+    (0, node_fs_1.mkdirSync)(HICORTEX_HOME, { recursive: true });
+    (0, node_fs_1.writeFileSync)(configPath, JSON.stringify(config, null, 2));
+}
+/** Read config.json, delete any `agentName` key, write it back (server path). */
+function clearAgentNameConfig(configPath) {
+    let config = {};
+    try {
+        config = JSON.parse((0, node_fs_1.readFileSync)(configPath, "utf-8"));
+    }
+    catch {
+        return; /* new / unreadable → nothing to clear */
+    }
+    if (!("agentName" in config))
+        return;
+    delete config.agentName;
+    (0, node_fs_1.mkdirSync)(HICORTEX_HOME, { recursive: true });
+    (0, node_fs_1.writeFileSync)(configPath, JSON.stringify(config, null, 2));
+}
 /**
  * Generic default memory domains scaffolded by server-mode init (issue #150).
  * Deliberately broad, high-level spheres — an editable STARTING POINT, not a
@@ -994,7 +1107,7 @@ async function ask(question) {
 // ---------------------------------------------------------------------------
 async function runInit(options = {}) {
     if (options.serverUrl) {
-        await runClientInit(options.serverUrl);
+        await runClientInit(options.serverUrl, options.agentName);
         return;
     }
     console.log("Hicortex — Setup for Claude Code\n");
@@ -1076,6 +1189,25 @@ async function runInit(options = {}) {
     // Classification activates automatically once an LLM is configured; until
     // then domains sit inert (strict-skip path).
     scaffoldDefaultDomains(configPath);
+    // Per-agent context id (#179): server mode writes it ONLY when the operator
+    // passes --agent-name. Without the flag no agentName is written and the
+    // co-located CC shares the global context (global by default). Explicit flag
+    // overwrites on re-init; `--agent-name ""` clears it back to global.
+    if (options.agentName !== undefined) {
+        const decision = decideAgentName(undefined, options.agentName);
+        if (decision.error) {
+            console.error(`  ✗ ${decision.error}`);
+            process.exit(1);
+        }
+        if (decision.clear) {
+            clearAgentNameConfig(configPath);
+            console.log("  ✓ Agent name cleared — global context");
+        }
+        else if (decision.write && decision.value) {
+            writeAgentNameConfig(configPath, decision.value);
+            console.log(`  ✓ Agent name set to '${decision.value}'`);
+        }
+    }
     // Install the nightly job (capture via localhost /distill + consolidation).
     // Without it a server-mode install never captures or consolidates — the
     // daemon only serves recall + /distill. Skips if a schedule already exists.
@@ -1137,7 +1269,7 @@ async function runInit(options = {}) {
 // ---------------------------------------------------------------------------
 // Client Mode Init
 // ---------------------------------------------------------------------------
-async function runClientInit(serverUrl) {
+async function runClientInit(serverUrl, agentName) {
     console.log("Hicortex — Client Mode Setup\n");
     serverUrl = serverUrl.replace(/\/+$/, "");
     // Step 1: Verify server is reachable
@@ -1216,8 +1348,30 @@ async function runClientInit(serverUrl) {
     config.serverUrl = serverUrl;
     if (authToken)
         config.authToken = authToken;
+    // Per-agent context id (#179): explicit opt-in only. Written ONLY when
+    // --agent-name is passed; otherwise no agentName is set and the client shares
+    // the global context (global by default). Re-init keeps an existing value
+    // unless --agent-name is explicit; `--agent-name ""` clears it back to global.
+    const nameDecision = decideAgentName(config.agentName, agentName);
+    if (nameDecision.error) {
+        console.error(`  ✗ ${nameDecision.error}`);
+        process.exit(1);
+    }
+    if (nameDecision.clear) {
+        delete config.agentName;
+        console.log("  ✓ Agent name cleared — global context");
+    }
+    else if (nameDecision.write && nameDecision.value) {
+        config.agentName = nameDecision.value;
+        if (agentName && nameDecision.value !== agentName) {
+            console.log(`  ℹ Agent name sanitized to '${nameDecision.value}'`);
+        }
+    }
     saveConfig(configPath, config);
     console.log(`  ✓ Client config saved to ${configPath}`);
+    if (typeof config.agentName === "string") {
+        console.log(`  ✓ Agent name: ${config.agentName}`);
+    }
     // Step 4: Register CC MCP pointing to remote server
     if (authToken) {
         // Write directly with auth header

package/dist/lessons-context.d.ts

@@ -21,6 +21,62 @@
  * parse error) results in silent exit-0. A broken hook must never block a
  * CC session, and a broken /context fetch must never blank the whole output.
  */
+/**
+ * The GET /context response shape, shared by the CC hook and the OC plugin so
+ * their gating cannot drift. `agent`/`mode` are echoed by a 0.13 server whenever
+ * `?agent=` was sent (in EVERY mode); a pre-0.13 server omits them.
+ */
+export interface ContextResponse {
+    sections?: Record<string, string>;
+    updated_at?: string;
+    clients?: string[];
+    agent?: string;
+    mode?: string;
+}
+/**
+ * Title-case a section name for its heading: split on `-`/`_`, capitalize each
+ * word ("user" → "User", "my_notes" → "My Notes").
+ * Exported so the OC plugin (index.ts) renders the `## Context` block
+ * identically to the CC hook rather than duplicating the logic.
+ */
+export declare function titleCaseSection(name: string): string;
+/**
+ * Stable section ordering: `user` first, then `rules` (the seeded primary
+ * sections, spec §8), then every other section alphabetically. Server-side
+ * enumeration order (readdirSync) is FS-dependent, so we sort here for a
+ * deterministic injection block. Exported for reuse by the OC plugin.
+ */
+export declare function orderSectionNames(names: string[]): string[];
+/**
+ * Render the `## Context` block from a resolved section map, or null when there
+ * is nothing to inject (no sections, or every section blank after trimming).
+ * Pure — no gating, no I/O. Shared verbatim by the CC hook and the OC plugin so
+ * both harnesses emit an identical block. Sections are ordered (user, rules,
+ * then alphabetical) and rendered under title-cased `###` headings.
+ */
+export declare function renderContextBlock(sections: Record<string, string>): string | null;
+/**
+ * Gate a GET /context response and render the `## Context` block, or null when
+ * nothing should be injected: `harness` not in the server-resolved `clients`,
+ * an empty/blank section set, or — when `requireAgentEcho` — a response that
+ * does not echo `agent`. The SINGLE gate used by both CC and OC so the two can
+ * never drift (the Python Hermes plugin `provider.py::_context_block` mirrors
+ * this logic — keep them in sync).
+ *
+ * `requireAgentEcho` is the old-server guard, and it is the CALLER's decision:
+ *   - OC passes `agentId !== null` — when it actually sent an id, a 0.12 server
+ *     that ignores `?agent=` (200 global, no echo) must NOT leak global context
+ *     into every persona; on a bare fetch (no id) the guard is off (amendment
+ *     A2).
+ *   - CC passes `false` ALWAYS and deliberately (see the call site): a thin CC
+ *     client auto-upgrades via npx BEFORE bedrock does, so during the upgrade
+ *     window it talks to a 0.12 server that cannot hold ANY per-agent config —
+ *     global IS the operator's intended state there, and a guard would instead
+ *     blank ALL context for every CC session in that window.
+ */
+export declare function gateAndRenderContext(data: ContextResponse, harness: string, opts: {
+    requireAgentEcho: boolean;
+}): string | null;
 /**
  * Fetch context + lessons concurrently and return the combined Markdown block,
  * or null when neither yields anything (nothing to inject; caller prints

package/dist/lessons-context.js

@@ -23,9 +23,14 @@
  * CC session, and a broken /context fetch must never blank the whole output.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.titleCaseSection = titleCaseSection;
+exports.orderSectionNames = orderSectionNames;
+exports.renderContextBlock = renderContextBlock;
+exports.gateAndRenderContext = gateAndRenderContext;
 exports.fetchLessonsContext = fetchLessonsContext;
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
+const context_store_js_1 = require("./context-store.js");
 const features_js_1 = require("./features.js");
 const extensions_js_1 = require("./extensions.js");
 const state_js_1 = require("./state.js");
@@ -50,7 +55,13 @@ function resolveConfig() {
     const serverUrl = config.mode === "client" && typeof config.serverUrl === "string"
         ? config.serverUrl.replace(/\/+$/, "")
         : `http://127.0.0.1:${config.port ?? DEFAULT_PORT}`;
-    return { serverUrl, authToken: config.authToken, home };
+    // Per-agent context id (0.13) via the shared resolver, so the id sent here
+    // always matches what `hicortex status` reports. No configured agentName →
+    // agentId null → NO ?agent= (bare fetch): CC's default is the shared global
+    // context. A configured agentName that sanitizes to null → agentId null too
+    // (NO ?agent=), never a 400 that the fail-soft hook would silently swallow.
+    const agentName = (0, context_store_js_1.resolveAgentIdentity)(config).agentId;
+    return { serverUrl, authToken: config.authToken, home, agentName };
 }
 function authHeaders(authToken) {
     return authToken ? { "Authorization": `Bearer ${authToken}` } : {};
@@ -112,6 +123,8 @@ async function fetchLessonsBlock(cfg) {
 /**
  * Title-case a section name for its heading: split on `-`/`_`, capitalize each
  * word ("user" → "User", "my_notes" → "My Notes").
+ * Exported so the OC plugin (index.ts) renders the `## Context` block
+ * identically to the CC hook rather than duplicating the logic.
  */
 function titleCaseSection(name) {
     return name
@@ -124,7 +137,7 @@ function titleCaseSection(name) {
  * Stable section ordering: `user` first, then `rules` (the seeded primary
  * sections, spec §8), then every other section alphabetically. Server-side
  * enumeration order (readdirSync) is FS-dependent, so we sort here for a
- * deterministic injection block.
+ * deterministic injection block. Exported for reuse by the OC plugin.
  */
 function orderSectionNames(names) {
     const primaries = ["user", "rules"].filter((p) => names.includes(p));
@@ -132,23 +145,13 @@ function orderSectionNames(names) {
     return [...primaries, ...rest];
 }
 /**
- * Fetch /context and build the `## Context` block, or null when nothing should
- * be injected: non-2xx, this harness not in `clients`, no sections, or all
- * sections empty. Throws propagate to the caller's fail-soft catch.
+ * Render the `## Context` block from a resolved section map, or null when there
+ * is nothing to inject (no sections, or every section blank after trimming).
+ * Pure — no gating, no I/O. Shared verbatim by the CC hook and the OC plugin so
+ * both harnesses emit an identical block. Sections are ordered (user, rules,
+ * then alphabetical) and rendered under title-cased `###` headings.
  */
-async function fetchContextBlock(cfg) {
-    const resp = await fetch(`${cfg.serverUrl}/context`, {
-        headers: authHeaders(cfg.authToken),
-        signal: AbortSignal.timeout(3000),
-    });
-    if (!resp.ok)
-        return null;
-    const data = await resp.json();
-    // Self-gate: only inject when this harness is in the server-resolved list.
-    const clients = Array.isArray(data.clients) ? data.clients : [];
-    if (!clients.includes(THIS_HARNESS))
-        return null;
-    const sections = data.sections;
+function renderContextBlock(sections) {
     if (!sections || typeof sections !== "object" || Array.isArray(sections))
         return null;
     const names = orderSectionNames(Object.keys(sections));
@@ -163,6 +166,62 @@ async function fetchContextBlock(cfg) {
         return null;
     return ["## Context", "", ...bodyParts].join("\n");
 }
+/**
+ * Gate a GET /context response and render the `## Context` block, or null when
+ * nothing should be injected: `harness` not in the server-resolved `clients`,
+ * an empty/blank section set, or — when `requireAgentEcho` — a response that
+ * does not echo `agent`. The SINGLE gate used by both CC and OC so the two can
+ * never drift (the Python Hermes plugin `provider.py::_context_block` mirrors
+ * this logic — keep them in sync).
+ *
+ * `requireAgentEcho` is the old-server guard, and it is the CALLER's decision:
+ *   - OC passes `agentId !== null` — when it actually sent an id, a 0.12 server
+ *     that ignores `?agent=` (200 global, no echo) must NOT leak global context
+ *     into every persona; on a bare fetch (no id) the guard is off (amendment
+ *     A2).
+ *   - CC passes `false` ALWAYS and deliberately (see the call site): a thin CC
+ *     client auto-upgrades via npx BEFORE bedrock does, so during the upgrade
+ *     window it talks to a 0.12 server that cannot hold ANY per-agent config —
+ *     global IS the operator's intended state there, and a guard would instead
+ *     blank ALL context for every CC session in that window.
+ */
+function gateAndRenderContext(data, harness, opts) {
+    if (!data || typeof data !== "object")
+        return null;
+    const clients = Array.isArray(data.clients) ? data.clients : [];
+    if (!clients.includes(harness))
+        return null;
+    if (opts.requireAgentEcho && typeof data.agent !== "string")
+        return null;
+    return renderContextBlock(data.sections ?? {});
+}
+/**
+ * Fetch /context and build the `## Context` block, or null when nothing should
+ * be injected: non-2xx, this harness not in `clients`, no sections, or all
+ * sections empty. Throws propagate to the caller's fail-soft catch.
+ */
+async function fetchContextBlock(cfg) {
+    // Send ?agent= only when we have a valid id; the server does the merge and
+    // returns the resolved sections, so the hook stays dumb (no client-side mode
+    // logic). A null id (CC's default: no configured agentName, or a configured
+    // value that sanitizes to nothing) → bare /context → the shared global set.
+    const url = cfg.agentName
+        ? `${cfg.serverUrl}/context?agent=${encodeURIComponent(cfg.agentName)}`
+        : `${cfg.serverUrl}/context`;
+    const resp = await fetch(url, {
+        headers: authHeaders(cfg.authToken),
+        signal: AbortSignal.timeout(3000),
+    });
+    if (!resp.ok)
+        return null;
+    const data = await resp.json();
+    // CC deliberately passes requireAgentEcho: false (NOT the OC/Hermes old-server
+    // guard). A thin CC client auto-upgrades via npx BEFORE bedrock does, so
+    // mid-upgrade it may hit a 0.12 server that returns global context with no
+    // `agent` echo — and a 0.12 server cannot hold per-agent config, so global is
+    // the intended state. Guarding here would blank ALL CC context in that window.
+    return gateAndRenderContext(data, THIS_HARNESS, { requireAgentEcho: false });
+}
 /**
  * Fetch context + lessons concurrently and return the combined Markdown block,
  * or null when neither yields anything (nothing to inject; caller prints

package/dist/mcp-server.js

@@ -81,6 +81,10 @@ let stateDir = "";
 // Resolved contextClients list (spec §2) — the harness names allowed to inject
 // the standing context layer. Echoed by GET /context so each hook self-gates.
 let contextClients = ["cc"];
+// Resolved contextAgents map (0.13) — agent id → mode (override/global/off).
+// Read once at boot (like contextClients); the drop-in-a-dir presence path is
+// per-request, so only explicit config entries need a daemon restart to apply.
+let contextAgents = {};
 // Cache detectChunkSize results keyed by "<provider>/<model>@<baseUrl>" so we
 // probe each endpoint once per server boot rather than once per /distill request.
 const chunkSizeCache = new Map();
@@ -436,6 +440,16 @@ async function startServer(options = {}) {
         console.warn(`[hicortex] Ignoring unknown contextClients: ${resolvedClients.dropped.join(", ")} ` +
             `(known: cc, hermes, oc)`);
     }
+    // Per-agent context (0.13): resolve the config-declared modes. Warn once per
+    // boot on dropped entries (bad key or bad mode) so typos surface. NOTE: this
+    // map is boot-time; editing contextAgents needs a daemon restart. Dropping an
+    // agents/<id> dir onto disk takes effect immediately (per-request presence).
+    const resolvedAgents = (0, context_store_js_1.resolveContextAgents)(savedConfig?.contextAgents);
+    contextAgents = resolvedAgents.agents;
+    if (resolvedAgents.dropped.length > 0) {
+        console.warn(`[hicortex] Ignoring invalid contextAgents entries: ${resolvedAgents.dropped.join(", ")} ` +
+            `(keys must match ^[a-z0-9][a-z0-9_-]*$; modes must be override|global|off)`);
+    }
     // Express app
     const app = (0, express_1.default)();
     // Raise the body limit — whole-session denoised transcripts exceed the 100 kB default.
@@ -620,7 +634,7 @@ async function startServer(options = {}) {
     // which the tests exercise directly — no mirror-app drift.
     app.get("/context", (req, res) => {
         try {
-            const r = (0, context_store_js_1.handleContextGet)((0, node_path_1.join)(stateDir, "context"), contextClients, req.query);
+            const r = (0, context_store_js_1.handleContextGet)((0, node_path_1.join)(stateDir, "context"), contextClients, req.query, contextAgents);
             res.status(r.status).json(r.body);
         }
         catch (err) {
@@ -629,7 +643,7 @@ async function startServer(options = {}) {
     });
     app.put("/context", (req, res) => {
         try {
-            const r = (0, context_store_js_1.handleContextPut)((0, node_path_1.join)(stateDir, "context"), req.body);
+            const r = (0, context_store_js_1.handleContextPut)((0, node_path_1.join)(stateDir, "context"), req.body, req.query, contextAgents);
             if (r.warn)
                 console.warn(`[hicortex] ${r.warn}`);
             res.status(r.status).json(r.body);