feat(aws-strands): filter the template agent's tools per request

Add `template_tools_provider` / `templateToolsProvider` to
`StrandsAgentConfig`. It is called once per request with that request's
`RunAgentInput` and returns the template tools the request may see, or
nothing to leave every one of them available, so the set can vary turn by
turn on a single thread by caller identity.

The filter is applied to the tool registry the thread's live Strands
`Agent` already owns, the same way client-declared tools are already
synchronised. That instance is load-bearing: it carries the thread's
`SessionManager`, its native interrupt checkpoint and its history, so
rebuilding it to change a tool list would discard a conversation and any
approval waiting inside it. Only the template's own tools are touched, and
only by identity, so a client proxy or an auto-injected A2UI tool sharing
a name is left in place rather than dropped.

Three consequences are pinned by tests. A tool in the batch a live
interrupt checkpoint would resume stays registered whatever the provider
returns, the rule `sync_proxy_tools` already applies to a proxy parked in
a frontend-tool interrupt. History is never rewritten, so a filtered-out
tool's earlier calls and results stay in the thread's messages. A provider
that raises ends the run with `RUN_ERROR` / `TEMPLATE_TOOLS_PROVIDER_ERROR`
rather than degrading to an unfiltered run, matching the per-thread agent
hook beside it.

Author: ranst91

integrations/aws-strands/ARCHITECTURE.md

@@ -150,6 +150,7 @@ This document explains how the AWS Strands integration inside `integrations/aws-
 | `tool_behaviors: Dict[str, ToolBehavior]` | Per-tool overrides keyed by the Strands tool name.                                                                           |
 | `state_context_builder`                   | Callable that enriches the outgoing prompt with the current shared state (useful for reiterating plan steps, recipes, etc.). |
 | `session_manager_provider`                | Factory invoked once per thread to produce a per-thread `SessionManager`.                                                    |
+| `template_tools_provider`                 | Per-request choice of which template tools this request may see, applied to the live per-thread registry.                    |
 | `emit_messages_snapshot`                  | Global opt-out of the four-point `MESSAGES_SNAPSHOT` emission. Default `True`.                                               |
 | `replay_history_into_strands`             | Global opt-out of the per-run Strands history reconciliation. Default `True`.                                                |
 
@@ -206,6 +207,7 @@ typescript/src/
 ├── agent.ts              ← StrandsAgent (port of agent.py)
 ├── client-proxy-tool.ts  ← sync of RunAgentInput.tools into Strands registry
 ├── config.ts             ← StrandsAgentConfig, ToolBehavior, helpers
+├── template-tools.ts     ← per-request filter over the template agent's tools
 ├── endpoint.ts           ← Express route registration + capabilities endpoint
 ├── logger.ts             ← injectable Logger interface + internal default
 ├── session-reconcile.ts  ← port of session_reconcile.py, snapshot-shaped

integrations/aws-strands/error-codes.json

@@ -170,6 +170,12 @@
       "sides": ["python", "typescript"],
       "messages": ["{}"]
     },
+    {
+      "code": "TEMPLATE_TOOLS_PROVIDER_ERROR",
+      "sides": ["python", "typescript"],
+      "messages": ["Failed to resolve the template tools for this request: {}"],
+      "note": "Reported when the per-request template-tools hook throws. Unlike the per-thread agent hook beside it, the option carries one name on both sides (template_tools_provider / templateToolsProvider) and returns the same thing, a selection of the template's tools, so there is one code and one sentence. Terminal rather than degrading to an unfiltered run: the hook exists to withhold tools from a caller, and failing open would hand the model exactly what the caller meant to keep back."
+    },
     {
       "code": "THREAD_AGENT_CONFIG_ERROR",
       "sides": ["typescript"],

integrations/aws-strands/python/README.md

@@ -77,13 +77,14 @@ See [ARCHITECTURE.md](../ARCHITECTURE.md) for diagrams and a deeper dive.
 
 ## Key Files
 
-| File                            | Description                                                                     |
-| ------------------------------- | ------------------------------------------------------------------------------- |
-| `src/ag_ui_strands/agent.py`    | Core wrapper translating Strands streams into AG-UI events                      |
-| `src/ag_ui_strands/config.py`   | Config primitives (`StrandsAgentConfig`, `ToolBehavior`, `PredictStateMapping`) |
-| `src/ag_ui_strands/endpoint.py` | FastAPI endpoint helper                                                         |
-| `src/ag_ui_strands/utils.py`    | `create_strands_app`, multimodal conversion, and `UrlFetchPolicy`               |
-| `examples/server/api/*.py`      | Ready-to-run demo apps                                                          |
+| File                                  | Description                                                                     |
+| ------------------------------------- | ------------------------------------------------------------------------------- |
+| `src/ag_ui_strands/agent.py`          | Core wrapper translating Strands streams into AG-UI events                      |
+| `src/ag_ui_strands/config.py`         | Config primitives (`StrandsAgentConfig`, `ToolBehavior`, `PredictStateMapping`) |
+| `src/ag_ui_strands/template_tools.py` | Per-request filter over the template agent's tools                              |
+| `src/ag_ui_strands/endpoint.py`       | FastAPI endpoint helper                                                         |
+| `src/ag_ui_strands/utils.py`          | `create_strands_app`, multimodal conversion, and `UrlFetchPolicy`               |
+| `examples/server/api/*.py`            | Ready-to-run demo apps                                                          |
 
 ## Amazon Bedrock AgentCore considerations
 
@@ -198,6 +199,66 @@ trusted values from client-controlled `forwarded_props`; derive them from
 authenticated request context instead. Custom routes can pass the same state
 directly with `agent.run(input_data, invocation_state={...})`.
 
+## Per-request tool filtering
+
+`StrandsAgentConfig.template_tools_provider` decides which of the template
+agent's tools one request may see. It is called once per request with that
+request's `RunAgentInput`, so the answer can vary turn by turn on a single
+thread:
+
+```python
+from ag_ui.core import RunAgentInput
+from ag_ui_strands import StrandsAgent, StrandsAgentConfig
+
+READ_ONLY = ["search_docs", "get_order"]
+
+def tools_for(input_data: RunAgentInput):
+    # Derive the role from authenticated request context in production;
+    # forwarded_props is client-controlled.
+    if (input_data.forwarded_props or {}).get("role") == "admin":
+        return None  # no filtering: every template tool stays available
+    return READ_ONLY
+
+agui_agent = StrandsAgent(
+    strands_agent,
+    name="assistant",
+    config=StrandsAgentConfig(template_tools_provider=tools_for),
+)
+```
+
+Return the tools themselves or their names. `None` declines to filter; an empty
+list is a real answer and withholds all of them. A name the template does not
+contribute is dropped with a warning, because the hook narrows the wrapped
+agent's tools and cannot add one. The provider may be async.
+
+The filter is applied to the tool registry the thread's live Strands `Agent`
+already owns, the same way client-declared tools are synchronised, and never by
+rebuilding that agent. The per-thread instance holds the thread's
+`SessionManager`, its native interrupt checkpoint and its history, so replacing
+it to change a tool list would discard a conversation and any approval waiting
+inside it.
+
+Three consequences follow from that:
+
+- **A parked call is never orphaned.** A tool in the batch a live interrupt
+  checkpoint would resume stays registered whatever the provider returns: the
+  human's answer is about to be routed back into that batch, and an absent tool
+  turns it into a "tool not found" the model re-fires. Filtering resumes once
+  the pause closes. This is the rule `sync_proxy_tools` already applies to a
+  proxy parked in a frontend-tool interrupt.
+- **History is never rewritten.** A filtered-out tool's earlier calls and
+  results stay in the thread's messages, so the model can still read what it
+  did with a tool it can no longer call.
+- **A failure is terminal.** If the provider raises, the run yields `RUN_ERROR`
+  with code `TEMPLATE_TOOLS_PROVIDER_ERROR` and stops, matching
+  `thread_agent_kwargs`. A filter that failed open would hand the model exactly
+  the tools the caller meant to withhold.
+
+Scope is the template's own tools. Client-declared tools on
+`RunAgentInput.tools` are re-synchronised from the request every turn already,
+so a caller that wants fewer of those sends fewer. The hook is not applied on
+the multi-agent orchestrator path, which has no template registry to filter.
+
 ## Human-in-the-loop (native Strands interrupts)
 
 Python frontend tools explicitly configured with

integrations/aws-strands/python/src/ag_ui_strands/__init__.py

@@ -18,6 +18,7 @@
 )
 from .citations import CITATIONS_METADATA_KEY
 from .client_proxy_tool import create_proxy_tool, sync_proxy_tools
+from .template_tools import sync_template_tools
 from .utils import (
     DEFAULT_URL_FETCH_POLICY,
     InvocationStateProvider,
@@ -34,6 +35,7 @@
     ToolStreamEventContext,
     PredictStateMapping,
     SessionManagerProvider,
+    TemplateToolsProvider,
     ToolStreamEventHandler,
 )
 from ag_ui.core import (
@@ -57,6 +59,7 @@
     "CITATIONS_METADATA_KEY",
     "create_proxy_tool",
     "sync_proxy_tools",
+    "sync_template_tools",
     "create_strands_app",
     "UrlFetchPolicy",
     "UrlFetchPolicyError",
@@ -71,6 +74,7 @@
     "ToolStreamEventContext",
     "PredictStateMapping",
     "SessionManagerProvider",
+    "TemplateToolsProvider",
     "ToolStreamEventHandler",
     "Interrupt",
     "ResumeEntry",

integrations/aws-strands/python/src/ag_ui_strands/agent.py

@@ -1364,6 +1364,10 @@ def _error_events(
     sync_proxy_tools,
     waits_for_frontend_call,
 )
+from .template_tools import (
+    parked_batch_tool_names,
+    sync_template_tools,
+)
 from .frontend_tool_interrupt import (
     frontend_tool_response_schema,
     index_frontend_tool_interrupts,
@@ -4156,6 +4160,38 @@ async def _run_raw(
         except Exception as e:
             logger.warning(f"Failed to set agui_context on strands_agent.state: {e}")
 
+        # Filter the tools the template contributed, per request. Applied to
+        # the registry this thread's live agent already owns: that instance
+        # carries the thread's session manager, its interrupt checkpoint and
+        # its history, so rebuilding it to change a tool list would discard a
+        # conversation and any approval waiting inside it.
+        if self.config.template_tools_provider is not None:
+            try:
+                template_tool_selection = await maybe_await(
+                    self.config.template_tools_provider(input_data)
+                )
+            except Exception as e:  # noqa: BLE001 - surfaced as RUN_ERROR
+                logger.error(
+                    "template_tools_provider failed: %s", e, exc_info=True
+                )
+                # Deliberately terminal rather than unfiltered: a filter that
+                # fails open hands the model tools the caller meant to withhold.
+                ev_started, ev_error = _error_events(
+                    input_data,
+                    "Failed to resolve the template tools for this request: "
+                    f"{e}",
+                    "TEMPLATE_TOOLS_PROVIDER_ERROR",
+                )
+                yield ev_started
+                yield ev_error
+                return
+            sync_template_tools(
+                strands_agent.tool_registry,
+                self._tools,
+                template_tool_selection,
+                exempt_names=parked_batch_tool_names(strands_agent),
+            )
+
         # Sync proxy tools from client-defined tools. A proxy parked in a live
         # frontend-tool interrupt is exempt from removal: Strands is about to
         # resume that tool, and an absent registry entry turns the client's

integrations/aws-strands/python/src/ag_ui_strands/config.py

@@ -139,6 +139,16 @@ class ToolBehavior:
 """
 
 
+TemplateToolsProvider = Callable[
+    ["RunAgentInput"],
+    Awaitable[Optional[Iterable[Any]]] | Optional[Iterable[Any]],
+]
+"""Chooses which of the template's tools one request may see.
+
+See :attr:`StrandsAgentConfig.template_tools_provider`.
+"""
+
+
 @dataclass
 class StrandsAgentConfig:
     """Top-level configuration for the Strands agent adapter."""
@@ -169,6 +179,57 @@ class StrandsAgentConfig:
     the run yields ``RUN_ERROR`` and the thread is not cached, so the next
     request retries it.
     """
+    template_tools_provider: Optional["TemplateToolsProvider"] = None
+    """Which of the template agent's tools this request may see.
+
+    Called once per request with that request's ``RunAgentInput``, so the answer
+    can vary turn by turn on one thread: the caller's identity is in
+    ``forwarded_props`` or ``context``, and a tool the request must not reach is
+    simply left out of the returned iterable. May be async.
+
+    Return the tools themselves or their names, whichever is to hand. Return
+    ``None`` to decline filtering, which leaves every template tool available;
+    an empty iterable is a real answer and leaves none of them. A name the
+    template does not contribute is dropped with a warning, because this hook
+    narrows the wrapped agent's tools and cannot add one.
+
+    Applied to the live per-thread agent's tool registry, never by rebuilding
+    that agent: the instance holds the thread's ``SessionManager``, its native
+    interrupt checkpoint and its history, so replacing it to change a tool list
+    would discard a conversation and any approval waiting inside it.
+
+    Three consequences worth knowing:
+
+    - A tool in the batch a live interrupt checkpoint would resume stays
+      registered whatever this returns. The human's answer is about to be
+      routed back into that batch, and an absent tool turns it into a "tool not
+      found" the model re-fires. Filtering resumes once the pause closes. This
+      is the rule ``sync_proxy_tools`` already applies to a proxy parked in a
+      frontend-tool interrupt.
+    - History is never rewritten. A filtered-out tool's earlier calls and
+      results stay in the thread's messages, so the model can still read what
+      it did with a tool it can no longer call, and a provider that returns
+      different sets across turns does not invalidate the transcript.
+    - If it raises, the run yields ``RUN_ERROR`` with code
+      ``TEMPLATE_TOOLS_PROVIDER_ERROR`` and stops, matching
+      ``thread_agent_kwargs``. A filter that fails open would hand the model
+      tools the caller meant to withhold.
+
+    Client-declared tools on ``RunAgentInput.tools`` are outside this hook:
+    they are re-synchronised from the request every turn already, so a caller
+    that wants fewer of those sends fewer. Not applied on the multi-agent
+    orchestrator path, which has no template registry to filter.
+
+    Example::
+
+        StrandsAgentConfig(
+            template_tools_provider=lambda input_data: (
+                ["read_docs"]
+                if (input_data.forwarded_props or {}).get("role") != "admin"
+                else None
+            )
+        )
+    """
     session_manager_provider: Optional[SessionManagerProvider] = None
     """Optional factory for creating per-thread SessionManager instances.