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.
Python agent-apiagent-frameworkagent-harnessai-agentsai-infrastructurecoding-agentconformance-testingdeepseek-harnessharness-engineeringhermesllmopen-protocolopen-sourceopen-standardpi-coding-agentself-hosteduhpunified-apiunified-harness-protocolunified-interface
fix(tools): Hermes could not use MCP at all, and disabled tools were ignored there
richard-epsillaea4c170c7e02
diff --git a/docker/entrypoint.sh b/docker/entrypoint.shindex d9fe4514..ba1c7073 100644--- a/docker/entrypoint.sh+++ b/docker/entrypoint.sh@@ -143,13 +143,44 @@ install_backends() {if wanted hermes && [ ! -x "$(backend_bin hermes)" ]; thenecho "[harnessrouter] installing Hermes (check its upstream license before use)…"{ "$PY" -m venv "$TOOLS/venv" \- && "$TOOLS/venv/bin/pip" install --no-cache-dir -q "hermes-agent==0.19.0" anthropic mcp; } \+ && "$TOOLS/venv/bin/pip" install --no-cache-dir -q \+ "hermes-agent==0.19.0" anthropic "$HERMES_MCP_PIN"; } \>/dev/null 2>&1 || truefi[ -d "$TOOLS/venv/bin" ] && export PATH="$TOOLS/venv/bin:$PATH"# Hermes otherwise tries to install its own dependencies mid-turn.export HERMES_DISABLE_LAZY_INSTALLS=1+ wanted hermes && verify_hermes_mcp+}++# hermes 0.19.0 gates HTTP MCP on importing `streamablehttp_client`, the name the mcp SDK+# deprecated and REMOVED in 2.0.0. With an unpinned `mcp`, pip resolves 2.0.0, that import fails,+# and hermes disables HTTP MCP entirely — every remote MCP server a user configures is dropped with+# only a line in a log file inside the workspace. The agent then answers "I can't access that tool",+# which reads as a model refusal rather than a broken install.+#+# So the SDK is pinned below 2.0, and the pin is VERIFIED rather than assumed: lazy installs are+# sealed, so hermes cannot repair this itself, and a volume provisioned before the pin still has+# the broken version. Checking the exact symbol hermes checks turns a silent capability loss into+# one line on start-up — and repairs it in place.+HERMES_MCP_PIN="${HERMES_MCP_PIN:-mcp>=1.9,<2}"++verify_hermes_mcp() {+ [ -x "$TOOLS/venv/bin/python" ] || return 0+ "$TOOLS/venv/bin/python" - <<'PYEOF' && return 0+try:+ from mcp.client.streamable_http import streamablehttp_client # noqa: F401+except Exception:+ raise SystemExit(1)+PYEOF+ echo "[harnessrouter] repairing Hermes MCP support (installed mcp SDK lacks the transport it needs)…"+ "$TOOLS/venv/bin/pip" install --no-cache-dir -q "$HERMES_MCP_PIN" >/dev/null 2>&1 || true+ if "$TOOLS/venv/bin/python" -c "from mcp.client.streamable_http import streamablehttp_client" 2>/dev/null; then+ echo "[harnessrouter] Hermes MCP support restored"+ else+ echo "[harnessrouter] WARNING: Hermes cannot use HTTP MCP servers — remote tools will be unavailable on that backend"+ fi}install_backendsdiff --git a/gateway/app.py b/gateway/app.pyindex ae0bcb10..f321f2a7 100644--- a/gateway/app.py+++ b/gateway/app.py@@ -2163,7 +2163,16 @@ async def _harness_plugins(harness_id: str, org: str, hdr_vals: dict[str, str] |if not s.get("url"):continue_hvals = hdr_vals or {} # (renamed from hv — that name is now the harness-vertex param)- entry = {"name": s.get("name") or s.get("id") or "mcp", "url": _sub_headers(s["url"], _hvals),+ _url = _sub_headers(s["url"], _hvals)+ # Same rule the console's Test connection applies. Enforced here too, because this is the+ # call that actually reaches the network: a URL the policy rejects must never be handed to+ # a sandbox, whatever is stored on the harness.+ _blocked = _ssrf_check(_url)+ if _blocked:+ print(f"[mcp] refusing '{s.get('name') or 'mcp'}' for harness {harness_id}: {_blocked}",+ flush=True)+ continue+ entry = {"name": s.get("name") or s.get("id") or "mcp", "url": _url,"transport": s.get("transport") or "http"}# $headers refs resolve BEFORE vault: an auth of "$headers.X-App-JWT" is the caller's# per-request token, not a vault key. Values are injected here, gateway-side, so the@@ -6176,10 +6185,34 @@ def _parse_jsonrpc(text: str) -> dict:def _ssrf_check(url: str) -> str | None:- """V1C02-006: gate a caller-supplied MCP URL before the server fetches it. HTTPS only;- resolve EVERY DNS answer and reject loopback / link-local / RFC1918 / IPv6 private / cloud- metadata (169.254.169.254 falls under link-local) so a hostname can't rebind to an internal- target. Returns an error string to reject, or None to allow."""+ """The ONE rule for whether this server may talk to an MCP endpoint.++ V1C02-006: gate a caller-supplied MCP URL before the server fetches it. HTTPS only; resolve+ EVERY DNS answer and reject loopback / link-local / RFC1918 / IPv6 private / cloud metadata+ (169.254.169.254 falls under link-local) so a hostname can't rebind to an internal target.+ Returns an error string to reject, or None to allow.++ Applied at BOTH config time (the console's Test connection) and run time (_harness_plugins).+ It used to run only on the test button, so the console refused a URL that a turn then connected+ to anyway: the check was advisory, the operator got a red error and a working server, and on a+ multi-tenant deployment the actual protection was absent. A test that does not predict run time+ is worse than no test.++ On a self-hosted instance the private-address rules are dropped, because there the "internal"+ network is the operator's own laptop: a local MCP server on 127.0.0.1 is a legitimate and+ common setup, the operator already has full access to that machine, and blocking it would+ remove a real capability while protecting nobody from anybody.+ """+ if _pool_is_local():+ from urllib.parse import urlparse+ try:+ u = urlparse(url)+ except Exception: # noqa: BLE001+ return "invalid url"+ if u.scheme not in ("http", "https"):+ return "MCP endpoints must be http or https"+ return None if u.hostname else "url has no host"+import ipaddressimport socketfrom urllib.parse import urlparsediff --git a/protocol/conformance/README.md b/protocol/conformance/README.mdindex 73a83172..8dd480dc 100644--- a/protocol/conformance/README.md+++ b/protocol/conformance/README.md@@ -37,13 +37,13 @@ anything that only inspects a schema.## What it checks-47 checks across three classes.+52 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 || **Extended** | +8 | Session listing and inspection, file input, artifacts, download headers, path-traversal probes |-| **Full** | +2 | Harness create / update / delete, and refusal of an unsupported base |+| **Full** | +7 | Harness create / update / delete, refusal of an unsupported base, skill-folder round trip, MCP and disabled-tool persistence |Every check names the section of the specification it enforces, so a failure points at the sentenceit violates rather than at a test name.@@ -64,6 +64,9 @@ A few of them are worth calling out, because they catch things a schema check neown origin.- **X-08** — artifact ids do not traverse out of their container. Probes for `../` and itspercent-encoded form.+- **F-03/F-04** — a skill is a folder, and it survives an unrelated edit. A server that stores only+ `SKILL.md`, or that empties a bundle when the harness is renamed, passes every other check: the+ config still looks right, and the loss only shows up later as an agent behaving oddly.## Outcomes@@ -85,7 +88,7 @@ a live instance on 2026-08-11:```Summary- 47/47 passed · 0 failed · 0 skipped · 0 errored+ 52/52 passed · 0 failed · 0 skipped · 0 erroredCONFORMANT — UHP 2026-08-11 (full)```@@ -104,6 +107,21 @@ in the suite itself:4. `POST /v1/harnesses` accepted a base the server could not run, deferring the failure to the firsttask — after the client had committed to it. Caught by **F-02** on the first full run.+Testing the tool and skill surface against live agents found three more, none of which any+config-level check would have seen:++5. **Hermes could not use HTTP MCP servers at all.** The image installed an unpinned `mcp` SDK,+ which resolved to a version that removed the symbol Hermes gates HTTP transport on. Every remote+ MCP server configured for that backend was silently dropped, and the agent replied "I can't+ access that tool" — indistinguishable from a model refusal. The SDK is now pinned, verified on+ start-up, and repaired in place on volumes that already have the broken version.+6. **Hermes ignored `disabledTools` entirely.** Claude enforces them with a hard flag and Codex+ receives them as an instruction; Hermes had neither branch, so an operator who disabled a tool+ got no enforcement and no warning.+7. **The MCP URL policy was advisory.** It ran only on the console's "Test connection" button, so+ the console refused a URL that a turn then connected to anyway. It is now one function applied at+ both config time and run time.+## Adding a checkA check is a function that asserts one requirement:diff --git a/protocol/conformance/reports/harnessrouter-ce-0.3.0.json b/protocol/conformance/reports/harnessrouter-ce-0.3.0.jsonindex 5bda48c7..7e7a3177 100644--- a/protocol/conformance/reports/harnessrouter-ce-0.3.0.json+++ b/protocol/conformance/reports/harnessrouter-ce-0.3.0.json@@ -6,11 +6,11 @@"conformant": true,"highest_class_passed": "full","summary": {- "pass": 47,+ "pass": 52,"fail": 0,"skip": 0,"error": 0,- "total": 47+ "total": 52},"checks": [{@@ -131,7 +131,7 @@"class": "core","spec": "protocol/versions/2026-08-11/harnesses.md#1-discovering-harnesses","outcome": "pass",- "detail": "4 harness(es)"+ "detail": "5 harness(es)"},{"id": "H-02",@@ -163,7 +163,7 @@"class": "core","spec": "protocol/versions/2026-08-11/tasks.md#3-the-response-object","outcome": "pass",- "detail": "status=completed in 5.2s"+ "detail": "status=completed in 6.4s"},{"id": "T-02",@@ -179,7 +179,7 @@"class": "core","spec": "protocol/versions/2026-08-11/tasks.md#13-model-selection-and-substitution","outcome": "pass",- "detail": "model=claude-sonnet-4.6"+ "detail": "model=claude-opus-4.8"},{"id": "T-04",@@ -187,7 +187,7 @@"class": "core","spec": "protocol/versions/2026-08-11/lifecycle.md#4-session-lifecycle","outcome": "pass",- "detail": "session_id=hsess572496c66b58478cb133db32e794aa90"+ "detail": "session_id=hsess3db19fb79ef74a34a425e165e49ccd3c"},{"id": "T-05",@@ -219,7 +219,7 @@"class": "core","spec": "protocol/versions/2026-08-11/streaming.md#1-opening-a-stream","outcome": "pass",- "detail": "14 events"+ "detail": "9 events"},{"id": "S-02",@@ -235,7 +235,7 @@"class": "core","spec": "protocol/versions/2026-08-11/schema.md","outcome": "pass",- "detail": "14 events valid"+ "detail": "9 events valid"},{"id": "S-04",@@ -283,7 +283,7 @@"class": "core","spec": "protocol/versions/2026-08-11/streaming.md#1-opening-a-stream","outcome": "pass",- "detail": "events spread over 8.7s"+ "detail": "events spread over 5.1s"},{"id": "C-01",@@ -291,7 +291,7 @@"class": "core","spec": "protocol/versions/2026-08-11/sessions.md#1-continuing-a-session","outcome": "pass",- "detail": "session hsess572496c66b58478cb133db32e794aa90 extended"+ "detail": "session hsess3db19fb79ef74a34a425e165e49ccd3c extended"},{"id": "C-02",@@ -379,7 +379,47 @@"class": "full","spec": "protocol/versions/2026-08-11/harnesses.md#4-managing-harnesses","outcome": "pass",- "detail": "created, updated and deleted chrn_beb16b3632d148aabdd8164fcb98fed6"+ "detail": "created, updated and deleted chrn_89269ae2a0b04d30b053333ac207e050"+ },+ {+ "id": "F-03",+ "title": "A skill folder round-trips through create and read",+ "class": "full",+ "spec": "protocol/versions/2026-08-11/harnesses.md#42-skills",+ "outcome": "pass",+ "detail": "3 files incl. nested + binary"+ },+ {+ "id": "F-04",+ "title": "An unrelated harness edit does not destroy skill contents",+ "class": "full",+ "spec": "protocol/versions/2026-08-11/harnesses.md#42-skills",+ "outcome": "pass",+ "detail": ""+ },+ {+ "id": "F-05",+ "title": "A skill bundle without SKILL.md is refused at config time",+ "class": "full",+ "spec": "protocol/versions/2026-08-11/harnesses.md#42-skills",+ "outcome": "pass",+ "detail": "refused with HTTP 400"+ },+ {+ "id": "F-06",+ "title": "MCP servers and disabled tools round-trip",+ "class": "full",+ "spec": "protocol/versions/2026-08-11/harnesses.md#41-mcp-servers",+ "outcome": "pass",+ "detail": "mcp + disabledTools preserved"+ },+ {+ "id": "F-07",+ "title": "Configured harnesses are cleaned up",+ "class": "full",+ "spec": "protocol/versions/2026-08-11/harnesses.md#53-delete",+ "outcome": "pass",+ "detail": "3 removed"},{"id": "F-02",diff --git a/protocol/conformance/uhp_conformance/checks.py b/protocol/conformance/uhp_conformance/checks.pyindex a7d5ef4b..bf47eb36 100644--- a/protocol/conformance/uhp_conformance/checks.py+++ b/protocol/conformance/uhp_conformance/checks.py@@ -690,6 +690,131 @@ def f01(ctx):return f"created, updated and deleted {hid}"+def _managed_harness(ctx, **cfg) -> dict:+ """Create a throwaway harness carrying `cfg`, remembered for cleanup."""+ base = _supported_base(ctx)+ body = {"name": f"uhp-conformance-{uuid.uuid4().hex[:6]}", "base": base, **cfg}+ r = ctx.client.post("/v1/harnesses", body=body)+ if r.status != 200:+ raise Skip(f"could not create a harness to configure (HTTP {r.status})")+ h = r.json or {}+ ctx.state.setdefault("_cleanup_harnesses", []).append(h.get("id"))+ return h+++def _supported_base(ctx) -> str:+ if ctx.state.get("_base"):+ return ctx.state["_base"]+ probe = ctx.client.post("/v1/harnesses", body={"name": "uhp-conformance-probe",+ "base": "uhp-conformance-unknown-base"})+ supported = (((probe.json or {}).get("error") or {}).get("detail") or {}).get("supported") or []+ if probe.status == 200:+ ctx.client.delete(f"/v1/harnesses/{(probe.json or {}).get('id')}")+ base = (supported or [(_harness(ctx)).get("base") or "claude-code"])[0]+ ctx.state["_base"] = base+ return base+++# A folder, not a file: the point of the check is the members that are NOT SKILL.md.+_SKILL_BUNDLE = {+ "name": "uhp-conformance-skill",+ "enabled": True,+ "files": [+ {"path": "SKILL.md",+ "content": "---\nname: uhp-conformance-skill\ndescription: A conformance fixture.\n---\n\nSee references/data.md.\n"},+ {"path": "references/data.md", "content": "nested reference file\n"},+ {"path": "assets/blob.bin", "content_b64": "AAECAwQF"},+ ],+}+++@check("F-03", "A skill folder round-trips through create and read", "full",+ f"{SPEC}/harnesses.md#42-skills")+def f03(ctx):+ h = _managed_harness(ctx, skills=[_SKILL_BUNDLE])+ r = ctx.client.get(f"/v1/harnesses/{h['id']}/skills/uhp-conformance-skill/files")+ assert r.status == 200, f"skill files endpoint returned HTTP {r.status}"+ body = r.json+ files = body.get("files") if isinstance(body, dict) else body+ paths = sorted(str((f or {}).get("path")) for f in (files or []))+ want = ["SKILL.md", "assets/blob.bin", "references/data.md"]+ assert paths == want, (+ f"the folder did not round-trip: got {paths}, expected {want}. Materialising or storing "+ "only SKILL.md breaks every skill that carries references, scripts or data.")+ blob = json.dumps(files)+ assert "AAECAwQF" in blob, "the binary member's content_b64 was not preserved byte-for-byte"+ return f"{len(paths)} files incl. nested + binary"+++@check("F-04", "An unrelated harness edit does not destroy skill contents", "full",+ f"{SPEC}/harnesses.md#42-skills")+def f04(ctx):+ h = _managed_harness(ctx, skills=[_SKILL_BUNDLE])+ hid = h["id"]+ got = (ctx.client.get(f"/v1/harnesses/{hid}").json or {})+ # Rename only — exactly what a client does when it PUTs back what it read.+ r = ctx.client.put(f"/v1/harnesses/{hid}", body={+ "name": "uhp-conformance-renamed", "base": got.get("base"),+ "skills": got.get("skills") or [], "mcp_servers": got.get("mcpServers") or [],+ "disabled_tools": got.get("disabledTools") or []})+ assert r.status == 200, f"rename returned HTTP {r.status}"+ after = ctx.client.get(f"/v1/harnesses/{hid}/skills/uhp-conformance-skill/files")+ files = (after.json or {}).get("files") if isinstance(after.json, dict) else after.json+ paths = sorted(str((f or {}).get("path")) for f in (files or []))+ assert paths == ["SKILL.md", "assets/blob.bin", "references/data.md"], (+ f"after renaming the harness the skill folder is {paths} — the round trip lost contents, "+ "which a user cannot detect until an agent behaves oddly.")+++@check("F-05", "A skill bundle without SKILL.md is refused at config time", "full",+ f"{SPEC}/harnesses.md#42-skills")+def f05(ctx):+ base = _supported_base(ctx)+ r = ctx.client.post("/v1/harnesses", body={+ "name": "uhp-conformance-badskill", "base": base,+ "skills": [{"name": "no-manifest", "enabled": True,+ "files": [{"path": "notes.md", "content": "no manifest here"}]}]})+ if r.status == 200:+ ctx.client.delete(f"/v1/harnesses/{(r.json or {}).get('id')}")+ raise AssertionError(+ "a bundle with no SKILL.md was accepted; it would be stored and then silently ignored "+ "at run time, which is the hardest kind of failure for a user to diagnose")+ assert r.status in (400, 422), f"expected 400/422, got HTTP {r.status}"+ return f"refused with HTTP {r.status}"+++@check("F-06", "MCP servers and disabled tools round-trip", "full",+ f"{SPEC}/harnesses.md#41-mcp-servers")+def f06(ctx):+ mcp = [{"name": "conformance-mcp", "url": "https://mcp.example.invalid/mcp",+ "transport": "http", "enabled": False}]+ h = _managed_harness(ctx, mcp_servers=mcp, disabled_tools=["WebSearch"])+ got = ctx.client.get(f"/v1/harnesses/{h['id']}").json or {}+ servers = got.get("mcpServers") or []+ assert servers, "mcpServers came back empty after being set"+ ctx.validate(servers[0], "McpServer")+ assert servers[0].get("enabled") is False, (+ "the server's `enabled: false` was not preserved; a client cannot tell a disabled entry "+ "from an enabled one, and the difference decides whether a third party is contacted")+ assert got.get("disabledTools") == ["WebSearch"], (+ f"disabledTools round-tripped as {got.get('disabledTools')}")+ return "mcp + disabledTools preserved"+++@check("F-07", "Configured harnesses are cleaned up", "full", f"{SPEC}/harnesses.md#53-delete")+def f07(ctx):+ ids = [i for i in ctx.state.get("_cleanup_harnesses") or [] if i]+ if not ids:+ raise Skip("no harnesses were created by earlier checks")+ left = []+ for hid in ids:+ ctx.client.delete(f"/v1/harnesses/{hid}")+ if ctx.client.get(f"/v1/harnesses/{hid}").status != 404:+ left.append(hid)+ assert not left, f"these harnesses still resolve after delete: {left}"+ return f"{len(ids)} removed"++@check("F-02", "Creating a harness with an unsupported base is refused", "full",f"{SPEC}/harnesses.md#41-create")def f02(ctx):diff --git a/protocol/schema/uhp-2026-08-11.openapi.yaml b/protocol/schema/uhp-2026-08-11.openapi.yamlindex d0e7401c..4557766c 100644--- a/protocol/schema/uhp-2026-08-11.openapi.yaml+++ b/protocol/schema/uhp-2026-08-11.openapi.yaml@@ -604,14 +604,74 @@ components:baseLabel: { type: string }defaultModel: { type: string }systemPrompt: { type: string }- mcpServers: { type: array, items: { type: object, additionalProperties: true } }- skills: { type: array, items: { type: object, additionalProperties: true } }+ mcpServers: { type: array, items: { $ref: '#/components/schemas/McpServer' } }+ skills: { type: array, items: { $ref: '#/components/schemas/Skill' } }disabledTools: { type: array, items: { type: string } }maxStep: { type: [integer, 'null'] }timeoutSeconds: { type: [integer, 'null'] }createdAt: { type: integer, description: Unix milliseconds }additionalProperties: true+ McpServer:+ type: object+ required: [name, url]+ description: |+ A remote MCP server attached to a harness. Only enabled entries are connected for a turn; a+ disabled entry must not be contacted at all. An unreachable server must not fail the task.+ properties:+ name: { type: string, description: Sanitised to a CLI-safe identifier by the server. }+ url: { type: string, format: uri }+ transport: { type: string, enum: [http, sse], default: http }+ enabled: { type: boolean, default: true }+ headers: { type: object, additionalProperties: { type: string } }+ auth:+ type: string+ description: |+ Bearer token, or a server-side reference the server resolves. A server must never return+ a resolved credential to a client.+ additionalProperties: true++ Skill:+ type: object+ required: [name]+ description: |+ A skill is a FOLDER, not a file. A server must materialise the whole folder where the agent+ can read it — materialising only SKILL.md breaks every skill carrying references, scripts or+ data. Round-tripping a harness through GET and PUT must not lose skill contents.+ properties:+ name: { type: string }+ enabled:+ type: boolean+ default: true+ description: false suppresses the skill, including one inherited from the base.+ files:+ type: array+ items: { $ref: '#/components/schemas/SkillFile' }+ description: The bundle. Must contain a SKILL.md.+ content:+ type: string+ description: Shorthand for a single-file bundle whose only member is SKILL.md.+ blob:+ type: string+ description: |+ Server-assigned handle for a bundle stored out of line. A client receives it, passes it+ back unchanged, and reads the files from the skill files endpoint.+ additionalProperties: true++ SkillFile:+ type: object+ required: [path]+ properties:+ path:+ type: string+ description: |+ Relative to the skill's own folder; nested directories are supported. A server must+ reject a path that escapes the folder.+ examples: ['SKILL.md', 'references/codes.md', 'assets/logo.png']+ content: { type: string, description: Text content. }+ content_b64: { type: string, description: Base64 for binary content; preserved byte-for-byte. }+ additionalProperties: true+HarnessCreate:type: objectrequired: [base]@@ -620,6 +680,8 @@ components:base: { type: string }default_model: { type: string }system_prompt: { type: string }+ mcp_servers: { type: array, items: { $ref: '#/components/schemas/McpServer' } }+ skills: { type: array, items: { $ref: '#/components/schemas/Skill' } }disabled_tools: { type: array, items: { type: string } }max_step: { type: [integer, 'null'] }timeout_seconds: { type: [integer, 'null'] }diff --git a/protocol/schema/uhp-2026-08-11.schema.json b/protocol/schema/uhp-2026-08-11.schema.jsonindex 936652c3..5e97226d 100644--- a/protocol/schema/uhp-2026-08-11.schema.json+++ b/protocol/schema/uhp-2026-08-11.schema.json@@ -135,15 +135,13 @@"mcpServers": {"type": "array","items": {- "type": "object",- "additionalProperties": true+ "$ref": "#/$defs/McpServer"}},"skills": {"type": "array","items": {- "type": "object",- "additionalProperties": true+ "$ref": "#/$defs/Skill"}},"disabledTools": {@@ -171,6 +169,106 @@},"additionalProperties": true},+ "McpServer": {+ "type": "object",+ "required": [+ "name",+ "url"+ ],+ "description": "A remote MCP server attached to a harness. Only enabled entries are connected for a turn; a\ndisabled entry must not be contacted at all. An unreachable server must not fail the task.\n",+ "properties": {+ "name": {+ "type": "string",+ "description": "Sanitised to a CLI-safe identifier by the server."+ },+ "url": {+ "type": "string",+ "format": "uri"+ },+ "transport": {+ "type": "string",+ "enum": [+ "http",+ "sse"+ ],+ "default": "http"+ },+ "enabled": {+ "type": "boolean",+ "default": true+ },+ "headers": {+ "type": "object",+ "additionalProperties": {+ "type": "string"+ }+ },+ "auth": {+ "type": "string",+ "description": "Bearer token, or a server-side reference the server resolves. A server must never return\na resolved credential to a client.\n"+ }+ },+ "additionalProperties": true+ },+ "Skill": {+ "type": "object",+ "required": [+ "name"+ ],+ "description": "A skill is a FOLDER, not a file. A server must materialise the whole folder where the agent\ncan read it — materialising only SKILL.md breaks every skill carrying references, scripts or\ndata. Round-tripping a harness through GET and PUT must not lose skill contents.\n",+ "properties": {+ "name": {+ "type": "string"+ },+ "enabled": {+ "type": "boolean",+ "default": true,+ "description": "false suppresses the skill, including one inherited from the base."+ },+ "files": {+ "type": "array",+ "items": {+ "$ref": "#/$defs/SkillFile"+ },+ "description": "The bundle. Must contain a SKILL.md."+ },+ "content": {+ "type": "string",+ "description": "Shorthand for a single-file bundle whose only member is SKILL.md."+ },+ "blob": {+ "type": "string",+ "description": "Server-assigned handle for a bundle stored out of line. A client receives it, passes it\nback unchanged, and reads the files from the skill files endpoint.\n"+ }+ },+ "additionalProperties": true+ },+ "SkillFile": {+ "type": "object",+ "required": [+ "path"+ ],+ "properties": {+ "path": {+ "type": "string",+ "description": "Relative to the skill's own folder; nested directories are supported. A server must\nreject a path that escapes the folder.\n",+ "examples": [+ "SKILL.md",+ "references/codes.md",+ "assets/logo.png"+ ]+ },+ "content": {+ "type": "string",+ "description": "Text content."+ },+ "content_b64": {+ "type": "string",+ "description": "Base64 for binary content; preserved byte-for-byte."+ }+ },+ "additionalProperties": true+ },"HarnessCreate": {"type": "object","required": [@@ -189,6 +287,18 @@"system_prompt": {"type": "string"},+ "mcp_servers": {+ "type": "array",+ "items": {+ "$ref": "#/$defs/McpServer"+ }+ },+ "skills": {+ "type": "array",+ "items": {+ "$ref": "#/$defs/Skill"+ }+ },"disabled_tools": {"type": "array","items": {diff --git a/protocol/versions/2026-08-11/harnesses.md b/protocol/versions/2026-08-11/harnesses.mdindex 77afcf17..e4e83b63 100644--- a/protocol/versions/2026-08-11/harnesses.md+++ b/protocol/versions/2026-08-11/harnesses.md@@ -114,11 +114,97 @@ work fails after they have committed to it.A client SHOULD present unavailable models as disabled rather than hiding them, so a user can seethat a model exists and is not configured, rather than wondering why it is missing.-## 4. Managing harnesses+## 4. Tools and skills++A configured harness carries three things that decide what its agent can do. All three are part of+the harness object and are set the same way it is.++### 4.1 MCP servers++```json+{ "mcpServers": [+ { "name": "vault", "url": "https://mcp.example.com/mcp", "transport": "http", "enabled": true }+] }+```++| Field | Required | Meaning |+|---|---|---|+| `name` | yes | Identifies the server to the agent; sanitised to a CLI-safe identifier |+| `url` | yes | Endpoint |+| `transport` | no | `http` (Streamable HTTP, default) or `sse` |+| `enabled` | no | Absent or `true` means enabled |+| `headers` | no | Extra request headers |+| `auth` | no | Bearer token, or a server-side reference the server resolves |++A server MUST connect only the **enabled** entries for a turn. A disabled entry MUST NOT be+contacted at all — not connected and then hidden, which would still leak the turn's existence to+whoever operates that endpoint.++An MCP server that cannot be reached MUST NOT fail the task. The turn MUST proceed without those+tools, because a third-party endpoint being down is not a reason to lose the user's work. A server+SHOULD make the degradation visible in the run rather than silent.++> A server MUST NOT advertise MCP support it cannot deliver. If the harness runtime behind it cannot+> speak the configured transport, that is a broken installation, and reporting it only in a log file+> inside the workspace is indistinguishable — to the user — from the model refusing to use the tool.++### 4.2 Skills++A skill is a **folder**, not a file:++```json+{ "skills": [+ { "name": "vault-manual", "enabled": true, "files": [+ { "path": "SKILL.md", "content": "---\nname: vault-manual\n---\n…" },+ { "path": "references/codes.md", "content": "…" },+ { "path": "scripts/helper.sh", "content": "#!/bin/sh\n…" },+ { "path": "assets/logo.png", "content_b64": "iVBORw0KGgo…" }+ ]}+] }+```++- `files[].path` is relative to the skill's own folder and MUST support nested directories. A server+ MUST reject a path that escapes the folder.+- Text is carried in `content`; binary in `content_b64`. A server MUST preserve both byte-for-byte.+- A bundle MUST contain a `SKILL.md`; a server MUST reject one that does not, at configuration time+ rather than at run time.+- A server MUST materialise the **whole folder** where the agent can read it. Materialising only+ `SKILL.md` breaks every skill that carries references, scripts or data — which is most non-trivial+ skills.+- `enabled: false` suppresses a skill, including one inherited from the base.++A server MAY store large bundles out of line, and MUST return the complete file list from:++```http+GET /v1/harnesses/{harness_id}/skills/{skill_id}/files+```++Round-tripping a harness through `GET` and `PUT` MUST NOT lose skill contents. This is the failure+worth designing against: an unrelated edit — renaming the harness — silently emptying a skill folder+that the user cannot tell is gone until an agent behaves oddly weeks later.++### 4.3 Disabled tools++```json+{ "disabledTools": ["WebSearch"] }+```++Names come from the harness base's own tool catalogue. Enforcement differs by runtime and a server+MUST NOT overstate it:++- Where the runtime supports per-tool restriction, the server MUST enforce it as a hard block.+- Where it does not, the server MUST still convey the restriction to the agent — as a standing+ instruction — and MUST NOT silently drop it. Dropping it is the worst outcome: the operator+ believes a tool is off, and it is not.++A client that requires a guaranteed block SHOULD confirm the harness base supports one rather than+assuming `disabledTools` is always hard.++## 5. Managing harnessesConformance class **Full** only. A client MUST check the `harness_management` capability first.-### 4.1 Create+### 5.1 Create```httpPOST /v1/harnesses@@ -131,7 +217,7 @@ POST /v1/harnessesReturns the created harness object. `base` is REQUIRED and MUST be one the server supports;otherwise `422` with `code: "unsupported_base"`.-### 4.2 Update+### 5.2 Update```httpPUT /v1/harnesses/{harness_id}@@ -141,7 +227,7 @@ Replaces the mutable configuration. A server MUST NOT change `id`, `base`, or `cthe base of an existing harness would silently change the behaviour of every session alreadyattached to it; a client that wants a different base MUST create a different harness.-### 4.3 Delete+### 5.3 Delete```httpDELETE /v1/harnesses/{harness_id}@@ -150,7 +236,7 @@ DELETE /v1/harnesses/{harness_id}A server MUST NOT delete the sessions or responses that used the harness. History that disappearswhen configuration changes cannot be audited.-## 5. Choosing a harness+## 6. Choosing a harnessNon-normative, but the question every client faces:diff --git a/runner/server.py b/runner/server.pyindex 727ece7d..2b1e58fa 100644--- a/runner/server.py+++ b/runner/server.py@@ -1950,10 +1950,16 @@ def turn(req: TurnReq, identifier: str = "") -> dict:) # materialize enabled skills for this backend (minus suppressed built-ins)# Seed the agent's instruction file (AGENTS.md/CLAUDE.md) from the harness doc + installed skills.# The model's system prompt stays the CLI default; persistent instructions live in this file.- # Codex has no per-tool CLI flag, so disabled tools are surfaced as an instruction (claude uses the- # hard --disallowedTools flag below instead).+ #+ # Disabled tools, by what each CLI can actually enforce:+ # claude — `--disallowedTools`, a hard block (applied in _build_claude below).+ # codex, hermes — no per-tool switch exists. Codex has none at all; hermes only disables whole+ # TOOLSETS, which is a different granularity from the per-tool names a harness configures.+ # Both read the agent doc, so both get the same instruction. It is a request to the model,+ # not a guarantee, and is written here once rather than as two divergent branches — hermes+ # previously had neither, and silently ignored every disabled tool.agent_doc = req.agent_doc or ""- if backend == "codex" and req.tools_disabled:+ if backend in ("codex", "hermes") and req.tools_disabled:_off = ", ".join(t for t in req.tools_disabled if t)if _off:agent_doc = ((agent_doc + "\n\n") if agent_doc.strip() else "") + \