agents-can-communicate 0.3.0 → 0.4.0

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,73 @@
+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) {
+    // Hook failures can include arbitrary payload or filesystem text. Report
+    // degradation without reflecting those details into the client's output.
+    tryWrite(stderr, "acc: coordination unavailable; 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 };
+}

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() {
@@ -28,6 +28,7 @@ export function createExampleAdapter() {
 
     detect, install, uninstall, doctor,
     planInstall,                      // what install would write
+    preflightUninstall,               // optional read-only removal validation
     normalizeHook,                    // client payload -> normalised event
     renderContext,                    // SyncResult -> text
     renderContextResult,              // text + ids of complete rendered groups
@@ -36,9 +37,14 @@ export function createExampleAdapter() {
 }
 ```
 
+`preflightUninstall(context)` is optional and read-only. Throw to refuse unsafe
+removal before the installer deactivates native integration or deletes recorded
+artifacts. `uninstall` should retain its own validation for direct adapter callers;
+recorded artifact fingerprint checks still determine the `keep` paths it receives.
+
 `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
@@ -46,6 +52,12 @@ convenience API for adapters that don't need it. An adapter with only the older
 instead: repeating an untracked body every turn would be quieter in code and dishonest about
 what was actually delivered.
 
+The hook also supplies `reminderMessageIds`, derived from this participant's `offered` or
+`retrieved` receipts with unresolved obligations. The standard projector combines those
+reply/acknowledgement attention items into counts after new bodies. A missing body alone
+is not evidence for compaction. Counts add no ids to `offeredMessageIds` or
+`includedAttentionIds`; complete inbox and status results remain available.
+
 `client.command` does double duty. `detect.mjs` uses it as the version-probe binary, and
 presence liveness separately walks the hook's process ancestry for the first ancestor whose
 executable basename matches it, to learn the client's own pid. Declare the binary the client
@@ -53,7 +65,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 +80,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
@@ -118,24 +131,48 @@ The rules `defineAdapter` enforces, and the ones the runtime applies:
   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
+- 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
+`nativeDelivery.policySource` defaults to the session environment. An adapter may
+declare `"installation-record"` when hooks and senders must read current recorded
+recipient consent independently of the vendor process environment. Installation
+records the requested policy even when current activation is unavailable. An absent
+or invalid record means `off`; a previously published binding cannot override it.
+
+The optional `refreshNativeSession()` method may revalidate an expired lease before
+an offer. It returns the same closed handshake shape as `bindNativeSession()` and
+must preserve the exact endpoint and protocol identity. The router rechecks the
+current session, generation, retirement, uniqueness and policy before publishing
+the refreshed lease. Refresh is not a heartbeat and cannot extend presence beyond
+its own expiry. Optional `retireNativeSession()` cleans adapter-owned endpoint state
+after confirmed core retirement; it must remain bounded and fail open for hooks.
+
+A package-shipped passing Codex installed-hook capture additionally references its
+complete real product matrix through the selected provenance record's
+`productEvidence: { fixture, sha256 }`. Package verification checks the actual file,
+raw digest and client/version/platform/package identity. A transport-only capture
+cannot certify the installed product route. `historicalFixtures` may retain hashed
+earlier failures without duplicating a certification tuple.
+
+## 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. 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.
+Installed hook wiring may reach tier 2, but each effective hook capability still
+requires exact client/version/platform evidence. Tier 3 has separate native
+contracts: Claude Code Channel from 2.1.258 and Codex LocalDaemon from 0.152.1 on
+macOS arm64, with current probes and exact session handshakes. Codex's earlier
+remote-wrapper failure remains historical evidence. Ordinary launch now preserves
+workspace identity; the full installed product matrix, including negative controls
+and fallback, backs its native claim.
 
-## 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.
@@ -151,7 +188,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**:
 
@@ -166,10 +203,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
@@ -188,7 +226,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
@@ -198,7 +236,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.

package/docs/ARCHITECTURE.md

@@ -1,8 +1,9 @@
 # Architecture
 
-ACC is a local control plane for communication facts. The execution planes remain the AI
-clients the user opened. Core records the truth before a delivery adapter is asked to make
-it arrive sooner.
+Use this page to trace a communication fact from an independently opened client through
+core, storage, and an optional delivery adapter. ACC is the local control plane; the AI
+clients remain independent execution planes. Core records the truth before an adapter is
+asked to make it arrive sooner.
 
 ```mermaid
 flowchart LR
@@ -41,7 +42,7 @@ The order is part of the public guarantee:
 
 1. validate and commit the message plus one `queued` receipt per resolved recipient;
 2. resolve the recipient's current delivery bindings;
-3. check recipient policy, current reachability, and exact client-version certification;
+3. check recipient policy and the current binding's reachability and offered native mode;
 4. ask one adapter to cross its transport boundary;
 5. only after acceptance, commit `offered` and an immutable success event.
 
@@ -71,16 +72,21 @@ lease without exposing the endpoint.
 
 ## Certified capability versus current reachability
 
-A capability says an exact client version on an exact platform passed a captured behavior.
-It does not say one particular session is reachable now. A binding says what that current
-generation exposes and whether its lease is current. Recipient policy says whether it may
-spend a turn. All three must agree before live delivery is possible.
-
-Codex and Claude Code currently ship failed native-delivery captures, so their
-`delivery.livePush` and `delivery.replyRoute` capabilities resolve false. Gemini CLI and
-Kimi Code have exact-version next-turn evidence only. Grok and generic MCP use inbox
-polling. The architecture includes a live seam without pretending the current clients
-proved it.
+Ordinary hook capabilities say an exact client version on an exact platform passed a
+captured behavior. Native live delivery uses a separate contract: installation checks the
+captured minimum, platform, and current feature probe, then each session publishes a binding
+only after a generation-bound handshake. The router trusts that admission and verifies the
+binding, recipient policy, declared adapter capability, and adapter response; it does not add
+a third exact-version certification check. A binding says what that current generation
+exposes and whether its lease is current, while recipient policy says whether it may spend a
+turn.
+
+Claude Code Channel has installed-client evidence on 2.1.258 and 2.1.260; Codex
+LocalDaemon has it on 0.152.1 and 0.153.4. Both use a captured platform minimum,
+current probe and exact session handshake. Codex preserves the ordinary client
+launch and verifies its registered thread and workspace; ACC owns no vendor daemon
+lifecycle. Gemini CLI and Kimi Code have exact-version next-turn evidence only;
+Grok and generic MCP use inbox polling.
 
 ## Storage and workspace identity
 
@@ -90,20 +96,34 @@ lexically, so a cursor is simply the last sequence returned.
 
 Workspace discovery checks an explicit config first, then the Git common directory, then
 the plain directory. Multiple worktrees share a workspace id while each session records
-its checkout and branch. Nothing written by ACC lands inside those roots.
+its checkout and branch. Runtime state never lands inside those roots; the only project
+file ACC writes is an optional `acc.workspace.json` explicitly requested through
+`acc config init`.
 
 A lone session can remain ephemeral. Durable state materialises when a second live session
-appears or the first claim, message, or handoff is committed. This makes “silent when
-alone” an architectural behavior, not a UI preference.
+appears or the first claim, message, or handoff is committed. Solo presence therefore
+does not require durable workspace history. Native turn hooks still supply the session's
+own CLI arguments, so a peer joining later in the same turn does not require reattachment.
+Without relevant coordination context, that identity header is the only projected content.
 
 ## Inbox, attention, and projection
 
-Inbox reads only messages addressed to the calling participant and advances that
-participant's receipt to `retrieved`. Reply validates ownership, creates an `answer` in the
+Public inbox discovery uses core `listInbox`: bounded, read-only message summaries
+addressed to the current participant. Exact body reads use `readInbox` and advance only
+that participant's receipt to `retrieved`; the embedded core API still supports bulk
+retrieval. History sync reads message records without receipt changes, using the same
+summary pager or one exact id. Reply validates ownership, creates an `answer` in the
 same thread, and acknowledges the original atomically. No participant can advance another
 participant's receipt.
 
-Attention is computed from six explicit rules:
+Decision lifecycle is derived from immutable message links, without a new record kind
+or mutable decision store. Read copies carry bounded status; raw forensic snapshots stay
+unchanged. Non-head decisions leave pending inbox, bulk delivery, and attention while
+exact reads retain them. Replacement/withdrawal records inherit recipients before commit,
+so offline readers receive the change without a forged acknowledgement. See
+[the protocol contract](PROTOCOL.md#decision-lifecycle).
+
+Attention is computed from six explicit rules for current obligations:
 
 | Priority | Kind | Observable trigger |
 |---|---|---|
@@ -121,6 +141,14 @@ Adapters project peer bodies in an attributed untrusted frame. If a complete bod
 fit, the projection keeps the message id and points to `acc inbox --message <id>` instead
 of silently truncating it.
 
+For this participant's unresolved messages already `offered` or `retrieved`, the standard
+projector combines reply and acknowledgement reminders into a compact count after new
+message bodies. Queued obligations and claim conflicts remain individual attention items.
+All pending headers stay discoverable through `acc inbox` pages; owned `acc status` retains
+its complete attention list. Full bodies require an exact inbox read; projection
+does not acknowledge or delete records. Explicit decision links, rather than the
+projector or message age, retire old decision obligations.
+
 ## Hooks fail open
 
 Hook execution is bounded. If coordination state cannot be read or a decision cannot be
@@ -129,3 +157,34 @@ it, but a coordination tool must not be the reason a session stops working.
 
 Next: [Protocol](PROTOCOL.md) · [Capabilities](CAPABILITIES.md) ·
 [Security model](SECURITY_MODEL.md)
+
+## Managed runtime activation
+
+The CLI owns installation generations under `<dataHome>/acc/runtime`, outside workspaces.
+All five launch paths select a generation and publish an actual-process lease under one
+admission mutex before loading workspace-capable code. Immutable launcher modules and
+runtime directories preserve in-progress imports. Leases survive `main()` returning and
+are removed only after confirmed process death. Parsed help, version, and update recovery
+remain available when workspace admission is unavailable.
+
+An independent worker downloads npm packages with lifecycle scripts disabled, checks exact
+stable package identity and the discovered integrity, and health-checks the staged runtime.
+Installer detection and planning happen before exclusive admission. The worker then checks
+ACC process leases and native binding PIDs, records `activating`, applies every integration,
+and only publishes the new active pointer after all applications succeed. Partial refresh
+remains fenced and repairs forward, with the old active pointer retained but normal
+workspace admission unavailable until recovery completes. Native bindings cease holding
+after observed SessionEnd cleanup or confirmed process death; the vendor daemon may remain
+running. Unknown PIDs remain holds until lifecycle cleanup. Presence TTL, `acc finish`,
+and delivery off alone do not prove native lifecycle end. ACC never manages the daemon.
+
+Lock ownership never expires by age. Retained nonempty tombstones prevent delayed observers
+from reclaiming a successor. Under an acquired lock, maintenance removes historical
+bookkeeping only when no live or unknown contender could still reference it; a stopped
+contender postpones cleanup. Admission also removes confirmed-dead process leases. None of
+this metadata is agent conversation history or injected context.
+
+The first upgrade from an unmanaged binary still requires a restart. ACC cannot fence old
+direct binaries or external applications importing core. Native trust and client-side cache
+activation remain vendor responsibilities; refreshed files do not establish observed
+capabilities.

package/docs/CAPABILITIES.md

@@ -1,5 +1,11 @@
 # Capabilities
 
+Use this page to set expectations after installation. Integration means ACC can introduce
+peer awareness and coordination instructions; it does not guarantee what a model will do
+with them. Delivery also varies independently from awareness. The durable inbox works for
+every participant, supported exact versions may add next-turn delivery, and the
+experimental Codex LocalDaemon and Claude Code Channel paths can deliver while a session is idle.
+
 Capability honesty separates four questions that are easy to collapse:
 
 1. **Certified support** — did this exact client version and platform pass a shipped
@@ -10,8 +16,12 @@ Capability honesty separates four questions that are easy to collapse:
    kind?
 4. **Fallback** — what durable path remains when any earlier answer is no?
 
-A source method or vendor documentation is not certification. Unknown versions and
-platforms degrade to false. No weaker session inherits a stronger peer's capability.
+A source method or vendor documentation is not certification. Uncaptured hook versions and
+unsupported platforms degrade to false. Native minimum-based eligibility is separate. No weaker session inherits a stronger peer's capability.
+
+Run `acc doctor` in the project when observed behavior differs from this page. It reports
+the installed client version, platform, effective capability, and fallback instead of
+assuming that a newer or differently packaged client behaves like a captured one.
 
 ## Certified support
 
@@ -32,22 +42,23 @@ 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 native rows remain `no` for the older exact hook versions in this matrix.
+Separate installed-client captures establish Codex `livePush` on 0.152.1 and
+0.153.4, and Claude Code `livePush` plus `replyRoute` on 2.1.258 and 2.1.260.
+Native eligibility uses the captured platform minimum, a current feature probe,
+and an exact per-session handshake. It is experimental and requires recipient
+opt-in. Codex replies through `acc reply`; its native `replyRoute` remains false.
 
 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. 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. |
+| Codex | Exact 0.147.0 next-turn context requires plugin trust. The observed stock 0.153.4 upgrade from ACC 0.3.1 to 0.4 required fresh review of five modified hook definitions; a subsequent restart retained all five active (activation evidence, not new event certification). LocalDaemon native delivery was captured through the installed package on 0.152.1 and 0.153.4, darwin-arm64; minimum 0.152.1, recorded opt-in, current feature probe and exact thread/cwd/process/version/protocol checks are required. Ordinary launch preserves the receiver workspace without ACC arguments or daemon ownership. Embedded or unreachable sessions keep their inbox. Native `replyRoute` remains 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. |
+| Generic MCP | As a receiver, tool polling is not next-turn injection, live push, or a native reply route. It has no write guard or client-lifecycle evidence. Outgoing messages may use an eligible recipient's opted-in native adapter. |
 
 `certification.json` beside each adapter is machine-readable. `COMPATIBILITY.md` records the
 captured client behavior, including what could not be observed.
@@ -59,23 +70,28 @@ would publish a generation-bound binding with `availableModes`, `clientVersion`,
 `livePolicy`, and `leaseUntil`. `acc status --json` reports these as `deliveryBindings`
 with a computed `reachable` boolean while keeping the opaque endpoint private.
 
-The router requires exactly one current eligible generation. No binding, an expired lease,
-several live sessions for one participant, a busy target, or a version that does not match
-passing evidence all stay on durable fallback.
-
-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.
+The router requires exactly one current eligible generation. No binding, several live
+sessions for one participant, and an adapter refusal keep delivery on the durable
+fallback. An expired lease may be revalidated by an adapter's optional refresh method;
+failure leaves the message queued. Busy behavior belongs to the transport: Claude's Channel can accept a
+message while the target is busy and queue it until the current turn finishes; an adapter
+that instead refuses with `recipient_busy` leaves the message on the durable path.
+
+An endpoint may renew its lease, or an adapter may revalidate that exact endpoint on
+demand without a client heartbeat. Retirement is final: neither route may revive a
+retired binding, a closed session or an old generation. Delivery lease refresh does
+not renew participant presence.
+
+On darwin-arm64, Codex LocalDaemon and Claude Code Channel have captured
+experimental live delivery. Other adapters retain their separately certified
+next-turn paths or inbox polling. Linux and other uncaptured platforms retain
+the durable inbox; these captures establish no new hook capabilities there.
+
+Codex's 120-second delivery lease can refresh on demand for the same live endpoint;
+it does not extend the 24-hour participant presence limit. A TUI exit can leave its
+daemon thread loaded and able to execute opted-in messages. Actual thread teardown,
+including explicit archive, runs `SessionEnd` and retires the binding. Turning ACC
+delivery off prevents new offers even while that thread remains loaded.
 
 ## Recipient policy
 
@@ -88,10 +104,16 @@ policy:
 | `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
-a force switch. The installer applies it only when the detected exact client has certified
-live push; otherwise effective policy remains off and the fallback diagnostic is printed.
-Room messages are never live-push candidates.
+The default is `off`. `acc install --delivery actionable|all` records recipient consent.
+Current activation remains off when the platform, captured minimum or feature probe
+does not qualify; that temporary failure does not erase the requested policy. Each
+session must pass its own generation-bound handshake. An adapter using the installation
+record rereads consent at hooks and before offers, so a long-running vendor process
+cannot retain permission through an old environment value or binding snapshot.
+
+For an adapter using recorded consent, `--delivery off` and uninstall prevent new
+native offers. They cannot withdraw a submission already accepted by the vendor queue. Ordinary hook capabilities still
+require exact-version certification. Room messages are never live-push candidates.
 
 ## Fallback