Claude connector reference

This page describes the Claude-specific adapter and its shared mesh runtime. For setup and launch procedures, see Connect Claude. The wire specification defines the protocol.

BindingCopy Anchor Link

Claude Code exposes four integration surfaces, and three of them collapse into a single dual-purpose MCP server:

The manager launches the real claude (no wrapper):

claude --mcp-config '{"mcpServers":{"cotal":{…}}}' \
       --dangerously-load-development-channels server:cotal \
       --permission-mode bypassPermissions
# env: COTAL_SPACE, COTAL_NAME, COTAL_ROLE, COTAL_CHANNEL=1, plus claude's documented auth vars

• Tool permissions. A managed seat has no human at its terminal, so it launches with --permission-mode bypassPermissions: a prompt under the default mode would stop its first mesh tool call until someone answered it, and nobody can. To get prompts back, pass --opt permission-mode=default (or another mode); the connector adds the default only when the launch options carry neither permission-mode nor dangerously-skip-permissions. A foreground cotal spawn runs in your terminal, so it keeps Claude's own permission mode and you answer its prompts there. Claude refuses the bypass mode as root and under a policy that disables it; such a host must pass a mode. Claude also asks each user to accept the bypass mode once, in a warning only that user may answer. Cotal never answers it. A managed seat that stops on it fails at the startup bound, and the error names both ways forward: accept it yourself once with claude --permission-mode bypassPermissions in a terminal, or launch with --opt permission-mode=default.

• Model auth. Locally, claude still reads macOS Keychain / ~/.claude. In a container or CI there is no Keychain, so the connector forwards the documented credential set: CLAUDE_CODE_OAUTH_TOKEN (from claude setup-token), ANTHROPIC_API_KEY / ANTHROPIC_AUTH_TOKEN, and the cloud-provider flags plus their credential vars. Host-session markers (CLAUDE_CODE_CHILD_SESSION, CLAUDECODE) stay out so a nested seat still saves a transcript. See Deploy.

• Persona privacy. The persona body is written to a private file and Claude receives only --append-system-prompt-file <path>. The body never appears in the spawned process argv. The carrier is a 0600 file inside a 0700 directory on POSIX, with equivalent owner-only ACL hardening on Windows. That is OS-user isolation: any process running as your user can read it while it exists. The manager or the foreground cotal spawn removes it, and the shared-server MCP config file, once it has proved the claude process gone. If the launcher is killed first, a watcher started beside claude removes them when claude exits.

• MCP servers. A spawned agent loads Claude's native MCP sources alongside Cotal and declared sharing overrides. Explicit --share-tools selections and carried private homes keep strict isolation. Claude still applies its own server approvals, disabled settings and managed policy (see below).

• Lean MCP server. Every session runs its own cotal MCP server, so Node starts it with --optimize-for-size --max-semi-space-size=1 to shrink its memory footprint. Managed launches and the plugin's .mcp.json (personal plugin sessions) both pass these flags. --lite-mode and --jitless would save more, but they remove WebAssembly, which Node's built-in fetch needs, so WebAssembly stays enabled.

• Light hook. Claude Code starts the plugin's hook as a new process for every tool call, prompt and stop. The hook imports @cotal-ai/core only through small subpaths such as @cotal-ai/core/peer-label, never the package root, which would bundle YAML and NATS into it. pnpm smoke:claude-hook-weight holds that.

• Installed plugin. The plugin is installed once, at user scope (claude plugin install cotal@cotal-mesh --scope user), because its hooks bind only to an installed plugin. Earlier releases installed it per project, at local scope; the next cotal setup removes those installs and keeps the user-scope one. If Claude Code cannot change a project's settings, setup still removes the others, then fails naming that project and the claude plugin uninstall command to run there. cotal update does the same for a machine that has only per-project installs: it installs the plugin at user scope and removes the per-project installs that had it on, keeping one a project turned off and any project-scope install. An account that turned the plugin off in its user settings keeps its per-project installs as they are. A session Cotal launches loads the package's own copy with --plugin-dir, which replaces the installed one for that session, so it still runs one cotal server. The repo's .claude-plugin/marketplace.json lists the committed plugin tree under claude-plugin/, which each release regenerates with the built bundles, the skills and the release version, so an install from the repo or from a pinned commit runs without a build (Release). cotal setup (npx, no clone) materializes the same marketplace under ~/.cotal/claude-plugin/ from the installed CLI (each plugin dir is rebuilt from scratch and atomically replaced, never merged, so no stale file rides in). The cotal-skills plugin installs from that same marketplace at user scope (claude plugin install cotal-skills@cotal-mesh --scope user); its manifest and install behavior ship inside the Claude connector, and its version tracks the CLI release so updates land.

• Identity-gated. A launched session joins under the identity in COTAL_NAME, COTAL_LINK or COTAL_AGENT_FILE. A plain claude with none of them joins only when its conversation calls cotal_connect, so your own sessions do not appear as stray peers. Until then its MCP server builds no mesh agent and opens no broker connection. See Sessions Cotal did not launch.

• Hands-free. The dev-channels flag prints a one-time confirm prompt. The runtime waits for the dialog title in normalized terminal text and presses Enter once when it appears, so startup speed does not affect a supervised launch. Claude skips that prompt when channels are off for the session, for example under a Team or Enterprise organization whose managed settings do not set channelsEnabled: true, and opens its input screen instead. The runtime then ends its watch without a key once the input screen's footer shows (shift+tab to cycle) or ? for shortcuts on two screen reads in a row. That seat gets mesh messages through its hooks only, so a message does not wake it while it is idle. For a once seat the answered prompt is not enough: the watch then reads for up to 15 more seconds for Claude's notice that server:cotal messages reach the session, however many lines a narrow pane wraps it onto, and the seat is served its task only after it sees that notice. A seat that opened its input screen, or answered the prompt without the notice, fails its spawn and is stopped. The PTY runtimes read the child's screen, and the tmux, cmux, Orca and Herdr runtimes read the pane's screen. If neither the prompt nor the input screen appears within 15 seconds, the seat ends with a bounded error naming the unmatched prompt instead of hanging silently or answering another dialog. Claude's first-run screens, the text style picker and the login method choice, and its Bypass Permissions warning are screens Cotal never answers. When the bound ends on one of them, the error names it and the step that clears it, such as running claude once in a terminal as that user to finish setup and log in. The PTY runtime writes that error to the seat's output and stops the child as a graceful stop does, so a child that ignores SIGTERM is killed 3 seconds later. Confirmation ends before the stop begins, so later child output receives no startup response. The other runtimes write the error to the manager's log.

• Trusted directory. An authorized supervised spawn accepts the selected workspace through Claude's native trust dialog, which Claude draws in one of two layouts. When a numbered list shows Yes first and selected, the runtime confirms it with Enter. When No comes first and is selected, the runtime moves to Yes and confirms only after seeing Yes selected. It never confirms while No is selected, sends each response once, and stops watching after the development-channel confirmation or on the input screen. A changed or unsupported dialog receives no guessed input and still fails within the startup bound. Claude saves trust with its own repository and linked worktree rules; Cotal does not rewrite the manager's configuration. Accepting trust enables the workspace's hooks and settings, which can select a tool permission mode when no launch flag overrides it. Cotal adds no tool-permission bypass flag. Review the checkout before authorizing a spawn there. A foreground cotal spawn keeps the trust dialog in your terminal.

Inbound mesh messages arrive in context as <channel source="cotal" from="bob" kind="dm" …>…</channel>: each meta key a tag attribute the agent can read for routing.

The consuming connector holds a crash-safe claim for its broker target, space, principal and lifecycle on this OS user account. A second patched session on the same host refuses before pulling that inbox, even when its launch files and control socket differ. Reconnect keeps the claim. Hooks and non-consuming helper connections do not claim it. The control listener binds before the broker connection. On Unix, a restart probes an occupied socket path and retries once after removing a leftover with no listener. A live listener, an inconclusive probe or a Windows named-pipe collision still refuses the bind.

This is cooperative same-host containment. Other hosts, broker URL aliases and older clients are not fenced. Preserve the existing session before choosing a distinct actor for a new launch. An uncertain shutdown keeps custody until the consuming process exits.

The seat entryCopy Anchor Link

The launched entry is dist/seat.cjs. It enables Node's module compile cache and then loads dist/mcp.cjs, which holds the server. The cache stores V8's compiled form of that 5 MB bundle, so every launch after the first one skips parsing it, which keeps about 5.7 MiB per seat out of the process's malloc arena for as long as the seat runs.

The cache lives in ~/.cotal/compile-cache (%LOCALAPPDATA%\Cotal\compile-cache on Windows), the OS user's own Cotal directory, which COTAL_HOME never redirects. Node keys a subdirectory inside it, so a Node upgrade pays one compile and reads no stale entry. The directory grows to the size of one compiled bundle per Node version, under 1 MB each, and deleting it is safe at any time: the next seat writes it again.

The directory is created with owner-only permissions, whatever the launching umask was, because a compiled bundle belongs to the user who ran the seat.

Two things the cache never does. A cache it cannot open, such as a read-only home, prints one line to stderr with Node's reason and the seat serves without it. NODE_DISABLE_COMPILE_CACHE=1 turns it off silently. Setting NODE_COMPILE_CACHE to a directory of your own takes precedence over both: Node enables the cache there at startup and the seat leaves it alone.

This entry needs Node 22.10 or newer, which is where module.flushCompileCache() lands, and that is the floor cotal-ai declares. On anything older the entry prints one line naming the floor and the running version and exits without serving, rather than starting a seat that dies on its first flush.

Nothing else moved. node dist/mcp.cjs is still a working seat launch for a config written before this entry existed, and it pays the compile on every start. It needs no compile cache, so it is also the way to serve from a Node older than the floor.

Personal sessionsCopy Anchor Link

A Claude Code session you start yourself, where the cotal plugin is installed, gets the tools the hosted connector offers: cotal_connect, cotal_wait, cotal_disconnect and the routed mesh tools. Nothing joins until the conversation calls cotal_connect with a name. The plugin's server then runs cotal app-identity provision with the CLI that cotal setup recorded beside the plugin (dist/cli.json), so it does not need cotal on PATH. Each conversation gets an identity of its own once a person approves it. To choose a registered mesh for this conversation, pass space:

{"name":"my-session","space":"cotal_cloud"}

This is the native plugin's cotal_connect argument. It takes precedence over the saved selection and the project folder, without changing either. cotal space lists this machine's registered spaces. A blank or unknown space is refused; it is never replaced by another mesh. With no space, the plugin uses the mesh a bare cotal spawn from the session's directory would pick, following the CLI's selection rules. Do not rename .cotal directories or add COTAL_SPACE to choose a personal conversation's target.

A connected conversation must call cotal_disconnect before choosing another name, space or grant. Before it connects, you can change a pending name or permissions by calling cotal_connect with the new values and no approval_id. You do not need to approve the unwanted request or start another conversation. The old watcher stops, the saved request is recovered and retired, and the replacement gets a fresh approval. Changing the space follows the same cleanup rule. If approval raced the change, its issued identity is retired before the replacement is requested; its grant is never reused. An unconfirmed retirement blocks the switch and keeps the old recovery record. A second host cannot replace a request while its original consumer is still alive.

The hosted HTTPS connector chooses its space during browser authorization. Its OAuth grant is bound to that space; a native space argument cannot retarget a hosted grant.

A static-auth or open mesh has no page where a person approves a connection, so the plugin opens no identity there. A plugin that cotal setup did not install has no record, and cotal_connect names that remedy.

Personal native Code sessions can join a signed-in mesh whose authority offers connection approval. The plugin binds the real native session and transcript before requesting an identity. Each conversation gets a separate actor. A new identity is issued only after a person approves it in the authority's signed-in web page. A model's tool arguments, a client flag or a native tool approval never approve it. The request first comes back pending with the page's address and its expiry, and nothing is issued yet. Connecting again sends the same request and secret: while it is pending it answers the same page, and once approved it issues the identity. A denial or an expiry drops the request, and the next connection asks again. No login proof reaches the conversation or its tools.

While a bound Code conversation's request is pending, the plugin's server replays that same request to the authority every ten seconds, serialized with the conversation's own cotal_connect, until the authority records a decision, the request passes its expiry, or the session ends. The server issues nothing by itself: an approved replay receives the identity the authority issued for that request, and the server holds it, unclaimed and unconnected, for the conversation's own cotal_connect with the same name and the approval_id from its pending result. The decision reaches only the native session that asked, through its wake reader, as one fixed line: approved (naming the approval_id to finish with), denied, or expired. Nothing else is written that way, and the native module admits no other shape. A session that ends before claiming an approved identity has it retired; a request still pending when the session ends stays saved, and the CLI finishes it before that conversation's next request. An approval_id that is not this conversation's own pending request is refused before any request is sent. Desktop chat has no native reader, so there the person asks Claude to retry. A remote mesh must advertise conversation identity v1 and connection approval v1 on its pinned HTTPS discovery endpoint. An absent capability, a different origin or a changed registration is refused before authenticated issuance, for a request without a selection too. There is no immediate-grant fallback. A signed-in mesh whose authority this machine holds has no approval page, so it issues no new identity either.

Every identity sends and receives direct messages and publishes its own activity on its own event channel. These come with the identity and are not optional, so the approval page shows them before the person decides. Native activity sharing includes the messages the person types, assistant replies, and each tool call's name with its start and end, after activation. It is not only presence or status. Tool arguments and tool results are withheld from the event channel, as on every connector (Event plane). While a tool waits for permission, presence shares only its tool name, never its command or arguments, with every roster reader. Reasoning is not shared by default, and earlier or pre-approval history is not shared. The space's activity read permissions determine who can read the event channel. Decline the connection if you do not want this sharing. A request without a selection proposes nothing beyond these rights: no role, capabilities or ordinary channel reads.

cotal_connect in a native Code session also takes a selection: channels to read (access: "read") or read and post to ("read-post"), a role, and capabilities (spawn, run). The selection is a proposal. The person may approve it, change it within their own current access, or approve nothing beyond the identity's own permissions. The issued grant must match what the person approved item for item, or the connection is refused. When the authority refuses an item outside your own grant before asking anyone, nothing is issued and the reply names every refused item. There is no fallback to the event-only identity. Its own event channel stays the first post entry. A remote mesh must also advertise conversationIdentitySelection version 1, or a selection is refused before any request. Endpoint calls are not selectable through this connection approval contract, which accepts only an empty endpoint selection. These conversations do not offer cotal_endpoints, cotal_describe or cotal_invoke.

A connection is offered the tools its grant can use: cotal_spawn, cotal_persona, cotal_personas and cotal_despawn with spawn, and cotal_run, cotal_turn_participate and cotal_yield with run, plus cotal_reconnect. Its manager calls exchange the conversation's own secret for a manager-call view, so they carry only its grant and name the manager instance when more than one could answer. A conversation is not a managed seat. cotal_despawn without a name refuses rather than stopping your app, and cotal_disconnect retires only that connection.

cotal_turn_participate opts the exact personal lifecycle into workflow turns for a short lease. Call it before starting a program that uses participant(), and renew it before expiry or after a reconnect. The manager verifies the current foreground grant still has run, the exact lifecycle is current and live, and the request came from that lifecycle. A hosted program can then bind only the conversation that admitted the run. Pending turns arrive through the native session reader. An explicit cotal_yield reports done, blocked or handoff; ending the native host turn reports done automatically. Participation never adds stop, attach, input or terminal custody. Persona text and model pins do not change the conversation's own instructions or model.

The plugin's ordinary command hooks supply the session and transcript binding. Its native module uses that binding without intercepting classic.* events, which Claude's built-in security guard withholds from user plugins. The guard stays enabled. If an organization disables command hooks or native modules, its administrator must permit them before this connection path can work. Command hooks still report lifecycle status and activity; the native module owns incoming message delivery.

A signed-in identity keeps its request and secret in private local recovery state. A lost create response retries the same request without rotating its secret or allocating another identity. Retiring a request that is still pending drops it, and no identity is issued for it. An identity issued before connection approval keeps working, and its recovery stays exact. Another plugin server reuses that identity only after the process that held it no longer exists. cotal_disconnect, session end and a signal request retirement of that lifecycle only. Other conversations stay connected. When the mesh reports retirement pending or does not confirm it, the conversation stays disconnected and keeps its saved record. Every tool then reports the same unfinished cleanup with the mesh's retirement phase. Calling cotal_disconnect again retries it at once. cotal_connect retries it too, and connects with a new identity once the mesh confirms retirement. A restarted plugin server recovers the same way. After each connection, the plugin retires the same mesh's saved identities whose plugin server process no longer exists, such as one killed before it could retire them. This runs in the background, so the connection does not wait for it. A server process that still exists keeps its identity, and a retirement that does not finish stays saved for a later run. A mesh requiring events refuses a connection without a native transcript source.

The gateway's MCP annotations distinguish read-only queries from updates. Orientation, connection status, the roster, the docs and channel information are read-only. Sending messages, connecting and joining channels are additive. Inbox reads and waits consume messages; status, channel mode, leaving and disconnecting can replace or remove state. These hints do not grant access or override Claude's permission settings or an organization's approval policy.

A message for a connected conversation starts a turn through the plugin's native hooks module. This works in supported Claude Code hosts, including local sessions in the Desktop app's Code tab. The module runs a local wake reader as a child of the same host that runs the MCP server. Each server uses its own socket in a private directory. Short messages arrive in full with their sender, message ID and reply context. Claude can answer these without calling cotal_inbox. The module uses Claude's plugin-sender attribution, never the person's own identity. While Claude is busy, delivery happens at a main-conversation tool boundary before the next request. A request already being sent has a fixed message snapshot. A later arrival waits for another tool boundary or starts its own attributed turn when the current turn ends; storing a note alone does not count as delivery to that request.

Each inline batch carries at most eight whole messages. Each rendered message must fit within 1,024 Unicode code points, and the encoded socket frame must fit within 4,096 characters. Larger messages remain queued. A notification-only reader or an oversized message uses Cotal: a new message for connection_id <id>. Read it with cotal_inbox. and a bounded preview. A preview is incomplete; Claude reads its contents through the inbox. An inline batch also names how many other messages remain pending.

The transcript shows a compact Cotal indicator. Expand it to inspect the delivery or preview. This changes only the display. Presentation observes only prompt rows; in-turn appends use their returned row ID, without observing protected notes or skill output.

Socket writes and previews do not acknowledge messages. A complete inline batch is committed only after the native host confirms admission to the bound conversation. An idle prompt also needs its stored prompt row; a busy append needs its returned row ID and complete stored text. An offer waits for a busy conversation's next safe boundary while its reader remains connected. Admission after claim has its own deadline. This confirms host handoff, not that Claude understood or completed the work. Delivery remains at least once after an unknown result. Message IDs distinguish retries from new requests.

A wake follows the rule cotal_wait follows and does not compete with an active wait. Confirmed inline delivery rearms the next wake without an inbox call. A replacement reader reoffers unread work. An offer from a closed connection cannot suppress its replacement connection's messages. Claude's Stop and organization controls still apply. Refused delivery stays pending without a retry loop; genuine person-origin input resumes it with a fresh offer. cotal_connect reports whether the incoming reader is attached; attachment alone does not prove native admission. When native modules are unavailable or blocked, the conversation can listen with cotal_wait.

Claude Desktop chat does not run a plugin's local server. On macOS and Windows, where Claude Desktop is installed, cotal setup adds a cotal server to Desktop's own config, claude_desktop_config.json (Settings > Developer > Edit Config), and keeps every other entry there. It runs the same server with --desktop, by the absolute paths of the node that runs the CLI and of the plugin copy under ~/.cotal/claude-plugin. Quit and reopen Claude Desktop to load it. A repeat cotal setup and cotal update keep the entry current, cotal status reports it, and a config file that is not valid JSON is refused and left as it was. Desktop reads that file when it starts and writes the copy it holds back while you use it, so an entry added while it runs is lost. On macOS, setup and update therefore leave the file alone while Claude Desktop is running, finish the rest of their work, and say so. Quit Claude Desktop, then run cotal setup again from a terminal outside it; a terminal in its Code tab keeps Desktop running. On Windows they still write while Desktop runs, because the loss was not reproduced there. Setup can use Desktop's bundled Code executable when there is no standalone claude CLI. Its installed MCP and command hooks use the recorded Node executable, so the app need not find Node on PATH. On Linux, setup writes nothing for Desktop Chat.

Desktop Chat supplies no native Code transcript binding, so this local server cannot join a signed-in space, such as one on Cotal Cloud, and refuses before identity issuance. Desktop Chat joins a signed-in space only through the hosted connector that the space's discovery document advertises as cloudCapabilities.hostedConnector, version 1 with an HTTPS URL. Add that URL in Claude under Settings > Connectors > Add custom connector. Setup for a signed-in space writes no Desktop entry and prints the URL instead. cotal status prints it on the Claude Desktop row when the selected space is signed in, and the refusal names it. When the space advertises none, all three say so. The Desktop server's instructions tell the model to use the hosted connector for a signed-in space. The hosted connector is a separate connection path; it does not supply autonomous chat wake.

Desktop's working directory is not your project, so its mesh is the cotal use mesh, else the only one running. Desktop runs no monitor, so a Desktop conversation hears messages when it calls a tool, and keeps calling cotal_wait when you ask it to keep listening. A chat with no turn running cannot be woken by any server: Claude's chat surfaces start a turn only from the person.

Message deliveryCopy Anchor Link

Durable deliveries land in the connector's inbox from JetStream consumers (SPEC §8); live channel traffic can instead arrive through an at-most-once core subscription. A durable message sent while the agent is busy or offline waits on the stream. Two things move a message from inbox to model; one delivers, the other only wakes:

• Hook drain (delivery). SessionStart / UserPromptSubmit hooks read automatic inbox items and inject them as additionalContext. This is the single authoritative path: deterministic and works on any Claude Code build. Quiet ambient is excluded and stays buffered for cotal_inbox. Each hook context stays within 9,000 characters, below Claude Code's 10,000-character inline limit. Complete messages that fit are handed off. The reply counts the messages still waiting, which remain unacknowledged for another hook or cotal_inbox. A message too large for one hook is left for the inbox, which can return it in parts. The budget includes the orientation card, the session briefing, run turns, repeat labels and waiting notice. If a channel notice accompanies a batch the hook already delivered, an empty cotal_inbox reply identifies the most recent confirmed hook handoff by count and event. It does not return those bodies again or describe the receipt as a new message. A confirmed handoff means the hook output was written, not that Claude read or acted on it. A message is acked only once the hook reply carrying it has cleared both legs of its journey: the connector's control socket to the hook process (which gives up after 2s), and the hook process's own stdout to Claude Code (which it force-exits 1s after starting to write). The relay sends a receipt back down the control socket from that stdout write's callback, and only on a clean write (a runtime whose pipe has gone away fails it), and the connector treats that receipt, not its own socket write, as delivery. So a large injection killed mid-flush, or one written to a broken pipe, leaves the message un-acked and JetStream redelivers it. What this does not prove is that Claude Code read or applied the reply: a payload small enough to fit the pipe buffer is reported written the moment the kernel takes it. That residual is why the path errs toward at-least-once rather than treating a confirmed write as a confirmed read. Acking when the reply was merely formatted meant a lost reply was a lost message: it was already marked handled, so its own redelivery was silently acked on arrival. A hook whose handler throws still returns an empty reply so the session is never blocked, and that reply carries nothing, so it commits nothing: the batch it had started to surface stays un-acked and goes out on a later frame. A manager-launched seat pulls its run turns (turn-pending) when its manager's turn notice arrives, when it connects, and after a reconnect while it holds a turn. The manager repeats a notice until the seat pulls the new turn, so an idle seat sends nothing. A pull that fails because the manager is down or unanswered is retried once every 15 seconds until one succeeds; a refusal is logged and not retried. The seat also drops any turn-pending row that breaks the manager contract, such as a run's turn with no integer deadline, and says so once in its log. A reply with no turns array changes nothing: the seat keeps the turns it already holds. This errs toward at-least-once: if a reply lands but its confirmation does not, the batch is surfaced again and flagged as a possible repeat. A duplicate injection is noise; a buried DM stops the peer answering at all.
• Channel nudge (wake). An arriving message fires a notifications/claude/channel event that wakes an idle session into a turn, so the drain runs now instead of at the next prompt. The nudge never acks anything. A nudge that the host rejects is retried with a bounded backoff while anything is still pending. For an idle session it is the only wake source, so dropping it means silence until someone types. When the channel becomes active, the connector first re-fires a focus mention remembered during startup, otherwise one buffered wake. A rejected push keeps its bounded retry, and JetStream redelivery remains the durable backstop for unacked inbox items. Neither a redelivery nor that retry repeats a nudge already pushed for that message, whether the message had its own nudge or was counted in a batch one, so a session held in a long tool call gets one nudge per message. Once a hook frame carries the message, or the push that announced it fails, its next redelivery nudges again, so a reply that never reached Claude Code still recovers. If the channel cannot run at all, delivery still waits for the next hook. Live-only traffic has no durable retry.

Two priority tiers. A directed message (DM, anycast, or a channel message that @mentions us) always nudges. Ambient channel chatter does not nudge mid-turn; it accumulates, and the Stop → idle transition fires one batch nudge so the backlog drains together.

Constraints (accepted). Channels are a Claude Code research preview (≥ v2.1.80; permission relay ≥ v2.1.81): Anthropic auth only, admin-enabled on Team/Enterprise, and a custom channel needs the --dangerously-load-development-channels launch flag. The hook drain does not depend on any of that; the channel only adds "wake me when idle."

The same channel also relays tool-permission requests onto the mesh, so a peer (a human at the CLI, a policy node) can approve or deny an agent's pending tool call through Cotal rather than a per-terminal prompt.

AttentionCopy Anchor Link

An agent picks how aggressively peer traffic reaches it with cotal_status({ attention }) (three modes, orthogonal to presence):

Per-channel overrides refine this: quiet (delivered, never wakes; @mention still wakes) and muted (dropped on receive, mentions included; DMs/anycast unaffected), set with cotal_channel_mode or as agent-file defaults (quiet: / muted:, agent files). A per-channel override is the final word for that channel. Quiet ambient is pull-only: it never hitchhikes on a human prompt, DM, mention, or other connector-driven turn. cotal_inbox explicitly surfaces and clears it. A quiet-channel @mention remains automatic and injects normally.

A pull is bounded too, and clears only what it hands over. One cotal_inbox call carries at most a receivable window (direct messages and role requests first, then channel traffic, replayed history last); whatever does not fit stays buffered, is named in the reply, and comes back on the next call. A message too large for one whole response is delivered in parts: once no smaller mail is waiting, each call carries its next part, and it is cleared only after its last part goes out, because clearing what was not handed over is the loss this bound exists to stop. That matters most on the path where it is easiest to lose mail: reconnecting brings a channel-history replay with it, so the largest payload and the least expendable message arrive in the same read.

The local inbox is bounded. On pathological overflow it evicts pull-only items first, then other channel traffic, and a direct message or role request only when the whole buffer is directed mail. It never evicts a message the connector is handing to the session or a turn is still carrying. An evicted channel item is acknowledged. An evicted direct message or role request never is, and the broker redelivers it after the ack wait until a redelivery finds room. A direct message stays pending on the session's DM durable, where cotal deliver pending <name> counts it. A role request stays on its role's shared queue, which that command does not read. A full inbox therefore delays directed mail until the session drains it. If the bounded live/durable classification guard also fills, the connector fails closed: otherwise-normal ambient becomes pull-only until restart. Muted hard-drop and normal focus recall still take precedence. Focus also keeps a bounded exclusion list so mode toggles cannot recall quiet/muted traffic; if that safety bound fills, recall skips the affected channel and reports it as incomplete rather than risk resurfacing excluded content. While focus recall is unsafe on a channel, a new non-historical mention on that unmuted channel still wakes the agent and its body stays in the bounded pull-only inbox, never automatic, including on quiet channels. Ambient traffic keeps its existing handling, and the incomplete-recall warning still names the unsafe channel. Recall cannot tell one message with an empty id from an identical one with another disposition, so in focus such a message is held in the local inbox as pull-only instead of being dropped, and a mention of it still wakes the agent. When the session settles an id-less copy, it reads the chat stream's last sequence. Identical copies arrive in stream order, and those reads can answer out of order, so the first read that can see the copies binds them in arrival order, latest first, each to the latest unbound stream copy at or below the lowest sequence read for it or any later identical copy. While the connection stays up, every stream copy at or below that sequence reached the session first, so a later identical copy sent during a reconnect gap is above it and stays unbound. A copy that arrives while a read runs may not be in that read, so it binds nothing there and recall reads the channel again, up to three times; if it still could be a stream copy in the last read, recall leaves that stream copy in the stream and reports the channel as incomplete. A settled copy a complete read cannot bind is behind the focus start or out of retention, and is forgotten. Recall hands back into the inbox only the stream copies nothing is bound to, such as one sent during a reconnect gap or one the inbox evicted on overflow, and cotal_inbox hands each over once. Overflow frees only the evicted copy, held or quiet, and a copy no read has bound yet keeps its place in arrival order, so an identical muted copy stays out of recall. When the inbox is full, recall leaves them in the stream for a later call and reports the channel as incomplete. A history read that fails, or a channel with replay off, settles nothing and is reported as incomplete, and recall calls run one at a time. If the sequence read for a settled copy fails, or answers only after the connection dropped, recall skips that channel for the rest of the focus period and reports it as incomplete. Recall cannot tell a late copy of a message it handed back from a new identical message, so every copy takes its own disposition: a new identical quiet mention is still delivered automatically, and a late copy can surface a second time. A recalled message that already went out in part is read to its last part, even if an exclusion lands after its first part. One session reads its inbox one call at a time: a cotal_inbox call that overlaps another waits for it to finish, so neither decides from a view the other has already moved past. If the separate hard-drop disposition guard fills, ambient channel traffic is suppressed for the rest of the session. Non-historical mentions on unmuted channels still wake the agent, with their bodies held in the bounded pull-only inbox instead of injected into a turn. Muted traffic and historical mentions remain suppressed, and known earlier hard drops stay excluded after a mode change. The inbox reports exhausted drop tracking and incomplete focus recall. cotal_connection_status reports degraded with channelDeliveryIssue, even when the transport is live. Restarting clears this session-local degradation. After exhaustion, a late redelivered copy of a mention first received while the channel was muted can surface once as a pull-only mention. DMs and anycast are unaffected.

Attention is advisory UX, not a boundary: any peer can wake a dnd/focus agent by naming it, and muted means "I opted out of receiving", not "the channel is blocked"; the broker still authorizes and delivers. Focus's real effect is shrinking the untrusted-ambient injection surface (only subject-authenticated dm/anycast auto-inject). It resets to open on SessionStart, so a restarted agent never stays silently deaf. Your attention is mirrored into presence so peers can see it.

Whatever does reach a turn is framed so a peer cannot write the frame. A line that begins at column zero is written by the connector; one message is one line plus indented continuations, with the sender inside a single bracket pair. A message body, a sender name and role, and a service or channel label are all peer-controlled, so each passes through the same neutralization the cotal_inbox reply uses: no line break a splitter may honour and no bracket survives into a rendered attribution. This matters more for an injected block than for a reply, because the agent did not ask for it and so never had the chance to distrust it.

Presence mappingCopy Anchor Link

The connector wires a small subset of Claude Code hooks to presence states; presence is coarse, and "what it is doing" rides on activity updates. Presence is advisory: a presence publish that fails (the endpoint mid-reconnect, say) is swallowed and never prevents the same hook from delivering messages or flushing held ones. A SessionStart during an open turn, including compaction, preserves the current working or waiting status until Stop, StopFailure, or SessionEnd closes the turn.

The connector also leaves gracefully when its stdin closes. An MCP client closes it to end the session, and a killed claude closes it with no SessionEnd, so a dead session drops off the roster instead of staying on it as a live peer.

StopFailure maps rate_limit and overloaded directly; auth and credential failures to auth; account and billing failures to billing; invalid_request to request; model_not_found to model; server_error to server; max_output_tokens to context; and unknown to failed. The native value remains in condition.source.

Hooks are relayed over the connector's authenticated local control endpoint (per-user socket + per-launch token, constant-time checked), so a local process that finds the path still can't drive presence or stop the agent. Claude Code's own hooks reference lists every hook event. The hooks the plugin registers, with their matchers, are listed in the adapter README.

Event planeCopy Anchor Link

A connected native session publishes a structured account of its activity: the messages a person typed, assistant replies, run boundaries, and each tool call's start and end. Tool arguments and results are withheld (below), and a turn a peer message started opens a run without republishing that message. Reasoning is off by default. Programs can read these events directly. The launcher sets COTAL_EVENTS by default; pass --no-events to opt out on an unrestricted space. A user-auth registration with policy: { events: "required" } carries eventsRequired in the private launch material, so the connector arms even without COTAL_EVENTS; --no-events is refused. A hand-driven user-mode session may carry the same decision as COTAL_EVENTS_REQUIRED=1. Its own publish grant must cover events.<owner>.<actor> or the connector refuses before joining. A personal native Code connection to a signed-in mesh uses the same recorder and captures its transcript boundary after approved issuance, before joining. Earlier history and time spent waiting for approval are not published. Its native lifecycle drives presence and recording for that session only; a subagent or another conversation cannot end its main run. The event channel keeps the space's normal read permissions. A personal connection makes manager calls only with its own selected grant.

If the event plane stops, the seat keeps running and its mesh connection, on every connector and on every space. The connector log records AG-UI emitter stopped with the reason and the delay before it re-establishes the plane: at once after a failure, then every second while the plane stays down, a fixed wait that neither grows nor is capped, so the plane is back within a second of the fault clearing. The re-establish is a fresh start: it reopens the write-ahead log, settles any frame it left pending, builds the mapper from the run the log has open, and reads on from the stored cursor, which is the same recovery a connector restart runs. A failed publish or a failed log write is never retried on the emitter it failed on. A turn that ends while the plane is down keeps its terminal, and so does a turn whose terminal's own log write failed: once the re-establish has read on, the run the log had open is closed with that terminal, a failure as a failure, rather than left open for the next prompt to close as a finish. That holds when the next prompt was already written before the plane came back: the failure is published after the failed turn's own records and before the next run opens, in a frame of the failed run, since a run error names no run and the frame is its only attribution. Every turn that ends while the plane is down keeps its own terminal. A terminal belongs to the last turn the transcript had begun when its hook fired: the connector reports a turn's terminal once that turn's records are written and before the next turn's are, so the position the transcript has reached at the hook names the turn, including a turn the connector opens no run for, such as a task notification, which takes its terminal and publishes nothing. A terminal repeated for a turn that has one replaces nothing and is kept for no later turn. A line the connector cannot read, written past that position while the plane was down, does not hold the terminal: the re-establish reports the gap and places the terminal after the records before it. A record no read answers, such as an OpenCode part still filling when its turn died, holds it no more: the terminal is placed after the records before it, and the turn end reads the session once rather than without end. The OpenCode source reads every record at or before the end it reported at a turn end as settled, so a part left filling by a failed turn does not stop the turns after it from publishing. A terminal reported while the first start is still waiting on the broker reaches the emitter before its first read, so a prompt written in that window does not close the failed turn as a finish. The same placement runs with the plane up: a terminal reported while the flush before it is still reading, with the next prompt written before that read, closes its own turn in the place of the finish that prompt synthesizes. The seat used to exit on a space that requires events; for Claude Code the connector is the MCP server, so that exit showed as the server disconnecting, and Claude Code restarted it on the next tool call.

A transcript line that is not a record does not stop the plane. Claude writes the transcript, and a write cut short by a full disk leaves part of one record glued to the next on a single line, which never becomes readable. The connector steps over that line, keeps the records after it, and writes skipped an unreadable transcript record at offset <offset> (<bytes> bytes) with the parser's reason to its stderr.

A new session includes its first run even when Claude writes a positional startup prompt before the connector receives SessionStart. That from-zero read is keyed only to Claude's explicit source: "startup"; resumed, forked, cleared, and compacted sessions adopt at the transcript boundary captured at that adopt, before the mesh link connects, so nothing Claude appends while the connector is still starting up lands behind the cursor and is silently dropped. Crash recovery follows the cursor already stored in the event write-ahead log, regardless of the new process's startup label.

Claude starts each hook in its own process, so a prompt or stop relay can reach Cotal before the SessionStart relay. The connector holds those event flushes and the terminal until SessionStart supplies the source, then enqueues adopt, flush, and close in that order.

SessionStart can also run before the connector process has bound its local control socket. The hook the SessionStart relay retries only transient pre-connect listener errors, with capped backoff inside its existing two-second budget. Later hooks and permanent local faults still fail open immediately. Once a socket has connected, a broken exchange is not retried: the connector may already have handled the frame, so replaying it could apply one lifecycle event twice. That retained SessionStart can itself arrive before Claude creates the transcript path. A genuinely new startup waits up to five seconds for that file with capped backoff, and the same deadline bounds one stalled file read; expiry fails loud instead of silently losing the first run. A forked session gets the same wait, because Claude copies the parent transcript into the fork's own file after the hook, and then adopts at the end of that copy. Resumed, cleared and compacted starts and recovered cursors still require their existing source at once.

Tool arguments (TOOL_CALL_ARGS) and tool results (TOOL_CALL_RESULT) are not republished onto this channel. The durable emitter drops those events before they are written to the write-ahead log, because this channel's read ACL is not the ACL the tool ran under. Content is mandatory on both kinds, so the event is suppressed rather than emptied or replaced with a placeholder. Tool start and end still go out. A restart that finds a pending pre-fix frame still carrying those kinds HALTS rather than republishing it.

The channel is events.<owner>.<actor>, named after the session's principal. What the actor half is depends on the mesh, and the difference matters when you go looking for it: on a static mesh it is a key the manager allocated, never the display name, so two live agents sharing a display name do not share a stream; on a user-auth mesh it is the agent's own name, because that is what the ledger row is keyed on. Spelled out again with both halves below. The launch grants publish rights on that channel alone. A spawn that asks for a different agent's event channel is refused at the door rather than granted, since that channel is that session's event stream. The same rule runs on restart: a manager resume document that names another agent's event channel is refused rather than adopted, because the managed row is re-armed from that document and the credential is re-minted from the row.

The rule reads a concrete channel, two principal tokens and nothing else. A pattern such as events.<owner>.> is not an event channel to it and passes untouched, governed by ordinary ACL authority: on a user mesh the delegation envelope, on a static mesh the spawning credential itself. That is deliberate, because the pattern is the form an operator writes on purpose for an observer, and it is worth knowing rather than assuming the fence is total.

To let something else read a plane, grant it out of band. The refusal prints the command for the mesh it is running on, spelled out in full, and only that one.

On a user-auth mesh:

cotal actor grant <reader> --owner <owner> --scope '' --allow-subscribe 'events.<owner>.<actor>' --allow-publish ''

Every field, deliberately. actor grant is an upsert of the whole row, so it refuses a grant that leaves off any of the three ACL flags. Only --full turns an omitted flag into the wide default (> read, > post, spawn,role:default scope), which is the opposite of what a scoped watcher is for.

On a static mesh there is no actor ledger for actor grant to write to, and the refusal says so; mint the reader instead:

cotal auth mint watcher --profile agent --allow-subscribe 'events.<owner>.<actor>' --provision

The agent profile, not the observer one. mint reads --allow-subscribe only for that profile, and refuses it anywhere else: --profile observer --allow-subscribe <channel> exits non-zero and writes no creds file, because the observer profile carries a fixed read set over the whole chat plane, which is the opposite of what a scoped watcher is for. The agent profile also prints the lifecycle uid the reader needs, since an authed consuming endpoint refuses to start without one.

On an open mesh there is nothing to grant: the mesh has no credentials and no ACLs, so any peer that lists the channel reads it, and the refusal says so instead of naming a command. The own-channel rule still applies there, because a spawn is not the place to hand out a read on another agent's tool inputs and outputs.

Two things a reader has to do that are not obvious, both on CotalEndpoint. It must pass the event channel in channels: an endpoint reads the channels it lists, so one constructed without the event channel joins nothing and the frames never arrive. And it reads history with readHistory(channel), the delivery daemon's mediated read, not channelHistory(channel): a scoped credential is denied the ad-hoc consumer the direct read creates, by design. cotal console and the web console already do both.

The <owner>.<actor> pair is the session's principal. On a user-auth mesh the actor half is the agent's own name, so the channel is events.<your-owner>.<agent-name>. On a static mesh the owner half is the literal local and the actor is a key the manager allocated, so the channel is events.local.<key>; the spawn reply carries that key as id. Note that cotal console and the web console keep event channels out of their channel lists on purpose, since a plane is a machine feed rather than a conversation; they draw the frames when you open the channel by name.

The rule governs the manager's doors, which are the ones a caller other than you can reach. A foreground cotal spawn on your own machine mints from your own signing material, so it can still grant any channel you name: that is the out-of-band grant, not a way around the rule.

Failed turns publish run errors. Claude Code decides for itself whether a turn finished or died and fires one of two hooks accordingly, so the connector relays that decision rather than making one of its own: a turn that ended on an API error ends its run with RUN_ERROR carrying the fixed message run failed and no code. Neither the detail Claude Code reported nor its error kind is published there: both are upstream values that can echo your prompt or tool output, and the events channel has a different read ACL. The error kind still reaches presence as the agent's condition (rate_limit, auth, billing and the rest). A turn that ended normally still ends with a run-finished event carrying no outcome, which says the turn ended and does not claim it succeeded.

Events are written to a per-session write-ahead log before they are published, so a hook that fires after a restart resumes at the cursor it left rather than replaying or skipping, and a run that was open when the session stopped is closed rather than left dangling.

A delayed initial connection or a broker reconnect pauses event publication without closing MCP. The recorder waits for both the mesh binding and its transport; unpublished records stay in the transcript until the connection recovers. Stopping the connector cancels that wait. A recording error, including a conflicting transcript or damaged event state, stops the publishing plane and not the session: it is reported with the delay before the next re-establish, on every space, and the seat keeps its mesh connection. A second transcript path offered to a bound recorder is refused the same way, and the first path stays bound.

One channel carries every session of one agent, because it is named after the principal and not after the session. Alongside the per-session logs the connector keeps one small record per principal, holding the last sequence the broker assigned on that channel, so a new session continues the stream its predecessor left instead of starting again from nothing. Both live under the events state root (COTAL_WORKSPACE_ROOT), and neither is something you edit by hand.

A missing record is not a fault: the connector rebuilds it from the session logs beside it, which is how an agent that was already running before this record existed keeps its stream. That rebuild stops if any one of those session logs is damaged. Unreadable, not valid JSON, and written for a different principal all count, and so does a session directory or a log that is a link rather than the real file the connector wrote, or a log that has more than one name. A tip taken from the rest would be too low, and it would stop publication later with nothing left to point at the cause. The connector names the file instead, and the only way past it is the directory removal described below, under the same condition. A record that disagrees with the broker is a fault, and the connector stops publishing and says why rather than guessing. A record that moved while a session was writing to it is refused the same way: it means something else wrote the principal's record, and the connector reports which value it held and which the file holds rather than writing over the later one. There is no command to clear it. The state is the principal's directory under the events root, and clearing it by hand means removing that directory whole: the sequence, the cursor and the per-session logs only mean anything together, so removing part of it leaves a state the next start refuses. Removing it is only half a remedy, and the half that comes first is the channel. The directory is where the agent's memory of the tip lives, not the tip itself, so on a channel that still holds frames the next session opens expecting an empty one and stops on the same disagreement, with the logs a tip could have been rebuilt from now gone. Purge the channel first, then remove the directory.

Reading it: cotal console and the web console draw event frames directly. A frame carries no text part by design, so a surface that renders a message as flat text shows a marker instead of prose.

On a per-user-auth mesh, the default event plane needs the spawner's grant to cover the channel. The event channel is added to the child's publish set, and delegation only narrows: an agent may hand down a subset of what it holds and no more. So a peer-initiated spawn is refused unless the spawning identity's own grant already covers the child's event channel. The refusal prints the exact cotal actor grant command that widens it. An operator launch, whose chain reaches an admin-scoped or roster row, is unaffected. Passing events: false is the explicit opt-out.

Arming the event plane through a typed spawn request (manager.spawn with events, including the CLI's cotal spawn --detach --events) is allowed on a user mesh when the child runs under the caller's owner. This also satisfies a registration policy that requires the plane. A spawn under another owner still needs the caller's admin tier. Without it, an explicit request or a required plane is refused before provisioning. A silent non-owner caller in a space without that policy has the plane disarmed with a notice in a successful reply. Later provisioning can still refuse the spawn. The child's own-channel rule and the ledger's delegation envelope still apply.

Carried session custodyCopy Anchor Link

--resume <session-id> pulls an existing Claude session, its context and transcript, into the mesh. It forks: Claude mints a new session id from that transcript (--resume <id> --fork-session), so the meshed agent gets its own session and the original is untouched.

• cotal spawn --resume <id> (foreground) is the primary surface: the transcript is on your machine, and errors are Claude's own stderr, inline.
• --detach --resume <id> --on <instance> carries a session held on your machine to that manager instance, which may run on another host. The CLI finds the transcript under your Claude config (~/.claude, or $CLAUDE_CONFIG_DIR), sends it through a JetStream Object Store bucket only that instance reads, under a writer credential pinned to that one transcript, and prints carried session <id> to <instance>: sha256:<hex>, <sent> of <size> bytes sent in <chunks> chunks. Without --agent, the CLI first asks that instance which harness the persona resolves to, so a persona with agent: claude is carried even when your COTAL_DEFAULT_AGENT names another connector. A re-run of the same bytes sends nothing, and an interrupted carry continues where it stopped. The seat forks it in a private Claude home under the manager's .cotal/seat-homes/, which no other seat's Claude lists or finds, and which is removed when the seat stops. When Claude starts the fork, the seat records the SHA-256 of the transcript it read from its own project; the manager stops a seat whose record names other bytes than the carried ones, or that records none within the join timeout after it joins, an uncertain launch included, and otherwise shows that record as the seat's provenance. cotal attach to such a seat names its source after the seat name, as (resumed from <host>:<id>). A remote manager receives a carry when its host issues it a transfer reader. On a user-auth mesh the CLI exchanges the operator's login for a one-object transfer-writer view, which needs scope admin.
• A session name in place of an id is refused, listing each session on this host that carries that name with its id, SHA-256 and modification time. An id this host does not hold resolves against the manager host's ~/.claude, as before.
• A seat-private home holds no login. The manager host needs CLAUDE_CODE_OAUTH_TOKEN (from claude setup-token), ANTHROPIC_AUTH_TOKEN, or a cloud provider selection in its environment; ANTHROPIC_API_KEY alone is refused. The private home trusts the authorized launch directory without changing the manager's home. Claude must be 2.1.234 or later.
• The manager waits for a real outcome: ✓ started means the agent joined the mesh, ✗ exited on launch carries Claude's last output and the seat's exit diagnostic, such as a startup confirmation that never appeared, and an uncertain launch (~30 s) is reported without tearing the agent down.
• --opt resume= with no id passes a bare --resume, which opens Claude's session picker, and the agent joins the mesh once you pick a session. A managed launch with it is ready once Claude runs: the CLI says the agent is waiting for you at Claude's session picker, attaches you to it in a terminal, -d included, or otherwise prints the attach command, and exits 0. --opt resume=<id> passes --resume <id> and joins as any launch does.
• Resume is an operator surface only, deliberately not exposed on MCP cotal_spawn (a mesh peer naming host-local transcripts would widen spawn into transcript disclosure). Claude, Hermes, Jcode and pi support it, each by forking; OpenCode and Codex fail loud (Connectors).
• Needs a claude new enough for --resume … --fork-session (verified on 2.1.197).

MCP configurationCopy Anchor Link

A spawned session loads the MCP servers your normal Claude Code configuration enables on the launch host: user, local, project, plugin and connected-account sources. Claude handles discovery, precedence, disabled servers, project approval and managed policy. Cotal adds its mesh server and any overrides declared in connectors.claude.mcpServers (format). It does not copy native server definitions or credentials into the launch file or onto another machine. The selected CLAUDE_CONFIG_DIR remains in effect for an ordinary local spawn.

First-run setup still seeds eligible user-scope declarations into the Cotal config and preserves an existing list. That list is not the source of truth for native discovery. A same-named declared override takes precedence; changing the native definition does not rewrite an override you kept. An empty Cotal sharing map leaves native discovery enabled.

Use --share-tools tavily,figma to load only those declared servers plus Cotal, or --share-tools none for Cotal alone. These explicit selections use --strict-mcp-config. Carried sessions also stay strict and keep their seat-private home; operator profiles and connected-account credentials are not copied into them. Native managed policy still applies.

The child environment stays allowlisted. References in declared shared servers and the selected user-owned MCP configuration forward their named variables. Repository and plugin files cannot add ambient secret names merely by referencing them; supply such names through an explicit shared declaration or the existing spawn.env policy. Native files retain their own configured values. Documented native MCP switches, including the connected-account opt-out and tool-search choice, keep their explicit values. Cotal does not forward the entire parent environment or force tool definitions to load upfront.

Sharing a credential grants it to the session, so enable only servers the session may use. Each enabled server may start a process per seat; an explicit sharing selection can reduce that cost. Native discovery does not change Cotal's mesh identity, hooks or channel wake path.

One Cotal path per sessionCopy Anchor Link

A spawned session is on its mesh through the local Cotal server. A connected-account source can also give it a hosted Cotal connector, which would join the same session a second time under another name. The plugin's PreToolUse hook refuses every cotal_* tool of any server other than the local one in a session Cotal launched, with the reason in the refusal. It decides in the hook process, so the refusal holds when the control socket is down. A Claude Code session that Cotal did not launch keeps the hosted connector. Where the plugin is installed, its local server's instructions tell the model to use the local path unless you ask for the hosted one.

In such a session the plugin also keeps each hosted connection with the session that opened it. A PostToolUse hook on the hosted cotal_connect records the returned connection_id under the plugin's data directory (CLAUDE_PLUGIN_DATA), and cotal_disconnect releases it. A fork made with --fork-session inherits that id in its transcript but has a new session id, so its calls with the id are refused and it is told to call cotal_connect. A resumed session and its subagents keep the session id and pass. An id the plugin never saw opened goes to the hosted connector, which checks the account. The guard runs only where the cotal plugin is installed. A Claude Code session with only the hosted connector has no hook, so nothing records its connections and its forks are not refused.

A hosted connector cannot start a turn, so a hosted conversation hears a message only when it calls a tool. cotal_wait holds until a message that would wake the agent arrives and returns it, or returns with none after the service's bound. The conversation calls it again to keep listening. Every other hosted tool adds a line to its result when messages are waiting. A conversation with no turn running is not woken.

Host sessions in one processCopy Anchor Link

A host serving many managed seats can run their MCP servers in one process with the subpath @cotal-ai/connector-claude-code/mcp, which loads with both import and require:

import { serveClaudeSession } from "@cotal-ai/connector-claude-code/mcp";

const session = await serveClaudeSession({ env, input, output });
await session.close();

Loading the module only exports it; it serves its own stdio only when run, as node dist/mcp.cjs. A host that loads it this way compiles the bundle in its own process and is outside the seat entry's compile cache (above); module.enableCompileCache() before the first load brings the host the same saving. The subpath ships CommonJS declarations so TypeScript hosts can use either module format, including CommonJS consumers with Node16 or Node18 module settings. Claude Code pushes claude/channel only to a stdio server it launched, so each claude still launches a stdio command, such as a small relay that pipes its stdio to the host.

• Managed only. env is a complete launch environment, copied when the call starts. It must carry a mesh identity and the full control pair, or the call rejects before the session joins the mesh. The presence environment label, bearer commands, carried-fork records and feedback contact lookup use that copy. Feedback's Git fallback reads the session's global config, including its includes, without reading the host repository config. Set COTAL_FEEDBACK_EMAIL or pass the feedback tool's email argument to choose another contact. Include the PATH, HOME and other OS variables subprocesses need; the host's environment is not merged into them. Subprocesses still use the host process's working directory. A session's card does not: its meta.cwd is the cwd its own SessionStart hook reports on startup, resume or fork, absent until then, and unchanged by clear or compact. It is advisory display data that every reader of the space's roster can see. A plain claude with no identity is served by mcp.cjs run directly. Sharing a process does not isolate untrusted tenants or their files.
• Streams. input carries JSON-RPC from the client and output carries this session's replies and claude/channel pushes. The caller owns both streams. Input that has emitted end or is destroyed rejects startup. Buffered unread input remains eligible. When an active session's input emits end or close, the session closes, including after a relay connection resets. Teardown may pause input and removes the transport's error handler. A host that reuses the stream must resume it as needed and keep its own stream error handlers.
• fatalBind. Off by default: a control socket that cannot be bound rejects the call and the host keeps its other sessions. Only a process that is the session turns it on, as mcp.cjs does.
• Teardown. close() closes the control socket, the wake policy, the AG-UI emitter, the mesh endpoint and the MCP server, and is idempotent. It removes its input listeners without closing the caller's streams. The returned promise rejects if teardown fails. A startup failure closes what was started before the call rejects. A manager shutdown frame or input EOF or closure closes the session and then calls onShutdown(code) once. A teardown failure is logged and reported with code 1, without becoming an unhandled rejection in the host. Close waits for a pending broker dial to settle. A dial that fails after shutdown starts is not a teardown failure. The session releases local inbox custody only after its connections are proved closed, so the same lifecycle can reopen after a successful close. An active duplicate or an unproved close retains custody.

Feedback configurationCopy Anchor Link

cotal_feedback works out of the box: without a key it posts to the public intake at https://cotal.ai/v1/feedback (needs a contact email: COTAL_FEEDBACK_EMAIL, then git config user.email, else the agent asks). Set COTAL_FEEDBACK_KEY=fbk_<key> in a beta tester's environment to route to the keyed intake (Authorization: Bearer, identity derived from the key); COTAL_FEEDBACK_URL overrides either endpoint. The CLI can send too: cotal feedback "<summary>" [--type bug]. Each submission carries origin: human | agent, whether the tester asked, or the agent auto-reported a major issue.

Plugin refreshCopy Anchor Link

Team and Enterprise accounts: Enable Claude Code channels before running unattended agents. Channels are blocked by default, so incoming messages cannot wake an idle session until an organization Owner enables them.

cotal setup --configure-only  # install the plugin and seed one agent without startup
cotal up         # brings up the mesh + delivery daemon + a detached manager

cotal setup installs the cotal plugin for your user account, so every Claude Code session on this machine gets the cotal_* tools, in any project. That covers the terminal, the IDE extensions and the Desktop app's local Code sessions. Setup can use Desktop's bundled Code executable when no terminal claude command is installed. Desktop-only users should open a local Code session once so Desktop downloads that executable. Setup checks it through the connector's own readiness probe; managed spawn still requires the terminal claude command. On a mesh you run with cotal up, sessions join through cotal spawn. A session you open yourself can join only a remote signed-in mesh whose authority offers connection approval: run setup once, reopen Claude and ask it to connect (see personal sessions). No MCP configuration edits or special launch flags are needed for this native plugin path. It also shares your own MCP servers with spawned sessions on its first run (see Sharing your MCP servers), and seeds one default persona; cotal up brings up the local stack so cotal spawn --detach / cotal_spawn work right away. Re-running either is idempotent. A repeat cotal setup and cotal update refresh the copy under ~/.cotal/claude-plugin and update existing Claude plugin registrations, including older cached installations. After an npm upgrade, the first regular Cotal command also refreshes these copies before accepting the new generation. Setup, skills installation and refresh share a machine-local lock through the final plugin check, so simultaneous commands cannot overwrite a generation while another command verifies it. Disabled installations stay disabled during an update. Claude Code can apply an update run in a project folder to an enclosing project that has its own installation, so the folder's local or project installation stays old. That installation does not stop the refresh or later commands: Cotal prints a warning naming the folder and the claude plugin uninstall command to run there to remove it. A user-scope installation that does not update is still an error. cotal status checks the resolved payload's manifest version and file contents. A folder-backed plugin can retain older version metadata in Claude's installation records; that metadata does not override the files Claude loads. Running sessions keep the code they loaded; reload plugins or reopen Claude to load the update. The install mechanics and the invariants behind them are in setup internals.

cotal setup also installs Cotal's authored Agent Skills (SKILL.md, the agentskills.io format) for coordinating agent teams (today team-topology), from one canonical source, on two channels:

• Claude Code gets a second, skills-only plugin, cotal-skills, from the same cotal-mesh marketplace, at user scope (machine-wide). The Claude connector declares and implements this setup provider, including the marketplace assets and native plugin commands; the base CLI only passes the vendor-neutral Agent Skills directory. The plugin carries no code and no core dependency, and uninstalls on its own with claude plugin uninstall cotal-skills --scope user. Its plugin version is stamped from the running CLI release. cotal update refreshes an existing skills plugin without enabling it or installing a removed one; cotal setup --skills also installs missing skills. cotal setup installs it on first run and on repeat runs, so upgraders are not left behind. The same provider reports the plugin and skills plugin rows in cotal status, which point a stale or missing skills plugin at cotal setup --skills.
• Every other harness (Codex, Cursor, OpenCode, Gemini CLI, Windsurf/Devin) reads the cross-vendor ~/.agents/skills/ directory convention, which has no remote index, so cotal setup reconciles it (and cotal setup --skills does only that): it installs/updates each Cotal skill, backs up a copy you have edited to SKILL.md.bak before replacing it, and removes a Cotal skill that is no longer shipped. Only skills Cotal owns are touched; your own or third-party skills there are left alone. cotal status reports whether the drop is current, stale, missing, or has a retired skill to reconcile, and names cotal setup --skills as the remedy. This is the working cross-vendor path.

Cotal also generates an Agent Skills discovery index on cotal.ai, but that RFC is still a draft with no harness consuming it yet, so it is a forward bet, not a channel to rely on today.

Launch permissionsCopy Anchor Link

See Binding for the current connector contract.

AuthenticationCopy Anchor Link

See Binding for the current connector contract.

Private launch filesCopy Anchor Link

See Binding for the current connector contract.

Process costCopy Anchor Link

See Binding for the current connector contract.

Plugin installationCopy Anchor Link

See Binding for the current connector contract.

Startup confirmationCopy Anchor Link

See Binding for the current connector contract.

Inbox custodyCopy Anchor Link

See Binding for the current connector contract.

Native wakeCopy Anchor Link

See Binding for the current connector contract.

Desktop chatCopy Anchor Link

See Binding for the current connector contract.

Connection guardsCopy Anchor Link

See Binding for the current connector contract.

Hook acknowledgementCopy Anchor Link

See Binding for the current connector contract.

Channel wakeCopy Anchor Link

See Binding for the current connector contract.

Inbox boundsCopy Anchor Link

See Binding for the current connector contract.

Focus recallCopy Anchor Link

See Binding for the current connector contract.

Event privacyCopy Anchor Link

See Binding for the current connector contract.

Channel identityCopy Anchor Link

See Binding for the current connector contract.

Reader grantsCopy Anchor Link

See Binding for the current connector contract.

Transcript adoptionCopy Anchor Link

See Binding for the current connector contract.

Event recoveryCopy Anchor Link

See Binding for the current connector contract.

Event stateCopy Anchor Link

See Binding for the current connector contract.

Session optionsCopy Anchor Link

See Binding for the current connector contract.

TeardownCopy Anchor Link

See Binding for the current connector contract.