Enforce per-tool approval flags + 3LO oauth_required for Gateway (protocol=mcp) tools

[philmerrell]

Summary

Follow-up to #419 (admin-managed AgentCore Gateway target registration). #419 shipped deliberately with zero new agent-side runtime code, so for protocol=mcp (Gateway) tools the catalog stores per-tool approval flags and requires_oauth_provider, but nothing enforces them at runtime. This issue tracks the agent-side wiring to actually enforce both.

Today both mechanisms are wired only for mcp_external tools.

⛔ Dependency

Backend for #419 is merged to develop (#450, #452, #453). This builds on the MCPGatewayConfig model + the protocol=mcp catalog rows it produces.

The enabling prerequisite (do this first)

Gateway tools currently bypass the catalog entirely at runtime — they surface straight from the Gateway discovery path as gateway_<target>___<tool> and RBAC is AppRole-based by that full id (apis/app_api/admin/services/tool_access.py). For either feature below to work, the agent loop must correlate a runtime gateway tool with its protocol=mcp catalog row (by target/tool name). That correlation unlocks both features at once.

Scope

1. Per-tool approval flags for gateway tools

• Extend GatewayIntegration (agents/main_agent/tools/gateway_integration.py) to expose approval_names_for_client() mirroring ExternalMCPIntegration.approval_names_for_client(), populated from the catalog row's mcp_gateway_config.approval_required_names() at client-creation time.
• Add a gateway path to the approval-hook lookup closure in base_agent.py (today MCPExternalApprovalHook resolves only mcp_external clients).
• Gotcha: the catalog's tools[].name must match the raw MCP tool name, not the prefixed gateway_* id.

2. oauth_required (3LO) consent for gateway tools

• Extend GatewayIntegration to track provider_id per client (from the row's requires_oauth_provider), and add gateway to the provider_lookup closure in base_agent.py. The existing OAuthConsentHook + oauth_required SSE machinery (session/hooks/oauth_consent.py) then works unchanged — it just needs the lookup to cover gateway clients.
• Verify against a live target: that outbound 3LO via the Gateway needs the user's vaulted token present before the Gateway's on-behalf-of exchange (i.e. consent must complete first). Confirm customParameters used at consent match those on the registered target (token-vault-key gotcha).

Out of scope

• Credential-provider provisioning (still reference-by-ARN, per Admin-managed AgentCore Gateway target registration (protocol=mcp) #419).
• Until this lands, OAuth Gateway targets work by having the user pre-connect the provider via the Connectors page.

🤖 Generated with Claude Code

[rpelevin]

I would make the runtime correlation record the first deliverable, because it unlocks both approval_required and oauth_required without duplicating Gateway logic.

For each discovered Gateway MCP tool, persist a catalog binding:

• gateway target id;
• raw MCP tool name;
• runtime tool id / gateway-prefixed name;
• catalog row id;
• approval_required flag/policy id;
• oauth provider id;
• customParameters digest used for the target;
• client/session id.

Then the approval hook and OAuth consent hook should both resolve from that same binding before the tool is callable.

Acceptance tests:

1. protocol=mcp gateway tool with approval_required pauses before execution.
2. the same raw tool name under another target does not share approval policy accidentally.
3. requires_oauth_provider blocks execution until the user's consent token is available.
4. changed Gateway target customParameters invalidates the old binding.
5. missing catalog binding fails closed instead of executing as an ungoverned gateway tool.

That keeps Gateway discovery dynamic while making the catalog the authority source for runtime enforcement.