ms-tau-sdk 2.0.15.dev62__tar.gz → 2.0.16.dev64__tar.gz

{ms_tau_sdk-2.0.15.dev62 → ms_tau_sdk-2.0.16.dev64}/CHANGELOG.md

@@ -2,6 +2,36 @@
 
 ## Unreleased
 
+- **The Tau skills say when and how a tool checks the person's teams
+  ([#103](https://github.com/mainsequence-sdk/ms-tau-sdk/issues/103)).** `tau_security_and_access`
+  has a section "Checking the person's teams". A delegated call already reaches what the person's
+  teams share, so a tool rarely checks teams itself; a tool whose own policy names teams asks with
+  `in_teams()`. That answers only while the person is the request's verified caller, and an error
+  is never a membership answer. `tau_project_customization` points to the section.
+
+## 2.0.15 — 2026-10-15
+
+- **Team membership on demand; the caller assertion's team list is deprecated
+  ([#103](https://github.com/mainsequence-sdk/ms-tau-sdk/issues/103), ADR 0019).** A caller
+  assertion named every team of its caller, so it grew with the Organization, and an Organization
+  admin is a member of every team. The platform is replacing that list with a membership check,
+  and the runtime now asks it instead of reading the list:
+  - the verifier accepts a caller assertion with or without `team_uids`. A list that is present is
+    still checked, and `null` or any other claim is refused;
+  - `await in_teams(team_uids, *, max_age_seconds=None)` on the verified caller
+    (`request.state.user`, `current_caller()`) returns which of the given teams the person belongs
+    to, as a `frozenset`. It asks the platform with the runtime's credential and the request's
+    assertion, in calls of at most 100 teams. A turn's requester has the same method while it is
+    the verified caller of the request, and raises otherwise;
+  - `TAU_TEAM_MEMBERSHIP_CACHE_SECONDS` (`TauSDKSettings.team_membership_cache_seconds`, default
+    `0`) sets how long an answer is reused across requests. Within a request the same question is
+    asked once, and `max_age_seconds=0` always asks and stores the new answer. Answers are keyed by
+    release, Organization Environment, person and team, at most 10,000 per process. A failed call
+    raises; it never answers "not a member";
+  - `team_uids` on the verified caller and on the requester is deprecated and warns when read. It
+    raises when the assertion carried no list. `signed_team_uids` holds the list, or `None`, and is
+    the name `dataclasses.asdict()` and the repr show.
+
 - **Tau reads skills nested in folders
   ([#99](https://github.com/mainsequence-sdk/ms-tau-sdk/issues/99)).** Tau read only the skill
   folders directly in `.tau/skills` and `.agents/skills`, so a skill one folder deeper, such as

{ms_tau_sdk-2.0.15.dev62 → ms_tau_sdk-2.0.16.dev64}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ms-tau-sdk
-Version: 2.0.15.dev62
+Version: 2.0.16.dev64
 Summary: Workspace-bound Tau application primitives for Main Sequence projects
 Project-URL: Changelog, https://github.com/mainsequence-sdk/ms-tau-sdk/blob/development/CHANGELOG.md
 Project-URL: Documentation, https://github.com/mainsequence-sdk/ms-tau-sdk/tree/development/docs

{ms_tau_sdk-2.0.15.dev62 → ms_tau_sdk-2.0.16.dev64}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "ms-tau-sdk"
-version = "2.0.15.dev62"
+version = "2.0.16.dev64"
 description = "Workspace-bound Tau application primitives for Main Sequence projects"
 readme = "README.md"
 requires-python = ">=3.13"

{ms_tau_sdk-2.0.15.dev62 → ms_tau_sdk-2.0.16.dev64}/src/ms_tau_sdk/agent_skills/tau_project_customization/SKILL.md

@@ -158,10 +158,13 @@ async def revenue_by_region(tool_call_id, arguments, signal=None, on_update=None
     return AgentToolResult(content=[TextContent(text=json.dumps(answer.json()["rows"]))])
 ```
 
-- `current_requester()` returns the person the turn serves, with `uid` and `team_uids`, or
-  `None`. The platform names that person when the turn starts, whoever called; it is `None` when
-  the platform names nobody, in local mode, and in code outside a turn. Only it names the
-  requester: never take a person's UID from tool arguments, the prompt, history, or a header.
+- `current_requester()` returns the person the turn serves, with `uid` and
+  `await in_teams(team_uids, *, max_age_seconds=None)`, or `None`. `in_teams()` answers while the
+  person is the verified caller of the turn's request (see `tau_security_and_access`, "Checking the
+  person's teams"); `team_uids` is deprecated. The platform names that person when the turn
+  starts, whoever called; it is `None` when the platform names nobody, in local mode, and in code
+  outside a turn. Only it names the requester: never take a person's UID from tool arguments, the
+  prompt, history, or a header.
 - `platform_client()` returns a client. `await client.request("GET", "/api/v1/...")` calls a
   platform API path, and `await client.call_release(release_uid, method, path, ...)` calls another
   platform application. Both return an `httpx.Response`.

{ms_tau_sdk-2.0.15.dev62 → ms_tau_sdk-2.0.16.dev64}/src/ms_tau_sdk/agent_skills/tau_security_and_access/SKILL.md

@@ -207,6 +207,33 @@ How sharing works:
   tool can use them when its design needs to, for example to refuse a team key where it expects a
   personal one. That is a choice of the tool, not a platform rule.
 
+## Checking the person's teams
+
+A delegated call already reaches exactly what the person can, including what is shared with their
+teams, so a tool rarely checks teams itself. When the tool's own policy names teams, ask the
+platform with `in_teams()`:
+
+```python
+person = current_requester()
+if person is None or REPORTS_TEAM_UID not in await person.in_teams([REPORTS_TEAM_UID]):
+    return AgentToolResult(content=[TextContent(text="These reports are for the team's members.")])
+```
+
+- `await in_teams(team_uids, *, max_age_seconds=None)` returns the subset of `team_uids` the
+  person is an active member of, as a `frozenset`. Unknown and inactive teams are left out.
+- On the turn's requester it answers only while that person is the verified caller of the request
+  the turn runs in, such as a chat or A2A Message they sent. A turn with no such request raises
+  `TauSDKError`: a Task attempt the platform dispatches, a turn that resumes a caller delivery, or
+  work another Agent asked for. Refuse the action then; never read the error as a membership
+  answer. An HTTP handler asks for its caller with `await request.state.user.in_teams(...)`.
+- The process reuses an answer across requests for `TAU_TEAM_MEMBERSHIP_CACHE_SECONDS` (default
+  `0`: only within its request); set it in `harness_agent.spec.env_vars`. `max_age_seconds=0`
+  always asks the platform: use it before a write that must see a removal at once.
+- A check the platform cannot answer raises `BackendError`; it never answers "not a member".
+- `team_uids` on the requester is deprecated and warns when read. It is empty when the turn does
+  not know the person's teams, and raises when the caller's assertion carried no team list, as
+  every assertion will once the platform stops signing them. Use `in_teams()`.
+
 ## What never reaches the model
 
 Tool results, their `details`, and errors can reach the model provider and the session history.

{ms_tau_sdk-2.0.15.dev62 → ms_tau_sdk-2.0.16.dev64}/src/ms_tau_sdk/api/request_identity.py

@@ -41,6 +41,12 @@ from ms_tau_sdk.backend.assertions import (
 )
 from ms_tau_sdk.backend.client import MainSequenceClient
 from ms_tau_sdk.backend.models import AgentSession, DirectoryUser
+from ms_tau_sdk.backend.team_memberships import (
+    TeamMembershipCache,
+    TeamMembershipScope,
+    bind_team_membership_scope,
+    unbind_team_membership_scope,
+)
 from ms_tau_sdk.errors import SessionNotFoundError, TauSDKError
 from ms_tau_sdk.logging import bind_request_identity_log_fields
 from ms_tau_sdk.runtime.provenance import CallerIdentityError
@@ -255,6 +261,12 @@ def required_assertion(scope: Scope) -> AssertionKind:
     return "platform" if internal else "caller"
 
 
+def _backend_of(scope: Scope) -> MainSequenceClient | None:
+    """Return the application's platform client once its lifespan has created it."""
+
+    return getattr(getattr(scope.get("app"), "state", None), "backend", None)
+
+
 def _assertion(scope: Scope) -> str:
     values = [
         value for name, value in scope.get("headers", ()) if name.lower() == _ASSERTION_HEADER_NAME
@@ -268,11 +280,24 @@ def _assertion(scope: Scope) -> str:
 
 
 class RequestIdentityMiddleware:
-    """Admit a hosted runtime's requests only with the platform's signed assertion."""
+    """Admit a hosted runtime's requests only with the platform's signed assertion.
+
+    It also gives each request with a verified caller what ``in_teams()`` needs: the deployment
+    the verifier trusts, the request's caller assertion, and the process's cache of answers, which
+    an answer may be reused from for ``team_membership_cache_seconds``.
+    """
 
-    def __init__(self, app: ASGIApp, *, verifier: AssertionVerifier) -> None:
+    def __init__(
+        self,
+        app: ASGIApp,
+        *,
+        verifier: AssertionVerifier,
+        team_membership_cache_seconds: float = 0,
+    ) -> None:
         self.app = app
         self.verifier = verifier
+        self.team_membership_cache_seconds = team_membership_cache_seconds
+        self.team_memberships = TeamMembershipCache()
 
     async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
         if scope["type"] not in {"http", "websocket"}:
@@ -304,17 +329,29 @@ class RequestIdentityMiddleware:
             organization_environment_uid=self.verifier.organization_environment_uid,
         )
         bind_request_identity_log_fields(scope, user_uid=user_uid, auth_outcome="authenticated")
+        membership: TeamMembershipScope | None = None
         if caller is not None:
-            scope[_CALLER_ASSERTION_SCOPE_KEY] = CallerAssertion(
+            caller_assertion = CallerAssertion(
                 caller=caller,
                 expires_at=verified.expires_at,
                 token=token,
             )
+            scope[_CALLER_ASSERTION_SCOPE_KEY] = caller_assertion
+            membership = TeamMembershipScope(
+                release_uid=self.verifier.resource_release_uid,
+                environment_uid=self.verifier.organization_environment_uid,
+                cache=self.team_memberships,
+                cache_seconds=self.team_membership_cache_seconds,
+                assertion=caller_assertion,
+                client=_backend_of(scope),
+            )
         caller_token = _current_caller.set(caller)
         lookups_token = _workload_lookups.set({})
+        membership_token = bind_team_membership_scope(membership)
         try:
             await self.app(scope, receive, send)
         finally:
+            unbind_team_membership_scope(membership, membership_token)
             _workload_lookups.reset(lookups_token)
             _current_caller.reset(caller_token)
             scope.pop(_CALLER_ASSERTION_SCOPE_KEY, None)
@@ -363,6 +400,7 @@ def install_request_identity(app: FastAPI, settings: TauSDKSettings) -> None:
         app.add_middleware(
             RequestIdentityMiddleware,
             verifier=AssertionVerifier.from_settings(settings),
+            team_membership_cache_seconds=settings.team_membership_cache_seconds,
         )
     setattr(
         app.state,

{ms_tau_sdk-2.0.15.dev62 → ms_tau_sdk-2.0.16.dev64}/src/ms_tau_sdk/backend/assertions.py

@@ -4,9 +4,9 @@ The platform signs two kinds of short-lived JWS with one Ed25519 key set and sen
 ``X-MainSequence-Caller-Assertion`` header:
 
 - a caller assertion, for a request a person or a workload sends to the runtime through the
-  platform. It names the caller (``sub``), the caller's teams in the Organization
-  (``team_uids``), and whether the caller administers the Organization
-  (``is_organization_admin``);
+  platform. It names the caller (``sub``) and whether the caller administers the Organization
+  (``is_organization_admin``). While the platform still signs it, it also carries the caller's
+  teams (``team_uids``), which is deprecated: ``in_teams()`` asks the platform instead (#103);
 - a platform assertion, for the platform's own background calls. It names no caller.
 
 Both are bound to this runtime's release (``aud``, ``resource_release_uid``) and Organization
@@ -24,7 +24,7 @@ import json
 import re
 import time
 import uuid
-from collections.abc import Callable, Mapping
+from collections.abc import Callable, Iterable, Mapping
 from dataclasses import dataclass, field
 from typing import Any, Literal
 from urllib.parse import urlsplit
@@ -33,6 +33,7 @@ import httpx
 import jwt
 from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PublicKey
 
+from ms_tau_sdk.backend.team_memberships import deprecated_team_uids, member_team_uids
 from ms_tau_sdk.errors import ConfigurationError
 from ms_tau_sdk.settings import (
     CALLER_ASSERTION_ISSUER_ENV,
@@ -59,7 +60,7 @@ PLATFORM_ASSERTION_CLAIMS = frozenset(
         "exp",
     }
 )
-CALLER_ASSERTION_CLAIMS = PLATFORM_ASSERTION_CLAIMS | {"sub", "team_uids", "is_organization_admin"}
+CALLER_ASSERTION_CLAIMS = PLATFORM_ASSERTION_CLAIMS | {"sub", "is_organization_admin"}
 
 type AssertionKind = Literal["caller", "platform"]
 
@@ -82,13 +83,55 @@ class AssertionKeysUnavailableError(Exception):
     """The platform's verification keys could not be obtained."""
 
 
-@dataclass(frozen=True, slots=True)
+@dataclass(frozen=True, slots=True, init=False)
 class VerifiedCaller:
-    """The caller that a verified caller assertion names."""
+    """The caller that a verified caller assertion names.
+
+    ``in_teams()`` asks the platform which teams the caller belongs to. ``team_uids`` is the
+    deprecated list earlier assertions carried; ``signed_team_uids`` is None when the assertion
+    carried none (#103).
+    """
 
     uid: str
-    team_uids: tuple[str, ...]
     is_organization_admin: bool
+    signed_team_uids: tuple[str, ...] | None
+
+    def __init__(
+        self,
+        uid: str,
+        team_uids: tuple[str, ...] | None = None,
+        is_organization_admin: bool = False,
+    ) -> None:
+        object.__setattr__(self, "uid", uid)
+        object.__setattr__(self, "is_organization_admin", is_organization_admin)
+        object.__setattr__(
+            self, "signed_team_uids", None if team_uids is None else tuple(team_uids)
+        )
+
+    @property
+    def team_uids(self) -> tuple[str, ...]:
+        """Deprecated: the team UIDs the caller's assertion carried. Use ``in_teams()``.
+
+        Warns when read, and raises ``TauSDKError`` when the assertion carried no team list; it
+        never answers an empty list for that.
+        """
+
+        return deprecated_team_uids(self.signed_team_uids)
+
+    async def in_teams(
+        self,
+        team_uids: Iterable[str | uuid.UUID],
+        *,
+        max_age_seconds: float | None = None,
+    ) -> frozenset[str]:
+        """Return which of ``team_uids`` the caller is an active member of.
+
+        It asks the platform with the request's caller assertion and reuses answers as the
+        runtime's ``team_membership_cache_seconds`` allows; ``max_age_seconds=0`` is a fresh
+        check. See ``ms_tau_sdk.backend.team_memberships.member_team_uids``.
+        """
+
+        return await member_team_uids(self.uid, team_uids, max_age_seconds=max_age_seconds)
 
 
 @dataclass(frozen=True, slots=True)
@@ -210,19 +253,26 @@ def _fresh_until(cache_control: str | None, now: float) -> float | None:
 
 def _verified_caller(payload: Mapping[str, Any]) -> VerifiedCaller:
     uid = payload["sub"]
-    team_uids = payload["team_uids"]
+    # The deprecated team list, checked while the platform still signs it (#103).
+    team_uids = payload.get("team_uids")
     is_organization_admin = payload["is_organization_admin"]
     if (
         not _is_canonical_uid(uid)
-        or not isinstance(team_uids, list)
-        or not all(_is_canonical_uid(team_uid) for team_uid in team_uids)
-        or team_uids != sorted(set(team_uids))
+        or (
+            team_uids is not None
+            and (
+                not isinstance(team_uids, list)
+                or not all(_is_canonical_uid(team_uid) for team_uid in team_uids)
+                or team_uids != sorted(set(team_uids))
+            )
+        )
+        or ("team_uids" in payload and team_uids is None)
         or type(is_organization_admin) is not bool
     ):
         raise InvalidAssertionError("The caller assertion does not name a valid caller")
     return VerifiedCaller(
         uid=uid,
-        team_uids=tuple(team_uids),
+        team_uids=None if team_uids is None else tuple(team_uids),
         is_organization_admin=is_organization_admin,
     )
 
@@ -332,7 +382,9 @@ class AssertionVerifier:
             )
         except (jwt.PyJWTError, TypeError, ValueError) as error:
             raise InvalidAssertionError(f"The {kind} assertion did not verify") from error
-        if set(payload) != claims:
+        # A caller assertion may still carry the deprecated team list (#103).
+        optional = {"team_uids"} if kind == "caller" else set()
+        if set(payload) - optional != claims:
             raise InvalidAssertionError(f"The {kind} assertion does not have the exact claim set")
         if (
             payload["iss"] != self.issuer

{ms_tau_sdk-2.0.15.dev62 → ms_tau_sdk-2.0.16.dev64}/src/ms_tau_sdk/backend/client.py

@@ -80,6 +80,7 @@ from .routes import (
     model_provider_credentials,
     resource_release_runtime_access,
     user,
+    user_team_memberships,
 )
 
 T = TypeVar("T")
@@ -427,6 +428,33 @@ class MainSequenceClient:
         data = await self._request("GET", user(user_uid), idempotent=True)
         return DirectoryUser.model_validate(data)
 
+    async def team_memberships(
+        self, user_uid: str, team_uids: list[str], *, caller_assertion: str
+    ) -> set[str]:
+        """Return which of ``team_uids`` the person ``user_uid`` is an active member of (#103).
+
+        ``caller_assertion`` is the verified assertion of the request that asks, sent only with
+        this call; ``user_uid`` must be the person it names. The platform answers at most 100
+        teams per call and leaves out the ones it does not count.
+        """
+
+        query = urlencode({"team_uid__in": ",".join(team_uids)})
+        try:
+            data = await self._request(
+                "GET",
+                f"{user_team_memberships(user_uid)}?{query}",
+                idempotent=True,
+                headers={ASSERTION_HEADER: caller_assertion},
+            )
+        except SessionNotFoundError as error:
+            raise BackendError(
+                "The platform has no team membership check for this person.", status_code=404
+            ) from error
+        answered = data.get("team_uids") if isinstance(data, dict) else None
+        if not isinstance(answered, list) or not all(isinstance(uid, str) for uid in answered):
+            raise BackendError("The platform's team membership answer is invalid.")
+        return set(answered) & set(team_uids)
+
     async def list_model_providers(
         self, *, organization_environment_uid: str | None = None
     ) -> dict[str, Any]:

{ms_tau_sdk-2.0.15.dev62 → ms_tau_sdk-2.0.16.dev64}/src/ms_tau_sdk/backend/routes.py

@@ -97,3 +97,7 @@ def resource_release_runtime_access(release_uid: str) -> str:
 
 def user(user_uid: str) -> str:
     return f"{USERS}{user_uid}/"
+
+
+def user_team_memberships(user_uid: str) -> str:
+    return f"{USERS}{user_uid}/team-memberships/"

ms_tau_sdk-2.0.16.dev64/src/ms_tau_sdk/backend/team_memberships.py

@@ -0,0 +1,229 @@
+"""Team membership checks a hosted runtime makes on demand (ADR-0019, #103).
+
+The platform answers which of the given teams a person is an active member of. The runtime asks
+only about the verified caller of the current request, with that request's caller assertion. It
+keeps the answers for the rest of the request and, for as long as the application chose, for
+later requests in the process.
+"""
+
+from __future__ import annotations
+
+import math
+import threading
+import time
+import uuid
+import warnings
+from collections import OrderedDict
+from collections.abc import Iterable
+from contextvars import ContextVar, Token
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+from ms_tau_sdk.errors import TauSDKError
+
+if TYPE_CHECKING:
+    from ms_tau_sdk.backend.assertions import CallerAssertion
+    from ms_tau_sdk.backend.client import MainSequenceClient
+
+# At most this many answers per process, and at most this many teams in one call to the platform,
+# which answers no more in one call.
+MAX_CACHED_ANSWERS = 10_000
+MAX_TEAMS_PER_CALL = 100
+
+# The release UID, Organization Environment UID, person UID and team UID.
+type AnswerKey = tuple[str, str, str, str]
+
+
+def _now() -> float:
+    return time.monotonic()
+
+
+class TeamMembershipCache:
+    """Yes-or-no answers across requests, oldest dropped first.
+
+    The key starts with the release and Organization Environment the runtime is deployed for, so
+    an answer obtained for one never answers another.
+    """
+
+    def __init__(self, max_answers: int = MAX_CACHED_ANSWERS) -> None:
+        self._answers: OrderedDict[AnswerKey, tuple[bool, float]] = OrderedDict()
+        self._max_answers = max_answers
+        self._lock = threading.Lock()
+
+    def get(self, key: AnswerKey, *, max_age: float) -> bool | None:
+        """Return the stored answer when it is younger than ``max_age`` seconds, else None."""
+
+        if max_age <= 0:
+            return None
+        with self._lock:
+            entry = self._answers.get(key)
+        if entry is None:
+            return None
+        answer, stored_at = entry
+        return answer if _now() - stored_at < max_age else None
+
+    def put(self, key: AnswerKey, answer: bool) -> None:
+        with self._lock:
+            self._answers[key] = (answer, _now())
+            self._answers.move_to_end(key)
+            while len(self._answers) > self._max_answers:
+                self._answers.popitem(last=False)
+
+    def __len__(self) -> int:
+        with self._lock:
+            return len(self._answers)
+
+
+@dataclass(slots=True)
+class TeamMembershipScope:
+    """What one hosted request may use to answer ``in_teams()``.
+
+    The release and Organization Environment are the ones the runtime's verifier reads from its
+    deployment configuration, never from the request, and every answer's key starts with them.
+    The request's caller assertion is presented only to ask the platform about that caller. The
+    scope ends with its request, also in the tasks that copied the request's context.
+    """
+
+    release_uid: str
+    environment_uid: str
+    cache: TeamMembershipCache = field(repr=False)
+    cache_seconds: float
+    assertion: CallerAssertion | None = field(default=None, repr=False)
+    client: MainSequenceClient | None = field(default=None, repr=False)
+    # The answers of this request, by key; the same question is asked once per request.
+    answers: dict[AnswerKey, bool] = field(default_factory=dict, repr=False)
+    active: bool = True
+
+
+_current_scope: ContextVar[TeamMembershipScope | None] = ContextVar(
+    "ms_tau_sdk_team_membership_scope",
+    default=None,
+)
+
+
+def bind_team_membership_scope(
+    scope: TeamMembershipScope | None,
+) -> Token[TeamMembershipScope | None]:
+    """Make ``scope`` the current request's; None for a request without a verified caller."""
+
+    return _current_scope.set(scope)
+
+
+def unbind_team_membership_scope(
+    scope: TeamMembershipScope | None,
+    token: Token[TeamMembershipScope | None],
+) -> None:
+    """End ``scope`` when its request ends, and restore the previous one."""
+
+    if scope is not None:
+        # Tasks that copied the request's context hold this same scope; it ends for them too.
+        scope.active = False
+        scope.assertion = None
+        scope.client = None
+        scope.answers = {}
+    _current_scope.reset(token)
+
+
+def canonical_team_uids(team_uids: Iterable[str | uuid.UUID]) -> list[str]:
+    """Return the distinct canonical UIDs of ``team_uids``, sorted."""
+
+    if isinstance(team_uids, str | bytes | uuid.UUID):
+        raise TypeError("in_teams() takes a collection of team UIDs, not a single UID")
+    try:
+        return sorted({str(uuid.UUID(str(team_uid).strip())) for team_uid in team_uids})
+    except (AttributeError, TypeError, ValueError) as error:
+        raise ValueError("Team UIDs must be valid UUIDs") from error
+
+
+async def member_team_uids(
+    person_uid: str,
+    team_uids: Iterable[str | uuid.UUID],
+    *,
+    max_age_seconds: float | None = None,
+) -> frozenset[str]:
+    """Return which of ``team_uids`` the person ``person_uid`` is an active member of.
+
+    ``VerifiedCaller.in_teams()`` and ``Requester.in_teams()`` call it, and it answers only about
+    the verified caller of the current hosted request:
+
+    - within the request, the same question is asked once;
+    - across requests, an answer is reused while it is younger than the runtime's
+      ``team_membership_cache_seconds``, or than ``max_age_seconds`` when the call gives one;
+    - ``max_age_seconds=0`` always asks the platform, skips both kinds of reuse, and stores the
+      new answer.
+
+    A longer list is asked in calls of at most 100 teams. A failed call raises; it never answers
+    "not a member".
+    """
+
+    asked = canonical_team_uids(team_uids)
+    if max_age_seconds is not None and (
+        isinstance(max_age_seconds, bool)
+        or not isinstance(max_age_seconds, int | float)
+        or not math.isfinite(max_age_seconds)
+        or max_age_seconds < 0
+    ):
+        raise ValueError("max_age_seconds must be None or a non-negative number of seconds")
+    scope = _current_scope.get()
+    if scope is None or not scope.active or scope.assertion is None:
+        raise TauSDKError("in_teams() needs a hosted request whose caller assertion was verified")
+    if person_uid != scope.assertion.caller.uid:
+        raise TauSDKError("in_teams() answers only about the verified caller of the request")
+    fresh = max_age_seconds == 0
+    lifetime = scope.cache_seconds if max_age_seconds is None else max_age_seconds
+    answers: dict[str, bool] = {}
+    unanswered: list[str] = []
+    for team_uid in asked:
+        key = (scope.release_uid, scope.environment_uid, person_uid, team_uid)
+        reused = None
+        if not fresh:
+            reused = scope.answers.get(key)
+            if reused is None:
+                reused = scope.cache.get(key, max_age=lifetime)
+        if reused is None:
+            unanswered.append(team_uid)
+        else:
+            answers[team_uid] = scope.answers[key] = reused
+    for start in range(0, len(unanswered), MAX_TEAMS_PER_CALL):
+        batch = unanswered[start : start + MAX_TEAMS_PER_CALL]
+        members = await _platform_members(scope, person_uid, batch)
+        for team_uid in batch:
+            key = (scope.release_uid, scope.environment_uid, person_uid, team_uid)
+            answers[team_uid] = scope.answers[key] = team_uid in members
+            scope.cache.put(key, answers[team_uid])
+    return frozenset(team_uid for team_uid, member in answers.items() if member)
+
+
+async def _platform_members(
+    scope: TeamMembershipScope,
+    person_uid: str,
+    team_uids: list[str],
+) -> set[str]:
+    assertion = scope.assertion if scope.active else None
+    token = assertion.unexpired_token() if assertion is not None else None
+    if token is None:
+        raise TauSDKError(
+            "in_teams() cannot ask the platform: the request's caller assertion has expired or "
+            "the request has ended"
+        )
+    if scope.client is None:
+        raise TauSDKError("in_teams() needs the Agent runtime of this process")
+    return await scope.client.team_memberships(person_uid, team_uids, caller_assertion=token)
+
+
+def deprecated_team_uids(signed: tuple[str, ...] | None) -> tuple[str, ...]:
+    """Return the deprecated team list a caller assertion carried, with a warning.
+
+    It raises when the assertion carried none; it never answers an empty list for that.
+    """
+
+    warnings.warn(
+        "team_uids is deprecated; check membership with in_teams() instead",
+        DeprecationWarning,
+        stacklevel=3,
+    )
+    if signed is None:
+        raise TauSDKError(
+            "The caller assertion carries no team list; check membership with in_teams()"
+        )
+    return signed

{ms_tau_sdk-2.0.15.dev62 → ms_tau_sdk-2.0.16.dev64}/src/ms_tau_sdk/runtime/manager.py

@@ -1776,7 +1776,7 @@ class SessionRuntimeManager:
         The platform's answer to the turn start names that person, whoever called: a chat or A2A
         Message turn, a Task attempt, and a turn the platform starts for a caller delivery alike.
         ``caller`` is the verified caller of the request, when there is one; it supplies the
-        person's teams only when it is that person.
+        deprecated team list its assertion carried only when it is that person.
         """
 
         if not self._requester_identity_verified():
@@ -1784,7 +1784,7 @@ class SessionRuntimeManager:
         uid = runtime.requester_user_uid
         if uid is None:
             return None
-        team_uids = caller.team_uids if caller is not None and caller.uid == uid else ()
+        team_uids = caller.signed_team_uids if caller is not None and caller.uid == uid else ()
         return Requester(uid=uid, team_uids=team_uids)
 
     def _requester_http(self) -> httpx.AsyncClient:

{ms_tau_sdk-2.0.15.dev62 → ms_tau_sdk-2.0.16.dev64}/src/ms_tau_sdk/runtime/requester.py

@@ -19,7 +19,7 @@ import asyncio
 import math
 import time
 import uuid
-from collections.abc import Awaitable, Callable, Mapping
+from collections.abc import Awaitable, Callable, Iterable, Mapping
 from contextlib import suppress
 from contextvars import ContextVar, Token
 from dataclasses import dataclass, field
@@ -31,6 +31,7 @@ import structlog
 from ms_tau_sdk.backend.auth import AccessToken, _jwt_expiry
 from ms_tau_sdk.backend.client import LeaseProof, answer_without_request_credentials
 from ms_tau_sdk.backend.models import ReleaseRuntimeAccess
+from ms_tau_sdk.backend.team_memberships import deprecated_team_uids, member_team_uids
 from ms_tau_sdk.errors import (
     ApplicationReadinessTimeoutError,
     ApplicationWakingError,
@@ -51,15 +52,48 @@ type Delegation = Literal["auto", "none", "required"]
 _DELEGATIONS: tuple[Delegation, ...] = ("auto", "none", "required")
 
 
-@dataclass(frozen=True, slots=True)
+@dataclass(frozen=True, slots=True, init=False)
 class Requester:
     """The verified person whose request the current turn serves.
 
-    ``team_uids`` can be empty when the turn does not know them.
+    ``in_teams()`` asks the platform which teams the person belongs to while the person is the
+    verified caller of the request the turn runs in, and raises otherwise. ``team_uids`` is the
+    deprecated list the caller's assertion carried: empty when the turn does not know the person's
+    teams, and ``signed_team_uids`` is None when the assertion carried no list (#103).
     """
 
     uid: str
-    team_uids: tuple[str, ...] = ()
+    signed_team_uids: tuple[str, ...] | None
+
+    def __init__(self, uid: str, team_uids: tuple[str, ...] | None = ()) -> None:
+        object.__setattr__(self, "uid", uid)
+        object.__setattr__(
+            self, "signed_team_uids", None if team_uids is None else tuple(team_uids)
+        )
+
+    @property
+    def team_uids(self) -> tuple[str, ...]:
+        """Deprecated: the team UIDs the caller's assertion carried. Use ``in_teams()``.
+
+        Warns when read, and raises ``TauSDKError`` when the assertion carried no team list; it
+        never answers an empty list for that.
+        """
+
+        return deprecated_team_uids(self.signed_team_uids)
+
+    async def in_teams(
+        self,
+        team_uids: Iterable[str | uuid.UUID],
+        *,
+        max_age_seconds: float | None = None,
+    ) -> frozenset[str]:
+        """Return which of ``team_uids`` the person is an active member of.
+
+        It answers while the person is the verified caller of the request the turn runs in, with
+        the reuse rules of ``VerifiedCaller.in_teams()``, and raises ``TauSDKError`` otherwise.
+        """
+
+        return await member_team_uids(self.uid, team_uids, max_age_seconds=max_age_seconds)
 
 
 @dataclass(frozen=True, slots=True)

{ms_tau_sdk-2.0.15.dev62 → ms_tau_sdk-2.0.16.dev64}/src/ms_tau_sdk/settings.py

@@ -147,6 +147,14 @@ class TauSDKSettings(BaseSettings):
         allow_inf_nan=False,
         validation_alias=A2A_MESSAGE_LIMIT_ENV,
     )
+    # How long a team membership answer may be reused across requests (ADR-0019, #103). The
+    # application chooses; 0 reuses an answer only within the same request.
+    team_membership_cache_seconds: float = Field(
+        default=0,
+        ge=0,
+        allow_inf_nan=False,
+        validation_alias="TAU_TEAM_MEMBERSHIP_CACHE_SECONDS",
+    )
     local_mode: bool = Field(default=False, validation_alias="TAU_LOCAL_MODE")
     exclude_base_tools: bool = Field(default=False, validation_alias="TAU_EXCLUDE_BASE_TOOLS")
     exclude_mainsequence_mcp: bool = Field(