agents-can-communicate 0.7.0 → 0.8.0

package/docs/CLI.md

@@ -97,7 +97,19 @@ acc work --clear
 ```
 
 `status` returns participants, current intent, claims, protection, attention, and current
-delivery bindings. Default `sync` reads events after a 16-digit event cursor (100 by
+delivery bindings. Each session row carries its participant's `unretrieved: {queued, offered}`,
+the messages addressed to that participant that it has not fetched, split by how far delivery
+got. Two sessions of one participant show the same numbers, so read the workspace total from
+`counts.unretrieved` rather than adding rows, and the text line ends with
+`<n> offered, not retrieved` when that number is above zero. Offered is not read: a
+transport took the bytes, and the model may or may not have looked.
+
+A participant with no open session is left out, unless messages still wait for it. Then its
+latest session stays listed as `offline`, with `endReason` when the client said why the
+session ended, such as `"clear"` for Claude Code's `/clear`. The text line names each one:
+`waiting for a closed session: claude_code-b (cleared, 2)`. `acc status --all` lists every
+session. Default `sync` reads
+events after a 16-digit event cursor (100 by
 default, up to 500). `--scope history` discovers historical message headers and reads
 selected records; `--scope full` adds an unbounded snapshot for explicit workspace forensics.
 
@@ -202,6 +214,36 @@ Human output starts with `recorded message_x`. A transport failure after that co
 not change the command exit code. Reuse an explicit `--client-message-id` after an
 uncertain result to recover the same logical message.
 
+A queued result names why no live offer was made. `no_live_transport` means the recipient
+is online but its session has no live transport bound: a participant attached with the CLI,
+or a client without live delivery. It reads the message from its inbox or next turn, and
+human output says `models has no live transport; the message waits in its inbox`.
+`recipient_offline` means the recipient has no open session; the message waits until one
+starts or resumes. When the client said why its last session ended, the result carries it,
+for example `"endReason": "clear"` after Claude Code's `/clear`, and human output says
+`models's conversation was cleared (/clear); the message waits until that conversation
+resumes`. `recipient_unavailable` means the recipient's session is open but its live
+transport could not be reached.
+
+The delivery outcome `woken` means ACC woke a Claude Code session through its inbox:
+
+```json
+{ "recipientParticipantId": "models", "outcome": "woken", "transport": "claude-inbox" }
+```
+
+Human output prints it as `woke models via claude-inbox; the message arrives with its next turn`.
+The wake carries only fixed ACC text and the message id. The receipt stays `queued`. The
+session's next-turn hook then shows the body and records the receipt as `offered` via
+`next-turn`.
+
+A Claude Code session that bypasses permission prompts holds each wake for its user's
+approval, unless its `crossSessionInbound` setting is `accept`. The outcome then carries
+`"pendingApproval": true`, and human output says
+`sent a wake to models via claude-inbox, which its session holds for approval because it
+bypasses permission prompts; the message arrives with its next turn`. A session whose
+`crossSessionInbound` is `refuse` gets no wake: the message stays `queued` with
+`delivery_disabled`.
+
 `reply` additionally returns `receipt`: the original message id, the replying participant,
 and state `acknowledged`. Its `message` and `delivery` describe the outgoing answer.
 Human output distinguishes `recorded <reply-id>` from `acknowledged <original-id>`.
@@ -258,7 +300,12 @@ summary fields, ordering, page limits, and message-id cursors as inbox. `--type`
 any message kind and filters before pagination; keep the same filter between pages.
 This public workspace observation includes records from before your session joined.
 Exact history reads return `view: "message"` and one complete message in `items`,
-without changing any receipt. Do not combine `--message` with type, cursor, or limit;
+without changing any receipt, plus `receipts`: one entry per recipient with `state`,
+`updatedAt` (the last state change) and `offer` - the transport that accepted it, when, and
+`repeatedAt` if the next turn showed it again - or `offer: null` when no offer was recorded
+or an older ACC recorded it. This is how a sender tells a message a peer's client accepted
+(`offered`) from one its participant fetched (`retrieved`) or answered (`acknowledged`).
+Retrieved is not model attention either. Do not combine `--message` with type, cursor, or limit;
 message and type are valid only in history scope. Decision reads also include `decisionStatus`. Use
 `acc sync --scope history --type decision --current --json` for terminal decisions
 and withdrawals; keep these filters when paging. Exact reads cannot use `--current`.
@@ -309,12 +356,12 @@ terminal asks one default-No question for all selected clients that need a decis
 its local service is unavailable or has no loaded session; this does not activate delivery.
 A non-interactive run or a `--dry-run` 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. Claude Code shell activation writes an owned
-zsh PATH block and a shim that `exec`s the real client; `ACC_BYPASS=1` bypasses that
-activation. Codex LocalDaemon delivery uses recorded installation consent without changing
-ordinary launch arguments. Its opt-in remains active when shim variables are absent or
-bypassed; `acc install --adapter codex --delivery off` disables new native offers. On a
+prerelease, known-bad, or a wrong platform - installation keeps the
+effective policy off and prints the reason. Every adapter reads live-delivery consent from
+the installation record. Claude Code live delivery uses the inbox that each Claude Code
+session opens itself. ACC adds no launch argument, shell file or wrapper for it. Codex
+LocalDaemon delivery also keeps ordinary launch arguments unchanged.
+`acc install --adapter <adapter> --delivery off` disables new native offers for that client. On a
 supported explicit install, complete consent can prepare a missing Codex service. On macOS
 arm64 with Codex 0.154.0 or newer, the same choice includes downloading a missing standalone
 package from OpenAI. ACC selects the installed CLI version and verifies the official
@@ -330,15 +377,14 @@ The install summary names each client's requested policy,
 activation state and verified fallback. `doctor` separates protocol readiness, recorded
 consent and a live channel in the current workspace, with a next step for missing activation.
 A supported version or an installed plugin alone is not an active delivery channel.
-`runtime: active` means ACC has a reachable local transport binding. Claude can still
-block inbound Channels messages while its MCP server and tools remain connected;
-doctor therefore also names the client-side startup check.
+`runtime: active` means ACC has a reachable local transport binding. Claude Code applies
+its own inbound controls to each wake: a session in `bypassPermissions` mode holds the wake
+for approval. See [delivery troubleshooting](TROUBLESHOOTING.md#a-claude-code-session-holds-or-drops-acc-wakes).
 In doctor JSON, `nativeDelivery.activation` distinguishes missing launch setup from a
 recorded setup (or `not_required` for a pre-existing service). `policy` is the installed
 choice. `deliveryDecision` gives its known source and reports legacy provenance as unknown.
-`nativeServiceSetup` reports service infrastructure separately. `sessionPolicy` describes a native binding when one is visible. Existing Claude
-sessions can retain their launch policy after a different choice is installed for new
-sessions; Codex checks current recorded consent before new offers.
+`nativeServiceSetup` reports service infrastructure separately. `sessionPolicy` describes a native binding when one is visible.
+Every adapter rereads the current recorded consent at hooks and before new offers.
 `nativeDelivery.sessions` lists each current session's identity, present transport state
 and `lastAttempt`: timestamp, startup/turn event, effective policy and its source, whether
 that policy was missing/invalid/off, whether a client process was identified, and the closed

package/docs/CONCEPTS.md

@@ -121,13 +121,21 @@ Listing inbox headers and observing workspace history do not change receipts.
 There is no `seen` receipt. A failed delivery attempt leaves the message queued and
 recoverable rather than creating a terminal failure state.
 
+The sender can see where each copy got to. An exact history read of a message lists every
+recipient's receipt with the time of its last change and the transport that offered it, and
+`acc status` counts, per participant, the messages offered and not yet retrieved. A live
+transport accepting a message is the weakest of these facts, so a live offer that nothing
+followed for 15 minutes is shown once more at the recipient's next turn, marked as a repeat,
+on a client that takes next-turn bodies.
+
 ## Durable first, faster delivery second
 
 The durable inbox is universal. An adapter whose captures reach the installed client may
-also offer messages at the next normal turn. Codex LocalDaemon and Claude Code Channel add
-experimental live delivery, off by default and subject to recipient policy and
-current reachability. Codex can retain an eligible daemon thread after its terminal
-exits. [Capabilities](CAPABILITIES.md) gives the current limits.
+also offer messages at the next normal turn. Codex LocalDaemon and the Claude Code inbox
+wake add experimental live delivery, off by default and subject to recipient policy and
+current reachability. A Claude Code wake makes the session run a turn, and that turn's
+next-turn hook shows the message. Codex can retain an eligible daemon thread after its
+terminal exits. [Capabilities](CAPABILITIES.md) gives the current limits.
 
 ## Handoffs preserve explicit context
 

package/docs/CONFIGURATION.md

@@ -129,13 +129,22 @@ acc install --adapter codex --delivery off
 
 The allowed values are `off`, `actionable`, and `all`; the default is `off`. This setting
 does not belong in `acc.workspace.json`, where a pull request could opt someone else into
-spending a turn. It also cannot create a capability. Exact-version evidence governs
-ordinary hook features; Claude Code live delivery separately requires macOS arm64, version
-2.1.258 or newer, and a current feature probe before installation applies the requested
+spending a turn. It also cannot create a capability. Every adapter reads live-delivery
+consent from this installation record, and only from it. Exact-version evidence governs
+ordinary hook features. Claude Code live delivery separately requires macOS arm64, version
+2.1.282 or newer, and a current feature probe before installation applies the requested
 policy. If those install-time checks fail, effective policy remains `off` and the installer
 reports next-turn or inbox fallback. Each later session must also pass its own
 generation-bound handshake. A failed session handshake clears or refuses that binding and
-reports degraded reachability; it does not rewrite the installed consent.
+reports degraded reachability. It does not rewrite the installed consent.
+
+Claude Code live delivery wakes the session through the inbox socket that the session opens
+itself. ACC changes no launch argument, shell profile or `PATH` entry for it. Claude Code's
+own inbound controls still apply to each wake. A session in `bypassPermissions` mode holds
+each wake for your approval unless its `crossSessionInbound` setting is `accept`. A
+`crossSessionInbound` setting of `refuse` drops wakes. These controls belong to you, and ACC
+never overrides them. See
+[held or dropped wakes](TROUBLESHOOTING.md#a-claude-code-session-holds-or-drops-acc-wakes).
 
 Codex LocalDaemon delivery separately requires macOS arm64, Codex 0.152.1 or newer, a
 current feature probe, and exact thread, canonical cwd, process, version and protocol
@@ -144,10 +153,9 @@ standalone package and prepare a definitely absent service. The setup choice nam
 download. Existing service-start consent alone does not permit it. Codex files remain
 under the selected `CODEX_HOME`; the existing CLI command and shell profiles are preserved.
 Message delivery does not install Codex, start it, or stop it.
-Explicit update maintenance can restart a verified service after separate confirmation. Codex reads
-consent from the installation record, not a shell-shim variable. Unavailable or ineligible
-sessions retain durable inbox fallback. Use `acc install --adapter codex --delivery off`
-to stop new native offers; bypassing a shim does not disable that recorded opt-in.
+Explicit update maintenance can restart a verified service after separate confirmation.
+Unavailable or ineligible sessions retain durable inbox fallback. Use
+`acc install --adapter codex --delivery off` to stop new native offers.
 
 ### Codex outgoing permissions
 
@@ -195,7 +203,6 @@ that resolves inside a workspace.
 | `ACC_NO_UPDATE_CHECK=1` | Disables update networking and background scheduling; manual recovery of an already downloaded update remains available |
 | `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_ANTIGRAVITY_HOOKS` | Where `acc install` registers Antigravity CLI hooks. `global`, the default, writes `~/.gemini/config/hooks.json`, which always loads and applies to every Antigravity session on the machine. `workspace` writes `<project>/.agents/hooks.json`, which is scoped to the project the command ran in and loads only while that project is an open Antigravity workspace - in print mode, only when it is passed with `--add-dir`. Any other value is refused by name rather than replaced by the default, and that client is skipped. The two cannot be combined: both files use the namespace `acc`, and a name in both is kept only once |
-| `ACC_NATIVE_DELIVERY_POLICY` | Owned shell-bootstrap consent, currently used by Claude Code. The shim sets `off`, `actionable`, or `all`; missing/invalid values mean off for that route. Codex instead reads recorded installation consent, even when this variable is absent |
-| `ACC_BYPASS=1` | Bypasses owned shell activation, currently Claude Code: no bootstrap check/native flags, and shim policy is unset. It does not disable Codex recorded opt-in; use `acc install --adapter codex --delivery off` for new Codex offers |
-| `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 |
+| `CLAUDE_CONFIG_DIR` | Claude Code's own configuration directory, `~/.claude` by default. ACC reads the session registry `sessions/<pid>.json` under it to verify a session's inbox. ACC reads the value from the hook environment and never sets it |
+| `CLAUDE_CODE_MESSAGING_SOCKET` | The inbox socket of one Claude Code session, which Claude Code exports to that session's hooks. ACC reads it in the hook environment and checks it against the session registry. ACC never reads `CLAUDE_CODE_MESSAGING_TOKEN` |

package/docs/GETTING_STARTED.md

@@ -66,13 +66,14 @@ means the infrastructure is ready. Start a Codex session and complete the client
 trust review to establish a session-bound channel. An incomplete existing standalone
 installation or unsupported CLI version still needs the vendor action named by install.
 
-If you opt into Claude Code's experimental idle delivery, check Claude's Channels startup
-notice for ACC and accept its development-channel warning when shown. If it reports Channels
-unavailable or blocked, a connected MCP server does not make inbound delivery work;
-see [troubleshooting](TROUBLESHOOTING.md#i-enabled-live-delivery-but-got-fallback).
-The feature is off by default, can spend
-model tokens, and currently requires Apple Silicon macOS, zsh, and Claude Code 2.1.258 or
-newer. You do not need it for durable messages or supported next-turn delivery.
+Claude Code's experimental live delivery wakes the session through the inbox that Claude
+Code opens for every session. After you opt in, start Claude Code with your ordinary command.
+ACC adds no launch flag, shell change or wrapper. A session in `bypassPermissions` mode asks
+you to approve each ACC wake. See
+[held or dropped wakes](TROUBLESHOOTING.md#a-claude-code-session-holds-or-drops-acc-wakes).
+The feature is off by default, can spend model tokens, and currently requires Apple Silicon
+macOS and Claude Code 2.1.282 or newer. You do not need it for durable messages or supported
+next-turn delivery.
 
 ## 2. Open two sessions and give them ordinary tasks
 
@@ -140,11 +141,13 @@ Antigravity CLI carries one extra condition: its hooks are given a project direc
 when the session has an open workspace. A session started without one attaches nothing, and
 the client shows no hook output to say so - `acc doctor` names it.
 
-Codex LocalDaemon and Claude Code Channel offer optional native delivery on
-Apple Silicon macOS. They are experimental, can spend tokens, and queue messages
-until a running turn finishes. Codex requires 0.152.1 or newer, LocalDaemon infrastructure,
-recorded opt-in, and a verified session. Supported explicit setup can prepare a missing
-service. Start the client with your normal command. A loaded daemon thread can receive
+Codex LocalDaemon and the Claude Code inbox wake offer optional native delivery on
+Apple Silicon macOS. They are experimental and can spend tokens. Codex queues a message
+until a running turn finishes. A busy Claude Code session takes the wake between two tool
+calls. Claude Code requires 2.1.282 or newer and recorded opt-in, and it wakes through the
+inbox that each session opens itself. Codex requires 0.152.1 or newer, LocalDaemon
+infrastructure, recorded opt-in, and a verified session. Supported explicit setup can
+prepare a missing service. Start the client with your normal command. A loaded daemon thread can receive
 messages after its terminal exits. Antigravity CLI 1.2.7 and later has one too: with delivery enabled,
 ACC's context asks the agent to start a relay from its own shell, up to three times while
 none is running, and you approve that command at the client's prompt.

package/docs/GLOSSARY.md

@@ -16,7 +16,8 @@
 - **Retrieved** — the participant received the body; not proof of model attention.
 - **Acknowledged** — that participant explicitly acknowledged or replied; a reply is not proof requested work finished.
 - **Next-turn delivery** — certified projection at the client's next normal turn; it never interrupts an active turn.
-- **Live push** — optional delivery through Claude Code Channel or Codex LocalDaemon to an already-running session, behind recipient opt-in. Both wait for an active turn to finish; [Capabilities](CAPABILITIES.md) gives the measured eligibility and limits.
+- **Live push** — optional delivery through the Claude Code inbox wake or Codex LocalDaemon to an already-running session, behind recipient opt-in. A busy Claude Code session takes the wake between two tool calls. Codex waits for an active turn to finish. [Capabilities](CAPABILITIES.md) gives the measured eligibility and limits.
+- **Wake** — a live offer that carries only fixed ACC text and the message id. Its delivery outcome is `woken`, and the receipt stays `queued` until the next-turn hook shows the body.
 - **Recipient policy** — `off`, `actionable`, or `all`; opt-in permission to spend a turn, not a capability.
 - **Delivery binding** — ephemeral, generation-bound reachability data owned by an adapter.
 - **Fallback** — durable inbox or certified next-turn recovery when live delivery is unavailable.

package/docs/HOW_IT_WORKS.md

@@ -102,10 +102,14 @@ All recipients have the same durable record, but adapters expose different accel
 - **Next normal turn:** exact captured versions of Codex, Claude Code, Gemini CLI, Antigravity CLI and Kimi
   Code can receive complete attributed peer context when the user next prompts that client.
   This does not wake an idle session.
-- **Optional Claude Code channel:** supported Claude Code versions on Apple Silicon macOS
-  may receive an addressed actionable message while idle. This is experimental, off by
-  default, can spend tokens, never interrupts a running turn, and requires the vendor's
-  visible development-channel warning.
+- **Optional Claude Code inbox wake:** on Apple Silicon macOS with Claude Code 2.1.282 or
+  later, ACC wakes the session through the inbox socket that the session opens itself. The
+  wake is one line of fixed ACC text with the message id. It carries no subject, body or
+  sender name. An idle session starts a turn. A busy session takes the wake between two tool
+  calls and keeps its turn. Each delivered wake fires `UserPromptSubmit`, ACC's next-turn
+  hook, which shows the message in its untrusted block. The model answers with
+  `acc reply`. This is experimental, off by default and can spend tokens. Claude Code's
+  own inbound controls apply to each wake.
 
 - **Optional Codex LocalDaemon delivery:** on Apple Silicon macOS, a captured
   minimum of 0.152.1 plus a current probe and exact session checks allow delivery

package/docs/PROTOCOL.md

@@ -199,6 +199,55 @@ peer body into diagnostics.
 Receipt `offered` is committed only after the transport accepts bytes. A failed attempt
 leaves the receipt queued.
 
+A wake is the one accepted offer that records nothing. An adapter whose native contract
+declares `offerKind: "wake"` sends only a notice that makes the client run a turn. The
+Claude Code inbox wake is one line of fixed ACC text with the message id, and it carries no
+subject, body, sender name or other peer byte. The router records no event for an accepted
+wake and returns this delivery outcome:
+
+```json
+{ "recipientParticipantId": "<id>", "outcome": "woken", "transport": "claude-inbox" }
+```
+
+An adapter whose client took the wake but holds it for its user's approval adds
+`"pendingApproval": true` to its acceptance, and the outcome carries it. Nothing about it is
+stored.
+
+The receipt stays `queued`. The recipient's next-turn hook shows the body and records
+`message.offer_succeeded` with `transport: "next-turn"` after its output carried the body.
+A failed wake is recorded as `message.offer_failed`, like any failed offer.
+
+The same transaction records how the receipt was offered, in the receipt's `extensions`:
+
+```json
+{ "offer": { "transport": "codex-app-server", "at": "<timestamp>", "repeatedAt": null } }
+```
+
+It lives in `extensions` because a new receipt field would fail validation in an older ACC
+that reads the same store. A receipt offered by an older ACC has no `offer` entry; readers
+report `offer: null` and never guess a transport. An exact history read returns every
+recipient's `state`, `updatedAt` and `offer` beside the message.
+
+### One repeat of a live offer
+
+A `next-turn` offer is recorded only after the hook's output carried the body, which is the
+closest ACC comes to the model. A live offer proves that a transport accepted the bytes. A
+direct message whose receipt is still `offered`, whose offer transport is anything other than
+`next-turn`, and whose offer is at least 15 minutes old, is shown once more by the
+recipient's next turn on a client that takes next-turn bodies (a certified `nextTurn` and a
+structured renderer): the body in the usual untrusted block, after new messages, with the
+line `repeat: offered via <transport> at <timestamp>; no retrieval recorded`. An end-of-turn
+continuation never carries a repeat, because continuing a turn costs a model call.
+
+When the hook's output carried it, the repeat is recorded as another
+`message.offer_succeeded` with `transport: "next-turn"` and `repeat: true`, and
+`extensions.offer.repeatedAt` is set. The receipt keeps its state and `updatedAt`: a repeat
+is an attempt, never a transition and never a second message. A repeat is recorded at most
+once per receipt, and a receipt that was retrieved, acknowledged or repeated in the meantime is
+left unchanged with nothing appended. Like a first offer, the display itself can happen twice:
+two sessions of one participant can both show it before either commits, and a hook that runs
+out of time after writing does not commit at all.
+
 `transport_permission_denied` means the sender's OS or sandbox refused local transport
 access (`EPERM` or `EACCES`). It is distinct from `recipient_unavailable` and remains a
 failed offer with a queued receipt; raw OS error strings are not persisted.
@@ -267,12 +316,13 @@ The recipient owns `livePolicy` because native push may start a model turn:
 
 Default is `off`. Policy never creates a capability. The router requires one
 current eligible recipient generation, supported client evidence, a verified
-binding and adapter acceptance. Claude Code Channel uses a captured 2.1.258
-minimum, confirmed on 2.1.260. Codex LocalDaemon uses a 0.152.1 minimum, confirmed
-through installed-product captures on 0.152.1 and 0.153.4; recorded consent and
-exact thread, cwd, process, version and protocol verification govern every session.
-Unavailable or refused routes fall back durably. Codex replies use the ACC CLI;
-its native reply route remains false.
+binding and adapter acceptance. The Claude Code inbox wake uses a captured 2.1.282
+minimum on darwin-arm64. Its binding requires the same pid and socket in Claude Code's
+session registry, and every refresh and wake also requires the same session id. Codex LocalDaemon uses a 0.152.1 minimum, confirmed
+through installed-product captures on 0.152.1 and 0.153.4. Recorded consent and
+exact thread, cwd, process, version and protocol verification govern every Codex session.
+Unavailable or refused routes fall back durably. Claude Code and Codex replies use the ACC
+CLI. Their native reply route remains false.
 
 ## Attention and sync
 

package/docs/RELEASING.md

@@ -119,8 +119,9 @@ work belongs under `Unreleased` and gets a new candidate record.
 
 Run native real-client checks on the exact versions and platforms recorded in
 retained fixtures. Exact-version evidence governs normal-turn and guard behavior.
-Claude Code Channel uses its captured macOS arm64 minimum plus a current probe and
-per-session handshake; its vendor warning remains part of startup. Codex LocalDaemon
+The Claude Code inbox wake uses its captured macOS arm64 minimum plus a current probe and
+per-session handshake. Its passing capture is a real-client product run of the packed
+candidate, launched with the ordinary command and installed hooks. Codex LocalDaemon
 uses a separate 0.152.1 minimum with installed-product captures on 0.152.1 and
 0.153.4. Its passing capture must ship the hashed complete product matrix and
 historical evidence references. Direct queue success alone cannot certify that route.

package/docs/SECURITY_MODEL.md

@@ -73,13 +73,26 @@ never copy the peer body.
 
 A live adapter must match its declared evidence contract, one current
 generation-bound binding and recipient opt-in. Opaque endpoints remain private
-and outside repositories. Claude Code Channel and Codex LocalDaemon delivery are
+and outside repositories. Claude Code inbox wakes and Codex LocalDaemon delivery are
 experimental and off by default. Codex verifies the exact receiver thread,
 canonical cwd, live process, stable version and protocol, and rereads recorded
 consent before offers. A loaded daemon thread can receive messages after its TUI
 exits. Delivery off and uninstall prevent new Codex submissions; a submission
 already accepted by the vendor queue cannot be withdrawn.
 
+A Claude Code inbox wake carries only fixed ACC text. It is one line with the message id,
+and it carries no subject, body, sender name or other peer byte. The body reaches the model
+only through the next-turn hook, inside the untrusted `acc-peer-message` block. Before each
+wake, ACC checks that the session registry still names the same pid, session id and socket,
+so a wake never reaches a reused pid.
+
+ACC connects to the inbox without credentials. It never reads the session's
+`CLAUDE_CODE_MESSAGING_TOKEN` or its `.key` file, and it sends no auth line. A frame with
+that token would pass as the session's own child and skip the receiver's inbound controls.
+ACC also never attests a permission mode. Claude Code's inbound controls therefore stay the
+user's: a session in `bypassPermissions` mode holds each wake for approval unless
+`crossSessionInbound` is `accept`, and `refuse` drops wakes.
+
 On captured Codex/macOS configurations, live opt-in also grants outgoing access to ACC's
 state and local Unix sockets through a deny-by-default network proxy. Custom permission
 policies remain user-owned. Selection, proxy and grants are restored together only while

package/docs/TROUBLESHOOTING.md

@@ -154,31 +154,35 @@ or a connected MCP server does not by itself establish automatic delivery. `life
 manual` can also mean the current version has no certified session-end hook; it does not
 prove that no hooks ran.
 
-For Claude Code, open a fresh interactive zsh after installation so its launcher
-is on PATH. Check Claude's **Channels startup notice for ACC**, and accept the
-development-channel warning when it appears. A successful bootstrap cache means the
-executable passed ACC's compatibility probe. `/mcp` showing `connected` and two tools
-means the MCP server connected. Even `runtime: active` in ACC's doctor JSON describes
-the local transport; none of these proves that Claude enabled inbound channel messages.
-
-If Claude says `--dangerously-load-development-channels ignored` or `Channels are not
-currently available`, it has not enabled that delivery path. On a fresh 2.1.266 test
-profile, the first launch showed those messages and the next launch showed the development
-warning; restarting once can recheck availability, but is not a guaranteed fix. If it
-remains unavailable, follow Claude's notice. Organization policy can also block Channels;
-an administrator must enable them where required. ACC does not override that policy.
-See [Claude's Channels documentation](https://code.claude.com/docs/en/channels).
-
-If `deliveryBindings` is empty, ACC has not bound a local transport either. Read the
+For Claude Code, use version 2.1.282 or newer on Apple Silicon macOS, and start it with
+your ordinary command. Each Claude Code session opens its own inbox socket. ACC reads the
+socket path from `CLAUDE_CODE_MESSAGING_SOCKET` in the hook environment. ACC then checks that
+path against Claude Code's session registry `<config>/sessions/<pid>.json`, where
+`<config>` is `CLAUDE_CONFIG_DIR` or `~/.claude`. The pid and the socket must match for the
+binding, and the session id must match too before each wake. Each turn hook binds the
+session again, so the next ordinary prompt retries a failed binding.
+
+- Claude Code 2.1.224 and later open the inbox, but ACC's captured minimum is 2.1.282. An
+  older version reports `below_minimum_version` and keeps next-turn delivery.
+- On native Windows, Claude Code serves its inbox on a named pipe that requires an auth
+  line. ACC has no capture of that inbox, so Windows keeps next-turn delivery.
+- Linux is uncaptured for live delivery. A Linux session keeps next-turn delivery.
+- A wake that reached the session can still wait for your approval. See
+  [the next section](#a-claude-code-session-holds-or-drops-acc-wakes).
+
+If `deliveryBindings` is empty, ACC has not bound a local transport. Read the
 per-session lines in `acc doctor`, or `nativeDelivery.sessions[].lastAttempt` in JSON:
 
-- An absent launch policy means that hook did not receive delivery consent, even if an
-  earlier bootstrap probe succeeded. For Claude, open a new terminal and client through
-  the installed launcher.
+- An absent or `off` policy means the installation record has no live-delivery consent
+  for that client. Run `acc install --adapter <adapter> --delivery actionable` (or `all`).
 - `client_process_unknown` means ACC could not identify the client process. A new client
   session repeats that lookup.
-- `handshake_failed` or `handshake_timeout` means the session could not bind the local
-  channel. Check the client's integration/channel setup; the next ordinary turn retries.
+- For Claude Code, `native_endpoint_unavailable` means the hook environment had no
+  `CLAUDE_CODE_MESSAGING_SOCKET`, or the socket failed ACC's safety checks.
+  `native_session_unavailable` means the session registry is missing or names another
+  session or socket.
+- `handshake_failed` or `handshake_timeout` means the session could not bind its local
+  transport. Check the client's integration. The next ordinary turn retries.
 - No attempt observed can mean no native hook ran, an older runtime wrote the owner, or
   diagnostic persistence failed. Check hook activation and the runtime versions in doctor.
 
@@ -190,6 +194,37 @@ Closing a Codex terminal can leave its daemon thread loaded and eligible. Use
 Already accepted queue entries remain with the vendor. Actual thread archive
 requires Codex's confirmation and produces `SessionEnd`.
 
+## A Claude Code session holds or drops ACC wakes
+
+Claude Code applies its own inbound controls to each ACC wake. These controls stay yours.
+ACC never attests a permission mode, never reads the session's messaging token or key file,
+and sends no auth line.
+
+- A session in a prompting mode (`default`, `auto`, `acceptEdits` or `dontAsk`) takes each
+  wake.
+- A session in `bypassPermissions` mode holds each wake for your approval. To let such a
+  session take wakes without approval, set Claude Code's `crossSessionInbound` setting to
+  `accept`.
+- A session with `crossSessionInbound` set to `refuse` drops each wake. ACC then sends
+  none: the message stays `queued` with `delivery_disabled` and arrives with the next turn.
+
+ACC reads the same inputs Claude Code reads: the hook's permission mode; before the first
+prompt, whose hook carries none, the `--permission-mode` or `--dangerously-skip-permissions`
+flag the session was started with, then `permissions.defaultMode`; and `crossSessionInbound`
+from managed, local, project and user settings in that order. A held wake is still sent, because Claude
+Code's approval dialog tells you a message is waiting, and the sender reads
+`sent a wake to <participant> via claude-inbox, which its session holds for approval`.
+
+The product re-run on 2.1.283 observed both the prompting case and a `bypassPermissions`
+session holding the wake. When live delivery is on and your user or managed settings do not
+say `accept`, `acc doctor` prints a `Claude Code inbound:` line naming the setting and the
+file.
+
+In every case the message stays durable. The receipt stays `queued` until the session's
+next-turn hook shows the body. The message arrives with the session's next turn, and
+`acc inbox` shows it at any time. The sender's `acc message` output still reports
+`woke <participant> via claude-inbox`, because the wake reached the inbox.
+
 ## Codex plugin is listed but inactive
 
 Open `/plugins` in Codex and check ACC is enabled. Open `/hooks`, review each ACC hook,
@@ -333,7 +368,7 @@ reported and retained. Remove those leftovers manually if desired.
 Runtime state is outside the repository by design. `ACC_DATA_HOME` can relocate it, but ACC
 refuses a path inside any workspace root. Relocate the whole data directory; a symlink for
 that directory is supported. Install rejects a symlink that moves only the internal
-`acc/runtime` tree, because runtime admission and the bootstrap cache need the same data home.
+`acc/runtime` tree, because the runtime launchers and their leases need the same data home.
 
 Next: [Getting started](GETTING_STARTED.md) · [Capabilities](CAPABILITIES.md) ·
 [Configuration](CONFIGURATION.md)
@@ -355,10 +390,11 @@ unrelated holds still require lifecycle cleanup or confirmed process exit; safet
 do not expire merely by elapsed time. See
 [maintenance and recovery](UPGRADING.md#confirmed-client-service-maintenance).
 
-If ACC 0.5.3 or 0.5.4 reports `acc-claude-channel; contract unknown` after an earlier
-0.4.x upgrade, its active pointer may have lost the contract field. This can affect newly
-opened Channels too. A pending old updater retries its downloaded release without looking
-for a newer fix. Install the current global CLI, then use that CLI to complete the update:
+If ACC 0.5.3 or 0.5.4 reports a Claude Code Channel process with `contract unknown` after
+an earlier 0.4.x upgrade, its active pointer may have lost the contract field. This can
+affect Channel processes opened after that upgrade too. A pending old updater retries its
+downloaded release without looking for a newer fix. Install the current global CLI, then use
+that CLI to complete the update:
 
 ```bash
 npm install -g agents-can-communicate@latest
@@ -366,9 +402,10 @@ acc update
 acc doctor
 ```
 
-The new reader can activate a compatible release while those Channels remain open.
+The new reader can activate a compatible release while those processes remain open.
 It still waits for different contracts, unknown native bindings, or generation files it
 cannot verify. See [legacy contract recovery](UPGRADING.md#recover-missing-runtime-contracts).
+Current releases retire the Channel path. See [upgrading from 0.7.x](UPGRADING.md#from-07x).
 
 Use `acc update` to retry a failed download or finish an interrupted integration refresh.
 A download failure keeps the working version. A partial integration refresh blocks

package/docs/UPGRADING.md

@@ -1,11 +1,52 @@
 # Upgrading to 0.5.0
 
+## From 0.7.x
+
+Claude Code live delivery wakes each session through the inbox socket that Claude Code opens
+for every session. The research-preview Channels path of 0.7.x is retired. Update as usual:
+
+```bash
+acc update
+acc version
+acc doctor
+```
+
+`acc update` and `acc install` retire these 0.7.x parts automatically:
+
+- the `claude` shim that 0.7.x put early on `PATH`, and its PATH block in `~/.zshrc`
+- the Channel entry `acc-channel` in the plugin `.mcp.json`, from every kept plugin copy
+- the `acc-bootstrap` and `acc-claude-channel` launchers
+- the bootstrap cache
+
+The shim and the `~/.zshrc` block are hash-checked. An edited shim or block is kept, and
+the command reports it. Remove a kept one by hand when you no longer need it. An old shim
+that is still on `PATH` launches the plain `claude` command, without
+`--dangerously-load-development-channels`.
+
+Live-delivery consent comes only from the installation record, and upgrading keeps the
+recorded policy. ACC ignores `ACC_NATIVE_DELIVERY_POLICY`, `ACC_BYPASS` and
+`ACC_BOOTSTRAP_DEBUG`. For Claude Code, the consent question now says that a session in
+`bypassPermissions` mode asks before each ACC wake.
+
+A Claude Code session that started through the old shim keeps its Channel until it exits.
+Its next turn binds the inbox. Start new sessions with your ordinary `claude` command.
+
+The Claude Code live-delivery minimum is now 2.1.282 on Apple Silicon macOS. With an older
+Claude Code, live delivery stays off and the recorded policy is kept. Update Claude Code and
+start a new session: the recorded policy applies to it, with nothing to install again.
+`acc doctor` reports the state. Native Windows keeps next-turn delivery.
+
+This release adds no new store event type or field, so a store it writes stays readable by
+0.7.x. The Channel captures remain as history in
+`packages/adapter-claude-code/COMPATIBILITY.md`.
+
 ## Recover missing runtime contracts
 
 ACC 0.5.5 fixes an upgrade defect that can leave 0.5.3 or 0.5.4 waiting for
 `acc-claude-channel` processes with `contract unknown`. The 0.4.x updater can activate
-a newer generation without copying its store contract into the active pointer. Channels
-started afterward copy that incomplete pointer even though their runtime declares a contract.
+a newer generation without copying its store contract into the active pointer. Claude Code
+Channel processes started afterward copy that incomplete pointer even though their runtime
+declares a contract.
 
 For an installation already waiting on an older pending release, run:
 
@@ -21,8 +62,8 @@ needed because the older updater retries its pending release before checking npm
 version. If a version pin selects an older release, clear it or select 0.5.5 first.
 
 The reader verifies the referenced generation's package identity, complete contents and
-file modes before recovering a missing contract. Compatible Channels can keep running on
-their original generation during activation. Explicit differing contracts and unknown
+file modes before recovering a missing contract. Compatible Channel processes can keep
+running on their original generation during activation. Explicit differing contracts and unknown
 native bindings still block. A generation without a contract, missing files, or changed
 contents remains unknown. ACC does not terminate these processes or edit their lease records.
 
@@ -51,15 +92,15 @@ policy is default or contains only ACC's legacy state root. Custom policies are
 and reported as unverified. See [outgoing permissions](CONFIGURATION.md#codex-outgoing-permissions).
 If doctor names a missing local service, follow its prerequisite or explicit install action
 before opening the new session. A supported explicit install can prepare the service. It
-does not make a session-bound channel ready.
+does not make a session-bound transport ready.
 
 Run `acc doctor` in the project after the new clients have started (or submitted a normal
-turn). Its per-session lines now explain missing launch consent, an unidentified client
+turn). Its per-session lines now explain missing consent, an unidentified client
 process and a failed or timed-out handshake. `nativeDelivery.sessions[].lastAttempt` in
 `acc doctor --json` provides the same closed metadata and timestamp. Existing owners may
 have no attempt record until a new hook runs; missing metadata does not prove hooks are
-disabled. A previous successful handshake and a connected MCP server do not prove that
-Claude admitted inbound Channels messages. See [delivery troubleshooting](TROUBLESHOOTING.md#i-enabled-live-delivery-but-got-fallback).
+disabled. A previous successful handshake does not prove that the session is reachable
+now. See [delivery troubleshooting](TROUBLESHOOTING.md#i-enabled-live-delivery-but-got-fallback).
 
 Upgrading preserves delivery consent. If doctor reports native delivery off and you want
 automatic peer requests, use `acc install --adapter codex --delivery actionable` (or the