agents-can-communicate 0.1.18 → 0.2.0

package/docs/ARCHITECTURE.md

@@ -0,0 +1,131 @@
+# 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.
+
+```mermaid
+flowchart LR
+  S["sender session"] -->|record| C["core"]
+  C --> D[("filesystem store<br/>outside repositories")]
+  C -->|message id| R["delivery router"]
+  R --> A["certified recipient adapter"]
+  A --> T["already-running recipient session"]
+  T -->|reply or acknowledge| C
+```
+
+ACC never starts, resumes, interrupts, supervises, or terminates the target client. A
+transport that requires owning that lifecycle is outside the product boundary.
+
+## Packages and dependency direction
+
+| Package | Owns |
+|---|---|
+| `protocol` | ids, closed schemas, semantic validation, receipt transitions, error and exit codes |
+| `core` | sessions, intent, claims, conversations, inbox, receipts, attention, ephemeral delivery bindings |
+| `storage-filesystem` | atomic transactions, event journal, materialised views, recovery, writer lock |
+| `adapter-sdk` | capability validation, exact-version certification, context projection, hook and install helpers |
+| `adapter-*` | vendor-specific hooks, responses, installation, evidence, and optional transport |
+| `delivery-router` | recipient policy, one-generation selection, safe offer, then receipt commit |
+| `hook-runner` | bounded adapter hook entry point |
+| `mcp-server` | polling participation for clients without a native adapter |
+| `cli` | universal local command boundary |
+
+Core cannot branch on a vendor name or import an adapter, Git, or
+`node:child_process`. Package-boundary tests enforce this rather than relying on
+convention.
+
+## Record, then offer
+
+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;
+4. ask one adapter to cross its transport boundary;
+5. only after acceptance, commit `offered` and an immutable success event.
+
+A failed offer records the selected recipient session id and generation with a safe
+diagnostic code, then leaves the receipt queued. Core validates that target provenance and
+derives the event actor from it. A crash after bytes cross the boundary but before the
+receipt commit may duplicate a later offer; ACC prefers that truthful underclaim to
+claiming delivery before it happened.
+
+## Delivery router is not a session manager
+
+Messages address participants. The router may choose a live path only when exactly one
+unexpired session generation is eligible. It does not open a session to make one eligible.
+Zero candidates, several candidates, an unknown version, recipient policy `off`, or an
+adapter refusal all produce durable fallback.
+
+The binding is ephemeral and stores:
+
+```text
+sessionId · generation · adapterId · clientVersion · availableModes
+livePolicy · opaqueEndpointRef · leaseUntil
+```
+
+Core validates identity and expiry but never interprets the opaque endpoint. That remains
+inside the owning adapter. `acc status` reports available modes, policy, reachability, and
+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.
+
+## Storage and workspace identity
+
+The filesystem store is the durable source of truth. Every meaningful mutation updates
+materialised records and appends an immutable event in one transaction. Sequence ids sort
+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.
+
+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
+alone” an architectural behavior, not a UI preference.
+
+## Inbox, attention, and projection
+
+Inbox reads only messages addressed to the calling participant and advances that
+participant's receipt to `retrieved`. Reply validates ownership, creates an `answer` in the
+same thread, and acknowledges the original atomically. No participant can advance another
+participant's receipt.
+
+Attention is computed from six explicit rules:
+
+| Priority | Kind | Observable trigger |
+|---|---|---|
+| 1 | `reply_required` | this participant owns an unacknowledged receipt whose message requires a reply |
+| 2 | `acknowledgement_required` | this participant owns an unacknowledged receipt whose message requires acknowledgement |
+| 3 | `recipient_unavailable` | a required recipient of this participant's message has no online session |
+| 4 | `claim_conflict` | this session's intent hint overlaps another live claim |
+| 5 | `claim_contended` | a peer intent hint overlaps a live claim this session owns |
+| 6 | `claim_expired` | a claim this session owned has reached its lease time |
+
+Semantic relevance belongs to the receiving model; correctness never depends on a hidden
+classifier.
+
+Adapters project peer bodies in an attributed untrusted frame. If a complete body cannot
+fit, the projection keeps the message id and points to `acc inbox --message <id>` instead
+of silently truncating it.
+
+## Hooks fail open
+
+Hook execution is bounded. If coordination state cannot be read or a decision cannot be
+made in time, the client action continues. ACC may warn or guard where a real hook allows
+it, but a coordination tool must not be the reason a session stops working.
+
+Next: [Protocol](PROTOCOL.md) · [Capabilities](CAPABILITIES.md) ·
+[Security model](SECURITY_MODEL.md)

package/docs/CAPABILITIES.md

@@ -1,219 +1,107 @@
 # Capabilities
 
-Capability honesty is part of the product: ACC coordinates sessions it does not own, so a
-workspace can promise only what every session in it actually exposes — one weaker
-participant lowers the reported protection level instead of inheriting a stronger label
-from its peers.
-
-Every row below is **measured**, not asserted: a `yes` has a fixture captured from a real
-session of that client version; a `no` means the behavior was not observed, not that it is
-impossible. Certified 2026-08-16 on macOS 15 (darwin 25.5.0, arm64) only — at least one
-finding here is filesystem- and path-shaped, so re-run the table before trusting it on
-another platform.
-
-## Clients
-
-| Adapter | Client | Version |
-|---|---|---|
-| `codex` | `codex-cli` | 0.147.0 |
-| `claude_code` | Claude Code | 2.1.233 |
-| `gemini_cli` | Gemini CLI | 0.37.0 and 0.55.1 |
-| `grok` | Grok | 1.0.13 |
-| `kimi` | Kimi Code | 0.36.1 |
-
-## Matrix
-
-| Capability | codex | claude_code | gemini_cli | grok | kimi |
-|---|---|---|---|---|---|
-| `lifecycle.sessionStart` | yes | yes | yes | yes | yes |
-| `lifecycle.sessionResume` | no | no | no | no | no |
-| `lifecycle.sessionEnd` | yes | yes | yes | yes | no |
+Capability honesty separates four questions that are easy to collapse:
+
+1. **Certified support** — did this exact client version and platform pass a shipped
+   real-client fixture?
+2. **Current reachability** — does one current session generation expose a live binding
+   whose lease is valid now?
+3. **Recipient policy** — did that recipient opt into spending a turn for this message
+   kind?
+4. **Fallback** — what durable path remains when any earlier answer is no?
+
+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.
+
+## Certified support
+
+Passing evidence currently ships for these exact versions on `darwin-arm64`:
+
+| Capability | Codex 0.147.0 | Claude Code 2.1.233 | Gemini CLI 0.37.0 | Grok 1.0.13 | Kimi 0.36.1 |
+|---|---:|---:|---:|---:|---:|
+| `lifecycle.sessionStart` | yes | yes | yes | no | yes |
+| `lifecycle.sessionEnd` | yes | yes | yes | no | no |
 | `lifecycle.heartbeat` | no | no | no | no | yes |
-| `lifecycle.childSessions` | no | no | no | no | no |
-| `context.startupInjection` | no | no | no | no | no |
 | `context.beforeTurnInjection` | yes | yes | yes | no | yes |
-| `context.safePointInjection` | no | no | no | no | no |
-| `guards.beforeRead` | no | no | no | no | no |
 | `guards.beforeWrite` | yes | yes | yes | no | yes |
-| `guards.beforeShell` | yes | yes | yes | no | yes |
-| `delivery.polling` | yes | yes | yes | yes | yes |
-| `delivery.activeNotification` | no | no | no | no | no |
-| `delivery.wakeDormantSession` | no | no | no | no | no |
-| `execution.launch` | no | no | no | no | no |
-| `execution.resume` | no | no | no | no | no |
-| `execution.terminate` | no | no | no | no | no |
-
-## Resolving a client's pid is not universal either
-
-Not a capability above — no adapter method backs it, so it has no row in the matrix — but
-it is presence's other signal for telling a dead process from an idle one, and it does not
-reach every client.
-
-A session's recorded pid comes from walking its process ancestry until the adapter's own
-declared binary (`client.command`) turns up in `ps -o comm=`. That only works when the
-operating system's own name for the process actually is that binary: true for a native
-executable, false for a script run through an interpreter, where `comm` reports the
-interpreter's name rather than the script's.
-
-| Client | `client.command` | `ps -o comm=` reports | Pid resolves |
-|---|---|---|---|
-| `codex` | `codex` | `codex`, a native binary | yes |
-| `claude_code` | `claude` | `claude`, a native binary | yes |
-| `gemini_cli` | `gemini` | `node` — `gemini.js` starts `#!/usr/bin/env node` | **no** |
-| `grok` | `grok` | `grok`, a native Mach-O at `~/.grok/bin/grok` | yes |
-| `kimi` | `kimi` | not installed on the machine this table was measured on; Kimi Code ships via npm as a Node.js CLI (`@moonshot-ai/kimi-code`), the same shape as Gemini CLI | **almost certainly no — not measured** |
-
-A Gemini session records `pid: null` for its whole life, and Kimi's is very likely the
-same, unconfirmed. `null` is the correct "nobody knows" answer and is handled identically
-wherever it is read — not a correctness bug. It does change what presence delivers, though:
-a confirmed-dead pid retires a session immediately and exactly, and today that is `codex`,
-`claude_code`, and `grok`. `gemini_cli` and `kimi` fall back to the same age-based floor every
-session has for whenever a pid is unavailable — thirty minutes of silence — so their
-sessions still leave, just later and on a timer instead of on the fact. See
-[ARCHITECTURE.md](ARCHITECTURE.md#presence) for the full floor.
-
-## What the yes values do not promise
-
-A capability says the client can do the thing. Several of them are conditional on how the
-client is being run, and the conditions differ per harness. These are the ones that bite.
-
-**`guards.beforeWrite` on `codex` depends on the model.** Whether the client offers
-`apply_patch` at all is a property of the model's metadata (`apply_patch_tool_type`), not
-a user setting. With a model that does not have it, edits run through `exec_command`,
-which reaches hooks as `tool_name: "Bash"` carrying a command string. A command names no
-resource, so there is nothing to compare against a claim. Observed on 0.147.0: the default
-toolset contained no `apply_patch`.
-
-**`guards.beforeWrite` on `gemini_cli` depends on the approval mode.** In the default and
-`plan` modes the client declares no write tool to the model at all. `write_file` and
-`replace` appear under `auto_edit`; `run_shell_command` under `yolo`.
-
-**`guards.beforeShell` is resource-aware where the write is unambiguous.** ACC reads the
-command for its write positions only — a redirection, an operand of a command whose whole
-job is to put bytes somewhere — and declares those paths as targets. Reading positions are
-left alone: `cat file` and `grep file` name a path and write nothing, and treating them as
-writes would have sessions blocking each other for looking.
-
-What it does not see is a language runtime opening the file itself (`python3 -c
-"open(...)"`), a command assembled at runtime, or an `eval`. A shell can still evade the
-guard. Until 0.1.7 every shell write did, which is why partial sight is the improvement it
-is: a session told to prefer the shell for file changes walked through every claim in the
-workspace.
-
-Where the guard cannot help, the turn context does: it names the claims other sessions
-hold and says which way this session stands with them. Two facts decide the wording — what
-the claim's owner asked for (`guarded` or `advisory`; see [Glossary](GLOSSARY.md)), and
-whether ACC can stop this session at all:
-
-| Claim | This session | Note |
-|---|---|---|
-| guarded | can be guarded | `file edits and recognised shell writes are blocked; a runtime can still get past` |
-| guarded | cannot be guarded | `not enforced for this session; do not edit it` |
-| advisory | either | `advisory; nothing will stop you, the owner is asking` |
-
-Unenforceable is not the same as unknown — and neither is it the same as unclaimed.
-
-**`lifecycle.sessionEnd` on `kimi` is false and it matters.** Each `kimi -p` run leaves an
-attached session that never closes itself — it just stops taking turns. Presence retires it
-instead, most likely without ever resolving a pid (see above), which means the session
-reads `offline` — and disappears from the default `acc status` view — only after thirty
-minutes of silence, not on its declared 60s heartbeat cadence. Interactive sessions
-heartbeat and do not have this problem.
-
-**`lifecycle.heartbeat` is Kimi's alone.** It fires on a timer — observed at 60002, 120004
-and 180006 ms of uptime — so an idle Kimi session keeps its presence honest. The other
-clients reach a hook only when the user takes a turn, so their idle sessions go stale while
-alive. This is why it is a capability of its own rather than a flavour of
-`delivery.polling`.
-
-**`context.beforeTurnInjection` on `grok` is false.** Grok 1.0.13 discards
-UserPromptSubmit stdout and `additionalContext`. The hook still runs (presence
-and polling), but the model is not shown that text. Agents on this client read
-`acc status` / `acc inbox` from the skill.
-
-**`guards.beforeWrite` / `beforeShell` on `grok` are false.** PreToolUse fires, and
-the matcher names `write`, `search_replace`, and `run_terminal_command`. A deny
-has not yet been captured blocking a real call, so the capability stays false.
-
-## Response contracts, which do not port
-
-The single most portable-looking mistake an adapter can make. Measured by running each
-candidate against a real session of each client and checking whether the tool actually
-ran. A dash means the candidate was never run against that client, not that it fails —
-only the shape each shipped adapter actually uses was measured on every client.
-
-| Reply to a guard hook | codex | claude_code | gemini_cli | grok | kimi |
-|---|---|---|---|---|---|
-| exit code 2 | denies | - | denies | - | denies |
-| `{"hookSpecificOutput":{…,"permissionDecision":"deny"}}` | - | denies | **ignored** | documented | denies |
-| `{"decision":"deny","reason":…}` | - | - | - | documented | - |
-| `{"decision":"block","reason":…}` | - | - | denies | - | **ignored** |
-| `{"permission":"deny"}` | - | - | ignored | - | ignored |
-| exit code 1 | - | - | ignored | - | ignored |
-
-Codex has no structured reply at all: it denies by exiting 2 with the reason on stderr.
-Gemini ignores the shape that Claude Code and Kimi Code both honour, and Kimi ignores the
-shape Gemini needs. Each ignored case fails silently — the write goes through and the
-client reports nothing.
-
-Context injection does not follow the deny contract even within one client:
-
-| Injection | codex | claude_code | gemini_cli | grok | kimi |
-|---|---|---|---|---|---|
-| `hookSpecificOutput.additionalContext` | - | works | works | **discarded** on UserPromptSubmit | works, but **not unwrapped** |
-| plain text on stdout | works | - | dropped | **discarded** on UserPromptSubmit | works |
-
-Codex delivers a hook's stdout as a `developer` role message, verbatim — the most direct
-of the four channels, and a reason for care rather than comfort: at that role a model
-reads text as instruction, so peer-authored text has to stay framed as data.
-
-Kimi Code shows the model whatever a hook printed, wrapped in
-`<hook_result hook_event="…">`, so the JSON envelope itself would end up in the
-conversation. Gemini unwraps the envelope and appends `<hook_context>…</hook_context>` to
-the user turn, and drops a bare string entirely.
-
-These two tables are the measurement; they say nothing about how an adapter produces the
-right shape without knowing which client it is talking to. That contract —
-`denyOutcome()` / `injectOutcome()` — is documented in
-[ADAPTER_AUTHORING.md](ADAPTER_AUTHORING.md#response-contracts-do-not-port).
-
-## Installation is not uniform either
-
-| | codex | claude_code | gemini_cli | grok | kimi |
-|---|---|---|---|---|---|
-| Where hooks live | marketplace plugin | plugin | `settings.json` | `~/.grok/hooks/acc.json` | `config.toml` |
-| Project-level config | no | no | yes | yes (`<project>/.grok/hooks`, unused) | **no** |
-| Hook `timeout` unit | - | - | milliseconds | **seconds** | **seconds** (max 600) |
-| Command path | absolute required | `${CLAUDE_PLUGIN_ROOT}` | absolute required | absolute required | absolute required |
-| Extra step by the user | hook trust | - | - | - | - |
-
-Kimi Code is the only one with no project-level config, so ACC edits the user's global
-`config.toml` — as a delimited block it owns, because ACC ships without dependencies and a
-hand-written TOML round-tripper would take the user's comments and formatting with it.
-
-Codex needs four things before a hook runs, not one: the plugin directory, a parseable
-marketplace, both `[marketplaces.…]` and `[plugins."…"]` registered in its config, and the
-plugin copied into `plugins/cache/<marketplace>/<plugin>/<version>/`. ACC does all four —
-that last copy is exactly and only what `codex plugin add` does, measured by diffing the
-home around it. Hook trust remains a manual step, which is the client's security model.
-
-## What a participant declares about itself
-
-Every session records `enforcement` (`guarded` | `advisory`) and `lifecycle`
-(`managed` | `manual`), taken from the adapter's proven capabilities in this matrix rather
-than from the harness's name — both default to the weaker reading, so a generic MCP client
-or a human at the CLI reads as advisory and manual. What that downgrade means for a
-workspace, and why one MCP participant in the room is enough to drop everyone else's
-protection, is explained canonically in
-[MCP.md](MCP.md#native-adapter-vs-mcp-client).
-
-**"Stoppable" is not "unevadable".** Even in a guarded workspace, a session that writes
-through a language runtime rather than a recognised shell form gets past — see
-`guards.beforeShell` above. The claim still says who is working where; enforcement is the
-floor, not the ceiling.
-
----
-
-See also: [README](index.md) for navigation, [Glossary](GLOSSARY.md) for terms,
-[Adapter authoring](ADAPTER_AUTHORING.md) for the deny/inject implementation contract, and
-[MCP](MCP.md) for the participation tier and the native-vs-MCP explanation.
+| `guards.beforeShell` | no | yes | yes | no | yes |
+| `delivery.nextTurn` | yes | yes | yes | no | yes |
+| `delivery.livePush` | no | no | no | no | no |
+| `delivery.replyRoute` | no | no | no | no | no |
+
+Every other capability in the closed shape defaults to false, including session resume,
+child sessions, startup or safe-point injection, and before-read guards.
+
+The limitations belong next to the adapters they affect:
+
+| Adapter | Exact limitation and evidence |
+|---|---|
+| Codex | 0.147.0 next-turn stdout arrives as unwrapped developer-role context and requires plugin trust. The separate 0.152.0 native capture found no daemon control socket; ACC did not start one, so live push and reply routing remain false. |
+| Claude Code | 2.1.233 next-turn delivery waits for the next user prompt. The 2.1.252 channel capture stopped at the development-channel warning before the ACC MCP child started; native delivery branches are unobserved and false. |
+| Gemini CLI | Only 0.37.0 has package-shipped next-turn certification. Write and shell tools depend on approval mode; other versions and platforms retain inbox access but no effective delivery capability. |
+| Grok | Documentation-shaped payloads do not count as real captures. UserPromptSubmit context was observed discarded, and no deny was captured stopping a real write; all capabilities remain false. |
+| Kimi Code | 0.36.1 has next-turn and guard evidence, plus a 60-second heartbeat. Prompt-mode `SessionEnd` never fired, and its next-turn path does not interrupt an active turn. |
+| Generic MCP | Tool polling is not next-turn injection, live push, or a native reply route. It has no write guard or client-lifecycle evidence. |
+
+`certification.json` beside each adapter is machine-readable. `COMPATIBILITY.md` records the
+captured client behavior, including what could not be observed.
+
+## Current reachability
+
+Certification is static evidence; reachability is runtime state. A live-capable adapter
+would publish a generation-bound binding with `availableModes`, `clientVersion`,
+`livePolicy`, and `leaseUntil`. `acc status --json` reports these as `deliveryBindings`
+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.
+
+Current shipped reality: no adapter publishes a native live binding, and no adapter has
+passing `livePush` certification. Codex and Claude Code are next-turn or inbox only;
+Gemini CLI and Kimi Code are next-turn only at their exact captured versions; Grok and MCP
+poll inbox.
+
+## Recipient policy
+
+Native live delivery may start a model turn and spend tokens, so the recipient owns the
+policy:
+
+| Policy | Meaning |
+|---|---|
+| `off` | normal next-turn and inbox only |
+| `actionable` | questions, requests, and addressed handoffs may use live push |
+| `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.
+
+## Fallback
+
+| Participant | Durable behavior when acceleration is unavailable |
+|---|---|
+| exact-certified Codex 0.147.0 | complete peer body at the next normal turn; `acc inbox` remains recoverable |
+| exact-certified Claude Code 2.1.233 | complete peer body at the next normal prompt; `acc inbox` remains recoverable |
+| exact-certified Gemini CLI 0.37.0 | complete peer body at the next normal turn; `acc inbox` remains recoverable |
+| exact-certified Kimi Code 0.36.1 | complete peer body at the next normal turn; `acc inbox` remains recoverable |
+| Grok, generic MCP, unknown version, other platform | explicit `acc inbox` polling |
+
+A send that committed durably succeeds even if a transport later fails. The delivery array
+names the queued fallback and safe error code. There is no terminal failed receipt.
+
+## Guard limitations
+
+A guarded claim stops only paths the client exposes to a captured pre-tool hook. Codex's
+write guard depends on the model offering `apply_patch`; recognised shell writes can be
+matched, but a language runtime opening a file cannot. Gemini's edit tools depend on
+approval mode. Grok has no certified guard. One live advisory session lowers workspace
+protection to advisory because that is the strongest honest room-wide statement.
+
+Hook response shapes are vendor-specific and not portable. An ignored deny response often
+fails silently, which is why each true cell above needs its own fixture rather than a
+shared documentation example.
+
+Next: [Protocol](PROTOCOL.md) · [MCP](MCP.md) ·
+[Adapter authoring](ADAPTER_AUTHORING.md)

package/docs/CLI.md

@@ -0,0 +1,157 @@
+# 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.
+
+<!-- test:command -->
+```bash
+acc help
+acc version
+```
+
+## Communication commands
+
+| Command | Required | Optional |
+|---|---|---|
+| `acc status` | — | `--participant`, `--all` |
+| `acc sync` | — | `--session`, `--cursor`, `--limit`, `--scope delta|full` |
+| `acc work` | `--summary` unless `--clear` | `--session`, `--generation`, `--mode`, `--state`, repeated `--hint`, `--clear` |
+| `acc claim` | `--resource` | `--session`, `--generation`, `--mode`, `--enforcement`, `--reason`, `--lease` |
+| `acc release` | `--claim` or `--resource` | `--session`, `--generation`, `--authority`, `--reason` |
+| `acc message` | `--subject`, `--body` | repeated `--to`, `--type`, `--obligation`, `--client-message-id`, owner flags |
+| `acc request` | `--to`, `--title` | `--detail`, `--client-message-id`, owner flags |
+| `acc inbox` | — | `--message`, owner flags |
+| `acc reply` | `--message`, `--body` | `--subject`, `--client-message-id`, owner flags |
+| `acc ack` | `--message` | owner flags |
+| `acc finish` | `--goal` | `--status`, `--to`, repeated `--completed`, `--remaining`, `--blocker`, `--client-message-id`, owner flags |
+
+Owner flags are `--session` and `--generation`. A normal hooked session omits them because
+the CLI resolves its current binding. Scripts and adapters may pass them explicitly.
+
+### Presence and intent
+
+```bash
+acc status
+acc work --summary "checking receipt transitions" --mode review \
+  --hint 'file:packages/core/src/receipts.mjs'
+acc work --clear
+```
+
+`status` returns participants, current intent, claims, protection, attention, and current
+delivery bindings. `sync` is a bounded event read; use `--scope full` only for an explicit
+whole-workspace forensic question. Neither is the recovery path for one message.
+
+### Claims
+
+```bash
+acc claim --resource 'file:packages/core/**' --reason "editing receipt logic"
+acc release --resource 'file:packages/core/**'
+```
+
+File resources use repository-relative paths. A directory claim ends in `/**`. Exit code
+`5` means a conflict. `--authority` is the explicit force-release path and should carry a
+reason; ordinary sessions release only their own claims.
+
+### Messages and requests
+
+```bash
+acc message --to models --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" \
+  --detail "Check CLI and MCP results; reply with defects only."
+```
+
+`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
+`reply`, and `handoff` only by `finish`.
+
+No `--to` creates a room message where the kind allows it. Addressed messages create a
+separate receipt for each recipient. `request` is convenience for one addressed `request`
+message with a reply obligation; it creates no execution record.
+
+The JSON result for `message`, `request`, `reply`, and `finish` is:
+
+```json
+{
+  "message": { "messageId": "message_x", "clientMessageId": "client_x" },
+  "delivery": [
+    { "recipientParticipantId": "models", "outcome": "queued",
+      "transport": "durable", "errorCode": "delivery_disabled" }
+  ]
+}
+```
+
+Human output starts with `recorded message_x`. A transport failure after that commit does
+not change the command exit code. Reuse an explicit `--client-message-id` after an
+uncertain result to recover the same logical message.
+
+### Inbox, reply, and acknowledgement
+
+```bash
+acc inbox
+acc inbox --message message_x
+acc reply --message message_x --body "Yes. Use offered."
+acc ack --message message_y
+```
+
+Inbox returns only unresolved messages addressed to this participant. Reading advances
+that participant's receipt to `retrieved`. Reply creates an `answer` in the same thread and
+acknowledges the original atomically. `ack` acknowledges without writing an answer and has
+no state override.
+
+### Handoff
+
+```bash
+acc finish --goal "document receipt semantics" --status partial \
+  --completed "protocol updated" --remaining "acceptance proof" \
+  --blocker "packed test not run" --to models
+```
+
+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
+
+| Command | Flags |
+|---|---|
+| `acc install` | `--adapter`, `--home`, `--delivery off|actionable|all`, `--dry-run`, `--downgrade` |
+| `acc uninstall` | `--adapter`, `--home`, `--dry-run` |
+| `acc doctor` | `--home`, `--repair` |
+| `acc config init` | `--yes`, `--force` |
+| `acc config validate` | — |
+| `acc update` | `--apply` |
+| `acc help` | — |
+| `acc version` | — |
+
+`--delivery` is a recipient policy request, not a capability switch. The default is
+`off`. If the detected exact client version lacks certified live push, installation keeps
+the effective policy off and prints the adapter's durable fallback.
+
+Only `update` touches the network. `ACC_NO_UPDATE_CHECK=1` disables update checks. Hooks
+never perform them.
+
+## Adapter lifecycle commands
+
+`acc attach --participant <id>`, `acc heartbeat --session <id> --generation <token>`, and
+`acc detach --session <id> --generation <token>` are public executable boundaries used by
+adapters. Installed skills do not teach models to call them. They maintain ACC presence;
+they do not start, keep alive, or close the external client process.
+
+## Exit codes
+
+| Code | Meaning |
+|---|---|
+| `0` | success |
+| `2` | usage |
+| `3` | timeout |
+| `4` | data or incompatible state |
+| `5` | claim or generation conflict |
+| `6` | attention |
+
+Next: [Protocol](PROTOCOL.md) · [MCP](MCP.md) · [Configuration](CONFIGURATION.md)