Use Claude Code, Codex, VSCode, Pi, and OpenCode (and 6 other harnesses) for free (1.3B+ free tokens) from your terminal, app, IDE, or phone, and now from the browser with native browser sessions (multi-harness + multi-model) like OpenClaw (voice supported + ToS friendly)
Python
Make Claude web search automatic through every provider (#1476)
Ali Khokhar9ffcf9ad22c8
diff --git a/.env.example b/.env.exampleindex fd46e625..afdaf61f 100644--- a/.env.example+++ b/.env.example@@ -380,8 +380,8 @@ ENABLE_SUGGESTION_MODE_SKIP=trueENABLE_FILEPATH_EXTRACTION_MOCK=true-# Local Anthropic web_search / web_fetch handling (outbound HTTP; disabled by default)-ENABLE_WEB_SERVER_TOOLS=false+# Claude Code WebSearch and forced local web-tool handling (set false to opt out)+ENABLE_WEB_SERVER_TOOLS=trueWEB_FETCH_ALLOWED_SCHEMES=http,httpsWEB_FETCH_ALLOW_PRIVATE_NETWORKS=falsediff --git a/ARCHITECTURE.md b/ARCHITECTURE.mdindex c8404134..2e517deb 100644--- a/ARCHITECTURE.md+++ b/ARCHITECTURE.md@@ -1199,16 +1199,31 @@ sequences remain on the request so a target converter can preserve them or rejecthe request as lossy. This policy belongs to the Claude Messages boundary, neverto an OpenAI provider or model-specific adapter.-Local `web_search` and `web_fetch` handling lives under-[api/web_tools/](src/free_claude_code/api/web_tools/). When `ENABLE_WEB_SERVER_TOOLS` is true, the-Messages handler can stream local Anthropic server-tool responses without sending the-request upstream. [api/web_tools/egress.py](src/free_claude_code/api/web_tools/egress.py) enforces URL-scheme and private-network restrictions for `web_fetch`.--Anthropic server-tool definitions are never passed to upstream OpenAI Chat-providers because that conversion would be lossy. Forced `web_search` or-`web_fetch` requests are handled locally when `ENABLE_WEB_SERVER_TOOLS` is true;-otherwise the Messages handler rejects them before provider execution.+Local `web_search` and `web_fetch` compatibility lives under+[api/web_tools/](src/free_claude_code/api/web_tools/). It is enabled by default+and can be disabled with `ENABLE_WEB_SERVER_TOOLS=false`. Forced+`web_search_20250305` and `web_fetch_20250910` requests bypass the provider and+retain the existing local result lifecycle. [api/web_tools/egress.py](src/free_claude_code/api/web_tools/egress.py)+continues to own URL-scheme and private-network restrictions for forced+`web_fetch`.++Current Claude Code uses a separate subordinate Messages request when its outer+`WebSearch` tool is available. For the exact request containing only+`web_search_20250305` with omitted or automatic tool choice, the Messages+boundary translates that server tool into one private ordinary search function.+`ProviderExecutor` runs and buffers one normal provider decision, preserving its+retry, fallback, timeout, and failure behavior. If the model declines the tool,+FCC replays the buffered stream unchanged. If the model selects one valid query,+FCC discards the private function frames, searches the fixed DuckDuckGo backend,+and emits the existing Anthropic `server_tool_use` and+`web_search_tool_result` lifecycle. Claude Code owns the outer continuation; FCC+does not run a second provider round or persist hidden transcript state.++Other Anthropic server-tool shapes remain fail-closed before provider execution:+automatic WebFetch, mixed tool lists, newer unverified versions, prior hosted+server-tool history, and extra choice semantics are not generalized. This keeps+the compatibility exception at the Messages/API boundary rather than leaking+server-tool semantics into providers or the executor.## CLI Launchers And Managed Claudediff --git a/pyproject.toml b/pyproject.tomlindex 234e9e0c..012ab042 100644--- a/pyproject.toml+++ b/pyproject.toml@@ -4,7 +4,7 @@ build-backend = "hatchling.build"[project]name = "free-claude-code"-version = "5.8.0"+version = "5.8.1"description = "Local proxy connecting coding agents to OpenAI-compatible AI providers"readme = "README.md"requires-python = ">=3.14.0"diff --git a/smoke/README.md b/smoke/README.mdindex aa1aadcc..2fc93ffe 100644--- a/smoke/README.md+++ b/smoke/README.md@@ -55,7 +55,7 @@ Default targets do not send real bot messages or load voice backends:| --- | --- | --- || `api` | messages, count_tokens full payload, errors, `/stop`, optimizations | configured provider only for streaming messages || `auth` | canonical bearer auth, conflicting legacy headers, invalid/missing auth | none; test sets an isolated token |-| `cli` | server entrypoint, Claude CLI adaptive thinking, Auto-mode classifier, session cleanup | Claude CLI binary and provider only for real CLI; connected OpenAI account for Auto mode |+| `cli` | server entrypoint, Claude CLI adaptive thinking, automatic WebSearch, Auto-mode classifier, session cleanup | Claude CLI binary and provider only for real CLI; connected OpenAI account for Auto mode; `FCC_SMOKE_RUN_WEB_TOOLS=1` for WebSearch || `clients` | VS Code and JetBrains protocol payloads; Pi, OpenCode, and Cline CLI prompts | configured provider; installed Pi/OpenCode/Cline binaries for their CLI scenarios || `config` | env precedence, removed-env migration, proxy/timeouts | none || `extensibility` | provider runtime and platform factory construction | none |@@ -151,6 +151,9 @@ uv run pytest smoke/product -n 0 -s --tb=shortfree CLI matrix models appended to the default or replacement set.- `FCC_SMOKE_TIMEOUT_S`: per-request/subprocess timeout, default `45`.- `FCC_SMOKE_CLAUDE_BIN`: Claude CLI executable name, default `claude`.+- `FCC_SMOKE_RUN_WEB_TOOLS=1`: enables the combined real-provider automatic+ WebSearch and installed Claude Code WebSearch scenario, including a public+ DuckDuckGo request.- `FCC_SMOKE_TELEGRAM_CHAT_ID`: Telegram chat/user ID for send/edit/delete.- `FCC_SMOKE_DISCORD_CHANNEL_ID`: Discord channel ID for send/edit/delete.- `FCC_SMOKE_INTERACTIVE=1`: enables manual inbound Telegram/Discord checks.diff --git a/smoke/capabilities.py b/smoke/capabilities.pyindex 531ac2e3..59785cd4 100644--- a/smoke/capabilities.py+++ b/smoke/capabilities.py@@ -53,8 +53,15 @@ CAPABILITY_CONTRACTS: tuple[CapabilityContract, ...] = ("Claude Code, VS Code, and JetBrains shaped requests","compatible streaming response","provider or validation error in Anthropic shape",- ("tests/api/test_api.py", "tests/cli/test_cli.py"),- ("test_vscode_and_jetbrains_shaped_requests",),+ (+ "tests/api/test_api.py",+ "tests/api/test_web_server_tools.py",+ "tests/cli/test_cli.py",+ ),+ (+ "test_vscode_and_jetbrains_shaped_requests",+ "test_claude_cli_web_search_e2e",+ ),),CapabilityContract("api_compatibility",@@ -498,9 +505,10 @@ CAPABILITY_CONTRACTS: tuple[CapabilityContract, ...] = ("Claude CLI binary and proxy env","stream-json events and session id mapping","stderr/error event and process cleanup",- ("tests/cli/test_cli.py",),+ ("tests/api/test_web_server_tools.py", "tests/cli/test_cli.py"),("test_claude_cli_prompt_when_available",+ "test_claude_cli_web_search_e2e","test_claude_cli_provider_error_e2e","test_nvidia_nim_cli_matrix_e2e","test_openrouter_free_cli_matrix_e2e",diff --git a/smoke/features.py b/smoke/features.pyindex 0a61ea73..5f49009b 100644--- a/smoke/features.py+++ b/smoke/features.py@@ -40,11 +40,16 @@ FEATURE_INVENTORY: tuple[FeatureCoverage, ...] = (FeatureCoverage("drop_in_claude_code_replacement","Claude-compatible API, CLI, and editor protocol flows work",- ("tests/api/test_api.py", "tests/cli/test_cli.py"),+ (+ "tests/api/test_api.py",+ "tests/api/test_web_server_tools.py",+ "tests/cli/test_cli.py",+ ),("test_probe_and_models_routes", "test_claude_cli_prompt_when_available"),("test_api_basic_conversation_e2e","test_claude_cli_adaptive_thinking_e2e",+ "test_claude_cli_web_search_e2e","test_claude_cli_provider_error_e2e","test_nvidia_nim_cli_matrix_e2e","test_openrouter_free_cli_matrix_e2e",@@ -441,10 +446,11 @@ FEATURE_INVENTORY: tuple[FeatureCoverage, ...] = (FeatureCoverage("claude_cli_drop_in","Claude CLI can send adaptive thinking and tool-shaped history",- ("tests/cli/test_cli.py",),+ ("tests/api/test_web_server_tools.py", "tests/cli/test_cli.py"),("test_claude_cli_prompt_when_available",),("test_claude_cli_adaptive_thinking_e2e",+ "test_claude_cli_web_search_e2e","test_claude_cli_multiturn_tool_protocol_e2e","test_nvidia_nim_cli_matrix_e2e","test_openrouter_free_cli_matrix_e2e",diff --git a/smoke/product/test_client_product_live.py b/smoke/product/test_client_product_live.pyindex 9c2b17de..dc2f2c65 100644--- a/smoke/product/test_client_product_live.py+++ b/smoke/product/test_client_product_live.py@@ -302,6 +302,99 @@ def test_claude_cli_adaptive_thinking_e2e(assert "FCC_SMOKE_CLI" in result.stdout[email protected]_target("cli")+def test_claude_cli_web_search_e2e(smoke_config: SmokeConfig, tmp_path: Path) -> None:+ if os.environ.get("FCC_SMOKE_RUN_WEB_TOOLS") != "1":+ pytest.skip("missing_env: set FCC_SMOKE_RUN_WEB_TOOLS=1")+ claude_bin = shutil.which(smoke_config.claude_bin)+ if not claude_bin:+ pytest.skip(f"missing_env: Claude CLI not found: {smoke_config.claude_bin}")+ provider_model = ProviderMatrixDriver(smoke_config).first_model()++ with SmokeServerDriver(+ smoke_config,+ name="product-claude-cli-web-search",+ env_overrides={+ "MODEL": provider_model.full_model,+ "MESSAGING_PLATFORM": "none",+ "ENABLE_WEB_SERVER_TOOLS": "true",+ "LOG_LEVEL": "DEBUG",+ },+ ).run() as server:+ automatic_turn = ConversationDriver(server, smoke_config).stream(+ {+ "model": provider_model.full_model,+ "max_tokens": 512,+ "messages": [+ {+ "role": "user",+ "content": (+ "You must use the available web search tool to find the "+ "Free Claude Code GitHub repository."+ ),+ }+ ],+ "tools": [+ {+ "name": "web_search",+ "type": "web_search_20250305",+ }+ ],+ "tool_choice": {"type": "auto"},+ }+ )+ run = run_claude_cli(+ claude_bin=claude_bin,+ server=server,+ config=smoke_config,+ cwd=tmp_path,+ bare=False,+ prompt=(+ "Use WebSearch exactly once to find the Free Claude Code GitHub "+ "repository. Then reply with FCC_SMOKE_WEB_SEARCH and one source URL."+ ),+ tools="WebSearch",+ )+ server_log = server.log_path.read_text(encoding="utf-8", errors="replace")++ assert run.timed_out is False, run.combined_output+ assert run.returncode == 0, run.combined_output+ assert "FCC_SMOKE_WEB_SEARCH" in run.combined_output+ assert "http" in run.combined_output+ automatic_payload = json.dumps(+ [event.data for event in automatic_turn.events], sort_keys=True+ )+ assert '"type": "server_tool_use"' in automatic_payload+ assert '"type": "web_search_tool_result"' in automatic_payload+ assert "github.com" in automatic_payload+ log_rows = _json_object_lines(server_log)+ assert (+ sum(+ row.get("event") == "free_claude_code.api.web_search.automatic_recognized"+ for row in log_rows+ )+ == 1+ ), server_log+ assert any(+ row.get("event") == "free_claude_code.api.optimization.web_server_tool"+ for row in log_rows+ ), server_log+ assert (+ sum(+ row.get("event") == "free_claude_code.api.web_search.automatic_selected"+ for row in log_rows+ )+ == 1+ ), server_log+ assert (+ sum(+ row.get("event") == "free_claude_code.api.web_search.automatic_completed"+ for row in log_rows+ )+ == 1+ ), server_log++@pytest.mark.smoke_target("cli")def test_claude_auto_mode_openai_connected_e2e(smoke_config: SmokeConfig, tmp_path: Pathdiff --git a/src/free_claude_code/api/handlers/messages.py b/src/free_claude_code/api/handlers/messages.pyindex 15873026..fcafd337 100644--- a/src/free_claude_code/api/handlers/messages.py+++ b/src/free_claude_code/api/handlers/messages.py@@ -23,12 +23,16 @@ from free_claude_code.api.response_streams import (terminal_execution_error_response,trace_terminal_execution_error,)+from free_claude_code.api.web_tools.automatic_search import (+ stream_automatic_web_search_response,+)from free_claude_code.api.web_tools.egress import (WebFetchEgressPolicy,web_fetch_allowed_scheme_set,)from free_claude_code.api.web_tools.request import (is_web_server_tool_request,+ plan_automatic_web_search,unsupported_server_tool_error,)from free_claude_code.api.web_tools.streaming import stream_web_server_tool_response@@ -103,9 +107,29 @@ class MessagesHandler:require_non_empty_messages(request_data.messages)routed = self._model_router.resolve_messages_request(request_data)routed = self._apply_message_routing_policies(routed)- self._reject_unsupported_server_tools(routed)-- result = self._run_message_intercepts(routed)+ automatic_search = plan_automatic_web_search(+ routed.request,+ web_tools_enabled=self._settings.enable_web_server_tools,+ )+ if automatic_search is None:+ self._reject_unsupported_server_tools(routed)+ result = self._run_message_intercepts(routed)+ else:+ input_tokens = self._token_counter(+ routed.request.messages,+ routed.request.system,+ routed.request.tools,+ )+ result = _MessagesStreamResult(+ stream_automatic_web_search_response(+ self._provider_executor,+ routed,+ automatic_search,+ request_id=request_id,+ fallback_input_tokens=input_tokens,+ verbose_client_errors=self._settings.log_api_error_tracebacks,+ )+ )if result is None:logger.debug("No optimization matched, routing to provider")result = _MessagesStreamResult(diff --git a/src/free_claude_code/api/web_tools/automatic_search.py b/src/free_claude_code/api/web_tools/automatic_search.pynew file mode 100644index 00000000..4478afdd--- /dev/null+++ b/src/free_claude_code/api/web_tools/automatic_search.py@@ -0,0 +1,234 @@+"""One provider decision for Claude Code's automatic WebSearch request."""++import sys+from collections.abc import AsyncIterator, Mapping+from dataclasses import replace+from urllib.parse import urlsplit++from free_claude_code.application.execution import ProviderExecutor+from free_claude_code.application.routing import RoutedMessagesRequest+from free_claude_code.core.anthropic import (+ aggregate_anthropic_sse_to_message,+ anthropic_status_for_error_type,+)+from free_claude_code.core.failures import ExecutionFailure, FailureKind+from free_claude_code.core.trace import close_stream_input, trace_event++from .request import (+ HIDDEN_WEB_SEARCH_NAME,+ AutomaticWebSearchPlan,+ WebSearchDomainFilter,+)+from .streaming import stream_selected_web_search_response+++async def stream_automatic_web_search_response(+ provider_executor: ProviderExecutor,+ routed: RoutedMessagesRequest,+ plan: AutomaticWebSearchPlan,+ *,+ request_id: str,+ fallback_input_tokens: int,+ verbose_client_errors: bool,+) -> AsyncIterator[str]:+ """Buffer one model decision, then replay it or execute one local search."""+ translated = replace(routed, request=plan.request)+ trace_event(+ stage="routing",+ event="free_claude_code.api.web_search.automatic_recognized",+ source="api",+ request_id=request_id,+ model=routed.resolved.original_model,+ )+ provider_stream = provider_executor.stream(+ translated,+ wire_api="messages",+ raw_log_label="FULL_PAYLOAD",+ raw_log_payload=plan.request.model_dump(),+ request_id=request_id,+ )+ chunks: list[str] = []+ try:+ chunks.extend([chunk async for chunk in provider_stream])+ finally:+ await close_stream_input(+ provider_stream,+ owner="automatic_web_search",+ source="api",+ preserved_error=sys.exception(),+ )++ message, stream_error = await aggregate_anthropic_sse_to_message(+ _iterate_chunks(chunks)+ )+ if stream_error is not None:+ raise _execution_failure_from_stream_error(stream_error)++ tool_calls = _tool_calls(message)+ if not tool_calls:+ trace_event(+ stage="execution",+ event="free_claude_code.api.web_search.automatic_declined",+ source="api",+ request_id=request_id,+ model=routed.resolved.original_model,+ )+ for chunk in chunks:+ yield chunk+ return+ if len(tool_calls) != 1:+ raise _protocol_failure(+ "Upstream model returned multiple tool calls for automatic WebSearch.",+ request_id=request_id,+ )++ call = tool_calls[0]+ if call.get("name") != HIDDEN_WEB_SEARCH_NAME:+ raise _protocol_failure(+ "Upstream model returned an unexpected tool for automatic WebSearch.",+ request_id=request_id,+ )+ arguments = call.get("input")+ if not isinstance(arguments, dict) or set(arguments) != {"query"}:+ raise _protocol_failure(+ "Upstream model returned malformed arguments for automatic WebSearch.",+ request_id=request_id,+ )+ raw_query = arguments.get("query")+ if not isinstance(raw_query, str) or not raw_query.strip():+ raise _protocol_failure(+ "Upstream model returned an empty query for automatic WebSearch.",+ request_id=request_id,+ )+ query = raw_query.strip()+ provider_usage = _provider_usage(message)+ input_tokens = _integer_field(provider_usage, "input_tokens")+ if input_tokens is None:+ input_tokens = fallback_input_tokens++ trace_event(+ stage="execution",+ event="free_claude_code.api.web_search.automatic_selected",+ source="api",+ request_id=request_id,+ model=routed.resolved.original_model,+ )+ async for frame in stream_selected_web_search_response(+ query,+ input_tokens=input_tokens,+ response_model=routed.resolved.original_model,+ provider_usage=provider_usage,+ result_filter=lambda results: _filter_results(results, plan.domains),+ verbose_client_errors=verbose_client_errors,+ ):+ yield frame+ trace_event(+ stage="execution",+ event="free_claude_code.api.web_search.automatic_completed",+ source="api",+ request_id=request_id,+ model=routed.resolved.original_model,+ )+++async def _iterate_chunks(chunks: list[str]) -> AsyncIterator[str]:+ for chunk in chunks:+ yield chunk+++def _tool_calls(message: Mapping[str, object]) -> list[dict[str, object]]:+ content = message.get("content")+ if not isinstance(content, list):+ return []+ calls: list[dict[str, object]] = []+ for block in content:+ if not isinstance(block, dict) or block.get("type") != "tool_use":+ continue+ calls.append({str(key): value for key, value in block.items()})+ return calls+++def _provider_usage(message: Mapping[str, object]) -> dict[str, object]:+ usage = message.get("usage")+ if not isinstance(usage, dict):+ return {}+ return {str(key): value for key, value in usage.items()}+++def _integer_field(values: Mapping[str, object], key: str) -> int | None:+ value = values.get(key)+ return value if isinstance(value, int) and not isinstance(value, bool) else None+++def _filter_results(+ results: list[dict[str, str]],+ domains: WebSearchDomainFilter,+) -> list[dict[str, str]]:+ if not domains.allowed and not domains.blocked:+ return results+ return [+ result+ for result in results+ if _hostname_is_allowed(result.get("url", ""), domains)+ ]+++def _hostname_is_allowed(url: str, domains: WebSearchDomainFilter) -> bool:+ hostname = urlsplit(url).hostname+ if hostname is None:+ return False+ try:+ normalized = hostname.encode("idna").decode("ascii").lower()+ except UnicodeError:+ return False+ if domains.allowed and not any(+ _is_hostname_or_subdomain(normalized, domain) for domain in domains.allowed+ ):+ return False+ return not any(+ _is_hostname_or_subdomain(normalized, domain) for domain in domains.blocked+ )+++def _is_hostname_or_subdomain(hostname: str, domain: str) -> bool:+ return hostname == domain or hostname.endswith(f".{domain}")+++def _execution_failure_from_stream_error(+ error: Mapping[str, object],+) -> ExecutionFailure:+ raw_type = error.get("type")+ error_type = raw_type if isinstance(raw_type, str) else "api_error"+ raw_message = error.get("message")+ message = (+ raw_message+ if isinstance(raw_message, str) and raw_message.strip()+ else "Provider request failed unexpectedly."+ )+ status = anthropic_status_for_error_type(error_type)+ kind = {+ 400: FailureKind.INVALID_REQUEST,+ 401: FailureKind.AUTHENTICATION,+ 402: FailureKind.PERMISSION,+ 403: FailureKind.PERMISSION,+ 404: FailureKind.INVALID_REQUEST,+ 413: FailureKind.INVALID_REQUEST,+ 429: FailureKind.RATE_LIMIT,+ 504: FailureKind.TIMEOUT,+ 529: FailureKind.OVERLOADED,+ }.get(status, FailureKind.UPSTREAM)+ return ExecutionFailure(+ kind=kind,+ status_code=status,+ message=message,+ retryable=False,+ )+++def _protocol_failure(message: str, *, request_id: str) -> ExecutionFailure:+ return ExecutionFailure(+ kind=FailureKind.UPSTREAM,+ status_code=500,+ message=f"{message}\n\nRequest ID: {request_id}",+ retryable=False,+ )diff --git a/src/free_claude_code/api/web_tools/request.py b/src/free_claude_code/api/web_tools/request.pyindex 7db4ad60..d961f56d 100644--- a/src/free_claude_code/api/web_tools/request.py+++ b/src/free_claude_code/api/web_tools/request.py@@ -1,12 +1,52 @@-"""Detect forced Anthropic web server tool requests."""+"""Recognize the narrow Anthropic web-tool requests FCC can execute locally."""+import re+from dataclasses import dataclass++from free_claude_code.application.errors import InvalidRequestErrorfrom free_claude_code.core.anthropic import MessagesRequest, Toolfrom .parsers import content_text+WEB_SEARCH_TYPE = "web_search_20250305"+WEB_FETCH_TYPE = "web_fetch_20250910"+HIDDEN_WEB_SEARCH_NAME = "fcc_web_search"++_SERVER_TOOL_TYPES = {+ "web_search": WEB_SEARCH_TYPE,+ "web_fetch": WEB_FETCH_TYPE,+}+_SERVER_TOOL_PREFIXES = ("web_search_", "web_fetch_")+_SERVER_HISTORY_TYPES = {+ "server_tool_use",+ "web_search_tool_result",+ "web_fetch_tool_result",+}+_WEB_SEARCH_OPTION_FIELDS = {"max_uses", "allowed_domains", "blocked_domains"}+_DOMAIN_PATTERN = re.compile(+ r"(?=.{1,253}\Z)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)*"+ r"[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?"+)+++@dataclass(frozen=True, slots=True)+class WebSearchDomainFilter:+ """Literal hostname constraints supplied by Claude Code."""++ allowed: tuple[str, ...] = ()+ blocked: tuple[str, ...] = ()+++@dataclass(frozen=True, slots=True)+class AutomaticWebSearchPlan:+ """One exact Claude Code automatic-search request translated for a provider."""++ request: MessagesRequest+ domains: WebSearchDomainFilter+def forced_tool_turn_text(request: MessagesRequest) -> str:- """Text for parsing forced server-tool inputs: latest user turn only (avoids stale history)."""+ """Text for parsing forced server-tool inputs: latest user turn only."""if not request.messages:return ""@@ -17,15 +57,18 @@ def forced_tool_turn_text(request: MessagesRequest) -> str:def forced_server_tool_name(request: MessagesRequest) -> str | None:- """Return web_search or web_fetch only when tool_choice forces that server tool."""- tc = request.tool_choice- if not isinstance(tc, dict):+ """Return a forced supported server tool, never an ordinary same-name function."""+ choice = request.tool_choice+ if not isinstance(choice, dict) or choice.get("type") != "tool":return None- if tc.get("type") != "tool":+ name = choice.get("name")+ if not isinstance(name, str) or name not in _SERVER_TOOL_TYPES:return None- name = tc.get("name")- if name in {"web_search", "web_fetch"}:- return str(name)+ expected_type = _SERVER_TOOL_TYPES[name]+ if any(+ tool.name == name and tool.type == expected_type for tool in request.tools or []+ ):+ return namereturn None@@ -34,43 +77,165 @@ def has_tool_named(request: MessagesRequest, name: str) -> bool:def is_web_server_tool_request(request: MessagesRequest) -> bool:- """True when the client forces a web server tool via tool_choice (not merely listed)."""- forced = forced_server_tool_name(request)- if forced is None:- return False- return has_tool_named(request, forced)+ """True only when the client forces one supported Anthropic server tool."""+ return forced_server_tool_name(request) is not Nonedef is_anthropic_server_tool_definition(tool: Tool) -> bool:- """Whether ``tool`` refers to an Anthropic server tool (web_search / web_fetch family)."""- name = (tool.name or "").strip()- if name in ("web_search", "web_fetch"):- return True- typ = tool.type- if isinstance(typ, str):- return typ.startswith("web_search") or typ.startswith("web_fetch")- return False+ """Whether ``tool.type`` identifies an Anthropic web server-tool family."""+ tool_type = tool.type+ return isinstance(tool_type, str) and tool_type.startswith(_SERVER_TOOL_PREFIXES)def has_listed_anthropic_server_tools(request: MessagesRequest) -> bool:- """True when tools include web_search / web_fetch-style entries (listed, forced or not)."""- return any(is_anthropic_server_tool_definition(t) for t in (request.tools or []))+ """True when tools include a typed Anthropic web server-tool definition."""+ return any(+ is_anthropic_server_tool_definition(tool) for tool in request.tools or []+ )+++def plan_automatic_web_search(+ request: MessagesRequest,+ *,+ web_tools_enabled: bool,+) -> AutomaticWebSearchPlan | None:+ """Translate only Claude Code's server-tool-only automatic WebSearch request."""+ choice = request.tool_choice+ if choice is not None and choice != {"type": "auto"}:+ return None++ tools = request.tools or []+ server_tools = [tool for tool in tools if is_anthropic_server_tool_definition(tool)]+ if not server_tools:+ return None+ if len(tools) != 1 or len(server_tools) != 1:+ return None++ tool = server_tools[0]+ if tool.type != WEB_SEARCH_TYPE:+ return None+ if not web_tools_enabled:+ raise InvalidRequestError(+ "Anthropic web_search is disabled (ENABLE_WEB_SERVER_TOOLS=false). "+ "Enable local web tools or remove web_search from the request."+ )+ if _has_server_tool_history(request):+ raise InvalidRequestError(+ "Automatic web_search does not accept prior Anthropic server-tool history."+ )+ if tool.name != "web_search":+ raise InvalidRequestError(+ f"Server tool type {WEB_SEARCH_TYPE!r} must use name 'web_search'."+ )+ if tool.description is not None or tool.input_schema is not None:+ raise InvalidRequestError(+ "Anthropic web_search must not define description or input_schema."+ )++ options = tool.model_extra or {}+ unsupported = sorted(set(options) - _WEB_SEARCH_OPTION_FIELDS)+ if unsupported:+ raise InvalidRequestError(+ "Anthropic web_search contains unsupported option(s): "+ + ", ".join(unsupported)+ + "."+ )+ _validate_max_uses(options.get("max_uses"))+ allowed = _parse_domains(+ options.get("allowed_domains"), field="web_search.allowed_domains"+ )+ blocked = _parse_domains(+ options.get("blocked_domains"), field="web_search.blocked_domains"+ )+ if allowed and blocked:+ raise InvalidRequestError(+ "web_search may define allowed_domains or blocked_domains, not both."+ )++ hidden_tool = Tool(+ name=HIDDEN_WEB_SEARCH_NAME,+ description="Search the public web for current information.",+ input_schema={+ "type": "object",+ "properties": {"query": {"type": "string"}},+ "required": ["query"],+ "additionalProperties": False,+ },+ )+ translated = request.model_copy(+ update={"tools": [hidden_tool]},+ deep=True,+ )+ return AutomaticWebSearchPlan(+ request=translated,+ domains=WebSearchDomainFilter(allowed=allowed, blocked=blocked),+ )def unsupported_server_tool_error(request: MessagesRequest, *, web_tools_enabled: bool) -> str | None:- """Return the user-facing error when the resolved provider cannot run server tools."""+ """Return the user-facing error for a server-tool shape FCC does not handle."""forced = forced_server_tool_name(request)if forced and not web_tools_enabled:return (- f"tool_choice forces Anthropic server tool {forced!r}, but local web server tools are "- "disabled (ENABLE_WEB_SERVER_TOOLS=false). Enable them or remove the forced server tool."+ f"tool_choice forces Anthropic server tool {forced!r}, but local web "+ "server tools are disabled (ENABLE_WEB_SERVER_TOOLS=false). Enable "+ "them or remove the forced server tool.")if not forced and has_listed_anthropic_server_tools(request):return (- "FCC cannot pass listed Anthropic server tools (web_search / web_fetch) "- "to OpenAI Chat upstreams. Set ENABLE_WEB_SERVER_TOOLS=true and force the "- "tool with tool_choice, or remove these tools from the request."+ "FCC supports automatic Anthropic web_search only for Claude Code's "+ f"{WEB_SEARCH_TYPE} server-tool-only request. Automatic web_fetch, "+ "mixed tools, and other server-tool choices are not supported.")return None+++def _has_server_tool_history(request: MessagesRequest) -> bool:+ for message in request.messages:+ if not isinstance(message.content, list):+ continue+ for block in message.content:+ if getattr(block, "type", None) in _SERVER_HISTORY_TYPES:+ return True+ return False+++def _validate_max_uses(value: object) -> None:+ if value is None:+ return+ if isinstance(value, bool) or not isinstance(value, int) or value <= 0:+ raise InvalidRequestError("web_search.max_uses must be a positive integer.")+++def _parse_domains(value: object, *, field: str) -> tuple[str, ...]:+ if value is None:+ return ()+ if not isinstance(value, list):+ raise InvalidRequestError(f"{field} must be a list of literal hostnames.")++ domains: list[str] = []+ for entry in value:+ if not isinstance(entry, str) or not entry or entry != entry.strip():+ raise InvalidRequestError(f"{field} entries must be non-empty hostnames.")+ if any(character in entry for character in ":/\\?#@*"):+ raise InvalidRequestError(+ f"{field} entry {entry!r} must be a literal hostname without a "+ "scheme, port, path, query, fragment, user info, or wildcard."+ )+ try:+ domain = entry.encode("idna").decode("ascii").lower()+ except UnicodeError as exc:+ raise InvalidRequestError(+ f"{field} entry {entry!r} is not a valid hostname."+ ) from exc+ if _DOMAIN_PATTERN.fullmatch(domain) is None:+ raise InvalidRequestError(+ f"{field} entry {entry!r} is not a valid hostname."+ )+ domains.append(domain)++ if len(domains) != len(set(domains)):+ raise InvalidRequestError(f"{field} must not contain duplicate hostnames.")+ return tuple(domains)diff --git a/src/free_claude_code/api/web_tools/streaming.py b/src/free_claude_code/api/web_tools/streaming.pyindex fb065ea4..fa1cc3bd 100644--- a/src/free_claude_code/api/web_tools/streaming.py+++ b/src/free_claude_code/api/web_tools/streaming.py@@ -1,7 +1,7 @@-"""SSE streaming for local web_search / web_fetch server tool results."""+"""SSE streaming for local web_search / web_fetch server-tool results."""import uuid-from collections.abc import AsyncIterator+from collections.abc import AsyncIterator, Callable, Mappingfrom datetime import UTC, datetimefrom free_claude_code.core.anthropic import MessagesRequest@@ -19,11 +19,12 @@ from . import outboundfrom .constants import _MAX_FETCH_CHARSfrom .egress import WebFetchEgressPolicyfrom .parsers import extract_query, extract_url-from .request import (- forced_server_tool_name,- forced_tool_turn_text,- has_tool_named,-)+from .request import forced_server_tool_name, forced_tool_turn_text, has_tool_named++type SearchResultFilter = Callable[+ [list[dict[str, str]]],+ list[dict[str, str]],+]def _search_summary(query: str, results: list[dict[str, str]]) -> str:@@ -43,36 +44,76 @@ async def stream_web_server_tool_response(response_model: str | None = None,verbose_client_errors: bool = False,) -> AsyncIterator[str]:- """Stream a minimal Anthropic-shaped turn for forced `web_search` / `web_fetch` (local fallback).-- When `ENABLE_WEB_SERVER_TOOLS` is on, this is a proxy-side execution path — not a full- hosted Anthropic citation or encrypted-content pipeline.- """+ """Stream the existing forced `web_search` / `web_fetch` local fallback."""tool_name = forced_server_tool_name(request)if tool_name is None or not has_tool_named(request, tool_name):returntext = forced_tool_turn_text(request)- message_id = f"msg_{uuid.uuid4()}"- tool_id = f"srvtoolu_{uuid.uuid4().hex}"- usage_key = (- "web_search_requests" if tool_name == "web_search" else "web_fetch_requests"- )tool_input = ({"query": extract_query(text)}if tool_name == "web_search"else {"url": extract_url(text)})- _result_block_for_tool = {+ async for frame in _stream_local_web_tool_response(+ tool_name=tool_name,+ tool_input=tool_input,+ input_tokens=input_tokens,+ web_fetch_egress=web_fetch_egress,+ response_model=request.model if response_model is None else response_model,+ verbose_client_errors=verbose_client_errors,+ ):+ yield frame+++async def stream_selected_web_search_response(+ query: str,+ *,+ input_tokens: int,+ response_model: str,+ provider_usage: Mapping[str, object],+ result_filter: SearchResultFilter,+ verbose_client_errors: bool = False,+) -> AsyncIterator[str]:+ """Stream the existing local result shape for one provider-selected query."""+ async for frame in _stream_local_web_tool_response(+ tool_name="web_search",+ tool_input={"query": query},+ input_tokens=input_tokens,+ web_fetch_egress=None,+ response_model=response_model,+ verbose_client_errors=verbose_client_errors,+ provider_usage=provider_usage,+ search_result_filter=result_filter,+ ):+ yield frame+++async def _stream_local_web_tool_response(+ *,+ tool_name: str,+ tool_input: dict[str, str],+ input_tokens: int,+ web_fetch_egress: WebFetchEgressPolicy | None,+ response_model: str,+ verbose_client_errors: bool,+ provider_usage: Mapping[str, object] | None = None,+ search_result_filter: SearchResultFilter | None = None,+) -> AsyncIterator[str]:+ message_id = f"msg_{uuid.uuid4()}"+ tool_id = f"srvtoolu_{uuid.uuid4().hex}"+ usage_key = (+ "web_search_requests" if tool_name == "web_search" else "web_fetch_requests"+ )+ result_block_for_tool = {"web_search": WEB_SEARCH_TOOL_RESULT,"web_fetch": WEB_FETCH_TOOL_RESULT,}- _error_payload_type_for_tool = {+ error_payload_type_for_tool = {"web_search": WEB_SEARCH_TOOL_RESULT_ERROR,"web_fetch": WEB_FETCH_TOOL_ERROR,}- wire_model = request.model if response_model is None else response_modelyield format_sse_event("message_start",{@@ -82,10 +123,10 @@ async def stream_web_server_tool_response("type": "message","role": "assistant","content": [],- "model": wire_model,+ "model": response_model,"stop_reason": None,"stop_sequence": None,- "usage": {"input_tokens": input_tokens, "output_tokens": 1},+ "usage": _message_start_usage(input_tokens, provider_usage),},},)@@ -108,8 +149,10 @@ async def stream_web_server_tool_response(try:if tool_name == "web_search":- query = str(tool_input["query"])+ query = tool_input["query"]results = await outbound._run_web_search(query)+ if search_result_filter is not None:+ results = search_result_filter(results)result_content: JsonValue = [{"type": "web_search_result",@@ -121,9 +164,9 @@ async def stream_web_server_tool_response(summary = _search_summary(query, results)result_block_type = WEB_SEARCH_TOOL_RESULTelse:- fetched = await outbound._run_web_fetch(- str(tool_input["url"]), web_fetch_egress- )+ if web_fetch_egress is None:+ raise RuntimeError("web_fetch requires an egress policy")+ fetched = await outbound._run_web_fetch(tool_input["url"], web_fetch_egress)result_content = {"type": "web_fetch_result","url": fetched["url"],@@ -142,19 +185,17 @@ async def stream_web_server_tool_response(summary = fetched["data"][:_MAX_FETCH_CHARS]result_block_type = WEB_FETCH_TOOL_RESULTexcept Exception as error:- fetch_url = str(tool_input["url"]) if tool_name == "web_fetch" else None+ fetch_url = tool_input.get("url") if tool_name == "web_fetch" else Noneoutbound._log_web_tool_failure(tool_name, error, fetch_url=fetch_url)- result_block_type = _result_block_for_tool[tool_name]+ result_block_type = result_block_for_tool[tool_name]result_content = {- "type": _error_payload_type_for_tool[tool_name],+ "type": error_payload_type_for_tool[tool_name],"error_code": "unavailable",}summary = outbound._web_tool_client_error_summary(tool_name, error, verbose=verbose_client_errors)- output_tokens = max(1, len(summary) // 4)-yield format_sse_event("content_block_start",{@@ -170,8 +211,6 @@ async def stream_web_server_tool_response(yield format_sse_event("content_block_stop", {"type": "content_block_stop", "index": 1})- # Model-facing summary: stream as normal text deltas (CLI/transcript code reads `text_delta`,- # not eager `text` on `content_block_start`).yield format_sse_event("content_block_start",{@@ -196,11 +235,52 @@ async def stream_web_server_tool_response({"type": "message_delta","delta": {"stop_reason": "end_turn", "stop_sequence": None},- "usage": {- "input_tokens": input_tokens,- "output_tokens": output_tokens,- "server_tool_use": {usage_key: 1},- },+ "usage": _completion_usage(+ input_tokens,+ summary,+ provider_usage,+ usage_key=usage_key,+ ),},)yield format_sse_event("message_stop", {"type": "message_stop"})+++def _message_start_usage(+ input_tokens: int,+ provider_usage: Mapping[str, object] | None,+) -> dict[str, object]:+ if provider_usage is None:+ return {"input_tokens": input_tokens, "output_tokens": 1}+ usage = _integer_usage(provider_usage)+ usage.setdefault("input_tokens", input_tokens)+ usage["output_tokens"] = 1+ return usage+++def _completion_usage(+ input_tokens: int,+ summary: str,+ provider_usage: Mapping[str, object] | None,+ *,+ usage_key: str,+) -> dict[str, object]:+ if provider_usage is None:+ usage: dict[str, object] = {+ "input_tokens": input_tokens,+ "output_tokens": max(1, len(summary) // 4),+ }+ else:+ usage = _integer_usage(provider_usage)+ usage.setdefault("input_tokens", input_tokens)+ usage.setdefault("output_tokens", max(1, len(summary) // 4))+ usage["server_tool_use"] = {usage_key: 1}+ return usage+++def _integer_usage(usage: Mapping[str, object]) -> dict[str, object]:+ return {+ key: value+ for key, value in usage.items()+ if isinstance(value, int) and not isinstance(value, bool)+ }diff --git a/src/free_claude_code/config/admin/manifest.py b/src/free_claude_code/config/admin/manifest.pyindex f7695838..c87c0a85 100644--- a/src/free_claude_code/config/admin/manifest.py+++ b/src/free_claude_code/config/admin/manifest.py@@ -434,6 +434,10 @@ _NON_PROVIDER_FIELDS: tuple[ConfigFieldSpec, ...] = ("web_tools","boolean",settings_attr="enable_web_server_tools",+ description=(+ "Let Claude Code use WebSearch through FCC and allow forced local web "+ "tools. Disable to prevent local web access."+ ),),ConfigFieldSpec("WEB_FETCH_ALLOWED_SCHEMES",diff --git a/src/free_claude_code/config/settings.py b/src/free_claude_code/config/settings.pyindex 7a8d7ad3..41a4382c 100644--- a/src/free_claude_code/config/settings.py+++ b/src/free_claude_code/config/settings.py@@ -582,9 +582,9 @@ class Settings(BaseModel):)# ==================== Local web server tools (web_search / web_fetch) ====================- # Off by default: these tools perform outbound HTTP from the proxy (SSRF risk).+ # On by default to match Claude Code's normal web-tool availability.enable_web_server_tools: bool = Field(- default=False, validation_alias="ENABLE_WEB_SERVER_TOOLS"+ default=True, validation_alias="ENABLE_WEB_SERVER_TOOLS")# Comma-separated URL schemes allowed for web_fetch (default: http,https).web_fetch_allowed_schemes: NonEmptyString = Field(diff --git a/tests/api/test_web_server_tools.py b/tests/api/test_web_server_tools.pyindex 8c0db6c6..d0dca6ff 100644--- a/tests/api/test_web_server_tools.py+++ b/tests/api/test_web_server_tools.py@@ -1,4 +1,6 @@+import asyncioimport json+from collections.abc import AsyncIteratorfrom typing import Anyfrom unittest.mock import AsyncMock, MagicMock, patch@@ -19,7 +21,12 @@ from free_claude_code.api.web_tools.outbound import (_read_response_body_capped,_run_web_fetch,)-from free_claude_code.api.web_tools.request import is_web_server_tool_request+from free_claude_code.api.web_tools.request import (+ HIDDEN_WEB_SEARCH_NAME,+ is_web_server_tool_request,+ plan_automatic_web_search,+ unsupported_server_tool_error,+)from free_claude_code.api.web_tools.streaming import stream_web_server_tool_responsefrom free_claude_code.application.errors import InvalidRequestErrorfrom free_claude_code.application.routing import (@@ -31,12 +38,19 @@ from free_claude_code.application.routing import (from free_claude_code.config.provider_catalog import PROVIDER_CATALOGfrom free_claude_code.config.reasoning import ReasoningPreferencefrom free_claude_code.config.settings import Settings-from free_claude_code.core.anthropic.models import Message, MessagesRequest, Tool+from free_claude_code.core.anthropic.models import (+ ContentBlockServerToolUse,+ Message,+ MessagesRequest,+ Tool,+)from free_claude_code.core.anthropic.stream_contracts import (assert_anthropic_stream_contract,parse_sse_text,text_content,)+from free_claude_code.core.anthropic.streaming import format_sse_event+from free_claude_code.core.failures import ExecutionFailure, FailureKindfrom free_claude_code.core.reasoning import ReasoningPolicyfrom free_claude_code.core.version import package_versionfrom free_claude_code.messaging.event_parser import parse_cli_event@@ -92,6 +106,228 @@ class FixedProviderModelRouter(ModelRouter):)+class ScriptedSelectionProvider:+ """One-stream provider double for the automatic WebSearch decision."""++ def __init__(+ self,+ events: list[str],+ *,+ failure: ExecutionFailure | None = None,+ failure_after_events: bool = False,+ wait_for: asyncio.Event | None = None,+ ) -> None:+ self.events = events+ self.failure = failure+ self.failure_after_events = failure_after_events+ self.wait_for = wait_for+ self.started = asyncio.Event()+ self.requests: list[MessagesRequest] = []+ self.stream_kwargs: list[dict[str, object]] = []+ self.close_count = 0++ def preflight_stream(+ self, request: MessagesRequest, *, reasoning: ReasoningPolicy+ ) -> None:+ return None++ async def stream_response(+ self,+ request: MessagesRequest,+ *,+ input_tokens: int,+ request_id: str,+ response_model: str,+ reasoning: ReasoningPolicy,+ ) -> AsyncIterator[str]:+ self.requests.append(request)+ self.stream_kwargs.append(+ {+ "input_tokens": input_tokens,+ "request_id": request_id,+ "response_model": response_model,+ "reasoning": reasoning,+ }+ )+ self.started.set()+ try:+ if self.wait_for is not None:+ await self.wait_for.wait()+ if self.failure is not None and not self.failure_after_events:+ raise self.failure+ for event in self.events:+ yield event+ if self.failure is not None:+ raise self.failure+ finally:+ self.close_count += 1+++def _provider_text_events(text: str) -> list[str]:+ return [+ format_sse_event(+ "message_start",+ {+ "type": "message_start",+ "message": {+ "id": "msg_provider",+ "type": "message",+ "role": "assistant",+ "content": [],+ "model": "gateway-model",+ "stop_reason": None,+ "stop_sequence": None,+ "usage": {"input_tokens": 11, "output_tokens": 1},+ },+ },+ ),+ format_sse_event(+ "content_block_start",+ {+ "type": "content_block_start",+ "index": 0,+ "content_block": {"type": "text", "text": ""},+ },+ ),+ format_sse_event(+ "content_block_delta",+ {+ "type": "content_block_delta",+ "index": 0,+ "delta": {"type": "text_delta", "text": text},+ },+ ),+ format_sse_event(+ "content_block_stop", {"type": "content_block_stop", "index": 0}+ ),+ format_sse_event(+ "message_delta",+ {+ "type": "message_delta",+ "delta": {"stop_reason": "end_turn", "stop_sequence": None},+ "usage": {"output_tokens": 3},+ },+ ),+ format_sse_event("message_stop", {"type": "message_stop"}),+ ]+++def _provider_tool_events(+ *,+ name: str = HIDDEN_WEB_SEARCH_NAME,+ arguments: dict[str, object] | None = None,+ additional_calls: int = 0,+) -> list[str]:+ calls = [(name, arguments if arguments is not None else {"query": "selected"})]+ calls.extend(+ (name, {"query": f"extra-{index}"}) for index in range(additional_calls)+ )+ events = [+ format_sse_event(+ "message_start",+ {+ "type": "message_start",+ "message": {+ "id": "msg_provider",+ "type": "message",+ "role": "assistant",+ "content": [],+ "model": "gateway-model",+ "stop_reason": None,+ "stop_sequence": None,+ "usage": {+ "input_tokens": 17,+ "output_tokens": 1,+ "cache_read_input_tokens": 5,+ },+ },+ },+ )+ ]+ for index, (tool_name, tool_input) in enumerate(calls):+ events.extend(+ [+ format_sse_event(+ "content_block_start",+ {+ "type": "content_block_start",+ "index": index,+ "content_block": {+ "type": "tool_use",+ "id": f"call_{index}",+ "name": tool_name,+ "input": {},+ },+ },+ ),+ format_sse_event(+ "content_block_delta",+ {+ "type": "content_block_delta",+ "index": index,+ "delta": {+ "type": "input_json_delta",+ "partial_json": json.dumps(tool_input),+ },+ },+ ),+ format_sse_event(+ "content_block_stop",+ {"type": "content_block_stop", "index": index},+ ),+ ]+ )+ events.extend(+ [+ format_sse_event(+ "message_delta",+ {+ "type": "message_delta",+ "delta": {"stop_reason": "tool_use", "stop_sequence": None},+ "usage": {"output_tokens": 9},+ },+ ),+ format_sse_event("message_stop", {"type": "message_stop"}),+ ]+ )+ return events+++def _automatic_search_request(+ *,+ stream: bool = True,+ tool: Tool | None = None,+ tool_choice: dict[str, Any] | None = None,+) -> MessagesRequest:+ return MessagesRequest(+ model="claude-haiku-4-5-20251001",+ max_tokens=100,+ stream=stream,+ messages=[+ Message(role="user", content="Prompt text must not become the query")+ ],+ tools=[tool or Tool(name="web_search", type="web_search_20250305")],+ tool_choice={"type": "auto"} if tool_choice is None else tool_choice,+ )+++def _automatic_search_service(+ provider: ScriptedSelectionProvider,+ *,+ settings: Settings | None = None,+) -> MessagesHandler:+ effective_settings = settings or Settings()+ return MessagesHandler(+ effective_settings,+ provider_resolver=lambda _: provider,+ model_router=FixedProviderModelRouter(+ effective_settings,+ _PROVIDER_IDS[0],+ provider_model="upstream-model",+ ),+ )++def test_web_server_tool_not_detected_when_tool_only_listed():"""Listing web_search without forcing it must not skip the upstream provider."""request = MessagesRequest(@@ -128,13 +364,181 @@ def test_web_server_tool_not_detected_when_forced_name_missing_from_tools():assert not is_web_server_tool_request(request)[email protected]("tool_choice", [None, {"type": "auto"}])+def test_plans_exact_automatic_web_search(tool_choice: dict[str, Any] | None) -> None:+ request = MessagesRequest(+ model="m",+ max_tokens=20,+ messages=[Message(role="user", content="search")],+ tools=[+ Tool(+ name="web_search",+ type="web_search_20250305",+ max_uses=8,+ allowed_domains=["Example.com"],+ )+ ],+ tool_choice=tool_choice,+ )++ plan = plan_automatic_web_search(request, web_tools_enabled=True)++ assert plan is not None+ assert plan.domains.allowed == ("example.com",)+ assert plan.domains.blocked == ()+ assert plan.request.tool_choice == tool_choice+ assert plan.request.tools is not None+ assert [tool.name for tool in plan.request.tools] == [HIDDEN_WEB_SEARCH_NAME]+ assert plan.request.tools[0].input_schema == {+ "type": "object",+ "properties": {"query": {"type": "string"}},+ "required": ["query"],+ "additionalProperties": False,+ }+ assert request.tools is not None+ assert request.tools[0].name == "web_search"+++def test_ordinary_function_named_web_search_remains_a_client_tool() -> None:+ request = MessagesRequest(+ model="m",+ max_tokens=20,+ messages=[Message(role="user", content="search")],+ tools=[+ Tool(+ name="web_search",+ description="ordinary client function",+ input_schema={"type": "object"},+ )+ ],+ tool_choice={"type": "tool", "name": "web_search"},+ )++ assert plan_automatic_web_search(request, web_tools_enabled=True) is None+ assert unsupported_server_tool_error(request, web_tools_enabled=True) is None+ assert not is_web_server_tool_request(request)+++ "tool",+ [+ Tool(name="web_fetch", type="web_fetch_20250910"),+ Tool(name="web_search", type="web_search_20260209"),+ Tool(name="WebSearch", input_schema={"type": "object"}),+ Tool(name="WebFetch", input_schema={"type": "object"}),+ ],+)+def test_does_not_plan_noncanonical_automatic_search(tool: Tool) -> None:+ request = _automatic_search_request(tool=tool)++ assert plan_automatic_web_search(request, web_tools_enabled=True) is None+++def test_does_not_plan_mixed_tools_or_extended_auto_choice() -> None:+ mixed = _automatic_search_request()+ mixed.tools = [+ Tool(name="web_search", type="web_search_20250305"),+ Tool(name="client_tool", input_schema={"type": "object"}),+ ]+ extended_choice = _automatic_search_request(+ tool_choice={"type": "auto", "disable_parallel_tool_use": True}+ )++ for request in (mixed, extended_choice):+ assert plan_automatic_web_search(request, web_tools_enabled=True) is None+ assert (+ unsupported_server_tool_error(request, web_tools_enabled=True) is not None+ )+++ ("tool", "message"),+ [+ (+ Tool(name="other", type="web_search_20250305"),+ "must use name 'web_search'",+ ),+ (+ Tool(+ name="web_search",+ type="web_search_20250305",+ description="custom",+ ),+ "must not define description",+ ),+ (+ Tool(name="web_search", type="web_search_20250305", max_uses=0),+ "must be a positive integer",+ ),+ (+ Tool(name="web_search", type="web_search_20250305", unknown="value"),+ "unsupported option",+ ),+ (+ Tool(+ name="web_search",+ type="web_search_20250305",+ allowed_domains=["example.com"],+ blocked_domains=["blocked.test"],+ ),+ "may define allowed_domains or blocked_domains",+ ),+ ],+)+def test_rejects_malformed_automatic_web_search_definition(+ tool: Tool, message: str+) -> None:+ with pytest.raises(InvalidRequestError, match=message):+ plan_automatic_web_search(+ _automatic_search_request(tool=tool), web_tools_enabled=True+ )+++def test_rejects_automatic_web_search_with_server_tool_history() -> None:+ request = _automatic_search_request()+ request.messages.insert(+ 0,+ Message(+ role="assistant",+ content=[+ ContentBlockServerToolUse(+ type="server_tool_use",+ id="srvtoolu_prior",+ name="web_search",+ input={"query": "prior"},+ )+ ],+ ),+ )++ with pytest.raises(InvalidRequestError, match="prior Anthropic server-tool"):+ plan_automatic_web_search(request, web_tools_enabled=True)+++ "domain",+ ["*.example.com", "example.com/path", "https://example.com", "example.com:443"],+)+def test_rejects_web_search_domain_wildcards_and_url_parts(domain: str) -> None:+ request = _automatic_search_request(+ tool=Tool(+ name="web_search",+ type="web_search_20250305",+ allowed_domains=[domain],+ )+ )++ with pytest.raises(InvalidRequestError, match="literal hostname"):+ plan_automatic_web_search(request, web_tools_enabled=True)++@pytest.mark.asyncio@pytest.mark.parametrize("provider_id", _PROVIDER_IDS)async def test_service_rejects_forced_server_tool_when_local_handler_is_disabled(provider_id: str,):"""Every provider needs FCC's local handler for forced server tools."""- settings = Settings()+ settings = Settings.model_validate({"ENABLE_WEB_SERVER_TOOLS": False})assert settings.enable_web_server_tools is Falseservice = MessagesHandler(settings,@@ -157,6 +561,278 @@ async def test_service_rejects_forced_server_tool_when_local_handler_is_disabledawait service.create(request)+async def test_automatic_web_search_replays_provider_response_when_declined(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ events = _provider_text_events("No search needed")+ provider = ScriptedSelectionProvider(events)+ search = AsyncMock()+ monkeypatch.setattr(+ "free_claude_code.api.web_tools.outbound._run_web_search", search+ )+ service = _automatic_search_service(provider)++ response = await service.create(+ _automatic_search_request(), request_id="req_automatic_declined"+ )++ assert isinstance(response, StreamingResponse)+ assert await _streaming_body_text(response) == "".join(events)+ search.assert_not_awaited()+ assert provider.close_count == 1+ assert len(provider.requests) == 1+ translated = provider.requests[0]+ assert translated.model == "upstream-model"+ assert translated.tool_choice == {"type": "auto"}+ assert translated.tools is not None+ assert [tool.name for tool in translated.tools] == [HIDDEN_WEB_SEARCH_NAME]+ assert provider.stream_kwargs == [+ {+ "input_tokens": provider.stream_kwargs[0]["input_tokens"],+ "request_id": "req_automatic_declined",+ "response_model": "claude-haiku-4-5-20251001",+ "reasoning": ReasoningPolicy.off(),+ }+ ]+++ ("domain_option", "domain"),+ [+ ("allowed_domains", "example.com"),+ ("blocked_domains", "unrelated.test"),+ ],+)+async def test_automatic_web_search_uses_model_query_and_filters_domains(+ domain_option: str,+ domain: str,+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ provider = ScriptedSelectionProvider(+ _provider_tool_events(arguments={"query": "model selected query"})+ )+ seen_queries: list[str] = []++ async def fake_search(query: str) -> list[dict[str, str]]:+ seen_queries.append(query)+ return [+ {"title": "Allowed", "url": "https://docs.example.com/page"},+ {"title": "Filtered", "url": "https://unrelated.test/page"},+ ]++ monkeypatch.setattr(+ "free_claude_code.api.web_tools.outbound._run_web_search", fake_search+ )+ service = _automatic_search_service(provider)+ request = _automatic_search_request(+ tool=Tool.model_validate(+ {+ "name": "web_search",+ "type": "web_search_20250305",+ "max_uses": 8,+ domain_option: [domain],+ }+ )+ )++ response = await service.create(request, request_id="req_automatic_selected")++ assert isinstance(response, StreamingResponse)+ raw = await _streaming_body_text(response)+ events = parse_sse_text(raw)+ assert_anthropic_stream_contract(events)+ assert seen_queries == ["model selected query"]+ assert HIDDEN_WEB_SEARCH_NAME not in raw+ assert "call_0" not in raw+ assert "Prompt text must not become the query" not in raw+ assert "docs.example.com/page" in raw+ assert "unrelated.test/page" not in raw+ assert sum(event.event == "message_start" for event in events) == 1+ assert sum(event.event == "message_stop" for event in events) == 1+ starts = [event for event in events if event.event == "content_block_start"]+ assert [start.data["content_block"]["type"] for start in starts] == [+ "server_tool_use",+ "web_search_tool_result",+ "text",+ ]+ assert starts[0].data["content_block"]["input"] == {"query": "model selected query"}+ assert (+ starts[1].data["content_block"]["tool_use_id"]+ == starts[0].data["content_block"]["id"]+ )+ message_start = next(+ event.data["message"] for event in events if event.event == "message_start"+ )+ assert message_start["model"] == "claude-haiku-4-5-20251001"+ final_usage = next(+ event.data["usage"] for event in events if event.event == "message_delta"+ )+ assert final_usage == {+ "input_tokens": 17,+ "output_tokens": 9,+ "cache_read_input_tokens": 5,+ "server_tool_use": {"web_search_requests": 1},+ }+ assert len(provider.requests) == 1+ assert provider.close_count == 1+++async def test_automatic_web_search_aggregates_when_stream_false(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ provider = ScriptedSelectionProvider(+ _provider_tool_events(arguments={"query": "json query"})+ )++ async def fake_search(_query: str) -> list[dict[str, str]]:+ return [{"title": "JSON result", "url": "https://example.com/json"}]++ monkeypatch.setattr(+ "free_claude_code.api.web_tools.outbound._run_web_search", fake_search+ )+ service = _automatic_search_service(provider)++ response = await service.create(+ _automatic_search_request(stream=False),+ request_id="req_automatic_json",+ )++ assert isinstance(response, JSONResponse)+ body = _json_body(response)+ assert [block["type"] for block in body["content"]] == [+ "server_tool_use",+ "web_search_tool_result",+ "text",+ ]+ assert body["content"][1]["content"][0]["url"] == "https://example.com/json"+ assert body["usage"]["server_tool_use"] == {"web_search_requests": 1}+ assert len(provider.requests) == 1+++ "events",+ [+ _provider_tool_events(arguments={"query": ""}),+ _provider_tool_events(name="unexpected_tool"),+ _provider_tool_events(additional_calls=1),+ ],+ ids=["blank-query", "wrong-tool", "multiple-tools"],+)+async def test_automatic_web_search_rejects_malformed_provider_selection(+ events: list[str],+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ provider = ScriptedSelectionProvider(events)+ search = AsyncMock()+ monkeypatch.setattr(+ "free_claude_code.api.web_tools.outbound._run_web_search", search+ )+ service = _automatic_search_service(provider)++ response = await service.create(+ _automatic_search_request(), request_id="req_malformed_selection"+ )++ assert isinstance(response, JSONResponse)+ assert response.status_code == 500+ assert response.headers["x-should-retry"] == "false"+ assert response.headers["content-type"].startswith("application/json")+ assert _json_body(response)["request_id"] == "req_malformed_selection"+ search.assert_not_awaited()+ assert provider.close_count == 1+++async def test_automatic_web_search_preserves_provider_failure_before_public_commit(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ provider = ScriptedSelectionProvider(+ [],+ failure=ExecutionFailure(+ kind=FailureKind.RATE_LIMIT,+ status_code=429,+ message="provider exhausted retries",+ retryable=False,+ ),+ )+ search = AsyncMock()+ monkeypatch.setattr(+ "free_claude_code.api.web_tools.outbound._run_web_search", search+ )+ service = _automatic_search_service(provider)++ response = await service.create(+ _automatic_search_request(), request_id="req_selection_failure"+ )++ assert isinstance(response, JSONResponse)+ assert response.status_code == 429+ assert response.headers["x-should-retry"] == "false"+ assert _json_body(response)["error"]["type"] == "rate_limit_error"+ search.assert_not_awaited()+ assert provider.close_count == 1+++async def test_automatic_web_search_converts_internal_post_start_failure_to_json(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ provider = ScriptedSelectionProvider(+ _provider_text_events("partial")[:2],+ failure=ExecutionFailure(+ kind=FailureKind.OVERLOADED,+ status_code=529,+ message="provider exhausted retries after starting",+ retryable=False,+ ),+ failure_after_events=True,+ )+ search = AsyncMock()+ monkeypatch.setattr(+ "free_claude_code.api.web_tools.outbound._run_web_search", search+ )+ service = _automatic_search_service(provider)++ response = await service.create(+ _automatic_search_request(), request_id="req_selection_post_start_failure"+ )++ assert isinstance(response, JSONResponse)+ assert response.status_code == 529+ assert response.headers["x-should-retry"] == "false"+ assert response.headers["content-type"].startswith("application/json")+ body = _json_body(response)+ assert body["error"]["type"] == "overloaded_error"+ assert body["request_id"] == "req_selection_post_start_failure"+ search.assert_not_awaited()+ assert provider.close_count == 1+++async def test_automatic_web_search_cancellation_closes_provider_stream() -> None:+ release = asyncio.Event()+ provider = ScriptedSelectionProvider(+ _provider_text_events("unused"), wait_for=release+ )+ service = _automatic_search_service(provider)+ task = asyncio.create_task(+ service.create(+ _automatic_search_request(), request_id="req_selection_cancelled"+ )+ )+ await provider.started.wait()++ task.cancel()++ with pytest.raises(asyncio.CancelledError):+ await task+ assert provider.close_count == 1++@pytest.mark.parametrize("url",[@@ -784,7 +1460,7 @@ async def test_drain_response_body_capped_stops_after_first_chunk_when_oversizedasync def test_service_rejects_listed_server_tools_for_every_provider(provider_id: str,) -> None:- settings = Settings()+ settings = Settings.model_validate({"ENABLE_WEB_SERVER_TOOLS": False})service = MessagesHandler(settings,provider_resolver=lambda _: MagicMock(),@@ -796,5 +1472,5 @@ async def test_service_rejects_listed_server_tools_for_every_provider(messages=[Message(role="user", content="q")],tools=[Tool(name="web_search", type="web_search_20250305")],)- with pytest.raises(InvalidRequestError, match="cannot pass listed Anthropic"):+ with pytest.raises(InvalidRequestError, match="ENABLE_WEB_SERVER_TOOLS=false"):await service.create(request)diff --git a/tests/config/test_config.py b/tests/config/test_config.pyindex 5bf6f24a..83022886 100644--- a/tests/config/test_config.py+++ b/tests/config/test_config.py@@ -40,7 +40,7 @@ def test_settings_defaults_are_valid_and_nonempty() -> None:assert settings.voice_note_enabled is Trueassert settings.whisper_device == "cpu"assert settings.whisper_model == "base"- assert settings.enable_web_server_tools is False+ assert settings.enable_web_server_tools is Trueassert settings.proxy_auth_enabled is Falseassert settings.proxy_auth_token == "freecc"assert [diff --git a/uv.lock b/uv.lockindex 1976ac7a..2d7fc7be 100644--- a/uv.lock+++ b/uv.lock@@ -607,7 +607,7 @@ wheels = [[[package]]name = "free-claude-code"-version = "5.8.0"+version = "5.8.1"source = { editable = "." }dependencies = [{ name = "aiohttp" },