agents-can-communicate 0.1.16 → 0.1.18

package/README.md

@@ -4,171 +4,101 @@
 [![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.**
+**Give the agent sessions you already opened a shared room — and stop being the wire
+between them.**
 
-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.
+ACC is a local-first coordination layer for independent AI coding sessions on one repo.
+They see who else is here, claim the files they touch, message each other directly, and
+hand work across — while each keeps its own client, checkout, permissions, and human. It
+runs entirely on your machine, on Node's standard library with **zero runtime
+dependencies**, and your transcripts never leave the client.
 
-Coordination runs locally on your machine. Raw transcripts stay private. The runtime is
-built entirely on Node's standard library.
+## The wall is you
+
+One session refactors and is about to remove a field called `item.drive`. Another, in a
+file you're not looking at, still reads it. Neither terminal knows the other exists — so
+either you carry the warning across by hand, or it ships broken.
+
+**Without ACC**, every warning, question, and handoff between sessions stops at you and
+starts again from you. **With ACC**, the sessions carry them to each other: the second
+agent sees the claim, gets the measured impact as a message, and the change lands in one
+piece. You go back to directing.
 
 ```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["You — set direction"]
+  A["session A"]
+  B["session B"]
+  C["session C"]
+  R["ACC shared room<br/>presence · claims · messages · handoffs"]
   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.
-
-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.
-
-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.
-
-```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"]
-```
-
-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.
-
 ## Install
 
-Run these commands in a terminal on each macOS or Linux machine where your agent clients
-run:
+Two commands, once per macOS or Linux machine where your clients run:
 
 ```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 install` wires ACC into the clients you have — Codex, Claude Code, Gemini CLI, Grok,
+Kimi Code — and names everything it changed. **Restart the client afterwards** (hooks load
+at startup); Codex also needs you to trust the plugin. Then just open a session in a
+project and it joins that project's room by itself; open a second and they coordinate.
+`acc doctor` shows what's active, `acc update --apply` keeps it current, `acc uninstall`
+removes only what ACC wrote.
 
-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.
+Coordination data lives in the platform app-data directory (`~/Library/Application
+Support/acc`, `~/.local/share/acc`; override with `ACC_DATA_HOME`), never in your repo.
+Every worktree of a repo shares one room; a plain folder works the same.
 
-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.
+## What the room holds
 
-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.
-
-**Parallel work becomes deliberate.** Agents claim shared files before editing. Supported
-client edits respect those claims and identify the participant already working there.
-
-**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.
-
-**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.
-
-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.
-
-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.
-
-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.
+| | |
+|---|---|
+| **presence** | who's live, their client and branch, and what each intends — one `acc status`. |
+| **claims** | the files each session is touching; on guardable clients a clashing edit is refused and the owner named. |
+| **messages** | questions, decisions, notes — attributed, delivered on the recipient's next turn, and data they weigh rather than orders. |
+| **requests & handoffs** | work addressed to a participant, so it waits across restarts and carries the answer back. |
 
-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.
+A targeted `acc inbox` survives context compaction, and `acc reply` answers and
+acknowledges in one operation. A session alone in a repo pays nothing — no banner, no
+protocol, nothing left behind.
 
 ## Everyday controls
 
-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:
+The installed guidance teaches your agents to claim, ask, request, and hand off on their
+own. These give you a direct view when you want one:
 
-| Command | What it is for |
+| Command | For |
 |---|---|
-| `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)
+| `acc status` | who's here, what they claim, and the room's protection level |
+| `acc inbox` | recover an addressed message without a workspace dump |
+| `acc reply` | answer and acknowledge in one operation |
+| `acc doctor` | confirm which client integrations are active and current |
+| `acc update --apply` | install the latest release and refresh integrations |
+| `acc uninstall` | remove ACC's integrations — settings you changed stay yours |
 
-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).
+## Documentation
 
-## Requirements
+Start at the **[documentation map](docs/index.md)** — it lays out a path for whatever
+brought you here: [why ACC](docs/WHY_ACC.md) and [concepts](docs/CONCEPTS.md) to evaluate
+it, [getting started](docs/GETTING_STARTED.md) to run it, the [CLI](docs/CLI.md) /
+[protocol](docs/PROTOCOL.md) / [capabilities](docs/CAPABILITIES.md) reference, and
+[adapter authoring](docs/ADAPTER_AUTHORING.md) to extend it. New to the vocabulary? The
+[glossary](docs/GLOSSARY.md) defines every term in one line.
 
-Node 24+, macOS or Linux. Git optional.
+See it run: [three workstreams](examples/three-workstreams.md) · [research in a plain
+folder](examples/non-git-research.md). Contributing starts with [AGENTS.md](AGENTS.md).
 
-## License
+## Requirements & license
 
-Free and MIT-licensed. Use it, fork it, keep it — see [LICENSE](LICENSE).
+Node 24+, macOS or Linux, Git optional. MIT — use it, fork it, keep it
+([LICENSE](LICENSE)).

package/bin/acc-hook.mjs

@@ -13,12 +13,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(),
 };
 

package/docs/CAPABILITIES.md

@@ -1,17 +1,15 @@
 # Capabilities
 
-Capability honesty is part of the product, not an implementation footnote. ACC coordinates
-sessions it does not own, so the workspace can promise only what every session actually
-exposes. One weaker participant lowers the reported protection level instead of inheriting
-a stronger label from its peers.
+Capability honesty is part of the product: ACC coordinates sessions it does not own, so a
+workspace can promise only what every session in it actually exposes — one weaker
+participant lowers the reported protection level instead of inheriting a stronger label
+from its peers.
 
-What each harness was **observed** doing, on the versions named here. Nothing in this
-table is inferred from documentation: every `yes` has a fixture captured from a real
-session, and every `no` means it was not seen, not that it is impossible.
-
-Certified 2026-08-16 on macOS 15 (darwin 25.5.0, arm64). No other operating system has
-been tested, and at least one finding here is filesystem- and path-shaped, so the table
-should be re-run before claiming another platform.
+Every row below is **measured**, not asserted: a `yes` has a fixture captured from a real
+session of that client version; a `no` means the behavior was not observed, not that it is
+impossible. Certified 2026-08-16 on macOS 15 (darwin 25.5.0, arm64) only — at least one
+finding here is filesystem- and path-shaped, so re-run the table before trusting it on
+another platform.
 
 ## Clients
 
@@ -20,33 +18,34 @@ should be re-run before claiming another platform.
 | `codex` | `codex-cli` | 0.147.0 |
 | `claude_code` | Claude Code | 2.1.233 |
 | `gemini_cli` | Gemini CLI | 0.37.0 and 0.55.1 |
+| `grok` | Grok | 1.0.13 |
 | `kimi` | Kimi Code | 0.36.1 |
 
 ## Matrix
 
-| Capability | codex | claude_code | gemini_cli | kimi |
-|---|---|---|---|---|
-| `lifecycle.sessionStart` | yes | yes | yes | yes |
-| `lifecycle.sessionResume` | no | no | no | no |
-| `lifecycle.sessionEnd` | yes | yes | yes | no |
-| `lifecycle.heartbeat` | no | no | no | yes |
-| `lifecycle.childSessions` | no | no | no | no |
-| `context.startupInjection` | no | no | no | no |
-| `context.beforeTurnInjection` | yes | yes | yes | yes |
-| `context.safePointInjection` | no | no | no | no |
-| `guards.beforeRead` | no | no | no | no |
-| `guards.beforeWrite` | yes | yes | yes | yes |
-| `guards.beforeShell` | yes | yes | yes | yes |
-| `delivery.polling` | yes | yes | yes | yes |
-| `delivery.activeNotification` | no | no | no | no |
-| `delivery.wakeDormantSession` | no | no | no | no |
-| `execution.launch` | no | no | no | no |
-| `execution.resume` | no | no | no | no |
-| `execution.terminate` | no | no | no | no |
+| Capability | codex | claude_code | gemini_cli | grok | kimi |
+|---|---|---|---|---|---|
+| `lifecycle.sessionStart` | yes | yes | yes | yes | yes |
+| `lifecycle.sessionResume` | no | no | no | no | no |
+| `lifecycle.sessionEnd` | yes | yes | yes | yes | no |
+| `lifecycle.heartbeat` | no | no | no | no | yes |
+| `lifecycle.childSessions` | no | no | no | no | no |
+| `context.startupInjection` | no | no | no | no | no |
+| `context.beforeTurnInjection` | yes | yes | yes | no | yes |
+| `context.safePointInjection` | no | no | no | no | no |
+| `guards.beforeRead` | no | no | no | no | no |
+| `guards.beforeWrite` | yes | yes | yes | no | yes |
+| `guards.beforeShell` | yes | yes | yes | no | yes |
+| `delivery.polling` | yes | yes | yes | yes | yes |
+| `delivery.activeNotification` | no | no | no | no | no |
+| `delivery.wakeDormantSession` | no | no | no | no | no |
+| `execution.launch` | no | no | no | no | no |
+| `execution.resume` | no | no | no | no | no |
+| `execution.terminate` | no | no | no | no | no |
 
 ## Resolving a client's pid is not universal either
 
-Not a capability above - no adapter method backs it, so it has no row in the matrix - but
+Not a capability above — no adapter method backs it, so it has no row in the matrix — but
 it is presence's other signal for telling a dead process from an idle one, and it does not
 reach every client.
 
@@ -60,15 +59,16 @@ interpreter's name rather than the script's.
 |---|---|---|---|
 | `codex` | `codex` | `codex`, a native binary | yes |
 | `claude_code` | `claude` | `claude`, a native binary | yes |
-| `gemini_cli` | `gemini` | `node` - `gemini.js` starts `#!/usr/bin/env node` | **no** |
-| `kimi` | `kimi` | not installed on the machine this table was measured on; Kimi Code ships via npm as a Node.js CLI (`@moonshot-ai/kimi-code`), the same shape as Gemini CLI | **almost certainly no - not measured** |
+| `gemini_cli` | `gemini` | `node` — `gemini.js` starts `#!/usr/bin/env node` | **no** |
+| `grok` | `grok` | `grok`, a native Mach-O at `~/.grok/bin/grok` | yes |
+| `kimi` | `kimi` | not installed on the machine this table was measured on; Kimi Code ships via npm as a Node.js CLI (`@moonshot-ai/kimi-code`), the same shape as Gemini CLI | **almost certainly no — not measured** |
 
 A Gemini session records `pid: null` for its whole life, and Kimi's is very likely the
 same, unconfirmed. `null` is the correct "nobody knows" answer and is handled identically
-wherever it is read - not a correctness bug. It does change what presence delivers, though:
-a confirmed-dead pid retires a session immediately and exactly, and today that is `codex`
-and `claude_code` only. `gemini_cli` and `kimi` fall back to the same age-based floor every
-session has for whenever a pid is unavailable - thirty minutes of silence - so their
+wherever it is read — not a correctness bug. It does change what presence delivers, though:
+a confirmed-dead pid retires a session immediately and exactly, and today that is `codex`,
+`claude_code`, and `grok`. `gemini_cli` and `kimi` fall back to the same age-based floor every
+session has for whenever a pid is unavailable — thirty minutes of silence — so their
 sessions still leave, just later and on a timer instead of on the fact. See
 [ARCHITECTURE.md](ARCHITECTURE.md#presence) for the full floor.
 
@@ -89,8 +89,8 @@ toolset contained no `apply_patch`.
 `replace` appear under `auto_edit`; `run_shell_command` under `yolo`.
 
 **`guards.beforeShell` is resource-aware where the write is unambiguous.** ACC reads the
-command for its write positions only - a redirection, an operand of a command whose whole
-job is to put bytes somewhere - and declares those paths as targets. Reading positions are
+command for its write positions only — a redirection, an operand of a command whose whole
+job is to put bytes somewhere — and declares those paths as targets. Reading positions are
 left alone: `cat file` and `grep file` name a path and write nothing, and treating them as
 writes would have sessions blocking each other for looking.
 
@@ -101,8 +101,9 @@ is: a session told to prefer the shell for file changes walked through every cla
 workspace.
 
 Where the guard cannot help, the turn context does: it names the claims other sessions
-hold and says which way this session stands with them. Two facts decide the wording -
-what the claim's owner asked for, and whether ACC can stop this session at all:
+hold and says which way this session stands with them. Two facts decide the wording — what
+the claim's owner asked for (`guarded` or `advisory`; see [Glossary](GLOSSARY.md)), and
+whether ACC can stop this session at all:
 
 | Claim | This session | Note |
 |---|---|---|
@@ -110,51 +111,59 @@ what the claim's owner asked for, and whether ACC can stop this session at all:
 | guarded | cannot be guarded | `not enforced for this session; do not edit it` |
 | advisory | either | `advisory; nothing will stop you, the owner is asking` |
 
-Unenforceable is not the same as unknown - and neither is it the same as unclaimed.
+Unenforceable is not the same as unknown — and neither is it the same as unclaimed.
 
 **`lifecycle.sessionEnd` on `kimi` is false and it matters.** Each `kimi -p` run leaves an
-attached session that never closes itself - it just stops taking turns. Presence retires it
+attached session that never closes itself — it just stops taking turns. Presence retires it
 instead, most likely without ever resolving a pid (see above), which means the session
-reads `offline` - and disappears from the default `acc status` view - only after thirty
+reads `offline` — and disappears from the default `acc status` view — only after thirty
 minutes of silence, not on its declared 60s heartbeat cadence. Interactive sessions
 heartbeat and do not have this problem.
 
-**`lifecycle.heartbeat` is Kimi's alone.** It fires on a timer - observed at 60002, 120004
-and 180006 ms of uptime - so an idle Kimi session keeps its presence honest. The other
-three reach a hook only when the user takes a turn, so their idle sessions go stale while
+**`lifecycle.heartbeat` is Kimi's alone.** It fires on a timer — observed at 60002, 120004
+and 180006 ms of uptime — so an idle Kimi session keeps its presence honest. The other
+clients reach a hook only when the user takes a turn, so their idle sessions go stale while
 alive. This is why it is a capability of its own rather than a flavour of
 `delivery.polling`.
 
+**`context.beforeTurnInjection` on `grok` is false.** Grok 1.0.13 discards
+UserPromptSubmit stdout and `additionalContext`. The hook still runs (presence
+and polling), but the model is not shown that text. Agents on this client read
+`acc status` / `acc inbox` from the skill.
+
+**`guards.beforeWrite` / `beforeShell` on `grok` are false.** PreToolUse fires, and
+the matcher names `write`, `search_replace`, and `run_terminal_command`. A deny
+has not yet been captured blocking a real call, so the capability stays false.
+
 ## Response contracts, which do not port
 
 The single most portable-looking mistake an adapter can make. Measured by running each
 candidate against a real session of each client and checking whether the tool actually
-ran.
-
-A dash means the candidate was never run against that client, not that it fails. Only the
-shape each adapter actually uses was measured on every client.
-
-| Reply to a guard hook | codex | claude_code | gemini_cli | kimi |
-|---|---|---|---|---|
-| exit code 2 | denies | - | denies | denies |
-| `{"hookSpecificOutput":{…,"permissionDecision":"deny"}}` | - | denies | **ignored** | denies |
-| `{"decision":"block","reason":…}` | - | - | denies | **ignored** |
-| `{"permission":"deny"}` | - | - | ignored | ignored |
-| exit code 1 | - | - | ignored | ignored |
+ran. A dash means the candidate was never run against that client, not that it fails —
+only the shape each shipped adapter actually uses was measured on every client.
+
+| Reply to a guard hook | codex | claude_code | gemini_cli | grok | kimi |
+|---|---|---|---|---|---|
+| exit code 2 | denies | - | denies | - | denies |
+| `{"hookSpecificOutput":{…,"permissionDecision":"deny"}}` | - | denies | **ignored** | documented | denies |
+| `{"decision":"deny","reason":…}` | - | - | - | documented | - |
+| `{"decision":"block","reason":…}` | - | - | denies | - | **ignored** |
+| `{"permission":"deny"}` | - | - | ignored | - | ignored |
+| exit code 1 | - | - | ignored | - | ignored |
 
 Codex has no structured reply at all: it denies by exiting 2 with the reason on stderr.
 Gemini ignores the shape that Claude Code and Kimi Code both honour, and Kimi ignores the
-shape Gemini needs. Each ignored case fails silently - the write goes through and the
+shape Gemini needs. Each ignored case fails silently — the write goes through and the
 client reports nothing.
 
 Context injection does not follow the deny contract even within one client:
 
-| Injection | codex | claude_code | gemini_cli | kimi |
-|---|---|---|---|---|
-| `hookSpecificOutput.additionalContext` | - | works | works | works, but **not unwrapped** |
-| plain text on stdout | works | - | dropped | works |
+| Injection | codex | claude_code | gemini_cli | grok | kimi |
+|---|---|---|---|---|---|
+| `hookSpecificOutput.additionalContext` | - | works | works | **discarded** on UserPromptSubmit | works, but **not unwrapped** |
+| plain text on stdout | works | - | dropped | **discarded** on UserPromptSubmit | works |
 
-Codex delivers a hook's stdout as a `developer` role message, verbatim - the most direct
+Codex delivers a hook's stdout as a `developer` role message, verbatim — the most direct
 of the four channels, and a reason for care rather than comfort: at that role a model
 reads text as instruction, so peer-authored text has to stay framed as data.
 
@@ -163,37 +172,48 @@ Kimi Code shows the model whatever a hook printed, wrapped in
 conversation. Gemini unwraps the envelope and appends `<hook_context>…</hook_context>` to
 the user turn, and drops a bare string entirely.
 
+These two tables are the measurement; they say nothing about how an adapter produces the
+right shape without knowing which client it is talking to. That contract —
+`denyOutcome()` / `injectOutcome()` — is documented in
+[ADAPTER_AUTHORING.md](ADAPTER_AUTHORING.md#response-contracts-do-not-port).
+
 ## Installation is not uniform either
 
-| | codex | claude_code | gemini_cli | kimi |
-|---|---|---|---|---|
-| Where hooks live | marketplace plugin | plugin | `settings.json` | `config.toml` |
-| Project-level config | no | no | yes | **no** |
-| Hook `timeout` unit | - | - | milliseconds | **seconds** (max 600) |
-| Command path | absolute required | `${CLAUDE_PLUGIN_ROOT}` | absolute required | absolute required |
-| Extra step by the user | hook trust | - | - | - |
+| | codex | claude_code | gemini_cli | grok | kimi |
+|---|---|---|---|---|---|
+| Where hooks live | marketplace plugin | plugin | `settings.json` | `~/.grok/hooks/acc.json` | `config.toml` |
+| Project-level config | no | no | yes | yes (`<project>/.grok/hooks`, unused) | **no** |
+| Hook `timeout` unit | - | - | milliseconds | **seconds** | **seconds** (max 600) |
+| Command path | absolute required | `${CLAUDE_PLUGIN_ROOT}` | absolute required | absolute required | absolute required |
+| Extra step by the user | hook trust | - | - | - | - |
 
 Kimi Code is the only one with no project-level config, so ACC edits the user's global
-`config.toml` - as a delimited block it owns, because ACC ships without dependencies and a
+`config.toml` — as a delimited block it owns, because ACC ships without dependencies and a
 hand-written TOML round-tripper would take the user's comments and formatting with it.
 
 Codex needs four things before a hook runs, not one: the plugin directory, a parseable
 marketplace, both `[marketplaces.…]` and `[plugins."…"]` registered in its config, and the
-plugin copied into `plugins/cache/<marketplace>/<plugin>/<version>/`. ACC does all four -
+plugin copied into `plugins/cache/<marketplace>/<plugin>/<version>/`. ACC does all four —
 that last copy is exactly and only what `codex plugin add` does, measured by diffing the
 home around it. Hook trust remains a manual step, which is the client's security model.
 
 ## What a participant declares about itself
 
 Every session records `enforcement` (`guarded` | `advisory`) and `lifecycle`
-(`managed` | `manual`), taken from the adapter's proven capabilities rather than from the
-harness name. Both default to the weaker reading, so a generic MCP client or a human at
-the CLI reads as advisory and manual.
-
-A workspace reports `protection: guarded` only when every live session can be stopped. One
-MCP client and a guarded claim is advice - so the workspace says `advisory`, whatever its
-claims were declared as.
-
-"Stoppable" is not "unevadable". Even in a guarded workspace, a session that writes through
-a language runtime rather than a recognised shell form gets past. The claim still says who
-is working where; enforcement is the floor, not the ceiling.
+(`managed` | `manual`), taken from the adapter's proven capabilities in this matrix rather
+than from the harness's name — both default to the weaker reading, so a generic MCP client
+or a human at the CLI reads as advisory and manual. What that downgrade means for a
+workspace, and why one MCP participant in the room is enough to drop everyone else's
+protection, is explained canonically in
+[MCP.md](MCP.md#native-adapter-vs-mcp-client).
+
+**"Stoppable" is not "unevadable".** Even in a guarded workspace, a session that writes
+through a language runtime rather than a recognised shell form gets past — see
+`guards.beforeShell` above. The claim still says who is working where; enforcement is the
+floor, not the ceiling.
+
+---
+
+See also: [README](index.md) for navigation, [Glossary](GLOSSARY.md) for terms,
+[Adapter authoring](ADAPTER_AUTHORING.md) for the deny/inject implementation contract, and
+[MCP](MCP.md) for the participation tier and the native-vs-MCP explanation.

package/node_modules/@agents-can-communicate/adapter-claude-code/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agents-can-communicate/adapter-claude-code",
-  "version": "0.1.16",
+  "version": "0.1.18",
   "private": true,
   "type": "module",
   "exports": {