LoopsHuman Loop Protocol

An SDK and protocol for wrapping existing agent harnesses with accountable human interaction.

Version 0.2.0-draft

The missing protocol surface is not tools or agents. It is accountability.

HLP defines how a human principal delegates bounded work to autonomous agent harnesses, pauses execution for decisions, reviews artifacts, and replays the entire lifecycle through audit.

DefinesTask ownership, checkpoints, reviews, artifacts, ledger, audit

Routes toExisting harnesses, A2A, ACP, AGNTCY, MCP, Agent Skills, local tools

Does not replaceAgent harnesses, tool protocols, transports, RBAC, UI channels

Understand HLPRead the positioning, object model, and why human-loop work needs its own protocol.Implement HLPUse the complete HLP specification for tasks, checkpoints, reviews, artifacts, ledger, and audit.Wrap harnessesMap HLP task identity, checkpoints, and harness events into existing harnesses.Use the SDKStart from the HLP host, then wire the harness adapters your platform already uses.

TaskCheckpointOwnershipReviewArtifactLedgerAudit

Integration model

HLP owns human interaction semantics. Existing harnesses keep execution.

Human Loop Protocol integration diagram: HLP above existing agent and capability protocol routes.

L1 and L0 pages are integration routes. They explain how HLP preserves task identity, checkpoint control, harness event projection, and capability provenance without defining another agent or tool protocol.

L2HLPThe only full protocol defined by this project: human-owned tasks, checkpoints, reviews, artifacts, ledger, and audit.
L1Agent routesIntroductory routing guidance for A2A, AGNTCY-style meshes, ACP-style brokers, and existing agent harnesses.
L0Capability routesIntroductory routing guidance for MCP, Agent Skills, local tools, and function-calling registries.

What HLP standardizes

Human-agent work units with stable task identity.
Decision checkpoints that pause agent work until a human resolves them.
Reviewable artifacts with immutable versions and provenance.
Audit trails that can replay every protocol operation.
Harness adapter contracts that keep implementation details from crossing boundaries.

What HLP does not replace

MCP servers and Skills runtimes remain the natural L0 implementations.
A2A, ACP, and agent meshes remain natural L1 implementations.
Host platforms still choose transport, persistence, identity, RBAC, and UI.
Agent harnesses remain free to choose models, prompts, tools, memory, and execution loops.

SDK surface

Applications embed HLP as an SDK, not as an execution harness.

Public entry pointloops and loops.hlp expose HLP protocol objects, HLPClient, HLPHost, stores, events, and adapters.

Runtime boundaryAgentAdapter controls external harnesses; HarnessAdapter projects their human-facing events into HLP.

SDK boundaryLoops does not ship a built-in agent harness. Execution belongs to the harness you wrap.

from loops import ArtifactPayload, CheckpointOptionfrom loops import CodexCLIAdapter, HLPHosthost = HLPHost.in_memory(adapter=CodexCLIAdapter())client = host.clienttask = await client.create_task( principal="user_alice", goal="Review PR #1234",)run = await client.delegate(task.id, "agent_codex")await client.start(task.id)checkpoint = await client.raise_checkpoint( task_id=task.id, kind="choice", prompt="Ship the patch?", options=(CheckpointOption(id="safe", label="Review first"),), raised_by=run.agent_id,)await client.resolve_checkpoint( checkpoint.id, by="user_alice", action="choose", choice="safe")artifact = await client.commit_artifact( task_id=task.id, type="report", payload=ArtifactPayload( kind="inline", uri="mem://report-v1", checksum="sha256:report-v1" ), produced_by=run.agent_id,)review = await client.submit_review( task_id=task.id, artifact_id=artifact.id, reviewer="user_alice", verdict="approved",)await client.write_ledger("project:web", "pr.1234", review.verdict, by=task.id)audit = await client.replay_audit(task.id)

First-class adapters

Four agent CLIs share one harness projection pipeline.

Codex, Pi, Claude Code, and Kimi wrap into HLP with the same JSONL projection of human-loop events, reliable peek/ack event delivery, and chat/protocol prompt modes — covered by offline contract suites and an opt-in live four-CLI lifecycle E2E.

CLI	Delegate adapter	Harness adapter (projection + peek/ack)	Wire mode
Codex	`CodexCLIAdapter`	`CodexHarnessAdapter`	`codex exec --json`
Pi	—	`PiHarnessAdapter`	`pi --mode json`
Claude Code	`ClaudeCodeCLIAdapter`	`ClaudeCodeHarnessAdapter`	`claude -p --output-format stream-json`
Kimi	`KimiCLIAdapter`	`KimiHarnessAdapter`	`kimi -p --output-format stream-json`

Sensor input such as brain-computer interfaces (BCI) is compatible by design (spec appendix C): a decoder is only a channel-plane producer of ControlSignal values, high-risk checkpoints cannot close on BCI alone (fail-closed, second factor supported), and the offline loops-hlp-bci-demo proves it — zero protocol changes.

Boundary rules

Four contracts keep the stack replaceable.

External evidenceCapability evidence is optional, opaque, and never transport.TaskID correlationThe HLP task id survives every delegated agent run.Checkpoint to blockHuman decisions pause and resume the corresponding run.Harness event projectionApproval, input, and artifact events become HLP objects.Ownership to handoffResponsibility changes preserve execution correlation.

Start with the human loop

Platforms that need accountable harness-backed human-agent work should embed HLP directly. Agent harnesses and capability providers stay on their existing protocols; HLP only requires narrow adapter contracts at the boundary.

Read the HLP spec or view the integration map.