agents-can-communicate 0.3.1 → 0.4.1

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

package/bin/entrypoints/acc-claude-channel.mjs

@@ -0,0 +1,149 @@
+#!/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 { 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, endpointDir, routeAck, routeReply }
+  from "@agents-can-communicate/adapter-claude-code/channel";
+
+import { pump, startInertChannel } from "./claude-channel-stdio.mjs";
+
+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 compose() {
+  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)) {
+    return startInertChannel({ write });
+  }
+
+  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;
+}
+
+export async function main() {
+  await compose().catch(() => startInertChannel());
+}

package/bin/entrypoints/acc-hook.mjs

@@ -0,0 +1,58 @@
+#!/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 { 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;
+});
+
+import { completeHookOutput } from "./hook-output.mjs";
+
+export 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;
+}

package/bin/entrypoints/acc-mcp.mjs

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+import { randomBytes } from "node:crypto";
+
+import { EXIT, createId } from "@agents-can-communicate/protocol";
+import { createCoordinationService } from "@agents-can-communicate/core";
+import { readInstalledLivePolicy } from "@agents-can-communicate/installer";
+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";
+
+export async function main({ managerRoot = null, packageRoot } = {}) {
+// 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 dataHome = platformDataHome({ platform: process.platform, env: process.env });
+const paths = runtimePaths({
+  dataHome,
+  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 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,
+      platform: `${process.platform}-${process.arch}`,
+      readLivePolicy: ({ adapter }) => readInstalledLivePolicy({ dataHome,
+        adapterId: adapter.id }) }),
+    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/entrypoints/acc.mjs

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+import { randomBytes } from "node:crypto";
+import { readFile } from "node:fs/promises";
+
+import { createId } from "@agents-can-communicate/protocol";
+import { readInstalledLivePolicy } from "@agents-can-communicate/installer";
+import { createDeliveryRouter } from "@agents-can-communicate/delivery-router";
+import { ALL_ADAPTERS, askConfirmation, main as runCli } from "@agents-can-communicate/cli";
+
+export async function main({ managerRoot = null, packageRoot, managementOnly = false } = {}) {
+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(),
+  managerRoot,
+  managementOnly,
+  packageRoot,
+  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, dataHome }) =>
+    createDeliveryRouter({ service, adapters, clock,
+      platform: `${process.platform}-${process.arch}`,
+      readLivePolicy: ({ adapter }) => readInstalledLivePolicy({ dataHome,
+        adapterId: adapter.id }) }),
+  // 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 runCli(process.argv.slice(2), runtime);
+
+}

package/bin/entrypoints/claude-channel-stdio.mjs

@@ -0,0 +1,29 @@
+// Workspace-free MCP fallback shared by composition and managed admission failure.
+import { createInertChannel } from "@agents-can-communicate/adapter-claude-code/channel";
+
+export function startInertChannel({ write = payload => process.stdout.write(JSON.stringify(payload) + "\n") } = {}) {
+  const inert = createInertChannel({ write });
+  pump(inert.handleLine, () => process.exit(0));
+  return inert;
+}
+
+/** One line-delimited JSON pump, for the bound server and the unbound one alike. */
+export 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();
+}

package/bin/entrypoints/hook-output.mjs

@@ -0,0 +1,77 @@
+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 } = {}) {
+  if (result.failed || result.timedOut) {
+    // Only a known code selects static recovery advice. Arbitrary payload or
+    // filesystem error text must never become client-visible instructions.
+    const recovery = result.failureCode === "workspace_contains_runtime"
+      ? ": workspace contains ACC runtime state; open a project directory and restart the client"
+        + " (or set ACC_DATA_HOME outside the workspace)"
+      : "";
+    tryWrite(stderr, `acc: coordination unavailable${recovery}; hook continued without context\n`);
+  }
+  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 };
+}