agents-can-communicate 0.5.10 → 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
 

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/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.
 

package/docs/TROUBLESHOOTING.md

@@ -214,6 +214,78 @@ trusted` and keeps going, and the default mode has no write or shell tool to gua
 guard never fires and the mode you passed appears to have been ignored. Trust the folder,
 or start the session somewhere trusted.
 
+## Antigravity is installed and nothing happens
+
+The most likely cause is that the session has no open workspace. Antigravity CLI gives its
+hooks a project directory only through `workspacePaths`, and that array is empty unless the
+session has one. The interactive TUI started in a project directory has one; a print-mode
+`agy -p "..."` started in the same directory does not. The
+hook then has no workspace to join, fails open as every ACC hook must, and this client shows
+no hook output, so nothing anywhere says why.
+
+Open the project as an Antigravity workspace, or pass it explicitly:
+
+```
+agy -p "..." --add-dir /path/to/project
+```
+
+The first TUI session in a folder you trusted at that same launch has no workspace either,
+even with `--add-dir`; start the TUI again once the folder is trusted.
+
+`acc doctor` names this state. Nothing else in the payload can substitute for it:
+`transcriptPath` and `artifactDirectoryPath` both point inside the client's own
+per-conversation directory, and the hook process does not inherit the directory the client
+was started in.
+
+If the session does have a workspace and ACC is still absent, check that the registration
+actually loaded rather than that the file exists:
+
+```
+agy -p "/hooks" --output-format json
+```
+
+This client accepts a hook configuration it will not load and reports nothing. A file on
+disk is not a registration: the Gemini CLI hook shape loads nothing here, an unsupported
+event name is dropped out of an otherwise valid namespace, and one top-level key that is not
+an integration namespace drops the whole file. The command above is the only answer that
+counts.
+
+The agent may see two ACC skills: `acc:acc`, which `acc install` puts there, and
+`agents-can-communicate:acc`. The second is this client's own copy of ACC's Gemini CLI
+extension, made on its first authenticated run into `~/.gemini/antigravity-cli/plugins/`. Its
+skill loads, but none of its hooks do, and every command in it runs the Gemini CLI extension's
+shim - so it works only while Gemini CLI is wired. `acc:acc` is the one to rely on; check what
+the client actually loaded with:
+
+```
+agy -p "/skills" --output-format json
+```
+
+`agy plugin list` is not that check: it lists only plugins installed through
+`agy plugin install`, and reports none while the imported skill above is loaded.
+
+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.
+
+## Antigravity never wakes while idle
+
+Live delivery needs four things, and `acc doctor` shows each:
+
+- the live policy is on: `acc install --adapter antigravity --delivery actionable` (or `all`);
+- the session is interactive - print mode ends with its turn and never runs a relay;
+- the session attached to ACC at all (see the section above);
+- the agent started the relay. ACC's context asks once per conversation; if the command was
+  declined, or never approved at the permission prompt, nothing asks again. Ask the agent to
+  run `sh "~/.gemini/config/acc/acc-relay.sh" start`, or start a new conversation.
+
+`acc doctor` reports how many relays are running and, per session, whether a live transport is
+active. A relay ends with its client; nothing is left running after the TUI exits or after
+`acc uninstall`.
+
 ## Grok shows no injected message
 
 Grok discards UserPromptSubmit context. On the observed 1.0.24 client, run public