agents-can-communicate 0.8.1 → 0.8.3

package/docs/ADAPTER_AUTHORING.md

@@ -29,6 +29,7 @@ export function createExampleAdapter() {
     detect, install, uninstall, doctor,
     planInstall,                      // what install would write
     preflightUninstall,               // optional read-only removal validation
+    inboundSockets,                   // optional: socket paths a live sender connects to
     normalizeHook,                    // client payload -> normalised event
     renderContext,                    // SyncResult -> text
     renderContextResult,              // text + ids of complete rendered groups
@@ -227,6 +228,19 @@ the refreshed lease. Refresh is not a heartbeat and cannot extend presence beyon
 its own expiry. Optional `retireNativeSession()` cleans adapter-owned endpoint state
 after confirmed core retirement; it must remain bounded and fail open for hooks.
 
+An adapter whose `offerMessage()` connects to a Unix socket in the recipient's session
+declares where those sockets live with the optional `inboundSockets(context)`. It returns
+absolute paths, directories or sockets, derived from `context.env`, `context.platform` and
+the client homes in the context. It runs synchronously, once per install, doctor or refresh
+command, and must never throw. It may read the adapter's own records under
+`context.stateRoot` when a session can bind outside what the environment implies. Claude Code
+reads its endpoint records there, and keeps each read bounded. The installer
+composes every known adapter's declaration into `context.receiverSockets`. An adapter whose
+client sandboxes the sender's shell allows exactly that list, and reports its outgoing
+permissions configured only while every entry is allowed. It never names another vendor's
+paths itself. Codex does this in its permission profile. Declare a new receiving transport
+here, or every Codex sender gets `transport_permission_denied` against it.
+
 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,

package/docs/CAPABILITIES.md

@@ -71,7 +71,7 @@ The limitations belong next to the adapters they affect:
 
 | Adapter | Exact limitation and evidence |
 |---|---|
-| Antigravity CLI | 1.2.7 on darwin-arm64, captured in print mode, and every later release by the forward rule. Only `SessionStart`, `PreInvocation`, `PostInvocation` and `Stop` load; `SessionEnd`, `PreToolUse` and `PostToolUse` are accepted into the config file and silently dropped, so there is no tool guard and no session-end deregistration - a session goes offline by presence age or an explicit `acc finish`. Payloads carry no `hook_event_name`, so each registered command passes its own event name. The end-of-turn `Stop` continuation reaches the model and is a bounded nudge, not a gate: ACC continues a turn at most once and fails open, and the client caps consecutive continuations itself (vendor 1.1.9). `agy agentapi send-message` can wake an idle session - captured - but only with that session's language-server address and CSRF token, which exist in the agent's own shell and in no hook. ACC does not take that token, so live push and reply routing are false. A peer message that arrives while the model writes its last answer is carried by the `Stop` continuation instead. A write that parses can register nothing, so install and doctor read `agy -p "/hooks"` back instead of trusting the file. Live push (1.2.7, darwin-arm64, TUI only, experimental, recorded opt-in) runs through a relay the agent starts once per conversation from its own shell - the only process holding the session endpoint - after ACC's context asks it to, up to three times while none is serving; the operator approves that command at the client's permission prompt. An idle session wakes; a busy one sees the message after its running answer, or at the next model invocation when the turn waits on a tool. Print mode and the first session in a folder trusted at that launch get no relay. |
+| Antigravity CLI | 1.2.7 on darwin-arm64, captured in print mode, and every later release by the forward rule. Only `SessionStart`, `PreInvocation`, `PostInvocation` and `Stop` load; `SessionEnd`, `PreToolUse` and `PostToolUse` are accepted into the config file and silently dropped, so there is no tool guard and no session-end deregistration - a session goes offline by presence age or an explicit `acc finish`. Payloads carry no `hook_event_name`, so each registered command passes its own event name. The end-of-turn `Stop` continuation reaches the model and is a bounded nudge, not a gate: ACC continues a turn at most once and fails open, and the client caps consecutive continuations itself (vendor 1.1.9). `agy agentapi send-message` can wake an idle session - captured - but only with that session's language-server address and CSRF token, which exist in the agent's own shell and in no hook. ACC does not take that token, so live push and reply routing are false. A peer message that arrives while the model writes its last answer is carried by the `Stop` continuation instead. A write that parses can register nothing, so install and doctor read `agy -p "/hooks"` back instead of trusting the file. Live push (1.2.7, darwin-arm64, TUI only, experimental, recorded opt-in) runs through a relay the agent starts once per conversation from its own shell - the only process holding the session endpoint - after ACC's context asks it to, up to three times while none is serving; the operator approves that command at the client's permission prompt. An idle session wakes; a busy one sees the message after its running answer, or at the next model invocation when the turn waits on a tool. Print mode and the first session in a folder trusted at that launch get no relay. The client asks before every shell command (1.2.12), so install always adds the prefix rule `command(<wrapper>)` to the client's settings to let the woken agent's ACC commands run without that prompt. A woken session answered with no prompt under that rule on 1.2.12 (2026-09-28); print mode with it has not been captured. |
 | Codex | Next-turn context, captured on 0.147.0, 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. From 2.1.282, captured on darwin-arm64 and applied on every platform whose inbox is a Unix socket, `delivery.livePush` is a live capability behind the native contract (experimental, off until opted in). ACC wakes the session through the inbox socket that Claude Code opens for every session, with one line of fixed ACC text and the message id. An idle session starts a turn. A busy session takes the wake between two tool calls. Each delivered wake fires `UserPromptSubmit`, so the next-turn hook shows the body and records the receipt `offered` via `next-turn`. The model answers with `acc reply`, so `delivery.replyRoute` stays false. A session in `bypassPermissions` mode holds each wake for approval unless `crossSessionInbound` is `accept`, and `refuse` drops wakes. Native Windows keeps next-turn delivery: its inbox is a named pipe that requires an auth line, and it is uncaptured. Linux is uncaptured. |
 | Gemini CLI | Package-shipped next-turn certification starts at 0.57.0. 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. |

package/docs/CLI.md

@@ -104,6 +104,17 @@ got. Two sessions of one participant show the same numbers, so read the workspac
 `<n> offered, not retrieved` when that number is above zero. Offered is not read: a
 transport took the bytes, and the model may or may not have looked.
 
+A session is `stale` when no turn has sent a heartbeat for three heartbeat cadences. Each
+session row says what a message to such a session meets. `processTracked` is true when ACC
+knows the client process. A dead process makes the session `offline`, so a stale session with
+a tracked process is idle. `liveDelivery` is true when the session has a live delivery
+binding, and `liveLeaseCurrent` says whether the binding's lease is still valid. A stale
+session wakes on send when the lease is valid, or when its adapter can verify the receiver
+again: the router does that for a lapsed lease before it offers. The text line counts stale
+sessions by that result:
+`5 live (2 idle, wake on send; 1 idle until next turn; 1 idle, inbox only)`. `not answering`
+is kept for a stale session whose process ACC does not know.
+
 A participant with no open session is left out, unless messages still wait for it: queued,
 or offered by a live transport and not yet shown again, so that its next turn would show
 them. A message the next-turn hook already showed does not wait, since nothing will reach the
@@ -373,6 +384,11 @@ Your existing npm or Homebrew command and shell profiles remain unchanged.
 An older consent that covered service start receives one expanded choice for the download.
 An accepted or declined answer persists. To change a declined answer, use
 `acc install --adapter codex --delivery actionable` (or `all` for that policy).
+Installing the Antigravity adapter always adds one prefix rule for ACC's wrapper to
+`~/.gemini/antigravity-cli/settings.json`, so ACC's commands run there without an approval
+prompt; nothing asks about it and the delivery policy does not change it. Uninstall removes
+exactly that rule. See
+[Antigravity CLI command approval](CONFIGURATION.md#antigravity-cli-command-approval).
 Explicit `--delivery actionable|all` also approves a required download on supported clients.
 Dry runs, delivery off, doctor, automatic refresh, and message delivery do not download
 Codex or start its service. Uninstall does not remove Codex or stop the shared vendor daemon.

package/docs/CONFIGURATION.md

@@ -131,8 +131,9 @@ The allowed values are `off`, `actionable`, and `all`; the default is `off`. Thi
 does not belong in `acc.workspace.json`, where a pull request could opt someone else into
 spending a turn. It also cannot create a capability. Every adapter reads live-delivery
 consent from this installation record, and only from it. Exact-version evidence governs
-ordinary hook features. Claude Code live delivery separately requires macOS arm64, version
-2.1.282 or newer, and a current feature probe before installation applies the requested
+ordinary hook features. Claude Code live delivery separately requires version 2.1.282 or
+newer on macOS or Linux (on native Windows its inbox is a named pipe, so delivery stays
+next-turn), and a current feature probe before installation applies the requested
 policy. If those install-time checks fail, effective policy remains `off` and the installer
 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
@@ -146,7 +147,7 @@ each wake for your approval unless its `crossSessionInbound` setting is `accept`
 never overrides them. See
 [held or dropped wakes](TROUBLESHOOTING.md#a-claude-code-session-holds-or-drops-acc-wakes).
 
-Codex LocalDaemon delivery separately requires macOS arm64, Codex 0.152.1 or newer, a
+Codex LocalDaemon delivery separately requires Codex 0.152.1 or newer, a
 current feature probe, and exact thread, canonical cwd, process, version and protocol
 checks. On Codex 0.154.0 or newer, explicit complete setup can download a missing matching
 standalone package and prepare a definitely absent service. The setup choice names the
@@ -160,15 +161,47 @@ Unavailable or ineligible sessions retain durable inbox fallback. Use
 ### Codex outgoing permissions
 
 Receiving a native message and sending from the agent's sandbox are separate operations.
-On Codex 0.153.4 or newer on macOS arm64, live opt-in also configures outgoing access
+On Codex 0.153.4 or newer, live opt-in also configures outgoing access
 for default workspace permissions. This happens even when the daemon is not yet available.
 Installation, its preview, and the interactive consent question disclose this change.
 
 ACC selects a permission profile named `acc-workspace`, extending `:workspace`. It grants
-write access to the ACC state directory and allows only the local ACC channel directory
-(`/tmp/acc-ch-<uid>`) and the Codex home control socket. The profile enables networking
-through `features.network_proxy = true`, with no external domains allowed. The proxy and
-socket grants must stay together: enabling networking without the proxy changes its scope.
+write access to the ACC state directory and allows only the Unix sockets ACC delivers to.
+Each receiving adapter declares its own, and the profile lists all of them even when an
+install names Codex alone:
+
+| Receiver | Allowed path |
+|---|---|
+| Codex | the control socket, `<CODEX_HOME>/app-server-control/app-server-control.sock` |
+| Antigravity CLI relay | the ACC channel directory, `/tmp/acc-ch-<uid>` on macOS |
+| Claude Code inbox | `/tmp/cc-socks`, `/tmp/cc-socks-<uid>`, `$XDG_RUNTIME_DIR/cc-socks` or else `$CLAUDE_CODE_TMPDIR/cc-socks` when set, `/run/user/<uid>/cc-socks` on Linux, and the directory of every Claude Code inbox ACC has bound on this machine |
+
+ACC writes each path with its existing parent resolved, so on macOS the entries read
+`/private/tmp/...`. Codex resolves a granted path only if it exists when Codex builds the
+sandbox policy, and the sandbox compares resolved paths: a `/tmp/cc-socks-<uid>` entry
+written before that directory existed never matched. A socket that is a link, such as the
+Codex control socket, keeps its own name.
+
+A command in the Codex sandbox can therefore connect to any of your Claude Code sessions'
+inbox sockets. Claude Code's own inbound settings still decide what a received frame may do,
+and ACC checks Claude Code's session registry before each wake it sends.
+
+The profile enables networking through `features.network_proxy = true`, with no external
+domains allowed. The proxy and socket grants must stay together: enabling networking
+without the proxy changes its scope.
+
+Doctor reports outgoing delivery as configured only while the profile allows every socket
+above. A profile that ACC 0.8.0 or 0.8.1 wrote lacks the Claude Code inbox directories;
+doctor names the missing paths and `acc install --adapter codex`. That command and
+`acc update` rewrite ACC's own profile under the recorded delivery policy, `off` included.
+Start a new Codex session afterwards.
+
+The environment variables above are read from the process that runs `acc install` or
+`acc doctor`. A Claude Code session started with its own `CLAUDE_CODE_TMPDIR` or
+`XDG_RUNTIME_DIR` binds its inbox elsewhere. ACC learns that directory when its hooks first
+bind the session, from its own endpoint record. From then on doctor names the directory
+until `acc install --adapter codex` or `acc update` adds it. Only a directory named as Claude
+Code names its inboxes, `cc-socks` or `cc-socks-<uid>`, is taken from a record.
 
 An existing legacy workspace-write configuration is migrated only when its sole writable
 root is ACC's state directory. Custom permission/configuration profiles, additional roots,
@@ -184,6 +217,38 @@ generated permission component is unchanged.
 If any component was edited or another setting depends on it, ACC preserves the entire
 bundle and reports it for review. Plugin registration can still be removed independently.
 
+### Antigravity CLI command approval
+
+Antigravity CLI asks for approval before each shell command, ACC's included. A session that
+live delivery wakes while you are away would therefore stop at the agent's first ACC command,
+and the peer would get no answer until someone approved it. So when `acc install` installs
+the Antigravity adapter, it always adds one rule to the client's own settings:
+
+```text
+~/.gemini/antigravity-cli/settings.json
+  permissions.allow: command(<home>/.gemini/config/acc/acc-cli.sh)
+```
+
+A one-word rule is a prefix: every command that starts with that path runs without asking.
+The agent then runs every ACC command without asking you, including one a peer's message
+prompts; every other command still asks. Install does not ask about the rule, and the
+delivery policy does not change it: it is part of ACC's Antigravity integration, as its hooks
+are.
+
+ACC keeps every other key and rule in the file, leaves a rule you already had as yours, and
+records what it added in its own data home. `acc uninstall` removes every copy of that rule (one
+in the same words cannot be told from ACC's), and a
+container or file ACC created only if nothing else is in it. A rule removed by hand comes back
+at the next `acc install` or automatic refresh; uninstall is what keeps it out. A file that is
+not valid JSON, or whose `permissions.allow` is not a list, is left as it is and reported. The
+client reads the file when it starts, so restart `agy` after install.
+
+The rule matches only a command whose first word is the path without quotes, so ACC's skill
+for this client writes the path without quotes. When your home path contains a space or a
+shell metacharacter, the path needs quotes, no rule can match it, and ACC adds none.
+`acc doctor` reports the rule as present, absent, or unable to apply, and asks for
+`acc install --adapter antigravity` when ACC's rule is missing.
+
 ## Override local paths and identity
 
 Nothing in `acc.workspace.json` says where state is stored, and nothing there can — that is

package/docs/GETTING_STARTED.md

@@ -43,7 +43,7 @@ session after that review; changed hook definitions may require trust again.
 
 For Codex live delivery, follow the outgoing-permission and local-service instructions
 from install/doctor, then start a new session. Default workspace permissions can be
-configured automatically on Codex 0.153.4 or newer on macOS arm64. Custom settings are
+configured automatically on Codex 0.153.4 or newer. Custom settings are
 preserved; see [outgoing permissions](CONFIGURATION.md#codex-outgoing-permissions).
 With legacy sandbox settings, the named ACC state directory must also be in
 `sandbox_workspace_write.writable_roots` in the config the installer identifies.
@@ -58,7 +58,7 @@ hooks wherever the client is at or after a captured version.
 An interactive install asks one default-No question for all selected clients that need a
 choice. Use `--delivery actionable|all` for explicit noninteractive consent. Use
 `--delivery off` to disable incoming automatic requests. A dry run does not ask, write
-configuration, download Codex, or start a service. On macOS arm64 with Codex 0.154.0 or newer,
+configuration, download Codex, or start a service. On macOS or Linux with Codex 0.154.0 or newer,
 the choice includes downloading a missing standalone package from OpenAI. ACC selects the
 matching version and keeps your existing npm or Homebrew command and shell profiles.
 When supported Codex service preparation succeeds, it
@@ -150,7 +150,10 @@ infrastructure, recorded opt-in, and a verified session. Supported explicit setu
 prepare a missing service. Start the client with your normal command. A loaded daemon thread can receive
 messages after its terminal exits. Antigravity CLI 1.2.7 and later has one too: with delivery enabled,
 ACC's context asks the agent to start a relay from its own shell, up to three times while
-none is running, and you approve that command at the client's prompt.
+none is running, and you approve that command at the client's prompt. Antigravity also asks
+before each shell command, so install adds a rule that lets ACC's own commands run without
+that prompt, and a woken session can answer while you are away; see
+[Antigravity CLI command approval](CONFIGURATION.md#antigravity-cli-command-approval).
 [Capabilities](CAPABILITIES.md) explains policy, versions and fallback.
 
 Delivery evidence is deliberately narrow: `queued -> offered -> retrieved -> acknowledged`.

package/docs/HOW_IT_WORKS.md

@@ -123,7 +123,9 @@ All recipients have the same durable record, but adapters expose different accel
   endpoint exists only in the agent's own shell, so ACC's context asks the agent once per
   conversation to start a relay; the user approves that command. The relay keeps the endpoint
   in memory, wakes an idle session with a fenced peer message, holds one for a busy session,
-  and ends with the client. It is experimental, off by default, and can spend tokens.
+  and ends with the client. It is experimental, off by default, and can spend tokens. The
+  woken agent's ACC commands run without the client's approval prompt because install adds
+  one allow rule for ACC's wrapper.
 
 Grok, generic MCP, unsupported versions and uncaptured platforms use inbox polling.
 [Capabilities](CAPABILITIES.md) lists evidence and fallback.

package/docs/SECURITY_MODEL.md

@@ -94,12 +94,22 @@ user's: a session in `bypassPermissions` mode holds each wake for approval unles
 `crossSessionInbound` is `accept`, and `refuse` drops wakes.
 
 On captured Codex/macOS configurations, live opt-in also grants outgoing access to ACC's
-state and local Unix sockets through a deny-by-default network proxy. Custom permission
+state and local Unix sockets through a deny-by-default network proxy. The sockets are the
+ones ACC delivers to, which include the directories where Claude Code binds each session's
+inbox: a command in the Codex sandbox can connect to those sockets, and Claude Code's own
+inbound settings decide what a received frame may do. Custom permission
 policies remain user-owned. Selection, proxy and grants are restored together only while
 unchanged; edited or newly referenced settings remain intact. See
 [Codex outgoing permissions](CONFIGURATION.md#codex-outgoing-permissions). Configuration
 readiness does not prove that an active session's overrides permit a live offer.
 
+Antigravity CLI asks before each shell command. Installing its adapter adds one prefix rule
+to that client's `permissions.allow`, for ACC's own wrapper path only. The agent then runs
+every ACC command without a prompt, including one that a peer's message prompts. Every other
+command still asks. ACC records the one rule it added and uninstall removes only that rule.
+It never writes a settings file that it cannot parse. See
+[Antigravity CLI command approval](CONFIGURATION.md#antigravity-cli-command-approval).
+
 ## Claims
 
 CLI claims default to advisory. Guarded enforcement must be requested explicitly and
@@ -175,6 +185,7 @@ caller chooses to send. The sender remains responsible for that content.
 | Symlink or traversal escapes a managed root | Per-segment containment, no-follow reads, closed config schema | Host filesystem compromise is out of scope |
 | Claim denial of service | Leases, visible owner, explicit authority release | Deliberate abuse by a trusted local peer is social |
 | Installer removes user configuration | Content-hashed ownership and byte comparison | User must remove modified leftovers manually |
+| Peer message leads an Antigravity agent to run ACC commands unasked | Allow rule scoped to ACC's wrapper; every other command still asks; uninstall removes it | A peer can still prompt ACC actions, such as a reply or a claim, that nobody approves one by one |
 | False delivery claim | Record-first order, transport-owned `offered`, recipient-owned retrieval/ack, mutation tests | Crash after offer before commit can cause duplicate display |
 | Native endpoint leaks | Ephemeral opaque reference, user-only local endpoint, status redaction | Same-user local processes are outside the trust boundary |
 | MCP client impersonates another session | Identity fixed by launch env, closed tool schemas | A compromised launch config already controls that client |

package/docs/TROUBLESHOOTING.md

@@ -138,8 +138,16 @@ client-owned hook and trust review.
 If a reply stays queued with `transport_permission_denied`, the sender's permissions
 blocked local transport. This is distinct from an unavailable recipient. The message was
 recorded successfully; the error does not mean it was read or acknowledged.
-On Codex 0.153.4 or newer on macOS arm64, rerun `acc install --adapter codex` with existing
+On Codex 0.153.4 or newer, rerun `acc install --adapter codex` with existing
 live consent. Add `--delivery actionable` when new consent is required, then start a new session.
+With ACC 0.8.0 or 0.8.1, every live offer from a Codex session to Claude Code failed this way:
+the Codex profile did not allow Claude Code's inbox directories, and doctor still reported it
+configured. Doctor now names the missing paths. `acc install --adapter codex` or `acc update`
+rewrites the profile; start a new Codex session so it runs under the new one.
+A Claude Code session started with its own `CLAUDE_CODE_TMPDIR` or `XDG_RUNTIME_DIR` binds its
+inbox outside the directories your shell's environment implies. After ACC first binds that
+session, doctor names its directory. Run `acc install --adapter codex` again, then start a new
+Codex session.
 Doctor's `outgoingDelivery` reports the installed permission configuration separately
 from `nativeDelivery.runtime`: an active receiving channel does not establish outgoing
 access. Custom policies and active-session overrides remain unverified; inspect the config
@@ -301,10 +309,11 @@ agy -p "/skills" --output-format json
 
 An agent that receives a peer message in print mode (`agy -p`) cannot answer it on its own.
 It forms the right `acc reply` command from the skill, and print mode denies every command
-because it cannot ask for approval; the client says so on stderr. The TUI asks instead.
-ACC does not grant itself that permission. To let headless agents answer, allow the ACC
-command yourself under `permissions.allow` in the client's settings, in the `command(...)`
-form its message names.
+because it cannot ask for approval; the client says so on stderr and names
+`permissions.allow` in its settings. The TUI asks instead. The one rule ACC's install adds
+there is described in
+[Antigravity CLI command approval](CONFIGURATION.md#antigravity-cli-command-approval); it was
+captured in the TUI, and print mode with it has not been captured.
 
 ## Antigravity never wakes while idle
 
@@ -322,6 +331,24 @@ Live delivery needs four things, and `acc doctor` shows each:
 active. A relay ends with its client; nothing is left running after the TUI exits or after
 `acc uninstall`.
 
+## Antigravity wakes and never answers
+
+A woken session that stops at an approval prompt answers only once someone approves its
+first ACC command. `acc doctor` prints an `Antigravity CLI inbound:` line with what it found in
+`~/.gemini/antigravity-cli/settings.json`:
+
+- **No rule.** Each ACC command waits for approval. ACC's install writes the rule, so it was
+  removed since or the install did not reach this file: run `acc install --adapter antigravity`,
+  then restart `agy`. Doctor lists this under what to run next.
+- **The rule is present.** The client reads it at startup, so a session started before it was
+  added still asks; restart `agy`. If a prompt still appears, check the command the agent
+  ran: a path in quotes, or a command wrapped in `sh -c`, matches no rule.
+- **The rule cannot apply.** The path to ACC's wrapper contains a space or a shell
+  metacharacter, so it needs quotes, and a quoted first word matches no rule. ACC adds no
+  rule and approvals stay manual.
+- **The file cannot be read.** ACC leaves an invalid `settings.json` as it is. Repair it, then
+  run `acc install --adapter antigravity` again.
+
 ## Grok shows no injected message
 
 Grok discards UserPromptSubmit context. On the observed 1.0.24 client, run public

package/docs/UPGRADING.md

@@ -1,5 +1,44 @@
 # Upgrading to 0.5.0
 
+## From 0.8.x
+
+Update as usual:
+
+```bash
+acc update
+acc version
+acc doctor
+```
+
+The update refreshes every installed integration with its recorded policy. Two of them change
+a client's own settings:
+
+- **Codex.** ACC's permission profile in `~/.codex/config.toml` also allows the Claude Code
+  inbox socket directories, so a Codex session can wake a Claude Code session live. Grants are
+  written in their resolved form, such as `/private/tmp/cc-socks` on macOS. A profile you
+  edited stays yours: doctor then names the missing grants and `acc install --adapter codex`.
+  Start a new Codex session after the update; a session already open keeps its old policy.
+- **Antigravity CLI.** The install adds `command(<wrapper>)` to `permissions.allow` in
+  `~/.gemini/antigravity-cli/settings.json`, and the skill calls the wrapper without quotes, so
+  a woken session runs its ACC commands without an approval prompt. Restart `agy`: it reads
+  the file only at startup. `acc uninstall` removes every copy of that rule.
+
+`acc doctor` and `acc status` describe an idle session by what a message sent to it meets
+(`idle, wake on send`, `idle until next turn`, `idle, inbox only`), and each status row carries
+`processTracked`, `liveDelivery` and `liveLeaseCurrent`. This release adds no store event type
+or field, so a store it writes stays readable by 0.8.x.
+
+The installed version performs the download. If `acc update` from 0.8.2 or earlier fails with
+`ETARGET` and `No matching version found` right after a release, npm is answering from a
+package document it cached before the registry listed the release. Run the update so that
+npm asks the registry again:
+
+```bash
+npm_config_prefer_online=true acc update
+```
+
+From 0.8.3, the download does this itself.
+
 ## From 0.7.x
 
 Claude Code live delivery wakes each session through the inbox socket that Claude Code opens
@@ -165,7 +204,7 @@ keeps holding activation across an uninstall until it exits.
 
 ## Confirmed client service maintenance
 
-On macOS arm64, `acc update` can ask once to restart a verified Codex service that holds a
+`acc update` can ask once to restart a verified Codex service that holds a
 native binding blocking activation, or that is serving a version outside the captured
 native-delivery contract. A serving version that satisfies that contract is left alone,
 even when the installed CLI has moved to a newer build. The captured maintenance contract

package/node_modules/@agents-can-communicate/adapter-antigravity/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agents-can-communicate/adapter-antigravity",
-  "version": "0.8.1",
+  "version": "0.8.3",
   "private": true,
   "type": "module",
   "exports": {

package/node_modules/@agents-can-communicate/adapter-antigravity/plugin/plugin.json

@@ -1,5 +1,5 @@
 {
   "name": "acc",
-  "version": "0.8.1",
+  "version": "0.8.3",
   "description": "Coordinate this Antigravity CLI session with other AI agent sessions working in the same workspace."
 }

package/node_modules/@agents-can-communicate/adapter-antigravity/plugin/skills/acc/SKILL.md

@@ -41,6 +41,13 @@ work. An MCP connection can have a different participant from the hook session;
 use inbox/reply only for the participant the message addresses. Do not borrow a
 peer's ID, read runtime bindings, or improvise credentials.
 
+### Run each command as written
+
+Start every ACC command with `{{ACC}}` exactly as this skill writes it: add no
+quotes around it and no `sh -c` wrapper. Antigravity CLI decides from a command's
+first word whether it needs approval, and the rule that lets ACC commands run
+without a prompt matches only that form.
+
 ## Start shared work once
 
 After understanding the request, publish one concise intent:

package/node_modules/@agents-can-communicate/adapter-antigravity/src/adapter.mjs

@@ -1,4 +1,4 @@
-import { defineAdapter, projectContext, projectContextResult }
+import { channelSocketDirectory, defineAdapter, projectContext, projectContextResult }
   from "@agents-can-communicate/adapter-sdk";
 import certification from "../certification.json" with { type: "json" };
 
@@ -82,6 +82,8 @@ export function createAntigravityAdapter() {
     },
     probeNativeDelivery, planNativeActivation, bindNativeSession, refreshNativeSession,
     offerMessage,
+    // The relay binds in ACC's own channel directory; a sandboxed sender is allowed it.
+    inboundSockets: () => [channelSocketDirectory()],
     deliveryFallback: { diagnostic:
       `Antigravity CLI next-turn and live delivery are certified from ${ANTIGRAVITY_CLI_VERSION} `
       + "onward; live delivery also needs the agent to start ACC's relay once per conversation, "

package/node_modules/@agents-can-communicate/adapter-antigravity/src/allow-rule.mjs

@@ -0,0 +1,204 @@
+import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+import { blankJson, isShellWord, removeIfEmpty, writeForeignJson }
+  from "@agents-can-communicate/adapter-sdk";
+
+/**
+ * The one allow rule ACC may add to Antigravity CLI's settings, with consent.
+ *
+ * Antigravity CLI asks before every shell command. On 1.2.12 a live push woke an
+ * idle session and its first ACC command waited at an approval prompt with
+ * nobody there, so the peer never got an answer (issue #214). A rule under
+ * `permissions.allow` removes the prompt. What 1.2.12 was captured doing:
+ *
+ * - The file is `~/.gemini/antigravity-cli/settings.json`, read once at startup.
+ *   `~/.gemini/settings.json` belongs to Gemini CLI and is never touched here.
+ * - A one-word rule is a prefix: `command("<wrapper>")` let `<wrapper> help`
+ *   run unasked.
+ * - A command whose first word is quoted matched no rule at all, quoted or not;
+ *   quotes around an argument are fine. So the skill names the wrapper bare,
+ *   and a wrapper path that only stays one word inside quotes cannot be allowed.
+ *
+ * ACC writes the bare form, `command(<wrapper>)`, on every install of this
+ * adapter: the user decided on 2026-09-27 that it is always on, with no
+ * question and no dependence on the delivery policy. The file is still the
+ * operator's: one that does not parse, or whose `permissions.allow` is not a
+ * list, is never rewritten. What ACC added is recorded in its own data home -
+ * the rule and the containers it had to create - and uninstall takes back
+ * exactly that, and always ends the claim, so the same words added later by
+ * the operator stay theirs.
+ */
+export const agySettingsPath = home => path.join(home, ".gemini", "antigravity-cli",
+  "settings.json");
+export const cliWrapperPath = home => path.join(home, ".gemini", "config", "acc", "acc-cli.sh");
+export const accAllowRule = wrapper => `command(${wrapper})`;
+
+// Forms that already allow every command starting with the bare wrapper: the
+// one ACC writes, and the quoted one-word form 1.2.12 was captured matching.
+const allowingForms = wrapper => [accAllowRule(wrapper), `command("${wrapper}")`];
+
+// Beside the `created-*` markers, for the same reason: the installer removes the
+// shim directory before uninstall runs. `acc doctor` passes the state root.
+const claimDir = ({ dataHome, stateRoot, home }) => typeof dataHome === "string" && dataHome !== ""
+  ? path.join(dataHome, "acc", "adapter-antigravity")
+  : typeof stateRoot === "string" && stateRoot !== ""
+    ? path.join(stateRoot, "adapter-antigravity")
+    : path.join(home, ".gemini", "config", "acc");
+const claimPath = (context, file) => path.join(claimDir(context),
+  `allow-rule-${Buffer.from(file).toString("base64url")}`);
+
+const isObject = value => value !== null && typeof value === "object" && !Array.isArray(value);
+
+async function readClaim(file) {
+  try {
+    const claim = JSON.parse(await readFile(file, "utf8"));
+    return typeof claim?.rule === "string" ? claim : null;
+  } catch {
+    return null;
+  }
+}
+
+/** The settings as the client would read them, or why ACC must not edit them. */
+async function readSettings(file) {
+  let text;
+  try {
+    text = await readFile(file, "utf8");
+  } catch (error) {
+    if (error.code === "ENOENT") return { state: "missing", value: {}, allow: [] };
+    return { state: "unreadable", reason: `could not be read (${error.code ?? error.message})` };
+  }
+  let value;
+  try {
+    value = JSON.parse(text);
+  } catch {
+    return { state: "unreadable", reason: "is not valid JSON" };
+  }
+  if (!isObject(value)) return { state: "unreadable", reason: "does not hold a JSON object" };
+  if (value.permissions !== undefined && !isObject(value.permissions)) {
+    return { state: "unreadable", reason: "has a permissions value that is not an object" };
+  }
+  const allow = value.permissions?.allow;
+  if (allow !== undefined && !Array.isArray(allow)) {
+    return { state: "unreadable", reason: "has a permissions.allow value that is not a list" };
+  }
+  return { state: "read", value, allow: allow ?? [] };
+}
+
+const RESTART = "Antigravity CLI reads it at startup, so a session started before it was "
+  + "added still asks until agy restarts";
+
+/** What the rule's state is on this machine, in words doctor can print. */
+export async function inspectAllowRule(context) {
+  const file = agySettingsPath(context.home);
+  const wrapper = cliWrapperPath(context.home);
+  const rule = accAllowRule(wrapper);
+  const base = { file, wrapper, rule, owned: false };
+  if (!isShellWord(wrapper)) {
+    return { ...base, state: "unmatchable", diagnostic: "each ACC command waits for approval, "
+      + "so a live wake stops at the agent's first ACC command until someone answers the "
+      + `approval prompt. No allow rule can remove it here: the wrapper ${wrapper} stays one `
+      + "shell word only inside quotes, and Antigravity CLI matches no rule against a command "
+      + "whose first word is quoted. ACC adds the prefix rule to permissions.allow in "
+      + `${file} when the wrapper path holds only letters, digits and . _ - /` };
+  }
+  const settings = await readSettings(file);
+  if (settings.state === "unreadable") {
+    return { ...base, state: "unreadable", diagnostic: `${file} ${settings.reason}, so ACC `
+      + "leaves it as it is and cannot tell whether ACC commands wait for approval; a live "
+      + "wake stops at the agent's first ACC command while they do. Repair the file, then run "
+      + `acc install --adapter antigravity to add ${rule} to permissions.allow` };
+  }
+  const matched = settings.allow.find(entry => allowingForms(wrapper).includes(entry));
+  if (matched !== undefined) {
+    const claim = await readClaim(claimPath(context, file));
+    const owned = claim?.rule === matched;
+    return { ...base, state: "allowed", owned, diagnostic: "ACC commands run without an "
+      + `approval prompt: permissions.allow in ${file} holds ${matched}`
+      + `${owned ? ", added by ACC" : ""}. ${RESTART}` };
+  }
+  // Every install writes the rule, so its absence means one did not run here, or
+  // the rule was taken out since.
+  return { ...base, state: "prompts",
+    diagnostic: "each ACC command waits for approval, so a live wake stops at the agent's "
+      + "first ACC command until someone answers the approval prompt. ACC's install adds "
+      + `${rule} to permissions.allow in ${file}, and it is not there: run acc install `
+      + "--adapter antigravity, then restart agy" };
+}
+
+async function addRule(context, found) {
+  const settings = await readSettings(found.file);
+  const claimFile = claimPath(context, found.file);
+  // Only what this write creates. A file or container that is already there is
+  // the operator's as far as ACC can tell: one ACC made earlier cannot be told
+  // from one they put in its place, and carrying the old flags over deleted
+  // their file at uninstall (review of #218). The cost is an empty container
+  // ACC once made staying after uninstall, never the operator's file going.
+  const created = {
+    file: settings.state === "missing",
+    permissions: settings.value.permissions === undefined,
+    allow: settings.value.permissions?.allow === undefined,
+  };
+  // The claim first: a crash between the two leaves a claim with no rule, which
+  // uninstall drops, rather than a rule nobody can tell is ACC's.
+  await mkdir(path.dirname(claimFile), { recursive: true });
+  await writeFile(claimFile, `${JSON.stringify({ file: found.file, rule: found.rule,
+    created })}\n`);
+  await writeForeignJson(found.file, { ...settings.value, permissions: {
+    ...settings.value.permissions, allow: [...settings.allow, found.rule] } },
+  { readFile, writeFile, mkdir });
+}
+
+/**
+ * Take back the rule ACC recorded adding, and the containers it created if they
+ * are empty. Every copy of it goes: one in the same words cannot be told from
+ * ACC's, and the client itself has duplicated grants across reloads, so taking
+ * one back left ACC commands running unasked after uninstall (review of #218).
+ * Anything else in the file stays, and a rule the operator had before ACC came
+ * was never claimed.
+ */
+export async function withdrawAllowRule(context) {
+  const file = agySettingsPath(context.home);
+  const claimFile = claimPath(context, file);
+  const claim = await readClaim(claimFile);
+  if (claim === null) return { changes: [], diagnostics: [], needsAction: [] };
+  const settings = await readSettings(file);
+  if (settings.state === "unreadable") {
+    // Kept, so the next install or uninstall can finish once the file reads.
+    return { changes: [], diagnostics: [], needsAction: [`${file} ${settings.reason}; ACC `
+      + `left it as it is and still has to remove its ${claim.rule} from permissions.allow`] };
+  }
+  if (!settings.allow.includes(claim.rule)) {
+    await rm(claimFile, { force: true });
+    return { changes: [], diagnostics: [], needsAction: [] };
+  }
+  const permissions = { ...settings.value.permissions,
+    allow: settings.allow.filter(rule => rule !== claim.rule) };
+  if (claim.created?.allow === true && permissions.allow.length === 0) delete permissions.allow;
+  const next = { ...settings.value, permissions };
+  if (claim.created?.permissions === true && Object.keys(permissions).length === 0) {
+    delete next.permissions;
+  }
+  await writeForeignJson(file, next, { readFile, writeFile, mkdir });
+  if (claim.created?.file === true) {
+    await removeIfEmpty(file, { readFile, rm, isEmpty: blankJson() });
+  }
+  await rm(claimFile, { force: true });
+  return { changes: [file], diagnostics: [`removed ACC's ${claim.rule} from ${file}`],
+    needsAction: [] };
+}
+
+/** Put ACC's rule in place, at every install. */
+export async function ensureAllowRule(context) {
+  const found = await inspectAllowRule(context);
+  if (found.state === "unmatchable" || found.state === "unreadable") {
+    return { changes: [], diagnostics: [found.diagnostic], needsAction: [found.diagnostic] };
+  }
+  if (found.state === "allowed") {
+    return { changes: [], diagnostics: [found.diagnostic], needsAction: [] };
+  }
+  await addRule(context, found);
+  return { changes: [found.file], needsAction: [], diagnostics: [`added ${found.rule} to `
+    + `permissions.allow in ${found.file}: ACC commands run without an approval prompt in `
+    + "Antigravity sessions started from now on; restart agy for a session already open"] };
+}