agents-can-communicate 0.7.1 → 0.8.0

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";
+}

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

@@ -0,0 +1,109 @@
+import { execFile } from "node:child_process";
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+
+// What Claude Code does with a wake from a sender that attests no permission
+// mode - ACC never attests one. A session that bypasses permission prompts
+// holds it for approval; `crossSessionInbound` overrides that both ways. ACC
+// reads the same inputs so the sender is told what will happen, and never
+// changes any of them.
+
+const MAX_BYTES = 256 * 1024;
+const RECEPTIONS = Object.freeze(["delivered", "held", "refused"]);
+
+export const MANAGED_SETTINGS = Object.freeze({
+  darwin: "/Library/Application Support/ClaudeCode/managed-settings.json",
+  linux: "/etc/claude-code/managed-settings.json",
+  win32: "C:\\Program Files\\ClaudeCode\\managed-settings.json",
+});
+
+async function readSettings(file) {
+  try {
+    const text = await readFile(file, "utf8");
+    if (Buffer.byteLength(text) > MAX_BYTES) return null;
+    const value = JSON.parse(text);
+    return value !== null && typeof value === "object" && !Array.isArray(value) ? value : null;
+  } catch {
+    return null;
+  }
+}
+
+const text = value => (typeof value === "string" && value !== "" ? value : null);
+
+/**
+ * The two inputs, each from the first file that sets it, in Claude Code's own
+ * order: managed policy, then the project's local and shared settings, then
+ * the user's.
+ */
+export async function readInboundSettings({ configDir, projectDir, managedSettingsPath }) {
+  const files = [managedSettingsPath,
+    ...(typeof projectDir === "string" && path.isAbsolute(projectDir)
+      ? [path.join(projectDir, ".claude", "settings.local.json"),
+        path.join(projectDir, ".claude", "settings.json")] : []),
+    path.join(configDir, "settings.json")].filter(file => typeof file === "string");
+  const layers = await Promise.all(files.map(readSettings));
+  const first = pick => layers.map(layer => (layer === null ? null : pick(layer))).find(value => value !== null)
+    ?? null;
+  return {
+    crossSessionInbound: first(layer => text(layer.crossSessionInbound)),
+    defaultMode: first(layer => text(layer.permissions?.defaultMode)),
+  };
+}
+
+/**
+ * The permission mode a Claude Code process was started with, from its own
+ * arguments, or null. Only the two flags are read; nothing else is kept.
+ */
+export function permissionModeFromArgs(args) {
+  if (!Array.isArray(args)) return null;
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === "--dangerously-skip-permissions") return "bypassPermissions";
+    if (arg === "--permission-mode") return text(args[index + 1]);
+    if (typeof arg === "string" && arg.startsWith("--permission-mode=")) {
+      return text(arg.slice("--permission-mode=".length));
+    }
+  }
+  return null;
+}
+
+/** A process's arguments as `ps` prints them, split on spaces, or null. */
+export function readProcessArgs(pid, { timeoutMs = 500 } = {}) {
+  if (!Number.isInteger(pid) || pid <= 0 || process.platform === "win32") return Promise.resolve(null);
+  return new Promise(resolve => {
+    execFile("ps", ["-o", "args=", "-p", String(pid)], { timeout: timeoutMs, maxBuffer: 64 * 1024 },
+      (error, stdout) => resolve(error ? null : String(stdout).trim().split(/\s+/).filter(Boolean)));
+  });
+}
+
+export function receptionOf({ permissionMode, crossSessionInbound }) {
+  if (crossSessionInbound === "accept") return "delivered";
+  if (crossSessionInbound === "refuse") return "refused";
+  if (crossSessionInbound === "hold" || permissionMode === "bypassPermissions") return "held";
+  return "delivered";
+}
+
+export const isReception = value => RECEPTIONS.includes(value);
+
+/**
+ * What `acc doctor` tells a person who turned live delivery on: the machine-wide
+ * view, from managed policy and the user's settings. A project can still set
+ * its own value; the bind reads that one per session.
+ */
+export async function inboundStatus({ configDir, managedSettingsPath }) {
+  const userFile = path.join(configDir, "settings.json");
+  for (const file of [managedSettingsPath, userFile].filter(item => typeof item === "string")) {
+    const value = text((await readSettings(file))?.crossSessionInbound);
+    if (value === "accept") return { state: "accepted", diagnostic: null };
+    if (value === "refuse") {
+      return { state: "refused", diagnostic: `crossSessionInbound is "refuse" in ${file}, so `
+        + "Claude Code drops every ACC wake; messages arrive with each next turn; set it to "
+        + "\"accept\" for live delivery" };
+    }
+    if (value !== null) break;
+  }
+  return { state: "attention", diagnostic: "a session that bypasses permission prompts asks "
+    + `before each ACC wake; add "crossSessionInbound": "accept" to ${userFile} to take wakes `
+    + "without asking; the next turn shows the message either way" };
+}
+