chap

CHAP (Collaborative Human Agent Protocol) is an open protocol and runtime for auditable human-agent collaboration, compatible with MCP and A2A. Its goal is to provide an accountable way to record work completed jointly by humans and agents.

Purpose In teams involving a large number of agents and people, agents handle drafting, triage, and recommendations, while humans handle approval, correction, rejection, and escalation. These human decisions are usually scattered only across chat logs, ticket comments, and memory. CHAP gives these decisions explicit structure and an auditable record: what the agent produced, what decision the human made, and why, all recorded in a queryable, verifiable log.

Main capabilities

• Structured override: when a human edits an agent's work, the edit is recorded together with the diff, rationale, and team-defined tags, making later analysis easier.
• Tamper-evident log: every change is recorded in order. When hash chaining is enabled, if the retained recent chain head is outside the operator's control, tampered entries will be detected during verification (see SECURITY.md §5). Historical records can be preserved across key rotation, vendor log expiration, and personnel changes.
• Signing and identity: optional extensions (called profiles) require every call to be signed, bind signing keys to verified identities, and submit entries to a transparency log.
• Coexistence with MCP and A2A: MCP connects agents and tools, A2A connects agents and agents, and CHAP records work shared by agents and humans.

Protocol structure CHAP is a set of calls sent to a coordinator by agents, humans, and their tools; the coordinator is the service that mediates the workspace. The coordinator checks each call according to workspace rules, responds, and records every accepted change in the workspace audit log. The TypeScript and Python packages are the coordinator, and can be embedded in your own process or run as a server. The verbs are their names: tasks are created, completed, and sent for review (task.create, task.complete, review.request); reviewers approve, reject, or override (decide.approve, decide.reject, decide.override); work is handed off or escalated (handoff.propose, escalate.raise); audit.read returns records.

Core and configurationProfiles Every coordinator implements Core (core/1.0): workspaces, participants, tasks, and audit logs. Everything else is an optional profile, named with a version. review/1.0 adds review requests and decisions; other profiles add quick questions to humans (whisper/1.0), group voting (deliberation/1.0), handoff (handoff/1.0), pause and rollback (control/1.0), routing (routing/1.0), shadow and trial modes (modes/1.0), signed calls (security-signed/1.0), verified identity (identity-oidc/1.0, identity-vc/1.0), and transparency logs (audit-scitt/1.0). A workspace declares the profiles it uses, and the coordinator rejects calls that belong to other profiles. core/SPEC.md condenses Core onto one page, profiles/PROFILES.md lists all profiles, and GLOSSARY.md defines every term.

How to use

• New project: create-chap-app can generate a project with a review console, a profile setup, and a diff-profiles command. The default template is a code gate: every change by a coding agent in a git repository is reviewed as a diff, approved with a reviewer's signature, and committed together with evidence for CI to verify. Other templates include MCP gates for Claude Desktop, Cursor, and Claude Code, a support desk, an outbound approval gate, and a production set. docs/profile-explorer.md shows what each profile brings.
• Clone from the repository: START_HERE.md runs a local review console on the Python coordinator, requiring only Python 3.10 or higher, with nothing else to install. examples/00-five-minute-start.md uses curl to send an envelope to the Core reference server and read back the audit log. The libraries are in packages/coordinator/ and packages/coordinator-py/, and the reference implementations are in reference/ and reference/python/.
• 90-second demo: shows a singleA developer uses Cursor to review a pull request, the bot flags a warning that the developer disagrees with, and the demo shows the entire interaction in six steps, about 23 seconds. The code for each step is given in TypeScript and Python. TypeScript provides a typed facade coord.api.*, with autocompletion and compile-time checking for every method; Python keeps the JSON-RPC envelope coord.dispatch({...}) at the surface, here wrapped in a send() helper function, which is the idiom used by the Python tests. Both send the same parameters and envelope, so the audit chain reads back consistently no matter which client calls it.
• Analytics: chap-analytics (pip install chap-analytics) loads the entire chain into documented pandas tables, and the source can be a SQLite file, a JSON export, a live coordinator, or audit.read, covering overrides, decisions, reviewers, whispers, and handoffs. There is a notebook that processes one week of review data, and ANALYTICS_ROADMAP.md describes the planned work.

Override Envelope The override envelope records a reviewer's changes to agent output. Two fields matter most for analytics: intent_preserved distinguishes refinement overrides (a person keeps the agent's decision but rewrites the wording) from replacement overrides (a person makes a different decision). The former more often points to a retrieval problem in the agent, while the latter more often points to policy ambiguity or a problem with the agent's task context. tags is a small controlled vocabulary agreed on by the team, and after three months it can be used to count which prompts need improvement and which paths the bot always gets wrong.

Applicable Scenarios

• Agent workflows that require human approval, override, handoff, and escalation.
• Compliance or accountability scenarios that require auditable, verifiable evidence logs.
• Multi-agent and human collaboration systems integrated with MCP or A2A.
• Framework bridges using LangGraph, Pydantic AI, AG2, LlamaIndex Workflows, and Google ADK to record human-in-the-loop decisions in the audit log.

Limitations and Status CHAP 0.3 is a public draft: a small Core and optional profile files (SPECIFICATION.md). Two reference coordinators (TypeScript and Python) implement the same methods, and a differential fuzzer checks whether their responses and recordsare consistent. The conformance test tooling covers Core and review/1.0 and can run against the Python coordinator and the standalone TypeScript server. A coordinator can present itself as an MCP server or an A2A agent. Before 1.0, minor versions may introduce breaking changes, and the changelog will list each breaking change and how to migrate; starting with 1.0, the specification follows semantic versioning. If you need strict stability, wait for 1.0: ROADMAP.md lists what it will commit to and the milestones along the way.

License The specification text uses CC BY 4.0 (see LICENSE-SPEC.md), and everything else uses Apache 2.0. Any language and any deployment method are fine.