agents-can-communicate 0.3.1 → 0.4.1

package/docs/ADAPTER_AUTHORING.md

@@ -28,6 +28,7 @@ export function createExampleAdapter() {
 
     detect, install, uninstall, doctor,
     planInstall,                      // what install would write
+    preflightUninstall,               // optional read-only removal validation
     normalizeHook,                    // client payload -> normalised event
     renderContext,                    // SyncResult -> text
     renderContextResult,              // text + ids of complete rendered groups
@@ -36,6 +37,21 @@ export function createExampleAdapter() {
 }
 ```
 
+`preflightUninstall(context)` is optional and read-only. Throw to refuse unsafe
+removal before the installer deactivates native integration or deletes recorded
+artifacts. `uninstall` should retain its own validation for direct adapter callers;
+recorded artifact fingerprint checks still determine the `keep` paths it receives.
+
+`injectToolOwnerOutcome({ owner, tool })` is an optional identity-only hook callback.
+The runner calls it after an allowed `beforeTool` handler only when that hook's
+binding still names an open session with the same generation in this workspace.
+Return `null` for an unsupported tool, or `{ stdout, stderr? }` using the client's
+documented context envelope. The runner preserves the guard decision and the
+owner line's byte budget. The callback receives no peer bodies or raw tool input;
+it cannot create a session or advance receipts. Grok uses it to supply CLI owner
+arguments after a terminal result. This does not certify general context or peer
+delivery, and a tool such as `finish` can close the owner before the line arrives.
+
 `renderContextResult` is required wherever an adapter renders peer messages. It returns
 `{ text, offeredMessageIds, includedAttentionIds }`, and the [receipt
 lifecycle](PROTOCOL.md#receipt-lifecycle) advances only from those ids — never by searching
@@ -46,6 +62,12 @@ convenience API for adapters that don't need it. An adapter with only the older
 instead: repeating an untracked body every turn would be quieter in code and dishonest about
 what was actually delivered.
 
+The hook also supplies `reminderMessageIds`, derived from this participant's `offered` or
+`retrieved` receipts with unresolved obligations. The standard projector combines those
+reply/acknowledgement attention items into counts after new bodies. A missing body alone
+is not evidence for compaction. Counts add no ids to `offeredMessageIds` or
+`includedAttentionIds`; complete inbox and status results remain available.
+
 `client.command` does double duty. `detect.mjs` uses it as the version-probe binary, and
 presence liveness separately walks the hook's process ancestry for the first ancestor whose
 executable basename matches it, to learn the client's own pid. Declare the binary the client
@@ -119,9 +141,30 @@ The rules `defineAdapter` enforces, and the ones the runtime applies:
   when numerically newer. `knownBad` names exact versions or inclusive intervals.
 - Exact-version certification still governs every non-native capability;
   `effectiveCapabilities()` is unchanged. The native rule is used for live delivery alone.
-- The three native methods return closed facts (`validateNativeActivationPlan()` closes the
+- Native methods return closed facts (`validateNativeActivationPlan()` closes the
   activation plan) and never put vendor data - endpoints, sockets, raw errors - into core.
 
+`nativeDelivery.policySource` defaults to the session environment. An adapter may
+declare `"installation-record"` when hooks and senders must read current recorded
+recipient consent independently of the vendor process environment. Installation
+records the requested policy even when current activation is unavailable. An absent
+or invalid record means `off`; a previously published binding cannot override it.
+
+The optional `refreshNativeSession()` method may revalidate an expired lease before
+an offer. It returns the same closed handshake shape as `bindNativeSession()` and
+must preserve the exact endpoint and protocol identity. The router rechecks the
+current session, generation, retirement, uniqueness and policy before publishing
+the refreshed lease. Refresh is not a heartbeat and cannot extend presence beyond
+its own expiry. Optional `retireNativeSession()` cleans adapter-owned endpoint state
+after confirmed core retirement; it must remain bounded and fail open for hooks.
+
+A package-shipped passing Codex installed-hook capture additionally references its
+complete real product matrix through the selected provenance record's
+`productEvidence: { fixture, sha256 }`. Package verification checks the actual file,
+raw digest and client/version/platform/package identity. A transport-only capture
+cannot certify the installed product route. `historicalFixtures` may retain hashed
+earlier failures without duplicating a certification tuple.
+
 ## Choose the integration depth
 
 | Tier | You register | You get | You do not get |
@@ -131,12 +174,13 @@ The rules `defineAdapter` enforces, and the ones the runtime applies:
 | 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. 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.
+Installed hook wiring may reach tier 2, but each effective hook capability still
+requires exact client/version/platform evidence. Tier 3 has separate native
+contracts: Claude Code Channel from 2.1.258 and Codex LocalDaemon from 0.152.1 on
+macOS arm64, with current probes and exact session handshakes. Codex's earlier
+remote-wrapper failure remains historical evidence. Ordinary launch now preserves
+workspace identity; the full installed product matrix, including negative controls
+and fallback, backs its native claim.
 
 ## Normalize hook input
 
@@ -163,7 +207,7 @@ Measure them. Every client differs, and a wrong shape fails **silently**:
 | Codex | exit 2 + stderr | plain stdout (`developer` message) |
 | Claude Code | `hookSpecificOutput.permissionDecision` | same envelope |
 | Gemini CLI | `{"decision":"block"}` | `hookSpecificOutput` envelope |
-| Grok | `{"decision":"deny","reason"}` (documented; deny not yet captured) | UserPromptSubmit stdout discarded on 1.0.13 |
+| Grok | `{"decision":"deny","reason"}` (documented; deny not yet captured) | UserPromptSubmit stdout discarded; own identity only via PreToolUse after a terminal result, observed on 1.0.24 |
 | Kimi Code | `hookSpecificOutput.permissionDecision` | plain stdout |
 
 `denyOutcome(reason)` returns `{ stdout, stderr, exitCode }`, so the runtime never has to

package/docs/ARCHITECTURE.md

@@ -81,12 +81,12 @@ a third exact-version certification check. A binding says what that current gene
 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.
+Claude Code Channel has installed-client evidence on 2.1.258 and 2.1.260; Codex
+LocalDaemon has it on 0.152.1 and 0.153.4. Both use a captured platform minimum,
+current probe and exact session handshake. Codex preserves the ordinary client
+launch and verifies its registered thread and workspace; ACC owns no vendor daemon
+lifecycle. Gemini CLI and Kimi Code have exact-version next-turn evidence only;
+Grok and generic MCP use inbox polling.
 
 ## Storage and workspace identity
 
@@ -101,17 +101,31 @@ 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
-alone” an architectural behavior, not a UI preference.
+appears or the first claim, message, or handoff is committed. Solo presence therefore
+does not require durable workspace history. Native turn hooks still supply the session's
+own CLI arguments, so a peer joining later in the same turn does not require reattachment.
+Grok instead receives that own header after a terminal tool result through PreToolUse;
+the first public status call makes it available for subsequent owned commands.
+Without relevant coordination context, that identity header is the only projected content.
 
 ## 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
+Public inbox discovery uses core `listInbox`: bounded, read-only message summaries
+addressed to the current participant. Exact body reads use `readInbox` and advance only
+that participant's receipt to `retrieved`; the embedded core API still supports bulk
+retrieval. History sync reads message records without receipt changes, using the same
+summary pager or one exact id. 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:
+Decision lifecycle is derived from immutable message links, without a new record kind
+or mutable decision store. Read copies carry bounded status; raw forensic snapshots stay
+unchanged. Non-head decisions leave pending inbox, bulk delivery, and attention while
+exact reads retain them. Replacement/withdrawal records inherit recipients before commit,
+so offline readers receive the change without a forged acknowledgement. See
+[the protocol contract](PROTOCOL.md#decision-lifecycle).
+
+Attention is computed from six explicit rules for current obligations:
 
 | Priority | Kind | Observable trigger |
 |---|---|---|
@@ -129,6 +143,14 @@ Adapters project peer bodies in an attributed untrusted frame. If a complete bod
 fit, the projection keeps the message id and points to `acc inbox --message <id>` instead
 of silently truncating it.
 
+For this participant's unresolved messages already `offered` or `retrieved`, the standard
+projector combines reply and acknowledgement reminders into a compact count after new
+message bodies. Queued obligations and claim conflicts remain individual attention items.
+All pending headers stay discoverable through `acc inbox` pages; owned `acc status` retains
+its complete attention list. Full bodies require an exact inbox read; projection
+does not acknowledge or delete records. Explicit decision links, rather than the
+projector or message age, retire old decision obligations.
+
 ## Hooks fail open
 
 Hook execution is bounded. If coordination state cannot be read or a decision cannot be
@@ -137,3 +159,34 @@ 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)
+
+## Managed runtime activation
+
+The CLI owns installation generations under `<dataHome>/acc/runtime`, outside workspaces.
+All five launch paths select a generation and publish an actual-process lease under one
+admission mutex before loading workspace-capable code. Immutable launcher modules and
+runtime directories preserve in-progress imports. Leases survive `main()` returning and
+are removed only after confirmed process death. Parsed help, version, and update recovery
+remain available when workspace admission is unavailable.
+
+An independent worker downloads npm packages with lifecycle scripts disabled, checks exact
+stable package identity and the discovered integrity, and health-checks the staged runtime.
+Installer detection and planning happen before exclusive admission. The worker then checks
+ACC process leases and native binding PIDs, records `activating`, applies every integration,
+and only publishes the new active pointer after all applications succeed. Partial refresh
+remains fenced and repairs forward, with the old active pointer retained but normal
+workspace admission unavailable until recovery completes. Native bindings cease holding
+after observed SessionEnd cleanup or confirmed process death; the vendor daemon may remain
+running. Unknown PIDs remain holds until lifecycle cleanup. Presence TTL, `acc finish`,
+and delivery off alone do not prove native lifecycle end. ACC never manages the daemon.
+
+Lock ownership never expires by age. Retained nonempty tombstones prevent delayed observers
+from reclaiming a successor. Under an acquired lock, maintenance removes historical
+bookkeeping only when no live or unknown contender could still reference it; a stopped
+contender postpones cleanup. Admission also removes confirmed-dead process leases. None of
+this metadata is agent conversation history or injected context.
+
+The first upgrade from an unmanaged binary still requires a restart. ACC cannot fence old
+direct binaries or external applications importing core. Native trust and client-side cache
+activation remain vendor responsibilities; refreshed files do not establish observed
+capabilities.

package/docs/CAPABILITIES.md

@@ -3,8 +3,8 @@
 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.
+every participant, supported exact versions may add next-turn delivery, and the
+experimental Codex LocalDaemon and Claude Code Channel paths can deliver while a session is idle.
 
 Capability honesty separates four questions that are easy to collapse:
 
@@ -16,8 +16,8 @@ Capability honesty separates four questions that are easy to collapse:
    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.
+A source method or vendor documentation is not certification. Uncaptured hook versions and
+unsupported platforms degrade to false. Native minimum-based eligibility is separate. 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
@@ -42,24 +42,23 @@ Passing evidence currently ships for these exact versions on `darwin-arm64`:
 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 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 native rows remain `no` for the older exact hook versions in this matrix.
+Separate installed-client captures establish Codex `livePush` on 0.152.1 and
+0.153.4, and Claude Code `livePush` plus `replyRoute` on 2.1.258 and 2.1.260.
+Native eligibility uses the captured platform minimum, a current feature probe,
+and an exact per-session handshake. It is experimental and requires recipient
+opt-in. Codex replies through `acc reply`; its native `replyRoute` remains false.
 
 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. |
+| Codex | Exact 0.147.0 next-turn context requires plugin trust. The observed stock 0.153.4 upgrade from ACC 0.3.1 to 0.4 required fresh review of five modified hook definitions; a subsequent restart retained all five active (activation evidence, not new event certification). LocalDaemon native delivery was captured through the installed package on 0.152.1 and 0.153.4, darwin-arm64; minimum 0.152.1, recorded opt-in, current feature probe and exact thread/cwd/process/version/protocol checks are required. Ordinary launch preserves the receiver workspace without ACC arguments or daemon ownership. Embedded or unreachable sessions keep their inbox. Native `replyRoute` remains 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. |
+| Grok | The Grok 1.0.24 installed-client check observed own CLI arguments after a terminal result, followed by owned work, message, and finish calls. This identity-only path does not certify peer-context injection. 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. |
+| Generic MCP | As a receiver, tool polling is not next-turn injection, live push, or a native reply route. It has no write guard or client-lifecycle evidence. Outgoing messages may use an eligible recipient's opted-in native adapter. |
 
 `certification.json` beside each adapter is machine-readable. `COMPATIBILITY.md` records the
 captured client behavior, including what could not be observed.
@@ -71,25 +70,28 @@ 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, and an adapter refusal each keep delivery on the
-durable fallback. Busy behavior belongs to the transport: Claude's Channel can accept a
+The router requires exactly one current eligible generation. No binding, several live
+sessions for one participant, and an adapter refusal keep delivery on the durable
+fallback. An expired lease may be revalidated by an adapter's optional refresh method;
+failure leaves the message queued. 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
-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.
+An endpoint may renew its lease, or an adapter may revalidate that exact endpoint on
+demand without a client heartbeat. Retirement is final: neither route may revive a
+retired binding, a closed session or an old generation. Delivery lease refresh does
+not renew participant presence.
 
-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. On Linux, the shipped captures above do not establish next-turn or
-live delivery, so the honest expectation is the durable inbox.
+On darwin-arm64, Codex LocalDaemon and Claude Code Channel have captured
+experimental live delivery. Other adapters retain their separately certified
+next-turn paths or inbox polling. Linux and other uncaptured platforms retain
+the durable inbox; these captures establish no new hook capabilities there.
+
+Codex's 120-second delivery lease can refresh on demand for the same live endpoint;
+it does not extend the 24-hour participant presence limit. A TUI exit can leave its
+daemon thread loaded and able to execute opted-in messages. Actual thread teardown,
+including explicit archive, runs `SessionEnd` and retires the binding. Turning ACC
+delivery off prevents new offers even while that thread remains loaded.
 
 ## Recipient policy
 
@@ -102,14 +104,16 @@ policy:
 | `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. 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.
+The default is `off`. `acc install --delivery actionable|all` records recipient consent.
+Current activation remains off when the platform, captured minimum or feature probe
+does not qualify; that temporary failure does not erase the requested policy. Each
+session must pass its own generation-bound handshake. An adapter using the installation
+record rereads consent at hooks and before offers, so a long-running vendor process
+cannot retain permission through an old environment value or binding snapshot.
+
+For an adapter using recorded consent, `--delivery off` and uninstall prevent new
+native offers. They cannot withdraw a submission already accepted by the vendor queue. Ordinary hook capabilities still
+require exact-version certification. Room messages are never live-push candidates.
 
 ## Fallback
 

package/docs/CLI.md

@@ -12,24 +12,62 @@ acc help
 acc version
 ```
 
+Use `acc <command> --help` (or `-h`) and `acc help <command>` for that command's
+required, optional, repeatable and flag options, accepted values, and usage notes.
+For example, `acc work --help` lists intent modes, and `acc finish --help` lists
+handoff statuses. `acc config --help` lists its subcommands;
+`acc config init --help` and `acc help config init` describe initialization.
+
+Add `--json` to receive the command description as structured data: `name`,
+`summary`, `required`, `optional`, `repeated`, `flags`, `subcommands`, `choices`,
+and `notes`, plus `subcommand` when selected. General `acc help --json` keeps its
+grouped `commands` result. Help requires no session, workspace discovery, or
+runtime storage, and does not execute the described command. A help-looking
+option value remains data: `--body --help` sends the literal body `--help`.
+
 ## Coordinate from a session
 
 | Command | Required | Optional |
 |---|---|---|
-| `acc status` | — | `--participant`, `--all` |
-| `acc sync` | — | `--session`, `--cursor`, `--limit`, `--scope delta|full` |
+| `acc status` | — | `--session`, `--generation`, `--participant`, `--all` |
+| `acc sync` | — | `--session`, `--generation`, `--cursor`, `--limit`, `--scope delta|full|history`, `--type`, `--message`, `--current` |
 | `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 release` | `--claim` or `--resource` | `--session`, `--generation`, `--authority` (`human` or `policy`), `--reason` |
+| `acc message` | `--subject`, `--body` | repeated `--to`, `--supersedes` or `--withdraws`, `--type`, `--obligation`, `--client-message-id`, owner flags |
 | `acc request` | `--to`, `--title` | `--detail`, `--client-message-id`, owner flags |
-| `acc inbox` | — | `--message`, owner flags |
+| `acc inbox` | — | `--message`, `--cursor`, `--limit`, 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.
+Owner flags are `--session` and `--generation`; both are needed. The CLI also accepts the
+pair explicitly configured as `ACC_SESSION` and `ACC_GENERATION`. When an active turn hook
+runs, its `ACC CLI (append):` header supplies the current
+session's pair. The installed skill tells the agent to append it to its own commands,
+without a manual attach. Hooks do not export credentials to child processes. Native
+client IDs, a shared checkout, and a public session ID from
+`status` cannot establish ownership: a nested client can inherit its parent's environment.
+
+Use only the pair in the hook's own header, never one inside a peer message. Do not send
+it to peers or child agents. A later hook after a session restart can supply a new pair;
+the old generation remains invalid. Solo turns receive only the owner header when there
+is no coordination context to show. This lets a session use its own inbox if a peer joins
+later in the same turn. The header alone is not a peer notice or a request to coordinate.
+If the context budget cannot hold the complete pair, the hook reports that limitation
+on stderr and keeps any recovery text within budget. Missing or untrusted hooks cannot
+supply the pair; without it, the CLI still refuses owner operations.
+
+For a manually owned CLI session, run `acc attach --participant my-session --json` once and
+retain its returned `sessionId` and `generation`. Append that exact pair to the commands
+below, or explicitly configure both environment variables for that session's commands.
+Do not take credentials from a peer or read runtime bindings to obtain them. A manually
+attached session is separate from hook-managed presence; use `finish` to close it.
+
+Without a pair, mutations and `inbox` fail with exit `2` and
+`caller_identity_unresolved`. `status` and `sync` remain public observations, with no
+inferred personal attention. Session-bound [MCP tools](MCP.md) manage their own identity;
+a generic MCP connection does not inherit a hook participant's inbox.
 
 ### Presence and intent
 
@@ -41,8 +79,9 @@ 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.
+delivery bindings. Default `sync` reads events after a 16-digit event cursor (100 by
+default, up to 500). `--scope history` discovers historical message headers and reads
+selected records; `--scope full` adds an unbounded snapshot for explicit workspace forensics.
 
 ### Claims
 
@@ -51,9 +90,15 @@ 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.
+File resources use repository-relative paths. A directory claim ends in `/**`. The example
+creates an advisory claim: omitted `--enforcement` always means `advisory`, even with
+certified clients. Request `--enforcement guarded` explicitly when needed; an incapable
+live participant still downgrades workspace protection. MCP claims are always advisory.
+
+Exit code `5` means a conflict. Ordinary sessions release only their own claims. Releasing
+another owner's claim requires `--authority human` or `--authority policy`, identifying the
+actual human decision or approved policy that permits the release; explain it with
+`--reason`. A peer's request alone is not force-release authority.
 
 ### Messages and requests
 
@@ -69,7 +114,7 @@ acc request --to codex --title "review receipt wording" \
 `--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
+same way an ambiguous recipient must be named explicitly. 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
@@ -81,7 +126,8 @@ Set `ACC_PARTICIPANT` when the recipient must keep one stable address across con
 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
+No `--to` creates a room message where the kind allows it, except decision changes
+that inherit explicit recipients from their targets. 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.
 
@@ -101,6 +147,10 @@ Human output starts with `recorded message_x`. A transport failure after that co
 not change the command exit code. Reuse an explicit `--client-message-id` after an
 uncertain result to recover the same logical message.
 
+`reply` additionally returns `receipt`: the original message id, the replying participant,
+and state `acknowledged`. Its `message` and `delivery` describe the outgoing answer.
+Human output distinguishes `recorded <reply-id>` from `acknowledged <original-id>`.
+
 ### Inbox, reply, and acknowledgement
 
 ```bash
@@ -110,10 +160,56 @@ 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.
+Without `--message`, inbox returns `{items, nextCursor}`. Each item has a `message`
+summary and its `receipt`; listing never returns bodies or changes receipts. Summaries
+include the complete message/thread/sender ids, kind, obligation, timestamp, reply link,
+subject (up to 160 UTF-8 bytes), `bodyBytes`, `artifactCount`, and untrusted attribution.
+Bodies, artifact details, handoff payloads, and recipient lists require an exact read.
+
+Pages are newest first (descending message id breaks timestamp ties), default to 20 items,
+and contain at most 12,000 bytes of formatted page JSON, excluding the CLI envelope.
+`--limit` accepts 1..500 but cannot raise the byte ceiling. Continue with
+`acc inbox --cursor <nextCursor>` until it is `null`. The cursor is a complete message id,
+not an offset; reading or acknowledging it does not shift the next page. These are live
+pages: omit the cursor to see new arrivals. An unknown or foreign cursor is an error.
+
+`--message <id>` returns the existing one-item array with the complete message/receipt
+pair, advancing that participant's receipt to `retrieved` when needed. It cannot be
+combined with `--cursor` or `--limit`. An exact id also reads an acknowledged message,
+preserving its receipt, timestamp, and event history.
+Use the original message id to inspect acknowledgement; the outgoing reply belongs to
+its recipient's inbox. Resolved messages stay out of the ordinary inbox.
+
+Reply creates an `answer` in the same thread and acknowledges the original atomically.
+`ack` acknowledges without writing an answer and has no state override.
+
+### Historical recovery
+
+```bash
+acc sync --scope history --type handoff --json
+acc sync --scope history --type handoff --cursor message_x --json
+acc sync --scope history --message message_y --json
+```
+
+History returns `{scope: "history", view: "summary", items, nextCursor}` with the same
+summary fields, ordering, page limits, and message-id cursors as inbox. `--type` accepts
+any message kind and filters before pagination; keep the same filter between pages.
+This public workspace observation includes records from before your session joined.
+Exact history reads return `view: "message"` and one complete message in `items`,
+without changing any receipt. Do not combine `--message` with type, cursor, or limit;
+message and type are valid only in history scope. Decision reads also include `decisionStatus`. Use
+`acc sync --scope history --type decision --current --json` for terminal decisions
+and withdrawals; keep these filters when paging. Exact reads cannot use `--current`.
+`current` means no explicit successor, not truth or consensus.
+
+To change a decision, send another `acc message --type decision` with repeated
+`--supersedes <message-id>` or `--withdraws <message-id>` (1..16 unique IDs; exclusive).
+Use subject/body for the new position or withdrawal reason. Changes inherit the target
+recipients and authors, including offline participants; `--to` adds recipients.
+Any owned participant can record an attributed change. Multiple successor branches
+remain conflicted until a new change explicitly references all current alternatives.
+Old records leave ordinary inbox/automatic attention without any receipt change;
+exact inbox and history still recover them. See [decision lifecycle](PROTOCOL.md#decision-lifecycle).
 
 ### Handoff
 
@@ -136,7 +232,7 @@ external AI client. An addressed handoff requires acknowledgement; a room handof
 | `acc doctor` | `--home`, `--repair` |
 | `acc config init` | `--yes`, `--force` |
 | `acc config validate` | — |
-| `acc update` | `--apply` |
+| `acc update` | `--check`, `--auto on\|off`, `--pin VERSION\|none`, `--apply` (alias) |
 | `acc help` | — |
 | `acc version` | — |
 
@@ -147,12 +243,36 @@ terminal asks one default-No question per eligible client, and on a non-interact
 `--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.
+effective policy off and prints the reason. Claude Code shell activation writes an owned
+zsh PATH block and a shim that `exec`s the real client; `ACC_BYPASS=1` bypasses that
+activation. Codex LocalDaemon delivery uses recorded installation consent without changing
+ordinary launch arguments. Its opt-in remains active when shim variables are absent or
+bypassed; `acc install --adapter codex --delivery off` disables new native offers. ACC never
+starts or stops the vendor daemon. See [delivery consent](CONFIGURATION.md#keep-delivery-consent-user-owned).
+
+An initial `acc install` enables automatic updates. Reinstalling preserves an explicit
+`acc update --auto off` choice. A full uninstall pauses updates; reinstalling restores
+the remembered setting. A background worker checks stable releases
+at most once a day, downloads and verifies a separate runtime, then refreshes installed
+integrations and skills after ACC process leases and native binding holds clear. ACC leases
+require confirmed process exit; a native binding can clear on observed SessionEnd even
+while its vendor daemon remains alive, or on confirmed process death. Unknown PIDs remain
+holds. `finish`, presence TTL, and delivery off are not observed native end. Hooks do not
+wait for network work. `ACC_NO_UPDATE_CHECK=1` disables update networking and background
+scheduling.
+
+`acc update` requests the update immediately; it reports a pending update when a running or
+unidentified client prevents activation. `--check` only checks and cannot be combined with
+settings changes. `--auto off` disables background updates, and `--auto on` enables them.
+`--pin 0.4.0` holds an exact stable version; `--pin none` follows stable releases. A pin
+cannot downgrade the active runtime. The old `--apply` flag remains accepted.
+
+Failed downloads keep the working runtime. A failed integration refresh exits with code
+`4`, names the failed adapter and configuration error, and keeps workspace admission closed.
+Fix the reported configuration problem, then run `acc update` to finish it. `acc doctor`
+reports the update policy and pending notice. Native clients may still require hook trust
+or activation review. See [Upgrading](UPGRADING.md) for the initial 0.3.1 transition and
+recovery details.
 
 ## Integrate a client lifecycle