agents-can-communicate 0.2.0 → 0.3.1

package/README.md

@@ -1,112 +1,122 @@
 # agents-can-communicate
 
+**Open your agents. Let them coordinate.**
+
+Give Codex the backend. Ask Claude Code to build the interface. Keep working as usual.
+
+ACC makes supported sessions in the same project aware of each other and gives them
+instructions for coordinating. Agents discover their peers, share what they're working
+on, and decide when to ask questions, agree on changes, or avoid overlapping edits.
+
+Think of the coordination you expect from subagents, extended across the independent
+sessions you open yourself — with different clients and models. You keep giving them
+ordinary tasks; they handle the conversations around their work.
+
+[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)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 [![Node](https://img.shields.io/badge/node-%E2%89%A524-brightgreen.svg)](https://nodejs.org)
 
-ACC connects independently opened AI sessions so they can discover, ask, answer, acknowledge, and hand off without becoming one managed agent team.
-
-It is a local-first communication layer for sessions you already run. Each session keeps
-its own client, model, checkout, permissions, context, and human direction. ACC supplies a
-shared room with presence, intent, narrow file claims, durable conversation threads, and
-truthful per-recipient receipts. It does not launch, steer, supervise, or terminate agents.
+## You describe the work. They work out the details.
 
-The project uses Node's standard library with **zero runtime dependencies**. Coordination
-state stays in platform app data outside the repository, and ACC never collects raw
-transcripts.
+Open two sessions in your project and give each its task:
 
-## Stop relaying between windows
-
-One session finds that removing `item.drive` will break another area. A second session is
-working there, but neither client knows the other exists. Without ACC, the warning stops at
-you: copy it to the other window, copy the answer back, and repeat for every question.
+| Session | Your prompt |
+|---|---|
+| Codex | Build the backend for account registration. |
+| Claude Code | Build the registration screen. |
 
-With ACC, the first session sends an attributed question. The second retrieves it, replies
-in the same thread, and thereby acknowledges the original. The first retrieves the answer.
-The message is durable throughout; neither model gains authority over the other.
+ACC's integration tells the agents that peers are present and teaches them how to find
+out what those peers are doing. As they work, they can notice the dependency and coordinate
+on their own. An illustrative exchange:
 
-```mermaid
-flowchart LR
-  A["session A — independently opened"] <--> R["ACC room<br/>presence · messages · receipts · claims"]
-  B["session B — independently opened"] <--> R
-  U["You — direction and authority"] --> A
-  U --> B
+```text
+Claude → Codex   I'm building the registration screen. What will your endpoint accept?
+Codex → Claude   Email and password. I'll return the new user and handle validation.
+Claude → Codex   I'll use that shape and keep my changes in the UI files.
 ```
 
-The product's canonical activation event is simple: a second independently opened session
-completes a useful acknowledged interaction without the human copying peer message content.
+The agents identify who to talk to and what to agree on. Your prompts stay focused on
+the feature you want to build.
+
+Each session keeps its own conversation and instructions. Response timing depends on the
+receiving client: see [when messages arrive](#when-messages-arrive).
 
-## Install
+## Try it
 
-On macOS or Linux with Node 24 or newer:
+You'll need **macOS or Linux, Node.js 24 or newer**, and two AI sessions in the same
+project. They can use different clients or the same one.
 
 ```bash
 npm install -g agents-can-communicate
 acc install
 ```
 
-Restart the clients whose hooks were installed; Codex also requires trusting the plugin.
-Then open two sessions in the same repository or plain directory as usual. They remain
-independent and join the same ACC workspace. Use `acc doctor` to see exact versions,
-installation health, and delivery downgrades.
+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.
 
-Runtime state lives in `~/Library/Application Support/acc` on macOS or the XDG data
-directory on Linux. `ACC_DATA_HOME` can override it, but ACC refuses a location inside a
-workspace. Git is optional; worktrees of one repository share awareness.
+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;
+its installed instructions guide the agents to coordinate when their work overlaps.
 
-## The communication loop
+Look for coordination in the agents' own activity: discovering a peer, checking who is
+changing a file, or asking about a shared dependency. Each agent decides what is relevant
+to its task; the integration provides awareness, not a guarantee that a model will
+coordinate on every task. [Client support](#when-messages-arrive) determines how
+automatically peers and messages reach it.
 
-```bash
-# Session A publishes awareness and reserves only what it will edit.
-acc work --summary "changing the item schema" --mode edit --hint 'file:src/item.mjs'
-acc claim --resource 'file:src/item.mjs' --reason "changing the item schema"
+If the other session doesn't appear, run `acc doctor` from your project directory.
+[Get help with setup](docs/TROUBLESHOOTING.md).
 
-# Session A asks a participant named by `acc status`.
-acc message --to models --type question --subject "item.drive" \
-  --body "Can your code stop reading item.drive before I remove it?"
+## When messages arrive
 
-# Session B reads and answers the exact message.
-acc inbox --message message_x
-acc reply --message message_x --body "Yes. Commit abc123 removes the final read."
+ACC connects sessions **on the same machine** and saves messages locally, so a waiting
+session can pick them up later. Delivery depends on the client:
 
-# Either session records a handoff while context is still available.
-acc finish --goal "remove item.drive" --status complete \
-  --completed "schema and reader updated" --remaining "none"
+| Client | How the agent receives a message |
+|---|---|
+| 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.
+
+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.
+
+[Full compatibility details](docs/CAPABILITIES.md).
+
+## Keep the workflow you like
+
+- **Your usual tools.** Start clients with their normal commands. You choose each
+  agent's task, model, and permissions.
+- **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.
+  [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.
+
+One npm package. No account or separate coordination service to set up.
+
+To remove the integrations:
+
+```bash
+acc uninstall
 ```
 
-Messages commit before any delivery attempt. `queued`, `offered`, `retrieved`, and
-`acknowledged` describe different observable facts: an offer is not a read, retrieval is
-not proof of model attention, and a reply resolves communication rather than proving a
-requested task finished.
+ACC preserves configuration changes you've made since installation.
 
-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.
+## Go further
 
-## What ACC owns
+[Getting started](docs/GETTING_STARTED.md) · [CLI reference](docs/CLI.md) ·
+[Connect an MCP client](docs/MCP.md) · [How ACC works](docs/HOW_IT_WORKS.md) ·
+[Security](docs/SECURITY_MODEL.md)
 
-| ACC owns | ACC does not own |
-|---|---|
-| participant and session presence | process or model lifecycle |
-| current intent and resource claims | prompts, permissions, or token budgets |
-| messages, threads, replies, acknowledgements | work queues or execution state |
-| delivery evidence and visible fallback | raw transcripts or shared model memory |
-
-A peer message is untrusted input, never system authority. A guarded claim can stop only
-the write paths a client actually exposes; `acc status` reports `advisory` when that cannot
-be guaranteed.
-
-## Documentation
-
-Start with [Getting started](docs/GETTING_STARTED.md), then 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
-adapter in its `COMPATIBILITY.md` and `certification.json`.
-
-Contributing starts with the repository's
-[AGENTS.md](https://github.com/automatis-tools/agents-can-communicate/blob/main/AGENTS.md).
-Node 24+, Git optional, MIT licensed.
+Want to contribute or add a client?
+Start with [AGENTS.md](https://github.com/automatis-tools/agents-can-communicate/blob/main/AGENTS.md)
+and the [adapter guide](docs/ADAPTER_AUTHORING.md).

package/SECURITY.md

@@ -1,6 +1,9 @@
 # Security policy
 
-## Reporting
+This page is for reporting a vulnerability. For system boundaries and threat reasoning,
+read the [security model](docs/SECURITY_MODEL.md).
+
+## Report privately
 
 Report privately via [GitHub security advisories](https://github.com/automatis-tools/agents-can-communicate/security/advisories/new).
 
@@ -9,7 +12,7 @@ Please do not open a public issue first.
 Include: what you ran, what happened, what you expected, and the client and
 version. A reproduction against a throwaway `ACC_DATA_HOME` is ideal.
 
-## Scope
+## Check the scope
 
 | In scope | Out of scope |
 |---|---|
@@ -21,11 +24,11 @@ version. A reproduction against a throwaway `ACC_DATA_HOME` is ideal.
 
 Reasoning behind each: [docs/SECURITY_MODEL.md](docs/SECURITY_MODEL.md).
 
-## Supported versions
+## Target a supported version
 
 Pre-1.0: the latest release only.
 
-## What we will do
+## Expect this response
 
 Acknowledge, reproduce, and tell you whether it is in scope. If it is, the fix
 ships with a test in `tests/security/` so it cannot come back quietly.

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

@@ -1,9 +1,9 @@
 # Writing an adapter
 
-An adapter teaches ACC one client. Nothing else in ACC knows that client exists. This page
-assumes the vocabulary in [Protocol](PROTOCOL.md#identity-hierarchy) — session, participant,
-claim — and points to [Capabilities](CAPABILITIES.md) for what was actually measured per
-client; see the [documentation map](index.md) for where both fit among the rest.
+Use this page to add one client without leaking vendor behavior into core. Start with the
+[identity contract](PROTOCOL.md#identity), then compare the shipped evidence under
+[certified support](CAPABILITIES.md#certified-support). The [documentation map](index.md)
+links the surrounding concepts and runtime architecture.
 
 ```mermaid
 graph LR
@@ -14,7 +14,7 @@ graph LR
   R --> H
 ```
 
-## The manifest
+## Define the manifest
 
 ```js
 export function createExampleAdapter() {
@@ -37,8 +37,8 @@ export function createExampleAdapter() {
 ```
 
 `renderContextResult` is required wherever an adapter renders peer messages. It returns
-`{ text, includedMessageIds, includedAttentionIds }`, and the [delivery
-lifecycle](PROTOCOL.md#delivery-lifecycle) advances only from those ids — never by searching
+`{ text, offeredMessageIds, includedAttentionIds }`, and the [receipt
+lifecycle](PROTOCOL.md#receipt-lifecycle) advances only from those ids — never by searching
 `text` for one, because peer text is untrusted and can imitate another message's header.
 `projectContextResult()` implements this contract; `projectContext()` remains the text-only
 convenience API for adapters that don't need it. An adapter with only the older
@@ -53,7 +53,7 @@ actually runs as — `command: "claude"` for a client that really runs as `node`
 nothing, and the failure is silent: the session gets `pid: null` and falls back to reading
 presence by age alone, with nothing telling you why.
 
-## Capabilities
+## Declare only proven capabilities
 
 Fourteen booleans in four groups, declared in the manifest's `capabilities` object:
 
@@ -68,7 +68,8 @@ Fourteen booleans in four groups, declared in the manifest's `capabilities` obje
 `defineAdapter` enforces the method — declaring `guards.beforeWrite: true` without
 `guardWrite()` is a usage error at construction. It also requires a passing entry in the
 validated `certification.json`; method existence is never evidence. What each shipped
-client was actually observed doing against this list is [Capabilities](CAPABILITIES.md#matrix).
+client was actually observed doing against this list is under
+[certified support](CAPABILITIES.md#certified-support).
 
 `lifecycle.heartbeat` is deliberately not a flavour of `delivery.nextTurn`. Next-turn
 delivery happens only when the client reaches a normal turn boundary; heartbeat fires on a
@@ -90,20 +91,54 @@ 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`.
 
-## How far you can get
+### 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.
+
+## Choose the integration depth
 
 | Tier | You register | You get | You do not get |
 |---|---|---|---|
 | 0 | nothing — humans run `acc` | durable messages, status, claims | anything automatic |
 | 1 | the MCP server | attach on first call, read, claim, message | guards, session end |
-| 2 | hooks + skill | automatic attach, turn context, write guards, cleanup | realtime |
-| 3 | + realtime surface | delivery receipts, safe-point injection, child sessions | — |
+| 2 | hooks + skill | only the lifecycle, context, guard, and next-turn behaviors separately captured for this client | uncaptured hook behaviors |
+| 3 | + native delivery surface | only captured live-push and reply-route modes | safe-point injection or child sessions unless separately captured |
 
 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. Tier 3 ships for one client: Claude Code, from
+2.1.258 on macOS arm64, behind the native delivery contract above. Codex reached a passing
+queue capture and was withdrawn anyway - the mode its transport needs reports the daemon's
+workspace as the session's - which is the standard: a capture that works is not the same
+claim as a capability that is safe to ship.
 
-## normalizeHook
+## Normalize hook input
 
 Whitelist, never a filter. Every client hands hooks the prompt, the transcript path, or the
 tool output; none of it may survive.
@@ -119,7 +154,7 @@ return normalizedEvent({
 Refuse an unrecognised payload. Inventing a session attaches the wrong one, or a new one
 every hook, and looks like it is working.
 
-## Response contracts do not port
+## Measure response contracts
 
 Measure them. Every client differs, and a wrong shape fails **silently**:
 
@@ -134,10 +169,11 @@ Measure them. Every client differs, and a wrong shape fails **silently**:
 `denyOutcome(reason)` returns `{ stdout, stderr, exitCode }`, so the runtime never has to
 know which client it is talking to. This table is only the shape each shipped adapter
 actually uses; the full experimental grid — every candidate shape tried against every
-client, including which ones are silently ignored — is measured in
-[Capabilities](CAPABILITIES.md#response-contracts-which-do-not-port).
+client, including which ones are silently ignored — is recorded in each adapter's
+`COMPATIBILITY.md` and certification fixtures. The cross-client summary is under
+[guard limitations](CAPABILITIES.md#guard-limitations).
 
-## Install and ownership
+## Preserve install ownership
 
 ```mermaid
 graph TB
@@ -156,7 +192,7 @@ Rules that are not negotiable:
 `planInstall` must use the same path helpers as `install`. A conformance test compares
 them, because a plan that drifts makes `--dry-run` a decoration.
 
-## Conformance
+## Run conformance
 
 ```bash
 node --test tests/conformance/*.test.mjs
@@ -166,7 +202,7 @@ node --test tests/process/hook-wiring.test.mjs
 The second one *executes* what your install wrote. Three adapters once shipped a hook
 command that did not exist anywhere; every test was green.
 
-## Record what you learned
+## Record the evidence
 
 One `COMPATIBILITY.md` per adapter: client version, event names, payload fields, the deny
 matrix, and what you could **not** observe. The next person's alternative is guessing.