graph-agents-cli 0.3.1__py3-none-any.whl

graph_agents_cli/scaffold/agents/langgraph/tests/unit/test_api_client.py

@@ -0,0 +1,1214 @@
+# Copyright 2026 graph-agents-cli contributors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Unit tests for the policy-enforcing API client (`app_utils.api_client`).
+
+No outside network: most requests go to an httpx MockTransport, the
+every-method tests to an HTTP server on 127.0.0.1 started by the test, and
+every refusal is checked to happen before anything is sent.
+"""
+
+from __future__ import annotations
+
+import importlib
+import json
+import os
+import pkgutil
+import threading
+from collections.abc import Iterator
+from dataclasses import dataclass, field
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from pathlib import Path
+from typing import Any
+
+import httpx
+import pytest
+import yaml
+
+from {{cookiecutter.agent_directory}}.app_utils import api_client
+from {{cookiecutter.agent_directory}}.app_utils.api_client import (
+    ApiCallError,
+    ApiPolicy,
+    ApiPolicyError,
+    Caller,
+    current_caller,
+    current_context,
+    current_run_id,
+    end_run,
+    get_client,
+    render_path,
+    require_direct_caller,
+    require_owner,
+    require_user_mentioned,
+    reset_limits,
+    reset_policy_cache,
+    set_outbound_headers,
+)
+from {{cookiecutter.agent_directory}}.app_utils.auth import caller_note_enabled, delegated_mentions
+from {{cookiecutter.agent_directory}}.app_utils.limits import SettingsError
+from {{cookiecutter.agent_directory}}.app_utils.telemetry import bind_log_context
+
+POLICY = """
+apis:
+  items:
+    base_url_env: ITEMS_API_BASE_URL
+    auth: bearer
+    token_env: ITEMS_API_TOKEN
+    allowed_methods: [GET]
+    allowed_operations:
+      - operationId: getItem
+        path: /items/{item_id}
+      - path: /sites/{site_id}/topology
+        methods: [GET]
+      - operationId: getSecret
+      - path: /listing
+    denied_operations:
+      - operationId: getSecret
+        path: /secret
+      - path: /items/admin
+    timeouts_ms: {connect: 1500, read: 2500}
+    pagination: {page_size_param: pageSize, max_page_size: 200}
+  directory:
+    base_url_env: DIRECTORY_API_BASE_URL
+    auth: forward
+    forward_header: X-User-Token
+    allowed_methods: ["*"]
+  public:
+    base_url_env: PUBLIC_API_BASE_URL
+    auth: none
+    allowed_methods: [GET, POST]
+  records:
+    base_url_env: RECORDS_API_BASE_URL
+    auth: none
+    allowed_methods: ["*"]
+    denied_operations:
+      - operationId: deleteRecord
+        methods: [DELETE]
+      - path: /admin/{section}
+      - operationId: dropTable
+        path: /tables/{table}
+        methods: [DELETE]
+    pagination: {page_size_param: limit, max_page_size: 50}
+  orders:
+    base_url_env: ORDERS_API_BASE_URL
+    auth: bearer
+    token_env: ORDERS_API_TOKEN
+    allowed_methods: [GET, HEAD, POST, PUT, PATCH, DELETE]
+    allowed_operations:
+      - {operationId: listOrders, path: /orders, methods: [GET, HEAD]}
+      - {operationId: createOrder, path: /orders, methods: [POST]}
+      - {operationId: replaceOrder, path: "/orders/{order_id}", methods: [PUT]}
+      - {operationId: updateOrder, path: "/orders/{order_id}", methods: [PATCH]}
+      - {operationId: cancelOrder, path: "/orders/{order_id}", methods: [DELETE]}
+    denied_operations:
+      - {operationId: purgeOrders, path: /orders, methods: [DELETE]}
+    limits: {max_calls_per_run: 3}
+  metered:
+    base_url_env: METERED_API_BASE_URL
+    auth: none
+    allowed_methods: [GET, POST]
+    limits: {rate_per_minute: 2}
+"""
+
+
+@dataclass
+class _Context:
+    principal_id: str = "u1"
+    attributes: dict[str, Any] = field(default_factory=dict)
+
+
+@pytest.fixture
+def policy_file(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> Path:
+    path = tmp_path / "api-policy.yaml"
+    path.write_text(POLICY, encoding="utf-8")
+    monkeypatch.setenv("API_POLICY_PATH", str(path))
+    monkeypatch.setenv("ITEMS_API_BASE_URL", "http://items.test")
+    monkeypatch.setenv("ITEMS_API_TOKEN", "tok")
+    monkeypatch.setenv("DIRECTORY_API_BASE_URL", "http://directory.test/api/v2/")
+    monkeypatch.setenv("PUBLIC_API_BASE_URL", "https://public.test")
+    monkeypatch.setenv("RECORDS_API_BASE_URL", "https://records.test")
+    monkeypatch.setenv("ORDERS_API_BASE_URL", "http://orders.test")
+    monkeypatch.setenv("ORDERS_API_TOKEN", "orders-token")
+    monkeypatch.setenv("METERED_API_BASE_URL", "http://metered.test")
+    reset_policy_cache()
+    reset_limits()
+    yield path
+    reset_policy_cache()
+    reset_limits()
+
+
+def _transport(calls: list[httpx.Request], status: int = 200, **extra: Any) -> httpx.MockTransport:
+    def handler(request: httpx.Request) -> httpx.Response:
+        calls.append(request)
+        return httpx.Response(status, json={"ok": True, "path": request.url.path}, **extra)
+
+    return httpx.MockTransport(handler)
+
+
+# --- fail closed: the policy file ----------------------------------------------
+
+
+def test_no_policy_file_refuses_every_client(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    monkeypatch.setenv("API_POLICY_PATH", str(tmp_path / "missing.yaml"))
+    reset_policy_cache()
+    with pytest.raises(ApiPolicyError, match="not found"):
+        get_client("anything")
+
+
+def test_undeclared_api_is_refused(policy_file: Path) -> None:
+    with pytest.raises(ApiPolicyError, match="not declared"):
+        get_client("billing")
+
+
+@pytest.mark.parametrize(
+    ("document", "fragment"),
+    [
+        ("product_api:\n  base_url_env: X\n", "retired single-API format"),
+        ("apis: {}\n", "non-empty mapping"),
+        ("apis:\n  a:\n    base_url_env: A\n    auth: none\n", "allowed_methods: required"),
+        (
+            "apis:\n  a:\n    base_url_env: A\n    auth: none\n    allowed_methods: [PUT]\n"
+            "    allowed_method: [POST]\n",
+            "unknown key 'allowed_method'",
+        ),
+        (
+            "apis:\n  a:\n    base_url_env: A\n    auth: bearer\n    allowed_methods: [POST]\n",
+            "token_env",
+        ),
+        (
+            "apis:\n  A:\n    base_url_env: A\n    auth: none\n    allowed_methods: [DELETE]\n",
+            "invalid API name",
+        ),
+        (
+            "apis:\n  a:\n    base_url_env: A\n    auth: none\n    allowed_methods: [PATCH]\n"
+            "    allowed_methods: ['*']\n",
+            "found duplicate key 'allowed_methods'",
+        ),
+        (
+            "apis:\n  a:\n    base_url_env: A\n    auth: none\n    allowed_methods: [POST]\n"
+            "    approval: required\n",
+            "approval: must be a mapping with required_for and approvers",
+        ),
+        (
+            "apis:\n  a:\n    base_url_env: A\n    auth: none\n    allowed_methods: [POST]\n"
+            "    approval: {required_for: {methods: [POST]}, approvers: [anyone]}\n",
+            "approval.approvers[0]: 'anyone' is not an approver",
+        ),
+        (
+            "apis:\n  a:\n    base_url_env: A\n    auth: none\n    allowed_methods: [POST]\n"
+            "    approval: []\n",
+            "approval: must not be empty",
+        ),
+        (
+            "apis:\n  a:\n    base_url_env: A\n    auth: none\n    allowed_methods: [POST]\n"
+            "    approval:\n      - {required_for: {methods: [POST]}, approvers: [requester]}\n"
+            "      - {required_for: {operations: [{operationId: x}]}}\n",
+            'approval[1].approvers: required (a list of "requester" and/or "role:<name>")',
+        ),
+        (
+            "apis:\n  a:\n    base_url_env: A\n    auth: none\n    allowed_methods: [POST]\n"
+            "    approval: {required_for: {methods: [POST]}, approvers: [requester], "
+            "timeout_s: 5}\n",
+            "approval.timeout_s: must be an integer from 30 to 86400",
+        ),
+        (
+            "apis:\n  a:\n    base_url_env: A\n    auth: none\n    allowed_methods: [POST]\n"
+            "    allowed_operations:\n      - operationId: createOrder\n        approval: true\n",
+            "not valid on an operation entry; gate the operation with "
+            "apis.a.approval.required_for.operations",
+        ),
+        (
+            "apis:\n  a:\n    base_url_env: A\n    auth: none\n    allowed_methods: [PUT]\n"
+            "    limits: {max_calls_per_run: 0}\n",
+            "limits.max_calls_per_run: must be an integer >= 1",
+        ),
+    ],
+)
+def test_invalid_policy_is_refused_with_the_schema_error(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch, document: str, fragment: str
+) -> None:
+    path = tmp_path / "api-policy.yaml"
+    path.write_text(document, encoding="utf-8")
+    monkeypatch.setenv("API_POLICY_PATH", str(path))
+    reset_policy_cache()
+    with pytest.raises(ApiPolicyError) as exc:
+        get_client("a")
+    assert fragment in str(exc.value)
+    assert exc.value.errors
+
+
+# --- the rules -------------------------------------------------------------------
+
+
+async def test_refusals_happen_before_sending(policy_file: Path) -> None:
+    calls: list[httpx.Request] = []
+    client = get_client("items", transport=_transport(calls))
+    with pytest.raises(ApiPolicyError, match="allowed_methods"):
+        await client.request("POST", "/items/1", operation_id="getItem")
+    with pytest.raises(ApiPolicyError, match="not in allowed_operations"):
+        await client.get("/users", operation_id="listUsers")
+    with pytest.raises(ApiPolicyError, match="denied"):
+        await client.get("/secret", operation_id="getSecret")
+    # AND: the operationId matches but the pinned path does not.
+    with pytest.raises(ApiPolicyError, match="not in allowed_operations"):
+        await client.get("/admin", operation_id="getItem")
+    # A denial on the rendered path is enforced even when the template is allowed.
+    with pytest.raises(ApiPolicyError, match="denied"):
+        await client.get(
+            "/items/{item_id}", operation_id="getItem", path_params={"item_id": "admin"}
+        )
+    assert calls == []
+
+
+async def test_allowed_call_is_sent_with_the_bearer_token(policy_file: Path) -> None:
+    calls: list[httpx.Request] = []
+    client = get_client("items", transport=_transport(calls))
+    data = await client.get(
+        "/items/{item_id}", operation_id="getItem", path_params={"item_id": "42"}
+    )
+    assert data == {"ok": True, "path": "/items/42"}
+    await client.get("/sites/7/topology")
+    # The policy's credential wins over a caller-supplied header.
+    await client.get("/listing", headers={"Authorization": "Bearer forged"})
+    assert [c.headers["authorization"] for c in calls] == ["Bearer tok"] * 3
+    assert str(calls[0].url) == "http://items.test/items/42"
+    assert calls[0].extensions["timeout"]["connect"] == 1.5
+
+
+TRACEPARENT = "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01"
+CORRELATION_HEADERS = ("x-request-id", "traceparent", "tracestate")
+
+
+def _forwarding_caller() -> _Context:
+    return _Context(attributes={"credentials": {"directory": "user-token-1"}})
+
+
+async def test_correlation_headers_are_sent_but_not_bound_by_an_approval(
+    policy_file: Path,
+) -> None:
+    calls: list[httpx.Request] = []
+    set_outbound_headers(
+        lambda: {"X-Request-ID": "req-1", "traceparent": TRACEPARENT, "Host": "elsewhere.test"}
+    )
+    try:
+        client = get_client("directory", context=_forwarding_caller(), transport=_transport(calls))
+        await client.get("/listing")
+        await client.get("/listing", headers={"X-Request-ID": "tool-own"})
+        prepared = client._prepare("GET", "/listing", None, None, None, None, {"X-Tool": "t"})
+    finally:
+        set_outbound_headers(None)
+    assert calls[0].headers["x-request-id"] == "req-1"
+    assert calls[0].headers["traceparent"] == TRACEPARENT
+    # A header a tool may not set is never added.
+    assert calls[0].headers["host"] == "directory.test"
+    assert calls[1].headers["x-request-id"] == "tool-own"  # the tool's own header wins
+    # They differ per request, so the request an approval binds leaves them out.
+    assert prepared.tool_headers == [("x-tool", "t")]
+    assert prepared.headers["traceparent"] == TRACEPARENT
+
+
+async def test_correlation_headers_go_only_to_forward_apis(policy_file: Path) -> None:
+    """The request id and trace context reach the APIs that act for the caller (another
+    agent, reached with the caller's credential), never a third party's bearer or open API."""
+    calls: list[httpx.Request] = []
+    set_outbound_headers(
+        lambda: {"X-Request-ID": "req-1", "traceparent": TRACEPARENT, "tracestate": "k=v"}
+    )
+    try:
+        await get_client("items", transport=_transport(calls)).get("/listing")
+        await get_client("public", transport=_transport(calls)).post("/search", json_body={})
+        forward = get_client("directory", context=_forwarding_caller(), transport=_transport(calls))
+        await forward.get("/me")
+        # A tool may still send its own header to any API: that is the tool's choice.
+        await get_client("items", transport=_transport(calls)).get(
+            "/listing", headers={"X-Request-ID": "tool-own"}
+        )
+    finally:
+        set_outbound_headers(None)
+    bearer, open_api, peer, own = calls
+    for third_party in (bearer, open_api):
+        assert not [h for h in CORRELATION_HEADERS if h in third_party.headers]
+    assert bearer.headers["authorization"] == "Bearer tok"
+    assert peer.headers["x-user-token"] == "user-token-1"
+    assert (peer.headers["x-request-id"], peer.headers["traceparent"]) == ("req-1", TRACEPARENT)
+    assert peer.headers["tracestate"] == "k=v"
+    assert own.headers["x-request-id"] == "tool-own" and "traceparent" not in own.headers
+    modes = ("forward", "exchange", "bearer", "none")
+    assert [api_client.propagates({"auth": mode}) for mode in modes] == [True, True, False, False]
+
+
+async def test_a_failing_correlation_provider_does_not_stop_the_call(policy_file: Path) -> None:
+    calls: list[httpx.Request] = []
+
+    def broken() -> dict[str, str]:
+        raise RuntimeError("no tracer")
+
+    set_outbound_headers(broken)
+    try:
+        client = get_client("directory", context=_forwarding_caller(), transport=_transport(calls))
+        await client.get("/me")
+    finally:
+        set_outbound_headers(None)
+    assert len(calls) == 1 and "x-request-id" not in calls[0].headers
+
+
+async def test_bearer_without_a_token_sends_nothing(
+    policy_file: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    monkeypatch.delenv("ITEMS_API_TOKEN")
+    calls: list[httpx.Request] = []
+    client = get_client("items", transport=_transport(calls))
+    with pytest.raises(ApiCallError, match="ITEMS_API_TOKEN"):
+        await client.get("/listing")
+    assert calls == []
+
+
+async def test_forward_sends_the_callers_credential_under_a_path_prefix(policy_file: Path) -> None:
+    calls: list[httpx.Request] = []
+    context = _Context(attributes={"credentials": {"directory": "user-token-1"}, "tenant": "t"})
+    client = get_client("directory", context=context, transport=_transport(calls))
+    await client.request("DELETE", "/people/{person_id}", path_params={"person_id": "p 1"})
+    assert calls[0].headers["x-user-token"] == "user-token-1"
+    assert "authorization" not in calls[0].headers
+    # The base URL's /api/v2 prefix is kept: the path is joined under it.
+    assert calls[0].url.raw_path == b"/api/v2/people/p%201"
+    # A mapping context (what LangGraph Server passes) works too.
+    other = get_client(
+        "directory",
+        context={"attributes": {"credentials": {"directory": "user-token-2"}}},
+        transport=_transport(calls),
+    )
+    await other.get("/me")
+    assert calls[1].headers["x-user-token"] == "user-token-2"
+
+
+async def test_forward_without_a_credential_sends_nothing(policy_file: Path) -> None:
+    calls: list[httpx.Request] = []
+    for context in (None, _Context(), _Context(attributes={"credentials": {"items": "x"}})):
+        client = get_client("directory", context=context, transport=_transport(calls))
+        with pytest.raises(ApiCallError, match="no credential"):
+            await client.get("/me")
+    assert calls == []
+
+
+async def test_auth_none_sends_no_credential(policy_file: Path) -> None:
+    calls: list[httpx.Request] = []
+    client = get_client("public", transport=_transport(calls))
+    await client.request("POST", "/search", json_body={"q": "x"})
+    assert "authorization" not in calls[0].headers
+    assert str(calls[0].url) == "https://public.test/search"
+
+
+@pytest.mark.parametrize(
+    "item_id",
+    [
+        "1/../../admin",
+        "../admin",
+        "..",
+        ".",
+        "1/extra",
+        "a/b",
+        "a\\b",
+        "",
+        " 1",
+        "1;x",
+        "1\x00",  # servers that end a path at a NUL route it to /items/1
+        "1\n2",
+    ],
+)
+async def test_path_params_refuse_traversal_before_sending(policy_file: Path, item_id: str) -> None:
+    calls: list[httpx.Request] = []
+    client = get_client("items", transport=_transport(calls))
+    with pytest.raises(ApiPolicyError):
+        await client.get(
+            "/items/{item_id}", operation_id="getItem", path_params={"item_id": item_id}
+        )
+    assert calls == []
+
+
+@pytest.mark.parametrize(
+    "path",
+    [
+        "/items/1/../../admin",
+        "/items/..",
+        "/items/%2e%2e",
+        "/items/1%2F..%2F..%2Fadmin",
+        "/items//1",
+        "/admin",
+        # Path parameters: servers that strip them route these to /items/1.
+        "/items/1;jsessionid=x",
+        "/items/1%3B",
+        "/items/1%3bx",
+        # Servers that trim segments, or end a path at a NUL, route these to /items/1.
+        "/items/1%20",
+        "/items/%201",
+        "/items/1%09",
+        "/items/1 ",
+        "/items/1%00",
+        "/items/1%00/x",
+        "/items/1%7F",
+        # Servers that trim the name before a format suffix, or strip trailing dots and
+        # spaces, route these to /items/1 as well.
+        "/items/1%20.json",
+        "/items/1%20%2e",
+        "/items/1.%20json",
+    ],
+)
+async def test_concrete_paths_are_validated(policy_file: Path, path: str) -> None:
+    calls: list[httpx.Request] = []
+    client = get_client("items", transport=_transport(calls))
+    with pytest.raises(ApiPolicyError):
+        await client.get(path, operation_id="getItem")
+    assert calls == []
+
+
+async def test_whitespace_inside_a_segment_is_sent(policy_file: Path) -> None:
+    calls: list[httpx.Request] = []
+    client = get_client("items", transport=_transport(calls))
+    await client.get("/items/red%20shirt", operation_id="getItem")
+    await client.get("/items/{item_id}", operation_id="getItem", path_params={"item_id": "a b"})
+    assert [c.url.raw_path for c in calls] == [b"/items/red%20shirt", b"/items/a%20b"]
+
+
+async def test_an_operation_id_denial_refuses_calls_that_do_not_name_one(policy_file: Path) -> None:
+    calls: list[httpx.Request] = []
+    client = get_client("records", transport=_transport(calls))
+    # Without an operation id the call cannot be told apart from deleteRecord.
+    with pytest.raises(ApiPolicyError, match="names no operation_id"):
+        await client.request("DELETE", "/records/{record_id}", path_params={"record_id": "1"})
+    with pytest.raises(ApiPolicyError, match="denied"):
+        await client.request(
+            "DELETE",
+            "/records/{record_id}",
+            operation_id="deleteRecord",
+            path_params={"record_id": "1"},
+        )
+    assert calls == []
+    await client.request(
+        "DELETE",
+        "/records/{record_id}",
+        operation_id="archiveRecord",
+        path_params={"record_id": "1"},
+    )
+    await client.get("/records/1")  # the denial pins DELETE
+    assert [(c.method, c.url.path) for c in calls] == [
+        ("DELETE", "/records/1"),
+        ("GET", "/records/1"),
+    ]
+
+
+@pytest.mark.parametrize("label", ["dropTable", "archiveTable", "dropTabel", None])
+async def test_a_denial_pinning_a_path_refuses_the_call_whatever_its_label(
+    policy_file: Path, label: str | None
+) -> None:
+    """The operation id is the tool's label: a relabelled call to a denied endpoint is refused."""
+    calls: list[httpx.Request] = []
+    client = get_client("records", transport=_transport(calls))
+    with pytest.raises(ApiPolicyError, match="denied"):
+        await client.request(
+            "DELETE", "/tables/{table}", operation_id=label, path_params={"table": "t1"}
+        )
+    with pytest.raises(ApiPolicyError, match="denied"):
+        await client.delete("/TABLES/t1/", operation_id=label)
+    assert calls == []
+    await client.get("/tables/t1", operation_id=label)  # the denial pins DELETE
+    assert [(c.method, c.url.path) for c in calls] == [("GET", "/tables/t1")]
+
+
+@pytest.mark.parametrize("path", ["/admin/1", "/admin/1/", "/ADMIN/1", "/%61dmin/1", "/Admin/%31"])
+async def test_path_denials_cover_equivalent_spellings(policy_file: Path, path: str) -> None:
+    calls: list[httpx.Request] = []
+    client = get_client("records", transport=_transport(calls))
+    with pytest.raises(ApiPolicyError, match="denied"):
+        await client.get(path, operation_id="getAdmin")
+    assert calls == []
+
+
+def test_path_rendering_encodes_each_value_as_one_segment() -> None:
+    assert render_path("/sites/{site_id}/topology", {"site_id": "x y"}) == "/sites/x%20y/topology"
+    assert render_path("/items/{item_id}", {"item_id": "a?b=1#f"}) == "/items/a%3Fb%3D1%23f"
+    with pytest.raises(ApiPolicyError, match="no parameter"):
+        render_path("/items/{item_id}", {"item_id": "1", "other": "2"})
+    with pytest.raises(ApiPolicyError, match="needs value"):
+        render_path("/items/{item_id}", {})
+
+
+@pytest.mark.parametrize(
+    ("value", "allowed"), [(50, True), ("200", True), (201, False), (0, False), ("many", False)]
+)
+async def test_page_size_is_capped(policy_file: Path, value: Any, allowed: bool) -> None:
+    calls: list[httpx.Request] = []
+    client = get_client("items", transport=_transport(calls))
+    if allowed:
+        await client.get("/listing", params={"pageSize": value})
+        assert calls[0].url.params["pageSize"] == str(value)
+    else:
+        with pytest.raises(ApiPolicyError, match="max_page_size"):
+            await client.get("/listing", params={"pageSize": value})
+        assert calls == []
+
+
+@pytest.mark.parametrize(
+    "params",
+    [
+        [("limit", "5000")],
+        {"Limit": 5000},
+        "limit=5000",
+        [("limit", "10"), ("limit", "5000")],
+        {"LIMIT": "10", "limit": "51"},
+        {"limit": " 10"},
+        {"limit": "1e3"},
+        {"limit": "9" * 5000},
+    ],
+)
+async def test_page_size_cap_covers_every_spelling(policy_file: Path, params: Any) -> None:
+    calls: list[httpx.Request] = []
+    client = get_client("records", transport=_transport(calls))
+    with pytest.raises(ApiPolicyError, match="max_page_size"):
+        await client.get("/records", params=params)
+    assert calls == []
+
+
+async def test_the_checked_query_is_the_one_sent(policy_file: Path) -> None:
+    calls: list[httpx.Request] = []
+    client = get_client("records", transport=_transport(calls))
+    await client.get("/records", params=[("limit", "20"), ("tag", "a"), ("tag", "b")])
+    assert calls[0].url.params.multi_items() == [("limit", "20"), ("tag", "a"), ("tag", "b")]
+
+
+async def test_redirects_and_errors_are_not_followed(policy_file: Path) -> None:
+    calls: list[httpx.Request] = []
+    moved = _transport(calls, status=302, headers={"location": "http://elsewhere.test/admin"})
+    with pytest.raises(ApiCallError, match="HTTP 302"):
+        await get_client("items", transport=moved).get("/listing")
+    with pytest.raises(ApiCallError, match="HTTP 500"):
+        await get_client("items", transport=_transport(calls, status=500)).get("/listing")
+    assert [c.url.host for c in calls] == ["items.test", "items.test"]
+
+
+async def test_missing_base_url_is_a_call_error(
+    policy_file: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    monkeypatch.delenv("PUBLIC_API_BASE_URL")
+    with pytest.raises(ApiCallError, match="PUBLIC_API_BASE_URL"):
+        await get_client("public", transport=_transport([])).get("/x")
+
+
+def test_current_context_outside_a_run_is_none() -> None:
+    assert current_context() is None
+
+
+# --- approval gates -------------------------------------------------------------
+
+GATED_POLICY = """
+apis:
+  shop:
+    base_url_env: SHOP_API_BASE_URL
+    auth: none
+    allowed_methods: [GET, POST, PATCH]
+    denied_operations:
+      - {path: "/orders/{order_id}/purge", methods: [POST]}
+    approval:
+      required_for:
+        methods: [PATCH]
+        operations:
+          - {operationId: cancelOrder, path: "/orders/{order_id}/cancel", methods: [POST]}
+          - {path: "/orders/{order_id}/purge"}
+      approvers: [requester, "role:ops"]
+      timeout_s: 60
+"""
+
+
+@pytest.fixture
+def gated_policy(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> Path:
+    path = tmp_path / "api-policy.yaml"
+    path.write_text(GATED_POLICY, encoding="utf-8")
+    monkeypatch.setenv("API_POLICY_PATH", str(path))
+    monkeypatch.setenv("SHOP_API_BASE_URL", "http://shop.test")
+    reset_policy_cache()
+    yield path
+    reset_policy_cache()
+
+
+def test_the_policy_names_gated_calls_and_their_approvers(gated_policy: Path) -> None:
+    policy = ApiPolicy.load(gated_policy)
+    gate = policy.gate("shop", "post", "cancelOrder", "/orders/7/cancel")
+    assert gate is not None
+    assert gate.approvers == ("requester", "role:ops") and gate.timeout_s == 60
+    # A path gate holds whatever label the call gives it.
+    assert policy.gate("shop", "POST", "archiveOrder", "/ORDERS/7/cancel/") is not None
+    assert policy.gate("shop", "PATCH", "updateOrder", "/orders/7").rule == (
+        "approval.required_for.methods ['PATCH']"
+    )
+    assert policy.gate("shop", "GET", "getOrder", "/orders/7") is None
+    assert policy.gate("shop", "POST", "createOrder", "/orders") is None
+
+
+def test_with_a_list_of_rules_the_first_that_covers_a_call_gates_it(
+    gated_policy: Path,
+) -> None:
+    """Other approvers for other calls of one API: the first covering rule in file order."""
+    gated_policy.write_text(
+        GATED_POLICY.split("    approval:")[0]
+        + "    approval:\n"
+        + "      - required_for:\n"
+        + "          operations:\n"
+        + '            - {operationId: cancelOrder, path: "/orders/{order_id}/cancel"}\n'
+        + "        approvers: [requester]\n"
+        + "      - required_for: {operations: [{operationId: createOrder, path: /orders}]}\n"
+        + '        approvers: ["role:admin"]\n'
+        + "        timeout_s: 3600\n"
+        + '      - {required_for: {methods: [POST, PATCH]}, approvers: ["role:ops"]}\n',
+        encoding="utf-8",
+    )
+    reset_policy_cache()
+    policy = ApiPolicy.load(gated_policy)
+    cancel = policy.gate("shop", "POST", "cancelOrder", "/orders/7/cancel")
+    assert (cancel.approvers, cancel.timeout_s, cancel.index, cancel.also) == (
+        ("requester",),
+        900,
+        0,
+        (2,),
+    )
+    create = policy.gate("shop", "POST", "placeOrder", "/orders")  # the path, whatever label
+    assert (create.approvers, create.timeout_s, create.index) == (("role:admin",), 3600, 1)
+    assert create.rule.startswith("approval[1].required_for.operations")
+    update = policy.gate("shop", "PATCH", "updateOrder", "/orders/7")
+    assert (update.approvers, update.index) == (("role:ops",), 2)
+    # The template it was rendered from counts too: the first rule covering either wins.
+    templated = policy.gate(
+        "shop", "POST", None, "/orders/7/x", template="/orders/{order_id}/cancel"
+    )
+    assert templated.index == 0
+    assert policy.gate("shop", "GET", "getOrder", "/orders/7") is None
+
+
+async def test_a_call_either_of_two_rules_with_other_approvers_may_gate_is_refused(
+    gated_policy: Path,
+) -> None:
+    """A rule by operationId alone cannot rule out a call that names no operation id.
+
+    When a later rule with other approvers also covers that call, it could be either
+    rule's: it is refused before anything is sent, instead of going to the first rule's
+    approvers (a requester approving what the later rule gives to role:admin).
+    """
+    gated_policy.write_text(
+        GATED_POLICY.split("    approval:")[0]
+        + "    approval:\n"
+        + "      - required_for: {operations: [{operationId: cancelOrder}]}\n"
+        + "        approvers: [requester]\n"
+        + '      - {required_for: {methods: [POST]}, approvers: ["role:admin"]}\n',
+        encoding="utf-8",
+    )
+    reset_policy_cache()
+    calls: list[httpx.Request] = []
+    client = get_client("shop", transport=_transport(calls))
+    with pytest.raises(ApiPolicyError) as exc:
+        await client.post("/orders", json_body={"sku": "A-1"})
+    assert "refused by the API policy" in str(exc.value)
+    assert "it could be either rule's call" in str(exc.value)
+    assert "name the operation_id on the call" in str(exc.value)
+    # Named, each call goes to its own rule's approvers (outside a run: refused as gated).
+    with pytest.raises(ApiPolicyError, match=r"needs human approval \(role:admin\)"):
+        await client.post("/orders", operation_id="createOrder", json_body={"sku": "A-1"})
+    with pytest.raises(ApiPolicyError, match=r"needs human approval \(requester\)"):
+        await client.post("/orders/7/cancel", operation_id="cancelOrder")
+    # No later rule with other approvers covers an unnamed PATCH: rule 0 gates it.
+    with pytest.raises(ApiPolicyError, match=r"needs human approval \(requester\)"):
+        await client.patch("/orders/7", json_body={"note": "x"})
+    assert calls == []
+
+
+async def test_a_gated_call_is_refused_before_sending(gated_policy: Path) -> None:
+    """Outside an agent run nothing can pause for a decision: a gated call fails closed.
+
+    (Inside a run it pauses for approval: see `test_approval_ledger.py`.)
+    """
+    calls: list[httpx.Request] = []
+    client = get_client("shop", transport=_transport(calls))
+    with pytest.raises(ApiPolicyError) as exc:
+        await client.post(
+            "/orders/{order_id}/cancel",
+            operation_id="cancelOrder",
+            path_params={"order_id": "7"},
+            json_body={"reason": "customer asked"},
+        )
+    assert "needs human approval (requester, role:ops)" in str(exc.value)
+    assert "nothing was sent" in str(exc.value)
+    with pytest.raises(ApiPolicyError, match="needs human approval"):
+        await client.patch("/orders/7", operation_id="updateOrder", json_body={"note": "x"})
+    # Relabelled: the gate on the path still holds.
+    with pytest.raises(ApiPolicyError, match="needs human approval"):
+        await client.post("/orders/7/cancel", operation_id="closeOrder")
+    assert calls == []
+    assert await client.get("/orders/7", operation_id="getOrder") == {
+        "ok": True,
+        "path": "/orders/7",
+    }
+    assert await client.post("/orders", operation_id="createOrder", json_body={}) == {
+        "ok": True,
+        "path": "/orders",
+    }
+    assert [(r.method, r.url.path) for r in calls] == [("GET", "/orders/7"), ("POST", "/orders")]
+
+
+@pytest.mark.parametrize(
+    "path",
+    [
+        # Format suffixes and a trailing dot on the gated (or denied) segment: servers
+        # that route `.json` or drop a trailing dot send these to the same endpoint.
+        "/orders/7/cancel.json",
+        "/orders/7/cancel.",
+        "/orders/7/cancel%2e",
+        "/orders/7/Cancel.JSON",
+    ],
+)
+async def test_a_dot_suffixed_spelling_of_a_gated_or_denied_path_is_covered(
+    gated_policy: Path, path: str
+) -> None:
+    calls: list[httpx.Request] = []
+    client = get_client("shop", transport=_transport(calls))
+    with pytest.raises(ApiPolicyError, match="needs human approval"):
+        await client.post(path, operation_id="closeOrder")
+    denied = path.replace("cancel", "purge").replace("Cancel", "Purge")
+    with pytest.raises(ApiPolicyError, match="denied by denied_operations"):
+        await client.post(denied, operation_id="purgeOrder")
+    assert calls == []
+
+
+@pytest.mark.parametrize(
+    "path",
+    [
+        # Whitespace next to a dot on the gated (or denied) segment: servers that trim the
+        # name before a format suffix, or strip trailing dots and spaces, send these to
+        # the bare segment, which the gate would not see in them: refused, not gated.
+        "/orders/7/cancel%20.json",
+        "/orders/7/cancel%20%2e",
+        "/orders/7/cancel%20%2E%2e",
+        "/orders/7/cancel.%20json",
+        "/orders/{order_id}/cancel%20.json",
+    ],
+)
+async def test_whitespace_next_to_a_dot_is_refused_before_sending(
+    gated_policy: Path, path: str
+) -> None:
+    calls: list[httpx.Request] = []
+    client = get_client("shop", transport=_transport(calls))
+    params = {"order_id": "7"} if "{" in path else None
+    for spelling in (path, path.replace("cancel", "purge")):
+        with pytest.raises(ApiPolicyError, match=r"whitespace next to a dot|not a valid"):
+            await client.post(spelling, operation_id="closeOrder", path_params=params)
+    # A path parameter value that would put it there is refused as well.
+    with pytest.raises(ApiPolicyError):
+        await client.post(
+            "/orders/{order_id}/cancel", operation_id="closeOrder", path_params={"order_id": "7 .x"}
+        )
+    assert calls == []
+
+
+async def test_approval_never_widens_access(gated_policy: Path) -> None:
+    """A gated call outside the policy is refused by the policy, not held for approval."""
+    calls: list[httpx.Request] = []
+    client = get_client("shop", transport=_transport(calls))
+    # Gated (the purge path) but denied: the denial wins.
+    with pytest.raises(ApiPolicyError) as denied:
+        await client.post("/orders/7/purge", operation_id="purgeOrder")
+    assert "denied by denied_operations" in str(denied.value)
+    assert "approval" not in str(denied.value)
+    # Gated (the purge path, every method) but DELETE is not allowed: allowed_methods refuses.
+    with pytest.raises(ApiPolicyError, match="not in allowed_methods"):
+        await client.delete("/orders/{order_id}/purge", path_params={"order_id": "7"})
+    assert calls == []
+
+
+# --- every method against a real server ------------------------------------------
+
+
+class _EchoHandler(BaseHTTPRequestHandler):
+    """Answers every method with what it received (204 and no body for DELETE)."""
+
+    def _answer(self) -> None:
+        length = int(self.headers.get("content-length") or 0)
+        raw = self.rfile.read(length) if length else b""
+        if self.command == "DELETE":
+            self.send_response(204)
+            self.end_headers()
+            return
+        payload = {
+            "method": self.command,
+            "path": self.path,
+            "body": json.loads(raw) if raw else None,
+            "authorization": self.headers.get("authorization"),
+            "x_request_tag": self.headers.get("x-request-tag"),
+            "content_type": self.headers.get("content-type"),
+        }
+        data = json.dumps(payload).encode()
+        self.send_response(200)
+        self.send_header("content-type", "application/json")
+        self.send_header("content-length", str(len(data)))
+        self.end_headers()
+        if self.command != "HEAD":
+            self.wfile.write(data)
+
+    do_GET = do_HEAD = do_POST = do_PUT = do_PATCH = do_DELETE = do_OPTIONS = _answer
+
+    def log_message(self, format: str, *args: Any) -> None:  # quiet test output
+        return
+
+
+@pytest.fixture
+def local_server(policy_file: Path, monkeypatch: pytest.MonkeyPatch) -> Iterator[str]:
+    server = ThreadingHTTPServer(("127.0.0.1", 0), _EchoHandler)
+    thread = threading.Thread(target=server.serve_forever, daemon=True)
+    thread.start()
+    base = f"http://127.0.0.1:{server.server_address[1]}/v1"
+    monkeypatch.setenv("ORDERS_API_BASE_URL", base)
+    try:
+        yield base
+    finally:
+        server.shutdown()
+        server.server_close()
+        thread.join(timeout=5)
+
+
+async def test_every_allowed_method_reaches_a_real_server(local_server: str) -> None:
+    client = get_client("orders", run_id="methods-1")
+    created = await client.post(
+        "/orders",
+        operation_id="createOrder",
+        json_body={"sku": "a-1", "quantity": 2},
+        params={"dry": "false"},
+        headers={"X-Request-Tag": "t1", "Authorization": "Bearer forged"},
+    )
+    assert created["method"] == "POST"
+    assert created["path"] == "/v1/orders?dry=false"
+    assert created["body"] == {"sku": "a-1", "quantity": 2}
+    assert created["content_type"] == "application/json"
+    assert created["x_request_tag"] == "t1"
+    assert created["authorization"] == "Bearer orders-token"  # the policy's token wins
+    replaced = await client.put(
+        "/orders/{order_id}",
+        operation_id="replaceOrder",
+        path_params={"order_id": "7"},
+        json_body={"sku": "b-2"},
+    )
+    assert (replaced["method"], replaced["path"], replaced["body"]) == (
+        "PUT",
+        "/v1/orders/7",
+        {"sku": "b-2"},
+    )
+    client = get_client("orders", run_id="methods-2")  # max_calls_per_run is 3
+    updated = await client.patch(
+        "/orders/{order_id}",
+        operation_id="updateOrder",
+        path_params={"order_id": "7"},
+        json_body={"quantity": 3},
+    )
+    assert (updated["method"], updated["body"]) == ("PATCH", {"quantity": 3})
+    cancelled = await client.delete(
+        "/orders/{order_id}", operation_id="cancelOrder", path_params={"order_id": "7"}
+    )
+    assert cancelled == ""  # 204, no body
+    assert await client.head("/orders", operation_id="listOrders") == ""
+
+
+async def test_a_denied_method_never_reaches_the_server(local_server: str) -> None:
+    client = get_client("orders", run_id="denied")
+    with pytest.raises(ApiPolicyError, match="denied"):
+        await client.delete("/orders", operation_id="purgeOrders")
+    with pytest.raises(ApiPolicyError, match="allowed_methods"):
+        await client.options("/orders", operation_id="listOrders")
+
+
+# --- limits ----------------------------------------------------------------------
+
+
+class _Clock:
+    def __init__(self) -> None:
+        self.now = 1000.0
+
+    def __call__(self) -> float:
+        return self.now
+
+
+async def test_max_calls_per_run_is_counted_per_run(policy_file: Path) -> None:
+    calls: list[httpx.Request] = []
+    run_a = get_client("orders", transport=_transport(calls), run_id="run-a")
+    for _ in range(3):
+        await run_a.get("/orders", operation_id="listOrders")
+    with pytest.raises(ApiPolicyError, match="max_calls_per_run"):
+        await run_a.get("/orders", operation_id="listOrders")
+    assert len(calls) == 3  # refused before sending
+    # Another run has its own count; a finished run's count is dropped.
+    run_b = get_client("orders", transport=_transport(calls), run_id="run-b")
+    await run_b.get("/orders", operation_id="listOrders")
+    end_run("run-a")
+    await run_a.get("/orders", operation_id="listOrders")
+    assert len(calls) == 5
+    # A refused call (outside the policy) does not use up the budget.
+    run_c = get_client("orders", transport=_transport(calls), run_id="run-c")
+    with pytest.raises(ApiPolicyError, match="not in allowed_operations"):
+        await run_c.get("/elsewhere", operation_id="other")
+    for _ in range(3):
+        await run_c.get("/orders", operation_id="listOrders")
+
+
+async def test_rate_per_minute_is_a_token_bucket(policy_file: Path) -> None:
+    clock = _Clock()
+    reset_limits(clock)
+    calls: list[httpx.Request] = []
+    client = get_client("metered", transport=_transport(calls))
+    await client.get("/a")
+    await client.post("/b")
+    with pytest.raises(ApiPolicyError, match="rate_per_minute"):
+        await client.get("/a")
+    assert len(calls) == 2
+    clock.now += 30  # half a minute refills one of the two tokens
+    await client.get("/a")
+    with pytest.raises(ApiPolicyError, match="rate_per_minute"):
+        await client.get("/a")
+    assert len(calls) == 3
+
+
+def test_run_counters_are_evicted_by_ttl_and_size(monkeypatch: pytest.MonkeyPatch) -> None:
+    clock = _Clock()
+    limiter = reset_limits(clock)
+    limits = {"max_calls_per_run": 1}
+    assert limiter.acquire("a", limits, "old") is None
+    clock.now += api_client.RUN_COUNTER_TTL_S + 1
+    assert limiter.acquire("a", limits, "new") is None
+    assert limiter.tracked_runs() == 1  # "old" went after the TTL
+    assert limiter.acquire("a", limits, "old") is None  # a fresh count
+    monkeypatch.setattr(api_client, "MAX_TRACKED_RUNS", 2)
+    for run in ("r1", "r2", "r3"):
+        assert limiter.acquire("a", limits, run) is None
+    assert limiter.tracked_runs() == 2
+
+
+async def test_the_run_id_comes_from_the_graph_run_then_the_request() -> None:
+    from typing import TypedDict
+
+    from langgraph.graph import END, START, StateGraph
+
+    class State(TypedDict):
+        seen: str
+
+    def node(state: State) -> dict[str, str]:
+        return {"seen": current_run_id() or ""}
+
+    builder = StateGraph(State)
+    builder.add_node("n", node)
+    builder.add_edge(START, "n")
+    builder.add_edge("n", END)
+    graph = builder.compile()
+    result = await graph.ainvoke({"seen": ""}, config={"metadata": {"run_id": "run-42"}})
+    assert result["seen"] == "run-42"
+    assert current_run_id() is None
+    bind_log_context(request_id="req-1")
+    try:
+        assert current_run_id() == "req-1"
+        bind_log_context(run_id="run-7")
+        assert current_run_id() == "run-7"
+    finally:
+        bind_log_context(request_id=None, run_id=None)
+
+
+# --- the project's own tools and policy ----------------------------------------
+
+
+def _project_policy() -> ApiPolicy | None:
+    path = Path(api_client.__file__).resolve().parents[2] / "api-policy.yaml"
+    return ApiPolicy.load(path) if path.is_file() else None
+
+
+def _tool_modules(package: Any) -> list[str]:
+    """Every module under the tools package, subpackages included (what lint reads).
+
+    `*.py` files anywhere below the package (hidden and cache directories
+    skipped, symlinked directories followed once), a subpackage's own
+    `__init__.py` included; the package's top-level `__init__.py` is the registry.
+    """
+    root = Path(package.__file__).resolve().parent
+    names: list[str] = []
+    seen: set[str] = set()
+    for directory, dirs, files in os.walk(root, followlinks=True):
+        real = os.path.realpath(directory)
+        if real in seen:
+            dirs[:] = []
+            continue
+        seen.add(real)
+        dirs[:] = sorted(d for d in dirs if not d.startswith(".") and d != "__pycache__")
+        relative = Path(directory).relative_to(root)
+        for filename in sorted(files):
+            if not filename.endswith(".py") or (not relative.parts and filename == "__init__.py"):
+                continue
+            parts = [*relative.parts] + ([] if filename == "__init__.py" else [filename[:-3]])
+            names.append(".".join([package.__name__, *parts]))
+    return sorted(names)
+
+
+def test_every_tool_declares_calls_its_policy_allows() -> None:
+    """Every `API_CALLS` entry names a declared API and passes its rules (what lint checks).
+
+    Tool subpackages count: lint reads every module below `tools/`, and so does this test.
+    """
+    import {{cookiecutter.agent_directory}}.tools as tools
+
+    policy = _project_policy()
+    modules = _tool_modules(tools)
+    # At least every module and subpackage `get_tools()` imports.
+    depth = len(tools.__name__.split("."))
+    walked = {name.split(".")[depth] for name in modules}
+    assert {info.name for info in pkgutil.iter_modules(tools.__path__)} <= walked
+    for name in modules:
+        module = importlib.import_module(name)
+        for call in getattr(module, "API_CALLS", []):
+            assert policy is not None, f"{name} declares API calls but there is no api-policy.yaml"
+            policy.check(call["api"], call["method"], call.get("operation_id"), call.get("path"))
+
+
+def test_the_tool_module_walk_covers_subpackages(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """The walk above reaches nested modules and subpackage `__init__`s, like lint."""
+    package = tmp_path / "walked_tools"
+    (package / "nested" / "deeper").mkdir(parents=True)
+    (package / "__pycache__").mkdir()
+    (package / ".hidden").mkdir()
+    for relative in (
+        "__init__.py",
+        "top.py",
+        "nested/__init__.py",
+        "nested/inner.py",
+        "nested/deeper/leaf.py",
+        "__pycache__/cached.py",
+        ".hidden/secret.py",
+    ):
+        (package / relative).write_text("API_CALLS = []\n", encoding="utf-8")
+    monkeypatch.syspath_prepend(str(tmp_path))
+    walked = importlib.import_module("walked_tools")
+    assert _tool_modules(walked) == [
+        "walked_tools.nested",
+        "walked_tools.nested.deeper.leaf",
+        "walked_tools.nested.inner",
+        "walked_tools.top",
+    ]
+
+
+def test_the_project_policy_is_valid() -> None:
+    policy = _project_policy()
+    if policy is None:
+        pytest.skip("this project declares no api-policy.yaml")
+    assert policy.apis
+    assert yaml.safe_load(policy.source.read_text(encoding="utf-8"))["apis"]
+
+
+# --- the caller when another agent asks for the user (0.3) ----------------------------------
+
+_CONCIERGE = {"id": "concierge", "chain": ["concierge", "web-agent"], "client": "concierge"}
+
+
+@dataclass
+class _AgentRun:
+    """A tool's runtime: the run context and the thread state."""
+
+    context: Any
+    state: dict[str, Any]
+
+
+def _context(*, actor: dict[str, Any] | None = None, origin: str | None = None) -> dict[str, Any]:
+    attributes: dict[str, Any] = {}
+    if actor is not None:
+        attributes["@actor"] = actor
+    if origin is not None:
+        attributes["credentials"] = {"@origin": {"text": origin, "truncated": False, "hops": 1}}
+    return {"principal_id": "alice", "roles": [], "attributes": attributes}
+
+
+def _asked(text: str, **context: Any) -> _AgentRun:
+    return _AgentRun(
+        context=_context(**context), state={"messages": [{"type": "human", "content": text}]}
+    )
+
+
+def test_caller_fields() -> None:
+    direct = current_caller(_context())
+    assert (direct.actor, direct.actor_chain, direct.delegated) == (None, (), False)
+    agent = current_caller(_context(actor=_CONCIERGE))
+    assert agent.principal_id == "alice" and agent.delegated
+    assert (agent.actor, agent.actor_chain) == ("concierge", ("concierge", "web-agent"))
+    assert current_caller(_context(actor={"id": "billing"})).actor_chain == ("billing",)
+    assert Caller("bob", frozenset()).actor is None  # the 0.2 constructor still works
+
+
+def test_require_direct_caller() -> None:
+    assert require_direct_caller(_context()).principal_id == "alice"
+    with pytest.raises(ApiPolicyError, match="not agent 'concierge' acting for them"):
+        require_direct_caller(_context(actor=_CONCIERGE))
+    # require_owner still compares the subject: the record is the user's.
+    assert require_owner("alice", context=_context(actor=_CONCIERGE)).actor == "concierge"
+
+
+def test_require_user_mentioned_delegated_uses_origin(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.delenv("A2A_DELEGATED_MENTIONS", raising=False)
+    # The user named it, and the agent's request names it: allowed.
+    require_user_mentioned(
+        "ORD-1002", _asked("Cancel ORD-1002", actor=_CONCIERGE, origin="cancel order ORD-1002")
+    )
+    # Only the agent's request names it (an instruction planted in data it read): refused.
+    with pytest.raises(ApiPolicyError, match="not named in the user's own words"):
+        require_user_mentioned(
+            "ORD-1017", _asked("Cancel ORD-1017", actor=_CONCIERGE, origin="cancel ORD-1002")
+        )
+    # The user named it, the agent's request does not: refused as before.
+    with pytest.raises(ApiPolicyError, match="not named in the user's latest message"):
+        require_user_mentioned(
+            "ORD-1002", _asked("Cancel it", actor=_CONCIERGE, origin="cancel ORD-1002")
+        )
+    # No forwarded words: refused, naming the agent.
+    with pytest.raises(ApiPolicyError) as refused:
+        require_user_mentioned("ORD-1002", _asked("Cancel ORD-1002", actor=_CONCIERGE))
+    assert str(refused.value) == (
+        "refused: 'ORD-1002' was asked for by agent 'concierge', which forwarded no user "
+        "message to check it against; the user must name it."
+    )
+    # A direct caller: the user's latest message, as in 0.2 (forwarded words are not read).
+    require_user_mentioned("ORD-1002", _asked("Cancel ORD-1002", origin="nothing"))
+
+
+def test_require_user_mentioned_refuse_and_request_modes(monkeypatch: pytest.MonkeyPatch) -> None:
+    run = _asked("Cancel ORD-1002", actor=_CONCIERGE, origin="cancel ORD-1002")
+    monkeypatch.setenv("A2A_DELEGATED_MENTIONS", "refuse")
+    with pytest.raises(ApiPolicyError, match="the user must ask this agent directly"):
+        require_user_mentioned("ORD-1002", run)
+    require_user_mentioned("ORD-1002", _asked("Cancel ORD-1002"))  # a direct caller
+    monkeypatch.setenv("A2A_DELEGATED_MENTIONS", "request")
+    require_user_mentioned("ORD-1017", _asked("Cancel ORD-1017", actor=_CONCIERGE))
+    # A bad value (the startup check refuses it) fails closed: refused.
+    monkeypatch.setenv("A2A_DELEGATED_MENTIONS", "sometimes")
+    with pytest.raises(ApiPolicyError, match="the user must ask this agent directly"):
+        require_user_mentioned("ORD-1002", run)
+
+
+def test_the_delegated_prompt_settings_are_checked() -> None:
+    assert delegated_mentions({}) == "origin"
+    assert delegated_mentions({"A2A_DELEGATED_MENTIONS": "Request"}) == "request"
+    assert caller_note_enabled({}) is True
+    assert caller_note_enabled({"A2A_CALLER_NOTE": "off"}) is False
+    with pytest.raises(SettingsError, match="A2A_DELEGATED_MENTIONS"):
+        delegated_mentions({"A2A_DELEGATED_MENTIONS": "any"})
+    with pytest.raises(SettingsError, match="A2A_CALLER_NOTE"):
+        caller_note_enabled({"A2A_CALLER_NOTE": "false"})