agents-can-communicate 0.4.0 → 0.4.2

package/README.md

@@ -1,23 +1,19 @@
 # agents-can-communicate
 
-**Open your agents. Let them coordinate.**
+**Independent AI sessions. Shared work context.**
 
-Give Codex the backend. Ask Claude Code to build the interface. Keep working as usual.
+Give Codex the backend. Ask Claude Code to build the interface. Keep using the clients
+and models you prefer.
 
-ACC makes supported sessions in the same project aware of each other and gives them
-instructions for coordinating. Agents discover their peers, share what they're working
-on, and decide when to ask questions, agree on changes, or avoid overlapping edits.
+ACC is a local coordination layer for AI sessions you open yourself. It gives them peer
+presence, work intent, file claims, messages, review requests, and durable handoffs.
+Each session keeps its own conversation, permissions, and task. The agents decide when
+coordination helps their work.
 
-Think of the coordination you expect from subagents, extended across the independent
-sessions you open yourself — with different clients and models. You keep giving them
-ordinary tasks; they handle the conversations around their work.
+Sessions can use different clients or multiple instances of the same one. They meet in
+the same workspace on the same machine and operating-system user; Git is optional.
 
-Active hooks supply each agent's own CLI arguments in coordination context; the installed
-skill tells the agent to use them. This path was observed in Claude Code 2.1.263 and
-Codex 0.153.4. Hooks must be enabled and trusted by the client. Without hook context, owner
-operations require an explicit pair or session-bound ACC MCP tools. See [CLI ownership](docs/CLI.md#coordinate-from-a-session).
-
-[Try it](#try-it) · [Supported clients](#when-messages-arrive) · [Documentation](docs/index.md)
+[Try it](#try-it) · [Client support](#when-messages-arrive) · [Update ACC](#update-or-remove-acc) · [Documentation](docs/index.md)
 
 [![CI](https://github.com/automatis-tools/agents-can-communicate/actions/workflows/ci.yml/badge.svg)](https://github.com/automatis-tools/agents-can-communicate/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
@@ -32,9 +28,9 @@ Open two sessions in your project and give each its task:
 | Codex | Build the backend for account registration. |
 | Claude Code | Build the registration screen. |
 
-ACC's integration tells the agents that peers are present and teaches them how to find
-out what those peers are doing. As they work, they can notice the dependency and coordinate
-on their own. An illustrative exchange:
+Supported integrations introduce peer awareness and teach agents how to find out what
+others are doing. As they work, they can notice a dependency and coordinate. An
+illustrative exchange:
 
 ```text
 Claude → Codex   I'm building the registration screen. What will your endpoint accept?
@@ -42,87 +38,118 @@ Codex → Claude   Email and password. I'll return the new user and handle valid
 Claude → Codex   I'll use that shape and keep my changes in the UI files.
 ```
 
-The agents identify who to talk to and what to agree on. Your prompts stay focused on
-the feature you want to build.
-
-The same setup supports a review and handoff. Ask one session to implement a change and
-request review of an identified revision: a commit when Git is available, or named files
-and version otherwise. Ask the other to return blocking defects or approval. The author
-can address the verdict before finishing, or leave a durable handoff so a later session
-can recover what is complete and what remains. See the
-[review request](docs/CLI.md#messages-and-requests) and [handoff](docs/CLI.md#handoff)
-commands behind that flow.
+Your prompts stay focused on the feature. Each agent decides which peers and messages
+matter to its task; installing ACC does not guarantee that a model will coordinate on
+every task. [Client support](#when-messages-arrive) determines how automatically that
+awareness reaches it.
 
-Each session keeps its own conversation and instructions. Response timing depends on the
-receiving client: see [when messages arrive](#when-messages-arrive).
+The same setup supports review and recovery. An author can request review of an
+identified revision, receive defects or approval, and leave a handoff describing completed
+work, remaining work, and blockers. A later session can look up that history. Git commits
+can identify a revision; named files and versions work when Git is unavailable.
+See [requests and replies](docs/CLI.md#messages-and-requests) and
+[handoffs](docs/CLI.md#handoff).
 
 ## Try it
 
 You'll need **macOS or Linux, Node.js 24 or newer**, and two AI sessions in the same
-project. They can use different clients or the same one.
+project. Install once on the machine:
 
 ```bash
 npm install -g agents-can-communicate
 acc install
 ```
 
-The installer connects the clients it finds. Open a new terminal and restart your AI
-clients to load the integration. If you use Codex, accept its plugin trust prompt.
-ACC then keeps its runtime and skills updated in the background, waiting for active clients
-to exit before switching versions. [Update controls](docs/UPGRADING.md#automatic-updates-after-installation)
-include manual update, opt-out, and version pinning.
+The installer connects the supported clients it finds. Follow its activation instructions,
+then restart your clients from the project directory. In Codex, check `/plugins` and
+review the current ACC definitions in `/hooks`; changed hooks may need fresh trust.
+[Getting started](docs/GETTING_STARTED.md) covers activation and preserved sandbox settings.
 
-Open two sessions in your project and give them ordinary tasks, as in the example above.
-On supported clients, ACC introduces peer awareness through the client's own integration;
-its installed instructions guide the agents to coordinate when their work overlaps.
+Open two sessions and give them ordinary tasks, as above. Look for an agent discovering a
+peer, checking who is changing a file, asking about a shared dependency, or replying to a
+review request.
 
-Look for coordination in the agents' own activity: discovering a peer, checking who is
-changing a file, or asking about a shared dependency. Each agent decides what is relevant
-to its task; the integration provides awareness, not a guarantee that a model will
-coordinate on every task. [Client support](#when-messages-arrive) determines how
-automatically peers and messages reach it.
+Run `acc doctor` from the project if a peer is missing. A directory containing ACC's own
+state, commonly your home directory, cannot be used as a workspace; start the client in a
+project directory. See [Troubleshooting](docs/TROUBLESHOOTING.md).
 
-If the other session doesn't appear, run `acc doctor` from your project directory.
-[Get help with setup](docs/TROUBLESHOOTING.md).
+Already using ACC? Follow the [upgrade guide](docs/UPGRADING.md), including the 0.4.0/0.4.1 →
+0.4.2 update and the data-format boundary when moving from 0.3.1.
 
 ## When messages arrive
 
-ACC connects sessions **on the same machine** and saves messages locally, so a waiting
-session can pick them up later. Delivery depends on the client:
+Messages are saved locally before delivery is attempted. A durable inbox remains
+available when a faster route cannot be used.
 
 | Client | How the agent receives a message |
 |---|---|
-| Codex CLI, Claude Code, Gemini CLI, Kimi Code | At the next normal turn on verified versions and platforms; otherwise by checking its ACC inbox. |
-| Grok or another client connected through [MCP](docs/MCP.md) | By checking its ACC inbox. |
+| Codex CLI, Claude Code, Gemini CLI, Kimi Code | At the next normal turn on the exact verified versions and platforms; otherwise through explicit ACC inbox reads. |
+| Grok | Through explicit ACC inbox reads, using its installed hooks and skill. CLI ownership was verified on Grok 1.0.24. |
+| Other clients connected through [MCP](docs/MCP.md) | Through ACC tools and inbox reads. Generic MCP requires its own client configuration and coordination instructions. |
+
+Grok's updated skill first runs public status through the terminal. The ACC hook reminder
+after that result supplies the session's own CLI arguments for subsequent inbox reads and
+mutations. It adds no automatic peer-message injection or idle delivery. A relocated
+`GROK_HOME` is respected by install, doctor, and uninstall.
+
+**Optional live delivery can start a turn in an idle Codex or Claude Code session.** It is
+experimental, off by default, and can spend model tokens. On Apple Silicon Macs, Codex
+0.152.1 or newer requires an already-running LocalDaemon and a verified session;
+Claude Code 2.1.258 or newer requires zsh and client-side Channels activation; check its
+startup notice for ACC and accept the development warning when shown. An MCP connection
+alone does not verify inbound delivery. Messages arriving mid-turn wait for the turn to
+finish. The receiving session's
+opt-in policy and current reachability determine whether delivery can proceed.
+`acc install` reports each client's delivery state and can save Codex consent before its
+service is available. `acc doctor` also names each session’s last native binding result,
+including missing launch consent, an unidentified client process or a failed handshake.
+It distinguishes a disabled policy from an unavailable service or a missing live channel
+in the current project.
+
+A Codex thread retained by LocalDaemon can receive opted-in messages after its terminal
+exits. Turning ACC delivery off prevents new native offers; already accepted queue entries
+remain with the client. [Compatibility and delivery controls](docs/CAPABILITIES.md) describe
+the exact evidence, versions, platforms, and fallback paths.
+
+A recorded message is send success. An offer is not proof of reading, and an
+acknowledgement or reply is not proof that the requested work is complete.
 
-**Codex and Claude Code can also reply while idle.** These optional modes are
-experimental, off by default, and can spend model tokens. On Apple Silicon Macs,
-Codex 0.152.1 or newer requires an already-running LocalDaemon and an exact session
-check; ACC preserves your ordinary launch command. Claude Code 2.1.258 or newer
-requires zsh and its development-channel warning at startup. Messages arriving
-mid-turn wait for it to finish.
+## Keep the workflow you like
 
-Each direction follows the receiving client's policy and current reachability.
-A Codex thread retained by LocalDaemon can receive opted-in messages after its
-terminal exits. Turn ACC delivery off to prevent new native offers; already accepted
-queue entries remain with the client.
+- **Your usual tools.** Start clients with their normal commands. You choose each agent's
+  task, model, and permissions.
+- **Separate checkouts, one project.** Git worktrees share an ACC workspace. Plain folders
+  work too; optional workspace configuration can supply a shared identity and roots.
+- **Agree before editing.** Agents can claim files and identify overlapping work. CLI claims
+  default to advisory. Guarded claims require certified guards from every live participant.
+  [How claims work](docs/CONCEPTS.md#intent-is-awareness-a-claim-commits).
+- **Focused context and durable history.** Normal turn context is bounded. Inbox and history
+  return summary pages, with message bodies fetched by id. Agents can supersede or withdraw
+  old decisions and recover prior handoffs when needed.
+- **Local coordination.** State lives in app data outside your project. ACC never collects
+  or shares raw transcripts; peer messages are untrusted input. Your clients keep using
+  their usual model providers.
 
-[Full compatibility details](docs/CAPABILITIES.md).
+One npm package. ACC needs no separate account, model API key, or hosted service.
 
-## Keep the workflow you like
+## Update or remove ACC
 
-- **Your usual tools.** Start clients with their normal commands. You choose each
-  agent's task, model, and permissions.
-- **Separate checkouts, one project.** Git worktrees share an ACC workspace.
-  Plain project folders work too; Git is optional.
-- **Agree before editing.** Agents can reserve files and identify overlapping work.
-  CLI reservations default to advisory. `--enforcement guarded` requests enforcement,
-  which still requires certified guards from every live participant.
-  [How reservations work](docs/CONCEPTS.md#intent-is-awareness-a-claim-commits).
-- **Local coordination.** Messages live in app data outside your project. ACC doesn't
-  collect or share raw transcripts. Your clients use their usual model providers.
+Initial installation enables automatic updates. ACC downloads stable releases in the
+background and waits for active clients and ACC processes to exit before switching the
+runtime and refreshing integrations. Restart clients afterward and complete any requested
+hook or plugin trust review.
+
+For an immediate update:
+
+```bash
+acc update
+```
 
-One npm package. No account or separate coordination service to set up.
+An existing managed installation selects its new runtime through this command. Updates
+also support an explicit opt-out and version pinning. Reinstalling preserves your update
+preference; see [update controls](docs/UPGRADING.md#automatic-updates-after-installation).
+If you fully uninstalled ACC 0.4.0 before upgrading and want automatic updates back, run
+`acc update --auto on` once: that version's uninstall record lost the previous preference.
 
 To remove the integrations:
 
@@ -130,7 +157,9 @@ To remove the integrations:
 acc uninstall
 ```
 
-ACC preserves configuration changes you've made since installation.
+ACC removes owned artifacts that still match its install record, preserves your edits and
+coordination history, and pauses automatic updates. A later install remembers the update
+preference.
 
 ## Go further
 

package/bin/entrypoints/hook-output.mjs

@@ -50,9 +50,13 @@ function tryWrite(stream, output) {
 export async function completeHookOutput(result,
   { stdout = process.stdout, stderr = process.stderr } = {}) {
   if (result.failed || result.timedOut) {
-    // Hook failures can include arbitrary payload or filesystem text. Report
-    // degradation without reflecting those details into the client's output.
-    tryWrite(stderr, "acc: coordination unavailable; hook continued without context\n");
+    // Only a known code selects static recovery advice. Arbitrary payload or
+    // filesystem error text must never become client-visible instructions.
+    const recovery = result.failureCode === "workspace_contains_runtime"
+      ? ": workspace contains ACC runtime state; open a project directory and restart the client"
+        + " (or set ACC_DATA_HOME outside the workspace)"
+      : "";
+    tryWrite(stderr, `acc: coordination unavailable${recovery}; hook continued without context\n`);
   }
   try {
     await writeOutput(stdout, result.stdout ?? "", { deadlineAt: result.deadlineAt });

package/docs/ADAPTER_AUTHORING.md

@@ -42,6 +42,16 @@ 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
@@ -197,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

@@ -68,7 +68,13 @@ livePolicy · opaqueEndpointRef · leaseUntil
 
 Core validates identity and expiry but never interprets the opaque endpoint. That remains
 inside the owning adapter. `acc status` reports available modes, policy, reachability, and
-lease without exposing the endpoint.
+lease without exposing the endpoint. The hook runner also replaces one optional native
+attempt diagnostic beside its session-owner file: closed policy/process/handshake
+metadata with a timestamp, never vendor output. Doctor joins it only to the current open
+generation and reports it separately from transport and receipt facts. It is not journalled
+or projected into agent context; session restart replaces it and SessionEnd attempts bounded
+cleanup. Doctor ignores closed or superseded generations even if cleanup could not finish. Diagnostic disk I/O runs in an
+unreferenced worker, so a stalled write cannot hold the hook process open.
 
 ## Certified capability versus current reachability
 
@@ -104,6 +110,8 @@ A lone session can remain ephemeral. Durable state materialises when a second li
 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

package/docs/CAPABILITIES.md

@@ -56,7 +56,7 @@ The limitations belong next to the adapters they affect:
 | 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 | 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. |
 

package/docs/CLI.md

@@ -239,8 +239,9 @@ external AI client. An addressed handoff requires acknowledgement; a room handof
 `--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
+terminal asks one default-No question per supported client. Codex can save consent while
+its local service is unavailable or has no loaded session; this does not activate delivery.
+A non-interactive run or a `--dry-run` 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. Claude Code shell activation writes an owned
@@ -248,9 +249,30 @@ zsh PATH block and a shim that `exec`s the real client; `ACC_BYPASS=1` bypasses
 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
+starts or stops the vendor daemon. The install summary names each client's requested policy,
+activation state and verified fallback. `doctor` separates protocol readiness, recorded
+consent and a live channel in the current workspace, with a next step for missing activation.
+A supported version or an installed plugin alone is not an active delivery channel.
+`runtime: active` means ACC has a reachable local transport binding. Claude can still
+block inbound Channels messages while its MCP server and tools remain connected;
+doctor therefore also names the client-side startup check.
+In doctor JSON, `nativeDelivery.activation` distinguishes missing launch setup from a
+recorded setup (or `not_required` for a pre-existing service). `policy` is the installed
+choice; `sessionPolicy` describes a native binding when one is visible. Existing Claude
+sessions can retain their launch policy after a different choice is installed for new
+sessions; Codex checks current recorded consent before new offers.
+`nativeDelivery.sessions` lists each current session's identity, present transport state
+and `lastAttempt`: timestamp, startup/turn event, effective policy and its source, whether
+that policy was missing/invalid/off, whether a client process was identified, and the closed
+handshake result/reason. `lastAttempt: null` means no usable attempt was observed for this
+generation; it does not prove hooks are disabled. A past successful handshake is separate
+from current transport reachability. ACC replaces this small diagnostic beside the
+hook-owner file outside the repository; it never adds attempt history to agent context.
+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

package/docs/GETTING_STARTED.md

@@ -4,16 +4,19 @@ Install ACC, open the AI sessions you already use, and give them related work. S
 integrations make peers visible and teach each agent how to communicate. You do not need to
 carry messages between windows or add coordination instructions to your task prompts.
 
-Active hooks supply each agent's own CLI arguments in coordination context; the installed
-skill tells the agent to use them. This path was observed in Claude Code 2.1.263 and
-Codex 0.153.4. Hooks must be enabled and trusted by the client. Without hook context, owner
-operations require an explicit pair or session-bound ACC MCP tools. See [CLI ownership](CLI.md#coordinate-from-a-session).
+Active hooks can supply each agent's own CLI arguments; the installed skill tells the
+agent how to use them. This path was observed in Claude Code 2.1.263, Codex 0.153.4, and
+Grok 1.0.24. Grok receives its own header after a terminal result, so its skill runs public
+status first; peer messages still require explicit inbox reads. Hooks must be enabled and
+trusted by the client. Without that owner context, owned operations require an explicit
+pair or session-bound ACC MCP tools. See [CLI ownership](CLI.md#coordinate-from-a-session).
 
 ## 1. Install once on this machine
 
 ACC requires macOS or Linux and Node.js 24 or newer.
 
-Already using 0.3.1? Follow the [upgrade guide](UPGRADING.md) before mixing versions.
+Already using ACC? Follow the [upgrade guide](UPGRADING.md) for the 0.4.0/0.4.1 → 0.4.2
+update or the data-format boundary when upgrading from 0.3.1.
 
 ```bash
 npm install -g agents-can-communicate
@@ -24,7 +27,8 @@ npm install -g agents-can-communicate
 acc install
 ```
 
-Installation also enables automatic updates. ACC downloads releases in the background and
+Initial installation also enables automatic updates; reinstalling keeps an explicit opt-out.
+ACC downloads releases in the background and
 refreshes its runtime and skills when active clients have left. Use `acc update` for an
 immediate update, or `acc update --auto off` to disable background updates. See
 [update controls](UPGRADING.md#automatic-updates-after-installation).
@@ -40,8 +44,16 @@ state directory is in `sandbox_workspace_write.writable_roots` in the config it
 ACC keeps those user settings unchanged. Installed files alone do not establish that hooks
 are active; `acc doctor` leaves current readiness unverified and directs you to Codex.
 
-If you opt into Claude Code's experimental idle delivery, Claude also shows its own
-development-channel warning at every startup. The feature is off by default, can spend
+Read the delivery summary for each client. Live delivery needs an explicit opt-in and a
+verified channel in the current session. Codex can save your choice even when its local
+service is not running yet. Declining uses the reported fallback: `acc inbox`, or next-turn
+hooks only where the exact client version and platform are certified.
+
+If you opt into Claude Code's experimental idle delivery, check Claude's Channels startup
+notice for ACC and accept its development-channel warning when shown. If it reports Channels
+unavailable or blocked, a connected MCP server does not make inbound delivery work;
+see [troubleshooting](TROUBLESHOOTING.md#i-enabled-live-delivery-but-got-fallback).
+The feature is off by default, can spend
 model tokens, and currently requires Apple Silicon macOS, zsh, and Claude Code 2.1.258 or
 newer. You do not need it for durable messages or supported next-turn delivery.
 

package/docs/RELEASING.md

@@ -1,7 +1,7 @@
 # Releasing
 
 Use this procedure to build one auditable npm artifact, verify that exact tarball, and keep
-its evidence tied to the commit that supplied its bytes. The package is currently `0.4.0`;
+its evidence tied to the commit that supplied its bytes. The package is currently `0.4.2`;
 the commands derive the version from `package.json` so the filename cannot drift.
 
 ```mermaid

package/docs/SECURITY_MODEL.md

@@ -104,7 +104,9 @@ from operating merely because its own state is unavailable.
 
 ## Managed automatic updates
 
-A normal managed installation enables automatic updates. The latency-sensitive hook path
+An initial managed installation enables automatic updates; later installs preserve an
+explicit opt-out. Full uninstall pauses updates while retaining the setting for a later
+reinstall. The latency-sensitive hook path
 does no network download; it may schedule a detached worker. That worker uses the configured
 npm registry/network and local npm executable, checks stable package identity/version and
 sha512 integrity against registry metadata, installs with lifecycle scripts disabled, and

package/docs/TROUBLESHOOTING.md

@@ -24,12 +24,32 @@ requires plugin trust.
 ACC does not launch a missing session. Open it normally after fixing the installation or
 workspace path.
 
+## A hook says `workspace contains ACC runtime state`
+
+The current directory contains ACC's own state, so ACC cannot use it as a workspace.
+This commonly happens when a client starts in your home directory (`~`). The client
+continues normally, but ACC provides no coordination context there.
+
+Open a project directory and restart the client from it. A project inside your home
+works normally; Git is optional. If you intentionally need the broader directory as
+a workspace, configure `ACC_DATA_HOME` outside it for all participating clients.
+This changes the state location; it does not migrate existing history or integrations.
+
+For a generic `coordination unavailable` warning, run `acc status --json` from the
+same directory to see the detailed workspace error, and `acc doctor` to check the
+installation. Hook warnings deliberately omit arbitrary paths and error details.
+
 ## CLI says `caller_identity_unresolved`
 
 ACC cannot prove which session owns this shell command. A hook-created presence record
 and the client's native session ID are not shell credentials. Restarting hooks alone does
 not fix this CLI limitation.
 
+In Grok, run public `acc status --json` through the terminal tool first. With the
+updated integration, the ACC hook reminder arrives after that result and supplies
+the session's own CLI arguments. Restart Grok after refreshing its integration;
+a header returned with `finish` belongs to the session that just closed.
+
 Use this session's ACC MCP tools if available. For a manual CLI workflow, open your own
 session with `acc attach --participant my-session --json`, retain the returned `sessionId`
 and `generation`, and pass both as `--session` and `--generation` on subsequent mutations
@@ -74,13 +94,51 @@ For Codex, use your ordinary launch command with 0.152.1 or newer on Apple Silic
 macOS. Its LocalDaemon must already be running, and trusted hooks must establish
 the receiver's exact thread and workspace. Embedded sessions, an absent socket,
 ambiguous recipients or failed identity checks retain durable inbox access.
-`acc doctor` reports current eligibility. ACC preserves requested consent through
-a temporary daemon outage and does not start the daemon for you.
+`acc doctor` reports readiness, consent and the current workspace's live channel separately.
+`native_endpoint_unavailable` means the local service endpoint is missing or is not a safe socket;
+`native_session_unavailable` means the service answered but has no loaded thread to probe.
+An interactive install can save consent in either case. ACC preserves it through a temporary
+outage and does not start the daemon for you.
+
+Check `acc doctor --json` and `acc status --json` while both clients are open. If policy is
+`off`, opt in with `acc install --adapter codex --delivery actionable` (or select another
+adapter). This can spend model tokens. If policy is enabled but runtime is `waiting` and
+`deliveryBindings` is empty, no live channel is bound in this workspace. Start a new client
+session, check its integration prompts and re-run doctor. A healthy store, online peers,
+or a connected MCP server does not by itself establish automatic delivery. `lifecycle:
+manual` can also mean the current version has no certified session-end hook; it does not
+prove that no hooks ran.
 
 For Claude Code, open a fresh interactive zsh after installation so its launcher
-is on PATH, and accept its visible development-channel warning. A failed channel
-connection may remain in Claude's `~/.claude/mcp-needs-auth-cache.json` for about
-fifteen minutes; remove only the `acc` entry and restart if that is the cause.
+is on PATH. Check Claude's **Channels startup notice for ACC**, and accept the
+development-channel warning when it appears. A successful bootstrap cache means the
+executable passed ACC's compatibility probe. `/mcp` showing `connected` and two tools
+means the MCP server connected. Even `runtime: active` in ACC's doctor JSON describes
+the local transport; none of these proves that Claude enabled inbound channel messages.
+
+If Claude says `--dangerously-load-development-channels ignored` or `Channels are not
+currently available`, it has not enabled that delivery path. On a fresh 2.1.266 test
+profile, the first launch showed those messages and the next launch showed the development
+warning; restarting once can recheck availability, but is not a guaranteed fix. If it
+remains unavailable, follow Claude's notice. Organization policy can also block Channels;
+an administrator must enable them where required. ACC does not override that policy.
+See [Claude's Channels documentation](https://code.claude.com/docs/en/channels).
+
+If `deliveryBindings` is empty, ACC has not bound a local transport either. Read the
+per-session lines in `acc doctor`, or `nativeDelivery.sessions[].lastAttempt` in JSON:
+
+- An absent launch policy means that hook did not receive delivery consent, even if an
+  earlier bootstrap probe succeeded. For Claude, open a new terminal and client through
+  the installed launcher.
+- `client_process_unknown` means ACC could not identify the client process. A new client
+  session repeats that lookup.
+- `handshake_failed` or `handshake_timeout` means the session could not bind the local
+  channel. Check the client's integration/channel setup; the next ordinary turn retries.
+- No attempt observed can mean no native hook ran, an older runtime wrote the owner, or
+  diagnostic persistence failed. Check hook activation and the runtime versions in doctor.
+
+The timestamp describes the last attempt for that exact generation. A past successful
+handshake does not establish a currently reachable channel or client-side admission.
 
 Closing a Codex terminal can leave its daemon thread loaded and eligible. Use
 `acc install --adapter codex --delivery off` to stop new ACC native offers.
@@ -112,8 +170,12 @@ or start the session somewhere trusted.
 
 ## Grok shows no injected message
 
-Grok 1.0.13 discarded UserPromptSubmit context in the real capture. Its next-turn and guard
-capabilities remain false. Use `acc status` and `acc inbox`; do not wait for a banner.
+Grok discards UserPromptSubmit context. On the observed 1.0.24 client, run public
+`acc status --json` in its terminal first: the ACC hook reminder after the result
+supplies your own `--session` and `--generation` pair for subsequent inbox reads and
+mutations. Restart Grok after refreshing its installed hooks and skill. Its next-turn,
+live delivery, and guard capabilities remain false; peer messages require explicit inbox
+reads. If the header never arrives, report missing ownership rather than adopting a peer.
 
 ## Kimi sessions remain in history