# CHAP – Collaborative Human-Agent Protocol

> An open protocol for auditable human-agent collaboration, giving approvals, overrides, handoffs, and escalations a structured, verifiable, hash-linked record compatible with MCP and A2A.

CHAP (Collaborative Human-Agent Protocol) is an open standard published by Brightbeam AI for structuring and auditing the moment a human steps into an AI agent workflow. It captures approvals, overrides, handoffs, and escalations as typed, hash-linked envelopes rather than letting them dissolve into chat threads and ticket comments. The specification is licensed CC-BY 4.0 and the reference code is Apache 2.0, royalty-free for any language or deployment.

## What It Is

CHAP defines a JSON-RPC 2.0 wire protocol with seven core methods — `workspace.describe`, `participant.join`, `participant.leave`, `task.create`, `task.update`, `task.complete`, and `audit.read` — that together create a shared, policy-bound workspace where humans and agents collaborate. Every action produces an envelope whose `prev_hash` field chains it to the previous entry using SHA-256 over JCS-canonicalised content, making the log append-only and tamper-evident. Optional profiles layer on top of the small core: `review/1.0` adds approve, reject, override, abstain, and escalate; `security-signed/1.0` adds Ed25519 per-message signatures; `audit-scitt/1.0` anchors the chain in an IETF SCITT transparency log for offline-verifiable receipts.

## How the Override Envelope Works

The `decide.override` envelope is the centrepiece of CHAP. When a human edits an agent's draft, the envelope captures:

- **`diff`** — an RFC 6902 JSON Patch describing exactly what changed
- **`rationale`** — a free-text reason typed by the reviewer
- **`intent_preserved`** — a boolean distinguishing a *refining* override (same decision, better expression) from a *substituting* override (different decision entirely)
- **`tags`** — a controlled vocabulary the team defines, which accumulates into a supervision dataset as a side-effect of normal review
- **`policy_refs`** — references to the policies that governed the decision

The distinction between refining and substituting overrides matters operationally: a high refining rate on a policy clause points to weak retrieval or a poor template; a high substituting rate points to ambiguous policy or missing task context. These tune to different fixes.

## Protocol Composition and Standards Reuse

CHAP is designed to sit beside MCP and A2A rather than replace them. MCP tool calls are recorded as citations inside CHAP artefacts; A2A peers appear as bridge participants in the workspace. The protocol defers to established standards throughout: JSON-RPC 2.0 for the wire, OIDC and W3C Verifiable Credentials for identity, IETF SCITT for transparency logs, and in-toto for attestations. The repository ships ready-to-adapt integration guides for CHAP + MCP, CHAP + A2A, and CHAP + OIDC/OAuth2, plus five framework bridges covering LangGraph, Pydantic AI, AG2, LlamaIndex Workflows, and Google ADK.

## Deployment and Setup Path

Reference implementations exist in both TypeScript (npm: `@brightbeamai/chap-coordinator`) and Python (PyPI: `chap-coordinator`). Both emit identical wire bytes; the audit chain is byte-for-byte the same regardless of which client made the call. A five-minute start guide runs the reference server locally with SQLite persistence and sends envelopes with `curl` — no SDK, identity provider, or signing setup required for the first walkthrough. The conformance harness ships in the repository and the GitHub README reports 23/23 conformance vectors passing as of the latest release.

## Update: v0.2.11

The latest release is **v0.2.11** (published 2026-08-20), described in the GitHub metadata as "coordinator-mcp namespace casing." CHAP is currently at **v0.2 — a public draft**. The homepage states the wire format and schemas are stable for review; the Core runs; the review profile and a routing-aware playground are runnable; and conformance scaffolding is in the repository. Wire-format changes in 0.x remain possible. The headline step to 1.0 is a second independent implementation — independent meaning from outside Brightbeam; the two existing reference implementations (TypeScript and Python) are both from Brightbeam and do not count toward that milestone. Hierarchical workspaces are an explicit candidate for v0.3, and hybrid post-quantum signatures are named as future work.

## Governance and Open-Source Model

The specification is governed to resist capture: at least three Steering Committee seats must be held by people not employed by the largest contributor, and no single party — including Brightbeam — can steer it unilaterally. A CHAP Enhancement Proposal (CEP) cannot be accepted without a working reference implementation, and vendor-specific extensions are explicitly out of scope. The project cites the pattern of TCP/IP, HTTP, OAuth, OIDC, and MCP as evidence that open shared standards become the basis of many platforms, and frames CHAP as the accountability layer that human-agent collaboration will need to standardise one way or another.

## Features
- Seven core JSON-RPC 2.0 methods for workspace, participant, task, and audit management
- Append-only, SHA-256 hash-linked evidence log
- Structured override envelopes with diff, rationale, intent_preserved, tags, and policy_refs
- Optional profiles: review, modes, routing, deliberation, whisper, handoff, identity-oidc, identity-vc, security-signed, audit-scitt, control
- Ed25519 per-message signatures with JCS canonicalisation
- IETF SCITT transparency log anchoring for offline-verifiable receipts
- MCP tool calls recorded as citations inside artefacts
- A2A peers appear as bridge participants
- OIDC and W3C Verifiable Credentials identity binding
- Override analytics and supervision dataset accumulation as a side-effect of normal review
- Conformance harness with 23/23 test vectors passing
- TypeScript and Python reference implementations with SQLite persistence
- Five framework bridges: LangGraph, Pydantic AI, AG2, LlamaIndex Workflows, Google ADK
- 12 worked scenarios from solo developer to GMP-regulated manufacturing
- Five-minute curl-only quickstart with no external dependencies

## Integrations
MCP (Model Context Protocol), A2A (Agent-to-Agent Protocol), OIDC / OAuth2, W3C Verifiable Credentials, IETF SCITT, in-toto attestations, LangGraph, Pydantic AI, AG2, LlamaIndex Workflows, Google ADK, Claude Code, Cursor, SQLite

## Platforms
LINUX, API, DEVELOPER_SDK, CLI

## Pricing
Open Source

## Version
v0.2.11

## Links
- Website: https://chap.brightbeam.works/
- Documentation: https://github.com/BrightbeamAI/chap/blob/main/SPECIFICATION.md
- Repository: https://github.com/BrightbeamAI/chap
- EveryDev.ai: https://www.everydev.ai/tools/chap-collaborative-human-agent-protocol