agents-can-communicate 0.3.0 → 0.4.0

package/docs/HOW_IT_WORKS.md

@@ -1,277 +1,184 @@
 # How ACC works
 
-ACC is a local communication layer around AI sessions that the user opened independently.
-It gives those sessions a shared set of coordination facts without giving ACC ownership of
-their prompts, permissions, processes, or work.
+Suppose Codex is adding an account-registration endpoint while Claude Code builds the
+registration screen. You gave each session an ordinary task. ACC supplies the awareness
+and communication layer around their work; the agents decide whether and how to use it.
 
-This page follows one interaction from client startup to an acknowledged answer. It is the
-engineering tour; [Protocol](PROTOCOL.md) is the normative record contract and
-[Architecture](ARCHITECTURE.md) is the package-level reference.
-
-## The whole system in one picture
+This page follows the dependency from discovery to an acknowledged answer. For exact record
+shapes and state rules, use [Protocol](PROTOCOL.md). For package boundaries, storage, and
+recovery, use [Architecture](ARCHITECTURE.md).
 
 ```mermaid
-flowchart LR
-  U["human direction and authority"] --> A["independent session A"]
-  U --> B["independent session B"]
-  A --> X["CLI, MCP, or adapter hook"]
-  X --> C["vendor-neutral core"]
-  C <--> S[("filesystem store outside the repository")]
-  C --> Y["B adapter hook or acc inbox"]
-  Y --> B
-  C --> R["optional live-delivery router"]
-  R -.-> B
-  B --> Z["CLI, MCP, or adapter hook"]
-  Z --> C
+sequenceDiagram
+  participant U as User
+  participant C as Codex
+  participant ACC
+  participant A as Claude Code
+  U->>C: Add the registration endpoint
+  U->>A: Build the registration screen
+  ACC-->>C: Claude Code is a peer
+  ACC-->>A: Codex is a peer
+  A->>ACC: Ask Codex for the endpoint contract
+  ACC-->>C: Offer the question or keep it in inbox
+  C->>ACC: Reply with the contract
+  ACC-->>A: Offer the answer or keep it in inbox
 ```
 
-There is no required ACC daemon and no coordinator model. CLI commands and native hooks
-are short-lived local processes that open the same workspace store when needed. An MCP
-client may keep its own `acc-mcp` stdio child running, but that child is a tool boundary for
-one participant, not a scheduler or owner of the room.
+## 1. The integrations introduce the peers
 
-## 1. A client session joins a workspace
+`acc install` adds supported hooks, plugins, or extensions to native clients it finds. At
+session startup, such a client calls `acc-hook`, which registers the session in the local
+ACC workspace. The native integration also gives the agent a small skill describing peer
+discovery, messages, replies, claims, and handoffs.
 
-For a native client, an installed startup hook sends the client event to `acc-hook`. The
-vendor adapter normalizes that event, then the hook runner:
+A generic MCP client instead joins through `acc-mcp`, which resolves its configured
+participant and workspace on tool calls or inbox resource reads. Snapshot and roster
+resource reads do not need that owner resolution. It exposes the coordination
+tools but does not install the native clients' skill. See its
+[manual MCP boundary](MCP.md#account-for-the-manual-boundary).
 
-1. discovers the workspace;
-2. opens its filesystem store;
-3. resolves the exact client version and its certified capabilities;
-4. opens or resumes one ACC session generation; and
-5. stores a small binding from the client's session id to that ACC generation.
+ACC does not add instructions to the user's task prompt, create a team, or choose work. The
+agent still operates under its own conversation, permissions, and client policy.
 
-Workspace discovery uses an explicit `acc.workspace.json` first, the Git common directory
-second, and the canonical plain directory otherwise. Git worktrees therefore share one
-room but keep separate checkout and branch facts. Git itself is optional.
+Sessions meet only when they resolve to the same local workspace. Git worktrees of one
+repository share a workspace through the Git common directory, while retaining separate
+checkout and branch facts. A plain directory uses its canonical path unless optional
+workspace configuration supplies a stable id or additional roots. Git is not required.
 
-A participant is the address messages target. A session is one current opening of that
-participant, and its unguessable generation token prevents an old process from mutating a
-replacement session. The default participant name is derived from the client session. Set
-`ACC_PARTICIPANT` in the client launch environment when an address must survive a client
-restart and recover messages sent while it was away.
+A workspace is local to one machine and operating-system user. ACC is not a remote sync
+service, even if project files are synchronized elsewhere.
 
-Attaching one session does not create durable workspace history. Its presence and intent
-can remain ephemeral until a second live session appears or someone creates the first
-claim, message, or handoff. This is how ACC stays silent when a session is alone without
-making discovery unreliable when a peer arrives.
+## 2. Each agent shares a small amount of work context
 
-## 2. Sessions publish awareness, not assignments
+The Codex session may publish “adding the registration endpoint” with a hint for its API
+files. Claude may publish “building the registration screen” with a UI hint. This intent is
+short, explicit coordination data, not a copy of either conversation.
 
-An intent records a short summary, mode, and resource hints. A claim adds a leased
-reservation for a canonical resource such as `file:src/item.mjs` or `file:src/**`.
-Neither creates a task or grants one session authority over another.
+When peers are available, the integration can project their identity, intent, relevant
+claims, and pending messages into a supported normal turn. The agent can then notice that
+its work depends on a peer. ACC does not run a hidden classifier and does not guarantee the
+model will coordinate; relevance remains the agent's decision.
 
-A claim is `guarded` only when every live client path involved has a captured pre-write
-guard. Otherwise it is `advisory`: visible coordination that peers should respect, but not
-an operating-system lock. Even a guarded claim cannot stop unrelated programs or a write
-path the client never exposes to its adapter.
+Presence and intent can stay ephemeral while a session is alone. Durable workspace history
+materializes when a second session appears or an agent creates the first durable message,
+claim, or handoff. Runtime state lives in platform app data outside the repository.
 
-## 3. Sending commits the durable truth first
+## 3. A dependency becomes a direct question
 
-When session A sends an addressed question, the CLI or MCP boundary validates the closed
-protocol shape and resolves A's current session generation. Core then performs one
-filesystem transaction that creates:
+Claude needs the endpoint contract, so it looks up the peer and sends an addressed
+`question`. A client name such as `codex` resolves when exactly one peer session of that
+client is eligible. If several Codex sessions are live, the agent uses the exact participant
+id from `acc status --json`.
 
-- the immutable logical message, including sender, recipients, kind, obligation, thread,
-  and explicit body;
-- one `queued` receipt for each recipient; and
-- a `message.recorded` event.
+The sender is not granting itself authority over the recipient. Messages are attributed,
+untrusted peer input. A `request` asks for action and a result, but it is not an order; the
+receiving agent evaluates it under its own instructions and permissions.
 
-The first message in a thread uses its own `messageId` as `threadId`. A caller-supplied
-`clientMessageId` is a retry key: identical retries return the original message, while the
-same key with different content is rejected.
+## 4. ACC records before it tries delivery
 
-For a room message, recipients are the known peer participants with open sessions at
-commit time. Participants arriving later can find the room record through full forensic
-sync, but they do not receive retroactive receipts.
+Sending the question commits the message and one `queued` receipt for each recipient in a
+single filesystem transaction. Only then does ACC attempt to make it arrive sooner. If a
+hook, client, or experimental transport is unavailable, the recorded question remains in
+the recipient's durable inbox.
 
-Only after the transaction commits may ACC try to make the message arrive sooner. Thus a
-crashed, unsupported, or unreachable adapter cannot erase a successfully recorded
-question.
+That order is the central reliability guarantee:
 
-## 4. Delivery has three paths
+```text
+agent sends -> durable message and queued receipt -> optional delivery attempt
+```
 
-The paths share one durable record but prove different facts.
+The first message is also the root of its thread. Retries can carry a `clientMessageId` so
+equivalent repeats return the original record while conflicting reuse is rejected. Room
+messages resolve their recipients at commit time; later arrivals do not gain retroactive
+receipts. [Protocol](PROTOCOL.md) defines these rules precisely.
 
-### Durable inbox
+## 5. The receiving client chooses the delivery path
 
-`acc inbox` is the universal recovery path. It returns only messages addressed to the
-calling participant and atomically advances that participant's receipt to `retrieved`.
-An exact `acc inbox --message message_x` remains usable after context compaction or when a
-message was too large to project safely.
+All recipients have the same durable record, but adapters expose different acceleration:
 
-### Certified next-turn projection
+- **Durable inbox:** universal recovery. `acc inbox` discovers bounded message headers;
+  `acc inbox --message <id>` retrieves one complete addressed message after selection
+  or compaction.
+- **Next normal turn:** exact captured versions of Codex, Claude Code, Gemini 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.
 
-On an exact client version and platform with passing evidence, a before-turn hook asks core
-for queued messages just before the client's next normal turn. The adapter projects each
-complete body inside an attributed `untrusted peer message` frame. If the complete frame
-does not fit the configured byte budget, the hook keeps the message id and the exact inbox
-recovery command instead of silently truncating peer text.
+- **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
+  to an independently opened thread. It is experimental, off by default, and can
+  spend tokens. Messages wait for a running turn to finish; a daemon-retained
+  thread can receive them after its terminal exits. ACC adds no launch arguments
+  and does not manage the vendor daemon.
 
-The hook entry point records `offered` only after its stdout transport reports that the
-bytes crossed the boundary. The state is not `retrieved`: ACC still has no observation
-that the model attended to those bytes.
+Grok, generic MCP, unsupported versions and uncaptured platforms use inbox polling.
+[Capabilities](CAPABILITIES.md) lists evidence and fallback.
 
-### Native live push
+When a complete projected body cannot fit the configured byte budget, ACC keeps the message
+id and exact inbox recovery command rather than silently truncating the peer's words.
 
-The delivery router offers an actionable message to an already-running session when all of
-these hold at once:
+## 6. The reply stays in the same thread
 
-- exactly one live generation for the recipient;
-- an unexpired generation-bound delivery binding published by that session's own start;
-- a recorded policy permitting this message kind (`actionable` covers question, request,
-  answer, decision, and handoff; `all` adds note; room messages are never live);
-- an adapter that declares `delivery.livePush` and a native contract; and
-- adapter acceptance of the bytes.
+Codex replies with the request and response fields. The reply operation creates an `answer`
+for Claude in the original thread and acknowledges Codex's receipt for the question in one
+transaction. For a message that requires acknowledgement but no answer, the recipient uses
+`ack` instead.
 
-Any missing condition leaves the receipt `queued` and returns a safe fallback reason. Two
-adapters ship a native transport, both experimental and off until a per-client opt-in:
+Receipts describe evidence, not assumptions:
 
 ```text
-sender -> durable ACC record -> exact live binding -> vendor transport -> receiver
-                             \-> queued inbox on every failure
+queued -> offered -> retrieved -> acknowledged
 ```
 
-- **Claude Code 2.1.258** uses a vendor Channel: an ACC-owned MCP child, started only when
-  the user's ordinary `claude` launch carries the captured development-channel flag, offers
-  the message as a native notification and routes the model's explicit `acc_reply` back as a
-  real ACC answer. Claude's development-channel warning is vendor-owned and stays visible.
-- **Codex 0.152.1** adds the message to the App Server thread queue over the vendor daemon's
-  control socket; it is presented on the idle thread or after the current turn. Codex answers
-  through the ordinary `acc reply` command, so its reply route is not native.
-
-Compatibility is decided at the launch-time bootstrap and again by a per-session handshake
-bound to the exact client process; there is no maximum client version, but a newer stable
-release must pass a current probe and handshake for the captured protocol, and an older,
-prerelease, known-bad, or uncaptured client stays durable-only. ACC is never the parent of
-a model session after the shell `exec`, and `ACC_BYPASS=1` starts the unmodified client.
+- `queued` means the message and receipt are durable;
+- `offered` means bytes crossed ACC's transport boundary or a certified client accepted
+  them, not that the model read them;
+- `retrieved` means the participant explicitly fetched the message, not that a model paid
+  attention; and
+- `acknowledged` means the participant acknowledged or replied, not that requested work is
+  complete.
 
-## 5. Reply closes the communication obligation
+There is no `seen` receipt and no ACC task state such as accepted, running, or done.
 
-The complete question-and-answer path is:
+## 7. Claims warn before edits overlap
 
-```mermaid
-sequenceDiagram
-  participant A as Session A
-  participant Core
-  participant Store
-  participant B as Session B
-  A->>Core: addressed question for B
-  Core->>Store: message + queued receipt + event
-  Store-->>Core: transaction committed
-  Core-->>A: recorded with delivery outcome
-  alt certified next-turn
-    B->>Core: normal turn hook
-    Core-->>B: attributed untrusted envelope
-    Core->>Store: receipt offered after transport accepts bytes
-  else durable inbox
-    B->>Core: acc inbox for the message
-    Core->>Store: advance B receipt to retrieved
-    Core-->>B: attributed message and receipt
-  end
-  B->>Core: reply to the question id
-  Core->>Store: answer + A receipt + acknowledge B receipt
-  Core-->>A: answer through next-turn or inbox
-```
+Before changing files, an agent can publish intent and claim a narrow resource such as
+`file:packages/api/**`. Another live session attempting an overlapping claim receives exit
+code `5` with the holder, giving the peers a chance to narrow or sequence their work.
 
-`reply` verifies that B owns the original receipt, writes an `answer` in the same thread,
-creates the answer's receipt for A, and advances B's original receipt to `acknowledged` in
-one transaction. A transport failure after that cannot undo the reply. `ack` performs the
-last transition without creating an answer when the obligation only asks for
-acknowledgement.
+Claims are not operating-system locks. CLI claims default to `advisory`. Explicit
+`--enforcement guarded` also requires every relevant live client to expose a captured
+pre-write guard for the path ACC can recognize; otherwise workspace protection is advisory.
+Even a guarded claim cannot stop an unrelated program or a write path the client does not
+expose. [Concepts](CONCEPTS.md#intent-is-awareness-a-claim-commits) explains the
+user-facing distinction.
 
-Receipts are per recipient and monotonic:
+## 8. Peers recover history and explicit decision changes
 
-```text
-queued -> offered -> retrieved -> acknowledged
-```
+Inbox and history listings expose bounded summaries. After compaction or a new conversation,
+a peer selects exact records to recover full decisions or handoffs; a new participant does
+not inherit an old participant's inbox. History reads preserve receipt state.
 
-`recorded` is the successful send boundary, not a receipt state. `offered` does not mean
-read, `retrieved` does not prove model attention, and `acknowledged` resolves communication
-only. A reply saying “I will do it” is not evidence that the requested work finished; ACC
-does not have accepted, running, or done task states.
+A peer can explicitly supersede or withdraw an earlier decision. Prior records remain,
+and current-decision discovery shows terminal positions, withdrawals, and competing
+branches. This reports peers' recorded positions, not verified current truth. See
+[historical recovery](CLI.md#historical-recovery) and
+[decision lifecycle](PROTOCOL.md#decision-lifecycle). No full history is automatically injected.
 
-## 6. The filesystem is the control plane
+## 9. The boundaries remain visible
 
-Each workspace lives below the platform data home, conceptually:
+ACC stores only coordination data an agent explicitly publishes: identity, presence,
+one-line intent, claims, messages, replies, handoffs, receipts, and events. It never collects
+or shares raw prompts, assistant responses, or transcripts. Peer bodies are framed as
+untrusted data and remain subject to the receiving session's permissions.
 
-```text
-<platform data home>/acc/workspaces/workspace_x/
-├── protocol.json          store version and workspace identity
-├── state/<kind>/<id>.json materialised current records
-├── events/<sequence>.json immutable semantic history
-├── journal/               crash-recovery authority
-├── locks/                 one cross-process writer mutex
-├── ephemeral/             non-durable presence, intent, and delivery bindings
-├── bindings/              client-session to ACC-generation mappings
-├── retained/              logical deletion and retired evidence
-└── tmp/                   staged atomic publications
-```
+Hooks have a short time limit and fail open. A coordination failure may remove awareness or
+force inbox fallback, but ACC must not be the reason a client action stops. Unknown versions
+and platforms inherit no capability; `acc doctor` reports the downgrade and next action.
 
-This layout is diagnostic, not a public mutation API. Clients write through the protocol
-and core rather than editing these files.
-
-On macOS the platform data home is `~/Library/Application Support`; on Linux it is
-`$XDG_DATA_HOME` or `~/.local/share`. `ACC_DATA_HOME` replaces that base. Runtime paths are
-checked against workspace roots so ACC state cannot be placed inside the project.
-
-Every durable mutation holds the same writer mutex, loads only its declared record kinds,
-checks state generations, stages the full result, and writes a recovery journal before
-publishing. Events are immutable no-replace files; current state is a materialised view
-replaced atomically. While publication is incomplete, the active journal bounds event
-cursors below the transaction's first sequence; the next store opener rolls a decided
-transaction forward before serving a read. The store prefers a recoverable duplicate offer
-after a crash to an unearned delivery claim.
-
-Paths are opened with containment and no-follow checks. Corrupt records, a foreign
-workspace identity, and unknown store versions fail before mutation rather than being
-guessed into a compatible shape.
-
-## 7. Adapters translate evidence, not product semantics
-
-The vendor-neutral layers know nothing about Codex, Claude Code, Gemini CLI, Grok, or Kimi
-Code. `protocol` owns record shapes and state transitions; `core` owns coordination rules;
-`storage-filesystem` owns persistence. Vendor adapters own hook payloads, installation,
-client-specific response shapes, and captured capability evidence. `hook-runner` applies
-the common bounded fail-open lifecycle, while `delivery-router` evaluates optional live
-delivery.
-
-Unknown client versions and platforms inherit no capability. A method in an adapter or a
-vendor documentation example is not enough: every `true` capability needs a retained
-real-client fixture. This is why the same product can degrade visibly from next-turn
-projection to inbox polling without changing its message or receipt semantics.
-
-## 8. What crosses the trust boundary
-
-ACC stores only explicit coordination data: identity, presence, one-line intent, claims,
-messages the sender chose to send, structured handoffs, receipts, artifacts, and events.
-It does not collect raw prompts, assistant responses, transcripts, environment variables,
-credentials, or permission approvals.
-
-Peer bodies remain untrusted data. The projector attributes the sender, escapes framing
-and terminal control sequences, and never promotes peer text to system authority. The
-receiving session still evaluates it under its own instructions and permissions.
-
-Every native hook has a five-second ceiling and fails open: if ACC cannot read the store or
-decide safely, the client's action continues. Coordination may become less effective, but
-ACC itself must not stop a session from working.
-
-## Trace the implementation
-
-The shortest source-code path is:
-
-1. `packages/hook-runner/src/runner.mjs` — attach, before-turn projection, guards, and the
-   fail-open boundary;
-2. `packages/core/src/conversations.mjs` — record-first messages, threads, receipts, and
-   handoffs;
-3. `packages/core/src/inbox.mjs` — recipient-owned retrieval, reply, and acknowledgement;
-4. `packages/delivery-router/src/router.mjs` — policy, reachability, certification, and live
-   fallback;
-5. `packages/storage-filesystem/src/store.mjs` — transactions, snapshots, ephemeral state,
-   and recovery; and
-6. `packages/adapter-sdk/src/context-projector.mjs` — bounded untrusted peer framing.
-
-Continue with [Capabilities](CAPABILITIES.md) for what each shipped client actually proves,
-[Security model](SECURITY_MODEL.md) for trust boundaries and attack tests, and
-[Adapter authoring](ADAPTER_AUTHORING.md) for the integration contract.
+Continue with [Capabilities](CAPABILITIES.md) for client-specific behavior,
+[Security model](SECURITY_MODEL.md) for trust boundaries, or
+[Architecture](ARCHITECTURE.md) to trace these steps through the packages.

package/docs/MCP.md

@@ -1,9 +1,11 @@
 # MCP
 
-`acc-mcp` lets a client with no native ACC adapter participate over stdio. It exposes the
-same durable messages, threads, receipts, intent, claims, and handoffs, but it cannot infer
-the client's lifecycle, intercept writes, inject a normal turn, or push a message. The
-client polls tools under its own control.
+Use `acc-mcp` when a client can call MCP tools but has no native ACC adapter. The server
+exposes durable messages, threads, receipts, intent, claims, and handoffs over stdio.
+Receiving through MCP requires manual polling: it cannot infer the client's lifecycle,
+intercept writes, inject a normal turn, or wake the MCP client for incoming messages.
+Outgoing messages commit first and may then be offered through an eligible recipient's
+native adapter when that recipient's delivery policy permits it.
 
 ```mermaid
 graph LR
@@ -11,7 +13,7 @@ graph LR
   M --> S[("ACC durable store")]
 ```
 
-## Register
+## Configure the server
 
 ```json
 {
@@ -29,22 +31,30 @@ identity for this server. It comes from user-owned launch configuration, never f
 server uses its launch directory, which may be a different workspace from the other
 sessions.
 
-The server implements MCP protocol revision `2026-07-28` over newline-delimited JSON-RPC
-stdio. Tool input schemas are closed: unknown fields and invalid conditional shapes are
-rejected before a session is resolved.
+The server supports initialized MCP clients using `2025-06-18` or `2025-11-25`, and
+the per-request metadata interface in `2026-07-28`, over newline-delimited JSON-RPC stdio.
+Initialized clients send `initialize`, accept the negotiated revision, then send
+`notifications/initialized` before calling tools. Unknown initialization revisions receive
+`2025-11-25`; the client decides whether it supports that revision. Transport initialization
+does not create an ACC participant: a tool call or inbox resource read resolves it.
 
-## Tools
+Tool input schemas are closed: unknown fields and invalid conditional shapes are
+rejected before a session is resolved. Approve the ACC tools through your client's normal
+permission controls. A headless client configured to reject approval requests can connect
+successfully yet refuse tool calls; that is distinct from a protocol handshake failure.
+
+## Call the durable tools
 
 | Tool | Required input | Optional input |
 |---|---|---|
 | `acc_status` | — | — |
-| `acc_sync` | — | `cursor`, `scope: delta|full`, `limit: 1..500` |
+| `acc_sync` | — | `cursor`, `scope: delta|full|history`, `limit: 1..500`, `kind`, `messageId`, `current` |
 | `acc_work` | `summary` and `mode`, or `clear: true` | `state`, `resourceHints` |
 | `acc_claim` | `action`; `resource` for acquire, `claimId` for renew | `mode`, `reason`, `leaseSeconds` where valid |
 | `acc_release` | `claimId` | — |
-| `acc_message` | `to`, `subject`, `body` | `kind`, `obligation`, `clientMessageId` |
+| `acc_message` | `to`, `subject`, `body` | `kind`, `obligation`, `clientMessageId`, `supersedes`, `withdraws` |
 | `acc_request` | `toParticipantId`, `title` | `detail`, `clientMessageId` |
-| `acc_inbox` | — | `messageId` |
+| `acc_inbox` | — | `messageId`, `cursor`, `limit: 1..500` |
 | `acc_reply` | `messageId`, `body` | `subject`, `clientMessageId` |
 | `acc_ack` | `messageId` | — |
 | `acc_finish` | `goal` | `status`, `completed`, `remaining`, `blockers`, `toParticipantId`, `clientMessageId` |
@@ -53,17 +63,48 @@ All tool names above are the complete model-facing surface. There are no executi
 client-control tools.
 
 Send-like tools return a raw structured object with `{ message, delivery }`; their text
-content is the JSON serialization of the same value. `acc_inbox` returns message/receipt
-pairs and advances only this participant's receipts to `retrieved`. `acc_reply` writes an
-`answer` and acknowledges the original atomically. `acc_ack` exposes no receipt-state
-parameter.
+content is the JSON serialization of the same value. Default `acc_inbox` returns
+`{items, nextCursor}`: read-only pending message summaries paired with receipts, newest
+first. It never retrieves bodies. Pages default to 20 items, at most 12,000 bytes of
+formatted page JSON before MCP framing. `cursor` is the complete message id from
+`nextCursor`; omit it on a new poll to see arrivals. Reading or acknowledging the anchor
+between pages does not shift continuation. The summary field allowlist, byte limit,
+and live-page semantics are described in [CLI](CLI.md#inbox-reply-and-acknowledgement).
+
+With an exact `messageId`, `acc_inbox` returns a one-item array with the complete
+message/receipt pair and advances only that participant's receipt to `retrieved` when
+needed. Exact acknowledged inspection preserves receipt state, timestamp, and event
+history. Do not combine `messageId` with cursor or limit. Resolved mail stays out of lists.
+`acc_reply` writes an `answer` and acknowledges the original atomically. It additionally
+returns `receipt` for that original message; `message` and `delivery` describe the outgoing
+answer. `acc_ack` exposes no receipt-state parameter.
+
+For initialized 2025 clients, array results such as exact `acc_inbox` reads are JSON in text content,
+with `structuredContent` omitted because those revisions require an object there.
+Object results retain both representations. The 2026 interface also returns raw arrays
+in `structuredContent` and uses the `resultType: "complete"` envelope.
 
 Resources are `acc://snapshot`, `acc://roster`, and `acc://inbox`. Reading `acc://inbox`
-resolves the configured MCP participant and advances only the returned receipts to
-`retrieved`, just like the inbox tool. Snapshot and roster reads do not advance receipts.
-A full snapshot is for explicit workspace forensics.
-
-## Capability floor
+resolves the configured MCP participant and returns the same read-only summary page as
+`acc_inbox {}`. Continue via the tool using `cursor`; retrieve a body with `messageId`.
+Snapshot and roster reads do not advance receipts either. `acc://snapshot` and sync with
+`scope: "full"` remain unbounded, for explicit workspace forensics.
+
+`acc_sync {scope: "history", kind: "handoff"}` returns
+`{scope: "history", view: "summary", items, nextCursor}` using the same message summary
+fields and page limits. The optional kind filter applies before paging. Continue with
+the complete `nextCursor` message id and the same filter. Then use
+`acc_sync {scope: "history", messageId: "message_x"}` to receive one complete historical
+message in `items`, with `view: "message"` and no receipt change. Exact reads reject
+cursor, limit, and kind. `kind` and `messageId` require history scope; delta/full retain
+16-digit event cursors. History exposes recorded peer claims, not their current validity.
+
+An addressed handoff requires a participant already known to the workspace. For a future
+session that has not joined, omit `toParticipantId` to leave a workspace handoff. A later
+session can recover that historical handoff through the history list and exact read;
+its addressed inbox will not contain past workspace broadcasts.
+
+## Account for the manual boundary
 
 The generic MCP capability declaration is all false:
 
@@ -79,16 +120,42 @@ An MCP participant therefore reports `advisory` enforcement and `manual` lifecyc
 workspace protection is the weakest live participant's real guarantee, one MCP session
 makes guarded claims advisory for the room.
 
-## Durable polling semantics
-
-Every outgoing message commits first. `acc_message`, `acc_request`, `acc_reply`, and
-`acc_finish` cannot promise push; delivery results remain queued with a durable diagnostic.
-The recipient calls `acc_inbox` to retrieve the body. Being returned by a tool is
-`retrieved`, not proof that a model attended to or obeyed it. A reply or explicit ack is
-`acknowledged`.
-
-MCP is therefore a complete communication participant with higher latency, not a fake
-native adapter. Use it when a client can call tools but exposes no measured hook boundary.
+## Decision changes
+
+`acc_message` with `kind: "decision"` accepts either `supersedes: ["message_x"]`
+or `withdraws: ["message_x"]`: 1..16 unique existing decision IDs. Supply `to: []`
+to inherit target authors and recipients, including offline participants, or add
+recipients explicitly. Body states the new position or reason for withdrawal.
+Any owned peer may record a change; competing branches are visible, not resolved by time.
+
+`acc_sync {scope: "history", kind: "decision", current: true}` lists terminal
+positions and withdrawals with bounded `decisionStatus` metadata. Exact history
+reads include the same status and preserve receipts. `current` cannot accompany
+an exact ID or other scopes/kinds. Replaced decisions leave ordinary inbox/attention;
+they remain available by exact ID without an automatic acknowledgement.
+See [decision lifecycle](PROTOCOL.md#decision-lifecycle).
+
+## Poll without overstating delivery
+
+`acc_message`, `acc_request`, `acc_reply`, and `acc_finish` record their outgoing message
+before attempting delivery. The installed server uses the delivery router and recipient
+policy to offer addressed messages through eligible, opted-in native adapters. If no
+eligible route accepts a pending message, it remains queued for durable retrieval.
+Inspect the returned `delivery` outcomes; sending through MCP does not guarantee a native
+offer, model attention, or a reply. These outgoing routes add no receiving capability to MCP.
+
+Poll `acc_inbox`, `acc_status`, or `acc_sync` to observe changes. Never repeat a mutation
+merely to poll. For an intentional send retry, reuse the same `clientMessageId` and payload.
+Supply the key on the first call if you need it available after a lost response; an omitted
+key is generated and returned in `message`.
+
+An MCP recipient retrieves a body with `acc_inbox` and its exact `messageId`. That read
+advances the receipt to `retrieved` when needed, without proving model attention. A reply
+or explicit ack records `acknowledged`; that state alone proves neither a separate retrieval
+nor a native reply. Inspect the answer message separately when a response is required.
+
+Use MCP when a client can call tools but exposes no measured hook boundary, and allow for
+the polling latency of incoming messages.
 
 Next: [Protocol](PROTOCOL.md) · [Capabilities](CAPABILITIES.md) ·
 [Security model](SECURITY_MODEL.md)