agents-can-communicate 0.1.17 → 0.2.0

package/README.md

@@ -4,171 +4,109 @@
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 [![Node](https://img.shields.io/badge/node-%E2%89%A524-brightgreen.svg)](https://nodejs.org)
 
-**Give every agent session a shared room for coordination. Keep your attention on the
-work.**
+ACC connects independently opened AI sessions so they can discover, ask, answer, acknowledge, and hand off without becoming one managed agent team.
 
-ACC is a local-first coordination layer for the AI agent sessions you already opened. It
-gives them shared presence, intent, claims, messages, and work requests while every
-session keeps its own authority.
+It is a local-first communication layer for sessions you already run. Each session keeps
+its own client, model, checkout, permissions, context, and human direction. ACC supplies a
+shared room with presence, intent, narrow file claims, durable conversation threads, and
+truthful per-recipient receipts. It does not launch, steer, supervise, or terminate agents.
 
-Coordination runs locally on your machine. Raw transcripts stay private. The runtime is
-built entirely on Node's standard library.
+The project uses Node's standard library with **zero runtime dependencies**. Coordination
+state stays in platform app data outside the repository, and ACC never collects raw
+transcripts.
 
-```mermaid
-flowchart TB
-  Y["You<br/>set direction"]
-  A["Agent session A"]
-  B["Agent session B"]
-  C["Agent session C"]
-  R["ACC shared room<br/>presence · intent · claims<br/>messages · work requests"]
-  O["Coordinated work<br/>with shared context"]
-
-  Y --> A
-  Y --> B
-  Y --> C
-  A <--> R
-  B <--> R
-  C <--> R
-  R --> O
-```
-
-## You opened more agents. You became the coordinator.
-
-One session implements. Another writes tests. A third reviews. At first, more agents means
-more work gets done.
+## Stop relaying between windows
 
-Then you start copying context between windows. You warn two agents away from the same
-file. You relay a question, return with the answer, and try to remember which terminal was
-waiting for what. The agents are capable; they need a room they can share.
+One session finds that removing `item.drive` will break another area. A second session is
+working there, but neither client knows the other exists. Without ACC, the warning stops at
+you: copy it to the other window, copy the answer back, and repeat for every question.
 
-ACC gives them that room. Each session stays in its original client, checkout, and trust
-boundary. You still decide when it starts and stops. ACC only supplies the coordination
-that was previously passing through you.
-
-## A handoff the agents carry themselves
-
-One agent finishes building a feature and sees that its final tests still need work. It
-asks the testing agent to take over, including a short summary of what is ready and what
-remains.
+With ACC, the first session sends an attributed question. The second retrieves it, replies
+in the same thread, and thereby acknowledges the original. The first retrieves the answer.
+The message is durable throughout; neither model gains authority over the other.
 
 ```mermaid
 flowchart LR
-  A["Feature agent<br/>finishes its part"] --> B["Requests tests<br/>from the testing agent"]
-  B --> C["ACC keeps the handoff<br/>ready for that agent"]
-  C --> D["Testing agent<br/>completes the work"]
-  D --> E["Result returns<br/>to the feature agent"]
+  A["session A — independently opened"] <--> R["ACC room<br/>presence · messages · receipts · claims"]
+  B["session B — independently opened"] <--> R
+  U["You — direction and authority"] --> A
+  U --> B
 ```
 
-The request stays with the testing agent across terminal restarts. When that agent returns,
-it receives the handoff, completes the tests, and sends the result back. You choose the
-direction and review the outcome; the agents carry the context between them.
+The product's canonical activation event is simple: a second independently opened session
+completes a useful acknowledged interaction without the human copying peer message content.
 
 ## Install
 
-Run these commands in a terminal on each macOS or Linux machine where your agent clients
-run:
+On macOS or Linux with Node 24 or newer:
 
 ```bash
 npm install -g agents-can-communicate
 acc install
 ```
 
-The first command makes `acc` available across the machine. The second finds Codex,
-Claude Code, Gemini CLI, and Kimi Code installations and activates the integrations that
-are available. Codex completes activation after you trust the plugin; `acc doctor` shows
-the current state.
-
-`acc install` names every client setting it activated and how to undo it.
-
-Open or restart your agent client inside a project. Each new session joins that project's
-room automatically. Open another session in the same project and the two can coordinate;
-run `acc status` from the project directory whenever you want to see the room yourself.
-
-ACC stores coordination data in the standard application-data location for your system.
-The defaults are `~/Library/Application Support/acc` on macOS and `~/.local/share/acc` on
-Linux. `XDG_DATA_HOME` relocates the Linux default; `ACC_DATA_HOME` overrides either
-platform, as described in [configuration](docs/CONFIGURATION.md). Project files stay
-unchanged. Git worktrees from one repository share a room, and plain folders receive the
-same coordination experience.
-
-Keep ACC current with `acc update --apply`. It installs the latest release and refreshes
-the client integrations together. `acc doctor` points to that action when their versions
-drift.
-
-Run `acc uninstall` to remove ACC's client integrations. Settings you changed remain
-yours.
-
-## What changes after installation
-
-**Agents know who is around.** Each session can see the other participants, their current
-focus, and the files they have claimed.
+Restart the clients whose hooks were installed; Codex also requires trusting the plugin.
+Then open two sessions in the same repository or plain directory as usual. They remain
+independent and join the same ACC workspace. Use `acc doctor` to see exact versions,
+installation health, and delivery downgrades.
 
-**Parallel work becomes deliberate.** Agents claim shared files before editing. Supported
-client edits respect those claims and identify the participant already working there.
+Runtime state lives in `~/Library/Application Support/acc` on macOS or the XDG data
+directory on Linux. `ACC_DATA_HOME` can override it, but ACC refuses a location inside a
+workspace. Git is optional; worktrees of one repository share awareness.
 
-**Questions and work find their way back.** Requests, decisions, and handoffs stay with
-the intended agent across session restarts, and results return to the agent that asked.
+## The communication loop
 
-**Human authority stays clear.** Peer messages arrive with attribution and remain peer
-context. Your instructions and approved policy continue to set the boundaries.
-
-**Solo work stays quiet.** A single session receives the familiar client experience.
-Shared context appears when another participant or pending handoff makes it useful.
-
-## Fits the workflow you already have
-
-Your agent client remains the place where sessions start, permissions are granted, and
-work happens. ACC joins at natural moments, shares the relevant context, and returns
-control to the client. Forward progress stays the priority during any coordination delay.
+```bash
+# Session A publishes awareness and reserves only what it will edit.
+acc work --summary "changing the item schema" --mode edit --hint 'file:src/item.mjs'
+acc claim --resource 'file:src/item.mjs' --reason "changing the item schema"
 
-ACC currently connects directly to Codex, Claude Code, Gemini CLI, and Kimi Code. Other
-clients that support MCP can join the same room, see its activity, and exchange work when
-they sync.
+# Session A asks a participant named by `acc status`.
+acc message --to models --type question --subject "item.drive" \
+  --body "Can your code stop reading item.drive before I remove it?"
 
-When a client exposes supported file edits, ACC can protect a claimed file before another
-agent changes it. Shell commands and separate local applications rely on visible claims
-instead. `acc status` explains the protection available in the current room.
+# Session B reads and answers the exact message.
+acc inbox --message message_x
+acc reply --message message_x --body "Yes. Commit abc123 removes the final read."
 
-Current support focuses on multiple sessions working in one project on one machine, on
-macOS or Linux. Each client retains its session lifecycle and full conversation history.
-The [capability evidence](docs/CAPABILITIES.md) records exactly what each integration has
-demonstrated in a real client.
+# Either session records a handoff while context is still available.
+acc finish --goal "remove item.drive" --status complete \
+  --completed "schema and reader updated" --remaining "none"
+```
 
-ACC currently retains every coordination record. It is sized for an active project's
-history; thousands of messages make each turn slower to assemble, so use your project
-documentation for long-term archives.
+Messages commit before any delivery attempt. `queued`, `offered`, `retrieved`, and
+`acknowledged` describe different observable facts: an offer is not a read, retrieval is
+not proof of model attention, and a reply resolves communication rather than proving a
+requested task finished.
 
-## Everyday controls
+Durable inbox recovery is the baseline for every client. Certified next-turn injection can
+reduce the polling, but only for the exact client version and platform captured by the
+adapter. Native live push is opt-in and would also require a current reachable binding;
+**no shipped adapter currently has passing live-push certification**. The failed Codex
+0.152.0 and Claude Code 2.1.252 captures are shipped as evidence, so ACC reports fallback
+instead of claiming realtime delivery.
 
-The installed guidance teaches agents how to claim files, ask questions, request work,
-and complete handoffs. These commands give you a direct view and control when you want it:
+## What ACC owns
 
-| Command | What it is for |
+| ACC owns | ACC does not own |
 |---|---|
-| `acc status` | See active sessions, claimed work, and the room's protection level |
-| `acc doctor` | Confirm which client integrations are active |
-| `acc update --apply` | Install the latest release and refresh integrations |
-| `acc uninstall` | Remove ACC's client integrations safely |
-
-Every operation is documented in the [CLI reference](docs/CLI.md).
-
-## Keep exploring
-
-- **Start using ACC:** [getting started](docs/GETTING_STARTED.md) ·
-  [configuration](docs/CONFIGURATION.md) · [troubleshooting](docs/TROUBLESHOOTING.md)
-- **Understand the promise:** [why ACC](docs/WHY_ACC.md) · [concepts](docs/CONCEPTS.md) ·
-  [capabilities](docs/CAPABILITIES.md) · [security](docs/SECURITY_MODEL.md)
-- **Build on ACC:** [MCP](docs/MCP.md) · [writing an adapter](docs/ADAPTER_AUTHORING.md) ·
-  [protocol](docs/PROTOCOL.md)
-
-See it in action: [three workstreams](examples/three-workstreams.md) ·
-[research in a plain directory](examples/non-git-research.md). Contributions start with
-[Repository Guidelines](AGENTS.md).
-
-## Requirements
-
-Node 24+, macOS or Linux. Git optional.
-
-## License
-
-Free and MIT-licensed. Use it, fork it, keep it — see [LICENSE](LICENSE).
+| participant and session presence | process or model lifecycle |
+| current intent and resource claims | prompts, permissions, or token budgets |
+| messages, threads, replies, acknowledgements | work queues or execution state |
+| delivery evidence and visible fallback | raw transcripts or shared model memory |
+
+A peer message is untrusted input, never system authority. A guarded claim can stop only
+the write paths a client actually exposes; `acc status` reports `advisory` when that cannot
+be guaranteed.
+
+## Documentation
+
+Start with [Getting started](docs/GETTING_STARTED.md), then use the
+[documentation map](docs/index.md). The exact surfaces are in the [CLI](docs/CLI.md),
+[MCP](docs/MCP.md), [Protocol](docs/PROTOCOL.md), and
+[Capabilities](docs/CAPABILITIES.md) references. Adapter evidence lives beside each
+adapter in its `COMPATIBILITY.md` and `certification.json`.
+
+Contributing starts with the repository's
+[AGENTS.md](https://github.com/automatis-tools/agents-can-communicate/blob/main/AGENTS.md).
+Node 24+, Git optional, MIT licensed.

package/SECURITY.md

@@ -0,0 +1,31 @@
+# Security policy
+
+## Reporting
+
+Report privately via [GitHub security advisories](https://github.com/automatis-tools/agents-can-communicate/security/advisories/new).
+
+Please do not open a public issue first.
+
+Include: what you ran, what happened, what you expected, and the client and
+version. A reproduction against a throwaway `ACC_DATA_HOME` is ideal.
+
+## Scope
+
+| In scope | Out of scope |
+|---|---|
+| Peer text escaping its quoted block | An attacker who already has write access to your data home |
+| Any path escaping the managed root | A model choosing to obey persuasive peer text |
+| Uninstall deleting files ACC did not write | Vulnerabilities in Codex, Claude Code, Gemini, Grok, or Kimi themselves |
+| ACC writing into a repository | Denial of service by a trusted peer |
+| Session impersonation across MCP | |
+
+Reasoning behind each: [docs/SECURITY_MODEL.md](docs/SECURITY_MODEL.md).
+
+## Supported versions
+
+Pre-1.0: the latest release only.
+
+## What we will do
+
+Acknowledge, reproduce, and tell you whether it is in scope. If it is, the fix
+ships with a test in `tests/security/` so it cannot come back quietly.

package/bin/acc-hook.mjs

@@ -6,6 +6,8 @@
 // someone's session stops working. Unknown adapter, malformed payload, broken
 // store, missing binding - all of them end in "allow, exit 0".
 import { randomBytes } from "node:crypto";
+import { realpathSync } from "node:fs";
+import { fileURLToPath } from "node:url";
 
 import { createId } from "@agents-can-communicate/protocol";
 import { runHook } from "@agents-can-communicate/hook-runner";
@@ -13,12 +15,14 @@ import { runHook } from "@agents-can-communicate/hook-runner";
 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";
+import { createGrokAdapter } from "@agents-can-communicate/adapter-grok";
 import { createKimiAdapter } from "@agents-can-communicate/adapter-kimi";
 
 const adapters = {
   claude_code: createClaudeCodeAdapter(),
   codex: createCodexAdapter(),
   gemini_cli: createGeminiCliAdapter(),
+  grok: createGrokAdapter(),
   kimi: createKimiAdapter(),
 };
 
@@ -34,20 +38,100 @@ const readStdin = () => new Promise(resolve => {
   return undefined;
 });
 
-const [adapterId] = process.argv.slice(2);
+export const writeOutput = (stream, output, { deadlineAt } = {}) => {
+  if (output === "") return Promise.resolve();
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    let timer;
+    const finish = error => {
+      if (settled) return;
+      settled = true;
+      if (timer !== undefined) clearTimeout(timer);
+      if (error === undefined || error === null) resolve();
+      else reject(error);
+    };
+    if (deadlineAt !== undefined) {
+      const remaining = deadlineAt - Date.now();
+      if (remaining <= 0) {
+        finish(new Error("hook budget exhausted before stdout write"));
+        return;
+      }
+      timer = setTimeout(() => finish(
+        new Error("hook budget exhausted waiting for stdout callback")), remaining);
+    }
+    try {
+      stream.write(output, finish);
+    } catch (error) {
+      finish(error);
+    }
+  });
+};
+
+const DIAGNOSTIC_BYTES = 512;
+
+function boundedDiagnostic(label, error) {
+  const detail = String(error?.message ?? error).replace(/[\u0000-\u001f\u007f]/g, " ");
+  let line = `acc: ${label}: ${detail}`;
+  while (Buffer.byteLength(`${line}\n`, "utf8") > DIAGNOSTIC_BYTES && line.length > 0) {
+    line = line.slice(0, -1);
+  }
+  return `${line}\n`;
+}
 
-let payload = null;
+function tryWrite(stream, output) {
+  if (output === "") return;
+  try {
+    stream.write(output, () => {});
+  } catch {
+    // A broken diagnostic stream must not turn a failed-open hook into a crash.
+  }
+}
+
+export async function completeHookOutput(result,
+  { stdout = process.stdout, stderr = process.stderr } = {}) {
+  try {
+    await writeOutput(stdout, result.stdout ?? "", { deadlineAt: result.deadlineAt });
+  } catch (error) {
+    tryWrite(stderr, boundedDiagnostic("stdout write failed", error));
+    return { exitCode: 0, wroteStdout: false, committedOffers: false };
+  }
+
+  let committedOffers = true;
+  try {
+    await result.commitOffers?.();
+  } catch (error) {
+    committedOffers = false;
+    tryWrite(stderr, boundedDiagnostic("offer commit failed", error));
+  }
+  if (result.stderr) tryWrite(stderr, `${result.stderr}\n`);
+  return { exitCode: 0, wroteStdout: true, committedOffers };
+}
+
+async function main() {
+  const [adapterId] = process.argv.slice(2);
+
+  let payload = null;
+  try {
+    payload = JSON.parse(await readStdin());
+  } catch {
+    payload = null;
+  }
+
+  const result = await runHook({ adapterId, payload, adapters,
+    runtime: { clock: { now: () => new Date().toISOString() },
+      ids: { next: kind => createId(kind, randomBytes) } },
+    env: process.env });
+
+  const completed = await completeHookOutput(result);
+  process.exitCode = result.exitCode ?? completed.exitCode;
+}
+
+let isMain = false;
 try {
-  payload = JSON.parse(await readStdin());
+  isMain = process.argv[1] !== undefined
+    && realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url));
 } catch {
-  payload = null;
+  isMain = false;
 }
 
-const result = await runHook({ adapterId, payload, adapters,
-  runtime: { clock: { now: () => new Date().toISOString() },
-    ids: { next: kind => createId(kind, randomBytes) } },
-  env: process.env });
-
-if (result.stdout !== "") process.stdout.write(result.stdout);
-if (result.stderr) process.stderr.write(`${result.stderr}\n`);
-process.exitCode = result.exitCode ?? 0;
+if (isMain) await main();

package/bin/acc-mcp.mjs

@@ -3,8 +3,9 @@ import { randomBytes } from "node:crypto";
 
 import { EXIT, createId } from "@agents-can-communicate/protocol";
 import { createCoordinationService } from "@agents-can-communicate/core";
+import { createDeliveryRouter } from "@agents-can-communicate/delivery-router";
 import { openFilesystemStore } from "@agents-can-communicate/storage-filesystem";
-import { createGitProbe, discoverWorkspace, platformDataHome, runtimePaths }
+import { ALL_ADAPTERS, createGitProbe, discoverWorkspace, platformDataHome, runtimePaths }
   from "@agents-can-communicate/cli";
 import { serve } from "@agents-can-communicate/mcp-server";
 
@@ -40,13 +41,16 @@ const paths = runtimePaths({
 });
 const store = await openFilesystemStore({ root: paths.root, clock, ids,
   workspaceId: descriptor.id });
+const service = createCoordinationService({ store, clock, ids });
+const adapters = Object.fromEntries(ALL_ADAPTERS().map(adapter => [adapter.id, adapter]));
 
 await serve({
   input: process.stdin,
   output: process.stdout,
   log: message => process.stderr.write(`acc-mcp: ${message}\n`),
   context: {
-    service: createCoordinationService({ store, clock, ids }),
+    service,
+    deliveryRouter: createDeliveryRouter({ service, adapters, clock }),
     workspaceId: descriptor.id,
     participantId,
     descriptor,

package/bin/acc.mjs

@@ -3,7 +3,10 @@ import { randomBytes } from "node:crypto";
 import { readFile } from "node:fs/promises";
 
 import { createId } from "@agents-can-communicate/protocol";
-import { askConfirmation, main } from "@agents-can-communicate/cli";
+import { createDeliveryRouter } from "@agents-can-communicate/delivery-router";
+import { ALL_ADAPTERS, askConfirmation, main } from "@agents-can-communicate/cli";
+
+const adapters = Object.fromEntries(ALL_ADAPTERS().map(adapter => [adapter.id, adapter]));
 
 // The composition root is the only place allowed to reach for ambient time and
 // randomness; everything below it receives them as ports.
@@ -15,6 +18,8 @@ const runtime = {
   stderr: process.stderr,
   clock: { now: () => new Date().toISOString() },
   ids: { next: kind => createId(kind, randomBytes) },
+  createDeliveryRouter: ({ service, clock }) =>
+    createDeliveryRouter({ service, adapters, clock }),
   // Asked only by `acc config init`, and only when stdout is a terminal. There
   // was no port here at all, so the question went to the fallback that always
   // answers no: in a real terminal the command printed "not written" and never

package/docs/ADAPTER_AUTHORING.md

@@ -0,0 +1,172 @@
+# Writing an adapter
+
+An adapter teaches ACC one client. Nothing else in ACC knows that client exists. This page
+assumes the vocabulary in [Protocol](PROTOCOL.md#identity-hierarchy) — session, participant,
+claim — and points to [Capabilities](CAPABILITIES.md) for what was actually measured per
+client; see the [documentation map](index.md) for where both fit among the rest.
+
+```mermaid
+graph LR
+  H[client hook] --> R[acc-hook runtime]
+  R -->|normalizeHook| E[normalised event]
+  E --> CO[core: attach, claims, sync]
+  CO -->|denyOutcome / injectOutcome| R
+  R --> H
+```
+
+## The manifest
+
+```js
+export function createExampleAdapter() {
+  return defineAdapter({
+    id: "example",                    // portable id
+    displayName: "Example CLI",
+    client: { command: "example", certificationName: "example-cli",
+      versionArgs: ["--version"] },
+    certification,                    // imported package-local certification.json
+    capabilities: { delivery: { nextTurn: true } },
+
+    detect, install, uninstall, doctor,
+    planInstall,                      // what install would write
+    normalizeHook,                    // client payload -> normalised event
+    renderContext,                    // SyncResult -> text
+    renderContextResult,              // text + ids of complete rendered groups
+    denyOutcome, injectOutcome,       // how this client is answered
+  });
+}
+```
+
+`renderContextResult` is required wherever an adapter renders peer messages. It returns
+`{ text, includedMessageIds, includedAttentionIds }`, and the [delivery
+lifecycle](PROTOCOL.md#delivery-lifecycle) advances only from those ids — never by searching
+`text` for one, because peer text is untrusted and can imitate another message's header.
+`projectContextResult()` implements this contract; `projectContext()` remains the text-only
+convenience API for adapters that don't need it. An adapter with only the older
+`renderContext()` gets pending bodies withheld and a visible `acc inbox` degradation warning
+instead: repeating an untracked body every turn would be quieter in code and dishonest about
+what was actually delivered.
+
+`client.command` does double duty. `detect.mjs` uses it as the version-probe binary, and
+presence liveness separately walks the hook's process ancestry for the first ancestor whose
+executable basename matches it, to learn the client's own pid. Declare the binary the client
+actually runs as — `command: "claude"` for a client that really runs as `node` resolves
+nothing, and the failure is silent: the session gets `pid: null` and falls back to reading
+presence by age alone, with nothing telling you why.
+
+## Capabilities
+
+Fourteen booleans in four groups, declared in the manifest's `capabilities` object:
+
+| Group | Entries |
+|---|---|
+| `lifecycle` | `sessionStart` `sessionResume` `sessionEnd` `heartbeat` `childSessions` |
+| `context` | `startupInjection` `beforeTurnInjection` `safePointInjection` |
+| `guards` | `beforeRead` `beforeWrite` `beforeShell` |
+| `delivery` | `nextTurn` `livePush` `replyRoute` |
+
+**False by default. `true` requires a backing method *and* an observed capture.**
+`defineAdapter` enforces the method — declaring `guards.beforeWrite: true` without
+`guardWrite()` is a usage error at construction. It also requires a passing entry in the
+validated `certification.json`; method existence is never evidence. What each shipped
+client was actually observed doing against this list is [Capabilities](CAPABILITIES.md#matrix).
+
+`lifecycle.heartbeat` is deliberately not a flavour of `delivery.nextTurn`. Next-turn
+delivery happens only when the client reaches a normal turn boundary; heartbeat fires on a
+timer even while the session is idle.
+
+### Certification evidence
+
+Every adapter ships `certification.json` and every referenced capture under `fixtures/`.
+Each evidence entry contains `client`, exact `version`, exact `platform`, `observedAt`,
+`capability`, package-relative `fixture`, `idleBehavior`, `busyBehavior`,
+`authorityLevel`, `limitations`, and `result` (`pass` or `fail`). A copied documentation
+example is not a capture. Failed experiments stay in the manifest as `fail`; they explain
+the false value and can never enable it.
+
+`effectiveCapabilities(adapter, { clientVersion, platform })` returns the full boolean
+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.
+
+The backing methods for delivery are `renderContextResult()` for `nextTurn`,
+`offerMessage()` for `livePush`, and `routeReply()` for `replyRoute`.
+
+## How far you can get
+
+| Tier | You register | You get | You do not get |
+|---|---|---|---|
+| 0 | nothing — humans run `acc` | durable messages, status, claims | anything automatic |
+| 1 | the MCP server | attach on first call, read, claim, message | guards, session end |
+| 2 | hooks + skill | automatic attach, turn context, write guards, cleanup | realtime |
+| 3 | + realtime surface | delivery receipts, safe-point injection, child sessions | — |
+
+Installed hook wiring may reach tier 2, but the effective capability is still limited to
+an exact certified client/version/platform. No client currently certifies native live push
+or native reply routing.
+
+## normalizeHook
+
+Whitelist, never a filter. Every client hands hooks the prompt, the transcript path, or the
+tool output; none of it may survive.
+
+```js
+return normalizedEvent({
+  kind, sessionId, cwd, model, parentSessionId, tool,
+  targets,   // paths this call would WRITE. For a shell call, pass the command to
+             // shellWriteTargets() — it reads write positions only, never reads.
+});
+```
+
+Refuse an unrecognised payload. Inventing a session attaches the wrong one, or a new one
+every hook, and looks like it is working.
+
+## Response contracts do not port
+
+Measure them. Every client differs, and a wrong shape fails **silently**:
+
+| | deny | inject |
+|---|---|---|
+| Codex | exit 2 + stderr | plain stdout (`developer` message) |
+| Claude Code | `hookSpecificOutput.permissionDecision` | same envelope |
+| Gemini CLI | `{"decision":"block"}` | `hookSpecificOutput` envelope |
+| Grok | `{"decision":"deny","reason"}` (documented; deny not yet captured) | UserPromptSubmit stdout discarded on 1.0.13 |
+| Kimi Code | `hookSpecificOutput.permissionDecision` | plain stdout |
+
+`denyOutcome(reason)` returns `{ stdout, stderr, exitCode }`, so the runtime never has to
+know which client it is talking to. This table is only the shape each shipped adapter
+actually uses; the full experimental grid — every candidate shape tried against every
+client, including which ones are silently ignored — is measured in
+[Capabilities](CAPABILITIES.md#response-contracts-which-do-not-port).
+
+## Install and ownership
+
+```mermaid
+graph TB
+  P[planInstall] -->|artifacts| K{kind}
+  K -->|tree| T[a directory ACC creates<br/>removable if unchanged]
+  K -->|merge| M[a file the user owns<br/>never deleted]
+```
+
+Rules that are not negotiable:
+
+- idempotent — installing twice equals installing once;
+- reversible — uninstall restores the user's file byte for byte;
+- absolute command paths — a hook's environment carries no PATH;
+- honour `keep`: uninstall receives paths the user has since edited.
+
+`planInstall` must use the same path helpers as `install`. A conformance test compares
+them, because a plan that drifts makes `--dry-run` a decoration.
+
+## Conformance
+
+```bash
+node --test tests/conformance/*.test.mjs
+node --test tests/process/hook-wiring.test.mjs
+```
+
+The second one *executes* what your install wrote. Three adapters once shipped a hook
+command that did not exist anywhere; every test was green.
+
+## Record what you learned
+
+One `COMPATIBILITY.md` per adapter: client version, event names, payload fields, the deny
+matrix, and what you could **not** observe. The next person's alternative is guessing.