@essentialai/cogent-plugin 3.25.8 → 3.25.10

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "cogent",
-  "version": "3.25.8",
+  "version": "3.25.10",
   "description": "Inter-session communication bridge for Claude Code with Slack integration. Enables CC agents and Slack team members to communicate in real time.",
   "author": {
     "name": "Essential AI Solutions",

package/bridge/cogent-bridge.mjs

@@ -655,18 +655,80 @@ async function loadCredentials(credentialPath) {
 async function saveCredentials(creds, credentialPath) {
   const filePath = resolveCredentialPath(credentialPath);
   await fs4.mkdir(path4.dirname(filePath), { recursive: true, mode: 448 });
-  await fs4.writeFile(
-    filePath,
-    JSON.stringify(creds, null, 2) + "\n",
-    { encoding: "utf-8", mode: 384 }
-  );
-  await fs4.chmod(filePath, 384);
+  let out = creds;
+  if (creds.peers === void 0) {
+    const prior = await loadCredentials(filePath);
+    if (prior?.peers) out = { ...creds, peers: prior.peers };
+  }
+  const tmp = `${filePath}.${process.pid}.${crypto.randomBytes(4).toString("hex")}.tmp`;
+  await fs4.writeFile(tmp, JSON.stringify(out, null, 2) + "\n", { encoding: "utf-8", mode: 384 });
+  await fs4.chmod(tmp, 384);
+  await fs4.rename(tmp, filePath);
 }
 async function rememberIssuedPeerSecret(sessionId, peerId, peerSecret) {
   const creds = await loadCredentials();
   if (!creds || creds.sessionId !== sessionId) return;
-  if (creds.peerId === peerId && creds.peerSecret === peerSecret) return;
-  await saveCredentials({ ...creds, peerId, peerSecret, savedAt: (/* @__PURE__ */ new Date()).toISOString() });
+  const entry = creds.peers?.[peerId];
+  const entryCurrent = !entry || entry.sessionId !== sessionId || entry.peerSecret === peerSecret;
+  if (creds.peerId === peerId && creds.peerSecret === peerSecret && entryCurrent) return;
+  const peers = entry && entry.sessionId === sessionId ? { ...creds.peers, [peerId]: { ...entry, peerSecret, savedAt: (/* @__PURE__ */ new Date()).toISOString() } } : creds.peers;
+  const base = entry && entry.sessionId === sessionId ? { ...creds, ...entry } : creds;
+  await saveCredentials({ ...base, peerId, peerSecret, ...peers ? { peers } : {}, savedAt: (/* @__PURE__ */ new Date()).toISOString() });
+}
+function setCurrentCloudConnection(c2) {
+  currentCloudConnection = c2;
+}
+function getCurrentCloudConnection() {
+  return currentCloudConnection;
+}
+function peerCredentials(folder, peerId) {
+  if (!folder) return null;
+  if (folder.peerId === peerId) {
+    const { peers: _p, ...top } = folder;
+    return top;
+  }
+  const e = folder.peers?.[peerId];
+  return e ? { ...e, peerId } : null;
+}
+function peerRecordsOf(folder) {
+  if (!folder?.peers) return [];
+  return Object.entries(folder.peers).map(([peerId, e]) => ({ ...e, peerId }));
+}
+async function loadPeerRecord(peerId, credentialPath) {
+  return peerCredentials(await loadCredentials(credentialPath), peerId);
+}
+async function loadPeerRecords(credentialPath) {
+  return peerRecordsOf(await loadCredentials(credentialPath));
+}
+async function savePeerRecord(rec, credentialPath) {
+  const folder = await loadCredentials(credentialPath);
+  if (!folder) return;
+  const { peerId, peers: _p, ...entry } = rec;
+  await saveCredentials({ ...folder, peers: { ...folder.peers ?? {}, [peerId]: entry } }, credentialPath);
+}
+async function deletePeerRecord(peerId, credentialPath) {
+  const folder = await loadCredentials(credentialPath);
+  if (!folder?.peers?.[peerId]) return;
+  const { [peerId]: _gone, ...rest } = folder.peers;
+  await saveCredentials({ ...folder, peers: rest }, credentialPath);
+}
+function chooseRestoreCredentials(folder, records, ownSession, platform) {
+  if (records.length === 0) return { creds: folder };
+  const top = folder?.peerId ? peerCredentials(folder, folder.peerId) : null;
+  const pick2 = (r) => peerCredentials(folder, r.peerId) ?? r;
+  if (ownSession) {
+    const mine = records.filter((r) => r.agentSession === ownSession);
+    if (mine.length > 0) return { creds: pick2(mine[0]) };
+  }
+  const sameKind = records.filter((r) => r.platform === platform);
+  if (sameKind.length === 1) return { creds: pick2(sameKind[0]) };
+  if (sameKind.length > 1 && top && sameKind.some((r) => r.peerId === top.peerId)) return { creds: top };
+  if (sameKind.length === 0 && top && !records.some((r) => r.peerId === top.peerId)) return { creds: top };
+  const names = records.map((r) => `'${r.peerId}' (${r.platform ?? "unknown agent"})`).join(", ");
+  return {
+    creds: null,
+    skip: sameKind.length === 0 ? `this folder's saved names belong to other agents \u2014 ${names}; this ${platform} agent has none, so it registers its own name explicitly` : `this folder has several saved ${platform} names and this bridge cannot tell which is its own \u2014 ${names}; the agent registers its name explicitly`
+  };
 }
 async function legacyGlobalCredentialsExist() {
   try {
@@ -676,7 +738,7 @@ async function legacyGlobalCredentialsExist() {
     return false;
   }
 }
-var LEGACY_GLOBAL_CREDENTIAL_PATH, joinedInProcessFlag, cloudAttemptInProcessFlag, cloudAttemptGeneration, cloudAttemptListeners;
+var LEGACY_GLOBAL_CREDENTIAL_PATH, joinedInProcessFlag, cloudAttemptInProcessFlag, cloudAttemptGeneration, cloudAttemptListeners, currentCloudConnection;
 var init_credential_store = __esm({
   "src/cloud/credential-store.ts"() {
     "use strict";
@@ -688,6 +750,7 @@ var init_credential_store = __esm({
     cloudAttemptInProcessFlag = false;
     cloudAttemptGeneration = 0;
     cloudAttemptListeners = /* @__PURE__ */ new Set();
+    currentCloudConnection = null;
   }
 });
 
@@ -26412,8 +26475,8 @@ var init_stdio2 = __esm({
 // src/constants.ts
 import { createRequire } from "node:module";
 function resolveVersion() {
-  if ("3.25.8") {
-    return "3.25.8";
+  if ("3.25.10") {
+    return "3.25.10";
   }
   try {
     const require2 = createRequire(import.meta.url);
@@ -26629,6 +26692,9 @@ ${issues}`);
   _config = Object.freeze(data);
   return _config;
 }
+function readOnlyWake(config2) {
+  return config2.COGENT_READ_ONLY_WAKE || config2.COGENT_WAKE_TOOLS === "read";
+}
 function getConfig() {
   if (!_config) throw new Error("Config not loaded. Call loadConfig() first.");
   return _config;
@@ -26692,6 +26758,44 @@ var init_config = __esm({
       // launches via the daemon (see bin/cogent-codex) and sets this to `app-server`.
       // Only affects COGENT_PLATFORM=codex; claude/gemini/mail rails never read it.
       COGENT_CODEX_WAKE: import_zod2.z.enum(["auto", "exec-resume", "app-server"]).default("auto"),
+      // COG-86 / COG-88: what a Claude wake may do. `full` (default) = every tool, as before 3.25.9. `read` = Read,
+      // Glob and Grep only: the wake answers but cannot edit, run commands or commit. A wake resumes the SAME session
+      // a human may have open in a terminal, and nothing can tell reliably that the terminal is there; on 2026-10-15
+      // a full-tool wake edited a live session's files, then committed and pushed. 3.25.9 made `read` the default;
+      // the operator reversed that on 2026-10-16 (COG-88): read-only is an opt-in, switched with the environment
+      // variable COGENT_READ_ONLY_WAKE (below) or here. An EMPTY value counts as unset — a host that substitutes an empty
+      // string for a missing setting must not take the bridge down. Case and surrounding spaces are ignored
+      // ("Read", "read " = read), the same rule COGENT_READ_ONLY_WAKE uses — a user opting in must not stop the
+      // bridge over a capital letter. Any other unknown value still fails loudly.
+      // Read it through readOnlyWake(), never directly: either opt-in turns read-only on.
+      COGENT_WAKE_TOOLS: import_zod2.z.preprocess(
+        (v) => {
+          if (typeof v !== "string") return v;
+          const s = v.trim().toLowerCase();
+          return s === "" ? void 0 : s;
+        },
+        import_zod2.z.enum(["read", "full"]).default("full")
+      ),
+      // COG-88: the read-only wake opt-in — an ENVIRONMENT VARIABLE only: no plugin setting, so no Claude Code
+      // version floor. Plugin users set it in the "env" block of ~/.claude/settings.json or export it in the shell
+      // (both reach the plugin's MCP server and its SessionStart hook — measured, Claude Code 2.1.74 and 2.1.302); a custom/Team config sets it
+      // in its server env block. Applied at bridge start: /reload-plugins does NOT restart the server (measured).
+      // The plugin's .mcp.json must NEVER set this key (nor COGENT_WAKE_TOOLS): a plugin env-block key wins over the
+      // shell and settings.json, so any value there would silently block the user's opt-in (measured).
+      //
+      // FUTURE /config option (operator, 2026-10-16: may become the only switch; NOT shipped now). It would be a
+      // plugin.json "userConfig": { "read_only_wake": { "type": "boolean", ... } } mapped by plugin/.mcp.json
+      // "COGENT_READ_ONLY_WAKE": "${user_config.read_only_wake}" — Claude Code passes the STRING "true"/"false"
+      // (measured, 2.1.301). userConfig needs Claude Code >= 2.1.75: 2.1.74 and older reject the manifest
+      // ('Unrecognized key: "userConfig"') and load NONE of the plugin (measured 2026-10-16). Adding that env line
+      // also ends the env-variable path for plugin users (the block wins), so the two cannot ship side by side, and
+      // the guards in src/config.test.ts and cogent-plugin/scripts/sync-from-plugin.test.mjs must change with it.
+      //
+      // Only an explicit affirmative turns it on. Anything else is OFF and never an error — "", "false", a typo, or
+      // an unsubstituted "${user_config.read_only_wake}": a config error here would stop the bridge, which is worse
+      // than a wake that behaves as it did before 3.25.9. The plugin's SessionStart notice reads it with the same rule
+      // (readOnlyWakeFromEnv in plugin/hooks/check-on-stop.lib.mjs, parity-tested).
+      COGENT_READ_ONLY_WAKE: import_zod2.z.string().optional().transform((v) => v !== void 0 && ["true", "1", "yes", "on"].includes(v.trim().toLowerCase())),
       // Auto-recovery for a blocked Codex sandbox. On a host where the OS sandbox
       // can't initialize (unprivileged user namespaces blocked — Ubuntu 24.04's
       // apparmor_restrict_unprivileged_userns, containers, hardened kernels),
@@ -27352,14 +27456,21 @@ async function execClaude(sessionId, message, cwd, timeoutMs) {
       // as a raw JSON blob. Flag drift is guarded by claude-preflight.ts.
       "--output-format",
       "json",
+      // COG-86: an ALLOW list, never a deny list. --disallowedTools Edit,Write,NotebookEdit,Bash was measured to leak
+      // (the Monitor tool, loaded through ToolSearch, ran a shell and wrote a file) and would miss every tool a later
+      // claude adds. --tools is variadic, so it must be followed by another option, never by the message. A claude
+      // too old to know --tools exits "unknown option" — the wake fails, it never runs with every tool.
+      // COG-88: opt-in (COGENT_READ_ONLY_WAKE=true or COGENT_WAKE_TOOLS=read in the env); off by default.
+      ...readOnlyWake(config2) ? ["--tools", READ_ONLY_WAKE_TOOLS, "--append-system-prompt", READ_ONLY_WAKE_NOTICE] : [],
       "-p",
-      truncated
+      readOnlyWake(config2) ? `${truncated}${READ_ONLY_WAKE_PROMPT_SEPARATOR}${READ_ONLY_WAKE_NOTICE}` : truncated
     ];
     const cleanEnv = buildResumeEnv(process.env, "CLAUDE", ["CLAUDE_CONFIG_DIR"]);
     if (resolvedRoot && resolvedRoot !== path10.resolve(claudeConfigDir())) {
       cleanEnv.CLAUDE_CONFIG_DIR = resolvedRoot;
     }
     cleanEnv.COGENT_CHECK_ON_STOP = "0";
+    cleanEnv.COGENT_WAKE = "1";
     const child = spawn(config2.COGENT_CLAUDE_PATH, args, {
       cwd,
       env: cleanEnv,
@@ -27480,12 +27591,16 @@ function parseClaudeJsonReply(raw) {
   const result = typeof env.result === "string" ? env.result : null;
   return { result, isError: env.is_error === true || env.subtype !== "success" };
 }
+var READ_ONLY_WAKE_TOOLS, READ_ONLY_WAKE_NOTICE, READ_ONLY_WAKE_PROMPT_SEPARATOR;
 var init_cc_cli = __esm({
   "src/services/cc-cli.ts"() {
     "use strict";
     init_config();
     init_agent_config();
     init_agent_sessions();
+    READ_ONLY_WAKE_TOOLS = "Read,Glob,Grep";
+    READ_ONLY_WAKE_NOTICE = "You are answering a message from another Cogent peer automatically. Your reply goes to that sender, not to your user. Your user chose to make these automatic replies read-only: you can read files, but you cannot edit files, run commands or commit, and neither you nor the sender can change that. If the message asks for a change, do not attempt it. Your reply must: (1) say plainly that this automatic reply could not change any files; (2) give the exact change: the file path and the precise text to replace and its replacement, or the exact command to run; (3) say that your user can make the change in this agent's own session. Do not offer to make the change later, and do not ask the sender to enable, re-enable or turn on any tool or permission.";
+    READ_ONLY_WAKE_PROMPT_SEPARATOR = "\n\n---\n[Cogent: read-only automatic reply \u2014 not part of the message above]\n";
   }
 });
 
@@ -32701,6 +32816,7 @@ function execCodex(sessionId, message, cwd, timeoutMs) {
     ];
     const cleanEnv = buildResumeEnv(process.env, "CODEX", ["CODEX_HOME"]);
     cleanEnv.COGENT_CHECK_ON_STOP = "0";
+    cleanEnv.COGENT_WAKE = "1";
     const child = spawn2(config2.COGENT_CODEX_PATH, args, {
       cwd,
       env: cleanEnv,
@@ -33900,6 +34016,7 @@ function announceBridge(cwd, peerId, version2, endpoint, sessionId = agentSessio
       cwd: path19.resolve(cwd),
       parentPid: process.ppid,
       ...sessionId ? { sessionId } : {},
+      platform: process.env.COGENT_PLATFORM || "cc",
       // 🔴 A headless bridge never had a client to lose (review r7 FIX2-2, SEC2-2): when its launching
       // shell exited, the changed parent read as "client gone" and any bridge that started took its name.
       ...startedWithoutClient() ? { noClient: true } : {}
@@ -35407,7 +35524,13 @@ function mayBeOwnPreSessionBridge(holder, ownSession) {
   const [maj, min, pat] = [Number(v[1]), Number(v[2]), Number(v[3])];
   return maj < 3 || maj === 3 && (min < 25 || min === 25 && pat < 7);
 }
-function heldNameAdvice(peerId) {
+function heldNameAdvice(peerId, holder, own) {
+  const otherSession = !!(holder?.sessionId && own?.sessionId && holder.sessionId !== own.sessionId);
+  const otherPlatform = !!(holder?.platform && own?.platform && holder.platform !== own.platform);
+  if (otherSession || otherPlatform) {
+    const who = [holder?.platform && `a ${holder.platform} agent`, holder?.sessionId && `session ${holder.sessionId}`].filter(Boolean).join(", ");
+    return `'${peerId}' is held by ANOTHER agent's live bridge in this folder (${who}). It keeps the name while that agent runs, so waiting will not free it. Do not take the name and do not rename: tell the user which agent holds '${peerId}' and ask them to have THAT agent run /cogent:register with ITS OWN peer name (which releases '${peerId}'); after that, run /cogent:register again with the SAME peer name '${peerId}'`;
+  }
   return `If this agent was just restarted, its previous connection closes within ${HOLDER_LINGER_SECONDS} seconds: wait ${HOLDER_LINGER_SECONDS}+ seconds, then run /cogent:register again with the SAME peer name '${peerId}'. If '${peerId}' is still held after that, another live connection is using it \u2014 another agent, or an old window of this one still open. Do not take the name and do not rename: ask the user`;
 }
 function anotherAgentSessionAmong(others, ownSession) {
@@ -35425,7 +35548,7 @@ function otherBridgeNotice(others, peerId, verdict, ownSession) {
     }
     return `${who} is registered as '${peerId}' too. NOBODY answers for '${peerId}' in this channel now: the bridge that started last (pid ${verdict.owner?.pid ?? "unknown"}) is the one that wakes its agent, but in this channel the relay registration now belongs to this bridge, so the relay refuses that bridge's replies here and this bridge does not wake. It stays that way until that bridge is closed or its agent registers again. If that bridge is registered in another channel, it still answers there.`;
   });
-  return lines.join(" ") + (anotherAgentSessionAmong(others, ownSession) ? ` Two agents in one folder are not supported yet: each agent needs its own peer name and, for now, its own folder.` : "");
+  return lines.join(" ") + (anotherAgentSessionAmong(others, ownSession) ? ` Each agent in this folder keeps its own saved name (COG-80): after a restart it comes back under that name, not the other agent's.` : "");
 }
 function autoPresenceEnabled(env = process.env) {
   const v = env.COGENT_AUTO_PRESENCE;
@@ -35441,6 +35564,10 @@ async function restorePresence(deps) {
       return { state: "online", restored: false, detail: "registered by this process" };
     }
     const creds = await deps.loadCredentials();
+    const skip = creds ? void 0 : deps.restoreSkip?.();
+    if (skip) {
+      return { state: "deferred", restored: false, detail: `nothing restored: ${skip}` };
+    }
     if (!creds || !creds.endpoint || !creds.sessionId || !creds.token) {
       return {
         state: "deferred",
@@ -35479,7 +35606,7 @@ async function restorePresence(deps) {
       const why = {
         "same-session": `That bridge serves this same agent session (${session})`,
         "no-session": `Neither bridge records an agent session (codex, gemini), so it cannot be told whether that bridge is this agent's previous one or another agent's. ${take}`,
-        "other-session": `That bridge serves another agent session (${servedBy.sessionId}; ours: ${session}). Two agents in one folder are not supported yet: a second agent needs its own folder and peer name. ${take}`,
+        "other-session": `That bridge serves another agent session (${servedBy.sessionId}; ours: ${session}). ` + heldNameAdvice(peerId, { sessionId: servedBy.sessionId }, { sessionId: session }),
         unknown: `Its agent session cannot be compared with this one (that bridge: ${servedBy.sessionId ?? "not recorded"}; this bridge: ${session ?? "not known"}): it may be this agent's own other bridge of an older version, or another agent's. ${take}`
       };
       return {
@@ -35741,14 +35868,18 @@ var init_heartbeat = __esm({
 // src/services/claude-preflight.ts
 import { execFile as execFile4 } from "node:child_process";
 import { promisify as promisify3 } from "node:util";
-function analyzeClaudeHelp(helpText) {
-  const checked = EXPECTED_CLAUDE_FLAGS.map((f) => f.flag);
-  const missing = EXPECTED_CLAUDE_FLAGS.filter(
+function expectedClaudeFlags(readOnly) {
+  return readOnly ? [...EXPECTED_CLAUDE_FLAGS, ...READ_ONLY_WAKE_CLAUDE_FLAGS] : EXPECTED_CLAUDE_FLAGS;
+}
+function analyzeClaudeHelp(helpText, readOnly = false) {
+  const expected = expectedClaudeFlags(readOnly);
+  const checked = expected.map((f) => f.flag);
+  const missing = expected.filter(
     (f) => !helpText.includes(f.flag)
   ).map((f) => f.flag);
   return { missing, checked };
 }
-async function preflightClaude(claudePath) {
+async function preflightClaude(claudePath, readOnly = false) {
   let helpText;
   try {
     const { stdout, stderr } = await execFileAsync2(claudePath, ["--help"], {
@@ -35762,9 +35893,9 @@ ${stderr}`;
     );
     return null;
   }
-  const analysis = analyzeClaudeHelp(helpText);
+  const analysis = analyzeClaudeHelp(helpText, readOnly);
   if (analysis.missing.length > 0) {
-    const detail = EXPECTED_CLAUDE_FLAGS.filter(
+    const detail = expectedClaudeFlags(readOnly).filter(
       (f) => analysis.missing.includes(f.flag)
     ).map((f) => `${f.flag} (${f.usedFor})`).join(", ");
     logger.error(
@@ -35777,7 +35908,7 @@ ${stderr}`;
   }
   return analysis;
 }
-var execFileAsync2, EXPECTED_CLAUDE_FLAGS;
+var execFileAsync2, EXPECTED_CLAUDE_FLAGS, READ_ONLY_WAKE_CLAUDE_FLAGS;
 var init_claude_preflight = __esm({
   "src/services/claude-preflight.ts"() {
     "use strict";
@@ -35791,6 +35922,10 @@ var init_claude_preflight = __esm({
       { flag: "--strict-mcp-config", usedFor: "isolate MCP config of the resumed process" },
       { flag: "--output-format", usedFor: "structured JSON reply envelope (Slice 3 capture)" }
     ];
+    READ_ONLY_WAKE_CLAUDE_FLAGS = [
+      { flag: "--tools", usedFor: "read-only wake: Read, Glob and Grep only (COG-86)" },
+      { flag: "--append-system-prompt", usedFor: "tell a read-only wake it cannot change anything (COG-86)" }
+    ];
   }
 });
 
@@ -36019,7 +36154,9 @@ async function restorePeerPresence(attempt = 0) {
     },
     agentSessionId: () => agentSessionId(),
     startedByWakeTurn: () => insideCodexWakeTurn(process.pid, ps()),
-    loadCredentials: () => loadCredentials(),
+    // COG-80: the identity THIS agent saved, not whichever agent registered in this folder last.
+    loadCredentials: () => restoreCandidate(),
+    restoreSkip: () => lastRestoreSkip,
     cwd: () => process.cwd(),
     recheckSeconds: Math.round(standbyRecheckMs() / 1e3),
     goOnline: async ({ peerId, endpoint, sessionId, token, cwd, label, peerSecret }) => {
@@ -36027,7 +36164,7 @@ async function restorePeerPresence(attempt = 0) {
       await reinitCloudBackend(endpoint, sessionId, token);
       const backend = getBackend();
       await backend.registerPeer(...presenceRegisterArgs({ peerId, sessionId, cwd, label, peerSecret }));
-      const slot = await loadCredentials();
+      const slot = await restoreCandidate();
       if (!stillCurrent() || slot?.sessionId !== sessionId || slot?.endpoint !== endpoint) {
         throw new Error(PRESENCE_SUPERSEDED);
       }
@@ -36159,9 +36296,20 @@ async function resolvePendingLabel() {
     logger.warn(`Post-connect label upgrade failed (non-fatal): ${err}`);
   }
 }
+async function restoreCandidate() {
+  const choice = chooseRestoreCredentials(
+    await loadCredentials(),
+    await loadPeerRecords(),
+    agentSessionId(),
+    getConfig().COGENT_PLATFORM
+  );
+  lastRestoreSkip = choice.skip;
+  return choice.creds;
+}
 async function reinitCloudBackend(endpoint, sessionId, token) {
   const config2 = getConfig();
   cloudHttpClient = new HttpClient(endpoint, token);
+  setCurrentCloudConnection({ endpoint, sessionId, token });
   const newBackend = new HttpBackend(cloudHttpClient, sessionId);
   resetBackend();
   initBackend(newBackend);
@@ -36266,6 +36414,7 @@ async function runStartup() {
     cloudInbox = new MessageInbox();
     bindInboxNotifier();
     cloudHttpClient = new HttpClient(effectiveEndpoint, effectiveToken);
+    setCurrentCloudConnection({ endpoint: effectiveEndpoint, sessionId: effectiveSessionId, token: effectiveToken });
     cloudWsClient = createCloudWsClient(
       effectiveEndpoint,
       effectiveSessionId,
@@ -36297,10 +36446,10 @@ async function runPreflights() {
       setSandboxOverride("bypass");
     }
   } else {
-    await preflightClaude(config2.COGENT_CLAUDE_PATH);
+    await preflightClaude(config2.COGENT_CLAUDE_PATH, readOnlyWake(config2));
   }
 }
-var UUID_V4_RE, execFileAsync3, PERSIST_PATH, legacyWarnEmitted, cloudWsClient, cloudInbox, cloudHttpClient, cloudModeActive, inboxNotifier, notifierBoundTo, reRegistrationInProgress, presenceRetry, ignoredHolders, presenceSupersedeBound, PRESENCE_SUPERSEDED, pendingLabelResolve;
+var UUID_V4_RE, execFileAsync3, PERSIST_PATH, legacyWarnEmitted, cloudWsClient, cloudInbox, cloudHttpClient, cloudModeActive, inboxNotifier, notifierBoundTo, reRegistrationInProgress, presenceRetry, ignoredHolders, presenceSupersedeBound, PRESENCE_SUPERSEDED, pendingLabelResolve, lastRestoreSkip;
 var init_startup = __esm({
   "src/startup.ts"() {
     "use strict";
@@ -36495,7 +36644,7 @@ function registerRegisterPeerTool(server) {
               new BridgeError(
                 "PEER_HELD_IN_FOLDER" /* PEER_HELD_IN_FOLDER */,
                 `'${peerId}' is held by another live connection in this folder (bridge pid ${holder.pid}, version ${registryText(holder.version)}); this bridge has NOT registered`,
-                heldNameAdvice(peerId)
+                heldNameAdvice(peerId, holder, { sessionId: own, platform: config2.COGENT_PLATFORM })
               )
             );
           }
@@ -36612,7 +36761,9 @@ function registerRegisterPeerTool(server) {
         let storedPeerSecret = argPeerSecret;
         if (storedPeerSecret === void 0 && isCloudMode()) {
           try {
-            storedPeerSecret = (await loadCredentials())?.peerSecret;
+            const own = await loadPeerRecord(peerId);
+            const folder = own ? null : await loadCredentials();
+            storedPeerSecret = own?.peerSecret ?? (!folder?.peerId || folder.peerId === peerId ? folder?.peerSecret : void 0);
           } catch {
             storedPeerSecret = void 0;
           }
@@ -36637,7 +36788,8 @@ function registerRegisterPeerTool(server) {
           let recovered;
           if (/PEER_NOT_YOURS/.test(msg) && isCloudMode()) {
             try {
-              const creds = await loadCredentials();
+              const folderCreds = await loadCredentials();
+              const creds = await loadPeerRecord(peerId) ?? (!folderCreds?.peerId || folderCreds.peerId === peerId ? folderCreds : null);
               if (creds?.ownerToken && creds.ownerToken !== creds.token && creds.endpoint && creds.sessionId) {
                 logger.warn(
                   `register_peer: '${peerId}' is owned by an earlier token (its peerSecret was lost by a pre-3.23.5 re-join). Re-proving ownership with the stored owner token.`
@@ -36659,7 +36811,7 @@ function registerRegisterPeerTool(server) {
                   recovered = await res.json();
                   const secret = recovered?.peerSecret;
                   if (secret) {
-                    await saveCredentials({ ...creds, peerId, peerSecret: secret, savedAt: (/* @__PURE__ */ new Date()).toISOString() });
+                    await savePeerRecord({ ...creds, peerId, peerSecret: secret, savedAt: (/* @__PURE__ */ new Date()).toISOString() });
                     logger.info(`register_peer: ownership reclaimed for '${peerId}'; a fresh peerSecret is stored.`);
                   }
                 }
@@ -36693,13 +36845,24 @@ function registerRegisterPeerTool(server) {
           try {
             const creds = await loadCredentials();
             const issuedSecret = peer?.peerSecret;
-            if (creds && (creds.peerId !== peerId || issuedSecret && creds.peerSecret !== issuedSecret)) {
-              await saveCredentials({
-                ...creds,
-                peerId,
-                ...issuedSecret ? { peerSecret: issuedSecret } : {},
+            const platform = getConfig().COGENT_PLATFORM;
+            const agent = { agentSession: (platform === "cc" ? agentSessionId() : void 0) ?? sessionId, platform };
+            if (creds) {
+              const channel = getCurrentCloudConnection() ?? { endpoint: creds.endpoint, sessionId: creds.sessionId, token: creds.token };
+              const mine = peerCredentials(creds, peerId);
+              const sameChannel = !!mine && mine.sessionId === channel.sessionId && mine.endpoint === channel.endpoint;
+              const secret = issuedSecret ?? (sameChannel ? mine.peerSecret : void 0);
+              const ownerToken = sameChannel ? mine.ownerToken ?? (mine.token !== channel.token ? mine.token : void 0) : void 0;
+              const label2 = creds.sessionId === channel.sessionId ? creds.label : sameChannel ? mine.label : void 0;
+              const entry = {
+                ...channel,
+                ...label2 ? { label: label2 } : {},
+                ...agent,
+                ...secret ? { peerSecret: secret } : {},
+                ...ownerToken ? { ownerToken } : {},
                 savedAt: (/* @__PURE__ */ new Date()).toISOString()
-              });
+              };
+              await saveCredentials({ ...entry, peerId, peers: { ...creds.peers ?? {}, [peerId]: entry } });
             }
           } catch (err) {
             logger.debug(
@@ -37819,7 +37982,8 @@ function registerDeregisterPeerTool(server) {
         const backend = getBackend();
         let ownershipProof;
         try {
-          ownershipProof = (await loadCredentials())?.peerSecret;
+          const folder = await loadCredentials();
+          ownershipProof = (await loadPeerRecord(peerId))?.peerSecret ?? (!folder?.peerId || folder.peerId === peerId ? folder?.peerSecret : void 0);
         } catch {
         }
         const { removed, mailboxDeprovisioned } = await backend.deregisterPeer(peerId, ownershipProof);
@@ -37840,6 +38004,7 @@ function registerDeregisterPeerTool(server) {
               await saveCredentials({ ...rest, savedAt: (/* @__PURE__ */ new Date()).toISOString() });
               logger.info("cleared stored peerId after deregister", { peerId });
             }
+            await deletePeerRecord(peerId);
           } catch (err) {
             logger.warn("failed to clear stored peerId after deregister", { error: err });
           }

package/hooks/check-on-stop.lib.mjs

@@ -21,6 +21,16 @@ export function parseScope(csv) {
   };
 }
 
+/**
+ * COG-88: are this agent's Claude wakes read-only? MUST equal src/config.ts readOnlyWake(loadConfig(env)):
+ * COGENT_READ_ONLY_WAKE truthy ("true"/"1"/"yes"/"on") OR COGENT_WAKE_TOOLS = "read", each trimmed and
+ * case-folded. Parity is tested against the REAL loadConfig (plugin/hooks/record-session.runtime.test.mjs).
+ */
+export function readOnlyWakeFromEnv(env) {
+  const v = (k) => String(env[k] ?? "").trim().toLowerCase();
+  return ["true", "1", "yes", "on"].includes(v("COGENT_READ_ONLY_WAKE")) || v("COGENT_WAKE_TOOLS") === "read";
+}
+
 /** sha256(path.resolve(cwd))[..16] — MUST equal credential-store.defaultCredentialPath's hash. */
 export function credHashForCwd(cwd) {
   return crypto.createHash("sha256").update(path.resolve(cwd)).digest("hex").slice(0, 16);
@@ -84,6 +94,27 @@ export function buildAgentSessionRecord(payload, nowIso) {
   };
 }
 
+/**
+ * Which saved identity this hook's agent is (COG-80). MUST follow src/cloud/credential-store.ts
+ * chooseRestoreCredentials + peerCredentials. `folder` is the folder file; its `peers` map holds one
+ * entry per registered peer. The top-level fields name the last-registered peer and are that peer's
+ * newest write. Returns null when the folder's names provably belong to other agents (stay silent
+ * rather than act as the other agent in the folder).
+ */
+export function chooseHookCredentials(folder, sessionId, platform) {
+  if (!folder) return null;
+  const records = Object.entries(folder.peers || {}).map(([peerId, e]) => ({ ...e, peerId }));
+  if (records.length === 0) return folder;
+  const resolve = (peerId) => (folder.peerId === peerId ? folder : { ...folder.peers[peerId], peerId });
+  const mine = sessionId ? records.filter((r) => r.agentSession === sessionId) : [];
+  if (mine.length > 0) return resolve(mine[0].peerId);
+  const sameKind = records.filter((r) => r.platform === platform);
+  if (sameKind.length === 1) return resolve(sameKind[0].peerId);
+  if (sameKind.length > 1 && folder.peerId && sameKind.some((r) => r.peerId === folder.peerId)) return folder;
+  if (sameKind.length === 0 && folder.peerId && !records.some((r) => r.peerId === folder.peerId)) return folder;
+  return null;
+}
+
 function isForMe(msg, me, scope) {
   if (msg.toPeerId === me) return scope.directed;
   if (msg.toPeerId === "*") {

package/hooks/check-on-stop.mjs

@@ -20,6 +20,8 @@ import {
   activeInFlightIds,
   agentSessionRecordPath,
   buildAgentSessionRecord,
+  chooseHookCredentials,
+  rootFromTranscriptPath,
 } from "./check-on-stop.lib.mjs";
 
 const HTTP_TIMEOUT_MS = 5000; // < the 8s hook timeout; only bites on a degraded relay
@@ -143,7 +145,9 @@ async function main() {
   if (envOff(env.COGENT_CHECK_ON_STOP)) return process.exit(0); // opt-out
   const cwd = input.cwd || process.cwd();
 
-  const creds = await readJson(credPath(cwd, env));
+  // COG-80: this agent's own record — the folder file names whichever agent registered last.
+  const creds = chooseHookCredentials(await readJson(credPath(cwd, env)), input.session_id,
+    rootFromTranscriptPath(input.transcript_path) ? "cc" : "codex");
   if (!creds || !creds.endpoint || !creds.sessionId || !creds.token) {
     return process.exit(0); // not registered in cloud mode → nothing to do
   }

package/hooks/record-session.mjs

@@ -1,8 +1,9 @@
 #!/usr/bin/env node
 // Cogent record-session. Runs on SessionStart as a SEPARATE short-lived process
 // (the host spawns it; it is NOT the bridge). Writes one small file and exits 0.
-// ALWAYS silent — it prints nothing on success or failure, so it can never block,
-// delay, or annotate a turn.
+// Silent, with ONE exception (COG-88, below): the once-only wake-permissions notice,
+// printed as {"systemMessage": ...} — valid SessionStart hook output that the host
+// shows to the human and never feeds to the model. It can never block or fail a turn.
 //
 // 🔴 WHY THIS EXISTS. Auto-wake has to find the agent's session transcript, and it
 // used to DERIVE the location:
@@ -23,10 +24,12 @@
 // Node built-ins only (fs, os, path). Byte-identical between plugin/hooks/ and
 // codex-plugin/hooks/ — enforced by scripts/wake-race-test.mjs assertContract().
 import fs from "node:fs/promises";
+import os from "node:os";
 import path from "node:path";
 import {
   agentSessionRecordPath,
   buildAgentSessionRecord,
+  readOnlyWakeFromEnv,
 } from "./check-on-stop.lib.mjs";
 
 async function readStdin() {
@@ -55,8 +58,70 @@ export async function persistRecord(record) {
   return target;
 }
 
+// ── COG-88: tell the human ONCE what a Cogent wake may do in this folder ──────────────
+// 3.25.9 made wakes read-only by default; 3.25.10 turned that back into an opt-in: the environment variable
+// COGENT_READ_ONLY_WAKE=true (or COGENT_WAKE_TOOLS=read). Nobody reads a changelog, so the person at the
+// terminal is told once, at a session start, what wakes can do and how to switch it.
+//
+// The mode is read from this hook's own env with the bridge's rule (readOnlyWakeFromEnv = readOnlyWake()).
+// Measured on Claude Code 2.1.302 and 2.1.74 (throwaway CLAUDE_CONFIG_DIR, probe plugin): a settings.json "env" value and
+// a shell export reach BOTH this hook and the plugin's MCP server, so the hook sees what the bridge sees.
+// Also measured: after a settings.json change, /reload-plugins does NOT restart the plugin's MCP server (it
+// keeps the old value), so the notice says "restart Claude Code".
+//
+// Shown ONLY when all hold:
+//   CLAUDECODE set                       — Claude Code. Codex never sets it (and shows systemMessage only
+//                                          after the first prompt).
+//   CLAUDE_CODE_SESSION_ATTENDED === "1" — a human is at the TUI ("0" in headless -p).
+//   COGENT_WAKE !== "1"                  — not inside a wake: the resumed claude runs this
+//                                          hook too (source "resume"), with the wake's env,
+//                                          and a notice there is swallowed but would still
+//                                          burn the once-only marker.
+//   the marker does not exist            — once per notice version.
+// Measured: Claude Code 2.1.302 gives a TUI SessionStart hook both variables; 2.1.74 gives it NEITHER (clean env, real
+// TUI), so on 2.1.74 the notice is never shown. Deliberate: nothing there tells a TUI from headless -p, and a
+// notice nobody sees would burn the marker. The opt-in itself still works on 2.1.74 (env reaches the bridge).
+// The marker is created with "wx" BEFORE printing, so two sessions starting together
+// cannot both show it, and it is never written unless the notice is printed.
+export const WAKE_NOTICE_MARKER = "wake-tools-notice-v1";
+
+export function wakeNoticeText(env) {
+  // Claude Code reads <CLAUDE_CONFIG_DIR>/settings.json when that variable is set; naming ~/.claude there
+  // would send the user to a file with no effect.
+  const dir = (env.CLAUDE_CONFIG_DIR || "").trim();
+  const settings = dir ? path.join(dir, "settings.json") : "~/.claude/settings.json";
+  if (readOnlyWakeFromEnv(env)) {
+    const names = ["COGENT_READ_ONLY_WAKE", "COGENT_WAKE_TOOLS"].filter((k) => readOnlyWakeFromEnv({ [k]: env[k] }));
+    const setting = names.join(" and ");
+    return (
+      `Cogent: wakes are read-only (${setting} ${names.length > 1 ? "are" : "is"} set) — when a Cogent message ` +
+      "wakes this agent, the wake can read files and answer, but cannot edit files or run commands. To let wakes " +
+      `edit again, remove ${setting} from the "env" block of ${settings} (or from your shell), then restart ` +
+      "Claude Code. (Shown once.)"
+    );
+  }
+  return (
+    "Cogent: when a Cogent message wakes this agent, the wake can edit files and run commands in this folder. " +
+    `To make wakes read-only, add "COGENT_READ_ONLY_WAKE": "true" to the "env" block of ${settings} ` +
+    "(or export it in your shell), then restart Claude Code. (Shown once.)"
+  );
+}
+
+async function maybeShowWakeNotice(env) {
+  if (!env.CLAUDECODE || env.CLAUDE_CODE_SESSION_ATTENDED !== "1" || env.COGENT_WAKE === "1") return;
+  const dir = env.CLAUDE_PLUGIN_DATA || path.join(os.homedir(), ".cogent", "notices");
+  await fs.mkdir(dir, { recursive: true });
+  // EEXIST (already shown) and every other failure throw → swallowed by the caller: silent.
+  await fs.writeFile(path.join(dir, WAKE_NOTICE_MARKER), `${new Date().toISOString()}\n`, { flag: "wx" });
+  const out = JSON.stringify({ systemMessage: wakeNoticeText(env) });
+  // Wait for the write: a pipe can be asynchronous (macOS), and exit() would cut it off.
+  await new Promise((resolve) => process.stdout.write(out, () => resolve()));
+}
+
 async function main() {
   const input = await readStdin();
+  // Independent of the record below, and never allowed to break it (or the session start).
+  await maybeShowWakeNotice(process.env).catch(() => {});
   const record = buildAgentSessionRecord(input, new Date().toISOString());
   // No transcript_path in this payload → nothing authoritative to record. The
   // resolver's discovery layer still covers this case; staying silent is correct.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@essentialai/cogent-plugin",
-  "version": "3.25.8",
+  "version": "3.25.10",
   "description": "Cogent — Claude Code plugin (skills + slash-commands + MCP server) for the cross-agent comms fabric.",
   "author": { "name": "Essential AI Solutions Ltd.", "url": "https://essentialai.uk" },
   "homepage": "https://cogent.tools",
@@ -10,6 +10,7 @@
   "files": [".claude-plugin", "commands", "skills", ".mcp.json", "hooks", "bridge", "README.md", "LICENSE"],
   "scripts": {
     "sync": "node scripts/sync-from-plugin.mjs",
+    "test": "node --test scripts/sync-from-plugin.test.mjs",
     "prepack": "node scripts/sync-from-plugin.mjs"
   }
 }