Skip to content

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.example
index fd46e625..afdaf61f 100644
--- a/.env.example
+++ b/.env.example
@@ -380,8 +380,8 @@ ENABLE_SUGGESTION_MODE_SKIP=true
ENABLE_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=true
WEB_FETCH_ALLOWED_SCHEMES=http,https
WEB_FETCH_ALLOW_PRIVATE_NETWORKS=false
diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
index 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 rejec
the request as lossy. This policy belongs to the Claude Messages boundary, never
to 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 Claude
diff --git a/pyproject.toml b/pyproject.toml
index 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.md
index 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=short
free 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.py
index 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.py
index 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.py
index 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: Path
diff --git a/src/free_claude_code/api/handlers/messages.py b/src/free_claude_code/api/handlers/messages.py
index 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.py
new file mode 100644
index 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.py
index 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 InvalidRequestError
from free_claude_code.core.anthropic import MessagesRequest, Tool
from .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 name
return 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 None
def 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.py
index 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, Mapping
from datetime import UTC, datetime
from free_claude_code.core.anthropic import MessagesRequest
@@ -19,11 +19,12 @@ from . import outbound
from .constants import _MAX_FETCH_CHARS
from .egress import WebFetchEgressPolicy
from .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):
return
text = 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_model
yield 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_RESULT
else:
- 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_RESULT
except 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 None
outbound._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.py
index 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.py
index 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.py
index 8c0db6c6..d0dca6ff 100644
--- a/tests/api/test_web_server_tools.py
+++ b/tests/api/test_web_server_tools.py
@@ -1,4 +1,6 @@
+import asyncio
import json
+from collections.abc import AsyncIterator
from typing import Any
from 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_response
from free_claude_code.application.errors import InvalidRequestError
from 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_CATALOG
from free_claude_code.config.reasoning import ReasoningPreference
from 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, FailureKind
from free_claude_code.core.reasoning import ReasoningPolicy
from free_claude_code.core.version import package_version
from 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 False
service = MessagesHandler(
settings,
@@ -157,6 +561,278 @@ async def test_service_rejects_forced_server_tool_when_local_handler_is_disabled
await 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_oversized
async 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.py
index 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 True
assert settings.whisper_device == "cpu"
assert settings.whisper_model == "base"
- assert settings.enable_web_server_tools is False
+ assert settings.enable_web_server_tools is True
assert settings.proxy_auth_enabled is False
assert settings.proxy_auth_token == "freecc"
assert [
diff --git a/uv.lock b/uv.lock
index 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" },