agents-can-communicate 0.3.1 → 0.4.0

package/README.md

@@ -12,6 +12,11 @@ Think of the coordination you expect from subagents, extended across the indepen
 sessions you open yourself — with different clients and models. You keep giving them
 ordinary tasks; they handle the conversations around their work.
 
+Active hooks supply each agent's own CLI arguments in coordination context; the installed
+skill tells the agent to use them. This path was observed in Claude Code 2.1.263 and
+Codex 0.153.4. Hooks must be enabled and trusted by the client. Without hook context, owner
+operations require an explicit pair or session-bound ACC MCP tools. See [CLI ownership](docs/CLI.md#coordinate-from-a-session).
+
 [Try it](#try-it) · [Supported clients](#when-messages-arrive) · [Documentation](docs/index.md)
 
 [![CI](https://github.com/automatis-tools/agents-can-communicate/actions/workflows/ci.yml/badge.svg)](https://github.com/automatis-tools/agents-can-communicate/actions/workflows/ci.yml)
@@ -40,6 +45,14 @@ Claude → Codex   I'll use that shape and keep my changes in the UI files.
 The agents identify who to talk to and what to agree on. Your prompts stay focused on
 the feature you want to build.
 
+The same setup supports a review and handoff. Ask one session to implement a change and
+request review of an identified revision: a commit when Git is available, or named files
+and version otherwise. Ask the other to return blocking defects or approval. The author
+can address the verdict before finishing, or leave a durable handoff so a later session
+can recover what is complete and what remains. See the
+[review request](docs/CLI.md#messages-and-requests) and [handoff](docs/CLI.md#handoff)
+commands behind that flow.
+
 Each session keeps its own conversation and instructions. Response timing depends on the
 receiving client: see [when messages arrive](#when-messages-arrive).
 
@@ -55,6 +68,9 @@ acc install
 
 The installer connects the clients it finds. Open a new terminal and restart your AI
 clients to load the integration. If you use Codex, accept its plugin trust prompt.
+ACC then keeps its runtime and skills updated in the background, waiting for active clients
+to exit before switching versions. [Update controls](docs/UPGRADING.md#automatic-updates-after-installation)
+include manual update, opt-out, and version pinning.
 
 Open two sessions in your project and give them ordinary tasks, as in the example above.
 On supported clients, ACC introduces peer awareness through the client's own integration;
@@ -79,13 +95,17 @@ session can pick them up later. Delivery depends on the client:
 | Codex CLI, Claude Code, Gemini CLI, Kimi Code | At the next normal turn on verified versions and platforms; otherwise by checking its ACC inbox. |
 | Grok or another client connected through [MCP](docs/MCP.md) | By checking its ACC inbox. |
 
-**Claude Code can also reply while idle.** This optional mode is experimental and off by
-default. It supports Apple Silicon Macs with zsh and Claude Code 2.1.258 or newer, subject
-to compatibility checks. It can spend model tokens and requires accepting Claude's
-development-channel warning at startup. Messages arriving mid-turn wait for it to finish.
+**Codex and Claude Code can also reply while idle.** These optional modes are
+experimental, off by default, and can spend model tokens. On Apple Silicon Macs,
+Codex 0.152.1 or newer requires an already-running LocalDaemon and an exact session
+check; ACC preserves your ordinary launch command. Claude Code 2.1.258 or newer
+requires zsh and its development-channel warning at startup. Messages arriving
+mid-turn wait for it to finish.
 
-Each direction follows the receiving client's rules: Claude's reply won't start a new
-Codex turn. Codex can pick it up on a supported next turn or by checking its inbox.
+Each direction follows the receiving client's policy and current reachability.
+A Codex thread retained by LocalDaemon can receive opted-in messages after its
+terminal exits. Turn ACC delivery off to prevent new native offers; already accepted
+queue entries remain with the client.
 
 [Full compatibility details](docs/CAPABILITIES.md).
 
@@ -96,7 +116,8 @@ Codex turn. Codex can pick it up on a supported next turn or by checking its inb
 - **Separate checkouts, one project.** Git worktrees share an ACC workspace.
   Plain project folders work too; Git is optional.
 - **Agree before editing.** Agents can reserve files and identify overlapping work.
-  Reservations are advisory unless the clients support enforcement.
+  CLI reservations default to advisory. `--enforcement guarded` requests enforcement,
+  which still requires certified guards from every live participant.
   [How reservations work](docs/CONCEPTS.md#intent-is-awareness-a-claim-commits).
 - **Local coordination.** Messages live in app data outside your project. ACC doesn't
   collect or share raw transcripts. Your clients use their usual model providers.

package/SECURITY.md

@@ -19,7 +19,7 @@ version. A reproduction against a throwaway `ACC_DATA_HOME` is ideal.
 | Peer text escaping its quoted block | An attacker who already has write access to your data home |
 | Any path escaping the managed root | A model choosing to obey persuasive peer text |
 | Uninstall deleting files ACC did not write | Vulnerabilities in Codex, Claude Code, Gemini, Grok, or Kimi themselves |
-| ACC writing into a repository | Denial of service by a trusted peer |
+| Unexpected ACC runtime/state or installer artifacts in a repository (excluding user-requested `acc.workspace.json`) | Denial of service by a trusted peer |
 | Session impersonation across MCP | |
 
 Reasoning behind each: [docs/SECURITY_MODEL.md](docs/SECURITY_MODEL.md).

package/bin/acc-bootstrap.mjs

@@ -1,56 +1,7 @@
 #!/usr/bin/env node
-// Internal entry point behind an ACC-owned shell shim: is this exact vendor
-// executable eligible for native delivery right now? Exit 0 means yes and the
-// shim exports its owned policy before `exec`; any other exit - including a
-// crash, a missing adapter, or a damaged install - means the shim launches the
-// vendor command untouched. Nothing is ever written to stdout, and stderr stays
-// empty unless ACC_BOOTSTRAP_DEBUG=1 asks for one safe line.
-import { checkNativeBootstrap } from "@agents-can-communicate/installer";
+import { fileURLToPath } from "node:url";
+import { invokedDirectly, runEntry } from "@agents-can-communicate/cli/managed-entry";
 
-import { createClaudeCodeAdapter } from "@agents-can-communicate/adapter-claude-code";
-import { createCodexAdapter } from "@agents-can-communicate/adapter-codex";
-import { createGeminiCliAdapter } from "@agents-can-communicate/adapter-gemini-cli";
-import { createGrokAdapter } from "@agents-can-communicate/adapter-grok";
-import { createKimiAdapter } from "@agents-can-communicate/adapter-kimi";
-
-const FLAGS = new Map([["--adapter", "adapter"], ["--real-executable", "realExecutable"],
-  ["--data-home", "dataHome"]]);
-
-function debug(line) {
-  if (process.env.ACC_BOOTSTRAP_DEBUG === "1") process.stderr.write(`acc-bootstrap: ${line}\n`);
-}
-
-function parse(args) {
-  const options = {};
-  for (let index = 0; index < args.length; index += 2) {
-    const key = FLAGS.get(args[index]);
-    const value = args[index + 1];
-    if (key === undefined || typeof value !== "string" || value === "" || key in options) return null;
-    options[key] = value;
-  }
-  return FLAGS.values().every(key => key in options) ? options : null;
-}
-
-try {
-  const options = parse(process.argv.slice(2));
-  if (options === null) {
-    debug("usage: --adapter <id> --real-executable <path> --data-home <path>");
-    process.exit(2);
-  }
-  const registry = {
-    claude_code: createClaudeCodeAdapter, codex: createCodexAdapter,
-    gemini_cli: createGeminiCliAdapter, grok: createGrokAdapter, kimi: createKimiAdapter,
-  };
-  const adapter = registry[options.adapter]?.();
-  if (adapter === undefined) {
-    debug(`${options.adapter}: unknown adapter`);
-    process.exit(1);
-  }
-  const result = await checkNativeBootstrap({ adapter, realExecutable: options.realExecutable,
-    platform: `${process.platform}-${process.arch}`, dataHome: options.dataHome, timeoutMs: 750 });
-  debug(`${options.adapter}: ${result.supported ? "supported" : result.reasonCode}`);
-  process.exit(result.supported ? 0 : 1);
-} catch (error) {
-  debug(`failed: ${String(error?.code ?? error?.name ?? "error")}`);
-  process.exit(1);
-}
+if (invokedDirectly(import.meta.url)) await runEntry({
+  kind: "acc-bootstrap", packageRoot: fileURLToPath(new URL("..", import.meta.url)),
+});

package/bin/acc-claude-channel.mjs

@@ -1,177 +1,10 @@
 #!/usr/bin/env node
-// The ACC Channel binary Claude Code spawns as a stdio MCP child. It composes
-// the same workspace discovery, session binding, core service, and local
-// data-home rules as acc-hook, opens a session-scoped endpoint for the delivery
-// router, and turns the model's explicit acc_reply / acc_ack into real ACC
-// records. It never collects a transcript or runs a model, and it fails open:
-// any composition error leaves Claude a plain MCP server that simply offers no
-// tools rather than crashing the session.
-import { randomBytes } from "node:crypto";
-import { realpathSync } from "node:fs";
-import path from "node:path";
 import { fileURLToPath } from "node:url";
-
-import { createClaudeCodeAdapter } from "@agents-can-communicate/adapter-claude-code";
-import { listSessionBindings } from "@agents-can-communicate/adapter-sdk";
-import { createCoordinationService } from "@agents-can-communicate/core";
-import { resolveClientPid } from "@agents-can-communicate/hook-runner/client-pid";
-import { readProcessTable } from "@agents-can-communicate/hook-runner/process-table";
-import { createId } from "@agents-can-communicate/protocol";
-import { openFilesystemStore } from "@agents-can-communicate/storage-filesystem";
-import { createGitProbe, discoverWorkspace, platformDataHome, runtimePaths }
-  from "@agents-can-communicate/cli";
-
-import { createAccChannel, createInertChannel, endpointDir, routeAck, routeReply }
-  from "@agents-can-communicate/adapter-claude-code/channel";
-
-const clock = { now: () => new Date().toISOString() };
-const ids = { next: kind => createId(kind, randomBytes) };
-
-/**
- * The ACC session this Claude process opened - decided by which client process
- * this Channel is running under, never by how many sessions happen to be
- * visible.
- *
- * There used to be a fallback here: if exactly one session was live, it was
- * taken to be this one. On a single-session machine that looked safe, and with
- * two sessions it silently handed one client the other's identity. The Channel
- * starts while its own SessionStart hook is still writing its binding, so the
- * only binding a second client can see at that moment is the *first* client's -
- * and the wait that was added to survive that race then locks the wrong answer
- * in on the first attempt, because it is a complete, live, plausible binding.
- *
- * Measured on two real 2.1.259 sessions: both Channels registered an endpoint
- * under the first client's pid. `bindNativeSession` refuses two registrations
- * for one pid, so the session that had been receiving live messages dropped
- * back to the durable inbox - and an `acc_reply` from the second window would
- * have been recorded as the first session's answer, which is a false record
- * rather than a lost message.
- *
- * This process was spawned by its client, so its own ancestry names that
- * client, and no race can change that. Ownership is decided by it.
- */
-export async function resolveSession({ runtimeDir, service, env, ownClientPid,
-  listBindings = listSessionBindings }) {
-  if (!Number.isInteger(ownClientPid)) return null;
-  const bindings = await listBindings({ runtimeDir });
-  if (bindings.length === 0) return null;
-  const status = await service.collectStatus({});
-  const live = new Set(status.participants
-    .filter(participant => participant.presence !== "offline")
-    .map(participant => participant.sessionId));
-  const mine = bindings.filter(binding => live.has(binding.accSessionId)
-    && binding.clientPid === ownClientPid);
-  // One client process can outlive a session and open another, so the pid alone
-  // can still name two. The harness session id the client exports separates
-  // them; with nothing to separate them the answer is nobody, as before.
-  const exported = new Set(Object.values(env ?? {}).filter(value => typeof value === "string"));
-  const matched = mine.filter(binding => exported.has(binding.harnessSessionId));
-  const chosen = mine.length === 1 ? mine[0] : matched.length === 1 ? matched[0] : null;
-  return chosen === null ? null
-    : { sessionId: chosen.accSessionId, generation: chosen.generation, clientPid: chosen.clientPid };
-}
-
-/** The client process this Channel was spawned by, or null when nobody knows. */
-export async function ownClient({ table = null, from = process.pid,
-  command = createClaudeCodeAdapter().client.command } = {}) {
-  return resolveClientPid({ table: table ?? await readProcessTable(), from, command });
-}
-
-// How long the Channel will wait for the hook to publish this session's
-// binding. Claude spawns this child while SessionStart is still running - both
-// landed in the same second on a real 2.1.259 launch - and a single lookup
-// loses that race often enough to make native delivery activate or not per
-// launch. Bounded, because a session with no ACC binding must still be answered.
-const BINDING_WAIT_MS = 5_000;
-const BINDING_POLL_MS = 100;
-
-/**
- * The session binding, once it exists - or null when the wait runs out.
- *
- * A binding with no `clientPid` names no process, and the Channel binds an
- * exact one, so it does not count as resolved: the hook writes the identity
- * first and the certified facts after, and reading in between must keep waiting
- * rather than settle for the half-written answer.
- */
-export async function resolveWithin({ resolve, deadline, intervalMs = BINDING_POLL_MS,
-  now = () => Date.now(), sleep = ms => new Promise(resolve_ => setTimeout(resolve_, ms)) }) {
-  for (;;) {
-    const session = await resolve();
-    if (session !== null && Number.isInteger(session?.clientPid)) return session;
-    if (now() >= deadline) return null;
-    await sleep(intervalMs);
-  }
-}
-
-async function main() {
-  const descriptor = await discoverWorkspace({ cwd: process.cwd(), env: process.env,
-    gitProbe: createGitProbe() });
-  const paths = runtimePaths({ dataHome: platformDataHome({ platform: process.platform,
-    env: process.env }), workspaceId: descriptor.id, workspaceRoots: descriptor.roots });
-  const store = await openFilesystemStore({ root: paths.root, clock, ids,
-    workspaceId: descriptor.id });
-  const service = createCoordinationService({ store, clock, ids });
-  const write = payload => process.stdout.write(`${JSON.stringify(payload)}\n`);
-  // Read once: the ancestry that decides ownership cannot change while this
-  // process runs, and re-reading it on every poll would spawn `ps` in a loop.
-  const clientPid = await ownClient();
-  const session = await resolveWithin({
-    resolve: () => resolveSession({ runtimeDir: paths.root, service, env: process.env,
-      ownClientPid: clientPid }),
-    deadline: Date.now() + BINDING_WAIT_MS });
-  // No binding to serve - but Claude is already speaking MCP to this child, and
-  // returning here left the event loop empty: the process exited in 75ms
-  // without answering `initialize`, and Claude reported the server as failed to
-  // connect on every session that enables the plugin without ACC's shim.
-  if (session === null || !Number.isInteger(session.clientPid)) {
-    const inert = createInertChannel({ write });
-    pump(inert.handleLine, () => process.exit(0));
-    return inert;
-  }
-
-  const channel = createAccChannel({
-    endpointDir: endpointDir(paths.root),
-    clientPid: session.clientPid,
-    write,
-    routeReply: ({ messageId, body }) => routeReply({ service, session, messageId, body }),
-    routeAck: ({ messageId }) => routeAck({ service, session, messageId }),
-    // This process is the only party that knows the endpoint is still being
-    // served, and Claude publishes no heartbeat, so nothing else would move
-    // ACC's lease while the session sits idle - which is when live delivery is
-    // worth having.
-    refreshBinding: leaseUntil => service.refreshDeliveryBinding({
-      sessionId: session.sessionId, generation: session.generation, leaseUntil }),
-  });
-  await channel.listen();
-  pump(channel.handleLine, () => { channel.close(); process.exit(0); });
-  return channel;
-}
-
-/** One line-delimited JSON pump, for the bound server and the unbound one alike. */
-function pump(handleLine, shutdown) {
-  let buffer = "";
-  process.stdin.setEncoding("utf8");
-  process.stdin.on("data", async chunk => {
-    buffer += chunk;
-    let newline = buffer.indexOf("\n");
-    while (newline !== -1) {
-      const line = buffer.slice(0, newline).trim();
-      buffer = buffer.slice(newline + 1);
-      newline = buffer.indexOf("\n");
-      if (line !== "") await handleLine(line);
-    }
-  });
-  process.stdin.on("end", shutdown);
-  process.once("SIGTERM", shutdown);
-  process.once("SIGINT", shutdown);
-  // Keeps the child answerable for as long as Claude holds the transport open.
-  process.stdin.resume();
-}
-
-const invokedDirectly = typeof process.argv[1] === "string"
-  && realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url));
-if (invokedDirectly) {
-  // Fail open: a Channel that cannot compose is simply absent, never a crash in
-  // front of the user's session.
-  await main().catch(() => { process.stdin.resume(); });
-}
+import { invokedDirectly, runEntry } from "@agents-can-communicate/cli/managed-entry";
+export const resolveSession = async options => (await import("./entrypoints/acc-claude-channel.mjs")).resolveSession(options);
+export const ownClient = async options => (await import("./entrypoints/acc-claude-channel.mjs")).ownClient(options);
+export const resolveWithin = async options => (await import("./entrypoints/acc-claude-channel.mjs")).resolveWithin(options);
+
+if (invokedDirectly(import.meta.url)) await runEntry({
+  kind: "acc-claude-channel", packageRoot: fileURLToPath(new URL("..", import.meta.url)),
+});

package/bin/acc-hook.mjs

@@ -1,137 +1,8 @@
 #!/usr/bin/env node
-// Hook entry point: `acc-hook <adapter-id> <kind>`, payload on stdin.
-//
-// Every harness runs this as a short-lived child process in front of the user's
-// turn. The one rule that overrides all others here: never be the reason
-// someone's session stops working. Unknown adapter, malformed payload, broken
-// store, missing binding - all of them end in "allow, exit 0".
-import { randomBytes } from "node:crypto";
-import { realpathSync } from "node:fs";
 import { fileURLToPath } from "node:url";
+import { invokedDirectly, runEntry } from "@agents-can-communicate/cli/managed-entry";
+export { writeOutput, completeHookOutput } from "./entrypoints/hook-output.mjs";
 
-import { createId } from "@agents-can-communicate/protocol";
-import { runHook } from "@agents-can-communicate/hook-runner";
-
-import { createClaudeCodeAdapter } from "@agents-can-communicate/adapter-claude-code";
-import { createCodexAdapter } from "@agents-can-communicate/adapter-codex";
-import { createGeminiCliAdapter } from "@agents-can-communicate/adapter-gemini-cli";
-import { createGrokAdapter } from "@agents-can-communicate/adapter-grok";
-import { createKimiAdapter } from "@agents-can-communicate/adapter-kimi";
-
-const adapters = {
-  claude_code: createClaudeCodeAdapter(),
-  codex: createCodexAdapter(),
-  gemini_cli: createGeminiCliAdapter(),
-  grok: createGrokAdapter(),
-  kimi: createKimiAdapter(),
-};
-
-const readStdin = () => new Promise(resolve => {
-  // A hook is always given its payload on stdin, but a client that closes it
-  // without writing must not leave this process hanging in front of a turn.
-  if (process.stdin.isTTY) return resolve("");
-  let raw = "";
-  process.stdin.setEncoding("utf8");
-  process.stdin.on("data", chunk => { raw += chunk; });
-  process.stdin.on("end", () => resolve(raw));
-  process.stdin.on("error", () => resolve(""));
-  return undefined;
+if (invokedDirectly(import.meta.url)) await runEntry({
+  kind: "acc-hook", packageRoot: fileURLToPath(new URL("..", import.meta.url)),
 });
-
-export const writeOutput = (stream, output, { deadlineAt } = {}) => {
-  if (output === "") return Promise.resolve();
-  return new Promise((resolve, reject) => {
-    let settled = false;
-    let timer;
-    const finish = error => {
-      if (settled) return;
-      settled = true;
-      if (timer !== undefined) clearTimeout(timer);
-      if (error === undefined || error === null) resolve();
-      else reject(error);
-    };
-    if (deadlineAt !== undefined) {
-      const remaining = deadlineAt - Date.now();
-      if (remaining <= 0) {
-        finish(new Error("hook budget exhausted before stdout write"));
-        return;
-      }
-      timer = setTimeout(() => finish(
-        new Error("hook budget exhausted waiting for stdout callback")), remaining);
-    }
-    try {
-      stream.write(output, finish);
-    } catch (error) {
-      finish(error);
-    }
-  });
-};
-
-const DIAGNOSTIC_BYTES = 512;
-
-function boundedDiagnostic(label, error) {
-  const detail = String(error?.message ?? error).replace(/[\u0000-\u001f\u007f]/g, " ");
-  let line = `acc: ${label}: ${detail}`;
-  while (Buffer.byteLength(`${line}\n`, "utf8") > DIAGNOSTIC_BYTES && line.length > 0) {
-    line = line.slice(0, -1);
-  }
-  return `${line}\n`;
-}
-
-function tryWrite(stream, output) {
-  if (output === "") return;
-  try {
-    stream.write(output, () => {});
-  } catch {
-    // A broken diagnostic stream must not turn a failed-open hook into a crash.
-  }
-}
-
-export async function completeHookOutput(result,
-  { stdout = process.stdout, stderr = process.stderr } = {}) {
-  try {
-    await writeOutput(stdout, result.stdout ?? "", { deadlineAt: result.deadlineAt });
-  } catch (error) {
-    tryWrite(stderr, boundedDiagnostic("stdout write failed", error));
-    return { exitCode: 0, wroteStdout: false, committedOffers: false };
-  }
-
-  let committedOffers = true;
-  try {
-    await result.commitOffers?.();
-  } catch (error) {
-    committedOffers = false;
-    tryWrite(stderr, boundedDiagnostic("offer commit failed", error));
-  }
-  if (result.stderr) tryWrite(stderr, `${result.stderr}\n`);
-  return { exitCode: 0, wroteStdout: true, committedOffers };
-}
-
-async function main() {
-  const [adapterId] = process.argv.slice(2);
-
-  let payload = null;
-  try {
-    payload = JSON.parse(await readStdin());
-  } catch {
-    payload = null;
-  }
-
-  const result = await runHook({ adapterId, payload, adapters,
-    runtime: { clock: { now: () => new Date().toISOString() },
-      ids: { next: kind => createId(kind, randomBytes) } },
-    env: process.env });
-
-  const completed = await completeHookOutput(result);
-  process.exitCode = result.exitCode ?? completed.exitCode;
-}
-
-let isMain = false;
-try {
-  isMain = process.argv[1] !== undefined
-    && realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url));
-} catch {
-  isMain = false;
-}
-
-if (isMain) await main();

package/bin/acc-mcp.mjs

@@ -1,62 +1,7 @@
 #!/usr/bin/env node
-import { randomBytes } from "node:crypto";
+import { fileURLToPath } from "node:url";
+import { invokedDirectly, runEntry } from "@agents-can-communicate/cli/managed-entry";
 
-import { EXIT, createId } from "@agents-can-communicate/protocol";
-import { createCoordinationService } from "@agents-can-communicate/core";
-import { createDeliveryRouter } from "@agents-can-communicate/delivery-router";
-import { openFilesystemStore } from "@agents-can-communicate/storage-filesystem";
-import { ALL_ADAPTERS, createGitProbe, discoverWorkspace, platformDataHome, runtimePaths }
-  from "@agents-can-communicate/cli";
-import { serve } from "@agents-can-communicate/mcp-server";
-
-// The composition root is the only place allowed to reach for ambient time and
-// randomness. The participant name comes from configuration, never from the
-// client: the protocol says clientInfo is self-reported and must not drive
-// behaviour, and the session is derived from this configuration alone.
-// Nothing is read from the command line, so nothing may be passed on it. It
-// used to accept and ignore anything: writing `acc-mcp --cwd <project>` - the
-// habit `acc` teaches - started a server rooted wherever the client happened to
-// launch it, alone in a workspace nobody else was in, with no warning at all.
-if (process.argv.length > 2) {
-  process.stderr.write("acc-mcp takes no arguments. It is configured by environment:\n"
-    + "  ACC_MCP_PARTICIPANT   who this server takes part as (default: mcp)\n"
-    + "  ACC_MCP_WORKSPACE     the project it joins (default: the working directory)\n"
-    + `refusing: ${process.argv.slice(2).join(" ")}\n`);
-  process.exit(EXIT.USAGE);
-}
-
-const participantId = process.env.ACC_MCP_PARTICIPANT ?? "mcp";
-const clock = { now: () => new Date().toISOString() };
-const ids = { next: kind => createId(kind, randomBytes) };
-
-const descriptor = await discoverWorkspace({
-  cwd: process.env.ACC_MCP_WORKSPACE ?? process.cwd(),
-  env: process.env,
-  gitProbe: createGitProbe(),
-});
-const paths = runtimePaths({
-  dataHome: platformDataHome({ platform: process.platform, env: process.env }),
-  workspaceId: descriptor.id,
-  workspaceRoots: descriptor.roots,
+if (invokedDirectly(import.meta.url)) await runEntry({
+  kind: "acc-mcp", packageRoot: fileURLToPath(new URL("..", import.meta.url)),
 });
-const store = await openFilesystemStore({ root: paths.root, clock, ids,
-  workspaceId: descriptor.id });
-const service = createCoordinationService({ store, clock, ids });
-const adapters = Object.fromEntries(ALL_ADAPTERS().map(adapter => [adapter.id, adapter]));
-
-await serve({
-  input: process.stdin,
-  output: process.stdout,
-  log: message => process.stderr.write(`acc-mcp: ${message}\n`),
-  context: {
-    service,
-    deliveryRouter: createDeliveryRouter({ service, adapters, clock }),
-    workspaceId: descriptor.id,
-    participantId,
-    descriptor,
-    runtimeDir: paths.root,
-  },
-});
-
-// Exiting on stdin EOF is the only portable graceful shutdown in this binding.
-process.exitCode = 0;

package/bin/acc-update-worker.mjs

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+// Private detached updater. It never opens workspace state or runs a model.
+import path from "node:path";
+import { runWorker, recordWorkerFailure } from "@agents-can-communicate/cli/managed-worker";
+const [root, ...extra] = process.argv.slice(2);
+if (typeof root === "string" && path.isAbsolute(root) && extra.length === 0) {
+  await runWorker(root, { wait: true }).catch(error => recordWorkerFailure(root, error));
+}

package/bin/acc.mjs

@@ -1,41 +1,7 @@
 #!/usr/bin/env node
-import { randomBytes } from "node:crypto";
-import { readFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+import { invokedDirectly, runEntry } from "@agents-can-communicate/cli/managed-entry";
 
-import { createId } from "@agents-can-communicate/protocol";
-import { createDeliveryRouter } from "@agents-can-communicate/delivery-router";
-import { ALL_ADAPTERS, askConfirmation, main } from "@agents-can-communicate/cli";
-
-const adapters = Object.fromEntries(ALL_ADAPTERS().map(adapter => [adapter.id, adapter]));
-
-// The composition root is the only place allowed to reach for ambient time and
-// randomness; everything below it receives them as ports.
-const runtime = {
-  cwd: process.cwd(),
-  env: process.env,
-  platform: process.platform,
-  stdout: process.stdout,
-  stderr: process.stderr,
-  clock: { now: () => new Date().toISOString() },
-  ids: { next: kind => createId(kind, randomBytes) },
-  createDeliveryRouter: ({ service, clock }) =>
-    createDeliveryRouter({ service, adapters, clock }),
-  // Asked only by `acc config init`, and only when stdout is a terminal. There
-  // was no port here at all, so the question went to the fallback that always
-  // answers no: in a real terminal the command printed "not written" and never
-  // said why, and `--yes` - the flag documented for runs with nobody to ask -
-  // was the only way to write the file.
-  confirm: (question, io = { input: process.stdin, output: process.stdout }) =>
-    askConfirmation(question, io),
-  // The two streams and the fact that a person is at both ends, for the
-  // per-client native delivery question `acc install` asks only interactively.
-  input: process.stdin,
-  output: process.stdout,
-  isInteractive: () => process.stdin.isTTY === true && process.stdout.isTTY === true,
-  // Asked for only by `acc version`, so a package missing its own manifest
-  // fails that one command rather than every command.
-  version: async () => JSON.parse(
-    await readFile(new URL("../package.json", import.meta.url), "utf8")).version,
-};
-
-process.exitCode = await main(process.argv.slice(2), runtime);
+if (invokedDirectly(import.meta.url)) await runEntry({
+  kind: "acc", packageRoot: fileURLToPath(new URL("..", import.meta.url)),
+});

package/bin/entrypoints/acc-bootstrap.mjs

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+// Internal entry point behind an ACC-owned shell shim: is this exact vendor
+// executable eligible for native delivery right now? Exit 0 means yes and the
+// shim exports its owned policy before `exec`; any other exit - including a
+// crash, a missing adapter, or a damaged install - means the shim launches the
+// vendor command untouched. Nothing is ever written to stdout, and stderr stays
+// empty unless ACC_BOOTSTRAP_DEBUG=1 asks for one safe line.
+import { checkNativeBootstrap } from "@agents-can-communicate/installer";
+
+import { createClaudeCodeAdapter } from "@agents-can-communicate/adapter-claude-code";
+import { createCodexAdapter } from "@agents-can-communicate/adapter-codex";
+import { createGeminiCliAdapter } from "@agents-can-communicate/adapter-gemini-cli";
+import { createGrokAdapter } from "@agents-can-communicate/adapter-grok";
+import { createKimiAdapter } from "@agents-can-communicate/adapter-kimi";
+
+import { parseBootstrapOptions } from "@agents-can-communicate/cli/managed-entry";
+
+function debug(line) {
+  if (process.env.ACC_BOOTSTRAP_DEBUG === "1") process.stderr.write(`acc-bootstrap: ${line}\n`);
+}
+
+export async function main() {
+try {
+  const options = parseBootstrapOptions(process.argv.slice(2));
+  if (options === null) {
+    debug("usage: --adapter <id> --real-executable <path> --data-home <path>");
+    process.exit(2);
+  }
+  const registry = {
+    claude_code: createClaudeCodeAdapter, codex: createCodexAdapter,
+    gemini_cli: createGeminiCliAdapter, grok: createGrokAdapter, kimi: createKimiAdapter,
+  };
+  const adapter = registry[options.adapter]?.();
+  if (adapter === undefined) {
+    debug(`${options.adapter}: unknown adapter`);
+    process.exit(1);
+  }
+  const result = await checkNativeBootstrap({ adapter, realExecutable: options.realExecutable,
+    platform: `${process.platform}-${process.arch}`, dataHome: options.dataHome, timeoutMs: 750 });
+  debug(`${options.adapter}: ${result.supported ? "supported" : result.reasonCode}`);
+  process.exit(result.supported ? 0 : 1);
+} catch (error) {
+  debug(`failed: ${String(error?.code ?? error?.name ?? "error")}`);
+  process.exit(1);
+}
+
+}