UHP specification: version 2026-09-12

Current protocol version

The official repository currently publishes 2026-09-12. UHP versions are dates, not semantic versions. A client may send a UHP-Version request header; the server returns the version actually used on every response.

If a client requests an unsupported version, the server is required to fail explicitly rather than silently substituting another protocol version.

Version 2026-09-12 is additive to 2026-08-11. Existing harnesses remain valid: direct mcpServers and skills keep their previous shape and meaning, while the new optional plugins surface is capability-gated.

Normative chapters

Chapter	What it defines
Architecture	Roles, conformance classes, object model, HTTP transport and authentication.
Lifecycle	Version negotiation, capability discovery, task states and session lifecycle.
Harnesses	Discovery and management of configured harness objects.
Plugins	Agent Plugins packages installed into a harness, derived components, export and package-file retrieval.
Tasks	Task submission, inputs, results, status, reserved request fields and continuation semantics.
Streaming	SSE event delivery, ordering and replay behavior.
Sessions	Listing, inspection, continuity, deletion and sharing at applicable classes.
Files	Input files, output artifacts, download behavior and container boundaries.
Errors	Machine-readable error envelope and codes.
Security	Threat boundaries and required protective behavior, including plugin execution.
Schema	Relationship to generated OpenAPI and JSON Schema definitions.

Harness Plugins is the new 2026-09-12 surface

UHP now defines an optional Harness Plugins sub-protocol. A UHP plugin is an Agent Plugins 1.0.0 package; UHP does not create another package format. The package contains plugin.json, optional mcp.json, and optional Agent Skills under skills/.

UHP defines how that package travels over the protocol, binds to a harness, becomes effective configuration, is retrieved, and can be exported again. The server derives manifest, mcpServers, skills and skipped from the package rather than treating those client-visible fields as independent configuration.

The new capability vocabulary includes plugins and plugin_schemas. Five new errors distinguish invalid packages, unsupported Agent Plugins schemas/transports, name conflicts and missing plugins. Plugin-contained MCP servers can use stdio, because the plugin supplies the filesystem root and data boundary that a hosted process requires.

Read the dedicated Harness Plugins guide for the composition, export and security boundaries.

Capability discovery first

The discovery endpoint is GET /v1/uhp. It reports supported protocol versions, the default version, conformance class, named capability booleans and optionally implementation identity. Clients should treat missing capability keys as unsupported.

For Harness Plugins, a server advertises plugins and supported plugin_schemas. A server that does not implement plugins can still conform to 2026-09-12; the plugin-specific checks are capability-gated and skip rather than pass.

Reserved Responses-compatible fields remain explicit

The protocol continues to define tools and include as reserved request fields. They remain accepted for Responses-wire compatibility, but a UHP server does not act on them. When a request carries either field, the response MUST name it in metadata.ignored_fields; a server MUST NOT reject the request merely because it carries one of these reserved fields.

That distinction is intentional. UHP puts tool invocation and tool results in the harness-owned output stream, so the client-side tool-return loop implied by the OpenAI Responses tools field does not exist in UHP. Treating tools as per-request MCP configuration would also widen execution authority from the configured harness owner to any API caller. The general rule remains: narrowing is safe, widening is escalation.

This behavior originated as an additive clarification in the 2026-08-11 line and is carried forward unchanged into 2026-09-12.

Session sharing and deletion carry forward

The current version retains the concrete interoperable sharing surface established in the prior version: POST/GET/DELETE /v1/sessions/{session_id}/share, a returned share url, bodyless publication, revocation of minted links and structured turn items.

The protocol-named session deletion path remains:

DELETE /v1/sessions/{session_id}

The server MUST cancel any in-flight task in that session first, delete the stored transcript/trace/working-folder state, stop the deleted state counting toward enforced storage or memory allowances, return a 2xx, and make a later GET /v1/sessions/{session_id} return 404. Deletion also invalidates any published shared view.

The older DELETE /v1/traces/{session_id} may remain as a compatibility alias, but /v1/sessions/{session_id} is the protocol-named path clients SHOULD use.

Conformance advances with the protocol

The official conformance package is now 2026.9.12 with 74 checks:

Class	Checks
Core	40
Extended	+8
Full	+25
Full total	74

The ten new Full-class P-01 through P-10 checks cover plugin package round trips, derivation, refusals and export. They are capability-gated. The checked-in HarnessRouter reference record remains the earlier 4 September 64/64 live run; PR #165 explicitly says the Community Edition gateway at merge time still serves 2026-08-11 and reports no plugins capability. Do not convert that older measurement into a 74/74 claim.

Task states

in_progress
   ├── completed
   ├── failed
   ├── incomplete   (budget/time/step limit)
   └── cancelled

The terminal states are deliberately distinct. An incomplete task is not the same as a failed task, and a cancellation requested by the client should not be reported as a failure. Partial output is retained when a task terminates.

Machine-readable artifacts

The repository contains OpenAPI 3.1 and JSON Schema 2020-12 outputs generated from the protocol source. For implementers, these files reduce ambiguity around object shapes, but they do not replace behavioral conformance testing.

The 2026-09-12 OpenAPI/schema surface includes plugin objects, plugin capability discovery, plugin-specific errors, package-file retrieval and harness export.

Implementation advice

• Implement discovery and version handling before product-specific convenience APIs.
• Keep server-internal execution mechanisms out of the wire model.
• Do not use tools or include as implementation-defined capability grants; report them as ignored when carried.
• Configure direct MCP servers and skills on the harness object rather than widening a task at request time.
• Treat Harness Plugins as optional and advertise plugins truthfully; do not claim plugin conformance by returning a field without implementing package semantics.
• Preserve the distinction between direct harness components and plugin-derived components so read/modify/write does not duplicate configuration.
• Use DELETE /v1/sessions/{session_id} for portable session deletion; treat /v1/traces/{session_id} only as a compatibility alias where a server exposes it.
• For Full session sharing, implement the named /share POST/GET/DELETE surface and return the share url; bodyless POST must work even if an enabled compatibility body is also accepted.
• Test streaming progressively; an SSE response that buffers until completion defeats the contract.
• Preserve stable object scoping and distinguish authorization failures without leaking object existence.
• Run the official conformance suite against a live server, not only schema tests.

Primary sources

• UHP current protocol README
• UHP 2026-09-12 specification directory
• UHP 2026-09-12 Plugins chapter
• PR #165 — UHP 2026-09-12 Harness Plugins sub-protocol
• Current conformance suite
• Conformance package 2026.9.12
• Agent Plugins 1.0.0 specification
• PR #60 — protocol-named session deletion and F-08
• PR #53 — session-sharing source/schema clarification
• PR #55 — R-08 bodyless share-publication check
• PR #46 — reserved tools and include semantics
• Generated UHP schema artifacts