agents-can-communicate 0.2.0 → 0.3.0

package/README.md

@@ -79,12 +79,21 @@ Messages commit before any delivery attempt. `queued`, `offered`, `retrieved`, a
 not proof of model attention, and a reply resolves communication rather than proving a
 requested task finished.
 
-Durable inbox recovery is the baseline for every client. Certified next-turn injection can
-reduce the polling, but only for the exact client version and platform captured by the
-adapter. Native live push is opt-in and would also require a current reachable binding;
-**no shipped adapter currently has passing live-push certification**. The failed Codex
-0.152.0 and Claude Code 2.1.252 captures are shipped as evidence, so ACC reports fallback
-instead of claiming realtime delivery.
+Durable inbox recovery is the baseline for every client. Certified next-turn injection
+reduces the polling for the exact captured client version and platform. Native live push is
+opt-in, experimental, and off until you choose it: **Claude Code 2.1.258 and Codex 0.152.1
+on macOS arm64 have passing live-push captures** and deliver an addressed message into a
+running session through the vendor's own transport, falling back to the durable inbox on any
+failure. Every other client, and any client below the captured minimum, stays next-turn or
+inbox only. The retained failed captures are shipped beside the passing ones as honest
+evidence.
+
+| Client | Native delivery |
+|---|---|
+| Claude Code 2.1.258 (darwin-arm64) | experimental Channel: idle offer, queue-after-turn, native reply, off until opt-in |
+| Codex 0.152.1 (darwin-arm64) | experimental App Server queue: idle/after-turn, reply via `acc reply`, off until opt-in |
+| Gemini CLI, Kimi Code | next-turn or inbox only; no captured transparent transport |
+| Grok | awaiting a compatibility capture; inbox only |
 
 ## What ACC owns
 
@@ -101,7 +110,8 @@ be guaranteed.
 
 ## Documentation
 
-Start with [Getting started](docs/GETTING_STARTED.md), then use the
+Start with [Getting started](docs/GETTING_STARTED.md), then read
+[How ACC works](docs/HOW_IT_WORKS.md) for the end-to-end engineering tour or use the
 [documentation map](docs/index.md). The exact surfaces are in the [CLI](docs/CLI.md),
 [MCP](docs/MCP.md), [Protocol](docs/PROTOCOL.md), and
 [Capabilities](docs/CAPABILITIES.md) references. Adapter evidence lives beside each

package/bin/acc-bootstrap.mjs

@@ -0,0 +1,56 @@
+#!/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";
+
+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);
+}

package/bin/acc-claude-channel.mjs

@@ -0,0 +1,177 @@
+#!/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(); });
+}

package/bin/acc.mjs

@@ -25,8 +25,13 @@ const runtime = {
   // 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 => askConfirmation(question,
-    { input: process.stdin, output: process.stdout }),
+  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(

package/docs/ADAPTER_AUTHORING.md

@@ -90,6 +90,37 @@ Unreadable, unknown, or mismatched clients degrade every uncertified row to fals
 The backing methods for delivery are `renderContextResult()` for `nextTurn`,
 `offerMessage()` for `livePush`, and `routeReply()` for `replyRoute`.
 
+### Native delivery contract
+
+An adapter that can push a message into a running session declares `nativeDelivery` next
+to its capabilities:
+
+```js
+nativeDelivery: {
+  minimumByPlatform: { "darwin-arm64": "2.1.258" },
+  anchors: [{ platform: "darwin-arm64", version: "2.1.258",
+    protocolContract: "claude-code-channel-mcp-v1" }],
+  knownBad: [],
+  activationKinds: ["shell-bootstrap"],
+}
+```
+
+The rules `defineAdapter` enforces, and the ones the runtime applies:
+
+- A minimum is the **first passing capture** on that platform, never a guessed first vendor
+  release. Every anchor must have passing `delivery.livePush` evidence for the same client,
+  version, and platform, and each minimum must itself be an anchor.
+- There is intentionally **no maximum version**. A newer stable release is admitted only
+  when a current read-only feature probe (`probeNativeDelivery()`) and a per-session
+  handshake (`bindNativeSession()`) both report the anchored `protocolContract`;
+  `evaluateNativeEligibility()` and `validateNativeHandshake()` are those two checks.
+- Prereleases require their own passing capture; they are `prerelease_not_captured` even
+  when numerically newer. `knownBad` names exact versions or inclusive intervals.
+- Exact-version certification still governs every non-native capability;
+  `effectiveCapabilities()` is unchanged. The native rule is used for live delivery alone.
+- The three native methods return closed facts (`validateNativeActivationPlan()` closes the
+  activation plan) and never put vendor data - endpoints, sockets, raw errors - into core.
+
 ## How far you can get
 
 | Tier | You register | You get | You do not get |
@@ -100,8 +131,9 @@ The backing methods for delivery are `renderContextResult()` for `nextTurn`,
 | 3 | + realtime surface | delivery receipts, safe-point injection, child sessions | — |
 
 Installed hook wiring may reach tier 2, but the effective capability is still limited to
-an exact certified client/version/platform. No client currently certifies native live push
-or native reply routing.
+an exact certified client/version/platform. Passing native captures exist for Claude Code
+2.1.258 and Codex 0.152.1 on macOS arm64; they become live capabilities only when the
+production transports ship behind the native delivery contract above.
 
 ## normalizeHook
 

package/docs/CAPABILITIES.md

@@ -17,7 +17,7 @@ platforms degrade to false. No weaker session inherits a stronger peer's capabil
 
 Passing evidence currently ships for these exact versions on `darwin-arm64`:
 
-| Capability | Codex 0.147.0 | Claude Code 2.1.233 | Gemini CLI 0.37.0 | Grok 1.0.13 | Kimi 0.36.1 |
+| Capability | Codex 0.147.0 | Claude Code 2.1.233 | Gemini CLI 0.57.0 | Grok 1.0.13 | Kimi 0.36.1 |
 |---|---:|---:|---:|---:|---:|
 | `lifecycle.sessionStart` | yes | yes | yes | no | yes |
 | `lifecycle.sessionEnd` | yes | yes | yes | no | no |
@@ -32,15 +32,21 @@ Passing evidence currently ships for these exact versions on `darwin-arm64`:
 Every other capability in the closed shape defaults to false, including session resume,
 child sessions, startup or safe-point injection, and before-read guards.
 
+The `delivery.livePush` and `delivery.replyRoute` row is `no` for the exact hook versions
+this matrix is keyed to. Native live delivery was captured on newer clients - Claude Code
+2.1.258 (livePush and replyRoute) and Codex 0.152.1 (livePush) - and is admitted through the
+native delivery contract rather than exact-version certification: it is off until a per-client
+opt-in, experimental, and never turns on for a client below the captured minimum.
+
 The limitations belong next to the adapters they affect:
 
 | Adapter | Exact limitation and evidence |
 |---|---|
-| Codex | 0.147.0 next-turn stdout arrives as unwrapped developer-role context and requires plugin trust. The separate 0.152.0 native capture found no daemon control socket; ACC did not start one, so live push and reply routing remain false. |
-| Claude Code | 2.1.233 next-turn delivery waits for the next user prompt. The 2.1.252 channel capture stopped at the development-channel warning before the ACC MCP child started; native delivery branches are unobserved and false. |
-| Gemini CLI | Only 0.37.0 has package-shipped next-turn certification. Write and shell tools depend on approval mode; other versions and platforms retain inbox access but no effective delivery capability. |
-| Grok | Documentation-shaped payloads do not count as real captures. UserPromptSubmit context was observed discarded, and no deny was captured stopping a real write; all capabilities remain false. |
-| Kimi Code | 0.36.1 has next-turn and guard evidence, plus a 60-second heartbeat. Prompt-mode `SessionEnd` never fired, and its next-turn path does not interrupt an active turn. |
+| Codex | 0.147.0 next-turn stdout arrives as unwrapped developer-role context and requires plugin trust. A 0.152.1 capture proved the App Server queue transport, but the release capture then measured that native delivery there requires `codex --remote unix://`, and in that mode the session runs inside the daemon: both the hook payload and the App Server's own thread record report the daemon's directory instead of the session's, so ACC cannot tell which workspace the session is in. Nothing ACC can reach carries the real one, and placing a session in the wrong workspace is worse than not placing it, so `delivery.livePush` is **not** claimed - the probe and the handshake both refuse with `workspace_identity_unavailable`. `replyRoute` stays false. |
+| Claude Code | 2.1.233 next-turn delivery waits for the next user prompt. A 2.1.258 Channel capture proved idle offer, busy queue-after-turn, explicit reply, duplicate suppression, and durable fallback, so `delivery.livePush` and `delivery.replyRoute` are live capabilities behind the native contract (experimental, off until opted in; Claude's development-channel warning is vendor-owned and visible). |
+| Gemini CLI | Only 0.57.0 has package-shipped next-turn certification. Its TUI has no captured external wake or queue interface and `--acp` changes launch ownership, so native delivery is fallback-only; live push and reply routing remain false. |
+| Grok | Documentation-shaped payloads do not count as real captures. The public leader surface exposed no proven addressed injection into an ordinary TUI session, so native delivery is `awaiting_compatibility_capture`; all capabilities remain false. |
+| Kimi Code | 0.36.1 has next-turn and guard evidence, plus a 60-second heartbeat. Its server/queue APIs do not prove a transparent binding to an independently opened session, so native delivery is fallback-only. |
 | Generic MCP | Tool polling is not next-turn injection, live push, or a native reply route. It has no write guard or client-lifecycle evidence. |
 
 `certification.json` beside each adapter is machine-readable. `COMPATIBILITY.md` records the
@@ -57,8 +63,17 @@ The router requires exactly one current eligible generation. No binding, an expi
 several live sessions for one participant, a busy target, or a version that does not match
 passing evidence all stay on durable fallback.
 
-Current shipped reality: no adapter publishes a native live binding, and no adapter has
-passing `livePush` certification. Codex and Claude Code are next-turn or inbox only;
+The lease is extended by whoever serves the endpoint, because only that process knows it is
+still alive. A client that publishes no heartbeat - Claude Code among them - would otherwise
+let the lease run out under an idle session, which is exactly when live delivery is worth
+having. Giving a binding up is a separate, final fact rather than an expired lease, so a
+channel that has not yet noticed cannot extend something the session already retired.
+
+Current shipped reality: Claude Code on darwin-arm64 has a passing experimental `livePush`
+capture behind the native delivery contract, off until a per-client opt-in. Codex is
+next-turn and inbox only: its queue transport works, but the mode that makes a session
+reachable is the mode that hides which workspace it is in. Every other client is next-turn or
+inbox only;
 Gemini CLI and Kimi Code are next-turn only at their exact captured versions; Grok and MCP
 poll inbox.
 
@@ -70,7 +85,7 @@ policy:
 | Policy | Meaning |
 |---|---|
 | `off` | normal next-turn and inbox only |
-| `actionable` | questions, requests, and addressed handoffs may use live push |
+| `actionable` | questions, requests, answers, decisions, and addressed handoffs may use live push; notes wait for the next turn |
 | `all` | every addressed message kind may use live push |
 
 The default is `off`. `acc install --delivery actionable|all` is an explicit request, not
@@ -84,7 +99,7 @@ Room messages are never live-push candidates.
 |---|---|
 | exact-certified Codex 0.147.0 | complete peer body at the next normal turn; `acc inbox` remains recoverable |
 | exact-certified Claude Code 2.1.233 | complete peer body at the next normal prompt; `acc inbox` remains recoverable |
-| exact-certified Gemini CLI 0.37.0 | complete peer body at the next normal turn; `acc inbox` remains recoverable |
+| exact-certified Gemini CLI 0.57.0 | complete peer body at the next normal turn; `acc inbox` remains recoverable |
 | exact-certified Kimi Code 0.36.1 | complete peer body at the next normal turn; `acc inbox` remains recoverable |
 | Grok, generic MCP, unknown version, other platform | explicit `acc inbox` polling |
 

package/docs/CLI.md

@@ -129,9 +129,16 @@ external AI client. An addressed handoff requires acknowledgement; a room handof
 | `acc help` | — |
 | `acc version` | — |
 
-`--delivery` is a recipient policy request, not a capability switch. The default is
-`off`. If the detected exact client version lacks certified live push, installation keeps
-the effective policy off and prints the adapter's durable fallback.
+`--delivery off|actionable|all` is a per-client recipient policy request, not a capability
+switch, and the default is `off`. `--adapter` is repeatable to name several clients. An
+explicit `--delivery` applies uniformly and never prompts; omitting it on an interactive
+terminal asks one default-No question per eligible client, and on a non-interactive run or a
+`--dry-run` it keeps fresh clients off. A recorded opt-in is kept on upgrade. If the detected
+client cannot receive native delivery - unsupported, below the captured minimum, a
+prerelease, known-bad, a wrong platform, or an unsupported shell - installation keeps the
+effective policy off and prints the reason. A live install writes an owned zsh PATH block and
+a per-command shim that keeps your command name and `exec`s the real client; `ACC_BYPASS=1`
+runs the unmodified client, and ACC is never the parent of the session after that `exec`.
 
 Only `update` touches the network. `ACC_NO_UPDATE_CHECK=1` disables update checks. Hooks
 never perform them.

package/docs/CONFIGURATION.md

@@ -141,3 +141,7 @@ that resolves inside a workspace.
 | `ACC_MCP_WORKSPACE` | The project `acc-mcp` joins. Without it the server takes the directory the client launched it in, which is rarely the project |
 | `ACC_NO_UPDATE_CHECK=1` | Never ask npm whether a newer ACC exists. `acc update` then says it is off, which is a different answer from "nothing is newer" |
 | `ACC_PROBE_TIMEOUT_MS` | How long to wait for a client to print its version. Three seconds by default: generous on an idle machine, and not always enough on a busy one, where a client that overruns it is reported as not installed |
+| `ACC_NATIVE_DELIVERY_POLICY` | Set only by an ACC-owned shell shim to the consented live policy (`off`, `actionable`, or `all`) before it `exec`s the real client, so the session's hook knows a native transport was activated. Not for a person to set: an ordinary or `ACC_BYPASS=1` launch leaves it unset, and the hook treats missing or invalid values as `off` |
+| `ACC_BYPASS=1` | Runs the unmodified client through an ACC shim: no launch-time check, no native flags, and the reserved policy variable is unset. The escape hatch when you want the vendor command exactly as it was |
+| `ACC_BOOTSTRAP_DEBUG=1` | Lets the internal `acc-bootstrap` check write one safe diagnostic line to stderr. Off, it is silent, and it never writes to stdout |
+| `CODEX_HOME` | Codex's own home, honoured when locating the Codex App Server daemon's control socket for native delivery. Codex sets it; ACC only reads it |