Human-Agent Control Protocol

Cards are the interface. Control is the protocol.

Draft 0.4

HACP is the semantic protocol behind Control Decks. It lets a human play explicit commands that bind to material, pass one Working Object, combine with other cards, and govern agent behavior without rewriting the same instructions.

One payload, then explicit cards

The HACP plugin loads one compact protocol payload when a session starts. It does not play a card and does not change ordinary conversation. Cards remain explicit human commands:

$deck-a:prepare
→ $deck-b:inspect
+ $deck-c:present

The agent preflights the complete stream, resolves it in written order, and returns the smallest useful final result. + denotes a presentation of the same semantic object; → passes the object into another operation.

The shared envelope

Binding + Working Object + Active Controls

• Binding says what a card acts on.
• Working Object carries the current kind, content, status, annotations, and provenance.
• Active Controls govern effects and tool calls before they occur.

Annotations carry their own Binding and provenance. They can travel with a derived result without pretending that the derived result was itself checked. Presentations render an object without replacing what a later operation receives.

Install the session adapter

Install HACP once, then install any compatible decks you want to use.

Codex

codex plugin marketplace add control-decks/human-agent-control-protocol
codex plugin add hacp@hacp

Codex requires explicit trust for non-managed plugin hooks. Review the HACP hook when prompted, or use /hooks where that command is available. A skipped hook means the session must not claim HACP conformance.

Invoke $hacp:protocol directly to explain or audit HACP. The session hook loads the same skill body automatically; it does not maintain separate rules. On delegation, SubagentStart reloads that payload while the parent passes the current object and active controls in the delegated task.

Claude Code

claude plugin marketplace add control-decks/human-agent-control-protocol --scope user
claude plugin install hacp@hacp --scope user

Invoke /hacp:protocol directly to explain or audit HACP.

Authoring cards

The plugin also exposes two human-only authoring cards:

Card	Result
HACP AUTHOR CARD	One complete hacp/card-definition
HACP AUTHOR DECK	One complete hacp/deck-definition

Both accept an optional semantic target such as a URL, path, name, slug, manifest, or available Working Object. With no target they author a new artifact. Invocation alone never grants permission to modify files.

What makes a deck compatible

A deck is a namespace, distribution unit, and coherent set of standalone cards. It does not carry its own resolver. Each card declares one effect, Binding, structural inputs, semantic preconditions, output, duration, and limits. Provider metadata prevents the agent from invoking cards itself.

The normative HACP Draft 0.4 specification defines the complete contract. hacp.deck.json exposes machine-readable card identities and interfaces.

First-party decks

• Think It Through develops thought.
• Work This Way sets visible session controls and acts.
• Reality Check adds scoped verification annotations.

Real cross-deck recipes live in deck documentation and the Control Decks profile. They are examples, not protocol dependencies.

Boundaries

HACP defines observable behavior. Its adapter is not a sandbox, permission system, parser, runtime, database, or transport. A conforming agent must honor controls, but HACP cannot prevent a broken or hostile implementation from ignoring them.

Feedback

Open a GitHub issue when a real card flow exposes an ambiguous rule or missing invariant.

License

MIT