Sunset --with-websearch when Databricks FMAPI ships native web_search/web_fetch for Anthropic

[IceRhymers]

Summary

--with-websearch (added in #142, shipped in v0.18.0) is an explicit workaround for the Databricks FMAPI gap on Anthropic's web_search / web_fetch server-side tools. It locally fulfills these tools and SSE-rewrites the response to look byte-shape-identical to native Anthropic.

When Databricks FMAPI ships native server-side web_search / web_fetch support for Anthropic models, this workaround needs to deprecate cleanly so customers don't end up double-fulfilling (proxy + native) and so we don't carry dead weight forever.

Note: Codex/GPT already gets native web tools through FMAPI today. This issue is scoped to the Anthropic path only — i.e. databricks-claude.

Background

• The workaround entry points are --with-websearch, --websearch-backend, --websearch-fetch-budget, persisted to ~/.claude/.databricks-claude.json.
• Implementation surface to remove eventually:
  • pkg/websearch/ (DuckDuckGo backend, Fetch, Robots)
  • pkg/proxy/sse_rewriter.go + sse_rewriter_test.go
  • pkg/proxy/anthropic/ (only if no other consumer adopts it — likely keep, the Extras roundtrip pattern is reusable)
  • pkg/proxy/websearch_handler.go (request-side rewrite + Lane 2 fallback)
  • websearch.go, state.go web_search fields
  • main.go flag wiring + the stderr workaround warning
  • README "Web Search & Fetch (Workaround)" section
• See feat: --with-websearch — local fulfillment of Anthropic web_search/web_fetch (workaround for FMAPI gap) #141 (final design, "Approach: SSE event rewriting") and feat: --with-websearch — local fulfillment of web_search/web_fetch (workaround) #142 (PR) for full context.

Proposed sunset arc

Phase A — Detect native support

Add a startup probe (or first-real-request probe) that issues a minimal /v1/messages with a real web_search_20250305 tool entry against the configured AI Gateway. If the upstream returns 200 instead of the current "unsupported tool type" error, flag the workspace as having native support.

Cache the result per-workspace in ~/.claude/.databricks-claude.json with a TTL (e.g. 7 days) so we don't probe on every invocation. Re-probe if the user passes --with-websearch and we haven't probed recently.

Phase B — Deprecation grace (one minor release)

When native support is detected:

• Print a stderr warning on every invocation while --with-websearch=true:

  databricks-claude: --with-websearch is no longer needed — your Databricks
  workspace now supports native web_search/web_fetch tools through FMAPI.
  Remove the --with-websearch flag (and any persisted setting via
  --with-websearch=false) to use the native path.
  This flag will be removed in the next minor release.
  

• Optionally short-circuit the workaround when native support is detected: forward the request unmolested even if --with-websearch=true. Decision pending — preserves opt-out symmetry but might surprise users who want the workaround for other reasons (e.g. a backend they prefer).

Phase C — Removal

In the next minor release after Phase B ships:

• Remove the flag, the warning, and the implementation surface listed above.
• BREAKING CHANGE: footer on the conventional commit so release-please cuts a major bump (per the project's release-please config).
• If users still pass --with-websearch on the CLI, the standard "unknown flag" error from flag.Parse is sufficient — no special handling needed.
• Update README to remove the workaround section; add a one-line note in CHANGELOG pointing at the removed flag and the native FMAPI path.

Out of scope

• Codex / GPT path. FMAPI already supports web tools for GPT models natively; databricks-codex never needed this workaround.
• Opencode. Demand is too low to justify a port; if requested later, the pkg/websearch and pkg/proxy/sse_rewriter.go are self-contained and portable.
• The pkg/proxy/anthropic package. The Request/Response Extras-roundtrip pattern is generally useful and likely stays even after the workaround is removed — decide at removal time.

Acceptance criteria

When this issue gets picked up:

• Phase A probe implemented and tested against both states (workspace with native support, workspace without).
• Phase B deprecation warning shipped in one minor release and announced in CHANGELOG.
• Phase C removal lands as a single PR with BREAKING CHANGE: footer; release-please cuts a major bump.
• All four flags (--with-websearch, --websearch-backend, --websearch-fetch-budget) removed.
• Persistent state migration: when removing the flag, also strip the now-defunct keys from ~/.claude/.databricks-claude.json so existing user state doesn't carry orphan fields forever.
• README workaround section removed.
• No regression in the non-workaround path (already covered by existing byte-identical pass-through tests).

Trigger

Open as a tracking issue. Don't act on it until FMAPI native web_search support is confirmed available. When that happens, drop a comment here with the FMAPI version / date and start Phase A.