agents-can-communicate 0.3.1 → 0.4.0

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. |
 | 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,34 @@ 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).
+
+A normal `acc install` enables automatic updates. 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
 

package/docs/CONCEPTS.md

@@ -79,6 +79,12 @@ Message kinds describe the conversation:
 An **obligation** is the communication response owed by a recipient. A request is not an
 order, and a reply is not proof that work is complete.
 
+A decision can explicitly replace or withdraw earlier decisions. The old records stay
+attributed and recoverable, while current reads and reminders follow the recorded links.
+Any peer may record a change; competing branches remain visible until explicitly joined.
+A current decision is a recorded position, not agreement or authority. See
+[decision lifecycle](PROTOCOL.md#decision-lifecycle).
+
 ## Threads keep the exchange together
 
 The first message is a **thread** root. A reply names the original message and stays in that
@@ -100,19 +106,20 @@ queued -> offered -> retrieved -> acknowledged
 
 - `queued`: the durable message and receipt committed;
 - `offered`: ACC or a certified client accepted the delivery bytes, not proof of reading;
-- `retrieved`: the participant fetched the message, not proof of model attention;
+- `retrieved`: the participant fetched the body through its inbox, not proof of model attention;
 - `acknowledged`: the participant acknowledged it or replied, not proof of task completion.
 
+Listing inbox headers and observing workspace history do not change receipts.
 There is no `seen` receipt. A failed delivery attempt leaves the message queued and
 recoverable rather than creating a terminal failure state.
 
 ## Durable first, faster delivery second
 
-The durable inbox is universal. Exact-version certified adapters may also offer messages at
-the next normal turn. That does not wake an idle client. Claude Code has the only shipped
-experimental live path, off by default and subject to recipient policy and current
-reachability; Codex live delivery is withdrawn. [Capabilities](CAPABILITIES.md) is the
-current adapter matrix.
+The durable inbox is universal. Exact-version certified adapters may also offer
+messages at the next normal turn. Codex LocalDaemon and Claude Code Channel add
+experimental live delivery, off by default and subject to recipient policy and
+current reachability. Codex can retain an eligible daemon thread after its terminal
+exits. [Capabilities](CAPABILITIES.md) gives the current limits.
 
 ## Handoffs preserve explicit context
 

package/docs/CONFIGURATION.md

@@ -6,7 +6,7 @@ as the same operating-system user on the same machine and resolve that same loca
 workspace.
 
 Create `acc.workspace.json` only for stable workspace identity, roots, or shared
-claim/context policy. It is optional project configuration that `acc config init` may write
+context budget. It is optional project configuration that `acc config init` may write
 at your request; runtime state remains in platform app data outside the repository. The
 file never defines agents, messages, execution state, or delivery endpoints. Project map:
 [README](index.md). Terms used below: [Glossary](GLOSSARY.md).
@@ -18,11 +18,8 @@ file never defines agents, messages, execution state, or delivery endpoints. Pro
   Matching ids never connect different machines or OS users.
 - **More than one root.** A monorepo whose apps live in separate directories, or a
   workspace that spans sibling checkouts.
-- **Shared policy.** Claim mode and context budget, agreed once and committed, rather than
-  each person's machine deciding.
-- **Stated expectations.** `requiredAdapters` records which harnesses this project expects
-  to be installed, so `acc doctor` can say what is missing rather than leaving a session
-  silently uncoordinated.
+- **Shared context budget.** Set the ceiling for supported injected turn context once for
+  the workspace.
 
 ### Define the file
 
@@ -39,10 +36,8 @@ link can point anywhere, including at a file the repository does not control.
   "displayName": "Example",
   "roots": ["."],
   "policy": {
-    "claimMode": "advisory",
     "contextBudgetBytes": 6000
-  },
-  "requiredAdapters": []
+  }
 }
 ```
 
@@ -52,11 +47,16 @@ link can point anywhere, including at a file the repository does not control.
 | `workspaceId` | Stable identity, portable id | required |
 | `displayName` | What peers see in a roster | the directory name |
 | `roots` | Directories in this workspace, relative to the config | `["."]` |
-| `policy.claimMode` | `advisory` or `guarded` | `advisory` |
+| `policy.claimMode` | Validated compatibility metadata (`advisory` or `guarded`); does not select claim enforcement | `advisory` |
 | `policy.contextBudgetBytes` | Ceiling on injected turn context, 1–64000 | `6000` |
-| `requiredAdapters` | Harnesses this project expects | `[]` |
+| `requiredAdapters` | Validated compatibility metadata; does not affect `acc doctor` diagnostics | `[]` |
 | `extensions` | Anything else, namespaced by whoever wrote it | `{}` |
 
+`policy.claimMode` and `requiredAdapters` are stored but have no claim or doctor effect in
+0.4. CLI claims default to advisory; request `--enforcement guarded` on each claim when
+appropriate, subject to every live participant's certified guard. MCP claims remain
+advisory. Do not use these metadata fields to configure protection or missing-client checks.
+
 Roots are refused if they are absolute or escape the workspace. An absolute root is one
 machine's layout committed to a shared repository, and `packages/../../elsewhere` reaches
 outside the boundary the workspace is supposed to be. The check counts path segments, so an
@@ -98,17 +98,25 @@ Close them, or pass `--force` if you mean it — and restart them afterwards.
 <!-- test:illustration asks a person to confirm; there is nobody to ask in a test -->
 ```bash
 acc config init        # preview, then write after you agree
-acc config validate    # read-only; reports what applies
+acc config validate    # read-only; checks acc.workspace.json in the selected directory
 ```
 
+`init` and `validate` operate only on `acc.workspace.json` directly inside the selected
+`--cwd` directory (the current directory when omitted). Unlike ordinary workspace discovery,
+they do not walk upward. Pass `--cwd` with the directory containing the config you intend
+to inspect or create. A nested `init` can create a new config that shadows an ancestor;
+check the ancestor first.
+
 `init` shows the exact file it would write and waits. In a non-interactive run — a pipe, a
 CI job, an agent — there is nobody to ask, so it refuses unless you pass `--yes`. It never
 overwrites an existing config: a committed identity is shared by everyone on the project,
 and replacing it on a mistyped command would split one workspace into two.
 
-`validate` only reads. A command someone runs to find out what is wrong must not change the
-thing it is inspecting. With no config present it reports the defaults rather than failing,
-because not having one is a valid state.
+`validate` only reads. If that selected directory has no config, it reports
+`no acc.workspace.json in selected directory; ancestors not checked`.
+The JSON result returns default config metadata for that missing local file. Ordinary
+commands may still discover an ancestor config; this is not an effective-policy report.
+Run validation with `--cwd` set to that ancestor directory to check its file.
 
 ## Keep delivery consent user-owned
 
@@ -129,6 +137,13 @@ reports next-turn or inbox fallback. Each later session must also pass its own
 generation-bound handshake. A failed session handshake clears or refuses that binding and
 reports degraded reachability; it does not rewrite the installed consent.
 
+Codex LocalDaemon delivery separately requires macOS arm64, Codex 0.152.1 or newer, a
+current feature probe, and exact thread, canonical cwd, process, version and protocol
+checks. Its daemon must already be running; ACC never starts or stops it. Codex reads
+consent from the installation record, not a shell-shim variable. Unavailable or ineligible
+sessions retain durable inbox fallback. Use `acc install --adapter codex --delivery off`
+to stop new native offers; bypassing a shim does not disable that recorded opt-in.
+
 ## Override local paths and identity
 
 Nothing in `acc.workspace.json` says where state is stored, and nothing there can — that is
@@ -137,17 +152,17 @@ that resolves inside a workspace.
 
 | Variable | Purpose |
 |---|---|
-| `ACC_DATA_HOME` | Where session, claim, and message state is kept, instead of the platform default (`~/Library/Application Support/acc` on macOS; `~/.local/share/acc` on Linux, or wherever `XDG_DATA_HOME` points) |
-| `ACC_CONFIG_HOME` | The same override, for configuration state the platform would otherwise keep alongside `ACC_DATA_HOME` |
-| `ACC_CACHE_HOME` | The same override, for cache data the platform would otherwise keep under its own cache location |
+| `ACC_DATA_HOME` | Base directory under which ACC creates `acc/` for runtime and coordination state. Defaults: `~/Library/Application Support` on macOS; `~/.local/share` on Linux, or `XDG_DATA_HOME` |
+| `ACC_CONFIG_HOME` | Parsed and validated path override; no current configuration-storage consumer |
+| `ACC_CACHE_HOME` | Parsed and validated path override; no current cache-storage consumer |
 | `ACC_PARTICIPANT` | Which participant a session belongs to, when the client does not say |
 | `ACC_WORKSPACE_ROOT` | The project to work in, instead of discovering one from the working directory. Absolute, or it is refused |
-| `ACC_SESSION` · `ACC_GENERATION` | Which session a command acts as when it is not worked out automatically. A supplied generation proves the exact opening; with only a session id the CLI resolves the current generation and refuses ambiguity |
+| `ACC_SESSION` · `ACC_GENERATION` | Explicit CLI owner credentials, supplied together by the operator for this session. Hooks do not set them. A public session ID alone never resolves a generation; see [CLI ownership](CLI.md#coordinate-from-a-session) |
 | `ACC_MCP_PARTICIPANT` | Who `acc-mcp` takes part as. `mcp` by default |
 | `ACC_MCP_WORKSPACE` | The project `acc-mcp` joins. Without it the server takes the directory the client launched it in, which is rarely the project |
-| `ACC_NO_UPDATE_CHECK=1` | Never ask npm whether a newer ACC exists. `acc update` then says it is off, which is a different answer from "nothing is newer" |
+| `ACC_NO_UPDATE_CHECK=1` | Disables update networking and background scheduling; manual recovery of an already downloaded update remains available |
 | `ACC_PROBE_TIMEOUT_MS` | How long to wait for a client to print its version. Three seconds by default: generous on an idle machine, and not always enough on a busy one, where a client that overruns it is reported as not installed |
-| `ACC_NATIVE_DELIVERY_POLICY` | Set only by an ACC-owned shell shim to the consented live policy (`off`, `actionable`, or `all`) before it `exec`s the real client, so the session's hook knows a native transport was activated. Not for a person to set: an ordinary or `ACC_BYPASS=1` launch leaves it unset, and the hook treats missing or invalid values as `off` |
-| `ACC_BYPASS=1` | Runs the unmodified client through an ACC shim: no launch-time check, no native flags, and the reserved policy variable is unset. The escape hatch when you want the vendor command exactly as it was |
+| `ACC_NATIVE_DELIVERY_POLICY` | Owned shell-bootstrap consent, currently used by Claude Code. The shim sets `off`, `actionable`, or `all`; missing/invalid values mean off for that route. Codex instead reads recorded installation consent, even when this variable is absent |
+| `ACC_BYPASS=1` | Bypasses owned shell activation, currently Claude Code: no bootstrap check/native flags, and shim policy is unset. It does not disable Codex recorded opt-in; use `acc install --adapter codex --delivery off` for new Codex offers |
 | `ACC_BOOTSTRAP_DEBUG=1` | Lets the internal `acc-bootstrap` check write one safe diagnostic line to stderr. Off, it is silent, and it never writes to stdout |
 | `CODEX_HOME` | Codex's own home, honoured when locating the Codex App Server daemon's control socket for native delivery. Codex sets it; ACC only reads it |

package/docs/DESIGN_DECISIONS.md

@@ -18,12 +18,15 @@ boundaries exist.
 | Runtime state outside the repository | A checkout can be deleted, cloned, or synced; presence and locks must not travel with it. |
 | Project config optional and runtime-free | A committed file is editable by anyone with a PR, so it may carry policy — never sessions or tokens. |
 | Durable state is authoritative | Next-turn or live delivery may accelerate an interaction; neither becomes the source of truth. |
+| Bounded discovery, explicit history recovery | Automatic context stays small; peers select exact messages or historical records when they need full bodies. |
+| Immutable explicit decision links | Replacements and withdrawals preserve prior records and expose competing branches without choosing by timestamp. |
+| Fence managed runtime activation | Refresh all integrations before switching the active generation; partial refresh stays fenced until forward recovery completes. |
 | No heartbeat helper in v1 | An idle session is honestly reported `stale`. A sidecar process to fake liveness is worse than the truth. |
 | Presence reads the process, never writes the record | A pid answers "gone" at once; an age floor covers what a pid cannot, including its own reuse. Nothing is written back — no session has authority to edit another's record. This checks a process already there, not one beating on a session's behalf like the heartbeat helper above. |
-| No process launching | ACC attaches to sessions you already own. Owning them is a different product. |
+| No AI client or session launching | ACC attaches to sessions you already own; its separate update worker manages ACC packages, not those sessions. |
 | One publishable package | One version and one release rather than twelve coordinated ones. |
 | MIT | Widest reuse, least friction. |
-| Node 24 (current production LTS) | Uses `node:test`, modern `fs` promises, and no transpiler. |
+| Node 24 or newer required | Uses `node:test`, modern `fs` promises, and no transpiler. |
 | MCP session from launch config | Never from `initialize` or `clientInfo` — those are attacker-controllable. See the threat scenarios in [SECURITY_MODEL.md](SECURITY_MODEL.md) (scenario 8). |
 
 ## Avoid these rejected designs
@@ -32,7 +35,7 @@ boundaries exist.
 |---|---|
 | A file in each repo that agents poll | No guard, no identity, no atomicity — and it ends up committed. |
 | A permanent global lead session | Turns peers into workers and makes one crash fatal. |
-| Treating MCP as a lifecycle guarantee | MCP is a tool surface. It cannot attach, guard, or wake anything. |
+| Treating MCP as an external-client lifecycle guarantee | Tool calls resolve MCP's own participant, but cannot infer the client's lifecycle, intercept writes, or wake its receiver. |
 | Requiring Git, tmux, PostgreSQL, or a service | Every requirement is a reason the tool is not installed. |
 | Collecting or sharing raw transcripts | Raw transcripts are never collected or shared. Explicit peer messages are bounded records the sender chose to address. |
 | Reporting queued messages as delivered | A delivery state that overstates itself is worse than no state. |
@@ -47,16 +50,18 @@ perturbed the record instead of removing it — a hook whose recorded hash no
 longer matched was still observed running, so absence was never actually
 tested.
 
-Absence is the whole mechanism. With no record, the client runs no hook at
-all, prints `hook: SessionStart Completed` while executing nothing, and ACC's
-write guard goes silently off — while `acc doctor` and `codex plugin list`
-both report it enabled. On a real machine, a shell write walked through a
+Absence was sufficient to disable the hooks in that historical capture. With no
+record, that client ran no hook, printed `hook: SessionStart Completed` while
+executing nothing, and ACC's write guard went silently off — while `acc doctor`
+and `codex plugin list` both reported it enabled. A shell write walked through a
 guarded claim; writing the exact same hashes back (captured before deletion,
 from an ACC three releases older) revived the guard immediately.
 
-That is why removal is never ACC's to do: the record is granted once by a
-person, survives ACC upgrades, and nothing ACC writes can restore it.
-Tidiness is not worth a permission only a human can re-grant.
+That is why removal is never ACC's to do: it preserves the client's trust decision.
+The historical observation above does not establish trust across arbitrary upgrades.
+Codex 0.153.4 compares each current definition's hash and reports changed definitions
+as modified; a trusted hook can also be disabled. ACC preserves the records but leaves
+current readiness unverified, directing the user to `/hooks` in Codex.
 
 **The generalisation, since this cost a release:** to learn whether state is
 load-bearing, take it away. Changing it tests something else.
@@ -81,7 +86,7 @@ where a guard stops behaves better than one that believes it absolute.
 1. **Storage backend.** The hardened filesystem store ships first. A transactional backend
    can go behind the same interface later — but not merely to avoid a dependency.
 2. **Remote coordination.** v2, or a separate product.
-3. **Process launching.** Possibly never; possibly an external integration.
+3. **AI client/session launching.** Possibly never; possibly an external integration.
 4. **Multi-root discovery rules** beyond the current `roots` list.
 5. **Default claim lease length** for hook-only adapters. A hook-only session cannot sustain
    a short renewal cadence, so lease policy must not assume one.