agents-can-communicate 0.1.18 → 0.3.0

package/docs/CAPABILITIES.md

@@ -1,219 +1,122 @@
 # 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.57.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 `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.
+
+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. A 0.152.1 capture proved the App Server queue transport, but the release capture then measured that native delivery there requires `codex --remote unix://`, and in that mode the session runs inside the daemon: both the hook payload and the App Server's own thread record report the daemon's directory instead of the session's, so ACC cannot tell which workspace the session is in. Nothing ACC can reach carries the real one, and placing a session in the wrong workspace is worse than not placing it, so `delivery.livePush` is **not** claimed - the probe and the handshake both refuse with `workspace_identity_unavailable`. `replyRoute` stays false. |
+| Claude Code | 2.1.233 next-turn delivery waits for the next user prompt. A 2.1.258 Channel capture proved idle offer, busy queue-after-turn, explicit reply, duplicate suppression, and durable fallback, so `delivery.livePush` and `delivery.replyRoute` are live capabilities behind the native contract (experimental, off until opted in; Claude's development-channel warning is vendor-owned and visible). |
+| Gemini CLI | Only 0.57.0 has package-shipped next-turn certification. Its TUI has no captured external wake or queue interface and `--acp` changes launch ownership, so native delivery is fallback-only; live push and reply routing remain false. |
+| Grok | Documentation-shaped payloads do not count as real captures. The public leader surface exposed no proven addressed injection into an ordinary TUI session, so native delivery is `awaiting_compatibility_capture`; all capabilities remain false. |
+| Kimi Code | 0.36.1 has next-turn and guard evidence, plus a 60-second heartbeat. Its server/queue APIs do not prove a transparent binding to an independently opened session, so native delivery is fallback-only. |
+| 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.
+
+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
+let the lease run out under an idle session, which is exactly when live delivery is worth
+having. Giving a binding up is a separate, final fact rather than an expired lease, so a
+channel that has not yet noticed cannot extend something the session already retired.
+
+Current shipped reality: Claude Code on darwin-arm64 has a passing experimental `livePush`
+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.
+
+## 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, answers, decisions, and addressed handoffs may use live push; notes wait for the next turn |
+| `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.57.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,164 @@
+# 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 off|actionable|all` is a per-client recipient policy request, not a capability
+switch, and the default is `off`. `--adapter` is repeatable to name several clients. An
+explicit `--delivery` applies uniformly and never prompts; omitting it on an interactive
+terminal asks one default-No question per eligible client, and on a non-interactive run or a
+`--dry-run` it keeps fresh clients off. A recorded opt-in is kept on upgrade. If the detected
+client cannot receive native delivery - unsupported, below the captured minimum, a
+prerelease, known-bad, a wrong platform, or an unsupported shell - installation keeps the
+effective policy off and prints the reason. A live install writes an owned zsh PATH block and
+a per-command shim that keeps your command name and `exec`s the real client; `ACC_BYPASS=1`
+runs the unmodified client, and ACC is never the parent of the session after that `exec`.
+
+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)