deepseek-web-retrieval 0.7.0 → 0.9.0

package/docs/research/control-matrix.md

@@ -71,8 +71,9 @@ Reading notes:
 One section per host, in hosts.jsonc order. Each carries what an install needs beyond the
 matrix: the built-in competitors, their kill switches, how the MCP server is registered,
 and which rules files steer preference. The `init` CLI implements these tiers for
-OpenCode, Pi, and Codex (see [installer design](../design/installer-design.md)). Config
-paths imply the available scopes; keys locked to a single scope are enumerated in the
+OpenCode, Pi, Codex, and Claude Code (see
+[installer design](../design/installer-design.md)). Config paths imply the available
+scopes; keys locked to a single scope are enumerated in the
 [installer design](../design/installer-design.md#scope).
 
 ### Cline
@@ -209,15 +210,31 @@ paths imply the available scopes; keys locked to a single scope are enumerated i
 - **Built-in web tools** — `WebSearch` and `WebFetch`. Kill switch: bare deny rules —
   `"permissions": {"deny": ["WebSearch", "WebFetch"]}` — remove the tools from the model's
   context entirely; deny outranks allow at every settings level and cannot be carved out.
-  `--disallowedTools` is the flag form. `CLAUDE_CODE_DISABLE_WEB_FETCH=1` (2.1.285+) kills
-  WebFetch only; there is no env equivalent for WebSearch
+  Permission rules live in the settings file of each level: managed
+  `managed-settings.json` (Linux `/etc/claude-code/`, macOS
+  `/Library/Application Support/ClaudeCode/`, Windows
+  `C:\Program Files\ClaudeCode\` — the legacy `C:\ProgramData\ClaudeCode\` path
+  is not read) →
+  user `~/.claude/settings.json` → project `.claude/settings.json` → local
+  `.claude/settings.local.json`; the installer writes the chosen scope's settings file
+  and reports an existing managed layer. A bare `mcp__<server>` rule denies every tool
+  of one MCP server — the per-server kill switch the installer uses for web-capable
+  competitors under the forced tier. `--disallowedTools` is the flag form.
+  `CLAUDE_CODE_DISABLE_WEB_FETCH=1` (2.1.285+) kills WebFetch only; there is no env
+  equivalent for WebSearch
   ([tools](https://code.claude.com/docs/en/tools),
-  [permissions](https://code.claude.com/docs/en/permissions)).
-- **MCP registration** — `.mcp.json` (`mcpServers` with `command`/`args`/`env`, or
-  `type: "http"` + `url`); `${VAR}` expansion in `command`/`args`/`env`/`url`/`headers`.
-  Tool permission rules use `mcp__<server>__<tool>`. Tool descriptions are capped at 4,096
+  [permissions](https://code.claude.com/docs/en/permissions),
+  [settings](https://code.claude.com/docs/en/settings)).
+- **MCP registration** — three scopes across two files: project `.mcp.json` at the
+  project root (team-shared, first-use approval prompt per project), local scope under
+  the project's entry in `~/.claude.json` (private, the `claude mcp add` default), and
+  user scope at the top-level `mcpServers` key of `~/.claude.json` (`--scope user`).
+  Entries take `mcpServers` with `command`/`args`/`env`, or `type: "http"` + `url`;
+  `${VAR}` expansion in `command`/`args`/`env`/`url`/`headers`. Tool permission rules
+  use `mcp__<server>__<tool>`. Tool descriptions are capped at 4,096
   chars (2.1.296+) and tool output at 25k tokens by default (`MAX_MCP_OUTPUT_TOKENS`),
-  with oversized text saved to a file; 16 MiB message cap on HTTP transports.
+  with oversized text saved to a file; 16 MiB message cap on HTTP transports
+  ([MCP quickstart](https://code.claude.com/docs/en/mcp-quickstart)).
 - **Rules** — `CLAUDE.md` hierarchy (managed → user `~/.claude/CLAUDE.md` → project →
   `CLAUDE.local.md`) with `@import`; `AGENTS.md` is read instead only when no CLAUDE.md
   exists anywhere above the cwd (since 2.1.277)
@@ -303,3 +320,11 @@ paths imply the available scopes; keys locked to a single scope are enumerated i
   `toolPolicies`). Codex's docs location and Copilot's `GEMINI.md` dating were re-verified
   2026-10-21 and are settled in their sections above. Protocol-revision evidence for every
   host lives in [mcp-compatibility.md](mcp-compatibility.md).
+- **Claude Code forward-compat anchors (checked at the 2.1.303 lock):** the headless docs
+  pre-announce `--bare` becoming the default for `-p`, and bare mode never reads
+  `.mcp.json` — the billed e2e scenario and the project-scope install story both need
+  re-checking when that lands. `${VAR}` expansion in the `env` block of a user-scope
+  `~/.claude.json` entry is supported but only indirectly documented (the docs spell out
+  `.mcp.json` and `command`/`args`; the e2e's `hasCompletedOnboarding` flag and the
+  redundant `enableAllProjectMcpServers` belt-and-suspenders are undocumented), so a
+  baseline bump should re-verify all three against the then-current docs.

package/docs/research/mcp-compatibility.md

@@ -82,7 +82,7 @@ host facts; each row below was verified against that lock on the research baseli
 | Cline | `2024-11-05` | stdio, Streamable HTTP, SSE | Custom client (no official SDK); `protocolVersion "2024-11-05"` extracted from the platform binary; source repo not public |
 | Codex | `2025-06-18`; `mcp_2026_07_28` feature flag opts into `2026-07-28` | stdio, Streamable HTTP (no SSE) | Git tag `rust-v0.163.0`: rmcp 3.5.1 pinned; initialize sends `V_2025_06_18` |
 | Pi | `2025-11-25` | stdio, Streamable HTTP (SSE rejected) | Git tag: own `@earendil-works/pi-mcp` client, `LATEST_PROTOCOL_VERSION "2025-11-25"` |
-| Claude Code | `2026-07-28` by default (`MCP_PROTOCOL_NEGOTIATION=legacy` opt-out) | stdio, Streamable HTTP, SSE, ws | Changelog 2.1.296+: "negotiate MCP protocol version 2026-07-28 by default"; docs: TS SDK 2.0 runtime |
+| Claude Code | `2026-07-28` by default (`MCP_PROTOCOL_NEGOTIATION=legacy` opt-out) | stdio, Streamable HTTP, SSE, ws | Docs: the v2 runtime (TS SDK 2.0) defaults from 2.1.274+ without flag fetching and "asks stdio servers for that revision by default"; changelog 2.1.299 extended the default to cloud session and Remote Control connectors |
 | Cursor | Unpinnable from primary sources (docs show ≥ `2025-06-18` features) | stdio, Streamable HTTP, SSE | Docs feature set only; no revision stated in docs or changelog |
 | Devin | `2026-07-28` | stdio, Streamable HTTP (SSE fallback), SSE | Changelog for the locked release itself: "Support for MCP protocol revision 2026-07-28" |
 | GitHub Copilot | `2026-07-28` | stdio (`type: "local"`), Streamable HTTP, SSE | Changelog 1.0.81: "Ship MCP 2026-07-28 support to CLI, SDK, IDE, and in-memory clients" |
@@ -128,7 +128,7 @@ differences:
    Codex and Pi reject it anyway.
 3. **Build on the official SDK v2 dual-era serving.** One build then serves the full range:
    the `2024-11-05` floor set by Cline (v2 legacy support spans `2024-10-07`–`2025-11-25`)
-   up to the `2026-07-28` negotiators (Claude Code 2.1.296+, Devin 3000.11.92, Copilot CLI
+   up to the `2026-07-28` negotiators (Claude Code 2.1.274+, Devin 3000.11.92, Copilot CLI
    1.0.81+). A v1.x-built server still works today — modern clients fall back to the legacy
    handshake — but it can never offer the stateless era; v2 serves both from one entry
    point.

package/docs/research/ori-question-sourcing.md

@@ -170,6 +170,15 @@ tag (commit `843a6c5`); the `opencode-ai/opencode` repository's tags stop at `v0
   only heuristic correlation via the session hooks (which fire per model request with the
   sessionID, but no API contract binds a provider call to a session).
 
+  Post-baseline drift check (2026-10-24): the interface is unchanged at 2.1.4, the latest npm
+  release on that date (unpkg dist of `@opencode/schema`/`@opencode/plugin` 2.1.4:
+  `ProviderInput = Pick<Input, "query">`, provider context `{ signal }`). Upstream requests
+  filed the same day to widen this surface:
+  [anomalyco/opencode#58635](https://github.com/anomalyco/opencode/issues/58635) (session
+  linkage in the provider execute context) and
+  [#58636](https://github.com/anomalyco/opencode/issues/58636) (optional per-call `count`
+  passthrough) — re-check both when the baseline or the OpenCode lock bumps.
+
 Verdict: **tool path (`deepseek_fetch` / the `webfetch` override): A feasible (validated against
 the declared schema; raw JSON Schema forwarded verbatim) and B feasible
 (`ctx.session.context`). Websearch provider path (the search replacement this repo ships): neither
@@ -256,7 +265,9 @@ negotiated revision in the matrix.
   `ctx.session.context({ sessionID })` — user messages with their `text` — at call time, so
   channel B exists here without touching schemas. The `websearch` provider replacement — the path
   this repo uses for search — has neither channel at 2.0.32: its model-facing input schema is
-  fixed in host source to `query`, and its provider context is `{ signal }` only. Note also that
+  fixed in host source to `query`, and its provider context is `{ signal }` only (upstream
+  requests: [#58635](https://github.com/anomalyco/opencode/issues/58635),
+  [#58636](https://github.com/anomalyco/opencode/issues/58636)). Note also that
   `FETCH_INPUT` sets `additionalProperties: false`, which matters if a parameter is ever added on
   channel A: an undeclared field would be rejected by OpenCode's runtime validation with a
   retryable error.

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "deepseek-web-retrieval",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "Token-efficient DeepSeek Search and Fetch for coding agents, starting with OpenCode v2.",
   "type": "module",
   "license": "MIT",
@@ -57,7 +57,8 @@
     "prepublishOnly": "bun run check:release",
     "test": "bun test",
     "test:package": "node scripts/test-package.mjs",
-    "test:e2e:keyless": "bun run test:e2e pi pi-extension installer reinit upgrade pkg capability-off",
+    "test:e2e:keyless": "bun run test:e2e pi pi-extension pi-mock opencode-mock installer reinit upgrade pkg capability-off",
+    "test:e2e:billed": "bun run test:e2e pi-billed opencode codex claude-code preferred",
     "check:release": "bun run check && bun run test:package && bun run test:e2e:keyless",
     "test:e2e": "bun run test/e2e/run.ts",
     "docs:matrix": "bun run scripts/render-matrix.ts",

package/src/core/auth.ts

@@ -7,3 +7,10 @@ export function apiKeyFromEnv(env: Readonly<Record<string, string | undefined>>
   const key = env[API_KEY_ENV]?.trim();
   return key ? key : undefined;
 }
+
+/** Resolves the API key from the environment or fails with shared guidance. */
+export function requireApiKey(env: Readonly<Record<string, string | undefined>>): string {
+  const apiKey = apiKeyFromEnv(env);
+  if (!apiKey) throw new Error(MISSING_API_KEY_MESSAGE);
+  return apiKey;
+}

package/src/core/client.ts

@@ -1,7 +1,14 @@
-import { FETCH_ENDPOINT, MAX_ORI_QUESTION_CHARS, MAX_QUERY_CHARS, SEARCH_ENDPOINT } from "./constants";
+import {
+  DEFAULT_API_BASE_URL,
+  FETCH_ENDPOINT_PATH,
+  MAX_FETCH_CHARS,
+  MAX_ORI_QUESTION_CHARS,
+  MAX_QUERY_CHARS,
+  SEARCH_ENDPOINT_PATH,
+} from "./constants";
 import { assertFetchHostPolicy } from "./domains";
 import { formatFetchedContent, truncate } from "./format";
-import { buildQuery, processResults } from "./search";
+import { composeSearchQuery, processResults } from "./search";
 import { postJson } from "./transport";
 import type {
   DeepSeekSearchResult,
@@ -9,9 +16,10 @@ import type {
   FetchedPage,
   FetchOptions,
   RequestAuth,
+  ResolvedOptions,
   RetryOptions,
   SearchOptions,
-  SearchResult,
+  SearchOutcome,
 } from "./types";
 import { parseFetchUrl } from "./url";
 
@@ -22,6 +30,24 @@ function effectiveTimeout(configuredMs: number, perCallMs: number | undefined):
   return perCallMs === undefined ? configuredMs : Math.min(configuredMs, perCallMs);
 }
 
+/**
+ * The per-call budget wins outright, unlike timeouts: a model that just saw a
+ * truncation marker is asking for more than the default on purpose, so the
+ * configured value stays the default rather than a ceiling.
+ */
+function effectiveMaxChars(configured: number, perCall: number | undefined): number {
+  if (perCall === undefined || !Number.isFinite(perCall)) return configured;
+  return Math.min(MAX_FETCH_CHARS, Math.max(0, Math.trunc(perCall)));
+}
+
+/**
+ * Composes a request endpoint from the resolved base URL (already
+ * slash-stripped by resolveBaseUrl; absent means the production default).
+ */
+function apiUrl(baseUrl: string | undefined, path: string): string {
+  return `${baseUrl ?? DEFAULT_API_BASE_URL}${path}`;
+}
+
 /**
  * The wire value for ori_question: absent/whitespace-only means "not
  * provided"; longer values are clamped rather than rejected — the field is
@@ -49,6 +75,14 @@ export interface RequestOptions {
   readonly retry: RetryOptions;
   /** Per-call cap in milliseconds; the shorter of this and the configured timeout wins. */
   readonly timeoutMs?: number;
+  /** Per-call fetch budget in characters; overrides the configured cap for this call. */
+  readonly maxChars?: number;
+  /**
+   * The resolved API root; adapters pass `config.baseUrl` so every request
+   * follows the `baseUrl` knob. Absent falls back to the production default
+   * (unit tests composing requests by hand rely on that).
+   */
+  readonly baseUrl?: string;
 }
 
 export interface SearchRequest extends RequestOptions {
@@ -60,31 +94,46 @@ export interface SearchRequest extends RequestOptions {
   readonly oriQuestion?: string;
 }
 
-export async function searchWeb(
-  query: string,
-  options: SearchOptions,
-  request: SearchRequest,
-): Promise<SearchResult[]> {
+/**
+ * The per-request context every adapter assembles from the resolved config:
+ * bound auth, retry policy, and base URL, plus any per-call overrides a
+ * tool input supplied.
+ */
+export function requestContext(
+  config: Pick<ResolvedOptions, "retry" | "baseUrl">,
+  apiKey: string,
+  signal: AbortSignal,
+  perCall?: { readonly timeoutMs?: number; readonly maxChars?: number },
+): RequestOptions {
+  return {
+    signal,
+    auth: { apiKey },
+    retry: config.retry,
+    baseUrl: config.baseUrl,
+    ...(perCall?.timeoutMs === undefined ? {} : { timeoutMs: perCall.timeoutMs }),
+    ...(perCall?.maxChars === undefined ? {} : { maxChars: perCall.maxChars }),
+  };
+}
+
+export async function searchWeb(query: string, options: SearchOptions, request: SearchRequest): Promise<SearchOutcome> {
   const trimmed = query.trim();
   if (!trimmed) throw new Error("DeepSeek search query must not be empty");
-  if (Array.from(trimmed).length > MAX_QUERY_CHARS) {
-    throw new Error(`DeepSeek search query must be ${MAX_QUERY_CHARS} characters or fewer`);
-  }
-
-  const builtQuery = buildQuery(trimmed, options);
-  const builtQueryLength = Array.from(builtQuery).length;
-  if (builtQueryLength > MAX_QUERY_CHARS) {
+  const trimmedLength = Array.from(trimmed).length;
+  if (trimmedLength > MAX_QUERY_CHARS) {
+    // The query rides in the message so the model can see what to shorten.
     throw new Error(
-      `DeepSeek search query must be ${MAX_QUERY_CHARS} characters or fewer after applying ` +
-        `blockedDomains, includeDomains, and language ` +
-        `(built query is ${builtQueryLength} characters)`,
+      `DeepSeek search query must be ${MAX_QUERY_CHARS} characters or fewer ` +
+        `(got ${trimmedLength}: ${JSON.stringify(truncate(trimmed, 64))})`,
     );
   }
 
+  const composed = composeSearchQuery(trimmed, options);
+  const builtQuery = composed.query;
+
   const timeout = effectiveTimeout(options.timeoutMs, request.timeoutMs);
   const oriQuestion = oriQuestionValue(request.oriQuestion);
   const payload = await postJson<SearchResponse>(
-    SEARCH_ENDPOINT,
+    apiUrl(request.baseUrl, SEARCH_ENDPOINT_PATH),
     {
       query: builtQuery,
       count: options.count,
@@ -99,7 +148,13 @@ export async function searchWeb(
   if (!Array.isArray(payload.results)) {
     throw new Error("DeepSeek Search returned a response without a results array");
   }
-  return processResults(payload.results as DeepSeekSearchResult[], options);
+  const results = processResults(payload.results as DeepSeekSearchResult[], options);
+  return {
+    results,
+    inputQuery: trimmed,
+    effectiveQuery: builtQuery,
+    notes: composed.notes,
+  };
 }
 
 export async function fetchPage(url: URL, options: FetchOptions, request: RequestOptions): Promise<FetchedPage> {
@@ -108,10 +163,15 @@ export async function fetchPage(url: URL, options: FetchOptions, request: Reques
   const target = parseFetchUrl(url.href);
   assertFetchHostPolicy(target, options);
   const timeout = effectiveTimeout(options.timeoutMs, request.timeoutMs);
-  const payload = await postJson<FetchResponse>(FETCH_ENDPOINT, { url: target.href }, "DeepSeek Fetch", {
-    ...request,
-    timeoutMs: timeout,
-  });
+  const payload = await postJson<FetchResponse>(
+    apiUrl(request.baseUrl, FETCH_ENDPOINT_PATH),
+    { url: target.href },
+    "DeepSeek Fetch",
+    {
+      ...request,
+      timeoutMs: timeout,
+    },
+  );
   const title = typeof payload.title === "string" ? payload.title.trim() : "";
   const content = typeof payload.content === "string" ? payload.content : "";
   if (!content.trim()) {
@@ -138,7 +198,11 @@ export async function fetchDocument(
 ): Promise<FetchedDocument> {
   if (typeof url !== "string" && !(url instanceof URL)) throw new Error('"url" must be a string or URL');
   const page = await fetchPage(url instanceof URL ? url : parseFetchUrl(url), options, request);
-  const formatted = formatFetchedContent(page.title, page.content, options.maxChars);
+  const formatted = formatFetchedContent(
+    page.title,
+    page.content,
+    effectiveMaxChars(options.maxChars, request.maxChars),
+  );
   return {
     url: page.url,
     title: page.title,

package/src/core/config-summary.ts

@@ -27,6 +27,7 @@ const VOCABULARY = [
   { key: "fetchBlockPrivateHosts", read: (o: ResolvedOptions) => o.fetch.blockPrivateHosts },
   { key: "maxRetries", read: (o: ResolvedOptions) => o.retry.maxRetries },
   { key: "retryBaseDelayMs", read: (o: ResolvedOptions) => o.retry.baseDelayMs },
+  { key: "baseUrl", read: (o: ResolvedOptions) => o.baseUrl },
 ] as const;
 
 /** The config keys in vocabulary order; the shared config file accepts exactly these. */

package/src/core/constants.ts

@@ -1,5 +1,15 @@
-export const SEARCH_ENDPOINT = "https://api.deepseek.com/v1/tools/search";
-export const FETCH_ENDPOINT = "https://api.deepseek.com/v1/tools/fetch";
+/**
+ * The DeepSeek API root every request is composed from. `baseUrl` overrides it
+ * (env `DEEPSEEK_BASE_URL`, shared-file key `baseUrl`) so proxies, enterprise
+ * gateways, and mock upstreams can intercept retrieval without touching the
+ * adapters; the two endpoints below stay the production default.
+ */
+export const DEFAULT_API_BASE_URL = "https://api.deepseek.com";
+export const SEARCH_ENDPOINT_PATH = "/v1/tools/search";
+export const FETCH_ENDPOINT_PATH = "/v1/tools/fetch";
+
+export const SEARCH_ENDPOINT = `${DEFAULT_API_BASE_URL}${SEARCH_ENDPOINT_PATH}`;
+export const FETCH_ENDPOINT = `${DEFAULT_API_BASE_URL}${FETCH_ENDPOINT_PATH}`;
 
 /**
  * Search defaults are benchmarked against surveyed AI-native search APIs and
@@ -19,6 +29,10 @@ export const DEFAULT_MIN_AUTHORITY = 0;
 export const DEFAULT_MAX_SUMMARY_CHARS = 1200;
 
 export const DEFAULT_FETCH_MAX_CHARS = 16000;
+/** The ceiling for a per-call fetch budget, matching the configured knob's range. */
+export const MAX_FETCH_CHARS = 1_000_000;
+/** The API's documented count range top; per-call counts share it. */
+export const MAX_SEARCH_COUNT = 50;
 export const DEFAULT_TIMEOUT_MS = 30000;
 export const MIN_TIMEOUT_MS = 1000;
 export const MAX_TIMEOUT_MS = 120000;
@@ -45,6 +59,7 @@ export const MAX_RETRY_DELAY_MS = 10000;
 
 /** The single source for every DEEPSEEK_* environment variable name. */
 export const API_KEY_ENV = "DEEPSEEK_API_KEY";
+export const BASE_URL_ENV = "DEEPSEEK_BASE_URL";
 export const ENABLE_SEARCH_ENV = "DEEPSEEK_ENABLE_SEARCH";
 export const ENABLE_FETCH_ENV = "DEEPSEEK_ENABLE_FETCH";
 export const SEARCH_LOCALIZATION_ENV = "DEEPSEEK_SEARCH_LOCALIZATION";

package/src/core/descriptions.ts

@@ -6,7 +6,8 @@
 export const FETCH_SERVICE_LIMITS =
   "DeepSeek does not render JavaScript and cannot reach private networks; PDFs, images, and other binary files are unsupported.";
 
-export const FETCH_OUTPUT_TRUNCATED = "Output is truncated to the configured size.";
+export const FETCH_OUTPUT_TRUNCATED =
+  "Output is truncated to the configured size; the optional maxChars parameter raises or lowers that size for one call.";
 
 export const FETCH_MARKDOWN_ONLY = 'Only format "markdown" is supported.';
 
@@ -45,3 +46,11 @@ export const SEARCH_ORI_QUESTION_PARAMETER =
   "reformulated query. Optional; 1-128 characters, and longer values are truncated.";
 
 export const FETCH_URL_PARAMETER = "Absolute http:// or https:// URL to fetch. Credentials are rejected.";
+
+export const FETCH_MAX_CHARS_PARAMETER =
+  "Optional per-call character budget for this fetch, 0-1,000,000, title included. Overrides the configured cap " +
+  "for this call; a [content truncated] marker is appended when the output is cut.";
+
+export const SEARCH_COUNT_PARAMETER =
+  "Optional number of results for this call, 1-50. Overrides the configured count and result cap for this call; " +
+  "billing is per request, not per result.";

package/src/core/env.ts

@@ -1,4 +1,4 @@
-import { API_KEY_ENV, ENABLE_FETCH_ENV, ENABLE_SEARCH_ENV, SEARCH_LOCALIZATION_ENV } from "./constants";
+import { API_KEY_ENV, BASE_URL_ENV, ENABLE_FETCH_ENV, ENABLE_SEARCH_ENV, SEARCH_LOCALIZATION_ENV } from "./constants";
 import { normalizeDomain } from "./domains";
 import { resolvePluginOptions } from "./options";
 import type { PluginOptions, ResolvedOptions } from "./types";
@@ -23,6 +23,7 @@ const NUMBER_ENV = {
 const TEXT_ENV = {
   language: "DEEPSEEK_SEARCH_LANGUAGE",
   searchLocalization: SEARCH_LOCALIZATION_ENV,
+  baseUrl: BASE_URL_ENV,
 } as const;
 
 const DOMAINS_ENV = {
@@ -40,18 +41,21 @@ const FALSE_ONLY_ENV = {
   fetchEnabled: ENABLE_FETCH_ENV,
 } as const;
 
+/** Every option key mapped onto its `DEEPSEEK_*` variable — the inverse view of the maps above. */
+export const OPTION_ENV_BY_KEY: Readonly<Record<string, string>> = {
+  ...NUMBER_ENV,
+  ...TEXT_ENV,
+  ...DOMAINS_ENV,
+  ...FALSE_ONLY_ENV,
+};
+
 /**
  * Every option's `DEEPSEEK_*` variable name, in map order — the names a host that
  * isolates its children from the parent environment (Codex) must forward for
  * shell-set options to reach the server. `DEEPSEEK_API_KEY` is deliberately
  * absent: it is not an option variable, and installers compose it separately.
  */
-export const OPTION_ENV_VARS: readonly string[] = [
-  ...Object.values(NUMBER_ENV),
-  ...Object.values(TEXT_ENV),
-  ...Object.values(DOMAINS_ENV),
-  ...Object.values(FALSE_ONLY_ENV),
-];
+export const OPTION_ENV_VARS: readonly string[] = Object.values(OPTION_ENV_BY_KEY);
 
 /**
  * Maps `DEEPSEEK_*` environment variables onto the shared plugin option keys and
@@ -104,6 +108,7 @@ export function envOptionsReport(env: Env = process.env): EnvOptionsReport {
 
   putNumber(options, "maxRetries", env, warnings);
   putNumber(options, "retryBaseDelayMs", env, warnings);
+  putText(options, "baseUrl", env);
 
   const known = new Set(OPTION_ENV_VARS);
   for (const key of Object.keys(env)) {

package/src/core/format.ts

@@ -85,14 +85,34 @@ export function formatTimeoutError(operation: string, timeoutMs: number): string
   return `${operation} timed out after ${timeoutMs} ms`;
 }
 
+/**
+ * The query context shown to the model above the results: emitted only when
+ * the effective query differs from what the model sent (operators applied or
+ * degradation happened), so an unfiltered search adds no header noise.
+ */
+export interface SearchQueryContext {
+  readonly inputQuery: string;
+  readonly effectiveQuery: string;
+  readonly notes: readonly string[];
+}
+
+function searchHeader(context: SearchQueryContext | undefined): string | undefined {
+  if (!context) return undefined;
+  if (context.effectiveQuery === context.inputQuery && context.notes.length === 0) return undefined;
+  const header = `Searched for: ${context.effectiveQuery}`;
+  return context.notes.length > 0 ? `${header} — ${context.notes.join("; ")}` : header;
+}
+
 /**
  * Renders processed search results as Markdown for a text content block.
  * Hosts that ignore structured output read this text.
  */
-export function formatSearchResults(results: readonly SearchResult[]): string {
-  if (results.length === 0) return "No results found.";
-
-  return results
+export function formatSearchResults(results: readonly SearchResult[], context?: SearchQueryContext): string {
+  const header = searchHeader(context);
+  if (results.length === 0) {
+    return header ? `${header}\n\nNo results found.` : "No results found.";
+  }
+  const body = results
     .map((result, index) => {
       const title = result.title?.trim() || result.url;
       const marker = formatQualityMarker(result);
@@ -106,6 +126,7 @@ export function formatSearchResults(results: readonly SearchResult[]): string {
       return lines.join("\n");
     })
     .join("\n\n");
+  return header ? `${header}\n\n${body}` : body;
 }
 
 /**

package/src/core/options.ts

@@ -1,5 +1,6 @@
 import { isIP } from "node:net";
 import {
+  DEFAULT_API_BASE_URL,
   DEFAULT_API_KEY_SOURCE,
   DEFAULT_FETCH_MAX_CHARS,
   DEFAULT_MAX_RESULTS,
@@ -12,6 +13,7 @@ import {
   DEFAULT_TIMEOUT_MS,
   MAX_RETRIES,
   MAX_RETRY_DELAY_MS,
+  MAX_SEARCH_COUNT,
   MAX_TIMEOUT_MS,
   MIN_TIMEOUT_MS,
 } from "./constants";
@@ -32,9 +34,22 @@ export function resolvePluginOptions(input?: PluginOptions): ResolvedOptions {
     fetch: resolveFetchOptions(input),
     auth: resolveAuthOptions(input),
     retry: resolveRetryOptions(input),
+    baseUrl: resolveBaseUrl(input?.baseUrl),
   };
 }
 
+/**
+ * The both-disabled refusal both server surfaces share: undefined when a tool
+ * stays enabled, otherwise one message naming why both are off.
+ */
+export function bothDisabledPrecheck(
+  config: Pick<ResolvedOptions, "search" | "fetch">,
+  reason: string,
+): string | undefined {
+  if (config.search.enabled || config.fetch.enabled) return undefined;
+  return `Both tools are disabled (${reason}); at least one must stay enabled.`;
+}
+
 export function resolveSearchOptions(input?: PluginOptions): SearchOptions {
   const count = clampInt(input?.count, DEFAULT_SEARCH_COUNT, 1, 50);
   return {
@@ -82,6 +97,38 @@ export function resolveRetryOptions(input?: PluginOptions): RetryOptions {
   };
 }
 
+/**
+ * Constraint: only an http(s) URL with no fragment survives, trailing slashes
+ * stripped so endpoint composition never doubles them. Anything else — a bare
+ * hostname, a non-http scheme, an empty string — drops to the production
+ * default, the same drop-and-default contract as every other invalid knob.
+ */
+export function resolveBaseUrl(value: unknown): string {
+  if (typeof value !== "string") return DEFAULT_API_BASE_URL;
+  const trimmed = value.trim();
+  if (!trimmed) return DEFAULT_API_BASE_URL;
+  let parsed: URL;
+  try {
+    parsed = new URL(trimmed);
+  } catch {
+    return DEFAULT_API_BASE_URL;
+  }
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") return DEFAULT_API_BASE_URL;
+  return trimmed.replace(/\/+$/, "");
+}
+
+/**
+ * Applies a per-call result count to resolved search options. The count the
+ * model asked for is what it wants to see, so it sets both the request count
+ * and the post-filter cap for that call; the configured knobs stay the
+ * default, not a ceiling.
+ */
+export function withPerCallCount(options: SearchOptions, count: number | undefined): SearchOptions {
+  if (count === undefined || !Number.isFinite(count)) return options;
+  const clamped = Math.min(MAX_SEARCH_COUNT, Math.max(1, Math.trunc(count)));
+  return { ...options, count: clamped, maxResults: clamped };
+}
+
 /**
  * Resolves the per-call timeout from the plugin cap and the built-in tool's
  * `timeout` field (seconds). The shorter limit wins.