Human–Agent Coordination Protocol Specification

1.1Positioning

HACP is a generic, cross-platform provenance protocol for agent actions. It is not tied to one model provider, agent framework, transport, organization, or application domain. The same Decision, Mandate, ActionEnvelope, and Receipt model can protect commerce, software changes, infrastructure operations, communications, data access, and other consequential actions.

HACP composes with the existing agent and web security stack rather than replacing it:

• AuthenticationWeb Bot Auth, OAuth, mTLS, or workload identity establishes which agent is calling.

• TransportHTTP, MCP, A2A, queues, or internal RPC carries the request.

• HACP provenanceEstablishes which human or institution authorized the action, what they decided, which constraints apply, and whether the concrete effect remains within that authority.

• Receiver policyThe receiving service independently decides whether the authenticated, provenance-backed action should be accepted.

This separation makes HACP portable across platforms and verifiable across organizational boundaries without asking a receiver to trust an agent’s private reasoning or its claim of good intent.

1.2Why HACP is needed

A website often sees an agent as just another API client. Consider two nearly identical airline booking requests: one comes from a trusted travel agent that Alice asked to book a Friday flight to New York for no more than $600; the other comes from an attacker-controlled agent attempting an unwanted purchase. Authentication can identify the software making each request, but it cannot prove which human authorized the booking, what that person intended, or whether the selected flight and price remain inside their instructions.

HACP gives the legitimate request a verifiable chain: Alice’s reviewed Decision, the exact limits she approved, the identity of the agent she authorized, and the concrete booking action the agent proposes. The airline verifies that chain and applies its own policy before creating the reservation. It can allow a properly authorized booking, request human review when evidence is insufficient, or deny an anonymous, altered, expired, replayed, or out-of-scope request.

1.3Key goals

• Portable provenanceCarry decision authority across agents, organizations, and transports without exposing an entire private conversation.

• Bounded delegationDelegate narrow, time-limited authority to a named agent and require monotonic attenuation across subdelegation.

• Receiver enforcementAllow websites and APIs to evaluate agent identity, human provenance, intent, constraints, and issuer trust before accepting an effect.

• Independent auditProduce cryptographically verifiable records that an authorized auditor can validate after execution.

• Protocol neutralityKeep the canonical semantics independent of HTTP, A2A, MCP, gRPC, or a specific identity system.

1.4Guiding principles

Human authority is explicit. Model inference is never equivalent to consent. Verification is local. Each receiver chooses its own trust anchors and risk policy. Disclosure is minimal. Proof of authority should not require disclosure of chain-of-thought or unrelated human communication. History is append-only. Correction and revocation create new records rather than rewriting the evidence available at action time.

1.5Specification structure

Core semantics remain invariant across bindings. A custom binding MUST provide representations equivalent to the canonical objects and MUST preserve the verification order defined by this specification.

1.6Normative content

The keywords MUST, MUST NOT, REQUIRED, SHOULD, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL are to be interpreted as requirement levels. Examples, diagrams, rationales, and implementation notes are informative unless explicitly marked normative.

2.1Actors

2.2Core concepts

3.2Operation semantics

Replay protection

Every ActionEnvelope carries a single-use nonce. The reference verifier scopes nonce consumption to the receiving audience and authenticated Agent, and production stores must consume it atomically.

Versioning

Clients MUST send the protocol major and minor version. Servers MUST process the declared semantics or return VERSION_NOT_SUPPORTED; they MUST NOT silently downgrade authorization behavior.

Three-valued disposition

ALLOW means all required checks passed. DENY means a non-recoverable verification or policy condition failed. REVIEW pauses the effect until fresh human judgment or missing evidence is supplied.

4.1Decision

{
  "hacpVersion": "0.1",
  "type": "decision",
  "id": "dec_01J8Z5XNT7",
  "state": "ATTESTED",
  "principal": {
    "id": "did:web:acme.example:users:alice",
    "type": "HUMAN",
    "organization": "did:web:acme.example"
  },
  "intent": {
    "type": "flight.book",
    "statement": "Book a Friday afternoon flight to NYC."
  },
  "constraints": {
    "maxAmount": { "currency": "USD", "value": "600.00" },
    "departureWindow": "2026-09-18T12:00:00-07:00/2026-09-18T18:00:00-07:00"
  },
  "evidence": [{
    "mediaType": "application/vnd.slack.message",
    "digest": "sha256:7e9f...",
    "disclosure": "DIGEST_ONLY"
  }],
  "fieldSources": [{
    "path": "/constraints/maxAmount",
    "basis": "ASSERTED",
    "evidenceDigest": "sha256:7e9f..."
  }],
  "createdAt": "2026-09-12T18:42:00.000Z",
  "attestation": {
    "method": "DIRECT_CONFIRMATION",
    "assuranceLevel": "HACP_L2",
    "attestedAt": "2026-09-12T18:42:03.000Z",
    "proof": {
      "type": "Ed25519Signature2020",
      "verificationMethod": "did:web:acme.example:users:alice#hacp-1",
      "createdAt": "2026-09-12T18:42:03.000Z",
      "proofValue": "z5Ns..."
    }
  }
}

4.2Mandate

{
  "hacpVersion": "0.1",
  "type": "mandate",
  "id": "mandate_01J8Z6M2Q4",
  "issuer": "did:web:acme.example:users:alice",
  "subject": "did:web:agents.acme.example:travel",
  "decisionRef": "dec_01J8Z5XNT7",
  "permissions": ["flight.search", "flight.purchase"],
  "constraints": {
    "destination": ["NYC"],
    "maxAmount": { "currency": "USD", "value": "600.00" }
  },
  "audience": ["https://api.example-air.com"],
  "maxDelegationDepth": 1,
  "validFrom": "2026-09-12T18:42:03.000Z",
  "notAfter": "2026-09-14T07:00:00.000Z",
  "nonce": "3f6bcda9-0db7-4f7c-a1b1-cf62eaf40b87",
  "proof": {
    "type": "Ed25519Signature2020",
    "verificationMethod": "did:web:acme.example#hacp-1",
    "createdAt": "2026-09-12T18:42:03.000Z",
    "proofValue": "z3FXQ..."
  }
}

4.3ActionEnvelope

The ActionEnvelope describes the external effect to be authorized. The Verifier evaluates the resolved target and final parameters, not only the Agent’s label for the action.

4.4Receipt and RevocationRecord

A Receipt binds the verification verdict to the ActionEnvelope digest and policy version. A RevocationRecord identifies its issuer, affected object, effective time, reason, and proof. Both are append-only audit events.

4.5Data type conventions

Timestamps use RFC 3339 UTC with millisecond precision. Monetary values use uppercase ISO currency codes and decimal strings; floating-point values MUST NOT be used for authorization limits. URIs are absolute. IDs are opaque and MUST NOT carry authorization meaning. Signed JSON is canonicalized using JSON Canonicalization Scheme semantics before hashing.

5.1Shipped binding

The 0.1 repository currently implements a Fetch-compatible HTTP binding. MCP and A2A binding profiles are roadmap items, not shipped interfaces.

6.1Identity resolution

HACP treats principal, issuer, subject, verifier, and verification-method identifiers as URIs. Deployments may use DIDs, HTTPS identifiers, workload identities, or organization-local identifiers. A trust policy decides which schemes and issuers are acceptable; HACP does not create a universal identity registry.

6.2Proof requirements

A proof MUST cover the canonical object, object type, protocol version, creation time, and verification-method identifier. Action proofs cover the exact operation, target, parameters, Mandate reference, creation time, and action nonce; the Mandate binds the audience. Verifiers MUST reject unknown critical proof parameters and algorithm substitutions.

6.3Proof suites

The 0.1 TypeScript reference implementation ships one concrete proof profile: Ed25519Signature2020. Signed objects are canonicalized before hashing and signing. Additional proof suites are future interoperability work and are not claimed by the current SDK.

7.1Extraction requirements

An Extractor MUST distinguish values explicitly asserted by a human from values inferred by a model. Inferred values carry source location, extraction method, and optional confidence. An inferred value MUST NOT broaden authority unless the applicable attestation explicitly confirms it.

7.2Attestation methods

7.3Assurance levels

8.1General requirements

HTTPS is REQUIRED. Request and response bodies use application/hacp+json. Clients send HACP-Version on every operation. Authentication remains deployment-specific but MUST be bound to the identity named by the ActionEnvelope.

8.2VerifyAction

The signed ActionEnvelope is sent directly to the protected application endpoint; HACP does not require a separate verification resource URL.

POST /flights/UA123 HTTP/1.1
Host: api.example-air.com
Content-Type: application/hacp+json
HACP-Version: 0.1
Authorization: Bearer <workload-credential>

{
  "hacpVersion": "0.1",
  "type": "action-envelope",
  "id": "act_01J8Z6P1JG",
  "mandateRef": "mandate_01J8Z6M2Q4",
  "agent": "did:web:agents.acme.example:travel",
  "action": {
    "type": "flight.purchase",
    "target": "https://api.example-air.com/flights/UA123",
    "parameters": {
      "destination": "NYC",
      "amount": { "currency": "USD", "value": "542.00" }
    }
  },
  "nonce": "80f30b3c-5c2b-4e8d-9f18-e51d9626e8f1",
  "createdAt": "2026-09-12T18:43:08.000Z",
  "proof": {
    "type": "Ed25519Signature2020",
    "verificationMethod": "did:web:agents.acme.example:travel#hacp-1",
    "createdAt": "2026-09-12T18:43:08.000Z",
    "proofValue": "z4Qm..."
  }
}

HTTP/1.1 200 OK
Content-Type: application/hacp+json
HACP-Version: 0.1

{
  "receipt": {
    "id": "rcpt_01J8Z6P4QS",
    "verdict": "ALLOW",
    "actionDigest": "sha256:4ca9...",
    "mandateRef": "mandate_01J8Z6M2Q4",
    "reasonCodes": ["DECISION_ATTESTATION_VALID", "AGENT_IDENTITY_BOUND", "MANDATE_CHAIN_VALID", "WITHIN_SCOPE"],
    "policyVersion": "air-api/hacp-policy@3",
    "evaluatedAt": "2026-09-12T18:43:09.000Z",
    "proof": {
      "type": "Ed25519Signature2020",
      "verificationMethod": "did:web:api.example-air.com:hacp#receipt-1",
      "createdAt": "2026-09-12T18:43:09.000Z",
      "proofValue": "z5Rcpt..."
    }
  }
}

The receiver MUST bind an independently authenticated caller to ActionEnvelope.agent and consume the action nonce atomically. Responses contain a signed Receipt: HTTP 200 for ALLOW, 202 for REVIEW, and 403 for DENY.

8.3Production storage

The included in-memory stores are development utilities. Production deployments require durable object resolution, atomic shared nonce storage, live revocation checks, and protected signing keys.

12.1Threats and mitigations

12.2Privacy

A verifier SHOULD receive only the claims required by its policy. Raw conversations, model reasoning, unrelated participants, and unneeded personal data remain outside the protocol exchange. Evidence references SHOULD support digest-only or selective-disclosure modes.

12.3Revocation and availability

High-risk operations SHOULD fail closed when fresh revocation status cannot be obtained. Lower-risk profiles may accept a stapled status proof within a declared freshness window. Revocation changes future authority; it does not rewrite historical receipts.

12.4Audit retention

Receivers SHOULD retain action digests, relevant Mandate chains, verdicts, reason codes, policy versions, and timestamps for the applicable audit period. Logs MUST exclude credentials and SHOULD avoid raw source communication.