agents-can-communicate 0.5.9 → 0.6.0

package/README.md

@@ -88,7 +88,8 @@ context; it cannot recover details that were never saved.
 
 ## Client support
 
-Integrations are available for **Claude Code, Codex, Gemini CLI, Grok, and Kimi Code**. Other
+Integrations are available for **Antigravity CLI, Claude Code, Codex, Gemini CLI, Grok, and
+Kimi Code**. Other
 clients can connect through [MCP](docs/MCP.md) with their own configuration and coordination
 instructions.
 

package/bin/acc-antigravity-relay.mjs

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { fileURLToPath } from "node:url";
+import { invokedDirectly, runEntry } from "@agents-can-communicate/cli/managed-entry";
+
+if (invokedDirectly(import.meta.url)) await runEntry({
+  kind: "acc-antigravity-relay", packageRoot: fileURLToPath(new URL("..", import.meta.url)),
+});

package/bin/entrypoints/acc-antigravity-relay.mjs

@@ -0,0 +1,116 @@
+#!/usr/bin/env node
+// The relay the agent starts: `start` in its tool shell, `run` detached from it.
+// Fails open everywhere - `start` prints one line and exits 0; `run` answers its
+// ready line and exits quietly when anything it needs is missing.
+import { execFile } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import { appendFile } from "node:fs/promises";
+import path from "node:path";
+
+import { agentApiCommand, createAgentApi } from "@agents-can-communicate/adapter-antigravity/agentapi";
+import { createRelay } from "@agents-can-communicate/adapter-antigravity/relay";
+import { listRegistrations, newRelayId, relayDir } from "@agents-can-communicate/adapter-antigravity/relay-endpoint";
+import { findConversation, spawnRelay, startRelay } from "@agents-can-communicate/adapter-antigravity/relay-start";
+import { loadSessionBinding } from "@agents-can-communicate/adapter-sdk";
+import { platformDataHome } from "@agents-can-communicate/cli";
+import { createCoordinationService } from "@agents-can-communicate/core";
+import { resolveClientPid } from "@agents-can-communicate/hook-runner/client-pid";
+import { readProcessTable } from "@agents-can-communicate/hook-runner/process-table";
+import { readInstalledLivePolicy } from "@agents-can-communicate/installer";
+import { createId } from "@agents-can-communicate/protocol";
+import { openFilesystemStore } from "@agents-can-communicate/storage-filesystem";
+
+import { activateAntigravityRelay } from "./antigravity-relay-binding.mjs";
+
+const clock = { now: () => new Date().toISOString() };
+const ids = { next: kind => createId(kind, randomBytes) };
+const alive = pid => { try { process.kill(pid, 0); return true; } catch { return false; } };
+const READY_MS = 10_000;
+
+const argvOf = pid => new Promise(resolve => execFile("ps", ["-o", "args=", "-p", String(pid)],
+  { timeout: 1_000 }, (_error, out) => resolve(String(out ?? "").trim().split(/\s+/).filter(Boolean))));
+
+// Through the launcher that ran `start`, never this module directly: an entry
+// module does not run itself, and under the managed runtime the launcher takes
+// the lease that keeps this generation installed for as long as the relay lives.
+const spawnRun = ({ env, payload }) => spawnRelay({ command: process.execPath,
+  args: [process.argv[1], "run"], env, payload, readyMs: READY_MS });
+
+async function start() {
+  const dataHome = platformDataHome({ platform: process.platform, env: process.env });
+  const line = await startRelay({ env: process.env, pid: process.pid,
+    readTable: () => readProcessTable(), argvOf,
+    resolveAgyPid: (table, from) => resolveClientPid({ table, from, command: "agy" }),
+    readPolicy: () => readInstalledLivePolicy({ dataHome, adapterId: "antigravity" }),
+    findConversation: ({ conversationId, agyPid }) => findConversation({ dataHome, conversationId, agyPid }),
+    liveRelayFor: async ({ runtimeDir, conversationId }) => (await listRegistrations({ runtimeDir }))
+      .some(record => record.conversationId === conversationId && alive(record.relayPid)),
+    spawnRun });
+  process.stdout.write(`${line}\n`);
+}
+
+async function readPayload() {
+  let text = "";
+  for await (const chunk of process.stdin) text += chunk;
+  return JSON.parse(text);
+}
+
+// Event names, message ids and closed reason codes only: never a body, the
+// token, the address or the nonce.
+const logger = file => entry => appendFile(file, `${JSON.stringify({ at: clock.now(), ...entry })}\n`,
+  { mode: 0o600 }).catch(() => {});
+
+async function run() {
+  const ready = result => process.stdout.write(`${JSON.stringify(result)}\n`);
+  const payload = await readPayload();
+  const { runtimeDir, conversationId, agyPid } = payload;
+  const dataHome = platformDataHome({ platform: process.platform, env: process.env });
+  const store = await openFilesystemStore({ root: runtimeDir, clock, ids, workspaceId: payload.workspaceId });
+  const service = createCoordinationService({ store, clock, ids });
+  const current = () => loadSessionBinding({ runtimeDir, harnessSessionId: conversationId });
+  const bound = await current();
+  if (bound === null || bound.clientPid !== agyPid) {
+    ready({ ok: false, reason: "no ACC session for this conversation" });
+    return;
+  }
+  const endpointId = newRelayId();
+  const relay = createRelay({ runtimeDir, conversationId, agyPid, isAlive: alive, endpointId,
+    clientVersion: bound.clientVersion,
+    observe: logger(path.join(relayDir(runtimeDir), `${endpointId}.log`)),
+    api: createAgentApi({ endpoint: payload, baseEnv: process.env,
+      command: agentApiCommand(process.env) }),
+    // The conversation can reopen under a new ACC generation while this relay
+    // keeps serving it, so renew whichever binding is current, never a copy.
+    refreshBinding: async leaseUntil => {
+      const now = await current();
+      if (now?.clientPid !== agyPid) return;
+      await service.refreshDeliveryBinding({ sessionId: now.accSessionId, generation: now.generation,
+        leaseUntil });
+    },
+    onExit: async () => {
+      const now = await current().catch(() => null);
+      if (now !== null) {
+        await service.clearDeliveryBinding({ sessionId: now.accSessionId, generation: now.generation,
+          opaqueEndpointRef: endpointId }).catch(() => {});
+      }
+      process.exit(0);
+    } });
+  await relay.listen();
+  process.on("SIGTERM", () => { relay.close("terminated"); });
+  const activation = await activateAntigravityRelay({ session: { sessionId: bound.accSessionId,
+    generation: bound.generation, clientPid: bound.clientPid, harnessSessionId: conversationId },
+  service, runtimeDir, dataHome }).catch(() => null);
+  if (activation?.state === "active") {
+    ready({ ok: true });
+    return;
+  }
+  ready({ ok: false, reason: activation?.reasonCode ?? "binding was not published" });
+  await relay.close("not_activated");
+}
+
+export async function main() {
+  const [command] = process.argv.slice(2);
+  if (command === "run") await run().catch(() => process.exit(0));
+  else await start().catch(() => process.stdout.write(
+    "ACC: live delivery did not start; peers still reach this conversation at its next turn.\n"));
+}

package/bin/entrypoints/acc-bootstrap.mjs

@@ -7,6 +7,7 @@
 // empty unless ACC_BOOTSTRAP_DEBUG=1 asks for one safe line.
 import { checkNativeBootstrap } from "@agents-can-communicate/installer";
 
+import { createAntigravityAdapter } from "@agents-can-communicate/adapter-antigravity";
 import { createClaudeCodeAdapter } from "@agents-can-communicate/adapter-claude-code";
 import { createCodexAdapter } from "@agents-can-communicate/adapter-codex";
 import { createGeminiCliAdapter } from "@agents-can-communicate/adapter-gemini-cli";
@@ -29,6 +30,9 @@ try {
   const registry = {
     claude_code: createClaudeCodeAdapter, codex: createCodexAdapter,
     gemini_cli: createGeminiCliAdapter, grok: createGrokAdapter, kimi: createKimiAdapter,
+    // No native delivery contract: this reports the client unsupported rather
+    // than unknown, which is a different and more useful thing to read.
+    antigravity: createAntigravityAdapter,
   };
   const adapter = registry[options.adapter]?.();
   if (adapter === undefined) {

package/bin/entrypoints/acc-hook.mjs

@@ -12,6 +12,7 @@ import { createId } from "@agents-can-communicate/protocol";
 import { runHook } from "@agents-can-communicate/hook-runner";
 import { hookEntrypointFor, resolvePinnedGeneration } from "@agents-can-communicate/cli";
 
+import { createAntigravityAdapter } from "@agents-can-communicate/adapter-antigravity";
 import { createClaudeCodeAdapter } from "@agents-can-communicate/adapter-claude-code";
 import { createCodexAdapter } from "@agents-can-communicate/adapter-codex";
 import { createGeminiCliAdapter } from "@agents-can-communicate/adapter-gemini-cli";
@@ -19,6 +20,9 @@ import { createGrokAdapter } from "@agents-can-communicate/adapter-grok";
 import { createKimiAdapter } from "@agents-can-communicate/adapter-kimi";
 
 const adapters = {
+  // Registered like any other client. Its hook commands carry an extra
+  // argument - the event name - because this client's payload has none.
+  antigravity: createAntigravityAdapter(),
   claude_code: createClaudeCodeAdapter(),
   codex: createCodexAdapter(),
   gemini_cli: createGeminiCliAdapter(),
@@ -46,9 +50,9 @@ import { completeHookOutput } from "./hook-output.mjs";
 // a hook that has no pin to look up pays nothing beyond it. Any adapter or
 // payload that will not yield a session id simply has no pin to find, same as
 // today's no-pin behaviour.
-async function harnessSessionIdFor(adapterId, payload) {
+async function harnessSessionIdFor(adapterId, payload, args) {
   try {
-    const event = await adapters[adapterId]?.normalizeHook(payload);
+    const event = await adapters[adapterId]?.normalizeHook(payload, { args });
     return typeof event?.sessionId === "string" ? event.sessionId : null;
   } catch {
     return null;
@@ -71,9 +75,9 @@ async function harnessSessionIdFor(adapterId, payload) {
 // mid-resolution by another hook for the same session, or simply wrong)
 // could say. Unbounded delegation would be a hang, worse than any of the
 // failures this file already falls open from.
-async function delegateToPin({ managerRoot, packageRoot, adapterId, payload, delegated }) {
+async function delegateToPin({ managerRoot, packageRoot, adapterId, payload, args, delegated }) {
   if (delegated || managerRoot === null || packageRoot === null) return false;
-  const harnessSessionId = await harnessSessionIdFor(adapterId, payload);
+  const harnessSessionId = await harnessSessionIdFor(adapterId, payload, args);
   if (harnessSessionId === null) return false;
   const pinned = await resolvePinnedGeneration({ root: managerRoot, harnessSessionId, active: packageRoot });
   if (pinned === null) return false;
@@ -87,7 +91,7 @@ async function delegateToPin({ managerRoot, packageRoot, adapterId, payload, del
 }
 
 export async function main({ managerRoot = null, packageRoot = null, payload, delegated = false } = {}) {
-  const [adapterId] = process.argv.slice(2);
+  const [adapterId, ...args] = process.argv.slice(2);
 
   // A delegating caller already read stdin once for the whole process and
   // hands its parsed payload down; only the outermost call reads it here.
@@ -99,9 +103,9 @@ export async function main({ managerRoot = null, packageRoot = null, payload, de
     }
   }
 
-  if (await delegateToPin({ managerRoot, packageRoot, adapterId, payload, delegated })) return;
+  if (await delegateToPin({ managerRoot, packageRoot, adapterId, payload, args, delegated })) return;
 
-  const result = await runHook({ adapterId, payload, adapters,
+  const result = await runHook({ adapterId, payload, args, adapters,
     runtime: { clock: { now: () => new Date().toISOString() },
       ids: { next: kind => createId(kind, randomBytes) } },
     env: process.env });

package/bin/entrypoints/antigravity-relay-binding.mjs

@@ -0,0 +1,43 @@
+import { createAntigravityAdapter } from "@agents-can-communicate/adapter-antigravity";
+import { loadSessionBinding, storeNativeAttempt } from "@agents-can-communicate/adapter-sdk";
+import { createCoordinationService } from "@agents-can-communicate/core";
+import { establishNativeBinding } from "@agents-can-communicate/hook-runner/native-binding";
+import { withSessionLifecycle } from "@agents-can-communicate/hook-runner/session-lifecycle";
+import { readInstalledLivePolicyState } from "@agents-can-communicate/installer";
+import { openFilesystemStore } from "@agents-can-communicate/storage-filesystem";
+
+// No hook runs when the agent starts a relay mid-turn, and the next
+// PreInvocation can be hours away. The relay publishes its own binding the way
+// the Claude Code Channel does: under the session's lifecycle lock, after
+// rereading ownership, so a queued start never publishes for a replaced or
+// closed session.
+export async function activateAntigravityRelay({ session, service, runtimeDir, dataHome,
+  adapter = createAntigravityAdapter(), deadlineAt = Date.now() + 5_000 }) {
+  if (typeof session.harnessSessionId !== "string") return null;
+  return withSessionLifecycle({ root: runtimeDir, sessionId: session.harnessSessionId,
+    clock: service.clock, deadlineAt }, async () => {
+    const { clock, ids } = service;
+    const store = await openFilesystemStore({ root: runtimeDir, clock, ids,
+      workspaceId: service.store.workspaceId, deadlineAt });
+    const current = createCoordinationService({ store, clock, ids });
+    const binding = await loadSessionBinding({ runtimeDir, harnessSessionId: session.harnessSessionId });
+    if (binding?.accSessionId !== session.sessionId || binding.generation !== session.generation
+      || binding.clientPid !== session.clientPid) return null;
+    const located = await current.locateSession(session.sessionId);
+    if (located?.record.state !== "open" || located.record.generation !== session.generation) return null;
+    const { policy, policyStatus } = await readInstalledLivePolicyState({ dataHome,
+      adapterId: adapter.id });
+    if (policy === "off" || Date.now() >= deadlineAt) return null;
+    const result = await establishNativeBinding({ adapter,
+      event: { kind: "relayReady", sessionId: session.harnessSessionId },
+      hookBinding: binding, clientVersion: binding.clientVersion, platform: binding.platform,
+      livePolicy: policy, service: current, runtimeDir, clock, env: {},
+      timeoutMs: Math.max(1, Math.min(750, deadlineAt - Date.now())) });
+    await storeNativeAttempt({ runtimeDir, harnessSessionId: session.harnessSessionId,
+      accSessionId: session.sessionId, generation: session.generation, deadlineAt,
+      nativeAttempt: { at: clock.now(), event: "relayReady", state: result.state,
+        reasonCode: result.reasonCode, policy, policySource: "installation-record", policyStatus,
+        clientProcess: "identified" } }).catch(() => {});
+    return result;
+  });
+}

package/docs/ADAPTER_AUTHORING.md

@@ -52,6 +52,17 @@ 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.
 
+`continueTurnOutcome({ reason, payload })` is optional. A client whose end-of-turn hook can
+hold a turn open implements it, and the runner's `turnEnd` handler calls it with the projected
+peer context when - and only when - a peer body no invocation has shown yet is waiting. It
+returns `{ stdout, stderr?, exitCode? }` in the client's own continuation shape, and prints
+nothing to let the turn end. `payload` is the raw hook payload handed back unread, so the
+adapter can apply its own ceiling from a counter the client supplies; nothing in core reads it.
+An empty `stdout` records no offer, so the body stays queued for the next invocation. A
+continuation costs the operator a model invocation, which is why an owner header or an
+attention count is never a reason to call it. Antigravity CLI uses it for `Stop`, bounded to
+one continuation per turn by the client's own `executionNum`.
+
 `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
@@ -110,6 +121,20 @@ the false value and can never enable it.
 shape for the installed client. Only an exact passing version/platform match remains true.
 Unreadable, unknown, or mismatched clients degrade every uncertified row to false.
 
+An adapter for a client that ships often may declare a floor per platform:
+
+```js
+certificationFloor: { "darwin-arm64": "1.2.7" },
+```
+
+A stable version at or above the floor, on that platform, is then judged by the floor
+version's evidence for any capability it has no capture of its own for. A later capture
+wins for its own version, capability by capability - a recorded failure turns that
+capability off for that version and leaves the rest on the floor. Earlier versions,
+prereleases and other platforms stay uncertified, and `defineAdapter` refuses a floor
+that names a version with no passing evidence on its platform. Antigravity CLI declares
+one; every other adapter certifies exact versions only.
+
 The backing methods for delivery are `renderContextResult()` for `nextTurn`,
 `offerMessage()` for `livePush`, and `routeReply()` for `replyRoute`.
 
@@ -198,6 +223,13 @@ return normalizedEvent({
 Refuse an unrecognised payload. Inventing a session attaches the wrong one, or a new one
 every hook, and looks like it is working.
 
+`normalizeHook(payload, { args })` also receives the arguments the client's hook command
+carried after the adapter id. Most clients name the event inside the payload and ignore this.
+Antigravity CLI does not send one at all, and its `PreInvocation` and `PostInvocation` hand
+over byte-identical envelopes - so for that client the registered command's own argument is
+the only thing that knows which hook ran, and its install writes the event name into each
+command. `args` is always an array; an adapter that does not need it may take one parameter.
+
 ## Measure response contracts
 
 Measure them. Every client differs, and a wrong shape fails **silently**:
@@ -207,6 +239,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 |
+| Antigravity CLI | no tool event loads, so a deny is unreachable | `{"injectSteps":[{"ephemeralMessage"}]}` from `PreInvocation` |
 | 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 |
 

package/docs/ARCHITECTURE.md

@@ -97,11 +97,13 @@ exposes and whether its lease is current, while recipient policy says whether it
 turn.
 
 Claude Code Channel has installed-client evidence on 2.1.258 and 2.1.260; Codex
-LocalDaemon has it on 0.152.1 and 0.153.4. Both use a captured platform minimum,
+LocalDaemon has it on 0.152.1 and 0.153.4; Antigravity CLI has it on 1.2.7 and later through a relay
+the agent starts in its own shell. All three use a captured platform minimum,
 current probe and exact session handshake. Codex preserves the ordinary client
 launch and verifies its registered thread and workspace; native delivery owns no vendor
-daemon lifecycle. Gemini CLI and Kimi Code have exact-version next-turn evidence only;
-Grok and generic MCP use inbox polling.
+daemon lifecycle. Gemini CLI and Kimi Code have exact-version next-turn evidence only; Grok
+and generic MCP use inbox polling. Antigravity CLI additionally attaches
+a session only where the client reports an open workspace.
 
 ## Storage and workspace identity
 
@@ -115,10 +117,31 @@ its checkout and branch. Runtime state never lands inside those roots; the only
 file ACC writes is an optional `acc.workspace.json` explicitly requested through
 `acc config init`.
 
+Native hooks persist the initial workspace directory and id, keyed by adapter and
+native session id, under the platform data home's `acc/native-workspaces`. This
+record carries routing only, never owner credentials. Subsequent hooks resolve the
+saved directory before loading the workspace-local owner binding; their payload's
+current cwd still resolves relative file targets. A nested repository cannot change
+the room or bypass its claims. A linked worktree of the original repository keeps
+repository-relative claim paths. Room publication is serialized before session
+opening, and the record survives SessionEnd so native conversation resume keeps the
+room. A changed initial workspace identity fails open with a diagnostic instead of
+opening a replacement room. If SessionStart was missed, the first user-turn hook
+establishes the room. A legacy session without this record establishes it on its
+next startup or user-turn hook; its original launch directory cannot be inferred.
+Every bound owner header includes a local `--workspace acc://<reference>` selector.
+The CLI validates the exact named routing record in ACC's own data home, then resolves
+the saved room through the same path as hooks. It does not scan for an owner or infer
+credentials. This also keeps a header usable when Git availability changes between
+the hook and the CLI command. Ordinary project-config validation remains unchanged.
+
 A lone session can remain ephemeral. Durable state materialises when a second live session
 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.
+own CLI arguments and workspace directory, so a peer joining later in the same turn
+does not require reattachment and a changed shell directory cannot silently select another
+workspace. Claude SessionStart also restores this owner header after compaction; it
+does not project peer bodies or advance their receipts.
 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.

package/docs/CAPABILITIES.md

@@ -17,7 +17,8 @@ Capability honesty separates four questions that are easy to collapse:
 4. **Fallback** — what durable path remains when any earlier answer is no?
 
 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.
+unsupported platforms degrade to false, except that an adapter may declare a captured version
+as a floor for later stable releases on the same platform - Antigravity CLI does. 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
@@ -25,34 +26,39 @@ assuming that a newer or differently packaged client behaves like a captured one
 
 ## Certified support
 
-Passing evidence currently ships for these exact versions on `darwin-arm64`:
-
-| Capability | Codex 0.147.0 | Claude Code 2.1.233 | Gemini CLI 0.57.0 | Grok 1.0.13 | Kimi 0.36.1 |
-|---|---:|---:|---:|---:|---:|
-| `lifecycle.sessionStart` | yes | yes | yes | no | yes |
-| `lifecycle.sessionEnd` | yes | yes | yes | no | no |
-| `lifecycle.heartbeat` | no | no | no | no | yes |
-| `context.beforeTurnInjection` | yes | yes | yes | no | yes |
-| `guards.beforeWrite` | yes | yes | yes | no | yes |
-| `guards.beforeShell` | no | yes | yes | no | yes |
-| `delivery.nextTurn` | yes | yes | yes | no | yes |
-| `delivery.livePush` | no | no | no | no | no |
-| `delivery.replyRoute` | no | no | no | no | no |
+Passing evidence currently ships for these exact versions on `darwin-arm64`. Antigravity
+CLI's column also covers every later stable release there: its adapter declares 1.2.7 as a
+certification floor, so a newer version is judged by the 1.2.7 captures until one of its
+own says otherwise.
+
+| Capability | Antigravity 1.2.7 | Codex 0.147.0 | Claude Code 2.1.233 | Gemini CLI 0.57.0 | Grok 1.0.13 | Kimi 0.36.1 |
+|---|---:|---:|---:|---:|---:|---:|
+| `lifecycle.sessionStart` | yes | yes | yes | yes | no | yes |
+| `lifecycle.sessionEnd` | no | yes | yes | yes | no | no |
+| `lifecycle.heartbeat` | no | no | no | no | no | yes |
+| `context.beforeTurnInjection` | yes | yes | yes | yes | no | yes |
+| `guards.beforeWrite` | no | yes | yes | yes | no | yes |
+| `guards.beforeShell` | no | no | yes | yes | no | yes |
+| `delivery.nextTurn` | yes | yes | yes | yes | no | yes |
+| `delivery.livePush` | yes | no | no | no | no | no |
+| `delivery.replyRoute` | no | no | no | no | no | no |
 
 Every other capability in the closed shape defaults to false, including session resume,
 child sessions, startup or safe-point injection, and before-read guards.
 
 The 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.
+0.153.4, Claude Code `livePush` plus `replyRoute` on 2.1.258 and 2.1.260, and
+Antigravity CLI `livePush` on 1.2.7 and later through a relay the agent starts in its own shell.
 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.
+opt-in. Codex and Antigravity CLI reply through `acc reply`; their native `replyRoute` remains false.
 
 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 later stable releases by certification floor. 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; 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. |
 | 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. |

package/docs/CLI.md

@@ -4,7 +4,12 @@ Use `acc` to install and diagnose integrations, or to inspect the same communica
 operations that installed skills use on an agent's behalf. Setup commands are for a
 person; communication commands are the smaller agent-facing vocabulary. Every command
 accepts `--json` and `--cwd <path>`. `--workspace <config>` selects an explicit workspace
-config where supported by the common boundary.
+config where supported by the common boundary. These three global options work before
+or after the command: `acc --cwd /project status` and `acc status --cwd /project`
+select the same workspace. A native hook also supplies `--workspace acc://<reference>`
+to select its saved room directly. This reference is local to ACC's data home, is
+not a network URL, and does not establish session ownership. Ordinary config paths
+retain their existing validation.
 
 <!-- test:command -->
 ```bash
@@ -44,7 +49,15 @@ option value remains data: `--body --help` sends the literal body `--help`.
 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,
+session's pair, a shell-quoted `--cwd`, and its saved `--workspace` room reference.
+Append the complete header even after changing the shell directory. Claude Code also
+restores this header on `SessionStart`, including compaction, without requiring another prompt.
+Native hooks retain the initial room even when later hook payloads have another
+`cwd`, including a nested Git repository. The header continues to name that initial
+directory and room even if Git later becomes available or unavailable. Standalone CLI
+commands without these arguments still discover their workspace from their own cwd;
+the CLI does not guess a native caller's identity.
+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.
@@ -54,7 +67,7 @@ it to peers or child agents. A later hook after a session restart can supply a n
 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
+If the context budget cannot hold the complete header, 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.
 
@@ -69,6 +82,11 @@ Without a pair, mutations and `inbox` fail with exit `2` and
 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.
 
+An explicit session selector absent from the selected workspace produces exit `5`
+with `caller_workspace_mismatch`, rather than a successful empty status. Restore the
+complete header or the manual attachment directory. A supplied generation must also
+match. This diagnostic does not search other workspaces or recover credentials.
+
 ### Presence and intent
 
 ```bash

package/docs/CONCEPTS.md

@@ -24,6 +24,13 @@ scoped to one machine and operating-system user. Git worktrees of one repository
 the same ACC workspace, but their checkout files remain separate. In a plain directory, the
 directory supplies identity unless optional configuration says otherwise. Git is optional.
 
+A native session keeps the room selected at startup. Moving into subdirectories,
+nested repositories, or other checkouts does not move that conversation to another
+room. Sessions launched from the same parent directory therefore stay together as
+their agents work in different child repositories. A separate session launched in
+a child repository selects its own initial room. Compaction and resuming the same
+native conversation retain its original room.
+
 A **participant** is the address for communication. A stable participant id can recover
 messages sent before a restart. A **session** is one current opening of that participant,
 with a generation token preventing an old process from changing its replacement's state.

package/docs/CONFIGURATION.md

@@ -194,6 +194,7 @@ that resolves inside a workspace.
 | `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` | 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_ANTIGRAVITY_HOOKS` | Where `acc install` registers Antigravity CLI hooks. `global`, the default, writes `~/.gemini/config/hooks.json`, which always loads and applies to every Antigravity session on the machine. `workspace` writes `<project>/.agents/hooks.json`, which is scoped to the project the command ran in and loads only while that project is an open Antigravity workspace - in print mode, only when it is passed with `--add-dir`. Any other value is refused by name rather than replaced by the default, and that client is skipped. The two cannot be combined: both files use the namespace `acc`, and a name in both is kept only once |
 | `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 |

package/docs/GETTING_STARTED.md

@@ -132,16 +132,22 @@ Every message is recorded before ACC attempts faster delivery. Every participant
 durable inbox, which is the universal recovery path.
 
 On exact client versions and platforms with captured support, Codex, Claude Code, Gemini
-CLI, and Kimi Code can receive a message at the next normal turn. That does not wake an idle
-session. Grok, generic MCP clients, unknown versions, and unsupported platforms use the
-durable inbox instead.
+CLI, Kimi Code and Antigravity CLI can receive a message at the next normal turn. That does
+not wake an idle session. Grok, generic MCP clients, unknown versions, and unsupported
+platforms use the durable inbox instead.
+
+Antigravity CLI carries one extra condition: its hooks are given a project directory only
+when the session has an open workspace. A session started without one attaches nothing, and
+the client shows no hook output to say so - `acc doctor` names it.
 
 Codex LocalDaemon and Claude Code Channel offer optional native delivery on
 Apple Silicon macOS. They are experimental, can spend tokens, and queue messages
 until a running turn finishes. Codex requires 0.152.1 or newer, LocalDaemon infrastructure,
 recorded opt-in, and a verified session. Supported explicit setup can prepare a missing
 service. Start the client with your normal command. A loaded daemon thread can receive
-messages after its terminal exits.
+messages after its terminal exits. Antigravity CLI 1.2.7 and later has one too: with delivery enabled,
+ACC's context asks the agent once per conversation to start a relay from its own shell, and
+you approve that command at the client's prompt.
 [Capabilities](CAPABILITIES.md) explains policy, versions and fallback.
 
 Delivery evidence is deliberately narrow: `queued -> offered -> retrieved -> acknowledged`.

package/docs/HOW_IT_WORKS.md

@@ -99,7 +99,7 @@ All recipients have the same durable record, but adapters expose different accel
 - **Durable inbox:** universal recovery. `acc inbox` discovers bounded message headers;
   `acc inbox --message <id>` retrieves one complete addressed message after selection
   or compaction.
-- **Next normal turn:** exact captured versions of Codex, Claude Code, Gemini CLI, and Kimi
+- **Next normal turn:** exact captured versions of Codex, Claude Code, Gemini CLI, Antigravity CLI and Kimi
   Code can receive complete attributed peer context when the user next prompts that client.
   This does not wake an idle session.
 - **Optional Claude Code channel:** supported Claude Code versions on Apple Silicon macOS
@@ -115,6 +115,12 @@ All recipients have the same durable record, but adapters expose different accel
   and does not manage the vendor daemon during message delivery. Separately,
   [confirmed update maintenance](UPGRADING.md#confirmed-client-service-maintenance) can restart it.
 
+- **Optional Antigravity CLI relay:** on Apple Silicon macOS with 1.2.7 or later, the session
+  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.
+
 Grok, generic MCP, unsupported versions and uncaptured platforms use inbox polling.
 [Capabilities](CAPABILITIES.md) lists evidence and fallback.