agents-can-communicate 0.1.18 → 0.2.0

package/docs/CONCEPTS.md

@@ -0,0 +1,134 @@
+# Concepts
+
+ACC connects AI sessions that were independently opened by a user. It adds communication
+around those sessions; it does not turn them into one managed runtime. Each client keeps
+its own context, permissions, lifecycle, checkout, and human authority.
+
+```mermaid
+graph LR
+  A["independent session A"] --- ACC["ACC local room"]
+  B["independent session B"] --- ACC
+  C["independent session C"] --- ACC
+```
+
+## Peers, not workers
+
+Sessions in one workspace may use different models, clients, trust settings, or people.
+No participant is automatically in charge of another. A peer may ask, answer, reserve,
+acknowledge, or hand off; the receiver evaluates the message under its own instructions.
+
+This is the middle layer between isolated terminals and a system that owns the agents.
+ACC owns durable coordination facts even when every model process is gone, but it never
+owns the process itself.
+
+## Participant and session
+
+A **participant** is the address used for communication. A stable participant id lets a
+new session recover messages addressed before restart. A **session** is one current client
+conversation with a generation token proving ownership of its mutations. Several sessions
+may belong to one participant; a live offer is ambiguous unless exactly one current
+generation is eligible.
+
+A **workspace** is the local room. Git worktrees of one repository resolve to the same
+workspace while retaining their checkout and branch in presence. In a non-Git directory,
+the directory itself supplies identity. Git enriches the record but is never required.
+
+## Intent is awareness; a claim commits
+
+An **intent** says what a session is doing and which resources may be affected. It
+authorises nothing. Publish it early because it is cheap:
+
+```bash
+acc work --summary "changing message rendering" --mode edit \
+  --hint 'file:packages/cli/**'
+```
+
+A **claim** reserves a resource for a lease. It is narrow, explicit, and either
+`advisory` or `guarded`:
+
+```bash
+acc claim --resource 'file:packages/cli/**' --reason "changing message rendering"
+```
+
+`guarded` means every live session exposes a measured pre-write guard for the path ACC can
+recognise. It never means an unrelated process or a runtime-generated write is impossible.
+If any live participant cannot be stopped, workspace protection is reported as
+`advisory`.
+
+File claims are repository-relative and canonical. `file:src/a.mjs` names a file;
+`file:src/**` names a directory tree. Ambiguous spellings such as `file:src/*` are refused
+instead of creating protection that covers nothing.
+
+## Messages are durable untrusted data
+
+The message kinds are `note`, `question`, `request`, `answer`, `decision`, and `handoff`.
+The generic send command creates the first four except `answer`, which requires `reply`,
+and `handoff`, which requires `finish` so their thread and structured payloads cannot be
+omitted.
+
+An independent **obligation** says what the recipient owes:
+
+| Kind | Obligation |
+|---|---|
+| `note` | `none` |
+| `question` | `reply` |
+| `request` | `reply` |
+| `answer` | `none` |
+| `decision` | `none`, or `acknowledge` when addressed |
+| `handoff` | `acknowledge` when addressed, `none` as a room record |
+
+A request is not an order. It asks for action and a result in the thread, but ACC does not
+track execution state. Every body is attributed, escaped, and framed as peer input rather
+than system authority.
+
+## Threads have no hidden status
+
+The first message is the thread root and uses its own `messageId` as `threadId`. A reply
+keeps that thread id and names the original with `inReplyTo`. There is no mutable thread
+record. What still needs attention is derived from message obligations and per-recipient
+receipts.
+
+`clientMessageId` is the caller's retry key. Repeating equivalent content with the same
+key returns the same logical message; reusing it for different content is rejected.
+
+## Delivery words are evidence
+
+Each recipient has an independent monotonic receipt:
+
+```text
+queued -> offered -> retrieved -> acknowledged
+```
+
+- `queued`: message and receipt committed durably;
+- `offered`: bytes crossed ACC's transport boundary or a certified native client accepted
+  the call;
+- `retrieved`: the participant explicitly read the message through inbox or equivalent
+  certified evidence;
+- `acknowledged`: the participant acknowledged it or replied.
+
+There is no `seen`: ACC cannot observe model attention. There is no terminal delivery
+failure: a failed acceleration leaves the durable message recoverable. Forward skips are
+legal when a stronger fact implies the weaker ones; backward transitions are rejected.
+
+## Durable first, acceleration second
+
+Every send records the message before attempting a transport. Inbox is the universal
+recovery path. Exact-version certified adapters may offer complete peer messages at the
+next normal turn. Native live push would additionally require passing certification, the
+recipient's opt-in policy, exactly one current reachable binding, and a safe recipient
+state.
+
+No shipped adapter currently passes live-push certification. Codex 0.152.0 had no daemon
+control socket; Claude Code 2.1.252 stopped at the development-channel warning before its
+ACC child started. Those failures are shipped as evidence and result in visible fallback,
+not a stronger promise.
+
+## Where state lives
+
+Presence, intents, claims, messages, receipts, events, and handoffs live in platform app
+data outside every repository. Raw transcripts remain in the client. A single session is
+silent; durable workspace state materialises when a second session or the first durable
+coordination object makes it necessary.
+
+Next: [Getting started](GETTING_STARTED.md) · [Protocol](PROTOCOL.md) ·
+[Capabilities](CAPABILITIES.md)

package/docs/CONFIGURATION.md

@@ -0,0 +1,143 @@
+# Configuration
+
+ACC works with no configuration at all. A workspace is identified by its Git common
+directory when there is one and by the directory itself otherwise. Independently opened
+sessions can communicate without adding runtime state to the project.
+
+`acc.workspace.json` is only for stable workspace identity, roots, and shared claim/context
+policy. It never defines agents, messages, execution state, or delivery endpoints. Project
+map: [README](index.md). Terms used below: [Glossary](GLOSSARY.md).
+
+## When you need a config
+
+- **Identity that survives a move.** Without a config, the same project checked out at two
+  paths is two workspaces, and two people whose clones sit in different directories do not
+  see each other. `workspaceId` fixes that, and it is the usual reason this file exists.
+- **More than one root.** A monorepo whose apps live in separate directories, or a
+  workspace that spans sibling checkouts.
+- **Shared policy.** Claim mode and context budget, agreed once and committed, rather than
+  each person's machine deciding.
+- **Stated expectations.** `requiredAdapters` records which harnesses this project expects
+  to be installed, so `acc doctor` can say what is missing rather than leaving a session
+  silently uncoordinated.
+
+### The file
+
+`acc.workspace.json`, at the root of the workspace. One name, so discovery is a lookup and
+not a search. It is found by walking up from the working directory, because sessions start
+wherever the human happens to be — a config that only counted at the top would apply to
+some sessions in a project and not others. A config reached through a symlink is refused: a
+link can point anywhere, including at a file the repository does not control.
+
+```json
+{
+  "schemaVersion": 1,
+  "workspaceId": "workspace_9pQ2f1xJ",
+  "displayName": "Example",
+  "roots": ["."],
+  "policy": {
+    "claimMode": "advisory",
+    "contextBudgetBytes": 6000
+  },
+  "requiredAdapters": []
+}
+```
+
+| Field | Meaning | Default |
+|---|---|---|
+| `schemaVersion` | Must be `1` | required |
+| `workspaceId` | Stable identity, portable id | required |
+| `displayName` | What peers see in a roster | the directory name |
+| `roots` | Directories in this workspace, relative to the config | `["."]` |
+| `policy.claimMode` | `advisory` or `guarded` | `advisory` |
+| `policy.contextBudgetBytes` | Ceiling on injected turn context, 1–64000 | `6000` |
+| `requiredAdapters` | Harnesses this project expects | `[]` |
+| `extensions` | Anything else, namespaced by whoever wrote it | `{}` |
+
+Roots are refused if they are absolute or escape the workspace. An absolute root is one
+machine's layout committed to a shared repository, and `packages/../../elsewhere` reaches
+outside the boundary the workspace is supposed to be. The check counts path segments, so an
+escape spelled in the middle is caught rather than only a leading `..`.
+
+An unrecognised key is an error, not a shrug. `clam_mode` reads like a typo to a human and
+like nothing at all to a parser that ignores what it does not know, and the result is a
+team whose policy quietly stopped applying. `extensions` is the one declared door for
+anything ACC does not define.
+
+### What it must never contain
+
+Sessions, participants, messages, claims, receipts, intents, events, tokens, credentials.
+All of it is refused, by name, with the key that caused it, for two reasons. Runtime state
+belongs under the platform data directory, so a checkout can be deleted, cloned, or synced
+without carrying presence and locks along. And a config lives in a repository, where anyone
+who can open a pull request can edit it — a file that could declare sessions would be a way
+to hand a peer state it should have had to earn.
+
+### Writing one while sessions are running
+
+The config carries the workspace identity, so writing one moves the project to a new
+workspace. Sessions already attached stay on the old one: they keep heartbeating it, they
+drop off everyone else's roster, and claims they hold stop being seen. They do not recover
+by themselves either — a session attaches when its client starts and at no other point.
+
+So `init` refuses while sessions are attached, and names them:
+
+```text
+2 session(s) are attached here and would stop seeing each other: graphics (claude_code),
+physics (codex). They re-attach only when their client starts, so close them first, or
+pass --force to write anyway.
+```
+
+Close them, or pass `--force` if you mean it — and restart them afterwards.
+
+### Commands
+
+<!-- test:illustration asks a person to confirm; there is nobody to ask in a test -->
+```bash
+acc config init        # preview, then write after you agree
+acc config validate    # read-only; reports what applies
+```
+
+`init` shows the exact file it would write and waits. In a non-interactive run — a pipe, a
+CI job, an agent — there is nobody to ask, so it refuses unless you pass `--yes`. It never
+overwrites an existing config: a committed identity is shared by everyone on the project,
+and replacing it on a mistyped command would split one workspace into two.
+
+`validate` only reads. A command someone runs to find out what is wrong must not change the
+thing it is inspecting. With no config present it reports the defaults rather than failing,
+because not having one is a valid state.
+
+## Delivery policy is not project policy
+
+Live delivery may start a model turn and spend that recipient's tokens, so it is configured
+through the recipient's user-owned client installation:
+
+```bash
+acc install --adapter codex --delivery off
+```
+
+The allowed values are `off`, `actionable`, and `all`; the default is `off`. This setting
+does not belong in `acc.workspace.json`, where a pull request could opt someone else into
+spending a turn. It also cannot create a capability: when the detected exact client
+version lacks passing live-push evidence, installation keeps the effective policy `off`
+and reports durable next-turn or inbox fallback. No shipped adapter currently qualifies
+for native live push.
+
+## Environment
+
+Nothing in `acc.workspace.json` says where state is stored, and nothing there can — that is
+the job of these variables, or the platform's own locations, and ACC refuses any of them
+that resolves inside a workspace.
+
+| Variable | Purpose |
+|---|---|
+| `ACC_DATA_HOME` | Where session, claim, and message state is kept, instead of the platform default (`~/Library/Application Support/acc` on macOS; `~/.local/share/acc` on Linux, or wherever `XDG_DATA_HOME` points) |
+| `ACC_CONFIG_HOME` | The same override, for configuration state the platform would otherwise keep alongside `ACC_DATA_HOME` |
+| `ACC_CACHE_HOME` | The same override, for cache data the platform would otherwise keep under its own cache location |
+| `ACC_PARTICIPANT` | Which participant a session belongs to, when the client does not say |
+| `ACC_WORKSPACE_ROOT` | The project to work in, instead of discovering one from the working directory. Absolute, or it is refused |
+| `ACC_SESSION` · `ACC_GENERATION` | Which session a command acts as when it is not worked out automatically. A supplied generation proves the exact opening; with only a session id the CLI resolves the current generation and refuses ambiguity |
+| `ACC_MCP_PARTICIPANT` | Who `acc-mcp` takes part as. `mcp` by default |
+| `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` | Never ask npm whether a newer ACC exists. `acc update` then says it is off, which is a different answer from "nothing is newer" |
+| `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 |

package/docs/DESIGN_DECISIONS.md

@@ -0,0 +1,89 @@
+# Design decisions
+
+Why ACC is shaped the way it is, and what is deliberately still open.
+
+## Settled
+
+| Decision | Reason |
+|---|---|
+| Local-first, same machine | Coordination that needs a server is coordination nobody sets up. |
+| Git optional | The problem is concurrent sessions, not version control; a plain directory works. |
+| Attach everywhere, materialise lazily | Universal attachment is what makes it ambient; lazy state is what makes a lone session free. |
+| No coordinator, workstream, or task subsystem | ACC connects peers; it does not assign, supervise, schedule, or own their work. |
+| Explicit peer conversations are first-class product data | Addressed questions, answers, decisions, and handoffs need durable threads and per-recipient receipts. |
+| Intent is awareness, not assignment | A session says what it is doing without creating a queue or granting another session authority. |
+| Claims are workspace-global | Independently opened sessions still share a filesystem. |
+| Runtime state outside the repository | A checkout can be deleted, cloned, or synced; presence and locks must not travel with it. |
+| Project config optional and runtime-free | A committed file is editable by anyone with a PR, so it may carry policy — never sessions or tokens. |
+| Durable state is authoritative | Next-turn or live delivery may accelerate an interaction; neither becomes the source of truth. |
+| No heartbeat helper in v1 | An idle session is honestly reported `stale`. A sidecar process to fake liveness is worse than the truth. |
+| Presence reads the process, never writes the record | A pid answers "gone" at once; an age floor covers what a pid cannot, including its own reuse. Nothing is written back — no session has authority to edit another's record. This checks a process already there, not one beating on a session's behalf like the heartbeat helper above. |
+| No process launching | ACC attaches to sessions you already own. Owning them is a different product. |
+| One publishable package | One version and one release rather than twelve coordinated ones. |
+| MIT | Widest reuse, least friction. |
+| Node 24 (current production LTS) | Uses `node:test`, modern `fs` promises, and no transpiler. |
+| MCP session from launch config | Never from `initialize` or `clientInfo` — those are attacker-controllable. See the threat scenarios in [SECURITY_MODEL.md](SECURITY_MODEL.md) (scenario 8). |
+
+## Rejected, and why
+
+| Rejected | Why |
+|---|---|
+| A file in each repo that agents poll | No guard, no identity, no atomicity — and it ends up committed. |
+| A permanent global lead session | Turns peers into workers and makes one crash fatal. |
+| Treating MCP as a lifecycle guarantee | MCP is a tool surface. It cannot attach, guard, or wake anything. |
+| Requiring Git, tmux, PostgreSQL, or a service | Every requirement is a reason the tool is not installed. |
+| Collecting or sharing raw transcripts | Raw transcripts are never collected or shared. Explicit peer messages are bounded records the sender chose to address. |
+| Reporting queued messages as delivered | A delivery state that overstates itself is worse than no state. |
+| Guessing file paths out of shell commands | It would block work at random and still miss real writes. See [CAPABILITIES.md](CAPABILITIES.md). |
+
+**Reversed in 0.1.11: removing the client's hook-trust record on uninstall.**
+0.1.9 took Codex's `[hooks.state."<plugin>:…"]` tables out on uninstall,
+reasoning they named a plugin that was gone. The check behind that reasoning
+perturbed the record instead of removing it — a hook whose recorded hash no
+longer matched was still observed running, so absence was never actually
+tested.
+
+Absence is the whole mechanism. With no record, the client runs no hook at
+all, prints `hook: SessionStart Completed` while executing nothing, and ACC's
+write guard goes silently off — while `acc doctor` and `codex plugin list`
+both report it enabled. On a real machine, a shell write walked through a
+guarded claim; writing the exact same hashes back (captured before deletion,
+from an ACC three releases older) revived the guard immediately.
+
+That is why removal is never ACC's to do: the record is granted once by a
+person, survives ACC upgrades, and nothing ACC writes can restore it.
+Tidiness is not worth a permission only a human can re-grant.
+
+**The generalisation, since this cost a release:** to learn whether state is
+load-bearing, take it away. Changing it tests something else.
+
+**Reversed in 0.1.7: reading write positions out of shell commands.** The
+rejected row above still holds against *guessing* — it stays because its
+reasoning shaped the replacement. What changed was the evidence: a live Codex
+session asked to append to a file another agent held guarded went through
+untouched via `printf ... >> file`. Agents here are told to prefer the shell
+for edits, so this was the common path, not an edge case.
+
+The fix is to read, not guess: only a redirection, or the operand of a
+command whose job is to put bytes somewhere, counts as a write position. A
+read is never reported, so the failure the rejected row feared — blocking
+work at random — cannot occur; only paths a command would actually write get
+declared. Coverage is deliberately partial, and
+[CAPABILITIES.md](CAPABILITIES.md) says where it ends: an agent that knows
+where a guard stops behaves better than one that believes it absolute.
+
+## Still open
+
+1. **Storage backend.** The hardened filesystem store ships first. A transactional backend
+   can go behind the same interface later — but not merely to avoid a dependency.
+2. **Remote coordination.** v2, or a separate product.
+3. **Process launching.** Possibly never; possibly an external integration.
+4. **Multi-root discovery rules** beyond the current `roots` list.
+5. **Default claim lease length** for hook-only adapters. A hook-only session cannot sustain
+   a short renewal cadence, so lease policy must not assume one.
+6. **Windows.** Measured as not working, not merely untested — see the
+   [repository changelog](https://github.com/automatis-tools/agents-can-communicate/blob/main/CHANGELOG.md).
+
+---
+
+See also: [README](index.md) for navigation and [Glossary](GLOSSARY.md) for terms.

package/docs/GETTING_STARTED.md

@@ -0,0 +1,145 @@
+# Getting started
+
+ACC begins with two AI sessions that you open yourself. It does not create a team or choose
+which model does what. The first useful run is a question that travels from one session to
+the other, receives a reply in the same thread, and is acknowledged without you copying
+the message between windows.
+
+```mermaid
+sequenceDiagram
+  participant A as First session
+  participant ACC
+  participant B as Second session
+  A->>ACC: durable question
+  ACC-->>B: next-turn offer or inbox fallback
+  B->>ACC: reply in the same thread
+  ACC-->>A: next-turn offer or inbox fallback
+```
+
+## 1. Install once per machine
+
+Install the package, then let ACC wire only the clients it detects:
+
+<!-- test:command -->
+```bash
+acc install
+```
+
+Restart those clients because hooks load at startup. Codex also asks you to trust the
+plugin. `acc doctor` names anything still missing and reports the effective delivery mode
+for each detected version.
+
+## 2. Open two sessions normally
+
+Open Codex, Claude Code, Gemini CLI, Grok, or Kimi Code in the same project exactly as you
+would without ACC. A generic MCP client can participate by running `acc-mcp`. ACC never
+launches or owns either session.
+
+In either window:
+
+```bash
+acc status
+```
+
+The roster gives the participant ids used by `--to`. If it shows only one session, fix the
+second client's installation or workspace path before testing communication.
+
+## 3. Publish intent, then claim narrowly
+
+Intent is cheap awareness and grants no protection:
+
+```bash
+acc work --summary "updating receipt rendering" --mode edit \
+  --hint 'file:packages/cli/src/main.mjs'
+```
+
+Reserve only what the session is about to change:
+
+```bash
+acc claim --resource 'file:packages/cli/src/main.mjs' \
+  --reason "updating receipt rendering"
+```
+
+Exit code `5` means an overlapping live claim exists. Ask its owner or narrow the edit;
+do not silently work around it. A claim can be `guarded` only where the client exposes a
+certified write guard. Otherwise it remains useful but `advisory`.
+
+## 4. Send a real question
+
+From the first session, address a participant listed by `acc status`:
+
+```bash
+acc message --to models --type question --subject "receipt wording" \
+  --body "Should the UI say offered or delivered after the transport accepts bytes?" \
+  --client-message-id client_receipt_wording_1
+```
+
+The output starts with `recorded message_x`. That is the durable guarantee. Any following
+delivery diagnostic is acceleration, not the source of truth. Reuse the explicit
+`client_receipt_wording_1` key when retrying after an uncertain result; it returns the same
+logical message instead of creating a duplicate.
+
+## 5. Read and reply from the second session
+
+A certified hook may offer the question on the recipient's next normal turn. Grok, MCP,
+unknown versions, and any missed projection use the same durable recovery path:
+
+```bash
+acc inbox
+acc inbox --message message_x
+acc reply --message message_x \
+  --body "Use offered. It proves transport acceptance, not that the model read it."
+```
+
+`reply` creates an `answer` in the original thread and acknowledges the recipient's
+receipt for the question atomically. It does not mark the requested work complete. The
+first session receives the answer through its own next-turn or inbox path; you do not copy
+the peer body between sessions.
+
+Use `acc ack --message message_x` only when the message asks for acknowledgement and no
+written reply is needed.
+
+## 6. Hand off while context still exists
+
+```bash
+acc finish --goal "update receipt rendering" --status partial \
+  --completed "CLI wording changed" --remaining "MCP docs" \
+  --blocker "waiting for fixture"
+```
+
+`finish` records a structured handoff, releases that ACC session's claims, and ends its ACC
+presence. It does not close the external client.
+
+## Delivery expectations
+
+Durable inbox delivery works for every participant. Certified next-turn delivery currently
+exists only for exact captured versions of Codex, Claude Code, Gemini CLI, and Kimi Code.
+Grok and generic MCP poll. No current adapter has certified native live push. Although
+`acc install --delivery off|actionable|all` defines recipient policy, unsupported or
+uncertified clients keep effective policy `off` and report their fallback beside the
+adapter result.
+
+## Optional workspace configuration
+
+No file is required. Use one only for a stable shared workspace id, multiple roots, or
+project policy:
+
+<!-- test:command -->
+```bash
+acc config validate
+```
+
+See [Configuration](CONFIGURATION.md) before writing it. Runtime messages and sessions
+never belong in that committed file.
+
+## Uninstall
+
+```bash
+acc uninstall
+```
+
+ACC removes only installation bytes that still match what it wrote. User-modified client
+settings remain in place.
+
+Next: [Why ACC](WHY_ACC.md) · [Capabilities](CAPABILITIES.md) · [CLI](CLI.md) ·
+[Troubleshooting](TROUBLESHOOTING.md)

package/docs/GLOSSARY.md

@@ -0,0 +1,26 @@
+# Glossary
+
+- **Workspace** — one local coordination room; all worktrees of a Git repository share it.
+- **Participant** — the stable address that sends and receives messages.
+- **Session** — one independently opened client conversation participating in a workspace.
+- **Generation** — the token proving a mutation belongs to the current opening of a session.
+- **Presence** — `online`, `stale`, or `offline`, based only on observed heartbeat and pid facts.
+- **Intent** — a session's current summary and resource hints; awareness, not permission.
+- **Claim** — a leased reservation for a canonical resource such as `file:src/**`.
+- **Advisory / guarded** — a claim peers must respect versus one ACC can stop on measured client write paths; neither stops unrelated local processes.
+- **Message** — an attributed untrusted `note`, `question`, `request`, `answer`, `decision`, or `handoff`.
+- **Thread** — a root message plus linked answers sharing one immutable `threadId`.
+- **Obligation** — `none`, `reply`, or `acknowledge`; what communication the recipient owes.
+- **Receipt** — one recipient's monotonic `queued`, `offered`, `retrieved`, or `acknowledged` evidence.
+- **Offered** — bytes crossed ACC's transport boundary; not proof the recipient read them.
+- **Retrieved** — the participant received the body; not proof of model attention.
+- **Acknowledged** — that participant explicitly acknowledged or replied; a reply is not proof requested work finished.
+- **Next-turn delivery** — certified projection at the client's next normal turn; it never interrupts an active turn.
+- **Live push** — optional delivery to an already-running session through an official certified client API. No shipped adapter currently qualifies.
+- **Recipient policy** — `off`, `actionable`, or `all`; opt-in permission to spend a turn, not a capability.
+- **Delivery binding** — ephemeral, generation-bound reachability data owned by an adapter.
+- **Fallback** — durable inbox or exact-certified next-turn recovery when live delivery is unavailable.
+- **Managed / manual lifecycle** — whether hooks report ACC presence automatically; never ownership of the external client process.
+- **MCP participation** — polling access to durable communication without native lifecycle, context, guards, or push.
+
+See [Concepts](CONCEPTS.md) for relationships and [Protocol](PROTOCOL.md) for exact rules.

package/docs/MCP.md

@@ -0,0 +1,94 @@
+# MCP
+
+`acc-mcp` lets a client with no native ACC adapter participate over stdio. It exposes the
+same durable messages, threads, receipts, intent, claims, and handoffs, but it cannot infer
+the client's lifecycle, intercept writes, inject a normal turn, or push a message. The
+client polls tools under its own control.
+
+```mermaid
+graph LR
+  C["independently opened MCP client"] -->|"stdio JSON-RPC"| M["acc-mcp"]
+  M --> S[("ACC durable store")]
+```
+
+## Register
+
+```json
+{
+  "command": "acc-mcp",
+  "env": {
+    "ACC_MCP_PARTICIPANT": "research",
+    "ACC_MCP_WORKSPACE": "/absolute/path/to/project"
+  }
+}
+```
+
+`acc-mcp` accepts no command-line arguments. `ACC_MCP_PARTICIPANT` is the stable recipient
+identity for this server. It comes from user-owned launch configuration, never from MCP
+`initialize` or `clientInfo`. `ACC_MCP_WORKSPACE` should be absolute; without it, the
+server uses its launch directory, which may be a different workspace from the other
+sessions.
+
+The server implements MCP protocol revision `2026-07-28` over newline-delimited JSON-RPC
+stdio. Tool input schemas are closed: unknown fields and invalid conditional shapes are
+rejected before a session is resolved.
+
+## Tools
+
+| Tool | Required input | Optional input |
+|---|---|---|
+| `acc_status` | — | — |
+| `acc_sync` | — | `cursor`, `scope: delta|full`, `limit: 1..500` |
+| `acc_work` | `summary` and `mode`, or `clear: true` | `state`, `resourceHints` |
+| `acc_claim` | `action`; `resource` for acquire, `claimId` for renew | `mode`, `reason`, `leaseSeconds` where valid |
+| `acc_release` | `claimId` | — |
+| `acc_message` | `to`, `subject`, `body` | `kind`, `obligation`, `clientMessageId` |
+| `acc_request` | `toParticipantId`, `title` | `detail`, `clientMessageId` |
+| `acc_inbox` | — | `messageId` |
+| `acc_reply` | `messageId`, `body` | `subject`, `clientMessageId` |
+| `acc_ack` | `messageId` | — |
+| `acc_finish` | `goal` | `status`, `completed`, `remaining`, `blockers`, `toParticipantId`, `clientMessageId` |
+
+All tool names above are the complete model-facing surface. There are no execution or
+client-control tools.
+
+Send-like tools return a raw structured object with `{ message, delivery }`; their text
+content is the JSON serialization of the same value. `acc_inbox` returns message/receipt
+pairs and advances only this participant's receipts to `retrieved`. `acc_reply` writes an
+`answer` and acknowledges the original atomically. `acc_ack` exposes no receipt-state
+parameter.
+
+Resources are `acc://snapshot`, `acc://roster`, and `acc://inbox`. Reading `acc://inbox`
+resolves the configured MCP participant and advances only the returned receipts to
+`retrieved`, just like the inbox tool. Snapshot and roster reads do not advance receipts.
+A full snapshot is for explicit workspace forensics.
+
+## Capability floor
+
+The generic MCP capability declaration is all false:
+
+| Group | Effective behavior |
+|---|---|
+| lifecycle | no automatic session-start, resume, or end signal |
+| context | no startup, before-turn, or safe-point injection |
+| guards | no before-read, before-write, or before-shell interception |
+| delivery | no `nextTurn`, `livePush`, or native `replyRoute` |
+
+An MCP participant therefore reports `advisory` enforcement and `manual` lifecycle.
+`manual` describes ACC presence reporting, not ownership of the external client. Because
+workspace protection is the weakest live participant's real guarantee, one MCP session
+makes guarded claims advisory for the room.
+
+## Durable polling semantics
+
+Every outgoing message commits first. `acc_message`, `acc_request`, `acc_reply`, and
+`acc_finish` cannot promise push; delivery results remain queued with a durable diagnostic.
+The recipient calls `acc_inbox` to retrieve the body. Being returned by a tool is
+`retrieved`, not proof that a model attended to or obeyed it. A reply or explicit ack is
+`acknowledged`.
+
+MCP is therefore a complete communication participant with higher latency, not a fake
+native adapter. Use it when a client can call tools but exposes no measured hook boundary.
+
+Next: [Protocol](PROTOCOL.md) · [Capabilities](CAPABILITIES.md) ·
+[Security model](SECURITY_MODEL.md)