agents-can-communicate 0.7.0 → 0.8.0

package/node_modules/@agents-can-communicate/adapter-claude-code/src/adapter.mjs

@@ -2,18 +2,15 @@ import { defineAdapter, projectContext, projectContextResult }
   from "@agents-can-communicate/adapter-sdk";
 import certification from "../certification.json" with { type: "json" };
 
-import { PROTOCOL_CONTRACT } from "./channel.mjs";
 import { denyOutcome, injectOutcome, injectStartOwnerOutcome, normalizeClaudeHook } from "./hooks.mjs";
+import { MIN_VERSION, PROTOCOL_CONTRACT, bindNativeSession, offerMessage, planNativeActivation,
+  probeNativeDelivery, refreshNativeSession, retireNativeSession } from "./inbox-delivery.mjs";
 import { planClaudeInstall, detectClaude, installClaudePlugin, uninstallClaudePlugin } from "./install.mjs";
-import { bindNativeSession, offerMessage, planNativeActivation, probeNativeDelivery, routeReply }
-  from "./native-delivery.mjs";
 
 export const CLAUDE_CODE_VERSION = "2.1.233";
-export const CLAUDE_CHANNEL_MINIMUM = "2.1.258";
 export const CLAUDE_DELIVERY_FALLBACK = Object.freeze({
-  diagnostic: "Claude Code native delivery requires client-side Channels activation; "
-    + "a successful bootstrap or connected ACC MCP server does not prove inbound delivery "
-    + "is enabled. Messages remain durable for certified next-turn delivery or acc inbox",
+  diagnostic: `Claude Code live delivery wakes a session through its inbox socket from ${MIN_VERSION}; `
+    + "fallback: next-turn hooks or acc inbox",
 });
 
 /**
@@ -25,7 +22,8 @@ export const CLAUDE_DELIVERY_FALLBACK = Object.freeze({
  * and a parent/child mapping claimed without observation is the kind of thing
  * that quietly maps every child onto its parent. `startupInjection` and
  * `safePointInjection` were not exercised - only the before-turn path was.
- * Native live delivery and reply routing are not certified for this harness.
+ * Native live delivery is the inbox wake, certified from 2.1.282 on
+ * darwin-arm64; reply routing through the transport is not claimed.
  */
 export function createClaudeCodeAdapter() {
   return defineAdapter({
@@ -44,28 +42,22 @@ export function createClaudeCodeAdapter() {
       context: { beforeTurnInjection: true },
       // PreToolUse denied both a Write and a Bash call; neither ran.
       guards: { beforeWrite: true, beforeShell: true },
-      // nextTurn is the certified 2.1.233 hook projection; livePush and
-      // replyRoute rest on the 2.1.258 Channel capture and the native contract
-      // below. effectiveCapabilities() carries each of those captures forward
-      // to later clients; the native contract is the separate live rule.
-      delivery: { nextTurn: true, livePush: true, replyRoute: true },
+      // nextTurn is the certified 2.1.233 hook projection. livePush rests on
+      // the 2.1.282 product capture of the inbox wake; the reply is the
+      // ordinary `acc reply` every adapter has, so replyRoute stays false.
+      delivery: { nextTurn: true, livePush: true },
     },
-    // The first passing capture is the shipped minimum; the research lower
-    // bound (2.1.80) is documented but not admitted without its own capture.
-    //
-    // The 2.1.260 release capture is passing evidence beside this, deliberately
-    // not a second anchor: an anchor is the minimum's proof, one per platform,
-    // and this contract has no maximum precisely so a newer stable client is
-    // admitted by probe and a generation-bound handshake instead of by another
-    // anchor. That capture is what exercised the rule - every branch observed
-    // on 2.1.260 while the minimum stayed here. Two minor versions of drift,
-    // served without a capture at either of them, is the rule working.
+
+    // The first passing capture is the minimum, and there is no maximum: a
+    // newer stable client is admitted by the probe and the per-session
+    // handshake. The offer is a wake; see src/inbox-delivery.mjs.
     nativeDelivery: {
-      minimumByPlatform: { "darwin-arm64": CLAUDE_CHANNEL_MINIMUM },
-      anchors: [{ platform: "darwin-arm64", version: CLAUDE_CHANNEL_MINIMUM,
-        protocolContract: PROTOCOL_CONTRACT }],
+      minimumByPlatform: { "darwin-arm64": MIN_VERSION },
+      anchors: [{ platform: "darwin-arm64", version: MIN_VERSION, protocolContract: PROTOCOL_CONTRACT }],
       knownBad: [],
-      activationKinds: ["shell-bootstrap", "native-config"],
+      activationKinds: ["native-service"],
+      policySource: "installation-record",
+      offerKind: "wake",
     },
 
     startSession: async () => ({ ok: true, changes: [], diagnostics: [] }),
@@ -75,8 +67,7 @@ export function createClaudeCodeAdapter() {
 
     planInstall: context => planClaudeInstall(context),
     detect: context => detectClaude(context),
-    install: context => installClaudePlugin({ ...context,
-      livePolicy: context.livePolicy ?? "off" }),
+    install: context => installClaudePlugin(context),
     uninstall: context => uninstallClaudePlugin(context),
 
     doctor: async context => {
@@ -85,6 +76,9 @@ export function createClaudeCodeAdapter() {
         ...detected.diagnostics,
         "hook payloads captured from Claude Code 2.1.233",
         CLAUDE_DELIVERY_FALLBACK.diagnostic,
+        // Claude Code's own inbound control decides whether a wake reaches the
+        // model; ACC never attests a permission mode. Said only when it matters.
+        ...(detected.inboundDelivery.diagnostic === null ? [] : [detected.inboundDelivery.diagnostic]),
         // SessionEnd is advisory and cannot summarise a conversation that has
         // already stopped, so the handoff is written from Stop or the skill.
         "handoff is written while the model is active, not at SessionEnd",
@@ -94,8 +88,9 @@ export function createClaudeCodeAdapter() {
     probeNativeDelivery,
     planNativeActivation,
     bindNativeSession,
+    refreshNativeSession,
+    retireNativeSession,
     offerMessage,
-    routeReply,
 
     denyOutcome,
     injectOutcome,

package/node_modules/@agents-can-communicate/adapter-claude-code/src/hooks.mjs

@@ -50,6 +50,12 @@ export function normalizeClaudeHook(payload) {
     parentSessionId: typeof payload.agent_id === "string" ? payload.session_id : null,
     tool,
     targets: writeTargets(tool, payload.tool_input),
+    // Documented as conditional; SessionStart carried none on 2.1.233.
+    permissionMode: typeof payload.permission_mode === "string" && payload.permission_mode !== ""
+      ? payload.permission_mode : null,
+    // SessionEnd says why: "clear", "logout", "prompt_input_exit", "other".
+    endReason: event === "SessionEnd" && typeof payload.reason === "string" && payload.reason !== ""
+      ? payload.reason : null,
   });
 }
 

package/node_modules/@agents-can-communicate/adapter-claude-code/src/inbox-contract.mjs

@@ -0,0 +1,10 @@
+// The facts of the inbox transport every module of it shares, kept apart so
+// the endpoint record and the delivery methods import them without a cycle.
+
+export const PROTOCOL_CONTRACT = "claude-code-inbox-socket-v1";
+// The first release the inbox wake was captured on. 2.1.224 binds the socket,
+// but only 2.1.282 was observed firing UserPromptSubmit for a delivered frame,
+// and that is what brings the message body in with the wake.
+export const MIN_VERSION = "2.1.282";
+export const INBOX_MODES = Object.freeze(["livePush", "idleWake", "busyQueue"]);
+export const TRANSPORT = "claude-inbox";

package/node_modules/@agents-can-communicate/adapter-claude-code/src/inbox-delivery.mjs

@@ -0,0 +1,254 @@
+import net from "node:net";
+
+import { INBOX_MODES, MIN_VERSION, PROTOCOL_CONTRACT, TRANSPORT } from "./inbox-contract.mjs";
+import { claimWake, newEndpointId, readInboxEndpoint, releaseWake, removeInboxEndpoint,
+  sweepDeadEndpoints, writeInboxEndpoint } from "./inbox-endpoint.mjs";
+import { claudeConfigDir, readSessionRecord, verifyInbox } from "./inbox-registry.mjs";
+import { MANAGED_SETTINGS, permissionModeFromArgs, readInboundSettings, readProcessArgs, receptionOf }
+  from "./inbox-settings.mjs";
+
+// Live delivery into a Claude Code session through the inbox socket the
+// session itself binds (2.1.224 and later, no flag, every provider).
+//
+// The offer is a wake, never the message. Measured on 2.1.282: every frame a
+// session accepts on its inbox fires UserPromptSubmit, idle or between two tool
+// calls, and ACC's beforeTurn hook then projects the queued message inside its
+// untrusted block, with receipts and the `acc reply` route. So the frame
+// carries fixed ACC wording and the ACC message id, and no byte a peer wrote:
+// Claude Code frames every inbox message as a teammate's request to act on,
+// and the only thing a wake gives it to act on is ACC's own notice.
+//
+// The connection sends no auth line, and this module never reads the
+// session's messaging token or key file. A frame carrying that token would
+// pass as the session's own child and skip the inbound controls its user set.
+
+const LEASE_MS = 120_000;
+const MESSAGE_ID = /^[A-Za-z0-9_-]{1,200}$/;
+const PROBE_NEEDLE = Buffer.from("messagingSocketPath");
+const PROBE_MAX_BYTES = 256 * 1024 * 1024;
+const STABLE_VERSION = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:\+[0-9A-Za-z.-]+)?$/;
+
+export { INBOX_MODES, MIN_VERSION, PROTOCOL_CONTRACT, TRANSPORT };
+
+// Claude Code shows the wake as a message from another Claude session, so the
+// text names the ACC route: a model otherwise tries SendMessage first.
+export const wakeText = messageId => `ACC: new peer message ${messageId} for this session. `
+  + "This turn's ACC context shows it. If it does not, it was already shown, or read it with "
+  + `acc inbox --message ${messageId}. Answer it through ACC with acc reply --message ${messageId}; `
+  + "SendMessage cannot deliver to an ACC participant.";
+
+function compare(left, right) {
+  const a = left.split("+")[0].split(".").map(Number);
+  const b = right.split("+")[0].split(".").map(Number);
+  for (let index = 0; index < 3; index += 1) if (a[index] !== b[index]) return a[index] < b[index] ? -1 : 1;
+  return 0;
+}
+
+// The registry field only a build with the inbox writes. Read-only, bounded.
+async function executableHasInbox(realExecutable) {
+  let handle;
+  try {
+    handle = await (await import("node:fs/promises")).open(realExecutable, "r");
+  } catch {
+    return false;
+  }
+  try {
+    const chunk = Buffer.alloc(1024 * 1024);
+    let carry = Buffer.alloc(0);
+    let position = 0;
+    for (;;) {
+      const { bytesRead } = await handle.read(chunk, 0, chunk.length, position);
+      if (bytesRead === 0) return false;
+      const window = Buffer.concat([carry, chunk.subarray(0, bytesRead)]);
+      if (window.includes(PROBE_NEEDLE)) return true;
+      carry = window.subarray(Math.max(0, window.length - PROBE_NEEDLE.length));
+      position += bytesRead;
+      if (position >= PROBE_MAX_BYTES) return false;
+    }
+  } finally {
+    await handle.close().catch(() => null);
+  }
+}
+
+function defaultReadVersion(realExecutable, timeoutMs) {
+  return new Promise(resolve => {
+    import("node:child_process").then(({ execFile }) => {
+      execFile(realExecutable, ["--version"], { timeout: timeoutMs, windowsHide: true },
+        (error, stdout, stderr) => {
+          if (error !== null) return resolve(null);
+          resolve(/(\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?)/.exec(`${stdout}${stderr}`)?.[1] ?? null);
+        });
+    });
+  });
+}
+
+function withTimeout(work, ms) {
+  let timer = null;
+  const deadline = new Promise((_resolve, reject) => {
+    timer = setTimeout(() => reject(Object.assign(new Error("native probe timed out"),
+      { code: "ETIMEDOUT" })), ms);
+  });
+  return Promise.race([work, deadline]).finally(() => clearTimeout(timer));
+}
+
+/**
+ * Read-only: a stable version at or above the capture, a platform whose inbox
+ * is a Unix socket, and an executable that writes the inbox into its session
+ * registry. Never launches a session. Native Windows serves a named pipe that
+ * demands an auth line; nothing there is captured, so it keeps hook delivery.
+ */
+export async function probeNativeDelivery({ realExecutable, timeoutMs = 750, platform = process.platform,
+  hasInbox = executableHasInbox, readVersion = defaultReadVersion } = {}) {
+  const unsupported = (reasonCode, clientVersion = null) => ({ supported: false, clientVersion,
+    protocolContract: PROTOCOL_CONTRACT, executableFingerprint: null, modes: [], reasonCode });
+  if (platform === "win32") return unsupported("native_delivery_unsupported");
+  if (typeof realExecutable !== "string" || realExecutable === "") return unsupported("feature_probe_failed");
+  const clientVersion = await withTimeout(Promise.resolve(readVersion(realExecutable, timeoutMs)), timeoutMs)
+    .catch(() => null);
+  if (clientVersion === null || !STABLE_VERSION.test(clientVersion)) {
+    return unsupported("feature_probe_failed", clientVersion);
+  }
+  if (compare(clientVersion, MIN_VERSION) < 0) return unsupported("below_minimum_version", clientVersion);
+  const present = await withTimeout(Promise.resolve(hasInbox(realExecutable)), timeoutMs).catch(() => false);
+  if (!present) return unsupported("protocol_mismatch", clientVersion);
+  return { supported: true, clientVersion, protocolContract: PROTOCOL_CONTRACT,
+    executableFingerprint: null, modes: [...INBOX_MODES], reasonCode: null };
+}
+
+// Claude Code runs the inbox itself. ACC starts nothing and rewrites no argument.
+export function planNativeActivation({ detection }) {
+  if (typeof detection?.realExecutable !== "string" || detection.realExecutable === "") {
+    return { eligible: false, reasonCode: "feature_probe_failed", mechanisms: [] };
+  }
+  return { eligible: true, reasonCode: null, mechanisms: [{ kind: "native-service",
+    serviceId: "claude-code-inbox", preExisting: true, applyCommand: null, teardownCommand: null }] };
+}
+
+const closed = (clientVersion, reasonCode) => ({ supported: false, clientVersion: clientVersion ?? null,
+  protocolContract: PROTOCOL_CONTRACT, modes: [], opaqueEndpointRef: null, leaseUntil: null, reasonCode });
+const handshake = (endpoint, now) => ({ supported: true, clientVersion: endpoint.clientVersion,
+  protocolContract: PROTOCOL_CONTRACT, modes: [...INBOX_MODES], opaqueEndpointRef: endpoint.endpointId,
+  leaseUntil: new Date(now() + LEASE_MS).toISOString(), reasonCode: null });
+
+/**
+ * Bind this ACC session to the inbox of the Claude process whose hook is
+ * running. The socket comes from the hook's own environment, which Claude Code
+ * exports per session and never inherits from a parent; the registry must
+ * name this process and this socket before anything is published. The session
+ * id is checked by every offer and refresh, since after /resume the registry
+ * catches up only once the hook has run.
+ */
+export async function bindNativeSession({ event, clientPid, clientVersion, runtimeDir,
+  env = process.env, now = Date.now, managedSettingsPath = MANAGED_SETTINGS[process.platform],
+  readClientArgs = readProcessArgs } = {}) {
+  if (!Number.isInteger(clientPid) || clientPid <= 0) return closed(clientVersion, "client_process_unknown");
+  if (typeof event?.sessionId !== "string" || event.sessionId === "") {
+    return closed(clientVersion, "handshake_failed");
+  }
+  if (typeof clientVersion !== "string" || !STABLE_VERSION.test(clientVersion)) {
+    return closed(clientVersion, "version_unavailable");
+  }
+  // The contract refuses it anyway, after this returns. Refusing here keeps an
+  // older client - which binds again on every turn - from writing an endpoint
+  // record each time.
+  if (compare(clientVersion, MIN_VERSION) < 0) return closed(clientVersion, "below_minimum_version");
+  const socketPath = env?.CLAUDE_CODE_MESSAGING_SOCKET;
+  if (typeof socketPath !== "string" || socketPath === "") {
+    return closed(clientVersion, "native_endpoint_unavailable");
+  }
+  await sweepDeadEndpoints({ runtimeDir });
+  const configDir = claudeConfigDir(env);
+  const refused = await verifyInbox({ configDir, clientPid, sessionId: event.sessionId, socketPath,
+    anyConversation: true });
+  if (refused !== null) return closed(clientVersion, refused);
+  // Project settings sit where the session was started, which the registry
+  // records; the hook's cwd follows the shell.
+  const record = await readSessionRecord({ configDir, clientPid });
+  const settings = await readInboundSettings({ configDir, projectDir: record?.cwd ?? event.cwd,
+    managedSettingsPath });
+  // The hook's mode is current. SessionStart carries none, so until the first
+  // prompt the launch flag stands in, then the configured default.
+  const launchMode = event.permissionMode == null
+    ? permissionModeFromArgs(await readClientArgs(clientPid).catch(() => null)) : null;
+  const reception = receptionOf({
+    permissionMode: event.permissionMode ?? launchMode ?? settings.defaultMode,
+    crossSessionInbound: settings.crossSessionInbound });
+  const endpoint = { schemaVersion: 1, endpointId: newEndpointId(), socketPath, configDir, clientPid,
+    sessionId: event.sessionId, clientVersion, protocolContract: PROTOCOL_CONTRACT,
+    leaseUntil: new Date(now() + LEASE_MS).toISOString(), reception };
+  try {
+    await writeInboxEndpoint({ runtimeDir, record: endpoint });
+  } catch {
+    return closed(clientVersion, "handshake_failed");
+  }
+  return handshake(endpoint, now);
+}
+
+async function verifiedEndpoint(binding, runtimeDir) {
+  const endpoint = await readInboxEndpoint({ runtimeDir, endpointId: binding?.opaqueEndpointRef });
+  if (endpoint === null) return null;
+  const refused = await verifyInbox({ configDir: endpoint.configDir, clientPid: endpoint.clientPid,
+    sessionId: endpoint.sessionId, socketPath: endpoint.socketPath });
+  return refused === null ? endpoint : null;
+}
+
+// The router calls this when a lease ran out, so a session that sits idle
+// between turns stays reachable. The id never changes on a refresh.
+export async function refreshNativeSession({ binding, runtimeDir, now = Date.now } = {}) {
+  const endpoint = await verifiedEndpoint(binding, runtimeDir);
+  return endpoint === null ? closed(binding?.clientVersion, "handshake_failed") : handshake(endpoint, now);
+}
+
+export const retireNativeSession = ({ binding, runtimeDir }) =>
+  removeInboxEndpoint({ runtimeDir, endpointId: binding?.opaqueEndpointRef });
+
+/**
+ * Sender side: re-verify the receiver, then write one wake line. The socket
+ * answers nothing, so acceptance is a line written to a verified inbox without
+ * an error inside the timeout. What the model then sees is recorded by the
+ * receiver's own hook.
+ */
+export async function offerMessage({ binding, message, runtimeDir, timeoutMs = 2_000,
+  connect = net.createConnection } = {}) {
+  const rejected = safeErrorCode => ({ accepted: false, transport: TRANSPORT,
+    clientVersion: binding?.clientVersion ?? null, safeErrorCode });
+  if (typeof message?.messageId !== "string" || !MESSAGE_ID.test(message.messageId)) {
+    return rejected("transport_rejected");
+  }
+  const endpoint = await verifiedEndpoint(binding, runtimeDir);
+  if (endpoint === null) return rejected("recipient_unavailable");
+  // The receiver's own crossSessionInbound refuses unattested wakes; one would
+  // be dropped, so none is sent and the message waits for its next turn.
+  if (endpoint.reception === "refused") return rejected("delivery_disabled");
+  const accepted = { accepted: true, transport: TRANSPORT, clientVersion: endpoint.clientVersion,
+    ...(endpoint.reception === "held" ? { pendingApproval: true } : {}) };
+  const wake = { runtimeDir, endpointId: endpoint.endpointId, messageId: message.messageId };
+  // Claude Code delivers a repeated msg_id again, so the dedupe is ours.
+  let first;
+  try {
+    first = await claimWake(wake);
+  } catch {
+    return rejected("transport_error");
+  }
+  if (!first) return accepted;
+  const frame = `${JSON.stringify({ type: "user",
+    message: { role: "user", content: wakeText(message.messageId) },
+    msg_id: `acc-wake-${message.messageId}` })}\n`;
+  const result = await new Promise(resolve => {
+    const socket = connect(endpoint.socketPath);
+    let settled = false;
+    const finish = value => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      socket.destroy();
+      resolve(value);
+    };
+    const timer = setTimeout(() => finish(rejected("transport_error")), timeoutMs);
+    socket.once("error", error => finish(rejected(["EPERM", "EACCES"].includes(error?.code)
+      ? "transport_permission_denied" : "recipient_unavailable")));
+    socket.once("connect", () => socket.end(frame, () => finish(accepted)));
+  });
+  if (!result.accepted) await releaseWake(wake);
+  return result;
+}

package/node_modules/@agents-can-communicate/adapter-claude-code/src/inbox-endpoint.mjs

@@ -0,0 +1,166 @@
+import { randomBytes } from "node:crypto";
+import { constants } from "node:fs";
+import { lstat, mkdir, open, readdir, realpath, rename, rm } from "node:fs/promises";
+import path from "node:path";
+
+import { PROTOCOL_CONTRACT } from "./inbox-contract.mjs";
+import { inboxSocketIsSafe } from "./inbox-registry.mjs";
+import { isReception } from "./inbox-settings.mjs";
+
+// One private record per hook binding, the way the Codex adapter keeps its
+// daemon endpoints: core holds only the random id, and the socket path, pid and
+// session id stay in a 0600 file under the workspace runtime directory.
+
+const KEYS = ["schemaVersion", "endpointId", "socketPath", "configDir", "clientPid", "sessionId",
+  "clientVersion", "protocolContract", "leaseUntil", "reception"];
+const ENDPOINT = /^claude_inbox_[a-f0-9]{32}$/;
+const STABLE = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:\+[0-9A-Za-z.-]+)?$/;
+const MAX_BYTES = 8_192;
+const absolute = value => typeof value === "string" && path.isAbsolute(value) && !value.includes("\0");
+const own = info => typeof process.getuid !== "function" || info.uid === process.getuid();
+const invalid = () => new Error("invalid Claude inbox endpoint registration");
+
+export const newEndpointId = () => `claude_inbox_${randomBytes(16).toString("hex")}`;
+
+function valid(record) {
+  return record !== null && typeof record === "object" && !Array.isArray(record)
+    && Object.keys(record).length === KEYS.length && KEYS.every(key => Object.hasOwn(record, key))
+    && record.schemaVersion === 1 && ENDPOINT.test(record.endpointId)
+    && absolute(record.socketPath) && absolute(record.configDir)
+    && Number.isInteger(record.clientPid) && record.clientPid > 0
+    && typeof record.sessionId === "string" && record.sessionId !== "" && record.sessionId.length <= 200
+    && typeof record.clientVersion === "string" && STABLE.test(record.clientVersion)
+    && record.protocolContract === PROTOCOL_CONTRACT
+    && typeof record.leaseUntil === "string"
+    && /^\d{4}-\d\d-\d\dT\d\d:\d\d:\d\d\.\d{3}Z$/.test(record.leaseUntil)
+    && Number.isFinite(Date.parse(record.leaseUntil))
+    && isReception(record.reception);
+}
+
+async function directory(runtimeDir, create = false) {
+  if (!absolute(runtimeDir)) throw invalid();
+  if (create) await mkdir(runtimeDir, { recursive: true, mode: 0o700 });
+  const root = await realpath(runtimeDir);
+  const dir = path.join(root, "claude-inbox-endpoints");
+  if (create) await mkdir(dir, { mode: 0o700 }).catch(error => {
+    if (error.code !== "EEXIST") throw error;
+  });
+  const info = await lstat(dir);
+  if (!info.isDirectory() || info.isSymbolicLink() || !own(info) || (info.mode & 0o022) !== 0) throw invalid();
+  return dir;
+}
+
+export async function writeInboxEndpoint({ runtimeDir, record }) {
+  if (!valid(record) || !await inboxSocketIsSafe(record.socketPath)) throw invalid();
+  const text = `${JSON.stringify(record)}\n`;
+  if (Buffer.byteLength(text) > MAX_BYTES) throw invalid();
+  const dir = await directory(runtimeDir, true);
+  const file = path.join(dir, `${record.endpointId}.json`);
+  const temporary = path.join(dir, `.${record.endpointId}.${randomBytes(8).toString("hex")}.tmp`);
+  let handle;
+  try {
+    handle = await open(temporary, "wx", 0o600);
+    await handle.writeFile(text, "utf8");
+    await handle.close(); handle = null;
+    await rename(temporary, file);
+  } finally {
+    await handle?.close().catch(() => null);
+    await rm(temporary, { force: true }).catch(() => null);
+  }
+}
+
+// An expired record is metadata for re-verification, never proof of reach.
+export async function readInboxEndpoint({ runtimeDir, endpointId }) {
+  if (typeof endpointId !== "string" || !ENDPOINT.test(endpointId)) return null;
+  let handle;
+  try {
+    const dir = await directory(runtimeDir);
+    handle = await open(path.join(dir, `${endpointId}.json`),
+      constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+    const info = await handle.stat();
+    if (!info.isFile() || !own(info) || info.size > MAX_BYTES || (info.mode & 0o077) !== 0) return null;
+    const record = JSON.parse(await handle.readFile("utf8"));
+    return valid(record) && record.endpointId === endpointId ? record : null;
+  } catch {
+    return null;
+  } finally {
+    await handle?.close().catch(() => null);
+  }
+}
+
+export async function removeInboxEndpoint({ runtimeDir, endpointId }) {
+  if (typeof endpointId !== "string" || !ENDPOINT.test(endpointId)) return;
+  try {
+    const dir = await directory(runtimeDir);
+    await rm(path.join(dir, `${endpointId}.json`), { force: true });
+  } catch { /* retirement is already recorded; cleanup is best effort */ }
+  try {
+    await rm(path.join(await wakesDirectory(runtimeDir), endpointId), { recursive: true, force: true });
+  } catch { /* the same */ }
+}
+
+const processExists = pid => {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error.code === "EPERM";
+  }
+};
+
+/**
+ * A Claude Code process that crashed ran no SessionEnd, so its binding was never
+ * retired. Only a record whose process is gone is removed: a live session whose
+ * registry briefly names another conversation (right after /resume) keeps its own.
+ */
+export async function sweepDeadEndpoints({ runtimeDir, exists = processExists, limit = 64 }) {
+  let names;
+  try {
+    names = await readdir(await directory(runtimeDir));
+  } catch {
+    return;
+  }
+  for (const name of names.filter(item => /^claude_inbox_[a-f0-9]{32}\.json$/.test(item)).slice(0, limit)) {
+    const endpointId = name.slice(0, -".json".length);
+    const record = await readInboxEndpoint({ runtimeDir, endpointId });
+    if (record !== null && !exists(record.clientPid)) await removeInboxEndpoint({ runtimeDir, endpointId });
+  }
+}
+
+// One empty marker per message a binding woke. A wake leaves the receipt
+// queued until the receiver's hook commits it, so a replayed send reaches the
+// transport again; the marker keeps it to one wake per message and binding.
+const WAKE_MESSAGE = /^[A-Za-z0-9_-]{1,200}$/;
+
+async function wakesDirectory(runtimeDir, create = false) {
+  const dir = path.join(path.dirname(await directory(runtimeDir, create)), "claude-inbox-wakes");
+  if (create) await mkdir(dir, { mode: 0o700 }).catch(error => {
+    if (error.code !== "EEXIST") throw error;
+  });
+  const info = await lstat(dir);
+  if (!info.isDirectory() || info.isSymbolicLink() || !own(info) || (info.mode & 0o022) !== 0) throw invalid();
+  return dir;
+}
+
+/** True when this call is the first to wake the binding for the message. */
+export async function claimWake({ runtimeDir, endpointId, messageId }) {
+  if (!ENDPOINT.test(endpointId) || !WAKE_MESSAGE.test(messageId)) throw invalid();
+  const dir = path.join(await wakesDirectory(runtimeDir, true), endpointId);
+  await mkdir(dir, { mode: 0o700 }).catch(error => {
+    if (error.code !== "EEXIST") throw error;
+  });
+  try {
+    await (await open(path.join(dir, messageId), "wx", 0o600)).close();
+    return true;
+  } catch (error) {
+    if (error.code === "EEXIST") return false;
+    throw error;
+  }
+}
+
+export async function releaseWake({ runtimeDir, endpointId, messageId }) {
+  if (!ENDPOINT.test(endpointId) || !WAKE_MESSAGE.test(messageId)) return;
+  try {
+    await rm(path.join(await wakesDirectory(runtimeDir), endpointId, messageId), { force: true });
+  } catch { /* a marker left behind only suppresses a repeat wake */ }
+}

package/node_modules/@agents-can-communicate/adapter-claude-code/src/inbox-registry.mjs

@@ -0,0 +1,71 @@
+import { constants } from "node:fs";
+import { lstat, open, realpath } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+
+// Claude Code's own record of a live session: `<config>/sessions/<pid>.json`
+// names the session id and the inbox socket it listens on. ACC reads that file
+// and nothing beside it - never the `<pid>.<hash>.key` next to it.
+
+const MAX_BYTES = 16_384;
+const own = info => typeof process.getuid !== "function" || info.uid === process.getuid();
+
+export const claudeConfigDir = env => typeof env?.CLAUDE_CONFIG_DIR === "string"
+  && path.isAbsolute(env.CLAUDE_CONFIG_DIR)
+  ? env.CLAUDE_CONFIG_DIR : path.join(os.homedir(), ".claude");
+
+/** The registry entry for one pid, or null. Bounded, owner-checked, never through a link. */
+export async function readSessionRecord({ configDir, clientPid }) {
+  if (!Number.isInteger(clientPid) || clientPid <= 0 || typeof configDir !== "string") return null;
+  let handle;
+  try {
+    handle = await open(path.join(configDir, "sessions", `${clientPid}.json`),
+      constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+    const info = await handle.stat();
+    if (!info.isFile() || !own(info) || info.size > MAX_BYTES) return null;
+    const record = JSON.parse(await handle.readFile("utf8"));
+    return record?.pid === clientPid && typeof record.sessionId === "string" && record.sessionId !== ""
+      && typeof record.messagingSocketPath === "string" && path.isAbsolute(record.messagingSocketPath)
+      ? { pid: record.pid, sessionId: record.sessionId, messagingSocketPath: record.messagingSocketPath,
+        cwd: typeof record.cwd === "string" && path.isAbsolute(record.cwd) ? record.cwd : null }
+      : null;
+  } catch {
+    return null;
+  } finally {
+    await handle?.close().catch(() => null);
+  }
+}
+
+/** A socket this user owns, reached without a link, closed to group and others. */
+export async function inboxSocketIsSafe(socketPath) {
+  if (typeof socketPath !== "string" || !path.isAbsolute(socketPath)) return false;
+  try {
+    const info = await lstat(socketPath);
+    return info.isSocket() && !info.isSymbolicLink() && own(info) && (info.mode & 0o077) === 0;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Whether this socket is the inbox of this session, right now.
+ *
+ * The socket path alone proves nothing: pids are reused, and a new process
+ * gets a new registry entry under the same name. Requiring the registry to
+ * name both this session id and this socket is what keeps a wake from reaching
+ * whatever process holds the pid later. Returns null, or the reason it is not.
+ *
+ * `anyConversation` is for the bind alone. Claude Code runs SessionStart for a
+ * /resume before it rewrites the entry, so there the hook's own process and
+ * socket are the proof; every offer and refresh still requires the session id.
+ */
+export async function verifyInbox({ configDir, clientPid, sessionId, socketPath, anyConversation = false }) {
+  if (!await inboxSocketIsSafe(socketPath)) return "native_endpoint_unavailable";
+  const record = await readSessionRecord({ configDir, clientPid });
+  if (record === null || (!anyConversation && record.sessionId !== sessionId)) {
+    return "native_session_unavailable";
+  }
+  const [registered, expected] = await Promise.all([
+    realpath(record.messagingSocketPath).catch(() => null), realpath(socketPath).catch(() => null)]);
+  return registered !== null && registered === expected ? null : "native_session_unavailable";
+}