feat(m3): smolagents + claude_agent_sdk bridge for CC subscription

[suzuke]

Summary

Stacked on #12 (M3 PR 18 marketing audit). Adds provider: "claude-subscription" to the smolagents backend so it can drive Claude via CC OAuth credentials (no API key burn).

Best of both worlds: smolagents' strong ACL boundary (CheatResistancePolicy at tool forward()) + CC subscription's auth path.

ACL invariant — the load-bearing pin

claude_agent_sdk.query() is NOT a token completion API — it's a complete agent product that runs its own loop with its own tools. Naive use would re-create the §3.3 agent-loop-in-agent-loop problem and silently void smolagents' ACL.

Fix: configure SDK as a degenerate single-turn text generator:

ClaudeAgentOptions(
    allowed_tools=[],
    disallowed_tools=[Read, Edit, Write, Glob, Grep, Bash,
                      WebFetch, WebSearch, Task, TodoWrite,
                      NotebookEdit, MultiEdit, BashOutput, KillShell],
    max_turns=1,
    can_use_tool=_deny_all_tools,  # defense in depth
)

This is locked in by test_sdk_is_invoked_with_no_internal_tools — patches claude_agent_sdk.query, captures the actual options arg, asserts all 4 invariant properties. If a future SDK update adds a default tool that bypasses disallowed_tools, this test breaks.

Reviewer trail

Round	Verdict	Headline
1 (design)	NEEDS_TWEAK	Q3 critical: my original design treated claude_agent_sdk.query() as a completion API; reviewer corrected — it's a complete agent. Forced single-turn config + invariant test added. Plus 4 didn't-ask items: SDK version pin, cost framing, auth UX, default opt-in.
2 (impl)	VERIFIED	ACL invariant solid, defense-in-depth properly layered, suite numbers match reality. 2 non-blocking: (1) auth classification was string-match coincidence not type-based — fixed via _classify_error_typed() + e2e regression test; (2) docstring claimed usage_source="oauth_estimated" already exists but it's deferred to PR 19a — reworded as future-tense.

Stats

• 2 commits (55d788b + a15b606 R2 fixes)
• 5 files changed (~+725 LOC counting all commits)
• 13 new tests including the critical ACL invariant + auth-classification e2e
• Full suite: 2775 passed + 1 pre-existing failure unchanged + 4 skipped. 0 regressions from PR 19.

Configuration

agent:
  type: smolagents
  smolagents:
    provider: claude-subscription   # NEW M3 PR 19 value
    model: claude-3-5-sonnet-20241022
    # api_key_env: ignored when provider="claude-subscription"

Existing provider: "anthropic" (default) and other LiteLLM providers unchanged.

Known limitations / non-blockers

• usage_source="oauth_estimated" not yet plumbed onto AttemptNode (spec §4.1 enum needs the new value + orchestrator change). Deferred to PR 19a; cost field falls back to orchestrator default for now. Module docstring uses future tense.
• Real-world spike NOT done — the wrapper's correctness is verifiable by the invariant test (we configure correctly), but Claude's behavior when forbidden from using tools is unverified. If real testing surfaces "Claude won't respond when it can't use tools," fix is a system-prompt nudge, not architectural change.
• Anthropic ToS has not publicly endorsed claude_agent_sdk use outside their first-party CC + Claude Code Skills products. Module docstring documents the risk; users should review their CC ToS before relying on this in production.
• Transitional shim — module docstring documents remove-when conditions: smolagents native subscription auth, OR Anthropic publishes a token-completion API path with OAuth.

🤖 Generated with Claude Code