Skip to content

HarnessRouter Community Edition: the self-hosted, Apache-2.0 edition of the unified interface for agent harnesses. Run Codex, Claude Code, Hermes, PI, DSH, and more through one API, with sessions, streaming, files, cancellation, and failure handling. Implements the Unified Harness Protocol (UHP), an open standard. Your keys, your infrastructure.

tasks: `tools` and `include` are reserved and ignored, and ignoring is now observable (#42)

Hashem Aldhaheri58603a8927a0
diff --git a/gateway/app.py b/gateway/app.py
index 22ff1d1e..086705de 100644
--- a/gateway/app.py
+++ b/gateway/app.py
@@ -4035,9 +4035,15 @@ class _RespTranslator:
usage so the non-streaming path and the stored record reuse the same assembly. sequence_number
is monotonic across the whole stream; each output item gets its own increasing output_index."""
- def __init__(self, resp_id: str, model: str, prev: str | None, store: bool, created_at: float, sid: str = ""):
+ def __init__(self, resp_id: str, model: str, prev: str | None, store: bool, created_at: float,
+ sid: str = "", ignored: list[str] | None = None):
self.resp_id, self.model, self.prev, self.store, self.created_at = resp_id, model, prev, store, created_at
self.sid = sid # surfaced in response.metadata so the client can highlight/track the session
+ # Request fields we accepted and did not act on (tasks.md 1.1). `tools` and `include` are
+ # reserved and ignored (1.4), and ignoring has to be observable: a silently dropped field
+ # is indistinguishable from an honoured one, which is the same reasoning that puts model
+ # substitution in metadata.
+ self.ignored: list[str] = list(ignored or [])
# run metadata (CT-124): the model the caller asked for, and whether the gateway substituted
# the harness's authorized default because the request was unavailable for this backend.
self.requested_model = ""
@@ -4068,6 +4074,8 @@ class _RespTranslator:
meta["model_fallback"] = True
if self.fallback_reason:
meta["model_fallback_reason"] = self.fallback_reason
+ if self.ignored:
+ meta["ignored_fields"] = self.ignored
return {"id": self.resp_id, "object": "response", "created_at": int(self.created_at),
"status": status, "error": self.error, "incomplete_details": None,
"previous_response_id": self.prev, "model": self.model,
@@ -5982,7 +5990,9 @@ async def create_response(body: CreateResponseBody, request: Request):
try:
# remember this turn's response id on the trace + session so a loaded session can resume
_session_trace.setdefault(sid, {}).update(last_response_id=resp_id)
- tr = _RespTranslator(resp_id, model_req or body.model or backend, body.previous_response_id, body.store, created_at, sid=sid)
+ # Reserved fields, named on the response rather than dropped in silence (tasks.md 1.4).
+ _ignored = [f for f in ("tools", "include") if getattr(body, f, None) is not None]
+ tr = _RespTranslator(resp_id, model_req or body.model or backend, body.previous_response_id, body.store, created_at, sid=sid, ignored=_ignored)
tr.requested_model, tr.model_fallback, tr.fallback_reason = requested_model, model_fallback, model_fallback_reason
# Broadcast a synthetic turn-start so the bus alone can render a conversation turn from
diff --git a/gateway/tests/test_ignored_fields.py b/gateway/tests/test_ignored_fields.py
new file mode 100644
index 00000000..81beb726
--- /dev/null
+++ b/gateway/tests/test_ignored_fields.py
@@ -0,0 +1,66 @@
+"""A field the gateway did not act on is named on the response.
+
+Tasks §1.4 makes `tools` and `include` reserved: accepted, never acted on. §1.1 makes ignoring
+observable — the response MUST name them in `metadata.ignored_fields`. The gateway already did the
+first half (it reads `tools` only for the idempotency hash and never for routing or execution) and
+none of the second, so a client sending either field got a response indistinguishable from one
+where the field had been honoured.
+
+These test the metadata at the source, so the invariant holds without a live turn, and they check
+both directions: a field that was sent is reported, and a field that was not sent is not.
+"""
+from __future__ import annotations
+
+import json
+import os
+import sys
+
+import jsonschema
+
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+_ROOT = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+_SCHEMA = os.path.join(_ROOT, "protocol", "schema", "uhp-2026-08-11.schema.json")
+
+
+def _response_schema() -> dict:
+ s = json.load(open(_SCHEMA))
+ return {"$defs": s["$defs"], **s["$defs"]["Response"]}
+
+
+def _translator(**kw):
+ from app import _RespTranslator
+ return _RespTranslator("resp_test", "some-model", None, True, 0.0, **kw)
+
+
+def test_a_reserved_field_that_was_sent_is_reported():
+ tr = _translator(ignored=["tools", "include"])
+ meta = tr._response_obj("completed")["metadata"]
+ assert meta["ignored_fields"] == ["tools", "include"]
+
+
+def test_a_request_that_sent_neither_is_not_told_one_was_ignored():
+ """The opposite mistake, and just as misleading: a hardcoded list tells a caller their request
+ was altered when it was not."""
+ meta = _translator()._response_obj("completed")["metadata"]
+ assert "ignored_fields" not in meta
+
+
+def test_only_the_fields_actually_sent_are_named():
+ meta = _translator(ignored=["include"])._response_obj("completed")["metadata"]
+ assert meta["ignored_fields"] == ["include"]
+
+
+def test_the_response_still_validates_against_the_spec():
+ tr = _translator(ignored=["tools", "include"])
+ jsonschema.validate(tr._response_obj("completed"), _response_schema())
+
+
+def test_the_selection_matches_what_the_request_carried():
+ """Mirrors the expression in the /v1/responses path: a field is ignored when it is present,
+ and `None` means the client did not send it."""
+ class Body:
+ tools = [{"type": "function", "name": "x"}]
+ include = None
+
+ assert [f for f in ("tools", "include") if getattr(Body, f, None) is not None] == ["tools"]
diff --git a/protocol/CHANGELOG.md b/protocol/CHANGELOG.md
index afc851b5..a8f0bba5 100644
--- a/protocol/CHANGELOG.md
+++ b/protocol/CHANGELOG.md
@@ -2,6 +2,42 @@
All notable changes to the Unified Harness Protocol.
+## Unreleased — additive to 2026-08-11
+
+### Clarified
+
+- **`tools` and `include` are reserved and ignored** ([Tasks §1.4](versions/2026-08-11/tasks.md#14-reserved-fields-tools-and-include)).
+ Both arrived with the OpenAI Responses wire shape this version stays compatible with, and neither
+ ever had defined semantics in UHP. A server accepts them and does not act on them.
+
+ `tools` cannot mean what it means in the Responses API, where the *client* executes tools and
+ returns the result as input: UHP puts both the call and its result in `output`, so there is no
+ input path for the return leg and the loop the field implies cannot be completed. The other
+ plausible reading — per-request MCP servers — is already covered by
+ [Harnesses §4.1](versions/2026-08-11/harnesses.md#41-mcp-servers), and would be an escalation
+ primitive besides: it would let any caller point the agent at an endpoint of their choosing,
+ executed with the harness owner's credentials and workspace. The rule underneath, stated so it
+ can be applied again: **narrowing is safe, widening is escalation.**
+
+- **`metadata.ignored_fields` is specified** ([Tasks §1.1](versions/2026-08-11/tasks.md#11-request-fields)),
+ and required when a request carries a reserved field. Ignoring has to be observable, for the same
+ reason model substitution is reported in §1.3: a silently dropped field is indistinguishable from
+ an honoured one.
+
+- **GOVERNANCE.md records "a declined field is not a pending one"** — the general rule these two
+ fields are the worked example of. Due to @aenawi in
+ [#42](https://github.com/HarnessRouter/harnessrouter/issues/42).
+
+Nothing is removed and no client breaks: a request sending either field was already accepted and
+already had no effect. Removal is a question for the next version.
+
+### Conformance
+
+Three checks at class Core, in both directions, where the suite previously sent neither field:
+**T-08** a request carrying them is accepted, **T-09** they are reported in
+`metadata.ignored_fields`, **T-10** a request that sent neither is not told one was ignored. Core
+goes from 37 checks to 40.
+
## 2026-08-11 — first published version
The initial specification, extracted from the shipping HarnessRouter implementation rather than
diff --git a/protocol/GOVERNANCE.md b/protocol/GOVERNANCE.md
index e841dfb7..c4d13015 100644
--- a/protocol/GOVERNANCE.md
+++ b/protocol/GOVERNANCE.md
@@ -59,6 +59,37 @@ per [VERSIONING.md](VERSIONING.md), published with a migration note.
- **Implementers** — anyone shipping a UHP server or client. Implementer feedback outranks
theoretical elegance in every design argument.
+## A declined field is not a pending one
+
+An implementation may choose not to carry a field. That choice is a **decision**, and it should be
+recorded as one — not left on a list that reads as work nobody has got to yet.
+
+The distinction matters because the two look identical from outside. A field an implementation
+intends to support later and a field it has decided never to support both show up the same way: as
+something the request asked for and did not get. Left unstated, the second quietly becomes the
+first, and a question that was actually settled gets re-opened by every new reader, every new
+implementer, and every issue triage.
+
+So:
+
+- **Say which it is.** A declined field is closed. Say why, once, somewhere durable, and stop
+ carrying it as an open item.
+- **Declining is about implementation, never about validation.** [Tasks
+ §1.1](versions/2026-08-11/tasks.md#11-request-fields) requires ignore-don't-reject, so a declined
+ field is still accepted, and a request carrying it still runs.
+- **Tell the caller.** A field that was dropped is named in `metadata.ignored_fields`. A silently
+ ignored field is indistinguishable from an honoured one, and the caller cannot tell which they
+ got. This is the same principle as reporting model substitution in [Tasks
+ §1.3](versions/2026-08-11/tasks.md#13-model-selection-and-substitution).
+
+This applies to the specification too, and `tools` and `include` are the worked example: rather than
+leaving them under-specified and letting each implementer guess, they are declared reserved and
+ignored in [Tasks §1.4](versions/2026-08-11/tasks.md#14-reserved-fields-tools-and-include), with the
+reason written down.
+
+The framing, and the phrase, are due to @aenawi in [#42](https://github.com/HarnessRouter/harnessrouter/issues/42),
+from ADR-0007 of an independent UHP implementation.
+
## Reporting problems
- **Specification bugs** — ambiguity, a rule that cannot be implemented, disagreement between the
diff --git a/protocol/conformance/README.md b/protocol/conformance/README.md
index 8eb89527..33a7d7c7 100644
--- a/protocol/conformance/README.md
+++ b/protocol/conformance/README.md
@@ -37,11 +37,11 @@ anything that only inspects a schema.
## What it checks
-59 checks across three classes.
+62 checks across three classes.
| Class | Checks | Covers |
|---|---|---|
-| **Core** | 37 | Discovery, version negotiation, authentication, the error envelope, harnesses, models, task execution (streaming and not), the event stream, sessions, cancellation |
+| **Core** | 40 | Discovery, version negotiation, authentication, the error envelope, harnesses, models, task execution (streaming and not), the event stream, sessions, cancellation, reserved request fields |
| **Extended** | +8 | Session listing and inspection, file input, artifacts, download headers, path-traversal probes |
| **Full** | +14 | Harness create / update / delete, refusal of an unsupported base, skill-folder round trip, MCP and disabled-tool persistence, session sharing |
@@ -64,6 +64,10 @@ A few of them are worth calling out, because they catch things a schema check ne
own origin.
- **X-08** — artifact ids do not traverse out of their container. Probes for `../` and its
percent-encoded form.
+- **T-08/T-09/T-10** — the reserved fields `tools` and `include` are accepted, and reported as
+ ignored. Both halves matter: before these, the suite sent neither field, so a server that
+ rejected them outright and a server that silently acted on them scored the same as a correct
+ one. T-10 covers the third mistake, a server that reports fields the request never sent.
- **R-01…R-07** — session sharing, which is mostly a set of refusals. Sessions §5 requires that a
shared view be read-only, revocable, and free of credentials, and a check that merely opens a
link and reads the conversation passes against a server that also lets that link continue the
@@ -113,14 +117,18 @@ a live instance on 2026-08-11:
CONFORMANT — UHP 2026-08-11 (full)
```
-That run predates the `R-` series, so it is a 52-check result. The R-series itself has been
-measured against the reference implementation directly: at the commit this note ships in,
-`R-01`…`R-07` all pass against a live self-hosted instance. Getting there took changes on both
-sides, which is the strongest argument this suite has for itself — against the reference as it
-stood, all seven checks skipped (its share dialect wanted `{"enabled": true}` and published no
-view URL), and behind those skips sat a real Sessions §6 violation: a session's share link kept
-serving the full conversation after `DELETE /v1/traces/{id}`, verified live before the fix. A
-suite that had shipped happy-path checks would have called that server conformant.
+That run predates the `T-` additions and the `R-` series, so it is a 52-check result. Both have
+since been measured against the reference implementation directly, live on a self-hosted
+instance, and both measured a real defect before passing:
+
+- `R-01`…`R-07` all pass. Against the reference as it stood, all seven skipped (its share
+ dialect wanted `{"enabled": true}` and published no view URL), and behind those skips sat a
+ real Sessions §6 violation: a session's share link kept serving the full conversation after
+ `DELETE /v1/traces/{id}`, verified live before the fix.
+- `T-08`–`T-10` pass, with `T-09` failing against the reference as it stood: `tools` fed the
+ idempotency hash and nothing reported it ignored — the silent drop §1.1 now forbids.
+
+A suite that had shipped happy-path checks would have called that server conformant both times.
The suite is developed against that implementation, which is exactly why the specification says
conformance is defined by the suite and not by the implementation: anything the reference does that
diff --git a/protocol/conformance/tests/reserved_field_stub.py b/protocol/conformance/tests/reserved_field_stub.py
new file mode 100644
index 00000000..6c9f06c6
--- /dev/null
+++ b/protocol/conformance/tests/reserved_field_stub.py
@@ -0,0 +1,102 @@
+"""A UHP server that gets the reserved-field rules wrong, one way at a time.
+
+Tasks §1.4 makes `tools` and `include` reserved, which is two requirements: accept them, and say
+you ignored them. Each has a distinct way of being broken, and a third way exists that looks like
+compliance — reporting fields the request never sent. This stub can do all three.
+
+ DEFECT=silent_ignore PORT=8941 python3 reserved_field_stub.py
+"""
+from __future__ import annotations
+
+import json
+import os
+import time
+import uuid
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from urllib.parse import urlsplit
+
+DEFECT = os.environ.get("DEFECT", "none")
+PORT = int(os.environ.get("PORT", "8941"))
+KEY = "stub-key"
+
+DEFECTS = {
+ "none",
+ "rejects_reserved", # 400s a request carrying `tools`, breaking ignore-don't-reject
+ "silent_ignore", # drops them and says nothing, so the client cannot tell
+ "partial_report", # reports `tools` but not `include`
+ "hardcoded_report", # always reports both, even when the request sent neither
+}
+assert DEFECT in DEFECTS, f"unknown defect {DEFECT!r}; one of {sorted(DEFECTS)}"
+
+RESERVED = ("tools", "include")
+
+
+class H(BaseHTTPRequestHandler):
+ protocol_version = "HTTP/1.1"
+
+ def log_message(self, *a):
+ pass
+
+ def send(self, status: int, payload=None):
+ body = b"" if payload is None else json.dumps(payload).encode()
+ self.send_response(status)
+ self.send_header("content-type", "application/json")
+ self.send_header("uhp-version", "2026-08-11")
+ self.send_header("content-length", str(len(body)))
+ self.end_headers()
+ if body:
+ self.wfile.write(body)
+
+ def do_GET(self):
+ p = [x for x in urlsplit(self.path).path.split("/") if x]
+ if p == ["v1", "uhp"]:
+ return self.send(200, {
+ "object": "uhp.discovery", "versions": ["2026-08-11"],
+ "default_version": "2026-08-11", "conformance_class": "core",
+ "capabilities": {"streaming": True, "sessions": True, "cancellation": True}})
+ if (self.headers.get("authorization") or "").removeprefix("Bearer ").strip() != KEY:
+ return self.send(401, {"error": {"code": "unauthorized", "message": "no credential"}})
+ if p == ["v1", "harnesses"]:
+ return self.send(200, {"harnesses": [{"id": "h1", "name": "stub", "base": "stub"}]})
+ return self.send(404, {"error": {"code": "not_found", "message": "no such endpoint"}})
+
+ def do_POST(self):
+ n = int(self.headers.get("content-length") or 0)
+ raw = self.rfile.read(n) if n else b"{}"
+ if (self.headers.get("authorization") or "").removeprefix("Bearer ").strip() != KEY:
+ return self.send(401, {"error": {"code": "unauthorized", "message": "no credential"}})
+ if [x for x in urlsplit(self.path).path.split("/") if x] != ["v1", "responses"]:
+ return self.send(404, {"error": {"code": "not_found", "message": "no such endpoint"}})
+
+ try:
+ body = json.loads(raw)
+ except Exception: # noqa: BLE001
+ body = {}
+ sent = [f for f in RESERVED if body.get(f) is not None]
+
+ if sent and DEFECT == "rejects_reserved":
+ return self.send(400, {"error": {"code": "invalid_request",
+ "message": "unsupported field: tools"}})
+
+ meta = {"session_id": f"sess_{uuid.uuid4().hex[:10]}", "harness_id": "h1"}
+ if DEFECT == "hardcoded_report":
+ meta["ignored_fields"] = list(RESERVED)
+ elif DEFECT == "partial_report":
+ if sent:
+ meta["ignored_fields"] = ["tools"]
+ elif DEFECT != "silent_ignore":
+ if sent:
+ meta["ignored_fields"] = sent
+
+ return self.send(200, {
+ "id": f"resp_{uuid.uuid4().hex[:10]}", "object": "response", "status": "completed",
+ "model": "stub-1", "usage": None, "created_at": int(time.time()),
+ "error": None, "incomplete_details": None, "previous_response_id": None, "store": True,
+ "output": [{"type": "message", "role": "assistant",
+ "content": [{"type": "output_text", "text": "ok"}]}],
+ "metadata": meta})
+
+
+if __name__ == "__main__":
+ print(f"stub: defect={DEFECT} port={PORT}", flush=True)
+ ThreadingHTTPServer(("127.0.0.1", PORT), H).serve_forever()
diff --git a/protocol/conformance/tests/test_reserved_fields.py b/protocol/conformance/tests/test_reserved_fields.py
new file mode 100644
index 00000000..be273c13
--- /dev/null
+++ b/protocol/conformance/tests/test_reserved_fields.py
@@ -0,0 +1,90 @@
+"""T-08/T-09/T-10 are shown to fail on servers that get §1.4 wrong.
+
+The suite sent neither `tools` nor `include` before this, so both directions of the reserved-field
+rule were unmeasured: a server that rejected them and a server that silently honoured them would
+each have scored the same as a correct one. These tests pin all three ways it can go wrong —
+rejecting, ignoring in silence, and reporting fields the request never sent.
+"""
+from __future__ import annotations
+
+import pathlib
+import socket
+import subprocess
+import sys
+import time
+import urllib.error
+import urllib.request
+
+import pytest
+
+from uhp_conformance import checks # noqa: F401 — importing populates the registry
+from uhp_conformance.client import Client
+from uhp_conformance.context import Context
+from uhp_conformance.registry import REGISTRY, Outcome
+
+STUB = pathlib.Path(__file__).parent / "reserved_field_stub.py"
+IDS = ("T-08", "T-09", "T-10")
+
+CAUGHT_BY = {
+ "rejects_reserved": "T-08",
+ "silent_ignore": "T-09",
+ "partial_report": "T-09",
+ "hardcoded_report": "T-10",
+}
+
+
+def _free_port() -> int:
+ with socket.socket() as s:
+ s.bind(("127.0.0.1", 0))
+ return s.getsockname()[1]
+
+
+def _run(defect: str) -> dict[str, Outcome]:
+ port = _free_port()
+ srv = subprocess.Popen([sys.executable, str(STUB)],
+ env={"DEFECT": defect, "PORT": str(port), "PATH": "/usr/bin:/bin"},
+ stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
+ try:
+ deadline = time.time() + 10
+ while time.time() < deadline:
+ try:
+ urllib.request.urlopen(f"http://127.0.0.1:{port}/v1/uhp", timeout=1).read()
+ break
+ except (urllib.error.URLError, OSError):
+ time.sleep(0.05)
+ else:
+ pytest.fail(f"the stub did not start for defect {defect!r}")
+ ctx = Context(client=Client(f"http://127.0.0.1:{port}", "stub-key"), task_timeout=30.0)
+ return {c.id: c.run(ctx).outcome for c in REGISTRY if c.id in IDS}
+ finally:
+ srv.terminate()
+ srv.wait(timeout=5)
+
+
+def test_the_checks_are_registered_at_core():
+ got = [c for c in REGISTRY if c.id in IDS]
+ assert [c.id for c in got] == list(IDS)
+ assert {c.cls for c in got} == {"core"}
+
+
+def test_a_conformant_server_passes_all_three():
+ assert all(o is Outcome.PASS for o in _run("none").values())
+
+
[email protected]("defect,expected", sorted(CAUGHT_BY.items()))
+def test_each_defect_is_caught_by_its_own_check(defect, expected):
+ out = _run(defect)
+ assert out[expected] is Outcome.FAIL, f"{defect!r} was not caught by {expected}: {out}"
+
+
+def test_rejecting_the_request_does_not_also_fail_the_reporting_check():
+ """A server that refuses the request never produced a response to report anything in, so
+ T-09 must skip rather than add a second red mark for one defect."""
+ out = _run("rejects_reserved")
+ assert out["T-08"] is Outcome.FAIL
+ assert out["T-09"] is Outcome.SKIP, out
+
+
+def test_no_check_errors_on_any_defect():
+ for defect in ["none", *CAUGHT_BY]:
+ assert Outcome.ERROR not in _run(defect).values(), defect
diff --git a/protocol/conformance/uhp_conformance/checks.py b/protocol/conformance/uhp_conformance/checks.py
index db3e32b2..77dafe32 100644
--- a/protocol/conformance/uhp_conformance/checks.py
+++ b/protocol/conformance/uhp_conformance/checks.py
@@ -828,6 +828,89 @@ def f02(ctx):
# ══════════════════════════════════════════════════════════════════════════════════════
+# Core — reserved request fields
+# ══════════════════════════════════════════════════════════════════════════════════════
+# `tools` and `include` are reserved and ignored (Tasks §1.4), which is two requirements and
+# not one. A server must accept a request carrying them, and it must say that it ignored them.
+# Both directions are currently unmeasured: no other check sends either field, so a server that
+# rejected them outright and a server that silently honoured them would both pass the suite.
+#
+# The second direction is the one with teeth. §1.1 requires ignoring to be observable for the
+# same reason §1.3 requires model substitution to be reported: a client that cannot tell a
+# dropped field from an honoured one has to assume the worst about every field it sends.
+
+def _run_with_reserved(ctx) -> dict:
+ """One task carrying both reserved fields, run once and cached."""
+ if "reserved" in ctx.state:
+ return ctx.state["reserved"]
+ h = _harness(ctx)
+ body = {"input": PROMPT, "metadata": {"harness_id": h["id"]}, "stream": False,
+ # Deliberately plausible under both readings of `tools` that implementers have
+ # reached for, so a server that quietly acts on either is exercised rather than
+ # merely handed something it can dismiss as malformed.
+ "tools": [{"type": "function", "name": "uhp_conformance_probe",
+ "description": "Must never be offered to the agent.",
+ "parameters": {"type": "object", "properties": {}}},
+ {"name": "uhp-conformance-mcp", "url": "https://mcp.example.invalid/mcp",
+ "transport": "http"}],
+ "include": ["uhp.conformance.not_a_real_value"]}
+ if ctx.model:
+ body["model"] = ctx.model
+ r = ctx.client.post("/v1/responses", body=body)
+ ctx.state["reserved"] = r
+ return r
+
+
+@check("T-08", "A request carrying reserved fields is accepted, not rejected", "core",
+ f"{SPEC}/tasks.md#11-request-fields")
+def t08(ctx):
+ r = _run_with_reserved(ctx)
+ assert r.status == 200, (
+ f"a task sending `tools` and `include` returned HTTP {r.status}: {r.body[:200]!r}. §1.1 "
+ "requires a server to ignore rather than reject, and §1.4 makes both fields reserved — a "
+ "client that sends them for wire compatibility with another API must not be refused.")
+ d = r.json or {}
+ assert d.get("status") in {"completed", "incomplete"}, (
+ f"the task carrying reserved fields ended {d.get('status')!r}; accepting a request means "
+ "running it, not failing it later for the same reason")
+ return "accepted and ran"
+
+
+@check("T-09", "Reserved fields are reported in metadata.ignored_fields", "core",
+ f"{SPEC}/tasks.md#14-reserved-fields-tools-and-include")
+def t09(ctx):
+ r = _run_with_reserved(ctx)
+ if r.status != 200:
+ raise Skip("the request carrying reserved fields was not accepted (see T-08)")
+ meta = ((r.json or {}).get("metadata") or {})
+ got = meta.get("ignored_fields")
+ assert got is not None, (
+ "the response has no `metadata.ignored_fields` for a request that sent `tools` and "
+ "`include`. §1.1 requires ignoring to be observable: silently dropping a field is "
+ "indistinguishable from acting on it, and the client cannot tell which happened.")
+ assert isinstance(got, list) and all(isinstance(x, str) for x in got), (
+ f"metadata.ignored_fields is {type(got).__name__}, expected an array of field names")
+ missing = [f for f in ("tools", "include") if f not in got]
+ assert not missing, (
+ f"the request sent `tools` and `include`, and ignored_fields names {got} — missing "
+ f"{missing}. §1.4 makes both reserved, so both must be reported whenever they are sent.")
+ return f"ignored_fields={got}"
+
+
+@check("T-10", "A task that sends no reserved field is not told one was ignored", "core",
+ f"{SPEC}/tasks.md#11-request-fields")
+def t10(ctx):
+ """The other half of T-09. A server that hardcodes the list reports fields the client never
+ sent, which is a different lie in the same place: it tells a client its request was altered
+ when it was not."""
+ d = (_run_blocking(ctx).json or {})
+ got = ((d.get("metadata") or {}).get("ignored_fields")) or []
+ over = [f for f in ("tools", "include") if f in got]
+ assert not over, (
+ f"the response names {over} in ignored_fields for a request that sent neither. "
+ "ignored_fields reports what this request carried and the server dropped, not a "
+ "catalogue of what the server would drop.")
+
# Full — session sharing
# ══════════════════════════════════════════════════════════════════════════════════════
# Sessions §5 is the Full requirement this suite could not see, and it is the one where a
diff --git a/protocol/schema/uhp-2026-08-11.openapi.yaml b/protocol/schema/uhp-2026-08-11.openapi.yaml
index 4557766c..5c47ec14 100644
--- a/protocol/schema/uhp-2026-08-11.openapi.yaml
+++ b/protocol/schema/uhp-2026-08-11.openapi.yaml
@@ -750,8 +750,22 @@ components:
max_output_tokens: { type: [integer, 'null'] }
max_step: { type: [integer, 'null'], description: Agent step (tool-call round) budget }
timeout_seconds: { type: [integer, 'null'], description: Wall-clock budget }
- tools: { type: array, items: { type: object, additionalProperties: true } }
- include: { type: array, items: { type: string } }
+ tools:
+ type: array
+ items: { type: object, additionalProperties: true }
+ description: |
+ Reserved and ignored. Accepted for wire compatibility, never acted on, and reported in
+ `metadata.ignored_fields` on the response. A UHP harness invokes and executes tools
+ itself and reports them in `output`; there is no input path for a tool result, so the
+ client-executed tool loop this field implies cannot be completed by a conformant server.
+ Configure tools on the harness instead — see Harnesses §4.1. Tasks §1.4.
+ include:
+ type: array
+ items: { type: string }
+ description: |
+ Reserved and ignored. Accepted for wire compatibility, never acted on, and reported in
+ `metadata.ignored_fields` on the response. No values are enumerated, so any string a
+ server recognised would be one it named itself. Tasks §1.4.
background: { type: boolean, default: false }
additionalProperties: true
@@ -791,6 +805,13 @@ components:
description: Present when the server ran a different model than was requested.
model_fallback: { type: boolean }
model_fallback_reason: { type: string }
+ ignored_fields:
+ type: array
+ items: { type: string }
+ description: |
+ Request fields the server did not act on, by name, in any order. Required when the
+ request carried `tools` or `include`, which are reserved and ignored. A silently
+ ignored field is indistinguishable from an honoured one. Tasks §1.1 and §1.4.
additionalProperties: true
additionalProperties: true
diff --git a/protocol/schema/uhp-2026-08-11.schema.json b/protocol/schema/uhp-2026-08-11.schema.json
index 951dbc0f..f2592cf2 100644
--- a/protocol/schema/uhp-2026-08-11.schema.json
+++ b/protocol/schema/uhp-2026-08-11.schema.json
@@ -478,13 +478,15 @@
"items": {
"type": "object",
"additionalProperties": true
- }
+ },
+ "description": "Reserved and ignored. Accepted for wire compatibility, never acted on, and reported in\n`metadata.ignored_fields` on the response. A UHP harness invokes and executes tools\nitself and reports them in `output`; there is no input path for a tool result, so the\nclient-executed tool loop this field implies cannot be completed by a conformant server.\nConfigure tools on the harness instead — see Harnesses §4.1. Tasks §1.4.\n"
},
"include": {
"type": "array",
"items": {
"type": "string"
- }
+ },
+ "description": "Reserved and ignored. Accepted for wire compatibility, never acted on, and reported in\n`metadata.ignored_fields` on the response. No values are enumerated, so any string a\nserver recognised would be one it named itself. Tasks §1.4.\n"
},
"background": {
"type": "boolean",
@@ -582,6 +584,13 @@
},
"model_fallback_reason": {
"type": "string"
+ },
+ "ignored_fields": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ },
+ "description": "Request fields the server did not act on, by name, in any order. Required when the\nrequest carried `tools` or `include`, which are reserved and ignored. A silently\nignored field is indistinguishable from an honoured one. Tasks §1.1 and §1.4.\n"
}
},
"additionalProperties": true
diff --git a/protocol/versions/2026-08-11/tasks.md b/protocol/versions/2026-08-11/tasks.md
index 26bd55c6..ce5272a0 100644
--- a/protocol/versions/2026-08-11/tasks.md
+++ b/protocol/versions/2026-08-11/tasks.md
@@ -36,13 +36,23 @@ Content-Type: application/json
| `max_output_tokens` | integer | no | Upper bound on generated tokens. |
| `max_step` | integer | no | Upper bound on agent steps (tool-call rounds) for this task. |
| `timeout_seconds` | integer | no | Wall-clock budget for this task. |
-| `tools` | array | no | Additional tools offered for this task. |
-| `include` | string[] | no | Optional extra content to include in the result. |
+| `tools` | array | no | **Reserved and ignored.** Accepted, never acted on. See §1.4. |
+| `include` | string[] | no | **Reserved and ignored.** Accepted, never acted on. See §1.4. |
| `background` | boolean | no | Return as soon as the task is accepted; follow it with the events endpoint. |
A server MUST ignore request fields it does not understand rather than rejecting the request. A
client MUST NOT rely on an unknown field having an effect.
+Ignoring MUST be observable. When a server does not act on a field the request carried, it MUST
+name that field in `metadata.ignored_fields` on the response — an array of request-field names, in
+any order. This is the same principle as model substitution in §1.3: where the server did not do
+what the request literally said, the response says so. A silently ignored field is
+indistinguishable from an honoured one, and a client cannot tell which it got.
+
+`tools` and `include` are reserved and ignored (§1.4), so a server MUST name them in
+`metadata.ignored_fields` whenever a request carries them. A server MUST NOT reject a request for
+carrying either.
+
`max_step` and `timeout_seconds` are budgets, not guarantees of precision: a server MUST stop the
task at or after the budget, MUST report `incomplete`, and MUST NOT report `completed` for work it
truncated.
@@ -98,6 +108,49 @@ with `metadata.requested_model`.
> measurement downstream wrong — benchmarks, cost attribution, quality comparisons — and the client
> has no way to detect it. Reporting the substitution costs two fields.
+### 1.4 Reserved fields: `tools` and `include`
+
+Both fields arrived with the OpenAI Responses wire shape this version stays compatible with. Neither
+was designed for UHP, and neither has ever had defined semantics here. They are **reserved**: a
+server accepts them, never acts on them, and reports them under `metadata.ignored_fields` (§1.1).
+
+This is a decision rather than a gap left open, so implementers can stop carrying them as unfinished
+work and client authors can stop building on them.
+
+**`tools` cannot mean what it means in the Responses API.** There, the field exists because the
+*client* executes tools: the model emits a `function_call`, the client runs it, and returns a
+`function_call_output` as input on the next request. UHP puts both of those in `output` (§3.1). The
+harness invokes and executes tools itself and reports them as observability. There is no input path
+for a tool result, so the loop `tools` implies cannot be completed by a conformant server — not
+because implementations are immature, but because the object model has no place for the return leg.
+
+**`tools` also cannot mean "MCP servers for this task", which is the other plausible reading.**
+[Harnesses](harnesses.md) §4.1 already specifies MCP servers on the harness, with a
+field table and the semantics that matter: a disabled entry MUST NOT be contacted, an unreachable
+server MUST NOT fail the task. A request-level form would be a second mechanism for one behaviour.
+
+More importantly, it would be an **escalation primitive**. If a request can attach an MCP server,
+anyone holding an API key can point the agent at an endpoint of their choosing, and the agent
+executes tools server-side with the harness's credentials and workspace access. The harness owner
+and the API caller are routinely different parties — a product configures a harness, and its end
+users drive tasks against it. Request-level declaration silently moves a capability decision from
+the accountable party to any caller. The configured harness is a first-class object precisely so
+that decision is made once, deliberately, by whoever owns the consequences.
+
+The durable rule underneath, which applies beyond this field: **narrowing is safe, widening is
+escalation.** A future version could reasonably add a typed per-request tool *disable* list. It
+should never add a per-request *grant*.
+
+**`include` has no vocabulary.** It is `array of string` with no enumerated values, so any string a
+server recognises is one that server named itself. Recognising a value would be inventing a
+vocabulary no other implementation shares.
+
+**How an agent gets tools:** configure them on the harness. See
+[Harnesses](harnesses.md) §4.1 for MCP servers and §4.2 for skills.
+
+Removal is a question for the next version. This one is additive-only and cannot drop a field, so
+the honest form here is to say plainly that these two do nothing.
+
## 2. Input
`input` is either a string or an array of items.