Copyright (c) 2026 Joe Feser.
Website: hacp.io
HACP is Human-Approved Coordination Protocol: a protocol for accountable delegation to agents and tools. It preserves the original request, source context, evidence, approved boundaries, send-back notes, stop reasons, audit trail, and final human decision so delegated work remains reviewable.
The draft is evidence-led. It comes from practical implementation experience with human-approved task packets, agent reports, review findings, decision gates, bounded iteration, and audit evidence. The public draft keeps the reusable contracts and leaves product-specific implementation details out of scope.
HACP is a human-approved coordination protocol with a vendor-neutral contract design goal. It defines packet, report, evidence, decision, stop, and audit contracts for accountable AI-assisted workflows. HACP sits as a control layer above tools, queues, CLIs, GitHub bots, agents, and adapters; it does not replace those systems or turn them into an autonomous execution engine.
The current dogfood slice helps preserve evidence, authority boundaries, and human decisions around delegated review workflows. PR review is one useful example, not the whole protocol. The same records can apply to launch change approval, local approved-tool checks, compliance evidence review, or agent handoff acceptance. The current implementation is a local/product-controlled trial slice, not an autonomous execution platform.
HACP does not execute shell/model/tool work by itself. File transport, CLI transport, and adapter delivery paths move records, but they do not grant authority. Report verification confirms custody and integrity checks, not task completion proof.
Risky authority transitions remain human-decision gated.
Task Packet: the scoped request, source context, authority boundaries, expected evidence, stop conditions, and approved profile references.Agent Report: the returned report from a worker, runner, reviewer, or agent. It records what was attempted, what evidence was produced, and which proof binds the report to the packet.Evidence Set: source links, summaries, check outputs, review findings, digests, and report artifacts used to support a human decision.Human Decision: the explicit approve, hold, reject, revise, send-back, or stop decision made by the accountable human.Audit Log: the append-only readback of packets, reports, evidence, decisions, rejects, send-back notes, and stop reasons.
Source context is first-class decision context. It may include the original human request, prompt or packet, spec or acceptance criteria, repo/issue/PR context, imported report source, and prior send-back notes. A future reader should be able to see what the human was deciding before auditing how the protocol represented it.
Send-back, or reject-with-notes, is a normal correction path. A human can send work back when evidence is stale, unclear, incomplete, mismatched, or outside the approved boundary. The decision preserves the original source context, the reason, the human notes, the requested correction, the expected next state, and the boundary that no automatic execution or mutation follows from the note.
Approved tool profiles describe reviewed tool identity, version, command shape, allowed and forbidden parameters, risky flag approval references, runtime/toolchain expectations, network/write policy, ownership, expiry, evidence references, and profile digest or equivalent proof. A fail-closed preflight stops before trusted work proceeds when the packet, profile, command, parameter, risky flag, runtime, or report proof does not match, then returns diagnostics for a human decision.
Runner report import proof is evidence custody: a scoped Task Packet is approved, an owner-controlled runner or agent performs work outside HACP core, the runner emits an Agent Report with evidence and digest/profile bindings, a verifier imports and checks the report, and a human reviews the evidence before deciding the next step. Imported proof supports a Human Decision; it is not automatic completion, merge approval, tool authorization, or proof that every downstream effect happened correctly.
See:
- docs/glossary.md
- docs/event-lifecycle.md
- docs/authority-boundaries.md
- docs/adapters-and-projections.md
- docs/workflows/owner-controlled-bridge.md
- docs/cli-bridge-contract/v0/README.md
- examples/public-packaging/v0/README.md
HACP is:
- a protocol for human-approved coordination
- a contract for packet/report/evidence/decision custody
- a way to audit gates, authority, and stop outcomes
HACP is not:
- an autonomous orchestration runtime
- a hosted shell
- model/tool routing authority
- a GitHub mutation authority
- a runtime dispatcher
- a RabbitMQ replacement
- a replacement for human approval
- completion proof by report presence or verification
HACP records, profiles, reports, and imported proof do not authorize shell commands, GitHub mutation, model/tool calls, runtime dispatch, approval replacement, automatic completion, merge readiness, risk acceptance, or future integrations written as if they are already shipped. Those effects require separate owner-approved tools, profiles, runtime boundaries, and explicit human decisions.
Teams are starting to use agents and automation for real work, but the approval trail is often still a mix of chat history, screenshots, ticket comments, and human memory. That is fragile when the work can affect customers, executives, orders, listings, communications, deployments, business records, or other authority-bearing workflows.
HACP is for the moment when a human wants help from agents or tools, but still needs to know:
- what was approved;
- who or what received the work;
- what evidence came back;
- whether the work stayed inside scope;
- which human accepted, rejected, revised, canceled, or completed the work.
Bounded work means work with an explicit, human-approved scope that the participant is not allowed to exceed.
HACP provides a record model for accountable delegation:
- A human approves a bounded work packet.
- The packet is carried to an agent, tool, adapter, or human workflow participant.
- The participant returns structured evidence.
- The returned work is matched to the approved packet.
- A human records a decision such as accept follow-up, mark complete, request revision, reject report, cancel session, or request continued human review.
The goal is not unchecked autonomy. The goal is useful automation with explicit human gates where risk, authority, customer impact, cost, or organizational policy requires review. In HACP, reports are evidence, not authorization.
Human-in-the-loop (HITL) is the broad workflow pattern: a human reviews, approves, rejects, escalates, or accepts responsibility at selected points in an automated or AI-assisted workflow.
HACP is narrower. It is a protocol-shaped approach inside the broader HITL family, focused on accountable delegation and chain of custody. HACP records what a human approved, who or what received the work, what evidence came back, whether that evidence matched the approved boundary, and which human decision followed.
Not every HITL workflow needs HACP. HACP is most useful when an output might be mistaken for authority: a report may look final, a recommendation may create action pressure, or a pre-flight check may be treated as a go/no-go decision. In HACP, those outputs remain evidence until a human decision record accepts, rejects, revises, cancels, or completes the next step.
For concrete examples, start with the explanatory HACP use cases. If you are asking "what problem does this solve?", that page is the best first read before the protocol vocabulary. Its terms section defines reader-facing terms such as owner system, authority, consequential state change, and matrix drift.
HACP is not a standard yet. It is a working draft and candidate protocol based on practical implementation evidence. WITS independently produces the seven v0.3 candidate record kinds and HACP cross-validates that encoding. The pinned who-decides 44-case proof supplies separate bounded evidence for the underlying one-use continuation semantics; it does not produce or validate the v0.3 record encoding. Together these are useful candidate evidence, not a claim of distributed execution, external effects, bidirectional production, or standard maturity. Vendor-neutrality remains a design goal and needs feedback from implementers who did not inherit the original project context.
This repository is intended for public review of the draft contracts. Do not describe an implementation as "HACP compliant" yet; use narrower labels such as "implements the HACP v0.1 draft base profile" and cite the evidence that was checked.
- draft artifact vocabulary for packets, reports, stops, findings, decisions, evidence sets, and loop policies;
- draft JSON Schema pack for machine-checkable artifact shape and vocabulary;
- valid/invalid example corpus with manifest expectations;
- local
hacp:doctorvalidation flow for repeatable draft checks; - explicit authority boundary language that keeps approval and risk acceptance human-owned.
- product-specific UX/readback and governance workflows;
- interoperability claims beyond the two bounded candidate implementations and their published limitations;
- any claim that schema validation alone proves operational safety;
- any maturity framing that implies a finalized or ratified standard.
Use these lanes when describing HACP externally: "working draft with proven local evidence" is accurate; "formal standard" is not.
HACP 0.2 is a new experimental protocol draft that frames HACP as a chain-of-custody protocol for human-authorized agent work. It adds handoff packages, match proofs, human decision records, digest domains, and explicit transport/execution profile separation.
Here, chain of custody means each report can be traced back to the exact human-approved work boundary it claims to answer.
Start here:
- docs/use-cases.md: explanatory human-facing examples of where HACP can help and how ordinary workflows map to protocol records.
- docs/hacp-0.2.md: core vocabulary, lifecycle, record model, digest domains, and audit/replay posture.
- docs/profiles.md: transport profiles and execution profiles, with registry values in profiles/hacp-base-draft-v0.2.yaml.
- docs/cli-bridge-contract/v0/README.md: public candidate package for owner-controlled CLI bridge profile, preflight, runner evidence, waiver, import, digest, doctor, and stop-reason objects.
- docs/workflows/ack-pr-loop-runbook.md: repo-local ACK PR-loop worker guidance, including lane loading, reviewer batching, stale-summary waiting, handoff artifacts, and human-mediated main promotion posture.
- docs/source-packets/wits-v0-hacp-source-packet.md: public-safe WITS v0 source packet for task packets, agent reports, human decision gates, evidence, stop reasons, transport envelopes, and fixture candidates.
- docs/source-packets/wits-v0/accountable-continuation-v0.3-draft.md: HACP v0.3 candidate source packet for one-successor consumption receipts, fail-closed extension processing, and accountable continuation evidence.
- docs/security-boundaries.md: authority, report, match-proof, human-decision, digest-domain, and fail-closed boundaries.
- docs/non-goals.md: what HACP 0.2 does not define.
- docs/review-packet.md: severity-ordered review packet for the 0.2 draft.
HACP 0.2 is not 1.0. HACP v0.3 is an earlier candidate with executable schemas, not a released standard or conformance profile. Both remain draft or candidate vocabulary and fixture material for review and independent implementation feedback.
For maturity framing across v0.1 and v0.2, see Stability Lanes.
The preferred place for early v0.1 feedback is Discussion #2: HACP v0.1 public review. HACP 0.2 is a newer experimental draft; use docs/review-packet.md when asking for focused 0.2 protocol review.
Please use that thread for broad feedback, protocol risks, implementation questions, and "does this framing work?" reactions. For structured v0.1 protocol reviews, consider using the review-packet.md template.
Use issues for concrete defects such as contradictions between RFCs, schema bugs, broken examples, or unclear conformance requirements.
| RFC | Title | Status |
|---|---|---|
| RFC-0000 | Motivation and Scope | Draft |
| RFC-0001 | Task Packet | Draft |
| RFC-0002 | Authority Vocabulary and Profiles | Draft |
| RFC-0003 | Agent Report | Draft |
| RFC-0004 | Review Finding | Draft |
| RFC-0005 | Human Decision Gate | Draft |
| RFC-0006 | Loop Ceiling and Bounded Iteration | Draft |
| RFC-0007 | Audit Trail and Evidence Set | Draft |
| RFC-0008 | Transport Boundary | Draft |
| RFC-0009 | Conformance and Profiles | Draft |
| RFC-0010 | Packet Assembly Attestation | Experimental Draft |
HACP 0.2 is an experimental public draft, not a stable conformance target. It is reviewable through the 0.2 docs, schemas, profile registry, and fixtures listed above. It should not be described as HACP 1.0 or as generally compliant until independent implementations and conformance fixtures exist.
HACP v0.3 candidate material includes an executable conformance package. It explores accountable continuation, consumption receipts, successor invocation evidence, and extension fail-closed behavior. It does not define a released standard, runtime, worker launch path, hosted execution surface, or product feature.
The current draft set is minimally reviewable as a v0.1 protocol sketch. It is not a standard, and it should not be described as vendor-neutral until at least two independent implementations validate the contracts.
HACP v0.1 base-profile conformance depends on these RFCs remaining mutually consistent:
- RFC-0000 Motivation and Scope
- RFC-0001 Task Packet
- RFC-0002 Authority Vocabulary and Profiles
- RFC-0003 Agent Report
- RFC-0004 Review Finding
- RFC-0005 Human Decision Gate
- RFC-0006 Loop Ceiling and Bounded Iteration
- RFC-0007 Audit Trail and Evidence Set
- RFC-0008 Transport Boundary
- RFC-0009 Conformance and Profiles
Profile extensions are only conforming when they meet RFC-0009 and preserve the invariants in RFC-0000. Automated transport claims additionally depend on the RFC-0008 transport-boundary checks.
| Area | Depends on |
|---|---|
| A packet can grant bounded authority | RFC-0000, RFC-0001, RFC-0002, RFC-0005 |
| A returned report can be reviewed | RFC-0001, RFC-0003, RFC-0004, RFC-0007 |
| Review/fix loops remain bounded | RFC-0004, RFC-0005, RFC-0006, RFC-0007 |
| Manual transport remains non-authorising | RFC-0001, RFC-0005, RFC-0008 |
| Automated transport can claim conformance | RFC-0008, RFC-0009 |
- Human authority is explicit and cannot be silently delegated away.
- Authority originates with a human approval act and is recorded or referenced by an approved task or authority packet, not by the mechanism that transports the packet.
- Manual and automated transport are different layers. Moving a packet does not widen the packet's authority.
- Closed vocabularies must not silently widen. Profiles may extend them only under declared conformance rules.
- Reports, findings, decisions, and audit evidence must be readable by humans and mechanically checkable by tools.
The v0.1 public review surface is intentionally small:
- the RFC drafts in rfcs/;
- the base profile declaration in profiles/hacp-base-draft-v0.1.yaml;
- the base decision matrix in decision-matrix-base-v0.1.yaml;
- the draft schemas in schemas/;
- the minimal end-to-end example in examples/minimal-v0.1/.
The v0.2 public review surface is the draft chain-of-custody packet:
- docs/use-cases.md as explanatory context;
- docs/hacp-0.2.md;
- docs/profiles.md;
- docs/security-boundaries.md;
- docs/source-packets/wits-v0-hacp-source-packet.md;
- docs/non-goals.md;
- profiles/hacp-base-draft-v0.2.yaml;
- the v0.2 schemas in schemas/;
- the v0.2 fixtures in fixtures/happy-path/ and fixtures/risk-cases/.
The v0.3 candidate review surface includes source-packet material and an executable candidate package:
- docs/source-packets/wits-v0/accountable-continuation-v0.3-draft.md;
- candidate JSON sketches in docs/source-packets/wits-v0/examples/.
- closed candidate schemas and computed vectors in schemas/v0.3-candidate/.
Packet-construction provenance is explored separately in RFC-0010 and the experimental packet-assembly-attestation package. It does not modify or extend the published v0.3-candidate package.
Implementation-specific trial artefacts are not required to review this public draft. The v0.3 candidate package includes bounded public evidence, conformance fixtures, and an independent-implementation report. Future work may add other implementations, distributed-effect evidence, and the bidirectional evidence required for full-release consideration.
Use review-packet.md when asking another model, reviewer, or tool owner to assess the v0.1 draft set. Use docs/review-packet.md for HACP 0.2. Both keep the review focused on protocol risks instead of wording polish.
Use site/README.md as the plain-language HACP public explainer. It summarizes the value, lifecycle, artifacts, validation story, and authority boundaries before readers move into the full spec.
Use site/navigation.md for role-based paths:
- New to HACP
- Enterprise/governance
- Implementing
- Reviewing protocol
- Validating examples
Use site/faq.md for public objection handling, including:
- "We already have PR reviews and CI"
- "We do not want another agent platform"
- "We need auditability, not more chat"
- "We cannot let agents approve work"
Use spec/README.md as the public-facing HACP spec draft. It explains the artifact model, authority boundaries, stop semantics, loop policy, and validation story.
Use adoption-primer.md for a concise, public-facing enterprise explainer covering HACP scope boundaries, governance language, and ecosystem mapping across GitHub, Azure DevOps, agent CLIs, and CI/CD policy surfaces.
Use quickstart.md for the smallest useful local loop using the draft schema examples and expected exit-code behavior.
HACP is not an agent runtime. HACP is not a transport protocol. HACP is not a replacement for human approval. HACP does not execute work, dispatch packets, call models, write GitHub, merge, deploy, ship, or accept risk. Validation output is evidence for review, not approval.
Use examples/minimal-v0.1/README.md for a small end-to-end fixture: one approved packet, one returned report, one review finding, and one JSON Lines audit export. It is intentionally tiny, so protocol reviewers can test the RFC contracts without inheriting an implementation's non-public evidence tree.
Use diagrams.md for non-normative visual aids covering the minimal lifecycle, authority boundary, base decision matrix, and core record relationships. The decision-matrix diagram is generated from decision-matrix-base-v0.1.yaml with scripts/generate_decision_matrix_mermaid.py.
Use examples/integrations/pyrapide/README.md for a non-normative sketch of how HACP audit events could map into a PyRapide-style causal event graph for invariant checking.
HACP is still pre-standardisation work. The most useful contributions are:
- protocol-risk findings ordered by severity;
- contradictions between RFCs, schemas, examples, and the decision matrix;
- evidence that a contract is not independently implementable;
- small interoperability fixtures or schema-validation cases.
Use review-packet.md for a focused v0.1 review prompt, docs/review-packet.md for a focused v0.2 review prompt, and see CONTRIBUTING.md for contribution expectations.
See LICENSE.md. The draft prose is offered under CC BY 4.0, and machine-readable artefacts, schemas, examples, validation fixtures, executable source code, and validation or generation scripts are offered under Apache-2.0 unless a file states otherwise.
v0.1 artefacts:
- profiles/hacp-base-draft-v0.1.yaml: base profile declaration, authority mappings, and forbidden-effect declarations.
- decision-matrix-base-v0.1.yaml: base Human Decision Gate status-transition matrix.
- schemas/README.md: draft schema pack index and limitations.
- schemas/task-packet.schema.json
- schemas/agent-report.schema.json
- schemas/human-decision.schema.json
- schemas/evidence-set.schema.json
- schemas/stop-response.schema.json
- schemas/review-finding.schema.json
- schemas/loop-policy.schema.json
- schemas/examples/manifest.json
- schemas/examples/valid/
- schemas/examples/invalid/
v0.2 artefacts:
- profiles/hacp-base-draft-v0.2.yaml: base registry for record kinds, profiles, digest domains, report shapes, and decisions.
- schemas/common-defs.schema.json: shared v0.2 digest and decision-rule reference definitions.
- schemas/authority-packet.schema.json
- schemas/handoff-package.schema.json
- schemas/adapter-report.schema.json
- schemas/match-proof.schema.json
- schemas/human-decision-record.schema.json
- fixtures/happy-path/
- fixtures/risk-cases/
experimental future record families:
- packet-assembly-attestation v0.1 draft: authenticated construction-claim shape, trust-bound validation harness, and positive/negative fixtures. This is not part of HACP v0.3-candidate.
The draft prose explains the contracts, but machine-readable vocabulary should come from the companion artefacts:
- profile, record-kind, authority, impact, evidence-visibility, actor, finding, and profile-status vocabularies come from profiles/hacp-base-draft-v0.1.yaml;
- status and decision-transition vocabularies come from decision-matrix-base-v0.1.yaml;
- HACP 0.2 profile, record-kind, digest-domain, requested-report-shape, review-condition, and decision vocabularies come from profiles/hacp-base-draft-v0.2.yaml;
- structural packet/report validation starts from schemas/.
If prose, examples, schemas, profile declarations, or the decision matrix disagree, treat that as a draft defect and report it.