fix(agents): raise OAuth consent interrupt for skill-folded external MCP tools

[philmerrell]

Problem

In skills mode (now the server default, agent_type="skill"), invoking a skill whose bound external MCP tool has no active OAuth authorization (e.g. "Gmail for employees" with no Gmail token in the vault) produced a text apology from the model instead of pausing the turn with the in-conversation consent prompt.

Root cause: OAuthConsentHook's provider_lookup only resolves when event.selected_tool is an MCPAgentTool. In skills mode the model calls the skill_executor meta-tool (a decorated function tool) — the real target only appears in the tool-use input ({skill_name, tool_name, ...}) — so the gate concluded "not OAuth-gated", the FoldedMCPTool ran call_tool_sync tokenless, and the auth error surfaced as tool text. No Strands interrupt → no pending_interrupt → no oauth_required SSE event.

A compounding bug: FoldedMCPTool.invoke swallowed all failures into success-status strings, so the hook's 401-retry heuristic (gated on status == "error") was also dead for folded tools — even the expired-token refresh path.

Fix

• oauth_consent.py — optional tool_use_provider_lookup: a second-chance resolver receiving the raw tool_use dict, consulted by both the consent gate and the 401-retry handler when provider_lookup returns None. Plain chat wiring passes None → behavior unchanged.
• skills/mcp_binding.py — make_folded_tool_provider_lookup(registry, provider_for_client): executor tool_use input → bound FoldedMCPTool → owning client → provider id. Gateway clients resolve to None (SigV4, not user OAuth). FoldedMCPTool.invoke now returns a ToolResult-shaped {"status": "error", ...} on failure (Strands' @tool decorator passes status+content dicts through), so error status survives the fold.
• base_agent.py / skill_agent.py — new _build_tool_use_provider_lookup() hook point (base returns None); SkillAgent overrides it with its registry + the external MCP integration.

Resume path is unchanged: the interrupt is raised on the skill_executor call itself, so consent → interrupt_responses → token-cache warm → the client's lazy token provider injects the bearer on the actual MCP request.

Tests

• TestOAuthConsentHookSkillFoldedTools — skill-bound tool with no token → InterruptException with the exact oauth_required reason; cached token proceeds; 401-through-the-fold clears cache and retries; no-lookup preserves old behavior.
• TestFoldedToolProviderLookup — resolver against a real SkillRegistry (unknown skill/tool, local non-folded tools, unmapped clients, malformed input).
• TestToolUseProviderLookupWiring — SkillAgent hands the hook a working resolver.
• FoldedMCPTool error-status preservation (exception + error-status MCP result).

Full backend suite: 3820 passed, 3 skipped (pytest is not run in CI; local suite is the gate).

Out of scope (flagged separately)

MCPExternalApprovalHook has the identical hole — needs_approval=True tools bound to a skill bypass the approval prompt. Tracked as a follow-up task using the same tool_use fallback pattern.

🤖 Generated with Claude Code