Skip to content

CCCC Collaboration Standard (CCCS) v1 ​

Status: Draft (proposed for CCCC v0.4.x ecosystem)

This document defines CCCS v1, a small, transport-agnostic standard for multi-agent collaboration built around an append-only event ledger. It is designed to be stable, extensible, and implementable by:

  • CCCC itself (daemon + web UI + MCP/IM bridges)
  • Client SDKs (TypeScript/Python/Go/etc.)
  • External tools and integrations (CI, IM bots, IDE plugins, automation)

CCCS v1 deliberately does not standardize workflows, model providers, or prompting. It standardizes the collaboration substrate: event envelopes, routing semantics, delivery/read/reply facts, system notifications, and cross-group provenance.

0. Conformance Language ​

The key words MUST, MUST NOT, SHOULD, SHOULD NOT, and MAY in this document are to be interpreted as described in RFC 2119.

1. Goals and Non‑Goals ​

1.1 Goals ​

CCCS v1 MUST enable:

  • Tool/code ⇄ agent collaboration: tools can send, observe, and act on the same collaboration stream as agents.
  • Append‑only truth: collaboration history is represented as immutable events appended to a ledger.
  • Provenance: relayed/forwarded messages can be traced back to an original event (cross-group).
  • Intentional delivery: senders choose immediate prompt delivery, explicit reply obligation, or durable Mail without prompt interruption.
  • Forward compatibility: unknown event kinds and unknown fields do not break clients.

1.2 Non‑Goals ​

CCCS v1 does NOT standardize:

  • Any specific workflow engine, DAG, or no-code builder.
  • Any model/provider API (OpenAI/Claude/etc.) or prompt format.
  • Any single transport (Unix socket, HTTP, SSE, WS, gRPC). CCCS v1 is transport-agnostic.
  • Multi-tenant auth schemes (but it reserves fields and rules for provenance/permissions).

2. Terminology ​

  • Group: A collaboration namespace (working group).
  • Scope: A project root URL attached to a group; each event is attributed to a scope_key.
  • Actor: A named agent identity within a group (e.g., foreman, peer-1).
  • Principal: Any entity that can write events (user, an actor_id, system, or svc:<name>).
    • Service principals SHOULD use a stable namespace (RECOMMENDED: svc:com.example.mybot when disambiguation is needed).
    • The svc:cccc. prefix is RESERVED for CCCC ecosystem services.
  • Ledger: An append-only sequence of events for a group.
  • Client: Any process/UI/bot that reads or writes events via a daemon.
  • Daemon: A single-writer authority that appends events and enforces permissions.

3. Core Object Model ​

3.1 Group ​

Each event belongs to exactly one group, identified by group_id (string).

3.2 Scope ​

Each group MAY have one or more scopes. Each event MUST include a scope_key:

  • scope_key MAY be "" (unknown / global / not tied to a scope).
  • scope_key is a stable identifier for a scope assigned by the daemon.
  • Clients MAY use scope_key for equality and filtering, but MUST treat it as an opaque string and MUST NOT parse or interpret its value.

3.3 Actor ​

Actors are identities within a group. CCCS v1 standardizes only:

  • actor_id: stable string identifier
  • role: "foreman" or "peer" (optional; the collaboration semantics do not require a role)

A user-owned native session MAY participate through ordinary Group Actors. Source discovery MUST NOT manufacture collaboration history. An administrator MAY explicitly admit a new native source to an existing Group as a new Actor; this MUST NOT silently replace an earlier identity, transfer its role, or inherit its pending work. In-flight native requests MUST remain bound to their captured source, Actor generation and native lifecycle revision; reusing a textual Actor ID MUST NOT transfer that authority. Transport acceptance, model execution and explicit read/reply receipts remain distinct; a receiver failure MUST NOT indefinitely block later messages or unrelated recipients. Native session ownership and local adapter operations are defined in the daemon IPC contract.

Resuming the same admitted native conversation after its former host exits is distinct from admitting another conversation. At the receive-attachment boundary, the daemon MAY restore that conversation's existing Actor binding only with the exact conversation/configuration and exited-host evidence defined in the IPC contract. This MUST retain Actor generation, role and access, preserve Group pause/stop, and audit the changed source. It MUST NOT revive disabled integration, choose among conflicting memberships, or replay submitted or uncertain work.

Copying or importing a Group MUST NOT implicitly activate its native memberships, even within the same local instance. Imported native Actors retain their source references and history with collaboration access disabled until an explicit user action; the source Group is unchanged. A native source reference is not a portable credential or a grant of live receiver authority.

4. Event Envelope (Normative) ​

All events MUST use the envelope below. Field semantics are fixed.

ts
interface CCCSEventV1 {
  v: 1
  id: string            // MUST be unique within the group ledger; SHOULD be globally unique (ULID/UUIDv7/UUID4)
  ts: string            // RFC3339 UTC timestamp assigned by the daemon at append time
  seq?: number          // OPTIONAL: monotonic sequence number assigned by the daemon (useful for streaming/cursors)
  kind: string          // e.g. "chat.message"
  group_id: string
  scope_key: string     // "" allowed
  by: string            // principal id ("user", "system", actor_id, or "svc:<name>") set by the daemon
  data: Record<string, unknown>
}

4.1 Forward Compatibility Rules ​

  • Clients MUST ignore unknown kind values (but MAY display them as raw/unknown events).
  • Clients MUST ignore unknown fields inside data.
  • Clients MUST preserve the event envelope when relaying/forwarding (see §9).

4.2 Versioning ​

  • v is the envelope version. CCCS v1 requires v: 1.
  • Implementations MAY add a data.v field for kind-specific versioning, but MUST NOT change envelope semantics without bumping v.

4.3 Ordering and Timestamps ​

  • The authoritative ordering of events is the ledger append order.
  • ts MUST be assigned by the daemon at append time. Clients MUST NOT rely on client-local timestamps for ordering.
  • Implementations MAY record a client-provided timestamp (RECOMMENDED: data.client_ts) for diagnostics or UI display, but it MUST NOT affect ordering.
  • A newline-delimited ledger writer that finds a nonempty active ledger without a terminating newline MUST preserve the existing bytes and append a newline separator under the same writer lock before appending the next event. It MUST NOT concatenate a new event onto an incomplete or complete unterminated record, report success for an event that cannot be read back, or treat a derived index as authority over the ledger bytes.

4.4 Event Kind Namespaces ​

Standard kinds use the chat.*, system.*, group.*, actor.*, context.*, and assistant.* namespaces.

Extensions SHOULD use one of:

  • x.<vendor>.* (recommended for private/vendor-specific kinds)
  • vendor.<name>.* (alternative vendor namespace)

Clients MUST treat unknown kinds as opaque and ignore them unless explicitly supported.

5. Recipient Routing Semantics ​

5.1 Recipient Tokens ​

Chat message routing uses to: string[] with these token types:

When a send request omits recipients or supplies an empty list, the daemon MUST materialize the group's default_send_to policy as @foreman or @all before appending the event.

Actor IDs

  • Example: "peer-1", "claude-1"

Selectors (MUST start with @)

  • @all: all visible collaboration actors in the group
  • @peers: all visible peer actors
  • @foreman: foreman actor(s)
  • @user: the human user (UI recipient)
  • @chet: the instance-wide Chet service, subject to the ambiguity rule below

Internal assistant Actors are not members of @all, @peers, or @foreman. The global Voice Secretary remains a service, not a chat recipient or Group Actor; confirmed Secretary handoffs use by="user" and retain the original Group/scope through normal peer delivery. Chet, the global Voice Analyst, is a service principal, not a Group Actor or a member of those broadcast selectors. An explicitly addressed @chet is stored as svc:chet. If a visible Group Actor's ID or title equals chet, ignoring ASCII case, the selector MUST fail as ambiguous rather than silently redirect that Actor's existing address. A bare Actor ID retains its existing meaning. A stored service identity is not, by itself, proof of a service-authored message under local-trust IPC (§5.4).

For a local Chet-authored chat message, the host writes data._cccc_chet_group_generation with the current Group generation. This field is read-only to clients: message and raw-event write operations MUST reject a caller-supplied value. A local service identity is recognized only when by is svc:chet, the host field matches the current Group generation, and the event is present in that Group's ledger. Copies and imports retain their old field value, which does not attest the new Group's service identity.

When a recipient replies to a host-verified Chet message without an explicit recipient, the daemon routes to the service identity as an internal target; it MUST NOT resolve the service principal as an Actor title. An explicit different recipient retains its ordinary routing. If an event claims that service author but cannot be verified in the current Group, the default reply MUST fail with an actionable error; it MUST NOT fall back to resolving the author as a name. When a member replies to a verified Chet answer on behalf of the user (§6.4), its default recipient is user. Cross-instance service addressing is not implied by the local selector.

Before Chet sends a reply that addresses the source Actor, the daemon MUST verify that the source event belongs to this Group generation and that the current Actor is the registration that sent it. If either cannot be established, the reply MUST be refused before waking a recipient or appending the reply, with guidance to ask the user to relay it. A previously accepted idempotent retry still returns its existing event. A reply explicitly addressed only to other recipients retains ordinary routing. Older Group ledgers without the Actor registration fact may not establish the source identity.

Selector membership describes the logical audience, not permission to start a runtime. A user broadcast to @all or @peers MUST NOT re-enable disabled actors. Explicitly targeted user wake actions follow the daemon IPC lifecycle contract; disabled recipients remain part of the message audience and history.

Compatibility

  • Implementations MAY accept the literal token "user" as equivalent to @user.

5.2 Audience Domains ​

Every new chat.message MUST address exactly one audience domain:

  • Human: the sole normalized recipient is user / @user.
  • Agents: every recipient is an actor ID or an actor selector (@all, @peers, or @foreman). Multiple agent recipients are allowed.
  • Chet: the sole normalized recipient is svc:chet.

A recipient list that mixes these domains MUST be rejected before the event is appended. Callers that need distinct actions MUST send separate messages so delivery and reply obligations remain independently attributable.

Multi-user note

  • CCCS v1 assumes a single human principal per group, identified as user.
  • Multi-user semantics (multiple distinct human principals) are out of scope for v1. Implementations MAY extend this outside of CCCS v1 (e.g., usr:<id> principals and selectors), but clients MUST remain forward-compatible.

5.3 Empty to ​

If to is absent or an empty list, the daemon MUST materialize the group's default_send_to policy before appending the message. The stored event therefore contains an explicit @foreman or @all selector; absence is not a separate broadcast state.

5.4 Permission and Visibility ​

CCCS does not mandate a single permission model, but a conforming daemon MUST ensure:

  • The daemon MUST set event.by to the principal identity it ascribes to the event.
    • If the transport provides authentication, event.by MUST be derived from the authenticated principal and clients MUST NOT be able to choose event.by arbitrarily.
    • If the transport does not provide authentication (local-trust IPC), a daemon MAY accept a client-provided principal hint (e.g., an RPC arg like by) as the effective principal. Such deployments MUST document that by is not a security boundary.
  • Only the daemon may append runtime.delivery; clients cannot claim transport acceptance on behalf of a recipient.

6. Chat Events ​

6.1 chat.message ​

chat.message represents an IM-style message.

ts
data: {
  text: string
  format?: "plain" | "markdown"               // default "plain"
  insight?: string | null                       // provisional sender perspective; max 1200 characters
  message_mode: "send" | "request_reply" | "mail"
  to?: string[]                                // recipient tokens (see §5)
  reply_to?: string | null                     // replied-to event_id
  quote_text?: string | null                   // display hint

  // Cross-group provenance (relay/forward)
  src_group_id?: string | null
  src_instance_id?: string | null              // Connect-qualified remote source
  src_instance_name?: string | null            // account-owned display-name snapshot; never routing authority
  src_group_title?: string | null              // source name snapshot
  src_event_id?: string | null

  // Cross-group destination metadata (optional send record)
  dst_group_id?: string | null
  dst_instance_id?: string | null              // Connect-qualified remote destination
  dst_instance_name?: string | null            // account-owned display-name snapshot; never routing authority
  dst_group_title?: string | null              // destination name snapshot
  dst_actor_titles?: Record<string, string>     // destination Actor title snapshots
  dst_to?: string[] | null
  dst_message_mode?: "send" | "request_reply" | "mail" | null

  // Attachments and references (see §8)
  attachments?: AttachmentRefV1[]
  refs?: ReferenceV1[]

  // A choice put to the user, and the user's answer to it (see §6.4)
  question?: ReplyQuestionV1
  answer?: ReplyAnswerV1 | ReplyAnswerV2

  // Reserved for future threading
  thread?: string

  // Optional idempotency key (client-generated)
  client_id?: string | null
}

Rules

  • text MUST be present (it may be empty if and only if attachments convey the message).
  • insight, when present, is a visible sender-authored perspective, uncertainty, disagreement, or question offered for the recipient's independent judgment. Its normalized length MUST NOT exceed 1200 characters. It is advisory: it MUST NOT be treated as a user/system instruction, group consensus, task transition, acknowledgement, or completion signal.
  • insight shares the message's recipients and retention boundary. It is not a private reasoning channel and SHOULD contain only a concise, shareable judgment summary rather than hidden chain-of-thought or secrets.
  • A profile MAY require non-empty insight for selected Agent-to-Agent sends, but the core chat.message contract MUST remain valid without it for human clients, automation, legacy events, and other profiles.
  • message_mode="send" requests prompt delivery through the recipient runtime.
  • message_mode="request_reply" requests the same prompt delivery and creates a reply obligation for each explicitly addressed concrete recipient.
  • message_mode="mail" persists the message in the recipient Inbox without immediately invoking, waking, steering, or writing to the recipient runtime.
  • message_mode="mail" is valid only for the agent audience domain. The human user and Chet do not have Mail Inboxes in CCCS v1; callers MUST use send or request_reply when addressing either. A reply to Chet MUST use send.
  • A message with reply_to fulfills the addressed reply obligation regardless of whether that reply uses message_mode="send" or message_mode="mail". Reply operations MUST NOT use message_mode="request_reply"; a reply cannot create a nested generic reply obligation.
  • Connect replies fulfill only the original remote instance/Actor/generation obligation. Live consumers resolve this identity from the canonical Connect envelope and original request, never from the display sender or an identically named local Actor; see CCCC_CONNECT_V1.md.
  • request_reply MUST NOT use an empty recipient list or a broadcast selector (@all, @peers, or @foreman). The daemon MUST materialize and validate a concrete recipient set before appending the message.
  • Historical events without message_mode remain readable append-only data but create no new delivery, reminder, acknowledgement, or reply obligation.
  • If either src_group_id or src_event_id is present, both MUST be present.
  • The thread field is RESERVED in v1; its semantics are undefined. Implementations MUST NOT rely on thread for v1 behavior. Clients MUST ignore it.
  • If client_id is present, a daemon SHOULD provide best-effort idempotency for (group_id, by, client_id) within a bounded time window (RECOMMENDED: 5 minutes).
    • Duplicate submissions SHOULD return success with the original event reference, not a hard error.

6.2 mail.read (Mail Cursor / Watermark) ​

mail.read records a recipient's Mail watermark up to a given Mail event.

ts
data: {
  actor_id: string  // the reader/recipient actor_id
  event_id: string  // the last consumed Mail event_id (inclusive)
}

Rules

  • The Mail cursor is evidence that Mail was returned by an explicit consuming Inbox operation. It is not proof that a runtime or model understood it.
  • event_id MUST reference an addressed chat.message whose message_mode="mail" in the group ledger. Send and Send + Reply messages do not participate in this cursor.
  • A daemon MUST enforce authorization: only the recipient actor (event.by == data.actor_id) or an authorized privileged principal (e.g., user) MAY emit mail.read for data.actor_id. data.actor_id="user" is invalid because CCCS v1 does not define a human Mail Inbox.
  • "Inclusive" means the referenced Mail event itself is considered read.
  • If a client cannot efficiently determine ordering, it SHOULD treat event_id as an opaque watermark maintained by the daemon.
  • A late status snapshot MUST NOT make an already consumed Mail unread again. The daemon still owns the current recipient set, including Actor generation changes; clients MUST NOT restore recipients removed by an authoritative snapshot.

6.3 chat.reply_request.cancelled ​

Cancels any still-open request_reply obligation created by one source message.

ts
data: {
  source_event_id: string
}

Rules

  • The target MUST be a chat.message with message_mode="request_reply" in the same group.
  • Only the original sender or the human user may cancel the request.
  • A reply from a recipient closes only that recipient's obligation. A cancellation closes every still-open recipient obligation. A recorded Chet answer on behalf of the user closes the user's obligation (§6.4).
  • Append order is authoritative. If a recipient replied before cancellation, that recipient is replied; otherwise the cancellation state is cancelled. Later replies remain visible but do not change cancelled back into replied.
  • Clients merging live events with HTTP snapshots MUST NOT reopen a terminal obligation when an older pending snapshot arrives. A terminal daemon snapshot remains authoritative for resolving reply versus cancellation by append order.

For Connect, the daemon derives the exact qualified original request and persists cancellation through the same durable outbox as messages. Only the original Actor generation or a participating Group's human may originate it. A received control is not forwarded automatically. Local obligation cancellation and remote connect_cancellation propagation are distinct: queued, sent, failed or unconfirmed. It does not retract a message or stop an Actor task. A terminal chat.cross_group_receipt with action="cancel" addresses the control via source_event_id and the local original message via original_event_id. A cancellation for an original absent after its delivery deadline may record source_event_id:null, not_delivered:true; it changes no obligation. See CCCC_CONNECT_V1.md for authority and recovery.

6.4 Questions to the user ​

A request_reply message to the user alone MAY carry a structured question, so the user chooses an answer instead of composing one.

ts
type ReplyQuestionV1 = {
  v: 1
  context?: string          // the sender's text; at most 4000 characters
  prompt: string            // at most 500 characters
  options?: {               // none (a free answer), or two to four
    id: "A" | "B" | "C" | "D" // in this order
    label: string           // one line, at most 80 characters
    consequence?: string    // one line, at most 240 characters
  }[]
  recommended?: { option_id: string; reason: string } // reason: one line, at most 240
}

type ReplyAnswerV1 =
  | { v: 1; option_id: string }
  | { v: 1; text: string }  // at most 4000 characters; kept exactly as written

type ReplyAnswerV2 = {
  v: 2
  option_id: string
  note: string              // nonempty, at most 4000 characters; kept exactly as written
}

Rules

  • Limits count Unicode scalar values. A value over a limit is rejected, never truncated.
  • The structure is authoritative and text is generated from it: context, prompt, one line per option, the recommendation, and a closing line naming the option ids. A client that reads only text therefore sees the complete question. A reader MUST accept a stored question only when its structure is valid and regenerating the text reproduces the stored text; otherwise it shows the text and treats the question as unavailable. Written records, imports and appended events are all read under this rule.
  • question is valid only on a new message with message_mode="request_reply" addressed to user alone by a sender other than user, so that every stored question is one the user's open requests include. Replies, cross-group and Connect messages cannot carry one.
  • The recommendation is advice. A client MUST NOT preselect it or treat it as the user's choice.
  • answer appears only on a reply to a question from the daemon's answer operation. It validates the caller's structured answer before writing it. V1 keeps its two mutually exclusive forms. V2 is used only for a selected option with a nonempty note; it does not change the question's V1 shape. The message text is generated for the requester: Selected <id>: <label> for a choice; for V2, that line followed by a blank line and Note: <note>; the user's words prefixed with Other: when the question offered options; and the user's words alone when it did not. The note is preserved exactly.
  • The user's obligation follows §6.3. The first reply by the user, recorded Chet answer on behalf of the user, or cancellation after the request closes it. user is the Group's shared human audience; one person's answer closes the request for everyone with access to the Group.
  • An answer is accepted only while the request is open, for an offered option, and only when the ledger proves the requester is still the same Actor registration: its latest actor.add precedes the request and records the identity the Group holds now. A removed, re-added or unproven requester is reported as such, never resolved to an Actor that shares its ID. Requests relayed from another Group or instance are answered with an ordinary reply.
  • During unattended mode, an authenticated Chet session can submit an answer to an eligible new request from a member to the user. The daemon checks the current mode and the source under the Group's write permit. It records the answer as by="svc:chet" with the existing Group provenance and the host-owned field data._cccc_chet_on_behalf_of="user". The field is reserved for this writer. Readers treat the recorded answer as the user's closure, including when viewing copied history. Normal Chet replies keep their ordinary reply semantics. For a reply to an answer Chet wrote in the current Group, the user defaults to the original requester and a member defaults to the user.
  • Closing the request and recording the answer do not mean the requester has received it; delivery is reported separately (§6.5). Answering never resumes a paused or stopped Group or re-enables an Actor; the answer waits for delivery until the user does.
  • Deciding whether a request is open requires every stored record of the Group's ledger to read as a complete event. A record that does not (a damaged line or a cut tail) could be the reply or cancellation that closed it, so that Group's requests are reported as unknown and in-place answers are refused until the ledger is repaired. The same holds when a request's id is used by more than one record (§4) or a reply or cancellation is stored before the request it names. Ordinary replies stay available.

6.5 runtime.delivery ​

Daemon-authored evidence that one source message was handed to one recipient runtime transport.

ts
data: {
  actor_id: string
  source_event_id: string
  delivery_id: string
  state: "claimed" | "accepted" | "failed" | "ambiguous" | "withdrawn"
  transport: string
  delivery_evidence?: "terminal_written" | "channel_accepted"
  reason?: string | null
  retryable?: boolean
}

Rules

  • Only the daemon may append this event.
  • delivery_id MUST be deterministic for one source event, actor generation, and recipient actor. A retry reuses that identity.
  • The daemon MUST append claimed before performing external runtime I/O and then append one initial observable result state for that attempt. A later verified receipt MAY append a reconciliation observation, such as changing an ambiguous handoff to accepted, without performing another submission. This does not authorize automatic retry.
  • A concurrent claimant that observes claimed MUST treat the delivery as in progress; it MUST NOT reinterpret or retry the active attempt.
  • During daemon startup, a latest claimed state left by the previous daemon process MUST be settled to ambiguous before runtime recovery begins.
  • accepted means the runtime adapter accepted the payload (queue, PTY, headless API, or browser submission boundary). It does not claim that the model read, understood, or acted on it.
  • An accepted record MAY include delivery_evidence from the handoff itself. terminal_written confirms that CCCC wrote the terminal input. channel_accepted confirms the runtime's delivery path accepted the input. Neither value establishes model execution. Receipts without recognized evidence retain generic acceptance. Readers MUST NOT infer evidence from transport, current Actor settings or later runtime observations.
  • failed means the adapter established that handoff did not occur, or that the runtime ran the turn and it failed after its retries. It does not prove that the model never saw the input.
  • A failed attempt MAY carry retryable=true only when the daemon established that it stopped before runtime submission (for example, a paused worker or a full daemon queue). This work remains pending for normal recovery. For transport="local_session", a native rejection or a legacy failed receipt without that evidence MUST NOT automatically retry. This flag never permits replay after accepted, ambiguous or withdrawn.
  • A daemon-managed runtime that retries a failed turn on its own MAY record the final failure with retryable=false once that bounded retry budget is spent. Automatic delivery MUST NOT start that delivery again, including after an Actor or daemon restart; an explicit delivery request MAY still retry it. A failed record without the flag keeps its existing recovery.
  • Eligible native pending work MUST remain recoverable beyond an in-memory queue or startup query page. The delivery owner MUST continue bounded ledger refill as capacity becomes available, without requiring another message, manual Actor Start or a receive-status refresh for each Group. Refill MUST preserve membership, Actor generation, source binding, pause/stop and terminal receipt boundaries. Status/discovery reads MUST NOT initiate refill or scan native history.
  • ambiguous means external side effects may have occurred but cannot be proven. Automatic retry MUST NOT follow accepted or ambiguous.
  • withdrawn means the source became obsolete before handoff, and the owner established that no external submission occurred. It is terminal and MUST NOT be automatically retried. A claim without its active projection is not proof of non-submission; uncertain external I/O remains ambiguous.
  • A normal mail append creates no runtime.delivery. An explicit manual delivery of that existing message may create one without appending a second chat.message.
  • A Group message addressed to Chet MAY carry one runtime.delivery with actor_id="svc:chet" and transport="chet_group". It records only that the host never handed the request to Chet: state="failed", reason="chet_wait_expired", retryable=false, with no preceding claimed, because no external submission was attempted. The daemon appends it at most once per source event, derives delivery_id from the source event, the service principal and the Group generation, and appends it only after Chet's private history durably records that the input will never be submitted. Clients show it on the source message as "not sent to Chet and not run; send it again if still needed". It reveals nothing about Chet's other work.

6.6 chat.reaction (Optional) ​

ts
data: {
  event_id: string
  actor_id: string
  emoji: string
}

7. System Notification Events ​

System notifications are separated from chat to avoid polluting conversations.

7.1 system.notify ​

ts
data: {
  kind: "nudge" | "automation" | "status_change" | "error" | "info" | string
  priority?: "low" | "normal" | "high" | "urgent"   // default "normal"
  title?: string
  message?: string
  target_actor_id?: string | null                   // null = broadcast
  im_visibility?: "internal" | "public"            // default "internal"
  context?: Record<string, unknown>                 // implementation-defined
  related_event_id?: string | null                  // optional correlation
}

Rules

  • Clients MUST ignore unknown data.kind values within system.notify (open enum).
  • Implementations MAY enforce an allowlist of data.kind values, but should not assume clients understand new kinds.
  • External IM bridges MUST fail closed: a system.notify is eligible for IM delivery only when im_visibility="public". Missing, invalid, or internal values stay inside CCCC. Actor-targeted notifications remain internal even if a malformed producer also marks them public.
  • Routing: CCCC's own mail_notice and reply_notice prompts go only to their target_actor_id and are not Inbox items. For every other notification, the sender (by) never receives its own notification. A non-empty target_actor_id addresses exactly that Actor, so a notification that targets its sender reaches no one rather than everyone. Implementations also read a non-empty data.actor_id as the target when target_actor_id is absent. Without a target, to lists Actor IDs or the selectors @all, @peers and @foreman; names and titles are not resolved as they are for chat.message. Internal Actors receive a notification only when to names them; other Actors receive it when to is empty (a broadcast) or selects them.
  • by is the producer. A port that acts for a caller MUST NOT copy the caller's identity into data (for example, an MCP tool's actor_id); producers address recipients only with target_actor_id or to.

system.notify has no generic acknowledgement protocol. Domain workflows use their own durable lifecycle events, while reply obligations belong only to chat.message with message_mode="request_reply".

8. Attachments and References ​

8.1 AttachmentRefV1 ​

ts
type AttachmentRefV1 = {
  kind?: "text" | "image" | "file"     // default "file"
  path: string                         // group-scoped path (implementation-defined)
  title?: string
  mime_type?: string
  bytes?: number
  sha256?: string
  // extra fields MAY exist; clients MUST ignore unknown fields
}

8.2 ReferenceV1 ​

ts
type ReferenceV1 =
  | {
      kind?: "file" | "url" | "commit" | "text"  // default "url"
      url?: string
      path?: string
      title?: string
      sha?: string
      bytes?: number
      // extra fields MAY exist; clients MUST ignore unknown fields
    }
  | {
      kind: "presentation_ref"
      v?: 1
      slot_id: string
      label?: string
      locator_label?: string
      title?: string
      card_type?: string
      status?: "open" | "needs_user" | "resolved"
      href?: string
      excerpt?: string
      locator?: Record<string, unknown>
      snapshot?: {
        path: string
        mime_type?: string
        bytes?: number
        sha256?: string
        width?: number
        height?: number
        captured_at?: string
        source?: "browser_surface" | "pdf_viewer" | "viewer_dom" | string
      }
      // extra fields MAY exist; clients MUST ignore unknown fields
    }
  | {
      kind: "connect_group_ref"
      instance_id: string
      group_id: string
      instance_name?: string
      group_title?: string
      token?: string
    }
  | {
      kind: "task_ref"
      task_id: string
      title?: string
      status?: "planned" | "active" | "done" | "archived" | string
      // extra fields MAY exist; clients MUST ignore unknown fields
    }

Rules

  • kind="connect_group_ref" identifies a remote Group mentioned in the message, qualified by both Instance and Group ID. Names and token are display snapshots. It is advisory context, never a destination, access grant or automatic send. Consumers MUST NOT interpret its Group ID as a local destination. When asked to contact it, Agents use cccc_connect(instance_id, target_group_id) to discover the current target, then ordinary Connect messaging with both destination IDs.
  • Attachments SHOULD include content hashes where possible (sha256) to enable reproducibility/auditing.
  • path MUST be stable and retrievable within the group’s storage scope.
  • kind="presentation_ref" is a structured evidence anchor into a group Presentation slot.
    • slot_id MUST identify the target slot within the group presentation surface.
    • locator SHOULD carry best-effort position hints for the current view (for example page, heading, row, or scroll state).
    • snapshot, when present, SHOULD be treated as a best-effort visual anchor for the quoted view.
      • snapshot.path MUST be a stable group-scoped blob path.
      • Implementations SHOULD use locator for precise recovery when possible, and snapshot as a visual fallback when precise recovery is unavailable.
    • status, when present, is advisory metadata for the referenced discussion state; ledger-derived obligation status remains authoritative.
  • kind="task_ref" links a chat message to a durable shared task.
    • task_id MUST identify a task in the same working group unless explicitly documented otherwise by a relay/bridge.
    • title and status, when present, are UI hints; the task store remains authoritative.

8.3 Attachment Resolution (Non‑Normative Guidance) ​

CCCS v1 does not mandate a transport, but implementations SHOULD provide a way to resolve AttachmentRefV1.path to bytes, for example:

  • An HTTP endpoint (e.g., GET /groups/{group_id}/blobs/{path}), or
  • An RPC/IPC operation that returns attachment metadata and streams bytes.

9. Cross‑Group Relay / Forward (Provenance) ​

CCCS v1 standardizes cross-group provenance via src_group_id/src_event_id on the destination message.

Connect messages additionally qualify remote Group IDs with src_instance_id / dst_instance_id; consumers MUST NOT treat such a remote Group ID as a local Group navigation or authorization target. The device transport, immutable message metadata, durable acceptance and terminal delivery receipts are specified in CCCC_CONNECT_V1.md. Those extensions do not grant remote history, Context, TUI or arbitrary tool access. Cross-member connections also pin an immutable connection_id to the logical delivery and its replies/cancellations. Group resource generations change on import or replacement, so restored IDs/history cannot restore an old sharing grant. Neither a fresh connection nor a same-ID local Actor may fulfill an old remote obligation.

9.1 Relay Semantics ​

To relay a message from group A into group B:

  • In group B, append a chat.message whose data.src_group_id and data.src_event_id reference the original event in group A.
  • The relayed message MUST either:
    • (a) include the original text verbatim, or
    • (b) clearly indicate truncation/summarization in the message (e.g., prefix with [Summarized]) and include src_group_id/src_event_id for full content retrieval.

Rules

  • If either src_group_id or src_event_id is set, both MUST be set.
  • UIs SHOULD provide “Open source message” (jump-to) affordances.
  • If the source is unavailable due to permissions or retention, clients MUST show a clear “source unavailable” state (not silent failure).

For replies over the local cross-group transport, each copy's reply_to MUST identify the parent in that copy's Group. The source audit record retains dst_reply_to for the destination parent, so a partially delivered reply can be retried without changing either thread or its destination Group. A conflicting retry MUST be rejected before any additional ledger write. Local cross-group attachments are copied into the destination Group's own blob store before either copy is recorded, so each copy's path resolves in its own Group; invalid attachments MUST be rejected before recording a reply or settling its obligation. The local reply fulfills the addressed Actor's existing reply obligation. The reply result exposes the caller's local event, not the destination copy.

9.2 Optional Send Record ​

Implementations MAY also append an “outbound send record” in the source group (for auditability) by writing a local chat.message with:

  • dst_group_id
  • dst_to
  • dst_message_mode

An outbound send record is a human-visible local audit message: its local to MUST be ["user"] and its local message_mode MUST be "send". dst_to and dst_message_mode preserve the actual destination audience and delivery mode. This separation prevents a remote Mail or reply request from creating a fictitious human Mail item or local human reply obligation.

This record is OPTIONAL and MUST NOT be required for the destination’s provenance correctness.

10. Event Stream Subscription (Transport‑Agnostic) ​

CCCS v1 defines an abstract “event stream” interface:

  • Input: (group_id, since_cursor?, filters?, follow?)
  • Output: an ordered stream of CCCSEventV1

10.1 Cursor ​

CCCS does not mandate a single cursor type. A daemon SHOULD support at least one:

  • since_ts (timestamp cursor), or
  • since_event_id (event-id cursor), or
  • since_seq (monotonic sequence number)

Clients MUST treat cursors as opaque and MUST NOT infer ordering from id. If since_seq is supported, it SHOULD correspond to the daemon-assigned event.seq field (when present).

10.2 Filters ​

Implementations SHOULD support filtering by:

  • kinds[] (e.g., only chat.message, system.notify)
  • limit (for bounded replays)

10.3 Capability Discovery (Non‑Normative Guidance) ​

Different implementations may support different cursor types and stream filters. Implementations SHOULD expose capability discovery via their chosen transport (e.g., an info/capabilities endpoint or an IPC operation) so SDKs can adapt automatically.

To make SDKs interoperable, daemons SHOULD expose errors as:

ts
{
  code: string
  message: string
  details?: Record<string, unknown>
}

Recommended stable code values:

  • invalid_request
  • permission_denied
  • group_not_found
  • actor_not_found
  • event_not_found
  • unknown_op
  • daemon_unavailable

12. Security Considerations (Minimal v1) ​

A conforming daemon MUST:

  • Enforce single-writer semantics for the ledger.
  • Set event.by to a principal identity consistent with the deployment’s trust model (authenticated vs. local-trust IPC) and document the security properties.
  • Reject client-authored runtime.delivery events.

13. Minimal Profiles (Guidance) ​

To reduce implementation burden, CCCS v1 MAY be implemented in profiles:

  • chat.message, mail.read, chat.reply_request.cancelled
  • runtime.delivery
  • system.notify
  • Recipient token semantics (§5)

13.2 Management Profile (optional) ​

  • group.*, actor.*

CCCC emits group.foreman_change after removal of the current foreman, with data.from naming the removed Actor and data.to naming its successor or null when none remain. by retains the removal's principal. This is a management notification of the committed membership change, not an independent role assignment; consumers derive current roles from the Group's Actor list.

13.3 Context Profile (optional) ​

  • context.sync (implementation-defined ops)

Repository-backlog operations may use this event with a backlog file snapshot reference and backlog.* changes. They do not invent a Context version or embed the Markdown content; see the daemon IPC backlog contract. A Context-only refresh does not reload this external file.

14. Examples ​

The following examples use placeholder IDs for brevity. Conformance test vectors with complete values may be provided separately.

14.1 Send + Reply Request ​

json
{
  "v": 1,
  "id": "01HZY2... (opaque)",
  "ts": "2026-01-13T10:00:00Z",
  "kind": "chat.message",
  "group_id": "g_123",
  "scope_key": "s_abc",
  "by": "user",
  "data": {
    "text": "Please review the release checklist today.",
    "format": "plain",
    "message_mode": "request_reply",
    "to": ["foreman"]
  }
}

Runtime acceptance:

json
{
  "v": 1,
  "id": "01HZY3... (opaque)",
  "ts": "2026-01-13T10:01:00Z",
  "kind": "runtime.delivery",
  "group_id": "g_123",
  "scope_key": "",
  "by": "system",
  "data": {
    "actor_id": "foreman",
    "source_event_id": "01HZY2... (opaque)",
    "delivery_id": "delivery:foreman:01HZY2...",
    "state": "accepted",
    "transport": "managed_session"
  }
}

14.2 Cross‑Group Relay ​

Destination group message:

json
{
  "v": 1,
  "id": "01HZY4... (opaque)",
  "ts": "2026-01-13T10:02:00Z",
  "kind": "chat.message",
  "group_id": "g_dst",
  "scope_key": "",
  "by": "svc:relay",
  "data": {
    "text": "Relayed: please review the release checklist today.",
    "message_mode": "send",
    "to": ["@all"],
    "src_group_id": "g_src",
    "src_event_id": "01HZY2... (opaque)"
  }
}

Historical manual Bridge receipts ​

Manual Group Bridge is retired. Original message events and source scope are not rewritten. Startup finalization may append chat.cross_group_receipt with group_bridge_retired=true, the original source Event/operation/registration and idempotency key, and status=sent|failed|unconfirmed. Unconfirmed is not proof of failure or permission to resend. Receipts and a deduplicated internal user notice must be committed before their old queue records are removed. No remote grant is inferred from history. Read-only status projections may annotate affected messages with _retired_bridge=true; replay must preserve it and consumers must not offer an active reply through that retired route. See Daemon IPC.

Standalone Direct Group connections use the same cross-instance provenance, Actor generation, immutable connection ID and durable receipt rules. Their direct-<UUID> grant authorizes only the paired Group generations and carries no membership account/device authority. Removal or replacement cannot redirect an existing delivery or let a new connection fulfill its obligation. See the Direct connection specification.

Released under the Apache-2.0 License.