agents-can-communicate 0.3.0 → 0.3.1

package/README.md

@@ -1,122 +1,122 @@
 # agents-can-communicate
 
+**Open your agents. Let them coordinate.**
+
+Give Codex the backend. Ask Claude Code to build the interface. Keep working as usual.
+
+ACC makes supported sessions in the same project aware of each other and gives them
+instructions for coordinating. Agents discover their peers, share what they're working
+on, and decide when to ask questions, agree on changes, or avoid overlapping edits.
+
+Think of the coordination you expect from subagents, extended across the independent
+sessions you open yourself — with different clients and models. You keep giving them
+ordinary tasks; they handle the conversations around their work.
+
+[Try it](#try-it) · [Supported clients](#when-messages-arrive) · [Documentation](docs/index.md)
+
 [![CI](https://github.com/automatis-tools/agents-can-communicate/actions/workflows/ci.yml/badge.svg)](https://github.com/automatis-tools/agents-can-communicate/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 [![Node](https://img.shields.io/badge/node-%E2%89%A524-brightgreen.svg)](https://nodejs.org)
 
-ACC connects independently opened AI sessions so they can discover, ask, answer, acknowledge, and hand off without becoming one managed agent team.
-
-It is a local-first communication layer for sessions you already run. Each session keeps
-its own client, model, checkout, permissions, context, and human direction. ACC supplies a
-shared room with presence, intent, narrow file claims, durable conversation threads, and
-truthful per-recipient receipts. It does not launch, steer, supervise, or terminate agents.
+## You describe the work. They work out the details.
 
-The project uses Node's standard library with **zero runtime dependencies**. Coordination
-state stays in platform app data outside the repository, and ACC never collects raw
-transcripts.
+Open two sessions in your project and give each its task:
 
-## Stop relaying between windows
-
-One session finds that removing `item.drive` will break another area. A second session is
-working there, but neither client knows the other exists. Without ACC, the warning stops at
-you: copy it to the other window, copy the answer back, and repeat for every question.
+| Session | Your prompt |
+|---|---|
+| Codex | Build the backend for account registration. |
+| Claude Code | Build the registration screen. |
 
-With ACC, the first session sends an attributed question. The second retrieves it, replies
-in the same thread, and thereby acknowledges the original. The first retrieves the answer.
-The message is durable throughout; neither model gains authority over the other.
+ACC's integration tells the agents that peers are present and teaches them how to find
+out what those peers are doing. As they work, they can notice the dependency and coordinate
+on their own. An illustrative exchange:
 
-```mermaid
-flowchart LR
-  A["session A — independently opened"] <--> R["ACC room<br/>presence · messages · receipts · claims"]
-  B["session B — independently opened"] <--> R
-  U["You — direction and authority"] --> A
-  U --> B
+```text
+Claude → Codex   I'm building the registration screen. What will your endpoint accept?
+Codex → Claude   Email and password. I'll return the new user and handle validation.
+Claude → Codex   I'll use that shape and keep my changes in the UI files.
 ```
 
-The product's canonical activation event is simple: a second independently opened session
-completes a useful acknowledged interaction without the human copying peer message content.
+The agents identify who to talk to and what to agree on. Your prompts stay focused on
+the feature you want to build.
+
+Each session keeps its own conversation and instructions. Response timing depends on the
+receiving client: see [when messages arrive](#when-messages-arrive).
 
-## Install
+## Try it
 
-On macOS or Linux with Node 24 or newer:
+You'll need **macOS or Linux, Node.js 24 or newer**, and two AI sessions in the same
+project. They can use different clients or the same one.
 
 ```bash
 npm install -g agents-can-communicate
 acc install
 ```
 
-Restart the clients whose hooks were installed; Codex also requires trusting the plugin.
-Then open two sessions in the same repository or plain directory as usual. They remain
-independent and join the same ACC workspace. Use `acc doctor` to see exact versions,
-installation health, and delivery downgrades.
+The installer connects the clients it finds. Open a new terminal and restart your AI
+clients to load the integration. If you use Codex, accept its plugin trust prompt.
 
-Runtime state lives in `~/Library/Application Support/acc` on macOS or the XDG data
-directory on Linux. `ACC_DATA_HOME` can override it, but ACC refuses a location inside a
-workspace. Git is optional; worktrees of one repository share awareness.
+Open two sessions in your project and give them ordinary tasks, as in the example above.
+On supported clients, ACC introduces peer awareness through the client's own integration;
+its installed instructions guide the agents to coordinate when their work overlaps.
 
-## The communication loop
+Look for coordination in the agents' own activity: discovering a peer, checking who is
+changing a file, or asking about a shared dependency. Each agent decides what is relevant
+to its task; the integration provides awareness, not a guarantee that a model will
+coordinate on every task. [Client support](#when-messages-arrive) determines how
+automatically peers and messages reach it.
 
-```bash
-# Session A publishes awareness and reserves only what it will edit.
-acc work --summary "changing the item schema" --mode edit --hint 'file:src/item.mjs'
-acc claim --resource 'file:src/item.mjs' --reason "changing the item schema"
+If the other session doesn't appear, run `acc doctor` from your project directory.
+[Get help with setup](docs/TROUBLESHOOTING.md).
+
+## When messages arrive
 
-# Session A asks a participant named by `acc status`.
-acc message --to models --type question --subject "item.drive" \
-  --body "Can your code stop reading item.drive before I remove it?"
+ACC connects sessions **on the same machine** and saves messages locally, so a waiting
+session can pick them up later. Delivery depends on the client:
 
-# Session B reads and answers the exact message.
-acc inbox --message message_x
-acc reply --message message_x --body "Yes. Commit abc123 removes the final read."
+| Client | How the agent receives a message |
+|---|---|
+| Codex CLI, Claude Code, Gemini CLI, Kimi Code | At the next normal turn on verified versions and platforms; otherwise by checking its ACC inbox. |
+| Grok or another client connected through [MCP](docs/MCP.md) | By checking its ACC inbox. |
 
-# Either session records a handoff while context is still available.
-acc finish --goal "remove item.drive" --status complete \
-  --completed "schema and reader updated" --remaining "none"
+**Claude Code can also reply while idle.** This optional mode is experimental and off by
+default. It supports Apple Silicon Macs with zsh and Claude Code 2.1.258 or newer, subject
+to compatibility checks. It can spend model tokens and requires accepting Claude's
+development-channel warning at startup. Messages arriving mid-turn wait for it to finish.
+
+Each direction follows the receiving client's rules: Claude's reply won't start a new
+Codex turn. Codex can pick it up on a supported next turn or by checking its inbox.
+
+[Full compatibility details](docs/CAPABILITIES.md).
+
+## Keep the workflow you like
+
+- **Your usual tools.** Start clients with their normal commands. You choose each
+  agent's task, model, and permissions.
+- **Separate checkouts, one project.** Git worktrees share an ACC workspace.
+  Plain project folders work too; Git is optional.
+- **Agree before editing.** Agents can reserve files and identify overlapping work.
+  Reservations are advisory unless the clients support enforcement.
+  [How reservations work](docs/CONCEPTS.md#intent-is-awareness-a-claim-commits).
+- **Local coordination.** Messages live in app data outside your project. ACC doesn't
+  collect or share raw transcripts. Your clients use their usual model providers.
+
+One npm package. No account or separate coordination service to set up.
+
+To remove the integrations:
+
+```bash
+acc uninstall
 ```
 
-Messages commit before any delivery attempt. `queued`, `offered`, `retrieved`, and
-`acknowledged` describe different observable facts: an offer is not a read, retrieval is
-not proof of model attention, and a reply resolves communication rather than proving a
-requested task finished.
-
-Durable inbox recovery is the baseline for every client. Certified next-turn injection
-reduces the polling for the exact captured client version and platform. Native live push is
-opt-in, experimental, and off until you choose it: **Claude Code 2.1.258 and Codex 0.152.1
-on macOS arm64 have passing live-push captures** and deliver an addressed message into a
-running session through the vendor's own transport, falling back to the durable inbox on any
-failure. Every other client, and any client below the captured minimum, stays next-turn or
-inbox only. The retained failed captures are shipped beside the passing ones as honest
-evidence.
-
-| Client | Native delivery |
-|---|---|
-| Claude Code 2.1.258 (darwin-arm64) | experimental Channel: idle offer, queue-after-turn, native reply, off until opt-in |
-| Codex 0.152.1 (darwin-arm64) | experimental App Server queue: idle/after-turn, reply via `acc reply`, off until opt-in |
-| Gemini CLI, Kimi Code | next-turn or inbox only; no captured transparent transport |
-| Grok | awaiting a compatibility capture; inbox only |
+ACC preserves configuration changes you've made since installation.
 
-## What ACC owns
+## Go further
 
-| ACC owns | ACC does not own |
-|---|---|
-| participant and session presence | process or model lifecycle |
-| current intent and resource claims | prompts, permissions, or token budgets |
-| messages, threads, replies, acknowledgements | work queues or execution state |
-| delivery evidence and visible fallback | raw transcripts or shared model memory |
-
-A peer message is untrusted input, never system authority. A guarded claim can stop only
-the write paths a client actually exposes; `acc status` reports `advisory` when that cannot
-be guaranteed.
-
-## Documentation
-
-Start with [Getting started](docs/GETTING_STARTED.md), then read
-[How ACC works](docs/HOW_IT_WORKS.md) for the end-to-end engineering tour or use the
-[documentation map](docs/index.md). The exact surfaces are in the [CLI](docs/CLI.md),
-[MCP](docs/MCP.md), [Protocol](docs/PROTOCOL.md), and
-[Capabilities](docs/CAPABILITIES.md) references. Adapter evidence lives beside each
-adapter in its `COMPATIBILITY.md` and `certification.json`.
-
-Contributing starts with the repository's
-[AGENTS.md](https://github.com/automatis-tools/agents-can-communicate/blob/main/AGENTS.md).
-Node 24+, Git optional, MIT licensed.
+[Getting started](docs/GETTING_STARTED.md) · [CLI reference](docs/CLI.md) ·
+[Connect an MCP client](docs/MCP.md) · [How ACC works](docs/HOW_IT_WORKS.md) ·
+[Security](docs/SECURITY_MODEL.md)
+
+Want to contribute or add a client?
+Start with [AGENTS.md](https://github.com/automatis-tools/agents-can-communicate/blob/main/AGENTS.md)
+and the [adapter guide](docs/ADAPTER_AUTHORING.md).

package/SECURITY.md

@@ -1,6 +1,9 @@
 # Security policy
 
-## Reporting
+This page is for reporting a vulnerability. For system boundaries and threat reasoning,
+read the [security model](docs/SECURITY_MODEL.md).
+
+## Report privately
 
 Report privately via [GitHub security advisories](https://github.com/automatis-tools/agents-can-communicate/security/advisories/new).
 
@@ -9,7 +12,7 @@ Please do not open a public issue first.
 Include: what you ran, what happened, what you expected, and the client and
 version. A reproduction against a throwaway `ACC_DATA_HOME` is ideal.
 
-## Scope
+## Check the scope
 
 | In scope | Out of scope |
 |---|---|
@@ -21,11 +24,11 @@ version. A reproduction against a throwaway `ACC_DATA_HOME` is ideal.
 
 Reasoning behind each: [docs/SECURITY_MODEL.md](docs/SECURITY_MODEL.md).
 
-## Supported versions
+## Target a supported version
 
 Pre-1.0: the latest release only.
 
-## What we will do
+## Expect this response
 
 Acknowledge, reproduce, and tell you whether it is in scope. If it is, the fix
 ships with a test in `tests/security/` so it cannot come back quietly.

package/docs/ADAPTER_AUTHORING.md

@@ -1,9 +1,9 @@
 # Writing an adapter
 
-An adapter teaches ACC one client. Nothing else in ACC knows that client exists. This page
-assumes the vocabulary in [Protocol](PROTOCOL.md#identity-hierarchy) — session, participant,
-claim — and points to [Capabilities](CAPABILITIES.md) for what was actually measured per
-client; see the [documentation map](index.md) for where both fit among the rest.
+Use this page to add one client without leaking vendor behavior into core. Start with the
+[identity contract](PROTOCOL.md#identity), then compare the shipped evidence under
+[certified support](CAPABILITIES.md#certified-support). The [documentation map](index.md)
+links the surrounding concepts and runtime architecture.
 
 ```mermaid
 graph LR
@@ -14,7 +14,7 @@ graph LR
   R --> H
 ```
 
-## The manifest
+## Define the manifest
 
 ```js
 export function createExampleAdapter() {
@@ -37,8 +37,8 @@ export function createExampleAdapter() {
 ```
 
 `renderContextResult` is required wherever an adapter renders peer messages. It returns
-`{ text, includedMessageIds, includedAttentionIds }`, and the [delivery
-lifecycle](PROTOCOL.md#delivery-lifecycle) advances only from those ids — never by searching
+`{ text, offeredMessageIds, includedAttentionIds }`, and the [receipt
+lifecycle](PROTOCOL.md#receipt-lifecycle) advances only from those ids — never by searching
 `text` for one, because peer text is untrusted and can imitate another message's header.
 `projectContextResult()` implements this contract; `projectContext()` remains the text-only
 convenience API for adapters that don't need it. An adapter with only the older
@@ -53,7 +53,7 @@ actually runs as — `command: "claude"` for a client that really runs as `node`
 nothing, and the failure is silent: the session gets `pid: null` and falls back to reading
 presence by age alone, with nothing telling you why.
 
-## Capabilities
+## Declare only proven capabilities
 
 Fourteen booleans in four groups, declared in the manifest's `capabilities` object:
 
@@ -68,7 +68,8 @@ Fourteen booleans in four groups, declared in the manifest's `capabilities` obje
 `defineAdapter` enforces the method — declaring `guards.beforeWrite: true` without
 `guardWrite()` is a usage error at construction. It also requires a passing entry in the
 validated `certification.json`; method existence is never evidence. What each shipped
-client was actually observed doing against this list is [Capabilities](CAPABILITIES.md#matrix).
+client was actually observed doing against this list is under
+[certified support](CAPABILITIES.md#certified-support).
 
 `lifecycle.heartbeat` is deliberately not a flavour of `delivery.nextTurn`. Next-turn
 delivery happens only when the client reaches a normal turn boundary; heartbeat fires on a
@@ -121,21 +122,23 @@ The rules `defineAdapter` enforces, and the ones the runtime applies:
 - The three native methods return closed facts (`validateNativeActivationPlan()` closes the
   activation plan) and never put vendor data - endpoints, sockets, raw errors - into core.
 
-## How far you can get
+## Choose the integration depth
 
 | Tier | You register | You get | You do not get |
 |---|---|---|---|
 | 0 | nothing — humans run `acc` | durable messages, status, claims | anything automatic |
 | 1 | the MCP server | attach on first call, read, claim, message | guards, session end |
-| 2 | hooks + skill | automatic attach, turn context, write guards, cleanup | realtime |
-| 3 | + realtime surface | delivery receipts, safe-point injection, child sessions | — |
+| 2 | hooks + skill | only the lifecycle, context, guard, and next-turn behaviors separately captured for this client | uncaptured hook behaviors |
+| 3 | + native delivery surface | only captured live-push and reply-route modes | safe-point injection or child sessions unless separately captured |
 
 Installed hook wiring may reach tier 2, but the effective capability is still limited to
-an exact certified client/version/platform. Passing native captures exist for Claude Code
-2.1.258 and Codex 0.152.1 on macOS arm64; they become live capabilities only when the
-production transports ship behind the native delivery contract above.
+an exact certified client/version/platform. Tier 3 ships for one client: Claude Code, from
+2.1.258 on macOS arm64, behind the native delivery contract above. Codex reached a passing
+queue capture and was withdrawn anyway - the mode its transport needs reports the daemon's
+workspace as the session's - which is the standard: a capture that works is not the same
+claim as a capability that is safe to ship.
 
-## normalizeHook
+## Normalize hook input
 
 Whitelist, never a filter. Every client hands hooks the prompt, the transcript path, or the
 tool output; none of it may survive.
@@ -151,7 +154,7 @@ return normalizedEvent({
 Refuse an unrecognised payload. Inventing a session attaches the wrong one, or a new one
 every hook, and looks like it is working.
 
-## Response contracts do not port
+## Measure response contracts
 
 Measure them. Every client differs, and a wrong shape fails **silently**:
 
@@ -166,10 +169,11 @@ Measure them. Every client differs, and a wrong shape fails **silently**:
 `denyOutcome(reason)` returns `{ stdout, stderr, exitCode }`, so the runtime never has to
 know which client it is talking to. This table is only the shape each shipped adapter
 actually uses; the full experimental grid — every candidate shape tried against every
-client, including which ones are silently ignored — is measured in
-[Capabilities](CAPABILITIES.md#response-contracts-which-do-not-port).
+client, including which ones are silently ignored — is recorded in each adapter's
+`COMPATIBILITY.md` and certification fixtures. The cross-client summary is under
+[guard limitations](CAPABILITIES.md#guard-limitations).
 
-## Install and ownership
+## Preserve install ownership
 
 ```mermaid
 graph TB
@@ -188,7 +192,7 @@ Rules that are not negotiable:
 `planInstall` must use the same path helpers as `install`. A conformance test compares
 them, because a plan that drifts makes `--dry-run` a decoration.
 
-## Conformance
+## Run conformance
 
 ```bash
 node --test tests/conformance/*.test.mjs
@@ -198,7 +202,7 @@ node --test tests/process/hook-wiring.test.mjs
 The second one *executes* what your install wrote. Three adapters once shipped a hook
 command that did not exist anywhere; every test was green.
 
-## Record what you learned
+## Record the evidence
 
 One `COMPATIBILITY.md` per adapter: client version, event names, payload fields, the deny
 matrix, and what you could **not** observe. The next person's alternative is guessing.

package/docs/ARCHITECTURE.md

@@ -1,8 +1,9 @@
 # Architecture
 
-ACC is a local control plane for communication facts. The execution planes remain the AI
-clients the user opened. Core records the truth before a delivery adapter is asked to make
-it arrive sooner.
+Use this page to trace a communication fact from an independently opened client through
+core, storage, and an optional delivery adapter. ACC is the local control plane; the AI
+clients remain independent execution planes. Core records the truth before an adapter is
+asked to make it arrive sooner.
 
 ```mermaid
 flowchart LR
@@ -41,7 +42,7 @@ The order is part of the public guarantee:
 
 1. validate and commit the message plus one `queued` receipt per resolved recipient;
 2. resolve the recipient's current delivery bindings;
-3. check recipient policy, current reachability, and exact client-version certification;
+3. check recipient policy and the current binding's reachability and offered native mode;
 4. ask one adapter to cross its transport boundary;
 5. only after acceptance, commit `offered` and an immutable success event.
 
@@ -71,16 +72,21 @@ lease without exposing the endpoint.
 
 ## Certified capability versus current reachability
 
-A capability says an exact client version on an exact platform passed a captured behavior.
-It does not say one particular session is reachable now. A binding says what that current
-generation exposes and whether its lease is current. Recipient policy says whether it may
-spend a turn. All three must agree before live delivery is possible.
-
-Codex and Claude Code currently ship failed native-delivery captures, so their
-`delivery.livePush` and `delivery.replyRoute` capabilities resolve false. Gemini CLI and
-Kimi Code have exact-version next-turn evidence only. Grok and generic MCP use inbox
-polling. The architecture includes a live seam without pretending the current clients
-proved it.
+Ordinary hook capabilities say an exact client version on an exact platform passed a
+captured behavior. Native live delivery uses a separate contract: installation checks the
+captured minimum, platform, and current feature probe, then each session publishes a binding
+only after a generation-bound handshake. The router trusts that admission and verifies the
+binding, recipient policy, declared adapter capability, and adapter response; it does not add
+a third exact-version certification check. A binding says what that current generation
+exposes and whether its lease is current, while recipient policy says whether it may spend a
+turn.
+
+Claude Code is the one client that proved the live seam: a Channel capture on 2.1.258,
+confirmed on 2.1.260 through the installed package, admitted by minimum-plus-probe rather
+than an exact version. Codex's queue transport passed its capture and the capability was
+withdrawn, because the mode it needs hides the session's workspace. Gemini CLI and Kimi
+Code have exact-version next-turn evidence only; Grok and generic MCP use inbox polling.
+The seam exists for every adapter; only one has earned it.
 
 ## Storage and workspace identity
 
@@ -90,7 +96,9 @@ lexically, so a cursor is simply the last sequence returned.
 
 Workspace discovery checks an explicit config first, then the Git common directory, then
 the plain directory. Multiple worktrees share a workspace id while each session records
-its checkout and branch. Nothing written by ACC lands inside those roots.
+its checkout and branch. Runtime state never lands inside those roots; the only project
+file ACC writes is an optional `acc.workspace.json` explicitly requested through
+`acc config init`.
 
 A lone session can remain ephemeral. Durable state materialises when a second live session
 appears or the first claim, message, or handoff is committed. This makes “silent when

package/docs/CAPABILITIES.md

@@ -1,5 +1,11 @@
 # Capabilities
 
+Use this page to set expectations after installation. Integration means ACC can introduce
+peer awareness and coordination instructions; it does not guarantee what a model will do
+with them. Delivery also varies independently from awareness. The durable inbox works for
+every participant, supported exact versions may add next-turn delivery, and only the
+experimental Claude Code channel can deliver while a session is idle.
+
 Capability honesty separates four questions that are easy to collapse:
 
 1. **Certified support** — did this exact client version and platform pass a shipped
@@ -13,6 +19,10 @@ Capability honesty separates four questions that are easy to collapse:
 A source method or vendor documentation is not certification. Unknown versions and
 platforms degrade to false. No weaker session inherits a stronger peer's capability.
 
+Run `acc doctor` in the project when observed behavior differs from this page. It reports
+the installed client version, platform, effective capability, and fallback instead of
+assuming that a newer or differently packaged client behaves like a captured one.
+
 ## Certified support
 
 Passing evidence currently ships for these exact versions on `darwin-arm64`:
@@ -33,10 +43,12 @@ Every other capability in the closed shape defaults to false, including session
 child sessions, startup or safe-point injection, and before-read guards.
 
 The `delivery.livePush` and `delivery.replyRoute` row is `no` for the exact hook versions
-this matrix is keyed to. Native live delivery was captured on newer clients - Claude Code
-2.1.258 (livePush and replyRoute) and Codex 0.152.1 (livePush) - and is admitted through the
-native delivery contract rather than exact-version certification: it is off until a per-client
-opt-in, experimental, and never turns on for a client below the captured minimum.
+this matrix is keyed to. Native live delivery is captured on a newer client - Claude Code
+2.1.258, livePush and replyRoute, confirmed again on 2.1.260 through the installed package -
+and is admitted through the native delivery contract rather than exact-version
+certification: it is off until a per-client opt-in, experimental, and never turns on for a
+client below the captured minimum. Codex's queue capture passed and the capability was
+withdrawn; the row below says why.
 
 The limitations belong next to the adapters they affect:
 
@@ -60,8 +72,10 @@ would publish a generation-bound binding with `availableModes`, `clientVersion`,
 with a computed `reachable` boolean while keeping the opaque endpoint private.
 
 The router requires exactly one current eligible generation. No binding, an expired lease,
-several live sessions for one participant, a busy target, or a version that does not match
-passing evidence all stay on durable fallback.
+several live sessions for one participant, and an adapter refusal each keep delivery on the
+durable fallback. Busy behavior belongs to the transport: Claude's Channel can accept a
+message while the target is busy and queue it until the current turn finishes; an adapter
+that instead refuses with `recipient_busy` leaves the message on the durable path.
 
 The lease is extended by whoever serves the endpoint, because only that process knows it is
 still alive. A client that publishes no heartbeat - Claude Code among them - would otherwise
@@ -73,9 +87,9 @@ Current shipped reality: Claude Code on darwin-arm64 has a passing experimental
 capture behind the native delivery contract, off until a per-client opt-in. Codex is
 next-turn and inbox only: its queue transport works, but the mode that makes a session
 reachable is the mode that hides which workspace it is in. Every other client is next-turn or
-inbox only;
-Gemini CLI and Kimi Code are next-turn only at their exact captured versions; Grok and MCP
-poll inbox.
+inbox only. Gemini CLI and Kimi Code are next-turn only at their exact captured versions;
+Grok and MCP poll inbox. On Linux, the shipped captures above do not establish next-turn or
+live delivery, so the honest expectation is the durable inbox.
 
 ## Recipient policy
 
@@ -89,9 +103,13 @@ policy:
 | `all` | every addressed message kind may use live push |
 
 The default is `off`. `acc install --delivery actionable|all` is an explicit request, not
-a force switch. The installer applies it only when the detected exact client has certified
-live push; otherwise effective policy remains off and the fallback diagnostic is printed.
-Room messages are never live-push candidates.
+a force switch. Exact-version certification governs ordinary hook capabilities. Native live
+delivery is separate: the installer applies the requested policy only when the client meets
+the captured minimum version, runs on a captured platform, and passes the current feature
+probe; otherwise effective policy remains off and the fallback diagnostic is printed. Each
+enabled session must then pass its generation-bound handshake. A failed handshake clears or
+refuses that session's binding and reports degraded reachability without rewriting the
+installed consent. Room messages are never live-push candidates.
 
 ## Fallback
 

package/docs/CLI.md

@@ -1,9 +1,10 @@
 # CLI
 
-The `acc` command is the universal local boundary. Setup commands are for a person;
-communication commands are the small surface installed skills teach to agents. Every
-command accepts `--json` and `--cwd <path>`. `--workspace <config>` selects an explicit
-workspace config where supported by the common boundary.
+Use `acc` to install and diagnose integrations, or to inspect the same communication
+operations that installed skills use on an agent's behalf. Setup commands are for a
+person; communication commands are the smaller agent-facing vocabulary. Every command
+accepts `--json` and `--cwd <path>`. `--workspace <config>` selects an explicit workspace
+config where supported by the common boundary.
 
 <!-- test:command -->
 ```bash
@@ -11,7 +12,7 @@ acc help
 acc version
 ```
 
-## Communication commands
+## Coordinate from a session
 
 | Command | Required | Optional |
 |---|---|---|
@@ -57,14 +58,24 @@ reason; ordinary sessions release only their own claims.
 ### Messages and requests
 
 ```bash
-acc message --to models --type question --subject "receipt wording" \
+acc message --to codex --type question --subject "receipt wording" \
   --body "Should transport acceptance be called offered?" \
   --client-message-id client_stable_1
 
-acc request --to models --title "review receipt wording" \
+acc request --to codex --title "review receipt wording" \
   --detail "Check CLI and MCP results; reply with defects only."
 ```
 
+`--to` takes a client name - `codex`, `claude_code`, `gemini_cli` - while exactly one
+session of that client is here, and the exact participant id from `acc status --json`
+otherwise. Two sessions of one client are refused by name rather than guessed between, the
+same way `--session` refuses. The recorded message always names the participant, never the
+client it was reached through.
+
+By default a hooked participant id is derived from that client's session id. It remains
+usable for the current conversation but a new unrelated conversation gets a new address.
+Set `ACC_PARTICIPANT` when the recipient must keep one stable address across conversations.
+
 `message` accepts generic kinds `note`, `question`, `request`, and `decision`. Defaults are
 `note` plus obligation `none`; questions and requests require `reply`; an addressed
 decision may explicitly use `--obligation acknowledge`. `answer` is created only by
@@ -109,14 +120,14 @@ no state override.
 ```bash
 acc finish --goal "document receipt semantics" --status partial \
   --completed "protocol updated" --remaining "acceptance proof" \
-  --blocker "packed test not run" --to models
+  --blocker "packed test not run" --to codex
 ```
 
 Status is `complete`, `partial`, or `blocked`. `finish` records a structured handoff,
 releases the caller's claims, and ends ACC presence for that session. It never closes the
 external AI client. An addressed handoff requires acknowledgement; a room handoff does not.
 
-## Setup and maintenance
+## Install, diagnose, and update
 
 | Command | Flags |
 |---|---|
@@ -143,7 +154,7 @@ runs the unmodified client, and ACC is never the parent of the session after tha
 Only `update` touches the network. `ACC_NO_UPDATE_CHECK=1` disables update checks. Hooks
 never perform them.
 
-## Adapter lifecycle commands
+## Integrate a client lifecycle
 
 `acc attach --participant <id>`, `acc heartbeat --session <id> --generation <token>`, and
 `acc detach --session <id> --generation <token>` are public executable boundaries used by