agents-can-communicate 0.3.0 → 0.3.1

package/docs/GLOSSARY.md

@@ -1,8 +1,8 @@
 # Glossary
 
-- **Workspace** — one local coordination room; all worktrees of a Git repository share it.
-- **Participant** — the stable address that sends and receives messages.
-- **Session** — one independently opened client conversation participating in a workspace.
+- **Workspace** — one same-machine, same-OS-user coordination room; all worktrees of a Git repository share it.
+- **Participant** — the address that sends and receives messages; it survives unrelated conversations only when explicitly configured.
+- **Session** — one independently opened client conversation participating in a workspace; its id supplies the default participant address.
 - **Generation** — the token proving a mutation belongs to the current opening of a session.
 - **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.
@@ -16,7 +16,7 @@
 - **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. No shipped adapter currently qualifies.
+- **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.
 - **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.

package/docs/HOW_IT_WORKS.md

@@ -1,277 +1,163 @@
 # 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. A client session joins a workspace
+## 1. The integrations introduce the peers
 
-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:
+`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.
 
-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.
+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
+tools but does not install the native clients' skill. See its
+[manual MCP boundary](MCP.md#account-for-the-manual-boundary).
 
-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.
+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.
 
-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.
+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.
 
-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.
+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.
 
-## 2. Sessions publish awareness, not assignments
+## 2. Each agent shares a small amount of work context
 
-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.
+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.
 
-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.
+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.
 
-## 3. Sending commits the durable truth first
+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.
 
-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:
+## 3. A dependency becomes a direct question
 
-- the immutable logical message, including sender, recipients, kind, obligation, thread,
-  and explicit body;
-- one `queued` receipt for each recipient; and
-- a `message.recorded` event.
+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 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.
+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.
 
-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.
+## 4. ACC records before it tries delivery
 
-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.
+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.
 
-## 4. Delivery has three paths
+That order is the central reliability guarantee:
 
-The paths share one durable record but prove different facts.
+```text
+agent sends -> durable message and queued receipt -> optional delivery attempt
+```
 
-### Durable inbox
+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.
 
-`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.
+## 5. The receiving client chooses the delivery path
 
-### Certified next-turn projection
+All recipients have the same durable record, but adapters expose different acceleration:
 
-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.
+- **Durable inbox:** universal recovery. An agent can retrieve the complete addressed
+  message with `acc inbox`, including by exact message id after 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.
 
-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.
+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.
 
-### 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.
-
-## 5. Reply closes the communication obligation
-
-The complete question-and-answer path is:
+- `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.
 
-```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
-```
+There is no `seen` receipt and no ACC task state such as accepted, running, or done.
 
-`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.
+## 7. Claims warn before edits overlap
 
-Receipts are per recipient and monotonic:
+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.
 
-```text
-queued -> offered -> retrieved -> acknowledged
-```
-
-`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.
+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
+user-facing distinction.
 
-## 6. The filesystem is the control plane
+## 8. 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,9 @@
 # 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. It is
+a manual polling integration: it cannot infer the client's lifecycle, intercept writes,
+inject a normal turn, or push a message.
 
 ```mermaid
 graph LR
@@ -11,7 +11,7 @@ graph LR
   M --> S[("ACC durable store")]
 ```
 
-## Register
+## Configure the server
 
 ```json
 {
@@ -33,7 +33,7 @@ The server implements MCP protocol revision `2026-07-28` over newline-delimited
 stdio. Tool input schemas are closed: unknown fields and invalid conditional shapes are
 rejected before a session is resolved.
 
-## Tools
+## Call the durable tools
 
 | Tool | Required input | Optional input |
 |---|---|---|
@@ -63,7 +63,7 @@ resolves the configured MCP participant and advances only the returned receipts
 `retrieved`, just like the inbox tool. Snapshot and roster reads do not advance receipts.
 A full snapshot is for explicit workspace forensics.
 
-## Capability floor
+## Account for the manual boundary
 
 The generic MCP capability declaration is all false:
 
@@ -79,7 +79,7 @@ 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
+## Poll without overstating delivery
 
 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.

package/docs/PROTOCOL.md

@@ -1,8 +1,9 @@
 # Protocol
 
-The protocol is the vendor-neutral contract shared by core, CLI, MCP, storage, and every
-adapter. Version 0.2 uses store schema version `3` and deliberately rejects v0.1 state.
-There is no compatibility reader, conversion, archive path, or automatic deletion.
+Use this page when implementing or checking a boundary shared by core, CLI, MCP, storage,
+and adapters. Protocol version 0.2 uses store schema version `3` and deliberately rejects
+v0.1 state. There is no compatibility reader, conversion, archive path, or automatic
+deletion.
 
 ## Durable records
 
@@ -24,7 +25,9 @@ Workspace
 ```
 
 - A workspace is one local coordination room.
-- A participant is the stable recipient of a message.
+- A participant is the recipient address for a message. A hooked session gets a default
+  address derived from its client session id; only an explicitly supplied participant id
+  is stable across unrelated client conversations.
 - A session is one client conversation. Its unguessable generation token proves that a
   later mutation still belongs to the current opening.
 
@@ -186,9 +189,11 @@ The recipient owns `livePolicy` because native push may start a model turn:
 - `all`: every addressed kind may use live push.
 
 Default is `off`. Policy never creates a capability. The router still requires a current
-reachable binding, one unambiguous recipient generation, a passing exact-version
-certification, and adapter acceptance. The current Codex and Claude captures do not meet
-those requirements; all shipped native live routes therefore fall back durably.
+reachable binding, one unambiguous recipient generation, supported client evidence, and
+adapter acceptance. Claude Code live delivery on macOS arm64 uses a captured 2.1.258
+minimum plus a current feature probe and per-session protocol handshake; it was confirmed
+again on 2.1.260. Codex's queue transport was captured but withdrawn because its required
+mode hides the session workspace. Every unavailable or refused route falls back durably.
 
 ## Attention and sync