ms-tau-sdk 2.0.6.dev40__tar.gz → 2.0.7.dev42__tar.gz

{ms_tau_sdk-2.0.6.dev40 → ms_tau_sdk-2.0.7.dev42}/CHANGELOG.md

@@ -2,6 +2,45 @@
 
 ## Unreleased
 
+- **Breaking: one delegation envelope on every call made for the work
+  ([#78](https://github.com/mainsequence-sdk/ms-tau-sdk/issues/78), ADR 0021 amendment).** This
+  release works only with the matching platform change, deployed in the same cutover; there is no
+  deprecation period, and earlier releases, including 2.0.6, stop acting for people once that
+  platform is deployed.
+  - Every hosted Main Sequence MCP call names the turn's session, and carries the person's
+    delegation (`mainsequence.ai/delegation/v1`) while the turn serves a person. The platform's
+    per-tool labels (`mainsequence.ai/requires-requester/v1`,
+    `mainsequence.ai/requires-caller-session-proof/v1`) are no longer read, and a turn that serves
+    nobody keeps its MCP tools: its calls are the Agent's own.
+  - Declared application tools run in every turn, with a token for the person the turn serves or
+    the Agent's own token when it serves nobody. A refused delegated call is reported and never
+    retried as the Agent.
+  - The person a turn serves comes only from the platform's answer to the turn start, whoever
+    called; dispatch, delivery and Task answers are no longer read for it. Delegated work serves
+    the person the platform records for it.
+  - `platform_client()` replaces `requester_client()`, with no alias. By default a call carries the
+    delegation while the turn serves a person; `delegation="none"` never carries it and
+    `delegation="required"` refuses the call before sending when the turn serves nobody. Outside a
+    turn no call carries a delegation, and in local mode calls use the signed-in person's own
+    credential.
+  - Delegated calls use the person's ordinary permissions, including administrative ones; the
+    statement people are shown changes accordingly.
+  - The SDK no longer hides the withdrawn private Secret entry operations, and the local health
+    field `mcp_session_proof_limited_tool_count` is removed.
+
+- A new packaged skill, `tau_security_and_access`, teaches building project tools that act for the
+  person a turn serves: which delegation each tool should use, a worked example of tools that use
+  a person's own Secret without exposing it to the model, and how sharing decides what a delegated
+  call can reach. `ms-tau skills sync` now installs five skills.
+
+- Documentation now distinguishes requester-bound reads and supported writes from workload grants,
+  states the write risk and platform rollout requirements, and includes conversation/Task
+  permissions and denial recovery. The Security and access guide keeps its `security-model.md`
+  path. Provider selection settings and troubleshooting, the public readiness-hook reference, and
+  the exported API compatibility list are complete. This changes documentation only.
+
+## 2.0.6 — 2026-10-07
+
 - The documentation no longer describes the platform's internal implementation. It no longer names
   the backend framework, its repositories, ADRs, classes or commits, and calls the backend "the
   platform". The archived Astro documents (`docs/history/astro`) and the ADR 56 migration workspace

{ms_tau_sdk-2.0.6.dev40 → ms_tau_sdk-2.0.7.dev42}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ms-tau-sdk
-Version: 2.0.6.dev40
+Version: 2.0.7.dev42
 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
@@ -133,10 +133,11 @@ only an application that declares it, so serve the application `create_app()` re
 hosting, requests are handled as before. See
 [request identity](docs/reference/runtime-contract.md#request-identity).
 
-An Agent that an Organization admin enabled for it can read with the access of the person whose
-request a turn is serving. Project tools read that person with `current_requester()` and call the
-platform or another platform application for them with `requester_client()`; neither exposes a
-proof or a token. See the [public API](docs/reference/public-api.md#current_requester-and-requester_client).
+An Agent that an Organization admin enabled for it can act with the ordinary permissions of the
+person whose request a turn is serving. Project tools read that person with `current_requester()`
+and call the platform or another platform application with `platform_client()`, which carries the
+person's delegation by default while the turn serves one; neither exposes a proof or a token. See
+the [public API](docs/reference/public-api.md#current_requester-and-platform_client).
 
 Job-hosted batch execution is an [accepted design](docs/adrs/0015-job-hosted-batch-execution.md)
 with implementation pending. It will run this SDK's configured Tau composition for one assignment
@@ -287,13 +288,14 @@ are not bundled into the SDK. Main Sequence transport and protocol behavior rema
 - explicit, version-matched development skills for repository integration, local debugging,
   project customization, and TAU's A2A host adapter
 
-## Security model
+## Security and access guide
 
-A hosted Agent runs as its own workload, with no access until it is granted, and never reads or
-writes Secret values. An Organization admin can let it read with the access of the person it is
-serving, read-only and for at most 24 hours. Everything its tools read reaches the model, and its
+A hosted Agent runs as its own workload, with no access until it is granted. An Organization admin
+can let it act with the ordinary permissions of the person it serves, including administrative
+ones, only during that work and for at most 24 hours. Prompt injection can cause unintended actions within those rights;
+completed changes can outlast that access. Everything its tools read reaches the model, and its
 tools and extensions run with its credentials. The
-[agent security model](docs/reference/security-model.md) explains what people who build and use
+[Security and access guide](docs/reference/security-model.md) explains what people who build and use
 Agents need to know.
 
 ## Deployment boundary

{ms_tau_sdk-2.0.6.dev40 → ms_tau_sdk-2.0.7.dev42}/README.md

@@ -100,10 +100,11 @@ only an application that declares it, so serve the application `create_app()` re
 hosting, requests are handled as before. See
 [request identity](docs/reference/runtime-contract.md#request-identity).
 
-An Agent that an Organization admin enabled for it can read with the access of the person whose
-request a turn is serving. Project tools read that person with `current_requester()` and call the
-platform or another platform application for them with `requester_client()`; neither exposes a
-proof or a token. See the [public API](docs/reference/public-api.md#current_requester-and-requester_client).
+An Agent that an Organization admin enabled for it can act with the ordinary permissions of the
+person whose request a turn is serving. Project tools read that person with `current_requester()`
+and call the platform or another platform application with `platform_client()`, which carries the
+person's delegation by default while the turn serves one; neither exposes a proof or a token. See
+the [public API](docs/reference/public-api.md#current_requester-and-platform_client).
 
 Job-hosted batch execution is an [accepted design](docs/adrs/0015-job-hosted-batch-execution.md)
 with implementation pending. It will run this SDK's configured Tau composition for one assignment
@@ -254,13 +255,14 @@ are not bundled into the SDK. Main Sequence transport and protocol behavior rema
 - explicit, version-matched development skills for repository integration, local debugging,
   project customization, and TAU's A2A host adapter
 
-## Security model
+## Security and access guide
 
-A hosted Agent runs as its own workload, with no access until it is granted, and never reads or
-writes Secret values. An Organization admin can let it read with the access of the person it is
-serving, read-only and for at most 24 hours. Everything its tools read reaches the model, and its
+A hosted Agent runs as its own workload, with no access until it is granted. An Organization admin
+can let it act with the ordinary permissions of the person it serves, including administrative
+ones, only during that work and for at most 24 hours. Prompt injection can cause unintended actions within those rights;
+completed changes can outlast that access. Everything its tools read reaches the model, and its
 tools and extensions run with its credentials. The
-[agent security model](docs/reference/security-model.md) explains what people who build and use
+[Security and access guide](docs/reference/security-model.md) explains what people who build and use
 Agents need to know.
 
 ## Deployment boundary

{ms_tau_sdk-2.0.6.dev40 → ms_tau_sdk-2.0.7.dev42}/pyproject.toml

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

{ms_tau_sdk-2.0.6.dev40 → ms_tau_sdk-2.0.7.dev42}/src/ms_tau_sdk/__init__.py

@@ -9,7 +9,7 @@ from .runtime.deployment_health import (
     RUNTIME_HEALTH_ABI_VERSION,
     register_deployment_readiness_hook,
 )
-from .runtime.requester import current_requester, requester_client
+from .runtime.requester import current_requester, platform_client
 from .settings import TauSDKSettings
 
 __all__ = [
@@ -18,6 +18,6 @@ __all__ = [
     "__version__",
     "create_app",
     "current_requester",
+    "platform_client",
     "register_deployment_readiness_hook",
-    "requester_client",
 ]

{ms_tau_sdk-2.0.6.dev40 → ms_tau_sdk-2.0.7.dev42}/src/ms_tau_sdk/agent_skills/tau_a2a_runtime_adapter/SKILL.md

@@ -23,19 +23,18 @@ The SDK owns:
 
 - projecting the authenticated Main Sequence MCP catalog into a TAU session;
 - preserving each tool's canonical name and metadata through host normalization;
-- privately attaching active caller-session proof when a tool advertises
-  `mainsequence.ai/requires-caller-session-proof/v1: true`;
-- attaching the same proof when a tool advertises `mainsequence.ai/requires-requester/v1: true`,
-  which the platform runs for the turn's requester, and refusing that tool before sending it in a
-  hosted turn that serves nobody;
+- privately attaching, to every hosted Main Sequence MCP call, the turn's caller-session proof under
+  `mainsequence.ai/caller-session-proof/v1`, and, while the turn serves a person, the same proof as
+  that person's delegation under `mainsequence.ai/delegation/v1`. No tool metadata decides it;
 - verifying the platform's signed caller or platform assertion on every inbound request of a
   hosted runtime, and admitting a request to a session or its Tasks only for the session's owner,
   an Organization admin, or the workload User of the Agent that delegated to that child session,
   which the platform's own records establish, never the `X-Caller-*` headers;
 - presenting the verified caller assertion of the request that starts a chat or A2A Message turn
-  only when it marks that turn active, so that the platform can record the turn's requester, and
-  giving extension tools that requester and requester-bound calls through `current_requester()`
-  and `requester_client()` without exposing the assertion, the lease proof, or any token;
+  only when it marks that turn active, so that the platform can record the turn's requester;
+  taking the person the turn serves only from the platform's answer to the turn start; and giving
+  extension tools that person and calls for the work through `current_requester()` and
+  `platform_client()` without exposing the assertion, the lease proof, or any token;
 - translating inbound A2A requests into the shared TAU runtime; and
 - translating runtime events and results into validated A2A responses.
 

{ms_tau_sdk-2.0.6.dev40 → ms_tau_sdk-2.0.7.dev42}/src/ms_tau_sdk/agent_skills/tau_project_customization/SKILL.md

@@ -97,10 +97,11 @@ tools do not grant new platform permissions merely because they run inside TAU.
 
 ## Acting for the person a turn serves
 
-An Agent that an Organization admin enabled for it can read platform data, and ask other platform
-applications, with the access of the person whose request a turn is serving: the requester. The
-platform keeps that authority and finds the person in its own records; the runtime only proves
-which of its sessions it is working on. Extension tools use two SDK functions and nothing else:
+An Agent that an Organization admin enabled for it can call the platform and other platform
+applications with the ordinary permissions of the person whose request a turn is serving: the
+requester. The platform keeps that authority and finds the person in its own records; the runtime
+only proves which of its sessions it is working on. Extension tools use two SDK functions and
+nothing else:
 
 ```python
 import json
@@ -108,64 +109,74 @@ import json
 from tau_agent.messages import TextContent
 from tau_agent.tools import AgentToolResult
 
-from ms_tau_sdk import current_requester, requester_client
+from ms_tau_sdk import platform_client
 
 ANALYST_DATA_RELEASE_UID = "..."  # the release of the application to ask
 
 
 async def revenue_by_region(tool_call_id, arguments, signal=None, on_update=None):
-    if current_requester() is None:
-        return AgentToolResult(content=[TextContent(text="Ask me from your own conversation.")])
+    # This tool answers each person with their own data, so it needs a person.
     try:
-        answer = await requester_client().call_release(
+        answer = await platform_client(delegation="required").call_release(
             ANALYST_DATA_RELEASE_UID,
             "POST",
             "/query",
             json={"question": "revenue by region"},
         )
     except PermissionError:
-        return AgentToolResult(content=[TextContent(text="Your access for this request ended.")])
+        return AgentToolResult(content=[TextContent(text="Ask me from your own conversation.")])
     return AgentToolResult(content=[TextContent(text=json.dumps(answer.json()["rows"]))])
 ```
 
-- `current_requester()` returns the turn's verified requester, with `uid` and `team_uids`, or
-  `None`. It is `None` for Agent callers, the platform's own calls other than a caller delivery
-  (which resumes delegated work for the person who asked), local mode, and code outside a turn.
-  Only it names the requester:
-  never take a person's UID from tool arguments, the prompt, history, or a header.
-- `requester_client()` returns a client bound to the turn. `await client.request("GET",
-  "/api/v1/...")` reads a platform API path for the requester. `await client.call_release(
-  release_uid, method, path, ...)` asks another platform application, which answers as the
-  requester. Both return an `httpx.Response`.
-- Without a requester, `requester_client()` raises a `PermissionError`. So does a call that the
-  platform refuses because the requester's access ended (`code` `requester_binding_invalid` or
-  `runtime_lease_*`): the turn is over, the access was removed, more than 24 hours passed, or the
-  Agent is not enabled. Catch it, say in plain words that the request cannot be served, and never
-  fall back to the Agent's own access.
+- `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.
+- `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`.
+- By default (`delegation="auto"`) a call carries the person's delegation while the turn serves a
+  person, and is the Agent's own otherwise; the operation or application decides what it may do.
+  `delegation="none"` never carries it. `delegation="required"` raises a `PermissionError` before
+  sending when the turn serves nobody; use it in a tool that only makes sense for a person.
+- A call the platform refuses because the person's access ended (`code`
+  `requester_binding_invalid` or `runtime_lease_*`) raises a `PermissionError`: the turn is over,
+  the access was removed, more than 24 hours passed, or the Agent is not enabled. Catch it, say in
+  plain words that the request cannot be served, and never retry it as the Agent.
 
 Rules for tools that act for the requester:
 
 - Never handle proofs or tokens. The SDK attaches the session, the lease proof, and the
   credentials itself. A tool never reads, logs, stores, or forwards them, passes a path rather than
   a URL, and never sets `Authorization` or an `X-MainSequence-*` header.
-- Requester-bound calls are read-only. The platform refuses writes, sharing, and Secret values;
-  do not build tools that try them.
+- A delegated call uses the person's ordinary permissions, including administrative ones; any other
+  call uses the Agent's own. Each operation decides what it needs. Never infer write permission
+  from view access.
+- This needs the platform's matching change, deployed in the same cutover; check the deployed
+  platform and the installed SDK before depending on it.
 - Return to the model only business results, such as rows, numbers, and names. Never return the
   response object, its headers, a token, a proof, or a raw error body.
-- Keep nothing for another turn or another person. The binding ends with the turn, and a task the
-  tool leaves running has no access afterwards.
+- Keep nothing for another turn or another person. The delegation ends with the turn, and a task
+  the tool leaves running acts only as the Agent afterwards.
 - What a tool reads for a person belongs to that person's conversation. Do not write it to shared
   stores, other Agents, or external systems.
 
 People who use such an Agent are told:
 
-> **This Agent works with your identity, securely.** It reads only what you can already read, only
-> to answer your own requests, and for at most 24 hours after you ask. It cannot act as anyone else,
-> cannot change, share or delete anything, never sees your secret values, and stops the moment your
-> access ends. Your Organization's administrator approved it to work this way.
+> **This Agent works with your identity.** It can read, create, change, run,
+> share or delete only what your permissions allow through supported operations,
+> only while serving your request, and for at most 24 hours after you ask. It
+> uses your ordinary permissions, including administrative permissions, and
+> access is checked on every call. Your Organization's administrator approved it
+> to work this way.
+
+The statement describes delegated calls. The Agent's own grants and trusted extension code remain
+separate authority. Prompt injection can cause unintended changes, sharing, or deletion within the
+person's permissions, and completed writes can outlast the delegation. Only Organization admins
+enable this authority.
 
-The limit is plain: while it works on your request, the Agent's code can read what you can read,
-which is why only administrators decide which Agents may work this way.
+For a complete example, a tool that uses a person's Secret without exposing it, and how sharing
+decides what a delegated call can reach, use `tau_security_and_access`.
 
 ## Validation
 

ms_tau_sdk-2.0.7.dev42/src/ms_tau_sdk/agent_skills/tau_security_and_access/SKILL.md

@@ -0,0 +1,244 @@
+---
+name: tau-security-and-access
+description: Build and review project tools that call the platform or other applications for the person a turn serves, including tools that use a person's Secret without exposing it, and explain how delegation and sharing decide what those tools can reach.
+---
+
+# TAU Security and Access
+
+Use this skill when a project tool under `.tau/extensions/` calls the platform or another
+platform application, uses a Secret, or must answer each person with their own data. Extension
+mechanics are in `tau_project_customization`. The full model, with the administrator setup, is in
+the SDK's Security and access guide (`docs/reference/security-model.md`). Sharing itself is in
+`.agents/skills/mainsequence/platform_operations/access_control_and_sharing/SKILL.md`.
+
+## Who a call acts as
+
+Every call a tool makes through `platform_client()` follows one rule:
+
+| The call carries | Permissions used |
+| --- | --- |
+| No delegation | The caller's own: the Agent's workload grants, or in local mode your own login. |
+| A valid delegation | The person the turn serves, with their ordinary permissions, including administrative ones. |
+| A delegation that ended or is invalid | None. The call is refused with a `PermissionError` and is never retried as the Agent. |
+
+- The platform names the person when the turn starts, and `current_requester()` returns them. It
+  returns `None` when the Agent is not enabled to act for people (only an Organization admin can
+  enable it, with `acts_for_requester`), for work no person asked for, in local mode and outside a
+  turn.
+- The operation or application that receives the call decides what it may do. No list says which
+  operations accept a delegation. Read access never implies edit, run, share or delete.
+- The call stays the Agent's call, made for the person. It is not impersonation: the platform
+  checks it on every call, only while the turn or Task serving the person runs, for at most 24
+  hours after their request, and only in the Agent's Environment.
+
+## Choose the delegation for each tool
+
+| The tool | `delegation` |
+| --- | --- |
+| Answers each person with their own data, or uses their credentials | `"required"` |
+| Works for anyone, for the person when the turn serves one | `"auto"` (the default) |
+| Uses only the Agent's own resources, the same for everyone | `"none"` |
+
+With `"required"`, a turn that serves nobody raises a `PermissionError` before anything is sent.
+With `"auto"`, the same tool reaches different things for different people, and the Agent's own
+grants when nobody is served: make sure both are what you intend. Local turns serve nobody, so a
+`"required"` tool refuses in local mode; test it with fakes (see [Testing](#testing)).
+
+## Example: a tool that uses a person's own Secret
+
+A person stores an API key for an outside data provider, and the Agent uses it for them without
+ever seeing it:
+
+1. The person creates the Secret themselves. The Agent never asks for the value or accepts it.
+2. The tool that calls the provider reads the Secret as the person, inside that same call.
+3. The tool uses the value and returns only the result.
+
+```python
+"""Quotes from an outside provider, with each person's own API key."""
+
+import json
+
+import httpx
+from tau_agent.messages import TextContent
+from tau_agent.tools import AgentTool, AgentToolResult
+
+from ms_tau_sdk import current_requester, platform_client
+
+PROVIDER_URL = "https://quotes.example.test/v1/latest"
+
+
+def _text(message):
+    return AgentToolResult(content=[TextContent(text=message)])
+
+
+def _secret_name():
+    # The name comes from the person the platform named, never from the model.
+    person = current_requester()
+    return None if person is None else f"QUOTES_API_KEY__{person.uid}"
+
+
+async def _secret_uid(client, name):
+    # Listing returns names and UIDs, never values. Names are unique in the Agent's Environment.
+    answer = await client.request("GET", "/api/v1/secrets/", params={"name": name})
+    if answer.status_code != 200:
+        return None
+    found = answer.json()["results"]
+    return found[0]["uid"] if found else None
+
+
+async def connect_quotes(tool_call_id, arguments, signal=None, on_update=None):
+    name = _secret_name()
+    if name is None:
+        return _text("I can set up your key only while answering your own request.")
+    try:
+        uid = await _secret_uid(platform_client(delegation="required"), name)
+    except PermissionError:
+        return _text("Your access for this request ended. Please ask again.")
+    if uid is not None:
+        return _text(f"Your key is stored as the Secret {name}.")
+    return _text(
+        f"Create a Secret named {name} with your API key, in the Environment this Agent runs in: "
+        f"on the Secrets page in Command Center, or with `mainsequence secrets create {name}`, "
+        "which asks for the value without showing it. Never paste the key into this chat."
+    )
+
+
+async def latest_quote(tool_call_id, arguments, signal=None, on_update=None):
+    name = _secret_name()
+    if name is None:
+        return _text("I can use your key only while answering your own request.")
+    client = platform_client(delegation="required")
+    try:
+        uid = await _secret_uid(client, name)
+        if uid is None:
+            return _text(f"First create the Secret {name}. Ask me how.")
+        secret = await client.request("GET", f"/api/v1/secrets/{uid}/")
+    except PermissionError:
+        return _text("Your access for this request ended. Please ask again.")
+    if secret.status_code != 200:
+        return _text("I could not read your key.")
+    try:
+        async with httpx.AsyncClient(timeout=10.0) as http:
+            quote = await http.get(
+                PROVIDER_URL,
+                params={"symbol": arguments["symbol"]},
+                headers={"Authorization": f"Bearer {secret.json()['value']}"},
+            )
+    except httpx.HTTPError:
+        # The error can carry the request with its headers: never show it.
+        return _text("The quotes provider did not answer.")
+    if quote.status_code != 200:
+        return _text(f"The quotes provider answered {quote.status_code}.")
+    data = quote.json()
+    return _text(json.dumps({"symbol": data["symbol"], "price": data["price"]}))
+
+
+def setup(tau):
+    tau.register_tool(
+        AgentTool(
+            name="connect_quotes",
+            label="Connect Quotes",
+            description="Check or explain how to store your quotes API key as your own Secret.",
+            parameters={"type": "object", "properties": {}, "additionalProperties": False},
+            execute_fn=connect_quotes,
+        )
+    )
+    tau.register_tool(
+        AgentTool(
+            name="latest_quote",
+            label="Latest Quote",
+            description="Get the latest quote for a symbol with your own quotes API key.",
+            parameters={
+                "type": "object",
+                "properties": {"symbol": {"type": "string"}},
+                "required": ["symbol"],
+                "additionalProperties": False,
+            },
+            execute_fn=latest_quote,
+        )
+    )
+```
+
+What makes it safe:
+
+- No tool takes a Secret value or a Secret name from the model. The name is built from
+  `current_requester().uid`, so prompt injection cannot point the tool at another Secret.
+- `delegation="required"` reads the Secret as the person. The platform returns it only if the
+  person can view it; the name is a lookup key, not the protection.
+- The value exists only inside one call. It never goes into the result, `details`, a log, an
+  exception message, a file or a cache for the next turn. It travels in a header, never in a URL,
+  because URLs reach logs. Errors from the outside call are caught, and the provider's raw body is
+  never returned.
+- There is no tool that returns a Secret value, and no tool that calls any platform path the model
+  chooses. With the delegation, such a tool would let the model read every Secret the person can.
+- The Agent's own workload holds no grant on these Secrets, so a call without the person reaches
+  none of them.
+
+## Sharing decides what a delegated call can reach
+
+A delegated read returns anything the person can view in the Agent's Environment: what they
+created and what others shared with them, directly or through a team. This holds for Secrets and
+every other object. The platform enforces sharing; which of those objects a tool uses is part of
+the tool's design. For Secrets, the naming convention states that design:
+
+- **A personal credential:** a name tied to the person, such as `QUOTES_API_KEY__<person uid>`.
+  The person decides whether to share it.
+- **A team credential:** a name the team agrees on, shared with the team for view. The tool reads
+  it for any member.
+- **Someone else's Secret shared with the person:** valid whenever the tool is meant to use it.
+
+Whoever can edit a Secret decides its value, so the tool uses whatever value they set. Granting or
+accepting edit on a Secret means trusting that person with what the tool does with it. That is a
+decision people make through sharing, not one the platform makes for them.
+
+How sharing works:
+
+- The creator of a Secret can always view and edit it, and cannot be removed from it. People who
+  can edit a Secret can share it, for view or for edit, with people and teams.
+- Most people can share only within the teams they belong to; Organization admins can share
+  across their Organization.
+- `GET /api/v1/secrets/<uid>/can-view/` and `can-edit/` list the people and teams with access. A
+  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.
+
+## What never reaches the model
+
+Tool results, their `details`, and errors can reach the model provider and the session history.
+Never return a Secret value, a token, a proof, an assertion, a response object, its headers or a
+raw error body. Return business results: rows, numbers, names, and plain messages. The SDK already
+keeps its own credentials out of that path and never lets a tool set `Authorization` or an
+`X-MainSequence-*` header.
+
+## Limits
+
+- This works in the Agent's own project tools. An application that receives a delegated call
+  learns the person with `User.get_requester()`, but it cannot call the platform as that person.
+- The delegation ends with the turn. A task the tool leaves running acts as the Agent afterwards,
+  and nothing read for one person may be kept for another turn or another person.
+- When the person's access ends (the turn is over, the access was removed, 24 hours passed, or
+  the Agent is not enabled), calls raise a `PermissionError` whose `code` is
+  `requester_binding_invalid` or starts with `runtime_lease_`. Say in plain words that the request
+  cannot be served, and never retry it as the Agent.
+- Every other answer, such as `403` or `404` for an object the person cannot see, is returned as
+  it is: check the status before using the body.
+
+## Testing
+
+Patch the extension module's `current_requester` and `platform_client` with fakes, and test:
+
+- with a person and the Secret: the result holds only business fields, and the value appears in no
+  result text, `details`, log record or exception;
+- with a person and no Secret: the tool explains how to create it and sends no provider call;
+- with nobody: the tool refuses and sends nothing;
+- a `PermissionError` from the client: a plain message, and no second call;
+- a failing or erroring provider: a plain message without the provider's body or the request.
+
+## Review checklist
+
+- Each tool has a deliberate `delegation`: `"required"` for a person's own data or credentials.
+- No person's UID, Secret name or Secret value comes from tool arguments, the prompt or history.
+- No tool returns a credential or calls a platform path the model chooses.
+- Secret values stay inside one call, in headers, never in results, logs, errors, URLs or caches.
+- The naming convention says whose Secrets the tool uses, and the people sharing them know it.
+- A refused delegated call is reported, never retried as the Agent.
+- The Agent's workload holds no grants it does not need, and none on people's Secrets.