agents-can-communicate 0.3.1 → 0.4.1

package/docs/CONCEPTS.md

@@ -79,6 +79,12 @@ Message kinds describe the conversation:
 An **obligation** is the communication response owed by a recipient. A request is not an
 order, and a reply is not proof that work is complete.
 
+A decision can explicitly replace or withdraw earlier decisions. The old records stay
+attributed and recoverable, while current reads and reminders follow the recorded links.
+Any peer may record a change; competing branches remain visible until explicitly joined.
+A current decision is a recorded position, not agreement or authority. See
+[decision lifecycle](PROTOCOL.md#decision-lifecycle).
+
 ## Threads keep the exchange together
 
 The first message is a **thread** root. A reply names the original message and stays in that
@@ -100,19 +106,20 @@ queued -> offered -> retrieved -> acknowledged
 
 - `queued`: the durable message and receipt committed;
 - `offered`: ACC or a certified client accepted the delivery bytes, not proof of reading;
-- `retrieved`: the participant fetched the message, not proof of model attention;
+- `retrieved`: the participant fetched the body through its inbox, not proof of model attention;
 - `acknowledged`: the participant acknowledged it or replied, not proof of task completion.
 
+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.
 
 ## Durable first, faster delivery second
 
-The durable inbox is universal. Exact-version certified adapters may also offer messages at
-the next normal turn. That does not wake an idle client. Claude Code has the only shipped
-experimental live path, off by default and subject to recipient policy and current
-reachability; Codex live delivery is withdrawn. [Capabilities](CAPABILITIES.md) is the
-current adapter matrix.
+The durable inbox is universal. Exact-version certified adapters 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.
 
 ## Handoffs preserve explicit context
 

package/docs/CONFIGURATION.md

@@ -6,7 +6,7 @@ as the same operating-system user on the same machine and resolve that same loca
 workspace.
 
 Create `acc.workspace.json` only for stable workspace identity, roots, or shared
-claim/context policy. It is optional project configuration that `acc config init` may write
+context budget. It is optional project configuration that `acc config init` may write
 at your request; runtime state remains in platform app data outside the repository. The
 file never defines agents, messages, execution state, or delivery endpoints. Project map:
 [README](index.md). Terms used below: [Glossary](GLOSSARY.md).
@@ -18,11 +18,8 @@ file never defines agents, messages, execution state, or delivery endpoints. Pro
   Matching ids never connect different machines or OS users.
 - **More than one root.** A monorepo whose apps live in separate directories, or a
   workspace that spans sibling checkouts.
-- **Shared policy.** Claim mode and context budget, agreed once and committed, rather than
-  each person's machine deciding.
-- **Stated expectations.** `requiredAdapters` records which harnesses this project expects
-  to be installed, so `acc doctor` can say what is missing rather than leaving a session
-  silently uncoordinated.
+- **Shared context budget.** Set the ceiling for supported injected turn context once for
+  the workspace.
 
 ### Define the file
 
@@ -39,10 +36,8 @@ link can point anywhere, including at a file the repository does not control.
   "displayName": "Example",
   "roots": ["."],
   "policy": {
-    "claimMode": "advisory",
     "contextBudgetBytes": 6000
-  },
-  "requiredAdapters": []
+  }
 }
 ```
 
@@ -52,11 +47,16 @@ link can point anywhere, including at a file the repository does not control.
 | `workspaceId` | Stable identity, portable id | required |
 | `displayName` | What peers see in a roster | the directory name |
 | `roots` | Directories in this workspace, relative to the config | `["."]` |
-| `policy.claimMode` | `advisory` or `guarded` | `advisory` |
+| `policy.claimMode` | Validated compatibility metadata (`advisory` or `guarded`); does not select claim enforcement | `advisory` |
 | `policy.contextBudgetBytes` | Ceiling on injected turn context, 1–64000 | `6000` |
-| `requiredAdapters` | Harnesses this project expects | `[]` |
+| `requiredAdapters` | Validated compatibility metadata; does not affect `acc doctor` diagnostics | `[]` |
 | `extensions` | Anything else, namespaced by whoever wrote it | `{}` |
 
+`policy.claimMode` and `requiredAdapters` are stored but have no claim or doctor effect in
+0.4. CLI claims default to advisory; request `--enforcement guarded` on each claim when
+appropriate, subject to every live participant's certified guard. MCP claims remain
+advisory. Do not use these metadata fields to configure protection or missing-client checks.
+
 Roots are refused if they are absolute or escape the workspace. An absolute root is one
 machine's layout committed to a shared repository, and `packages/../../elsewhere` reaches
 outside the boundary the workspace is supposed to be. The check counts path segments, so an
@@ -98,17 +98,25 @@ Close them, or pass `--force` if you mean it — and restart them afterwards.
 <!-- test:illustration asks a person to confirm; there is nobody to ask in a test -->
 ```bash
 acc config init        # preview, then write after you agree
-acc config validate    # read-only; reports what applies
+acc config validate    # read-only; checks acc.workspace.json in the selected directory
 ```
 
+`init` and `validate` operate only on `acc.workspace.json` directly inside the selected
+`--cwd` directory (the current directory when omitted). Unlike ordinary workspace discovery,
+they do not walk upward. Pass `--cwd` with the directory containing the config you intend
+to inspect or create. A nested `init` can create a new config that shadows an ancestor;
+check the ancestor first.
+
 `init` shows the exact file it would write and waits. In a non-interactive run — a pipe, a
 CI job, an agent — there is nobody to ask, so it refuses unless you pass `--yes`. It never
 overwrites an existing config: a committed identity is shared by everyone on the project,
 and replacing it on a mistyped command would split one workspace into two.
 
-`validate` only reads. A command someone runs to find out what is wrong must not change the
-thing it is inspecting. With no config present it reports the defaults rather than failing,
-because not having one is a valid state.
+`validate` only reads. If that selected directory has no config, it reports
+`no acc.workspace.json in selected directory; ancestors not checked`.
+The JSON result returns default config metadata for that missing local file. Ordinary
+commands may still discover an ancestor config; this is not an effective-policy report.
+Run validation with `--cwd` set to that ancestor directory to check its file.
 
 ## Keep delivery consent user-owned
 
@@ -129,6 +137,13 @@ 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.
 
+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
+checks. Its daemon must already be running; ACC never starts or stops it. 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.
+
 ## Override local paths and identity
 
 Nothing in `acc.workspace.json` says where state is stored, and nothing there can — that is
@@ -137,17 +152,17 @@ that resolves inside a workspace.
 
 | Variable | Purpose |
 |---|---|
-| `ACC_DATA_HOME` | Where session, claim, and message state is kept, instead of the platform default (`~/Library/Application Support/acc` on macOS; `~/.local/share/acc` on Linux, or wherever `XDG_DATA_HOME` points) |
-| `ACC_CONFIG_HOME` | The same override, for configuration state the platform would otherwise keep alongside `ACC_DATA_HOME` |
-| `ACC_CACHE_HOME` | The same override, for cache data the platform would otherwise keep under its own cache location |
+| `ACC_DATA_HOME` | Base directory under which ACC creates `acc/` for runtime and coordination state. Defaults: `~/Library/Application Support` on macOS; `~/.local/share` on Linux, or `XDG_DATA_HOME` |
+| `ACC_CONFIG_HOME` | Parsed and validated path override; no current configuration-storage consumer |
+| `ACC_CACHE_HOME` | Parsed and validated path override; no current cache-storage consumer |
 | `ACC_PARTICIPANT` | Which participant a session belongs to, when the client does not say |
 | `ACC_WORKSPACE_ROOT` | The project to work in, instead of discovering one from the working directory. Absolute, or it is refused |
-| `ACC_SESSION` · `ACC_GENERATION` | Which session a command acts as when it is not worked out automatically. A supplied generation proves the exact opening; with only a session id the CLI resolves the current generation and refuses ambiguity |
+| `ACC_SESSION` · `ACC_GENERATION` | Explicit CLI owner credentials, supplied together by the operator for this session. Hooks do not set them. A public session ID alone never resolves a generation; see [CLI ownership](CLI.md#coordinate-from-a-session) |
 | `ACC_MCP_PARTICIPANT` | Who `acc-mcp` takes part as. `mcp` by default |
 | `ACC_MCP_WORKSPACE` | The project `acc-mcp` joins. Without it the server takes the directory the client launched it in, which is rarely the project |
-| `ACC_NO_UPDATE_CHECK=1` | Never ask npm whether a newer ACC exists. `acc update` then says it is off, which is a different answer from "nothing is newer" |
+| `ACC_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_NATIVE_DELIVERY_POLICY` | Set only by an ACC-owned shell shim to the consented live policy (`off`, `actionable`, or `all`) before it `exec`s the real client, so the session's hook knows a native transport was activated. Not for a person to set: an ordinary or `ACC_BYPASS=1` launch leaves it unset, and the hook treats missing or invalid values as `off` |
-| `ACC_BYPASS=1` | Runs the unmodified client through an ACC shim: no launch-time check, no native flags, and the reserved policy variable is unset. The escape hatch when you want the vendor command exactly as it was |
+| `ACC_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 |

package/docs/DESIGN_DECISIONS.md

@@ -18,12 +18,15 @@ boundaries exist.
 | Runtime state outside the repository | A checkout can be deleted, cloned, or synced; presence and locks must not travel with it. |
 | Project config optional and runtime-free | A committed file is editable by anyone with a PR, so it may carry policy — never sessions or tokens. |
 | Durable state is authoritative | Next-turn or live delivery may accelerate an interaction; neither becomes the source of truth. |
+| Bounded discovery, explicit history recovery | Automatic context stays small; peers select exact messages or historical records when they need full bodies. |
+| Immutable explicit decision links | Replacements and withdrawals preserve prior records and expose competing branches without choosing by timestamp. |
+| Fence managed runtime activation | Refresh all integrations before switching the active generation; partial refresh stays fenced until forward recovery completes. |
 | No heartbeat helper in v1 | An idle session is honestly reported `stale`. A sidecar process to fake liveness is worse than the truth. |
 | Presence reads the process, never writes the record | A pid answers "gone" at once; an age floor covers what a pid cannot, including its own reuse. Nothing is written back — no session has authority to edit another's record. This checks a process already there, not one beating on a session's behalf like the heartbeat helper above. |
-| No process launching | ACC attaches to sessions you already own. Owning them is a different product. |
+| No AI client or session launching | ACC attaches to sessions you already own; its separate update worker manages ACC packages, not those sessions. |
 | One publishable package | One version and one release rather than twelve coordinated ones. |
 | MIT | Widest reuse, least friction. |
-| Node 24 (current production LTS) | Uses `node:test`, modern `fs` promises, and no transpiler. |
+| Node 24 or newer required | Uses `node:test`, modern `fs` promises, and no transpiler. |
 | MCP session from launch config | Never from `initialize` or `clientInfo` — those are attacker-controllable. See the threat scenarios in [SECURITY_MODEL.md](SECURITY_MODEL.md) (scenario 8). |
 
 ## Avoid these rejected designs
@@ -32,7 +35,7 @@ boundaries exist.
 |---|---|
 | A file in each repo that agents poll | No guard, no identity, no atomicity — and it ends up committed. |
 | A permanent global lead session | Turns peers into workers and makes one crash fatal. |
-| Treating MCP as a lifecycle guarantee | MCP is a tool surface. It cannot attach, guard, or wake anything. |
+| Treating MCP as an external-client lifecycle guarantee | Tool calls resolve MCP's own participant, but cannot infer the client's lifecycle, intercept writes, or wake its receiver. |
 | Requiring Git, tmux, PostgreSQL, or a service | Every requirement is a reason the tool is not installed. |
 | Collecting or sharing raw transcripts | Raw transcripts are never collected or shared. Explicit peer messages are bounded records the sender chose to address. |
 | Reporting queued messages as delivered | A delivery state that overstates itself is worse than no state. |
@@ -47,16 +50,18 @@ perturbed the record instead of removing it — a hook whose recorded hash no
 longer matched was still observed running, so absence was never actually
 tested.
 
-Absence is the whole mechanism. With no record, the client runs no hook at
-all, prints `hook: SessionStart Completed` while executing nothing, and ACC's
-write guard goes silently off — while `acc doctor` and `codex plugin list`
-both report it enabled. On a real machine, a shell write walked through a
+Absence was sufficient to disable the hooks in that historical capture. With no
+record, that client ran no hook, printed `hook: SessionStart Completed` while
+executing nothing, and ACC's write guard went silently off — while `acc doctor`
+and `codex plugin list` both reported it enabled. A shell write walked through a
 guarded claim; writing the exact same hashes back (captured before deletion,
 from an ACC three releases older) revived the guard immediately.
 
-That is why removal is never ACC's to do: the record is granted once by a
-person, survives ACC upgrades, and nothing ACC writes can restore it.
-Tidiness is not worth a permission only a human can re-grant.
+That is why removal is never ACC's to do: it preserves the client's trust decision.
+The historical observation above does not establish trust across arbitrary upgrades.
+Codex 0.153.4 compares each current definition's hash and reports changed definitions
+as modified; a trusted hook can also be disabled. ACC preserves the records but leaves
+current readiness unverified, directing the user to `/hooks` in Codex.
 
 **The generalisation, since this cost a release:** to learn whether state is
 load-bearing, take it away. Changing it tests something else.
@@ -81,7 +86,7 @@ where a guard stops behaves better than one that believes it absolute.
 1. **Storage backend.** The hardened filesystem store ships first. A transactional backend
    can go behind the same interface later — but not merely to avoid a dependency.
 2. **Remote coordination.** v2, or a separate product.
-3. **Process launching.** Possibly never; possibly an external integration.
+3. **AI client/session launching.** Possibly never; possibly an external integration.
 4. **Multi-root discovery rules** beyond the current `roots` list.
 5. **Default claim lease length** for hook-only adapters. A hook-only session cannot sustain
    a short renewal cadence, so lease policy must not assume one.

package/docs/GETTING_STARTED.md

@@ -4,10 +4,20 @@ Install ACC, open the AI sessions you already use, and give them related work. S
 integrations make peers visible and teach each agent how to communicate. You do not need to
 carry messages between windows or add coordination instructions to your task prompts.
 
+Active hooks can supply each agent's own CLI arguments; the installed skill tells the
+agent how to use them. This path was observed in Claude Code 2.1.263, Codex 0.153.4, and
+Grok 1.0.24. Grok receives its own header after a terminal result, so its skill runs public
+status first; peer messages still require explicit inbox reads. Hooks must be enabled and
+trusted by the client. Without that owner context, owned operations require an explicit
+pair or session-bound ACC MCP tools. See [CLI ownership](CLI.md#coordinate-from-a-session).
+
 ## 1. Install once on this machine
 
 ACC requires macOS or Linux and Node.js 24 or newer.
 
+Already using ACC? Follow the [upgrade guide](UPGRADING.md) for the 0.4.0 → 0.4.1
+update or the data-format boundary when upgrading from 0.3.1.
+
 ```bash
 npm install -g agents-can-communicate
 ```
@@ -17,9 +27,22 @@ npm install -g agents-can-communicate
 acc install
 ```
 
+Initial installation also enables automatic updates; reinstalling keeps an explicit opt-out.
+ACC downloads releases in the background and
+refreshes its runtime and skills when active clients have left. Use `acc update` for an
+immediate update, or `acc update --auto off` to disable background updates. See
+[update controls](UPGRADING.md#automatic-updates-after-installation).
+
 The installer connects only the supported clients it finds. Open a new terminal and
-restart any running clients so they load their integrations. Codex asks you to trust its
-plugin once.
+restart any running clients so they load their integrations. Follow the activation steps
+printed by the installer. In Codex, use `/plugins` to check ACC is enabled, then `/hooks`
+to review each ACC hook and enable/trust its current definition if needed. Restart the
+session after that review; changed hook definitions may require trust again.
+
+If the installer preserved your existing Codex sandbox settings, verify the named ACC
+state directory is in `sandbox_workspace_write.writable_roots` in the config it identifies.
+ACC keeps those user settings unchanged. Installed files alone do not establish that hooks
+are active; `acc doctor` leaves current readiness unverified and directs you to Codex.
 
 If you opt into Claude Code's experimental idle delivery, Claude also shows its own
 development-channel warning at every startup. The feature is off by default, can spend
@@ -46,6 +69,16 @@ Same-client addresses can be ambiguous when several instances are live; agents u
 exact participant ids in the roster when needed. See [Concepts](CONCEPTS.md) for participant
 and session identity.
 
+A second repeatable pattern is review and handoff. Ask the implementing agent to request
+review of an identified revision (a commit when Git is available, or named files and
+version otherwise) and wait for the verdict. Ask the reviewer to return blocking defects
+or approval. If either session must stop, it can leave a durable handoff naming completed
+work, remaining work, and blockers. A later session can recover it from history. The
+underlying commands are [`acc request`](CLI.md#messages-and-requests), exact
+[`acc inbox --message`](CLI.md#inbox-reply-and-acknowledgement),
+[`acc reply`](CLI.md#inbox-reply-and-acknowledgement), and
+[`acc finish`](CLI.md#handoff).
+
 ## 3. Watch for useful coordination
 
 Look for an agent discovering a peer, publishing the files it expects to change, noticing a
@@ -71,11 +104,12 @@ CLI, and Kimi Code can receive a message at the next normal turn. That does not
 session. Grok, generic MCP clients, unknown versions, and unsupported platforms use the
 durable inbox instead.
 
-Claude Code's optional native channel is the only shipped idle-delivery path. It is
-experimental, never interrupts a turn already in progress, and remains subject to current
-reachability and recipient policy. Codex native live delivery is withdrawn; Codex uses its
-certified next-turn path or inbox. Read [Capabilities](CAPABILITIES.md) for exact versions,
-platforms, and limitations.
+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, an already-running
+LocalDaemon, recorded opt-in and a verified session; start it with your normal
+command. A loaded daemon thread can receive messages after its terminal exits.
+[Capabilities](CAPABILITIES.md) explains policy, versions and fallback.
 
 Delivery evidence is deliberately narrow: `queued -> offered -> retrieved -> acknowledged`.
 An offer is not proof that the model read anything, retrieval is not proof of attention, and

package/docs/GLOSSARY.md

@@ -7,7 +7,7 @@
 - **Presence** — `online`, `stale`, or `offline`, based only on observed heartbeat and pid facts.
 - **Intent** — a session's current summary and resource hints; awareness, not permission.
 - **Claim** — a leased reservation for a canonical resource such as `file:src/**`.
-- **Advisory / guarded** — a claim peers must respect versus one ACC can stop on measured client write paths; neither stops unrelated local processes.
+- **Advisory / guarded** — CLI claims default to advisory. Explicit guarded enforcement also requires certified guards from every live participant; neither mode stops unrelated local processes.
 - **Message** — an attributed untrusted `note`, `question`, `request`, `answer`, `decision`, or `handoff`.
 - **Thread** — a root message plus linked answers sharing one immutable `threadId`.
 - **Obligation** — `none`, `reply`, or `acknowledge`; what communication the recipient owes.
@@ -16,11 +16,17 @@
 - **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 to an already-running session through an official certified client API. Claude Code 2.1.258+ on macOS arm64 qualifies, behind an opt-in; it waits for a turn in progress rather than interrupting it.
+- **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.
 - **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 exact-certified next-turn recovery when live delivery is unavailable.
 - **Managed / manual lifecycle** — whether hooks report ACC presence automatically; never ownership of the external client process.
-- **MCP participation** — polling access to durable communication without native lifecycle, context, guards, or push.
+- **MCP participation** — manual incoming polling without native lifecycle, context, guards, or receive wake; outgoing messages can use an eligible recipient's opted-in native route.
+- **Bounded discovery** — inbox/history summary pages with limits and cursors; bodies require selection.
+- **Exact recovery** — read one addressed inbox body, or one history record; history reads do not advance receipts.
+- **Decision change** — an immutable decision explicitly supersedes or withdraws prior decisions; old records remain.
+- **Current decision** — a terminal recorded position or withdrawal, not proven truth; competing branches stay visible.
+- **Managed runtime** — ACC's staged installation generations and automatic-update controls, distinct from managed/manual session presence.
+- **Activation hold** — an ACC process lease or native binding that postpones runtime refresh; observed lifecycle cleanup can release a native hold without stopping a vendor daemon.
 
 See [Concepts](CONCEPTS.md) for relationships and [Protocol](PROTOCOL.md) for exact rules.

package/docs/HOW_IT_WORKS.md

@@ -32,7 +32,8 @@ ACC workspace. The native integration also gives the agent a small skill describ
 discovery, messages, replies, claims, and handoffs.
 
 A generic MCP client instead joins through `acc-mcp`, which resolves its configured
-participant and workspace when tools or resources are called. It exposes the coordination
+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).
 
@@ -95,8 +96,9 @@ receipts. [Protocol](PROTOCOL.md) defines these rules precisely.
 
 All recipients have the same durable record, but adapters expose different acceleration:
 
-- **Durable inbox:** universal recovery. An agent can retrieve the complete addressed
-  message with `acc inbox`, including by exact message id after compaction.
+- **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.
@@ -105,9 +107,15 @@ All recipients have the same durable record, but adapters expose different accel
   default, can spend tokens, never interrupts a running turn, and requires the vendor's
   visible development-channel warning.
 
-Codex native live delivery is withdrawn because the required remote mode hides the
-session's real workspace. Grok, generic MCP, unknown versions, and uncaptured platforms use
-inbox polling. [Capabilities](CAPABILITIES.md) lists the evidence and exact fallbacks.
+- **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.
+
+Grok, generic MCP, unsupported versions and uncaptured platforms use inbox polling.
+[Capabilities](CAPABILITIES.md) lists evidence and fallback.
 
 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.
@@ -141,13 +149,26 @@ Before changing files, an agent can publish intent and claim a narrow resource s
 `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.
 
-Claims are not operating-system locks. A claim is `guarded` only when every relevant live
-client exposes a captured pre-write guard for the path ACC can recognize. Otherwise it 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
+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.
 
-## 8. The boundaries remain visible
+## 8. Peers recover history and explicit decision changes
+
+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.
+
+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.
+
+## 9. The boundaries remain visible
 
 ACC stores only coordination data an agent explicitly publishes: identity, presence,
 one-line intent, claims, messages, replies, handoffs, receipts, and events. It never collects

package/docs/MCP.md

@@ -1,9 +1,11 @@
 # MCP
 
 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. It is
-a manual polling integration: it cannot infer the client's lifecycle, intercept writes,
-inject a normal turn, or push a message.
+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
@@ -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.
+
+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,15 +63,46 @@ 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.
+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
 
@@ -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.
 
-## Poll without overstating delivery
+## 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.
 
-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`.
+`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
 
-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.
+`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)