merge: feat/ctgov-processed-date — trials answers show the date ClinicalTrials.gov processed the data (dataTimestamp via one direct /api/v2/version call, ADR-0001 exception approved 2026-11-12) and state our changes; addendum pillow count 40

docs/adr/ADR-0001-knowledge-specialist-contract.md

@@ -81,6 +81,28 @@ two weeks). The fleet's contract has to sit between ToolUniverse and the orchest
    or limit becomes a structured `source_errors` entry, never a retry loop that outlasts the orchestrator's call
    limit.
 
+## Exception: direct calls (2026-11-12)
+
+**Decided 2026-11-12 by the project lead (option A, "direct call").** Decision 7 makes every outbound call an
+allow-listed ToolUniverse tool. One fact no ToolUniverse 1.5.6 tool returns is the date ClinicalTrials.gov processed
+its data, which the ClinicalTrials.gov Terms and Conditions ask a redistributor to show (with a statement of any
+changes): every ClinicalTrials.gov tool rebuilds a study from its record keeping only the start and completion dates,
+and none wraps `/api/v2/version`, whose `dataTimestamp` is that date. So the Space makes one direct call,
+`ctgov_data_timestamp` (`GET https://clinicaltrials.gov/api/v2/version`), once per `trials_for_genes` answer.
+
+The exception is bounded, and tests hold each bound (`tests/test_direct_calls.py`):
+
+- A direct call is a named entry in `src/direct_calls.py`, the only module that opens a URL itself. It takes no
+  arguments, so no identifier or other input reaches it.
+- Its host is already declared for its source in `config/sources.yaml`; this one adds no host.
+- It runs through `ToolClient` like a tool: our cache with the source's TTL (24 h), the source's rate bucket, the
+  deadline, a pinned schema (`src/schemas/ctgov_data_timestamp.schema.json`), and cassette replay in tests.
+- Adding another direct call needs the same kind of decision; it is not a config change.
+
+What it shows: every `trials_for_genes` payload with an answer carries `source_terms` and ends its narrative with
+"Data from ClinicalTrials.gov, processed by ClinicalTrials.gov on <date>." plus the statement of what this Space
+changes (`src/ctgov_terms.py`). If the date cannot be read the notice says so and why, and the studies stay.
+
 ## Knowledge is annotation, never analysis
 
 - The specialist computes nothing across sources: no combined scores, no rankings of its own, no p-values. When a

docs/security/addendum-knowledge-specialist.md

@@ -45,6 +45,12 @@ loaded tool's configuration and code in the installed package and fails on any u
 8 hosts in all; 6 are called by a Phase 1 endpoint. Source of truth: `config/sources.yaml`, checked against the installed ToolUniverse by `tests/test_sources_hosts.py`.
 <!-- host-table:end -->
 
+**One direct call (ADR-0001 exception, 2026-11-12).** Besides the ToolUniverse tools, the Space makes one call of
+its own: `GET https://clinicaltrials.gov/api/v2/version`, to read the date ClinicalTrials.gov processed its data,
+which its terms ask every trials answer to show. It reaches a host already in the table, sends nothing (no
+arguments), and goes through the same cache, rate limit, deadline and schema check as the tools
+[`src/direct_calls.py`; `tests/test_direct_calls.py`].
+
 **What leaves the Space.** Only public identifiers: gene symbols (HGNC), gene ids (Ensembl), protein entry numbers (UniProt),
 EFO/MONDO/Orphanet disease ids, NCT ids, and a disease name as a bounded string (at most 80 characters; letters,
 digits, spaces, hyphens, commas, apostrophes), at most 100 per call. Free text, sample identifiers, numbers
@@ -93,7 +99,7 @@ It holds no secret and no model key, and it keeps counts and timings only, never
   is share-alike, so a redistributed table built from ChEMBL rows must carry the same licence [`config/sources.yaml`].
 - **Development.** The same enforced pre-push gate as the other repositories: pip-audit over the full 119-package
   lock, bandit, gitleaks over the tree and full history, and an SBOM [`scripts/security_scan.sh`]. One accepted
-  finding set, shared with the rest of the fleet, is documented and expires on 2026-12-18: 39 pillow 12.3.0
+  finding set, shared with the rest of the fleet, is documented and expires on 2026-12-18: 40 pillow 12.3.0
   advisories that gradio's own version constraint prevents fixing, none reachable here because the Space never
   decodes an image a caller supplies [`security/ACCEPTED-FINDINGS.md` §1; `security/accepted-vulns.txt`].
 - **The vendor's own posture.** ToolUniverse states that it operates no servers and collects no telemetry; a lookup's

scripts/record_fixtures.py

@@ -25,7 +25,7 @@ from pathlib import Path
 ROOT = Path(__file__).resolve().parent.parent
 sys.path.insert(0, str(ROOT))
 
-from src import config, schemas
+from src import config, direct_calls, schemas
 from src.cache import ResponseCache
 from src.endpoints import ENDPOINTS, _common
 from src.tu_client import (
@@ -133,7 +133,10 @@ class Recorder:
         self.calls: list[dict] = []
 
     def __call__(self, tool: str, args: dict):
-        response = self.tu.run_one_function({"name": tool, "arguments": args}, use_cache=False)
+        if direct_calls.is_direct(tool):
+            response = direct_calls.run(tool, args, timeout=30)
+        else:
+            response = self.tu.run_one_function({"name": tool, "arguments": args}, use_cache=False)
         self.calls.append({"tool": tool, "args": dict(args), "response": response})
         return response
 

src/config.py

@@ -136,6 +136,10 @@ def tools_for_endpoint(endpoint: str) -> tuple[str, ...]:
 
 
 def source_of(tool: str) -> str:
+    from src.direct_calls import DIRECT_CALLS  # the ADR-0001 direct-call exception
+
+    if tool in DIRECT_CALLS:
+        return DIRECT_CALLS[tool].source
     try:
         return allowlist()["tools"][tool]["source"]
     except KeyError:

src/ctgov_terms.py

@@ -0,0 +1,58 @@
+"""ClinicalTrials.gov redistribution notice: the date its data were processed, and our changes.
+
+The ClinicalTrials.gov Terms and Conditions (config/sources.yaml, checked 2026-10-27) ask anyone
+who redistributes the data to show the date ClinicalTrials.gov processed it and to state any
+changes made. The date is ``dataTimestamp`` from ClinicalTrials.gov's own ``/api/v2/version``
+response (src/direct_calls.py), never our fetch time or today's date. Every payload with
+ClinicalTrials.gov results carries the notice as a structured ``source_terms`` entry AND as the
+last sentence of its narrative, because the narrative is what the UI summary shows and what the
+orchestrator relays. The wording is deterministic text, never generated.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+SOURCE = "clinicaltrials"
+DATE_TOOL = "ctgov_data_timestamp"
+# The fields the row builder in src/endpoints/trials.py keeps, in words
+# (tests/test_ctgov_terms.py checks this list against the rows).
+SHOWN_FIELDS = (
+    "NCT number",
+    "title",
+    "overall status",
+    "phases",
+    "study type",
+    "conditions",
+    "up to five intervention names",
+    "lead sponsor",
+    "start date",
+    "completion date",
+)
+CHANGES = (
+    "This Space shows selected fields of each matching study record ("
+    + ", ".join(SHOWN_FIELDS)
+    + ") and lists only studies whose intervention name matches the gene; it does not edit "
+    "the values. Records change: the current version of each is at "
+    "clinicaltrials.gov/study/<NCT number>."
+)
+
+
+def notice(data_timestamp: str | None, problem: str | None = None) -> dict[str, Any]:
+    """The structured notice. ``data_timestamp`` is ClinicalTrials.gov's ``dataTimestamp``."""
+    processed = data_timestamp[:10] if data_timestamp else None
+    if processed:
+        lead = f"Data from ClinicalTrials.gov, processed by ClinicalTrials.gov on {processed}."
+    else:
+        lead = (
+            "Data from ClinicalTrials.gov; the date ClinicalTrials.gov processed it could not "
+            f"be read ({problem or 'not reported'})."
+        )
+    return {
+        "source": SOURCE,
+        "data_processed_on": processed,
+        "data_timestamp": data_timestamp,
+        "date_from": "ClinicalTrials.gov /api/v2/version dataTimestamp",
+        "changes": CHANGES,
+        "sentence": f"{lead} {CHANGES}",
+    }

src/direct_calls.py

@@ -0,0 +1,62 @@
+"""Direct source calls — the ADR-0001 exception for what ToolUniverse cannot return.
+
+ADR-0001 says this Space wraps an allow-listed ToolUniverse subset. One fact no ToolUniverse
+1.5.6 tool returns is the date ClinicalTrials.gov processed its data, which the
+ClinicalTrials.gov Terms and Conditions ask a redistributor to show: every ClinicalTrials.gov
+tool rebuilds each study from its record and keeps only the start and completion dates, and none
+wraps ``/api/v2/version``, whose ``dataTimestamp`` is that date. The project lead approved one
+direct call for it on 2026-11-12 (option A; recorded in
+docs/adr/ADR-0001-knowledge-specialist-contract.md, "Exception: direct calls").
+
+A direct call is not a back door around the client. It is a named entry here, it goes through
+:class:`src.tu_client.ToolClient` exactly like a ToolUniverse tool (our cache with the source's
+TTL, the source's rate bucket, the deadline, a pinned schema under ``src/schemas/``, cassette
+replay in tests), its URL's host must already be declared for its source in
+``config/sources.yaml`` (tests/test_direct_calls.py), and it takes no arguments, so nothing a
+caller types reaches the URL. This module imports nothing from ``src``.
+"""
+
+from __future__ import annotations
+
+import json
+import urllib.request
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass(frozen=True)
+class DirectCall:
+    source: str
+    url: str
+    why: str
+
+
+DIRECT_CALLS: dict[str, DirectCall] = {
+    "ctgov_data_timestamp": DirectCall(
+        source="clinicaltrials",
+        url="https://clinicaltrials.gov/api/v2/version",
+        why=(
+            "dataTimestamp = the date ClinicalTrials.gov processed its data, shown on every "
+            "trials answer as its terms ask; no ToolUniverse 1.5.6 tool returns it "
+            "(project lead, 2026-11-12)"
+        ),
+    ),
+}
+
+
+def is_direct(tool: str) -> bool:
+    return tool in DIRECT_CALLS
+
+
+def run(tool: str, args: dict[str, Any], timeout: float) -> dict[str, Any]:
+    """GET the call's fixed URL; the response in ToolUniverse's envelope, so the client treats
+    it like any tool's. Errors propagate: the client turns them into ``source_unavailable``."""
+    call = DIRECT_CALLS[tool]
+    if args:
+        raise ValueError(f"{tool} takes no arguments")
+    request = urllib.request.Request(
+        call.url, headers={"Accept": "application/json", "User-Agent": "pdac-knowledge-agent"}
+    )
+    with urllib.request.urlopen(request, timeout=timeout) as response:
+        data = json.loads(response.read().decode("utf-8"))
+    return {"status": "success", "data": data, "metadata": {"source": call.url}}

src/endpoints/trials.py

@@ -6,13 +6,19 @@ name (Phase 0 finding 5: "CD40" gives the one pancreas-specific mitazalimab tria
 API query also returns two solid-tumour basket trials). That rewrite is helpful but silent, so
 every payload states it: ``query_semantics`` in words, and ``executed_queries`` with the exact
 query ClinicalTrials.gov ran, taken from the response itself and pinned by a recorded fixture.
+
+ClinicalTrials.gov's terms ask a redistributor to show the date ClinicalTrials.gov processed the
+data and to state any changes: once a search has answered, one more call reads that date
+(``dataTimestamp``, src/direct_calls.py) and the payload carries the notice of
+:mod:`src.ctgov_terms` in ``source_terms`` and as the narrative's last sentence. Each row also
+carries ``ctgov_data_processed_on``, so a relay that shows only rows keeps the date.
 """
 
 from __future__ import annotations
 
 from typing import Any
 
-from src import payloads
+from src import ctgov_terms, payloads
 from src.endpoints._common import Budget, Collector, according_to, get_client, stamped
 from src.identifiers import parse_disease, parse_gene_list
 
@@ -110,6 +116,10 @@ def trials_for_genes(genes: str = "", condition: str = "", status: str = "") ->
             "ClinicalTrials.gov did not answer; nothing was looked up.",
             source_errors=out.source_errors,
         )
+    terms = _terms_notice(client, budget, out) if per_gene else None
+    if terms is not None:
+        for row in out.rows:
+            row["ctgov_data_processed_on"] = terms["data_processed_on"]
     lead = according_to(["clinicaltrials"], out.retrieved)
     kind = "of any status" if wanted == "ANY" else wanted
     clauses = []
@@ -136,6 +146,8 @@ def trials_for_genes(genes: str = "", condition: str = "", status: str = "") ->
             + "; ".join(f"{e['source']} {e['reason']}" for e in out.source_errors)
             + "."
         )
+    if terms is not None:
+        sentences.append(terms["sentence"])
     return payloads.ok(
         ENDPOINT,
         query={"genes": symbols, "condition": condition_name, "status": wanted},
@@ -146,4 +158,19 @@ def trials_for_genes(genes: str = "", condition: str = "", status: str = "") ->
         source_errors=out.source_errors,
         query_semantics=QUERY_SEMANTICS,
         executed_queries=executed,
+        source_terms=[terms] if terms is not None else [],
     )
+
+
+def _terms_notice(client, budget: Budget, out: Collector) -> dict[str, Any]:
+    """The ClinicalTrials.gov notice, with the processed date read from ClinicalTrials.gov.
+
+    A failure here never hides the studies already found: the notice says the date could not be
+    read and why, and the failure is not a ``source_errors`` entry (the search itself answered).
+    """
+    if budget.spent:
+        return ctgov_terms.notice(None, "the call budget ran out before it could be read")
+    result, err = out.attempt(client, budget, ctgov_terms.DATE_TOOL, {})
+    if err is not None:
+        return ctgov_terms.notice(None, f"{err.reason}: {err.detail}")
+    return ctgov_terms.notice(result.data["dataTimestamp"])

src/schemas/ctgov_data_timestamp.schema.json

@@ -0,0 +1,17 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$comment": "Pinned 2026-11-12 for the direct call src/direct_calls.py::ctgov_data_timestamp (GET clinicaltrials.gov/api/v2/version; ADR-0001 exception approved 2026-11-12). dataTimestamp is the date ClinicalTrials.gov processed its data, shown on every trials answer; it must start with an ISO date so the shown date is never guessed.",
+  "type": "object",
+  "required": [
+    "dataTimestamp"
+  ],
+  "properties": {
+    "dataTimestamp": {
+      "type": "string",
+      "pattern": "^\\d{4}-\\d{2}-\\d{2}"
+    },
+    "apiVersion": {
+      "type": "string"
+    }
+  }
+}

src/tu_client.py

@@ -25,7 +25,9 @@ ADR-0001 §7, enforced in code rather than by convention:
   ``tooluniverse_version``. A bump is its own lane (doctor, re-recorded fixtures, schema tests,
   security scan) and never changes an endpoint's name or payload shape.
 
-:class:`ToolClient` is what the endpoints call. It returns a :class:`SourceResult` or raises a
+:class:`ToolClient` is what the endpoints call. It also runs the few named direct calls of
+:mod:`src.direct_calls` (the ADR-0001 exception for facts no ToolUniverse tool returns) through
+the same cache, rate limit, deadline and schema check. It returns a :class:`SourceResult` or raises a
 :class:`SourceError` whose ``reason`` is one of the three payload source-error reasons, so a
 timeout, a limit or a drifted response is always structured, never a guess.
 """
@@ -43,7 +45,7 @@ from collections.abc import Callable, Mapping
 from dataclasses import dataclass
 from typing import Any
 
-from src import config, schemas
+from src import config, direct_calls, schemas
 from src.cache import ResponseCache
 from src.ratelimit import RateLimiters
 
@@ -285,6 +287,9 @@ class ToolClient:
         return self._version
 
     def _default_runner(self, tool: str, args: dict[str, Any]) -> Any:
+        if direct_calls.is_direct(tool):
+            timeout = config.source(config.source_of(tool))["timeout_seconds"]
+            return direct_calls.run(tool, args, timeout)
         with _build_lock:
             if self._tu is None:
                 self._tu = build_tooluniverse()
@@ -299,8 +304,9 @@ class ToolClient:
         deadline: float | None = None,
     ) -> SourceResult:
         """``deadline`` can shorten the source's ``timeout_seconds`` for this call, never extend it."""
-        if tool not in config.endpoint_tool_names():
-            # A programming error, not a user input: endpoints only ever name loaded tools.
+        if tool not in config.endpoint_tool_names() and not direct_calls.is_direct(tool):
+            # A programming error, not a user input: endpoints only ever name loaded tools (or a
+            # named direct call, src/direct_calls.py).
             raise ValueError(f"{tool!r} is not an endpoint tool")
         source = config.source_of(tool)
         cfg = config.source(source)

tests/fixtures/cassettes/q5_trials_cd40.json

@@ -9,8 +9,8 @@
    ""
   ],
   "tooluniverse_version": "1.5.6",
-  "recorded_on": "2026-10-21T04:42:55Z",
-  "recorded_at_epoch": 1792557775.678,
+  "recorded_on": "2026-11-12T16:59:22Z",
+  "recorded_at_epoch": 1794502761.98,
   "recorded_with": "scripts/record_fixtures.py",
   "payload_status_when_recorded": "ok",
   "licences": {
@@ -85,6 +85,20 @@
      "operation": "search"
     }
    }
+  },
+  {
+   "tool": "ctgov_data_timestamp",
+   "args": {},
+   "response": {
+    "status": "success",
+    "data": {
+     "apiVersion": "2.0.5",
+     "dataTimestamp": "2026-11-12T10:00:05"
+    },
+    "metadata": {
+     "source": "https://clinicaltrials.gov/api/v2/version"
+    }
+   }
   }
  ]
 }

tests/test_ctgov_terms.py

@@ -0,0 +1,179 @@
+"""ClinicalTrials.gov terms: every trials answer shows the date ClinicalTrials.gov processed the
+data (its own ``dataTimestamp``, never our fetch time or today's date) and states our changes.
+
+The date comes from the direct ``/api/v2/version`` call (ADR-0001 exception, 2026-11-12). The
+recorded CD40 cassette carries that response; the synthetic cases use a date far from the clock,
+so a value taken from anywhere but the response would show.
+"""
+
+from __future__ import annotations
+
+import datetime
+import json
+
+import pytest
+
+from src import ctgov_terms
+from src.endpoints import _common
+from src.endpoints.trials import trials_for_genes
+from src.ratelimit import RateLimiters
+from src.tu_client import ToolClient
+from tests.conftest import CASSETTES, FakeRunner
+
+CT = "ClinicalTrials_search_studies"
+
+
+def _cassette_timestamp() -> str:
+    calls = json.loads((CASSETTES / "q5_trials_cd40.json").read_text())["calls"]
+    [call] = [c for c in calls if c["tool"] == ctgov_terms.DATE_TOOL]
+    return call["response"]["data"]["dataTimestamp"]
+
+
+def test_recorded_cd40_answer_shows_the_processed_date_and_the_changes(replay):
+    payload = replay("q5_trials_cd40")
+    processed = _cassette_timestamp()[:10]
+    [terms] = payload["source_terms"]
+    assert terms["source"] == "clinicaltrials"
+    assert terms["data_processed_on"] == processed
+    assert terms["data_timestamp"] == _cassette_timestamp()
+    expected = f"Data from ClinicalTrials.gov, processed by ClinicalTrials.gov on {processed}."
+    # The narrative is what the UI summary shows and the orchestrator relays.
+    assert payload["narrative"].endswith(f"{expected} {ctgov_terms.CHANGES}")
+    assert all(r["ctgov_data_processed_on"] == processed for r in payload["rows"])
+
+
+def _study(nct="NCT00000001"):
+    return {
+        "nct_id": nct,
+        "brief_title": "A trial",
+        "status": "RECRUITING",
+        "phases": ["PHASE1"],
+        "study_type": "INTERVENTIONAL",
+        "conditions": ["Pancreatic Cancer"],
+        "interventions": ["drug"],
+        "sponsor": "Someone",
+        "start_date": "2024-01-01",
+        "completion_date": "2030-01",
+    }
+
+
+def _search(studies):
+    return {
+        "status": "success",
+        "data": {
+            "studies": studies,
+            "total_count": len(studies),
+            "executed_query": {"query.intr": "x"},
+        },
+    }
+
+
+@pytest.fixture()
+def client_with(memory_cache, clock):
+    def make(responses):
+        runner = FakeRunner(responses)
+        client = ToolClient(
+            runner=runner,
+            cache=memory_cache,
+            limiters=RateLimiters(clock=clock, sleep=clock.sleep),
+            clock=clock,
+            tooluniverse_version="1.5.6",
+        )
+        _common.set_client(client)
+        return runner
+
+    yield make
+    _common.set_client(None)
+
+
+def test_the_date_is_the_responses_not_the_clocks(client_with, clock):
+    client_with(
+        {
+            CT: _search([_study()]),
+            ctgov_terms.DATE_TOOL: {
+                "status": "success",
+                "data": {"apiVersion": "2.0.5", "dataTimestamp": "2019-03-04T10:00:05"},
+            },
+        }
+    )
+    payload = trials_for_genes("CD40")
+    today = datetime.datetime.fromtimestamp(clock(), datetime.UTC).date().isoformat()
+    assert today != "2019-03-04"
+    assert payload["source_terms"][0]["data_processed_on"] == "2019-03-04"
+    assert "processed by ClinicalTrials.gov on 2019-03-04." in payload["narrative"]
+    assert payload["rows"][0]["ctgov_data_processed_on"] == "2019-03-04"
+
+
+def test_the_date_is_read_once_per_answer(client_with):
+    runner = client_with(
+        {
+            CT: _search([_study()]),
+            ctgov_terms.DATE_TOOL: {"status": "success", "data": {"dataTimestamp": "2026-11-12"}},
+        }
+    )
+    trials_for_genes("CD40,KRAS")
+    assert [t for t, _ in runner.calls].count(ctgov_terms.DATE_TOOL) == 1
+
+
+def test_an_unreadable_date_is_said_and_the_studies_stay(client_with):
+    client_with({CT: _search([_study()]), ctgov_terms.DATE_TOOL: OSError("down")})
+    payload = trials_for_genes("CD40")
+    assert payload["status"] == "ok" and len(payload["rows"]) == 1
+    [terms] = payload["source_terms"]
+    assert terms["data_processed_on"] is None
+    assert "the date ClinicalTrials.gov processed it could not be read" in payload["narrative"]
+    assert ctgov_terms.CHANGES in payload["narrative"]
+    assert payload["source_errors"] == []  # the search answered; only the date is missing
+
+
+def test_a_drifted_date_response_is_not_guessed(client_with):
+    client_with(
+        {
+            CT: _search([_study()]),
+            ctgov_terms.DATE_TOOL: {"status": "success", "data": {"dataTimestamp": "yesterday"}},
+        }
+    )
+    terms = trials_for_genes("CD40")["source_terms"][0]
+    assert terms["data_processed_on"] is None
+
+
+def test_a_failed_search_reads_no_date(client_with):
+    runner = client_with({CT: OSError("down"), ctgov_terms.DATE_TOOL: AssertionError("unused")})
+    payload = trials_for_genes("CD40")
+    assert payload["status"] == "error"
+    assert ctgov_terms.DATE_TOOL not in [t for t, _ in runner.calls]
+
+
+def test_zero_studies_still_carries_the_notice(client_with):
+    client_with(
+        {
+            CT: _search([]),
+            ctgov_terms.DATE_TOOL: {"status": "success", "data": {"dataTimestamp": "2026-11-12"}},
+        }
+    )
+    payload = trials_for_genes("CD40")
+    assert payload["source_terms"][0]["data_processed_on"] == "2026-11-12"
+
+
+def test_the_changes_statement_names_every_field_the_rows_keep(replay):
+    payload = replay("q5_trials_cd40")
+    kept = {
+        "nct_id": "NCT number",
+        "title": "title",
+        "status": "overall status",
+        "phases": "phases",
+        "study_type": "study type",
+        "conditions": "conditions",
+        "interventions": "up to five intervention names",
+        "sponsor": "lead sponsor",
+        "start_date": "start date",
+        "completion_date": "completion date",
+    }
+    row = payload["rows"][0]
+    assert set(kept) <= set(row)
+    assert list(kept.values()) == list(ctgov_terms.SHOWN_FIELDS)
+    # A new study field in the row builder must be named in the statement too.
+    study_fields = {"gene", "ctgov_data_processed_on", *kept}
+    from src.provenance import PROVENANCE_FIELDS
+
+    assert set(row) - set(PROVENANCE_FIELDS) - {"provenance"} <= study_fields

tests/test_direct_calls.py

@@ -0,0 +1,73 @@
+"""The ADR-0001 direct-call exception stays narrow (approved by the project lead, 2026-11-12).
+
+A direct call is a named entry in src/direct_calls.py, takes no arguments, reaches only a host
+already declared for its source, has a pinned schema and goes through ToolClient. Nothing else in
+the Space opens a URL itself.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+import pytest
+
+from src import config, schemas
+from src.direct_calls import DIRECT_CALLS, run
+from src.tu_client import ToolClient
+from tests.conftest import FakeRunner
+
+ROOT = Path(__file__).resolve().parent.parent
+
+
+def test_only_the_approved_direct_call_exists():
+    assert set(DIRECT_CALLS) == {"ctgov_data_timestamp"}
+
+
+@pytest.mark.parametrize("tool", sorted(DIRECT_CALLS))
+def test_direct_call_host_is_declared_for_its_source(tool):
+    call = DIRECT_CALLS[tool]
+    host = re.match(r"https://([^/]+)/", call.url).group(1)
+    assert host in config.source(call.source)["hosts"]
+    assert config.source_of(tool) == call.source
+
+
+@pytest.mark.parametrize("tool", sorted(DIRECT_CALLS))
+def test_direct_call_has_a_pinned_schema_and_is_not_a_tooluniverse_name(tool):
+    assert tool in schemas.pinned_tools()
+    assert tool not in config.allowed_tool_names()
+
+
+def test_direct_calls_take_no_arguments():
+    with pytest.raises(ValueError):
+        run("ctgov_data_timestamp", {"q": "x"}, timeout=1)
+
+
+def test_direct_call_goes_through_cache_and_schema(memory_cache, clock):
+    runner = FakeRunner(
+        {"ctgov_data_timestamp": {"status": "success", "data": {"dataTimestamp": "2026-11-12"}}}
+    )
+    client = ToolClient(
+        runner=runner, cache=memory_cache, clock=clock, tooluniverse_version="1.5.6"
+    )
+    first = client.call("ctgov_data_timestamp", {})
+    second = client.call("ctgov_data_timestamp", {})
+    assert (first.cache, second.cache) == ("miss", "hit")
+    assert first.source == "clinicaltrials"
+    assert len(runner.calls) == 1
+
+
+def test_no_other_module_opens_a_url_itself():
+    pattern = re.compile(
+        r"^\s*(import|from)\s+(urllib\.request|requests|httpx|http\.client)\b", re.MULTILINE
+    )
+    offenders = [
+        str(p.relative_to(ROOT))
+        for folder in ("src", "scripts")
+        for p in (ROOT / folder).rglob("*.py")
+        if pattern.search(p.read_text(encoding="utf-8"))
+    ]
+    offenders += [
+        p.name for p in ROOT.glob("*.py") if pattern.search(p.read_text(encoding="utf-8"))
+    ]
+    assert offenders == ["src/direct_calls.py"]

tests/test_output_schemas.py

@@ -110,9 +110,13 @@ def test_every_recorded_response_validates(scenario):
         schemas.validate(call["tool"], data)
 
 
-def test_every_pinned_schema_belongs_to_an_endpoint_tool():
-    assert schemas.pinned_tools() <= config.endpoint_tool_names()
+def test_every_pinned_schema_belongs_to_an_endpoint_tool_or_a_direct_call():
+    from src.direct_calls import DIRECT_CALLS
 
+    assert schemas.pinned_tools() <= config.endpoint_tool_names() | set(DIRECT_CALLS)
 
-def test_every_endpoint_tool_has_a_pinned_schema():
-    assert schemas.pinned_tools() == config.endpoint_tool_names()
+
+def test_every_endpoint_tool_and_direct_call_has_a_pinned_schema():
+    from src.direct_calls import DIRECT_CALLS
+
+    assert schemas.pinned_tools() == config.endpoint_tool_names() | set(DIRECT_CALLS)