HACP: A Capability-Contract Protocol for AI Agents and Edge Hardware

Status of This Memo

This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.¶

Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at https://datatracker.ietf.org/drafts/current/.¶

Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."¶

This Internet-Draft will expire on 2 November 2026.¶

Copyright Notice

Copyright (c) 2026 IETF Trust and the persons identified as the document authors. All rights reserved.¶

This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License.¶

Table of Contents

1. Introduction

LLM-based agents are increasingly asked to operate on physical hardware: read sensors, set GPIO lines, query system telemetry, manage files. Today, each agent framework reinvents this surface, often by shelling out to operating-system primitives. The result is fragile, unauditable, non-portable, and hard to secure.¶

HACP defines a small, stable JSON-RPC 2.0 protocol that an agent or an agent-side framework speaks to a host-side daemon. The daemon owns the hardware, enforces security policy, and emits an audit trail. The agent owns the intent, the planning, and the natural-language surface.¶

Goals:¶

1. Capability contract, not a driver API. HACP describes what an agent may ask for (read this GPIO, list I2C buses, write this file under a safe path). It does not describe how the daemon talks to silicon.¶

2. Safe by construction. Every operation passes through an allowlist, a path guard, a per-tool risk level, and an audit log. Agents cannot escape into a shell.¶

3. Plannable, not just callable. A request expresses an intent and an ordered list of steps; the server executes them as a single task with one task identifier, one status, and one audit trail.¶

4. Transport-neutral. The wire encoding is JSON-RPC 2.0 framed by line-delimited JSON; the carrier may be a Unix domain socket, a TCP socket over mutual TLS, an SSH stream, or a WebSocket.¶

5. Portable across edge boards. A capability name (e.g. "gpio.set", "hw.i2c.list", "sys.thermal") means the same thing on different physical platforms.¶

6. Forward-compatible. New methods, new tools, and new fields can be added without breaking existing clients.¶

Non-goals: HACP does not prescribe an agent SDK shape, a hardware description schema, a deployment manifest format, or an internal bus between daemons. Those are the subject of separate companion specifications outside this document's scope.¶

2. Wire format

{ "jsonrpc": "2.0", "id": 7, "method": "tool.list",
  "params": { "session_id": "..." } }

{ "jsonrpc": "2.0", "id": 7, "result": { ... } }

{ "jsonrpc": "2.0", "id": 7,
  "error": { "code": -32602, "message": "Invalid params" } }

3. Core methods

The following methods make up the HACP Core and MUST be implemented by every conformant server.¶

Optional method namespaces:¶

{
  "session_id": "01J9...XYZ",
  "capabilities": ["CAP_GPIO_RW", "CAP_FILE_READ"],
  "protocol_version": "0.1.0"
}

{
  "tools": [
    {
      "name": "gpio.set",
      "version": 1,
      "risk_level": 2,
      "timeout_ms": 1000,
      "supports_rollback": true,
      "description": "Set a GPIO line to 0 or 1.",
      "params_schema": { "type": "object" }
    }
  ]
}

{
  "session_id": "...",
  "task": {
    "intent": "Read sensor and toggle status LED",
    "steps": [
      { "tool": "i2c.read",
        "args": { "bus": 1, "addr": "0x48", "reg": "0x00", "len": 2 } },
      { "tool": "gpio.set",
        "args": { "line": 17, "value": 1 } }
    ],
    "constraints": {
      "max_duration_ms": 5000,
      "abort_on_step_failure": true,
      "max_risk_level": 2
    }
  }
}

{ "task_id": "01J9...ABC", "status": "QUEUED" }

{
  "task_id": "01J9...ABC",
  "status": "SUCCESS",
  "intent": "...",
  "steps": [
    { "tool": "i2c.read", "status": "SUCCESS",
      "result": { "data": "ABcd" }, "latency_ms": 4 },
    { "tool": "gpio.set", "status": "SUCCESS",
      "result": { "line": 17, "value": 1 }, "latency_ms": 1 }
  ]
}

4. Capability namespaces (informative)

Tool names are dot-separated. The first segment is a namespace; the rest is implementation-defined. The following namespaces are reserved by this specification:¶

Vendors SHOULD prefix custom namespaces with their reverse-DNS, for example com.acme.modbus.read, to avoid collisions.¶

5. Lifecycle

A session begins with session.open and ends with session.close or an idle timeout. While a session is active, an agent MAY submit any number of tasks. Each task progresses through:¶

QUEUED -> RUNNING -> { SUCCESS | FAILED | CANCELLED }

Idle sessions SHOULD be reaped after a server-defined time-to-live (default 300 seconds); reaping MUST run session.close semantics, including cancelling any in-flight tasks.¶

A server MUST reject any post-close request that uses the closed session identifier with RPC_SESSION_INVALID.¶

6. Error model

HACP reuses the JSON-RPC 2.0 standard codes:¶

Plus HACP-specific codes (range -32099 to -32000):¶

Implementations MAY add codes in -32099 to -32005. They MUST NOT re-use the codes above with different meaning.¶

The optional error.data field MAY carry a structured detail object:¶

{ "code": -32003, "message": "Permission denied",
  "data": { "tool": "gpio.set",
            "reason": "max_risk_level=1 < tool=2" } }

7. Audit semantics

Every accepted task.submit, every step start, every step finish, and every session.open and session.close MUST generate an audit event.¶

The recommended event shape is illustrative; a full audit log format is the subject of a separate companion document:¶

{
  "ts":         "2026-04-19T22:48:01.234Z",
  "event":      "task.step.finish",
  "session_id": "...",
  "task_id":    "...",
  "step_index": 0,
  "tool":       "gpio.set",
  "status":     "SUCCESS",
  "latency_ms": 1,
  "args_hash":  "sha256:..."
}

Audit logs SHOULD be append-only and rotation-friendly (newline- delimited JSON). Implementations MAY chain consecutive records cryptographically (for example, by including the SHA-256 hash of the previous record in the next record) to provide tamper evidence.¶

8. Streaming extension (optional)

The polling pattern (task.submit followed by repeated task.get) is sufficient but verbose. A server MAY advertise the CAP_STREAMING_TASK_EVENTS capability in session.open. If present, clients MAY call:¶

{ "method": "task.events.subscribe",
  "params": { "session_id": "...", "task_id": "..." } }

The server then sends one or more notifications (JSON-RPC objects with no id):¶

{ "jsonrpc": "2.0", "method": "task.event",
  "params": { "task_id": "...", "step_index": 0,
              "phase": "start",
              "ts": "2026-04-19T22:48:01.234Z" } }

Phases: start, progress, finish, task_finish. The subscription ends implicitly when the task reaches a terminal status.¶

9. Versioning

The protocol uses Semantic Versioning [SEMVER] as MAJOR.MINOR.PATCH:¶

• PATCH: clarifications and editorial fixes only.¶

• MINOR: additive — new methods, fields, or error codes. Older clients still work.¶

• MAJOR: breaking. Servers MAY support multiple majors side by side via protocol_version in session.open.¶

Servers MUST advertise their highest supported version in the session.open result.¶

10. Transport bindings

11. Future Considerations

Future revisions of this specification may explore:¶

• Remote operation across network boundaries with stronger authentication and confidentiality requirements.¶

• Mutual authentication and authorization between agents and capability providers based on hardware identities.¶

• Hardware-backed attestation of capability providers (for example, via TPM 2.0 quotes binding the running daemon binary, the kernel, and the device identity to a client-supplied nonce).¶

• Catalog versioning and capability negotiation evolution as the agent ecosystem matures.¶

The detailed mechanisms are out of scope for this document.¶

12. Security Considerations

HACP exposes physical hardware to programs that act on behalf of LLMs. This is inherently security-sensitive.¶

A conformant server MUST:¶

1. Allowlist tools at startup. The set of registered tools is fixed per process; agents cannot install new tools at runtime over HACP.¶

2. Path-guard every filesystem operation. file.* and any tool that accepts a path MUST consult a configured read/write allowlist; reject with RPC_PERMISSION_DENIED on miss.¶

3. Enforce per-tool risk caps. A session MUST NOT execute a tool whose risk_level exceeds the session's configured maximum.¶

4. Audit every accepted task (Section 7).¶

5. Bound resource use. Server MUST reject task.submit when internal queues are full.¶

A conformant server SHOULD:¶

• Run as an unprivileged user, joining only the groups required for the buses it exposes.¶

• Apply rate limits per (session_id, tool) pair.¶

• Apply per-tool timeouts.¶

• Drop privileges and apply syscall filtering before serving.¶

Servers MUST NOT expose a proc.exec-style escape hatch in the default tool set. Operators that need shell access MUST opt in explicitly and MUST flag such tools as risk_level: 3.¶

The default Unix Domain Socket transport relies on filesystem permissions for authentication. Operators deploying HACP over network transports MUST apply mutual TLS or an equivalent authentication mechanism, as the JSON-RPC envelope itself carries no confidentiality or integrity protection.¶

The audit log is the primary mechanism for detecting and investigating abuse. Operators SHOULD store audit logs on append-only media or use cryptographic chaining (Section 7) to detect tampering after the fact.¶

A malicious or compromised agent that gains a HACP session is limited by the configured tool allowlist, risk cap, and path guard. HACP does not protect against an attacker who can reconfigure the server itself (for example, by editing its configuration file as root); operators are expected to apply standard host hardening to the server's runtime environment.¶

13. Privacy Considerations

The audit log records the full sequence of operations performed on behalf of an agent, including a hash of arguments. Operators SHOULD treat audit logs as sensitive: they may incidentally correlate hardware events with user activity (for example, motion sensor reads taken at specific times). Standard log retention, access control, and minimization practices apply.¶

HACP itself does not transmit personally identifiable information as part of the protocol envelope. Implementations that expose tools returning personal data (for example, a microphone capture tool) MUST classify those tools at an appropriate risk_level and SHOULD require explicit operator opt-in.¶

14. IANA Considerations

This document has no IANA actions.¶

A future revision may register a media type for line-delimited HACP framing and a default port number for the optional TCP transport. No registrations are requested at this time.¶

15. Implementation Status

A reference implementation, the HEARTH project [HEARTH], includes a server (hearthd, written in C) and an agent client (ai-shell). The reference implementation covers all six core methods, the audit log format, the Unix Domain Socket transport, and the MCP bridge. Streaming task events and attestation are partial.¶

This section is intended to be removed by the RFC Editor before publication.¶

16. References

Appendix A. Acknowledgments

The author thanks the early reviewers and contributors of the HEARTH project for their feedback on the protocol surface, and the broader LLM agent community whose function-calling conventions informed the design of the task.submit shape.¶

Author's Address